## Process this file with automake to produce Makefile.in
ACLOCAL_AMFLAGS=-I m4 ${ACLOCAL_FLAGS}
-SUBDIRS = cmake help tests
+SUBDIRS = buildsystems/autotools buildsystems/cmake help tests
bin_SCRIPTS = \
gtkdoc-check \
gtkdoc-mkpdf \
gtkdoc-rebase \
gtkdoc-scan \
- gtkdoc-scangobj \
- gtkdocize
+ gtkdoc-scangobj
gtkdocdatadir = $(datadir)/gtk-doc/data
gtkdocdata_DATA = \
version-greater-or-equal.xsl \
devhelp2.xsd \
devhelp2.xsl \
- gtk-doc.make \
- gtk-doc.flat.make \
style/home.png \
style/left.png \
style/left-insensitive.png \
pkgconfigdir = $(datadir)/pkgconfig
pkgconfig_DATA = gtk-doc.pc
-aclocaldir = $(datadir)/aclocal
-aclocal_DATA = gtk-doc.m4
-
-gtk-doc.flat.make: gtk-doc.make
- @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@
-
EXTRA_DIST = \
MAINTAINERS \
$(gtkdocdata_DATA) \
$(pylibdata_DATA) \
gtk-doc.pc.in \
- gtk-doc.m4 \
gtk-doc.doap \
gtk-doc-fo.xsl \
doc/README \
COPYING-DOCS
CLEANFILES = \
- gtk-doc.flat.make \
gtkdoc-checkc \
gtkdoc-depscanc \
gtkdoc-fixxrefc \
CONFIG_CLEAN_FILES = gtk-doc.pc gtkdoc/config.py gtkdoc-check \
gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml \
gtkdoc-mkhtml2 gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase \
- gtkdoc-scan gtkdoc-scangobj gtkdocize
+ gtkdoc-scan gtkdoc-scangobj
CONFIG_CLEAN_VPATH_FILES =
am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
am__vpath_adj = case $$p in \
|| { echo " ( cd '$$dir' && rm -f" $$files ")"; \
$(am__cd) "$$dir" && rm -f $$files; }; \
}
-am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" \
- "$(DESTDIR)$(gtkdocdatadir)" "$(DESTDIR)$(pkgconfigdir)" \
- "$(DESTDIR)$(pylibdatadir)"
+am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(gtkdocdatadir)" \
+ "$(DESTDIR)$(pkgconfigdir)" "$(DESTDIR)$(pylibdatadir)"
SCRIPTS = $(bin_SCRIPTS)
AM_V_P = $(am__v_P_@AM_V@)
am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
n|no|NO) false;; \
*) (install-info --version) >/dev/null 2>&1;; \
esac
-DATA = $(aclocal_DATA) $(gtkdocdata_DATA) $(pkgconfig_DATA) \
- $(pylibdata_DATA)
+DATA = $(gtkdocdata_DATA) $(pkgconfig_DATA) $(pylibdata_DATA)
RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \
distclean-recursive maintainer-clean-recursive
am__recursive_targets = \
$(srcdir)/gtkdoc-mkhtml.in $(srcdir)/gtkdoc-mkhtml2.in \
$(srcdir)/gtkdoc-mkman.in $(srcdir)/gtkdoc-mkpdf.in \
$(srcdir)/gtkdoc-rebase.in $(srcdir)/gtkdoc-scan.in \
- $(srcdir)/gtkdoc-scangobj.in $(srcdir)/gtkdocize.in \
- $(top_srcdir)/build-aux/compile \
+ $(srcdir)/gtkdoc-scangobj.in $(top_srcdir)/build-aux/compile \
$(top_srcdir)/build-aux/config.guess \
$(top_srcdir)/build-aux/config.sub \
$(top_srcdir)/build-aux/install-sh \
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
-SUBDIRS = cmake help tests
+SUBDIRS = buildsystems/autotools buildsystems/cmake help tests
bin_SCRIPTS = \
gtkdoc-check \
gtkdoc-depscan \
gtkdoc-mkpdf \
gtkdoc-rebase \
gtkdoc-scan \
- gtkdoc-scangobj \
- gtkdocize
+ gtkdoc-scangobj
gtkdocdatadir = $(datadir)/gtk-doc/data
gtkdocdata_DATA = \
version-greater-or-equal.xsl \
devhelp2.xsd \
devhelp2.xsl \
- gtk-doc.make \
- gtk-doc.flat.make \
style/home.png \
style/left.png \
style/left-insensitive.png \
pkgconfigdir = $(datadir)/pkgconfig
pkgconfig_DATA = gtk-doc.pc
-aclocaldir = $(datadir)/aclocal
-aclocal_DATA = gtk-doc.m4
EXTRA_DIST = \
MAINTAINERS \
$(gtkdocdata_DATA) \
$(pylibdata_DATA) \
gtk-doc.pc.in \
- gtk-doc.m4 \
gtk-doc.doap \
gtk-doc-fo.xsl \
doc/README \
COPYING-DOCS
CLEANFILES = \
- gtk-doc.flat.make \
gtkdoc-checkc \
gtkdoc-depscanc \
gtkdoc-fixxrefc \
cd $(top_builddir) && $(SHELL) ./config.status $@
gtkdoc-scangobj: $(top_builddir)/config.status $(srcdir)/gtkdoc-scangobj.in
cd $(top_builddir) && $(SHELL) ./config.status $@
-gtkdocize: $(top_builddir)/config.status $(srcdir)/gtkdocize.in
- cd $(top_builddir) && $(SHELL) ./config.status $@
install-binSCRIPTS: $(bin_SCRIPTS)
@$(NORMAL_INSTALL)
@list='$(bin_SCRIPTS)'; test -n "$(bindir)" || list=; \
distclean-libtool:
-rm -f libtool config.lt
-install-aclocalDATA: $(aclocal_DATA)
- @$(NORMAL_INSTALL)
- @list='$(aclocal_DATA)'; test -n "$(aclocaldir)" || list=; \
- if test -n "$$list"; then \
- echo " $(MKDIR_P) '$(DESTDIR)$(aclocaldir)'"; \
- $(MKDIR_P) "$(DESTDIR)$(aclocaldir)" || exit 1; \
- fi; \
- for p in $$list; do \
- if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
- echo "$$d$$p"; \
- done | $(am__base_list) | \
- while read files; do \
- echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(aclocaldir)'"; \
- $(INSTALL_DATA) $$files "$(DESTDIR)$(aclocaldir)" || exit $$?; \
- done
-
-uninstall-aclocalDATA:
- @$(NORMAL_UNINSTALL)
- @list='$(aclocal_DATA)'; test -n "$(aclocaldir)" || list=; \
- files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \
- dir='$(DESTDIR)$(aclocaldir)'; $(am__uninstall_files_from_dir)
install-gtkdocdataDATA: $(gtkdocdata_DATA)
@$(NORMAL_INSTALL)
@list='$(gtkdocdata_DATA)'; test -n "$(gtkdocdatadir)" || list=; \
all-am: Makefile $(SCRIPTS) $(DATA)
installdirs: installdirs-recursive
installdirs-am:
- for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" "$(DESTDIR)$(gtkdocdatadir)" "$(DESTDIR)$(pkgconfigdir)" "$(DESTDIR)$(pylibdatadir)"; do \
+ for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(gtkdocdatadir)" "$(DESTDIR)$(pkgconfigdir)" "$(DESTDIR)$(pylibdatadir)"; do \
test -z "$$dir" || $(MKDIR_P) "$$dir"; \
done
install: install-recursive
info-am:
-install-data-am: install-aclocalDATA install-gtkdocdataDATA \
- install-pkgconfigDATA install-pylibdataDATA
+install-data-am: install-gtkdocdataDATA install-pkgconfigDATA \
+ install-pylibdataDATA
install-dvi: install-dvi-recursive
ps-am:
-uninstall-am: uninstall-aclocalDATA uninstall-binSCRIPTS \
- uninstall-gtkdocdataDATA uninstall-pkgconfigDATA \
- uninstall-pylibdataDATA
+uninstall-am: uninstall-binSCRIPTS uninstall-gtkdocdataDATA \
+ uninstall-pkgconfigDATA uninstall-pylibdataDATA
.MAKE: $(am__recursive_targets) install-am install-strip
dist-tarZ dist-xz dist-zip distcheck distclean \
distclean-generic distclean-libtool distclean-tags \
distcleancheck distdir distuninstallcheck dvi dvi-am html \
- html-am info info-am install install-aclocalDATA install-am \
- install-binSCRIPTS install-data install-data-am install-dvi \
- install-dvi-am install-exec install-exec-am \
- install-gtkdocdataDATA install-html install-html-am \
- install-info install-info-am install-man install-pdf \
- install-pdf-am install-pkgconfigDATA install-ps install-ps-am \
- install-pylibdataDATA install-strip installcheck \
- installcheck-am installcheck-binSCRIPTS installdirs \
- installdirs-am maintainer-clean maintainer-clean-generic \
- mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \
- ps ps-am tags tags-am uninstall uninstall-aclocalDATA \
+ html-am info info-am install install-am install-binSCRIPTS \
+ install-data install-data-am install-dvi install-dvi-am \
+ install-exec install-exec-am install-gtkdocdataDATA \
+ install-html install-html-am install-info install-info-am \
+ install-man install-pdf install-pdf-am install-pkgconfigDATA \
+ install-ps install-ps-am install-pylibdataDATA install-strip \
+ installcheck installcheck-am installcheck-binSCRIPTS \
+ installdirs installdirs-am maintainer-clean \
+ maintainer-clean-generic mostlyclean mostlyclean-generic \
+ mostlyclean-libtool pdf pdf-am ps ps-am tags tags-am uninstall \
uninstall-am uninstall-binSCRIPTS uninstall-gtkdocdataDATA \
uninstall-pkgconfigDATA uninstall-pylibdataDATA
.PRECIOUS: Makefile
-gtk-doc.flat.make: gtk-doc.make
- @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@
-
-include $(top_srcdir)/git.mk
dist-hook:
+GTK-Doc 1.29 (Aug 28 2018)
+===============
+
+GTK-Doc now requires python-3.X. It does not requires python-six anymore.
+
+Note that this is a nonmaintainer release and that tests are known to be broken.
+
+ Changes
+
+ o 674163 : – html-build.stamp rule broken for out-of-tree builds with absolute paths
+ o 795744 : Too much escaped string - " & lt;child > " in description of " GtkOverlay as GtkBuildable " section
+ o 796011 : Crash in ScanDirectory caused by overlooked use of renamed `dir` variable
+ o 796012 : Several places in rebase.py incorrectly use `match.groups(1)` instead of `match.group(1)`, one causes a crash
+
+ Contributors
+
+ Adam Williamson
+ Anders Jonsson
+ Daniel Mustieles
+ David D
+ LRN
+ Marek Cernocky
+ Martin Blanchard
+ Michael Biebl
+ Michael Catanzaro
+ Rafael Fontenelle
+ Sebastian Geiger
+ Stefan Sauer
+ Tim Sabsch
+
+
GTK-Doc 1.28 (Mar 24 2018)
==============
libxslt & libxml2 >= 2.3.6.
http://xmlsoft.org/
-
Most distributions now have packages for all of these, so I would strongly
advise that you grab those.
See the documentation in the help/manual directory for more information. You can
read it e.g. with yelp file://$PWD/help/manual/C/gtk-doc-manual.xml
+
+
+Building
+========
+
+We are supporting two build systems to build gtk-doc for some transitions time.
+
+
+Build using auto*
+-----------------
+
+In order to build with a the classic auto* system use these commands:
+
+Build from git:
+./autogen.sh; make
+
+Build from dist tarball:
+./configure; make
+
+There are a few parameters one can pass to ./configure, run ./configure --help
+to see them. Also ./autogen.sh can take those settings (and will hand them
+through to ./configure).
+
+To run the tests:
+make check
+
+To install:
+make install
+
+To make a release:
+make distcheck
+or
+make dist
+
+
+Build using meson
+-----------------
+
+Support for meson is new and still experiemntal.
+
+Build it from git:
+meson build .
+ninja -C build
+
+There are some options one can specify too:
+meson build . --prefix=
+meson build . -Dautotools_support=false
+meson build . -Dcmake_support=false
+meson build . -Dyelp_manual=false
+
+To run tests:
+ninja -C build test
+
+To install:
+ninja -C build install
+
+To make a release:
+ninja -C build dist
* would be good to be able to have page titles as a concatenation of document
name and page name (gtk+:GtkWIdget)
* formats
- http://bugzilla.gnome.org/show_bug.cgi?id=531572 : html-single
http://bugzilla.gnome.org/show_bug.cgi?id=466535 : pdf
http://bugzilla.gnome.org/show_bug.cgi?id=467488 : man
we need more configure options in gtk-doc.m4:
- --(enable|disable)-gtk-doc-(html|pdf|man|html-single|rtf)
+ --(enable|disable)-gtk-doc-(html|pdf|man)
- html : enabled by default
- - html-single : is single page html
* validation
xmllint --noout --xinclude --postvalid tester-docs.xml
xmllint --noout --postvalid tester-docs.fo --dtdvalid file://$HOME/download/fo.dtd
- fo.dtd : http://www.renderx.com/Tests/validator/fo.zip
-* single page
- xsltproc --nonet --xinclude -o gtk-docs.html /home/ensonic/projects/gtk-doc/gtk-doc-single.xsl gtk-docs.sgml
- * need to check if we can pass the style-sheet class as a parameter (--stringparam gtkdoc.stylesheet=(chunk|docbook))
- * we might also need to reflow some things, as gtk-doc.xsl also runs the devhelp/devhelp2 generation
- - but then the urls in the devhelp file, refer to the chunked html anyway
-
= Warnings =
Bugzilla has some requests for extra warnings. We should support a common
0m33.282s 0m29.266s 0m4.012s
- removing the gentext calls for nav-bar alt tags does not help
-
- - try plain docbook xslt to see if maybe we have bad xslt templates in the
- customisation layer (gtk-doc.xsl)
-
- we could do the xinlcude processing once and use it for both html and pdf
time /usr/bin/xsltproc 2>../xslt4.log --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --xinclude --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ../tester-docs.xml
real user sys
- unfortunately there is no way to ask xsltproc to pre-transform an xslt, that could
- strip comments
- process xsl:import and xsl:include
- - compile xslt
- http://sourceforge.net/projects/xsltc/
- http://www.xmlhack.com/read.php?item=618
- extra xsltproc options:
--novalid: saves ~ 0.12 sec
-
+
+ - strip DOCTYPES on xincludes
+ - there is a performance bottleneck in libxml, where it parses DTD for each fragment
+ - we're using the dtd to
+ - validate fragments
+ - inject package name/version etc.
+ - 1) we could provide a flags to gtkdoc-mkdb to not put any doctype on
+ generated file and manually result entities in generated files (and
+ expand_content_files)
+ - to get a list of entities:
+ - we could parse entities from the main doc-file header
+ - tricky as with xml/gtkdocentities.ent, they are in a extra file
+ - we could pass entities as args for gtkdoc-mkdb
+ - if the flag is used, we should warn if entities are in the header
+ - 2) if the doctype on the main doc, does not conatin entities, skip adding
+ the doctype to generated output
+ - 3) if the doctype on the main doc contains entities, only add the doctype
+ if the generated content contains entities ([&%][_a-zA-Z]*;)
+ - a quick check on the gnome modules showed:
+ - quite a few don't use entities
+ - those that use version.xml
+ - seem to mostly use it in the main doc
+ - but a few use it for man pages
+ find . -name "*.xml" -exec grep -Hn "&version;" {} \; | grep -v "\-docs.xml"
+
+find . -name "*.xml" -exec egrep --color -Hn '&[_a-zA-Z]*;' {} \; | egrep -v '&(amp|lt|gt|quot|apos|nbsp);' | egrep --color '&[_a-zA-Z]*;'
+find . -name "*.xml" -exec egrep -o '&[_a-zA-Z]*;' {} \; | sort | uniq -c | sort -n
= python =
- consider swithcing to this markdown parser
If you have problems, you may need to regenerate the build system entirely.
To do so, use the procedure documented by the package, typically 'autoreconf'.])])
-dnl pkg.m4 - Macros to locate and utilise pkg-config. -*- Autoconf -*-
-dnl serial 11 (pkg-config-0.29)
-dnl
+# pkg.m4 - Macros to locate and utilise pkg-config. -*- Autoconf -*-
+# serial 11 (pkg-config-0.29.1)
+
dnl Copyright © 2004 Scott James Remnant <scott@netsplit.com>.
dnl Copyright © 2012-2015 Dan Nicholson <dbn.lists@gmail.com>
dnl
dnl See the "Since" comment for each macro you use to see what version
dnl of the macros you require.
m4_defun([PKG_PREREQ],
-[m4_define([PKG_MACROS_VERSION], [0.29])
+[m4_define([PKG_MACROS_VERSION], [0.29.1])
m4_if(m4_version_compare(PKG_MACROS_VERSION, [$1]), -1,
[m4_fatal([pkg.m4 version $1 or higher is required but ]PKG_MACROS_VERSION[ found])])
])dnl PKG_PREREQ
AS_VAR_IF([$1], [""], [$5], [$4])dnl
])dnl PKG_CHECK_VAR
+dnl PKG_WITH_MODULES(VARIABLE-PREFIX, MODULES,
+dnl [ACTION-IF-FOUND],[ACTION-IF-NOT-FOUND],
+dnl [DESCRIPTION], [DEFAULT])
+dnl ------------------------------------------
+dnl
+dnl Prepare a "--with-" configure option using the lowercase
+dnl [VARIABLE-PREFIX] name, merging the behaviour of AC_ARG_WITH and
+dnl PKG_CHECK_MODULES in a single macro.
+AC_DEFUN([PKG_WITH_MODULES],
+[
+m4_pushdef([with_arg], m4_tolower([$1]))
+
+m4_pushdef([description],
+ [m4_default([$5], [build with ]with_arg[ support])])
+
+m4_pushdef([def_arg], [m4_default([$6], [auto])])
+m4_pushdef([def_action_if_found], [AS_TR_SH([with_]with_arg)=yes])
+m4_pushdef([def_action_if_not_found], [AS_TR_SH([with_]with_arg)=no])
+
+m4_case(def_arg,
+ [yes],[m4_pushdef([with_without], [--without-]with_arg)],
+ [m4_pushdef([with_without],[--with-]with_arg)])
+
+AC_ARG_WITH(with_arg,
+ AS_HELP_STRING(with_without, description[ @<:@default=]def_arg[@:>@]),,
+ [AS_TR_SH([with_]with_arg)=def_arg])
+
+AS_CASE([$AS_TR_SH([with_]with_arg)],
+ [yes],[PKG_CHECK_MODULES([$1],[$2],$3,$4)],
+ [auto],[PKG_CHECK_MODULES([$1],[$2],
+ [m4_n([def_action_if_found]) $3],
+ [m4_n([def_action_if_not_found]) $4])])
+
+m4_popdef([with_arg])
+m4_popdef([description])
+m4_popdef([def_arg])
+
+])dnl PKG_WITH_MODULES
+
+dnl PKG_HAVE_WITH_MODULES(VARIABLE-PREFIX, MODULES,
+dnl [DESCRIPTION], [DEFAULT])
+dnl -----------------------------------------------
+dnl
+dnl Convenience macro to trigger AM_CONDITIONAL after PKG_WITH_MODULES
+dnl check._[VARIABLE-PREFIX] is exported as make variable.
+AC_DEFUN([PKG_HAVE_WITH_MODULES],
+[
+PKG_WITH_MODULES([$1],[$2],,,[$3],[$4])
+
+AM_CONDITIONAL([HAVE_][$1],
+ [test "$AS_TR_SH([with_]m4_tolower([$1]))" = "yes"])
+])dnl PKG_HAVE_WITH_MODULES
+
+dnl PKG_HAVE_DEFINE_WITH_MODULES(VARIABLE-PREFIX, MODULES,
+dnl [DESCRIPTION], [DEFAULT])
+dnl ------------------------------------------------------
+dnl
+dnl Convenience macro to run AM_CONDITIONAL and AC_DEFINE after
+dnl PKG_WITH_MODULES check. HAVE_[VARIABLE-PREFIX] is exported as make
+dnl and preprocessor variable.
+AC_DEFUN([PKG_HAVE_DEFINE_WITH_MODULES],
+[
+PKG_HAVE_WITH_MODULES([$1],[$2],[$3],[$4])
+
+AS_IF([test "$AS_TR_SH([with_]m4_tolower([$1]))" = "yes"],
+ [AC_DEFINE([HAVE_][$1], 1, [Enable ]m4_tolower([$1])[ support])])
+])dnl PKG_HAVE_DEFINE_WITH_MODULES
+
AC_DEFUN([YELP_HELP_INIT],
[
AC_REQUIRE([AC_PROG_LN_S])
xmlpath="$$lc:$(srcdir)/$$lc"; \
fi; \
for page in $(HELP_FILES); do \
- echo "$(XMLLINT) --noout --noent --path $$xmlpath --xinclude $$d$$lc/$$page"; \
- $(XMLLINT) --noout --noent --path "$$xmlpath" --xinclude "$$d$$lc/$$page"; \
+ echo "$(XMLLINT) --nonet --noout --noent --path $$xmlpath --xinclude $$d$$lc/$$page"; \
+ $(XMLLINT) --nonet --noout --noent --path "$$xmlpath" --xinclude "$$d$$lc/$$page"; \
done; \
done
dnl supported. (2.0 was released on October 16, 2000).
dnl FIXME: Remove the need to hard-code Python versions here.
m4_define_default([_AM_PYTHON_INTERPRETER_LIST],
-[python python2 python3 python3.8 python3.7 python3.6 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 dnl
+[python python2 python3 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 dnl
python2.6 python2.5 python2.4 python2.3 python2.2 python2.1 python2.0])
AC_ARG_VAR([PYTHON], [the Python interpreter])
-#! /bin/sh
+#!/bin/sh
# Wrapper for compilers which do not understand '-c -o'.
-scriptversion=2012-10-14.11; # UTC
+scriptversion=2016-01-11.22; # UTC
-# Copyright (C) 1999-2014 Free Software Foundation, Inc.
+# Copyright (C) 1999-2017 Free Software Foundation, Inc.
# Written by Tom Tromey <tromey@cygnus.com>.
#
# This program is free software; you can redistribute it and/or modify
echo "compile $scriptversion"
exit $?
;;
- cl | *[/\\]cl | cl.exe | *[/\\]cl.exe )
+ cl | *[/\\]cl | cl.exe | *[/\\]cl.exe | \
+ icl | *[/\\]icl | icl.exe | *[/\\]icl.exe )
func_cl_wrapper "$@" # Doesn't return...
;;
esac
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-time-zone: "UTC"
+# time-stamp-time-zone: "UTC0"
# time-stamp-end: "; # UTC"
# End:
-#! /bin/sh
+#!/bin/sh
# Attempt to guess a canonical system name.
-# Copyright 1992-2016 Free Software Foundation, Inc.
+# Copyright 1992-2017 Free Software Foundation, Inc.
-timestamp='2016-10-02'
+timestamp='2017-08-08'
# This file is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
GNU config.guess ($timestamp)
Originally written by Per Bothner.
-Copyright 1992-2016 Free Software Foundation, Inc.
+Copyright 1992-2017 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE."
*:Sortix:*:*)
echo ${UNAME_MACHINE}-unknown-sortix
exit ;;
+ *:Redox:*:*)
+ echo ${UNAME_MACHINE}-unknown-redox
+ exit ;;
alpha:OSF1:*:*)
case $UNAME_RELEASE in
*4.0)
UNAME_PROCESSOR=`/usr/bin/uname -p`
case ${UNAME_PROCESSOR} in
amd64)
- echo x86_64-unknown-freebsd`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'` ;;
- *)
- echo ${UNAME_PROCESSOR}-unknown-freebsd`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'` ;;
+ UNAME_PROCESSOR=x86_64 ;;
+ i386)
+ UNAME_PROCESSOR=i586 ;;
esac
+ echo ${UNAME_PROCESSOR}-unknown-freebsd`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'`
exit ;;
i*:CYGWIN*:*)
echo ${UNAME_MACHINE}-pc-cygwin
if test `echo "$UNAME_RELEASE" | sed -e 's/\..*//'` -le 10 ; then
if [ "$CC_FOR_BUILD" != no_compiler_found ]; then
if (echo '#ifdef __LP64__'; echo IS_64BIT_ARCH; echo '#endif') | \
- (CCOPTS="" $CC_FOR_BUILD -E - 2>/dev/null) | \
- grep IS_64BIT_ARCH >/dev/null
+ (CCOPTS="" $CC_FOR_BUILD -E - 2>/dev/null) | \
+ grep IS_64BIT_ARCH >/dev/null
then
case $UNAME_PROCESSOR in
i386) UNAME_PROCESSOR=x86_64 ;;
powerpc) UNAME_PROCESSOR=powerpc64 ;;
esac
fi
+ # On 10.4-10.6 one might compile for PowerPC via gcc -arch ppc
+ if (echo '#ifdef __POWERPC__'; echo IS_PPC; echo '#endif') | \
+ (CCOPTS="" $CC_FOR_BUILD -E - 2>/dev/null) | \
+ grep IS_PPC >/dev/null
+ then
+ UNAME_PROCESSOR=powerpc
+ fi
fi
elif test "$UNAME_PROCESSOR" = i386 ; then
# Avoid executing cc on OS X 10.9, as it ships with a stub
*:QNX:*:4*)
echo i386-pc-qnx
exit ;;
- NEO-?:NONSTOP_KERNEL:*:*)
+ NEO-*:NONSTOP_KERNEL:*:*)
echo neo-tandem-nsk${UNAME_RELEASE}
exit ;;
NSE-*:NONSTOP_KERNEL:*:*)
echo nse-tandem-nsk${UNAME_RELEASE}
exit ;;
- NSR-?:NONSTOP_KERNEL:*:*)
+ NSR-*:NONSTOP_KERNEL:*:*)
echo nsr-tandem-nsk${UNAME_RELEASE}
exit ;;
+ NSX-*:NONSTOP_KERNEL:*:*)
+ echo nsx-tandem-nsk${UNAME_RELEASE}
+ exit ;;
*:NonStop-UX:*:*)
echo mips-compaq-nonstopux
exit ;;
$0: unable to guess system type
This script (version $timestamp), has failed to recognize the
-operating system you are using. If your script is old, overwrite
-config.guess and config.sub with the latest versions from:
+operating system you are using. If your script is old, overwrite *all*
+copies of config.guess and config.sub with the latest versions from:
http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess
and
-#! /bin/sh
+#!/bin/sh
# Configuration validation subroutine script.
-# Copyright 1992-2016 Free Software Foundation, Inc.
+# Copyright 1992-2017 Free Software Foundation, Inc.
-timestamp='2016-11-04'
+timestamp='2017-04-02'
# This file is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
version="\
GNU config.sub ($timestamp)
-Copyright 1992-2016 Free Software Foundation, Inc.
+Copyright 1992-2017 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE."
| fido | fr30 | frv | ft32 \
| h8300 | h8500 | hppa | hppa1.[01] | hppa2.0 | hppa2.0[nw] | hppa64 \
| hexagon \
- | i370 | i860 | i960 | ia64 \
+ | i370 | i860 | i960 | ia16 | ia64 \
| ip2k | iq2000 \
| k1om \
| le32 | le64 \
| ubicom32 \
| v850 | v850e | v850e1 | v850e2 | v850es | v850e2v3 \
| visium \
+ | wasm32 \
| we32k \
| x86 | xc16x | xstormy16 | xtensa \
| z8k | z80)
| h8300-* | h8500-* \
| hppa-* | hppa1.[01]-* | hppa2.0-* | hppa2.0[nw]-* | hppa64-* \
| hexagon-* \
- | i*86-* | i860-* | i960-* | ia64-* \
+ | i*86-* | i860-* | i960-* | ia16-* | ia64-* \
| ip2k-* | iq2000-* \
| k1om-* \
| le32-* | le64-* \
| v850-* | v850e-* | v850e1-* | v850es-* | v850e2-* | v850e2v3-* \
| vax-* \
| visium-* \
+ | wasm32-* \
| we32k-* \
| x86-* | x86_64-* | xc16x-* | xps100-* \
| xstormy16-* | xtensa*-* \
nsr-tandem)
basic_machine=nsr-tandem
;;
+ nsx-tandem)
+ basic_machine=nsx-tandem
+ ;;
op50n-* | op60c-*)
basic_machine=hppa1.1-oki
os=-proelf
;;
ppc64) basic_machine=powerpc64-unknown
;;
- ppc64-*) basic_machine=powerpc64-`echo $basic_machine | sed 's/^[^-]*-//'`
+ ppc64-* | ppc64p7-*) basic_machine=powerpc64-`echo $basic_machine | sed 's/^[^-]*-//'`
;;
ppc64le | powerpc64little)
basic_machine=powerpc64le-unknown
basic_machine=a29k-wrs
os=-vxworks
;;
+ wasm32)
+ basic_machine=wasm32-unknown
+ ;;
w65*)
basic_machine=w65-wdc
os=-none
| -bosx* | -nextstep* | -cxux* | -aout* | -elf* | -oabi* \
| -ptx* | -coff* | -ecoff* | -winnt* | -domain* | -vsta* \
| -udi* | -eabi* | -lites* | -ieee* | -go32* | -aux* \
- | -chorusos* | -chorusrdb* | -cegcc* \
+ | -chorusos* | -chorusrdb* | -cegcc* | -glidix* \
| -cygwin* | -msys* | -pe* | -psos* | -moss* | -proelf* | -rtems* \
| -midipix* | -mingw32* | -mingw64* | -linux-gnu* | -linux-android* \
| -linux-newlib* | -linux-musl* | -linux-uclibc* \
| -morphos* | -superux* | -rtmk* | -rtmk-nova* | -windiss* \
| -powermax* | -dnix* | -nx6 | -nx7 | -sei* | -dragonfly* \
| -skyos* | -haiku* | -rdos* | -toppers* | -drops* | -es* \
- | -onefs* | -tirtos* | -phoenix* | -fuchsia*)
+ | -onefs* | -tirtos* | -phoenix* | -fuchsia* | -redox*)
# Remember, each alternative MUST END IN *, to match a version number.
;;
-qnx*)
sparc-* | *-sun)
os=-sunos4.1.1
;;
+ pru-*)
+ os=-elf
+ ;;
*-be)
os=-beos
;;
-#! /bin/sh
+#!/bin/sh
# depcomp - compile a program generating dependencies as side-effects
scriptversion=2016-01-11.22; # UTC
#!/bin/sh
# install - install a program, script, or datafile
-scriptversion=2014-09-12.12; # UTC
+scriptversion=2016-01-11.22; # UTC
# This originates from X11R5 (mit/util/scripts/install.sh), which was
# later released in X11R6 (xc/config/util/install.sh) with the
# is incompatible with FreeBSD 'install' when (umask & 300) != 0.
;;
*)
- # $RANDOM is not portable (e.g. dash); use it when possible to
- # lower collision chance
tmpdir=${TMPDIR-/tmp}/ins$RANDOM-$$
- trap 'ret=$?; rmdir "$tmpdir/a/b" "$tmpdir/a" "$tmpdir" 2>/dev/null; exit $ret' 0
+ trap 'ret=$?; rmdir "$tmpdir/d" "$tmpdir" 2>/dev/null; exit $ret' 0
- # As "mkdir -p" follows symlinks and we work in /tmp possibly; so
- # create the $tmpdir first (and fail if unsuccessful) to make sure
- # that nobody tries to guess the $tmpdir name.
if (umask $mkdir_umask &&
- $mkdirprog $mkdir_mode "$tmpdir" &&
- exec $mkdirprog $mkdir_mode -p -- "$tmpdir/a/b") >/dev/null 2>&1
+ exec $mkdirprog $mkdir_mode -p -- "$tmpdir/d") >/dev/null 2>&1
then
if test -z "$dir_arg" || {
# Check for POSIX incompatibilities with -m.
# HP-UX 11.23 and IRIX 6.5 mkdir -m -p sets group- or
# other-writable bit of parent directory when it shouldn't.
# FreeBSD 6.1 mkdir -m -p sets mode of existing directory.
- test_tmpdir="$tmpdir/a"
- ls_ld_tmpdir=`ls -ld "$test_tmpdir"`
+ ls_ld_tmpdir=`ls -ld "$tmpdir"`
case $ls_ld_tmpdir in
d????-?r-*) different_mode=700;;
d????-?--*) different_mode=755;;
*) false;;
esac &&
- $mkdirprog -m$different_mode -p -- "$test_tmpdir" && {
- ls_ld_tmpdir_1=`ls -ld "$test_tmpdir"`
+ $mkdirprog -m$different_mode -p -- "$tmpdir" && {
+ ls_ld_tmpdir_1=`ls -ld "$tmpdir"`
test "$ls_ld_tmpdir" = "$ls_ld_tmpdir_1"
}
}
then posix_mkdir=:
fi
- rmdir "$tmpdir/a/b" "$tmpdir/a" "$tmpdir"
+ rmdir "$tmpdir/d" "$tmpdir"
else
# Remove any dirs left behind by ancient mkdir implementations.
- rmdir ./$mkdir_mode ./-p ./-- "$tmpdir" 2>/dev/null
+ rmdir ./$mkdir_mode ./-p ./-- 2>/dev/null
fi
trap '' 0;;
esac;;
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-time-zone: "UTC"
+# time-stamp-time-zone: "UTC0"
# time-stamp-end: "; # UTC"
# End:
PROGRAM=libtool
PACKAGE=libtool
-VERSION="2.4.6 Debian-2.4.6-2"
+VERSION=2.4.6
package_revision=2.4.6
compiler: $LTCC
compiler flags: $LTCFLAGS
linker: $LD (gnu? $with_gnu_ld)
- version: $progname $scriptversion Debian-2.4.6-2
+ version: $progname (GNU libtool) 2.4.6
automake: `($AUTOMAKE --version) 2>/dev/null |$SED 1q`
autoconf: `($AUTOCONF --version) 2>/dev/null |$SED 1q`
Report bugs to <bug-libtool@gnu.org>.
-GNU libtool home page: <http://www.gnu.org/s/libtool/>.
+GNU libtool home page: <http://www.gnu.org/software/libtool/>.
General help using GNU software: <http://www.gnu.org/gethelp/>."
exit 0
}
# -O*, -g*, -flto*, -fwhopr*, -fuse-linker-plugin GCC link-time optimization
# -specs=* GCC specs files
# -stdlib=* select c++ std lib with clang
- # -fsanitize=* Clang/GCC memory and address sanitizer
-64|-mips[0-9]|-r[0-9][0-9]*|-xarch=*|-xtarget=*|+DA*|+DD*|-q*|-m*| \
-t[45]*|-txscale*|-p|-pg|--coverage|-fprofile-*|-F*|@*|-tp=*|--sysroot=*| \
-O*|-g*|-flto*|-fwhopr*|-fuse-linker-plugin|-fstack-protector*|-stdlib=*| \
- -specs=*|-fsanitize=*)
+ -specs=*)
func_quote_for_eval "$arg"
arg=$func_quote_for_eval_result
func_append compile_command " $arg"
case $pass in
dlopen) libs=$dlfiles ;;
dlpreopen) libs=$dlprefiles ;;
- link)
- libs="$deplibs %DEPLIBS%"
- test "X$link_all_deplibs" != Xno && libs="$libs $dependency_libs"
- ;;
+ link) libs="$deplibs %DEPLIBS% $dependency_libs" ;;
esac
fi
if test lib,dlpreopen = "$linkmode,$pass"; then
# It is a libtool convenience library, so add in its objects.
func_append convenience " $ladir/$objdir/$old_library"
func_append old_convenience " $ladir/$objdir/$old_library"
- tmp_libs=
- for deplib in $dependency_libs; do
- deplibs="$deplib $deplibs"
- if $opt_preserve_dup_deps; then
- case "$tmp_libs " in
- *" $deplib "*) func_append specialdeplibs " $deplib" ;;
- esac
- fi
- func_append tmp_libs " $deplib"
- done
elif test prog != "$linkmode" && test lib != "$linkmode"; then
func_fatal_error "'$lib' is not a convenience library"
fi
+ tmp_libs=
+ for deplib in $dependency_libs; do
+ deplibs="$deplib $deplibs"
+ if $opt_preserve_dup_deps; then
+ case "$tmp_libs " in
+ *" $deplib "*) func_append specialdeplibs " $deplib" ;;
+ esac
+ fi
+ func_append tmp_libs " $deplib"
+ done
continue
fi # $pass = conv
revision=$number_minor
lt_irix_increment=no
;;
- *)
- func_fatal_configuration "$modename: unknown library version type '$version_type'"
- ;;
esac
;;
no)
-#! /bin/sh
+#!/bin/sh
# Common wrapper for a few potentially missing GNU programs.
-scriptversion=2013-10-28.13; # UTC
+scriptversion=2016-01-11.22; # UTC
-# Copyright (C) 1996-2014 Free Software Foundation, Inc.
+# Copyright (C) 1996-2017 Free Software Foundation, Inc.
# Originally written by Fran,cois Pinard <pinard@iro.umontreal.ca>, 1996.
# This program is free software; you can redistribute it and/or modify
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-time-zone: "UTC"
+# time-stamp-time-zone: "UTC0"
# time-stamp-end: "; # UTC"
# End:
-#! /bin/sh
+#!/bin/sh
# test-driver - basic testsuite driver script.
-scriptversion=2013-07-13.22; # UTC
+scriptversion=2016-01-11.22; # UTC
-# Copyright (C) 2011-2014 Free Software Foundation, Inc.
+# Copyright (C) 2011-2017 Free Software Foundation, Inc.
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-time-zone: "UTC"
+# time-stamp-time-zone: "UTC0"
# time-stamp-end: "; # UTC"
# End:
--- /dev/null
+EXTRA_DIST = \
+ $(autotoolsdata_DATA) \
+ gtk-doc.m4
+
+CLEANFILES = gtk-doc.flat.make
+
+bin_SCRIPTS = gtkdocize
+
+autotoolsdatadir = $(datadir)/gtk-doc/data
+autotoolsdata_DATA = \
+ gtk-doc.make \
+ gtk-doc.flat.make
+
+aclocaldir = $(datadir)/aclocal
+aclocal_DATA = gtk-doc.m4
+
+gtk-doc.flat.make: gtk-doc.make
+ @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@
+
+-include $(top_srcdir)/git.mk
--- /dev/null
+# Makefile.in generated by automake 1.15.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994-2017 Free Software Foundation, Inc.
+
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+
+
+VPATH = @srcdir@
+am__is_gnu_make = { \
+ if test -z '$(MAKELEVEL)'; then \
+ false; \
+ elif test -n '$(MAKE_HOST)'; then \
+ true; \
+ elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \
+ true; \
+ else \
+ false; \
+ fi; \
+}
+am__make_running_with_option = \
+ case $${target_option-} in \
+ ?) ;; \
+ *) echo "am__make_running_with_option: internal error: invalid" \
+ "target option '$${target_option-}' specified" >&2; \
+ exit 1;; \
+ esac; \
+ has_opt=no; \
+ sane_makeflags=$$MAKEFLAGS; \
+ if $(am__is_gnu_make); then \
+ sane_makeflags=$$MFLAGS; \
+ else \
+ case $$MAKEFLAGS in \
+ *\\[\ \ ]*) \
+ bs=\\; \
+ sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
+ | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \
+ esac; \
+ fi; \
+ skip_next=no; \
+ strip_trailopt () \
+ { \
+ flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
+ }; \
+ for flg in $$sane_makeflags; do \
+ test $$skip_next = yes && { skip_next=no; continue; }; \
+ case $$flg in \
+ *=*|--*) continue;; \
+ -*I) strip_trailopt 'I'; skip_next=yes;; \
+ -*I?*) strip_trailopt 'I';; \
+ -*O) strip_trailopt 'O'; skip_next=yes;; \
+ -*O?*) strip_trailopt 'O';; \
+ -*l) strip_trailopt 'l'; skip_next=yes;; \
+ -*l?*) strip_trailopt 'l';; \
+ -[dEDm]) skip_next=yes;; \
+ -[JT]) skip_next=yes;; \
+ esac; \
+ case $$flg in \
+ *$$target_option*) has_opt=yes; break;; \
+ esac; \
+ done; \
+ test $$has_opt = yes
+am__make_dryrun = (target_option=n; $(am__make_running_with_option))
+am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
+pkgdatadir = $(datadir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkglibexecdir = $(libexecdir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+subdir = buildsystems/autotools
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+ $(top_srcdir)/m4/gtkdoc_jh_path_xml_catalog.m4 \
+ $(top_srcdir)/m4/libtool.m4 $(top_srcdir)/m4/ltoptions.m4 \
+ $(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \
+ $(top_srcdir)/m4/lt~obsolete.m4 $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+ $(ACLOCAL_M4)
+DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON)
+mkinstalldirs = $(install_sh) -d
+CONFIG_CLEAN_FILES = gtkdocize
+CONFIG_CLEAN_VPATH_FILES =
+am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
+am__vpath_adj = case $$p in \
+ $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
+ *) f=$$p;; \
+ esac;
+am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`;
+am__install_max = 40
+am__nobase_strip_setup = \
+ srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'`
+am__nobase_strip = \
+ for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||"
+am__nobase_list = $(am__nobase_strip_setup); \
+ for p in $$list; do echo "$$p $$p"; done | \
+ sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \
+ $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \
+ if (++n[$$2] == $(am__install_max)) \
+ { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \
+ END { for (dir in files) print dir, files[dir] }'
+am__base_list = \
+ sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \
+ sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g'
+am__uninstall_files_from_dir = { \
+ test -z "$$files" \
+ || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \
+ || { echo " ( cd '$$dir' && rm -f" $$files ")"; \
+ $(am__cd) "$$dir" && rm -f $$files; }; \
+ }
+am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" \
+ "$(DESTDIR)$(autotoolsdatadir)"
+SCRIPTS = $(bin_SCRIPTS)
+AM_V_P = $(am__v_P_@AM_V@)
+am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
+am__v_P_0 = false
+am__v_P_1 = :
+AM_V_GEN = $(am__v_GEN_@AM_V@)
+am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
+am__v_GEN_0 = @echo " GEN " $@;
+am__v_GEN_1 =
+AM_V_at = $(am__v_at_@AM_V@)
+am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
+am__v_at_0 = @
+am__v_at_1 =
+SOURCES =
+DIST_SOURCES =
+am__can_run_installinfo = \
+ case $$AM_UPDATE_INFO_DIR in \
+ n|no|NO) false;; \
+ *) (install-info --version) >/dev/null 2>&1;; \
+ esac
+DATA = $(aclocal_DATA) $(autotoolsdata_DATA)
+am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
+am__DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/gtkdocize.in
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+ACLOCAL = @ACLOCAL@
+AMTAR = @AMTAR@
+AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
+AR = @AR@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+CC = @CC@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DATE_FMT_CMD = @DATE_FMT_CMD@
+DBLATEX = @DBLATEX@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DLLTOOL = @DLLTOOL@
+DSYMUTIL = @DSYMUTIL@
+DUMPBIN = @DUMPBIN@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EGREP = @EGREP@
+ELAPSED_FMT = @ELAPSED_FMT@
+EXEEXT = @EXEEXT@
+FGREP = @FGREP@
+FOP = @FOP@
+GREP = @GREP@
+HELP_DIR = @HELP_DIR@
+HIGHLIGHT = @HIGHLIGHT@
+HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+ITSTOOL = @ITSTOOL@
+LD = @LD@
+LDFLAGS = @LDFLAGS@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LIBTOOL = @LIBTOOL@
+LIPO = @LIPO@
+LN_S = @LN_S@
+LTLIBOBJS = @LTLIBOBJS@
+LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@
+MAINT = @MAINT@
+MAKEINFO = @MAKEINFO@
+MANIFEST_TOOL = @MANIFEST_TOOL@
+MKDIR_P = @MKDIR_P@
+NM = @NM@
+NMEDIT = @NMEDIT@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OTOOL = @OTOOL@
+OTOOL64 = @OTOOL64@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_DATA_DIR = @PACKAGE_DATA_DIR@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PKG_CONFIG = @PKG_CONFIG@
+PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@
+PKG_CONFIG_PATH = @PKG_CONFIG_PATH@
+PYTHON = @PYTHON@
+PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@
+PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@
+PYTHON_PLATFORM = @PYTHON_PLATFORM@
+PYTHON_PREFIX = @PYTHON_PREFIX@
+PYTHON_VERSION = @PYTHON_VERSION@
+RANLIB = @RANLIB@
+SED = @SED@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+STRIP = @STRIP@
+TEST_DEPS_CFLAGS = @TEST_DEPS_CFLAGS@
+TEST_DEPS_LIBS = @TEST_DEPS_LIBS@
+TS_FMT = @TS_FMT@
+VERSION = @VERSION@
+XMLCATALOG = @XMLCATALOG@
+XMLLINT = @XMLLINT@
+XML_CATALOG_FILE = @XML_CATALOG_FILE@
+XSLTPROC = @XSLTPROC@
+YELP_LC_DIST = @YELP_LC_DIST@
+YELP_LC_MEDIA_LINKS = @YELP_LC_MEDIA_LINKS@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_AR = @ac_ct_AR@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+glib_prefix = @glib_prefix@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+pkgpyexecdir = @pkgpyexecdir@
+pkgpythondir = @pkgpythondir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+pyexecdir = @pyexecdir@
+pythondir = @pythondir@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+EXTRA_DIST = \
+ $(autotoolsdata_DATA) \
+ gtk-doc.m4
+
+CLEANFILES = gtk-doc.flat.make
+bin_SCRIPTS = gtkdocize
+autotoolsdatadir = $(datadir)/gtk-doc/data
+autotoolsdata_DATA = \
+ gtk-doc.make \
+ gtk-doc.flat.make
+
+aclocaldir = $(datadir)/aclocal
+aclocal_DATA = gtk-doc.m4
+all: all-am
+
+.SUFFIXES:
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps)
+ @for dep in $?; do \
+ case '$(am__configure_deps)' in \
+ *$$dep*) \
+ ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
+ && { if test -f $@; then exit 0; else break; fi; }; \
+ exit 1;; \
+ esac; \
+ done; \
+ echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu buildsystems/autotools/Makefile'; \
+ $(am__cd) $(top_srcdir) && \
+ $(AUTOMAKE) --gnu buildsystems/autotools/Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ @case '$?' in \
+ *config.status*) \
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+ *) \
+ echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
+ esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps)
+ cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(am__aclocal_m4_deps):
+gtkdocize: $(top_builddir)/config.status $(srcdir)/gtkdocize.in
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@
+install-binSCRIPTS: $(bin_SCRIPTS)
+ @$(NORMAL_INSTALL)
+ @list='$(bin_SCRIPTS)'; test -n "$(bindir)" || list=; \
+ if test -n "$$list"; then \
+ echo " $(MKDIR_P) '$(DESTDIR)$(bindir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(bindir)" || exit 1; \
+ fi; \
+ for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ if test -f "$$d$$p"; then echo "$$d$$p"; echo "$$p"; else :; fi; \
+ done | \
+ sed -e 'p;s,.*/,,;n' \
+ -e 'h;s|.*|.|' \
+ -e 'p;x;s,.*/,,;$(transform)' | sed 'N;N;N;s,\n, ,g' | \
+ $(AWK) 'BEGIN { files["."] = ""; dirs["."] = 1; } \
+ { d=$$3; if (dirs[d] != 1) { print "d", d; dirs[d] = 1 } \
+ if ($$2 == $$4) { files[d] = files[d] " " $$1; \
+ if (++n[d] == $(am__install_max)) { \
+ print "f", d, files[d]; n[d] = 0; files[d] = "" } } \
+ else { print "f", d "/" $$4, $$1 } } \
+ END { for (d in files) print "f", d, files[d] }' | \
+ while read type dir files; do \
+ if test "$$dir" = .; then dir=; else dir=/$$dir; fi; \
+ test -z "$$files" || { \
+ echo " $(INSTALL_SCRIPT) $$files '$(DESTDIR)$(bindir)$$dir'"; \
+ $(INSTALL_SCRIPT) $$files "$(DESTDIR)$(bindir)$$dir" || exit $$?; \
+ } \
+ ; done
+
+uninstall-binSCRIPTS:
+ @$(NORMAL_UNINSTALL)
+ @list='$(bin_SCRIPTS)'; test -n "$(bindir)" || exit 0; \
+ files=`for p in $$list; do echo "$$p"; done | \
+ sed -e 's,.*/,,;$(transform)'`; \
+ dir='$(DESTDIR)$(bindir)'; $(am__uninstall_files_from_dir)
+
+installcheck-binSCRIPTS: $(bin_SCRIPTS)
+ bad=0; pid=$$$$; list="$(bin_SCRIPTS)"; for p in $$list; do \
+ case ' $(AM_INSTALLCHECK_STD_OPTIONS_EXEMPT) ' in \
+ *" $$p "* | *" $(srcdir)/$$p "*) continue;; \
+ esac; \
+ f=`echo "$$p" | sed 's,^.*/,,;$(transform)'`; \
+ for opt in --help --version; do \
+ if "$(DESTDIR)$(bindir)/$$f" $$opt >c$${pid}_.out \
+ 2>c$${pid}_.err </dev/null \
+ && test -n "`cat c$${pid}_.out`" \
+ && test -z "`cat c$${pid}_.err`"; then :; \
+ else echo "$$f does not support $$opt" 1>&2; bad=1; fi; \
+ done; \
+ done; rm -f c$${pid}_.???; exit $$bad
+
+mostlyclean-libtool:
+ -rm -f *.lo
+
+clean-libtool:
+ -rm -rf .libs _libs
+install-aclocalDATA: $(aclocal_DATA)
+ @$(NORMAL_INSTALL)
+ @list='$(aclocal_DATA)'; test -n "$(aclocaldir)" || list=; \
+ if test -n "$$list"; then \
+ echo " $(MKDIR_P) '$(DESTDIR)$(aclocaldir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(aclocaldir)" || exit 1; \
+ fi; \
+ for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ echo "$$d$$p"; \
+ done | $(am__base_list) | \
+ while read files; do \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(aclocaldir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(aclocaldir)" || exit $$?; \
+ done
+
+uninstall-aclocalDATA:
+ @$(NORMAL_UNINSTALL)
+ @list='$(aclocal_DATA)'; test -n "$(aclocaldir)" || list=; \
+ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \
+ dir='$(DESTDIR)$(aclocaldir)'; $(am__uninstall_files_from_dir)
+install-autotoolsdataDATA: $(autotoolsdata_DATA)
+ @$(NORMAL_INSTALL)
+ @list='$(autotoolsdata_DATA)'; test -n "$(autotoolsdatadir)" || list=; \
+ if test -n "$$list"; then \
+ echo " $(MKDIR_P) '$(DESTDIR)$(autotoolsdatadir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(autotoolsdatadir)" || exit 1; \
+ fi; \
+ for p in $$list; do \
+ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+ echo "$$d$$p"; \
+ done | $(am__base_list) | \
+ while read files; do \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(autotoolsdatadir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(autotoolsdatadir)" || exit $$?; \
+ done
+
+uninstall-autotoolsdataDATA:
+ @$(NORMAL_UNINSTALL)
+ @list='$(autotoolsdata_DATA)'; test -n "$(autotoolsdatadir)" || list=; \
+ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \
+ dir='$(DESTDIR)$(autotoolsdatadir)'; $(am__uninstall_files_from_dir)
+tags TAGS:
+
+ctags CTAGS:
+
+cscope cscopelist:
+
+
+distdir: $(DISTFILES)
+ @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+ list='$(DISTFILES)'; \
+ dist_files=`for file in $$list; do echo $$file; done | \
+ sed -e "s|^$$srcdirstrip/||;t" \
+ -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+ case $$dist_files in \
+ */*) $(MKDIR_P) `echo "$$dist_files" | \
+ sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+ sort -u` ;; \
+ esac; \
+ for file in $$dist_files; do \
+ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+ if test -d $$d/$$file; then \
+ dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+ if test -d "$(distdir)/$$file"; then \
+ find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+ fi; \
+ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+ cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
+ find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+ fi; \
+ cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
+ else \
+ test -f "$(distdir)/$$file" \
+ || cp -p $$d/$$file "$(distdir)/$$file" \
+ || exit 1; \
+ fi; \
+ done
+check-am: all-am
+check: check-am
+all-am: Makefile $(SCRIPTS) $(DATA)
+installdirs:
+ for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" "$(DESTDIR)$(autotoolsdatadir)"; do \
+ test -z "$$dir" || $(MKDIR_P) "$$dir"; \
+ done
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+ if test -z '$(STRIP)'; then \
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ install; \
+ else \
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+ "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
+ fi
+mostlyclean-generic:
+
+clean-generic:
+ -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
+
+distclean-generic:
+ -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+ -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
+
+maintainer-clean-generic:
+ @echo "This command is intended for maintainers to use"
+ @echo "it deletes files that may require special tools to rebuild."
+clean: clean-am
+
+clean-am: clean-generic clean-libtool mostlyclean-am
+
+distclean: distclean-am
+ -rm -f Makefile
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am:
+
+html: html-am
+
+html-am:
+
+info: info-am
+
+info-am:
+
+install-data-am: install-aclocalDATA install-autotoolsdataDATA
+
+install-dvi: install-dvi-am
+
+install-dvi-am:
+
+install-exec-am: install-binSCRIPTS
+
+install-html: install-html-am
+
+install-html-am:
+
+install-info: install-info-am
+
+install-info-am:
+
+install-man:
+
+install-pdf: install-pdf-am
+
+install-pdf-am:
+
+install-ps: install-ps-am
+
+install-ps-am:
+
+installcheck-am: installcheck-binSCRIPTS
+
+maintainer-clean: maintainer-clean-am
+ -rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am: uninstall-aclocalDATA uninstall-autotoolsdataDATA \
+ uninstall-binSCRIPTS
+
+.MAKE: install-am install-strip
+
+.PHONY: all all-am check check-am clean clean-generic clean-libtool \
+ cscopelist-am ctags-am distclean distclean-generic \
+ distclean-libtool distdir dvi dvi-am html html-am info info-am \
+ install install-aclocalDATA install-am \
+ install-autotoolsdataDATA install-binSCRIPTS install-data \
+ install-data-am install-dvi install-dvi-am install-exec \
+ install-exec-am install-html install-html-am install-info \
+ install-info-am install-man install-pdf install-pdf-am \
+ install-ps install-ps-am install-strip installcheck \
+ installcheck-am installcheck-binSCRIPTS installdirs \
+ maintainer-clean maintainer-clean-generic mostlyclean \
+ mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \
+ tags-am uninstall uninstall-aclocalDATA uninstall-am \
+ uninstall-autotoolsdataDATA uninstall-binSCRIPTS
+
+.PRECIOUS: Makefile
+
+
+gtk-doc.flat.make: gtk-doc.make
+ @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@
+
+-include $(top_srcdir)/git.mk
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
for file in $(HTML_IMAGES) ; do \
test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$file $(abs_builddir)/html; \
+ test -f $$file && cp $$file $(abs_builddir)/html; \
done;
$(GTK_DOC_V_XREF)gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
$(AM_V_at)touch html-build.stamp
for file in $(HTML_IMAGES) ; do \
test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$file $(abs_builddir)/html; \
+ test -f $$file && cp $$file $(abs_builddir)/html; \
done;
$(GTK_DOC_V_XREF)gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
$(AM_V_at)touch html-build.stamp
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
-subdir = cmake
+subdir = buildsystems/cmake
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
$(top_srcdir)/m4/gtkdoc_jh_path_xml_catalog.m4 \
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
exit 1;; \
esac; \
done; \
- echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu cmake/Makefile'; \
+ echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu buildsystems/cmake/Makefile'; \
$(am__cd) $(top_srcdir) && \
- $(AUTOMAKE) --gnu cmake/Makefile
+ $(AUTOMAKE) --gnu buildsystems/cmake/Makefile
Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
@case '$?' in \
*config.status*) \
#! /bin/sh
# Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.69 for gtk-doc 1.28.
+# Generated by GNU Autoconf 2.69 for gtk-doc 1.29.
#
# Report bugs to <http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc>.
#
# Identity of this package.
PACKAGE_NAME='gtk-doc'
PACKAGE_TARNAME='gtk-doc'
-PACKAGE_VERSION='1.28'
-PACKAGE_STRING='gtk-doc 1.28'
+PACKAGE_VERSION='1.29'
+PACKAGE_STRING='gtk-doc 1.29'
PACKAGE_BUGREPORT='http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc'
PACKAGE_URL=''
docdir
oldincludedir
includedir
-runstatedir
localstatedir
sharedstatedir
sysconfdir
sysconfdir='${prefix}/etc'
sharedstatedir='${prefix}/com'
localstatedir='${prefix}/var'
-runstatedir='${localstatedir}/run'
includedir='${prefix}/include'
oldincludedir='/usr/include'
docdir='${datarootdir}/doc/${PACKAGE_TARNAME}'
| -silent | --silent | --silen | --sile | --sil)
silent=yes ;;
- -runstatedir | --runstatedir | --runstatedi | --runstated \
- | --runstate | --runstat | --runsta | --runst | --runs \
- | --run | --ru | --r)
- ac_prev=runstatedir ;;
- -runstatedir=* | --runstatedir=* | --runstatedi=* | --runstated=* \
- | --runstate=* | --runstat=* | --runsta=* | --runst=* | --runs=* \
- | --run=* | --ru=* | --r=*)
- runstatedir=$ac_optarg ;;
-
-sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb)
ac_prev=sbindir ;;
-sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \
for ac_var in exec_prefix prefix bindir sbindir libexecdir datarootdir \
datadir sysconfdir sharedstatedir localstatedir includedir \
oldincludedir docdir infodir htmldir dvidir pdfdir psdir \
- libdir localedir mandir runstatedir
+ libdir localedir mandir
do
eval ac_val=\$$ac_var
# Remove trailing slashes.
# Omit some internal or obsolete options to make the list less imposing.
# This message is too long to be a string in the A/UX 3.1 sh.
cat <<_ACEOF
-\`configure' configures gtk-doc 1.28 to adapt to many kinds of systems.
+\`configure' configures gtk-doc 1.29 to adapt to many kinds of systems.
Usage: $0 [OPTION]... [VAR=VALUE]...
--sysconfdir=DIR read-only single-machine data [PREFIX/etc]
--sharedstatedir=DIR modifiable architecture-independent data [PREFIX/com]
--localstatedir=DIR modifiable single-machine data [PREFIX/var]
- --runstatedir=DIR modifiable per-process data [LOCALSTATEDIR/run]
--libdir=DIR object code libraries [EPREFIX/lib]
--includedir=DIR C header files [PREFIX/include]
--oldincludedir=DIR C header files for non-gcc [/usr/include]
if test -n "$ac_init_help"; then
case $ac_init_help in
- short | recursive ) echo "Configuration of gtk-doc 1.28:";;
+ short | recursive ) echo "Configuration of gtk-doc 1.29:";;
esac
cat <<\_ACEOF
test -n "$ac_init_help" && exit $ac_status
if $ac_init_version; then
cat <<\_ACEOF
-gtk-doc configure 1.28
+gtk-doc configure 1.29
generated by GNU Autoconf 2.69
Copyright (C) 2012 Free Software Foundation, Inc.
This file contains any messages produced by compilers while
running configure, to aid debugging if configure makes a mistake.
-It was created by gtk-doc $as_me 1.28, which was
+It was created by gtk-doc $as_me 1.29, which was
generated by GNU Autoconf 2.69. Invocation command line was
$ $0 $@
# Define the identity of the package.
PACKAGE='gtk-doc'
- VERSION='1.28'
+ VERSION='1.29'
cat >>confdefs.h <<_ACEOF
lt_cv_deplibs_check_method=pass_all
;;
-netbsd* | netbsdelf*-gnu)
+netbsd*)
if echo __ELF__ | $CC -E - | $GREP __ELF__ > /dev/null; then
lt_cv_deplibs_check_method='match_pattern /lib[^/]+(\.so\.[0-9]+\.[0-9]+|_pic\.a)$'
else
openbsd* | bitrig*)
with_gnu_ld=no
;;
- linux* | k*bsd*-gnu | gnu*)
- link_all_deplibs=no
- ;;
esac
ld_shlibs=yes
fi
;;
- netbsd* | netbsdelf*-gnu)
+ netbsd*)
if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then
archive_cmds='$LD -Bshareable $libobjs $deplibs $linker_flags -o $lib'
wlarc=
if test yes = "$lt_cv_irix_exported_symbol"; then
archive_expsym_cmds='$CC -shared $pic_flag $libobjs $deplibs $compiler_flags $wl-soname $wl$soname `test -n "$verstring" && func_echo_all "$wl-set_version $wl$verstring"` $wl-update_registry $wl$output_objdir/so_locations $wl-exports_file $wl$export_symbols -o $lib'
fi
- link_all_deplibs=no
else
archive_cmds='$CC -shared $libobjs $deplibs $compiler_flags -soname $soname `test -n "$verstring" && func_echo_all "-set_version $verstring"` -update_registry $output_objdir/so_locations -o $lib'
archive_expsym_cmds='$CC -shared $libobjs $deplibs $compiler_flags -soname $soname `test -n "$verstring" && func_echo_all "-set_version $verstring"` -update_registry $output_objdir/so_locations -exports_file $export_symbols -o $lib'
esac
;;
- netbsd* | netbsdelf*-gnu)
+ netbsd*)
if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then
archive_cmds='$LD -Bshareable -o $lib $libobjs $deplibs $linker_flags' # a.out
else
# before this can be enabled.
hardcode_into_libs=yes
+ # Add ABI-specific directories to the system library path.
+ sys_lib_dlsearch_path_spec="/lib64 /usr/lib64 /lib /usr/lib"
+
# Ideally, we could use ldconfig to report *all* directores which are
# searched for libraries, however this is still not possible. Aside from not
# being certain /sbin/ldconfig is available, command
# appending ld.so.conf contents (and includes) to the search path.
if test -f /etc/ld.so.conf; then
lt_ld_extra=`awk '/^include / { system(sprintf("cd /etc; cat %s 2>/dev/null", \$2)); skip = 1; } { if (!skip) print \$0; skip = 0; }' < /etc/ld.so.conf | $SED -e 's/#.*//;/^[ ]*hwcap[ ]/d;s/[:, ]/ /g;s/=[^=]*$//;s/=[^= ]* / /g;s/"//g;/^$/d' | tr '\n' ' '`
- sys_lib_dlsearch_path_spec="/lib /usr/lib $lt_ld_extra"
+ sys_lib_dlsearch_path_spec="$sys_lib_dlsearch_path_spec $lt_ld_extra"
fi
# We used to test for /lib/ld.so.1 and disable shared libraries on
dynamic_linker='GNU/Linux ld.so'
;;
-netbsdelf*-gnu)
- version_type=linux
- need_lib_prefix=no
- need_version=no
- library_names_spec='${libname}${release}${shared_ext}$versuffix ${libname}${release}${shared_ext}$major ${libname}${shared_ext}'
- soname_spec='${libname}${release}${shared_ext}$major'
- shlibpath_var=LD_LIBRARY_PATH
- shlibpath_overrides_runpath=no
- hardcode_into_libs=yes
- dynamic_linker='NetBSD ld.elf_so'
- ;;
-
netbsd*)
version_type=sunos
need_lib_prefix=no
if test -n "$PYTHON"; then
# If the user set $PYTHON, use it and don't search something else.
- { $as_echo "$as_me:${as_lineno-$LINENO}: checking whether $PYTHON version is >= 2.7" >&5
-$as_echo_n "checking whether $PYTHON version is >= 2.7... " >&6; }
+ { $as_echo "$as_me:${as_lineno-$LINENO}: checking whether $PYTHON version is >= 3.2" >&5
+$as_echo_n "checking whether $PYTHON version is >= 3.2... " >&6; }
prog="import sys
# split strings by '.' and convert to numeric. Append some zeros
# because we need at least 4 digits for the hex conversion.
# map returns an iterator in Python 3.0 and a list in 2.x
-minver = list(map(int, '2.7'.split('.'))) + [0, 0, 0]
+minver = list(map(int, '3.2'.split('.'))) + [0, 0, 0]
minverhex = 0
# xrange is not present in Python 3.0 and range returns an iterator
for i in list(range(0, 4)): minverhex = (minverhex << 8) + minver[i]
else
# Otherwise, try each interpreter until we find one that satisfies
# VERSION.
- { $as_echo "$as_me:${as_lineno-$LINENO}: checking for a Python interpreter with version >= 2.7" >&5
-$as_echo_n "checking for a Python interpreter with version >= 2.7... " >&6; }
+ { $as_echo "$as_me:${as_lineno-$LINENO}: checking for a Python interpreter with version >= 3.2" >&5
+$as_echo_n "checking for a Python interpreter with version >= 3.2... " >&6; }
if ${am_cv_pathless_PYTHON+:} false; then :
$as_echo_n "(cached) " >&6
else
- for am_cv_pathless_PYTHON in python python2 python3 python3.8 python3.7 python3.6 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 python2.6 python2.5 python2.4 python2.3 python2.2 python2.1 python2.0 none; do
+ for am_cv_pathless_PYTHON in python python2 python3 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 python2.6 python2.5 python2.4 python2.3 python2.2 python2.1 python2.0 none; do
test "$am_cv_pathless_PYTHON" = none && break
prog="import sys
# split strings by '.' and convert to numeric. Append some zeros
# because we need at least 4 digits for the hex conversion.
# map returns an iterator in Python 3.0 and a list in 2.x
-minver = list(map(int, '2.7'.split('.'))) + [0, 0, 0]
+minver = list(map(int, '3.2'.split('.'))) + [0, 0, 0]
minverhex = 0
# xrange is not present in Python 3.0 and range returns an iterator
for i in list(range(0, 4)): minverhex = (minverhex << 8) + minver[i]
xmlpath="$$lc:$(srcdir)/$$lc"; \
fi; \
for page in $(HELP_FILES); do \
- echo "$(XMLLINT) --noout --noent --path $$xmlpath --xinclude $$d$$lc/$$page"; \
- $(XMLLINT) --noout --noent --path "$$xmlpath" --xinclude "$$d$$lc/$$page"; \
+ echo "$(XMLLINT) --nonet --noout --noent --path $$xmlpath --xinclude $$d$$lc/$$page"; \
+ $(XMLLINT) --nonet --noout --noent --path "$$xmlpath" --xinclude "$$d$$lc/$$page"; \
done; \
done
fi
-# cmake/GtkDocConfig.cmake is handled in the Makefile, not here.
-ac_config_files="$ac_config_files Makefile gtk-doc.pc cmake/Makefile cmake/GtkDocConfigVersion.cmake gtkdoc/config.py help/Makefile help/manual/Makefile tests/Makefile tests/annotations/Makefile tests/annotations/src/Makefile tests/annotations/docs/Makefile tests/bugs/Makefile tests/bugs/src/Makefile tests/bugs/docs/Makefile tests/empty/Makefile tests/empty/src/Makefile tests/empty/docs/Makefile tests/fail/Makefile tests/fail/src/Makefile tests/fail/docs/Makefile tests/gobject/Makefile tests/gobject/src/Makefile tests/gobject/docs/Makefile tests/program/Makefile tests/program/src/Makefile tests/program/docs/Makefile tests/repro/Makefile tests/repro/src/Makefile tests/repro/docs/Makefile"
+# buildsystems/cmake/GtkDocConfig.cmake is handled in the Makefile, not here.
+ac_config_files="$ac_config_files Makefile gtk-doc.pc buildsystems/autotools/Makefile buildsystems/cmake/Makefile buildsystems/cmake/GtkDocConfigVersion.cmake gtkdoc/config.py help/Makefile help/manual/Makefile tests/Makefile tests/annotations/Makefile tests/annotations/src/Makefile tests/annotations/docs/Makefile tests/bugs/Makefile tests/bugs/src/Makefile tests/bugs/docs/Makefile tests/empty/Makefile tests/empty/src/Makefile tests/empty/docs/Makefile tests/fail/Makefile tests/fail/src/Makefile tests/fail/docs/Makefile tests/gobject/Makefile tests/gobject/src/Makefile tests/gobject/docs/Makefile tests/program/Makefile tests/program/src/Makefile tests/program/docs/Makefile tests/repro/Makefile tests/repro/src/Makefile tests/repro/docs/Makefile"
ac_config_files="$ac_config_files gtkdoc-check"
ac_config_files="$ac_config_files gtkdoc-scangobj"
-ac_config_files="$ac_config_files gtkdocize"
+ac_config_files="$ac_config_files buildsystems/autotools/gtkdocize"
ac_config_files="$ac_config_files tests/tools.sh"
# report actual input values of CONFIG_FILES etc. instead of their
# values after options handling.
ac_log="
-This file was extended by gtk-doc $as_me 1.28, which was
+This file was extended by gtk-doc $as_me 1.29, which was
generated by GNU Autoconf 2.69. Invocation command line was
CONFIG_FILES = $CONFIG_FILES
cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
ac_cs_version="\\
-gtk-doc config.status 1.28
+gtk-doc config.status 1.29
configured by $0, generated by GNU Autoconf 2.69,
with options \\"\$ac_cs_config\\"
"libtool") CONFIG_COMMANDS="$CONFIG_COMMANDS libtool" ;;
"Makefile") CONFIG_FILES="$CONFIG_FILES Makefile" ;;
"gtk-doc.pc") CONFIG_FILES="$CONFIG_FILES gtk-doc.pc" ;;
- "cmake/Makefile") CONFIG_FILES="$CONFIG_FILES cmake/Makefile" ;;
- "cmake/GtkDocConfigVersion.cmake") CONFIG_FILES="$CONFIG_FILES cmake/GtkDocConfigVersion.cmake" ;;
+ "buildsystems/autotools/Makefile") CONFIG_FILES="$CONFIG_FILES buildsystems/autotools/Makefile" ;;
+ "buildsystems/cmake/Makefile") CONFIG_FILES="$CONFIG_FILES buildsystems/cmake/Makefile" ;;
+ "buildsystems/cmake/GtkDocConfigVersion.cmake") CONFIG_FILES="$CONFIG_FILES buildsystems/cmake/GtkDocConfigVersion.cmake" ;;
"gtkdoc/config.py") CONFIG_FILES="$CONFIG_FILES gtkdoc/config.py" ;;
"help/Makefile") CONFIG_FILES="$CONFIG_FILES help/Makefile" ;;
"help/manual/Makefile") CONFIG_FILES="$CONFIG_FILES help/manual/Makefile" ;;
"gtkdoc-rebase") CONFIG_FILES="$CONFIG_FILES gtkdoc-rebase" ;;
"gtkdoc-scan") CONFIG_FILES="$CONFIG_FILES gtkdoc-scan" ;;
"gtkdoc-scangobj") CONFIG_FILES="$CONFIG_FILES gtkdoc-scangobj" ;;
- "gtkdocize") CONFIG_FILES="$CONFIG_FILES gtkdocize" ;;
+ "buildsystems/autotools/gtkdocize") CONFIG_FILES="$CONFIG_FILES buildsystems/autotools/gtkdocize" ;;
"tests/tools.sh") CONFIG_FILES="$CONFIG_FILES tests/tools.sh" ;;
*) as_fn_error $? "invalid argument: \`$ac_config_target'" "$LINENO" 5;;
cat <<_LT_EOF >> "$cfgfile"
#! $SHELL
# Generated automatically by $as_me ($PACKAGE) $VERSION
+# Libtool was configured on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
# NOTE: Changes made to this file will be lost: look at ltmain.sh.
# Provide generalized library-building support services.
"gtkdoc-rebase":F) chmod +x gtkdoc-rebase ;;
"gtkdoc-scan":F) chmod +x gtkdoc-scan ;;
"gtkdoc-scangobj":F) chmod +x gtkdoc-scangobj ;;
- "gtkdocize":F) chmod +x gtkdocize ;;
+ "buildsystems/autotools/gtkdocize":F) chmod +x buildsystems/autotools/gtkdocize ;;
"tests/tools.sh":F) chmod +x tests/tools.sh ;;
esac
dnl We're using a two digit number for the releases and
dnl a three digit number for the development version
-m4_define(gtk_doc_version, 1.28)
+m4_define(gtk_doc_version, 1.29)
AC_INIT([gtk-doc],[gtk_doc_version],[http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc],[gtk-doc])
dnl
dnl Check for Python.
dnl
-AM_PATH_PYTHON([2.7])
+AM_PATH_PYTHON([3.2])
dnl
dnl Check for xsltproc
fi
AM_CONDITIONAL([HAVE_YELP_TOOLS],[test x$have_yelp_tools = xyes])
-# cmake/GtkDocConfig.cmake is handled in the Makefile, not here.
+# buildsystems/cmake/GtkDocConfig.cmake is handled in the Makefile, not here.
AC_CONFIG_FILES([Makefile
gtk-doc.pc
-cmake/Makefile
-cmake/GtkDocConfigVersion.cmake
+buildsystems/autotools/Makefile
+buildsystems/cmake/Makefile
+buildsystems/cmake/GtkDocConfigVersion.cmake
gtkdoc/config.py
help/Makefile
help/manual/Makefile
AC_CONFIG_FILES([gtkdoc-rebase], [chmod +x gtkdoc-rebase])
AC_CONFIG_FILES([gtkdoc-scan], [chmod +x gtkdoc-scan])
AC_CONFIG_FILES([gtkdoc-scangobj], [chmod +x gtkdoc-scangobj])
-AC_CONFIG_FILES([gtkdocize], [chmod +x gtkdocize])
+AC_CONFIG_FILES([buildsystems/autotools/gtkdocize], [chmod +x buildsystems/autotools/gtkdocize])
AC_CONFIG_FILES([tests/tools.sh], [chmod +x tests/tools.sh])
AC_OUTPUT
parser = argparse.ArgumentParser(
description='gtkdoc-mkhtml version %s - generate documentation in html format' % config.version)
parser.add_argument('--version', action='version', version=config.version)
+ parser.add_argument('--path', default=[], action='append',
+ help='Extra source directories')
+ parser.add_argument('--src-lang', default='c',
+ help='Programing language used for syntax highlighting. This'
+ 'can be any language pygments supports.')
parser.add_argument('args', nargs='*',
help='MODULE DRIVER_FILE')
# TODO: only for testing, replace with env-var
Makefile.am: TESTS = $(GTKDOC_CHECK).
"""
-# Support both Python 2 and 3
-from __future__ import print_function
-
import os
import re
from glob import glob
return count
+def read_file(filename):
+ with open(filename, 'r', encoding='utf-8') as f:
+ return f.read().splitlines()
+
+
def check_includes(filename):
# Check that each XML file in the xml directory is included in doc_main_file
- with common.open_text(filename) as f:
- lines = f.read().splitlines()
- num_missing = 0
- for include in glob('xml/*.xml'):
- try:
- next(line for line in lines if include in line)
- except StopIteration:
- num_missing += 1
- print('%s:1:E: doesn\'t appear to include "%s"' % (filename, include))
+ lines = read_file(filename)
+ num_missing = 0
+ for include in glob('xml/*.xml'):
+ try:
+ next(line for line in lines if include in line)
+ except StopIteration:
+ num_missing += 1
+ print('%s:1:E: doesn\'t appear to include "%s"' % (filename, include))
return num_missing
return value
-def read_file(filename):
- with common.open_text(filename) as f:
- return f.read().splitlines()
-
-
def run_tests(workdir, doc_module, doc_main_file):
checks = 4
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
-# Support both Python 2 and 3
-from __future__ import print_function
-
from collections import OrderedDict
import logging
import os
import re
import subprocess
import sys
-import six
-import codecs
from . import config
-def open_text(filename, mode='r', encoding='utf-8'):
- """An open() which removes some differences between Python 2 and 3 and
- has saner defaults.
-
- Unlike the builtin open by default utf-8 is use and not the locale
- encoding (which is ANSI on Windows for example, not very helpful)
-
- For Python 2, files are opened in text mode like with Python 3.
- """
-
- if mode not in ('r', 'w'):
- raise ValueError("mode %r not supported, must be 'r' or 'w'" % mode)
-
- if six.PY3:
- return open(filename, mode, encoding=encoding)
- else:
- # We can't use io.open() here as its write method is too strict and
- # only allows unicode instances and not everything in the codebase
- # forces unicode at the moment. codecs.open() on the other hand
- # happily takes ASCII str and decodes it.
- return codecs.open(filename, mode, encoding=encoding)
-
-
def setup_logging():
"""Check GTKDOC_TRACE environment variable.
logging.basicConfig(stream=sys.stdout,
level=logging.getLevelName(log_level.upper()),
format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s')
- # When redirecting the output on python2 or if run with a non utf-8 locale
+ # When redirecting the output and running with a non utf-8 locale
# we get UnicodeEncodeError:
encoding = sys.stdout.encoding
if 'PYTHONIOENCODING' not in os.environ and (not encoding or encoding != 'UTF-8'):
sys.stdout.flush()
- if six.PY3:
- sys.stdout = open(sys.stdout.fileno(), mode='w', encoding='utf8', buffering=1)
- else:
- import codecs
- sys.stdout = codecs.getwriter('utf8')(sys.stdout)
+ sys.stdout = open(sys.stdout.fileno(), mode='w', encoding='utf8', buffering=1)
def UpdateFileIfChanged(old_file, new_file, make_backup):
-version = "1.28"
+version = "1.29"
# tools
-dblatex = '/usr/bin/dblatex'
+dblatex = ''
fop = ''
highlight = '/usr/bin/source-highlight'
highlight_options = '-t4 -s$SRC_LANG -cstyle.css --no-doc -i'
xsltproc = '/usr/bin/xsltproc'
# configured directories
-prefix = '/usr'
+prefix = '/usr/local'
datarootdir = "${prefix}/share".replace('${prefix}', prefix)
datadir = "${datarootdir}".replace('${datarootdir}', datarootdir)
''"Fix cross-references in the HTML documentation.''"
-# Support both Python 2 and 3
-from __future__ import print_function
-
import logging
import os
import re
'unsigned',
'va-list',
'void',
- 'GBoxed',
- 'GEnum',
- 'GFlags',
- 'GInterface'
}
if dir != html_dir:
logging.info('Scanning GLib directory: %s', dir)
ScanIndices(dir, (re.search(prefix_match, dir) is None), dir_cache)
+ else:
+ NoLinks.add('GBoxed')
+ NoLinks.add('GEnum')
+ NoLinks.add('GFlags')
+ NoLinks.add('GInterface')
path = os.environ.get('GNOME2_PATH')
if path:
logging.info('Scanning index file=%s, absolute=%d, dir=%s', file, use_absolute_links, dir)
- for line in common.open_text(file):
+ for line in open(file, 'r', encoding='utf-8'):
m = re.search(r' link="([^#]*)#([^"]*)"', line)
if m:
link = m.group(1) + '#' + m.group(2)
def ReadSections(module):
"""We don't warn on missing links to non-public sysmbols."""
- for line in common.open_text(module + '-sections.txt'):
+ for line in open(module + '-sections.txt', 'r', encoding='utf-8'):
m1 = re.search(r'^<SUBSECTION\s*(.*)>', line)
if line.startswith('#') or line.strip() == '':
continue
def FixHTMLFile(src_lang, module, file):
logging.info('Fixing file: %s', file)
- content = common.open_text(file).read()
+ content = open(file, 'r', encoding='utf-8').read()
if config.highlight:
# FIXME: ideally we'd pass a clue about the example language to the highligher
new_file = file + '.new'
content = '\n'.join(lines)
- with common.open_text(new_file, 'w') as h:
+ with open(new_file, 'w', encoding='utf-8') as h:
h.write(content)
os.unlink(file)
os.rename(new_file, file)
-def MakeXRef(module, file, line, id, text):
+def GetXRef(id):
href = Links.get(id)
+ if href:
+ return (id, href)
# This is a workaround for some inconsistency we have with CreateValidSGMLID
- if not href and ':' in id:
- href = Links.get(id.replace(':', '--'))
+ if ':' in id:
+ tid = id.replace(':', '--')
+ href = Links.get(tid)
+ if href:
+ return (tid, href)
+
# poor mans plural support
- if not href and id.endswith('s'):
+ if id.endswith('s'):
tid = id[:-1]
href = Links.get(tid)
- if not href:
- href = Links.get(tid + '-struct')
- if not href:
- href = Links.get(id + '-struct')
+ if href:
+ return (tid, href)
+ tid += '-struct'
+ href = Links.get(tid)
+ if href:
+ return (tid, href)
+ tid = id + '-struct'
+ href = Links.get(tid)
if href:
- # if it is a link to same module, remove path to make it work uninstalled
- m = re.search(r'^\.\./' + module + '/(.*)$', href)
- if m:
- href = m.group(1)
- logging.info('Fixing link to uninstalled doc: %s, %s, %s', id, href, text)
- else:
- logging.info('Fixing link: %s, %s, %s', id, href, text)
+ return (tid, href)
+
+ return (id, None)
+
+
+def ReportBadXRef(file, line, id, text):
+ logging.info('no link for: id=%s, linktext=%s', id, text)
+
+ # don't warn multiple times and also skip blacklisted (ctypes)
+ if id in NoLinks:
+ return
+ # if it's a function, don't warn if it does not contain a "_"
+ # (transformed to "-")
+ # - gnome coding style would use '_'
+ # - will avoid wrong warnings for ansi c functions
+ if re.search(r' class=\"function\"', text) and '-' not in id:
+ return
+ # if it's a 'return value', don't warn (implicitly created link)
+ if re.search(r' class=\"returnvalue\"', text):
+ return
+ # if it's a 'type', don't warn if it starts with lowercase
+ # - gnome coding style would use CamelCase
+ if re.search(r' class=\"type\"', text) and id[0].islower():
+ return
+ # don't warn for self links
+ if text == id:
+ return
+
+ common.LogWarning(file, line, 'no link for: "%s" -> (%s).' % (id, text))
+ NoLinks.add(id)
+
+
+def MakeRelativeXRef(module, href):
+ # if it is a link to same module, remove path to make it work uninstalled
+ m = re.search(r'^\.\./' + module + '/(.*)$', href)
+ if m:
+ href = m.group(1)
+ return href
+
+
+def MakeXRef(module, file, line, id, text):
+ href = GetXRef(id)[1]
+
+ if href:
+ href = MakeRelativeXRef(module, href)
+ logging.info('Fixing link: %s, %s, %s', id, href, text)
return "<a href=\"%s\">%s</a>" % (href, text)
else:
- logging.info('no link for: %s, %s', id, text)
-
- # don't warn multiple times and also skip blacklisted (ctypes)
- if id in NoLinks:
- return text
- # if it's a function, don't warn if it does not contain a "_"
- # (transformed to "-")
- # - gnome coding style would use '_'
- # - will avoid wrong warnings for ansi c functions
- if re.search(r' class=\"function\"', text) and '-' not in id:
- return text
- # if it's a 'return value', don't warn (implicitly created link)
- if re.search(r' class=\"returnvalue\"', text):
- return text
- # if it's a 'type', don't warn if it starts with lowercase
- # - gnome coding style would use CamelCase
- if re.search(r' class=\"type\"', text) and id[0].islower():
- return text
- # don't warn for self links
- if text == id:
- return text
-
- common.LogWarning(file, line, 'no link for: "%s" -> (%s).' % (id, text))
- NoLinks.add(id)
+ ReportBadXRef(file, line, id, text)
return text
script += "%s -n -e -u NONE -T xterm >/dev/null" % config.highlight
subprocess.check_call([script], shell=True)
- highlighted_source = common.open_text(temp_source_file + ".html").read()
+ highlighted_source = open(temp_source_file + ".html", 'r', encoding='utf-8').read()
highlighted_source = re.sub(r'.*<pre\b[^>]*>\n', '', highlighted_source, flags=re.DOTALL)
highlighted_source = re.sub(r'</pre>.*', '', highlighted_source, flags=re.DOTALL)
Creates the DocBook files from the source comments.
"""
-from __future__ import print_function
-from six import iteritems, iterkeys
-
from collections import OrderedDict
import logging
import os
old_object_index = os.path.join(DB_OUTPUT_DIR, "object_index.sgml")
new_object_index = os.path.join(DB_OUTPUT_DIR, "object_index.new")
- OUTPUT = common.open_text(new_object_index, 'w')
+ OUTPUT = open(new_object_index, 'w', encoding='utf-8')
OUTPUT.write('''%s
<informaltable pgwide="1" frame="none">
"""
logging.info("Reading: %s", file)
- INPUT = common.open_text(file)
+ INPUT = open(file, 'r', encoding='utf-8')
filename = ''
book_top = ''
book_bottom = ''
while True:
prefix = {}
letter = ''
- for symbol in iterkeys(IndexEntriesFull):
+ for symbol in IndexEntriesFull.keys():
if name_space == '' or name_space.lower() in symbol.lower():
if len(symbol) > pos:
letter = symbol[pos:pos + 1]
if letter != '' and letter != "_":
maxletter = ''
maxsymbols = 0
- for letter in iterkeys(prefix):
+ for letter in prefix.keys():
logging.debug("ns prefix: %s: %s", letter, prefix[letter])
if prefix[letter] > maxsymbols:
maxletter = letter
{
'original': x,
'short': re.sub(r'^' + NAME_SPACE + r'\_?(.*)', r'\1', x.upper(), flags=re.I),
- } for x in iterkeys(apiindex)]
+ } for x in apiindex.keys()]
sorted_keys = sorted(mapped_keys, key=lambda d: (d['short'], d['original']))
for key in sorted_keys:
"""Generate the 'since' api index files."""
for version in set(Since.values()):
logging.info("Since : [%s]", version)
- index = {x: IndexEntriesSince[x] for x in iterkeys(IndexEntriesSince) if Since[x] == version}
+ index = {x: IndexEntriesSince[x] for x in IndexEntriesSince.keys() if Since[x] == version}
OutputIndex("api-index-" + version, index)
rerun = True
break
- OUTPUT = common.open_text(new_glossary, 'w')
+ OUTPUT = open(new_glossary, 'w', encoding='utf-8')
OUTPUT.write('''%s
<glossary id="annotation-glossary">
<title>Annotation Glossary</title>
''' % MakeDocHeader("glossary"))
- for annotation in sorted(iterkeys(AnnotationsUsed), key=str.lower):
+ for annotation in sorted(AnnotationsUsed.keys(), key=str.lower):
if annotation in AnnotationDefinition:
definition = AnnotationDefinition[annotation]
curletter = annotation[0].upper()
subsection = ''
logging.info("Reading: %s", file)
- INPUT = common.open_text(file)
+ INPUT = open(file, 'r', encoding='utf-8')
for line in INPUT:
if line.startswith('#'):
continue
<tbody>
''' % sid
- for field_name, text in iteritems(fields):
+ for field_name, text in fields.items():
param_annotations = ''
desc += "<row role=\"member\"><entry role=\"struct_member_name\"><para>%s</para></entry>\n" % text
<tbody>
''' % sid
- for field_name, text in iteritems(fields):
+ for field_name, text in fields.items():
param_annotations = ''
desc += "<row><entry role=\"union_member_name\"><para>%s</para></entry>\n" % text
if param_annotations != '':
desc += "\n<para>%s</para>" % param_annotations
- desc += OutputParamDescriptions("FUNCTION", symbol, iterkeys(fields))
+ desc += OutputParamDescriptions("FUNCTION", symbol, fields.keys())
desc += OutputSymbolTraits(symbol)
desc += "</refsect2>\n"
return (synop, desc)
missing_parameters = ''
unused_parameters = ''
- for param_name, param_desc in iteritems(params):
+ for param_name, param_desc in params.items():
(param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc)
param_desc = ConvertMarkDown(symbol, param_desc)
# trim
old_db_file = os.path.join(DB_OUTPUT_DIR, file + '.xml')
new_db_file = os.path.join(DB_OUTPUT_DIR, file + '.xml.new')
- OUTPUT = common.open_text(new_db_file, 'w')
+ OUTPUT = open(new_db_file, 'w', encoding='utf-8')
object_anchors = ''
for fobject in file_objects:
old_db_file = os.path.join(DB_OUTPUT_DIR, program + ".xml")
new_db_file = os.path.join(DB_OUTPUT_DIR, program + ".xml.new")
- OUTPUT = common.open_text(new_db_file, 'w')
+ OUTPUT = open(new_db_file, 'w', encoding='utf-8')
OUTPUT.write('''%s
<refentry id="%s">
old_db_file = os.path.join(DB_OUTPUT_DIR, basename)
new_db_file = os.path.join(DB_OUTPUT_DIR, basename + ".new")
- contents = common.open_text(file).read()
+ contents = open(file, 'r', encoding='utf-8').read()
- OUTPUT = common.open_text(new_db_file, 'w')
- OUTPUT.write(ExpandAbbreviations(basename + " file", contents))
- OUTPUT.close()
+ with open(new_db_file, 'w', encoding='utf-8') as out:
+ out.write(ExpandAbbreviations(basename + " file", contents))
return common.UpdateFileIfChanged(old_db_file, new_db_file, 0)
def GetDocbookHeader(main_file):
if os.path.exists(main_file):
- INPUT = common.open_text(main_file)
+ INPUT = open(main_file, 'r', encoding='utf-8')
header = ''
for line in INPUT:
if re.search(r'^\s*<(book|chapter|article)', line):
old_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.top")
new_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.top.new")
- OUTPUT = common.open_text(new_file, 'w')
- OUTPUT.write(book_top)
- OUTPUT.close()
+ with open(new_file, 'w', encoding='utf-8') as out:
+ out.write(book_top)
common.UpdateFileIfChanged(old_file, new_file, 0)
old_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.bottom")
new_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.bottom.new")
- OUTPUT = common.open_text(new_file, 'w')
- OUTPUT.write(book_bottom)
- OUTPUT.close()
+ with open(new_file, 'w', encoding='utf-8') as out:
+ out.write(book_bottom)
common.UpdateFileIfChanged(old_file, new_file, 0)
# If the main docbook file hasn't been created yet, we create it here.
# The user can tweak it later.
if main_file and not os.path.exists(main_file):
- OUTPUT = common.open_text(main_file, 'w')
+ OUTPUT = open(main_file, 'w', encoding='utf-8')
logging.info("no master doc, create default one at: " + main_file)
OUTPUT.write('''%s
-<book id="index">
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>&package_name; Reference Manual</title>
<releaseinfo>
<chapter>
<title>[Insert title here]</title>
- %s
- </chapter>
+%s </chapter>
''' % (MakeDocHeader("book"), book_bottom))
if os.path.exists('xml/tree_index.sgml'):
OUTPUT.write(''' <chapter id="object-tree">
# For the simple non-sgml mode, convert to entities everywhere.
text = re.sub(r'&(?![a-zA-Z#]+;)', r'&', text) # Do this first, or the others get messed up.
- text = re.sub(r'<', r'<', text)
+ # Allow '<' in verbatim markdown
+ # TODO: we don't want to convert any of them between ``
+ text = re.sub(r'(?<!`)<', r'<', text)
# Allow '>' at beginning of string for blockquote markdown
text = re.sub(r'''(?<=[^\w\n"'\/-])>''', r'>', text)
logging.info("Scanning source file: %s", ifile)
- SRCFILE = common.open_text(ifile)
+ SRCFILE = open(ifile, 'r', encoding='utf-8')
in_comment_block = False
symbol = None
in_part = ''
# Convert special characters
description = ConvertSGMLChars(symbol, description)
- for (param_name, param_desc) in iteritems(params):
+ for (param_name, param_desc) in params.items():
params[param_name] = ConvertSGMLChars(symbol, param_desc)
# Handle Section docs
ifile, line_number, "Section %s is not defined in the %s-sections.txt file." % (real_symbol, MODULE))
logging.info("SECTION DOCS found in source for : '%s'", real_symbol)
- for param_name, param_desc in iteritems(params):
+ for param_name, param_desc in params.items():
logging.info(" '" + param_name + "'")
param_name = param_name.lower()
key = None
section_id = None
logging.info("PROGRAM DOCS found in source for '%s'", real_symbol)
- for param_name, param_desc in iteritems(params):
+ for param_name, param_desc in params.items():
logging.info("PROGRAM key %s: '%s'", real_symbol, param_name)
param_name = param_name.lower()
key = None
buffer_deprecated = ''
buffer_descriptions = ''
- UNDOCUMENTED = common.open_text(new_undocumented_file, 'w')
+ UNDOCUMENTED = open(new_undocumented_file, 'w', encoding='utf-8')
- for symbol in sorted(iterkeys(AllSymbols)):
+ for symbol in sorted(AllSymbols.keys()):
# FIXME: should we print common.LogWarnings for undocumented stuff?
# DEBUG
# location = "defined at " + GetSymbolSourceFile(symbol) + ":" + GetSymbolSourceLine(symbol) + "\n"
old_undeclared_file = os.path.join(ROOT_DIR, MODULE + "-undeclared.txt")
new_undeclared_file = os.path.join(ROOT_DIR, MODULE + "-undeclared.new")
- UNDECLARED = common.open_text(new_undeclared_file, 'w')
-
- if UndeclaredSymbols:
- UNDECLARED.write("\n".join(sorted(iterkeys(UndeclaredSymbols))))
- UNDECLARED.write("\n")
- print("See %s-undeclared.txt for the list of undeclared symbols." % MODULE)
-
- UNDECLARED.close()
+ with open(new_undeclared_file, 'w', encoding='utf-8') as out:
+ if UndeclaredSymbols:
+ out.write("\n".join(sorted(UndeclaredSymbols.keys())))
+ out.write("\n")
+ print("See %s-undeclared.txt for the list of undeclared symbols." % MODULE)
return common.UpdateFileIfChanged(old_undeclared_file, new_undeclared_file, 0)
old_unused_file = os.path.join(ROOT_DIR, MODULE + "-unused.txt")
new_unused_file = os.path.join(ROOT_DIR, MODULE + "-unused.new")
- UNUSED = common.open_text(new_unused_file, 'w')
+ with open(new_unused_file, 'w', encoding='utf-8') as out:
- for symbol in sorted(iterkeys(Declarations)):
- if symbol not in DeclarationOutput:
- UNUSED.write("%s\n" % symbol)
- num_unused += 1
+ for symbol in sorted(Declarations.keys()):
+ if symbol not in DeclarationOutput:
+ out.write("%s\n" % symbol)
+ num_unused += 1
- for symbol in sorted(iterkeys(AllUnusedSymbols)):
- UNUSED.write(symbol + "(" + AllUnusedSymbols[symbol] + ")\n")
- num_unused += 1
+ for symbol in sorted(AllUnusedSymbols.keys()):
+ out.write(symbol + "(" + AllUnusedSymbols[symbol] + ")\n")
+ num_unused += 1
- UNUSED.close()
if num_unused != 0:
common.LogWarning(
old_unused_file, 1, "%d unused declarations. They should be added to %s-sections.txt in the appropriate place." % (num_unused, MODULE))
def OutputAllSymbols():
"""Outputs list of all symbols to a file."""
- SYMBOLS = common.open_text(os.path.join(ROOT_DIR, MODULE + "-symbols.txt"), 'w')
-
- for symbol in sorted(iterkeys(AllSymbols)):
- SYMBOLS.write(symbol + "\n")
- SYMBOLS.close()
+ new_symbols_file = os.path.join(ROOT_DIR, MODULE + "-symbols.txt")
+ with open(new_symbols_file, 'w', encoding='utf-8') as out:
+ for symbol in sorted(AllSymbols.keys()):
+ out.write(symbol + "\n")
def OutputSymbolsWithoutSince():
"""Outputs list of all symbols without a since tag to a file."""
- SYMBOLS = common.open_text(os.path.join(ROOT_DIR, MODULE + "-nosince.txt"), 'w')
-
- for symbol in sorted(iterkeys(SourceSymbolDocs)):
- if symbol in Since:
- SYMBOLS.write(symbol + "\n")
- SYMBOLS.close()
+ new_nosince_file = os.path.join(ROOT_DIR, MODULE + "-nosince.txt")
+ with open(new_nosince_file, 'w', encoding='utf-8') as out:
+ for symbol in sorted(SourceSymbolDocs.keys()):
+ if symbol in Since:
+ out.write(symbol + "\n")
def CheckParamsDocumented(symbol, params):
if len(params) > 0:
logging.info("params: %s", str(params))
- for (param_name, param_desc) in iteritems(params):
+ for (param_name, param_desc) in params.items():
# Output a warning if the parameter is empty and remember for stats.
if param_name != "void" and not re.search(r'\S', param_desc):
if symbol in AllIncompleteSymbols:
"""
# add whats found in the source
- symbols = set(iterkeys(SourceSymbolDocs))
+ symbols = set(SourceSymbolDocs.keys())
# and add known symbols from -sections.txt
- for symbol in iterkeys(KnownSymbols):
+ for symbol in KnownSymbols.keys():
if KnownSymbols[symbol] == 1:
symbols.add(symbol)
DeclarationConditional.clear()
DeclarationOutput.clear()
- INPUT = common.open_text(ifile)
+ INPUT = open(ifile, 'r', encoding='utf-8')
declaration_type = ''
declaration_name = None
declaration = None
if not os.path.isfile(ifile):
return
- INPUT = common.open_text(ifile)
+ INPUT = open(ifile, 'r', encoding='utf-8')
line_number = 0
for line in INPUT:
line_number += 1
logging.debug('no *-hierarchy.tx')
return
- INPUT = common.open_text(ifile)
+ INPUT = open(ifile, 'r', encoding='utf-8')
# Only emit objects if they are supposed to be documented, or if
# they have documented children. To implement this, we maintain a
logging.debug('got %d entries for hierarchy', len(tree))
- OUTPUT = common.open_text(new_tree_index, 'w')
- OUTPUT.write(MakeDocHeader("screen") + "\n<screen>\n" + AddTreeLineArt(tree) + "\n</screen>\n")
- OUTPUT.close()
+ with open(new_tree_index, 'w', encoding='utf-8') as out:
+ out.write(MakeDocHeader("screen"))
+ out.write("\n<screen>\n")
+ out.write(AddTreeLineArt(tree))
+ out.write("\n</screen>\n")
common.UpdateFileIfChanged(old_tree_index, new_tree_index, 0)
if not os.path.isfile(ifile):
return
- INPUT = common.open_text(ifile)
+ INPUT = open(ifile, 'r', encoding='utf-8')
for line in INPUT:
line = line.strip()
if not os.path.isfile(ifile):
return
- INPUT = common.open_text(ifile)
+ INPUT = open(ifile, 'r', encoding='utf-8')
for line in INPUT:
line = line.strip()
if not os.path.isfile(ifile):
return
- INPUT = common.open_text(ifile)
+ INPUT = open(ifile, 'r', encoding='utf-8')
line_number = 0
for line in INPUT:
line_number += 1
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
-"""Prototype for builtin docbook processing
+"""Generate html from docbook
The tool loads the main xml document (<module>-docs.xml) and chunks it
like the xsl-stylesheets would do. For that it resolves all the xml-includes.
-Each chunk is converted to htnml using python functions.
+Each chunk is converted to html using python functions.
In contrast to our previous approach of running gtkdoc-mkhtml + gtkdoc-fixxref,
this tools will replace both without relying on external tools such as xsltproc
and source-highlight.
+Please note, that we're not aiming for complete docbook-xml support. All tags
+used in the generated xml are of course handled. More tags used in handwritten
+xml can be easilly supported, but for some combinations of tags we prefer
+simplicity.
+
TODO:
-- more chunk converters
+- tag converters:
+ - 'section'/'simplesect' - the first we convert as a chunk, the nested ones we
+ need to convert as 'sect{2,3,4,...}, we can track depth in 'ctx'
+ - inside 'footnote' one can have many tags, we only handle 'para'/'simpara'
+ - inside 'glossentry' we're only handling 'glossterm' and 'glossdef'
+ - convert_{figure,table} need counters.
- check each docbook tag if it can contain #PCDATA, if not don't check for
- xml.text
+ xml.text/xml.tail and add a comment (# no PCDATA allowed here)
+- find a better way to print context for warnings
+ - we use 'xml.sourceline', but this all does not help a lot due to xi:include
+- consolidate title handling:
+ - always use the titles-dict
+ - convert_title(): uses titles.get(tid)['title']
+ - convert_xref(): uses titles[tid]['tag'], ['title'] and ['xml']
+ - create_devhelp2_refsect2_keyword(): uses titles[tid]['title']
+ - there only store what we have (xml, tag, ...)
+ - when chunking generate 'id's and add entries to titles-dict
+ - add accessors for title and raw_title that lazily get them
+ - see if any of the other ~10 places that call convert_title() could use this
+ cache
+- performance
+ - consider some perf-warnings flag
+ - see 'No "id" attribute on'
+ - xinclude processing in libxml2 is slow
+ - if we disable it, we get '{http://www.w3.org/2003/XInclude}include' tags
+ and we could try handling them ourself, in some cases those are subtrees
+ that we extract for chunking anyway
+
+DIFFERENCES:
+- titles
+ - we add the chunk label to the title in toc, on the page and in nav tooltips
+ - docbook xsl only sometimes adds the label to the titles and when it does it
+ adds name chunk type too (e.g. 'Part I.' instead of 'I.')
+- navigation
+ - we always add an up-link except on the first page
+- footer
+ - we're nov omitting the footer
+- tocs
+ - we always add "Table of Contents' before a toc
+ - docbook does that for some pages, it is configurable
OPTIONAL:
- minify html: https://pypi.python.org/pypi/htmlmin/
from pygments import highlight
from pygments.lexers import CLexer
from pygments.formatters import HtmlFormatter
+from timeit import default_timer as timer
from . import config, fixxref
# pygments setup
-# TODO: maybe use get_lexer_for_filename()
-LEXER = CLexer()
+# lazily constructed lexer cache
+LEXERS = {
+ 'c': CLexer()
+}
HTML_FORMATTER = HtmlFormatter(nowrap=True)
-# http://www.sagehill.net/docbookxsl/Chunking.html
-CHUNK_TAGS = [
- 'appendix',
- 'article',
- 'bibliography', # in article or book
- 'book',
- 'chapter',
- 'colophon',
- 'glossary', # in article or book
- 'index', # in article or book
- 'part',
- 'preface',
- 'refentry',
- 'reference',
- 'sect1', # except first
- 'section', # if equivalent to sect1
- 'set',
- 'setindex',
-]
-
class ChunkParams(object):
- def __init__(self, prefix, parent=None):
+ def __init__(self, prefix, parent=None, min_idx=0):
self.prefix = prefix
- self.parent = None
- self.count = 0
+ self.parent = parent
+ self.min_idx = min_idx
+ self.idx = 1
-# TODO: look up the abbrevs and hierarchy for other tags
+DONT_CHUNK = float('inf')
+# docbook-xsl defines the chunk tags here.
# http://www.sagehill.net/docbookxsl/Chunking.html#GeneratedFilenames
# https://github.com/oreillymedia/HTMLBook/blob/master/htmlbook-xsl/chunk.xsl#L33
+# If not defined, we can just create an example without an 'id' attr and see
+# docbook xsl does.
+#
+# For toc levels see http://www.sagehill.net/docbookxsl/TOCcontrol.html
+# TODO: this list has also a flag that controls wheter we add the
+# 'Table of Contents' heading in convert_chunk_with_toc()
CHUNK_PARAMS = {
'appendix': ChunkParams('app', 'book'),
'book': ChunkParams('bk'),
'chapter': ChunkParams('ch', 'book'),
+ 'glossary': ChunkParams('go', 'book'),
'index': ChunkParams('ix', 'book'),
'part': ChunkParams('pt', 'book'),
- 'sect1': ChunkParams('s', 'chapter'),
- 'section': ChunkParams('s', 'chapter'),
+ 'preface': ChunkParams('pr', 'book'),
+ 'refentry': ChunkParams('re', 'book'),
+ 'reference': ChunkParams('rn', 'book'),
+ 'sect1': ChunkParams('s', 'chapter', 1),
+ 'section': ChunkParams('s', 'chapter', 1),
+ 'sect2': ChunkParams('s', 'sect1', DONT_CHUNK),
+ 'sect3': ChunkParams('s', 'sect2', DONT_CHUNK),
+ 'sect4': ChunkParams('s', 'sect3', DONT_CHUNK),
+ 'sect5': ChunkParams('s', 'sect4', DONT_CHUNK),
}
+# TAGS we don't support:
+# 'article', 'bibliography', 'colophon', 'set', 'setindex'
TITLE_XPATHS = {
'_': (etree.XPath('./title'), None),
),
}
-ID_XPATH = etree.XPath('//@id')
+ID_XPATH = etree.XPath('//*[@id]')
+GLOSSENTRY_XPATH = etree.XPath('//glossentry')
+glossary = {}
-def gen_chunk_name(node):
- if 'id' in node.attrib:
- return node.attrib['id']
+footnote_idx = 1
- tag = node.tag
- if tag not in CHUNK_PARAMS:
- CHUNK_PARAMS[tag] = ChunkParams(node.tag[:2])
- logging.warning('Add CHUNK_PARAMS for "%s"', tag)
-
- naming = CHUNK_PARAMS[tag]
- naming.count += 1
- name = ('%s%02d' % (naming.prefix, naming.count))
- # handle parents to make names of nested tags unique
- # TODO: we only need to prepend the parent if there are > 1 of them in the
- # xml
- # while naming.parent:
- # parent = naming.parent
+# nested dict with subkeys:
+# title: textual title
+# tag: chunk tag
+# xml: title xml node
+titles = {}
+
+# files to copy
+assets = set()
+
+
+def encode_entities(text):
+ return text.replace('&', '&').replace('<', '<').replace('>', '>')
+
+
+def raw_text(xml):
+ return etree.tostring(xml, method="text", encoding=str).strip()
+
+
+def gen_chunk_name(node, chunk_params):
+ """Generate a chunk file name
+
+ This is either based on the id or on the position in the doc. In the latter
+ case it uses a prefix from CHUNK_PARAMS and a sequence number for each chunk
+ type.
+ """
+ idval = node.attrib.get('id')
+ if idval is not None:
+ return idval
+
+ name = ('%s%02d' % (chunk_params.prefix, chunk_params.idx))
+ chunk_params.idx += 1
+
+ # handle parents to make names of nested tags like in docbook
+ # - we only need to prepend the parent if there are > 1 of them in the
+ # xml. None, the parents we have are not sufficient, e.g. 'index' can
+ # be in 'book' or 'part' or ... Maybe we can track the chunk_parents
+ # when we chunk explicitly and on each level maintain the 'idx'
+ # while chunk_params.parent:
+ # parent = chunk_params.parent
# if parent not in CHUNK_PARAMS:
# break;
- # naming = CHUNK_PARAMS[parent]
- # name = ('%s%02d' % (naming.prefix, naming.count)) + name
+ # chunk_params = CHUNK_PARAMS[parent]
+ # name = ('%s%02d' % (chunk_params.prefix, chunk_params.idx)) + name
+
+ logging.info('Gen chunk name: "%s"', name)
return name
-def get_chunk_titles(node):
+def get_chunk_titles(module, node):
tag = node.tag
- if tag not in TITLE_XPATHS:
- # Use defaults
- (title, subtitle) = TITLE_XPATHS['_']
- else:
- (title, subtitle) = TITLE_XPATHS[tag]
+ (title, subtitle) = TITLE_XPATHS.get(tag, TITLE_XPATHS['_'])
- xml = title(node)[0]
+ ctx = {
+ 'module': module,
+ 'files': [],
+ }
result = {
- 'title': xml.text
+ 'title': None,
+ 'title_tag': None,
+ 'subtitle': None,
+ 'subtitle_tag': None
}
- if xml.tag != 'title':
- result['title_tag'] = xml.tag
- else:
- result['title_tag'] = tag
+ res = title(node)
+ if res:
+ # handle chunk label for tocs
+ label = node.attrib.get('label')
+ if label:
+ label += '. '
+ else:
+ label = ''
+
+ xml = res[0]
+ # TODO: consider to eval 'title'/'raw_title' lazily
+ result['title'] = label + ''.join(convert_title(ctx, xml))
+ result['raw_title'] = encode_entities(raw_text(xml))
+ if xml.tag != 'title':
+ result['title_tag'] = xml.tag
+ else:
+ result['title_tag'] = tag
if subtitle:
- xml = subtitle(node)[0]
- result['subtitle'] = xml.text
- result['subtitle_tag'] = xml.tag
- else:
- result['subtitle'] = None
- result['subtitle_tag'] = None
+ res = subtitle(node)
+ if res:
+ xml = res[0]
+ result['subtitle'] = ''.join(convert_title(ctx, xml))
+ result['subtitle_tag'] = xml.tag
return result
-def chunk(xml_node, parent=None):
+def chunk(xml_node, module, depth=0, idx=0, parent=None):
"""Chunk the tree.
The first time, we're called with parent=None and in that case we return
- the new_node as the root of the tree
+ the new_node as the root of the tree. For each tree-node we generate a
+ filename and process the children.
"""
- if xml_node.tag in CHUNK_TAGS:
- if parent:
- # remove the xml-node from the parent
- sub_tree = etree.ElementTree(deepcopy(xml_node)).getroot()
- xml_node.getparent().remove(xml_node)
- xml_node = sub_tree
-
- title_args = get_chunk_titles(xml_node)
- chunk_name = gen_chunk_name(xml_node)
- parent = Node(xml_node.tag, parent=parent, xml=xml_node,
- filename=chunk_name + '.html', **title_args)
-
- for child in xml_node:
- chunk(child, parent)
+ tag = xml_node.tag
+ chunk_params = CHUNK_PARAMS.get(tag)
+ if chunk_params:
+ title_args = get_chunk_titles(module, xml_node)
+ chunk_name = gen_chunk_name(xml_node, chunk_params)
+
+ # check idx to handle 'sect1'/'section' special casing and title-only
+ # segments
+ if idx >= chunk_params.min_idx:
+ logging.info('chunk tag: "%s"[%d]', tag, idx)
+ if parent:
+ # remove the xml-node from the parent
+ sub_tree = etree.ElementTree(deepcopy(xml_node)).getroot()
+ xml_node.getparent().remove(xml_node)
+ xml_node = sub_tree
+
+ parent = Node(tag, parent=parent, xml=xml_node, depth=depth,
+ idx=idx,
+ filename=chunk_name + '.html', anchor=None,
+ **title_args)
+ else:
+ parent = Node(tag, parent=parent, xml=xml_node, depth=depth,
+ idx=idx,
+ filename=parent.filename, anchor='#' + chunk_name,
+ **title_args)
+
+ depth += 1
+ idx = 0
+ for child in xml_node:
+ chunk(child, module, depth, idx, parent)
+ if child.tag in CHUNK_PARAMS:
+ idx += 1
return parent
-def add_id_links(files, links):
+def add_id_links_and_titles(files, links):
for node in files:
chunk_name = node.filename[:-5]
chunk_base = node.filename + '#'
- for attr in ID_XPATH(node.xml):
+ for elem in ID_XPATH(node.xml):
+ attr = elem.attrib['id']
if attr == chunk_name:
links[attr] = node.filename
else:
links[attr] = chunk_base + attr
+ title = TITLE_XPATHS.get(elem.tag, TITLE_XPATHS['_'])[0]
+ res = title(elem)
+ if res:
+ xml = res[0]
+ # TODO: consider to eval 'title' lazily
+ titles[attr] = {
+ 'title': encode_entities(raw_text(xml)),
+ 'xml': xml,
+ 'tag': elem.tag,
+ }
+
+
+def build_glossary(files):
+ for node in files:
+ if node.xml.tag != 'glossary':
+ continue
+ for term in GLOSSENTRY_XPATH(node.xml):
+ # TODO: there can be all kind of things in a glossary. This only supports
+ # what we commonly use, glossterm is mandatory
+ key_node = term.find('glossterm')
+ val_node = term.find('glossdef')
+ if key_node is not None and val_node is not None:
+ glossary[raw_text(key_node)] = raw_text(val_node)
+ else:
+ debug = []
+ if key_node is None:
+ debug.append('missing key')
+ if val_node is None:
+ debug.append('missing val')
+ logging.warning('Broken glossentry "%s": %s',
+ term.attrib['id'], ','.join(debug))
+
# conversion helpers
def convert_skip(ctx, xml):
- return ['']
+ return []
+
+
+def append_idref(attrib, result):
+ idval = attrib.get('id')
+ if idval is not None:
+ result.append('<a name="%s"></a>' % idval)
+
+
+def append_text(ctx, text, result):
+ if text and ('no-strip' in ctx or text.strip()):
+ result.append(encode_entities(text))
missing_tags = {}
def convert__unknown(ctx, xml):
# don't recurse on subchunks
- if xml.tag in CHUNK_TAGS:
+ if xml.tag in CHUNK_PARAMS:
return []
- # warn only once
- if xml.tag not in missing_tags:
- logging.warning('Add tag converter for "%s"', xml.tag)
- missing_tags[xml.tag] = True
- result = ['<!-- ' + xml.tag + '-->\n']
- convert_inner(ctx, xml, result)
- result.append('<!-- /' + xml.tag + '-->\n')
- return result
-
-
-def convert_refsect(ctx, xml, h_tag, inner_func=convert_inner):
+ if isinstance(xml, etree._Comment):
+ return ['<!-- ' + xml.text + '-->\n']
+ else:
+ # warn only once
+ if xml.tag not in missing_tags:
+ logging.warning('Add tag converter for "%s"', xml.tag)
+ missing_tags[xml.tag] = True
+ result = ['<!-- ' + xml.tag + '-->\n']
+ convert_inner(ctx, xml, result)
+ result.append('<!-- /' + xml.tag + '-->\n')
+ return result
+
+
+def convert_mediaobject_children(ctx, xml, result):
+ # look for textobject/phrase
+ alt_text = ''
+ textobject = xml.find('textobject')
+ if textobject is not None:
+ phrase = textobject.findtext('phrase')
+ if phrase:
+ alt_text = ' alt="%s"' % phrase
+
+ # look for imageobject/imagedata
+ imageobject = xml.find('imageobject')
+ if imageobject is not None:
+ imagedata = imageobject.find('imagedata')
+ if imagedata is not None:
+ # TODO(ensonic): warn on missing fileref attr?
+ fileref = imagedata.attrib.get('fileref', '')
+ if fileref:
+ assets.add(fileref)
+ result.append('<img src="%s"%s>' % (fileref, alt_text))
+
+
+def convert_sect(ctx, xml, h_tag, inner_func=convert_inner):
result = ['<div class="%s">\n' % xml.tag]
- title = xml.find('title')
- if title is not None:
- if 'id' in xml.attrib:
- result.append('<a name="%s"></a>' % xml.attrib['id'])
- result.append('<%s>%s</%s>' % (h_tag, title.text, h_tag))
- xml.remove(title)
- if xml.text:
- result.append(xml.text)
+ title_tag = xml.find('title')
+ if title_tag is not None:
+ append_idref(xml.attrib, result)
+ result.append('<%s>%s</%s>' % (
+ h_tag, ''.join(convert_title(ctx, title_tag)), h_tag))
+ append_text(ctx, xml.text, result)
inner_func(ctx, xml, result)
result.append('</div>')
- if xml.tail:
- result.append(xml.tail)
+ append_text(ctx, xml.tail, result)
return result
-def xml_get_title(xml):
- title = xml.find('title')
- if title is not None:
- return title.text
+def xml_get_title(ctx, xml):
+ title_tag = xml.find('title')
+ if title_tag is not None:
+ return ''.join(convert_title(ctx, title_tag))
else:
- # TODO(ensonic): any way to get the file (inlcudes) too?
logging.warning('%s: Expected title tag under "%s %s"', xml.sourceline, xml.tag, str(xml.attrib))
return ''
# docbook tags
+
+def convert_abstract(ctx, xml):
+ result = ["""<div class="abstract">
+ <p class="title"><b>Abstract</b></p>"""]
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ result.append('</div>')
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_acronym(ctx, xml):
+ key = xml.text
+ title = glossary.get(key, '')
+ # TODO: print a sensible warning if missing
+ result = ['<acronym title="%s"><span class="acronym">%s</span></acronym>' % (title, key)]
+ if xml.tail:
+ result.append(xml.tail)
+ return result
+
+
+def convert_anchor(ctx, xml):
+ return ['<a name="%s"></a>' % xml.attrib['id']]
+
+
def convert_bookinfo(ctx, xml):
result = ['<div class="titlepage">']
- for releaseinfo in xml.findall('releaseinfo'):
- result.extend(convert_para(ctx, releaseinfo))
+ convert_inner(ctx, xml, result)
result.append("""<hr>
</div>""")
if xml.tail:
def convert_blockquote(ctx, xml):
result = ['<div class="blockquote">\n<blockquote class="blockquote">']
- if xml.text:
- result.append(xml.text)
+ append_text(ctx, xml.text, result)
convert_inner(ctx, xml, result)
result.append('</blockquote>\n</div>')
- if xml.tail:
- result.append(xml.tail)
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_code(ctx, xml):
+ result = ['<code class="%s">' % xml.tag]
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ result.append('</code>')
+ append_text(ctx, xml.tail, result)
return result
def convert_colspec(ctx, xml):
result = ['<col']
- a = xml.attrib
- if 'colname' in a:
- result.append(' class="%s"' % a['colname'])
- if 'colwidth' in a:
- result.append(' width="%s"' % a['colwidth'])
+ colname = xml.attrib.get('colname')
+ if colname is not None:
+ result.append(' class="%s"' % colname)
+ colwidth = xml.attrib.get('colwidth')
+ if colwidth is not None:
+ result.append(' width="%s"' % colwidth)
result.append('>\n')
# is in tgroup and there can be no 'text'
return result
+def convert_command(ctx, xml):
+ result = ['<strong class="userinput"><code>']
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ result.append('</code></strong>')
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_corpauthor(ctx, xml):
+ result = ['<div><h3 class="corpauthor">\n']
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ result.append('</h3></div>\n')
+ append_text(ctx, xml.tail, result)
+ return result
+
+
def convert_div(ctx, xml):
result = ['<div class="%s">\n' % xml.tag]
- if xml.text:
- result.append(xml.text)
+ append_text(ctx, xml.text, result)
convert_inner(ctx, xml, result)
result.append('</div>')
- if xml.tail:
- result.append(xml.tail)
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_emphasis(ctx, xml):
+ role = xml.attrib.get('role')
+ if role is not None:
+ result = ['<span class="%s">' % role]
+ end = '</span>'
+ else:
+ result = ['<span class="emphasis"><em>']
+ end = '</em></span>'
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ result.append(end)
+ append_text(ctx, xml.tail, result)
return result
-def convert_em_class(ctx, xml):
+def convert_em(ctx, xml):
+ result = ['<em class="%s">' % xml.tag]
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ result.append('</em>')
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_em_code(ctx, xml):
result = ['<em class="%s"><code>' % xml.tag]
- if xml.text:
- result.append(xml.text)
+ append_idref(xml.attrib, result)
+ append_text(ctx, xml.text, result)
convert_inner(ctx, xml, result)
result.append('</code></em>')
- if xml.tail:
- result.append(xml.tail)
+ append_text(ctx, xml.tail, result)
return result
def convert_entry(ctx, xml):
- result = ['<td']
- if 'role' in xml.attrib:
- result.append(' class="%s">' % xml.attrib['role'])
+ entry_type = ctx['table.entry']
+ result = ['<' + entry_type]
+ role = xml.attrib.get('role')
+ if role is not None:
+ result.append(' class="%s"' % role)
+ morerows = xml.attrib.get('morerows')
+ if morerows is not None:
+ result.append(' rowspan="%s"' % (1 + int(morerows)))
+ result.append('>')
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ result.append('</' + entry_type + '>')
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_figure(ctx, xml):
+ result = ['<div class="figure">\n']
+ append_idref(xml.attrib, result)
+ title_tag = xml.find('title')
+ if title_tag is not None:
+ # TODO(ensonic): Add a 'Figure X. ' prefix, needs a figure counter
+ result.append('<p><b>%s</b></p>' % ''.join(convert_title(ctx, title_tag)))
+ result.append('<div class="figure-contents">')
+ # TODO(ensonic): title can become alt on inner 'graphic' element
+ convert_inner(ctx, xml, result)
+ result.append('</div></div><br class="figure-break"/>')
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_footnote(ctx, xml):
+ footnotes = ctx.get('footnotes', [])
+ # footnotes idx is not per page, but per doc
+ global footnote_idx
+ idx = footnote_idx
+ footnote_idx += 1
+
+ # need a pair of ids for each footnote (docbook generates different ids)
+ this_id = 'footnote-%d' % idx
+ that_id = 'ftn.' + this_id
+
+ inner = ['<div id="%s" class="footnote">' % that_id]
+ inner.append('<p><a href="#%s" class="para"><sup class="para">[%d] </sup></a>' % (
+ this_id, idx))
+ # TODO(ensonic): this can contain all kind of tags, if we convert them we'll
+ # get double nested paras :/.
+ # convert_inner(ctx, xml, inner)
+ para = xml.find('para')
+ if para is None:
+ para = xml.find('simpara')
+ if para is not None:
+ inner.append(para.text)
else:
- result.append('>')
- if xml.text:
- result.append(xml.text)
+ logging.warning('%s: Unhandled footnote content: %s', xml.sourceline, raw_text(xml))
+ inner.append('</p></div>')
+ footnotes.append(inner)
+ ctx['footnotes'] = footnotes
+ return ['<a href="#%s" class="footnote" name="%s"><sup class="footnote">[%s]</sup></a>' % (
+ that_id, this_id, idx)]
+
+
+def convert_formalpara(ctx, xml):
+ result = None
+ title_tag = xml.find('title')
+ result = ['<p><b>%s</b>' % ''.join(convert_title(ctx, title_tag))]
+ para_tag = xml.find('para')
+ append_text(ctx, para_tag.text, result)
+ convert_inner(ctx, para_tag, result)
+ append_text(ctx, para_tag.tail, result)
+ result.append('</p>')
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_glossdef(ctx, xml):
+ result = ['<dd class="glossdef">']
+ convert_inner(ctx, xml, result)
+ result.append('</dd>\n')
+ return result
+
+
+def convert_glossdiv(ctx, xml):
+ title_tag = xml.find('title')
+ title = title_tag.text
+ xml.remove(title_tag)
+ result = [
+ '<a name="gls%s"></a><h3 class="title">%s</h3>' % (title, title)
+ ]
+ convert_inner(ctx, xml, result)
+ return result
+
+
+def convert_glossentry(ctx, xml):
+ result = []
convert_inner(ctx, xml, result)
- result.append('</td>')
- if xml.tail:
- result.append(xml.tail)
return result
+def convert_glossterm(ctx, xml):
+ glossid = ''
+ text = ''
+ anchor = xml.find('anchor')
+ if anchor is not None:
+ glossid = anchor.attrib.get('id', '')
+ text += anchor.tail or ''
+ text += xml.text or ''
+ if glossid == '':
+ glossid = 'glossterm-' + text
+ return [
+ '<dt><span class="glossterm"><a name="%s"></a>%s</span></dt>' % (
+ glossid, text)
+ ]
+
+
+def convert_graphic(ctx, xml):
+ # TODO(ensonic): warn on missing fileref attr?
+ fileref = xml.attrib.get('fileref', '')
+ if fileref:
+ assets.add(fileref)
+ return ['<div><img src="%s"></div>' % fileref]
+
+
def convert_indexdiv(ctx, xml):
title_tag = xml.find('title')
title = title_tag.text
def convert_informaltable(ctx, xml):
result = ['<div class="informaltable"><table class="informaltable"']
- a = xml.attrib
- if 'pgwide' in a and a['pgwide'] == '1':
+ if xml.attrib.get('pgwide') == '1':
result.append(' width="100%"')
- if 'frame' in a and a['frame'] == 'none':
+ if xml.attrib.get('frame') == 'none':
result.append(' border="0"')
result.append('>\n')
convert_inner(ctx, xml, result)
return result
+def convert_inlinegraphic(ctx, xml):
+ # TODO(ensonic): warn on missing fileref attr?
+ fileref = xml.attrib.get('fileref', '')
+ if fileref:
+ assets.add(fileref)
+ return ['<img src="%s">' % fileref]
+
+
+def convert_inlinemediaobject(ctx, xml):
+ result = ['<span class="inlinemediaobject">']
+ # no PCDATA allowed here
+ convert_mediaobject_children(ctx, xml, result)
+ result.append('</span>')
+ append_text(ctx, xml.tail, result)
+ return result
+
+
def convert_itemizedlist(ctx, xml):
result = ['<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">']
convert_inner(ctx, xml, result)
def convert_link(ctx, xml):
linkend = xml.attrib['linkend']
- if linkend in fixxref.NoLinks:
- linkend = None
result = []
if linkend:
link_text = []
+ append_text(ctx, xml.text, link_text)
convert_inner(ctx, xml, link_text)
- if xml.text:
- link_text.append(xml.text)
- # TODO: fixxref does some weird checks in xml.text
- result = [fixxref.MakeXRef(ctx['module'], '', 0, linkend, ''.join(link_text))]
- if xml.tail:
- result.append(xml.tail)
+ text = ''.join(link_text)
+
+ (tid, href) = fixxref.GetXRef(linkend)
+ if href:
+ title_attr = ''
+ title = titles.get(tid)
+ if title:
+ title_attr = ' title="%s"' % title['title']
+
+ href = fixxref.MakeRelativeXRef(ctx['module'], href)
+ result = ['<a href="%s"%s>%s</a>' % (href, title_attr, text)]
+ else:
+ # TODO: filename is for the output and xml.sourceline is on the masterdoc ...
+ fixxref.ReportBadXRef(ctx['node'].filename, 0, linkend, text)
+ result = [text]
+ else:
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ append_text(ctx, xml.tail, result)
return result
result = ['<li class="listitem">']
convert_inner(ctx, xml, result)
result.append('</li>')
- # is in itemizedlist and there can be no 'text'
+ # no PCDATA allowed here, is in itemizedlist
return result
-def convert_literal(ctx, xml):
- result = ['<code class="%s">' % xml.tag]
- if xml.text:
- result.append(xml.text)
+def convert_literallayout(ctx, xml):
+ result = ['<div class="literallayout"><p><br>\n']
+ append_text(ctx, xml.text, result)
convert_inner(ctx, xml, result)
- result.append('</code>')
- if xml.tail:
- result.append(xml.tail)
+ result.append('</p></div>')
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_mediaobject(ctx, xml):
+ result = ['<div class="mediaobject">\n']
+ # no PCDATA allowed here
+ convert_mediaobject_children(ctx, xml, result)
+ result.append('</div>')
+ append_text(ctx, xml.tail, result)
return result
def convert_orderedlist(ctx, xml):
- result = ['<div class="orderedlistlist"><ol class="orderedlistlist" type="1">']
+ result = ['<div class="orderedlist"><ol class="orderedlist" type="1">']
convert_inner(ctx, xml, result)
result.append('</ol></div>')
- if xml.tail:
- result.append(xml.tail)
+ append_text(ctx, xml.tail, result)
return result
def convert_para(ctx, xml):
- result = ['<p>']
- if xml.tag != 'para':
- result = ['<p class="%s">' % xml.tag]
- if xml.text:
- result.append(xml.text)
+ result = []
+ role = xml.attrib.get('role')
+ if role is not None:
+ result.append('<p class="%s">' % role)
+ else:
+ result.append('<p>')
+ append_idref(xml.attrib, result)
+ append_text(ctx, xml.text, result)
convert_inner(ctx, xml, result)
result.append('</p>')
- if xml.tail:
- result.append(xml.tail)
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_para_like(ctx, xml):
+ result = []
+ append_idref(xml.attrib, result)
+ result.append('<p class="%s">' % xml.tag)
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ result.append('</p>')
+ append_text(ctx, xml.tail, result)
return result
def convert_phrase(ctx, xml):
result = ['<span']
- if 'role' in xml.attrib:
- result.append(' class="%s">' % xml.attrib['role'])
+ role = xml.attrib.get('role')
+ if role is not None:
+ result.append(' class="%s">' % role)
else:
result.append('>')
- if xml.text:
- result.append(xml.text)
+ append_text(ctx, xml.text, result)
convert_inner(ctx, xml, result)
result.append('</span>')
- if xml.tail:
- result.append(xml.tail)
+ append_text(ctx, xml.tail, result)
return result
def convert_pre(ctx, xml):
- result = ['<pre class="%s">\n' % xml.tag]
- if xml.text:
- result.append(xml.text)
+ # Since we're inside <pre> don't skip newlines
+ ctx['no-strip'] = True
+ result = ['<pre class="%s">' % xml.tag]
+ append_text(ctx, xml.text, result)
convert_inner(ctx, xml, result)
result.append('</pre>')
- if xml.tail:
- result.append(xml.tail)
+ del ctx['no-strip']
+ append_text(ctx, xml.tail, result)
return result
result = []
if xml.attrib.get('role', '') == 'example':
if xml.text:
- # TODO: check 'language' attr and use respective lexer
- highlighted = highlight(xml.text, LEXER, HTML_FORMATTER)
-
- # we do own line-numbering
- line_count = highlighted.count('\n')
- source_lines = '\n'.join([str(i) for i in range(1, line_count + 1)])
- result.append("""<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
+ lang = xml.attrib.get('language', ctx['src-lang']).lower()
+ if lang not in LEXERS:
+ LEXERS[lang] = get_lexer_by_name(lang)
+ lexer = LEXERS.get(lang, None)
+ if lexer:
+ highlighted = highlight(xml.text, lexer, HTML_FORMATTER)
+
+ # we do own line-numbering
+ line_count = highlighted.count('\n')
+ source_lines = '\n'.join([str(i) for i in range(1, line_count + 1)])
+ result.append("""<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>%s</pre></td>
</tbody>
</table>
""" % (source_lines, highlighted))
+ else:
+ logging.warn('No pygments lexer for language="%s"', lang)
+ result.append('<pre class="programlisting">')
+ result.append(xml.text)
+ result.append('</pre>')
else:
result.append('<pre class="programlisting">')
- if xml.text:
- result.append(xml.text)
+ append_text(ctx, xml.text, result)
convert_inner(ctx, xml, result)
result.append('</pre>')
- if xml.tail:
- result.append(xml.tail)
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_quote(ctx, xml):
+ result = ['<span class="quote">"<span class="quote">']
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ result.append('</span>"</span>')
+ append_text(ctx, xml.tail, result)
return result
result.append('<hr>\n')
result.extend(convert_tags.get(child.tag, convert__unknown)(ctx, child))
prev = child
- return convert_refsect(ctx, xml, 'h2', convert_inner)
+ return convert_sect(ctx, xml, 'h2', convert_inner)
def convert_refsect2(ctx, xml):
- return convert_refsect(ctx, xml, 'h3')
+ return convert_sect(ctx, xml, 'h3')
def convert_refsect3(ctx, xml):
- return convert_refsect(ctx, xml, 'h4')
+ return convert_sect(ctx, xml, 'h4')
def convert_row(ctx, xml):
return result
+def convert_sbr(ctx, xml):
+ return ['<br>']
+
+
+def convert_sect1_tag(ctx, xml):
+ return convert_sect(ctx, xml, 'h2')
+
+
+def convert_sect2(ctx, xml):
+ return convert_sect(ctx, xml, 'h3')
+
+
+def convert_sect3(ctx, xml):
+ return convert_sect(ctx, xml, 'h4')
+
+
def convert_simpara(ctx, xml):
result = ['<p>']
- if xml.text:
- result.append(xml.text)
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
result.append('</p>')
- if xml.tail:
- result.append(xml.tail)
+ append_text(ctx, xml.tail, result)
return result
def convert_span(ctx, xml):
result = ['<span class="%s">' % xml.tag]
- if xml.text:
- result.append(xml.text)
+ append_text(ctx, xml.text, result)
convert_inner(ctx, xml, result)
result.append('</span>')
- if xml.tail:
- result.append(xml.tail)
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_table(ctx, xml):
+ result = ['<div class="table">']
+ append_idref(xml.attrib, result)
+ title_tag = xml.find('title')
+ if title_tag is not None:
+ result.append('<p class="title"><b>')
+ # TODO(ensonic): Add a 'Table X. ' prefix, needs a table counter
+ result.extend(convert_title(ctx, title_tag))
+ result.append('</b></p>')
+ result.append('<div class="table-contents"><table class="table" summary="g_object_new" border="1">')
+
+ convert_inner(ctx, xml, result)
+
+ result.append('</table></div></div>')
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_tag(ctx, xml):
+ classval = xml.attrib.get('class')
+ if classval is not None:
+ result = ['<code class="sgmltag-%s">' % classval]
+ else:
+ result = ['<code>']
+ append_text(ctx, xml.text, result)
+ result.append('</code>')
+ append_text(ctx, xml.tail, result)
return result
def convert_tbody(ctx, xml):
result = ['<tbody>']
+ ctx['table.entry'] = 'td'
convert_inner(ctx, xml, result)
result.append('</tbody>')
# is in tgroup and there can be no 'text'
return result
+def convert_thead(ctx, xml):
+ result = ['<thead>']
+ ctx['table.entry'] = 'th'
+ convert_inner(ctx, xml, result)
+ result.append('</thead>')
+ # is in tgroup and there can be no 'text'
+ return result
+
+
+def convert_title(ctx, xml):
+ # This is always explicitly called from some context
+ result = []
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ append_text(ctx, xml.tail, result)
+ return result
+
+
def convert_ulink(ctx, xml):
- result = ['<a class="%s" href="%s">%s</a>' % (xml.tag, xml.attrib['url'], xml.text)]
- if xml.tail:
- result.append(xml.tail)
+ if xml.text:
+ result = ['<a class="%s" href="%s">%s</a>' % (xml.tag, xml.attrib['url'], xml.text)]
+ else:
+ url = xml.attrib['url']
+ result = ['<a class="%s" href="%s">%s</a>' % (xml.tag, url, url)]
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_userinput(ctx, xml):
+ result = ['<span class="command"><strong>']
+ append_text(ctx, xml.text, result)
+ convert_inner(ctx, xml, result)
+ result.append('</strong></span>')
+ append_text(ctx, xml.tail, result)
+ return result
+
+
+def convert_variablelist(ctx, xml):
+ result = ["""<div class="variablelist"><table border="0" class="variablelist">
+<colgroup>
+<col align="left" valign="top">
+<col>
+</colgroup>
+<tbody>"""]
+ convert_inner(ctx, xml, result)
+ result.append("""</tbody>
+</table></div>""")
+ return result
+
+
+def convert_varlistentry(ctx, xml):
+ result = ['<tr>']
+
+ result.append('<td><p>')
+ term = xml.find('term')
+ result.extend(convert_span(ctx, term))
+ result.append('</p></td>')
+
+ result.append('<td>')
+ listitem = xml.find('listitem')
+ convert_inner(ctx, listitem, result)
+ result.append('</td>')
+
+ result.append('<tr>')
+ return result
+
+
+def convert_xref(ctx, xml):
+ result = []
+ linkend = xml.attrib['linkend']
+ (tid, href) = fixxref.GetXRef(linkend)
+ try:
+ title = titles[tid]
+ # all sectN need to become 'section
+ tag = title['tag']
+ tag = {
+ 'sect1': 'section',
+ 'sect2': 'section',
+ 'sect3': 'section',
+ 'sect4': 'section',
+ 'sect5': 'section',
+ }.get(tag, tag)
+ result = [
+ '<a class="xref" href="%s" title="%s">the %s called “%s”</a>' %
+ (href, title['title'], tag, ''.join(convert_title(ctx, title['xml'])))
+ ]
+ except KeyError:
+ logging.warning('invalid linkend "%s"', tid)
+
+ append_text(ctx, xml.tail, result)
return result
# TODO(ensonic): turn into class with converters as functions and ctx as self
convert_tags = {
+ 'abstract': convert_abstract,
+ 'acronym': convert_acronym,
+ 'anchor': convert_anchor,
+ 'application': convert_span,
'bookinfo': convert_bookinfo,
'blockquote': convert_blockquote,
+ 'classname': convert_code,
+ 'caption': convert_div,
+ 'code': convert_code,
'colspec': convert_colspec,
+ 'constant': convert_code,
+ 'command': convert_command,
+ 'corpauthor': convert_corpauthor,
+ 'emphasis': convert_emphasis,
'entry': convert_entry,
- 'function': convert_span,
+ 'envar': convert_code,
+ 'footnote': convert_footnote,
+ 'figure': convert_figure,
+ 'filename': convert_code,
+ 'firstterm': convert_em,
+ 'formalpara': convert_formalpara,
+ 'function': convert_code,
+ 'glossdef': convert_glossdef,
+ 'glossdiv': convert_glossdiv,
+ 'glossentry': convert_glossentry,
+ 'glossterm': convert_glossterm,
+ 'graphic': convert_graphic,
'indexdiv': convert_indexdiv,
'indexentry': convert_ignore,
'indexterm': convert_skip,
'informalexample': convert_div,
'informaltable': convert_informaltable,
+ 'inlinegraphic': convert_inlinegraphic,
+ 'inlinemediaobject': convert_inlinemediaobject,
+ 'interfacename': convert_code,
'itemizedlist': convert_itemizedlist,
+ 'legalnotice': convert_div,
'link': convert_link,
'listitem': convert_listitem,
- 'literal': convert_literal,
+ 'literal': convert_code,
+ 'literallayout': convert_literallayout,
+ 'mediaobject': convert_mediaobject,
'note': convert_div,
+ 'option': convert_code,
'orderedlist': convert_orderedlist,
'para': convert_para,
- 'parameter': convert_em_class,
+ 'partintro': convert_div,
+ 'parameter': convert_em_code,
'phrase': convert_phrase,
'primaryie': convert_primaryie,
'programlisting': convert_programlisting,
- 'releaseinfo': convert_para,
+ 'quote': convert_quote,
+ 'releaseinfo': convert_para_like,
'refsect1': convert_refsect1,
'refsect2': convert_refsect2,
'refsect3': convert_refsect3,
+ 'replaceable': convert_em_code,
'returnvalue': convert_span,
'row': convert_row,
+ 'sbr': convert_sbr,
'screen': convert_pre,
+ 'section': convert_sect2, # FIXME: need tracking of nesting
+ 'sect1': convert_sect1_tag,
+ 'sect2': convert_sect2,
+ 'sect3': convert_sect3,
'simpara': convert_simpara,
- 'structfield': convert_em_class,
+ 'simplesect': convert_sect2, # FIXME: need tracking of nesting
+ 'structfield': convert_em_code,
+ 'structname': convert_span,
+ 'synopsis': convert_pre,
+ 'symbol': convert_span,
+ 'table': convert_table,
+ 'tag': convert_tag,
'tbody': convert_tbody,
+ 'term': convert_span,
'tgroup': convert_tgroup,
+ 'thead': convert_thead,
+ 'title': convert_skip,
'type': convert_span,
'ulink': convert_ulink,
+ 'userinput': convert_userinput,
+ 'varname': convert_code,
+ 'variablelist': convert_variablelist,
+ 'varlistentry': convert_varlistentry,
'warning': convert_div,
+ 'xref': convert_xref,
}
# conversion helpers
def generate_head_links(ctx):
n = ctx['nav_home']
result = [
- '<link rel="home" href="%s" title="%s">\n' % (n.filename, n.title)
+ '<link rel="home" href="%s" title="%s">\n' % (n.filename, n.raw_title)
]
- if 'nav_up' in ctx:
- n = ctx['nav_up']
- result.append('<link rel="up" href="%s" title="%s">\n' % (n.filename, n.title))
- if 'nav_prev' in ctx:
- n = ctx['nav_prev']
- result.append('<link rel="prev" href="%s" title="%s">\n' % (n.filename, n.title))
- if 'nav_next' in ctx:
- n = ctx['nav_next']
- result.append('<link rel="next" href="%s" title="%s">\n' % (n.filename, n.title))
+
+ n = ctx.get('nav_up')
+ if n is not None:
+ result.append('<link rel="up" href="%s" title="%s">\n' % (n.filename, n.raw_title))
+
+ n = ctx.get('nav_prev')
+ if n is not None:
+ result.append('<link rel="prev" href="%s" title="%s">\n' % (n.filename, n.raw_title))
+
+ n = ctx.get('nav_next')
+ if n is not None:
+ result.append('<link rel="next" href="%s" title="%s">\n' % (n.filename, n.raw_title))
+
return ''.join(result)
result = [
'<td><a accesskey="h" href="%s"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>' % n.filename
]
- if 'nav_up' in ctx:
- n = ctx['nav_up']
+
+ n = ctx.get('nav_up')
+ if n is not None:
result.append(
'<td><a accesskey="u" href="%s"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>' % n.filename)
else:
result.append('<td><img src="up-insensitive.png" width="16" height="16" border="0"></td>')
- if 'nav_prev' in ctx:
- n = ctx['nav_prev']
+
+ n = ctx.get('nav_prev')
+ if n is not None:
result.append(
'<td><a accesskey="p" href="%s"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>' % n.filename)
else:
result.append('<td><img src="left-insensitive.png" width="16" height="16" border="0"></td>')
- if 'nav_next' in ctx:
- n = ctx['nav_next']
+
+ n = ctx.get('nav_next')
+ if n is not None:
result.append(
'<td><a accesskey="n" href="%s"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>' % n.filename)
else:
result = []
for c in node.children:
# TODO: urlencode the filename: urllib.parse.quote_plus()
+ link = c.filename
+ if c.anchor:
+ link += c.anchor
result.append('<dt><span class="%s"><a href="%s">%s</a></span>\n' % (
- c.title_tag, c.filename, c.title))
+ c.title_tag, link, c.title))
if c.subtitle:
result.append('<span class="%s"> — %s</span>' % (c.subtitle_tag, c.subtitle))
result.append('</dt>\n')
""" % generate_nav_links(ctx)
-def generate_index_nav(ctx, indexdivs):
+def generate_alpha_nav(ctx, divs, prefix, span_id):
ix_nav = []
- for s in indexdivs:
- title = xml_get_title(s)
- ix_nav.append('<a class="shortcut" href="#idx%s">%s</a>' % (title, title))
+ for s in divs:
+ title = xml_get_title(ctx, s)
+ ix_nav.append('<a class="shortcut" href="#%s%s">%s</a>' % (prefix, title, title))
return """<table class="navigation" id="top" width="100%%" cellpadding="2" cellspacing="5">
<tr valign="middle">
<td width="100%%" align="left" class="shortcuts">
- <span id="nav_index">
+ <span id="nav_%s">
%s
</span>
</td>
%s
</tr>
</table>
- """ % ('\n<span class="dim">|</span>\n'.join(ix_nav), generate_nav_links(ctx))
+ """ % (span_id, '\n<span class="dim">|</span>\n'.join(ix_nav), generate_nav_links(ctx))
def generate_refentry_nav(ctx, refsect1s, result):
- result.append("""<table class="navigation" id="top" width="100%%" cellpadding="2" cellspacing="5">
+ result.append("""<table class="navigation" id="top" width="100%" cellpadding="2" cellspacing="5">
<tr valign="middle">
- <td width="100%%" align="left" class="shortcuts">
+ <td width="100%" align="left" class="shortcuts">
<a href="#" class="shortcut">Top</a>""")
for s in refsect1s:
# don't list TOC sections (role="xxx_proto")
if s.attrib.get('role', '').endswith("_proto"):
continue
+ # skip section without 'id' attrs
+ ref_id = s.attrib.get('id')
+ if ref_id is None:
+ continue
+
+ # skip foreign sections
+ if '.' not in ref_id:
+ continue
+
+ title = xml_get_title(ctx, s)
+ span_id = ref_id.split('.')[1].replace('-', '_')
- title = xml_get_title(s)
result.append("""
- <span id="nav_description">
- <span class="dim">|</span>
+ <span id="nav_%s">
+ <span class="dim">|</span>
<a href="#%s" class="shortcut">%s</a>
- </span>""" % (s.attrib['id'], title))
+ </span>
+ """ % (span_id, ref_id, title))
result.append("""
</td>
%s
""" % generate_nav_links(ctx))
-def get_id(node):
- xml = node.xml
- node_id = xml.attrib.get('id', None)
- if node_id:
- return node_id
+def generate_footer(ctx):
+ footnotes = ctx.get('footnotes')
+ if footnotes is None:
+ return []
+
+ result = ["""<div class="footnotes">\n
+<br><hr style="width:100; text-align:left;margin-left: 0">
+"""]
+ for f in footnotes:
+ result.extend(f)
+ result.append('</div>\n')
+ return result
- logging.warning('%d: No "id" attribute on "%s"', xml.sourceline, xml.tag)
+
+def get_id_path(node):
+ """ Generate the 'id'.
+ We need to walk up the xml-tree and check the positions for each sibling.
+ When reaching the top of the tree we collect remaining index entries from
+ the chunked-tree.
+ """
ix = []
- # Generate the 'id'. We need to walk up the xml-tree and check the positions
- # for each sibling.
+ xml = node.xml
parent = xml.getparent()
while parent is not None:
children = parent.getchildren()
ix.insert(0, str(children.index(xml) + 1))
xml = parent
parent = xml.getparent()
+ while node is not None:
+ ix.insert(0, str(node.idx + 1))
+ node = node.parent
+
+ return ix
+
+
+def get_id(node):
+ xml = node.xml
+ node_id = xml.attrib.get('id', None)
+ if node_id:
+ return node_id
+
+ # TODO: this is moot if nothing links to it, we could also consider to omit
+ # the <a name="$id"></a> tag.
+ logging.info('%d: No "id" attribute on "%s", generating one',
+ xml.sourceline, xml.tag)
+ ix = get_id_path(node)
# logging.warning('%s: id indexes: %s', node.filename, str(ix))
- return 'id-1.' + '.'.join(ix)
+ return 'id-' + '.'.join(ix)
+
+
+def convert_chunk_with_toc(ctx, div_class, title_tag):
+ node = ctx['node']
+ result = [
+ HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)),
+ generate_basic_nav(ctx),
+ '<div class="%s">' % div_class,
+ ]
+ if node.title:
+ result.append("""
+<div class="titlepage">
+<%s class="title"><a name="%s"></a>%s</%s>
+</div>""" % (
+ title_tag, get_id(node), node.title, title_tag))
+
+ toc = generate_toc(ctx, node)
+ if toc:
+ # TODO: not all docbook page types use this extra heading
+ result.append("""<p><b>Table of Contents</b></p>
+ <div class="toc">
+ <dl class="toc">
+ """)
+ result.extend(toc)
+ result.append("""</dl>
+ </div>
+ """)
+ convert_inner(ctx, node.xml, result)
+ result.extend(generate_footer(ctx))
+ result.append("""</div>
+</body>
+</html>""")
+ return result
# docbook chunks
result.extend(generate_toc(ctx, node.root))
result.append("""</dl>
</div>
-</div>
+""")
+ result.extend(generate_footer(ctx))
+ result.append("""</div>
</body>
</html>""")
return result
def convert_chapter(ctx):
+ return convert_chunk_with_toc(ctx, 'chapter', 'h2')
+
+
+def convert_glossary(ctx):
node = ctx['node']
+ glossdivs = node.xml.findall('glossdiv')
+
result = [
HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)),
- generate_basic_nav(ctx),
- '<div class="chapter">',
+ generate_alpha_nav(ctx, glossdivs, 'gls', 'glossary'),
+ """<div class="glossary">
+<div class="titlepage"><h%1d class="title">
+<a name="%s"></a>%s</h%1d>
+</div>""" % (node.depth, get_id(node), node.title, node.depth)
]
- title = node.xml.find('title')
- if title is not None:
- result.append('<div class="titlepage"><h1 class="title"><a name="%s"></a>%s</h1></div>' % (
- get_id(node), title.text))
- node.xml.remove(title)
- convert_inner(ctx, node.xml, result)
- result.append("""<div class="toc">
- <dl class="toc">
-""")
- result.extend(generate_toc(ctx, node))
- result.append("""</dl>
-</div>
-</div>
+ for i in glossdivs:
+ result.extend(convert_glossdiv(ctx, i))
+ result.extend(generate_footer(ctx))
+ result.append("""</div>
</body>
</html>""")
return result
def convert_index(ctx):
node = ctx['node']
- node_id = get_id(node)
# Get all indexdivs under indexdiv
indexdivs = node.xml.find('indexdiv').findall('indexdiv')
result = [
HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)),
- generate_index_nav(ctx, indexdivs),
+ generate_alpha_nav(ctx, indexdivs, 'idx', 'index'),
"""<div class="index">
-<div class="titlepage"><h1 class="title">
-<a name="%s"></a>%s</h1>
-</div>""" % (node_id, node.title)
+<div class="titlepage"><h%1d class="title">
+<a name="%s"></a>%s</h%1d>
+</div>""" % (node.depth, get_id(node), node.title, node.depth)
]
for i in indexdivs:
result.extend(convert_indexdiv(ctx, i))
+ result.extend(generate_footer(ctx))
result.append("""</div>
</body>
</html>""")
return result
+def convert_part(ctx):
+ return convert_chunk_with_toc(ctx, 'part', 'h1')
+
+
+def convert_preface(ctx):
+ node = ctx['node']
+ result = [
+ HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)),
+ generate_basic_nav(ctx),
+ '<div class="preface">'
+ ]
+ if node.title:
+ result.append("""
+<div class="titlepage">
+<h2 class="title"><a name="%s"></a>%s</h2>
+</div>""" % (get_id(node), node.title))
+ convert_inner(ctx, node.xml, result)
+ result.extend(generate_footer(ctx))
+ result.append("""</div>
+</body>
+</html>""")
+ return result
+
+
+def convert_reference(ctx):
+ return convert_chunk_with_toc(ctx, 'reference', 'h1')
+
+
def convert_refentry(ctx):
node = ctx['node']
node_id = get_id(node)
refsect1s = node.xml.findall('refsect1')
+ gallery = ''
+ refmeta = node.xml.find('refmeta')
+ if refmeta is not None:
+ refmiscinfo = refmeta.find('refmiscinfo')
+ if refmiscinfo is not None:
+ inlinegraphic = refmiscinfo.find('inlinegraphic')
+ if inlinegraphic is not None:
+ gallery = ''.join(convert_inlinegraphic(ctx, inlinegraphic))
+
result = [
HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx))
]
<table width="100%%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="%s.top_of_page"></a>%s</span></h2>
- <p>%s — module for gtk-doc unit test</p>
+ <p>%s — %s</p>
</td>
- <td class="gallery_image" valign="top" align="right"></td>
+ <td class="gallery_image" valign="top" align="right">%s</td>
</tr></table>
</div>
-""" % (node_id, node_id, node.title, node.title))
+""" % (node_id, node_id, node.title, node.title, node.subtitle, gallery))
for s in refsect1s:
result.extend(convert_refsect1(ctx, s))
+ result.extend(generate_footer(ctx))
result.append("""</div>
</body>
</html>""")
return result
+def convert_section(ctx):
+ return convert_chunk_with_toc(ctx, 'section', 'h2')
+
+
+def convert_sect1(ctx):
+ return convert_chunk_with_toc(ctx, 'sect1', 'h2')
+
+
# TODO(ensonic): turn into class with converters as functions and ctx as self
convert_chunks = {
'book': convert_book,
'chapter': convert_chapter,
+ 'glossary': convert_glossary,
'index': convert_index,
+ 'part': convert_part,
+ 'preface': convert_preface,
+ 'reference': convert_reference,
'refentry': convert_refentry,
+ 'section': convert_section,
+ 'sect1': convert_sect1,
}
return nav
-def convert(out_dir, module, files, node):
+def convert(out_dir, module, files, node, src_lang):
"""Convert the docbook chunks to a html file.
Args:
"""
logging.info('Writing: %s', node.filename)
- with open(os.path.join(out_dir, node.filename), 'wt') as html:
+ with open(os.path.join(out_dir, node.filename), 'wt',
+ newline='\n', encoding='utf-8') as html:
ctx = {
'module': module,
'files': files,
'node': node,
+ 'src-lang': src_lang,
}
ctx.update(generate_nav_nodes(files, node))
- if node.name in convert_chunks:
- for line in convert_chunks[node.name](ctx):
+ converter = convert_chunks.get(node.name)
+ if converter is not None:
+ for line in converter(ctx):
html.write(line)
else:
- logging.warning('Add converter/template for "%s"', node.name)
+ logging.warning('Add chunk converter for "%s"', node.name)
def create_devhelp2_toc(node):
result = []
for c in node.children:
if c.children:
- result.append('<sub name="%s" link="%s">\n' % (c.title, c.filename))
+ result.append('<sub name="%s" link="%s">\n' % (c.raw_title, c.filename))
result.extend(create_devhelp2_toc(c))
result.append('</sub>\n')
else:
- result.append('<sub name="%s" link="%s"/>\n' % (c.title, c.filename))
+ result.append('<sub name="%s" link="%s"/>\n' % (c.raw_title, c.filename))
return result
def create_devhelp2_condition_attribs(node):
- if 'condition' in node.attrib:
+ condition = node.attrib.get('condition')
+ if condition is not None:
# condition -> since, deprecated, ... (separated with '|')
- cond = node.attrib['condition'].replace('"', '"').split('|')
- return' ' + ' '.join(['%s="%s"' % tuple(c.split(':', 1)) for c in cond])
+ cond = condition.replace('"', '"').split('|')
+ keywords = []
+ for c in cond:
+ if ':' in c:
+ keywords.append('{}="{}"'.format(*c.split(':', 1)))
+ else:
+ # deprecated can have no description
+ keywords.append('{}="{}"'.format(c, ''))
+ return ' ' + ' '.join(keywords)
else:
return ''
def create_devhelp2_refsect2_keyword(node, base_link):
+ node_id = node.attrib['id']
return' <keyword type="%s" name="%s" link="%s"%s/>\n' % (
- node.attrib['role'], xml_get_title(node), base_link + node.attrib['id'],
+ node.attrib['role'], titles[node_id]['title'], base_link + node_id,
create_devhelp2_condition_attribs(node))
def create_devhelp2(out_dir, module, xml, files):
- with open(os.path.join(out_dir, module + '.devhelp2'), 'wt') as idx:
+ with open(os.path.join(out_dir, module + '.devhelp2'), 'wt',
+ newline='\n', encoding='utf-8') as idx:
bookinfo_nodes = xml.xpath('/book/bookinfo')
title = ''
if bookinfo_nodes is not None:
return (gtkdocdir, styledir)
-def main(module, index_file, out_dir, uninstalled):
+def main(module, index_file, out_dir, uninstalled, src_lang, paths):
+
+ # == Loading phase ==
+ # the next 3 steps could be done in paralel
+
+ # 1) load the docuemnt
+ _t = timer()
+ # does not seem to be faster
+ # parser = etree.XMLParser(dtd_validation=False, collect_ids=False)
+ # tree = etree.parse(index_file, parser)
tree = etree.parse(index_file)
+ logging.warning("1a: %7.3lf: load doc", timer() - _t)
+ _t = timer()
tree.xinclude()
+ logging.warning("1b: %7.3lf: xinclude doc", timer() - _t)
+ # 2) copy datafiles
+ _t = timer()
+ # TODO: handle additional images
(gtkdocdir, styledir) = get_dirs(uninstalled)
# copy navigation images and stylesheets to html directory ...
css_file = os.path.join(styledir, 'style.css')
for f in glob(os.path.join(styledir, '*.png')) + [css_file]:
shutil.copy(f, out_dir)
css_file = os.path.join(out_dir, 'style.css')
- with open(css_file, 'at') as css:
+ with open(css_file, 'at', newline='\n', encoding='utf-8') as css:
css.write(HTML_FORMATTER.get_style_defs())
+ logging.warning("2: %7.3lf: copy datafiles", timer() - _t)
+ # 3) load xref targets
+ _t = timer()
# TODO: migrate options from fixxref
- # TODO: do in parallel with loading the xml above.
+ # TODO: ideally explicity specify the files we need, this will save us the
+ # globbing and we'll load less files.
fixxref.LoadIndicies(out_dir, '/usr/share/gtk-doc/html', [])
-
- # We do multiple passes:
- # 1) recursively walk the tree and chunk it into a python tree so that we
- # can generate navigation and link tags.
- files = chunk(tree.getroot())
- files = list(PreOrderIter(files))
- # 2) find all 'id' attribs and add them to the link map
- add_id_links(files, fixxref.Links)
- # 3) create a xxx.devhelp2 file, do this before 3), since we modify the tree
+ logging.warning("3: %7.3lf: load xrefs", timer() - _t)
+
+ # == Processing phase ==
+
+ # 4) recursively walk the tree and chunk it into a python tree so that we
+ # can generate navigation and link tags.
+ _t = timer()
+ files = chunk(tree.getroot(), module)
+ files = [f for f in PreOrderIter(files) if f.anchor is None]
+ logging.warning("4: %7.3lf: chunk doc", timer() - _t)
+
+ # 5) extract tables:
+ _t = timer()
+ # TODO: can be done in parallel
+ # - find all 'id' attribs and add them to the link map
+ # - .. get their titles and store them into the titles map
+ add_id_links_and_titles(files, fixxref.Links)
+ # - build glossary dict
+ build_glossary(files)
+ logging.warning("5: %7.3lf: extract tables", timer() - _t)
+
+ # == Output phase ==
+ # the next two step could be done in parllel
+
+ # 6) create a xxx.devhelp2 file
+ _t = timer()
create_devhelp2(out_dir, module, tree.getroot(), files)
- # 4) iterate the tree and output files
- # TODO: use multiprocessing
+ logging.warning("6: %7.3lf: create devhelp2", timer() - _t)
+
+ # 7) iterate the tree and output files
+ _t = timer()
+ # TODO: can be done in parallel, figure out why this is not faster
+ # from multiprocessing.pool import Pool
+ # with Pool(4) as p:
+ # p.apply_async(convert, args=(out_dir, module, files))
+ # from multiprocessing.pool import ThreadPool
+ # with ThreadPool(4) as p:
+ # p.apply_async(convert, args=(out_dir, module, files))
for node in files:
- convert(out_dir, module, files, node)
+ convert(out_dir, module, files, node, src_lang)
+ logging.warning("7: %7.3lf: create html", timer() - _t)
+
+ # 8) copy assets over
+ _t = timer()
+ paths = set(paths + [os.getcwd()])
+ for a in assets:
+ logging.info('trying %s in %s', a, str(paths))
+ copied = False
+ for p in paths:
+ try:
+ shutil.copy(os.path.join(p, a), out_dir)
+ copied = True
+ except FileNotFoundError:
+ pass
+ if not copied:
+ logging.warning('file %s not found in path (did you add --path?)', a)
+ logging.warning("8: %7.3lf: copy assets", timer() - _t)
def run(options):
if e.errno != errno.EEXIST:
raise
- sys.exit(main(module, document, out_dir, options.uninstalled))
+ sys.exit(main(module, document, out_dir, options.uninstalled, options.src_lang,
+ options.path))
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
-# Support both Python 2 and 3
-from __future__ import print_function
-
import logging
import os
import sys
The rebase tool rewrites URI references in installed HTML documentation.
"""
-from __future__ import print_function
-from six import iteritems, iterkeys
-
import logging
import os
import re
if onlinedir and entry == "index.sgml":
log(options, "Reading index from index.sgml")
- onlinedir = ReadIndex(dir, entry)
+ onlinedir = ReadIndex(scan_dir, entry)
have_index = True
elif entry == "index.sgml.gz" and not os.path.exists(os.path.join(scan_dir, 'index.sgml')):
# debian/ubuntu started to compress this as index.sgml.gz :/
def ReadDevhelp(dir, file):
onlinedir = None
- for line in common.open_text(os.path.join(dir, file)):
+ for line in open(os.path.join(dir, file), mode='r', encoding='utf-8'):
# online must come before chapter/functions
if '<chapters' in line or '<functions' in line:
break
def ReadIndex(dir, file):
onlinedir = None
- for line in common.open_text(os.path.join(dir, file)):
+ for line in open(os.path.join(dir, file), mode='r', encoding='utf-8'):
# ONLINE must come before any ANCHORs
if '<ANCHOR' in line:
break
match = re.match(r'''^<ONLINE\s+href\s*=\s*"([^"]+)"\s*>''', line)
if match:
# Remove trailing non-directory component.
- onlinedir = re.sub(r'''(.*/).*''', r'\1', match.groups(1))
+ onlinedir = re.sub(r'''(.*/).*''', r'\1', match.group(1))
return onlinedir
def repl_func(match):
return match.group(1) + RebaseLink(match.group(2), options) + match.group(3)
- contents = common.open_text(filename).read()
+ contents = open(filename, mode='r', encoding='utf-8').read()
processed = re.sub(regex, repl_func, contents)
newfilename = filename + '.new'
- with common.open_text(newfilename, 'w') as h:
+ with open(newfilename, mode='w', encoding='utf-8') as h:
h.write(processed)
os.unlink(filename)
os.rename(newfilename, filename)
else:
match = re.match(r'\.\./([^/]+)', href)
if match is not None:
- package = match.groups(1)
+ package = match.group(1)
elif options.aggressive:
match = re.search(r'''([^/]+)/$''', href)
- package = match.groups(1)
+ package = match.group(1)
if package:
if options.online and package in OnlineMap:
def PrintWhatWeHaveDone():
- for origdir in sorted(iterkeys(Mapped)):
+ for origdir in sorted(Mapped.keys()):
info = Mapped[origdir]
print(origdir, "->", info[0], "(%s)" % info[1])
organized into sections ready to output the XML pages.
"""
-from __future__ import print_function
-from six import iteritems, iterkeys
-
import logging
import os
import re
for dir in options.source_dir:
ScanHeaders(dir, section_list, decl_list, get_types, options)
- with common.open_text(new_decl_list, 'w') as f:
- for section in sorted(iterkeys(section_list)):
+ with open(new_decl_list, 'w', encoding='utf-8') as f:
+ for section in sorted(section_list.keys()):
f.write(section_list[section])
- with common.open_text(new_decl, 'w') as f:
+ with open(new_decl, 'w', encoding='utf-8') as f:
for decl in decl_list:
f.write(decl)
if options.rebuild_types:
- with common.open_text(new_types, 'w') as f:
+ with open(new_types, 'w', encoding='utf-8') as f:
for func in sorted(get_types):
f.write(func + '\n')
# because EXTRA_DIST in gtk-doc.make requires it.
overrides_file = base_filename + '-overrides.txt'
if not os.path.exists(overrides_file):
- open(overrides_file, 'w').close()
+ open(overrides_file, 'w', encoding='utf-8').close()
#
logging.info('Scanning %s', input_file)
- for line in common.open_text(input_file):
+ for line in open(input_file, 'r', encoding='utf-8'):
# If this is a private header, skip it.
if re.search(r'^\s*/\*\s*<\s*private_header\s*>\s*\*/', line):
return
previous_line = line
# print remaining forward declarations
- for symbol in sorted(iterkeys(forward_decls)):
+ for symbol in sorted(forward_decls.keys()):
if forward_decls[symbol]:
AddSymbolToList(slist, symbol)
decl_list.append(forward_decls[symbol])
logging.info('options: %s', str(options.__dict__))
c_file = options.module + '-scan.c'
- output = common.open_text(c_file, 'w')
+ output = open(c_file, 'w', encoding='utf-8')
base_filename = os.path.join(options.output_dir, options.module)
old_signals_filename = base_filename + '.signals'
get_types = ""
ntypes = 1
- for line in common.open_text(options.types):
+ for line in open(options.types, 'r', encoding='utf-8'):
if line.startswith('#include'):
includes += line
elif line.startswith('%') or line.strip() == '':
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
<revhistory>
<revision>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development</revremark>
+ </revision>
+ <revision>
<revnumber>1.28</revnumber>
<date>24 Mar 2018</date>
<authorinitials>ss</authorinitials>
<guilabel>Writing the documentation.</guilabel>
The author fills in the source files with the documentation for each
- function, macro, union etc. (In the past information was entered in
- generated template files, which is not recommended anymore).
+ function, macro, structs or unions, etc.
</para>
</listitem>
<title>About GTK-Doc</title>
<para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
+ <para>
(FIXME)
</para>
<para>
- (History, authors, web pages, mailing list, license, future plans,
+ (authors, web pages, mailing list, license, future plans,
comparison with other similar systems.)
</para>
</chapter>
<chapter id="settingup">
- <title>Setting up your project</title>
+ <title>Project Setup</title>
<para>
- The next sections describe what steps to perform to integrate GTK-Doc into
- your project. Theses sections assume we work on a project called 'meep'.
- This project contains a library called 'libmeep' and
- an end-user app called 'meeper'. We also assume you will be using autoconf
- and automake. In addition section <link linkend="plain_makefiles">plain
- makefiles or other build systems</link> will describe the basics needed to
- work in a different build setup.
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
</para>
<sect1 id="settingup_docfiles">
<title>Setting up a skeleton documentation</title>
<para>
- Under your top-level project directory create folders called docs/reference
- (this way you can also have docs/help for end-user documentation).
- It is recommended to create another subdirectory with the name of the doc-package.
- For packages with just one library this step is not necessary.
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
</para>
<para>
- This can then look as shown below:
- <example><title>Example directory structure</title>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
<programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
</para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>Integration with autoconf</title>
-
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
<para>
- Very easy! Just add one line to your <filename>configure.ac</filename> script.
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
+
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>Integration with autoconf</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-]]></programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>
- This will require all developers to have gtk-doc installed. If it is
- okay for your project to have optional api-doc build setup, you can
- solve this as below. Keep it as is, as gtkdocize is looking for
- <function>GTK_DOC_CHECK</function> at the start of a line.
- <example><title>Keep gtk-doc optional</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-],[
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
-]]></programlisting>
+ <sect2 id="settingup_automake">
+ <title>Integration with automake</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class='directory'>examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class='directory'>docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
+ <programlisting>
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
+</programlisting>
</example>
- </para>
- <para>
- The first argument is used to check for the gtkdocversion at configure time.
- The 2nd, optional argument is used by <application>gtkdocize</application>.
- The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure switches:
- </para>
- <orderedlist>
- <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
- <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
- <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
+
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <important>
- <para>
- GTK-Doc is disabled by default! Remember to pass the option
- <option>'--enable-gtk-doc'</option> to the next
- <filename>configure</filename> run. Otherwise pregenerated documentation is installed
- (which makes sense for users but not for developers).
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
+
+ All the tools support <option>--help</option> to list the supported
+ options.
</para>
- </important>
- <para>
- Furthermore it is recommended that you have the following line inside
- your <filename>configure.ac</filename> script.
- This allows <application>gtkdocize</application> to automatically copy the
- macro definition for <function>GTK_DOC_CHECK</function> to your project.
- </para>
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
- <para>
- <example><title>Preparation for gtkdocize</title>
- <programlisting><![CDATA[
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>Integration with autoconf</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
]]></programlisting>
- </example>
- </para>
- <para>
- After all changes to <filename>configure.ac</filename> are made, update
- the <filename>configure</filename> file. This can be done by re-running
- <code>autoreconf -i</code> or <code>autogen.sh</code>.
- </para>
- </sect1>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>Integration with automake</title>
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class='directory'>examples</filename> sub directory of the
- <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
- to your project's API documentation directory (
- <filename class='directory'>./docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple doc-packages repeat this for each one.
- </para>
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <para>
- The next step is to edit the settings inside the <filename>Makefile.am</filename>.
- All the settings have a comment above that describes their purpose.
- Most settings are extra flags passed to the respective tools. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
- All the tools support <option>--help</option> to list the supported
- parameters.
- </para>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <!-- FIXME: explain options ? -->
+ <orderedlist>
+ <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
+ <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
+ </orderedlist>
- </sect1>
+ <important>
+ <para>
+ GTK-Doc is disabled by default! Remember to pass the option
+ <option>'--enable-gtk-doc'</option> to the next
+ <filename>configure</filename> run. Otherwise pregenerated documentation is installed
+ (which makes sense for users but not for developers).
+ </para>
+ </important>
- <sect1 id="settingup_autogen">
- <title>Integration with autogen</title>
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- <para>
- Most projects will have an <filename>autogen.sh</filename> script to
- setup the build infrastructure after a checkout from version control
- system (such as cvs/svn/git). GTK-Doc comes with a tool called
- <application>gtkdocize</application> which can be used in such a script.
- It should be run before autoheader, automake or autoconf.
- </para>
+ <sect2 id="settingup_autogen">
+ <title>Integration with autogen</title>
- <para>
- <example><title>Running gtkdocize from autogen.sh</title>
- <programlisting><![CDATA[
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
+
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
+
+ <para>
+ <example><title>Running gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
gtkdocize || exit 1
]]></programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>
- When running <application>gtkdocize</application> it copies
- <filename>gtk-doc.make</filename> to your project root (or any directory
- specified by the <option>--docdir</option> option).
- It also checks you configure script for the <function>GTK_DOC_CHECK</function>
- invocation. This macro can be used to pass extra parameters to
- <application>gtkdocize</application>.
- </para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>
- Historically GTK-Doc was generating template files where developers entered the docs.
- This turned out to be not so good (e.g. the need for having generated
- files under version control).
- Since GTK-Doc 1.9 the tools can get all the information from source comments
- and thus the templates can be avoided. We encourage people to keep
- documentation in the code. <application>gtkdocize</application> supports now
- a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
- tmpl usage totally. Besides adding the option directly to the command
- invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
- or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
- If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
- please remove the directory (e.g. from version control system).
- </para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>Running the doc build</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>
- After the previous steps it's time to run the build. First we need to
- rerun <filename>autogen.sh</filename>. If this script runs configure for
- you, then give it the <option>--enable-gtk-doc</option> option.
- Otherwise manually run <filename>configure</filename> with this option
- afterwards.
- </para>
- <para>
- The first make run generates several additional files in the doc-directories.
- The important ones are:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>.
- </para>
- <para>
- <example><title>Running the doc build</title>
- <programlisting><![CDATA[
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>
+ After the previous steps it's time to run the build. First we need to
+ rerun <filename>autogen.sh</filename>. If this script runs configure
+ for you, then give it the <option>--enable-gtk-doc</option> option.
+ Otherwise manually run <filename>configure</filename> with this option
+ afterwards.
+ </para>
+ <para>
+ The first make run generates several additional files in the doc-directories.
+ The important ones are:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>.
+ </para>
+ <para>
+ <example><title>Running the doc build</title>
+ <programlisting><![CDATA[
./autogen.sh --enable-gtk-doc
make
]]></programlisting>
- </example>
- </para>
- <para>
- Now you can point your browser to <filename>docs/reference/<package>/index.html</filename>.
- Yes, it's a bit disappointing still. But hang-on, during the next chapter we
- tell you how to fill the pages with life.
- </para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>Integration with version control systems</title>
+ <sect1 id="settingup_cmake">
+ <title>Integration with CMake build systems</title>
<para>
- As a rule of thumb, it's the files you edit which should go under
- version control. For typical projects it's these files:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>,
- <filename>Makefile.am</filename>.
+ GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
+ (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
+ module). This provides a <literal>gtk_doc_add_module</literal>
+ command that you can set in your <filename>CMakeLists.txt</filename>
+ file.
</para>
+
<para>
- Files in the <filename>xml/</filename> and <filename>html/</filename>
- directories should not go under version control. Neither should any of
- the <filename>.stamp</filename> files.
+ The following example shows how to use this command.
+ <example><title>Example of using GTK-Doc from CMake</title>
+ <programlisting><![CDATA[
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+]]></programlisting>
+ </example>
</para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integration with plain makefiles or other build systems</title>
<para>
</para>
</sect1>
- <sect1 id="cmake">
- <title>Integration with CMake build systems</title>
-
- <para>
- GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
- (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
- module). This provides a <literal>gtk_doc_add_module</literal>
- command that you can set in your <filename>CMakeLists.txt</filename>
- file.
- </para>
-
- <para>
- The following example shows how to use this command.
- <example><title>Example of using GTK-Doc from CMake</title>
- <programlisting><![CDATA[
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>Integration with version control systems</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>
+ As a rule of thumb, it's the files you edit which should go under
+ version control. For typical projects it's these files:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>,
+ <filename>Makefile.am</filename>.
+ </para>
+ <para>
+ Files in the <filename>xml/</filename> and <filename>html/</filename>
+ directories should not go under version control. Neither should any of
+ the <filename>.stamp</filename> files.
+ </para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
- </sect1>
</chapter>
<chapter id="documenting">
syntax of the comments.
</para>
- <note>
- <title>Documentation placement</title>
- <para>
- In the past most documentation had to be filled into files residing
- inside the <filename>tmpl</filename> directory. This has the
- disadvantages that the information is often not updated and also that
- the file tend to cause conflicts with version control systems.
- </para>
- <para>
- The avoid the aforementioned problems we suggest putting the
- documentation inside the sources. This manual will only describe this
- way of documenting code.
- </para>
- </note>
-
<para>
- The scanner can handle the majority of C headers fine. In the case of
- receiving warnings from the scanner that look like a special case, one can
- hint GTK-Doc to skip over them.
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<para>
As already mentioned earlier GTK-Doc is for documenting public API. Thus
one cannot write documentation for static symbols. Nevertheless it is good
- to comment those symbols too. This helps other to understand you code.
+ to comment those symbols too. This helps other developers to understand
+ your code.
Therefore we recommend to comment these using normal comments (without the
2nd '*' in the first line).
If later the function needs to be made public, all one needs to do is to
</para>
<para>
- <example><title>Example types file snippet</title>
+ <example><title>Example <package>.types file</title>
<programlisting><![CDATA[
#include <gtk/gtk.h>
containing entities for e.g. package_name and package_version. You can
use this e.g. in the main xml file to avoid hardcoding the version
number. Below is an example that shows how the entity file is included
- and how the entities are used. The entities can also be used in all
+ in the master template and how the entities are used.
+ The entities can also be used in all
generated files, GTK-Doc will use the same xml header in generated xml
files.
<example><title>Use pre-generated entities</title>
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
<revhistory>
<revision>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development</revremark>
+ </revision>
+ <revision>
<revnumber>1.28</revnumber>
<date>24 Mar 2018</date>
<authorinitials>ss</authorinitials>
<guilabel>Writing the documentation.</guilabel>
The author fills in the source files with the documentation for each
- function, macro, union etc. (In the past information was entered in
- generated template files, which is not recommended anymore).
+ function, macro, structs or unions, etc.
</para>
</listitem>
<sect1 id="aboutgtkdoc">
<title>GTK-Doc পরিচিতি</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(FIXME)</para>
<para>
- (History, authors, web pages, mailing list, license, future plans,
+ (authors, web pages, mailing list, license, future plans,
comparison with other similar systems.)
</para>
</chapter>
<chapter id="settingup">
- <title>প্রজেক্ট প্রস্তুত করার প্রণালী</title>
+ <title>Project Setup</title>
+
+ <para>
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- The next sections describe what steps to perform to integrate GTK-Doc into
- your project. Theses sections assume we work on a project called 'meep'.
- This project contains a library called 'libmeep' and
- an end-user app called 'meeper'. We also assume you will be using autoconf
- and automake. In addition section <link linkend="plain_makefiles">plain
- makefiles or other build systems</link> will describe the basics needed to
- work in a different build setup.
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
</para>
<sect1 id="settingup_docfiles">
<title>নথির একটি পরিকাঠামো নির্ধারণের প্রণালী</title>
<para>
- Under your top-level project directory create folders called docs/reference
- (this way you can also have docs/help for end-user documentation).
- It is recommended to create another subdirectory with the name of the doc-package.
- For packages with just one library this step is not necessary.
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
</para>
<para>
- This can then look as shown below:
- <example><title>Example directory structure</title>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
<programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
</para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>autoconf সহযোগে একত্রিত করার প্রণালী</title>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
- <para>এই কাজ অতিমাত্রায় সহজ! <filename>configure.ac</filename> স্ক্রিপ্টের মধ্যে একটি পংক্তি যোগ করুন।</para>
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>autoconf সহযোগে একত্রিত করার প্রণালী</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-]]></programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>
- This will require all developers to have gtk-doc installed. If it is
- okay for your project to have optional api-doc build setup, you can
- solve this as below. Keep it as is, as gtkdocize is looking for
- <function>GTK_DOC_CHECK</function> at the start of a line.
- <example><title>Keep gtk-doc optional</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-],[
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
-]]></programlisting>
+ <sect2 id="settingup_automake">
+ <title>automake সহযোগে একত্রিত করার প্রণালী</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
+ <programlisting>
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
+</programlisting>
</example>
- </para>
- <para>
- The first argument is used to check for the gtkdocversion at configure time.
- The 2nd, optional argument is used by <application>gtkdocize</application>.
- The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure switches:
- </para>
- <orderedlist>
- <listitem><para>--with-html-dir=PATH : ইনস্টল করা ডকুমেন্টের পাথ</para></listitem>
- <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
- <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
+
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <important>
- <para>
- GTK-Doc is disabled by default! Remember to pass the option
- <option>'--enable-gtk-doc'</option> to the next
- <filename>configure</filename> run. Otherwise pregenerated documentation is installed
- (which makes sense for users but not for developers).
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
+
+ All the tools support <option>--help</option> to list the supported
+ options.
</para>
- </important>
- <para>
- Furthermore it is recommended that you have the following line inside
- your <filename>configure.ac</filename> script.
- This allows <application>gtkdocize</application> to automatically copy the
- macro definition for <function>GTK_DOC_CHECK</function> to your project.
- </para>
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
- <para>
- <example><title>gtkdocize-র প্রস্তুতি</title>
- <programlisting><![CDATA[
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>autoconf সহযোগে একত্রিত করার প্রণালী</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
]]></programlisting>
- </example>
- </para>
- <para>
- After all changes to <filename>configure.ac</filename> are made, update
- the <filename>configure</filename> file. This can be done by re-running
- <code>autoreconf -i</code> or <code>autogen.sh</code>.
- </para>
- </sect1>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>automake সহযোগে একত্রিত করার প্রণালী</title>
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub directory of the
- <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
- to your project's API documentation directory (
- <filename class="directory">./docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple doc-packages repeat this for each one.
- </para>
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <para>
- The next step is to edit the settings inside the <filename>Makefile.am</filename>.
- All the settings have a comment above that describes their purpose.
- Most settings are extra flags passed to the respective tools. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
- All the tools support <option>--help</option> to list the supported
- parameters.
- </para>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <!-- FIXME: explain options ? -->
+ <orderedlist>
+ <listitem><para>--with-html-dir=PATH : ইনস্টল করা ডকুমেন্টের পাথ</para></listitem>
+ <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
+ </orderedlist>
- </sect1>
+ <important>
+ <para>
+ GTK-Doc is disabled by default! Remember to pass the option
+ <option>'--enable-gtk-doc'</option> to the next
+ <filename>configure</filename> run. Otherwise pregenerated documentation is installed
+ (which makes sense for users but not for developers).
+ </para>
+ </important>
- <sect1 id="settingup_autogen">
- <title>autogen সহযোগে একত্রিত করার প্রণালী</title>
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- <para>
- Most projects will have an <filename>autogen.sh</filename> script to
- setup the build infrastructure after a checkout from version control
- system (such as cvs/svn/git). GTK-Doc comes with a tool called
- <application>gtkdocize</application> which can be used in such a script.
- It should be run before autoheader, automake or autoconf.
- </para>
+ <sect2 id="settingup_autogen">
+ <title>autogen সহযোগে একত্রিত করার প্রণালী</title>
- <para>
- <example><title>autogen.sh থেকে gtkdocsize সঞ্চালনার প্রণালী</title>
- <programlisting><![CDATA[
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
+
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
+
+ <para>
+ <example><title>autogen.sh থেকে gtkdocsize সঞ্চালনার প্রণালী</title>
+ <programlisting><![CDATA[
gtkdocize || exit 1
]]></programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>
- When running <application>gtkdocize</application> it copies
- <filename>gtk-doc.make</filename> to your project root (or any directory
- specified by the <option>--docdir</option> option).
- It also checks you configure script for the <function>GTK_DOC_CHECK</function>
- invocation. This macro can be used to pass extra parameters to
- <application>gtkdocize</application>.
- </para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>
- Historically GTK-Doc was generating template files where developers entered the docs.
- This turned out to be not so good (e.g. the need for having generated
- files under version control).
- Since GTK-Doc 1.9 the tools can get all the information from source comments
- and thus the templates can be avoided. We encourage people to keep
- documentation in the code. <application>gtkdocize</application> supports now
- a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
- tmpl usage totally. Besides adding the option directly to the command
- invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
- or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
- If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
- please remove the directory (e.g. from version control system).
- </para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>doc build সঞ্চালনার প্রণালী</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>
- After the previous steps it's time to run the build. First we need to
- rerun <filename>autogen.sh</filename>. If this script runs configure for
- you, then give it the <option>--enable-gtk-doc</option> option.
- Otherwise manually run <filename>configure</filename> with this option
- afterwards.
- </para>
- <para>
- The first make run generates several additional files in the doc-directories.
- The important ones are:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>.
- </para>
- <para>
- <example><title>doc build সঞ্চালনার প্রণালী</title>
- <programlisting><![CDATA[
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>
+ After the previous steps it's time to run the build. First we need to
+ rerun <filename>autogen.sh</filename>. If this script runs configure
+ for you, then give it the <option>--enable-gtk-doc</option> option.
+ Otherwise manually run <filename>configure</filename> with this option
+ afterwards.
+ </para>
+ <para>
+ The first make run generates several additional files in the doc-directories.
+ The important ones are:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>.
+ </para>
+ <para>
+ <example><title>doc build সঞ্চালনার প্রণালী</title>
+ <programlisting><![CDATA[
./autogen.sh --enable-gtk-doc
make
]]></programlisting>
- </example>
- </para>
- <para>
- Now you can point your browser to <filename>docs/reference/<package>/index.html</filename>.
- Yes, it's a bit disappointing still. But hang-on, during the next chapter we
- tell you how to fill the pages with life.
- </para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>ভার্সান কনট্রোল সিস্টেমের সাথে একত্রিত করার প্রণালী</title>
+ <sect1 id="settingup_cmake">
+ <title>Integration with CMake build systems</title>
<para>
- As a rule of thumb, it's the files you edit which should go under
- version control. For typical projects it's these files:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>,
- <filename>Makefile.am</filename>.
+ GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
+ (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
+ module). This provides a <literal>gtk_doc_add_module</literal>
+ command that you can set in your <filename>CMakeLists.txt</filename>
+ file.
</para>
+
<para>
- Files in the <filename>xml/</filename> and <filename>html/</filename>
- directories should not go under version control. Neither should any of
- the <filename>.stamp</filename> files.
+ The following example shows how to use this command.
+ <example><title>Example of using GTK-Doc from CMake</title>
+ <programlisting><![CDATA[
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+]]></programlisting>
+ </example>
</para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integration with plain makefiles or other build systems</title>
<para>
</para>
</sect1>
- <sect1 id="cmake">
- <title>Integration with CMake build systems</title>
-
- <para>
- GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
- (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
- module). This provides a <literal>gtk_doc_add_module</literal>
- command that you can set in your <filename>CMakeLists.txt</filename>
- file.
- </para>
-
- <para>
- The following example shows how to use this command.
- <example><title>Example of using GTK-Doc from CMake</title>
- <programlisting><![CDATA[
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>ভার্সান কনট্রোল সিস্টেমের সাথে একত্রিত করার প্রণালী</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>
+ As a rule of thumb, it's the files you edit which should go under
+ version control. For typical projects it's these files:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>,
+ <filename>Makefile.am</filename>.
+ </para>
+ <para>
+ Files in the <filename>xml/</filename> and <filename>html/</filename>
+ directories should not go under version control. Neither should any of
+ the <filename>.stamp</filename> files.
+ </para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
- </sect1>
</chapter>
<chapter id="documenting">
syntax of the comments.
</para>
- <note>
- <title>নথিপত্রের স্থাপনা</title>
- <para>
- In the past most documentation had to be filled into files residing
- inside the <filename>tmpl</filename> directory. This has the
- disadvantages that the information is often not updated and also that
- the file tend to cause conflicts with version control systems.
- </para>
- <para>
- The avoid the aforementioned problems we suggest putting the
- documentation inside the sources. This manual will only describe this
- way of documenting code.
- </para>
- </note>
-
<para>
- The scanner can handle the majority of C headers fine. In the case of
- receiving warnings from the scanner that look like a special case, one can
- hint GTK-Doc to skip over them.
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<para>
As already mentioned earlier GTK-Doc is for documenting public API. Thus
one cannot write documentation for static symbols. Nevertheless it is good
- to comment those symbols too. This helps other to understand you code.
+ to comment those symbols too. This helps other developers to understand
+ your code.
Therefore we recommend to comment these using normal comments (without the
2nd '*' in the first line).
If later the function needs to be made public, all one needs to do is to
</para>
<para>
- <example><title>Example types file snippet</title>
+ <example><title>Example <package>.types file</title>
<programlisting><![CDATA[
#include <gtk/gtk.h>
containing entities for e.g. package_name and package_version. You can
use this e.g. in the main xml file to avoid hardcoding the version
number. Below is an example that shows how the entity file is included
- and how the entities are used. The entities can also be used in all
+ in the master template and how the entities are used.
+ The entities can also be used in all
generated files, GTK-Doc will use the same xml header in generated xml
files.
<example><title>Use pre-generated entities</title>
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc master\n"
-"POT-Creation-Date: 2017-12-28 10:31+0000\n"
-"PO-Revision-Date: 2018-03-03 07:23+0100\n"
+"POT-Creation-Date: 2018-03-24 15:17+0000\n"
+"PO-Revision-Date: 2018-04-03 13:41+0200\n"
"Last-Translator: Marek Černocký <marek@manet.cz>\n"
"Language-Team: čeština <gnome-cs-list@gnome.org>\n"
"Language: cs\n"
#. (itstool) path: revhistory/revision
#: C/index.docbook:83
msgid ""
-"<revnumber>1.2
7.1</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
+"<revnumber>1.2
8.1</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>development</revremark>"
msgstr ""
-"<revnumber>1.27.1</revnumber> <date>7. prosince 2017</date> "
+"<revnumber>1.28.1</revnumber> <date>24. března 2018</date> "
"<authorinitials>ss</authorinitials> <revremark>vývoj</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
msgid ""
+"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes</revremark>"
+msgstr ""
+"<revnumber>1.28</revnumber> <date>24. března 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>opravy chyb</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+msgid ""
"<revnumber>1.27</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>fine tuning of the python port</revremark>"
msgstr ""
"jazyce Python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
msgid ""
"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>port all tools from perl/bash to python</"
"jazyka Python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
+#: C/index.docbook:107
msgid ""
"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
"authorinitials> <revremark>opravy chyb, pročištění testů</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:107
+#: C/index.docbook:113
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>oprava chyby</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:113
+#: C/index.docbook:119
msgid ""
"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>oprava chyby</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:119
+#: C/index.docbook:125
msgid ""
"<revnumber>1.22</revnumber> <date>07 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"revremark>"
msgstr ""
"<revnumber>1.22</revnumber> <date>07. květen 2015</date> <authorinitials>ss</"
-"authorinitials> <revremark>oprava chyb, odstranění zastaralých věcí</"
+"authorinitials> <revremark>opravy chyb, odstranění zastaralých věcí</"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:125
+#: C/index.docbook:131
msgid ""
"<revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"revremark>"
msgstr ""
"<revnumber>1.21</revnumber> <date>17. červenec 2014</date> "
-"<authorinitials>ss</authorinitials> <revremark>oprava chyb, odstranění "
+"<authorinitials>ss</authorinitials> <revremark>opravy chyb, odstranění "
"zastaralých věcí</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:131
+#: C/index.docbook:137
msgid ""
"<revnumber>1.20</revnumber> <date>16 Feb 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, markdown support, style improvements</"
"vylepšení stylů</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:137
+#: C/index.docbook:143
msgid ""
"<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
"authorinitials> <revremark>opravy chyb</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:143
+#: C/index.docbook:149
msgid ""
"<revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, speedups, markdown support</revremark>"
"jazyka</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:149
+#: C/index.docbook:155
msgid ""
"<revnumber>1.17</revnumber> <date>26 Feb 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>urgent bug fix update</revremark>"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:155
+#: C/index.docbook:161
msgid ""
"<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes, layout improvements</revremark>"
"authorinitials> <revremark>opravy chyb, vylepšení vzhledu</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:161
+#: C/index.docbook:167
msgid ""
"<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bug and regression fixes</revremark>"
"authorinitials> <revremark>opravy chyb a regresí</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:167
+#: C/index.docbook:173
msgid ""
"<revnumber>1.14</revnumber> <date>28 March 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes and performance improvements</revremark>"
"authorinitials> <revremark>opravy chyb a vylepšení výkonu</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:173
+#: C/index.docbook:179
msgid ""
"<revnumber>1.13</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>broken tarball update</"
"balíčku</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:179
+#: C/index.docbook:185
msgid ""
"<revnumber>1.12</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>new tool features and "
"chyb</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:185
+#: C/index.docbook:191
msgid ""
"<revnumber>1.11</revnumber> <date>16 November 2008</date> "
"<authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</"
"GNOME</revremark>"
#. (itstool) path: chapter/title
-#: C/index.docbook:198
+#: C/index.docbook:204
msgid "Introduction"
msgstr "Úvod"
#. (itstool) path: chapter/para
-#: C/index.docbook:200
+#: C/index.docbook:206
msgid ""
"This chapter introduces GTK-Doc and gives an overview of what it is and how "
"it is used."
"použít."
#. (itstool) path: sect1/title
-#: C/index.docbook:206
+#: C/index.docbook:212
msgid "What is GTK-Doc?"
msgstr "Co je to GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:208
+#: C/index.docbook:214
msgid ""
"GTK-Doc is used to document C code. It is typically used to document the "
"public API of libraries, such as the GTK+ and GNOME libraries. But it can "
"ale použít i k dokumentaci aplikačního kódu."
#. (itstool) path: sect1/title
-#: C/index.docbook:216
+#: C/index.docbook:222
msgid "How Does GTK-Doc Work?"
msgstr "Jak GTK-Doc pracuje?"
#. (itstool) path: sect1/para
-#: C/index.docbook:218
+#: C/index.docbook:224
msgid ""
"GTK-Doc works by using documentation of functions placed inside the source "
"files in specially-formatted comment blocks, or documentation added to the "
"nevytváří)."
#. (itstool) path: sect1/para
-#: C/index.docbook:225
+#: C/index.docbook:231
msgid ""
"GTK-Doc consists of a number of python scripts, each performing a different "
"step in the process."
"část procesu."
#. (itstool) path: sect1/para
-#: C/index.docbook:230
+#: C/index.docbook:236
msgid "There are 5 main steps in the process:"
msgstr "Celý proces se skládá z pěti hlavních kroků:"
#. (itstool) path: listitem/para
-#: C/index.docbook:237
+#: C/index.docbook:243
msgid ""
"<guilabel>Writing the documentation.</guilabel> The author fills in the "
"source files with the documentation for each function, macro, union etc. (In "
"nedoporučuje)."
#. (itstool) path: listitem/para
-#: C/index.docbook:247
+#: C/index.docbook:253
msgid ""
"<guilabel>Gathering information about the code.</guilabel> "
"<application>gtkdoc-scan</application> scans the header files of the code "
"filename> do <filename><module>-overrides.txt</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:264
+#: C/index.docbook:270
msgid ""
"<application>gtkdoc-scangobj</application> can also be used to dynamically "
"query a library about any GObject subclasses it exports. It saves "
"signálech objektu GObject, které poskytují."
#. (itstool) path: listitem/para
-#: C/index.docbook:270
+#: C/index.docbook:276
msgid ""
"<application>gtkdoc-scanobj</application> should not be used anymore. It was "
"needed in the past when GObject was still GtkObject inside gtk+."
"Bylo zapotřebí v minulosti, kdy byl GObject ještě GtkObject v rámci gtk+."
#. (itstool) path: listitem/para
-#: C/index.docbook:277
+#: C/index.docbook:283
msgid ""
"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
"mkdb</application> turns the template files into XML files in the <filename "
"zdrojového kódu a introspektivních dat."
#. (itstool) path: listitem/para
-#: C/index.docbook:286
+#: C/index.docbook:292
msgid ""
"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
"nazvaný <filename><balíček>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:292
+#: C/index.docbook:298
msgid ""
"Files in <filename class=\"directory\">xml/</filename> and <filename class="
"\"directory\">html/</filename> directories are always overwritten. One "
"neměly být upravovány přímo."
#. (itstool) path: listitem/para
-#: C/index.docbook:300
+#: C/index.docbook:306
msgid ""
"<guilabel>Fixing up cross-references between documents.</guilabel> After "
"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
"dokumenty, které jsou nainstalované)."
#. (itstool) path: sect1/title
-#: C/index.docbook:318
+#: C/index.docbook:324
msgid "Getting GTK-Doc"
msgstr "Jak získat GTK-Doc?"
#. (itstool) path: sect2/title
-#: C/index.docbook:321
+#: C/index.docbook:327
msgid "Requirements"
msgstr "Požadavky"
#. (itstool) path: sect2/para
-#: C/index.docbook:322
+#: C/index.docbook:328
msgid ""
"<guilabel>python 2/3</guilabel> - the main scripts are written in python."
msgstr "<guilabel>Python 2/3</guilabel> – hlavní skripty jsou v jazyce Python."
#. (itstool) path: sect2/para
-#: C/index.docbook:325
+#: C/index.docbook:331
msgid ""
"<guilabel>xsltproc</guilabel> - the xslt processor from libxslt <ulink url="
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
#. (itstool) path: sect2/para
-#: C/index.docbook:329
+#: C/index.docbook:335
msgid ""
"<guilabel>docbook-xsl</guilabel> - the docbook xsl stylesheets <ulink url="
"\"http://sourceforge.net/projects/docbook/files/docbook-xsl/\" type=\"http"
"\">sourceforge.net/projects/docbook/files/docbook-xsl</ulink>"
#. (itstool) path: sect2/para
-#: C/index.docbook:333
+#: C/index.docbook:339
msgid ""
"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
"syntaxe u příkladů"
#. (itstool) path: sect1/title
-#: C/index.docbook:341
+#: C/index.docbook:347
msgid "About GTK-Doc"
msgstr "O aplikaci GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:343 C/index.docbook:357
+#: C/index.docbook:349 C/index.docbook:363
msgid "(FIXME)"
msgstr "(DOPLNIT)"
#. (itstool) path: sect1/para
-#: C/index.docbook:347
+#: C/index.docbook:353
msgid ""
"(History, authors, web pages, mailing list, license, future plans, "
"comparison with other similar systems.)"
"budoucna, srovnání s ostatními podobnými systémy.)"
#. (itstool) path: sect1/title
-#: C/index.docbook:355
+#: C/index.docbook:361
msgid "About this Manual"
msgstr "O této příručce"
#. (itstool) path: sect1/para
-#: C/index.docbook:361
+#: C/index.docbook:367
msgid "(who it is meant for, where you can get it, license)"
msgstr "(k čemu je určená, kde ji můžete získat, licence)"
#. (itstool) path: chapter/title
-#: C/index.docbook:370
+#: C/index.docbook:376
msgid "Setting up your project"
msgstr "Nastavení vašeho projektu"
#. (itstool) path: chapter/para
-#: C/index.docbook:372
+#: C/index.docbook:378
msgid ""
"The next sections describe what steps to perform to integrate GTK-Doc into "
"your project. Theses sections assume we work on a project called 'meep'. "
"popsány základní požadavky pro fungování s jinými postupy sestavování."
#. (itstool) path: sect1/title
-#: C/index.docbook:383
+#: C/index.docbook:389
msgid "Setting up a skeleton documentation"
msgstr "Nastavení kostry dokumentace"
#. (itstool) path: sect1/para
-#: C/index.docbook:385
+#: C/index.docbook:391
msgid ""
"Under your top-level project directory create folders called docs/reference "
"(this way you can also have docs/help for end-user documentation). It is "
"jedinou knihovnou není tento krok nutný."
#. (itstool) path: example/title
-#: C/index.docbook:394
+#: C/index.docbook:400
msgid "Example directory structure"
msgstr "Příklad struktury složek"
#. (itstool) path: example/programlisting
-#: C/index.docbook:395
+#: C/index.docbook:401
#, no-wrap
msgid ""
"\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:392
+#: C/index.docbook:398
msgid "This can then look as shown below: <_:example-1/>"
msgstr "Ve výsledku to může vypadat nějak takto: <_:example-1/>"
#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:410 C/index.docbook:417
+#: C/index.docbook:416 C/index.docbook:423
msgid "Integration with autoconf"
msgstr "Integrace s autoconf"
#. (itstool) path: sect1/para
-#: C/index.docbook:412
+#: C/index.docbook:418
msgid ""
"Very easy! Just add one line to your <filename>configure.ac</filename> "
"script."
"<filename>configure.ac</filename>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:418
+#: C/index.docbook:424
#, no-wrap
msgid ""
"\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
#. (itstool) path: example/title
-#: C/index.docbook:430
+#: C/index.docbook:436
msgid "Keep gtk-doc optional"
msgstr "Ponechání gtk-doc jako volitelného"
#. (itstool) path: example/programlisting
-#: C/index.docbook:431
+#: C/index.docbook:437
#, no-wrap
msgid ""
"\n"
"])\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:425
+#: C/index.docbook:431
msgid ""
"This will require all developers to have gtk-doc installed. If it is okay "
"for your project to have optional api-doc build setup, you can solve this as "
"example-1/>"
#. (itstool) path: sect1/para
-#: C/index.docbook:442
+#: C/index.docbook:448
msgid ""
"The first argument is used to check for the gtkdocversion at configure time. "
"The 2nd, optional argument is used by <application>gtkdocize</application>. "
"přepínačů pro configure:"
#. (itstool) path: listitem/para
-#: C/index.docbook:448
+#: C/index.docbook:454
msgid "--with-html-dir=PATH : path to installed docs"
msgstr "--with-html-dir=CESTA: cesta, kam se má dokumentace nainstalovat"
#. (itstool) path: listitem/para
-#: C/index.docbook:449
+#: C/index.docbook:455
msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]"
msgstr ""
"--enable-gtk-doc: použít k sestavení dokumentace gtk-doc [výchozí je ne]"
#. (itstool) path: listitem/para
-#: C/index.docbook:450
+#: C/index.docbook:456
msgid ""
"--enable-gtk-doc-html : build documentation in html format [default=yes]"
msgstr ""
"--enable-gtk-doc-html: sestavit dokumentaci ve formátu HTML [výchozí je ano]"
#. (itstool) path: listitem/para
-#: C/index.docbook:451
+#: C/index.docbook:457
msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
msgstr ""
"--enable-gtk-doc-pdf: sestavit dokumentaci ve formátu PDF [výchozí je ne]"
#. (itstool) path: important/para
-#: C/index.docbook:455
+#: C/index.docbook:461
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"uživatele, ale ne pro vývojáře)."
#. (itstool) path: sect1/para
-#: C/index.docbook:463
+#: C/index.docbook:469
msgid ""
"Furthermore it is recommended that you have the following line inside your "
"<filename>configure.ac</filename> script. This allows "
"function> do vašeho projektu."
#. (itstool) path: example/title
-#: C/index.docbook:471
+#: C/index.docbook:477
msgid "Preparation for gtkdocize"
msgstr "Příprava pro gtkdocize"
#. (itstool) path: example/programlisting
-#: C/index.docbook:472
+#: C/index.docbook:478
#, no-wrap
msgid ""
"\n"
"AC_CONFIG_MACRO_DIR(m4)\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:477
+#: C/index.docbook:483
msgid ""
"After all changes to <filename>configure.ac</filename> are made, update the "
"<filename>configure</filename> file. This can be done by re-running "
"<code>autoreconf -i</code> nebo <code>autogen.sh</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:485
+#: C/index.docbook:491
msgid "Integration with automake"
msgstr "Integrace s automake"
#. (itstool) path: sect1/para
-#: C/index.docbook:487
+#: C/index.docbook:493
msgid ""
"First copy the <filename>Makefile.am</filename> from the <filename class="
"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
"opakujte tento krok pro každý z nich."
#. (itstool) path: sect1/para
-#: C/index.docbook:498
+#: C/index.docbook:504
msgid ""
"The next step is to edit the settings inside the <filename>Makefile.am</"
"filename>. All the settings have a comment above that describes their "
"přepínačů."
#. (itstool) path: sect1/title
-#: C/index.docbook:512
+#: C/index.docbook:518
msgid "Integration with autogen"
msgstr "Integrace s autogen"
#. (itstool) path: sect1/para
-#: C/index.docbook:514
+#: C/index.docbook:520
msgid ""
"Most projects will have an <filename>autogen.sh</filename> script to setup "
"the build infrastructure after a checkout from version control system (such "
"Měl by být spuštěný před autoheader, automake nebo autoconf."
#. (itstool) path: example/title
-#: C/index.docbook:523
+#: C/index.docbook:529
msgid "Running gtkdocize from autogen.sh"
msgstr "Spuštění gtkdocize z autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:524
+#: C/index.docbook:530
#, no-wrap
msgid ""
"\n"
"gtkdocize || exit 1\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:530
+#: C/index.docbook:536
msgid ""
"When running <application>gtkdocize</application> it copies <filename>gtk-"
"doc.make</filename> to your project root (or any directory specified by the "
"application>."
#. (itstool) path: sect1/para
-#: C/index.docbook:539
+#: C/index.docbook:545
msgid ""
"Historically GTK-Doc was generating template files where developers entered "
"the docs. This turned out to be not so good (e.g. the need for having "
#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:556 C/index.docbook:573
+#: C/index.docbook:562 C/index.docbook:579
msgid "Running the doc build"
msgstr "Sestavení dokumentace"
#. (itstool) path: sect1/para
-#: C/index.docbook:558
+#: C/index.docbook:564
msgid ""
"After the previous steps it's time to run the build. First we need to rerun "
"<filename>autogen.sh</filename>. If this script runs configure for you, then "
"Jinak potom ručně spusťte <filename>configure</filename> s tímto přepínačem."
#. (itstool) path: sect1/para
-#: C/index.docbook:565
+#: C/index.docbook:571
msgid ""
"The first make run generates several additional files in the doc-"
"directories. The important ones are: <filename><package>.types</"
"package>-sections.txt</filename>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:574
+#: C/index.docbook:580
#, no-wrap
msgid ""
"\n"
"make\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:580
+#: C/index.docbook:586
msgid ""
"Now you can point your browser to <filename>docs/reference/<package>/"
"index.html</filename>. Yes, it's a bit disappointing still. But hang-on, "
"nebojte, v následující kapitole vám řekneme, jak stránky uvést do života."
#. (itstool) path: sect1/title
-#: C/index.docbook:588
+#: C/index.docbook:594
msgid "Integration with version control systems"
msgstr "Integrace se systémem pro správu verzí"
#. (itstool) path: sect1/para
-#: C/index.docbook:590
+#: C/index.docbook:596
msgid ""
"As a rule of thumb, it's the files you edit which should go under version "
"control. For typical projects it's these files: <filename><package>."
"<filename>Makefile.am</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:598
+#: C/index.docbook:604
msgid ""
"Files in the <filename>xml/</filename> and <filename>html/</filename> "
"directories should not go under version control. Neither should any of the "
"filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:606
+#: C/index.docbook:612
msgid "Integration with plain makefiles or other build systems"
msgstr ""
"Integrace s prostými soubory Makefile nebo jinými sestavovacími systémy"
#. (itstool) path: sect1/para
-#: C/index.docbook:608
+#: C/index.docbook:614
msgid ""
"In the case one does not want to use automake and therefore <filename>gtk-"
"doc.mak</filename> one will need to call the gtkdoc tools in the right order "
"souborech make (nebo jiných nástrojích)."
#. (itstool) path: example/title
-#: C/index.docbook:615
+#: C/index.docbook:621
msgid "Documentation build steps"
msgstr "Kroky sestavení dokumentace"
#. (itstool) path: example/programlisting
-#: C/index.docbook:616
+#: C/index.docbook:622
#, no-wrap
msgid ""
"\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:630
+#: C/index.docbook:636
msgid ""
"One will need to look at the <filename>Makefile.am</filename> and "
"<filename>gtk-doc.mak</filename> to pick the extra options needed."
"am</filename> a <filename>gtk-doc.mak</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:637
+#: C/index.docbook:643
msgid "Integration with CMake build systems"
msgstr "Integrace se sestavovacím systémem CMake"
#. (itstool) path: sect1/para
-#: C/index.docbook:639
+#: C/index.docbook:645
msgid ""
"GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module (and "
"the corresponding <filename>GtkDocConfigVersion.cmake</filename> module). "
"nastavit ve svém souboru <filename>CMakeLists.txt</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:649
+#: C/index.docbook:655
msgid "Example of using GTK-Doc from CMake"
msgstr "Příklad použití GTK-Doc z CMake"
#. (itstool) path: example/programlisting
-#: C/index.docbook:650
+#: C/index.docbook:656
#, no-wrap
msgid ""
"\n"
" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:647
+#: C/index.docbook:653
msgid "The following example shows how to use this command. <_:example-1/>"
msgstr "Následující příklad ukazuje, jak tento příkaz použít: <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:675
+#: C/index.docbook:681
msgid "Documenting the code"
msgstr "Dokumentování v kódu"
#. (itstool) path: chapter/para
-#: C/index.docbook:677
+#: C/index.docbook:683
msgid ""
"GTK-Doc uses source code comment with a special syntax for code "
"documentation. Further it retrieves information about your project structure "
"syntaxi komentářů."
#. (itstool) path: note/title
-#: C/index.docbook:685
+#: C/index.docbook:691
msgid "Documentation placement"
msgstr "Umístění dokumentace"
#. (itstool) path: note/para
-#: C/index.docbook:686
+#: C/index.docbook:692
msgid ""
"In the past most documentation had to be filled into files residing inside "
"the <filename>tmpl</filename> directory. This has the disadvantages that the "
"systémech pro správu verzí."
#. (itstool) path: note/para
-#: C/index.docbook:692
+#: C/index.docbook:698
msgid ""
"The avoid the aforementioned problems we suggest putting the documentation "
"inside the sources. This manual will only describe this way of documenting "
"tento způsob dokumentování kódu."
#. (itstool) path: example/title
-#: C/index.docbook:703 C/index.docbook:729
+#: C/index.docbook:709 C/index.docbook:735
msgid "GTK-Doc comment block"
msgstr "Komentářový blok GTK-Doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:704
+#: C/index.docbook:710
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:699
+#: C/index.docbook:705
msgid ""
"The scanner can handle the majority of C headers fine. In the case of "
"receiving warnings from the scanner that look like a special case, one can "
"poradit, aby jej přeskakovala. <_:example-1/>"
#. (itstool) path: note/title
-#: C/index.docbook:713
+#: C/index.docbook:719
msgid "Limitations"
msgstr "Omezení"
#. (itstool) path: note/para
-#: C/index.docbook:714
+#: C/index.docbook:720
msgid ""
"Note, that GTK-Doc's supports <code>#ifndef(__GTK_DOC_IGNORE__)</code> but "
"not <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations."
"ale ne <code>#if !defined(__GTK_DOC_IGNORE__)</code> nebo jiné kombinace."
#. (itstool) path: sect1/title
-#: C/index.docbook:724
+#: C/index.docbook:730
msgid "Documentation comments"
msgstr "Dokumentační komentáře"
#. (itstool) path: example/programlisting
-#: C/index.docbook:730
+#: C/index.docbook:736
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:726
+#: C/index.docbook:732
msgid ""
"A multiline comment that starts with an additional '*' marks a documentation "
"block that will be processed by the GTK-Doc tools. <_:example-1/>"
"dokumentačním blokem a bude zpracovaný nástroji GTK-Doc. <_:example-1/>"
#. (itstool) path: sect1/para
-#: C/index.docbook:739
+#: C/index.docbook:745
msgid ""
"The 'identifier' is one line with the name of the item the comment is "
"related to. The syntax differs a little depending on the item. (TODO add "
"se seznamem identifikátorů)"
#. (itstool) path: sect1/para
-#: C/index.docbook:745
+#: C/index.docbook:751
msgid ""
"The 'documentation' block is also different for each symbol type. Symbol "
"types that get parameters such as functions or macros have the parameter "
"hvězdička mezera mezera). To se hodí na text s pevným formátem (výpis kódu)."
#. (itstool) path: listitem/para
-#: C/index.docbook:762
+#: C/index.docbook:768
msgid ""
"What it is: The name for a class or function can sometimes be misleading for "
"people coming from a different background."
"používají něco jiného."
#. (itstool) path: listitem/para
-#: C/index.docbook:768
+#: C/index.docbook:774
msgid ""
"What it does: Tell about common uses. Put it in relation with the other API."
msgstr ""
"K čemu to je: Uveďte běžném použití. Dejte ho do souvislosti se zbytkem API."
#. (itstool) path: tip/para
-#: C/index.docbook:758
+#: C/index.docbook:764
msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>"
msgstr ""
"Když píšete dokumentaci ke kódu, popište dva aspekty: <_:itemizedlist-1/>"
#. (itstool) path: listitem/para
-#: C/index.docbook:783
+#: C/index.docbook:789
msgid "Use function() to refer to functions or macros which take arguments."
msgstr ""
"Použijte funkce() pro odkaz na funkci nebo makro, které mají argumenty."
#. (itstool) path: listitem/para
-#: C/index.docbook:788
+#: C/index.docbook:794
msgid ""
"Use @param to refer to parameters. Also use this when referring to "
"parameters of other functions, related to the one being described."
"odkazujete na parametry jiných funkcí, vztahujících se k popisované funkci."
#. (itstool) path: listitem/para
-#: C/index.docbook:794
+#: C/index.docbook:800
msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS."
msgstr "Použijte %konstanta pro odkaz na konstantu, např. %G_TRAVERSE_LEAFS."
#. (itstool) path: listitem/para
-#: C/index.docbook:799
+#: C/index.docbook:805
msgid ""
"Use #symbol to refer to other types of symbol, e.g. structs and enums and "
"macros which don't take arguments."
"makro, který nemá argumenty."
#. (itstool) path: listitem/para
-#: C/index.docbook:805
+#: C/index.docbook:811
msgid "Use #Object::signal to refer to a GObject signal."
msgstr "Použijte #Objekt::signál pro odkaz na signál objektu GObject."
#. (itstool) path: listitem/para
-#: C/index.docbook:810
+#: C/index.docbook:816
msgid "Use #Object:property to refer to a GObject property."
msgstr "Použijte #Objekt:vlastnost pro odkaz na vlastnost objektu GObject."
#. (itstool) path: listitem/para
-#: C/index.docbook:815
+#: C/index.docbook:821
msgid ""
"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
"foo_bar() to refer to a vmethod."
"neco() pro odkaz na virtuální metodu."
#. (itstool) path: sect1/para
-#: C/index.docbook:777
+#: C/index.docbook:783
msgid ""
"One advantage of hyper-text over plain-text is the ability to have links in "
"the document. Writing the correct markup for a link can be tedious though. "
"vám snaží pomoci několika užitečnými zkratkami. <_:itemizedlist-1/>"
#. (itstool) path: tip/para
-#: C/index.docbook:824
+#: C/index.docbook:830
msgid ""
"If you need to use the special characters '<', '>', '()', '@', '%', or "
"'#' in your documentation without GTK-Doc changing them you can use the XML "
"se zpětným lomítkem „\\“."
#. (itstool) path: sect1/para
-#: C/index.docbook:833
+#: C/index.docbook:839
msgid ""
"DocBook can do more than just links. One can also have lists, examples, "
"headings, and images. As of version 1.20, the preferred way is to use a "
"začátku."
#. (itstool) path: sect1/para
-#: C/index.docbook:844
+#: C/index.docbook:850
msgid ""
"While markdown is now preferred one can mix both. One limitation here is "
"that one can use docbook xml within markdown, but markdown within docbook "
"markdown v docbook xml podporován není."
#. (itstool) path: sect1/para
-#: C/index.docbook:850
+#: C/index.docbook:856
msgid ""
"In older GTK-Doc releases, if you need support for additional formatting, "
"you would need to enable the usage of docbook XML tags inside doc-comments "
"<filename>Makefile.am</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:859
+#: C/index.docbook:865
msgid "GTK-Doc comment block using Markdown"
msgstr "Komentářový blok GTK-Doc používající značkovací jazyk"
#. (itstool) path: example/programlisting
-#: C/index.docbook:860
+#: C/index.docbook:866
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:899
+#: C/index.docbook:905
msgid ""
"More examples of what markdown tags are supported can be found in the <ulink "
"url=\"https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown"
"\">Referenční příručce k syntaxi Markdown pro dokumentaci GTK+</ulink>."
#. (itstool) path: tip/para
-#: C/index.docbook:905
+#: C/index.docbook:911
msgid ""
"As already mentioned earlier GTK-Doc is for documenting public API. Thus one "
"cannot write documentation for static symbols. Nevertheless it is good to "
"správné místo v souboru oddílů vložit název symbolu."
#. (itstool) path: sect1/title
-#: C/index.docbook:919
+#: C/index.docbook:925
msgid "Documenting sections"
msgstr "Dokumentování oddílů"
#. (itstool) path: sect1/para
-#: C/index.docbook:921
+#: C/index.docbook:927
msgid ""
"Each section of the documentation contains information about one class or "
"module. To introduce the component one can write a section block. The short "
"použije v rámci tabulky s obsahem. Všechna @pole jsou volitelná."
#. (itstool) path: example/title
-#: C/index.docbook:929
+#: C/index.docbook:935
msgid "Section comment block"
msgstr "Komentářový blok oddílu"
#. (itstool) path: example/programlisting
-#: C/index.docbook:930
+#: C/index.docbook:936
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:949
+#: C/index.docbook:955
msgid "SECTION:<name>"
msgstr "SECTION:<název>"
#. (itstool) path: listitem/para
-#: C/index.docbook:951
+#: C/index.docbook:957
msgid ""
"The name links the section documentation to the respective part in the "
"<filename><package>-sections.txt</filename> file. The name given here "
"<SOUBOR> v souboru <filename><package>-sections.txt</filename>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:960
+#: C/index.docbook:966
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:962
+#: C/index.docbook:968
msgid ""
"A one line description of the section, that later will appear after the "
"links in the TOC and at the top of the section page."
"obsahem a na začátku stránky oddílu."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:969
+#: C/index.docbook:975
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:971
+#: C/index.docbook:977
msgid ""
"The section title defaults to <name> from the SECTION declaration. It "
"can be overridden with the @title field."
"jej ale určit i přímo v poli @title."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:978
+#: C/index.docbook:984
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:980
+#: C/index.docbook:986
msgid ""
"Overrides the use of title as a section identifier. For GObjects the <"
"title> is used as a section_id and for other sections it is <"
"MODULE>-<title>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:988
+#: C/index.docbook:994
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:990
+#: C/index.docbook:996
msgid "A list of symbols that are related to this section."
msgstr "Seznam symbolů, které se vztahují k tomuto oddílu."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:996
+#: C/index.docbook:1002
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1003
+#: C/index.docbook:1009
msgid ""
"Stable - The intention of a Stable interface is to enable arbitrary third "
"parties to develop applications to these interfaces, release them, and have "
"nekompatibilní změny očekávají zřídka v opravdu odůvodněných případech."
#. (itstool) path: listitem/para
-#: C/index.docbook:1015
+#: C/index.docbook:1021
msgid ""
"Unstable - Unstable interfaces are experimental or transitional. They are "
"typically used to give outside developers early access to new or rapidly "
"následujíc."
#. (itstool) path: listitem/para
-#: C/index.docbook:1027
+#: C/index.docbook:1033
msgid ""
"Private - An interface that can be used within the GNOME stack itself, but "
"that is not documented for end-users. Such functions should only be used in "
"měly používat jen určeným a dokumentovaným způsobem."
#. (itstool) path: listitem/para
-#: C/index.docbook:1036
+#: C/index.docbook:1042
msgid ""
"Internal - An interface that is internal to a module and does not require "
"end-user documentation. Functions that are undocumented are assumed to be "
"nedokumentované, jsou považované za interní."
#. (itstool) path: listitem/para
-#: C/index.docbook:998
+#: C/index.docbook:1004
msgid ""
"An informal description of the stability level this API has. We recommend "
"the use of one of these terms: <_:itemizedlist-1/>"
"těchto termínů: <_:itemizedlist-1/>"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1048
+#: C/index.docbook:1054
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1050
+#: C/index.docbook:1056
msgid ""
"The <literal>#include</literal> files to show in the section synopsis (a "
"comma separated list), overriding the global value from the <link linkend="
"položka je volitelná."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1059
+#: C/index.docbook:1065
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1061
+#: C/index.docbook:1067
msgid ""
"The image to display at the top of the reference page for this section. This "
"will often be some sort of a diagram to illustrate the visual appearance of "
"nebo nákres se vztahy vůči jiným třídám. Tato položka je volitelná."
#. (itstool) path: tip/para
-#: C/index.docbook:1072
+#: C/index.docbook:1078
msgid ""
"To avoid unnecessary recompilation after doc-changes put the section docs "
"into the c-source where possible."
"vložte, kde je to možné, dokumentaci oddílu do zdrojového kódu c."
#. (itstool) path: sect1/title
-#: C/index.docbook:1081
+#: C/index.docbook:1087
msgid "Documenting symbols"
msgstr "Dokumentování symbolů"
#. (itstool) path: sect1/para
-#: C/index.docbook:1083
+#: C/index.docbook:1089
msgid ""
"Each symbol (function, macro, struct, enum, signal and property) is "
"documented in a separate block. The block is best placed close to the "
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1091 C/index.docbook:1157
+#: C/index.docbook:1097 C/index.docbook:1163
msgid "General tags"
msgstr "Obecné značky"
#. (itstool) path: sect2/para
-#: C/index.docbook:1093
+#: C/index.docbook:1099
msgid ""
"You can add versioning information to all documentation elements to tell "
"when an API was introduced, or when it was deprecated."
"sdělili, kdy bylo API zavedeno, nebo kdy bylo označeno za zastaralé."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1098
+#: C/index.docbook:1104
msgid "Versioning Tags"
msgstr "Značky pro verzování"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1099
+#: C/index.docbook:1105
msgid "Since:"
msgstr "Since:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1101
+#: C/index.docbook:1107
msgid "Description since which version of the code the API is available."
msgstr "Popisuje, od které verze kódu je API dostupné."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1106
+#: C/index.docbook:1112
msgid "Deprecated:"
msgstr "Deprecated:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1108
+#: C/index.docbook:1114
msgid ""
"Paragraph denoting that this function should no be used anymore. The "
"description should point the reader to the new API."
"měl čtenáře odkazovat na nové API."
#. (itstool) path: sect2/para
-#: C/index.docbook:1116
+#: C/index.docbook:1122
msgid ""
"You can also add stability information to all documentation elements to "
"indicate whether API stability is guaranteed for them for all future minor "
"minoritní vydání projektu."
#. (itstool) path: sect2/para
-#: C/index.docbook:1122
+#: C/index.docbook:1128
msgid ""
"The default stability level for all documentation elements can be set by "
"passing the <option>--default-stability</option> argument to "
"do <application>gtkdoc-mkdb</application>."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1128
+#: C/index.docbook:1134
msgid "Stability Tags"
msgstr "Značky pro stabilitu"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1129
+#: C/index.docbook:1135
msgid "Stability: Stable"
msgstr "Stability: Stable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1131
+#: C/index.docbook:1137
msgid ""
"Mark the element as stable. This is for public APIs which are guaranteed to "
"remain stable for all future minor releases of the project."
"že zůstanou stabilní po všechna minoritní vydání projektu."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1138
+#: C/index.docbook:1144
msgid "Stability: Unstable"
msgstr "Stability: Unstable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1140
+#: C/index.docbook:1146
msgid ""
"Mark the element as unstable. This is for public APIs which are released as "
"a preview before being stabilised."
"vydána jako ukázky před tím, než jsou stabilizována."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1146
+#: C/index.docbook:1152
msgid "Stability: Private"
msgstr "Stability: Private"
#. (itstool) path: listitem/para
-#: C/index.docbook:1148
+#: C/index.docbook:1154
msgid ""
"Mark the element as private. This is for interfaces which can be used by "
"tightly coupled modules, but not by arbitrary third parties."
"použita přímo v modulu, ale ne kterýmikoliv třetími stranami."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1158
+#: C/index.docbook:1164
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1178 C/index.docbook:1188
+#: C/index.docbook:1184 C/index.docbook:1194
msgid "Annotations"
msgstr "Anotace"
#. (itstool) path: sect2/para
-#: C/index.docbook:1180
+#: C/index.docbook:1186
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"org/GObjectIntrospection/Annotations\" type=\"http\">wiki</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1189
+#: C/index.docbook:1195
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1210 C/index.docbook:1239
+#: C/index.docbook:1216 C/index.docbook:1245
msgid "Function comment block"
msgstr "Komentářový blok pro funkci"
#. (itstool) path: listitem/para
-#: C/index.docbook:1216
+#: C/index.docbook:1222
msgid ""
"Document whether returned objects, lists, strings, etc, should be freed/"
"unrefed/released."
"uvolnit z paměti."
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1228
msgid "Document whether parameters can be NULL, and what happens if they are."
msgstr ""
"Zdokumentovat, jestli může parametr být NULL a co se stane, když tomu tak je."
#. (itstool) path: listitem/para
-#: C/index.docbook:1227
+#: C/index.docbook:1233
msgid ""
"Mention interesting pre-conditions and post-conditions where appropriate."
msgstr "Kde je to vhodné, zmínit úvodní a koncové podmínky."
#. (itstool) path: sect2/para
-#: C/index.docbook:1212 C/index.docbook:1298
+#: C/index.docbook:1218 C/index.docbook:1304
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Nezapomeňte prosím: <_:itemizedlist-1/>"
#. (itstool) path: sect2/para
-#: C/index.docbook:1234
+#: C/index.docbook:1240
msgid ""
"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
"private. They are treated like static functions."
"„_“, jsou soukromé. Potom se s nimi zachází jako se statickými funkcemi."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1240
+#: C/index.docbook:1246
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1261
+#: C/index.docbook:1267
msgid "Function tags"
msgstr "Značky pro funkce"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1262 C/index.docbook:1469
+#: C/index.docbook:1268 C/index.docbook:1475
msgid "Returns:"
msgstr "Returns:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1264
+#: C/index.docbook:1270
msgid "Paragraph describing the returned result."
msgstr "Odstavec popisující vracený výsledek."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1269
+#: C/index.docbook:1275
msgid "@...:"
msgstr "@…:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1271
+#: C/index.docbook:1277
msgid ""
"In case the function has variadic arguments, you should use this tag "
"(@Varargs: does also work for historic reasons)."
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1281 C/index.docbook:1283
+#: C/index.docbook:1287 C/index.docbook:1289
msgid "Property comment block"
msgstr "Komentářový blok pro vlastnost"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1284
+#: C/index.docbook:1290
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1296 C/index.docbook:1315
+#: C/index.docbook:1302 C/index.docbook:1321
msgid "Signal comment block"
msgstr "Komentářový blok pro signál"
#. (itstool) path: listitem/para
-#: C/index.docbook:1302
+#: C/index.docbook:1308
msgid ""
"Document when the signal is emitted and whether it is emitted before or "
"after other signals."
"ostatních signálech."
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1314
msgid "Document what an application might do in the signal handler."
msgstr "Zdokumentovat, co aplikace smí v obsluze signálu provádět."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1316
+#: C/index.docbook:1322
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1333 C/index.docbook:1334
+#: C/index.docbook:1339 C/index.docbook:1340
msgid "Struct comment block"
msgstr "Komentářový blok pro strukturu"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1335
+#: C/index.docbook:1341
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1350
+#: C/index.docbook:1356
msgid ""
"Use <code>/*< private >*/</code> before the private struct fields you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"*/</code>."
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1362
msgid ""
"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" "
"it will be considered private automatically and doesn't need to be mentioned "
"komentářovém bloku."
#. (itstool) path: sect2/para
-#: C/index.docbook:1362
+#: C/index.docbook:1368
msgid ""
"Struct comment blocks can also be used for GObjects and GObjectClasses. It "
"is usually a good idea to add a comment block for a class, if it has "
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1374 C/index.docbook:1375
+#: C/index.docbook:1380 C/index.docbook:1381
msgid "Enum comment block"
msgstr "Komentářový blok pro výčty"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1376
+#: C/index.docbook:1382
#, no-wrap
msgid ""
"\n"
"} Something;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1393
+#: C/index.docbook:1399
msgid ""
"Use <code>/*< private >*/</code> before the private enum values you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"public >*/</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1404
+#: C/index.docbook:1410
msgid "Inline program documentation"
msgstr "Dokumentaci k vloženým programům"
#. (itstool) path: sect1/para
-#: C/index.docbook:1405
+#: C/index.docbook:1411
msgid ""
"You can document programs and their commandline interface using inline "
"documentation."
"vložené dokumentace."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1411
+#: C/index.docbook:1417
msgid "Tags"
msgstr "Značky"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1413
+#: C/index.docbook:1419
msgid "PROGRAM"
msgstr "PROGRAM"
#. (itstool) path: listitem/para
-#: C/index.docbook:1416
+#: C/index.docbook:1422
msgid "Defines the start of a program documentation."
msgstr "Definuje začátek dokumentace k programu."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1423
+#: C/index.docbook:1429
msgid "@short_description:"
msgstr "@short_description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1425
+#: C/index.docbook:1431
msgid "Defines a short description of the program. (Optional)"
msgstr "Definuje krátký popis programu. (volitelné)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1432
+#: C/index.docbook:1438
msgid "@synopsis:"
msgstr "@synopsis:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1434
+#: C/index.docbook:1440
msgid ""
"Defines the arguments, or list of arguments that the program can take. "
"(Optional)"
"Definuje argumenty nebo seznam argumentů, které program přebírá. (volitelné)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1442
+#: C/index.docbook:1448
msgid "@see_also:"
msgstr "@see_also:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1444
+#: C/index.docbook:1450
msgid "See Also manual page section. (Optional)"
msgstr "Část stránky oddílu „Viz také“. (volitelné)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1451
+#: C/index.docbook:1457
msgid "@arg:"
msgstr "@arg:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1453
+#: C/index.docbook:1459
msgid "Argument(s) passed to the program and their description. (Optional)"
msgstr "Argument(y) předávané do programu a jejich popis. (volitelné)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1460
+#: C/index.docbook:1466
msgid "Description:"
msgstr "Description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1462
+#: C/index.docbook:1468
msgid "A longer description of the program."
msgstr "Úplný popis programu."
#. (itstool) path: listitem/para
-#: C/index.docbook:1471
+#: C/index.docbook:1477
msgid "Specificy what value(s) the program returns. (Optional)"
msgstr "Specifikuje, jakou hodnotu či více hodnot program vrací. (volitelné)"
#. (itstool) path: sect2/title
-#: C/index.docbook:1480
+#: C/index.docbook:1486
msgid "Example of program documentation."
msgstr "Příklad dokumentace k programu."
#. (itstool) path: example/title
-#: C/index.docbook:1481
+#: C/index.docbook:1487
msgid "Program documentation block"
msgstr "Komentářový blok pro program"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1482
+#: C/index.docbook:1488
#, no-wrap
msgid ""
"\n"
"}\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1508
+#: C/index.docbook:1514
msgid "Useful DocBook tags"
msgstr "Užitečné značky DocBook"
#. (itstool) path: sect1/para
-#: C/index.docbook:1510
+#: C/index.docbook:1516
msgid ""
"Here are some DocBook tags which are most useful when documenting the code."
msgstr ""
"význam."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1519
+#: C/index.docbook:1525
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Hašovací tabulky</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1515
+#: C/index.docbook:1521
msgid ""
"To link to another section in the GTK docs: <_:informalexample-1/> The "
"linkend is the SGML/XML id on the top item of the page you want to link to. "
"podtržítka se převedou na „-“, aby to vyhovovalo SGML/XML."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1532
+#: C/index.docbook:1538
#, no-wrap
msgid ""
"\n"
"<function>…</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1529
+#: C/index.docbook:1535
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
">"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1541
+#: C/index.docbook:1547
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1552
+#: C/index.docbook:1558
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1538
+#: C/index.docbook:1544
msgid ""
"To include example code: <_:informalexample-1/> or possibly this, for very "
"short code fragments which don't need a title: <_:informalexample-2/> For "
"V novějších verzích GTK-Doc je také podporované zkracování: |[ … ]|"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1571
+#: C/index.docbook:1577
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1568
+#: C/index.docbook:1574
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Vložení seznamu s odrážkami: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1591
+#: C/index.docbook:1597
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1588
+#: C/index.docbook:1594
msgid ""
"To include a note which stands out from the text: <_:informalexample-1/>"
msgstr "Vložení poznámky, která se objeví mimo text: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1604
+#: C/index.docbook:1610
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1601
+#: C/index.docbook:1607
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "Odkaz na typ: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1613
+#: C/index.docbook:1619
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1610
+#: C/index.docbook:1616
msgid ""
"To refer to an external structure (not one described in the GTK docs): <_:"
"informalexample-1/>"
"informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1622
+#: C/index.docbook:1628
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1619
+#: C/index.docbook:1625
msgid "To refer to a field of a structure: <_:informalexample-1/>"
msgstr "Odkaz na pole struktury: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1631
+#: C/index.docbook:1637
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1628
+#: C/index.docbook:1634
msgid ""
"To refer to a class name, we could possibly use: <_:informalexample-1/> but "
"you'll probably be using #GtkWidget instead (to automatically create a link "
"\"documenting_syntax\">zkratky</link>)."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1642
+#: C/index.docbook:1648
#, no-wrap
msgid ""
"\n"
"<emphasis>Toto je důležité</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1639
+#: C/index.docbook:1645
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Zvýrazněný text: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1651
+#: C/index.docbook:1657
#, no-wrap
msgid ""
"\n"
"<filename>/home/user/documents</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1648
+#: C/index.docbook:1654
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Pro název souboru použijte: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1660
+#: C/index.docbook:1666
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1657
+#: C/index.docbook:1663
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "Odkaz na použití klávesy: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1670
+#: C/index.docbook:1676
msgid "Filling the extra files"
msgstr "Vyplňování dodatečných souborů"
#. (itstool) path: chapter/para
-#: C/index.docbook:1672
+#: C/index.docbook:1678
msgid ""
"There are a couple of extra files, that need to be maintained along with the "
"inline source code comments: <filename><package>.types</filename>, "
"<filename><balíček>-sections.txt</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1681
+#: C/index.docbook:1687
msgid "Editing the types file"
msgstr "Úprava souboru s typy"
#. (itstool) path: sect1/para
-#: C/index.docbook:1683
+#: C/index.docbook:1689
msgid ""
"If your library or application includes GObjects, you want their signals, "
"arguments/parameters and position in the hierarchy to be shown in the "
"filename>."
#. (itstool) path: example/title
-#: C/index.docbook:1692
+#: C/index.docbook:1698
msgid "Example types file snippet"
msgstr "Příklad úryvku ze souboru typů"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1693
+#: C/index.docbook:1699
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1704
+#: C/index.docbook:1710
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"byste soubor s typy šířit do správy verzí."
#. (itstool) path: sect1/title
-#: C/index.docbook:1713
+#: C/index.docbook:1719
msgid "Editing the master document"
msgstr "Úprava hlavního dokumentu"
#. (itstool) path: sect1/para
-#: C/index.docbook:1715
+#: C/index.docbook:1721
msgid ""
"GTK-Doc produces documentation in DocBook SGML/XML. When processing the "
"inline source comments, the GTK-Doc tools generate one documentation page "
"soubor. Všechny jsou pak uvedené seřazené v hlavním dokumentu."
#. (itstool) path: sect1/para
-#: C/index.docbook:1722
+#: C/index.docbook:1728
msgid ""
"While GTK-Doc creates a template master document for you, later runs will "
"not touch it again. This means that one can freely structure the "
"nahlédnout, jestli se v něm neobjevily nějaké nové věci."
#. (itstool) path: tip/para
-#: C/index.docbook:1732
+#: C/index.docbook:1738
msgid ""
"Do not create tutorials as extra documents. Just write extra chapters. The "
"benefit of directly embedding the tutorial for your library into the API "
"v knihovně."
#. (itstool) path: sect1/para
-#: C/index.docbook:1741
+#: C/index.docbook:1747
msgid ""
"So what are the things to change inside the master document? For a start is "
"only a little. There are some placeholders (text in square brackets) there "
"závorkách), o které byste se měli postarat."
#. (itstool) path: example/title
-#: C/index.docbook:1748
+#: C/index.docbook:1754
msgid "Master document header"
msgstr "Hlavička hlavního dokumentu"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1749
+#: C/index.docbook:1755
#, no-wrap
msgid ""
"\n"
" <title>[Insert title here]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1765
+#: C/index.docbook:1771
msgid ""
"In addition a few option elements are created in commented form. You can "
"review these and enable them as you like."
"projít a případně povolit."
#. (itstool) path: example/title
-#: C/index.docbook:1771
+#: C/index.docbook:1777
msgid "Optional part in the master document"
msgstr "Volitelná část hlavního dokumentu"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1772
+#: C/index.docbook:1778
#, no-wrap
msgid ""
"\n"
" -->\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1780
+#: C/index.docbook:1786
msgid ""
"Finally you need to add new section whenever you introduce one. The <link "
"linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> tool will remind "
"vygenerované soubory XML, které zatím nejsou v dokumentaci zahrnuté."
#. (itstool) path: example/title
-#: C/index.docbook:1788 C/index.docbook:1823
+#: C/index.docbook:1794 C/index.docbook:1829
msgid "Including generated sections"
msgstr "Vkládání generovaných oddílů"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1789
+#: C/index.docbook:1795
#, no-wrap
msgid ""
"\n"
" …\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1801
+#: C/index.docbook:1807
msgid "Editing the section file"
msgstr "Úprava souboru oddílů"
#. (itstool) path: sect1/para
-#: C/index.docbook:1803
+#: C/index.docbook:1809
msgid ""
"The section file is used to organise the documentation output by GTK-Doc. "
"Here one specifies which symbol belongs to which module or class and control "
"viditelnost (jestli je veřejný nebo soukromý)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1809
+#: C/index.docbook:1815
msgid ""
"The section file is a plain text file with tags delimiting sections. Blank "
"lines are ignored and lines starting with a '#' are treated as comment lines."
"jako s komentářovými řádky."
#. (itstool) path: note/para
-#: C/index.docbook:1816
+#: C/index.docbook:1822
msgid ""
"While the tags make the file look like xml, it is not. Please do not close "
"tags like <SUBSECTION>."
"Neuzavírejte prosím značky jako je <SUBSECTION>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1824
+#: C/index.docbook:1830
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1841
+#: C/index.docbook:1847
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"názvu třídy GObject převedeného na malá písmena.)"
#. (itstool) path: sect1/para
-#: C/index.docbook:1853
+#: C/index.docbook:1859
msgid ""
"The <TITLE> ... </TITLE> tag is used to specify the title of the "
"section. It is only useful before the templates (if used) are initially "
"zdrojovém kódu."
#. (itstool) path: sect1/para
-#: C/index.docbook:1860
+#: C/index.docbook:1866
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"virtuální metody)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1879
+#: C/index.docbook:1885
msgid ""
"You can also use <INCLUDE> ... </INCLUDE> to specify the "
"#include files which are shown in the synopsis sections. It contains a comma-"
"konce souboru. Když je nastavíte v konkrétním oddílu, použijí se jen pro něj."
#. (itstool) path: chapter/title
-#: C/index.docbook:1893
+#: C/index.docbook:1899
msgid "Controlling the result"
msgstr "Ovlivnění výsledku"
#. (itstool) path: chapter/para
-#: C/index.docbook:1895
+#: C/index.docbook:1901
msgid ""
"A GTK-Doc run generates report files inside the documentation directory. The "
"generated files are named: <filename><package>-undocumented.txt</"
"prosté textové soubory, které si lze jednoduše prohlížet a zpracovávat je."
#. (itstool) path: chapter/para
-#: C/index.docbook:1904
+#: C/index.docbook:1910
msgid ""
"The <filename><package>-undocumented.txt</filename> file starts with "
"the documentation coverage summary. Below are two sections divided by blank "
"parametr."
#. (itstool) path: chapter/para
-#: C/index.docbook:1913
+#: C/index.docbook:1919
msgid ""
"The <filename><package>-undeclared.txt</filename> file lists symbols "
"given in the <filename><package>-sections.txt</filename> but not found "
"v nich není překlep."
#. (itstool) path: chapter/para
-#: C/index.docbook:1920
+#: C/index.docbook:1926
msgid ""
"The <filename><package>-unused.txt</filename> file lists symbol names, "
"where the GTK-Doc scanner has found documentation, but does not know where "
"balíček>-section.txt</filename>."
#. (itstool) path: tip/para
-#: C/index.docbook:1928
+#: C/index.docbook:1934
msgid ""
"Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile."
"am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during "
"správnosti údajů."
#. (itstool) path: chapter/para
-#: C/index.docbook:1935
+#: C/index.docbook:1941
msgid ""
"One can also look at the files produced by the source code scanner: "
"<filename><package>-decl-list.txt</filename> and <filename><"
"zkontrolovat, jestli se vyskytuje v tomto souboru."
#. (itstool) path: chapter/para
-#: C/index.docbook:1944
+#: C/index.docbook:1950
msgid ""
"If the project is GObject based, one can also look into the files produced "
"by the object scanner: <filename><package>.args.txt</filename>, "
"Doc, aby přechodně zachovat soubor pro pozdější analýzu."
#. (itstool) path: chapter/title
-#: C/index.docbook:1959
+#: C/index.docbook:1965
msgid "Modernizing the documentation"
msgstr "Modernizace dokumentu"
#. (itstool) path: chapter/para
-#: C/index.docbook:1961
+#: C/index.docbook:1967
msgid ""
"GTK-Doc has been around for quite some time. In this section we list new "
"features together with the version since when it is available."
"funkcí spolu s číslem verze, od které je tato funkčnost k dispozici."
#. (itstool) path: sect1/title
-#: C/index.docbook:1967
+#: C/index.docbook:1973
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1969
+#: C/index.docbook:1975
msgid ""
"When using xml instead of sgml, one can actually name the master document "
"<filename><package>-docs.xml</filename>."
"dokument <filename><package>-docs.xml</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1974
+#: C/index.docbook:1980
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-sections</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"<code>meld <package>-decl-list.txt <package>-sections.txt</code>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1985
+#: C/index.docbook:1991
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"tuto volbu do <filename>configure.ac</filename> a je to."
#. (itstool) path: sect1/title
-#: C/index.docbook:1997
+#: C/index.docbook:2003
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:1999
+#: C/index.docbook:2005
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"filename> pro kód, který je sestavován podmíněně."
#. (itstool) path: sect1/title
-#: C/index.docbook:2010
+#: C/index.docbook:2016
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:2016
+#: C/index.docbook:2022
msgid "Enable gtkdoc-check"
msgstr "Povolení gtkdoc-check"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2017
+#: C/index.docbook:2023
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2012
+#: C/index.docbook:2018
msgid ""
"This version includes a new tool called gtkdoc-check. This tool can run a "
"set of sanity checks on your documentation. It is enabled by adding these "
">"
#. (itstool) path: sect1/title
-#: C/index.docbook:2030
+#: C/index.docbook:2036
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:2032
+#: C/index.docbook:2038
msgid ""
"Version 1.18 brought some initial markdown support. Using markdown in doc "
"comments is less intrusive than writing docbook xml. This version improves a "
"\"documenting_syntax\">syntax komentářů</link>."
#. (itstool) path: sect1/title
-#: C/index.docbook:2042
+#: C/index.docbook:2048
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:2052
+#: C/index.docbook:2058
msgid "Use pre-generated entities"
msgstr "Používání předgenerovaných entit"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2053
+#: C/index.docbook:2059
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2044
+#: C/index.docbook:2050
msgid ""
"The makefiles shipped with this version generate an entity file at "
"<filename>xml/gtkdocentities.ent</filename>, containing entities for e.g. "
"hlavičku XML v generovaných souborech XML. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:2078
+#: C/index.docbook:2084
msgid "Documenting other interfaces"
msgstr "Dokumentování ostatních rozhraní"
#. (itstool) path: chapter/para
-#: C/index.docbook:2080
+#: C/index.docbook:2086
msgid ""
"So far we have been using GTK-Doc to document the API of code. The next "
"sections contain suggestions how the tools can be used to document other "
"dalších rozhraní."
#. (itstool) path: sect1/title
-#: C/index.docbook:2087
+#: C/index.docbook:2093
msgid "Command line options and man pages"
msgstr "Přepínače příkazového řádku a manuálové stránky"
#. (itstool) path: sect1/para
-#: C/index.docbook:2089
+#: C/index.docbook:2095
msgid ""
"As one can generate man pages for a docbook refentry as well, it sounds like "
"a good idea to use it for that purpose. This way the interface is part of "
"manuálovou stránku."
#. (itstool) path: sect2/title
-#: C/index.docbook:2096
+#: C/index.docbook:2102
msgid "Document the tool"
msgstr "Dokumentování nástrojů"
#. (itstool) path: sect2/para
-#: C/index.docbook:2098
+#: C/index.docbook:2104
msgid ""
"Create one refentry file per tool. Following <link linkend="
"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
"souboru v podsložce XML, například v glib."
#. (itstool) path: sect2/title
-#: C/index.docbook:2108
+#: C/index.docbook:2114
msgid "Adding the extra configure check"
msgstr "Přidání doplňkových kontrol do configure"
#. (itstool) path: example/title
-#: C/index.docbook:2111 C/index.docbook:2129
+#: C/index.docbook:2117 C/index.docbook:2135
msgid "Extra configure checks"
msgstr "Dodatečné kontroly nastavení"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2112
+#: C/index.docbook:2118
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2126
+#: C/index.docbook:2132
msgid "Adding the extra makefile rules"
msgstr "Přidání doplňkových pravidel do Makefile"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2130
+#: C/index.docbook:2136
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2152
+#: C/index.docbook:2158
msgid "DBus interfaces"
msgstr "Rozhraní D-Bus"
#. (itstool) path: sect1/para
-#: C/index.docbook:2154
+#: C/index.docbook:2160
msgid ""
"(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://"
"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
#. (itstool) path: chapter/title
-#: C/index.docbook:2163
+#: C/index.docbook:2169
msgid "Frequently asked questions"
msgstr "Často kladené dotazy"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2167
+#: C/index.docbook:2173
msgid "Question"
msgstr "Dotaz"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2168
+#: C/index.docbook:2174
msgid "Answer"
msgstr "Odpověď"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2170
+#: C/index.docbook:2176
msgid "No class hierarchy."
msgstr "Schází hierarchie třídy."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2171
+#: C/index.docbook:2177
msgid ""
"The objects <function>xxx_get_type()</function> function has not been "
"entered into the <filename><package>.types</filename> file."
"objektu <function>xxx_get_type()</function>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2177
+#: C/index.docbook:2183
msgid "Still no class hierarchy."
msgstr "Stále schází hierarchie třídy."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2178
+#: C/index.docbook:2184
msgid ""
"Missing or wrong naming in <filename><package>-sections.txt</filename> "
"file (see <ulink url=\"http://mail.gnome.org/archives/gtk-doc-list/2003-"
"doc-list/2003-October/msg00006.html\">vysvětlení</ulink>)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2184
+#: C/index.docbook:2190
msgid "Damn, I have still no class hierarchy."
msgstr "Do háje, pořád nemám hierarchii třídy."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2185
+#: C/index.docbook:2191
msgid ""
"Is the object name (name of the instance struct, e.g. <type>GtkWidget</"
"type>) part of the normal section (don't put this into Standard or Private "
"Private)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2192
+#: C/index.docbook:2198
msgid "No symbol index."
msgstr "Chybí rejstřík symbolů."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2193
+#: C/index.docbook:2199
msgid ""
"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
"index that xi:includes the generated index?"
"který vloží pomocí xi:include vygenerovaný rejstřík?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2199
+#: C/index.docbook:2205
msgid "Symbols are not linked to their doc-section."
msgstr "Symbol nemá odkaz do svého oddílu dokumentace."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2200
+#: C/index.docbook:2206
msgid ""
"Is the doc-comment using the correct markup (added #,% or ())? Check if the "
"gtkdoc-fixxref warns about unresolvable xrefs."
"Podívejte se na varování gtkdoc-fixxref o nevyřešených křížových odkazech."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2206
+#: C/index.docbook:2212
msgid "A new class does not appear in the docs."
msgstr "Nová třída se neobjevila v dokumentaci."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2207
+#: C/index.docbook:2213
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"{xml,sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2213
+#: C/index.docbook:2219
msgid "A new symbol does not appear in the docs."
msgstr "Nový symbol se neobjevil v dokumentaci."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2214
+#: C/index.docbook:2220
msgid ""
"Is the doc-comment properly formatted. Check for spelling mistakes in the "
"begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable "
"<filename><package>-sections.txt</filename> ve veřejném pododdíle."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2222
+#: C/index.docbook:2228
msgid "A type is missing from the class hierarchy."
msgstr "V hierarchii třídy schází typ."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2223
+#: C/index.docbook:2229
msgid ""
"If the type is listed in <filename><package>.hierarchy</filename> but "
"not in <filename>xml/tree_index.sgml</filename> then double check that the "
"zobrazena."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2232
+#: C/index.docbook:2238
msgid "I get foldoc links for all gobject annotations."
msgstr ""
"Vytvořily se mi odkazy na složku s dokumentací pro všechny anotace k GObject"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2233
+#: C/index.docbook:2239
msgid ""
"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
"from <filename><package>-docs.{xml,sgml}</filename>."
"pomocí xi:include z <filename><package>-docs.{xml,sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2241
+#: C/index.docbook:2247
msgid "Parameter described in source code comment block but does not exist"
msgstr ""
"Parametr je v komentářovém bloku zdrojového kódu popsaný, ale neexistuje."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2242
+#: C/index.docbook:2248
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
"než ve zdrojovém kódu."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2247
+#: C/index.docbook:2253
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "Více „ID“ pro tentýž cíl odkazu: XYZ"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2248
+#: C/index.docbook:2254
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"objevuje dvakrát."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2251
+#: C/index.docbook:2257
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"mu žádná šablona."
#. (itstool) path: chapter/title
-#: C/index.docbook:2258
+#: C/index.docbook:2264
msgid "Tools related to gtk-doc"
msgstr "Nástroje související s GTK-Doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2260
+#: C/index.docbook:2266
msgid ""
"GtkDocPlugin - a <ulink url=\"http://trac-hacks.org/wiki/GtkDocPlugin\">Trac "
"GTK-Doc</ulink> integration plugin, that adds API docs to a trac site and "
"dokumentaci k API na sledovací web a integruje ji do vyhledávání."
#. (itstool) path: chapter/para
-#: C/index.docbook:2265
+#: C/index.docbook:2271
msgid ""
"Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since "
"tags in the API to determine the minimum required version."
<revhistory>
<revision>
- <revnumber>1.28</revnumber>
- <date>24 Mar 2018</date>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>bug fixes</revremark>
+ <revremark>development</revremark>
</revision>
+ <revision><revnumber>1.28</revnumber> <date>24. března 2018</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb</revremark></revision>
<revision><revnumber>1.27</revnumber> <date>7. prosince 2017</date> <authorinitials>ss</authorinitials> <revremark>detailní vyladění portu v jazyce Python</revremark></revision>
<revision><revnumber>1.26</revnumber> <date>11. srpen 2017</date> <authorinitials>ss</authorinitials> <revremark>přenesení všech nástrojů z jazyků Perl/Bash do jazyka Python</revremark></revision>
<revision><revnumber>1.25</revnumber> <date>21. březen 2016</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb, pročištění testů</revremark></revision>
<revision><revnumber>1.24</revnumber> <date>29. května 2015</date> <authorinitials>ss</authorinitials> <revremark>oprava chyby</revremark></revision>
<revision><revnumber>1.23</revnumber> <date>17. květen 2015</date> <authorinitials>ss</authorinitials> <revremark>oprava chyby</revremark></revision>
- <revision><revnumber>1.22</revnumber> <date>07. květen 2015</date> <authorinitials>ss</authorinitials> <revremark>oprava chyb, odstranění zastaralých věcí</revremark></revision>
- <revision><revnumber>1.21</revnumber> <date>17. červenec 2014</date> <authorinitials>ss</authorinitials> <revremark>oprava chyb, odstranění zastaralých věcí</revremark></revision>
+ <revision><revnumber>1.22</revnumber> <date>07. květen 2015</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb, odstranění zastaralých věcí</revremark></revision>
+ <revision><revnumber>1.21</revnumber> <date>17. červenec 2014</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb, odstranění zastaralých věcí</revremark></revision>
<revision><revnumber>1.20</revnumber> <date>16. únor 2014</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb, podpora značkovacího jazyka, vylepšení stylů</revremark></revision>
<revision><revnumber>1.19</revnumber> <date>05. červen 2013</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb</revremark></revision>
<revision><revnumber>1.18</revnumber> <date>14. září 2011</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb, zrychlení, podpora značkovacího jazyka</revremark></revision>
<orderedlist>
<listitem>
- <para><guilabel>Psaní dokumentace.</guilabel> Autor doplní soubory se zdrojovým kódem dokumentací pro každou funkci, makro, strukturu atd. (Dříve se informace vkládaly do souborů s vygenerovanými šablonami, což se již nedoporučuje).</para>
+ <para>
+ <guilabel>Writing the documentation.</guilabel>
+
+ The author fills in the source files with the documentation for each
+ function, macro, structs or unions, etc.
+ </para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>O aplikaci GTK-Doc</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(DOPLNIT)</para>
- <para>(Historie, autoři, webové stránky, poštovní konference, licence, plány do budoucna, srovnání s ostatními podobnými systémy.)</para>
+ <para>
+ (authors, web pages, mailing list, license, future plans,
+ comparison with other similar systems.)
+ </para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Nastavení vašeho projektu</title>
+ <title>Project Setup</title>
+
+ <para>
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
- <para>Následující oddíl popisuje kroky, které musíte provést, abyste integrovali GTK-Doc do svého projektu. Tento oddíl předpokládá, že pracujeme na projektu nazvaném „meep“. Tento projekt obsahuje knihovnu nazvanou „libmeep“ a aplikaci pro koncového uživatele nazvanou „meeper“. Rovněž předpokládá, že používáte autoconf a automake. V oddílu <link linkend="plain_makefiles">prosté soubory Makefile nebo jiné sestavovací systémy</link> budou popsány základní požadavky pro fungování s jinými postupy sestavování.</para>
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
+ </para>
<sect1 id="settingup_docfiles">
<title>Nastavení kostry dokumentace</title>
- <para>Pod nejvyšší složkou projektu vytvořte složky nazvané docs/reference (takto můžete mít i docs/help s dokumentací pro koncového uživatele). Je doporučeno vytvořit další podsložku s názvem balíčku s dokumentací. Pro balíčky s jedinou knihovnou není tento krok nutný.</para>
+ <para>
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
+ </para>
- <para>Ve výsledku to může vypadat nějak takto: <example><title>Příklad struktury složek</title>
- <programlisting>
+ <para>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
+ <programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
-</programlisting>
- </example></para>
+]]></programlisting>
+ </example>
+ </para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>Integrace s autoconf</title>
-
- <para>Velmi snadné! Stačí jen přidat jeden řádek do vašeho skriptu <filename>configure.ac</filename>.</para>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
+
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>Integrace s autoconf</title>
- <programlisting>
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-</programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>Vyžaduje to, aby všichni vývojáři měli gtk-doc nainstalované. Jestli u vašeho projektu stačí mít sestavení dokumentaci k API jen volitelné, můžete to vyřešit podle vzoru níže. Použijte to přesně tak, jak je uvedeno, protože gtkdocize hledá <function>GTK_DOC_CHECK</function> na začátku řádku. <example><title>Ponechání gtk-doc jako volitelného</title>
+ <sect2 id="settingup_automake">
+ <title>Integrace s automake</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </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)
-])
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
</programlisting>
- </example></para>
+ </example>
- <para>První argument se používá ke kontrole gtkdocversion v průběhu konfigurace. Druhý, volitelný argument používá nástroj <application>gtkdocize</application>. Makro <symbol>GTK_DOC_CHECK</symbol> také přidává několik přepínačů pro configure:</para>
- <orderedlist>
- <listitem><para>--with-html-dir=CESTA: cesta, kam se má dokumentace nainstalovat</para></listitem>
- <listitem><para>--enable-gtk-doc: použít k sestavení dokumentace gtk-doc [výchozí je ne]</para></listitem>
- <listitem><para>--enable-gtk-doc-html: sestavit dokumentaci ve formátu HTML [výchozí je ano]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf: sestavit dokumentaci ve formátu PDF [výchozí je ne]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
- <important>
- <para>GTK-Doc je standardně vypnuté! Nezapomeňte zadat přepínač „<option>--enable-gtk-doc</option>“ při dalším spuštění <filename>configure</filename>. Jinak se nainstaluje předgenerovaná dokumentace (která může mít význam pro uživatele, ale ne pro vývojáře).</para>
- </important>
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <para>Mimo to je ještě doporučeno, abyste měli ve skriptu <filename>configure.ac</filename> následující řádek. Umožní to <application>gtkdocize</application> automaticky nakopírovat definice maker pro <function>GTK_DOC_CHECK</function> do vašeho projektu.</para>
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
- <para>
- <example><title>Příprava pro gtkdocize</title>
- <programlisting>
+ All the tools support <option>--help</option> to list the supported
+ options.
+ </para>
+
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>Integrace s autoconf</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
-</programlisting>
- </example>
- </para>
- <para>Po provedení změn v <filename>configure.ac</filename> aktualizujte soubor <filename>configure</filename>. To se dá udělat opětovným spuštěním <code>autoreconf -i</code> nebo <code>autogen.sh</code>.</para>
- </sect1>
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+]]></programlisting>
+ </example>
+ </para>
+
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
+
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>Integrace s automake</title>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <para>Jako první nakopírujte <filename>Makefile.am</filename> z podsložky <filename class="directory">examples</filename> ve složce <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink> do složky s dokumentací API svého projektu (<filename class="directory">./docs/reference/<package></filename>). Místní kopie by měla být k dispozici např. pod <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Pokud máte více balíčků s dokumentací, opakujte tento krok pro každý z nich.</para>
+ <orderedlist>
+ <listitem><para>--with-html-dir=CESTA: cesta, kam se má dokumentace nainstalovat</para></listitem>
+ <listitem><para>--enable-gtk-doc: použít k sestavení dokumentace gtk-doc [výchozí je ne]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html: sestavit dokumentaci ve formátu HTML [výchozí je ano]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf: sestavit dokumentaci ve formátu PDF [výchozí je ne]</para></listitem>
+ </orderedlist>
- <para>Dalším krokem je úprava nastavení v <filename>Makefile.am</filename>. Všechna nastavení mají komentáře s popisem jejich účelu. Většina nastavení má doplňující příznaky předávané do dotyčných nástrojů. Každý nástroj má proměnnou ve formátu <option><NÁZEVNÁSTROJE>_OPTIONS</option>. Všechny nástroje podporují <option>--help</option> pro vypsání podporovaných přepínačů.</para>
+ <important>
+ <para>GTK-Doc je standardně vypnuté! Nezapomeňte zadat přepínač „<option>--enable-gtk-doc</option>“ při dalším spuštění <filename>configure</filename>. Jinak se nainstaluje předgenerovaná dokumentace (která může mít význam pro uživatele, ale ne pro vývojáře).</para>
+ </important>
- <!-- FIXME: explain options ? -->
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- </sect1>
+ <sect2 id="settingup_autogen">
+ <title>Integrace s autogen</title>
- <sect1 id="settingup_autogen">
- <title>Integrace s autogen</title>
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
- <para>Většina projektů má skript <filename>autogen.sh</filename>, který po stažení ze systému pro správu verzí (jako je CVS, SVN nebo Git), nastaví infrastrukturu pro sestavení. GTK-Doc se dodává s nástrojem nazvaným <application>gtkdocize</application>, který lze v takovémto skriptu využít. Měl by být spuštěný před autoheader, automake nebo autoconf.</para>
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
- <para>
- <example><title>Spuštění gtkdocize z autogen.sh</title>
- <programlisting>
+ <example><title>Spuštění gtkdocize z autogen.sh</title>
gtkdocize || exit 1
</programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>Když spustíte <filename>gtkdocize</filename>, tak nakopíruje do kořenové složky vašeho projektu (nebo složky určené přepínačem <option>--docdir</option>) soubor <filename>gtk-doc.make</filename>. Navíc zkontroluje váš skript configure, jestli volá <function>GTK_DOC_CHECK</function>. Toto makro můžete použít k předání dalších parametrů do <application>gtkdocize</application>.</para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>Dříve GTK-Doc generovalo soubory šablon, do kterých vývojáři vkládali dokumentaci. To bylo zrušeno, protože to nebylo příliš dobré (například kvůli potřebě mít generované soubory pod správou verzí). Od GTK-Doc verz 1.9 umí nástroje získávat všechny informace z komentářů ve zdrojových kódech a šablony tak můžete úplně vynechat. Doporučujeme lidem, aby dokumentaci udržovali v rámci kódu. <application>gtkdocize</application> nyní podporuje přepínač <option>--flavour=no-tmpl</option>, který způsobí, že makefile použití tmpl úplně vynechá. Mimo přidání této volby přímo do volaného příkazu, jej můžete předat také jako proměnnou prostředí s názvem <symbol>GTKDOCIZE_FLAGS</symbol>, nebo nastavit jako druhý parametr v makru <symbol>GTK_DOC_CHECK</symbol> v konfiguračním skriptu. Pokud jste nikdy ručně neměnili žádný soubor v tmpl a přecházíte ze starší verze gtkdoc, tak tuto složku prosím odstraňte (například ze správy verzí).</para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>Sestavení dokumentace</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>Po dokončení předchozích kroků nastal čas spustit sestavení. Nejdříve musíte znovu spustit <filename>autogen.sh</filename>. Pokud tento skript pro vás provádí nastavení, předejte mu přepínač <option>--enable-gtk-doc</option>. Jinak potom ručně spusťte <filename>configure</filename> s tímto přepínačem.</para>
- <para>První make spustí vygenerování několika doplňujících souborů ve složkách doc. Podstatné jsou tyto: <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (dříve .sgml) a <filename><package>-sections.txt</filename>.</para>
- <para>
- <example><title>Sestavení dokumentace</title>
- <programlisting>
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>Po dokončení předchozích kroků nastal čas spustit sestavení. Nejdříve musíte znovu spustit <filename>autogen.sh</filename>. Pokud tento skript pro vás provádí nastavení, předejte mu přepínač <option>--enable-gtk-doc</option>. Jinak potom ručně spusťte <filename>configure</filename> s tímto přepínačem.</para>
+ <para>První make spustí vygenerování několika doplňujících souborů ve složkách doc. Podstatné jsou tyto: <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (dříve .sgml) a <filename><package>-sections.txt</filename>.</para>
+ <para>
+ <example><title>Sestavení dokumentace</title>
+ <programlisting>
./autogen.sh --enable-gtk-doc
make
</programlisting>
- </example>
- </para>
- <para>Nyní se můžete ve svém prohlížeči podívat na <filename>docs/reference/<package>/index.html</filename>. Zatím je to poněkud neuspokojivé, že? Ale nebojte, v následující kapitole vám řekneme, jak stránky uvést do života.</para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>Integrace se systémem pro správu verzí</title>
+ <sect1 id="settingup_cmake">
+ <title>Integrace se sestavovacím systémem CMake</title>
- <para>Podle nepsaných pravidel byste soubory, které upravujete, měli udržovat ve správě verzí. U typických projektů to jsou tyto soubory: <filename><balíček>.types</filename>, <filename><balíček>-docs.xml</filename> (dříve .sgml), <filename><balíček>-sections.txt</filename> a <filename>Makefile.am</filename>.</para>
- <para>Soubory ze složek <filename>xml/</filename> a <filename>html/</filename> by neměly být zařazeny do správy verzí. A ani žádné soubory <filename>.stamp</filename>.</para>
+ <para>GTK-Doc nyní nabízí modul <filename>GtkDocConfig.cmake</filename> (a příslušný modul <filename>GtkDocConfigVersion.cmake</filename>). Ten poskytuje příkaz <literal>gtk_doc_add_module</literal>, který můžete nastavit ve svém souboru <filename>CMakeLists.txt</filename>.</para>
+
+ <para>Následující příklad ukazuje, jak tento příkaz použít: <example><title>Příklad použití GTK-Doc z CMake</title>
+ <programlisting>
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Vytvoření cíle doc-libmeep.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Sestavení doc-libmeep jako součásti výchozího cíle. Bez tohoto byste museli
+# ručně spouštět něco jako `make doc-libmeep`, aby se dokumentace sestavila.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Instalace dokumentace. (Předpokládá to, že používáte modul CMake GNUInstallDirs
+# ke správnému nastavení proměnné CMAKE_INSTALL_DOCDIR).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+</programlisting>
+ </example></para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integrace s prostými soubory Makefile nebo jinými sestavovacími systémy</title>
<para>Když někdo nechce používat automake, a tím pádem <filename>gtk-doc.mak</filename>, bude muset volat nástroje gtkdoc ve správném pořadí ve vlastních souborech make (nebo jiných nástrojích).</para>
<para>Na výběr dalších potřebných voleb se musíte se podívat do <filename>Makefile.am</filename> a <filename>gtk-doc.mak</filename>.</para>
</sect1>
- <sect1 id="cmake">
- <title>Integrace se sestavovacím systémem CMake</title>
-
- <para>GTK-Doc nyní nabízí modul <filename>GtkDocConfig.cmake</filename> (a příslušný modul <filename>GtkDocConfigVersion.cmake</filename>). Ten poskytuje příkaz <literal>gtk_doc_add_module</literal>, který můžete nastavit ve svém souboru <filename>CMakeLists.txt</filename>.</para>
-
- <para>Následující příklad ukazuje, jak tento příkaz použít: <example><title>Příklad použití GTK-Doc z CMake</title>
- <programlisting>
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Vytvoření cíle doc-libmeep.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>Integrace se systémem pro správu verzí</title>
-# Sestavení doc-libmeep jako součásti výchozího cíle. Bez tohoto byste museli
-# ručně spouštět něco jako `make doc-libmeep`, aby se dokumentace sestavila.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>Podle nepsaných pravidel byste soubory, které upravujete, měli udržovat ve správě verzí. U typických projektů to jsou tyto soubory: <filename><balíček>.types</filename>, <filename><balíček>-docs.xml</filename> (dříve .sgml), <filename><balíček>-sections.txt</filename> a <filename>Makefile.am</filename>.</para>
+ <para>Soubory ze složek <filename>xml/</filename> a <filename>html/</filename> by neměly být zařazeny do správy verzí. A ani žádné soubory <filename>.stamp</filename>.</para>
+ </sect1>
-# Instalace dokumentace. (Předpokládá to, že používáte modul CMake GNUInstallDirs
-# ke správnému nastavení proměnné CMAKE_INSTALL_DOCDIR).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-</programlisting>
- </example></para>
- </sect1>
</chapter>
<chapter id="documenting">
<para>GTK-Doc používá pro kód dokumentace komentáře se speciální syntaxí ve zdrojovém kódu. K tomu se ještě získávají informace o struktuře vašeho projektu z dalších zdrojů. V následujícím oddílu najdete všechny informace o syntaxi komentářů.</para>
- <note>
- <title>Umístění dokumentace</title>
- <para>Dříve musela být většina dokumentace doplněná do souborů umístěných ve složce <filename>tmpl</filename>. Následkem toho bylo, že informace byly často neaktualizované a soubory měli tendenci způsobovat konflikty v systémech pro správu verzí.</para>
- <para>Aby se předešlo těmto zmiňovaným problémům, předpokládáme vkládání dokumentace přímo do zdrojových kódů. Tato příručka bude popisovat pouze tento způsob dokumentování kódu.</para>
- </note>
-
- <para>Skener zvládá dobře většinu hlavičkových souborů C. V případě, že od něj obdržíte varování, které vypadá jako speciální případ, můžete GTK-Doc poradit, aby jej přeskakovala. <example><title>Komentářový blok GTK-Doc</title>
- <programlisting>
+ <para>
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
+ <example><title>GTK-Doc comment block</title>
+ <programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
-/* kód zde se nezpracovává */
+/* unparseable code here */
#endif
-</programlisting>
- </example></para>
+]]></programlisting>
+ </example>
+ </para>
<note>
<title>Omezení</title>
<para>Více příkladů k podporovaným značkám Markdown můžete najít v <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">Referenční příručce k syntaxi Markdown pro dokumentaci GTK+</ulink>.</para>
<tip>
- <para>Jak již bylo zmíněno dříve, slouží GTK-Doc pro dokumentování veřejného API. Tím pádem nemůžete psát dokumentaci pro statické symboly. Nicméně je vhodné komentovat i tyto symboly. Pomůže to ostatním porozumět vašemu kódu. Proto doporučujeme komentovat je pomocí normálních komentářů (bez druhé „*“ na prvním řádku). Pokud je budete v budoucnu chtít předělat na veřejné, jediné co budete muset udělat, je přidat do komentářového bloku jednu „*“ a na správné místo v souboru oddílů vložit název symbolu.</para>
+ <para>
+ As already mentioned earlier GTK-Doc is for documenting public API. Thus
+ one cannot write documentation for static symbols. Nevertheless it is good
+ to comment those symbols too. This helps other developers to understand
+ your code.
+ Therefore we recommend to comment these using normal comments (without the
+ 2nd '*' in the first line).
+ If later the function needs to be made public, all one needs to do is to
+ add another '*' in the comment block and insert the symbol name at the
+ right place inside the sections file.
+ </para>
</tip>
</sect1>
<para>Pokud vaše knihovna nebo aplikace vkládá objekty GObject, chcete jejich signály, argumenty/parametry a pozici v hierarchii ukázat v dokumentaci. Vše, co pro to potřebujete udělat, je vypsat funkce <function>xxx_get_type</function> spolu s jejich include v souboru <filename><balíček>.types</filename>.</para>
<para>
- <example><title>Příklad úryvku ze souboru typů</title>
+ <example><title>Example <package>.types file</title>
<programlisting>
#include <gtk/gtk.h>
<sect1 id="modernizing-gtk-doc-1-25">
<title>GTK-Doc 1.25</title>
- <para>Soubory Makefile dodávané s touto verzí generují do <filename>xml/gtkdocentities.ent</filename> soubor s entitami, který obsahuje entity například pro package_name a package_version. Můžete je použít třeba v hlavním souboru XML, abyste nemuseli mít číslo verze zapsané natvrdo. Níže je uveden příklad, jak soubor s entitami vložit a jak entity použít. Použít je lze také ve všech generovaných souborech, GTK-Doc bude používat tu samou hlavičku XML v generovaných souborech XML. <example><title>Používání předgenerovaných entit</title>
- <programlisting>
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ <para>
+ The makefiles shipped with this version generate an entity file at <filename>xml/gtkdocentities.ent</filename>,
+ containing entities for e.g. package_name and package_version. You can
+ use this e.g. in the main xml file to avoid hardcoding the version
+ number. Below is an example that shows how the entity file is included
+ in the master template and how the entities are used.
+ The entities can also be used in all
+ generated files, GTK-Doc will use the same xml header in generated xml
+ files.
+ <example><title>Use pre-generated entities</title>
+ <programlisting><![CDATA[
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
- <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
- <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
- <bookinfo>
- <title>&Referenční příručka k package_name;</title>
- <releaseinfo>
- for &package_string;.
- Nejnovější verzi této dokumentace můžete najít on-line na
- <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
- </releaseinfo>
- </bookinfo>
-</programlisting>
- </example></para>
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+ <bookinfo>
+ <title>&package_name; Reference Manual</title>
+ <releaseinfo>
+ for &package_string;.
+ The latest version of this documentation can be found on-line at
+ <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
+ </releaseinfo>
+ </bookinfo>
+]]></programlisting>
+ </example>
+ </para>
</sect1>
</chapter>
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc help master\n"
-"POT-Creation-Date: 2018-01-12 10:35+0000\n"
-"PO-Revision-Date: 2018-01-14 13:39+0100\n"
+"POT-Creation-Date: 2018-05-20 18:37+0000\n"
+"PO-Revision-Date: 2018-08-09 18:25+0200\n"
"Last-Translator: Tim Sabsch <tim@sabsch.com>\n"
"Language-Team: German <gnome-de@gnome.org>\n"
"Language: de\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
-"X-Generator: Poedit 2.0.5\n"
+"X-Generator: Poedit 2.0.9\n"
#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
msgctxt "_"
#. (itstool) path: revhistory/revision
#: C/index.docbook:83
msgid ""
-"<revnumber>1.2
7.1</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
+"<revnumber>1.2
8.1</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>development</revremark>"
msgstr ""
-"<revnumber>1.27.1</revnumber> <date>07. Dezember 2017</date> "
-"<authorinitials>ss</authorinitials> <revremark>Entwicklerversion</revremark>"
+"<revnumber>1.28.1</revnumber> <date>24. März 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>Entwicklerversion</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
msgid ""
+"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes</revremark>"
+msgstr ""
+"<revnumber>1.28</revnumber> <date>24. März 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>Fehlerbehebungen</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+msgid ""
"<revnumber>1.27</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>fine tuning of the python port</revremark>"
msgstr ""
"Portierung</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
msgid ""
"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>port all tools from perl/bash to python</"
"nach Python portiert</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
+#: C/index.docbook:107
msgid ""
"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
"authorinitials> <revremark>Fehlerbehebungen, Test-Cleanups</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:107
+#: C/index.docbook:113
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>Fehlerbehebungen</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:113
+#: C/index.docbook:119
msgid ""
"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>Fehlerbehebungen</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:119
+#: C/index.docbook:125
msgid ""
"<revnumber>1.22</revnumber> <date>07 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:125
+#: C/index.docbook:131
msgid ""
"<revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:131
+#: C/index.docbook:137
msgid ""
"<revnumber>1.20</revnumber> <date>16 Feb 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, markdown support, style improvements</"
"Unterstützung für Markdown, Layoutverbesserungen</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:137
+#: C/index.docbook:143
msgid ""
"<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
"authorinitials> <revremark>Fehlerbehebungen</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:143
+#: C/index.docbook:149
msgid ""
"<revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, speedups, markdown support</revremark>"
"Geschwindigkeit, Unterstützung für markdown</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:149
+#: C/index.docbook:155
msgid ""
"<revnumber>1.17</revnumber> <date>26 Feb 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>urgent bug fix update</revremark>"
"Aktualisierung</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:155
+#: C/index.docbook:161
msgid ""
"<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes, layout improvements</revremark>"
"authorinitials> <revremark>Bugfixes, Layoutverbesserungen</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:161
+#: C/index.docbook:167
msgid ""
"<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bug and regression fixes</revremark>"
"authorinitials> <revremark>Bug- und Regressionsfixes</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:167
+#: C/index.docbook:173
msgid ""
"<revnumber>1.14</revnumber> <date>28 March 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes and performance improvements</revremark>"
"authorinitials> <revremark>Bugfixes und Leistungsverbesserungen</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:173
+#: C/index.docbook:179
msgid ""
"<revnumber>1.13</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>broken tarball update</"
"beschädigten Tarballs</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:179
+#: C/index.docbook:185
msgid ""
"<revnumber>1.12</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>new tool features and "
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:185
+#: C/index.docbook:191
msgid ""
"<revnumber>1.11</revnumber> <date>16 November 2008</date> "
"<authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</"
"utils</revremark>"
#. (itstool) path: chapter/title
-#: C/index.docbook:198
+#: C/index.docbook:204
msgid "Introduction"
msgstr "Einführung"
#. (itstool) path: chapter/para
-#: C/index.docbook:200
+#: C/index.docbook:206
msgid ""
"This chapter introduces GTK-Doc and gives an overview of what it is and how "
"it is used."
"es sich dabei handelt und wie es benutzt wird."
#. (itstool) path: sect1/title
-#: C/index.docbook:206
+#: C/index.docbook:212
msgid "What is GTK-Doc?"
msgstr "Was ist GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:208
+#: C/index.docbook:214
msgid ""
"GTK-Doc is used to document C code. It is typically used to document the "
"public API of libraries, such as the GTK+ and GNOME libraries. But it can "
"Anwendungscode verwendet werden."
#. (itstool) path: sect1/title
-#: C/index.docbook:216
+#: C/index.docbook:222
msgid "How Does GTK-Doc Work?"
msgstr "Wie funktioniert GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:218
+#: C/index.docbook:224
msgid ""
"GTK-Doc works by using documentation of functions placed inside the source "
"files in specially-formatted comment blocks, or documentation added to the "
"keine Ausgaben für statische Funktionen."
#. (itstool) path: sect1/para
-#: C/index.docbook:225
+#: C/index.docbook:231
msgid ""
"GTK-Doc consists of a number of python scripts, each performing a different "
"step in the process."
"bestimmten Schritt in dem Prozess ausführt."
#. (itstool) path: sect1/para
-#: C/index.docbook:230
+#: C/index.docbook:236
msgid "There are 5 main steps in the process:"
msgstr "Dieser Vorgang umfasst fünf Hauptschritte:"
#. (itstool) path: listitem/para
-#: C/index.docbook:237
+#: C/index.docbook:243
msgid ""
"<guilabel>Writing the documentation.</guilabel> The author fills in the "
"source files with the documentation for each function, macro, union etc. (In "
"eingegeben. Dies wird nicht mehr empfohlen."
#. (itstool) path: listitem/para
-#: C/index.docbook:247
+#: C/index.docbook:253
msgid ""
"<guilabel>Gathering information about the code.</guilabel> "
"<application>gtkdoc-scan</application> scans the header files of the code "
"<filename><module>-overrides.txt</filename> platzieren."
#. (itstool) path: listitem/para
-#: C/index.docbook:264
+#: C/index.docbook:270
msgid ""
"<application>gtkdoc-scangobj</application> can also be used to dynamically "
"query a library about any GObject subclasses it exports. It saves "
"und -Signale, die es bietet."
#. (itstool) path: listitem/para
-#: C/index.docbook:270
+#: C/index.docbook:276
msgid ""
"<application>gtkdoc-scanobj</application> should not be used anymore. It was "
"needed in the past when GObject was still GtkObject inside gtk+."
"GtkObject innerhalb von gtk+ war."
#. (itstool) path: listitem/para
-#: C/index.docbook:277
+#: C/index.docbook:283
msgid ""
"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
"mkdb</application> turns the template files into XML files in the <filename "
"introspection-Daten gelesen."
#. (itstool) path: listitem/para
-#: C/index.docbook:286
+#: C/index.docbook:292
msgid ""
"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
"in ein PDF-Dokument namens <filename><package>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:292
+#: C/index.docbook:298
msgid ""
"Files in <filename class=\"directory\">xml/</filename> and <filename class="
"\"directory\">html/</filename> directories are always overwritten. One "
"sollte diese direkt bearbeiten."
#. (itstool) path: listitem/para
-#: C/index.docbook:300
+#: C/index.docbook:306
msgid ""
"<guilabel>Fixing up cross-references between documents.</guilabel> After "
"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
"lokale Verweise umzuwandeln (wo diese Dokumente installiert werden)."
#. (itstool) path: sect1/title
-#: C/index.docbook:318
+#: C/index.docbook:324
msgid "Getting GTK-Doc"
msgstr "GTK-Doc bekommen"
#. (itstool) path: sect2/title
-#: C/index.docbook:321
+#: C/index.docbook:327
msgid "Requirements"
msgstr "Erfordernisse"
#. (itstool) path: sect2/para
-#: C/index.docbook:322
+#: C/index.docbook:328
msgid ""
"<guilabel>python 2/3</guilabel> - the main scripts are written in python."
msgstr ""
"geschrieben."
#. (itstool) path: sect2/para
-#: C/index.docbook:325
+#: C/index.docbook:331
msgid ""
"<guilabel>xsltproc</guilabel> - the xslt processor from libxslt <ulink url="
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
#. (itstool) path: sect2/para
-#: C/index.docbook:329
+#: C/index.docbook:335
msgid ""
"<guilabel>docbook-xsl</guilabel> - the docbook xsl stylesheets <ulink url="
"\"http://sourceforge.net/projects/docbook/files/docbook-xsl/\" type=\"http"
"\">sourceforge.net/projects/docbook/files/docbook-xsl</ulink>"
#. (itstool) path: sect2/para
-#: C/index.docbook:333
+#: C/index.docbook:339
msgid ""
"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
"<guilabel>vim</guilabel> - optional - für Syntax-Hervorhebung von Beispielen"
#. (itstool) path: sect1/title
-#: C/index.docbook:341
+#: C/index.docbook:347
msgid "About GTK-Doc"
msgstr "Info zu GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:343 C/index.docbook:357
+#: C/index.docbook:349 C/index.docbook:363
msgid "(FIXME)"
msgstr "(FIXME)"
#. (itstool) path: sect1/para
-#: C/index.docbook:347
+#: C/index.docbook:353
msgid ""
"(History, authors, web pages, mailing list, license, future plans, "
"comparison with other similar systems.)"
"Vergleich mit ähnlichen Systemen)"
#. (itstool) path: sect1/title
-#: C/index.docbook:355
+#: C/index.docbook:361
msgid "About this Manual"
msgstr "Über dieses Handbuch"
#. (itstool) path: sect1/para
-#: C/index.docbook:361
+#: C/index.docbook:367
msgid "(who it is meant for, where you can get it, license)"
msgstr "(wofür es bestimmt ist, wo Sie es erhalten können, Lizenz)"
#. (itstool) path: chapter/title
-#: C/index.docbook:370
+#: C/index.docbook:376
msgid "Setting up your project"
msgstr "Einrichten Ihres Projekts"
#. (itstool) path: chapter/para
-#: C/index.docbook:372
+#: C/index.docbook:378
msgid ""
"The next sections describe what steps to perform to integrate GTK-Doc into "
"your project. Theses sections assume we work on a project called 'meep'. "
"Erstellungsumgebung."
#. (itstool) path: sect1/title
-#: C/index.docbook:383
+#: C/index.docbook:389
msgid "Setting up a skeleton documentation"
msgstr "Einrichten des Grundgerüsts der Dokumentation"
#. (itstool) path: sect1/para
-#: C/index.docbook:385
+#: C/index.docbook:391
msgid ""
"Under your top-level project directory create folders called docs/reference "
"(this way you can also have docs/help for end-user documentation). It is "
"notwendig."
#. (itstool) path: example/title
-#: C/index.docbook:394
+#: C/index.docbook:400
msgid "Example directory structure"
msgstr "Beispiel für die Ordnerstruktur"
#. (itstool) path: example/programlisting
-#: C/index.docbook:395
+#: C/index.docbook:401
#, no-wrap
msgid ""
"\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:392
+#: C/index.docbook:398
msgid "This can then look as shown below: <_:example-1/>"
msgstr "Dies kann dann wie nachstehend angezeigt aussehen: <_:example-1/>"
#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:410 C/index.docbook:417
+#: C/index.docbook:416 C/index.docbook:423
msgid "Integration with autoconf"
msgstr "Integration in autoconf"
#. (itstool) path: sect1/para
-#: C/index.docbook:412
+#: C/index.docbook:418
msgid ""
"Very easy! Just add one line to your <filename>configure.ac</filename> "
"script."
"filename>-Skript hinzu."
#. (itstool) path: example/programlisting
-#: C/index.docbook:418
+#: C/index.docbook:424
#, no-wrap
msgid ""
"\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
#. (itstool) path: example/title
-#: C/index.docbook:430
+#: C/index.docbook:436
msgid "Keep gtk-doc optional"
msgstr "Halten Sie gtk-doc optional"
#. (itstool) path: example/programlisting
-#: C/index.docbook:431
+#: C/index.docbook:437
#, no-wrap
msgid ""
"\n"
"])\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:425
+#: C/index.docbook:431
msgid ""
"This will require all developers to have gtk-doc installed. If it is okay "
"for your project to have optional api-doc build setup, you can solve this as "
"Zeile sucht. <_:example-1/>"
#. (itstool) path: sect1/para
-#: C/index.docbook:442
+#: C/index.docbook:448
msgid ""
"The first argument is used to check for the gtkdocversion at configure time. "
"The 2nd, optional argument is used by <application>gtkdocize</application>. "
"hinzu:"
#. (itstool) path: listitem/para
-#: C/index.docbook:448
+#: C/index.docbook:454
msgid "--with-html-dir=PATH : path to installed docs"
msgstr "--with-html-dir=PATH : Pfad zur installierten Dokumentation"
#. (itstool) path: listitem/para
-#: C/index.docbook:449
+#: C/index.docbook:455
msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]"
msgstr ""
"--enable-gtk-doc : gtk-doc zur Erstellung der Dokumentation verwenden "
"[Vorgabe=no]"
#. (itstool) path: listitem/para
-#: C/index.docbook:450
+#: C/index.docbook:456
msgid ""
"--enable-gtk-doc-html : build documentation in html format [default=yes]"
msgstr ""
"[Vorgabe=yes]"
#. (itstool) path: listitem/para
-#: C/index.docbook:451
+#: C/index.docbook:457
msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
msgstr ""
"--enable-gtk-doc-pdf : Erstellung der Dokumentation im PDF-Format "
"[Vorgabe=no]"
#. (itstool) path: important/para
-#: C/index.docbook:455
+#: C/index.docbook:461
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"aber nicht für Entwickler."
#. (itstool) path: sect1/para
-#: C/index.docbook:463
+#: C/index.docbook:469
msgid ""
"Furthermore it is recommended that you have the following line inside your "
"<filename>configure.ac</filename> script. This allows "
"<function>GTK_DOC_CHECK</function> in Ihr Projekt."
#. (itstool) path: example/title
-#: C/index.docbook:471
+#: C/index.docbook:477
msgid "Preparation for gtkdocize"
msgstr "Vorbereitung für gtkdocize"
#. (itstool) path: example/programlisting
-#: C/index.docbook:472
+#: C/index.docbook:478
#, no-wrap
msgid ""
"\n"
"AC_CONFIG_MACRO_DIR(m4)\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:477
+#: C/index.docbook:483
msgid ""
"After all changes to <filename>configure.ac</filename> are made, update the "
"<filename>configure</filename> file. This can be done by re-running "
"<code>autogen.sh</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:485
+#: C/index.docbook:491
msgid "Integration with automake"
msgstr "Integration in automake"
#. (itstool) path: sect1/para
-#: C/index.docbook:487
+#: C/index.docbook:493
msgid ""
"First copy the <filename>Makefile.am</filename> from the <filename class="
"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
"Dokumentationspakete haben, müssen Sie dies für jedes davon wiederholen."
#. (itstool) path: sect1/para
-#: C/index.docbook:498
+#: C/index.docbook:504
msgid ""
"The next step is to edit the settings inside the <filename>Makefile.am</"
"filename>. All the settings have a comment above that describes their "
"unterstützten Parameter."
#. (itstool) path: sect1/title
-#: C/index.docbook:512
+#: C/index.docbook:518
msgid "Integration with autogen"
msgstr "Integration in autogen"
#. (itstool) path: sect1/para
-#: C/index.docbook:514
+#: C/index.docbook:520
msgid ""
"Most projects will have an <filename>autogen.sh</filename> script to setup "
"the build infrastructure after a checkout from version control system (such "
"oder autoconf ausgeführt werden."
#. (itstool) path: example/title
-#: C/index.docbook:523
+#: C/index.docbook:529
msgid "Running gtkdocize from autogen.sh"
msgstr "Ausführen von gtkdocize durch autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:524
+#: C/index.docbook:530
#, no-wrap
msgid ""
"\n"
"gtkdocize || exit 1\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:530
+#: C/index.docbook:536
msgid ""
"When running <application>gtkdocize</application> it copies <filename>gtk-"
"doc.make</filename> to your project root (or any directory specified by the "
"Parameter an <application>gtkdocize</application> zu übergeben."
#. (itstool) path: sect1/para
-#: C/index.docbook:539
+#: C/index.docbook:545
msgid ""
"Historically GTK-Doc was generating template files where developers entered "
"the docs. This turned out to be not so good (e.g. the need for having "
#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:556 C/index.docbook:573
+#: C/index.docbook:562 C/index.docbook:579
msgid "Running the doc build"
msgstr "Erstellung der Dokumentation"
#. (itstool) path: sect1/para
-#: C/index.docbook:558
+#: C/index.docbook:564
msgid ""
"After the previous steps it's time to run the build. First we need to rerun "
"<filename>autogen.sh</filename>. If this script runs configure for you, then "
"Option."
#. (itstool) path: sect1/para
-#: C/index.docbook:565
+#: C/index.docbook:571
msgid ""
"The first make run generates several additional files in the doc-"
"directories. The important ones are: <filename><package>.types</"
"(früher .sgml), <filename><package>-sections.txt</filename>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:574
+#: C/index.docbook:580
#, no-wrap
msgid ""
"\n"
"make\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:580
+#: C/index.docbook:586
msgid ""
"Now you can point your browser to <filename>docs/reference/<package>/"
"index.html</filename>. Yes, it's a bit disappointing still. But hang-on, "
"Seiten mit Leben füllen können."
#. (itstool) path: sect1/title
-#: C/index.docbook:588
+#: C/index.docbook:594
msgid "Integration with version control systems"
msgstr "Integration in Versionsverwaltungssysteme"
#. (itstool) path: sect1/para
-#: C/index.docbook:590
+#: C/index.docbook:596
msgid ""
"As a rule of thumb, it's the files you edit which should go under version "
"control. For typical projects it's these files: <filename><package>."
"sections.txt</filename>, <filename>Makefile.am</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:598
+#: C/index.docbook:604
msgid ""
"Files in the <filename>xml/</filename> and <filename>html/</filename> "
"directories should not go under version control. Neither should any of the "
"keine der <filename>.stamp</filename>-Dateien."
#. (itstool) path: sect1/title
-#: C/index.docbook:606
+#: C/index.docbook:612
msgid "Integration with plain makefiles or other build systems"
msgstr "Integration in Klartext-Makefiles oder andere Erstellungssysteme"
#. (itstool) path: sect1/para
-#: C/index.docbook:608
+#: C/index.docbook:614
msgid ""
"In the case one does not want to use automake and therefore <filename>gtk-"
"doc.mak</filename> one will need to call the gtkdoc tools in the right order "
"(oder andere Werkzeuge) in der richtigen Reihenfolge aufrufen."
#. (itstool) path: example/title
-#: C/index.docbook:615
+#: C/index.docbook:621
msgid "Documentation build steps"
msgstr "Schritte zur Erstellung der Dokumentation"
#. (itstool) path: example/programlisting
-#: C/index.docbook:616
+#: C/index.docbook:622
#, no-wrap
msgid ""
"\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:630
+#: C/index.docbook:636
msgid ""
"One will need to look at the <filename>Makefile.am</filename> and "
"<filename>gtk-doc.mak</filename> to pick the extra options needed."
"filename> anschauen, um die zusätzlich notwendigen Optionen herauszusuchen."
#. (itstool) path: sect1/title
-#: C/index.docbook:637
+#: C/index.docbook:643
msgid "Integration with CMake build systems"
msgstr "Integration in CMake-Erstellungssysteme"
#. (itstool) path: sect1/para
-#: C/index.docbook:639
+#: C/index.docbook:645
msgid ""
"GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module (and "
"the corresponding <filename>GtkDocConfigVersion.cmake</filename> module). "
"integrieren können."
#. (itstool) path: example/title
-#: C/index.docbook:649
+#: C/index.docbook:655
msgid "Example of using GTK-Doc from CMake"
msgstr "Beispiel zur Verwendung von GTK-Doc mit CMake"
#. (itstool) path: example/programlisting
-#: C/index.docbook:650
+#: C/index.docbook:656
#, no-wrap
msgid ""
"\n"
" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:647
+#: C/index.docbook:653
msgid "The following example shows how to use this command. <_:example-1/>"
msgstr ""
"Das folgende Beispiel zeigt, wie dieser Befehl eingesetzt wird. <_:example-1/"
">"
#. (itstool) path: chapter/title
-#: C/index.docbook:675
+#: C/index.docbook:681
msgid "Documenting the code"
msgstr "Dokumentieren des Codes"
#. (itstool) path: chapter/para
-#: C/index.docbook:677
+#: C/index.docbook:683
msgid ""
"GTK-Doc uses source code comment with a special syntax for code "
"documentation. Further it retrieves information about your project structure "
"Informationen über die Syntax der Kommentare."
#. (itstool) path: note/title
-#: C/index.docbook:685
+#: C/index.docbook:691
msgid "Documentation placement"
msgstr "Platzierung der Dokumentation"
#. (itstool) path: note/para
-#: C/index.docbook:686
+#: C/index.docbook:692
msgid ""
"In the past most documentation had to be filled into files residing inside "
"the <filename>tmpl</filename> directory. This has the disadvantages that the "
"Konflikte mit Versionsverwaltungssystemen verursachen kann."
#. (itstool) path: note/para
-#: C/index.docbook:692
+#: C/index.docbook:698
msgid ""
"The avoid the aforementioned problems we suggest putting the documentation "
"inside the sources. This manual will only describe this way of documenting "
"ausschließlich dieser Weg des Dokumentierens des Quellcodes beschrieben."
#. (itstool) path: example/title
-#: C/index.docbook:703 C/index.docbook:729
+#: C/index.docbook:709 C/index.docbook:735
msgid "GTK-Doc comment block"
msgstr "GTK-Doc-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:704
+#: C/index.docbook:710
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:699
+#: C/index.docbook:705
msgid ""
"The scanner can handle the majority of C headers fine. In the case of "
"receiving warnings from the scanner that look like a special case, one can "
"anweisen diese zu überspringen. <_:example-1/>"
#. (itstool) path: note/title
-#: C/index.docbook:713
+#: C/index.docbook:719
msgid "Limitations"
msgstr "Einschränkungen"
#. (itstool) path: note/para
-#: C/index.docbook:714
+#: C/index.docbook:720
msgid ""
"Note, that GTK-Doc's supports <code>#ifndef(__GTK_DOC_IGNORE__)</code> but "
"not <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations."
"andere Kombinationen."
#. (itstool) path: sect1/title
-#: C/index.docbook:724
+#: C/index.docbook:730
msgid "Documentation comments"
msgstr "Kommentare zur Dokumentation"
#. (itstool) path: example/programlisting
-#: C/index.docbook:730
+#: C/index.docbook:736
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:726
+#: C/index.docbook:732
msgid ""
"A multiline comment that starts with an additional '*' marks a documentation "
"block that will be processed by the GTK-Doc tools. <_:example-1/>"
"example-1/>"
#. (itstool) path: sect1/para
-#: C/index.docbook:739
+#: C/index.docbook:745
msgid ""
"The 'identifier' is one line with the name of the item the comment is "
"related to. The syntax differs a little depending on the item. (TODO add "
"variieren."
#. (itstool) path: sect1/para
-#: C/index.docbook:745
+#: C/index.docbook:751
msgid ""
"The 'documentation' block is also different for each symbol type. Symbol "
"types that get parameters such as functions or macros have the parameter "
"dahinter. Dies ist in vorformatiertem Text nützlich (Code-Auflistungen)."
#. (itstool) path: listitem/para
-#: C/index.docbook:762
+#: C/index.docbook:768
msgid ""
"What it is: The name for a class or function can sometimes be misleading for "
"people coming from a different background."
"führend sein für Personen, die einen anderen Hintergrund haben."
#. (itstool) path: listitem/para
-#: C/index.docbook:768
+#: C/index.docbook:774
msgid ""
"What it does: Tell about common uses. Put it in relation with the other API."
msgstr ""
"Verhältnis mit der anderen API."
#. (itstool) path: tip/para
-#: C/index.docbook:758
+#: C/index.docbook:764
msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>"
msgstr ""
"Beim Dokumentieren von Code beschreiben Sie zwei Aspekte: <_:itemizedlist-1/>"
#. (itstool) path: listitem/para
-#: C/index.docbook:783
+#: C/index.docbook:789
msgid "Use function() to refer to functions or macros which take arguments."
msgstr ""
"Verwenden Sie function(), um einen Bezug zu Funktionen oder Makros "
"herzustellen, die Argumente akzeptieren."
#. (itstool) path: listitem/para
-#: C/index.docbook:788
+#: C/index.docbook:794
msgid ""
"Use @param to refer to parameters. Also use this when referring to "
"parameters of other functions, related to the one being described."
"bezogen auf jene, die Sie gerade beschreiben."
#. (itstool) path: listitem/para
-#: C/index.docbook:794
+#: C/index.docbook:800
msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS."
msgstr ""
"Benutzen Sie %constant, um einen Bezug auf eine Konstante herzustellen, z.B. "
"%G_TRAVERSE_LEAFS."
#. (itstool) path: listitem/para
-#: C/index.docbook:799
+#: C/index.docbook:805
msgid ""
"Use #symbol to refer to other types of symbol, e.g. structs and enums and "
"macros which don't take arguments."
"»structs« und »enums« und Makros, die keine Argumente benötigen."
#. (itstool) path: listitem/para
-#: C/index.docbook:805
+#: C/index.docbook:811
msgid "Use #Object::signal to refer to a GObject signal."
-msgstr "Verwenden Sie #Object::signal, um auf ein GObject-Signal zu verweisen"
+msgstr "Verwenden Sie #Object::signal, um auf ein GObject-Signal zu verweisen."
#. (itstool) path: listitem/para
-#: C/index.docbook:810
+#: C/index.docbook:816
msgid "Use #Object:property to refer to a GObject property."
msgstr ""
"Verwenden Sie #Object:property, um auf eine GObject-Eigenschaft zu verweisen."
#. (itstool) path: listitem/para
-#: C/index.docbook:815
+#: C/index.docbook:821
msgid ""
"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
"foo_bar() to refer to a vmethod."
"verweisen und #GObjectClass.foo_bar() für eine vmethod."
#. (itstool) path: sect1/para
-#: C/index.docbook:777
+#: C/index.docbook:783
msgid ""
"One advantage of hyper-text over plain-text is the ability to have links in "
"the document. Writing the correct markup for a link can be tedious though. "
"itemizedlist-1/>"
#. (itstool) path: tip/para
-#: C/index.docbook:824
+#: C/index.docbook:830
msgid ""
"If you need to use the special characters '<', '>', '()', '@', '%', or "
"'#' in your documentation without GTK-Doc changing them you can use the XML "
"einem Backslash »\\« maskieren."
#. (itstool) path: sect1/para
-#: C/index.docbook:833
+#: C/index.docbook:839
msgid ""
"DocBook can do more than just links. One can also have lists, examples, "
"headings, and images. As of version 1.20, the preferred way is to use a "
"Listenobjekte als Zeilen, die mit einem Gedankenstrich beginnen."
#. (itstool) path: sect1/para
-#: C/index.docbook:844
+#: C/index.docbook:850
msgid ""
"While markdown is now preferred one can mix both. One limitation here is "
"that one can use docbook xml within markdown, but markdown within docbook "
"verwenden können, während Markdown in DocBook XML nicht unterstützt wird."
#. (itstool) path: sect1/para
-#: C/index.docbook:850
+#: C/index.docbook:856
msgid ""
"In older GTK-Doc releases, if you need support for additional formatting, "
"you would need to enable the usage of docbook XML tags inside doc-comments "
"die Option <option>--xml-mode</option> (oder <option>--sgml-mode</option>)."
#. (itstool) path: example/title
-#: C/index.docbook:859
+#: C/index.docbook:865
msgid "GTK-Doc comment block using Markdown"
msgstr "GTK-Doc-Kommentarblock in Markdown-Syntax"
#. (itstool) path: example/programlisting
-#: C/index.docbook:860
+#: C/index.docbook:866
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:899
+#: C/index.docbook:905
msgid ""
"More examples of what markdown tags are supported can be found in the <ulink "
"url=\"https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown"
"Markdown\">GTK+ Documentation Markdown Syntax Reference</ulink>."
#. (itstool) path: tip/para
-#: C/index.docbook:905
+#: C/index.docbook:911
msgid ""
"As already mentioned earlier GTK-Doc is for documenting public API. Thus one "
"cannot write documentation for static symbols. Nevertheless it is good to "
"Abschnittsdatei einzubauen."
#. (itstool) path: sect1/title
-#: C/index.docbook:919
+#: C/index.docbook:925
msgid "Documenting sections"
msgstr "Dokumentieren von Abschnitten"
#. (itstool) path: sect1/para
-#: C/index.docbook:921
+#: C/index.docbook:927
msgid ""
"Each section of the documentation contains information about one class or "
"module. To introduce the component one can write a section block. The short "
"Inhaltsverzeichnis verwendet. Alle @-Felder sind optional."
#. (itstool) path: example/title
-#: C/index.docbook:929
+#: C/index.docbook:935
msgid "Section comment block"
msgstr "Abschnitts-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:930
+#: C/index.docbook:936
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:949
+#: C/index.docbook:955
msgid "SECTION:<name>"
msgstr "SECTION:<name>"
#. (itstool) path: listitem/para
-#: C/index.docbook:951
+#: C/index.docbook:957
msgid ""
"The name links the section documentation to the respective part in the "
"<filename><package>-sections.txt</filename> file. The name given here "
"<filename><package>-sections.txt</filename> entsprechen."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:960
+#: C/index.docbook:966
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:962
+#: C/index.docbook:968
msgid ""
"A one line description of the section, that later will appear after the "
"links in the TOC and at the top of the section page."
"im Inhaltsverzeichnis und oben in der Abschnittsseite erscheint."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:969
+#: C/index.docbook:975
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:971
+#: C/index.docbook:977
msgid ""
"The section title defaults to <name> from the SECTION declaration. It "
"can be overridden with the @title field."
"kann im Feld @title überschrieben werden."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:978
+#: C/index.docbook:984
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:980
+#: C/index.docbook:986
msgid ""
"Overrides the use of title as a section identifier. For GObjects the <"
"title> is used as a section_id and for other sections it is <"
"<MODUL>-<Titel>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:988
+#: C/index.docbook:994
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:990
+#: C/index.docbook:996
msgid "A list of symbols that are related to this section."
msgstr "Eine Liste von Symbolen, welche sich auf diesen Abschnitt beziehen."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:996
+#: C/index.docbook:1002
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1003
+#: C/index.docbook:1009
msgid ""
"Stable - The intention of a Stable interface is to enable arbitrary third "
"parties to develop applications to these interfaces, release them, and have "
"von stark berechtigten."
#. (itstool) path: listitem/para
-#: C/index.docbook:1015
+#: C/index.docbook:1021
msgid ""
"Unstable - Unstable interfaces are experimental or transitional. They are "
"typically used to give outside developers early access to new or rapidly "
"Binärkompatibilität von einer minor-Freigabe zur nächsten gegeben."
#. (itstool) path: listitem/para
-#: C/index.docbook:1027
+#: C/index.docbook:1033
msgid ""
"Private - An interface that can be used within the GNOME stack itself, but "
"that is not documented for end-users. Such functions should only be used in "
"nur auf spezifizierte und dokumentierte Weisen verwendet werden."
#. (itstool) path: listitem/para
-#: C/index.docbook:1036
+#: C/index.docbook:1042
msgid ""
"Internal - An interface that is internal to a module and does not require "
"end-user documentation. Functions that are undocumented are assumed to be "
"intern angesehen."
#. (itstool) path: listitem/para
-#: C/index.docbook:998
+#: C/index.docbook:1004
msgid ""
"An informal description of the stability level this API has. We recommend "
"the use of one of these terms: <_:itemizedlist-1/>"
"dafür einen der folgenden Begriffe: <_:itemizedlist-1/>"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1048
+#: C/index.docbook:1054
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1050
+#: C/index.docbook:1056
msgid ""
"The <literal>#include</literal> files to show in the section synopsis (a "
"comma separated list), overriding the global value from the <link linkend="
"Befehlszeile wird überschrieben. Dieser Punkt ist optional."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1059
+#: C/index.docbook:1065
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1061
+#: C/index.docbook:1067
msgid ""
"The image to display at the top of the reference page for this section. This "
"will often be some sort of a diagram to illustrate the visual appearance of "
"darstellt. Dieses Objekt ist optional."
#. (itstool) path: tip/para
-#: C/index.docbook:1072
+#: C/index.docbook:1078
msgid ""
"To avoid unnecessary recompilation after doc-changes put the section docs "
"into the c-source where possible."
"möglich ist."
#. (itstool) path: sect1/title
-#: C/index.docbook:1081
+#: C/index.docbook:1087
msgid "Documenting symbols"
msgstr "Dokumentieren von Symbolen"
#. (itstool) path: sect1/para
-#: C/index.docbook:1083
+#: C/index.docbook:1089
msgid ""
"Each symbol (function, macro, struct, enum, signal and property) is "
"documented in a separate block. The block is best placed close to the "
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1091 C/index.docbook:1157
+#: C/index.docbook:1097 C/index.docbook:1163
msgid "General tags"
msgstr "Allgemeine Markierungen"
#. (itstool) path: sect2/para
-#: C/index.docbook:1093
+#: C/index.docbook:1099
msgid ""
"You can add versioning information to all documentation elements to tell "
"when an API was introduced, or when it was deprecated."
"als veraltet markiert wurde."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1098
+#: C/index.docbook:1104
msgid "Versioning Tags"
msgstr "Versionierungs-Markierungen"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1099
+#: C/index.docbook:1105
msgid "Since:"
msgstr "Since:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1101
+#: C/index.docbook:1107
msgid "Description since which version of the code the API is available."
msgstr "Beschreibung, seit welcher Version des Codes die API verfügbar ist."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1106
+#: C/index.docbook:1112
msgid "Deprecated:"
msgstr "Deprecated:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1108
+#: C/index.docbook:1114
msgid ""
"Paragraph denoting that this function should no be used anymore. The "
"description should point the reader to the new API."
"enthalten."
#. (itstool) path: sect2/para
-#: C/index.docbook:1116
+#: C/index.docbook:1122
msgid ""
"You can also add stability information to all documentation elements to "
"indicate whether API stability is guaranteed for them for all future minor "
"Veröffentlichungen des Projekts garantiert wird."
#. (itstool) path: sect2/para
-#: C/index.docbook:1122
+#: C/index.docbook:1128
msgid ""
"The default stability level for all documentation elements can be set by "
"passing the <option>--default-stability</option> argument to "
"beschriebenen Werte."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1128
+#: C/index.docbook:1134
msgid "Stability Tags"
msgstr "Stabilitäts-Markierungen"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1129
+#: C/index.docbook:1135
msgid "Stability: Stable"
msgstr "Stability: Stable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1131
+#: C/index.docbook:1137
msgid ""
"Mark the element as stable. This is for public APIs which are guaranteed to "
"remain stable for all future minor releases of the project."
"gewährleistet ist."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1138
+#: C/index.docbook:1144
msgid "Stability: Unstable"
msgstr "Stability: Unstable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1140
+#: C/index.docbook:1146
msgid ""
"Mark the element as unstable. This is for public APIs which are released as "
"a preview before being stabilised."
"die als Vorschau vor der endgültigen Stabilisierung gedacht sind."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1146
+#: C/index.docbook:1152
msgid "Stability: Private"
msgstr "Stability: Private"
#. (itstool) path: listitem/para
-#: C/index.docbook:1148
+#: C/index.docbook:1154
msgid ""
"Mark the element as private. This is for interfaces which can be used by "
"tightly coupled modules, but not by arbitrary third parties."
"beliebigen Drittanbietern."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1158
+#: C/index.docbook:1164
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1178 C/index.docbook:1188
+#: C/index.docbook:1184 C/index.docbook:1194
msgid "Annotations"
msgstr "Anmerkungen"
#. (itstool) path: sect2/para
-#: C/index.docbook:1180
+#: C/index.docbook:1186
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"GObjectIntrospection/Annotations\" type=\"http\">Wiki</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1189
+#: C/index.docbook:1195
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1210 C/index.docbook:1239
+#: C/index.docbook:1216 C/index.docbook:1245
msgid "Function comment block"
msgstr "Kommentarblock einer Funktion"
#. (itstool) path: listitem/para
-#: C/index.docbook:1216
+#: C/index.docbook:1222
msgid ""
"Document whether returned objects, lists, strings, etc, should be freed/"
"unrefed/released."
"dereferenziert/freigegeben werden."
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1228
msgid "Document whether parameters can be NULL, and what happens if they are."
msgstr ""
"Dokumentiert, ob Parameter NULL sein können, und was in diesem Fall "
"geschieht."
#. (itstool) path: listitem/para
-#: C/index.docbook:1227
+#: C/index.docbook:1233
msgid ""
"Mention interesting pre-conditions and post-conditions where appropriate."
msgstr ""
"es nützlich erscheint."
#. (itstool) path: sect2/para
-#: C/index.docbook:1212 C/index.docbook:1298
+#: C/index.docbook:1218 C/index.docbook:1304
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Bitte denken Sie an: <_:itemizedlist-1/>"
#. (itstool) path: sect2/para
-#: C/index.docbook:1234
+#: C/index.docbook:1240
msgid ""
"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
"private. They are treated like static functions."
"beginnen, privat sind. Sie werden wie statische Funktionen behandelt."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1240
+#: C/index.docbook:1246
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1261
+#: C/index.docbook:1267
msgid "Function tags"
msgstr "Funktions-Markierungen"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1262 C/index.docbook:1469
+#: C/index.docbook:1268 C/index.docbook:1475
msgid "Returns:"
msgstr "Returns:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1264
+#: C/index.docbook:1270
msgid "Paragraph describing the returned result."
msgstr "Abschnitt, der das zurückgegebene Ergebnis beschreibt."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1269
+#: C/index.docbook:1275
msgid "@...:"
msgstr "@...:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1271
+#: C/index.docbook:1277
msgid ""
"In case the function has variadic arguments, you should use this tag "
"(@Varargs: does also work for historic reasons)."
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1281 C/index.docbook:1283
+#: C/index.docbook:1287 C/index.docbook:1289
msgid "Property comment block"
msgstr "Property-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1284
+#: C/index.docbook:1290
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1296 C/index.docbook:1315
+#: C/index.docbook:1302 C/index.docbook:1321
msgid "Signal comment block"
msgstr "Signal-Kommentarblock"
#. (itstool) path: listitem/para
-#: C/index.docbook:1302
+#: C/index.docbook:1308
msgid ""
"Document when the signal is emitted and whether it is emitted before or "
"after other signals."
"anderen Signalen ausgegeben wird."
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1314
msgid "Document what an application might do in the signal handler."
msgstr "Dokumentiert, was eine Anwendung in dem Signal-Handler tun könnte."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1316
+#: C/index.docbook:1322
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1333 C/index.docbook:1334
+#: C/index.docbook:1339 C/index.docbook:1340
msgid "Struct comment block"
msgstr "Struct-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1335
+#: C/index.docbook:1341
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1350
+#: C/index.docbook:1356
msgid ""
"Use <code>/*< private >*/</code> before the private struct fields you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"verwenden Sie <code>/*< public >*/</code>."
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1362
msgid ""
"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" "
"it will be considered private automatically and doesn't need to be mentioned "
"erwähnt werden."
#. (itstool) path: sect2/para
-#: C/index.docbook:1362
+#: C/index.docbook:1368
msgid ""
"Struct comment blocks can also be used for GObjects and GObjectClasses. It "
"is usually a good idea to add a comment block for a class, if it has "
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1374 C/index.docbook:1375
+#: C/index.docbook:1380 C/index.docbook:1381
msgid "Enum comment block"
msgstr "Enum-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1376
+#: C/index.docbook:1382
#, no-wrap
msgid ""
"\n"
"} Something;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1393
+#: C/index.docbook:1399
msgid ""
"Use <code>/*< private >*/</code> before the private enum values you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"verwenden Sie <code>/*< public >*/</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1404
+#: C/index.docbook:1410
msgid "Inline program documentation"
msgstr "Eingebettete Programmdokumentation"
#. (itstool) path: sect1/para
-#: C/index.docbook:1405
+#: C/index.docbook:1411
msgid ""
"You can document programs and their commandline interface using inline "
"documentation."
"eingebetteter Dokumentation."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1411
+#: C/index.docbook:1417
msgid "Tags"
msgstr "Schlagwörter"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1413
+#: C/index.docbook:1419
msgid "PROGRAM"
msgstr "PROGRAM"
#. (itstool) path: listitem/para
-#: C/index.docbook:1416
+#: C/index.docbook:1422
msgid "Defines the start of a program documentation."
msgstr "Definiert den Start einer Programmdokumentation"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1423
+#: C/index.docbook:1429
msgid "@short_description:"
msgstr "@short_description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1425
+#: C/index.docbook:1431
msgid "Defines a short description of the program. (Optional)"
msgstr "Definiert eine Kurzbeschreibung des Programms (optional)."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1432
+#: C/index.docbook:1438
msgid "@synopsis:"
msgstr "@synopsis:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1434
+#: C/index.docbook:1440
msgid ""
"Defines the arguments, or list of arguments that the program can take. "
"(Optional)"
"akzeptiert (optional)."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1442
+#: C/index.docbook:1448
msgid "@see_also:"
msgstr "@see_also:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1444
+#: C/index.docbook:1450
msgid "See Also manual page section. (Optional)"
msgstr ""
"Der Abschnitt »SEE ALSO« in den man-Pages (Unix-Handbuchseiten, optional)."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1451
+#: C/index.docbook:1457
msgid "@arg:"
msgstr "@arg:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1453
+#: C/index.docbook:1459
msgid "Argument(s) passed to the program and their description. (Optional)"
msgstr ""
"Argument(e), die dem Programm übergeben wurden, und die zugehörige "
"Beschreibung (optional)."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1460
+#: C/index.docbook:1466
msgid "Description:"
msgstr "Description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1462
+#: C/index.docbook:1468
msgid "A longer description of the program."
msgstr "Eine ausführlichere Beschreibung des Programms."
#. (itstool) path: listitem/para
-#: C/index.docbook:1471
+#: C/index.docbook:1477
msgid "Specificy what value(s) the program returns. (Optional)"
msgstr "Geben Sie an, welche Wert(e) das Programm zurück gibt (optional)."
#. (itstool) path: sect2/title
-#: C/index.docbook:1480
+#: C/index.docbook:1486
msgid "Example of program documentation."
msgstr "Beispiel einer Programmdokumentation."
#. (itstool) path: example/title
-#: C/index.docbook:1481
+#: C/index.docbook:1487
msgid "Program documentation block"
msgstr "Programm-Dokumentationsblock"
# Würde ich nicht übersetzen. Ein Entwickler schreibt stets in Englisch,
# die Übersetzung ist unsere Sache.
#. (itstool) path: example/programlisting
-#: C/index.docbook:1482
+#: C/index.docbook:1488
#, no-wrap
msgid ""
"\n"
"}\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1508
+#: C/index.docbook:1514
msgid "Useful DocBook tags"
msgstr "Nützliche DocBook-Markierungen"
#. (itstool) path: sect1/para
-#: C/index.docbook:1510
+#: C/index.docbook:1516
msgid ""
"Here are some DocBook tags which are most useful when documenting the code."
msgstr ""
"von Code nützlich sein können."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1519
+#: C/index.docbook:1525
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1515
+#: C/index.docbook:1521
msgid ""
"To link to another section in the GTK docs: <_:informalexample-1/> The "
"linkend is the SGML/XML id on the top item of the page you want to link to. "
"konform in »-« umgewandelt. "
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1532
+#: C/index.docbook:1538
#, no-wrap
msgid ""
"\n"
"<function>...</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1529
+#: C/index.docbook:1535
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
"<_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1541
+#: C/index.docbook:1547
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1552
+#: C/index.docbook:1558
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1538
+#: C/index.docbook:1544
msgid ""
"To include example code: <_:informalexample-1/> or possibly this, for very "
"short code fragments which don't need a title: <_:informalexample-2/> For "
"Außerdem unterstützt GTK-Doc auch eine Abkürzung: |[ ... ]|"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1571
+#: C/index.docbook:1577
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1568
+#: C/index.docbook:1574
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Für eine Liste mit Aufzählungszeichen: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1591
+#: C/index.docbook:1597
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1588
+#: C/index.docbook:1594
msgid ""
"To include a note which stands out from the text: <_:informalexample-1/>"
msgstr ""
"Für eine nicht zum eigentlichen Text gehörende Notiz: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1604
+#: C/index.docbook:1610
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1601
+#: C/index.docbook:1607
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "Für einen Bezug zu einem Typ: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1613
+#: C/index.docbook:1619
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1610
+#: C/index.docbook:1616
msgid ""
"To refer to an external structure (not one described in the GTK docs): <_:"
"informalexample-1/>"
"beschrieben wird): <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1622
+#: C/index.docbook:1628
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1619
+#: C/index.docbook:1625
msgid "To refer to a field of a structure: <_:informalexample-1/>"
msgstr "Für einen Bezug zu einem Feld einer Struktur: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1631
+#: C/index.docbook:1637
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1628
+#: C/index.docbook:1634
msgid ""
"To refer to a class name, we could possibly use: <_:informalexample-1/> but "
"you'll probably be using #GtkWidget instead (to automatically create a link "
"- lesen Sie <link linkend=\"documenting_syntax\">die Abkürzungen</link>)."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1642
+#: C/index.docbook:1648
#, no-wrap
msgid ""
"\n"
"<emphasis>This is important</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1639
+#: C/index.docbook:1645
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Zum Hervorheben von Text: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1651
+#: C/index.docbook:1657
#, no-wrap
msgid ""
"\n"
"<filename>/home/user/documents</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1648
+#: C/index.docbook:1654
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Für Dateinamen: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1660
+#: C/index.docbook:1666
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1657
+#: C/index.docbook:1663
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "Für einen Bezug zu einem Schlüssel: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1670
+#: C/index.docbook:1676
msgid "Filling the extra files"
msgstr "Füllen der zusätzlichen Dateien"
#. (itstool) path: chapter/para
-#: C/index.docbook:1672
+#: C/index.docbook:1678
msgid ""
"There are a couple of extra files, that need to be maintained along with the "
"inline source code comments: <filename><package>.types</filename>, "
"<filename><package>-sections.txt</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1681
+#: C/index.docbook:1687
msgid "Editing the types file"
msgstr "Bearbeiten der Typendatei"
#. (itstool) path: sect1/para
-#: C/index.docbook:1683
+#: C/index.docbook:1689
msgid ""
"If your library or application includes GObjects, you want their signals, "
"arguments/parameters and position in the hierarchy to be shown in the "
"der Datei <filename><package>.types</filename> aufzulisten."
#. (itstool) path: example/title
-#: C/index.docbook:1692
+#: C/index.docbook:1698
msgid "Example types file snippet"
msgstr "Beispiel-Schnipsel einer Typen-Datei"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1693
+#: C/index.docbook:1699
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1704
+#: C/index.docbook:1710
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"stellen."
#. (itstool) path: sect1/title
-#: C/index.docbook:1713
+#: C/index.docbook:1719
msgid "Editing the master document"
msgstr "Bearbeiten des Master-Dokuments"
#. (itstool) path: sect1/para
-#: C/index.docbook:1715
+#: C/index.docbook:1721
msgid ""
"GTK-Doc produces documentation in DocBook SGML/XML. When processing the "
"inline source comments, the GTK-Doc tools generate one documentation page "
"Hauptdokument schließt diese ein und setzt sie in die passende Reihenfolge."
#. (itstool) path: sect1/para
-#: C/index.docbook:1722
+#: C/index.docbook:1728
msgid ""
"While GTK-Doc creates a template master document for you, later runs will "
"not touch it again. This means that one can freely structure the "
"Neuigkeiten eingeführt werden."
#. (itstool) path: tip/para
-#: C/index.docbook:1732
+#: C/index.docbook:1738
msgid ""
"Do not create tutorials as extra documents. Just write extra chapters. The "
"benefit of directly embedding the tutorial for your library into the API "
"die gleichen Aktualisierungen erfährt wie die Bibliothek selbst."
#. (itstool) path: sect1/para
-#: C/index.docbook:1741
+#: C/index.docbook:1747
msgid ""
"So what are the things to change inside the master document? For a start is "
"only a little. There are some placeholders (text in square brackets) there "
"beachten sollten."
#. (itstool) path: example/title
-#: C/index.docbook:1748
+#: C/index.docbook:1754
msgid "Master document header"
msgstr "Kopfzeile des Master-Dokuments"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1749
+#: C/index.docbook:1755
#, no-wrap
msgid ""
"\n"
" <title>[Insert title here]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1765
+#: C/index.docbook:1771
msgid ""
"In addition a few option elements are created in commented form. You can "
"review these and enable them as you like."
"können sich diese anschauen und aktivieren, wenn Sie wollen."
#. (itstool) path: example/title
-#: C/index.docbook:1771
+#: C/index.docbook:1777
msgid "Optional part in the master document"
msgstr "Optionaler Teil im Master-Dokument"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1772
+#: C/index.docbook:1778
#, no-wrap
msgid ""
"\n"
" --> \n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1780
+#: C/index.docbook:1786
msgid ""
"Finally you need to add new section whenever you introduce one. The <link "
"linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> tool will remind "
"in der Dokumentation noch nicht erfasst sind."
#. (itstool) path: example/title
-#: C/index.docbook:1788 C/index.docbook:1823
+#: C/index.docbook:1794 C/index.docbook:1829
msgid "Including generated sections"
msgstr "Einbeziehen erzeugter Abschnitte"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1789
+#: C/index.docbook:1795
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1801
+#: C/index.docbook:1807
msgid "Editing the section file"
msgstr "Bearbeiten der Abschnittsdatei"
#. (itstool) path: sect1/para
-#: C/index.docbook:1803
+#: C/index.docbook:1809
msgid ""
"The section file is used to organise the documentation output by GTK-Doc. "
"Here one specifies which symbol belongs to which module or class and control "
"welcher Klasse gehört und regelt die Sichtbarkeit (öffentlich oder privat)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1809
+#: C/index.docbook:1815
msgid ""
"The section file is a plain text file with tags delimiting sections. Blank "
"lines are ignored and lines starting with a '#' are treated as comment lines."
"die mit »#« beginnen, werden als Kommentarzeilen behandelt."
#. (itstool) path: note/para
-#: C/index.docbook:1816
+#: C/index.docbook:1822
msgid ""
"While the tags make the file look like xml, it is not. Please do not close "
"tags like <SUBSECTION>."
"trügt. Bitte schließen Sie keine Markierungen wie <SUBSECTION>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1824
+#: C/index.docbook:1830
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1841
+#: C/index.docbook:1847
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"Kleinbuchstaben)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1853
+#: C/index.docbook:1859
msgid ""
"The <TITLE> ... </TITLE> tag is used to specify the title of the "
"section. It is only useful before the templates (if used) are initially "
"das SECTION-Kommentar in den Quellen einsetzt, ist dies überflüssig."
#. (itstool) path: sect1/para
-#: C/index.docbook:1860
+#: C/index.docbook:1866
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"(Variablen, vmethods)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1879
+#: C/index.docbook:1885
msgid ""
"You can also use <INCLUDE> ... </INCLUDE> to specify the "
"#include files which are shown in the synopsis sections. It contains a comma-"
"Abschnitts festlegen, wirkt es nur in diesem Abschnitt."
#. (itstool) path: chapter/title
-#: C/index.docbook:1893
+#: C/index.docbook:1899
msgid "Controlling the result"
msgstr "Überprüfung des Ergebnisses"
#. (itstool) path: chapter/para
-#: C/index.docbook:1895
+#: C/index.docbook:1901
msgid ""
"A GTK-Doc run generates report files inside the documentation directory. The "
"generated files are named: <filename><package>-undocumented.txt</"
"werden."
#. (itstool) path: chapter/para
-#: C/index.docbook:1904
+#: C/index.docbook:1910
msgid ""
"The <filename><package>-undocumented.txt</filename> file starts with "
"the documentation coverage summary. Below are two sections divided by blank "
"Dokumentation haben, aber z.B. ein neuer Parameter hinzugefügt worden ist."
#. (itstool) path: chapter/para
-#: C/index.docbook:1913
+#: C/index.docbook:1919
msgid ""
"The <filename><package>-undeclared.txt</filename> file lists symbols "
"given in the <filename><package>-sections.txt</filename> but not found "
"geschrieben wurden."
#. (itstool) path: chapter/para
-#: C/index.docbook:1920
+#: C/index.docbook:1926
msgid ""
"The <filename><package>-unused.txt</filename> file lists symbol names, "
"where the GTK-Doc scanner has found documentation, but does not know where "
"wurde."
#. (itstool) path: tip/para
-#: C/index.docbook:1928
+#: C/index.docbook:1934
msgid ""
"Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile."
"am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during "
"ausgeführt."
#. (itstool) path: chapter/para
-#: C/index.docbook:1935
+#: C/index.docbook:1941
msgid ""
"One can also look at the files produced by the source code scanner: "
"<filename><package>-decl-list.txt</filename> and <filename><"
"kann man prüfen, ob diese Datei es enthält."
#. (itstool) path: chapter/para
-#: C/index.docbook:1944
+#: C/index.docbook:1950
msgid ""
"If the project is GObject based, one can also look into the files produced "
"by the object scanner: <filename><package>.args.txt</filename>, "
"ausführen."
#. (itstool) path: chapter/title
-#: C/index.docbook:1959
+#: C/index.docbook:1965
msgid "Modernizing the documentation"
msgstr "Die Dokumentation modernisieren"
#. (itstool) path: chapter/para
-#: C/index.docbook:1961
+#: C/index.docbook:1967
msgid ""
"GTK-Doc has been around for quite some time. In this section we list new "
"features together with the version since when it is available."
"wir neue Features und die Version, mit der sie eingeführt wurden."
#. (itstool) path: sect1/title
-#: C/index.docbook:1967
+#: C/index.docbook:1973
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1969
+#: C/index.docbook:1975
msgid ""
"When using xml instead of sgml, one can actually name the master document "
"<filename><package>-docs.xml</filename>."
"<filename><package>-docs.xml</filename> nennen."
#. (itstool) path: sect1/para
-#: C/index.docbook:1974
+#: C/index.docbook:1980
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-sections</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"Abschnittsdatei sehr einfach aktualisiert werden."
#. (itstool) path: sect1/para
-#: C/index.docbook:1985
+#: C/index.docbook:1991
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"die Sache ist erledigt."
#. (itstool) path: sect1/title
-#: C/index.docbook:1997
+#: C/index.docbook:2003
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:1999
+#: C/index.docbook:2005
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"soll."
#. (itstool) path: sect1/title
-#: C/index.docbook:2010
+#: C/index.docbook:2016
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:2016
+#: C/index.docbook:2022
msgid "Enable gtkdoc-check"
msgstr "gtkdoc-check einschalten"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2017
+#: C/index.docbook:2023
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2012
+#: C/index.docbook:2018
msgid ""
"This version includes a new tool called gtkdoc-check. This tool can run a "
"set of sanity checks on your documentation. It is enabled by adding these "
"<filename>Makefile.am</filename> hinzu. <_:example-1/>"
#. (itstool) path: sect1/title
-#: C/index.docbook:2030
+#: C/index.docbook:2036
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:2032
+#: C/index.docbook:2038
msgid ""
"Version 1.18 brought some initial markdown support. Using markdown in doc "
"comments is less intrusive than writing docbook xml. This version improves a "
"\">Kommentarsyntax</link>."
#. (itstool) path: sect1/title
-#: C/index.docbook:2042
+#: C/index.docbook:2048
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:2052
+#: C/index.docbook:2058
msgid "Use pre-generated entities"
msgstr "Vorerzeugte Entitäten verwenden"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2053
+#: C/index.docbook:2059
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2044
+#: C/index.docbook:2050
msgid ""
"The makefiles shipped with this version generate an entity file at "
"<filename>xml/gtkdocentities.ent</filename>, containing entities for e.g. "
"die gleichen XML-Kopfeinträge auch in generierten Dateien. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:2078
+#: C/index.docbook:2084
msgid "Documenting other interfaces"
msgstr "Dokumentieren anderer Schnittstellen"
#. (itstool) path: chapter/para
-#: C/index.docbook:2080
+#: C/index.docbook:2086
msgid ""
"So far we have been using GTK-Doc to document the API of code. The next "
"sections contain suggestions how the tools can be used to document other "
"Werkzeuge zum Dokumentieren anderer Schnittstellen eingesetzt werden können."
#. (itstool) path: sect1/title
-#: C/index.docbook:2087
+#: C/index.docbook:2093
msgid "Command line options and man pages"
msgstr "Befehlszeilenoptionen und Handbuchseiten"
#. (itstool) path: sect1/para
-#: C/index.docbook:2089
+#: C/index.docbook:2095
msgid ""
"As one can generate man pages for a docbook refentry as well, it sounds like "
"a good idea to use it for that purpose. This way the interface is part of "
"kostenfrei die man-Hilfeseite."
#. (itstool) path: sect2/title
-#: C/index.docbook:2096
+#: C/index.docbook:2102
msgid "Document the tool"
msgstr "Dokumentieren des Werkzeuges"
#. (itstool) path: sect2/para
-#: C/index.docbook:2098
+#: C/index.docbook:2104
msgid ""
"Create one refentry file per tool. Following <link linkend="
"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
"Beispiele (z.B. in glib) ansehen."
#. (itstool) path: sect2/title
-#: C/index.docbook:2108
+#: C/index.docbook:2114
msgid "Adding the extra configure check"
msgstr "Hinzufügen der zusätzlichen Configure-Überprüfungen"
#. (itstool) path: example/title
-#: C/index.docbook:2111 C/index.docbook:2129
+#: C/index.docbook:2117 C/index.docbook:2135
msgid "Extra configure checks"
msgstr "Zusätzliche Configure-Überprüfungen"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2112
+#: C/index.docbook:2118
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2126
+#: C/index.docbook:2132
msgid "Adding the extra makefile rules"
msgstr "Hinzufügen der zusätzlichen Makefile-Regeln"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2130
+#: C/index.docbook:2136
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2152
+#: C/index.docbook:2158
msgid "DBus interfaces"
msgstr "DBus-Schnittstellen"
#. (itstool) path: sect1/para
-#: C/index.docbook:2154
+#: C/index.docbook:2160
msgid ""
"(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://"
"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
#. (itstool) path: chapter/title
-#: C/index.docbook:2163
+#: C/index.docbook:2169
msgid "Frequently asked questions"
msgstr "Häufig gestellte Fragen"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2167
+#: C/index.docbook:2173
msgid "Question"
msgstr "Frage"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2168
+#: C/index.docbook:2174
msgid "Answer"
msgstr "Antwort"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2170
+#: C/index.docbook:2176
msgid "No class hierarchy."
msgstr "Keine Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2171
+#: C/index.docbook:2177
msgid ""
"The objects <function>xxx_get_type()</function> function has not been "
"entered into the <filename><package>.types</filename> file."
"die Datei <filename><package>.types</filename> eingegeben."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2177
+#: C/index.docbook:2183
msgid "Still no class hierarchy."
msgstr "Noch immer keine Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2178
+#: C/index.docbook:2184
msgid ""
"Missing or wrong naming in <filename><package>-sections.txt</filename> "
"file (see <ulink url=\"http://mail.gnome.org/archives/gtk-doc-list/2003-"
"archives/gtk-doc-list/2003-October/msg00006.html\">Erklärung</ulink>)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2184
+#: C/index.docbook:2190
msgid "Damn, I have still no class hierarchy."
msgstr "Verdammt, ich habe immer noch keine Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2185
+#: C/index.docbook:2191
msgid ""
"Is the object name (name of the instance struct, e.g. <type>GtkWidget</"
"type>) part of the normal section (don't put this into Standard or Private "
"Teil des normalen Abschnitts (nicht in den Standard- oder Unterabschnitte)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2192
+#: C/index.docbook:2198
msgid "No symbol index."
msgstr "Kein Symbolindex."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2193
+#: C/index.docbook:2199
msgid ""
"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
"index that xi:includes the generated index?"
"der den erstellten Index xi:enthält?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2199
+#: C/index.docbook:2205
msgid "Symbols are not linked to their doc-section."
msgstr "Symbole werden nicht mit deren Dokumentationsbschnitt verknüpft."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2200
+#: C/index.docbook:2206
msgid ""
"Is the doc-comment using the correct markup (added #,% or ())? Check if the "
"gtkdoc-fixxref warns about unresolvable xrefs."
"»()«)? Prüfen Sie, ob gtkdoc-fixxref wegen nicht auflösbarer xrefs warnt."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2206
+#: C/index.docbook:2212
msgid "A new class does not appear in the docs."
msgstr "Eine neue Klasse erscheint nicht in der Dokumentation."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2207
+#: C/index.docbook:2213
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"sgml}</filename>?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2213
+#: C/index.docbook:2219
msgid "A new symbol does not appear in the docs."
msgstr "Ein neues Symbol erscheint nicht in der Dokumentation."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2214
+#: C/index.docbook:2220
msgid ""
"Is the doc-comment properly formatted. Check for spelling mistakes in the "
"begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable "
"Abschnitt gelistet ist."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2222
+#: C/index.docbook:2228
msgid "A type is missing from the class hierarchy."
msgstr "Ein Typ fehlt in der Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2223
+#: C/index.docbook:2229
msgid ""
"If the type is listed in <filename><package>.hierarchy</filename> but "
"not in <filename>xml/tree_index.sgml</filename> then double check that the "
"sie nicht angezeigt."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2232
+#: C/index.docbook:2238
msgid "I get foldoc links for all gobject annotations."
msgstr "Ich erhalte foldoc-Verweise für alle gobjekt-Anmerkungen."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2233
+#: C/index.docbook:2239
msgid ""
"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
"from <filename><package>-docs.{xml,sgml}</filename>."
"<filename><package>-docs.{xml,sgml}</filename> xi:eingebunden ist."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2241
+#: C/index.docbook:2247
msgid "Parameter described in source code comment block but does not exist"
msgstr ""
"Parameter wird im Kommentarblock des Quellcodes beschrieben, aber existiert "
"nicht"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2242
+#: C/index.docbook:2248
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
msgstr ""
"Überprüfen Sie, ob die Parameternamen der Prototypen in der Quelle und im "
-"Header unterschiedlich sind"
+"Header unterschiedlich sind."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2247
+#: C/index.docbook:2253
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "Mehrfache »IDs« für »constraint linkend: XYZ«"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2248
+#: C/index.docbook:2254
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"sections.txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2251
+#: C/index.docbook:2257
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"entspricht."
#. (itstool) path: chapter/title
-#: C/index.docbook:2258
+#: C/index.docbook:2264
msgid "Tools related to gtk-doc"
msgstr "Werkzeuge mit Bezug zu gtk-doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2260
+#: C/index.docbook:2266
msgid ""
"GtkDocPlugin - a <ulink url=\"http://trac-hacks.org/wiki/GtkDocPlugin\">Trac "
"GTK-Doc</ulink> integration plugin, that adds API docs to a trac site and "
"Seite hinzufügt und die trac-Suche einbindet."
#. (itstool) path: chapter/para
-#: C/index.docbook:2265
+#: C/index.docbook:2271
msgid ""
"Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since "
"tags in the API to determine the minimum required version."
<revhistory>
<revision>
- <revnumber>1.28</revnumber>
- <date>24 Mar 2018</date>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>bug fixes</revremark>
+ <revremark>development</revremark>
</revision>
+ <revision><revnumber>1.28</revnumber> <date>24. März 2018</date> <authorinitials>ss</authorinitials> <revremark>Fehlerbehebungen</revremark></revision>
<revision><revnumber>1.27</revnumber> <date>07. Dezember 2017</date>> <authorinitials>ss</authorinitials> <revremark>Detailanpassungen der Python-Portierung</revremark></revision>
<revision><revnumber>1.26.1</revnumber> <date>11. August 2017</date> <authorinitials>ss</authorinitials> <revremark>Alle Werkzeuge von Perl/Bash nach Python portiert</revremark></revision>
<revision><revnumber>1.25</revnumber> <date>21. März 2015</date> <authorinitials>ss</authorinitials> <revremark>Fehlerbehebungen, Test-Cleanups</revremark></revision>
<orderedlist>
<listitem>
- <para><guilabel>Schreiben der Dokumentation.</guilabel> Der Autor ergänzt die Quelldateien um die Dokumentation für jede Funktion, jedes Makro usw. In der Vergangenheit wurden diese Informationen in erstellte Vorlagendateien eingegeben. Dies wird nicht mehr empfohlen.</para>
+ <para>
+ <guilabel>Writing the documentation.</guilabel>
+
+ The author fills in the source files with the documentation for each
+ function, macro, structs or unions, etc.
+ </para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>Info zu GTK-Doc</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(FIXME)</para>
- <para>(Geschichte, Autoren, Webseiten, Mailingliste, Lizenz, Zukunftspläne, Vergleich mit ähnlichen Systemen)</para>
+ <para>
+ (authors, web pages, mailing list, license, future plans,
+ comparison with other similar systems.)
+ </para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Einrichten Ihres Projekts</title>
+ <title>Project Setup</title>
- <para>Die nächsten Abschnitte beschreiben die notwendigen Schritte, um GTK-Doc in Ihr Projekt zu integrieren. Nehmen wir an, wir arbeiten an einem Projekt namens »meep«. Das Projekt enthält eine Bibliothek namens »libmeep« sowie eine Endbenutzer-Anwendung namens »meeper«. Weiterhin gehen wir davon aus, dass wir autoconf und automake verwenden. Zusätzlich beschreibt der Abschnitt <link linkend="plain_makefiles">Klartext-Makefiles oder andere Erstellungssysteme</link> die Grundlagen für die Arbeit in einer anderen Erstellungsumgebung.</para>
+ <para>
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
+ </para>
<sect1 id="settingup_docfiles">
<title>Einrichten des Grundgerüsts der Dokumentation</title>
- <para>Erstellen Sie in dem Ordner der obersten Ebene des Projekts die Unterordner namens docs/reference. Auf diese Weise können Sie auch docs/help für die Endbenutzerdokumentation anlegen. Es ist empfehlenswert, einen weiteren Unterordner mit dem Namen des Dokumentationspakets anzulegen. Für Pakete, die nur eine einzige Bibliothek enthalten, ist dieser Schritt nicht notwendig.</para>
+ <para>
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
+ </para>
- <para>Dies kann dann wie nachstehend angezeigt aussehen: <example><title>Beispiel für die Ordnerstruktur</title>
- <programlisting>
+ <para>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
+ <programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
-</programlisting>
- </example></para>
+]]></programlisting>
+ </example>
+ </para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>Integration in autoconf</title>
-
- <para>Sehr einfach! Fügen Sie eine Zeile zu Ihrem <filename>configure.ac</filename>-Skript hinzu.</para>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
+
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>Integration in autoconf</title>
- <programlisting>
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-</programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>Dazu müssen alle Entwickler gtk-doc installiert haben. Wenn es für das Projekt vertretbar ist, einen optionalen Erstellungsschritt für die api-doc zu haben, so können Sie es wie im Folgenden lösen. Lassen Sie es so, wie es ist, weil gtkdocize nach <function>GTK_DOC_CHECK</function> am Anfang einer Zeile sucht. <example><title>Halten Sie gtk-doc optional</title>
+ <sect2 id="settingup_automake">
+ <title>Integration in automake</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </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)
-])
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
</programlisting>
- </example></para>
+ </example>
- <para>Das erste Argument wird zur Überprüfung von gtkdocversion während des configure-Durchlaufs benutzt. Das zweite, optionale Argument wird von <application>gtkdocize</application> verwendet. Das Makro <symbol>GTK_DOC_CHECK</symbol> fügt verschiedene Schalter für configure hinzu:</para>
- <orderedlist>
- <listitem><para>--with-html-dir=PATH : Pfad zur installierten Dokumentation</para></listitem>
- <listitem><para>--enable-gtk-doc : gtk-doc zur Erstellung der Dokumentation verwenden [Vorgabe=no]</para></listitem>
- <listitem><para>--enable-gtk-doc-html : Erstellung der Dokumentation im HTML-Format [Vorgabe=yes]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : Erstellung der Dokumentation im PDF-Format [Vorgabe=no]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
- <important>
- <para>GTK-Doc ist standardmäßig deaktiviert! Denken Sie daran, die Option <option>'--enable-gtk-doc'</option> beim nächsten Durchlauf von <filename>configure</filename> zu übergeben. Anderenfalls wird die vorher erstellte Dokumentation installiert. Dies ergibt für Benutzer durchaus Sinn, aber nicht für Entwickler.</para>
- </important>
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <para>Weiterhin ist es empfehlenswert, dass das <filename>configure.ac</filename>-Skript die folgende Zeile enthält. Dies erlaubt <application>gtkdocize</application> das automatische Kopieren der Makrodefinition für <function>GTK_DOC_CHECK</function> in Ihr Projekt.</para>
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
- <para>
- <example><title>Vorbereitung für gtkdocize</title>
- <programlisting>
+ All the tools support <option>--help</option> to list the supported
+ options.
+ </para>
+
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>Integration in autoconf</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
-</programlisting>
- </example>
- </para>
- <para>Nachdem alle Änderungen auf <filename>configure.ac</filename> angewendet wurden, aktualisieren Sie die Datei <filename>configure</filename>. Dies geschieht durch erneutes Ausführen von <code>autoreconf -i</code> oder <code>autogen.sh</code>.</para>
- </sect1>
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+]]></programlisting>
+ </example>
+ </para>
+
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
+
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>Integration in automake</title>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <para>Kopieren Sie zunächst die Datei <filename>Makefile.am</filename> aus dem <filename class="directory">Beispiel</filename>-Unterordner der <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink> in den API-Dokumentationsordner Ihres Projekts ( <filename class="directory">./docs/reference/<package></filename>). Eine lokale Kopie sollte beispielsweise unter <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename> verfügbar sein. Falls Sie mehrere Dokumentationspakete haben, müssen Sie dies für jedes davon wiederholen.</para>
+ <orderedlist>
+ <listitem><para>--with-html-dir=PATH : Pfad zur installierten Dokumentation</para></listitem>
+ <listitem><para>--enable-gtk-doc : gtk-doc zur Erstellung der Dokumentation verwenden [Vorgabe=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : Erstellung der Dokumentation im HTML-Format [Vorgabe=yes]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : Erstellung der Dokumentation im PDF-Format [Vorgabe=no]</para></listitem>
+ </orderedlist>
- <para>Im nächsten Schritt bearbeiten Sie die Einstellungen in <filename>Makefile.am</filename>. Allen Einstellungen ist ein Kommentar vorangestellt, der den jeweiligen Zweck beschreibt. Die meisten Einstellungen sind zusätzliche Flags, die an verschiedene Werkzeuge übergeben werden. Jedes der Werkzeuge hat eine Variable der Form <option><WERKZEUGNAME>_OPTIONEN</option>. Alle Werkzeuge unterstützen <option>--help</option> zur Auflistung der unterstützten Parameter.</para>
+ <important>
+ <para>GTK-Doc ist standardmäßig deaktiviert! Denken Sie daran, die Option <option>'--enable-gtk-doc'</option> beim nächsten Durchlauf von <filename>configure</filename> zu übergeben. Anderenfalls wird die vorher erstellte Dokumentation installiert. Dies ergibt für Benutzer durchaus Sinn, aber nicht für Entwickler.</para>
+ </important>
- <!-- FIXME: explain options ? -->
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- </sect1>
+ <sect2 id="settingup_autogen">
+ <title>Integration in autogen</title>
- <sect1 id="settingup_autogen">
- <title>Integration in autogen</title>
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
- <para>Die meisten Projekte dürften über ein <filename>autogen.sh</filename>-Skript verfügen, welches die Build-Infrastruktur nach dem Auschecken aus einem Versionsverwaltungssystem wie CVS, SVN oder Git erzeugt. GTK-Doc liefert ein Werkzeug namens <application>gtkdocize</application> mit, das in einem solchen Skript verwendet werden kann. Es sollte vor autoheader, automake oder autoconf ausgeführt werden.</para>
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
- <para>
- <example><title>Ausführen von gtkdocize durch autogen.sh</title>
- <programlisting>
+ <example><title>Ausführen von gtkdocize durch autogen.sh</title>
gtkdocize || exit 1
</programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>Beim Ausführen von <application>gtkdocize</application> wird <filename>gtk-doc.make</filename> in die Wurzel Ihres Projekts oder in jeden anderen durch die Option <option>--docdir</option> festgelegten Ordner kopiert. Außerdem wird das configure-Skript daraufhin überprüft, ob <function>GTK_DOC_CHECK</function> enthalten ist. Dieses Makro kann verwendet werden, um weitere Parameter an <application>gtkdocize</application> zu übergeben.</para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>In früherer Zeit erzeugte GTK-Doc die Vorlagendateien dort, wo die Entwickler die Dokumentation platzierten. Das stellte sich als nicht optimal heraus, beispielsweise um generierte Dateien unter Versionskontrolle zu haben. Seit einigen Versionen kann GTK-Doc auch sämtliche Informationen aus Quellcode-Kommentaren ermitteln. Seit GTK-Doc 1.9 sind diese Vorlagen nicht mehr notwendig. Wir ermutigen die Entwickler, die Dokumentation innerhalb des Codes zu halten. <application>gtkdocize</application> unterstützt nun die Option <option>--flavour no-tmpl</option>, wodurch ein Makefile gewählt wird, welches die Verwendung der Vorlagen komplett umgeht. Neben der Möglichkeit, diese Option direkt beim Befehlsaufruf zu übergeben, kann Sie auch zu einer Umgebungsvariable namens <symbol>GTKDOCIZE_FLAGS</symbol> hinzugefügt oder als zweiter Parameter im <symbol>GTK_DOC_CHECK</symbol>-Makro im Konfigurationsskript aufgeführt werden. Falls Sie niemals Dateien im Vorlagenordner manuell bearbeitet oder aus älteren GTK-Doc-Versionen importiert haben, sollten Sie den Ordner löschen, z.B. in der Versionsverwaltung.</para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>Erstellung der Dokumentation</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>Nach den bisher absolvierten Schritten ist es Zeit für den Build-Vorgang. Zunächst muss <filename>autogen.sh</filename> erneut ausgeführt werden. Falls dieses Skript auch den configure-Aufruf enthält, sollten Sie die Option <option>--enable-gtk-doc</option> hinzufügen. Anderenfalls führen Sie danach <filename>configure</filename> manuell aus, ebenfalls mit dieser Option.</para>
- <para>Der erste Durchlauf von make erstellt verschiedene zusätzliche Dateien in den Dokumentationsordnern. Die bedeutendsten davon sind: <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (früher .sgml), <filename><package>-sections.txt</filename>.</para>
- <para>
- <example><title>Erstellung der Dokumentation</title>
- <programlisting>
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>Nach den bisher absolvierten Schritten ist es Zeit für den Build-Vorgang. Zunächst muss <filename>autogen.sh</filename> erneut ausgeführt werden. Falls dieses Skript auch den configure-Aufruf enthält, sollten Sie die Option <option>--enable-gtk-doc</option> hinzufügen. Anderenfalls führen Sie danach <filename>configure</filename> manuell aus, ebenfalls mit dieser Option.</para>
+ <para>Der erste Durchlauf von make erstellt verschiedene zusätzliche Dateien in den Dokumentationsordnern. Die bedeutendsten davon sind: <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (früher .sgml), <filename><package>-sections.txt</filename>.</para>
+ <para>
+ <example><title>Erstellung der Dokumentation</title>
+ <programlisting>
./autogen.sh --enable-gtk-doc
make
</programlisting>
- </example>
- </para>
- <para>Nun können Sie <filename>docs/reference/<package>/index.html</filename> in Ihrem Browser öffnen. Zugegeben, das Ergebnis ist noch ein wenig enttäuschend. Im nächsten Abschnitt zeigen wir Ihnen, wie Sie die Seiten mit Leben füllen können.</para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>Integration in Versionsverwaltungssysteme</title>
+ <sect1 id="settingup_cmake">
+ <title>Integration in CMake-Erstellungssysteme</title>
- <para>Als Faustregel gilt, dass alle von Ihnen bearbeiteten Dateien auch unter Versionsverwaltung stehen sollten. In typischen Projekten sind das folgende Dateien: <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (früher .sgml), <filename><package>-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
- <para>Dateien in den Ordnern <filename>xml/</filename> und <filename>html/</filename> sollten nicht unter Versionsverwaltung gestellt werden, ebenso keine der <filename>.stamp</filename>-Dateien.</para>
+ <para>GTK-Doc stellt nun ein <filename>GtkDocConfig.cmake</filename>-Modul (und das korrespondierende <filename>GtkDocConfigVersion.cmake</filename>-Modul) bereit. Dadurch steht Ihnen der Befehl <literal>gtk_doc_add_module</literal> zur Verfügung, den Sie in die Datei <filename>CMakeLists.txt</filename> integrieren können.</para>
+
+ <para>Das folgende Beispiel zeigt, wie dieser Befehl eingesetzt wird. <example><title>Beispiel zur Verwendung von GTK-Doc mit CMake</title>
+ <programlisting>
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+</programlisting>
+ </example></para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integration in Klartext-Makefiles oder andere Erstellungssysteme</title>
<para>Für den Fall, dass jemand nicht automake und damit <filename>gtk-doc.mak</filename> einsetzen will, muss man die gtkdoc-Werkzeuge in eigenen makefiles (oder andere Werkzeuge) in der richtigen Reihenfolge aufrufen.</para>
<para>Man muss sich <filename>Makefile.am</filename> und <filename>gtk-doc.mak</filename> anschauen, um die zusätzlich notwendigen Optionen herauszusuchen.</para>
</sect1>
- <sect1 id="cmake">
- <title>Integration in CMake-Erstellungssysteme</title>
-
- <para>GTK-Doc stellt nun ein <filename>GtkDocConfig.cmake</filename>-Modul (und das korrespondierende <filename>GtkDocConfigVersion.cmake</filename>-Modul) bereit. Dadurch steht Ihnen der Befehl <literal>gtk_doc_add_module</literal> zur Verfügung, den Sie in die Datei <filename>CMakeLists.txt</filename> integrieren können.</para>
-
- <para>Das folgende Beispiel zeigt, wie dieser Befehl eingesetzt wird. <example><title>Beispiel zur Verwendung von GTK-Doc mit CMake</title>
- <programlisting>
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>Integration in Versionsverwaltungssysteme</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>Als Faustregel gilt, dass alle von Ihnen bearbeiteten Dateien auch unter Versionsverwaltung stehen sollten. In typischen Projekten sind das folgende Dateien: <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (früher .sgml), <filename><package>-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
+ <para>Dateien in den Ordnern <filename>xml/</filename> und <filename>html/</filename> sollten nicht unter Versionsverwaltung gestellt werden, ebenso keine der <filename>.stamp</filename>-Dateien.</para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-</programlisting>
- </example></para>
- </sect1>
</chapter>
<chapter id="documenting">
<para>GTK-Doc benutzt Quellcode-Kommentare mit einer speziellen Syntax für Code-Dokumentation. Weiterhin werden Informationen über Ihre Projektstruktur aus anderen Quellen geholt. Im nächsten Abschnitt finden Sie umfassende Informationen über die Syntax der Kommentare.</para>
- <note>
- <title>Platzierung der Dokumentation</title>
- <para>In der Vergangenheit wurde die Dokumentation oft in Dateien gespeichert, die im Ordner <filename>tmpl</filename> liegen. Das hat den Nachteil, dass die Informationen oft nicht aktualisiert wurden und die Datei tendenziell Konflikte mit Versionsverwaltungssystemen verursachen kann.</para>
- <para>Um die bereits genannten Probleme zu vermeiden, empfehlen wir, die Dokumentation innerhalb der Quellen zu halten. In diesem Handbuch wird ausschließlich dieser Weg des Dokumentierens des Quellcodes beschrieben.</para>
- </note>
-
- <para>Der Scanner kann mit den meisten C-Kopfdateien umgehen. Im Falle von Warnungen des Scanners, die wie ein Spezialfall aussehen, kann man GTK-Doc anweisen diese zu überspringen. <example><title>GTK-Doc-Kommentarblock</title>
- <programlisting>
+ <para>
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
+ <example><title>GTK-Doc comment block</title>
+ <programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif
-</programlisting>
- </example></para>
+]]></programlisting>
+ </example>
+ </para>
<note>
<title>Einschränkungen</title>
<para>Verwenden Sie #symbol, um auf andere Symboltypen zu verweisen, z.B. »structs« und »enums« und Makros, die keine Argumente benötigen.</para>
</listitem>
<listitem>
- <para>Verwenden Sie #Object::signal, um auf ein GObject-Signal zu verweisen</para>
+ <para>Verwenden Sie #Object::signal, um auf ein GObject-Signal zu verweisen.</para>
</listitem>
<listitem>
<para>Verwenden Sie #Object:property, um auf eine GObject-Eigenschaft zu verweisen.</para>
<para>Weitere Beispiele zu den unterstützten Markdown-Formatierungen finden Sie in der <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">GTK+ Documentation Markdown Syntax Reference</ulink>.</para>
<tip>
- <para>Wie an früherer Stelle bereits erwähnt, ist GTK-Doc für das Dokumentieren der öffentlichen API gedacht. Daher kann man keine Dokumentation für statische Symbole schreiben. Nichtsdestotrotz ist es jedoch gut, diese Symbole trotzdem zu dokumentieren. Dies hilft anderen, Ihren Code besser zu verstehen. Deswegen empfehlen wir, hierfür normale Kommentare zu verwenden, ohne das zweite »*« in der ersten Zeile. Falls später die Funktion veröffentlicht werden soll, ist es lediglich nötig, im Kommentarblock ein zweites »*« hinzuzufügen und den Symbolnamen an der richtigen Stelle in die Abschnittsdatei einzubauen.</para>
+ <para>
+ As already mentioned earlier GTK-Doc is for documenting public API. Thus
+ one cannot write documentation for static symbols. Nevertheless it is good
+ to comment those symbols too. This helps other developers to understand
+ your code.
+ Therefore we recommend to comment these using normal comments (without the
+ 2nd '*' in the first line).
+ If later the function needs to be made public, all one needs to do is to
+ add another '*' in the comment block and insert the symbol name at the
+ right place inside the sections file.
+ </para>
</tip>
</sect1>
<para>Falls Ihre Bibliothek oder Anwendung GObjects beinhaltet, sollten deren Signale, Argumente/Parameter und Positionen in der Hierarchie in der Dokumentation erscheinen. Alles was Sie tun müssen, ist die <function>xxx_get_type</function>-Funktionen zusammen mit deren Includes in der Datei <filename><package>.types</filename> aufzulisten.</para>
<para>
- <example><title>Beispiel-Schnipsel einer Typen-Datei</title>
+ <example><title>Example <package>.types file</title>
<programlisting>
#include <gtk/gtk.h>
<sect1 id="modernizing-gtk-doc-1-25">
<title>GTK-Doc 1.25</title>
- <para>Die in dieser Version enthaltenen Make-Steuerdateien erzeugen die Entitätsdatei <filename>xml/gtkdocentities.ent</filename>, die Entitäten für beispielsweise package_name und package_version enthält. Sie können diese in der XML-Hauptdatei verwenden, um eine fest codierte Versionsnummer zu vermeiden. Nachfolgend finden Sie ein Beispiel, wie die Entitätsdatei einbezogen wird und und wie die Einträge verwendet werden. Die Entitäten können auch in allen generierten Dateien verwendet werden. GTK-Doc verwendet die gleichen XML-Kopfeinträge auch in generierten Dateien. <example><title>Vorerzeugte Entitäten verwenden</title>
- <programlisting>
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ <para>
+ The makefiles shipped with this version generate an entity file at <filename>xml/gtkdocentities.ent</filename>,
+ containing entities for e.g. package_name and package_version. You can
+ use this e.g. in the main xml file to avoid hardcoding the version
+ number. Below is an example that shows how the entity file is included
+ in the master template and how the entities are used.
+ The entities can also be used in all
+ generated files, GTK-Doc will use the same xml header in generated xml
+ files.
+ <example><title>Use pre-generated entities</title>
+ <programlisting><![CDATA[
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
- <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
- <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
- <bookinfo>
- <title>&package_name; Reference Manual</title>
- <releaseinfo>
- for &package_string;.
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+ <bookinfo>
+ <title>&package_name; Reference Manual</title>
+ <releaseinfo>
+ for &package_string;.
The latest version of this documentation can be found on-line at
- <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
- </releaseinfo>
- </bookinfo>
-</programlisting>
- </example></para>
+ <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
+ </releaseinfo>
+ </bookinfo>
+]]></programlisting>
+ </example>
+ </para>
</sect1>
</chapter>
<!-- gtk-doc warnings: -->
<seglistitem>
<seg>Parameter wird im Kommentarblock des Quellcodes beschrieben, aber existiert nicht</seg>
- <seg>Überprüfen Sie, ob die Parameternamen der Prototypen in der Quelle und im Header unterschiedlich sind</seg>
+ <seg>Überprüfen Sie, ob die Parameternamen der Prototypen in der Quelle und im Header unterschiedlich sind.</seg>
</seglistitem>
<!-- docbook warnings: -->
<revhistory>
<revision>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development</revremark>
+ </revision>
+ <revision>
<revnumber>1.28</revnumber>
<date>24 Mar 2018</date>
<authorinitials>ss</authorinitials>
<orderedlist>
<listitem>
- <para><guilabel>Συγγραφή της τεκμηρίωσης</guilabel> Ο συγγραφέας συμπληρώνει τα πηγαία αρχεία με τεκμηρίωση για όλες τις συναρτήσεις, μακροεντολές, ενώσεις κτλ. (Στο παρελθόν, οι πληροφορίες συμπληρώνονταν σε πρότυπα αρχεία που παράγονταν αυτόματα, αλλά αυτός ο τρόπος δεν συνιστάται πλέον.)</para>
+ <para>
+ <guilabel>Writing the documentation.</guilabel>
+
+ The author fills in the source files with the documentation for each
+ function, macro, structs or unions, etc.
+ </para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>Περί GTK-Doc</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(ΠΡΟΣ ΔΙΟΡΘΩΣΗ)</para>
- <para>(Ιστορικό, συγγραφείς, ιστοσελίδες, λίστα αλληλογραφίας, άδεια, μελλοντικά σχέδια, σύγκριση με άλλα παρόμοια συστήματα.)</para>
+ <para>
+ (authors, web pages, mailing list, license, future plans,
+ comparison with other similar systems.)
+ </para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Δημιουργώντας το δικό σας έργο</title>
+ <title>Project Setup</title>
+
+ <para>
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
- <para>Οι επόμενες ενότητες περιγράφουν τα βήματα που απαιτούνται για να ενσωματώσετε το GTK-Doc στο έργο σας. Αυτές οι ενότητες προϋποθέτουν ότι εργάζεσθε σε ένα έργο που λέγεται 'meep'. Το έργο περιέχει τη βιβλιοθήκη 'libmeep' και την εφαρμογή 'meeper' για τον τελικό χρήστη. Θεωρούμε επίσης, ότι θα χρησιμοποιείτε το autoconf και το automake. Επιπλέον, η ενότητα <link linkend="plain_makefiles">αρχεία makefiles ή άλλα συστήματα ανάπτυξης</link> θα περιγράψει τα βασικά στοιχεία που απαιτούνται για να εργαστείτε σε μια διαφορετική δόμηση ρυθμίσεων.</para>
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
+ </para>
<sect1 id="settingup_docfiles">
<title>Δημιουργία του σκελετού τεκμηρίωσης</title>
- <para>Εντός του ριζικού καταλόγου του έργου δημιουργήστε το φάκελο docs/reference (ώστε να μπορείτε να χρησιμοποιήσετε το όνομα docs/help για την τεκμηρίωση του τελικού χρήστη). Συνιστάται να δημιουργήσετε έναν ακόμη υποκατάλογο με το όνομα του πακέτου τεκμηρίωσης. Αυτό δε χρειάζεται για πακέτα που περιλαμβάνουν μόνο μία βιβλιοθήκη.</para>
+ <para>
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
+ </para>
- <para>Αυτό θα φαίνεται, λοιπόν, όπως εμφανίζεται παρακάτω: <example><title>Παράδειγμα δομής καταλόγου</title>
- <programlisting>
+ <para>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
+ <programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
-</programlisting>
- </example></para>
+]]></programlisting>
+ </example>
+ </para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>Ενσωμάτωση στο autoconf</title>
-
- <para>Πολύ εύκολα! Απλά προσθέτετε μία γραμμή στη δέσμη ενεργειών <filename>configure.ac</filename>.</para>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
+
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>Ενσωμάτωση στο autoconf</title>
- <programlisting>
-# έλεγχος για gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-</programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>Αυτό απαιτεί από όλους τους προγραμματιστές να έχουν εγκατεστημένο το gtk-doc. Αν είναι εντάξει για το έργο σας να έχετε μια επιπλέον δόμηση ρυθμίσεων για το api-doc, μπορείτε να το επιλύσετε όπως αναφέρεται παρακάτω. Αφήστε το ως έχει, όσο το gtkdocize αναζητά την αρχή της σειράς για το <function>GTK_DOC_CHECK</function>. <example><title>Προαιρετικά διατηρήστε το gtk-doc</title>
+ <sect2 id="settingup_automake">
+ <title>Ενσωμάτωση στο automake</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
<programlisting>
-# έλεγχος για gtk-doc
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-],[
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
</programlisting>
- </example></para>
+ </example>
- <para>Το πρώτο όρισμα χρησιμοποιείται για έλεγχο του gtkdocversion κατά τη ρύθμιση. Το δεύτερο, προαιρετικό όρισμα χρησιμοποιείται από το <application>gtkdocize</application>. Η μακροεντολή <symbol>GTK_DOC_CHECK</symbol> επίσης προσθέτει αρκετούς διακόπτες ρύθμισης:</para>
- <orderedlist>
- <listitem><para>--with-html-dir= PATH : διαδρομή προς την εγκατεστημένη τεκμηρίωση</para></listitem>
- <listitem><para>--enable-gtk-doc : χρήση gtk-doc για τη δόμηση τεκμηρίωσης [προεπιλογή=no]</para></listitem>
- <listitem><para>--enable-gtk-doc-html : δόμηση τεκμηρίωσης σε μορφή html [προεπιλογή=yes]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : δόμηση τεκμηρίωσης σε μορφή pdf [προεπιλογή=no]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
- <important>
- <para>Το GTK-Doc είναι απενεργοποιημένο από προεπιλογή! Να θυμάστε να χρησιμοποιείτε την επιλογή <option>'--enable-gtk-doc'</option> στην επόμενη εκτέλεση του <filename>configure</filename>. Διαφορετικά, εγκαθίσταται η προπαραχθείσα τεκμηρίωση (δυνατότητα χρήσιμη για τον χρήστη, αλλά όχι για τον προγραμματιστή).</para>
- </important>
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <para>
- Furthermore it is recommended that you have the following line inside
- your <filename>configure.ac</filename> script.
- This allows <application>gtkdocize</application> to automatically copy the
- macro definition for <function>GTK_DOC_CHECK</function> to your project.
- </para>
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
- <para>
- <example><title>Προετοιμασία για το gtkdocize</title>
- <programlisting>
+ All the tools support <option>--help</option> to list the supported
+ options.
+ </para>
+
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>Ενσωμάτωση στο autoconf</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
-</programlisting>
- </example>
- </para>
- <para>Όταν όλες οι αλλαγές στο <filename>configure.ac</filename> έχουν γίνει, ενημερώστε το αρχείο <filename>configure</filename>. Αυτό μπορείτε να το κάνετε επανεκετελώντας το <code>autoreconf -i</code> ή το <code>autogen.sh</code>.</para>
- </sect1>
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+]]></programlisting>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>Ενσωμάτωση στο automake</title>
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
- <para>Πρώτα αντιγράψτε το <filename>Makefile.am</filename> από τον υποκατάλογο με τα <filename class="directory">παραδείγματα</filename> των <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink> στον κατάλογο της τεκμηρίωσης API του έργου σας ( <filename class="directory">./docs/reference/<package></filename>). Ένα τοπικό αντίγραφο θα πρέπει να είναι διαθέσιμο π.χ. στο <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Αν έχετε πολλά doc-packages επαναλάβετε αυτό το βήμα για το καθένα απο αυτά.</para>
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <para>Το επόμενο βήμα είναι να τροποποιήσετε τις ρυθμίσεις στο <filename>Makefile.am</filename>. Πριν από κάθε ρύθμιση υπάρχει ένα σχόλιο που εξηγεί τη χρησιμότητά της. Οι περισσότερες είναι σημαίες που στέλνονται στα αντίστοιχα εργαλεία. Κάθε εργαλείο διαθέτει μια μεταβλητή της μορφής <option><TOOLNAME>_OPTIONS</option>. Όλα τα εργαλεία υποστηρίζουν την επιλογή <option>--help</option> για την παραγωγή λίστας με τις υποστηριζόμενες παραμέτρους.</para>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <!-- FIXME: explain options ? -->
+ <orderedlist>
+ <listitem><para>--with-html-dir= PATH : διαδρομή προς την εγκατεστημένη τεκμηρίωση</para></listitem>
+ <listitem><para>--enable-gtk-doc : χρήση gtk-doc για τη δόμηση τεκμηρίωσης [προεπιλογή=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : δόμηση τεκμηρίωσης σε μορφή html [προεπιλογή=yes]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : δόμηση τεκμηρίωσης σε μορφή pdf [προεπιλογή=no]</para></listitem>
+ </orderedlist>
- </sect1>
+ <important>
+ <para>Το GTK-Doc είναι απενεργοποιημένο από προεπιλογή! Να θυμάστε να χρησιμοποιείτε την επιλογή <option>'--enable-gtk-doc'</option> στην επόμενη εκτέλεση του <filename>configure</filename>. Διαφορετικά, εγκαθίσταται η προπαραχθείσα τεκμηρίωση (δυνατότητα χρήσιμη για τον χρήστη, αλλά όχι για τον προγραμματιστή).</para>
+ </important>
- <sect1 id="settingup_autogen">
- <title>Ενσωμάτωση στο autogen</title>
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- <para>Τα περισσότερα έργα διαθέτουν ένα σενάριο <filename>autogen.sh</filename> για τη δόμηση υποδομών μετά από έναν έλεγχο από το σύστημα ελέγχου εκδόσεων (π.χ., cvs/svn/git). Το GTK-Doc διαθέτει το εργαλείο <filename>gtkdocize</filename>, το οποίο μπορεί να χρησιμοποιηθεί για ένα τέτοιο σενάριο. Θα πρέπει να εκτελείται πριν το autoheader, το automake ή το autoconf.</para>
+ <sect2 id="settingup_autogen">
+ <title>Ενσωμάτωση στο autogen</title>
- <para>
- <example><title>Εκτέλεση του gtkdocize από το autogen.sh</title>
- <programlisting>
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
+
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
+
+ <para>
+ <example><title>Εκτέλεση του gtkdocize από το autogen.sh</title>
+ <programlisting>
gtkdocize || exit 1
</programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>Κατά την εκτέλεσή του, το <filename>gtkdocize</filename> αντιγράφει το <filename>gtk-doc.make</filename> στο ριζικό κατάλογο του έργου σας (ή στον κατάλογο που ορίζει η επιλογή <option>--docdir</option>). Επίσης, ελέγχει τη δέσμη ενεργειών configure για να βρει την κλήση στο <function>GTK_DOC_CHECK</function>.</para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>Αρχικά, το GTK-Doc δημιουργούσε αρχεία προτύπων εκεί που οι προγραμματιστές εισήγαγαν την τεκμηρίωση. Δυστυχώς, αυτή η προσέγγιση δεν ήταν ιδιαίτερα επιτυχής (π.χ η ανάγκη για παραγωγή αρχείων στο σύστημα ελέγχου εκδόσεων). Από την έκδοση 1.9 και μετά, τα πρότυπα αρχεία δεν είναι πλέον απαραίτητα. Σας συνιστούμε να διατηρείτε την τεκμηρίωση στον κώδικα. To <application>gtkdocize</application> υποστηρίζει πλέον την επιλογή <option>--flavour no-tmpl</option> που επιλέγει ένα αρχείο makefile που δεν χρησιμοποιεί καθόλου πρότυπα tmpl. Πέρα από την άμεση προσθήκη της επιλογής στην κλήση της εντολής, μπορεί να προστεθεί και σε μια μεταβλητή περιβάλλοντος που ονομάζεται <symbol>GTKDOCIZE_FLAGS</symbol> ή να ορισθεί ως δεύτερη παράμετρος στη μακροεντολή <symbol>GTK_DOC_CHECK</symbol> στο σενάριο configure. Αν δεν έχετε κάνει ποτέ αλλαγές με το χέρι σε αρχεία προτύπων και μεταβαίνετε από μια παλιότερη έκδοση του gtkdoc, παρακαλώ αφαιρέστε τον κατάλογο (π.χ. από το σύστημα ελέγχου εκδόσεων).</para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>Εκτέλεση της δόμησης τεκμηρίωσης</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>Αφού ολοκληρωθούν τα προηγούμενα βήματα, προχωρήστε στην δόμηση. Πρώτα, θα πρέπει να εκτελεσθεί εκ νέου το <filename>autogen.sh</filename>. Αν το σενάριο εκτελεί και το configure, προσθέστε την επιλογή <option>--enable-gtk-doc</option>. Διαφορετικά, εκτελέστε εσείς το<filename>configure</filename> με αυτή την επιλογή.</para>
- <para>Η πρώτη εκτέλεση του make δημιουργεί μια σειρά από πρόσθετα αρχεία στους καταλόγους της τεκμηρίωσης. Τα σημαντικά είναι τα: <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (στο παρελθόν .sgml), <filename><package>-sections.txt</filename>.</para>
- <para>
- <example><title>Εκτέλεση της δόμησης τεκμηρίωσης</title>
- <programlisting>
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>Αφού ολοκληρωθούν τα προηγούμενα βήματα, προχωρήστε στην δόμηση. Πρώτα, θα πρέπει να εκτελεσθεί εκ νέου το <filename>autogen.sh</filename>. Αν το σενάριο εκτελεί και το configure, προσθέστε την επιλογή <option>--enable-gtk-doc</option>. Διαφορετικά, εκτελέστε εσείς το<filename>configure</filename> με αυτή την επιλογή.</para>
+ <para>Η πρώτη εκτέλεση του make δημιουργεί μια σειρά από πρόσθετα αρχεία στους καταλόγους της τεκμηρίωσης. Τα σημαντικά είναι τα: <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (στο παρελθόν .sgml), <filename><package>-sections.txt</filename>.</para>
+ <para>
+ <example><title>Εκτέλεση της δόμησης τεκμηρίωσης</title>
+ <programlisting>
./autogen.sh --enable-gtk-doc
make
</programlisting>
- </example>
- </para>
- <para>Τώρα, μπορείτε να εμφανίσετε το <filename>docs/reference/<package>/index.html</filename> στον περιηγητή σας. Είναι αλήθεια ότι προς το παρόν το αποτέλεσμα είναι μάλλον απογοητευτικό. Μην ανησυχείτε όμως. Στο επόμενο κεφάλαιο θα μάθετε πώς μπορείτε να ζωντανέψετε τις σελίδες σας.</para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>Ενσωμάτωση σε συστήματα ελέγχου εκδόσεων</title>
+ <sect1 id="settingup_cmake">
+ <title>Ενσωμάτωση με συστήματα δόμησης CMake</title>
- <para>Ο εμπειρικός κανόνας είναι ότι αυτά τα αρχεία που επεξεργασθήκατε πρέπει να περάσουν από τον έλεγχο έκδοσης. Για τυπικά έργα, πρόκειται για τα αρχεία: <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (στο παρελθόν .sgml), <filename><package>-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
- <para>Αρχεία στους καταλόγους <filename>xml/</filename> και <filename>html/</filename> δεν θα πρέπει να υποβληθούν σε έλεγχο έκδοσης. Ούτε και αρχεία <filename>xml/</filename> and <filename>html/</filename>.</para>
+ <para>Το GTK-Doc παρέχει το άρθρωμα <filename>GtkDocConfig.cmake</filename> (και το αντίστοιχο άρθρωμα <filename>GtkDocConfigVersion.cmake</filename>). Επίσης παρέχει την εντολή <literal>gtk_doc_add_module</literal> την οποία μπορείτε να ορίσετε στο αρχείο <filename>CMakeLists.txt</filename>.</para>
+
+ <para>Το ακόλουθο παράδειγμα δείχνει πως να χρησιμοποιήσετε την εντολή. <example><title>Παράδειγμα χρήσης του GTK-Doc από το CMake</title>
+ <programlisting>
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+</programlisting>
+ </example></para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Ενσωμάτωση στα αρχεία makefiles ή άλλα συστήματα δόμησης</title>
<para>Στην περίπτωση που κάποιος δε θέλει να χρησιμοποιήσει το automake και, επομένως, το <filename>gtk-doc.mak</filename> θα χρειαστεί να καλέσει τα εργαλεία του gtkdoc στη σωστή σειρά στα makefiles (ή άλλα εργαλεία δόμησης).</para>
<para>Πρέπει να κοιτάξετε στα αρχεία <filename>Makefile.am</filename> και <filename>gtk-doc.mak</filename> για να επιλέξετε τις ρυθμίσεις που χρειάζονται.</para>
</sect1>
- <sect1 id="cmake">
- <title>Ενσωμάτωση με συστήματα δόμησης CMake</title>
-
- <para>Το GTK-Doc παρέχει το άρθρωμα <filename>GtkDocConfig.cmake</filename> (και το αντίστοιχο άρθρωμα <filename>GtkDocConfigVersion.cmake</filename>). Επίσης παρέχει την εντολή <literal>gtk_doc_add_module</literal> την οποία μπορείτε να ορίσετε στο αρχείο <filename>CMakeLists.txt</filename>.</para>
-
- <para>Το ακόλουθο παράδειγμα δείχνει πως να χρησιμοποιήσετε την εντολή. <example><title>Παράδειγμα χρήσης του GTK-Doc από το CMake</title>
- <programlisting>
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>Ενσωμάτωση σε συστήματα ελέγχου εκδόσεων</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>Ο εμπειρικός κανόνας είναι ότι αυτά τα αρχεία που επεξεργασθήκατε πρέπει να περάσουν από τον έλεγχο έκδοσης. Για τυπικά έργα, πρόκειται για τα αρχεία: <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (στο παρελθόν .sgml), <filename><package>-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
+ <para>Αρχεία στους καταλόγους <filename>xml/</filename> και <filename>html/</filename> δεν θα πρέπει να υποβληθούν σε έλεγχο έκδοσης. Ούτε και αρχεία <filename>xml/</filename> and <filename>html/</filename>.</para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-</programlisting>
- </example></para>
- </sect1>
</chapter>
<chapter id="documenting">
<para>Το GTK-Doc χρησιμοποιεί σχόλια με ειδική σύνταξη για την προσθήκη τεκμηρίωσης στον κώδικα. Παράλληλα, ανακαλεί πληροφορίες για τη δομή του έργου σας από άλλες πηγές. Στην επόμενη ενότητα περιέχονται όλες οι λεπτομέρειες για τη σύνταξη αυτών των σχολίων.</para>
- <note>
- <title>Τοποθέτηση τεκμηρίωσης</title>
- <para>Στο παρελθόν, η τεκμηρίωση έπρεπε να συμπληρώνεται σε αρχεία του καταλόγου <filename>tmpl</filename>. Αυτή η προσέγγιση εμφανίζει το μειονέκτημα ότι οι πληροφορίες δεν ενημερώνονται συχνά, καθώς και το ότι προκύπτουν περιοδικές συγκρούσεις με τα συστήματα ελέγχου εκδόσεων.</para>
- <para>Για να αποφύγετε αυτά τα προβλήματα, σας προτείνουμε να ενσωματώνετε την τεκμηρίωση στον πηγαίο κώδικα. Αυτή είναι και η μόνη μέθοδος που θα περιγράψουμε σε αυτό το εγχειρίδιο.</para>
- </note>
-
- <para>Ο σαρωτής μπορεί να χειρισθεί άνετα την πλειοψηφία των κεφαλίδων C. Σε περίπτωση που παίρνετε προειδοποιήσεις από τον σαρωτή οι οποίες μοιάζουν με έναν ειδικό χαρακτήρα, μπορείτε να υποδείξετε στο GTK-Doc να τους παραλείψει. <example><title>Μπλοκ σχολίου GTK-Doc</title>
- <programlisting>
+ <para>
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
+ <example><title>GTK-Doc comment block</title>
+ <programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif
-</programlisting>
- </example></para>
+]]></programlisting>
+ </example>
+ </para>
<note>
<title>Περιορισμοί</title>
<para>Μπορείτε να βρείτε περισσότερα παραδείγματα για το ποιες ετικέτες markdown υποστηρίζονται στη διεύθυνση <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">GTK+ Documentation Markdown Syntax Reference</ulink>.</para>
<tip>
- <para>Όπως αναφέρθηκε και προηγουμένως το GTK-Doc στοχεύει στην τεκμηρίωση του δημόσιου API. Άρα, δεν μπορεί κάποιος να γράψει τεκμηρίωση για στατικά σύμβολα. Παρόλα αυτά, συνιστάται ο σχολιασμός και αυτών των συμβόλων, γιατί βοηθά στην κατανόηση του κώδικα. Σας προτείνουμε λοιπόν να τα σχολιάζετε χρησιμοποιώντας κανονικά σχόλια (χωρίς το δεύτερο «*» στην πρώτη γραμμή). Αν αργότερα χρειαστεί να μετατραπεί η συνάρτηση σε δημόσια, το μόνο που θα πρέπει να γίνει είναι να προστεθεί άλλο ένα «*» στο μπλοκ του σχολίου, και να εισαχθεί το όνομα του συμβόλου στην κατάλληλη θέση του αρχείου ενοτήτων.</para>
+ <para>
+ As already mentioned earlier GTK-Doc is for documenting public API. Thus
+ one cannot write documentation for static symbols. Nevertheless it is good
+ to comment those symbols too. This helps other developers to understand
+ your code.
+ Therefore we recommend to comment these using normal comments (without the
+ 2nd '*' in the first line).
+ If later the function needs to be made public, all one needs to do is to
+ add another '*' in the comment block and insert the symbol name at the
+ right place inside the sections file.
+ </para>
</tip>
</sect1>
<para>Αν η βιβλιοθήκη ή η εφαρμογή σας περιέχει GObjects, θα θέλετε να εμφανίζονται στην τεκμηρίωση τα σήματα, τα ορίσματα/παράμετροι καθώς και η θέση τους στην ιεραρχία. Για να το πετύχετε, απλά καταγράψτε τις συναρτήσεις <function>xxx_get_type</function> μαζί με την συμπερίληψή τους στο αρχείο <filename><package>.types</filename>.</para>
<para>
- <example><title>Υπόδειγμα αποσπάσματος αρχείου types</title>
+ <example><title>Example <package>.types file</title>
<programlisting>
#include <gtk/gtk.h>
containing entities for e.g. package_name and package_version. You can
use this e.g. in the main xml file to avoid hardcoding the version
number. Below is an example that shows how the entity file is included
- and how the entities are used. The entities can also be used in all
+ in the master template and how the entities are used.
+ The entities can also be used in all
generated files, GTK-Doc will use the same xml header in generated xml
files.
<example><title>Use pre-generated entities</title>
<revhistory>
<revision>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development</revremark>
+ </revision>
+ <revision>
<revnumber>1.28</revnumber>
<date>24 Mar 2018</date>
<authorinitials>ss</authorinitials>
<orderedlist>
<listitem>
- <para><guilabel>Writing the documentation.</guilabel> The author fills in the source files with the documentation for each function, macro, union etc. (In the past information was entered in generated template files, which is not recommended any more).</para>
+ <para>
+ <guilabel>Writing the documentation.</guilabel>
+
+ The author fills in the source files with the documentation for each
+ function, macro, structs or unions, etc.
+ </para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>About GTK-Doc</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(FIXME)</para>
<para>
- (History, authors, web pages, mailing list, license, future plans,
+ (authors, web pages, mailing list, license, future plans,
comparison with other similar systems.)
</para>
</chapter>
<chapter id="settingup">
- <title>Setting up your project</title>
+ <title>Project Setup</title>
<para>
- The next sections describe what steps to perform to integrate GTK-Doc into
- your project. Theses sections assume we work on a project called 'meep'.
- This project contains a library called 'libmeep' and
- an end-user app called 'meeper'. We also assume you will be using autoconf
- and automake. In addition section <link linkend="plain_makefiles">plain
- makefiles or other build systems</link> will describe the basics needed to
- work in a different build setup.
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
</para>
<sect1 id="settingup_docfiles">
<title>Setting up a skeleton documentation</title>
- <para>Under your top-level project directory create a folder called <filename class="directory">docs/reference</filename> (this way you can also have <filename class="directory">docs/help</filename> for end-user documentation). It is recommended to create another subdirectory with the name of the doc-package. For packages with just one library this step is not necessary.</para>
+ <para>
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
+ </para>
<para>
- This can then look as shown below:
- <example><title>Example directory structure</title>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
<programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
</para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>Integration with autoconf</title>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
- <para>Very easy! Just add one line to your <filename>configure.ac</filename> script.</para>
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>Integration with autoconf</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-]]></programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>
- This will require all developers to have gtk-doc installed. If it is
- okay for your project to have optional api-doc build setup, you can
- solve this as below. Keep it as is, as gtkdocize is looking for
- <function>GTK_DOC_CHECK</function> at the start of a line.
- <example><title>Keep gtk-doc optional</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-],[
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
-]]></programlisting>
+ <sect2 id="settingup_automake">
+ <title>Integration with automake</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
+ <programlisting>
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
+</programlisting>
</example>
- </para>
- <para>
- The first argument is used to check for the gtkdocversion at configure time.
- The 2nd, optional argument is used by <application>gtkdocize</application>.
- The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure switches:
- </para>
- <orderedlist>
- <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
- <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
- <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
+
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
+
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
- <important>
- <para>
- GTK-Doc is disabled by default! Remember to pass the option
- <option>'--enable-gtk-doc'</option> to the next
- <filename>configure</filename> run. Otherwise pregenerated documentation is installed
- (which makes sense for users but not for developers).
+ All the tools support <option>--help</option> to list the supported
+ options.
</para>
- </important>
- <para>
- Furthermore it is recommended that you have the following line inside
- your <filename>configure.ac</filename> script.
- This allows <application>gtkdocize</application> to automatically copy the
- macro definition for <function>GTK_DOC_CHECK</function> to your project.
- </para>
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
- <para>
- <example><title>Preparation for gtkdocize</title>
- <programlisting><![CDATA[
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>Integration with autoconf</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
]]></programlisting>
- </example>
- </para>
- <para>
- After all changes to <filename>configure.ac</filename> are made, update
- the <filename>configure</filename> file. This can be done by re-running
- <code>autoreconf -i</code> or <code>autogen.sh</code>.
- </para>
- </sect1>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>Integration with automake</title>
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub directory of the
- <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
- to your project's API documentation directory (
- <filename class="directory">./docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple doc-packages repeat this for each one.
- </para>
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <para>
- The next step is to edit the settings inside the <filename>Makefile.am</filename>.
- All the settings have a comment above that describes their purpose.
- Most settings are extra flags passed to the respective tools. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
- All the tools support <option>--help</option> to list the supported
- parameters.
- </para>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <!-- FIXME: explain options ? -->
+ <orderedlist>
+ <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
+ <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
+ </orderedlist>
- </sect1>
+ <important>
+ <para>
+ GTK-Doc is disabled by default! Remember to pass the option
+ <option>'--enable-gtk-doc'</option> to the next
+ <filename>configure</filename> run. Otherwise pregenerated documentation is installed
+ (which makes sense for users but not for developers).
+ </para>
+ </important>
- <sect1 id="settingup_autogen">
- <title>Integration with autogen</title>
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- <para>
- Most projects will have an <filename>autogen.sh</filename> script to
- setup the build infrastructure after a checkout from version control
- system (such as cvs/svn/git). GTK-Doc comes with a tool called
- <application>gtkdocize</application> which can be used in such a script.
- It should be run before autoheader, automake or autoconf.
- </para>
+ <sect2 id="settingup_autogen">
+ <title>Integration with autogen</title>
- <para>
- <example><title>Running gtkdocize from autogen.sh</title>
- <programlisting><![CDATA[
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
+
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
+
+ <para>
+ <example><title>Running gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
gtkdocize || exit 1
]]></programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>
- When running <application>gtkdocize</application> it copies
- <filename>gtk-doc.make</filename> to your project root (or any directory
- specified by the <option>--docdir</option> option).
- It also checks you configure script for the <function>GTK_DOC_CHECK</function>
- invocation. This macro can be used to pass extra parameters to
- <application>gtkdocize</application>.
- </para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>
- Historically GTK-Doc was generating template files where developers entered the docs.
- This turned out to be not so good (e.g. the need for having generated
- files under version control).
- Since GTK-Doc 1.9 the tools can get all the information from source comments
- and thus the templates can be avoided. We encourage people to keep
- documentation in the code. <application>gtkdocize</application> supports now
- a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
- tmpl usage totally. Besides adding the option directly to the command
- invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
- or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
- If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
- please remove the directory (e.g. from version control system).
- </para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>Running the doc build</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>After the previous steps it is time to run the build. First we need to rerun <filename>autogen.sh</filename>. If this script runs <filename>configure</filename> for you, then give it the <option>--enable-gtk-doc</option> option. Otherwise manually run <filename>configure</filename> with this option afterwards.</para>
- <para>
- The first make run generates several additional files in the doc-directories.
- The important ones are:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>.
- </para>
- <para>
- <example><title>Running the doc build</title>
- <programlisting><![CDATA[
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>After the previous steps it is time to run the build. First we need to rerun <filename>autogen.sh</filename>. If this script runs <filename>configure</filename> for you, then give it the <option>--enable-gtk-doc</option> option. Otherwise manually run <filename>configure</filename> with this option afterwards.</para>
+ <para>
+ The first make run generates several additional files in the doc-directories.
+ The important ones are:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>.
+ </para>
+ <para>
+ <example><title>Running the doc build</title>
+ <programlisting><![CDATA[
./autogen.sh --enable-gtk-doc
make
]]></programlisting>
- </example>
- </para>
- <para>Now you can point your browser to <filename>docs/reference/<replaceable>package</replaceable>/index.html</filename>. Yes, it's a bit disappointing still. But hang on; during the next chapter we tell you how to fill the pages with life.</para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>Integration with version control systems</title>
+ <sect1 id="settingup_cmake">
+ <title>Integration with CMake build systems</title>
<para>
- As a rule of thumb, it's the files you edit which should go under
- version control. For typical projects it's these files:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>,
- <filename>Makefile.am</filename>.
+ GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
+ (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
+ module). This provides a <literal>gtk_doc_add_module</literal>
+ command that you can set in your <filename>CMakeLists.txt</filename>
+ file.
</para>
+
<para>
- Files in the <filename>xml/</filename> and <filename>html/</filename>
- directories should not go under version control. Neither should any of
- the <filename>.stamp</filename> files.
+ The following example shows how to use this command.
+ <example><title>Example of using GTK-Doc from CMake</title>
+ <programlisting><![CDATA[
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+]]></programlisting>
+ </example>
</para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integration with plain makefiles or other build systems</title>
<para>
</para>
</sect1>
- <sect1 id="cmake">
- <title>Integration with CMake build systems</title>
-
- <para>
- GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
- (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
- module). This provides a <literal>gtk_doc_add_module</literal>
- command that you can set in your <filename>CMakeLists.txt</filename>
- file.
- </para>
-
- <para>
- The following example shows how to use this command.
- <example><title>Example of using GTK-Doc from CMake</title>
- <programlisting><![CDATA[
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>Integration with version control systems</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>
+ As a rule of thumb, it's the files you edit which should go under
+ version control. For typical projects it's these files:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>,
+ <filename>Makefile.am</filename>.
+ </para>
+ <para>
+ Files in the <filename>xml/</filename> and <filename>html/</filename>
+ directories should not go under version control. Neither should any of
+ the <filename>.stamp</filename> files.
+ </para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
- </sect1>
</chapter>
<chapter id="documenting">
syntax of the comments.
</para>
- <note>
- <title>Documentation placement</title>
- <para>In the past most documentation had to be filled into files residing inside the <filename class="directory">tmpl</filename> directory. This has the disadvantages that the information is often not updated and also that the file tend to cause conflicts with version control systems.</para>
- <para>To avoid the aforementioned problems we suggest putting the documentation inside the sources. This manual will only describe this way of documenting code.</para>
- </note>
-
<para>
- The scanner can handle the majority of C headers fine. In the case of
- receiving warnings from the scanner that look like a special case, one can
- hint GTK-Doc to skip over them.
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<para>
As already mentioned earlier GTK-Doc is for documenting public API. Thus
one cannot write documentation for static symbols. Nevertheless it is good
- to comment those symbols too. This helps other to understand you code.
+ to comment those symbols too. This helps other developers to understand
+ your code.
Therefore we recommend to comment these using normal comments (without the
2nd '*' in the first line).
If later the function needs to be made public, all one needs to do is to
</para>
<para>
- <example><title>Example types file snippet</title>
+ <example><title>Example <package>.types file</title>
<programlisting><![CDATA[
#include <gtk/gtk.h>
containing entities for e.g. package_name and package_version. You can
use this e.g. in the main xml file to avoid hardcoding the version
number. Below is an example that shows how the entity file is included
- and how the entities are used. The entities can also be used in all
+ in the master template and how the entities are used.
+ The entities can also be used in all
generated files, GTK-Doc will use the same xml header in generated xml
files.
<example><title>Use pre-generated entities</title>
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc-help.master\n"
-"POT-Creation-Date: 2017-12-28 10:31+0000\n"
-"PO-Revision-Date: 2018-02-22 12:50+0100\n"
+"POT-Creation-Date: 2018-05-20 18:37+0000\n"
+"PO-Revision-Date: 2018-07-31 12:18+0200\n"
"Last-Translator: Daniel Mustieles <daniel.mustieles@gmail.com>\n"
"Language-Team: es <gnome-es-list@gnome.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
-"X-Generator: Gtranslator 2.91.6\n"
+"X-Generator: Gtranslator 2.91.7\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
msgctxt "_"
msgid "translator-credits"
msgstr ""
-"Daniel Mustieles <daniel.mustieles@gmail.com>, 2009 - 2017\n"
+"Daniel Mustieles <daniel.mustieles@gmail.com>, 2009 - 2018\n"
"Jorge González <jorgegonz@svn.gnome.org>, 2009 - 2011\n"
"Francisco Javier F. Serrador <serrrador@svn.gnome.org>, 2009, 2010"
#: C/index.docbook:83
#| msgid ""
#| "<revnumber>1.27.1</revnumber> <date>07 Dec 2017</date> "
-#| "<authorinitials>ss</authorinitials> <revremark>developemnt</revremark>"
+#| "<authorinitials>ss</authorinitials> <revremark>development</revremark>"
msgid ""
-"<revnumber>1.2
7.1</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
+"<revnumber>1.2
8.1</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>development</revremark>"
msgstr ""
-"<revnumber>1.27.1</revnumber> <date>07 de diciembre de 2017</date> "
+"<revnumber>1.28.1</revnumber> <date>24 de marzo de 2018</date> "
"<authorinitials>ss</authorinitials> <revremark>desarrollo</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
+#| msgid ""
+#| "<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
+#| "authorinitials> <revremark>bug fix</revremark>"
+msgid ""
+"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes</revremark>"
+msgstr ""
+"<revnumber>1.28</revnumber> <date>24 de marzo de 2018</date> "
+"<authorinitials>ss</authorinitials> <revremark>correcciones de errores</"
+"revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
msgid ""
"<revnumber>1.27</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>fine tuning of the python port</revremark>"
"python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
msgid ""
"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>port all tools from perl/bash to python</"
"de perl/bash a python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
+#: C/index.docbook:107
msgid ""
"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
"limpieza</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:107
+#: C/index.docbook:113
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:113
+#: C/index.docbook:119
msgid ""
"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:119
+#: C/index.docbook:125
msgid ""
"<revnumber>1.22</revnumber> <date>07 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"eliminadas funcionalidades obsoletas</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:125
+#: C/index.docbook:131
msgid ""
"<revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"eliminadas funcionalidades obsoletas</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:131
+#: C/index.docbook:137
msgid ""
"<revnumber>1.20</revnumber> <date>16 Feb 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, markdown support, style improvements</"
"de marcado, mejoras en los estilos</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:137
+#: C/index.docbook:143
msgid ""
"<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:143
+#: C/index.docbook:149
msgid ""
"<revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, speedups, markdown support</revremark>"
"mejoras en la velocidad y soporte de marcado</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:149
+#: C/index.docbook:155
msgid ""
"<revnumber>1.17</revnumber> <date>26 Feb 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>urgent bug fix update</revremark>"
"corrección de error</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:155
+#: C/index.docbook:161
msgid ""
"<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes, layout improvements</revremark>"
"mejoras en la distribución</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:161
+#: C/index.docbook:167
msgid ""
"<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bug and regression fixes</revremark>"
"regresiones</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:167
+#: C/index.docbook:173
msgid ""
"<revnumber>1.14</revnumber> <date>28 March 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes and performance improvements</revremark>"
"mejoras en el rendimiento</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:173
+#: C/index.docbook:179
msgid ""
"<revnumber>1.13</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>broken tarball update</"
"roto</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:179
+#: C/index.docbook:185
msgid ""
"<revnumber>1.12</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>new tool features and "
"nuevas características</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:185
+#: C/index.docbook:191
msgid ""
"<revnumber>1.11</revnumber> <date>16 November 2008</date> "
"<authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</"
"revremark>"
#. (itstool) path: chapter/title
-#: C/index.docbook:198
+#: C/index.docbook:204
msgid "Introduction"
msgstr "Introducción"
#. (itstool) path: chapter/para
-#: C/index.docbook:200
+#: C/index.docbook:206
msgid ""
"This chapter introduces GTK-Doc and gives an overview of what it is and how "
"it is used."
"es y cómo usarlo."
#. (itstool) path: sect1/title
-#: C/index.docbook:206
+#: C/index.docbook:212
msgid "What is GTK-Doc?"
msgstr "¿Qué es GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:208
+#: C/index.docbook:214
msgid ""
"GTK-Doc is used to document C code. It is typically used to document the "
"public API of libraries, such as the GTK+ and GNOME libraries. But it can "
"Pero también se puede usar para documentar código de aplicaciones."
#. (itstool) path: sect1/title
-#: C/index.docbook:216
+#: C/index.docbook:222
msgid "How Does GTK-Doc Work?"
msgstr "¿Cómo funciona GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:218
+#: C/index.docbook:224
msgid ""
"GTK-Doc works by using documentation of functions placed inside the source "
"files in specially-formatted comment blocks, or documentation added to the "
"archivos de cabecera; no produce salida para funciones estáticas)."
#. (itstool) path: sect1/para
-#: C/index.docbook:225
+#: C/index.docbook:231
msgid ""
"GTK-Doc consists of a number of python scripts, each performing a different "
"step in the process."
"diferente en el proceso."
#. (itstool) path: sect1/para
-#: C/index.docbook:230
+#: C/index.docbook:236
msgid "There are 5 main steps in the process:"
msgstr "Existen 5 pasos importantes en el proceso:"
#. (itstool) path: listitem/para
-#: C/index.docbook:237
+#: C/index.docbook:243
msgid ""
"<guilabel>Writing the documentation.</guilabel> The author fills in the "
"source files with the documentation for each function, macro, union etc. (In "
"lo que ya no se recomienda)."
#. (itstool) path: listitem/para
-#: C/index.docbook:247
+#: C/index.docbook:253
msgid ""
"<guilabel>Gathering information about the code.</guilabel> "
"<application>gtkdoc-scan</application> scans the header files of the code "
"txt</filename> dentro de <filename><module>-overrides.txt</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:264
+#: C/index.docbook:270
msgid ""
"<application>gtkdoc-scangobj</application> can also be used to dynamically "
"query a library about any GObject subclasses it exports. It saves "
"que proporciona."
#. (itstool) path: listitem/para
-#: C/index.docbook:270
+#: C/index.docbook:276
msgid ""
"<application>gtkdoc-scanobj</application> should not be used anymore. It was "
"needed in the past when GObject was still GtkObject inside gtk+."
"necesitó en el pasado, cuando GObject todavía era GtkObject dentro de GTK+."
#. (itstool) path: listitem/para
-#: C/index.docbook:277
+#: C/index.docbook:283
msgid ""
"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
"mkdb</application> turns the template files into XML files in the <filename "
"obtiene los documentos de los fuentes y los datos obtenidos en introspección."
#. (itstool) path: listitem/para
-#: C/index.docbook:286
+#: C/index.docbook:292
msgid ""
"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
"paquete>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:292
+#: C/index.docbook:298
msgid ""
"Files in <filename class=\"directory\">xml/</filename> and <filename class="
"\"directory\">html/</filename> directories are always overwritten. One "
"Nunca se deben editar directamente."
#. (itstool) path: listitem/para
-#: C/index.docbook:300
+#: C/index.docbook:306
msgid ""
"<guilabel>Fixing up cross-references between documents.</guilabel> After "
"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
"esa documentación está instalada)."
#. (itstool) path: sect1/title
-#: C/index.docbook:318
+#: C/index.docbook:324
msgid "Getting GTK-Doc"
msgstr "Obtener GTK-Doc"
#. (itstool) path: sect2/title
-#: C/index.docbook:321
+#: C/index.docbook:327
msgid "Requirements"
msgstr "Requerimientos"
#. (itstool) path: sect2/para
-#: C/index.docbook:322
+#: C/index.docbook:328
msgid ""
"<guilabel>python 2/3</guilabel> - the main scripts are written in python."
msgstr ""
"python."
#. (itstool) path: sect2/para
-#: C/index.docbook:325
+#: C/index.docbook:331
msgid ""
"<guilabel>xsltproc</guilabel> - the xslt processor from libxslt <ulink url="
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
#. (itstool) path: sect2/para
-#: C/index.docbook:329
+#: C/index.docbook:335
msgid ""
"<guilabel>docbook-xsl</guilabel> - the docbook xsl stylesheets <ulink url="
"\"http://sourceforge.net/projects/docbook/files/docbook-xsl/\" type=\"http"
"\"http\">sourceforge.net/projects/docbook/files/docbook-xsl</ulink>"
#. (itstool) path: sect2/para
-#: C/index.docbook:333
+#: C/index.docbook:339
msgid ""
"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
"los ejemplos."
#. (itstool) path: sect1/title
-#: C/index.docbook:341
+#: C/index.docbook:347
msgid "About GTK-Doc"
msgstr "Acerca de GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:343 C/index.docbook:357
+#: C/index.docbook:349 C/index.docbook:363
msgid "(FIXME)"
msgstr "(ARRÉGLAME)"
#. (itstool) path: sect1/para
-#: C/index.docbook:347
+#: C/index.docbook:353
msgid ""
"(History, authors, web pages, mailing list, license, future plans, "
"comparison with other similar systems.)"
"futuros, comparación con otros sistemas similares.)"
#. (itstool) path: sect1/title
-#: C/index.docbook:355
+#: C/index.docbook:361
msgid "About this Manual"
msgstr "Acerca de este manual"
#. (itstool) path: sect1/para
-#: C/index.docbook:361
+#: C/index.docbook:367
msgid "(who it is meant for, where you can get it, license)"
msgstr "(a quién está dirigido, dónde puede obtenerse, licencia)"
#. (itstool) path: chapter/title
-#: C/index.docbook:370
+#: C/index.docbook:376
msgid "Setting up your project"
msgstr "Configurando su proyecto"
#. (itstool) path: chapter/para
-#: C/index.docbook:372
+#: C/index.docbook:378
msgid ""
"The next sections describe what steps to perform to integrate GTK-Doc into "
"your project. Theses sections assume we work on a project called 'meep'. "
"construcción diferente."
#. (itstool) path: sect1/title
-#: C/index.docbook:383
+#: C/index.docbook:389
msgid "Setting up a skeleton documentation"
msgstr "Configurar el esquema de la documentación"
#. (itstool) path: sect1/para
-#: C/index.docbook:385
+#: C/index.docbook:391
msgid ""
"Under your top-level project directory create folders called docs/reference "
"(this way you can also have docs/help for end-user documentation). It is "
"Para paquetes con una sola biblioteca este paso no es necesario."
#. (itstool) path: example/title
-#: C/index.docbook:394
+#: C/index.docbook:400
msgid "Example directory structure"
msgstr "Ejemplo de estructura de carpetas"
#. (itstool) path: example/programlisting
-#: C/index.docbook:395
+#: C/index.docbook:401
#, no-wrap
msgid ""
"\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:392
+#: C/index.docbook:398
msgid "This can then look as shown below: <_:example-1/>"
msgstr "Esto después aparecerá como se muestra debajo: <_:example-1/>"
#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:410 C/index.docbook:417
+#: C/index.docbook:416 C/index.docbook:423
msgid "Integration with autoconf"
msgstr "Integración con autoconf"
#. (itstool) path: sect1/para
-#: C/index.docbook:412
+#: C/index.docbook:418
msgid ""
"Very easy! Just add one line to your <filename>configure.ac</filename> "
"script."
"filename>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:418
+#: C/index.docbook:424
#, no-wrap
msgid ""
"\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
#. (itstool) path: example/title
-#: C/index.docbook:430
+#: C/index.docbook:436
msgid "Keep gtk-doc optional"
msgstr "Mantener gtk-doc como opcional"
#. (itstool) path: example/programlisting
-#: C/index.docbook:431
+#: C/index.docbook:437
#, no-wrap
msgid ""
"\n"
"])\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:425
+#: C/index.docbook:431
msgid ""
"This will require all developers to have gtk-doc installed. If it is okay "
"for your project to have optional api-doc build setup, you can solve this as "
"<_:example-1/>"
#. (itstool) path: sect1/para
-#: C/index.docbook:442
+#: C/index.docbook:448
msgid ""
"The first argument is used to check for the gtkdocversion at configure time. "
"The 2nd, optional argument is used by <application>gtkdocize</application>. "
"symbol> también añade diversas opciones de configuración:"
#. (itstool) path: listitem/para
-#: C/index.docbook:448
+#: C/index.docbook:454
msgid "--with-html-dir=PATH : path to installed docs"
msgstr "--with-html-dir=RUTA: ruta a los documentos instalados"
#. (itstool) path: listitem/para
-#: C/index.docbook:449
+#: C/index.docbook:455
msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]"
msgstr ""
"--enable-gtk-doc: usar gtk-doc para construir la documentación "
"[predeterminado=no]"
#. (itstool) path: listitem/para
-#: C/index.docbook:450
+#: C/index.docbook:456
msgid ""
"--enable-gtk-doc-html : build documentation in html format [default=yes]"
msgstr ""
"[predeterminado=sí]"
#. (itstool) path: listitem/para
-#: C/index.docbook:451
+#: C/index.docbook:457
msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
msgstr ""
"--enable-gtk-doc: usar gtk-doc para construir la documentación "
"[predeterminado=no]"
#. (itstool) path: important/para
-#: C/index.docbook:455
+#: C/index.docbook:461
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"desarrolladores)."
#. (itstool) path: sect1/para
-#: C/index.docbook:463
+#: C/index.docbook:469
msgid ""
"Furthermore it is recommended that you have the following line inside your "
"<filename>configure.ac</filename> script. This allows "
"<function>GTK_DOC_CHECK</function> a su proyecto."
#. (itstool) path: example/title
-#: C/index.docbook:471
+#: C/index.docbook:477
msgid "Preparation for gtkdocize"
msgstr "Preparación para gtkdocize"
#. (itstool) path: example/programlisting
-#: C/index.docbook:472
+#: C/index.docbook:478
#, no-wrap
msgid ""
"\n"
"AC_CONFIG_MACRO_DIR(m4)\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:477
+#: C/index.docbook:483
msgid ""
"After all changes to <filename>configure.ac</filename> are made, update the "
"<filename>configure</filename> file. This can be done by re-running "
"volviendo a ejecutar <code>autoreconf -i</code> o <code>autogen.sh</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:485
+#: C/index.docbook:491
msgid "Integration with automake"
msgstr "Integración con automake"
#. (itstool) path: sect1/para
-#: C/index.docbook:487
+#: C/index.docbook:493
msgid ""
"First copy the <filename>Makefile.am</filename> from the <filename class="
"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
"repítalo para cada uno de ellos."
#. (itstool) path: sect1/para
-#: C/index.docbook:498
+#: C/index.docbook:504
msgid ""
"The next step is to edit the settings inside the <filename>Makefile.am</"
"filename>. All the settings have a comment above that describes their "
"soportan <option>--help</option> para listar los parámetros que soportan."
#. (itstool) path: sect1/title
-#: C/index.docbook:512
+#: C/index.docbook:518
msgid "Integration with autogen"
msgstr "Integración con autogen"
#. (itstool) path: sect1/para
-#: C/index.docbook:514
+#: C/index.docbook:520
msgid ""
"Most projects will have an <filename>autogen.sh</filename> script to setup "
"the build infrastructure after a checkout from version control system (such "
"automake o autoconf."
#. (itstool) path: example/title
-#: C/index.docbook:523
+#: C/index.docbook:529
msgid "Running gtkdocize from autogen.sh"
msgstr "Ejecutar gtkdocize desde autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:524
+#: C/index.docbook:530
#, no-wrap
msgid ""
"\n"
"gtkdocize || exit 1\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:530
+#: C/index.docbook:536
msgid ""
"When running <application>gtkdocize</application> it copies <filename>gtk-"
"doc.make</filename> to your project root (or any directory specified by the "
"<application>gtkdocize</application>."
#. (itstool) path: sect1/para
-#: C/index.docbook:539
+#: C/index.docbook:545
msgid ""
"Historically GTK-Doc was generating template files where developers entered "
"the docs. This turned out to be not so good (e.g. the need for having "
#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:556 C/index.docbook:573
+#: C/index.docbook:562 C/index.docbook:579
msgid "Running the doc build"
msgstr "Ejecutar la construcción de la documentación"
#. (itstool) path: sect1/para
-#: C/index.docbook:558
+#: C/index.docbook:564
msgid ""
"After the previous steps it's time to run the build. First we need to rerun "
"<filename>autogen.sh</filename>. If this script runs configure for you, then "
"<filename>configure</filename> con esta opción."
#. (itstool) path: sect1/para
-#: C/index.docbook:565
+#: C/index.docbook:571
msgid ""
"The first make run generates several additional files in the doc-"
"directories. The important ones are: <filename><package>.types</"
"pasado), <filename><paquete>-sections.txt</filename>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:574
+#: C/index.docbook:580
#, no-wrap
msgid ""
"\n"
"make\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:580
+#: C/index.docbook:586
msgid ""
"Now you can point your browser to <filename>docs/reference/<package>/"
"index.html</filename>. Yes, it's a bit disappointing still. But hang-on, "
"información."
#. (itstool) path: sect1/title
-#: C/index.docbook:588
+#: C/index.docbook:594
msgid "Integration with version control systems"
msgstr "Integración con los sistemas de control de versiones"
#. (itstool) path: sect1/para
-#: C/index.docbook:590
+#: C/index.docbook:596
msgid ""
"As a rule of thumb, it's the files you edit which should go under version "
"control. For typical projects it's these files: <filename><package>."
"txt</filename>, <filename>Makefile.am</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:598
+#: C/index.docbook:604
msgid ""
"Files in the <filename>xml/</filename> and <filename>html/</filename> "
"directories should not go under version control. Neither should any of the "
"los archivos <filename>.stamp</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:606
+#: C/index.docbook:612
msgid "Integration with plain makefiles or other build systems"
msgstr "Integración con makefiles u otros sistemas de construcción"
#. (itstool) path: sect1/para
-#: C/index.docbook:608
+#: C/index.docbook:614
msgid ""
"In the case one does not want to use automake and therefore <filename>gtk-"
"doc.mak</filename> one will need to call the gtkdoc tools in the right order "
"makefiles propios (o en otras herramientas de construcción)."
#. (itstool) path: example/title
-#: C/index.docbook:615
+#: C/index.docbook:621
msgid "Documentation build steps"
msgstr "Pasos de construcción de la documentación"
#. (itstool) path: example/programlisting
-#: C/index.docbook:616
+#: C/index.docbook:622
#, no-wrap
msgid ""
"\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:630
+#: C/index.docbook:636
msgid ""
"One will need to look at the <filename>Makefile.am</filename> and "
"<filename>gtk-doc.mak</filename> to pick the extra options needed."
"doc.mak</filename> para elegir las opciones adicionales necesarias."
#. (itstool) path: sect1/title
-#: C/index.docbook:637
+#: C/index.docbook:643
msgid "Integration with CMake build systems"
msgstr "Integración con sistemas de construcción CMake"
#. (itstool) path: sect1/para
-#: C/index.docbook:639
+#: C/index.docbook:645
msgid ""
"GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module (and "
"the corresponding <filename>GtkDocConfigVersion.cmake</filename> module). "
"filename>."
#. (itstool) path: example/title
-#: C/index.docbook:649
+#: C/index.docbook:655
msgid "Example of using GTK-Doc from CMake"
msgstr "Ejeplo de uso de GTK-Doc desde CMake"
#. (itstool) path: example/programlisting
-#: C/index.docbook:650
+#: C/index.docbook:656
#, no-wrap
msgid ""
"\n"
" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:647
+#: C/index.docbook:653
msgid "The following example shows how to use this command. <_:example-1/>"
msgstr "El siguiente ejemplo muestra cómo usar este comando. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:675
+#: C/index.docbook:681
msgid "Documenting the code"
msgstr "Documentar el código"
#. (itstool) path: chapter/para
-#: C/index.docbook:677
+#: C/index.docbook:683
msgid ""
"GTK-Doc uses source code comment with a special syntax for code "
"documentation. Further it retrieves information about your project structure "
"acerca de la sintaxis de los comentarios."
#. (itstool) path: note/title
-#: C/index.docbook:685
+#: C/index.docbook:691
msgid "Documentation placement"
msgstr "Ubicación de la documentación"
#. (itstool) path: note/para
-#: C/index.docbook:686
+#: C/index.docbook:692
msgid ""
"In the past most documentation had to be filled into files residing inside "
"the <filename>tmpl</filename> directory. This has the disadvantages that the "
"conflictos con los sistemas de control de versiones."
#. (itstool) path: note/para
-#: C/index.docbook:692
+#: C/index.docbook:698
msgid ""
"The avoid the aforementioned problems we suggest putting the documentation "
"inside the sources. This manual will only describe this way of documenting "
"documentar el código."
#. (itstool) path: example/title
-#: C/index.docbook:703 C/index.docbook:729
+#: C/index.docbook:709 C/index.docbook:735
msgid "GTK-Doc comment block"
msgstr "Bloque de comentario de GTK-Doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:704
+#: C/index.docbook:710
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:699
+#: C/index.docbook:705
msgid ""
"The scanner can handle the majority of C headers fine. In the case of "
"receiving warnings from the scanner that look like a special case, one can "
"GTK-Doc que los omita. <_:example-1/>"
#. (itstool) path: note/title
-#: C/index.docbook:713
+#: C/index.docbook:719
msgid "Limitations"
msgstr "Limitaciones"
#. (itstool) path: note/para
-#: C/index.docbook:714
+#: C/index.docbook:720
msgid ""
"Note, that GTK-Doc's supports <code>#ifndef(__GTK_DOC_IGNORE__)</code> but "
"not <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations."
"pero <code>#if !defined(__GTK_DOC_IGNORE__)</code> u otras combinaciones."
#. (itstool) path: sect1/title
-#: C/index.docbook:724
+#: C/index.docbook:730
msgid "Documentation comments"
msgstr "Comentarios de la documentación"
#. (itstool) path: example/programlisting
-#: C/index.docbook:730
+#: C/index.docbook:736
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:726
+#: C/index.docbook:732
msgid ""
"A multiline comment that starts with an additional '*' marks a documentation "
"block that will be processed by the GTK-Doc tools. <_:example-1/>"
"bloque de documentación que GTK-Doc tools procesarán. <_:example-1/>"
#. (itstool) path: sect1/para
-#: C/index.docbook:739
+#: C/index.docbook:745
msgid ""
"The 'identifier' is one line with the name of the item the comment is "
"related to. The syntax differs a little depending on the item. (TODO add "
"hacer: añadir una tabla mostrando los identificadores)"
#. (itstool) path: sect1/para
-#: C/index.docbook:745
+#: C/index.docbook:751
msgid ""
"The 'documentation' block is also different for each symbol type. Symbol "
"types that get parameters such as functions or macros have the parameter "
"espacio). Esto es útil para texto preformateado (listados de código)."
#. (itstool) path: listitem/para
-#: C/index.docbook:762
+#: C/index.docbook:768
msgid ""
"What it is: The name for a class or function can sometimes be misleading for "
"people coming from a different background."
"personas que provengan de otros entornos."
#. (itstool) path: listitem/para
-#: C/index.docbook:768
+#: C/index.docbook:774
msgid ""
"What it does: Tell about common uses. Put it in relation with the other API."
msgstr "Qué hace: indique los usos comunes, en relación con las otras API."
#. (itstool) path: tip/para
-#: C/index.docbook:758
+#: C/index.docbook:764
msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>"
msgstr "Al documentar código, describa dos aspectos: <_:itemizedlist-1/>"
#. (itstool) path: listitem/para
-#: C/index.docbook:783
+#: C/index.docbook:789
msgid "Use function() to refer to functions or macros which take arguments."
msgstr ""
"Use función() para referirse a funciones o macros que toman argumentos."
#. (itstool) path: listitem/para
-#: C/index.docbook:788
+#: C/index.docbook:794
msgid ""
"Use @param to refer to parameters. Also use this when referring to "
"parameters of other functions, related to the one being described."
"parámetros de otras funciones, relacionados al que se describe."
#. (itstool) path: listitem/para
-#: C/index.docbook:794
+#: C/index.docbook:800
msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS."
msgstr "Use %constant para referirse a una constante, ej: %G_TRAVERSE_LEAFS."
#. (itstool) path: listitem/para
-#: C/index.docbook:799
+#: C/index.docbook:805
msgid ""
"Use #symbol to refer to other types of symbol, e.g. structs and enums and "
"macros which don't take arguments."
"estructuras, enumeraciones y macros que no toman argumentos."
#. (itstool) path: listitem/para
-#: C/index.docbook:805
+#: C/index.docbook:811
msgid "Use #Object::signal to refer to a GObject signal."
msgstr "Use #Object::signal para referirse a una señal de GObject."
#. (itstool) path: listitem/para
-#: C/index.docbook:810
+#: C/index.docbook:816
msgid "Use #Object:property to refer to a GObject property."
msgstr "Use #Object:property para referirse a una propiedad de GObject."
#. (itstool) path: listitem/para
-#: C/index.docbook:815
+#: C/index.docbook:821
msgid ""
"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
"foo_bar() to refer to a vmethod."
"#GObjectClass.foo_bar() para referirse a un vmethod."
#. (itstool) path: sect1/para
-#: C/index.docbook:777
+#: C/index.docbook:783
msgid ""
"One advantage of hyper-text over plain-text is the ability to have links in "
"the document. Writing the correct markup for a link can be tedious though. "
"itemizedlist-1/>"
#. (itstool) path: tip/para
-#: C/index.docbook:824
+#: C/index.docbook:830
msgid ""
"If you need to use the special characters '<', '>', '()', '@', '%', or "
"'#' in your documentation without GTK-Doc changing them you can use the XML "
"doble «\\»."
#. (itstool) path: sect1/para
-#: C/index.docbook:833
+#: C/index.docbook:839
msgid ""
"DocBook can do more than just links. One can also have lists, examples, "
"headings, and images. As of version 1.20, the preferred way is to use a "
"elementos de una lista aparecerán como líneas que empiezan con un guión."
#. (itstool) path: sect1/para
-#: C/index.docbook:844
+#: C/index.docbook:850
msgid ""
"While markdown is now preferred one can mix both. One limitation here is "
"that one can use docbook xml within markdown, but markdown within docbook "
"xml no está soportado."
#. (itstool) path: sect1/para
-#: C/index.docbook:850
+#: C/index.docbook:856
msgid ""
"In older GTK-Doc releases, if you need support for additional formatting, "
"you would need to enable the usage of docbook XML tags inside doc-comments "
"<filename>Makefile.am</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:859
+#: C/index.docbook:865
msgid "GTK-Doc comment block using Markdown"
msgstr "Bloque de comentario de GTK-Doc usando marcado"
#. (itstool) path: example/programlisting
-#: C/index.docbook:860
+#: C/index.docbook:866
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:899
+#: C/index.docbook:905
msgid ""
"More examples of what markdown tags are supported can be found in the <ulink "
"url=\"https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown"
"GTK+</ulink>."
#. (itstool) path: tip/para
-#: C/index.docbook:905
+#: C/index.docbook:911
msgid ""
"As already mentioned earlier GTK-Doc is for documenting public API. Thus one "
"cannot write documentation for static symbols. Nevertheless it is good to "
"secciones."
#. (itstool) path: sect1/title
-#: C/index.docbook:919
+#: C/index.docbook:925
msgid "Documenting sections"
msgstr "Documentar secciones"
#. (itstool) path: sect1/para
-#: C/index.docbook:921
+#: C/index.docbook:927
msgid ""
"Each section of the documentation contains information about one class or "
"module. To introduce the component one can write a section block. The short "
"los campos @ son opcionales."
#. (itstool) path: example/title
-#: C/index.docbook:929
+#: C/index.docbook:935
msgid "Section comment block"
msgstr "Bloque de comentarios en una sección"
#. (itstool) path: example/programlisting
-#: C/index.docbook:930
+#: C/index.docbook:936
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:949
+#: C/index.docbook:955
msgid "SECTION:<name>"
msgstr "SECCIÓN <nombre>"
#. (itstool) path: listitem/para
-#: C/index.docbook:951
+#: C/index.docbook:957
msgid ""
"The name links the section documentation to the respective part in the "
"<filename><package>-sections.txt</filename> file. The name given here "
"archivo <filename><paquete>-sections.txt</filename>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:960
+#: C/index.docbook:966
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:962
+#: C/index.docbook:968
msgid ""
"A one line description of the section, that later will appear after the "
"links in the TOC and at the top of the section page."
"TOC y en la página de la sección."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:969
+#: C/index.docbook:975
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:971
+#: C/index.docbook:977
msgid ""
"The section title defaults to <name> from the SECTION declaration. It "
"can be overridden with the @title field."
"declaración SECTION. Se puede sobrescribir con el campo @title."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:978
+#: C/index.docbook:984
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:980
+#: C/index.docbook:986
msgid ""
"Overrides the use of title as a section identifier. For GObjects the <"
"title> is used as a section_id and for other sections it is <"
"para otra sección es <MÓDULO>-<title>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:988
+#: C/index.docbook:994
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:990
+#: C/index.docbook:996
msgid "A list of symbols that are related to this section."
msgstr "Una lista de símbolos relacionados con esta sección."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:996
+#: C/index.docbook:1002
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1003
+#: C/index.docbook:1009
msgid ""
"Stable - The intention of a Stable interface is to enable arbitrary third "
"parties to develop applications to these interfaces, release them, and have "
"de haberlos habrá buenas razones para ello."
#. (itstool) path: listitem/para
-#: C/index.docbook:1015
+#: C/index.docbook:1021
msgid ""
"Unstable - Unstable interfaces are experimental or transitional. They are "
"typically used to give outside developers early access to new or rapidly "
"publicación menor a la siguiente."
#. (itstool) path: listitem/para
-#: C/index.docbook:1027
+#: C/index.docbook:1033
msgid ""
"Private - An interface that can be used within the GNOME stack itself, but "
"that is not documented for end-users. Such functions should only be used in "
"deberían usar de formas especificadas y documentadas."
#. (itstool) path: listitem/para
-#: C/index.docbook:1036
+#: C/index.docbook:1042
msgid ""
"Internal - An interface that is internal to a module and does not require "
"end-user documentation. Functions that are undocumented are assumed to be "
"son internas."
#. (itstool) path: listitem/para
-#: C/index.docbook:998
+#: C/index.docbook:1004
msgid ""
"An informal description of the stability level this API has. We recommend "
"the use of one of these terms: <_:itemizedlist-1/>"
"recomienda el uso de uno de estos términos: <_:itemizedlist-1/>"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1048
+#: C/index.docbook:1054
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1050
+#: C/index.docbook:1056
msgid ""
"The <literal>#include</literal> files to show in the section synopsis (a "
"comma separated list), overriding the global value from the <link linkend="
"línea de comandos. Este elemento es opcional."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1059
+#: C/index.docbook:1065
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1061
+#: C/index.docbook:1067
msgid ""
"The image to display at the top of the reference page for this section. This "
"will often be some sort of a diagram to illustrate the visual appearance of "
"Este elemento es opcional."
#. (itstool) path: tip/para
-#: C/index.docbook:1072
+#: C/index.docbook:1078
msgid ""
"To avoid unnecessary recompilation after doc-changes put the section docs "
"into the c-source where possible."
"sea posible."
#. (itstool) path: sect1/title
-#: C/index.docbook:1081
+#: C/index.docbook:1087
msgid "Documenting symbols"
msgstr "Documentar símbolos"
#. (itstool) path: sect1/para
-#: C/index.docbook:1083
+#: C/index.docbook:1089
msgid ""
"Each symbol (function, macro, struct, enum, signal and property) is "
"documented in a separate block. The block is best placed close to the "
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1091 C/index.docbook:1157
+#: C/index.docbook:1097 C/index.docbook:1163
msgid "General tags"
msgstr "Etiquetas generales"
#. (itstool) path: sect2/para
-#: C/index.docbook:1093
+#: C/index.docbook:1099
msgid ""
"You can add versioning information to all documentation elements to tell "
"when an API was introduced, or when it was deprecated."
"obsoleta."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1098
+#: C/index.docbook:1104
msgid "Versioning Tags"
msgstr "Versionado de etiquetas"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1099
+#: C/index.docbook:1105
msgid "Since:"
msgstr "Desde:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1101
+#: C/index.docbook:1107
msgid "Description since which version of the code the API is available."
msgstr "Descripción desde qué versión del código está disponible la API."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1106
+#: C/index.docbook:1112
msgid "Deprecated:"
msgstr "Obsoleto:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1108
+#: C/index.docbook:1114
msgid ""
"Paragraph denoting that this function should no be used anymore. The "
"description should point the reader to the new API."
"debería informar al lector de la nueva API."
#. (itstool) path: sect2/para
-#: C/index.docbook:1116
+#: C/index.docbook:1122
msgid ""
"You can also add stability information to all documentation elements to "
"indicate whether API stability is guaranteed for them for all future minor "
"todas las versiones menores futuras del proyecto."
#. (itstool) path: sect2/para
-#: C/index.docbook:1122
+#: C/index.docbook:1128
msgid ""
"The default stability level for all documentation elements can be set by "
"passing the <option>--default-stability</option> argument to "
"siguientes valores."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1128
+#: C/index.docbook:1134
msgid "Stability Tags"
msgstr "Etiquetas de estabilidad"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1129
+#: C/index.docbook:1135
msgid "Stability: Stable"
msgstr "Estabilidad: estable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1131
+#: C/index.docbook:1137
msgid ""
"Mark the element as stable. This is for public APIs which are guaranteed to "
"remain stable for all future minor releases of the project."
"proyecto."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1138
+#: C/index.docbook:1144
msgid "Stability: Unstable"
msgstr "Estabilidad: inestable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1140
+#: C/index.docbook:1146
msgid ""
"Mark the element as unstable. This is for public APIs which are released as "
"a preview before being stabilised."
"publican como versión previa antes de estabilizarse."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1146
+#: C/index.docbook:1152
msgid "Stability: Private"
msgstr "Estabilidad: privado"
#. (itstool) path: listitem/para
-#: C/index.docbook:1148
+#: C/index.docbook:1154
msgid ""
"Mark the element as private. This is for interfaces which can be used by "
"tightly coupled modules, but not by arbitrary third parties."
"en módulos fuertemente acoplados, pero no en terceras partes aleatorias."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1158
+#: C/index.docbook:1164
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1178 C/index.docbook:1188
+#: C/index.docbook:1184 C/index.docbook:1194
msgid "Annotations"
msgstr "Anotaciones"
#. (itstool) path: sect2/para
-#: C/index.docbook:1180
+#: C/index.docbook:1186
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"type=\"http\">el wiki</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1189
+#: C/index.docbook:1195
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1210 C/index.docbook:1239
+#: C/index.docbook:1216 C/index.docbook:1245
msgid "Function comment block"
msgstr "Bloque de comentario de función"
#. (itstool) path: listitem/para
-#: C/index.docbook:1216
+#: C/index.docbook:1222
msgid ""
"Document whether returned objects, lists, strings, etc, should be freed/"
"unrefed/released."
"debería liberarse/desreferenciarse/etc."
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1228
msgid "Document whether parameters can be NULL, and what happens if they are."
msgstr ""
"El documento, dependiendo de si sus parámetros pueden ser nulos, y qué "
"sucede si lo son."
#. (itstool) path: listitem/para
-#: C/index.docbook:1227
+#: C/index.docbook:1233
msgid ""
"Mention interesting pre-conditions and post-conditions where appropriate."
msgstr ""
"Mencionar precondiciones y postcondiciones interesantes donde sea apropiado."
#. (itstool) path: sect2/para
-#: C/index.docbook:1212 C/index.docbook:1298
+#: C/index.docbook:1218 C/index.docbook:1304
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Recuerde: <_:itemizedlist-1/>"
#. (itstool) path: sect2/para
-#: C/index.docbook:1234
+#: C/index.docbook:1240
msgid ""
"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
"private. They are treated like static functions."
"«_» son privados. Se tratan como funciones estáticas."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1240
+#: C/index.docbook:1246
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1261
+#: C/index.docbook:1267
msgid "Function tags"
msgstr "Etiquetas de funciones"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1262 C/index.docbook:1469
+#: C/index.docbook:1268 C/index.docbook:1475
msgid "Returns:"
msgstr "Devuelve:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1264
+#: C/index.docbook:1270
msgid "Paragraph describing the returned result."
msgstr "Párrafo que describe el resultado devuelto."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1269
+#: C/index.docbook:1275
msgid "@...:"
msgstr "@...:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1271
+#: C/index.docbook:1277
msgid ""
"In case the function has variadic arguments, you should use this tag "
"(@Varargs: does also work for historic reasons)."
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1281 C/index.docbook:1283
+#: C/index.docbook:1287 C/index.docbook:1289
msgid "Property comment block"
msgstr "Bloque de comentario de propiedad"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1284
+#: C/index.docbook:1290
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1296 C/index.docbook:1315
+#: C/index.docbook:1302 C/index.docbook:1321
msgid "Signal comment block"
msgstr "Bloque de comentario de señal"
#. (itstool) path: listitem/para
-#: C/index.docbook:1302
+#: C/index.docbook:1308
msgid ""
"Document when the signal is emitted and whether it is emitted before or "
"after other signals."
"otras señales."
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1314
msgid "Document what an application might do in the signal handler."
msgstr "Documentar qué aplicación debe gestionar las señales."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1316
+#: C/index.docbook:1322
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1333 C/index.docbook:1334
+#: C/index.docbook:1339 C/index.docbook:1340
msgid "Struct comment block"
msgstr "Bloque de comentario de estructura"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1335
+#: C/index.docbook:1341
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1350
+#: C/index.docbook:1356
msgid ""
"Use <code>/*< private >*/</code> before the private struct fields you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"revertir el comportamiento anterior."
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1362
msgid ""
"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" "
"it will be considered private automatically and doesn't need to be mentioned "
"bloque de comentario."
#. (itstool) path: sect2/para
-#: C/index.docbook:1362
+#: C/index.docbook:1368
msgid ""
"Struct comment blocks can also be used for GObjects and GObjectClasses. It "
"is usually a good idea to add a comment block for a class, if it has "
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1374 C/index.docbook:1375
+#: C/index.docbook:1380 C/index.docbook:1381
msgid "Enum comment block"
msgstr "Enumerar bloques de comentarios"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1376
+#: C/index.docbook:1382
#, no-wrap
msgid ""
"\n"
"} Something;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1393
+#: C/index.docbook:1399
msgid ""
"Use <code>/*< private >*/</code> before the private enum values you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"comportamiento anterior."
#. (itstool) path: sect1/title
-#: C/index.docbook:1404
+#: C/index.docbook:1410
msgid "Inline program documentation"
msgstr "Documentación en línea del programa"
#. (itstool) path: sect1/para
-#: C/index.docbook:1405
+#: C/index.docbook:1411
msgid ""
"You can document programs and their commandline interface using inline "
"documentation."
"documentación en línea."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1411
+#: C/index.docbook:1417
msgid "Tags"
msgstr "Etiquetas"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1413
+#: C/index.docbook:1419
msgid "PROGRAM"
msgstr "PROGRAM"
#. (itstool) path: listitem/para
-#: C/index.docbook:1416
+#: C/index.docbook:1422
msgid "Defines the start of a program documentation."
msgstr "Define el inicio de la documentación de un programa."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1423
+#: C/index.docbook:1429
msgid "@short_description:"
msgstr "@short_description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1425
+#: C/index.docbook:1431
msgid "Defines a short description of the program. (Optional)"
msgstr "Define una descripción corta del programa. (Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1432
+#: C/index.docbook:1438
msgid "@synopsis:"
msgstr "@synopsis:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1434
+#: C/index.docbook:1440
msgid ""
"Defines the arguments, or list of arguments that the program can take. "
"(Optional)"
"(Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1442
+#: C/index.docbook:1448
msgid "@see_also:"
msgstr "@see_also:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1444
+#: C/index.docbook:1450
msgid "See Also manual page section. (Optional)"
msgstr "Página del manual Ver también. (Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1451
+#: C/index.docbook:1457
msgid "@arg:"
msgstr "@arg:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1453
+#: C/index.docbook:1459
msgid "Argument(s) passed to the program and their description. (Optional)"
msgstr "Argumentos pasados al programa y su descripción. (Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1460
+#: C/index.docbook:1466
msgid "Description:"
msgstr "Description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1462
+#: C/index.docbook:1468
msgid "A longer description of the program."
msgstr "Una descripción más larga del programa."
#. (itstool) path: listitem/para
-#: C/index.docbook:1471
+#: C/index.docbook:1477
msgid "Specificy what value(s) the program returns. (Optional)"
msgstr "Especifique qué valores devuelve el programa. (Opcional)"
#. (itstool) path: sect2/title
-#: C/index.docbook:1480
+#: C/index.docbook:1486
msgid "Example of program documentation."
msgstr "Ejemplo de documentación de un programa."
#. (itstool) path: example/title
-#: C/index.docbook:1481
+#: C/index.docbook:1487
msgid "Program documentation block"
msgstr "Bloque de documentación del programa"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1482
+#: C/index.docbook:1488
#, no-wrap
msgid ""
"\n"
"}\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1508
+#: C/index.docbook:1514
msgid "Useful DocBook tags"
msgstr "Etiquetas DocBook útiles"
#. (itstool) path: sect1/para
-#: C/index.docbook:1510
+#: C/index.docbook:1516
msgid ""
"Here are some DocBook tags which are most useful when documenting the code."
msgstr ""
"Aquí están varias etiquetas de DocBook muy útiles al documentar código."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1519
+#: C/index.docbook:1525
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1515
+#: C/index.docbook:1521
msgid ""
"To link to another section in the GTK docs: <_:informalexample-1/> The "
"linkend is the SGML/XML id on the top item of the page you want to link to. "
"ajustarse a SGML/XML."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1532
+#: C/index.docbook:1538
#, no-wrap
msgid ""
"\n"
"<function>...</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1529
+#: C/index.docbook:1535
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
"informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1541
+#: C/index.docbook:1547
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1552
+#: C/index.docbook:1558
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1538
+#: C/index.docbook:1544
msgid ""
"To include example code: <_:informalexample-1/> or possibly this, for very "
"short code fragments which don't need a title: <_:informalexample-2/> For "
"informalexample-2/>. El último GTK-Doc también soporta abreviación: |[ ... ]|"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1571
+#: C/index.docbook:1577
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1568
+#: C/index.docbook:1574
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Para incluir listas de topos: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1591
+#: C/index.docbook:1597
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1588
+#: C/index.docbook:1594
msgid ""
"To include a note which stands out from the text: <_:informalexample-1/>"
msgstr "Para incluir una nota que sobresale del texto: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1604
+#: C/index.docbook:1610
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1601
+#: C/index.docbook:1607
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "Para referirse a un tipo: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1613
+#: C/index.docbook:1619
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1610
+#: C/index.docbook:1616
msgid ""
"To refer to an external structure (not one described in the GTK docs): <_:"
"informalexample-1/>"
"de GTK): <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1622
+#: C/index.docbook:1628
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1619
+#: C/index.docbook:1625
msgid "To refer to a field of a structure: <_:informalexample-1/>"
msgstr "Para referirse a un campo o a una estructura: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1631
+#: C/index.docbook:1637
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1628
+#: C/index.docbook:1634
msgid ""
"To refer to a class name, we could possibly use: <_:informalexample-1/> but "
"you'll probably be using #GtkWidget instead (to automatically create a link "
"\"documenting_syntax\">abreviaciones</link>)."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1642
+#: C/index.docbook:1648
#, no-wrap
msgid ""
"\n"
"<emphasis>This is important</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1639
+#: C/index.docbook:1645
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Para enfatizar un texto: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1651
+#: C/index.docbook:1657
#, no-wrap
msgid ""
"\n"
"<filename>/home/user/documents</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1648
+#: C/index.docbook:1654
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Para uso de nombres de archivo: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1660
+#: C/index.docbook:1666
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1657
+#: C/index.docbook:1663
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "Para referirse a claves: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1670
+#: C/index.docbook:1676
msgid "Filling the extra files"
msgstr "Rellenar campos adicionales"
#. (itstool) path: chapter/para
-#: C/index.docbook:1672
+#: C/index.docbook:1678
msgid ""
"There are a couple of extra files, that need to be maintained along with the "
"inline source code comments: <filename><package>.types</filename>, "
"pasado) y <filename><paquete>-sections.txt</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1681
+#: C/index.docbook:1687
msgid "Editing the types file"
msgstr "Editar los tipos de archivo"
#. (itstool) path: sect1/para
-#: C/index.docbook:1683
+#: C/index.docbook:1689
msgid ""
"If your library or application includes GObjects, you want their signals, "
"arguments/parameters and position in the hierarchy to be shown in the "
"<filename><paquete>.types</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:1692
+#: C/index.docbook:1698
msgid "Example types file snippet"
msgstr "Fragmento de ejemplo de tipos de archivo"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1693
+#: C/index.docbook:1699
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1704
+#: C/index.docbook:1710
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"los tipos de archivo ni tenerlos bajo el control de versiones."
#. (itstool) path: sect1/title
-#: C/index.docbook:1713
+#: C/index.docbook:1719
msgid "Editing the master document"
msgstr "Editar la sección maestra del documento"
#. (itstool) path: sect1/para
-#: C/index.docbook:1715
+#: C/index.docbook:1721
msgid ""
"GTK-Doc produces documentation in DocBook SGML/XML. When processing the "
"inline source comments, the GTK-Doc tools generate one documentation page "
"documento maestro las incluye y ordena."
#. (itstool) path: sect1/para
-#: C/index.docbook:1722
+#: C/index.docbook:1728
msgid ""
"While GTK-Doc creates a template master document for you, later runs will "
"not touch it again. This means that one can freely structure the "
"vez en cuando para ver si se han introducido algunas mejoras."
#. (itstool) path: tip/para
-#: C/index.docbook:1732
+#: C/index.docbook:1738
msgid ""
"Do not create tutorials as extra documents. Just write extra chapters. The "
"benefit of directly embedding the tutorial for your library into the API "
"el tutorial junto con la biblioteca son mayores."
#. (itstool) path: sect1/para
-#: C/index.docbook:1741
+#: C/index.docbook:1747
msgid ""
"So what are the things to change inside the master document? For a start is "
"only a little. There are some placeholders (text in square brackets) there "
"que habría que encargarse."
#. (itstool) path: example/title
-#: C/index.docbook:1748
+#: C/index.docbook:1754
msgid "Master document header"
msgstr "Cabecera del documento maestro"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1749
+#: C/index.docbook:1755
#, no-wrap
msgid ""
"\n"
" <title>[Insert title here]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1765
+#: C/index.docbook:1771
msgid ""
"In addition a few option elements are created in commented form. You can "
"review these and enable them as you like."
"Puede revisarlos y activarlos como quiera."
#. (itstool) path: example/title
-#: C/index.docbook:1771
+#: C/index.docbook:1777
msgid "Optional part in the master document"
msgstr "Parte opcional en el documento maestro"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1772
+#: C/index.docbook:1778
#, no-wrap
msgid ""
"\n"
" --> \n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1780
+#: C/index.docbook:1786
msgid ""
"Finally you need to add new section whenever you introduce one. The <link "
"linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> tool will remind "
"todavía en la documentación."
#. (itstool) path: example/title
-#: C/index.docbook:1788 C/index.docbook:1823
+#: C/index.docbook:1794 C/index.docbook:1829
msgid "Including generated sections"
msgstr "Incluir secciones generadas"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1789
+#: C/index.docbook:1795
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1801
+#: C/index.docbook:1807
msgid "Editing the section file"
msgstr "Editar el archivo de sección"
#. (itstool) path: sect1/para
-#: C/index.docbook:1803
+#: C/index.docbook:1809
msgid ""
"The section file is used to organise the documentation output by GTK-Doc. "
"Here one specifies which symbol belongs to which module or class and control "
"y el control de la visibilidad (pública o privada)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1809
+#: C/index.docbook:1815
msgid ""
"The section file is a plain text file with tags delimiting sections. Blank "
"lines are ignored and lines starting with a '#' are treated as comment lines."
"comiencen con «#» se tratan como comentarios."
#. (itstool) path: note/para
-#: C/index.docbook:1816
+#: C/index.docbook:1822
msgid ""
"While the tags make the file look like xml, it is not. Please do not close "
"tags like <SUBSECTION>."
"etiquetas del tipo <SUBSECTION>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1824
+#: C/index.docbook:1830
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1841
+#: C/index.docbook:1847
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"clase de GObject convertido a minúscula.)"
#. (itstool) path: sect1/para
-#: C/index.docbook:1853
+#: C/index.docbook:1859
msgid ""
"The <TITLE> ... </TITLE> tag is used to specify the title of the "
"section. It is only useful before the templates (if used) are initially "
"obsoleto."
#. (itstool) path: sect1/para
-#: C/index.docbook:1860
+#: C/index.docbook:1866
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"públicas (variables, vmethods)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1879
+#: C/index.docbook:1885
msgid ""
"You can also use <INCLUDE> ... </INCLUDE> to specify the "
"#include files which are shown in the synopsis sections. It contains a comma-"
"a esa sección."
#. (itstool) path: chapter/title
-#: C/index.docbook:1893
+#: C/index.docbook:1899
msgid "Controlling the result"
msgstr "Controlar el resultado"
#. (itstool) path: chapter/para
-#: C/index.docbook:1895
+#: C/index.docbook:1901
msgid ""
"A GTK-Doc run generates report files inside the documentation directory. The "
"generated files are named: <filename><package>-undocumented.txt</"
"archivos de texto plano y se pueden ver y posprocesar fácilmente."
#. (itstool) path: chapter/para
-#: C/index.docbook:1904
+#: C/index.docbook:1910
msgid ""
"The <filename><package>-undocumented.txt</filename> file starts with "
"the documentation coverage summary. Below are two sections divided by blank "
"documentación pero dónde; p.e. se ha añadido un parámetro nuevo."
#. (itstool) path: chapter/para
-#: C/index.docbook:1913
+#: C/index.docbook:1919
msgid ""
"The <filename><package>-undeclared.txt</filename> file lists symbols "
"given in the <filename><package>-sections.txt</filename> but not found "
"eliminado o no se han escrito correctamente."
#. (itstool) path: chapter/para
-#: C/index.docbook:1920
+#: C/index.docbook:1926
msgid ""
"The <filename><package>-unused.txt</filename> file lists symbol names, "
"where the GTK-Doc scanner has found documentation, but does not know where "
"todavía al archivo <filename><paquete>-sections.txt</filename>."
#. (itstool) path: tip/para
-#: C/index.docbook:1928
+#: C/index.docbook:1934
msgid ""
"Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile."
"am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during "
"de integridad durante la ejecución de make check."
#. (itstool) path: chapter/para
-#: C/index.docbook:1935
+#: C/index.docbook:1941
msgid ""
"One can also look at the files produced by the source code scanner: "
"<filename><package>-decl-list.txt</filename> and <filename><"
"si este archivo lo contiene."
#. (itstool) path: chapter/para
-#: C/index.docbook:1944
+#: C/index.docbook:1950
msgid ""
"If the project is GObject based, one can also look into the files produced "
"by the object scanner: <filename><package>.args.txt</filename>, "
"ejecutándolo como <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>."
#. (itstool) path: chapter/title
-#: C/index.docbook:1959
+#: C/index.docbook:1965
msgid "Modernizing the documentation"
msgstr "Modernizar la documentación"
#. (itstool) path: chapter/para
-#: C/index.docbook:1961
+#: C/index.docbook:1967
msgid ""
"GTK-Doc has been around for quite some time. In this section we list new "
"features together with the version since when it is available."
"características nuevas junto con la versión desde la que están disponibles."
#. (itstool) path: sect1/title
-#: C/index.docbook:1967
+#: C/index.docbook:1973
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1969
+#: C/index.docbook:1975
msgid ""
"When using xml instead of sgml, one can actually name the master document "
"<filename><package>-docs.xml</filename>."
"maestro <filename><paquete>-docs.xml</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1974
+#: C/index.docbook:1980
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-sections</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"paquete>-decl-list.txt <paquete>-sections.txt</code>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1985
+#: C/index.docbook:1991
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"<filename>configure.ac</filename> y lo tendrá hecho."
#. (itstool) path: sect1/title
-#: C/index.docbook:1997
+#: C/index.docbook:2003
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:1999
+#: C/index.docbook:2005
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"condicional."
#. (itstool) path: sect1/title
-#: C/index.docbook:2010
+#: C/index.docbook:2016
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:2016
+#: C/index.docbook:2022
msgid "Enable gtkdoc-check"
msgstr "Activar gtkdoc-check"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2017
+#: C/index.docbook:2023
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2012
+#: C/index.docbook:2018
msgid ""
"This version includes a new tool called gtkdoc-check. This tool can run a "
"set of sanity checks on your documentation. It is enabled by adding these "
"archivo <filename>Makefile.am</filename>. <_:example-1/>"
#. (itstool) path: sect1/title
-#: C/index.docbook:2030
+#: C/index.docbook:2036
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:2032
+#: C/index.docbook:2038
msgid ""
"Version 1.18 brought some initial markdown support. Using markdown in doc "
"comments is less intrusive than writing docbook xml. This version improves a "
"comentarios</link> contiene todos los detalles."
#. (itstool) path: sect1/title
-#: C/index.docbook:2042
+#: C/index.docbook:2048
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:2052
+#: C/index.docbook:2058
msgid "Use pre-generated entities"
msgstr "Usar entidades generadas previamenet"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2053
+#: C/index.docbook:2059
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2044
+#: C/index.docbook:2050
msgid ""
"The makefiles shipped with this version generate an entity file at "
"<filename>xml/gtkdocentities.ent</filename>, containing entities for e.g. "
"archivos XML generados. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:2078
+#: C/index.docbook:2084
msgid "Documenting other interfaces"
msgstr "Documentar otras interfaces"
#. (itstool) path: chapter/para
-#: C/index.docbook:2080
+#: C/index.docbook:2086
msgid ""
"So far we have been using GTK-Doc to document the API of code. The next "
"sections contain suggestions how the tools can be used to document other "
"herramientas para documentar otras interfaces."
#. (itstool) path: sect1/title
-#: C/index.docbook:2087
+#: C/index.docbook:2093
msgid "Command line options and man pages"
msgstr "Opciones de la línea de comandos y páginas man"
#. (itstool) path: sect1/para
-#: C/index.docbook:2089
+#: C/index.docbook:2095
msgid ""
"As one can generate man pages for a docbook refentry as well, it sounds like "
"a good idea to use it for that purpose. This way the interface is part of "
"interfaz es parte de la referencia y se obtienen las páginas man sin trabajo."
#. (itstool) path: sect2/title
-#: C/index.docbook:2096
+#: C/index.docbook:2102
msgid "Document the tool"
msgstr "Documentar la herramienta"
#. (itstool) path: sect2/para
-#: C/index.docbook:2098
+#: C/index.docbook:2104
msgid ""
"Create one refentry file per tool. Following <link linkend="
"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
"así como los ejemplos en, por ejemplo, glib."
#. (itstool) path: sect2/title
-#: C/index.docbook:2108
+#: C/index.docbook:2114
msgid "Adding the extra configure check"
msgstr "Añadir la comprobación de configuración adicional"
#. (itstool) path: example/title
-#: C/index.docbook:2111 C/index.docbook:2129
+#: C/index.docbook:2117 C/index.docbook:2135
msgid "Extra configure checks"
msgstr "Comprobaciones de configuración adicionales"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2112
+#: C/index.docbook:2118
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2126
+#: C/index.docbook:2132
msgid "Adding the extra makefile rules"
msgstr "Añadir reglas de makefile adicionales"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2130
+#: C/index.docbook:2136
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2152
+#: C/index.docbook:2158
msgid "DBus interfaces"
msgstr "Interfaces de DBus"
#. (itstool) path: sect1/para
-#: C/index.docbook:2154
+#: C/index.docbook:2160
msgid ""
"(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://"
"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
#. (itstool) path: chapter/title
-#: C/index.docbook:2163
+#: C/index.docbook:2169
msgid "Frequently asked questions"
msgstr "Preguntas más frecuentes"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2167
+#: C/index.docbook:2173
msgid "Question"
msgstr "Pregunta"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2168
+#: C/index.docbook:2174
msgid "Answer"
msgstr "Respuesta"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2170
+#: C/index.docbook:2176
msgid "No class hierarchy."
msgstr "Sin jerarquía de clases."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2171
+#: C/index.docbook:2177
msgid ""
"The objects <function>xxx_get_type()</function> function has not been "
"entered into the <filename><package>.types</filename> file."
"introducido en el archivo <filename><package>.types</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2177
+#: C/index.docbook:2183
msgid "Still no class hierarchy."
msgstr "Aún sin jerarquía de clases."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2178
+#: C/index.docbook:2184
msgid ""
"Missing or wrong naming in <filename><package>-sections.txt</filename> "
"file (see <ulink url=\"http://mail.gnome.org/archives/gtk-doc-list/2003-"
"doc-list/2003-October/msg00006.html\">explicación</ulink>)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2184
+#: C/index.docbook:2190
msgid "Damn, I have still no class hierarchy."
msgstr "Maldición, aún no hay una jerarquía de clases."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2185
+#: C/index.docbook:2191
msgid ""
"Is the object name (name of the instance struct, e.g. <type>GtkWidget</"
"type>) part of the normal section (don't put this into Standard or Private "
"Estándar o Privado)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2192
+#: C/index.docbook:2198
msgid "No symbol index."
msgstr "Sin índice de símbolos."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2193
+#: C/index.docbook:2199
msgid ""
"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
"index that xi:includes the generated index?"
"«xi:includes» el índice generado?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2199
+#: C/index.docbook:2205
msgid "Symbols are not linked to their doc-section."
msgstr "Los símbolos no se enlazan con su sección en el documento."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2200
+#: C/index.docbook:2206
msgid ""
"Is the doc-comment using the correct markup (added #,% or ())? Check if the "
"gtkdoc-fixxref warns about unresolvable xrefs."
"si gtk-doc-fixxref avisa de alguna referencia xref sin resolver."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2206
+#: C/index.docbook:2212
msgid "A new class does not appear in the docs."
msgstr "Una clase nueva no aparece en la documentación."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2207
+#: C/index.docbook:2213
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2213
+#: C/index.docbook:2219
msgid "A new symbol does not appear in the docs."
msgstr "Un símbolo nuevo no aparece en la documentación."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2214
+#: C/index.docbook:2220
msgid ""
"Is the doc-comment properly formatted. Check for spelling mistakes in the "
"begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable "
"txt</filename> en una subsección pública."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2222
+#: C/index.docbook:2228
msgid "A type is missing from the class hierarchy."
msgstr "Falta un tipo en la clase de jerarquías"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2223
+#: C/index.docbook:2229
msgid ""
"If the type is listed in <filename><package>.hierarchy</filename> but "
"not in <filename>xml/tree_index.sgml</filename> then double check that the "
"privada."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2232
+#: C/index.docbook:2238
msgid "I get foldoc links for all gobject annotations."
msgstr ""
"Obtengo enlaces de seguimiento de documentos para todas las anotaciones "
"gobject."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2233
+#: C/index.docbook:2239
msgid ""
"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
"from <filename><package>-docs.{xml,sgml}</filename>."
"included» desde <filename><package>-docs.{xml,sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2241
+#: C/index.docbook:2247
msgid "Parameter described in source code comment block but does not exist"
msgstr ""
"Parámetro descrito en el bloque de comentarios del código fuente pero no "
"existe"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2242
+#: C/index.docbook:2248
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
"diferentes de la fuente."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2247
+#: C/index.docbook:2253
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "múltiples «ID» para la restricción enlazada: XYZ"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2248
+#: C/index.docbook:2254
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"sections.txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2251
+#: C/index.docbook:2257
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"coincide."
#. (itstool) path: chapter/title
-#: C/index.docbook:2258
+#: C/index.docbook:2264
msgid "Tools related to gtk-doc"
msgstr "Herramientas relacionadas con GTK-Doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2260
+#: C/index.docbook:2266
msgid ""
"GtkDocPlugin - a <ulink url=\"http://trac-hacks.org/wiki/GtkDocPlugin\">Trac "
"GTK-Doc</ulink> integration plugin, that adds API docs to a trac site and "
"a un sitio «trac» y se integra con la búsqueda de «trac»."
#. (itstool) path: chapter/para
-#: C/index.docbook:2265
+#: C/index.docbook:2271
msgid ""
"Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since "
"tags in the API to determine the minimum required version."
<revhistory>
<revision>
- <revnumber>1.28</revnumber>
- <date>24 Mar 2018</date>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>bug fixes</revremark>
+ <revremark>development</revremark>
</revision>
+ <revision><revnumber>1.28</revnumber> <date>24 de marzo de 2018</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
<revision><revnumber>1.27</revnumber> <date>07 de diciembre de 2017</date> <authorinitials>ss</authorinitials> <revremark>ajustes para la migración a python</revremark></revision>
<revision><revnumber>1.26</revnumber> <date>11 de agosto de 2017</date> <authorinitials>ss</authorinitials> <revremark>portar todas las herramientas de perl/bash a python</revremark></revision>
<revision><revnumber>1.25</revnumber> <date>21 de marzo de 2016</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores, limpieza</revremark></revision>
</othercredit>
<copyright>
- <year>2009 - 2017</year>
+ <year>2009 - 2018</year>
<holder>Daniel Mustieles</holder>
</copyright>
<orderedlist>
<listitem>
- <para><guilabel>Escribir la documentación.</guilabel> El autor rellena los archivos de fuentes con la documentación para cada función, macro, unión, etc. (En el pasado la información se introducía en archivos de plantillas, lo que ya no se recomienda).</para>
+ <para>
+ <guilabel>Writing the documentation.</guilabel>
+
+ The author fills in the source files with the documentation for each
+ function, macro, structs or unions, etc.
+ </para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>Acerca de GTK-Doc</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(ARRÉGLAME)</para>
- <para>(Historia, autores, páginas web, listas de correo, licencias, planes futuros, comparación con otros sistemas similares.)</para>
+ <para>
+ (authors, web pages, mailing list, license, future plans,
+ comparison with other similar systems.)
+ </para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Configurando su proyecto</title>
+ <title>Project Setup</title>
- <para>Las siguientes secciones describen los pasos que realizar para integrar GTK-Doc en su proyecto. Estas secciones asumen que se trabaja en un proyecto llamado «meep». Este proyecto contiene una biblioteca llamada «libmeep» y una aplicación final de usuario llamada «meeper». También se asume que usará «autoconf» y «automake». En la sección <link linkend="plain_makefiles">Integración con makefiles u otros sistemas de construcción</link> se describen las necesidades básicas para trabajar con un sistema de construcción diferente.</para>
+ <para>
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
+ </para>
<sect1 id="settingup_docfiles">
<title>Configurar el esquema de la documentación</title>
- <para>Bajo su carpeta de nivel superior cree carpetas llamadas docs/reference (de esta forma también puede tener docs/help para la documentación final de usuario). Se recomienda crear otra subcarpeta con el nombre doc-package. Para paquetes con una sola biblioteca este paso no es necesario.</para>
+ <para>
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
+ </para>
- <para>Esto después aparecerá como se muestra debajo: <example><title>Ejemplo de estructura de carpetas</title>
- <programlisting>
+ <para>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
+ <programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
-</programlisting>
- </example></para>
+]]></programlisting>
+ </example>
+ </para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>Integración con autoconf</title>
-
- <para>Muy fácil, simplemente añada una línea a su script <filename>configure.ac</filename>.</para>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
+
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>Integración con autoconf</title>
- <programlisting>
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-</programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>Esto requerirá que todos los desarrolladores tengan gtk-doc instalado. Si para su proyecto es correcto tener una configuración de construcción de api-doc opcional, puede resolver esto como sigue. Manténgalo como está, ya que gtkdocize busca en <function>GTK_DOC_CHECK</function> al inicio de la línea. <example><title>Mantener gtk-doc como opcional</title>
+ <sect2 id="settingup_automake">
+ <title>Integración con automake</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </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)
-])
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
</programlisting>
- </example></para>
+ </example>
- <para>El primer argumento se usa para comprobar gtkdocversion durante la configuración. El segundo, y opcional, argumento lo usa <application>gtkdocize</application>. La macro <symbol>GTK_DOC_CHECK</symbol> también añade diversas opciones de configuración:</para>
- <orderedlist>
- <listitem><para>--with-html-dir=RUTA: ruta a los documentos instalados</para></listitem>
- <listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no]</para></listitem>
- <listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=sí]</para></listitem>
- <listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
- <important>
- <para>GTK-Doc está desactivado de forma predeterminada. Recuerde pasar la opción <option>«--enable-gtk-doc»</option> en la siguiente ejecución de <filename>configure</filename>. De otra forma, la documentación pregenerada se instala (lo que tiene sentido para usuarios, pero no para desarrolladores).</para>
- </important>
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <para>Aún más, se recomienda que tenga la siguiente línea en su script <filename>configure.ac</filename>. Esto permite que <application>gtkdocize</application> copie automáticamente la definición de la macro para <function>GTK_DOC_CHECK</function> a su proyecto.</para>
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
- <para>
- <example><title>Preparación para gtkdocize</title>
- <programlisting>
+ All the tools support <option>--help</option> to list the supported
+ options.
+ </para>
+
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>Integración con autoconf</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
-</programlisting>
- </example>
- </para>
- <para>Después de hacer los cambios en el <filename>configure.ac</filename> actualice el archivo <filename>configure</filename>. Esto se puede hacer volviendo a ejecutar <code>autoreconf -i</code> o <code>autogen.sh</code>.</para>
- </sect1>
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+]]></programlisting>
+ </example>
+ </para>
+
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
+
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>Integración con automake</title>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <para>Primero copie el archivo <filename>Makefile.am</filename> de la subcarpeta <filename class="directory">examples</filename> de <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink> a la carpeta de documentación de la API de su proyecto (<filename class="directory">./docs/reference/<package></filename>). Debería haber una copia local disponible en <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Si tiene varios paquetes de documentación, repítalo para cada uno de ellos.</para>
+ <orderedlist>
+ <listitem><para>--with-html-dir=RUTA: ruta a los documentos instalados</para></listitem>
+ <listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=sí]</para></listitem>
+ <listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no]</para></listitem>
+ </orderedlist>
- <para>El siguiente paso es editar la configuración dentro de <filename>Makefile.am</filename>. Todos los ajustes tienen un comentario encima que describe su propósito. Muchos ajustes son opciones adicionales pasadas a las respectivas herramientas. Cada herramienta tiene una variable de la forma <option><NOMBRE_DE_LA_HERRAMIENTA>_OPCIONES</option>. Todas las herramientas soportan <option>--help</option> para listar los parámetros que soportan.</para>
+ <important>
+ <para>GTK-Doc está desactivado de forma predeterminada. Recuerde pasar la opción <option>«--enable-gtk-doc»</option> en la siguiente ejecución de <filename>configure</filename>. De otra forma, la documentación pregenerada se instala (lo que tiene sentido para usuarios, pero no para desarrolladores).</para>
+ </important>
- <!-- FIXME: explain options ? -->
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- </sect1>
+ <sect2 id="settingup_autogen">
+ <title>Integración con autogen</title>
- <sect1 id="settingup_autogen">
- <title>Integración con autogen</title>
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
- <para>La mayoría de los proyectos tienen un script <filename>autogen.sh</filename> para configurar la infraestructura de construcción después de hacer un «checkout» desde los sistemas de control de versiones (tales como cvs/svn/git). GTK-Doc tiene una herramienta llamada <filename>gtkdocize</filename> que se puede usar en tal script. Se debería ejecutar antes que autoheader, automake o autoconf.</para>
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
- <para>
- <example><title>Ejecutar gtkdocize desde autogen.sh</title>
- <programlisting>
+ <example><title>Ejecutar gtkdocize desde autogen.sh</title>
gtkdocize || exit 1
</programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>Al ejecutar <filename>gtkdocize</filename> copia <filename>gtk-doc.make</filename> a la raíz de su proyecto (o cualquier carpeta especificada por la opción <option>--docdir</option>). También comprueba su script de configuración para la invocación de <function>GTK_DOC_CHECK</function>. Esta macro se puede usar para pasar parámetros adicionales a <application>gtkdocize</application>.</para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>Históricamente GTK-Doc generaba plantillas de archivos donde los desarrolladores introducían los documentos. Al final esto resulto no ser muy bueno (por ejemplo, por la necesidad de tener archivos generados bajo un control de versiones). Desde la versión de DTK-Doc 1.9 las herramientas pueden obtener toda la información desde los comentarios del código fuente y por ello se pueden evitar las plantillas. Se anima a los desarrolladores a mantener su documentación en el código. <application>gtkdocize</application> ahora soporta una opción <option>--flavour no-tmpl</option> que elije un makefile que omite completamente el uso de plantillas. Además de añadir la opción directamente a la línea de comandos al invocarlo, se pueden añadir a una variable de entorno llamada <symbol>GTKDOCIZE_FLAGS</symbol> o configurar como un segundo parámetro en la macro <symbol>GTK_DOC_CHECK</symbol> en el script de configuración. Si nunca ha cambiado un archivo tmpl (plantilla) a mano, elimine la carpeta una vez (ej. desde el sistema de control de versiones).</para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>Ejecutar la construcción de la documentación</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>Después de los pasos anteriores es hora de ejecutar el constructor. Primero se debe volver a ejecutar <filename>autogen.sh</filename>. Si este script ejecuta configure automáticamente, entonces debe pasar la opción <option>--enable-gtk-doc</option>. De otra forma, ejecute posteriormente <filename>configure</filename> con esta opción.</para>
- <para>El primer make genera diversas líneas adicionales en las carpetas de documentación. Las importantes son: <filename><paquete>.types</filename>, <filename><paquete>-docs.xml</filename> (.sgml en el pasado), <filename><paquete>-sections.txt</filename>.</para>
- <para>
- <example><title>Ejecutar la construcción de la documentación</title>
- <programlisting>
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>Después de los pasos anteriores es hora de ejecutar el constructor. Primero se debe volver a ejecutar <filename>autogen.sh</filename>. Si este script ejecuta configure automáticamente, entonces debe pasar la opción <option>--enable-gtk-doc</option>. De otra forma, ejecute posteriormente <filename>configure</filename> con esta opción.</para>
+ <para>El primer make genera diversas líneas adicionales en las carpetas de documentación. Las importantes son: <filename><paquete>.types</filename>, <filename><paquete>-docs.xml</filename> (.sgml en el pasado), <filename><paquete>-sections.txt</filename>.</para>
+ <para>
+ <example><title>Ejecutar la construcción de la documentación</title>
+ <programlisting>
./autogen.sh --enable-gtk-doc
make
</programlisting>
- </example>
- </para>
- <para>Ahora puede apuntar su navegador a <filename>docs/reference/<paquete>/index.html</filename>. Sí, aún es un poco decepcionante. Pero espere, durante el siguiente capítulo aprenderá a rellenar las páginas con información.</para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>Integración con los sistemas de control de versiones</title>
+ <sect1 id="settingup_cmake">
+ <title>Integración con sistemas de construcción CMake</title>
- <para>Como regla principal, son los archivos que edita los que deberían estar bajo el control de versiones. Para proyectos típicos son los archivos: <filename><paquete>.types</filename>, <filename><paquete>-docs.xml</filename> (anteriormente .sgml), <filename><paquete>-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
- <para>Los archivos de las carpetas <filename>xml/</filename> y <filename>html/</filename> No deberían estar bajo control de versiones. Tampoco ninguno de los archivos <filename>.stamp</filename>.</para>
+ <para>Ahroa, GTK-Doc proporciona un módulo <filename>GtkDocConfig.cmake</filename> (y el correspondiente módulo <filename>GtkDocConfigVersion.cmake</filename>). Esto proporciona un comando <literal>gtk_doc_add_module</literal> que puede configurar en su archivo <filename>CMakeLists.txt</filename>.</para>
+
+ <para>El siguiente ejemplo muestra cómo usar este comando. <example><title>Ejeplo de uso de GTK-Doc desde CMake</title>
+ <programlisting>
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+</programlisting>
+ </example></para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integración con makefiles u otros sistemas de construcción</title>
<para>En el caso de que no quiera usar automake y por ello <filename>gtk-doc.mak</filename> deberá llamar a las herramientas gtkdoc en el orden correcto en makefiles propios (o en otras herramientas de construcción).</para>
<para>Deberá mirar en el archivo <filename>Makefile.am</filename> y <filename>gtk-doc.mak</filename> para elegir las opciones adicionales necesarias.</para>
</sect1>
- <sect1 id="cmake">
- <title>Integración con sistemas de construcción CMake</title>
-
- <para>Ahroa, GTK-Doc proporciona un módulo <filename>GtkDocConfig.cmake</filename> (y el correspondiente módulo <filename>GtkDocConfigVersion.cmake</filename>). Esto proporciona un comando <literal>gtk_doc_add_module</literal> que puede configurar en su archivo <filename>CMakeLists.txt</filename>.</para>
-
- <para>El siguiente ejemplo muestra cómo usar este comando. <example><title>Ejeplo de uso de GTK-Doc desde CMake</title>
- <programlisting>
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>Integración con los sistemas de control de versiones</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>Como regla principal, son los archivos que edita los que deberían estar bajo el control de versiones. Para proyectos típicos son los archivos: <filename><paquete>.types</filename>, <filename><paquete>-docs.xml</filename> (anteriormente .sgml), <filename><paquete>-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
+ <para>Los archivos de las carpetas <filename>xml/</filename> y <filename>html/</filename> No deberían estar bajo control de versiones. Tampoco ninguno de los archivos <filename>.stamp</filename>.</para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-</programlisting>
- </example></para>
- </sect1>
</chapter>
<chapter id="documenting">
<para>GTK-Doc usa código fuente comentado con una sintaxis especial para documentar el código. Además obtiene información acerca de la estructura de su proyecto de otras fuentes. En la siguiente sección encontrará información acerca de la sintaxis de los comentarios.</para>
- <note>
- <title>Ubicación de la documentación</title>
- <para>En el pasado la mayoría de la documentación se debía rellenar en campos dentro de la carpeta <filename>tmpl</filename>. Esto tiene las desventajas de que la información. Esto tiene las desventajas de que la información no se actualiza muy a menudo y que el archivo tiene tendencia a causar conflictos con los sistemas de control de versiones.</para>
- <para>Para evitar los problemas anteriormente mencionados, se sugiere dejar la documentación dentro de los fuentes. Este manual sólo describe esta forma de documentar el código.</para>
- </note>
-
- <para>El analizador puede manejar bien la mayoría de cabeceras de C. En el caso de recibir avisos del analizador que parecen casos especiales, puede sugerir a GTK-Doc que los omita. <example><title>Bloque de comentario de GTK-Doc</title>
- <programlisting>
+ <para>
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
+ <example><title>GTK-Doc comment block</title>
+ <programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif
-</programlisting>
- </example></para>
+]]></programlisting>
+ </example>
+ </para>
<note>
<title>Limitaciones</title>
<para>Se pueden encontrar más ejemplos de las etiquetas de marcado soportadas en el <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">Manual de referencia de sintaxis de marcado de documentación de GTK+</ulink>.</para>
<tip>
- <para>Tal y como se ha mencionado antes, la documentación anterior de GTK-Doc es para documentar la API pública .Por ello, no se puede escribir documentación para los símbolos estáticos. No obstante es una buena práctica comentar los símbolos. Esto ayuda a que otros entiendan su código. Por ello se recomienda comentarlos usando comentarios normales (sin el segundo «*» en la primera línea). Si la función, posteriormente, se debe hacer pública, todo lo que el programador debe hacer es añadir otro «*» en el bloque de comentario e introducir el nombre del símbolo en la parte derecha dentro del archivo de secciones.</para>
+ <para>
+ As already mentioned earlier GTK-Doc is for documenting public API. Thus
+ one cannot write documentation for static symbols. Nevertheless it is good
+ to comment those symbols too. This helps other developers to understand
+ your code.
+ Therefore we recommend to comment these using normal comments (without the
+ 2nd '*' in the first line).
+ If later the function needs to be made public, all one needs to do is to
+ add another '*' in the comment block and insert the symbol name at the
+ right place inside the sections file.
+ </para>
</tip>
</sect1>
<para>Si su biblioteca o aplicación incluye GObjects puede querer que sus señales, argumentos y/o parámetros y posición en la jerarquía se muestre en la documentación. Todo lo que debe hacer es listar las funciones <function>xxx_get_type</function> junto con sus «include» en el archivo <filename><paquete>.types</filename>.</para>
<para>
- <example><title>Fragmento de ejemplo de tipos de archivo</title>
+ <example><title>Example <package>.types file</title>
<programlisting>
#include <gtk/gtk.h>
<sect1 id="modernizing-gtk-doc-1-25">
<title>GTK-Doc 1.25</title>
- <para>El makefile distribuído con esta versión genera un archivo de entidad en <filename>xml/gtkdocentities.ent</filename>, que contiene las entidades para, por ejemplo nombre_paquete y versión_paquete. Puede usar este ejemplo en el archivo main.xml para evitar escribir a mano el número de versión. A continuación se muestra un ejemplo que muestra cómo se incluye el archivo de entidad y cómo se usan las entidades. Las entidades también se pueden usar en todos los archivos generados, GTK-Doc usará la misma cabecera XML en los archivos XML generados. <example><title>Usar entidades generadas previamenet</title>
- <programlisting>
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ <para>
+ The makefiles shipped with this version generate an entity file at <filename>xml/gtkdocentities.ent</filename>,
+ containing entities for e.g. package_name and package_version. You can
+ use this e.g. in the main xml file to avoid hardcoding the version
+ number. Below is an example that shows how the entity file is included
+ in the master template and how the entities are used.
+ The entities can also be used in all
+ generated files, GTK-Doc will use the same xml header in generated xml
+ files.
+ <example><title>Use pre-generated entities</title>
+ <programlisting><![CDATA[
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
- <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
- <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
- <bookinfo>
- <title>&package_name; Reference Manual</title>
- <releaseinfo>
- for &package_string;.
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+ <bookinfo>
+ <title>&package_name; Reference Manual</title>
+ <releaseinfo>
+ for &package_string;.
The latest version of this documentation can be found on-line at
- <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
- </releaseinfo>
- </bookinfo>
-</programlisting>
- </example></para>
+ <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
+ </releaseinfo>
+ </bookinfo>
+]]></programlisting>
+ </example>
+ </para>
</sect1>
</chapter>
msgstr ""
"Project-Id-Version: gtk-doc-help HEAD\n"
"Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2012-10-15 08:49+0000\n"
-"PO-Revision-Date: 2013-01-23 12:34+0100\n"
+"POT-Creation-Date: 2017-08-11 11:08+0000\n"
+"PO-Revision-Date: 2017-10-19 11:24+0200\n"
"Last-Translator: Daniel Mustieles <daniel.mustieles@gmail.com>\n"
"Language-Team: Español <gnome-es-list@gnome.org>\n"
-"Language: \n"
+"Language: fr\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=n>1;\n"
+"X-Generator: Poedit 2.0.1\n"
#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
msgctxt "_"
"Gérard Baylard <Geodebay@gmail.com>, 2010\n"
"Luc Pionchon <pionchon.luc@gmail.com>, 2011"
-#: C/index.docbook:12(bookinfo/title)
+#. (itstool) path: bookinfo/title
+#: C/index.docbook:12
msgid "GTK-Doc Manual"
msgstr "Manuel de GTK-Doc"
-#: C/index.docbook:13(bookinfo/edition)
-msgid "1.18.1"
-msgstr "1.18.1"
+#. (itstool) path: bookinfo/edition
+#: C/index.docbook:13
+msgid "1.24.1"
+msgstr "1.24.1"
-#: C/index.docbook:14(abstract/para)
+#. (itstool) path: abstract/para
+#: C/index.docbook:14
msgid "User manual for developers with instructions of GTK-Doc usage."
msgstr ""
"Manuel utilisateur pour les développeurs contenant les instructions sur "
"l'usage de GTK-Doc."
-#: C/index.docbook:16(authorgroup/author)
+#. (itstool) path: authorgroup/author
+#: C/index.docbook:16
msgid ""
"<firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation> "
"<address> <email>chris@wilddev.net</email> </address> </affiliation>"
"<firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation> "
"<address> <email>chris@wilddev.net</email> </address> </affiliation>"
-#: C/index.docbook:25(authorgroup/author)
+#. (itstool) path: authorgroup/author
+#: C/index.docbook:25
msgid ""
"<firstname>Dan</firstname> <surname>Mueth</surname> <affiliation> <address> "
"<email>d-mueth@uchicago.edu</email> </address> </affiliation>"
"<firstname>Dan</firstname> <surname>Mueth</surname> <affiliation> <address> "
"<email>d-mueth@uchicago.edu</email> </address> </affiliation>"
-#: C/index.docbook:34(authorgroup/author)
+#. (itstool) path: authorgroup/author
+#: C/index.docbook:34
+#| msgid ""
+#| "<firstname>Stefan</firstname> <surname>Kost</surname> <affiliation> "
+#| "<address> <email>ensonic@users.sf.net</email> </address> </affiliation>"
msgid ""
-"<firstname>Stefan</firstname> <surname>
Kost</surname> <affiliation> "
+"<firstname>Stefan</firstname> <surname>
Sauer (Kost)</surname> <affiliation> "
"<address> <email>ensonic@users.sf.net</email> </address> </affiliation>"
msgstr ""
-"<firstname>Stefan</firstname> <surname>
Kost</surname> <affiliation> "
+"<firstname>Stefan</firstname> <surname>
Sauer (Kost)</surname> <affiliation> "
"<address> <email>ensonic@users.sf.net</email> </address> </affiliation>"
-#: C/index.docbook:45(publisher/publishername)
+#. (itstool) path: publisher/publishername
+#: C/index.docbook:45
msgid "GTK-Doc project"
msgstr "Projet GTK-Doc"
-#: C/index.docbook:44(bookinfo/publisher)
+#. (itstool) path: bookinfo/publisher
+#: C/index.docbook:44
msgid ""
"<_:publishername-1/> <address><email>gtk-doc-list@gnome.org</email></address>"
msgstr ""
"<_:publishername-1/> <address><email>gtk-doc-list@gnome.org</email></address>"
-#: C/index.docbook:48(bookinfo/copyright)
+#. (itstool) path: bookinfo/copyright
+#: C/index.docbook:48
msgid "<year>2000, 2005</year> <holder>Dan Mueth and Chris Lyttle</holder>"
msgstr "<year>2000, 2005</year> <holder>Dan Mueth et Chris Lyttle</holder>"
-#: C/index.docbook:52(bookinfo/copyright)
-msgid "<year>2007-2011</year> <holder>Stefan Sauer (Kost)</holder>"
-msgstr "<year>2007-2011</year> <holder>Stefan Sauer (Kost)</holder>"
+#. (itstool) path: bookinfo/copyright
+#: C/index.docbook:52
+#| msgid "<year>2007-2011</year> <holder>Stefan Sauer (Kost)</holder>"
+msgid "<year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder>"
+msgstr "<year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder>"
-#: C/index.docbook:65(legalnotice/para)
+#. (itstool) path: legalnotice/para
+#: C/index.docbook:65
msgid ""
"Permission is granted to copy, distribute and/or modify this document under "
"the terms of the <citetitle>GNU Free Documentation License</citetitle>, "
"couverture ni texte de dernière page de couverture. Vous trouverez un "
"exemplaire de cette licence en suivant ce <link linkend=\"fdl\">lien</link>."
-#: C/index.docbook:73(legalnotice/para)
+#. (itstool) path: legalnotice/para
+#: C/index.docbook:73
msgid ""
"Many of the names used by companies to distinguish their products and "
"services are claimed as trademarks. Where those names appear in any GNOME "
"Documentation GNOME sont informés de l'existence de ces marques déposées, "
"soit ces noms entiers, soit leur première lettre est en majuscule."
-#: C/index.docbook:83(revhistory/revision)
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:83
+#| msgid ""
+#| "<revnumber>1.18.1</revnumber> <date>20 Sep 2011</date> "
+#| "<authorinitials>ss</authorinitials> <revremark>development version</"
+#| "revremark>"
msgid ""
-"<revnumber>1.
18.1</revnumber> <date>20 Sep 2011</date> <authorinitials>ss</"
-"authorinitials> <revremark>development version</revremark>"
+"<revnumber>1.
26.1</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
+"authorinitials> <revremark>development</revremark>"
msgstr ""
-"<revnumber>1.18.1</revnumber> <date>20 septembre 2011</date> "
-"<authorinitials>ss</authorinitials> <revremark>version de développement</"
+"<revnumber>1.26.1</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
+"authorinitials> <revremark>développement</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:89
+#| msgid ""
+#| "<revnumber>1.18.1</revnumber> <date>20 Sep 2011</date> "
+#| "<authorinitials>ss</authorinitials> <revremark>development version</"
+#| "revremark>"
+msgid ""
+"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
+"authorinitials> <revremark>port all tools from perl/bash to python</"
"revremark>"
+msgstr ""
+"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
+"authorinitials> <revremark>portage de tous les outils depuis perl/bash vers "
+"python</revremark>"
-#: C/index.docbook:89(revhistory/revision)
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+#| msgid ""
+#| "<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
+#| "authorinitials> <revremark>bug and regression fixes</revremark>"
msgid ""
-"<revnumber>1.18</revnumber> <date>14 sep 2011</date> <authorinitials>ss</"
-"authorinitials> <revremark>bug fixes, speedups, markdown support</revremark>"
+"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
+msgstr ""
+"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
+"authorinitials> <revremark>corrections d'anomalies, nettoyages de test</"
+"revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:101
+#| msgid ""
+#| "<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
+#| "authorinitials> <revremark>bug and regression fixes</revremark>"
+msgid ""
+"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fix</revremark>"
msgstr ""
-"<revnumber>1.18</revnumber> <date>14 septembre 2011</date> "
-"<authorinitials>ss</authorinitials> <revremark>correction de bogues, "
-"amélioration de la vitesse de traitement, prise en charge de markdown</"
+"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>corrections d'anomalies</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:107
+#| msgid ""
+#| "<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
+#| "authorinitials> <revremark>bug and regression fixes</revremark>"
+msgid ""
+"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fix</revremark>"
+msgstr ""
+"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>corrections d'anomalies\n"
+"</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:113
+#| msgid ""
+#| "<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
+#| "authorinitials> <revremark>bugfixes, layout improvements</revremark>"
+msgid ""
+"<revnumber>1.22</revnumber> <date>07 May 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"revremark>"
+msgstr ""
+"<revnumber>1.22</revnumber> <date>07 May 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>corrections d'anomalies, abandon de "
+"fonctionnalités obsolètes</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:119
+#| msgid ""
+#| "<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
+#| "authorinitials> <revremark>bugfixes, layout improvements</revremark>"
+msgid ""
+"<revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes, dropping deprecated features</"
+"revremark>"
+msgstr ""
+"<revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</"
+"authorinitials> <revremark>corrections d'anomalies, abandon de "
+"fonctionnalités obsolètes</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:125
+#, fuzzy
+#| msgid ""
+#| "<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
+#| "authorinitials> <revremark>bugfixes, layout improvements</revremark>"
+msgid ""
+"<revnumber>1.20</revnumber> <date>16 Feb 2014</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes, markdown support, style improvements</"
+"revremark>"
+msgstr ""
+"<revnumber>1.16</revnumber> <date>14 janvier 2011</date> <authorinitials>sk</"
+"authorinitials> <revremark>correctifs et améliorations de mise en page</"
+"revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:131
+#| msgid ""
+#| "<revnumber>1.17</revnumber> <date>26 Feb 2011</date> <authorinitials>sk</"
+#| "authorinitials> <revremark>urgent bug fix update</revremark>"
+msgid ""
+"<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes</revremark>"
+msgstr ""
+"<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
+"authorinitials> <revremark>corrections d'anomalies</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:137
+#| msgid ""
+#| "<revnumber>1.18</revnumber> <date>14 sep 2011</date> <authorinitials>ss</"
+#| "authorinitials> <revremark>bug fixes, speedups, markdown support</"
+#| "revremark>"
+msgid ""
+"<revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes, speedups, markdown support</revremark>"
+msgstr ""
+"<revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</"
+"authorinitials> <revremark>correction de bogues, amélioration de la vitesse "
+"de traitement, prise en charge de markdown</revremark>"
-#: C/index.docbook:95(revhistory/revision)
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:143
msgid ""
"<revnumber>1.17</revnumber> <date>26 Feb 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>urgent bug fix update</revremark>"
"authorinitials> <revremark>mise à jour pour une correction de bogue urgente</"
"revremark>"
-#: C/index.docbook:101(revhistory/revision)
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:149
msgid ""
"<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes, layout improvements</revremark>"
"authorinitials> <revremark>correctifs et améliorations de mise en page</"
"revremark>"
-#: C/index.docbook:107(revhistory/revision)
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:155
msgid ""
"<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bug and regression fixes</revremark>"
"authorinitials> <revremark>corrections d'anomalies et de régressions</"
"revremark>"
-#: C/index.docbook:113(revhistory/revision)
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:161
msgid ""
"<revnumber>1.14</revnumber> <date>28 March 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes and performance improvements</revremark>"
"authorinitials> <revremark>correctifs et amélioration de performances</"
"revremark>"
-#: C/index.docbook:119(revhistory/revision)
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:167
msgid ""
"<revnumber>1.13</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>broken tarball update</"
"<authorinitials>sk</authorinitials> <revremark>mise à jour du tarball brisé</"
"revremark>"
-#: C/index.docbook:125(revhistory/revision)
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:173
msgid ""
"<revnumber>1.12</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>new tool features and "
"<authorinitials>sk</authorinitials> <revremark>nouvelles fonctionnalités aux "
"outils et résolution de bogues</revremark>"
-#: C/index.docbook:131(revhistory/revision)
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:179
msgid ""
"<revnumber>1.11</revnumber> <date>16 November 2008</date> "
"<authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</"
"<authorinitials>mal</authorinitials> <revremark>Migration à GNOME doc-utils</"
"revremark>"
-#: C/index.docbook:144(chapter/title)
+#. (itstool) path: chapter/title
+#: C/index.docbook:192
msgid "Introduction"
msgstr "Introduction"
-#: C/index.docbook:146(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:194
msgid ""
"This chapter introduces GTK-Doc and gives an overview of what it is and how "
"it is used."
"Ce chapitre présente GTK-Doc et fournit un aperçu de ce que c'est et de la "
"manière de l'utiliser."
-#: C/index.docbook:152(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:200
msgid "What is GTK-Doc?"
msgstr "Qu'est-ce que GTK-Doc ?"
-#: C/index.docbook:154(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:202
msgid ""
"GTK-Doc is used to document C code. It is typically used to document the "
"public API of libraries, such as the GTK+ and GNOME libraries. But it can "
"GTK+ et GNOME. Mais il peut aussi être utilisé pour documenter du code "
"d'application."
-#: C/index.docbook:162(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:210
msgid "How Does GTK-Doc Work?"
msgstr "Fonctionnement de GTK-Doc ?"
-#: C/index.docbook:164(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:212
msgid ""
"GTK-Doc works by using documentation of functions placed inside the source "
"files in specially-formatted comment blocks, or documentation added to the "
"déclarées dans des fichiers d'en-tête ; il ne fait rien pour les fonctions "
"statiques)."
-#: C/index.docbook:171(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:219
msgid ""
-"GTK-Doc consists of a number of perl scripts, each performing a different "
+"GTK-Doc consists of a number of python scripts, each performing a different "
"step in the process."
msgstr ""
-"GTK-Doc consiste en un certain nombre de scripts Perl, chacun réalisant une "
-"étape du processus."
+"GTK-Doc consiste en un certain nombre de scripts Python, chacun réalisant "
+"une étape du processus."
-#: C/index.docbook:176(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:224
msgid "There are 5 main steps in the process:"
msgstr "Il y a 5 étapes principales :"
-#: C/index.docbook:183(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:231
msgid ""
"<guilabel>Writing the documentation.</guilabel> The author fills in the "
"source files with the documentation for each function, macro, union etc. (In "
"etc. (dans le passé, l'information était saisie dans les fichiers prototypes "
"générés mais ce n'est plus recommandé)."
-#: C/index.docbook:193(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:241
msgid ""
"<guilabel>Gathering information about the code.</guilabel> "
"<application>gtkdoc-scan</application> scans the header files of the code "
"possible d'ajouter des entrées dans <filename><module>-overrides.txt</"
"filename> similaires à celle de <filename><module>-decl.txt</filename>."
-#: C/index.docbook:210(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:258
msgid ""
"<application>gtkdoc-scangobj</application> can also be used to dynamically "
"query a library about any GObject subclasses it exports. It saves "
"informations sur la position de chaque objet dans la hiérarchie de classe et "
"sur tous les arguments et signaux GTK fournis."
-#: C/index.docbook:216(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:264
msgid ""
"<application>gtkdoc-scanobj</application> should not be used anymore. It was "
"needed in the past when GObject was still GtkObject inside gtk+."
"était nécessaire par le passé lorsque GObject était encore GtkObject dans gtk"
"+."
-#: C/index.docbook:223(listitem/para)
-msgid ""
-"<guilabel>Generating the \"template\" files.</guilabel> <application>gtkdoc-"
-"mktmpl</application> creates a number of files in the <filename class="
-"\"directory\">tmpl/</filename> subdirectory, using the information gathered "
-"in the first step. (Note that this can be run repeatedly. It will try to "
-"ensure that no documentation is ever lost.)"
-msgstr ""
-"<guilabel>Génération des fichiers « prototypes ».</guilabel> "
-"<application>gtkdoc-mktmpl</application> crée un certain nombre de fichiers "
-"dans le sous-répertoire <filename class=\"directory\">tmpl/</filename>, en "
-"utilisant les informations récoltées lors de la première étape (notez que le "
-"script peut être exécuté plusieurs fois, il est fait en sorte qu'aucune "
-"donnée ne soit jamais perdue)."
-
-#: C/index.docbook:232(note/para)
-msgid ""
-"Since GTK-Doc 1.9 the templates can be avoided. We encourage people to keep "
-"documentation in the code. <application>gtkdocize</application> supports now "
-"a <option>--flavour no-tmpl</option> option that chooses a makefile that "
-"skips tmpl usage totally. If you have never changed file in tmpl by hand, "
-"please remove the directory (e.g. from version control system)."
-msgstr ""
-"Depuis GTK-Doc 1.9, les prototypes peuvent être évités. Nous encourageons "
-"tout le monde à conserver la documentation dans le code. "
-"<application>gtkdocize</application> prend maintenant en charge l'option "
-"<option>--flavour no-tmpl</option> qui choisit un makefile qui évite "
-"complètement l'utilisation de tmpl. Si vous n'avez jamais modifié de "
-"fichiers à la main dans tmpl, effacez le répertoire (par ex. à partir d'un "
-"système de gestion de versions)."
-
-#: C/index.docbook:244(listitem/para)
-msgid ""
-"<guilabel>Generating the SGML/XML and HTML/PDF.</guilabel> "
-"<application>gtkdoc-mkdb</application> turns the template files into SGML or "
-"XML files in the <filename class=\"directory\">sgml/</filename> or <filename "
+#. (itstool) path: listitem/para
+#: C/index.docbook:271
+#, fuzzy
+#| msgid ""
+#| "<guilabel>Generating the SGML/XML and HTML/PDF.</guilabel> "
+#| "<application>gtkdoc-mkdb</application> turns the template files into SGML "
+#| "or XML files in the <filename class=\"directory\">sgml/</filename> or "
+#| "<filename class=\"directory\">xml/</filename> subdirectory. If the source "
+#| "code contains documentation on functions, using the special comment "
+#| "blocks, it gets merged in here. If there are no tmpl files used it only "
+#| "reads docs from sources and introspection data. We recommend to use "
+#| "Docbook XML."
+msgid ""
+"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
+"mkdb</application> turns the template files into XML files in the <filename "
"class=\"directory\">xml/</filename> subdirectory. If the source code "
"contains documentation on functions, using the special comment blocks, it "
"gets merged in here. If there are no tmpl files used it only reads docs from "
-"sources and introspection data. We recommend to use Docbook XML."
+"sources and introspection data."
msgstr ""
"<guilabel>Génération du SGML/XML et du HTML/PDF.</guilabel> "
"<application>gtkdoc-mkdb</application> transforme les fichiers prototypes en "
"données d'introspection seront lues. Nous recommandons l'utilisation de XML "
"DocBook."
-#: C/index.docbook:255(listitem/para)
-msgid ""
-"<application>gtkdoc-mkhtml</application> turns the SGML/XML files into HTML "
-"files in the <filename class=\"directory\">html/</filename> subdirectory. "
-"Likewise <application>gtkdoc-mkpdf</application> turns the SGML/XML files "
-"into a PDF document called <filename><package>.pdf</filename>."
+#. (itstool) path: listitem/para
+#: C/index.docbook:280
+#, fuzzy
+#| msgid ""
+#| "<application>gtkdoc-mkhtml</application> turns the SGML/XML files into "
+#| "HTML files in the <filename class=\"directory\">html/</filename> "
+#| "subdirectory. Likewise <application>gtkdoc-mkpdf</application> turns the "
+#| "SGML/XML files into a PDF document called <filename><package>.pdf</"
+#| "filename>."
+msgid ""
+"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
+"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
+"<application>gtkdoc-mkpdf</application> turns the XML files into a PDF "
+"document called <filename><package>.pdf</filename>."
msgstr ""
"<application>gtkdoc-mkhtml</application> transforme les fichiers SGML/XML en "
"fichiers HTML dans le répertoire <filename class=\"directory\">html/</"
"fichiers SGML/XML en documents PDF appelés <filename><package>.pdf</"
"filename>."
-#: C/index.docbook:261(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:286
msgid ""
-"Files in <filename class=\"directory\">sgml/</filename> or <filename class="
-"\"directory\">xml/</filename> and <filename class=\"directory\">html/</"
-"filename> directories are always overwritten. One should never edit them "
-"directly."
+"Files in <filename class=\"directory\">xml/</filename> and <filename class="
+"\"directory\">html/</filename> directories are always overwritten. One "
+"should never edit them directly."
msgstr ""
-"Les fichiers dans les répertoires <filename class=\"directory\">sgml/</"
-"filename> ou <filename class=\"directory\">xml/</filename> et <filename "
-"class=\"directory\">html/</filename> sont toujours écrasés. Il ne faut pas "
-"les modifier directement."
+"Les fichiers dans les répertoires <filename class=\"directory\">xml/</"
+"filename> et <filename class=\"directory\">html/</filename> sont toujours "
+"écrasés. Il ne faut pas les modifier directement."
-#: C/index.docbook:269(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:294
msgid ""
"<guilabel>Fixing up cross-references between documents.</guilabel> After "
"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
"distribuée (pré-générée), la même application va essayer de retransformer "
"les liens en liens locaux (là où ces documentations sont installées)."
-#: C/index.docbook:287(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:312
msgid "Getting GTK-Doc"
msgstr "Obtention de GTK-Doc"
-#: C/index.docbook:290(sect2/title)
+#. (itstool) path: sect2/title
+#: C/index.docbook:315
msgid "Requirements"
msgstr "Pré-requis"
-#: C/index.docbook:291(sect2/para)
-msgid "<guilabel>Perl v5</guilabel> - the main scripts are in Perl."
-msgstr ""
-"<guilabel>Perl v5</guilabel> - les principaux scripts sont écrits en Perl."
-
-#: C/index.docbook:294(sect2/para)
-msgid ""
-"<guilabel>DocBook DTD v3.0</guilabel> - This is the DocBook SGML DTD. <ulink "
-"url=\"http://www.ora.com/davenport\" type=\"http\">http://www.ora.com/"
-"davenport</ulink>"
-msgstr ""
-"<guilabel>DocBook DTD v3.0</guilabel> - ce sont les DTD DocBook SGML. <ulink "
-"url=\"http://www.ora.com/davenport\" type=\"http\">http://www.ora.com/"
-"davenport</ulink>"
-
-#: C/index.docbook:298(sect2/para)
-msgid ""
-"<guilabel>Jade v1.1</guilabel> - This is a DSSSL processor for converting "
-"SGML to various formats. <ulink url=\"http://www.jclark.com/jade\" type="
-"\"http\">http://www.jclark.com/jade</ulink>"
-msgstr ""
-"<guilabel>Jade v1.1</guilabel> - c'est un moteur DSSSL pour convertir le "
-"SGML en divers formats. <ulink url=\"http://www.jclark.com/jade\" type=\"http"
-"\">http://www.jclark.com/jade</ulink>"
-
-#: C/index.docbook:302(sect2/para)
+#. (itstool) path: sect2/para
+#: C/index.docbook:316
msgid ""
-"<guilabel>Modular DocBook Stylesheets</guilabel> This is the DSSSL code to "
-"convert DocBook to HTML (and a few other formats). It's used together with "
-"jade. I've customized the DSSSL code slightly, in gtk-doc.dsl, to colour the "
-"program code listings/declarations, and to support global cross-reference "
-"indices in the generated HTML. <ulink url=\"http://nwalsh.com/docbook/dsssl"
-"\" type=\"http\">http://nwalsh.com/docbook/dsssl</ulink>"
+"<guilabel>python 2/3</guilabel> - the main scripts are written in python."
msgstr ""
-"<guilabel>Modular DocBook Stylesheets</guilabel> - c'est le code DSSSL "
-"utilisé pour convertir de DocBook vers HTML (ainsi que quelques autres "
-"formats). Il est utilisé conjointement avec Jade. J'ai légèrement "
-"personnalisé le code DSSSL, dans gtk-doc.dsl, pour coloriser les listings de "
-"code du programme et les déclarations ainsi que pour prendre en charge les "
-"indices globaux des références croisées dans le HTML généré. <ulink url="
-"\"http://nwalsh.com/docbook/dsssl\" type=\"http\">http://nwalsh.com/docbook/"
-"dsssl</ulink>"
+"<guilabel>python 2/3</guilabel> - les principaux scripts sont écrits en "
+"Python."
-#: C/index.docbook:311(sect2/para)
+#. (itstool) path: sect2/para
+#: C/index.docbook:319
msgid ""
-"<guilabel>docbook-to-man</guilabel> - if you want to create man pages from "
-"the DocBook. I've customized the 'translation spec' slightly, to capitalise "
-"section headings and add the 'GTK Library' title at the top of the pages and "
-"the revision date at the bottom. There is a link to this on <ulink url="
-"\"http://www.ora.com/davenport\" type=\"http\">http://www.ora.com/davenport</"
-"ulink> NOTE: This does not work yet."
+"<guilabel>xsltproc</guilabel> - the xslt processor from libxslt <ulink url="
+"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
msgstr ""
-"<guilabel>docbook-to-man</guilabel> - si vous souhaitez créer des pages de "
-"manuel depuis DocBook. J'ai légèrement adapté les « spécifications de "
-"traduction » pour mettre en majuscule les en-têtes de section et pour "
-"ajouter le titre « GTK Library » en haut des pages et la date de révision en "
-"bas. Il y a un lien sur cela ici <ulink url=\"http://www.ora.com/davenport\" "
-"type=\"http\">http://www.ora.com/davenport</ulink>. Note : cela ne "
-"fonctionne pas encore."
-
-#: C/index.docbook:322(sect2/title)
-msgid "Installation"
-msgstr "Installation"
-#: C/index.docbook:323(sect2/para)
+#. (itstool) path: sect2/para
+#: C/index.docbook:323
msgid ""
-"There is no standard place where the DocBook Modular Stylesheets are "
-"installed."
-msgstr ""
-"Il n'y a pas d'emplacement standard pour l'installation des feuilles de "
-"styles modulaires de DocBook."
-
-#: C/index.docbook:326(sect2/para)
-msgid "GTK-Doc's configure script searches these 3 directories automatically:"
+"<guilabel>docbook-xsl</guilabel> - the docbook xsl stylesheets <ulink url="
+"\"http://sourceforge.net/projects/docbook/files/docbook-xsl/\" type=\"http"
+"\">sourceforge.net/projects/docbook/files/docbook-xsl</ulink>"
msgstr ""
-"Les scripts d'installation de GTK-Doc cherchent dans ces trois répertoires "
-"automatiquement :"
-#: C/index.docbook:329(sect2/para)
+#. (itstool) path: sect2/para
+#: C/index.docbook:327
msgid ""
-"<filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> (used by "
-"RedHat)"
+"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
+"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
+"examples"
msgstr ""
-"<filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> (utilisé par "
-"Red Hat)"
-#: C/index.docbook:332(sect2/para)
-msgid ""
-"<filename> /usr/lib/dsssl/stylesheets/docbook </filename> (used by Debian)"
-msgstr ""
-"<filename> /usr/lib/dsssl/stylesheets/docbook </filename> (utilisé par "
-"Debian)"
-
-#: C/index.docbook:335(sect2/para)
-msgid "<filename> /usr/share/sgml/docbkdsl </filename> (used by SuSE)"
-msgstr "<filename> /usr/share/sgml/docbkdsl </filename> (utilisé par SuSE)"
-
-#: C/index.docbook:338(sect2/para)
-msgid ""
-"If you have the stylesheets installed somewhere else, you need to configure "
-"GTK-Doc using the option: <command> --with-dsssl-dir=<"
-"PATH_TO_TOPLEVEL_STYLESHEETS_DIR> </command>"
-msgstr ""
-"Si les feuilles de styles sont installées autre part, vous devez configurer "
-"GTK-Doc en utilisant l'option : <command>--with-dsssl-dir=<"
-"CHEMIN_VERS_REPERTOIRE_RACINE_FEUILLES2STYLEs></command>."
-
-#: C/index.docbook:362(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:335
msgid "About GTK-Doc"
msgstr "À propos de GTK-Doc"
-#: C/index.docbook:364(sect1/para) C/index.docbook:378(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:337 C/index.docbook:351
msgid "(FIXME)"
msgstr "(À COMPLETER)"
-#: C/index.docbook:368(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:341
msgid ""
-"(History, authors, web pages, license, future plans, comparison with other "
-"similar systems.)"
+"(History, authors, web pages, mailing list, license, future plans, "
+"comparison with other similar systems.)"
msgstr ""
-"(Historique, auteurs, pages Web, licence, projets futurs, comparaison avec "
-"des systèmes similaires.)"
+"(Historique, auteurs, pages Web, liste de diffusion, licence, projets "
+"futurs, comparaison avec des systèmes similaires.)"
-#: C/index.docbook:376(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:349
msgid "About this Manual"
msgstr "À propos de ce manuel"
-#: C/index.docbook:382(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:355
msgid "(who it is meant for, where you can get it, license)"
msgstr "(qui est concerné, où le récupérer, licence)"
-#: C/index.docbook:391(chapter/title)
+#. (itstool) path: chapter/title
+#: C/index.docbook:364
msgid "Setting up your project"
msgstr "Mise en place de votre projet"
-#: C/index.docbook:393(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:366
msgid ""
"The next sections describe what steps to perform to integrate GTK-Doc into "
"your project. Theses sections assume we work on a project called 'meep'. "
"link> décrit les éléments de base à respecter pour travailler dans une autre "
"configuration de construction."
-#: C/index.docbook:404(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:377
msgid "Setting up a skeleton documentation"
msgstr "Mise en place du squelette de documentation"
-#: C/index.docbook:406(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:379
msgid ""
"Under your top-level project directory create folders called docs/reference "
"(this way you can also have docs/help for end-user documentation). It is "
"répertoire portant le nom du paquet de documentation. Pour les paquets qui "
"contiennent seulement une bibliothèque, cette étape n'est pas nécessaire."
-#: C/index.docbook:415(example/title)
+#. (itstool) path: example/title
+#: C/index.docbook:388
msgid "Example directory structure"
msgstr "Exemple d'arborescence de répertoires"
-#: C/index.docbook:416(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:389
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "meep/\n"
+#| " docs/\n"
+#| " reference/\n"
+#| " libmeep/\n"
+#| " meeper/\n"
+#| " src/\n"
+#| " libmeep/\n"
+#| " meeper/\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"meep/\n"
" docs/\n"
" reference/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"meep/\n"
" docs/\n"
" reference/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
-"\n"
-" "
-#: C/index.docbook:413(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:386
msgid "This can then look as shown below: <_:example-1/>"
msgstr "Cela peut ressembler à ce qui suit : <_:example-1/>"
-#: C/index.docbook:433(sect1/title) C/index.docbook:440(example/title)
+#. (itstool) path: sect1/title
+#. (itstool) path: example/title
+#: C/index.docbook:404 C/index.docbook:411
msgid "Integration with autoconf"
msgstr "Intégration avec autoconf"
-#: C/index.docbook:435(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:406
msgid ""
"Very easy! Just add one line to your <filename>configure.ac</filename> "
"script."
"C'est très simple ! Il faut juste ajouter une ligne dans votre script "
"<filename>configure.ac</filename>."
-#: C/index.docbook:441(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:412
#, no-wrap
msgid ""
"\n"
-"\n"
"# check for gtk-doc\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"# check for gtk-doc\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
-"\n"
-" "
-#: C/index.docbook:455(example/title)
+#. (itstool) path: example/title
+#: C/index.docbook:424
msgid "Keep gtk-doc optional"
msgstr "Laisser gtk-doc optionnel"
-#: C/index.docbook:456(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:425
#, no-wrap
msgid ""
"\n"
-"\n"
"# check for gtk-doc\n"
"m4_ifdef([GTK_DOC_CHECK], [\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
"],[\n"
"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n"
"])\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"# check for gtk-doc\n"
"m4_ifdef([GTK_DOC_CHECK], [\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
"],[\n"
"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n"
"])\n"
-"\n"
-" "
-#: C/index.docbook:450(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:419
msgid ""
"This will require all developers to have gtk-doc installed. If it is okay "
"for your project to have optional api-doc build setup, you can solve this as "
"modifiez pas car gtkdocize recherche <function>GTK_DOC_CHECK</function> au "
"début d'une ligne. <_:example-1/>"
-#: C/index.docbook:469(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:436
msgid ""
"The first argument is used to check for the gtkdocversion at configure time. "
"The 2nd, optional argument is used by <application>gtkdocize</application>. "
"<application>gtkdocize</application>. La macro <symbol>GTK_DOC_CHECK</"
"symbol> ajoute également plusieurs drapeaux de configuration :"
-#: C/index.docbook:475(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:442
msgid "--with-html-dir=PATH : path to installed docs"
msgstr ""
"--with-html-dir=CHEMIN : répertoire d'installation de la documentation,"
-#: C/index.docbook:476(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:443
msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]"
msgstr ""
"--enable-gtk-doc : utilisation de gtk-doc pour construire la documentation "
"[par défaut=no],"
-#: C/index.docbook:477(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:444
msgid ""
"--enable-gtk-doc-html : build documentation in html format [default=yes]"
msgstr ""
"--enable-gtk-doc-html : construction de la documentation au format html [par "
"défaut=yes],"
-#: C/index.docbook:478(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:445
msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
-msgstr ""
-"--enable-gtk-doc-pdf : construction de la documentation au format pdf [par "
-"défaut=no]."
+msgstr "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
-#: C/index.docbook:482(important/para)
+#. (itstool) path: important/para
+#: C/index.docbook:449
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"générée est installée (ce qui a du sens pour les utilisateurs mais pas pour "
"les développeurs)."
-#: C/index.docbook:490(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:457
+#, fuzzy
+#| msgid ""
+#| "Furthermore it is recommended that you have the following line inside you "
+#| "<filename>configure.ac</filename> script. This allows "
+#| "<application>gtkdocize</application> to automatically copy the macro "
+#| "definition for <function>GTK_DOC_CHECK</function> to your project."
msgid ""
-"Furthermore it is recommended that you have the following line inside you "
+"Furthermore it is recommended that you have the following line inside your "
"<filename>configure.ac</filename> script. This allows "
"<application>gtkdocize</application> to automatically copy the macro "
"definition for <function>GTK_DOC_CHECK</function> to your project."
"application> de copier automatiquement les définitions de macro pour "
"<function>GTK_DOC_CHECK</function> à votre projet."
-#: C/index.docbook:498(example/title)
+#. (itstool) path: example/title
+#: C/index.docbook:465
msgid "Preparation for gtkdocize"
msgstr "Préparation pour gtkdocize"
-#: C/index.docbook:499(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:466
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "AC_CONFIG_MACRO_DIR(m4)\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"AC_CONFIG_MACRO_DIR(m4)\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"AC_CONFIG_MACRO_DIR(m4)\n"
-"\n"
-" "
-#: C/index.docbook:509(sect1/title)
+#. (itstool) path: sect1/para
+#: C/index.docbook:471
+msgid ""
+"After all changes to <filename>configure.ac</filename> are made, update the "
+"<filename>configure</filename> file. This can be done by re-running "
+"<code>autoreconf -i</code> or <code>autogen.sh</code>."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:479
msgid "Integration with automake"
msgstr "Intégration avec automake"
-#: C/index.docbook:511(sect1/para)
-msgid ""
-"First copy the <filename>Makefile.am</filename> from the examples "
-"subdirectory of the gtkdoc-sources to your project's API documentation "
-"directory ( <filename class=\"directory\">./docs/reference/<package></"
-"filename>). If you have multiple doc-packages repeat this for each one."
+#. (itstool) path: sect1/para
+#: C/index.docbook:481
+#, fuzzy
+#| msgid ""
+#| "First copy the <filename>Makefile.am</filename> from the examples "
+#| "subdirectory of the gtkdoc-sources to your project's API documentation "
+#| "directory ( <filename class=\"directory\">./docs/reference/<package>"
+#| "</filename>). If you have multiple doc-packages repeat this for each one."
+msgid ""
+"First copy the <filename>Makefile.am</filename> from the <filename class="
+"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
+"git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am\">gtkdoc-sources</"
+"ulink> to your project's API documentation directory ( <filename class="
+"\"directory\">./docs/reference/<package></filename>). A local copy "
+"should be available under e.g. <filename>/usr/share/doc/gtk-doc-tools/"
+"examples/Makefile.am</filename>. If you have multiple doc-packages repeat "
+"this for each one."
msgstr ""
"Pour commencer, copiez le fichier <filename>Makefile.am</filename> depuis le "
"sous-répertoire des exemples de gtkdoc-sources vers le répertoire de "
"reference/<paquet></filename>). S'il y a plusieurs paquets de "
"documentation, répétez cette étape pour chacun d'eux."
-#: C/index.docbook:518(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:492
msgid ""
"The next step is to edit the settings inside the <filename>Makefile.am</"
"filename>. All the settings have a comment above that describes their "
"_OPTIONS</option>. Tous les outils prennent en charge l'option <option>--"
"help</option> qui affiche la liste des options prises en charge."
-#: C/index.docbook:529(sect1/para)
-msgid ""
-"You may also want to enable GTK-Doc for the distcheck make target. Just add "
-"the one line shown in the next example to your top-level <filename>Makefile."
-"am</filename>:"
-msgstr ""
-"Il est aussi possible d'activer GTK-Doc pour la cible distcheck de make. Il "
-"faut juste ajouter la ligne suivante au fichier <filename>Makefile.am</"
-"filename> du répertoire racine :"
-
-#: C/index.docbook:536(example/title)
-msgid "Enable GTK-Doc during make distcheck"
-msgstr "Activation de GTK-Doc pendant le « make distcheck »"
-
-#: C/index.docbook:537(example/programlisting)
-#, no-wrap
-msgid ""
-"\n"
-"\n"
-"DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc\n"
-"\n"
-" "
-msgstr ""
-"\n"
-"\n"
-"DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc\n"
-"\n"
-" "
-
-#: C/index.docbook:548(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:506
msgid "Integration with autogen"
msgstr "Intégration avec autogen"
-#: C/index.docbook:550(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:508
msgid ""
"Most projects will have an <filename>autogen.sh</filename> script to setup "
"the build infrastructure after a checkout from version control system (such "
"utilisé dans un script comme celui-ci. Il doit être lancé avant autoheader, "
"automake ou autoconf."
-#: C/index.docbook:559(example/title)
+#. (itstool) path: example/title
+#: C/index.docbook:517
msgid "Running gtkdocize from autogen.sh"
msgstr "Exécution de gtkdocize depuis autogen.sh"
-#: C/index.docbook:560(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:518
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "gtkdocize || exit 1\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"gtkdocize || exit 1\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"gtkdocize || exit 1\n"
-"\n"
-" "
-#: C/index.docbook:568(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:524
msgid ""
"When running <application>gtkdocize</application> it copies <filename>gtk-"
"doc.make</filename> to your project root (or any directory specified by the "
"configure. Cette macro peut être utilisée pour transmettre des paramètres "
"supplémentaires à <application>gtkdocize</application>."
-#: C/index.docbook:577(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:533
msgid ""
"Historically GTK-Doc was generating template files where developers entered "
"the docs. This turned out to be not so good (e.g. the need for having "
"d'anciennes versions de gtkdoc, supprimez le répertoire (par ex. à partir du "
"système de gestion de versions)."
-#: C/index.docbook:594(sect1/title) C/index.docbook:611(example/title)
+#. (itstool) path: sect1/title
+#. (itstool) path: example/title
+#: C/index.docbook:550 C/index.docbook:567
msgid "Running the doc build"
msgstr "Lancement de la construction de la documentation"
-#: C/index.docbook:596(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:552
msgid ""
"After the previous steps it's time to run the build. First we need to rerun "
"<filename>autogen.sh</filename>. If this script runs configure for you, then "
"enable-gtk-doc</option>, sinon lancez manuellement <filename>configure</"
"filename> suivi de cette option."
-#: C/index.docbook:603(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:559
msgid ""
"The first make run generates several additional files in the doc-"
"directories. The important ones are: <filename><package>.types</"
"docs.xml</filename> (anciennement .sgml), <filename><paquet>-sections."
"txt</filename>."
-#: C/index.docbook:612(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:568
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "./autogen.sh --enable-gtk-doc\n"
+#| "make\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"./autogen.sh --enable-gtk-doc\n"
"make\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"./autogen.sh --enable-gtk-doc\n"
"make\n"
-"\n"
-" "
-#: C/index.docbook:620(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:574
msgid ""
"Now you can point your browser to <filename>docs/reference/<package>/"
"index.html</filename>. Yes, it's a bit disappointing still. But hang-on, "
"encore un peu décevant mais le prochain chapitre va expliquer comment donner "
"de la vie à ces pages."
-#: C/index.docbook:628(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:582
msgid "Integration with version control systems"
msgstr "Intégration avec des systèmes de gestion de versions"
-#: C/index.docbook:630(sect1/para)
-msgid ""
-"As a rule of the thumb, it's those files you edit, that should go under "
-"version control. For typical projects it's these files: <filename><"
-"package>.types</filename>, <filename><package>-docs..xml</filename> "
-"(in the past .sgml), <filename><package>-sections.txt</filename>, "
-"<filename>Makefile.am</filename>"
+#. (itstool) path: sect1/para
+#: C/index.docbook:584
+#, fuzzy
+#| msgid ""
+#| "As a rule of the thumb, it's those files you edit, that should go under "
+#| "version control. For typical projects it's these files: <filename><"
+#| "package>.types</filename>, <filename><package>-docs..xml</"
+#| "filename> (in the past .sgml), <filename><package>-sections.txt</"
+#| "filename>, <filename>Makefile.am</filename>"
+msgid ""
+"As a rule of thumb, it's the files you edit which should go under version "
+"control. For typical projects it's these files: <filename><package>."
+"types</filename>, <filename><package>-docs.xml</filename> (in the "
+"past .sgml), <filename><package>-sections.txt</filename>, "
+"<filename>Makefile.am</filename>."
msgstr ""
"Comme le veut la règle de base, ce sont les fichiers que vous modifiez qui "
"doivent être placés dans le système de gestion de versions. Pour les projets "
"<filename><paquet>-sections.txt</filename>, <filename>Makefile.am</"
"filename>"
-#: C/index.docbook:641(sect1/title)
+#. (itstool) path: sect1/para
+#: C/index.docbook:592
+msgid ""
+"Files in the <filename>xml/</filename> and <filename>html/</filename> "
+"directories should not go under version control. Neither should any of the "
+"<filename>.stamp</filename> files."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:600
msgid "Integration with plain makefiles or other build systems"
msgstr ""
"Intégration avec des « makefiles » simples et d'autres systèmes de "
"compilation"
-#: C/index.docbook:643(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:602
msgid ""
"In the case one does not want to use automake and therefore <filename>gtk-"
"doc.mak</filename> one will need to call the gtkdoc tools in the right order "
"gtkdoc dans le bon ordre dans les fichiers « makefiles » ad hoc (ou d'autres "
"systèmes)."
-#: C/index.docbook:650(example/title)
+#. (itstool) path: example/title
+#: C/index.docbook:609
msgid "Documentation build steps"
msgstr "Étapes de construction de la documentation"
-#: C/index.docbook:651(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:610
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "DOC_MODULE=meep\n"
+#| "// sources have changed\n"
+#| "gtkdoc-scan --module=$(DOC_MODULE) --source-dir=...\n"
+#| "gtkdoc-scangobj --module=$(DOC_MODULE)\n"
+#| "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml\n"
+#| "// xml files have changed\n"
+#| "mkdir html\n"
+#| "cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n"
+#| "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"DOC_MODULE=meep\n"
"// sources have changed\n"
-"gtkdoc-scan --module=$(DOC_MODULE) --source-dir=...\n"
+"gtkdoc-scan --module=$(DOC_MODULE) <source-dir>\n"
"gtkdoc-scangobj --module=$(DOC_MODULE)\n"
-"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml\n"
+"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>\n"
"// xml files have changed\n"
"mkdir html\n"
"cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"DOC_MODULE=meep\n"
"// sources have changed\n"
-"gtkdoc-scan --module=$(DOC_MODULE) --source-dir=...\n"
+"gtkdoc-scan --module=$(DOC_MODULE) <source-dir>\n"
"gtkdoc-scangobj --module=$(DOC_MODULE)\n"
-"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml\n"
+"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>\n"
"// xml files have changed\n"
"mkdir html\n"
"cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
-"\n"
-" "
-#: C/index.docbook:667(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:624
msgid ""
"One will need to look at the <filename>Makefile.am</filename> and "
"<filename>gtk-doc.mak</filename> to pick the extra options needed."
"<filename>gtk-doc.mak</filename> pour y trouver les options supplémentaires "
"nécessaires."
-#: C/index.docbook:676(chapter/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:631
+#, fuzzy
+#| msgid "Integration with plain makefiles or other build systems"
+msgid "Integration with CMake build systems"
+msgstr ""
+"Intégration avec des « makefiles » simples et d'autres systèmes de "
+"compilation"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:633
+msgid ""
+"GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module (and "
+"the corresponding <filename>GtkDocConfigVersion.cmake</filename> module). "
+"This provides a <literal>gtk_doc_add_module</literal> command that you can "
+"set in your <filename>CMakeLists.txt</filename> file."
+msgstr ""
+
+#. (itstool) path: example/title
+#: C/index.docbook:643
+msgid "Example of using GTK-Doc from CMake"
+msgstr "Exemple d'utilisation de GTK-Doc depuis CMake"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:644
+#, no-wrap
+msgid ""
+"\n"
+"find_package(GtkDoc 1.25 REQUIRED)\n"
+"\n"
+"# Create the doc-libmeep target.\n"
+"gtk_doc_add_module(\n"
+" libmeep ${CMAKE_SOURCE_DIR}/libmeep\n"
+" XML meep-docs.xml\n"
+" LIBRARIES libmeep\n"
+")\n"
+"\n"
+"# Build doc-libmeep as part of the default target. Without this, you would\n"
+"# have to explicitly run something like `make doc-libmeep` to build the docs.\n"
+"add_custom_target(documentation ALL DEPENDS doc-libmeep)\n"
+"\n"
+"# Install the docs. (This assumes you're using the GNUInstallDirs CMake module\n"
+"# to set the CMAKE_INSTALL_DOCDIR variable correctly).\n"
+"install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html\n"
+" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
+msgstr ""
+"\n"
+"find_package(GtkDoc 1.25 REQUIRED)\n"
+"\n"
+"# Create the doc-libmeep target.\n"
+"gtk_doc_add_module(\n"
+" libmeep ${CMAKE_SOURCE_DIR}/libmeep\n"
+" XML meep-docs.xml\n"
+" LIBRARIES libmeep\n"
+")\n"
+"\n"
+"# Build doc-libmeep as part of the default target. Without this, you would\n"
+"# have to explicitly run something like `make doc-libmeep` to build the docs.\n"
+"add_custom_target(documentation ALL DEPENDS doc-libmeep)\n"
+"\n"
+"# Install the docs. (This assumes you're using the GNUInstallDirs CMake module\n"
+"# to set the CMAKE_INSTALL_DOCDIR variable correctly).\n"
+"install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html\n"
+" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:641
+msgid "The following example shows how to use this command. <_:example-1/>"
+msgstr ""
+"L'exemple suivant montre comment utiliser cette commande. <_:example-1/>"
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:669
msgid "Documenting the code"
msgstr "Documentation du code"
-#: C/index.docbook:678(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:671
msgid ""
"GTK-Doc uses source code comment with a special syntax for code "
"documentation. Further it retrieves information about your project structure "
"structure de votre projet à partir d'autres sources. La section suivante "
"vous donne toutes les informations concernant la syntaxe des commentaires."
-#: C/index.docbook:686(note/title)
+#. (itstool) path: note/title
+#: C/index.docbook:679
msgid "Documentation placement"
msgstr "Emplacement de la documentation"
-#: C/index.docbook:687(note/para)
+#. (itstool) path: note/para
+#: C/index.docbook:680
msgid ""
"In the past most documentation had to be filled into files residing inside "
"the <filename>tmpl</filename> directory. This has the disadvantages that the "
"fichiers avaient tendance à provoquer des conflits avec les systèmes de "
"gestion de versions."
-#: C/index.docbook:693(note/para)
+#. (itstool) path: note/para
+#: C/index.docbook:686
msgid ""
"The avoid the aforementioned problems we suggest putting the documentation "
"inside the sources. This manual will only describe this way of documenting "
"Pour éviter ces problèmes, il est conseillé de placer la documentation dans "
"le code source. Ce manuel ne décrit que cette manière de documenter du code."
-#: C/index.docbook:704(example/title) C/index.docbook:723(example/title)
+#. (itstool) path: example/title
+#: C/index.docbook:697 C/index.docbook:723
msgid "GTK-Doc comment block"
msgstr "Bloc de commentaire GTK-Doc"
-#: C/index.docbook:705(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:698
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "#ifndef __GTK_DOC_IGNORE__\n"
+#| "/* unparseable code here */\n"
+#| "#endif\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"#ifndef __GTK_DOC_IGNORE__\n"
"/* unparseable code here */\n"
"#endif\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"#ifndef __GTK_DOC_IGNORE__\n"
"/* unparseable code here */\n"
"#endif\n"
-"\n"
-" "
-#: C/index.docbook:700(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:693
+#, fuzzy
+#| msgid ""
+#| "The scanner can handle the majority of c headers fine. In the case of "
+#| "receiving warnings from the scanner that look like a special case, one "
+#| "can hint GTK-Doc to skip over them. <_:example-1/>"
msgid ""
-"The scanner can handle the majority of c headers fine. In the case of "
+"The scanner can handle the majority of C headers fine. In the case of "
"receiving warnings from the scanner that look like a special case, one can "
"hint GTK-Doc to skip over them. <_:example-1/>"
msgstr ""
"l'air d'être des cas spéciaux, vous pouvez indiquer à GTK-Doc de les passer. "
"<_:example-1/>"
-#: C/index.docbook:718(sect1/title)
+#. (itstool) path: note/title
+#: C/index.docbook:707
+#| msgid "Dedications"
+msgid "Limitations"
+msgstr "Limitations"
+
+#. (itstool) path: note/para
+#: C/index.docbook:708
+msgid ""
+"Note, that GTK-Doc's supports <code>#ifndef(__GTK_DOC_IGNORE__)</code> but "
+"not <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:718
msgid "Documentation comments"
msgstr "Commentaires de documentation"
-#: C/index.docbook:724(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:724
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "/**\n"
+#| " * identifier:\n"
+#| " * documentation ...\n"
+#| " */\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"/**\n"
" * identifier:\n"
" * documentation ...\n"
" */\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"/**\n"
" * identifier:\n"
" * documentation ...\n"
" */\n"
-"\n"
-" "
-#: C/index.docbook:720(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:720
msgid ""
"A multiline comment that starts with an additional '*' marks a documentation "
"block that will be processed by the GTK-Doc tools. <_:example-1/>"
"indique un bloc de documentation qui sera traité par les outils GTK-Doc. <_:"
"example-1/>"
-#: C/index.docbook:735(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:733
msgid ""
"The 'identifier' is one line with the name of the item the comment is "
"related to. The syntax differs a little depending on the item. (TODO add "
"fonction de l'élément. (À FAIRE : ajouter un tableau montrant les "
"identifiants)"
-#: C/index.docbook:741(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:739
+#, fuzzy
+#| msgid ""
+#| "The 'documentation' block is also different for each symbol type. Symbol "
+#| "types that get parameters such as functions or macros have the parameter "
+#| "description first followed by a blank line (just a '*'). Afterwards "
+#| "follows the detailed description. All lines (outside program- listings "
+#| "and CDATA sections) just containing a ' *' (blank-asterisk) are converted "
+#| "to paragraph breaks. If you don't want a paragraph break, change that "
+#| "into ' * ' (blank-asterisk-blank-blank). This is useful in preformatted "
+#| "text (code listings)."
msgid ""
"The 'documentation' block is also different for each symbol type. Symbol "
"types that get parameters such as functions or macros have the parameter "
"description first followed by a blank line (just a '*'). Afterwards follows "
-"the detailed description. All lines (outside program- listings and CDATA "
+"the detailed description. All lines (outside program listings and CDATA "
"sections) just containing a ' *' (blank-asterisk) are converted to paragraph "
"breaks. If you don't want a paragraph break, change that into ' * ' (blank-"
"asterisk-blank-blank). This is useful in preformatted text (code listings)."
"paragraphe. Si vous ne désirez pas de saut de paragraphe, modifiez-les en "
"« * » (espace-astérisque-espace-espace)."
-#: C/index.docbook:758(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:756
msgid ""
"What it is: The name for a class or function can sometimes be misleading for "
"people coming from a different background."
"Ce que c'est : le nom d'une classe ou d'une fonction peut parfois être "
"trompeur pour les personnes habituées à d'autres environnements."
-#: C/index.docbook:764(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:762
msgid ""
"What it does: Tell about common uses. Put it in relation with the other API."
msgstr ""
"Ce qu'il fait : indiquer les usages courants. À mettre en relation avec les "
"autres API."
-#: C/index.docbook:754(tip/para)
+#. (itstool) path: tip/para
+#: C/index.docbook:752
msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>"
msgstr ""
"En documentant le code, deux aspects doivent être abordés : <_:"
"itemizedlist-1/>"
-#: C/index.docbook:779(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:777
msgid "Use function() to refer to functions or macros which take arguments."
msgstr ""
"Utilisez fonction() pour vous référer à des fonctions ou des macros qui "
"prennent des arguments."
-#: C/index.docbook:784(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:782
msgid ""
"Use @param to refer to parameters. Also use this when referring to "
"parameters of other functions, related to the one being described."
"Utilisez @paramètre pour vous référer aux paramètres. Utilisez-le aussi pour "
"les paramètres d'autres fonctions, en relation avec celle décrite."
-#: C/index.docbook:790(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:788
msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS."
msgstr ""
"Utilisez %constante pour vous référer à une constante, par ex. : "
"%MA_CONSTANTE."
-#: C/index.docbook:795(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:793
msgid ""
"Use #symbol to refer to other types of symbol, e.g. structs and enums and "
"macros which don't take arguments."
"Utilisez #symbole pour vous référer à d'autres types de symbole. Par exemple "
"des structures, énumérations ou macros qui ne prennent pas d'arguments."
-#: C/index.docbook:801(listitem/para)
-msgid "Use #Object::signal to refer to a GObject signal"
+#. (itstool) path: listitem/para
+#: C/index.docbook:799
+#, fuzzy
+#| msgid "Use #Object::signal to refer to a GObject signal"
+msgid "Use #Object::signal to refer to a GObject signal."
msgstr "Utilisez #Objet::signal pour vous référer à un signal GObject."
-#: C/index.docbook:806(listitem/para)
-msgid "Use #Object:property to refer to a GObject property"
+#. (itstool) path: listitem/para
+#: C/index.docbook:804
+#, fuzzy
+#| msgid "Use #Object:property to refer to a GObject property"
+msgid "Use #Object:property to refer to a GObject property."
msgstr "Utilisez #Objet::propriété pour vous référer à une propriété GObject."
-#: C/index.docbook:811(listitem/para)
-msgid "Use #Struct.field to refer to a field inside a structure."
+#. (itstool) path: listitem/para
+#: C/index.docbook:809
+#, fuzzy
+#| msgid "Use #Struct.field to refer to a field inside a structure."
+msgid ""
+"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
+"foo_bar() to refer to a vmethod."
msgstr "Utilisez #Structure.champ pour vous référer au champ d'une stucture."
-#: C/index.docbook:773(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:771
msgid ""
"One advantage of hyper-text over plain-text is the ability to have links in "
"the document. Writing the correct markup for a link can be tedious though. "
"balisage d'un lien peut être fastidieux. GTK-Doc fournit plusieurs "
"raccourcis utiles pour vous aider. <_:itemizedlist-1/>"
-#: C/index.docbook:819(tip/para)
+#. (itstool) path: tip/para
+#: C/index.docbook:818
msgid ""
"If you need to use the special characters '<', '>', '()', '@', '%', or "
"'#' in your documentation without GTK-Doc changing them you can use the XML "
"gt; », « &lpar; », « &rpar; », « &commat; », « &percnt; », "
"« &num; » ou les échapper en les précédant d'un antislash « \\ »."
-#: C/index.docbook:828(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:827
msgid ""
-"DocBook can do more than just links. One can also have lists, tables and "
-"examples. To enable the usage of docbook SGML/XML tags inside doc-comments "
-"you need to have <option>--xml-mode</option> or <option>--sgml-mode</option> "
-"in the variable <symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</"
+"DocBook can do more than just links. One can also have lists, examples, "
+"headings, and images. As of version 1.20, the preferred way is to use a "
+"subset of the basic text formatting syntax called <ulink url=\"http://"
+"daringfireball.net/projects/markdown/\">Markdown</ulink>. On older GTK-Doc "
+"versions any documentation that includes Markdown will be rendered as is. "
+"For example, list items will appear as lines starting with a dash."
+msgstr ""
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:838
+msgid ""
+"While markdown is now preferred one can mix both. One limitation here is "
+"that one can use docbook xml within markdown, but markdown within docbook "
+"xml is not supported."
+msgstr ""
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:844
+#, fuzzy
+#| msgid ""
+#| "DocBook can do more than just links. One can also have lists, tables and "
+#| "examples. To enable the usage of docbook SGML/XML tags inside doc-"
+#| "comments you need to have <option>--xml-mode</option> or <option>--sgml-"
+#| "mode</option> in the variable <symbol>MKDB_OPTIONS</symbol> inside "
+#| "<filename>Makefile.am</filename>."
+msgid ""
+"In older GTK-Doc releases, if you need support for additional formatting, "
+"you would need to enable the usage of docbook XML tags inside doc-comments "
+"by putting <option>--xml-mode</option> (or <option>--sgml-mode</option>) in "
+"the variable <symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</"
"filename>."
msgstr ""
"DocBook peut faire plus que des liens. Il peut aussi générer des listes, des "
"variable <symbol>MKDB_OPTIONS</symbol> du fichier <filename>Makefile.am</"
"filename>."
-#: C/index.docbook:842(example/title)
-msgid "GTK-Doc comment block using markdown"
+#. (itstool) path: example/title
+#: C/index.docbook:853
+#, fuzzy
+#| msgid "GTK-Doc comment block using markdown"
+msgid "GTK-Doc comment block using Markdown"
msgstr "Bloc de commentaire GTK-Doc utilisant la syntaxe markdown"
-#: C/index.docbook:843(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:854
#, no-wrap
msgid ""
"\n"
-"\n"
"/**\n"
" * identifier:\n"
" *\n"
-" * documentation ...\n"
+" * documentation paragraph ...\n"
" *\n"
-" * # Sub heading #\n"
+" * # Sub Heading #\n"
+" *\n"
+" * ## Second Sub Heading\n"
+" *\n"
+" * # Sub Heading With a Link Anchor # {#heading-two}\n"
" *\n"
" * more documentation:\n"
+" *\n"
" * - list item 1\n"
+" *\n"
+" * Paragraph inside a list item.\n"
+" *\n"
" * - list item 2\n"
" *\n"
-" * Even more docs.\n"
-" */\n"
-"\n"
-" "
-msgstr ""
-"\n"
-"\n"
-"/**\n"
-" * identifier:\n"
+" * 1. numbered list item\n"
" *\n"
-" * documentation ...\n"
+" * 2. another numbered list item\n"
" *\n"
-" * # Sub heading #\n"
+" * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)\n"
" *\n"
-" * more documentation:\n"
-" * - list item 1\n"
-" * - list item 2\n"
+" * \n"
+" *\n"
+" * [A link to the heading anchor above][heading-two]\n"
" *\n"
-" * Even more docs.\n"
+" * A C-language example:\n"
+" * |[<!-- language=\"C\" -->\n"
+" * GtkWidget *label = gtk_label_new (\"Gorgeous!\");\n"
+" * ]|\n"
" */\n"
-"\n"
-" "
+msgstr ""
-#: C/index.docbook:836(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:893
msgid ""
-"Since GTK-Doc-1.18 the tool supports a subset or the <ulink url=\"http://"
-"daringfireball.net/projects/markdown/\">markdown language</ulink>. One can "
-"use it for sub-headings and simple itemized lists. On older GTK-Doc versions "
-"the content will be rendered as it (the list items will appear in one line "
-"separated by dashes). <_:example-1/>"
+"More examples of what markdown tags are supported can be found in the <ulink "
+"url=\"https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown"
+"\">GTK+ Documentation Markdown Syntax Reference</ulink>."
msgstr ""
-"À partir de GTK-Doc 1.18, il est possible d'utiliser un sous-ensemble de la "
-"<ulink url=\"http://daringfireball.net/projects/markdown/\">syntaxe "
-"markdown</ulink>. On peut l'utiliser pour les sous-titres et les listes à "
-"puces simples. Dans des versions plus anciennes de GTK-Doc, le contenu est "
-"affiché tel quel (les éléments d'une liste sont affichés sur une seule "
-"ligne, séparés par des tirets). <_:example-1/>"
-#: C/index.docbook:864(tip/para)
+#. (itstool) path: tip/para
+#: C/index.docbook:899
msgid ""
"As already mentioned earlier GTK-Doc is for documenting public API. Thus one "
"cannot write documentation for static symbols. Nevertheless it is good to "
"d'ajouter un « * » dans le bloc de commentaires et d'ajouter le nom du "
"symbole à la bonne place à l'intérieur du fichier des sections."
-#: C/index.docbook:878(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:913
msgid "Documenting sections"
msgstr "Documentation des sections"
-#: C/index.docbook:880(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:915
msgid ""
"Each section of the documentation contains information about one class or "
"module. To introduce the component one can write a section block. The short "
"de section. La description courte est également utilisée dans la table des "
"matières. Tous les @champs sont facultatifs."
-#: C/index.docbook:888(example/title)
+#. (itstool) path: example/title
+#: C/index.docbook:923
msgid "Section comment block"
msgstr "Bloc de commentaires de section"
-#: C/index.docbook:889(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:924
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "/**\n"
+#| " * SECTION:meepapp\n"
+#| " * @short_description: the application class\n"
+#| " * @title: Meep application\n"
+#| " * @section_id:\n"
+#| " * @see_also: #MeepSettings\n"
+#| " * @stability: Stable\n"
+#| " * @include: meep/app.h\n"
+#| " * @image: application.png\n"
+#| " *\n"
+#| " * The application class handles ...\n"
+#| " */\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"/**\n"
" * SECTION:meepapp\n"
" * @short_description: the application class\n"
" *\n"
" * The application class handles ...\n"
" */\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"/**\n"
" * SECTION:meepapp\n"
" * @short_description: the application class\n"
" *\n"
" * The application class handles ...\n"
" */\n"
-"\n"
-" "
-#: C/index.docbook:910(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:943
msgid "SECTION:<name>"
msgstr "SECTION:<nom>"
-#: C/index.docbook:912(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:945
+#, fuzzy
+#| msgid ""
+#| "The name links the section documentation to the respective part in the "
+#| "<filename><package>-sections.txt</filename> file. The name give "
+#| "here should match the <FILE> tag in the <filename><package>-"
+#| "sections.txt</filename> file."
msgid ""
"The name links the section documentation to the respective part in the "
-"<filename><package>-sections.txt</filename> file. The name give here "
+"<filename><package>-sections.txt</filename> file. The name given here "
"should match the <FILE> tag in the <filename><package>-sections."
"txt</filename> file."
msgstr ""
"doit correspondre à la balise <FILE> du fichier <filename><"
"package>-sections.txt</filename>."
-#: C/index.docbook:921(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:954
msgid "@short_description"
msgstr "@short_description"
-#: C/index.docbook:923(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:956
msgid ""
"A one line description of the section, that later will appear after the "
"links in the TOC and at the top of the section page."
"Une description de la section en une seule ligne, elle apparaîtra derrière "
"les liens dans la table des matières et au début de la page de la section."
-#: C/index.docbook:930(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:963
msgid "@title"
msgstr "@title"
-#: C/index.docbook:932(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:965
msgid ""
"The section title defaults to <name> from the SECTION declaration. It "
"can be overridden with the @title field."
"Par défaut, la section titre est celle de la déclaration SECTION: <"
"nom>. Elle peut être modifiée grâce au champ @title."
-#: C/index.docbook:939(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:972
msgid "@section_id"
msgstr "@section_id"
-#: C/index.docbook:941(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:974
msgid ""
"Overrides the use of title as a section identifier. For GObjects the <"
"title> is used as a section_id and for other sections it is <"
"GObjects, <title> est utilisé à la place de section_id et pour les "
"autres sections, c'est <MODULE>-<title>."
-#: C/index.docbook:949(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:982
msgid "@see_also"
msgstr "@see_also"
-#: C/index.docbook:951(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:984
msgid "A list of symbols that are related to this section."
msgstr "Une liste de symboles qui ont un lien avec cette section."
-#: C/index.docbook:957(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:990
msgid "@stability"
msgstr "@stability"
-#: C/index.docbook:964(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:997
msgid ""
"Stable - The intention of a Stable interface is to enable arbitrary third "
"parties to develop applications to these interfaces, release them, and have "
"les modifications incompatibles doivent être rares et être sérieusement "
"justifiées."
-#: C/index.docbook:976(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1009
msgid ""
"Unstable - Unstable interfaces are experimental or transitional. They are "
"typically used to give outside developers early access to new or rapidly "
"de la compatibilité binaire ou de celle des sources, d'une version mineure à "
"l'autre."
-#: C/index.docbook:988(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1021
msgid ""
"Private - An interface that can be used within the GNOME stack itself, but "
"that is not documented for end-users. Such functions should only be used in "
"type de fonctions ne doit être utilisé que dans des cas spécifiques et "
"documentés."
-#: C/index.docbook:997(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1030
msgid ""
"Internal - An interface that is internal to a module and does not require "
"end-user documentation. Functions that are undocumented are assumed to be "
"nécessite pas de documentation pour l'utilisateur final. Les fonctions non "
"documentées sont considérées comme internes."
-#: C/index.docbook:959(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:992
+#, fuzzy
+#| msgid ""
+#| "A informal description of the stability level this API has. We recommend "
+#| "the use of one of these terms: <_:itemizedlist-1/>"
msgid ""
-"A informal description of the stability level this API has. We recommend the "
-"use of one of these terms: <_:itemizedlist-1/>"
+"An informal description of the stability level this API has. We recommend "
+"the use of one of these terms: <_:itemizedlist-1/>"
msgstr ""
"Une description informelle du niveau de stabilité de cet API. Il est "
"recommandé d'utiliser l'un de ces termes : <_:itemizedlist-1/>"
-#: C/index.docbook:1009(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1042
msgid "@include"
msgstr "@include"
-#: C/index.docbook:1011(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1044
msgid ""
"The <literal>#include</literal> files to show in the section synopsis (a "
"comma separated list), overriding the global value from the <link linkend="
"valeur globale du <link linkend=\"metafiles_sections\">fichier de section</"
"link> ou de la ligne de commande. Cet élément est facultatif."
-#: C/index.docbook:1020(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1053
msgid "@image"
msgstr "@image"
-#: C/index.docbook:1022(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1055
msgid ""
"The image to display at the top of the reference page for this section. This "
"will often be some sort of a diagram to illustrate the visual appearance of "
"d'une classe ou un diagramme de ses relations avec d'autres classes. Cet "
"élément est facultatif."
-#: C/index.docbook:1033(tip/para)
+#. (itstool) path: tip/para
+#: C/index.docbook:1066
msgid ""
"To avoid unnecessary recompilation after doc-changes put the section docs "
"into the c-source where possible."
"documentation, placez la documentation de section dans les fichiers sources "
"C, lorsque cela est possible."
-#: C/index.docbook:1042(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:1075
msgid "Documenting symbols"
msgstr "Documentation des symboles"
-#: C/index.docbook:1044(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1077
msgid ""
"Each symbol (function, macro, struct, enum, signal and property) is "
"documented in a separate block. The block is best placed close to the "
"sources C et les macros et les structures et les énumérations le sont dans "
"le fichier d'en-tête."
-#: C/index.docbook:1052(sect2/title) C/index.docbook:1081(example/title)
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1085 C/index.docbook:1151
msgid "General tags"
msgstr "Étiquettes générales"
-#: C/index.docbook:1054(sect2/para)
+#. (itstool) path: sect2/para
+#: C/index.docbook:1087
msgid ""
"You can add versioning information to all documentation elements to tell "
"when an API was introduced, or when it was deprecated."
"documentation pour indiquer quand l'API a été introduite ou quand elle est "
"devenue obsolète."
-#: C/index.docbook:1059(variablelist/title)
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1092
msgid "Versioning Tags"
msgstr "Étiquettes de version"
-#: C/index.docbook:1060(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1093
msgid "Since:"
msgstr "« Since »:"
-#: C/index.docbook:1062(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1095
msgid "Description since which version of the code the API is available."
msgstr ""
"Texte indiquant depuis quelle version du code cette API est disponible."
-#: C/index.docbook:1067(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1100
msgid "Deprecated:"
msgstr "« Deprecated » :"
-#: C/index.docbook:1069(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1102
msgid ""
"Paragraph denoting that this function should no be used anymore. The "
"description should point the reader to the new API."
"Texte indiquant que cette fonction ne doit plus être utilisée. La "
"description doit rediriger le lecteur vers la nouvelle API."
-#: C/index.docbook:1077(sect2/para)
-msgid "(FIXME : Stability information)"
-msgstr "(FIXME : informations de stabilité)"
+#. (itstool) path: sect2/para
+#: C/index.docbook:1110
+#, fuzzy
+#| msgid ""
+#| "You can add versioning information to all documentation elements to tell "
+#| "when an API was introduced, or when it was deprecated."
+msgid ""
+"You can also add stability information to all documentation elements to "
+"indicate whether API stability is guaranteed for them for all future minor "
+"releases of the project."
+msgstr ""
+"Vous pouvez ajouter des informations de version à tous les éléments de "
+"documentation pour indiquer quand l'API a été introduite ou quand elle est "
+"devenue obsolète."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1116
+msgid ""
+"The default stability level for all documentation elements can be set by "
+"passing the <option>--default-stability</option> argument to "
+"<application>gtkdoc-mkdb</application> with one of the values below."
+msgstr ""
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1122
+#, fuzzy
+#| msgid "@stability"
+msgid "Stability Tags"
+msgstr "@stability"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1123
+msgid "Stability: Stable"
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1125
+msgid ""
+"Mark the element as stable. This is for public APIs which are guaranteed to "
+"remain stable for all future minor releases of the project."
+msgstr ""
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1132
+msgid "Stability: Unstable"
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1134
+msgid ""
+"Mark the element as unstable. This is for public APIs which are released as "
+"a preview before being stabilised."
+msgstr ""
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1140
+msgid "Stability: Private"
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1142
+msgid ""
+"Mark the element as private. This is for interfaces which can be used by "
+"tightly coupled modules, but not by arbitrary third parties."
+msgstr ""
-#: C/index.docbook:1082(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1152
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "/**\n"
+#| " * foo_get_bar:\n"
+#| " * @foo: some foo\n"
+#| " *\n"
+#| " * Retrieves @foo's bar.\n"
+#| " *\n"
+#| " * Returns: @foo's bar\n"
+#| " *\n"
+#| " * Since: 2.6\n"
+#| " * Deprecated: 2.12: Use foo_baz_get_bar() instead.\n"
+#| " **/\n"
+#| "Bar *\n"
+#| "foo_get_bar(Foo *foo)\n"
+#| "{\n"
+#| "...\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"/**\n"
" * foo_get_bar:\n"
" * @foo: some foo\n"
" *\n"
" * Since: 2.6\n"
" * Deprecated: 2.12: Use foo_baz_get_bar() instead.\n"
-" **/\n"
+" */\n"
"Bar *\n"
"foo_get_bar(Foo *foo)\n"
"{\n"
"...\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"/**\n"
" * foo_get_bar:\n"
" * @foo: some foo\n"
" *\n"
" * Since: 2.6\n"
" * Deprecated: 2.12: Use foo_baz_get_bar() instead.\n"
-" **/\n"
+" */\n"
"Bar *\n"
"foo_get_bar(Foo *foo)\n"
"{\n"
"...\n"
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1172 C/index.docbook:1182
+#| msgid "Installation"
+msgid "Annotations"
+msgstr "Annotations"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1174
+msgid ""
+"Documentation blocks can contain annotation-tags. These tags will be "
+"rendered with tooltips describing their meaning. The tags are used by "
+"gobject-introspection to generate language bindings. A detailed list of the "
+"supported tags can be found on <ulink url=\"http://live.gnome.org/"
+"GObjectIntrospection/Annotations\" type=\"http\">the wiki</ulink>."
+msgstr ""
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1183
+#, no-wrap
+msgid ""
"\n"
-" "
+"/**\n"
+" * foo_get_bar: (annotation)\n"
+" * @foo: (annotation): some foo\n"
+" *\n"
+" * Retrieves @foo's bar.\n"
+" *\n"
+" * Returns: (annotation): @foo's bar\n"
+" */\n"
+"...\n"
+"/**\n"
+" * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)\n"
+" * (and another annotation)\n"
+" * @foo: (annotation) (another annotation): some foo\n"
+" *\n"
+" * Sets bar on @foo.\n"
+" */\n"
+msgstr ""
-#: C/index.docbook:1104(sect2/title) C/index.docbook:1140(example/title)
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1204 C/index.docbook:1233
msgid "Function comment block"
msgstr "Bloc de commentaires pour les fonctions"
-#: C/index.docbook:1110(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1210
msgid ""
"Document whether returned objects, lists, strings, etc, should be freed/"
"unrefed/released."
"d'indiquer si les objets, listes, chaînes, etc. retournés doivent être freed/"
"unfreed/released,"
-#: C/index.docbook:1116(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1216
msgid "Document whether parameters can be NULL, and what happens if they are."
msgstr ""
"d'indiquer si les paramètres peuvent être NULL et ce qui se passe dans ce "
-"cas,"
+"cas."
-#: C/index.docbook:1121(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1221
msgid ""
"Mention interesting pre-conditions and post-conditions where appropriate."
msgstr ""
-"de mentionner les pré-conditions et post-conditions intéressantes si "
-"nécessaire."
+"Mentionner les pré-conditions et post-conditions intéressantes si nécessaire."
-#: C/index.docbook:1106(sect2/para) C/index.docbook:1203(sect2/para)
+#. (itstool) path: sect2/para
+#: C/index.docbook:1206 C/index.docbook:1292
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "N'oubliez pas : <_:itemizedlist-1/>"
-#: C/index.docbook:1128(sect2/para)
+#. (itstool) path: sect2/para
+#: C/index.docbook:1228
msgid ""
"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
"private. They are treated like static functions."
"GTK-Doc considère que tous les symboles (macros, fonctions) commençant par "
"« _ » sont privés. Ils sont traités comme des fonctions statiques."
-#: C/index.docbook:1133(sect2/para)
-msgid ""
-"Also, take a look at gobject introspection annotation tags: http://live."
-"gnome.org/GObjectIntrospection/Annotations"
-msgstr ""
-"Jetez un coup d'œil aux étiquettes d'annotation de l'introspection gobject : "
-"http://live.gnome.org/GObjectIntrospection/Annotations"
-
-#: C/index.docbook:1141(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1234
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "/**\n"
+#| " * function_name:\n"
+#| " * @par1: description of parameter 1. These can extend over more than\n"
+#| " * one line.\n"
+#| " * @par2: description of parameter 2\n"
+#| " * @...: a %NULL-terminated list of bars\n"
+#| " *\n"
+#| " * The function description goes here. You can use @par1 to refer to parameters\n"
+#| " * so that they are highlighted in the output. You can also use %constant\n"
+#| " * for constants, function_name2() for functions and #GtkWidget for links to\n"
+#| " * other declarations (which may be documented elsewhere).\n"
+#| " *\n"
+#| " * Returns: an integer.\n"
+#| " *\n"
+#| " * Since: 2.2\n"
+#| " * Deprecated: 2.18: Use other_function() instead.\n"
+#| " */\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"/**\n"
" * function_name:\n"
" * @par1: description of parameter 1. These can extend over more than\n"
" * Since: 2.2\n"
" * Deprecated: 2.18: Use other_function() instead.\n"
" */\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"/**\n"
" * function_name:\n"
" * @par1: description of parameter 1. These can extend over more than\n"
" * Since: 2.2\n"
" * Deprecated: 2.18: Use other_function() instead.\n"
" */\n"
-"\n"
-" "
-#: C/index.docbook:1164(variablelist/title)
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1255
msgid "Function tags"
msgstr "Étiquettes de fonction"
-#: C/index.docbook:1165(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1256 C/index.docbook:1463
msgid "Returns:"
msgstr "« Returns » :"
-#: C/index.docbook:1167(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1258
msgid "Paragraph describing the returned result."
msgstr "Paragraphe décrivant le résultat retourné."
-#: C/index.docbook:1172(varlistentry/term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1263
msgid "@...:"
msgstr "@...:"
-#: C/index.docbook:1174(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1265
msgid ""
"In case the function has variadic arguments, you should use this tag "
"(@Varargs: does also work for historic reasons)."
"cette étiquette (@Varargs : peut également être utilisé pour des raisons "
"historiques)."
-#: C/index.docbook:1184(sect2/title) C/index.docbook:1186(example/title)
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1275 C/index.docbook:1277
msgid "Property comment block"
msgstr "Bloc de commentaires pour les propriétés"
-#: C/index.docbook:1187(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1278
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "/**\n"
+#| " * SomeWidget:some-property:\n"
+#| " *\n"
+#| " * Here you can document a property.\n"
+#| " */\n"
+#| "g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"/**\n"
" * SomeWidget:some-property:\n"
" *\n"
" * Here you can document a property.\n"
" */\n"
"g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"/**\n"
" * SomeWidget:some-property:\n"
" *\n"
" * Here you can document a property.\n"
" */\n"
"g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);\n"
-"\n"
-" "
-#: C/index.docbook:1201(sect2/title) C/index.docbook:1220(example/title)
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1290 C/index.docbook:1309
msgid "Signal comment block"
msgstr "Bloc de commentaires pour les signaux"
-#: C/index.docbook:1207(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1296
msgid ""
"Document when the signal is emitted and whether it is emitted before or "
"after other signals."
msgstr ""
-"d'indiquer quand le signal est émis et s'il est émis avant ou après d'autres "
-"signaux,"
+"Documenter lorsque le signal est émis et s'il est émis avant ou après "
+"d'autres signaux,"
-#: C/index.docbook:1213(listitem/para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:1302
msgid "Document what an application might do in the signal handler."
msgstr ""
-"d'indiquer ce qu'une application peut faire dans le gestionnaire du signal."
+"Documenter ce qu'une application pourrait faire dans le gestionnaire du "
+"signal."
-#: C/index.docbook:1221(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1310
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "/**\n"
+#| " * FooWidget::foobarized:\n"
+#| " * @widget: the widget that received the signal\n"
+#| " * @foo: some foo\n"
+#| " * @bar: some bar\n"
+#| " *\n"
+#| " * The ::foobarized signal is emitted each time someone tries to foobarize @widget.\n"
+#| " */\n"
+#| "foo_signals[FOOBARIZE] =\n"
+#| " g_signal_new (\"foobarize\",\n"
+#| " ...\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"/**\n"
" * FooWidget::foobarized:\n"
" * @widget: the widget that received the signal\n"
"foo_signals[FOOBARIZE] =\n"
" g_signal_new (\"foobarize\",\n"
" ...\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"/**\n"
" * FooWidget::foobarized:\n"
" * @widget: the widget that received the signal\n"
"foo_signals[FOOBARIZE] =\n"
" g_signal_new (\"foobarize\",\n"
" ...\n"
-"\n"
-" "
-#: C/index.docbook:1240(sect2/title) C/index.docbook:1241(example/title)
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1327 C/index.docbook:1328
msgid "Struct comment block"
msgstr "Bloc de commentaire pour les structures"
-#: C/index.docbook:1242(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1329
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "/**\n"
+#| " * FooWidget:\n"
+#| " * @bar: some #gboolean\n"
+#| " *\n"
+#| " * This is the best widget, ever.\n"
+#| " */\n"
+#| "typedef struct _FooWidget {\n"
+#| " /*< private >*/\n"
+#| " GtkWidget parent;\n"
+#| "\n"
+#| " /*< public >*/\n"
+#| " gboolean bar;\n"
+#| "} FooWidget;\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"/**\n"
" * FooWidget:\n"
" * @bar: some #gboolean\n"
" * This is the best widget, ever.\n"
" */\n"
"typedef struct _FooWidget {\n"
-" /*< private >*/\n"
-" GtkWidget parent;\n"
+" GtkWidget parent_instance;\n"
"\n"
-" /*< public >*/\n"
" gboolean bar;\n"
"} FooWidget;\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"/**\n"
" * FooWidget:\n"
" * @bar: some #gboolean\n"
" * This is the best widget, ever.\n"
" */\n"
"typedef struct _FooWidget {\n"
-" /*< private >*/\n"
-" GtkWidget parent;\n"
+" GtkWidget parent_instance;\n"
"\n"
-" /*< public >*/\n"
" gboolean bar;\n"
"} FooWidget;\n"
-"\n"
-" "
-#: C/index.docbook:1261(sect2/para)
+#. (itstool) path: sect2/para
+#: C/index.docbook:1344
msgid ""
"Use <code>/*< private >*/</code> before the private struct fields you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"privées que vous voulez cacher. Utilisez <code>/*< public >*/</code> "
"dans le cas contraire."
-#: C/index.docbook:1267(sect2/para)
+#. (itstool) path: sect2/para
+#: C/index.docbook:1350
+msgid ""
+"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" "
+"it will be considered private automatically and doesn't need to be mentioned "
+"in the comment block."
+msgstr ""
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1356
msgid ""
"Struct comment blocks can also be used for GObjects and GObjectClasses. It "
"is usually a good idea to add a comment block for a class, if it has "
"possède des champs publics. Le désavantage ici étant que cela crée deux "
"entrées d'index pour le même nom (la structure et la section)."
-#: C/index.docbook:1279(sect2/title) C/index.docbook:1280(example/title)
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1368 C/index.docbook:1369
msgid "Enum comment block"
msgstr "Bloc de commentaire pour les énumérations"
-#: C/index.docbook:1281(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1370
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "/**\n"
+#| " * Something:\n"
+#| " * @SOMETHING_FOO: something foo\n"
+#| " * @SOMETHING_BAR: something bar\n"
+#| " *\n"
+#| " * Enum values used for the thing, to specify the thing.\n"
+#| " *\n"
+#| " **/\n"
+#| "typedef enum {\n"
+#| " SOMETHING_FOO,\n"
+#| " SOMETHING_BAR,\n"
+#| " /*< private >*/\n"
+#| " SOMETHING_COUNT\n"
+#| "} Something;\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"/**\n"
" * Something:\n"
" * @SOMETHING_FOO: something foo\n"
" * @SOMETHING_BAR: something bar\n"
" *\n"
" * Enum values used for the thing, to specify the thing.\n"
-" *\n"
-" **/\n"
+" */\n"
"typedef enum {\n"
" SOMETHING_FOO,\n"
" SOMETHING_BAR,\n"
" /*< private >*/\n"
" SOMETHING_COUNT\n"
"} Something;\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"/**\n"
" * Something:\n"
" * @SOMETHING_FOO: something foo\n"
" * @SOMETHING_BAR: something bar\n"
" *\n"
" * Enum values used for the thing, to specify the thing.\n"
-" *\n"
-" **/\n"
+" */\n"
"typedef enum {\n"
" SOMETHING_FOO,\n"
" SOMETHING_BAR,\n"
" /*< private >*/\n"
" SOMETHING_COUNT\n"
"} Something;\n"
-"\n"
-" "
-#: C/index.docbook:1301(sect2/para)
+#. (itstool) path: sect2/para
+#: C/index.docbook:1387
msgid ""
"Use <code>/*< private >*/</code> before the private enum values you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"privées que vous voulez cacher. Utilisez <code>/*< public >*/</code> "
"dans le cas contraire."
-#: C/index.docbook:1311(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:1398
+#, fuzzy
+#| msgid "Setting up a skeleton documentation"
+msgid "Inline program documentation"
+msgstr "Mise en place du squelette de documentation"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1399
+msgid ""
+"You can document programs and their commandline interface using inline "
+"documentation."
+msgstr ""
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1405
+msgid "Tags"
+msgstr ""
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1407
+msgid "PROGRAM"
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1410
+msgid "Defines the start of a program documentation."
+msgstr ""
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1417
+#| msgid "@short_description"
+msgid "@short_description:"
+msgstr "@short_description:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1419
+msgid "Defines a short description of the program. (Optional)"
+msgstr ""
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1426
+msgid "@synopsis:"
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1428
+msgid ""
+"Defines the arguments, or list of arguments that the program can take. "
+"(Optional)"
+msgstr ""
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1436
+#| msgid "@see_also"
+msgid "@see_also:"
+msgstr "@see_also:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1438
+msgid "See Also manual page section. (Optional)"
+msgstr ""
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1445
+msgid "@arg:"
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1447
+msgid "Argument(s) passed to the program and their description. (Optional)"
+msgstr ""
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1454
+#| msgid "@short_description"
+msgid "Description:"
+msgstr "Description:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1456
+msgid "A longer description of the program."
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1465
+msgid "Specificy what value(s) the program returns. (Optional)"
+msgstr ""
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:1474
+msgid "Example of program documentation."
+msgstr ""
+
+#. (itstool) path: example/title
+#: C/index.docbook:1475
+msgid "Program documentation block"
+msgstr "Bloc de documentation programme"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1476
+#, no-wrap
+msgid ""
+"\n"
+"/**\n"
+" * PROGRAM:test-program\n"
+" * @short_description: A test program\n"
+" * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*\n"
+" * @see_also: test(1)\n"
+" * @--arg1 *arg*: set arg1 to *arg*\n"
+" * @--arg2 *arg*: set arg2 to *arg*\n"
+" * @-v, --version: Print the version number\n"
+" * @-h, --help: Print the help message\n"
+" *\n"
+" * Long description of program.\n"
+" *\n"
+" * Returns: Zero on success, non-zero on failure\n"
+" */\n"
+"int main(int argc, char *argv[])\n"
+"{\n"
+"\treturn 0;\n"
+"}\n"
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1502
msgid "Useful DocBook tags"
msgstr "Balises DocBook utiles"
-#: C/index.docbook:1313(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1504
msgid ""
"Here are some DocBook tags which are most useful when documenting the code."
msgstr ""
"Voici quelques balises DocBook très utiles pendant la conception de la "
"documentation d'un code."
-#: C/index.docbook:1322(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1513
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
-"\n"
-" "
-#: C/index.docbook:1318(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1509
msgid ""
"To link to another section in the GTK docs: <_:informalexample-1/> The "
"linkend is the SGML/XML id on the top item of the page you want to link to. "
"caractères de soulignement sont convertis en « - » pour être conforme au "
"SGML/XML."
-#: C/index.docbook:1337(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1526
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<function>...</function>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<function>...</function>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<function>...</function>\n"
-"\n"
-" "
-#: C/index.docbook:1334(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1523
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
"Pour faire référence à une fonction externe comme, par exemple, à une "
"fonction C standard : <_:informalexample-1/>"
-#: C/index.docbook:1348(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1535
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<example>\n"
+#| " <title>Using a GHashTable.</title>\n"
+#| " <programlisting>\n"
+#| " ...\n"
+#| " </programlisting>\n"
+#| "</example>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<example>\n"
" <title>Using a GHashTable.</title>\n"
" <programlisting>\n"
" ...\n"
" </programlisting>\n"
"</example>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<example>\n"
" <title>Using a GHashTable.</title>\n"
" <programlisting>\n"
" ...\n"
" </programlisting>\n"
"</example>\n"
-"\n"
-" "
-#: C/index.docbook:1361(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1546
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<informalexample>\n"
+#| " <programlisting>\n"
+#| " ...\n"
+#| " </programlisting>\n"
+#| "</informalexample>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<informalexample>\n"
" <programlisting>\n"
" ...\n"
" </programlisting>\n"
"</informalexample>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<informalexample>\n"
" <programlisting>\n"
" ...\n"
" </programlisting>\n"
"</informalexample>\n"
-"\n"
-" "
-#: C/index.docbook:1345(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1532
msgid ""
"To include example code: <_:informalexample-1/> or possibly this, for very "
"short code fragments which don't need a title: <_:informalexample-2/> For "
"informalexample-2/> Pour ces derniers, GTK-Doc prend également en charge une "
"abréviation : |[ ... ]|"
-#: C/index.docbook:1382(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1565
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<itemizedlist>\n"
+#| " <listitem>\n"
+#| " <para>\n"
+#| " ...\n"
+#| " </para>\n"
+#| " </listitem>\n"
+#| " <listitem>\n"
+#| " <para>\n"
+#| " ...\n"
+#| " </para>\n"
+#| " </listitem>\n"
+#| "</itemizedlist>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<itemizedlist>\n"
" <listitem>\n"
" <para>\n"
" </para>\n"
" </listitem>\n"
"</itemizedlist>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<itemizedlist>\n"
" <listitem>\n"
" <para>\n"
" </para>\n"
" </listitem>\n"
"</itemizedlist>\n"
-"\n"
-" "
-#: C/index.docbook:1379(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1562
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Pour ajouter une liste à puces : <_:informalexample-1/>"
-#: C/index.docbook:1404(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1585
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<note>\n"
+#| " <para>\n"
+#| " Make sure you free the data after use.\n"
+#| " </para>\n"
+#| "</note>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<note>\n"
" <para>\n"
" Make sure you free the data after use.\n"
" </para>\n"
"</note>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<note>\n"
" <para>\n"
" Make sure you free the data after use.\n"
" </para>\n"
"</note>\n"
-"\n"
-" "
-#: C/index.docbook:1401(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1582
msgid ""
"To include a note which stands out from the text: <_:informalexample-1/>"
msgstr "Pour ajouter une note de bas de page : <_:informalexample-1/>"
-#: C/index.docbook:1419(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1598
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<type>unsigned char</type>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<type>unsigned char</type>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<type>unsigned char</type>\n"
-"\n"
-" "
-#: C/index.docbook:1416(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1595
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "Pour se référer à un type : <_:informalexample-1/>"
-#: C/index.docbook:1430(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1607
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<structname>XFontStruct</structname>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<structname>XFontStruct</structname>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<structname>XFontStruct</structname>\n"
-"\n"
-" "
-#: C/index.docbook:1427(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1604
msgid ""
"To refer to an external structure (not one described in the GTK docs): <_:"
"informalexample-1/>"
"Pour se référer à une structure externe (non décrite dans la documentation "
"GTK) : <_:informalexample-1/>"
-#: C/index.docbook:1441(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1616
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<structfield>len</structfield>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<structfield>len</structfield>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<structfield>len</structfield>\n"
-"\n"
-" "
-#: C/index.docbook:1438(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1613
msgid "To refer to a field of a structure: <_:informalexample-1/>"
msgstr "Pour se référer à un champ d'une structure : <_:informalexample-1/>"
-#: C/index.docbook:1452(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1625
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<classname>GtkWidget</classname>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<classname>GtkWidget</classname>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<classname>GtkWidget</classname>\n"
-"\n"
-" "
-#: C/index.docbook:1449(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1622
msgid ""
"To refer to a class name, we could possibly use: <_:informalexample-1/> but "
"you'll probably be using #GtkWidget instead (to automatically create a link "
"(pour créer automatiquement un lien vers la page GtkWidget - consultez <link "
"linkend=\"documenting_syntax\">les raccourcis</link>)."
-#: C/index.docbook:1465(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1636
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<emphasis>This is important</emphasis>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<emphasis>This is important</emphasis>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<emphasis>This is important</emphasis>\n"
-"\n"
-" "
-#: C/index.docbook:1462(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1633
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Pour mettre en évidence un texte : <_:informalexample-1/>"
-#: C/index.docbook:1476(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1645
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<filename>/home/user/documents</filename>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<filename>/home/user/documents</filename>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<filename>/home/user/documents</filename>\n"
-"\n"
-" "
-#: C/index.docbook:1473(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1642
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Pour les noms de fichiers : <_:informalexample-1/>"
-#: C/index.docbook:1487(informalexample/programlisting)
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1654
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
-"\n"
-" "
-#: C/index.docbook:1484(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1651
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "Pour se référer à des touches : <_:informalexample-1/>"
-#: C/index.docbook:1499(chapter/title)
+#. (itstool) path: chapter/title
+#: C/index.docbook:1664
msgid "Filling the extra files"
msgstr "Remplissage des fichiers supplémentaires"
-#: C/index.docbook:1501(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:1666
msgid ""
"There are a couple of extra files, that need to be maintained along with the "
"inline source code comments: <filename><package>.types</filename>, "
"package>.types</filename>, <filename><package>-docs.xml</filename> "
"(anciennement .sgml), <filename><package>-sections.txt</filename>."
-#: C/index.docbook:1510(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:1675
msgid "Editing the types file"
-msgstr "Édition du fichier « types »"
-
-#: C/index.docbook:1512(sect1/para)
-msgid ""
-"If your library or application includes GtkObjects/GObjects, you want their "
-"signals, arguments/parameters and position in the hierarchy to be shown in "
-"the documentation. All you need to do, is to list the "
-"<function>xxx_get_type</function> functions together with their include "
-"inside the <filename><package>.types</filename> file."
+msgstr "Édition des fichiers types"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1677
+#, fuzzy
+#| msgid ""
+#| "If your library or application includes GtkObjects/GObjects, you want "
+#| "their signals, arguments/parameters and position in the hierarchy to be "
+#| "shown in the documentation. All you need to do, is to list the "
+#| "<function>xxx_get_type</function> functions together with their include "
+#| "inside the <filename><package>.types</filename> file."
+msgid ""
+"If your library or application includes GObjects, you want their signals, "
+"arguments/parameters and position in the hierarchy to be shown in the "
+"documentation. All you need to do, is to list the <function>xxx_get_type</"
+"function> functions together with their include inside the <filename><"
+"package>.types</filename> file."
msgstr ""
"Si votre bibliothèque ou application contient des GtkObjects ou GObjects, "
"vous voudrez que leurs signaux, arguments/paramètres et position dans la "
"lister les fonctions <function>xxx_get_type</function> ainsi que leur "
"fichier inclus dans le fichier <filename><package>.types</filename>."
-#: C/index.docbook:1521(example/title)
+#. (itstool) path: example/title
+#: C/index.docbook:1686
msgid "Example types file snippet"
-msgstr "Extrait d'un exemple de fichier « types »"
+msgstr "Extrait d'un exemple de fichiers types"
-#: C/index.docbook:1522(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1687
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "#include <gtk/gtk.h>\n"
+#| "\n"
+#| "gtk_accel_label_get_type\n"
+#| "gtk_adjustment_get_type\n"
+#| "gtk_alignment_get_type\n"
+#| "gtk_arrow_get_type\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"#include <gtk/gtk.h>\n"
"\n"
"gtk_accel_label_get_type\n"
"gtk_adjustment_get_type\n"
"gtk_alignment_get_type\n"
"gtk_arrow_get_type\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"#include <gtk/gtk.h>\n"
"\n"
"gtk_accel_label_get_type\n"
"gtk_adjustment_get_type\n"
"gtk_alignment_get_type\n"
"gtk_arrow_get_type\n"
-"\n"
-" "
-#: C/index.docbook:1535(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1698
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"utilisez cette approche vous ne devriez pas distribuer le fichier « types », "
"ni l'avoir dans le système de gestion de versions."
-#: C/index.docbook:1544(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:1707
msgid "Editing the master document"
msgstr "Édition du document maître"
-#: C/index.docbook:1546(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1709
msgid ""
"GTK-Doc produces documentation in DocBook SGML/XML. When processing the "
"inline source comments, the GTK-Doc tools generate one documentation page "
"génèrent une page de documentation par classe ou par module dans un fichier "
"séparé. Le document maître les inclut et les place dans l'ordre."
-#: C/index.docbook:1553(sect1/para)
-msgid ""
-"While GTK-Doc creates a template master document for you, later run will not "
-"touch it again. This means that one can freely structure the documentation. "
-"That includes grouping pages and adding extra pages. GTK-Doc has now a test "
-"suite, where also the master-document is recreated from scratch. Its a good "
-"idea to look at this from time to time to see if there are some new goodies "
-"introduced there."
+#. (itstool) path: sect1/para
+#: C/index.docbook:1716
+#, fuzzy
+#| msgid ""
+#| "While GTK-Doc creates a template master document for you, later run will "
+#| "not touch it again. This means that one can freely structure the "
+#| "documentation. That includes grouping pages and adding extra pages. GTK-"
+#| "Doc has now a test suite, where also the master-document is recreated "
+#| "from scratch. Its a good idea to look at this from time to time to see if "
+#| "there are some new goodies introduced there."
+msgid ""
+"While GTK-Doc creates a template master document for you, later runs will "
+"not touch it again. This means that one can freely structure the "
+"documentation. That includes grouping pages and adding extra pages. GTK-Doc "
+"has now a test suite, where also the master-document is recreated from "
+"scratch. Its a good idea to look at this from time to time to see if there "
+"are some new goodies introduced there."
msgstr ""
"Une fois que GTK-Doc a créé un prototype de document maître pour vous, il ne "
"va plus y toucher par la suite. Vous pouvez ainsi structurer votre "
"regarder cela de temps en temps pour voir s'il n'y a pas des nouveautés "
"intéressantes."
-#: C/index.docbook:1563(tip/para)
+#. (itstool) path: tip/para
+#: C/index.docbook:1726
msgid ""
"Do not create tutorials as extra documents. Just write extra chapters. The "
"benefit of directly embedding the tutorial for your library into the API "
"plus, il y aura plus de chance que votre tutoriel soit mis à jour en même "
"temps que la bibliothèque."
-#: C/index.docbook:1572(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1735
msgid ""
"So what are the things to change inside the master document? For a start is "
"only a little. There are some placeholders (text in square brackets) there "
"commencer, très peu de choses. Il n'y a quelques paramètres substituables "
"(texte entre crochets) que vous devrez prendre en charge."
-#: C/index.docbook:1579(example/title)
+#. (itstool) path: example/title
+#: C/index.docbook:1742
msgid "Master document header"
msgstr "En-tête du document maître"
-#: C/index.docbook:1580(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1743
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "<bookinfo>\n"
+#| " <title>MODULENAME Reference Manual</title>\n"
+#| " <releaseinfo>\n"
+#| " for MODULENAME [VERSION]\n"
+#| " The latest version of this documentation can be found on-line at\n"
+#| " <ulink role=\"online-location\" url=\"http://[SERVER]/MODULENAME/index.html\">http://[SERVER]/MODULENAME/</ulink>.\n"
+#| " </releaseinfo>\n"
+#| "</bookinfo>\n"
+#| "\n"
+#| "<chapter>\n"
+#| " <title>[Insert title here]</title>\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"<bookinfo>\n"
" <title>MODULENAME Reference Manual</title>\n"
" <releaseinfo>\n"
"\n"
"<chapter>\n"
" <title>[Insert title here]</title>\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"<bookinfo>\n"
" <title>MODULENAME Reference Manual</title>\n"
" <releaseinfo>\n"
"\n"
"<chapter>\n"
" <title>[Insert title here]</title>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1759
+msgid ""
+"In addition a few option elements are created in commented form. You can "
+"review these and enable them as you like."
+msgstr ""
+
+#. (itstool) path: example/title
+#: C/index.docbook:1765
+msgid "Optional part in the master document"
+msgstr "Partie optionnelle dans le document maître"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1766
+#, no-wrap
+msgid ""
+"\n"
+" <!-- enable this when you use gobject introspection annotations\n"
+" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n"
+" -->\n"
+msgstr ""
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1774
+msgid ""
+"Finally you need to add new section whenever you introduce one. The <link "
+"linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> tool will remind "
+"you of newly generated xml files that are not yet included into the doc."
+msgstr ""
+
+#. (itstool) path: example/title
+#: C/index.docbook:1782 C/index.docbook:1817
+msgid "Including generated sections"
+msgstr ""
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1783
+#, no-wrap
+msgid ""
+"\n"
+" <chapter>\n"
+" <title>my library</title>\n"
+" <xi:include href=\"xml/object.xml\"/>\n"
+" ...\n"
+msgstr ""
"\n"
-" "
+" <chapter>\n"
+" <title>my library</title>\n"
+" <xi:include href=\"xml/object.xml\"/>\n"
+" ...\n"
-#: C/index.docbook:1601(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:1795
msgid "Editing the section file"
msgstr "Édition du fichier section"
-#: C/index.docbook:1603(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1797
msgid ""
"The section file is used to organise the documentation output by GTK-Doc. "
"Here one specifies which symbol belongs to which module or class and control "
"GTK-Doc. C'est ici qu'il faut indiquer quels symboles sont attachés à quels "
"modules ou classes et contrôler la visibilité (« public » ou « private »)."
-#: C/index.docbook:1609(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1803
+#, fuzzy
+#| msgid ""
+#| "The section file is a plain test file with xml like syntax (using tags). "
+#| "Blank lines are ignored and lines starting with a '#' are treated as "
+#| "comment lines."
msgid ""
-"The section file is a plain test file with xml like syntax (using tags). "
-"Blank lines are ignored and lines starting with a '#' are treated as comment "
-"lines."
+"The section file is a plain text file with tags delimiting sections. Blank "
+"lines are ignored and lines starting with a '#' are treated as comment lines."
msgstr ""
"Le fichier section est un fichier texte plat, avec une syntaxe type XML "
"(utilisant des balises). Les lignes blanches sont ignorées et celles "
"commençant par un « # » sont considérées comme des lignes de commentaires."
-#: C/index.docbook:1615(sect1/para)
+#. (itstool) path: note/para
+#: C/index.docbook:1810
+msgid ""
+"While the tags make the file look like xml, it is not. Please do not close "
+"tags like <SUBSECTION>."
+msgstr ""
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1818
+#, no-wrap
+msgid ""
+"\n"
+"<INCLUDE>libmeep/meep.h</INCLUDE>\n"
+"\n"
+"<SECTION>\n"
+"<FILE>meepapp</FILE>\n"
+"<TITLE>MeepApp</TITLE>\n"
+"MeepApp\n"
+"<SUBSECTION Standard>\n"
+"MEEP_APP\n"
+"...\n"
+"MeepAppClass\n"
+"meep_app_get_type\n"
+"</SECTION>\n"
+msgstr ""
+"\n"
+"<INCLUDE>libmeep/meep.h</INCLUDE>\n"
+"\n"
+"<SECTION>\n"
+"<FILE>meepapp</FILE>\n"
+"<TITLE>MeepApp</TITLE>\n"
+"MeepApp\n"
+"<SUBSECTION Standard>\n"
+"MEEP_APP\n"
+"...\n"
+"MeepAppClass\n"
+"meep_app_get_type\n"
+"</SECTION>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1835
+#, fuzzy
+#| msgid ""
+#| "The <FILE> ... </FILE> tag is used to specify the file name, "
+#| "without any suffix. For example, using '<FILE>gnome-config</"
+#| "FILE>' will result in the section declarations being output in the "
+#| "template file <filename>tmpl/gnome-config.sgml</filename>, which will be "
+#| "converted into the DocBook SGML/XML file <filename>sgml/gnome-config."
+#| "sgml</filename> or .DocBook XML file <filename>xml/gnome-config.xml</"
+#| "filename>. (The name of the html file is based on the module name and the "
+#| "section title, or for gobjects it is based on the gobjects class name "
+#| "converted to lower case)."
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"FILE>' will result in the section declarations being output in the "
"template file <filename>tmpl/gnome-config.sgml</filename>, which will be "
-"converted into the DocBook SGML/XML file <filename>sgml/gnome-config.sgml</"
-"filename> or .DocBook XML file <filename>xml/gnome-config.xml</filename>. "
-"(The name of the html file is based on the module name and the section "
-"title, or for gobjects it is based on the gobjects class name converted to "
+"converted into the DocBook XML file <filename>xml/gnome-config.sgml</"
+"filename> or the DocBook XML file <filename>xml/gnome-config.xml</filename>. "
+"(The name of the HTML file is based on the module name and the section "
+"title, or for GObjects it is based on the GObjects class name converted to "
"lower case)."
msgstr ""
"La balise <FILE> ... </FILE> est utilisée pour indiquer le nom "
"de la section, ou, pour les gobjects, sur le nom de la classe gobjects "
"converti en minuscule)."
-#: C/index.docbook:1627(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1847
msgid ""
"The <TITLE> ... </TITLE> tag is used to specify the title of the "
"section. It is only useful before the templates (if used) are initially "
"Elle est également obsolète si des commentaires de SECTION sont utilisés "
"dans les fichiers sources."
-#: C/index.docbook:1634(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:1854
+#, fuzzy
+#| msgid ""
+#| "You can group items in the section by using the <SUBSECTION> tag. "
+#| "Currently it outputs a blank line between subsections in the synopsis "
+#| "section. You can also use <SUBSECTION Standard> for standard "
+#| "GObject declarations (e.g. the functions like g_object_get_type and "
+#| "macros like G_OBJECT(), G_IS_OBJECT() etc.). Currently these are left out "
+#| "of the documentation. You can also use <SUBSECTION Private> for "
+#| "private declarations which will not be output (It is a handy way to avoid "
+#| "warning messages about unused declarations.). If your library contains "
+#| "private types which you don't want to appear in the object hierarchy and "
+#| "the list of implemented or required interfaces, add them to a Private "
+#| "subsection. Whether you would place GObject and GObjectClass like structs "
+#| "in public or Standard section depends if they have public entries "
+#| "(variables, vmethods)."
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"declarations (e.g. the functions like g_object_get_type and macros like "
"G_OBJECT(), G_IS_OBJECT() etc.). Currently these are left out of the "
"documentation. You can also use <SUBSECTION Private> for private "
-"declarations which will not be output (It is a handy way to avoid warning "
-"messages about unused declarations.). If your library contains private types "
+"declarations which will not be output (it is a handy way to avoid warning "
+"messages about unused declarations). If your library contains private types "
"which you don't want to appear in the object hierarchy and the list of "
"implemented or required interfaces, add them to a Private subsection. "
"Whether you would place GObject and GObjectClass like structs in public or "
"<SUBSECTION>. Actuellement, une ligne blanche est ajoutée entre les "
"sous-sections dans la section résumé. Vous pouvez également utiliser <"
"SUBSECTION Standard> pour les déclarations GObject standards (par "
-"exemple, les fonctions comme g_object_get_type et les macros comme G_OBJECT"
-"(), G_IS_OBJECT(), etc.). Actuellement, elles ne sont pas intégrées dans la "
-"documentation. Vous pouvez utiliser <SUBSECTION Private> pour les "
-"déclarations privées qui ne seront pas affichées (c'est un moyen pratique "
-"d'éviter les messages d'avertissement sur les déclarations inutilisées). Si "
-"votre bibliothèque contient des types privés que vous ne souhaitez pas voir "
-"apparaître dans la hiérarchie des objets et dans la liste des interfaces "
-"implémentées ou nécessaires, ajoutez-les à une sous-section privée. Le choix "
-"de placer des GObject ou GObjectClass comme des structures dans une section "
-"standard ou publique dépend de la présence d'éléments publics (variables, "
-"vmethods)."
-
-#: C/index.docbook:1653(sect1/para)
+"exemple, les fonctions comme g_object_get_type et les macros comme "
+"G_OBJECT(), G_IS_OBJECT(), etc.). Actuellement, elles ne sont pas intégrées "
+"dans la documentation. Vous pouvez utiliser <SUBSECTION Private> pour "
+"les déclarations privées qui ne seront pas affichées (c'est un moyen "
+"pratique d'éviter les messages d'avertissement sur les déclarations "
+"inutilisées). Si votre bibliothèque contient des types privés que vous ne "
+"souhaitez pas voir apparaître dans la hiérarchie des objets et dans la liste "
+"des interfaces implémentées ou nécessaires, ajoutez-les à une sous-section "
+"privée. Le choix de placer des GObject ou GObjectClass comme des structures "
+"dans une section standard ou publique dépend de la présence d'éléments "
+"publics (variables, vmethods)."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1873
msgid ""
"You can also use <INCLUDE> ... </INCLUDE> to specify the "
"#include files which are shown in the synopsis sections. It contains a comma-"
"s'appliquent à toutes les sections jusqu'à la fin du fichier. Si vous les "
"placez dans une section, elles s'appliquent seulement à cette section."
-#: C/index.docbook:1667(chapter/title)
+#. (itstool) path: chapter/title
+#: C/index.docbook:1887
msgid "Controlling the result"
msgstr "Contrôle du résultat"
-#: C/index.docbook:1669(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:1889
msgid ""
"A GTK-Doc run generates report files inside the documentation directory. The "
"generated files are named: <filename><package>-undocumented.txt</"
"filename>. Tous ces fichiers texte peuvent être lus et post-traités "
"facilement."
-#: C/index.docbook:1678(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:1898
msgid ""
"The <filename><package>-undocumented.txt</filename> file starts with "
"the documentation coverage summary. Below are two sections divided by blank "
"documentations de sections. Les éléments incomplets sont ceux qui possèdent "
"une documentation mais auxquels, par exemple, un paramètre a été ajouté."
-#: C/index.docbook:1687(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:1907
msgid ""
"The <filename><package>-undeclared.txt</filename> file lists symbols "
"given in the <filename><package>-sections.txt</filename> but not found "
"filename> mais non trouvés dans les fichiers sources. Vérifiez s'ils n'ont "
"pas été supprimés ou mal orthographiés."
-#: C/index.docbook:1694(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:1914
msgid ""
"The <filename><package>-unused.txt</filename> file lists symbol names, "
"where the GTK-Doc scanner has found documentation, but does not know where "
"mais ne sait pas où la placer. Cela signifie que le symbole n'a pas encore "
"été ajouté au fichier <filename><package>-sections.txt</filename>."
-#: C/index.docbook:1702(tip/para)
+#. (itstool) path: tip/para
+#: C/index.docbook:1922
msgid ""
"Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile."
"am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during "
"1.9, des contrôles de validité seront lancés pendant l'exécution de "
"<command>make check</command>."
-#: C/index.docbook:1709(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:1929
+#, fuzzy
+#| msgid ""
+#| "One can also look at the files produced by the source code scanner: "
+#| "<filename><package>-decl-list.txt</filename> and <filename><"
+#| "package>-decl.txt</filename>. The first one can be compared with the "
+#| "section file if that is manually maintained. The second lists all "
+#| "declarations from the headers If a symbol is missing one could check if "
+#| "this file contains it."
msgid ""
"One can also look at the files produced by the source code scanner: "
"<filename><package>-decl-list.txt</filename> and <filename><"
"package>-decl.txt</filename>. The first one can be compared with the "
"section file if that is manually maintained. The second lists all "
-"declarations from the headers If a symbol is missing one could check if this "
-"file contains it."
+"declarations from the headers. If a symbol is missing one could check if "
+"this file contains it."
msgstr ""
"Vous pouvez également regarder les fichiers produits par le scanneur de code "
"source : <filename><package>-decl-list.txt</filename> et <filename><"
"déclarations contenues dans les fichiers en-tête. Si un symbole est "
"manquant, il faut vérifier si ce fichier le contient."
-#: C/index.docbook:1718(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:1938
+#, fuzzy
+#| msgid ""
+#| "If the project is GObject based, one can also look into the files "
+#| "produced by the object scanner: <filename><package>.args.txt</"
+#| "filename>, <filename><package>.hierarchy.txt</filename>, "
+#| "<filename><package>.interfaces.txt</filename>, <filename><"
+#| "package>.prerequisites.txt</filename> and <filename><package>."
+#| "signals.txt</filename>. If there are missing symbols in any of those, one "
+#| "can ask gtkdoc to keep the intermediate scanner file for further "
+#| "analysis, but running it as <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</"
+#| "command>."
msgid ""
"If the project is GObject based, one can also look into the files produced "
"by the object scanner: <filename><package>.args.txt</filename>, "
"<filename><package>.hierarchy.txt</filename>, <filename><"
"package>.interfaces.txt</filename>, <filename><package>."
"prerequisites.txt</filename> and <filename><package>.signals.txt</"
-"filename>. If there are missing symbols in any of those, one can ask gtkdoc "
-"to keep the intermediate scanner file for further analysis, but running it "
-"as <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>."
+"filename>. If there are missing symbols in any of those, one can ask GTK-Doc "
+"to keep the intermediate scanner file for further analysis, by running it as "
+"<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>."
msgstr ""
"Si le projet est basé sur GObject, il est possible de regarder dans les "
"fichiersgénérés par le scanneur d'objet : <filename><package>.args."
"intermédiaire pour en faire une analyse ultérieure mais en le lançant comme "
"<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>."
-#: C/index.docbook:1733(chapter/title)
+#. (itstool) path: chapter/title
+#: C/index.docbook:1953
+msgid "Modernizing the documentation"
+msgstr "Modernisation de la documentation"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1955
+msgid ""
+"GTK-Doc has been around for quite some time. In this section we list new "
+"features together with the version since when it is available."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1961
+msgid "GTK-Doc 1.9"
+msgstr "Manuel de GTK-Doc 1.9"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1963
+#, fuzzy
+#| msgid ""
+#| "Is the new page xi:included from <filename><package>-docs.{xml,sgml}"
+#| "</filename>."
+msgid ""
+"When using xml instead of sgml, one can actually name the master document "
+"<filename><package>-docs.xml</filename>."
+msgstr ""
+"Est-ce que la nouvelle page est xi:included à partir de <filename><"
+"module>-docs.{xml,sgml}</filename>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1968
+msgid ""
+"This version supports <option>SCAN_OPTIONS=--rebuild-sections</option> in "
+"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
+"package>-sections.txt</filename> is autogenerated and can be removed from "
+"the vcs. This only works nicely for projects that have a very regular "
+"structure (e.g. each .{c,h} pair will create new section). If one organize a "
+"project close to that updating a manually maintained section file can be as "
+"simple as running <code>meld <package>-decl-list.txt <package>-"
+"sections.txt</code>."
+msgstr ""
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1979
+msgid ""
+"Version 1.8 already introduced the syntax for documenting sections in the "
+"sources instead of the separate files under <filename class=\"directory"
+"\">tmpl</filename>. This version adds options to switch the whole doc module "
+"to not use the extra tmpl build step at all, by using <option>--flavour no-"
+"tmpl</option> in <filename>configure.ac</filename>. If you don't have a "
+"<filename class=\"directory\">tmpl</filename> checked into your source "
+"control system and haven't yet switched, just add the flag to "
+"<filename>configure.ac</filename> and you are done."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1991
+msgid "GTK-Doc 1.10"
+msgstr "Manuel de GTK-Doc 1.10"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1993
+msgid ""
+"This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in "
+"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
+"package>.types</filename> is autogenerated and can be removed from the "
+"vcs. When using this feature it is important to also setup the "
+"<varname>IGNORE_HFILES</varname> in <filename>Makefile.am</filename> for "
+"code that is build conditionally."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2004
+msgid "GTK-Doc 1.16"
+msgstr "Manuel de GTK-Doc 1.16"
+
+#. (itstool) path: example/title
+#: C/index.docbook:2010
+msgid "Enable gtkdoc-check"
+msgstr ""
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2011
+#, no-wrap
+msgid ""
+"\n"
+"if ENABLE_GTK_DOC\n"
+"TESTS_ENVIRONMENT = \\\n"
+" DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \\\n"
+" SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)\n"
+"TESTS = $(GTKDOC_CHECK)\n"
+"endif\n"
+msgstr ""
+"\n"
+"if ENABLE_GTK_DOC\n"
+"TESTS_ENVIRONMENT = \\\n"
+" DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \\\n"
+" SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)\n"
+"TESTS = $(GTKDOC_CHECK)\n"
+"endif\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:2006
+msgid ""
+"This version includes a new tool called gtkdoc-check. This tool can run a "
+"set of sanity checks on your documentation. It is enabled by adding these "
+"lines to the end of <filename>Makefile.am</filename>. <_:example-1/>"
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2024
+msgid "GTK-Doc 1.20"
+msgstr "Manuel de GTK-Doc 1.20"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:2026
+msgid ""
+"Version 1.18 brought some initial markdown support. Using markdown in doc "
+"comments is less intrusive than writing docbook xml. This version improves a "
+"lot on this and add a lot more styles. The section that explains the <link "
+"linkend=\"documenting_syntax\">comment syntax</link> has all the details."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2036
+msgid "GTK-Doc 1.25"
+msgstr "Manuel de GTK-Doc 1.25"
+
+#. (itstool) path: example/title
+#: C/index.docbook:2046
+msgid "Use pre-generated entities"
+msgstr ""
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2047
+#, no-wrap
+msgid ""
+"\n"
+"<?xml version=\"1.0\"?>\n"
+"<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"\n"
+" \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"\n"
+"[\n"
+" <!ENTITY % local.common.attrib \"xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'\">\n"
+" <!ENTITY % gtkdocentities SYSTEM \"xml/gtkdocentities.ent\">\n"
+" %gtkdocentities;\n"
+"]>\n"
+"<book id=\"index\" xmlns:xi=\"http://www.w3.org/2003/XInclude\">\n"
+" <bookinfo>\n"
+" <title>&package_name; Reference Manual</title>\n"
+" <releaseinfo>\n"
+" for &package_string;.\n"
+" The latest version of this documentation can be found on-line at\n"
+" <ulink role=\"online-location\" url=\"http://[SERVER]/&package_name;/index.html\">http://[SERVER]/&package_name;/</ulink>.\n"
+" </releaseinfo>\n"
+" </bookinfo>\n"
+msgstr ""
+"\n"
+"<?xml version=\"1.0\"?>\n"
+"<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"\n"
+" \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"\n"
+"[\n"
+" <!ENTITY % local.common.attrib \"xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'\">\n"
+" <!ENTITY % gtkdocentities SYSTEM \"xml/gtkdocentities.ent\">\n"
+" %gtkdocentities;\n"
+"]>\n"
+"<book id=\"index\" xmlns:xi=\"http://www.w3.org/2003/XInclude\">\n"
+" <bookinfo>\n"
+" <title>&package_name; Reference Manual</title>\n"
+" <releaseinfo>\n"
+" for &package_string;.\n"
+" The latest version of this documentation can be found on-line at\n"
+" <ulink role=\"online-location\" url=\"http://[SERVER]/&package_name;/index.html\">http://[SERVER]/&package_name;/</ulink>.\n"
+" </releaseinfo>\n"
+" </bookinfo>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:2038
+msgid ""
+"The makefiles shipped with this version generate an entity file at "
+"<filename>xml/gtkdocentities.ent</filename>, containing entities for e.g. "
+"package_name and package_version. You can use this e.g. in the main xml file "
+"to avoid hardcoding the version number. Below is an example that shows how "
+"the entity file is included and how the entities are used. The entities can "
+"also be used in all generated files, GTK-Doc will use the same xml header in "
+"generated xml files. <_:example-1/>"
+msgstr ""
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:2072
msgid "Documenting other interfaces"
msgstr "Documentation d'autres interfaces"
-#: C/index.docbook:1735(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:2074
msgid ""
"So far we have been using GTK-Doc to document the API of code. The next "
"sections contain suggestions how the tools can be used to document other "
"sections qui suivent contiennent des suggestions sur la manière d'utiliser "
"les outils pour documenter aussi d'autres interfaces."
-#: C/index.docbook:1742(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:2081
msgid "Command line options and man pages"
msgstr "Options de ligne de commande et pages de manuel"
-#: C/index.docbook:1744(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:2083
msgid ""
"As one can generate man pages for a docbook refentry as well, it sounds like "
"a good idea to use it for that purpose. This way the interface is part of "
"Ainsi, l'interface fait partie de la référence et l'on obtient en cadeau la "
"page de manuel."
-#: C/index.docbook:1751(sect2/title)
+#. (itstool) path: sect2/title
+#: C/index.docbook:2090
msgid "Document the tool"
msgstr "Documentation de l'outil"
-#: C/index.docbook:1753(sect2/para)
+#. (itstool) path: sect2/para
+#: C/index.docbook:2092
msgid ""
"Create one refentry file per tool. Following <link linkend="
"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
"balises XML pouvant être utilisées, on peut observer le fichier généré dans "
"le sous-répertoire xml ou des exemples comme dans glib."
-#: C/index.docbook:1763(sect2/title)
+#. (itstool) path: sect2/title
+#: C/index.docbook:2102
msgid "Adding the extra configure check"
msgstr "Ajout de contrôles « configure » supplémentaires"
-#: C/index.docbook:1766(example/title) C/index.docbook:1786(example/title)
+#. (itstool) path: example/title
+#: C/index.docbook:2105 C/index.docbook:2123
msgid "Extra configure checks"
msgstr "Contrôles « configure » supplémentaires"
-#: C/index.docbook:1767(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2106
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "AC_ARG_ENABLE(man,\n"
+#| " [AC_HELP_STRING([--enable-man],\n"
+#| " [regenerate man pages from Docbook [default=no]])],enable_man=yes,\n"
+#| " enable_man=no)\n"
+#| "\n"
+#| "AC_PATH_PROG([XSLTPROC], [xsltproc])\n"
+#| "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"AC_ARG_ENABLE(man,\n"
" [AC_HELP_STRING([--enable-man],\n"
" [regenerate man pages from Docbook [default=no]])],enable_man=yes,\n"
"\n"
"AC_PATH_PROG([XSLTPROC], [xsltproc])\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"AC_ARG_ENABLE(man,\n"
" [AC_HELP_STRING([--enable-man],\n"
" [regenerate man pages from Docbook [default=no]])],enable_man=yes,\n"
"\n"
"AC_PATH_PROG([XSLTPROC], [xsltproc])\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
-"\n"
-" "
-#: C/index.docbook:1783(sect2/title)
+#. (itstool) path: sect2/title
+#: C/index.docbook:2120
msgid "Adding the extra makefile rules"
msgstr "Ajout de règles « makefile » supplémentaires"
-#: C/index.docbook:1787(example/programlisting)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2124
#, no-wrap
+#| msgid ""
+#| "\n"
+#| "\n"
+#| "man_MANS = \\\n"
+#| " meeper.1\n"
+#| "\n"
+#| "if ENABLE_GTK_DOC\n"
+#| "if ENABLE_MAN\n"
+#| "\n"
+#| "%.1 : %.xml\n"
+#| " @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<\n"
+#| "\n"
+#| "endif\n"
+#| "endif\n"
+#| "\n"
+#| "BUILT_EXTRA_DIST = $(man_MANS)\n"
+#| "EXTRA_DIST += meep.xml\n"
+#| "\n"
+#| " "
msgid ""
"\n"
-"\n"
"man_MANS = \\\n"
" meeper.1\n"
"\n"
"\n"
"BUILT_EXTRA_DIST = $(man_MANS)\n"
"EXTRA_DIST += meep.xml\n"
-"\n"
-" "
msgstr ""
"\n"
-"\n"
"man_MANS = \\\n"
" meeper.1\n"
"\n"
"\n"
"BUILT_EXTRA_DIST = $(man_MANS)\n"
"EXTRA_DIST += meep.xml\n"
-"\n"
-" "
-#: C/index.docbook:1811(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:2146
msgid "DBus interfaces"
msgstr "Interfaces DBus"
-#: C/index.docbook:1813(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:2148
msgid ""
"(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://"
"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
"(À_CORRIGER : http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, "
"http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
-#: C/index.docbook:1822(chapter/title)
+#. (itstool) path: chapter/title
+#: C/index.docbook:2157
msgid "Frequently asked questions"
msgstr "Foire aux questions"
-#: C/index.docbook:1826(segmentedlist/segtitle)
+#. (itstool) path: segmentedlist/segtitle
+#: C/index.docbook:2161
msgid "Question"
-msgstr "Question "
+msgstr "Question"
-#: C/index.docbook:1827(segmentedlist/segtitle)
+#. (itstool) path: segmentedlist/segtitle
+#: C/index.docbook:2162
msgid "Answer"
-msgstr "Réponse "
+msgstr "Réponse"
-#: C/index.docbook:1829(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2164
msgid "No class hierarchy."
msgstr "Pas de hiérarchie de classe."
-#: C/index.docbook:1830(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2165
msgid ""
"The objects <function>xxx_get_type()</function> function has not been "
"entered into the <filename><package>.types</filename> file."
"Les fonctions objet <function>xxx_get_type()</function> n'ont pas été "
"saisies dans le fichier <filename><module>.types</filename>."
-#: C/index.docbook:1836(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2171
msgid "Still no class hierarchy."
msgstr "Toujours pas de hiérarchie de classe."
-#: C/index.docbook:1837(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2172
msgid ""
"Missing or wrong naming in <filename><package>-sections.txt</filename> "
"file (see <ulink url=\"http://mail.gnome.org/archives/gtk-doc-list/2003-"
"txt</filename> (consultez une <ulink url=\"http://mail.gnome.org/archives/"
"gtk-doc-list/2003-October/msg00006.html\">explication</ulink>)."
-#: C/index.docbook:1843(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2178
msgid "Damn, I have still no class hierarchy."
msgstr "Zut, je n'ai toujours pas de hiérarchie de classe."
-#: C/index.docbook:1844(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2179
msgid ""
"Is the object name (name of the instance struct, e.g. <type>GtkWidget</"
"type>) part of the normal section (don't put this into Standard or Private "
"<type>GtkWidget</type>) fait parti de la section « normal » (ne pas le "
"mettre dans les sous-sections « Standard » ou « Private »)."
-#: C/index.docbook:1851(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2186
msgid "No symbol index."
msgstr "Pas d'index des symboles."
-#: C/index.docbook:1852(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2187
msgid ""
"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
"index that xi:includes the generated index?"
"Est-ce que <filename><module>-docs.{xml,sgml}</filename> contient un "
"index qui « xi:includes » l'index généré ?"
-#: C/index.docbook:1858(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2193
msgid "Symbols are not linked to their doc-section."
msgstr "Les symboles ne sont pas liés à leur section de documentation."
-#: C/index.docbook:1859(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2194
msgid ""
"Is the doc-comment using the correct markup (added #,% or ())? Check if the "
"gtkdoc-fixxref warns about unresolvable xrefs."
"Contrôlez si gtkdoc-fixxref affiche des avertissements à propos de xrefs non "
"résolus."
-#: C/index.docbook:1865(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2200
msgid "A new class does not appear in the docs."
msgstr "Une nouvelle classe n'apparaît pas dans les documents."
-#: C/index.docbook:1866(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2201
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"Est-ce que la nouvelle page est xi:included à partir de <filename><"
"module>-docs.{xml,sgml}</filename>."
-#: C/index.docbook:1872(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2207
msgid "A new symbol does not appear in the docs."
msgstr "Un nouveau symbole n'apparaît pas dans les documents."
-#: C/index.docbook:1873(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2208
msgid ""
"Is the doc-comment properly formatted. Check for spelling mistakes in the "
"begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable "
"correctement listé dans une section publique de <filename><module>-"
"sections.txt</filename>."
-#: C/index.docbook:1881(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2216
msgid "A type is missing from the class hierarchy."
msgstr "Un type est absent dans la hiérarchie de classe."
-#: C/index.docbook:1882(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2217
+#, fuzzy
+#| msgid ""
+#| "If the type is listed in <filename><package>.hierarchy</filename> "
+#| "but not in <filename>xml/tree_index.sgml</filename> then double check "
+#| "that the type is correctly placed in the <filename><package>-"
+#| "sections.txt</filename>. If the type instance (e.g. <type>GtkWidget</"
+#| "type>) is not listed or incidentialy makred private it will not be shown."
msgid ""
"If the type is listed in <filename><package>.hierarchy</filename> but "
"not in <filename>xml/tree_index.sgml</filename> then double check that the "
"type is correctly placed in the <filename><package>-sections.txt</"
"filename>. If the type instance (e.g. <type>GtkWidget</type>) is not listed "
-"or incidentialy makred private it will not be shown."
+"or incidentally marked private it will not be shown."
msgstr ""
"Si le type est listé dans <filename><module>.hierarchy</filename> mais "
"pas dans <filename>xml/tree_index.sgml</filename> alors contrôlez deux-fois "
"txt</filename>. Si l'instance du type (par ex. <type>GtkWidget</type>) n'est "
"pas listée ou marquée par accident comme privée, elle ne sera pas affichée."
-#: C/index.docbook:1891(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2226
msgid "I get foldoc links for all gobject annotations."
msgstr "J'obtiens des liens foldoc pour toutes les annotations gobject."
-#: C/index.docbook:1892(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2227
msgid ""
"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
"from <filename><package>-docs.{xml,sgml}</filename>."
"Vérifiez que <filename>xml/annotation-glossary.xml</filename> est xi:"
"included à partir de <filename><module>-docs.{xml,sgml}</filename>."
-#: C/index.docbook:1900(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2235
msgid "Parameter described in source code comment block but does not exist"
msgstr ""
"Un paramètre est décrit dans le bloc de commentaires dans le code source "
"mais il n'existe pas."
-#: C/index.docbook:1901(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2236
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
"Vérifiez si le prototype dans le fichier d'en-tête possède des noms de "
"paramètres différents de ceux du fichier source."
-#: C/index.docbook:1906(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2241
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "« ID » multiples pour le linkend: XYZ contraint"
-#: C/index.docbook:1907(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2242
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
msgstr ""
-"Le symbole XYZ apparaît en double dans le fichier <filename><module>-"
+"Le symbole XYZ apparaît en double dans le fichier <filename><package>-"
"sections.txt</filename>."
-#: C/index.docbook:1910(seglistitem/seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2245
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"Élément typename dans l'espace de nom '' rencontré dans para mais aucun "
"prototype ne correspond."
-#: C/index.docbook:1917(chapter/title)
+#. (itstool) path: chapter/title
+#: C/index.docbook:2252
msgid "Tools related to gtk-doc"
msgstr "Outils liés à gtk-doc"
-#: C/index.docbook:1919(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:2254
msgid ""
"GtkDocPlugin - a <ulink url=\"http://trac-hacks.org/wiki/GtkDocPlugin\">Trac "
-"GTK-Doc</ulink> integration plugin, that adds api docs to a trac site and "
+"GTK-Doc</ulink> integration plugin, that adds API docs to a trac site and "
"integrates with the trac search."
msgstr ""
"GtkDocPlugin - un greffon d'intégration à <ulink url=\"http://trac-hacks.org/"
-"wiki/GtkDocPlugin\">Trac</ulink>, qui ajoute la documentation d'API à un "
-"site Trac et s'intègre à la recherche Trac."
+"wiki/GtkDocPlugin\">Trac GTK-Doc</ulink>, qui ajoute la documentation d'API "
+"à un site Trac et s'intègre à la recherche Trac."
-#: C/index.docbook:1924(chapter/para)
+#. (itstool) path: chapter/para
+#: C/index.docbook:2259
+#, fuzzy
+#| msgid ""
+#| "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since "
+#| "tags in the api to determine the minimum required version."
msgid ""
"Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since "
-"tags in the api to determine the minimum required version."
+"tags in the API to determine the minimum required version."
msgstr ""
"Gtkdoc-depscan - un outil (intégré à gtk-doc) qui vérifie les API utilisées "
"pour déterminer la version minimale requise."
-#: C/index.docbook:12(appendixinfo/releaseinfo)
-#: C/fdl-appendix.xml:12(appendixinfo/releaseinfo)
+#. (itstool) path: appendixinfo/releaseinfo
+#: C/index.docbook:12 C/fdl-appendix.xml:12
msgid "Version 1.1, March 2000"
msgstr "Version 1.1, mars 2000"
-#: C/index.docbook:15(appendixinfo/copyright)
+#. (itstool) path: appendixinfo/copyright
+#: C/index.docbook:15
msgid "<year>2000</year><holder>Free Software Foundation, Inc.</holder>"
msgstr "<year>2000</year><holder>Free Software Foundation, Inc.</holder>"
-#: C/index.docbook:20(para/address)
+#. (itstool) path: para/address
+#: C/index.docbook:20
#, no-wrap
msgid ""
"Free Software Foundation, Inc. <street>51 Franklin Street, \n"
" Suite 330</street>, <city>Boston</city>, <state>MA</state> \n"
" <postcode>02110-1301</postcode> <country>USA</country>"
-#: C/index.docbook:19(legalnotice/para)
-#: C/fdl-appendix.xml:19(legalnotice/para)
+#. (itstool) path: legalnotice/para
+#: C/index.docbook:19 C/fdl-appendix.xml:19
msgid ""
"<_:address-1/> Everyone is permitted to copy and distribute verbatim copies "
"of this license document, but changing it is not allowed."
"<_:address-1/> Chacun est libre de copier et de distribuer des copies "
"conformes de cette Licence, mais nul n'est autorisé à la modifier."
-#: C/index.docbook:28(appendix/title) C/fdl-appendix.xml:28(appendix/title)
-#: C/fdl-appendix.xml:642(para/quote)
+#. (itstool) path: appendix/title
+#. (itstool) path: para/quote
+#: C/index.docbook:28 C/fdl-appendix.xml:28 C/fdl-appendix.xml:642
msgid "GNU Free Documentation License"
msgstr "Licence de Documentation Libre GNU"
-#: C/index.docbook:31(sect1/title) C/fdl-appendix.xml:31(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:31 C/fdl-appendix.xml:31
msgid "0. PREAMBLE"
msgstr "0. Préambule"
-#: C/index.docbook:32(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:32
msgid ""
"The purpose of this License is to make a manual, textbook, or other written "
"document <quote>free</quote> in the sense of freedom: to assure everyone the "
"qu'ils soient pour autant considérés comme responsables des modifications "
"réalisées par des tiers."
-#: C/index.docbook:43(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:43
msgid ""
"This License is a kind of <quote>copyleft</quote>, which means that "
"derivative works of the document must themselves be free in the same sense. "
"les mêmes termes. Elle complète la Licence Publique Générale GNU, qui est "
"également une Licence copyleft, conçue pour les logiciels libres."
-#: C/index.docbook:50(sect1/para) C/fdl-appendix.xml:50(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:50 C/fdl-appendix.xml:50
msgid ""
"We have designed this License in order to use it for manuals for free "
"software, because free software needs free documentation: a free program "
"Licence principalement pour les travaux destinés à des fins d'enseignement "
"ou devant servir de documents de référence."
-#: C/index.docbook:62(sect1/title) C/fdl-appendix.xml:62(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:62 C/fdl-appendix.xml:62
msgid "1. APPLICABILITY AND DEFINITIONS"
msgstr "1. APPLICABILITÉ ET DÉFINITIONS"
-#: C/index.docbook:63(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:63
msgid ""
"This License applies to any manual or other work that contains a notice "
"placed by the copyright holder saying it can be distributed under the terms "
"ou travail. Toute personne en est par définition concessionnaire et est "
"référencée ci-après par le terme <quote>Vous</quote>."
-#: C/index.docbook:72(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:72
msgid ""
"A <quote>Modified Version</quote> of the Document means any work containing "
"the Document or a portion of it, either copied verbatim, or with "
"contenant la totalité ou seulement une portion de celui-ci, copiée mot pour "
"mot, modifiée et/ou traduite dans une autre langue."
-#: C/index.docbook:79(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:79
msgid ""
"A <quote>Secondary Section</quote> is a named appendix or a front-matter "
"section of the <link linkend=\"fdl-document\">Document</link> that deals "
"philosophiques, ou des positions éthiques ou politiques susceptibles de "
"concerner le sujet traité."
-#: C/index.docbook:94(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:94
msgid ""
"The <quote>Invariant Sections</quote> are certain <link linkend=\"fdl-"
"secondary\"> Secondary Sections</link> whose titles are designated, as being "
"modifiées et citées comme telles dans la notice légale qui place le <link "
"linkend=\"fdl-document\">Document</link> sous cette Licence."
-#: C/index.docbook:103(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:103
msgid ""
"The <quote>Cover Texts</quote> are certain short passages of text that are "
"listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says "
"\">Document</link>, et cités comme tels dans la mention légale de ce <link "
"linkend=\"fdl-document\">Document</link>."
-#: C/index.docbook:111(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:111
msgid ""
"A <quote>Transparent</quote> copy of the <link linkend=\"fdl-document\"> "
"Document</link> means a machine-readable copy, represented in a format whose "
"Une copie qui n'est pas <quote>Transparente</quote> est considérée, par "
"opposition, comme <quote>Opaque</quote>."
-#: C/index.docbook:128(sect1/para) C/fdl-appendix.xml:128(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:128 C/fdl-appendix.xml:128
msgid ""
"Examples of suitable formats for Transparent copies include plain ASCII "
"without markup, Texinfo input format, LaTeX input format, SGML or XML using "
"d'un traitement de texte quelconque et dans le seul but de la génération "
"d'un format de sortie."
-#: C/index.docbook:141(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:141
msgid ""
"The <quote>Title Page</quote> means, for a printed book, the title page "
"itself, plus such following pages as are needed to hold, legibly, the "
"décrit ci-dessus, la <quote>Page de titre</quote> désigne le texte qui "
"s'apparente le plus au titre du document et situé avant le texte principal."
-#: C/index.docbook:153(sect1/title) C/fdl-appendix.xml:153(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:153 C/fdl-appendix.xml:153
msgid "2. VERBATIM COPYING"
msgstr "2. COPIES CONFORMES"
-#: C/index.docbook:154(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:154
msgid ""
"You may copy and distribute the <link linkend=\"fdl-document\">Document</"
"link> in any medium, either commercially or noncommercially, provided that "
"grande quantité de copies, référez-vous aux dispositions de la <link linkend="
"\"fdl-section3\">section 3</link>."
-#: C/index.docbook:169(sect1/para) C/fdl-appendix.xml:169(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:169 C/fdl-appendix.xml:169
msgid ""
"You may also lend copies, under the same conditions stated above, and you "
"may publicly display copies."
"celles suscitées, et vous pouvez afficher publiquement des copies de ce "
"Document."
-#: C/index.docbook:176(sect1/title) C/fdl-appendix.xml:176(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:176 C/fdl-appendix.xml:176
msgid "3. COPYING IN QUANTITY"
msgstr "3. COPIES EN NOMBRE"
-#: C/index.docbook:177(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:177
msgid ""
"If you publish printed copies of the <link linkend=\"fdl-document"
"\">Document</link> numbering more than 100, and the Document's license "
"document\">Document</link> soit préservé et que les conditions indiquées "
"précédemment soient respectées."
-#: C/index.docbook:195(sect1/para) C/fdl-appendix.xml:195(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:195 C/fdl-appendix.xml:195
msgid ""
"If the required texts for either cover are too voluminous to fit legibly, "
"you should put the first ones listed (as many as fit reasonably) on the "
"y tenir de manière claire, vous pouvez ne placer que les premiers sur la "
"première page et placer les suivants sur les pages consécutives."
-#: C/index.docbook:202(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:202
msgid ""
"If you publish or distribute <link linkend=\"fdl-transparent\">Opaque</link> "
"copies of the <link linkend=\"fdl-document\">Document</link> numbering more "
"durant une année pleine après la diffusion publique de la dernière Copie "
"opaque(directement ou via vos revendeurs)."
-#: C/index.docbook:222(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:222
msgid ""
"It is requested, but not required, that you contact the authors of the <link "
"linkend=\"fdl-document\">Document</link> well before redistributing any "
"avant toute publication d'un grand nombre de copies, afin de lui permettre "
"de vous donner une version à jour du Document."
-#: C/index.docbook:231(sect1/title) C/fdl-appendix.xml:231(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:231 C/fdl-appendix.xml:231
msgid "4. MODIFICATIONS"
msgstr "4. MODIFICATIONS"
-#: C/index.docbook:232(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:232
msgid ""
"You may copy and distribute a <link linkend=\"fdl-modified\">Modified "
"Version</link> of the <link linkend=\"fdl-document\">Document</link> under "
"modifiée à quiconque en possède une copie. De plus, vous devez effectuer les "
"actions suivantes dans la Version modifiée :"
-#: C/index.docbook:248(formalpara/title)
-#: C/fdl-appendix.xml:248(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:248 C/fdl-appendix.xml:248
msgid "A"
msgstr "A"
-#: C/index.docbook:249(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:249
msgid ""
"Use in the <link linkend=\"fdl-title-page\">Title Page</link> (and on the "
"covers, if any) a title distinct from that of the <link linkend=\"fdl-"
"mentionnées dans la section Historique du Document). Vous pouvez utiliser le "
"même titre si l'éditeur d'origine vous en a donné expressément la permission."
-#: C/index.docbook:264(formalpara/title)
-#: C/fdl-appendix.xml:264(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:264 C/fdl-appendix.xml:264
msgid "B"
msgstr "B"
-#: C/index.docbook:265(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:265
msgid ""
"List on the <link linkend=\"fdl-title-page\">Title Page</link>, as authors, "
"one or more persons or entities responsible for authorship of the "
"avec au moins les cinq principaux auteurs du <link linkend=\"fdl-document"
"\">Document</link> (ou tous les auteurs s'il y en a moins de cinq)."
-#: C/index.docbook:279(formalpara/title)
-#: C/fdl-appendix.xml:279(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:279 C/fdl-appendix.xml:279
msgid "C"
msgstr "C"
-#: C/index.docbook:280(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:280
msgid ""
"State on the <link linkend=\"fdl-title-page\">Title Page</link> the name of "
"the publisher of the <link linkend=\"fdl-modified\">Modified Version</link>, "
"de l'éditeur de la <link linkend=\"fdl-modified\">Version modifiée</link>, "
"en tant qu'éditeur du Document."
-#: C/index.docbook:291(formalpara/title)
-#: C/fdl-appendix.xml:291(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:291 C/fdl-appendix.xml:291
msgid "D"
msgstr "D"
-#: C/index.docbook:292(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:292
msgid ""
"Preserve all the copyright notices of the <link linkend=\"fdl-document"
"\">Document</link>."
"Préserver intégralement toutes les notices de copyright du <link linkend="
"\"fdl-document\">Document</link>."
-#: C/index.docbook:301(formalpara/title)
-#: C/fdl-appendix.xml:301(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:301 C/fdl-appendix.xml:301
msgid "E"
msgstr "E"
-#: C/index.docbook:302(formalpara/para)
-#: C/fdl-appendix.xml:302(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:302 C/fdl-appendix.xml:302
msgid ""
"Add an appropriate copyright notice for your modifications adjacent to the "
"other copyright notices."
"Ajouter une notice de copyright adjacente aux autres notices pour vos "
"propres modifications."
-#: C/index.docbook:311(formalpara/title)
-#: C/fdl-appendix.xml:311(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:311 C/fdl-appendix.xml:311
msgid "F"
msgstr "F"
-#: C/index.docbook:312(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:312
msgid ""
"Include, immediately after the copyright notices, a license notice giving "
"the public permission to use the <link linkend=\"fdl-modified\">Modified "
"\">Version modifiée</link> selon les termes de cette Licence, sous la forme "
"présentée dans l'annexe indiquée ci-dessous."
-#: C/index.docbook:324(formalpara/title)
-#: C/fdl-appendix.xml:324(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:324 C/fdl-appendix.xml:324
msgid "G"
msgstr "G"
-#: C/index.docbook:325(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:325
msgid ""
"Preserve in that license notice the full lists of <link linkend=\"fdl-"
"invariant\"> Invariant Sections</link> and required <link linkend=\"fdl-"
"texts\">Textes de couverture</link> donnés avec la notice de la Licence du "
"<link linkend=\"fdl-document\">Document</link>."
-#: C/index.docbook:337(formalpara/title)
-#: C/fdl-appendix.xml:337(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:337 C/fdl-appendix.xml:337
msgid "H"
msgstr "H"
-#: C/index.docbook:338(formalpara/para)
-#: C/fdl-appendix.xml:338(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:338 C/fdl-appendix.xml:338
msgid "Include an unaltered copy of this License."
msgstr "Inclure une copie non modifiée de cette Licence."
-#: C/index.docbook:346(formalpara/title)
-#: C/fdl-appendix.xml:346(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:346 C/fdl-appendix.xml:346
msgid "I"
msgstr "I"
-#: C/index.docbook:347(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:347
msgid ""
"Preserve the section entitled <quote>History</quote>, and its title, and add "
"to it an item stating at least the title, year, new authors, and publisher "
"titre</link>, et ajouter une entrée décrivant la <link linkend=\"fdl-modified"
"\">Version modifiée</link> tel que précisé dans la phrase précédente."
-#: C/index.docbook:365(formalpara/title)
-#: C/fdl-appendix.xml:365(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:365 C/fdl-appendix.xml:365
msgid "J"
msgstr "J"
-#: C/index.docbook:366(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:366
msgid ""
"Preserve the network location, if any, given in the <link linkend=\"fdl-"
"document\">Document</link> for public access to a <link linkend=\"fdl-"
"conserver les liens pour un travail datant de plus de quatre ans avant la "
"version courante ou si l'éditeur d'origine vous en accorde la permission."
-#: C/index.docbook:383(formalpara/title)
-#: C/fdl-appendix.xml:383(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:383 C/fdl-appendix.xml:383
msgid "K"
msgstr "K"
-#: C/index.docbook:384(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:384
msgid ""
"In any section entitled <quote>Acknowledgements</quote> or "
"<quote>Dedications</quote>, preserve the section's title, and preserve in "
"contributeurs et les personnes auxquelles s'adressent ces remerciements "
"doivent être conservées, ainsi que le titre de ces sections."
-#: C/index.docbook:396(formalpara/title)
-#: C/fdl-appendix.xml:396(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:396 C/fdl-appendix.xml:396
msgid "L"
msgstr "L"
-#: C/index.docbook:397(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:397
msgid ""
"Preserve all the <link linkend=\"fdl-invariant\">Invariant Sections</link> "
"of the <link linkend=\"fdl-document\">Document</link>, unaltered in their "
"dans leurs textes, ni dans leurs titres. Les numéros de sections ne sont pas "
"considérés comme faisant partie du texte des sections."
-#: C/index.docbook:409(formalpara/title)
-#: C/fdl-appendix.xml:409(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:409 C/fdl-appendix.xml:409
msgid "M"
msgstr "M"
-#: C/index.docbook:410(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:410
msgid ""
"Delete any section entitled <quote>Endorsements</quote>. Such a section may "
"not be included in the <link linkend=\"fdl-modified\">Modified Version</"
"section ne peut pas être incluse dans une <link linkend=\"fdl-modified"
"\">Version modifiée</link>."
-#: C/index.docbook:421(formalpara/title)
-#: C/fdl-appendix.xml:421(formalpara/title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:421 C/fdl-appendix.xml:421
msgid "N"
msgstr "N"
-#: C/index.docbook:422(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:422
msgid ""
"Do not retitle any existing section as <quote>Endorsements</quote> or to "
"conflict in title with any <link linkend=\"fdl-invariant\">Invariant "
"quote> ou sous un autre titre entrant en conflit avec le titre d'une <link "
"linkend=\"fdl-invariant\">Section inaltérable</link>."
-#: C/index.docbook:432(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:432
msgid ""
"If the <link linkend=\"fdl-modified\">Modified Version</link> includes new "
"front-matter sections or appendices that qualify as <link linkend=\"fdl-"
"notice de Licence de la Version modifiée. Ces titres doivent êtres distincts "
"des titres des autres sections."
-#: C/index.docbook:444(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:444
msgid ""
"You may add a section entitled <quote>Endorsements</quote>, provided it "
"contains nothing but endorsements of your <link linkend=\"fdl-modified"
"par une organisation le reconnaissant comme étant la définition d'un "
"standard)."
-#: C/index.docbook:453(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:453
msgid ""
"You may add a passage of up to five words as a <link linkend=\"fdl-cover-"
"texts\">Front-Cover Text</link>, and a passage of up to 25 words as a <link "
"supplémentaire ; mais vous pouvez remplacer un ancien passage si vous avez "
"expressément obtenu l'autorisation de l'éditeur de celui-ci."
-#: C/index.docbook:470(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:470
msgid ""
"The author(s) and publisher(s) of the <link linkend=\"fdl-document"
"\">Document</link> do not by this License give permission to use their names "
"publicitaires ou pour prétendre à l'approbation d'une <link linkend=\"fdl-"
"modified\">Version modifiée</link>."
-#: C/index.docbook:480(sect1/title) C/fdl-appendix.xml:480(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:480 C/fdl-appendix.xml:480
msgid "5. COMBINING DOCUMENTS"
msgstr "5. FUSION DE DOCUMENTS"
-#: C/index.docbook:481(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:481
msgid ""
"You may combine the <link linkend=\"fdl-document\">Document</link> with "
"other documents released under this License, under the terms defined in "
"modification, et de toutes les lister dans la liste des Sections "
"inaltérables de la notice de Licence du document résultant de la fusion."
-#: C/index.docbook:492(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:492
msgid ""
"The combined work need only contain one copy of this License, and multiple "
"identical <link linkend=\"fdl-invariant\">Invariant Sections</link> may be "
"être réalisées dans la liste des Sections inaltérables de la notice de "
"Licence du document final."
-#: C/index.docbook:505(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:505
msgid ""
"In the combination, you must combine any sections entitled <quote>History</"
"quote> in the various original documents, forming one section entitled "
"<quote>Dédicaces</quote>. Vous devez supprimer toutes les sections "
"<quote>Approbations</quote>."
-#: C/index.docbook:516(sect1/title) C/fdl-appendix.xml:516(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:516 C/fdl-appendix.xml:516
msgid "6. COLLECTIONS OF DOCUMENTS"
msgstr "6. REGROUPEMENTS DE DOCUMENTS"
-#: C/index.docbook:517(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:517
msgid ""
"You may make a collection consisting of the <link linkend=\"fdl-document"
"\">Document</link> and other documents released under this License, and "
"documents, à condition de respecter pour chacun de ces documents l'ensemble "
"des règles de cette Licence concernant les copies conformes."
-#: C/index.docbook:527(sect1/para) C/fdl-appendix.xml:527(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:527 C/fdl-appendix.xml:527
+#, fuzzy
+#| msgid ""
+#| "You may extract a single document from such a collection, and dispbibute "
+#| "it individually under this License, provided you insert a copy of this "
+#| "License into the extracted document, and follow this License in all other "
+#| "respects regarding verbatim copying of that document."
msgid ""
-"You may extract a single document from such a collection, and dispbibute it "
+"You may extract a single document from such a collection, and distribute it "
"individually under this License, provided you insert a copy of this License "
"into the extracted document, and follow this License in all other respects "
"regarding verbatim copying of that document."
"copie de cette Licence et d'en respecter l'ensemble des règles concernant "
"les copies conformes."
-#: C/index.docbook:537(sect1/title) C/fdl-appendix.xml:537(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:537 C/fdl-appendix.xml:537
msgid "7. AGGREGATION WITH INDEPENDENT WORKS"
msgstr "7. AGRÉGATION AVEC DES TRAVAUX INDÉPENDANTS"
-#: C/index.docbook:538(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:538
msgid ""
"A compilation of the <link linkend=\"fdl-document\">Document</link> or its "
"derivatives with other separate and independent documents or works, in or on "
"que le Document au sein de l'agrégat. Dans le cas contraire, ils doivent "
"apparaître sur les pages de couverture de l'agrégat complet."
-#: C/index.docbook:561(sect1/title) C/fdl-appendix.xml:561(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:561 C/fdl-appendix.xml:561
msgid "8. TRANSLATION"
msgstr "8. TRADUCTION"
-#: C/index.docbook:562(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:562
msgid ""
"Translation is considered a kind of modification, so you may distribute "
"translations of the <link linkend=\"fdl-document\">Document</link> under the "
"originale en anglais. En cas de contradiction entre la traduction et la "
"version originale en anglais, c'est cette dernière qui prévaut."
-#: C/index.docbook:580(sect1/title) C/fdl-appendix.xml:580(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:580 C/fdl-appendix.xml:580
msgid "9. TERMINATION"
msgstr "9. RÉVOCATION"
-#: C/index.docbook:581(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:581
msgid ""
"You may not copy, modify, sublicense, or distribute the <link linkend=\"fdl-"
"document\">Document</link> except as expressly provided for under this "
"cette Licence ne voient pas leurs droits révoqués tant qu'elles en "
"respectent les principes."
-#: C/index.docbook:594(sect1/title) C/fdl-appendix.xml:594(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:594 C/fdl-appendix.xml:594
msgid "10. FUTURE REVISIONS OF THIS LICENSE"
msgstr "10. RÉVISIONS FUTURES DE CETTE LICENCE"
-#: C/index.docbook:595(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:595
msgid ""
"The <ulink type=\"http\" url=\"http://www.gnu.org/fsf/fsf.html\">Free "
"Software Foundation</ulink> may publish new, revised versions of the GNU "
"<ulink type=\"http\" url=\"http://www.gnu.org/copyleft\">http://www.gnu.org/"
"copyleft/</ulink> pour plus de détails."
-#: C/index.docbook:606(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:606
msgid ""
"Each version of the License is given a distinguishing version number. If the "
"<link linkend=\"fdl-document\">Document</link> specifies that a particular "
"spécifié, vous pouvez choisir n'importe quelle version officielle publiée "
"par la Free Software Foundation."
-#: C/index.docbook:621(sect1/title) C/fdl-appendix.xml:621(sect1/title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:621 C/fdl-appendix.xml:621
msgid "Addendum"
msgstr "Addendum"
-#: C/index.docbook:622(sect1/para) C/fdl-appendix.xml:622(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:622 C/fdl-appendix.xml:622
msgid ""
"To use this License in a document you have written, include a copy of the "
"License in the document and put the following copyright and license notices "
"une copie du texte de cette Licence en anglais et placez le texte ci-dessous "
"juste après la page de titre :"
-#: C/index.docbook:629(blockquote/para)
-#: C/fdl-appendix.xml:629(blockquote/para)
+#. (itstool) path: blockquote/para
+#: C/index.docbook:629 C/fdl-appendix.xml:629
msgid "Copyright YEAR YOUR NAME."
msgstr "Copyright © 2010 Bruno Brouard."
-#: C/index.docbook:632(blockquote/para)
+#. (itstool) path: blockquote/para
+#: C/index.docbook:632
msgid ""
"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 "
"COUVERTURE. Une copie de cette Licence est incluse dans la section appelée "
"<quote>GNU Free Documentation License</quote> de ce document."
-#: C/index.docbook:647(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:647
msgid ""
"If you have no <link linkend=\"fdl-invariant\">Invariant Sections</link>, "
"write <quote>with no Invariant Sections</quote> instead of saying which ones "
"PREMIÈRE PAGE DE COUVERTURE</quote> ; de même pour le <link linkend=\"fdl-"
"cover-texts\">texte de dernière page de couverture</link>."
-#: C/index.docbook:657(sect1/para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:657
msgid ""
"If your document contains nontrivial examples of program code, we recommend "
"releasing these examples in parallel under your choice of free software "
"\" url=\"http://www.gnu.org/copyleft/gpl.html\">Licence GNU General Public "
"License</ulink>, qui permet leur usage dans les logiciels libres."
-#: C/fdl-appendix.xml:16(copyright/year)
+#. (itstool) path: copyright/year
+#: C/fdl-appendix.xml:16
msgid "2000"
msgstr "2000"
-#: C/fdl-appendix.xml:16(copyright/holder)
+#. (itstool) path: copyright/holder
+#: C/fdl-appendix.xml:16
msgid "Free Software Foundation, Inc."
msgstr "Free Software Foundation, Inc."
-#: C/fdl-appendix.xml:20(address/street)
+#. (itstool) path: address/street
+#: C/fdl-appendix.xml:20
msgid "51 Franklin Street, Suite 330"
msgstr "51 Franklin Street, Suite 330"
-#: C/fdl-appendix.xml:21(address/city)
+#. (itstool) path: address/city
+#: C/fdl-appendix.xml:21
msgid "Boston"
msgstr "Boston"
-#: C/fdl-appendix.xml:21(address/state)
+#. (itstool) path: address/state
+#: C/fdl-appendix.xml:21
msgid "MA"
msgstr "MA"
-#: C/fdl-appendix.xml:22(address/postcode)
+#. (itstool) path: address/postcode
+#: C/fdl-appendix.xml:22
msgid "02110-1301"
msgstr "02110-1301"
-#: C/fdl-appendix.xml:22(address/country)
+#. (itstool) path: address/country
+#: C/fdl-appendix.xml:22
msgid "USA"
msgstr "USA"
-#: C/fdl-appendix.xml:20(para/address)
+#. (itstool) path: para/address
+#: C/fdl-appendix.xml:20
msgid ""
"Free Software Foundation, Inc. <_:street-1/>, <_:city-2/>, <_:state-3/> <_:"
"postcode-4/> <_:country-5/>"
"Free Software Foundation, Inc. <_:street-1/>, <_:city-2/>, <_:state-3/> <_:"
"postcode-4/> <_:country-5/>"
-#: C/fdl-appendix.xml:34(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:34
msgid "free"
msgstr "libre"
-#: C/fdl-appendix.xml:32(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:32
msgid ""
"The purpose of this License is to make a manual, textbook, or other written "
"document <_:quote-1/> in the sense of freedom: to assure everyone the "
"qu'ils soient pour autant considérés comme responsables des modifications "
"réalisées par des tiers."
-#: C/fdl-appendix.xml:44(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:44
msgid "copyleft"
msgstr "copyleft"
-#: C/fdl-appendix.xml:43(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:43
msgid ""
"This License is a kind of <_:quote-1/>, which means that derivative works of "
"the document must themselves be free in the same sense. It complements the "
"termes. Elle complète la Licence Publique Générale GNU, qui est également "
"une Licence copyleft, conçue pour les logiciels libres."
-#: C/fdl-appendix.xml:67(para/quote) C/fdl-appendix.xml:82(para/link)
-#: C/fdl-appendix.xml:99(para/link) C/fdl-appendix.xml:107(para/link)
-#: C/fdl-appendix.xml:113(para/link) C/fdl-appendix.xml:156(para/link)
-#: C/fdl-appendix.xml:179(para/link) C/fdl-appendix.xml:190(para/link)
-#: C/fdl-appendix.xml:205(para/link) C/fdl-appendix.xml:224(para/link)
-#: C/fdl-appendix.xml:235(para/link) C/fdl-appendix.xml:253(para/link)
-#: C/fdl-appendix.xml:271(para/link) C/fdl-appendix.xml:294(para/link)
-#: C/fdl-appendix.xml:354(para/link) C/fdl-appendix.xml:368(para/link)
-#: C/fdl-appendix.xml:400(para/link) C/fdl-appendix.xml:462(para/link)
-#: C/fdl-appendix.xml:472(para/link) C/fdl-appendix.xml:482(para/link)
-#: C/fdl-appendix.xml:519(para/link) C/fdl-appendix.xml:540(para/link)
-#: C/fdl-appendix.xml:565(para/link) C/fdl-appendix.xml:583(para/link)
-#: C/fdl-appendix.xml:608(para/link)
+#. (itstool) path: para/quote
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:67 C/fdl-appendix.xml:82 C/fdl-appendix.xml:99
+#: C/fdl-appendix.xml:107 C/fdl-appendix.xml:113 C/fdl-appendix.xml:156
+#: C/fdl-appendix.xml:179 C/fdl-appendix.xml:190 C/fdl-appendix.xml:205
+#: C/fdl-appendix.xml:224 C/fdl-appendix.xml:235 C/fdl-appendix.xml:253
+#: C/fdl-appendix.xml:271 C/fdl-appendix.xml:294 C/fdl-appendix.xml:354
+#: C/fdl-appendix.xml:368 C/fdl-appendix.xml:400 C/fdl-appendix.xml:462
+#: C/fdl-appendix.xml:472 C/fdl-appendix.xml:482 C/fdl-appendix.xml:519
+#: C/fdl-appendix.xml:540 C/fdl-appendix.xml:565 C/fdl-appendix.xml:583
+#: C/fdl-appendix.xml:608
msgid "Document"
msgstr "Document"
-#: C/fdl-appendix.xml:69(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:69
msgid "you"
msgstr "Vous"
-#: C/fdl-appendix.xml:63(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:63
msgid ""
"This License applies to any manual or other work that contains a notice "
"placed by the copyright holder saying it can be distributed under the terms "
"Toute personne en est par définition concessionnaire et est référencée ci-"
"après par le terme <_:quote-2/>."
-#: C/fdl-appendix.xml:73(para/quote) C/fdl-appendix.xml:234(para/link)
-#: C/fdl-appendix.xml:269(para/link) C/fdl-appendix.xml:283(para/link)
-#: C/fdl-appendix.xml:315(para/link) C/fdl-appendix.xml:351(para/link)
-#: C/fdl-appendix.xml:413(para/link) C/fdl-appendix.xml:433(para/link)
-#: C/fdl-appendix.xml:447(para/link) C/fdl-appendix.xml:459(para/link)
-#: C/fdl-appendix.xml:475(para/link) C/fdl-appendix.xml:543(para/link)
+#. (itstool) path: para/quote
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:73 C/fdl-appendix.xml:234 C/fdl-appendix.xml:269
+#: C/fdl-appendix.xml:283 C/fdl-appendix.xml:315 C/fdl-appendix.xml:351
+#: C/fdl-appendix.xml:413 C/fdl-appendix.xml:433 C/fdl-appendix.xml:447
+#: C/fdl-appendix.xml:459 C/fdl-appendix.xml:475 C/fdl-appendix.xml:543
msgid "Modified Version"
msgstr "Version modifiée"
-#: C/fdl-appendix.xml:72(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:72
msgid ""
"A <_:quote-1/> of the Document means any work containing the Document or a "
"portion of it, either copied verbatim, or with modifications and/or "
"ou seulement une portion de celui-ci, copiée mot pour mot, modifiée et/ou "
"traduite dans une autre langue."
-#: C/fdl-appendix.xml:80(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:80
msgid "Secondary Section"
msgstr "Section secondaire"
-#: C/fdl-appendix.xml:79(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:79
msgid ""
"A <_:quote-1/> is a named appendix or a front-matter section of the <_:"
"link-2/> that deals exclusively with the relationship of the publishers or "
"légales, commerciales, philosophiques, ou des positions éthiques ou "
"politiques susceptibles de concerner le sujet traité."
-#: C/fdl-appendix.xml:95(para/quote) C/fdl-appendix.xml:327(para/link)
-#: C/fdl-appendix.xml:398(para/link) C/fdl-appendix.xml:439(para/link)
-#: C/fdl-appendix.xml:486(para/link) C/fdl-appendix.xml:494(para/link)
-#: C/fdl-appendix.xml:567(para/link) C/fdl-appendix.xml:637(para/link)
-#: C/fdl-appendix.xml:648(para/link)
+#. (itstool) path: para/quote
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:95 C/fdl-appendix.xml:327 C/fdl-appendix.xml:398
+#: C/fdl-appendix.xml:439 C/fdl-appendix.xml:486 C/fdl-appendix.xml:494
+#: C/fdl-appendix.xml:567 C/fdl-appendix.xml:637 C/fdl-appendix.xml:648
msgid "Invariant Sections"
msgstr "Sections inaltérables"
-#: C/fdl-appendix.xml:96(para/link) C/fdl-appendix.xml:435(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:96 C/fdl-appendix.xml:435
msgid "Secondary Sections"
msgstr "sections secondaires"
-#: C/fdl-appendix.xml:94(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:94
msgid ""
"The <_:quote-1/> are certain <_:link-2/> whose titles are designated, as "
"being those of Invariant Sections, in the notice that says that the <_:"
"modifiées et citées comme telles dans la notice légale qui place le <_:"
"link-3/> sous cette Licence."
-#: C/fdl-appendix.xml:104(para/quote) C/fdl-appendix.xml:181(para/link)
-#: C/fdl-appendix.xml:328(para/link) C/fdl-appendix.xml:458(para/link)
+#. (itstool) path: para/quote
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:104 C/fdl-appendix.xml:181 C/fdl-appendix.xml:328
+#: C/fdl-appendix.xml:458
msgid "Cover Texts"
msgstr "Textes de couverture"
-#: C/fdl-appendix.xml:103(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:103
msgid ""
"The <_:quote-1/> are certain short passages of text that are listed, as "
"Front-Cover Texts or Back-Cover Texts, in the notice that says that the <_:"
"avant et arrière, et cités comme tels dans la mention légale de ce <_:link-2/"
">."
-#: C/fdl-appendix.xml:112(para/quote) C/fdl-appendix.xml:124(para/quote)
-#: C/fdl-appendix.xml:207(para/link) C/fdl-appendix.xml:369(para/link)
+#. (itstool) path: para/quote
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:112 C/fdl-appendix.xml:124 C/fdl-appendix.xml:207
+#: C/fdl-appendix.xml:369
msgid "Transparent"
msgstr "Copie transparente"
-#: C/fdl-appendix.xml:125(para/quote) C/fdl-appendix.xml:204(para/link)
+#. (itstool) path: para/quote
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:125 C/fdl-appendix.xml:204
msgid "Opaque"
msgstr "Opaque"
-#: C/fdl-appendix.xml:111(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:111
msgid ""
"A <_:quote-1/> copy of the <_:link-2/> means a machine-readable copy, "
"represented in a format whose specification is available to the general "
"comme une Copie Transparente. Une copie qui n'est pas <_:quote-3/> est "
"considérée, par opposition, comme <_:quote-4/>."
-#: C/fdl-appendix.xml:142(para/quote) C/fdl-appendix.xml:146(para/quote)
-#: C/fdl-appendix.xml:250(para/link) C/fdl-appendix.xml:266(para/link)
-#: C/fdl-appendix.xml:281(para/link) C/fdl-appendix.xml:352(para/link)
+#. (itstool) path: para/quote
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:142 C/fdl-appendix.xml:146 C/fdl-appendix.xml:250
+#: C/fdl-appendix.xml:266 C/fdl-appendix.xml:281 C/fdl-appendix.xml:352
msgid "Title Page"
msgstr "Page de titre"
-#: C/fdl-appendix.xml:141(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:141
msgid ""
"The <_:quote-1/> means, for a printed book, the title page itself, plus such "
"following pages as are needed to hold, legibly, the material this License "
"dessus, la <_:quote-2/> désigne le texte qui s'apparente le plus au titre du "
"document et situé avant le texte principal."
-#: C/fdl-appendix.xml:166(para/link) C/fdl-appendix.xml:551(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:166 C/fdl-appendix.xml:551
msgid "section 3"
msgstr "section 3"
-#: C/fdl-appendix.xml:154(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:154
msgid ""
"You may copy and distribute the <_:link-1/> in any medium, either "
"commercially or noncommercially, provided that this License, the copyright "
"des copies. Si vous distribuez une grande quantité de copies, référez-vous "
"aux dispositions de la <_:link-2/>."
-#: C/fdl-appendix.xml:177(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:177
msgid ""
"If you publish printed copies of the <_:link-1/> numbering more than 100, "
"and the Document's license notice requires <_:link-2/>, you must enclose the "
"comme des copies conformes, à condition que le titre du <_:link-3/> soit "
"préservé et que les conditions indiquées précédemment soient respectées."
-#: C/fdl-appendix.xml:202(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:202
msgid ""
"If you publish or distribute <_:link-1/> copies of the <_:link-2/> numbering "
"more than 100, you must either include a machine-readable <_:link-3/> copy "
"transparente durant une année pleine après la diffusion publique de la "
"dernière Copie opaque(directement ou via vos revendeurs)."
-#: C/fdl-appendix.xml:222(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:222
msgid ""
"It is requested, but not required, that you contact the authors of the <_:"
"link-1/> well before redistributing any large number of copies, to give them "
"nombre de copies, afin de lui permettre de vous donner une version à jour du "
"Document."
-#: C/fdl-appendix.xml:236(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:236
msgid "2"
msgstr "2"
-#: C/fdl-appendix.xml:237(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:237
msgid "3"
msgstr "3"
-#: C/fdl-appendix.xml:232(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:232
msgid ""
"You may copy and distribute a <_:link-1/> of the <_:link-2/> under the "
"conditions of sections <_:link-3/> and <_:link-4/> above, provided that you "
"de modifier cette Version modifiée à quiconque en possède une copie. De "
"plus, vous devez effectuer les actions suivantes dans la Version modifiée :"
-#: C/fdl-appendix.xml:249(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:249
msgid ""
"Use in the <_:link-1/> (and on the covers, if any) a title distinct from "
"that of the <_:link-2/>, and from those of previous versions (which should, "
"dans la section Historique du Document). Vous pouvez utiliser le même titre "
"si l'éditeur d'origine vous en a donné expressément la permission."
-#: C/fdl-appendix.xml:265(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:265
msgid ""
"List on the <_:link-1/>, as authors, one or more persons or entities "
"responsible for authorship of the modifications in the <_:link-2/>, together "
"au moins les cinq principaux auteurs du <_:link-3/> (ou tous les auteurs "
"s'il y en a moins de cinq)."
-#: C/fdl-appendix.xml:280(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:280
msgid ""
"State on the <_:link-1/> the name of the publisher of the <_:link-2/>, as "
"the publisher."
"Préciser sur la <_:link-1/> le nom de l'éditeur de la <_:link-2/>, en tant "
"qu'éditeur du Document."
-#: C/fdl-appendix.xml:292(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:292
msgid "Preserve all the copyright notices of the <_:link-1/>."
msgstr ""
"Préserver intégralement toutes les notices de copyright du <_:link-1/>."
-#: C/fdl-appendix.xml:312(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:312
msgid ""
"Include, immediately after the copyright notices, a license notice giving "
"the public permission to use the <_:link-1/> under the terms of this "
"quiconque l'autorisation d'utiliser la <_:link-1/> selon les termes de cette "
"Licence, sous la forme présentée dans l'annexe indiquée ci-dessous."
-#: C/fdl-appendix.xml:330(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:330
msgid "Document's"
msgstr "Document"
-#: C/fdl-appendix.xml:325(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:325
msgid ""
"Preserve in that license notice the full lists of <_:link-1/> and required "
"<_:link-2/> given in the <_:link-3/> license notice."
"Préserver dans cette notice la liste complète des <_:link-1/> et les <_:"
"link-2/> donnés avec la notice de la Licence du <_:link-3/>."
-#: C/fdl-appendix.xml:348(para/quote) C/fdl-appendix.xml:353(para/quote)
-#: C/fdl-appendix.xml:372(para/quote) C/fdl-appendix.xml:507(para/quote)
-#: C/fdl-appendix.xml:508(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:348 C/fdl-appendix.xml:353 C/fdl-appendix.xml:372
+#: C/fdl-appendix.xml:507 C/fdl-appendix.xml:508
msgid "History"
msgstr "Historique"
-#: C/fdl-appendix.xml:347(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:347
msgid ""
"Preserve the section entitled <_:quote-1/>, and its title, and add to it an "
"item stating at least the title, year, new authors, and publisher of the <_:"
"Document tel que précisé sur la Page de titre,et ajouter une entrée "
"décrivant la Version modifiée tel que précisé dans la phrase précédente."
-#: C/fdl-appendix.xml:366(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:366
msgid ""
"Preserve the network location, if any, given in the <_:link-1/> for public "
"access to a <_:link-2/> copy of the Document, and likewise the network "
"datant de plus de quatre ans avant la version courante ou si l'éditeur "
"d'origine vous en accorde la permission."
-#: C/fdl-appendix.xml:385(para/quote) C/fdl-appendix.xml:509(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:385 C/fdl-appendix.xml:509
msgid "Acknowledgements"
msgstr "Remerciements"
-#: C/fdl-appendix.xml:386(para/quote) C/fdl-appendix.xml:510(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:386 C/fdl-appendix.xml:510
msgid "Dedications"
msgstr "Dédicaces"
-#: C/fdl-appendix.xml:384(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:384
msgid ""
"In any section entitled <_:quote-1/> or <_:quote-2/>, preserve the section's "
"title, and preserve in the section all the substance and tone of each of the "
"personnes auxquelles s'adressent ces remerciements doivent être conservées, "
"ainsi que le titre de ces sections."
-#: C/fdl-appendix.xml:397(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:397
msgid ""
"Preserve all the <_:link-1/> of the <_:link-2/>, unaltered in their text and "
"in their titles. Section numbers or the equivalent are not considered part "
"textes, ni dans leurs titres. Les numéros de sections ne sont pas considérés "
"comme faisant partie du texte des sections."
-#: C/fdl-appendix.xml:412(para/quote) C/fdl-appendix.xml:424(para/quote)
-#: C/fdl-appendix.xml:445(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:412 C/fdl-appendix.xml:424 C/fdl-appendix.xml:445
msgid "Endorsements"
msgstr "Approbations"
-#: C/fdl-appendix.xml:410(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:410
msgid ""
"Delete any section entitled <_:quote-1/>. Such a section may not be included "
"in the <_:link-2/>."
"Effacer toute section intitulée <_:quote-1/>. Une telle section ne peut pas "
"être incluse dans une <_:link-2/>."
-#: C/fdl-appendix.xml:425(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:425
msgid "Invariant Section"
msgstr "Section inaltérable"
-#: C/fdl-appendix.xml:422(formalpara/para)
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:422
msgid ""
"Do not retitle any existing section as <_:quote-1/> or to conflict in title "
"with any <_:link-2/>."
"Ne pas renommer une section existante sous le titre <_:quote-1/> ou sous un "
"autre titre entrant en conflit avec le titre d'une <_:link-2/>."
-#: C/fdl-appendix.xml:432(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:432
msgid ""
"If the <_:link-1/> includes new front-matter sections or appendices that "
"qualify as <_:link-2/> and contain no material copied from the Document, you "
"link-3/> au sein de la notice de Licence de la Version modifiée. Ces titres "
"doivent êtres distincts des titres des autres sections."
-#: C/fdl-appendix.xml:444(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:444
msgid ""
"You may add a section entitled <_:quote-1/>, provided it contains nothing "
"but endorsements of your <_:link-2/> by various parties--for example, "
"du texte par une organisation le reconnaissant comme étant la définition "
"d'un standard)."
-#: C/fdl-appendix.xml:455(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:455
msgid "Front-Cover Text"
msgstr "première page de couverture"
-#: C/fdl-appendix.xml:457(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:457
msgid "Back-Cover Text"
msgstr "dernière page de couverture"
-#: C/fdl-appendix.xml:453(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:453
msgid ""
"You may add a passage of up to five words as a <_:link-1/>, and a passage of "
"up to 25 words as a <_:link-2/>, to the end of the list of <_:link-3/> in "
"passage si vous avez expressément obtenu l'autorisation de l'éditeur de "
"celui-ci."
-#: C/fdl-appendix.xml:470(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:470
msgid ""
"The author(s) and publisher(s) of the <_:link-1/> do not by this License "
"give permission to use their names for publicity for or to assert or imply "
"des éditeurs de ce <_:link-1/> à des fins publicitaires ou pour prétendre à "
"l'approbation d'une <_:link-2/>."
-#: C/fdl-appendix.xml:484(para/link) C/fdl-appendix.xml:566(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:484 C/fdl-appendix.xml:566
msgid "section 4"
msgstr "section 4"
-#: C/fdl-appendix.xml:481(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:481
msgid ""
"You may combine the <_:link-1/> with other documents released under this "
"License, under the terms defined in <_:link-2/> above for modified versions, "
"dans la liste des Sections inaltérables de la notice de Licence du document "
"résultant de la fusion."
-#: C/fdl-appendix.xml:492(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:492
msgid ""
"The combined work need only contain one copy of this License, and multiple "
"identical <_:link-1/> may be replaced with a single copy. If there are "
"mêmes modifications doivent être réalisées dans la liste des Sections "
"inaltérables de la notice de Licence du document final."
-#: C/fdl-appendix.xml:511(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:511
msgid "Endorsements."
msgstr "Approbations"
-#: C/fdl-appendix.xml:505(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:505
msgid ""
"In the combination, you must combine any sections entitled <_:quote-1/> in "
"the various original documents, forming one section entitled <_:quote-2/>; "
">. De même, vous devez rassembler les sections <_:quote-3/> et <_:quote-4/>. "
"Vous devez supprimer toutes les sections <_:quote-5/>."
-#: C/fdl-appendix.xml:517(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:517
msgid ""
"You may make a collection consisting of the <_:link-1/> and other documents "
"released under this License, and replace the individual copies of this "
"chacun de ces documents l'ensemble des règles de cette Licence concernant "
"les copies conformes."
-#: C/fdl-appendix.xml:546(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:546
msgid "aggregate"
msgstr "agrégat"
-#: C/fdl-appendix.xml:550(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:550
msgid "Cover Text"
msgstr "Textes de couverture"
-#: C/fdl-appendix.xml:538(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:538
msgid ""
"A compilation of the <_:link-1/> or its derivatives with other separate and "
"independent documents or works, in or on a volume of a storage or "
"Dans le cas contraire, ils doivent apparaître sur les pages de couverture de "
"l'agrégat complet."
-#: C/fdl-appendix.xml:562(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:562
msgid ""
"Translation is considered a kind of modification, so you may distribute "
"translations of the <_:link-1/> under the terms of <_:link-2/>. Replacing <_:"
"traduction et la version originale en anglais, c'est cette dernière qui "
"prévaut."
-#: C/fdl-appendix.xml:581(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:581
msgid ""
"You may not copy, modify, sublicense, or distribute the <_:link-1/> except "
"as expressly provided for under this License. Any other attempt to copy, "
"sur le document sous couvert de cette Licence ne voient pas leurs droits "
"révoqués tant qu'elles en respectent les principes."
-#: C/fdl-appendix.xml:597(para/ulink)
+#. (itstool) path: para/ulink
+#: C/fdl-appendix.xml:597
msgid "Free Software Foundation"
msgstr "Free Software Foundation"
-#: C/fdl-appendix.xml:603(para/ulink)
+#. (itstool) path: para/ulink
+#: C/fdl-appendix.xml:603
msgid "http://www.gnu.org/copyleft/"
msgstr "http://www.gnu.org/copyleft/"
-#: C/fdl-appendix.xml:595(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:595
msgid ""
"The <_:ulink-1/> may publish new, revised versions of the GNU Free "
"Documentation License from time to time. Such new versions will be similar "
"particuliers en fonction de nouvelles questions ou nouveaux problèmes. Voyez "
"<_:ulink-2/> pour plus de détails."
-#: C/fdl-appendix.xml:610(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:610
msgid "or any later version"
msgstr "ou toute autre version ultérieure"
-#: C/fdl-appendix.xml:606(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:606
msgid ""
"Each version of the License is given a distinguishing version number. If the "
"<_:link-1/> specifies that a particular numbered version of this License <_:"
"version n'est spécifié, vous pouvez choisir n'importe quelle version "
"officielle publiée par la Free Software Foundation."
-#: C/fdl-appendix.xml:639(para/link) C/fdl-appendix.xml:651(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:639 C/fdl-appendix.xml:651
msgid "Front-Cover Texts"
msgstr "texte de première page de couverture"
-#: C/fdl-appendix.xml:640(para/link) C/fdl-appendix.xml:654(para/link)
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:640 C/fdl-appendix.xml:654
msgid "Back-Cover Texts"
msgstr "texte de dernière page de couverture"
-#: C/fdl-appendix.xml:632(blockquote/para)
+#. (itstool) path: blockquote/para
+#: C/fdl-appendix.xml:632
msgid ""
"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 "
"TEXTE DE DERNIÈRE PAGE DE COUVERTURE. Une copie de cette Licence est incluse "
"dans la section appelée <_:quote-4/> de ce document."
-#: C/fdl-appendix.xml:649(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:649
msgid "with no Invariant Sections"
msgstr "pas de section inaltérable"
-#: C/fdl-appendix.xml:652(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:652
msgid "no Front-Cover Texts"
msgstr "pas de texte de première page de couverture"
-#: C/fdl-appendix.xml:653(para/quote)
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:653
msgid "Front-Cover Texts being LIST"
msgstr ""
"texte de première page de couverture suivant TEXTE DE PREMIÈRE PAGE DE "
"COUVERTURE"
-#: C/fdl-appendix.xml:647(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:647
msgid ""
"If you have no <_:link-1/>, write <_:quote-2/> instead of saying which ones "
"are invariant. If you have no <_:link-3/>, write <_:quote-4/> instead of <_:"
"pas de <_:link-3/>, écrivez <_:quote-4/> au lieu de <_:quote-5/>; de même "
"pour le <_:link-6/>."
-#: C/fdl-appendix.xml:661(para/ulink)
+#. (itstool) path: para/ulink
+#: C/fdl-appendix.xml:661
msgid "GNU General Public License"
msgstr "Licence Publique Générale GNU"
-#: C/fdl-appendix.xml:657(sect1/para)
+#. (itstool) path: sect1/para
+#: C/fdl-appendix.xml:657
msgid ""
"If your document contains nontrivial examples of program code, we recommend "
"releasing these examples in parallel under your choice of free software "
"recommandons de distribuer ces exemples en parallèle sous <_:ulink-1/>, qui "
"permet leur usage dans les logiciels libres."
+#~ msgid "1.18.1"
+#~ msgstr "1.18.1"
+
+#~ msgid ""
+#~ "<guilabel>Generating the \"template\" files.</guilabel> "
+#~ "<application>gtkdoc-mktmpl</application> creates a number of files in the "
+#~ "<filename class=\"directory\">tmpl/</filename> subdirectory, using the "
+#~ "information gathered in the first step. (Note that this can be run "
+#~ "repeatedly. It will try to ensure that no documentation is ever lost.)"
+#~ msgstr ""
+#~ "<guilabel>Génération des fichiers « prototypes ».</guilabel> "
+#~ "<application>gtkdoc-mktmpl</application> crée un certain nombre de "
+#~ "fichiers dans le sous-répertoire <filename class=\"directory\">tmpl/</"
+#~ "filename>, en utilisant les informations récoltées lors de la première "
+#~ "étape (notez que le script peut être exécuté plusieurs fois, il est fait "
+#~ "en sorte qu'aucune donnée ne soit jamais perdue)."
+
+#~ msgid ""
+#~ "Since GTK-Doc 1.9 the templates can be avoided. We encourage people to "
+#~ "keep documentation in the code. <application>gtkdocize</application> "
+#~ "supports now a <option>--flavour no-tmpl</option> option that chooses a "
+#~ "makefile that skips tmpl usage totally. If you have never changed file in "
+#~ "tmpl by hand, please remove the directory (e.g. from version control "
+#~ "system)."
+#~ msgstr ""
+#~ "Depuis GTK-Doc 1.9, les prototypes peuvent être évités. Nous encourageons "
+#~ "tout le monde à conserver la documentation dans le code. "
+#~ "<application>gtkdocize</application> prend maintenant en charge l'option "
+#~ "<option>--flavour no-tmpl</option> qui choisit un makefile qui évite "
+#~ "complètement l'utilisation de tmpl. Si vous n'avez jamais modifié de "
+#~ "fichiers à la main dans tmpl, effacez le répertoire (par ex. à partir "
+#~ "d'un système de gestion de versions)."
+
+#~ msgid ""
+#~ "<guilabel>DocBook DTD v3.0</guilabel> - This is the DocBook SGML DTD. "
+#~ "<ulink url=\"http://www.ora.com/davenport\" type=\"http\">http://www.ora."
+#~ "com/davenport</ulink>"
+#~ msgstr ""
+#~ "<guilabel>DocBook DTD v3.0</guilabel> - ce sont les DTD DocBook SGML. "
+#~ "<ulink url=\"http://www.ora.com/davenport\" type=\"http\">http://www.ora."
+#~ "com/davenport</ulink>"
+
+#~ msgid ""
+#~ "<guilabel>Jade v1.1</guilabel> - This is a DSSSL processor for converting "
+#~ "SGML to various formats. <ulink url=\"http://www.jclark.com/jade\" type="
+#~ "\"http\">http://www.jclark.com/jade</ulink>"
+#~ msgstr ""
+#~ "<guilabel>Jade v1.1</guilabel> - c'est un moteur DSSSL pour convertir le "
+#~ "SGML en divers formats. <ulink url=\"http://www.jclark.com/jade\" type="
+#~ "\"http\">http://www.jclark.com/jade</ulink>"
+
+#~ msgid ""
+#~ "<guilabel>Modular DocBook Stylesheets</guilabel> This is the DSSSL code "
+#~ "to convert DocBook to HTML (and a few other formats). It's used together "
+#~ "with jade. I've customized the DSSSL code slightly, in gtk-doc.dsl, to "
+#~ "colour the program code listings/declarations, and to support global "
+#~ "cross-reference indices in the generated HTML. <ulink url=\"http://nwalsh."
+#~ "com/docbook/dsssl\" type=\"http\">http://nwalsh.com/docbook/dsssl</ulink>"
+#~ msgstr ""
+#~ "<guilabel>Modular DocBook Stylesheets</guilabel> - c'est le code DSSSL "
+#~ "utilisé pour convertir de DocBook vers HTML (ainsi que quelques autres "
+#~ "formats). Il est utilisé conjointement avec Jade. J'ai légèrement "
+#~ "personnalisé le code DSSSL, dans gtk-doc.dsl, pour coloriser les listings "
+#~ "de code du programme et les déclarations ainsi que pour prendre en charge "
+#~ "les indices globaux des références croisées dans le HTML généré. <ulink "
+#~ "url=\"http://nwalsh.com/docbook/dsssl\" type=\"http\">http://nwalsh.com/"
+#~ "docbook/dsssl</ulink>"
+
+#~ msgid ""
+#~ "<guilabel>docbook-to-man</guilabel> - if you want to create man pages "
+#~ "from the DocBook. I've customized the 'translation spec' slightly, to "
+#~ "capitalise section headings and add the 'GTK Library' title at the top of "
+#~ "the pages and the revision date at the bottom. There is a link to this on "
+#~ "<ulink url=\"http://www.ora.com/davenport\" type=\"http\">http://www.ora."
+#~ "com/davenport</ulink> NOTE: This does not work yet."
+#~ msgstr ""
+#~ "<guilabel>docbook-to-man</guilabel> - si vous souhaitez créer des pages "
+#~ "de manuel depuis DocBook. J'ai légèrement adapté les « spécifications de "
+#~ "traduction » pour mettre en majuscule les en-têtes de section et pour "
+#~ "ajouter le titre « GTK Library » en haut des pages et la date de révision "
+#~ "en bas. Il y a un lien sur cela ici <ulink url=\"http://www.ora.com/"
+#~ "davenport\" type=\"http\">http://www.ora.com/davenport</ulink>. Note : "
+#~ "cela ne fonctionne pas encore."
+
+#~ msgid ""
+#~ "There is no standard place where the DocBook Modular Stylesheets are "
+#~ "installed."
+#~ msgstr ""
+#~ "Il n'y a pas d'emplacement standard pour l'installation des feuilles de "
+#~ "styles modulaires de DocBook."
+
+#~ msgid ""
+#~ "GTK-Doc's configure script searches these 3 directories automatically:"
+#~ msgstr ""
+#~ "Les scripts d'installation de GTK-Doc cherchent dans ces trois "
+#~ "répertoires automatiquement :"
+
+#~ msgid ""
+#~ "<filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> (used by "
+#~ "RedHat)"
+#~ msgstr ""
+#~ "<filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> (utilisé "
+#~ "par Red Hat)"
+
+#~ msgid ""
+#~ "<filename> /usr/lib/dsssl/stylesheets/docbook </filename> (used by Debian)"
+#~ msgstr ""
+#~ "<filename> /usr/lib/dsssl/stylesheets/docbook </filename> (utilisé par "
+#~ "Debian)"
+
+#~ msgid "<filename> /usr/share/sgml/docbkdsl </filename> (used by SuSE)"
+#~ msgstr "<filename> /usr/share/sgml/docbkdsl </filename> (utilisé par SuSE)"
+
+#~ msgid ""
+#~ "If you have the stylesheets installed somewhere else, you need to "
+#~ "configure GTK-Doc using the option: <command> --with-dsssl-dir=<"
+#~ "PATH_TO_TOPLEVEL_STYLESHEETS_DIR> </command>"
+#~ msgstr ""
+#~ "Si les feuilles de styles sont installées autre part, vous devez "
+#~ "configurer GTK-Doc en utilisant l'option : <command>--with-dsssl-dir=<"
+#~ "CHEMIN_VERS_REPERTOIRE_RACINE_FEUILLES2STYLEs></command>."
+
+#~ msgid ""
+#~ "You may also want to enable GTK-Doc for the distcheck make target. Just "
+#~ "add the one line shown in the next example to your top-level "
+#~ "<filename>Makefile.am</filename>:"
+#~ msgstr ""
+#~ "Il est aussi possible d'activer GTK-Doc pour la cible distcheck de make. "
+#~ "Il faut juste ajouter la ligne suivante au fichier <filename>Makefile.am</"
+#~ "filename> du répertoire racine :"
+
+#~ msgid "Enable GTK-Doc during make distcheck"
+#~ msgstr "Activation de GTK-Doc pendant le « make distcheck »"
+
+#~ msgid ""
+#~ "\n"
+#~ "\n"
+#~ "DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc\n"
+#~ "\n"
+#~ " "
+#~ msgstr ""
+#~ "\n"
+#~ "\n"
+#~ "DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc\n"
+#~ "\n"
+#~ " "
+
+#~ msgid ""
+#~ "\n"
+#~ "\n"
+#~ "/**\n"
+#~ " * identifier:\n"
+#~ " *\n"
+#~ " * documentation ...\n"
+#~ " *\n"
+#~ " * # Sub heading #\n"
+#~ " *\n"
+#~ " * more documentation:\n"
+#~ " * - list item 1\n"
+#~ " * - list item 2\n"
+#~ " *\n"
+#~ " * Even more docs.\n"
+#~ " */\n"
+#~ "\n"
+#~ " "
+#~ msgstr ""
+#~ "\n"
+#~ "\n"
+#~ "/**\n"
+#~ " * identifier:\n"
+#~ " *\n"
+#~ " * documentation ...\n"
+#~ " *\n"
+#~ " * # Sub heading #\n"
+#~ " *\n"
+#~ " * more documentation:\n"
+#~ " * - list item 1\n"
+#~ " * - list item 2\n"
+#~ " *\n"
+#~ " * Even more docs.\n"
+#~ " */\n"
+#~ "\n"
+#~ " "
+
+#~ msgid ""
+#~ "Since GTK-Doc-1.18 the tool supports a subset or the <ulink url=\"http://"
+#~ "daringfireball.net/projects/markdown/\">markdown language</ulink>. One "
+#~ "can use it for sub-headings and simple itemized lists. On older GTK-Doc "
+#~ "versions the content will be rendered as it (the list items will appear "
+#~ "in one line separated by dashes). <_:example-1/>"
+#~ msgstr ""
+#~ "À partir de GTK-Doc 1.18, il est possible d'utiliser un sous-ensemble de "
+#~ "la <ulink url=\"http://daringfireball.net/projects/markdown/\">syntaxe "
+#~ "markdown</ulink>. On peut l'utiliser pour les sous-titres et les listes à "
+#~ "puces simples. Dans des versions plus anciennes de GTK-Doc, le contenu "
+#~ "est affiché tel quel (les éléments d'une liste sont affichés sur une "
+#~ "seule ligne, séparés par des tirets). <_:example-1/>"
+
+#~ msgid "(FIXME : Stability information)"
+#~ msgstr "(FIXME : informations de stabilité)"
+
+#~ msgid ""
+#~ "Also, take a look at gobject introspection annotation tags: http://live."
+#~ "gnome.org/GObjectIntrospection/Annotations"
+#~ msgstr ""
+#~ "Jetez un coup d'œil aux étiquettes d'annotation de l'introspection "
+#~ "gobject : http://live.gnome.org/GObjectIntrospection/Annotations"
+
#~ msgid "Chris"
#~ msgstr "Chris"
<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>
+ <author><firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> <affiliation> <address> <email>ensonic@users.sf.net</email> </address> </affiliation></author>
</authorgroup>
<publisher role="maintainer"><publishername>Projet GTK-Doc</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
<copyright><year>2000, 2005</year> <holder>Dan Mueth et Chris Lyttle</holder></copyright>
- <copyright>
- <year>2007-2015</year>
- <holder>Stefan Sauer (Kost)</holder>
- </copyright>
+ <copyright><year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder></copyright>
<!-- translators: uncomment this:
<copyright>
<revhistory>
<revision>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development</revremark>
+ </revision>
+ <revision>
<revnumber>1.28</revnumber>
<date>24 Mar 2018</date>
<authorinitials>ss</authorinitials>
<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>port all tools from perl/bash to python</revremark>
- </revision>
- <revision>
- <revnumber>1.25</revnumber>
- <date>21 March 2016</date>
- <authorinitials>ss</authorinitials>
- <revremark>bug fixes, test cleanups</revremark>
- </revision>
- <revision>
- <revnumber>1.24</revnumber>
- <date>29 May 2015</date>
- <authorinitials>ss</authorinitials>
- <revremark>bug fix</revremark>
- </revision>
- <revision>
- <revnumber>1.23</revnumber>
- <date>17 May 2015</date>
- <authorinitials>ss</authorinitials>
- <revremark>bug fix</revremark>
- </revision>
- <revision>
- <revnumber>1.22</revnumber>
- <date>07 May 2015</date>
- <authorinitials>ss</authorinitials>
- <revremark>bug fixes, dropping deprecated features</revremark>
- </revision>
- <revision>
- <revnumber>1.21</revnumber>
- <date>17 Jul 2014</date>
- <authorinitials>ss</authorinitials>
- <revremark>bug fixes, dropping deprecated features</revremark>
- </revision>
+ <revision><revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</authorinitials> <revremark>portage de tous les outils depuis perl/bash vers python</revremark></revision>
+ <revision><revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</authorinitials> <revremark>corrections d'anomalies, nettoyages de test</revremark></revision>
+ <revision><revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</authorinitials> <revremark>corrections d'anomalies</revremark></revision>
+ <revision><revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</authorinitials> <revremark>corrections d'anomalies
+</revremark></revision>
+ <revision><revnumber>1.22</revnumber> <date>07 May 2015</date> <authorinitials>ss</authorinitials> <revremark>corrections d'anomalies, abandon de fonctionnalités obsolètes</revremark></revision>
+ <revision><revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</authorinitials> <revremark>corrections d'anomalies, abandon de fonctionnalités obsolètes</revremark></revision>
<revision>
<revnumber>1.20</revnumber>
<date>16 Feb 2014</date>
<authorinitials>ss</authorinitials>
<revremark>bug fixes, markdown support, style improvements</revremark>
</revision>
- <revision>
- <revnumber>1.19</revnumber>
- <date>05 Jun 2013</date>
- <authorinitials>ss</authorinitials>
- <revremark>bug fixes</revremark>
- </revision>
- <revision>
- <revnumber>1.18</revnumber>
- <date>14 Sep 2011</date>
- <authorinitials>ss</authorinitials>
- <revremark>bug fixes, speedups, markdown support</revremark>
- </revision>
+ <revision><revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</authorinitials> <revremark>corrections d'anomalies</revremark></revision>
+ <revision><revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</authorinitials> <revremark>correction de bogues, amélioration de la vitesse de traitement, prise en charge de markdown</revremark></revision>
<revision><revnumber>1.17</revnumber> <date>26 février 2011</date> <authorinitials>sk</authorinitials> <revremark>mise à jour pour une correction de bogue urgente</revremark></revision>
<revision><revnumber>1.16</revnumber> <date>14 janvier 2011</date> <authorinitials>sk</authorinitials> <revremark>correctifs et améliorations de mise en page</revremark></revision>
<revision><revnumber>1.15</revnumber> <date>21 mai 2010</date> <authorinitials>sk</authorinitials> <revremark>corrections d'anomalies et de régressions</revremark></revision>
<para>GTK-Doc fonctionne en utilisant la documentation de fonctions placées dans le code source sous la forme de blocs de commentaires avec un formatage spécifique ou la documentation ajoutée aux fichiers prototypes que GTK-Doc utilise (notez cependant que GTK-Doc ne documente que les fonctions déclarées dans des fichiers d'en-tête ; il ne fait rien pour les fonctions statiques).</para>
- <para>
- GTK-Doc consists of a number of python scripts, each performing a different step
- in the process.
- </para>
+ <para>GTK-Doc consiste en un certain nombre de scripts Python, chacun réalisant une étape du processus.</para>
<para>Il y a 5 étapes principales :</para>
<orderedlist>
<listitem>
- <para><guilabel>Écriture de la documentation.</guilabel> L'auteur complète les fichiers sources avec la documentation pour chaque fonction, macro, union, etc. (dans le passé, l'information était saisie dans les fichiers prototypes générés mais ce n'est plus recommandé).</para>
+ <para>
+ <guilabel>Writing the documentation.</guilabel>
+
+ The author fills in the source files with the documentation for each
+ function, macro, structs or unions, etc.
+ </para>
</listitem>
<listitem>
Likewise <application>gtkdoc-mkpdf</application> turns the XML files into a PDF
document called <filename><package>.pdf</filename>.
</para>
- <para>
- Files in <filename class="directory">xml/</filename> and
- <filename class="directory">html/</filename> directories are always
- overwritten. One should never edit them directly.
- </para>
+ <para>Les fichiers dans les répertoires <filename class="directory">xml/</filename> et <filename class="directory">html/</filename> sont toujours écrasés. Il ne faut pas les modifier directement.</para>
</listitem>
<listitem>
<sect2 id="requirements">
<title>Pré-requis</title>
- <para>
- <guilabel>python 2/3</guilabel> - the main scripts are written in python.
- </para>
+ <para><guilabel>python 2/3</guilabel> - les principaux scripts sont écrits en Python.</para>
<para>
<guilabel>xsltproc</guilabel> - the xslt processor from libxslt
<ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink>
<sect1 id="aboutgtkdoc">
<title>À propos de GTK-Doc</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(À COMPLETER)</para>
<para>
- (History, authors, web pages, mailing list, license, future plans,
+ (authors, web pages, mailing list, license, future plans,
comparison with other similar systems.)
</para>
</chapter>
<chapter id="settingup">
- <title>Mise en place de votre projet</title>
+ <title>Project Setup</title>
+
+ <para>
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
- <para>Les sections suivantes décrivent les étapes à suivre pour intégrer GTK-Doc dans votre projet. Nous allons supposer que vous travaillez sur un projet appelé « meep ». Ce projet contient une bibliothèque appelée « libmeep » et une application « meeper ». Nous supposons également que vous utilisez autoconf et automake. Dans le cas contraire, la section <link linkend="plain_makefiles">« makefiles » simples et autres systèmes de compilation</link> décrit les éléments de base à respecter pour travailler dans une autre configuration de construction.</para>
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
+ </para>
<sect1 id="settingup_docfiles">
<title>Mise en place du squelette de documentation</title>
- <para>Dans le répertoire racine de votre projet, créez les répertoires appelés docs/reference (de la même façon, vous pouvez avoir docs/help pour la documentation utilisateur). Il est recommandé de créer un autre sous-répertoire portant le nom du paquet de documentation. Pour les paquets qui contiennent seulement une bibliothèque, cette étape n'est pas nécessaire.</para>
+ <para>
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
+ </para>
+
+ <para>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
- <para>Cela peut ressembler à ce qui suit : <example><title>Exemple d'arborescence de répertoires</title>
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
<programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
]]></programlisting>
- </example></para>
+ </example>
+ </para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>Intégration avec autoconf</title>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
- <para>C'est très simple ! Il faut juste ajouter une ligne dans votre script <filename>configure.ac</filename>.</para>
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>Intégration avec autoconf</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-]]></programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>Cela impose à tous les développeurs d'installer gtk-doc. Si pour votre projet, vous pouvez avoir une configuration de construction api-doc optionnelle, vous pouvez résoudre ce problème comme ci-dessous. Ne le modifiez pas car gtkdocize recherche <function>GTK_DOC_CHECK</function> au début d'une ligne. <example><title>Laisser gtk-doc optionnel</title>
- <programlisting><![CDATA[
-# 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>
+ <sect2 id="settingup_automake">
+ <title>Intégration avec automake</title>
- <para>Le premier argument est utilisé pour vérifier le paramètre gtkdocversion au moment de la configuration. Le second, en option, est utilisé par <application>gtkdocize</application>. La macro <symbol>GTK_DOC_CHECK</symbol> ajoute également plusieurs drapeaux de configuration :</para>
- <orderedlist>
- <listitem><para>--with-html-dir=CHEMIN : répertoire d'installation de la documentation,</para></listitem>
- <listitem><para>--enable-gtk-doc : utilisation de gtk-doc pour construire la documentation [par défaut=no],</para></listitem>
- <listitem><para>--enable-gtk-doc-html : construction de la documentation au format html [par défaut=yes],</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : construction de la documentation au format pdf [par défaut=no].</para></listitem>
- </orderedlist>
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
- <important>
- <para>GTK-Doc est désactivé par défaut ! N'oubliez pas de passer l'option <option>'--enable-gtk-doc'</option> lors de la prochaine exécution du script <filename>configure</filename>. Dans le cas contraire, la documentation pré-générée est installée (ce qui a du sens pour les utilisateurs mais pas pour les développeurs).</para>
- </important>
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
+ <programlisting>
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
+</programlisting>
+ </example>
- <para>
- Furthermore it is recommended that you have the following line inside
- your <filename>configure.ac</filename> script.
- This allows <application>gtkdocize</application> to automatically copy the
- macro definition for <function>GTK_DOC_CHECK</function> to your project.
- </para>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
- <para>
- <example><title>Préparation pour gtkdocize</title>
- <programlisting><![CDATA[
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
+
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
+
+ All the tools support <option>--help</option> to list the supported
+ options.
+ </para>
+
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>Intégration avec autoconf</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
]]></programlisting>
- </example>
- </para>
- <para>
- After all changes to <filename>configure.ac</filename> are made, update
- the <filename>configure</filename> file. This can be done by re-running
- <code>autoreconf -i</code> or <code>autogen.sh</code>.
- </para>
- </sect1>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>Intégration avec automake</title>
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub directory of the
- <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
- to your project's API documentation directory (
- <filename class="directory">./docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple doc-packages repeat this for each one.
- </para>
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <para>L'étape suivante est de modifier les options dans le fichier <filename>Makefile.am</filename>. Toutes les options sont accompagnées d'un commentaire au-dessus qui explique leur fonction. La plupart des options sont des paramètres supplémentaires qui sont passés aux outils respectifs. Chaque outil possède une variable de la forme <option><NOM_DE_L_OUTIL>_OPTIONS</option>. Tous les outils prennent en charge l'option <option>--help</option> qui affiche la liste des options prises en charge.</para>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <!-- FIXME: explain options ? -->
+ <orderedlist>
+ <listitem><para>--with-html-dir=CHEMIN : répertoire d'installation de la documentation,</para></listitem>
+ <listitem><para>--enable-gtk-doc : utilisation de gtk-doc pour construire la documentation [par défaut=no],</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : construction de la documentation au format html [par défaut=yes],</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
+ </orderedlist>
- </sect1>
+ <important>
+ <para>GTK-Doc est désactivé par défaut ! N'oubliez pas de passer l'option <option>'--enable-gtk-doc'</option> lors de la prochaine exécution du script <filename>configure</filename>. Dans le cas contraire, la documentation pré-générée est installée (ce qui a du sens pour les utilisateurs mais pas pour les développeurs).</para>
+ </important>
- <sect1 id="settingup_autogen">
- <title>Intégration avec autogen</title>
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- <para>La plupart des projets possède un script <filename>autogen.sh</filename> pour configurer l'infrastructure de compilation après un « checkout » depuis un système de gestion de versions (comme cvs/svn/git). GTK-Doc est livré avec un outil appelé <application>gtkdocize</application>, qui peut être utilisé dans un script comme celui-ci. Il doit être lancé avant autoheader, automake ou autoconf.</para>
+ <sect2 id="settingup_autogen">
+ <title>Intégration avec autogen</title>
- <para>
- <example><title>Exécution de gtkdocize depuis autogen.sh</title>
- <programlisting><![CDATA[
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
+
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
+
+ <para>
+ <example><title>Exécution de gtkdocize depuis autogen.sh</title>
+ <programlisting>
gtkdocize || exit 1
+</programlisting>
+ </example>
+ </para>
+
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
]]></programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>Lorsque <filename>gtkdocize</filename> est exécuté, il copie <filename>gtk-doc.make</filename> vers le répertoire racine de votre projet (ou tout autre répertoire désigné par l'option <option>--docdir</option>). Il vérifie également l'invocation de <function>GTK_DOC_CHECK</function> dans le script configure. Cette macro peut être utilisée pour transmettre des paramètres supplémentaires à <application>gtkdocize</application>.</para>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <para>Historiquement, GTK-Doc générait des fichiers prototypes dans lesquels les développeurs saisissaient la documentation. Il s'est avéré que ce n'était pas une bonne idée (comme le besoin de placer les fichiers générés dans le gestionnaire de versions). Depuis GTK-Doc 1.9, les outils peuvent récupérer toutes les informations à partir des commentaires dans les sources, ce qui permet d'éviter d'avoir des prototypes. Nous vous encourageons à conserver la documentation dans le code. <application>gtkdocize</application> prend maintenant en charge une option <option>--flavour=no-tmpl</option> qui choisit un makefile qui s'affranchit totalement de l'utilisation des fichiers prototypes (tmpl). En plus d'ajouter les options directement au moment de l'appel de la commande, elles peuvent être ajoutées également dans une variable d'environnement appelée <symbol>GTKDOCIZE_FLAGS</symbol> ou choisies comme deuxième paramètre dans la macro <symbol>GTK_DOC_CHECK</symbol> dans le script de configuration. Si aucune modification n'a été faite à la main dans les fichiers prototypes et si vous migrez à partir d'anciennes versions de gtkdoc, supprimez le répertoire (par ex. à partir du système de gestion de versions).</para>
- </sect1>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <sect1 id="settingup_firstrun">
- <title>Lancement de la construction de la documentation</title>
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
- <para>Après toutes ces étapes, il est temps de lancer la construction. Tout d'abord, il faut relancer <filename>autogen.sh</filename>. Si ce script lance « configure » pour vous, alors il faut ajouter l'option <option>--enable-gtk-doc</option>, sinon lancez manuellement <filename>configure</filename> suivi de cette option.</para>
- <para>La première exécution de make génère plusieurs fichiers supplémentaires dans les répertoires de documentation (doc-directories). Les plus importants sont : <filename><paquet>.types</filename>, <filename><paquet>-docs.xml</filename> (anciennement .sgml), <filename><paquet>-sections.txt</filename>.</para>
- <para>
- <example><title>Lancement de la construction de la documentation</title>
- <programlisting><![CDATA[
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>Après toutes ces étapes, il est temps de lancer la construction. Tout d'abord, il faut relancer <filename>autogen.sh</filename>. Si ce script lance « configure » pour vous, alors il faut ajouter l'option <option>--enable-gtk-doc</option>, sinon lancez manuellement <filename>configure</filename> suivi de cette option.</para>
+ <para>La première exécution de make génère plusieurs fichiers supplémentaires dans les répertoires de documentation (doc-directories). Les plus importants sont : <filename><paquet>.types</filename>, <filename><paquet>-docs.xml</filename> (anciennement .sgml), <filename><paquet>-sections.txt</filename>.</para>
+ <para>
+ <example><title>Lancement de la construction de la documentation</title>
+ <programlisting>
./autogen.sh --enable-gtk-doc
make
-]]></programlisting>
- </example>
- </para>
- <para>Maintenant, vous pouvez saisir l'adresse <filename>docs/reference/<paquet>/index.html</filename> dans votre navigateur. Le résultat est encore un peu décevant mais le prochain chapitre va expliquer comment donner de la vie à ces pages.</para>
+</programlisting>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>Intégration avec des systèmes de gestion de versions</title>
+ <sect1 id="settingup_cmake">
+ <title>Integration with CMake build systems</title>
<para>
- As a rule of thumb, it's the files you edit which should go under
- version control. For typical projects it's these files:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>,
- <filename>Makefile.am</filename>.
- </para>
- <para>
- Files in the <filename>xml/</filename> and <filename>html/</filename>
- directories should not go under version control. Neither should any of
- the <filename>.stamp</filename> files.
+ GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
+ (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
+ module). This provides a <literal>gtk_doc_add_module</literal>
+ command that you can set in your <filename>CMakeLists.txt</filename>
+ file.
</para>
+
+ <para>L'exemple suivant montre comment utiliser cette commande. <example><title>Exemple d'utilisation de GTK-Doc depuis CMake</title>
+ <programlisting>
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+</programlisting>
+ </example></para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Intégration avec des « makefiles » simples et d'autres systèmes de compilation</title>
<para>Dans les cas où l'emploi de automake n'est pas souhaité et donc sans fichier <filename>gtk-doc.mak</filename>, il s'agit alors d'appeler les outils gtkdoc dans le bon ordre dans les fichiers « makefiles » ad hoc (ou d'autres systèmes).</para>
<para>
<example><title>Étapes de construction de la documentation</title>
- <programlisting><![CDATA[
+ <programlisting>
DOC_MODULE=meep
// sources have changed
-gtkdoc-scan --module=$(DOC_MODULE) <source-dir>
+gtkdoc-scan --module=$(DOC_MODULE) <source-dir>
gtkdoc-scangobj --module=$(DOC_MODULE)
-gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>
+gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>
// xml files have changed
mkdir html
-cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
+cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
-]]></programlisting>
+</programlisting>
</example>
</para>
<para>Il s'agit d'examiner les fichiers <filename>Makefile.am</filename> et <filename>gtk-doc.mak</filename> pour y trouver les options supplémentaires nécessaires.</para>
</sect1>
- <sect1 id="cmake">
- <title>Integration with CMake build systems</title>
-
- <para>
- GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
- (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
- module). This provides a <literal>gtk_doc_add_module</literal>
- command that you can set in your <filename>CMakeLists.txt</filename>
- file.
- </para>
-
- <para>
- The following example shows how to use this command.
- <example><title>Example of using GTK-Doc from CMake</title>
- <programlisting><![CDATA[
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>Intégration avec des systèmes de gestion de versions</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>
+ As a rule of thumb, it's the files you edit which should go under
+ version control. For typical projects it's these files:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>,
+ <filename>Makefile.am</filename>.
+ </para>
+ <para>
+ Files in the <filename>xml/</filename> and <filename>html/</filename>
+ directories should not go under version control. Neither should any of
+ the <filename>.stamp</filename> files.
+ </para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
- </sect1>
</chapter>
<chapter id="documenting">
<para>GTK-Doc utilise les commentaires du code source, avec une syntaxe spéciale pour la documentation du code. En outre, il récupère des informations sur la structure de votre projet à partir d'autres sources. La section suivante vous donne toutes les informations concernant la syntaxe des commentaires.</para>
- <note>
- <title>Emplacement de la documentation</title>
- <para>Par le passé, la plupart de la documentation devait être placé dans des fichiers dans le répertoire <filename>tmpl</filename>. Les inconvénients étaient que l'information n'était pas souvent mise à jour et que ces fichiers avaient tendance à provoquer des conflits avec les systèmes de gestion de versions.</para>
- <para>Pour éviter ces problèmes, il est conseillé de placer la documentation dans le code source. Ce manuel ne décrit que cette manière de documenter du code.</para>
- </note>
-
<para>
- The scanner can handle the majority of C headers fine. In the case of
- receiving warnings from the scanner that look like a special case, one can
- hint GTK-Doc to skip over them.
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<title>Commentaires de documentation</title>
<para>Un commentaire multi-ligne qui commence avec un symbole « * » supplémentaire indique un bloc de documentation qui sera traité par les outils GTK-Doc. <example><title>Bloc de commentaire GTK-Doc</title>
- <programlisting><![CDATA[
+ <programlisting>
/**
* identifier:
* documentation ...
*/
-]]></programlisting>
+</programlisting>
</example></para>
<para>L'« identifier » (identifiant) est une ligne contenant le nom de l'élément avec lequel le commentaire est lié. La syntaxe diffère légèrement en fonction de l'élément. (À FAIRE : ajouter un tableau montrant les identifiants)</para>
</para>
<tip>
- <para>Comme indiqué plus tôt, GTK-Doc est fait pour documenter les API publiques. On ne peut donc pas écrire de la documentation pour les symboles statiques. Néanmoins, il est bon de commenter ces symboles aussi. Cela aide les autres à comprendre votre code. Par conséquent, nous recommandons de les documenter à l'aide de commentaires normaux (sans le second « * » à la première ligne). Si, plus tard, la fonction doit être rendue publique, il suffira juste d'ajouter un « * » dans le bloc de commentaires et d'ajouter le nom du symbole à la bonne place à l'intérieur du fichier des sections.</para>
+ <para>
+ As already mentioned earlier GTK-Doc is for documenting public API. Thus
+ one cannot write documentation for static symbols. Nevertheless it is good
+ to comment those symbols too. This helps other developers to understand
+ your code.
+ Therefore we recommend to comment these using normal comments (without the
+ 2nd '*' in the first line).
+ If later the function needs to be made public, all one needs to do is to
+ add another '*' in the comment block and insert the symbol name at the
+ right place inside the sections file.
+ </para>
</tip>
</sect1>
<para>
<example><title>Bloc de commentaires de section</title>
- <programlisting><![CDATA[
+ <programlisting>
/**
* SECTION:meepapp
* @short_description: the application class
*
* The application class handles ...
*/
-]]></programlisting>
+</programlisting>
</example>
</para>
</variablelist>
<example><title>Étiquettes générales</title>
- <programlisting><![CDATA[
+ <programlisting>
/**
* foo_get_bar:
* @foo: some foo
foo_get_bar(Foo *foo)
{
...
-]]></programlisting>
+</programlisting>
</example>
</sect2>
<para>d'indiquer si les objets, listes, chaînes, etc. retournés doivent être freed/unfreed/released,</para>
</listitem>
<listitem>
- <para>d'indiquer si les paramètres peuvent être NULL et ce qui se passe dans ce cas,</para>
+ <para>d'indiquer si les paramètres peuvent être NULL et ce qui se passe dans ce cas.</para>
</listitem>
<listitem>
- <para>de mentionner les pré-conditions et post-conditions intéressantes si nécessaire.</para>
+ <para>Mentionner les pré-conditions et post-conditions intéressantes si nécessaire.</para>
</listitem>
</itemizedlist></para>
<para>GTK-Doc considère que tous les symboles (macros, fonctions) commençant par « _ » sont privés. Ils sont traités comme des fonctions statiques.</para>
<example><title>Bloc de commentaires pour les fonctions</title>
- <programlisting><![CDATA[
+ <programlisting>
/**
* function_name:
* @par1: description of parameter 1. These can extend over more than
* Since: 2.2
* Deprecated: 2.18: Use other_function() instead.
*/
-]]></programlisting>
+</programlisting>
</example>
<variablelist><title>Étiquettes de fonction</title>
<sect2><title>Bloc de commentaires pour les propriétés</title>
<example><title>Bloc de commentaires pour les propriétés</title>
- <programlisting><![CDATA[
+ <programlisting>
/**
* SomeWidget:some-property:
*
* Here you can document a property.
*/
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
-]]></programlisting>
+</programlisting>
</example>
</sect2>
<para>N'oubliez pas : <itemizedlist>
<listitem>
- <para>d'indiquer quand le signal est émis et s'il est émis avant ou après d'autres signaux,</para>
+ <para>Documenter lorsque le signal est émis et s'il est émis avant ou après d'autres signaux,</para>
</listitem>
<listitem>
- <para>d'indiquer ce qu'une application peut faire dans le gestionnaire du signal.</para>
+ <para>Documenter ce qu'une application pourrait faire dans le gestionnaire du signal.</para>
</listitem>
</itemizedlist></para>
<sect2><title>Bloc de commentaire pour les structures</title>
<example><title>Bloc de commentaire pour les structures</title>
- <programlisting><![CDATA[
+ <programlisting>
/**
* FooWidget:
* @bar: some #gboolean
gboolean bar;
} FooWidget;
-]]></programlisting>
+</programlisting>
</example>
<para>Utilisez <code>/*< private >*/</code> avant les champs de structures privées que vous voulez cacher. Utilisez <code>/*< public >*/</code> dans le cas contraire.</para>
<sect2><title>Bloc de commentaire pour les énumérations</title>
<example><title>Bloc de commentaire pour les énumérations</title>
- <programlisting><![CDATA[
+ <programlisting>
/**
* Something:
* @SOMETHING_FOO: something foo
typedef enum {
SOMETHING_FOO,
SOMETHING_BAR,
- /*< private >*/
+ /*< private >*/
SOMETHING_COUNT
} Something;
-]]></programlisting>
+</programlisting>
</example>
<para>Utilisez <code>/*< private >*/</code> avant les valeurs d'énumérations privées que vous voulez cacher. Utilisez <code>/*< public >*/</code> dans le cas contraire.</para>
<sect2>
<title>Example of program documentation.</title>
- <example><title>Program documentation block</title>
+ <example><title>Bloc de documentation programme</title>
<programlisting><![CDATA[
/**
* PROGRAM:test-program
<para>Voici quelques balises DocBook très utiles pendant la conception de la documentation d'un code.</para>
<para>Pour créer un lien vers une autre section dans la documentation GTK : <informalexample>
- <programlisting><![CDATA[
-<link linkend="glib-Hash-Tables">Hash Tables</link>
-]]></programlisting>
+ <programlisting>
+<link linkend="glib-Hash-Tables">Hash Tables</link>
+</programlisting>
</informalexample> l'élément « linkend » est l'identifiant SGML/XML de l'élément le plus haut sur la page vers laquelle vous voulez pointer. Pour la plupart des pages, c'est en général la partie (« gtk », « gdk », « glib ») suivi du titre de la page (« Hash Tables »). Pour les éléments graphiques, c'est simplement le nom de la classe. Les espaces et les caractères de soulignement sont convertis en « - » pour être conforme au SGML/XML.</para>
<para>Pour faire référence à une fonction externe comme, par exemple, à une fonction C standard : <informalexample>
- <programlisting><![CDATA[
-<function>...</function>
-]]></programlisting>
+ <programlisting>
+<function>...</function>
+</programlisting>
</informalexample></para>
<para>Pour inclure des extraits de code : <informalexample>
- <programlisting><![CDATA[
-<example>
- <title>Using a GHashTable.</title>
- <programlisting>
+ <programlisting>
+<example>
+ <title>Using a GHashTable.</title>
+ <programlisting>
...
- </programlisting>
-</example>
-]]></programlisting>
+ </programlisting>
+</example>
+</programlisting>
</informalexample> ou ceci, pour des petits fragments de code qui ne nécessitent pas de titre : <informalexample>
- <programlisting><![CDATA[
-<informalexample>
- <programlisting>
+ <programlisting>
+<informalexample>
+ <programlisting>
...
- </programlisting>
-</informalexample>
-]]></programlisting>
+ </programlisting>
+</informalexample>
+</programlisting>
</informalexample> Pour ces derniers, GTK-Doc prend également en charge une abréviation : |[ ... ]|</para>
<para>Pour ajouter une liste à puces : <informalexample>
- <programlisting><![CDATA[
-<itemizedlist>
- <listitem>
- <para>
+ <programlisting>
+<itemizedlist>
+ <listitem>
+ <para>
...
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
...
- </para>
- </listitem>
-</itemizedlist>
-]]></programlisting>
+ </para>
+ </listitem>
+</itemizedlist>
+</programlisting>
</informalexample></para>
<para>Pour ajouter une note de bas de page : <informalexample>
- <programlisting><![CDATA[
-<note>
- <para>
+ <programlisting>
+<note>
+ <para>
Make sure you free the data after use.
- </para>
-</note>
-]]></programlisting>
+ </para>
+</note>
+</programlisting>
</informalexample></para>
<para>Pour se référer à un type : <informalexample>
- <programlisting><![CDATA[
-<type>unsigned char</type>
-]]></programlisting>
+ <programlisting>
+<type>unsigned char</type>
+</programlisting>
</informalexample></para>
<para>Pour se référer à une structure externe (non décrite dans la documentation GTK) : <informalexample>
- <programlisting><![CDATA[
-<structname>XFontStruct</structname>
-]]></programlisting>
+ <programlisting>
+<structname>XFontStruct</structname>
+</programlisting>
</informalexample></para>
<para>Pour se référer à un champ d'une structure : <informalexample>
- <programlisting><![CDATA[
-<structfield>len</structfield>
-]]></programlisting>
+ <programlisting>
+<structfield>len</structfield>
+</programlisting>
</informalexample></para>
<para>Pour se référer au nom d'une classe, il est possible d'utiliser : <informalexample>
- <programlisting><![CDATA[
-<classname>GtkWidget</classname>
-]]></programlisting>
+ <programlisting>
+<classname>GtkWidget</classname>
+</programlisting>
</informalexample> mais vous utiliserez probablement #GtkWidget à la place (pour créer automatiquement un lien vers la page GtkWidget - consultez <link linkend="documenting_syntax">les raccourcis</link>).</para>
<para>Pour mettre en évidence un texte : <informalexample>
- <programlisting><![CDATA[
-<emphasis>This is important</emphasis>
-]]></programlisting>
+ <programlisting>
+<emphasis>This is important</emphasis>
+</programlisting>
</informalexample></para>
<para>Pour les noms de fichiers : <informalexample>
- <programlisting><![CDATA[
-<filename>/home/user/documents</filename>
-]]></programlisting>
+ <programlisting>
+<filename>/home/user/documents</filename>
+</programlisting>
</informalexample></para>
<para>Pour se référer à des touches : <informalexample>
- <programlisting><![CDATA[
-<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
-]]></programlisting>
+ <programlisting>
+<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
+</programlisting>
</informalexample></para>
</sect1>
<para>Il y a plusieurs fichiers supplémentaires, qui ont besoin d'être maintenus en parallèle aux commentaires dans le code source : <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (anciennement .sgml), <filename><package>-sections.txt</filename>.</para>
<sect1 id="metafiles_types">
- <title>Édition du fichier « types »</title>
+ <title>Édition des fichiers types</title>
<para>
If your library or application includes GObjects, you want
</para>
<para>
- <example><title>Extrait d'un exemple de fichier « types »</title>
- <programlisting><![CDATA[
-#include <gtk/gtk.h>
+ <example><title>Example <package>.types file</title>
+ <programlisting>
+#include <gtk/gtk.h>
gtk_accel_label_get_type
gtk_adjustment_get_type
gtk_alignment_get_type
gtk_arrow_get_type
-]]></programlisting>
+</programlisting>
</example>
</para>
<para>
<example><title>En-tête du document maître</title>
- <programlisting><![CDATA[
-<bookinfo>
- <title>MODULENAME Reference Manual</title>
- <releaseinfo>
+ <programlisting>
+<bookinfo>
+ <title>MODULENAME Reference Manual</title>
+ <releaseinfo>
for MODULENAME [VERSION]
The latest version of this documentation can be found on-line at
- <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>.
- </releaseinfo>
-</bookinfo>
+ <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>.
+ </releaseinfo>
+</bookinfo>
-<chapter>
- <title>[Insert title here]</title>
-]]></programlisting>
+<chapter>
+ <title>[Insert title here]</title>
+</programlisting>
</example>
</para>
</para>
<para>
- <example><title>Optional part in the master document</title>
+ <example><title>Partie optionnelle dans le document maître</title>
<programlisting><![CDATA[
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
<para>
<example><title>Including generated sections</title>
- <programlisting><![CDATA[
- <chapter>
- <title>my library</title>
- <xi:include href="xml/object.xml"/>
+ <programlisting>
+ <chapter>
+ <title>my library</title>
+ <xi:include href="xml/object.xml"/>
...
-]]></programlisting>
+</programlisting>
</example>
</para>
<para>
<example><title>Including generated sections</title>
- <programlisting><![CDATA[
-<INCLUDE>libmeep/meep.h</INCLUDE>
+ <programlisting>
+<INCLUDE>libmeep/meep.h</INCLUDE>
-<SECTION>
-<FILE>meepapp</FILE>
-<TITLE>MeepApp</TITLE>
+<SECTION>
+<FILE>meepapp</FILE>
+<TITLE>MeepApp</TITLE>
MeepApp
-<SUBSECTION Standard>
+<SUBSECTION Standard>
MEEP_APP
...
MeepAppClass
meep_app_get_type
-</SECTION>
-]]></programlisting>
+</SECTION>
+</programlisting>
</example>
</para>
</chapter>
<chapter id="modernizing">
- <title>Modernizing the documentation</title>
+ <title>Modernisation de la documentation</title>
<para>
GTK-Doc has been around for quite some time. In this section we list new
</para>
<sect1 id="modernizing-gtk-doc-1-9">
- <title>GTK-Doc 1.9</title>
+ <title>Manuel de GTK-Doc 1.9</title>
<para>
When using xml instead of sgml, one can actually name the master
</sect1>
<sect1 id="modernizing-gtk-doc-1-10">
- <title>GTK-Doc 1.10</title>
+ <title>Manuel de GTK-Doc 1.10</title>
<para>
This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in
</sect1>
<sect1 id="modernizing-gtk-doc-1-16">
- <title>GTK-Doc 1.16</title>
+ <title>Manuel de GTK-Doc 1.16</title>
<para>
This version includes a new tool called gtkdoc-check. This tool can run
</sect1>
<sect1 id="modernizing-gtk-doc-1-20">
- <title>GTK-Doc 1.20</title>
+ <title>Manuel de GTK-Doc 1.20</title>
<para>
Version 1.18 brought some initial markdown support. Using markdown in
</sect1>
<sect1 id="modernizing-gtk-doc-1-25">
- <title>GTK-Doc 1.25</title>
+ <title>Manuel de GTK-Doc 1.25</title>
<para>
The makefiles shipped with this version generate an entity file at <filename>xml/gtkdocentities.ent</filename>,
containing entities for e.g. package_name and package_version. You can
use this e.g. in the main xml file to avoid hardcoding the version
number. Below is an example that shows how the entity file is included
- and how the entities are used. The entities can also be used in all
+ in the master template and how the entities are used.
+ The entities can also be used in all
generated files, GTK-Doc will use the same xml header in generated xml
files.
<example><title>Use pre-generated entities</title>
<para>
<example><title>Contrôles « configure » supplémentaires</title>
- <programlisting><![CDATA[
+ <programlisting>
AC_ARG_ENABLE(man,
[AC_HELP_STRING([--enable-man],
[regenerate man pages from Docbook [default=no]])],enable_man=yes,
AC_PATH_PROG([XSLTPROC], [xsltproc])
AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)
-]]></programlisting>
+</programlisting>
</example>
</para>
</sect2>
<para>
<example><title>Contrôles « configure » supplémentaires</title>
- <programlisting><![CDATA[
+ <programlisting>
man_MANS = \
meeper.1
if ENABLE_MAN
%.1 : %.xml
- @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+ @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
endif
endif
BUILT_EXTRA_DIST = $(man_MANS)
EXTRA_DIST += meep.xml
-]]></programlisting>
+</programlisting>
</example>
</para>
</sect2>
<segmentedlist>
<?dbhtml list-presentation="list"?>
- <segtitle>Question </segtitle>
- <segtitle>Réponse </segtitle>
+ <segtitle>Question</segtitle>
+ <segtitle>Réponse</segtitle>
<seglistitem>
<seg>Pas de hiérarchie de classe.</seg>
<seg>Les fonctions objet <function>xxx_get_type()</function> n'ont pas été saisies dans le fichier <filename><module>.types</filename>.</seg>
<!-- docbook warnings: -->
<seglistitem>
<seg>« ID » multiples pour le linkend: XYZ contraint</seg>
- <seg>Le symbole XYZ apparaît en double dans le fichier <filename><module>-sections.txt</filename>.</seg>
+ <seg>Le symbole XYZ apparaît en double dans le fichier <filename><package>-sections.txt</filename>.</seg>
</seglistitem>
<seglistitem>
<seg>Élément typename dans l'espace de nom '' rencontré dans para mais aucun prototype ne correspond.</seg>
<chapter id="contrib">
<title>Outils liés à gtk-doc</title>
- <para>
- GtkDocPlugin - a <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink>
- integration plugin, that adds API docs to a trac site and integrates with
- the trac search.
- </para>
+ <para>GtkDocPlugin - un greffon d'intégration à <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink>, qui ajoute la documentation d'API à un site Trac et s'intègre à la recherche Trac.</para>
<para>
Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since
tags in the API to determine the minimum required version.
<revhistory>
<revision>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development</revremark>
+ </revision>
+ <revision>
<revnumber>1.28</revnumber>
<date>24 Mar 2018</date>
<authorinitials>ss</authorinitials>
<guilabel>Writing the documentation.</guilabel>
The author fills in the source files with the documentation for each
- function, macro, union etc. (In the past information was entered in
- generated template files, which is not recommended anymore).
+ function, macro, structs or unions, etc.
</para>
</listitem>
<title>About GTK-Doc</title>
<para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
+ <para>
(FIXME)
</para>
<para>
- (History, authors, web pages, mailing list, license, future plans,
+ (authors, web pages, mailing list, license, future plans,
comparison with other similar systems.)
</para>
</chapter>
<chapter id="settingup">
- <title>Setting up your project</title>
+ <title>Project Setup</title>
+
+ <para>
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- The next sections describe what steps to perform to integrate GTK-Doc into
- your project. Theses sections assume we work on a project called 'meep'.
- This project contains a library called 'libmeep' and
- an end-user app called 'meeper'. We also assume you will be using autoconf
- and automake. In addition section <link linkend="plain_makefiles">plain
- makefiles or other build systems</link> will describe the basics needed to
- work in a different build setup.
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
</para>
<sect1 id="settingup_docfiles">
<title>Setting up a skeleton documentation</title>
<para>
- Under your top-level project directory create folders called docs/reference
- (this way you can also have docs/help for end-user documentation).
- It is recommended to create another subdirectory with the name of the doc-package.
- For packages with just one library this step is not necessary.
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
</para>
<para>
- This can then look as shown below:
- <example><title>Example directory structure</title>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
<programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
</para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>Integration with autoconf</title>
-
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
<para>
- Very easy! Just add one line to your <filename>configure.ac</filename> script.
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
+
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>Integration with autoconf</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-]]></programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>
- This will require all developers to have gtk-doc installed. If it is
- okay for your project to have optional api-doc build setup, you can
- solve this as below. Keep it as is, as gtkdocize is looking for
- <function>GTK_DOC_CHECK</function> at the start of a line.
- <example><title>Keep gtk-doc optional</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-],[
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
-]]></programlisting>
+ <sect2 id="settingup_automake">
+ <title>Integration with automake</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
+ <programlisting>
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
+</programlisting>
</example>
- </para>
- <para>
- The first argument is used to check for the gtkdocversion at configure time.
- The 2nd, optional argument is used by <application>gtkdocize</application>.
- The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure switches:
- </para>
- <orderedlist>
- <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
- <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
- <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
+
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <important>
- <para>
- GTK-Doc is disabled by default! Remember to pass the option
- <option>'--enable-gtk-doc'</option> to the next
- <filename>configure</filename> run. Otherwise pregenerated documentation is installed
- (which makes sense for users but not for developers).
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
+
+ All the tools support <option>--help</option> to list the supported
+ options.
</para>
- </important>
- <para>
- Furthermore it is recommended that you have the following line inside
- your <filename>configure.ac</filename> script.
- This allows <application>gtkdocize</application> to automatically copy the
- macro definition for <function>GTK_DOC_CHECK</function> to your project.
- </para>
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
- <para>
- <example><title>Preparation for gtkdocize</title>
- <programlisting><![CDATA[
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>Integration with autoconf</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
]]></programlisting>
- </example>
- </para>
- <para>
- After all changes to <filename>configure.ac</filename> are made, update
- the <filename>configure</filename> file. This can be done by re-running
- <code>autoreconf -i</code> or <code>autogen.sh</code>.
- </para>
- </sect1>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>Integration with automake</title>
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub directory of the
- <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
- to your project's API documentation directory (
- <filename class="directory">./docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple doc-packages repeat this for each one.
- </para>
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <para>
- The next step is to edit the settings inside the <filename>Makefile.am</filename>.
- All the settings have a comment above that describes their purpose.
- Most settings are extra flags passed to the respective tools. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
- All the tools support <option>--help</option> to list the supported
- parameters.
- </para>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <!-- FIXME: explain options ? -->
+ <orderedlist>
+ <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
+ <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
+ </orderedlist>
- </sect1>
+ <important>
+ <para>
+ GTK-Doc is disabled by default! Remember to pass the option
+ <option>'--enable-gtk-doc'</option> to the next
+ <filename>configure</filename> run. Otherwise pregenerated documentation is installed
+ (which makes sense for users but not for developers).
+ </para>
+ </important>
- <sect1 id="settingup_autogen">
- <title>Integration with autogen</title>
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- <para>
- Most projects will have an <filename>autogen.sh</filename> script to
- setup the build infrastructure after a checkout from version control
- system (such as cvs/svn/git). GTK-Doc comes with a tool called
- <application>gtkdocize</application> which can be used in such a script.
- It should be run before autoheader, automake or autoconf.
- </para>
+ <sect2 id="settingup_autogen">
+ <title>Integration with autogen</title>
- <para>
- <example><title>Running gtkdocize from autogen.sh</title>
- <programlisting><![CDATA[
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
+
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
+
+ <para>
+ <example><title>Running gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
gtkdocize || exit 1
]]></programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>
- When running <application>gtkdocize</application> it copies
- <filename>gtk-doc.make</filename> to your project root (or any directory
- specified by the <option>--docdir</option> option).
- It also checks you configure script for the <function>GTK_DOC_CHECK</function>
- invocation. This macro can be used to pass extra parameters to
- <application>gtkdocize</application>.
- </para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>
- Historically GTK-Doc was generating template files where developers entered the docs.
- This turned out to be not so good (e.g. the need for having generated
- files under version control).
- Since GTK-Doc 1.9 the tools can get all the information from source comments
- and thus the templates can be avoided. We encourage people to keep
- documentation in the code. <application>gtkdocize</application> supports now
- a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
- tmpl usage totally. Besides adding the option directly to the command
- invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
- or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
- If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
- please remove the directory (e.g. from version control system).
- </para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>Running the doc build</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>
- After the previous steps it's time to run the build. First we need to
- rerun <filename>autogen.sh</filename>. If this script runs configure for
- you, then give it the <option>--enable-gtk-doc</option> option.
- Otherwise manually run <filename>configure</filename> with this option
- afterwards.
- </para>
- <para>
- The first make run generates several additional files in the doc-directories.
- The important ones are:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>.
- </para>
- <para>
- <example><title>Running the doc build</title>
- <programlisting><![CDATA[
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>
+ After the previous steps it's time to run the build. First we need to
+ rerun <filename>autogen.sh</filename>. If this script runs configure
+ for you, then give it the <option>--enable-gtk-doc</option> option.
+ Otherwise manually run <filename>configure</filename> with this option
+ afterwards.
+ </para>
+ <para>
+ The first make run generates several additional files in the doc-directories.
+ The important ones are:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>.
+ </para>
+ <para>
+ <example><title>Running the doc build</title>
+ <programlisting><![CDATA[
./autogen.sh --enable-gtk-doc
make
]]></programlisting>
- </example>
- </para>
- <para>
- Now you can point your browser to <filename>docs/reference/<package>/index.html</filename>.
- Yes, it's a bit disappointing still. But hang-on, during the next chapter we
- tell you how to fill the pages with life.
- </para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>Integration with version control systems</title>
+ <sect1 id="settingup_cmake">
+ <title>Integration with CMake build systems</title>
<para>
- As a rule of thumb, it's the files you edit which should go under
- version control. For typical projects it's these files:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>,
- <filename>Makefile.am</filename>.
+ GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
+ (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
+ module). This provides a <literal>gtk_doc_add_module</literal>
+ command that you can set in your <filename>CMakeLists.txt</filename>
+ file.
</para>
+
<para>
- Files in the <filename>xml/</filename> and <filename>html/</filename>
- directories should not go under version control. Neither should any of
- the <filename>.stamp</filename> files.
+ The following example shows how to use this command.
+ <example><title>Example of using GTK-Doc from CMake</title>
+ <programlisting><![CDATA[
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+]]></programlisting>
+ </example>
</para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integration with plain makefiles or other build systems</title>
<para>
</para>
</sect1>
- <sect1 id="cmake">
- <title>Integration with CMake build systems</title>
-
- <para>
- GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
- (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
- module). This provides a <literal>gtk_doc_add_module</literal>
- command that you can set in your <filename>CMakeLists.txt</filename>
- file.
- </para>
-
- <para>
- The following example shows how to use this command.
- <example><title>Example of using GTK-Doc from CMake</title>
- <programlisting><![CDATA[
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>Integration with version control systems</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>
+ As a rule of thumb, it's the files you edit which should go under
+ version control. For typical projects it's these files:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>,
+ <filename>Makefile.am</filename>.
+ </para>
+ <para>
+ Files in the <filename>xml/</filename> and <filename>html/</filename>
+ directories should not go under version control. Neither should any of
+ the <filename>.stamp</filename> files.
+ </para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
- </sect1>
</chapter>
<chapter id="documenting">
syntax of the comments.
</para>
- <note>
- <title>Documentation placement</title>
- <para>
- In the past most documentation had to be filled into files residing
- inside the <filename>tmpl</filename> directory. This has the
- disadvantages that the information is often not updated and also that
- the file tend to cause conflicts with version control systems.
- </para>
- <para>
- The avoid the aforementioned problems we suggest putting the
- documentation inside the sources. This manual will only describe this
- way of documenting code.
- </para>
- </note>
-
<para>
- The scanner can handle the majority of C headers fine. In the case of
- receiving warnings from the scanner that look like a special case, one can
- hint GTK-Doc to skip over them.
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<para>
As already mentioned earlier GTK-Doc is for documenting public API. Thus
one cannot write documentation for static symbols. Nevertheless it is good
- to comment those symbols too. This helps other to understand you code.
+ to comment those symbols too. This helps other developers to understand
+ your code.
Therefore we recommend to comment these using normal comments (without the
2nd '*' in the first line).
If later the function needs to be made public, all one needs to do is to
</para>
<para>
- <example><title>Example types file snippet</title>
+ <example><title>Example <package>.types file</title>
<programlisting><![CDATA[
#include <gtk/gtk.h>
containing entities for e.g. package_name and package_version. You can
use this e.g. in the main xml file to avoid hardcoding the version
number. Below is an example that shows how the entity file is included
- and how the entities are used. The entities can also be used in all
+ in the master template and how the entities are used.
+ The entities can also be used in all
generated files, GTK-Doc will use the same xml header in generated xml
files.
<example><title>Use pre-generated entities</title>
<revhistory>
<revision>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development</revremark>
+ </revision>
+ <revision>
<revnumber>1.28</revnumber>
<date>24 Mar 2018</date>
<authorinitials>ss</authorinitials>
<orderedlist>
<listitem>
- <para><guilabel>દસ્તાવેજીકરણને લખી રહ્યા છે.</guilabel> લેખક એ દરેક વિધેયને, મેક્રો, યુનિયન વગેરે માટે દસ્તાવેજીકરણ સાથે સ્ત્રોત ફાઇલોમાં ભરે છે. (ઉત્પન્ન થયેલ ટેમ્પલેટ ફાઇલમાં ભૂતકાળની જાણકારી દાખલ થયેલ હતી, કે જે કોઇપણ રીતે અગ્રહણીય થયેલ નથી)</para>
+ <para>
+ <guilabel>Writing the documentation.</guilabel>
+
+ The author fills in the source files with the documentation for each
+ function, macro, structs or unions, etc.
+ </para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>GTK-Doc વિશે</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(FIXME)</para>
<para>
- (History, authors, web pages, mailing list, license, future plans,
+ (authors, web pages, mailing list, license, future plans,
comparison with other similar systems.)
</para>
</chapter>
<chapter id="settingup">
- <title>તમારા પ્રોજેક્ટને સુયોજિત કરી રહ્યા છે</title>
+ <title>Project Setup</title>
<para>
- The next sections describe what steps to perform to integrate GTK-Doc into
- your project. Theses sections assume we work on a project called 'meep'.
- This project contains a library called 'libmeep' and
- an end-user app called 'meeper'. We also assume you will be using autoconf
- and automake. In addition section <link linkend="plain_makefiles">plain
- makefiles or other build systems</link> will describe the basics needed to
- work in a different build setup.
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
</para>
<sect1 id="settingup_docfiles">
<title>સ્કેલેટન દસ્તાવેજીકરણને સુયોજિત કરી રહ્યા છે</title>
<para>
- Under your top-level project directory create folders called docs/reference
- (this way you can also have docs/help for end-user documentation).
- It is recommended to create another subdirectory with the name of the doc-package.
- For packages with just one library this step is not necessary.
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
</para>
<para>
- This can then look as shown below:
- <example><title>Example directory structure</title>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
<programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
</para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>autoconf સાથે એકત્રિકરણ</title>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
- <para>ઘણું સરળ છે! ફક્ત તમારી <filename>configure.ac</filename> સ્ક્રિપ્ટમાં એક વાક્ય ને ઉમેરો.</para>
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>autoconf સાથે એકત્રિકરણ</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-]]></programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>
- This will require all developers to have gtk-doc installed. If it is
- okay for your project to have optional api-doc build setup, you can
- solve this as below. Keep it as is, as gtkdocize is looking for
- <function>GTK_DOC_CHECK</function> at the start of a line.
- <example><title>Keep gtk-doc optional</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-],[
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
-]]></programlisting>
+ <sect2 id="settingup_automake">
+ <title>automake સાથે એકત્રિકરણ</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
+ <programlisting>
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
+</programlisting>
</example>
- </para>
- <para>પહેલી દલીલ રૂપરેખાંકિત સમયે gtkdocversion માટે ચકાસવા વપરાયેલ છે. બીજી, વૈકલ્પિક દલીલ એ <application>gtkdocize</application> દ્દારા વપરાયેલ છે. <symbol>GTK_DOC_CHECK</symbol> મેક્રો પણ ઘણીબધા રૂપરેખાંકિત ફેરબદલોને ઉમેરે છે:</para>
- <orderedlist>
- <listitem><para>--with-html-dir=PATH : સ્થાપિત થયેલ દસ્તાવેજોનો પાથ</para></listitem>
- <listitem><para>--enable-gtk-doc : દસ્તાવેજીકરણ ને બિલ્ડ કરવા માટે gtk-doc ને વાપરો [default=no]</para></listitem>
- <listitem><para>--enable-gtk-doc-html : html બંધારણમાં દસ્તાવેજીકરણ બિલ્ડ કરો [default=yes]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : pdf બંધારણમાં દસ્તાવેજીકરણને બિલ્ડ કરો [default=no]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
- <important>
- <para>GTK-Doc એ મૂળભૂત રીતે નિષ્ક્રિય થયેલ છે! આગળનાં <filename>configure</filename> ને ચલાવવા માટે <option>'--enable-gtk-doc'</option> ને પસાર કરવાનું યાદ રાખો. નહિં તો પહેલીથી ઉત્પન્ન થયેલ દસ્તાવેજીકરણ સ્થાપિત થયેલ છે (કે જે વપરાશકર્તાઓ માટેનો અર્થ બને છે પરંતુ ડેવલપરો માટે નહિં).</para>
- </important>
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <para>
- Furthermore it is recommended that you have the following line inside
- your <filename>configure.ac</filename> script.
- This allows <application>gtkdocize</application> to automatically copy the
- macro definition for <function>GTK_DOC_CHECK</function> to your project.
- </para>
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
- <para>
- <example><title>gtkdocize માટે તૈયારી</title>
- <programlisting><![CDATA[
+ All the tools support <option>--help</option> to list the supported
+ options.
+ </para>
+
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>autoconf સાથે એકત્રિકરણ</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
]]></programlisting>
- </example>
- </para>
- <para>
- After all changes to <filename>configure.ac</filename> are made, update
- the <filename>configure</filename> file. This can be done by re-running
- <code>autoreconf -i</code> or <code>autogen.sh</code>.
- </para>
- </sect1>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>automake સાથે એકત્રિકરણ</title>
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub directory of the
- <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
- to your project's API documentation directory (
- <filename class="directory">./docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple doc-packages repeat this for each one.
- </para>
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <para>
- The next step is to edit the settings inside the <filename>Makefile.am</filename>.
- All the settings have a comment above that describes their purpose.
- Most settings are extra flags passed to the respective tools. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
- All the tools support <option>--help</option> to list the supported
- parameters.
- </para>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <!-- FIXME: explain options ? -->
+ <orderedlist>
+ <listitem><para>--with-html-dir=PATH : સ્થાપિત થયેલ દસ્તાવેજોનો પાથ</para></listitem>
+ <listitem><para>--enable-gtk-doc : દસ્તાવેજીકરણ ને બિલ્ડ કરવા માટે gtk-doc ને વાપરો [default=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : html બંધારણમાં દસ્તાવેજીકરણ બિલ્ડ કરો [default=yes]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : pdf બંધારણમાં દસ્તાવેજીકરણને બિલ્ડ કરો [default=no]</para></listitem>
+ </orderedlist>
- </sect1>
+ <important>
+ <para>GTK-Doc એ મૂળભૂત રીતે નિષ્ક્રિય થયેલ છે! આગળનાં <filename>configure</filename> ને ચલાવવા માટે <option>'--enable-gtk-doc'</option> ને પસાર કરવાનું યાદ રાખો. નહિં તો પહેલીથી ઉત્પન્ન થયેલ દસ્તાવેજીકરણ સ્થાપિત થયેલ છે (કે જે વપરાશકર્તાઓ માટેનો અર્થ બને છે પરંતુ ડેવલપરો માટે નહિં).</para>
+ </important>
- <sect1 id="settingup_autogen">
- <title>autogen સાથે એકત્રિકરણ</title>
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- <para>મોટાભાગનાં પ્રોજેક્ટો પાસે આવૃત્તિ નિયંત્રણ સિસ્ટમ (જેવી કે cvs/svn/git) માંથી ચેકઆઉટ પછી ઇન્ફ્રાસ્ટ્રક્ચરને બિલ્ડ કરવાનું સુયોજિત કરવા માટે <filename>autogen.sh</filename> સ્ક્રિપ્ટ હશે. GTK-Doc એ સાધન <application>gtkdocize</application> તરીકે કહેવાતા સાધન સાથે આવે છે કે જે આવી સ્ક્રિપ્ટમાં વાપરી શકાય છે. તે autoheader, automake અથવા autoconf પહેલાં ચાલવુ જોઇએ.</para>
+ <sect2 id="settingup_autogen">
+ <title>autogen સાથે એકત્રિકરણ</title>
- <para>
- <example><title>autogen.sh માંથી gtkdocize ને ચલાવી રહ્યા છે</title>
- <programlisting><![CDATA[
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
+
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
+
+ <para>
+ <example><title>autogen.sh માંથી gtkdocize ને ચલાવી રહ્યા છે</title>
+ <programlisting><![CDATA[
gtkdocize || exit 1
]]></programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>
- When running <application>gtkdocize</application> it copies
- <filename>gtk-doc.make</filename> to your project root (or any directory
- specified by the <option>--docdir</option> option).
- It also checks you configure script for the <function>GTK_DOC_CHECK</function>
- invocation. This macro can be used to pass extra parameters to
- <application>gtkdocize</application>.
- </para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>
- Historically GTK-Doc was generating template files where developers entered the docs.
- This turned out to be not so good (e.g. the need for having generated
- files under version control).
- Since GTK-Doc 1.9 the tools can get all the information from source comments
- and thus the templates can be avoided. We encourage people to keep
- documentation in the code. <application>gtkdocize</application> supports now
- a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
- tmpl usage totally. Besides adding the option directly to the command
- invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
- or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
- If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
- please remove the directory (e.g. from version control system).
- </para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
+
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <sect1 id="settingup_firstrun">
- <title>દસ્તાવેજ બિલ્ડને ચલાવી રહ્યા છે</title>
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
- <para>પહેલાનાં પગલાઓ પછી બિલ્ડ ને ચલાવવા માટે સમય થઇ ગયો છે. પહેલાં આપણે <filename>autogen.sh</filename> પુન:ચલાવવાની જરૂર છે. નહિં તો પછીથી આ વિકલ્પ સાથે <filename>configure</filename> ને જાતે જ ચલાવો.</para>
- <para>
- The first make run generates several additional files in the doc-directories.
- The important ones are:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>.
- </para>
- <para>
- <example><title>દસ્તાવેજ બિલ્ડને ચલાવી રહ્યા છે</title>
- <programlisting><![CDATA[
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>પહેલાનાં પગલાઓ પછી બિલ્ડ ને ચલાવવા માટે સમય થઇ ગયો છે. પહેલાં આપણે <filename>autogen.sh</filename> પુન:ચલાવવાની જરૂર છે. નહિં તો પછીથી આ વિકલ્પ સાથે <filename>configure</filename> ને જાતે જ ચલાવો.</para>
+ <para>
+ The first make run generates several additional files in the doc-directories.
+ The important ones are:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>.
+ </para>
+ <para>
+ <example><title>દસ્તાવેજ બિલ્ડને ચલાવી રહ્યા છે</title>
+ <programlisting><![CDATA[
./autogen.sh --enable-gtk-doc
make
]]></programlisting>
- </example>
- </para>
- <para>હવે તમે <filename>docs/reference/<package>/index.html</filename> માટે તમારા બ્રાઉઝર પર આંગળી ચીંધી શકો છો. હાં, તે થોડુ હજુ નિરાશ કરે તેવુ છે. પરંતુ આગળનામ વિષય માટે આપણે તને કહીએ છે કે જીદંગી સાથે પાનાંઓને કેવી રીતે ભરવા તે દરમ્યાન થોડા સમય માટે અટકી જાય છે</para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>આવૃત્તિ નિયંત્રણ સિસ્ટમો સાથે એકત્રિકરણ</title>
+ <sect1 id="settingup_cmake">
+ <title>Integration with CMake build systems</title>
<para>
- As a rule of thumb, it's the files you edit which should go under
- version control. For typical projects it's these files:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>,
- <filename>Makefile.am</filename>.
+ GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
+ (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
+ module). This provides a <literal>gtk_doc_add_module</literal>
+ command that you can set in your <filename>CMakeLists.txt</filename>
+ file.
</para>
+
<para>
- Files in the <filename>xml/</filename> and <filename>html/</filename>
- directories should not go under version control. Neither should any of
- the <filename>.stamp</filename> files.
+ The following example shows how to use this command.
+ <example><title>Example of using GTK-Doc from CMake</title>
+ <programlisting><![CDATA[
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+]]></programlisting>
+ </example>
</para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integration with plain makefiles or other build systems</title>
<para>
</para>
</sect1>
- <sect1 id="cmake">
- <title>Integration with CMake build systems</title>
-
- <para>
- GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
- (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
- module). This provides a <literal>gtk_doc_add_module</literal>
- command that you can set in your <filename>CMakeLists.txt</filename>
- file.
- </para>
-
- <para>
- The following example shows how to use this command.
- <example><title>Example of using GTK-Doc from CMake</title>
- <programlisting><![CDATA[
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>આવૃત્તિ નિયંત્રણ સિસ્ટમો સાથે એકત્રિકરણ</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>
+ As a rule of thumb, it's the files you edit which should go under
+ version control. For typical projects it's these files:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>,
+ <filename>Makefile.am</filename>.
+ </para>
+ <para>
+ Files in the <filename>xml/</filename> and <filename>html/</filename>
+ directories should not go under version control. Neither should any of
+ the <filename>.stamp</filename> files.
+ </para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
- </sect1>
</chapter>
<chapter id="documenting">
syntax of the comments.
</para>
- <note>
- <title>દસ્તાવેજીકરણ નિયુક્તિ</title>
- <para>
- In the past most documentation had to be filled into files residing
- inside the <filename>tmpl</filename> directory. This has the
- disadvantages that the information is often not updated and also that
- the file tend to cause conflicts with version control systems.
- </para>
- <para>
- The avoid the aforementioned problems we suggest putting the
- documentation inside the sources. This manual will only describe this
- way of documenting code.
- </para>
- </note>
-
<para>
- The scanner can handle the majority of C headers fine. In the case of
- receiving warnings from the scanner that look like a special case, one can
- hint GTK-Doc to skip over them.
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
</para>
<tip>
- <para>પહેલાનાં GTK-Doc માં પહેલેથી જણાવેલ પ્રમાણે સાર્વજનિક API દસ્તાવેજીકરણ માટે છે. છતાં એક એ સ્થિર સંકેતો માટે દસ્તાવેજીકરણ ને લખી શકતુ નથી. તેમ છતાં તે પેલાં સંકેતો પર ટિપ્પણી કરવા માટે સારુ છે. આ તમારાં કોડને સમજવા માટે બીજાને મદદ કરે છે. માટે આપણે સામાન્ય ટિપ્પણીઓની મદદથી આ ટિપ્પણી એ અગ્રહણીય કરેલ છે (પહેલાં વાક્યમાં બીજા '*' વગર). જો પછી વિધેયને સાર્વજનિક બનાવવાની જરૂર છે, ટિપ્પણી બ્લોકમાં બીજા '*' ઉમેરવા માટે બધાને કરવાની જરૂર છે અને ફાઇલ વિભાગોની અંદર જમણી જગ્યા પર સંકેત નામને દાખલ કરો.</para>
+ <para>
+ As already mentioned earlier GTK-Doc is for documenting public API. Thus
+ one cannot write documentation for static symbols. Nevertheless it is good
+ to comment those symbols too. This helps other developers to understand
+ your code.
+ Therefore we recommend to comment these using normal comments (without the
+ 2nd '*' in the first line).
+ If later the function needs to be made public, all one needs to do is to
+ add another '*' in the comment block and insert the symbol name at the
+ right place inside the sections file.
+ </para>
</tip>
</sect1>
</para>
<para>
- <example><title>Example types file snippet</title>
+ <example><title>Example <package>.types file</title>
<programlisting><![CDATA[
#include <gtk/gtk.h>
containing entities for e.g. package_name and package_version. You can
use this e.g. in the main xml file to avoid hardcoding the version
number. Below is an example that shows how the entity file is included
- and how the entities are used. The entities can also be used in all
+ in the master template and how the entities are used.
+ The entities can also be used in all
generated files, GTK-Doc will use the same xml header in generated xml
files.
<example><title>Use pre-generated entities</title>
<revhistory>
<revision>
- <revnumber>1.28</revnumber>
- <date>24 Mar 2018</date>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>bug fixes</revremark>
+ <revremark>development</revremark>
</revision>
+ <revision><revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</authorinitials> <revremark>correçãoõesão de erros</revremark></revision>
<revision><revnumber>1.27</revnumber> <date>07 Maio 2017</date> <authorinitials>ss</authorinitials> <revremark>ajustes do porte para Python</revremark></revision>
<revision><revnumber>1.26</revnumber> <date>11 Ago 2017</date> <authorinitials>ss</authorinitials> <revremark>portadas todas ferramentas de perl/bash para Python</revremark></revision>
<revision><revnumber>1.25</revnumber> <date>21 Mar 2016</date> <authorinitials>ss</authorinitials> <revremark>correção de erros, limpezas de testes</revremark></revision>
<orderedlist>
<listitem>
- <para><guilabel>Escrevendo a documentação.</guilabel> O autor preenche os arquivos fonte com a documentação para cada função, macro, union, etc. (Anteriormente, a informação era inserida em arquivos de modelo gerados, o que não é mais recomendado).</para>
+ <para>
+ <guilabel>Writing the documentation.</guilabel>
+
+ The author fills in the source files with the documentation for each
+ function, macro, structs or unions, etc.
+ </para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>Sobre GTK-Doc</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(CORRIJA-ME)</para>
- <para>(História, autores, páginas web, lista de discussão, licença, planos futuros, comparação com outros sistemas similares.)</para>
+ <para>
+ (authors, web pages, mailing list, license, future plans,
+ comparison with other similar systems.)
+ </para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Preparando seu projeto</title>
+ <title>Project Setup</title>
- <para>As próximas seções descrevem quais as etapas para realizar a integração do GTK-Doc em seu projeto. Estas seções consideram que nós trabalhamos em um projeto chamado “meep”. Este projeto contém uma biblioteca chamada “libmeep” e um aplicativo para usuário final chamado “meeper”. Nós também consideramos que você estará usando autoconf e automake. Além disso, a seção sobre <link linkend="plain_makefiles">makefiles simples ou outros sistemas de compilação</link> vai descrever as necessidades básicas para trabalhar em uma configuração de compilação diferente.</para>
+ <para>
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
+ </para>
<sect1 id="settingup_docfiles">
<title>Preparando o esqueleto de uma documentação</title>
- <para>No diretório raiz do seu projeto, crie pastas chamadas docs/reference (desta forma, você também pode ter docs/help para documentação para usuário final). É recomendado criar um outro subdiretório com o nome do pacote de documentação. Para pacotes com apenas uma biblioteca, esta etapa não é obrigatória.</para>
+ <para>
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
+ </para>
- <para>Isto pode, então, parecer como exibido abaixo: <example><title>Exemplo de estrutura de diretórios</title>
- <programlisting>
+ <para>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
+ <programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
-</programlisting>
- </example></para>
+]]></programlisting>
+ </example>
+ </para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>Integração com autoconf</title>
-
- <para>Muito fácil! Basta adicionar uma linha ao seu script <filename>configure.ac</filename>.</para>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
+
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>Integração com autoconf</title>
- <programlisting>
-# verifica por gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-</programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>Isso vai exigir que todos os desenvolvedores tenham o gtk-doc instalado. Se não houver problema para seu projeto ter uma configuração opcional de compilação de documentação de API, você pode resolver isso como mostrado abaixo. Mantenha assim, pois o gtkdocize está procurando por <function>GTK_DOC_CHECK</function> no começo de uma linha. <example><title>Mantenha o gtk-doc como opcional</title>
+ <sect2 id="settingup_automake">
+ <title>Integração com automake</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
<programlisting>
-# verifica por gtk-doc
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-],[
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
</programlisting>
- </example></para>
+ </example>
- <para>O primeiro argumento é usado para verificar a gtkdocversion em tempo de compilação. O segundo argumento é opcional, sendo usado por <application>gtkdocize</application>. A macro <symbol>GTK_DOC_CHECK</symbol> também adiciona várias opções de configuração:</para>
- <orderedlist>
- <listitem><para>--with-html-dir=CAMINHO : caminho para as documentações instaladas</para></listitem>
- <listitem><para>--enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=no]</para></listitem>
- <listitem><para>--enable-gtk-doc-html : compila documentação em formato html [padrão=sim]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : compila documentação em formato pdf [padrão=não]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
- <important>
- <para>GTK-Doc está desabilitado por padrão! Lembre-se de passar a opção <option>"--enable-gtk-doc"</option> à próxima execução do <filename>configure</filename>. Do contrário, uma documentação gerada previamente é instalada (o que faz sentido para usuários, mas não para desenvolvedores).</para>
- </important>
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <para>Além disso, é recomendado que você tenha a seguinte linha dentro do seu script <filename>configure.ac</filename>. Ela permite que <application>gtkdocize</application> copie automaticamente a definição de macro para <function>GTK_DOC_CHECK</function> para o seu projeto.</para>
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
- <para>
- <example><title>Preparação para gtkdocize</title>
- <programlisting>
+ All the tools support <option>--help</option> to list the supported
+ options.
+ </para>
+
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>Integração com autoconf</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
-</programlisting>
- </example>
- </para>
- <para>Após todas as alterações do <filename>configure.ac</filename> serem feitas, atualize o arquivo <filename>configure</filename>. Isso pode ser feito executando novamente <code>autoreconf -i</code> ou <code>autogen.sh</code>.</para>
- </sect1>
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+]]></programlisting>
+ </example>
+ </para>
+
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
+
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>Integração com automake</title>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <para>Primeiro copie o <filename>Makefile.am</filename> dos subdiretório do <filename class="directory">exemplo</filename> do <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink> para o diretório de documentação da API do seu projeto ( <filename class="directory">./docs/reference/<pacote></filename>). Uma cópia local deveria estar disponível sob, por exemplo, <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Se você tiver múltiplos pacotes de documentação, repita isso para cada um.</para>
+ <orderedlist>
+ <listitem><para>--with-html-dir=CAMINHO : caminho para as documentações instaladas</para></listitem>
+ <listitem><para>--enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : compila documentação em formato html [padrão=sim]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : compila documentação em formato pdf [padrão=não]</para></listitem>
+ </orderedlist>
- <para>A próxima etapa é editar as configurações dentro do <filename>Makefile.am</filename>. Todas as configurações tem um comentário em cima que descreve seu propósito. A maioria das configurações são opções extras passadas para as respectivas ferramentas. Cada ferramenta tem uma variável na forma <option><NOME-FERRAMENTA>_OPTIONS</option>. Todas as ferramentas têm suporte a <option>--help</option> pra listar os parâmetros disponíveis.</para>
+ <important>
+ <para>GTK-Doc está desabilitado por padrão! Lembre-se de passar a opção <option>"--enable-gtk-doc"</option> à próxima execução do <filename>configure</filename>. Do contrário, uma documentação gerada previamente é instalada (o que faz sentido para usuários, mas não para desenvolvedores).</para>
+ </important>
- <!-- FIXME: explain options ? -->
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- </sect1>
+ <sect2 id="settingup_autogen">
+ <title>Integração com autogen</title>
- <sect1 id="settingup_autogen">
- <title>Integração com autogen</title>
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
- <para>A maioria dos projetos têm um script <filename>autogen.sh</filename> para configurar a infraestrutura de compilação após baixar do sistema de controle de versão (como cvs/svn/git). GTK-Doc vêm com uma ferramenta chamada <application>gtkdocize</application> que pode ser usada em um script assim. O gtkdocize deveria ser executado antes de autoheader, automake ou autoconf.</para>
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
- <para>
- <example><title>Executando gtkdocize no autogen.sh</title>
- <programlisting>
+ <example><title>Executando gtkdocize no autogen.sh</title>
gtkdocize || exit 1
</programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>Ao executar <application>gtkdocize</application>, ele copia <filename>gtk-doc.make</filename> para a raiz do seu projeto (ou qualquer diretório especificado pela opção <option>--docdir</option>). Ele também verifica se seu script de configuração pela chamada de <function>GTK_DOC_CHECK</function>. Esta macro pode ser usada para passar parâmetros extras para <application>gtkdocize</application>.</para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>Historicamente, GTK-Doc estava gerando arquivos modelo (template) nos quais os desenvolvedores inseriam as documentações. Isso acabou sendo não tão bom (ex.: a necessidade de serem gerados arquivos sob controle de versão). Desde o GTK-Doc 1.9 as ferramentas podem obter todas as informações dos comentários no fonte e, portanto, os arquivos modelo podem ser evitados. Nós encorajamos as pessoas a manter a documentação no código. O <application>gtkdocize</application> possui agora suporte à opção <option>--flavour no-tmpl</option> que escolhe um makefile que ignora totalmente o uso de tmpl. Além de adicionar a opção diretamente à chamada do comando, elas também podem ser adicionadas a uma variável de ambiente chamada <symbol>GTKDOCIZE_FLAGS</symbol> ou definidas como um segundo parâmetro na macro <symbol>GTK_DOC_CHECK</symbol> no script configure. Se você nunca alterou um arquivo tmpl a mão e está migrando de versões antigas do gtkdoc, por favor remova o diretório (ex.: do sistema de controle de versão).</para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
+
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
+
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
- <sect1 id="settingup_firstrun">
- <title>Executando a compilação da documentação</title>
+ </sect2>
- <para>Após as etapas anteriores, é hora de executar a compilação. Primeiro, nós queremos executar novamente o <filename>autogen.sh</filename>. Se este script executa o configure para você, então forneça a este a opção <option>--enable-gtk-doc</option>. Do contrário, execute manualmente <filename>configure</filename> com esta opção em seguida.</para>
- <para>A primeira execução do make cria vários arquivos adicionais nos diretórios de documentação. Os importantes são: <filename><pacote>.types</filename>, <filename><pacote>-docs.xml</filename> (no passado, .sgml), <filename><pacote>-sections.txt</filename>.</para>
- <para>
- <example><title>Executando a compilação da documentação</title>
- <programlisting>
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>Após as etapas anteriores, é hora de executar a compilação. Primeiro, nós queremos executar novamente o <filename>autogen.sh</filename>. Se este script executa o configure para você, então forneça a este a opção <option>--enable-gtk-doc</option>. Do contrário, execute manualmente <filename>configure</filename> com esta opção em seguida.</para>
+ <para>A primeira execução do make cria vários arquivos adicionais nos diretórios de documentação. Os importantes são: <filename><pacote>.types</filename>, <filename><pacote>-docs.xml</filename> (no passado, .sgml), <filename><pacote>-sections.txt</filename>.</para>
+ <para>
+ <example><title>Executando a compilação da documentação</title>
+ <programlisting>
./autogen.sh --enable-gtk-doc
make
</programlisting>
- </example>
- </para>
- <para>Agora você pode apontar seu navegador para <filename>docs/reference/<pacote>/index.html</filename>. Sim, é um pouco desapontador. Mas aguente aí, durante o próximo capítulo nós vamos dizer como você pode preencher as páginas com vida.</para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>Integração com sistemas de controle de versão</title>
+ <sect1 id="settingup_cmake">
+ <title>Integração com sistemas de compilação CMake</title>
- <para>Como uma regra de ouro, são aqueles arquivos que você edita que deveriam entrar no controle de versão. Para projetos normais, esses são os arquivos: <filename><pacote>.types</filename>, <filename><pacote>-docs.xml</filename> (no passado, .sgml), <filename><pacote>-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
- <para>Arquivos nos diretórios <filename>xml/</filename> e <filename>html/</filename> não deveriam entrar no controle de versão. Da mesma forma, não deveriam entrar arquivos <filename>.stamp</filename>.</para>
+ <para>GTK-Doc agora fornece um módulo <filename>GtkDocConfig.cmake</filename> (e o module <filename>GtkDocConfigVersion.cmake</filename> correspondente). Ele fornece um comando <literal>gtk_doc_add_module</literal> que você pode usar em seu arquivo <filename>CMakeLists.txt</filename>.</para>
+
+ <para>O exemplo a seguir mostra como usar este comando. <example><title>Exemplo de uso do GTK-Doc no CMake</title>
+ <programlisting>
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Cria o alvo doc-libmeep.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Compila doc-libmeep como parte do alvo padrão. Sem isso, você precisaria
+# executar explicitamente algo como `make doc-libmeep` para compilar os
+# documentos.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+</programlisting>
+ </example></para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integração com makefiles simples ou outros sistemas de compilação</title>
<para>Neste caso, não se deseja usar o automake e, portanto, <filename>gtk-doc.mak</filename>. Será necessário chamar as ferramentas do gtkdoc na ordem correta nos makefiles devidos (ou outras ferramentas de compilação).</para>
<para>Será necessário olhar no <filename>Makefile.am</filename> e no <filename>gtk-doc.mak</filename> para obter as opções extras necessárias.</para>
</sect1>
- <sect1 id="cmake">
- <title>Integração com sistemas de compilação CMake</title>
-
- <para>GTK-Doc agora fornece um módulo <filename>GtkDocConfig.cmake</filename> (e o module <filename>GtkDocConfigVersion.cmake</filename> correspondente). Ele fornece um comando <literal>gtk_doc_add_module</literal> que você pode usar em seu arquivo <filename>CMakeLists.txt</filename>.</para>
-
- <para>O exemplo a seguir mostra como usar este comando. <example><title>Exemplo de uso do GTK-Doc no CMake</title>
- <programlisting>
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Cria o alvo doc-libmeep.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>Integração com sistemas de controle de versão</title>
-# Compila doc-libmeep como parte do alvo padrão. Sem isso, você precisaria
-# executar explicitamente algo como `make doc-libmeep` para compilar os
-# documentos.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>Como uma regra de ouro, são aqueles arquivos que você edita que deveriam entrar no controle de versão. Para projetos normais, esses são os arquivos: <filename><pacote>.types</filename>, <filename><pacote>-docs.xml</filename> (no passado, .sgml), <filename><pacote>-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
+ <para>Arquivos nos diretórios <filename>xml/</filename> e <filename>html/</filename> não deveriam entrar no controle de versão. Da mesma forma, não deveriam entrar arquivos <filename>.stamp</filename>.</para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-</programlisting>
- </example></para>
- </sect1>
</chapter>
<chapter id="documenting">
<para>GTK-Doc usa comentários do código fonte com uma sintaxe especial para documentação do código. Além disso, ele obtém informações sobre a estrutura do seu projeto a partir de outros fontes. Na próxima seção, você vai descobrir todas as informações sobre a sintaxe dos comentários.</para>
- <note>
- <title>Localização da documentação</title>
- <para>Antigamente, a maioria das documentações tinha que ser preenchida em arquivos residentes dentro do diretório <filename>tmpl</filename>. Isso tem as desvantagens das informações frequentemente não serem atualizadas e também que o arquivo tende a causar conflitos com sistemas de controle de versão.</para>
- <para>Para evitar os problemas mencionados a seguir nós sugerimos que a documentação seja colocada dentro das fontes. Este manual vai apenas descrever esta forma de documentar código.</para>
- </note>
-
- <para>A varredura sabe lidar com a maioria dos cabeçalhos de C sem problemas. Caso se receba avisos (warnings) na varredura que pareça ser um caso especial, pode-se informar ao GTK-Doc para ignorá-los. <example><title>Bloco de comentário do GTK-Doc</title>
- <programlisting>
+ <para>
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
+ <example><title>GTK-Doc comment block</title>
+ <programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
-/* código não analisável arqui */
+/* unparseable code here */
#endif
-</programlisting>
- </example></para>
+]]></programlisting>
+ </example>
+ </para>
<note>
<title>Limitações</title>
<para>Mais exemplos do quais tags de markdown tags tem suporte pode ser encontrado na <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">Referência de sintaxe de markdown de documentação</ulink>.</para>
<tip>
- <para>Como já mencionado anteriormente, GTK-Doc serve para documentar API pública. Portanto, não é possível escrever documentação para símbolos estáticos. Não obstante, é bom comentar estes símbolos também. Isso ajuda outros a entender seu código. Portanto, é recomendado comentá-los usando comentários normais (sem o segundo “*” na primeira linha). Se, posteriormente, a função precisar ser publicada, tudo que precisa ser feito é adicionar outro “*” no bloco de comentário e inserir o nome do símbolo no lugar correto do arquivo e seções.</para>
+ <para>
+ As already mentioned earlier GTK-Doc is for documenting public API. Thus
+ one cannot write documentation for static symbols. Nevertheless it is good
+ to comment those symbols too. This helps other developers to understand
+ your code.
+ Therefore we recommend to comment these using normal comments (without the
+ 2nd '*' in the first line).
+ If later the function needs to be made public, all one needs to do is to
+ add another '*' in the comment block and insert the symbol name at the
+ right place inside the sections file.
+ </para>
</tip>
</sect1>
<para>Se sua biblioteca ou aplicativo inclui GObjects, você deseja que seus sinais, argumentos/parâmetros e posição na hierarquia sejam mostrados na documentação. Tudo que você precisa fazer é listar as funções <function>xxx_get_type</function> junto com seus include dentro do arquivo <filename><pacote>.types</filename>.</para>
<para>
- <example><title>Trecho de exemplo de arquivo de tipos</title>
+ <example><title>Example <package>.types file</title>
<programlisting>
#include <gtk/gtk.h>
<sect1 id="modernizing-gtk-doc-1-25">
<title>GTK-Doc 1.25</title>
- <para>Os makefiles fornecidos com esta versão geram um arquivo de entidade em <filename>xml/gtkdocentities.ent</filename>, contendo entidades para, por exemplo, nome-pacote e versão-pacote. Você pode usar isto, por exemplo, no arquivo xml principal para evitar ter que inserir diretamente o número de versão. Logo abaixo encontra-se um exemplo que mostra como o arquivo de entidade é incluído e como as entidades são usadas. As entidades também podem ser usadas em todos arquivos gerados, GTK-Doc usará o mesmo cabeçalho xml nos arquivos xml gerados. <example><title>Usando entradas geradas previamente</title>
- <programlisting>
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ <para>
+ The makefiles shipped with this version generate an entity file at <filename>xml/gtkdocentities.ent</filename>,
+ containing entities for e.g. package_name and package_version. You can
+ use this e.g. in the main xml file to avoid hardcoding the version
+ number. Below is an example that shows how the entity file is included
+ in the master template and how the entities are used.
+ The entities can also be used in all
+ generated files, GTK-Doc will use the same xml header in generated xml
+ files.
+ <example><title>Use pre-generated entities</title>
+ <programlisting><![CDATA[
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
- <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
- <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
- <bookinfo>
- <title>Manual de referência do &nome-pacote;</title>
- <releaseinfo>
- para &versão-pacote;.
- A última versão desta documentação pode ser encontra on-line em
- <ulink role="online-location" url="http://[SERVIDOR]/&nome-pacote;/index.html">http://[SERVIDOR]/&nome-pacote;/</ulink>.
- </releaseinfo>
- </bookinfo>
-</programlisting>
- </example></para>
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+ <bookinfo>
+ <title>&package_name; Reference Manual</title>
+ <releaseinfo>
+ for &package_string;.
+ The latest version of this documentation can be found on-line at
+ <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
+ </releaseinfo>
+ </bookinfo>
+]]></programlisting>
+ </example>
+ </para>
</sect1>
</chapter>
"Project-Id-Version: gtk-doc help\n"
"Report-Msgid-Bugs-To: http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-"
"doc&keywords=I18N+L10N&component=general\n"
-"POT-Creation-Date: 2017-12-28 10:31+0000\n"
-"PO-Revision-Date: 2018-01-23 11:16-0200\n"
+"POT-Creation-Date: 2018-03-24 15:17+0000\n"
+"PO-Revision-Date: 2018-03-28 23:03-0200\n"
"Last-Translator: Rafael Fontenelle <rafaelff@gnome.org>\n"
"Language-Team: Brazilian Portuguese <gnome-pt_br-list@gnome.org>\n"
"Language: pt_BR\n"
#. (itstool) path: revhistory/revision
#: C/index.docbook:83
#| msgid ""
-#| "<revnumber>1.26.1</revnumber> <date>11 Aug 2017</date> "
+#| "<revnumber>1.27.1</revnumber> <date>07 Dec 2017</date> "
#| "<authorinitials>ss</authorinitials> <revremark>development</revremark>"
msgid ""
-"<revnumber>1.2
7.1</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
+"<revnumber>1.2
8.1</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>development</revremark>"
msgstr ""
-"<revnumber>1.27.1</revnumber> <date>07 Dez 2017</date> "
+"<revnumber>1.28.1</revnumber> <date>24 Mar 2018</date> "
"<authorinitials>ss</authorinitials> <revremark>desenvolvimento</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
+#| msgid ""
+#| "<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
+#| "authorinitials> <revremark>bug fix</revremark>"
+msgid ""
+"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes</revremark>"
+msgstr ""
+"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> "
+"<authorinitials>ss</authorinitials> <revremark>correçãoõesão de "
+"erros</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
msgid ""
"<revnumber>1.27</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>fine tuning of the python port</revremark>"
msgstr ""
-"<revnumber>1.27</revnumber> <date>07 Maio 2017</date> "
-"<authorinitials>ss</authorinitials> <revremark>ajustes do porte para "
-"Python</revremark>"
+"<revnumber>1.27</revnumber> <date>07 Maio 2017</date> <authorinitials>ss</"
+"authorinitials> <revremark>ajustes do porte para Python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
msgid ""
"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>port all tools from perl/bash to python</"
"revremark>"
msgstr ""
-"<revnumber>1.26</revnumber> <date>11 Ago 2017</date> "
-"<authorinitials>ss</authorinitials> <revremark>portadas todas ferramentas de "
-"perl/bash para Python</revremark>"
+"<revnumber>1.26</revnumber> <date>11 Ago 2017</date> <authorinitials>ss</"
+"authorinitials> <revremark>portadas todas ferramentas de perl/bash para "
+"Python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
+#: C/index.docbook:107
msgid ""
"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
msgstr ""
-"<revnumber>1.25</revnumber> <date>21 Mar 2016</date> "
-"<authorinitials>ss</authorinitials> <revremark>correção de erros, limpezas "
-"de testes</revremark>"
+"<revnumber>1.25</revnumber> <date>21 Mar 2016</date> <authorinitials>ss</"
+"authorinitials> <revremark>correção de erros, limpezas de testes</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:107
+#: C/index.docbook:113
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>correção de erros</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:113
+#: C/index.docbook:119
msgid ""
"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>correção de erros</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:119
+#: C/index.docbook:125
msgid ""
"<revnumber>1.22</revnumber> <date>07 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"obsoletas</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:125
+#: C/index.docbook:131
msgid ""
"<revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"obsoletas</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:131
+#: C/index.docbook:137
msgid ""
"<revnumber>1.20</revnumber> <date>16 Feb 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, markdown support, style improvements</"
"no estilo</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:137
+#: C/index.docbook:143
msgid ""
"<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
"authorinitials> <revremark>correção de erros</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:143
+#: C/index.docbook:149
msgid ""
"<revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, speedups, markdown support</revremark>"
"markdown</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:149
+#: C/index.docbook:155
msgid ""
"<revnumber>1.17</revnumber> <date>26 Feb 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>urgent bug fix update</revremark>"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:155
+#: C/index.docbook:161
msgid ""
"<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes, layout improvements</revremark>"
"authorinitials> <revremark>correção de erros, melhorias no layout</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:161
+#: C/index.docbook:167
msgid ""
"<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bug and regression fixes</revremark>"
"authorinitials> <revremark>correção de erros e regressões</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:167
+#: C/index.docbook:173
msgid ""
"<revnumber>1.14</revnumber> <date>28 March 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes and performance improvements</revremark>"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:173
+#: C/index.docbook:179
msgid ""
"<revnumber>1.13</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>broken tarball update</"
"authorinitials> <revremark>atualização de tarball defeituoso</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:179
+#: C/index.docbook:185
msgid ""
"<revnumber>1.12</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>new tool features and "
"erros</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:185
+#: C/index.docbook:191
msgid ""
"<revnumber>1.11</revnumber> <date>16 November 2008</date> "
"<authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</"
"authorinitials> <revremark>migração do GNOME doc-utils</revremark>"
#. (itstool) path: chapter/title
-#: C/index.docbook:198
+#: C/index.docbook:204
msgid "Introduction"
msgstr "Introdução"
#. (itstool) path: chapter/para
-#: C/index.docbook:200
+#: C/index.docbook:206
msgid ""
"This chapter introduces GTK-Doc and gives an overview of what it is and how "
"it is used."
"usado."
#. (itstool) path: sect1/title
-#: C/index.docbook:206
+#: C/index.docbook:212
msgid "What is GTK-Doc?"
msgstr "O que é GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:208
+#: C/index.docbook:214
msgid ""
"GTK-Doc is used to document C code. It is typically used to document the "
"public API of libraries, such as the GTK+ and GNOME libraries. But it can "
"GNOME. Mas ele também pode ser usado para documentar código de aplicativos."
#. (itstool) path: sect1/title
-#: C/index.docbook:216
+#: C/index.docbook:222
msgid "How Does GTK-Doc Work?"
msgstr "Como o GTK-Doc funciona?"
#. (itstool) path: sect1/para
-#: C/index.docbook:218
+#: C/index.docbook:224
msgid ""
"GTK-Doc works by using documentation of functions placed inside the source "
"files in specially-formatted comment blocks, or documentation added to the "
"arquivos de cabeçalho; ele não irá produzir saída para funções estáticas)."
#. (itstool) path: sect1/para
-#: C/index.docbook:225
+#: C/index.docbook:231
msgid ""
"GTK-Doc consists of a number of python scripts, each performing a different "
"step in the process."
"etapa diferente no processo."
#. (itstool) path: sect1/para
-#: C/index.docbook:230
+#: C/index.docbook:236
msgid "There are 5 main steps in the process:"
msgstr "Há 5 etapas principais no processo:"
#. (itstool) path: listitem/para
-#: C/index.docbook:237
+#: C/index.docbook:243
msgid ""
"<guilabel>Writing the documentation.</guilabel> The author fills in the "
"source files with the documentation for each function, macro, union etc. (In "
"que não é mais recomendado)."
#. (itstool) path: listitem/para
-#: C/index.docbook:247
+#: C/index.docbook:253
msgid ""
"<guilabel>Gathering information about the code.</guilabel> "
"<application>gtkdoc-scan</application> scans the header files of the code "
"txt</filename> no <filename><módulo>-overrides.txt</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:264
+#: C/index.docbook:270
msgid ""
"<application>gtkdoc-scangobj</application> can also be used to dynamically "
"query a library about any GObject subclasses it exports. It saves "
"fornece."
#. (itstool) path: listitem/para
-#: C/index.docbook:270
+#: C/index.docbook:276
msgid ""
"<application>gtkdoc-scanobj</application> should not be used anymore. It was "
"needed in the past when GObject was still GtkObject inside gtk+."
"era necessário no passado, quando GObject ainda era GtkObject dentro do gtk+."
#. (itstool) path: listitem/para
-#: C/index.docbook:277
+#: C/index.docbook:283
msgid ""
"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
"mkdb</application> turns the template files into XML files in the <filename "
"documentos dos dados de introspecção e dos fontes."
#. (itstool) path: listitem/para
-#: C/index.docbook:286
+#: C/index.docbook:292
msgid ""
"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
"pacote>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:292
+#: C/index.docbook:298
msgid ""
"Files in <filename class=\"directory\">xml/</filename> and <filename class="
"\"directory\">html/</filename> directories are always overwritten. One "
"devem ser editados manualmente."
#. (itstool) path: listitem/para
-#: C/index.docbook:300
+#: C/index.docbook:306
msgid ""
"<guilabel>Fixing up cross-references between documents.</guilabel> After "
"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
"volta para links locais (onde aquelas documentações estão instaladas)."
#. (itstool) path: sect1/title
-#: C/index.docbook:318
+#: C/index.docbook:324
msgid "Getting GTK-Doc"
msgstr "Obtendo GTK-Doc"
#. (itstool) path: sect2/title
-#: C/index.docbook:321
+#: C/index.docbook:327
msgid "Requirements"
msgstr "Requisitos"
#. (itstool) path: sect2/para
-#: C/index.docbook:322
+#: C/index.docbook:328
msgid ""
"<guilabel>python 2/3</guilabel> - the main scripts are written in python."
msgstr ""
"Python."
#. (itstool) path: sect2/para
-#: C/index.docbook:325
+#: C/index.docbook:331
msgid ""
"<guilabel>xsltproc</guilabel> - the xslt processor from libxslt <ulink url="
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
#. (itstool) path: sect2/para
-#: C/index.docbook:329
+#: C/index.docbook:335
msgid ""
"<guilabel>docbook-xsl</guilabel> - the docbook xsl stylesheets <ulink url="
"\"http://sourceforge.net/projects/docbook/files/docbook-xsl/\" type=\"http"
"\"http\">sourceforge.net/projects/docbook/files/docbook-xsl</ulink>"
#. (itstool) path: sect2/para
-#: C/index.docbook:333
+#: C/index.docbook:339
msgid ""
"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
"sintaxe de exemplos"
#. (itstool) path: sect1/title
-#: C/index.docbook:341
+#: C/index.docbook:347
msgid "About GTK-Doc"
msgstr "Sobre GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:343 C/index.docbook:357
+#: C/index.docbook:349 C/index.docbook:363
msgid "(FIXME)"
msgstr "(CORRIJA-ME)"
#. (itstool) path: sect1/para
-#: C/index.docbook:347
+#: C/index.docbook:353
msgid ""
"(History, authors, web pages, mailing list, license, future plans, "
"comparison with other similar systems.)"
"futuros, comparação com outros sistemas similares.)"
#. (itstool) path: sect1/title
-#: C/index.docbook:355
+#: C/index.docbook:361
msgid "About this Manual"
msgstr "Sobre este manual"
#. (itstool) path: sect1/para
-#: C/index.docbook:361
+#: C/index.docbook:367
msgid "(who it is meant for, where you can get it, license)"
msgstr "(pra quem ele serve, onde você pode obtê-lo, licença)"
#. (itstool) path: chapter/title
-#: C/index.docbook:370
+#: C/index.docbook:376
msgid "Setting up your project"
msgstr "Preparando seu projeto"
#. (itstool) path: chapter/para
-#: C/index.docbook:372
+#: C/index.docbook:378
msgid ""
"The next sections describe what steps to perform to integrate GTK-Doc into "
"your project. Theses sections assume we work on a project called 'meep'. "
"uma configuração de compilação diferente."
#. (itstool) path: sect1/title
-#: C/index.docbook:383
+#: C/index.docbook:389
msgid "Setting up a skeleton documentation"
msgstr "Preparando o esqueleto de uma documentação"
#. (itstool) path: sect1/para
-#: C/index.docbook:385
+#: C/index.docbook:391
msgid ""
"Under your top-level project directory create folders called docs/reference "
"(this way you can also have docs/help for end-user documentation). It is "
"obrigatória."
#. (itstool) path: example/title
-#: C/index.docbook:394
+#: C/index.docbook:400
msgid "Example directory structure"
msgstr "Exemplo de estrutura de diretórios"
#. (itstool) path: example/programlisting
-#: C/index.docbook:395
+#: C/index.docbook:401
#, no-wrap
msgid ""
"\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:392
+#: C/index.docbook:398
msgid "This can then look as shown below: <_:example-1/>"
msgstr "Isto pode, então, parecer como exibido abaixo: <_:example-1/>"
#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:410 C/index.docbook:417
+#: C/index.docbook:416 C/index.docbook:423
msgid "Integration with autoconf"
msgstr "Integração com autoconf"
#. (itstool) path: sect1/para
-#: C/index.docbook:412
+#: C/index.docbook:418
msgid ""
"Very easy! Just add one line to your <filename>configure.ac</filename> "
"script."
"filename>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:418
+#: C/index.docbook:424
#, no-wrap
msgid ""
"\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
#. (itstool) path: example/title
-#: C/index.docbook:430
+#: C/index.docbook:436
msgid "Keep gtk-doc optional"
msgstr "Mantenha o gtk-doc como opcional"
#. (itstool) path: example/programlisting
-#: C/index.docbook:431
+#: C/index.docbook:437
#, no-wrap
msgid ""
"\n"
"])\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:425
+#: C/index.docbook:431
msgid ""
"This will require all developers to have gtk-doc installed. If it is okay "
"for your project to have optional api-doc build setup, you can solve this as "
"<function>GTK_DOC_CHECK</function> no começo de uma linha. <_:example-1/>"
#. (itstool) path: sect1/para
-#: C/index.docbook:442
+#: C/index.docbook:448
msgid ""
"The first argument is used to check for the gtkdocversion at configure time. "
"The 2nd, optional argument is used by <application>gtkdocize</application>. "
"também adiciona várias opções de configuração:"
#. (itstool) path: listitem/para
-#: C/index.docbook:448
+#: C/index.docbook:454
msgid "--with-html-dir=PATH : path to installed docs"
msgstr "--with-html-dir=CAMINHO : caminho para as documentações instaladas"
#. (itstool) path: listitem/para
-#: C/index.docbook:449
+#: C/index.docbook:455
msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]"
msgstr "--enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=no]"
#. (itstool) path: listitem/para
-#: C/index.docbook:450
+#: C/index.docbook:456
msgid ""
"--enable-gtk-doc-html : build documentation in html format [default=yes]"
msgstr ""
"--enable-gtk-doc-html : compila documentação em formato html [padrão=sim]"
#. (itstool) path: listitem/para
-#: C/index.docbook:451
+#: C/index.docbook:457
msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
msgstr ""
"--enable-gtk-doc-pdf : compila documentação em formato pdf [padrão=não]"
#. (itstool) path: important/para
-#: C/index.docbook:455
+#: C/index.docbook:461
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"que faz sentido para usuários, mas não para desenvolvedores)."
#. (itstool) path: sect1/para
-#: C/index.docbook:463
+#: C/index.docbook:469
msgid ""
"Furthermore it is recommended that you have the following line inside your "
"<filename>configure.ac</filename> script. This allows "
"macro para <function>GTK_DOC_CHECK</function> para o seu projeto."
#. (itstool) path: example/title
-#: C/index.docbook:471
+#: C/index.docbook:477
msgid "Preparation for gtkdocize"
msgstr "Preparação para gtkdocize"
#. (itstool) path: example/programlisting
-#: C/index.docbook:472
+#: C/index.docbook:478
#, no-wrap
msgid ""
"\n"
"AC_CONFIG_MACRO_DIR(m4)\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:477
+#: C/index.docbook:483
msgid ""
"After all changes to <filename>configure.ac</filename> are made, update the "
"<filename>configure</filename> file. This can be done by re-running "
"executando novamente <code>autoreconf -i</code> ou <code>autogen.sh</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:485
+#: C/index.docbook:491
msgid "Integration with automake"
msgstr "Integração com automake"
#. (itstool) path: sect1/para
-#: C/index.docbook:487
+#: C/index.docbook:493
msgid ""
"First copy the <filename>Makefile.am</filename> from the <filename class="
"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
"documentação, repita isso para cada um."
#. (itstool) path: sect1/para
-#: C/index.docbook:498
+#: C/index.docbook:504
msgid ""
"The next step is to edit the settings inside the <filename>Makefile.am</"
"filename>. All the settings have a comment above that describes their "
"suporte a <option>--help</option> pra listar os parâmetros disponíveis."
#. (itstool) path: sect1/title
-#: C/index.docbook:512
+#: C/index.docbook:518
msgid "Integration with autogen"
msgstr "Integração com autogen"
#. (itstool) path: sect1/para
-#: C/index.docbook:514
+#: C/index.docbook:520
msgid ""
"Most projects will have an <filename>autogen.sh</filename> script to setup "
"the build infrastructure after a checkout from version control system (such "
"O gtkdocize deveria ser executado antes de autoheader, automake ou autoconf."
#. (itstool) path: example/title
-#: C/index.docbook:523
+#: C/index.docbook:529
msgid "Running gtkdocize from autogen.sh"
msgstr "Executando gtkdocize no autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:524
+#: C/index.docbook:530
#, no-wrap
msgid ""
"\n"
"gtkdocize || exit 1\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:530
+#: C/index.docbook:536
msgid ""
"When running <application>gtkdocize</application> it copies <filename>gtk-"
"doc.make</filename> to your project root (or any directory specified by the "
"<application>gtkdocize</application>."
#. (itstool) path: sect1/para
-#: C/index.docbook:539
+#: C/index.docbook:545
msgid ""
"Historically GTK-Doc was generating template files where developers entered "
"the docs. This turned out to be not so good (e.g. the need for having "
#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:556 C/index.docbook:573
+#: C/index.docbook:562 C/index.docbook:579
msgid "Running the doc build"
msgstr "Executando a compilação da documentação"
#. (itstool) path: sect1/para
-#: C/index.docbook:558
+#: C/index.docbook:564
msgid ""
"After the previous steps it's time to run the build. First we need to rerun "
"<filename>autogen.sh</filename>. If this script runs configure for you, then "
"<filename>configure</filename> com esta opção em seguida."
#. (itstool) path: sect1/para
-#: C/index.docbook:565
+#: C/index.docbook:571
msgid ""
"The first make run generates several additional files in the doc-"
"directories. The important ones are: <filename><package>.types</"
"<filename><pacote>-sections.txt</filename>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:574
+#: C/index.docbook:580
#, no-wrap
msgid ""
"\n"
"make\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:580
+#: C/index.docbook:586
msgid ""
"Now you can point your browser to <filename>docs/reference/<package>/"
"index.html</filename>. Yes, it's a bit disappointing still. But hang-on, "
"páginas com vida."
#. (itstool) path: sect1/title
-#: C/index.docbook:588
+#: C/index.docbook:594
msgid "Integration with version control systems"
msgstr "Integração com sistemas de controle de versão"
#. (itstool) path: sect1/para
-#: C/index.docbook:590
+#: C/index.docbook:596
msgid ""
"As a rule of thumb, it's the files you edit which should go under version "
"control. For typical projects it's these files: <filename><package>."
"filename>, <filename>Makefile.am</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:598
+#: C/index.docbook:604
msgid ""
"Files in the <filename>xml/</filename> and <filename>html/</filename> "
"directories should not go under version control. Neither should any of the "
"deveriam entrar arquivos <filename>.stamp</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:606
+#: C/index.docbook:612
msgid "Integration with plain makefiles or other build systems"
msgstr "Integração com makefiles simples ou outros sistemas de compilação"
#. (itstool) path: sect1/para
-#: C/index.docbook:608
+#: C/index.docbook:614
msgid ""
"In the case one does not want to use automake and therefore <filename>gtk-"
"doc.mak</filename> one will need to call the gtkdoc tools in the right order "
"correta nos makefiles devidos (ou outras ferramentas de compilação)."
#. (itstool) path: example/title
-#: C/index.docbook:615
+#: C/index.docbook:621
msgid "Documentation build steps"
msgstr "Etapas de compilação da documentação"
#. (itstool) path: example/programlisting
-#: C/index.docbook:616
+#: C/index.docbook:622
#, no-wrap
msgid ""
"\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:630
+#: C/index.docbook:636
msgid ""
"One will need to look at the <filename>Makefile.am</filename> and "
"<filename>gtk-doc.mak</filename> to pick the extra options needed."
"doc.mak</filename> para obter as opções extras necessárias."
#. (itstool) path: sect1/title
-#: C/index.docbook:637
+#: C/index.docbook:643
msgid "Integration with CMake build systems"
msgstr "Integração com sistemas de compilação CMake"
#. (itstool) path: sect1/para
-#: C/index.docbook:639
+#: C/index.docbook:645
msgid ""
"GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module (and "
"the corresponding <filename>GtkDocConfigVersion.cmake</filename> module). "
"em seu arquivo <filename>CMakeLists.txt</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:649
+#: C/index.docbook:655
msgid "Example of using GTK-Doc from CMake"
msgstr "Exemplo de uso do GTK-Doc no CMake"
#. (itstool) path: example/programlisting
-#: C/index.docbook:650
+#: C/index.docbook:656
#, no-wrap
msgid ""
"\n"
" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:647
+#: C/index.docbook:653
msgid "The following example shows how to use this command. <_:example-1/>"
msgstr "O exemplo a seguir mostra como usar este comando. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:675
+#: C/index.docbook:681
msgid "Documenting the code"
msgstr "Documentando o código"
#. (itstool) path: chapter/para
-#: C/index.docbook:677
+#: C/index.docbook:683
msgid ""
"GTK-Doc uses source code comment with a special syntax for code "
"documentation. Further it retrieves information about your project structure "
"descobrir todas as informações sobre a sintaxe dos comentários."
#. (itstool) path: note/title
-#: C/index.docbook:685
+#: C/index.docbook:691
msgid "Documentation placement"
msgstr "Localização da documentação"
#. (itstool) path: note/para
-#: C/index.docbook:686
+#: C/index.docbook:692
msgid ""
"In the past most documentation had to be filled into files residing inside "
"the <filename>tmpl</filename> directory. This has the disadvantages that the "
"versão."
#. (itstool) path: note/para
-#: C/index.docbook:692
+#: C/index.docbook:698
msgid ""
"The avoid the aforementioned problems we suggest putting the documentation "
"inside the sources. This manual will only describe this way of documenting "
"descrever esta forma de documentar código."
#. (itstool) path: example/title
-#: C/index.docbook:703 C/index.docbook:729
+#: C/index.docbook:709 C/index.docbook:735
msgid "GTK-Doc comment block"
msgstr "Bloco de comentário do GTK-Doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:704
+#: C/index.docbook:710
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:699
+#: C/index.docbook:705
msgid ""
"The scanner can handle the majority of C headers fine. In the case of "
"receiving warnings from the scanner that look like a special case, one can "
"pode-se informar ao GTK-Doc para ignorá-los. <_:example-1/>"
#. (itstool) path: note/title
-#: C/index.docbook:713
+#: C/index.docbook:719
msgid "Limitations"
msgstr "Limitações"
#. (itstool) path: note/para
-#: C/index.docbook:714
+#: C/index.docbook:720
msgid ""
"Note, that GTK-Doc's supports <code>#ifndef(__GTK_DOC_IGNORE__)</code> but "
"not <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations."
"combinações."
#. (itstool) path: sect1/title
-#: C/index.docbook:724
+#: C/index.docbook:730
msgid "Documentation comments"
msgstr "Comentários de documentação"
#. (itstool) path: example/programlisting
-#: C/index.docbook:730
+#: C/index.docbook:736
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:726
+#: C/index.docbook:732
msgid ""
"A multiline comment that starts with an additional '*' marks a documentation "
"block that will be processed by the GTK-Doc tools. <_:example-1/>"
# Ocultei o TODO da tradução. Para que server? :/
#. (itstool) path: sect1/para
-#: C/index.docbook:739
+#: C/index.docbook:745
msgid ""
"The 'identifier' is one line with the name of the item the comment is "
"related to. The syntax differs a little depending on the item. (TODO add "
"relacionado. A sintaxe difere um pouco dependendo do item."
#. (itstool) path: sect1/para
-#: C/index.docbook:745
+#: C/index.docbook:751
msgid ""
"The 'documentation' block is also different for each symbol type. Symbol "
"types that get parameters such as functions or macros have the parameter "
"espaço). Isso é útil em textos pré-formatados (listagens de código)."
#. (itstool) path: listitem/para
-#: C/index.docbook:762
+#: C/index.docbook:768
msgid ""
"What it is: The name for a class or function can sometimes be misleading for "
"people coming from a different background."
"entendimento equivocado pessoas com experiências diferentes."
#. (itstool) path: listitem/para
-#: C/index.docbook:768
+#: C/index.docbook:774
msgid ""
"What it does: Tell about common uses. Put it in relation with the other API."
msgstr ""
"O que isso faz: Fale sobre usos comuns. Coloque em relação com a outra API."
#. (itstool) path: tip/para
-#: C/index.docbook:758
+#: C/index.docbook:764
msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>"
msgstr "Ao documentar um código, descreva dois aspectos: <_:itemizedlist-1/>"
#. (itstool) path: listitem/para
-#: C/index.docbook:783
+#: C/index.docbook:789
msgid "Use function() to refer to functions or macros which take arguments."
msgstr "Use function() para referir às funções ou macros que levam argumentos."
#. (itstool) path: listitem/para
-#: C/index.docbook:788
+#: C/index.docbook:794
msgid ""
"Use @param to refer to parameters. Also use this when referring to "
"parameters of other functions, related to the one being described."
"parâmetros de outras funções, relacionadas àquele sendo descrito."
#. (itstool) path: listitem/para
-#: C/index.docbook:794
+#: C/index.docbook:800
msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS."
msgstr "Use %constant para se referir a uma constante, ex.: %G_TRAVERSE_LEAFS."
#. (itstool) path: listitem/para
-#: C/index.docbook:799
+#: C/index.docbook:805
msgid ""
"Use #symbol to refer to other types of symbol, e.g. structs and enums and "
"macros which don't take arguments."
"e macros que não levam argumentos."
#. (itstool) path: listitem/para
-#: C/index.docbook:805
+#: C/index.docbook:811
msgid "Use #Object::signal to refer to a GObject signal."
msgstr "Use #Object::signal para se referir a um sinal de GObject."
#. (itstool) path: listitem/para
-#: C/index.docbook:810
+#: C/index.docbook:816
msgid "Use #Object:property to refer to a GObject property."
msgstr "Use #Object:property para se referir a uma propriedade de GObject."
#. (itstool) path: listitem/para
-#: C/index.docbook:815
+#: C/index.docbook:821
msgid ""
"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
"foo_bar() to refer to a vmethod."
"#GObjectClass.foo_bar() para se referir a um vmethod."
#. (itstool) path: sect1/para
-#: C/index.docbook:777
+#: C/index.docbook:783
msgid ""
"One advantage of hyper-text over plain-text is the ability to have links in "
"the document. Writing the correct markup for a link can be tedious though. "
"itemizedlist-1/>"
#. (itstool) path: tip/para
-#: C/index.docbook:824
+#: C/index.docbook:830
msgid ""
"If you need to use the special characters '<', '>', '()', '@', '%', or "
"'#' in your documentation without GTK-Doc changing them you can use the XML "
"uma contrabarra “\\”."
#. (itstool) path: sect1/para
-#: C/index.docbook:833
+#: C/index.docbook:839
msgid ""
"DocBook can do more than just links. One can also have lists, examples, "
"headings, and images. As of version 1.20, the preferred way is to use a "
"linhas começando com um traço."
#. (itstool) path: sect1/para
-#: C/index.docbook:844
+#: C/index.docbook:850
msgid ""
"While markdown is now preferred one can mix both. One limitation here is "
"that one can use docbook xml within markdown, but markdown within docbook "
"suporte a markdown no docbook xml."
#. (itstool) path: sect1/para
-#: C/index.docbook:850
+#: C/index.docbook:856
msgid ""
"In older GTK-Doc releases, if you need support for additional formatting, "
"you would need to enable the usage of docbook XML tags inside doc-comments "
"symbol> dentro de <filename>Makefile.am</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:859
+#: C/index.docbook:865
msgid "GTK-Doc comment block using Markdown"
msgstr "Bloco de comentário do GTK-Doc usando Markdown"
#. (itstool) path: example/programlisting
-#: C/index.docbook:860
+#: C/index.docbook:866
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:899
+#: C/index.docbook:905
msgid ""
"More examples of what markdown tags are supported can be found in the <ulink "
"url=\"https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown"
"Markdown\">Referência de sintaxe de markdown de documentação</ulink>."
#. (itstool) path: tip/para
-#: C/index.docbook:905
+#: C/index.docbook:911
msgid ""
"As already mentioned earlier GTK-Doc is for documenting public API. Thus one "
"cannot write documentation for static symbols. Nevertheless it is good to "
"comentário e inserir o nome do símbolo no lugar correto do arquivo e seções."
#. (itstool) path: sect1/title
-#: C/index.docbook:919
+#: C/index.docbook:925
msgid "Documenting sections"
msgstr "Documentando seções"
#. (itstool) path: sect1/para
-#: C/index.docbook:921
+#: C/index.docbook:927
msgid ""
"Each section of the documentation contains information about one class or "
"module. To introduce the component one can write a section block. The short "
"os @fields são opcionais."
#. (itstool) path: example/title
-#: C/index.docbook:929
+#: C/index.docbook:935
msgid "Section comment block"
msgstr "Bloco de comentário de sessão"
#. (itstool) path: example/programlisting
-#: C/index.docbook:930
+#: C/index.docbook:936
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:949
+#: C/index.docbook:955
msgid "SECTION:<name>"
msgstr "SECTION:<nome>"
#. (itstool) path: listitem/para
-#: C/index.docbook:951
+#: C/index.docbook:957
msgid ""
"The name links the section documentation to the respective part in the "
"<filename><package>-sections.txt</filename> file. The name given here "
"txt</filename>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:960
+#: C/index.docbook:966
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:962
+#: C/index.docbook:968
msgid ""
"A one line description of the section, that later will appear after the "
"links in the TOC and at the top of the section page."
"no TOC (sumário) no topo da página da sessão."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:969
+#: C/index.docbook:975
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:971
+#: C/index.docbook:977
msgid ""
"The section title defaults to <name> from the SECTION declaration. It "
"can be overridden with the @title field."
"pode ser sobrescrito com o campo @title."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:978
+#: C/index.docbook:984
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:980
+#: C/index.docbook:986
msgid ""
"Overrides the use of title as a section identifier. For GObjects the <"
"title> is used as a section_id and for other sections it is <"
"MÓDULO>-<title>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:988
+#: C/index.docbook:994
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:990
+#: C/index.docbook:996
msgid "A list of symbols that are related to this section."
msgstr "Uma lista de símbolos que estão relacionados a esta sessão."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:996
+#: C/index.docbook:1002
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1003
+#: C/index.docbook:1009
msgid ""
"Stable - The intention of a Stable interface is to enable arbitrary third "
"parties to develop applications to these interfaces, release them, and have "
"alterações incompatíveis sejam raras e que tenham fortes justificativas."
#. (itstool) path: listitem/para
-#: C/index.docbook:1015
+#: C/index.docbook:1021
msgid ""
"Unstable - Unstable interfaces are experimental or transitional. They are "
"typically used to give outside developers early access to new or rapidly "
"fontes de uma versão menor para a próxima."
#. (itstool) path: listitem/para
-#: C/index.docbook:1027
+#: C/index.docbook:1033
msgid ""
"Private - An interface that can be used within the GNOME stack itself, but "
"that is not documented for end-users. Such functions should only be used in "
"usadas nas formas especificadas e documentadas."
#. (itstool) path: listitem/para
-#: C/index.docbook:1036
+#: C/index.docbook:1042
msgid ""
"Internal - An interface that is internal to a module and does not require "
"end-user documentation. Functions that are undocumented are assumed to be "
"sendo “Interna”."
#. (itstool) path: listitem/para
-#: C/index.docbook:998
+#: C/index.docbook:1004
msgid ""
"An informal description of the stability level this API has. We recommend "
"the use of one of these terms: <_:itemizedlist-1/>"
"recomendamos o uso de um desses termos: <_:itemizedlist-1/>"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1048
+#: C/index.docbook:1054
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1050
+#: C/index.docbook:1056
msgid ""
"The <literal>#include</literal> files to show in the section synopsis (a "
"comma separated list), overriding the global value from the <link linkend="
"Este item é opcional."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1059
+#: C/index.docbook:1065
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1061
+#: C/index.docbook:1067
msgid ""
"The image to display at the top of the reference page for this section. This "
"will often be some sort of a diagram to illustrate the visual appearance of "
"opcional."
#. (itstool) path: tip/para
-#: C/index.docbook:1072
+#: C/index.docbook:1078
msgid ""
"To avoid unnecessary recompilation after doc-changes put the section docs "
"into the c-source where possible."
"inseridas nas documentações de seção no fonte em C onde possível."
#. (itstool) path: sect1/title
-#: C/index.docbook:1081
+#: C/index.docbook:1087
msgid "Documenting symbols"
msgstr "Documentando símbolos"
#. (itstool) path: sect1/para
-#: C/index.docbook:1083
+#: C/index.docbook:1089
msgid ""
"Each symbol (function, macro, struct, enum, signal and property) is "
"documented in a separate block. The block is best placed close to the "
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1091 C/index.docbook:1157
+#: C/index.docbook:1097 C/index.docbook:1163
msgid "General tags"
msgstr "Tags gerais"
#. (itstool) path: sect2/para
-#: C/index.docbook:1093
+#: C/index.docbook:1099
msgid ""
"You can add versioning information to all documentation elements to tell "
"when an API was introduced, or when it was deprecated."
"tornou obsoleta."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1098
+#: C/index.docbook:1104
msgid "Versioning Tags"
msgstr "Tags de versionamento"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1099
+#: C/index.docbook:1105
msgid "Since:"
msgstr "Since:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1101
+#: C/index.docbook:1107
msgid "Description since which version of the code the API is available."
msgstr "Descrição de desde qual versão do código a API está disponível."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1106
+#: C/index.docbook:1112
msgid "Deprecated:"
msgstr "Deprecated:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1108
+#: C/index.docbook:1114
msgid ""
"Paragraph denoting that this function should no be used anymore. The "
"description should point the reader to the new API."
"deveria apontar o leitor para a nova API."
#. (itstool) path: sect2/para
-#: C/index.docbook:1116
+#: C/index.docbook:1122
msgid ""
"You can also add stability information to all documentation elements to "
"indicate whether API stability is guaranteed for them for all future minor "
"garantida para eles para futuros lançamentos menores do projeto."
#. (itstool) path: sect2/para
-#: C/index.docbook:1122
+#: C/index.docbook:1128
msgid ""
"The default stability level for all documentation elements can be set by "
"passing the <option>--default-stability</option> argument to "
"<application>gtkdoc-mkdb</application> com um dos balores abaixo."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1128
+#: C/index.docbook:1134
msgid "Stability Tags"
msgstr "Tags de estabilidade"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1129
+#: C/index.docbook:1135
msgid "Stability: Stable"
msgstr "Stability: Stable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1131
+#: C/index.docbook:1137
msgid ""
"Mark the element as stable. This is for public APIs which are guaranteed to "
"remain stable for all future minor releases of the project."
"garantida para todos os próximos lançamentos menores do projeto."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1138
+#: C/index.docbook:1144
msgid "Stability: Unstable"
msgstr "Stability: Unstable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1140
+#: C/index.docbook:1146
msgid ""
"Mark the element as unstable. This is for public APIs which are released as "
"a preview before being stabilised."
"como versão de desenvolvimento antes de se tornar estável."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1146
+#: C/index.docbook:1152
msgid "Stability: Private"
msgstr "Stability: Private"
#. (itstool) path: listitem/para
-#: C/index.docbook:1148
+#: C/index.docbook:1154
msgid ""
"Mark the element as private. This is for interfaces which can be used by "
"tightly coupled modules, but not by arbitrary third parties."
"por um conjunto pequeno de módulos, mas não por terceiros."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1158
+#: C/index.docbook:1164
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1178 C/index.docbook:1188
+#: C/index.docbook:1184 C/index.docbook:1194
msgid "Annotations"
msgstr "Anotações"
#. (itstool) path: sect2/para
-#: C/index.docbook:1180
+#: C/index.docbook:1186
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"\">no wiki</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1189
+#: C/index.docbook:1195
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1210 C/index.docbook:1239
+#: C/index.docbook:1216 C/index.docbook:1245
msgid "Function comment block"
msgstr "Bloco de comentário de função"
#. (itstool) path: listitem/para
-#: C/index.docbook:1216
+#: C/index.docbook:1222
msgid ""
"Document whether returned objects, lists, strings, etc, should be freed/"
"unrefed/released."
"não referenciados/liberada."
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1228
msgid "Document whether parameters can be NULL, and what happens if they are."
msgstr ""
"Documente se parâmetros pode ser NULL e o que acontece se eles o forem."
#. (itstool) path: listitem/para
-#: C/index.docbook:1227
+#: C/index.docbook:1233
msgid ""
"Mention interesting pre-conditions and post-conditions where appropriate."
msgstr ""
"Mencione pré-condições e pós-condições interessantes onde for apropriado."
#. (itstool) path: sect2/para
-#: C/index.docbook:1212 C/index.docbook:1298
+#: C/index.docbook:1218 C/index.docbook:1304
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Por favor, lembre-se de: <_:itemizedlist-1/>"
#. (itstool) path: sect2/para
-#: C/index.docbook:1234
+#: C/index.docbook:1240
msgid ""
"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
"private. They are treated like static functions."
"são privadas. Elas são tratadas como funções estáticas."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1240
+#: C/index.docbook:1246
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1261
+#: C/index.docbook:1267
msgid "Function tags"
msgstr "Tags de função"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1262 C/index.docbook:1469
+#: C/index.docbook:1268 C/index.docbook:1475
msgid "Returns:"
msgstr "Returns:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1264
+#: C/index.docbook:1270
msgid "Paragraph describing the returned result."
msgstr "Parágrafo descrevendo o resultado retornado."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1269
+#: C/index.docbook:1275
msgid "@...:"
msgstr "@...:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1271
+#: C/index.docbook:1277
msgid ""
"In case the function has variadic arguments, you should use this tag "
"(@Varargs: does also work for historic reasons)."
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1281 C/index.docbook:1283
+#: C/index.docbook:1287 C/index.docbook:1289
msgid "Property comment block"
msgstr "Bloco de comentário de propriedade"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1284
+#: C/index.docbook:1290
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1296 C/index.docbook:1315
+#: C/index.docbook:1302 C/index.docbook:1321
msgid "Signal comment block"
msgstr "Bloco de comentário de sinal"
#. (itstool) path: listitem/para
-#: C/index.docbook:1302
+#: C/index.docbook:1308
msgid ""
"Document when the signal is emitted and whether it is emitted before or "
"after other signals."
"sinais."
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1314
msgid "Document what an application might do in the signal handler."
msgstr "Documente o que um aplicativo pode fazer no manipulador do sinal."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1316
+#: C/index.docbook:1322
#, no-wrap
-#| msgid ""
-#| "\n"
-#| "/**\n"
-#| " * FooWidget::foobarized:\n"
-#| " * @widget: the widget that received the signal\n"
-#| " * @foo: some foo\n"
-#| " * @bar: some bar\n"
-#| " *\n"
-#| " * The ::foobarized signal is emitted each time someone tries to foobarize @widget.\n"
-#| " */\n"
-#| "foo_signals[FOOBARIZE] =\n"
-#| " g_signal_new (\"foobarize\",\n"
-#| " ...\n"
msgid ""
"\n"
"/**\n"
" * @foo: algum foo\n"
" * @bar: algum bar\n"
" *\n"
-" * O sinal ::foobarized é emitido cada vez que alguém tenta foobarizar "
-"@widget.\n"
+" * O sinal ::foobarized é emitido cada vez que alguém tenta foobarizar @widget.\n"
" */\n"
"foo_sinais[FOOBARIZADO] =\n"
" g_signal_novo (\"foobarizado\",\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1333 C/index.docbook:1334
+#: C/index.docbook:1339 C/index.docbook:1340
msgid "Struct comment block"
msgstr "Bloco de comentário de struct"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1335
+#: C/index.docbook:1341
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1350
+#: C/index.docbook:1356
msgid ""
"Use <code>/*< private >*/</code> before the private struct fields you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"comportamento inverso."
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1362
msgid ""
"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" "
"it will be considered private automatically and doesn't need to be mentioned "
"no bloco de comentário."
#. (itstool) path: sect2/para
-#: C/index.docbook:1362
+#: C/index.docbook:1368
msgid ""
"Struct comment blocks can also be used for GObjects and GObjectClasses. It "
"is usually a good idea to add a comment block for a class, if it has "
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1374 C/index.docbook:1375
+#: C/index.docbook:1380 C/index.docbook:1381
msgid "Enum comment block"
msgstr "Bloco de comentário de enum"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1376
+#: C/index.docbook:1382
#, no-wrap
msgid ""
"\n"
"} Alguma coisa;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1393
+#: C/index.docbook:1399
msgid ""
"Use <code>/*< private >*/</code> before the private enum values you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"comportamento inverso."
#. (itstool) path: sect1/title
-#: C/index.docbook:1404
+#: C/index.docbook:1410
msgid "Inline program documentation"
msgstr "Documentação de programa em-linha"
#. (itstool) path: sect1/para
-#: C/index.docbook:1405
+#: C/index.docbook:1411
msgid ""
"You can document programs and their commandline interface using inline "
"documentation."
"documentação em-linha."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1411
+#: C/index.docbook:1417
msgid "Tags"
msgstr "Tags"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1413
+#: C/index.docbook:1419
msgid "PROGRAM"
msgstr "PROGRAM"
#. (itstool) path: listitem/para
-#: C/index.docbook:1416
+#: C/index.docbook:1422
msgid "Defines the start of a program documentation."
msgstr "Define o início da documentação de um programa."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1423
+#: C/index.docbook:1429
msgid "@short_description:"
msgstr "@short_description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1425
+#: C/index.docbook:1431
msgid "Defines a short description of the program. (Optional)"
msgstr "Define uma descrição breve do programa. (Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1432
+#: C/index.docbook:1438
msgid "@synopsis:"
msgstr "@synopsis:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1434
+#: C/index.docbook:1440
msgid ""
"Defines the arguments, or list of arguments that the program can take. "
"(Optional)"
"(Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1442
+#: C/index.docbook:1448
msgid "@see_also:"
msgstr "@see_also:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1444
+#: C/index.docbook:1450
msgid "See Also manual page section. (Optional)"
msgstr "A seção “Veja Também” (See Also) de páginas de manual. (Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1451
+#: C/index.docbook:1457
msgid "@arg:"
msgstr "@arg:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1453
+#: C/index.docbook:1459
msgid "Argument(s) passed to the program and their description. (Optional)"
msgstr "Argumento(s) passado(s) para o programa e sua descrição. (Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1460
+#: C/index.docbook:1466
msgid "Description:"
msgstr "Description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1462
+#: C/index.docbook:1468
msgid "A longer description of the program."
msgstr "Um descrição mais longa do programa."
#. (itstool) path: listitem/para
-#: C/index.docbook:1471
+#: C/index.docbook:1477
msgid "Specificy what value(s) the program returns. (Optional)"
msgstr "Especifique quais valor(es) o programa retorna. (Opcional)"
#. (itstool) path: sect2/title
-#: C/index.docbook:1480
+#: C/index.docbook:1486
msgid "Example of program documentation."
msgstr "Exemplo de documentação de programa."
#. (itstool) path: example/title
-#: C/index.docbook:1481
+#: C/index.docbook:1487
msgid "Program documentation block"
msgstr "Bloco de documentação de programa"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1482
+#: C/index.docbook:1488
#, no-wrap
msgid ""
"\n"
"}\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1508
+#: C/index.docbook:1514
msgid "Useful DocBook tags"
msgstr "Tags úteis do DocBook"
#. (itstool) path: sect1/para
-#: C/index.docbook:1510
+#: C/index.docbook:1516
msgid ""
"Here are some DocBook tags which are most useful when documenting the code."
msgstr ""
"documentado o código."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1519
+#: C/index.docbook:1525
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Tabela de hashes</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1515
+#: C/index.docbook:1521
msgid ""
"To link to another section in the GTK docs: <_:informalexample-1/> The "
"linkend is the SGML/XML id on the top item of the page you want to link to. "
"convertidos em '-' para estar em conformidade com SGML/XML."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1532
+#: C/index.docbook:1538
#, no-wrap
msgid ""
"\n"
"<function>...</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1529
+#: C/index.docbook:1535
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
"do C: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1541
+#: C/index.docbook:1547
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1552
+#: C/index.docbook:1558
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1538
+#: C/index.docbook:1544
msgid ""
"To include example code: <_:informalexample-1/> or possibly this, for very "
"short code fragments which don't need a title: <_:informalexample-2/> For "
"abreviação: |[ ... ]|"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1571
+#: C/index.docbook:1577
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1568
+#: C/index.docbook:1574
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Para incluir listas com marcadores: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1591
+#: C/index.docbook:1597
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1588
+#: C/index.docbook:1594
msgid ""
"To include a note which stands out from the text: <_:informalexample-1/>"
msgstr "Para incluir uma nota que fique fora do texto: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1604
+#: C/index.docbook:1610
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1601
+#: C/index.docbook:1607
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "Para se referir a um tipo: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1613
+#: C/index.docbook:1619
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1610
+#: C/index.docbook:1616
msgid ""
"To refer to an external structure (not one described in the GTK docs): <_:"
"informalexample-1/>"
"GTK): <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1622
+#: C/index.docbook:1628
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1619
+#: C/index.docbook:1625
msgid "To refer to a field of a structure: <_:informalexample-1/>"
msgstr "Para se referir a um campo de uma estrutura: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1631
+#: C/index.docbook:1637
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1628
+#: C/index.docbook:1634
msgid ""
"To refer to a class name, we could possibly use: <_:informalexample-1/> but "
"you'll probably be using #GtkWidget instead (to automatically create a link "
"veja <link linkend=\"documenting_syntax\">as abreviações</link>)."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1642
+#: C/index.docbook:1648
#, no-wrap
msgid ""
"\n"
"<emphasis>Isso é importante</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1639
+#: C/index.docbook:1645
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Para enfatizar um texto: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1651
+#: C/index.docbook:1657
#, no-wrap
msgid ""
"\n"
"<filename>/home/usuario/documentos</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1648
+#: C/index.docbook:1654
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Para nome de arquivos use: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1660
+#: C/index.docbook:1666
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1657
+#: C/index.docbook:1663
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "Para se referir a chaves use: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1670
+#: C/index.docbook:1676
msgid "Filling the extra files"
msgstr "Preenchendo os arquivos extras"
#. (itstool) path: chapter/para
-#: C/index.docbook:1672
+#: C/index.docbook:1678
msgid ""
"There are a couple of extra files, that need to be maintained along with the "
"inline source code comments: <filename><package>.types</filename>, "
"<filename><pacote>-sections.txt</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1681
+#: C/index.docbook:1687
msgid "Editing the types file"
msgstr "Editando o arquivo de tipos"
#. (itstool) path: sect1/para
-#: C/index.docbook:1683
+#: C/index.docbook:1689
msgid ""
"If your library or application includes GObjects, you want their signals, "
"arguments/parameters and position in the hierarchy to be shown in the "
"<filename><pacote>.types</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:1692
+#: C/index.docbook:1698
msgid "Example types file snippet"
msgstr "Trecho de exemplo de arquivo de tipos"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1693
+#: C/index.docbook:1699
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1704
+#: C/index.docbook:1710
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"deveria distribuir o arquivo de tipos nem tê-lo sob um controle de versão."
#. (itstool) path: sect1/title
-#: C/index.docbook:1713
+#: C/index.docbook:1719
msgid "Editing the master document"
msgstr "Editando o documento mestre"
#. (itstool) path: sect1/para
-#: C/index.docbook:1715
+#: C/index.docbook:1721
msgid ""
"GTK-Doc produces documentation in DocBook SGML/XML. When processing the "
"inline source comments, the GTK-Doc tools generate one documentation page "
"mestre os inclui e os coloca em uma ordem."
#. (itstool) path: sect1/para
-#: C/index.docbook:1722
+#: C/index.docbook:1728
msgid ""
"While GTK-Doc creates a template master document for you, later runs will "
"not touch it again. This means that one can freely structure the "
"em tempo para ver se há itens a serem introduzidos lá."
#. (itstool) path: tip/para
-#: C/index.docbook:1732
+#: C/index.docbook:1738
msgid ""
"Do not create tutorials as extra documents. Just write extra chapters. The "
"benefit of directly embedding the tutorial for your library into the API "
"atualizações junto com a biblioteca."
#. (itstool) path: sect1/para
-#: C/index.docbook:1741
+#: C/index.docbook:1747
msgid ""
"So what are the things to change inside the master document? For a start is "
"only a little. There are some placeholders (text in square brackets) there "
"colchetes) que você deve cuidar."
#. (itstool) path: example/title
-#: C/index.docbook:1748
+#: C/index.docbook:1754
msgid "Master document header"
msgstr "Cabeçalho do documento mestre"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1749
+#: C/index.docbook:1755
#, no-wrap
msgid ""
"\n"
" <title>[Insira o título aqui]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1765
+#: C/index.docbook:1771
msgid ""
"In addition a few option elements are created in commented form. You can "
"review these and enable them as you like."
"pode revisá-los e habilitá-los como preferir."
#. (itstool) path: example/title
-#: C/index.docbook:1771
+#: C/index.docbook:1777
msgid "Optional part in the master document"
msgstr "Parte opcional do documento mestre"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1772
+#: C/index.docbook:1778
#, no-wrap
msgid ""
"\n"
" -->\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1780
+#: C/index.docbook:1786
msgid ""
"Finally you need to add new section whenever you introduce one. The <link "
"linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> tool will remind "
"incluídos na documentação."
#. (itstool) path: example/title
-#: C/index.docbook:1788 C/index.docbook:1823
+#: C/index.docbook:1794 C/index.docbook:1829
msgid "Including generated sections"
msgstr "Incluindo seções geradas"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1789
+#: C/index.docbook:1795
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1801
+#: C/index.docbook:1807
msgid "Editing the section file"
msgstr "Editando o arquivo de seção"
#. (itstool) path: sect1/para
-#: C/index.docbook:1803
+#: C/index.docbook:1809
msgid ""
"The section file is used to organise the documentation output by GTK-Doc. "
"Here one specifies which symbol belongs to which module or class and control "
"e controla a visibilidade (pública ou privada)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1809
+#: C/index.docbook:1815
msgid ""
"The section file is a plain text file with tags delimiting sections. Blank "
"lines are ignored and lines starting with a '#' are treated as comment lines."
"tratadas como linhas de comentários."
#. (itstool) path: note/para
-#: C/index.docbook:1816
+#: C/index.docbook:1822
msgid ""
"While the tags make the file look like xml, it is not. Please do not close "
"tags like <SUBSECTION>."
"feche tags como <SUBSECTION>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1824
+#: C/index.docbook:1830
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1841
+#: C/index.docbook:1847
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"para minúsculos)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1853
+#: C/index.docbook:1859
msgid ""
"The <TITLE> ... </TITLE> tag is used to specify the title of the "
"section. It is only useful before the templates (if used) are initially "
"obsoleto."
#. (itstool) path: sect1/para
-#: C/index.docbook:1860
+#: C/index.docbook:1866
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"padrão ou pública depende se há entradas públicas (variáveis, vmethods)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1879
+#: C/index.docbook:1885
msgid ""
"You can also use <INCLUDE> ... </INCLUDE> to specify the "
"#include files which are shown in the synopsis sections. It contains a comma-"
"aplicar àquela seção."
#. (itstool) path: chapter/title
-#: C/index.docbook:1893
+#: C/index.docbook:1899
msgid "Controlling the result"
msgstr "Controlando o resultado"
#. (itstool) path: chapter/para
-#: C/index.docbook:1895
+#: C/index.docbook:1901
msgid ""
"A GTK-Doc run generates report files inside the documentation directory. The "
"generated files are named: <filename><package>-undocumented.txt</"
"processados."
#. (itstool) path: chapter/para
-#: C/index.docbook:1904
+#: C/index.docbook:1910
msgid ""
"The <filename><package>-undocumented.txt</filename> file starts with "
"the documentation coverage summary. Below are two sections divided by blank "
"exemplo, um novo parâmetro foi adicionado."
#. (itstool) path: chapter/para
-#: C/index.docbook:1913
+#: C/index.docbook:1919
msgid ""
"The <filename><package>-undeclared.txt</filename> file lists symbols "
"given in the <filename><package>-sections.txt</filename> but not found "
"escritos incorretamente."
#. (itstool) path: chapter/para
-#: C/index.docbook:1920
+#: C/index.docbook:1926
msgid ""
"The <filename><package>-unused.txt</filename> file lists symbol names, "
"where the GTK-Doc scanner has found documentation, but does not know where "
"ainda ao arquivo <filename><pacote>-sections.txt</filename>."
#. (itstool) path: tip/para
-#: C/index.docbook:1928
+#: C/index.docbook:1934
msgid ""
"Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile."
"am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during "
"verificações de sanidade durante a execução de <command>make check</command>."
#. (itstool) path: chapter/para
-#: C/index.docbook:1935
+#: C/index.docbook:1941
msgid ""
"One can also look at the files produced by the source code scanner: "
"<filename><package>-decl-list.txt</filename> and <filename><"
"este arquivo o contém."
#. (itstool) path: chapter/para
-#: C/index.docbook:1944
+#: C/index.docbook:1950
msgid ""
"If the project is GObject based, one can also look into the files produced "
"by the object scanner: <filename><package>.args.txt</filename>, "
"executando <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>."
#. (itstool) path: chapter/title
-#: C/index.docbook:1959
+#: C/index.docbook:1965
msgid "Modernizing the documentation"
msgstr "Modernizando a documentação"
#. (itstool) path: chapter/para
-#: C/index.docbook:1961
+#: C/index.docbook:1967
msgid ""
"GTK-Doc has been around for quite some time. In this section we list new "
"features together with the version since when it is available."
"funcionalidades juntamente da versão desde a qual está disponível."
#. (itstool) path: sect1/title
-#: C/index.docbook:1967
+#: C/index.docbook:1973
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1969
+#: C/index.docbook:1975
msgid ""
"When using xml instead of sgml, one can actually name the master document "
"<filename><package>-docs.xml</filename>."
"<filename><pacote>-docs.xml</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1974
+#: C/index.docbook:1980
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-sections</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"<code>meld <package>-decl-list.txt <package>-sections.txt</code>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1985
+#: C/index.docbook:1991
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"ao <filename>configure.ac</filename> e está resolvido."
#. (itstool) path: sect1/title
-#: C/index.docbook:1997
+#: C/index.docbook:2003
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:1999
+#: C/index.docbook:2005
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"código que é compilado condicionalmente."
#. (itstool) path: sect1/title
-#: C/index.docbook:2010
+#: C/index.docbook:2016
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:2016
+#: C/index.docbook:2022
msgid "Enable gtkdoc-check"
msgstr "Habilitar gtkdoc-check"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2017
+#: C/index.docbook:2023
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2012
+#: C/index.docbook:2018
msgid ""
"This version includes a new tool called gtkdoc-check. This tool can run a "
"set of sanity checks on your documentation. It is enabled by adding these "
"filename>. <_:example-1/>"
#. (itstool) path: sect1/title
-#: C/index.docbook:2030
+#: C/index.docbook:2036
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:2032
+#: C/index.docbook:2038
msgid ""
"Version 1.18 brought some initial markdown support. Using markdown in doc "
"comments is less intrusive than writing docbook xml. This version improves a "
"comentário</link> tem todos os detalhes."
#. (itstool) path: sect1/title
-#: C/index.docbook:2042
+#: C/index.docbook:2048
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:2052
+#: C/index.docbook:2058
msgid "Use pre-generated entities"
msgstr "Usando entradas geradas previamente"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2053
+#: C/index.docbook:2059
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2044
+#: C/index.docbook:2050
msgid ""
"The makefiles shipped with this version generate an entity file at "
"<filename>xml/gtkdocentities.ent</filename>, containing entities for e.g. "
"xml nos arquivos xml gerados. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:2078
+#: C/index.docbook:2084
msgid "Documenting other interfaces"
msgstr "Documentando outras interfaces"
#. (itstool) path: chapter/para
-#: C/index.docbook:2080
+#: C/index.docbook:2086
msgid ""
"So far we have been using GTK-Doc to document the API of code. The next "
"sections contain suggestions how the tools can be used to document other "
"para documentar outras interfaces, também."
#. (itstool) path: sect1/title
-#: C/index.docbook:2087
+#: C/index.docbook:2093
msgid "Command line options and man pages"
msgstr "Opções de linha de comando e de páginas man"
# RefEntry é uma página de referência do DocBook (http://www.docbook.org/tdg/en/html/refentry.html)
#. (itstool) path: sect1/para
-#: C/index.docbook:2089
+#: C/index.docbook:2095
msgid ""
"As one can generate man pages for a docbook refentry as well, it sounds like "
"a good idea to use it for that purpose. This way the interface is part of "
"parte da referência e é possível obter a página man de graça."
#. (itstool) path: sect2/title
-#: C/index.docbook:2096
+#: C/index.docbook:2102
msgid "Document the tool"
msgstr "Documentar a ferramenta"
#. (itstool) path: sect2/para
-#: C/index.docbook:2098
+#: C/index.docbook:2104
msgid ""
"Create one refentry file per tool. Following <link linkend="
"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
"assim como exemplos, por exemplo, em glib."
#. (itstool) path: sect2/title
-#: C/index.docbook:2108
+#: C/index.docbook:2114
msgid "Adding the extra configure check"
msgstr "Adicionando a verificação extra ao configure"
#. (itstool) path: example/title
-#: C/index.docbook:2111 C/index.docbook:2129
+#: C/index.docbook:2117 C/index.docbook:2135
msgid "Extra configure checks"
msgstr "Verificações extra no configure"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2112
+#: C/index.docbook:2118
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2126
+#: C/index.docbook:2132
msgid "Adding the extra makefile rules"
msgstr "Adicionando as regras extras ao makefile"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2130
+#: C/index.docbook:2136
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2152
+#: C/index.docbook:2158
msgid "DBus interfaces"
msgstr "Interfaces DBus"
#. (itstool) path: sect1/para
-#: C/index.docbook:2154
+#: C/index.docbook:2160
msgid ""
"(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://"
"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
"http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
#. (itstool) path: chapter/title
-#: C/index.docbook:2163
+#: C/index.docbook:2169
msgid "Frequently asked questions"
msgstr "Perguntas frequentes"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2167
+#: C/index.docbook:2173
msgid "Question"
msgstr "Questão"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2168
+#: C/index.docbook:2174
msgid "Answer"
msgstr "Resposta"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2170
+#: C/index.docbook:2176
msgid "No class hierarchy."
msgstr "Sem hierarquia de classe."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2171
+#: C/index.docbook:2177
msgid ""
"The objects <function>xxx_get_type()</function> function has not been "
"entered into the <filename><package>.types</filename> file."
"arquivo <filename><pacote>.types</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2177
+#: C/index.docbook:2183
msgid "Still no class hierarchy."
msgstr "Ainda sem hierarquia."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2178
+#: C/index.docbook:2184
msgid ""
"Missing or wrong naming in <filename><package>-sections.txt</filename> "
"file (see <ulink url=\"http://mail.gnome.org/archives/gtk-doc-list/2003-"
"gtk-doc-list/2003-October/msg00006.html\">explicação</ulink>)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2184
+#: C/index.docbook:2190
msgid "Damn, I have still no class hierarchy."
msgstr "Droga. Eu ainda não tenho hierarquia de classes."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2185
+#: C/index.docbook:2191
msgid ""
"Is the object name (name of the instance struct, e.g. <type>GtkWidget</"
"type>) part of the normal section (don't put this into Standard or Private "
"subseções Standard ou Private)?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2192
+#: C/index.docbook:2198
msgid "No symbol index."
msgstr "Nenhum símbolo de índice."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2193
+#: C/index.docbook:2199
msgid ""
"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
"index that xi:includes the generated index?"
"“xi:inclui” o índice gerado?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2199
+#: C/index.docbook:2205
msgid "Symbols are not linked to their doc-section."
msgstr "Símbolos não estão vinculados ao seus doc-section."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2200
+#: C/index.docbook:2206
msgid ""
"Is the doc-comment using the correct markup (added #,% or ())? Check if the "
"gtkdoc-fixxref warns about unresolvable xrefs."
"Verifique se o gtkdoc-fixxref avisa sobre xrefs não resolvidos."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2206
+#: C/index.docbook:2212
msgid "A new class does not appear in the docs."
msgstr "Uma nova classe não aparece nos documentos."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2207
+#: C/index.docbook:2213
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"filename>?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2213
+#: C/index.docbook:2219
msgid "A new symbol does not appear in the docs."
msgstr "Um novo símbolo não aparece nos documentos."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2214
+#: C/index.docbook:2220
msgid ""
"Is the doc-comment properly formatted. Check for spelling mistakes in the "
"begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable "
"<filename><pacote>-sections.txt</filename> em uma subseção pública."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2222
+#: C/index.docbook:2228
msgid "A type is missing from the class hierarchy."
msgstr "Um tipo está faltando da hierarquia de classe."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2223
+#: C/index.docbook:2229
msgid ""
"If the type is listed in <filename><package>.hierarchy</filename> but "
"not in <filename>xml/tree_index.sgml</filename> then double check that the "
"listada ou incidentalmente marcada como privada, ela não será mostrada."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2232
+#: C/index.docbook:2238
msgid "I get foldoc links for all gobject annotations."
msgstr ""
"Obtenho links de seguimento de documentos para todas as anotações gobject."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2233
+#: C/index.docbook:2239
msgid ""
"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
"from <filename><package>-docs.{xml,sgml}</filename>."
"incluído” de <filename><pacote>-docs.{xml,sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2241
+#: C/index.docbook:2247
msgid "Parameter described in source code comment block but does not exist"
msgstr "Parâmetro descrito no bloco de comentário do código fonte não existe"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2242
+#: C/index.docbook:2248
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
"fonte."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2247
+#: C/index.docbook:2253
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "múltiplos “IDs” para restrições do fim do link XYZ"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2248
+#: C/index.docbook:2254
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"sections.txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2251
+#: C/index.docbook:2257
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"correspondeu."
#. (itstool) path: chapter/title
-#: C/index.docbook:2258
+#: C/index.docbook:2264
msgid "Tools related to gtk-doc"
msgstr "Ferramentas relacionadas ao gtk-doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2260
+#: C/index.docbook:2266
msgid ""
"GtkDocPlugin - a <ulink url=\"http://trac-hacks.org/wiki/GtkDocPlugin\">Trac "
"GTK-Doc</ulink> integration plugin, that adds API docs to a trac site and "
"a um site trac e integra com a pesquisa do trac."
#. (itstool) path: chapter/para
-#: C/index.docbook:2265
+#: C/index.docbook:2271
msgid ""
"Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since "
"tags in the API to determine the minimum required version."
<revhistory>
<revision>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development</revremark>
+ </revision>
+ <revision>
<revnumber>1.28</revnumber>
<date>24 Mar 2018</date>
<authorinitials>ss</authorinitials>
<guilabel>Writing the documentation.</guilabel>
The author fills in the source files with the documentation for each
- function, macro, union etc. (In the past information was entered in
- generated template files, which is not recommended anymore).
+ function, macro, structs or unions, etc.
</para>
</listitem>
<title>About GTK-Doc</title>
<para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
+ <para>
(FIXME)
</para>
<para>
- (History, authors, web pages, mailing list, license, future plans,
+ (authors, web pages, mailing list, license, future plans,
comparison with other similar systems.)
</para>
</chapter>
<chapter id="settingup">
- <title>Setting up your project</title>
+ <title>Project Setup</title>
+
+ <para>
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- The next sections describe what steps to perform to integrate GTK-Doc into
- your project. Theses sections assume we work on a project called 'meep'.
- This project contains a library called 'libmeep' and
- an end-user app called 'meeper'. We also assume you will be using autoconf
- and automake. In addition section <link linkend="plain_makefiles">plain
- makefiles or other build systems</link> will describe the basics needed to
- work in a different build setup.
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
</para>
<sect1 id="settingup_docfiles">
<title>Setting up a skeleton documentation</title>
<para>
- Under your top-level project directory create folders called docs/reference
- (this way you can also have docs/help for end-user documentation).
- It is recommended to create another subdirectory with the name of the doc-package.
- For packages with just one library this step is not necessary.
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
</para>
<para>
- This can then look as shown below:
- <example><title>Example directory structure</title>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
<programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
</para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>Integration with autoconf</title>
-
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
<para>
- Very easy! Just add one line to your <filename>configure.ac</filename> script.
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
+
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>Integration with autoconf</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-]]></programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>
- This will require all developers to have gtk-doc installed. If it is
- okay for your project to have optional api-doc build setup, you can
- solve this as below. Keep it as is, as gtkdocize is looking for
- <function>GTK_DOC_CHECK</function> at the start of a line.
- <example><title>Keep gtk-doc optional</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-],[
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
-]]></programlisting>
+ <sect2 id="settingup_automake">
+ <title>Integration with automake</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
+ <programlisting>
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
+</programlisting>
</example>
- </para>
- <para>
- The first argument is used to check for the gtkdocversion at configure time.
- The 2nd, optional argument is used by <application>gtkdocize</application>.
- The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure switches:
- </para>
- <orderedlist>
- <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
- <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
- <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
+
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <important>
- <para>
- GTK-Doc is disabled by default! Remember to pass the option
- <option>'--enable-gtk-doc'</option> to the next
- <filename>configure</filename> run. Otherwise pregenerated documentation is installed
- (which makes sense for users but not for developers).
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
+
+ All the tools support <option>--help</option> to list the supported
+ options.
</para>
- </important>
- <para>
- Furthermore it is recommended that you have the following line inside
- your <filename>configure.ac</filename> script.
- This allows <application>gtkdocize</application> to automatically copy the
- macro definition for <function>GTK_DOC_CHECK</function> to your project.
- </para>
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
- <para>
- <example><title>Preparation for gtkdocize</title>
- <programlisting><![CDATA[
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>Integration with autoconf</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
]]></programlisting>
- </example>
- </para>
- <para>
- After all changes to <filename>configure.ac</filename> are made, update
- the <filename>configure</filename> file. This can be done by re-running
- <code>autoreconf -i</code> or <code>autogen.sh</code>.
- </para>
- </sect1>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>Integration with automake</title>
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub directory of the
- <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
- to your project's API documentation directory (
- <filename class="directory">./docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple doc-packages repeat this for each one.
- </para>
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <para>
- The next step is to edit the settings inside the <filename>Makefile.am</filename>.
- All the settings have a comment above that describes their purpose.
- Most settings are extra flags passed to the respective tools. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
- All the tools support <option>--help</option> to list the supported
- parameters.
- </para>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <!-- FIXME: explain options ? -->
+ <orderedlist>
+ <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
+ <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
+ </orderedlist>
- </sect1>
+ <important>
+ <para>
+ GTK-Doc is disabled by default! Remember to pass the option
+ <option>'--enable-gtk-doc'</option> to the next
+ <filename>configure</filename> run. Otherwise pregenerated documentation is installed
+ (which makes sense for users but not for developers).
+ </para>
+ </important>
- <sect1 id="settingup_autogen">
- <title>Integration with autogen</title>
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- <para>
- Most projects will have an <filename>autogen.sh</filename> script to
- setup the build infrastructure after a checkout from version control
- system (such as cvs/svn/git). GTK-Doc comes with a tool called
- <application>gtkdocize</application> which can be used in such a script.
- It should be run before autoheader, automake or autoconf.
- </para>
+ <sect2 id="settingup_autogen">
+ <title>Integration with autogen</title>
- <para>
- <example><title>Running gtkdocize from autogen.sh</title>
- <programlisting><![CDATA[
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
+
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
+
+ <para>
+ <example><title>Running gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
gtkdocize || exit 1
]]></programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>
- When running <application>gtkdocize</application> it copies
- <filename>gtk-doc.make</filename> to your project root (or any directory
- specified by the <option>--docdir</option> option).
- It also checks you configure script for the <function>GTK_DOC_CHECK</function>
- invocation. This macro can be used to pass extra parameters to
- <application>gtkdocize</application>.
- </para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>
- Historically GTK-Doc was generating template files where developers entered the docs.
- This turned out to be not so good (e.g. the need for having generated
- files under version control).
- Since GTK-Doc 1.9 the tools can get all the information from source comments
- and thus the templates can be avoided. We encourage people to keep
- documentation in the code. <application>gtkdocize</application> supports now
- a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
- tmpl usage totally. Besides adding the option directly to the command
- invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
- or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
- If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
- please remove the directory (e.g. from version control system).
- </para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>Running the doc build</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>
- After the previous steps it's time to run the build. First we need to
- rerun <filename>autogen.sh</filename>. If this script runs configure for
- you, then give it the <option>--enable-gtk-doc</option> option.
- Otherwise manually run <filename>configure</filename> with this option
- afterwards.
- </para>
- <para>
- The first make run generates several additional files in the doc-directories.
- The important ones are:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>.
- </para>
- <para>
- <example><title>Running the doc build</title>
- <programlisting><![CDATA[
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>
+ After the previous steps it's time to run the build. First we need to
+ rerun <filename>autogen.sh</filename>. If this script runs configure
+ for you, then give it the <option>--enable-gtk-doc</option> option.
+ Otherwise manually run <filename>configure</filename> with this option
+ afterwards.
+ </para>
+ <para>
+ The first make run generates several additional files in the doc-directories.
+ The important ones are:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>.
+ </para>
+ <para>
+ <example><title>Running the doc build</title>
+ <programlisting><![CDATA[
./autogen.sh --enable-gtk-doc
make
]]></programlisting>
- </example>
- </para>
- <para>
- Now you can point your browser to <filename>docs/reference/<package>/index.html</filename>.
- Yes, it's a bit disappointing still. But hang-on, during the next chapter we
- tell you how to fill the pages with life.
- </para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>Integration with version control systems</title>
+ <sect1 id="settingup_cmake">
+ <title>Integration with CMake build systems</title>
<para>
- As a rule of thumb, it's the files you edit which should go under
- version control. For typical projects it's these files:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>,
- <filename>Makefile.am</filename>.
+ GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
+ (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
+ module). This provides a <literal>gtk_doc_add_module</literal>
+ command that you can set in your <filename>CMakeLists.txt</filename>
+ file.
</para>
+
<para>
- Files in the <filename>xml/</filename> and <filename>html/</filename>
- directories should not go under version control. Neither should any of
- the <filename>.stamp</filename> files.
+ The following example shows how to use this command.
+ <example><title>Example of using GTK-Doc from CMake</title>
+ <programlisting><![CDATA[
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+]]></programlisting>
+ </example>
</para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integration with plain makefiles or other build systems</title>
<para>
</para>
</sect1>
- <sect1 id="cmake">
- <title>Integration with CMake build systems</title>
-
- <para>
- GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
- (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
- module). This provides a <literal>gtk_doc_add_module</literal>
- command that you can set in your <filename>CMakeLists.txt</filename>
- file.
- </para>
-
- <para>
- The following example shows how to use this command.
- <example><title>Example of using GTK-Doc from CMake</title>
- <programlisting><![CDATA[
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>Integration with version control systems</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>
+ As a rule of thumb, it's the files you edit which should go under
+ version control. For typical projects it's these files:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>,
+ <filename>Makefile.am</filename>.
+ </para>
+ <para>
+ Files in the <filename>xml/</filename> and <filename>html/</filename>
+ directories should not go under version control. Neither should any of
+ the <filename>.stamp</filename> files.
+ </para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
- </sect1>
</chapter>
<chapter id="documenting">
syntax of the comments.
</para>
- <note>
- <title>Documentation placement</title>
- <para>
- In the past most documentation had to be filled into files residing
- inside the <filename>tmpl</filename> directory. This has the
- disadvantages that the information is often not updated and also that
- the file tend to cause conflicts with version control systems.
- </para>
- <para>
- The avoid the aforementioned problems we suggest putting the
- documentation inside the sources. This manual will only describe this
- way of documenting code.
- </para>
- </note>
-
<para>
- The scanner can handle the majority of C headers fine. In the case of
- receiving warnings from the scanner that look like a special case, one can
- hint GTK-Doc to skip over them.
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<para>
As already mentioned earlier GTK-Doc is for documenting public API. Thus
one cannot write documentation for static symbols. Nevertheless it is good
- to comment those symbols too. This helps other to understand you code.
+ to comment those symbols too. This helps other developers to understand
+ your code.
Therefore we recommend to comment these using normal comments (without the
2nd '*' in the first line).
If later the function needs to be made public, all one needs to do is to
</para>
<para>
- <example><title>Example types file snippet</title>
+ <example><title>Example <package>.types file</title>
<programlisting><![CDATA[
#include <gtk/gtk.h>
containing entities for e.g. package_name and package_version. You can
use this e.g. in the main xml file to avoid hardcoding the version
number. Below is an example that shows how the entity file is included
- and how the entities are used. The entities can also be used in all
+ in the master template and how the entities are used.
+ The entities can also be used in all
generated files, GTK-Doc will use the same xml header in generated xml
files.
<example><title>Use pre-generated entities</title>
<revhistory>
<revision>
- <revnumber>1.28</revnumber>
- <date>24 Mar 2018</date>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>bug fixes</revremark>
+ <revremark>development</revremark>
</revision>
- <revision><revnumber>1.27</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</authorinitials> <revremark>finjustering av python-porteringen</revremark></revision>
- <revision><revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</authorinitials> <revremark>portera alla verktyg från perl/bash till python</revremark></revision>
- <revision><revnumber>1.25</revnumber> <date>21 Mars 2016</date> <authorinitials>ss</authorinitials> <revremark>programfixar, uppstädning av tester</revremark></revision>
- <revision><revnumber>1.24</revnumber> <date>29 Maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfix</revremark></revision>
- <revision><revnumber>1.23</revnumber> <date>17 Maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfix</revremark></revision>
- <revision><revnumber>1.22</revnumber> <date>07 Maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfixar, borttagning av föråldrade funktioner</revremark></revision>
- <revision><revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</authorinitials> <revremark>programfixar, borttagning av föråldrade funktioner</revremark></revision>
- <revision><revnumber>1.20</revnumber> <date>16 Feb 2014</date> <authorinitials>ss</authorinitials> <revremark>programfixar, stöd för markdown, stilförbättringar</revremark></revision>
- <revision><revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</authorinitials> <revremark>programfixar</revremark></revision>
- <revision><revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</authorinitials> <revremark>programfixar, uppsnabbningar, stöd för markdown</revremark></revision>
- <revision><revnumber>1.17</revnumber> <date>26 Feb 2011</date> <authorinitials>sk</authorinitials> <revremark>brådskande programfixuppdatering</revremark></revision>
- <revision><revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</authorinitials> <revremark>programfixar, layoutförbättringar</revremark></revision>
- <revision><revnumber>1.15</revnumber> <date>21 Maj 2010</date> <authorinitials>sk</authorinitials> <revremark>program- och regressionsfixar</revremark></revision>
- <revision><revnumber>1.14</revnumber> <date>28 Mars 2010</date> <authorinitials>sk</authorinitials> <revremark>programfixar och prestandaförbättringar</revremark></revision>
- <revision><revnumber>1.13</revnumber> <date>18 December 2009</date> <authorinitials>sk</authorinitials> <revremark>uppdatering på grund av trasigt tar-arkiv</revremark></revision>
- <revision><revnumber>1.12</revnumber> <date>18 December 2009</date> <authorinitials>sk</authorinitials> <revremark>nya verktygsfunktioner och programfixar</revremark></revision>
- <revision><revnumber>1.11</revnumber> <date>16 November 2008</date> <authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</revremark></revision>
+ <revision><revnumber>1.28</revnumber> <date>24 mar 2018</date> <authorinitials>ss</authorinitials> <revremark>programfixar</revremark></revision>
+ <revision><revnumber>1.27</revnumber> <date>07 dec 2017</date> <authorinitials>ss</authorinitials> <revremark>finjustering av python-porteringen</revremark></revision>
+ <revision><revnumber>1.26</revnumber> <date>11 aug 2017</date> <authorinitials>ss</authorinitials> <revremark>portera alla verktyg från perl/bash till python</revremark></revision>
+ <revision><revnumber>1.25</revnumber> <date>21 mars 2016</date> <authorinitials>ss</authorinitials> <revremark>programfixar, uppstädning av tester</revremark></revision>
+ <revision><revnumber>1.24</revnumber> <date>29 maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfix</revremark></revision>
+ <revision><revnumber>1.23</revnumber> <date>17 maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfix</revremark></revision>
+ <revision><revnumber>1.22</revnumber> <date>07 maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfixar, borttagning av föråldrade funktioner</revremark></revision>
+ <revision><revnumber>1.21</revnumber> <date>17 jul 2014</date> <authorinitials>ss</authorinitials> <revremark>programfixar, borttagning av föråldrade funktioner</revremark></revision>
+ <revision><revnumber>1.20</revnumber> <date>16 feb 2014</date> <authorinitials>ss</authorinitials> <revremark>programfixar, stöd för markdown, stilförbättringar</revremark></revision>
+ <revision><revnumber>1.19</revnumber> <date>05 jun 2013</date> <authorinitials>ss</authorinitials> <revremark>programfixar</revremark></revision>
+ <revision><revnumber>1.18</revnumber> <date>14 sep 2011</date> <authorinitials>ss</authorinitials> <revremark>programfixar, uppsnabbningar, stöd för markdown</revremark></revision>
+ <revision><revnumber>1.17</revnumber> <date>26 feb 2011</date> <authorinitials>sk</authorinitials> <revremark>brådskande programfixuppdatering</revremark></revision>
+ <revision><revnumber>1.16</revnumber> <date>14 jan 2011</date> <authorinitials>sk</authorinitials> <revremark>programfixar, layoutförbättringar</revremark></revision>
+ <revision><revnumber>1.15</revnumber> <date>21 maj 2010</date> <authorinitials>sk</authorinitials> <revremark>program- och regressionsfixar</revremark></revision>
+ <revision><revnumber>1.14</revnumber> <date>28 mars 2010</date> <authorinitials>sk</authorinitials> <revremark>programfixar och prestandaförbättringar</revremark></revision>
+ <revision><revnumber>1.13</revnumber> <date>18 december 2009</date> <authorinitials>sk</authorinitials> <revremark>uppdatering på grund av trasigt tar-arkiv</revremark></revision>
+ <revision><revnumber>1.12</revnumber> <date>18 december 2009</date> <authorinitials>sk</authorinitials> <revremark>nya verktygsfunktioner och programfixar</revremark></revision>
+ <revision><revnumber>1.11</revnumber> <date>16 november 2008</date> <authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</revremark></revision>
</revhistory>
<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>
+ <para>
+ <guilabel>Writing the documentation.</guilabel>
+
+ The author fills in the source files with the documentation for each
+ function, macro, structs or unions, etc.
+ </para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>Om GTK-Doc</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(FIXME)</para>
- <para>(Historia, författare, webbsidor, sändlistor, licens, framtida planer, jämförelse med andra liknande system.)</para>
+ <para>
+ (authors, web pages, mailing list, license, future plans,
+ comparison with other similar systems.)
+ </para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Att ställa in ditt projekt</title>
+ <title>Project Setup</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>
+ <para>
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
+ </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>
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
+ </para>
- <para>Detta kan se ut enligt nedan: <example><title>Exempel på katalogstruktur</title>
- <programlisting>
+ <para>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
+ <programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
-</programlisting>
- </example></para>
+]]></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>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
+
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>Integrering med autoconf</title>
- <programlisting>
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-</programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</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>
+ <sect2 id="settingup_automake">
+ <title>Integrering med automake</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </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)
-])
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
</programlisting>
- </example></para>
+ </example>
- <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>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
- <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>
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <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>
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
- <para>
- <example><title>Förberedelse för gtkdocize</title>
- <programlisting>
+ All the tools support <option>--help</option> to list the supported
+ options.
+ </para>
+
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>Integrering med autoconf</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
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>
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+]]></programlisting>
+ </example>
+ </para>
+
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
+
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>Integrering med automake</title>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <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/<paket></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>
+ <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>
- <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><VERKTYGSNAMN>_OPTIONS</option>. Alla verktygen har stöd för <option>--help</option> för att lista de parametrar som stöds.</para>
+ <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>
- <!-- FIXME: explain options ? -->
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- </sect1>
+ <sect2 id="settingup_autogen">
+ <title>Integrering med autogen</title>
- <sect1 id="settingup_autogen">
- <title>Integrering med autogen</title>
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
- <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>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
- <para>
- <example><title>Köra gtkdocize från autogen.sh</title>
- <programlisting>
+ <example><title>Köra gtkdocize från autogen.sh</title>
gtkdocize || exit 1
</programlisting>
- </example>
- </para>
+ </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>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </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>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>Att köra dokumentationsbygget</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <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><paket>.types</filename>, <filename><paket>-docs.xml</filename> (tidigare .sgml), <filename><paket>-sections.txt</filename>.</para>
- <para>
- <example><title>Att köra dokumentationsbygget</title>
- <programlisting>
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</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><paket>.types</filename>, <filename><paket>-docs.xml</filename> (tidigare .sgml), <filename><paket>-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/<paket>/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>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>Integrering med versionshanteringssystem</title>
+ <sect1 id="settingup_cmake">
+ <title>Integrering med CMake-byggsystem</title>
- <para>Som en tumregel är det filerna du redigerar som bör versionshanteras. För typiska projekt är det följande filer: <filename><paket>.types</filename>, <filename><paket>-docs.xml</filename> (tidigare .sgml), <filename><paket>-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>
+ <para>GTK-Doc kommer nu att producera en <filename>GtkDocConfig.cmake</filename>-modul (och motsvarande <filename>GtkDocConfigVersion.cmake</filename>-modul). Detta tillhandahåller ett <literal>gtk_doc_add_module</literal>-kommando som du kan ställa in i din <filename>CMakeLists.txt</filename>-fil.</para>
+
+ <para>Det följande exemplet visar hur du använder detta kommando. <example><title>Exempel på användning av GTK-Doc från CMake</title>
+ <programlisting>
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Skapa målet doc-libmeep.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Bygg doc-libmeep som standardmålet. Utan detta måste du uttryckligen
+# köra något i stil med `make doc-libmeep` för att bygga dokumentationen.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Installera dokumentationen. (Detta förutsätter att du använder CMake-modulen
+# GNUInstallDirs för att ställa in variabeln CMAKE_INSTALL_DOCDIR korrekt).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+</programlisting>
+ </example></para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integrering med vanliga makefiler eller andra byggsystem</title>
<para>I det fall man inte vill använda automake och därför inte heller <filename>gtk-doc.mak</filename> kommer man att behöva anropa gtkdoc-verktygen i rätt ordning i sina egna makefiler (eller andra byggverktyg).</para>
<para>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
-)
+ <sect1 id="settingup_vcs">
+ <title>Integrering med versionshanteringssystem</title>
-# 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)
+ <para>Som en tumregel är det filerna du redigerar som bör versionshanteras. För typiska projekt är det följande filer: <filename><paket>.types</filename>, <filename><paket>-docs.xml</filename> (tidigare .sgml), <filename><paket>-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>
-# 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">
<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>
+ <para>
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
+ <example><title>GTK-Doc comment block</title>
+ <programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif
-</programlisting>
- </example></para>
+]]></programlisting>
+ </example>
+ </para>
<note>
<title>Begränsningar</title>
<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>
+ <para>
+ As already mentioned earlier GTK-Doc is for documenting public API. Thus
+ one cannot write documentation for static symbols. Nevertheless it is good
+ to comment those symbols too. This helps other developers to understand
+ your code.
+ Therefore we recommend to comment these using normal comments (without the
+ 2nd '*' in the first line).
+ If later the function needs to be made public, all one needs to do is to
+ add another '*' in the comment block and insert the symbol name at the
+ right place inside the sections file.
+ </para>
</tip>
</sect1>
<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><package>.types</filename>.</para>
<para>
- <example><title>Exempel på typfilsnutt</title>
+ <example><title>Example <package>.types file</title>
<programlisting>
#include <gtk/gtk.h>
<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>
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ <para>
+ The makefiles shipped with this version generate an entity file at <filename>xml/gtkdocentities.ent</filename>,
+ containing entities for e.g. package_name and package_version. You can
+ use this e.g. in the main xml file to avoid hardcoding the version
+ number. Below is an example that shows how the entity file is included
+ in the master template and how the entities are used.
+ The entities can also be used in all
+ generated files, GTK-Doc will use the same xml header in generated xml
+ files.
+ <example><title>Use pre-generated entities</title>
+ <programlisting><![CDATA[
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
- <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
- <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
- <bookinfo>
- <title>&package_name; handbok</title>
- <releaseinfo>
- för &package_string;.
- Den senaste versionen av detta dokument kan hittas på nätet på
- <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
- </releaseinfo>
- </bookinfo>
-</programlisting>
- </example></para>
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+ <bookinfo>
+ <title>&package_name; Reference Manual</title>
+ <releaseinfo>
+ for &package_string;.
+ The latest version of this documentation can be found on-line at
+ <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
+ </releaseinfo>
+ </bookinfo>
+]]></programlisting>
+ </example>
+ </para>
</sect1>
</chapter>
# Swedish translation of gtk-doc.
-# Copyright © 2009-2017 Free Software Foundation, Inc.
+# Copyright © 2009-2018 Free Software Foundation, Inc.
# This file is distributed under the same license as the gtk-doc package.
# Daniel Nylander <po@danielnylander.se>, 2009.
# Sebastian Rasmussen <sebras@gmail.com>, 2016.
-# Anders Jonsson <anders.jonsson@norsjovallen.se>, 2017.
+# Anders Jonsson <anders.jonsson@norsjovallen.se>, 2017, 2018.
#
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc master\n"
-"POT-Creation-Date: 2017-12-28 10:31+0000\n"
-"PO-Revision-Date: 2018-01-04 01:06+0100\n"
+"POT-Creation-Date: 2018-03-24 15:17+0000\n"
+"PO-Revision-Date: 2018-03-24 22:40+0100\n"
"Last-Translator: Anders Jonsson <anders.jonsson@norsjovallen.se>\n"
"Language-Team: Swedish <tp-sv@listor.tp-sv.se>\n"
"Language: sv\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
-"X-Generator: Poedit 2.0.5\n"
+"X-Generator: Poedit 2.0.6\n"
#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
msgctxt "_"
#. (itstool) path: revhistory/revision
#: C/index.docbook:83
msgid ""
-"<revnumber>1.2
7.1</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
+"<revnumber>1.2
8.1</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>development</revremark>"
msgstr ""
-"<revnumber>1.2
7.1</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
+"<revnumber>1.2
8.1</revnumber> <date>24 mar 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>utveckling</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
msgid ""
+"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes</revremark>"
+msgstr ""
+"<revnumber>1.28</revnumber> <date>24 mar 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>programfixar</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+msgid ""
"<revnumber>1.27</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>fine tuning of the python port</revremark>"
msgstr ""
-"<revnumber>1.27</revnumber> <date>07
Dec 2017</date> <authorinitials>ss</"
+"<revnumber>1.27</revnumber> <date>07
dec 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>finjustering av python-porteringen</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
msgid ""
"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>port all tools from perl/bash to python</"
"revremark>"
msgstr ""
-"<revnumber>1.26</revnumber> <date>11
Aug 2017</date> <authorinitials>ss</"
+"<revnumber>1.26</revnumber> <date>11
aug 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>portera alla verktyg från perl/bash till python</"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
+#: C/index.docbook:107
msgid ""
"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
msgstr ""
-"<revnumber>1.25</revnumber> <date>21
Mars 2016</date> <authorinitials>ss</"
+"<revnumber>1.25</revnumber> <date>21
mars 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>programfixar, uppstädning av tester</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:107
+#: C/index.docbook:113
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
msgstr ""
-"<revnumber>1.24</revnumber> <date>29
Maj 2015</date> <authorinitials>ss</"
+"<revnumber>1.24</revnumber> <date>29
maj 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>programfix</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:113
+#: C/index.docbook:119
msgid ""
"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
msgstr ""
-"<revnumber>1.23</revnumber> <date>17
Maj 2015</date> <authorinitials>ss</"
+"<revnumber>1.23</revnumber> <date>17
maj 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>programfix</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:119
+#: C/index.docbook:125
msgid ""
"<revnumber>1.22</revnumber> <date>07 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"revremark>"
msgstr ""
-"<revnumber>1.22</revnumber> <date>07
Maj 2015</date> <authorinitials>ss</"
+"<revnumber>1.22</revnumber> <date>07
maj 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>programfixar, borttagning av föråldrade "
"funktioner</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:125
+#: C/index.docbook:131
msgid ""
"<revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"revremark>"
msgstr ""
-"<revnumber>1.21</revnumber> <date>17
Jul 2014</date> <authorinitials>ss</"
+"<revnumber>1.21</revnumber> <date>17
jul 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>programfixar, borttagning av föråldrade "
"funktioner</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:131
+#: C/index.docbook:137
msgid ""
"<revnumber>1.20</revnumber> <date>16 Feb 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, markdown support, style improvements</"
"revremark>"
msgstr ""
-"<revnumber>1.20</revnumber> <date>16
Feb 2014</date> <authorinitials>ss</"
+"<revnumber>1.20</revnumber> <date>16
feb 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>programfixar, stöd för markdown, "
"stilförbättringar</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:137
+#: C/index.docbook:143
msgid ""
"<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
msgstr ""
-"<revnumber>1.19</revnumber> <date>05
Jun 2013</date> <authorinitials>ss</"
+"<revnumber>1.19</revnumber> <date>05
jun 2013</date> <authorinitials>ss</"
"authorinitials> <revremark>programfixar</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:143
+#: C/index.docbook:149
msgid ""
"<revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, speedups, markdown support</revremark>"
msgstr ""
-"<revnumber>1.18</revnumber> <date>14
Sep 2011</date> <authorinitials>ss</"
+"<revnumber>1.18</revnumber> <date>14
sep 2011</date> <authorinitials>ss</"
"authorinitials> <revremark>programfixar, uppsnabbningar, stöd för markdown</"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:149
+#: C/index.docbook:155
msgid ""
"<revnumber>1.17</revnumber> <date>26 Feb 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>urgent bug fix update</revremark>"
msgstr ""
-"<revnumber>1.17</revnumber> <date>26
Feb 2011</date> <authorinitials>sk</"
+"<revnumber>1.17</revnumber> <date>26
feb 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>brådskande programfixuppdatering</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:155
+#: C/index.docbook:161
msgid ""
"<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes, layout improvements</revremark>"
msgstr ""
-"<revnumber>1.16</revnumber> <date>14
Jan 2011</date> <authorinitials>sk</"
+"<revnumber>1.16</revnumber> <date>14
jan 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>programfixar, layoutförbättringar</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:161
+#: C/index.docbook:167
msgid ""
"<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bug and regression fixes</revremark>"
msgstr ""
-"<revnumber>1.15</revnumber> <date>21
Maj 2010</date> <authorinitials>sk</"
+"<revnumber>1.15</revnumber> <date>21
maj 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>program- och regressionsfixar</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:167
+#: C/index.docbook:173
msgid ""
"<revnumber>1.14</revnumber> <date>28 March 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes and performance improvements</revremark>"
msgstr ""
-"<revnumber>1.14</revnumber> <date>28
Mars 2010</date> <authorinitials>sk</"
+"<revnumber>1.14</revnumber> <date>28
mars 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>programfixar och prestandaförbättringar</"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:173
+#: C/index.docbook:179
msgid ""
"<revnumber>1.13</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>broken tarball update</"
"revremark>"
msgstr ""
-"<revnumber>1.13</revnumber> <date>18 December 2009</date> "
+"<revnumber>1.13</revnumber> <date>18 december 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>uppdatering på grund av "
"trasigt tar-arkiv</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:179
+#: C/index.docbook:185
msgid ""
"<revnumber>1.12</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>new tool features and "
"bugfixes</revremark>"
msgstr ""
-"<revnumber>1.12</revnumber> <date>18 December 2009</date> "
+"<revnumber>1.12</revnumber> <date>18 december 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>nya verktygsfunktioner och "
"programfixar</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:185
+#: C/index.docbook:191
msgid ""
"<revnumber>1.11</revnumber> <date>16 November 2008</date> "
"<authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</"
"revremark>"
msgstr ""
-"<revnumber>1.11</revnumber> <date>16 November 2008</date> "
+"<revnumber>1.11</revnumber> <date>16 november 2008</date> "
"<authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</"
"revremark>"
#. (itstool) path: chapter/title
-#: C/index.docbook:198
+#: C/index.docbook:204
msgid "Introduction"
msgstr "Introduktion"
#. (itstool) path: chapter/para
-#: C/index.docbook:200
+#: C/index.docbook:206
msgid ""
"This chapter introduces GTK-Doc and gives an overview of what it is and how "
"it is used."
"hur det används."
#. (itstool) path: sect1/title
-#: C/index.docbook:206
+#: C/index.docbook:212
msgid "What is GTK-Doc?"
msgstr "Vad är GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:208
+#: C/index.docbook:214
msgid ""
"GTK-Doc is used to document C code. It is typically used to document the "
"public API of libraries, such as the GTK+ and GNOME libraries. But it can "
"biblioteken. Men det kan också användas för att dokumentera programkod."
#. (itstool) path: sect1/title
-#: C/index.docbook:216
+#: C/index.docbook:222
msgid "How Does GTK-Doc Work?"
msgstr "Hur fungerar GTK-Doc?"
# sebras: how do I translate header files?
#. (itstool) path: sect1/para
-#: C/index.docbook:218
+#: C/index.docbook:224
msgid ""
"GTK-Doc works by using documentation of functions placed inside the source "
"files in specially-formatted comment blocks, or documentation added to the "
"huvudfiler; det kommer inte att producera utdata för statiska funktioner)."
#. (itstool) path: sect1/para
-#: C/index.docbook:225
+#: C/index.docbook:231
msgid ""
"GTK-Doc consists of a number of python scripts, each performing a different "
"step in the process."
"i processen."
#. (itstool) path: sect1/para
-#: C/index.docbook:230
+#: C/index.docbook:236
msgid "There are 5 main steps in the process:"
msgstr "Det finns 5 huvudsteg i processen:"
#. (itstool) path: listitem/para
-#: C/index.docbook:237
+#: C/index.docbook:243
msgid ""
"<guilabel>Writing the documentation.</guilabel> The author fills in the "
"source files with the documentation for each function, macro, union etc. (In "
# sebras: more header files...
#. (itstool) path: listitem/para
-#: C/index.docbook:247
+#: C/index.docbook:253
msgid ""
"<guilabel>Gathering information about the code.</guilabel> "
"<application>gtkdoc-scan</application> scans the header files of the code "
"module>-overrides.txt</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:264
+#: C/index.docbook:270
msgid ""
"<application>gtkdoc-scangobj</application> can also be used to dynamically "
"query a library about any GObject subclasses it exports. It saves "
"vilka GObject-egenskaper och signaler det tillhandahåller."
#. (itstool) path: listitem/para
-#: C/index.docbook:270
+#: C/index.docbook:276
msgid ""
"<application>gtkdoc-scanobj</application> should not be used anymore. It was "
"needed in the past when GObject was still GtkObject inside gtk+."
"behövdes tidigare när GObject fortfarande var GtkObject inuti gtk+."
#. (itstool) path: listitem/para
-#: C/index.docbook:277
+#: C/index.docbook:283
msgid ""
"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
"mkdb</application> turns the template files into XML files in the <filename "
"introspektionsdata."
#. (itstool) path: listitem/para
-#: C/index.docbook:286
+#: C/index.docbook:292
msgid ""
"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
"till ett PDF-dokument kallat <filename><package>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:292
+#: C/index.docbook:298
msgid ""
"Files in <filename class=\"directory\">xml/</filename> and <filename class="
"\"directory\">html/</filename> directories are always overwritten. One "
"aldrig redigera dem direkt."
#. (itstool) path: listitem/para
-#: C/index.docbook:300
+#: C/index.docbook:306
msgid ""
"<guilabel>Fixing up cross-references between documents.</guilabel> After "
"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
"(i de fall där dokumentationen finns installerad)."
#. (itstool) path: sect1/title
-#: C/index.docbook:318
+#: C/index.docbook:324
msgid "Getting GTK-Doc"
msgstr "Hämta GTK-Doc"
#. (itstool) path: sect2/title
-#: C/index.docbook:321
+#: C/index.docbook:327
msgid "Requirements"
msgstr "Krav"
#. (itstool) path: sect2/para
-#: C/index.docbook:322
+#: C/index.docbook:328
msgid ""
"<guilabel>python 2/3</guilabel> - the main scripts are written in python."
msgstr "<guilabel>python 2/3</guilabel> - huvudskripten är skrivna i python."
#. (itstool) path: sect2/para
-#: C/index.docbook:325
+#: C/index.docbook:331
msgid ""
"<guilabel>xsltproc</guilabel> - the xslt processor from libxslt <ulink url="
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
#. (itstool) path: sect2/para
-#: C/index.docbook:329
+#: C/index.docbook:335
msgid ""
"<guilabel>docbook-xsl</guilabel> - the docbook xsl stylesheets <ulink url="
"\"http://sourceforge.net/projects/docbook/files/docbook-xsl/\" type=\"http"
# sebras: remind me how was highlighting translated..?
#. (itstool) path: sect2/para
-#: C/index.docbook:333
+#: C/index.docbook:339
msgid ""
"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
"syntaxfärgning av exempel"
#. (itstool) path: sect1/title
-#: C/index.docbook:341
+#: C/index.docbook:347
msgid "About GTK-Doc"
msgstr "Om GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:343 C/index.docbook:357
+#: C/index.docbook:349 C/index.docbook:363
msgid "(FIXME)"
msgstr "(FIXME)"
#. (itstool) path: sect1/para
-#: C/index.docbook:347
+#: C/index.docbook:353
msgid ""
"(History, authors, web pages, mailing list, license, future plans, "
"comparison with other similar systems.)"
"jämförelse med andra liknande system.)"
#. (itstool) path: sect1/title
-#: C/index.docbook:355
+#: C/index.docbook:361
msgid "About this Manual"
msgstr "Om denna handbok"
#. (itstool) path: sect1/para
-#: C/index.docbook:361
+#: C/index.docbook:367
msgid "(who it is meant for, where you can get it, license)"
msgstr "(vem är den avsett för, var kan du få tag i den, licens)"
#. (itstool) path: chapter/title
-#: C/index.docbook:370
+#: C/index.docbook:376
msgid "Setting up your project"
msgstr "Att ställa in ditt projekt"
#. (itstool) path: chapter/para
-#: C/index.docbook:372
+#: C/index.docbook:378
msgid ""
"The next sections describe what steps to perform to integrate GTK-Doc into "
"your project. Theses sections assume we work on a project called 'meep'. "
"byggsystem."
#. (itstool) path: sect1/title
-#: C/index.docbook:383
+#: C/index.docbook:389
msgid "Setting up a skeleton documentation"
msgstr "Att ställa in en skelettstruktur för dokumentation"
#. (itstool) path: sect1/para
-#: C/index.docbook:385
+#: C/index.docbook:391
msgid ""
"Under your top-level project directory create folders called docs/reference "
"(this way you can also have docs/help for end-user documentation). It is "
"bibliotek är detta steg inte nödvändigt."
#. (itstool) path: example/title
-#: C/index.docbook:394
+#: C/index.docbook:400
msgid "Example directory structure"
msgstr "Exempel på katalogstruktur"
#. (itstool) path: example/programlisting
-#: C/index.docbook:395
+#: C/index.docbook:401
#, no-wrap
msgid ""
"\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:392
+#: C/index.docbook:398
msgid "This can then look as shown below: <_:example-1/>"
msgstr "Detta kan se ut enligt nedan: <_:example-1/>"
#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:410 C/index.docbook:417
+#: C/index.docbook:416 C/index.docbook:423
msgid "Integration with autoconf"
msgstr "Integrering med autoconf"
#. (itstool) path: sect1/para
-#: C/index.docbook:412
+#: C/index.docbook:418
msgid ""
"Very easy! Just add one line to your <filename>configure.ac</filename> "
"script."
"filename>-skript."
#. (itstool) path: example/programlisting
-#: C/index.docbook:418
+#: C/index.docbook:424
#, no-wrap
msgid ""
"\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
#. (itstool) path: example/title
-#: C/index.docbook:430
+#: C/index.docbook:436
msgid "Keep gtk-doc optional"
msgstr "Låt gtk-doc vara valfritt"
#. (itstool) path: example/programlisting
-#: C/index.docbook:431
+#: C/index.docbook:437
#, no-wrap
msgid ""
"\n"
"])\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:425
+#: C/index.docbook:431
msgid ""
"This will require all developers to have gtk-doc installed. If it is okay "
"for your project to have optional api-doc build setup, you can solve this as "
# sebras: <function> or <symbol>?
#. (itstool) path: sect1/para
-#: C/index.docbook:442
+#: C/index.docbook:448
msgid ""
"The first argument is used to check for the gtkdocversion at configure time. "
"The 2nd, optional argument is used by <application>gtkdocize</application>. "
"lägger också till flera configure-flaggor:"
#. (itstool) path: listitem/para
-#: C/index.docbook:448
+#: C/index.docbook:454
msgid "--with-html-dir=PATH : path to installed docs"
msgstr "--with-html-dir=SÖKVÄG : sökväg till installerad dokumentation"
#. (itstool) path: listitem/para
-#: C/index.docbook:449
+#: C/index.docbook:455
msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]"
msgstr ""
"--enable-gtk-doc : använd gtk-doc för att bygga dokumentation "
"[standardvärde=no]"
#. (itstool) path: listitem/para
-#: C/index.docbook:450
+#: C/index.docbook:456
msgid ""
"--enable-gtk-doc-html : build documentation in html format [default=yes]"
msgstr ""
"--enable-gtk-doc-html : bygg dokumentation i html-format [standardvärde=yes]"
#. (itstool) path: listitem/para
-#: C/index.docbook:451
+#: C/index.docbook:457
msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
msgstr ""
"--enable-gtk-doc-pdf : bygg dokumentation i pdf-format [standardvärde=no]"
#. (itstool) path: important/para
-#: C/index.docbook:455
+#: C/index.docbook:461
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"är rimligt för användare men inte för utvecklare)."
#. (itstool) path: sect1/para
-#: C/index.docbook:463
+#: C/index.docbook:469
msgid ""
"Furthermore it is recommended that you have the following line inside your "
"<filename>configure.ac</filename> script. This allows "
"till ditt projekt."
#. (itstool) path: example/title
-#: C/index.docbook:471
+#: C/index.docbook:477
msgid "Preparation for gtkdocize"
msgstr "Förberedelse för gtkdocize"
#. (itstool) path: example/programlisting
-#: C/index.docbook:472
+#: C/index.docbook:478
#, no-wrap
msgid ""
"\n"
"AC_CONFIG_MACRO_DIR(m4)\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:477
+#: C/index.docbook:483
msgid ""
"After all changes to <filename>configure.ac</filename> are made, update the "
"<filename>configure</filename> file. This can be done by re-running "
"köra om <code>autoreconf -i</code> eller <code>autogen.sh</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:485
+#: C/index.docbook:491
msgid "Integration with automake"
msgstr "Integrering med automake"
#. (itstool) path: sect1/para
-#: C/index.docbook:487
+#: C/index.docbook:493
msgid ""
"First copy the <filename>Makefile.am</filename> from the <filename class="
"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
"och ett."
#. (itstool) path: sect1/para
-#: C/index.docbook:498
+#: C/index.docbook:504
msgid ""
"The next step is to edit the settings inside the <filename>Makefile.am</"
"filename>. All the settings have a comment above that describes their "
"att lista de parametrar som stöds."
#. (itstool) path: sect1/title
-#: C/index.docbook:512
+#: C/index.docbook:518
msgid "Integration with autogen"
msgstr "Integrering med autogen"
#. (itstool) path: sect1/para
-#: C/index.docbook:514
+#: C/index.docbook:520
msgid ""
"Most projects will have an <filename>autogen.sh</filename> script to setup "
"the build infrastructure after a checkout from version control system (such "
"ett sådant skript. Det bör köras före autoheader, automake eller autoconf."
#. (itstool) path: example/title
-#: C/index.docbook:523
+#: C/index.docbook:529
msgid "Running gtkdocize from autogen.sh"
msgstr "Köra gtkdocize från autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:524
+#: C/index.docbook:530
#, no-wrap
msgid ""
"\n"
"gtkdocize || exit 1\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:530
+#: C/index.docbook:536
msgid ""
"When running <application>gtkdocize</application> it copies <filename>gtk-"
"doc.make</filename> to your project root (or any directory specified by the "
# sebras: e.g. because of,... it can be...any files in tmpl...and is migrating...<symbol> or <function>? gtkdoc or GTK-Doc
#. (itstool) path: sect1/para
-#: C/index.docbook:539
+#: C/index.docbook:545
msgid ""
"Historically GTK-Doc was generating template files where developers entered "
"the docs. This turned out to be not so good (e.g. the need for having "
#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:556 C/index.docbook:573
+#: C/index.docbook:562 C/index.docbook:579
msgid "Running the doc build"
msgstr "Att köra dokumentationsbygget"
#. (itstool) path: sect1/para
-#: C/index.docbook:558
+#: C/index.docbook:564
msgid ""
"After the previous steps it's time to run the build. First we need to rerun "
"<filename>autogen.sh</filename>. If this script runs configure for you, then "
"<filename>configure</filename> med denna flagga efteråt."
#. (itstool) path: sect1/para
-#: C/index.docbook:565
+#: C/index.docbook:571
msgid ""
"The first make run generates several additional files in the doc-"
"directories. The important ones are: <filename><package>.types</"
"sections.txt</filename>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:574
+#: C/index.docbook:580
#, no-wrap
msgid ""
"\n"
"make\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:580
+#: C/index.docbook:586
msgid ""
"Now you can point your browser to <filename>docs/reference/<package>/"
"index.html</filename>. Yes, it's a bit disappointing still. But hang-on, "
"nästa kapitel kommer vi att berätta för dig hur du fyller sidorna med liv."
#. (itstool) path: sect1/title
-#: C/index.docbook:588
+#: C/index.docbook:594
msgid "Integration with version control systems"
msgstr "Integrering med versionshanteringssystem"
#. (itstool) path: sect1/para
-#: C/index.docbook:590
+#: C/index.docbook:596
msgid ""
"As a rule of thumb, it's the files you edit which should go under version "
"control. For typical projects it's these files: <filename><package>."
"filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:598
+#: C/index.docbook:604
msgid ""
"Files in the <filename>xml/</filename> and <filename>html/</filename> "
"directories should not go under version control. Neither should any of the "
"filerna."
#. (itstool) path: sect1/title
-#: C/index.docbook:606
+#: C/index.docbook:612
msgid "Integration with plain makefiles or other build systems"
msgstr "Integrering med vanliga makefiler eller andra byggsystem"
#. (itstool) path: sect1/para
-#: C/index.docbook:608
+#: C/index.docbook:614
msgid ""
"In the case one does not want to use automake and therefore <filename>gtk-"
"doc.mak</filename> one will need to call the gtkdoc tools in the right order "
"verktygen i rätt ordning i sina egna makefiler (eller andra byggverktyg)."
#. (itstool) path: example/title
-#: C/index.docbook:615
+#: C/index.docbook:621
msgid "Documentation build steps"
msgstr "Byggsteg för dokumentation"
#. (itstool) path: example/programlisting
-#: C/index.docbook:616
+#: C/index.docbook:622
#, no-wrap
msgid ""
"\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:630
+#: C/index.docbook:636
msgid ""
"One will need to look at the <filename>Makefile.am</filename> and "
"<filename>gtk-doc.mak</filename> to pick the extra options needed."
"behövs."
#. (itstool) path: sect1/title
-#: C/index.docbook:637
+#: C/index.docbook:643
msgid "Integration with CMake build systems"
msgstr "Integrering med CMake-byggsystem"
#. (itstool) path: sect1/para
-#: C/index.docbook:639
+#: C/index.docbook:645
msgid ""
"GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module (and "
"the corresponding <filename>GtkDocConfigVersion.cmake</filename> module). "
"kommando som du kan ställa in i din <filename>CMakeLists.txt</filename>-fil."
#. (itstool) path: example/title
-#: C/index.docbook:649
+#: C/index.docbook:655
msgid "Example of using GTK-Doc from CMake"
msgstr "Exempel på användning av GTK-Doc från CMake"
#. (itstool) path: example/programlisting
-#: C/index.docbook:650
+#: C/index.docbook:656
#, no-wrap
msgid ""
"\n"
" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:647
+#: C/index.docbook:653
msgid "The following example shows how to use this command. <_:example-1/>"
msgstr ""
"Det följande exemplet visar hur du använder detta kommando. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:675
+#: C/index.docbook:681
msgid "Documenting the code"
msgstr "Att dokumentera koden"
#. (itstool) path: chapter/para
-#: C/index.docbook:677
+#: C/index.docbook:683
msgid ""
"GTK-Doc uses source code comment with a special syntax for code "
"documentation. Further it retrieves information about your project structure "
"syntaxen i kommentarerna."
#. (itstool) path: note/title
-#: C/index.docbook:685
+#: C/index.docbook:691
msgid "Documentation placement"
msgstr "Dokumentationsplacering"
#. (itstool) path: note/para
-#: C/index.docbook:686
+#: C/index.docbook:692
msgid ""
"In the past most documentation had to be filled into files residing inside "
"the <filename>tmpl</filename> directory. This has the disadvantages that the "
"konflikter med versionshanteringssystem."
#. (itstool) path: note/para
-#: C/index.docbook:692
+#: C/index.docbook:698
msgid ""
"The avoid the aforementioned problems we suggest putting the documentation "
"inside the sources. This manual will only describe this way of documenting "
"dokumentera kod."
#. (itstool) path: example/title
-#: C/index.docbook:703 C/index.docbook:729
+#: C/index.docbook:709 C/index.docbook:735
msgid "GTK-Doc comment block"
msgstr "GTK-Doc-kommentarsblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:704
+#: C/index.docbook:710
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:699
+#: C/index.docbook:705
msgid ""
"The scanner can handle the majority of C headers fine. In the case of "
"receiving warnings from the scanner that look like a special case, one can "
"Doc att hoppa över dem. <_:example-1/>"
#. (itstool) path: note/title
-#: C/index.docbook:713
+#: C/index.docbook:719
msgid "Limitations"
msgstr "Begränsningar"
# sebras: no 's in the original
#. (itstool) path: note/para
-#: C/index.docbook:714
+#: C/index.docbook:720
msgid ""
"Note, that GTK-Doc's supports <code>#ifndef(__GTK_DOC_IGNORE__)</code> but "
"not <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations."
"inte <code>#if !defined(__GTK_DOC_IGNORE__)</code> eller andra kombinationer."
#. (itstool) path: sect1/title
-#: C/index.docbook:724
+#: C/index.docbook:730
msgid "Documentation comments"
msgstr "Dokumentationskommentarer"
#. (itstool) path: example/programlisting
-#: C/index.docbook:730
+#: C/index.docbook:736
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:726
+#: C/index.docbook:732
msgid ""
"A multiline comment that starts with an additional '*' marks a documentation "
"block that will be processed by the GTK-Doc tools. <_:example-1/>"
"example-1/>"
#. (itstool) path: sect1/para
-#: C/index.docbook:739
+#: C/index.docbook:745
msgid ""
"The 'identifier' is one line with the name of the item the comment is "
"related to. The syntax differs a little depending on the item. (TODO add "
"till tabell som visar identifierare)"
#. (itstool) path: sect1/para
-#: C/index.docbook:745
+#: C/index.docbook:751
msgid ""
"The 'documentation' block is also different for each symbol type. Symbol "
"types that get parameters such as functions or macros have the parameter "
"användbart i förformaterad text (kodlistningar)."
#. (itstool) path: listitem/para
-#: C/index.docbook:762
+#: C/index.docbook:768
msgid ""
"What it is: The name for a class or function can sometimes be misleading for "
"people coming from a different background."
"vilseledande för personer med annan bakgrund."
#. (itstool) path: listitem/para
-#: C/index.docbook:768
+#: C/index.docbook:774
msgid ""
"What it does: Tell about common uses. Put it in relation with the other API."
msgstr ""
"det andra API:t."
#. (itstool) path: tip/para
-#: C/index.docbook:758
+#: C/index.docbook:764
msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>"
msgstr "När du dokumenterar kod, beskriv två aspekter: <_:itemizedlist-1/>"
#. (itstool) path: listitem/para
-#: C/index.docbook:783
+#: C/index.docbook:789
msgid "Use function() to refer to functions or macros which take arguments."
msgstr ""
"Använd funktion() för att referera till funktioner eller makron som tar "
"argument."
#. (itstool) path: listitem/para
-#: C/index.docbook:788
+#: C/index.docbook:794
msgid ""
"Use @param to refer to parameters. Also use this when referring to "
"parameters of other functions, related to the one being described."
"beskrivs."
#. (itstool) path: listitem/para
-#: C/index.docbook:794
+#: C/index.docbook:800
msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS."
msgstr ""
"Använd %konstant för att referera till en konstant, t.ex. %G_TRAVERSE_LEAFS."
#. (itstool) path: listitem/para
-#: C/index.docbook:799
+#: C/index.docbook:805
msgid ""
"Use #symbol to refer to other types of symbol, e.g. structs and enums and "
"macros which don't take arguments."
"strukturer eller uppräkningar och makron som inte tar argument."
#. (itstool) path: listitem/para
-#: C/index.docbook:805
+#: C/index.docbook:811
msgid "Use #Object::signal to refer to a GObject signal."
msgstr "Använd #Objekt::signal för att referera till en GObject-signal."
#. (itstool) path: listitem/para
-#: C/index.docbook:810
+#: C/index.docbook:816
msgid "Use #Object:property to refer to a GObject property."
msgstr "Använd #Objekt:egenskap för att referera till en GObject-egenskap."
#. (itstool) path: listitem/para
-#: C/index.docbook:815
+#: C/index.docbook:821
msgid ""
"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
"foo_bar() to refer to a vmethod."
"#GObjectKlass.foo_bar() för att referera till en virtuell metod."
#. (itstool) path: sect1/para
-#: C/index.docbook:777
+#: C/index.docbook:783
msgid ""
"One advantage of hyper-text over plain-text is the ability to have links in "
"the document. Writing the correct markup for a link can be tedious though. "
"förkortningar. <_:itemizedlist-1/>"
#. (itstool) path: tip/para
-#: C/index.docbook:824
+#: C/index.docbook:830
msgid ""
"If you need to use the special characters '<', '>', '()', '@', '%', or "
"'#' in your documentation without GTK-Doc changing them you can use the XML "
"kontrollsekvensen ”\\”."
#. (itstool) path: sect1/para
-#: C/index.docbook:833
+#: C/index.docbook:839
msgid ""
"DocBook can do more than just links. One can also have lists, examples, "
"headings, and images. As of version 1.20, the preferred way is to use a "
"ett bindestreck."
#. (itstool) path: sect1/para
-#: C/index.docbook:844
+#: C/index.docbook:850
msgid ""
"While markdown is now preferred one can mix both. One limitation here is "
"that one can use docbook xml within markdown, but markdown within docbook "
"inte."
#. (itstool) path: sect1/para
-#: C/index.docbook:850
+#: C/index.docbook:856
msgid ""
"In older GTK-Doc releases, if you need support for additional formatting, "
"you would need to enable the usage of docbook XML tags inside doc-comments "
# sebras: markdown or Markdown?
#. (itstool) path: example/title
-#: C/index.docbook:859
+#: C/index.docbook:865
msgid "GTK-Doc comment block using Markdown"
msgstr "GTK-Doc-kommentarsblock som använder Markdown"
#. (itstool) path: example/programlisting
-#: C/index.docbook:860
+#: C/index.docbook:866
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:899
+#: C/index.docbook:905
msgid ""
"More examples of what markdown tags are supported can be found in the <ulink "
"url=\"https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown"
"\">Referensen för GTK+-dokumentationens markdown-syntax</ulink>."
#. (itstool) path: tip/para
-#: C/index.docbook:905
+#: C/index.docbook:911
msgid ""
"As already mentioned earlier GTK-Doc is for documenting public API. Thus one "
"cannot write documentation for static symbols. Nevertheless it is good to "
"ställe i avsnittsfilen."
#. (itstool) path: sect1/title
-#: C/index.docbook:919
+#: C/index.docbook:925
msgid "Documenting sections"
msgstr "Dokumentationsavsnitt"
#. (itstool) path: sect1/para
-#: C/index.docbook:921
+#: C/index.docbook:927
msgid ""
"Each section of the documentation contains information about one class or "
"module. To introduce the component one can write a section block. The short "
"valfria."
#. (itstool) path: example/title
-#: C/index.docbook:929
+#: C/index.docbook:935
msgid "Section comment block"
msgstr "Kommentarsblock för avsnitt"
#. (itstool) path: example/programlisting
-#: C/index.docbook:930
+#: C/index.docbook:936
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:949
+#: C/index.docbook:955
msgid "SECTION:<name>"
msgstr "SECTION:<namn>"
#. (itstool) path: listitem/para
-#: C/index.docbook:951
+#: C/index.docbook:957
msgid ""
"The name links the section documentation to the respective part in the "
"<filename><package>-sections.txt</filename> file. The name given here "
"filename>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:960
+#: C/index.docbook:966
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:962
+#: C/index.docbook:968
msgid ""
"A one line description of the section, that later will appear after the "
"links in the TOC and at the top of the section page."
"innehållsförteckningen och lägst upp på avsnittssidan."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:969
+#: C/index.docbook:975
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:971
+#: C/index.docbook:977
msgid ""
"The section title defaults to <name> from the SECTION declaration. It "
"can be overridden with the @title field."
"kan åsidosättas med fältet @title."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:978
+#: C/index.docbook:984
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:980
+#: C/index.docbook:986
msgid ""
"Overrides the use of title as a section identifier. For GObjects the <"
"title> is used as a section_id and for other sections it is <"
"MODULE>-<title>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:988
+#: C/index.docbook:994
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:990
+#: C/index.docbook:996
msgid "A list of symbols that are related to this section."
msgstr "En lista över symboler som är relaterade till detta avsnitt."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:996
+#: C/index.docbook:1002
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1003
+#: C/index.docbook:1009
msgid ""
"Stable - The intention of a Stable interface is to enable arbitrary third "
"parties to develop applications to these interfaces, release them, and have "
"motiverade."
#. (itstool) path: listitem/para
-#: C/index.docbook:1015
+#: C/index.docbook:1021
msgid ""
"Unstable - Unstable interfaces are experimental or transitional. They are "
"typically used to give outside developers early access to new or rapidly "
"programfixversion till nästa."
#. (itstool) path: listitem/para
-#: C/index.docbook:1027
+#: C/index.docbook:1033
msgid ""
"Private - An interface that can be used within the GNOME stack itself, but "
"that is not documented for end-users. Such functions should only be used in "
"på angivna och dokumenterade sätt."
#. (itstool) path: listitem/para
-#: C/index.docbook:1036
+#: C/index.docbook:1042
msgid ""
"Internal - An interface that is internal to a module and does not require "
"end-user documentation. Functions that are undocumented are assumed to be "
"interna."
#. (itstool) path: listitem/para
-#: C/index.docbook:998
+#: C/index.docbook:1004
msgid ""
"An informal description of the stability level this API has. We recommend "
"the use of one of these terms: <_:itemizedlist-1/>"
"att använda en av dessa termer: <_:itemizedlist-1/>"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1048
+#: C/index.docbook:1054
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1050
+#: C/index.docbook:1056
msgid ""
"The <literal>#include</literal> files to show in the section synopsis (a "
"comma separated list), overriding the global value from the <link linkend="
"Detta objekt är valfritt."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1059
+#: C/index.docbook:1065
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1061
+#: C/index.docbook:1067
msgid ""
"The image to display at the top of the reference page for this section. This "
"will often be some sort of a diagram to illustrate the visual appearance of "
"klasser. Detta objekt är valfritt."
#. (itstool) path: tip/para
-#: C/index.docbook:1072
+#: C/index.docbook:1078
msgid ""
"To avoid unnecessary recompilation after doc-changes put the section docs "
"into the c-source where possible."
"avsnittsdokumentationen i c-källkoden där möjligt."
#. (itstool) path: sect1/title
-#: C/index.docbook:1081
+#: C/index.docbook:1087
msgid "Documenting symbols"
msgstr "Dokumentationssymboler"
#. (itstool) path: sect1/para
-#: C/index.docbook:1083
+#: C/index.docbook:1089
msgid ""
"Each symbol (function, macro, struct, enum, signal and property) is "
"documented in a separate block. The block is best placed close to the "
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1091 C/index.docbook:1157
+#: C/index.docbook:1097 C/index.docbook:1163
msgid "General tags"
msgstr "Generella taggar"
#. (itstool) path: sect2/para
-#: C/index.docbook:1093
+#: C/index.docbook:1099
msgid ""
"You can add versioning information to all documentation elements to tell "
"when an API was introduced, or when it was deprecated."
"att berätta när ett API introducerats eller blev föråldrat."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1098
+#: C/index.docbook:1104
msgid "Versioning Tags"
msgstr "Versioneringstaggar"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1099
+#: C/index.docbook:1105
msgid "Since:"
msgstr "Since:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1101
+#: C/index.docbook:1107
msgid "Description since which version of the code the API is available."
msgstr ""
"Beskrivning över från och med vilken version av koden som API:t är "
"tillgängligt."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1106
+#: C/index.docbook:1112
msgid "Deprecated:"
msgstr "Deprecated:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1108
+#: C/index.docbook:1114
msgid ""
"Paragraph denoting that this function should no be used anymore. The "
"description should point the reader to the new API."
"Beskrivningen bör peka läsaren vidare till det nya API:t."
#. (itstool) path: sect2/para
-#: C/index.docbook:1116
+#: C/index.docbook:1122
msgid ""
"You can also add stability information to all documentation elements to "
"indicate whether API stability is guaranteed for them for all future minor "
"för dem för alla framtida programfix-versioner av projektet."
#. (itstool) path: sect2/para
-#: C/index.docbook:1122
+#: C/index.docbook:1128
msgid ""
"The default stability level for all documentation elements can be set by "
"passing the <option>--default-stability</option> argument to "
"till <application>gtkdoc-mkdb</application> med endera av värdena nedan."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1128
+#: C/index.docbook:1134
msgid "Stability Tags"
msgstr "Stabilitetstaggar"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1129
+#: C/index.docbook:1135
msgid "Stability: Stable"
msgstr "Stability: Stable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1131
+#: C/index.docbook:1137
msgid ""
"Mark the element as stable. This is for public APIs which are guaranteed to "
"remain stable for all future minor releases of the project."
"projektet."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1138
+#: C/index.docbook:1144
msgid "Stability: Unstable"
msgstr "Stability: Unstable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1140
+#: C/index.docbook:1146
msgid ""
"Mark the element as unstable. This is for public APIs which are released as "
"a preview before being stabilised."
"på förhand innan de blivit stabiliserade."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1146
+#: C/index.docbook:1152
msgid "Stability: Private"
msgstr "Stability: Private"
#. (itstool) path: listitem/para
-#: C/index.docbook:1148
+#: C/index.docbook:1154
msgid ""
"Mark the element as private. This is for interfaces which can be used by "
"tightly coupled modules, but not by arbitrary third parties."
"av tätt sammankopplade moduler, men inte av godtyckliga tredje parter."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1158
+#: C/index.docbook:1164
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1178 C/index.docbook:1188
+#: C/index.docbook:1184 C/index.docbook:1194
msgid "Annotations"
msgstr "Noteringar"
# sebras: was it called verkygstips? verktygshjälp? I forget...
#. (itstool) path: sect2/para
-#: C/index.docbook:1180
+#: C/index.docbook:1186
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"GObjectIntrospection/Annotations\" type=\"http\">wikisidan</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1189
+#: C/index.docbook:1195
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1210 C/index.docbook:1239
+#: C/index.docbook:1216 C/index.docbook:1245
msgid "Function comment block"
msgstr "Kommentarsblock för funktioner"
#. (itstool) path: listitem/para
-#: C/index.docbook:1216
+#: C/index.docbook:1222
msgid ""
"Document whether returned objects, lists, strings, etc, should be freed/"
"unrefed/released."
"avrefereras/släppas."
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1228
msgid "Document whether parameters can be NULL, and what happens if they are."
msgstr ""
"Dokumentera huruvida parametrar tillåts vara NULL och vad som händer om de "
"är NULL."
#. (itstool) path: listitem/para
-#: C/index.docbook:1227
+#: C/index.docbook:1233
msgid ""
"Mention interesting pre-conditions and post-conditions where appropriate."
msgstr "Nämn intressanta förvillkor och eftervillkor där lämpligt."
#. (itstool) path: sect2/para
-#: C/index.docbook:1212 C/index.docbook:1298
+#: C/index.docbook:1218 C/index.docbook:1304
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Kom ihåg att: <_:itemizedlist-1/>"
# sebras: Gtk-doc? GTK-Doc? gtk-doc? macros and functions?
#. (itstool) path: sect2/para
-#: C/index.docbook:1234
+#: C/index.docbook:1240
msgid ""
"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
"private. They are treated like static functions."
# sebras: how to translate highlight?
#. (itstool) path: example/programlisting
-#: C/index.docbook:1240
+#: C/index.docbook:1246
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1261
+#: C/index.docbook:1267
msgid "Function tags"
msgstr "Funktions-taggar"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1262 C/index.docbook:1469
+#: C/index.docbook:1268 C/index.docbook:1475
msgid "Returns:"
msgstr "Returns:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1264
+#: C/index.docbook:1270
msgid "Paragraph describing the returned result."
msgstr "Stycke som beskriver det returnerade resultatet."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1269
+#: C/index.docbook:1275
msgid "@...:"
msgstr "@...:"
# sebras: variadic?
#. (itstool) path: listitem/para
-#: C/index.docbook:1271
+#: C/index.docbook:1277
msgid ""
"In case the function has variadic arguments, you should use this tag "
"(@Varargs: does also work for historic reasons)."
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1281 C/index.docbook:1283
+#: C/index.docbook:1287 C/index.docbook:1289
msgid "Property comment block"
msgstr "Kommentarsblock för egenskaper"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1284
+#: C/index.docbook:1290
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1296 C/index.docbook:1315
+#: C/index.docbook:1302 C/index.docbook:1321
msgid "Signal comment block"
msgstr "Kommentarsblock för signaler"
#. (itstool) path: listitem/para
-#: C/index.docbook:1302
+#: C/index.docbook:1308
msgid ""
"Document when the signal is emitted and whether it is emitted before or "
"after other signals."
"efter andra signaler."
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1314
msgid "Document what an application might do in the signal handler."
msgstr "Dokumentera vad ett program kan göra i signalhanteraren."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1316
+#: C/index.docbook:1322
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1333 C/index.docbook:1334
+#: C/index.docbook:1339 C/index.docbook:1340
msgid "Struct comment block"
msgstr "Kommentarsblock för strukturer"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1335
+#: C/index.docbook:1341
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1350
+#: C/index.docbook:1356
msgid ""
"Use <code>/*< private >*/</code> before the private struct fields you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"beteendet."
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1362
msgid ""
"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" "
"it will be considered private automatically and doesn't need to be mentioned "
"kommentarsblocket."
#. (itstool) path: sect2/para
-#: C/index.docbook:1362
+#: C/index.docbook:1368
msgid ""
"Struct comment blocks can also be used for GObjects and GObjectClasses. It "
"is usually a good idea to add a comment block for a class, if it has "
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1374 C/index.docbook:1375
+#: C/index.docbook:1380 C/index.docbook:1381
msgid "Enum comment block"
msgstr "Kommentarsblock för uppräkningar"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1376
+#: C/index.docbook:1382
#, no-wrap
msgid ""
"\n"
"} Something;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1393
+#: C/index.docbook:1399
msgid ""
"Use <code>/*< private >*/</code> before the private enum values you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"beteendet."
#. (itstool) path: sect1/title
-#: C/index.docbook:1404
+#: C/index.docbook:1410
msgid "Inline program documentation"
msgstr "Infogad programdokumentation"
# sebras: how to translate inline?
#. (itstool) path: sect1/para
-#: C/index.docbook:1405
+#: C/index.docbook:1411
msgid ""
"You can document programs and their commandline interface using inline "
"documentation."
"dokumentation."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1411
+#: C/index.docbook:1417
msgid "Tags"
msgstr "Taggar"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1413
+#: C/index.docbook:1419
msgid "PROGRAM"
msgstr "PROGRAM"
#. (itstool) path: listitem/para
-#: C/index.docbook:1416
+#: C/index.docbook:1422
msgid "Defines the start of a program documentation."
msgstr "Definierar början av programdokumentationen."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1423
+#: C/index.docbook:1429
msgid "@short_description:"
msgstr "@short_description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1425
+#: C/index.docbook:1431
msgid "Defines a short description of the program. (Optional)"
msgstr "Definierar en kort beskrivning av programmet. (Valfritt)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1432
+#: C/index.docbook:1438
msgid "@synopsis:"
msgstr "@synopsis:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1434
+#: C/index.docbook:1440
msgid ""
"Defines the arguments, or list of arguments that the program can take. "
"(Optional)"
"(Valfritt)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1442
+#: C/index.docbook:1448
msgid "@see_also:"
msgstr "@see_also:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1444
+#: C/index.docbook:1450
msgid "See Also manual page section. (Optional)"
msgstr "Se vidare i manualavsnitt. (Valfritt)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1451
+#: C/index.docbook:1457
msgid "@arg:"
msgstr "@arg:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1453
+#: C/index.docbook:1459
msgid "Argument(s) passed to the program and their description. (Optional)"
msgstr ""
"Argument som skickas vidare till programmet och deras beskrivningar. "
"(Valfritt)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1460
+#: C/index.docbook:1466
msgid "Description:"
msgstr "Beskrivning:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1462
+#: C/index.docbook:1468
msgid "A longer description of the program."
msgstr "En längre beskrivning av programmet."
#. (itstool) path: listitem/para
-#: C/index.docbook:1471
+#: C/index.docbook:1477
msgid "Specificy what value(s) the program returns. (Optional)"
msgstr "Ange vilka värden programmet returnerar. (Valfritt)"
#. (itstool) path: sect2/title
-#: C/index.docbook:1480
+#: C/index.docbook:1486
msgid "Example of program documentation."
msgstr "Exempel på programdokumentation."
#. (itstool) path: example/title
-#: C/index.docbook:1481
+#: C/index.docbook:1487
msgid "Program documentation block"
msgstr "Dokumentationsblock för program"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1482
+#: C/index.docbook:1488
#, no-wrap
msgid ""
"\n"
"}\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1508
+#: C/index.docbook:1514
msgid "Useful DocBook tags"
msgstr "Användbara DocBook-taggar"
#. (itstool) path: sect1/para
-#: C/index.docbook:1510
+#: C/index.docbook:1516
msgid ""
"Here are some DocBook tags which are most useful when documenting the code."
msgstr ""
"Här är några DocBook-taggar som är användbara när man dokumenterar koden."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1519
+#: C/index.docbook:1525
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Hashtabeller</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1515
+#: C/index.docbook:1521
msgid ""
"To link to another section in the GTK docs: <_:informalexample-1/> The "
"linkend is the SGML/XML id on the top item of the page you want to link to. "
"konverteras till ”-” för att överensstämma med SGML/XML."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1532
+#: C/index.docbook:1538
#, no-wrap
msgid ""
"\n"
"<function>…</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1529
+#: C/index.docbook:1535
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
"informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1541
+#: C/index.docbook:1547
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1552
+#: C/index.docbook:1558
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1538
+#: C/index.docbook:1544
msgid ""
"To include example code: <_:informalexample-1/> or possibly this, for very "
"short code fragments which don't need a title: <_:informalexample-2/> For "
"förkortningen: |[ … ]|"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1571
+#: C/index.docbook:1577
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1568
+#: C/index.docbook:1574
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "För att inkludera punktlistor: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1591
+#: C/index.docbook:1597
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1588
+#: C/index.docbook:1594
msgid ""
"To include a note which stands out from the text: <_:informalexample-1/>"
msgstr ""
"För att inkludera en not som skiljer sig från texten: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1604
+#: C/index.docbook:1610
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1601
+#: C/index.docbook:1607
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "För att refera till en typ: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1613
+#: C/index.docbook:1619
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1610
+#: C/index.docbook:1616
msgid ""
"To refer to an external structure (not one described in the GTK docs): <_:"
"informalexample-1/>"
"dokumentationen): <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1622
+#: C/index.docbook:1628
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1619
+#: C/index.docbook:1625
msgid "To refer to a field of a structure: <_:informalexample-1/>"
msgstr "För att referera till ett fält för en struktur: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1631
+#: C/index.docbook:1637
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1628
+#: C/index.docbook:1634
msgid ""
"To refer to a class name, we could possibly use: <_:informalexample-1/> but "
"you'll probably be using #GtkWidget instead (to automatically create a link "
"\"documenting_syntax\">förkortningarna</link>)."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1642
+#: C/index.docbook:1648
#, no-wrap
msgid ""
"\n"
"<emphasis>Detta är viktigt</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1639
+#: C/index.docbook:1645
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "För att betona text: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1651
+#: C/index.docbook:1657
#, no-wrap
msgid ""
"\n"
"<filename>/home/användare/dokument</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1648
+#: C/index.docbook:1654
msgid "For filenames use: <_:informalexample-1/>"
msgstr "För filnamn använd: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1660
+#: C/index.docbook:1666
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1657
+#: C/index.docbook:1663
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "För att referera till tangenter använd: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1670
+#: C/index.docbook:1676
msgid "Filling the extra files"
msgstr "Fylla i de extra filerna"
#. (itstool) path: chapter/para
-#: C/index.docbook:1672
+#: C/index.docbook:1678
msgid ""
"There are a couple of extra files, that need to be maintained along with the "
"inline source code comments: <filename><package>.types</filename>, "
"paket>-sections.txt</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1681
+#: C/index.docbook:1687
msgid "Editing the types file"
msgstr "Redigera typfilen"
#. (itstool) path: sect1/para
-#: C/index.docbook:1683
+#: C/index.docbook:1689
msgid ""
"If your library or application includes GObjects, you want their signals, "
"arguments/parameters and position in the hierarchy to be shown in the "
"package>.types</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:1692
+#: C/index.docbook:1698
msgid "Example types file snippet"
msgstr "Exempel på typfilsnutt"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1693
+#: C/index.docbook:1699
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1704
+#: C/index.docbook:1710
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"du inte distribuera typfilen eller versionshantera den."
#. (itstool) path: sect1/title
-#: C/index.docbook:1713
+#: C/index.docbook:1719
msgid "Editing the master document"
msgstr "Redigera huvuddokumentet"
#. (itstool) path: sect1/para
-#: C/index.docbook:1715
+#: C/index.docbook:1721
msgid ""
"GTK-Doc produces documentation in DocBook SGML/XML. When processing the "
"inline source comments, the GTK-Doc tools generate one documentation page "
# sebras: Its -> it's
#. (itstool) path: sect1/para
-#: C/index.docbook:1722
+#: C/index.docbook:1728
msgid ""
"While GTK-Doc creates a template master document for you, later runs will "
"not touch it again. This means that one can freely structure the "
# sebras: for -> from Apart -> together/embedded...
#. (itstool) path: tip/para
-#: C/index.docbook:1732
+#: C/index.docbook:1738
msgid ""
"Do not create tutorials as extra documents. Just write extra chapters. The "
"benefit of directly embedding the tutorial for your library into the API "
"blir uppdaterad tillsammans med biblioteket."
#. (itstool) path: sect1/para
-#: C/index.docbook:1741
+#: C/index.docbook:1747
msgid ""
"So what are the things to change inside the master document? For a start is "
"only a little. There are some placeholders (text in square brackets) there "
"Det finns en del platshållare (text i hakparenteser) som du bör ta hand om."
#. (itstool) path: example/title
-#: C/index.docbook:1748
+#: C/index.docbook:1754
msgid "Master document header"
msgstr "Huvuddokumentets huvud"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1749
+#: C/index.docbook:1755
#, no-wrap
msgid ""
"\n"
" <title>[Infoga titel här]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1765
+#: C/index.docbook:1771
msgid ""
"In addition a few option elements are created in commented form. You can "
"review these and enable them as you like."
"Du kan granska dessa och aktivera dem enligt dina egna önskemål."
#. (itstool) path: example/title
-#: C/index.docbook:1771
+#: C/index.docbook:1777
msgid "Optional part in the master document"
msgstr "Valfri del i huvuddokumentet"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1772
+#: C/index.docbook:1778
#, no-wrap
msgid ""
"\n"
" -->\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1780
+#: C/index.docbook:1786
msgid ""
"Finally you need to add new section whenever you introduce one. The <link "
"linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> tool will remind "
"infogats i dokumentationen."
#. (itstool) path: example/title
-#: C/index.docbook:1788 C/index.docbook:1823
+#: C/index.docbook:1794 C/index.docbook:1829
msgid "Including generated sections"
msgstr "Inkludera genererade avsnitt"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1789
+#: C/index.docbook:1795
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1801
+#: C/index.docbook:1807
msgid "Editing the section file"
msgstr "Redigera avsnittsfilen"
#. (itstool) path: sect1/para
-#: C/index.docbook:1803
+#: C/index.docbook:1809
msgid ""
"The section file is used to organise the documentation output by GTK-Doc. "
"Here one specifies which symbol belongs to which module or class and control "
"styra synligheten (publik eller privat)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1809
+#: C/index.docbook:1815
msgid ""
"The section file is a plain text file with tags delimiting sections. Blank "
"lines are ignored and lines starting with a '#' are treated as comment lines."
"kommentarsrader."
#. (itstool) path: note/para
-#: C/index.docbook:1816
+#: C/index.docbook:1822
msgid ""
"While the tags make the file look like xml, it is not. Please do not close "
"tags like <SUBSECTION>."
"taggar så som <SUBSECTION>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1824
+#: C/index.docbook:1830
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1841
+#: C/index.docbook:1847
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"klassnamnet för GObjectet konverterat till gemener)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1853
+#: C/index.docbook:1859
msgid ""
"The <TITLE> ... </TITLE> tag is used to specify the title of the "
"section. It is only useful before the templates (if used) are initially "
"Vidare är detta föråldrat om man använder SECTIONS-kommentarer i källkoden."
#. (itstool) path: sect1/para
-#: C/index.docbook:1860
+#: C/index.docbook:1866
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"beror på om de har publika poster (variabler, virtuella metoder)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1879
+#: C/index.docbook:1885
msgid ""
"You can also use <INCLUDE> ... </INCLUDE> to specify the "
"#include files which are shown in the synopsis sections. It contains a comma-"
"påverka det avsnittet."
#. (itstool) path: chapter/title
-#: C/index.docbook:1893
+#: C/index.docbook:1899
msgid "Controlling the result"
msgstr "Kontrollera resultatet"
#. (itstool) path: chapter/para
-#: C/index.docbook:1895
+#: C/index.docbook:1901
msgid ""
"A GTK-Doc run generates report files inside the documentation directory. The "
"generated files are named: <filename><package>-undocumented.txt</"
"kan visas eller efterbehandlas enkelt."
#. (itstool) path: chapter/para
-#: C/index.docbook:1904
+#: C/index.docbook:1910
msgid ""
"The <filename><package>-undocumented.txt</filename> file starts with "
"the documentation coverage summary. Below are two sections divided by blank "
"dokumentation, men där en ny parameter har lagts till."
#. (itstool) path: chapter/para
-#: C/index.docbook:1913
+#: C/index.docbook:1919
msgid ""
"The <filename><package>-undeclared.txt</filename> file lists symbols "
"given in the <filename><package>-sections.txt</filename> but not found "
"källkoden. Kontrollera om de har tagits bort eller om de är felstavade."
#. (itstool) path: chapter/para
-#: C/index.docbook:1920
+#: C/index.docbook:1926
msgid ""
"The <filename><package>-unused.txt</filename> file lists symbol names, "
"where the GTK-Doc scanner has found documentation, but does not know where "
# sebras: <filename>?
#. (itstool) path: tip/para
-#: C/index.docbook:1928
+#: C/index.docbook:1934
msgid ""
"Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile."
"am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during "
"köra rimlighetskontroller under körning av <command>make check</command>."
#. (itstool) path: chapter/para
-#: C/index.docbook:1935
+#: C/index.docbook:1941
msgid ""
"One can also look at the files produced by the source code scanner: "
"<filename><package>-decl-list.txt</filename> and <filename><"
"en symbol saknas bör man kontrollera om denna filen innehåller den."
#. (itstool) path: chapter/para
-#: C/index.docbook:1944
+#: C/index.docbook:1950
msgid ""
"If the project is GObject based, one can also look into the files produced "
"by the object scanner: <filename><package>.args.txt</filename>, "
"<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>."
#. (itstool) path: chapter/title
-#: C/index.docbook:1959
+#: C/index.docbook:1965
msgid "Modernizing the documentation"
msgstr "Modernisera dokumentationen"
#. (itstool) path: chapter/para
-#: C/index.docbook:1961
+#: C/index.docbook:1967
msgid ""
"GTK-Doc has been around for quite some time. In this section we list new "
"features together with the version since when it is available."
"tillsammans med vilken version de gjordes tillgängliga."
#. (itstool) path: sect1/title
-#: C/index.docbook:1967
+#: C/index.docbook:1973
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1969
+#: C/index.docbook:1975
msgid ""
"When using xml instead of sgml, one can actually name the master document "
"<filename><package>-docs.xml</filename>."
"huvuddokumentet <filename><paket>-docs.xml</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1974
+#: C/index.docbook:1980
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-sections</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"<code>meld <paket>-decl-list.txt <paket>-sections.txt</code>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1985
+#: C/index.docbook:1991
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"filename> så är du klar."
#. (itstool) path: sect1/title
-#: C/index.docbook:1997
+#: C/index.docbook:2003
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:1999
+#: C/index.docbook:2005
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"filename> för kod som bara byggs ibland."
#. (itstool) path: sect1/title
-#: C/index.docbook:2010
+#: C/index.docbook:2016
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:2016
+#: C/index.docbook:2022
msgid "Enable gtkdoc-check"
msgstr "Aktivera gtkdoc-check"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2017
+#: C/index.docbook:2023
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2012
+#: C/index.docbook:2018
msgid ""
"This version includes a new tool called gtkdoc-check. This tool can run a "
"set of sanity checks on your documentation. It is enabled by adding these "
"am</filename>. <_:example-1/>"
#. (itstool) path: sect1/title
-#: C/index.docbook:2030
+#: C/index.docbook:2036
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:2032
+#: C/index.docbook:2038
msgid ""
"Version 1.18 brought some initial markdown support. Using markdown in doc "
"comments is less intrusive than writing docbook xml. This version improves a "
"\">kommentarsyntax</link> finnas alla detaljer."
#. (itstool) path: sect1/title
-#: C/index.docbook:2042
+#: C/index.docbook:2048
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:2052
+#: C/index.docbook:2058
msgid "Use pre-generated entities"
msgstr "Att använda förgenererade entiteter"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2053
+#: C/index.docbook:2059
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2044
+#: C/index.docbook:2050
msgid ""
"The makefiles shipped with this version generate an entity file at "
"<filename>xml/gtkdocentities.ent</filename>, containing entities for e.g. "
"använda samma xml-huvud i genererade xml-filer. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:2078
+#: C/index.docbook:2084
msgid "Documenting other interfaces"
msgstr "Dokumentera andra gränssnitt"
#. (itstool) path: chapter/para
-#: C/index.docbook:2080
+#: C/index.docbook:2086
msgid ""
"So far we have been using GTK-Doc to document the API of code. The next "
"sections contain suggestions how the tools can be used to document other "
"också dokumentera andra gränssnitt."
#. (itstool) path: sect1/title
-#: C/index.docbook:2087
+#: C/index.docbook:2093
msgid "Command line options and man pages"
msgstr "Kommandoradsflaggor och mansidor"
#. (itstool) path: sect1/para
-#: C/index.docbook:2089
+#: C/index.docbook:2095
msgid ""
"As one can generate man pages for a docbook refentry as well, it sounds like "
"a good idea to use it for that purpose. This way the interface is part of "
"gränssnittet att vara en del av referensen och man får mansidan gratis."
#. (itstool) path: sect2/title
-#: C/index.docbook:2096
+#: C/index.docbook:2102
msgid "Document the tool"
msgstr "Dokumentera verktyget"
# sebras: strange English
#. (itstool) path: sect2/para
-#: C/index.docbook:2098
+#: C/index.docbook:2104
msgid ""
"Create one refentry file per tool. Following <link linkend="
"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
"väl som exempel i glib."
#. (itstool) path: sect2/title
-#: C/index.docbook:2108
+#: C/index.docbook:2114
msgid "Adding the extra configure check"
msgstr "Lägga till den extra configure-kontrollen"
#. (itstool) path: example/title
-#: C/index.docbook:2111 C/index.docbook:2129
+#: C/index.docbook:2117 C/index.docbook:2135
msgid "Extra configure checks"
msgstr "Lägga till extra configure-kontroller"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2112
+#: C/index.docbook:2118
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2126
+#: C/index.docbook:2132
msgid "Adding the extra makefile rules"
msgstr "Lägga till de extra makefilsreglerna"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2130
+#: C/index.docbook:2136
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2152
+#: C/index.docbook:2158
msgid "DBus interfaces"
msgstr "DBus-gränssnitt"
#. (itstool) path: sect1/para
-#: C/index.docbook:2154
+#: C/index.docbook:2160
msgid ""
"(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://"
"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
#. (itstool) path: chapter/title
-#: C/index.docbook:2163
+#: C/index.docbook:2169
msgid "Frequently asked questions"
msgstr "Frågor och svar"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2167
+#: C/index.docbook:2173
msgid "Question"
msgstr "Fråga"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2168
+#: C/index.docbook:2174
msgid "Answer"
msgstr "Svar"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2170
+#: C/index.docbook:2176
msgid "No class hierarchy."
msgstr "Ingen klasshierarki."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2171
+#: C/index.docbook:2177
msgid ""
"The objects <function>xxx_get_type()</function> function has not been "
"entered into the <filename><package>.types</filename> file."
"filen <filename><paket>.types</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2177
+#: C/index.docbook:2183
msgid "Still no class hierarchy."
msgstr "Fortfarande ingen klasshierarki."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2178
+#: C/index.docbook:2184
msgid ""
"Missing or wrong naming in <filename><package>-sections.txt</filename> "
"file (see <ulink url=\"http://mail.gnome.org/archives/gtk-doc-list/2003-"
"October/msg00006.html\">förklaring</ulink>)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2184
+#: C/index.docbook:2190
msgid "Damn, I have still no class hierarchy."
msgstr "Förbannat, jag har fortfarande ingen klasshierarki."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2185
+#: C/index.docbook:2191
msgid ""
"Is the object name (name of the instance struct, e.g. <type>GtkWidget</"
"type>) part of the normal section (don't put this into Standard or Private "
"Standard eller Private)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2192
+#: C/index.docbook:2198
msgid "No symbol index."
msgstr "Inget symbolindex."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2193
+#: C/index.docbook:2199
msgid ""
"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
"index that xi:includes the generated index?"
"inkluderar det genererade indexet med xi:include?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2199
+#: C/index.docbook:2205
msgid "Symbols are not linked to their doc-section."
msgstr "Symboler är inte länkade till deras dokumentationsavsnitt."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2200
+#: C/index.docbook:2206
msgid ""
"Is the doc-comment using the correct markup (added #,% or ())? Check if the "
"gtkdoc-fixxref warns about unresolvable xrefs."
"korsreferenser."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2206
+#: C/index.docbook:2212
msgid "A new class does not appear in the docs."
msgstr "En ny klass dyker inte upp i dokumentationen."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2207
+#: C/index.docbook:2213
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"docs.{xml,sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2213
+#: C/index.docbook:2219
msgid "A new symbol does not appear in the docs."
msgstr "En ny symbol dyker inte upp i dokumentationen."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2214
+#: C/index.docbook:2220
msgid ""
"Is the doc-comment properly formatted. Check for spelling mistakes in the "
"begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable "
"paket>-sections.txt</filename> i ett publikt avsnitt."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2222
+#: C/index.docbook:2228
msgid "A type is missing from the class hierarchy."
msgstr "En typ saknas från klasshierarkin."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2223
+#: C/index.docbook:2229
msgid ""
"If the type is listed in <filename><package>.hierarchy</filename> but "
"not in <filename>xml/tree_index.sgml</filename> then double check that the "
"privat kommer den inte att visas."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2232
+#: C/index.docbook:2238
msgid "I get foldoc links for all gobject annotations."
msgstr "Jag får foldoc-länkar för alla gobject-noteringar."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2233
+#: C/index.docbook:2239
msgid ""
"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
"from <filename><package>-docs.{xml,sgml}</filename>."
"filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2241
+#: C/index.docbook:2247
msgid "Parameter described in source code comment block but does not exist"
msgstr "Parameter beskriven i kommentarsblock i källkoden men existerar inte"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2242
+#: C/index.docbook:2248
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
"Kontrollera om prototypen i huvudet har andra parameternamn än i källkoden."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2247
+#: C/index.docbook:2253
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "multipla ”ID:n” för begränsat länkslut: XYZ"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2248
+#: C/index.docbook:2254
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2251
+#: C/index.docbook:2257
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
msgstr "Elementtypnamn i namnrymd ”” påträffat i para, men ingen mall matchar."
#. (itstool) path: chapter/title
-#: C/index.docbook:2258
+#: C/index.docbook:2264
msgid "Tools related to gtk-doc"
msgstr "Verktyg relaterade till gtk-doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2260
+#: C/index.docbook:2266
msgid ""
"GtkDocPlugin - a <ulink url=\"http://trac-hacks.org/wiki/GtkDocPlugin\">Trac "
"GTK-Doc</ulink> integration plugin, that adds API docs to a trac site and "
"dokumentation till en trac-webbplats och integrerar med trac-sökningen."
#. (itstool) path: chapter/para
-#: C/index.docbook:2265
+#: C/index.docbook:2271
msgid ""
"Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since "
"tags in the API to determine the minimum required version."
<revhistory>
<revision>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development</revremark>
+ </revision>
+ <revision>
<revnumber>1.28</revnumber>
<date>24 Mar 2018</date>
<authorinitials>ss</authorinitials>
<orderedlist>
<listitem>
- <para><guilabel>ஆவணம் எழுதும் முறை.</guilabel> ஆசிரியர் மூல கோப்பை ஒவ்வொரு செயல், மேக்ரோ, இணைப்புக்கும் ஆவணங்களால் நிரப்புவார். (முன்னே விவரங்கள் உருவாக்கப்பட்ட வார்ப்புரு கோப்புக்களால் உள்ளிடப்பட்டது. அப்படி இனி செய்ய பரிந்துரைக்கவில்லை.)</para>
+ <para>
+ <guilabel>Writing the documentation.</guilabel>
+
+ The author fills in the source files with the documentation for each
+ function, macro, structs or unions, etc.
+ </para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>ஜிடிகே டாக் பற்றி</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(FIXME)</para>
<para>
- (History, authors, web pages, mailing list, license, future plans,
+ (authors, web pages, mailing list, license, future plans,
comparison with other similar systems.)
</para>
</chapter>
<chapter id="settingup">
- <title>உங்கள் திட்டத்தை அமைத்தல்</title>
+ <title>Project Setup</title>
<para>
- The next sections describe what steps to perform to integrate GTK-Doc into
- your project. Theses sections assume we work on a project called 'meep'.
- This project contains a library called 'libmeep' and
- an end-user app called 'meeper'. We also assume you will be using autoconf
- and automake. In addition section <link linkend="plain_makefiles">plain
- makefiles or other build systems</link> will describe the basics needed to
- work in a different build setup.
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
</para>
<sect1 id="settingup_docfiles">
<title>தோராய ஆவணம் அமைத்தல்</title>
- <para>உங்கள் தலை மட்ட திட்ட அடைவில் இந்த மாதிரி அடைவுகளை உருவாக்குக.docs/reference (இதனால் உங்களுக்கு பயனர் ஆவணம் docs/help உம் கிடைக்கும்). இன்னொரு துணை அடைவு doc-package என் பெயரிட்டு உருவாக்கவும். ஒரே ஒரு நூலகம் உள்ள பொதிகளுக்கு இந்த படி தேவையில்லை</para>
+ <para>
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
+ </para>
<para>
- This can then look as shown below:
- <example><title>Example directory structure</title>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
<programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
</para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>ஆட்டோ கான்ஃப் உடன் ஒருங்கிணைப்பு</title>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
- <para>ரொம்ப சுலபம். <filename>configure.ac</filename> குறுநிரலுக்கு ஒரே ஒரு வரி மட்டும் சேருங்கள்.</para>
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>ஆட்டோ கான்ஃப் உடன் ஒருங்கிணைப்பு</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-]]></programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>
- This will require all developers to have gtk-doc installed. If it is
- okay for your project to have optional api-doc build setup, you can
- solve this as below. Keep it as is, as gtkdocize is looking for
- <function>GTK_DOC_CHECK</function> at the start of a line.
- <example><title>Keep gtk-doc optional</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-],[
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
-]]></programlisting>
+ <sect2 id="settingup_automake">
+ <title>ஆட்டோமேக் உடன் ஒருங்கிணைப்பு</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
+ <programlisting>
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
+</programlisting>
</example>
- </para>
- <para>முதல் தரு மதிப்பு வடிவமைப்பு நேரத்தில் ஜிடிகே டாக் இன் பதிப்பை சோதிக்கிறது. இரண்டாவது தெர்வு தருமதிப்பு. இது இந்த நிரலால் பயன்படுத்தப்படுகிறது. <application>gtkdocize</application>. <symbol>GTK_DOC_CHECK</symbol> மேக்ரோ பல மாற்றிகளை வடிவமைத்து சேர்க்கிறது:</para>
- <orderedlist>
- <listitem><para>--with-html-dir=PATH : நிறுவிய ஆவணங்களுக்கான பாதை</para></listitem>
- <listitem><para>""--enable-gtk-doc :ஆவணமாக்கத்துக்கு ஜிடிகே டாக் ஐ பயன்படுத்துக. [முன்னிருப்பு=இல்லை]</para></listitem>
- <listitem><para>--enable-gtk-doc-html : html ஒழுங்கில் ஆவணத்தை உருவாக்குக[முன்னிருப்பு=ஆம்]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : pdf ஒழுங்கில் ஆவணத்தை உருவாக்குக [முன்னிருப்பு=இல்லை]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
- <important>
- <para>ஜிடிகே டாக் GTK-Doc முன்னிருப்பாக செயலிழந்து இருக்கும்! ஆகவே அடுத்த <filename>configure</filename> இயக்கத்துக்கு இந்த தேர்வை செய்க: <option>'--enable-gtk-doc'</option> . இல்லையானால் முன் உருவாக்கிய ஆவணங்கள் நிறூவப்படும்.( இது பயனர்களுக்கு புரியும், நல்லது. ஆனால் உருவாக்குவோருக்கு அல்ல).</para>
- </important>
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <para>
- Furthermore it is recommended that you have the following line inside
- your <filename>configure.ac</filename> script.
- This allows <application>gtkdocize</application> to automatically copy the
- macro definition for <function>GTK_DOC_CHECK</function> to your project.
- </para>
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
- <para>
- <example><title>gtkdocize க்கு முன்னேற்பாடு</title>
- <programlisting><![CDATA[
+ All the tools support <option>--help</option> to list the supported
+ options.
+ </para>
+
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>ஆட்டோ கான்ஃப் உடன் ஒருங்கிணைப்பு</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
]]></programlisting>
- </example>
- </para>
- <para>
- After all changes to <filename>configure.ac</filename> are made, update
- the <filename>configure</filename> file. This can be done by re-running
- <code>autoreconf -i</code> or <code>autogen.sh</code>.
- </para>
- </sect1>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>ஆட்டோமேக் உடன் ஒருங்கிணைப்பு</title>
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub directory of the
- <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
- to your project's API documentation directory (
- <filename class="directory">./docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple doc-packages repeat this for each one.
- </para>
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <para>
- The next step is to edit the settings inside the <filename>Makefile.am</filename>.
- All the settings have a comment above that describes their purpose.
- Most settings are extra flags passed to the respective tools. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
- All the tools support <option>--help</option> to list the supported
- parameters.
- </para>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <!-- FIXME: explain options ? -->
+ <orderedlist>
+ <listitem><para>--with-html-dir=PATH : நிறுவிய ஆவணங்களுக்கான பாதை</para></listitem>
+ <listitem><para>""--enable-gtk-doc :ஆவணமாக்கத்துக்கு ஜிடிகே டாக் ஐ பயன்படுத்துக. [முன்னிருப்பு=இல்லை]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : html ஒழுங்கில் ஆவணத்தை உருவாக்குக[முன்னிருப்பு=ஆம்]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : pdf ஒழுங்கில் ஆவணத்தை உருவாக்குக [முன்னிருப்பு=இல்லை]</para></listitem>
+ </orderedlist>
- </sect1>
+ <important>
+ <para>ஜிடிகே டாக் GTK-Doc முன்னிருப்பாக செயலிழந்து இருக்கும்! ஆகவே அடுத்த <filename>configure</filename> இயக்கத்துக்கு இந்த தேர்வை செய்க: <option>'--enable-gtk-doc'</option> . இல்லையானால் முன் உருவாக்கிய ஆவணங்கள் நிறூவப்படும்.( இது பயனர்களுக்கு புரியும், நல்லது. ஆனால் உருவாக்குவோருக்கு அல்ல).</para>
+ </important>
- <sect1 id="settingup_autogen">
- <title>ஆட்டொஜென் உடன் ஒருங்கிணைத்தல்</title>
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- <para>முக்கால்வாசி திட்டங்களில் (cvs/svn/git போன்ற) வெர்ஷன் கட்டுப்பாடு அமைப்பில் இருந்து பெறப்பட்டதும் அடிக்கட்டுமான பணியை செய்ய <filename>autogen.sh</filename> குறுநிரல் இருக்கும். ஜிடிகே டாக் (GTK-Doc) இல் <application>gtkdocize</application> என ஒரு கருவி உண்டு. இது அது போன்ற குறுநிரலுடன் வேலை செய்யும்.இது autoheader, automake அல்லது autoconf க்கு முன்னால் இயக்கப்பட வேண்டும்.</para>
+ <sect2 id="settingup_autogen">
+ <title>ஆட்டொஜென் உடன் ஒருங்கிணைத்தல்</title>
- <para>
- <example><title>autogen.sh இலிருந்து gtkdocize ஐ இயக்குதல்</title>
- <programlisting><![CDATA[
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
+
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
+
+ <para>
+ <example><title>autogen.sh இலிருந்து gtkdocize ஐ இயக்குதல்</title>
+ <programlisting><![CDATA[
gtkdocize || exit 1
]]></programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>
- When running <application>gtkdocize</application> it copies
- <filename>gtk-doc.make</filename> to your project root (or any directory
- specified by the <option>--docdir</option> option).
- It also checks you configure script for the <function>GTK_DOC_CHECK</function>
- invocation. This macro can be used to pass extra parameters to
- <application>gtkdocize</application>.
- </para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>
- Historically GTK-Doc was generating template files where developers entered the docs.
- This turned out to be not so good (e.g. the need for having generated
- files under version control).
- Since GTK-Doc 1.9 the tools can get all the information from source comments
- and thus the templates can be avoided. We encourage people to keep
- documentation in the code. <application>gtkdocize</application> supports now
- a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
- tmpl usage totally. Besides adding the option directly to the command
- invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
- or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
- If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
- please remove the directory (e.g. from version control system).
- </para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>டாக் உருவாக்கியை (doc build) இயக்குதல்</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>இப்போது கட்டுமானத்திற்கு ஆயத்தமாகிவிட்டோம். முதலில் நாம் மீன்டும் <filename>autogen.sh</filename> ஐ இயக்கவேண்டும். இது உங்களுக்கு கட்டமைப்பை இயக்கினால் அதற்கு <option>--enable-gtk-doc</option> தேர்வை தரவும். இல்லையானால் கைமுறையாக இதே தேர்வுடன் <filename>configure</filename> ஐ பிரிதொரு முறை இயக்கவும்.</para>
- <para>
- The first make run generates several additional files in the doc-directories.
- The important ones are:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>.
- </para>
- <para>
- <example><title>டாக் உருவாக்கியை (doc build) இயக்குதல்</title>
- <programlisting><![CDATA[
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>இப்போது கட்டுமானத்திற்கு ஆயத்தமாகிவிட்டோம். முதலில் நாம் மீன்டும் <filename>autogen.sh</filename> ஐ இயக்கவேண்டும். இது உங்களுக்கு கட்டமைப்பை இயக்கினால் அதற்கு <option>--enable-gtk-doc</option> தேர்வை தரவும். இல்லையானால் கைமுறையாக இதே தேர்வுடன் <filename>configure</filename> ஐ பிரிதொரு முறை இயக்கவும்.</para>
+ <para>
+ The first make run generates several additional files in the doc-directories.
+ The important ones are:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>.
+ </para>
+ <para>
+ <example><title>டாக் உருவாக்கியை (doc build) இயக்குதல்</title>
+ <programlisting><![CDATA[
./autogen.sh --enable-gtk-doc
make
]]></programlisting>
- </example>
- </para>
- <para>இப்போது உங்கள் உலாவியை <filename>docs/reference/<package>/index.html</filename> க்கு சுட்டிக்காட்டலாம். ஆமாம், இது கொஞ்சம் ஏமாற்றமாகத்தான் இருக்கிறது. கவலை வேண்டாம். அடுத்த அத்தியாயத்தில் எப்படி இவற்றை உயிருக்கு கொண்டு வருவது என பார்க்கலாம்.</para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>வெர்ஷன் கன்ட்ரோல் அமைப்புகளுடன் ஒருங்கிணைத்தல்</title>
+ <sect1 id="settingup_cmake">
+ <title>Integration with CMake build systems</title>
<para>
- As a rule of thumb, it's the files you edit which should go under
- version control. For typical projects it's these files:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>,
- <filename>Makefile.am</filename>.
+ GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
+ (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
+ module). This provides a <literal>gtk_doc_add_module</literal>
+ command that you can set in your <filename>CMakeLists.txt</filename>
+ file.
</para>
+
<para>
- Files in the <filename>xml/</filename> and <filename>html/</filename>
- directories should not go under version control. Neither should any of
- the <filename>.stamp</filename> files.
+ The following example shows how to use this command.
+ <example><title>Example of using GTK-Doc from CMake</title>
+ <programlisting><![CDATA[
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+]]></programlisting>
+ </example>
</para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integration with plain makefiles or other build systems</title>
<para>
</para>
</sect1>
- <sect1 id="cmake">
- <title>Integration with CMake build systems</title>
-
- <para>
- GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
- (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
- module). This provides a <literal>gtk_doc_add_module</literal>
- command that you can set in your <filename>CMakeLists.txt</filename>
- file.
- </para>
-
- <para>
- The following example shows how to use this command.
- <example><title>Example of using GTK-Doc from CMake</title>
- <programlisting><![CDATA[
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>வெர்ஷன் கன்ட்ரோல் அமைப்புகளுடன் ஒருங்கிணைத்தல்</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>
+ As a rule of thumb, it's the files you edit which should go under
+ version control. For typical projects it's these files:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>,
+ <filename>Makefile.am</filename>.
+ </para>
+ <para>
+ Files in the <filename>xml/</filename> and <filename>html/</filename>
+ directories should not go under version control. Neither should any of
+ the <filename>.stamp</filename> files.
+ </para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
- </sect1>
</chapter>
<chapter id="documenting">
syntax of the comments.
</para>
- <note>
- <title>ஆவணம் இடுதல்</title>
- <para>முன் காலத்தில் பெரும்பாலான ஆவணங்கள் <filename>tmpl</filename> அடைவில் இருக்கும் கோப்புகளில் நிரப்பப்பட வேண்டி இருந்தது. இதில் நஷ்டமாக தகவல்கள் அவ்வப்போது புதுப்பிக்கப்படவில்லை. மேலும் இவை வெர்ஷன் கட்டுப்பாடு அமைப்புகளுடன் பொருந்தவில்லை</para>
- <para>மேற்கூறிய காரணங்களால் நாங்கள் ஆவணங்களை மூலத்துடன் வைக்கு மாறூ சொல்கிறோம். இந்த கையேடு இந்த முறையை மட்டுமே விவாதிக்கும்.</para>
- </note>
-
<para>
- The scanner can handle the majority of C headers fine. In the case of
- receiving warnings from the scanner that look like a special case, one can
- hint GTK-Doc to skip over them.
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
</para>
<tip>
- <para>ஜிடிகே டாக் </para>
+ <para>
+ As already mentioned earlier GTK-Doc is for documenting public API. Thus
+ one cannot write documentation for static symbols. Nevertheless it is good
+ to comment those symbols too. This helps other developers to understand
+ your code.
+ Therefore we recommend to comment these using normal comments (without the
+ 2nd '*' in the first line).
+ If later the function needs to be made public, all one needs to do is to
+ add another '*' in the comment block and insert the symbol name at the
+ right place inside the sections file.
+ </para>
</tip>
</sect1>
</para>
<para>
- <example><title>Example types file snippet</title>
+ <example><title>Example <package>.types file</title>
<programlisting><![CDATA[
#include <gtk/gtk.h>
containing entities for e.g. package_name and package_version. You can
use this e.g. in the main xml file to avoid hardcoding the version
number. Below is an example that shows how the entity file is included
- and how the entities are used. The entities can also be used in all
+ in the master template and how the entities are used.
+ The entities can also be used in all
generated files, GTK-Doc will use the same xml header in generated xml
files.
<example><title>Use pre-generated entities</title>
<revhistory>
<revision>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development</revremark>
+ </revision>
+ <revision>
<revnumber>1.28</revnumber>
<date>24 Mar 2018</date>
<authorinitials>ss</authorinitials>
<orderedlist>
<listitem>
- <para><guilabel>పత్రికీకరణను వ్రాయుట.</guilabel> మూలకర్త(ఆథర్) సోర్స్ ఫైళ్ళనందు ప్రతి ఫంక్షన్కు, మాక్రోకు, యూనియన్కు పత్రకీకరణను యిస్తాడు. (గతంలో సమాచారమును మాదిరి ఫైళ్ళనందు ప్రవేశపెట్టేవారు, యిది యిప్పడు సమర్ధించబడదు).</para>
+ <para>
+ <guilabel>Writing the documentation.</guilabel>
+
+ The author fills in the source files with the documentation for each
+ function, macro, structs or unions, etc.
+ </para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>GTK-Doc గురించి</title>
+ <para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
<para>(FIXME)</para>
<para>
- (History, authors, web pages, mailing list, license, future plans,
+ (authors, web pages, mailing list, license, future plans,
comparison with other similar systems.)
</para>
</chapter>
<chapter id="settingup">
- <title>మీ ప్రోజెక్టును అమర్చుట</title>
+ <title>Project Setup</title>
<para>
- The next sections describe what steps to perform to integrate GTK-Doc into
- your project. Theses sections assume we work on a project called 'meep'.
- This project contains a library called 'libmeep' and
- an end-user app called 'meeper'. We also assume you will be using autoconf
- and automake. In addition section <link linkend="plain_makefiles">plain
- makefiles or other build systems</link> will describe the basics needed to
- work in a different build setup.
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
</para>
<sect1 id="settingup_docfiles">
<title>స్కెల్టెన్ పత్రికీకరణను అమర్చుచున్నది</title>
- <para>మీ పై-స్థాయి ప్రోజెక్టు డైరెక్టరీ క్రింద docs/reference అను ఫోల్డర్లను సృష్టించుము (ఈ విధంగా మీరు docs/helpను అంత్య-వినియోగదారి పత్రికీకరణ కొరకు కలిగివుండవచ్చును). doc-package నామముతో వేరొక వుపసంచయంను సృష్టించుకొనుట సిఫార్సు చేయబడింది. కేవలం వొక లైబ్రరీ మాత్రమే వున్న ప్యాకేజీలకు యిది అవసరములేదు.</para>
+ <para>
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
+ </para>
<para>
- This can then look as shown below:
- <example><title>Example directory structure</title>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
<programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
</para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>autoconf తో విలీనం</title>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
- <para>చాలా సులువు! మీ <filename>configure.ac</filename> స్క్రిప్టునకు వొక లైను మాత్రమే జతచేయుము.</para>
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>autoconf తో విలీనం</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-]]></programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>
- This will require all developers to have gtk-doc installed. If it is
- okay for your project to have optional api-doc build setup, you can
- solve this as below. Keep it as is, as gtkdocize is looking for
- <function>GTK_DOC_CHECK</function> at the start of a line.
- <example><title>Keep gtk-doc optional</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-],[
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
-]]></programlisting>
+ <sect2 id="settingup_automake">
+ <title>automake తో విలీనం</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
+ <programlisting>
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
+</programlisting>
</example>
- </para>
- <para>ఆకృతీకరణ సమయము వద్ద gtkdocversion కొరకు పరిశీలించుటకు మొదటి ఆర్గుమెంటు వుపయోగించబడింది. 2వది, <application>gtkdocize</application> చేత వుపయోగించబడిన ఐచ్చిక ఆర్గుమెంట్. <symbol>GTK_DOC_CHECK</symbol> మాక్రో చాలా ఆకృతీకరణ స్విచ్లను జతచేస్తుంది:</para>
- <orderedlist>
- <listitem><para>--with-html-dir=PATH : సంస్థాపించిన పత్రములకు పాత్</para></listitem>
- <listitem><para>--enable-gtk-doc : పత్రికీకరణను నిర్మించుటకు gtk-doc వుపయోగించుము [default=no]</para></listitem>
- <listitem><para>--enable-gtk-doc-html : పత్రికీకరణను html ఫార్మాట్నందు నిర్మించుము [default=yes]</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : పత్రికీకరణను pdf ఫార్మాట్ నందు నిర్మించుము [default=no]</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
- <important>
- <para>GTK-Doc అప్రమేయంగా అచేతనము చేయబడింది! ఐచ్చికము <option>'--enable-gtk-doc'</option>ను తరువాతి <filename>configure</filename>కు నడుపుట మర్చిపోవద్దు. లేకపోతే ముందుగా జనియింపచేసిన పత్రికీకరణ సంస్థాపించబడుతుంది (ఇది వినియోగదారులకు వుపయోగకరం అయితే అభివృద్దికారులకు కాదు).</para>
- </important>
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <para>
- Furthermore it is recommended that you have the following line inside
- your <filename>configure.ac</filename> script.
- This allows <application>gtkdocize</application> to automatically copy the
- macro definition for <function>GTK_DOC_CHECK</function> to your project.
- </para>
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
- <para>
- <example><title>gtkdocize కొరకు సన్నాహం</title>
- <programlisting><![CDATA[
+ All the tools support <option>--help</option> to list the supported
+ options.
+ </para>
+
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>autoconf తో విలీనం</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
]]></programlisting>
- </example>
- </para>
- <para>
- After all changes to <filename>configure.ac</filename> are made, update
- the <filename>configure</filename> file. This can be done by re-running
- <code>autoreconf -i</code> or <code>autogen.sh</code>.
- </para>
- </sect1>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>automake తో విలీనం</title>
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub directory of the
- <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
- to your project's API documentation directory (
- <filename class="directory">./docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple doc-packages repeat this for each one.
- </para>
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <para>
- The next step is to edit the settings inside the <filename>Makefile.am</filename>.
- All the settings have a comment above that describes their purpose.
- Most settings are extra flags passed to the respective tools. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
- All the tools support <option>--help</option> to list the supported
- parameters.
- </para>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <!-- FIXME: explain options ? -->
+ <orderedlist>
+ <listitem><para>--with-html-dir=PATH : సంస్థాపించిన పత్రములకు పాత్</para></listitem>
+ <listitem><para>--enable-gtk-doc : పత్రికీకరణను నిర్మించుటకు gtk-doc వుపయోగించుము [default=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : పత్రికీకరణను html ఫార్మాట్నందు నిర్మించుము [default=yes]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : పత్రికీకరణను pdf ఫార్మాట్ నందు నిర్మించుము [default=no]</para></listitem>
+ </orderedlist>
- </sect1>
+ <important>
+ <para>GTK-Doc అప్రమేయంగా అచేతనము చేయబడింది! ఐచ్చికము <option>'--enable-gtk-doc'</option>ను తరువాతి <filename>configure</filename>కు నడుపుట మర్చిపోవద్దు. లేకపోతే ముందుగా జనియింపచేసిన పత్రికీకరణ సంస్థాపించబడుతుంది (ఇది వినియోగదారులకు వుపయోగకరం అయితే అభివృద్దికారులకు కాదు).</para>
+ </important>
- <sect1 id="settingup_autogen">
- <title>autogen తో విలీనం</title>
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- <para>వర్షన్ కంట్రోల్ సిస్టమ్ (cvs/svn/git వంటి) నుండి చెక్అవుట్ తర్వాత బుల్డ్ నిర్మాణం అమర్చుటకు చాలా ప్రోజెక్టులు <filename>autogen.sh</filename> స్క్రిప్టును కలిగివుంటాయి. GTK-Doc అనునది <application>gtkdocize</application> అనబడు సాధనంతో వస్తుంది దీనిని అటువంటి స్క్రిప్టు నందు వుపయోగించవచ్చును. ఇది autoheader, automake లేదా autoconf ముందు నడుపవలెను.</para>
+ <sect2 id="settingup_autogen">
+ <title>autogen తో విలీనం</title>
- <para>
- <example><title>autogen.sh నుండి gtkdocize నడుపుతోంది</title>
- <programlisting><![CDATA[
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
+
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
+
+ <para>
+ <example><title>autogen.sh నుండి gtkdocize నడుపుతోంది</title>
+ <programlisting><![CDATA[
gtkdocize || exit 1
]]></programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>
- When running <application>gtkdocize</application> it copies
- <filename>gtk-doc.make</filename> to your project root (or any directory
- specified by the <option>--docdir</option> option).
- It also checks you configure script for the <function>GTK_DOC_CHECK</function>
- invocation. This macro can be used to pass extra parameters to
- <application>gtkdocize</application>.
- </para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>
- Historically GTK-Doc was generating template files where developers entered the docs.
- This turned out to be not so good (e.g. the need for having generated
- files under version control).
- Since GTK-Doc 1.9 the tools can get all the information from source comments
- and thus the templates can be avoided. We encourage people to keep
- documentation in the code. <application>gtkdocize</application> supports now
- a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
- tmpl usage totally. Besides adding the option directly to the command
- invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
- or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
- If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
- please remove the directory (e.g. from version control system).
- </para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>doc బుల్డును నడుపుట</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>గతంలో జరిపిన స్టెప్పుల తర్వాత యిప్పుడు బుల్డును నడుపవలెను. ముందుగా మనము <filename>autogen.sh</filename>ను తిరిగి నడుపవలెను. ఈ స్క్రిప్టు మీ కొరకు ఆకృతీకరణను నడిపితే, దానికి <option>--enable-gtk-doc</option> ఐచ్చికాన్ని యివ్వుము. లేదా తరువాత ఈ ఐచ్చికముతో మానవీయంగా <filename>configure</filename>ను నడుపుము.</para>
- <para>
- The first make run generates several additional files in the doc-directories.
- The important ones are:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>.
- </para>
- <para>
- <example><title>doc బుల్డును నడుపుట</title>
- <programlisting><![CDATA[
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>గతంలో జరిపిన స్టెప్పుల తర్వాత యిప్పుడు బుల్డును నడుపవలెను. ముందుగా మనము <filename>autogen.sh</filename>ను తిరిగి నడుపవలెను. ఈ స్క్రిప్టు మీ కొరకు ఆకృతీకరణను నడిపితే, దానికి <option>--enable-gtk-doc</option> ఐచ్చికాన్ని యివ్వుము. లేదా తరువాత ఈ ఐచ్చికముతో మానవీయంగా <filename>configure</filename>ను నడుపుము.</para>
+ <para>
+ The first make run generates several additional files in the doc-directories.
+ The important ones are:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>.
+ </para>
+ <para>
+ <example><title>doc బుల్డును నడుపుట</title>
+ <programlisting><![CDATA[
./autogen.sh --enable-gtk-doc
make
]]></programlisting>
- </example>
- </para>
- <para>ఇప్పుడు మీ బ్రౌజర్కు మీరు <filename>docs/reference/<package>/index.html</filename>ను సూచించవచ్చును. అవును, యిప్పటికి యిది కొంత నిరుత్సాహపరుస్తోంది. అయితే ఆగండి, తరువాతి అధ్యాయమునందు పేజీలను యెలా నింపాలో చెబుతాము.</para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>వర్షన్ కంట్రోల్ సిస్టమ్తో విలీనం</title>
+ <sect1 id="settingup_cmake">
+ <title>Integration with CMake build systems</title>
<para>
- As a rule of thumb, it's the files you edit which should go under
- version control. For typical projects it's these files:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>,
- <filename>Makefile.am</filename>.
+ GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
+ (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
+ module). This provides a <literal>gtk_doc_add_module</literal>
+ command that you can set in your <filename>CMakeLists.txt</filename>
+ file.
</para>
+
<para>
- Files in the <filename>xml/</filename> and <filename>html/</filename>
- directories should not go under version control. Neither should any of
- the <filename>.stamp</filename> files.
+ The following example shows how to use this command.
+ <example><title>Example of using GTK-Doc from CMake</title>
+ <programlisting><![CDATA[
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+]]></programlisting>
+ </example>
</para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>Integration with plain makefiles or other build systems</title>
<para>
</para>
</sect1>
- <sect1 id="cmake">
- <title>Integration with CMake build systems</title>
-
- <para>
- GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
- (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
- module). This provides a <literal>gtk_doc_add_module</literal>
- command that you can set in your <filename>CMakeLists.txt</filename>
- file.
- </para>
-
- <para>
- The following example shows how to use this command.
- <example><title>Example of using GTK-Doc from CMake</title>
- <programlisting><![CDATA[
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>వర్షన్ కంట్రోల్ సిస్టమ్తో విలీనం</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>
+ As a rule of thumb, it's the files you edit which should go under
+ version control. For typical projects it's these files:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>,
+ <filename>Makefile.am</filename>.
+ </para>
+ <para>
+ Files in the <filename>xml/</filename> and <filename>html/</filename>
+ directories should not go under version control. Neither should any of
+ the <filename>.stamp</filename> files.
+ </para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
- </sect1>
</chapter>
<chapter id="documenting">
syntax of the comments.
</para>
- <note>
- <title>పత్రికీకరణ స్థానము</title>
- <para>గతంలో చాలా వరకు పత్రికీకరణ అనునది <filename>tmpl</filename> డైరెక్టరీ క్రిందని ఫైళ్ళలో నింపవలసివుండేది. సమాచారము సరిగా నవీకరించబడక పోవుట మరియు ఆ ఫైలు వర్షన్ కంట్రోల్ సిస్టమ్సుతో విభేదించుట వంటి లోపాలను యిది కలిగివుంది.</para>
- <para>ముందుగా తెలిపిన సమస్యలను తప్పించుటకు మేము పత్రికీకరణను మూలముల లోపలే వుంచమని సూచించుచున్నాము. ఈ మాన్యుయల్ ఈ విధంగా కోడ్ పత్రికీకరణను మాత్రమే వివరించును.</para>
- </note>
-
<para>
- The scanner can handle the majority of C headers fine. In the case of
- receiving warnings from the scanner that look like a special case, one can
- hint GTK-Doc to skip over them.
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
</para>
<tip>
- <para>ముందుగా చెప్పినట్లుగా GTK-Doc అనునది పబ్లిక్ API పత్రికీకరణ కొరకు. స్థిర చిహ్నములకు వొక్కరే పత్రికీకరణ వ్రాయలేరు. ఆ చిహ్నములను కూడా వ్యాఖ్యానించుట మంచిది. ఇది యితరులు కూడా మీ కోడ్ను అర్ధము చేసుకొనుటకు సహాయపడును. అందుకని వీటిని సాదారణ వ్యాఖ్యలు (మొదటి వరుసనందు 2వ '*' లేకుండా) వుపయోగించి వ్యాఖ్యానించమని సూచించడమైంది. తరువాత ఆ ఫంక్షన్ పబ్లిక్గా మార్చవలసివుంటే, చేయవలసినదల్లా వేరొక '*'ను వ్యాఖ్య బ్లాక్ నందు చేర్చి మరియు చిహ్నపు నామాన్నివిభగాముల ఫైలునందు సరైన స్థానములో వుంచడమే.</para>
+ <para>
+ As already mentioned earlier GTK-Doc is for documenting public API. Thus
+ one cannot write documentation for static symbols. Nevertheless it is good
+ to comment those symbols too. This helps other developers to understand
+ your code.
+ Therefore we recommend to comment these using normal comments (without the
+ 2nd '*' in the first line).
+ If later the function needs to be made public, all one needs to do is to
+ add another '*' in the comment block and insert the symbol name at the
+ right place inside the sections file.
+ </para>
</tip>
</sect1>
</para>
<para>
- <example><title>Example types file snippet</title>
+ <example><title>Example <package>.types file</title>
<programlisting><![CDATA[
#include <gtk/gtk.h>
containing entities for e.g. package_name and package_version. You can
use this e.g. in the main xml file to avoid hardcoding the version
number. Below is an example that shows how the entity file is included
- and how the entities are used. The entities can also be used in all
+ in the master template and how the entities are used.
+ The entities can also be used in all
generated files, GTK-Doc will use the same xml header in generated xml
files.
<example><title>Use pre-generated entities</title>
<revhistory>
<revision>
+ <revnumber>1.29</revnumber>
+ <date>28 Aug 2018</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development</revremark>
+ </revision>
+ <revision>
<revnumber>1.28</revnumber>
<date>24 Mar 2018</date>
<authorinitials>ss</authorinitials>
<guilabel>Writing the documentation.</guilabel>
The author fills in the source files with the documentation for each
- function, macro, union etc. (In the past information was entered in
- generated template files, which is not recommended anymore).
+ function, macro, structs or unions, etc.
</para>
</listitem>
<title>关于 GTK-Doc</title>
<para>
+ Historically GTK-Doc was used to generate template files from the soures
+ code. These template files could be used by developers to enter the
+ API documentation. This approach was rather inconvenient because it
+ required to keep the generated files under version control.
+ Since GTK-Doc 1.9 it became possible to place all API information
+ into source comments, which made the template support obsolete.
+ In version 1.26 template support has been.
+ </para>
+
+ <para>
(FIXME)
</para>
<para>
- (History, authors, web pages, mailing list, license, future plans,
+ (authors, web pages, mailing list, license, future plans,
comparison with other similar systems.)
</para>
</chapter>
<chapter id="settingup">
- <title>设置您的项目</title>
+ <title>Project Setup</title>
<para>
- The next sections describe what steps to perform to integrate GTK-Doc into
- your project. Theses sections assume we work on a project called 'meep'.
- This project contains a library called 'libmeep' and
- an end-user app called 'meeper'. We also assume you will be using autoconf
- and automake. In addition section <link linkend="plain_makefiles">plain
- makefiles or other build systems</link> will describe the basics needed to
- work in a different build setup.
+ This Chapter describes the steps that are necessary to integrate GTK-Doc
+ into your project. The integration of GTK-Doc into a project includes the
+ following steps:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Preparation of the directory structure and creating required
+ configuration files for your GTK-Doc documentation (see
+ <link linkend="settingup_docfiles">
+ Setting up a skeleton documentation</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjusting the build system to build your documentation using the
+ GTK-Doc tools. Multiple build systems are supported, in
+ this manual we describe how to integrate GTK-Doc with
+ <link linkend="settingup_autotools">Autotools</link>,
+ <link linkend="settingup_cmake">CMake</link>, and
+ <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adding GTK-Doc specific files to version control and deciding which
+ files to ignore (see <link linkend="settingup_vcs">
+ Integration with version control systems</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections assume we work on a project called
+ <code>meep</code>.
+ This project contains two packages (or modules),
+ a library called <code>libmeep</code> and an end-user app
+ called <code>meeper</code>.
</para>
<sect1 id="settingup_docfiles">
<title>设置一个框架文档</title>
<para>
- Under your top-level project directory create folders called docs/reference
- (this way you can also have docs/help for end-user documentation).
- It is recommended to create another subdirectory with the name of the doc-package.
- For packages with just one library this step is not necessary.
+ A common convention is to place documentation into a folder called
+ <code>docs</code> inside your top-level project directory.
+ We usually distinguish between <emphasis>reference
+ documentation</emphasis> intended for developers and an
+ <emphasis>user manual</emphasis> intended for end-users.
+ Again the convention is to have separate folders for both.
+ We usually place the reference documentation in a folder named
+ <code>reference</code> and the end-user manual in a folder named
+ <code>help</code> as.
+
+ According to the above convention the documentation for our
+ <code>libmeep</code> package would be placed into:
+ <code>docs/reference/libmeep</code>.
+
+ For packages with just one library or application
+ the documentation could also be placed directly into
+ <code>docs/reference</code>.
+
+ It is not mandatory to use the above convention, but if you
+ choose to use a different directory structure you must adjust
+ your build system configuration to match your directory
+ structure.
</para>
- <para>目录结构将会如下所示：<example><title>范例目录结构</title>
+ <para>
+ In the following sections we will assume a directory structure
+ for our <emphasis>meep</emphasis> project that uses the above
+ conventions.
+
+ <example>
+ <title>Example directory structure of <emphasis>meep</emphasis>
+ project</title>
<programlisting><![CDATA[
meep/
docs/
- reference/
+ reference/ # reference documentation
libmeep/
meeper/
+ help/ # optional: user manual
+ meeper/
src/
libmeep/
meeper/
]]></programlisting>
- </example></para>
+ </example>
+ </para>
</sect1>
- <sect1 id="settingup_autoconf">
- <title>与autoconf集成</title>
+ <sect1 id="settingup_autotools">
+ <title>Integration with Autotools</title>
+ <para>
+ Integration of GTK-Doc into an autotools-based build system requires the
+ following steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that <application>gtkdocize</application> is run once before
+ the <filename>configure</filename> script. If an
+ <filename>autogen.sh</filename> script is present, adjust it to
+ check for GTK-Doc and add a call to
+ <application>gtkdocize</application>.
+ </para>
- <para>非常容易！只需在您的 <filename>configure.ac</filename> 脚本中添加一行。</para>
+ <para>
+ The main purpose of <application>gtkdocize</application> is to
+ make the <filename>gtk-doc.make</filename> Makefile and the
+ <filename>gtk-doc.m4</filename> macro definition file available
+ to the build system, either by copying or linking it
+ into the project.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add the necessary <application>autoconf</application> macros to
+ <filename>configure.ac</filename> to enable GTK-Doc in your build
+ system to allow configuration of GTK-Doc via the generated
+ <filename>configure</filename> script.
+ </para>
+ <para>
+ Among others with registers the <code>--enable-gtk-doc</code>
+ option with the <filename>configure</filename> script.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an <application>automake</application> script for each
+ application or library in your project. In the example used in this
+ documentation this step applies to both <code>meeper</code> and
+ <code>libmeep</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- <example><title>与autoconf集成</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-]]></programlisting>
- </example>
+ In the following sections, we will perform the above steps in reverse
+ order. We start with the <application>automake</application> scripts
+ and work our way up to <filename>configure.ac</filename> and
+ <filename>autogen.sh</filename>.
+ Then we show how enable Gtk-Doc in the build system and
+ how to build the documentation.
</para>
- <para>
- This will require all developers to have gtk-doc installed. If it is
- okay for your project to have optional api-doc build setup, you can
- solve this as below. Keep it as is, as gtkdocize is looking for
- <function>GTK_DOC_CHECK</function> at the start of a line.
- <example><title>Keep gtk-doc optional</title>
- <programlisting><![CDATA[
-# check for gtk-doc
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-],[
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
-]]></programlisting>
+ <sect2 id="settingup_automake">
+ <title>与automake集成</title>
+
+ <para>
+ First copy the <filename>Makefile.am</filename> from the
+ <filename class="directory">examples</filename> sub-directory of the
+ <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
+ gtkdoc-sources</ulink>
+ to your project's reference documentation directory (e.g.
+ <filename class="directory">docs/reference/<package></filename>).
+ A local copy should be available under e.g.
+ <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
+ If you have multiple packages repeat this for each one.
+ </para>
+
+ <note>
+ <simpara>
+ Do not forget to add each <filename>Makefile.am</filename>
+ to the <function>AC_CONFIG_FILES</function> macro in
+ <filename>configure.ac</filename>. For
+ <filename>docs/reference/libmeep/Makefile.am</filename> you will
+ need to add the entry
+ <filename>docs/reference/libmeep/Makefile</filename>
+ to <function>AC_CONFIG_FILES</function>.
+ </simpara>
+ </note>
+
+ <example>
+ <title>
+ Example directory structure with <filename>Makefiles.am</filename>
+ </title>
+ <programlisting>
+meep/
+ docs/
+ reference/ # reference documentation
+ libmeep/
+ Makefile.am
+ meeper/
+ Makefile.am
+ help/ # optional: user manual
+ meeper/
+ src/
+ libmeep/
+ meeper/
+</programlisting>
</example>
- </para>
- <para>
- The first argument is used to check for the gtkdocversion at configure time.
- The 2nd, optional argument is used by <application>gtkdocize</application>.
- The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure switches:
- </para>
- <orderedlist>
- <listitem><para>--with-html-dir=PATH : 安装文档的路径</para></listitem>
- <listitem><para>--enable-gtk-doc : 用gtk-doc构建文档［默认值：no］</para></listitem>
- <listitem><para>--enable-gtk-doc-html :用html格式构建文档［默认值：yes］</para></listitem>
- <listitem><para>--enable-gtk-doc-pdf : 以PDF格式构建文档［默认值：no］</para></listitem>
- </orderedlist>
+ <para>
+ Next, you need to customize the copied Makefiles
+ and provide values for the various parameters in each
+ <filename>Makefile.am</filename>.
- <important>
- <para>GTK-Doc在默认情况下是关闭的！请记得给文本<filename>configure</filename>运作时传递<option>'--enable-gtk-doc'</option>选项。否则，将会安装预先生成的文档（对用户有意义但对开发人员没用处）。</para>
- </important>
+ All settings have a comment above them that describes their purpose
+ and how to customize the setting.
- <para>
- Furthermore it is recommended that you have the following line inside
- your <filename>configure.ac</filename> script.
- This allows <application>gtkdocize</application> to automatically copy the
- macro definition for <function>GTK_DOC_CHECK</function> to your project.
- </para>
+ Most settings are used to supply extra flags to the respective tools
+ to which they apply. Every tool
+ has a variable of the form <option><TOOLNAME>_OPTIONS</option>
+ (e.g. the tool <application>gtkdoc-mkhtml</application> has
+ an option named <code>MKHTML_OPTIONS</code>).
- <para>
- <example><title>准备gtkdocize</title>
- <programlisting><![CDATA[
+ All the tools support <option>--help</option> to list the supported
+ options.
+ </para>
+
+ <para>
+ The following list explains the most relevant options. Check the
+ example <filename>Makefile.am</filename> for additional options.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>DOC_MODULE</option> is used to provide the name of the
+ package that is being documentated (e.g. <code>meeper</code>, or
+ <code>libmeep</code>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>DOC_SOURCE_DIR</option>
+ is used to specify the location
+ of source directory which GTK-Doc searches for your API
+ documentation. This will usually be
+ <code>
+ DOC_SOURCE_DIR=$(top_srcdir)/src
+ </code>
+ or a sub-directory of that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HFILE_GLOB</option>
+ and
+ <option>CFILE_GLOB</option>
+ are used for dependencies. Each option take a file-glob (e.g.
+ <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
+ The documentation will be rebuilt if any of the matched files
+ change.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>EXTRA_HFILES</option>
+ allows to specify extra header files
+ to include when scanning for API documentation, which are not
+ found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
+ EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>IGNORE_HFILES</option>
+ allows to specify header files
+ or directories to ignore when scanning for API documentation.
+ Use the basename of the file or directory (e.g. <code>
+ IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>HTML_IMAGES</option>
+ allows to specify images files which
+ will be copied into the <filename>html/</filename> directory of
+ the generated documentation.
+ If your API documentation includes any images they need to be
+ added to this
+ option (e.g. <code>
+ HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>content_files</option>
+ allows to specify extra files
+ that are included by
+ <code>$(DOC_MAIN_SGML_FILE)</code>
+ (e.g. <code>
+ content_files=running.xml building.xml changes-2.0.xml</code>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>expand_content_files</option>
+ allows to specify files
+ where <emphasis>gtk-doc abbrevations</emphasis> such as
+ <code>#GtkWidget</code>
+ are expanded (e.g. <code>
+ expand_content_files=running.xml</code>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_autoconf">
+ <title>与autoconf集成</title>
+
+ <para>
+ Integration with <application>autoconf</application> is very simple
+ and includes one required step and an additional optional
+ (but recommended) step.
+
+ The first step is to add the <function>GTK_DOC_CHECK</function> macro
+ to your <filename>configure.ac</filename> script. This registers
+ several configure options to enable GTK-Doc and allows you
+ to set default arguments for <application>gtkdocize</application>.
+ </para>
+
+ <warning>
+ <simpara>
+ Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
+ The macro must start at the beginning of the line and should not
+ start with whitespace.
+ </simpara>
+ </warning>
+
+ <para>
+ The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
+ to your <filename>configure.ac</filename>. This is not required
+ but helps <application>gtkdocize</application> to automatically copy
+ the macro definition (e.g <filename>gtk-doc.m4</filename>) which
+ contains the <function>GTK_DOC_CHECK</function> macro to your
+ project's macro directory. Without this, the GTK_DOC_CHECK macro
+ might not be found and you would need to explicitly tell the
+ <application>aclocal</application> tool where to find the macro
+ definition file.
+ </para>
+
+ <para>
+ <example><title>Minimal integration with autoconf</title>
+ <programlisting><![CDATA[
+# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
]]></programlisting>
- </example>
- </para>
- <para>
- After all changes to <filename>configure.ac</filename> are made, update
- the <filename>configure</filename> file. This can be done by re-running
- <code>autoreconf -i</code> or <code>autogen.sh</code>.
- </para>
- </sect1>
+ </example>
+ </para>
- <sect1 id="settingup_automake">
- <title>与automake集成</title>
+ <para>
+ The above example works, but will require all developers to have
+ gtk-doc installed. A better way is to make building the documentation
+ optional as shown in the next example:
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub directory of the
- <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
- to your project's API documentation directory (
- <filename class="directory">./docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple doc-packages repeat this for each one.
- </para>
+ <example>
+ <title>Integration with optional gtk-doc dependency</title>
+ <programlisting><![CDATA[
+m4_ifdef([GTK_DOC_CHECK], [
+# recommended: set m4 directory
+AC_CONFIG_MACRO_DIR(m4)
+# optional: register gtk-doc in configure
+GTK_DOC_CHECK([1.28])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+]]></programlisting>
+ </example>
+ </para>
- <para>
- The next step is to edit the settings inside the <filename>Makefile.am</filename>.
- All the settings have a comment above that describes their purpose.
- Most settings are extra flags passed to the respective tools. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
- All the tools support <option>--help</option> to list the supported
- parameters.
- </para>
+ <para>
+ The first argument is used to check for the Gtk-Doc version at
+ configure time. The 2nd, optional argument is used by
+ <application>gtkdocize</application>.
+ The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
+ switches:
+ </para>
- <!-- FIXME: explain options ? -->
+ <orderedlist>
+ <listitem><para>--with-html-dir=PATH : 安装文档的路径</para></listitem>
+ <listitem><para>--enable-gtk-doc : 用gtk-doc构建文档［默认值：no］</para></listitem>
+ <listitem><para>--enable-gtk-doc-html :用html格式构建文档［默认值：yes］</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : 以PDF格式构建文档［默认值：no］</para></listitem>
+ </orderedlist>
- </sect1>
+ <important>
+ <para>GTK-Doc在默认情况下是关闭的！请记得给文本<filename>configure</filename>运作时传递<option>'--enable-gtk-doc'</option>选项。否则，将会安装预先生成的文档（对用户有意义但对开发人员没用处）。</para>
+ </important>
- <sect1 id="settingup_autogen">
- <title>与autogen集成</title>
+ <para>
+ After all changes to <filename>configure.ac</filename> are made,
+ update the <filename>configure</filename> file. This can be done by
+ re-running <code>autogen.sh</code>.
+ </para>
+ </sect2>
- <para>
- Most projects will have an <filename>autogen.sh</filename> script to
- setup the build infrastructure after a checkout from version control
- system (such as cvs/svn/git). GTK-Doc comes with a tool called
- <application>gtkdocize</application> which can be used in such a script.
- It should be run before autoheader, automake or autoconf.
- </para>
+ <sect2 id="settingup_autogen">
+ <title>与autogen集成</title>
- <para>
- <example><title>从autogen.sh中运行gtkdocize</title>
- <programlisting><![CDATA[
+ <para>
+ Most projects will have an <filename>autogen.sh</filename> script to
+ setup the build infrastructure after the project was checked out from
+ a version control system (such as git or svn). GTK-Doc comes with a
+ script called <application>gtkdocize</application> which can be used
+ to copy the necessary files needed by Gtk-Doc to the source directory.
+ </para>
+
+ <para>
+ It should be run before autoreconf, autoheader, automake or autoconf.
+ </para>
+
+ <para>
+ <example><title>从autogen.sh中运行gtkdocize</title>
+ <programlisting><![CDATA[
gtkdocize || exit 1
]]></programlisting>
- </example>
- </para>
+ </example>
+ </para>
- <para>
- When running <application>gtkdocize</application> it copies
- <filename>gtk-doc.make</filename> to your project root (or any directory
- specified by the <option>--docdir</option> option).
- It also checks you configure script for the <function>GTK_DOC_CHECK</function>
- invocation. This macro can be used to pass extra parameters to
- <application>gtkdocize</application>.
- </para>
+ <para>
+ <example>
+ <title>Conditionally run gtkdocize from autogen.sh</title>
+ <programlisting><![CDATA[
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test $? -ne 0; then
+ echo "No gtk-doc support found. You can't build the docs."
+else
+ $GTKDOCIZE || exit 1
+fi
+]]></programlisting>
+ </example>
+ </para>
- <para>
- Historically GTK-Doc was generating template files where developers entered the docs.
- This turned out to be not so good (e.g. the need for having generated
- files under version control).
- Since GTK-Doc 1.9 the tools can get all the information from source comments
- and thus the templates can be avoided. We encourage people to keep
- documentation in the code. <application>gtkdocize</application> supports now
- a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
- tmpl usage totally. Besides adding the option directly to the command
- invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
- or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
- If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
- please remove the directory (e.g. from version control system).
- </para>
- </sect1>
+ <para>
+ When running <application>gtkdocize</application> it copies
+ <filename>gtk-doc.make</filename> to your project root (or any
+ directory specified by the <option>--docdir</option> option).
+ </para>
- <sect1 id="settingup_firstrun">
- <title>运行文档构建</title>
+ <para>
+ <application>gtkdocize</application> checks your
+ <filename>configure.ac</filename> script for
+ the <function>GTK_DOC_CHECK</function> macro.
+ The <function>GTK_DOC_CHECK</function> macro can be used to pass
+ extra arguments to the <application>gtkdocize</application> script.
+ the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
+ </para>
- <para>
- After the previous steps it's time to run the build. First we need to
- rerun <filename>autogen.sh</filename>. If this script runs configure for
- you, then give it the <option>--enable-gtk-doc</option> option.
- Otherwise manually run <filename>configure</filename> with this option
- afterwards.
- </para>
- <para>
- The first make run generates several additional files in the doc-directories.
- The important ones are:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>.
- </para>
- <para>
- <example><title>运行文档构建</title>
- <programlisting><![CDATA[
+ <para>
+ Alternatively, additional arguments can also be passed to
+ <application>gtkdocize</application> via the
+ <function>GTKDOCIZE_FLAGS</function> environment variable, or by
+ directly specifying them to <application>gtkdocize</application>
+ in <filename>autogen.sh</filename>.
+ </para>
+
+ </sect2>
+
+ <sect2 id="settingup_firstrun">
+ <title>Executing GTK-Doc from the Build System</title>
+
+ <para>
+ After the previous steps it's time to run the build. First we need to
+ rerun <filename>autogen.sh</filename>. If this script runs configure
+ for you, then give it the <option>--enable-gtk-doc</option> option.
+ Otherwise manually run <filename>configure</filename> with this option
+ afterwards.
+ </para>
+ <para>
+ The first make run generates several additional files in the doc-directories.
+ The important ones are:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>.
+ </para>
+ <para>
+ <example><title>运行文档构建</title>
+ <programlisting><![CDATA[
./autogen.sh --enable-gtk-doc
make
]]></programlisting>
- </example>
- </para>
- <para>
- Now you can point your browser to <filename>docs/reference/<package>/index.html</filename>.
- Yes, it's a bit disappointing still. But hang-on, during the next chapter we
- tell you how to fill the pages with life.
- </para>
+ </example>
+ </para>
+
+ <para>
+ Now you can point your browser to
+ <filename>docs/reference/<package>/index.html</filename>.
+ With this initial setup you will only see a very simple document.
+ The next chapter will teach you how to add API documentation to your
+ code via special comment blocks. The Chapter afterwards introduces
+ <link linkend="metafiles">additional files</link> and shows how to
+ edit the <link linkend="metafiles_master">master template</link> to
+ add additional chapters and sections to your documentation files.
+ </para>
+
+ </sect2>
+
</sect1>
- <sect1 id="settingup_vcs">
- <title>与版本控制系统集成</title>
+ <sect1 id="settingup_cmake">
+ <title>Integration with CMake build systems</title>
<para>
- As a rule of thumb, it's the files you edit which should go under
- version control. For typical projects it's these files:
- <filename><package>.types</filename>,
- <filename><package>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>,
- <filename>Makefile.am</filename>.
+ GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
+ (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
+ module). This provides a <literal>gtk_doc_add_module</literal>
+ command that you can set in your <filename>CMakeLists.txt</filename>
+ file.
</para>
+
<para>
- Files in the <filename>xml/</filename> and <filename>html/</filename>
- directories should not go under version control. Neither should any of
- the <filename>.stamp</filename> files.
+ The following example shows how to use this command.
+ <example><title>Example of using GTK-Doc from CMake</title>
+ <programlisting><![CDATA[
+find_package(GtkDoc 1.25 REQUIRED)
+
+# Create the doc-libmeep target.
+gtk_doc_add_module(
+ libmeep ${CMAKE_SOURCE_DIR}/libmeep
+ XML meep-docs.xml
+ LIBRARIES libmeep
+)
+
+# Build doc-libmeep as part of the default target. Without this, you would
+# have to explicitly run something like `make doc-libmeep` to build the docs.
+add_custom_target(documentation ALL DEPENDS doc-libmeep)
+
+# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
+# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
+ DESTINATION ${CMAKE_INSTALL_DOCDIR})
+]]></programlisting>
+ </example>
</para>
</sect1>
- <sect1 id="plain_makefiles">
+ <sect1 id="settingup_plain_makefiles">
<title>与普通makefile或其它构建系统整合</title>
<para>
<para>您必须查阅<filename>Makefile.am</filename> 和 <filename>gtk-doc.mak</filename>以获取所须的额外选项。</para>
</sect1>
- <sect1 id="cmake">
- <title>Integration with CMake build systems</title>
-
- <para>
- GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
- (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
- module). This provides a <literal>gtk_doc_add_module</literal>
- command that you can set in your <filename>CMakeLists.txt</filename>
- file.
- </para>
-
- <para>
- The following example shows how to use this command.
- <example><title>Example of using GTK-Doc from CMake</title>
- <programlisting><![CDATA[
-find_package(GtkDoc 1.25 REQUIRED)
-
-# Create the doc-libmeep target.
-gtk_doc_add_module(
- libmeep ${CMAKE_SOURCE_DIR}/libmeep
- XML meep-docs.xml
- LIBRARIES libmeep
-)
+ <sect1 id="settingup_vcs">
+ <title>与版本控制系统集成</title>
-# Build doc-libmeep as part of the default target. Without this, you would
-# have to explicitly run something like `make doc-libmeep` to build the docs.
-add_custom_target(documentation ALL DEPENDS doc-libmeep)
+ <para>
+ As a rule of thumb, it's the files you edit which should go under
+ version control. For typical projects it's these files:
+ <filename><package>.types</filename>,
+ <filename><package>-docs.xml</filename> (in the past .sgml),
+ <filename><package>-sections.txt</filename>,
+ <filename>Makefile.am</filename>.
+ </para>
+ <para>
+ Files in the <filename>xml/</filename> and <filename>html/</filename>
+ directories should not go under version control. Neither should any of
+ the <filename>.stamp</filename> files.
+ </para>
+ </sect1>
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
-install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
- DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
- </sect1>
</chapter>
<chapter id="documenting">
syntax of the comments.
</para>
- <note>
- <title>文档位置</title>
- <para>在过去，多数文档不得不写入驻留在<filename>tmpl</filename>目录的文件中。这样会出现一些糟糕的情况：其信息常常没有更新，而且文件也倾向于与版本控制系统发生冲突。</para>
- <para>为避免上述的问题，我们建议把注释文档放入源代码中去。本手册仅描述此种编写代码文档的方法。</para>
- </note>
-
<para>
- The scanner can handle the majority of C headers fine. In the case of
- receiving warnings from the scanner that look like a special case, one can
- hint GTK-Doc to skip over them.
+ The GTK-Doc scanner can handle the majority of C headers fine. In the
+ case of receiving warnings from the scanner that look like a special
+ case, one can hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
</para>
<tip>
- <para>如早先所述，GTK-Doc是为编写公共的API而作的。所以你不能够为静态符号编写文档。尽管如此，它也可以很好地为那些符号作注释。这有助于他人理解你的代码。因此我们建议你用普通的注释来注释它们（不使用第一行的第二个'*'号）。如果以后函数须要作为public，你须做的只是在注释块中加入另一个 '*'号并且在区段文件里插入正确的标识符名称。</para>
+ <para>
+ As already mentioned earlier GTK-Doc is for documenting public API. Thus
+ one cannot write documentation for static symbols. Nevertheless it is good
+ to comment those symbols too. This helps other developers to understand
+ your code.
+ Therefore we recommend to comment these using normal comments (without the
+ 2nd '*' in the first line).
+ If later the function needs to be made public, all one needs to do is to
+ add another '*' in the comment block and insert the symbol name at the
+ right place inside the sections file.
+ </para>
</tip>
</sect1>
</para>
<para>
- <example><title>示例类型文件代码段</title>
+ <example><title>Example <package>.types file</title>
<programlisting><![CDATA[
#include <gtk/gtk.h>
containing entities for e.g. package_name and package_version. You can
use this e.g. in the main xml file to avoid hardcoding the version
number. Below is an example that shows how the entity file is included
- and how the entities are used. The entities can also be used in all
+ in the master template and how the entities are used.
+ The entities can also be used in all
generated files, GTK-Doc will use the same xml header in generated xml
files.
<example><title>Use pre-generated entities</title>
cat <<_LT_EOF >> "$cfgfile"
#! $SHELL
# Generated automatically by $as_me ($PACKAGE) $VERSION
+# Libtool was configured on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
# NOTE: Changes made to this file will be lost: look at ltmain.sh.
# Provide generalized library-building support services.
# before this can be enabled.
hardcode_into_libs=yes
+ # Add ABI-specific directories to the system library path.
+ sys_lib_dlsearch_path_spec="/lib64 /usr/lib64 /lib /usr/lib"
+
# Ideally, we could use ldconfig to report *all* directores which are
# searched for libraries, however this is still not possible. Aside from not
# being certain /sbin/ldconfig is available, command
# appending ld.so.conf contents (and includes) to the search path.
if test -f /etc/ld.so.conf; then
lt_ld_extra=`awk '/^include / { system(sprintf("cd /etc; cat %s 2>/dev/null", \[$]2)); skip = 1; } { if (!skip) print \[$]0; skip = 0; }' < /etc/ld.so.conf | $SED -e 's/#.*//;/^[ ]*hwcap[ ]/d;s/[:, ]/ /g;s/=[^=]*$//;s/=[^= ]* / /g;s/"//g;/^$/d' | tr '\n' ' '`
- sys_lib_dlsearch_path_spec="/lib /usr/lib $lt_ld_extra"
+ sys_lib_dlsearch_path_spec="$sys_lib_dlsearch_path_spec $lt_ld_extra"
fi
# We used to test for /lib/ld.so.1 and disable shared libraries on
dynamic_linker='GNU/Linux ld.so'
;;
-netbsdelf*-gnu)
- version_type=linux
- need_lib_prefix=no
- need_version=no
- library_names_spec='${libname}${release}${shared_ext}$versuffix ${libname}${release}${shared_ext}$major ${libname}${shared_ext}'
- soname_spec='${libname}${release}${shared_ext}$major'
- shlibpath_var=LD_LIBRARY_PATH
- shlibpath_overrides_runpath=no
- hardcode_into_libs=yes
- dynamic_linker='NetBSD ld.elf_so'
- ;;
-
netbsd*)
version_type=sunos
need_lib_prefix=no
lt_cv_deplibs_check_method=pass_all
;;
-netbsd* | netbsdelf*-gnu)
+netbsd*)
if echo __ELF__ | $CC -E - | $GREP __ELF__ > /dev/null; then
lt_cv_deplibs_check_method='match_pattern /lib[[^/]]+(\.so\.[[0-9]]+\.[[0-9]]+|_pic\.a)$'
else
;;
esac
;;
- netbsd* | netbsdelf*-gnu)
+ netbsd*)
;;
*qnx* | *nto*)
# QNX uses GNU C++, but need to define -shared option too, otherwise
;;
esac
;;
- linux* | k*bsd*-gnu | gnu*)
- _LT_TAGVAR(link_all_deplibs, $1)=no
- ;;
*)
_LT_TAGVAR(export_symbols_cmds, $1)='$NM $libobjs $convenience | $global_symbol_pipe | $SED '\''s/.* //'\'' | sort | uniq > $export_symbols'
;;
openbsd* | bitrig*)
with_gnu_ld=no
;;
- linux* | k*bsd*-gnu | gnu*)
- _LT_TAGVAR(link_all_deplibs, $1)=no
- ;;
esac
_LT_TAGVAR(ld_shlibs, $1)=yes
fi
;;
- netbsd* | netbsdelf*-gnu)
+ netbsd*)
if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then
_LT_TAGVAR(archive_cmds, $1)='$LD -Bshareable $libobjs $deplibs $linker_flags -o $lib'
wlarc=
if test yes = "$lt_cv_irix_exported_symbol"; then
_LT_TAGVAR(archive_expsym_cmds, $1)='$CC -shared $pic_flag $libobjs $deplibs $compiler_flags $wl-soname $wl$soname `test -n "$verstring" && func_echo_all "$wl-set_version $wl$verstring"` $wl-update_registry $wl$output_objdir/so_locations $wl-exports_file $wl$export_symbols -o $lib'
fi
- _LT_TAGVAR(link_all_deplibs, $1)=no
else
_LT_TAGVAR(archive_cmds, $1)='$CC -shared $libobjs $deplibs $compiler_flags -soname $soname `test -n "$verstring" && func_echo_all "-set_version $verstring"` -update_registry $output_objdir/so_locations -o $lib'
_LT_TAGVAR(archive_expsym_cmds, $1)='$CC -shared $libobjs $deplibs $compiler_flags -soname $soname `test -n "$verstring" && func_echo_all "-set_version $verstring"` -update_registry $output_objdir/so_locations -exports_file $export_symbols -o $lib'
esac
;;
- netbsd* | netbsdelf*-gnu)
+ netbsd*)
if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then
_LT_TAGVAR(archive_cmds, $1)='$LD -Bshareable -o $lib $libobjs $deplibs $linker_flags' # a.out
else
if BUILD_TESTS
TESTS = \
- check.py common.py mk_to_db.py \
- tools.sh gobject.sh bugs.sh annotations.sh fail.sh empty.sh sanity.sh \
- program.sh
+ check.py common.py mk_to_db.py mkhtml2.py \
+ tools.sh \
+ annotations.sh bugs.sh empty.sh fail.sh gobject.sh program.sh
+
TESTS_ENVIRONMENT = \
BUILDDIR=$(abs_builddir) \
SRCDIR=$(abs_srcdir) \
PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
GLIB_PREFIX="$(glib_prefix)"
+
TEST_EXTENSIONS = .py
PY_LOG_COMPILER = $(PYTHON)
+
endif
EXTRA_DIST = gtkdoctest.sh $(TESTS)
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# maybe move it to a subdir?
SUBDIRS = annotations bugs empty fail gobject program repro .
@BUILD_TESTS_TRUE@TESTS = \
-@BUILD_TESTS_TRUE@ check.py common.py mk_to_db.py \
-@BUILD_TESTS_TRUE@ tools.sh gobject.sh bugs.sh annotations.sh fail.sh empty.sh sanity.sh \
-@BUILD_TESTS_TRUE@ program.sh
+@BUILD_TESTS_TRUE@ check.py common.py mk_to_db.py mkhtml2.py \
+@BUILD_TESTS_TRUE@ tools.sh \
+@BUILD_TESTS_TRUE@ annotations.sh bugs.sh empty.sh fail.sh gobject.sh program.sh
@BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \
@BUILD_TESTS_TRUE@ BUILDDIR=$(abs_builddir) \
--log-file $$b.log --trs-file $$b.trs \
$(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \
"$$tst" $(AM_TESTS_FD_REDIRECT)
-gobject.sh.log: gobject.sh
- @p='gobject.sh'; \
- b='gobject.sh'; \
+annotations.sh.log: annotations.sh
+ @p='annotations.sh'; \
+ b='annotations.sh'; \
$(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \
--log-file $$b.log --trs-file $$b.trs \
$(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \
--log-file $$b.log --trs-file $$b.trs \
$(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \
"$$tst" $(AM_TESTS_FD_REDIRECT)
-annotations.sh.log: annotations.sh
- @p='annotations.sh'; \
- b='annotations.sh'; \
+empty.sh.log: empty.sh
+ @p='empty.sh'; \
+ b='empty.sh'; \
$(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \
--log-file $$b.log --trs-file $$b.trs \
$(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \
--log-file $$b.log --trs-file $$b.trs \
$(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \
"$$tst" $(AM_TESTS_FD_REDIRECT)
-empty.sh.log: empty.sh
- @p='empty.sh'; \
- b='empty.sh'; \
- $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \
- --log-file $$b.log --trs-file $$b.trs \
- $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \
- "$$tst" $(AM_TESTS_FD_REDIRECT)
-sanity.sh.log: sanity.sh
- @p='sanity.sh'; \
- b='sanity.sh'; \
+gobject.sh.log: gobject.sh
+ @p='gobject.sh'; \
+ b='gobject.sh'; \
$(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \
--log-file $$b.log --trs-file $$b.trs \
$(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \
#!/bin/sh
-gtkdoctest.sh annotations
+set -e
+gtkdoctest.sh annotations
+sanity.sh annotations
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
if BUILD_TESTS
TESTS_ENVIRONMENT = \
DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
- PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
- PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
endif
-include $(top_srcdir)/git.mk
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
@BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \
@BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
-@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
-@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
all: all-am
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
#!/bin/sh
-gtkdoctest.sh bugs
+set -e
+gtkdoctest.sh bugs
+sanity.sh bugs
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
if BUILD_TESTS
TESTS_ENVIRONMENT = \
DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
- PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
- PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
endif
-include $(top_srcdir)/git.mk
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
@BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \
@BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
-@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
-@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
all: all-am
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
#!/bin/sh
+set -e
+
if ! grep -q ^GtkDocTestIf$ empty/docs/tester-sections.txt; then
echo "Test for bug https://bugzilla.gnome.org/show_bug.cgi?id=705633 has failed."
exit 1
fi
gtkdoctest.sh empty
-
+sanity.sh empty
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
if BUILD_TESTS
TESTS_ENVIRONMENT = \
DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
- PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
- PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
endif
CLEANFILES += \
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
@BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \
@BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
-@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
-@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
all: all-am
<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
]>
-<book id="index">
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>&package_name; Reference Manual</title>
<releaseinfo>
<chapter>
<title>[Insert title here]</title>
- <xi:include href="xml/tester.xml"/>
-
+ <xi:include href="xml/tester.xml"/>
</chapter>
<chapter id="object-tree">
<title>Object Hierarchy</title>
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
if BUILD_TESTS
TESTS_ENVIRONMENT = \
DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
- PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
- PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
endif
-include $(top_srcdir)/git.mk
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
@BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \
@BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
-@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
-@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
all: all-am
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
#!/bin/sh
-gtkdoctest.sh gobject
+set -e
+gtkdoctest.sh gobject
+sanity.sh gobject
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
if BUILD_TESTS
TESTS_ENVIRONMENT = \
DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
- PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
- PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
endif
-include $(top_srcdir)/git.mk
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
@BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \
@BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
-@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
-@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
all: all-am
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
- <title>&package_name; Reference Manual</title>
+ <title>&package_name; Reference Manual</title>
<corpauthor>
The <ulink url="http://www.gtk.org/gtk-doc">gtk-doc team</ulink>.
</corpauthor>
</footnote>
</para>
</preface>
-
+
<part label="1" id="part.i">
<title>Overview</title>
<chapter id="Overview-building">
<title>Index of new API in 0.5</title>
<xi:include href="xml/api-index-0.5.xml"><xi:fallback /></xi:include>
</index>
-
+
<glossary id="glossary">
<title>Glossary</title>
<glossdiv><title>A</title>
</glossentry>
</glossdiv>
</glossary>
-
+
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</part>
</book>
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
*
* Just incase you wonder, special caracters can be escaped with a \ like in \%
* or \# or even \@.
+ *
+ * We also support verbatim spans - lets test escaping of a `<tag>` block.
*/
/**
* SECTION:iface2
*
* This is a section with a heading without a trailing hash mark.
*
- * > Do not confuse the GtkUIManager UI Definitions described here with
- * > the similarly named <link linkend="BUILDER-UI">GtkBuilder UI
- * > Definitions</link>.
+ * > This is a bloclquote with a link to <link linkend="GtkdocObject2">
+ * > GtkdocObject2</link>.
*
* > Single line quote
*
output = md_to_db.MarkDownParse(input_, "")
self.assertEqual(expected, output)
+ def test_verbatim(self):
+ input_ = "a `<child>` element"
+ expected = '<para>a <literal><child></literal> element</para>\n'
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
def test_code(self):
input_ = """\
|[<!-- language="C" -->
--- /dev/null
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2018 Stefan Sauer
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+
+import logging
+import unittest
+
+from lxml import etree
+
+from gtkdoc import mkhtml2
+
+
+class TestChunking(unittest.TestCase):
+
+ def setUp(self):
+ logging.basicConfig(
+ level=logging.INFO,
+ format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s')
+
+ def test_chunk_only_root_gives_single_chunk(self):
+ root = etree.XML('<book />')
+ files = mkhtml2.chunk(root, 'test')
+ self.assertEqual('book', files.name)
+ self.assertEqual(0, len(files.descendants))
+
+ def test_chunk_single_chapter_gives_two_chunks(self):
+ root = etree.XML('<book><chapter /></book>')
+ files = mkhtml2.chunk(root, 'test')
+ descendants = [f for f in files.descendants if f.anchor is None]
+ logging.info('descendants : %s', str(descendants))
+ self.assertEqual(1, len(descendants))
+
+ def test_chunk_first_sect1_is_inlined(self):
+ root = etree.XML('<book><chapter><sect1 /></chapter></book>')
+ files = mkhtml2.chunk(root, 'test')
+ descendants = [f for f in files.descendants if f.anchor is None]
+ logging.info('descendants : %s', str(descendants))
+ self.assertEqual(1, len(descendants))
+
+ def test_chunk_second_sect1_is_not_inlined(self):
+ root = etree.XML('<book><chapter><sect1 /><sect1 /></chapter></book>')
+ files = mkhtml2.chunk(root, 'test')
+ descendants = [f for f in files.descendants if f.anchor is None]
+ logging.info('descendants : %s', str(descendants))
+ self.assertEqual(2, len(descendants))
+
+
+if __name__ == '__main__':
+ unittest.main()
#!/bin/sh
-gtkdoctest.sh program
+set -e
+gtkdoctest.sh program
+sanity.sh program
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
if BUILD_TESTS
TESTS_ENVIRONMENT = \
DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
- PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
- PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
endif
-include $(top_srcdir)/git.mk
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
@BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \
@BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
-@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
-@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
all: all-am
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
if BUILD_TESTS
TESTS_ENVIRONMENT = \
DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
- PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
- PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
endif
CLEANFILES += \
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
@BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \
@BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
-@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
-@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH)
all: all-am
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
-runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
+++ /dev/null
-#!/bin/sh
-
-dir=$BUILDDIR
-#`dirname $0`
-suite="sanity"
-
-failed=0
-tested=0
-
-echo "Running suite(s): gtk-doc-$suite";
-
-# check the presence and non-emptyness of certain files
-nok=0
-for path in $dir/*/docs/html; do
- if test ! -s $path/index.html ; then
- echo 1>&2 "no or empty $path/index.html"
- nok=`expr $nok + 1`; break;
- fi
- if test ! -s $path/home.png ; then
- echo 1>&2 "no or empty $path/home.png"
- nok=`expr $nok + 1`; break;
- fi
- file=`echo $path/*.devhelp2`
- if test ! -s $file ; then
- echo 1>&2 "no or empty $file"
- nok=`expr $nok + 1`; break;
- fi
-done
-if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
-tested=`expr $tested + 1`
-
-# TODO: if we have pdf support check for ./tests/*/docs/tester.pdf
-nok=0
-for path in $dir/*/docs; do
- if test ! -s $path/tester.pdf ; then
- if test -s $path/gtkdoc-mkpdf.log; then
- if ! grep >/dev/null 2>&1 "must be installed to use gtkdoc-mkpdf" $path/gtkdoc-mkpdf.log; then
- echo 1>&2 "no or empty $path/tester.pdf"
- nok=`expr $nok + 1`; break;
- fi
- fi
- fi
-done
-if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
-tested=`expr $tested + 1`
-
-# check validity of generated xml files
-nok=0
-for file in $dir/*/docs/xml/*.xml; do
- xmllint --noout --noent $file
- if test $? != 0 ; then
- echo 1>&2 "xml validity check failed for $file"
- nok=`expr $nok + 1`;
- fi
-done
-if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
-tested=`expr $tested + 1`
-
-
-# check validity of generated sgml files
-nok=0
-for file in $dir/*/docs/xml/*.sgml; do
- xmllint --noout --noent $file
- if test $? != 0 ; then
- echo 1>&2 "sgml validity check failed for $file"
- nok=`expr $nok + 1`;
- fi
-done
-if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
-tested=`expr $tested + 1`
-
-# check validity of devhelp2 files
-nok=0
-for file in $dir/*/docs/html/*.devhelp2; do
- xmllint --noout --nonet --schema $ABS_TOP_SRCDIR/devhelp2.xsd $file
- if test $? != 0 ; then
- echo 1>&2 "devhelp2 xml validity check failed for $file"
- nok=`expr $nok + 1`;
- fi
-done
-if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
-tested=`expr $tested + 1`
-
-# check that log files have only one line (the command)
-# discard references to launchapd bugs
-nok=0
-DISCARD_PATTERN='Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/[0-9]* . For now run:
-gunzip .*.gz
-
-'
-for file in $dir/*/docs/gtkdoc-*.log; do
- # skip this in verbose mode as we'll have more text
- if test "x${V}" = "x1"; then
- continue
- fi
-
- expected_lines="1"
- # adjust for known files
- if test $file = "$dir/fail/docs/gtkdoc-mkdb.log"; then
- expected_lines="16"
- fi
- if test $file = "$dir/bugs/docs/gtkdoc-mkdb.log"; then
- expected_lines="2"
- fi
- if test $file = "$dir/gobject/docs/gtkdoc-fixxref.log"; then
- expected_lines="2"
- fi
- case $file in
- *gtkdoc-fixxref.log)
- # if there is no /usr/share/gtk-doc/html/gobject we should skip fixxref logs
- if test ! -d "$GLIB_PREFIX/share/gtk-doc/html/gobject"; then
- continue
- fi
- ;;
- esac
-
- lines=`grep -v -x -G -e "$DISCARD_PATTERN" $file | wc -l | cut -d' ' -f1`
- if test $lines -gt $expected_lines; then
- echo 1>&2 "expected no more than $expected_lines log line in $file, but got $lines"
- nok=`expr $nok + 1`;
- fi
-done
-if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
-tested=`expr $tested + 1`
-
-# check stability of generated xml/html
-nok=0
-for path in $dir/*/docs*; do
- if test -d $path/xml.ref; then
- diff -u $path/xml.ref $path/xml
- if test $? = 1 ; then
- echo 1>&2 "difference in generated xml for $path"
- nok=`expr $nok + 1`;
- fi
- fi
- if test -d $path/html.ref; then
- diff -u $path/html.ref $path/html
- if test $? = 1 ; then
- echo 1>&2 "difference in generated html for $path"
- nok=`expr $nok + 1`;
- fi
- fi
-done
-if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
-tested=`expr $tested + 1`
-
-
-# summary
-successes=`expr $tested - $failed`
-rate=`expr 100 \* $successes / $tested`;
-echo "$rate %: Checks $tested, Failures: $failed"
-
-test $failed = 0
-exit $?
# test python scripts
# TODO: also test the module files
-# TODO: test python 2 and 3 (python3 -mcompileall gtkdoc/*.py)
-for file in gtkdoc-check gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase gtkdoc-scangobj; do
+for file in gtkdoc-check gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkhtml2 gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase gtkdoc-scangobj; do
fullfile=`which $file`
- /usr/bin/python -m py_compile $fullfile
+ /usr/bin/python3 -m py_compile $fullfile
if test $? != 0 ; then failed=`expr $failed + 1`; fi
tested=`expr $tested + 1`
done
# test python scripts
# TODO: also test the module files
-# TODO: test python 2 and 3 (python3 -mcompileall gtkdoc/*.py)
-for file in gtkdoc-check gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase gtkdoc-scangobj; do
+for file in gtkdoc-check gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkhtml2 gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase gtkdoc-scangobj; do
fullfile=`which $file`
@PYTHON@ -m py_compile $fullfile
if test $? != 0 ; then failed=`expr $failed + 1`; fi
projects / platform / upstream / gtk-doc.git / commitdiff