-Stefan Kost
+Stefan Sauer
Email: ensonic@hora-obscura.de
Userid: stefkost
Userid: matthiasc
-Note that several people are contributing to gtk-doc, and some parts of it
+Note that several people are contributing to gtk-doc, and some parts of it
are technically maintained by other people. The people listed above are
meant as contacts for administrative questions. Other questions are best
directed to the mailing list gtk-doc-list@gnome.org.
bin_SCRIPTS = \
gtkdoc-check \
+ gtkdoc-depscan \
gtkdoc-fixxref \
gtkdoc-mkdb \
gtkdoc-mkhtml \
gtkdoc-mkman \
- gtkdoc-mkpdf \
- gtkdoc-mktmpl \
+ gtkdoc-mkpdf \
gtkdoc-rebase \
gtkdoc-scan \
gtkdoc-scangobj \
gtkdocize
-if HAVE_PYTHON
-bin_SCRIPTS += \
- gtkdoc-depscan
-endif
-
gtkdocdatadir = $(datadir)/gtk-doc/data
gtkdocdata_DATA = \
- gtkdoc-common.pl \
- gtk-doc.dsl \
- gtk-doc.dcl \
gtk-doc.xsl \
version-greater-or-equal.xsl \
devhelp2.xsd \
devhelp2.xsl \
gtk-doc.make \
- gtk-doc.notmpl.make \
gtk-doc.flat.make \
- gtk-doc.notmpl-flat.make \
style/home.png \
style/left.png \
style/left-insensitive.png \
style/up-insensitive.png \
style/style.css
+pylibdatadir = $(datadir)/gtk-doc/python/gtkdoc
+pylibdata_DATA = \
+ gtkdoc/__init__.py \
+ gtkdoc/check.py \
+ gtkdoc/common.py \
+ gtkdoc/config.py \
+ gtkdoc/fixxref.py \
+ gtkdoc/md_to_db.py \
+ gtkdoc/mkdb.py \
+ gtkdoc/mkhtml.py \
+ gtkdoc/mkman.py \
+ gtkdoc/mkpdf.py \
+ gtkdoc/rebase.py \
+ gtkdoc/scan.py \
+ gtkdoc/scangobj.py
+
pkgconfigdir = $(datadir)/pkgconfig
pkgconfig_DATA = gtk-doc.pc
aclocaldir = $(datadir)/aclocal
aclocal_DATA = gtk-doc.m4
-sgmldir = $(datadir)/sgml/gtk-doc
-sgml_DATA = gtk-doc.cat
-
gtk-doc.flat.make: gtk-doc.make
@$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@
-gtk-doc.notmpl-flat.make: gtk-doc.notmpl.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.spec.in \
- gtk-doc.spec \
gtk-doc-fo.xsl \
- gtk-doc.cat.in \
doc/README \
doc/authors.txt \
doc/gnome.txt \
doc/sections-file.txt \
doc/setting-up.txt \
doc/style-guide.txt \
- db2man/README \
- db2man/docbook-to-man \
- db2man/docbook-to-man.ts \
examples/README \
examples/Makefile.am \
tools/docpercentages.pl \
CLEANFILES = \
gtk-doc.flat.make \
- gtk-doc.notmpl-flat.make \
- gtkdoc-depscanc
-
+ gtkdoc-checkc \
+ gtkdoc-depscanc \
+ gtkdoc-fixxrefc \
+ gtkdoc-mkdbc \
+ gtkdoc-mkhtmlc \
+ gtkdoc-mkmanc \
+ gtkdoc-mkpdfc \
+ gtkdoc-rebasec \
+ gtkdoc-scangobjc \
+ gtkdoc/__init__.pyc \
+ gtkdoc/check.pyc \
+ gtkdoc/common.pyc \
+ gtkdoc/config.pyc \
+ gtkdoc/fixxref.pyc \
+ gtkdoc/md_to_db.pyc \
+ gtkdoc/mkdb.pyc \
+ gtkdoc/mkhtml.pyc \
+ gtkdoc/mkman.pyc \
+ gtkdoc/mkpdf.pyc \
+ gtkdoc/rebase.pyc \
+ gtkdoc/scan.pyc \
+ gtkdoc/scangobj.pyc
+
DISTCLEANFILES = \
- gtk-doc.cat \
gtkdoc-check \
- gtkdoc-common.pl \
gtkdoc-depscan \
- gtk-doc.dsl \
gtkdoc-fixxref \
gtkdocize \
gtkdoc-mkdb \
gtkdoc-mkhtml \
gtkdoc-mkman \
gtkdoc-mkpdf \
- gtkdoc-mktmpl \
gtk-doc.pc \
gtkdoc-rebase \
gtkdoc-scangobj \
gtkdoc-scan \
- gtk-doc.spec
-
+ gtkdoc/config.py
MAINTAINERCLEANFILES = \
$(GITIGNORE_MAINTAINERCLEANFILES_TOPLEVEL) \
RELNOTES.txt \
ChangeLog-?.?? \
gtk-doc-*.tar.xz \
- build-aux
+ build-aux \
+ __pycache__ gtkdoc/__pycache__ tests/__pycache__
-include $(top_srcdir)/git.mk
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
-@HAVE_PYTHON_TRUE@am__append_1 = \
-@HAVE_PYTHON_TRUE@ gtkdoc-depscan
-
subdir = .
DIST_COMMON = INSTALL NEWS README AUTHORS ChangeLog \
$(srcdir)/Makefile.in $(srcdir)/Makefile.am \
$(top_srcdir)/configure $(am__configure_deps) \
- $(srcdir)/gtk-doc.pc.in $(srcdir)/gtk-doc.dsl.in \
- $(srcdir)/gtk-doc.spec.in $(srcdir)/gtk-doc.cat.in \
- $(srcdir)/gtkdoc-common.pl.in $(srcdir)/gtkdoc-check.in \
- $(srcdir)/gtkdoc-depscan.in $(srcdir)/gtkdoc-fixxref.in \
- $(srcdir)/gtkdoc-mkdb.in $(srcdir)/gtkdoc-mkhtml.in \
- $(srcdir)/gtkdoc-mkman.in $(srcdir)/gtkdoc-mkpdf.in \
- $(srcdir)/gtkdoc-mktmpl.in $(srcdir)/gtkdoc-rebase.in \
+ $(srcdir)/gtk-doc.pc.in $(top_srcdir)/gtkdoc/config.py.in \
+ $(srcdir)/gtkdoc-check.in $(srcdir)/gtkdoc-depscan.in \
+ $(srcdir)/gtkdoc-fixxref.in $(srcdir)/gtkdoc-mkdb.in \
+ $(srcdir)/gtkdoc-mkhtml.in $(srcdir)/gtkdoc-mkman.in \
+ $(srcdir)/gtkdoc-mkpdf.in $(srcdir)/gtkdoc-rebase.in \
$(srcdir)/gtkdoc-scan.in $(srcdir)/gtkdoc-scangobj.in \
$(srcdir)/gtkdocize.in COPYING TODO build-aux/compile \
build-aux/config.guess build-aux/config.sub build-aux/depcomp \
am__CONFIG_DISTCLEAN_FILES = config.status config.cache config.log \
configure.lineno config.status.lineno
mkinstalldirs = $(install_sh) -d
-CONFIG_CLEAN_FILES = gtk-doc.pc gtk-doc.dsl gtk-doc.spec gtk-doc.cat \
- gtkdoc-common.pl gtkdoc-check gtkdoc-depscan gtkdoc-fixxref \
- gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkman gtkdoc-mkpdf \
- gtkdoc-mktmpl gtkdoc-rebase gtkdoc-scan gtkdoc-scangobj \
- gtkdocize
+CONFIG_CLEAN_FILES = gtk-doc.pc gtkdoc/config.py gtkdoc-check \
+ gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml \
+ gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase gtkdoc-scan \
+ gtkdoc-scangobj gtkdocize
CONFIG_CLEAN_VPATH_FILES =
am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
am__vpath_adj = case $$p in \
}
am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" \
"$(DESTDIR)$(gtkdocdatadir)" "$(DESTDIR)$(pkgconfigdir)" \
- "$(DESTDIR)$(sgmldir)"
+ "$(DESTDIR)$(pylibdatadir)"
SCRIPTS = $(bin_SCRIPTS)
AM_V_P = $(am__v_P_@AM_V@)
am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
*) (install-info --version) >/dev/null 2>&1;; \
esac
DATA = $(aclocal_DATA) $(gtkdocdata_DATA) $(pkgconfig_DATA) \
- $(sgml_DATA)
+ $(pylibdata_DATA)
RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \
distclean-recursive maintainer-clean-recursive
am__recursive_targets = \
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
top_srcdir = @top_srcdir@
ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
SUBDIRS = cmake help tests
-bin_SCRIPTS = gtkdoc-check gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml \
- gtkdoc-mkman gtkdoc-mkpdf gtkdoc-mktmpl gtkdoc-rebase \
- gtkdoc-scan gtkdoc-scangobj gtkdocize $(am__append_1)
+bin_SCRIPTS = \
+ gtkdoc-check \
+ gtkdoc-depscan \
+ gtkdoc-fixxref \
+ gtkdoc-mkdb \
+ gtkdoc-mkhtml \
+ gtkdoc-mkman \
+ gtkdoc-mkpdf \
+ gtkdoc-rebase \
+ gtkdoc-scan \
+ gtkdoc-scangobj \
+ gtkdocize
+
gtkdocdatadir = $(datadir)/gtk-doc/data
gtkdocdata_DATA = \
- gtkdoc-common.pl \
- gtk-doc.dsl \
- gtk-doc.dcl \
gtk-doc.xsl \
version-greater-or-equal.xsl \
devhelp2.xsd \
devhelp2.xsl \
gtk-doc.make \
- gtk-doc.notmpl.make \
gtk-doc.flat.make \
- gtk-doc.notmpl-flat.make \
style/home.png \
style/left.png \
style/left-insensitive.png \
style/up-insensitive.png \
style/style.css
+pylibdatadir = $(datadir)/gtk-doc/python/gtkdoc
+pylibdata_DATA = \
+ gtkdoc/__init__.py \
+ gtkdoc/check.py \
+ gtkdoc/common.py \
+ gtkdoc/config.py \
+ gtkdoc/fixxref.py \
+ gtkdoc/md_to_db.py \
+ gtkdoc/mkdb.py \
+ gtkdoc/mkhtml.py \
+ gtkdoc/mkman.py \
+ gtkdoc/mkpdf.py \
+ gtkdoc/rebase.py \
+ gtkdoc/scan.py \
+ gtkdoc/scangobj.py
+
pkgconfigdir = $(datadir)/pkgconfig
pkgconfig_DATA = gtk-doc.pc
aclocaldir = $(datadir)/aclocal
aclocal_DATA = gtk-doc.m4
-sgmldir = $(datadir)/sgml/gtk-doc
-sgml_DATA = gtk-doc.cat
EXTRA_DIST = \
MAINTAINERS \
$(gtkdocdata_DATA) \
+ $(pylibdata_DATA) \
gtk-doc.pc.in \
gtk-doc.m4 \
gtk-doc.doap \
- gtk-doc.spec.in \
- gtk-doc.spec \
gtk-doc-fo.xsl \
- gtk-doc.cat.in \
doc/README \
doc/authors.txt \
doc/gnome.txt \
doc/sections-file.txt \
doc/setting-up.txt \
doc/style-guide.txt \
- db2man/README \
- db2man/docbook-to-man \
- db2man/docbook-to-man.ts \
examples/README \
examples/Makefile.am \
tools/docpercentages.pl \
CLEANFILES = \
gtk-doc.flat.make \
- gtk-doc.notmpl-flat.make \
- gtkdoc-depscanc
+ gtkdoc-checkc \
+ gtkdoc-depscanc \
+ gtkdoc-fixxrefc \
+ gtkdoc-mkdbc \
+ gtkdoc-mkhtmlc \
+ gtkdoc-mkmanc \
+ gtkdoc-mkpdfc \
+ gtkdoc-rebasec \
+ gtkdoc-scangobjc \
+ gtkdoc/__init__.pyc \
+ gtkdoc/check.pyc \
+ gtkdoc/common.pyc \
+ gtkdoc/config.pyc \
+ gtkdoc/fixxref.pyc \
+ gtkdoc/md_to_db.pyc \
+ gtkdoc/mkdb.pyc \
+ gtkdoc/mkhtml.pyc \
+ gtkdoc/mkman.pyc \
+ gtkdoc/mkpdf.pyc \
+ gtkdoc/rebase.pyc \
+ gtkdoc/scan.pyc \
+ gtkdoc/scangobj.pyc
DISTCLEANFILES = \
- gtk-doc.cat \
gtkdoc-check \
- gtkdoc-common.pl \
gtkdoc-depscan \
- gtk-doc.dsl \
gtkdoc-fixxref \
gtkdocize \
gtkdoc-mkdb \
gtkdoc-mkhtml \
gtkdoc-mkman \
gtkdoc-mkpdf \
- gtkdoc-mktmpl \
gtk-doc.pc \
gtkdoc-rebase \
gtkdoc-scangobj \
gtkdoc-scan \
- gtk-doc.spec
+ gtkdoc/config.py
MAINTAINERCLEANFILES = \
$(GITIGNORE_MAINTAINERCLEANFILES_TOPLEVEL) \
RELNOTES.txt \
ChangeLog-?.?? \
gtk-doc-*.tar.xz \
- build-aux
+ build-aux \
+ __pycache__ gtkdoc/__pycache__ tests/__pycache__
all: all-recursive
$(am__aclocal_m4_deps):
gtk-doc.pc: $(top_builddir)/config.status $(srcdir)/gtk-doc.pc.in
cd $(top_builddir) && $(SHELL) ./config.status $@
-gtk-doc.dsl: $(top_builddir)/config.status $(srcdir)/gtk-doc.dsl.in
- cd $(top_builddir) && $(SHELL) ./config.status $@
-gtk-doc.spec: $(top_builddir)/config.status $(srcdir)/gtk-doc.spec.in
- cd $(top_builddir) && $(SHELL) ./config.status $@
-gtk-doc.cat: $(top_builddir)/config.status $(srcdir)/gtk-doc.cat.in
- cd $(top_builddir) && $(SHELL) ./config.status $@
-gtkdoc-common.pl: $(top_builddir)/config.status $(srcdir)/gtkdoc-common.pl.in
+gtkdoc/config.py: $(top_builddir)/config.status $(top_srcdir)/gtkdoc/config.py.in
cd $(top_builddir) && $(SHELL) ./config.status $@
gtkdoc-check: $(top_builddir)/config.status $(srcdir)/gtkdoc-check.in
cd $(top_builddir) && $(SHELL) ./config.status $@
cd $(top_builddir) && $(SHELL) ./config.status $@
gtkdoc-mkpdf: $(top_builddir)/config.status $(srcdir)/gtkdoc-mkpdf.in
cd $(top_builddir) && $(SHELL) ./config.status $@
-gtkdoc-mktmpl: $(top_builddir)/config.status $(srcdir)/gtkdoc-mktmpl.in
- cd $(top_builddir) && $(SHELL) ./config.status $@
gtkdoc-rebase: $(top_builddir)/config.status $(srcdir)/gtkdoc-rebase.in
cd $(top_builddir) && $(SHELL) ./config.status $@
gtkdoc-scan: $(top_builddir)/config.status $(srcdir)/gtkdoc-scan.in
@list='$(pkgconfig_DATA)'; test -n "$(pkgconfigdir)" || list=; \
files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \
dir='$(DESTDIR)$(pkgconfigdir)'; $(am__uninstall_files_from_dir)
-install-sgmlDATA: $(sgml_DATA)
+install-pylibdataDATA: $(pylibdata_DATA)
@$(NORMAL_INSTALL)
- @list='$(sgml_DATA)'; test -n "$(sgmldir)" || list=; \
+ @list='$(pylibdata_DATA)'; test -n "$(pylibdatadir)" || list=; \
if test -n "$$list"; then \
- echo " $(MKDIR_P) '$(DESTDIR)$(sgmldir)'"; \
- $(MKDIR_P) "$(DESTDIR)$(sgmldir)" || exit 1; \
+ echo " $(MKDIR_P) '$(DESTDIR)$(pylibdatadir)'"; \
+ $(MKDIR_P) "$(DESTDIR)$(pylibdatadir)" || 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)$(sgmldir)'"; \
- $(INSTALL_DATA) $$files "$(DESTDIR)$(sgmldir)" || exit $$?; \
+ echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pylibdatadir)'"; \
+ $(INSTALL_DATA) $$files "$(DESTDIR)$(pylibdatadir)" || exit $$?; \
done
-uninstall-sgmlDATA:
+uninstall-pylibdataDATA:
@$(NORMAL_UNINSTALL)
- @list='$(sgml_DATA)'; test -n "$(sgmldir)" || list=; \
+ @list='$(pylibdata_DATA)'; test -n "$(pylibdatadir)" || list=; \
files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \
- dir='$(DESTDIR)$(sgmldir)'; $(am__uninstall_files_from_dir)
+ dir='$(DESTDIR)$(pylibdatadir)'; $(am__uninstall_files_from_dir)
# This directory's subdirectories are mostly independent; you can cd
# into them and run 'make' without going through this Makefile.
all-am: Makefile $(SCRIPTS) $(DATA)
installdirs: installdirs-recursive
installdirs-am:
- for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" "$(DESTDIR)$(gtkdocdatadir)" "$(DESTDIR)$(pkgconfigdir)" "$(DESTDIR)$(sgmldir)"; do \
+ for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" "$(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-sgmlDATA
+ install-pkgconfigDATA install-pylibdataDATA
install-dvi: install-dvi-recursive
uninstall-am: uninstall-aclocalDATA uninstall-binSCRIPTS \
uninstall-gtkdocdataDATA uninstall-pkgconfigDATA \
- uninstall-sgmlDATA
+ uninstall-pylibdataDATA
.MAKE: $(am__recursive_targets) install-am install-strip
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-sgmlDATA 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 uninstall-am \
- uninstall-binSCRIPTS uninstall-gtkdocdataDATA \
- uninstall-pkgconfigDATA uninstall-sgmlDATA
+ 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 \
+ uninstall-am uninstall-binSCRIPTS uninstall-gtkdocdataDATA \
+ uninstall-pkgconfigDATA uninstall-pylibdataDATA
gtk-doc.flat.make: gtk-doc.make
@$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@
-gtk-doc.notmpl-flat.make: gtk-doc.notmpl.make
- @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@
-
-include $(top_srcdir)/git.mk
dist-hook:
+GTK-Doc 1.26 (Aug 11 2017)
+==============
+
+Remove tmpl support (gtkdoc-mktmpl). Port all tools from bash/perl to python.
+
+ Changes
+
+ o 773879 : – scangobj: Do not generate unused parameters
+ o 780789 : Convert gtkdoc-scan from Perl to Python
+ o 752126 : Add support for inline program documentation
+ o 753052 : _() causes element a: validity error : ID idx already defined
+ o 758137 : GtkLabel and GtkShortcutsShortcut notes on escaping character entities don't render properly
+ o 764407 : Broken links to structs in function definitions
+ o 764543 : /usr/bin/gtkdoc-mkpdf always exits with an error
+ o 768675 : make check fails on master
+ o 769125 : gtkdoc-mkhtml/pdf fails on spaces in search path
+ o 769341 : gtkdoc-mkdb line 3966 triggers " Negative repeat count does nothing " warnings
+ o 771255 : " Symbol name not found at the start of comment block " warning with " attributes " annotation.
+ o 773151 : configure: Lower perl dependency to 5.16.0
+ o 774168 : gobject introspection annotations and gtk-doc parser do not agree
+ o 774812 : Error messages from xsltproc are hidden by gtkdoc-mkhtml
+ o 778144 : Allow disabling introspection for ancillary property mechanisms
+ o 779566 : Replace shell executables with Python
+
+ Contributors
+
+ Anders Jonsson
+ Bernhard M. Wiedemann
+ Carlos Garcia Campos
+ Christian Kirbach
+ Daniel Mustieles
+ Emmanuele Bassi
+ Ernestas Kulik
+ HorimotoYasuhiro
+ Jussi Pakkanen
+ Kalev Lember
+ Marek Černocký
+ Mario Blättermann
+ Marius Vlad
+ Marvin Schmidt
+ Nirbheek Chauhan
+ Philip Withnall
+ Rafael Fontenelle
+ Sam Thursfield
+ Sebastian Rasmussen
+ Simon Josefsson
+ Stefan Sauer
+ Thomas Wood
+ Ting-Wei Lan
+ Tom Tryfonidis
+ Víctor Manuel Jáquez Leal
+
GTK-Doc 1.25 (Mar 21 2016)
==============
o 706404 : Minor bug in gtkdoc-mkdb
o 706438 : Empty lines added at the beginning and at the end of a programlisting
o 707426 : master is broken in picking up flavour from configure.ac
- o 707717 : Support " Deprecated: X.Y "
+ o 707717 : Support " Deprecated: X.Y "
o 708268 : New *-insensitive.png files are not distributes
o 710478 : gtkdoc-mkdb: Don't complain about annotations with hyphen
o 711111 : gtkdoc-mkdb: sort entries in the glossary
o 671960 : make dist fails without html/*
o 672710 : Use new documentation infrastructure
o 676685 : Allow to order functions without using $MODULE-sections.txt
- o 685365 : (PATCH) Fix contents of warning message, should be " -sections.txt " not " -section.txt "
+ o 685365 : (PATCH) Fix contents of warning message, should be " -sections.txt " not " -section.txt "
o 686148 : [patch] suggested parameters for gtkdoc-scangobj
o 687685 : 'g_type_init' is deprecated
o 688204 : undocumented enum values missing in indexes
o gtk-doc does not generate old devhelp files any more. This cuts down doc
generation time and works for devhelp >=0.11 (was released in 2005).
o changes for out-of-source dir build caused breakage for projects using
- DOC_SOURCE_DIR with a relative path (to builddir). It is recommended to use
+ DOC_SOURCE_DIR with a relative path (to builddir). It is recommended to use
DOC_SOURCE_DIR=$(top_srcdir)/src/xxx.
Changes
o 512155 : gets confused by multiline typedef
o 568711 : undocumented enum values are not reported
o 590602 : secondly running gtkdoc-mkdb will generate DOCTYPE missing XML files
- o 590625 : $(DOC_MODULE)-overrides.txt is required by " make dist "
+ o 590625 : $(DOC_MODULE)-overrides.txt is required by " make dist "
o 591975 : Section_Id always embeds a trailing newline
o 604885 : Fix the use of gtkdocize --flavour option
o 604992 : gtkdoc-fixxref broken link warning is broken for functions
o 609194 : sort interface implementers
o 610255 : Self-test failure in git as of 2010-02-17: FAIL: gobject.sh
o 610257 : Patch to make GTK-DOC notice functions/variables with 'signed' prototypes
- o 611848 : gtk-doc produces invalid DocBook markup if the SECTION ends with a tag that cannot be nested inside < para >
+ o 611848 : gtk-doc produces invalid DocBook markup if the SECTION ends with a tag that cannot be nested inside < para >
Contributors
o 552822 : Add rules to create $(REPORT_FILES)
o 553407 : Example Makefile.am uses obsolete INCLUDES instead of AM_...
o 554718 : gtk-doc needs to allow versioned TARGET_DIR
- o 554833 : Be more careful with " struct _ < struct_name > "
+ o 554833 : Be more careful with " struct _ < struct_name > "
o 558082 : evince docs build fails with GTK_DISABLE_SINGLE_INCLUDES
o 559281 : Correct check for existance of gtkdoc-rebase
-
+
Contributors
Behdad Esfahbod
o 379466 : Improve C parser to handle TYPE\nVARIABLE in function pro...
o 380824 : docs are truncated if line begins with '* returns '
o 383456 : ' make check ' test for 100% documentation
- o 411739 : Gtk-doc fails to handle ' struct tm * function_name (); '
+ o 411739 : Gtk-doc fails to handle ' struct tm * function_name (); '
o 415388 : Please clean -undocumented.txt files
o 418027 : gtkdoc-mkdb does not handle #ifdef in enum {}
o 419997 : parameter name trouble
o 459725 : ' jhbuild build gtk-doc ' fails on make
o 460127 : parsing nested union/structs confuses public/private state
o 465365 : [PATCH] gtk-doc does not compile
- o 466559 : [CSS] styling <hr />;
+ o 466559 : [CSS] styling <hr />;
o 471014 : G_CONST_RETURN * G_CONST_RETURN * function not picked up
o 477532 : function variables
o 479913 : gtk-doc.notmpl.make is not distributed
o Emit "Since:" information for signals and properties.
o Added derived subclasses and interfaces to the widget hierarchies.
o Added .cat SGML catalog file.
- o Support properties on interfaces.
+ o Support properties on interfaces.
o Added "--help" options to the scripts.
GTK-Doc 0.10 (Nov 14 2002)
============
- o --output-format option to select whether SGML or XML is generated.
+ o --output-format option to select whether SGML or XML is generated.
o Use openjade or jade when converting SGML to HTML.
o Use xsltproc to convert XML to HTML, with a new look.
o In XML mode, support XIncludes as an alternative to entities.
- o In XML mode, create .devhelp files.
+ o In XML mode, create .devhelp files.
o List interfaces in the object hierarchy.
o Create docs for signals on interfaces.
o Generate links between interface and their implementations and
prerequisites.
o Create docs for child and style properties.
o Use blurbs for property documentation.
- o Allow inline documentation for signals and properties.
+ o Allow inline documentation for signals and properties.
to document the signals and properties of GTK+ widgets and GObject classes
which other tools may not have.
-GTK-Doc allows your documentation to be written in 2 ways:
- a) Embedded inside the source code in specially-formatted comments.
- or
- b) Added to the 'template' files which gtk-doc outputs after scanning all
- the header files and parsing the declarations (deprecated now).
-
-From these source code comments and template files GTK-Doc generates a Docbook
-XML (or SGML) document, which is then transformed into HTML.
+From your source code comments GTK-Doc generates a Docbook XML document, which
+is then transformed into HTML and/or PDF.
The generated HTML documentation can be browsed in an ordinary web browser or
by using the special Devhelp API browser
(see http://developer.imendio.com/wiki/Devhelp).
-Please don't use template files in new projects. Support for for those will
-be removed at some point in the future (together with gtkdoc-mktmpl). Please
-also use DoxBook XML instead of DocBook SGML.
+Please use DoxBook XML instead of DocBook SGML - support for the later will be
+dropped.
Requirements
============
-Perl v5 - the main scripts are in Perl.
- http://www.perl.com/
+Python 2.7, 3.x - the secondary scripts are written in Python
+ http:///www.python.org
+Python-six - for python 2,3 compatibility
For XML output (recommended):
http://xmlsoft.org/
-For SGML output (not actively maintained any more):
-
-The DocBook SGML DTD.
- http://www.oasis-open.org/docbook/
-
-Jade v1.1 or OpenJade 1.3.1.
- http://www.jclark.com/jade
- http://sourceforge.net/projects/openjade
-
-The DocBook DSSSL Stylesheets (I've got 1.40, but v1.19+ may be OK).
- 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.
- http://docbook.sourceforge.net/projects/dsssl/
-
-
Most distributions now have packages for all of these, so I would strongly
advise that you grab those.
file
* we need to check if this works well for all kind of _types (e.g. boxed)
https://bugzilla.gnome.org/show_bug.cgi?id=605025
-
+
== -section.txt ==
https://bugzilla.gnome.org/show_bug.cgi?id=646094
* using SCAN_OPTION="--rebuild-sections" can be used to use the audogenerated
sections file
-* when scanning a header file, everything of the header and the respective .c
+* when scanning a header file, everything of the header and the respective .c
file will be put to one section
* symbols can be hidden using __GTK_DOC_IGNORE__
= Running =
gtk-doc is using a makefile with several targets to get from sources to docs. It
uses makefile variables for configuration.
-It might be easier to have a gtk-doc tool that can run the other gtk-doc tools
+It might be easier to have a gtkdoc tool that can run the other gtkdoc tools
in the right order (ev. by importing them as modules). This could handle a few
things nicer that the makefiles don't do well. This would also make it easy to
run it manually or integrate into other build systems.
+= Intermediate files =
+Can we change the intermediate files into a perl-module? So that all we need to
+do is to import it. Ideally we have just one outfile for each tool:
+gtkdoc-scan -> scan.pm (decl.txt, decl-list.txt, types.txt, sections.txt)
+gtkdoc-scangobj -> scanobj.pm (interfacs, prerequisites, ...)
+
+Can we drop the decl-list.txt file (or rename to make sure this is what a
+generated section.txt would look like)
+
= Issues =
* gtkdoc-fixxref makefile targets use $HTML_DIR
* HTML_DIR: The directory where gtk-doc generated documentation is installed
GtkDocConfig.cmake \
GtkDocConfigVersion.cmake \
GtkDocScanGObjWrapper.cmake
+
+-include $(top_srcdir)/git.mk
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
uninstall-am uninstall-cmakeDATA
+-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:
#! /bin/sh
# Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.69 for gtk-doc 1.25.
+# Generated by GNU Autoconf 2.69 for gtk-doc 1.26.
#
# 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.25'
-PACKAGE_STRING='gtk-doc 1.25'
+PACKAGE_VERSION='1.26'
+PACKAGE_STRING='gtk-doc 1.26'
PACKAGE_BUGREPORT='http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc'
PACKAGE_URL=''
-ac_unique_file="gtkdoc-common.pl.in"
+ac_unique_file="gtk-doc.pc.in"
# Factoring default headers for most tests.
ac_includes_default="\
#include <stdio.h>
GTK_DOC_USE_LIBTOOL_TRUE
TEST_DEPS_LIBS
TEST_DEPS_CFLAGS
+PYTHON_PACKAGE_DIR
PACKAGE_DATA_DIR
HIGHLIGHT_OPTIONS
HIGHLIGHT
FOP
DBLATEX
XSLTPROC
-HAVE_PYTHON_FALSE
-HAVE_PYTHON_TRUE
pkgpyexecdir
pyexecdir
pkgpythondir
PYTHON_PREFIX
PYTHON_VERSION
PYTHON
-PERL
PKG_CONFIG_LIBDIR
PKG_CONFIG_PATH
PKG_CONFIG
# 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.25 to adapt to many kinds of systems.
+\`configure' configures gtk-doc 1.26 to adapt to many kinds of systems.
Usage: $0 [OPTION]... [VAR=VALUE]...
if test -n "$ac_init_help"; then
case $ac_init_help in
- short | recursive ) echo "Configuration of gtk-doc 1.25:";;
+ short | recursive ) echo "Configuration of gtk-doc 1.26:";;
esac
cat <<\_ACEOF
test -n "$ac_init_help" && exit $ac_status
if $ac_init_version; then
cat <<\_ACEOF
-gtk-doc configure 1.25
+gtk-doc configure 1.26
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.25, which was
+It was created by gtk-doc $as_me 1.26, which was
generated by GNU Autoconf 2.69. Invocation command line was
$ $0 $@
# Define the identity of the package.
PACKAGE='gtk-doc'
- VERSION='1.25'
+ VERSION='1.26'
cat >>confdefs.h <<_ACEOF
fi
fi
-# Extract the first word of "perl", so it can be a program name with args.
-set dummy perl; ac_word=$2
-{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
-$as_echo_n "checking for $ac_word... " >&6; }
-if ${ac_cv_path_PERL+:} false; then :
- $as_echo_n "(cached) " >&6
-else
- case $PERL in
- [\\/]* | ?:[\\/]*)
- ac_cv_path_PERL="$PERL" # Let the user override the test with a path.
- ;;
- *)
- as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
-for as_dir in $PATH
-do
- IFS=$as_save_IFS
- test -z "$as_dir" && as_dir=.
- for ac_exec_ext in '' $ac_executable_extensions; do
- if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
- ac_cv_path_PERL="$as_dir/$ac_word$ac_exec_ext"
- $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
- break 2
- fi
-done
- done
-IFS=$as_save_IFS
-
- ;;
-esac
-fi
-PERL=$ac_cv_path_PERL
-if test -n "$PERL"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: $PERL" >&5
-$as_echo "$PERL" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
-fi
-
-
-if test -z "$PERL"; then
- as_fn_error $? "perl not found" "$LINENO" 5
-fi
-
-{ $as_echo "$as_me:${as_lineno-$LINENO}: checking if Perl version >= 5.18.0" >&5
-$as_echo_n "checking if Perl version >= 5.18.0... " >&6; }
-if "$PERL" -e "require v5.18.0"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: yes" >&5
-$as_echo "yes" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
- as_fn_error $? "perl >= 5.18.0 is required for gtk-doc" "$LINENO" 5
-fi
-
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.3" >&5
-$as_echo_n "checking whether $PYTHON version is >= 2.3... " >&6; }
+ { $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; }
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.3'.split('.'))) + [0, 0, 0]
+minver = list(map(int, '2.7'.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.3" >&5
-$as_echo_n "checking for a Python interpreter with version >= 2.3... " >&6; }
+ { $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; }
if ${am_cv_pathless_PYTHON+:} false; then :
$as_echo_n "(cached) " >&6
else
# 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.3'.split('.'))) + [0, 0, 0]
+minver = list(map(int, '2.7'.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]
if test "$PYTHON" = :; then
- :
+ as_fn_error $? "no suitable Python interpreter found" "$LINENO" 5
else
fi
- if test "$PYTHON" != :; then
- HAVE_PYTHON_TRUE=
- HAVE_PYTHON_FALSE='#'
-else
- HAVE_PYTHON_TRUE='#'
- HAVE_PYTHON_FALSE=
-fi
-
# Extract the first word of "xsltproc", so it can be a program name with args.
set dummy xsltproc; ac_word=$2
test "$prefix_NONE" && prefix=NONE
test "$exec_prefix_NONE" && exec_prefix=NONE
+PYTHON_PACKAGE_DIR="${datadir}/${PACKAGE}/python"
+
+ prefix_NONE=
+ exec_prefix_NONE=
+ test "x$prefix" = xNONE && prefix_NONE=yes && prefix=$ac_default_prefix
+ test "x$exec_prefix" = xNONE && exec_prefix_NONE=yes && exec_prefix=$prefix
+ eval ac_define_dir="\"$PYTHON_PACKAGE_DIR\""
+ eval ac_define_dir="\"$ac_define_dir\""
+ PYTHON_PACKAGE_DIR="$ac_define_dir"
+
+ test "$prefix_NONE" && prefix=NONE
+ test "$exec_prefix_NONE" && exec_prefix=NONE
+
if test "x$GCC" = "xyes"; then
if test -z "`echo "$CFLAGS" | grep "\-Wall" 2> /dev/null`" ; then
fi
-ac_config_files="$ac_config_files Makefile gtk-doc.pc gtk-doc.dsl gtk-doc.spec gtk-doc.cat gtkdoc-common.pl cmake/Makefile cmake/GtkDocConfig.cmake cmake/GtkDocConfigVersion.cmake help/Makefile help/manual/Makefile tests/Makefile tests/gobject/Makefile tests/gobject/src/Makefile tests/gobject/docs/Makefile tests/bugs/Makefile tests/bugs/src/Makefile tests/bugs/docs/Makefile tests/annotations/Makefile tests/annotations/src/Makefile tests/annotations/docs/Makefile tests/fail/Makefile tests/fail/src/Makefile tests/fail/docs/Makefile tests/empty/Makefile tests/empty/src/Makefile tests/empty/docs/Makefile"
+ac_config_files="$ac_config_files Makefile gtk-doc.pc cmake/Makefile cmake/GtkDocConfig.cmake cmake/GtkDocConfigVersion.cmake gtkdoc/config.py help/Makefile help/manual/Makefile tests/Makefile tests/gobject/Makefile tests/gobject/src/Makefile tests/gobject/docs/Makefile tests/bugs/Makefile tests/bugs/src/Makefile tests/bugs/docs/Makefile tests/annotations/Makefile tests/annotations/src/Makefile tests/annotations/docs/Makefile tests/fail/Makefile tests/fail/src/Makefile tests/fail/docs/Makefile tests/empty/Makefile tests/empty/src/Makefile tests/empty/docs/Makefile tests/program/Makefile tests/program/src/Makefile tests/program/docs/Makefile"
ac_config_files="$ac_config_files gtkdoc-check"
ac_config_files="$ac_config_files gtkdoc-mkpdf"
-ac_config_files="$ac_config_files gtkdoc-mktmpl"
-
ac_config_files="$ac_config_files gtkdoc-rebase"
ac_config_files="$ac_config_files gtkdoc-scan"
as_fn_error $? "conditional \"am__fastdepCC\" was never defined.
Usually this means the macro was only invoked conditionally." "$LINENO" 5
fi
-if test -z "${HAVE_PYTHON_TRUE}" && test -z "${HAVE_PYTHON_FALSE}"; then
- as_fn_error $? "conditional \"HAVE_PYTHON\" was never defined.
-Usually this means the macro was only invoked conditionally." "$LINENO" 5
-fi
if test -z "${GTK_DOC_USE_LIBTOOL_TRUE}" && test -z "${GTK_DOC_USE_LIBTOOL_FALSE}"; then
as_fn_error $? "conditional \"GTK_DOC_USE_LIBTOOL\" was never defined.
Usually this means the macro was only invoked conditionally." "$LINENO" 5
# 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.25, which was
+This file was extended by gtk-doc $as_me 1.26, 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.25
+gtk-doc config.status 1.26
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" ;;
- "gtk-doc.dsl") CONFIG_FILES="$CONFIG_FILES gtk-doc.dsl" ;;
- "gtk-doc.spec") CONFIG_FILES="$CONFIG_FILES gtk-doc.spec" ;;
- "gtk-doc.cat") CONFIG_FILES="$CONFIG_FILES gtk-doc.cat" ;;
- "gtkdoc-common.pl") CONFIG_FILES="$CONFIG_FILES gtkdoc-common.pl" ;;
"cmake/Makefile") CONFIG_FILES="$CONFIG_FILES cmake/Makefile" ;;
"cmake/GtkDocConfig.cmake") CONFIG_FILES="$CONFIG_FILES cmake/GtkDocConfig.cmake" ;;
"cmake/GtkDocConfigVersion.cmake") CONFIG_FILES="$CONFIG_FILES 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" ;;
"tests/Makefile") CONFIG_FILES="$CONFIG_FILES tests/Makefile" ;;
"tests/empty/Makefile") CONFIG_FILES="$CONFIG_FILES tests/empty/Makefile" ;;
"tests/empty/src/Makefile") CONFIG_FILES="$CONFIG_FILES tests/empty/src/Makefile" ;;
"tests/empty/docs/Makefile") CONFIG_FILES="$CONFIG_FILES tests/empty/docs/Makefile" ;;
+ "tests/program/Makefile") CONFIG_FILES="$CONFIG_FILES tests/program/Makefile" ;;
+ "tests/program/src/Makefile") CONFIG_FILES="$CONFIG_FILES tests/program/src/Makefile" ;;
+ "tests/program/docs/Makefile") CONFIG_FILES="$CONFIG_FILES tests/program/docs/Makefile" ;;
"gtkdoc-check") CONFIG_FILES="$CONFIG_FILES gtkdoc-check" ;;
"gtkdoc-depscan") CONFIG_FILES="$CONFIG_FILES gtkdoc-depscan" ;;
"gtkdoc-fixxref") CONFIG_FILES="$CONFIG_FILES gtkdoc-fixxref" ;;
"gtkdoc-mkhtml") CONFIG_FILES="$CONFIG_FILES gtkdoc-mkhtml" ;;
"gtkdoc-mkman") CONFIG_FILES="$CONFIG_FILES gtkdoc-mkman" ;;
"gtkdoc-mkpdf") CONFIG_FILES="$CONFIG_FILES gtkdoc-mkpdf" ;;
- "gtkdoc-mktmpl") CONFIG_FILES="$CONFIG_FILES gtkdoc-mktmpl" ;;
"gtkdoc-rebase") CONFIG_FILES="$CONFIG_FILES gtkdoc-rebase" ;;
"gtkdoc-scan") CONFIG_FILES="$CONFIG_FILES gtkdoc-scan" ;;
"gtkdoc-scangobj") CONFIG_FILES="$CONFIG_FILES gtkdoc-scangobj" ;;
"gtkdoc-mkhtml":F) chmod +x gtkdoc-mkhtml ;;
"gtkdoc-mkman":F) chmod +x gtkdoc-mkman ;;
"gtkdoc-mkpdf":F) chmod +x gtkdoc-mkpdf ;;
- "gtkdoc-mktmpl":F) chmod +x gtkdoc-mktmpl ;;
"gtkdoc-rebase":F) chmod +x gtkdoc-rebase ;;
"gtkdoc-scan":F) chmod +x gtkdoc-scan ;;
"gtkdoc-scangobj":F) chmod +x gtkdoc-scangobj ;;
gtk-doc was configured with the following options:
==================================================" >&6;}
-test "$PYTHON" != : \
- && { $as_echo "$as_me:${as_lineno-$LINENO}: ** Python based tools enabled, using $PYTHON" >&5
-$as_echo "$as_me: ** Python based tools enabled, using $PYTHON" >&6;} \
- || { $as_echo "$as_me:${as_lineno-$LINENO}: Python based tools disabled" >&5
-$as_echo "$as_me: Python based tools disabled" >&6;}
test -n "$DBLATEX$FOP" \
- && { $as_echo "$as_me:${as_lineno-$LINENO}: ** XML PDF support enabled, using $DBLATEX$FOP" >&5
-$as_echo "$as_me: ** XML PDF support enabled, using $DBLATEX$FOP" >&6;} \
- || { $as_echo "$as_me:${as_lineno-$LINENO}: XML PDF support disabled, no dblatex or fop available" >&5
-$as_echo "$as_me: XML PDF support disabled, no dblatex or fop available" >&6;}
+ && { $as_echo "$as_me:${as_lineno-$LINENO}: ** PDF support enabled, using $DBLATEX$FOP" >&5
+$as_echo "$as_me: ** PDF support enabled, using $DBLATEX$FOP" >&6;} \
+ || { $as_echo "$as_me:${as_lineno-$LINENO}: PDF support disabled, no dblatex or fop available" >&5
+$as_echo "$as_me: PDF support disabled, no dblatex or fop available" >&6;}
test -n "$HIGHLIGHT" \
&& { $as_echo "$as_me:${as_lineno-$LINENO}: ** Syntax highlighting of examples enabled, using $HIGHLIGHT" >&5
$as_echo "$as_me: ** Syntax highlighting of examples enabled, using $HIGHLIGHT" >&6;} \
dnl Makefile can only cope with that, i.e. use 1.1, 1.2, 1.3 ... 9.9.
dnl FIXME: I can't see anything failing (1.14.1), lets try to use a three digit
dnl number for the development version
-m4_define(gtk_doc_version, 1.25)
+m4_define(gtk_doc_version, 1.26)
AC_INIT([gtk-doc],[gtk_doc_version],[http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc],[gtk-doc])
AC_CONFIG_MACRO_DIR([m4])
-AC_CONFIG_SRCDIR([gtkdoc-common.pl.in])
+AC_CONFIG_SRCDIR([gtk-doc.pc.in])
AC_CONFIG_AUX_DIR([build-aux])
AM_INIT_AUTOMAKE([1.11 check-news std-options -Wno-portability tar-ustar no-dist-gzip dist-xz])
dnl Make sure we have pkg-config >= 0.19, so installing in $(datadir) is OK.
PKG_PROG_PKG_CONFIG([0.19])
-dnl
-dnl Check for Perl.
-dnl
-AC_PATH_PROG([PERL], [perl])
-if test -z "$PERL"; then
- AC_MSG_ERROR([perl not found])
-fi
-
-AC_MSG_CHECKING([if Perl version >= 5.18.0])
-if "$PERL" -e "require v5.18.0"; then
- AC_MSG_RESULT([yes])
-else
- AC_MSG_RESULT([no])
- AC_MSG_ERROR([perl >= 5.18.0 is required for gtk-doc])
-fi
-
dnl
dnl Check for Python.
dnl
-AM_PATH_PYTHON([2.3],,[:])
-AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
+AM_PATH_PYTHON([2.7])
dnl
dnl Check for xsltproc
AC_SUBST([HIGHLIGHT_OPTIONS])
dnl
-dnl Set PACKAGE_DATA_DIR so we can find the script containing common routines.
+dnl Set runtime package dirs so we can find the script containing common routines.
dnl
dnl From Autoconf Macro Archive:
m4_define([AC_DEFINE_DIR], [
])
PACKAGE_DATA_DIR="${datadir}/${PACKAGE}/data"
AC_DEFINE_DIR([PACKAGE_DATA_DIR], [PACKAGE_DATA_DIR])
+PYTHON_PACKAGE_DIR="${datadir}/${PACKAGE}/python"
+AC_DEFINE_DIR([PYTHON_PACKAGE_DIR], [PYTHON_PACKAGE_DIR])
dnl Only use -Wall if we have gcc
if test "x$GCC" = "xyes"; then
]
)
AM_CONDITIONAL(GTK_DOC_USE_LIBTOOL, test -n "$LIBTOOL" -a x$gtk_doc_use_libtool = xyes )
-dnl this enable the rule in test/Makefile.am
+dnl this enables the rule in test/Makefile.am
AM_CONDITIONAL(BUILD_TESTS, test x$build_tests = xyes)
AC_SUBST(glib_prefix)
AC_CONFIG_FILES([Makefile
gtk-doc.pc
-gtk-doc.dsl
-gtk-doc.spec
-gtk-doc.cat
-gtkdoc-common.pl
cmake/Makefile
cmake/GtkDocConfig.cmake
cmake/GtkDocConfigVersion.cmake
+gtkdoc/config.py
help/Makefile
help/manual/Makefile
tests/Makefile
tests/empty/Makefile
tests/empty/src/Makefile
tests/empty/docs/Makefile
+tests/program/Makefile
+tests/program/src/Makefile
+tests/program/docs/Makefile
])
dnl run chmod on these after parsing them.
AC_CONFIG_FILES([gtkdoc-check], [chmod +x gtkdoc-check])
AC_CONFIG_FILES([gtkdoc-depscan], [chmod +x gtkdoc-depscan])
AC_CONFIG_FILES([gtkdoc-fixxref], [chmod +x gtkdoc-fixxref])
-dnl that would be nice, but would fail if perl is in a non-std path
-dnl AC_CONFIG_FILES([gtkdoc-mkdb], [chmod +x gtkdoc-mkdb && perl -cwT gtkdoc-mkdb])
AC_CONFIG_FILES([gtkdoc-mkdb], [chmod +x gtkdoc-mkdb])
AC_CONFIG_FILES([gtkdoc-mkhtml], [chmod +x gtkdoc-mkhtml])
AC_CONFIG_FILES([gtkdoc-mkman], [chmod +x gtkdoc-mkman])
AC_CONFIG_FILES([gtkdoc-mkpdf], [chmod +x gtkdoc-mkpdf])
-AC_CONFIG_FILES([gtkdoc-mktmpl], [chmod +x gtkdoc-mktmpl])
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])
gtk-doc was configured with the following options:
==================================================])
-test "$PYTHON" != : \
- && AC_MSG_NOTICE([** Python based tools enabled, using $PYTHON]) \
- || AC_MSG_NOTICE([ Python based tools disabled])
test -n "$DBLATEX$FOP" \
- && AC_MSG_NOTICE([** XML PDF support enabled, using $DBLATEX$FOP]) \
- || AC_MSG_NOTICE([ XML PDF support disabled, no dblatex or fop available])
+ && AC_MSG_NOTICE([** PDF support enabled, using $DBLATEX$FOP]) \
+ || AC_MSG_NOTICE([ PDF support disabled, no dblatex or fop available])
test -n "$HIGHLIGHT" \
&& AC_MSG_NOTICE([** Syntax highlighting of examples enabled, using $HIGHLIGHT]) \
|| AC_MSG_NOTICE([ Syntax highlighting of examples disabled])
+++ /dev/null
-
-FILES
-=====
-
-docbook-to-man
- my customized version of the docbook-to-man script. Note that it has
- paths in it that you may need to change.
- I also used the PROLOG stuff to specify the DocBook DTD when passing
- the man pages to instant.
-
-docbook-to-man.ts
- my customized version of the instant 'translation spec'.
- I added support for the central title at the top of the pages, and the
- revision date at the end. I also converted section 1 headings to all caps.
\ No newline at end of file
+++ /dev/null
-#!/bin/sh
-#############################################################################
-#
-# docbook-to-man.sh
-#
-#############################################################################
-#
-# Copyright (c) 1996 X Consortium
-# Copyright (c) 1996 Dalrymple Consulting
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# X CONSORTIUM OR DALRYMPLE CONSULTING BE LIABLE FOR ANY CLAIM, DAMAGES OR
-# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-# OTHER DEALINGS IN THE SOFTWARE.
-#
-# Except as contained in this notice, the names of the X Consortium and
-# Dalrymple Consulting shall not be used in advertising or otherwise to
-# promote the sale, use or other dealings in this Software without prior
-# written authorization.
-#
-#############################################################################
-#
-# Written 5/29/96 by Fred Dalrymple
-#
-#############################################################################
-
-# ***** change the following paths if your installation of nsgmls and / or
-# ***** DocBook isn't into the default places.
-
-ROOT=/usr
-SGMLS=$ROOT/lib/sgml
-DOCBOOK=$SGMLS/davenport
-
-
-# ***** modify the following line (to "=false") if you're not using the
-# ***** Elan Documentor's Workbench
-
-doElanPSInclude=false
-
-
-
-# Everything below this line should be pretty standard and not require
-# modification.
-
-#ulimit -c unlimited
-
-PARSER=nsgmls
-INSTANT=instant
-INSTANT_OPT=-d
-
-#CATALOG=$DOCBOOK/docbook.cat
-CATALOG=/etc/sgml.catalog
-DECL=$DOCBOOK/docbook.dcl
-
-error=false
-
-if [ $# -eq 1 ]
-then INSTANCE=$1
-else error=true
-fi
-
-if `$error`
-then echo "usage: docbook-to-man docbook-instance"
- exit 1
-fi
-
-if `$doElanPSInclude`
-then cat > /tmp/dtm.$$.psinc <<\!
-...\" $Header$
-...\"
-...\" transcript compatibility for postscript use.
-...\"
-...\" synopsis: .P! <file.ps>
-...\"
-.de P!
-\\&.
-.fl \" force out current output buffer
-\\!%PB
-\\!/showpage{}def
-...\" the following is from Ken Flowers -- it prevents dictionary overflows
-\\!/tempdict 200 dict def tempdict begin
-.fl \" prolog
-.sy cat \\$1\" bring in postscript file
-...\" the following line matches the tempdict above
-\\!end % tempdict %
-\\!PE
-\\!.
-.sp \\$2u \" move below the image
-..
-!
-else cat > /tmp/dtm.$$.psinc <<\!
-...\" $Header$
-...\"
-...\" transcript compatibility for postscript use.
-...\"
-...\" synopsis: .P! <file.ps>
-...\"
-.de P!
-.fl
-\!!1 setgray
-.fl
-\\&.\"
-.fl
-\!!0 setgray
-.fl \" force out current output buffer
-\!!save /psv exch def currentpoint translate 0 0 moveto
-\!!/showpage{}def
-.fl \" prolog
-.sy sed -e 's/^/!/' \\$1\" bring in postscript file
-\!!psv restore
-.
-!
-fi
-
-cat >> /tmp/dtm.$$.psinc <<\!
-.de pF
-.ie \a\\*(f1\a\a .ds f1 \\n(.f
-.el .ie \a\\*(f2\a\a .ds f2 \\n(.f
-.el .ie \a\\*(f3\a\a .ds f3 \\n(.f
-.el .ie \a\\*(f4\a\a .ds f4 \\n(.f
-.el .tm ? font overflow
-.ft \\$1
-..
-.de fP
-.ie !\a\\*(f4\a\a \{\
-. ft \\*(f4
-. ds f4\"
-' br \}
-.el .ie !\a\\*(f3\a\a \{\
-. ft \\*(f3
-. ds f3\"
-' br \}
-.el .ie !\a\\*(f2\a\a \{\
-. ft \\*(f2
-. ds f2\"
-' br \}
-.el .ie !\a\\*(f1\a\a \{\
-. ft \\*(f1
-. ds f1\"
-' br \}
-.el .tm ? font underflow
-..
-.ds f1\"
-.ds f2\"
-.ds f3\"
-.ds f4\"
-!
-
-
-cat > /tmp/dtm.$$.prolog <<!
-<!DOCTYPE RefEntry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
-<!ENTITY npzwc "">
-]>
-!
-
-(cat /tmp/dtm.$$.psinc;
- $PARSER -gl -wno-idref -m$CATALOG $DECL /tmp/dtm.$$.prolog $INSTANCE |
- $INSTANT $INSTANT_OPT -croff.cmap -sroff.sdata -tdocbook-to-man.ts)
-
-#(cat /tmp/dtm.$$.psinc;
-# $PARSER -gl -wno-idref -m$CATALOG $DECL $INSTANCE |
-# $INSTANT $INSTANT_OPT -croff.cmap -sroff.sdata -tdocbook-to-man.ts)
-
-rm -f /tmp/dtm.$$.psinc
-rm -f /tmp/dtm.$$.prolog
+++ /dev/null
-#############################################################################
-#
-# docbook-to-man.ts
-#
-#############################################################################
-#
-# Copyright (c) 1996 X Consortium
-# Copyright (c) 1996 Dalrymple Consulting
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# X CONSORTIUM OR DALRYMPLE CONSULTING BE LIABLE FOR ANY CLAIM, DAMAGES OR
-# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-# OTHER DEALINGS IN THE SOFTWARE.
-#
-# Except as contained in this notice, the names of the X Consortium and
-# Dalrymple Consulting shall not be used in advertising or otherwise to
-# promote the sale, use or other dealings in this Software without prior
-# written authorization.
-#
-#############################################################################
-#
-# Written 5/29/96 by Fred Dalrymple
-#
-#############################################################################
-#
-# Variables
-#
-Var: callout 0
-Var: orderlist 0
-Var: procstep 0
-Var: procsubstep 0
-#
-#
-#
-#
-#############################################################################
-#
-# Hierarchy (and document meta stuff)
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: REFENTRY
-StartText: ^.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
- ^.TH "${_followrel descendant REFENTRYTITLE 1000}"
- "${_followrel descendant MANVOLNUM 1000}"
- "${REVISION}" ""
- "${_followrel descendant REFMISCINFO 1000}"^
-EndText: ^...\\" created by instant / docbook-to-man, ${date}^
--
-#
-GI: DOCINFO
-Ignore: all
--
-#
-GI: TITLE
-Context: DOCINFO
-# inside DocInfo, which we're ignoring
--
-#
-GI: REFMETA
-Ignore: all
--
-#
-GI: REFNAMEDIV
-StartText: ^.SH "NAME"^
--
-#
-GI: REFDESCRIPTOR
-StartText: \\fB
-EndText: \\fR\s
--
-#
-GI: REFNAME
-Relation: sibling- REFDESCRIPTOR
-# inhibit REFNAMEs when a REFDESCRIPTOR is present
-Ignore: all
--
-#
-GI: REFNAME
-StartText: ${_isset refnameseen xxx 20}
-EndText: ${_set refnameseen xxx}
--
-#
-GI: _refname
-SpecID: 20
-StartText: ,\s
--
-#
-GI: REFPURPOSE
-StartText: \s\\-\s
-EndText: ^
--
-#
-GI: REFCLASS
-StartText: ^.PP^
-EndText: ^
--
-#
-GI: REFSYNOPSISDIV
-StartText: ^.SH "SYNOPSIS"^
-EndText: ^
--
-#
-GI: REFSECT1
-StartText: ^.SH "${_followrel child TITLE 1001}"^
-EndText: ^
--
-#
-GI: REFSECT2
-StartText: ^.SS "${_followrel child TITLE 1000}"^
-EndText: ^
--
-#
-GI: REFSECT3
-StartText: ^.SS "${_followrel child TITLE 1000}"^
-EndText: ^
--
-#
-GI: BRIDGEHEAD
-StartText: ^.PP^\\fB
-EndText: \\fP^.PP^
--
-#
-GI: TITLE
-Context: REFSECT1
-Ignore: all
--
-#
-GI: TITLE
-Context: REFSECT2
-Ignore: all
--
-#
-GI: TITLE
-Context: REFSECT3
-Ignore: all
--
-#
-GI: LEGALNOTICE
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-GI: TITLE
-Context: LEGALNOTICE
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-GI: REFENTRYTITLE
-Context: REFMETA
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-GI: MANVOLNUM
-Context: REFMETA
-# part of the DocInfo structure, which is ignored, though this element
-# if accessed directly by the _followrel call from the REFENTRY element.
-Ignore: all
--
-#
-GI: REFMISCINFO
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-GI: SUBTITLE
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-GI: AUTHORGROUP
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-GI: AUTHOR
-Context: AUTHORGROUP
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-GI: EDITOR
-Context: AUTHORGROUP
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-GI: COLLAB
-Context: AUTHORGROUP
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-GI: COLLABNAME
-Context: COLLAB
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-GI: CORPAUTHOR
-Context: AUTHORGROUP
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-GI: OTHERCREDIT
-Context: AUTHORGROUP
-# part of the DocInfo structure, which is ignored
-Ignore: all
--
-#
-#
-#############################################################################
-#
-# (before we get into the branch stuff, we turn off paragraphs in some
-# contexts where they would break the flow. Generally, this happens
-# within indented areas, such as within lists.
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: PARA
-Context: LISTITEM
-NthChild: 1
-# nothing in this context
--
-#
-GI: PARA
-Context: GLOSSDEF
-NthChild: 1
-# nothing in this context
--
-#
-GI: PARA
-Context: STEP
-NthChild: 1
-# nothing in this context
--
-#
-GI: PARA
-Context: CALLOUT
-NthChild: 1
-# nothing in this context
--
-#
-GI: PARA
-Context: MSGTEXT
-NthChild: 1
-# nothing in this context
--
-#
-GI: PARA
-Relation: parent ENTRY
-NthChild: 1
-# first one does nothing in this context
--
-#
-GI: PARA
-Relation: parent ENTRY
-StartText: ^.br^
--
-#
-#
-#
-#############################################################################
-#
-# Regular "branch" stuff
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: FORMALPARA
-# it's all done in TITLE (FORMALPARA) and PARA
--
-#
-GI: TITLE
-Context: FORMALPARA
-StartText: ^.PP^\\fB
-EndText: \\fR^
--
-#
-GI: PARA
-Relation: ancestor LISTITEM
-StartText: ^.IP "" 10^
--
-#
-GI: PARA
-Relation: ancestor STEP
-StartText: ^.IP "" 10^
--
-#
-GI: PARA
-StartText: ^.PP^
--
-#
-GI: SIMPARA
-StartText: ^.PP^
--
-#
-GI: PROGRAMLISTING
-StartText: ^.PP^.nf^\\f(CW
-EndText: \\fR^.fi^.PP^
--
-#
-GI: LITERALLAYOUT
-StartText: ^.PP^.nf^
-EndText: ^.fi^
--
-#
-GI: BLOCKQUOTE
-StartText: ^.PP^.RS^
-EndText: ^.RE^
--
-#
-GI: TITLE
-Context: BLOCKQUOTE
-StartText: ^\\fB
-EndText: \\fR^.PP^
--
-#
-GI: EPIGRAPH
-StartText: ^.PP^.RS^
-EndText: ^.RE^
--
-#
-GI: ATTRIBUTION
-StartText: ^\\fI
-EndText: \\fR^.PP^
--
-#
-GI: ABSTRACT
-Relation: child TITLE
--
-#
-GI: ABSTRACT
-StartText: ^.SS "Abstract"^
--
-#
-GI: TITLE
-Context: ABSTRACT
-StartText: ^.SS "
-EndText: "^
-Substitute: " ""
--
-#
-GI: REVHISTORY
-StartText: ^.SS "Revision History"^
-EndText: ^
--
-#
-GI: REVISION
-StartText: ^.PP^\\fBRevision:\\fR\s
-EndText: ^
--
-#
-GI: REVNUMBER
-StartText: #\s
-EndText: ;\s
--
-#
-GI: DATE
-EndText: ;\s
--
-#
-GI: AUTHORINITIALS
-Context: REVISION
-StartText: \s
--
-#
-GI: REVREMARK
-StartText: ;\s\s
-EndText: ^
--
-#
-GI: PROGRAMLISTINGCO
-# nothing to do specifically in ProgramListingCO -- it falls to
-# the content of ProgramListing and any callout list
--
-#
-GI: SCREEN
-StartText: ^.PP^.nf^
-EndText: ^.fi^
--
-#
-GI: SCREENCO
-# nothing to do specifically in ScreenCO -- it falls to
-# the content of Screen and any callout list
--
-#
-GI: SCREENSHOT
-# nothing specific to do here -- defer to any ScreenInfo or the
-# included graphic
--
-#
-GI: SCREENINFO
-StartText: ^.PP^\\fI
-EndText: \\fR^.PP^
--
-#
-GI: GRAPHICCO
-# nothing to do specifically in GraphicCO -- it falls to
-# the content of Graphic and any callout list
--
-#
-GI: INFORMALEXAMPLE
-# nothing special to do here -- it falls to the content.
--
-#
-GI: EXAMPLE
-# nothing special to do here -- it falls to the content.
--
-#
-GI: TITLE
-Context: EXAMPLE
-StartText: ^.PP^\\fB
-EndText: \\fR^
--
-#
-GI: FIGURE
-# nothing special to do here -- it falls to the content.
--
-#
-GI: TITLE
-Context: FIGURE
-StartText: ^.PP^\\fB
-EndText: \\fR^
--
-#
-GI: SIDEBAR
-Relation: child TITLE
-StartText: ^.PP^.RS^
-EndText: ^.RE^
--
-#
-GI: SIDEBAR
-StartText: ^.PP^.RS^\\fB[ Sidebar ]\\fR^
-EndText: ^.RE^
--
-#
-GI: TITLE
-Context: SIDEBAR
-StartText: ^\\fB[ Sidebar:\s
-EndText: \s]\\fR^
--
-#
-GI: HIGHLIGHTS
-StartText: ^.SS "Highlights"^
--
-#
-GI: AUTHORBLURB
-# nothing to do specially -- an included title may occur
--
-#
-GI: TITLE
-Context: AUTHORBLURB
-StartText: ^.PP^\\fB
-EndText: \\fR^
--
-#
-#
-#############################################################################
-#
-# Call-out material
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: CO
-# nothing to do for the anchor of a callout
--
-#
-GI: AREASPEC
-Ignore: all
-# not much to do with representing the anchor of callouts in n/troff
--
-#
-GI: AREA
-Ignore: all
-# part of AreaSpec, which is being ignored
--
-#
-GI: AREASET
-Ignore: all
-# part of AreaSpec, which is being ignored
--
-#
-#
-#############################################################################
-#
-# Address block
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: ADDRESS
-StartText: ^.PP^.nf^
-EndText: ^.fi^
--
-#
-GI: STREET
-# just the content...
--
-#
-GI: POB
-# just the content...
--
-#
-GI: POSTCODE
-# just the content...
--
-#
-GI: CITY
-EndText: ,\s
--
-#
-GI: STATE
-# just the content
--
-#
-GI: COUNTRY
-# just the content
--
-#
-GI: PHONE
-StartText: ^voice:\s
--
-#
-GI: FAX
-StartText: ^fax:\s
--
-#
-GI: OTHERADDR
-# just the content..
--
-#
-GI: EMAIL
-Context: ADDRESS
-# just the content..
--
-#
-#
-#############################################################################
-#
-# Lists
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: GLOSSLIST
-Relation: ancestor ITEMIZEDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: GLOSSLIST
-Relation: ancestor GLOSSLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: GLOSSLIST
-Relation: ancestor ORDEREDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: GLOSSLIST
-Relation: ancestor SIMPLELIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: GLOSSLIST
-Relation: ancestor VARIABLELIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: GLOSSLIST
-Relation: ancestor SEGMENTEDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: GLOSSLIST
-# Nothing to do here.. see glossentry, etc
--
-#
-GI: GLOSSENTRY
-# nothing to do..
--
-#
-GI: GLOSSTERM
-Context: GLOSSENTRY
-StartText: ^.IP "
-EndText: " 10^
-Substitute: " ""
--
-#
-GI: GLOSSTERM
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: ACRONYM
-Context: GLOSSENTRY
-StartText: (\\fIacronym:\s\\fR
-EndText: )\s\s
--
-#
-GI: ABBREV
-Context: GLOSSENTRY
-StartText: (\\fIabbreviation:\s\\fR
-EndText: )\s\s
--
-#
-GI: GLOSSSEE
-StartText: ^\\fISee \\fR
--
-#
-GI: GLOSSDEF
-# nothing special to do -- just pass the content.
--
-#
-GI: GLOSSSEEALSO
-StartText: ^^\\fISee Also \\fR
--
-#
-GI: ITEMIZEDLIST
-Relation: ancestor ITEMIZEDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ITEMIZEDLIST
-Relation: ancestor GLOSSLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ITEMIZEDLIST
-Relation: ancestor ORDEREDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ITEMIZEDLIST
-Relation: ancestor SIMPLELIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ITEMIZEDLIST
-Relation: ancestor VARIABLELIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ITEMIZEDLIST
-Relation: ancestor SEGMENTEDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ITEMIZEDLIST
-# nothing to do..
--
-#
-GI: LISTITEM
-Context: ITEMIZEDLIST
-StartText: ^.IP "\ \ \ \\(bu" 6^
--
-#
-GI: ORDEREDLIST
-Relation: ancestor ITEMIZEDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ORDEREDLIST
-Relation: ancestor GLOSSLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ORDEREDLIST
-Relation: ancestor ORDEREDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ORDEREDLIST
-Relation: ancestor SIMPLELIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ORDEREDLIST
-Relation: ancestor VARIABLELIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ORDEREDLIST
-Relation: ancestor SEGMENTEDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: ORDEREDLIST
-StartText: ${_set orderlist 1}
--
-#
-GI: LISTITEM
-Context: ORDEREDLIST
-StartText: ^.IP "\ \ \ ${orderlist}." 6^
-Increment: orderlist
--
-#
-GI: SIMPLELIST
-Relation: ancestor ITEMIZEDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: SIMPLELIST
-Relation: ancestor GLOSSLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: SIMPLELIST
-Relation: ancestor ORDEREDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: SIMPLELIST
-Relation: ancestor SIMPLELIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: SIMPLELIST
-Relation: ancestor VARIABLELIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: SIMPLELIST
-Relation: ancestor SEGMENTEDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: SIMPLELIST
-# nothing to do here..
--
-#
-GI: MEMBER
-PAttSet: TYPE INLINE
-NthChild: 1
--
-#
-GI: MEMBER
-PAttSet: TYPE INLINE
-StartText: ,\s
--
-#
-GI: MEMBER
-PAttSet: TYPE HORIZ
-NthChild: 1
-StartText: ^.PP^\t
--
-#
-GI: MEMBER
-PAttSet: TYPE HORIZ
-StartText: \t
--
-#
-GI: MEMBER
-PAttSet: TYPE VERT
-StartText: ^.IP "" 10^
-EndText: ^
--
-#
-GI: VARIABLELIST
-Relation: ancestor ITEMIZEDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: VARIABLELIST
-Relation: ancestor GLOSSLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: VARIABLELIST
-Relation: ancestor ORDEREDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: VARIABLELIST
-Relation: ancestor SIMPLELIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: VARIABLELIST
-Relation: ancestor VARIABLELIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: VARIABLELIST
-Relation: ancestor SEGMENTEDLIST
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: VARIABLELIST
-# nothing to do now, see VarListEntry
--
-#
-GI: VARLISTENTRY
-# nothing to do now, see Term
--
-#
-GI: TERM
-StartText: ^.IP "
-EndText: " 10^
-Substitute: " ""
--
-#
-GI: LISTITEM
-Context: VARLISTENTRY
-# nothing special to do..
--
-#
-GI: SEGMENTEDLIST
-Relation: ancestor ITEMIZEDLIST
-StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab(\a);^l l l l l l l l l l l l l l l l l l.^
-EndText: ^.TE^.RE^
--
-#
-GI: SEGMENTEDLIST
-Relation: ancestor GLOSSLIST
-StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab(\a);^l l l l l l l l l l l l l l l l l l.^
-EndText: ^.TE^.RE^
--
-#
-GI: SEGMENTEDLIST
-Relation: ancestor ORDEREDLIST
-StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab(\a);^l l l l l l l l l l l l l l l l l l.^
-EndText: ^.TE^.RE^
--
-#
-GI: SEGMENTEDLIST
-Relation: ancestor SIMPLELIST
-StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab(\a);^l l l l l l l l l l l l l l l l l l.^
-EndText: ^.TE^.RE^
--
-#
-GI: SEGMENTEDLIST
-Relation: ancestor VARIABLELIST
-StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab(\a);^l l l l l l l l l l l l l l l l l l.^
-EndText: ^.TE^.RE^
--
-#
-GI: SEGMENTEDLIST
-Relation: ancestor SEGMENTEDLIST
-StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab(\a);^l l l l l l l l l l l l l l l l l l.^
-EndText: ^.TE^.RE^
--
-#
-GI: SEGMENTEDLIST
-Relation: child TITLE
-StartText: ^${_followrel child TITLE 400}^.TS^tab(\a);^l l l l l l l l l l l l l l l l l l.^
-EndText: ^.TE^
--
-#
-GI: TITLE
-Context: SEGMENTEDLIST
-# ignored by default -- must be called by SEGMENTEDLIST gi
-Ignore: all
--
-#
-GI: _segmentedlist_title
-SpecID: 400
-StartText: ^.sp 1^\\fB
-EndText: \\fR^
--
-#
-GI: SEGTITLE
-StartText: \\fB
-EndText: \\fR\a
--
-#
-GI: SEGLISTITEM
-StartText: ^
-EndText: ^
--
-#
-GI: SEG
-EndText: \a
--
-#
-GI: PROCEDURE
-# defer to the content...
-StartText: ${_set procstep 1}${_set procsubstep 1}
--
-#
-GI: TITLE
-Context: PROCEDURE
-StartText: ^.PP^\\fB
-EndText: \\fR^
--
-#
-GI: STEP
-Context: SUBSTEPS
-StartText: ^.PP^\\fISubstep ${procsubstep}.\s\s
-EndText: ^
-Increment: procsubstep 1
--
-#
-GI: STEP
-StartText: ^.PP^\\fIStep ${procstep}.\s\s
-EndText: ^
-Increment: procstep 1
--
-#
-GI: TITLE
-Context: STEP
-StartText: ^\\fB
-EndText: \\fR^.PP^
--
-#
-GI: SUBSTEPS
-StartText: ^.RS^
-EndText: ^.RE^
--
-#
-GI: CALLOUTLIST
-StartText: ${_set callout 1}
-# nothing to do specifically, defer to the content...
--
-#
-GI: TITLE
-Context: CALLOUTLIST
-StartText: ^\\fB
-EndText: \\fR^.PP^
--
-#
-GI: CALLOUT
-StartText: ^.PP^\\fICallout ${callout}.\s\s\\fR
-EndText: ^
-Increment: callout
--
-#
-#
-#############################################################################
-#
-# Messages
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: MSGSET
-StartText: ^.SS "Message Set"^
--
-#
-GI: MSGENTRY
-StartText: ^.PP^\\fBMessage Entry\\fR^.RS^
-EndText: ^.RE^
--
-#
-GI: MSG
-Relation: child TITLE
-StartText: ^.PP^
-EndText: ^
--
-#
-GI: MSG
-StartText: ^.PP^\\fBMessage:\\fR^.PP^
-EndText: ^
--
-#
-GI: TITLE
-Context: MSG
-StartText: ^.PP^\\fB
-EndText: \\fR^.PP^
--
-#
-GI: MSGINFO
-# nothing specific -- just groups (MsgLevel | MsgOrig | MsgAud)*
--
-#
-GI: MSGEXPLAN
-# nothing special -- defer to content
--
-#
-GI: TITLE
-Context: MSGEXPLAN
-StartText: ^.PP^\\fB
-EndText: \\fR^
--
-#
-GI: MSGMAIN
-# defer to content
--
-#
-GI: TITLE
-Context: MSGMAIN
-StartText: ^\\fB
-EndText: \\fR^
--
-#
-GI: MSGSUB
-# defer to content
--
-#
-GI: TITLE
-Context: MSGSUB
-StartText: ^.PP^\\fB
-EndText: \\fR^
--
-#
-GI: MSGREL
-# defer to content
--
-#
-GI: TITLE
-Context: MSGREL
-StartText: ^.PP^\\fB
-EndText: \\fR^
--
-#
-GI: MSGLEVEL
-StartText: ^.PP^\\fIMessage level:\s\s\\fR
-EndText: ^
--
-#
-GI: MSGORIG
-StartText: ^.PP^\\fIMessage origin:\s\s\\fR
-EndText: ^
--
-#
-GI: MSGAUD
-StartText: ^.PP^\\fIMessage audience:\s\s\\fR
-EndText: ^
--
-#
-GI: MSGTEXT
-Context: PARA
-StartText: \\fI
-EndText: \\fP
--
-#
-GI: MSGTEXT
-StartText: \\fR^\\fIMessage text:\\fR\s\s
-EndText: ^
--
-#
-#
-#############################################################################
-#
-# Admonitions
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: CAUTION
-Relation: child TITLE
-StartText: ^.PP^.RS
-EndText: ^.RE^
--
-#
-GI: CAUTION
-StartText: ^.PP^.RS^\\fBCaution:\s\s
-EndText: ^.RE^
--
-#
-GI: TITLE
-Context: CAUTION
-StartText: ^\\fBCaution:\s\s
-EndText: \\fR^.PP^
--
-#
-GI: IMPORTANT
-Relation: child TITLE
-StartText: ^.PP^.RS^
-EndText: ^.RE^
--
-#
-GI: IMPORTANT
-StartText: ^.PP^.RS^\\fBImportant:\s\s
-EndText: ^.RE^
--
-#
-GI: TITLE
-Context: IMPORTANT
-StartText: ^\\fBImportant:\s\s
-EndText: \\fR^.PP^
--
-#
-GI: NOTE
-Relation: child TITLE
-StartText: ^.PP^.RS
-EndText: ^.RE^
--
-#
-GI: NOTE
-StartText: ^.PP^.RS^\\fBNote:\s\s
-EndText: ^.RE^
--
-#
-GI: TITLE
-Context: NOTE
-StartText: ^\\fBNote:\s\s
-EndText: \\fR^.PP^
--
-#
-GI: TIP
-Relation: child TITLE
-StartText: ^.PP^.RS
-EndText: ^.RE^
--
-#
-GI: TIP
-StartText: ^.PP^.RS^\\fBTip:\s\s
-EndText: ^.RE^
--
-#
-GI: TITLE
-Context: TIP
-StartText: ^\\fBTip:\s\s
-EndText: \\fR^.PP^
--
-#
-GI: WARNING
-Relation: child TITLE
-StartText: ^.PP^.RS
-EndText: ^.RE^
--
-#
-GI: WARNING
-StartText: ^.PP^.RS^\\fBWarning:\s\s
-EndText: ^.RE^
--
-#
-GI: TITLE
-Context: WARNING
-StartText: ^\\fBWarning:\s\s
-EndText: \\fR^.PP^
--
-#
-#
-#############################################################################
-#
-# Synopses
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: SYNOPSIS
-StartText: ^.PP^.nf^
-EndText: ^.fi^
--
-#
-GI: CMDSYNOPSIS
-StartText: ^.PP^
-EndText: ^
--
-#
-GI: ARG
-Context: GROUP
-NthChild: 1
-EndText: ${_attval REP REPEAT 505}\s
--
-#
-GI: ARG
-Context: GROUP
-StartText: \s|\s
-EndText: ${_attval REP REPEAT 505}\s
--
-#
-GI: ARG
-AttValue: CHOICE OPT
-StartText: \s[
-EndText: ${_attval REP REPEAT 505}]\s
--
-#
-GI: ARG
-# no special attrs -- just pass content through
-EndText: ${_attval REP REPEAT 505}\s
--
-#
-GI: _arg_group
-SpecID: 505
-StartText: \s\\&...
-Ignore: all
--
-#
-GI: GROUP
-AttValue: CHOICE OPT
-StartText: \s[
-EndText: ]\s${_attval REP REPEAT 505}
--
-#
-GI: GROUP
-AttValue: CHOICE REQ
-StartText: \s{
-EndText: }\s${_attval REP REPEAT 505}
--
-#
-GI: GROUP
-AttValue: CHOICE OPTMULT
-StartText: \s[[
-EndText: ]]\s${_attval REP REPEAT 505}
--
-#
-GI: GROUP
-AttValue: CHOICE REQMULT
-StartText: \s{{
-EndText: }}\s${_attval REP REPEAT 505}
--
-#
-GI: GROUP
-AttValue: CHOICE PLAIN
-EndText: ${_attval REP REPEAT 505}
--
-#
-GI: SBR
-StartText: ^.br^
--
-#
-GI: SYNOPFRAGMENT
-# nothing special to do here -- just pass through content (Arg | Group)+
--
-#
-GI: SYNOPFRAGMENTREF
-# WHAT TO DO HERE?? pass through the content, but what about the
-# linkend? (will call it across...)
-EndText: \s\\fI(refers to: ${_followlink LINKEND 1000})\\fR
--
-#
-GI: FUNCSYNOPSIS
-StartText: ^.PP^.nf^
-EndText: ^.fi^
--
-#
-GI: FUNCSYNOPSISINFO
-StartText: ^
-EndText: ^
--
-#
-GI: FUNCPROTOTYPE
-# nothing special -- just pass through content (looks like
-# a function def
-StartText: ^.sp 1^
--
-#
-GI: FUNCDEF
-StartText: ^\\fB
-EndText: \\fR(
--
-#
-GI: FUNCPARAMS
-StartText: ^\t\t\t\\fB
-EndText: \\fR^
--
-#
-GI: VOID
-StartText: \\fBvoid\\fR);
--
-#
-GI: VARARGS
-StartText: \\fB\\&...\\fR);
--
-#
-GI: PARAMDEF
-Relation: sibling+ PARAMDEF
-StartText: ^\\fB
-EndText: \\fR,^
--
-#
-GI: PARAMDEF
-StartText: ^\\fB
-EndText: \\fR);^
--
-#
-#
-#############################################################################
-#
-# Links
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: LINK
-StartText: \\fI
-EndText: \\fR
--
-#
-GI: OLINK
-StartText: \\fI
-EndText: \s(link to external document ${TargetDocEnt})\s\\fR
--
-#
-GI: ULINK
-StartText: \\fI
-EndText: \s(link to URL ${URL})\s\\fR
--
-#
-GI: FOOTNOTEREF
-# just let the footnote ref mark come through
--
-#
-GI: FOOTNOTE
-# just let footnote body come through (-man doesn't support footnotes)
--
-#
-GI: XREF
-AttValue: ENDTERM
-StartText: \\fI(cross-reference to ``${_followlink ENDTERM 1000}'')\\fR\s
--
-#
-GI: XREF
-StartText: \\fI(cross-reference to ``${_followlink LINKEND 600})''\\fR\s
--
-#
-GI: _xref
-SpecID: 600
-StartText: ${XREFLABEL}
-Ignore: all
--
-#
-GI: ANCHOR
-# nothing to do -- this just marks a place..
--
-#
-#
-#############################################################################
-#
-# Graphics and Equations
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: GRAPHIC
-AttValue: ENTITYREF
-StartText: ^.PP^.if t .P! "${_filename}"^
--
-#
-GI: INLINEGRAPHIC
-StartText: ^.if t .P! "${_filename}"^
--
-#
-GI: INFORMALEQUATION
-# nothing special to do -- defer to graphic content..
--
-#
-GI: EQUATION
-# nothing special to do -- defer to graphic content..
--
-#
-GI: TITLE
-Context: EQUATION
-StartText: ^.PP^\\fB
-EndText: \\fR^
--
-#
-GI: INLINEEQUATION
-# nothing special to do -- defer to graphic content..
--
-#
-#
-#############################################################################
-#
-# Tables
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-#
-GI: INFORMALTABLE
-StartText: ^${_calstable tbl tablestart}^
-EndText: ^${_calstable tbl tableend}^
--
-#
-GI: TABLE
-StartText: ^.PP^\\fB${_followrel child TITLE 1000}\\fR
- ^${_calstable tbl tablestart}^
-EndText: ^${_calstable tbl tableend}^
--
-#
-GI: TITLE
-Context: TABLE
-# handled in TABLE element
-Ignore: all
--
-#
-GI: TGROUP
-StartText: ^${_calstable tbl tablegroup}^${_followrel child THEAD 700}${_followrel child TBODY 700}${_followrel child TFOOT 701}
-EndText: ${_calstable tbl tablegroupend}
--
-#
-GI: COLSPEC
-Ignore: all
--
-#
-GI: SPANSPEC
-Ignore: all
--
-#
-GI: THEAD TBODY TFOOT
-# they're called explicitly from TGROUP, but ignored here
-Ignore: all
--
-#
-GI: _thead_tbody
-SpecID: 700
-# nothing special to do -- just pass through content
--
-#
-GI: _tfoot
-SpecID: 701
-StartText: ^${_calstable tbl tablefoot}^
--
-#
-GI: ROW
-StartText: ^${_calstable tbl rowstart}
-EndText: ${_calstable tbl rowend}
--
-#
-GI: ENTRY
-StartText: ${_calstable tbl entrystart}
-EndText: ${_calstable tbl entryend}
--
-#
-GI: ENTRYTBL
-StartText:
-EndText:
-Message: ^IMPLEMENT <${_gi} ${_allatts}>^
--
-#
-#
-#############################################################################
-#
-# Index terms
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: INDEXTERM
-StartText: ^.iX\s
-EndText: ^
--
-#
-GI: PRIMARY
-StartText: "
-EndText: "
--
-#
-GI: SECONDARY
-StartText: \s"
-EndText: "
--
-#
-GI: TERTIARY
-StartText: \s"
-EndText: "
--
-#
-GI: SEE
-StartText: \s"See:\s
-EndText: "
--
-#
-GI: SEEALSO
-StartText: \s"SeeAlso:\s
-EndText: "
--
-#
-#
-#############################################################################
-#
-# Author / OtherCredit material
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: OTHERCREDIT
-# nothing specific -- defer to content
--
-#
-GI: HONORIFIC
-# nothing specific -- defer to content
-EndText: \s
--
-#
-GI: FIRSTNAME
-# nothing specific -- defer to content
-EndText: \s
--
-#
-GI: SURNAME
-# nothing specific -- defer to content
-EndText: \s
--
-#
-GI: LINEAGE
-# nothing specific -- defer to content
-EndText: \s
--
-#
-GI: OTHERNAME
-# nothing specific -- defer to content
-StartText: (
-EndText: )\s
--
-#
-GI: AFFILIATION
-# nothing specific -- defer to content
-EndText: \s
--
-#
-GI: SHORTAFFIL
-# nothing specific -- defer to content
-EndText: \s
--
-#
-GI: JOBTITLE
-# nothing specific -- defer to content
-EndText: \s
--
-#
-GI: ORGNAME
-# nothing specific -- defer to content
-EndText: \s
--
-#
-GI: ORGDIV
-# nothing specific -- defer to content
-EndText: \s
--
-#
-GI: CONTRIB
-# nothing specific -- defer to content
-EndText: \s
--
-#
-#
-#############################################################################
-#
-# "Leaf" material
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: ABBREV
-# no special presentation
--
-#
-GI: ACCEL
-# no special presentation
--
-#
-GI: ACRONYM
-# no special presentation
--
-#
-GI: AUTHORINITIALS
-# no special presentation
--
-#
-GI: CITATION
-StartText: \\fI
-EndText: \\fP
--
-#
-GI: CITETITLE
-AttValue: PUBWORK
-StartText: \\fI
-EndText: \\fP (${PUBWORK})\s
--
-#
-GI: CITETITLE
-StartText: \\fI
-EndText: \\fP
--
-#
-GI: CITEREFENTRY
-# defer to content..
--
-#
-GI: REFENTRYTITLE
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: MANVOLNUM
-StartText: \\fB(
-EndText: )\\fP
--
-#
-GI: COMMENT
-# docbook says to inhibit this from finished products...
-Ignore: all
--
-#
-GI: EMAIL
-# no special presentation
--
-#
-GI: EMPHASIS
-StartText: \\fI
-EndText: \\fP
--
-#
-GI: FIRSTTERM
-StartText: \\fI
-EndText: \\fR
--
-#
-GI: FOREIGNPHRASE
-# no special presentation
--
-#
-GI: PHRASE
-# no special presentation
--
-#
-GI: QUOTE
-StartText: ``\\fI
-EndText: \\fP''
--
-#
-GI: TRADEMARK
-EndText: \\u\\s-2TM\\s+2\\d
--
-#
-GI: WORDASWORD
-# no special presentation
--
-#
-GI: ACTION
-# no special presentation
--
-#
-GI: APPLICATION
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: CLASSNAME
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: COMMAND
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: COMPUTEROUTPUT
-StartText: \\f(CW
-EndText: \\fP
--
-#
-GI: DATABASE
-# no special presentation
--
-#
-GI: ERRORNAME
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: ERRORTYPE
-# no special presentation
--
-#
-GI: FILENAME
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: FUNCTION
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: GUIBUTTON
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: GUIICON
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: GUILABEL
-# no special presentation
--
-#
-GI: GUIMENU
-# no special presentation
--
-#
-GI: GUIMENUITEM
-# no special presentation
--
-#
-GI: GUISUBMENU
-# no special presentation
--
-#
-GI: HARDWARE
-# no special presentation
--
-#
-GI: INTERFACE
-# no special presentation
--
-#
-GI: INTERFACEDEFINITION
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: KEYCAP
-StartText: \\fB<
-EndText: >\\fP
--
-#
-GI: KEYCODE
-# no special presentation
--
-#
-GI: KEYCOMBO
-# no special presentation -- defer to the content
--
-#
-GI: KEYSYM
-StartText: \\fB<
-EndText: >\\fP
--
-#
-GI: LINEANNOTATION
-StartText: \\fI
-EndText: \\fP
--
-#
-GI: LITERAL
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: MARKUP
-StartText: \\f(CW
-EndText: \\fP
--
-#
-GI: MEDIALABEL
-# no special presentation
--
-#
-GI: MENUCHOICE
-# no special presentation
--
-#
-GI: SHORTCUT
-# no special presentation
--
-#
-GI: MOUSEBUTTON
-# no special presentation
--
-#
-GI: OPTION
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: OPTIONAL
-StartText: [
-EndText: ]
--
-#
-GI: PARAMETER
-StartText: \\fB
-EndText: \\fR
--
-#
-GI: PROPERTY
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: REPLACEABLE
-StartText: \\fI
-EndText: \\fP
--
-#
-GI: RETURNVALUE
-StartText: \\fB
-EndText: \\fR
--
-#
-GI: SGMLTAG
-AttValue: CLASS ELEMENT
-StartText: \\fB<
-EndText: >\\fP
--
-#
-GI: SGMLTAG
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: STRUCTFIELD
-StartText: \\fB
-EndText: \\fR
--
-#
-GI: STRUCTNAME
-StartText: \\fB
-EndText: \\fR
--
-#
-GI: SYMBOL
-AttValue: ROLE Variable
-StartText: \\fI
-EndText: \\fP
--
-#
-GI: SYMBOL
-StartText: \\fI
-EndText: \\fP
--
-#
-GI: SYSTEMITEM
-AttValue: CLASS CONSTANT
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: SYSTEMITEM
-AttValue: CLASS ENVIRONVAR
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: SYSTEMITEM
-AttValue: CLASS RESOURCE
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: SYSTEMITEM
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: TOKEN
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: TYPE
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: USERINPUT
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: AUTHOR
-# no special presentation - defer to content
--
-#
-GI: CORPAUTHOR
-# no special presentation
--
-#
-GI: MODESPEC
-# nothing to render (this is meta information for Links)
--
-#
-GI: PRODUCTNAME
-StartText: \\fB
-EndText: \\fP
--
-#
-GI: PRODUCTNUMBER
-# no special presentation
--
-#
-GI: SUBSCRIPT
-StartText: \\d
-EndText: \\u
--
-#
-GI: SUPERSCRIPT
-StartText: \\u
-EndText: \\d
--
-#
-#
-#############################################################################
-#
-# stuff that gets ignored (and doesn't belong elsewhere)
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: TITLEABBREV
-# this element is ignored in favor of the real title
-Ignore: all
--
-#
-#
-#
-#############################################################################
-#
-# handle layout-specific stuff and PIs
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: BEGINPAGE
-StartText: ^.br\s
-EndText: ^
--
-#
-GI: _x-break
-StartText: ^.br\s
-EndText: ^
--
-#
-GI: _sml-break
-StartText: ^.br\s
-EndText: ^
--
-#
-GI: _sml-need
-StartText: ^.ne\s
-EndText: ^
--
-#
-GI: _sml-size
-StartText: ^.ps\s
-EndText: ^
--
-#
-GI: _sml-indent
-StartText: ^.in\s
-EndText: ^
--
-#
-GI: _sml-space
-StartText: ^.sp\s
-EndText: ^
--
-#
-GI: _sml-tabset
-StartText: ^.ta\s
-EndText: ^
--
-#
-#
-#############################################################################
-#
-# General purpose transpecs
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: _passthrough
-SpecID: 1000
--
-#
-GI: _passthrough2
-SpecID: 1001
-StartText: ${+caps}
-Ignore: all
--
-#
-GI: _doTitle
-SpecID: 1010
-StartText: ^.PP^\\fB
-EndText: \\fR^.PP^
--
-#
-#
-#############################################################################
-#
-# Catch-all for unknown PIs -- ignore them...
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-GI: _*
-Ignore: data
--
-#
-#
-#############################################################################
-#
-# Catch-all for unknown elements -- just output their content..
-#
-# #### ##### ##### ##### ##### ##### #### #####
-#
-#GI: *
-#-
-#
+++ /dev/null
- -- ...................................................................... --
- -- DSSL stylesheet ...................................................... --
- -- ...................................................................... --
-
-PUBLIC "-//Gtk//DOCUMENT Gtk-doc HTML Stylesheet//EN"
- "@PACKAGE_DATA_DIR@/gtk-doc.dsl"
+++ /dev/null
-<!SGML "ISO 8879:1986"
- -- ...................................................................... --
- -- DocBook SGML declaration V3.1 ........................................ --
- -- file docbook.dcl ..................................................... --
-
-CHARSET
-
- BASESET
- "ISO 646:1983//CHARSET International Reference Version (IRV)//ESC 2/5 4/0"
- DESCSET
- 0 9 UNUSED
- 9 2 9
- 11 2 UNUSED
- 13 1 13
- 14 18 UNUSED
- 32 95 32
- 127 1 UNUSED
-
- BASESET
- "ISO Registration Number 100//CHARSET ECMA-94 Right Part of Latin Alphabet Nr. 1//ESC 2/13 4/1"
- DESCSET
- 128 32 UNUSED
- 160 96 32
-
-CAPACITY SGMLREF
-
- TOTALCAP 99000000
- ATTCAP 1000000
- ATTCHCAP 1000000
- AVGRPCAP 1000000
- ELEMCAP 1000000
- ENTCAP 1000000
- ENTCHCAP 1000000
- GRPCAP 1000000
- IDCAP 32000000
- IDREFCAP 32000000
-
-SCOPE DOCUMENT
-
-SYNTAX
-
- SHUNCHAR CONTROLS 0 1 2 3 4 5 6 7 8 9
- 10 11 12 13 14 15 16 17 18 19
- 20 21 22 23 24 25 26 27 28 29
- 30 31 127 128 129
- 130 131 132 133 134 135 136 137 138 139
- 140 141 142 143 144 145 146 147 148 149
- 150 151 152 153 154 155 156 157 158 159
-
- BASESET
- "ISO 646:1983//CHARSET International Reference Version (IRV)//ESC 2/5 4/0"
- DESCSET
- 0 128 0
-
- FUNCTION
- RE 13
- RS 10
- SPACE 32
- TAB SEPCHAR 9
-
- NAMING
- LCNMSTRT ""
- UCNMSTRT ""
- LCNMCHAR ".-_:"
- UCNMCHAR ".-_:"
- NAMECASE
- GENERAL YES
- ENTITY NO
-
- DELIM
- GENERAL SGMLREF
- SHORTREF SGMLREF
-
- NAMES SGMLREF
-
- QUANTITY SGMLREF
- ATTCNT 256
- GRPCNT 253
- GRPGTCNT 253
- LITLEN 8092
- NAMELEN 256
- TAGLVL 100
-
-FEATURES
-
- MINIMIZE
- DATATAG NO
- OMITTAG NO
- RANK NO
- SHORTTAG YES
-
- LINK
- SIMPLE NO
- IMPLICIT NO
- EXPLICIT NO
-
- OTHER
- CONCUR NO
- SUBDOC NO
- FORMAL YES
-
-APPINFO NONE
-
- -- End of DocBook SGML declaration V3.1 ................................. --
- -- ...................................................................... --
->
<name xml:lang="en">gtk-doc</name>
- <shortdesc xml:lang="en">GTK-Doc is used to document C code.
+ <shortdesc xml:lang="en">Documentation generator for C code.</shortdesc>
+ <description>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 also be
used to document application code.
-</shortdesc>
+</description>
<homepage rdf:resource="http://www.gtk.org/gtk-doc/" />
<mailing-list rdf:resource="http://mail.gnome.org/mailman/listinfo/gtk-doc-devel-list" />
<maintainer>
<foaf:Person>
- <foaf:name>Stefan Kost</foaf:name>
+ <foaf:name>Stefan Sauer</foaf:name>
<foaf:mbox rdf:resource="mailto:ensonic@users.sf.net" />
<gnome:userid>stefkost</gnome:userid>
</foaf:Person>
</maintainer>
- <maintainer>
- <foaf:Person>
- <foaf:name>Damon Chaplin</foaf:name>
- <gnome:userid>damon</gnome:userid>
- </foaf:Person>
- </maintainer>
- <maintainer>
- <foaf:Person>
- <foaf:name>Owen Taylor</foaf:name>
- <foaf:mbox rdf:resource="mailto:otaylor@redhat.com" />
- <gnome:userid>otaylor</gnome:userid>
- </foaf:Person>
- </maintainer>
<maintainer>
<foaf:Person>
<foaf:name>Matthias Clasen</foaf:name>
+++ /dev/null
-<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
-<!ENTITY dbstyle PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
-]>
-
-<style-sheet>
-<style-specification use="docbook">
-<style-specification-body>
-
-(define gtkdoc-version "")
-(define gtkdoc-bookname "")
-
-;; These are some customizations to the standard HTML output produced by the
-;; Modular DocBook Stylesheets.
-;; I've copied parts of a few functions from the stylesheets so these should
-;; be checked occasionally to ensure they are up to date.
-;;
-;; The last check was with version 1.40 of the stylesheets.
-;; It will not work with versions < 1.19 since the $shade-verbatim-attr$
-;; function was added then. Versions 1.19 to 1.39 may be OK, if you're lucky!
-
-;;(define %generate-book-toc% #f)
-
-;; If a Chapter has role="no-toc" we don't generate a table of contents.
-;; This is useful if a better contents page has been added manually, e.g. for
-;; the GTK+ Widgets & Objects page. (But it is a bit of a hack.)
-(define ($generate-chapter-toc$)
- (not (equal? (attribute-string (normalize "role") (current-node)) "no-toc")))
-
-(define %chapter-autolabel%
- ;; Are chapters enumerated?
- #f)
-
-(define %use-id-as-filename% #t)
-
-(define %html-ext% ".html")
-
-(define ($user-html-header$ #!optional
- (home (empty-node-list))
- (up (empty-node-list))
- (prev (empty-node-list))
- (next (empty-node-list)))
- (make sequence
- (if (not (string=? gtkdoc-version ""))
- (make empty-element gi: "META"
- attributes: (list
- (list "NAME" "GENERATOR")
- (list "CONTENT" (string-append
- "GTK-Doc V"
- gtkdoc-version
- " (SGML mode)"))))
- (empty-sosofo))
- (make element gi: "STYLE"
- attributes: (list (list "TYPE" "text/css"))
- (literal ".synopsis, .classsynopsis {
- background: #eeeeee;
- border: solid 1px #aaaaaa;
- padding: 0.5em;
-}
-.programlisting {
- background: #eeeeff;
- border: solid 1px #aaaaff;
- padding: 0.5em;
-}
-.variablelist {
- padding: 4px;
- margin-left: 3em;
-}
-.navigation {
- background: #ffeeee;
- border: solid 1px #ffaaaa;
- margin-top: 0.5em;
- margin-bottom: 0.5em;
-}
-.navigation a {
- color: #770000;
-}
-.navigation a:visited {
- color: #550000;
-}
-.navigation .title {
- font-size: 200%;
-}"))))
-
-
-(mode book-titlepage-recto-mode
- (element title
- (make element gi: "TABLE"
- attributes: (list
- (list "CLASS" "navigation")
- (list "WIDTH" %gentext-nav-tblwidth%)
- (list "CELLPADDING" "2")
- (list "CELLSPACING" "0"))
- (make element gi: "TR"
- (make element gi: "TH"
- attributes: (list
- (list "ALIGN" "center")
- (list "VALIGN" "MIDDLE"))
- (make element gi: "P"
- attributes: (list (list "CLASS" (gi)))
- (process-children-trim)
- (make empty-element gi: "A"
- attributes: (list (list "NAME" (element-id))))))))))
-
-(define (book-titlepage-separator side)
- (empty-sosofo))
-
-
-;; This overrides the variablelist definition (copied from 1.76,
-;; dblists.dsl). It changes the table background color, cell spacing
-;; and cell padding.
-;;
-;; I have also removed the code to handle the non-table case.
-(element variablelist
- (make sequence
- (if %spacing-paras%
- (make element gi: "P" (empty-sosofo))
- (empty-sosofo))
- (para-check)
-
- (make element gi: "TABLE"
- attributes: '(("CLASS" "variablelist")
- ("BORDER" "0")
- ("CELLSPACING" "0")
- ("CELLPADDING" "4"))
- (if %html40%
- (make element gi: "TBODY"
- (with-mode variablelist-table
- (process-children)))
- (with-mode variablelist-table
- (process-children))))
- (para-check 'restart)))
-
-(mode variablelist-table
- (element (variablelist title)
- (make element gi: "TR"
- attributes: '(("CLASS" "TITLE"))
- (make element gi: "TH"
- attributes: '(("ALIGN" "LEFT")
- ("VALIGN" "TOP")
- ("COLSPAN" "2"))
- (process-children))))
-
- (element varlistentry
- (let* ((terms (select-elements (children (current-node))
- (normalize "term")))
- (listitem (select-elements (children (current-node))
- (normalize "listitem"))))
-
- (make element gi: "TR"
- (make element gi: "TD"
- attributes: '(("ALIGN" "LEFT")
- ("VALIGN" "TOP"))
- (make empty-element gi: "A"
- attributes: (list
- (list "NAME" (element-id))))
- (process-node-list terms))
- (make element gi: "TD"
- attributes: '(("ALIGN" "LEFT")
- ("VALIGN" "TOP"))
- (process-node-list listitem)))))
-
- (element (varlistentry term)
- (make sequence
- (if %css-decoration%
- (make element gi: "SPAN"
- attributes: '(("STYLE" "white-space: nowrap"))
- (process-children-trim))
- (make element gi: "NOBR"
- (process-children-trim)))
- (if (not (last-sibling?))
- (literal ", ")
- (literal ""))))
-
- (element (varlistentry listitem)
- (process-children))
-)
-
-
-;; This overrides the refsect2 definition (copied from 1.20, dbrfntry.dsl).
-;; It puts a horizontal rule before each function/struct/... description,
-;; except the first one in the refsect1.
-(element refsect2
- (make sequence
- (if (first-sibling?)
- (empty-sosofo)
- (make empty-element gi: "HR"))
- ($block-container$)))
-
-;; Override the book declaration, so that we generate a crossreference
-;; for the book
-
-(element book
- (let* ((bookinfo (select-elements (children (current-node)) (normalize "bookinfo")))
- (ititle (select-elements (children bookinfo) (normalize "title")))
- (title (if (node-list-empty? ititle)
- (select-elements (children (current-node)) (normalize "title"))
- (node-list-first ititle)))
- (nl (titlepage-info-elements (current-node) bookinfo))
- (tsosofo (with-mode head-title-mode
- (process-node-list title)))
- (dedication (select-elements (children (current-node)) (normalize "dedication"))))
- (make sequence
- (html-document
- tsosofo
- (make element gi: "DIV"
- attributes: '(("CLASS" "BOOK"))
- (if %generate-book-titlepage%
- (make sequence
- (book-titlepage nl 'recto)
- (book-titlepage nl 'verso))
- (empty-sosofo))
-
- (if (node-list-empty? dedication)
- (empty-sosofo)
- (with-mode dedication-page-mode
- (process-node-list dedication)))
-
- (if (not (generate-toc-in-front))
- (process-children)
- (empty-sosofo))
-
- (if %generate-book-toc%
- (build-toc (current-node) (toc-depth (current-node)))
- (empty-sosofo))
-
- ;; (let loop ((gilist %generate-book-lot-list%))
- ;; (if (null? gilist)
- ;; (empty-sosofo)
- ;; (if (not (node-list-empty?
- ;; (select-elements (descendants (current-node))
- ;; (car gilist))))
- ;; (make sequence
- ;; (build-lot (current-node) (car gilist))
- ;; (loop (cdr gilist)))
- ;; (loop (cdr gilist)))))
-
- (if (generate-toc-in-front)
- (process-children)
- (empty-sosofo))))
- (make entity
- system-id: "index.sgml"
- (with-mode generate-index-mode
- (process-children))))))
-
-;; Mode for generating cross references
-
-(define (process-child-elements)
- (process-node-list
- (node-list-map (lambda (snl)
- (if (equal? (node-property 'class-name snl) 'element)
- snl
- (empty-node-list)))
- (children (current-node)))))
-
-(mode generate-index-mode
- (element anchor
- (if (attribute-string "href" (current-node))
- (empty-sosofo)
- (make formatting-instruction data:
- (string-append "\less-than-sign;ANCHOR id =\""
- (attribute-string "id" (current-node))
- "\" href=\""
- (if (not (string=? gtkdoc-bookname ""))
- (string-append gtkdoc-bookname "/")
- "")
- (href-to (current-node))
- "\"\greater-than-sign;
-"))))
-
- ;; We also want to be able to link to complete RefEntry.
- (element refentry
- (make sequence
- (make formatting-instruction data:
- (string-append "\less-than-sign;ANCHOR id =\""
- (attribute-string "id" (current-node))
- "\" href=\""
- (if (not (string=? gtkdoc-bookname ""))
- (string-append gtkdoc-bookname "/")
- "")
- (href-to (current-node))
- "\"\greater-than-sign;
-"))
- (process-child-elements)))
-
- (default
- (process-child-elements)))
-
-;; For hypertext links for which no target is found in the document, we output
-;; our own special tag which we use later to resolve cross-document links.
-(element link
- (let* ((target (element-with-id (attribute-string (normalize "linkend")))))
- (if (node-list-empty? target)
- (make element gi: "GTKDOCLINK"
- attributes: (list
- (list "HREF" (attribute-string (normalize "linkend"))))
- (process-children))
- (make element gi: "A"
- attributes: (list
- (list "HREF" (href-to target)))
- (process-children)))))
-
-
-;; This overrides default-header-nav-tbl-noff (copied from 1.20, dbnavig.dsl).
-;; I want 'Home' and 'Up' links at the top of each page, and white text on
-;; black.
-(define (default-header-nav-tbl-noff elemnode prev next prevsib nextsib)
- (let* ((up (parent elemnode))
- (home (nav-home elemnode))
- (show-title? (nav-banner? elemnode))
- (title-sosofo
- (make element gi: "TH"
- attributes: (list
- (list "WIDTH" "100%")
- (list "align" "center"))
- (if show-title?
- (nav-banner elemnode)
- (empty-sosofo))))
- (show-banner? (or show-title?
- (not (node-list-empty? prev))
- (not (node-list-empty? next))
- (nav-context? elemnode)))
- (banner-sosofo
- (make element gi: "TR"
- attributes: (list
- (list "VALIGN" "middle"))
- (if (not (node-list-empty? prev))
- (make element gi: "TD"
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "p")
- (list "HREF"
- (href-to prev)))
- (make empty-element gi: "IMG"
- attributes: (list
- (list "SRC" "left.png")
- (list "WIDTH" "16")
- (list "HEIGHT" "16")
- (list "BORDER" "0")
- (list "ALT" "Prev")))))
- (empty-sosofo))
- (if (nav-up? elemnode)
- (make element gi: "TD"
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "u")
- (list "HREF"
- (href-to up)))
- (make empty-element gi: "IMG"
- attributes: (list
- (list "SRC" "up.png")
- (list "WIDTH" "16")
- (list "HEIGHT" "16")
- (list "BORDER" "0")
- (list "ALT" "Up")))))
- (empty-sosofo))
- (if (nav-home? elemnode)
- (make element gi: "TD"
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "h")
- (list "HREF"
- (href-to home)))
- (make empty-element gi: "IMG"
- attributes: (list
- (list "SRC" "home.png")
- (list "WIDTH" "16")
- (list "HEIGHT" "16")
- (list "BORDER" "0")
- (list "ALT" "Home")))))
- (empty-sosofo))
- title-sosofo
- (if (not (node-list-empty? next))
- (make element gi: "TD"
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "n")
- (list "HREF"
- (href-to next)))
- (make empty-element gi: "IMG"
- attributes: (list
- (list "SRC" "right.png")
- (list "WIDTH" "16")
- (list "HEIGHT" "16")
- (list "BORDER" "0")
- (list "ALT" "Next")))))
- (empty-sosofo)))))
-
- (if show-banner?
- (make element gi: "TABLE"
- attributes: (list
- (list "WIDTH" %gentext-nav-tblwidth%)
- (list "CLASS" "navigation")
- (list "SUMMARY" "Navigation header")
- (list "CELLPADDING" "2")
- (list "CELLSPACING" "2"))
- banner-sosofo)
- (empty-sosofo))))
-
-;; This overrides default-footer-nav-tbl (copied from 1.20, dbnavig.dsl).
-;; It matches the header above.
-(define (default-footer-nav-tbl elemnode prev next prevsib nextsib)
- (let* ((show-footer? (or (not (node-list-empty? prev))
- (not (node-list-empty? next))))
- (footer-sosofo
- (make element gi: "TR"
- attributes: (list
- (list "VALIGN" "middle"))
- (make element gi: "TD"
- attributes: (list
- (list "ALIGN" "left"))
- (if (not (node-list-empty? prev))
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "p")
- (list "HREF" (href-to prev)))
- (make element gi: "B"
- (make entity-ref name: "lt")
- (make entity-ref name: "lt")
- (make entity-ref name: "lt")
- (make entity-ref name: "nbsp")
- (element-title-sosofo prev)))
- (empty-sosofo)))
- (make element gi: "TD"
- attributes: (list
- (list "ALIGN" "right"))
- (if (not (node-list-empty? next))
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "n")
- (list "HREF" (href-to next)))
- (make element gi: "B"
- (element-title-sosofo next)
- (make entity-ref name: "nbsp")
- (make entity-ref name: "gt")
- (make entity-ref name: "gt")
- (make entity-ref name: "gt")))
- (empty-sosofo))))))
-
- (if show-footer?
- (make element gi: "TABLE"
- attributes: (list
- (list "CLASS" "navigation")
- (list "WIDTH" %gentext-nav-tblwidth%)
- (list "SUMMARY" "Navigation footer")
- (list "CELLPADDING" "2")
- (list "CELLSPACING" "2"))
- footer-sosofo)
- (empty-sosofo))))
-
-
-(define ($section-body$)
- (make sequence
- (make empty-element gi: "BR"
- attributes: (list (list "CLEAR" "all")))
- (make element gi: "DIV"
- attributes: (list (list "CLASS" (gi)))
- ($section-separator$)
- ($section-title$)
- (process-children))))
-
-</style-specification-body>
-</style-specification>
-<external-specification id="docbook" document="dbstyle">
-</style-sheet>
+++ /dev/null
-<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
-<!ENTITY dbstyle PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
-]>
-
-<style-sheet>
-<style-specification use="docbook">
-<style-specification-body>
-
-(define gtkdoc-version "")
-(define gtkdoc-bookname "")
-
-;; These are some customizations to the standard HTML output produced by the
-;; Modular DocBook Stylesheets.
-;; I've copied parts of a few functions from the stylesheets so these should
-;; be checked occasionally to ensure they are up to date.
-;;
-;; The last check was with version 1.40 of the stylesheets.
-;; It will not work with versions < 1.19 since the $shade-verbatim-attr$
-;; function was added then. Versions 1.19 to 1.39 may be OK, if you're lucky!
-
-;;(define %generate-book-toc% #f)
-
-;; If a Chapter has role="no-toc" we don't generate a table of contents.
-;; This is useful if a better contents page has been added manually, e.g. for
-;; the GTK+ Widgets & Objects page. (But it is a bit of a hack.)
-(define ($generate-chapter-toc$)
- (not (equal? (attribute-string (normalize "role") (current-node)) "no-toc")))
-
-(define %chapter-autolabel%
- ;; Are chapters enumerated?
- #f)
-
-(define %use-id-as-filename% #t)
-
-(define %html-ext% ".html")
-
-(define ($user-html-header$ #!optional
- (home (empty-node-list))
- (up (empty-node-list))
- (prev (empty-node-list))
- (next (empty-node-list)))
- (make sequence
- (if (not (string=? gtkdoc-version ""))
- (make empty-element gi: "META"
- attributes: (list
- (list "NAME" "GENERATOR")
- (list "CONTENT" (string-append
- "GTK-Doc V"
- gtkdoc-version
- " (SGML mode)"))))
- (empty-sosofo))
- (make element gi: "STYLE"
- attributes: (list (list "TYPE" "text/css"))
- (literal ".synopsis, .classsynopsis {
- background: #eeeeee;
- border: solid 1px #aaaaaa;
- padding: 0.5em;
-}
-.programlisting {
- background: #eeeeff;
- border: solid 1px #aaaaff;
- padding: 0.5em;
-}
-.variablelist {
- padding: 4px;
- margin-left: 3em;
-}
-.navigation {
- background: #ffeeee;
- border: solid 1px #ffaaaa;
- margin-top: 0.5em;
- margin-bottom: 0.5em;
-}
-.navigation a {
- color: #770000;
-}
-.navigation a:visited {
- color: #550000;
-}
-.navigation .title {
- font-size: 200%;
-}"))))
-
-
-(mode book-titlepage-recto-mode
- (element title
- (make element gi: "TABLE"
- attributes: (list
- (list "CLASS" "navigation")
- (list "WIDTH" %gentext-nav-tblwidth%)
- (list "CELLPADDING" "2")
- (list "CELLSPACING" "0"))
- (make element gi: "TR"
- (make element gi: "TH"
- attributes: (list
- (list "ALIGN" "center")
- (list "VALIGN" "MIDDLE"))
- (make element gi: "P"
- attributes: (list (list "CLASS" (gi)))
- (process-children-trim)
- (make empty-element gi: "A"
- attributes: (list (list "NAME" (element-id))))))))))
-
-(define (book-titlepage-separator side)
- (empty-sosofo))
-
-
-;; This overrides the variablelist definition (copied from 1.76,
-;; dblists.dsl). It changes the table background color, cell spacing
-;; and cell padding.
-;;
-;; I have also removed the code to handle the non-table case.
-(element variablelist
- (make sequence
- (if %spacing-paras%
- (make element gi: "P" (empty-sosofo))
- (empty-sosofo))
- (para-check)
-
- (make element gi: "TABLE"
- attributes: '(("CLASS" "variablelist")
- ("BORDER" "0")
- ("CELLSPACING" "0")
- ("CELLPADDING" "4"))
- (if %html40%
- (make element gi: "TBODY"
- (with-mode variablelist-table
- (process-children)))
- (with-mode variablelist-table
- (process-children))))
- (para-check 'restart)))
-
-(mode variablelist-table
- (element (variablelist title)
- (make element gi: "TR"
- attributes: '(("CLASS" "TITLE"))
- (make element gi: "TH"
- attributes: '(("ALIGN" "LEFT")
- ("VALIGN" "TOP")
- ("COLSPAN" "2"))
- (process-children))))
-
- (element varlistentry
- (let* ((terms (select-elements (children (current-node))
- (normalize "term")))
- (listitem (select-elements (children (current-node))
- (normalize "listitem"))))
-
- (make element gi: "TR"
- (make element gi: "TD"
- attributes: '(("ALIGN" "LEFT")
- ("VALIGN" "TOP"))
- (make empty-element gi: "A"
- attributes: (list
- (list "NAME" (element-id))))
- (process-node-list terms))
- (make element gi: "TD"
- attributes: '(("ALIGN" "LEFT")
- ("VALIGN" "TOP"))
- (process-node-list listitem)))))
-
- (element (varlistentry term)
- (make sequence
- (if %css-decoration%
- (make element gi: "SPAN"
- attributes: '(("STYLE" "white-space: nowrap"))
- (process-children-trim))
- (make element gi: "NOBR"
- (process-children-trim)))
- (if (not (last-sibling?))
- (literal ", ")
- (literal ""))))
-
- (element (varlistentry listitem)
- (process-children))
-)
-
-
-;; This overrides the refsect2 definition (copied from 1.20, dbrfntry.dsl).
-;; It puts a horizontal rule before each function/struct/... description,
-;; except the first one in the refsect1.
-(element refsect2
- (make sequence
- (if (first-sibling?)
- (empty-sosofo)
- (make empty-element gi: "HR"))
- ($block-container$)))
-
-;; Override the book declaration, so that we generate a crossreference
-;; for the book
-
-(element book
- (let* ((bookinfo (select-elements (children (current-node)) (normalize "bookinfo")))
- (ititle (select-elements (children bookinfo) (normalize "title")))
- (title (if (node-list-empty? ititle)
- (select-elements (children (current-node)) (normalize "title"))
- (node-list-first ititle)))
- (nl (titlepage-info-elements (current-node) bookinfo))
- (tsosofo (with-mode head-title-mode
- (process-node-list title)))
- (dedication (select-elements (children (current-node)) (normalize "dedication"))))
- (make sequence
- (html-document
- tsosofo
- (make element gi: "DIV"
- attributes: '(("CLASS" "BOOK"))
- (if %generate-book-titlepage%
- (make sequence
- (book-titlepage nl 'recto)
- (book-titlepage nl 'verso))
- (empty-sosofo))
-
- (if (node-list-empty? dedication)
- (empty-sosofo)
- (with-mode dedication-page-mode
- (process-node-list dedication)))
-
- (if (not (generate-toc-in-front))
- (process-children)
- (empty-sosofo))
-
- (if %generate-book-toc%
- (build-toc (current-node) (toc-depth (current-node)))
- (empty-sosofo))
-
- ;; (let loop ((gilist %generate-book-lot-list%))
- ;; (if (null? gilist)
- ;; (empty-sosofo)
- ;; (if (not (node-list-empty?
- ;; (select-elements (descendants (current-node))
- ;; (car gilist))))
- ;; (make sequence
- ;; (build-lot (current-node) (car gilist))
- ;; (loop (cdr gilist)))
- ;; (loop (cdr gilist)))))
-
- (if (generate-toc-in-front)
- (process-children)
- (empty-sosofo))))
- (make entity
- system-id: "index.sgml"
- (with-mode generate-index-mode
- (process-children))))))
-
-;; Mode for generating cross references
-
-(define (process-child-elements)
- (process-node-list
- (node-list-map (lambda (snl)
- (if (equal? (node-property 'class-name snl) 'element)
- snl
- (empty-node-list)))
- (children (current-node)))))
-
-(mode generate-index-mode
- (element anchor
- (if (attribute-string "href" (current-node))
- (empty-sosofo)
- (make formatting-instruction data:
- (string-append "\less-than-sign;ANCHOR id =\""
- (attribute-string "id" (current-node))
- "\" href=\""
- (if (not (string=? gtkdoc-bookname ""))
- (string-append gtkdoc-bookname "/")
- "")
- (href-to (current-node))
- "\"\greater-than-sign;
-"))))
-
- ;; We also want to be able to link to complete RefEntry.
- (element refentry
- (make sequence
- (make formatting-instruction data:
- (string-append "\less-than-sign;ANCHOR id =\""
- (attribute-string "id" (current-node))
- "\" href=\""
- (if (not (string=? gtkdoc-bookname ""))
- (string-append gtkdoc-bookname "/")
- "")
- (href-to (current-node))
- "\"\greater-than-sign;
-"))
- (process-child-elements)))
-
- (default
- (process-child-elements)))
-
-;; For hypertext links for which no target is found in the document, we output
-;; our own special tag which we use later to resolve cross-document links.
-(element link
- (let* ((target (element-with-id (attribute-string (normalize "linkend")))))
- (if (node-list-empty? target)
- (make element gi: "GTKDOCLINK"
- attributes: (list
- (list "HREF" (attribute-string (normalize "linkend"))))
- (process-children))
- (make element gi: "A"
- attributes: (list
- (list "HREF" (href-to target)))
- (process-children)))))
-
-
-;; This overrides default-header-nav-tbl-noff (copied from 1.20, dbnavig.dsl).
-;; I want 'Home' and 'Up' links at the top of each page, and white text on
-;; black.
-(define (default-header-nav-tbl-noff elemnode prev next prevsib nextsib)
- (let* ((up (parent elemnode))
- (home (nav-home elemnode))
- (show-title? (nav-banner? elemnode))
- (title-sosofo
- (make element gi: "TH"
- attributes: (list
- (list "WIDTH" "100%")
- (list "align" "center"))
- (if show-title?
- (nav-banner elemnode)
- (empty-sosofo))))
- (show-banner? (or show-title?
- (not (node-list-empty? prev))
- (not (node-list-empty? next))
- (nav-context? elemnode)))
- (banner-sosofo
- (make element gi: "TR"
- attributes: (list
- (list "VALIGN" "middle"))
- (if (not (node-list-empty? prev))
- (make element gi: "TD"
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "p")
- (list "HREF"
- (href-to prev)))
- (make empty-element gi: "IMG"
- attributes: (list
- (list "SRC" "left.png")
- (list "WIDTH" "16")
- (list "HEIGHT" "16")
- (list "BORDER" "0")
- (list "ALT" "Prev")))))
- (empty-sosofo))
- (if (nav-up? elemnode)
- (make element gi: "TD"
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "u")
- (list "HREF"
- (href-to up)))
- (make empty-element gi: "IMG"
- attributes: (list
- (list "SRC" "up.png")
- (list "WIDTH" "16")
- (list "HEIGHT" "16")
- (list "BORDER" "0")
- (list "ALT" "Up")))))
- (empty-sosofo))
- (if (nav-home? elemnode)
- (make element gi: "TD"
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "h")
- (list "HREF"
- (href-to home)))
- (make empty-element gi: "IMG"
- attributes: (list
- (list "SRC" "home.png")
- (list "WIDTH" "16")
- (list "HEIGHT" "16")
- (list "BORDER" "0")
- (list "ALT" "Home")))))
- (empty-sosofo))
- title-sosofo
- (if (not (node-list-empty? next))
- (make element gi: "TD"
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "n")
- (list "HREF"
- (href-to next)))
- (make empty-element gi: "IMG"
- attributes: (list
- (list "SRC" "right.png")
- (list "WIDTH" "16")
- (list "HEIGHT" "16")
- (list "BORDER" "0")
- (list "ALT" "Next")))))
- (empty-sosofo)))))
-
- (if show-banner?
- (make element gi: "TABLE"
- attributes: (list
- (list "WIDTH" %gentext-nav-tblwidth%)
- (list "CLASS" "navigation")
- (list "SUMMARY" "Navigation header")
- (list "CELLPADDING" "2")
- (list "CELLSPACING" "2"))
- banner-sosofo)
- (empty-sosofo))))
-
-;; This overrides default-footer-nav-tbl (copied from 1.20, dbnavig.dsl).
-;; It matches the header above.
-(define (default-footer-nav-tbl elemnode prev next prevsib nextsib)
- (let* ((show-footer? (or (not (node-list-empty? prev))
- (not (node-list-empty? next))))
- (footer-sosofo
- (make element gi: "TR"
- attributes: (list
- (list "VALIGN" "middle"))
- (make element gi: "TD"
- attributes: (list
- (list "ALIGN" "left"))
- (if (not (node-list-empty? prev))
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "p")
- (list "HREF" (href-to prev)))
- (make element gi: "B"
- (make entity-ref name: "lt")
- (make entity-ref name: "lt")
- (make entity-ref name: "lt")
- (make entity-ref name: "nbsp")
- (element-title-sosofo prev)))
- (empty-sosofo)))
- (make element gi: "TD"
- attributes: (list
- (list "ALIGN" "right"))
- (if (not (node-list-empty? next))
- (make element gi: "A"
- attributes: (list
- (list "ACCESSKEY" "n")
- (list "HREF" (href-to next)))
- (make element gi: "B"
- (element-title-sosofo next)
- (make entity-ref name: "nbsp")
- (make entity-ref name: "gt")
- (make entity-ref name: "gt")
- (make entity-ref name: "gt")))
- (empty-sosofo))))))
-
- (if show-footer?
- (make element gi: "TABLE"
- attributes: (list
- (list "CLASS" "navigation")
- (list "WIDTH" %gentext-nav-tblwidth%)
- (list "SUMMARY" "Navigation footer")
- (list "CELLPADDING" "2")
- (list "CELLSPACING" "2"))
- footer-sosofo)
- (empty-sosofo))))
-
-
-(define ($section-body$)
- (make sequence
- (make empty-element gi: "BR"
- attributes: (list (list "CLEAR" "all")))
- (make element gi: "DIV"
- attributes: (list (list "CLASS" (gi)))
- ($section-separator$)
- ($section-title$)
- (process-children))))
-
-</style-specification-body>
-</style-specification>
-<external-specification id="docbook" document="dbstyle">
-</style-sheet>
$(HTML_IMAGES) \
$(SETUP_FILES)
-DOC_STAMPS=setup-build.stamp scan-build.stamp tmpl-build.stamp sgml-build.stamp \
+DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \
html-build.stamp pdf-build.stamp \
- tmpl.stamp sgml.stamp html.stamp pdf.stamp
+ sgml.stamp html.stamp pdf.stamp
SCANOBJ_FILES = \
$(DOC_MODULE).args \
#### setup ####
-GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_$(V))
-GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_@AM_V@)
+GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_@AM_DEFAULT_V@)
GTK_DOC_V_SETUP_0=@echo " DOC Preparing build";
setup-build.stamp:
-$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \
- if test "x$$files" != "x" ; then \
- for file in $$files ; do \
- destdir=`dirname $(abs_builddir)/$$file` ;\
- test -d "$$destdir" || mkdir -p "$$destdir"; \
- test -f $(abs_srcdir)/$$file && \
- cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
- done; \
- fi; \
- test -d $(abs_srcdir)/tmpl && \
- { cp -pR $(abs_srcdir)/tmpl $(abs_builddir)/; \
- chmod -R u+w $(abs_builddir)/tmpl; } \
+ files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \
+ if test "x$$files" != "x" ; then \
+ for file in $$files ; do \
+ destdir=`dirname $(abs_builddir)/$$file`; \
+ test -d "$$destdir" || mkdir -p "$$destdir"; \
+ test -f $(abs_srcdir)/$$file && \
+ cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
+ done; \
+ fi; \
fi
$(AM_V_at)touch setup-build.stamp
#### scan ####
-GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_$(V))
-GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_@AM_V@)
+GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_@AM_DEFAULT_V@)
GTK_DOC_V_SCAN_0=@echo " DOC Scanning header files";
-GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_$(V))
-GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_@AM_V@)
+GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_@AM_DEFAULT_V@)
GTK_DOC_V_INTROSPECT_0=@echo " DOC Introspecting gobjects";
scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
$(GTK_DOC_V_SCAN)_source_dir='' ; \
for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)
$(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
- scanobj_options=""; \
- gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \
- if test "$$?" = "0"; then \
- if test "x$(V)" = "x1"; then \
- scanobj_options="--verbose"; \
- fi; \
+ scanobj_options=""; \
+ gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \
+ if test "$$?" = "0"; then \
+ if test "x$(V)" = "x1"; then \
+ scanobj_options="--verbose"; \
fi; \
- CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
- gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \
+ fi; \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
+ gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \
else \
- for i in $(SCANOBJ_FILES) ; do \
- test -f $$i || touch $$i ; \
- done \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
fi
$(AM_V_at)touch scan-build.stamp
$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp
@true
-#### templates ####
-
-GTK_DOC_V_TMPL=$(GTK_DOC_V_TMPL_$(V))
-GTK_DOC_V_TMPL_=$(GTK_DOC_V_TMPL_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_TMPL_0=@echo " DOC Rebuilding template files";
-
-tmpl-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
- $(GTK_DOC_V_TMPL)gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS)
- $(AM_V_at)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- if test -w $(abs_srcdir) ; then \
- cp -pR $(abs_builddir)/tmpl $(abs_srcdir)/; \
- fi \
- fi
- $(AM_V_at)touch tmpl-build.stamp
-
-tmpl.stamp: tmpl-build.stamp
- @true
-
-$(srcdir)/tmpl/*.sgml:
- @true
-
#### xml ####
-GTK_DOC_V_XML=$(GTK_DOC_V_XML_$(V))
-GTK_DOC_V_XML_=$(GTK_DOC_V_XML_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_XML=$(GTK_DOC_V_XML_@AM_V@)
+GTK_DOC_V_XML_=$(GTK_DOC_V_XML_@AM_DEFAULT_V@)
GTK_DOC_V_XML_0=@echo " DOC Building XML";
-sgml-build.stamp: tmpl.stamp $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files) xml/gtkdocentities.ent
- -$(GTK_DOC_V_XML)chmod -R u+w $(srcdir) && _source_dir='' ; \
+sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent
+ $(GTK_DOC_V_XML)_source_dir='' ; \
for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)
$(AM_V_at)touch sgml-build.stamp
#### html ####
-GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_$(V))
-GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_@AM_V@)
+GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_@AM_DEFAULT_V@)
GTK_DOC_V_HTML_0=@echo " DOC Building HTML";
-GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_$(V))
-GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_@AM_V@)
+GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_@AM_DEFAULT_V@)
GTK_DOC_V_XREF_0=@echo " DOC Fixing cross-references";
html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files)
cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
-@test "x$(HTML_IMAGES)" = "x" || \
for file in $(HTML_IMAGES) ; do \
- if test -f $(abs_srcdir)/$$file ; then \
- cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
- fi; \
- if test -f $(abs_builddir)/$$file ; then \
- cp $(abs_builddir)/$$file $(abs_builddir)/html; \
- fi; \
+ test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
+ test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$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
#### pdf ####
-GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_$(V))
-GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_@AM_V@)
+GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_@AM_DEFAULT_V@)
GTK_DOC_V_PDF_0=@echo " DOC Building PDF";
pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files)
$(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
rm -f $(SETUP_FILES) $(DOC_MODULE).types; \
- rm -rf tmpl; \
fi
maintainer-clean-local:
endif
dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local
- @mkdir $(distdir)/tmpl
@mkdir $(distdir)/html
- @-cp ./tmpl/*.sgml $(distdir)/tmpl
@cp ./html/* $(distdir)/html
@-cp ./$(DOC_MODULE).pdf $(distdir)/
@-cp ./$(DOC_MODULE).types $(distdir)/
$(HTML_IMAGES) \
$(SETUP_FILES)
-DOC_STAMPS=setup-build.stamp scan-build.stamp tmpl-build.stamp sgml-build.stamp \
+DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \
html-build.stamp pdf-build.stamp \
- tmpl.stamp sgml.stamp html.stamp pdf.stamp
+ sgml.stamp html.stamp pdf.stamp
SCANOBJ_FILES = \
$(DOC_MODULE).args \
#### setup ####
-GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_$(V))
-GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_@AM_V@)
+GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_@AM_DEFAULT_V@)
GTK_DOC_V_SETUP_0=@echo " DOC Preparing build";
setup-build.stamp:
-$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \
- if test "x$$files" != "x" ; then \
- for file in $$files ; do \
- destdir=`dirname $(abs_builddir)/$$file` ;\
- test -d "$$destdir" || mkdir -p "$$destdir"; \
- test -f $(abs_srcdir)/$$file && \
- cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
- done; \
- fi; \
- test -d $(abs_srcdir)/tmpl && \
- { cp -pR $(abs_srcdir)/tmpl $(abs_builddir)/; \
- chmod -R u+w $(abs_builddir)/tmpl; } \
+ files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \
+ if test "x$$files" != "x" ; then \
+ for file in $$files ; do \
+ destdir=`dirname $(abs_builddir)/$$file`; \
+ test -d "$$destdir" || mkdir -p "$$destdir"; \
+ test -f $(abs_srcdir)/$$file && \
+ cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
+ done; \
+ fi; \
fi
$(AM_V_at)touch setup-build.stamp
#### scan ####
-GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_$(V))
-GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_@AM_V@)
+GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_@AM_DEFAULT_V@)
GTK_DOC_V_SCAN_0=@echo " DOC Scanning header files";
-GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_$(V))
-GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_@AM_V@)
+GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_@AM_DEFAULT_V@)
GTK_DOC_V_INTROSPECT_0=@echo " DOC Introspecting gobjects";
scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
$(GTK_DOC_V_SCAN)_source_dir='' ; \
for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)
$(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
- scanobj_options=""; \
- gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \
- if test "$$?" = "0"; then \
- if test "x$(V)" = "x1"; then \
- scanobj_options="--verbose"; \
- fi; \
+ scanobj_options=""; \
+ gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \
+ if test "$$?" = "0"; then \
+ if test "x$(V)" = "x1"; then \
+ scanobj_options="--verbose"; \
fi; \
- CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
- gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \
+ fi; \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
+ gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \
else \
- for i in $(SCANOBJ_FILES) ; do \
- test -f $$i || touch $$i ; \
- done \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
fi
$(AM_V_at)touch scan-build.stamp
$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp
@true
-#### templates ####
-
-GTK_DOC_V_TMPL=$(GTK_DOC_V_TMPL_$(V))
-GTK_DOC_V_TMPL_=$(GTK_DOC_V_TMPL_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_TMPL_0=@echo " DOC Rebuilding template files";
-
-tmpl-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
- $(GTK_DOC_V_TMPL)gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS)
- $(AM_V_at)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- if test -w $(abs_srcdir) ; then \
- cp -pR $(abs_builddir)/tmpl $(abs_srcdir)/; \
- fi \
- fi
- $(AM_V_at)touch tmpl-build.stamp
-
-tmpl.stamp: tmpl-build.stamp
- @true
-
-$(srcdir)/tmpl/*.sgml:
- @true
-
#### xml ####
-GTK_DOC_V_XML=$(GTK_DOC_V_XML_$(V))
-GTK_DOC_V_XML_=$(GTK_DOC_V_XML_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_XML=$(GTK_DOC_V_XML_@AM_V@)
+GTK_DOC_V_XML_=$(GTK_DOC_V_XML_@AM_DEFAULT_V@)
GTK_DOC_V_XML_0=@echo " DOC Building XML";
-sgml-build.stamp: tmpl.stamp $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files) xml/gtkdocentities.ent
- -$(GTK_DOC_V_XML)chmod -R u+w $(srcdir) && _source_dir='' ; \
+sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent
+ $(GTK_DOC_V_XML)_source_dir='' ; \
for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)
$(AM_V_at)touch sgml-build.stamp
#### html ####
-GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_$(V))
-GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_@AM_V@)
+GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_@AM_DEFAULT_V@)
GTK_DOC_V_HTML_0=@echo " DOC Building HTML";
-GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_$(V))
-GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_@AM_V@)
+GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_@AM_DEFAULT_V@)
GTK_DOC_V_XREF_0=@echo " DOC Fixing cross-references";
html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files)
cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
-@test "x$(HTML_IMAGES)" = "x" || \
for file in $(HTML_IMAGES) ; do \
- if test -f $(abs_srcdir)/$$file ; then \
- cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
- fi; \
- if test -f $(abs_builddir)/$$file ; then \
- cp $(abs_builddir)/$$file $(abs_builddir)/html; \
- fi; \
+ test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
+ test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$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
#### pdf ####
-GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_$(V))
-GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_@AM_V@)
+GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_@AM_DEFAULT_V@)
GTK_DOC_V_PDF_0=@echo " DOC Building PDF";
pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files)
$(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
rm -f $(SETUP_FILES) $(DOC_MODULE).types; \
- rm -rf tmpl; \
fi
maintainer-clean-local:
endif
dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local
- @mkdir $(distdir)/tmpl
@mkdir $(distdir)/html
- @-cp ./tmpl/*.sgml $(distdir)/tmpl
@cp ./html/* $(distdir)/html
@-cp ./$(DOC_MODULE).pdf $(distdir)/
@-cp ./$(DOC_MODULE).types $(distdir)/
+++ /dev/null
-# -*- mode: makefile -*-
-
-####################################
-# Everything below here is generic #
-####################################
-
-if GTK_DOC_USE_LIBTOOL
-GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
-GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS)
-GTKDOC_RUN = $(LIBTOOL) --mode=execute
-else
-GTKDOC_CC = $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
-GTKDOC_LD = $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS)
-GTKDOC_RUN =
-endif
-
-# We set GPATH here; this gives us semantics for GNU make
-# which are more like other make's VPATH, when it comes to
-# whether a source that is a target of one rule is then
-# searched for in VPATH/GPATH.
-#
-GPATH = $(srcdir)
-
-TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
-
-SETUP_FILES = \
- $(content_files) \
- $(expand_content_files) \
- $(DOC_MAIN_SGML_FILE) \
- $(DOC_MODULE)-sections.txt \
- $(DOC_MODULE)-overrides.txt
-
-EXTRA_DIST += \
- $(HTML_IMAGES) \
- $(SETUP_FILES)
-
-DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \
- html-build.stamp pdf-build.stamp \
- sgml.stamp html.stamp pdf.stamp
-
-SCANOBJ_FILES = \
- $(DOC_MODULE).args \
- $(DOC_MODULE).hierarchy \
- $(DOC_MODULE).interfaces \
- $(DOC_MODULE).prerequisites \
- $(DOC_MODULE).signals
-
-REPORT_FILES = \
- $(DOC_MODULE)-undocumented.txt \
- $(DOC_MODULE)-undeclared.txt \
- $(DOC_MODULE)-unused.txt
-
-gtkdoc-check.test: Makefile
- $(AM_V_GEN)echo "#!/bin/sh -e" > $@; \
- echo "$(GTKDOC_CHECK_PATH) || exit 1" >> $@; \
- chmod +x $@
-
-CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) gtkdoc-check.test
-
-if GTK_DOC_BUILD_HTML
-HTML_BUILD_STAMP=html-build.stamp
-else
-HTML_BUILD_STAMP=
-endif
-if GTK_DOC_BUILD_PDF
-PDF_BUILD_STAMP=pdf-build.stamp
-else
-PDF_BUILD_STAMP=
-endif
-
-all-gtk-doc: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
-.PHONY: all-gtk-doc
-
-if ENABLE_GTK_DOC
-all-local: all-gtk-doc
-endif
-
-docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
-
-$(REPORT_FILES): sgml-build.stamp
-
-#### setup ####
-
-GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_$(V))
-GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_SETUP_0=@echo " DOC Preparing build";
-
-setup-build.stamp:
- -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \
- if test "x$$files" != "x" ; then \
- for file in $$files ; do \
- destdir=`dirname $(abs_builddir)/$$file`; \
- test -d "$$destdir" || mkdir -p "$$destdir"; \
- test -f $(abs_srcdir)/$$file && \
- cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
- done; \
- fi; \
- fi
- $(AM_V_at)touch setup-build.stamp
-
-
-#### scan ####
-
-GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_$(V))
-GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_SCAN_0=@echo " DOC Scanning header files";
-
-GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_$(V))
-GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_INTROSPECT_0=@echo " DOC Introspecting gobjects";
-
-scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
- $(GTK_DOC_V_SCAN)_source_dir='' ; \
- for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
- done ; \
- gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)
- $(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
- scanobj_options=""; \
- gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \
- if test "$$?" = "0"; then \
- if test "x$(V)" = "x1"; then \
- scanobj_options="--verbose"; \
- fi; \
- fi; \
- CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
- gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \
- else \
- for i in $(SCANOBJ_FILES) ; do \
- test -f $$i || touch $$i ; \
- done \
- fi
- $(AM_V_at)touch scan-build.stamp
-
-$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp
- @true
-
-#### xml ####
-
-GTK_DOC_V_XML=$(GTK_DOC_V_XML_$(V))
-GTK_DOC_V_XML_=$(GTK_DOC_V_XML_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_XML_0=@echo " DOC Building XML";
-
-sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent
- $(GTK_DOC_V_XML)_source_dir='' ; \
- for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
- done ; \
- gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)
- $(AM_V_at)touch sgml-build.stamp
-
-sgml.stamp: sgml-build.stamp
- @true
-
-xml/gtkdocentities.ent: Makefile
- $(GTK_DOC_V_XML)$(MKDIR_P) $(@D) && ( \
- echo "<!ENTITY package \"$(PACKAGE)\">"; \
- echo "<!ENTITY package_bugreport \"$(PACKAGE_BUGREPORT)\">"; \
- echo "<!ENTITY package_name \"$(PACKAGE_NAME)\">"; \
- echo "<!ENTITY package_string \"$(PACKAGE_STRING)\">"; \
- echo "<!ENTITY package_tarname \"$(PACKAGE_TARNAME)\">"; \
- echo "<!ENTITY package_url \"$(PACKAGE_URL)\">"; \
- echo "<!ENTITY package_version \"$(PACKAGE_VERSION)\">"; \
- ) > $@
-
-#### html ####
-
-GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_$(V))
-GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_HTML_0=@echo " DOC Building HTML";
-
-GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_$(V))
-GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_XREF_0=@echo " DOC Fixing cross-references";
-
-html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files)
- $(GTK_DOC_V_HTML)rm -rf html && mkdir html && \
- mkhtml_options=""; \
- gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-verbose"; \
- if test "$$?" = "0"; then \
- if test "x$(V)" = "x1"; then \
- mkhtml_options="$$mkhtml_options --verbose"; \
- fi; \
- fi; \
- gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-path"; \
- if test "$$?" = "0"; then \
- mkhtml_options="$$mkhtml_options --path=\"$(abs_srcdir)\""; \
- fi; \
- cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
- -@test "x$(HTML_IMAGES)" = "x" || \
- for file in $(HTML_IMAGES) ; do \
- if test -f $(abs_srcdir)/$$file ; then \
- cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
- fi; \
- if test -f $(abs_builddir)/$$file ; then \
- cp $(abs_builddir)/$$file $(abs_builddir)/html; \
- fi; \
- 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
-
-#### pdf ####
-
-GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_$(V))
-GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_PDF_0=@echo " DOC Building PDF";
-
-pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files)
- $(GTK_DOC_V_PDF)rm -f $(DOC_MODULE).pdf && \
- mkpdf_options=""; \
- gtkdoc-mkpdf 2>&1 --help | grep >/dev/null "\-\-verbose"; \
- if test "$$?" = "0"; then \
- if test "x$(V)" = "x1"; then \
- mkpdf_options="$$mkpdf_options --verbose"; \
- fi; \
- fi; \
- if test "x$(HTML_IMAGES)" != "x"; then \
- for img in $(HTML_IMAGES); do \
- part=`dirname $$img`; \
- echo $$mkpdf_options | grep >/dev/null "\-\-imgdir=$$part "; \
- if test $$? != 0; then \
- mkpdf_options="$$mkpdf_options --imgdir=$$part"; \
- fi; \
- done; \
- fi; \
- gtkdoc-mkpdf --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)
- $(AM_V_at)touch pdf-build.stamp
-
-##############
-
-clean-local:
- @rm -f *~ *.bak
- @rm -rf .libs
- @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \
- rm -f $(DOC_MODULE).types; \
- fi
- @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-sections" ; then \
- rm -f $(DOC_MODULE)-sections.txt; \
- fi
-
-distclean-local:
- @rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \
- $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
- @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- rm -f $(SETUP_FILES) $(DOC_MODULE).types; \
- fi
-
-maintainer-clean-local:
- @rm -rf xml html
-
-install-data-local:
- @installfiles=`echo $(builddir)/html/*`; \
- if test "$$installfiles" = '$(builddir)/html/*'; \
- then echo 1>&2 'Nothing to install' ; \
- else \
- if test -n "$(DOC_MODULE_VERSION)"; then \
- installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \
- else \
- installdir="$(DESTDIR)$(TARGET_DIR)"; \
- fi; \
- $(mkinstalldirs) $${installdir} ; \
- for i in $$installfiles; do \
- echo ' $(INSTALL_DATA) '$$i ; \
- $(INSTALL_DATA) $$i $${installdir}; \
- done; \
- if test -n "$(DOC_MODULE_VERSION)"; then \
- mv -f $${installdir}/$(DOC_MODULE).devhelp2 \
- $${installdir}/$(DOC_MODULE)-$(DOC_MODULE_VERSION).devhelp2; \
- fi; \
- $(GTKDOC_REBASE) --relative --dest-dir=$(DESTDIR) --html-dir=$${installdir}; \
- fi
-
-uninstall-local:
- @if test -n "$(DOC_MODULE_VERSION)"; then \
- installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \
- else \
- installdir="$(DESTDIR)$(TARGET_DIR)"; \
- fi; \
- rm -rf $${installdir}
-
-#
-# Require gtk-doc when making dist
-#
-if HAVE_GTK_DOC
-dist-check-gtkdoc: docs
-else
-dist-check-gtkdoc:
- @echo "*** gtk-doc is needed to run 'make dist'. ***"
- @echo "*** gtk-doc was not found when 'configure' ran. ***"
- @echo "*** please install gtk-doc and rerun 'configure'. ***"
- @false
-endif
-
-dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local
- @mkdir $(distdir)/html
- @cp ./html/* $(distdir)/html
- @-cp ./$(DOC_MODULE).pdf $(distdir)/
- @-cp ./$(DOC_MODULE).types $(distdir)/
- @-cp ./$(DOC_MODULE)-sections.txt $(distdir)/
- @cd $(distdir) && rm -f $(DISTCLEANFILES)
- @$(GTKDOC_REBASE) --online --relative --html-dir=$(distdir)/html
-
-.PHONY : dist-hook-local docs
+++ /dev/null
-# -*- mode: makefile -*-
-
-####################################
-# Everything below here is generic #
-####################################
-
-if GTK_DOC_USE_LIBTOOL
-GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
-GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS)
-GTKDOC_RUN = $(LIBTOOL) --mode=execute
-else
-GTKDOC_CC = $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
-GTKDOC_LD = $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS)
-GTKDOC_RUN =
-endif
-
-# We set GPATH here; this gives us semantics for GNU make
-# which are more like other make's VPATH, when it comes to
-# whether a source that is a target of one rule is then
-# searched for in VPATH/GPATH.
-#
-GPATH = $(srcdir)
-
-TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
-
-SETUP_FILES = \
- $(content_files) \
- $(expand_content_files) \
- $(DOC_MAIN_SGML_FILE) \
- $(DOC_MODULE)-sections.txt \
- $(DOC_MODULE)-overrides.txt
-
-EXTRA_DIST = \
- $(HTML_IMAGES) \
- $(SETUP_FILES)
-
-DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \
- html-build.stamp pdf-build.stamp \
- sgml.stamp html.stamp pdf.stamp
-
-SCANOBJ_FILES = \
- $(DOC_MODULE).args \
- $(DOC_MODULE).hierarchy \
- $(DOC_MODULE).interfaces \
- $(DOC_MODULE).prerequisites \
- $(DOC_MODULE).signals
-
-REPORT_FILES = \
- $(DOC_MODULE)-undocumented.txt \
- $(DOC_MODULE)-undeclared.txt \
- $(DOC_MODULE)-unused.txt
-
-gtkdoc-check.test: Makefile
- $(AM_V_GEN)echo "#!/bin/sh -e" > $@; \
- echo "$(GTKDOC_CHECK_PATH) || exit 1" >> $@; \
- chmod +x $@
-
-CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) gtkdoc-check.test
-
-if GTK_DOC_BUILD_HTML
-HTML_BUILD_STAMP=html-build.stamp
-else
-HTML_BUILD_STAMP=
-endif
-if GTK_DOC_BUILD_PDF
-PDF_BUILD_STAMP=pdf-build.stamp
-else
-PDF_BUILD_STAMP=
-endif
-
-all-gtk-doc: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
-.PHONY: all-gtk-doc
-
-if ENABLE_GTK_DOC
-all-local: all-gtk-doc
-endif
-
-docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP)
-
-$(REPORT_FILES): sgml-build.stamp
-
-#### setup ####
-
-GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_$(V))
-GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_SETUP_0=@echo " DOC Preparing build";
-
-setup-build.stamp:
- -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \
- if test "x$$files" != "x" ; then \
- for file in $$files ; do \
- destdir=`dirname $(abs_builddir)/$$file`; \
- test -d "$$destdir" || mkdir -p "$$destdir"; \
- test -f $(abs_srcdir)/$$file && \
- cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \
- done; \
- fi; \
- fi
- $(AM_V_at)touch setup-build.stamp
-
-
-#### scan ####
-
-GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_$(V))
-GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_SCAN_0=@echo " DOC Scanning header files";
-
-GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_$(V))
-GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_INTROSPECT_0=@echo " DOC Introspecting gobjects";
-
-scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
- $(GTK_DOC_V_SCAN)_source_dir='' ; \
- for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
- done ; \
- gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)
- $(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
- scanobj_options=""; \
- gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \
- if test "$$?" = "0"; then \
- if test "x$(V)" = "x1"; then \
- scanobj_options="--verbose"; \
- fi; \
- fi; \
- CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
- gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \
- else \
- for i in $(SCANOBJ_FILES) ; do \
- test -f $$i || touch $$i ; \
- done \
- fi
- $(AM_V_at)touch scan-build.stamp
-
-$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp
- @true
-
-#### xml ####
-
-GTK_DOC_V_XML=$(GTK_DOC_V_XML_$(V))
-GTK_DOC_V_XML_=$(GTK_DOC_V_XML_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_XML_0=@echo " DOC Building XML";
-
-sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent
- $(GTK_DOC_V_XML)_source_dir='' ; \
- for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
- done ; \
- gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)
- $(AM_V_at)touch sgml-build.stamp
-
-sgml.stamp: sgml-build.stamp
- @true
-
-xml/gtkdocentities.ent: Makefile
- $(GTK_DOC_V_XML)$(MKDIR_P) $(@D) && ( \
- echo "<!ENTITY package \"$(PACKAGE)\">"; \
- echo "<!ENTITY package_bugreport \"$(PACKAGE_BUGREPORT)\">"; \
- echo "<!ENTITY package_name \"$(PACKAGE_NAME)\">"; \
- echo "<!ENTITY package_string \"$(PACKAGE_STRING)\">"; \
- echo "<!ENTITY package_tarname \"$(PACKAGE_TARNAME)\">"; \
- echo "<!ENTITY package_url \"$(PACKAGE_URL)\">"; \
- echo "<!ENTITY package_version \"$(PACKAGE_VERSION)\">"; \
- ) > $@
-
-#### html ####
-
-GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_$(V))
-GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_HTML_0=@echo " DOC Building HTML";
-
-GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_$(V))
-GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_XREF_0=@echo " DOC Fixing cross-references";
-
-html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files)
- $(GTK_DOC_V_HTML)rm -rf html && mkdir html && \
- mkhtml_options=""; \
- gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-verbose"; \
- if test "$$?" = "0"; then \
- if test "x$(V)" = "x1"; then \
- mkhtml_options="$$mkhtml_options --verbose"; \
- fi; \
- fi; \
- gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-path"; \
- if test "$$?" = "0"; then \
- mkhtml_options="$$mkhtml_options --path=\"$(abs_srcdir)\""; \
- fi; \
- cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
- -@test "x$(HTML_IMAGES)" = "x" || \
- for file in $(HTML_IMAGES) ; do \
- if test -f $(abs_srcdir)/$$file ; then \
- cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
- fi; \
- if test -f $(abs_builddir)/$$file ; then \
- cp $(abs_builddir)/$$file $(abs_builddir)/html; \
- fi; \
- 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
-
-#### pdf ####
-
-GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_$(V))
-GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_$(AM_DEFAULT_VERBOSITY))
-GTK_DOC_V_PDF_0=@echo " DOC Building PDF";
-
-pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files)
- $(GTK_DOC_V_PDF)rm -f $(DOC_MODULE).pdf && \
- mkpdf_options=""; \
- gtkdoc-mkpdf 2>&1 --help | grep >/dev/null "\-\-verbose"; \
- if test "$$?" = "0"; then \
- if test "x$(V)" = "x1"; then \
- mkpdf_options="$$mkpdf_options --verbose"; \
- fi; \
- fi; \
- if test "x$(HTML_IMAGES)" != "x"; then \
- for img in $(HTML_IMAGES); do \
- part=`dirname $$img`; \
- echo $$mkpdf_options | grep >/dev/null "\-\-imgdir=$$part "; \
- if test $$? != 0; then \
- mkpdf_options="$$mkpdf_options --imgdir=$$part"; \
- fi; \
- done; \
- fi; \
- gtkdoc-mkpdf --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)
- $(AM_V_at)touch pdf-build.stamp
-
-##############
-
-clean-local:
- @rm -f *~ *.bak
- @rm -rf .libs
- @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \
- rm -f $(DOC_MODULE).types; \
- fi
- @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-sections" ; then \
- rm -f $(DOC_MODULE)-sections.txt; \
- fi
-
-distclean-local:
- @rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \
- $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
- @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- rm -f $(SETUP_FILES) $(DOC_MODULE).types; \
- fi
-
-maintainer-clean-local:
- @rm -rf xml html
-
-install-data-local:
- @installfiles=`echo $(builddir)/html/*`; \
- if test "$$installfiles" = '$(builddir)/html/*'; \
- then echo 1>&2 'Nothing to install' ; \
- else \
- if test -n "$(DOC_MODULE_VERSION)"; then \
- installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \
- else \
- installdir="$(DESTDIR)$(TARGET_DIR)"; \
- fi; \
- $(mkinstalldirs) $${installdir} ; \
- for i in $$installfiles; do \
- echo ' $(INSTALL_DATA) '$$i ; \
- $(INSTALL_DATA) $$i $${installdir}; \
- done; \
- if test -n "$(DOC_MODULE_VERSION)"; then \
- mv -f $${installdir}/$(DOC_MODULE).devhelp2 \
- $${installdir}/$(DOC_MODULE)-$(DOC_MODULE_VERSION).devhelp2; \
- fi; \
- $(GTKDOC_REBASE) --relative --dest-dir=$(DESTDIR) --html-dir=$${installdir}; \
- fi
-
-uninstall-local:
- @if test -n "$(DOC_MODULE_VERSION)"; then \
- installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \
- else \
- installdir="$(DESTDIR)$(TARGET_DIR)"; \
- fi; \
- rm -rf $${installdir}
-
-#
-# Require gtk-doc when making dist
-#
-if HAVE_GTK_DOC
-dist-check-gtkdoc: docs
-else
-dist-check-gtkdoc:
- @echo "*** gtk-doc is needed to run 'make dist'. ***"
- @echo "*** gtk-doc was not found when 'configure' ran. ***"
- @echo "*** please install gtk-doc and rerun 'configure'. ***"
- @false
-endif
-
-dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local
- @mkdir $(distdir)/html
- @cp ./html/* $(distdir)/html
- @-cp ./$(DOC_MODULE).pdf $(distdir)/
- @-cp ./$(DOC_MODULE).types $(distdir)/
- @-cp ./$(DOC_MODULE)-sections.txt $(distdir)/
- @cd $(distdir) && rm -f $(DISTCLEANFILES)
- @$(GTKDOC_REBASE) --online --relative --html-dir=$(distdir)/html
-
-.PHONY : dist-hook-local docs
+++ /dev/null
-# -*- mode: rpm-spec -*-
-
-Summary: GTK+ DocBook Documentation Generator
-Name: gtk-doc
-Version: 1.25
-Release: 1
-License: GPL
-Group: Utilities/Text
-Source: ftp://ftp.gtk.org/pub/gtk/v1.1/docs/rdp/gtk-doc-%{version}.tar.gz
-BuildRoot: /var/tmp/%{name}-%{version}-root
-URL: http://www.gtk.org/rdp/
-BuildArchitectures: noarch
-Requires: openjade
-Requires: perl >= 5.6.0
-Requires: libxslt
-Requires: docbook-dtds
-Requires: docbook-style-xsl
-Provides: perl(gtkdoc-common.pl)
-
-BuildRequires: perl, openjade, libxslt, docbook-dtds, docbook-style-xsl
-
-%description
-gtk-doc is a set of perl scripts that generate API reference documention in
-DocBook format. It can extract documentation from source code comments in a
-manner similar to java-doc. It is used to generate the documentation for
-GLib, Gtk+, and GNOME.
-
-%prep
-%setup -q
-
-# Move this doc file to avoid name collisions
-mv doc/README doc/README.docs
-
-%build
-CFLAGS="$RPM_OPT_FLAGS" ./configure $MYARCH_FLAGS --prefix=%{_prefix} \
- --sysconfdir=%{_sysconfdir} --datadir=%{_datadir}
-
-make
-
-%install
-rm -rf $RPM_BUILD_ROOT
-
-make prefix=$RPM_BUILD_ROOT%{_prefix} \
- sysconfdir=$RPM_BUILD_ROOT%{_sysconfdir} \
- datadir=$RPM_BUILD_ROOT%{_datadir} install
-
-%clean
-rm -rf $RPM_BUILD_ROOT
-
-%files
-%defattr(-, root, root)
-
-%doc AUTHORS COPYING ChangeLog README doc/* examples
-# INSTALL is generic instructions from autoconf
-# NEWS is currently empty
-# %doc INSTALL
-%doc NEWS
-
-%{_bindir}/*
-%dir %{_datadir}/gtk-doc
-%dir %{_datadir}/gtk-doc/html
-%dir %{_datadir}/gtk-doc/data
-%{_datadir}/gtk-doc/data/*
-%{_libdir}/pkgconfig/*
-
-%changelog
-* Tue Jun 03 2003 Matthias Clasen <maclas@gmx.de>
-- Add a missing Provides: and include the .pc file.
- (#106568, Joe Pranevich)
-
-* Sun Aug 12 2001 Jens Finke <jens@gnome.org>
-- Modified to match GPP standard:
- - Changed to Copyright to License
- - Don't use hardcoded path, use rpm macros instead
- - Moved ChangeLog to the end of the file.
- - Removed packager
- - Don't set docdir path.
- - Use /var/tmp as installation prefix
-
-* Fri Apr 27 2001 Toshio Kuratomi <badger@prtr-13.ucsc.edu>
-- Merge in some of the features of the redhat spec file.
-
-* Wed Nov 15 2000 John Gotts <jgotts@linuxsavvy.com>
-- Minor updates for 0.4.
-* Thu Aug 26 1999 John E. Gotts <jgotts@engin.umich.edu>
-- Created spec file.
-
-
-
-
-
-
-
+++ /dev/null
-# -*- mode: rpm-spec -*-
-
-Summary: GTK+ DocBook Documentation Generator
-Name: gtk-doc
-Version: @VERSION@
-Release: 1
-License: GPL
-Group: Utilities/Text
-Source: ftp://ftp.gtk.org/pub/gtk/v1.1/docs/rdp/gtk-doc-%{version}.tar.gz
-BuildRoot: /var/tmp/%{name}-%{version}-root
-URL: http://www.gtk.org/rdp/
-BuildArchitectures: noarch
-Requires: openjade
-Requires: perl >= 5.6.0
-Requires: libxslt
-Requires: docbook-dtds
-Requires: docbook-style-xsl
-Provides: perl(gtkdoc-common.pl)
-
-BuildRequires: perl, openjade, libxslt, docbook-dtds, docbook-style-xsl
-
-%description
-gtk-doc is a set of perl scripts that generate API reference documention in
-DocBook format. It can extract documentation from source code comments in a
-manner similar to java-doc. It is used to generate the documentation for
-GLib, Gtk+, and GNOME.
-
-%prep
-%setup -q
-
-# Move this doc file to avoid name collisions
-mv doc/README doc/README.docs
-
-%build
-CFLAGS="$RPM_OPT_FLAGS" ./configure $MYARCH_FLAGS --prefix=%{_prefix} \
- --sysconfdir=%{_sysconfdir} --datadir=%{_datadir}
-
-make
-
-%install
-rm -rf $RPM_BUILD_ROOT
-
-make prefix=$RPM_BUILD_ROOT%{_prefix} \
- sysconfdir=$RPM_BUILD_ROOT%{_sysconfdir} \
- datadir=$RPM_BUILD_ROOT%{_datadir} install
-
-%clean
-rm -rf $RPM_BUILD_ROOT
-
-%files
-%defattr(-, root, root)
-
-%doc AUTHORS COPYING ChangeLog README doc/* examples
-# INSTALL is generic instructions from autoconf
-# NEWS is currently empty
-# %doc INSTALL
-%doc NEWS
-
-%{_bindir}/*
-%dir %{_datadir}/gtk-doc
-%dir %{_datadir}/gtk-doc/html
-%dir %{_datadir}/gtk-doc/data
-%{_datadir}/gtk-doc/data/*
-%{_libdir}/pkgconfig/*
-
-%changelog
-* Tue Jun 03 2003 Matthias Clasen <maclas@gmx.de>
-- Add a missing Provides: and include the .pc file.
- (#106568, Joe Pranevich)
-
-* Sun Aug 12 2001 Jens Finke <jens@gnome.org>
-- Modified to match GPP standard:
- - Changed to Copyright to License
- - Don't use hardcoded path, use rpm macros instead
- - Moved ChangeLog to the end of the file.
- - Removed packager
- - Don't set docdir path.
- - Use /var/tmp as installation prefix
-
-* Fri Apr 27 2001 Toshio Kuratomi <badger@prtr-13.ucsc.edu>
-- Merge in some of the features of the redhat spec file.
-
-* Wed Nov 15 2000 John Gotts <jgotts@linuxsavvy.com>
-- Minor updates for 0.4.
-* Thu Aug 26 1999 John E. Gotts <jgotts@engin.umich.edu>
-- Created spec file.
-
-
-
-
-
-
-
-#!@PERL@ -w
-# -*- cperl -*-
+#!@PYTHON@
+# -*- python; coding: utf-8 -*-
#
# gtk-doc - GTK DocBook documentation generator.
# Copyright (C) 2007 David Nečas
+# 2007-2017 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
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
-#############################################################################
-# Script : gtkdoc-check
-# Description : Runs various checks on built documentation and outputs test
-# results. Can be run druring make check, by adding this to the
-# documentations Makefile.am: TESTS = $(GTKDOC_CHECK)
-#############################################################################
+import argparse
+import sys
+sys.path.append('@PYTHON_PACKAGE_DIR@')
-use strict;
-use Getopt::Long;
+from gtkdoc import common, check, config
-my $PRINT_VERSION;
-my $PRINT_HELP;
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ description='gtkdoc-check version %s - run documentation unit tests' % config.version)
+ parser.add_argument('--version', action='version', version=config.version)
+ options = parser.parse_args()
-my %optctl = ('version' => \$PRINT_VERSION,
- 'help' => \$PRINT_HELP);
-GetOptions(\%optctl, "version", "help");
+ common.setup_logging()
-if ($PRINT_VERSION) {
- print "@VERSION@\n";
- exit 0;
-}
-
-if ($PRINT_HELP) {
- print <<EOF;
-gtkdoc-check version @VERSION@ - run documentation unit tests
-
---version Print the version of this program
---help Print this help
-EOF
- exit 0;
-}
-
-my $checks = 4;
-
-# Get parameters from test env, if not there try to grab them from the makefile
-# We like Makefile.am more but builddir does not necessarily contain one.
-my $makefile = (-f 'Makefile.am') ? 'Makefile.am' : 'Makefile';
-
-# For historic reasons tests are launched in srcdir
-my $SRCDIR = $ENV{"SRCDIR"};
-my $BUILDDIR = $ENV{"BUILDDIR"};
-my $dir = ".";
-if (defined($BUILDDIR) and $BUILDDIR ne "") {
- $dir=$BUILDDIR;
-}
-
-# debug
-#for my $key (sort(keys(%ENV))) { print "$key = ", $ENV{$key}, "\n"; }
-# debug
-
-my $DOC_MODULE = $ENV{"DOC_MODULE"};
-if (!defined($DOC_MODULE) or $DOC_MODULE eq "") {
- $DOC_MODULE = &Grep('^\s*DOC_MODULE\s*=\s*(\S+)', $makefile, 'DOC_MODULE');
-}
-my $DOC_MAIN_SGML_FILE = $ENV{"DOC_MAIN_SGML_FILE"};
-if (!defined($DOC_MAIN_SGML_FILE) or $DOC_MAIN_SGML_FILE eq "") {
- $DOC_MAIN_SGML_FILE = &Grep('^\s*DOC_MAIN_SGML_FILE\s*=\s*(\S+)', $makefile, 'DOC_MAIN_SGML_FILE');
- $DOC_MAIN_SGML_FILE =~ s/\$\(DOC_MODULE\)/$DOC_MODULE/;
-}
-
-print "Running suite(s): gtk-doc-$DOC_MODULE\n";
-
-my $undocumented = int &Grep('^(\d+)\s+not\s+documented\.\s*$',
- "$dir/$DOC_MODULE-undocumented.txt",
- 'number of undocumented symbols');
-my $incomplete = int &Grep('^(\d+)\s+symbols?\s+incomplete\.\s*$',
- "$dir/$DOC_MODULE-undocumented.txt",
- 'number of incomplete symbols');
-my $total = $undocumented + $incomplete;
-if ($total) {
- print "$DOC_MODULE-undocumented.txt:1:E: $total undocumented or incomplete symbols\n";
-}
-
-my $undeclared = &CheckEmpty("$dir/$DOC_MODULE-undeclared.txt",
- 'undeclared symbols');
-my $unused = &CheckEmpty("$dir/$DOC_MODULE-unused.txt",
- 'unused documentation entries');
-
-my $missing_includes = &CheckIncludes ("$dir/$DOC_MAIN_SGML_FILE");
-
-my $failed = ($total > 0) + ($undeclared != 0) + ($unused != 0) + ($missing_includes != 0);
-my $rate = 100.0*($checks - $failed)/$checks;
-printf "%.1f%%: Checks %d, Failures: %d\n", $rate, $checks, $failed;
-exit ($failed != 0);
-
-sub Grep() {
- my ($regexp, $filename, $what) = @_;
- my $retval;
-
- if (not open GFILE, "<$filename") {
- die "Cannot open $filename: $!\n";
- }
- while (<GFILE>) {
- next if not m/$regexp/;
- $retval = $1;
- last;
- }
- close GFILE;
- if (not defined $retval) {
- die "Cannot find $what in $filename\n";
- }
- return $retval;
-}
-
-sub CheckEmpty() {
- my ($filename, $what) = @_;
- my $count = 0;
-
- if (not open GFILE, "<$filename") {
- return $count;
- }
- while (<GFILE>) {
- if (m/\S/) {
- $count++
- }
- }
- close GFILE;
- if ($count) {
- print "$filename:1:E: $count $what\n"
- }
- return $count;
-}
-
-sub CheckIncludes() {
- my ($main_sgml_file) = @_;
-
- if (not open GFILE, "<$main_sgml_file") {
- die "Cannot open $main_sgml_file: $!\n";
- }
-
- # Check that each of the XML files in the xml directory are included in $DOC_MAIN_SGML_FILE
- my @xml_files = <xml/*.xml>;
- my $num_missing = 0;
-
- foreach my $xml_file (@xml_files) {
- my $regex = quotemeta ($xml_file);
- my $found = 0;
-
- while (<GFILE>) {
- next if not m/"$regex"/;
- $found = 1;
- last;
- }
-
- if (!$found) {
- $num_missing++;
- print "$main_sgml_file doesn't appear to include \"$xml_file\"\n";
- }
-
- seek (GFILE, 0, 0);
- }
-
- close (GFILE);
-
- return $num_missing;
-}
+ sys.exit(check.run(options))
+++ /dev/null
-#!/usr/bin/perl -w
-# -*- cperl -*-
-#
-# gtk-doc - GTK DocBook documentation generator.
-# Copyright (C) 2001 Damon Chaplin
-#
-# 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.
-#
-
-#
-# These are functions used by several of the gtk-doc Perl scripts.
-# We'll move more of the common routines here eventually, though they need to
-# stop using global variables first.
-#
-
-1;
-
-
-#############################################################################
-# Function : UpdateFileIfChanged
-# Description : Compares the old version of the file with the new version and
-# if the file has changed it moves the new version into the old
-# versions place. This is used so we only change files if
-# needed, so we can do proper dependency tracking and we don't
-# needlessly check files into version control systems that haven't
-# changed.
-# It returns 0 if the file hasn't changed, and 1 if it has.
-# Arguments : $old_file - the pathname of the old file.
-# $new_file - the pathname of the new version of the file.
-# $make_backup - 1 if a backup of the old file should be kept.
-# It will have the .bak suffix added to the file name.
-#############################################################################
-
-sub UpdateFileIfChanged {
- my ($old_file, $new_file, $make_backup) = @_;
-
- #LogTrace("Comparing $old_file with $new_file...");
-
- # If the old file doesn't exist we want this to default to 1.
- my $exit_code = 1;
-
- if (-e $old_file) {
- `cmp -s "$old_file" "$new_file"`;
- $exit_code = $? >> 8;
- #LogTrace(" cmp exit code: $exit_code ($?)");
- }
-
- if ($exit_code > 1) {
- die "Error running 'cmp $old_file $new_file'";
- }
-
- if ($exit_code == 1) {
- #LogTrace(" files changed - replacing old version with new version.");
- if ($make_backup && -e $old_file) {
- rename ($old_file, "$old_file.bak")
- || die "Can't move $old_file to $old_file.bak: $!";
- }
- rename ($new_file, $old_file)
- || die "Can't move $new_file to $old_file: $!";
-
- return 1;
- } else {
- #LogTrace(" files the same - deleting new version.");
- unlink ("$new_file")
- || die "Can't delete file: $new_file: $!";
-
- return 0;
- }
-}
-
-
-#############################################################################
-# Function : ParseStructDeclaration
-# Description : This function takes a structure declaration and
-# breaks it into individual type declarations.
-# Arguments : $declaration - the declaration to parse
-# $is_object - true if this is an object structure
-# $output_function_params - true if full type is wanted for
-# function pointer members
-# $typefunc - function reference to apply to type
-# $namefunc - function reference to apply to name
-#############################################################################
-
-sub ParseStructDeclaration {
- my ($declaration, $is_object, $output_function_params, $typefunc, $namefunc) = @_;
-
- # For forward struct declarations just return an empty array.
- if ($declaration =~ m/(?:struct|union)\s+\S+\s*;/msg) {
- return ();
- }
-
- # Remove all private parts of the declaration
-
- # For objects, assume private
- if ($is_object) {
- $declaration =~ s!((?:struct|union)\s+\w*\s*\{)
- .*?
- (?:/\*\s*<\s*public\s*>\s*\*/|(?=\}))!$1!msgx;
- }
-
- # Remove private symbols
- # Assume end of declaration if line begins with '}'
- $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx;
-
- # Remove all other comments
- $declaration =~ s@\n\s*/\*([^*]+|\*(?!/))*\*/\s*\n@\n@msg;
- $declaration =~ s@/\*([^*]+|\*(?!/))*\*/@ @g;
- $declaration =~ s@\n\s*//.*?\n@\n@msg;
- $declaration =~ s@//.*@@g;
-
- # Remove g_iface, parent_instance and parent_class if they are first member
- $declaration =~ s/(\{)\s*(\w)+\s+(g_iface|parent_instance|parent_class)\s*;/$1/g;
-
- my @result = ();
-
- if ($declaration =~ /^\s*$/) {
- return @result;
- }
-
- # Prime match after "struct/union {" declaration
- if (!scalar($declaration =~ m/(?:struct|union)\s+\w*\s*\{/msg)) {
- die "Declaration '$declaration' does not begin with struct/union [NAME] {\n";
- }
-
- #LogTrace("public fields in struct/union: $declaration");
-
- # Treat lines in sequence, allowing singly nested anonymous structs
- # and unions.
- while ($declaration =~ m/\s*([^{;]+(\{[^\}]*\}[^{;]+)?);/msg) {
- my $line = $1;
-
- last if $line =~ /^\s*\}\s*\w*\s*$/;
-
- # FIXME: Just ignore nested structs and unions for now
- next if $line =~ /{/;
-
- # ignore preprocessor directives
- while ($line =~ /^#.*?\n\s*(.*)/msg) {
- $line=$1;
- }
-
- last if $line =~ /^\s*\}\s*\w*\s*$/;
-
- # Try to match structure members which are functions
- if ($line =~ m/^
- (const\s+|G_CONST_RETURN\s+|unsigned\s+|signed\s+|long\s+|short\s+)*(struct\s+|enum\s+)? # mod1
- (\w+)\s* # type
- (\**(?:\s*restrict)?)\s* # ptr1
- (const\s+)? # mod2
- (\**\s*) # ptr2
- (const\s+)? # mod3
- \(\s*\*\s*(\w+)\s*\)\s* # name
- \(([^)]*)\)\s* # func_params
- $/x) {
-
- my $mod1 = defined($1) ? $1 : "";
- if (defined($2)) { $mod1 .= $2; }
- my $type = $3;
- my $ptr1 = $4;
- my $mod2 = defined($5) ? $5 : "";
- my $ptr2 = $6;
- my $mod3 = defined($7) ? $7 : "";
- my $name = $8;
- my $func_params = $9;
- my $ptype = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
- my $pname = defined $namefunc ? $namefunc->($name) : $name;
-
- push @result, $name;
-
- if ($output_function_params) {
- push @result, "$mod1$ptype$ptr1$mod2$ptr2$mod3 (*$pname) ($func_params)";
- } else {
- push @result, "$pname ()";
- }
-
-
- # Try to match normal struct fields of comma-separated variables/
- } elsif ($line =~ m/^
- ((?:const\s+|volatile\s+|unsigned\s+|signed\s+|short\s+|long\s+)?)(struct\s+|enum\s+)? # mod1
- (\w+)\s* # type
- (\** \s* const\s+)? # mod2
- (.*) # variables
- $/x) {
-
- my $mod1 = defined($1) ? $1 : "";
- if (defined($2)) { $mod1 .= $2; }
- my $type = $3;
- my $ptype = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
- my $mod2 = defined($4) ? " " . $4 : "";
- my $list = $5;
-
- #LogTrace("'$mod1' '$type' '$mod2' '$list'");
-
- $mod1 =~ s/ / /g;
- $mod2 =~ s/ / /g;
-
- my @names = split /,/, $list;
- for my $n (@names) {
- # Each variable can have any number of '*' before the
- # identifier, and be followed by any number of pairs of
- # brackets or a bit field specifier.
- # e.g. *foo, ***bar, *baz[12][23], foo : 25.
- if ($n =~ m/^\s* (\**(?:\s*restrict\b)?) \s* (\w+) \s* (?: ((?:\[[^\]]*\]\s*)+) | (:\s*\d+)?) \s* $/x) {
- my $ptrs = $1;
- my $name = $2;
- my $array = defined($3) ? $3 : "";
- my $bits = defined($4) ? " $4" : "";
-
- if ($ptrs && $ptrs !~ m/\*$/) { $ptrs .= " "; }
- $array =~ s/ / /g;
- $bits =~ s/ / /g;
-
- push @result, $name;
- if (defined $namefunc) {
- $name = $namefunc->($name);
- }
- push @result, "$mod1$ptype$mod2 $ptrs$name$array$bits;";
-
- #LogTrace("Matched line: $mod1$ptype$mod2 $ptrs$name$array$bits");
- } else {
- print "WARNING: Couldn't parse struct field: $n\n";
- }
- }
-
- } else {
- print "WARNING: Cannot parse structure field: \"$line\"\n";
- }
- }
-
- return @result;
-}
-
-
-#############################################################################
-# Function : ParseEnumDeclaration
-# Description : This function takes a enumeration declaration and
-# breaks it into individual enum member declarations.
-# Arguments : $declaration - the declaration to parse
-#############################################################################
-
-sub ParseEnumDeclaration {
- my ($declaration, $is_object) = @_;
-
- # For forward enum declarations just return an empty array.
- if ($declaration =~ m/enum\s+\S+\s*;/msg) {
- return ();
- }
-
- # Remove private symbols
- # Assume end of declaration if line begins with '}'
- $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx;
-
- # Remove all other comments
- $declaration =~ s@\n\s*/\*([^*]+|\*(?!/))*\*/\s*\n@\n@msg;
- $declaration =~ s@/\*([^*]+|\*(?!/))*\*/@ @g;
- $declaration =~ s@\n\s*//.*?\n@\n@msg;
- $declaration =~ s@//.*@@g;
-
- my @result = ();
-
- if ($declaration =~ /^\s*$/) {
- return @result;
- }
-
- # Remove parenthesized expressions (in macros like GTK_BLAH = BLAH(1,3))
- # to avoid getting confused by commas they might contain. This
- # doesn't handle nested parentheses correctly.
-
- $declaration =~ s/\([^)\n]+\)//g;
-
- # Remove apostrophed characters (e.g. '}' or ',') values to avoid getting
- # confused with end of enumeration.
- # See https://bugzilla.gnome.org/show_bug.cgi?id=741305
-
- $declaration =~ s/\'.\'//g;
-
- # Remove comma from comma - possible whitespace - closing brace sequence
- # since it is legal in GNU C and C99 to have a trailing comma but doesn't
- # result in an actual enum member
-
- $declaration =~ s/,(\s*})/$1/g;
-
- # Prime match after "typedef enum {" declaration
- if (!scalar($declaration =~ m/(typedef\s+)?enum\s*(\S+\s*)?\{/msg)) {
- die "Enum declaration '$declaration' does not begin with 'typedef enum {' or 'enum XXX {'\n";
- }
-
- #LogTrace("public fields in enum: $declaration");
-
- # Treat lines in sequence.
- while ($declaration =~ m/\s*([^,\}]+)([,\}])/msg) {
- my $line = $1;
- my $terminator = $2;
-
- # ignore preprocessor directives
- while ($line =~ /^#.*?\n\s*(.*)/msg) {
- $line=$1;
- }
-
- if ($line =~ m/^(\w+)\s*(=.*)?$/msg) {
- push @result, $1;
-
- # Special case for GIOCondition, where the values are specified by
- # macros which expand to include the equal sign like '=1'.
- } elsif ($line =~ m/^(\w+)\s*GLIB_SYSDEF_POLL/msg) {
- push @result, $1;
-
- # Special case include of <gdk/gdkcursors.h>, just ignore it
- } elsif ($line =~ m/^#include/) {
- last;
-
- # Special case for #ifdef/#else/#endif, just ignore it
- } elsif ($line =~ m/^#(?:if|else|endif)/) {
- last;
-
- } else {
- warn "Cannot parse enumeration member \"$line\"";
- }
-
- last if $terminator eq '}';
- }
-
- return @result;
-}
-
-
-#############################################################################
-# Function : ParseFunctionDeclaration
-# Description : This function takes a function declaration and
-# breaks it into individual parameter declarations.
-# Arguments : $declaration - the declaration to parse
-# $typefunc - function reference to apply to type
-# $namefunc - function reference to apply to name
-#############################################################################
-
-sub ParseFunctionDeclaration {
- my ($declaration, $typefunc, $namefunc) = @_;
-
- my @result = ();
-
- my ($param_num) = 0;
- while ($declaration ne "") {
- #LogTrace("[$declaration]");
-
- if ($declaration =~ s/^[\s,]+//) {
- # skip whitespace and commas
- next;
-
- } elsif ($declaration =~ s/^void\s*[,\n]//) {
- if ($param_num != 0) {
- # FIXME: whats the problem here?
- warn "void used as parameter in function $declaration";
- }
- push @result, "void";
- my $xref = "<type>void</type>";
- my $label = defined $namefunc ? $namefunc->($xref) : $xref;
- push @result, $label;
-
- } elsif ($declaration =~ s/^\s*[_a-zA-Z0-9]*\.\.\.\s*[,\n]//) {
- push @result, "...";
- my $label = defined $namefunc ? $namefunc->("...") : "...";
- push @result, $label;
-
- # allow alphanumerics, '_', '[' & ']' in param names
- # Try to match a standard parameter
- # $1 $2 $3 $4 $5
- } elsif ($declaration =~ s/^\s*((?:(?:G_CONST_RETURN|G_GNUC_[A-Z_]+\s+|unsigned long|unsigned short|signed long|signed short|unsigned|signed|long|short|volatile|const)\s+)*)((?:struct\b|enum\b)?\s*\w+)\s*((?:(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*\*?\s*(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*)*)(\w+)?\s*((?:\[\S*\])*)\s*(?:G_GNUC_[A-Z_]+)?\s*[,\n]//) {
- my $pre = defined($1) ? $1 : "";
- my $type = $2;
- my $ptr = defined($3) ? $3 : "";
- my $name = defined($4) ? $4 : "";
- my $array = defined($5) ? $5 : "";
-
- $pre =~ s/\s+/ /g;
- $type =~ s/\s+/ /g;
- $ptr =~ s/\s+/ /g;
- $ptr =~ s/\s+$//;
- if ($ptr && $ptr !~ m/\*$/) { $ptr .= " "; }
-
- #LogTrace("$symbol: '$pre' '$type' '$ptr' '$name' '$array'");
-
- if (($name eq "") && $pre =~ m/^((un)?signed .*)\s?/ ) {
- $name = $type;
- $type = "$1";
- $pre = "";
- }
-
- if ($name eq "") {
- $name = "Param" . ($param_num + 1);
- }
-
- #LogTrace("$symbol: '$pre' '$type' '$ptr' '$name' '$array'");
-
- push @result, $name;
- my $xref = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
- my $label = "$pre$xref $ptr$name$array";
- if (defined $namefunc) {
- $label = $namefunc->($label)
- }
- push @result, $label;
-
- # Try to match parameters which are functions
- # $1 $2 $3 $4 $5 $6 $7 $8
- } elsif ($declaration =~ s/^(const\s+|G_CONST_RETURN\s+|G_GNUC_[A-Z_]+\s+|signed\s+|unsigned\s+)*(struct\s+)?(\w+)\s*(\**)\s*(?:restrict\b)?\s*(const\s+)?\(\s*(\*[\s\*]*)\s*(\w+)\s*\)\s*\(([^)]*)\)\s*[,\n]//) {
- my $mod1 = defined($1) ? $1 : "";
- if (defined($2)) { $mod1 .= $2; }
- my $type = $3;
- my $ptr1 = $4;
- my $mod2 = defined($5) ? $5 : "";
- my $func_ptr = $6;
- my $name = $7;
- my $func_params = defined($8) ? $8 : "";
-
- #if (!defined($type)) { print "## no type\n"; };
- #if (!defined($ptr1)) { print "## no ptr1\n"; };
- #if (!defined($func_ptr)) { print "## no func_ptr\n"; };
- #if (!defined($name)) { print "## no name\n"; };
-
- if ($ptr1 && $ptr1 !~ m/\*$/) { $ptr1 .= " "; }
- $func_ptr =~ s/\s+//g;
-
- push @result, $name;
- my $xref = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
- #LogTrace("Type: [$mod1][$xref][$ptr1][$mod2] ([$func_ptr][$name]) ($func_params)");
- my $label = "$mod1$xref$ptr1$mod2 ($func_ptr$name) ($func_params)";
- if (defined $namefunc) {
- $label = $namefunc->($label)
- }
- push @result, $label;
- } else {
- warn "Can't parse args for function in \"$declaration\"";
- last;
- }
- $param_num++;
- }
-
- return @result;
-}
-
-
-#############################################################################
-# Function : ParseMacroDeclaration
-# Description : This function takes a macro declaration and
-# breaks it into individual parameter declarations.
-# Arguments : $declaration - the declaration to parse
-# $namefunc - function reference to apply to name
-#############################################################################
-
-sub ParseMacroDeclaration {
- my ($declaration, $namefunc) = @_;
-
- my @result = ();
-
- if ($declaration =~ m/^\s*#\s*define\s+\w+\(([^\)]*)\)/) {
- my $params = $1;
-
- $params =~ s/\\\n//g;
- foreach $param (split (/,/, $params)) {
- $param =~ s/^\s+//;
- $param =~ s/\s*$//;
- # Allow varargs variations
- if ($param =~ m/^.*\.\.\.$/) {
- $param = "...";
- }
- if ($param =~ m/\S/) {
- push @result, $param;
- push @result, defined $namefunc ? $namefunc->($param) : $param;
- }
- }
- }
-
- return @result;
-}
-
-
-#############################################################################
-# Function : LogWarning
-# Description : Log a warning in gcc style format
-# Arguments : $file - the file the error comes from
-# $line - line number for the wrong entry
-# $message - description of the issue
-#############################################################################
-
-sub LogWarning {
- my ($file, $line, $message) = @_;
-
- $file="unknown" if !defined($file);
- $line="0" if !defined($line);
-
- print "$file:$line: warning: $message\n"
-}
-
-sub LogTrace {
- my ($message) = @_;
-
- if (defined($ENV{"GTKDOC_TRACE"})) {
- my (undef, $file, $line) = caller;
-
- chomp($message);
- print "$file:$line: trace: $message\n"
- }
-}
-
-
-#############################################################################
-# Function : CreateValidSGMLID
-# Description : Creates a valid SGML 'id' from the given string.
-# According to http://www.w3.org/TR/html4/types.html#type-id
-# "ID and NAME tokens must begin with a letter ([A-Za-z]) and
-# may be followed by any number of letters, digits ([0-9]),
-# hyphens ("-"), underscores ("_"), colons (":"), and
-# periods (".")."
-#
-# NOTE: When creating SGML IDS, we append ":CAPS" to all
-# all-caps identifiers to prevent name clashes (SGML ids are
-# case-insensitive). (It basically never is the case that
-# mixed-case identifiers would collide.)
-# Arguments : $id - the string to be converted into a valid SGML id.
-#############################################################################
-
-sub CreateValidSGMLID {
- my ($id) = $_[0];
-
- # Special case, '_' would end up as '' so we use 'gettext-macro' instead.
- if ($id eq "_") { return "gettext-macro"; }
-
- $id =~ s/[_ ]/-/g;
- $id =~ s/[,;]//g;
- $id =~ s/^-*//;
- $id =~ s/::/-/g;
- $id =~ s/:/--/g;
-
- # Append ":CAPS" to all all-caps identifiers
- # FIXME: there are some inconsistencies here, we have sgml.index files
- # containing e.g. TRUE--CAPS
- if ($id !~ /[a-z]/ && $id !~ /-CAPS$/) { $id .= ":CAPS" };
-
- return $id;
-}
-
+++ /dev/null
-#!@PERL@ -w
-# -*- cperl -*-
-#
-# gtk-doc - GTK DocBook documentation generator.
-# Copyright (C) 2001 Damon Chaplin
-#
-# 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.
-#
-
-#
-# These are functions used by several of the gtk-doc Perl scripts.
-# We'll move more of the common routines here eventually, though they need to
-# stop using global variables first.
-#
-
-1;
-
-
-#############################################################################
-# Function : UpdateFileIfChanged
-# Description : Compares the old version of the file with the new version and
-# if the file has changed it moves the new version into the old
-# versions place. This is used so we only change files if
-# needed, so we can do proper dependency tracking and we don't
-# needlessly check files into version control systems that haven't
-# changed.
-# It returns 0 if the file hasn't changed, and 1 if it has.
-# Arguments : $old_file - the pathname of the old file.
-# $new_file - the pathname of the new version of the file.
-# $make_backup - 1 if a backup of the old file should be kept.
-# It will have the .bak suffix added to the file name.
-#############################################################################
-
-sub UpdateFileIfChanged {
- my ($old_file, $new_file, $make_backup) = @_;
-
- #@TRACE@("Comparing $old_file with $new_file...");
-
- # If the old file doesn't exist we want this to default to 1.
- my $exit_code = 1;
-
- if (-e $old_file) {
- `cmp -s "$old_file" "$new_file"`;
- $exit_code = $? >> 8;
- #@TRACE@(" cmp exit code: $exit_code ($?)");
- }
-
- if ($exit_code > 1) {
- die "Error running 'cmp $old_file $new_file'";
- }
-
- if ($exit_code == 1) {
- #@TRACE@(" files changed - replacing old version with new version.");
- if ($make_backup && -e $old_file) {
- rename ($old_file, "$old_file.bak")
- || die "Can't move $old_file to $old_file.bak: $!";
- }
- rename ($new_file, $old_file)
- || die "Can't move $new_file to $old_file: $!";
-
- return 1;
- } else {
- #@TRACE@(" files the same - deleting new version.");
- unlink ("$new_file")
- || die "Can't delete file: $new_file: $!";
-
- return 0;
- }
-}
-
-
-#############################################################################
-# Function : ParseStructDeclaration
-# Description : This function takes a structure declaration and
-# breaks it into individual type declarations.
-# Arguments : $declaration - the declaration to parse
-# $is_object - true if this is an object structure
-# $output_function_params - true if full type is wanted for
-# function pointer members
-# $typefunc - function reference to apply to type
-# $namefunc - function reference to apply to name
-#############################################################################
-
-sub ParseStructDeclaration {
- my ($declaration, $is_object, $output_function_params, $typefunc, $namefunc) = @_;
-
- # For forward struct declarations just return an empty array.
- if ($declaration =~ m/(?:struct|union)\s+\S+\s*;/msg) {
- return ();
- }
-
- # Remove all private parts of the declaration
-
- # For objects, assume private
- if ($is_object) {
- $declaration =~ s!((?:struct|union)\s+\w*\s*\{)
- .*?
- (?:/\*\s*<\s*public\s*>\s*\*/|(?=\}))!$1!msgx;
- }
-
- # Remove private symbols
- # Assume end of declaration if line begins with '}'
- $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx;
-
- # Remove all other comments
- $declaration =~ s@\n\s*/\*([^*]+|\*(?!/))*\*/\s*\n@\n@msg;
- $declaration =~ s@/\*([^*]+|\*(?!/))*\*/@ @g;
- $declaration =~ s@\n\s*//.*?\n@\n@msg;
- $declaration =~ s@//.*@@g;
-
- # Remove g_iface, parent_instance and parent_class if they are first member
- $declaration =~ s/(\{)\s*(\w)+\s+(g_iface|parent_instance|parent_class)\s*;/$1/g;
-
- my @result = ();
-
- if ($declaration =~ /^\s*$/) {
- return @result;
- }
-
- # Prime match after "struct/union {" declaration
- if (!scalar($declaration =~ m/(?:struct|union)\s+\w*\s*\{/msg)) {
- die "Declaration '$declaration' does not begin with struct/union [NAME] {\n";
- }
-
- #@TRACE@("public fields in struct/union: $declaration");
-
- # Treat lines in sequence, allowing singly nested anonymous structs
- # and unions.
- while ($declaration =~ m/\s*([^{;]+(\{[^\}]*\}[^{;]+)?);/msg) {
- my $line = $1;
-
- last if $line =~ /^\s*\}\s*\w*\s*$/;
-
- # FIXME: Just ignore nested structs and unions for now
- next if $line =~ /{/;
-
- # ignore preprocessor directives
- while ($line =~ /^#.*?\n\s*(.*)/msg) {
- $line=$1;
- }
-
- last if $line =~ /^\s*\}\s*\w*\s*$/;
-
- # Try to match structure members which are functions
- if ($line =~ m/^
- (const\s+|G_CONST_RETURN\s+|unsigned\s+|signed\s+|long\s+|short\s+)*(struct\s+|enum\s+)? # mod1
- (\w+)\s* # type
- (\**(?:\s*restrict)?)\s* # ptr1
- (const\s+)? # mod2
- (\**\s*) # ptr2
- (const\s+)? # mod3
- \(\s*\*\s*(\w+)\s*\)\s* # name
- \(([^)]*)\)\s* # func_params
- $/x) {
-
- my $mod1 = defined($1) ? $1 : "";
- if (defined($2)) { $mod1 .= $2; }
- my $type = $3;
- my $ptr1 = $4;
- my $mod2 = defined($5) ? $5 : "";
- my $ptr2 = $6;
- my $mod3 = defined($7) ? $7 : "";
- my $name = $8;
- my $func_params = $9;
- my $ptype = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
- my $pname = defined $namefunc ? $namefunc->($name) : $name;
-
- push @result, $name;
-
- if ($output_function_params) {
- push @result, "$mod1$ptype$ptr1$mod2$ptr2$mod3 (*$pname) ($func_params)";
- } else {
- push @result, "$pname ()";
- }
-
-
- # Try to match normal struct fields of comma-separated variables/
- } elsif ($line =~ m/^
- ((?:const\s+|volatile\s+|unsigned\s+|signed\s+|short\s+|long\s+)?)(struct\s+|enum\s+)? # mod1
- (\w+)\s* # type
- (\** \s* const\s+)? # mod2
- (.*) # variables
- $/x) {
-
- my $mod1 = defined($1) ? $1 : "";
- if (defined($2)) { $mod1 .= $2; }
- my $type = $3;
- my $ptype = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
- my $mod2 = defined($4) ? " " . $4 : "";
- my $list = $5;
-
- #@TRACE@("'$mod1' '$type' '$mod2' '$list'");
-
- $mod1 =~ s/ / /g;
- $mod2 =~ s/ / /g;
-
- my @names = split /,/, $list;
- for my $n (@names) {
- # Each variable can have any number of '*' before the
- # identifier, and be followed by any number of pairs of
- # brackets or a bit field specifier.
- # e.g. *foo, ***bar, *baz[12][23], foo : 25.
- if ($n =~ m/^\s* (\**(?:\s*restrict\b)?) \s* (\w+) \s* (?: ((?:\[[^\]]*\]\s*)+) | (:\s*\d+)?) \s* $/x) {
- my $ptrs = $1;
- my $name = $2;
- my $array = defined($3) ? $3 : "";
- my $bits = defined($4) ? " $4" : "";
-
- if ($ptrs && $ptrs !~ m/\*$/) { $ptrs .= " "; }
- $array =~ s/ / /g;
- $bits =~ s/ / /g;
-
- push @result, $name;
- if (defined $namefunc) {
- $name = $namefunc->($name);
- }
- push @result, "$mod1$ptype$mod2 $ptrs$name$array$bits;";
-
- #@TRACE@("Matched line: $mod1$ptype$mod2 $ptrs$name$array$bits");
- } else {
- print "WARNING: Couldn't parse struct field: $n\n";
- }
- }
-
- } else {
- print "WARNING: Cannot parse structure field: \"$line\"\n";
- }
- }
-
- return @result;
-}
-
-
-#############################################################################
-# Function : ParseEnumDeclaration
-# Description : This function takes a enumeration declaration and
-# breaks it into individual enum member declarations.
-# Arguments : $declaration - the declaration to parse
-#############################################################################
-
-sub ParseEnumDeclaration {
- my ($declaration, $is_object) = @_;
-
- # For forward enum declarations just return an empty array.
- if ($declaration =~ m/enum\s+\S+\s*;/msg) {
- return ();
- }
-
- # Remove private symbols
- # Assume end of declaration if line begins with '}'
- $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx;
-
- # Remove all other comments
- $declaration =~ s@\n\s*/\*([^*]+|\*(?!/))*\*/\s*\n@\n@msg;
- $declaration =~ s@/\*([^*]+|\*(?!/))*\*/@ @g;
- $declaration =~ s@\n\s*//.*?\n@\n@msg;
- $declaration =~ s@//.*@@g;
-
- my @result = ();
-
- if ($declaration =~ /^\s*$/) {
- return @result;
- }
-
- # Remove parenthesized expressions (in macros like GTK_BLAH = BLAH(1,3))
- # to avoid getting confused by commas they might contain. This
- # doesn't handle nested parentheses correctly.
-
- $declaration =~ s/\([^)\n]+\)//g;
-
- # Remove apostrophed characters (e.g. '}' or ',') values to avoid getting
- # confused with end of enumeration.
- # See https://bugzilla.gnome.org/show_bug.cgi?id=741305
-
- $declaration =~ s/\'.\'//g;
-
- # Remove comma from comma - possible whitespace - closing brace sequence
- # since it is legal in GNU C and C99 to have a trailing comma but doesn't
- # result in an actual enum member
-
- $declaration =~ s/,(\s*})/$1/g;
-
- # Prime match after "typedef enum {" declaration
- if (!scalar($declaration =~ m/(typedef\s+)?enum\s*(\S+\s*)?\{/msg)) {
- die "Enum declaration '$declaration' does not begin with 'typedef enum {' or 'enum XXX {'\n";
- }
-
- #@TRACE@("public fields in enum: $declaration");
-
- # Treat lines in sequence.
- while ($declaration =~ m/\s*([^,\}]+)([,\}])/msg) {
- my $line = $1;
- my $terminator = $2;
-
- # ignore preprocessor directives
- while ($line =~ /^#.*?\n\s*(.*)/msg) {
- $line=$1;
- }
-
- if ($line =~ m/^(\w+)\s*(=.*)?$/msg) {
- push @result, $1;
-
- # Special case for GIOCondition, where the values are specified by
- # macros which expand to include the equal sign like '=1'.
- } elsif ($line =~ m/^(\w+)\s*GLIB_SYSDEF_POLL/msg) {
- push @result, $1;
-
- # Special case include of <gdk/gdkcursors.h>, just ignore it
- } elsif ($line =~ m/^#include/) {
- last;
-
- # Special case for #ifdef/#else/#endif, just ignore it
- } elsif ($line =~ m/^#(?:if|else|endif)/) {
- last;
-
- } else {
- warn "Cannot parse enumeration member \"$line\"";
- }
-
- last if $terminator eq '}';
- }
-
- return @result;
-}
-
-
-#############################################################################
-# Function : ParseFunctionDeclaration
-# Description : This function takes a function declaration and
-# breaks it into individual parameter declarations.
-# Arguments : $declaration - the declaration to parse
-# $typefunc - function reference to apply to type
-# $namefunc - function reference to apply to name
-#############################################################################
-
-sub ParseFunctionDeclaration {
- my ($declaration, $typefunc, $namefunc) = @_;
-
- my @result = ();
-
- my ($param_num) = 0;
- while ($declaration ne "") {
- #@TRACE@("[$declaration]");
-
- if ($declaration =~ s/^[\s,]+//) {
- # skip whitespace and commas
- next;
-
- } elsif ($declaration =~ s/^void\s*[,\n]//) {
- if ($param_num != 0) {
- # FIXME: whats the problem here?
- warn "void used as parameter in function $declaration";
- }
- push @result, "void";
- my $xref = "<type>void</type>";
- my $label = defined $namefunc ? $namefunc->($xref) : $xref;
- push @result, $label;
-
- } elsif ($declaration =~ s/^\s*[_a-zA-Z0-9]*\.\.\.\s*[,\n]//) {
- push @result, "...";
- my $label = defined $namefunc ? $namefunc->("...") : "...";
- push @result, $label;
-
- # allow alphanumerics, '_', '[' & ']' in param names
- # Try to match a standard parameter
- # $1 $2 $3 $4 $5
- } elsif ($declaration =~ s/^\s*((?:(?:G_CONST_RETURN|G_GNUC_[A-Z_]+\s+|unsigned long|unsigned short|signed long|signed short|unsigned|signed|long|short|volatile|const)\s+)*)((?:struct\b|enum\b)?\s*\w+)\s*((?:(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*\*?\s*(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*)*)(\w+)?\s*((?:\[\S*\])*)\s*(?:G_GNUC_[A-Z_]+)?\s*[,\n]//) {
- my $pre = defined($1) ? $1 : "";
- my $type = $2;
- my $ptr = defined($3) ? $3 : "";
- my $name = defined($4) ? $4 : "";
- my $array = defined($5) ? $5 : "";
-
- $pre =~ s/\s+/ /g;
- $type =~ s/\s+/ /g;
- $ptr =~ s/\s+/ /g;
- $ptr =~ s/\s+$//;
- if ($ptr && $ptr !~ m/\*$/) { $ptr .= " "; }
-
- #@TRACE@("$symbol: '$pre' '$type' '$ptr' '$name' '$array'");
-
- if (($name eq "") && $pre =~ m/^((un)?signed .*)\s?/ ) {
- $name = $type;
- $type = "$1";
- $pre = "";
- }
-
- if ($name eq "") {
- $name = "Param" . ($param_num + 1);
- }
-
- #@TRACE@("$symbol: '$pre' '$type' '$ptr' '$name' '$array'");
-
- push @result, $name;
- my $xref = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
- my $label = "$pre$xref $ptr$name$array";
- if (defined $namefunc) {
- $label = $namefunc->($label)
- }
- push @result, $label;
-
- # Try to match parameters which are functions
- # $1 $2 $3 $4 $5 $6 $7 $8
- } elsif ($declaration =~ s/^(const\s+|G_CONST_RETURN\s+|G_GNUC_[A-Z_]+\s+|signed\s+|unsigned\s+)*(struct\s+)?(\w+)\s*(\**)\s*(?:restrict\b)?\s*(const\s+)?\(\s*(\*[\s\*]*)\s*(\w+)\s*\)\s*\(([^)]*)\)\s*[,\n]//) {
- my $mod1 = defined($1) ? $1 : "";
- if (defined($2)) { $mod1 .= $2; }
- my $type = $3;
- my $ptr1 = $4;
- my $mod2 = defined($5) ? $5 : "";
- my $func_ptr = $6;
- my $name = $7;
- my $func_params = defined($8) ? $8 : "";
-
- #if (!defined($type)) { print "## no type\n"; };
- #if (!defined($ptr1)) { print "## no ptr1\n"; };
- #if (!defined($func_ptr)) { print "## no func_ptr\n"; };
- #if (!defined($name)) { print "## no name\n"; };
-
- if ($ptr1 && $ptr1 !~ m/\*$/) { $ptr1 .= " "; }
- $func_ptr =~ s/\s+//g;
-
- push @result, $name;
- my $xref = defined $typefunc ? $typefunc->($type, "<type>$type</type>") : $type;
- #@TRACE@("Type: [$mod1][$xref][$ptr1][$mod2] ([$func_ptr][$name]) ($func_params)");
- my $label = "$mod1$xref$ptr1$mod2 ($func_ptr$name) ($func_params)";
- if (defined $namefunc) {
- $label = $namefunc->($label)
- }
- push @result, $label;
- } else {
- warn "Can't parse args for function in \"$declaration\"";
- last;
- }
- $param_num++;
- }
-
- return @result;
-}
-
-
-#############################################################################
-# Function : ParseMacroDeclaration
-# Description : This function takes a macro declaration and
-# breaks it into individual parameter declarations.
-# Arguments : $declaration - the declaration to parse
-# $namefunc - function reference to apply to name
-#############################################################################
-
-sub ParseMacroDeclaration {
- my ($declaration, $namefunc) = @_;
-
- my @result = ();
-
- if ($declaration =~ m/^\s*#\s*define\s+\w+\(([^\)]*)\)/) {
- my $params = $1;
-
- $params =~ s/\\\n//g;
- foreach $param (split (/,/, $params)) {
- $param =~ s/^\s+//;
- $param =~ s/\s*$//;
- # Allow varargs variations
- if ($param =~ m/^.*\.\.\.$/) {
- $param = "...";
- }
- if ($param =~ m/\S/) {
- push @result, $param;
- push @result, defined $namefunc ? $namefunc->($param) : $param;
- }
- }
- }
-
- return @result;
-}
-
-
-#############################################################################
-# Function : LogWarning
-# Description : Log a warning in gcc style format
-# Arguments : $file - the file the error comes from
-# $line - line number for the wrong entry
-# $message - description of the issue
-#############################################################################
-
-sub LogWarning {
- my ($file, $line, $message) = @_;
-
- $file="unknown" if !defined($file);
- $line="0" if !defined($line);
-
- print "$file:$line: warning: $message\n"
-}
-
-sub LogTrace {
- my ($message) = @_;
-
- if (defined($ENV{"GTKDOC_TRACE"})) {
- my (undef, $file, $line) = caller;
-
- chomp($message);
- print "$file:$line: trace: $message\n"
- }
-}
-
-
-#############################################################################
-# Function : CreateValidSGMLID
-# Description : Creates a valid SGML 'id' from the given string.
-# According to http://www.w3.org/TR/html4/types.html#type-id
-# "ID and NAME tokens must begin with a letter ([A-Za-z]) and
-# may be followed by any number of letters, digits ([0-9]),
-# hyphens ("-"), underscores ("_"), colons (":"), and
-# periods (".")."
-#
-# NOTE: When creating SGML IDS, we append ":CAPS" to all
-# all-caps identifiers to prevent name clashes (SGML ids are
-# case-insensitive). (It basically never is the case that
-# mixed-case identifiers would collide.)
-# Arguments : $id - the string to be converted into a valid SGML id.
-#############################################################################
-
-sub CreateValidSGMLID {
- my ($id) = $_[0];
-
- # Special case, '_' would end up as '' so we use 'gettext-macro' instead.
- if ($id eq "_") { return "gettext-macro"; }
-
- $id =~ s/[_ ]/-/g;
- $id =~ s/[,;]//g;
- $id =~ s/^-*//;
- $id =~ s/::/-/g;
- $id =~ s/:/--/g;
-
- # Append ":CAPS" to all all-caps identifiers
- # FIXME: there are some inconsistencies here, we have sgml.index files
- # containing e.g. TRUE--CAPS
- if ($id !~ /[a-z]/ && $id !~ /-CAPS$/) { $id .= ":CAPS" };
-
- return $id;
-}
-
#!@PYTHON@
+from __future__ import print_function
+
import gzip, os.path, re
from os import environ, popen, walk
break
if not self.__catalog:
- raise IOError, 'No devhelp book found for "%s"' % name
+ raise IOError('No devhelp book found for "%s"' % name)
def __cmp__(self, other):
if isinstance(other, Book):
path = path and path.split(':') or []
prefix = popen(
- 'pkg-config --variable=prefix glib-2.0'
+ '@PKG_CONFIG@ --variable=prefix glib-2.0'
).readline().rstrip()
path.insert(0, prefix)
for filename, lineno, symbol in matches:
if not isinstance(symbol, Symbol):
if options.verbose:
- print '%s:%d: unknown symbol %s' % (filename, lineno, symbol)
+ print('%s:%d: unknown symbol %s' % (filename, lineno, symbol))
continue
since = '%s-%s' % (symbol.book.name, symbol.since)
options.books = default_books
def trace(message, *args):
- if options.verbose: print message % args
+ if options.verbose: print(message % args)
def parse_book(name):
try:
version = version and Symbol.VersionInfo(version)
return name, Book(name, options.dirs, version)
- except IOError, e:
+ except IOError as e:
print >>stderr, 'WARNING: %s.' % e
def scan_source_file(name):
try:
contents = __comment_regex.sub('', file(name).read())
- except IOError, e:
+ except IOError as e:
print >>stderr, e
if contents:
if options.summarize:
summary = summarize_matches(matches)
for since in sorted(summary.keys()):
- print '%s required for' % since
+ print('%s required for' % since)
for x in summary[since]:
- print ' %u %s' % (x[1], x[0])
+ print(' %u %s' % (x[1], x[0]))
else:
for filename, lineno, symbol in matches:
if isinstance(symbol, Symbol):
args = filename, lineno, symbol.book.name, symbol.since, symbol.name
- print '%s:%d: %s-%s required for %s' % args
+ print('%s:%d: %s-%s required for %s' % args)
elif options.verbose:
- print '%s:%d: unknown symbol %s' % (filename, lineno, symbol)
+ print('%s:%d: unknown symbol %s' % (filename, lineno, symbol))
if options.unknown:
unknown = [m[2].split('_')[0].lower() for m in unknown_symbols]
unknown = list(set(unknown))
unknown.sort()
- print 'unknown prefixes: %s' % ', '.join(unknown)
+ print('unknown prefixes: %s' % ', '.join(unknown))
raise SystemExit(matches and 1 or 0)
-#!@PERL@ -w
-# -*- cperl -*-
+#!@PYTHON@
+# -*- python -*-
#
# gtk-doc - GTK DocBook documentation generator.
# Copyright (C) 1998 Damon Chaplin
+# 2007-2016 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
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
-#############################################################################
-# Script : gtkdoc-fixxref
-# Description : This fixes cross-references in the HTML documentation.
-#############################################################################
-
-use strict;
-use bytes;
-use Getopt::Long;
-
-push @INC, '@PACKAGE_DATA_DIR@';
-require "gtkdoc-common.pl";
-
-# Options
-
-# name of documentation module
-my $MODULE;
-my $MODULE_DIR;
-my $HTML_DIR = "";
-my @EXTRA_DIRS;
-my $PRINT_VERSION;
-my $PRINT_HELP;
-my $SRC_LANG;
-
-# This contains all the entities and their relative URLs.
-my %Links;
-
-# failing link targets we don't warn about even once
-my %NoLinks = (
- 'char' => 1,
- 'double' => 1,
- 'float' => 1,
- 'int' => 1,
- 'long' => 1,
- 'main' => 1,
- 'signed' => 1,
- 'unsigned' => 1,
- 'va-list' => 1,
- 'void' => 1,
- 'GBoxed' => 1,
- 'GEnum' => 1,
- 'GFlags' => 1,
- 'GInterface' => 1
-);
-
-# Cache of dirs we already scanned for index files
-my %DirCache;
-
-run() unless caller; # Run program unless loaded as a module
-
-
-sub run {
- my %optctl = ('module' => \$MODULE,
- 'module-dir' => \$MODULE_DIR,
- 'html-dir' => \$HTML_DIR,
- 'extra-dir' => \@EXTRA_DIRS,
- 'version' => \$PRINT_VERSION,
- 'help' => \$PRINT_HELP,
- 'src-lang' => \$SRC_LANG);
-
- GetOptions(\%optctl, "module=s", "module-dir=s", "html-dir:s", "extra-dir=s@",
- "src-lang=s", "version", "help");
-
- if ($PRINT_VERSION) {
- print "@VERSION@\n";
- exit 0;
- }
-
- if ($PRINT_HELP) {
- print <<EOF;
-gtkdoc-fixxref version @VERSION@ - fix cross references in html files
-
---module=MODULE_NAME Name of the doc module being parsed
---module-dir=MODULE_DIR The directory which contains the generated HTML
---html-dir=HTML_DIR The directory where gtk-doc generated documentation is
- installed
---extra-dir=EXTRA_DIR Directories to recursively scan for indices (index.sgml)
- in addition to HTML_DIR
- May be used more than once for multiple directories
---src-lang=SRC_LANG Programing language used for syntax highlighting. The
- available languages depend on the source source
- highlighter you use.
---version Print the version of this program
---help Print this help
-EOF
- exit 0;
- }
-
- if (!$SRC_LANG) {
- $SRC_LANG="c"
- }
-
- my $path_prefix="";
- if ($HTML_DIR =~ m%(.*?)/share/gtk-doc/html%) {
- $path_prefix=$1;
- @TRACE@("Path prefix: $path_prefix");
- }
-
- if (!defined $MODULE_DIR) {
- $MODULE_DIR="$HTML_DIR/$MODULE";
- }
-
- my $dir;
-
- # We scan the directory containing GLib and any directories in GNOME2_PATH
- # first, but these will be overriden by any later scans.
- $dir = `pkg-config --variable=prefix glib-2.0`;
- $dir =~ s/\s+$//;
- $dir = $dir . "/share/gtk-doc/html";
- if (-d $dir) {
- # Some predefined link targets to get links into type hierarchies as these
- # have no targets. These are always absolute for now.
- $Links{'GBoxed'} = "$dir/gobject/gobject-Boxed-Types.html";
- $Links{'GEnum'} = "$dir/gobject/gobject-Enumeration-and-Flag-Types.html";
- $Links{'GFlags'} = "$dir/gobject/gobject-Enumeration-and-Flag-Types.html";
- $Links{'GInterface'} = "$dir/gobject/GTypeModule.html";
-
- if ($dir ne $HTML_DIR) {
- @TRACE@("Scanning GLib directory: $dir");
- if ($dir !~ m%^\Q$path_prefix\E/%) {
- &ScanIndices ($dir, 1);
- } else {
- &ScanIndices ($dir, 0);
- }
- }
- }
-
- if (defined ($ENV{"GNOME2_PATH"})) {
- foreach $dir (split (/:/, $ENV{"GNOME2_PATH"})) {
- $dir = $dir . "/share/gtk-doc/html";
- if (-d $dir && $dir ne $HTML_DIR) {
- @TRACE@("Scanning GNOME2_PATH directory: $dir");
- if ($dir !~ m%^\Q$path_prefix\E/%) {
- &ScanIndices ($dir, 1);
- } else {
- &ScanIndices ($dir, 0);
- }
- }
- # ubuntu started to compress this as index.sgml.gz :/
- # https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138
- }
- }
-
- @TRACE@("Scanning HTML_DIR directory: $HTML_DIR");
- &ScanIndices ($HTML_DIR, 0);
- @TRACE@("Scanning HTML_DIR directory: $MODULE_DIR");
- &ScanIndices ($MODULE_DIR, 0);
-
- # check all extra dirs, but skip already scanned dirs or subdirs of those
- foreach my $dir (@EXTRA_DIRS) {
- my $vdir;
-
- $dir =~ s#/$##;
- @TRACE@("Scanning EXTRA_DIR directory: $dir");
-
- # If the --extra-dir option is not relative and is not sharing the same
- # prefix as the target directory of the docs, we need to use absolute
- # directories for the links
- if ($dir !~m/^\.\./ && $dir !~ m%\Q$path_prefix\E/%) {
- &ScanIndices ($dir, 1);
- } else {
- &ScanIndices ($dir, 0);
- }
- }
-
- &ReadSections ();
-
- &FixCrossReferences ($MODULE_DIR);
-}
-
-
-sub ScanIndices {
- my ($scan_dir, $use_absolute_links) = @_;
-
- if (exists $DirCache{$scan_dir}) {
- return;
- }
- $DirCache{$scan_dir} = 1;
-
- @TRACE@("Scanning source directory: $scan_dir absolute: $use_absolute_links");
-
- # This array holds any subdirectories found.
- my (@subdirs) = ();
-
- opendir (HTMLDIR, $scan_dir) || return;
- my $file;
- foreach $file (readdir (HTMLDIR)) {
- if ($file eq '.' || $file eq '..') {
- next;
- } elsif (-d "$scan_dir/$file") {
- push (@subdirs, $file);
- next;
- }
- if ($file =~ m/\.devhelp2$/) {
- # if devhelp-file is good don't read index.sgml
- &ReadDevhelp ("$scan_dir/$file", $use_absolute_links);
- }
- elsif ($file eq "index.sgml.gz") {
- # debian/ubuntu started to compress this as index.sgml.gz :/
- print <<EOF;
-Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138 . For now run:
-gunzip $scan_dir/$file
-EOF
- }
- elsif ($file =~ m/\.devhelp2.gz$/) {
- # debian/ubuntu started to compress this as *devhelp2.gz :/
- print <<EOF;
-Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/1466210 . For now run:
-gunzip $scan_dir/$file
-EOF
- }
- # we could consider supporting: use IO::Zlib;
- }
- closedir (HTMLDIR);
-
- # Now recursively scan the subdirectories.
- my $dir;
- foreach $dir (sort(@subdirs)) {
- &ScanIndices ("$scan_dir/$dir", $use_absolute_links);
- }
-}
-
-
-sub ReadDevhelp {
- my ($file, $use_absolute_links) = @_;
-
- # Determine the absolute directory, to be added to links in $file
- # if we need to use an absolute link.
- # $file will be something like /prefix/gnome/share/gtk-doc/html/gtk/$file
- # We want the part up to 'html/.*' since the links in $file include
- # the rest.
- my $dir = "../";
- if ($use_absolute_links) {
- # For uninstalled index.sgml files we'd need to map the path to where it
- # will be installed to
- if ($file !~ /\.\//) {
- $file =~ /(.*\/)(.*?)\/.*?\.devhelp2/;
- $dir = "$1$2";
- }
- } else {
- if ($file =~ /(.*\/)(.*?)\/.*?\.devhelp2/) {
- $dir .= "$2/";
- } else {
- $dir = "";
- }
- }
-
- @TRACE@("Scanning index file=$file, absolute=$use_absolute_links, dir=$dir");
-
- open (INDEXFILE, $file)
- || die "Can't open $file: $!";
- while (<INDEXFILE>) {
- if (m/ link="([^#]*)#([^"]*)"/) {
- @TRACE@("Found id: $2 href: $1#$2");
- $Links{$2} = "$dir$1#$2";
- }
- }
- close (INDEXFILE);
-}
-
-
-sub ReadSections {
- if (!defined($MODULE)) {
- return;
- }
-
- open (INPUT, "$MODULE-sections.txt")
- || die "Can't open $MODULE-sections.txt: $!";
- my $subsection = "";
- while (<INPUT>) {
- if (m/^#/) {
- next;
-
- } elsif (m/^<SECTION>/) {
- $subsection = "";
- } elsif (m/^<SUBSECTION\s*(.*)>/i) {
- $subsection = $1;
- } elsif (m/^<SUBSECTION>/) {
- next;
- } elsif (m/^<TITLE>(.*)<\/TITLE>/) {
- next;
- } elsif (m/^<FILE>(.*)<\/FILE>/) {
- next;
- } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
- next;
- } elsif (m/^<\/SECTION>/) {
- next;
- } elsif (m/^(\S+)/) {
- my $symbol=$1;
-
- if ($subsection eq "Standard" || $subsection eq "Private") {
- $NoLinks{CreateValidSGMLID($symbol)} = 1;
- }
- }
- }
- close (INPUT);
-}
-
-
-sub FixCrossReferences {
- my ($scan_dir) = @_;
-
- opendir (HTMLDIR, $scan_dir)
- || die "Can't open HTML directory $scan_dir: $!";
- my $file;
- foreach $file (readdir (HTMLDIR)) {
- if ($file eq '.' || $file eq '..') {
- next;
- } elsif ($file =~ m/.html?$/) {
- &FixHTMLFile ("$scan_dir/$file");
- }
- }
- closedir (HTMLDIR);
-}
-
-
-sub FixHTMLFile {
- my ($file) = @_;
- @TRACE@("Fixing file: $file");
-
- open (HTMLFILE, $file)
- || die "Can't open $file: $!";
- undef $/;
- my $entire_file = <HTMLFILE>;
- close (HTMLFILE);
-
- if ("@HIGHLIGHT@" ne "") {
- # FIXME: ideally we'd pass a clue about the example language to the highligher
- # unfortunately the "language" attribute is not appearing in the html output
- # we could patch the customization to have <code class="xxx"> inside of <pre>
- if ("@HIGHLIGHT@" =~ m%/vim$%) {
- $entire_file =~ s%<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>%&HighlightSourceVim($1,$2);%gse;
- }
- else {
- $entire_file =~ s%<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>%&HighlightSource($1,$2);%gse;
- }
- # this just broke existing GTKDOCLINK tags
- # <GTKDOCLINK HREF="GST-PAD-SINK:CAPS">GST_PAD_SINK</GTKDOCLINK>
- $entire_file =~ s%\<GTKDOCLINK\s+HREF=\"(.*?)\"\>(.*?)\</GTKDOCLINK\>%\<GTKDOCLINK\ HREF=\"$1\"\>$2\</GTKDOCLINK\>%gs;
-
- # from the highlighter we get all the functions marked up
- # now we could turn them into GTKDOCLINK items
- $entire_file =~ s%(<span class=\"function\">)(.*?)(</span>)%&MakeGtkDocLink($1,$2,$3);%gse;
- # we could also try the first item in stuff marked up as 'normal'
- $entire_file =~ s%(<span class=\"normal\">\s*)(.+?)((\s+.+?)?\s*</span>)%&MakeGtkDocLink($1,$2,$3);%gse;
- }
-
- my @lines = split(/\n/, $entire_file);
- for (my $i=0; $i<$#lines; $i++) {
- $lines[$i] =~ s%<GTKDOCLINK\s+HREF="([^"]*)"\s*>(.*?)</GTKDOCLINK\s*>% &MakeXRef($file,$i+1,$1,$2); %ge;
- #if ($lines[$i] =~ m/GTKDOCLINK/) {
- # print "make xref failed for line: ",$lines[$i], "\n";
- #}
- }
- $entire_file = join("\n",@lines);
-
- open (NEWFILE, ">$file.new")
- || die "Can't open $file: $!";
- print NEWFILE $entire_file;
- close (NEWFILE);
-
- unlink ($file)
- || die "Can't delete $file: $!";
- rename ("$file.new", $file)
- || die "Can't rename $file.new: $!";
-}
-
-sub MakeXRef {
- my ($file, $line, $id, $text) = @_;
-
- my $href = $Links{$id};
-
- # this is a workaround for some inconsistency we have with CreateValidSGMLID
- if (!$href && $id =~ m/:/) {
- my $tid = $id;
- $tid =~ s/:/--/g;
- $href = $Links{$tid};
- }
- # poor mans plural support
- if (!$href && $id =~ m/s$/) {
- my $tid = $id;
- $tid =~ s/s$//g;
- $href = $Links{$tid};
- if (!$href && defined $Links{"$tid-struct"}) {
- $href = $Links{"$tid-struct"};
- }
- }
- if (!$href && defined $Links{"$id-struct"}) {
- $href = $Links{"$id-struct"};
- }
-
- if ($href) {
- # if it is a link to same module, remove path to make it work
- # uninstalled
- if (defined($MODULE) && $href =~ m%^\.\./$MODULE/(.*)$%) {
- $href=$1;
- @TRACE@(" Fixing link to uninstalled doc: $id, $href, $text");
- } else {
- @TRACE@(" Fixing link: $id, $href, $text");
- }
- return "<a href=\"$href\">$text</a>";
- } else {
- my $warn = 1;
- @TRACE@(" no link for: $id, $text");
-
- # don't warn multiple times and also skip blacklisted (ctypes)
- $warn = 0 if exists $NoLinks{$id};
- # 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
- $warn = 0 if ($text =~ m/ class=\"function\"/ && $id !~ m/-/);
- # if it's a 'return value', don't warn (implicitly created link)
- $warn = 0 if ($text =~ m/ class=\"returnvalue\"/);
- # if it's a 'type', don't warn if it starts with lowercase
- # - gnome coding style would use CamelCase
- $warn = 0 if ($text =~ m/ class=\"type\"/ && ($id =~ m/^[a-z]/));
- # don't warn for self links
- $warn = 0 if ($text eq $id);
-
- if ($warn == 1) {
- &LogWarning ($file, $line, "no link for: '$id' -> ($text).");
- $NoLinks{$id} = 1;
- }
- return $text;
- }
-}
-
-
-sub MakeGtkDocLink {
- my ($pre,$symbol,$post) = @_;
-
- my $id=CreateValidSGMLID($symbol);
-
- # these are implicitely created links in highlighed sources
- # we don't want warnings for those if the links cannot be resolved.
- $NoLinks{$id} = 1;
-
- #return "<span class=\"$type\"><GTKDOCLINK HREF=\"$id\">$symbol</GTKDOCLINK></span>";
- return "$pre<GTKDOCLINK HREF=\"$id\">$symbol</GTKDOCLINK>$post";
-}
-
-
-sub HighlightSource {
- my ($type, $source) = @_;
-
- # chop of leading and trailing empty lines
- $source =~ s/^\s*\n+//gs;
- $source =~ s/[\s\n]+$//gs;
- # cut common indent
- $source =~ m/^(\s*)/;
- $source =~ s/^$1//gms;
- # avoid double entity replacement
- $source =~ s/</</g;
- $source =~ s/>/>/g;
- $source =~ s/&/&/g;
-
- # write source to a temp file
- # FIXME: use .c for now to hint the language to the highlighter
- my $temp_source_file="$MODULE_DIR/_temp_src.$$.c";
- open (NEWFILE, ">$temp_source_file") || die "Can't open $temp_source_file: $!";
- print NEWFILE $source;
- close (NEWFILE);
-
- @TRACE@(" running @HIGHLIGHT@ @HIGHLIGHT_OPTIONS@$temp_source_file ");
-
- # format source
- my $highlighted_source=`@HIGHLIGHT@ @HIGHLIGHT_OPTIONS@$temp_source_file`;
- if ("@HIGHLIGHT@" =~ m%/source-highlight$%) {
- $highlighted_source =~ s%^<\!-- .*? -->%%gs;
- $highlighted_source =~ s%<pre><tt>(.*?)</tt></pre>%$1%gs;
- }
- elsif ("@HIGHLIGHT@" =~ m%/highlight$%) {
- # need to rewrite the stylesheet classes
- $highlighted_source =~ s%<span class="gtkdoc com">%<span class="comment">%gs;
- $highlighted_source =~ s%<span class="gtkdoc dir">%<span class="preproc">%gs;
- $highlighted_source =~ s%<span class="gtkdoc kwd">%<span class="function">%gs;
- $highlighted_source =~ s%<span class="gtkdoc kwa">%<span class="keyword">%gs;
- $highlighted_source =~ s%<span class="gtkdoc line">%<span class="linenum">%gs;
- $highlighted_source =~ s%<span class="gtkdoc num">%<span class="number">%gs;
- $highlighted_source =~ s%<span class="gtkdoc str">%<span class="string">%gs;
- $highlighted_source =~ s%<span class="gtkdoc sym">%<span class="symbol">%gs;
- # maybe also do
- # $highlighted_source =~ s%</span>(.+)<span%</span><span class="normal">$1</span><span%gs;
- }
- # remove temp file
- unlink ($temp_source_file)
- || die "Can't delete $temp_source_file: $!";
-
- return &HighlightSourcePostprocess($type, $highlighted_source);
-}
-
-
-sub HighlightSourceVim {
- my ($type, $source) = @_;
-
- # chop of leading and trailing empty lines
- $source =~ s/^\s*\n+//gs;
- $source =~ s/[\s\n]+$//gs;
- # cut common indent
- $source =~ m/^(\s*)/;
- $source =~ s/^$1//gms;
- # avoid double entity replacement
- $source =~ s/</</g;
- $source =~ s/>/>/g;
- $source =~ s/&/&/g;
-
- # write source to a temp file
- my $temp_source_file="$MODULE_DIR/_temp_src.$$.h";
- open (NEWFILE, ">$temp_source_file") || die "Can't open $temp_source_file: $!";
- print NEWFILE $source;
- close (NEWFILE);
-
- # format source
- system "echo 'let html_number_lines=0|let html_use_css=1|let html_use_xhtml=1|e $temp_source_file|syn on|set syntax=$SRC_LANG|run! syntax/2html.vim|w! $temp_source_file.html|qa!' | @HIGHLIGHT@ -n -e -u NONE -T xterm >/dev/null";
-
- my $highlighted_source;
- {
- local $/;
- open (NEWFILE, "<$temp_source_file.html");
- $highlighted_source = <NEWFILE>;
- close (NEWFILE);
- }
- $highlighted_source =~ s#.*<pre\b[^>]*>\n##s;
- $highlighted_source =~ s#</pre>.*##s;
-
- # need to rewrite the stylesheet classes
- # FIXME: Vim has somewhat different syntax groups
- $highlighted_source =~ s%<span class="Comment">%<span class="comment">%gs;
- $highlighted_source =~ s%<span class="PreProc">%<span class="preproc">%gs;
- $highlighted_source =~ s%<span class="Statement">%<span class="keyword">%gs;
- $highlighted_source =~ s%<span class="Identifier">%<span class="function">%gs;
- $highlighted_source =~ s%<span class="Constant">%<span class="number">%gs;
- $highlighted_source =~ s%<span class="Special">%<span class="symbol">%gs;
- $highlighted_source =~ s%<span class="Type">%<span class="type">%gs;
-
- # remove temp files
- unlink ($temp_source_file)
- || die "Can't delete $temp_source_file: $!";
- unlink ("$temp_source_file.html")
- || die "Can't delete $temp_source_file.html: $!";
-
- return &HighlightSourcePostprocess($type, $highlighted_source);
-}
-
-
-sub HighlightSourcePostprocess {
- my ($type, $highlighted_source) = @_;
-
- # chop of leading and trailing empty lines
- $highlighted_source =~ s/^[\s\n]+//gs;
- $highlighted_source =~ s/[\s\n]+$//gs;
-
- # turn common urls in comments into links
- $highlighted_source =~ s%<span class="url">(.*?)</span>%<span class="url"><a href="$1">$1</a></span>%gs;
-
- # we do own line-numbering
- my $source_lines="";
- my $line_count = () = $highlighted_source =~ /\n/gs;
- for (my $i=1; $i < ($line_count+2); $i++) {
- $source_lines.="$i\n";
- }
- $source_lines =~ s/\n\Z//;
-
- return <<END_OF_HTML
-<div class="$type">
- <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
- <tbody>
- <tr>
- <td class="listing_lines" align="right"><pre>$source_lines</pre></td>
- <td class="listing_code"><pre class="programlisting">$highlighted_source</pre></td>
- </tr>
- </tbody>
- </table>
-</div>
-END_OF_HTML
-}
+import argparse
+import os
+import sys
+sys.path.append('@PYTHON_PACKAGE_DIR@')
+
+from gtkdoc import common, config, fixxref
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ description='gtkdoc-fixxref version %s - fix cross references in html files' % config.version)
+ parser.add_argument('--version', action='version', version=config.version)
+ parser.add_argument('--module', required=True,
+ help='Name of the doc module being processed.')
+ parser.add_argument('--module-dir', default='',
+ help='The directory which contains the generated HTML.')
+ parser.add_argument('--html-dir', default='',
+ help='The directory where gtk-doc generated documentation is'
+ 'installed.')
+ parser.add_argument('--extra-dir', default=[], action='append',
+ help='Directories to recursively scan for indices (index.sgml)'
+ 'in addition to HTML_DIR')
+ parser.add_argument('--src-lang', default='c',
+ help='Programing language used for syntax highlighting. The'
+ 'available languages depend on the source'
+ 'highlighter you use.')
+
+ options = parser.parse_args()
+
+ if not options.module_dir:
+ options.module_dir = os.path.join(options.html_dir, options.module)
+
+ common.setup_logging()
+
+ fixxref.Run(options)
-#!@PERL@ -w
-# -*- cperl -*-
+#!@PYTHON@
+# -*- python; coding: utf-8 -*-
#
# gtk-doc - GTK DocBook documentation generator.
# Copyright (C) 1998 Damon Chaplin
-# 2007,2008,2009 Stefan Kost
+# 2007-2016 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
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
-#############################################################################
-# Script : gtkdoc-mkdb
-# Description : This creates the DocBook files from the edited templates.
-#############################################################################
-
-use warnings;
-use strict;
-use Getopt::Long;
-
-push @INC, '@PACKAGE_DATA_DIR@';
-require "gtkdoc-common.pl";
-
-# Options
-
-# name of documentation module
-my $MODULE;
-my $TMPL_DIR;
-my $DB_OUTPUT_DIR;
-my @SOURCE_DIRS;
-my $SOURCE_SUFFIXES = "";
-my $IGNORE_FILES = "";
-my $PRINT_VERSION;
-my $PRINT_HELP;
-my $MAIN_SGML_FILE;
-my $EXPAND_CONTENT_FILES = "";
-my $INLINE_MARKUP_MODE;
-my $DEFAULT_STABILITY;
-my $DEFAULT_INCLUDES;
-my $OUTPUT_FORMAT;
-my $NAME_SPACE = "";
-my $OUTPUT_ALL_SYMBOLS;
-my $OUTPUT_SYMBOLS_WITHOUT_SINCE;
-my $ROOT_DIR = ".";
-my $OBJECT_TREE_FILE;
-my $INTERFACES_FILE;
-my $PREREQUISITES_FILE;
-my $SIGNALS_FILE;
-my $ARGS_FILE;
-
-# These global arrays store information on signals. Each signal has an entry
-# in each of these arrays at the same index, like a multi-dimensional array.
-my @SignalObjects; # The GtkObject which emits the signal.
-my @SignalNames; # The signal name.
-my @SignalReturns; # The return type.
-my @SignalFlags; # Flags for the signal
-my @SignalPrototypes; # The rest of the prototype of the signal handler.
-
-# These global arrays store information on Args. Each Arg has an entry
-# in each of these arrays at the same index, like a multi-dimensional array.
-my @ArgObjects; # The GtkObject which has the Arg.
-my @ArgNames; # The Arg name.
-my @ArgTypes; # The Arg type - gint, GtkArrowType etc.
-my @ArgFlags; # How the Arg can be used - readable/writable etc.
-my @ArgNicks; # The nickname of the Arg.
-my @ArgBlurbs; # Docstring of the Arg.
-my @ArgDefaults; # Default value of the Arg.
-my @ArgRanges; # The range of the Arg type
-# These global hashes store declaration info keyed on a symbol name.
-my %Declarations;
-my %DeclarationTypes;
-my %DeclarationConditional;
-my %DeclarationOutput;
-my %Deprecated;
-my %Since;
-my %StabilityLevel;
-my %StructHasTypedef;
-
-# These global hashes store the existing documentation.
-my %SymbolDocs;
-my %SymbolTypes;
-my %SymbolParams;
-my %SymbolSourceFile;
-my %SymbolSourceLine;
-my %SymbolAnnotations;
-
-# These global hashes store documentation scanned from the source files.
-my %SourceSymbolDocs;
-my %SourceSymbolParams;
-my %SourceSymbolSourceFile;
-my %SourceSymbolSourceLine;
-
-# all documentation goes in here, so we can do coverage analysis
-my %AllSymbols;
-my %AllIncompleteSymbols;
-my %AllUnusedSymbols;
-my %AllDocumentedSymbols;
-
-# Undeclared yet documented symbols
-my %UndeclaredSymbols;
-
-# These global arrays store GObject, subclasses and the hierarchy (also of
-# non-object derived types).
-my @Objects;
-my @ObjectLevels;
-my %ObjectRoots;
-
-my %Interfaces;
-my %Prerequisites;
-
-# holds the symbols which are mentioned in $MODULE-sections.txt and in which
-# section they are defined
-my %KnownSymbols;
-my %SymbolSection;
-my %SymbolSectionId;
-
-# collects index entries
-my %IndexEntriesFull;
-my %IndexEntriesSince;
-my %IndexEntriesDeprecated;
-
-# Standard C preprocessor directives, which we ignore for '#' abbreviations.
-my %PreProcessorDirectives = (
- 'assert' => 1,
- 'define' => 1,
- 'elif' => 1,
- 'else' => 1,
- 'endif' => 1,
- 'error' => 1,
- 'if' => 1,
- 'ifdef' => 1,
- 'ifndef' => 1,
- 'include' => 1,
- 'line' => 1,
- 'pragma' => 1,
- 'unassert' => 1,
- 'undef' => 1,
- 'warning' => 1
-);
-
-# remember used annotation (to write minimal glossary)
-my %AnnotationsUsed;
-
-my %AnnotationDefinition = (
- # the GObjectIntrospection annotations are defined at:
- # https://live.gnome.org/GObjectIntrospection/Annotations
- 'allow-none' => "NULL is OK, both for passing and for returning.",
- 'nullable' => "NULL may be passed as the value in, out, in-out; or as a return value.",
- 'not nullable' => "NULL must not be passed as the value in, out, in-out; or as a return value.",
- 'optional' => "NULL may be passed instead of a pointer to a location.",
- 'array' => "Parameter points to an array of items.",
- 'attribute' => "Deprecated free-form custom annotation, replaced by (attributes) annotation.",
- 'attributes' => "Free-form key-value pairs.",
- 'closure' => "This parameter is a 'user_data', for callbacks; many bindings can pass NULL here.",
- 'constructor' => "This symbol is a constructor, not a static method.",
- 'destroy' => "This parameter is a 'destroy_data', for callbacks.",
- 'default' => "Default parameter value (for in case the <acronym>shadows</acronym>-to function has less parameters).",
- 'element-type' => "Generics and defining elements of containers and arrays.",
- 'error-domains' => "Typed errors. Similar to throws in Java.",
- 'foreign' => "This is a foreign struct.",
- 'get-value-func' => "The specified function is used to convert a struct from a GValue, must be a GTypeInstance.",
- 'in' => "Parameter for input. Default is <acronym>transfer none</acronym>.",
- 'inout' => "Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.",
- 'in-out' => "Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.",
- 'method' => "This is a method",
- 'not-error' => "A GError parameter is not to be handled like a normal GError.",
- 'out' => "Parameter for returning results. Default is <acronym>transfer full</acronym>.",
- 'out caller-allocates' => "Out parameter, where caller must allocate storage.",
- 'out callee-allocates' => "Out parameter, where caller must allocate storage.",
- 'ref-func' => "The specified function is used to ref a struct, must be a GTypeInstance.",
- 'rename-to' => "Rename the original symbol's name to SYMBOL.",
- 'scope call' => "The callback is valid only during the call to the method.",
- 'scope async' => "The callback is valid until first called.",
- 'scope notified' => "The callback is valid until the GDestroyNotify argument is called.",
- 'set-value-func' => "The specified function is used to convert from a struct to a GValue, must be a GTypeInstance.",
- 'skip' => "Exposed in C code, not necessarily available in other languages.",
- 'transfer container' => "Free data container after the code is done.",
- 'transfer floating' => "Alias for <acronym>transfer none</acronym>, used for objects with floating refs.",
- 'transfer full' => "Free data after the code is done.",
- 'transfer none' => "Don't free data after the code is done.",
- 'type' => "Override the parsed C type with given type.",
- 'unref-func' => "The specified function is used to unref a struct, must be a GTypeInstance.",
- 'virtual' => "This is the invoker for a virtual method.",
- 'value' => "The specified value overrides the evaluated value of the constant.",
- # Stability Level definition
- # https://bugzilla.gnome.org/show_bug.cgi?id=170860
- 'Stable' => <<EOF,
-The intention of a Stable interface is to enable arbitrary third parties to
-develop applications to these interfaces, release them, and have confidence that
-they will run on all minor releases of the product (after the one in which the
-interface was introduced, and within the same major release). Even at a major
-release, incompatible changes are expected to be rare, and to have strong
-justifications.
-EOF
- 'Unstable' => <<EOF,
-Unstable interfaces are experimental or transitional. They are typically used to
-give outside developers early access to new or rapidly changing technology, or
-to provide an interim solution to a problem where a more general solution is
-anticipated. No claims are made about either source or binary compatibility from
-one minor release to the next.
-
-The Unstable interface level is a warning that these interfaces are subject to
-change without warning and should not be used in unbundled products.
-
-Given such caveats, customer impact need not be a factor when considering
-incompatible changes to an Unstable interface in a major or minor release.
-Nonetheless, when such changes are introduced, the changes should still be
-mentioned in the release notes for the affected release.
-EOF
- 'Private' => <<EOF
-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 specified and
-documented ways.
-EOF
-);
-
-# Elements to consider non-block items in MarkDown parsing
-my %MD_TEXT_LEVEL_ELEMENTS = ( "literal" => 1,
- "emphasis" => 1,
- "envar" => 1,
- "filename" => 1,
- "firstterm" => 1,
- "footnote" => 1,
- "function" => 1,
- "manvolnum" => 1,
- "option" => 1,
- "replaceable" => 1,
- "structfield" => 1,
- "structname" => 1,
- "title" => 1,
- "varname" => 1 );
-my %MD_ESCAPABLE_CHARS = ( "\\" => 1,
- "`" => 1,
- "*" => 1,
- "_" => 1,
- "{" => 1,
- "}" => 1,
- "[" => 1,
- "]" => 1,
- "(" => 1,
- ")" => 1,
- ">" => 1,
- "#" => 1,
- "+" => 1,
- "-" => 1,
- "." => 1,
- "!" => 1 );
-my %MD_GTK_ESCAPABLE_CHARS = ( "@" => 1,
- "%" => 1 );
-
-# Function and other declaration output settings.
-my $RETURN_TYPE_FIELD_WIDTH = 20;
-my $SYMBOL_FIELD_WIDTH = 36;
-my $MAX_SYMBOL_FIELD_WIDTH = 40;
-my $SIGNAL_FIELD_WIDTH = 16;
-my $PARAM_FIELD_COUNT = 2;
-
-# XML, SGML formatting helper
-my $doctype_header;
-
-
-run() unless caller; # Run program unless loaded as a module
-
-
-sub run {
- my %optctl = ('module' => \$MODULE,
- 'source-dir' => \@SOURCE_DIRS,
- 'source-suffixes' => \$SOURCE_SUFFIXES,
- 'ignore-files' => \$IGNORE_FILES,
- 'output-dir' => \$DB_OUTPUT_DIR,
- 'tmpl-dir' => \$TMPL_DIR,
- 'version' => \$PRINT_VERSION,
- 'help' => \$PRINT_HELP,
- 'main-sgml-file' => \$MAIN_SGML_FILE,
- 'expand-content-files' => \$EXPAND_CONTENT_FILES,
- 'sgml-mode' => \$INLINE_MARKUP_MODE,
- 'xml-mode' => \$INLINE_MARKUP_MODE,
- 'default-stability' => \$DEFAULT_STABILITY,
- 'default-includes' => \$DEFAULT_INCLUDES,
- 'output-format' => \$OUTPUT_FORMAT,
- 'name-space' => \$NAME_SPACE,
- 'outputallsymbols' => \$OUTPUT_ALL_SYMBOLS,
- 'outputsymbolswithoutsince' => \$OUTPUT_SYMBOLS_WITHOUT_SINCE
- );
- GetOptions(\%optctl, "module=s", "source-dir:s", "source-suffixes:s",
- "ignore-files:s", "output-dir:s", "tmpl-dir:s", "version",
- "outputallsymbols", "outputsymbolswithoutsince",
- "expand-content-files:s", "main-sgml-file:s", "extra-db-files:s", "help",
- "sgml-mode", "xml-mode", "default-stability:s", "default-includes:s",
- "output-format:s", "name-space:s");
-
- if ($PRINT_VERSION) {
- print "@VERSION@\n";
- exit 0;
- }
-
- if (!$MODULE) {
- $PRINT_HELP = 1;
- }
-
- if ($DEFAULT_STABILITY && $DEFAULT_STABILITY ne "Stable"
- && $DEFAULT_STABILITY ne "Private" && $DEFAULT_STABILITY ne "Unstable") {
- $PRINT_HELP = 1;
- }
-
- if ($PRINT_HELP) {
- print <<EOF;
-gtkdoc-mkdb version @VERSION@ - generate docbook files
-
---module=MODULE_NAME Name of the doc module being parsed
---source-dir=DIRNAME Directories which contain inline reference material
---source-suffixes=SUFFIXES Suffixes of source files to scan, comma-separated
---ignore-files=FILES A space-separated list of header files/dirs not to
- scan
---output-dir=DIRNAME Directory to put the generated DocBook files in
---tmpl-dir=DIRNAME Directory in which template files may be found
---main-sgml-file=FILE File containing the toplevel DocBook file.
---expand-content-files=FILES Extra DocBook files to expand abbreviations in.
---output-format=FORMAT Format to use for the generated docbook, XML or SGML.
---{xml,sgml}-mode Allow DocBook markup in inline documentation.
---default-stability=LEVEL Specify default stability Level. Valid values are
- Stable, Unstable, or Private.
---default-includes=FILENAMES Specify default includes for section Synopsis
---name-space=NS Omit namespace in index.
---version Print the version of this program
---help Print this help
-EOF
- exit 0;
- }
-
- @TRACE@(" ignore files: [$IGNORE_FILES]\n");
-
- # check output format
- if (! defined($OUTPUT_FORMAT) || ($OUTPUT_FORMAT eq "")) {
- $OUTPUT_FORMAT = "xml";
- } else {
- $OUTPUT_FORMAT = lc($OUTPUT_FORMAT);
- }
- if ($OUTPUT_FORMAT ne "xml") {
- die "Invalid format '$OUTPUT_FORMAT' passed to --output.format"
- }
-
- if (!$MAIN_SGML_FILE) {
- # backwards compatibility
- if (-e "${MODULE}-docs.sgml") {
- $MAIN_SGML_FILE = "${MODULE}-docs.sgml";
- } else {
- $MAIN_SGML_FILE = "${MODULE}-docs.xml";
- }
- }
-
- # extract docbook header or define default
- if (-e $MAIN_SGML_FILE) {
- open(INPUT, "<$MAIN_SGML_FILE") || die "Can't open $MAIN_SGML_FILE";
- $doctype_header = "";
- while (<INPUT>) {
- if (/^\s*<(book|chapter|article)/) {
- # check that the top-level tagSYSTEM or the doctype decl contain the xinclude namespace decl
- if (($_ !~ m/http:\/\/www.w3.org\/200[13]\/XInclude/) && ($doctype_header !~ m/http:\/\/www.w3.org\/200[13]\/XInclude/m)) {
- $doctype_header = "";
- }
- last;
- }
- # if there are SYSTEM ENTITIES here, we should prepend "../" to the path
- # FIXME: not sure if we can do this now, as people already work-around the problem
- # s#<!ENTITY % ([a-zA-Z-]+) SYSTEM \"([^/][a-zA-Z./]+)\">#<!ENTITY % $1 SYSTEM \"../$2\">#;
- s#<!ENTITY % gtkdocentities SYSTEM \"([^"]*)\">#<!ENTITY % gtkdocentities SYSTEM \"../$1\">#;
- $doctype_header .= $_;
- }
- close(INPUT);
- } else {
- $doctype_header = <<EOF;
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
-[
- <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
- <!ENTITY % gtkdocentities SYSTEM "../xml/gtkdocentities.ent">
- %gtkdocentities;
-]>
-EOF
- }
- chomp($doctype_header);
-
- # All the files are written in subdirectories beneath here.
- $TMPL_DIR = $TMPL_DIR ? $TMPL_DIR : "$ROOT_DIR/tmpl";
-
- # This is where we put all the DocBook output.
- $DB_OUTPUT_DIR = $DB_OUTPUT_DIR ? $DB_OUTPUT_DIR : "$ROOT_DIR/xml";
-
- # This file contains the object hierarchy.
- $OBJECT_TREE_FILE = "$ROOT_DIR/$MODULE.hierarchy";
-
- # This file contains the interfaces.
- $INTERFACES_FILE = "$ROOT_DIR/$MODULE.interfaces";
-
- # This file contains the prerequisites.
- $PREREQUISITES_FILE = "$ROOT_DIR/$MODULE.prerequisites";
-
- # This file contains signal arguments and names.
- $SIGNALS_FILE = "$ROOT_DIR/$MODULE.signals";
-
- # The file containing Arg information.
- $ARGS_FILE = "$ROOT_DIR/$MODULE.args";
-
- # Create the root DocBook output directory if it doens't exist.
- if (! -e $DB_OUTPUT_DIR) {
- mkdir ("$DB_OUTPUT_DIR", 0777)
- || die "Can't create directory: $DB_OUTPUT_DIR";
- }
-
- &ReadKnownSymbols ("$ROOT_DIR/$MODULE-sections.txt");
- &ReadSignalsFile ($SIGNALS_FILE);
- &ReadArgsFile ($ARGS_FILE);
- &ReadObjectHierarchy;
- &ReadInterfaces;
- &ReadPrerequisites;
-
- &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-decl.txt", 0);
- if (-f "$ROOT_DIR/$MODULE-overrides.txt") {
- &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-overrides.txt", 1);
- }
-
- for my $dir (@SOURCE_DIRS) {
- &ReadSourceDocumentation ($dir);
- }
-
- my $changed = &OutputDB ("$ROOT_DIR/$MODULE-sections.txt");
-
- # If any of the DocBook files have changed, update the timestamp file (so
- # it can be used for Makefile dependencies).
- if ($changed || ! -e "$ROOT_DIR/sgml.stamp") {
-
- # try to detect the common prefix
- # GtkWidget, GTK_WIDGET, gtk_widget -> gtk
- if ($NAME_SPACE eq "") {
- $NAME_SPACE="";
- my $pos=0;
- my $ratio=0.0;
- do {
- my %prefix;
- my $letter="";
- foreach my $symbol (keys(%IndexEntriesFull)) {
- if(($NAME_SPACE eq "") || $symbol =~ /^$NAME_SPACE/i) {
- if (length($symbol)>$pos) {
- $letter=substr($symbol,$pos,1);
- # stop prefix scanning
- if ($letter eq "_") {
- # stop on "_"
- last;
- }
- # Should we also stop on a uppercase char, if last was lowercase
- # GtkWidget, if we have the 'W' and had the 't' before
- # or should we count upper and lowercase, and stop one 2nd uppercase, if we already had a lowercase
- # GtkWidget, the 'W' would be the 2nd uppercase and with 't','k' we had lowercase chars before
- # need to recound each time as this is per symbol
- $prefix{uc($letter)}++;
- }
- }
- }
- if ($letter ne "" && $letter ne "_") {
- my $maxletter="";
- my $maxsymbols=0;
- foreach $letter (keys(%prefix)) {
- #print "$letter: $prefix{$letter}.\n";
- if ($prefix{$letter}>$maxsymbols) {
- $maxletter=$letter;
- $maxsymbols=$prefix{$letter};
- }
- }
- $ratio = scalar(keys(%IndexEntriesFull)) / $prefix{$maxletter};
- #print "most symbols start with $maxletter, that is ". (100 * $ratio) ." %\n";
- if ($ratio > 0.9) {
- # do another round
- $NAME_SPACE .= $maxletter;
- }
- $pos++;
- }
- else {
- $ratio=0.0;
- }
- } while ($ratio > 0.9);
- #print "most symbols start with $NAME_SPACE\n";
- }
-
- &OutputIndexFull;
- &OutputDeprecatedIndex;
- &OutputSinceIndexes;
- &OutputAnnotationGlossary;
-
- open (TIMESTAMP, ">$ROOT_DIR/sgml.stamp")
- || die "Can't create $ROOT_DIR/sgml.stamp: $!";
- print (TIMESTAMP "timestamp");
- close (TIMESTAMP);
- }
-}
-
-#############################################################################
-# Function : OutputObjectList
-# Description : This outputs the alphabetical list of objects, in a columned
-# table.
-# FIXME: Currently this also outputs ancestor objects
-# which may not actually be in this module.
-# Arguments : none
-#############################################################################
-
-sub OutputObjectList {
- my $cols = 3;
-
- # FIXME: use .xml
- # my $old_object_index = "$DB_OUTPUT_DIR/object_index.xml";
- my $old_object_index = "$DB_OUTPUT_DIR/object_index.sgml";
- my $new_object_index = "$DB_OUTPUT_DIR/object_index.new";
-
- open (OUTPUT, ">$new_object_index")
- || die "Can't create $new_object_index: $!";
-
- print (OUTPUT <<EOF);
-${\( MakeDocHeader ("informaltable") )}
-<informaltable pgwide="1" frame="none">
-<tgroup cols="$cols">
-<colspec colwidth="1*"/>
-<colspec colwidth="1*"/>
-<colspec colwidth="1*"/>
-<tbody>
-EOF
-
- my $count = 0;
- my $object;
- foreach $object (sort (@Objects)) {
- my $xref = &MakeXRef ($object);
- if ($count % $cols == 0) { print (OUTPUT "<row>\n"); }
- print (OUTPUT "<entry>$xref</entry>\n");
- if ($count % $cols == ($cols - 1)) { print (OUTPUT "</row>\n"); }
- $count++;
- }
- if ($count == 0) {
- # emit an empty row, since empty tables are invalid
- print (OUTPUT "<row><entry> </entry></row>\n");
- }
- else {
- if ($count % $cols > 0) {
- print (OUTPUT "</row>\n");
- }
- }
-
- print (OUTPUT <<EOF);
-</tbody></tgroup></informaltable>
-EOF
- close (OUTPUT);
-
- &UpdateFileIfChanged ($old_object_index, $new_object_index, 0);
-}
-
-#############################################################################
-# Function : TrimTextBlock
-# Description : Trims extra whitespace. Empty lines inside a block are
-# preserved.
-# Arguments : $desc - the text block to trim. May contain newlines.
-#############################################################################
-
-sub TrimTextBlock {
- my ($desc) = @_;
-
- # strip leading spaces on the block
- $desc =~ s/^\s+//s;
- # strip trailing spaces on every line
- $desc =~ s/\s+$/\n/mg;
-
- return $desc;
-}
-
-
-#############################################################################
-# Function : OutputDB
-# Description : This collects the output for each section of the docs, and
-# outputs each file when the end of the section is found.
-# Arguments : $file - the $MODULE-sections.txt file which contains all of
-# the functions/macros/structs etc. being documented, organised
-# into sections and subsections.
-#############################################################################
-
-sub OutputDB {
- my ($file) = @_;
-
- @TRACE@("Reading: $file\n");
- open (INPUT, $file)
- || die "Can't open $file: $!";
- my $filename = "";
- my $book_top = "";
- my $book_bottom = "";
- my $includes = (defined $DEFAULT_INCLUDES) ? $DEFAULT_INCLUDES : "";
- my $section_includes = "";
- my $in_section = 0;
- my $title = "";
- my $section_id = "";
- my $subsection = "";
- my $num_symbols;
- my $changed = 0;
- my $functions_synop = "";
- my $other_synop = "";
- my $functions_details = "";
- my $other_details = "";
- my $signals_synop = "";
- my $signals_desc = "";
- my $args_synop = "";
- my $child_args_synop = "";
- my $style_args_synop = "";
- my $args_desc = "";
- my $child_args_desc = "";
- my $style_args_desc = "";
- my $hierarchy_str = "";
- my @hierarchy = ();
- my $interfaces = "";
- my $implementations = "";
- my $prerequisites = "";
- my $derived = "";
- my @file_objects = ();
- my %templates = ();
- my %symbol_def_line = ();
-
- # merge the source docs, in case there are no templates
- &MergeSourceDocumentation;
-
- while (<INPUT>) {
- if (m/^#/) {
- next;
-
- } elsif (m/^<SECTION>/) {
- $num_symbols = 0;
- $in_section = 1;
- @file_objects = ();
- %symbol_def_line = ();
-
- } elsif (m/^<SUBSECTION\s*(.*)>/i) {
- $other_synop .= "\n";
- $functions_synop .= "\n";
- $subsection = $1;
-
- } elsif (m/^<SUBSECTION>/) {
-
- } elsif (m/^<TITLE>(.*)<\/TITLE>/) {
- $title = $1;
- @TRACE@("Section: $title\n");
-
- # We don't want warnings if object & class structs aren't used.
- $DeclarationOutput{$title} = 1;
- $DeclarationOutput{"${title}Class"} = 1;
- $DeclarationOutput{"${title}Iface"} = 1;
- $DeclarationOutput{"${title}Interface"} = 1;
-
- } elsif (m/^<FILE>(.*)<\/FILE>/) {
- $filename = $1;
- if (! defined $templates{$filename}) {
- if (&ReadTemplateFile ("$TMPL_DIR/$filename", 1)) {
- &MergeSourceDocumentation;
- $templates{$filename}=$.;
- }
- } else {
- &LogWarning ($file, $., "Double <FILE>$filename</FILE> entry. ".
- "Previous occurrence on line ".$templates{$filename}.".");
- }
- if (($title eq "") and (defined $SourceSymbolDocs{"$TMPL_DIR/$filename:Title"})) {
- $title = $SourceSymbolDocs{"$TMPL_DIR/$filename:Title"};
- # Remove trailing blanks
- $title =~ s/\s+$//;
- }
-
- } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
- if ($in_section) {
- $section_includes = $1;
- } else {
- if (defined $DEFAULT_INCLUDES) {
- &LogWarning ($file, $., "Default <INCLUDE> being overridden by command line option.");
- }
- else {
- $includes = $1;
- }
- }
-
- } elsif (m/^<\/SECTION>/) {
- @TRACE@("End of section: $title\n");
- if ($num_symbols > 0) {
- # collect documents
- $book_bottom .= " <xi:include href=\"xml/$filename.xml\"/>\n";
-
- if (defined ($SourceSymbolDocs{"$TMPL_DIR/$filename:Include"})) {
- if ($section_includes) {
- &LogWarning ($file, $., "Section <INCLUDE> being overridden by inline comments.");
- }
- $section_includes = $SourceSymbolDocs{"$TMPL_DIR/$filename:Include"};
- }
- if ($section_includes eq "") {
- $section_includes = $includes;
- }
-
- $signals_synop =~ s/^\n*//g;
- $signals_synop =~ s/\n+$/\n/g;
- if ($signals_synop ne '') {
- $signals_synop = <<EOF;
-<refsect1 id="$section_id.signals" role="signal_proto">
-<title role="signal_proto.title">Signals</title>
-<informaltable frame="none">
-<tgroup cols="3">
-<colspec colname="signals_return" colwidth="150px"/>
-<colspec colname="signals_name" colwidth="300px"/>
-<colspec colname="signals_flags" colwidth="200px"/>
-<tbody>
-${signals_synop}
-</tbody>
-</tgroup>
-</informaltable>
-</refsect1>
-EOF
- $signals_desc = TrimTextBlock($signals_desc);
- $signals_desc = <<EOF;
-<refsect1 id="$section_id.signal-details" role="signals">
-<title role="signals.title">Signal Details</title>
-$signals_desc
-</refsect1>
-EOF
- }
-
- $args_synop =~ s/^\n*//g;
- $args_synop =~ s/\n+$/\n/g;
- if ($args_synop ne '') {
- $args_synop = <<EOF;
-<refsect1 id="$section_id.properties" role="properties">
-<title role="properties.title">Properties</title>
-<informaltable frame="none">
-<tgroup cols="3">
-<colspec colname="properties_type" colwidth="150px"/>
-<colspec colname="properties_name" colwidth="300px"/>
-<colspec colname="properties_flags" colwidth="200px"/>
-<tbody>
-${args_synop}
-</tbody>
-</tgroup>
-</informaltable>
-</refsect1>
-EOF
- $args_desc = TrimTextBlock($args_desc);
- $args_desc = <<EOF;
-<refsect1 id="$section_id.property-details" role="property_details">
-<title role="property_details.title">Property Details</title>
-$args_desc
-</refsect1>
-EOF
- }
-
- $child_args_synop =~ s/^\n*//g;
- $child_args_synop =~ s/\n+$/\n/g;
- if ($child_args_synop ne '') {
- $args_synop .= <<EOF;
-<refsect1 id="$section_id.child-properties" role="child_properties">
-<title role="child_properties.title">Child Properties</title>
-<informaltable frame="none">
-<tgroup cols="3">
-<colspec colname="child_properties_type" colwidth="150px"/>
-<colspec colname="child_properties_name" colwidth="300px"/>
-<colspec colname="child_properties_flags" colwidth="200px"/>
-<tbody>
-${child_args_synop}
-</tbody>
-</tgroup>
-</informaltable>
-</refsect1>
-EOF
- $child_args_desc = TrimTextBlock($child_args_desc);
- $args_desc .= <<EOF;
-<refsect1 id="$section_id.child-property-details" role="child_property_details">
-<title role="child_property_details.title">Child Property Details</title>
-$child_args_desc
-</refsect1>
-EOF
- }
-
- $style_args_synop =~ s/^\n*//g;
- $style_args_synop =~ s/\n+$/\n/g;
- if ($style_args_synop ne '') {
- $args_synop .= <<EOF;
-<refsect1 id="$section_id.style-properties" role="style_properties">
-<title role="style_properties.title">Style Properties</title>
-<informaltable frame="none">
-<tgroup cols="3">
-<colspec colname="style_properties_type" colwidth="150px"/>
-<colspec colname="style_properties_name" colwidth="300px"/>
-<colspec colname="style_properties_flags" colwidth="200px"/>
-<tbody>
-${style_args_synop}
-</tbody>
-</tgroup>
-</informaltable>
-</refsect1>
-EOF
- $style_args_desc = TrimTextBlock($style_args_desc);
- $args_desc .= <<EOF;
-<refsect1 id="$section_id.style-property-details" role="style_properties_details">
-<title role="style_properties_details.title">Style Property Details</title>
-$style_args_desc
-</refsect1>
-EOF
- }
-
- $hierarchy_str = &AddTreeLineArt(\@hierarchy);
- if ($hierarchy_str ne "") {
- $hierarchy_str = <<EOF;
-<refsect1 id="$section_id.object-hierarchy" role="object_hierarchy">
-<title role="object_hierarchy.title">Object Hierarchy</title>
-<screen>$hierarchy_str
-</screen>
-</refsect1>
-EOF
- }
-
- $interfaces =~ TrimTextBlock($interfaces);
- if ($interfaces ne "") {
- $interfaces = <<EOF;
-<refsect1 id="$section_id.implemented-interfaces" role="impl_interfaces">
-<title role="impl_interfaces.title">Implemented Interfaces</title>
-$interfaces
-</refsect1>
-EOF
- }
-
- $implementations = TrimTextBlock($implementations);
- if ($implementations ne "") {
- $implementations = <<EOF;
-<refsect1 id="$section_id.implementations" role="implementations">
-<title role="implementations.title">Known Implementations</title>
-$implementations
-</refsect1>
-EOF
- }
-
- $prerequisites = TrimTextBlock($prerequisites);
- if ($prerequisites ne "") {
- $prerequisites = <<EOF;
-<refsect1 id="$section_id.prerequisites" role="prerequisites">
-<title role="prerequisites.title">Prerequisites</title>
-$prerequisites
-</refsect1>
-EOF
- }
-
- $derived = TrimTextBlock($derived);
- if ($derived ne "") {
- $derived = <<EOF;
-<refsect1 id="$section_id.derived-interfaces" role="derived_interfaces">
-<title role="derived_interfaces.title">Known Derived Interfaces</title>
-$derived
-</refsect1>
-EOF
- }
-
- $functions_synop =~ s/^\n*//g;
- $functions_synop =~ s/\n+$/\n/g;
- if ($functions_synop ne '') {
- $functions_synop = <<EOF;
-<refsect1 id="$section_id.functions" role="functions_proto">
-<title role="functions_proto.title">Functions</title>
-<informaltable pgwide="1" frame="none">
-<tgroup cols="2">
-<colspec colname="functions_return" colwidth="150px"/>
-<colspec colname="functions_name"/>
-<tbody>
-${functions_synop}
-</tbody>
-</tgroup>
-</informaltable>
-</refsect1>
-EOF
- }
-
- $other_synop =~ s/^\n*//g;
- $other_synop =~ s/\n+$/\n/g;
- if ($other_synop ne '') {
- $other_synop = <<EOF;
-<refsect1 id="$section_id.other" role="other_proto">
-<title role="other_proto.title">Types and Values</title>
-<informaltable role="enum_members_table" pgwide="1" frame="none">
-<tgroup cols="2">
-<colspec colname="name" colwidth="150px"/>
-<colspec colname="description"/>
-<tbody>
-${other_synop}
-</tbody>
-</tgroup>
-</informaltable>
-</refsect1>
-EOF
- }
-
- my $file_changed = &OutputDBFile ($filename, $title, $section_id,
- $section_includes,
- \$functions_synop, \$other_synop,
- \$functions_details, \$other_details,
- \$signals_synop, \$signals_desc,
- \$args_synop, \$args_desc,
- \$hierarchy_str, \$interfaces,
- \$implementations,
- \$prerequisites, \$derived,
- \@file_objects);
- if ($file_changed) {
- $changed = 1;
- }
- }
- $title = "";
- $section_id = "";
- $subsection = "";
- $in_section = 0;
- $section_includes = "";
- $functions_synop = "";
- $other_synop = "";
- $functions_details = "";
- $other_details = "";
- $signals_synop = "";
- $signals_desc = "";
- $args_synop = "";
- $child_args_synop = "";
- $style_args_synop = "";
- $args_desc = "";
- $child_args_desc = "";
- $style_args_desc = "";
- $hierarchy_str = "";
- @hierarchy = ();
- $interfaces = "";
- $implementations = "";
- $prerequisites = "";
- $derived = "";
-
- } elsif (m/^(\S+)/) {
- my $symbol = $1;
- @TRACE@(" Symbol: $symbol in subsection: $subsection\n");
-
- # check for duplicate entries
- if (! defined $symbol_def_line{$symbol}) {
- my $declaration = $Declarations{$symbol};
- if (defined ($declaration)) {
- if (&CheckIsObject ($symbol)) {
- push @file_objects, $symbol;
- }
- # We don't want standard macros/functions of GObjects,
- # or private declarations.
- if ($subsection ne "Standard" && $subsection ne "Private") {
- my ($synop, $desc) = &OutputDeclaration ($symbol,
- $declaration);
- my $type = $DeclarationTypes {$symbol};
-
- if ($type eq 'FUNCTION' || $type eq 'USER_FUNCTION') {
- $functions_synop .= $synop;
- $functions_details .= $desc;
- } elsif ($type eq 'MACRO' && $declaration =~ /$symbol\(/) {
- $functions_synop .= $synop;
- $functions_details .= $desc;
- } else {
- $other_synop .= $synop;
- $other_details .= $desc;
- }
- }
- my ($sig_synop, $sig_desc) = &GetSignals ($symbol);
- my ($arg_synop, $child_arg_synop, $style_arg_synop,
- $arg_desc, $child_arg_desc, $style_arg_desc) = &GetArgs ($symbol);
- my $ifaces = &GetInterfaces ($symbol);
- my $impls = &GetImplementations ($symbol);
- my $prereqs = &GetPrerequisites ($symbol);
- my $der = &GetDerived ($symbol);
- @hierarchy = &GetHierarchy ($symbol, \@hierarchy);
-
- $signals_synop .= $sig_synop;
- $signals_desc .= $sig_desc;
- $args_synop .= $arg_synop;
- $child_args_synop .= $child_arg_synop;
- $style_args_synop .= $style_arg_synop;
- $args_desc .= $arg_desc;
- $child_args_desc .= $child_arg_desc;
- $style_args_desc .= $style_arg_desc;
- $interfaces .= $ifaces;
- $implementations .= $impls;
- $prerequisites .= $prereqs;
- $derived .= $der;
-
- # Note that the declaration has been output.
- $DeclarationOutput{$symbol} = 1;
- } elsif ($subsection ne "Standard" && $subsection ne "Private") {
- $UndeclaredSymbols{$symbol} = 1;
- &LogWarning ($file, $., "No declaration found for $symbol.");
- }
- $num_symbols++;
- $symbol_def_line{$symbol}=$.;
-
- if ($section_id eq "") {
- if($title eq "" && $filename eq "") {
- &LogWarning ($file, $., "Section has no title and no file.");
- }
- # FIXME: one of those would be enough
- # filename should be an internal detail for gtk-doc
- if ($title eq "") {
- $title = $filename;
- } elsif ($filename eq "") {
- $filename = $title;
- }
- $filename =~ s/\s/_/g;
-
- $section_id = $SourceSymbolDocs{"$TMPL_DIR/$filename:Section_Id"};
- if (defined ($section_id) && $section_id !~ m/^\s*$/) {
- # Remove trailing blanks and use as is
- $section_id =~ s/\s+$//;
- } elsif (&CheckIsObject ($title)) {
- # GObjects use their class name as the ID.
- $section_id = &CreateValidSGMLID ($title);
- } else {
- $section_id = &CreateValidSGMLID ("$MODULE-$title");
- }
- }
- $SymbolSection{$symbol}=$title;
- $SymbolSectionId{$symbol}=$section_id;
- }
- else {
- &LogWarning ($file, $., "Double symbol entry for $symbol. ".
- "Previous occurrence on line ".$symbol_def_line{$symbol}.".");
- }
- }
- }
- close (INPUT);
-
- &OutputMissingDocumentation;
- &OutputUndeclaredSymbols;
- &OutputUnusedSymbols;
-
- if ($OUTPUT_ALL_SYMBOLS) {
- &OutputAllSymbols;
- }
- if ($OUTPUT_SYMBOLS_WITHOUT_SINCE) {
- &OutputSymbolsWithoutSince;
- }
-
- for $filename (split (' ', $EXPAND_CONTENT_FILES)) {
- my $file_changed = &OutputExtraFile ($filename);
- if ($file_changed) {
- $changed = 1;
- }
- }
-
- &OutputBook ($book_top, $book_bottom);
-
- return $changed;
-}
-
-#############################################################################
-# Function : OutputIndex
-# Description : This writes an indexlist that can be included into the main-
-# document into an <index> tag.
-#############################################################################
-
-sub OutputIndex {
- my ($basename, $apiindexref ) = @_;
- my %apiindex = %{$apiindexref};
- my $old_index = "$DB_OUTPUT_DIR/$basename.xml";
- my $new_index = "$DB_OUTPUT_DIR/$basename.new";
- my $lastletter = " ";
- my $divopen = 0;
- my $symbol;
- my $short_symbol;
-
- open (OUTPUT, ">$new_index")
- || die "Can't create $new_index";
-
- print (OUTPUT &MakeDocHeader ("indexdiv")."\n<indexdiv id=\"$basename\">\n");
-
- @TRACE@("generate $basename index (".%apiindex." entries)\n");
-
- # do a case insensitive sort while chopping off the prefix
- foreach my $hash (
- sort { $$a{criteria} cmp $$b{criteria} or $$a{original} cmp $$b{original} }
- map { my $x = uc($_); $x =~ s/^$NAME_SPACE\_?(.*)/$1/i; { criteria => $x, original => $_, short => $1 } }
- keys %apiindex) {
-
- $symbol = $$hash{original};
- if (defined($$hash{short})) {
- $short_symbol = $$hash{short};
- } else {
- $short_symbol = $symbol;
- }
-
- # generate a short symbol description
- my $symbol_desc = "";
- my $symbol_section = "";
- my $symbol_section_id = "";
- my $symbol_type = "";
- if (defined($DeclarationTypes{$symbol})) {
- $symbol_type = lc($DeclarationTypes{$symbol});
- }
- if ($symbol_type eq "") {
- @TRACE@("trying symbol $symbol\n");
- if ($symbol =~ m/(.*)::(.*)/) {
- my $oname = $1;
- my $osym = $2;
- my $i;
- @TRACE@(" trying object signal ${oname}:$osym in ".$#SignalNames." signals\n");
- for ($i = 0; $i <= $#SignalNames; $i++) {
- if ($SignalNames[$i] eq $osym) {
- $symbol_type = "object signal";
- if (defined($SymbolSection{$oname})) {
- $symbol_section = $SymbolSection{$oname};
- $symbol_section_id = $SymbolSectionId{$oname};
- }
- last;
- }
- }
- } elsif ($symbol =~ m/(.*):(.*)/) {
- my $oname = $1;
- my $osym = $2;
- my $i;
- @TRACE@(" trying object property ${oname}::$osym in ".$#ArgNames." properties\n");
- for ($i = 0; $i <= $#ArgNames; $i++) {
- @TRACE@(" ".$ArgNames[$i]."\n");
- if ($ArgNames[$i] eq $osym) {
- $symbol_type = "object property";
- if (defined($SymbolSection{$oname})) {
- $symbol_section = $SymbolSection{$oname};
- $symbol_section_id = $SymbolSectionId{$oname};
- }
- last;
- }
- }
- }
- } else {
- if (defined($SymbolSection{$symbol})) {
- $symbol_section = $SymbolSection{$symbol};
- $symbol_section_id = $SymbolSectionId{$symbol};
- }
- }
- if ($symbol_type ne "") {
- $symbol_desc=", $symbol_type";
- if ($symbol_section ne "") {
- $symbol_desc.=" in <link linkend=\"$symbol_section_id\">$symbol_section</link>";
- #$symbol_desc.=" in ". &ExpandAbbreviations($symbol, "#$symbol_section");
- }
- }
-
- my $curletter = uc(substr($short_symbol,0,1));
- my $id = $apiindex{$symbol};
-
- @TRACE@(" add symbol $symbol with $id to index in section $curletter\n");
-
- if ($curletter ne $lastletter) {
- $lastletter = $curletter;
-
- if ($divopen == 1) {
- print (OUTPUT "</indexdiv>\n");
- }
- print (OUTPUT "<indexdiv><title>$curletter</title>\n");
- $divopen = 1;
- }
-
- print (OUTPUT <<EOF);
-<indexentry><primaryie linkends="$id"><link linkend="$id">$symbol</link>$symbol_desc</primaryie></indexentry>
-EOF
- }
-
- if ($divopen == 1) {
- print (OUTPUT "</indexdiv>\n");
- }
- print (OUTPUT "</indexdiv>\n");
- close (OUTPUT);
-
- &UpdateFileIfChanged ($old_index, $new_index, 0);
-}
-
-
-#############################################################################
-# Function : OutputIndexFull
-# Description : This writes the full api indexlist that can be included into the
-# main document into an <index> tag.
-#############################################################################
-
-sub OutputIndexFull {
- &OutputIndex ("api-index-full", \%IndexEntriesFull);
-}
-
-
-#############################################################################
-# Function : OutputDeprecatedIndex
-# Description : This writes the deprecated api indexlist that can be included
-# into the main document into an <index> tag.
-#############################################################################
-
-sub OutputDeprecatedIndex {
- &OutputIndex ("api-index-deprecated", \%IndexEntriesDeprecated);
-}
-
-
-#############################################################################
-# Function : OutputSinceIndexes
-# Description : This writes the 'since' api indexlists that can be included into
-# the main document into an <index> tag.
-#############################################################################
-
-sub OutputSinceIndexes {
- my @sinces = keys %{{ map { $_ => 1 } values %Since }};
-
- foreach my $version (@sinces) {
- @TRACE@("Since : [$version]\n");
- # TODO make filtered hash
- #my %index = grep { $Since{$_} eq $version } %IndexEntriesSince;
- my %index = map { $_ => $IndexEntriesSince{$_} } grep { $Since{$_} eq $version } keys %IndexEntriesSince;
-
- &OutputIndex ("api-index-$version", \%index);
- }
-}
-
-#############################################################################
-# Function : OutputAnnotationGlossary
-# Description : This writes a glossary of the used annotation terms into a
-# separate glossary file that can be included into the main
-# document.
-#############################################################################
-
-sub OutputAnnotationGlossary {
- my $old_glossary = "$DB_OUTPUT_DIR/annotation-glossary.xml";
- my $new_glossary = "$DB_OUTPUT_DIR/annotation-glossary.new";
- my $lastletter = " ";
- my $divopen = 0;
-
- # if there are no annotations used return
- return if (! keys(%AnnotationsUsed));
-
- # add acronyms that are referenced from acronym text
-rerun:
- foreach my $annotation (keys(%AnnotationsUsed)) {
- if(defined($AnnotationDefinition{$annotation})) {
- if($AnnotationDefinition{$annotation} =~ m/<acronym>([\w ]+)<\/acronym>/) {
- if (!exists($AnnotationsUsed{$1})) {
- $AnnotationsUsed{$1} = 1;
- goto rerun;
- }
- }
- }
- }
-
- open (OUTPUT, ">$new_glossary")
- || die "Can't create $new_glossary";
-
- print (OUTPUT <<EOF);
-${\( MakeDocHeader ("glossary") )}
-<glossary id="annotation-glossary">
- <title>Annotation Glossary</title>
-EOF
-
- foreach my $annotation (sort({lc $a cmp lc $b} keys(%AnnotationsUsed))) {
- if(defined($AnnotationDefinition{$annotation})) {
- my $def = $AnnotationDefinition{$annotation};
- my $curletter = uc(substr($annotation,0,1));
-
- if ($curletter ne $lastletter) {
- $lastletter = $curletter;
-
- if ($divopen == 1) {
- print (OUTPUT "</glossdiv>\n");
- }
- print (OUTPUT "<glossdiv><title>$curletter</title>\n");
- $divopen = 1;
- }
- print (OUTPUT <<EOF);
- <glossentry>
- <glossterm><anchor id="annotation-glossterm-$annotation"/>$annotation</glossterm>
- <glossdef>
- <para>$def</para>
- </glossdef>
- </glossentry>
-EOF
- }
- }
-
- if ($divopen == 1) {
- print (OUTPUT "</glossdiv>\n");
- }
- print (OUTPUT "</glossary>\n");
- close (OUTPUT);
-
- &UpdateFileIfChanged ($old_glossary, $new_glossary, 0);
-}
-
-#############################################################################
-# Function : ReadKnownSymbols
-# Description : This collects the names of non-private symbols from the
-# $MODULE-sections.txt file.
-# Arguments : $file - the $MODULE-sections.txt file which contains all of
-# the functions/macros/structs etc. being documented, organised
-# into sections and subsections.
-#############################################################################
-
-sub ReadKnownSymbols {
- my ($file) = @_;
-
- my $subsection = "";
-
- @TRACE@("Reading: $file\n");
- open (INPUT, $file)
- || die "Can't open $file: $!";
-
- while (<INPUT>) {
- if (m/^#/) {
- next;
-
- } elsif (m/^<SECTION>/) {
- $subsection = "";
-
- } elsif (m/^<SUBSECTION\s*(.*)>/i) {
- $subsection = $1;
-
- } elsif (m/^<SUBSECTION>/) {
- next;
-
- } elsif (m/^<TITLE>(.*)<\/TITLE>/) {
- next;
-
- } elsif (m/^<FILE>(.*)<\/FILE>/) {
- $KnownSymbols{"$TMPL_DIR/$1:Long_Description"} = 1;
- $KnownSymbols{"$TMPL_DIR/$1:Short_Description"} = 1;
- next;
-
- } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
- next;
-
- } elsif (m/^<\/SECTION>/) {
- next;
-
- } elsif (m/^(\S+)/) {
- my $symbol = $1;
-
- if ($subsection ne "Standard" && $subsection ne "Private") {
- $KnownSymbols{$symbol} = 1;
- }
- else {
- $KnownSymbols{$symbol} = 0;
- }
- }
- }
- close (INPUT);
-}
-
-
-#############################################################################
-# Function : OutputDeclaration
-# Description : Returns the synopsis and detailed description DocBook
-# describing one function/macro etc.
-# Arguments : $symbol - the name of the function/macro begin described.
-# $declaration - the declaration of the function/macro.
-#############################################################################
-
-sub OutputDeclaration {
- my ($symbol, $declaration) = @_;
-
- my $type = $DeclarationTypes {$symbol};
- if ($type eq 'MACRO') {
- return &OutputMacro ($symbol, $declaration);
- } elsif ($type eq 'TYPEDEF') {
- return &OutputTypedef ($symbol, $declaration);
- } elsif ($type eq 'STRUCT') {
- return &OutputStruct ($symbol, $declaration);
- } elsif ($type eq 'ENUM') {
- return &OutputEnum ($symbol, $declaration);
- } elsif ($type eq 'UNION') {
- return &OutputUnion ($symbol, $declaration);
- } elsif ($type eq 'VARIABLE') {
- return &OutputVariable ($symbol, $declaration);
- } elsif ($type eq 'FUNCTION') {
- return &OutputFunction ($symbol, $declaration, $type);
- } elsif ($type eq 'USER_FUNCTION') {
- return &OutputFunction ($symbol, $declaration, $type);
- } else {
- die "Unknown symbol type";
- }
-}
-
-
-#############################################################################
-# Function : OutputSymbolTraits
-# Description : Returns the Since and StabilityLevel paragraphs for a symbol.
-# Arguments : $symbol - the name of the function/macro begin described.
-#############################################################################
-
-sub OutputSymbolTraits {
- my ($symbol) = @_;
- my $desc = "";
-
- if (exists $Since{$symbol}) {
- my $link_id = "api-index-".$Since{$symbol};
- $desc .= "<para role=\"since\">Since: <link linkend=\"$link_id\">$Since{$symbol}</link></para>";
- }
- if (exists $StabilityLevel{$symbol}) {
- my $stability = $StabilityLevel{$symbol};
- $AnnotationsUsed{$stability} = 1;
- $desc .= "<para role=\"stability\">Stability Level: <acronym>$stability</acronym></para>";
- }
- return $desc;
-}
-
-#############################################################################
-# Function : Output{Symbol,Section}ExtraLinks
-# Description : Returns extralinks for the symbol (if enabled).
-# Arguments : $symbol - the name of the function/macro begin described.
-#############################################################################
-
-sub uri_escape {
- my $text = $_[0];
- return undef unless defined $text;
-
- # Build a char to hex map
- my %escapes = ();
- for (0..255) {
- $escapes{chr($_)} = sprintf("%%%02X", $_);
- }
-
- # Default unsafe characters. RFC 2732 ^(uric - reserved)
- $text =~ s/([^A-Za-z0-9\-_.!~*'()])/$escapes{$1}/g;
-
- return $text;
-}
-
-sub OutputSymbolExtraLinks {
- my ($symbol) = @_;
- my $desc = "";
-
- if (0) { # NEW FEATURE: needs configurability
- my $sstr = &uri_escape($symbol);
- my $mstr = &uri_escape($MODULE);
- $desc .= <<EOF;
-<ulink role="extralinks" url="http://www.google.com/codesearch?q=$sstr">code search</ulink>
-<ulink role="extralinks" url="http://library.gnome.org/edit?module=$mstr&symbol=$sstr">edit documentation</ulink>
-EOF
- }
- return $desc;
-}
-
-sub OutputSectionExtraLinks {
- my ($symbol,$docsymbol) = @_;
- my $desc = "";
-
- if (0) { # NEW FEATURE: needs configurability
- my $sstr = &uri_escape($symbol);
- my $mstr = &uri_escape($MODULE);
- my $dsstr = &uri_escape($docsymbol);
- $desc .= <<EOF;
-<ulink role="extralinks" url="http://www.google.com/codesearch?q=$sstr">code search</ulink>
-<ulink role="extralinks" url="http://library.gnome.org/edit?module=$mstr&symbol=$dsstr">edit documentation</ulink>
-EOF
- }
- return $desc;
-}
-
-
-#############################################################################
-# Function : OutputMacro
-# Description : Returns the synopsis and detailed description of a macro.
-# Arguments : $symbol - the macro.
-# $declaration - the declaration of the macro.
-#############################################################################
-
-sub OutputMacro {
- my ($symbol, $declaration) = @_;
- my $id = &CreateValidSGMLID ($symbol);
- my $condition = &MakeConditionDescription ($symbol);
- my $synop = "<row><entry role=\"define_keyword\">#define</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link>";
- my $desc;
-
- my @fields = ParseMacroDeclaration($declaration, \&CreateValidSGML);
- my $title = $symbol . (@fields ? "()" : "");
-
- $desc = "<refsect2 id=\"$id\" role=\"macro\"$condition>\n<title>$title</title>\n";
- $desc .= MakeIndexterms($symbol, $id);
- $desc .= "\n";
- $desc .= OutputSymbolExtraLinks($symbol);
-
- if (@fields) {
- $synop .= "<phrase role=\"c_punctuation\">()</phrase>";
- }
- $synop .= "</entry></row>\n";
-
- # Don't output the macro definition if is is a conditional macro or it
- # looks like a function, i.e. starts with "g_" or "_?gnome_", or it is
- # longer than 2 lines, otherwise we get lots of complicated macros like
- # g_assert.
- if (!defined ($DeclarationConditional{$symbol}) && ($symbol !~ m/^g_/)
- && ($symbol !~ m/^_?gnome_/) && (($declaration =~ tr/\n//) < 2)) {
- my $decl_out = &CreateValidSGML ($declaration);
- $desc .= "<programlisting language=\"C\">$decl_out</programlisting>\n";
- } else {
- $desc .= "<programlisting language=\"C\">" . &MakeReturnField("#define") . "$symbol";
- if ($declaration =~ m/^\s*#\s*define\s+\w+(\([^\)]*\))/) {
- my $args = $1;
- my $pad = ' ' x ($RETURN_TYPE_FIELD_WIDTH - length ("#define "));
- # Align each line so that if should all line up OK.
- $args =~ s/\n/\n$pad/gm;
- $desc .= &CreateValidSGML ($args);
- }
- $desc .= "</programlisting>\n";
- }
-
- $desc .= &MakeDeprecationNote($symbol);
-
- my $parameters = &OutputParamDescriptions ("MACRO", $symbol, @fields);
-
- if (defined ($SymbolDocs{$symbol})) {
- my $symbol_docs = &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
- $desc .= $symbol_docs;
- }
-
- $desc .= $parameters;
- $desc .= OutputSymbolTraits ($symbol);
- $desc .= "</refsect2>\n";
- return ($synop, $desc);
-}
-
-
-#############################################################################
-# Function : OutputTypedef
-# Description : Returns the synopsis and detailed description of a typedef.
-# Arguments : $symbol - the typedef.
-# $declaration - the declaration of the typedef,
-# e.g. 'typedef unsigned int guint;'
-#############################################################################
-
-sub OutputTypedef {
- my ($symbol, $declaration) = @_;
- my $id = &CreateValidSGMLID ($symbol);
- my $condition = &MakeConditionDescription ($symbol);
- my $desc = "<refsect2 id=\"$id\" role=\"typedef\"$condition>\n<title>$symbol</title>\n";
- my $synop = "<row><entry role=\"typedef_keyword\">typedef</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link></entry></row>\n";
-
- $desc .= MakeIndexterms($symbol, $id);
- $desc .= "\n";
- $desc .= OutputSymbolExtraLinks($symbol);
-
- if (!defined ($DeclarationConditional{$symbol})) {
- my $decl_out = &CreateValidSGML ($declaration);
- $desc .= "<programlisting language=\"C\">$decl_out</programlisting>\n";
- }
-
- $desc .= &MakeDeprecationNote($symbol);
-
- if (defined ($SymbolDocs{$symbol})) {
- $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
- }
- $desc .= OutputSymbolTraits ($symbol);
- $desc .= "</refsect2>\n";
- return ($synop, $desc);
-}
-
-
-#############################################################################
-# Function : OutputStruct
-# Description : Returns the synopsis and detailed description of a struct.
-# We check if it is a object struct, and if so we only output
-# parts of it that are noted as public fields.
-# We also use a different IDs for object structs, since the
-# original ID is used for the entire RefEntry.
-# Arguments : $symbol - the struct.
-# $declaration - the declaration of the struct.
-#############################################################################
-
-sub OutputStruct {
- my ($symbol, $declaration) = @_;
-
- my $is_gtype = 0;
- my $default_to_public = 1;
- if (&CheckIsObject ($symbol)) {
- @TRACE@("Found struct gtype: $symbol\n");
- $is_gtype = 1;
- $default_to_public = $ObjectRoots{$symbol} eq 'GBoxed';
- }
-
- my $id;
- my $condition;
- if ($is_gtype) {
- $id = &CreateValidSGMLID ($symbol . "_struct");
- $condition = &MakeConditionDescription ($symbol . "_struct");
- } else {
- $id = &CreateValidSGMLID ($symbol);
- $condition = &MakeConditionDescription ($symbol);
- }
-
- # Determine if it is a simple struct or it also has a typedef.
- my $has_typedef = 0;
- if ($StructHasTypedef{$symbol} || $declaration =~ m/^\s*typedef\s+/) {
- $has_typedef = 1;
- }
-
- my $type_output;
- my $desc;
- if ($has_typedef) {
- # For structs with typedefs we just output the struct name.
- $type_output = "";
- $desc = "<refsect2 id=\"$id\" role=\"struct\"$condition>\n<title>$symbol</title>\n";
- } else {
- $type_output = "struct";
- $desc = "<refsect2 id=\"$id\" role=\"struct\"$condition>\n<title>struct $symbol</title>\n";
- }
- my $synop = "<row><entry role=\"datatype_keyword\">${type_output}</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link></entry></row>\n";
-
- $desc .= MakeIndexterms($symbol, $id);
- $desc .= "\n";
- $desc .= OutputSymbolExtraLinks($symbol);
-
- # Form a pretty-printed, private-data-removed form of the declaration
-
- my $decl_out = "";
- if ($declaration =~ m/^\s*$/) {
- @TRACE@("Found opaque struct: $symbol\n");
- $decl_out = "typedef struct _$symbol $symbol;";
- } elsif ($declaration =~ m/^\s*struct\s+\w+\s*;\s*$/) {
- @TRACE@("Found opaque struct: $symbol\n");
- $decl_out = "struct $symbol;";
- } else {
- my $public = $default_to_public;
- my $new_declaration = "";
- my $decl_line;
- my $decl = $declaration;
-
- if ($decl =~ m/^\s*(typedef\s+)?struct\s*\w*\s*(?:\/\*.*\*\/)?\s*{(.*)}\s*\w*\s*;\s*$/s) {
- my $struct_contents = $2;
-
- foreach $decl_line (split (/\n/, $struct_contents)) {
- @TRACE@("Struct line: $decl_line\n");
- if ($decl_line =~ m%/\*\s*<\s*public\s*>\s*\*/%) {
- $public = 1;
- } elsif ($decl_line =~ m%/\*\s*<\s*(private|protected)\s*>\s*\*/%) {
- $public = 0;
- } elsif ($public) {
- $new_declaration .= $decl_line . "\n";
- }
- }
-
- if ($new_declaration) {
- # Strip any blank lines off the ends.
- $new_declaration =~ s/^\s*\n//;
- $new_declaration =~ s/\n\s*$/\n/;
-
- if ($has_typedef) {
- $decl_out = "typedef struct {\n" . $new_declaration
- . "} $symbol;\n";
- } else {
- $decl_out = "struct $symbol {\n" . $new_declaration
- . "};\n";
- }
- }
- } else {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Couldn't parse struct:\n$declaration");
- }
-
- # If we couldn't parse the struct or it was all private, output an
- # empty struct declaration.
- if ($decl_out eq "") {
- if ($has_typedef) {
- $decl_out = "typedef struct _$symbol $symbol;";
- } else {
- $decl_out = "struct $symbol;";
- }
- }
- }
-
- $decl_out = &CreateValidSGML ($decl_out);
- $desc .= "<programlisting language=\"C\">$decl_out</programlisting>\n";
-
- $desc .= &MakeDeprecationNote($symbol);
-
- if (defined ($SymbolDocs{$symbol})) {
- $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
- }
-
- # Create a table of fields and descriptions
-
- # FIXME: Inserting  's into the produced type declarations here would
- # improve the output in most situations ... except for function
- # members of structs!
- my @fields = ParseStructDeclaration($declaration, !$default_to_public,
- 0, \&MakeXRef,
- sub {
- "<structfield id=\"".&CreateValidSGMLID("$id.$_[0]")."\">$_[0]</structfield>";
- });
- my $params = $SymbolParams{$symbol};
-
- # If no parameters are filled in, we don't generate the description
- # table, for backwards compatibility.
-
- my $found = 0;
- if (defined $params) {
- for (my $i = 1; $i <= $#$params; $i += $PARAM_FIELD_COUNT) {
- if ($params->[$i] =~ /\S/) {
- $found = 1;
- last;
- }
- }
- }
-
- if ($found) {
- my %field_descrs = @$params;
- my $missing_parameters = "";
- my $unused_parameters = "";
- my $id = &CreateValidSGMLID ("$symbol".".members");
-
- $desc .= <<EOF;
-<refsect3 id="$id" role="struct_members">\n<title>Members</title>
-<informaltable role="struct_members_table" pgwide="1" frame="none">
-<tgroup cols="3">
-<colspec colname="struct_members_name" colwidth="300px"/>
-<colspec colname="struct_members_description"/>
-<colspec colname="struct_members_annotations" colwidth="200px"/>
-<tbody>
-EOF
-
- while (@fields) {
- my $field_name = shift @fields;
- my $text = shift @fields;
- my $field_descr = $field_descrs{$field_name};
- my $param_annotations = "";
-
- $desc .= "<row role=\"member\"><entry role=\"struct_member_name\"><para>$text</para></entry>\n";
- if (defined $field_descr) {
- ($field_descr,$param_annotations) = &ExpandAnnotation($symbol, $field_descr);
- $field_descr = &ConvertMarkDown($symbol, $field_descr);
- # trim
- $field_descr =~ s/^(\s|\n)+//msg;
- $field_descr =~ s/(\s|\n)+$//msg;
- $desc .= "<entry role=\"struct_member_description\">$field_descr</entry>\n<entry role=\"struct_member_annotations\">$param_annotations</entry>\n";
- delete $field_descrs{$field_name};
- } else {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Field description for $symbol"."::"."$field_name is missing in source code comment block.");
- if ($missing_parameters ne "") {
- $missing_parameters .= ", ".$field_name;
- } else {
- $missing_parameters = $field_name;
- }
- $desc .= "<entry /><entry />\n";
- }
- $desc .= "</row>\n";
- }
- $desc .= "</tbody></tgroup></informaltable>\n</refsect3>\n";
- foreach my $field_name (keys %field_descrs) {
- # Documenting those standard fields is not required anymore, but
- # we don't want to warn if they are documented anyway.
- if ($field_name =~ /(g_iface|parent_instance|parent_class)/) {
- next;
- }
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Field description for $symbol"."::"."$field_name is not used from source code comment block.");
- if ($unused_parameters ne "") {
- $unused_parameters .= ", ".$field_name;
- } else {
- $unused_parameters = $field_name;
- }
- }
-
- # remember missing/unused parameters (needed in tmpl-free build)
- if (($missing_parameters ne "") and (! exists ($AllIncompleteSymbols{$symbol}))) {
- $AllIncompleteSymbols{$symbol}=$missing_parameters;
- }
- if (($unused_parameters ne "") and (! exists ($AllUnusedSymbols{$symbol}))) {
- $AllUnusedSymbols{$symbol}=$unused_parameters;
- }
- }
- else {
- if (scalar(@fields) > 0) {
- if (! exists ($AllIncompleteSymbols{$symbol})) {
- $AllIncompleteSymbols{$symbol}="<items>";
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Field descriptions for struct $symbol are missing in source code comment block.");
- @TRACE@("Remaining structs fields: ".@fields.":".join(',',@fields)."\n");
- }
- }
- }
-
- $desc .= OutputSymbolTraits ($symbol);
- $desc .= "</refsect2>\n";
- return ($synop, $desc);
-}
-
-
-#############################################################################
-# Function : OutputUnion
-# Description : Returns the synopsis and detailed description of a union.
-# Arguments : $symbol - the union.
-# $declaration - the declaration of the union.
-#############################################################################
-
-sub OutputUnion {
- my ($symbol, $declaration) = @_;
-
- my $is_gtype = 0;
- if (&CheckIsObject ($symbol)) {
- @TRACE@("Found union gtype: $symbol\n");
- $is_gtype = 1;
- }
-
- my $id;
- my $condition;
- if ($is_gtype) {
- $id = &CreateValidSGMLID ($symbol . "_union");
- $condition = &MakeConditionDescription ($symbol . "_union");
- } else {
- $id = &CreateValidSGMLID ($symbol);
- $condition = &MakeConditionDescription ($symbol);
- }
-
- # Determine if it is a simple struct or it also has a typedef.
- my $has_typedef = 0;
- if ($StructHasTypedef{$symbol} || $declaration =~ m/^\s*typedef\s+/) {
- $has_typedef = 1;
- }
-
- my $type_output;
- my $desc;
- if ($has_typedef) {
- # For unions with typedefs we just output the union name.
- $type_output = "";
- $desc = "<refsect2 id=\"$id\" role=\"union\"$condition>\n<title>$symbol</title>\n";
- } else {
- $type_output = "union";
- $desc = "<refsect2 id=\"$id\" role=\"union\"$condition>\n<title>union $symbol</title>\n";
- }
- my $synop = "<row><entry role=\"datatype_keyword\">${type_output}</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link></entry></row>\n";
-
- $desc .= MakeIndexterms($symbol, $id);
- $desc .= "\n";
- $desc .= OutputSymbolExtraLinks($symbol);
- $desc .= &MakeDeprecationNote($symbol);
-
- if (defined ($SymbolDocs{$symbol})) {
- $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
- }
-
- # Create a table of fields and descriptions
-
- # FIXME: Inserting  's into the produced type declarations here would
- # improve the output in most situations ... except for function
- # members of structs!
- my @fields = ParseStructDeclaration($declaration, 0,
- 0, \&MakeXRef,
- sub {
- "<structfield id=\"".&CreateValidSGMLID("$id.$_[0]")."\">$_[0]</structfield>";
- });
- my $params = $SymbolParams{$symbol};
-
- # If no parameters are filled in, we don't generate the description
- # table, for backwards compatibility
-
- my $found = 0;
- if (defined $params) {
- for (my $i = 1; $i <= $#$params; $i += $PARAM_FIELD_COUNT) {
- if ($params->[$i] =~ /\S/) {
- $found = 1;
- last;
- }
- }
- }
-
- if ($found) {
- my %field_descrs = @$params;
- my $missing_parameters = "";
- my $unused_parameters = "";
- my $id = &CreateValidSGMLID ("$symbol".".members");
-
- $desc .= <<EOF;
-<refsect3 id="$id" role="union_members">\n<title>Members</title>
-<informaltable role="union_members_table" pgwide="1" frame="none">
-<tgroup cols="3">
-<colspec colname="union_members_name" colwidth="300px"/>
-<colspec colname="union_members_description"/>
-<colspec colname="union_members_annotations" colwidth="200px"/>
-<tbody>
-EOF
-
- while (@fields) {
- my $field_name = shift @fields;
- my $text = shift @fields;
- my $field_descr = $field_descrs{$field_name};
- my $param_annotations = "";
-
- $desc .= "<row><entry role=\"union_member_name\"><para>$text</para></entry>\n";
- if (defined $field_descr) {
- ($field_descr,$param_annotations) = &ExpandAnnotation($symbol, $field_descr);
- $field_descr = &ConvertMarkDown($symbol, $field_descr);
-
- # trim
- $field_descr =~ s/^(\s|\n)+//msg;
- $field_descr =~ s/(\s|\n)+$//msg;
- $desc .= "<entry role=\"union_member_description\">$field_descr</entry>\n<entry role=\"union_member_annotations\">$param_annotations</entry>\n";
- delete $field_descrs{$field_name};
- } else {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Field description for $symbol"."::"."$field_name is missing in source code comment block.");
- if ($missing_parameters ne "") {
- $missing_parameters .= ", ".$field_name;
- } else {
- $missing_parameters = $field_name;
- }
- $desc .= "<entry /><entry />\n";
- }
- $desc .= "</row>\n";
- }
- $desc .= "</tbody></tgroup></informaltable>\n</refsect3>";
- foreach my $field_name (keys %field_descrs) {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Field description for $symbol"."::"."$field_name is not used from source code comment block.");
- if ($unused_parameters ne "") {
- $unused_parameters .= ", ".$field_name;
- } else {
- $unused_parameters = $field_name;
- }
- }
-
- # remember missing/unused parameters (needed in tmpl-free build)
- if (($missing_parameters ne "") and (! exists ($AllIncompleteSymbols{$symbol}))) {
- $AllIncompleteSymbols{$symbol}=$missing_parameters;
- }
- if (($unused_parameters ne "") and (! exists ($AllUnusedSymbols{$symbol}))) {
- $AllUnusedSymbols{$symbol}=$unused_parameters;
- }
- }
- else {
- if (scalar(@fields) > 0) {
- if (! exists ($AllIncompleteSymbols{$symbol})) {
- $AllIncompleteSymbols{$symbol}="<items>";
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Field descriptions for union $symbol are missing in source code comment block.");
- @TRACE@("Remaining union fields: ".@fields.":".join(',',@fields)."\n");
- }
- }
- }
-
- $desc .= OutputSymbolTraits ($symbol);
- $desc .= "</refsect2>\n";
- return ($synop, $desc);
-}
-
-
-#############################################################################
-# Function : OutputEnum
-# Description : Returns the synopsis and detailed description of a enum.
-# Arguments : $symbol - the enum.
-# $declaration - the declaration of the enum.
-#############################################################################
-
-sub OutputEnum {
- my ($symbol, $declaration) = @_;
-
- my $is_gtype = 0;
- if (&CheckIsObject ($symbol)) {
- @TRACE@("Found enum gtype: $symbol\n");
- $is_gtype = 1;
- }
-
- my $id;
- my $condition;
- if ($is_gtype) {
- $id = &CreateValidSGMLID ($symbol . "_enum");
- $condition = &MakeConditionDescription ($symbol . "_enum");
- } else {
- $id = &CreateValidSGMLID ($symbol);
- $condition = &MakeConditionDescription ($symbol);
- }
-
- my $synop = "<row><entry role=\"datatype_keyword\">enum</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link></entry></row>\n";
- my $desc = "<refsect2 id=\"$id\" role=\"enum\"$condition>\n<title>enum $symbol</title>\n";
-
- $desc .= MakeIndexterms($symbol, $id);
- $desc .= "\n";
- $desc .= OutputSymbolExtraLinks($symbol);
- $desc .= &MakeDeprecationNote($symbol);
-
- if (defined ($SymbolDocs{$symbol})) {
- $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
- }
-
- # Create a table of fields and descriptions
-
- my @fields = ParseEnumDeclaration($declaration);
- my $params = $SymbolParams{$symbol};
-
- # If nothing at all is documented log a single summary warning at the end.
- # Otherwise, warn about each undocumented item.
-
- my $found = 0;
- if (defined $params) {
- for (my $i = 1; $i <= $#$params; $i += $PARAM_FIELD_COUNT) {
- if ($params->[$i] =~ /\S/) {
- $found = 1;
- last;
- }
- }
- }
-
- my %field_descrs = (defined $params ? @$params : ());
- my $missing_parameters = "";
- my $unused_parameters = "";
-
- $id = &CreateValidSGMLID ("$symbol".".members");
- $desc .= <<EOF;
-<refsect3 id="$id" role="enum_members">\n<title>Members</title>
-<informaltable role="enum_members_table" pgwide="1" frame="none">
-<tgroup cols="3">
-<colspec colname="enum_members_name" colwidth="300px"/>
-<colspec colname="enum_members_description"/>
-<colspec colname="enum_members_annotations" colwidth="200px"/>
-<tbody>
-EOF
-
- for my $field_name (@fields) {
- my $field_descr = $field_descrs{$field_name};
- my $param_annotations = "";
-
- $id = &CreateValidSGMLID ($field_name);
- $condition = &MakeConditionDescription ($field_name);
- $desc .= "<row role=\"constant\"><entry role=\"enum_member_name\"><para id=\"$id\">$field_name</para></entry>\n";
- if (defined $field_descr) {
- ($field_descr,$param_annotations) = &ExpandAnnotation($symbol, $field_descr);
- $field_descr = &ConvertMarkDown($symbol, $field_descr);
- $desc .= "<entry role=\"enum_member_description\">$field_descr</entry>\n<entry role=\"enum_member_annotations\">$param_annotations</entry>\n";
- delete $field_descrs{$field_name};
- } else {
- if ($found) {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Value description for $symbol"."::"."$field_name is missing in source code comment block.");
- if ($missing_parameters ne "") {
- $missing_parameters .= ", ".$field_name;
- } else {
- $missing_parameters = $field_name;
- }
- }
- $desc .= "<entry /><entry />\n";
- }
- $desc .= "</row>\n";
- }
- $desc .= "</tbody></tgroup></informaltable>\n</refsect3>";
- foreach my $field_name (keys %field_descrs) {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Value description for $symbol"."::"."$field_name is not used from source code comment block.");
- if ($unused_parameters ne "") {
- $unused_parameters .= ", ".$field_name;
- } else {
- $unused_parameters = $field_name;
- }
- }
-
- # remember missing/unused parameters (needed in tmpl-free build)
- if (($missing_parameters ne "") and (! exists ($AllIncompleteSymbols{$symbol}))) {
- $AllIncompleteSymbols{$symbol}=$missing_parameters;
- }
- if (($unused_parameters ne "") and (! exists ($AllUnusedSymbols{$symbol}))) {
- $AllUnusedSymbols{$symbol}=$unused_parameters;
- }
-
- if (!$found) {
- if (scalar(@fields) > 0) {
- if (! exists ($AllIncompleteSymbols{$symbol})) {
- $AllIncompleteSymbols{$symbol}="<items>";
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Value descriptions for $symbol are missing in source code comment block.");
- }
- }
- }
-
- $desc .= OutputSymbolTraits ($symbol);
- $desc .= "</refsect2>\n";
- return ($synop, $desc);
-}
-
-
-#############################################################################
-# Function : OutputVariable
-# Description : Returns the synopsis and detailed description of a variable.
-# Arguments : $symbol - the extern'ed variable.
-# $declaration - the declaration of the variable.
-#############################################################################
-
-sub OutputVariable {
- my ($symbol, $declaration) = @_;
- my $id = &CreateValidSGMLID ($symbol);
- my $condition = &MakeConditionDescription ($symbol);
-
- @TRACE@("ouputing variable: '$symbol' '$declaration'");
-
- my $type_output;
- if ($declaration =~ m/^\s*extern\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*;/) {
- my $mod1 = defined ($1) ? $1 : "";
- my $ptr = defined ($3) ? $3 : "";
- my $space = defined ($4) ? $4 : "";
- my $mod2 = defined ($5) ? $5 : "";
- $type_output = "extern $mod1$ptr$space$mod2";
- } elsif ($declaration =~ m/^\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*=/) {
- my $mod1 = defined ($1) ? $1 : "";
- my $ptr = defined ($3) ? $3 : "";
- my $space = defined ($4) ? $4 : "";
- my $mod2 = defined ($5) ? $5 : "";
- $type_output = "$mod1$ptr$space$mod2";
- } else {
- $type_output = "extern";
- }
- my $synop = "<row><entry role=\"variable_type\">${type_output}</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link></entry></row>\n";
-
- my $desc = "<refsect2 id=\"$id\" role=\"variable\"$condition>\n<title>$symbol</title>\n";
-
- $desc .= MakeIndexterms($symbol, $id);
- $desc .= "\n";
- $desc .= OutputSymbolExtraLinks($symbol);
-
- my $decl_out = &CreateValidSGML ($declaration);
- $desc .= "<programlisting language=\"C\">$decl_out</programlisting>\n";
-
- $desc .= &MakeDeprecationNote($symbol);
-
- if (defined ($SymbolDocs{$symbol})) {
- $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
- }
- if (defined ($SymbolAnnotations{$symbol})) {
- my $param_desc = $SymbolAnnotations{$symbol};
- my $param_annotations = "";
- ($param_desc,$param_annotations) = &ExpandAnnotation($symbol, $param_desc);
- if ($param_annotations ne "") {
- $desc .= "\n<para>$param_annotations</para>";
- }
- }
-
- $desc .= OutputSymbolTraits ($symbol);
- $desc .= "</refsect2>\n";
- return ($synop, $desc);
-}
-
-
-#############################################################################
-# Function : OutputFunction
-# Description : Returns the synopsis and detailed description of a function.
-# Arguments : $symbol - the function.
-# $declaration - the declaration of the function.
-#############################################################################
-
-sub OutputFunction {
- my ($symbol, $declaration, $symbol_type) = @_;
- my $id = &CreateValidSGMLID ($symbol);
- my $condition = &MakeConditionDescription ($symbol);
-
- # Take out the return type $1 $2 $3
- $declaration =~ s/<RETURNS>\s*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|enum\s+)*)(\w+)(\s*\**\s*(?:const|G_CONST_RETURN)?\s*\**\s*(?:restrict)?\s*)<\/RETURNS>\n//;
- my $type_modifier = defined($1) ? $1 : "";
- my $type = $2;
- my $pointer = $3;
- # Trim trailing spaces as we are going to pad to $RETURN_TYPE_FIELD_WIDTH below anyway
- $pointer =~ s/\s+$//;
- my $xref = &MakeXRef ($type, &tagify($type, "returnvalue"));
- my $start = "";
- #if ($symbol_type eq 'USER_FUNCTION') {
- # $start = "typedef ";
- #}
-
- # We output const rather than G_CONST_RETURN.
- $type_modifier =~ s/G_CONST_RETURN/const/g;
- $pointer =~ s/G_CONST_RETURN/const/g;
- $pointer =~ s/^\s+/ /g;
-
- my $ret_type_output;
- $ret_type_output = "$start$type_modifier$xref$pointer\n";
-
- my $indent_len;
- $indent_len = length ($symbol) + 2;
- my $char1 = my $char2 = my $char3 = "";
- if ($symbol_type eq 'USER_FUNCTION') {
- $indent_len += 3;
- $char1 = "<phrase role=\"c_punctuation\">(</phrase>";
- $char2 = "*";
- $char3 = "<phrase role=\"c_punctuation\">)</phrase>";
- }
-
- my ($symbol_output, $symbol_desc_output);
- $symbol_output = "$char1<link linkend=\"$id\">$char2$symbol</link>$char3";
- if ($indent_len < $MAX_SYMBOL_FIELD_WIDTH) {
- $symbol_desc_output = "$char1$char2$symbol$char3 ";
- } else {
- $indent_len = $MAX_SYMBOL_FIELD_WIDTH - 8;
- $symbol_desc_output = "$char1$char2$symbol$char3\n"
- . (' ' x ($indent_len - 1));
- }
-
- my $synop = "<row><entry role=\"function_type\">${ret_type_output}</entry><entry role=\"function_name\">${symbol_output} <phrase role=\"c_punctuation\">()</phrase></entry></row>\n";
-
- my $desc = "<refsect2 id=\"$id\" role=\"function\"$condition>\n<title>${symbol} ()</title>\n";
-
- $desc .= MakeIndexterms($symbol, $id);
- $desc .= "\n";
- $desc .= OutputSymbolExtraLinks($symbol);
-
- $desc .= "<programlisting language=\"C\">${ret_type_output}$symbol_desc_output(";
-
- my @fields = ParseFunctionDeclaration($declaration, \&MakeXRef,
- sub {
- &tagify($_[0],"parameter");
- });
-
- for (my $i = 1; $i <= $#fields; $i += 2) {
- my $field_name = $fields[$i];
-
- if ($i == 1) {
- $desc .= "$field_name";
- } else {
- $desc .= ",\n"
- . (' ' x $indent_len)
- . "$field_name";
- }
-
- }
-
- $desc .= ");</programlisting>\n";
-
- $desc .= &MakeDeprecationNote($symbol);
-
- if (defined ($SymbolDocs{$symbol})) {
- $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
- }
- if (defined ($SymbolAnnotations{$symbol})) {
- my $param_desc = $SymbolAnnotations{$symbol};
- my $param_annotations = "";
- ($param_desc,$param_annotations) = &ExpandAnnotation($symbol, $param_desc);
- if ($param_annotations ne "") {
- $desc .= "\n<para>$param_annotations</para>";
- }
- }
-
- $desc .= &OutputParamDescriptions ("FUNCTION", $symbol, @fields);
- $desc .= OutputSymbolTraits ($symbol);
- $desc .= "</refsect2>\n";
- return ($synop, $desc);
-}
-
-
-#############################################################################
-# Function : OutputParamDescriptions
-# Description : Returns the DocBook output describing the parameters of a
-# function, macro or signal handler.
-# Arguments : $symbol_type - 'FUNCTION', 'MACRO' or 'SIGNAL'. Signal
-# handlers have an implicit user_data parameter last.
-# $symbol - the name of the function/macro being described.
-# @fields - parsed fields from the declaration, used to determine
-# undocumented/unused entries
-#############################################################################
-
-sub OutputParamDescriptions {
- my ($symbol_type, $symbol, @fields) = @_;
- my $output = "";
- my $params = $SymbolParams{$symbol};
- my $num_params = 0;
- my %field_descrs = ();
-
- if (@fields) {
- %field_descrs = @fields;
- delete $field_descrs{"void"};
- delete $field_descrs{"Returns"};
- }
-
- if (defined $params) {
- my $returns = "";
- my $params_desc = "";
- my $missing_parameters = "";
- my $unused_parameters = "";
- my $j;
-
- for ($j = 0; $j <= $#$params; $j += $PARAM_FIELD_COUNT) {
- my $param_name = $$params[$j];
- my $param_desc = $$params[$j + 1];
- my $param_annotations = "";
-
- ($param_desc,$param_annotations) = &ExpandAnnotation($symbol, $param_desc);
- $param_desc = &ConvertMarkDown($symbol, $param_desc);
- # trim
- $param_desc =~ s/^(\s|\n)+//msg;
- $param_desc =~ s/(\s|\n)+$//msg;
- if ($param_name eq "Returns") {
- $returns = $param_desc;
- if ($param_annotations ne "") {
- $returns .= "\n<para>$param_annotations</para>";
- }
- } elsif ($param_name eq "void") {
- # FIXME: &LogWarning()?
- @TRACE@("!!!! void in params for $symbol?\n");
- } else {
- if (@fields) {
- if (!defined $field_descrs{$param_name}) {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Parameter description for $symbol"."::"."$param_name is not used from source code comment block.");
- if ($unused_parameters ne "") {
- $unused_parameters .= ", ".$param_name;
- } else {
- $unused_parameters = $param_name;
- }
- } else {
- delete $field_descrs{$param_name};
- }
- }
- if($param_desc ne "") {
- $params_desc .= "<row><entry role=\"parameter_name\"><para>$param_name</para></entry>\n<entry role=\"parameter_description\">$param_desc</entry>\n<entry role=\"parameter_annotations\">$param_annotations</entry></row>\n";
- $num_params++;
- }
- }
- }
- foreach my $param_name (keys %field_descrs) {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Parameter description for $symbol"."::"."$param_name is missing in source code comment block.");
- if ($missing_parameters ne "") {
- $missing_parameters .= ", ".$param_name;
- } else {
- $missing_parameters = $param_name;
- }
- }
-
- # Signals have an implicit user_data parameter which we describe.
- if ($symbol_type eq "SIGNAL") {
- $params_desc .= "<row><entry role=\"parameter_name\"><simpara>user_data</simpara></entry>\n<entry role=\"parameter_description\"><simpara>user data set when the signal handler was connected.</simpara></entry>\n<entry role=\"parameter_annotations\"></entry></row>\n";
- }
-
- # Start a table if we need one.
- if ($params_desc ne "") {
- my $id = &CreateValidSGMLID ("$symbol".".parameters");
-
- $output .= <<EOF;
-<refsect3 id="$id" role="parameters">\n<title>Parameters</title>
-<informaltable role="parameters_table" pgwide="1" frame="none">
-<tgroup cols="3">
-<colspec colname="parameters_name" colwidth="150px"/>
-<colspec colname="parameters_description"/>
-<colspec colname="parameters_annotations" colwidth="200px"/>
-<tbody>
-EOF
- $output .= $params_desc;
- $output .= "</tbody></tgroup></informaltable>\n</refsect3>";
- }
-
- # Output the returns info last
- if ($returns ne "") {
- my $id = &CreateValidSGMLID ("$symbol".".returns");
-
- $output .= <<EOF;
-<refsect3 id="$id" role=\"returns\">\n<title>Returns</title>
-EOF
- $output .= $returns;
- $output .= "\n</refsect3>";
- }
-
- # remember missing/unused parameters (needed in tmpl-free build)
- if (($missing_parameters ne "") and (! exists ($AllIncompleteSymbols{$symbol}))) {
- $AllIncompleteSymbols{$symbol}=$missing_parameters;
- }
- if (($unused_parameters ne "") and (! exists ($AllUnusedSymbols{$symbol}))) {
- $AllUnusedSymbols{$symbol}=$unused_parameters;
- }
- }
- if (($num_params == 0) && @fields && (scalar(keys(%field_descrs)) > 0)) {
- if (! exists ($AllIncompleteSymbols{$symbol})) {
- $AllIncompleteSymbols{$symbol}="<parameters>";
- }
- }
-
- return $output;
-}
-
-
-#############################################################################
-# Function : ParseStabilityLevel
-# Description : Parses a stability level and outputs a warning if it isn't
-# valid.
-# Arguments : $stability - the stability text.
-# $file, $line - context for error message
-# $message - description of where the level is from, to use in
-# any error message.
-# Returns : The parsed stability level string.
-#############################################################################
-
-sub ParseStabilityLevel {
- my ($stability, $file, $line, $message) = @_;
-
- $stability =~ s/^\s*//;
- $stability =~ s/\s*$//;
- if ($stability =~ m/^stable$/i) {
- $stability = "Stable";
- } elsif ($stability =~ m/^unstable$/i) {
- $stability = "Unstable";
- } elsif ($stability =~ m/^private$/i) {
- $stability = "Private";
- } else {
- &LogWarning ($file, $line, "$message is $stability.".
- "It should be one of these: Stable, Unstable, or Private.");
- }
- return $stability;
-}
-
-
-#############################################################################
-# Function : OutputDBFile
-# Description : Outputs the final DocBook file for one section.
-# Arguments : $file - the name of the file.
-# $title - the title from the $MODULE-sections.txt file, which
-# will be overridden by the title in the template file.
-# $section_id - the id to use for the toplevel tag.
-# $includes - comma-separates list of include files added at top of
-# synopsis, with '<' '>' around them (if not already enclosed in "").
-# $functions_synop - reference to the DocBook for the Functions Synopsis part.
-# $other_synop - reference to the DocBook for the Types and Values Synopsis part.
-# $functions_details - reference to the DocBook for the Functions Details part.
-# $other_details - reference to the DocBook for the Types and Values Details part.
-# $signal_synop - reference to the DocBook for the Signal Synopsis part
-# $signal_desc - reference to the DocBook for the Signal Description part
-# $args_synop - reference to the DocBook for the Arg Synopsis part
-# $args_desc - reference to the DocBook for the Arg Description part
-# $hierarchy - reference to the DocBook for the Object Hierarchy part
-# $interfaces - reference to the DocBook for the Interfaces part
-# $implementations - reference to the DocBook for the Known Implementations part
-# $prerequisites - reference to the DocBook for the Prerequisites part
-# $derived - reference to the DocBook for the Derived Interfaces part
-# $file_objects - reference to an array of objects in this file
-#############################################################################
-
-sub OutputDBFile {
- my ($file, $title, $section_id, $includes, $functions_synop, $other_synop, $functions_details, $other_details, $signals_synop, $signals_desc, $args_synop, $args_desc, $hierarchy, $interfaces, $implementations, $prerequisites, $derived, $file_objects) = @_;
-
- @TRACE@("Output docbook for file $file with title '$title'\n");
-
- # The edited title overrides the one from the sections file.
- my $new_title = $SymbolDocs{"$TMPL_DIR/$file:Title"};
- if (defined ($new_title) && $new_title !~ m/^\s*$/) {
- $title = $new_title;
- @TRACE@("Found title: $title\n");
- }
- my $short_desc = $SymbolDocs{"$TMPL_DIR/$file:Short_Description"};
- if (!defined ($short_desc) || $short_desc =~ m/^\s*$/) {
- $short_desc = "";
- } else {
- # Don't use ConvertMarkDown here for now since we don't want blocks
- $short_desc = &ExpandAbbreviations("$title:Short_description",
- $short_desc);
- @TRACE@("Found short_desc: $short_desc");
- }
- my $long_desc = $SymbolDocs{"$TMPL_DIR/$file:Long_Description"};
- if (!defined ($long_desc) || $long_desc =~ m/^\s*$/) {
- $long_desc = "";
- } else {
- $long_desc = &ConvertMarkDown("$title:Long_description",
- $long_desc);
- @TRACE@("Found long_desc: $long_desc");
- }
- my $see_also = $SymbolDocs{"$TMPL_DIR/$file:See_Also"};
- if (!defined ($see_also) || $see_also =~ m%^\s*(<para>)?\s*(</para>)?\s*$%) {
- $see_also = "";
- } else {
- $see_also = &ConvertMarkDown("$title:See_Also", $see_also);
- @TRACE@("Found see_also: $see_also");
- }
- if ($see_also) {
- $see_also = "<refsect1 id=\"$section_id.see-also\">\n<title>See Also</title>\n$see_also\n</refsect1>\n";
- }
- my $stability = $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"};
- if (!defined ($stability) || $stability =~ m/^\s*$/) {
- $stability = "";
- } else {
- $stability = &ParseStabilityLevel($stability, $file, $., "Section stability level");
- @TRACE@("Found stability: $stability");
- }
- if ($stability) {
- $AnnotationsUsed{$stability} = 1;
- $stability = "<refsect1 id=\"$section_id.stability-level\">\n<title>Stability Level</title>\n<acronym>$stability</acronym>, unless otherwise indicated\n</refsect1>\n";
- } elsif ($DEFAULT_STABILITY) {
- $AnnotationsUsed{$DEFAULT_STABILITY} = 1;
- $stability = "<refsect1 id=\"$section_id.stability-level\">\n<title>Stability Level</title>\n<acronym>$DEFAULT_STABILITY</acronym>, unless otherwise indicated\n</refsect1>\n";
- }
-
- my $image = $SymbolDocs{"$TMPL_DIR/$file:Image"};
- if (!defined ($image) || $image =~ m/^\s*$/) {
- $image = "";
- } else {
- $image =~ s/^\s*//;
- $image =~ s/\s*$//;
-
- my $format;
-
- if ($image =~ /jpe?g$/i) {
- $format = "format='JPEG'";
- } elsif ($image =~ /png$/i) {
- $format = "format='PNG'";
- } elsif ($image =~ /svg$/i) {
- $format = "format='SVG'";
- } else {
- $format = "";
- }
-
- $image = " <inlinegraphic fileref='$image' $format/>\n"
- }
-
- my ($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) =
- gmtime (time);
- my $month = (qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec))[$mon];
- $year += 1900;
-
- my $include_output = "";
- if ($includes) {
- $include_output .= "<refsect1 id=\"$section_id.includes\"><title>Includes</title><synopsis>";
- my $include;
- foreach $include (split (/,/, $includes)) {
- if ($include =~ m/^\".+\"$/) {
- $include_output .= "#include ${include}\n";
- }
- else {
- $include =~ s/^\s+|\s+$//gs;
- $include_output .= "#include <${include}>\n";
- }
- }
- $include_output .= "</synopsis></refsect1>\n";
- }
-
- my $extralinks = OutputSectionExtraLinks($title,"Section:$file");
-
- my $old_db_file = "$DB_OUTPUT_DIR/$file.xml";
- my $new_db_file = "$DB_OUTPUT_DIR/$file.xml.new";
-
- open (OUTPUT, ">$new_db_file")
- || die "Can't create $new_db_file: $!";
-
- my $object_anchors = "";
- foreach my $object (@$file_objects) {
- next if ($object eq $section_id);
- my $id = CreateValidSGMLID($object);
- @TRACE@("Adding anchor for $object\n");
- $object_anchors .= "<anchor id=\"$id\"/>";
- }
-
- # Make sure we produce valid docbook
- $$functions_details ||= "<para />";
-
- # We used to output this, but is messes up our UpdateFileIfChanged code
- # since it changes every day (and it is only used in the man pages):
- # "<refentry id="$section_id" revision="$mday $month $year">"
-
- print OUTPUT <<EOF;
-${\( MakeDocHeader ("refentry") )}
-<refentry id="$section_id">
-<refmeta>
-<refentrytitle role="top_of_page" id="$section_id.top_of_page">$title</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>\U$MODULE\E Library$image</refmiscinfo>
-</refmeta>
-<refnamediv>
-<refname>$title</refname>
-<refpurpose>$short_desc</refpurpose>
-</refnamediv>
-$stability
-$$functions_synop$$args_synop$$signals_synop$object_anchors$$other_synop$$hierarchy$$prerequisites$$derived$$interfaces$$implementations
-$include_output
-<refsect1 id="$section_id.description" role="desc">
-<title role="desc.title">Description</title>
-$extralinks$long_desc
-</refsect1>
-<refsect1 id="$section_id.functions_details" role="details">
-<title role="details.title">Functions</title>
-$$functions_details
-</refsect1>
-<refsect1 id="$section_id.other_details" role="details">
-<title role="details.title">Types and Values</title>
-$$other_details
-</refsect1>
-$$args_desc$$signals_desc$see_also
-</refentry>
-EOF
- close (OUTPUT);
-
- return &UpdateFileIfChanged ($old_db_file, $new_db_file, 0);
-}
-
-
-#############################################################################
-# Function : OutputExtraFile
-# Description : Copies an "extra" DocBook file into the output directory,
-# expanding abbreviations
-# Arguments : $file - the source file.
-#############################################################################
-sub OutputExtraFile {
- my ($file) = @_;
-
- my $basename;
-
- ($basename = $file) =~ s!^.*/!!;
-
- my $old_db_file = "$DB_OUTPUT_DIR/$basename";
- my $new_db_file = "$DB_OUTPUT_DIR/$basename.new";
-
- my $contents;
-
- open(EXTRA_FILE, "<$file") || die "Can't open $file";
-
- {
- local $/;
- $contents = <EXTRA_FILE>;
- }
-
- open (OUTPUT, ">$new_db_file")
- || die "Can't create $new_db_file: $!";
-
- print OUTPUT &ExpandAbbreviations ("$basename file", $contents);
- close (OUTPUT);
-
- return &UpdateFileIfChanged ($old_db_file, $new_db_file, 0);
-}
-#############################################################################
-# Function : OutputBook
-# Description : Outputs the entities that need to be included into the
-# main docbook file for the module.
-# Arguments : $book_top - the declarations of the entities, which are added
-# at the top of the main docbook file.
-# $book_bottom - the references to the entities, which are
-# added in the main docbook file at the desired position.
-#############################################################################
-
-sub OutputBook {
- my ($book_top, $book_bottom) = @_;
-
- my $old_file = "$DB_OUTPUT_DIR/$MODULE-doc.top";
- my $new_file = "$DB_OUTPUT_DIR/$MODULE-doc.top.new";
-
- open (OUTPUT, ">$new_file")
- || die "Can't create $new_file: $!";
- print OUTPUT $book_top;
- close (OUTPUT);
-
- &UpdateFileIfChanged ($old_file, $new_file, 0);
-
-
- $old_file = "$DB_OUTPUT_DIR/$MODULE-doc.bottom";
- $new_file = "$DB_OUTPUT_DIR/$MODULE-doc.bottom.new";
-
- open (OUTPUT, ">$new_file")
- || die "Can't create $new_file: $!";
- print OUTPUT $book_bottom;
- close (OUTPUT);
-
- &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_SGML_FILE && ! -e $MAIN_SGML_FILE) {
- open (OUTPUT, ">$MAIN_SGML_FILE")
- || die "Can't create $MAIN_SGML_FILE: $!";
-
- print OUTPUT <<EOF;
-${\( MakeDocHeader ("book") )}
-<book id="index">
- <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>
-
- <chapter>
- <title>[Insert title here]</title>
- $book_bottom
- </chapter>
-EOF
- if (-e $OBJECT_TREE_FILE) {
- print OUTPUT <<EOF;
- <chapter id="object-tree">
- <title>Object Hierarchy</title>
- <xi:include href="xml/tree_index.sgml"/>
- </chapter>
-EOF
- } else {
- print OUTPUT <<EOF;
- <!-- enable this when you use gobject types
- <chapter id="object-tree">
- <title>Object Hierarchy</title>
- <xi:include href="xml/tree_index.sgml"/>
- </chapter>
- -->
-EOF
- }
- print OUTPUT <<EOF;
- <index id="api-index-full">
- <title>API Index</title>
- <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
- </index>
- <index id="deprecated-api-index" role="deprecated">
- <title>Index of deprecated API</title>
- <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
- </index>
-EOF
- if (keys(%AnnotationsUsed)) {
- print OUTPUT <<EOF;
- <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-EOF
- } else {
- print OUTPUT <<EOF;
- <!-- enable this when you use gobject introspection annotations
- <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
-EOF
- }
- print OUTPUT <<EOF;
-</book>
-EOF
-
- close (OUTPUT);
- }
-}
-
-
-#############################################################################
-# Function : CreateValidSGML
-# Description : This turns any chars which are used in SGML into entities,
-# e.g. '<' into '<'
-# Arguments : $text - the text to turn into proper SGML.
-#############################################################################
-
-sub CreateValidSGML {
- my ($text) = @_;
- $text =~ s/&/&/g; # Do this first, or the others get messed up.
- $text =~ s/</</g;
- $text =~ s/>/>/g;
- # browers render single tabs inconsistently
- $text =~ s/([^\s])\t([^\s])/$1 $2/g;
- return $text;
-}
-
-#############################################################################
-# Function : ConvertSGMLChars
-# Description : This is used for text in source code comment blocks, to turn
-# chars which are used in SGML into entities, e.g. '<' into
-# '<'. Depending on $INLINE_MARKUP_MODE, this is done
-# unconditionally or only if the character doesn't seem to be
-# part of an SGML construct (tag or entity reference).
-# Arguments : $text - the text to turn into proper SGML.
-#############################################################################
-
-sub ConvertSGMLChars {
- my ($symbol, $text) = @_;
-
- if ($INLINE_MARKUP_MODE) {
- # For the XML/SGML mode only convert to entities outside CDATA sections.
- return &ModifyXMLElements ($text, $symbol,
- "<!\\[CDATA\\[|<programlisting[^>]*>",
- \&ConvertSGMLCharsEndTag,
- \&ConvertSGMLCharsCallback);
- } else {
- # For the simple non-sgml mode, convert to entities everywhere.
-
- # First, convert freestanding & to &
- $text =~ s/&(?![a-zA-Z#]+;)/&/g;
- $text =~ s/</</g;
- # Allow ">" at beginning of string for blockquote markdown
- $text =~ s/(?<=[^\w\n"'\/-])>/>/g;
-
- return $text;
- }
-}
-
-
-sub ConvertSGMLCharsEndTag {
- if ($_[0] eq "<!\[CDATA\[") {
- return "]]>";
- } else {
- return "</programlisting>";
- }
-}
-
-sub ConvertSGMLCharsCallback {
- my ($text, $symbol, $tag) = @_;
-
- if ($tag =~ m/^<programlisting/) {
- # We can handle <programlisting> specially here.
- return &ModifyXMLElements ($text, $symbol,
- "<!\\[CDATA\\[",
- \&ConvertSGMLCharsEndTag,
- \&ConvertSGMLCharsCallback2);
- } elsif ($tag eq "") {
- # If we're not in CDATA convert to entities.
- $text =~ s/&(?![a-zA-Z#]+;)/&/g; # Do this first, or the others get messed up.
- $text =~ s/<(?![a-zA-Z\/!])/</g;
- # Allow ">" at beginning of string for blockquote markdown
- $text =~ s/(?<=[^\w\n"'\/-])>/>/g;
-
- # Handle "#include <xxxxx>"
- $text =~ s/#include(\s+)<([^>]+)>/#include$1<$2>/g;
- }
-
- return $text;
-}
-
-sub ConvertSGMLCharsCallback2 {
- my ($text, $symbol, $tag) = @_;
-
- # If we're not in CDATA convert to entities.
- # We could handle <programlisting> differently, though I'm not sure it helps.
- if ($tag eq "") {
- # replace only if its not a tag
- $text =~ s/&(?![a-zA-Z#]+;)/&/g; # Do this first, or the others get messed up.
- $text =~ s/<(?![a-zA-Z\/!])/</g;
- $text =~ s/(?<![a-zA-Z0-9"'\/-])>/>/g;
-
- # Handle "#include <xxxxx>"
- $text =~ s/#include(\s+)<([^>]+)>/#include$1<$2>/g;
- }
-
- return $text;
-}
-
-#############################################################################
-# Function : ExpandAnnotation
-# Description : This turns annotations into acronym tags.
-# Arguments : $symbol - the symbol being documented, for error messages.
-# $text - the text to expand.
-#############################################################################
-sub ExpandAnnotation {
- my ($symbol, $param_desc) = @_;
- my $param_annotations = "";
-
- # look for annotations at the start of the comment part
- # function level annotations don't end with a colon ':'
- if ($param_desc =~ m%^\s*\((.*?)\)(:|$)%) {
- my @annotations;
- my $annotation;
- $param_desc = $';
-
- @annotations = split(/\)\s*\(/,$1);
- @TRACE@("annotations for $symbol: '$1'\n");
- foreach $annotation (@annotations) {
- # need to search for the longest key-match in %AnnotationDefinition
- my $match_length=0;
- my $match_annotation="";
- my $annotationdef;
- foreach $annotationdef (keys %AnnotationDefinition) {
- if ($annotation =~ m/^$annotationdef/) {
- if (length($annotationdef)>$match_length) {
- $match_length=length($annotationdef);
- $match_annotation=$annotationdef;
- }
- }
- }
- my $annotation_extra = "";
- if ($match_annotation ne "") {
- if ($annotation =~ m%$match_annotation\s+(.*)%) {
- $annotation_extra = " $1";
- }
- $AnnotationsUsed{$match_annotation} = 1;
- $param_annotations .= "[<acronym>$match_annotation</acronym>$annotation_extra]";
- }
- else {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "unknown annotation \"$annotation\" in documentation for $symbol.");
- $param_annotations .= "[$annotation]";
- }
- }
- chomp($param_desc);
- $param_desc =~ m/^(.*?)\.*\s*$/s;
- $param_desc = "$1. ";
- }
- if ($param_annotations ne "") {
- $param_annotations = "<emphasis role=\"annotation\">$param_annotations</emphasis>";
- }
- return ($param_desc, $param_annotations);
-}
-
-#############################################################################
-# Function : ExpandAbbreviations
-# Description : This turns the abbreviations function(), macro(), @param,
-# %constant, and #symbol into appropriate DocBook markup.
-# CDATA sections and <programlisting> parts are skipped.
-# Arguments : $symbol - the symbol being documented, for error messages.
-# $text - the text to expand.
-#############################################################################
-
-sub ExpandAbbreviations {
- my ($symbol, $text) = @_;
-
- # Note: This is a fallback and normally done in the markdown parser
-
- # Convert "|[" and "]|" into the start and end of program listing examples.
- # Support \[<!-- language="C" --> modifiers
- $text =~ s%\|\[<!-- language="([^"]+)" -->%<informalexample><programlisting language="$1"><![CDATA[%g;
- $text =~ s%\|\[%<informalexample><programlisting><![CDATA[%g;
- $text =~ s%\]\|%]]></programlisting></informalexample>%g;
-
- # keep CDATA unmodified, preserve ulink tags (ideally we preseve all tags
- # as such)
- return &ModifyXMLElements ($text, $symbol,
- "<!\\[CDATA\\[|<ulink[^>]*>|<programlisting[^>]*>|<!DOCTYPE",
- \&ExpandAbbreviationsEndTag,
- \&ExpandAbbreviationsCallback);
-}
-
-
-# Returns the end tag (as a regexp) corresponding to the given start tag.
-sub ExpandAbbreviationsEndTag {
- my ($start_tag) = @_;
-
- if ($start_tag eq "<!\[CDATA\[") {
- return "]]>";
- } elsif ($start_tag eq "<!DOCTYPE") {
- return ">";
- } elsif ($start_tag =~ m/<(\w+)/) {
- return "</$1>";
- }
-}
-
-# Called inside or outside each CDATA or <programlisting> section.
-sub ExpandAbbreviationsCallback {
- my ($text, $symbol, $tag) = @_;
-
- if ($tag =~ m/^<programlisting/) {
- # Handle any embedded CDATA sections.
- return &ModifyXMLElements ($text, $symbol,
- "<!\\[CDATA\\[",
- \&ExpandAbbreviationsEndTag,
- \&ExpandAbbreviationsCallback2);
- } elsif ($tag eq "") {
- # NOTE: this is a fallback. It is normally done by the Markdown parser.
-
- # We are outside any CDATA or <programlisting> sections, so we expand
- # any gtk-doc abbreviations.
-
- # Convert '@param()'
- # FIXME: we could make those also links ($symbol.$2), but that would be less
- # useful as the link target is a few lines up or down
- $text =~ s/(\A|[^\\])\@(\w+((\.|->)\w+)*)\s*\(\)/$1<parameter>$2()<\/parameter>/g;
-
- # Convert 'function()' or 'macro()'.
- # if there is abc_*_def() we don't want to make a link to _def()
- # FIXME: also handle abc(def(....)) : but that would need to be done recursively :/
- $text =~ s/([^\*.\w])(\w+)\s*\(\)/$1.&MakeXRef($2, &tagify($2 . "()", "function"));/eg;
- # handle #Object.func()
- $text =~ s/(\A|[^\\])#([\w\-:\.]+[\w]+)\s*\(\)/$1.&MakeXRef($2, &tagify($2 . "()", "function"));/eg;
-
- # Convert '@param', but not '\@param'.
- $text =~ s/(\A|[^\\])\@(\w+((\.|->)\w+)*)/$1<parameter>$2<\/parameter>/g;
- $text =~ s/\\\@/\@/g;
-
- # Convert '%constant', but not '\%constant'.
- # Also allow negative numbers, e.g. %-1.
- $text =~ s/(\A|[^\\])\%(-?\w+)/$1.&MakeXRef($2, &tagify($2, "literal"));/eg;
- $text =~ s/\\\%/\%/g;
-
- # Convert '#symbol', but not '\#symbol'.
- $text =~ s/(\A|[^\\])#([\w\-:\.]+[\w]+)/$1.&MakeHashXRef($2, "type");/eg;
- $text =~ s/\\#/#/g;
- }
-
- return $text;
-}
-
-# This is called inside a <programlisting>
-sub ExpandAbbreviationsCallback2 {
- my ($text, $symbol, $tag) = @_;
-
- if ($tag eq "") {
- # We are inside a <programlisting> but outside any CDATA sections,
- # so we expand any gtk-doc abbreviations.
- # FIXME: why is this different from &ExpandAbbreviationsCallback(),
- # why not just call it
- $text =~ s/#(\w+)/&MakeHashXRef($1, "");/eg;
- } elsif ($tag eq "<![CDATA[") {
- # NOTE: this is a fallback. It is normally done by the Markdown parser.
- $text = &ReplaceEntities ($text, $symbol);
- }
-
- return $text;
-}
-
-sub MakeHashXRef {
- my ($symbol, $tag) = @_;;
- my $text = $symbol;
-
- # Check for things like '#include', '#define', and skip them.
- if ($PreProcessorDirectives{$symbol}) {
- return "#$symbol";
- }
-
- # Get rid of special suffixes ('-struct','-enum').
- $text =~ s/-struct$//;
- $text =~ s/-enum$//;
-
- # If the symbol is in the form "Object::signal", then change the symbol to
- # "Object-signal" and use "signal" as the text.
- if ($symbol =~ s/::/-/) {
- $text = "“$'”";
- }
-
- # If the symbol is in the form "Object:property", then change the symbol to
- # "Object--property" and use "property" as the text.
- if ($symbol =~ s/:/--/) {
- $text = "“$'”";
- }
-
- if ($tag ne "") {
- $text = tagify ($text, $tag);
- }
-
- return &MakeXRef($symbol, $text);
-}
-
-
-#############################################################################
-# Function : ModifyXMLElements
-# Description : Looks for given XML element tags within the text, and calls
-# the callback on pieces of text inside & outside those elements.
-# Used for special handling of text inside things like CDATA
-# and <programlisting>.
-# Arguments : $text - the text.
-# $symbol - the symbol currently being documented (only used for
-# error messages).
-# $start_tag_regexp - the regular expression to match start tags.
-# e.g. "<!\\[CDATA\\[|<programlisting[^>]*>" to match
-# CDATA sections or programlisting elements.
-# $end_tag_func - function which is passed the matched start tag
-# and should return the appropriate end tag string regexp.
-# $callback - callback called with each part of the text. It is
-# called with a piece of text, the symbol being
-# documented, and the matched start tag or "" if the text
-# is outside the XML elements being matched.
-#############################################################################
-sub ModifyXMLElements {
- my ($text, $symbol, $start_tag_regexp, $end_tag_func, $callback) = @_;
- my ($before_tag, $start_tag, $end_tag_regexp, $end_tag);
- my $result = "";
-
- while ($text =~ m/$start_tag_regexp/s) {
- $before_tag = $`; # Prematch for last successful match string
- $start_tag = $&; # Last successful match
- $text = $'; # Postmatch for last successful match string
-
- $result .= &$callback ($before_tag, $symbol, "");
- $result .= $start_tag;
-
- # get the matching end-tag for current tag
- $end_tag_regexp = &$end_tag_func ($start_tag);
-
- if ($text =~ m/$end_tag_regexp/s) {
- $before_tag = $`;
- $end_tag = $&;
- $text = $';
-
- $result .= &$callback ($before_tag, $symbol, $start_tag);
- $result .= $end_tag;
- } else {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Can't find tag end: $end_tag_regexp in docs for: $symbol.");
- # Just assume it is all inside the tag.
- $result .= &$callback ($text, $symbol, $start_tag);
- $text = "";
- }
- }
-
- # Handle any remaining text outside the tags.
- $result .= &$callback ($text, $symbol, "");
-
- return $result;
-}
-
-sub noop {
- return $_[0];
-}
-
-# Adds a tag around some text.
-# e.g tagify("Text", "literal") => "<literal>Text</literal>".
-sub tagify {
- my ($text, $elem) = @_;
- return "<" . $elem . ">" . $text . "</" . $elem . ">";
-}
-
-#############################################################################
-# Function : MakeDocHeader
-# Description : Builds a docbook header for the given tag
-# Arguments : $tag - doctype tag
-#############################################################################
-
-sub MakeDocHeader {
- my ($tag) = @_;
- my $header = $doctype_header;
- $header =~ s/<!DOCTYPE \w+/<!DOCTYPE $tag/;
-
- # fix the path for book since this is one level up
- if ($tag eq "book") {
- $header =~ s#<!ENTITY % gtkdocentities SYSTEM \"../([a-zA-Z./]+)\">#<!ENTITY % gtkdocentities SYSTEM \"$1\">#;
- }
-
- return $header;
-}
-
-
-#############################################################################
-# Function : MakeXRef
-# Description : This returns a cross-reference link to the given symbol.
-# Though it doesn't try to do this for a few standard C types
-# that it knows won't be in the documentation.
-# Arguments : $symbol - the symbol to try to create a XRef to.
-# $text - text text to put inside the XRef, defaults to $symbol
-#############################################################################
-
-sub MakeXRef {
- my ($symbol, $text) = ($_[0], $_[1]);
-
- $symbol =~ s/^\s+//;
- $symbol =~ s/\s+$//;
-
- if (!defined($text)) {
- $text = $symbol;
-
- # Get rid of special suffixes ('-struct','-enum').
- $text =~ s/-struct$//;
- $text =~ s/-enum$//;
- }
-
- if ($symbol =~ m/ /) {
- return "$text";
- }
-
- @TRACE@("Getting type link for $symbol -> $text\n");
-
- my $symbol_id = &CreateValidSGMLID ($symbol);
- return "<link linkend=\"$symbol_id\">$text</link>";
-}
-
-
-#############################################################################
-# Function : MakeIndexterms
-# Description : This returns a indexterm elements for the given symbol
-# Arguments : $symbol - the symbol to create indexterms for
-#############################################################################
-
-sub MakeIndexterms {
- my ($symbol, $id) = @_;
- my $terms = "";
- my $sortas = "";
-
- # make the index useful, by ommiting the namespace when sorting
- if ($NAME_SPACE ne "") {
- if ($symbol =~ m/^$NAME_SPACE\_?(.*)/i) {
- $sortas=" sortas=\"$1\"";
- }
- }
-
- if (exists $Deprecated{$symbol}) {
- $terms .= "<indexterm zone=\"$id\" role=\"deprecated\"><primary$sortas>$symbol</primary></indexterm>";
- $IndexEntriesDeprecated{$symbol}=$id;
- $IndexEntriesFull{$symbol}=$id;
- }
- if (exists $Since{$symbol}) {
- my $since = $Since{$symbol};
- $since =~ s/^\s+//;
- $since =~ s/\s+$//;
- if ($since ne "") {
- $terms .= "<indexterm zone=\"$id\" role=\"$since\"><primary$sortas>$symbol</primary></indexterm>";
- }
- $IndexEntriesSince{$symbol}=$id;
- $IndexEntriesFull{$symbol}=$id;
- }
- if ($terms eq "") {
- $terms .= "<indexterm zone=\"$id\"><primary$sortas>$symbol</primary></indexterm>";
- $IndexEntriesFull{$symbol}=$id;
- }
-
- return $terms;
- }
-
-#############################################################################
-# Function : MakeDeprecationNote
-# Description : This returns a deprecation warning for the given symbol.
-# Arguments : $symbol - the symbol to try to create a warning for.
-#############################################################################
-
-sub MakeDeprecationNote {
- my ($symbol) = $_[0];
- my $desc = "";
- if (exists $Deprecated{$symbol}) {
- my $note;
-
- $desc .= "<warning><para><literal>$symbol</literal> ";
-
- $note = $Deprecated{$symbol};
-
- if ($note =~ /^\s*([0-9\.]+)\s*:?/) {
- $desc .= "has been deprecated since version $1 and should not be used in newly-written code.</para>";
- } else {
- $desc .= "is deprecated and should not be used in newly-written code.</para>";
- }
- $note =~ s/^\s*([0-9\.]+)\s*:?\s*//;
- $note =~ s/^\s+//;
- $note =~ s/\s+$//;
- if ($note ne "") {
- $note = &ConvertMarkDown($symbol, $note);
- $desc .= " " . $note;
- }
- $desc .= "</warning>\n";
- }
- return $desc;
-}
-
-#############################################################################
-# Function : MakeConditionDescription
-# Description : This returns a sumary of conditions for the given symbol.
-# Arguments : $symbol - the symbol to try to create the sumary.
-#############################################################################
-
-sub MakeConditionDescription {
- my ($symbol) = $_[0];
- my $desc = "";
-
- if (exists $Deprecated{$symbol}) {
- if ($desc ne "") {
- $desc .= "|";
- }
-
- if ($Deprecated{$symbol} =~ /^\s*(.*?)\s*$/) {
- $desc .= "deprecated:$1";
- } else {
- $desc .= "deprecated";
- }
- }
-
- if (exists $Since{$symbol}) {
- if ($desc ne "") {
- $desc .= "|";
- }
-
- if ($Since{$symbol} =~ /^\s*(.*?)\s*$/) {
- $desc .= "since:$1";
- } else {
- $desc .= "since";
- }
- }
-
- if (exists $StabilityLevel{$symbol}) {
- if ($desc ne "") {
- $desc .= "|";
- }
- $desc .= "stability:".$StabilityLevel{$symbol};
- }
-
- if ($desc ne "") {
- my $cond = $desc;
- $cond =~ s/\"/"/g;
- $desc=" condition=\"".$cond."\"";
- @TRACE@("condition for '$symbol' = '$desc'\n");
- }
- return $desc;
-}
-
-#############################################################################
-# Function : GetHierarchy
-# Description : Returns the DocBook output describing the ancestors and
-# immediate children of a GObject subclass. It uses the
-# global @Objects and @ObjectLevels arrays to walk the tree.
-#
-# Arguments : $object - the GtkObject subclass.
-# @hierarchy - previous hierarchy
-#############################################################################
-
-sub GetHierarchy {
- my ($object,$hierarchy_ref) = @_;
- my @hierarchy = @{$hierarchy_ref};
-
- # Find object in the objects array.
- my $found = 0;
- my @children = ();
- my $i;
- my $level;
- my $j;
- for ($i = 0; $i < @Objects; $i++) {
- if ($found) {
- if ($ObjectLevels[$i] <= $level) {
- last;
- }
- elsif ($ObjectLevels[$i] == $level + 1) {
- push (@children, $Objects[$i]);
- }
- }
- elsif ($Objects[$i] eq $object) {
- $found = 1;
- $j = $i;
- $level = $ObjectLevels[$i];
- }
- }
- if (!$found) {
- return @hierarchy;
- }
-
- # Walk up the hierarchy, pushing ancestors onto the ancestors array.
- my @ancestors = ();
- push (@ancestors, $object);
- @TRACE@("Level: $level\n");
- while ($level > 1) {
- $j--;
- if ($ObjectLevels[$j] < $level) {
- push (@ancestors, $Objects[$j]);
- $level = $ObjectLevels[$j];
- @TRACE@("Level: $level\n");
- }
- }
-
- # Output the ancestors, indented and with links.
- my $last_index = 0;
- $level = 1;
- for ($i = $#ancestors; $i >= 0; $i--) {
- my $entry_text;
- my $alt_text;
- my $ancestor = $ancestors[$i];
- my $ancestor_id = &CreateValidSGMLID ($ancestor);
- my $indent = ' ' x ($level * 4);
- # Don't add a link to the current object, i.e. when i == 0.
- if ($i > 0) {
- $entry_text = $indent . "<link linkend=\"$ancestor_id\">$ancestor</link>";
- $alt_text = $indent . $ancestor;
- } else {
- $entry_text = $indent . $ancestor;
- $alt_text = $indent . "<link linkend=\"$ancestor_id\">$ancestor</link>";
- }
- @TRACE@("Checking for '$entry_text' or '$alt_text'");
- # Check if we already have this object
- my $index = -1;
- for ($j = 0; $j <= $#hierarchy; $j++) {
- if (($hierarchy[$j] eq $entry_text) or ($hierarchy[$j] eq $alt_text)) {
- $index = $j;
- last;
- }
- }
- if ($index == -1) {
- # We have a new entry, find insert position in alphabetical order
- my $found = 0;
- for ($j = $last_index; $j <= $#hierarchy; $j++) {
- if ($hierarchy[$j] !~ m/^${indent}/) {
- $last_index = $j;
- $found = 1;
- last;
- } elsif ($hierarchy[$j] =~ m/^${indent}[^ ]/) {
- my $stripped_text = $hierarchy[$j];
- if ($entry_text !~ m/<link linkend/) {
- $stripped_text =~ s%<link linkend="[A-Za-z]*">%%;
- $stripped_text =~ s%</link>%%;
- }
- if ($entry_text lt $stripped_text) {
- $last_index = $j;
- $found = 1;
- last;
- }
- }
- }
- # Append to bottom
- if (!$found) {
- $last_index = 1 + $#hierarchy;
- }
- splice @hierarchy, $last_index, 0, ($entry_text);
- $last_index++;
- } else {
- # Already have this one, make sure we use the not linked version
- if ($entry_text !~ m/<link linkend=/) {
- $hierarchy[$j] = $entry_text;
- }
- # Remember index as base insert point
- $last_index = $index + 1;
- }
- $level++;
- }
- # Output the children, indented and with links.
- for ($i = 0; $i <= $#children; $i++) {
- my $id = &CreateValidSGMLID ($children[$i]);
- my $indented_text = ' ' x ($level * 4) . "<link linkend=\"$id\">$children[$i]</link>";
- splice @hierarchy, $last_index, 0, ($indented_text);
- $last_index++;
- }
-
- return @hierarchy;
-}
-
-#############################################################################
-# Function : GetInterfaces
-# Description : Returns the DocBook output describing the interfaces
-# implemented by a class. It uses the global %Interfaces hash.
-# Arguments : $object - the GtkObject subclass.
-#############################################################################
-
-sub GetInterfaces {
- my ($object) = @_;
- my $text = "";
- my $i;
-
- # Find object in the objects array.
- if (exists($Interfaces{$object})) {
- my @ifaces = split(' ', $Interfaces{$object});
- $text = <<EOF;
-<para>
-$object implements
-EOF
- for ($i = 0; $i <= $#ifaces; $i++) {
- my $id = &CreateValidSGMLID ($ifaces[$i]);
- $text .= " <link linkend=\"$id\">$ifaces[$i]</link>";
- if ($i < $#ifaces - 1) {
- $text .= ', ';
- }
- elsif ($i < $#ifaces) {
- $text .= ' and ';
- }
- else {
- $text .= '.';
- }
- }
- $text .= <<EOF;
-</para>
-EOF
- }
-
- return $text;
-}
-
-#############################################################################
-# Function : GetImplementations
-# Description : Returns the DocBook output describing the implementations
-# of an interface. It uses the global %Interfaces hash.
-# Arguments : $object - the GtkObject subclass.
-#############################################################################
-
-sub GetImplementations {
- my ($object) = @_;
- my @impls = ();
- my $text = "";
- my $i;
- foreach my $key (keys %Interfaces) {
- if ($Interfaces{$key} =~ /\b$object\b/) {
- push (@impls, $key);
- }
- }
- if ($#impls >= 0) {
- @impls = sort @impls;
- $text = <<EOF;
-<para>
-$object is implemented by
-EOF
- for ($i = 0; $i <= $#impls; $i++) {
- my $id = &CreateValidSGMLID ($impls[$i]);
- $text .= " <link linkend=\"$id\">$impls[$i]</link>";
- if ($i < $#impls - 1) {
- $text .= ', ';
- }
- elsif ($i < $#impls) {
- $text .= ' and ';
- }
- else {
- $text .= '.';
- }
- }
- $text .= <<EOF;
-</para>
-EOF
- }
- return $text;
-}
-
-
-#############################################################################
-# Function : GetPrerequisites
-# Description : Returns the DocBook output describing the prerequisites
-# of an interface. It uses the global %Prerequisites hash.
-# Arguments : $iface - the interface.
-#############################################################################
-
-sub GetPrerequisites {
- my ($iface) = @_;
- my $text = "";
- my $i;
-
- if (exists($Prerequisites{$iface})) {
- $text = <<EOF;
-<para>
-$iface requires
-EOF
- my @prereqs = split(' ', $Prerequisites{$iface});
- for ($i = 0; $i <= $#prereqs; $i++) {
- my $id = &CreateValidSGMLID ($prereqs[$i]);
- $text .= " <link linkend=\"$id\">$prereqs[$i]</link>";
- if ($i < $#prereqs - 1) {
- $text .= ', ';
- }
- elsif ($i < $#prereqs) {
- $text .= ' and ';
- }
- else {
- $text .= '.';
- }
- }
- $text .= <<EOF;
-</para>
-EOF
- }
- return $text;
-}
-
-#############################################################################
-# Function : GetDerived
-# Description : Returns the DocBook output describing the derived interfaces
-# of an interface. It uses the global %Prerequisites hash.
-# Arguments : $iface - the interface.
-#############################################################################
-
-sub GetDerived {
- my ($iface) = @_;
- my $text = "";
- my $i;
-
- my @derived = ();
- foreach my $key (keys %Prerequisites) {
- if ($Prerequisites{$key} =~ /\b$iface\b/) {
- push (@derived, $key);
- }
- }
- if ($#derived >= 0) {
- @derived = sort @derived;
- $text = <<EOF;
-<para>
-$iface is required by
-EOF
- for ($i = 0; $i <= $#derived; $i++) {
- my $id = &CreateValidSGMLID ($derived[$i]);
- $text .= " <link linkend=\"$id\">$derived[$i]</link>";
- if ($i < $#derived - 1) {
- $text .= ', ';
- }
- elsif ($i < $#derived) {
- $text .= ' and ';
- }
- else {
- $text .= '.';
- }
- }
- $text .= <<EOF;
-</para>
-EOF
- }
- return $text;
-}
-
-
-#############################################################################
-# Function : GetSignals
-# Description : Returns the synopsis and detailed description DocBook output
-# for the signal handlers of a given GtkObject subclass.
-# Arguments : $object - the GtkObject subclass, e.g. 'GtkButton'.
-#############################################################################
-
-sub GetSignals {
- my ($object) = @_;
- my $synop = "";
- my $desc = "";
-
- my $i;
- for ($i = 0; $i <= $#SignalObjects; $i++) {
- if ($SignalObjects[$i] eq $object) {
- @TRACE@("Found signal: $SignalNames[$i]\n");
- my $name = $SignalNames[$i];
- my $symbol = "${object}::${name}";
- my $id = &CreateValidSGMLID ("$object-$name");
-
- $desc .= "<refsect2 id=\"$id\" role=\"signal\"><title>The <literal>“$name”</literal> signal</title>\n";
- $desc .= MakeIndexterms($symbol, $id);
- $desc .= "\n";
- $desc .= OutputSymbolExtraLinks($symbol);
-
- $desc .= "<programlisting language=\"C\">";
-
- $SignalReturns[$i] =~ m/\s*(const\s+)?(\w+)\s*(\**)/;
- my $type_modifier = defined($1) ? $1 : "";
- my $type = $2;
- my $pointer = $3;
- my $xref = &MakeXRef ($type, &tagify($type, "returnvalue"));
-
- my $ret_type_output = "$type_modifier$xref$pointer";
- my $callback_name = "user_function";
- $desc .= "${ret_type_output}\n${callback_name} (";
-
- my $indentation = ' ' x (length($callback_name) + 2);
- my $pad = $indentation;
-
- my $sourceparams = $SourceSymbolParams{$symbol};
- my @params = split ("\n", $SignalPrototypes[$i]);
- my $j;
- my $l;
- my $type_len = length("gpointer");
- my $name_len = length("user_data");
- # do two passes, the first one is to calculate padding
- for ($l = 0; $l < 2; $l++) {
- for ($j = 0; $j <= $#params; $j++) {
- my $param_name;
- # allow alphanumerics, '_', '[' & ']' in param names
- if ($params[$j] =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)\s*$/) {
- $type = $1;
- $pointer = $2;
- if (defined($sourceparams)) {
- $param_name = $$sourceparams[$PARAM_FIELD_COUNT * $j];
- }
- else {
- $param_name = $3;
- }
- if (!defined($param_name)) {
- $param_name = "arg$j";
- }
- if ($l == 0) {
- if (length($type) + length($pointer) > $type_len) {
- $type_len = length($type) + length($pointer);
- }
- if (length($param_name) > $name_len) {
- $name_len = length($param_name);
- }
- }
- else {
- $xref = &MakeXRef ($type, &tagify($type, "type"));
- $pad = ' ' x ($type_len - length($type) - length($pointer));
- $desc .= "$xref$pad $pointer${param_name},\n";
- $desc .= $indentation;
- }
- } else {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Can't parse arg: $params[$j]\nArgs:$SignalPrototypes[$i]");
- }
- }
- }
- $xref = &MakeXRef ("gpointer", &tagify("gpointer", "type"));
- $pad = ' ' x ($type_len - length("gpointer"));
- $desc .= "$xref$pad user_data)";
- $desc .= "</programlisting>\n";
-
- my $flags = $SignalFlags[$i];
- my $flags_string = "";
-
- if (defined ($flags)) {
- if ($flags =~ m/f/) {
- $flags_string = "<link linkend=\"G-SIGNAL-RUN-FIRST:CAPS\">Run First</link>";
- }
- elsif ($flags =~ m/l/) {
- $flags_string = "<link linkend=\"G-SIGNAL-RUN-LAST:CAPS\">Run Last</link>";
- }
- elsif ($flags =~ m/c/) {
- $flags_string = "<link linkend=\"G-SIGNAL-RUN-CLEANUP:CAPS\">Cleanup</link>";
- $flags_string = "Cleanup";
- }
- if ($flags =~ m/r/) {
- if ($flags_string) { $flags_string .= " / "; }
- $flags_string = "<link linkend=\"G-SIGNAL-NO-RECURSE:CAPS\">No Recursion</link>";
- }
- if ($flags =~ m/d/) {
- if ($flags_string) { $flags_string .= " / "; }
- $flags_string = "<link linkend=\"G-SIGNAL-DETAILED:CAPS\">Has Details</link>";
- }
- if ($flags =~ m/a/) {
- if ($flags_string) { $flags_string .= " / "; }
- $flags_string = "<link linkend=\"G-SIGNAL-ACTION:CAPS\">Action</link>";
- }
- if ($flags =~ m/h/) {
- if ($flags_string) { $flags_string .= " / "; }
- $flags_string = "<link linkend=\"G-SIGNAL-NO-HOOKS:CAPS\">No Hooks</link>";
- }
- }
-
- $synop .= "<row><entry role=\"signal_type\">${ret_type_output}</entry><entry role=\"signal_name\"><link linkend=\"$id\">${name}</link></entry><entry role=\"signal_flags\">${flags_string}</entry></row>\n";
-
- my $parameters = &OutputParamDescriptions ("SIGNAL", $symbol);
-
- $AllSymbols{$symbol} = 1;
- if (defined ($SymbolDocs{$symbol})) {
- my $symbol_docs = &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
-
- $desc .= $symbol_docs;
-
- if (!IsEmptyDoc($SymbolDocs{$symbol})) {
- $AllDocumentedSymbols{$symbol} = 1;
- }
- }
- if (defined ($SymbolAnnotations{$symbol})) {
- my $param_desc = $SymbolAnnotations{$symbol};
- my $param_annotations = "";
- ($param_desc,$param_annotations) = &ExpandAnnotation($symbol, $param_desc);
- if ($param_annotations ne "") {
- $desc .= "\n<para>$param_annotations</para>";
- }
- }
- $desc .= &MakeDeprecationNote($symbol);
-
- $desc .= $parameters;
- if ($flags_string) {
- $desc .= "<para>Flags: $flags_string</para>\n";
- }
- $desc .= OutputSymbolTraits ($symbol);
- $desc .= "</refsect2>";
- }
- }
- return ($synop, $desc);
-}
-
-
-#############################################################################
-# Function : GetArgs
-# Description : Returns the synopsis and detailed description DocBook output
-# for the Args of a given GtkObject subclass.
-# Arguments : $object - the GtkObject subclass, e.g. 'GtkButton'.
-#############################################################################
-
-sub GetArgs {
- my ($object) = @_;
- my $synop = "";
- my $desc = "";
- my $child_synop = "";
- my $child_desc = "";
- my $style_synop = "";
- my $style_desc = "";
-
- my $i;
- for ($i = 0; $i <= $#ArgObjects; $i++) {
- if ($ArgObjects[$i] eq $object) {
- @TRACE@("Found arg: $ArgNames[$i]\n");
- my $name = $ArgNames[$i];
- my $flags = $ArgFlags[$i];
- my $flags_string = "";
- my $kind = "";
- my $id_sep = "";
-
- if ($flags =~ m/c/) {
- $kind = "child property";
- $id_sep = "c-";
- }
- elsif ($flags =~ m/s/) {
- $kind = "style property";
- $id_sep = "s-";
- }
- else {
- $kind = "property";
- }
-
- # Remember only one colon so we don't clash with signals.
- my $symbol = "${object}:${name}";
- # use two dashes and ev. an extra separator here for the same reason.
- my $id = &CreateValidSGMLID ("$object--$id_sep$name");
-
- my $type = $ArgTypes[$i];
- my $type_output;
- my $range = $ArgRanges[$i];
- my $range_output = CreateValidSGML ($range);
- my $default = $ArgDefaults[$i];
- my $default_output = CreateValidSGML ($default);
-
- if ($type eq "GtkString") {
- $type = "char *";
- }
- if ($type eq "GtkSignal") {
- $type = "GtkSignalFunc, gpointer";
- $type_output = &MakeXRef ("GtkSignalFunc") . ", "
- . &MakeXRef ("gpointer");
- } elsif ($type =~ m/^(\w+)\*$/) {
- $type_output = &MakeXRef ($1, &tagify($1, "type")) . " *";
- } else {
- $type_output = &MakeXRef ($type, &tagify($type, "type"));
- }
-
- if ($flags =~ m/r/) {
- $flags_string = "Read";
- }
- if ($flags =~ m/w/) {
- if ($flags_string) { $flags_string .= " / "; }
- $flags_string .= "Write";
- }
- if ($flags =~ m/x/) {
- if ($flags_string) { $flags_string .= " / "; }
- $flags_string .= "Construct";
- }
- if ($flags =~ m/X/) {
- if ($flags_string) { $flags_string .= " / "; }
- $flags_string .= "Construct Only";
- }
-
- $AllSymbols{$symbol} = 1;
- my $blurb = "";
- if (defined($SymbolDocs{$symbol}) &&
- !IsEmptyDoc($SymbolDocs{$symbol})) {
- $blurb = &ConvertMarkDown($symbol, $SymbolDocs{$symbol});
- @TRACE@(".. [$SymbolDocs{$symbol}][$blurb]\n");
- $AllDocumentedSymbols{$symbol} = 1;
- }
- else {
- if ($ArgBlurbs[$i] ne "") {
- $blurb = "<para>" . &CreateValidSGML ($ArgBlurbs[$i]) . "</para>";
- $AllDocumentedSymbols{$symbol} = 1;
- } else {
- # FIXME: print a warning?
- @TRACE@(".. no description\n");
- }
- }
-
- my $pad1 = " " x (24 - length ($name));
-
- my $arg_synop = "<row><entry role=\"property_type\">$type_output</entry><entry role=\"property_name\"><link linkend=\"$id\">$name</link></entry><entry role=\"property_flags\">$flags_string</entry></row>\n";
- my $arg_desc = "<refsect2 id=\"$id\" role=\"property\"><title>The <literal>“$name”</literal> $kind</title>\n";
- $arg_desc .= MakeIndexterms($symbol, $id);
- $arg_desc .= "\n";
- $arg_desc .= OutputSymbolExtraLinks($symbol);
-
- $arg_desc .= "<programlisting> “$name”$pad1 $type_output</programlisting>\n";
- $arg_desc .= $blurb;
- if (defined ($SymbolAnnotations{$symbol})) {
- my $param_desc = $SymbolAnnotations{$symbol};
- my $param_annotations = "";
- ($param_desc,$param_annotations) = &ExpandAnnotation($symbol, $param_desc);
- if ($param_annotations ne "") {
- $arg_desc .= "\n<para>$param_annotations</para>";
- }
- }
- $arg_desc .= &MakeDeprecationNote($symbol);
-
- if ($flags_string) {
- $arg_desc .= "<para>Flags: $flags_string</para>\n";
- }
- if ($range ne "") {
- $arg_desc .= "<para>Allowed values: $range_output</para>\n";
- }
- if ($default ne "") {
- $arg_desc .= "<para>Default value: $default_output</para>\n";
- }
- $arg_desc .= OutputSymbolTraits ($symbol);
- $arg_desc .= "</refsect2>\n";
-
- if ($flags =~ m/c/) {
- $child_synop .= $arg_synop;
- $child_desc .= $arg_desc;
- }
- elsif ($flags =~ m/s/) {
- $style_synop .= $arg_synop;
- $style_desc .= $arg_desc;
- }
- else {
- $synop .= $arg_synop;
- $desc .= $arg_desc;
- }
- }
- }
- return ($synop, $child_synop, $style_synop, $desc, $child_desc, $style_desc);
-}
-
-
-#############################################################################
-# Function : ReadSourceDocumentation
-# Description : This reads in the documentation embedded in comment blocks
-# in the source code (for Gnome).
-#
-# Parameter descriptions override any in the template files.
-# Function descriptions are placed before any description from
-# the template files.
-#
-# It recursively descends the source directory looking for .c
-# files and scans them looking for specially-formatted comment
-# blocks.
-#
-# Arguments : $source_dir - the directory to scan.
-#############m###############################################################
-
-sub ReadSourceDocumentation {
- my ($source_dir) = @_;
- my ($file, $dir, @suffix_list, $suffix);
-
- # prepend entries from @SOURCE_DIR
- for my $dir (@SOURCE_DIRS) {
- # Check if the filename is in the ignore list.
- if ($source_dir =~ m%^\Q$dir\E/(.*)$% and $IGNORE_FILES =~ m/(\s|^)\Q$1\E(\s|$)/) {
- @TRACE@("Skipping source directory: $source_dir");
- return;
- } else {
- @TRACE@("No match for: ".($1 || $source_dir));
- }
- }
-
- @TRACE@("Scanning source directory: $source_dir");
-
- # This array holds any subdirectories found.
- my (@subdirs) = ();
-
- @suffix_list = split (/,/, $SOURCE_SUFFIXES);
-
- opendir (SRCDIR, $source_dir)
- || die "Can't open source directory $source_dir: $!";
-
- foreach $file (readdir (SRCDIR)) {
- if ($file =~ /^\./) {
- next;
- } elsif (-d "$source_dir/$file") {
- push (@subdirs, $file);
- } elsif (@suffix_list) {
- foreach $suffix (@suffix_list) {
- if ($file =~ m/\.\Q${suffix}\E$/) {
- &ScanSourceFile ("$source_dir/$file");
- }
- }
- } elsif ($file =~ m/\.[ch]$/) {
- &ScanSourceFile ("$source_dir/$file");
- }
- }
- closedir (SRCDIR);
-
- # Now recursively scan the subdirectories.
- foreach $dir (@subdirs) {
- &ReadSourceDocumentation ("$source_dir/$dir");
- }
-}
-
-
-#############################################################################
-# Function : ScanSourceFile
-# Description : Scans one source file looking for specially-formatted comment
-# blocks. Later &MergeSourceDocumentation is used to merge any
-# documentation found with the documentation already read in
-# from the template files.
-#
-# Arguments : $file - the file to scan.
-#############################################################################
-
-sub ScanSourceFile {
- my ($file) = @_;
- my $basename;
-
- # prepend entries from @SOURCE_DIR
- for my $dir (@SOURCE_DIRS) {
- # Check if the filename is in the ignore list.
- if ($file =~ m%^\Q$dir\E/(.*)$% and $IGNORE_FILES =~ m/(\s|^)\Q$1\E(\s|$)/) {
- @TRACE@("Skipping source file: $file");
- return;
- }
- }
-
- if ($file =~ m/^.*[\/\\]([^\/\\]*)$/) {
- $basename = $1;
- } else {
- &LogWarning ($file, 1, "Can't find basename for this filename.");
- $basename = $file;
- }
-
- # Check if the basename is in the list of files to ignore.
- if ($IGNORE_FILES =~ m/(\s|^)\Q${basename}\E(\s|$)/) {
- @TRACE@("Skipping source file: $file");
- return;
- }
-
- @TRACE@("Scanning source file: $file");
-
- open (SRCFILE, $file)
- || die "Can't open $file: $!";
- my $in_comment_block = 0;
- my $symbol;
- my $in_part = "";
- my ($description, $return_desc);
- my ($since_desc, $stability_desc, $deprecated_desc);
- my $current_param;
- my @params;
- while (<SRCFILE>) {
- # Look for the start of a comment block.
- if (!$in_comment_block) {
- if (m%^\s*/\*.*\*/%) {
- #one-line comment - not gtkdoc
- } elsif (m%^\s*/\*\*\s%) {
- @TRACE@("Found comment block start\n");
-
- $in_comment_block = 1;
-
- # Reset all the symbol data.
- $symbol = "";
- $in_part = "";
- $description = "";
- $return_desc = "";
- $since_desc = "";
- $deprecated_desc = "";
- $stability_desc = "";
- $current_param = -1;
- @params = ();
- }
- next;
- }
-
- # We're in a comment block. Check if we've found the end of it.
- if (m%^\s*\*+/%) {
- if (!$symbol) {
- # maybe its not even meant to be a gtk-doc comment?
- &LogWarning ($file, $., "Symbol name not found at the start of the comment block.");
- } else {
- # Add the return value description onto the end of the params.
- if ($return_desc) {
- # TODO(ensonic): check for duplicated Return docs
- # &LogWarning ($file, $., "Multiple Returns for $symbol.");
- push (@params, "Returns");
- push (@params, $return_desc);
- }
- # Convert special characters
- $description = &ConvertSGMLChars ($symbol, $description);
- my $k;
- for ($k = 1; $k <= $#params; $k += $PARAM_FIELD_COUNT) {
- $params[$k] = &ConvertSGMLChars ($symbol, $params[$k]);
- }
-
- # Handle Section docs
- if ($symbol =~ m/SECTION:\s*(.*)/) {
- my $real_symbol=$1;
- my $key;
-
- if (scalar %KnownSymbols) {
- if ((! defined($KnownSymbols{"$TMPL_DIR/$real_symbol:Long_Description"})) || $KnownSymbols{"$TMPL_DIR/$real_symbol:Long_Description"} != 1) {
- &LogWarning ($file, $., "Section $real_symbol is not defined in the $MODULE-sections.txt file.");
- }
- }
-
- @TRACE@("SECTION DOCS found in source for : '$real_symbol'\n");
- for ($k = 0; $k <= $#params; $k += $PARAM_FIELD_COUNT) {
- @TRACE@(" '".$params[$k]."'\n");
- $params[$k] = "\L$params[$k]";
- undef $key;
- if ($params[$k] eq "short_description") {
- $key = "$TMPL_DIR/$real_symbol:Short_Description";
- } elsif ($params[$k] eq "see_also") {
- $key = "$TMPL_DIR/$real_symbol:See_Also";
- } elsif ($params[$k] eq "title") {
- $key = "$TMPL_DIR/$real_symbol:Title";
- } elsif ($params[$k] eq "stability") {
- $key = "$TMPL_DIR/$real_symbol:Stability_Level";
- } elsif ($params[$k] eq "section_id") {
- $key = "$TMPL_DIR/$real_symbol:Section_Id";
- } elsif ($params[$k] eq "include") {
- $key = "$TMPL_DIR/$real_symbol:Include";
- } elsif ($params[$k] eq "image") {
- $key = "$TMPL_DIR/$real_symbol:Image";
- }
- if (defined($key)) {
- $SourceSymbolDocs{$key}=$params[$k+1];
- $SourceSymbolSourceFile{$key} = $file;
- $SourceSymbolSourceLine{$key} = $.;
- }
- }
- $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Long_Description"}=$description;
- $SourceSymbolSourceFile{"$TMPL_DIR/$real_symbol:Long_Description"} = $file;
- $SourceSymbolSourceLine{"$TMPL_DIR/$real_symbol:Long_Description"} = $.;
- #$SourceSymbolTypes{$symbol} = "SECTION";
- } else {
- @TRACE@("SYMBOL DOCS found in source for : '$symbol' ",length($description), "\n");
- $SourceSymbolDocs{$symbol} = $description;
- $SourceSymbolParams{$symbol} = [ @params ];
- # FIXME $SourceSymbolTypes{$symbol} = "STRUCT,SIGNAL,ARG,FUNCTION,MACRO";
- #if (defined $DeclarationTypes{$symbol}) {
- # $SourceSymbolTypes{$symbol} = $DeclarationTypes{$symbol}
- #}
- $SourceSymbolSourceFile{$symbol} = $file;
- $SourceSymbolSourceLine{$symbol} = $.;
- }
-
- if ($since_desc) {
- ($since_desc, my @extra_lines) = split ("\n", $since_desc);
- $since_desc =~ s/^\s+//;
- $since_desc =~ s/\s+$//;
- @TRACE@("Since($symbol) : [$since_desc]\n");
- $Since{$symbol} = &ConvertSGMLChars ($symbol, $since_desc);
- if(scalar @extra_lines) {
- &LogWarning ($file, $., "multi-line since docs found");
- }
- }
-
- if ($stability_desc) {
- $stability_desc = &ParseStabilityLevel($stability_desc, $file, $., "Stability level for $symbol");
- $StabilityLevel{$symbol} = &ConvertSGMLChars ($symbol, $stability_desc);
- }
-
- if ($deprecated_desc) {
- if (!exists $Deprecated{$symbol}) {
- # don't warn for signals and properties
- #if ($symbol !~ m/::?(.*)/) {
- if (defined $DeclarationTypes{$symbol}) {
- &LogWarning ($file, $.,
- "$symbol is deprecated in the inline comments, but no deprecation guards were found around the declaration.".
- " (See the --deprecated-guards option for gtkdoc-scan.)");
- }
- }
- $Deprecated{$symbol} = &ConvertSGMLChars ($symbol, $deprecated_desc);
- }
- }
-
- $in_comment_block = 0;
- next;
- }
-
- # Get rid of ' * ' at start of every line in the comment block.
- s%^\s*\*\s?%%;
- # But make sure we don't get rid of the newline at the end.
- if (!$_) {
- $_ = "\n";
- }
- @TRACE@("scanning :$_");
-
- # If we haven't found the symbol name yet, look for it.
- if (!$symbol) {
- if (m%^\s*(SECTION:\s*\S+)%) {
- $symbol = $1;
- @TRACE@("SECTION DOCS found in source for : '$symbol'\n");
- } elsif (m%^\s*([\w:-]*\w)\s*:?\s*(\([-A-Za-z0-9._() ]+?\)\s*)*$%) {
- $symbol = $1;
- my $annotation = $2;
- @TRACE@("SYMBOL DOCS found in source for : '$symbol'\n");
- if (defined($annotation)) {
- chomp($annotation);
- if ($annotation ne "") {
- $SymbolAnnotations{$symbol} = $annotation;
- @TRACE@("remaining text for $symbol: '$annotation'\n");
- }
- }
- }
- next;
- }
-
- if ($in_part eq "description") {
- # Get rid of 'Description:'
- s%^\s*Description:%%;
- }
-
- if (m%^\s*(returns|return\s+value):%i) {
- # we're in param section and have not seen the blank line
- if($in_part ne "") {
- $return_desc = $';
- $in_part = "return";
- next;
- }
- } elsif (m%^\s*since:%i) {
- # we're in param section and have not seen the blank line
- if($in_part ne "param") {
- $since_desc = $';
- $in_part = "since";
- next;
- }
- } elsif (m%^\s*deprecated:%i) {
- # we're in param section and have not seen the blank line
- if($in_part ne "param") {
- $deprecated_desc = $';
- $in_part = "deprecated";
- next;
- }
- } elsif (m%^\s*stability:%i) {
- $stability_desc = $';
- $in_part = "stability";
- next;
- }
-
- if ($in_part eq "description") {
- $description .= $_;
- next;
- } elsif ($in_part eq "return") {
- $return_desc .= $_;
- next;
- } elsif ($in_part eq "since") {
- $since_desc .= $_;
- next;
- } elsif ($in_part eq "stability") {
- $stability_desc .= $_;
- next;
- } elsif ($in_part eq "deprecated") {
- $deprecated_desc .= $_;
- next;
- }
-
- # We must be in the parameters. Check for the empty line below them.
- if (m%^\s*$%) {
- $in_part = "description";
- next;
- }
-
- # Look for a parameter name.
- if (m%^\s*@(\S+)\s*:\s*%) {
- my $param_name = $1;
- my $param_desc = $';
-
- @TRACE@("Found parameter: $param_name\n");
- # Allow varargs variations
- if ($param_name =~ m/^\.\.\.$/) {
- $param_name = "...";
- }
- @TRACE@("Found param for symbol $symbol : '$param_name'= '$_'");
-
- push (@params, $param_name);
- push (@params, $param_desc);
- $current_param += $PARAM_FIELD_COUNT;
- $in_part = "param";
- next;
- } elsif ($in_part eq "") {
- @TRACE@("continuation for $symbol annotation '$_'");
- my $annotation = $_;
- $annotation =~ s/^\s+|\s+$//g ;
- $SymbolAnnotations{$symbol} .= $annotation;
- next;
- }
-
- # We must be in the middle of a parameter description, so add it on
- # to the last element in @params.
- if ($current_param == -1) {
- &LogWarning ($file, $., "Parsing comment block file : parameter expected, but got '$_'");
- } else {
- $params[$#params] .= $_;
- }
- }
- close (SRCFILE);
-}
-
-#############################################################################
-# Function : OutputMissingDocumentation
-# Description : Outputs report of documentation coverage to a file
-#
-# Arguments : none
-#############################################################################
-
-sub OutputMissingDocumentation {
- my $old_undocumented_file = "$ROOT_DIR/$MODULE-undocumented.txt";
- my $new_undocumented_file = "$ROOT_DIR/$MODULE-undocumented.new";
-
- my $n_documented = 0;
- my $n_incomplete = 0;
- my $total = 0;
- my $symbol;
- my $percent;
- my $msg;
- my $buffer = "";
- my $buffer_deprecated = "";
- my $buffer_descriptions = "";
-
- open(UNDOCUMENTED, ">$new_undocumented_file")
- || die "Can't create $new_undocumented_file";
-
- foreach $symbol (sort (keys (%AllSymbols))) {
- # FIXME: should we print LogWarnings for undocumented stuff?
- # DEBUG
- #my $ssfile = &GetSymbolSourceFile($symbol);
- #my $ssline = &GetSymbolSourceLine($symbol);
- #my $location = "defined at " . (defined($ssfile)?$ssfile:"?") . ":" . (defined($ssline)?$ssline:"0") . "\n";
- # DEBUG
- if ($symbol !~ /:(Title|Long_Description|Short_Description|See_Also|Stability_Level|Include|Section_Id|Image)/) {
- $total++;
- if (exists ($AllDocumentedSymbols{$symbol})) {
- $n_documented++;
- if (exists ($AllIncompleteSymbols{$symbol})) {
- $n_incomplete++;
- $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
- #$buffer .= "\t0: ".$location;
- }
- } elsif (exists $Deprecated{$symbol}) {
- if (exists ($AllIncompleteSymbols{$symbol})) {
- $n_incomplete++;
- $buffer_deprecated .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
- #$buffer .= "\t1a: ".$location;
- } else {
- $buffer_deprecated .= $symbol . "\n";
- #$buffer .= "\t1b: ".$location;
- }
- } else {
- if (exists ($AllIncompleteSymbols{$symbol})) {
- $n_incomplete++;
- $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n";
- #$buffer .= "\t2a: ".$location;
- } else {
- $buffer .= $symbol . "\n";
- #$buffer .= "\t2b: ".$location;
- }
- }
- } elsif ($symbol =~ /:(Long_Description|Short_Description)/) {
- $total++;
- if (((exists ($SymbolDocs{$symbol})) && (length ($SymbolDocs{$symbol}) > 0))
- || ((exists ($AllDocumentedSymbols{$symbol})) && (length ($AllDocumentedSymbols{$symbol}) > 0))) {
- $n_documented++;
- } else {
- # cut off the leading namespace ($TMPL_DIR)
- $symbol =~ m/^.*\/(.*)$/;
- $buffer_descriptions .= $1 . "\n";
- }
- }
- }
-
- if ($total == 0) {
- $percent = 100;
- } else {
- $percent = ($n_documented / $total) * 100.0;
- }
-
- printf UNDOCUMENTED "%.0f%% symbol docs coverage.\n", $percent;
- print UNDOCUMENTED "$n_documented symbols documented.\n";
- print UNDOCUMENTED "$n_incomplete symbols incomplete.\n";
- print UNDOCUMENTED ($total - $n_documented) . " not documented.\n";
-
- if ($buffer_deprecated ne "") {
- $buffer .= "\n" . $buffer_deprecated;
- }
- if ($buffer_descriptions ne "") {
- $buffer .= "\n" . $buffer_descriptions;
- }
- if ($buffer ne "") {
- print UNDOCUMENTED "\n\n$buffer";
- }
- close (UNDOCUMENTED);
-
- return &UpdateFileIfChanged ($old_undocumented_file, $new_undocumented_file, 0);
-
- printf "%.0f%% symbol docs coverage", $percent;
- print "($n_documented symbols documented, $n_incomplete symbols incomplete, " . ($total - $n_documented) . " not documented)\n";
- print "See $MODULE-undocumented.txt for a list of missing docs.\nThe doc coverage percentage doesn't include intro sections.\n";
-}
-
-
-#############################################################################
-# Function : OutputUndeclaredSymbols
-# Description : Outputs symbols that are listed in the section file, but not
-# declaration is found in the sources
-#
-# Arguments : none
-#############################################################################
-
-sub OutputUndeclaredSymbols {
- my $old_undeclared_file = "$ROOT_DIR/$MODULE-undeclared.txt";
- my $new_undeclared_file = "$ROOT_DIR/$MODULE-undeclared.new";
-
- open(UNDECLARED, ">$new_undeclared_file")
- || die "Can't create $new_undeclared_file";
-
- if (%UndeclaredSymbols) {
- print UNDECLARED (join("\n", sort keys %UndeclaredSymbols));
- print UNDECLARED "\n";
- print "See $MODULE-undeclared.txt for the list of undeclared symbols.\n"
- }
- close(UNDECLARED);
-
- return &UpdateFileIfChanged ($old_undeclared_file, $new_undeclared_file, 0);
-}
-
-#############################################################################
-# Function : OutputUnusedSymbols
-# Description : Outputs symbols that are documented in comments, but not
-# declared in the sources
-#
-# Arguments : none
-#############################################################################
-
-sub OutputUnusedSymbols {
- my $num_unused = 0;
- my $old_unused_file = "$ROOT_DIR/$MODULE-unused.txt";
- my $new_unused_file = "$ROOT_DIR/$MODULE-unused.new";
-
- open (UNUSED, ">$new_unused_file")
- || die "Can't open $new_unused_file";
- my ($symbol);
- foreach $symbol (sort keys (%Declarations)) {
- if (!defined ($DeclarationOutput{$symbol})) {
- print (UNUSED "$symbol\n");
- $num_unused++;
- }
- }
- foreach $symbol (sort (keys (%AllUnusedSymbols))) {
- print (UNUSED "$symbol(" . $AllUnusedSymbols{$symbol} . ")\n");
- $num_unused++;
- }
- close (UNUSED);
- if ($num_unused != 0) {
- &LogWarning ($old_unused_file, 1, "$num_unused unused declarations.".
- "They should be added to $MODULE-sections.txt in the appropriate place.");
- }
-
- return &UpdateFileIfChanged ($old_unused_file, $new_unused_file, 0);
-}
-
-
-#############################################################################
-# Function : OutputAllSymbols
-# Description : Outputs list of all symbols to a file
-#
-# Arguments : none
-#############################################################################
-
-sub OutputAllSymbols {
- my $n_documented = 0;
- my $total = 0;
- my $symbol;
- my $percent;
- my $msg;
-
- open (SYMBOLS, ">$ROOT_DIR/$MODULE-symbols.txt")
- || die "Can't create $ROOT_DIR/$MODULE-symbols.txt: $!";
-
- foreach $symbol (sort (keys (%AllSymbols))) {
- print SYMBOLS $symbol . "\n";
- }
-
- close (SYMBOLS);
-}
-
-#############################################################################
-# Function : OutputSymbolsWithoutSince
-# Description : Outputs list of all symbols without a since tag to a file
-#
-# Arguments : none
-#############################################################################
-
-sub OutputSymbolsWithoutSince {
- my $n_documented = 0;
- my $total = 0;
- my $symbol;
- my $percent;
- my $msg;
-
- open (SYMBOLS, ">$ROOT_DIR/$MODULE-nosince.txt")
- || die "Can't create $ROOT_DIR/$MODULE-nosince.txt: $!";
-
- foreach $symbol (sort (keys (%SourceSymbolDocs))) {
- if (!defined $Since{$symbol}) {
- print SYMBOLS $symbol . "\n";
- }
- }
-
- close (SYMBOLS);
-}
-
-
-#############################################################################
-# Function : MergeSourceDocumentation
-# Description : This merges documentation read from a source file into the
-# documentation read in from a template file.
-#
-# Parameter descriptions override any in the template files.
-# Function descriptions are placed before any description from
-# the template files.
-#
-# Arguments : none
-#############################################################################
-
-sub MergeSourceDocumentation {
- my $symbol;
- my @Symbols;
-
- if (scalar %SymbolDocs) {
- @Symbols=keys (%SymbolDocs);
- @TRACE@("num existing entries: ".(scalar @Symbols)."\n");
- }
- else {
- # filter scanned declarations, with what we suppress from -sections.txt
- my %tmp = ();
- foreach $symbol (keys (%Declarations)) {
- if (defined($KnownSymbols{$symbol}) && $KnownSymbols{$symbol} == 1) {
- $tmp{$symbol}=1;
- }
- }
- # , add the rest from -sections.txt
- foreach $symbol (keys (%KnownSymbols)) {
- if ($KnownSymbols{$symbol} == 1) {
- $tmp{$symbol}=1;
- }
- }
- # and add whats found in the source
- foreach $symbol (keys (%SourceSymbolDocs)) {
- $tmp{$symbol}=1;
- }
- @Symbols = keys (%tmp);
- @TRACE@("num source entries: ".(scalar @Symbols)."\n");
- }
- foreach $symbol (@Symbols) {
- $AllSymbols{$symbol} = 1;
-
- my $have_tmpl_docs = 0;
-
- ## see if the symbol is documented in template
- my $tmpl_doc = defined ($SymbolDocs{$symbol}) ? $SymbolDocs{$symbol} : "";
- my $check_tmpl_doc =$tmpl_doc;
- # remove all xml-tags and whitespaces
- $check_tmpl_doc =~ s/<.*?>//g;
- $check_tmpl_doc =~ s/\s//g;
- # anything left ?
- if ($check_tmpl_doc ne "") {
- $have_tmpl_docs = 1;
- } else {
- # if the docs have just an empty para, don't merge that.
- $check_tmpl_doc = $tmpl_doc;
- $check_tmpl_doc =~ s/(\s|\n)//msg;
- if ($check_tmpl_doc eq "<para></para>") {
- $tmpl_doc = "";
- }
- }
-
- if (exists ($SourceSymbolDocs{$symbol})) {
- my $type = $DeclarationTypes {$symbol};
-
- @TRACE@("merging [$symbol] from source\n");
-
- my $item = "Parameter";
- if (defined ($type)) {
- if ($type eq 'STRUCT') {
- $item = "Field";
- } elsif ($type eq 'ENUM') {
- $item = "Value";
- } elsif ($type eq 'UNION') {
- $item = "Field";
- }
- } else {
- $type="SIGNAL";
- }
-
- my $src_doc = $SourceSymbolDocs{$symbol};
- # remove leading and training whitespaces
- $src_doc =~ s/^\s+//;
- $src_doc =~ s/\s+$//;
-
- # Don't output warnings for overridden titles as titles are
- # automatically generated in the -sections.txt file, and thus they
- # are often overridden.
- if ($have_tmpl_docs && $symbol !~ m/:Title$/) {
- # check if content is different
- if ($tmpl_doc ne $src_doc) {
- #print "[$tmpl_doc] [$src_doc]\n";
- &LogWarning ($SourceSymbolSourceFile{$symbol}, $SourceSymbolSourceLine{$symbol},
- "Documentation in template ".$SymbolSourceFile{$symbol}.":".$SymbolSourceLine{$symbol}." for $symbol being overridden by inline comments.");
- }
- }
-
- if ($src_doc ne "") {
- $AllDocumentedSymbols{$symbol} = 1;
- }
-
- # Do not add <para> to nothing, it breaks missing docs checks.
- my $src_doc_para = "";
- if ($src_doc ne "") {
- $src_doc_para = $src_doc;
- }
-
- if ($symbol =~ m/$TMPL_DIR\/.+:Long_Description/) {
- $SymbolDocs{$symbol} = "$src_doc_para$tmpl_doc";
- } elsif ($symbol =~ m/$TMPL_DIR\/.+:.+/) {
- # For the title/summary/see also section docs we don't want to
- # add any <para> tags.
- $SymbolDocs{$symbol} = "$src_doc"
- } else {
- $SymbolDocs{$symbol} = "$src_doc_para$tmpl_doc";
- }
-
- # merge parameters
- if ($symbol =~ m/.*::.*/) {
- # For signals we prefer the param names from the source docs,
- # since the ones from the templates are likely to contain the
- # artificial argn names which are generated by gtkdoc-scangobj.
- $SymbolParams{$symbol} = $SourceSymbolParams{$symbol};
- # FIXME: we need to check for empty docs here as well!
- } else {
- # The templates contain the definitive parameter names and order,
- # so we will not change that. We only override the actual text.
- my $tmpl_params = $SymbolParams{$symbol};
- if (!defined ($tmpl_params)) {
- @TRACE@("No merge needed for $symbol\n");
- $SymbolParams{$symbol} = $SourceSymbolParams{$symbol};
- # FIXME: we still like to get the number of params and merge
- # 1) we would noticed that params have been removed/renamed
- # 2) we would catch undocumented params
- # params are not (yet) exported in -decl.txt so that we
- # could easily grab them :/
- } else {
- my $params = $SourceSymbolParams{$symbol};
- my $j;
- @TRACE@("Merge needed for $symbol, tmpl_params: ",$#$tmpl_params,", source_params: ",$#$params," \n");
- for ($j = 0; $j <= $#$tmpl_params; $j += $PARAM_FIELD_COUNT) {
- my $tmpl_param_name = $$tmpl_params[$j];
-
- # Try to find the param in the source comment documentation.
- my $found = 0;
- my $k;
- @TRACE@(" try merge param $tmpl_param_name\n");
- for ($k = 0; $k <= $#$params; $k += $PARAM_FIELD_COUNT) {
- my $param_name = $$params[$k];
- my $param_desc = $$params[$k + 1];
-
- @TRACE@(" test param $param_name\n");
- # We accept changes in case, since the Gnome source
- # docs contain a lot of these.
- if ("\L$param_name" eq "\L$tmpl_param_name") {
- $found = 1;
-
- # Override the description.
- $$tmpl_params[$j + 1] = $param_desc;
-
- # Set the name to "" to mark it as used.
- $$params[$k] = "";
- last;
- }
- }
-
- # If it looks like the parameters are there, but not
- # in the right place, try to explain a bit better.
- if ((!$found) && ($src_doc =~ m/\@$tmpl_param_name:/)) {
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "Parameters for $symbol must start on the line immediately after the function or macro name.");
- }
- }
-
- # Now we output a warning if parameters have been described which
- # do not exist.
- for ($j = 0; $j <= $#$params; $j += $PARAM_FIELD_COUNT) {
- my $param_name = $$params[$j];
- if ($param_name) {
- # the template builder cannot detect if a macro returns
- # a result or not
- if(($type eq "MACRO") && ($param_name eq "Returns")) {
- # FIXME: do we need to add it then to tmpl_params[] ?
- my $num=$#$tmpl_params;
- @TRACE@(" adding Returns: to macro docs for $symbol.\n");
- $$tmpl_params[$num+1]="Returns";
- $$tmpl_params[$num+2]=$$params[$j+1];
- next;
- }
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "$item described in source code comment block but does not exist. $type: $symbol $item: $param_name.");
- }
- }
- }
- }
- } else {
- if ($have_tmpl_docs) {
- $AllDocumentedSymbols{$symbol} = 1;
- @TRACE@("merging [$symbol] from template\n");
- }
- else {
- @TRACE@("[$symbol] undocumented\n");
- }
- }
-
- # if this symbol is documented, check if docs are complete
- $check_tmpl_doc = defined ($SymbolDocs{$symbol}) ? $SymbolDocs{$symbol} : "";
- # remove all xml-tags and whitespaces
- $check_tmpl_doc =~ s/<.*?>//g;
- $check_tmpl_doc =~ s/\s//g;
- if ($check_tmpl_doc ne "") {
- my $tmpl_params = $SymbolParams{$symbol};
- if (defined ($tmpl_params)) {
- my $type = $DeclarationTypes {$symbol};
-
- my $item = "Parameter";
- if (defined ($type)) {
- if ($type eq 'STRUCT') {
- $item = "Field";
- } elsif ($type eq 'ENUM') {
- $item = "Value";
- } elsif ($type eq 'UNION') {
- $item = "Field";
- }
- } else {
- $type="SIGNAL";
- }
-
- @TRACE@("Check param docs for $symbol, tmpl_params: ",$#$tmpl_params," entries, type=$type\n");
-
- if ($#$tmpl_params > 0) {
- my $j;
- for ($j = 0; $j <= $#$tmpl_params; $j += $PARAM_FIELD_COUNT) {
- # Output a warning if the parameter is empty and
- # remember for stats.
- my $tmpl_param_name = $$tmpl_params[$j];
- my $tmpl_param_desc = $$tmpl_params[$j + 1];
- if ($tmpl_param_name ne "void" && $tmpl_param_desc !~ m/\S/) {
- if (exists ($AllIncompleteSymbols{$symbol})) {
- $AllIncompleteSymbols{$symbol}.=", ".$tmpl_param_name;
- } else {
- $AllIncompleteSymbols{$symbol}=$tmpl_param_name;
- }
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "$item description for $symbol"."::"."$tmpl_param_name is missing in source code comment block.");
- }
- }
- }
- else {
- if ($#$tmpl_params == 0) {
- $AllIncompleteSymbols{$symbol}="<items>";
- &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
- "$item descriptions for $symbol are missing in source code comment block.");
- }
- # $#$tmpl_params==-1 means we don't know about parameters
- # this unfortunately does not tell if there should be some
- }
- }
- }
- }
- @TRACE@("num doc entries: ".(scalar %SymbolDocs)."\n");
-}
-
-#############################################################################
-# Function : IsEmptyDoc
-# Description : Check if a doc-string is empty. Its also regarded as empty if
-# it only consist of whitespace or e.g. FIXME.
-# Arguments : the doc-string
-#############################################################################
-sub IsEmptyDoc {
- my ($doc) = @_;
-
- if ($doc =~ /^\s*$/) {
- return 1;
- }
-
- if ($doc =~ /^\s*<para>\s*(FIXME)?\s*<\/para>\s*$/) {
- return 1;
- }
-
- return 0;
-}
-
-#############################################################################
-# Function : ConvertMarkDown
-# Description : Converts mark down syntax to the respective docbook.
-# http://de.wikipedia.org/wiki/Markdown
-# Inspired by the design of ParseDown
-# http://parsedown.org/
-# Copyright (c) 2013 Emanuil Rusev, erusev.com
-# Arguments : the symbol name, the doc-string
-#############################################################################
-
-sub ConvertMarkDown {
- my ($symbol, $text) = @_;
-
- $text = &MarkDownParse ($text, $symbol);
-
- return $text
-}
-
-# SUPPORTED MARKDOWN
-# ==================
-#
-# Atx-style Headers
-# -----------------
-#
-# # Header 1
-#
-# ## Header 2 ##
-#
-# Setext-style Headers
-# --------------------
-#
-# Header 1
-# ========
-#
-# Header 2
-# --------
-#
-# Ordered (unnested) Lists
-# ------------------------
-#
-# 1. item 1
-#
-# 1. item 2 with loooong
-# description
-#
-# 3. item 3
-#
-# Note: we require a blank line above the list items
-#
-
-# TODO(ensonic): it would be nice to add id parameters to the refsect2 elements
-
-sub MarkDownParseBlocks {
- my ($linesref, $symbol, $context) = @_;
- my $line;
- my @md_blocks = ();
- my $md_block = { type => "" };
-
- OUTER: foreach $line (@$linesref) {
- my $first_char = substr ($line, 0, 1);
- my $deindented_line;
-
- @TRACE@("in '".$md_block->{"type"}."' state, parsing '$line'");
-
- if ($md_block->{"type"} eq "markup") {
- if (!$md_block->{"closed"}) {
- if (index ($line, $md_block->{"start"}) != -1) {
- $md_block->{"depth"}++;
- }
- if (index ($line, $md_block->{"end"}) != -1) {
- if ($md_block->{"depth"} > 0) {
- $md_block->{"depth"}--;
- } else {
- @TRACE@("closing tag '$line'");
- $md_block->{"closed"} = 1;
- # TODO(ensonic): reparse inner text with MarkDownParseLines?
- }
- }
- $md_block->{"text"} .= "\n" . $line;
- @TRACE@("add to markup");
- next OUTER;
- }
- }
-
- $deindented_line = $line;
- $deindented_line =~ s/^\s+//;
-
- if ($md_block->{"type"} eq "heading") {
- # a heading is ended by any level less than or equal
- if ($md_block->{"level"} == 1) {
- if ($line =~ /^={4,}[ \t]*$/) {
- my $text = pop @{$md_block->{"lines"}};
- $md_block->{"interrupted"} = 0;
- push @md_blocks, $md_block;
-
- $md_block = { type => "heading",
- text => $text,
- lines => [],
- level => 1 };
- next OUTER;
- } elsif ($line =~ /^[#][ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$/) {
- $md_block->{"interrupted"} = 0;
- push @md_blocks, $md_block;
-
- $md_block = { type => "heading",
- text => $1,
- id => $2,
- lines => [],
- level => 1 };
- next OUTER;
- } else {
- # push lines into the block until the end is reached
- push @{$md_block->{"lines"}}, $line;
- next OUTER;
- }
- } else {
- if ($line =~ /^[=]{4,}[ \t]*$/) {
- my $text = pop @{$md_block->{"lines"}};
- $md_block->{"interrupted"} = 0;
- push @md_blocks, $md_block;
-
- $md_block = { type => "heading",
- text => $text,
- lines => [],
- level => 1 };
- next OUTER;
- } elsif ($line =~ /^[-]{4,}[ \t]*$/) {
- my $text = pop @{$md_block->{"lines"}};
- $md_block->{"interrupted"} = 0;
- push @md_blocks, $md_block;
-
- $md_block = { type => "heading",
- text => $text,
- lines => [],
- level => 2 };
- next OUTER;
- } elsif ($line =~ /^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$/) {
- $md_block->{"interrupted"} = 0;
- push @md_blocks, $md_block;
-
- $md_block = { type => "heading",
- text => $2,
- id => $3,
- lines => [],
- level => length($1) };
- next OUTER;
- } else {
- # push lines into the block until the end is reached
- push @{$md_block->{"lines"}}, $line;
- next OUTER;
- }
- }
- } elsif ($md_block->{"type"} eq "code") {
- if ($line =~ /^[ \t]*\]\|(.*)/) {
- push @md_blocks, $md_block;
- $md_block = { type => "paragraph",
- text => "$1",
- lines => [] };
- } else {
- push @{$md_block->{"lines"}}, $line;
- }
- next OUTER;
- }
-
- if ($deindented_line eq "") {
- $md_block->{"interrupted"} = 1;
- next;
- }
-
- if ($md_block->{"type"} eq "quote") {
- if (!$md_block->{"interrupted"}) {
- $line =~ s/^[ ]*>[ ]?//;
- push @{$md_block->{"lines"}}, $line;
- next OUTER;
- }
- } elsif ($md_block->{"type"} eq "li") {
- my $marker = $md_block->{"marker"};
- if ($line =~ /^([ ]{0,3})($marker)[ ](.*)/) {
- my $indentation = $1;
- if ($md_block->{"indentation"} ne $indentation) {
- push @{$md_block->{"lines"}}, $line;
- } else {
- my $lines = $3;
- my $ordered = $md_block->{"ordered"};
- $lines =~ s/^[ ]{0,4}//;
- $md_block->{"last"} = 0;
- push @md_blocks, $md_block;
- $md_block = { type => "li",
- ordered => $ordered,
- indentation => $indentation,
- marker => $marker,
- first => 0,
- last => 1,
- lines => [ $lines ] };
- }
- next OUTER;
- }
-
- if ($md_block->{"interrupted"}) {
- if ($first_char eq " ") {
- push @{$md_block->{"lines"}}, "";
- $line =~ s/^[ ]{0,4}//;
- push @{$md_block->{"lines"}}, $line;
- $md_block->{"interrupted"} = 0;
- next OUTER;
- }
- } else {
- $line =~ s/^[ ]{0,4}//;
- push @{$md_block->{"lines"}}, $line;
- next OUTER;
- }
- }
-
- # indentation sensitive types
- @TRACE@("parsing '$line'");
-
- if ($line =~ /^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$/) {
- # atx heading (#)
- push @md_blocks, $md_block;
-
- $md_block = { type => "heading",
- text => $2,
- id => $3,
- lines => [],
- level => length($1) };
-
- next OUTER;
- } elsif ($line =~ /^={4,}[ \t]*$/) {
- # setext heading (====)
-
- if ($md_block->{"type"} eq "paragraph" && $md_block->{"interrupted"}) {
- push @md_blocks, $md_block;
- $md_block->{"type"} = "heading";
- $md_block->{"lines"} = [];
- $md_block->{"level"} = 1;
- }
-
- next OUTER;
- } elsif ($line =~ /^-{4,}[ \t]*$/) {
- # setext heading (-----)
-
- if ($md_block->{"type"} eq "paragraph" && $md_block->{"interrupted"}) {
- push @md_blocks, $md_block;
- $md_block->{"type"} = "heading";
- $md_block->{"lines"} = [];
- $md_block->{"level"} = 2;
- }
-
- next OUTER;
- } elsif ($line =~ /^[ \t]*\|\[[ ]*(?:<!-- language="([^"]+?)" -->)?/) {
- # code
- $md_block->{"interrupted"} = 1;
- push @md_blocks, $md_block;
- $md_block = { type => "code",
- language => $1,
- lines => [] };
- next OUTER;
- }
-
- # indentation insensitive types
- if ($line =~ /^[ ]*<!DOCTYPE/) {
- push @md_blocks, $md_block;
-
- $md_block = { type => "markup",
- text => $deindented_line,
- start => "<",
- end => ">",
- closed => 0,
- depth => 0 };
-
- } elsif ($line =~ /^[ ]*<\??(\w+)[^>]*([\/\?])?[ \t]*>/) {
- # markup, including <?xml version="1.0"?>
- my $tag = $1;
- my $is_self_closing = defined($2);
-
- # skip link markdown
- # TODO(ensonic): consider adding more uri schemes (ftp, ...)
- if ($tag =~ /^https?/) {
- @TRACE@("skipping link '$tag'");
- } else {
- # for TEXT_LEVEL_ELEMENTS, we want to keep them as-is in the paragraph
- # instead of creation a markdown block.
- my $scanning_for_end_of_text_level_tag = (
- $md_block->{"type"} eq "paragraph" &&
- defined($md_block->{"start"}) &&
- !$md_block->{"closed"});
- @TRACE@("markup found '$tag', scanning $scanning_for_end_of_text_level_tag ?");
- if (!$MD_TEXT_LEVEL_ELEMENTS{$tag} && !$scanning_for_end_of_text_level_tag) {
- push @md_blocks, $md_block;
-
- if ($is_self_closing) {
- @TRACE@("self-closing docbook '$tag'");
- $md_block = { type => "self-closing tag",
- text => $deindented_line };
- $is_self_closing = 0;
- next OUTER;
- }
-
- @TRACE@("new markup '$tag'");
- $md_block = { type => "markup",
- text => $deindented_line,
- start => "<" . $tag . ">",
- end => "</" . $tag . ">",
- closed => 0,
- depth => 0 };
- if ($deindented_line =~ /<\/$tag>/) {
- $md_block->{"closed"} = 1;
- }
- next OUTER;
- } else {
- if ($MD_TEXT_LEVEL_ELEMENTS{$tag}) {
- @TRACE@("text level docbook '$tag' in '".$md_block->{"type"}."' state");
- # TODO(ensonic): handle nesting
- if (!$scanning_for_end_of_text_level_tag) {
- if ($deindented_line !~ /<\/$tag>/) {
- @TRACE@("new text level markup '$tag'");
- $md_block->{"start"} = "<" . $tag . ">";
- $md_block->{"end"} = "</" . $tag . ">";
- $md_block->{"closed"} = 0;
- @TRACE@("scanning for end of '$tag'");
- }
- } else {
- if ($deindented_line =~ /$md_block->{"end"}/) {
- $md_block->{"closed"} = 1;
- @TRACE@("found end of '$tag'");
- }
- }
- }
- }
- }
- } elsif ($line =~ /^([ ]*)[*+-][ ](.*)/) {
- # li
- push @md_blocks, $md_block;
- my $lines = $2;
- my $indentation = $1;
- $lines =~ s/^[ ]{0,4}//;
- $md_block = { type => "li",
- ordered => 0,
- indentation => $indentation,
- marker => "[*+-]",
- first => 1,
- last => 1,
- lines => [ $lines ] };
- next OUTER;
- } elsif ($line =~ /^[ ]*>[ ]?(.*)/) {
- push @md_blocks, $md_block;
- $md_block = { type => "quote",
- lines => [ $1 ] };
- next OUTER;
- }
-
- # list item
- if ($line =~ /^([ ]{0,4})\d+[.][ ]+(.*)/) {
- push @md_blocks, $md_block;
- my $lines = $2;
- my $indentation = $1;
- $lines =~ s/^[ ]{0,4}//;
-
- $md_block = { type => "li",
- ordered => 1,
- indentation => $indentation,
- marker => "\\d+[.]",
- first => 1,
- last => 1,
- lines => [ $lines ] };
-
- next;
- }
-
- # paragraph
- if ($md_block->{"type"} eq "paragraph") {
- if ($md_block->{"interrupted"}) {
- push @md_blocks, $md_block;
- $md_block = { type => "paragraph",
- interrupted => 0,
- text => $line };
- @TRACE@("new paragraph due to interrupted");
- } else {
- $md_block->{"text"} .= "\n" . $line;
- @TRACE@("add to paragraph");
- }
- } else {
- push @md_blocks, $md_block;
- $md_block = { type => "paragraph",
- text => $line };
- @TRACE@("new paragraph due to different block type");
- }
- }
-
- push @md_blocks, $md_block;
-
- shift @md_blocks;
-
- return @md_blocks;
-}
-
-sub MarkDownParseSpanElementsInner {
- my ($text, $markersref) = @_;
- my $markup = "";
- my %markers = map { $_ => 1 } @$markersref;
-
- while ($text ne "") {
- my $closest_marker = "";
- my $closest_marker_index = 0;
- my $closest_marker_position = -1;
- my $text_marker = "";
- my $i = 0;
- my $offset = 0;
- my @markers_rest;
- my $marker;
- my $use;
-
- while ( ($marker, $use) = each %markers ) {
- my $marker_position;
-
- if (!$use) {
- next;
- }
-
- $marker_position = index ($text, $marker);
-
- if ($marker_position < 0) {
- $markers{$marker} = 0;
- next;
- }
-
- if ($closest_marker eq "" || $marker_position < $closest_marker_position) {
- $closest_marker = $marker;
- $closest_marker_index = $i;
- $closest_marker_position = $marker_position;
- }
- }
-
- if ($closest_marker_position >= 0) {
- $text_marker = substr ($text, $closest_marker_position);
- }
-
- if ($text_marker eq "") {
- $markup .= $text;
- $text = "";
- next; # last
- }
-
- $markup .= substr ($text, 0, $closest_marker_position);
- $text = substr ($text, $closest_marker_position);
- @markers_rest = map { $markers{$_} ? ($_ eq $closest_marker ? () : $_) : () } keys %markers;
-
- if ($closest_marker eq "![" || $closest_marker eq "[") {
- my %element;
-
- if (index ($text, "]") && $text =~ /\[((?:[^][]|(?R))*)\]/) {
- my $remaining_text;
-
- %element = ( "!" => (substr ($text, 0, 1) eq "!"),
- "a" => $1 );
-
- $offset = length ($&);
- if ($element{"!"}) {
- $offset++;
- }
-
- $remaining_text = substr ($text, $offset);
- if ($remaining_text =~ /^\([ ]*([^)'"]*?)(?:[ ]+['"](.+?)['"])?[ ]*\)/) {
- $element{"»"} = $1;
- if (defined ($2)) {
- $element{"#"} = $2;
- }
- $offset += length ($&);
- } elsif ($remaining_text =~ /^\s*\[([^\]<]*?)\]/) {
- $element{"ref"} = $1;
- $offset += length ($&);
- } else {
- undef %element;
- }
- }
-
- if (%element) {
- if ($element{"»"}) {
- $element{"»"} =~ s/&/&/g;
- $element{"»"} =~ s/</</g;
- }
- if ($element{"!"}) {
- $markup .= "<inlinemediaobject><imageobject><imagedata fileref=\"" . $element{"»"} . "\"></imagedata></imageobject>";
-
- if (defined ($element{"a"})) {
- $markup .= "<textobject><phrase>" . $element{"a"} . "</phrase></textobject>";
- }
-
- $markup .= "</inlinemediaobject>";
- } elsif ($element{"ref"}) {
- $element{"a"} = &MarkDownParseSpanElementsInner ($element{"a"}, \@markers_rest);
- $markup .= "<link linkend=\"" . $element{"ref"} . "\"";
-
- if (defined ($element{"#"})) {
- # title attribute not supported
- }
-
- $markup .= ">" . $element{"a"} . "</link>";
- } else {
- $element{"a"} = &MarkDownParseSpanElementsInner ($element{"a"}, \@markers_rest);
- $markup .= "<ulink url=\"" . $element{"»"} . "\"";
-
- if (defined ($element{"#"})) {
- # title attribute not supported
- }
-
- $markup .= ">" . $element{"a"} . "</ulink>";
- }
- } else {
- $markup .= $closest_marker;
- if ($closest_marker eq "![") {
- $offset = 2;
- } else {
- $offset = 1;
- }
- }
- } elsif ($closest_marker eq "<") {
- if ($text =~ /^<(https?:[\/]{2}[^\s]+?)>/i) {
- my $element_url = $1;
- $element_url =~ s/&/&/g;
- $element_url =~ s/</</g;
-
- $markup .= "<ulink url=\"" . $element_url . "\">" . $element_url . "</ulink>";
- $offset = length ($&);
- } elsif ($text =~ /^<([A-Za-z0-9._-]+?@[A-Za-z0-9._-]+?)>/) {
- $markup .= "<ulink url=\"mailto:" . $1 . "\">" . $1 . "</ulink>";
- $offset = length ($&);
- } elsif ($text =~ /^<[^>]+?>/) {
- $markup .= $&;
- $offset = length ($&);
- } else {
- $markup .= "<";
- $offset = 1;
- }
- } elsif ($closest_marker eq "\\") {
- my $special_char = substr ($text, 1, 1);
- if ($MD_ESCAPABLE_CHARS{$special_char} ||
- $MD_GTK_ESCAPABLE_CHARS{$special_char}) {
- $markup .= $special_char;
- $offset = 2;
- } else {
- $markup .= "\\";
- $offset = 1;
- }
- } elsif ($closest_marker eq "`") {
- if ($text =~ /^(`+)([^`]+?)\1(?!`)/) {
- my $element_text = $2;
- $markup .= "<literal>" . $element_text . "</literal>";
- $offset = length ($&);
- } else {
- $markup .= "`";
- $offset = 1;
- }
- } elsif ($closest_marker eq "@") {
- # Convert '@param()'
- # FIXME: we could make those also links ($symbol.$2), but that would be less
- # useful as the link target is a few lines up or down
- if ($text =~ /^(\A|[^\\])\@(\w+((\.|->)\w+)*)\s*\(\)/) {
- $markup .= $1 . "<parameter>" . $2 . "()</parameter>\n";
- $offset = length ($&);
- } elsif ($text =~ /^(\A|[^\\])\@(\w+((\.|->)\w+)*)/) {
- # Convert '@param', but not '\@param'.
- $markup .= $1 . "<parameter>" . $2 . "</parameter>\n";
- $offset = length ($&);
- } elsif ($text =~ /^\\\@/) {
- $markup .= "\@";
- $offset = length ($&);
- } else {
- $markup .= "@";
- $offset = 1;
- }
- } elsif ($closest_marker eq "#") {
- if ($text =~ /^(\A|[^\\])#([\w\-:\.]+[\w]+)\s*\(\)/) {
- # handle #Object.func()
- $markup .= $1 . &MakeXRef ($2, &tagify ($2 . "()", "function"));
- $offset = length ($&);
- } elsif ($text =~ /^(\A|[^\\])#([\w\-:\.]+[\w]+)/) {
- # Convert '#symbol', but not '\#symbol'.
- $markup .= $1 . &MakeHashXRef ($2, "type");
- $offset = length ($&);
- } elsif ($text =~ /^\\#/) {
- $markup .= "#";
- $offset = length ($&);
- } else {
- $markup .= "#";
- $offset = 1;
- }
- } elsif ($closest_marker eq "%") {
- if ($text =~ /^(\A|[^\\])\%(-?\w+)/) {
- # Convert '%constant', but not '\%constant'.
- # Also allow negative numbers, e.g. %-1.
- $markup .= $1 . &MakeXRef ($2, &tagify ($2, "literal"));
- $offset = length ($&);
- } elsif ($text =~ /^\\%/) {
- $markup .= "\%";
- $offset = length ($&);
- } else {
- $markup .= "%";
- $offset = 1;
- }
- }
-
- if ($offset > 0) {
- $text = substr ($text, $offset);
- }
- }
-
- return $markup;
-}
-
-sub MarkDownParseSpanElements {
- my ($text) = @_;
- my @markers = ( "\\", "<", "![", "[", "`", "%", "#", "@" );
-
- $text = &MarkDownParseSpanElementsInner ($text, \@markers);
-
- # Convert 'function()' or 'macro()'.
- # if there is abc_*_def() we don't want to make a link to _def()
- # FIXME: also handle abc(def(....)) : but that would need to be done recursively :/
- $text =~ s/([^\*.\w])(\w+)\s*\(\)/$1.&MakeXRef($2, &tagify($2 . "()", "function"));/eg;
-
- return $text;
-}
-
-sub ReplaceEntities {
- my ($text, $symbol) = @_;
- my $warn = "";
- my @entities = ( [ "<", "<" ],
- [ ">", ">" ],
- [ "*", "*" ],
- [ "#", "#" ],
- [ "%", "%"],
- [ ":", ":" ],
- [ """, "\"" ],
- [ "'", "'" ],
- [ " ", " " ],
- [ "&", "&" ] ); # Do this last, or the others get messed up.
- my $i;
-
- # Expand entities in <programlisting> even inside CDATA since
- # we changed the definition of |[ to add CDATA
- for ($i = 0; $i <= $#entities; $i++) {
- $text =~ s/$entities[$i][0]/$entities[$i][1]/g;
- }
-
- return $text;
-}
-
-sub MarkDownOutputDocBook {
- my ($blocksref, $symbol, $context) = @_;
- my $output = "";
- my $block;
- my @blocks = @$blocksref;
-
- foreach $block (@blocks) {
- my $text;
- my $title;
-
- #$output .= "\n<!-- beg type='" . $block->{"type"} . "'-->\n";
-
- if ($block->{"type"} eq "paragraph") {
- $text = &MarkDownParseSpanElements ($block->{"text"});
- if ($context eq "li" && $output eq "") {
- if ($block->{"interrupted"}) {
- $output .= "\n<para>$text</para>\n";
- } else {
- $output .= "<para>$text</para>";
- if ($#blocks > 0) {
- $output .= "\n";
- }
- }
- } else {
- $output .= "<para>$text</para>\n";
- }
-
- } elsif ($block->{"type"} eq "heading") {
- my $tag;
-
- $title = &MarkDownParseSpanElements ($block->{"text"});
-
- if ($block->{"level"} == 1) {
- $tag = "refsect2";
- } else {
- $tag = "refsect3";
- }
-
- $text = &MarkDownParseLines ($block->{"lines"}, $symbol, "heading");
- if (defined ($block->{"id"})) {
- $output .= "<$tag id=\"" . $block->{"id"} . "\">";
- } else {
- $output .= "<$tag>";
- }
-
- $output .= "<title>$title</title>$text</$tag>\n";
- } elsif ($block->{"type"} eq "li") {
- my $tag = "itemizedlist";
-
- if ($block->{"first"}) {
- if ($block->{"ordered"}) {
- $tag = "orderedlist";
- }
- $output .= "<$tag>\n";
- }
-
- if ($block->{"interrupted"}) {
- push @{$block->{"lines"}}, "";
- }
-
- $text = &MarkDownParseLines ($block->{"lines"}, $symbol, "li");
- $output .= "<listitem>".$text."</listitem>\n";
- if ($block->{"last"}) {
- if ($block->{"ordered"}) {
- $tag = "orderedlist";
- }
- $output .= "</$tag>\n";
- }
- } elsif ($block->{"type"} eq "quote") {
- $text = &MarkDownParseLines ($block->{"lines"}, $symbol, "quote");
- $output .= "<blockquote>\n$text</blockquote>\n";
- } elsif ($block->{"type"} eq "code") {
- my $tag = "programlisting";
-
- if ($block->{"language"}) {
- if ($block->{"language"} eq "plain") {
- $output .= "<informalexample><screen><![CDATA[\n";
- $tag = "screen";
- } else {
- $output .= "<informalexample><programlisting language=\"" . $block->{"language"} . "\"><![CDATA[\n";
- }
- } else {
- $output .= "<informalexample><programlisting><![CDATA[\n";
- }
- foreach (@{$block->{"lines"}}) {
- $output .= &ReplaceEntities ($_, $symbol) . "\n";
- }
- $output .= "]]></$tag></informalexample>\n";
- } elsif ($block->{"type"} eq "markup") {
- $text = &ExpandAbbreviations($symbol, $block->{"text"});
- $output .= $text."\n";
- } else {
- $output .= $block->{"text"}."\n";
- }
- #$output .= "\n<!-- end type='" . $block->{"type"} . "'-->\n";
- }
-
- return $output;
-}
-
-sub MarkDownParseLines {
- my ($linesref, $symbol, $context) = @_;
- my $output;
- my @lines = @$linesref;
- my @blocks;
-
- @blocks = &MarkDownParseBlocks (\@lines, $symbol, $context);
- $output = &MarkDownOutputDocBook (\@blocks, $symbol, $context);
-
- return $output;
-}
-
-sub MarkDownParse {
- my ($text, $symbol) = @_;
- my @lines;
-
- # take out some variability in line endings
- $text =~ s%\r\n%\n%g;
- $text =~ s%\r%\n%g;
-
- # split lines
- @lines = split("\n", $text);
- $text = MarkDownParseLines(\@lines, $symbol, "");
-
- return $text;
-}
-
-#############################################################################
-# LIBRARY FUNCTIONS - These functions are used in both gtkdoc-mkdb and
-# gtkdoc-mktmpl and should eventually be moved to a
-# separate library.
-#############################################################################
-
-#############################################################################
-# Function : ReadDeclarationsFile
-# Description : This reads in a file containing the function/macro/enum etc.
-# declarations.
-#
-# Note that in some cases there are several declarations with
-# the same name, e.g. for conditional macros. In this case we
-# set a flag in the %DeclarationConditional hash so the
-# declaration is not shown in the docs.
-#
-# If a macro and a function have the same name, e.g. for
-# gtk_object_ref, the function declaration takes precedence.
-#
-# Some opaque structs are just declared with 'typedef struct
-# _name name;' in which case the declaration may be empty.
-# The structure may have been found later in the header, so
-# that overrides the empty declaration.
-#
-# Arguments : $file - the declarations file to read
-# $override - if declarations in this file should override
-# any current declaration.
-#############################################################################
-
-sub ReadDeclarationsFile {
- my ($file, $override) = @_;
-
- if ($override == 0) {
- %Declarations = ();
- %DeclarationTypes = ();
- %DeclarationConditional = ();
- %DeclarationOutput = ();
- }
-
- open (INPUT, $file)
- || die "Can't open $file: $!";
- my $declaration_type = "";
- my $declaration_name;
- my $declaration;
- my $is_deprecated = 0;
- while (<INPUT>) {
- if (!$declaration_type) {
- if (m/^<([^>]+)>/) {
- $declaration_type = $1;
- $declaration_name = "";
- @TRACE@("Found declaration: $declaration_type\n");
- $declaration = "";
- }
- } else {
- if (m%^<NAME>(.*)</NAME>%) {
- $declaration_name = $1;
- } elsif (m%^<DEPRECATED/>%) {
- $is_deprecated = 1;
- } elsif (m%^</$declaration_type>%) {
- @TRACE@("Found end of declaration: $declaration_name\n");
- # Check that the declaration has a name
- if ($declaration_name eq "") {
- &LogWarning ($file, $., "$declaration_type has no name.\n");
- }
-
- # If the declaration is an empty typedef struct _XXX XXX
- # set the flag to indicate the struct has a typedef.
- if (($declaration_type eq 'STRUCT' || $declaration_type eq 'UNION')
- && $declaration =~ m/^\s*$/) {
- @TRACE@("Struct has typedef: $declaration_name\n");
- $StructHasTypedef{$declaration_name} = 1;
- }
-
- # Check if the symbol is already defined.
- if (defined ($Declarations{$declaration_name})
- && $override == 0) {
- # Function declarations take precedence.
- if ($DeclarationTypes{$declaration_name} eq 'FUNCTION') {
- # Ignore it.
- } elsif ($declaration_type eq 'FUNCTION') {
- if ($is_deprecated) {
- $Deprecated{$declaration_name} = "";
- }
- $Declarations{$declaration_name} = $declaration;
- $DeclarationTypes{$declaration_name} = $declaration_type;
- } elsif ($DeclarationTypes{$declaration_name}
- eq $declaration_type) {
- # If the existing declaration is empty, or is just a
- # forward declaration of a struct, override it.
- if ($declaration_type eq 'STRUCT' || $declaration_type eq 'UNION') {
- if ($Declarations{$declaration_name} =~ m/^\s*((struct|union)\s+\w+\s*;)?\s*$/) {
- if ($is_deprecated) {
- $Deprecated{$declaration_name} = "";
- }
- $Declarations{$declaration_name} = $declaration;
- } elsif ($declaration =~ m/^\s*((struct|union)\s+\w+\s*;)?\s*$/) {
- # Ignore an empty or forward declaration.
- } else {
- &LogWarning ($file, $., "Structure $declaration_name has multiple definitions.");
- }
- } else {
- # set flag in %DeclarationConditional hash for
- # multiply defined macros/typedefs.
- $DeclarationConditional{$declaration_name} = 1;
- }
- } else {
- &LogWarning ($file, $., "$declaration_name has multiple definitions.");
- }
- } else {
- if ($is_deprecated) {
- $Deprecated{$declaration_name} = "";
- }
- $Declarations{$declaration_name} = $declaration;
- $DeclarationTypes{$declaration_name} = $declaration_type;
- }
-
- $declaration_type = "";
- $is_deprecated = 0;
- } else {
- $declaration .= $_;
- }
- }
- }
- close (INPUT);
-}
-
-
-#############################################################################
-# Function : ReadSignalsFile
-# Description : This reads in an existing file which contains information on
-# all GTK signals. It creates the arrays @SignalNames and
-# @SignalPrototypes containing info on the signals. The first
-# line of the SignalPrototype is the return type of the signal
-# handler. The remaining lines are the parameters passed to it.
-# The last parameter, "gpointer user_data" is always the same
-# so is not included.
-# Arguments : $file - the file containing the signal handler prototype
-# information.
-#############################################################################
-
-sub ReadSignalsFile {
- my ($file) = @_;
-
- my $in_signal = 0;
- my $signal_object;
- my $signal_name;
- my $signal_returns;
- my $signal_flags;
- my $signal_prototype;
-
- # Reset the signal info.
- @SignalObjects = ();
- @SignalNames = ();
- @SignalReturns = ();
- @SignalFlags = ();
- @SignalPrototypes = ();
-
- if (! -f $file) {
- return;
- }
- if (!open (INPUT, $file)) {
- warn "Can't open $file - skipping signals\n";
- return;
- }
- while (<INPUT>) {
- if (!$in_signal) {
- if (m/^<SIGNAL>/) {
- $in_signal = 1;
- $signal_object = "";
- $signal_name = "";
- $signal_returns = "";
- $signal_prototype = "";
- }
- } else {
- if (m/^<NAME>(.*)<\/NAME>/) {
- $signal_name = $1;
- if ($signal_name =~ m/^(.*)::(.*)$/) {
- $signal_object = $1;
- ($signal_name = $2) =~ s/_/-/g;
- @TRACE@("Found signal: $signal_name\n");
- } else {
- &LogWarning ($file, $., "Invalid signal name: $signal_name.");
- }
- } elsif (m/^<RETURNS>(.*)<\/RETURNS>/) {
- $signal_returns = $1;
- } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
- $signal_flags = $1;
- } elsif (m%^</SIGNAL>%) {
- @TRACE@("Found end of signal: ${signal_object}::${signal_name}\nReturns: ${signal_returns}\n${signal_prototype}");
- push (@SignalObjects, $signal_object);
- push (@SignalNames, $signal_name);
- push (@SignalReturns, $signal_returns);
- push (@SignalFlags, $signal_flags);
- push (@SignalPrototypes, $signal_prototype);
- $in_signal = 0;
- } else {
- $signal_prototype .= $_;
- }
- }
- }
- close (INPUT);
-}
-
-
-#############################################################################
-# Function : ReadTemplateFile
-# Description : This reads in the manually-edited documentation file
-# corresponding to the file currently being created, so we can
-# insert the documentation at the appropriate places.
-# It outputs %SymbolTypes, %SymbolDocs and %SymbolParams, which
-# is a hash of arrays.
-# NOTE: This function is duplicated in gtkdoc-mktmpl (but
-# slightly different).
-# Arguments : $docsfile - the template file to read in.
-# $skip_unused_params - 1 if the unused parameters should be
-# skipped.
-#############################################################################
-
-sub ReadTemplateFile {
- my ($docsfile, $skip_unused_params) = @_;
-
- my $template = "$docsfile.sgml";
- if (! -f $template) {
- @TRACE@("File doesn't exist: $template\n");
- return 0;
- }
-
- # start with empty hashes, we merge the source comment for each file
- # afterwards
- %SymbolDocs = ();
- %SymbolTypes = ();
- %SymbolParams = ();
-
- my $current_type = ""; # Type of symbol being read.
- my $current_symbol = ""; # Name of symbol being read.
- my $symbol_doc = ""; # Description of symbol being read.
- my @params; # Parameter names and descriptions of current
- # function/macro/function typedef.
- my $current_param = -1; # Index of parameter currently being read.
- # Note that the param array contains pairs
- # of param name & description.
- my $in_unused_params = 0; # True if we are reading in the unused params.
- my $in_deprecated = 0;
- my $in_since = 0;
- my $in_stability = 0;
-
- open (DOCS, "$template")
- || die "Can't open $template: $!";
-
- @TRACE@("reading template $template");
-
- while (<DOCS>) {
- if (m/^<!-- ##### ([A-Z_]+) (\S+) ##### -->/) {
- my $type = $1;
- my $symbol = $2;
- if ($symbol eq "Title"
- || $symbol eq "Short_Description"
- || $symbol eq "Long_Description"
- || $symbol eq "See_Also"
- || $symbol eq "Stability_Level"
- || $symbol eq "Include"
- || $symbol eq "Image") {
-
- $symbol = $docsfile . ":" . $symbol;
- }
-
- @TRACE@("Found symbol: $symbol\n");
- # Remember file and line for the symbol
- $SymbolSourceFile{$symbol} = $template;
- $SymbolSourceLine{$symbol} = $.;
-
- # Store previous symbol, but remove any trailing blank lines.
- if ($current_symbol ne "") {
- $symbol_doc =~ s/\s+$//;
- $SymbolTypes{$current_symbol} = $current_type;
- $SymbolDocs{$current_symbol} = $symbol_doc;
-
- # Check that the stability level is valid.
- if ($StabilityLevel{$current_symbol}) {
- $StabilityLevel{$current_symbol} = &ParseStabilityLevel($StabilityLevel{$current_symbol}, $template, $., "Stability level for $current_symbol");
- }
-
- if ($current_param >= 0) {
- $SymbolParams{$current_symbol} = [ @params ];
- } else {
- # Delete any existing params in case we are overriding a
- # previously read template.
- delete $SymbolParams{$current_symbol};
- }
- }
- $current_type = $type;
- $current_symbol = $symbol;
- $current_param = -1;
- $in_unused_params = 0;
- $in_deprecated = 0;
- $in_since = 0;
- $in_stability = 0;
- $symbol_doc = "";
- @params = ();
-
- } elsif (m/^<!-- # Unused Parameters # -->/) {
- @TRACE@("Found unused parameters\n");
- $in_unused_params = 1;
- next;
-
- } elsif ($in_unused_params && $skip_unused_params) {
- # When outputting the DocBook we skip unused parameters.
- @TRACE@("Skipping unused param: $_");
- next;
-
- } else {
- # Check if param found. Need to handle "..." and "format...".
- if (s/^\@([\w\.]+):\040?//) {
- my $param_name = $1;
- my $param_desc = $_;
- # Allow variations of 'Returns'
- if ($param_name =~ m/^[Rr]eturns?$/) {
- $param_name = "Returns";
- }
- # Allow varargs variations
- if ($param_name =~ m/^.*\.\.\.$/) {
- $param_name = "...";
- }
-
- # strip trailing whitespaces and blank lines
- s/\s+\n$/\n/m;
- s/\n+$/\n/sm;
- @TRACE@("Found param for symbol $current_symbol : '$param_name'= '$_'");
-
- if ($param_name eq "Deprecated") {
- $in_deprecated = 1;
- $Deprecated{$current_symbol} = $_;
- } elsif ($param_name eq "Since") {
- $in_since = 1;
- chomp;
- $Since{$current_symbol} = $_;
- } elsif ($param_name eq "Stability") {
- $in_stability = 1;
- $StabilityLevel{$current_symbol} = $_;
- } else {
- push (@params, $param_name);
- push (@params, $param_desc);
- $current_param += $PARAM_FIELD_COUNT;
- }
- } else {
- # strip trailing whitespaces and blank lines
- s/\s+\n$/\n/m;
- s/\n+$/\n/sm;
-
- if (!m/^\s+$/) {
- if ($in_deprecated) {
- $Deprecated{$current_symbol} .= $_;
- } elsif ($in_since) {
- &LogWarning ($template, $., "multi-line since docs found");
- #$Since{$current_symbol} .= $_;
- } elsif ($in_stability) {
- $StabilityLevel{$current_symbol} .= $_;
- } elsif ($current_param >= 0) {
- $params[$current_param] .= $_;
- } else {
- $symbol_doc .= $_;
- }
- }
- }
- }
- }
-
- # Remember to finish the current symbol doccs.
- if ($current_symbol ne "") {
-
- $symbol_doc =~ s/\s+$//;
- $SymbolTypes{$current_symbol} = $current_type;
- $SymbolDocs{$current_symbol} = $symbol_doc;
-
- # Check that the stability level is valid.
- if ($StabilityLevel{$current_symbol}) {
- $StabilityLevel{$current_symbol} = &ParseStabilityLevel($StabilityLevel{$current_symbol}, $template, $., "Stability level for $current_symbol");
- }
-
- if ($current_param >= 0) {
- $SymbolParams{$current_symbol} = [ @params ];
- } else {
- # Delete any existing params in case we are overriding a
- # previously read template.
- delete $SymbolParams{$current_symbol};
- }
- }
-
- close (DOCS);
- return 1;
-}
-
-
-#############################################################################
-# Function : ReadObjectHierarchy
-# Description : This reads in the $MODULE-hierarchy.txt file containing all
-# the GtkObject subclasses described in this module (and their
-# ancestors).
-# It places them in the @Objects array, and places their level
-# in the object hierarchy in the @ObjectLevels array, at the
-# same index. GtkObject, the root object, has a level of 1.
-#
-# This also generates tree_index.sgml as it goes along.
-#
-# Arguments : none
-#############################################################################
-
-sub ReadObjectHierarchy {
- @Objects = ();
- @ObjectLevels = ();
-
- if (! -f $OBJECT_TREE_FILE) {
- return;
- }
- if (!open (INPUT, $OBJECT_TREE_FILE)) {
- warn "Can't open $OBJECT_TREE_FILE - skipping object tree\n";
- return;
- }
-
- # Only emit objects if they are supposed to be documented, or if
- # they have documented children. To implement this, we maintain a
- # stack of pending objects which will be emitted if a documented
- # child turns up.
- my @pending_objects = ();
- my @pending_levels = ();
- my $root;
- my @tree = ();
- while (<INPUT>) {
- if (m/\S+/) {
- my $object = $&;
- my $level = (length($`)) / 2 + 1;
- my $xref = "";
-
- if ($level == 1) {
- $root = $object;
- }
-
- while (($#pending_levels >= 0) && ($pending_levels[$#pending_levels] >= $level)) {
- my $pobject = pop(@pending_objects);
- my $plevel = pop(@pending_levels);
- }
-
- push (@pending_objects, $object);
- push (@pending_levels, $level);
-
- if (exists($KnownSymbols{$object})) {
- while ($#pending_levels >= 0) {
- $object = shift @pending_objects;
- $level = shift @pending_levels;
- $xref = &MakeXRef ($object);
-
- push (@tree, ' ' x ($level * 4) . "$xref");
- push (@Objects, $object);
- push (@ObjectLevels, $level);
- $ObjectRoots{$object} = $root;
- }
- }
- #else {
- # LogWarning ($OBJECT_TREE_FILE, $., "unknown type $object");
- #}
- }
- }
- close (INPUT);
-
- # FIXME: use xml
- # my $old_tree_index = "$DB_OUTPUT_DIR/tree_index.$xml";
- my $old_tree_index = "$DB_OUTPUT_DIR/tree_index.sgml";
- my $new_tree_index = "$DB_OUTPUT_DIR/tree_index.new";
-
- open (OUTPUT, ">$new_tree_index")
- || die "Can't create $new_tree_index: $!";
-
- print (OUTPUT &MakeDocHeader ("screen")."\n<screen>\n".&AddTreeLineArt(\@tree)."\n</screen>\n");
- close (OUTPUT);
-
- &UpdateFileIfChanged ($old_tree_index, $new_tree_index, 0);
-
- &OutputObjectList;
-}
-
-#############################################################################
-# Function : ReadInterfaces
-# Description : This reads in the $MODULE.interfaces file.
-#
-# Arguments : none
-#############################################################################
-
-sub ReadInterfaces {
- %Interfaces = ();
-
- if (! -f $INTERFACES_FILE) {
- return;
- }
- if (!open (INPUT, $INTERFACES_FILE)) {
- warn "Can't open $INTERFACES_FILE - skipping interfaces\n";
- return;
- }
-
- while (<INPUT>) {
- chomp;
- my ($object, @ifaces) = split;
- if (exists($KnownSymbols{$object}) && $KnownSymbols{$object} == 1) {
- my @knownIfaces = ();
-
- # filter out private interfaces, but leave foreign interfaces
- foreach my $iface (@ifaces) {
- if (!exists($KnownSymbols{$iface}) || $KnownSymbols{$iface} == 1) {
- push (@knownIfaces, $iface);
- }
- }
-
- $Interfaces{$object} = join(' ', @knownIfaces);
- @TRACE@("Interfaces for $object: $Interfaces{$object}\n");
- } else {
- @TRACE@("skipping interfaces for unknown symbol: $object\n");
- }
- }
- close (INPUT);
-}
-
-#############################################################################
-# Function : ReadPrerequisites
-# Description : This reads in the $MODULE.prerequisites file.
-#
-# Arguments : none
-#############################################################################
-
-sub ReadPrerequisites {
- %Prerequisites = ();
-
- if (! -f $PREREQUISITES_FILE) {
- return;
- }
- if (!open (INPUT, $PREREQUISITES_FILE)) {
- warn "Can't open $PREREQUISITES_FILE - skipping prerequisites\n";
- return;
- }
-
- while (<INPUT>) {
- chomp;
- my ($iface, @prereqs) = split;
- if (exists($KnownSymbols{$iface}) && $KnownSymbols{$iface} == 1) {
- my @knownPrereqs = ();
-
- # filter out private prerequisites, but leave foreign prerequisites
- foreach my $prereq (@prereqs) {
- if (!exists($KnownSymbols{$prereq}) || $KnownSymbols{$prereq} == 1) {
- push (@knownPrereqs, $prereq);
- }
- }
-
- $Prerequisites{$iface} = join(' ', @knownPrereqs);
- }
- }
- close (INPUT);
-}
-
-#############################################################################
-# Function : ReadArgsFile
-# Description : This reads in an existing file which contains information on
-# all GTK args. It creates the arrays @ArgObjects, @ArgNames,
-# @ArgTypes, @ArgFlags, @ArgNicks and @ArgBlurbs containing info
-# on the args.
-# Arguments : $file - the file containing the arg information.
-#############################################################################
-
-sub ReadArgsFile {
- my ($file) = @_;
-
- my $in_arg = 0;
- my $arg_object;
- my $arg_name;
- my $arg_type;
- my $arg_flags;
- my $arg_nick;
- my $arg_blurb;
- my $arg_default;
- my $arg_range;
-
- # Reset the args info.
- @ArgObjects = ();
- @ArgNames = ();
- @ArgTypes = ();
- @ArgFlags = ();
- @ArgNicks = ();
- @ArgBlurbs = ();
- @ArgDefaults = ();
- @ArgRanges = ();
-
- if (! -f $file) {
- return;
- }
- if (!open (INPUT, $file)) {
- warn "Can't open $file - skipping args\n";
- return;
- }
- while (<INPUT>) {
- if (!$in_arg) {
- if (m/^<ARG>/) {
- $in_arg = 1;
- $arg_object = "";
- $arg_name = "";
- $arg_type = "";
- $arg_flags = "";
- $arg_nick = "";
- $arg_blurb = "";
- $arg_default = "";
- $arg_range = "";
- }
- } else {
- if (m/^<NAME>(.*)<\/NAME>/) {
- $arg_name = $1;
- if ($arg_name =~ m/^(.*)::(.*)$/) {
- $arg_object = $1;
- ($arg_name = $2) =~ s/_/-/g;
- @TRACE@("Found arg: $arg_name\n");
- } else {
- &LogWarning ($file, $., "Invalid argument name: $arg_name");
- }
- } elsif (m/^<TYPE>(.*)<\/TYPE>/) {
- $arg_type = $1;
- } elsif (m/^<RANGE>(.*)<\/RANGE>/) {
- $arg_range = $1;
- } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
- $arg_flags = $1;
- } elsif (m/^<NICK>(.*)<\/NICK>/) {
- $arg_nick = $1;
- } elsif (m/^<BLURB>(.*)<\/BLURB>/) {
- $arg_blurb = $1;
- if ($arg_blurb eq "(null)") {
- $arg_blurb = "";
- &LogWarning ($file, $., "Property ${arg_object}:${arg_name} has no documentation.");
- }
- } elsif (m/^<DEFAULT>(.*)<\/DEFAULT>/) {
- $arg_default = $1;
- } elsif (m%^</ARG>%) {
- @TRACE@("Found end of arg: ${arg_object}::${arg_name}\n${arg_type} : ${arg_flags}\n");
- push (@ArgObjects, $arg_object);
- push (@ArgNames, $arg_name);
- push (@ArgTypes, $arg_type);
- push (@ArgRanges, $arg_range);
- push (@ArgFlags, $arg_flags);
- push (@ArgNicks, $arg_nick);
- push (@ArgBlurbs, $arg_blurb);
- push (@ArgDefaults, $arg_default);
- $in_arg = 0;
- }
- }
- }
- close (INPUT);
-}
-
-#############################################################################
-# Function : AddTreeLineArt
-# Description : Add unicode lineart to a pre-indented string array and returns
-# it as as multiline string.
-# Arguments : @tree - array of indented strings.
-#############################################################################
-
-sub AddTreeLineArt {
- my @tree = @{$_[0]};
- my $i;
- my $j;
- my $indent;
-
- # iterate bottom up over the tree
- for ($i = $#tree; $i >= 0; $i--) {
- # count leading spaces
- $tree[$i] =~ /^([^<A-Za-z]*)/;
- $indent = length( $1 );
- # replace with ╰───, if place of ╰ is not space insert ├
- if ($indent > 4) {
- if (substr($tree[$i],$indent-4,1) eq " ") {
- substr($tree[$i],$indent-4,4) = "--- ";
- } else {
- substr($tree[$i],$indent-4,4) = "+-- ";
- }
- # go lines up while space and insert |
- for ($j = $i - 1; ($j >= 0 && substr($tree[$j],$indent-4,1) eq ' '); $j--) {
- substr($tree[$j],$indent-4,1) = '|';
- }
- }
- }
-
- my $res = join("\n", @tree);
- # unicode chars for: ╰──
- $res =~ s%---%<phrase role=\"lineart\">╰──</phrase>%g;
- # unicde chars for: ├──
- $res =~ s%\+--%<phrase role=\"lineart\">├──</phrase>%g;
- # unicode char for: │
- $res =~ s%\|%<phrase role=\"lineart\">│</phrase>%g;
-
- return $res;
-}
-
-
-#############################################################################
-# Function : CheckIsObject
-# Description : Returns 1 if the given name is a GObject or a subclass.
-# It uses the global @Objects array.
-# Note that the @Objects array only contains classes in the
-# current module and their ancestors - not all GObject classes.
-# Arguments : $name - the name to check.
-#############################################################################
-
-sub CheckIsObject {
- my ($name) = @_;
- my $root = $ObjectRoots{$name};
- # Let GBoxed pass as an object here to get -struct appended to the id
- # and prevent conflicts with sections.
- return (defined($root) and $root ne 'GEnum' and $root ne 'GFlags');
-}
-
-
-#############################################################################
-# Function : MakeReturnField
-# Description : Pads a string to $RETURN_TYPE_FIELD_WIDTH.
-# Arguments : $str - the string to pad.
-#############################################################################
-
-sub MakeReturnField {
- my ($str) = @_;
-
- return $str . (' ' x ($RETURN_TYPE_FIELD_WIDTH - length ($str)));
-}
-
-#############################################################################
-# Function : GetSymbolSourceFile
-# Description : Get the filename where the symbol docs where taken from.
-# Arguments : $symbol - the symbol name
-#############################################################################
-
-sub GetSymbolSourceFile {
- my ($symbol) = @_;
-
- if (defined($SourceSymbolSourceFile{$symbol})) {
- return $SourceSymbolSourceFile{$symbol};
- } elsif (defined($SymbolSourceFile{$symbol})) {
- return $SymbolSourceFile{$symbol};
- } else {
- return "";
- }
-}
-
-#############################################################################
-# Function : GetSymbolSourceLine
-# Description : Get the file line where the symbol docs where taken from.
-# Arguments : $symbol - the symbol name
-#############################################################################
-
-sub GetSymbolSourceLine {
- my ($symbol) = @_;
-
- if (defined($SourceSymbolSourceLine{$symbol})) {
- return $SourceSymbolSourceLine{$symbol};
- } elsif (defined($SymbolSourceLine{$symbol})) {
- return $SymbolSourceLine{$symbol};
- } else {
- return 0;
- }
-}
-
+from __future__ import print_function
+
+import argparse
+import sys
+sys.path.append('@PYTHON_PACKAGE_DIR@')
+
+from gtkdoc import common, config, mkdb
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser()
+ parser.add_argument('--version', action='version', version=config.version)
+ parser.add_argument('--module', required=True,
+ help='Name of the doc module being parsed')
+ parser.add_argument('--source-dir', action='append', dest='source_dir', default=[])
+ parser.add_argument('--source-suffixes', dest='source_suffixes', default='')
+ parser.add_argument('--ignore-files', dest='ignore_files', default='')
+ parser.add_argument('--output-dir', dest='output_dir', default='')
+ parser.add_argument('--tmpl-dir', dest='tmpl_dir', help="DEPRECATED")
+ parser.add_argument('--main-sgml-file', dest='main_sgml_file', default='')
+ parser.add_argument('--expand-content-files', dest='expand_content_files', default='')
+ group = parser.add_mutually_exclusive_group()
+ group.add_argument('--sgml-mode', action='store_true', default=False, dest='sgml_mode')
+ group.add_argument('--xml-mode', action='store_true', default=False, dest='xml_mode')
+ parser.add_argument('--default-stability', dest='default_stability',
+ choices=['', 'Stable', 'Private', 'Unstable'], default='')
+ parser.add_argument('--default-includes', dest='default_includes', default='')
+ parser.add_argument('--output-format', default='xml') # MUST be 'xml', deprecate?
+ parser.add_argument('--name-space', dest='name_space', default='')
+ parser.add_argument('--outputallsymbols', default=False, action='store_true')
+ parser.add_argument('--outputsymbolswithoutsince', default=False, action='store_true')
+
+ options = parser.parse_args()
+
+ if options.output_format != "xml":
+ sys.exit('Invalid format "%s" passed to --output.format' % options.output_format)
+
+ common.setup_logging()
+
+ mkdb.Run(options)
-#!/bin/sh
+#!@PYTHON@
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998 Owen Taylor
+# 2001-2005 Damon Chaplin
+# 2009-2017 Stefan Sauer
+# 2017 Jussi Pakkanen
+#
+# 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.
#
-usage() {
-cat <<EOF
-gtkdoc-mkhtml version @VERSION@ - generate documentation in html format
-
---verbose Print extra output while processing
---path=SEARCH_PATH Extra source directories
-MODULE Name of the doc module being parsed
-DRIVER_FILE File containing the toplevel DocBook file.
---version Print the version of this program
---help Print this help
-EOF
-}
-
-# echo "args $*\n";
-
-# parse options, ignore unknown options for future extensions
-
-verbose="0"
-searchpath=
-uninstalled=no
-while true; do
- case "X$1" in
- X--version) echo "@VERSION@"; exit 0;;
- X--help) usage; exit 0;;
- X--uninstalled) uninstalled=yes; shift;;
- X--verbose) verbose="1"; shift;;
- X--path=*) searchpath=`echo "$1" | sed s/.*=//`; shift;;
- X--*) shift;;
- X*) break;;
- esac
-done
-
-if test $# -lt 2; then
- usage 1>&2
- exit 1
-fi
-
-module="$1"
-shift
-document="$1"
-shift
-
-quiet="1"
-if test $verbose = "1"; then
- quiet="0"
-fi
-
-if test $uninstalled = yes; then
- # this does not work from buiddir!=srcdir
- gtkdocdir=`dirname $0`
- # traditional Bourne shells may not support -e here, use -f
- if test ! -f $gtkdocdir/gtk-doc.xsl; then
- # try to src dir (set from makefiles) too
- if test -f $ABS_TOP_SRCDIR/gtk-doc.xsl; then
- gtkdocdir=$ABS_TOP_SRCDIR
- fi
- fi
- styledir=$gtkdocdir/style
- #echo "uninstalled, gtkdocdir=$gtkdocdir, cwd=$PWD"
-else
- # the first two are needed to resolve datadir
- prefix=@prefix@
- datarootdir=@datarootdir@
- gtkdocdir=@datadir@/gtk-doc/data
- styledir=$gtkdocdir
-fi
-
-# we could do "$path_option $PWD "
-# to avoid needing rewriting entities that are copied from the header
-# into docs under xml
-if test "X$searchpath" = "X"; then
- path_arg=
-else
- path_arg="--path $searchpath"
-fi
-
-# profiling
-profile_args=""
-if test "$GTKDOC_PROFILE" != ""; then
- profile_args="--profile"
-fi
-
-#echo @XSLTPROC@ $path_arg --nonet --xinclude \
-# --stringparam gtkdoc.bookname $module \
-# --stringparam gtkdoc.version "@VERSION@" \
-# "$@" $gtkdocdir/gtk-doc.xsl "$document"
-@XSLTPROC@ 2>profile.txt $profile_args $path_arg --nonet --xinclude \
- --stringparam gtkdoc.bookname $module \
- --stringparam gtkdoc.version "@VERSION@" \
- --stringparam chunk.quietly $quiet \
- --stringparam chunker.output.quiet $quiet \
- "$@" $gtkdocdir/gtk-doc.xsl "$document" || exit $?
-
-# profiling
-if test "$GTKDOC_PROFILE" != ""; then
- cat profile.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o profile.png
-else
- rm profile.txt
-fi
-
-# copy navigation images and stylesheets to html directory ...
-cp -f $styledir/*.png $styledir/*.css ./
-
-
-echo "timestamp" > ../html.stamp
-
+import argparse
+import sys
+sys.path.append('@PYTHON_PACKAGE_DIR@')
+
+from gtkdoc import common, config, mkhtml
+
+if __name__ == '__main__':
+ 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('--verbose', default=False, action='store_true',
+ help='Print extra output while processing')
+ parser.add_argument('--path', default=[], action='append',
+ help='Extra source directories')
+ parser.add_argument('args', nargs='*',
+ help='MODULE DRIVER_FILE')
+ # TODO: only for testing, replace with env-var
+ parser.add_argument('--uninstalled', action='store_true', default=False,
+ help='???')
+
+ options = parser.parse_args()
+ if len(options.args) < 2:
+ sys.exit('Too few arguments')
+
+ common.setup_logging()
+
+ sys.exit(mkhtml.run(options))
-#!/bin/sh
+#!@PYTHON@
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998 Owen Taylor
+# 2001-2005 Damon Chaplin
+# 2009-2017 Stefan Sauer
+# 2017 Jussi Pakkanen
+#
+# 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.
#
-usage() {
-cat <<EOF
-gtkdoc-mkman version @VERSION@ - generate documentation in man format
-
---verbose Print extra output while processing
---path=SEARCH_PATH Extra source directories
-MODULE Name of the doc module being parsed
-DRIVER_FILE File containing the toplevel DocBook file.
---version Print the version of this program
---help Print this help
-EOF
-}
-
-# parse options, ignore unknown options for future extensions
-
-verbose=0
-searchpath=
-uninstalled=no
-while true; do
- case "X$1" in
- X--version) echo "@VERSION@"; exit 0;;
- X--help) usage; exit 0;;
- X--uninstalled) uninstalled=yes; shift;;
- X--verbose) verbose="1"; shift;;
- X--path=*) searchpath=`echo $1 | sed s/.*=//`; shift;;
- X--*) shift;;
- X*) break;;
- esac
-done
-
-if test $# -ne 2; then
- usage 1>&2
- exit 1
-fi
-
-module=$1
-shift
-document=$1
-shift
-
-quiet="1"
-if test $verbose = "1"; then
- quiet="0"
-fi
+import argparse
+import sys
+sys.path.append('@PYTHON_PACKAGE_DIR@')
-if test $uninstalled = yes; then
- # this does not work from buiddir!=srcdir
- gtkdocdir=`dirname $0`
- #echo "uninstalled, gtkdocdir=$gtkdocdir"
-else
- # the first two are needed to resolve datadir
- prefix=@prefix@
- datarootdir=@datarootdir@
- gtkdocdir=@datadir@/gtk-doc/data
-fi
+from gtkdoc import common, config, mkman
-if head -n 1 $document | grep "<?xml" > /dev/null; then
- is_xml=true
- path_option='--path'
-else
- is_xml=false
- path_option='--directory'
-fi
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ description='gtkdoc-mkman version %s - generate documentation in man format' % config.version)
+ parser.add_argument('--version', action='version', version=config.version)
+ parser.add_argument('--verbose', default=False, action='store_true',
+ help='Print extra output while processing')
+ parser.add_argument('--path', default=[], action='append',
+ help='Extra source directories')
+ parser.add_argument('args', nargs=2,
+ help='MODULE DRIVER_FILE')
+ # TODO: only for testing, replace with env-var
+ parser.add_argument('--uninstalled', action='store_true', default=False,
+ help='???')
-# we could do "$path_option $PWD "
-# to avoid needing rewriting entities that are copied from the header
-# into docs under xml
-if test "X$searchpath" = "X"; then
- path_arg=
-else
- path_arg="$path_option $searchpath"
-fi
+ options = parser.parse_args()
-# would it make sens to create man pages only for certain refentries
-# e.g. for tools
-if $is_xml; then
- # see http://bugzilla.gnome.org/show_bug.cgi?id=467488
- @XSLTPROC@ $path_arg --nonet --xinclude \
- --stringparam gtkdoc.bookname $module \
- --stringparam gtkdoc.version "@VERSION@" \
- --stringparam chunk.quietly $quiet \
- --stringparam chunker.output.quiet $quiet \
- http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl \
- $document || exit $?
-else
- for i in `cd sgml;ls *.sgml`; do
- j=`echo $i | sed 's/.sgml/.man/'`
- echo ": converting " $i $j
- docbook-to-man sgml/$i > man/$j 2> man/$j.log
- done
-fi
+ common.setup_logging()
+ sys.exit(mkman.run(options))
-#!/bin/sh
+#!@PYTHON@
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2009-2017 Stefan Sauer
+# 2017 Jussi Pakkanen
+#
+# 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.
#
-usage() {
-cat <<EOF
-gtkdoc-mkpdf version @VERSION@ - generate documentation in pdf format
-
---verbose Print extra output while processing
---path=SEARCH_PATH Extra source directories
---imgdir=DIR Extra image directories
-MODULE Name of the doc module being parsed
-DRIVER_FILE File containing the toplevel DocBook file.
---version Print the version of this program
---help Print this help
-EOF
-}
-
-#echo "args $0\n";
-
-cleanexit() {
- rm -f $module.fo
- exit 1
-}
-
-# parse options, ignore unknown options for future extensions
-
-verbose="0"
-searchpath=
-uninstalled=no
-imgdirs=
-while true; do
- case "X$1" in
- X--version) echo "@VERSION@"; exit 0;;
- X--help) usage; exit 0;;
- X--uninstalled) uninstalled=yes; shift;;
- X--verbose) verbose="1"; shift;;
- X--path=*) searchpath=`echo "$1" | sed s/.*=//`; shift;;
- X--imgdir=*) imgdirs="$imgdirs -I `echo "$1" | sed s/.*=//`"; shift;;
- X--*) shift;;
- X*) break;;
- esac
-done
-
-if test $# -lt 2; then
- usage 1>&2
- exit 1
-fi
-
-module="$1"
-shift
-document="$1"
-shift
-
-quiet="1"
-if test $verbose = "1"; then
- quiet="0"
-fi
-
-if test $uninstalled = yes; then
- # this does not work from buiddir!=srcdir
- # we could try this
- # MAKE_SCRDIR=$(abs_srcdir) MAKE_BUILDDIR=$(abs_builddir) gtkdoc-mkpdf ...
- gtkdocdir=`dirname $0`
- #echo "uninstalled, gtkdocdir=$gtkdocdir"
-else
- # the first two are needed to resolve datadir
- prefix=@prefix@
- datarootdir=@datarootdir@
- gtkdocdir=@datadir@/gtk-doc/data
-fi
+import argparse
+import sys
+sys.path.append('@PYTHON_PACKAGE_DIR@')
-if head -n 1 $document | grep "<?xml" > /dev/null; then
- is_xml=true
- path_option='--path'
-else
- is_xml=false
- path_option='--directory'
-fi
+from gtkdoc import common, config, mkpdf
-# we could do "$path_option $PWD "
-# to avoid needing rewriting entities that are copied from the header
-# into docs under xml
-if test "X$searchpath" = "X"; then
- path_arg=
-else
- path_arg="$path_option $searchpath"
-fi
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ description='gtkdoc-mkpdf version %s - generate documentation in pdf format' % config.version)
+ parser.add_argument('--version', action='version', version=config.version)
+ parser.add_argument('--verbose', default=False, action='store_true',
+ help='Print extra output while processing.')
+ parser.add_argument('--path', default=[], action='append',
+ help='Extra source directories.')
+ parser.add_argument('--imgdir', default=[], action='append',
+ help='Extra image directories.')
+ parser.add_argument('--uninstalled', action='store_true', default=False,
+ help='???')
+ parser.add_argument('args', nargs=2,
+ help='MODULE DRIVER_FILE')
-if $is_xml; then
- if test -n "@DBLATEX@"; then
- # extra options to consider
- # -I FIG_PATH
- # -V is useful for debugging
- # -T db2latex : different style
- # -d : keep transient files (for debugging)
- # -P abc.def=$quiet : once the stylesheets have a quiet mode
- # xsltproc is already called with --xinclude
- # does not work: --xslt-opts "$path_arg --nonet $@"
- dblatex_options="-o $module.pdf $imgdirs $document"
- #echo "calling: @DBLATEX@ $dblatex_options"
- if test $verbose = "0"; then
- @DBLATEX@ 2>&1 --help | grep >/dev/null "\-\-quiet"
- if test "$?" = "0"; then
- dblatex_options="--quiet $dblatex_options";
- fi;
- @DBLATEX@ 2>&1 >/dev/null $dblatex_options | grep -v 'programlisting or screen'
- else
- { @DBLATEX@ 2>&1 >&3 $dblatex_options | grep -v 'programlisting or screen' >&2; } 3>&1
- fi
- else
- if test -n "@FOP@"; then
- @XSLTPROC@ $path_arg --nonet --xinclude \
- --stringparam gtkdoc.bookname $module \
- --stringparam gtkdoc.version "@VERSION@" \
- --stringparam chunk.quietly $quiet \
- --stringparam chunker.output.quiet $quiet \
- "$@" -o $module.fo $gtkdocdir/gtk-doc-fo.xsl "$document" || cleanexit $?
- # fop dies too easily :(
- # @FOP@ $module.fo $module.pdf
- else
- echo "dblatex or fop must be installed to use gtkdoc-mkpdf." >&2
- cleanexit 1
- fi
- fi
-else
- # not very good output
- # also for xxx-docs.sgml it will produce xxx-docs.pdf
- docbook2pdf -e no-valid "$document"
-fi
+ options = parser.parse_args()
-echo "timestamp" > pdf.stamp
-cleanexit 0
+ common.setup_logging()
+ sys.exit(mkpdf.run(options))
+++ /dev/null
-#!@PERL@ -w
-# -*- cperl -*-
-#
-# gtk-doc - GTK DocBook documentation generator.
-# Copyright (C) 1998 Damon Chaplin
-#
-# 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.
-#
-
-#############################################################################
-# Script : gtkdoc-mktmpl
-# Description : This creates or updates the template files which contain the
-# manually-edited documentation. (A 'template' is a simple text
-# form which is filled in with the description of a function,
-# macro, enum, or struct. For functions and macros it also
-# contains fields for describing the parameters.)
-#
-# This script reads in the existing templates, found in
-# tmpl/*.sgml, moves these files to tmpl/*.sgml.bak, and then
-# recreates the .sgml files according to the structure given in
-# the file $MODULE-sections.txt.
-#
-# Any new templates added, or new function parameters, are
-# marked with 'FIXME' so you can do a grep to see which parts
-# need updating.
-#
-# Any templates which are no longer used (i.e. they are remove
-# from $MODULE-sections.txt) are placed in the file
-# tmpl/$MODULE-unused.sgml. If they are included again later
-# they are automatically copied back into position.
-# If you are certain that these templates will never be used
-# again you can delete them from tmpl/$MODULE-unused.sgml.
-#
-# Any parameters to functions which are no longer used are
-# separated from the rest of the parameters with the line
-# '<!-- # Unused Parameters # -->'. It may be that the parameter
-# name has just been changed, in which case you can copy the
-# description to the parameter with the new name. You can delete
-# the unused parameter descriptions when no longer needed.
-#############################################################################
-
-use strict;
-use Getopt::Long;
-
-push @INC, '@PACKAGE_DATA_DIR@';
-require "gtkdoc-common.pl";
-
-# Options
-
-# name of documentation module
-my $MODULE;
-my $TMPL_DIR;
-my $FLAG_CHANGES;
-my $PRINT_VERSION;
-my $PRINT_HELP;
-my $ONLY_SECTION_TMPL;
-
-my %optctl = ('module' => \$MODULE,
- 'flag-changes' => \$FLAG_CHANGES,
- 'output-dir' => \$TMPL_DIR,
- 'only-section-tmpl' => \$ONLY_SECTION_TMPL,
- 'version' => \$PRINT_VERSION,
- 'help' => \$PRINT_HELP);
-GetOptions(\%optctl, "module=s", "flag-changes!", "output-dir:s", "only-section-tmpl!", "version", "help");
-
-if ($PRINT_VERSION) {
- print "@VERSION@\n";
- exit 0;
-}
-
-if (!$MODULE) {
- $PRINT_HELP = 1;
-}
-
-if ($PRINT_HELP) {
- print <<EOF;
-gtkdoc-mktmpl version @VERSION@ - generate documentation templates
-
---module=MODULE_NAME Name of the doc module being parsed
---flag-changes If specified, changes in templates are flagged
---output-dir=DIRNAME The directory where the results are stored
---only-section-tmpl Only include section information in templates
---version Print the version of this program
---help Print this help
-EOF
- exit 0;
-}
-
-print <<EOF;
-###############################################################################
-gtkdoc-mktmpl is deprecated and will be removed from one of the next gtk-doc
-release.
-Please refer to the documentation "Modernizing the documentation"/"GTK-Doc 1.9".
-###############################################################################
-EOF
-
-my $ROOT_DIR = ".";
-
-# The directory containing the template files.
-$TMPL_DIR = $TMPL_DIR ? $TMPL_DIR : "$ROOT_DIR/tmpl";
-
-# This file contains the object hierarchy.
-my $OBJECT_TREE_FILE = "$ROOT_DIR/$MODULE.hierarchy";
-
-# The file containing signal handler prototype information.
-my $SIGNALS_FILE = "$ROOT_DIR/$MODULE.signals";
-
-# The file containing Arg information.
-my $ARGS_FILE = "$ROOT_DIR/$MODULE.args";
-
-# Set the flag to indicate changes, if requested.
-my $CHANGES_FLAG = $FLAG_CHANGES ? "FIXME" : "";
-
-# These global arrays store information on signals. Each signal has an entry
-# in each of these arrays at the same index, like a multi-dimensional array.
-my @SignalObjects; # The GtkObject which emits the signal.
-my @SignalNames; # The signal name.
-my @SignalReturns; # The return type.
-my @SignalFlags; # Flags for the signal
-my @SignalPrototypes; # The rest of the prototype of the signal handler.
-
-# These global arrays store information on Args. Each Arg has an entry
-# in each of these arrays at the same index, like a multi-dimensional array.
-my @ArgObjects; # The GtkObject which has the Arg.
-my @ArgNames; # The Arg name.
-my @ArgTypes; # The Arg type - gint, GtkArrowType etc.
-my @ArgFlags; # How the Arg can be used - readable/writable etc.
-
-# These global hashes store declaration info keyed on a symbol name.
-my %Declarations;
-my %DeclarationTypes;
-my %DeclarationConditional;
-my %DeclarationOutput;
-
-# These global hashes store the existing documentation.
-my %SymbolDocs;
-my %SymbolTypes;
-my %SymbolParams;
-my %SymbolSourceFile;
-my %SymbolSourceLine;
-
-# These global arrays store GObject and subclasses and the hierarchy.
-my @Objects;
-my @ObjectLevels;
-
-&ReadSignalsFile ($SIGNALS_FILE);
-&ReadArgsFile ($ARGS_FILE);
-&ReadObjectHierarchy;
-
-&ReadDeclarationsFile ("$ROOT_DIR/$MODULE-decl.txt", 0);
-if (-f "$ROOT_DIR/$MODULE-overrides.txt") {
- &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-overrides.txt", 1);
-}
-&ReadExistingTemplates;
-
-my $changed = 0;
-
-if (&UpdateTemplates ("$ROOT_DIR/$MODULE-sections.txt")) {
- $changed = 1;
-}
-&OutputUnusedTemplates;
-if (&CheckAllDeclarationsOutput) {
- $changed = 1;
-}
-
-if ($changed || ! -e "$ROOT_DIR/tmpl.stamp") {
- open (TIMESTAMP, ">$ROOT_DIR/tmpl.stamp")
- || die "Can't create $ROOT_DIR/tmpl.stamp";
- print (TIMESTAMP "timestamp");
- close (TIMESTAMP);
-}
-
-#############################################################################
-# Function : ReadExistingTemplates
-# Description : This reads in all the existing documentation, into the global
-# variables %SymbolDocs, %SymbolTypes, and %SymbolParams (a
-# hash of arrays).
-# Arguments : none
-#############################################################################
-
-sub ReadExistingTemplates {
- %SymbolDocs = ();
- %SymbolTypes = ();
- %SymbolParams = ();
-
- # Read the unused docs first, so they get overridden by any real docs.
- # (though this shouldn't happen often).
- my $unused_doc = "$TMPL_DIR/$MODULE-unused.sgml";
- if (-e $unused_doc) {
- &ReadTemplateFile ($unused_doc, 0);
- }
-
- while (<$TMPL_DIR/*.sgml>) {
-# print "Reading $_\n";
- if ($_ eq $unused_doc) {
-# print "skipping $unused_doc\n";
- } else {
- &ReadTemplateFile ($_, 0);
- }
- }
-}
-
-
-#############################################################################
-# Function : UpdateTemplates
-# Description : This collects the output for each section of the docs, and
-# outputs each file when the end of the section is found.
-# Arguments : $file - the file containing the sections of the docs.
-#############################################################################
-
-sub UpdateTemplates {
- my ($file) = @_;
-# print "Reading: $file\n";
-
- open (INPUT, $file)
- || die "Can't open $file";
-
- # Create the top output directory if it doesn't exist.
- if (! -e $TMPL_DIR) {
- mkdir ("$TMPL_DIR", 0777)
- || die "Can't create directory: $TMPL_DIR";
- }
-
- my $filename = "";
- my $title = "";
- my $subsection = "";
- my $output;
- my $changed = 0;
- while (<INPUT>) {
- if (m/^#/) {
- next;
-
- } elsif (m/^<SECTION>/) {
- $output = "";
-
- } elsif (m/^<SUBSECTION\s*(.*)>/i) {
- $subsection = $1;
- next;
-
- } elsif (m/^<TITLE>(.*)<\/TITLE>/) {
- $title = $1;
-# print "Section: $title\n";
-
- } elsif (m/^<FILE>(.*)<\/FILE>/) {
- $filename = $1;
-
- } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
- next;
-
- } elsif (m/^<\/SECTION>/) {
- if ($title eq "") {
- $title = $filename;
- }
-# print "End of section: $title\n";
-
- $filename =~ s/\s/_/g;
- $filename .= ".sgml";
-
- if (&OutputTemplateFile ($filename, $title, \$output)) {
- $changed = 1;
- }
-
- $title = "";
- $subsection = "";
-
- } elsif (m/^(\S+)/) {
- my $symbol = $1;
-# print " Symbol: $symbol\n";
-
- my $declaration = $Declarations{$1};
- if (defined ($declaration)) {
- # We don't want templates for standard macros/functions of
- # GObjects or private declarations.
- if ($subsection ne "Standard" && $subsection ne "Private") {
- $output .= &OutputDeclaration ($DeclarationTypes {$symbol},
- $symbol, $declaration);
-
- $output .= &OutputSignalTemplates ($symbol);
- $output .= &OutputArgTemplates ($symbol);
- }
-
- # Note that the declaration has been output.
- $DeclarationOutput{$symbol} = 1;
-
- if ($declaration eq '##conditional##') {
-# print "Conditional $DeclarationTypes{$symbol}\n";
- }
-
- } else {
- &LogWarning ($file, $., "No declaration found for: $1");
- }
- }
- }
- close (INPUT);
-
- return $changed;
-}
-
-
-#############################################################################
-# Function : CheckAllDeclarationsOutput
-# Description : This steps through all the declarations that were loaded, and
-# makes sure that each one has been output, by checking the
-# corresponding flag in the %DeclarationOutput hash. It is
-# intended to check that any new declarations in new versions
-# of the module get added to the $MODULE-sections.txt file.
-# Arguments : none
-#############################################################################
-
-sub CheckAllDeclarationsOutput {
- my $num_unused = 0;
-
- my $old_unused_file = "$ROOT_DIR/$MODULE-unused.txt";
- my $new_unused_file = "$ROOT_DIR/$MODULE-unused.new";
-
- open (UNUSED, ">$new_unused_file")
- || die "Can't open $new_unused_file";
- my ($symbol);
- foreach $symbol (sort keys (%Declarations)) {
- if (!defined ($DeclarationOutput{$symbol})) {
- print (UNUSED "$symbol\n");
- $num_unused++;
- }
- }
- close (UNUSED);
- if ($num_unused != 0) {
- &LogWarning ($old_unused_file, 1, "$num_unused unused declarations.".
- "They should be added to $MODULE-sections.txt in the appropriate place.");
- }
-
- return &UpdateFileIfChanged ($old_unused_file, $new_unused_file, 0);
-}
-
-
-#############################################################################
-# Function : OutputDeclaration
-# Description : This returns the template for one symbol & declaration.
-# Note that it uses the global %SymbolDocs and %SymbolParams to
-# lookup any existing documentation.
-# Arguments : $type - the type of the symbol ('FUNCTION'/'MACRO' etc.)
-# $symbol - the symbol name.
-# $declaration - the declaration of the symbol.
-#############################################################################
-
-sub OutputDeclaration {
- my ($type, $symbol, $declaration) = @_;
- my ($output) = "";
-
- #print "Outputting $type: $symbol\n";
-
- # See if symbol already has a description.
- my ($symbol_desc) = $SymbolDocs{$symbol};
- my ($template_exists);
- if (defined ($symbol_desc)) {
- $template_exists = 1;
- $symbol_desc =~ s/\s+$//;
- } else {
- $template_exists = 0;
- $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>";
- }
-
- $output .= <<EOF;
-<!-- ##### $type $symbol ##### -->
-$symbol_desc
-
-EOF
-
- # For functions, function typedefs and macros, we output the arguments.
- # For functions and function typedefs we also output the return value.
- if ($type eq "FUNCTION" || $type eq "USER_FUNCTION") {
- # Take out the return type
- $declaration =~ s/<RETURNS>\s*(.*?)<\/RETURNS>\n//;
- my $ret_type_decl = $1;
- my $ret_type_modifier;
- my $ret_type;
- my $ret_type_pointer;
-
- if ($ret_type_decl =~ m/((const\s+|G_CONST_RETURN\s+|unsigned\s+|signed\s+|long\s+|short\s+|struct\s+|enum\s+)*)(\w+)\s*(\**\s*(const|G_CONST_RETURN)?\s*\**\s*(restrict)?\s*)/) {
- $ret_type_modifier = defined($1) ? $1 : "";
- $ret_type = $3;
- $ret_type_pointer = $4;
- } else {
- $ret_type = "void";
- }
-
- my @fields = ParseFunctionDeclaration($declaration);
-
- for (my $i = 0; $i <= $#fields; $i += 2) {
- my $field_name = $fields[$i];
- $output .= &OutputParam ($symbol, $field_name, $template_exists, 1, "");
- }
-
- if ($ret_type ne "void" || $ret_type_modifier || $ret_type_pointer) {
- $output .= &OutputParam ($symbol, "Returns", $template_exists, 1, "");
- }
-
- $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
- $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
- $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
- $output .= &OutputOldParams ($symbol);
- $output .= "\n";
- }
-
- if ($type eq "MACRO") {
- my @fields = ParseMacroDeclaration($declaration);
-
- for (my $i = 0; $i <= $#fields; $i +=2) {
- my $field_name = $fields[$i];
-
- $output .= &OutputParam ($symbol, $field_name, $template_exists,
- 1, "");
- }
- $output .= &OutputParam ($symbol, "Returns", $template_exists, 0, "");
- $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
- $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
- $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
- $output .= &OutputOldParams ($symbol);
- $output .= "\n";
- }
-
- if ($type eq "STRUCT") {
- my $is_object_struct = CheckIsObject ($symbol);
- my @fields = ParseStructDeclaration($declaration, $is_object_struct, 1);
-
- for (my $i = 0; $i <= $#fields; $i += 2) {
- my $field_name = $fields[$i];
- $output .= &OutputParam ($symbol, $field_name, $template_exists, 1, "");
- }
- $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
- $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
- $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
- }
-
- if ($type eq "ENUM") {
- my @members = ParseEnumDeclaration($declaration);
-
- for my $member (@members) {
- $output .= &OutputParam ($symbol, $member, $template_exists, 1, "");
- }
- $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
- $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
- $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
- }
-
- $output .= "\n";
-
- # Remove the used docs from the hashes.
- if ($template_exists) {
- delete $SymbolDocs{$symbol};
- delete $SymbolParams{$symbol};
- }
-
- return $output;
-}
-
-
-#############################################################################
-# Function : OutputParam
-# Description : This outputs the part of a template for one parameter.
-# It first checks if the parameter is already described, and if
-# so it uses that description, and clears it so it isn't output
-# as an old param.
-# Arguments : $symbol - the symbol (function or macro) name.
-# $param_to_output - the parameter to add.
-# $template_exists - TRUE if the template already existed in
-# template files. If it did, then we will flag any changes
-# with 'FIXME'.
-# $force_output - TRUE if the parameter should be output even
-# if it didn't already exist in the template. (The return
-# values of macros are added manually if required, and so we
-# never add it here - we only copy it if it already exists.)
-# $default_description - the default description of the
-# parameter to be used if it doesn't already exist. (Signal
-# handlers have a few common parameters.)
-#############################################################################
-
-sub OutputParam {
- my ($symbol, $param_to_output, $template_exists,
- $force_output, $default_description) = @_;
- my ($j);
-
- my ($params) = $SymbolParams{$symbol};
- if (defined ($params)) {
- for ($j = 0; $j <= $#$params; $j += 2) {
- my $param_name = $$params[$j];
- my $param_desc = $$params[$j + 1];
-
- if ($param_name eq $param_to_output) {
- $param_desc =~ s/\s+$//;
- $$params[$j] = "";
- $$params[$j + 1] = "";
- return "\@$param_name: $param_desc\n";
- }
- }
- }
-
- # If the template was already in a file, flag the new parameter.
- # If not, the template itself will be flagged, so we don't need to flag
- # all the new parameters as well.
- if ($force_output) {
- if ($default_description ne "") {
- $default_description =~ s/\s+$//;
- return "\@$param_to_output: $default_description\n";
- } else {
- if ($template_exists) {
- return "\@$param_to_output: $CHANGES_FLAG\n";
- } else {
- return "\@$param_to_output: \n";
- }
- }
- }
- return "";
-}
-
-
-#############################################################################
-# Function : OutputOldParams
-# Description : This returns all the existing documentation for parameters of
-# the given function/macro/signal symbol which are unused, with
-# a comment before them.
-# Arguments : $symbol - the symbol (function/macro/signal) name.
-#############################################################################
-
-sub OutputOldParams {
- my ($symbol) = @_;
- my $output = "";
-
- my ($params) = $SymbolParams{$symbol};
- if (defined ($params)) {
- my $j;
- for ($j = 0; $j <= $#$params; $j += 2) {
- my $param_name = $$params[$j];
- my $param_desc = $$params[$j + 1];
-
- if ($param_name ne "") {
- $param_desc =~ s/\s+$//;
-
- # There's no point keeping it if it has no docs.
- if ($param_desc ne "") {
- $output .= "\@$param_name: $param_desc\n";
- }
- }
- }
- }
- if ($output) {
- $output = "<!-- # Unused Parameters # -->\n" . $output;
- }
- return $output;
-}
-
-
-#############################################################################
-# Function : OutputTemplateFile
-# Description : This outputs one template file.
-# Arguments : $file - the basename of the file to output.
-# $title - the title from the $MODULE-sections.txt file. This
-# will be overridden by any title given in the template file.
-# $output - reference to the templates to output.
-#############################################################################
-
-sub OutputTemplateFile {
- my ($file, $title, $output) = @_;
-
- my ($short_desc, $long_desc, $see_also, $stability, $image);
-
- if (defined ($SymbolDocs{"$TMPL_DIR/$file:Title"})) {
- $title = $SymbolDocs{"$TMPL_DIR/$file:Title"};
- delete $SymbolDocs{"$TMPL_DIR/$file:Title"};
- }
- if (defined ($SymbolDocs{"$TMPL_DIR/$file:Short_Description"})) {
- $short_desc = $SymbolDocs{"$TMPL_DIR/$file:Short_Description"};
- delete $SymbolDocs{"$TMPL_DIR/$file:Short_Description"};
- } else {
- $short_desc = "";
- }
- if (defined ($SymbolDocs{"$TMPL_DIR/$file:Long_Description"})) {
- $long_desc = $SymbolDocs{"$TMPL_DIR/$file:Long_Description"};
- delete $SymbolDocs{"$TMPL_DIR/$file:Long_Description"};
- } else {
- $long_desc = "<para>\n\n</para>\n";
- }
- if (defined ($SymbolDocs{"$TMPL_DIR/$file:See_Also"})) {
- $see_also = $SymbolDocs{"$TMPL_DIR/$file:See_Also"};
- delete $SymbolDocs{"$TMPL_DIR/$file:See_Also"};
- } else {
- $see_also = "<para>\n\n</para>\n";
- }
- if (defined ($SymbolDocs{"$TMPL_DIR/$file:Stability_Level"})) {
- $stability = $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"};
- delete $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"};
- } else {
- $stability = "";
- }
- if (defined ($SymbolDocs{"$TMPL_DIR/$file:Image"})) {
- $image = $SymbolDocs{"$TMPL_DIR/$file:Image"};
- delete $SymbolDocs{"$TMPL_DIR/$file:Image"};
- } else {
- $image = "";
- }
-
-
- my $old_tmpl_file = "$TMPL_DIR/$file";
- my $new_tmpl_file = "$TMPL_DIR/$file.new";
-
- open (OUTPUT, ">$new_tmpl_file")
- || die "Can't create $new_tmpl_file";
-
- print (OUTPUT <<EOF);
-<!-- ##### SECTION Title ##### -->
-$title
-
-<!-- ##### SECTION Short_Description ##### -->
-$short_desc
-
-<!-- ##### SECTION Long_Description ##### -->
-$long_desc
-
-<!-- ##### SECTION See_Also ##### -->
-$see_also
-
-<!-- ##### SECTION Stability_Level ##### -->
-$stability
-
-<!-- ##### SECTION Image ##### -->
-$image
-
-EOF
-
- print (OUTPUT $$output) unless $ONLY_SECTION_TMPL;
- close (OUTPUT);
-
- return &UpdateFileIfChanged ($old_tmpl_file, $new_tmpl_file, 1);
-}
-
-
-#############################################################################
-# Function : OutputSignalTemplates
-# Description : Outputs templates for signal handlers.
-# Arguments : $title - the title from the $MODULE-sections.txt file. If the
-# file is describing a GtkObject subclass, the title should
-# be the name of the class, e.g. 'GtkButton'.
-#############################################################################
-
-sub OutputSignalTemplates {
- my ($title) = @_;
-
- my $output = "";
- my ($i, $template_exists);
- for ($i = 0; $i <= $#SignalObjects; $i++) {
- if ($SignalObjects[$i] eq $title) {
-# print "Found signal: $SignalObjects[$i]\n";
- my ($symbol) = "$SignalObjects[$i]::$SignalNames[$i]";
-
- # See if symbol already has a description.
- my ($symbol_desc) = $SymbolDocs{$symbol};
- if (defined ($symbol_desc)) {
- $template_exists = 1;
- $symbol_desc =~ s/\s+$//;
- delete $SymbolDocs{$symbol};
- } else {
- $template_exists = 0;
- $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>";
- }
-
- $output .= <<EOF;
-<!-- ##### SIGNAL $symbol ##### -->
-$symbol_desc
-
-EOF
- my $sourceparams = $SymbolParams{$symbol};
- my @params = split ("[,\n]", $SignalPrototypes[$i]);
- my ($j, $name);
- for ($j = 0; $j <= $#params; $j++) {
- my $param = $params[$j];
- $param =~ s/^\s+//;
- $param =~ s/\s*$//;
- if ($param =~ m/^\s*$/) { next; }
- if ($param =~ m/^void$/) { next; }
-
- if ($param =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)?\s*$/) {
- if (defined ($sourceparams)) {
- $name = $$sourceparams[2 * $j];
- } else {
- $name = $3;
- }
-
- if (!defined ($name)) {
- $name = "Param" . ($j + 1);
- }
-
- if ($j == 0) {
- $output .= &OutputParam ($symbol, $name,
- $template_exists, 1,
- "the object which received the signal.");
- } else {
- $output .= &OutputParam ($symbol, $name,
- $template_exists, 1, "");
- }
- }
- }
-
- if ($SignalReturns[$i] ne "void") {
- $output .= &OutputParam ($symbol, "Returns", $template_exists,
- 1, "");
- }
- $output .= &OutputOldParams ($symbol);
- $output .= "\n";
- }
- }
- return $output;
-}
-
-
-#############################################################################
-# Function : OutputArgTemplates
-# Description : Outputs templates for Args.
-# Arguments : $title - the title from the $MODULE-sections.txt file. If the
-# file is describing a GtkObject subclass, the title should
-# be the name of the class, e.g. 'GtkButton'.
-#############################################################################
-
-sub OutputArgTemplates {
- my ($title) = @_;
-
- my $output = "";
- my $i;
- for ($i = 0; $i <= $#ArgObjects; $i++) {
- if ($ArgObjects[$i] eq $title) {
-# print "Found arg: $ArgObjects[$i]\n";
- # I've only used one colon so we don't clash with signals.
- my ($symbol) = "$ArgObjects[$i]:$ArgNames[$i]";
-
- # See if symbol already has a description.
- my ($symbol_desc) = $SymbolDocs{$symbol};
- if (defined ($symbol_desc)) {
- delete $SymbolDocs{$symbol};
- $symbol_desc =~ s/\s+$//;
- } else {
- $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>";
- }
-
- $output .= <<EOF;
-<!-- ##### ARG $symbol ##### -->
-$symbol_desc
-
-EOF
- }
- }
- return $output;
-}
-
-
-#############################################################################
-# Function : OutputUnusedTemplates
-# Description : This saves any unused documentation into $MODULE-unused.sgml.
-# Arguments : none
-#############################################################################
-
-sub OutputUnusedTemplates {
- my ($old_unused_file) = "$TMPL_DIR/$MODULE-unused.sgml";
- my ($new_unused_file) = "$TMPL_DIR/$MODULE-unused.new";
-
- open (UNUSED, ">$new_unused_file")
- || die "Can't open file: $new_unused_file";
-
- my $output = "";
- my ($symbol, $symbol_desc);
- for $symbol (sort keys %SymbolDocs) {
- $symbol_desc = $SymbolDocs{$symbol};
-
-# print "Unused: $symbol\n";
-
- my $type = $SymbolTypes{$symbol};
- if (!defined ($type)) {
- $type = "UNKNOWN";
- &LogWarning ($SymbolSourceFile{$symbol},$SymbolSourceLine{$symbol}, "Unused symbol $symbol has unknown type.");
- }
-
- $output .= <<EOF;
-<!-- ##### $type $symbol ##### -->
-$symbol_desc
-
-EOF
-
- my ($params) = $SymbolParams{$symbol};
- if (defined ($params)) {
- my $j;
- for ($j = 0; $j <= $#$params; $j += 2) {
- my $param_name = $$params[$j];
- my $param_desc = $$params[$j + 1];
- $param_desc =~ s/\s+$//;
- $output .= "\@$param_name: $param_desc\n";
- }
- }
- $output .= "\n";
- }
-
- print UNUSED $output;
- close (UNUSED);
-
- &UpdateFileIfChanged ($old_unused_file, $new_unused_file, 1);
-}
-
-
-#############################################################################
-# LIBRARY FUNCTIONS - These functions are used in both gtkdoc-mkdb and
-# gtkdoc-mktmpl and should eventually be moved to a
-# separate library.
-#############################################################################
-
-#############################################################################
-# Function : ReadDeclarationsFile
-# Description : This reads in a file containing the function/macro/enum etc.
-# declarations.
-#
-# Note that in some cases there are several declarations with
-# the same name, e.g. for conditional macros. In this case we
-# set a flag in the %DeclarationConditional hash so the
-# declaration is not shown in the docs.
-#
-# If a macro and a function have the same name, e.g. for
-# gtk_object_ref, the function declaration takes precedence.
-#
-# Some opaque structs are just declared with 'typedef struct
-# _name name;' in which case the declaration may be empty.
-# The structure may have been found later in the header, so
-# that overrides the empty declaration.
-#
-# Arguments : $file - the declarations file to read
-# $override - if declarations in this file should override
-# any current declaration.
-#############################################################################
-
-sub ReadDeclarationsFile {
- my ($file, $override) = @_;
-
- if ($override == 0) {
- %Declarations = ();
- %DeclarationTypes = ();
- %DeclarationConditional = ();
- %DeclarationOutput = ();
- }
-
- open (INPUT, $file)
- || die "Can't open $file";
- my $declaration_type = "";
- my $declaration_name;
- my $declaration;
- while (<INPUT>) {
- if (!$declaration_type) {
- if (m/^<([^>]+)>/) {
- $declaration_type = $1;
- $declaration_name = "";
-# print "Found declaration: $declaration_type\n";
- $declaration = "";
- }
- } else {
- if (m%^<NAME>(.*)</NAME>%) {
- $declaration_name = $1;
- } elsif (m%<DEPRECATED/>%) {
- # do nothing, just skip the line; we handle this
- # in mkdb
- } elsif (m%^</$declaration_type>%) {
-# print "Found end of declaration: $declaration_name\n";
- # Check that the declaration has a name
- if ($declaration_name eq "") {
- print "ERROR: $declaration_type has no name $file:$.\n";
- }
-
- # Check if the symbol is already defined.
- if (defined ($Declarations{$declaration_name})
- && $override == 0) {
- # Function declarations take precedence.
- if ($DeclarationTypes{$declaration_name} eq 'FUNCTION') {
- # Ignore it.
- } elsif ($declaration_type eq 'FUNCTION') {
- $Declarations{$declaration_name} = $declaration;
- $DeclarationTypes{$declaration_name} = $declaration_type;
- } elsif ($DeclarationTypes{$declaration_name}
- eq $declaration_type) {
- # If the existing declaration is empty, or is just a
- # forward declaration of a struct, override it.
- if ($declaration_type eq 'STRUCT') {
- if ($Declarations{$declaration_name} =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) {
- $Declarations{$declaration_name} = $declaration;
- } elsif ($declaration =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) {
- # Ignore an empty or forward declaration.
- } else {
- &LogWarning ($file, $., "Structure $declaration_name has multiple definitions.");
- }
-
- } else {
- # set flag in %DeclarationConditional hash for
- # multiply defined macros/typedefs.
- $DeclarationConditional{$declaration_name} = 1;
- }
- } else {
- &LogWarning ($file, $., "$declaration_name has multiple definitions.");
- }
- } else {
- $Declarations{$declaration_name} = $declaration;
- $DeclarationTypes{$declaration_name} = $declaration_type;
- }
- $declaration_type = "";
- } else {
- $declaration .= $_;
- }
- }
- }
- close (INPUT);
-}
-
-
-#############################################################################
-# Function : ReadSignalsFile
-# Description : This reads in an existing file which contains information on
-# all GObject signals. It creates the arrays @SignalNames and
-# @SignalPrototypes containing info on the signals. The first
-# line of the SignalPrototype is the return type of the signal
-# handler. The remaining lines are the parameters passed to it.
-# The last parameter, "gpointer user_data" is always the same
-# so is not included.
-# Arguments : $file - the file containing the signal handler prototype
-# information.
-#############################################################################
-
-sub ReadSignalsFile {
- my ($file) = @_;
-
- my $in_signal = 0;
- my $signal_object;
- my $signal_name;
- my $signal_returns;
- my $signal_flags;
- my $signal_prototype;
-
- # Reset the signal info.
- @SignalObjects = ();
- @SignalNames = ();
- @SignalReturns = ();
- @SignalFlags = ();
- @SignalPrototypes = ();
-
- if (! -f $file) {
- return;
- }
- if (!open (INPUT, $file)) {
- warn "Can't open $file - skipping signals\n";
- return;
- }
- while (<INPUT>) {
- if (!$in_signal) {
- if (m/^<SIGNAL>/) {
- $in_signal = 1;
- $signal_object = "";
- $signal_name = "";
- $signal_returns = "";
- $signal_prototype = "";
- }
- } else {
- if (m/^<NAME>(.*)<\/NAME>/) {
- $signal_name = $1;
- if ($signal_name =~ m/^(.*)::(.*)$/) {
- $signal_object = $1;
- ($signal_name = $2) =~ s/_/-/g;
-# print "Found signal: $signal_name\n";
- } else {
- print "Invalid signal name: $signal_name\n";
- }
- } elsif (m/^<RETURNS>(.*)<\/RETURNS>/) {
- $signal_returns = $1;
- } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
- $signal_flags = $1;
- } elsif (m%^</SIGNAL>%) {
-# print "Found end of signal: ${signal_object}::${signal_name}\nReturns: ${signal_returns}\n${signal_prototype}";
- push (@SignalObjects, $signal_object);
- push (@SignalNames, $signal_name);
- push (@SignalReturns, $signal_returns);
- push (@SignalFlags, $signal_flags);
- push (@SignalPrototypes, $signal_prototype);
- $in_signal = 0;
- } else {
- $signal_prototype .= $_;
- }
- }
- }
- close (INPUT);
-}
-
-
-#############################################################################
-# Function : ReadTemplateFile
-# Description : This reads in the manually-edited documentation file
-# corresponding to the file currently being created, so we can
-# insert the documentation at the appropriate places.
-# It outputs %SymbolTypes, %SymbolDocs and %SymbolParams, which
-# is a hash of arrays.
-# NOTE: This function is duplicated in gtkdoc-mkdb (but
-# slightly different).
-# Arguments : $docsfile - the template file to read in.
-# $skip_unused_params - 1 if the unused parameters should be
-# skipped.
-#############################################################################
-
-sub ReadTemplateFile {
- my ($docsfile, $skip_unused_params) = @_;
-
-# print "Reading $docsfile\n";
- if (! -f $docsfile) {
- print "File doesn't exist: $docsfile\n";
- return 0;
- }
-
- my $CurrentType = ""; # Type of symbol being read.
- my $CurrentSymbol = ""; # Name of symbol being read.
- my $SymbolDoc = ""; # Description of symbol being read.
- my @Params; # Parameter names and descriptions of current
- # function/macro/function typedef.
- my $CurrentParam = -1; # Index of parameter currently being read.
- # Note that the param array contains pairs
- # of param name & description.
- my $InUnusedParameters = 0; # True if we are reading in the unused params.
-
- open (DOCS, $docsfile)
- || die "Can't open file $docsfile: $!";
- while (<DOCS>) {
- if (m/^<!-- ##### ([A-Z_]+) (\S+) ##### -->/) {
- my $type = $1;
- my $symbol = $2;
- if ($symbol eq "Title"
- || $symbol eq "Short_Description"
- || $symbol eq "Long_Description"
- || $symbol eq "See_Also"
- || $symbol eq "Stability_Level"
- || $symbol eq "Image") {
- $symbol = $docsfile . ":" . $symbol;
- }
-
- #print "Found symbol: $symbol\n";
- # Remember file and line for the symbol
- $SymbolSourceFile{$symbol} = $docsfile;
- $SymbolSourceLine{$symbol} = $.;
-
- # Canonicalize signal and argument names to have -, not _
- if ($type eq "ARG" || $type eq "SIGNAL") {
- $symbol =~ s/_/-/g;
- }
-
- # Store previous symbol, but remove any trailing blank lines.
- if ($CurrentSymbol ne "") {
- $SymbolDoc =~ s/\s+$//;
- $SymbolTypes{$CurrentSymbol} = $CurrentType;
- $SymbolDocs{$CurrentSymbol} = $SymbolDoc;
-
- if ($CurrentParam >= 0) {
- $SymbolParams{$CurrentSymbol} = [ @Params ];
- } else {
- # Delete any existing params in case we are overriding a
- # previously read template.
- delete $SymbolParams{$CurrentSymbol};
- }
- }
- $CurrentType = $type;
- $CurrentSymbol = $symbol;
- $CurrentParam = -1;
- $InUnusedParameters = 0;
- $SymbolDoc = "";
- @Params = ();
-
- } elsif (m/^<!-- # Unused Parameters # -->/) {
- $InUnusedParameters = 1;
- next;
-
- } else {
- # Workaround for an old bug that left a mess in the templates.
- # This happened with macros with args spread over several lines.
- if (m/^\@\\$/) {
- # Skip the next line.
- $_ = <DOCS>;
- next;
- }
-
- # Workaround for an old bug that left '@:' at start of lines.
- if (m/^\@:$/) {
- next;
- }
-
-
- # Check if param found. Need to handle "..." and "format...".
- if (s/^\@([\w\.]+):\040?//) {
- my $param_name = $1;
- # Allow variations of 'Returns'
- if ($param_name =~ m/^[Rr]eturns?$/) {
- $param_name = "Returns";
- }
-# print "Found param: $param_name\n";
- push (@Params, $param_name);
- push (@Params, $_);
- $CurrentParam += 2;
- next;
- }
-
- # When outputting the DocBook we skip unused parameters.
- if (!$InUnusedParameters || !$skip_unused_params) {
- if ($CurrentParam >= 0) {
- $Params[$CurrentParam] .= $_;
- } else {
- $SymbolDoc .= $_;
- }
- }
- }
- }
-
- # Remember to finish the current symbol doccs.
- if ($CurrentSymbol ne "") {
-
- $SymbolDoc =~ s/\s+$//;
- $SymbolTypes{$CurrentSymbol} = $CurrentType;
- $SymbolDocs{$CurrentSymbol} = $SymbolDoc;
-
- if ($CurrentParam >= 0) {
- $SymbolParams{$CurrentSymbol} = [ @Params ];
- } else {
- delete $SymbolParams{$CurrentSymbol};
- }
- }
-
- close (DOCS);
- return 1;
-}
-
-
-#############################################################################
-# Function : ReadObjectHierarchy
-# Description : This reads in the $MODULE-hierarchy.txt file containing all
-# the GtkObject subclasses described in this module (and their
-# ancestors).
-# It places them in the @Objects array, and places their level
-# in the widget hierarchy in the @ObjectLevels array, at the
-# same index. GtkObject, the root object, has a level of 1.
-#
-# FIXME: the version in gtkdoc-mkdb also generates tree_index.sgml
-# as it goes along, this should be split out into a separate
-# function.
-#
-# Arguments : none
-#############################################################################
-
-sub ReadObjectHierarchy {
- @Objects = ();
- @ObjectLevels = ();
-
- if (! -f $OBJECT_TREE_FILE) {
- return;
- }
- if (!open (INPUT, $OBJECT_TREE_FILE)) {
- warn "Can't open $OBJECT_TREE_FILE - skipping object tree\n";
- return;
- }
- while (<INPUT>) {
- if (m/\S+/) {
- my $object = $&;
- my $level = (length($`)) / 2 + 1;
-# print ("Level: $level Object: $object\n");
-
- push (@Objects, $object);
- push (@ObjectLevels, $level);
- }
- }
-
- close (INPUT);
-}
-
-
-#############################################################################
-# Function : ReadArgsFile
-# Description : This reads in an existing file which contains information on
-# all GObject args. It creates the arrays @ArgObjects, @ArgNames,
-# @ArgTypes and @ArgFlags containing info on the args.
-# Arguments : $file - the file containing the arg information.
-#############################################################################
-
-sub ReadArgsFile {
- my ($file) = @_;
-
- my $in_arg = 0;
- my $arg_object;
- my $arg_name;
- my $arg_type;
- my $arg_flags;
-
- # Reset the signal info.
- @ArgObjects = ();
- @ArgNames = ();
- @ArgTypes = ();
- @ArgFlags = ();
-
- if (! -f $file) {
- return;
- }
- if (!open (INPUT, $file)) {
- warn "Can't open $file - skipping args\n";
- return;
- }
- while (<INPUT>) {
- if (!$in_arg) {
- if (m/^<ARG>/) {
- $in_arg = 1;
- $arg_object = "";
- $arg_name = "";
- $arg_type = "";
- $arg_flags = "";
- }
- } else {
- if (m/^<NAME>(.*)<\/NAME>/) {
- $arg_name = $1;
- if ($arg_name =~ m/^(.*)::(.*)$/) {
- $arg_object = $1;
- ($arg_name = $2) =~ s/_/-/g;
-# print "Found arg: $arg_name\n";
- } else {
- print "Invalid arg name: $arg_name\n";
- }
- } elsif (m/^<TYPE>(.*)<\/TYPE>/) {
- $arg_type = $1;
- } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
- $arg_flags = $1;
- } elsif (m%^</ARG>%) {
-# print "Found end of arg: ${arg_object}::${arg_name}\n${arg_type} : ${arg_flags}\n";
- push (@ArgObjects, $arg_object);
- push (@ArgNames, $arg_name);
- push (@ArgTypes, $arg_type);
- push (@ArgFlags, $arg_flags);
- $in_arg = 0;
- }
- }
- }
- close (INPUT);
-}
-
-
-#############################################################################
-# Function : CheckIsObject
-# Description : Returns 1 if the given name is a GObject or a subclass.
-# It uses the global @Objects array.
-# Note that the @Objects array only contains classes in the
-# current module and their ancestors - not all GObject classes.
-# Arguments : $name - the name to check.
-#############################################################################
-
-sub CheckIsObject {
- my ($name) = @_;
-
- my $object;
- foreach $object (@Objects) {
- if ($object eq $name) {
- return 1;
- }
- }
- return 0;
-}
-
-#!@PERL@ -w
-# -*- cperl -*-
+#!@PYTHON@
+# -*- python -*-
#
# gtk-doc - GTK DocBook documentation generator.
# Copyright (C) 1998 Damon Chaplin
-# Copyright (C) 2007 David Necas (Yeti)
+# 2007 David Necas (Yeti)
+# 2007-2016 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
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
-#############################################################################
-# Script : gtkdoc-rebase
-# Description : Rebases URI references in installed HTML documentation.
-#############################################################################
-
-use strict;
-use bytes;
-use Getopt::Long qw(:config gnu_getopt);
-use Cwd qw(realpath);
-
-# Options
-
-my $HTML_DIR;
-my @OTHER_DIRS;
-my $DEST_DIR;
-my $PRINT_VERSION;
-my $PRINT_HELP;
-my $AGGRESSIVE;
-my $ONLINE;
-my $RELATIVE;
-my $VERBOSE;
-
-# Maps.
-# These two point to the last seen URI of given type for a package:
-# OnlineMap: package => on-line URI
-# LocalMap: package => local URI
-# This maps all seen URIs of a package to fix broken links in the process:
-# RevMap: URI => package
-my (%OnlineMap, %LocalMap, %RevMap);
-# Remember what mangling we did.
-my %Mapped;
-
-
-run() unless caller; # Run program unless loaded as a module
-
-
-sub run {
- my %optctl = ('html-dir' => \$HTML_DIR,
- 'other-dir' => \@OTHER_DIRS,
- 'dest-dir' => \$DEST_DIR,
- 'online' => \$ONLINE,
- 'relative' => \$RELATIVE,
- 'aggressive' => \$AGGRESSIVE,
- 'verbose' => \$VERBOSE,
- 'version' => \$PRINT_VERSION,
- 'help' => \$PRINT_HELP);
- GetOptions(\%optctl, 'html-dir=s', 'other-dir=s@', 'dest-dir:s',
- 'online', 'relative', 'aggressive', 'verbose',
- 'version', 'help');
-
- if ($PRINT_VERSION) {
- print "@VERSION@\n";
- exit 0;
- }
-
- if ($PRINT_HELP) {
- print <<EOF;
-gtkdoc-rebase version @VERSION@ - rewrite the base url of html files
-
---html-dir=HTML_DIR The directory which contains the installed HTML
---other-dir=OTHER_DIR Directories to recursively scan for indices (index.sgml)
- May be used more than once for multiple directories
---online Prefer cross-references to online documents
---relative Prefer relative cross-references
---aggressive Rebase links to all files that are under a directory
- matching a package name.
---dest-dir=ROOT_DIR Staging area virtual root, this prefix will be removed
- from HTML_DIR fore relative link calculation.
---verbose Be verbose
---version Print the version of this program
---help Print this help
-EOF
- exit 0;
- }
-
- if (!$HTML_DIR) {
- die "No HTML directory (--html-dir) given.\n";
- }
-
- my $dir;
-
- # We scan the directory containing GLib and any directories in GNOME2_PATH
- # first, but these will be overriden by any later scans.
- if (defined ($ENV{"GNOME2_PATH"})) {
- foreach $dir (split(/:/, $ENV{"GNOME2_PATH"})) {
- $dir = $dir . "/share/gtk-doc/html";
- if ($dir && -d $dir) {
- print "Prepending GNOME2_PATH directory: $dir\n" if $VERBOSE;
- unshift @OTHER_DIRS, $dir;
- }
- }
- }
-
- $dir = `pkg-config --variable=prefix glib-2.0`;
- $dir =~ s/^\s*(\S*)\s*$/$1/;
- $dir = $dir . "/share/gtk-doc/html";
- print "Prepending GLib directory $dir\n" if $VERBOSE;
- unshift @OTHER_DIRS, $dir;
-
- # Check all other dirs, but skip already scanned dirs ord subdirs of those
- if ($DEST_DIR) {
- $DEST_DIR =~ s#/?$#/#;
- }
- $HTML_DIR =~ s#/?$#/#;
-
- foreach $dir (@OTHER_DIRS) {
- &ScanDirectory($dir, $HTML_DIR);
- }
-
- if ($RELATIVE) {
- &RelativizeLocalMap($HTML_DIR);
- }
-
- &RebaseReferences($HTML_DIR);
- &PrintWhatWeHaveDone();
-}
-
-
-sub ScanDirectory {
- my ($dir, $self) = @_;
- # This array holds any subdirectories found.
- my (@subdirs) = ();
-
- print "Scanning documentation directory $dir\n" if $VERBOSE;
-
- if ("$dir/" eq $self) {
- print "Excluding self\n" if $VERBOSE;
- return;
- }
- if (not opendir(HTMLDIR, $dir)) {
- print "Cannot open $dir: $!\n";
- return;
- }
-
- my $file;
- my $onlinedir;
- my $have_index = 0;
- foreach $file (readdir(HTMLDIR)) {
- if ($file eq '.' or $file eq '..') {
- next;
- }
- elsif (-d "$dir/$file") {
- push @subdirs, $file;
- next;
- }
- if ($file =~ m/\.devhelp2$/) {
- print "Reading index from $file\n" if $VERBOSE;
- my $o = &ReadDevhelp($dir, $file);
- # Prefer this location over possibly stale index.sgml
- if ($o) {
- $onlinedir = $o;
- }
- $have_index = 1;
- }
- if (!$onlinedir and ($file eq "index.sgml")) {
- print "Reading index from index.sgml\n" if $VERBOSE;
- $onlinedir = &ReadIndex($dir, $file);
- $have_index = 1;
- }
- elsif ($file eq "index.sgml.gz") {
- # debian/ubuntu started to compress this as index.sgml.gz :/
- print <<EOF;
-Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138 . For now run:
-gunzip $dir/$file
-EOF
- }
- elsif ($file =~ m/\.devhelp2.gz$/) {
- # debian/ubuntu started to compress this as *devhelp2.gz :/
- print <<EOF;
-Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/1466210 . For now run:
-gunzip $dir/$file
-EOF
- }
- # we could consider supporting: use IO::Zlib;
- }
- closedir (HTMLDIR);
- if ($have_index) {
- &AddMap($dir, $onlinedir);
- }
-
- # Now recursively scan the subdirectories.
- my $d;
- foreach my $subdir (@subdirs) {
- &ScanDirectory("$dir/$subdir", $self);
- }
-}
-
-
-sub ReadDevhelp {
- my ($dir, $file) = @_;
- my $onlinedir;
-
- open(INDEXFILE, "$dir/$file") || die "Can't open $dir/$file: $!";
- while (<INDEXFILE>) {
- # online must come before chapter/functions
- last if m/<(chapters|functions)/;
- if (m/ online="([^"]*)"/) {
- $onlinedir = $1;
- # Remove trailing non-directory component.
- $onlinedir =~ s#(.*/).*#$1#;
- }
- }
- close (INDEXFILE);
- return $onlinedir;
-}
-
-
-sub ReadIndex {
- my ($dir, $file) = @_;
- my $onlinedir;
-
- open(INDEXFILE, "$dir/$file") || die "Can't open $dir/$file: $!";
- while (<INDEXFILE>) {
- # ONLINE must come before any ANCHORs
- last if m/^<ANCHOR/;
- if (m/^<ONLINE\s+href\s*=\s*"([^"]+)"\s*>/) {
- $onlinedir = $1;
- # Remove trailing non-directory component.
- $onlinedir =~ s#(.*/).*#$1#;
- }
- }
- close (INDEXFILE);
- return $onlinedir;
-}
-
-
-sub AddMap {
- my ($dir, $onlinedir) = @_;
- my $package;
-
- $dir =~ s#/?$#/#;
- ($package = $dir) =~ s#.*/([^/]+)/#$1#;
- if ($DEST_DIR and substr($dir, 0, length $DEST_DIR) eq $DEST_DIR) {
- $dir = substr($dir, -1 + length $DEST_DIR);
- }
- if ($onlinedir) {
- print "On-line location of $package: $onlinedir\n" if $VERBOSE;
- $OnlineMap{ $package } = $onlinedir;
- $RevMap{ $onlinedir } = $package;
- } else {
- print "No On-line location for $package found\n" if $VERBOSE;
- }
- print "Local location of $package: $dir\n" if $VERBOSE;
- $LocalMap{ $package } = $dir;
- $RevMap{ $dir } = $package;
-}
-
-
-sub RelativizeLocalMap {
- my ($self) = @_;
- my $prefix;
- my $dir;
-
- $self = realpath $self;
- $self =~ s#/?$#/#;
- ($prefix = $self) =~ s#[^/]+/$##;
- foreach my $package (keys %LocalMap) {
- $dir = $LocalMap{ $package };
- if (substr($dir, 0, length $prefix) eq $prefix) {
- $dir = "../" . substr($dir, length $prefix);
- $LocalMap{ $package } = $dir;
- print "Relativizing local location of $package to $dir\n" if $VERBOSE;
- }
- }
-}
-
-
-sub RebaseReferences {
- my ($dir) = @_;
-
- opendir(HTMLDIR, $dir) || die "Can't open HTML directory $dir: $!";
- foreach my $file (readdir(HTMLDIR)) {
- if ($file =~ m/\.html?$/) {
- &RebaseFile("$dir$file");
- }
- }
- closedir (HTMLDIR);
-}
-
-
-sub RebaseFile {
- my ($file) = @_;
- print "Fixing file: $file\n" if $VERBOSE;
-
- open(HTMLFILE, $file) || die "Can't open $file: $!";
- local $/;
- undef $/;
- my $text = <HTMLFILE>;
- close(HTMLFILE);
-
- $text =~ s#(<a(?:\s+\w+=(?:"[^"]*"|'[^']*'))*\s+href=")([^"]*)(")#$1 . &RebaseLink($2) .$3#gse;
-
- open(NEWFILE, ">$file.new") || die "Can't open $file: $!";
- print NEWFILE $text;
- close(NEWFILE);
-
- unlink($file) || die "Can't delete $file: $!";
- rename("$file.new", $file) || die "Can't rename $file.new: $!";
-}
-
-
-sub RebaseLink {
- my ($href) = @_;
- my ($dir, $origdir, $file, $package);
-
- if ($href =~ m#^(.*/)([^/]*)$#) {
- $dir = $origdir = $1;
- $file = $2;
- if ($RevMap{ $dir }) {
- $package = $RevMap{ $dir };
- }
- elsif ($dir =~ m#^\.\./([^/]+)/#) {
- $package = $1
- }
- elsif ($AGGRESSIVE) {
- $dir =~ m#([^/]+)/$#;
- $package = $1;
- }
-
- if ($package) {
- if ($ONLINE && $OnlineMap{ $package }) {
- $dir = $OnlineMap{ $package };
- }
- elsif ($LocalMap{ $package }) {
- $dir = $LocalMap{ $package };
- }
- $href = $dir . $file;
- }
- if ($dir ne $origdir) {
- if ($Mapped{ $origdir }) {
- $Mapped{ $origdir }->[1]++;
- }
- else {
- $Mapped{ $origdir } = [ $dir, 1 ];
- }
- }
- }
- return $href;
-}
-
-
-sub PrintWhatWeHaveDone {
- my ($origdir, $info);
- foreach $origdir (sort keys %Mapped) {
- $info = $Mapped{$origdir};
- print "$origdir -> ", $info->[0], " (", $info->[1], ")\n";
- }
-}
+import argparse
+import sys
+sys.path.append('@PYTHON_PACKAGE_DIR@')
+
+from gtkdoc import common, config, rebase
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ description='gtkdoc-rebase version %s - rewrite links in html docs' % config.version)
+ parser.add_argument('--version', action='version', version=config.version)
+ parser.add_argument('--html-dir', required=True,
+ help='The directory which contains the installed HTML')
+ parser.add_argument('--other-dir', default=[], action='append',
+ help='Directories to recursively scan for indices (*.devhelp2).'
+ 'May be used more than once for multiple directories.')
+ parser.add_argument('--dest-dir', default='',
+ help='Staging area virtual root, this prefix will be removed'
+ 'from HTML_DIR for relative link calculation.')
+ parser.add_argument('--aggressive', action='store_true', default=False,
+ help='Rebase links to all files that are under a directory matching a package name.')
+ parser.add_argument('--verbose', action='store_true', default=False,
+ help='Print extra output while processing')
+ parser.add_argument('--online', action='store_true', default=False,
+ help='Prefer cross-references to online documents')
+ parser.add_argument('--relative', action='store_true', default=False,
+ help='Prefer relative cross-references')
+
+ options = parser.parse_args()
+
+ common.setup_logging()
+
+ sys.exit(rebase.run(options))
-#!@PERL@ -w
-# -*- cperl -*-
+#!@PYTHON@
+# -*- python -*-
#
# gtk-doc - GTK DocBook documentation generator.
# Copyright (C) 1998 Damon Chaplin
+# 2007-2016 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
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
-#############################################################################
-# Script : gtkdoc-scan
-# Description : Extracts declarations of functions, macros, enums, structs
-# and unions from header files.
-#
-# It is called with a module name, an optional source directory,
-# an optional output directory, and the header files to scan.
-#
-# It outputs all declarations found to a file named
-# '$MODULE-decl.txt', and the list of decarations to another
-# file '$MODULE-decl-list.txt'.
-#
-# This second list file is typically copied to
-# '$MODULE-sections.txt' and organized into sections ready to
-# output the SGML pages.
-#############################################################################
-
-use strict;
-use Getopt::Long;
-use Cwd qw(realpath);
-
-push @INC, '@PACKAGE_DATA_DIR@';
-require "gtkdoc-common.pl";
-
-# Options
-
-# name of documentation module
-my $MODULE;
-my $OUTPUT_DIR;
-my @SOURCE_DIRS;
-my $IGNORE_HEADERS = "";
-my $REBUILD_TYPES;
-my $REBUILD_SECTIONS;
-my $PRINT_VERSION;
-my $PRINT_HELP;
-# regexp matching cpp symbols which surround deprecated stuff
-# e.g. 'GTK_ENABLE_BROKEN|GTK_DISABLE_DEPRECATED'
-# these are detected if they are used as #if FOO, #ifndef FOO, or #ifdef FOO
-my $DEPRECATED_GUARDS;
-# regexp matching decorators that should be ignored
-my $IGNORE_DECORATORS;
-
-my @get_types = ();
-
-# do not read files twice; checking it here permits to give both srcdir and
-# builddir as --source-dir without fear of duplicities
-my %seen_headers;
-
-
-run() unless caller; # Run program unless loaded as a module
-
-
-sub run {
- my %optctl = (module => \$MODULE,
- 'source-dir' => \@SOURCE_DIRS,
- 'ignore-headers' => \$IGNORE_HEADERS,
- 'output-dir' => \$OUTPUT_DIR,
- 'rebuild-types' => \$REBUILD_TYPES,
- 'rebuild-sections' => \$REBUILD_SECTIONS,
- 'version' => \$PRINT_VERSION,
- 'help' => \$PRINT_HELP,
- 'deprecated-guards' => \$DEPRECATED_GUARDS,
- 'ignore-decorators' => \$IGNORE_DECORATORS);
- GetOptions(\%optctl, "module=s", "source-dir:s", "ignore-headers:s",
- "output-dir:s", "rebuild-types", "rebuild-sections", "version",
- "help", "deprecated-guards:s", "ignore-decorators:s");
-
- if ($PRINT_VERSION) {
- print "@VERSION@\n";
- exit 0;
- }
-
- if (!$MODULE) {
- $PRINT_HELP = 1;
- }
-
- if ($PRINT_HELP) {
- print <<EOF;
-gtkdoc-scan version @VERSION@ - scan header files for public symbols
-
---module=MODULE_NAME Name of the doc module being parsed
---source-dir=DIRNAME Directories containing the source files to scan
---ignore-headers=FILES A space-separated list of header files/dirs not to
- scan
---output-dir=DIRNAME The directory where the results are stored
---deprecated-guards=GUARDS A |-separated list of symbols used as deprecation
- guards
---ignore-decorators=DECS A |-separated list of addition decorators in
- declarations that should be ignored
---rebuild-sections Rebuild (overwrite) the MODULE-sections.txt file
---rebuild-types Automatically recreate the MODULE.types file using
- all the *_get_type() functions found
---version Print the version of this program
---help Print this help
-EOF
- exit 0;
- }
-
- $DEPRECATED_GUARDS = $DEPRECATED_GUARDS ? $DEPRECATED_GUARDS : "does_not_match_any_cpp_symbols_at_all_nope";
-
- $IGNORE_DECORATORS = $IGNORE_DECORATORS || "(?=no)match";
-
- $OUTPUT_DIR = $OUTPUT_DIR ? $OUTPUT_DIR : ".";
-
- if (!-d ${OUTPUT_DIR}) {
- mkdir($OUTPUT_DIR, 0755) || die "Cannot create $OUTPUT_DIR: $!";
- }
-
- my $old_decl_list = "${OUTPUT_DIR}/$MODULE-decl-list.txt";
- my $new_decl_list = "${OUTPUT_DIR}/$MODULE-decl-list.new";
- my $old_decl = "${OUTPUT_DIR}/$MODULE-decl.txt";
- my $new_decl = "${OUTPUT_DIR}/$MODULE-decl.new";
- my $old_types = "${OUTPUT_DIR}/$MODULE.types";
- my $new_types = "${OUTPUT_DIR}/$MODULE.types.new";
- my $sections_file = "${OUTPUT_DIR}/$MODULE-sections.txt";
-
- # If this is the very first run then we create the .types file automatically.
- if (! -e $sections_file && ! -e $old_types) {
- $REBUILD_TYPES = 1;
- }
-
- open (DECLLIST, ">$new_decl_list")
- || die "Can't open $new_decl_list";
- open (DECL, ">$new_decl")
- || die "Can't open $new_decl";
- if ($REBUILD_TYPES) {
- open (TYPES, ">$new_types")
- || die "Can't open $new_types";
- }
-
- my %section_list = ();
- my $file;
-
- # The header files to scan are passed in as command-line args.
- for $file (@ARGV) {
- &ScanHeader ($file, \%section_list);
- }
-
- for my $dir (@SOURCE_DIRS) {
- &ScanHeaders ($dir, \%section_list);
- }
-
- ## FIXME: sort by key and output
- #print DECLLIST $section_list;
- my $section;
- foreach $section (sort(keys %section_list)) {
- print DECLLIST "$section_list{$section}";
- }
-
- close (DECLLIST);
- close (DECL);
-
- if ($REBUILD_TYPES) {
- my $func;
-
- foreach $func (sort(@get_types)) {
- print TYPES "$func\n";
- }
- close (TYPES);
- &UpdateFileIfChanged ($old_types, $new_types, 1);
-
- # remove the file if empty
- if (scalar (@get_types) == 0) {
- unlink ("$new_types");
- }
- }
-
- &UpdateFileIfChanged ($old_decl_list, $new_decl_list, 1);
- &UpdateFileIfChanged ($old_decl, $new_decl, 1);
-
- # If there is no MODULE-sections.txt file yet or we are asked to rebuild it,
- # we copy the MODULE-decl-list.txt file into its place. The user can tweak it
- # later if they want.
- if ($REBUILD_SECTIONS || ! -e $sections_file) {
- `cp $old_decl_list $sections_file`;
- }
-
- # If there is no MODULE-overrides.txt file we create an empty one
- # because EXTRA_DIST in gtk-doc.make requires it.
- my $overrides_file = "${OUTPUT_DIR}/$MODULE-overrides.txt";
- if (! -e $overrides_file) {
- `touch $overrides_file`;
- }
-}
-
-
-#############################################################################
-# Function : ScanHeaders
-# Description : This scans a directory tree looking for header files.
-#
-# Arguments : $source_dir - the directory to scan.
-# $section_list - a reference to the hashmap of sections.
-#############################################################################
-
-sub ScanHeaders {
- my ($source_dir, $section_list) = @_;
- @TRACE@("Scanning source directory: $source_dir");
-
- # This array holds any subdirectories found.
- my (@subdirs) = ();
-
- opendir (SRCDIR, $source_dir)
- || die "Can't open source directory $source_dir: $!";
- my $file;
- foreach $file (readdir (SRCDIR)) {
- if ($file eq '.' || $file eq '..' || $file =~ /^\./) {
- next;
- } elsif (-d "$source_dir/$file") {
- push (@subdirs, $file);
- } elsif ($file =~ m/\.h$/) {
- &ScanHeader ("$source_dir/$file", $section_list);
- }
- }
- closedir (SRCDIR);
-
- # Now recursively scan the subdirectories.
- my $dir;
- foreach $dir (@subdirs) {
- next if ($IGNORE_HEADERS =~ m/(\s|^)\Q${dir}\E(\s|$)/);
- &ScanHeaders ("$source_dir/$dir", $section_list);
- }
-}
-
-
-#############################################################################
-# Function : ScanHeader
-# Description : This scans a header file, looking for declarations of
-# functions, macros, typedefs, structs and unions, which it
-# outputs to the DECL file.
-# Arguments : $input_file - the header file to scan.
-# $section_list - a reference to the hashmap of sections.
-# Returns : it adds declarations to the appropriate list.
-#############################################################################
-
-sub ScanHeader {
- my ($input_file, $section_list) = @_;
-
- my $list = ""; # Holds the resulting list of declarations.
- my $title = ""; # Holds the title of the section
- my ($in_comment) = 0; # True if we are in a comment.
- my ($in_declaration) = ""; # The type of declaration we are in, e.g.
- # 'function' or 'macro'.
- my ($skip_block) = 0; # True if we should skip a block.
- my ($symbol); # The current symbol being declared.
- my ($decl); # Holds the declaration of the current symbol.
- my ($ret_type); # For functions and function typedefs this
- # holds the function's return type.
- my ($pre_previous_line) = ""; # The pre-previous line read in - some Gnome
- # functions have the return type on one
- # line, the function name on the next,
- # and the rest of the declaration after.
- my ($previous_line) = ""; # The previous line read in - some Gnome
- # functions have the return type on one line
- # and the rest of the declaration after.
- my ($first_macro) = 1; # Used to try to skip the standard #ifdef XXX
- # #define XXX at the start of headers.
- my ($level); # Used to handle structs/unions which contain
- # nested structs or unions.
- my @objects = (); # Holds declarations that look like GtkObject
- # subclasses, which we remove from the list.
- my ($internal) = 0; # Set to 1 for internal symbols, we need to
- # fully parse, but don't add them to docs
- my %forward_decls = (); # hashtable of forward declarations, we skip
- # them if we find the real declaration
- # later.
- my %doc_comments = (); # hastable of doc-comment we found. We can
- # use that to put element to the right
- # sction in the generated section-file
-
- my $file_basename;
-
- my $deprecated_conditional_nest = 0;
- my $ignore_conditional_nest = 0;
-
- my $deprecated = "";
- my $doc_comment = "";
-
- # Don't scan headers twice
- my $canonical_input_file = realpath $input_file;
- if (exists $seen_headers{$canonical_input_file}) {
- @TRACE@("File already scanned: $input_file");
- return;
- }
- $seen_headers{$canonical_input_file} = 1;
-
- if ($input_file =~ m/^.*[\/\\](.*)\.h+$/) {
- $file_basename = $1;
- } else {
- LogWarning(__FILE__,__LINE__,"Can't find basename of file $input_file");
- $file_basename = $input_file;
- }
-
- # Check if the basename is in the list of headers to ignore.
- if ($IGNORE_HEADERS =~ m/(\s|^)\Q${file_basename}\E\.h(\s|$)/) {
- @TRACE@("File ignored: $input_file");
- return;
- }
- # Check if the full name is in the list of headers to ignore.
- if ($IGNORE_HEADERS =~ m/(\s|^)\Q${input_file}\E(\s|$)/) {
- @TRACE@("File ignored: $input_file");
- return;
- }
-
- if (! -f $input_file) {
- LogWarning(__FILE__,__LINE__,"File doesn't exist: $input_file");
- return;
- }
-
- @TRACE@("Scanning $input_file");
-
- open(INPUT, $input_file)
- || die "Can't open $input_file: $!";
- while(<INPUT>) {
- # If this is a private header, skip it.
- if (m%^\s*/\*\s*<\s*private_header\s*>\s*\*/%) {
- close(INPUT);
- return;
- }
-
- # Skip to the end of the current comment.
- if ($in_comment) {
- @TRACE@("Comment: $_");
- $doc_comment .= $_;
- if (m%\*/%) {
- if ($doc_comment =~ m/\* ([a-zA-Z][a-zA-Z0-9_]+):/) {
- $doc_comments{lc($1)} = 1;
- }
- $in_comment = 0;
- $doc_comment = "";
- }
- next;
- }
-
- # Keep a count of #if, #ifdef, #ifndef nesting,
- # and if we enter a deprecation-symbol-bracketed
- # zone, take note.
- if (m/^\s*#\s*if(?:n?def\b|\s+!?\s*defined\s*\()\s*(\w+)/) {
- my $define_name = $1;
- if ($deprecated_conditional_nest < 1 and $define_name =~ /$DEPRECATED_GUARDS/) {
- $deprecated_conditional_nest = 1;
- } elsif ($deprecated_conditional_nest >= 1) {
- $deprecated_conditional_nest += 1;
- }
- if ($ignore_conditional_nest == 0 and $define_name =~ /__GTK_DOC_IGNORE__/) {
- $ignore_conditional_nest = 1;
- } elsif ($ignore_conditional_nest > 0) {
- $ignore_conditional_nest += 1;
- }
- } elsif (m/^\s*#\sif/) {
- if ($deprecated_conditional_nest >= 1) {
- $deprecated_conditional_nest += 1;
- }
- if ($ignore_conditional_nest > 0) {
- $ignore_conditional_nest += 1;
- }
- } elsif (m/^\s*#endif/) {
- if ($deprecated_conditional_nest >= 1) {
- $deprecated_conditional_nest -= 1;
- }
- if ($ignore_conditional_nest > 0) {
- $ignore_conditional_nest -= 1;
- }
- }
-
- # If we find a line containing _DEPRECATED, we hope that this is
- # attribute based deprecation and also treat this as a deprecation
- # guard, unless it's a macro definition.
- if ($deprecated_conditional_nest == 0 and m/_DEPRECATED/) {
- unless (m/^\s*#\s*(if*|define)/ or $in_declaration eq "enum") {
- @TRACE@("Found deprecation annotation (decl: '$in_declaration'): $_");
- $deprecated_conditional_nest += 0.1;
- }
- }
-
- # set global that is used later when we do AddSymbolToList
- if ($deprecated_conditional_nest > 0) {
- $deprecated = "<DEPRECATED/>\n";
- } else {
- $deprecated = "";
- }
-
- if($ignore_conditional_nest) {
- next;
- }
-
- if (!$in_declaration) {
- # Skip top-level comments.
- if (s%^\s*/\*%%) {
- if (m%\*/%) {
- @TRACE@("Found one-line comment: $_");
- } else {
- $in_comment = 1;
- $doc_comment = $_;
- @TRACE@("Found start of comment: $_");
- }
- next;
- }
-
- @TRACE@("0: $_");
-
- # MACROS
-
- if (m/^\s*#\s*define\s+(\w+)/) {
- $symbol = $1;
- $decl = $_;
- # We assume all macros which start with '_' are private, but
- # we accept '_' itself which is the standard gettext macro.
- # We also try to skip the first macro if it looks like the
- # standard #ifndef HEADER_FILE #define HEADER_FILE etc.
- # And we only want TRUE & FALSE defined in GLib (libdefs.h in
- # libgnome also defines them if they are not already defined).
- if (($symbol !~ m/^_/
- && ($previous_line !~ m/#ifndef\s+$symbol/
- || $first_macro == 0)
- && (($symbol ne 'TRUE' && $symbol ne 'FALSE')
- || $MODULE eq 'glib'))
- || $symbol eq "_") {
- $in_declaration = "macro";
- @TRACE@("Macro: $symbol");
- } else {
- @TRACE@("skipping Macro: $symbol");
- $in_declaration = "macro";
- $internal = 1;
- }
- $first_macro = 0;
-
-
- # TYPEDEF'D FUNCTIONS (i.e. user functions)
-
- # $1 $3 $4 $5
- } elsif (m/^\s*typedef\s+((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
- my $p3 = defined($3) ? $3 : "";
- $ret_type = "$1$p3 $4";
- $symbol = $5;
- $decl = $';
- $in_declaration = "user_function";
- @TRACE@("user function (1): $symbol, Returns: $ret_type");
-
- # $1 $3 $4 $5
- } elsif (($previous_line =~ m/^\s*typedef\s*/) && m/^\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
- my $p3 = defined($3) ? $3 : "";
- $ret_type = "$1$p3 $4";
- $symbol = $5;
- $decl = $';
- $in_declaration = "user_function";
- @TRACE@("user function (2): $symbol, Returns: $ret_type");
-
- # $1 $2
- } elsif (($previous_line =~ m/^\s*typedef\s*/) && m/^\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) {
- $ret_type = $1;
- $symbol = $2;
- $decl = $';
- # $1 $3
- if ($previous_line =~ m/^\s*typedef\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*/) {
- my $p3 = defined($3) ? $3 : "";
- $ret_type = "$1$p3 ".$ret_type;
- $in_declaration = "user_function";
- @TRACE@("user function (3): $symbol, Returns: $ret_type");
-
- }
- # FUNCTION POINTER VARIABLES
- # $1 $3 $4 $5
- } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/o) {
- my $p3 = defined($3) ? $3 : "";
- $ret_type = "$1$p3 $4";
- $symbol = $5;
- $decl = $';
- $in_declaration = "user_function";
- @TRACE@("function pointer variable: $symbol, Returns: $ret_type");
-
- # ENUMS
-
- } elsif (s/^\s*enum\s+_?(\w+)\s+\{/enum $1 {/) {
- # We assume that 'enum _<enum_name> {' is really the
- # declaration of enum <enum_name>.
- $symbol = $1;
- @TRACE@("plain enum: $symbol");
- $decl = $_;
- $in_declaration = "enum";
-
- } elsif (m/^\s*typedef\s+enum\s+_?(\w+)\s+\1\s*;/) {
- # We skip 'typedef enum <enum_name> _<enum_name>;' as the enum will
- # be declared elsewhere.
- @TRACE@("skipping enum typedef: $1");
-
- } elsif (m/^\s*typedef\s+enum/) {
- $symbol = "";
- @TRACE@("typedef enum: -");
- $decl = $_;
- $in_declaration = "enum";
-
-
- # STRUCTS AND UNIONS
-
- } elsif (m/^\s*typedef\s+(struct|union)\s+_(\w+)\s+\2\s*;/) {
- # We've found a 'typedef struct _<name> <name>;'
- # This could be an opaque data structure, so we output an
- # empty declaration. If the structure is actually found that
- # will override this.
- my $structsym = uc $1;
- @TRACE@("$structsym typedef: $2");
- $forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$deprecated</$structsym>\n"
-
- } elsif (m/^\s*(?:struct|union)\s+_(\w+)\s*;/) {
- # Skip private structs/unions.
- @TRACE@("private struct/union");
-
- } elsif (m/^\s*(struct|union)\s+(\w+)\s*;/) {
- # Do a similar thing for normal structs as for typedefs above.
- # But we output the declaration as well in this case, so we
- # can differentiate it from a typedef.
- my $structsym = uc $1;
- @TRACE@("$structsym: $2");
- $forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$_$deprecated</$structsym>\n";
-
- } elsif (m/^\s*typedef\s+(struct|union)\s*\w*\s*{/) {
- $symbol = "";
- $decl = $_;
- $level = 0;
- $in_declaration = $1;
- @TRACE@("typedef struct/union $1");
-
- # OTHER TYPEDEFS
-
- } elsif (m/^\s*typedef\s+(?:struct|union)\s+\w+[\s\*]+(\w+)\s*;/) {
- @TRACE@("Found struct/union(*) typedef $1: $_");
- if (&AddSymbolToList (\$list, $1)) {
- print DECL "<TYPEDEF>\n<NAME>$1</NAME>\n$deprecated$_</TYPEDEF>\n";
- }
-
- } elsif (m/^\s*(G_GNUC_EXTENSION\s+)?typedef\s+(.+[\s\*])(\w+)(\s*\[[^\]]+\])*\s*;/) {
- if ($2 !~ m/^struct\s/ && $2 !~ m/^union\s/) {
- @TRACE@("Found typedef: $_");
- if (&AddSymbolToList (\$list, $3)) {
- print DECL "<TYPEDEF>\n<NAME>$3</NAME>\n$deprecated$_</TYPEDEF>\n";
- }
- }
- } elsif (m/^\s*typedef\s+/) {
- @TRACE@("Skipping typedef: $_");
-
-
- # VARIABLES (extern'ed variables)
-
- } elsif (m/^\s*(extern|[A-Za-z_]+VAR|${IGNORE_DECORATORS})\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*;/o) {
- $symbol = $6;
- s/^\s*([A-Za-z_]+VAR)\b/extern/;
- $decl = $_;
- @TRACE@("Possible extern var $symbol: $decl");
- if (&AddSymbolToList (\$list, $symbol)) {
- print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$deprecated$decl</VARIABLE>\n";
- }
-
-
- # VARIABLES
-
- } elsif (m/^\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*\=/) {
- $symbol = $5;
- $decl = $_;
- @TRACE@("Possible global var $symbol: $decl");
- if (&AddSymbolToList (\$list, $symbol)) {
- print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$deprecated$decl</VARIABLE>\n";
- }
-
- # G_DECLARE_*
-
- } elsif (m/.*G_DECLARE_(FINAL_TYPE|DERIVABLE_TYPE|INTERFACE)\s*\(/) {
- $in_declaration = "g-declare";
- $symbol = "G_DECLARE_$1";
- $decl = $';
-
- # FUNCTIONS
-
- # We assume that functions which start with '_' are private, so
- # we skip them.
- # $1 $2 $3
- } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s+|\*)+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*(_[A-Za-z]\w*)\s*\(/o) {
- $ret_type = $1;
- if (defined ($2)) { $ret_type .= " $2"; }
- $symbol = $3;
- $decl = $';
- @TRACE@("internal Function: $symbol, Returns: [$1][$2]");
- $in_declaration = "function";
- $internal = 1;
- if (m/^\s*G_INLINE_FUNC/) {
- @TRACE@("skip block after inline function");
- # now we we need to skip a whole { } block
- $skip_block = 1;
- }
-
- # $1 $2 $3
- } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s+|\*)+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*([A-Za-z]\w*)\s*\(/o) {
- $ret_type = $1;
- if (defined ($2)) { $ret_type .= " $2"; }
- $symbol = $3;
- $decl = $';
- @TRACE@("Function (1): $symbol, Returns: [$1][$2]");
- $in_declaration = "function";
- if (m/^\s*G_INLINE_FUNC/) {
- @TRACE@("skip block after inline function");
- # now we we need to skip a whole { } block
- $skip_block = 1;
- }
-
- # Try to catch function declarations which have the return type on
- # the previous line. But we don't want to catch complete functions
- # which have been declared G_INLINE_FUNC, e.g. g_bit_nth_lsf in
- # glib, or 'static inline' functions.
- } elsif (m/^\s*([A-Za-z]\w*)\s*\(/) {
- $symbol = $1;
- $decl = $';
-
- if ($previous_line !~ m/^\s*G_INLINE_FUNC/) {
- if ($previous_line !~ m/^\s*static\s+/) {
- # $1 $2
- if ($previous_line =~ m/^\s*(?:\b(?:extern|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$/o) {
- $ret_type = $1;
- if (defined ($2)) { $ret_type .= " $2"; }
- @TRACE@("Function (2): $symbol, Returns: $ret_type");
- $in_declaration = "function";
- }
- } else {
- @TRACE@("skip block after inline function");
- # now we we need to skip a whole { } block
- $skip_block = 1;
- # $1 $2
- if ($previous_line =~ m/^\s*(?:\b(?:extern|static|inline|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$/o) {
- $ret_type = $1;
- if (defined ($2)) { $ret_type .= " $2"; }
- @TRACE@("Function (3): $symbol, Returns: $ret_type");
- $in_declaration = "function";
- }
- }
- }
- else {
- if ($previous_line !~ m/^\s*static\s+/) {
- @TRACE@("skip block after inline function");
- # now we we need to skip a whole { } block
- $skip_block = 1;
- # $1 $2
- if ($previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$/o) {
- $ret_type = $1;
- if (defined ($2)) { $ret_type .= " $2"; }
- @TRACE@("Function (4): $symbol, Returns: $ret_type");
- $in_declaration = "function";
- }
- }
- }
-
- # Try to catch function declarations with the return type and name
- # on the previous line(s), and the start of the parameters on this.
- } elsif (m/^\s*\(/) {
- $decl = $';
- if ($previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|enum\s+)*\w+)(\s+\*+|\*+|\s)\s*([A-Za-z]\w*)\s*$/o) {
- $ret_type = "$1 $2";
- $symbol = $3;
- @TRACE@("Function (5): $symbol, Returns: $ret_type");
- $in_declaration = "function";
-
- } elsif ($previous_line =~ m/^\s*\w+\s*$/
- && $pre_previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|struct\s+|union\s+|enum\s+)*\w+(?:\**\s+\**(?:const|G_CONST_RETURN))?(?:\s+|\s*\*+))\s*$/o) {
- $ret_type = $1;
- $ret_type =~ s/\s*\n//;
- $in_declaration = "function";
-
- $symbol = $previous_line;
- $symbol =~ s/^\s+//;
- $symbol =~ s/\s*\n//;
- @TRACE@("Function (6): $symbol, Returns: $ret_type");
- }
-
- #} elsif (m/^extern\s+/) {
- #print "DEBUG: Skipping extern: $_";
-
-
- # STRUCTS
-
- } elsif (m/^\s*struct\s+_?(\w+)\s*\*/) {
- # Skip 'struct _<struct_name> *', since it could be a
- # return type on its own line.
-
- } elsif (m/^\s*struct\s+_?(\w+)/) {
- # We assume that 'struct _<struct_name>' is really the
- # declaration of struct <struct_name>.
- $symbol = $1;
- $decl = $_;
- # we will find the correct level as below we do $level += tr/{//;
- $level = 0;
- $in_declaration = "struct";
- @TRACE@("Struct(_): $symbol");
-
-
- # UNIONS
-
- } elsif (m/^\s*union\s+_(\w+)\s*\*/) {
- # Skip 'union _<union_name> *' (see above)
- } elsif (m/^\s*union\s+_(\w+)/) {
- $symbol = $1;
- $decl = $_;
- $level = 0;
- $in_declaration = "union";
- @TRACE@("Union(_): $symbol");
- }
-
- } else {
- @TRACE@("1: [$skip_block] $_");
- # If we were already in the middle of a declaration, we simply add
- # the current line onto the end of it.
- if ($skip_block == 0) {
- $decl .= $_;
- } else {
- # Remove all nested pairs of curly braces.
- while ($_ =~ s/{[^{]*}//g) { }
- # Then hope at most one remains in the line...
- if (m%(.*?){%) {
- if ($skip_block == 1) {
- $decl .= $1;
- }
- $skip_block += 1;
- } elsif (m%}%) {
- $skip_block -= 1;
- if ($skip_block == 1) {
- # this is a hack to detect the end of declaration
- $decl .= ";";
- $skip_block = 0;
- @TRACE@("2: ---");
- }
- } else {
- if ($skip_block == 1) {
- $decl .= $_;
- }
- }
- }
- }
-
- #if ($in_declaration ne '') {
- # print "$in_declaration = $decl\n";
- #}
-
- if ($in_declaration eq "g-declare") {
- if ($decl =~ s/\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*\).*$//) {
- my $ModuleObjName = $1;
- my $module_obj_name = $2;
- if ($REBUILD_TYPES) {
- push (@get_types, "${module_obj_name}_get_type");
- }
- $forward_decls{$ModuleObjName} = "<STRUCT>\n<NAME>$ModuleObjName</NAME>\n$deprecated</STRUCT>\n";
- if ($symbol =~ /^G_DECLARE_DERIVABLE/) {
- $forward_decls{"${ModuleObjName}Class"} = "<STRUCT>\n<NAME>${ModuleObjName}Class</NAME>\n$deprecated</STRUCT>\n";
- }
- if ($symbol =~ /^G_DECLARE_INTERFACE/) {
- $forward_decls{"${ModuleObjName}Interface"} = "<STRUCT>\n<NAME>${ModuleObjName}Interface</NAME>\n$deprecated</STRUCT>\n";
- }
- $in_declaration = "";
- }
- }
-
- # Note that sometimes functions end in ') G_GNUC_PRINTF (2, 3);' or
- # ') __attribute__ (...);'.
- if ($in_declaration eq 'function') {
- if ($decl =~ s/\)\s*(G_GNUC_.*|.*DEPRECATED.*|${IGNORE_DECORATORS}\s*|__attribute__\s*\(.*\)\s*)*;.*$//s) {
- if ($internal == 0) {
- $decl =~ s%/\*.*?\*/%%gs; # remove comments.
- #$decl =~ s/^\s+//; # remove leading whitespace.
- #$decl =~ s/\s+$//; # remove trailing whitespace.
- $decl =~ s/\s*\n\s*/ /gs; # consolidate whitespace at start
- # and end of lines.
- $ret_type =~ s%/\*.*?\*/%%g; # remove comments in ret type.
- if (&AddSymbolToList (\$list, $symbol)) {
- print DECL "<FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl\n</FUNCTION>\n";
- if ($REBUILD_TYPES) {
- # check if this looks like a get_type function and if so remember
- if (($symbol =~ m/_get_type$/) && ($ret_type =~ m/GType/) && ($decl =~ m/^(void|)$/)) {
- @TRACE@("Adding get-type: [$ret_type] [$symbol] [$decl]\tfrom $input_file");
- push (@get_types, $symbol);
- }
- }
- }
- } else {
- $internal = 0;
- }
- $deprecated_conditional_nest = int($deprecated_conditional_nest);
- $in_declaration = "";
- $skip_block = 0;
- }
- }
-
- if ($in_declaration eq 'user_function') {
- if ($decl =~ s/\).*$//) {
- if (&AddSymbolToList (\$list, $symbol)) {
- print DECL "<USER_FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl</USER_FUNCTION>\n";
- }
- $deprecated_conditional_nest = int($deprecated_conditional_nest);
- $in_declaration = "";
- }
- }
-
- if ($in_declaration eq 'macro') {
- if ($decl !~ m/\\\s*$/) {
- if ($internal == 0) {
- if (&AddSymbolToList (\$list, $symbol)) {
- print DECL "<MACRO>\n<NAME>$symbol</NAME>\n$deprecated$decl</MACRO>\n";
- }
- } else {
- $internal = 0;
- }
- $deprecated_conditional_nest = int($deprecated_conditional_nest);
- $in_declaration = "";
- }
- }
-
- if ($in_declaration eq 'enum') {
- if ($decl =~ m/\}\s*(\w+)?;\s*$/) {
- if ($symbol eq "") {
- $symbol = $1;
- }
- if (&AddSymbolToList (\$list, $symbol)) {
- print DECL "<ENUM>\n<NAME>$symbol</NAME>\n$deprecated$decl</ENUM>\n";
- }
- $deprecated_conditional_nest = int($deprecated_conditional_nest);
- $in_declaration = "";
- }
- }
-
- # We try to handle nested stucts/unions, but unmatched brackets in
- # comments will cause problems.
- if ($in_declaration eq 'struct' or $in_declaration eq 'union') {
- if (($level <= 1) && ($decl =~ m/\n\}\s*(\w*);\s*$/)) {
- if ($symbol eq "") {
- $symbol = $1;
- }
-
- if ($symbol =~ m/^(\S+)(Class|Iface|Interface)\b/) {
- my $objectname = $1;
- @TRACE@("Found object: $1");
- $title = "<TITLE>$objectname</TITLE>\n";
- push (@objects, $objectname);
- }
- @TRACE@("Store struct: $symbol");
- if (&AddSymbolToList (\$list, $symbol)) {
- my $structsym = uc $in_declaration;
- print DECL "<$structsym>\n<NAME>$symbol</NAME>\n$deprecated$decl</$structsym>\n";
- if (defined($forward_decls{$symbol})) {
- undef($forward_decls{$symbol});
- }
- }
- $deprecated_conditional_nest = int($deprecated_conditional_nest);
- $in_declaration = "";
- } else {
- # We use tr to count the brackets in the line, and adjust
- # $level accordingly.
- $level += tr/{//;
- $level -= tr/}//;
- @TRACE@("struct/union level : $level");
- }
- }
-
- $pre_previous_line = $previous_line;
- $previous_line = $_;
- }
- close(INPUT);
-
- # print remaining forward declarations
- foreach $symbol (sort(keys %forward_decls)) {
- if (defined($forward_decls{$symbol})) {
- &AddSymbolToList (\$list, $symbol);
- print DECL $forward_decls{$symbol};
- }
- }
-
- # add title
- $list = "$title$list";
-
- @TRACE@("Scanning $input_file done\n");
-
- # Try to separate the standard macros and functions, placing them at the
- # end of the current section, in a subsection named 'Standard'.
- # do this in a loop to catch object, enums and flags
- my ($class,$lclass,$prefix,$lprefix);
- my ($standard_decl) = "";
- do {
- if ($list =~ m/^(\S+)_IS_(\S*)_CLASS\n/m) {
- $prefix = $1;
- $lprefix = lc($prefix);
- $class = $2;
- $lclass = lc($class);
- @TRACE@("Found gobject type '${prefix}_$class' from is_class macro\n");
- } elsif ($list =~ m/^(\S+)_IS_(\S*)\n/m) {
- $prefix = $1;
- $lprefix = lc($prefix);
- $class = $2;
- $lclass = lc($class);
- @TRACE@("Found gobject type '${prefix}_$class' from is_ macro\n");
- } elsif ($list =~ m/^(\S+?)_(\S*)_get_type\n/m) {
- $lprefix = $1;
- $prefix = uc($lprefix);
- $lclass = $2;
- $class = uc($lclass);
- @TRACE@("Found gobject type '${prefix}_$class' from get_type function\n");
- } else {
- $class = $lclass = "";
- }
-
- if ($class ne "") {
- my ($cclass) = $lclass;
- $cclass =~ s/_//g;
- my ($type) = $lprefix.$cclass;
-
- if ($list =~ s/^${type}Private\n//im) { $standard_decl .= $&; }
-
- # We only leave XxYy* in the normal section if they have docs
- if (! defined($doc_comments{$type})) {
- @TRACE@(" Hide instance docs for $type");
- if ($list =~ s/^${type}\n//im) { $standard_decl .= $&; }
- }
- if (! defined($doc_comments{$type."class"})) {
- @TRACE@(" Hide class docs for $type");
- if ($list =~ s/^${type}Class\n//im) { $standard_decl .= $&; }
- }
- if (! defined($doc_comments{$type."interface"})) {
- @TRACE@(" Hide iface docs for $type");
- if ($list =~ s/^$type}Interface\n//im) { $standard_decl .= $&; }
- }
- if (! defined($doc_comments{$type."iface"})) {
- @TRACE@(" Hide iface docs for $type");
- if ($list =~ s/${type}Iface\n//im) { $standard_decl .= $&; }
- }
-
- while ($list =~ s/^\S+_IS_$class\n//m) { $standard_decl .= $&; }
- while ($list =~ s/^\S+_TYPE_$class\n//m) { $standard_decl .= $&; }
- while ($list =~ s/^\S+_${lclass}_get_type\n//m) { $standard_decl .= $&; }
- while ($list =~ s/^\S+_${class}_CLASS\n//m) { $standard_decl .= $&; }
- while ($list =~ s/^\S+_IS_${class}_CLASS\n//m) { $standard_decl .= $&; }
- while ($list =~ s/^\S+_${class}_GET_CLASS\n//m) { $standard_decl .= $&; }
- while ($list =~ s/^\S+_${class}_GET_IFACE\n//m) { $standard_decl .= $&; }
- while ($list =~ s/^\S+_${class}_GET_INTERFACE\n//m) { $standard_decl .= $&; }
-
- # We do this one last, otherwise it tends to be caught by the IS_$class macro
- while ($list =~ s/^\S+_$class\n//m) { $standard_decl .= $&; }
-
- @TRACE@("Decl '".join(",",split("\n",$list))."'\n");
- @TRACE@("Std '".join(",",split("\n",$standard_decl))."'\n");
- }
- } while ($class ne "");
- if ($standard_decl ne "") {
- # sort the symbols
- $standard_decl=join("\n",sort(split("\n",$standard_decl)))."\n";
- $list .= "<SUBSECTION Standard>\n$standard_decl";
- }
- if ($list ne "") {
- $$section_list{$file_basename} .= "<SECTION>\n<FILE>$file_basename</FILE>\n$list</SECTION>\n\n";
- }
-}
-
-
-#############################################################################
-# Function : AddSymbolToList
-# Description : This adds the symbol to the list of declarations, but only if
-# it is not already in the list.
-# Arguments : $list - reference to the list of symbols, one on each line.
-# $symbol - the symbol to add to the list.
-#############################################################################
-
-sub AddSymbolToList {
- my ($list, $symbol) = @_;
-
- if ($$list =~ m/\b\Q$symbol\E\b/) {
- #print "Symbol $symbol already in list. skipping\n";
- # we return 0 to skip outputting another entry to -decl.txt
- # this is to avoid redeclarations (e.g. in conditional
- # sections).
- return 0;
- }
- $$list .= "$symbol\n";
- return 1;
-}
+from __future__ import print_function
+
+import argparse
+import sys
+sys.path.append('@PYTHON_PACKAGE_DIR@')
+
+from gtkdoc import common, config, scan
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ description='gtkdoc-scan version %s - scan header files for public symbols' % config.version)
+ parser.add_argument('--version', action='version', version=config.version)
+ parser.add_argument('--module', required=True,
+ help='Name of the doc module being processed.')
+ parser.add_argument('--source-dir', action='append', default=[],
+ help='Directories containing the source files to scan')
+ parser.add_argument('--ignore-headers', default='',
+ help='A space-separated list of header files/dirs not to scan')
+ parser.add_argument('--output-dir', default='.',
+ help='The directory where the results are stored')
+ parser.add_argument('--deprecated-guards', default='does_not_match_any_cpp_symbols_at_all_nope',
+ help='A |-separated list of symbols used as deprecation guards')
+ parser.add_argument('--ignore-decorators', default='(?=no)match',
+ help='A |-separated list of additional decorators in'
+ 'declarations that should be ignored')
+ parser.add_argument('--rebuild-sections', action='store_true', default=False,
+ help='Rebuild (overwrite) the MODULE-sections.txt file')
+ parser.add_argument('--rebuild-types', action='store_true', default=False,
+ help='Automatically recreate the MODULE.types file using'
+ 'all the *_get_type() functions found')
+ parser.add_argument('headers', nargs='*')
+
+ options = parser.parse_args()
+
+ common.setup_logging()
+
+ scan.Run(options)
-#!@PERL@ -w
-# -*- cperl -*-
+#!@PYTHON@
+# -*- python -*-
#
# gtk-doc - GTK DocBook documentation generator.
# Copyright (C) 1998 Damon Chaplin
+# 2007-2016 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
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
-#
-# This gets information about object hierarchies and signals
-# by compiling a small C program. CFLAGS and LDFLAGS must be
-# set appropriately before running this script.
-#
-
-use strict;
-use Getopt::Long;
-
-push @INC, '@PACKAGE_DATA_DIR@';
-require "gtkdoc-common.pl";
-
-# Options
-
-# name of documentation module
-my $MODULE;
-my $TYPES_FILE;
-my $NO_GTK_INIT;
-my $OUTPUT_DIR;
-my $VERBOSE;
-my $PRINT_VERSION;
-my $PRINT_HELP;
-my $TYPE_INIT_FUNC="#if !GLIB_CHECK_VERSION(2,35,0)\n g_type_init();\n #endif\n g_type_class_ref(G_TYPE_OBJECT)";
-my $QUERY_CHILD_PROPERTIES;
-
-my $CC;
-my $LD;
-my $CFLAGS;
-my $LDFLAGS;
-my $RUN;
-
-# --nogtkinit is deprecated, as it is the default now anyway.
-my %optctl = (module => \$MODULE,
- types => \$TYPES_FILE,
- nogtkinit => \$NO_GTK_INIT,
- 'type-init-func' => \$TYPE_INIT_FUNC,
- 'query-child-properties' => \$QUERY_CHILD_PROPERTIES,
- 'output-dir' => \$OUTPUT_DIR,
- 'cc' => \$CC,
- 'ld' => \$LD,
- 'cflags' => \$CFLAGS,
- 'ldflags' => \$LDFLAGS,
- 'run' => \$RUN,
- 'verbose' => \$VERBOSE,
- 'version' => \$PRINT_VERSION,
- 'help' => \$PRINT_HELP);
-
-GetOptions(\%optctl, "module=s", "types:s", "output-dir:s", "nogtkinit", "type-init-func:s", "query-child-properties:s", "cc:s", "ld:s", "run:s", "cflags:s", "ldflags:s", "verbose", "version", "help");
-
-if ($NO_GTK_INIT) {
- # Do nothing. This just avoids a warning.
- # the option is not used anymore
-}
-
-if ($PRINT_VERSION) {
- print "@VERSION@\n";
- exit 0;
-}
-
-if (!$MODULE) {
- $PRINT_HELP = 1;
-}
-
-if ($PRINT_HELP) {
- print <<EOF;
-gtkdoc-scangobj version @VERSION@ - introspect g-objects
-
---module=MODULE_NAME Name of the doc module being parsed
---types=FILE The name of the file to store the types in
---type-init-func=FUNC The init function to call instead of g_type_init()
---query-child-properties=FUNC A function that returns a list of child
- properties for a class
---output-dir=DIRNAME The directory where the results are stored
---cc=COMPILER The compiler to use
---ld=LINKER The linker to use
---run=RUN Command for running the scanner
---cflags=CFLAGS Compiler flags
---ldflags=LDFLAGS Linker flags
---verbose Print extra output while processing
---version Print the version of this program
---help Print this help
-EOF
- exit 0;
-}
-
-$OUTPUT_DIR = $OUTPUT_DIR ? $OUTPUT_DIR : ".";
-
-$TYPES_FILE = $TYPES_FILE ? $TYPES_FILE : "$OUTPUT_DIR/$MODULE.types";
-
-open (TYPES, $TYPES_FILE) || die "Cannot open $TYPES_FILE: $!\n";
-open (OUTPUT, ">$MODULE-scan.c") || die "Cannot open $MODULE-scan.c: $!\n";
-
-my $old_signals_filename = "$OUTPUT_DIR/$MODULE.signals";
-my $new_signals_filename = "$OUTPUT_DIR/$MODULE.signals.new";
-my $old_hierarchy_filename = "$OUTPUT_DIR/$MODULE.hierarchy";
-my $new_hierarchy_filename = "$OUTPUT_DIR/$MODULE.hierarchy.new";
-my $old_interfaces_filename = "$OUTPUT_DIR/$MODULE.interfaces";
-my $new_interfaces_filename = "$OUTPUT_DIR/$MODULE.interfaces.new";
-my $old_prerequisites_filename = "$OUTPUT_DIR/$MODULE.prerequisites";
-my $new_prerequisites_filename = "$OUTPUT_DIR/$MODULE.prerequisites.new";
-my $old_args_filename = "$OUTPUT_DIR/$MODULE.args";
-my $new_args_filename = "$OUTPUT_DIR/$MODULE.args.new";
-
-# generate a C program to scan the types
-
-my $includes = "";
-my $forward_decls = "";
-my $get_types = "";
-my $ntypes = 1;
-
-for (<TYPES>) {
- if (/^#include/) {
- $includes .= $_;
- } elsif (/^gnome_keyring_item_info_get_type$/) {
- # HACK: This isn't really a GObject type so skip it.
- next;
- } elsif (/^%/) {
- next;
- } elsif (/^\s*$/) {
- next;
- } else {
- chomp;
- $get_types .= " object_types[i++] = $_ ();\n";
- $forward_decls .= "extern GType $_ (void);\n";
- $ntypes++;
- }
-}
-
-print OUTPUT <<EOT;
-#include <string.h>
-#include <stdlib.h>
-#include <stdio.h>
-#include <errno.h>
-#include <glib-object.h>
-
-EOT
-
-if ($includes) {
- print OUTPUT $includes;
-} else {
- print OUTPUT $forward_decls;
-}
-
-if ($QUERY_CHILD_PROPERTIES) {
- print OUTPUT <<EOT;
-extern GParamSpec** $QUERY_CHILD_PROPERTIES (gpointer class, guint *n_properties);
-EOT
-}
-
-print OUTPUT <<EOT;
-
-#ifdef GTK_IS_WIDGET_CLASS
-#include <gtk/gtk.h>
-#endif
-static GType object_types[$ntypes];
-
-static GType *
-get_object_types (void)
-{
- gpointer g_object_class;
- gint i = 0;
-
-${get_types}
- object_types[i] = G_TYPE_INVALID;
-
- /* reference the GObjectClass to initialize the param spec pool
- * potentially needed by interfaces. See http://bugs.gnome.org/571820 */
- g_object_class = g_type_class_ref (G_TYPE_OBJECT);
-
- /* Need to make sure all the types are loaded in and initialize
- * their signals and properties.
- */
- for (i=0; object_types[i]; i++) {
- if (G_TYPE_IS_CLASSED (object_types[i]))
- g_type_class_ref (object_types[i]);
- if (G_TYPE_IS_INTERFACE (object_types[i]))
- g_type_default_interface_ref (object_types[i]);
- }
-
- g_type_class_unref (g_object_class);
-
- return object_types;
-}
-
-/*
- * This uses GObject type functions to output signal prototypes and the object
- * hierarchy.
- */
-
-/* The output files */
-const gchar *signals_filename = "$new_signals_filename";
-const gchar *hierarchy_filename = "$new_hierarchy_filename";
-const gchar *interfaces_filename = "$new_interfaces_filename";
-const gchar *prerequisites_filename = "$new_prerequisites_filename";
-const gchar *args_filename = "$new_args_filename";
-
-static void output_signals (void);
-static void output_object_signals (FILE *fp,
- GType object_type);
-static void output_object_signal (FILE *fp,
- const gchar *object_class_name,
- guint signal_id);
-static const gchar * get_type_name (GType type,
- gboolean * is_pointer);
-static void output_object_hierarchy (void);
-static void output_hierarchy (FILE *fp,
- GType type,
- guint level);
-
-static void output_object_interfaces (void);
-static void output_interfaces (FILE *fp,
- GType type);
-
-static void output_interface_prerequisites (void);
-static void output_prerequisites (FILE *fp,
- GType type);
-
-static void output_args (void);
-static void output_object_args (FILE *fp, GType object_type);
-
-int
-main (int argc, char *argv[])
-{
- $TYPE_INIT_FUNC;
-
- get_object_types ();
-
- output_signals ();
- output_object_hierarchy ();
- output_object_interfaces ();
- output_interface_prerequisites ();
- output_args ();
-
- return 0;
-}
-
-static void
-output_signals (void)
-{
- FILE *fp;
- gint i;
-
- fp = fopen (signals_filename, "w");
- if (fp == NULL) {
- g_warning ("Couldn't open output file: %s : %s", signals_filename, g_strerror(errno));
- return;
- }
-
- for (i = 0; object_types[i]; i++)
- output_object_signals (fp, object_types[i]);
-
- fclose (fp);
-}
-
-static gint
-compare_signals (const void *a, const void *b)
-{
- const guint *signal_a = a;
- const guint *signal_b = b;
-
- return strcmp (g_signal_name (*signal_a), g_signal_name (*signal_b));
-}
-
-/* This outputs all the signals of one object. */
-static void
-output_object_signals (FILE *fp, GType object_type)
-{
- const gchar *object_class_name;
- guint *signals, n_signals;
- guint sig;
-
- if (G_TYPE_IS_INSTANTIATABLE (object_type) ||
- G_TYPE_IS_INTERFACE (object_type)) {
-
- object_class_name = g_type_name (object_type);
-
- signals = g_signal_list_ids (object_type, &n_signals);
- qsort (signals, n_signals, sizeof (guint), compare_signals);
-
- for (sig = 0; sig < n_signals; sig++) {
- output_object_signal (fp, object_class_name, signals[sig]);
- }
- g_free (signals);
- }
-}
-
-/* This outputs one signal. */
-static void
-output_object_signal (FILE *fp,
- const gchar *object_name,
- guint signal_id)
-{
- GSignalQuery query_info;
- const gchar *type_name, *ret_type, *object_arg, *arg_name;
- gchar *pos, *object_arg_lower;
- gboolean is_pointer;
- gchar buffer[1024];
- guint i, param;
- gint param_num, widget_num, event_num, callback_num;
- gint *arg_num;
- gchar signal_name[128];
- gchar flags[16];
-
- /* g_print ("Object: %s Signal: %u\\n", object_name, signal_id);*/
-
- param_num = 1;
- widget_num = event_num = callback_num = 0;
-
- g_signal_query (signal_id, &query_info);
-
- /* Output the signal object type and the argument name. We assume the
- * type is a pointer - I think that is OK. We remove "Gtk" or "Gnome" and
- * convert to lower case for the argument name. */
- pos = buffer;
- sprintf (pos, "%s ", object_name);
- pos += strlen (pos);
-
- /* Try to come up with a sensible variable name for the first arg
- * It chops off 2 know prefixes :/ and makes the name lowercase
- * It should replace lowercase -> uppercase with '_'
- * GFileMonitor -> file_monitor
- * GIOExtensionPoint -> extension_point
- * GtkTreeView -> tree_view
- * if 2nd char is upper case too
- * search for first lower case and go back one char
- * else
- * search for next upper case
- */
- if (!strncmp (object_name, "Gtk", 3))
- object_arg = object_name + 3;
- else if (!strncmp (object_name, "Gnome", 5))
- object_arg = object_name + 5;
- else
- object_arg = object_name;
-
- object_arg_lower = g_ascii_strdown (object_arg, -1);
- sprintf (pos, "*%s\\n", object_arg_lower);
- pos += strlen (pos);
- if (!strncmp (object_arg_lower, "widget", 6))
- widget_num = 2;
- g_free(object_arg_lower);
-
- /* Convert signal name to use underscores rather than dashes '-'. */
- strncpy (signal_name, query_info.signal_name, 127);
- signal_name[127] = '\\0';
- for (i = 0; signal_name[i]; i++) {
- if (signal_name[i] == '-')
- signal_name[i] = '_';
- }
-
- /* Output the signal parameters. */
- for (param = 0; param < query_info.n_params; param++) {
- type_name = get_type_name (query_info.param_types[param] & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer);
-
- /* Most arguments to the callback are called "arg1", "arg2", etc.
- GtkWidgets are called "widget", "widget2", ...
- GtkCallbacks are called "callback", "callback2", ... */
- if (!strcmp (type_name, "GtkWidget")) {
- arg_name = "widget";
- arg_num = &widget_num;
- }
- else if (!strcmp (type_name, "GtkCallback")
- || !strcmp (type_name, "GtkCCallback")) {
- arg_name = "callback";
- arg_num = &callback_num;
- }
- else {
- arg_name = "arg";
- arg_num = ¶m_num;
- }
- sprintf (pos, "%s ", type_name);
- pos += strlen (pos);
-
- if (!arg_num || *arg_num == 0)
- sprintf (pos, "%s%s\\n", is_pointer ? "*" : " ", arg_name);
- else
- sprintf (pos, "%s%s%i\\n", is_pointer ? "*" : " ", arg_name,
- *arg_num);
- pos += strlen (pos);
-
- if (arg_num) {
- if (*arg_num == 0)
- *arg_num = 2;
- else
- *arg_num += 1;
- }
- }
-
- pos = flags;
- /* We use one-character flags for simplicity. */
- if (query_info.signal_flags & G_SIGNAL_RUN_FIRST)
- *pos++ = 'f';
- if (query_info.signal_flags & G_SIGNAL_RUN_LAST)
- *pos++ = 'l';
- if (query_info.signal_flags & G_SIGNAL_RUN_CLEANUP)
- *pos++ = 'c';
- if (query_info.signal_flags & G_SIGNAL_NO_RECURSE)
- *pos++ = 'r';
- if (query_info.signal_flags & G_SIGNAL_DETAILED)
- *pos++ = 'd';
- if (query_info.signal_flags & G_SIGNAL_ACTION)
- *pos++ = 'a';
- if (query_info.signal_flags & G_SIGNAL_NO_HOOKS)
- *pos++ = 'h';
- *pos = 0;
-
- /* Output the return type and function name. */
- ret_type = get_type_name (query_info.return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer);
-
- fprintf (fp,
- "<SIGNAL>\\n<NAME>%s::%s</NAME>\\n<RETURNS>%s%s</RETURNS>\\n<FLAGS>%s</FLAGS>\\n%s</SIGNAL>\\n\\n",
- object_name, query_info.signal_name, ret_type, is_pointer ? "*" : "", flags, buffer);
-}
-
-
-/* Returns the type name to use for a signal argument or return value, given
- the GtkType from the signal info. It also sets is_pointer to TRUE if the
- argument needs a '*' since it is a pointer. */
-static const gchar *
-get_type_name (GType type, gboolean * is_pointer)
-{
- const gchar *type_name;
-
- *is_pointer = FALSE;
- type_name = g_type_name (type);
-
- switch (type) {
- case G_TYPE_NONE:
- case G_TYPE_CHAR:
- case G_TYPE_UCHAR:
- case G_TYPE_BOOLEAN:
- case G_TYPE_INT:
- case G_TYPE_UINT:
- case G_TYPE_LONG:
- case G_TYPE_ULONG:
- case G_TYPE_FLOAT:
- case G_TYPE_DOUBLE:
- case G_TYPE_POINTER:
- /* These all have normal C type names so they are OK. */
- return type_name;
-
- case G_TYPE_STRING:
- /* A GtkString is really a gchar*. */
- *is_pointer = TRUE;
- return "gchar";
-
- case G_TYPE_ENUM:
- case G_TYPE_FLAGS:
- /* We use a gint for both of these. Hopefully a subtype with a decent
- name will be registered and used instead, as GTK+ does itself. */
- return "gint";
-
- case G_TYPE_BOXED:
- /* The boxed type shouldn't be used itself, only subtypes. Though we
- return 'gpointer' just in case. */
- return "gpointer";
-
- case G_TYPE_PARAM:
- /* A GParam is really a GParamSpec*. */
- *is_pointer = TRUE;
- return "GParamSpec";
-
-#if GLIB_CHECK_VERSION (2, 25, 9)
- case G_TYPE_VARIANT:
- *is_pointer = TRUE;
- return "GVariant";
-#endif
-
-default:
- break;
- }
-
- /* For all GObject subclasses we can use the class name with a "*",
- e.g. 'GtkWidget *'. */
- if (g_type_is_a (type, G_TYPE_OBJECT))
- *is_pointer = TRUE;
-
- /* Also catch non GObject root types */
- if (G_TYPE_IS_CLASSED (type))
- *is_pointer = TRUE;
-
- /* All boxed subtypes will be pointers as well. */
- /* Exception: GStrv */
- if (g_type_is_a (type, G_TYPE_BOXED) &&
- !g_type_is_a (type, G_TYPE_STRV))
- *is_pointer = TRUE;
-
- /* All pointer subtypes will be pointers as well. */
- if (g_type_is_a (type, G_TYPE_POINTER))
- *is_pointer = TRUE;
-
- /* But enums are not */
- if (g_type_is_a (type, G_TYPE_ENUM) ||
- g_type_is_a (type, G_TYPE_FLAGS))
- *is_pointer = FALSE;
-
- return type_name;
-}
-
-
-/* This outputs the hierarchy of all objects which have been initialized,
- i.e. by calling their XXX_get_type() initialization function. */
-static void
-output_object_hierarchy (void)
-{
- FILE *fp;
- gint i,j;
- GType root, type;
- GType root_types[$ntypes] = { G_TYPE_INVALID, };
-
- fp = fopen (hierarchy_filename, "w");
- if (fp == NULL) {
- g_warning ("Couldn't open output file: %s : %s", hierarchy_filename, g_strerror(errno));
- return;
- }
- output_hierarchy (fp, G_TYPE_OBJECT, 0);
- output_hierarchy (fp, G_TYPE_INTERFACE, 0);
-
- for (i=0; object_types[i]; i++) {
- root = object_types[i];
- while ((type = g_type_parent (root))) {
- root = type;
- }
- if ((root != G_TYPE_OBJECT) && (root != G_TYPE_INTERFACE)) {
- for (j=0; root_types[j]; j++) {
- if (root == root_types[j]) {
- root = G_TYPE_INVALID; break;
- }
- }
- if(root) {
- root_types[j] = root;
- output_hierarchy (fp, root, 0);
- }
- }
- }
-
- fclose (fp);
-}
-
-/* This is called recursively to output the hierarchy of a object. */
-static void
-output_hierarchy (FILE *fp,
- GType type,
- guint level)
-{
- guint i;
- GType *children;
- guint n_children;
-
- if (!type)
- return;
-
- for (i = 0; i < level; i++)
- fprintf (fp, " ");
- fprintf (fp, "%s\\n", g_type_name (type));
-
- children = g_type_children (type, &n_children);
-
- for (i=0; i < n_children; i++)
- output_hierarchy (fp, children[i], level + 1);
-
- g_free (children);
-}
-
-static void output_object_interfaces (void)
-{
- guint i;
- FILE *fp;
-
- fp = fopen (interfaces_filename, "w");
- if (fp == NULL) {
- g_warning ("Couldn't open output file: %s : %s", interfaces_filename, g_strerror(errno));
- return;
- }
- output_interfaces (fp, G_TYPE_OBJECT);
-
- for (i = 0; object_types[i]; i++) {
- if (!g_type_parent (object_types[i]) &&
- (object_types[i] != G_TYPE_OBJECT) &&
- G_TYPE_IS_INSTANTIATABLE (object_types[i])) {
- output_interfaces (fp, object_types[i]);
- }
- }
- fclose (fp);
-}
-
-static void
-output_interfaces (FILE *fp,
- GType type)
-{
- guint i;
- GType *children, *interfaces;
- guint n_children, n_interfaces;
-
- if (!type)
- return;
-
- interfaces = g_type_interfaces (type, &n_interfaces);
-
- if (n_interfaces > 0) {
- fprintf (fp, "%s", g_type_name (type));
- for (i=0; i < n_interfaces; i++)
- fprintf (fp, " %s", g_type_name (interfaces[i]));
- fprintf (fp, "\\n");
- }
- g_free (interfaces);
-
- children = g_type_children (type, &n_children);
-
- for (i=0; i < n_children; i++)
- output_interfaces (fp, children[i]);
-
- g_free (children);
-}
-
-static void output_interface_prerequisites (void)
-{
- FILE *fp;
-
- fp = fopen (prerequisites_filename, "w");
- if (fp == NULL) {
- g_warning ("Couldn't open output file: %s : %s", prerequisites_filename, g_strerror(errno));
- return;
- }
- output_prerequisites (fp, G_TYPE_INTERFACE);
- fclose (fp);
-}
-
-static void
-output_prerequisites (FILE *fp,
- GType type)
-{
-#if GLIB_CHECK_VERSION(2,1,0)
- guint i;
- GType *children, *prerequisites;
- guint n_children, n_prerequisites;
-
- if (!type)
- return;
-
- prerequisites = g_type_interface_prerequisites (type, &n_prerequisites);
-
- if (n_prerequisites > 0) {
- fprintf (fp, "%s", g_type_name (type));
- for (i=0; i < n_prerequisites; i++)
- fprintf (fp, " %s", g_type_name (prerequisites[i]));
- fprintf (fp, "\\n");
- }
- g_free (prerequisites);
-
- children = g_type_children (type, &n_children);
-
- for (i=0; i < n_children; i++)
- output_prerequisites (fp, children[i]);
-
- g_free (children);
-#endif
-}
-
-static void
-output_args (void)
-{
- FILE *fp;
- gint i;
-
- fp = fopen (args_filename, "w");
- if (fp == NULL) {
- g_warning ("Couldn't open output file: %s : %s", args_filename, g_strerror(errno));
- return;
- }
-
- for (i = 0; object_types[i]; i++) {
- output_object_args (fp, object_types[i]);
- }
-
- fclose (fp);
-}
-
-static gint
-compare_param_specs (const void *a, const void *b)
-{
- GParamSpec *spec_a = *(GParamSpec **)a;
- GParamSpec *spec_b = *(GParamSpec **)b;
-
- return strcmp (g_param_spec_get_name (spec_a), g_param_spec_get_name (spec_b));
-}
-
-/* Its common to have unsigned properties restricted
- * to the signed range. Therefore we make this look
- * a bit nicer by spelling out the max constants.
- */
-
-/* Don't use "==" with floats, it might trigger a gcc warning. */
-#define GTKDOC_COMPARE_FLOAT(x, y) (x <= y && x >= y)
-
-static gchar*
-describe_double_constant (gdouble value)
-{
- gchar *desc;
-
- if (GTKDOC_COMPARE_FLOAT (value, G_MAXDOUBLE))
- desc = g_strdup ("G_MAXDOUBLE");
- else if (GTKDOC_COMPARE_FLOAT (value, G_MINDOUBLE))
- desc = g_strdup ("G_MINDOUBLE");
- else if (GTKDOC_COMPARE_FLOAT (value, -G_MAXDOUBLE))
- desc = g_strdup ("-G_MAXDOUBLE");
- else if (GTKDOC_COMPARE_FLOAT (value, G_MAXFLOAT))
- desc = g_strdup ("G_MAXFLOAT");
- else if (GTKDOC_COMPARE_FLOAT (value, G_MINFLOAT))
- desc = g_strdup ("G_MINFLOAT");
- else if (GTKDOC_COMPARE_FLOAT (value, -G_MAXFLOAT))
- desc = g_strdup ("-G_MAXFLOAT");
- else{
- /* make sure floats are output with a decimal dot irrespective of
- * current locale. Use formatd since we want human-readable numbers
- * and do not need the exact same bit representation when deserialising */
- desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
- g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g", value);
- }
-
- return desc;
-}
-
-static gchar*
-describe_signed_constant (gsize size, gint64 value)
-{
- gchar *desc = NULL;
-
- switch (size) {
- case 2:
- if (sizeof (int) == 2) {
- if (value == G_MAXINT)
- desc = g_strdup ("G_MAXINT");
- else if (value == G_MININT)
- desc = g_strdup ("G_MININT");
- }
- break;
- case 4:
- if (sizeof (int) == 4) {
- if (value == G_MAXINT)
- desc = g_strdup ("G_MAXINT");
- else if (value == G_MININT)
- desc = g_strdup ("G_MININT");
- }
- if (value == G_MAXLONG)
- desc = g_strdup ("G_MAXLONG");
- else if (value == G_MINLONG)
- desc = g_strdup ("G_MINLONG");
- break;
- case 8:
- if (value == G_MAXINT64)
- desc = g_strdup ("G_MAXINT64");
- else if (value == G_MININT64)
- desc = g_strdup ("G_MININT64");
- break;
- default:
- break;
- }
- if (!desc)
- desc = g_strdup_printf ("%" G_GINT64_FORMAT, value);
-
- return desc;
-}
-
-static gchar*
-describe_unsigned_constant (gsize size, guint64 value)
-{
- gchar *desc = NULL;
-
- switch (size) {
- case 2:
- if (sizeof (int) == 2) {
- if (value == (guint64)G_MAXINT)
- desc = g_strdup ("G_MAXINT");
- else if (value == G_MAXUINT)
- desc = g_strdup ("G_MAXUINT");
- }
- break;
- case 4:
- if (sizeof (int) == 4) {
- if (value == (guint64)G_MAXINT)
- desc = g_strdup ("G_MAXINT");
- else if (value == G_MAXUINT)
- desc = g_strdup ("G_MAXUINT");
- }
- if (value == (guint64)G_MAXLONG)
- desc = g_strdup ("G_MAXLONG");
- else if (value == G_MAXULONG)
- desc = g_strdup ("G_MAXULONG");
- break;
- case 8:
- if (value == G_MAXINT64)
- desc = g_strdup ("G_MAXINT64");
- else if (value == G_MAXUINT64)
- desc = g_strdup ("G_MAXUINT64");
- break;
- default:
- break;
- }
- if (!desc)
- desc = g_strdup_printf ("%" G_GUINT64_FORMAT, value);
-
- return desc;
-}
-
-static gchar*
-describe_type (GParamSpec *spec)
-{
- gchar *desc;
- gchar *lower;
- gchar *upper;
-
- if (G_IS_PARAM_SPEC_CHAR (spec)) {
- GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec);
-
- lower = describe_signed_constant (sizeof(gchar), pspec->minimum);
- upper = describe_signed_constant (sizeof(gchar), pspec->maximum);
- if (pspec->minimum == G_MININT8 && pspec->maximum == G_MAXINT8)
- desc = g_strdup ("");
- else if (pspec->minimum == G_MININT8)
- desc = g_strdup_printf ("<= %s", upper);
- else if (pspec->maximum == G_MAXINT8)
- desc = g_strdup_printf (">= %s", lower);
- else
- desc = g_strdup_printf ("[%s,%s]", lower, upper);
- g_free (lower);
- g_free (upper);
- }
- else if (G_IS_PARAM_SPEC_UCHAR (spec)) {
- GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec);
-
- lower = describe_unsigned_constant (sizeof(guchar), pspec->minimum);
- upper = describe_unsigned_constant (sizeof(guchar), pspec->maximum);
- if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT8)
- desc = g_strdup ("");
- else if (pspec->minimum == 0)
- desc = g_strdup_printf ("<= %s", upper);
- else if (pspec->maximum == G_MAXUINT8)
- desc = g_strdup_printf (">= %s", lower);
- else
- desc = g_strdup_printf ("[%s,%s]", lower, upper);
- g_free (lower);
- g_free (upper);
- }
- else if (G_IS_PARAM_SPEC_INT (spec)) {
- GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec);
-
- lower = describe_signed_constant (sizeof(gint), pspec->minimum);
- upper = describe_signed_constant (sizeof(gint), pspec->maximum);
- if (pspec->minimum == G_MININT && pspec->maximum == G_MAXINT)
- desc = g_strdup ("");
- else if (pspec->minimum == G_MININT)
- desc = g_strdup_printf ("<= %s", upper);
- else if (pspec->maximum == G_MAXINT)
- desc = g_strdup_printf (">= %s", lower);
- else
- desc = g_strdup_printf ("[%s,%s]", lower, upper);
- g_free (lower);
- g_free (upper);
- }
- else if (G_IS_PARAM_SPEC_UINT (spec)) {
- GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec);
-
- lower = describe_unsigned_constant (sizeof(guint), pspec->minimum);
- upper = describe_unsigned_constant (sizeof(guint), pspec->maximum);
- if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT)
- desc = g_strdup ("");
- else if (pspec->minimum == 0)
- desc = g_strdup_printf ("<= %s", upper);
- else if (pspec->maximum == G_MAXUINT)
- desc = g_strdup_printf (">= %s", lower);
- else
- desc = g_strdup_printf ("[%s,%s]", lower, upper);
- g_free (lower);
- g_free (upper);
- }
- else if (G_IS_PARAM_SPEC_LONG (spec)) {
- GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec);
-
- lower = describe_signed_constant (sizeof(glong), pspec->minimum);
- upper = describe_signed_constant (sizeof(glong), pspec->maximum);
- if (pspec->minimum == G_MINLONG && pspec->maximum == G_MAXLONG)
- desc = g_strdup ("");
- else if (pspec->minimum == G_MINLONG)
- desc = g_strdup_printf ("<= %s", upper);
- else if (pspec->maximum == G_MAXLONG)
- desc = g_strdup_printf (">= %s", lower);
- else
- desc = g_strdup_printf ("[%s,%s]", lower, upper);
- g_free (lower);
- g_free (upper);
- }
- else if (G_IS_PARAM_SPEC_ULONG (spec)) {
- GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec);
-
- lower = describe_unsigned_constant (sizeof(gulong), pspec->minimum);
- upper = describe_unsigned_constant (sizeof(gulong), pspec->maximum);
- if (pspec->minimum == 0 && pspec->maximum == G_MAXULONG)
- desc = g_strdup ("");
- else if (pspec->minimum == 0)
- desc = g_strdup_printf ("<= %s", upper);
- else if (pspec->maximum == G_MAXULONG)
- desc = g_strdup_printf (">= %s", lower);
- else
- desc = g_strdup_printf ("[%s,%s]", lower, upper);
- g_free (lower);
- g_free (upper);
- }
- else if (G_IS_PARAM_SPEC_INT64 (spec)) {
- GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec);
-
- lower = describe_signed_constant (sizeof(gint64), pspec->minimum);
- upper = describe_signed_constant (sizeof(gint64), pspec->maximum);
- if (pspec->minimum == G_MININT64 && pspec->maximum == G_MAXINT64)
- desc = g_strdup ("");
- else if (pspec->minimum == G_MININT64)
- desc = g_strdup_printf ("<= %s", upper);
- else if (pspec->maximum == G_MAXINT64)
- desc = g_strdup_printf (">= %s", lower);
- else
- desc = g_strdup_printf ("[%s,%s]", lower, upper);
- g_free (lower);
- g_free (upper);
- }
- else if (G_IS_PARAM_SPEC_UINT64 (spec)) {
- GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec);
-
- lower = describe_unsigned_constant (sizeof(guint64), pspec->minimum);
- upper = describe_unsigned_constant (sizeof(guint64), pspec->maximum);
- if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT64)
- desc = g_strdup ("");
- else if (pspec->minimum == 0)
- desc = g_strdup_printf ("<= %s", upper);
- else if (pspec->maximum == G_MAXUINT64)
- desc = g_strdup_printf (">= %s", lower);
- else
- desc = g_strdup_printf ("[%s,%s]", lower, upper);
- g_free (lower);
- g_free (upper);
- }
- else if (G_IS_PARAM_SPEC_FLOAT (spec)) {
- GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec);
-
- lower = describe_double_constant (pspec->minimum);
- upper = describe_double_constant (pspec->maximum);
- if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXFLOAT)) {
- if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT))
- desc = g_strdup ("");
- else
- desc = g_strdup_printf ("<= %s", upper);
- }
- else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT))
- desc = g_strdup_printf (">= %s", lower);
- else
- desc = g_strdup_printf ("[%s,%s]", lower, upper);
- g_free (lower);
- g_free (upper);
- }
- else if (G_IS_PARAM_SPEC_DOUBLE (spec)) {
- GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec);
-
- lower = describe_double_constant (pspec->minimum);
- upper = describe_double_constant (pspec->maximum);
- if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXDOUBLE)) {
- if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE))
- desc = g_strdup ("");
- else
- desc = g_strdup_printf ("<= %s", upper);
- }
- else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE))
- desc = g_strdup_printf (">= %s", lower);
- else
- desc = g_strdup_printf ("[%s,%s]", lower, upper);
- g_free (lower);
- g_free (upper);
- }
-#if GLIB_CHECK_VERSION (2, 12, 0)
- else if (G_IS_PARAM_SPEC_GTYPE (spec)) {
- GParamSpecGType *pspec = G_PARAM_SPEC_GTYPE (spec);
- gboolean is_pointer;
-
- desc = g_strdup (get_type_name (pspec->is_a_type, &is_pointer));
- }
-#endif
-#if GLIB_CHECK_VERSION (2, 25, 9)
- else if (G_IS_PARAM_SPEC_VARIANT (spec)) {
- GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec);
- gchar *variant_type;
-
- variant_type = g_variant_type_dup_string (pspec->type);
- desc = g_strdup_printf ("GVariant<%s>", variant_type);
- g_free (variant_type);
- }
-#endif
- else {
- desc = g_strdup ("");
- }
-
- return desc;
-}
-
-static gchar*
-describe_default (GParamSpec *spec)
-{
- gchar *desc;
-
- if (G_IS_PARAM_SPEC_CHAR (spec)) {
- GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec);
-
- desc = g_strdup_printf ("%d", pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_UCHAR (spec)) {
- GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec);
-
- desc = g_strdup_printf ("%u", pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_BOOLEAN (spec)) {
- GParamSpecBoolean *pspec = G_PARAM_SPEC_BOOLEAN (spec);
-
- desc = g_strdup_printf ("%s", pspec->default_value ? "TRUE" : "FALSE");
- }
- else if (G_IS_PARAM_SPEC_INT (spec)) {
- GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec);
-
- desc = g_strdup_printf ("%d", pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_UINT (spec)) {
- GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec);
-
- desc = g_strdup_printf ("%u", pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_LONG (spec)) {
- GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec);
-
- desc = g_strdup_printf ("%ld", pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_LONG (spec)) {
- GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec);
-
- desc = g_strdup_printf ("%lu", pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_INT64 (spec)) {
- GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec);
-
- desc = g_strdup_printf ("%" G_GINT64_FORMAT, pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_UINT64 (spec))
- {
- GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec);
-
- desc = g_strdup_printf ("%" G_GUINT64_FORMAT, pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_UNICHAR (spec)) {
- GParamSpecUnichar *pspec = G_PARAM_SPEC_UNICHAR (spec);
-
- if (g_unichar_isprint (pspec->default_value))
- desc = g_strdup_printf ("'%c'", pspec->default_value);
- else
- desc = g_strdup_printf ("%u", pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_ENUM (spec)) {
- GParamSpecEnum *pspec = G_PARAM_SPEC_ENUM (spec);
-
- GEnumValue *value = g_enum_get_value (pspec->enum_class, pspec->default_value);
- if (value)
- desc = g_strdup_printf ("%s", value->value_name);
- else
- desc = g_strdup_printf ("%d", pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_FLAGS (spec)) {
- GParamSpecFlags *pspec = G_PARAM_SPEC_FLAGS (spec);
- guint default_value;
- GString *acc;
-
- default_value = pspec->default_value;
- acc = g_string_new ("");
-
- while (default_value) {
- GFlagsValue *value = g_flags_get_first_value (pspec->flags_class, default_value);
-
- if (!value)
- break;
-
- if (acc->len > 0)
- g_string_append (acc, " | ");
- g_string_append (acc, value->value_name);
-
- default_value &= ~value->value;
- }
-
- if (default_value == 0)
- desc = g_string_free (acc, FALSE);
- else {
- desc = g_strdup_printf ("%d", pspec->default_value);
- g_string_free (acc, TRUE);
- }
- }
- else if (G_IS_PARAM_SPEC_FLOAT (spec)) {
- GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec);
-
- /* make sure floats are output with a decimal dot irrespective of
- * current locale. Use formatd since we want human-readable numbers
- * and do not need the exact same bit representation when deserialising */
- desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
- g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g",
- pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_DOUBLE (spec)) {
- GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec);
-
- /* make sure floats are output with a decimal dot irrespective of
- * current locale. Use formatd since we want human-readable numbers
- * and do not need the exact same bit representation when deserialising */
- desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
- g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g",
- pspec->default_value);
- }
- else if (G_IS_PARAM_SPEC_STRING (spec)) {
- GParamSpecString *pspec = G_PARAM_SPEC_STRING (spec);
-
- if (pspec->default_value) {
- gchar *esc = g_strescape (pspec->default_value, NULL);
- desc = g_strdup_printf ("\\"%s\\"", esc);
- g_free (esc);
- }
- else
- desc = g_strdup_printf ("NULL");
- }
-#if GLIB_CHECK_VERSION (2, 25, 9)
- else if (G_IS_PARAM_SPEC_VARIANT (spec)) {
- GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec);
-
- if (pspec->default_value)
- desc = g_variant_print (pspec->default_value, TRUE);
- else
- desc = g_strdup ("NULL");
- }
-#endif
- else {
- desc = g_strdup ("");
- }
-
- return desc;
-}
-
-
-static void
-output_object_args (FILE *fp, GType object_type)
-{
- gpointer class;
- const gchar *object_class_name;
- guint arg;
- gchar flags[16], *pos;
- GParamSpec **properties;
- guint n_properties;
- gboolean child_prop;
- gboolean style_prop;
- gboolean is_pointer;
- const gchar *type_name;
- gchar *type_desc;
- gchar *default_value;
-
- if (G_TYPE_IS_OBJECT (object_type)) {
- class = g_type_class_peek (object_type);
- if (!class)
- return;
-
- properties = g_object_class_list_properties (class, &n_properties);
- }
-#if GLIB_MAJOR_VERSION > 2 || (GLIB_MAJOR_VERSION == 2 && GLIB_MINOR_VERSION >= 3)
- else if (G_TYPE_IS_INTERFACE (object_type)) {
- class = g_type_default_interface_ref (object_type);
-
- if (!class)
- return;
-
- properties = g_object_interface_list_properties (class, &n_properties);
- }
-#endif
- else
- return;
-
- object_class_name = g_type_name (object_type);
-
- child_prop = FALSE;
- style_prop = FALSE;
-
- while (TRUE) {
- qsort (properties, n_properties, sizeof (GParamSpec *), compare_param_specs);
- for (arg = 0; arg < n_properties; arg++) {
- GParamSpec *spec = properties[arg];
- const gchar *nick, *blurb, *dot;
-
- if (spec->owner_type != object_type)
- continue;
-
- pos = flags;
- /* We use one-character flags for simplicity. */
- if (child_prop && !style_prop)
- *pos++ = 'c';
- if (style_prop)
- *pos++ = 's';
- if (spec->flags & G_PARAM_READABLE)
- *pos++ = 'r';
- if (spec->flags & G_PARAM_WRITABLE)
- *pos++ = 'w';
- if (spec->flags & G_PARAM_CONSTRUCT)
- *pos++ = 'x';
- if (spec->flags & G_PARAM_CONSTRUCT_ONLY)
- *pos++ = 'X';
- *pos = 0;
-
- nick = g_param_spec_get_nick (spec);
- blurb = g_param_spec_get_blurb (spec);
-
- dot = "";
- if (blurb) {
- int str_len = strlen (blurb);
- if (str_len > 0 && blurb[str_len - 1] != '.')
- dot = ".";
- }
-
- type_desc = describe_type (spec);
- default_value = describe_default (spec);
- type_name = get_type_name (spec->value_type, &is_pointer);
- fprintf (fp, "<ARG>\\n<NAME>%s::%s</NAME>\\n<TYPE>%s%s</TYPE>\\n<RANGE>%s</RANGE>\\n<FLAGS>%s</FLAGS>\\n<NICK>%s</NICK>\\n<BLURB>%s%s</BLURB>\\n<DEFAULT>%s</DEFAULT>\\n</ARG>\\n\\n",
- object_class_name, g_param_spec_get_name (spec), type_name, is_pointer ? "*" : "", type_desc, flags, nick ? nick : "(null)", blurb ? blurb : "(null)", dot, default_value);
- g_free (type_desc);
- g_free (default_value);
- }
-
- g_free (properties);
-
-#ifdef GTK_IS_CONTAINER_CLASS
- if (!child_prop && GTK_IS_CONTAINER_CLASS (class)) {
- properties = gtk_container_class_list_child_properties (class, &n_properties);
- child_prop = TRUE;
- continue;
- }
-#endif
-
-#ifdef GTK_IS_CELL_AREA_CLASS
- if (!child_prop && GTK_IS_CELL_AREA_CLASS (class)) {
- properties = gtk_cell_area_class_list_cell_properties (class, &n_properties);
- child_prop = TRUE;
- continue;
- }
-#endif
-
-#ifdef GTK_IS_WIDGET_CLASS
-#if GTK_CHECK_VERSION(2,1,0)
- if (!style_prop && GTK_IS_WIDGET_CLASS (class)) {
- properties = gtk_widget_class_list_style_properties (GTK_WIDGET_CLASS (class), &n_properties);
- style_prop = TRUE;
- continue;
- }
-#endif
-#endif
-
-EOT
-
-if ($QUERY_CHILD_PROPERTIES) {
- print OUTPUT <<EOT;
- if (!child_prop) {
- properties = $QUERY_CHILD_PROPERTIES (class, &n_properties);
- if (properties) {
- child_prop = TRUE;
- continue;
- }
- }
-
-EOT
-}
-
-print OUTPUT <<EOT;
- break;
- }
-}
-EOT
-
-close OUTPUT;
-
-# Compile and run our file
-
-unless ($CC) {
- $CC = $ENV{CC} ? $ENV{CC} : "gcc";
-}
-unless ($LD) {
- $LD = $ENV{LD} ? $ENV{LD} : $CC;
-}
-unless ($CFLAGS) {
- $CFLAGS = $ENV{CFLAGS} ? $ENV{CFLAGS} : "";
-}
-unless ($LDFLAGS) {
- $LDFLAGS = $ENV{LDFLAGS} ? $ENV{LDFLAGS} : "";
-}
-unless ($RUN) {
- $RUN = $ENV{RUN} ? $ENV{RUN} : "";
-}
-
-my $o_file = $CC =~ /libtool/ ? "$MODULE-scan.lo" :"$MODULE-scan.o";
-
-my $stdout="";
-if (!defined($VERBOSE) or $VERBOSE eq "0") {
- $stdout=">/dev/null";
-}
-
-# Compiling scanner
-my $command = "$CC $stdout $CFLAGS -c -o $o_file $MODULE-scan.c";
-system("($command)") == 0 or die "Compilation of scanner failed: $!\n";
-
-# Linking scanner
-# FIXME: Can we turn off as-needed for the docs (or better fix it?)
-#$command = "$LD -Wl,--no-as-needed $o_file $LDFLAGS -o $MODULE-scan@EXEEXT@";
-$command = "$LD $stdout $o_file $LDFLAGS -o $MODULE-scan@EXEEXT@";
-system("($command)") == 0 or die "Linking of scanner failed: $!\n";
-
-# Running scanner $MODULE-scan ";
-system("($RUN ./$MODULE-scan@EXEEXT@)") == 0 or die "Scan failed: $!\n";
-
-
-if (!defined($ENV{"GTK_DOC_KEEP_INTERMEDIATE"})) {
- unlink "./$MODULE-scan.c", "./$MODULE-scan.o", "./$MODULE-scan.lo", "./$MODULE-scan@EXEEXT@";
-}
-
-&UpdateFileIfChanged ($old_signals_filename, $new_signals_filename, 0);
-&UpdateFileIfChanged ($old_hierarchy_filename, $new_hierarchy_filename, 0);
-&UpdateFileIfChanged ($old_interfaces_filename, $new_interfaces_filename, 0);
-&UpdateFileIfChanged ($old_prerequisites_filename, $new_prerequisites_filename, 0);
-&UpdateFileIfChanged ($old_args_filename, $new_args_filename, 0);
+import argparse
+import os
+import sys
+sys.path.append('@PYTHON_PACKAGE_DIR@')
+
+from gtkdoc import common, config, scangobj
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(
+ description='gtkdoc-rebase version %s - introspect g-objects' % config.version)
+ parser.add_argument('--version', action='version', version=config.version)
+ parser.add_argument('--module', required=True,
+ help='Name of the doc module being parsed')
+ parser.add_argument('--types', default='',
+ help='The name of the file to store the types in')
+ parser.add_argument('--type-init-func', default='',
+ help='The init function(s) to call instead of g_type_init()')
+ parser.add_argument('--query-child-properties', default='',
+ help='A function that returns a list of child properties for a class')
+ parser.add_argument('--output-dir', default='.',
+ help='The directory where the results are stored')
+ parser.add_argument('--cc', default='', help='The compiler to use')
+ parser.add_argument('--ld', default='', help='The linker to use')
+ parser.add_argument('--cflags', default='', help='Compiler flags')
+ parser.add_argument('--ldflags', default='', help='Linker flags')
+ parser.add_argument('--run', default='',
+ help='Command for running the scanner')
+ parser.add_argument('--verbose', action='store_true', default=False,
+ help='Print extra output while processing')
+
+ options = parser.parse_args()
+
+ if options.types == '':
+ options.types = os.path.join(options.output_dir, options.module + '.types')
+
+ if not options.cc:
+ options.cc = os.environ.get('CC', 'gcc')
+ if not options.ld:
+ options.ld = os.environ.get('LD', options.cc)
+ if not options.cflags:
+ options.cflags = os.environ.get('CFLAGS', '')
+ if not options.ldflags:
+ options.ldflags = os.environ.get('LDFLAGS', '')
+ if not options.run:
+ options.run = os.environ.get('RUN', '')
+
+ common.setup_logging()
+
+ sys.exit(scangobj.run(options))
--- /dev/null
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2007 David Nečas
+# 2007-2017 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.
+#
+
+"""
+The check tool runs various tests on built documentation and outputs test
+results. Can be run druring make check, by adding this to the documentations
+Makefile.am: TESTS = $(GTKDOC_CHECK).
+"""
+
+# Support both Python 2 and 3
+from __future__ import print_function
+
+import os
+import re
+from glob import glob
+
+
+class FileFormatError(Exception):
+ pass
+
+
+def grep(regexp, lines, what):
+ pattern = re.compile(regexp)
+ for line in lines:
+ for match in re.finditer(pattern, line):
+ return match.group(1)
+ raise FileFormatError(what)
+
+
+def check_empty(filename):
+ with open(filename) as f:
+ count = sum(1 for line in f if line.strip())
+ return count
+
+
+def check_includes(filename):
+ # Check that each XML file in the xml directory is included in doc_main_file
+ with open(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))
+
+ return num_missing
+
+
+def get_variable(env, lines, variable):
+ value = env.get(variable,
+ grep(r'^\s*' + variable + r'\s*=\s*(\S+)', lines, variable))
+ return value
+
+
+def read_file(filename):
+ with open(filename) as f:
+ return f.read().splitlines()
+
+
+def run_tests(workdir, doc_module, doc_main_file):
+ checks = 4
+
+ print('Running suite(s): gtk-doc-' + doc_module)
+
+ # Test #1
+ statusfilename = os.path.join(workdir, doc_module + '-undocumented.txt')
+ statusfile = read_file(statusfilename)
+ try:
+ undocumented = int(grep(r'^(\d+)\s+not\s+documented\.\s*$',
+ statusfile, 'number of undocumented symbols'))
+ incomplete = int(grep(r'^(\d+)\s+symbols?\s+incomplete\.\s*$',
+ statusfile, 'number of incomplete symbols'))
+ except FileFormatError as e:
+ print('Cannot find %s in %s' % (str(e), statusfilename))
+ return checks # consider all failed
+
+ total = undocumented + incomplete
+ if total:
+ print(doc_module + '-undocumented.txt:1:E: %d undocumented or incomplete symbols' % total)
+
+ # Test #2
+ undeclared = check_empty(os.path.join(workdir, doc_module + '-undeclared.txt'))
+ if undeclared:
+ print(doc_module + '-undeclared.txt:1:E: %d undeclared symbols\n' % undeclared)
+
+ # Test #3
+ unused = check_empty(os.path.join(workdir, doc_module + '-unused.txt'))
+ if unused:
+ print(doc_module + '-unused.txt:1:E: %d unused documentation entries\n' % unused)
+
+ # Test #4
+ missing_includes = check_includes(os.path.join(workdir, doc_main_file))
+
+ # Test Summary
+ failed = (total > 0) + (undeclared != 0) + (unused != 0) + (missing_includes != 0)
+ rate = 100.0 * (checks - failed) / checks
+ print("%.1f%%: Checks %d, Failures: %d" % (rate, checks, failed))
+ return failed
+
+
+def run(options=None):
+ """Runs the tests.
+
+ Returns:
+ int: a system exit code.
+ """
+
+ # Get parameters from test env, if not there try to grab them from the makefile
+ # We like Makefile.am more but builddir does not necessarily contain one.
+ makefilename = 'Makefile.am'
+ if not os.path.exists(makefilename):
+ makefilename = 'Makefile'
+ makefile = read_file(makefilename)
+
+ # For historic reasons tests are launched in srcdir
+ workdir = os.environ.get('BUILDDIR', None)
+ if not workdir:
+ workdir = '.'
+
+ try:
+ doc_module = get_variable(os.environ, makefile, 'DOC_MODULE')
+ doc_main_file = get_variable(os.environ, makefile, 'DOC_MAIN_SGML_FILE')
+ except FileFormatError as e:
+ print('Cannot find %s in %s' % (str(e), makefilename))
+ return 1
+
+ doc_main_file = doc_main_file.replace('$(DOC_MODULE)', doc_module)
+
+ return run_tests(workdir, doc_module, doc_main_file)
--- /dev/null
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2001 Damon Chaplin
+# 2007-2016 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.
+#
+
+# 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
+
+from . import config
+
+
+def setup_logging():
+ """Check GTKDOC_TRACE environment variable.
+
+ Set python log level to the value of the environment variable (DEBUG, INFO,
+ WARNING, ERROR and CRITICAL) or INFO if the environment variable is empty.
+ """
+ log_level = os.environ.get('GTKDOC_TRACE')
+ if log_level == '':
+ log_level = 'INFO'
+ if log_level:
+ 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 we get UnicodeEncodeError:
+ if not sys.stdout.encoding:
+ import codecs
+ sys.stdout = codecs.getwriter('utf8')(sys.stdout)
+
+
+def UpdateFileIfChanged(old_file, new_file, make_backup):
+ """Compares the old version of the file with the new version and if the
+ file has changed it moves the new version into the old versions place. This
+ is used so we only change files if needed, so we can do proper dependency
+ tracking.
+
+ Args:
+ old_file (str): The pathname of the old file.
+ new_file (str): The pathname of the new version of the file.
+ make_backup (bool): True if a backup of the old file should be kept.
+ It will have the .bak suffix added to the file name.
+
+ Returns:
+ bool: It returns False if the file hasn't changed, and True if it has.
+ """
+
+ logging.debug("Comparing %s with %s...", old_file, new_file)
+
+ if os.path.exists(old_file):
+ old_contents = open(old_file, 'rb').read()
+ new_contents = open(new_file, 'rb').read()
+ if old_contents == new_contents:
+ os.unlink(new_file)
+ logging.debug("-> content is the same.")
+ return False
+
+ if make_backup:
+ backupname = old_file + '.bak'
+ if os.path.exists(backupname):
+ os.unlink(backupname)
+ os.rename(old_file, backupname)
+ else:
+ os.unlink(old_file)
+ logging.debug("-> content differs.")
+ else:
+ logging.debug("-> %s created.", old_file)
+
+ os.rename(new_file, old_file)
+ return True
+
+
+def GetModuleDocDir(module_name):
+ """Get the docdir for the given module via pkg-config
+
+ Args:
+ module_name (string): The module, e.g. 'glib-2.0'
+
+ Returns:
+ str: the doc directory
+ """
+ path = subprocess.check_output([config.pkg_config, '--variable=prefix', module_name], universal_newlines=True)
+ return os.path.join(path.strip(), 'share/gtk-doc/html')
+
+
+def LogWarning(filename, line, message):
+ """Log a warning in gcc style format
+
+ Args:
+ file (str): The file the error comes from
+ line (int): line number in the file
+ message (str): the error message to print
+ """
+ filename = filename or "unknown"
+
+ # TODO: write to stderr
+ print ("%s:%d: warning: %s" % (filename, line, message))
+
+
+def CreateValidSGMLID(xml_id):
+ """Creates a valid SGML 'id' from the given string.
+
+ According to http://www.w3.org/TR/html4/types.html#type-id "ID and NAME
+ tokens must begin with a letter ([A-Za-z]) and may be followed by any number
+ of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"),
+ and periods (".")."
+
+ When creating SGML IDS, we append ":CAPS" to all all-caps identifiers to
+ prevent name clashes (SGML ids are case-insensitive). (It basically never is
+ the case that mixed-case identifiers would collide.)
+
+ Args:
+ id (str): The text to be converted into a valid SGML id.
+
+ Returns:
+ str: The converted id.
+ """
+
+ # Special case, '_' would end up as '' so we use 'gettext-macro' instead.
+ if xml_id == '_':
+ return "gettext-macro"
+
+ xml_id = re.sub(r'[,;]', '', xml_id)
+ xml_id = re.sub(r'[_ ]', '-', xml_id)
+ xml_id = re.sub(r'^-+', '', xml_id)
+ xml_id = xml_id.replace('::', '-')
+ xml_id = xml_id.replace(':', '--')
+
+ # Append ":CAPS" to all all-caps identifiers
+ # FIXME: there are some inconsistencies here, we have index files containing e.g. TRUE--CAPS
+ if xml_id.isupper() and not xml_id.endswith('-CAPS'):
+ xml_id += ':CAPS'
+
+ return xml_id
+
+
+# Parsing helpers (move to mkdb ?)
+
+class ParseError(Exception):
+ pass
+
+
+def PreprocessStructOrEnum(declaration):
+ """Trim a type declaration for display.
+
+ Removes private sections and comments from the declaration.
+
+ Args:
+ declaration (str): the type declaration (struct or enum)
+
+ Returns:
+ str: the trimmed declaration
+ """
+ # Remove private symbols
+ # Assume end of declaration if line begins with '}'
+ declaration = re.sub(r'\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))',
+ '', declaration, flags=re.MULTILINE | re.DOTALL)
+
+ # Remove all other comments
+ declaration = re.sub(r'\n\s*/\*.*?\*/\s*\n', r'\n', declaration, flags=re.MULTILINE | re.DOTALL)
+ declaration = re.sub(r'/\*([^*]+|\*(?!/))*\*/', r' ', declaration)
+ declaration = re.sub(r'\n\s*//.*?\n', r'\n', declaration, flags=re.MULTILINE | re.DOTALL)
+ declaration = re.sub(r'//.*', '', declaration)
+
+ return declaration
+
+
+# TODO: output_function_params is always passed as 0
+# TODO: we always pass both functions
+def ParseStructDeclaration(declaration, is_object, output_function_params, typefunc=None, namefunc=None):
+ """ Parse a struct declaration.
+
+ Takes a structure declaration and breaks it into individual type declarations.
+
+ Args:
+ declaration (str): the declaration to parse
+ is_object (bool): true if this is an object structure
+ output_function_params (bool): true if full type is wanted for function pointer members
+ typefunc (func): function to apply to type
+ namefunc (func): function to apply to name
+
+ Returns:
+ dict: map of (symbol, decl) pairs describing the public declaration
+ """
+
+ # For forward struct declarations just return an empty array.
+ if re.search(r'(?:struct|union)\s+\S+\s*;', declaration, flags=re.MULTILINE | re.DOTALL):
+ return {}
+
+ # Remove all private parts of the declaration
+ # For objects, assume private
+ if is_object:
+ declaration = re.sub(r'''((?:struct|union)\s+\w*\s*\{)
+ .*?
+ (?:/\*\s*<\s*public\s*>\s*\*/|(?=\}))''',
+ r'\1', declaration, flags=re.MULTILINE | re.DOTALL | re.VERBOSE)
+
+ # Remove g_iface, parent_instance and parent_class if they are first member
+ declaration = re.sub(r'(\{)\s*(\w)+\s+(g_iface|parent_instance|parent_class)\s*;', r'\1', declaration)
+
+ declaration = PreprocessStructOrEnum(declaration)
+
+ if declaration.strip() == '':
+ return {}
+
+ # Prime match after "struct/union {" declaration
+ match = re.search(r'(?:struct|union)\s+\w*\s*\{', declaration, flags=re.MULTILINE | re.DOTALL)
+ if not match:
+ raise ParseError('Declaration "%s" does not begin with "struct/union [NAME] {"' % declaration)
+
+ logging.debug('public fields in struct/union: %s', declaration)
+
+ result = OrderedDict()
+
+ # Treat lines in sequence, allowing singly nested anonymous structs and unions.
+ for m in re.finditer(r'\s*([^{;]+(\{[^\}]*\}[^{;]+)?);', declaration[match.end():], flags=re.MULTILINE | re.DOTALL):
+ line = m.group(1)
+
+ logging.debug('checking "%s"', line)
+
+ if re.search(r'^\s*\}\s*\w*\s*$', line):
+ break
+
+ # FIXME: Just ignore nested structs and unions for now
+ if '{' in line:
+ continue
+
+ # ignore preprocessor directives
+ line = re.sub(r'^#.*?\n\s*', '', line, flags=re.MULTILINE | re.DOTALL)
+
+ if re.search(r'^\s*\}\s*\w*\s*$', line):
+ break
+
+ func_match = re.search(r'''^
+ (const\s+|G_CONST_RETURN\s+|unsigned\s+|signed\s+|long\s+|short\s+)*(struct\s+|enum\s+)? # mod1
+ (\w+)\s* # type
+ (\**(?:\s*restrict)?)\s* # ptr1
+ (const\s+)? # mod2
+ (\**\s*) # ptr2
+ (const\s+)? # mod3
+ \(\s*\*\s*(\w+)\s*\)\s* # name
+ \(([^)]*)\)\s* # func_params
+ $''', line, flags=re.VERBOSE)
+ vars_match = re.search(r'''^
+ ((?:const\s+|volatile\s+|unsigned\s+|signed\s+|short\s+|long\s+)?)(struct\s+|enum\s+)? # mod1
+ (\w+)\s* # type
+ (\** \s* const\s+)? # mod2
+ (.*) # variables
+ $''', line, flags=re.VERBOSE)
+
+ # Try to match structure members which are functions
+ if func_match:
+ mod1 = func_match.group(1) or ''
+ if func_match.group(2):
+ mod1 += func_match.group(2)
+ func_type = func_match.group(3)
+ ptr1 = func_match.group(4)
+ mod2 = func_match.group(5) or ''
+ ptr2 = func_match.group(6)
+ mod3 = func_match.group(7) or ''
+ name = func_match.group(8)
+ func_params = func_match.group(9)
+ ptype = func_type
+ if typefunc:
+ ptype = typefunc(func_type, '<type>%s</type>' % func_type)
+ pname = name
+ if namefunc:
+ pname = namefunc(name)
+
+ if output_function_params:
+ result[name] = '%s%s%s%s%s%s (*%s) (%s)' % (
+ mod1, ptype, ptr1, mod2, ptr2, mod3, pname, func_params)
+ else:
+ result[name] = '%s ()' % pname
+
+ # Try to match normal struct fields of comma-separated variables/
+ elif vars_match:
+ mod1 = vars_match.group(1) or ''
+ if vars_match.group(2):
+ mod1 += vars_match.group(2)
+ vtype = vars_match.group(3)
+ ptype = vtype
+ if typefunc:
+ ptype = typefunc(vtype, '<type>%s</type>' % vtype)
+ mod2 = vars_match.group(4) or ''
+ if mod2:
+ mod2 = ' ' + mod2
+ var_list = vars_match.group(5)
+
+ logging.debug('"%s" "%s" "%s" "%s"', mod1, vtype, mod2, var_list)
+
+ mod1 = mod1.replace(' ', ' ')
+ mod2 = mod2.replace(' ', ' ')
+
+ for n in var_list.split(','):
+ # Each variable can have any number of '*' before the identifier,
+ # and be followed by any number of pairs of brackets or a bit field specifier.
+ # e.g. *foo, ***bar, *baz[12][23], foo : 25.
+ m = re.search(
+ r'^\s* (\**(?:\s*restrict\b)?) \s* (\w+) \s* (?: ((?:\[[^\]]*\]\s*)+) | (:\s*\d+)?) \s* $',
+ n, flags=re.VERBOSE)
+ if m:
+ ptrs = m.group(1)
+ name = m.group(2)
+ array = m.group(3) or ''
+ bits = m.group(4)
+ if bits:
+ bits = ' ' + bits
+ else:
+ bits = ''
+ if ptrs and not ptrs.endswith('*'):
+ ptrs += ' '
+
+ array = array.replace(' ', ' ')
+ bits = bits.replace(' ', ' ')
+
+ pname = name
+ if namefunc:
+ pname = namefunc(name)
+
+ result[name] = '%s%s%s %s%s%s%s;' % (mod1, ptype, mod2, ptrs, pname, array, bits)
+
+ logging.debug('Matched line: %s%s%s %s%s%s%s', mod1, ptype, mod2, ptrs, pname, array, bits)
+ else:
+ logging.warning('Cannot parse struct field: "%s"', n)
+
+ else:
+ logging.warning('Cannot parse structure field: "%s"', line)
+
+ return result
+
+
+def ParseEnumDeclaration(declaration):
+ """Parse an enum declaration.
+
+ This function takes a enumeration declaration and breaks it into individual
+ enum member declarations.
+
+ Args:
+ declaration (str): the declaration to parse
+
+ Returns:
+ str: list of strings describing the public declaration
+ """
+
+ # For forward struct declarations just return an empty array.
+ if re.search(r'enum\s+\S+\s*;', declaration, flags=re.MULTILINE | re.DOTALL):
+ return ()
+
+ declaration = PreprocessStructOrEnum(declaration)
+
+ if declaration.strip() == '':
+ return ()
+
+ result = []
+
+ # Remove parenthesized expressions (in macros like GTK_BLAH = BLAH(1,3))
+ # to avoid getting confused by commas they might contain. This doesn't
+ # handle nested parentheses correctly.
+ declaration = re.sub(r'\([^)\n]+\)', '', declaration)
+
+ # Remove apostrophed characters (e.g. '}' or ',') values to avoid getting
+ # confused with end of enumeration.
+ # See https://bugzilla.gnome.org/show_bug.cgi?id=741305
+ declaration = re.sub(r'\'.\'', '', declaration)
+
+ # Remove comma from comma - possible whitespace - closing brace sequence
+ # since it is legal in GNU C and C99 to have a trailing comma but doesn't
+ # result in an actual enum member
+ declaration = re.sub(r',(\s*})', r'\1', declaration)
+
+ # Prime match after "typedef enum {" declaration
+ match = re.search(r'(typedef\s+)?enum\s*(\S+\s*)?\{', declaration, flags=re.MULTILINE | re.DOTALL)
+ if not match:
+ raise ParseError('Enum declaration "%s" does not begin with "typedef enum {" or "enum [NAME] {"' % declaration)
+
+ logging.debug("public fields in enum: %s'", declaration)
+
+ # Treat lines in sequence.
+ for m in re.finditer(r'\s*([^,\}]+)([,\}])', declaration[match.end():], flags=re.MULTILINE | re.DOTALL):
+ line = m.group(1)
+ terminator = m.group(2)
+
+ # ignore preprocessor directives
+ line = re.sub(r'^#.*?\n\s*', '', line, flags=re.MULTILINE | re.DOTALL)
+
+ m1 = re.search(r'^(\w+)\s*(=.*)?$', line, flags=re.MULTILINE | re.DOTALL)
+ # Special case for GIOCondition, where the values are specified by
+ # macros which expand to include the equal sign like '=1'.
+ m2 = re.search(r'^(\w+)\s*GLIB_SYSDEF_POLL', line, flags=re.MULTILINE | re.DOTALL)
+ if m1:
+ result.append(m1.group(1))
+ elif m2:
+ result.append(m2.group(1))
+ elif line.strip().startswith('#'):
+ # Special case include of <gdk/gdkcursors.h>, just ignore it
+ # Special case for #ifdef/#else/#endif, just ignore it
+ break
+ else:
+ logging.warning('Cannot parse enumeration member: %s', line)
+
+ if terminator == '}':
+ break
+
+ return result
+
+
+def ParseFunctionDeclaration(declaration, typefunc, namefunc):
+ """Parse a function declaration.
+
+ This function takes a function declaration and breaks it into individual
+ parameter declarations.
+
+ Args:
+ declaration (str): the declaration to parse
+ typefunc (func): function to apply to type
+ namefunc (func): function to apply to name
+
+ Returns:
+ dict: map of (symbol, decl) pairs describing the prototype
+ """
+
+ result = OrderedDict()
+
+ param_num = 0
+ while declaration:
+ logging.debug('decl=[%s]', declaration)
+
+ # skip whitespace and commas
+ declaration, n = re.subn(r'^[\s,]+', '', declaration)
+ if n:
+ continue
+
+ declaration, n = re.subn(r'^void\s*[,\n]', '', declaration)
+ if n:
+ if param_num != 0:
+ logging.warning('void used as parameter %d in function %s', param_num, declaration)
+ result['void'] = namefunc('<type>void</type>')
+ param_num += 1
+ continue
+
+ declaration, n = re.subn(r'^\s*[_a-zA-Z0-9]*\.\.\.\s*[,\n]', '', declaration)
+ if n:
+ result['...'] = namefunc('...')
+ param_num += 1
+ continue
+
+ # allow alphanumerics, '_', '[' & ']' in param names, try to match a standard parameter
+ # $1 $2 $3 $4 $5
+ regex = r'^\s*((?:(?:G_CONST_RETURN|G_GNUC_[A-Z_]+\s+|unsigned long|unsigned short|signed long|signed short|unsigned|signed|long|short|volatile|const)\s+)*)((?:struct\b|enum\b)?\s*\w+)\s*((?:(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*\*?\s*(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*)*)(\w+)?\s*((?:\[\S*\])*)\s*(?:G_GNUC_[A-Z_]+)?\s*[,\n]'
+ m = re.match(regex, declaration)
+ if m:
+ declaration = re.sub(regex, '', declaration)
+
+ pre = m.group(1) or ''
+ type = m.group(2)
+ ptr = m.group(3) or ''
+ name = m.group(4) or ''
+ array = m.group(5) or ''
+
+ pre = re.sub(r'\s+', ' ', pre)
+ type = re.sub(r'\s+', ' ', type)
+ ptr = re.sub(r'\s+', ' ', ptr)
+ ptr = re.sub(r'\s+$', '', ptr)
+ if ptr and not ptr.endswith('*'):
+ ptr += ' '
+
+ logging.debug('"%s" "%s" "%s" "%s" "%s"', pre, type, ptr, name, array)
+
+ m = re.search(r'^((un)?signed .*)\s?', pre)
+ if name == '' and m:
+ name = type
+ type = m.group(1)
+ pre = ''
+
+ if name == '':
+ name = 'Param' + str(param_num + 1)
+
+ logging.debug('"%s" "%s" "%s" "%s" "%s"', pre, type, ptr, name, array)
+
+ xref = typefunc(type, '<type>%s</type>' % type)
+ result[name] = namefunc('%s%s %s%s%s' % (pre, xref, ptr, name, array))
+ param_num += 1
+ continue
+
+ # Try to match parameters which are functions
+ # $1 $2 $3 $4 $5 $6 $7 $8
+ regex = r'^(const\s+|G_CONST_RETURN\s+|G_GNUC_[A-Z_]+\s+|signed\s+|unsigned\s+)*(struct\s+)?(\w+)\s*(\**)\s*(?:restrict\b)?\s*(const\s+)?\(\s*(\*[\s\*]*)\s*(\w+)\s*\)\s*\(([^)]*)\)\s*[,\n]'
+ m = re.match(regex, declaration)
+ if m:
+ declaration = re.sub(regex, '', declaration)
+
+ mod1 = m.group(1) or ''
+ if m.group(2):
+ mod1 += m.group(2)
+ type = m.group(3)
+ ptr1 = m.group(4)
+ mod2 = m.group(5) or ''
+ func_ptr = m.group(6)
+ name = m.group(7)
+ func_params = m.group(8) or ''
+
+ if ptr1 and not ptr1.endswith('*'):
+ ptr1 += ' '
+ func_ptr = re.sub(r'\s+', ' ', func_ptr)
+
+ logging.debug('"%s" "%s" "%s" "%s" "%s"', mod1, type, mod2, func_ptr, name)
+
+ xref = typefunc(type, '<type>%s</type>' % type)
+ result[name] = namefunc('%s%s%s%s (%s%s) (%s)' % (mod1, xref, ptr1, mod2, func_ptr, name, func_params))
+ param_num += 1
+ continue
+
+ logging.warning('Cannnot parse args for function in "%s"', declaration)
+ break
+
+ return result
+
+
+def ParseMacroDeclaration(declaration, namefunc):
+ """Parse a macro declaration.
+
+ This function takes a macro declaration and breaks it into individual
+ parameter declarations.
+
+ Args:
+ declaration (str): the declaration to parse
+ namefunc (func): function to apply to name
+
+ Returns:
+ dict: map of (symbol, decl) pairs describing the macro
+ """
+
+ result = OrderedDict()
+
+ logging.debug('decl=[%s]', declaration)
+
+ m = re.search(r'^\s*#\s*define\s+\w+\(([^\)]*)\)', declaration)
+ if m:
+ params = m.group(1)
+ params = re.sub(r'\n', '', params)
+
+ logging.debug('params=[%s]', params)
+
+ for param in params.split(','):
+ param = param.strip()
+
+ # Allow varargs variations
+ if param.endswith('...'):
+ param = '...'
+
+ if param != '':
+ result[param] = namefunc(param)
+
+ return result
--- /dev/null
+version = "1.26"
+
+# tools
+dblatex = '/usr/bin/dblatex'
+fop = ''
+highlight = '/usr/bin/source-highlight'
+highlight_options = '-t4 -s$SRC_LANG -cstyle.css --no-doc -i'
+pkg_config = '/usr/bin/pkg-config'
+xsltproc = '/usr/bin/xsltproc'
+
+# configured directories
+prefix = '/usr'
+datarootdir = "${prefix}/share".replace('${prefix}', prefix)
+datadir = "${datarootdir}".replace('${datarootdir}', datarootdir)
+
+exeext = ''
--- /dev/null
+version = "@VERSION@"
+
+# tools
+dblatex = '@DBLATEX@'
+fop = '@FOP@'
+highlight = '@HIGHLIGHT@'
+highlight_options = '@HIGHLIGHT_OPTIONS@'
+pkg_config = '@PKG_CONFIG@'
+xsltproc = '@XSLTPROC@'
+
+# configured directories
+prefix = '@prefix@'
+datarootdir = "@datarootdir@".replace('${prefix}', prefix)
+datadir = "@datadir@".replace('${datarootdir}', datarootdir)
+
+exeext = '@EXEEXT@'
--- /dev/null
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998 Damon Chaplin
+# 2007-2016 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.
+#
+
+''"Fix cross-references in the HTML documentation.''"
+
+# Support both Python 2 and 3
+from __future__ import print_function
+
+import logging
+import os
+import re
+import shlex
+import subprocess
+import sys
+import tempfile
+
+from . import common, config
+
+# This contains all the entities and their relative URLs.
+Links = {}
+
+# failing link targets we don't warn about even once
+NoLinks = {
+ 'char',
+ 'double',
+ 'float',
+ 'int',
+ 'long',
+ 'main',
+ 'signed',
+ 'unsigned',
+ 'va-list',
+ 'void',
+ 'GBoxed',
+ 'GEnum',
+ 'GFlags',
+ 'GInterface'
+}
+
+# Cache of dirs we already scanned for index files
+DirCache = {}
+
+
+def Run(options):
+ # logging.basicConfig(level=logging.INFO)
+
+ path_prefix = ''
+ m = re.search(r'(.*?)/share/gtk-doc/html', options.html_dir)
+ if m:
+ path_prefix = m.group(1)
+ logging.info('Path prefix: %s', path_prefix)
+ prefix_match = r'^' + re.escape(path_prefix) + r'/'
+
+ # We scan the directory containing GLib and any directories in GNOME2_PATH
+ # first, but these will be overriden by any later scans.
+ dir = common.GetModuleDocDir('glib-2.0')
+ if os.path.exists(dir):
+ # Some predefined link targets to get links into type hierarchies as these
+ # have no targets. These are always absolute for now.
+ Links['GBoxed'] = dir + '/gobject/gobject-Boxed-Types.html'
+ Links['GEnum'] = dir + '/gobject/gobject-Enumeration-and-Flag-Types.html'
+ Links['GFlags'] = dir + '/gobject/gobject-Enumeration-and-Flag-Types.html'
+ Links['GInterface'] = dir + '/gobject/GTypeModule.html'
+
+ if dir != options.html_dir:
+ logging.info('Scanning GLib directory: %s', dir)
+ ScanIndices(dir, (re.search(prefix_match, dir) is None))
+
+ path = os.environ.get('GNOME2_PATH')
+ if path:
+ for dir in path.split(':'):
+ dir += '/share/gtk-doc/html'
+ if os.path.exists(dir) and dir != options.html_dir:
+ logging.info('Scanning GNOME2_PATH directory: %s', dir)
+ ScanIndices(dir, (re.search(prefix_match, dir) is None))
+
+ logging.info('Scanning HTML_DIR directory: %s', options.html_dir)
+ ScanIndices(options.html_dir, 0)
+ logging.info('Scanning MODULE_DIR directory: %s', options.module_dir)
+ ScanIndices(options.module_dir, 0)
+
+ # check all extra dirs, but skip already scanned dirs or subdirs of those
+ for dir in options.extra_dir:
+ dir = dir.rstrip('/')
+ logging.info('Scanning EXTRA_DIR directory: %s', dir)
+
+ # If the --extra-dir option is not relative and is not sharing the same
+ # prefix as the target directory of the docs, we need to use absolute
+ # directories for the links
+ if not dir.startswith('..') and re.search(prefix_match, dir) is None:
+ ScanIndices(dir, 1)
+ else:
+ ScanIndices(dir, 0)
+
+ ReadSections(options)
+ FixCrossReferences(options)
+
+
+def ScanIndices(scan_dir, use_absolute_links):
+ if not scan_dir or scan_dir in DirCache:
+ return
+ DirCache[scan_dir] = 1
+
+ logging.info('Scanning index directory: %s, absolute: %d', scan_dir, use_absolute_links)
+
+ # TODO(ensonic): this code is the same as in rebase.py
+ if not os.path.isdir(scan_dir):
+ logging.info('Cannot open dir "%s"', scan_dir)
+ return
+
+ subdirs = []
+ for entry in sorted(os.listdir(scan_dir)):
+ full_entry = os.path.join(scan_dir, entry)
+ if os.path.isdir(full_entry):
+ subdirs.append(full_entry)
+ continue
+
+ if entry.endswith('.devhelp2'):
+ # if devhelp-file is good don't read index.sgml
+ ReadDevhelp(full_entry, use_absolute_links)
+ 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 :/
+ print(''' Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138 . For now run:
+gunzip %s
+''' % full_entry)
+ elif entry.endswith('.devhelp2.gz') and not os.path.exists(full_entry[:-3]):
+ # debian/ubuntu started to compress this as *devhelp2.gz :/
+ print('''Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/1466210 . For now run:
+gunzip %d
+''' % full_entry)
+ # we could consider supporting: gzip module
+
+ # Now recursively scan the subdirectories.
+ for subdir in subdirs:
+ ScanIndices(subdir, use_absolute_links)
+
+
+def ReadDevhelp(file, use_absolute_links):
+ # Determine the absolute directory, to be added to links in $file
+ # if we need to use an absolute link.
+ # $file will be something like /prefix/gnome/share/gtk-doc/html/gtk/$file
+ # We want the part up to 'html/.*' since the links in $file include
+ # the rest.
+ dir = "../"
+ if use_absolute_links:
+ # For uninstalled index files we'd need to map the path to where it
+ # will be installed to
+ if not file.startswith('./'):
+ m = re.search(r'(.*\/)(.*?)\/.*?\.devhelp2', file)
+ dir = m.group(1) + m.group(2) + '/'
+ else:
+ m = re.search(r'(.*\/)(.*?)\/.*?\.devhelp2', file)
+ if m:
+ dir += m.group(2) + '/'
+ else:
+ dir = ''
+
+ logging.info('Scanning index file=%s, absolute=%d, dir=%s', file, use_absolute_links, dir)
+
+ for line in open(file):
+ m = re.search(r' link="([^#]*)#([^"]*)"', line)
+ if m:
+ link = m.group(1) + '#' + m.group(2)
+ logging.debug('Found id: %s href: %s', m.group(2), link)
+ Links[m.group(2)] = dir + link
+
+
+def ReadSections(options):
+ for line in open(options.module + '-sections.txt'):
+ m1 = re.search(r'^<SUBSECTION\s*(.*)>', line)
+ if line.startswith('#') or line.strip() == '':
+ continue
+ elif line.startswith('<SECTION>'):
+ subsection = ''
+ elif m1:
+ subsection = m1.group(1)
+ elif line.startswith('<SUBSECTION>') or line.startswith('</SECTION>'):
+ continue
+ elif re.search(r'^<TITLE>(.*)<\/TITLE>', line):
+ continue
+ elif re.search(r'^<FILE>(.*)<\/FILE>', line):
+ continue
+ elif re.search(r'^<INCLUDE>(.*)<\/INCLUDE>', line):
+ continue
+ else:
+ symbol = line.strip()
+ if subsection == "Standard" or subsection == "Private":
+ NoLinks.add(common.CreateValidSGMLID(symbol))
+
+
+def FixCrossReferences(options):
+ scan_dir = options.module_dir
+ # TODO(ensonic): use glob.glob()?
+ for entry in sorted(os.listdir(scan_dir)):
+ full_entry = os.path.join(scan_dir, entry)
+ if os.path.isdir(full_entry):
+ continue
+ elif entry.endswith('.html') or entry.endswith('.htm'):
+ FixHTMLFile(options, full_entry)
+
+
+def FixHTMLFile(options, file):
+ logging.info('Fixing file: %s', file)
+
+ content = open(file).read()
+ if sys.version_info < (3,):
+ content = content.decode('utf-8')
+
+ if config.highlight:
+ # FIXME: ideally we'd pass a clue about the example language to the highligher
+ # unfortunately the "language" attribute is not appearing in the html output
+ # we could patch the customization to have <code class="xxx"> inside of <pre>
+ if config.highlight.endswith('vim'):
+ def repl_func(m):
+ return HighlightSourceVim(options, m.group(1), m.group(2))
+ content = re.sub(
+ r'<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>',
+ repl_func, content, flags=re.DOTALL)
+ else:
+ def repl_func(m):
+ return HighlightSource(options, m.group(1), m.group(2))
+ content = re.sub(
+ r'<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>',
+ repl_func, content, flags=re.DOTALL)
+
+ content = re.sub(r'\<GTKDOCLINK\s+HREF=\"(.*?)\"\>(.*?)\</GTKDOCLINK\>',
+ r'\<GTKDOCLINK\ HREF=\"\1\"\>\2\</GTKDOCLINK\>', content, flags=re.DOTALL)
+
+ # From the highlighter we get all the functions marked up. Now we can turn them into GTKDOCLINK items
+ def repl_func(m):
+ return MakeGtkDocLink(m.group(1), m.group(2), m.group(3))
+ content = re.sub(r'(<span class=\"function\">)(.*?)(</span>)', repl_func, content, flags=re.DOTALL)
+ # We can also try the first item in stuff marked up as 'normal'
+ content = re.sub(
+ r'(<span class=\"normal\">\s*)(.+?)((\s+.+?)?\s*</span>)', repl_func, content, flags=re.DOTALL)
+
+ lines = content.rstrip().split('\n')
+
+ def repl_func_with_ix(i):
+ def repl_func(m):
+ return MakeXRef(options, file, i + 1, m.group(1), m.group(2))
+ return repl_func
+
+ for i in range(len(lines)):
+ lines[i] = re.sub(r'<GTKDOCLINK\s+HREF="([^"]*)"\s*>(.*?)</GTKDOCLINK\s*>', repl_func_with_ix(i), lines[i])
+ if 'GTKDOCLINK' in lines[i]:
+ logging.info('make xref failed for line %d: "%s"', i, lines[i])
+
+ new_file = file + '.new'
+ content = '\n'.join(lines)
+ if sys.version_info < (3,):
+ content = content.encode('utf-8')
+ open(new_file, 'w').write(content)
+
+ os.unlink(file)
+ os.rename(new_file, file)
+
+
+def MakeXRef(options, file, line, id, text):
+ href = Links.get(id)
+
+ # This is a workaround for some inconsistency we have with CreateValidSGMLID
+ if not href and ':' in id:
+ href = Links.get(id.replace(':', '--'))
+ # poor mans plural support
+ if not href and 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:
+ # if it is a link to same module, remove path to make it work uninstalled
+ m = re.search(r'^\.\./' + options.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 "<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)
+ return text
+
+
+def MakeGtkDocLink(pre, symbol, post):
+ id = common.CreateValidSGMLID(symbol)
+
+ # these are implicitely created links in highlighed sources
+ # we don't want warnings for those if the links cannot be resolved.
+ NoLinks.add(id)
+
+ return pre + '<GTKDOCLINK HREF="' + id + '">' + symbol + '</GTKDOCLINK>' + post
+
+
+def HighlightSource(options, type, source):
+ # write source to a temp file
+ # FIXME: use .c for now to hint the language to the highlighter
+ with tempfile.NamedTemporaryFile(mode='w+', suffix='.c') as f:
+ temp_source_file = HighlightSourcePreProcess(f, source)
+ highlight_options = config.highlight_options.replace('$SRC_LANG', options.src_lang)
+
+ logging.info('running %s %s %s', config.highlight, highlight_options, temp_source_file)
+
+ # format source
+ highlighted_source = subprocess.check_output(
+ [config.highlight] + shlex.split(highlight_options) + [temp_source_file]).decode('utf-8')
+ logging.debug('result: [%s]', highlighted_source)
+ if config.highlight.endswith('/source-highlight'):
+ highlighted_source = re.sub(r'^<\!-- .*? -->', '', highlighted_source, flags=re.MULTILINE | re.DOTALL)
+ highlighted_source = re.sub(
+ r'<pre><tt>(.*?)</tt></pre>', r'\1', highlighted_source, flags=re.MULTILINE | re.DOTALL)
+ elif config.highlight.endswith('/highlight'):
+ # need to rewrite the stylesheet classes
+ highlighted_source = highlighted_source.replace('<span class="gtkdoc com">', '<span class="comment">')
+ highlighted_source = highlighted_source.replace('<span class="gtkdoc dir">', '<span class="preproc">')
+ highlighted_source = highlighted_source.replace('<span class="gtkdoc kwd">', '<span class="function">')
+ highlighted_source = highlighted_source.replace('<span class="gtkdoc kwa">', '<span class="keyword">')
+ highlighted_source = highlighted_source.replace('<span class="gtkdoc line">', '<span class="linenum">')
+ highlighted_source = highlighted_source.replace('<span class="gtkdoc num">', '<span class="number">')
+ highlighted_source = highlighted_source.replace('<span class="gtkdoc str">', '<span class="string">')
+ highlighted_source = highlighted_source.replace('<span class="gtkdoc sym">', '<span class="symbol">')
+ # maybe also do
+ # highlighted_source = re.sub(r'</span>(.+)<span', '</span><span class="normal">\1</span><span')
+
+ return HighlightSourcePostprocess(type, highlighted_source)
+
+
+def HighlightSourceVim(options, type, source):
+ # write source to a temp file
+ with tempfile.NamedTemporaryFile(mode='w+', suffix='.h') as f:
+ temp_source_file = HighlightSourcePreProcess(f, source)
+
+ # format source
+ # TODO(ensonic): use p.communicate()
+ script = "echo 'let html_number_lines=0|let html_use_css=1|let html_use_xhtml=1|e %s|syn on|set syntax=%s|run! syntax/2html.vim|w! %s.html|qa!' | " % (
+ temp_source_file, options.src_lang, temp_source_file)
+ script += "%s -n -e -u NONE -T xterm >/dev/null" % config.highlight
+ subprocess.check_call([script], shell=True)
+
+ highlighted_source = open(temp_source_file + ".html").read()
+ highlighted_source = re.sub(r'.*<pre\b[^>]*>\n', '', highlighted_source, flags=re.MULTILINE)
+ highlighted_source = re.sub(r'</pre>.*', '', highlighted_source, flags=re.MULTILINE)
+
+ # need to rewrite the stylesheet classes
+ highlighted_source = highlighted_source.replace('<span class="Comment">', '<span class="comment">')
+ highlighted_source = highlighted_source.replace('<span class="PreProc">', '<span class="preproc">')
+ highlighted_source = highlighted_source.replace('<span class="Statement">', '<span class="keyword">')
+ highlighted_source = highlighted_source.replace('<span class="Identifier">', '<span class="function">')
+ highlighted_source = highlighted_source.replace('<span class="Constant">', '<span class="number">')
+ highlighted_source = highlighted_source.replace('<span class="Special">', '<span class="symbol">')
+ highlighted_source = highlighted_source.replace('<span class="Type">', '<span class="type">')
+
+ # remove temp files
+ os.unlink(temp_source_file + '.html')
+
+ return HighlightSourcePostprocess(type, highlighted_source)
+
+
+def HighlightSourcePreProcess(f, source):
+ # chop of leading and trailing empty lines, leave leading space in first real line
+ source = source.strip(' ')
+ source = source.strip('\n')
+ source = source.rstrip()
+
+ # cut common indent
+ m = re.search(r'^(\s+)', source)
+ if m:
+ source = re.sub(r'^' + m.group(1), '', source, flags=re.MULTILINE)
+ # avoid double entity replacement
+ source = source.replace('<', '<')
+ source = source.replace('>', '>')
+ source = source.replace('&', '&')
+ if sys.version_info < (3,):
+ source = source.encode('utf-8')
+ f.write(source)
+ f.flush()
+ return f.name
+
+
+def HighlightSourcePostprocess(type, highlighted_source):
+ # chop of leading and trailing empty lines
+ highlighted_source = highlighted_source.strip()
+
+ # turn common urls in comments into links
+ highlighted_source = re.sub(r'<span class="url">(.*?)</span>',
+ r'<span class="url"><a href="\1">\1</a></span>',
+ highlighted_source, flags=re.DOTALL)
+
+ # we do own line-numbering
+ line_count = highlighted_source.count('\n')
+ source_lines = '\n'.join([str(i) for i in range(1, line_count + 2)])
+
+ return """<div class="%s">
+ <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
+ <tbody>
+ <tr>
+ <td class="listing_lines" align="right"><pre>%s</pre></td>
+ <td class="listing_code"><pre class="programlisting">%s</pre></td>
+ </tr>
+ </tbody>
+ </table>
+</div>
+""" % (type, source_lines, highlighted_source)
--- /dev/null
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998 Damon Chaplin
+# 2007-2016 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.
+#
+
+"""
+Markdown to Docbook converter
+"""
+
+import logging
+import re
+
+# external functions
+ExpandAbbreviations = MakeXRef = MakeHashXRef = tagify = None
+
+# Elements to consider non-block items in MarkDown parsing
+MD_TEXT_LEVEL_ELEMENTS = {
+ 'emphasis', 'envar', 'filename', 'firstterm', 'footnote', 'function', 'literal',
+ 'manvolnum', 'option', 'replaceable', 'structfield', 'structname', 'title',
+ 'varname'
+}
+MD_ESCAPABLE_CHARS = r'\`*_{}[]()>#+-.!'
+MD_GTK_ESCAPABLE_CHARS = r'@%'
+
+
+def Init():
+ # TODO(enonic): find a better way to do this
+ global ExpandAbbreviations, MakeXRef, MakeHashXRef, tagify
+ from .mkdb import ExpandAbbreviations, MakeXRef, MakeHashXRef, tagify
+
+
+def MarkDownParseBlocks(lines, symbol, context):
+ md_blocks = []
+ md_block = {"type": ''}
+
+ logging.debug("parsing %s lines", len(lines))
+ for line in lines:
+ logging.info("type='%s', int='%s', parsing '%s'", md_block["type"], md_block.get('interrupted'), line)
+ first_char = None
+ if line:
+ first_char = line[0]
+
+ if md_block["type"] == "markup":
+ if 'closed' not in md_block:
+ if md_block["start"] in line:
+ md_block["depth"] += 1
+
+ if md_block["end"] in line:
+ if md_block["depth"] > 0:
+ md_block["depth"] -= 1
+ else:
+ logging.info("closing tag '%s'", line)
+ md_block["closed"] = 1
+ # TODO(ensonic): reparse inner text with MarkDownParseLines?
+
+ md_block["text"] += "\n" + line
+ logging.info("add to markup: '%s'", line)
+ continue
+
+ deindented_line = line.lstrip()
+
+ if md_block["type"] == "heading":
+ # a heading is ended by any level less than or equal
+ if md_block["level"] == 1:
+ heading_match = re.search(r'^[#][ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$', line)
+ if re.search(r'^={4,}[ \t]*$', line):
+ text = md_block["lines"].pop()
+ md_block.pop("interrupted", None)
+ md_blocks.append(md_block)
+ md_block = {'type': "heading",
+ 'text': text,
+ 'lines': [],
+ 'level': 1,
+ }
+ continue
+ elif heading_match:
+ md_block.pop("interrupted", None)
+ md_blocks.append(md_block)
+ md_block = {'type': "heading",
+ 'text': heading_match.group(1),
+ 'lines': [],
+ 'level': 1,
+ }
+ if heading_match.group(2):
+ md_block['id'] = heading_match.group(2)
+ continue
+ else:
+ # push lines into the block until the end is reached
+ md_block["lines"].append(line)
+ continue
+
+ else:
+ heading_match = re.search(r'^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$', line)
+ if re.search(r'^[=]{4,}[ \t]*$', line):
+ text = md_block["lines"].pop()
+ md_block.pop("interrupted", None)
+ md_blocks.append(md_block)
+ md_block = {'type': "heading",
+ 'text': text,
+ 'lines': [],
+ 'level': 1,
+ }
+ continue
+ elif re.search(r'^[-]{4,}[ \t]*$', line):
+ text = md_block["lines"].pop()
+ md_block.pop("interrupted", None)
+ md_blocks.append(md_block)
+ md_block = {'type': "heading",
+ 'text': text,
+ 'lines': [],
+ 'level': 2,
+ }
+ continue
+ elif heading_match:
+ md_block.pop("interrupted", None)
+ md_blocks.append(md_block)
+ md_block = {'type': "heading",
+ 'text': heading_match.group(2),
+ 'lines': [],
+ 'level': len(heading_match.group(1))
+ }
+ if heading_match.group(3):
+ md_block['id'] = heading_match.group(3)
+ continue
+ else:
+ # push lines into the block until the end is reached
+ md_block["lines"].append(line)
+ continue
+ elif md_block["type"] == "code":
+ end_of_code_match = re.search(r'^[ \t]*\]\|(.*)', line)
+ if end_of_code_match:
+ md_blocks.append(md_block)
+ md_block = {'type': "paragraph",
+ 'text': end_of_code_match.group(1),
+ 'lines': [],
+ }
+ else:
+ md_block["lines"].append(line)
+ continue
+
+ if deindented_line == '':
+ logging.info('setting "interrupted" due to empty line')
+ md_block["interrupted"] = 1
+ continue
+
+ if md_block["type"] == "quote":
+ if 'interrupted' not in md_block:
+ line = re.sub(r'^[ ]*>[ ]?', '', line)
+ md_block["lines"].append(line)
+ continue
+
+ elif md_block["type"] == "li":
+ marker = md_block["marker"]
+ marker_match = re.search(r'^([ ]{0,3})(%s)[ ](.*)' % marker, line)
+ if marker_match:
+ indentation = marker_match.group(1)
+ if md_block["indentation"] != indentation:
+ md_block["lines"].append(line)
+ else:
+ ordered = md_block["ordered"]
+ md_block.pop('last', None)
+ md_blocks.append(md_block)
+ md_block = {'type': "li",
+ 'ordered': ordered,
+ 'indentation': indentation,
+ 'marker': marker,
+ 'last': 1,
+ 'lines': [re.sub(r'^[ ]{0,4}', '', marker_match.group(3))],
+ }
+ continue
+
+ if 'interrupted' in md_block:
+ if first_char == " ":
+ md_block["lines"].append('')
+ line = re.sub(r'^[ ]{0,4}', '', line)
+ md_block["lines"].append(line)
+ md_block.pop("interrupted", None)
+ continue
+ else:
+ line = re.sub(r'^[ ]{0,4}', '', line)
+ md_block["lines"].append(line)
+ continue
+
+ # indentation sensitive types
+ heading_match = re.search(r'^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$', line)
+ code_match = re.search(r'^[ \t]*\|\[[ ]*(?:<!-- language="([^"]+?)" -->)?', line)
+ if heading_match:
+ # atx heading (#)
+ md_blocks.append(md_block)
+ md_block = {'type': "heading",
+ 'text': heading_match.group(2),
+ 'lines': [],
+ 'level': len(heading_match.group(1)),
+ }
+ if heading_match.group(3):
+ md_block['id'] = heading_match.group(3)
+ continue
+ elif re.search(r'^={4,}[ \t]*$', line):
+ # setext heading (====)
+
+ if md_block["type"] == "paragraph" and "interrupted" in md_block:
+ md_blocks.append(md_block.copy())
+ md_block["type"] = "heading"
+ md_block["lines"] = []
+ md_block["level"] = 1
+ continue
+ elif re.search(r'^-{4,}[ \t]*$', line):
+ # setext heading (-----)
+
+ if md_block["type"] == "paragraph" and "interrupted" in md_block:
+ md_blocks.append(md_block.copy())
+ md_block["type"] = "heading"
+ md_block["lines"] = []
+ md_block["level"] = 2
+
+ continue
+ elif code_match:
+ # code
+ md_block["interrupted"] = 1
+ md_blocks.append(md_block)
+ md_block = {'type': "code",
+ 'lines': [],
+ }
+ if code_match.group(1):
+ md_block['language'] = code_match.group(1)
+ continue
+
+ # indentation insensitive types
+ markup_match = re.search(r'^[ ]*<\??(\w+)[^>]*([\/\?])?[ \t]*>', line)
+ li_match = re.search(r'^([ ]*)[*+-][ ](.*)', line)
+ quote_match = re.search(r'^[ ]*>[ ]?(.*)', line)
+ if re.search(r'^[ ]*<!DOCTYPE/', line):
+ md_blocks.append(md_block)
+ md_block = {'type': "markup",
+ 'text': deindented_line,
+ 'start': '<',
+ 'end': '>',
+ 'depth': 0,
+ }
+
+ elif markup_match:
+ # markup, including <?xml version="1.0"?>
+ tag = markup_match.group(1)
+ is_self_closing = markup_match.group(2) is not None
+
+ # skip link markdown
+ # TODO(ensonic): consider adding more uri schemes (ftp, ...)
+ if re.search(r'https?', tag):
+ logging.info("skipping link '%s'", tag)
+ else:
+ # for TEXT_LEVEL_ELEMENTS, we want to keep them as-is in the paragraph
+ # instead of creation a markdown block.
+ scanning_for_end_of_text_level_tag = (
+ md_block["type"] == "paragraph" and
+ 'start' in md_block and
+ 'closed' not in md_block)
+ logging.info("markup found '%s', scanning %s ?", tag, scanning_for_end_of_text_level_tag)
+ if tag not in MD_TEXT_LEVEL_ELEMENTS and not scanning_for_end_of_text_level_tag:
+ md_blocks.append(md_block)
+
+ if is_self_closing:
+ logging.info("self-closing docbook '%s'", tag)
+ md_block = {'type': "self-closing tag",
+ 'text': deindented_line,
+ }
+ is_self_closing = 0
+ continue
+
+ logging.info("new markup '%s'", tag)
+ md_block = {'type': "markup",
+ 'text': deindented_line,
+ 'start': '<' + tag + '>',
+ 'end': '</' + tag + '>',
+ 'depth': 0,
+ }
+ if re.search(r'<\/%s>' % tag, deindented_line):
+ md_block["closed"] = 1
+
+ continue
+ else:
+ if tag in MD_TEXT_LEVEL_ELEMENTS:
+ logging.info("text level docbook '%s' in '%s' state", tag, md_block["type"])
+ # TODO(ensonic): handle nesting
+ if not scanning_for_end_of_text_level_tag:
+ if not re.search(r'<\/%s>' % tag, deindented_line):
+ logging.info("new text level markup '%s'", tag)
+ md_block["start"] = '<' + tag + '>'
+ md_block["end"] = '</' + tag + '>'
+ md_block.pop("closed", None)
+ logging.info("scanning for end of '%s'", tag)
+
+ else:
+ if md_block["end"] in deindented_line:
+ md_block["closed"] = 1
+ logging.info("found end of '%s'", tag)
+ elif li_match:
+ # li
+ md_blocks.append(md_block)
+ indentation = li_match.group(1)
+ md_block = {'type': "li",
+ 'ordered': 0,
+ 'indentation': indentation,
+ 'marker': "[*+-]",
+ 'first': 1,
+ 'last': 1,
+ 'lines': [re.sub(r'^[ ]{0,4}', '', li_match.group(2))],
+ }
+ continue
+ elif quote_match:
+ md_blocks.append(md_block)
+ md_block = {'type': "quote",
+ 'lines': [quote_match.group(1)],
+ }
+ continue
+
+ # list item
+ list_item_match = re.search(r'^([ ]{0,4})\d+[.][ ]+(.*)', line)
+ if list_item_match:
+ md_blocks.append(md_block)
+ indentation = list_item_match.group(1)
+ md_block = {'type': "li",
+ 'ordered': 1,
+ 'indentation': indentation,
+ 'marker': "\\d+[.]",
+ 'first': 1,
+ 'last': 1,
+ 'lines': [re.sub(r'^[ ]{0,4}', '', list_item_match.group(2))],
+ }
+ continue
+
+ # paragraph
+ if md_block["type"] == "paragraph":
+ if "interrupted" in md_block:
+ md_blocks.append(md_block)
+ md_block = {'type': "paragraph",
+ 'text': line,
+ }
+ logging.info("new paragraph due to interrupted")
+ else:
+ md_block["text"] += "\n" + line
+ logging.info("add to paragraph: '%s'", line)
+
+ else:
+ md_blocks.append(md_block)
+ md_block = {'type': "paragraph",
+ 'text': line,
+ }
+ logging.info("new paragraph due to different block type")
+
+ md_blocks.append(md_block)
+ md_blocks.pop(0)
+
+ return md_blocks
+
+
+def MarkDownParseSpanElementsInner(text, markersref):
+ markup = ''
+ markers = {i: 1 for i in markersref}
+
+ while text != '':
+ closest_marker = ''
+ closest_marker_position = -1
+ text_marker = ''
+ offset = 0
+ markers_rest = []
+
+ for marker, use in markers.items():
+ if not use:
+ continue
+
+ marker_position = text.find(marker)
+
+ if marker_position < 0:
+ markers[marker] = 0
+ continue
+
+ if closest_marker == '' or marker_position < closest_marker_position:
+ closest_marker = marker
+ closest_marker_position = marker_position
+
+ if closest_marker_position >= 0:
+ text_marker = text[closest_marker_position:]
+
+ if text_marker == '':
+ markup += text
+ text = ''
+ continue
+
+ markup += text[:closest_marker_position]
+ text = text[closest_marker_position:]
+ markers_rest = {k: v for k, v in markers.items() if v and k != closest_marker}
+
+ if closest_marker == '![' or closest_marker == '[':
+ element = None
+
+ # FIXME: '(?R)' is a recursive subpattern
+ # match a [...] block with no ][ inside or this thing again
+ # m = re.search(r'\[((?:[^][]|(?R))*)\]', text)
+ m = re.search(r'\[((?:[^][])*)\]', text)
+ if ']' in text and m:
+ element = {'!': text[0] == '!',
+ 'a': m.group(1),
+ }
+
+ offset = len(m.group(0))
+ if element['!']:
+ offset += 1
+ logging.debug("Recursive md-expr match: off=%d, text='%s', match='%s'", offset, text, m.group(1))
+
+ remaining_text = text[offset:]
+ m2 = re.search(r'''^\([ ]*([^)'"]*?)(?:[ ]+['"](.+?)['"])?[ ]*\)''', remaining_text)
+ m3 = re.search(r'^\s*\[([^\]<]*?)\]', remaining_text)
+ if m2:
+ element['»'] = m2.group(1)
+ if m2.group(2):
+ element['#'] = m2.group(2)
+ offset += len(m2.group(0))
+ elif m3:
+ element['ref'] = m3.group(1)
+ offset += len(m3.group(0))
+ else:
+ element = None
+
+ if element:
+ if '»' in element:
+ element['»'] = element['»'].replace('&', '&').replace('<', '<')
+
+ if element['!']:
+ markup += '<inlinemediaobject><imageobject><imagedata fileref="' + \
+ element['»'] + '"></imagedata></imageobject>'
+
+ if 'a' in element:
+ markup += "<textobject><phrase>" + element['a'] + "</phrase></textobject>"
+
+ markup += "</inlinemediaobject>"
+ elif 'ref' in element:
+ element['a'] = MarkDownParseSpanElementsInner(element['a'], markers_rest)
+ markup += '<link linkend="' + element['ref'] + '"'
+
+ if '#' in element:
+ # title attribute not supported
+ pass
+
+ markup += '>' + element['a'] + "</link>"
+ else:
+ element['a'] = MarkDownParseSpanElementsInner(element['a'], markers_rest)
+ markup += '<ulink url="' + element['»'] + '"'
+
+ if '#' in element:
+ # title attribute not supported
+ pass
+
+ markup += '>' + element['a'] + "</ulink>"
+
+ else:
+ markup += closest_marker
+ if closest_marker == '![':
+ offset = 2
+ else:
+ offset = 1
+
+ elif closest_marker == '<':
+ m4 = re.search(r'^<(https?:[\/]{2}[^\s]+?)>', text, flags=re.I)
+ m5 = re.search(r'^<([A-Za-z0-9._-]+?@[A-Za-z0-9._-]+?)>', text)
+ m6 = re.search(r'^<[^>]+?>', text)
+ if m4:
+ element_url = m4.group(1).replace('&', '&').replace('<', '<')
+
+ markup += '<ulink url="' + element_url + '">' + element_url + '</ulink>'
+ offset = len(m4.group(0))
+ elif m5:
+ markup += "<ulink url=\"mailto:" + m5.group(1) + "\">" + m5.group(1) + "</ulink>"
+ offset = len(m5.group(0))
+ elif m6:
+ markup += m6.group(0)
+ offset = len(m6.group(0))
+ else:
+ markup += "<"
+ offset = 1
+
+ elif closest_marker == "\\":
+ special_char = ''
+ if len(text) > 1:
+ special_char = text[1]
+ if special_char in MD_ESCAPABLE_CHARS or special_char in MD_GTK_ESCAPABLE_CHARS:
+ markup += special_char
+ offset = 2
+ else:
+ markup += "\\"
+ offset = 1
+
+ elif closest_marker == "`":
+ m7 = re.search(r'^(`+)([^`]+?)\1(?!`)', text)
+ if m7:
+ element_text = m7.group(2)
+ markup += "<literal>" + element_text + "</literal>"
+ offset = len(m7.group(0))
+ else:
+ markup += "`"
+ offset = 1
+
+ elif closest_marker == "@":
+ # Convert '@param()'
+ # FIXME: we could make those also links ($symbol.$2), but that would be less
+ # useful as the link target is a few lines up or down
+ m7 = re.search(r'^(\A|[^\\])\@(\w+((\.|->)\w+)*)\s*\(\)', text)
+ m8 = re.search(r'^(\A|[^\\])\@(\w+((\.|->)\w+)*)', text)
+ m9 = re.search(r'^\\\@', text)
+ if m7:
+ markup += m7.group(1) + "<parameter>" + m7.group(2) + "()</parameter>\n"
+ offset = len(m7.group(0))
+ elif m8:
+ # Convert '@param', but not '\@param'.
+ markup += m8.group(1) + "<parameter>" + m8.group(2) + "</parameter>\n"
+ offset = len(m8.group(0))
+ elif m9:
+ markup += r"\@"
+ offset = len(m9.group(0))
+ else:
+ markup += "@"
+ offset = 1
+
+ elif closest_marker == '#':
+ m10 = re.search(r'^(\A|[^\\])#([\w\-:\.]+[\w]+)\s*\(\)', text)
+ m11 = re.search(r'^(\A|[^\\])#([\w\-:\.]+[\w]+)', text)
+ m12 = re.search(r'^\\#', text)
+ if m10:
+ # handle #Object.func()
+ markup += m10.group(1) + MakeXRef(m10.group(2), tagify(m10.group(2) + "()", "function"))
+ offset = len(m10.group(0))
+ elif m11:
+ # Convert '#symbol', but not '\#symbol'.
+ markup += m11.group(1) + MakeHashXRef(m11.group(2), "type")
+ offset = len(m11.group(0))
+ elif m12:
+ markup += '#'
+ offset = len(m12.group(0))
+ else:
+ markup += '#'
+ offset = 1
+
+ elif closest_marker == "%":
+ m12 = re.search(r'^(\A|[^\\])\%(-?\w+)', text)
+ m13 = re.search(r'^\\%', text)
+ if m12:
+ # Convert '%constant', but not '\%constant'.
+ # Also allow negative numbers, e.g. %-1.
+ markup += m12.group(1) + MakeXRef(m12.group(2), tagify(m12.group(2), "literal"))
+ offset = len(m12.group(0))
+ elif m13:
+ markup += r"\%"
+ offset = len(m13.group(0))
+ else:
+ markup += "%"
+ offset = 1
+
+ if offset > 0:
+ text = text[offset:]
+
+ return markup
+
+
+def MarkDownParseSpanElements(text):
+ markers = ["\\", '<', '![', '[', "`", '%', '#', '@']
+
+ text = MarkDownParseSpanElementsInner(text, markers)
+
+ # Convert 'function()' or 'macro()'.
+ # if there is abc_*_def() we don't want to make a link to _def()
+ # FIXME: also handle abc(def(....)) : but that would need to be done recursively :/
+ def f(m):
+ return m.group(1) + MakeXRef(m.group(2), tagify(m.group(2) + "()", "function"))
+ text = re.sub(r'([^\*.\w])(\w+)\s*\(\)', f, text)
+ return text
+
+
+def ReplaceEntities(text):
+ entities = [["<", '<'],
+ [">", '>'],
+ ["*", '*'],
+ ["#", '#'],
+ ["%", '%'],
+ [":", ':'],
+ [""", '"'],
+ ["'", "'"],
+ [" ", ' '],
+ ["&", '&'], # Do this last, or the others get messed up.
+ ]
+
+ # Expand entities in <programlisting> even inside CDATA since
+ # we changed the definition of |[ to add CDATA
+ for i in entities:
+ text = re.sub(i[0], i[1], text)
+ return text
+
+
+def MarkDownOutputDocBook(blocksref, symbol, context):
+ output = ''
+ blocks = blocksref
+
+ for block in blocks:
+ #$output += "\n<!-- beg type='" . $block->{"type"} . "'-->\n"
+
+ if block["type"] == "paragraph":
+ text = MarkDownParseSpanElements(block["text"])
+ if context == "li" and output == '':
+ if 'interrupted' in block:
+ output += "\n<para>%s</para>\n" % text
+ else:
+ output += "<para>%s</para>" % text
+ if len(blocks) > 1:
+ output += "\n"
+ else:
+ output += "<para>%s</para>\n" % text
+
+ elif block["type"] == "heading":
+
+ title = MarkDownParseSpanElements(block["text"])
+
+ if block["level"] == 1:
+ tag = "refsect2"
+ else:
+ tag = "refsect3"
+
+ text = MarkDownParseLines(block["lines"], symbol, "heading")
+ if 'id' in block:
+ output += "<%s id=\"%s\">" % (tag, block["id"])
+ else:
+ output += "<%s>" % tag
+
+ output += "<title>%s</title>%s</%s>\n" % (title, text, tag)
+ elif block["type"] == "li":
+ tag = "itemizedlist"
+
+ if "first" in block:
+ if block["ordered"]:
+ tag = "orderedlist"
+ output += "<%s>\n" % tag
+
+ if "interrupted" in block:
+ block["lines"].append('')
+
+ text = MarkDownParseLines(block["lines"], symbol, "li")
+ output += "<listitem>" + text + "</listitem>\n"
+ if 'last' in block:
+ if block["ordered"]:
+ tag = "orderedlist"
+ output += "</%s>\n" % tag
+
+ elif block["type"] == "quote":
+ text = MarkDownParseLines(block["lines"], symbol, "quote")
+ output += "<blockquote>\n%s</blockquote>\n" % text
+ elif block["type"] == "code":
+ tag = "programlisting"
+
+ if "language" in block:
+ if block["language"] == "plain":
+ output += "<informalexample><screen><![CDATA[\n"
+ tag = "screen"
+ else:
+ output += "<informalexample><programlisting language=\"%s\"><![CDATA[\n" % block['language']
+ else:
+ output += "<informalexample><programlisting><![CDATA[\n"
+
+ logging.debug('listing for %s: [%s]', symbol, '\n'.join(block['lines']))
+ for line in block["lines"]:
+ output += ReplaceEntities(line) + "\n"
+
+ output += "]]></%s></informalexample>\n" % tag
+ elif block["type"] == "markup":
+ text = ExpandAbbreviations(symbol, block["text"])
+ output += text + "\n"
+ else:
+ output += block["text"] + "\n"
+
+ #$output += "\n<!-- end type='" . $block->{"type"} . "'-->\n"
+ return output
+
+
+def MarkDownParseLines(lines, symbol, context):
+ logging.info('md parse: ctx=%s, [%s]', context, '\n'.join(lines))
+ blocks = MarkDownParseBlocks(lines, symbol, context)
+ output = MarkDownOutputDocBook(blocks, symbol, context)
+ return output
+
+
+def MarkDownParse(text, symbol):
+ """Converts mark down syntax to the respective docbook.
+
+ http://de.wikipedia.org/wiki/Markdown
+ Inspired by the design of ParseDown
+ http://parsedown.org/
+ Copyright (c) 2013 Emanuil Rusev, erusev.com
+
+ SUPPORTED MARKDOWN
+ ==================
+
+ Atx-style Headers
+ -----------------
+
+ # Header 1
+
+ ## Header 2 ##
+
+ Setext-style Headers
+ --------------------
+
+ Header 1
+ ========
+
+ Header 2
+ --------
+
+ Ordered (unnested) Lists
+ ------------------------
+
+ 1. item 1
+
+ 1. item 2 with loooong
+ description
+
+ 3. item 3
+
+ Note: we require a blank line above the list items
+ """
+ # TODO(ensonic): it would be nice to add id parameters to the refsect2 elements
+
+ return MarkDownParseLines(text.splitlines(), symbol, '')
--- /dev/null
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998 Damon Chaplin
+# 2007-2016 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.
+#
+
+"""
+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
+import re
+import string
+import sys
+
+from . import common, md_to_db
+
+# Options
+MODULE = None
+DB_OUTPUT_DIR = None
+INLINE_MARKUP_MODE = None
+DEFAULT_STABILITY = None
+NAME_SPACE = ''
+ROOT_DIR = '.'
+
+# These global arrays store information on signals. Each signal has an entry
+# in each of these arrays at the same index, like a multi-dimensional array.
+SignalObjects = [] # The GtkObject which emits the signal.
+SignalNames = [] # The signal name.
+SignalReturns = [] # The return type.
+SignalFlags = [] # Flags for the signal
+SignalPrototypes = [] # The rest of the prototype of the signal handler.
+
+# These global arrays store information on Args. Each Arg has an entry
+# in each of these arrays at the same index, like a multi-dimensional array.
+ArgObjects = [] # The GtkObject which has the Arg.
+ArgNames = [] # The Arg name.
+ArgTypes = [] # The Arg type - gint, GtkArrowType etc.
+ArgFlags = [] # How the Arg can be used - readable/writable etc.
+ArgNicks = [] # The nickname of the Arg.
+ArgBlurbs = [] # Docstring of the Arg.
+ArgDefaults = [] # Default value of the Arg.
+ArgRanges = [] # The range of the Arg type
+
+# These global hashes store declaration info keyed on a symbol name.
+Declarations = {}
+DeclarationTypes = {}
+DeclarationConditional = {}
+DeclarationOutput = {}
+Deprecated = {}
+Since = {}
+StabilityLevel = {}
+StructHasTypedef = {}
+
+# These global hashes store the existing documentation.
+SymbolDocs = {}
+SymbolParams = {}
+SymbolAnnotations = {}
+
+# These global hashes store documentation scanned from the source files.
+SourceSymbolDocs = {}
+SourceSymbolParams = {}
+SourceSymbolSourceFile = {}
+SourceSymbolSourceLine = {}
+
+# all documentation goes in here, so we can do coverage analysis
+AllSymbols = {}
+AllIncompleteSymbols = {}
+AllUnusedSymbols = {}
+AllDocumentedSymbols = {}
+
+# Undeclared yet documented symbols
+UndeclaredSymbols = {}
+
+# These global arrays store GObject, subclasses and the hierarchy (also of
+# non-object derived types).
+Objects = []
+ObjectLevels = []
+ObjectRoots = {}
+
+Interfaces = {}
+Prerequisites = {}
+
+# holds the symbols which are mentioned in <MODULE>-sections.txt and in which
+# section they are defined
+KnownSymbols = {}
+SymbolSection = {}
+SymbolSectionId = {}
+
+# collects index entries
+IndexEntriesFull = {}
+IndexEntriesSince = {}
+IndexEntriesDeprecated = {}
+
+# Standard C preprocessor directives, which we ignore for '#' abbreviations.
+PreProcessorDirectives = {
+ 'assert', 'define', 'elif', 'else', 'endif', 'error', 'if', 'ifdef', 'ifndef',
+ 'include', 'line', 'pragma', 'unassert', 'undef', 'warning'
+}
+
+# remember used annotation (to write minimal glossary)
+AnnotationsUsed = {}
+
+# the regexp that parses the annotation is in ScanSourceFile()
+AnnotationDefinition = {
+ # the GObjectIntrospection annotations are defined at:
+ # https://live.gnome.org/GObjectIntrospection/Annotations
+ 'allow-none': "NULL is OK, both for passing and for returning.",
+ 'nullable': "NULL may be passed as the value in, out, in-out; or as a return value.",
+ 'not nullable': "NULL must not be passed as the value in, out, in-out; or as a return value.",
+ 'optional': "NULL may be passed instead of a pointer to a location.",
+ 'array': "Parameter points to an array of items.",
+ 'attribute': "Deprecated free-form custom annotation, replaced by (attributes) annotation.",
+ 'attributes': "Free-form key-value pairs.",
+ 'closure': "This parameter is a 'user_data', for callbacks; many bindings can pass NULL here.",
+ 'constructor': "This symbol is a constructor, not a static method.",
+ 'destroy': "This parameter is a 'destroy_data', for callbacks.",
+ 'default': "Default parameter value (for in case the <acronym>shadows</acronym>-to function has less parameters).",
+ 'element-type': "Generics and defining elements of containers and arrays.",
+ 'error-domains': "Typed errors. Similar to throws in Java.",
+ 'foreign': "This is a foreign struct.",
+ 'get-value-func': "The specified function is used to convert a struct from a GValue, must be a GTypeInstance.",
+ 'in': "Parameter for input. Default is <acronym>transfer none</acronym>.",
+ 'inout': "Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.",
+ 'in-out': "Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.",
+ 'method': "This is a method",
+ 'not-error': "A GError parameter is not to be handled like a normal GError.",
+ 'out': "Parameter for returning results. Default is <acronym>transfer full</acronym>.",
+ 'out caller-allocates': "Out parameter, where caller must allocate storage.",
+ 'out callee-allocates': "Out parameter, where caller must allocate storage.",
+ 'ref-func': "The specified function is used to ref a struct, must be a GTypeInstance.",
+ 'rename-to': "Rename the original symbol's name to SYMBOL.",
+ 'scope call': "The callback is valid only during the call to the method.",
+ 'scope async': "The callback is valid until first called.",
+ 'scope notified': "The callback is valid until the GDestroyNotify argument is called.",
+ 'set-value-func': "The specified function is used to convert from a struct to a GValue, must be a GTypeInstance.",
+ 'skip': "Exposed in C code, not necessarily available in other languages.",
+ 'transfer container': "Free data container after the code is done.",
+ 'transfer floating': "Alias for <acronym>transfer none</acronym>, used for objects with floating refs.",
+ 'transfer full': "Free data after the code is done.",
+ 'transfer none': "Don't free data after the code is done.",
+ 'type': "Override the parsed C type with given type.",
+ 'unref-func': "The specified function is used to unref a struct, must be a GTypeInstance.",
+ 'virtual': "This is the invoker for a virtual method.",
+ 'value': "The specified value overrides the evaluated value of the constant.",
+ # Stability Level definition
+ # https://bugzilla.gnome.org/show_bug.cgi?id=170860
+ 'Stable': '''The intention of a Stable interface is to enable arbitrary third parties to
+develop applications to these interfaces, release them, and have confidence that
+they will run on all minor releases of the product (after the one in which the
+interface was introduced, and within the same major release). Even at a major
+release, incompatible changes are expected to be rare, and to have strong
+justifications.
+''',
+ 'Unstable': '''Unstable interfaces are experimental or transitional. They are typically used to
+give outside developers early access to new or rapidly changing technology, or
+to provide an interim solution to a problem where a more general solution is
+anticipated. No claims are made about either source or binary compatibility from
+one minor release to the next.
+
+The Unstable interface level is a warning that these interfaces are subject to
+change without warning and should not be used in unbundled products.
+
+Given such caveats, customer impact need not be a factor when considering
+incompatible changes to an Unstable interface in a major or minor release.
+Nonetheless, when such changes are introduced, the changes should still be
+mentioned in the release notes for the affected release.
+''',
+ '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 specified and
+documented ways.
+''',
+}
+
+# Function and other declaration output settings.
+RETURN_TYPE_FIELD_WIDTH = 20
+MAX_SYMBOL_FIELD_WIDTH = 40
+
+# XML header
+doctype_header = None
+
+# refentry template
+REFENTRY = string.Template('''${header}
+<refentry id="${section_id}">
+<refmeta>
+<refentrytitle role="top_of_page" id="${section_id}.top_of_page">${title}</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>${MODULE} Library${image}</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>${title}</refname>
+<refpurpose>${short_desc}</refpurpose>
+</refnamediv>
+${stability}
+${functions_synop}${args_synop}${signals_synop}${object_anchors}${other_synop}${hierarchy}${prerequisites}${derived}${interfaces}${implementations}
+${include_output}
+<refsect1 id="${section_id}.description" role="desc">
+<title role="desc.title">Description</title>
+${extralinks}${long_desc}
+</refsect1>
+<refsect1 id="${section_id}.functions_details" role="details">
+<title role="details.title">Functions</title>
+${functions_details}
+</refsect1>
+<refsect1 id="${section_id}.other_details" role="details">
+<title role="details.title">Types and Values</title>
+${other_details}
+</refsect1>
+${args_desc}${signals_desc}${see_also}
+</refentry>
+''')
+
+
+def Run(options):
+ global MODULE, INLINE_MARKUP_MODE, DEFAULT_STABILITY, NAME_SPACE, \
+ DB_OUTPUT_DIR, doctype_header
+
+ # We should pass the options variable around instead of this global variable horror
+ # but too much of the code expects these to be around. Fix this once the transition is done.
+ MODULE = options.module
+ INLINE_MARKUP_MODE = options.xml_mode or options.sgml_mode
+ DEFAULT_STABILITY = options.default_stability
+ NAME_SPACE = options.name_space
+
+ main_sgml_file = options.main_sgml_file
+ if not main_sgml_file:
+ # backwards compatibility
+ if os.path.exists(MODULE + "-docs.sgml"):
+ main_sgml_file = MODULE + "-docs.sgml"
+ else:
+ main_sgml_file = MODULE + "-docs.xml"
+
+ # extract docbook header or define default
+ doctype_header = GetDocbookHeader(main_sgml_file)
+
+ # This is where we put all the DocBook output.
+ DB_OUTPUT_DIR = DB_OUTPUT_DIR if DB_OUTPUT_DIR else os.path.join(ROOT_DIR, "xml")
+ if not os.path.isdir(DB_OUTPUT_DIR):
+ os.mkdir(DB_OUTPUT_DIR)
+
+ ReadKnownSymbols(os.path.join(ROOT_DIR, MODULE + "-sections.txt"))
+ ReadSignalsFile(os.path.join(ROOT_DIR, MODULE + ".signals"))
+ ReadArgsFile(os.path.join(ROOT_DIR, MODULE + ".args"))
+ ReadObjectHierarchy(os.path.join(ROOT_DIR, MODULE + ".hierarchy"))
+ ReadInterfaces(os.path.join(ROOT_DIR, MODULE + ".interfaces"))
+ ReadPrerequisites(os.path.join(ROOT_DIR, MODULE + ".prerequisites"))
+
+ ReadDeclarationsFile(os.path.join(ROOT_DIR, MODULE + "-decl.txt"), 0)
+ if os.path.isfile(os.path.join(ROOT_DIR, MODULE + "-overrides.txt")):
+ ReadDeclarationsFile(os.path.join(ROOT_DIR, MODULE + "-overrides.txt"), 1)
+
+ # Scan sources
+ if options.source_suffixes:
+ suffix_list = ['.' + ext for ext in options.source_suffixes.split(',')]
+ else:
+ suffix_list = ['.c', '.h']
+
+ source_dirs = options.source_dir
+ ignore_files = options.ignore_files
+ logging.info(" ignore files: " + ignore_files)
+ for sdir in source_dirs:
+ ReadSourceDocumentation(sdir, suffix_list, source_dirs, ignore_files)
+
+ changed, book_top, book_bottom = OutputDB(os.path.join(ROOT_DIR, MODULE + "-sections.txt"), options)
+ OutputBook(main_sgml_file, book_top, book_bottom)
+
+ logging.info("All files created: %d", changed)
+
+ # If any of the DocBook files have changed, update the timestamp file (so
+ # it can be used for Makefile dependencies).
+ if changed or not os.path.exists(os.path.join(ROOT_DIR, "sgml.stamp")):
+
+ # try to detect the common prefix
+ # GtkWidget, GTK_WIDGET, gtk_widget -> gtk
+ if NAME_SPACE == '':
+ NAME_SPACE = DetermineNamespace()
+
+ logging.info('namespace prefix ="%s"', NAME_SPACE)
+
+ OutputIndex("api-index-full", IndexEntriesFull)
+ OutputIndex("api-index-deprecated", IndexEntriesDeprecated)
+ OutputSinceIndexes()
+ OutputAnnotationGlossary()
+
+ open(os.path.join(ROOT_DIR, 'sgml.stamp'), 'w').write('timestamp')
+
+
+def OutputObjectList():
+ """This outputs the alphabetical list of objects, in a columned table."""
+ # FIXME: Currently this also outputs ancestor objects which may not actually
+ # be in this module.
+ cols = 3
+
+ # FIXME: use .xml
+ 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 = open(new_object_index, 'w')
+
+ OUTPUT.write('''%s
+<informaltable pgwide="1" frame="none">
+<tgroup cols="%s">
+<colspec colwidth="1*"/>
+<colspec colwidth="1*"/>
+<colspec colwidth="1*"/>
+<tbody>
+''' % (MakeDocHeader("informaltable"), cols))
+
+ count = 0
+ object = None
+ for object in sorted(Objects):
+ xref = MakeXRef(object)
+ if count % cols == 0:
+ OUTPUT.write("<row>\n")
+ OUTPUT.write("<entry>%s</entry>\n" % xref)
+ if count % cols == cols - 1:
+ OUTPUT.write("</row>\n")
+ count += 1
+
+ if count == 0:
+ # emit an empty row, since empty tables are invalid
+ OUTPUT.write("<row><entry> </entry></row>\n")
+
+ else:
+ if count % cols > 0:
+ OUTPUT.write("</row>\n")
+
+ OUTPUT.write('''</tbody></tgroup></informaltable>\n''')
+ OUTPUT.close()
+
+ common.UpdateFileIfChanged(old_object_index, new_object_index, 0)
+
+
+def TrimTextBlock(desc):
+ """Trims extra whitespace.
+
+ Empty lines inside a block are preserved.
+ Args:
+ desc (str): the text block to trim. May contain newlines.
+ """
+
+ # strip trailing spaces on every line
+ return re.sub(r'\s+$', '\n', desc.lstrip(), flags=re.MULTILINE)
+
+
+def OutputDB(file, options):
+ """Generate docbook files.
+
+ This collects the output for each section of the docs, and outputs each file
+ when the end of the section is found.
+
+ Args:
+ file (str): the $MODULE-sections.txt file which contains all of the
+ functions/macros/structs etc. being documented, organised
+ into sections and subsections.
+ options: commandline options
+ """
+
+ logging.info("Reading: %s", file)
+ INPUT = open(file)
+ filename = ''
+ book_top = ''
+ book_bottom = ''
+ includes = options.default_includes or ''
+ section_includes = ''
+ in_section = 0
+ title = ''
+ section_id = ''
+ subsection = ''
+ num_symbols = 0
+ changed = 0
+ functions_synop = ''
+ other_synop = ''
+ functions_details = ''
+ other_details = ''
+ signals_synop = ''
+ signals_desc = ''
+ args_synop = ''
+ child_args_synop = ''
+ style_args_synop = ''
+ args_desc = ''
+ child_args_desc = ''
+ style_args_desc = ''
+ hierarchy_str = ''
+ hierarchy = []
+ interfaces = ''
+ implementations = ''
+ prerequisites = ''
+ derived = ''
+ file_objects = []
+ file_def_line = {}
+ symbol_def_line = {}
+
+ MergeSourceDocumentation()
+
+ line_number = 0
+ for line in INPUT:
+ line_number += 1
+
+ if line.startswith('#'):
+ continue
+
+ logging.info("section file data: %d: %s", line_number, line)
+
+ m1 = re.search(r'^<SUBSECTION\s*(.*)>', line, re.I)
+ m2 = re.search(r'^<TITLE>(.*)<\/TITLE', line)
+ m3 = re.search(r'^<FILE>(.*)<\/FILE>', line)
+ m4 = re.search(r'^<INCLUDE>(.*)<\/INCLUDE>', line)
+ m5 = re.search(r'^(\S+)', line)
+
+ if line.startswith('<SECTION>'):
+ num_symbols = 0
+ in_section = False
+ file_objects = []
+ symbol_def_line = {}
+
+ elif m1:
+ other_synop += "\n"
+ functions_synop += "\n"
+ subsection = m1.group(1)
+
+ elif line.startswith('<SUBSECTION>'):
+ continue
+ elif m2:
+ title = m2.group(1)
+ logging.info("Section: %s", title)
+
+ # We don't want warnings if object & class structs aren't used.
+ DeclarationOutput[title] = 1
+ DeclarationOutput["%sClass" % title] = 1
+ DeclarationOutput["%sIface" % title] = 1
+ DeclarationOutput["%sInterface" % title] = 1
+
+ elif m3:
+ filename = m3.group(1)
+ if not filename in file_def_line:
+ file_def_line[filename] = line_number
+ else:
+ common.LogWarning(file, line_number, "Double <FILE>%s</FILE> entry. Previous occurrence on line %s." %
+ (filename, file_def_line[filename]))
+ if title == '':
+ key = filename + ":Title"
+ if key in SourceSymbolDocs:
+ title = SourceSymbolDocs[key].rstrip()
+
+ elif m4:
+ if in_section:
+ section_includes = m4.group(1)
+ else:
+ if options.default_includes:
+ common.LogWarning(file, line_number, "Default <INCLUDE> being overridden by command line option.")
+ else:
+ includes = m4.group(1)
+
+ elif re.search(r'^<\/SECTION>', line):
+ logging.info("End of section: %s", title)
+ if num_symbols > 0:
+ # collect documents
+ book_bottom += " <xi:include href=\"xml/%s.xml\"/>\n" % filename
+
+ key = filename + ":Include"
+ if key in SourceSymbolDocs:
+ if section_includes:
+ common.LogWarning(file, line_number, "Section <INCLUDE> being overridden by inline comments.")
+ section_includes = SourceSymbolDocs[key]
+
+ if section_includes == '':
+ section_includes = includes
+
+ signals_synop = re.sub(r'^\n*', '', signals_synop)
+ signals_synop = re.sub(r'\n+$', '\n', signals_synop)
+
+ if signals_synop != '':
+ signals_synop = '''<refsect1 id="%s.signals" role="signal_proto">
+<title role="signal_proto.title">Signals</title>
+<informaltable frame="none">
+<tgroup cols="3">
+<colspec colname="signals_return" colwidth="150px"/>
+<colspec colname="signals_name" colwidth="300px"/>
+<colspec colname="signals_flags" colwidth="200px"/>
+<tbody>
+%s
+</tbody>
+</tgroup>
+</informaltable>
+</refsect1>
+''' % (section_id, signals_synop)
+ signals_desc = TrimTextBlock(signals_desc)
+ signals_desc = '''<refsect1 id="%s.signal-details" role="signals">
+<title role="signals.title">Signal Details</title>
+%s
+</refsect1>
+''' % (section_id, signals_desc)
+
+ args_synop = re.sub(r'^\n*', '', args_synop)
+ args_synop = re.sub(r'\n+$', '\n', args_synop)
+ if args_synop != '':
+ args_synop = '''<refsect1 id="%s.properties" role="properties">
+<title role="properties.title">Properties</title>
+<informaltable frame="none">
+<tgroup cols="3">
+<colspec colname="properties_type" colwidth="150px"/>
+<colspec colname="properties_name" colwidth="300px"/>
+<colspec colname="properties_flags" colwidth="200px"/>
+<tbody>
+%s
+</tbody>
+</tgroup>
+</informaltable>
+</refsect1>
+''' % (section_id, args_synop)
+ args_desc = TrimTextBlock(args_desc)
+ args_desc = '''<refsect1 id="%s.property-details" role="property_details">
+<title role="property_details.title">Property Details</title>
+%s
+</refsect1>
+''' % (section_id, args_desc)
+
+ child_args_synop = re.sub(r'^\n*', '', child_args_synop)
+ child_args_synop = re.sub(r'\n+$', '\n', child_args_synop)
+ if child_args_synop != '':
+ args_synop += '''<refsect1 id="%s.child-properties" role="child_properties">
+<title role="child_properties.title">Child Properties</title>
+<informaltable frame="none">
+<tgroup cols="3">
+<colspec colname="child_properties_type" colwidth="150px"/>
+<colspec colname="child_properties_name" colwidth="300px"/>
+<colspec colname="child_properties_flags" colwidth="200px"/>
+<tbody>
+%s
+</tbody>
+</tgroup>
+</informaltable>
+</refsect1>
+''' % (section_id, child_args_synop)
+ child_args_desc = TrimTextBlock(child_args_desc)
+ args_desc += '''<refsect1 id="%s.child-property-details" role="child_property_details">
+<title role="child_property_details.title">Child Property Details</title>
+%s
+</refsect1>
+''' % (section_id, child_args_desc)
+
+ style_args_synop = re.sub(r'^\n*', '', style_args_synop)
+ style_args_synop = re.sub(r'\n+$', '\n', style_args_synop)
+ if style_args_synop != '':
+ args_synop += '''<refsect1 id="%s.style-properties" role="style_properties">
+<title role="style_properties.title">Style Properties</title>
+<informaltable frame="none">
+<tgroup cols="3">
+<colspec colname="style_properties_type" colwidth="150px"/>
+<colspec colname="style_properties_name" colwidth="300px"/>
+<colspec colname="style_properties_flags" colwidth="200px"/>
+<tbody>
+%s
+</tbody>
+</tgroup>
+</informaltable>
+</refsect1>
+''' % (section_id, style_args_synop)
+ style_args_desc = TrimTextBlock(style_args_desc)
+ args_desc += '''<refsect1 id="%s.style-property-details" role="style_properties_details">
+<title role="style_properties_details.title">Style Property Details</title>
+%s
+</refsect1>
+''' % (section_id, style_args_desc)
+
+ hierarchy_str = AddTreeLineArt(hierarchy)
+ if hierarchy_str != '':
+ hierarchy_str = '''<refsect1 id="%s.object-hierarchy" role="object_hierarchy">
+<title role="object_hierarchy.title">Object Hierarchy</title>
+<screen>%s
+</screen>
+</refsect1>
+''' % (section_id, hierarchy_str)
+
+ interfaces = TrimTextBlock(interfaces)
+ if interfaces != '':
+ interfaces = '''<refsect1 id="%s.implemented-interfaces" role="impl_interfaces">
+<title role="impl_interfaces.title">Implemented Interfaces</title>
+%s
+</refsect1>
+''' % (section_id, interfaces)
+
+ implementations = TrimTextBlock(implementations)
+ if implementations != '':
+ implementations = '''<refsect1 id="%s.implementations" role="implementations">
+<title role="implementations.title">Known Implementations</title>
+%s
+</refsect1>
+''' % (section_id, implementations)
+
+ prerequisites = TrimTextBlock(prerequisites)
+ if prerequisites != '':
+ prerequisites = '''<refsect1 id="%s.prerequisites" role="prerequisites">
+<title role="prerequisites.title">Prerequisites</title>
+%s
+</refsect1>
+''' % (section_id, prerequisites)
+
+ derived = TrimTextBlock(derived)
+ if derived != '':
+ derived = '''<refsect1 id="%s.derived-interfaces" role="derived_interfaces">
+<title role="derived_interfaces.title">Known Derived Interfaces</title>
+%s
+</refsect1>
+''' % (section_id, derived)
+
+ functions_synop = re.sub(r'^\n*', '', functions_synop)
+ functions_synop = re.sub(r'\n+$', '\n', functions_synop)
+ if functions_synop != '':
+ functions_synop = '''<refsect1 id="%s.functions" role="functions_proto">
+<title role="functions_proto.title">Functions</title>
+<informaltable pgwide="1" frame="none">
+<tgroup cols="2">
+<colspec colname="functions_return" colwidth="150px"/>
+<colspec colname="functions_name"/>
+<tbody>
+%s
+</tbody>
+</tgroup>
+</informaltable>
+</refsect1>
+''' % (section_id, functions_synop)
+
+ other_synop = re.sub(r'^\n*', '', other_synop)
+ other_synop = re.sub(r'\n+$', '\n', other_synop)
+ if other_synop != '':
+ other_synop = '''<refsect1 id="%s.other" role="other_proto">
+<title role="other_proto.title">Types and Values</title>
+<informaltable role="enum_members_table" pgwide="1" frame="none">
+<tgroup cols="2">
+<colspec colname="name" colwidth="150px"/>
+<colspec colname="description"/>
+<tbody>
+%s
+</tbody>
+</tgroup>
+</informaltable>
+</refsect1>
+''' % (section_id, other_synop)
+
+ file_changed = OutputDBFile(filename, title, section_id,
+ section_includes,
+ functions_synop, other_synop,
+ functions_details, other_details,
+ signals_synop, signals_desc,
+ args_synop, args_desc,
+ hierarchy_str, interfaces,
+ implementations,
+ prerequisites, derived,
+ file_objects)
+ if file_changed:
+ changed = True
+
+ title = ''
+ section_id = ''
+ subsection = ''
+ in_section = 0
+ section_includes = ''
+ functions_synop = ''
+ other_synop = ''
+ functions_details = ''
+ other_details = ''
+ signals_synop = ''
+ signals_desc = ''
+ args_synop = ''
+ child_args_synop = ''
+ style_args_synop = ''
+ args_desc = ''
+ child_args_desc = ''
+ style_args_desc = ''
+ hierarchy_str = ''
+ hierarchy = []
+ interfaces = ''
+ implementations = ''
+ prerequisites = ''
+ derived = ''
+
+ elif m5:
+ symbol = m5.group(1)
+ logging.info(' Symbol: "%s" in subsection: "%s"', symbol, subsection)
+
+ # check for duplicate entries
+ if symbol not in symbol_def_line:
+ declaration = Declarations.get(symbol)
+ # FIXME: with this we'll output empty declaration
+ if declaration is not None:
+ if CheckIsObject(symbol):
+ file_objects.append(symbol)
+
+ # We don't want standard macros/functions of GObjects,
+ # or private declarations.
+ if subsection != "Standard" and subsection != "Private":
+ synop, desc = OutputDeclaration(symbol, declaration)
+ type = DeclarationTypes[symbol]
+
+ if type == 'FUNCTION' or type == 'USER_FUNCTION':
+ functions_synop += synop
+ functions_details += desc
+ elif type == 'MACRO' and re.search(symbol + r'\(', declaration):
+ functions_synop += synop
+ functions_details += desc
+ else:
+ other_synop += synop
+ other_details += desc
+
+ sig_synop, sig_desc = GetSignals(symbol)
+ arg_synop, child_arg_synop, style_arg_synop, arg_desc, child_arg_desc, style_arg_desc = GetArgs(
+ symbol)
+ ifaces = GetInterfaces(symbol)
+ impls = GetImplementations(symbol)
+ prereqs = GetPrerequisites(symbol)
+ der = GetDerived(symbol)
+ hierarchy = GetHierarchy(symbol, hierarchy)
+
+ signals_synop += sig_synop
+ signals_desc += sig_desc
+ args_synop += arg_synop
+ child_args_synop += child_arg_synop
+ style_args_synop += style_arg_synop
+ args_desc += arg_desc
+ child_args_desc += child_arg_desc
+ style_args_desc += style_arg_desc
+ interfaces += ifaces
+ implementations += impls
+ prerequisites += prereqs
+ derived += der
+
+ # Note that the declaration has been output.
+ DeclarationOutput[symbol] = True
+ elif subsection != "Standard" and subsection != "Private":
+ UndeclaredSymbols[symbol] = True
+ common.LogWarning(file, line_number, "No declaration found for %s." % symbol)
+
+ num_symbols += 1
+ symbol_def_line[symbol] = line_number
+
+ if section_id == '':
+ if title == '' and filename == '':
+ common.LogWarning(file, line_number, "Section has no title and no file.")
+
+ # FIXME: one of those would be enough
+ # filename should be an internal detail for gtk-doc
+ if title == '':
+ title = filename
+ elif filename == '':
+ filename = title
+
+ filename = filename.replace(' ', '_')
+
+ section_id = SourceSymbolDocs.get(filename + ":Section_Id")
+ if section_id and section_id.strip() != '':
+ # Remove trailing blanks and use as is
+ section_id = section_id.rstrip()
+ elif CheckIsObject(title):
+ # GObjects use their class name as the ID.
+ section_id = common.CreateValidSGMLID(title)
+ else:
+ section_id = common.CreateValidSGMLID(MODULE + '-' + title)
+
+ SymbolSection[symbol] = title
+ SymbolSectionId[symbol] = section_id
+
+ else:
+ common.LogWarning(file, line_number, "Double symbol entry for %s. "
+ "Previous occurrence on line %d." % (symbol, symbol_def_line[symbol]))
+ INPUT.close()
+
+ OutputMissingDocumentation()
+ OutputUndeclaredSymbols()
+ OutputUnusedSymbols()
+
+ if options.outputallsymbols:
+ OutputAllSymbols()
+
+ if options.outputsymbolswithoutsince:
+ OutputSymbolsWithoutSince()
+
+ for filename in options.expand_content_files.split():
+ file_changed = OutputExtraFile(filename)
+ if file_changed:
+ changed = True
+
+ return (changed, book_top, book_bottom)
+
+
+def DetermineNamespace():
+ """Find common set of characters."""
+ name_space = ''
+ pos = 0
+ ratio = 0.0
+ while True:
+ prefix = {}
+ letter = ''
+ for symbol in iterkeys(IndexEntriesFull):
+ if name_space == '' or name_space.lower() in symbol.lower():
+ if len(symbol) > pos:
+ letter = symbol[pos:pos + 1]
+ # stop prefix scanning
+ if letter == "_":
+ # stop on "_"
+ break
+ # Should we also stop on a uppercase char, if last was lowercase
+ # GtkWidget, if we have the 'W' and had the 't' before
+ # or should we count upper and lowercase, and stop one 2nd uppercase, if we already had a lowercase
+ # GtkWidget, the 'W' would be the 2nd uppercase and with 't','k' we had lowercase chars before
+ # need to recound each time as this is per symbol
+ ul = letter.upper()
+ if ul in prefix:
+ prefix[ul] += 1
+ else:
+ prefix[ul] = 1
+
+ if letter != '' and letter != "_":
+ maxletter = ''
+ maxsymbols = 0
+ for letter in iterkeys(prefix):
+ logging.debug("ns prefix: %s: %s", letter, prefix[letter])
+ if prefix[letter] > maxsymbols:
+ maxletter = letter
+ maxsymbols = prefix[letter]
+
+ ratio = float(len(IndexEntriesFull)) / prefix[maxletter]
+ logging.debug('most symbols start with %s, that is %f', maxletter, (100 * ratio))
+ if ratio > 0.9:
+ # do another round
+ name_space += maxletter
+
+ pos += 1
+
+ else:
+ ratio = 0.0
+
+ if ratio < 0.9:
+ break
+ return name_space
+
+
+def OutputIndex(basename, apiindex):
+ """Writes an index that can be included into the main-document into an <index> tag.
+
+ Args:
+ basename (str): name of the index file without extension
+ apiindex (dict): the index data
+ """
+ old_index = os.path.join(DB_OUTPUT_DIR, basename + '.xml')
+ new_index = os.path.join(DB_OUTPUT_DIR, basename + '.new')
+ lastletter = " "
+ divopen = 0
+ symbol = None
+ short_symbol = None
+
+ OUTPUT = open(new_index, 'w')
+
+ OUTPUT.write(MakeDocHeader("indexdiv") + "\n<indexdiv id=\"%s\">\n" % basename)
+
+ logging.info("generate %s index (%d entries) with namespace %s", basename, len(apiindex), NAME_SPACE)
+
+ # do a case insensitive sort while chopping off the prefix
+ mapped_keys = [
+ {
+ 'original': x,
+ 'short': re.sub(r'^' + NAME_SPACE + r'\_?(.*)', r'\1', x.upper(), flags=re.I),
+ } for x in iterkeys(apiindex)]
+ sorted_keys = sorted(mapped_keys, key=lambda d: (d['short'], d['original']))
+
+ for key in sorted_keys:
+ symbol = key['original']
+ short = key['short']
+ if short != '':
+ short_symbol = short
+ else:
+ short_symbol = symbol
+
+ # generate a short symbol description
+ symbol_desc = ''
+ symbol_section = ''
+ symbol_section_id = ''
+ symbol_type = ''
+ if symbol in DeclarationTypes:
+ symbol_type = DeclarationTypes[symbol].lower()
+
+ if symbol_type == '':
+ logging.info("trying symbol %s", symbol)
+ m1 = re.search(r'(.*)::(.*)', symbol)
+ m2 = re.search(r'(.*):(.*)', symbol)
+ if m1:
+ oname = m1.group(1)
+ osym = m1.group(2)
+ logging.info(" trying object signal %s:%s in %d signals", oname, osym, len(SignalNames))
+ for name in SignalNames:
+ logging.info(" " + name)
+ if name == osym:
+ symbol_type = "object signal"
+ if oname in SymbolSection:
+ symbol_section = SymbolSection[oname]
+ symbol_section_id = SymbolSectionId[oname]
+ break
+ elif m2:
+ oname = m2.group(1)
+ osym = m2.group(2)
+ logging.info(" trying object property %s::%s in %d properties", oname, osym, len(ArgNames))
+ for name in ArgNames:
+ logging.info(" " + name)
+ if name == osym:
+ symbol_type = "object property"
+ if oname in SymbolSection:
+ symbol_section = SymbolSection[oname]
+ symbol_section_id = SymbolSectionId[oname]
+ break
+ else:
+ if symbol in SymbolSection:
+ symbol_section = SymbolSection[symbol]
+ symbol_section_id = SymbolSectionId[symbol]
+
+ if symbol_type != '':
+ symbol_desc = ", " + symbol_type
+ if symbol_section != '':
+ symbol_desc += " in <link linkend=\"%s\">%s</link>" % (symbol_section_id, symbol_section)
+ # symbol_desc +=" in " + ExpandAbbreviations(symbol, "#symbol_section")
+
+ curletter = short_symbol[0].upper()
+ ixid = apiindex[symbol]
+
+ logging.info(" add symbol %s with %s to index in section '%s' (derived from %s)",
+ symbol, ixid, curletter, short_symbol)
+
+ if curletter != lastletter:
+ lastletter = curletter
+
+ if divopen:
+ OUTPUT.write("</indexdiv>\n")
+
+ OUTPUT.write("<indexdiv><title>%s</title>\n" % curletter)
+ divopen = True
+
+ OUTPUT.write('<indexentry><primaryie linkends="%s"><link linkend="%s">%s</link>%s</primaryie></indexentry>\n' %
+ (ixid, ixid, symbol, symbol_desc))
+
+ if divopen:
+ OUTPUT.write("</indexdiv>\n")
+
+ OUTPUT.write("</indexdiv>\n")
+ OUTPUT.close()
+
+ common.UpdateFileIfChanged(old_index, new_index, 0)
+
+
+def OutputSinceIndexes():
+ """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}
+ OutputIndex("api-index-" + version, index)
+
+
+def OutputAnnotationGlossary():
+ """Writes a glossary of the used annotation terms.
+
+ The glossary file can be included into the main document.
+ """
+ # if there are no annotations used return
+ if not AnnotationsUsed:
+ return
+
+ old_glossary = os.path.join(DB_OUTPUT_DIR, "annotation-glossary.xml")
+ new_glossary = os.path.join(DB_OUTPUT_DIR, "annotation-glossary.new")
+ lastletter = " "
+ divopen = False
+
+ # add acronyms that are referenced from acronym text
+ rerun = True
+ while rerun:
+ rerun = False
+ for annotation in AnnotationsUsed:
+ if annotation not in AnnotationDefinition:
+ continue
+ m = re.search(r'<acronym>([\w ]+)<\/acronym>', AnnotationDefinition[annotation])
+ if m and m.group(1) not in AnnotationsUsed:
+ AnnotationsUsed[m.group(1)] = 1
+ rerun = True
+ break
+
+ OUTPUT = open(new_glossary, 'w')
+
+ OUTPUT.write('''%s
+<glossary id="annotation-glossary">
+ <title>Annotation Glossary</title>
+''' % MakeDocHeader("glossary"))
+
+ for annotation in sorted(iterkeys(AnnotationsUsed), key=str.lower):
+ if annotation in AnnotationDefinition:
+ definition = AnnotationDefinition[annotation]
+ curletter = annotation[0].upper()
+
+ if curletter != lastletter:
+ lastletter = curletter
+
+ if divopen:
+ OUTPUT.write("</glossdiv>\n")
+
+ OUTPUT.write("<glossdiv><title>%s</title>\n" % curletter)
+ divopen = True
+
+ OUTPUT.write(''' <glossentry>
+ <glossterm><anchor id="annotation-glossterm-%s"/>%s</glossterm>
+ <glossdef>
+ <para>%s</para>
+ </glossdef>
+ </glossentry>
+''' % (annotation, annotation, definition))
+
+ if divopen:
+ OUTPUT.write("</glossdiv>\n")
+
+ OUTPUT.write("</glossary>\n")
+ OUTPUT.close()
+
+ common.UpdateFileIfChanged(old_glossary, new_glossary, 0)
+
+
+def ReadKnownSymbols(file):
+ """Collect the names of non-private symbols from the $MODULE-sections.txt file.
+
+ Args:
+ file: the $MODULE-sections.txt file
+ """
+
+ subsection = ''
+
+ logging.info("Reading: %s", file)
+ INPUT = open(file)
+ for line in INPUT:
+ if line.startswith('#'):
+ continue
+
+ if line.startswith('<SECTION>'):
+ subsection = ''
+ continue
+
+ m = re.search(r'^<SUBSECTION\s*(.*)>', line, flags=re.I)
+ if m:
+ subsection = m.group(1)
+ continue
+
+ if line.startswith('<SUBSECTION>'):
+ continue
+
+ if re.search(r'^<TITLE>(.*)<\/TITLE>', line):
+ continue
+
+ m = re.search(r'^<FILE>(.*)<\/FILE>', line)
+ if m:
+ KnownSymbols[m.group(1) + ":Long_Description"] = 1
+ KnownSymbols[m.group(1) + ":Short_Description"] = 1
+ continue
+
+ m = re.search(r'^<INCLUDE>(.*)<\/INCLUDE>', line)
+ if m:
+ continue
+
+ m = re.search(r'^<\/SECTION>', line)
+ if m:
+ continue
+
+ m = re.search(r'^(\S+)', line)
+ if m:
+ symbol = m.group(1)
+ if subsection != "Standard" and subsection != "Private":
+ KnownSymbols[symbol] = 1
+ else:
+ KnownSymbols[symbol] = 0
+ INPUT.close()
+
+
+def OutputDeclaration(symbol, declaration):
+ """Returns the formatted documentation block for a symbol.
+
+ Args:
+ symbol (str): the name of the function/macro/...
+ declaration (str): the declaration of the function/macro.
+
+ Returns:
+ str: the formatted documentation
+ """
+
+ dtype = DeclarationTypes[symbol]
+ if dtype == 'MACRO':
+ return OutputMacro(symbol, declaration)
+ elif dtype == 'TYPEDEF':
+ return OutputTypedef(symbol, declaration)
+ elif dtype == 'STRUCT':
+ return OutputStruct(symbol, declaration)
+ elif dtype == 'ENUM':
+ return OutputEnum(symbol, declaration)
+ elif dtype == 'UNION':
+ return OutputUnion(symbol, declaration)
+ elif dtype == 'VARIABLE':
+ return OutputVariable(symbol, declaration)
+ elif dtype == 'FUNCTION':
+ return OutputFunction(symbol, declaration, dtype)
+ elif dtype == 'USER_FUNCTION':
+ return OutputFunction(symbol, declaration, dtype)
+ else:
+ sys.exit("Unknown symbol type " + dtype)
+
+
+def OutputSymbolTraits(symbol):
+ """Returns the Since and StabilityLevel paragraphs for a symbol.
+
+ Args:
+ symbol (str): the name to describe
+
+ Returns:
+ str: paragraph or empty string
+ """
+
+ desc = ''
+
+ if symbol in Since:
+ link_id = "api-index-" + Since[symbol]
+ desc += "<para role=\"since\">Since: <link linkend=\"%s\">%s</link></para>" % (link_id, Since[symbol])
+
+ if symbol in StabilityLevel:
+ stability = StabilityLevel[symbol]
+ AnnotationsUsed[stability] = True
+ desc += "<para role=\"stability\">Stability Level: <acronym>%s</acronym></para>" % stability
+ return desc
+
+
+def uri_escape(text):
+ if text is None:
+ return None
+
+ # Build a char to hex map
+ escapes = {chr(i): ("%%%02X" % i) for i in range(256)}
+
+ # Default unsafe characters. RFC 2732 ^(uric - reserved)
+ def do_escape(char):
+ return escapes[char]
+ return re.sub(r"([^A-Za-z0-9\-_.!~*'()]", do_escape, text)
+
+
+def OutputSymbolExtraLinks(symbol):
+ """Returns extralinks for the symbol (if enabled).
+
+ Args:
+ symbol (str): the name to describe
+
+ Returns:
+ str: paragraph or empty string
+ """
+ desc = ''
+
+ if False: # NEW FEATURE: needs configurability
+ sstr = uri_escape(symbol)
+ mstr = uri_escape(MODULE)
+ desc += '''<ulink role="extralinks" url="http://www.google.com/codesearch?q=%s">code search</ulink>
+<ulink role="extralinks" url="http://library.gnome.org/edit?module=%s&symbol=%s">edit documentation</ulink>
+''' % (sstr, mstr, sstr)
+
+ return desc
+
+
+def OutputSectionExtraLinks(symbol, docsymbol):
+ desc = ''
+
+ if False: # NEW FEATURE: needs configurability
+ sstr = uri_escape(symbol)
+ mstr = uri_escape(MODULE)
+ dsstr = uri_escape(docsymbol)
+ desc += '''<ulink role="extralinks" url="http://www.google.com/codesearch?q=%s">code search</ulink>
+<ulink role="extralinks" url="http://library.gnome.org/edit?module=%s&symbol=%s">edit documentation</ulink>
+''' % (sstr, mstr, dsstr)
+ return desc
+
+
+def OutputMacro(symbol, declaration):
+ """Returns the synopsis and detailed description of a macro.
+
+ Args:
+ symbol (str): the macro name.
+ declaration (str): the declaration of the macro.
+
+ Returns:
+ str: the formated docs
+ """
+ sid = common.CreateValidSGMLID(symbol)
+ condition = MakeConditionDescription(symbol)
+ synop = "<row><entry role=\"define_keyword\">#define</entry><entry role=\"function_name\"><link linkend=\"%s\">%s</link>" % (
+ sid, symbol)
+
+ fields = common.ParseMacroDeclaration(declaration, CreateValidSGML)
+ title = symbol
+ if len(fields) > 0:
+ title += '()'
+
+ desc = '<refsect2 id="%s" role="macro"%s>\n<title>%s</title>\n' % (sid, condition, title)
+ desc += MakeIndexterms(symbol, sid)
+ desc += "\n"
+ desc += OutputSymbolExtraLinks(symbol)
+
+ if len(fields) > 0:
+ synop += "<phrase role=\"c_punctuation\">()</phrase>"
+
+ synop += "</entry></row>\n"
+
+ # Don't output the macro definition if is is a conditional macro or it
+ # looks like a function, i.e. starts with "g_" or "_?gnome_", or it is
+ # longer than 2 lines, otherwise we get lots of complicated macros like
+ # g_assert.
+ if symbol not in DeclarationConditional and not symbol.startswith('g_') \
+ and not re.search(r'^_?gnome_', symbol) and declaration.count('\n') < 2:
+ decl_out = CreateValidSGML(declaration)
+ desc += "<programlisting language=\"C\">%s</programlisting>\n" % decl_out
+ else:
+ desc += "<programlisting language=\"C\">" + "#define".ljust(RETURN_TYPE_FIELD_WIDTH) + symbol
+ m = re.search(r'^\s*#\s*define\s+\w+(\([^\)]*\))', declaration)
+ if m:
+ args = m.group(1)
+ pad = ' ' * (RETURN_TYPE_FIELD_WIDTH - len("#define "))
+ # Align each line so that if should all line up OK.
+ args = args.replace('\n', '\n' + pad)
+ desc += CreateValidSGML(args)
+
+ desc += "</programlisting>\n"
+
+ desc += MakeDeprecationNote(symbol)
+
+ parameters = OutputParamDescriptions("MACRO", symbol, fields)
+
+ if symbol in SymbolDocs:
+ symbol_docs = ConvertMarkDown(symbol, SymbolDocs[symbol])
+ desc += symbol_docs
+
+ desc += parameters
+ desc += OutputSymbolTraits(symbol)
+ desc += "</refsect2>\n"
+ return (synop, desc)
+
+
+def OutputTypedef(symbol, declaration):
+ """Returns the synopsis and detailed description of a typedef.
+
+ Args:
+ symbol (str): the typedef.
+ declaration (str): the declaration of the typedef,
+ e.g. 'typedef unsigned int guint;'
+
+ Returns:
+ str: the formated docs
+ """
+ sid = common.CreateValidSGMLID(symbol)
+ condition = MakeConditionDescription(symbol)
+ desc = "<refsect2 id=\"%s\" role=\"typedef\"%s>\n<title>%s</title>\n" % (sid, condition, symbol)
+ synop = "<row><entry role=\"typedef_keyword\">typedef</entry><entry role=\"function_name\"><link linkend=\"%s\">%s</link></entry></row>\n" % (
+ sid, symbol)
+
+ desc += MakeIndexterms(symbol, sid)
+ desc += "\n"
+ desc += OutputSymbolExtraLinks(symbol)
+
+ if symbol in DeclarationConditional:
+ decl_out = CreateValidSGML(declaration)
+ desc += "<programlisting language=\"C\">%s</programlisting>\n" % decl_out
+
+ desc += MakeDeprecationNote(symbol)
+
+ if symbol in SymbolDocs:
+ desc += ConvertMarkDown(symbol, SymbolDocs[symbol])
+
+ desc += OutputSymbolTraits(symbol)
+ desc += "</refsect2>\n"
+ return (synop, desc)
+
+
+def OutputStruct(symbol, declaration):
+ """Returns the synopsis and detailed description of a struct.
+
+ We check if it is a object struct, and if so we only output parts of it that
+ are noted as public fields. We also use a different IDs for object structs,
+ since the original ID is used for the entire RefEntry.
+
+ Args:
+ symbol (str): the struct.
+ declaration (str): the declaration of the struct.
+
+ Returns:
+ str: the formated docs
+ """
+ is_gtype = False
+ default_to_public = True
+ if CheckIsObject(symbol):
+ logging.info("Found struct gtype: %s", symbol)
+ is_gtype = True
+ default_to_public = ObjectRoots[symbol] == 'GBoxed'
+
+ sid = None
+ condition = None
+ if is_gtype:
+ sid = common.CreateValidSGMLID(symbol + "_struct")
+ condition = MakeConditionDescription(symbol + "_struct")
+ else:
+ sid = common.CreateValidSGMLID(symbol)
+ condition = MakeConditionDescription(symbol)
+
+ # Determine if it is a simple struct or it also has a typedef.
+ has_typedef = False
+ if symbol in StructHasTypedef or re.search(r'^\s*typedef\s+', declaration):
+ has_typedef = True
+
+ type_output = None
+ desc = None
+ if has_typedef:
+ # For structs with typedefs we just output the struct name.
+ type_output = ''
+ desc = "<refsect2 id=\"%s\" role=\"struct\"%s>\n<title>%s</title>\n" % (sid, condition, symbol)
+ else:
+ type_output = "struct"
+ desc = "<refsect2 id=\"%s\" role=\"struct\"%s>\n<title>struct %s</title>\n" % (sid, condition, symbol)
+
+ synop = "<row><entry role=\"datatype_keyword\">%s</entry><entry role=\"function_name\"><link linkend=\"%s\">%s</link></entry></row>\n" % (
+ type_output, sid, symbol)
+
+ desc += MakeIndexterms(symbol, sid)
+ desc += "\n"
+ desc += OutputSymbolExtraLinks(symbol)
+
+ # Form a pretty-printed, private-data-removed form of the declaration
+
+ decl_out = ''
+ if re.search(r'^\s*$', declaration):
+ logging.info("Found opaque struct: %s", symbol)
+ decl_out = "typedef struct _%s %s;" % (symbol, symbol)
+ elif re.search(r'^\s*struct\s+\w+\s*;\s*$', declaration):
+ logging.info("Found opaque struct: %s", symbol)
+ decl_out = "struct %s;" % symbol
+ else:
+ m = re.search(
+ r'^\s*(typedef\s+)?struct\s*\w*\s*(?:\/\*.*\*\/)?\s*{(.*)}\s*\w*\s*;\s*$', declaration, flags=re.S)
+ if m:
+ struct_contents = m.group(2)
+
+ public = default_to_public
+ new_declaration = ''
+
+ for decl_line in struct_contents.splitlines():
+ logging.info("Struct line: %s", decl_line)
+ m2 = re.search(r'/\*\s*<\s*public\s*>\s*\*/', decl_line)
+ m3 = re.search(r'/\*\s*<\s*(private|protected)\s*>\s*\*/', decl_line)
+ if m2:
+ public = True
+ elif m3:
+ public = False
+ elif public:
+ new_declaration += decl_line + "\n"
+
+ if new_declaration:
+ # Strip any blank lines off the ends.
+ new_declaration = re.sub(r'^\s*\n', '', new_declaration)
+ new_declaration = re.sub(r'\n\s*$', r'\n', new_declaration)
+
+ if has_typedef:
+ decl_out = "typedef struct {\n%s} %s;\n" % (new_declaration, symbol)
+ else:
+ decl_out = "struct %s {\n%s};\n" % (symbol, new_declaration)
+
+ else:
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Couldn't parse struct:\n%s" % declaration)
+
+ # If we couldn't parse the struct or it was all private, output an
+ # empty struct declaration.
+ if decl_out == '':
+ if has_typedef:
+ decl_out = "typedef struct _%s %s;" % (symbol, symbol)
+ else:
+ decl_out = "struct %s;" % symbol
+
+ decl_out = CreateValidSGML(decl_out)
+ desc += "<programlisting language=\"C\">%s</programlisting>\n" % decl_out
+
+ desc += MakeDeprecationNote(symbol)
+
+ if symbol in SymbolDocs:
+ desc += ConvertMarkDown(symbol, SymbolDocs[symbol])
+
+ # Create a table of fields and descriptions
+
+ # FIXME: Inserting  's into the produced type declarations here would
+ # improve the output in most situations ... except for function
+ # members of structs!
+ def pfunc(*args):
+ return '<structfield id="%s">%s</structfield>' % (common.CreateValidSGMLID(sid + '.' + args[0]), args[0])
+ fields = common.ParseStructDeclaration(declaration, not default_to_public, 0, MakeXRef, pfunc)
+ params = SymbolParams.get(symbol)
+
+ # If no parameters are filled in, we don't generate the description
+ # table, for backwards compatibility.
+ found = False
+ if params:
+ found = next((True for p in params.values() if p.strip() != ''), False)
+
+ if found:
+ field_descrs = params
+ missing_parameters = ''
+ unused_parameters = ''
+ sid = common.CreateValidSGMLID(symbol + ".members")
+
+ desc += '''<refsect3 id="%s" role="struct_members">\n<title>Members</title>
+<informaltable role="struct_members_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="struct_members_name" colwidth="300px"/>
+<colspec colname="struct_members_description"/>
+<colspec colname="struct_members_annotations" colwidth="200px"/>
+<tbody>
+''' % sid
+
+ for field_name, text in iteritems(fields):
+ param_annotations = ''
+
+ desc += "<row role=\"member\"><entry role=\"struct_member_name\"><para>%s</para></entry>\n" % text
+ if field_name in field_descrs:
+ (field_descr, param_annotations) = ExpandAnnotation(symbol, field_descrs[field_name])
+ field_descr = ConvertMarkDown(symbol, field_descr)
+ # trim
+ field_descr = re.sub(r'^(\s|\n)+', '', field_descr, flags=re.M | re.S)
+ field_descr = re.sub(r'(\s|\n)+$', '', field_descr, flags=re.M | re.S)
+ desc += "<entry role=\"struct_member_description\">%s</entry>\n<entry role=\"struct_member_annotations\">%s</entry>\n" % (
+ field_descr, param_annotations)
+ del field_descrs[field_name]
+ else:
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Field description for %s::%s is missing in source code comment block." % (symbol, field_name))
+ if missing_parameters != '':
+ missing_parameters += ", " + field_name
+ else:
+ missing_parameters = field_name
+
+ desc += "<entry /><entry />\n"
+
+ desc += "</row>\n"
+
+ desc += "</tbody></tgroup></informaltable>\n</refsect3>\n"
+ for field_name in field_descrs:
+ # Documenting those standard fields is not required anymore, but
+ # we don't want to warn if they are documented anyway.
+ m = re.search(r'(g_iface|parent_instance|parent_class)', field_name)
+ if m:
+ continue
+
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Field description for %s::%s is not used from source code comment block." % (symbol, field_name))
+ if unused_parameters != '':
+ unused_parameters += ", " + field_name
+ else:
+ unused_parameters = field_name
+
+ # remember missing/unused parameters (needed in tmpl-free build)
+ if missing_parameters != '' and (symbol not in AllIncompleteSymbols):
+ AllIncompleteSymbols[symbol] = missing_parameters
+
+ if unused_parameters != '' and (symbol not in AllUnusedSymbols):
+ AllUnusedSymbols[symbol] = unused_parameters
+ else:
+ if fields:
+ if symbol not in AllIncompleteSymbols:
+ AllIncompleteSymbols[symbol] = "<items>"
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Field descriptions for struct %s are missing in source code comment block." % symbol)
+ logging.info("Remaining structs fields: " + ':'.join(fields) + "\n")
+
+ desc += OutputSymbolTraits(symbol)
+ desc += "</refsect2>\n"
+ return (synop, desc)
+
+
+def OutputUnion(symbol, declaration):
+ """Returns the synopsis and detailed description of a union.
+
+ Args:
+ symbol (str): the union.
+ declaration (str): the declaration of the union.
+
+ Returns:
+ str: the formated docs
+ """
+ is_gtype = False
+ if CheckIsObject(symbol):
+ logging.info("Found union gtype: %s", symbol)
+ is_gtype = True
+
+ sid = None
+ condition = None
+ if is_gtype:
+ sid = common.CreateValidSGMLID(symbol + "_union")
+ condition = MakeConditionDescription(symbol + "_union")
+ else:
+ sid = common.CreateValidSGMLID(symbol)
+ condition = MakeConditionDescription(symbol)
+
+ # Determine if it is a simple struct or it also has a typedef.
+ has_typedef = False
+ if symbol in StructHasTypedef or re.search(r'^\s*typedef\s+', declaration):
+ has_typedef = True
+
+ type_output = None
+ desc = None
+ if has_typedef:
+ # For unions with typedefs we just output the union name.
+ type_output = ''
+ desc = "<refsect2 id=\"%s\" role=\"union\"%s>\n<title>%s</title>\n" % (sid, condition, symbol)
+ else:
+ type_output = "union"
+ desc = "<refsect2 id=\"%s\" role=\"union\"%s>\n<title>union %s</title>\n" % (sid, condition, symbol)
+
+ synop = "<row><entry role=\"datatype_keyword\">%s</entry><entry role=\"function_name\"><link linkend=\"%s\">%s</link></entry></row>\n" % (
+ type_output, sid, symbol)
+
+ desc += MakeIndexterms(symbol, sid)
+ desc += "\n"
+ desc += OutputSymbolExtraLinks(symbol)
+ desc += MakeDeprecationNote(symbol)
+
+ if symbol in SymbolDocs:
+ desc += ConvertMarkDown(symbol, SymbolDocs[symbol])
+
+ # Create a table of fields and descriptions
+
+ # FIXME: Inserting  's into the produced type declarations here would
+ # improve the output in most situations ... except for function
+ # members of structs!
+ def pfunc(*args):
+ return '<structfield id="%s">%s</structfield>' % (common.CreateValidSGMLID(sid + '.' + args[0]), args[0])
+ fields = common.ParseStructDeclaration(declaration, 0, 0, MakeXRef, pfunc)
+ params = SymbolParams.get(symbol)
+
+ # If no parameters are filled in, we don't generate the description
+ # table, for backwards compatibility
+ found = False
+ if params:
+ found = next((True for p in params.values() if p.strip() != ''), False)
+
+ logging.debug('Union %s has %d entries, found=%d, has_typedef=%d', symbol, len(fields), found, has_typedef)
+
+ if found:
+ field_descrs = params
+ missing_parameters = ''
+ unused_parameters = ''
+ sid = common.CreateValidSGMLID('%s.members' % symbol)
+
+ desc += '''<refsect3 id="%s" role="union_members">\n<title>Members</title>
+<informaltable role="union_members_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="union_members_name" colwidth="300px"/>
+<colspec colname="union_members_description"/>
+<colspec colname="union_members_annotations" colwidth="200px"/>
+<tbody>
+''' % sid
+
+ for field_name, text in iteritems(fields):
+ param_annotations = ''
+
+ desc += "<row><entry role=\"union_member_name\"><para>%s</para></entry>\n" % text
+ if field_name in field_descrs:
+ (field_descr, param_annotations) = ExpandAnnotation(symbol, field_descrs[field_name])
+ field_descr = ConvertMarkDown(symbol, field_descr)
+
+ # trim
+ field_descr = re.sub(r'^(\s|\n)+', '', field_descr, flags=re.M | re.S)
+ field_descr = re.sub(r'(\s|\n)+$', '', field_descr, flags=re.M | re.S)
+ desc += "<entry role=\"union_member_description\">%s</entry>\n<entry role=\"union_member_annotations\">%s</entry>\n" % (
+ field_descr, param_annotations)
+ del field_descrs[field_name]
+ else:
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Field description for %s::%s is missing in source code comment block." % (symbol, field_name))
+ if missing_parameters != '':
+ missing_parameters += ", " + field_name
+ else:
+ missing_parameters = field_name
+
+ desc += "<entry /><entry />\n"
+
+ desc += "</row>\n"
+
+ desc += "</tbody></tgroup></informaltable>\n</refsect3>"
+ for field_name in field_descrs:
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Field description for %s::%s is not used from source code comment block." % (symbol, field_name))
+ if unused_parameters != '':
+ unused_parameters += ", " + field_name
+ else:
+ unused_parameters = field_name
+
+ # remember missing/unused parameters (needed in tmpl-free build)
+ if missing_parameters != '' and (symbol not in AllIncompleteSymbols):
+ AllIncompleteSymbols[symbol] = missing_parameters
+
+ if unused_parameters != '' and (symbol not in AllUnusedSymbols):
+ AllUnusedSymbols[symbol] = unused_parameters
+ else:
+ if len(fields) > 0:
+ if symbol not in AllIncompleteSymbols:
+ AllIncompleteSymbols[symbol] = "<items>"
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Field descriptions for union %s are missing in source code comment block." % symbol)
+ logging.info("Remaining union fields: " + ':'.join(fields) + "\n")
+
+ desc += OutputSymbolTraits(symbol)
+ desc += "</refsect2>\n"
+ return (synop, desc)
+
+
+def OutputEnum(symbol, declaration):
+ """Returns the synopsis and detailed description of a enum.
+
+ Args:
+ symbol (str): the enum.
+ declaration (str): the declaration of the enum.
+
+ Returns:
+ str: the formated docs
+ """
+ is_gtype = False
+ if CheckIsObject(symbol):
+ logging.info("Found enum gtype: %s", symbol)
+ is_gtype = True
+
+ sid = None
+ condition = None
+ if is_gtype:
+ sid = common.CreateValidSGMLID(symbol + "_enum")
+ condition = MakeConditionDescription(symbol + "_enum")
+ else:
+ sid = common.CreateValidSGMLID(symbol)
+ condition = MakeConditionDescription(symbol)
+
+ synop = "<row><entry role=\"datatype_keyword\">enum</entry><entry role=\"function_name\"><link linkend=\"%s\">%s</link></entry></row>\n" % (
+ sid, symbol)
+ desc = "<refsect2 id=\"%s\" role=\"enum\"%s>\n<title>enum %s</title>\n" % (sid, condition, symbol)
+
+ desc += MakeIndexterms(symbol, sid)
+ desc += "\n"
+ desc += OutputSymbolExtraLinks(symbol)
+ desc += MakeDeprecationNote(symbol)
+
+ if symbol in SymbolDocs:
+ desc += ConvertMarkDown(symbol, SymbolDocs[symbol])
+
+ # Create a table of fields and descriptions
+
+ fields = common.ParseEnumDeclaration(declaration)
+ params = SymbolParams.get(symbol)
+
+ # If nothing at all is documented log a single summary warning at the end.
+ # Otherwise, warn about each undocumented item.
+
+ found = False
+ if params:
+ found = next((True for p in params.values() if p.strip() != ''), False)
+ field_descrs = params
+ else:
+ field_descrs = {}
+
+ missing_parameters = ''
+ unused_parameters = ''
+
+ sid = common.CreateValidSGMLID("%s.members" % symbol)
+ desc += '''<refsect3 id="%s" role="enum_members">\n<title>Members</title>
+<informaltable role="enum_members_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="enum_members_name" colwidth="300px"/>
+<colspec colname="enum_members_description"/>
+<colspec colname="enum_members_annotations" colwidth="200px"/>
+<tbody>
+''' % sid
+
+ for field_name in fields:
+ field_descr = field_descrs.get(field_name)
+ param_annotations = ''
+
+ sid = common.CreateValidSGMLID(field_name)
+ condition = MakeConditionDescription(field_name)
+ desc += "<row role=\"constant\"><entry role=\"enum_member_name\"><para id=\"%s\">%s</para></entry>\n" % (
+ sid, field_name)
+ if field_descr:
+ field_descr, param_annotations = ExpandAnnotation(symbol, field_descr)
+ field_descr = ConvertMarkDown(symbol, field_descr)
+ desc += "<entry role=\"enum_member_description\">%s</entry>\n<entry role=\"enum_member_annotations\">%s</entry>\n" % (
+ field_descr, param_annotations)
+ del field_descrs[field_name]
+ else:
+ if found:
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Value description for %s::%s is missing in source code comment block." % (symbol, field_name))
+ if missing_parameters != '':
+ missing_parameters += ", " + field_name
+ else:
+ missing_parameters = field_name
+ desc += "<entry /><entry />\n"
+ desc += "</row>\n"
+
+ desc += "</tbody></tgroup></informaltable>\n</refsect3>"
+ for field_name in field_descrs:
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Value description for %s::%s is not used from source code comment block." % (symbol, field_name))
+ if unused_parameters != '':
+ unused_parameters += ", " + field_name
+ else:
+ unused_parameters = field_name
+
+ # remember missing/unused parameters (needed in tmpl-free build)
+ if missing_parameters != '' and (symbol not in AllIncompleteSymbols):
+ AllIncompleteSymbols[symbol] = missing_parameters
+
+ if unused_parameters != '' and (symbol not in AllUnusedSymbols):
+ AllUnusedSymbols[symbol] = unused_parameters
+
+ if not found:
+ if len(fields) > 0:
+ if symbol not in AllIncompleteSymbols:
+ AllIncompleteSymbols[symbol] = "<items>"
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Value descriptions for %s are missing in source code comment block." % symbol)
+
+ desc += OutputSymbolTraits(symbol)
+ desc += "</refsect2>\n"
+ return (synop, desc)
+
+
+def OutputVariable(symbol, declaration):
+ """Returns the synopsis and detailed description of a variable.
+
+ Args:
+ symbol (str): the extern'ed variable.
+ declaration (str): the declaration of the variable.
+
+ Returns:
+ str: the formated docs
+ """
+ sid = common.CreateValidSGMLID(symbol)
+ condition = MakeConditionDescription(symbol)
+
+ logging.info("ouputing variable: '%s' '%s'", symbol, declaration)
+
+ type_output = None
+ m1 = re.search(
+ r'^\s*extern\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*;', declaration)
+ m2 = re.search(
+ r'\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*=', declaration)
+ if m1:
+ mod1 = m1.group(1) or ''
+ ptr = m1.group(3) or ''
+ space = m1.group(4) or ''
+ mod2 = m1.group(5) or ''
+ type_output = "extern %s%s%s%s" % (mod1, ptr, space, mod2)
+ elif m2:
+ mod1 = m2.group(1) or ''
+ ptr = m2.group(3) or ''
+ space = m2.group(4) or ''
+ mod2 = m2.group(5) or ''
+ type_output = '%s%s%s%s' % (mod1, ptr, space, mod2)
+ else:
+ type_output = "extern"
+
+ synop = "<row><entry role=\"variable_type\">%s</entry><entry role=\"function_name\"><link linkend=\"%s\">%s</link></entry></row>\n" % (
+ type_output, sid, symbol)
+
+ desc = "<refsect2 id=\"%s\" role=\"variable\"%s>\n<title>%s</title>\n" % (sid, condition, symbol)
+
+ desc += MakeIndexterms(symbol, sid)
+ desc += "\n"
+ desc += OutputSymbolExtraLinks(symbol)
+
+ decl_out = CreateValidSGML(declaration)
+ desc += "<programlisting language=\"C\">%s</programlisting>\n" % decl_out
+
+ desc += MakeDeprecationNote(symbol)
+
+ if symbol in SymbolDocs:
+ desc += ConvertMarkDown(symbol, SymbolDocs[symbol])
+
+ if symbol in SymbolAnnotations:
+ param_desc = SymbolAnnotations[symbol]
+ param_annotations = ''
+ (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc)
+ if param_annotations != '':
+ desc += "\n<para>%s</para>" % param_annotations
+
+ desc += OutputSymbolTraits(symbol)
+ desc += "</refsect2>\n"
+ return (synop, desc)
+
+
+def OutputFunction(symbol, declaration, symbol_type):
+ """Returns the synopsis and detailed description of a function.
+
+ Args:
+ symbol (str): the function.
+ declaration (str): the declaration of the function.
+
+ Returns:
+ str: the formated docs
+ """
+ sid = common.CreateValidSGMLID(symbol)
+ condition = MakeConditionDescription(symbol)
+
+ # Take out the return type
+ # $1 $2 $3
+ regex = r'<RETURNS>\s*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|enum\s+)*)(\w+)(\s*\**\s*(?:const|G_CONST_RETURN)?\s*\**\s*(?:restrict)?\s*)<\/RETURNS>\n'
+ m = re.search(regex, declaration)
+ declaration = re.sub(regex, '', declaration)
+ type_modifier = m.group(1) or ''
+ type = m.group(2)
+ pointer = m.group(3)
+ pointer = pointer.rstrip()
+ xref = MakeXRef(type, tagify(type, "returnvalue"))
+ start = ''
+ # if (symbol_type == 'USER_FUNCTION')
+ # start = "typedef "
+ #
+
+ # We output const rather than G_CONST_RETURN.
+ type_modifier = re.sub(r'G_CONST_RETURN', 'const', type_modifier)
+ pointer = re.sub(r'G_CONST_RETURN', 'const', pointer)
+ pointer = re.sub(r'^\s+', ' ', pointer)
+
+ ret_type_output = "%s%s%s%s\n" % (start, type_modifier, xref, pointer)
+
+ indent_len = len(symbol) + 2
+ char1 = char2 = char3 = ''
+ if symbol_type == 'USER_FUNCTION':
+ indent_len += 3
+ char1 = "<phrase role=\"c_punctuation\">(</phrase>"
+ char2 = "*"
+ char3 = "<phrase role=\"c_punctuation\">)</phrase>"
+
+ symbol_output = "%s<link linkend=\"%s\">%s%s</link>%s" % (char1, sid, char2, symbol, char3)
+ if indent_len < MAX_SYMBOL_FIELD_WIDTH:
+ symbol_desc_output = "%s%s%s%s " % (char1, char2, symbol, char3)
+ else:
+ indent_len = MAX_SYMBOL_FIELD_WIDTH - 8
+ symbol_desc_output = ('%s%s%s%s\n' % (char1, char2, symbol, char3)) + (' ' * (indent_len - 1))
+
+ synop = "<row><entry role=\"function_type\">%s</entry><entry role=\"function_name\">%s <phrase role=\"c_punctuation\">()</phrase></entry></row>\n" % (
+ ret_type_output, symbol_output)
+
+ desc = "<refsect2 id=\"%s\" role=\"function\"%s>\n<title>%s ()</title>\n" % (sid, condition, symbol)
+
+ desc += MakeIndexterms(symbol, sid)
+ desc += "\n"
+ desc += OutputSymbolExtraLinks(symbol)
+
+ desc += "<programlisting language=\"C\">%s%s(" % (ret_type_output, symbol_desc_output)
+
+ def tagfun(*args):
+ return tagify(args[0], "parameter")
+
+ fields = common.ParseFunctionDeclaration(declaration, MakeXRef, tagfun)
+
+ first = True
+ for field_name in fields.values():
+ if first:
+ desc += field_name
+ first = False
+ else:
+ desc += ",\n" + (' ' * indent_len) + field_name
+
+ desc += ");</programlisting>\n"
+
+ desc += MakeDeprecationNote(symbol)
+
+ if symbol in SymbolDocs:
+ desc += ConvertMarkDown(symbol, SymbolDocs[symbol])
+
+ if symbol in SymbolAnnotations:
+ param_desc = SymbolAnnotations[symbol]
+ (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc)
+ if param_annotations != '':
+ desc += "\n<para>%s</para>" % param_annotations
+
+ desc += OutputParamDescriptions("FUNCTION", symbol, iterkeys(fields))
+ desc += OutputSymbolTraits(symbol)
+ desc += "</refsect2>\n"
+ return (synop, desc)
+
+
+def OutputParamDescriptions(symbol_type, symbol, fields):
+ """Returns the DocBook output describing the parameters of a symbol.
+
+ This can be used for functions, macros or signal handlers.
+
+ Args:
+ symbol_type (str): 'FUNCTION', 'MACRO' or 'SIGNAL'. Signal
+ handlers have an implicit user_data parameter last.
+ symbol (str): the name of the symbol being described.
+ fields (list): parsed fields from the declaration, used to determine
+ undocumented/unused entries
+
+ Returns:
+ str: the formated parameter docs
+ """
+ output = ''
+ num_params = 0
+ field_descrs = None
+
+ if fields:
+ field_descrs = [f for f in fields if f not in ['void', 'Returns']]
+ else:
+ field_descrs = []
+
+ params = SymbolParams.get(symbol)
+ logging.info("param_desc(%s, %s) = %s", symbol_type, symbol, str(params))
+ # This might be an empty dict, but for SIGNALS we append the user_data docs.
+ # TODO(ensonic): maybe create that docstring in GetSignals()
+ if params is not None:
+ returns = ''
+ params_desc = ''
+ missing_parameters = ''
+ unused_parameters = ''
+
+ for param_name, param_desc in iteritems(params):
+ (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc)
+ param_desc = ConvertMarkDown(symbol, param_desc)
+ # trim
+ param_desc = re.sub(r'^(\s|\n)+', '', param_desc, flags=re.M | re.S)
+ param_desc = re.sub(r'(\s|\n)+$', '', param_desc, flags=re.M | re.S)
+ if param_name == "Returns":
+ returns = param_desc
+ if param_annotations != '':
+ returns += "\n<para>%s</para>" % param_annotations
+
+ elif param_name == "void":
+ # FIXME: &common.LogWarning()?
+ logging.info("!!!! void in params for %s?\n", symbol)
+ else:
+ if fields:
+ if param_name not in field_descrs:
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Parameter description for %s::%s is not used from source code comment block." % (symbol, param_name))
+ if unused_parameters != '':
+ unused_parameters += ", " + param_name
+ else:
+ unused_parameters = param_name
+ else:
+ field_descrs.remove(param_name)
+
+ if param_desc != '':
+ params_desc += "<row><entry role=\"parameter_name\"><para>%s</para></entry>\n<entry role=\"parameter_description\">%s</entry>\n<entry role=\"parameter_annotations\">%s</entry></row>\n" % (
+ param_name, param_desc, param_annotations)
+ num_params += 1
+
+ for param_name in field_descrs:
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Parameter description for %s::%s is missing in source code comment block." % (symbol, param_name))
+ if missing_parameters != '':
+ missing_parameters += ", " + param_name
+ else:
+ missing_parameters = param_name
+
+ # Signals have an implicit user_data parameter which we describe.
+ if symbol_type == "SIGNAL":
+ params_desc += "<row><entry role=\"parameter_name\"><simpara>user_data</simpara></entry>\n<entry role=\"parameter_description\"><simpara>user data set when the signal handler was connected.</simpara></entry>\n<entry role=\"parameter_annotations\"></entry></row>\n"
+
+ # Start a table if we need one.
+ if params_desc != '':
+ sid = common.CreateValidSGMLID("%s.parameters" % symbol)
+
+ output += '''<refsect3 id="%s" role="parameters">\n<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+''' % sid
+ output += params_desc
+ output += "</tbody></tgroup></informaltable>\n</refsect3>"
+
+ # Output the returns info last
+ if returns != '':
+ sid = common.CreateValidSGMLID("%s.returns" % symbol)
+
+ output += '''<refsect3 id="%s" role=\"returns\">\n<title>Returns</title>
+''' % sid
+ output += returns
+ output += "\n</refsect3>"
+
+ # remember missing/unused parameters (needed in tmpl-free build)
+ if missing_parameters != '' and (symbol not in AllIncompleteSymbols):
+ AllIncompleteSymbols[symbol] = missing_parameters
+
+ if unused_parameters != '' and (symbol not in AllUnusedSymbols):
+ AllUnusedSymbols[symbol] = unused_parameters
+
+ if num_params == 0 and fields and field_descrs:
+ if symbol not in AllIncompleteSymbols:
+ AllIncompleteSymbols[symbol] = "<parameters>"
+ return output
+
+
+def ParseStabilityLevel(stability, file, line, message):
+ """Parses a stability level and outputs a warning if it isn't valid.
+ Args:
+ stability (str): the stability text.
+ file, line: context for error message
+ message: description of where the level is from, to use in any error message.
+ Returns:
+ str: the parsed stability level string.
+ """
+ sl = stability.strip().lower()
+ if sl == 'stable':
+ stability = "Stable"
+ elif sl == 'unstable':
+ stability = "Unstable"
+ elif sl == 'private':
+ stability = "Private"
+ else:
+ common.LogWarning(file, line, "%s is %s." % (message, stability) +
+ "It should be one of these: Stable, Unstable, or Private.")
+ return stability
+
+
+def OutputDBFile(file, title, section_id, includes, functions_synop, other_synop, functions_details, other_details, signals_synop, signals_desc, args_synop, args_desc, hierarchy, interfaces, implementations, prerequisites, derived, file_objects):
+ """Outputs the final DocBook file for one section.
+
+ Args:
+ file (str): the name of the file.
+ title (str): the title from the $MODULE-sections.txt file
+ section_id (str): the id to use for the toplevel tag.
+ includes (str): comma-separates list of include files added at top of
+ synopsis, with '<' '>' around them (if not already enclosed in '').
+ functions_synop (str): the DocBook for the Functions Synopsis part.
+ other_synop (str): the DocBook for the Types and Values Synopsis part.
+ functions_details (str): the DocBook for the Functions Details part.
+ other_details (str): the DocBook for the Types and Values Details part.
+ signal_synop (str): the DocBook for the Signal Synopsis part
+ signal_desc (str): the DocBook for the Signal Description part
+ args_synop (str): the DocBook for the Arg Synopsis part
+ args_desc (str): the DocBook for the Arg Description part
+ hierarchy (str): the DocBook for the Object Hierarchy part
+ interfaces (str): the DocBook for the Interfaces part
+ implementations (str): the DocBook for the Known Implementations part
+ prerequisites (str): the DocBook for the Prerequisites part
+ derived (str): the DocBook for the Derived Interfaces part
+ file_objects (list): objects in this file
+
+ Returns:
+ bool: True if the docs where updated
+ """
+
+ logging.info("Output docbook for file %s with title '%s'", file, title)
+
+ # The edited title overrides the one from the sections file.
+ new_title = SymbolDocs.get(file + ":Title")
+ if new_title and not new_title.strip() == '':
+ title = new_title
+ logging.info("Found title: %s", title)
+
+ short_desc = SymbolDocs.get(file + ":Short_Description")
+ if not short_desc or short_desc.strip() == '':
+ short_desc = ''
+ else:
+ # Don't use ConvertMarkDown here for now since we don't want blocks
+ short_desc = ExpandAbbreviations(title + ":Short_description", short_desc)
+ logging.info("Found short_desc: %s", short_desc)
+
+ long_desc = SymbolDocs.get(file + ":Long_Description")
+ if not long_desc or long_desc.strip() == '':
+ long_desc = ''
+ else:
+ long_desc = ConvertMarkDown(title + ":Long_description", long_desc)
+ logging.info("Found long_desc: %s", long_desc)
+
+ see_also = SymbolDocs.get(file + ":See_Also")
+ if not see_also or re.search(r'^\s*(<para>)?\s*(</para>)?\s*$', see_also):
+ see_also = ''
+ else:
+ see_also = ConvertMarkDown(title + ":See_Also", see_also)
+ logging.info("Found see_also: %s", see_also)
+
+ if see_also:
+ see_also = "<refsect1 id=\"%s.see-also\">\n<title>See Also</title>\n%s\n</refsect1>\n" % (section_id, see_also)
+
+ stability = SymbolDocs.get(file + ":Stability_Level")
+ if not stability or re.search(r'^\s*$', stability):
+ stability = ''
+ else:
+ line_number = GetSymbolSourceLine(file + ":Stability_Level")
+ stability = ParseStabilityLevel(stability, file, line_number, "Section stability level")
+ logging.info("Found stability: %s", stability)
+
+ if stability:
+ AnnotationsUsed[stability] = 1
+ stability = "<refsect1 id=\"%s.stability-level\">\n<title>Stability Level</title>\n<acronym>%s</acronym>, unless otherwise indicated\n</refsect1>\n" % (
+ section_id, stability)
+ elif DEFAULT_STABILITY:
+ AnnotationsUsed[DEFAULT_STABILITY] = 1
+ stability = "<refsect1 id=\"%s.stability-level\">\n<title>Stability Level</title>\n<acronym>%s</acronym>, unless otherwise indicated\n</refsect1>\n" % (
+ section_id, DEFAULT_STABILITY)
+
+ image = SymbolDocs.get(file + ":Image")
+ if not image or re.search(r'^\s*$', image):
+ image = ''
+ else:
+ image = image.strip()
+
+ format = None
+
+ il = image.lower()
+ if re.search(r'jpe?g$', il):
+ format = "format='JPEG'"
+ elif il.endswith('png'):
+ format = "format='PNG'"
+ elif il.endswith('svg'):
+ format = "format='SVG'"
+ else:
+ format = ''
+
+ image = " <inlinegraphic fileref='%s' %s/>\n" % (image, format)
+
+ include_output = ''
+ if includes:
+ include_output += "<refsect1 id=\"%s.includes\"><title>Includes</title><synopsis>" % section_id
+ for include in includes.split(','):
+ if re.search(r'^\".+\"$', include):
+ include_output += "#include %s\n" % include
+ else:
+ include = re.sub(r'^\s+|\s+$', '', include, flags=re.S)
+ include_output += "#include <%s>\n" % include
+
+ include_output += "</synopsis></refsect1>\n"
+
+ extralinks = OutputSectionExtraLinks(title, "Section:%s" % file)
+
+ old_db_file = os.path.join(DB_OUTPUT_DIR, file + '.xml')
+ new_db_file = os.path.join(DB_OUTPUT_DIR, file + '.xml.new')
+
+ OUTPUT = open(new_db_file, 'w')
+
+ object_anchors = ''
+ for fobject in file_objects:
+ if fobject == section_id:
+ continue
+ sid = common.CreateValidSGMLID(fobject)
+ logging.info("Adding anchor for %s\n", fobject)
+ object_anchors += "<anchor id=\"%s\"/>" % sid
+
+ # Make sure we produce valid docbook
+ if not functions_details:
+ functions_details = "<para />"
+
+ # We used to output this, but is messes up our common.UpdateFileIfChanged code
+ # since it changes every day (and it is only used in the man pages):
+ # "<refentry id="$section_id" revision="$mday $month $year">"
+
+ OUTPUT.write(REFENTRY.substitute({
+ 'args_desc': args_desc,
+ 'args_synop': args_synop,
+ 'derived': derived,
+ 'extralinks': extralinks,
+ 'functions_details': functions_details,
+ 'functions_synop': functions_synop,
+ 'header': MakeDocHeader('refentry'),
+ 'hierarchy': hierarchy,
+ 'image': image,
+ 'include_output': include_output,
+ 'interfaces': interfaces,
+ 'implementations': implementations,
+ 'long_desc': long_desc,
+ 'object_anchors': object_anchors,
+ 'other_details': other_details,
+ 'other_synop': other_synop,
+ 'prerequisites': prerequisites,
+ 'section_id': section_id,
+ 'see_also': see_also,
+ 'signals_desc': signals_desc,
+ 'signals_synop': signals_synop,
+ 'short_desc': short_desc,
+ 'stability': stability,
+ 'title': title,
+ 'MODULE': MODULE.upper(),
+ }))
+ OUTPUT.close()
+
+ return common.UpdateFileIfChanged(old_db_file, new_db_file, 0)
+
+
+def OutputProgramDBFile(program, section_id):
+ """Outputs the final DocBook file for one program.
+
+ Args:
+ file (str): the name of the file.
+ section_id (str): the id to use for the toplevel tag.
+
+ Returns:
+ bool: True if the docs where updated
+ """
+ logging.info("Output program docbook for %s", program)
+
+ short_desc = SourceSymbolDocs.get(program + ":Short_Description")
+ if not short_desc or short_desc.strip() == '':
+ short_desc = ''
+ else:
+ # Don't use ConvertMarkDown here for now since we don't want blocks
+ short_desc = ExpandAbbreviations(program, short_desc)
+ logging.info("Found short_desc: %s", short_desc)
+
+ synopsis = SourceSymbolDocs.get(program + ":Synopsis")
+ if synopsis and synopsis.strip() != '':
+ items = synopsis.split(' ')
+ for i in range(0, len(items)):
+ parameter = items[i]
+ choice = "plain"
+ rep = ''
+
+ # first parameter is the command name
+ if i == 0:
+ synopsis = "<command>%s</command>\n" % parameter
+ continue
+
+ # square brackets indicate optional parameters, curly brackets
+ # indicate required parameters ("plain" parameters are also
+ # mandatory, but do not get extra decoration)
+ m1 = re.search(r'^\[(.+?)\]$', parameter)
+ m2 = re.search(r'^\{(.+?)\}$', parameter)
+ if m1:
+ choice = "opt"
+ parameter = m1.group(1)
+ elif m2:
+ choice = "req"
+ parameter = m2.group(1)
+
+ # parameters ending in "..." are repeatable
+ if parameter.endswith('...'):
+ rep = ' rep=\"repeat\"'
+ parameter = parameter[:-3]
+
+ # italic parameters are replaceable parameters
+ parameter = re.sub(r'\*(.+?)\*', r'<replaceable>\1</replaceable>', parameter)
+
+ synopsis += "<arg choice=\"%s\"%s>" % (choice, rep)
+ synopsis += parameter
+ synopsis += "</arg>\n"
+
+ logging.info("Found synopsis: %s", synopsis)
+ else:
+ synopsis = "<command>%s</command>" % program
+
+ long_desc = SourceSymbolDocs.get(program + ":Long_Description")
+ if not long_desc or long_desc.strip() == '':
+ long_desc = ''
+ else:
+ long_desc = ConvertMarkDown("%s:Long_description" % program, long_desc)
+ logging.info("Found long_desc: %s", long_desc)
+
+ options = ''
+ o = program + ":Options"
+ if o in SourceSymbolDocs:
+ opts = SourceSymbolDocs[o].split('\t')
+
+ logging.info('options: %d, %s', len(opts), str(opts))
+
+ options = "<refsect1>\n<title>Options</title>\n<variablelist>\n"
+ for k in range(0, len(opts), 2):
+ opt_desc = opts[k + 1]
+
+ opt_desc = re.sub(r'\*(.+?)\*', r'<replaceable>\1</replaceable>', opt_desc)
+
+ options += "<varlistentry>\n<term>"
+ opt_names = opts[k].split(',')
+ for i in range(len(opt_names)):
+ prefix = ', ' if i > 0 else ''
+ # italic parameters are replaceable parameters
+ opt_name = re.sub(r'\*(.+?)\*', r'<replaceable>\1</replaceable>', opt_names[i])
+
+ options += "%s<option>%s</option>\n" % (prefix, opt_name)
+
+ options += "</term>\n"
+ options += "<listitem><para>%s</para></listitem>\n" % opt_desc
+ options += "</varlistentry>\n"
+
+ options += "</variablelist></refsect1>\n"
+
+ exit_status = SourceSymbolDocs.get(program + ":Returns")
+ if exit_status and exit_status != '':
+ exit_status = ConvertMarkDown("%s:Returns" % program, exit_status)
+ exit_status = "<refsect1 id=\"%s.exit-status\">\n<title>Exit Status</title>\n%s\n</refsect1>\n" % (
+ section_id, exit_status)
+ else:
+ exit_status = ''
+
+ see_also = SourceSymbolDocs.get(program + ":See_Also")
+ if not see_also or re.search(r'^\s*(<para>)?\s*(</para>)?\s*$', see_also):
+ see_also = ''
+ else:
+ see_also = ConvertMarkDown("%s:See_Also" % program, see_also)
+ logging.info("Found see_also: %s", see_also)
+
+ if see_also:
+ see_also = "<refsect1 id=\"%s.see-also\">\n<title>See Also</title>\n%s\n</refsect1>\n" % (section_id, see_also)
+
+ old_db_file = os.path.join(DB_OUTPUT_DIR, program + ".xml")
+ new_db_file = os.path.join(DB_OUTPUT_DIR, program + ".xml.new")
+
+ OUTPUT = open(new_db_file, 'w')
+
+ OUTPUT.write('''%s
+<refentry id="%s">
+<refmeta>
+<refentrytitle role="top_of_page" id="%s.top_of_page">%s</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo>User Commands</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>%s</refname>
+<refpurpose>%s</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<cmdsynopsis>%s</cmdsynopsis>
+</refsynopsisdiv>
+<refsect1 id="%s.description" role="desc">
+<title role="desc.title">Description</title>
+%s
+</refsect1>
+%s%s%s
+</refentry>
+''' % (MakeDocHeader("refentry"), section_id, section_id, program, program, short_desc, synopsis, section_id, long_desc, options, exit_status, see_also))
+ OUTPUT.close()
+
+ return common.UpdateFileIfChanged(old_db_file, new_db_file, 0)
+
+
+def OutputExtraFile(file):
+ """Copies an "extra" DocBook file into the output directory, expanding abbreviations.
+
+ Args:
+ file (str): the source file.
+
+ Returns:
+ bool: True if the docs where updated
+ """
+
+ basename = os.path.basename(file)
+
+ old_db_file = os.path.join(DB_OUTPUT_DIR, basename)
+ new_db_file = os.path.join(DB_OUTPUT_DIR, basename + ".new")
+
+ contents = open(file).read()
+
+ OUTPUT = open(new_db_file, 'w')
+ OUTPUT.write(ExpandAbbreviations(basename + " file", contents))
+ OUTPUT.close()
+
+ return common.UpdateFileIfChanged(old_db_file, new_db_file, 0)
+
+
+def GetDocbookHeader(main_file):
+ if os.path.exists(main_file):
+ INPUT = open(main_file)
+ header = ''
+ for line in INPUT:
+ if re.search(r'^\s*<(book|chapter|article)', line):
+ # check that the top-level tagSYSTEM or the doctype decl contain the xinclude namespace decl
+ if not re.search(r'http:\/\/www.w3.org\/200[13]\/XInclude', line) and \
+ not re.search(r'http:\/\/www.w3.org\/200[13]\/XInclude', header, flags=re.MULTILINE):
+ header = ''
+ break
+
+ # if there are SYSTEM ENTITIES here, we should prepend "../" to the path
+ # FIXME: not sure if we can do this now, as people already work-around the problem
+ # r'#<!ENTITY % ([a-zA-Z-]+) SYSTEM \"([^/][a-zA-Z./]+)\">', r'<!ENTITY % \1 SYSTEM \"../\2\">';
+ line = re.sub(
+ r'<!ENTITY % gtkdocentities SYSTEM "([^"]*)">', r'<!ENTITY % gtkdocentities SYSTEM "../\1">', line)
+ header += line
+ INPUT.close()
+ header = header.strip()
+ else:
+ header = '''<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY % gtkdocentities SYSTEM "../xml/gtkdocentities.ent">
+ %gtkdocentities;
+]>'''
+ return header
+
+
+def OutputBook(main_file, book_top, book_bottom):
+ """Outputs the entities that need to be included into the main docbook file for the module.
+
+ Args:
+ book_top (str): the declarations of the entities, which are added
+ at the top of the main docbook file.
+ book_bottom (str): the entities, which are added in the main docbook
+ file at the desired position.
+ """
+
+ old_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.top")
+ new_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.top.new")
+
+ OUTPUT = open(new_file, 'w')
+ OUTPUT.write(book_top)
+ OUTPUT.close()
+
+ 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 = open(new_file, 'w')
+ OUTPUT.write(book_bottom)
+ OUTPUT.close()
+
+ 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 = open(main_file, 'w')
+
+ logging.info("no master doc, create default one at: " + main_file)
+
+ OUTPUT.write('''%s
+<book id="index">
+ <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>
+
+ <chapter>
+ <title>[Insert title here]</title>
+ %s
+ </chapter>
+''' % (MakeDocHeader("book"), book_bottom))
+ if os.path.exists('xml/tree_index.sgml'):
+ OUTPUT.write(''' <chapter id="object-tree">
+ <title>Object Hierarchy</title>
+ <xi:include href="xml/tree_index.sgml"/>
+ </chapter>
+''')
+ else:
+ OUTPUT.write(''' <!-- enable this when you use gobject types
+ <chapter id="object-tree">
+ <title>Object Hierarchy</title>
+ <xi:include href="xml/tree_index.sgml"/>
+ </chapter>
+ -->
+''')
+
+ OUTPUT.write(''' <index id="api-index-full">
+ <title>API Index</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="deprecated-api-index" role="deprecated">
+ <title>Index of deprecated API</title>
+ <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+ </index>
+''')
+ for version in set(Since.values()):
+ dash_version = version.replace('.', '-')
+ OUTPUT.write(''' <index id="api-index-%s" role="%s">
+ <title>Index of new API in %s</title>
+ <xi:include href="xml/api-index-%s.xml"><xi:fallback /></xi:include>
+ </index>
+''' % (dash_version, version, version, version))
+
+ if AnnotationsUsed:
+ OUTPUT.write(''' <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+''')
+ else:
+ OUTPUT.write(''' <!-- enable this when you use gobject introspection annotations
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+ -->
+''')
+
+ OUTPUT.write('''</book>
+''')
+
+ OUTPUT.close()
+
+
+def CreateValidSGML(text):
+ """Turn any chars which are used in XML into entities.
+
+ e.g. '<' into '<'
+
+ Args:
+ text (str): the text to turn into proper XML.
+
+ Returns:
+ str: escaped input
+ """
+
+ text = text.replace('&', '&') # Do this first, or the others get messed up.
+ text = text.replace('<', '<')
+ text = text.replace('>', '>')
+ # browsers render single tabs inconsistently
+ text = re.sub(r'([^\s])\t([^\s])', r'\1 \2', text)
+ return text
+
+
+def ConvertSGMLChars(symbol, text):
+ """Escape XML chars.
+
+ This is used for text in source code comment blocks, to turn
+ chars which are used in XML into entities, e.g. '<' into
+ <'. Depending on INLINE_MARKUP_MODE, this is done
+ unconditionally or only if the character doesn't seem to be
+ part of an XML construct (tag or entity reference).
+ Args:
+ text (str): the text to turn into proper XML.
+
+ Returns:
+ str: escaped input
+ """
+
+ if INLINE_MARKUP_MODE:
+ # For the XML/SGML mode only convert to entities outside CDATA sections.
+ return ModifyXMLElements(text, symbol,
+ "<!\\[CDATA\\[|<programlisting[^>]*>",
+ ConvertSGMLCharsEndTag,
+ ConvertSGMLCharsCallback)
+ # 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 '>' at beginning of string for blockquote markdown
+ text = re.sub(r'''(?<=[^\w\n"'\/-])>''', r'>', text)
+
+ return text
+
+
+def ConvertSGMLCharsEndTag(start_tag):
+ if start_tag == '<![CDATA[':
+ return "]]>"
+ return "</programlisting>"
+
+
+def ConvertSGMLCharsCallback(text, symbol, tag):
+ if re.search(r'^<programlisting', tag):
+ logging.debug('call modifyXML')
+ # We can handle <programlisting> specially here.
+ return ModifyXMLElements(text, symbol,
+ "<!\\[CDATA\\[",
+ ConvertSGMLCharsEndTag,
+ ConvertSGMLCharsCallback2)
+ elif tag == '':
+ logging.debug('replace entities')
+ # If we're not in CDATA convert to entities.
+ text = re.sub(r'&(?![a-zA-Z#]+;)', r'&', text) # Do this first, or the others get messed up.
+ text = re.sub(r'<(?![a-zA-Z\/!])', r'<', text)
+ # Allow '>' at beginning of string for blockquote markdown
+ text = re.sub(r'''(?<=[^\w\n"'\/-])>''', r'>', text)
+
+ # Handle "#include <xxxxx>"
+ text = re.sub(r'#include(\s+)<([^>]+)>', r'#include\1<\2>', text)
+
+ return text
+
+
+def ConvertSGMLCharsCallback2(text, symbol, tag):
+ # If we're not in CDATA convert to entities.
+ # We could handle <programlisting> differently, though I'm not sure it helps.
+ if tag == '':
+ # replace only if its not a tag
+ text = re.sub(r'&(?![a-zA-Z#]+;)', r'&', text) # Do this first, or the others get messed up.
+ text = re.sub(r'<(?![a-zA-Z\/!])', r'<', text)
+ text = re.sub(r'''(?<![a-zA-Z0-9"'\/-])>''', r'>', text)
+ # Handle "#include <xxxxx>"
+ text = re.sub(r'/#include(\s+)<([^>]+)>', r'#include\1<\2>', text)
+
+ return text
+
+
+def ExpandAnnotation(symbol, param_desc):
+ """This turns annotations into acronym tags.
+ Args:
+ symbol (str): the symbol being documented, for error messages.
+ param_desc (str): the text to expand.
+
+ Returns:
+ str: the remaining param_desc
+ str: the formatted annotations
+ """
+ param_annotations = ''
+
+ # look for annotations at the start of the comment part
+ # function level annotations don't end with a colon ':'
+ m = re.search(r'^\s*\((.*?)\)(:|$)', param_desc)
+ if m:
+ param_desc = param_desc[m.end():]
+
+ annotations = re.split(r'\)\s*\(', m.group(1))
+ logging.info("annotations for %s: '%s'\n", symbol, m.group(1))
+ for annotation in annotations:
+ # need to search for the longest key-match in %AnnotationDefinition
+ match_length = 0
+ match_annotation = ''
+
+ for annotationdef in AnnotationDefinition:
+ if annotation.startswith(annotationdef):
+ if len(annotationdef) > match_length:
+ match_length = len(annotationdef)
+ match_annotation = annotationdef
+
+ annotation_extra = ''
+ if match_annotation != '':
+ m = re.search(match_annotation + r'\s+(.*)', annotation)
+ if m:
+ annotation_extra = " " + m.group(1)
+
+ AnnotationsUsed[match_annotation] = 1
+ param_annotations += "[<acronym>%s</acronym>%s]" % (match_annotation, annotation_extra)
+ else:
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "unknown annotation \"%s\" in documentation for %s." % (annotation, symbol))
+ param_annotations += "[%s]" % annotation
+
+ param_desc = param_desc.strip()
+ m = re.search(r'^(.*?)\.*\s*$', param_desc, flags=re.S)
+ param_desc = m.group(1) + '. '
+
+ if param_annotations != '':
+ param_annotations = "<emphasis role=\"annotation\">%s</emphasis>" % param_annotations
+
+ return (param_desc, param_annotations)
+
+
+def ExpandAbbreviations(symbol, text):
+ """Expand the shortcut notation for symbol references.
+
+ This turns the abbreviations function(), macro(), @param, %constant, and #symbol
+ into appropriate DocBook markup. CDATA sections and <programlisting> parts
+ are skipped.
+
+ Args:
+ symbol (str): the symbol being documented, for error messages.
+ text (str): the text to expand.
+
+ Returns:
+ str: the expanded text
+ """
+ # Note: This is a fallback and normally done in the markdown parser
+
+ logging.debug('expand abbreviations for "%s", text: [%s]', symbol, text)
+ m = re.search(r'\|\[[^\n]*\n(.*)\]\|', text, flags=re.M | re.S)
+ if m:
+ logging.debug('replaced entities in code block')
+ text = text[:m.start(1)] + md_to_db.ReplaceEntities(m.group(1)) + text[m.end(1):]
+
+ # Convert "|[" and "]|" into the start and end of program listing examples.
+ # Support \[<!-- language="C" --> modifiers
+ text = re.sub(r'\|\[<!-- language="([^"]+)" -->', r'<informalexample><programlisting language="\1"><![CDATA[', text)
+ text = re.sub(r'\|\[', r'<informalexample><programlisting><![CDATA[', text)
+ text = re.sub(r'\]\|', r']]></programlisting></informalexample>', text)
+
+ # keep CDATA unmodified, preserve ulink tags (ideally we preseve all tags
+ # as such)
+ return ModifyXMLElements(text, symbol,
+ "<!\\[CDATA\\[|<ulink[^>]*>|<programlisting[^>]*>|<!DOCTYPE",
+ ExpandAbbreviationsEndTag,
+ ExpandAbbreviationsCallback)
+
+
+def ExpandAbbreviationsEndTag(start_tag):
+ # Returns the end tag (as a regexp) corresponding to the given start tag.
+ if start_tag == r'<!\[CDATA\[':
+ return "]]>"
+ if start_tag == "<!DOCTYPE":
+ return '>'
+ m = re.search(r'<(\w+)', start_tag)
+ if m:
+ return "</%s>" % m.group(1)
+
+ logging.warning('no end tag for "%s"', start_tag)
+ return ''
+
+
+def ExpandAbbreviationsCallback(text, symbol, tag):
+ # Called inside or outside each CDATA or <programlisting> section.
+ if tag.startswith(r'^<programlisting'):
+ # Handle any embedded CDATA sections.
+ return ModifyXMLElements(text, symbol,
+ "<!\\[CDATA\\[",
+ ExpandAbbreviationsEndTag,
+ ExpandAbbreviationsCallback2)
+ elif tag == '':
+ # NOTE: this is a fallback. It is normally done by the Markdown parser.
+ # but is also used for OutputExtraFile
+
+ # We are outside any CDATA or <programlisting> sections, so we expand
+ # any gtk-doc abbreviations.
+
+ # Convert '@param()'
+ # FIXME: we could make those also links ($symbol.$2), but that would be less
+ # useful as the link target is a few lines up or down
+ text = re.sub(r'(\A|[^\\])\@(\w+((\.|->)\w+)*)\s*\(\)', r'\1<parameter>\2()</parameter>', text)
+
+ # Convert 'function()' or 'macro()'.
+ # if there is abc_*_def() we don't want to make a link to _def()
+ # FIXME: also handle abc(def(....)) : but that would need to be done recursively :/
+ def f1(m):
+ return m.group(1) + MakeXRef(m.group(2), tagify(m.group(2) + "()", "function"))
+ text = re.sub(r'([^\*.\w])(\w+)\s*\(\)', f1, text)
+ # handle #Object.func()
+ text = re.sub(r'(\A|[^\\])#([\w\-:\.]+[\w]+)\s*\(\)', f1, text)
+
+ # Convert '@param', but not '\@param'.
+ text = re.sub(r'(\A|[^\\])\@(\w+((\.|->)\w+)*)', r'\1<parameter>\2</parameter>', text)
+ text = re.sub(r'/\\\@', r'\@', text)
+
+ # Convert '%constant', but not '\%constant'.
+ # Also allow negative numbers, e.g. %-1.
+ def f2(m):
+ return m.group(1) + MakeXRef(m.group(2), tagify(m.group(2), "literal"))
+ text = re.sub(r'(\A|[^\\])\%(-?\w+)', f2, text)
+ text = re.sub(r'\\\%', r'\%', text)
+
+ # Convert '#symbol', but not '\#symbol'.
+ def f3(m):
+ return m.group(1) + MakeHashXRef(m.group(2), "type")
+ text = re.sub(r'(\A|[^\\])#([\w\-:\.]+[\w]+)', f3, text)
+ text = re.sub(r'\\#', '#', text)
+
+ return text
+
+
+def ExpandAbbreviationsCallback2(text, symbol, tag):
+ # This is called inside a <programlisting>
+ if tag == '':
+ # We are inside a <programlisting> but outside any CDATA sections,
+ # so we expand any gtk-doc abbreviations.
+ # FIXME: why is this different from &ExpandAbbreviationsCallback(),
+ # why not just call it
+ text = re.sub(r'#(\w+)', lambda m: '%s;' % MakeHashXRef(m.group(1), ''), text)
+ elif tag == "<![CDATA[":
+ # NOTE: this is a fallback. It is normally done by the Markdown parser.
+ text = ReplaceEntities(text, symbol)
+
+ return text
+
+
+def MakeHashXRef(symbol, tag):
+ text = symbol
+
+ # Check for things like '#include', '#define', and skip them.
+ if symbol in PreProcessorDirectives:
+ return "#%s" % symbol
+
+ # Get rid of special suffixes ('-struct','-enum').
+ text = re.sub(r'-struct$', '', text)
+ text = re.sub(r'-enum$', '', text)
+
+ # If the symbol is in the form "Object::signal", then change the symbol to
+ # "Object-signal" and use "signal" as the text.
+ if '::' in symbol:
+ o, s = symbol.split('::', 1)
+ symbol = '%s-%s' % (o, s)
+ text = '“' + s + '”'
+
+ # If the symbol is in the form "Object:property", then change the symbol to
+ # "Object--property" and use "property" as the text.
+ if ':' in symbol:
+ o, p = symbol.split(':', 1)
+ symbol = '%s--%s' % (o, p)
+ text = '“' + p + '”'
+
+ if tag != '':
+ text = tagify(text, tag)
+
+ return MakeXRef(symbol, text)
+
+
+def ModifyXMLElements(text, symbol, start_tag_regexp, end_tag_func, callback):
+ """Rewrite XML blocks.
+
+ Looks for given XML element tags within the text, and calls
+ the callback on pieces of text inside & outside those elements.
+ Used for special handling of text inside things like CDATA
+ and <programlisting>.
+
+ Args:
+ text (str): the text.
+ symbol (str): the symbol currently being documented (only used for
+ error messages).
+ start_tag_regexp (str): the regular expression to match start tags.
+ e.g. "<!\\[CDATA\\[|<programlisting[^>]*>" to
+ match CDATA sections or programlisting elements.
+ end_tag_func (func): function which is passed the matched start tag
+ and should return the appropriate end tag string
+ regexp.
+ callback - callback called with each part of the text. It is
+ called with a piece of text, the symbol being
+ documented, and the matched start tag or '' if the text
+ is outside the XML elements being matched.
+
+ Returns:
+ str: modified text
+ """
+ before_tag = start_tag = end_tag_regexp = end_tag = None
+ result = ''
+
+ logging.debug('modify xml for symbol: %s, regex: %s, text: [%s]', symbol, start_tag_regexp, text)
+
+ m = re.search(start_tag_regexp, text, flags=re.S)
+ while m:
+ before_tag = text[:m.start()] # Prematch for last successful match string
+ start_tag = m.group(0) # Last successful match
+ text = text[m.end():] # Postmatch for last successful match string
+ # get the matching end-tag for current tag
+ end_tag_regexp = end_tag_func(start_tag)
+
+ logging.debug('symbol: %s matched start: %s, end_tag: %s, text: [%s]', symbol, start_tag, end_tag_regexp, text)
+
+ logging.debug('converting before tag: [%s]', before_tag)
+ result += callback(before_tag, symbol, '')
+ result += start_tag
+
+ m2 = re.search(end_tag_regexp, text, flags=re.S)
+ if m2:
+ before_tag = text[:m2.start()]
+ end_tag = m2.group(0)
+ text = text[m2.end():]
+
+ logging.debug('symbol: %s matched end %s: text: [%s]', symbol, end_tag, text)
+
+ result += callback(before_tag, symbol, start_tag)
+ result += end_tag
+ else:
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Can't find tag end: %s in docs for: %s." % (end_tag_regexp, symbol))
+ # Just assume it is all inside the tag.
+ result += callback(text, symbol, start_tag)
+ text = ''
+ m = re.search(start_tag_regexp, text, flags=re.S)
+
+ # Handle any remaining text outside the tags.
+ logging.debug('converting after tag: [%s]', text)
+ result += callback(text, symbol, '')
+ logging.debug('results for symbol: %s, text: [%s]', symbol, result)
+
+ return result
+
+
+def tagify(text, elem):
+ # Adds a tag around some text.
+ # e.g tagify("Text", "literal") => "<literal>Text</literal>".
+ return '<' + elem + '>' + text + '</' + elem + '>'
+
+
+def MakeDocHeader(tag):
+ """Builds a docbook header for the given tag.
+
+ Args:
+ tag (str): doctype tag
+
+ Returns:
+ str: the docbook header
+ """
+ header = re.sub(r'<!DOCTYPE \w+', r'<!DOCTYPE ' + tag, doctype_header)
+ # fix the path for book since this is one level up
+ if tag == 'book':
+ header = re.sub(
+ r'<!ENTITY % gtkdocentities SYSTEM "../([a-zA-Z./]+)">', r'<!ENTITY % gtkdocentities SYSTEM "\1">', header)
+ return header
+
+
+def MakeXRef(symbol, text=None):
+ """This returns a cross-reference link to the given symbol.
+
+ Though it doesn't try to do this for a few standard C types that it knows
+ won't be in the documentation.
+
+ Args:
+ symbol (str): the symbol to try to create a XRef to.
+ text (str): text to put inside the XRef, defaults to symbol
+
+ Returns:
+ str: a docbook link
+ """
+ symbol = symbol.strip()
+ if not text:
+ text = symbol
+
+ # Get rid of special suffixes ('-struct','-enum').
+ text = re.sub(r'-struct$', '', text)
+ text = re.sub(r'-enum$', '', text)
+
+ if ' ' in symbol:
+ return text
+
+ logging.info("Getting type link for %s -> %s", symbol, text)
+
+ symbol_id = common.CreateValidSGMLID(symbol)
+ return "<link linkend=\"%s\">%s</link>" % (symbol_id, text)
+
+
+def MakeIndexterms(symbol, sid):
+ """This returns a indexterm elements for the given symbol
+
+ Args:
+ symbol (str): the symbol to create indexterms for
+
+ Returns:
+ str: doxbook index terms
+ """
+ terms = ''
+ sortas = ''
+
+ # make the index useful, by ommiting the namespace when sorting
+ if NAME_SPACE != '':
+ m = re.search(r'^%s\_?(.*)' % NAME_SPACE, symbol, flags=re.I)
+ if m:
+ sortas = ' sortas="%s"' % m.group(1)
+
+ if symbol in Deprecated:
+ terms += "<indexterm zone=\"%s\" role=\"deprecated\"><primary%s>%s</primary></indexterm>" % (
+ sid, sortas, symbol)
+ IndexEntriesDeprecated[symbol] = sid
+ IndexEntriesFull[symbol] = sid
+ if symbol in Since:
+ since = Since[symbol].strip()
+ if since != '':
+ terms += "<indexterm zone=\"%s\" role=\"%s\"><primary%s>%s</primary></indexterm>" % (
+ sid, since, sortas, symbol)
+ IndexEntriesSince[symbol] = sid
+ IndexEntriesFull[symbol] = sid
+ if terms == '':
+ terms += "<indexterm zone=\"%s\"><primary%s>%s</primary></indexterm>" % (sid, sortas, symbol)
+ IndexEntriesFull[symbol] = sid
+ return terms
+
+
+def MakeDeprecationNote(symbol):
+ """This returns a deprecation warning for the given symbol.
+
+ Args:
+ symbol (str): the symbol to try to create a warning for.
+
+ Returns:
+ str: formatted warning or empty string if symbol is not deprecated
+ """
+ desc = ''
+ if symbol in Deprecated:
+ desc += "<warning><para><literal>%s</literal> " % symbol
+ note = Deprecated[symbol]
+
+ m = re.search(r'^\s*([0-9\.]+)\s*:?', note)
+ if m:
+ desc += "has been deprecated since version %s and should not be used in newly-written code.</para>" % m.group(
+ 1)
+ else:
+ desc += "is deprecated and should not be used in newly-written code.</para>"
+
+ note = re.sub(r'^\s*([0-9\.]+)\s*:?\s*', '', note)
+ note = note.strip()
+
+ if note != '':
+ note = ConvertMarkDown(symbol, note)
+ desc += " " + note
+
+ desc += "</warning>\n"
+
+ return desc
+
+
+def MakeConditionDescription(symbol):
+ """This returns a sumary of conditions for the given symbol.
+
+ Args:
+ symbol (str): the symbol to create the sumary for.
+
+ Returns:
+ str: formatted text or empty string if no special conditions apply.
+ """
+ desc = ''
+ if symbol in Deprecated:
+ if desc != '':
+ desc += "|"
+ m = re.search(r'^\s*(.*?)\s*$', Deprecated[symbol])
+ if m:
+ desc += "deprecated:%s" % m.group(1)
+ else:
+ desc += "deprecated"
+
+ if symbol in Since:
+ if desc != '':
+ desc += "|"
+ m = re.search(r'^\s*(.*?)\s*$', Since[symbol])
+ if m:
+ desc += "since:%s" % m.group(1)
+ else:
+ desc += "since"
+
+ if symbol in StabilityLevel:
+ if desc != '':
+ desc += "|"
+
+ desc += "stability:" + StabilityLevel[symbol]
+
+ if desc != '':
+ cond = re.sub(r'"', r'"', desc)
+ desc = ' condition=\"%s\"' % cond
+ logging.info("condition for '%s' = '%s'", symbol, desc)
+
+ return desc
+
+
+def GetHierarchy(gobject, hierarchy):
+ """Generate the object inheritance graph.
+
+ Returns the DocBook output describing the ancestors and
+ immediate children of a GObject subclass. It uses the
+ global Objects and ObjectLevels arrays to walk the tree.
+
+ Args:
+ object (str): the GtkObject subclass.
+ hierarchy (list) - previous hierarchy
+
+ Returns:
+ list: lines of docbook describing the hierarchy
+ """
+ # Find object in the objects array.
+ found = False
+ children = []
+ level = 0
+ j = 0
+ for i in range(len(Objects)):
+ if found:
+ if ObjectLevels[i] <= level:
+ break
+
+ elif ObjectLevels[i] == level + 1:
+ children.append(Objects[i])
+
+ elif Objects[i] == gobject:
+ found = True
+ j = i
+ level = ObjectLevels[i]
+
+ if not found:
+ return hierarchy
+
+ logging.info("=== Hierachy for: %s (%d existing entries) ===", gobject, len(hierarchy))
+
+ # Walk up the hierarchy, pushing ancestors onto the ancestors array.
+ ancestors = [gobject]
+ logging.info("Level: %s", level)
+ while level > 1:
+ j -= 1
+ if ObjectLevels[j] < level:
+ ancestors.append(Objects[j])
+ level = ObjectLevels[j]
+ logging.info("Level: %s", level)
+
+ # Output the ancestors, indented and with links.
+ logging.info('%d ancestors', len(ancestors))
+ last_index = 0
+ level = 1
+ for i in range(len(ancestors) - 1, -1, -1):
+ ancestor = ancestors[i]
+ ancestor_id = common.CreateValidSGMLID(ancestor)
+ indent = ' ' * (level * 4)
+ # Don't add a link to the current object, i.e. when i == 0.
+ if i > 0:
+ entry_text = indent + "<link linkend=\"%s\">%s</link>" % (ancestor_id, ancestor)
+ alt_text = indent + ancestor
+ else:
+ entry_text = indent + ancestor
+ alt_text = indent + "<link linkend=\"%s\">%s</link>" % (ancestor_id, ancestor)
+
+ logging.info("Checking for '%s' or '%s'", entry_text, alt_text)
+ # Check if we already have this object
+ index = -1
+ for j in range(len(hierarchy)):
+ if hierarchy[j] == entry_text or (hierarchy[j] == alt_text):
+ index = j
+ break
+ if index == -1:
+ # We have a new entry, find insert position in alphabetical order
+ found = False
+ for j in range(last_index, len(hierarchy)):
+ if not re.search(r'^' + indent, hierarchy[j]):
+ last_index = j
+ found = True
+ break
+ elif re.search(r'^%s[^ ]' % indent, hierarchy[j]):
+ stripped_text = hierarchy[j]
+ if r'<link linkend' not in entry_text:
+ stripped_text = re.sub(r'<link linkend="[A-Za-z]*">', '', stripped_text)
+ stripped_text = re.sub(r'</link>', '', stripped_text)
+
+ if entry_text < stripped_text:
+ last_index = j
+ found = True
+ break
+
+ # Append to bottom
+ if not found:
+ last_index = len(hierarchy)
+
+ logging.debug('insert at %d: %s', last_index, entry_text)
+ hierarchy.insert(last_index, entry_text)
+ last_index += 1
+ else:
+ # Already have this one, make sure we use the not linked version
+ if r'<link linkend' not in entry_text:
+ hierarchy[j] = entry_text
+
+ # Remember index as base insert point
+ last_index = index + 1
+
+ level += 1
+
+ # Output the children, indented and with links.
+ logging.info('%d children', len(children))
+ for i in range(len(children)):
+ sid = common.CreateValidSGMLID(children[i])
+ indented_text = ' ' * (level * 4) + "<link linkend=\"%s\">%s</link>" % (sid, children[i])
+ logging.debug('insert at %d: %s', last_index, indented_text)
+ hierarchy.insert(last_index, indented_text)
+ last_index += 1
+ return hierarchy
+
+
+def GetInterfaces(gobject):
+ """Generate interface implementation graph.
+
+ Returns the DocBook output describing the interfaces
+ implemented by a class. It uses the global Interfaces hash.
+
+ Args:
+ object (str): the GObject subclass.
+
+ Returns:
+ str: implemented interfaces
+ """
+ text = ''
+ # Find object in the objects array.
+ if gobject in Interfaces:
+ ifaces = Interfaces[gobject].split()
+ text = '''<para>
+%s implements
+''' % gobject
+ count = len(ifaces)
+ for i in range(count):
+ sid = common.CreateValidSGMLID(ifaces[i])
+ text += " <link linkend=\"%s\">%s</link>" % (sid, ifaces[i])
+ if i < count - 2:
+ text += ', '
+ elif i < count - 1:
+ text += ' and '
+ else:
+ text += '.'
+ text += '</para>\n'
+ return text
+
+
+def GetImplementations(gobject):
+ """Generate interface usage graph.
+
+ Returns the DocBook output describing the implementations
+ of an interface. It uses the global Interfaces hash.
+
+ Args:
+ object (str): the GObject subclass.
+
+ Returns:
+ str: interface implementations
+ """
+ text = ''
+ impls = []
+ for key in Interfaces:
+ if re.search(r'\b%s\b' % gobject, Interfaces[key]):
+ impls.append(key)
+
+ count = len(impls)
+ if count > 0:
+ impls.sort()
+ text = '''<para>
+%s is implemented by
+''' % gobject
+ for i in range(count):
+ sid = common.CreateValidSGMLID(impls[i])
+ text += " <link linkend=\"%s\">%s</link>" % (sid, impls[i])
+ if i < count - 2:
+ text += ', '
+ elif i < count - 1:
+ text += ' and '
+ else:
+ text += '.'
+ text += '</para>\n'
+ return text
+
+
+def GetPrerequisites(iface):
+ """Generates interface requirements.
+
+ Returns the DocBook output describing the prerequisites
+ of an interface. It uses the global Prerequisites hash.
+ Args:
+ iface (str): the interface.
+
+ Returns:
+ str: required interfaces
+ """
+
+ text = ''
+ if iface in Prerequisites:
+ text = '''<para>
+%s requires
+''' % iface
+ prereqs = Prerequisites[iface].split()
+ count = len(prereqs)
+ for i in range(count):
+ sid = common.CreateValidSGMLID(prereqs[i])
+ text += " <link linkend=\"%s\">%s</link>" % (sid, prereqs[i])
+ if i < count - 2:
+ text += ', '
+ elif i < count - 1:
+ text += ' and '
+ else:
+ text += '.'
+ text += '</para>\n'
+ return text
+
+
+def GetDerived(iface):
+ """
+ Returns the DocBook output describing the derived interfaces
+ of an interface. It uses the global %Prerequisites hash.
+
+ Args:
+ iface (str): the interface.
+
+ Returns:
+ str: derived interfaces
+ """
+ text = ''
+ derived = []
+ for key in Prerequisites:
+ if re.search(r'\b%s\b' % iface, Prerequisites[key]):
+ derived.append(key)
+
+ count = len(derived)
+ if count > 0:
+ derived.sort()
+ text = '''<para>
+%s is required by
+''' % iface
+ for i in range(count):
+ sid = common.CreateValidSGMLID(derived[i])
+ text += " <link linkend=\"%s\">%s</link>" % (sid, derived[i])
+ if i < count - 2:
+ text += ', '
+ elif i < count - 1:
+ text += ' and '
+ else:
+ text += '.'
+ text += '</para>\n'
+ return text
+
+
+def GetSignals(gobject):
+ """Generate signal docs.
+
+ Returns the synopsis and detailed description DocBook output
+ for the signal handlers of a given GObject subclass.
+
+ Args:
+ object (str): the GObject subclass, e.g. 'GtkButton'.
+
+ Returns:
+ str: signal docs
+ """
+ synop = ''
+ desc = ''
+
+ for i in range(len(SignalObjects)):
+ if SignalObjects[i] == gobject:
+ logging.info("Found signal: %s", SignalNames[i])
+ name = SignalNames[i]
+ symbol = '%s::%s' % (gobject, name)
+ sid = common.CreateValidSGMLID('%s-%s' % (gobject, name))
+
+ desc += "<refsect2 id=\"%s\" role=\"signal\"><title>The <literal>“%s”</literal> signal</title>\n" % (
+ sid, name)
+ desc += MakeIndexterms(symbol, sid)
+ desc += "\n"
+ desc += OutputSymbolExtraLinks(symbol)
+
+ desc += "<programlisting language=\"C\">"
+
+ m = re.search(r'\s*(const\s+)?(\w+)\s*(\**)', SignalReturns[i])
+ type_modifier = m.group(1) or ''
+ gtype = m.group(2)
+ pointer = m.group(3)
+ xref = MakeXRef(gtype, tagify(gtype, "returnvalue"))
+
+ ret_type_output = '%s%s%s' % (type_modifier, xref, pointer)
+ callback_name = "user_function"
+ desc += '%s\n%s (' % (ret_type_output, callback_name)
+
+ indentation = ' ' * (len(callback_name) + 2)
+
+ sourceparams = SourceSymbolParams.get(symbol)
+ sourceparam_names = None
+ if sourceparams:
+ sourceparam_names = list(sourceparams) # keys as list
+ params = SignalPrototypes[i].splitlines()
+ type_len = len("gpointer")
+ name_len = len("user_data")
+ # do two passes, the first one is to calculate padding
+ for l in range(2):
+ for j in range(len(params)):
+ param_name = None
+ # allow alphanumerics, '_', '[' & ']' in param names
+ m = re.search(r'^\s*(\w+)\s*(\**)\s*([\w\[\]]+)\s*$', params[j])
+ if m:
+ gtype = m.group(1)
+ pointer = m.group(2)
+ if sourceparam_names:
+ if j < len(sourceparam_names):
+ param_name = sourceparam_names[j]
+ logging.info('from sourceparams: "%s" (%d: %s)', param_name, j, params[j])
+ # we're mssing the docs for this param, don't warn here though
+ else:
+ param_name = m.group(3)
+ logging.info('from params: "%s" (%d: %s)', param_name, j, params[j])
+
+ if not param_name:
+ param_name = "arg%d" % j
+
+ if l == 0:
+ if len(gtype) + len(pointer) > type_len:
+ type_len = len(gtype) + len(pointer)
+ if len(param_name) > name_len:
+ name_len = len(param_name)
+ else:
+ logging.info("signal arg[%d]: '%s'", j, param_name)
+ xref = MakeXRef(gtype, tagify(gtype, "type"))
+ pad = ' ' * (type_len - len(gtype) - len(pointer))
+ desc += '%s%s %s%s,\n' % (xref, pad, pointer, param_name)
+ desc += indentation
+
+ else:
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "Can't parse arg: %s\nArgs:%s" % (params[j], SignalPrototypes[i]))
+
+ xref = MakeXRef("gpointer", tagify("gpointer", "type"))
+ pad = ' ' * (type_len - len("gpointer"))
+ desc += '%s%s user_data)' % (xref, pad)
+ desc += "</programlisting>\n"
+
+ flags = SignalFlags[i]
+ flags_string = ''
+ if flags:
+ if 'f' in flags:
+ flags_string = "<link linkend=\"G-SIGNAL-RUN-FIRST:CAPS\">Run First</link>"
+
+ elif 'l' in flags:
+ flags_string = "<link linkend=\"G-SIGNAL-RUN-LAST:CAPS\">Run Last</link>"
+
+ elif 'c' in flags:
+ flags_string = "<link linkend=\"G-SIGNAL-RUN-CLEANUP:CAPS\">Cleanup</link>"
+ flags_string = "Cleanup"
+
+ if 'r' in flags:
+ if flags_string:
+ flags_string += " / "
+ flags_string = "<link linkend=\"G-SIGNAL-NO-RECURSE:CAPS\">No Recursion</link>"
+
+ if 'd' in flags:
+ if flags_string:
+ flags_string += " / "
+ flags_string = "<link linkend=\"G-SIGNAL-DETAILED:CAPS\">Has Details</link>"
+
+ if 'a' in flags:
+ if flags_string:
+ flags_string += " / "
+ flags_string = "<link linkend=\"G-SIGNAL-ACTION:CAPS\">Action</link>"
+
+ if 'h' in flags:
+ if flags_string:
+ flags_string += " / "
+ flags_string = "<link linkend=\"G-SIGNAL-NO-HOOKS:CAPS\">No Hooks</link>"
+
+ synop += "<row><entry role=\"signal_type\">%s</entry><entry role=\"signal_name\"><link linkend=\"%s\">%s</link></entry><entry role=\"signal_flags\">%s</entry></row>\n" % (
+ ret_type_output, sid, name, flags_string)
+
+ parameters = OutputParamDescriptions("SIGNAL", symbol, None)
+ logging.info("formatted signal params: '%s' -> '%s'", symbol, parameters)
+
+ AllSymbols[symbol] = 1
+ if symbol in SymbolDocs:
+ symbol_docs = ConvertMarkDown(symbol, SymbolDocs[symbol])
+
+ desc += symbol_docs
+
+ if not IsEmptyDoc(SymbolDocs[symbol]):
+ AllDocumentedSymbols[symbol] = 1
+
+ if symbol in SymbolAnnotations:
+ param_desc = SymbolAnnotations[symbol]
+ (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc)
+ if param_annotations != '':
+ desc += "\n<para>%s</para>" % param_annotations
+
+ desc += MakeDeprecationNote(symbol)
+
+ desc += parameters
+ if flags_string:
+ desc += "<para>Flags: %s</para>\n" % flags_string
+
+ desc += OutputSymbolTraits(symbol)
+ desc += "</refsect2>"
+
+ return (synop, desc)
+
+
+def GetArgs(gobject):
+ """Generate property docs.
+
+ Returns the synopsis and detailed description DocBook output
+ for the Args of a given GtkObject subclass.
+
+ Args:
+ object (str): the GObject subclass, e.g. 'GtkButton'.
+
+ Returns:
+ str: property docs
+ """
+ synop = ''
+ desc = ''
+ child_synop = ''
+ child_desc = ''
+ style_synop = ''
+ style_desc = ''
+
+ for i in range(len(ArgObjects)):
+ if ArgObjects[i] == gobject:
+ logging.info("Found arg: %s", ArgNames[i])
+ name = ArgNames[i]
+ flags = ArgFlags[i]
+ flags_string = ''
+ kind = ''
+ id_sep = ''
+
+ if 'c' in flags:
+ kind = "child property"
+ id_sep = "c-"
+ elif 's' in flags:
+ kind = "style property"
+ id_sep = "s-"
+ else:
+ kind = "property"
+
+ # Remember only one colon so we don't clash with signals.
+ symbol = '%s:%s' % (gobject, name)
+ # use two dashes and ev. an extra separator here for the same reason.
+ sid = common.CreateValidSGMLID('%s--%s%s' % (gobject, id_sep, name))
+
+ atype = ArgTypes[i]
+ type_output = None
+ arange = ArgRanges[i]
+ range_output = CreateValidSGML(arange)
+ default = ArgDefaults[i]
+ default_output = CreateValidSGML(default)
+
+ if atype == "GtkString":
+ atype = "char *"
+
+ if atype == "GtkSignal":
+ atype = "GtkSignalFunc, gpointer"
+ type_output = MakeXRef("GtkSignalFunc") + ", " + MakeXRef("gpointer")
+ elif re.search(r'^(\w+)\*$', atype):
+ m = re.search(r'^(\w+)\*$', atype)
+ type_output = MakeXRef(m.group(1), tagify(m.group(1), "type")) + " *"
+ else:
+ type_output = MakeXRef(atype, tagify(atype, "type"))
+
+ if 'r' in flags:
+ flags_string = "Read"
+
+ if 'w' in flags:
+ if flags_string:
+ flags_string += " / "
+ flags_string += "Write"
+
+ if 'x' in flags:
+ if flags_string:
+ flags_string += " / "
+ flags_string += "Construct"
+
+ if 'X' in flags:
+ if flags_string:
+ flags_string += " / "
+ flags_string += "Construct Only"
+
+ AllSymbols[symbol] = 1
+ blurb = ''
+ if symbol in SymbolDocs and not IsEmptyDoc(SymbolDocs[symbol]):
+ blurb = ConvertMarkDown(symbol, SymbolDocs[symbol])
+ logging.info(".. [%s][%s]", SymbolDocs[symbol], blurb)
+ AllDocumentedSymbols[symbol] = 1
+
+ else:
+ if ArgBlurbs[i] != '':
+ blurb = "<para>" + CreateValidSGML(ArgBlurbs[i]) + "</para>"
+ AllDocumentedSymbols[symbol] = 1
+ else:
+ # FIXME: print a warning?
+ logging.info(".. no description")
+
+ pad1 = ''
+ if len(name) < 24:
+ pad1 = " " * (24 - len(name))
+
+ arg_synop = "<row><entry role=\"property_type\">%s</entry><entry role=\"property_name\"><link linkend=\"%s\">%s</link></entry><entry role=\"property_flags\">%s</entry></row>\n" % (
+ type_output, sid, name, flags_string)
+ arg_desc = "<refsect2 id=\"%s\" role=\"property\"><title>The <literal>“%s”</literal> %s</title>\n" % (
+ sid, name, kind)
+ arg_desc += MakeIndexterms(symbol, sid)
+ arg_desc += "\n"
+ arg_desc += OutputSymbolExtraLinks(symbol)
+
+ arg_desc += "<programlisting> “%s”%s %s</programlisting>\n" % (name, pad1, type_output)
+ arg_desc += blurb
+ if symbol in SymbolAnnotations:
+ param_desc = SymbolAnnotations[symbol]
+ (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc)
+ if param_annotations != '':
+ arg_desc += "\n<para>%s</para>" % param_annotations
+
+ arg_desc += MakeDeprecationNote(symbol)
+
+ if flags_string:
+ arg_desc += "<para>Flags: %s</para>\n" % flags_string
+
+ if arange != '':
+ arg_desc += "<para>Allowed values: %s</para>\n" % range_output
+
+ if default != '':
+ arg_desc += "<para>Default value: %s</para>\n" % default_output
+
+ arg_desc += OutputSymbolTraits(symbol)
+ arg_desc += "</refsect2>\n"
+
+ if 'c' in flags:
+ child_synop += arg_synop
+ child_desc += arg_desc
+
+ elif 's' in flags:
+ style_synop += arg_synop
+ style_desc += arg_desc
+
+ else:
+ synop += arg_synop
+ desc += arg_desc
+
+ return (synop, child_synop, style_synop, desc, child_desc, style_desc)
+
+
+def IgnorePath(path, source_dirs, ignore_files):
+ for sdir in source_dirs:
+ # Cut off base directory
+ m1 = re.search(r'^%s/(.*)$' % re.escape(sdir), path)
+ if m1:
+ # Check if the filename is in the ignore list.
+ m2 = re.search(r'(\s|^)%s(\s|$)' % re.escape(m1.group(1)), ignore_files)
+ if m2:
+ logging.info("Skipping path: %s", path)
+ return True
+ else:
+ logging.info("No match for: %s", m1.group(1))
+ else:
+ logging.info("No match for: %s", path)
+ return False
+
+
+def ReadSourceDocumentation(source_dir, suffix_list, source_dirs, ignore_files):
+ """Read the documentation embedded in comment blocks in the source code.
+
+ It recursively descends the source directory looking for source files and
+ scans them looking for specially-formatted comment blocks.
+
+ Args:
+ source_dir (str): the directory to scan.
+ suffix_list (list): extensions to check
+ """
+ if IgnorePath(source_dir, source_dirs, ignore_files):
+ return
+
+ logging.info("Scanning source directory: %s", source_dir)
+
+ # This array holds any subdirectories found.
+ subdirs = []
+
+ for ifile in sorted(os.listdir(source_dir)):
+ logging.debug("... : %s", ifile)
+ if ifile.startswith('.'):
+ continue
+ fname = os.path.join(source_dir, ifile)
+ if os.path.isdir(fname):
+ subdirs.append(fname)
+ else:
+ for suffix in suffix_list:
+ if ifile.endswith(suffix):
+ if not IgnorePath(fname, source_dirs, ignore_files):
+ ScanSourceFile(fname, ignore_files)
+ break
+
+ # Now recursively scan the subdirectories.
+ for sdir in subdirs:
+ ReadSourceDocumentation(sdir, suffix_list, source_dirs, ignore_files)
+
+
+def ScanSourceFile(ifile, ignore_files):
+ """Scans one source file looking for specially-formatted comment blocks.
+
+ Later MergeSourceDocumentation() is copying over the doc blobs that are not
+ suppressed/ignored.
+
+ Args:
+ file (str): the file to scan.
+ """
+ m = re.search(r'^.*[\/\\]([^\/\\]*)$', ifile)
+ if m:
+ basename = m.group(1)
+ else:
+ common.LogWarning(ifile, 1, "Can't find basename for this filename.")
+ basename = ifile
+
+ # Check if the basename is in the list of files to ignore.
+ if re.search(r'(\s|^)%s(\s|$)' % re.escape(basename), ignore_files):
+ logging.info("Skipping source file: %s", ifile)
+ return
+
+ logging.info("Scanning source file: %s", ifile)
+
+ SRCFILE = open(ifile)
+ in_comment_block = False
+ symbol = None
+ in_part = ''
+ description = ''
+ return_desc = ''
+ since_desc = stability_desc = deprecated_desc = ''
+ params = OrderedDict()
+ param_name = None
+ line_number = 0
+ for line in SRCFILE:
+ line_number += 1
+ # Look for the start of a comment block.
+ if not in_comment_block:
+ if re.search(r'^\s*/\*.*\*/', line):
+ # one-line comment - not gtkdoc
+ pass
+ elif re.search(r'^\s*/\*\*\s', line):
+ logging.info("Found comment block start")
+
+ in_comment_block = True
+
+ # Reset all the symbol data.
+ symbol = ''
+ in_part = ''
+ description = ''
+ return_desc = ''
+ since_desc = ''
+ deprecated_desc = ''
+ stability_desc = ''
+ params = OrderedDict()
+ param_name = None
+
+ continue
+
+ # We're in a comment block. Check if we've found the end of it.
+ if re.search(r'^\s*\*+/', line):
+ if not symbol:
+ # maybe its not even meant to be a gtk-doc comment?
+ common.LogWarning(ifile, line_number, "Symbol name not found at the start of the comment block.")
+ else:
+ # Add the return value description onto the end of the params.
+ if return_desc:
+ # TODO(ensonic): check for duplicated Return docs
+ # common.LogWarning(file, line_number, "Multiple Returns for %s." % symbol)
+ params['Returns'] = return_desc
+
+ # Convert special characters
+ description = ConvertSGMLChars(symbol, description)
+ for (param_name, param_desc) in iteritems(params):
+ params[param_name] = ConvertSGMLChars(symbol, param_desc)
+
+ # Handle Section docs
+ m = re.search(r'SECTION:\s*(.*)', symbol)
+ m2 = re.search(r'PROGRAM:\s*(.*)', symbol)
+ if m:
+ real_symbol = m.group(1)
+ long_descr = real_symbol + ":Long_Description"
+
+ if long_descr not in KnownSymbols or KnownSymbols[long_descr] != 1:
+ common.LogWarning(
+ 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):
+ logging.info(" '" + param_name + "'")
+ param_name = param_name.lower()
+ key = None
+ if param_name == "short_description":
+ key = real_symbol + ":Short_Description"
+ elif param_name == "see_also":
+ key = real_symbol + ":See_Also"
+ elif param_name == "title":
+ key = real_symbol + ":Title"
+ elif param_name == "stability":
+ key = real_symbol + ":Stability_Level"
+ elif param_name == "section_id":
+ key = real_symbol + ":Section_Id"
+ elif param_name == "include":
+ key = real_symbol + ":Include"
+ elif param_name == "image":
+ key = real_symbol + ":Image"
+
+ if key:
+ SourceSymbolDocs[key] = param_desc
+ SourceSymbolSourceFile[key] = ifile
+ SourceSymbolSourceLine[key] = line_number
+
+ SourceSymbolDocs[long_descr] = description
+ SourceSymbolSourceFile[long_descr] = ifile
+ SourceSymbolSourceLine[long_descr] = line_number
+ elif m2:
+ real_symbol = m2.group(1)
+ key = None
+ section_id = None
+
+ logging.info("PROGRAM DOCS found in source for '%s'", real_symbol)
+ for param_name, param_desc in iteritems(params):
+ logging.info("PROGRAM key %s: '%s'", real_symbol, param_name)
+ param_name = param_name.lower()
+ key = None
+ if param_name == "short_description":
+ key = real_symbol + ":Short_Description"
+ elif param_name == "see_also":
+ key = real_symbol + ":See_Also"
+ elif param_name == "section_id":
+ key = real_symbol + ":Section_Id"
+ elif param_name == "synopsis":
+ key = real_symbol + ":Synopsis"
+ elif param_name == "returns":
+ key = real_symbol + ":Returns"
+ elif re.search(r'^(-.*)', param_name):
+ logging.info("PROGRAM opts: '%s': '%s'", param_name, param_desc)
+ key = real_symbol + ":Options"
+ opts = []
+ opts_str = SourceSymbolDocs.get(key)
+ if opts_str:
+ opts = opts_str.split('\t')
+ opts.append(param_name)
+ opts.append(param_desc)
+
+ logging.info("Setting options for symbol: %s: '%s'", real_symbol, '\t'.join(opts))
+ SourceSymbolDocs[key] = '\t'.join(opts)
+ continue
+
+ if key:
+ logging.info("PROGRAM value %s: '%s'", real_symbol, param_desc.rstrip())
+ SourceSymbolDocs[key] = param_desc.rstrip()
+ SourceSymbolSourceFile[key] = ifile
+ SourceSymbolSourceLine[key] = line_number
+
+ long_descr = real_symbol + ":Long_Description"
+ SourceSymbolDocs[long_descr] = description
+ SourceSymbolSourceFile[long_descr] = ifile
+ SourceSymbolSourceLine[long_descr] = line_number
+
+ section_id = SourceSymbolDocs.get(real_symbol + ":Section_Id")
+ if section_id and section_id.strip() != '':
+ # Remove trailing blanks and use as is
+ section_id = section_id.rstrip()
+ else:
+ section_id = common.CreateValidSGMLID('%s-%s' % (MODULE, real_symbol))
+ OutputProgramDBFile(real_symbol, section_id)
+
+ else:
+ logging.info("SYMBOL DOCS found in source for : '%s'", symbol)
+ SourceSymbolDocs[symbol] = description
+ SourceSymbolParams[symbol] = params
+ SourceSymbolSourceFile[symbol] = ifile
+ SourceSymbolSourceLine[symbol] = line_number
+
+ if since_desc:
+ arr = since_desc.splitlines()
+ since_desc = arr[0].strip()
+ extra_lines = arr[1:]
+ logging.info("Since(%s) : [%s]", symbol, since_desc)
+ Since[symbol] = ConvertSGMLChars(symbol, since_desc)
+ if len(extra_lines) > 1:
+ common.LogWarning(ifile, line_number, "multi-line since docs found")
+
+ if stability_desc:
+ stability_desc = ParseStabilityLevel(
+ stability_desc, ifile, line_number, "Stability level for %s" % symbol)
+ StabilityLevel[symbol] = ConvertSGMLChars(symbol, stability_desc)
+
+ if deprecated_desc:
+ if symbol not in Deprecated:
+ # don't warn for signals and properties
+ # if ($symbol !~ m/::?(.*)/)
+ if symbol in DeclarationTypes:
+ common.LogWarning(ifile, line_number,
+ "%s is deprecated in the inline comments, but no deprecation guards were found around the declaration. (See the --deprecated-guards option for gtkdoc-scan.)" % symbol)
+
+ Deprecated[symbol] = ConvertSGMLChars(symbol, deprecated_desc)
+
+ in_comment_block = False
+ continue
+
+ # Get rid of ' * ' at start of every line in the comment block.
+ line = re.sub(r'^\s*\*\s?', '', line)
+ # But make sure we don't get rid of the newline at the end.
+ if not line.endswith('\n'):
+ line = line + "\n"
+
+ logging.info("scanning :%s", line.strip())
+
+ # If we haven't found the symbol name yet, look for it.
+ if not symbol:
+ m1 = re.search(r'^\s*(SECTION:\s*\S+)', line)
+ m2 = re.search(r'^\s*(PROGRAM:\s*\S+)', line)
+ m3 = re.search(r'^\s*([\w:-]*\w)\s*:?\s*(\(.+?\)\s*)*$', line)
+ if m1:
+ symbol = m1.group(1)
+ logging.info("SECTION DOCS found in source for : '%s'", symbol)
+ elif m2:
+ symbol = m2.group(1)
+ logging.info("PROGRAM DOCS found in source for : '%s'", symbol)
+ elif m3:
+ symbol = m3.group(1)
+ annotation = m3.group(2)
+ logging.info("SYMBOL DOCS found in source for : '%s'", symbol)
+ if annotation:
+ annotation = annotation.strip()
+ if annotation != '':
+ SymbolAnnotations[symbol] = annotation
+ logging.info("remaining text for %s: '%s'", symbol, annotation)
+
+ continue
+
+ if in_part == "description":
+ # Get rid of 'Description:'
+ line = re.sub(r'^\s*Description:', '', line)
+
+ m1 = re.search(r'^\s*(returns|return\s+value):', line, flags=re.I)
+ m2 = re.search(r'^\s*since:', line, flags=re.I)
+ m3 = re.search(r'^\s*deprecated:', line, flags=re.I)
+ m4 = re.search(r'^\s*stability:', line, flags=re.I)
+
+ if m1:
+ # we're in param section and have not seen the blank line
+ if in_part != '':
+ return_desc = line[m1.end():]
+ in_part = "return"
+ continue
+
+ if m2:
+ # we're in param section and have not seen the blank line
+ if in_part != "param":
+ since_desc = line[m2.end():]
+ in_part = "since"
+ continue
+
+ elif m3:
+ # we're in param section and have not seen the blank line
+ if in_part != "param":
+ deprecated_desc = line[m3.end():]
+ in_part = "deprecated"
+ continue
+
+ elif m4:
+ stability_desc = line[m4.end():]
+ in_part = "stability"
+ continue
+
+ if in_part == "description":
+ description += line
+ continue
+ elif in_part == "return":
+ return_desc += line
+ continue
+ elif in_part == "since":
+ since_desc += line
+ continue
+ elif in_part == "stability":
+ stability_desc += line
+ continue
+ elif in_part == "deprecated":
+ deprecated_desc += line
+ continue
+
+ # We must be in the parameters. Check for the empty line below them.
+ if re.search(r'^\s*$', line):
+ in_part = "description"
+ continue
+
+ # Look for a parameter name.
+ m = re.search(r'^\s*@(.+?)\s*:\s*', line)
+ if m:
+ param_name = m.group(1)
+ param_desc = line[m.end():]
+
+ logging.info("Found parameter: %s", param_name)
+ # Allow varargs variations
+ if re.search(r'^\.\.\.$', param_name):
+ param_name = "..."
+
+ logging.info("Found param for symbol %s : '%s'= '%s'", symbol, param_name, line)
+
+ params[param_name] = param_desc
+ in_part = "param"
+ continue
+ elif in_part == '':
+ logging.info("continuation for %s annotation '%s'", symbol, line)
+ annotation = re.sub(r'^\s+|\s+$', '', line)
+ if symbol in SymbolAnnotations:
+ SymbolAnnotations[symbol] += annotation
+ else:
+ SymbolAnnotations[symbol] = annotation
+ continue
+
+ # We must be in the middle of a parameter description, so add it on
+ # to the last element in @params.
+ if not param_name:
+ common.LogWarning(file, line_number, "Parsing comment block file : parameter expected, but got '%s'" % line)
+ else:
+ params[param_name] += line
+
+ SRCFILE.close()
+
+
+def OutputMissingDocumentation():
+ """Outputs report of documentation coverage to a file.
+
+ Returns:
+ bool: True if the report was updated
+ """
+ old_undocumented_file = os.path.join(ROOT_DIR, MODULE + "-undocumented.txt")
+ new_undocumented_file = os.path.join(ROOT_DIR, MODULE + "-undocumented.new")
+
+ n_documented = 0
+ n_incomplete = 0
+ total = 0
+ symbol = None
+ percent = None
+ buffer = ''
+ buffer_deprecated = ''
+ buffer_descriptions = ''
+
+ UNDOCUMENTED = open(new_undocumented_file, 'w')
+
+ for symbol in sorted(iterkeys(AllSymbols)):
+ # FIXME: should we print common.LogWarnings for undocumented stuff?
+ # DEBUG
+ # location = "defined at " + GetSymbolSourceFile(symbol) + ":" + GetSymbolSourceLine(symbol) + "\n"
+ # DEBUG
+ m = re.search(
+ r':(Title|Long_Description|Short_Description|See_Also|Stability_Level|Include|Section_Id|Image)', symbol)
+ m2 = re.search(r':(Long_Description|Short_Description)', symbol)
+ if not m:
+ total += 1
+ if symbol in AllDocumentedSymbols:
+ n_documented += 1
+ if symbol in AllIncompleteSymbols:
+ n_incomplete += 1
+ buffer += symbol + " (" + AllIncompleteSymbols[symbol] + ")\n"
+ #$buffer += "\t0: ".$location
+
+ elif symbol in Deprecated:
+ if symbol in AllIncompleteSymbols:
+ n_incomplete += 1
+ buffer_deprecated += symbol + " (" + AllIncompleteSymbols[symbol] + ")\n"
+ #$buffer += "\t1a: ".$location
+ else:
+ buffer_deprecated += symbol + "\n"
+ #$buffer += "\t1b: ".$location
+
+ else:
+ if symbol in AllIncompleteSymbols:
+ n_incomplete += 1
+ buffer += symbol + " (" + AllIncompleteSymbols[symbol] + ")\n"
+ #$buffer += "\t2a: ".$location
+ else:
+ buffer += symbol + "\n"
+ #$buffer += "\t2b: ".$location
+
+ elif m2:
+ total += 1
+ if (symbol in SymbolDocs and len(SymbolDocs[symbol]) > 0)\
+ or (symbol in AllDocumentedSymbols and AllDocumentedSymbols[symbol] > 0):
+ n_documented += 1
+ else:
+ buffer_descriptions += symbol + "\n"
+
+ if total == 0:
+ percent = 100
+ else:
+ percent = (n_documented / total) * 100.0
+
+ UNDOCUMENTED.write("%.0f%% symbol docs coverage.\n" % percent)
+ UNDOCUMENTED.write("%s symbols documented.\n" % n_documented)
+ UNDOCUMENTED.write("%s symbols incomplete.\n" % n_incomplete)
+ UNDOCUMENTED.write("%d not documented.\n" % (total - n_documented))
+
+ if buffer_deprecated != '':
+ buffer += "\n" + buffer_deprecated
+
+ if buffer_descriptions != '':
+ buffer += "\n" + buffer_descriptions
+
+ if buffer != '':
+ UNDOCUMENTED.write("\n\n" + buffer)
+
+ UNDOCUMENTED.close()
+
+ return common.UpdateFileIfChanged(old_undocumented_file, new_undocumented_file, 0)
+
+
+def OutputUndeclaredSymbols():
+ """Reports undeclared symbols.
+
+ Outputs symbols that are listed in the section file, but have no declaration
+ in the sources.
+
+ Returns:
+ bool: True if the report was updated
+ """
+ old_undeclared_file = os.path.join(ROOT_DIR, MODULE + "-undeclared.txt")
+ new_undeclared_file = os.path.join(ROOT_DIR, MODULE + "-undeclared.new")
+
+ UNDECLARED = open(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()
+
+ return common.UpdateFileIfChanged(old_undeclared_file, new_undeclared_file, 0)
+
+
+def OutputUnusedSymbols():
+ """Reports unused documentation.
+
+ Outputs symbols that are documented in comments, but not declared in the
+ sources.
+
+ Returns:
+ bool: True if the report was updated
+ """
+ num_unused = 0
+ old_unused_file = os.path.join(ROOT_DIR, MODULE + "-unused.txt")
+ new_unused_file = os.path.join(ROOT_DIR, MODULE + "-unused.new")
+
+ UNUSED = open(new_unused_file, 'w')
+
+ for symbol in sorted(iterkeys(Declarations)):
+ if not symbol in DeclarationOutput:
+ UNUSED.write("%s\n" % symbol)
+ num_unused += 1
+
+ for symbol in sorted(iterkeys(AllUnusedSymbols)):
+ UNUSED.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))
+
+ return common.UpdateFileIfChanged(old_unused_file, new_unused_file, 0)
+
+
+def OutputAllSymbols():
+ """Outputs list of all symbols to a file."""
+ SYMBOLS = open(os.path.join(ROOT_DIR, MODULE + "-symbols.txt"), 'w')
+
+ for symbol in sorted(iterkeys(AllSymbols)):
+ SYMBOLS.write(symbol + "\n")
+ SYMBOLS.close()
+
+
+def OutputSymbolsWithoutSince():
+ """Outputs list of all symbols without a since tag to a file."""
+ SYMBOLS = open(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()
+
+
+def CheckParamsDocumented(symbol, params):
+ stype = DeclarationTypes.get(symbol)
+
+ item = "Parameter"
+ if stype:
+ if stype == 'STRUCT':
+ item = "Field"
+ elif stype == 'ENUM':
+ item = "Value"
+ elif stype == 'UNION':
+ item = "Field"
+ else:
+ stype = "SIGNAL"
+ logging.info("Check param docs for %s, params: %s entries, type=%s", symbol, len(params), stype)
+
+ if len(params) > 0:
+ logging.info("params: %s", str(params))
+ for (param_name, param_desc) in iteritems(params):
+ # 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:
+ AllIncompleteSymbols[symbol] += ", " + param_name
+ else:
+ AllIncompleteSymbols[symbol] = param_name
+
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "%s description for %s::%s is missing in source code comment block." % (item, symbol, param_name))
+
+ elif len(params) == 0:
+ AllIncompleteSymbols[symbol] = "<items>"
+ common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol),
+ "%s descriptions for %s are missing in source code comment block." % (item, symbol))
+
+
+def MergeSourceDocumentation():
+ """Merges documentation read from a source file.
+
+ Parameter descriptions override any in the template files.
+ Function descriptions are placed before any description from
+ the template files.
+ """
+
+ # add whats found in the source
+ symbols = set(iterkeys(SourceSymbolDocs))
+
+ # and add known symbols from -sections.txt
+ for symbol in iterkeys(KnownSymbols):
+ if KnownSymbols[symbol] == 1:
+ symbols.add(symbol)
+
+ logging.info("num source entries: %d", len(symbols))
+
+ for symbol in symbols:
+ AllSymbols[symbol] = 1
+
+ if symbol in SourceSymbolDocs:
+ logging.info("merging [%s] from source", symbol)
+
+ # remove leading and training whitespaces
+ src_docs = SourceSymbolDocs[symbol].strip()
+ if src_docs != '':
+ AllDocumentedSymbols[symbol] = 1
+
+ SymbolDocs[symbol] = src_docs
+
+ # merge parameters
+ if symbol in SourceSymbolParams:
+ param_docs = SourceSymbolParams[symbol]
+ SymbolParams[symbol] = param_docs
+ # if this symbol is documented, check if docs are complete
+ # remove all xml-tags and whitespaces
+ check_docs = re.sub(r'\s', '', re.sub(r'<.*?>', '', src_docs))
+ if check_docs != '' and param_docs:
+ CheckParamsDocumented(symbol, param_docs)
+ else:
+ logging.info("[%s] undocumented", symbol)
+
+ logging.info("num doc entries: %d", len(SymbolDocs))
+
+
+def IsEmptyDoc(doc):
+ """Check if a doc-string is empty.
+
+ It is also regarded as empty if it only consist of whitespace or e.g. FIXME.
+
+ Args:
+ doc (str): the doc-string
+
+ Returns:
+ bool: True if empty
+ """
+ if re.search(r'^\s*$', doc):
+ return True
+ if re.search(r'^\s*<para>\s*(FIXME)?\s*<\/para>\s*$', doc):
+ return True
+ return False
+
+
+def ConvertMarkDown(symbol, text):
+ md_to_db.Init()
+ return md_to_db.MarkDownParse(text, symbol)
+
+
+def ReadDeclarationsFile(ifile, override):
+ """Reads in a file containing the function/macro/enum etc. declarations.
+
+ Note that in some cases there are several declarations with
+ the same name, e.g. for conditional macros. In this case we
+ set a flag in the DeclarationConditional hash so the
+ declaration is not shown in the docs.
+
+ If a macro and a function have the same name, e.g. for
+ g_object_ref, the function declaration takes precedence.
+
+ Some opaque structs are just declared with 'typedef struct
+ _name name;' in which case the declaration may be empty.
+ The structure may have been found later in the header, so
+ that overrides the empty declaration.
+
+ Args:
+ file (str): the declarations file to read
+ override (bool): if declarations in this file should override
+ any current declaration.
+ """
+ if override == 0:
+ Declarations.clear()
+ DeclarationTypes.clear()
+ DeclarationConditional.clear()
+ DeclarationOutput.clear()
+
+ INPUT = open(ifile)
+ declaration_type = ''
+ declaration_name = None
+ declaration = None
+ is_deprecated = 0
+ line_number = 0
+ for line in INPUT:
+ line_number += 1
+ if not declaration_type:
+ m1 = re.search(r'^<([^>]+)>', line)
+ if m1:
+ declaration_type = m1.group(1)
+ declaration_name = ''
+ logging.info("Found declaration: %s", declaration_type)
+ declaration = ''
+ else:
+ m2 = re.search(r'^<NAME>(.*)</NAME>', line)
+ m3 = re.search(r'^<DEPRECATED/>', line)
+ m4 = re.search(r'^</%s>' % declaration_type, line)
+ if m2:
+ declaration_name = m2.group(1)
+ elif m3:
+ is_deprecated = True
+ elif m4:
+ logging.info("Found end of declaration: %s, %s", declaration_type, declaration_name)
+ # Check that the declaration has a name
+ if declaration_name == '':
+ common.LogWarning(ifile, line_number, declaration_type + " has no name.\n")
+
+ # If the declaration is an empty typedef struct _XXX XXX
+ # set the flag to indicate the struct has a typedef.
+ if (declaration_type == 'STRUCT' or declaration_type == 'UNION') \
+ and re.search(r'^\s*$', declaration):
+ logging.info("Struct has typedef: %s", declaration_name)
+ StructHasTypedef[declaration_name] = 1
+
+ # Check if the symbol is already defined.
+ if declaration_name in Declarations and override == 0:
+ # Function declarations take precedence.
+ if DeclarationTypes[declaration_name] == 'FUNCTION':
+ # Ignore it.
+ pass
+ elif declaration_type == 'FUNCTION':
+ if is_deprecated:
+ Deprecated[declaration_name] = ''
+
+ Declarations[declaration_name] = declaration
+ DeclarationTypes[declaration_name] = declaration_type
+ elif DeclarationTypes[declaration_name] == declaration_type:
+ # If the existing declaration is empty, or is just a
+ # forward declaration of a struct, override it.
+ if declaration_type == 'STRUCT' or declaration_type == 'UNION':
+ if re.search(r'^\s*((struct|union)\s+\w+\s*;)?\s*$', Declarations[declaration_name]):
+ if is_deprecated:
+ Deprecated[declaration_name] = ''
+ Declarations[declaration_name] = declaration
+ elif re.search(r'^\s*((struct|union)\s+\w+\s*;)?\s*$', declaration):
+ # Ignore an empty or forward declaration.
+ pass
+ else:
+ common.LogWarning(
+ ifile, line_number, "Structure %s has multiple definitions." % declaration_name)
+
+ else:
+ # set flag in %DeclarationConditional hash for
+ # multiply defined macros/typedefs.
+ DeclarationConditional[declaration_name] = 1
+
+ else:
+ common.LogWarning(ifile, line_number, declaration_name + " has multiple definitions.")
+
+ else:
+ if is_deprecated:
+ Deprecated[declaration_name] = ''
+
+ Declarations[declaration_name] = declaration
+ DeclarationTypes[declaration_name] = declaration_type
+ logging.debug("added declaration: %s, %s, [%s]", declaration_type, declaration_name, declaration)
+
+ declaration_type = ''
+ is_deprecated = False
+ else:
+ declaration += line
+ INPUT.close()
+
+
+def ReadSignalsFile(ifile):
+ """Reads information about object signals.
+
+ It creates the arrays @SignalNames and @SignalPrototypes containing details
+ about the signals. The first line of the SignalPrototype is the return type
+ of the signal handler. The remaining lines are the parameters passed to it.
+ The last parameter, "gpointer user_data" is always the same so is not included.
+
+ Args:
+ ifile (str): the file containing the signal handler prototype information.
+ """
+ in_signal = 0
+ signal_object = None
+ signal_name = None
+ signal_returns = None
+ signal_flags = None
+ signal_prototype = None
+
+ # Reset the signal info.
+ SignalObjects[:] = []
+ SignalNames[:] = []
+ SignalReturns[:] = []
+ SignalFlags[:] = []
+ SignalPrototypes[:] = []
+
+ if not os.path.isfile(ifile):
+ return
+
+ INPUT = open(ifile)
+ line_number = 0
+ for line in INPUT:
+ line_number += 1
+ if not in_signal:
+ if re.search(r'^<SIGNAL>', line):
+ in_signal = 1
+ signal_object = ''
+ signal_name = ''
+ signal_returns = ''
+ signal_prototype = ''
+
+ else:
+ m = re.search(r'^<NAME>(.*)<\/NAME>', line)
+ m2 = re.search(r'^<RETURNS>(.*)<\/RETURNS>', line)
+ m3 = re.search(r'^<FLAGS>(.*)<\/FLAGS>', line)
+ if m:
+ signal_name = m.group(1)
+ m1_2 = re.search(r'^(.*)::(.*)$', signal_name)
+ if m1_2:
+ signal_object = m1_2.group(1)
+ signal_name = m1_2.group(2).replace('_', '-')
+ logging.info("Found signal: %s", signal_name)
+ else:
+ common.LogWarning(ifile, line_number, "Invalid signal name: %s." % signal_name)
+
+ elif m2:
+ signal_returns = m2.group(1)
+ elif m3:
+ signal_flags = m3.group(1)
+ elif re.search(r'^</SIGNAL>', line):
+ logging.info("Found end of signal: %s::%s\nReturns: %s\n%s",
+ signal_object, signal_name, signal_returns, signal_prototype)
+ SignalObjects.append(signal_object)
+ SignalNames.append(signal_name)
+ SignalReturns.append(signal_returns)
+ SignalFlags.append(signal_flags)
+ SignalPrototypes.append(signal_prototype)
+ in_signal = False
+ else:
+ signal_prototype += line
+ INPUT.close()
+
+
+def ReadObjectHierarchy(ifile):
+ """Reads the $MODULE-hierarchy.txt file.
+
+ This contains all the GObject subclasses described in this module (and their
+ ancestors).
+ It places them in the Objects array, and places their level
+ in the object hierarchy in the ObjectLevels array, at the
+ same index. GObject, the root object, has a level of 1.
+
+ This also generates tree_index.sgml as it goes along.
+
+ Args:
+ ifile (str): the input filename.
+ """
+
+ Objects[:] = []
+ ObjectLevels[:] = []
+
+ if not os.path.isfile(ifile):
+ logging.debug('no *-hierarchy.tx')
+ return
+
+ INPUT = open(ifile)
+
+ # Only emit objects if they are supposed to be documented, or if
+ # they have documented children. To implement this, we maintain a
+ # stack of pending objects which will be emitted if a documented
+ # child turns up.
+ pending_objects = []
+ pending_levels = []
+ root = None
+ tree = []
+ for line in INPUT:
+ m1 = re.search(r'\S+', line)
+ if not m1:
+ continue
+
+ gobject = m1.group(0)
+ level = len(line[:m1.start()]) // 2 + 1
+
+ if level == 1:
+ root = gobject
+
+ while pending_levels and pending_levels[-1] >= level:
+ pending_objects.pop()
+ pending_levels.pop()
+
+ pending_objects.append(gobject)
+ pending_levels.append(level)
+
+ if gobject in KnownSymbols:
+ while len(pending_levels) > 0:
+ gobject = pending_objects.pop(0)
+ level = pending_levels.pop(0)
+ xref = MakeXRef(gobject)
+
+ tree.append(' ' * (level * 4) + xref)
+ Objects.append(gobject)
+ ObjectLevels.append(level)
+ ObjectRoots[gobject] = root
+ # else
+ # common.LogWarning(ifile, line_number, "unknown type %s" % object)
+ #
+
+ INPUT.close()
+
+ # FIXME: use xml
+ # my $old_tree_index = "$DB_OUTPUT_DIR/tree_index.$xml"
+ old_tree_index = os.path.join(DB_OUTPUT_DIR, "tree_index.sgml")
+ new_tree_index = os.path.join(DB_OUTPUT_DIR, "tree_index.new")
+
+ logging.debug('got %d entries for hierarchy', len(tree))
+
+ OUTPUT = open(new_tree_index, 'w')
+ OUTPUT.write(MakeDocHeader("screen") + "\n<screen>\n" + AddTreeLineArt(tree) + "\n</screen>\n")
+ OUTPUT.close()
+
+ common.UpdateFileIfChanged(old_tree_index, new_tree_index, 0)
+
+ OutputObjectList()
+
+
+def ReadInterfaces(ifile):
+ """Reads the $MODULE.interfaces file.
+
+ Args:
+ ifile (str): the input filename.
+ """
+
+ Interfaces.clear()
+
+ if not os.path.isfile(ifile):
+ return
+
+ INPUT = open(ifile)
+
+ for line in INPUT:
+ line = line.strip()
+ ifaces = line.split()
+ gobject = ifaces.pop(0)
+ if gobject in KnownSymbols and KnownSymbols[gobject] == 1:
+ knownIfaces = []
+
+ # filter out private interfaces, but leave foreign interfaces
+ for iface in ifaces:
+ if iface not in KnownSymbols or KnownSymbols[iface] == 1:
+ knownIfaces.append(iface)
+
+ Interfaces[gobject] = ' '.join(knownIfaces)
+ logging.info("Interfaces for %s: %s", gobject, Interfaces[gobject])
+ else:
+ logging.info("skipping interfaces for unknown symbol: %s", gobject)
+
+ INPUT.close()
+
+
+def ReadPrerequisites(ifile):
+ """This reads in the $MODULE.prerequisites file.
+
+ Args:
+ ifile (str): the input filename.
+ """
+ Prerequisites.clear()
+
+ if not os.path.isfile(ifile):
+ return
+
+ INPUT = open(ifile)
+
+ for line in INPUT:
+ line = line.strip()
+ prereqs = line.split()
+ iface = prereqs.pop(0)
+ if iface in KnownSymbols and KnownSymbols[iface] == 1:
+ knownPrereqs = []
+
+ # filter out private prerequisites, but leave foreign prerequisites
+ for prereq in prereqs:
+ if prereq not in KnownSymbols or KnownSymbols[prereq] == 1:
+ knownPrereqs.append(prereq)
+
+ Prerequisites[iface] = ' '.join(knownPrereqs)
+
+ INPUT.close()
+
+
+def ReadArgsFile(ifile):
+ """Reads information about object properties
+
+ It creates the arrays ArgObjects, ArgNames, ArgTypes, ArgFlags, ArgNicks and
+ ArgBlurbs containing info on the args.
+
+ Args:
+ ifile (str): the input filename.
+ """
+ in_arg = False
+ arg_object = None
+ arg_name = None
+ arg_type = None
+ arg_flags = None
+ arg_nick = None
+ arg_blurb = None
+ arg_default = None
+ arg_range = None
+
+ # Reset the args info.
+ ArgObjects[:] = []
+ ArgNames[:] = []
+ ArgTypes[:] = []
+ ArgFlags[:] = []
+ ArgNicks[:] = []
+ ArgBlurbs[:] = []
+ ArgDefaults[:] = []
+ ArgRanges[:] = []
+
+ if not os.path.isfile(ifile):
+ return
+
+ INPUT = open(ifile)
+ line_number = 0
+ for line in INPUT:
+ line_number += 1
+ if not in_arg:
+ if line.startswith('<ARG>'):
+ in_arg = True
+ arg_object = ''
+ arg_name = ''
+ arg_type = ''
+ arg_flags = ''
+ arg_nick = ''
+ arg_blurb = ''
+ arg_default = ''
+ arg_range = ''
+
+ else:
+ m1 = re.search(r'^<NAME>(.*)</NAME>', line)
+ m2 = re.search(r'^<TYPE>(.*)</TYPE>', line)
+ m3 = re.search(r'^<RANGE>(.*)</RANGE>', line)
+ m4 = re.search(r'^<FLAGS>(.*)</FLAGS>', line)
+ m5 = re.search(r'^<NICK>(.*)</NICK>', line)
+ m6 = re.search(r'^<BLURB>(.*)</BLURB>', line)
+ m7 = re.search(r'^<DEFAULT>(.*)</DEFAULT>', line)
+ if m1:
+ arg_name = m1.group(1)
+ m1_1 = re.search(r'^(.*)::(.*)$', arg_name)
+ if m1_1:
+ arg_object = m1_1.group(1)
+ arg_name = m1_1.group(2).replace('_', '-')
+ logging.info("Found arg: %s", arg_name)
+ else:
+ common.LogWarning(ifile, line_number, "Invalid argument name: " + arg_name)
+
+ elif m2:
+ arg_type = m2.group(1)
+ elif m3:
+ arg_range = m3.group(1)
+ elif m4:
+ arg_flags = m4.group(1)
+ elif m5:
+ arg_nick = m5.group(1)
+ elif m6:
+ arg_blurb = m6.group(1)
+ if arg_blurb == "(null)":
+ arg_blurb = ''
+ common.LogWarning(
+ ifile, line_number, "Property %s:%s has no documentation." % (arg_object, arg_name))
+
+ elif m7:
+ arg_default = m7.group(1)
+ elif re.search(r'^</ARG>', line):
+ logging.info("Found end of arg: %s::%s\n%s : %s", arg_object, arg_name, arg_type, arg_flags)
+ ArgObjects.append(arg_object)
+ ArgNames.append(arg_name)
+ ArgTypes.append(arg_type)
+ ArgRanges.append(arg_range)
+ ArgFlags.append(arg_flags)
+ ArgNicks.append(arg_nick)
+ ArgBlurbs.append(arg_blurb)
+ ArgDefaults.append(arg_default)
+ in_arg = False
+
+ INPUT.close()
+
+
+def AddTreeLineArt(tree):
+ """Generate a line art tree.
+
+ Add unicode lineart to a pre-indented string array and returns
+ it as as multiline string.
+
+ Args:
+ tree (list): of indented strings.
+
+ Returns:
+ str: multiline string with tree line art
+ """
+ # iterate bottom up over the tree
+ for i in range(len(tree) - 1, -1, -1):
+ # count leading spaces
+ m = re.search(r'^([^<A-Za-z]*)', tree[i])
+ indent = len(m.group(1))
+ # replace with ╰───, if place of ╰ is not space insert ├
+ if indent > 4:
+ if tree[i][indent - 4] == " ":
+ tree[i] = tree[i][:indent - 4] + "--- " + tree[i][indent:]
+ else:
+ tree[i] = tree[i][:indent - 4] + "+-- " + tree[i][indent:]
+
+ # go lines up while space and insert |
+ j = i - 1
+ while j >= 0 and tree[j][indent - 4] == ' ':
+ tree[j] = tree[j][:indent - 4] + '|' + tree[j][indent - 3:]
+ j -= 1
+
+ res = "\n".join(tree)
+ # unicode chars for: ╰──
+ res = re.sub(r'---', '<phrase role=\"lineart\">╰──</phrase>', res)
+ # unicde chars for: ├──
+ res = re.sub(r'\+--', '<phrase role=\"lineart\">├──</phrase>', res)
+ # unicode char for: │
+ res = re.sub(r'\|', '<phrase role=\"lineart\">│</phrase>', res)
+
+ return res
+
+
+def CheckIsObject(name):
+ """Check if symbols is an object.
+
+ It uses the global Objects array. Note that the Objects array only contains
+ classes in the current module and their ancestors - not all GObject classes.
+
+ Args:
+ name (str): the object name to check.
+
+ Returns:
+ bool: True if the given name is a GObject or a subclass.
+ """
+ root = ObjectRoots.get(name)
+ # Let GBoxed pass as an object here to get -struct appended to the id
+ # and prevent conflicts with sections.
+ return root and root != 'GEnum' and root != 'GFlags'
+
+
+def GetSymbolSourceFile(symbol):
+ """Get the filename where the symbol docs where taken from."""
+ return SourceSymbolSourceFile.get(symbol, '')
+
+
+def GetSymbolSourceLine(symbol):
+ """Get the file line where the symbol docs where taken from."""
+ return SourceSymbolSourceLine.get(symbol, 0)
--- /dev/null
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998 Owen Taylor
+# 2001-2005 Damon Chaplin
+# 2009-2017 Stefan Sauer
+# 2017 Jussi Pakkanen
+#
+# 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 os
+import sys
+import subprocess
+import shutil
+from glob import glob
+
+from . import config
+
+
+def run_xsltproc(options, args):
+ command = [config.xsltproc]
+ # we could do "$path_option $PWD " to avoid needing rewriting entities that
+ # are copied from the header into docs under xml
+ if os.environ.get("GTKDOC_PROFILE", '') == '':
+ for path in options.path:
+ command += ['--path', path]
+ return subprocess.call(command + args)
+ else:
+ command += ['--profile']
+ for path in options.path:
+ command += ['--path', path]
+ return subprocess.call(command + args, stderr=open('profile.txt', 'w'))
+
+
+def run(options):
+ module = options.args[0]
+ document = options.args[1]
+ if options.verbose:
+ quiet = '0'
+ else:
+ quiet = '1'
+ remaining_args = options.args[2:]
+
+ if options.uninstalled:
+ # this does not work from buiddir!=srcdir
+ gtkdocdir = os.path.split(sys.argv[0])[0]
+ if not os.path.exists(gtkdocdir + '/gtk-doc.xsl'):
+ # try to src dir (set from makefiles) too
+ if os.path.exists(os.environ.get("ABS_TOP_SRCDIR", '') + '/gtk-doc.xsl'):
+ gtkdocdir = os.environ['ABS_TOP_SRCDIR']
+ styledir = gtkdocdir + '/style'
+ else:
+ gtkdocdir = os.path.join(config.datadir, 'gtk-doc/data')
+ styledir = gtkdocdir
+
+ res = run_xsltproc(options, [
+ '--nonet',
+ '--xinclude',
+ '--stringparam',
+ 'gtkdoc.bookname',
+ module,
+ '--stringparam',
+ 'gtkdoc.version',
+ config.version,
+ '--stringparam',
+ 'chunk.quietly',
+ quiet,
+ '--stringparam',
+ 'chunker.output.quiet',
+ quiet] + remaining_args + [gtkdocdir + '/gtk-doc.xsl', document])
+
+ # profiling
+ if os.environ.get("GTKDOC_PROFILE", '') != '':
+ subprocess.check_call('cat profile.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o profile.png', shell=True)
+
+ # copy navigation images and stylesheets to html directory ...
+ for f in glob(styledir + '/*.png') + glob(styledir + '/*.css'):
+ shutil.copy(f, '.')
+
+ open('../html.stamp', 'w').write('timestamp')
+ return res
--- /dev/null
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998 Owen Taylor
+# 2001-2005 Damon Chaplin
+# 2009-2017 Stefan Sauer
+# 2017 Jussi Pakkanen
+#
+# 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 subprocess
+
+from . import config
+
+
+def run(options):
+ module = options.args[0]
+ document = options.args[1]
+ if options.verbose:
+ quiet = '0'
+ else:
+ quiet = '1'
+
+ # we could do "--path $PWD " to avoid needing rewriting entities that
+ # are copied from the header into docs under xml
+ path_arg = []
+ for path in options.path:
+ path_arg += ['--path', path]
+
+ # would it make sense to create man pages only for certain refentries
+ # e.g. for tools
+ # see http://bugzilla.gnome.org/show_bug.cgi?id=467488
+ return subprocess.call([config.xsltproc] + path_arg + [
+ '--nonet',
+ '--xinclude',
+ '--stringparam',
+ 'gtkdoc.bookname',
+ module,
+ '--stringparam',
+ 'gtkdoc.version',
+ config.version,
+ '--stringparam',
+ 'chunk.quietly ',
+ quiet,
+ '--stringparam',
+ 'chunker.output.quiet',
+ quiet,
+ 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl',
+ document])
--- /dev/null
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2009-2017 Stefan Sauer
+# 2017 Jussi Pakkanen
+#
+# 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.
+#
+
+# Support both Python 2 and 3
+from __future__ import print_function
+
+import os
+import sys
+import subprocess
+
+from . import config
+
+
+def run_xsltproc(options, args):
+ command = [config.xsltproc]
+ # we could do "--path $PWD " to avoid needing rewriting entities that are
+ # copied from the header into docs under xml
+ for path in options.path:
+ command += ['--path', path]
+ pc = subprocess.Popen(command + args, stderr=subprocess.PIPE)
+ (o, stde) = pc.communicate()
+ open('profile.txt', 'wb').write(stde)
+ return pc.returncode
+
+
+def run(options):
+ module = options.args[0]
+ document = options.args[1]
+
+ if options.uninstalled:
+ # this does not work from buiddir!=srcdir
+ # we could try this
+ # MAKE_SCRDIR=$(abs_srcdir) MAKE_BUILDDIR=$(abs_builddir) gtkdoc-mkpdf ...
+ gtkdocdir = os.path.split(sys.argv[0])[0]
+ else:
+ gtkdocdir = os.path.join(config.datadir, 'gtk-doc/data')
+
+ if config.dblatex != '':
+ # extra options to consider
+ # -I FIG_PATH
+ # -V is useful for debugging
+ # -T db2latex : different style
+ # -d : keep transient files (for debugging)
+ # -P abc.def=$quiet : once the stylesheets have a quiet mode
+ # xsltproc is already called with --xinclude
+ # does not work: --xslt-opts "--path $searchpath --nonet $@"
+ dblatex_options = ['-o', module + '.pdf']
+ for i in options.imgdir:
+ dblatex_options += ['-I', i]
+ dblatex_options.append(document)
+ if not options.verbose:
+ pc = subprocess.Popen([config.dblatex, '--help'], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ (stdo, stde) = pc.communicate()
+ if b'--quiet' in stdo or b'--quiet' in stde:
+ dblatex_options = ['--quiet'] + dblatex_options
+ dbcmd = [config.dblatex] + dblatex_options
+ pc = subprocess.Popen(dbcmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+ (stde, _) = pc.communicate()
+ for line in stde.decode('utf-8').split('\n'):
+ if not line.strip():
+ continue
+ if 'programlisting or screen' in line:
+ continue
+ # This happens when dblatex has no support for some special chars
+ if 'Missing character' in line:
+ continue
+ print(line)
+ res = pc.returncode
+ elif config.fop != '':
+ if options.verbose:
+ quiet = '0'
+ else:
+ quiet = '1'
+ res = run_xsltproc(options, ['--nonet',
+ '--xinclude',
+ '--stringparam',
+ 'gtkdoc.bookname',
+ module,
+ '--stringparam',
+ 'gtkdoc.version',
+ config.version,
+ '--stringparam',
+ 'chunk.quietly',
+ quiet,
+ '--stringparam',
+ 'chunker.output.quiet',
+ quiet,
+ module,
+ document,
+ '-o',
+ module + '.fo',
+ gtkdocdir + '/gtk-doc-fo.xsl',
+ document])
+ # TODO: fop dies too easily :(
+ # res = subprocess.call([config.fop, module + '.fo', module + '.pdf'))
+ fname = module + '.fo'
+ if os.path.exists(fname):
+ os.unlink(fname)
+ else:
+ print("dblatex or fop must be installed to use gtkdoc-mkpdf.")
+ res = 1
+
+ open('pdf.stamp', 'w').write('timestamp')
+ return res
--- /dev/null
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998 Damon Chaplin
+# 2007 David Necas (Yeti)
+# 2007-2016 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.
+#
+
+"""
+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
+
+from . import common
+
+# Maps.
+# These two point to the last seen URI of given type for a package:
+# OnlineMap: package => on-line URI
+# LocalMap: package => local URI
+# This maps all seen URIs of a package to fix broken links in the process:
+# RevMap: URI => package
+OnlineMap = {}
+LocalMap = {}
+RevMap = {}
+# Remember what mangling we did.
+Mapped = {}
+
+
+def log(options, *msg):
+ if options.verbose:
+ print(*msg)
+
+
+def run(options):
+ other_dirs = []
+
+ # We scan the directory containing GLib and any directories in GNOME2_PATH
+ # first, but these will be overriden by any later scans.
+ if "GNOME2_PATH" in os.environ:
+ for dir in os.environ["GNOME2_PATH"].split(':'):
+ dir = os.path.join(dir, "/share/gtk-doc/html")
+ if os.path.isdir(dir):
+ log(options, "Prepending GNOME2_PATH directory:", dir)
+ other_dirs = [dir] + other_dirs
+
+ dir = common.GetModuleDocDir('glib-2.0')
+ log(options, "Prepending GLib directory", dir)
+ other_dirs = [dir] + other_dirs
+
+ # Check all other dirs, but skip already scanned dirs ord subdirs of those
+
+ for dir in other_dirs:
+ ScanDirectory(dir, options)
+
+ if options.relative:
+ RelativizeLocalMap(options.html_dir, options)
+
+ RebaseReferences(options.html_dir, options)
+ PrintWhatWeHaveDone()
+
+
+def ScanDirectory(scan_dir, options):
+ log(options, "Scanning documentation directory %s", scan_dir)
+
+ if scan_dir == options.html_dir:
+ log(options, "Excluding self")
+ return
+
+ if not os.path.isdir(scan_dir):
+ logging.info('Cannot open dir "%s"', scan_dir)
+ return
+
+ subdirs = []
+ onlinedir = None
+ have_index = False
+ for entry in sorted(os.listdir(scan_dir)):
+ full_entry = os.path.join(scan_dir, entry)
+ if os.path.isdir(full_entry):
+ subdirs.append(full_entry)
+ continue
+
+ if entry.endswith('.devhelp2'):
+ log(options, "Reading index from " + entry)
+ o = ReadDevhelp(scan_dir, entry)
+ # Prefer this location over possibly stale index.sgml
+ if o is not None:
+ onlinedir = o
+ have_index = True
+
+ if onlinedir and entry == "index.sgml":
+ log(options, "Reading index from index.sgml")
+ onlinedir = ReadIndex(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 :/
+ print(''' Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138 . For now run:
+gunzip %s/%s
+''' % (scan_dir, entry))
+ elif entry.endswith('.devhelp2.gz') and not os.path.exists(full_entry[:-3]):
+ # debian/ubuntu started to compress this as *devhelp2.gz :/
+ print('''Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/1466210 . For now run:
+gunzip %d/%s
+''' % (scan_dir, entry))
+ # we could consider supporting: gzip module
+
+ if have_index:
+ AddMap(scan_dir, onlinedir, options)
+
+ # Now recursively scan the subdirectories.
+ for subdir in subdirs:
+ ScanDirectory(subdir, options)
+
+
+def ReadDevhelp(dir, file):
+ onlinedir = None
+
+ for line in open(os.path.join(dir, file)):
+ # online must come before chapter/functions
+ if '<chapters' in line or '<functions' in line:
+ break
+ match = re.search(r' online="([^"]*)"/', line)
+ if match:
+ # Remove trailing non-directory component.
+ onlinedir = re.sub(r'(.*/).*', r'\1', match.groups(1))
+ return onlinedir
+
+
+def ReadIndex(dir, file):
+ onlinedir = None
+
+ for line in open(os.path.join(dir, file)):
+ # 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))
+ return onlinedir
+
+
+def AddMap(dir, onlinedir, options):
+ package = None
+
+ package = os.path.split(dir)[1]
+ if options.dest_dir != '' and dir.startswith(options.dest_dir):
+ dir = dir[len(options.dest_dir) - 1:]
+
+ if onlinedir:
+ log(options, "On-line location of %s." % onlinedir)
+ OnlineMap[package] = onlinedir
+ RevMap[onlinedir] = package
+ else:
+ log(options, "No On-line location for %s found" % package)
+
+ log(options, "Local location of $package: " + dir)
+ LocalMap[package] = dir
+ RevMap[dir] = package
+
+
+def RelativizeLocalMap(dirname, options):
+ prefix = None
+ dir = None
+
+ dirname = os.path.realpath(dirname)
+ prefix = os.path.split(dirname)
+ for package, dir in LocalMap.items():
+ if dir.startswith(prefix):
+ dir = os.path.join("..", dir[len(prefix):])
+ LocalMap[package] = dir
+ log(options, "Relativizing local location of $package to " + dir)
+
+
+def RebaseReferences(dirname, options):
+ for ifile in sorted(os.listdir(dirname)):
+ if ifile.endswith('.html'):
+ RebaseFile(os.path.join(dirname, ifile), options)
+
+
+def RebaseFile(filename, options):
+ log(options, "Fixing file: " + filename)
+ regex = re.compile(r'''(<a(?:\s+\w+=(?:"[^"]*"|'[^']*'))*\s+href=")([^"]*)(")''',
+ flags=re.MULTILINE)
+
+ def repl_func(match):
+ return match.group(1) + RebaseLink(match.group(2), options) + match.group(3)
+
+ contents = open(filename).read()
+ processed = re.sub(regex, repl_func, contents)
+ newfilename = filename + '.new'
+ open(newfilename, 'w').write(processed)
+ os.unlink(filename)
+ os.rename(newfilename, filename)
+
+
+def RebaseLink(href, options):
+ match = re.match(r'^(.*/)([^/]*)$', href)
+ package = None
+ origdir = 'INVALID'
+
+ if match:
+ dir = origdir = match.group(1)
+ file = match.group(2)
+ if dir in RevMap:
+ package = RevMap[dir]
+ else:
+ match = re.match(r'\.\./([^/]+)', href)
+ if match is not None:
+ package = match.groups(1)
+ elif options.aggressive:
+ match = re.search(r'''([^/]+)/$''', href)
+ package = match.groups(1)
+
+ if package:
+ if options.online and package in OnlineMap:
+ dir = OnlineMap[package]
+ elif package in LocalMap:
+ dir = LocalMap[package]
+ href = os.path.join(dir, file)
+ else:
+ log(options, "Can't determine package for '%s'" % href)
+
+ if dir != origdir:
+ if origdir in Mapped:
+ Mapped[origdir][1] += 1
+ else:
+ Mapped[origdir] = [dir, 1]
+ return href
+
+
+def PrintWhatWeHaveDone():
+ for origdir in sorted(iterkeys(Mapped)):
+ info = Mapped[origdir]
+ print(origdir, "->", info[0], "(%s)" % info[1])
--- /dev/null
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998 Damon Chaplin
+# 2007-2016 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.
+#
+
+"""
+Extracts declarations of functions, macros, enums, structs and unions from
+header files.
+
+It is called with a module name, an optional source directory, an optional
+output directory, and the header files to scan.
+
+It outputs all declarations found to a file named '$MODULE-decl.txt', and the
+list of decarations to another file '$MODULE-decl-list.txt'.
+
+This second list file is typically copied to '$MODULE-sections.txt' and
+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
+import shutil
+
+from . import common
+
+# do not read files twice; checking it here permits to give both srcdir and
+# builddir as --source-dir without fear of duplicities
+seen_headers = {}
+
+
+def Run(options):
+ # logging.basicConfig(level=logging.INFO)
+
+ if not os.path.isdir(options.output_dir):
+ os.mkdir(options.output_dir)
+
+ base_filename = os.path.join(options.output_dir, options.module)
+ old_decl_list = base_filename + '-decl-list.txt'
+ new_decl_list = base_filename + '-decl-list.new'
+ old_decl = base_filename + '-decl.txt'
+ new_decl = base_filename + '-decl.new'
+ old_types = base_filename + '.types'
+ new_types = base_filename + '.types.new'
+ sections_file = base_filename + '-sections.txt'
+
+ # If this is the very first run then we create the .types file automatically.
+ if not os.path.exists(sections_file) and not os.path.exists(old_types):
+ options.rebuild_types = True
+
+ section_list = {}
+ decl_list = []
+ get_types = []
+
+ for file in options.headers:
+ ScanHeader(file, section_list, decl_list, get_types, options)
+
+ for dir in options.source_dir:
+ ScanHeaders(dir, section_list, decl_list, get_types, options)
+
+ with open(new_decl_list, 'w') as f:
+ for section in sorted(iterkeys(section_list)):
+ f.write(section_list[section])
+
+ with open(new_decl, 'w') as f:
+ for decl in decl_list:
+ f.write(decl)
+
+ if options.rebuild_types:
+ with open(new_types, 'w') as f:
+ for func in sorted(get_types):
+ f.write(func + '\n')
+
+ # remove the file if empty
+ if len(get_types) == 0:
+ os.unlink(new_types)
+ if os.path.exists(old_types):
+ os.rename(old_types, old_types + '.bak')
+ else:
+ common.UpdateFileIfChanged(old_types, new_types, True)
+
+ common.UpdateFileIfChanged(old_decl_list, new_decl_list, True)
+ common.UpdateFileIfChanged(old_decl, new_decl, True)
+
+ # If there is no MODULE-sections.txt file yet or we are asked to rebuild it,
+ # we copy the MODULE-decl-list.txt file into its place. The user can tweak it
+ # later if they want.
+ if options.rebuild_sections or not os.path.exists(sections_file):
+ new_sections_file = base_filename + '-sections.new'
+ shutil.copyfile(old_decl_list, new_sections_file)
+ common.UpdateFileIfChanged(sections_file, new_sections_file, False)
+
+ # If there is no MODULE-overrides.txt file we create an empty one
+ # 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()
+
+
+#
+# Function : ScanHeaders
+# Description : This scans a directory tree looking for header files.
+#
+# Arguments : $source_dir - the directory to scan.
+# $section_list - a reference to the hashmap of sections.
+#
+
+def ScanHeaders(source_dir, section_list, decl_list, get_types, options):
+ logging.info('Scanning source directory: %s', source_dir)
+
+ # This array holds any subdirectories found.
+ subdirs = []
+
+ for file in sorted(os.listdir(source_dir)):
+ if file.startswith('.'):
+ continue
+ fullname = os.path.join(source_dir, file)
+ if os.path.isdir(fullname):
+ subdirs.append(file)
+ elif file.endswith('.h'):
+ ScanHeader(fullname, section_list, decl_list, get_types, options)
+
+ # Now recursively scan the subdirectories.
+ for dir in subdirs:
+ matchstr = r'(\s|^)' + re.escape(dir) + r'(\s|$)'
+ if re.search(matchstr, options.ignore_headers):
+ continue
+ ScanHeaders(os.path.join(source_dir, dir), section_list, decl_list,
+ get_types, options)
+
+
+#
+# Function : ScanHeader
+# Description : This scans a header file, looking for declarations of
+# functions, macros, typedefs, structs and unions, which it
+# outputs to the decl_list.
+# Arguments : $input_file - the header file to scan.
+# $section_list - a map of sections.
+# $decl_list - a list of declarations
+# Returns : it adds declarations to the appropriate list.
+#
+
+def ScanHeader(input_file, section_list, decl_list, get_types, options):
+ global seen_headers
+ slist = [] # Holds the resulting list of declarations.
+ title = '' # Holds the title of the section
+ in_comment = 0 # True if we are in a comment.
+ in_declaration = '' # The type of declaration we are in, e.g.
+ # 'function' or 'macro'.
+ skip_block = 0 # True if we should skip a block.
+ symbol = None # The current symbol being declared.
+ decl = '' # Holds the declaration of the current symbol.
+ ret_type = None # For functions and function typedefs this
+ # holds the function's return type.
+ pre_previous_line = '' # The pre-previous line read in - some Gnome
+ # functions have the return type on one
+ # line, the function name on the next,
+ # and the rest of the declaration after.
+ previous_line = '' # The previous line read in - some Gnome
+ # functions have the return type on one line
+ # and the rest of the declaration after.
+ first_macro = 1 # Used to try to skip the standard #ifdef XXX
+ # define XXX at the start of headers.
+ level = None # Used to handle structs/unions which contain
+ # nested structs or unions.
+ internal = 0 # Set to 1 for internal symbols, we need to
+ # fully parse, but don't add them to docs
+ forward_decls = {} # Dict of forward declarations, we skip
+ # them if we find the real declaration
+ # later.
+ doc_comments = {} # Dict of doc-comments we found.
+ # The key is lowercase symbol name, val=1.
+
+ file_basename = None
+
+ deprecated_conditional_nest = 0
+ ignore_conditional_nest = 0
+
+ deprecated = ''
+ doc_comment = ''
+
+ # Don't scan headers twice
+ canonical_input_file = os.path.realpath(input_file)
+ if canonical_input_file in seen_headers:
+ logging.info('File already scanned: %s', input_file)
+ return
+
+ seen_headers[canonical_input_file] = 1
+
+ file_basename = os.path.split(input_file)[1][:-2] # filename ends in .h
+
+ # Check if the basename is in the list of headers to ignore.
+ matchstr = r'(\s|^)' + re.escape(file_basename) + r'\.h(\s|$)'
+ if re.search(matchstr, options.ignore_headers):
+ logging.info('File ignored: %s', input_file)
+ return
+
+ # Check if the full name is in the list of headers to ignore.
+ matchstr = r'(\s|^)' + re.escape(input_file) + r'(\s|$)'
+ if re.search(matchstr, options.ignore_headers):
+ logging.info('File ignored: %s', input_file)
+ return
+
+ if not os.path.exists(input_file):
+ logging.warning('File does not exist: %s', input_file)
+ return
+
+ logging.info('Scanning %s', input_file)
+
+ for line in open(input_file):
+ # If this is a private header, skip it.
+ if re.search(r'%^\s*/\*\s*<\s*private_header\s*>\s*\*/', line):
+ return
+
+ # Skip to the end of the current comment.
+ if in_comment:
+ logging.info('Comment: %s', line.strip())
+ doc_comment += line
+ if re.search(r'\*/', line):
+ m = re.search(r'\* ([a-zA-Z][a-zA-Z0-9_]+):', doc_comment)
+ if m:
+ doc_comments[m.group(1).lower()] = 1
+ in_comment = 0
+ doc_comment = ''
+ continue
+
+ # Keep a count of #if, #ifdef, #ifndef nesting,
+ # and if we enter a deprecation-symbol-bracketed
+ # zone, take note.
+ m = re.search(r'^\s*#\s*if(?:n?def\b|\s+!?\s*defined\s*\()\s*(\w+)', line)
+ if m:
+ define_name = m.group(1)
+ if deprecated_conditional_nest < 1 and re.search(options.deprecated_guards, define_name):
+ deprecated_conditional_nest = 1
+ elif deprecated_conditional_nest >= 1:
+ deprecated_conditional_nest += 1
+ if ignore_conditional_nest == 0 and '__GTK_DOC_IGNORE__' in define_name:
+ ignore_conditional_nest = 1
+ elif ignore_conditional_nest > 0:
+ ignore_conditional_nest = 1
+
+ elif re.search(r'^\s*#\sif', line):
+ if deprecated_conditional_nest >= 1:
+ deprecated_conditional_nest += 1
+
+ if ignore_conditional_nest > 0:
+ ignore_conditional_nest += 1
+ elif re.search(r'^\s*#endif', line):
+ if deprecated_conditional_nest >= 1:
+ deprecated_conditional_nest -= 1
+
+ if ignore_conditional_nest > 0:
+ ignore_conditional_nest -= 1
+
+ # If we find a line containing _DEPRECATED, we hope that this is
+ # attribute based deprecation and also treat this as a deprecation
+ # guard, unless it's a macro definition.
+ if deprecated_conditional_nest == 0 and '_DEPRECATED' in line:
+ m = re.search(r'^\s*#\s*(if*|define)', line)
+ if not (m or in_declaration == 'enum'):
+ logging.info('Found deprecation annotation (decl: "%s"): "%s"',
+ in_declaration, line.strip())
+ deprecated_conditional_nest += 0.1
+
+ # set flag that is used later when we do AddSymbolToList
+ if deprecated_conditional_nest > 0:
+ deprecated = '<DEPRECATED/>\n'
+ else:
+ deprecated = ''
+
+ if ignore_conditional_nest:
+ continue
+
+ if not in_declaration:
+ # Skip top-level comments.
+ m = re.search(r'^\s*/\*', line)
+ if m:
+ re.sub(r'^\s*/\*', '', line)
+ if re.search(r'\*/', line):
+ logging.info('Found one-line comment: %s', line.strip())
+ else:
+ in_comment = 1
+ doc_comment = line
+ logging.info('Found start of comment: %s', line.strip())
+ continue
+
+ logging.info('no decl: %s', line.strip())
+
+ # avoid generating regex with |'' (matching no string)
+ ignore_decorators = ''
+ if options.ignore_decorators:
+ ignore_decorators = '|' + options.ignore_decorators
+
+ m = re.search(r'^\s*#\s*define\s+(\w+)', line)
+ # $1 $3 $4 $5
+ m2 = re.search(
+ r'^\s*typedef\s+((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(', line)
+ # $1 $3 $4 $5
+ m3 = re.search(r'^\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(', line)
+ # $1 $2
+ m4 = re.search(r'^\s*(\**)\s*\(\*\s*(\w+)\)\s*\(', line)
+ # $1 $3
+ m5 = re.search(r'^\s*typedef\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*', previous_line)
+ # $1 $3 $4 $5
+ m6 = re.search(
+ r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(' % ignore_decorators, line)
+ m7 = re.search(r'^\s*enum\s+_?(\w+)\s+\{', line)
+ m8 = re.search(r'^\s*typedef\s+enum', line)
+ m9 = re.search(r'^\s*typedef\s+(struct|union)\s+_(\w+)\s+\2\s*;', line)
+ m10 = re.search(r'^\s*(struct|union)\s+(\w+)\s*;', line)
+ m11 = re.search(r'^\s*typedef\s+(struct|union)\s*\w*\s*{', line)
+ m12 = re.search(r'^\s*typedef\s+(?:struct|union)\s+\w+[\s\*]+(\w+)\s*;', line)
+ m13 = re.search(r'^\s*(G_GNUC_EXTENSION\s+)?typedef\s+(.+[\s\*])(\w+)(\s*\[[^\]]+\])*\s*;', line)
+ m14 = re.search(
+ r'^\s*(extern|[A-Za-z_]+VAR%s)\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*;' % ignore_decorators, line)
+ m15 = re.search(
+ r'^\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*\=', line)
+ m16 = re.search(r'.*G_DECLARE_(FINAL_TYPE|DERIVABLE_TYPE|INTERFACE)\s*\(', line)
+ # $1 $2 $3
+ m17 = re.search(
+ r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)([\s*]+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*(_[A-Za-z]\w*)\s*\(' % ignore_decorators, line)
+ # $1 $2 $3
+ m18 = re.search(
+ r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)([\s*]+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*([A-Za-z]\w*)\s*\(' % ignore_decorators, line)
+ m19 = re.search(r'^\s*([A-Za-z]\w*)\s*\(', line)
+ m20 = re.search(r'^\s*\(', line)
+ m21 = re.search(r'^\s*struct\s+_?(\w+)', line)
+ m22 = re.search(r'^\s*union\s+_(\w+)', line)
+
+ # MACROS
+
+ if m:
+ symbol = m.group(1)
+ decl = line
+ # We assume all macros which start with '_' are private.
+ # We also try to skip the first macro if it looks like the
+ # standard #ifndef HEADER_FILE #define HEADER_FILE etc.
+ # And we only want TRUE & FALSE defined in GLib.
+ if not symbol.startswith('_') \
+ and (not re.search(r'#ifndef\s+' + symbol, previous_line)
+ or first_macro == 0) \
+ and ((symbol != 'TRUE' and symbol != 'FALSE')
+ or options.module == 'glib'):
+ in_declaration = 'macro'
+ logging.info('Macro: "%s"', symbol)
+ else:
+ logging.info('skipping Macro: "%s"', symbol)
+ in_declaration = 'macro'
+ internal = 1
+ first_macro = 0
+
+ # TYPEDEF'D FUNCTIONS (i.e. user functions)
+ elif m2:
+ p3 = m2.group(3) or ''
+ ret_type = "%s%s %s" % (m2.group(1), p3, m2.group(4))
+ symbol = m2.group(5)
+ decl = line[m2.end():]
+ in_declaration = 'user_function'
+ logging.info('user function (1): "%s", Returns: "%s"', symbol, ret_type)
+
+ elif re.search(r'^\s*typedef\s*', previous_line) and m3:
+ p3 = m3.group(3) or ''
+ ret_type = '%s%s %s' % (m3.group(1), p3, m3.group(4))
+ symbol = m3.group(5)
+ decl = line[m3.end():]
+ in_declaration = 'user_function'
+ logging.info('user function (2): "%s", Returns: "%s"', symbol, ret_type)
+
+ elif re.search(r'^\s*typedef\s*', previous_line) and m4:
+ ret_type = m4.group(1)
+ symbol = m4.group(2)
+ decl = line[m4.end():]
+ if m5:
+ p3 = m5.group(3) or ''
+ ret_type = "%s%s %s" % (m5.group(1), p3, ret_type)
+ in_declaration = 'user_function'
+ logging.info('user function (3): "%s", Returns: "%s"', symbol, ret_type)
+
+ # FUNCTION POINTER VARIABLES
+ elif m6:
+ p3 = m6.group(3) or ''
+ ret_type = '%s%s %s' % (m6.group(1), p3, m6.group(4))
+ symbol = m6.group(5)
+ decl = line[m6.end():]
+ in_declaration = 'user_function'
+ logging.info('function pointer variable: "%s", Returns: "%s"', symbol, ret_type)
+
+ # ENUMS
+
+ elif m7:
+ re.sub(r'^\s*enum\s+_?(\w+)\s+\{', r'enum \1 {', line)
+ # We assume that 'enum _<enum_name> {' is really the
+ # declaration of enum <enum_name>.
+ symbol = m7.group(1)
+ decl = line
+ in_declaration = 'enum'
+ logging.info('plain enum: "%s"', symbol)
+
+ elif re.search(r'^\s*typedef\s+enum\s+_?(\w+)\s+\1\s*;', line):
+ # We skip 'typedef enum <enum_name> _<enum_name>;' as the enum will
+ # be declared elsewhere.
+ logging.info('skipping enum typedef: "%s"', line)
+ elif m8:
+ symbol = ''
+ decl = line
+ in_declaration = 'enum'
+ logging.info('typedef enum: -')
+
+ # STRUCTS AND UNIONS
+
+ elif m9:
+ # We've found a 'typedef struct _<name> <name>;'
+ # This could be an opaque data structure, so we output an
+ # empty declaration. If the structure is actually found that
+ # will override this.
+ structsym = m9.group(1).upper()
+ logging.info('%s typedef: "%s"', structsym, m9.group(2))
+ forward_decls[m9.group(2)] = '<%s>\n<NAME>%s</NAME>\n%s</%s>\n' % (
+ structsym, m9.group(2), deprecated, structsym)
+
+ elif re.search(r'^\s*(?:struct|union)\s+_(\w+)\s*;', line):
+ # Skip private structs/unions.
+ logging.info('private struct/union')
+
+ elif m10:
+ # Do a similar thing for normal structs as for typedefs above.
+ # But we output the declaration as well in this case, so we
+ # can differentiate it from a typedef.
+ structsym = m10.group(1).upper()
+ logging.info('%s:%s', structsym, m10.group(2))
+ forward_decls[m10.group(2)] = '<%s>\n<NAME>%s</NAME>\n%s%s</%s>\n' % (
+ structsym, m10.group(2), line, deprecated, structsym)
+
+ elif m11:
+ symbol = ''
+ decl = line
+ level = 0
+ in_declaration = m11.group(1)
+ logging.info('typedef struct/union "%s"', in_declaration)
+
+ # OTHER TYPEDEFS
+
+ elif m12:
+ logging.info('Found struct/union(*) typedef "%s": "%s"', m12.group(1), line)
+ if AddSymbolToList(slist, m12.group(1)):
+ decl_list.append('<TYPEDEF>\n<NAME>%s</NAME>\n%s%s</TYPEDEF>\n' % (m12.group(1), deprecated, line))
+
+ elif m13:
+ if m13.group(2).split()[0] not in ('struct', 'union'):
+ logging.info('Found typedef: "%s"', line)
+ if AddSymbolToList(slist, m13.group(3)):
+ decl_list.append(
+ '<TYPEDEF>\n<NAME>%s</NAME>\n%s%s</TYPEDEF>\n' % (m13.group(3), deprecated, line))
+ elif re.search(r'^\s*typedef\s+', line):
+ logging.info('Skipping typedef: "%s"', line)
+
+ # VARIABLES (extern'ed variables)
+
+ elif m14:
+ symbol = m14.group(6)
+ line = re.sub(r'^\s*([A-Za-z_]+VAR)\b', r'extern', line)
+ decl = line
+ logging.info('Possible extern var "%s": "%s"', symbol, decl)
+ if AddSymbolToList(slist, symbol):
+ decl_list.append('<VARIABLE>\n<NAME>%s</NAME>\n%s%s</VARIABLE>\n' % (symbol, deprecated, decl))
+
+ # VARIABLES
+
+ elif m15:
+ symbol = m15.group(5)
+ decl = line
+ logging.info('Possible global var" %s": "%s"', symbol, decl)
+ if AddSymbolToList(slist, symbol):
+ decl_list.append('<VARIABLE>\n<NAME>%s</NAME>\n%s%s</VARIABLE>\n' % (symbol, deprecated, decl))
+
+ # G_DECLARE_*
+
+ elif m16:
+ in_declaration = 'g-declare'
+ symbol = 'G_DECLARE_' + m16.group(1)
+ decl = line[m16.end():]
+
+ # FUNCTIONS
+
+ # We assume that functions which start with '_' are private, so
+ # we skip them.
+ elif m17:
+ ret_type = m17.group(1)
+ if m17.group(2):
+ ret_type += ' ' + m17.group(2)
+ symbol = m17.group(3)
+ decl = line[m17.end():]
+ logging.info('internal Function: "%s", Returns: "%s""%s"', symbol, m17.group(1), m17.group(2))
+ in_declaration = 'function'
+ internal = 1
+ if line.strip().startswith('G_INLINE_FUNC'):
+ logging.info('skip block after inline function')
+ # now we we need to skip a whole { } block
+ skip_block = 1
+
+ elif m18:
+ ret_type = m18.group(1)
+ if m18.group(2):
+ ret_type += ' ' + m18.group(2)
+ symbol = m18.group(3)
+ decl = line[m18.end():]
+ logging.info('Function (1): "%s", Returns: "%s""%s"', symbol, m18.group(1), m18.group(2))
+ in_declaration = 'function'
+ if line.strip().startswith('G_INLINE_FUNC'):
+ logging.info('skip block after inline function')
+ # now we we need to skip a whole { } block
+ skip_block = 1
+
+ # Try to catch function declarations which have the return type on
+ # the previous line. But we don't want to catch complete functions
+ # which have been declared G_INLINE_FUNC, e.g. g_bit_nth_lsf in
+ # glib, or 'static inline' functions.
+ elif m19:
+ symbol = m19.group(1)
+ decl = line[m19.end():]
+
+ previous_line_words = previous_line.strip().split()
+
+ if not previous_line.strip().startswith('G_INLINE_FUNC'):
+ if not previous_line_words or previous_line_words[0] != 'static':
+ # $1 $2
+ pm = re.search(r'^\s*(?:\b(?:extern%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$' %
+ ignore_decorators, previous_line)
+ if pm:
+ ret_type = pm.group(1)
+ if pm.group(2):
+ ret_type += ' ' + pm.group(2)
+ logging.info('Function (2): "%s", Returns: "%s"', symbol, ret_type)
+ in_declaration = 'function'
+ else:
+ logging.info('skip block after inline function')
+ # now we we need to skip a whole { } block
+ skip_block = 1
+ # $1 $2
+ pm = re.search(r'^\s*(?:\b(?:extern|static|inline%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$' %
+ ignore_decorators, previous_line)
+ if pm:
+ ret_type = pm.group(1)
+ if pm.group(2):
+ ret_type += ' ' + pm.group(2)
+ logging.info('Function (3): "%s", Returns: "%s"', symbol, ret_type)
+ in_declaration = 'function'
+ else:
+ if not previous_line_words or previous_line_words[0] != 'static':
+ logging.info('skip block after inline function')
+ # now we we need to skip a whole { } block
+ skip_block = 1
+ # $1 $2
+ pm = re.search(r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$' %
+ ignore_decorators, previous_line)
+ if pm:
+ ret_type = pm.group(1)
+ if pm.group(2):
+ ret_type += ' ' + pm.group(2)
+ logging.info('Function (4): "%s", Returns: "%s"', symbol, ret_type)
+ in_declaration = 'function'
+
+ # Try to catch function declarations with the return type and name
+ # on the previous line(s), and the start of the parameters on this.
+ elif m20:
+ decl = line[m20.end():]
+ pm = re.search(
+ r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|enum\s+)*\w+)(\s+\*+|\*+|\s)\s*([A-Za-z]\w*)\s*$' % ignore_decorators, previous_line)
+ ppm = re.search(r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|struct\s+|union\s+|enum\s+)*\w+(?:\**\s+\**(?:const|G_CONST_RETURN))?(?:\s+|\s*\*+))\s*$' %
+ ignore_decorators, pre_previous_line)
+ if pm:
+ ret_type = pm.group(1) + ' ' + pm.group(2)
+ symbol = pm.group(3)
+ in_declaration = 'function'
+ logging.info('Function (5): "%s", Returns: "%s"', symbol, ret_type)
+
+ elif re.search(r'^\s*\w+\s*$', previous_line) and ppm:
+ ret_type = ppm.group(1)
+ ret_type = re.sub(r'\s*\n', '', ret_type, flags=re.MULTILINE)
+ in_declaration = 'function'
+
+ symbol = previous_line
+ symbol = re.sub(r'^\s+', '', symbol)
+ symbol = re.sub(r'\s*\n', '', symbol, flags=re.MULTILINE)
+ logging.info('Function (6): "%s", Returns: "%s"', symbol, ret_type)
+
+ #} elsif (m/^extern\s+/) {
+ # print "DEBUG: Skipping extern: $_"
+
+ # STRUCTS
+ elif re.search(r'^\s*struct\s+_?(\w+)\s*\*', line):
+ # Skip 'struct _<struct_name> *', since it could be a
+ # return type on its own line.
+ pass
+ elif m21:
+ # We assume that 'struct _<struct_name>' is really the
+ # declaration of struct <struct_name>.
+ symbol = m21.group(1)
+ decl = line
+ # we will find the correct level as below we do $level += tr/{//
+ level = 0
+ in_declaration = 'struct'
+ logging.info('Struct(_): "%s"', symbol)
+
+ # UNIONS
+ elif re.search(r'^\s*union\s+_(\w+)\s*\*', line):
+ # Skip 'union _<union_name> *' (see above)
+ pass
+ elif m22:
+ symbol = m22.group(1)
+ decl = line
+ level = 0
+ in_declaration = 'union'
+ logging.info('Union(_): "%s"', symbol)
+ else:
+ logging.info('in decl: skip=%s %s', skip_block, line.strip())
+ # If we were already in the middle of a declaration, we simply add
+ # the current line onto the end of it.
+ if skip_block == 0:
+ decl += line
+ else:
+ # Remove all nested pairs of curly braces.
+ brace_remover = r'{[^{]*}'
+ bm = re.search(brace_remover, line)
+ while bm:
+ line = re.sub(brace_remover, '', line)
+ bm = re.search(brace_remover, line)
+ # Then hope at most one remains in the line...
+ bm = re.search(r'(.*?){', line)
+ if bm:
+ if skip_block == 1:
+ decl += bm.group(1)
+ skip_block += 1
+ elif '}' in line:
+ skip_block -= 1
+ if skip_block == 1:
+ # this is a hack to detect the end of declaration
+ decl += ';'
+ skip_block = 0
+ logging.info('2: ---')
+
+ else:
+ if skip_block == 1:
+ decl += line
+
+ if in_declaration == "g-declare":
+ dm = re.search(r'\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*\).*$', decl)
+ # FIXME the original code does s// stuff here and we don't. Is it necessary?
+ if dm:
+ ModuleObjName = dm.group(1)
+ module_obj_name = dm.group(2)
+ if options.rebuild_types:
+ get_types.append(module_obj_name + '_get_type')
+ forward_decls[ModuleObjName] = '<STRUCT>\n<NAME>%s</NAME>\n%s</STRUCT>\n' % (ModuleObjName, deprecated)
+ if symbol.startswith('G_DECLARE_DERIVABLE'):
+ forward_decls[ModuleObjName + 'Class'] = '<STRUCT>\n<NAME>%sClass</NAME>\n%s</STRUCT>\n' % (
+ ModuleObjName, deprecated)
+ if symbol.startswith('G_DECLARE_INTERFACE'):
+ forward_decls[ModuleObjName + 'Interface'] = '<STRUCT>\n<NAME>%sInterface</NAME>\n%s</STRUCT>\n' % (
+ ModuleObjName, deprecated)
+ in_declaration = ''
+
+ # Note that sometimes functions end in ') G_GNUC_PRINTF (2, 3);' or
+ # ') __attribute__ (...);'.
+ if in_declaration == 'function':
+ regex = r'\)\s*(G_GNUC_.*|.*DEPRECATED.*%s\s*|__attribute__\s*\(.*\)\s*)*;.*$' % ignore_decorators
+ pm = re.search(regex, decl, flags=re.MULTILINE)
+ if pm:
+ logging.info('scrubbing:[%s]', decl.strip())
+ decl = re.sub(regex, '', decl, flags=re.MULTILINE)
+ logging.info('scrubbed:[%s]', decl.strip())
+ if internal == 0:
+ decl = re.sub(r'/\*.*?\*/', '', decl, flags=re.MULTILINE) # remove comments.
+ decl = re.sub(r'\s*\n\s*(?!$)', ' ', decl, flags=re.MULTILINE)
+ # consolidate whitespace at start/end of lines.
+ decl = decl.strip()
+ ret_type = re.sub(r'/\*.*?\*/', '', ret_type) # remove comments in ret type.
+ if AddSymbolToList(slist, symbol):
+ decl_list.append('<FUNCTION>\n<NAME>%s</NAME>\n%s<RETURNS>%s</RETURNS>\n%s\n</FUNCTION>\n' %
+ (symbol, deprecated, ret_type, decl))
+ if options.rebuild_types:
+ # check if this looks like a get_type function and if so remember
+ if symbol.endswith('_get_type') and 'GType' in ret_type and re.search(r'^(void|)$', decl):
+ logging.info(
+ "Adding get-type: [%s] [%s] [%s]\tfrom %s", ret_type, symbol, decl, input_file)
+ get_types.append(symbol)
+ else:
+ internal = 0
+ deprecated_conditional_nest = int(deprecated_conditional_nest)
+ in_declaration = ''
+ skip_block = 0
+
+ if in_declaration == 'user_function':
+ if re.search(r'\).*$', decl):
+ decl = re.sub(r'\).*$', '', decl)
+ if AddSymbolToList(slist, symbol):
+ decl_list.append('<USER_FUNCTION>\n<NAME>%s</NAME>\n%s<RETURNS>%s</RETURNS>\n%s</USER_FUNCTION>\n' %
+ (symbol, deprecated, ret_type, decl))
+ deprecated_conditional_nest = int(deprecated_conditional_nest)
+ in_declaration = ''
+
+ if in_declaration == 'macro':
+ if not re.search(r'\\\s*$', decl):
+ if internal == 0:
+ if AddSymbolToList(slist, symbol):
+ decl_list.append('<MACRO>\n<NAME>%s</NAME>\n%s%s</MACRO>\n' % (symbol, deprecated, decl))
+ else:
+ internal = 0
+ deprecated_conditional_nest = int(deprecated_conditional_nest)
+ in_declaration = ''
+
+ if in_declaration == 'enum':
+ em = re.search(r'\}\s*(\w+)?;\s*$', decl)
+ if em:
+ if symbol == '':
+ symbol = em.group(1)
+ if AddSymbolToList(slist, symbol):
+ decl_list.append('<ENUM>\n<NAME>%s</NAME>\n%s%s</ENUM>\n' % (symbol, deprecated, decl))
+ deprecated_conditional_nest = int(deprecated_conditional_nest)
+ in_declaration = ''
+
+ # We try to handle nested stucts/unions, but unmatched brackets in
+ # comments will cause problems.
+ if in_declaration == 'struct' or in_declaration == 'union':
+ sm = re.search(r'\n\}\s*(\w*);\s*$', decl)
+ if level <= 1 and sm:
+ if symbol == '':
+ symbol = sm.group(1)
+
+ bm = re.search(r'^(\S+)(Class|Iface|Interface)\b', symbol)
+ if bm:
+ objectname = bm.group(1)
+ logging.info('Found object: "%s"', objectname)
+ title = '<TITLE>%s</TITLE>' % objectname
+
+ logging.info('Store struct: "%s"', symbol)
+ if AddSymbolToList(slist, symbol):
+ structsym = in_declaration.upper()
+ decl_list.append('<%s>\n<NAME>%s</NAME>\n%s%s</%s>\n' %
+ (structsym, symbol, deprecated, decl, structsym))
+ if symbol in forward_decls:
+ del forward_decls[symbol]
+ deprecated_conditional_nest = int(deprecated_conditional_nest)
+ in_declaration = ''
+ else:
+ # We use tr to count the brackets in the line, and adjust
+ # $level accordingly.
+ level += line.count('{')
+ level -= line.count('}')
+ logging.info('struct/union level : %d', level)
+
+ pre_previous_line = previous_line
+ previous_line = line
+
+ # print remaining forward declarations
+ for symbol in sorted(iterkeys(forward_decls)):
+ if forward_decls[symbol]:
+ AddSymbolToList(slist, symbol)
+ decl_list.append(forward_decls[symbol])
+
+ # add title
+ slist = [title] + slist
+
+ logging.info("Scanning %s done", input_file)
+
+ # Try to separate the standard macros and functions, placing them at the
+ # end of the current section, in a subsection named 'Standard'.
+ # do this in a loop to catch object, enums and flags
+ klass = lclass = prefix = lprefix = None
+ standard_decl = []
+ liststr = '\n'.join(s for s in slist if s) + '\n'
+ while True:
+ m = re.search(r'^(\S+)_IS_(\S*)_CLASS\n', liststr, flags=re.MULTILINE)
+ m2 = re.search(r'^(\S+)_IS_(\S*)\n', liststr, flags=re.MULTILINE)
+ m3 = re.search(r'^(\S+?)_(\S*)_get_type\n', liststr, flags=re.MULTILINE)
+ if m:
+ prefix = m.group(1)
+ lprefix = prefix.lower()
+ klass = m.group(2)
+ lclass = klass.lower()
+ logging.info("Found gobject type '%s_%s' from is_class macro", prefix, klass)
+ elif m2:
+ prefix = m2.group(1)
+ lprefix = prefix.lower()
+ klass = m2.group(2)
+ lclass = klass.lower()
+ logging.info("Found gobject type '%s_%s' from is_ macro", prefix, klass)
+ elif m3:
+ lprefix = m3.group(1)
+ prefix = lprefix.upper()
+ lclass = m3.group(2)
+ klass = lclass.upper()
+ logging.info("Found gobject type '%s_%s' from get_type function", prefix, klass)
+ else:
+ break
+
+ cclass = lclass
+ cclass = cclass.replace('_', '')
+ mtype = lprefix + cclass
+
+ liststr, standard_decl = replace_once(liststr, standard_decl, r'^%sPrivate\n' % mtype)
+
+ # We only leave XxYy* in the normal section if they have docs
+ if mtype not in doc_comments:
+ logging.info(" Hide instance docs for %s", mtype)
+ liststr, standard_decl = replace_once(liststr, standard_decl, r'^%s\n' % mtype)
+
+ if mtype + 'class' not in doc_comments:
+ logging.info(" Hide class docs for %s", mtype)
+ liststr, standard_decl = replace_once(liststr, standard_decl, r'^%sClass\n' % mtype)
+
+ if mtype + 'interface' not in doc_comments:
+ logging.info(" Hide iface docs for %s", mtype)
+ liststr, standard_decl = replace_once(liststr, standard_decl, r'%sInterface\n' % mtype)
+
+ if mtype + 'iface' not in doc_comments:
+ logging.info(" Hide iface docs for " + mtype)
+ liststr, standard_decl = replace_once(liststr, standard_decl, r'%sIface\n' % mtype)
+
+ liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_IS_%s\n' % klass)
+ liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_TYPE_%s\n' % klass)
+ liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_get_type\n' % lclass)
+ liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_CLASS\n' % klass)
+ liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_IS_%s_CLASS\n' % klass)
+ liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_GET_CLASS\n' % klass)
+ liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_GET_IFACE\n' % klass)
+ liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_GET_INTERFACE\n' % klass)
+ # We do this one last, otherwise it tends to be caught by the IS_$class macro
+ liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s\n' % klass)
+
+ logging.info('Decl:%s---', liststr)
+ logging.info('Std :%s---', ''.join(sorted(standard_decl)))
+ if len(standard_decl):
+ # sort the symbols
+ liststr += '<SUBSECTION Standard>\n' + ''.join(sorted(standard_decl))
+
+ if liststr != '':
+ if file_basename not in section_list:
+ section_list[file_basename] = ''
+ section_list[file_basename] += "<SECTION>\n<FILE>%s</FILE>\n%s</SECTION>\n\n" % (file_basename, liststr)
+
+
+def replace_once(liststr, standard_decl, regex):
+ mre = re.search(regex, liststr, flags=re.IGNORECASE | re.MULTILINE)
+ if mre:
+ standard_decl.append(mre.group(0))
+ liststr = re.sub(regex, '', liststr, flags=re.IGNORECASE | re.MULTILINE)
+ return liststr, standard_decl
+
+
+def replace_all(liststr, standard_decl, regex):
+ mre = re.search(regex, liststr, flags=re.MULTILINE)
+ while mre:
+ standard_decl.append(mre.group(0))
+ liststr = re.sub(regex, '', liststr, flags=re.MULTILINE)
+ mre = re.search(regex, liststr, flags=re.MULTILINE)
+ return liststr, standard_decl
+
+
+def AddSymbolToList(slist, symbol):
+ """ Adds symbol to list of declaration if not already present.
+
+ Args:
+ slist: The list of symbols.
+ symbol: The symbol to add to the list.
+ """
+ if symbol in slist:
+ # logging.info('Symbol %s already in list. skipping', symbol)
+ # we return False to skip outputting another entry to -decl.txt
+ # this is to avoid redeclarations (e.g. in conditional sections).
+ return False
+ slist.append(symbol)
+ return True
--- /dev/null
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 1998 Damon Chaplin
+# 2007-2016 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.
+#
+
+"""
+The scangobj tool gets information about object hierarchies and signals by
+compiling and running a small C program. CFLAGS and LDFLAGS must be set
+appropriately before running this script.
+"""
+
+import logging
+import os
+import string
+import subprocess
+
+from . import common, config
+
+
+COMMON_INCLUDES = """
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <errno.h>
+#include <glib-object.h>
+"""
+
+QUERY_CHILD_PROPS_PROTOTYPE = "extern GParamSpec** %s (gpointer class, guint *n_properties);"
+
+QUERY_CHILD_PROPS_CODE = """
+ if (!child_prop) {
+ properties = %s (class, &n_properties);
+ if (properties) {
+ child_prop = TRUE;
+ continue;
+ }
+ }
+"""
+
+MAIN_CODE = """
+
+#ifdef GTK_IS_WIDGET_CLASS
+#include <gtk/gtk.h>
+#endif
+static GType object_types[$ntypes];
+
+static GType *
+get_object_types (void)
+{
+ gpointer g_object_class;
+ gint i = 0;
+
+${get_types}
+ object_types[i] = G_TYPE_INVALID;
+
+ /* reference the GObjectClass to initialize the param spec pool
+ * potentially needed by interfaces. See http://bugs.gnome.org/571820 */
+ g_object_class = g_type_class_ref (G_TYPE_OBJECT);
+
+ /* Need to make sure all the types are loaded in and initialize
+ * their signals and properties.
+ */
+ for (i=0; object_types[i]; i++) {
+ if (G_TYPE_IS_CLASSED (object_types[i]))
+ g_type_class_ref (object_types[i]);
+ if (G_TYPE_IS_INTERFACE (object_types[i]))
+ g_type_default_interface_ref (object_types[i]);
+ }
+
+ g_type_class_unref (g_object_class);
+
+ return object_types;
+}
+
+/*
+ * This uses GObject type functions to output signal prototypes and the object
+ * hierarchy.
+ */
+
+/* The output files */
+const gchar *signals_filename = "$new_signals_filename";
+const gchar *hierarchy_filename = "$new_hierarchy_filename";
+const gchar *interfaces_filename = "$new_interfaces_filename";
+const gchar *prerequisites_filename = "$new_prerequisites_filename";
+const gchar *args_filename = "$new_args_filename";
+
+static void output_signals (void);
+static void output_object_signals (FILE *fp,
+ GType object_type);
+static void output_object_signal (FILE *fp,
+ const gchar *object_class_name,
+ guint signal_id);
+static const gchar * get_type_name (GType type,
+ gboolean * is_pointer);
+static void output_object_hierarchy (void);
+static void output_hierarchy (FILE *fp,
+ GType type,
+ guint level);
+
+static void output_object_interfaces (void);
+static void output_interfaces (FILE *fp,
+ GType type);
+
+static void output_interface_prerequisites (void);
+static void output_prerequisites (FILE *fp,
+ GType type);
+
+static void output_args (void);
+static void output_object_args (FILE *fp, GType object_type);
+
+int
+main (int argc, char *argv[])
+{
+ ${type_init_func};
+
+ get_object_types ();
+
+ output_signals ();
+ output_object_hierarchy ();
+ output_object_interfaces ();
+ output_interface_prerequisites ();
+ output_args ();
+
+ return 0;
+}
+
+static void
+output_signals (void)
+{
+ FILE *fp;
+ gint i;
+
+ fp = fopen (signals_filename, "w");
+ if (fp == NULL) {
+ g_warning ("Couldn't open output file: %s : %s", signals_filename, g_strerror(errno));
+ return;
+ }
+
+ for (i = 0; object_types[i]; i++)
+ output_object_signals (fp, object_types[i]);
+
+ fclose (fp);
+}
+
+static gint
+compare_signals (const void *a, const void *b)
+{
+ const guint *signal_a = a;
+ const guint *signal_b = b;
+
+ return strcmp (g_signal_name (*signal_a), g_signal_name (*signal_b));
+}
+
+/* This outputs all the signals of one object. */
+static void
+output_object_signals (FILE *fp, GType object_type)
+{
+ const gchar *object_class_name;
+ guint *signals, n_signals;
+ guint sig;
+
+ if (G_TYPE_IS_INSTANTIATABLE (object_type) ||
+ G_TYPE_IS_INTERFACE (object_type)) {
+
+ object_class_name = g_type_name (object_type);
+
+ signals = g_signal_list_ids (object_type, &n_signals);
+ qsort (signals, n_signals, sizeof (guint), compare_signals);
+
+ for (sig = 0; sig < n_signals; sig++) {
+ output_object_signal (fp, object_class_name, signals[sig]);
+ }
+ g_free (signals);
+ }
+}
+
+/* This outputs one signal. */
+static void
+output_object_signal (FILE *fp,
+ const gchar *object_name,
+ guint signal_id)
+{
+ GSignalQuery query_info;
+ const gchar *type_name, *ret_type, *object_arg, *arg_name;
+ gchar *pos, *object_arg_lower;
+ gboolean is_pointer;
+ gchar buffer[1024];
+ guint i, param;
+ gint param_num, widget_num, event_num, callback_num;
+ gint *arg_num;
+ gchar signal_name[128];
+ gchar flags[16];
+
+ /* g_print ("Object: %s Signal: %u\\n", object_name, signal_id);*/
+
+ param_num = 1;
+ widget_num = event_num = callback_num = 0;
+
+ g_signal_query (signal_id, &query_info);
+
+ /* Output the signal object type and the argument name. We assume the
+ * type is a pointer - I think that is OK. We remove "Gtk" or "Gnome" and
+ * convert to lower case for the argument name. */
+ pos = buffer;
+ sprintf (pos, "%s ", object_name);
+ pos += strlen (pos);
+
+ /* Try to come up with a sensible variable name for the first arg
+ * It chops off 2 know prefixes :/ and makes the name lowercase
+ * It should replace lowercase -> uppercase with '_'
+ * GFileMonitor -> file_monitor
+ * GIOExtensionPoint -> extension_point
+ * GtkTreeView -> tree_view
+ * if 2nd char is upper case too
+ * search for first lower case and go back one char
+ * else
+ * search for next upper case
+ */
+ if (!strncmp (object_name, "Gtk", 3))
+ object_arg = object_name + 3;
+ else if (!strncmp (object_name, "Gnome", 5))
+ object_arg = object_name + 5;
+ else
+ object_arg = object_name;
+
+ object_arg_lower = g_ascii_strdown (object_arg, -1);
+ sprintf (pos, "*%s\\n", object_arg_lower);
+ pos += strlen (pos);
+ if (!strncmp (object_arg_lower, "widget", 6))
+ widget_num = 2;
+ g_free(object_arg_lower);
+
+ /* Convert signal name to use underscores rather than dashes '-'. */
+ strncpy (signal_name, query_info.signal_name, 127);
+ signal_name[127] = '\\0';
+ for (i = 0; signal_name[i]; i++) {
+ if (signal_name[i] == '-')
+ signal_name[i] = '_';
+ }
+
+ /* Output the signal parameters. */
+ for (param = 0; param < query_info.n_params; param++) {
+ type_name = get_type_name (query_info.param_types[param] & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer);
+
+ /* Most arguments to the callback are called "arg1", "arg2", etc.
+ GtkWidgets are called "widget", "widget2", ...
+ GtkCallbacks are called "callback", "callback2", ... */
+ if (!strcmp (type_name, "GtkWidget")) {
+ arg_name = "widget";
+ arg_num = &widget_num;
+ }
+ else if (!strcmp (type_name, "GtkCallback")
+ || !strcmp (type_name, "GtkCCallback")) {
+ arg_name = "callback";
+ arg_num = &callback_num;
+ }
+ else {
+ arg_name = "arg";
+ arg_num = ¶m_num;
+ }
+ sprintf (pos, "%s ", type_name);
+ pos += strlen (pos);
+
+ if (!arg_num || *arg_num == 0)
+ sprintf (pos, "%s%s\\n", is_pointer ? "*" : " ", arg_name);
+ else
+ sprintf (pos, "%s%s%i\\n", is_pointer ? "*" : " ", arg_name,
+ *arg_num);
+ pos += strlen (pos);
+
+ if (arg_num) {
+ if (*arg_num == 0)
+ *arg_num = 2;
+ else
+ *arg_num += 1;
+ }
+ }
+
+ pos = flags;
+ /* We use one-character flags for simplicity. */
+ if (query_info.signal_flags & G_SIGNAL_RUN_FIRST)
+ *pos++ = 'f';
+ if (query_info.signal_flags & G_SIGNAL_RUN_LAST)
+ *pos++ = 'l';
+ if (query_info.signal_flags & G_SIGNAL_RUN_CLEANUP)
+ *pos++ = 'c';
+ if (query_info.signal_flags & G_SIGNAL_NO_RECURSE)
+ *pos++ = 'r';
+ if (query_info.signal_flags & G_SIGNAL_DETAILED)
+ *pos++ = 'd';
+ if (query_info.signal_flags & G_SIGNAL_ACTION)
+ *pos++ = 'a';
+ if (query_info.signal_flags & G_SIGNAL_NO_HOOKS)
+ *pos++ = 'h';
+ *pos = 0;
+
+ /* Output the return type and function name. */
+ ret_type = get_type_name (query_info.return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer);
+
+ fprintf (fp,
+ "<SIGNAL>\\n<NAME>%s::%s</NAME>\\n<RETURNS>%s%s</RETURNS>\\n<FLAGS>%s</FLAGS>\\n%s</SIGNAL>\\n\\n",
+ object_name, query_info.signal_name, ret_type, is_pointer ? "*" : "", flags, buffer);
+}
+
+
+/* Returns the type name to use for a signal argument or return value, given
+ the GtkType from the signal info. It also sets is_pointer to TRUE if the
+ argument needs a '*' since it is a pointer. */
+static const gchar *
+get_type_name (GType type, gboolean * is_pointer)
+{
+ const gchar *type_name;
+
+ *is_pointer = FALSE;
+ type_name = g_type_name (type);
+
+ switch (type) {
+ case G_TYPE_NONE:
+ case G_TYPE_CHAR:
+ case G_TYPE_UCHAR:
+ case G_TYPE_BOOLEAN:
+ case G_TYPE_INT:
+ case G_TYPE_UINT:
+ case G_TYPE_LONG:
+ case G_TYPE_ULONG:
+ case G_TYPE_FLOAT:
+ case G_TYPE_DOUBLE:
+ case G_TYPE_POINTER:
+ /* These all have normal C type names so they are OK. */
+ return type_name;
+
+ case G_TYPE_STRING:
+ /* A GtkString is really a gchar*. */
+ *is_pointer = TRUE;
+ return "gchar";
+
+ case G_TYPE_ENUM:
+ case G_TYPE_FLAGS:
+ /* We use a gint for both of these. Hopefully a subtype with a decent
+ name will be registered and used instead, as GTK+ does itself. */
+ return "gint";
+
+ case G_TYPE_BOXED:
+ /* The boxed type shouldn't be used itself, only subtypes. Though we
+ return 'gpointer' just in case. */
+ return "gpointer";
+
+ case G_TYPE_PARAM:
+ /* A GParam is really a GParamSpec*. */
+ *is_pointer = TRUE;
+ return "GParamSpec";
+
+#if GLIB_CHECK_VERSION (2, 25, 9)
+ case G_TYPE_VARIANT:
+ *is_pointer = TRUE;
+ return "GVariant";
+#endif
+
+default:
+ break;
+ }
+
+ /* For all GObject subclasses we can use the class name with a "*",
+ e.g. 'GtkWidget *'. */
+ if (g_type_is_a (type, G_TYPE_OBJECT))
+ *is_pointer = TRUE;
+
+ /* Also catch non GObject root types */
+ if (G_TYPE_IS_CLASSED (type))
+ *is_pointer = TRUE;
+
+ /* All boxed subtypes will be pointers as well. */
+ /* Exception: GStrv */
+ if (g_type_is_a (type, G_TYPE_BOXED) &&
+ !g_type_is_a (type, G_TYPE_STRV))
+ *is_pointer = TRUE;
+
+ /* All pointer subtypes will be pointers as well. */
+ if (g_type_is_a (type, G_TYPE_POINTER))
+ *is_pointer = TRUE;
+
+ /* But enums are not */
+ if (g_type_is_a (type, G_TYPE_ENUM) ||
+ g_type_is_a (type, G_TYPE_FLAGS))
+ *is_pointer = FALSE;
+
+ return type_name;
+}
+
+
+/* This outputs the hierarchy of all objects which have been initialized,
+ i.e. by calling their XXX_get_type() initialization function. */
+static void
+output_object_hierarchy (void)
+{
+ FILE *fp;
+ gint i,j;
+ GType root, type;
+ GType root_types[$ntypes] = { G_TYPE_INVALID, };
+
+ fp = fopen (hierarchy_filename, "w");
+ if (fp == NULL) {
+ g_warning ("Couldn't open output file: %s : %s", hierarchy_filename, g_strerror(errno));
+ return;
+ }
+ output_hierarchy (fp, G_TYPE_OBJECT, 0);
+ output_hierarchy (fp, G_TYPE_INTERFACE, 0);
+
+ for (i=0; object_types[i]; i++) {
+ root = object_types[i];
+ while ((type = g_type_parent (root))) {
+ root = type;
+ }
+ if ((root != G_TYPE_OBJECT) && (root != G_TYPE_INTERFACE)) {
+ for (j=0; root_types[j]; j++) {
+ if (root == root_types[j]) {
+ root = G_TYPE_INVALID; break;
+ }
+ }
+ if(root) {
+ root_types[j] = root;
+ output_hierarchy (fp, root, 0);
+ }
+ }
+ }
+
+ fclose (fp);
+}
+
+/* This is called recursively to output the hierarchy of a object. */
+static void
+output_hierarchy (FILE *fp,
+ GType type,
+ guint level)
+{
+ guint i;
+ GType *children;
+ guint n_children;
+
+ if (!type)
+ return;
+
+ for (i = 0; i < level; i++)
+ fprintf (fp, " ");
+ fprintf (fp, "%s\\n", g_type_name (type));
+
+ children = g_type_children (type, &n_children);
+
+ for (i=0; i < n_children; i++)
+ output_hierarchy (fp, children[i], level + 1);
+
+ g_free (children);
+}
+
+static void output_object_interfaces (void)
+{
+ guint i;
+ FILE *fp;
+
+ fp = fopen (interfaces_filename, "w");
+ if (fp == NULL) {
+ g_warning ("Couldn't open output file: %s : %s", interfaces_filename, g_strerror(errno));
+ return;
+ }
+ output_interfaces (fp, G_TYPE_OBJECT);
+
+ for (i = 0; object_types[i]; i++) {
+ if (!g_type_parent (object_types[i]) &&
+ (object_types[i] != G_TYPE_OBJECT) &&
+ G_TYPE_IS_INSTANTIATABLE (object_types[i])) {
+ output_interfaces (fp, object_types[i]);
+ }
+ }
+ fclose (fp);
+}
+
+static void
+output_interfaces (FILE *fp,
+ GType type)
+{
+ guint i;
+ GType *children, *interfaces;
+ guint n_children, n_interfaces;
+
+ if (!type)
+ return;
+
+ interfaces = g_type_interfaces (type, &n_interfaces);
+
+ if (n_interfaces > 0) {
+ fprintf (fp, "%s", g_type_name (type));
+ for (i=0; i < n_interfaces; i++)
+ fprintf (fp, " %s", g_type_name (interfaces[i]));
+ fprintf (fp, "\\n");
+ }
+ g_free (interfaces);
+
+ children = g_type_children (type, &n_children);
+
+ for (i=0; i < n_children; i++)
+ output_interfaces (fp, children[i]);
+
+ g_free (children);
+}
+
+static void output_interface_prerequisites (void)
+{
+ FILE *fp;
+
+ fp = fopen (prerequisites_filename, "w");
+ if (fp == NULL) {
+ g_warning ("Couldn't open output file: %s : %s", prerequisites_filename, g_strerror(errno));
+ return;
+ }
+ output_prerequisites (fp, G_TYPE_INTERFACE);
+ fclose (fp);
+}
+
+static void
+output_prerequisites (FILE *fp,
+ GType type)
+{
+#if GLIB_CHECK_VERSION(2,1,0)
+ guint i;
+ GType *children, *prerequisites;
+ guint n_children, n_prerequisites;
+
+ if (!type)
+ return;
+
+ prerequisites = g_type_interface_prerequisites (type, &n_prerequisites);
+
+ if (n_prerequisites > 0) {
+ fprintf (fp, "%s", g_type_name (type));
+ for (i=0; i < n_prerequisites; i++)
+ fprintf (fp, " %s", g_type_name (prerequisites[i]));
+ fprintf (fp, "\\n");
+ }
+ g_free (prerequisites);
+
+ children = g_type_children (type, &n_children);
+
+ for (i=0; i < n_children; i++)
+ output_prerequisites (fp, children[i]);
+
+ g_free (children);
+#endif
+}
+
+static void
+output_args (void)
+{
+ FILE *fp;
+ gint i;
+
+ fp = fopen (args_filename, "w");
+ if (fp == NULL) {
+ g_warning ("Couldn't open output file: %s : %s", args_filename, g_strerror(errno));
+ return;
+ }
+
+ for (i = 0; object_types[i]; i++) {
+ output_object_args (fp, object_types[i]);
+ }
+
+ fclose (fp);
+}
+
+static gint
+compare_param_specs (const void *a, const void *b)
+{
+ GParamSpec *spec_a = *(GParamSpec **)a;
+ GParamSpec *spec_b = *(GParamSpec **)b;
+
+ return strcmp (g_param_spec_get_name (spec_a), g_param_spec_get_name (spec_b));
+}
+
+/* Its common to have unsigned properties restricted
+ * to the signed range. Therefore we make this look
+ * a bit nicer by spelling out the max constants.
+ */
+
+/* Don't use "==" with floats, it might trigger a gcc warning. */
+#define GTKDOC_COMPARE_FLOAT(x, y) (x <= y && x >= y)
+
+static gchar*
+describe_double_constant (gdouble value)
+{
+ gchar *desc;
+
+ if (GTKDOC_COMPARE_FLOAT (value, G_MAXDOUBLE))
+ desc = g_strdup ("G_MAXDOUBLE");
+ else if (GTKDOC_COMPARE_FLOAT (value, G_MINDOUBLE))
+ desc = g_strdup ("G_MINDOUBLE");
+ else if (GTKDOC_COMPARE_FLOAT (value, -G_MAXDOUBLE))
+ desc = g_strdup ("-G_MAXDOUBLE");
+ else if (GTKDOC_COMPARE_FLOAT (value, G_MAXFLOAT))
+ desc = g_strdup ("G_MAXFLOAT");
+ else if (GTKDOC_COMPARE_FLOAT (value, G_MINFLOAT))
+ desc = g_strdup ("G_MINFLOAT");
+ else if (GTKDOC_COMPARE_FLOAT (value, -G_MAXFLOAT))
+ desc = g_strdup ("-G_MAXFLOAT");
+ else{
+ /* make sure floats are output with a decimal dot irrespective of
+ * current locale. Use formatd since we want human-readable numbers
+ * and do not need the exact same bit representation when deserialising */
+ desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
+ g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g", value);
+ }
+
+ return desc;
+}
+
+static gchar*
+describe_signed_constant (gsize size, gint64 value)
+{
+ gchar *desc = NULL;
+
+ switch (size) {
+ case 2:
+ if (sizeof (int) == 2) {
+ if (value == G_MAXINT)
+ desc = g_strdup ("G_MAXINT");
+ else if (value == G_MININT)
+ desc = g_strdup ("G_MININT");
+ }
+ break;
+ case 4:
+ if (sizeof (int) == 4) {
+ if (value == G_MAXINT)
+ desc = g_strdup ("G_MAXINT");
+ else if (value == G_MININT)
+ desc = g_strdup ("G_MININT");
+ }
+ if (value == G_MAXLONG)
+ desc = g_strdup ("G_MAXLONG");
+ else if (value == G_MINLONG)
+ desc = g_strdup ("G_MINLONG");
+ break;
+ case 8:
+ if (value == G_MAXINT64)
+ desc = g_strdup ("G_MAXINT64");
+ else if (value == G_MININT64)
+ desc = g_strdup ("G_MININT64");
+ break;
+ default:
+ break;
+ }
+ if (!desc)
+ desc = g_strdup_printf ("%" G_GINT64_FORMAT, value);
+
+ return desc;
+}
+
+static gchar*
+describe_unsigned_constant (gsize size, guint64 value)
+{
+ gchar *desc = NULL;
+
+ switch (size) {
+ case 2:
+ if (sizeof (int) == 2) {
+ if (value == (guint64)G_MAXINT)
+ desc = g_strdup ("G_MAXINT");
+ else if (value == G_MAXUINT)
+ desc = g_strdup ("G_MAXUINT");
+ }
+ break;
+ case 4:
+ if (sizeof (int) == 4) {
+ if (value == (guint64)G_MAXINT)
+ desc = g_strdup ("G_MAXINT");
+ else if (value == G_MAXUINT)
+ desc = g_strdup ("G_MAXUINT");
+ }
+ if (value == (guint64)G_MAXLONG)
+ desc = g_strdup ("G_MAXLONG");
+ else if (value == G_MAXULONG)
+ desc = g_strdup ("G_MAXULONG");
+ break;
+ case 8:
+ if (value == G_MAXINT64)
+ desc = g_strdup ("G_MAXINT64");
+ else if (value == G_MAXUINT64)
+ desc = g_strdup ("G_MAXUINT64");
+ break;
+ default:
+ break;
+ }
+ if (!desc)
+ desc = g_strdup_printf ("%" G_GUINT64_FORMAT, value);
+
+ return desc;
+}
+
+static gchar*
+describe_type (GParamSpec *spec)
+{
+ gchar *desc;
+ gchar *lower;
+ gchar *upper;
+
+ if (G_IS_PARAM_SPEC_CHAR (spec)) {
+ GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec);
+
+ lower = describe_signed_constant (sizeof(gchar), pspec->minimum);
+ upper = describe_signed_constant (sizeof(gchar), pspec->maximum);
+ if (pspec->minimum == G_MININT8 && pspec->maximum == G_MAXINT8)
+ desc = g_strdup ("");
+ else if (pspec->minimum == G_MININT8)
+ desc = g_strdup_printf ("<= %s", upper);
+ else if (pspec->maximum == G_MAXINT8)
+ desc = g_strdup_printf (">= %s", lower);
+ else
+ desc = g_strdup_printf ("[%s,%s]", lower, upper);
+ g_free (lower);
+ g_free (upper);
+ }
+ else if (G_IS_PARAM_SPEC_UCHAR (spec)) {
+ GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec);
+
+ lower = describe_unsigned_constant (sizeof(guchar), pspec->minimum);
+ upper = describe_unsigned_constant (sizeof(guchar), pspec->maximum);
+ if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT8)
+ desc = g_strdup ("");
+ else if (pspec->minimum == 0)
+ desc = g_strdup_printf ("<= %s", upper);
+ else if (pspec->maximum == G_MAXUINT8)
+ desc = g_strdup_printf (">= %s", lower);
+ else
+ desc = g_strdup_printf ("[%s,%s]", lower, upper);
+ g_free (lower);
+ g_free (upper);
+ }
+ else if (G_IS_PARAM_SPEC_INT (spec)) {
+ GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec);
+
+ lower = describe_signed_constant (sizeof(gint), pspec->minimum);
+ upper = describe_signed_constant (sizeof(gint), pspec->maximum);
+ if (pspec->minimum == G_MININT && pspec->maximum == G_MAXINT)
+ desc = g_strdup ("");
+ else if (pspec->minimum == G_MININT)
+ desc = g_strdup_printf ("<= %s", upper);
+ else if (pspec->maximum == G_MAXINT)
+ desc = g_strdup_printf (">= %s", lower);
+ else
+ desc = g_strdup_printf ("[%s,%s]", lower, upper);
+ g_free (lower);
+ g_free (upper);
+ }
+ else if (G_IS_PARAM_SPEC_UINT (spec)) {
+ GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec);
+
+ lower = describe_unsigned_constant (sizeof(guint), pspec->minimum);
+ upper = describe_unsigned_constant (sizeof(guint), pspec->maximum);
+ if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT)
+ desc = g_strdup ("");
+ else if (pspec->minimum == 0)
+ desc = g_strdup_printf ("<= %s", upper);
+ else if (pspec->maximum == G_MAXUINT)
+ desc = g_strdup_printf (">= %s", lower);
+ else
+ desc = g_strdup_printf ("[%s,%s]", lower, upper);
+ g_free (lower);
+ g_free (upper);
+ }
+ else if (G_IS_PARAM_SPEC_LONG (spec)) {
+ GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec);
+
+ lower = describe_signed_constant (sizeof(glong), pspec->minimum);
+ upper = describe_signed_constant (sizeof(glong), pspec->maximum);
+ if (pspec->minimum == G_MINLONG && pspec->maximum == G_MAXLONG)
+ desc = g_strdup ("");
+ else if (pspec->minimum == G_MINLONG)
+ desc = g_strdup_printf ("<= %s", upper);
+ else if (pspec->maximum == G_MAXLONG)
+ desc = g_strdup_printf (">= %s", lower);
+ else
+ desc = g_strdup_printf ("[%s,%s]", lower, upper);
+ g_free (lower);
+ g_free (upper);
+ }
+ else if (G_IS_PARAM_SPEC_ULONG (spec)) {
+ GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec);
+
+ lower = describe_unsigned_constant (sizeof(gulong), pspec->minimum);
+ upper = describe_unsigned_constant (sizeof(gulong), pspec->maximum);
+ if (pspec->minimum == 0 && pspec->maximum == G_MAXULONG)
+ desc = g_strdup ("");
+ else if (pspec->minimum == 0)
+ desc = g_strdup_printf ("<= %s", upper);
+ else if (pspec->maximum == G_MAXULONG)
+ desc = g_strdup_printf (">= %s", lower);
+ else
+ desc = g_strdup_printf ("[%s,%s]", lower, upper);
+ g_free (lower);
+ g_free (upper);
+ }
+ else if (G_IS_PARAM_SPEC_INT64 (spec)) {
+ GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec);
+
+ lower = describe_signed_constant (sizeof(gint64), pspec->minimum);
+ upper = describe_signed_constant (sizeof(gint64), pspec->maximum);
+ if (pspec->minimum == G_MININT64 && pspec->maximum == G_MAXINT64)
+ desc = g_strdup ("");
+ else if (pspec->minimum == G_MININT64)
+ desc = g_strdup_printf ("<= %s", upper);
+ else if (pspec->maximum == G_MAXINT64)
+ desc = g_strdup_printf (">= %s", lower);
+ else
+ desc = g_strdup_printf ("[%s,%s]", lower, upper);
+ g_free (lower);
+ g_free (upper);
+ }
+ else if (G_IS_PARAM_SPEC_UINT64 (spec)) {
+ GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec);
+
+ lower = describe_unsigned_constant (sizeof(guint64), pspec->minimum);
+ upper = describe_unsigned_constant (sizeof(guint64), pspec->maximum);
+ if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT64)
+ desc = g_strdup ("");
+ else if (pspec->minimum == 0)
+ desc = g_strdup_printf ("<= %s", upper);
+ else if (pspec->maximum == G_MAXUINT64)
+ desc = g_strdup_printf (">= %s", lower);
+ else
+ desc = g_strdup_printf ("[%s,%s]", lower, upper);
+ g_free (lower);
+ g_free (upper);
+ }
+ else if (G_IS_PARAM_SPEC_FLOAT (spec)) {
+ GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec);
+
+ lower = describe_double_constant (pspec->minimum);
+ upper = describe_double_constant (pspec->maximum);
+ if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXFLOAT)) {
+ if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT))
+ desc = g_strdup ("");
+ else
+ desc = g_strdup_printf ("<= %s", upper);
+ }
+ else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT))
+ desc = g_strdup_printf (">= %s", lower);
+ else
+ desc = g_strdup_printf ("[%s,%s]", lower, upper);
+ g_free (lower);
+ g_free (upper);
+ }
+ else if (G_IS_PARAM_SPEC_DOUBLE (spec)) {
+ GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec);
+
+ lower = describe_double_constant (pspec->minimum);
+ upper = describe_double_constant (pspec->maximum);
+ if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXDOUBLE)) {
+ if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE))
+ desc = g_strdup ("");
+ else
+ desc = g_strdup_printf ("<= %s", upper);
+ }
+ else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE))
+ desc = g_strdup_printf (">= %s", lower);
+ else
+ desc = g_strdup_printf ("[%s,%s]", lower, upper);
+ g_free (lower);
+ g_free (upper);
+ }
+#if GLIB_CHECK_VERSION (2, 12, 0)
+ else if (G_IS_PARAM_SPEC_GTYPE (spec)) {
+ GParamSpecGType *pspec = G_PARAM_SPEC_GTYPE (spec);
+ gboolean is_pointer;
+
+ desc = g_strdup (get_type_name (pspec->is_a_type, &is_pointer));
+ }
+#endif
+#if GLIB_CHECK_VERSION (2, 25, 9)
+ else if (G_IS_PARAM_SPEC_VARIANT (spec)) {
+ GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec);
+ gchar *variant_type;
+
+ variant_type = g_variant_type_dup_string (pspec->type);
+ desc = g_strdup_printf ("GVariant<%s>", variant_type);
+ g_free (variant_type);
+ }
+#endif
+ else {
+ desc = g_strdup ("");
+ }
+
+ return desc;
+}
+
+static gchar*
+describe_default (GParamSpec *spec)
+{
+ gchar *desc;
+
+ if (G_IS_PARAM_SPEC_CHAR (spec)) {
+ GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec);
+
+ desc = g_strdup_printf ("%d", pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_UCHAR (spec)) {
+ GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec);
+
+ desc = g_strdup_printf ("%u", pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_BOOLEAN (spec)) {
+ GParamSpecBoolean *pspec = G_PARAM_SPEC_BOOLEAN (spec);
+
+ desc = g_strdup_printf ("%s", pspec->default_value ? "TRUE" : "FALSE");
+ }
+ else if (G_IS_PARAM_SPEC_INT (spec)) {
+ GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec);
+
+ desc = g_strdup_printf ("%d", pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_UINT (spec)) {
+ GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec);
+
+ desc = g_strdup_printf ("%u", pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_LONG (spec)) {
+ GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec);
+
+ desc = g_strdup_printf ("%ld", pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_LONG (spec)) {
+ GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec);
+
+ desc = g_strdup_printf ("%lu", pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_INT64 (spec)) {
+ GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec);
+
+ desc = g_strdup_printf ("%" G_GINT64_FORMAT, pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_UINT64 (spec))
+ {
+ GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec);
+
+ desc = g_strdup_printf ("%" G_GUINT64_FORMAT, pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_UNICHAR (spec)) {
+ GParamSpecUnichar *pspec = G_PARAM_SPEC_UNICHAR (spec);
+
+ if (g_unichar_isprint (pspec->default_value))
+ desc = g_strdup_printf ("'%c'", pspec->default_value);
+ else
+ desc = g_strdup_printf ("%u", pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_ENUM (spec)) {
+ GParamSpecEnum *pspec = G_PARAM_SPEC_ENUM (spec);
+
+ GEnumValue *value = g_enum_get_value (pspec->enum_class, pspec->default_value);
+ if (value)
+ desc = g_strdup_printf ("%s", value->value_name);
+ else
+ desc = g_strdup_printf ("%d", pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_FLAGS (spec)) {
+ GParamSpecFlags *pspec = G_PARAM_SPEC_FLAGS (spec);
+ guint default_value;
+ GString *acc;
+
+ default_value = pspec->default_value;
+ acc = g_string_new ("");
+
+ while (default_value) {
+ GFlagsValue *value = g_flags_get_first_value (pspec->flags_class, default_value);
+
+ if (!value)
+ break;
+
+ if (acc->len > 0)
+ g_string_append (acc, " | ");
+ g_string_append (acc, value->value_name);
+
+ default_value &= ~value->value;
+ }
+
+ if (default_value == 0)
+ desc = g_string_free (acc, FALSE);
+ else {
+ desc = g_strdup_printf ("%d", pspec->default_value);
+ g_string_free (acc, TRUE);
+ }
+ }
+ else if (G_IS_PARAM_SPEC_FLOAT (spec)) {
+ GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec);
+
+ /* make sure floats are output with a decimal dot irrespective of
+ * current locale. Use formatd since we want human-readable numbers
+ * and do not need the exact same bit representation when deserialising */
+ desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
+ g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g",
+ pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_DOUBLE (spec)) {
+ GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec);
+
+ /* make sure floats are output with a decimal dot irrespective of
+ * current locale. Use formatd since we want human-readable numbers
+ * and do not need the exact same bit representation when deserialising */
+ desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE);
+ g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g",
+ pspec->default_value);
+ }
+ else if (G_IS_PARAM_SPEC_STRING (spec)) {
+ GParamSpecString *pspec = G_PARAM_SPEC_STRING (spec);
+
+ if (pspec->default_value) {
+ gchar *esc = g_strescape (pspec->default_value, NULL);
+ desc = g_strdup_printf ("\\"%s\\"", esc);
+ g_free (esc);
+ }
+ else
+ desc = g_strdup_printf ("NULL");
+ }
+#if GLIB_CHECK_VERSION (2, 25, 9)
+ else if (G_IS_PARAM_SPEC_VARIANT (spec)) {
+ GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec);
+
+ if (pspec->default_value)
+ desc = g_variant_print (pspec->default_value, TRUE);
+ else
+ desc = g_strdup ("NULL");
+ }
+#endif
+ else {
+ desc = g_strdup ("");
+ }
+
+ return desc;
+}
+
+
+static void
+output_object_args (FILE *fp, GType object_type)
+{
+ gpointer class;
+ const gchar *object_class_name;
+ guint arg;
+ gchar flags[16], *pos;
+ GParamSpec **properties;
+ guint n_properties;
+ gboolean child_prop;
+ gboolean style_prop;
+ gboolean is_pointer;
+ const gchar *type_name;
+ gchar *type_desc;
+ gchar *default_value;
+
+ if (G_TYPE_IS_OBJECT (object_type)) {
+ class = g_type_class_peek (object_type);
+ if (!class)
+ return;
+
+ properties = g_object_class_list_properties (class, &n_properties);
+ }
+#if GLIB_MAJOR_VERSION > 2 || (GLIB_MAJOR_VERSION == 2 && GLIB_MINOR_VERSION >= 3)
+ else if (G_TYPE_IS_INTERFACE (object_type)) {
+ class = g_type_default_interface_ref (object_type);
+
+ if (!class)
+ return;
+
+ properties = g_object_interface_list_properties (class, &n_properties);
+ }
+#endif
+ else
+ return;
+
+ object_class_name = g_type_name (object_type);
+
+ child_prop = FALSE;
+ style_prop = FALSE;
+
+ while (TRUE) {
+ qsort (properties, n_properties, sizeof (GParamSpec *), compare_param_specs);
+ for (arg = 0; arg < n_properties; arg++) {
+ GParamSpec *spec = properties[arg];
+ const gchar *nick, *blurb, *dot;
+
+ if (spec->owner_type != object_type)
+ continue;
+
+ pos = flags;
+ /* We use one-character flags for simplicity. */
+ if (child_prop && !style_prop)
+ *pos++ = 'c';
+ if (style_prop)
+ *pos++ = 's';
+ if (spec->flags & G_PARAM_READABLE)
+ *pos++ = 'r';
+ if (spec->flags & G_PARAM_WRITABLE)
+ *pos++ = 'w';
+ if (spec->flags & G_PARAM_CONSTRUCT)
+ *pos++ = 'x';
+ if (spec->flags & G_PARAM_CONSTRUCT_ONLY)
+ *pos++ = 'X';
+ *pos = 0;
+
+ nick = g_param_spec_get_nick (spec);
+ blurb = g_param_spec_get_blurb (spec);
+
+ dot = "";
+ if (blurb) {
+ int str_len = strlen (blurb);
+ if (str_len > 0 && blurb[str_len - 1] != '.')
+ dot = ".";
+ }
+
+ type_desc = describe_type (spec);
+ default_value = describe_default (spec);
+ type_name = get_type_name (spec->value_type, &is_pointer);
+ fprintf (fp, "<ARG>\\n"
+ "<NAME>%s::%s</NAME>\\n"
+ "<TYPE>%s%s</TYPE>\\n"
+ "<RANGE>%s</RANGE>\\n"
+ "<FLAGS>%s</FLAGS>\\n"
+ "<NICK>%s</NICK>\\n"
+ "<BLURB>%s%s</BLURB>\\n"
+ "<DEFAULT>%s</DEFAULT>\\n"
+ "</ARG>\\n\\n",
+ object_class_name, g_param_spec_get_name (spec), type_name,
+ is_pointer ? "*" : "", type_desc, flags, nick ? nick : "(null)",
+ blurb ? blurb : "(null)", dot, default_value);
+ g_free (type_desc);
+ g_free (default_value);
+ }
+
+ g_free (properties);
+
+#ifdef GTK_IS_CONTAINER_CLASS
+ if (!child_prop && GTK_IS_CONTAINER_CLASS (class)) {
+ properties = gtk_container_class_list_child_properties (class, &n_properties);
+ child_prop = TRUE;
+ continue;
+ }
+#endif
+
+#ifdef GTK_IS_CELL_AREA_CLASS
+ if (!child_prop && GTK_IS_CELL_AREA_CLASS (class)) {
+ properties = gtk_cell_area_class_list_cell_properties (class, &n_properties);
+ child_prop = TRUE;
+ continue;
+ }
+#endif
+
+#ifdef GTK_IS_WIDGET_CLASS
+#if GTK_CHECK_VERSION(2,1,0) && !GTK_CHECK_VERSION(3,89,2)
+ if (!style_prop && GTK_IS_WIDGET_CLASS (class)) {
+ properties = gtk_widget_class_list_style_properties (GTK_WIDGET_CLASS (class), &n_properties);
+ style_prop = TRUE;
+ continue;
+ }
+#endif
+#endif
+
+"""
+
+MAIN_CODE_END = """
+ break;
+ }
+}
+"""
+
+
+def run(options):
+
+ c_file = options.module + '-scan.c'
+ output = open(c_file, 'w')
+
+ base_filename = os.path.join(options.output_dir, options.module)
+ old_signals_filename = base_filename + '.signals'
+ new_signals_filename = base_filename + '.signals.new'
+ old_hierarchy_filename = base_filename + '.hierarchy'
+ new_hierarchy_filename = base_filename + '.hierarchy.new'
+ old_interfaces_filename = base_filename + '.interfaces'
+ new_interfaces_filename = base_filename + '.interfaces.new'
+ old_prerequisites_filename = base_filename + '.prerequisites'
+ new_prerequisites_filename = base_filename + '.prerequisites.new'
+ old_args_filename = base_filename + '.args'
+ new_args_filename = base_filename + '.args.new'
+
+ # generate a C program to scan the types
+
+ includes = ""
+ forward_decls = ""
+ get_types = ""
+ ntypes = 1
+
+ for line in open(options.types):
+ if line.startswith('#include'):
+ includes += line
+ elif line.startswith('%') or line.strip() == '':
+ continue
+ else:
+ line = line.strip()
+ get_types += ' object_types[i++] = ' + line + ' ();\n'
+ forward_decls += 'extern GType ' + line + ' (void);\n'
+ ntypes += 1
+
+ output.write(COMMON_INCLUDES)
+
+ if includes:
+ output.write(includes)
+ else:
+ output.write(forward_decls)
+
+ if options.query_child_properties:
+ output.write(QUERY_CHILD_PROPS_PROTOTYPE % options.query_child_properties)
+
+ # substitute local vars in the template
+ type_init_func = options.type_init_func
+ output.write(string.Template(MAIN_CODE).substitute(locals()))
+
+ if options.query_child_properties:
+ output.write(QUERY_CHILD_PROPS_CODE % options.query_child_properties)
+
+ output.write(MAIN_CODE_END)
+
+ output.close()
+
+ # Compile and run our file
+ if 'libtool' in options.cc:
+ o_file = options.module + '-scan.lo'
+ else:
+ o_file = options.module + '-scan.o'
+
+ x_file = options.module + '-scan' + config.exeext
+
+ stdout = ""
+ if not options.verbose:
+ stdout = ">/dev/null"
+
+ logging.debug('Intermediate scanner files: %s, %s, %s', c_file, o_file, x_file)
+
+ # Compiling scanner
+ command = '%s %s %s -c -o %s %s' % (options.cc, stdout, options.cflags, o_file, c_file)
+ res = subprocess.check_call(command, shell=True)
+ if res > 0:
+ logging.warning('Compilation of scanner failed: %d', res)
+ return res
+
+ # Linking scanner
+ command = '%s %s %s %s -o %s' % (options.ld, stdout, o_file, options.ldflags, x_file)
+ res = subprocess.check_call(command, shell=True)
+ if res > 0:
+ logging.warning('Linking of scanner failed: %d', res)
+ return res
+
+ # Running scanner
+ command = '%s ./%s' % (options.run, x_file)
+ res = subprocess.check_call(command, shell=True)
+ if res > 0:
+ logging.warning('Running scanner failed: %d', res)
+ return res
+
+ logging.debug('Scan complete')
+ if 'GTK_DOC_KEEP_INTERMEDIATE' not in os.environ:
+ os.unlink(c_file)
+ os.unlink(o_file)
+ os.unlink(x_file)
+ if 'libtool' in options.cc:
+ o_file = options.module + '-scan.o'
+ if os.path.exists(o_file):
+ os.unlink(o_file)
+ else:
+ logging.debug('Keeping generated sources for analysis: %s, %s, %s',
+ c_file, o_file, x_file)
+
+ common.UpdateFileIfChanged(old_signals_filename, new_signals_filename, False)
+ common.UpdateFileIfChanged(old_hierarchy_filename, new_hierarchy_filename, False)
+ common.UpdateFileIfChanged(old_interfaces_filename, new_interfaces_filename, False)
+ common.UpdateFileIfChanged(old_prerequisites_filename, new_prerequisites_filename, False)
+ common.UpdateFileIfChanged(old_args_filename, new_args_filename, False)
+
+ return 0
done
case "$flavour" in
- legacy-flat*)
+ legacy-flat|no-tmpl-flat)
makefile=gtk-doc.flat.make
;;
- legacy*)
- ;;
- no-tmpl-flat*)
- makefile=gtk-doc.notmpl-flat.make
- ;;
- no-tmpl*)
- makefile=gtk-doc.notmpl.make
+ legacy|no-tmpl)
;;
*)
echo "$progname: invalid value for --flavour" 1>&2
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
</legalnotice>
<revhistory>
+ <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>
</para>
<para>
- GTK-Doc consists of a number of perl scripts, each performing a different step
+ GTK-Doc consists of a number of python scripts, each performing a different step
in the process.
</para>
</para>
</listitem>
- <listitem>
- <para>
- <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.)
- </para>
- <note>
- <para>
- 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).
- </para>
- </note>
- </listitem>
-
<listitem>
<para>
<guilabel>Generating the XML and HTML/PDF.</guilabel>
document called <filename><package>.pdf</filename>.
</para>
<para>
- Files in <filename class='directory'>xml/</filename> and
+ Files in <filename class='directory'>xml/</filename> and
<filename class='directory'>html/</filename> directories are always
overwritten. One should never edit them directly.
</para>
<sect2 id="requirements">
<title>Requirements</title>
<para>
- <guilabel>Perl v5</guilabel> - the main scripts are in Perl.
+ <guilabel>python 2/3</guilabel> - the main scripts are written in python.
</para>
<para>
<guilabel>xsltproc</guilabel> - the xslt processor from libxslt
<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>
</para>
- <para>
- <guilabel>Python</guilabel> - optional - for gtkdoc-depscan
- </para>
<para>
One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> or
<guilabel>vim</guilabel> - optional - used for syntax highlighting of examples
<para>
Furthermore it is recommended that you have the following line inside
- you <filename>configure.ac</filename> script.
+ 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>
<title>Integration with automake</title>
<para>
- First copy the <filename>Makefile.am</filename> from the
+ 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.
+ 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>
<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.
+ hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<title>Limitations</title>
<para>
Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
+ <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
<code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
</para>
</note>
<para>
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>
+ 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>.
</para>
<para>
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
+ name given here should match the <FILE> tag in the
<filename><package>-sections.txt</filename> file.
</para>
</listitem>
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
+ of the supported tags can be found on
<ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
</para>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Inline program documentation</title>
+ <para>
+ You can document programs and their commandline interface using inline
+ documentation.
+ </para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>
+ Defines the start of a program documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>
+ Defines a short description of the program. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>
+ Defines the arguments, or list of arguments that the program can take.
+ (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>
+ See Also manual page section. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>
+ Argument(s) passed to the program and their description. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ A longer description of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Returns:</term>
+ <listitem>
+ <para>
+ Specificy what value(s) the program returns. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Example of program documentation.</title>
+ <example><title>Program documentation block</title>
+ <programlisting><![CDATA[
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+]]></programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>Useful DocBook tags</title>
In addition a few option elements are created in commented form. You can
review these and enable them as you like.
</para>
-
+
<para>
<example><title>Optional part in the master document</title>
<programlisting><![CDATA[
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
+ -->
]]></programlisting>
</example>
</para>
-
+
<para>
Finally you need to add new section whenever you introduce one. The
<link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
Blank lines are ignored and lines starting with a '#' are treated as
comment lines.
</para>
-
+
<note>
<para>
While the tags make the file look like xml, it is not. Please do not
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizing the documentation</title>
-
+
<para>
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.
</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
When using xml instead of sgml, one can actually name the master
document <filename><package>-docs.xml</filename>.
</para>
-
+
<para>
This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
in <filename>Makefile.am</filename>. When this is enabled, the
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
+ maintained section file can be as simple as running
<code>meld <package>-decl-list.txt <package>-sections.txt</code>.
</para>
-
+
<para>
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 you source control system and haven't yet switched, just
+ checked into your source control system and haven't yet switched, just
add the flag to <filename>configure.ac</filename> and you are done.
</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
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 any example that shows how the entity file is included
+ 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.
index.docbook \
fdl-appendix.xml
-HELP_LINGUAS = bn_IN de el en_GB es fr gl gu pt_BR sl sv ta te zh_CN
+HELP_LINGUAS = bn_IN cs de el en_GB es fr gl gu pt_BR sl sv ta te zh_CN
CLEANFILES = $(_HELP_LC_FILES) $(_HELP_LC_STAMPS) $(_HELP_MOFILES)
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
index.docbook \
fdl-appendix.xml
-HELP_LINGUAS = bn_IN de el en_GB es fr gl gu pt_BR sl sv ta te zh_CN
+HELP_LINGUAS = bn_IN cs de el en_GB es fr gl gu pt_BR sl sv ta te zh_CN
CLEANFILES = $(_HELP_LC_FILES) $(_HELP_LC_STAMPS) $(_HELP_MOFILES)
GITIGNOREFILES = ??_??/$(HELP_ID).xml ??/$(HELP_ID).xml
all: all-am
<revhistory>
<revision>
- <revnumber>1.24.1</revnumber>
- <date>30 May 2015</date>
+ <revnumber>1.25.1</revnumber>
+ <date>21 March 2016</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development version</revremark>
+ </revision>
+ <revision>
+ <revnumber>1.25</revnumber>
+ <date>21 March 2016</date>
<authorinitials>ss</authorinitials>
- <revremark>development version</revremark>
+ <revremark>bug fixes, test cleanups</revremark>
</revision>
<revision>
<revnumber>1.24</revnumber>
</para>
</listitem>
- <listitem>
- <para>
- <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.)
- </para>
- <note>
- <para>
- 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).
- </para>
- </note>
- </listitem>
-
<listitem>
<para>
<guilabel>Generating the XML and HTML/PDF.</guilabel>
document called <filename><package>.pdf</filename>.
</para>
<para>
- Files in <filename class="directory">xml/</filename> and
+ 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>
Furthermore it is recommended that you have the following line inside
- you <filename>configure.ac</filename> script.
+ 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>
<title>automake সহযোগে একত্রিত করার প্রণালী</title>
<para>
- First copy the <filename>Makefile.am</filename> from the
+ 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.
+ 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>
<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.
+ hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<title>Limitations</title>
<para>
Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
+ <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
<code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
</para>
</note>
<para>
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>
+ 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>.
</para>
<para>
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
+ name given here should match the <FILE> tag in the
<filename><package>-sections.txt</filename> file.
</para>
</listitem>
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
+ of the supported tags can be found on
<ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
</para>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Inline program documentation</title>
+ <para>
+ You can document programs and their commandline interface using inline
+ documentation.
+ </para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>
+ Defines the start of a program documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>
+ Defines a short description of the program. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>
+ Defines the arguments, or list of arguments that the program can take.
+ (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>
+ See Also manual page section. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>
+ Argument(s) passed to the program and their description. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ A longer description of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>প্রাপ্ত মান:</term>
+ <listitem>
+ <para>
+ Specificy what value(s) the program returns. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Example of program documentation.</title>
+ <example><title>Program documentation block</title>
+ <programlisting><![CDATA[
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+]]></programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>সুবিধাজনক DocBook ট্যাগ</title>
In addition a few option elements are created in commented form. You can
review these and enable them as you like.
</para>
-
+
<para>
<example><title>Optional part in the master document</title>
<programlisting><![CDATA[
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
+ -->
]]></programlisting>
</example>
</para>
-
+
<para>
Finally you need to add new section whenever you introduce one. The
<link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
Blank lines are ignored and lines starting with a '#' are treated as
comment lines.
</para>
-
+
<note>
<para>
While the tags make the file look like xml, it is not. Please do not
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizing the documentation</title>
-
+
<para>
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.
</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
When using xml instead of sgml, one can actually name the master
document <filename><package>-docs.xml</filename>.
</para>
-
+
<para>
This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
in <filename>Makefile.am</filename>. When this is enabled, the
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
+ maintained section file can be as simple as running
<code>meld <package>-decl-list.txt <package>-sections.txt</code>.
</para>
-
+
<para>
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 you source control system and haven't yet switched, just
+ checked into your source control system and haven't yet switched, just
add the flag to <filename>configure.ac</filename> and you are done.
</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
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 any example that shows how the entity file is included
+ 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.
--- /dev/null
+# Czech translation of gtk-doc.
+# Copyright (C) 2009 gtk-doc's COPYRIGHT HOLDER
+# This file is distributed under the same license as the gtk-doc package.
+# Marek Černocký <marek@manet.cz>, 2009, 2015, 2016.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: gtk-doc master\n"
+"POT-Creation-Date: 2016-09-06 04:43+0000\n"
+"PO-Revision-Date: 2016-09-18 10:27+0200\n"
+"Last-Translator: Marek Černocký <marek@manet.cz>\n"
+"Language-Team: čeština <gnome-cs-list@gnome.org>\n"
+"Language: cs\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=3; plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;\n"
+"X-Generator: Gtranslator 2.91.7\n"
+
+#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
+msgctxt "_"
+msgid "translator-credits"
+msgstr "Marek Černocký <marek@manet.cz>"
+
+#. (itstool) path: bookinfo/title
+#: C/index.docbook:12
+msgid "GTK-Doc Manual"
+msgstr "Příručka ke GTK-Doc"
+
+#. (itstool) path: bookinfo/edition
+#: C/index.docbook:13
+msgid "1.24.1"
+msgstr "1.24.1"
+
+#. (itstool) path: abstract/para
+#: C/index.docbook:14
+msgid "User manual for developers with instructions of GTK-Doc usage."
+msgstr "Uživatelská příručka pro vývojáře s instrukcemi k používání GTK-Doc."
+
+#. (itstool) path: authorgroup/author
+#: C/index.docbook:16
+msgid ""
+"<firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation> "
+"<address> <email>chris@wilddev.net</email> </address> </affiliation>"
+msgstr ""
+"<firstname>Chris</firstname> <surname>Lyttle</surname> "
+"<affiliation><address><email>chris@wilddev.net</email></address></"
+"affiliation>"
+
+#. (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>"
+msgstr ""
+"<firstname>Dan</firstname> <surname>Mueth</surname> "
+"<affiliation><address><email>d-mueth@uchicago.edu</email></address></"
+"affiliation>"
+
+#. (itstool) path: authorgroup/author
+#: C/index.docbook:34
+msgid ""
+"<firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> <affiliation> "
+"<address> <email>ensonic@users.sf.net</email> </address> </affiliation>"
+msgstr ""
+"<firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> "
+"<affiliation><address><email>ensonic@users.sf.net</email></address></"
+"affiliation>"
+
+#. (itstool) path: publisher/publishername
+#: C/index.docbook:45
+msgid "GTK-Doc project"
+msgstr "Projekt GTK-Doc"
+
+#. (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>"
+
+#. (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 and Chris Lyttle</holder>"
+
+#. (itstool) path: bookinfo/copyright
+#: C/index.docbook:52
+msgid "<year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder>"
+msgstr "<year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder>"
+
+#. (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>, "
+"Version 1.1 or any later version published by the Free Software Foundation "
+"with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A "
+"copy of the license is <link linkend=\"fdl\">included</link>."
+msgstr ""
+"Je povoleno kopírovat, šířit a/nebo upravovat tento dokument za podmínek "
+"<citetitle>GNU Free Documentation License</citetitle> ve verzi 1.1 nebo v "
+"jakékoli další verzi vydané nadací Free Software Foundation, s neměnnými "
+"oddíly, bez textů předních desek a bez textů zadních desek. Kopie licence je "
+"<link linkend=\"fdl\">součástí</link>."
+
+#. (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, and those trademarks are made aware to the members of the "
+"GNOME Documentation Project, the names have been printed in caps or initial "
+"caps."
+msgstr ""
+"Mnoho názvů použitých firmami k zviditelnění produktů nebo služeb jsou "
+"ochranné známky. Na místech, kde jsou tyto názvy v dokumentaci použity a "
+"členové Dokumentačního projektu GNOME jsou si vědomi skutečnosti, že se "
+"jedná o ochrannou známku, je takovýto název psán velkými písmeny celý nebo s "
+"velkým písmenem na začátku."
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:83
+msgid ""
+"<revnumber>1.25.1</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
+"authorinitials> <revremark>development version</revremark>"
+msgstr ""
+"<revnumber>1.25.1</revnumber> <date>21. březen 2016</date> "
+"<authorinitials>ss</authorinitials> <revremark>development version</"
+"revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:89
+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. březen 2016</date> <authorinitials>ss</"
+"authorinitials> <revremark>opravy chyb, pročištění testů</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+msgid ""
+"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fix</revremark>"
+msgstr ""
+"<revnumber>1.24</revnumber> <date>29. května 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>oprava chyby</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:101
+msgid ""
+"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fix</revremark>"
+msgstr ""
+"<revnumber>1.23</revnumber> <date>17. květen 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>oprava chyby</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:107
+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í</"
+"revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:113
+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í "
+"zastaralých věcí</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:119
+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. únor 2014</date> <authorinitials>ss</"
+"authorinitials> <revremark>opravy chyb, podpora značkovacího jazyka, "
+"vylepšení stylů</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:125
+msgid ""
+"<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes</revremark>"
+msgstr ""
+"<revnumber>1.19</revnumber> <date>05. červen 2013</date> <authorinitials>ss</"
+"authorinitials> <revremark>opravy chyb</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:131
+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. září 2011</date> <authorinitials>ss</"
+"authorinitials> <revremark>opravy chyb, zrychlení, podpora značkovacího "
+"jazyka</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:137
+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. únor 2011</date> <authorinitials>sk</"
+"authorinitials> <revremark>aktualizace kvůli neodkladné opravě chyby</"
+"revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:143
+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. leden 2011</date> <authorinitials>sk</"
+"authorinitials> <revremark>opravy chyb, vylepšení vzhledu</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:149
+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. květen 2010</date> <authorinitials>sk</"
+"authorinitials> <revremark>opravy chyb a regresí</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:155
+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. březen 2010</date> <authorinitials>sk</"
+"authorinitials> <revremark>opravy chyb a vylepšení výkonu</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:161
+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. prosinec 2009</date> "
+"<authorinitials>sk</authorinitials> <revremark>aktualizace poškozeného "
+"balíčku</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:167
+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. prosinec 2009</date> "
+"<authorinitials>sk</authorinitials> <revremark>nové funkce nástroje a opravy "
+"chyb</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:173
+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. listopad 2008</date> "
+"<authorinitials>mal</authorinitials> <revremark>přechod na doc-utils z "
+"GNOME</revremark>"
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:186
+msgid "Introduction"
+msgstr "Úvod"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:188
+msgid ""
+"This chapter introduces GTK-Doc and gives an overview of what it is and how "
+"it is used."
+msgstr ""
+"Tato kapitola je úvodem do GTK-Doc a podává přehled o tom, co to je a jak to "
+"použít."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:194
+msgid "What is GTK-Doc?"
+msgstr "Co je to GTK-Doc?"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:196
+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 "
+"also be used to document application code."
+msgstr ""
+"GTK-Doc se používá k dokumentaci kódu jazyka C. Typické použití je pro "
+"dokumentaci veřejného API knihoven, jako jsou knihovny GTK+ a GNOME. Lze jej "
+"ale použít i k dokumentaci aplikačního kódu."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:204
+msgid "How Does GTK-Doc Work?"
+msgstr "Jak GTK-Doc pracuje?"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:206
+msgid ""
+"GTK-Doc works by using documentation of functions placed inside the source "
+"files in specially-formatted comment blocks, or documentation added to the "
+"template files which GTK-Doc uses (though note that GTK-Doc will only "
+"document functions that are declared in header files; it won't produce "
+"output for static functions)."
+msgstr ""
+"GTK-Doc pracuje na základě dokumentace funkcí umístěné přímo v souborech se "
+"zdrojovým kódem ve speciálně formátovaných komentářových blocích, nebo "
+"dokumentace přidané do souborů šablon, které GTK-Doc používá (ačkoliv je "
+"nutno poznamenat, že GTK-Doc dokumentuje pouze funkce, které jsou "
+"deklarované v hlavičkových souborech; pro statické funkce žádný výstup "
+"nevytváří)."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:213
+msgid ""
+"GTK-Doc consists of a number of perl scripts, each performing a different "
+"step in the process."
+msgstr ""
+"GTK-Doc sestává z řady perlových skriptů, z nichž každý provádí jinou část "
+"procesu."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:218
+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:225
+msgid ""
+"<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)."
+msgstr ""
+"<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)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:235
+msgid ""
+"<guilabel>Gathering information about the code.</guilabel> "
+"<application>gtkdoc-scan</application> scans the header files of the code "
+"looking for declarations of functions, macros, enums, structs, and unions. "
+"It creates the file <filename><module>-decl-list.txt</filename> "
+"containing a list of the declarations, placing them into sections according "
+"to which header file they are in. On the first run this file is copied to "
+"<filename><module>-sections.txt</filename>. The author can rearrange "
+"the sections, and the order of the declarations within them, to produce the "
+"final desired order. The second file it generates is <filename><"
+"module>-decl.txt</filename>. This file contains the full declarations "
+"found by the scanner. If for some reason one would like some symbols to show "
+"up in the docs, where the full declaration cannot be found by the scanner or "
+"the declaration should appear differently, one can place entities similar to "
+"the ones in <filename><module>-decl.txt</filename> into <filename><"
+"module>-overrides.txt</filename>."
+msgstr ""
+"<guilabel>Shromáždění informací o kódu.</guilabel> <application>gtkdoc-scan</"
+"application> projde hlavičkové soubory kódu a vyhledá při tom deklarace "
+"funkcí, maker, výčtů, struktur a sjednocení. Tím se vytvoří soubor "
+"<filename><module>-decl-list.txt</filename> obsahující seznam "
+"deklarací, které jsou rozdělené do oddílů podle hlavičkového souboru, ze "
+"kterého pochází. Při prvním spuštění se tento soubor zkopíruje do "
+"<filename><module>-sections.txt</filename>. Autor může změnit "
+"uspořádání oddílů a jejich pořadí v rámci deklarací tak, jak to požaduje ve "
+"výsledku. Druhý soubor, který se vytvoří, je <filename><module>-decl."
+"txt</filename>. Tento soubor obsahuje úplné deklarace nalezené při "
+"procházení. Pokud byste z nějakého důvodu chtěli v dokumentaci zahrnout "
+"symbol, který při procházení nebyl nalezen, nebo jeho deklarace vypadá "
+"jinak, můžete jej umístit podobně jako v <filename><module>-decl.txt</"
+"filename> do <filename><module>-overrides.txt</filename>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:252
+msgid ""
+"<application>gtkdoc-scangobj</application> can also be used to dynamically "
+"query a library about any GObject subclasses it exports. It saves "
+"information about each object's position in the class hierarchy and about "
+"any GObject properties and signals it provides."
+msgstr ""
+"Dá se také použít <application>gtkdoc-scanobj</application> k dynamickým "
+"dotazům do knihoven na podtřídy objektu GObject, které exportují. Tím se "
+"uloží informace o pozici každého objektu v hierarchii tříd a o argumentech a "
+"signálech objektu GObject, které poskytují."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:258
+msgid ""
+"<application>gtkdoc-scanobj</application> should not be used anymore. It was "
+"needed in the past when GObject was still GtkObject inside gtk+."
+msgstr ""
+"<application>gtkdoc-scanobj</application> by se ale již používat nemělo. "
+"Bylo zapotřebí v minulosti, kdy byl GObject ještě GtkObject v rámci gtk+."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:265
+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>Generování souborů „šablon“.</guilabel> <application>gtkdoc-"
+"mktmpl</application> vytvoří v podsložce <filename class=\"directory\">tmpl/"
+"</filename> řadu souborů, za použití informací shromážděných v prvním kroku. "
+"(Poznamenejme, že může být spouštěn opakovaně. Tím se zajistí, že se žádná "
+"dokumentace neztratí.)"
+
+#. (itstool) path: note/para
+#: C/index.docbook:274
+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 ""
+"Od verze gtk-doc 1.9 můžete šablony vynechat. Doporučujeme lidem, aby "
+"udržovali dokumentaci v kódu. <application>gtkdocize</application> nyní "
+"podporuje přepínač <option>--flavour no-tmpl</option>, který způsobí, že "
+"makefile úplně přeskočí použití tmpl. Pokud jste nikdy ručně neměnili "
+"soubory v tmpl, tak tuto složku prosím odstraňte."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:286
+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."
+msgstr ""
+"<guilabel>Generování XML a HTML/PDF.</guilabel> <application>gtkdoc-mkdb</"
+"application> přemění soubory šablon na soubory XML v podsložce <filename "
+"class=\"directory\">xml/</filename>. Pokud zdrojový kód obsahuje dokumentaci "
+"funkcí za použití speciálních komentářových bloků, tak zde se sloučí. V "
+"případě, že není použitý žádný soubor šablon, načte se dokumentace pouze ze "
+"zdrojového kódu a introspektivních dat."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:295
+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> převádí soubory XML na soubory HTML "
+"v podsložce <filename class=\"directory\">html/</filename>. Obdobně "
+"<application>gtkdoc-mkpdf</application> převádí soubory XML na dokument PDF "
+"nazvaný <filename><balíček>.pdf</filename>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:301
+msgid ""
+"Files in <filename class=\"directory\">xml/</filename> and <filename class="
+"\"directory\">html/</filename> directories are always overwritten. One "
+"should never edit them directly."
+msgstr ""
+"Soubory ve složkách <filename class=\"directory\">xml/</filename> a "
+"<filename class=\"directory\">html/</filename> jsou vždy přepsány. Nikdy by "
+"neměly být upravovány přímo."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:309
+msgid ""
+"<guilabel>Fixing up cross-references between documents.</guilabel> After "
+"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
+"run to fix up any cross-references between separate documents. For example, "
+"the GTK+ documentation contains many cross-references to types documented in "
+"the GLib manual. When creating the source tarball for distribution, "
+"<application>gtkdoc-rebase</application> turns all external links into web-"
+"links. When installing distributed (pregenerated) docs the same application "
+"will try to turn links back to local links (where those docs are installed)."
+msgstr ""
+"<guilabel>Opravy křížových odkazů mezi dokumenty.</guilabel> Po "
+"nainstalování souborů HTML můžete spustit <application>gtkdoc-fixxref</"
+"application>, aby se opravily křížové odkazy mezi samostanými dokumenty. "
+"Například dokumentace GTK+ obsahuje křížové odkazy na typy zdokumentované v "
+"příručce GLib. Když vytváříte zdrojový balíček pro distribuci, "
+"<application>gtkdoc-rebase</application> předělá všechny externí odkazy na "
+"webové odkazy. Když se distribuovaná (předgenerovaná) dokumentace instaluje, "
+"pokusí se tatáž aplikace předělat odkazy zpátky na místní odkazy (na "
+"dokumenty, které jsou nainstalované)."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:327
+msgid "Getting GTK-Doc"
+msgstr "Jak získat GTK-Doc?"
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:330
+msgid "Requirements"
+msgstr "Požadavky"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:331
+msgid "<guilabel>Perl v5</guilabel> - the main scripts are in Perl."
+msgstr "<guilabel>Perl v5</guilabel> – hlavní skripty jsou v jazyce Perl."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:334
+msgid ""
+"<guilabel>xsltproc</guilabel> - the xslt processor from libxslt <ulink url="
+"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
+msgstr ""
+"<guilabel>xsltproc</guilabel> – procesor xslt z knihovny libxslt <ulink url="
+"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:338
+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>"
+msgstr ""
+"<guilabel>docbook-xsl</guilabel> – stylopisy XSL pro docbook <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:342
+msgid "<guilabel>Python</guilabel> - optional - for gtkdoc-depscan"
+msgstr "<guilabel>Python</guilabel> – pro gtkdoc-depscan (volitelné)"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:345
+msgid ""
+"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
+"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
+"examples"
+msgstr ""
+"Něco z <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
+"nebo <guilabel>vim</guilabel> – (volitelné) používá se pro zvýraznění "
+"syntaxe u příkladů"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:353
+msgid "About GTK-Doc"
+msgstr "O aplikaci GTK-Doc"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:355 C/index.docbook:369
+msgid "(FIXME)"
+msgstr "(DOPLNIT)"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:359
+msgid ""
+"(History, authors, web pages, mailing list, license, future plans, "
+"comparison with other similar systems.)"
+msgstr ""
+"(Historie, autoři, webové stránky, poštovní konference, licence, plány do "
+"budoucna, srovnání s ostatními podobnými systémy.)"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:367
+msgid "About this Manual"
+msgstr "O této příručce"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:373
+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:382
+msgid "Setting up your project"
+msgstr "Nastavení vašeho projektu"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:384
+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'. "
+"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."
+msgstr ""
+"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í."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:395
+msgid "Setting up a skeleton documentation"
+msgstr "Nastavení kostry dokumentace"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:397
+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 "
+"recommended to create another subdirectory with the name of the doc-package. "
+"For packages with just one library this step is not necessary."
+msgstr ""
+"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ý."
+
+#. (itstool) path: example/title
+#: C/index.docbook:406
+msgid "Example directory structure"
+msgstr "Příklad struktury složek"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:407
+#, no-wrap
+msgid ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/\n"
+" libmeep/\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+msgstr ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/\n"
+" libmeep/\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:404
+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:422 C/index.docbook:429
+msgid "Integration with autoconf"
+msgstr "Integrace s autoconf"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:424
+msgid ""
+"Very easy! Just add one line to your <filename>configure.ac</filename> "
+"script."
+msgstr ""
+"Velmi snadné! Stačí jen přidat jeden řádek do vašeho skriptu "
+"<filename>configure.ac</filename>."
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:430
+#, no-wrap
+msgid ""
+"\n"
+"# check for gtk-doc\n"
+"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+msgstr ""
+"\n"
+"# check for gtk-doc\n"
+"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+
+#. (itstool) path: example/title
+#: C/index.docbook:442
+msgid "Keep gtk-doc optional"
+msgstr "Ponechání gtk-doc jako volitelného"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:443
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\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"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:437
+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 "
+"below. Keep it as is, as gtkdocize is looking for <function>GTK_DOC_CHECK</"
+"function> at the start of a line. <_:example-1/>"
+msgstr ""
+"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-1/>"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:454
+msgid ""
+"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:"
+msgstr ""
+"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:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:460
+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:461
+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:462
+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:463
+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:467
+msgid ""
+"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)."
+msgstr ""
+"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)."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:475
+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."
+msgstr ""
+"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."
+
+#. (itstool) path: example/title
+#: C/index.docbook:483
+msgid "Preparation for gtkdocize"
+msgstr "Příprava pro gtkdocize"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:484
+#, no-wrap
+msgid ""
+"\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+msgstr ""
+"\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:489
+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 ""
+"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>."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:497
+msgid "Integration with automake"
+msgstr "Integrace s automake"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:499
+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 ""
+"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."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:510
+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 "
+"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."
+msgstr ""
+"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čů."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:524
+msgid "Integration with autogen"
+msgstr "Integrace s autogen"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:526
+msgid ""
+"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."
+msgstr ""
+"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."
+
+#. (itstool) path: example/title
+#: C/index.docbook:535
+msgid "Running gtkdocize from autogen.sh"
+msgstr "Spuštění gtkdocize z autogen.sh"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:536
+#, no-wrap
+msgid ""
+"\n"
+"gtkdocize || exit 1\n"
+msgstr ""
+"\n"
+"gtkdocize || exit 1\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:542
+msgid ""
+"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>."
+msgstr ""
+"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>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:551
+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 "
+"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)."
+msgstr ""
+"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í)."
+
+#. (itstool) path: sect1/title
+#. (itstool) path: example/title
+#: C/index.docbook:568 C/index.docbook:585
+msgid "Running the doc build"
+msgstr "Sestavení dokumentace"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:570
+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 "
+"give it the <option>--enable-gtk-doc</option> option. Otherwise manually run "
+"<filename>configure</filename> with this option afterwards."
+msgstr ""
+"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."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:577
+msgid ""
+"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>."
+msgstr ""
+"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>."
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:586
+#, no-wrap
+msgid ""
+"\n"
+"./autogen.sh --enable-gtk-doc\n"
+"make\n"
+msgstr ""
+"\n"
+"./autogen.sh --enable-gtk-doc\n"
+"make\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:592
+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, "
+"during the next chapter we tell you how to fill the pages with life."
+msgstr ""
+"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."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:600
+msgid "Integration with version control systems"
+msgstr "Integrace se systémem pro správu verzí"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:602
+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 ""
+"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>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:610
+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 ""
+"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>."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:618
+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:620
+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 "
+"in own makefiles (or other build tools)."
+msgstr ""
+"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)."
+
+#. (itstool) path: example/title
+#: C/index.docbook:627
+msgid "Documentation build steps"
+msgstr "Kroky sestavení dokumentace"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:628
+#, no-wrap
+msgid ""
+"\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 --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"
+msgstr ""
+"\n"
+"DOC_MODULE=meep\n"
+"// sources have changed\n"
+"gtkdoc-scan --module=$(DOC_MODULE) <zdrojová-složka>\n"
+"gtkdoc-scangobj --module=$(DOC_MODULE)\n"
+"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<zdrojová-složka>\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"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:642
+msgid ""
+"One will need to look at the <filename>Makefile.am</filename> and "
+"<filename>gtk-doc.mak</filename> to pick the extra options needed."
+msgstr ""
+"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>."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:649
+msgid "Integration with CMake build systems"
+msgstr "Integrace se sestavovacím systémem CMake"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:651
+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 ""
+"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>."
+
+#. (itstool) path: example/title
+#: C/index.docbook:661
+msgid "Example of using GTK-Doc from CMake"
+msgstr "Příklad použití GTK-Doc z CMake"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:662
+#, 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"
+"# Vytvoření cíle doc-libmeep.\n"
+"gtk_doc_add_module(\n"
+" libmeep ${CMAKE_SOURCE_DIR}/libmeep\n"
+" XML meep-docs.xml\n"
+" LIBRARIES libmeep\n"
+")\n"
+"\n"
+"# Sestavení doc-libmeep jako součásti výchozího cíle. Bez tohoto byste museli\n"
+"# ručně spouštět něco jako `make doc-libmeep`, aby se dokumentace sestavila.\n"
+"add_custom_target(documentation ALL DEPENDS doc-libmeep)\n"
+"\n"
+"# Instalace dokumentace. (Předpokládá to, že používáte modul CMake GNUInstallDirs\n"
+"# ke správnému nastavení proměnné CMAKE_INSTALL_DOCDIR).\n"
+"install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html\n"
+" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:659
+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:687
+msgid "Documenting the code"
+msgstr "Dokumentování v kódu"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:689
+msgid ""
+"GTK-Doc uses source code comment with a special syntax for code "
+"documentation. Further it retrieves information about your project structure "
+"from other sources. During the next section you will find all information "
+"about the syntax of the comments."
+msgstr ""
+"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ářů."
+
+#. (itstool) path: note/title
+#: C/index.docbook:697
+msgid "Documentation placement"
+msgstr "Umístění dokumentace"
+
+#. (itstool) path: note/para
+#: C/index.docbook:698
+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 "
+"information is often not updated and also that the file tend to cause "
+"conflicts with version control systems."
+msgstr ""
+"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í."
+
+#. (itstool) path: note/para
+#: C/index.docbook:704
+msgid ""
+"The avoid the aforementioned problems we suggest putting the documentation "
+"inside the sources. This manual will only describe this way of documenting "
+"code."
+msgstr ""
+"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."
+
+#. (itstool) path: example/title
+#: C/index.docbook:715 C/index.docbook:741
+msgid "GTK-Doc comment block"
+msgstr "Komentářový blok GTK-Doc"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:716
+#, no-wrap
+msgid ""
+"\n"
+"#ifndef __GTK_DOC_IGNORE__\n"
+"/* unparseable code here */\n"
+"#endif\n"
+msgstr ""
+"\n"
+"#ifndef __GTK_DOC_IGNORE__\n"
+"/* kód zde se nezpracovává */\n"
+"#endif\n"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:711
+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/>"
+msgstr ""
+"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-1/>"
+
+#. (itstool) path: note/title
+#: C/index.docbook:725
+msgid "Limitations"
+msgstr "Omezení"
+
+#. (itstool) path: note/para
+#: C/index.docbook:726
+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 ""
+"Uvědomte si, že GTK-Doc podporuje <code>#ifndef(__GTK_DOC_IGNORE__)</code>, "
+"ale ne <code>#if !defined(__GTK_DOC_IGNORE__)</code> nebo jiné kombinace."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:736
+msgid "Documentation comments"
+msgstr "Dokumentační komentáře"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:742
+#, no-wrap
+msgid ""
+"\n"
+"/**\n"
+" * identifier:\n"
+" * documentation ...\n"
+" */\n"
+msgstr ""
+"\n"
+"/**\n"
+" * identifikátor:\n"
+" * dokumentace …\n"
+" */\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:738
+msgid ""
+"A multiline comment that starts with an additional '*' marks a documentation "
+"block that will be processed by the GTK-Doc tools. <_:example-1/>"
+msgstr ""
+"Každý víceřádkový komentář, který je označený další „*“ navíc, je "
+"dokumentačním blokem a bude zpracovaný nástroji GTK-Doc. <_:example-1/>"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:751
+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 "
+"table showing identifiers)"
+msgstr ""
+"„identifikátor“ je jeden řádek s názvem položky, ke které se komentář "
+"vztahuje. Syntaxe se částečně liší podle položky. (DOPLNIT: přidat tabulku "
+"se seznamem identifikátorů)"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:757
+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)."
+msgstr ""
+"Blok „dokumentace“ se rovněž liší pro různé typy symbolů. Symboly, které "
+"přebírají parametry, jako jsou funkce nebo makra, mají nejdříve popsané "
+"parametry, za kterými následuje prázdný řádek (pouze „*“). Za ním pak "
+"následuje podrobný popis. Všechny řádky (mimo seznamu programů a oddílu "
+"CDATA), které obsahují „ *“ (mezera hvězdička) se převedou na zalomení "
+"odstavce. Pokud zalomení odstavce nechcete, změňte to na „ * “ (mezera "
+"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:774
+msgid ""
+"What it is: The name for a class or function can sometimes be misleading for "
+"people coming from a different background."
+msgstr ""
+"Co to je: Název třídy nebo funkce může být občas matoucí pro lidi, kteří "
+"používají něco jiného."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:780
+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:770
+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:795
+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:800
+msgid ""
+"Use @param to refer to parameters. Also use this when referring to "
+"parameters of other functions, related to the one being described."
+msgstr ""
+"Použijte @parametr pro odkaz na parametry. Použijte to rovněž, když se "
+"odkazujete na parametry jiných funkcí, vztahujících se k popisované funkci."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:806
+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:811
+msgid ""
+"Use #symbol to refer to other types of symbol, e.g. structs and enums and "
+"macros which don't take arguments."
+msgstr ""
+"Použijte #symbol pro odkaz na jiný typ symbolu, např. strukturu, výčet a "
+"makro, který nemá argumenty."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:817
+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:822
+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:827
+msgid ""
+"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
+"foo_bar() to refer to a vmethod."
+msgstr ""
+"Použijte #Struktura.pole pro odkaz na pole uvnitř struktury a #GObjectTřída."
+"neco() pro odkaz na virtuální metodu."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:789
+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. "
+"GTK-Doc comes to help by providing several useful abbreviations. <_:"
+"itemizedlist-1/>"
+msgstr ""
+"Jednou z výhod hypertextu, oproti prostému textu, je možnost mít v dokumentu "
+"odkazy. Zápis správných značek pro odkazy může být úmorná práce. GTK-Doc se "
+"vám snaží pomoci několika užitečnými zkratkami. <_:itemizedlist-1/>"
+
+#. (itstool) path: tip/para
+#: C/index.docbook:836
+msgid ""
+"If you need to use the special characters '<', '>', '()', '@', '%', or "
+"'#' in your documentation without GTK-Doc changing them you can use the XML "
+"entities \"&lt;\", \"&gt;\", \"&lpar;\", \"&rpar;\", \"&"
+"commat;\", \"&percnt;\" and \"&num;\" respectively or escape them "
+"with a backslash '\\'."
+msgstr ""
+"V případě, že potřebujete ve své dokumentaci použít speciální znaky „<“, "
+"„>“, „()“, „@“, „%“ nebo „#“, aniž by je GTK-Doc změnilo, můžete místo "
+"nich použít použít entity XML „&lt;“, „&gt;“, „&lpar;“, „&"
+"rpar;“, „&commat;“, „&percnt;“ a „&num;“ nebo únikovou sekvenci "
+"se zpětným lomítkem „\\“."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:845
+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 "
+"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 ""
+"DocBook toho ale umí více, než jen odkazy. Může mít také seznamy, příklady, "
+"nadpisy a obrázky. Od verze 1.20 je dána přednost použití jen podmnožiny ze "
+"základní syntaxe formátování textu. Tato podmnožina se nazývá <ulink url="
+"\"http://daringfireball.net/projects/markdown/\">Markdown</ulink>. "
+"Dokumentace ze starší verze GTK-Doc, která obsahuje Markdown, bude "
+"vygenerována tak, jak je. Například položky seznamu se objeví s pomlčkou na "
+"začátku."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:856
+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 ""
+"I když je markdown v současnosti preferovaný, můžete míchat oba dohromady. "
+"Má to jediné omezení v tom, že můžete použít docbook xml v markdown, ale "
+"markdown v docbook xml podporován není."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:862
+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 ""
+"Když ve starších vydáních GTK-Doc potřebujete podporu pro dodatečné "
+"formátování, musíte zapnout použití značek XML pro DocBook uvnitř "
+"dokumentačních komentářů pomocí <option>--xml-mode</option> (nebo <option>--"
+"sgml-mode</option>) v proměnné <symbol>MKDB_OPTIONS</symbol> v souboru "
+"<filename>Makefile.am</filename>."
+
+#. (itstool) path: example/title
+#: C/index.docbook:871
+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:872
+#, no-wrap
+msgid ""
+"\n"
+"/**\n"
+" * identifier:\n"
+" *\n"
+" * documentation paragraph ...\n"
+" *\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"
+" * 1. numbered list item\n"
+" *\n"
+" * 2. another numbered list item\n"
+" *\n"
+" * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)\n"
+" *\n"
+" * \n"
+" *\n"
+" * [A link to the heading anchor above][heading-two]\n"
+" *\n"
+" * A C-language example:\n"
+" * |[<!-- language=\"C\" -->\n"
+" * GtkWidget *label = gtk_label_new (\"Gorgeous!\");\n"
+" * ]|\n"
+" */\n"
+msgstr ""
+"\n"
+"/**\n"
+" * identifikátor:\n"
+" *\n"
+" * odstavec dokumentace…\n"
+" *\n"
+" * # Podnadpis #\n"
+" *\n"
+" * ## Podnadpis druhé úrovně\n"
+" *\n"
+" * # Podnadpis s kotvou pro odkazy # {#heading-two}\n"
+" *\n"
+" * další dokumentace:\n"
+" *\n"
+" * - položka seznamu 1\n"
+" *\n"
+" * Odstavec v rámci položky seznamu.\n"
+" *\n"
+" * - položka seznamu 2\n"
+" *\n"
+" * 1. číslovaná položka seznamu\n"
+" *\n"
+" * 2. další číslovaná položka seznamu\n"
+" *\n"
+" * Další odstavec. [Odkazy na webové stránky GNOME](http://www.gnome.org/)\n"
+" *\n"
+" * \n"
+" *\n"
+" * [Odkaz na nadpis pomocí kotvy uvedené výše][heading-two]\n"
+" *\n"
+" * Příklad v jazyce C:\n"
+" * |[<!-- language=\"C\" -->\n"
+" * GtkWidget *label = gtk_label_new (\"Paráda!\");\n"
+" * ]|\n"
+" */\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:911
+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+ Documentation Markdown Syntax Reference</ulink>."
+msgstr ""
+"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>."
+
+#. (itstool) path: tip/para
+#: C/index.docbook:917
+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 "
+"comment those symbols too. This helps other to understand you 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."
+msgstr ""
+"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."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:931
+msgid "Documenting sections"
+msgstr "Dokumentování oddílů"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:933
+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 "
+"description is also used inside the table of contents. All the @fields are "
+"optional."
+msgstr ""
+"Každý oddíl dokumentace obsahuje informaci o jedné třídě nebo modulu. Můžete "
+"do oddílu napsat blok, ve kterém je představíte. Stručný popis se rovněž "
+"použije v rámci tabulky s obsahem. Všechna @pole jsou volitelná."
+
+#. (itstool) path: example/title
+#: C/index.docbook:941
+msgid "Section comment block"
+msgstr "Komentářový blok oddílu"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:942
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\n"
+"/**\n"
+" * SECTION:meepapp\n"
+" * @short_description: třída plikace\n"
+" * @title: Aplikace Meep\n"
+" * @section_id:\n"
+" * @see_also: #MeepSettings\n"
+" * @stability: Stable\n"
+" * @include: meep/app.h\n"
+" * @image: application.png\n"
+" *\n"
+" * Třída aplikace starající se o…\n"
+" */\n"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:961
+msgid "SECTION:<name>"
+msgstr "SECTION:<název>"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:963
+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."
+msgstr ""
+"Název prováže oddíl dokumentace s příslušnou částí v souboru <filename><"
+"package>-sections.txt</filename>. Název zde musí odpovídat značce <"
+"SOUBOR> v souboru <filename><package>-sections.txt</filename>."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:972
+msgid "@short_description"
+msgstr "@short_description"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:974
+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."
+msgstr ""
+"Jednořádkový popis oddílu, který se později objeví za odkazy v tabulce s "
+"obsahem a na začátku stránky oddílu."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:981
+msgid "@title"
+msgstr "@title"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:983
+msgid ""
+"The section title defaults to <name> from the SECTION declaration. It "
+"can be overridden with the @title field."
+msgstr ""
+"Název oddílu se standardně zvolí podle <name> v deklaraci SECTION. Lze "
+"jej ale určit i přímo v poli @title."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:990
+msgid "@section_id"
+msgstr "@section_id"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:992
+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>."
+msgstr ""
+"Přepíše použití názvu jako identifikátoru oddílu. Pro objekty GObject se "
+"jako section_id použije <title> a pro ostatní oddíly to je <"
+"MODULE>-<title>."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1000
+msgid "@see_also"
+msgstr "@see_also"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1002
+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:1008
+msgid "@stability"
+msgstr "@stability"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1015
+msgid ""
+"Stable - The intention of a Stable interface is to enable arbitrary third "
+"parties to develop applications to these interfaces, release them, and have "
+"confidence that they will run on all minor releases of the product (after "
+"the one in which the interface was introduced, and within the same major "
+"release). Even at a major release, incompatible changes are expected to be "
+"rare, and to have strong justifications."
+msgstr ""
+"Stable (stabilní) – Záměrem stabilního rozhraní je umožnit libovolné třetí "
+"straně vyvinout aplikace využívající toto rozhraní, vydat je a moci se "
+"spolehnout, že poběží na všech podružných vydáních produktu (po té, co je "
+"rozhraní vydáno a v rámci stejné hlavní verze). I mezi hlavními vydáními se "
+"nekompatibilní změny očekávají zřídka v opravdu odůvodněných případech."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1027
+msgid ""
+"Unstable - Unstable interfaces are experimental or transitional. They are "
+"typically used to give outside developers early access to new or rapidly "
+"changing technology, or to provide an interim solution to a problem where a "
+"more general solution is anticipated. No claims are made about either source "
+"or binary compatibility from one minor release to the next."
+msgstr ""
+"Unstable (nestabilní) – Nestabilní rozhraní je experimentální a přechodné. "
+"Typicky bývá dáno vývojářům k dispozici kvůli včasnému přístupu k novým a "
+"rychle se měnícím technologiím nebo kvůli poskytnutí provizorního řešení "
+"problému, kdy je předpokládané více obecné řešení. Není žádná záruka ohledně "
+"zdrojové či binární kompatibility při přechodu z jedné podružné verze na "
+"následujíc."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1039
+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 "
+"specified and documented ways."
+msgstr ""
+"Private (soukromé) – Rozhraní, které může být použité v rámci zásobníku "
+"GNOME, ale není dokumentované pro koncového uživatele. Takové funkce by se "
+"měly používat jen určeným a dokumentovaným způsobem."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1048
+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 "
+"Internal."
+msgstr ""
+"Internal (interní) – Rozhraní, které je určené pro interní potřeby modulu a "
+"nevyžaduje dokumentaci pro koncového uživatele. Funkce, které jsou "
+"nedokumentované, jsou považované za interní."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1010
+msgid ""
+"An informal description of the stability level this API has. We recommend "
+"the use of one of these terms: <_:itemizedlist-1/>"
+msgstr ""
+"Informační popis úrovně stability tohoto API. Doporučujeme použít jeden z "
+"těchto termínů: <_:itemizedlist-1/>"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1060
+msgid "@include"
+msgstr "@include"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1062
+msgid ""
+"The <literal>#include</literal> files to show in the section synopsis (a "
+"comma separated list), overriding the global value from the <link linkend="
+"\"metafiles_sections\">section file</link> or command line. This item is "
+"optional."
+msgstr ""
+"Seznam souborů z <literal>#include</literal> oddělených čárkou, aby se "
+"zobrazily v oddílu anotace. Přepisuje globální hodnotu ze <link linkend="
+"\"metafiles_sections\">souboru oddílů</link> nebo příkazové řádky. Tato "
+"položka je volitelná."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1071
+msgid "@image"
+msgstr "@image"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1073
+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 "
+"a class or a diagram of its relationship to other classes. This item is "
+"optional."
+msgstr ""
+"Obrázek, který se má zobrazit na začátku referenční stránky k tomuto oddílu. "
+"Často se jedná o nějaký nákres, který schématicky znázorňuje podobu třídy "
+"nebo nákres se vztahy vůči jiným třídám. Tato položka je volitelná."
+
+#. (itstool) path: tip/para
+#: C/index.docbook:1084
+msgid ""
+"To avoid unnecessary recompilation after doc-changes put the section docs "
+"into the c-source where possible."
+msgstr ""
+"Aby se po změně dokumentace předešlo rekompilacím, které nejsou nutné, "
+"vložte, kde je to možné, dokumentaci oddílu do zdrojového kódu c."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1093
+msgid "Documenting symbols"
+msgstr "Dokumentování symbolů"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1095
+msgid ""
+"Each symbol (function, macro, struct, enum, signal and property) is "
+"documented in a separate block. The block is best placed close to the "
+"definition of the symbols so that it is easy to keep them in sync. Thus "
+"functions are usually documented in the c-source and macros, structs and "
+"enums in the header file."
+msgstr ""
+"Každý symbol (funkce, makro, struktura, výčet, signál a vlastnost) se "
+"dokumentuje v odděleném bloku. Blok je nejlepší umístit v rámci definice "
+"symbolu, protože se tak snadno udržuje synchronizovaný. Z tohoto důvodu se "
+"funkce obvykle dokumentují ve zdrojovém kódu C a makra, struktury a výčty v "
+"hlavičkovém souboru."
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1103 C/index.docbook:1169
+msgid "General tags"
+msgstr "Obecné značky"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1105
+msgid ""
+"You can add versioning information to all documentation elements to tell "
+"when an API was introduced, or when it was deprecated."
+msgstr ""
+"Informace o verzích můžete přidat ke všem prvkům dokumentace, abyste "
+"sdělili, kdy bylo API zavedeno, nebo kdy bylo označeno za zastaralé."
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1110
+msgid "Versioning Tags"
+msgstr "Značky pro verzování"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1111
+msgid "Since:"
+msgstr "Since:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1113
+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:1118
+msgid "Deprecated:"
+msgstr "Deprecated:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1120
+msgid ""
+"Paragraph denoting that this function should no be used anymore. The "
+"description should point the reader to the new API."
+msgstr ""
+"Odstavec upozorňující, že by se tato funkce neměla nadále používat. Popis by "
+"měl čtenáře odkazovat na nové API."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1128
+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 ""
+"Můžete také ke všem prvkům dokumentace přidat informaci o stabilitě, abyste "
+"dali najevo, že je u API zaručena stabilita pro všechna následující "
+"minoritní vydání projektu."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1134
+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 ""
+"Výchozí stabilitu pro všechny prvky dokumentace můžete pomocí argumentu "
+"<option>--default-stability</option> s jednou u níže uvedených hodnot předat "
+"do <application>gtkdoc-mkdb</application>."
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1140
+msgid "Stability Tags"
+msgstr "Značky pro stabilitu"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1141
+msgid "Stability: Stable"
+msgstr "Stability: Stable"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1143
+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 ""
+"Označuje prvek jako stabilní. Je to určeno pro veřejná API, která zaručují, "
+"že zůstanou stabilní po všechna minoritní vydání projektu."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1150
+msgid "Stability: Unstable"
+msgstr "Stability: Unstable"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1152
+msgid ""
+"Mark the element as unstable. This is for public APIs which are released as "
+"a preview before being stabilised."
+msgstr ""
+"Označuje prvek jako nestabilní. Je to určeno pro veřejná API, která jsou "
+"vydána jako ukázky před tím, než jsou stabilizována."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1158
+msgid "Stability: Private"
+msgstr "Stability: Private"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1160
+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 ""
+"Označuje prvek jako soukromý. Je to určeno pro rozhraní, která mohou být "
+"použita přímo v modulu, ale ne kterýmikoliv třetími stranami."
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1170
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\n"
+"/**\n"
+" * foo_get_bar:\n"
+" * @foo: nějaké něco\n"
+" *\n"
+" * Získá @foo něčeho.\n"
+" *\n"
+" * Returns: @foo něčeho\n"
+" *\n"
+" * Since: 2.6\n"
+" * Deprecated: 2.12: Místo toho použijte foo_baz_get_bar().\n"
+" */\n"
+"Bar *\n"
+"foo_get_bar(Foo *foo)\n"
+"{\n"
+"...\n"
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1190 C/index.docbook:1200
+msgid "Annotations"
+msgstr "Anotace"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1192
+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 ""
+"Dokumentační bloky mohou obsahovat anotační štítky. Tyto štítky budou "
+"zpracovány jako vysvětlivky popisující jejich význam. Používají se "
+"introspekcí objektu GObjekt k vygenerování vazby na další jazyky. Podrobný "
+"seznam podporovaných štítků můžete najít na <ulink url=\"http://live.gnome."
+"org/GObjectIntrospection/Annotations\" type=\"http\">wiki</ulink>."
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1201
+#, 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 ""
+"\n"
+"/**\n"
+" * foo_get_bar: (annotation)\n"
+" * @foo: (annotation): nějaké něco\n"
+" *\n"
+" * Získá @foo něčeho.\n"
+" *\n"
+" * Returns: (annotation): @foo něčeho\n"
+" */\n"
+"...\n"
+"/**\n"
+" * foo_set_bar_using_the_frobnicator: (annotation) (annotation)\n"
+" * (annotation) …\n"
+" * @foo: (annotation) (annotation) …: nějaké něco\n"
+" *\n"
+" * Nastaví něco na @foo.\n"
+" */\n"
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1222 C/index.docbook:1251
+msgid "Function comment block"
+msgstr "Komentářový blok pro funkci"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1228
+msgid ""
+"Document whether returned objects, lists, strings, etc, should be freed/"
+"unrefed/released."
+msgstr ""
+"Zdokumentovat, jestli je třeba vracené objekty, seznamy, řetězce apod. "
+"uvolnit z paměti."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1234
+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:1239
+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:1224 C/index.docbook:1310
+msgid "Please remember to: <_:itemizedlist-1/>"
+msgstr "Nezapomeňte prosím: <_:itemizedlist-1/>"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1246
+msgid ""
+"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
+"private. They are treated like static functions."
+msgstr ""
+"Gtk-doc předpokládá, že všechny symboly (makra, funkce) začínající znakem "
+"„_“, jsou soukromé. Potom se s nimi zachází jako se statickými funkcemi."
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1252
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\n"
+"/**\n"
+" * function_name:\n"
+" * @par1: popis parametru 1. Může zabírat více jak\n"
+" * jeden řádek.\n"
+" * @par2: popis parametru 2\n"
+" * @...: seznam proměnných parametrů zakončených NULL\n"
+" *\n"
+" * Zde pokračuje popis funkce. K odkazu na parametr můžete použit @par1,\n"
+" * takže bude ve výstupu zvýrazněný. Můžete také použít %constant pro\n"
+" * konstanty, function_name() pro funkce a #GtkWidget pro odkazy na jiné\n"
+" * deklarace (které mohou být zdokumentované jinde).\n"
+" *\n"
+" * Returns: celé číslo.\n"
+" *\n"
+" * Since: 2.2\n"
+" * Deprecated: 2.18: Místo toho použijte other_function().\n"
+" */\n"
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1273
+msgid "Function tags"
+msgstr "Značky pro funkce"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1274 C/index.docbook:1481
+msgid "Returns:"
+msgstr "Returns:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1276
+msgid "Paragraph describing the returned result."
+msgstr "Odstavec popisující vracený výsledek."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1281
+msgid "@...:"
+msgstr "@…:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1283
+msgid ""
+"In case the function has variadic arguments, you should use this tag "
+"(@Varargs: does also work for historic reasons)."
+msgstr ""
+"Když má funkce proměnný počet argumentů, měli byste použít tuto značku (z "
+"historických důvodů funguje i @Varargs:)."
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1293 C/index.docbook:1295
+msgid "Property comment block"
+msgstr "Komentářový blok pro vlastnost"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1296
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\n"
+"/**\n"
+" * SomeWidget:some-property:\n"
+" *\n"
+" * Zde vlastnost zdokumentujte.\n"
+" */\n"
+"g_object_class_install_property (object_class, PROP_SOME_PROPERTY, …);\n"
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1308 C/index.docbook:1327
+msgid "Signal comment block"
+msgstr "Komentářový blok pro signál"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1314
+msgid ""
+"Document when the signal is emitted and whether it is emitted before or "
+"after other signals."
+msgstr ""
+"Zdokumentovat, kdy je signál vyslán a jestli je vyslána před nebo po "
+"ostatních signálech."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1320
+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:1328
+#, 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"
+msgstr ""
+"\n"
+"/**\n"
+" * FooWidget::foobarized:\n"
+" * @widget: widget, který signál přijímá\n"
+" * @foo: nějaké něco\n"
+" * @bar: jiné něco\n"
+" *\n"
+" * Signál ::foobarized je vyslán pokaždé, když někdo zkusí něco s @widget.\n"
+" */\n"
+"foo_signals[FOOBARIZE] =\n"
+" g_signal_new (\"foobarize\",\n"
+" ...\n"
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1345 C/index.docbook:1346
+msgid "Struct comment block"
+msgstr "Komentářový blok pro strukturu"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1347
+#, no-wrap
+msgid ""
+"\n"
+"/**\n"
+" * FooWidget:\n"
+" * @bar: some #gboolean\n"
+" *\n"
+" * This is the best widget, ever.\n"
+" */\n"
+"typedef struct _FooWidget {\n"
+" GtkWidget parent_instance;\n"
+"\n"
+" gboolean bar;\n"
+"} FooWidget;\n"
+msgstr ""
+"\n"
+"/**\n"
+" * FooWidget:\n"
+" * @bar: nějaká #gboolean\n"
+" *\n"
+" * Tohle je ten nejlepší widget.\n"
+" */\n"
+"typedef struct _FooWidget {\n"
+" GtkWidget parent_instance;\n"
+"\n"
+" gboolean bar;\n"
+"} FooWidget;\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1362
+msgid ""
+"Use <code>/*< private >*/</code> before the private struct fields you "
+"want to hide. Use <code>/*< public >*/</code> for the reverse "
+"behaviour."
+msgstr ""
+"Před privátními poli struktury použijte <code>/*< private >*/</code>, "
+"abyste je skryli. K přesně opačnému účelu se používá <code>/*< public >"
+"*/</code>."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1368
+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 ""
+"Pokud je prvním polem „g_iface“, „parent_instance“ nebo „parent_class“, bude "
+"za privátní považováno automaticky a není to zapotřebí zmiňovat v "
+"komentářovém bloku."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1374
+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 "
+"vmethods (as this is how they can be documented). For the GObject itself one "
+"can use the related section docs, having a separate block for the instance "
+"struct would be useful if the instance has public fields. One disadvantage "
+"here is that this creates two index entries of the same name (the structure "
+"and the section)."
+msgstr ""
+"Komentářové bloky struktur můžete použít také pro objekty GObject a třídy "
+"GObjectClass. Obvykle je rozumné přidat komentářový blok pro třídu, pokud má "
+"virtuální metody (protože to je způsob, jakým je lze zdokumentovat). Pro "
+"vlastní GObject je možné použít příslušnou dokumentaci oddílu, který bude "
+"mít samostatný blok pro strukturu instance, což se může hodit, když má "
+"instance veřejná pole. Jedinou nevýhodou je, že se tím vytvoří dvě položky v "
+"rejstříku se stejným názvem (struktura a oddíl)."
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1386 C/index.docbook:1387
+msgid "Enum comment block"
+msgstr "Komentářový blok pro výčty"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1388
+#, no-wrap
+msgid ""
+"\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"
+"typedef enum {\n"
+" SOMETHING_FOO,\n"
+" SOMETHING_BAR,\n"
+" /*< private >*/\n"
+" SOMETHING_COUNT\n"
+"} Something;\n"
+msgstr ""
+"\n"
+"/**\n"
+" * Something:\n"
+" * @SOMETHING_FOO: nějaké něco\n"
+" * @SOMETHING_BAR: jiné něco\n"
+" *\n"
+" * Výčtové hodnoty používané pro určení věci.\n"
+" */\n"
+"typedef enum {\n"
+" SOMETHING_FOO,\n"
+" SOMETHING_BAR,\n"
+" /*< private >*/\n"
+" SOMETHING_COUNT\n"
+"} Something;\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1405
+msgid ""
+"Use <code>/*< private >*/</code> before the private enum values you "
+"want to hide. Use <code>/*< public >*/</code> for the reverse "
+"behaviour."
+msgstr ""
+"Před privátními výčtovými hodnotami použijte <code>/*< private >*/</"
+"code>, abyste je skryli. K přesně opačnému účelu se používá <code>/*< "
+"public >*/</code>."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1416
+msgid "Inline program documentation"
+msgstr "Dokumentaci k vloženým programům"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1417
+msgid ""
+"You can document programs and their commandline interface using inline "
+"documentation."
+msgstr ""
+"Programy a jejich rozhraní příkazového řádku můžete zdokumentovat pomocí "
+"vložené dokumentace."
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1423
+msgid "Tags"
+msgstr "Značky"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1425
+msgid "PROGRAM"
+msgstr "PROGRAM"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1428
+msgid "Defines the start of a program documentation."
+msgstr "Definuje začátek dokumentace k programu."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1435
+msgid "@short_description:"
+msgstr "@short_description:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1437
+msgid "Defines a short description of the program. (Optional)"
+msgstr "Definuje krátký popis programu. (volitelné)"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1444
+msgid "@synopsis:"
+msgstr "@synopsis:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1446
+msgid ""
+"Defines the arguments, or list of arguments that the program can take. "
+"(Optional)"
+msgstr ""
+"Definuje argumenty nebo seznam argumentů, které program přebírá. (volitelné)"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1454
+msgid "@see_also:"
+msgstr "@see_also:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1456
+msgid "See Also manual page section. (Optional)"
+msgstr "Část stránky oddílu „Viz také“. (volitelné)"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1463
+msgid "@arg:"
+msgstr "@arg:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1465
+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:1472
+msgid "Description:"
+msgstr "Description:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1474
+msgid "A longer description of the program."
+msgstr "Úplný popis programu."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1483
+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:1492
+msgid "Example of program documentation."
+msgstr "Příklad dokumentace k programu."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1493
+msgid "Program documentation block"
+msgstr "Komentářový blok pro program"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1494
+#, 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 ""
+"\n"
+"/**\n"
+" * PROGRAM:test-program\n"
+" * @short_description: Testovací program\n"
+" * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*\n"
+" * @see_also: test(1)\n"
+" * @--arg1 *arg*: nastaví arg1 do *arg*\n"
+" * @--arg2 *arg*: nastaví arg2 do *arg*\n"
+" * @-v, --version: Vypíše verzi programu\n"
+" * @-h, --help: Vypíše nápovědu k programu\n"
+" *\n"
+" * Úplný popis programu.\n"
+" *\n"
+" * Returns: Vrací nulu při úspěchu, nenulovou hodnotu při selhání.\n"
+" */\n"
+"int main(int argc, char *argv[])\n"
+"{\n"
+"\treturn 0;\n"
+"}\n"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1520
+msgid "Useful DocBook tags"
+msgstr "Užitečné značky DocBook"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1522
+msgid ""
+"Here are some DocBook tags which are most useful when documenting the code."
+msgstr ""
+"Zde jsou některé značky DocBook, které mají pro dokumentaci kódu největší "
+"význam."
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1531
+#, no-wrap
+msgid ""
+"\n"
+"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
+msgstr ""
+"\n"
+"<link linkend=\"glib-Hash-Tables\">Hašovací tabulky</link>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1527
+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. "
+"For most pages this is currently the part (\"gtk\", \"gdk\", \"glib\") and "
+"then the page title (\"Hash Tables\"). For widgets it is just the class "
+"name. Spaces and underscores are converted to '-' to conform to SGML/XML."
+msgstr ""
+"Odkaz na jiný oddíl v dokumentaci GTK: <_:informalexample-1/> Odkazem je id "
+"SGML/XML v první položce stránky, na kterou chcete odkazovat. Pro většinu "
+"stránek je to v současnosti část („gtk“, „gdk“, „glib“) a potom název "
+"stránky („Hašovací tabulka“). Pro ovládací prvky je to název třídy. Mezery a "
+"podtržítka se převedou na „-“, aby to vyhovovalo SGML/XML."
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1544
+#, no-wrap
+msgid ""
+"\n"
+"<function>...</function>\n"
+msgstr ""
+"\n"
+"<function>…</function>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1541
+msgid ""
+"To refer to an external function, e.g. a standard C function: <_:"
+"informalexample-1/>"
+msgstr ""
+"Odkaz na externí funkci, například standardní funkci C: <_:informalexample-1/"
+">"
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1553
+#, no-wrap
+msgid ""
+"\n"
+"<example>\n"
+" <title>Using a GHashTable.</title>\n"
+" <programlisting>\n"
+" ...\n"
+" </programlisting>\n"
+"</example>\n"
+msgstr ""
+"\n"
+"<example>\n"
+" <title>Používání GHashTable.</title>\n"
+" <programlisting>\n"
+" …\n"
+" </programlisting>\n"
+"</example>\n"
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1564
+#, no-wrap
+msgid ""
+"\n"
+"<informalexample>\n"
+" <programlisting>\n"
+" ...\n"
+" </programlisting>\n"
+"</informalexample>\n"
+msgstr ""
+"\n"
+"<informalexample>\n"
+" <programlisting>\n"
+" …\n"
+" </programlisting>\n"
+"</informalexample>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1550
+msgid ""
+"To include example code: <_:informalexample-1/> or possibly this, for very "
+"short code fragments which don't need a title: <_:informalexample-2/> For "
+"the latter GTK-Doc also supports an abbreviation: |[ ... ]|"
+msgstr ""
+"Vložení ukázky kódu: <_:informalexample-1/> nebo pro velmi krátké úseky "
+"kódu, které nepotřebují nadpisy, je případně možné i: <_:informalexample-2/> "
+"V novějších verzích GTK-Doc je také podporované zkracování: |[ … ]|"
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1583
+#, no-wrap
+msgid ""
+"\n"
+"<itemizedlist>\n"
+" <listitem>\n"
+" <para>\n"
+" ...\n"
+" </para>\n"
+" </listitem>\n"
+" <listitem>\n"
+" <para>\n"
+" ...\n"
+" </para>\n"
+" </listitem>\n"
+"</itemizedlist>\n"
+msgstr ""
+"\n"
+"<itemizedlist>\n"
+" <listitem>\n"
+" <para>\n"
+" …\n"
+" </para>\n"
+" </listitem>\n"
+" <listitem>\n"
+" <para>\n"
+" …\n"
+" </para>\n"
+" </listitem>\n"
+"</itemizedlist>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1580
+msgid "To include bulleted lists: <_:informalexample-1/>"
+msgstr "Vložení seznamu s odrážkami: <_:informalexample-1/>"
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1603
+#, no-wrap
+msgid ""
+"\n"
+"<note>\n"
+" <para>\n"
+" Make sure you free the data after use.\n"
+" </para>\n"
+"</note>\n"
+msgstr ""
+"\n"
+"<note>\n"
+" <para>\n"
+" Ujistěte se, že data po použití uvolníte.\n"
+" </para>\n"
+"</note>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1600
+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:1616
+#, no-wrap
+msgid ""
+"\n"
+"<type>unsigned char</type>\n"
+msgstr ""
+"\n"
+"<type>unsigned char</type>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1613
+msgid "To refer to a type: <_:informalexample-1/>"
+msgstr "Odkaz na typ: <_:informalexample-1/>"
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1625
+#, no-wrap
+msgid ""
+"\n"
+"<structname>XFontStruct</structname>\n"
+msgstr ""
+"\n"
+"<structname>XFontStruct</structname>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1622
+msgid ""
+"To refer to an external structure (not one described in the GTK docs): <_:"
+"informalexample-1/>"
+msgstr ""
+"Odkaz na externí strukturu (která není popsaná v dokumentaci GTK): <_:"
+"informalexample-1/>"
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1634
+#, no-wrap
+msgid ""
+"\n"
+"<structfield>len</structfield>\n"
+msgstr ""
+"\n"
+"<structfield>len</structfield>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1631
+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:1643
+#, no-wrap
+msgid ""
+"\n"
+"<classname>GtkWidget</classname>\n"
+msgstr ""
+"\n"
+"<classname>GtkWidget</classname>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1640
+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 "
+"to the GtkWidget page - see <link linkend=\"documenting_syntax\">the "
+"abbreviations</link>)."
+msgstr ""
+"Pro odkaz na název třídy by se dal nejspíše použít: <_:informalexample-1/> "
+"ale pravděpodobně místo toho použijete #GtkWidget (aby se automaticky "
+"vytvořil odkaz na stránku ovládacího prvku, viz <link linkend="
+"\"documenting_syntax\">zkratky</link>)."
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1654
+#, no-wrap
+msgid ""
+"\n"
+"<emphasis>This is important</emphasis>\n"
+msgstr ""
+"\n"
+"<emphasis>Toto je důležité</emphasis>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1651
+msgid "To emphasize text: <_:informalexample-1/>"
+msgstr "Zvýrazněný text: <_:informalexample-1/>"
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1663
+#, no-wrap
+msgid ""
+"\n"
+"<filename>/home/user/documents</filename>\n"
+msgstr ""
+"\n"
+"<filename>/home/user/documents</filename>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1660
+msgid "For filenames use: <_:informalexample-1/>"
+msgstr "Pro název souboru použijte: <_:informalexample-1/>"
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1672
+#, no-wrap
+msgid ""
+"\n"
+"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
+msgstr ""
+"\n"
+"<keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1669
+msgid "To refer to keys use: <_:informalexample-1/>"
+msgstr "Odkaz na použití klávesy: <_:informalexample-1/>"
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:1682
+msgid "Filling the extra files"
+msgstr "Vyplňování dodatečných souborů"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1684
+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>-docs.xml</filename> (in the past .sgml), "
+"<filename><package>-sections.txt</filename>."
+msgstr ""
+"Mimo komentářů vložených ve zdrojovém kódu je zde ještě pár dodatečných "
+"souborů, které je potřeba udržovat:<filename><balíček>.types</"
+"filename>, <filename><balíček>-docs.xml</filename> (dříve .sgml) a "
+"<filename><balíček>-sections.txt</filename>."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1693
+msgid "Editing the types file"
+msgstr "Úprava souboru s typy"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1695
+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 ""
+"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>."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1704
+msgid "Example types file snippet"
+msgstr "Příklad úryvku ze souboru typů"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1705
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\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"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1716
+msgid ""
+"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
+"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
+"<filename>Makefile.am</filename>. If you use this approach you should not "
+"dist the types file nor have it under version control."
+msgstr ""
+"Od GTK-Doc verze 1.8 vám tento seznam vygeneruje <application>gtkdoc-scan</"
+"application>. Stačí jen přidat „--rebuild-types“ do SCAN_OPTIONS v "
+"<filename>Makefile.am</filename>. Pokud tento přístup použijete, neměli "
+"byste soubor s typy šířit do správy verzí."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1725
+msgid "Editing the master document"
+msgstr "Úprava hlavního dokumentu"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1727
+msgid ""
+"GTK-Doc produces documentation in DocBook SGML/XML. When processing the "
+"inline source comments, the GTK-Doc tools generate one documentation page "
+"per class or module as a separate file. The master document includes them "
+"and place them in an order."
+msgstr ""
+"GTK-Doc produkuje dokumentaci v SGML/XML standardu DocBook. Když se "
+"zpracovávají komentáře vložené ve zdrojovém kódu, generují nástroje GTK-Doc "
+"pro každou třídu nebo modul jednu stránku dokumentace jako samostatný "
+"soubor. Všechny jsou pak uvedené seřazené v hlavním dokumentu."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1734
+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 ""
+"Jakmile pro vás GTK-Doc vytvoří šablonu hlavního dokumentu, při pozdějším "
+"spuštění již do ní nezasahuje. To znamená, že můžete dokumentaci bez omezení "
+"strukturovat. A to včetně seskupování stránek a přidávání doplňujících "
+"stránek. GTK-Doc má v současnosti testovací sadu, ve které je také hlavní "
+"dokument vytvořen znovu od začátku. Je dobré se čas od času do něj "
+"nahlédnout, jestli se v něm neobjevily nějaké nové věci."
+
+#. (itstool) path: tip/para
+#: C/index.docbook:1744
+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 "
+"documentation is that it is easy to link for the tutorial to symbol "
+"documentation. Apart chances are higher that the tutorial gets updates along "
+"with the library."
+msgstr ""
+"Nevytvářejte výukové dokumenty (tutorial) jako zvláštní dokumenty. Napište "
+"je jako zvláštní kapitolu. Výhodou přímého spojení výukového dokumentu k "
+"vaší knihovně s dokumentací API je snadné vytváření odkazů pro symboly. "
+"Zvyšuje se tím také šance, že výukový dokument bude reflektovat aktualizace "
+"v knihovně."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1753
+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 "
+"which you should take care of."
+msgstr ""
+"Nyní se podívejme, které věci můžete v hlavním dokumentu měnit. Pro začátek "
+"je to pouze název. Je zde několik zástupných hodnot (text v hranatých "
+"závorkách), o které byste se měli postarat."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1760
+msgid "Master document header"
+msgstr "Hlavička hlavního dokumentu"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1761
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\n"
+"<bookinfo>\n"
+" <title>Referenční příručka k NÁZEV_MODULU</title>\n"
+" <releaseinfo>\n"
+" pro NÁZEV_MODULU [VERSION]\n"
+" Nejvnovější verzi tohoto dokumentu můžete najít on-line na\n"
+" <ulink role=\"online-location\" url=\"http://[SERVER]/NÁZEV_MODULU/index.html\">http://[SERVER]/NÁZEV_MODULU/</ulink>.\n"
+" </releaseinfo>\n"
+"</bookinfo>\n"
+"\n"
+"<chapter>\n"
+" <title>[Insert title here]</title>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1777
+msgid ""
+"In addition a few option elements are created in commented form. You can "
+"review these and enable them as you like."
+msgstr ""
+"Navíc se vytvoří pár volitelných prvků ve formě komentáře. Můžete si je "
+"projít a případně povolit."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1783
+msgid "Optional part in the master document"
+msgstr "Volitelná část hlavního dokumentu"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1784
+#, 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 ""
+"\n"
+" <!-- enable this when you use gobject introspection annotations\n"
+" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n"
+" --> \n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1792
+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 ""
+"Nakonec musíte přidat nový oddíl, kdekoliv chcete. Nástroj <link linkend="
+"\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> vás upozorní na nově "
+"vygenerované soubory XML, které zatím nejsou v dokumentaci zahrnuté."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1800 C/index.docbook:1835
+msgid "Including generated sections"
+msgstr "Vkládání generovaných oddílů"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1801
+#, no-wrap
+msgid ""
+"\n"
+" <chapter>\n"
+" <title>my library</title>\n"
+" <xi:include href=\"xml/object.xml\"/>\n"
+" ...\n"
+msgstr ""
+"\n"
+" <chapter>\n"
+" <title>moje knihovna</title>\n"
+" <xi:include href=\"xml/object.xml\"/>\n"
+" …\n"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1813
+msgid "Editing the section file"
+msgstr "Úprava souboru oddílů"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1815
+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 "
+"the visibility (public or private)."
+msgstr ""
+"Soubor oddílů se používá k organizování výstupu dokumentace z GTK-Doc. Zde "
+"se určuje, který symbol náleží ke kterému modulu nebo třídě, a řídí se "
+"viditelnost (jestli je veřejný nebo soukromý)."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1821
+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."
+msgstr ""
+"Soubor oddílů je prostý textový soubor, ve kterém jsou oddíly oddělené "
+"značkami. Prázdné řádky se ignorují a s řádky začínajícími „#“ se zachází "
+"jako s komentářovými řádky."
+
+#. (itstool) path: note/para
+#: C/index.docbook:1828
+msgid ""
+"While the tags make the file look like xml, it is not. Please do not close "
+"tags like <SUBSECTION>."
+msgstr ""
+"Přestože díky značkám vypadá soubor podobně jako XML, není tomu tak. "
+"Neuzavírejte prosím značky jako je <SUBSECTION>."
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1836
+#, 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:1853
+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 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 ""
+"Značka <FILE> … </FILE> se používá k určení názvu souboru bez "
+"přípony. Například použití „<FILE>gnome-config</FILE>“ bude mít "
+"v deklaracích oddílu za následek výstup do souboru šablony <filename>tmpl/"
+"gnome-config.sgml</filename>, který bude převeden do souboru <filename>sgml/"
+"gnome-config.sgml</filename> ve formátu DocBook SGML nebo do souboru "
+"<filename>xml/gnome-config.xml</filename> ve formátu DocBook XML. (Název "
+"souboru HTML vychází z názvu modulu a názvu oddílu, případně pro GObject z "
+"názvu třídy GObject převedeného na malá písmena.)"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1865
+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 "
+"created, since the title set in the template file overrides this. Also if "
+"one uses SECTION comment in the sources, this is obsolete."
+msgstr ""
+"Značka <TITLE> … </TITLE> se používá k určení názvu oddílu. To "
+"je použitelné pouze dříve, než je poprvé vytvořena šablona (pokud se "
+"používá), protože název nastavený v šabloně tento název přepíše. Navíc je "
+"považována za zastaralou v případě, že se používá komentář SECTION ve "
+"zdrojovém kódu."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1872
+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)."
+msgstr ""
+"Můžete také seskupovat položky v oddílu pomocí značky <SUBSECTION>. V "
+"současnosti způsobí prázdný řádek mezi pododdíly v souhrnné části. Můžete "
+"také použít <SUBSECTION Standard> pro standardní deklarace GObject "
+"(například funkce jako je g_object_get_type, makra jako G_OBJECT(), "
+"G_IS_OBJECT() atd.). V současnosti jsou tyto v dokumentaci vynechané. Můžete "
+"také použít <SUBSECTION Private> pro privátní deklarace, které ve "
+"výsledku nebudou (jedná se o ruční způsob, jak zabránit varovným hlášením o "
+"nepoužitých deklaracích). Pokud vaše knihovna obsahuje privátní typy, u "
+"kterých nechcete, aby se objevily v hierarchii objektů a v seznamu "
+"implementovaných nebo vyžadovaných rozhraní, přidejte je do pododdílu "
+"Private. Jestli umístit struktury jako GObject a GObjectClass do veřejné "
+"nebo standardní části záleží na tom, jestli mají veřejné položky (proměnné, "
+"virtuální metody)."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1891
+msgid ""
+"You can also use <INCLUDE> ... </INCLUDE> to specify the "
+"#include files which are shown in the synopsis sections. It contains a comma-"
+"separate list of #include files, without the angle brackets. If you set it "
+"outside of any sections, it acts for all sections until the end of the file. "
+"If you set it within a section, it only applies to that section."
+msgstr ""
+"Můžete také použít <INCLUDE> ... </INCLUDE> k určení #include "
+"souborů, které jsou zobrazené v souhrnné části. Obsahuje čárkami oddělený "
+"seznam jednotlivých #include souborů, bez lomených závorek. Když je "
+"nastavíte mimo kterýkoliv oddíl, budou fungovat pro všechny oddíly až do "
+"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:1905
+msgid "Controlling the result"
+msgstr "Ovlivnění výsledku"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1907
+msgid ""
+"A GTK-Doc run generates report files inside the documentation directory. The "
+"generated files are named: <filename><package>-undocumented.txt</"
+"filename>, <filename><package>-undeclared.txt</filename> and "
+"<filename><package>-unused.txt</filename>. All those are plain text "
+"files that can be viewed and postprocessed easily."
+msgstr ""
+"Spuštění GTK-Doc vygeneruje ve složkách pro dokumentaci soubory s výstupními "
+"sestavami. Generované soubory jsou nazvané: <filename><balíček>-"
+"undocumented.txt</filename>, <filename><balíček>-undeclared.txt</"
+"filename> a <filename><balíček>-unused.txt</filename>. Všechno to jsou "
+"prosté textové soubory, které si lze jednoduše prohlížet a zpracovávat je."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1916
+msgid ""
+"The <filename><package>-undocumented.txt</filename> file starts with "
+"the documentation coverage summary. Below are two sections divided by blank "
+"lines. The first section lists undocumented or incomplete symbols. The "
+"second section does the same for section docs. Incomplete entries are those, "
+"which have documentation, but where e.g. a new parameter has been added."
+msgstr ""
+"Soubor <filename><balíček>-undocumented.txt</filename> začíná "
+"souhrnnými údaji o dokumentaci. Následují dva oddíly oddělené prázdnými "
+"řádky. První oddíl je seznam nezdokumentovaných nebo neúplných symbolů. "
+"Druhý oddíl je to stejné, ale pro dokumentace oddílů. Neúplné položky jsou "
+"takové, které mají dokumentaci, ale u kterých byl například přidán nový "
+"parametr."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1925
+msgid ""
+"The <filename><package>-undeclared.txt</filename> file lists symbols "
+"given in the <filename><package>-sections.txt</filename> but not found "
+"in the sources. Check if they have been removed or if they are misspelled."
+msgstr ""
+"Soubor <filename><balíček>-undeclared.txt</filename> uvádí symboly, "
+"které jsou zadané v <filename><balíček>-section.txt</filename>, ale "
+"nebyly nalezené ve zdrojových kódech. Ověřte, jestli nebyly odstraněny, nebo "
+"v nich není překlep."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1932
+msgid ""
+"The <filename><package>-unused.txt</filename> file lists symbol names, "
+"where the GTK-Doc scanner has found documentation, but does not know where "
+"to put it. This means that the symbol has not yet been added to the "
+"<filename><package>-sections.txt</filename> file."
+msgstr ""
+"Soubor <filename><balíček>-unused.txt</filename> uvádí názvy symbolů, "
+"které GTK-Doc při procházení dokumentace nalezl, ale neví, kam je zařadit. "
+"To znamená, že tyto symboly nejsou zatím zařazené v souboru <filename><"
+"balíček>-section.txt</filename>."
+
+#. (itstool) path: tip/para
+#: C/index.docbook:1940
+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 "
+"<command>make check</command> run."
+msgstr ""
+"Povolte nebo přidejte řádek <option>TESTS=($GTKDOC_CHECK)</option> v "
+"Makefile.am. Pokud máte nainstalované GTK-Doc ve verzi minimálně 1.9, bude "
+"se díky tomu při spuštění <command>make check</command> provádět kontrola "
+"správnosti údajů."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1947
+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."
+msgstr ""
+"Můžete se také podívat do souborů vytvořených skenerem zdrojového kódu: "
+"<filename><package>-decl-list.txt</filename> a <filename><"
+"package>-decl.txt</filename>. První můžete porovnat se souborem s oddíly, "
+"pokud je ručně spravován. Ve druhém jsou uvedené všechny deklarace z "
+"hlavičkových souborů. Pokud v dokumentaci schází některý symbol, můžete "
+"zkontrolovat, jestli se vyskytuje v tomto souboru."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1956
+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 GTK-Doc "
+"to keep the intermediate scanner file for further analysis, by running it as "
+"<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>."
+msgstr ""
+"Pokud je základem projektu GObject, můžete se také podívat do souborů "
+"vytvořených skenerem objektů: <filename><package>.args.txt</filename>, "
+"<filename><package>.hierarchy.txt</filename>, <filename><"
+"package>.interfaces.txt</filename>, <filename><package>."
+"prerequisites.txt</filename> a <filename><package>.signals.txt</"
+"filename>. Jestliže v kterémkoliv z nich jsou chybějící symboly, můžete "
+"spuštěním <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command> požádat GTK-"
+"Doc, aby přechodně zachovat soubor pro pozdější analýzu."
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:1971
+msgid "Modernizing the documentation"
+msgstr "Modernizace dokumentu"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1973
+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 ""
+"GTK-Doc existuje již nějakou dobu. V této části je uveden seznam nových "
+"funkcí spolu s číslem verze, od které je tato funkčnost k dispozici."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1979
+msgid "GTK-Doc 1.9"
+msgstr "GTK-Doc 1.9"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1981
+msgid ""
+"When using xml instead of sgml, one can actually name the master document "
+"<filename><package>-docs.xml</filename>."
+msgstr ""
+"Když používáte XML namísto SGML, můžete ve skutečnosti pojmenovat hlavní "
+"dokument <filename><package>-docs.xml</filename>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1986
+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 ""
+"Tato verze podporuje <option>SCAN_OPTIONS=--rebuild-sections</option> v "
+"<filename>Makefile.am</filename>. Když je tato volba zapnutá, je "
+"<filename><package>-sections.txt</filename> generován automaticky a "
+"můžete jej odstranit ze správy verzí. To funguje hezky je u projektů, které "
+"mají pravidelnou strukturu (například jednotlivé páry souboru .c a .h "
+"vytvoří nový oddíl). Pokud máte projekt takto pečlivě organizovaný, vystačí "
+"si aktualizace ručně spravovaného souboru s oddíly s prostým spuštěním "
+"<code>meld <package>-decl-list.txt <package>-sections.txt</code>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1997
+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 you source "
+"control system and haven't yet switched, just add the flag to "
+"<filename>configure.ac</filename> and you are done."
+msgstr ""
+"Již verze 1.18 zavedla syntax pro dokumentování oddílů ve zdrojovém kódu "
+"namísto zvláštních souborů ve složce <filename class=\"directory\">tmpl</"
+"filename>. Tato verze přidává pomocí <option>--flavour no-tmpl</option> in "
+"<filename>configure.ac</filename> volbu pro přepnutí celého modulu "
+"dokumentace, aby nepoužíval speciální složku tmp během sestavení. Jestliže "
+"nepotřebujete udržovat <filename class=\"directory\">tmpl</filename> v "
+"systému pro správu verzí ještě jste zatím přepnutí neprovedli, stačí přidat "
+"tuto volbu do <filename>configure.ac</filename> a je to."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2009
+msgid "GTK-Doc 1.10"
+msgstr "GTK-Doc 1.10"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:2011
+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 ""
+"Tato verze podporuje <option>SCAN_OPTIONS=--rebuild-types</option> v "
+"<filename>Makefile.am</filename>. Když je tato volba zapnutá, je "
+"<filename><package>.types</filename> generován automaticky a můžete "
+"jej odstranit ze správy verzí. Jestliže tuto funkci využíváte, je důležité "
+"nastavit také <varname>IGNORE_HFILES</varname> v <filename>Makefile.am</"
+"filename> pro kód, který je sestavován podmíněně."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2022
+msgid "GTK-Doc 1.16"
+msgstr "GTK-Doc 1.16"
+
+#. (itstool) path: example/title
+#: C/index.docbook:2028
+msgid "Enable gtkdoc-check"
+msgstr "Povolení gtkdoc-check"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2029
+#, 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:2024
+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 ""
+"Součástí této verze je nový nástroj s názvem gtkdoc-check. Jeho spuštěním se "
+"provede kontrola správnosti vašeho dokumentu. Povolit jej můžete přidáním "
+"těchto řádků na konec souboru <filename>Makefile.am</filename>. <_:example-1/"
+">"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2042
+msgid "GTK-Doc 1.20"
+msgstr "GTK-Doc 1.20"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:2044
+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 ""
+"Verze 1.18 přinesla počáteční podporu pro Markdown. Jeho použití v "
+"dokumentačních komentářích je méně rušivé, než zápis XML z DocBook. Tato "
+"verze jeho podporu značně vylepšuje a přidává mnohem více stylů. Více "
+"podrobností je uvedeno v oddílu, který vysvětluje <link linkend="
+"\"documenting_syntax\">syntax komentářů</link>."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2054
+msgid "GTK-Doc 1.25"
+msgstr "GTK-Doc 1.25"
+
+#. (itstool) path: example/title
+#: C/index.docbook:2064
+msgid "Use pre-generated entities"
+msgstr "Používání předgenerovaných entit"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2065
+#, 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>&Referenční příručka k package_name;</title>\n"
+" <releaseinfo>\n"
+" for &package_string;.\n"
+" Nejnovější verzi této dokumentace můžete najít on-line na\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:2056
+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 any 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 ""
+"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-1/>"
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:2090
+msgid "Documenting other interfaces"
+msgstr "Dokumentování ostatních rozhraní"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:2092
+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 "
+"interfaces too."
+msgstr ""
+"Doposud jsme pomocí GTK-Doc dokumentovali API kódu. Následující oddíl "
+"obsahuje doporučení, jak se dají nástroje použít také k dokumentování "
+"dalších rozhraní."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2099
+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:2101
+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 "
+"the reference and one gets the man-page for free."
+msgstr ""
+"Protože je stejně možné generovat manuálové stránky pro referenční položky "
+"DocBook, zní jako dobrý nápad použít to pro tento účel. Tímto způsobem se "
+"rozhraní stane součástí referenční příručky a získáte tak bez námahy "
+"manuálovou stránku."
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:2108
+msgid "Document the tool"
+msgstr "Dokumentování nástrojů"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:2110
+msgid ""
+"Create one refentry file per tool. Following <link linkend="
+"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
+"docs/reference/meeper/meep.xml</filename>. For the xml tags that should be "
+"used and can look at generated file in the xml subdirectory as well as "
+"examples e.g. in glib."
+msgstr ""
+"Vytvořte jeden soubor s referenční příručkou pro každý z nástrojů. V <link "
+"linkend=\"settingup_docfiles\">našem příkladu</link> by se měl nazývat "
+"<filename>meep/docs/reference/meeper/meep.xml</filename>. Na značky XML, "
+"který by se měly použít, se podívejte do nějakého ukázkového vygenerovaného "
+"souboru v podsložce XML, například v glib."
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:2120
+msgid "Adding the extra configure check"
+msgstr "Přidání doplňkových kontrol do configure"
+
+#. (itstool) path: example/title
+#: C/index.docbook:2123 C/index.docbook:2141
+msgid "Extra configure checks"
+msgstr "Dodatečné kontroly nastavení"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2124
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\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"
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:2138
+msgid "Adding the extra makefile rules"
+msgstr "Přidání doplňkových pravidel do Makefile"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2142
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\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"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2164
+msgid "DBus interfaces"
+msgstr "Rozhraní D-Bus"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:2166
+msgid ""
+"(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://"
+"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
+msgstr ""
+"(OPRAVIT: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://"
+"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:2175
+msgid "Frequently asked questions"
+msgstr "Často kladené dotazy"
+
+#. (itstool) path: segmentedlist/segtitle
+#: C/index.docbook:2179
+msgid "Question"
+msgstr "Dotaz"
+
+#. (itstool) path: segmentedlist/segtitle
+#: C/index.docbook:2180
+msgid "Answer"
+msgstr "Odpověď"
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2182
+msgid "No class hierarchy."
+msgstr "Schází hierarchie třídy."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2183
+msgid ""
+"The objects <function>xxx_get_type()</function> function has not been "
+"entered into the <filename><package>.types</filename> file."
+msgstr ""
+"Do souboru <filename><balíček>.types</filename> nebyla vložena funkce "
+"objektu <function>xxx_get_type()</function>."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2189
+msgid "Still no class hierarchy."
+msgstr "Stále schází hierarchie třídy."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2190
+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\">explanation</ulink>)."
+msgstr ""
+"Chybějící nebo nesprávné pojmenování souboru <filename><balíček>-"
+"sections.txt</filename> (viz <ulink url=\"http://mail.gnome.org/archives/gtk-"
+"doc-list/2003-October/msg00006.html\">vysvětlení</ulink>)."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2196
+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:2197
+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 "
+"subsections)."
+msgstr ""
+"Je název objektu (název struktury instance, například <type>GtkWidget</"
+"type>) součástí normálního oddílu? (Nedávejte je do pododdílu Standard nebo "
+"Private)."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2204
+msgid "No symbol index."
+msgstr "Chybí rejstřík symbolů."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2205
+msgid ""
+"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
+"index that xi:includes the generated index?"
+msgstr ""
+"Obsahuje <filename><package>-docs.{xml,sgml}</filename> rejstřík, "
+"který vloží pomocí xi:include vygenerovaný rejstřík?"
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2211
+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:2212
+msgid ""
+"Is the doc-comment using the correct markup (added #,% or ())? Check if the "
+"gtkdoc-fixxref warns about unresolvable xrefs."
+msgstr ""
+"Používá dokumentační komentář správnou značku (přidané znaky #,% nebo ())? "
+"Podívejte se na varování gtkdoc-fixxref o nevyřešených křížových odkazech."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2218
+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:2219
+msgid ""
+"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
+"filename>."
+msgstr ""
+"Je nový balíček vložený pomocí xi:include z <filename><package>-docs."
+"{xml,sgml}</filename>."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2225
+msgid "A new symbol does not appear in the docs."
+msgstr "Nový symbol se neobjevil v dokumentaci."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2226
+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 "
+"xrefs. Check if the symbol is correctly listed in the <filename><"
+"package>-sections.txt</filename> in a public subsection."
+msgstr ""
+"Je dokumentační komentář správně naformátovaný? Zkontrolujte překlepy na "
+"začátku komentáře. Podívejte se po varováních gtkdoc-fixxref o nevyřešených "
+"křížových odkazech. Zkontrolujte, jestli je symbol správně uvedený v "
+"<filename><package>-sections.txt</filename> ve veřejném pododdíle."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2234
+msgid "A type is missing from the class hierarchy."
+msgstr "V hierarchii třídy schází typ."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2235
+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 incidentally marked private it will not be shown."
+msgstr ""
+"Jestliže je typ uvedený v <filename><package>.hierarchy</filename>, "
+"ale není v <filename>xml/tree_index.sgml</filename>, tak raději dvakrát "
+"zkontrolujte, jestli je typ správně uvedený v <filename><package>-"
+"sections.txt</filename>. Jestliže instance typu (například <type>GtkWidget</"
+"type>) není uvedená, nebo je nedopatřením označení jako privátní, nebude "
+"zobrazena."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2244
+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:2245
+msgid ""
+"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
+"from <filename><package>-docs.{xml,sgml}</filename>."
+msgstr ""
+"Zkontrolujte, že <filename>xml/annotation-glossary.xml</filename> je vložené "
+"pomocí xi:include z <filename><package>-docs.{xml,sgml}</filename>."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2253
+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:2254
+msgid ""
+"Check if the prototype in the header has different parameter names as in the "
+"source."
+msgstr ""
+"Zkontrolujte, za nemá prototyp v hlavičkovém souboru jiné názvy parametrů, "
+"než ve zdrojovém kódu."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2259
+msgid "multiple \"IDs\" for constraint linkend: XYZ"
+msgstr "Více „ID“ pro tentýž cíl odkazu: XYZ"
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2260
+msgid ""
+"Symbol XYZ appears twice in <filename><package>-sections.txt</"
+"filename> file."
+msgstr ""
+"Symbol XYZ se v souboru <filename><package>-sections.txt</filename> "
+"objevuje dvakrát."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2263
+msgid ""
+"Element typename in namespace '' encountered in para, but no template "
+"matches."
+msgstr ""
+"Element typename ve jmenném prostoru '' je uvedený v rodiči, ale neodpovídá "
+"mu žádná šablona."
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:2270
+msgid "Tools related to gtk-doc"
+msgstr "Nástroje související s GTK-Doc"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:2272
+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 "
+"integrates with the trac search."
+msgstr ""
+"GtkDocPlugin – zásuvný modul pro integraci <ulink url=\"http://trac-hacks."
+"org/wiki/GtkDocPlugin\">GTK-Doc do systému Track</ulink>, který přidává "
+"dokumentaci k API na sledovací web a integruje ji do vyhledávání."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:2277
+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."
+msgstr ""
+"Gtkdoc-depscan – nástroj (součást GTK-Doc), který kontroluje použité API "
+"vůči štítku since v API, aby určil minimální požadovanou verzi."
+
+#. (itstool) path: appendixinfo/releaseinfo
+#: C/index.docbook:12 C/fdl-appendix.xml:12
+msgid "Version 1.1, March 2000"
+msgstr "Verze 1.1, březen 2000"
+
+#. (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>"
+
+#. (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>"
+msgstr ""
+"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>"
+
+#. (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."
+msgstr ""
+"<_:address-1/> Kdokoliv je oprávněn kopírovat a šířit doslovné kopie tohoto "
+"dokumentu s licencí, ale nesmí v něm provádět žádné změny."
+
+#. (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 "GNU Free Documentation License"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:31 C/fdl-appendix.xml:31
+msgid "0. PREAMBLE"
+msgstr ""
+
+#. (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 "
+"effective freedom to copy and redistribute it, with or without modifying it, "
+"either commercially or noncommercially. Secondarily, this License preserves "
+"for the author and publisher a way to get credit for their work, while not "
+"being considered responsible for modifications made by others."
+msgstr ""
+
+#. (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. "
+"It complements the GNU General Public License, which is a copyleft license "
+"designed for free software."
+msgstr ""
+
+#. (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 "
+"should come with manuals providing the same freedoms that the software does. "
+"But this License is not limited to software manuals; it can be used for any "
+"textual work, regardless of subject matter or whether it is published as a "
+"printed book. We recommend this License principally for works whose purpose "
+"is instruction or reference."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:62 C/fdl-appendix.xml:62
+msgid "1. APPLICABILITY AND DEFINITIONS"
+msgstr ""
+
+#. (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 "
+"of this License. The <quote>Document</quote>, below, refers to any such "
+"manual or work. Any member of the public is a licensee, and is addressed as "
+"<quote>you</quote>."
+msgstr ""
+
+#. (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 "
+"modifications and/or translated into another language."
+msgstr ""
+
+#. (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 "
+"exclusively with the relationship of the publishers or authors of the "
+"Document to the Document's overall subject (or to related matters) and "
+"contains nothing that could fall directly within that overall subject. (For "
+"example, if the Document is in part a textbook of mathematics, a Secondary "
+"Section may not explain any mathematics.) The relationship could be a matter "
+"of historical connection with the subject or with related matters, or of "
+"legal, commercial, philosophical, ethical or political position regarding "
+"them."
+msgstr ""
+
+#. (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 "
+"those of Invariant Sections, in the notice that says that the <link linkend="
+"\"fdl-document\">Document</link> is released under this License."
+msgstr ""
+
+#. (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 "
+"that the <link linkend=\"fdl-document\">Document</link> is released under "
+"this License."
+msgstr ""
+
+#. (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 "
+"specification is available to the general public, whose contents can be "
+"viewed and edited directly and straightforwardly with generic text editors "
+"or (for images composed of pixels) generic paint programs or (for drawings) "
+"some widely available drawing editor, and that is suitable for input to text "
+"formatters or for automatic translation to a variety of formats suitable for "
+"input to text formatters. A copy made in an otherwise Transparent file "
+"format whose markup has been designed to thwart or discourage subsequent "
+"modification by readers is not Transparent. A copy that is not "
+"<quote>Transparent</quote> is called <quote>Opaque</quote>."
+msgstr ""
+
+#. (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 "
+"a publicly available DTD, and standard-conforming simple HTML designed for "
+"human modification. Opaque formats include PostScript, PDF, proprietary "
+"formats that can be read and edited only by proprietary word processors, "
+"SGML or XML for which the DTD and/or processing tools are not generally "
+"available, and the machine-generated HTML produced by some word processors "
+"for output purposes only."
+msgstr ""
+
+#. (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 "
+"material this License requires to appear in the title page. For works in "
+"formats which do not have any title page as such, <quote>Title Page</quote> "
+"means the text near the most prominent appearance of the work's title, "
+"preceding the beginning of the body of the text."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:153 C/fdl-appendix.xml:153
+msgid "2. VERBATIM COPYING"
+msgstr ""
+
+#. (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 "
+"this License, the copyright notices, and the license notice saying this "
+"License applies to the Document are reproduced in all copies, and that you "
+"add no other conditions whatsoever to those of this License. You may not use "
+"technical measures to obstruct or control the reading or further copying of "
+"the copies you make or distribute. However, you may accept compensation in "
+"exchange for copies. If you distribute a large enough number of copies you "
+"must also follow the conditions in <link linkend=\"fdl-section3\">section 3</"
+"link>."
+msgstr ""
+
+#. (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."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:176 C/fdl-appendix.xml:176
+msgid "3. COPYING IN QUANTITY"
+msgstr ""
+
+#. (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 "
+"notice requires <link linkend=\"fdl-cover-texts\">Cover Texts</link>, you "
+"must enclose the copies in covers that carry, clearly and legibly, all these "
+"Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on "
+"the back cover. Both covers must also clearly and legibly identify you as "
+"the publisher of these copies. The front cover must present the full title "
+"with all words of the title equally prominent and visible. You may add other "
+"material on the covers in addition. Copying with changes limited to the "
+"covers, as long as they preserve the title of the <link linkend=\"fdl-"
+"document\">Document</link> and satisfy these conditions, can be treated as "
+"verbatim copying in other respects."
+msgstr ""
+
+#. (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 "
+"actual cover, and continue the rest onto adjacent pages."
+msgstr ""
+
+#. (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 "
+"than 100, you must either include a machine-readable <link linkend=\"fdl-"
+"transparent\">Transparent</link> copy along with each Opaque copy, or state "
+"in or with each Opaque copy a publicly-accessible computer-network location "
+"containing a complete Transparent copy of the Document, free of added "
+"material, which the general network-using public has access to download "
+"anonymously at no charge using public-standard network protocols. If you use "
+"the latter option, you must take reasonably prudent steps, when you begin "
+"distribution of Opaque copies in quantity, to ensure that this Transparent "
+"copy will remain thus accessible at the stated location until at least one "
+"year after the last time you distribute an Opaque copy (directly or through "
+"your agents or retailers) of that edition to the public."
+msgstr ""
+
+#. (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 "
+"large number of copies, to give them a chance to provide you with an updated "
+"version of the Document."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:231 C/fdl-appendix.xml:231
+msgid "4. MODIFICATIONS"
+msgstr ""
+
+#. (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 "
+"the conditions of sections <link linkend=\"fdl-section2\">2</link> and <link "
+"linkend=\"fdl-section3\">3</link> above, provided that you release the "
+"Modified Version under precisely this License, with the Modified Version "
+"filling the role of the Document, thus licensing distribution and "
+"modification of the Modified Version to whoever possesses a copy of it. In "
+"addition, you must do these things in the Modified Version:"
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:248 C/fdl-appendix.xml:248
+msgid "A"
+msgstr "A"
+
+#. (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-"
+"document\">Document</link>, and from those of previous versions (which "
+"should, if there were any, be listed in the History section of the "
+"Document). You may use the same title as a previous version if the original "
+"publisher of that version gives permission."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:264 C/fdl-appendix.xml:264
+msgid "B"
+msgstr "B"
+
+#. (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 "
+"modifications in the <link linkend=\"fdl-modified\">Modified Version</link>, "
+"together with at least five of the principal authors of the <link linkend="
+"\"fdl-document\">Document</link> (all of its principal authors, if it has "
+"less than five)."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:279 C/fdl-appendix.xml:279
+msgid "C"
+msgstr "C"
+
+#. (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>, "
+"as the publisher."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:291 C/fdl-appendix.xml:291
+msgid "D"
+msgstr "D"
+
+#. (itstool) path: formalpara/para
+#: C/index.docbook:292
+msgid ""
+"Preserve all the copyright notices of the <link linkend=\"fdl-document"
+"\">Document</link>."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:301 C/fdl-appendix.xml:301
+msgid "E"
+msgstr "E"
+
+#. (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."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:311 C/fdl-appendix.xml:311
+msgid "F"
+msgstr "F"
+
+#. (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</link> under the terms of this License, in the form shown in the "
+"Addendum below."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:324 C/fdl-appendix.xml:324
+msgid "G"
+msgstr "G"
+
+#. (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-"
+"cover-texts\">Cover Texts</link> given in the <link linkend=\"fdl-document"
+"\">Document's</link> license notice."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:337 C/fdl-appendix.xml:337
+msgid "H"
+msgstr "H"
+
+#. (itstool) path: formalpara/para
+#: C/index.docbook:338 C/fdl-appendix.xml:338
+msgid "Include an unaltered copy of this License."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:346 C/fdl-appendix.xml:346
+msgid "I"
+msgstr "I"
+
+#. (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 "
+"of the <link linkend=\"fdl-modified\">Modified Version</link> as given on "
+"the <link linkend=\"fdl-title-page\">Title Page</link>. If there is no "
+"section entitled <quote>History</quote> in the <link linkend=\"fdl-document"
+"\">Document</link>, create one stating the title, year, authors, and "
+"publisher of the Document as given on its Title Page, then add an item "
+"describing the Modified Version as stated in the previous sentence."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:365 C/fdl-appendix.xml:365
+msgid "J"
+msgstr "J"
+
+#. (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-"
+"transparent\">Transparent</link> copy of the Document, and likewise the "
+"network locations given in the Document for previous versions it was based "
+"on. These may be placed in the <quote>History</quote> section. You may omit "
+"a network location for a work that was published at least four years before "
+"the Document itself, or if the original publisher of the version it refers "
+"to gives permission."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:383 C/fdl-appendix.xml:383
+msgid "K"
+msgstr "K"
+
+#. (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 "
+"the section all the substance and tone of each of the contributor "
+"acknowledgements and/or dedications given therein."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:396 C/fdl-appendix.xml:396
+msgid "L"
+msgstr "L"
+
+#. (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 "
+"text and in their titles. Section numbers or the equivalent are not "
+"considered part of the section titles."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:409 C/fdl-appendix.xml:409
+msgid "M"
+msgstr "M"
+
+#. (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</"
+"link>."
+msgstr ""
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:421 C/fdl-appendix.xml:421
+msgid "N"
+msgstr "N"
+
+#. (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 "
+"Section</link>."
+msgstr ""
+
+#. (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-"
+"secondary\">Secondary Sections</link> and contain no material copied from "
+"the Document, you may at your option designate some or all of these sections "
+"as invariant. To do this, add their titles to the list of <link linkend="
+"\"fdl-invariant\">Invariant Sections</link> in the Modified Version's "
+"license notice. These titles must be distinct from any other section titles."
+msgstr ""
+
+#. (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"
+"\">Modified Version</link> by various parties--for example, statements of "
+"peer review or that the text has been approved by an organization as the "
+"authoritative definition of a standard."
+msgstr ""
+
+#. (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 "
+"linkend=\"fdl-cover-texts\">Back-Cover Text</link>, to the end of the list "
+"of <link linkend=\"fdl-cover-texts\">Cover Texts</link> in the <link linkend="
+"\"fdl-modified\">Modified Version</link>. Only one passage of Front-Cover "
+"Text and one of Back-Cover Text may be added by (or through arrangements "
+"made by) any one entity. If the <link linkend=\"fdl-document\">Document</"
+"link> already includes a cover text for the same cover, previously added by "
+"you or by arrangement made by the same entity you are acting on behalf of, "
+"you may not add another; but you may replace the old one, on explicit "
+"permission from the previous publisher that added the old one."
+msgstr ""
+
+#. (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 "
+"for publicity for or to assert or imply endorsement of any <link linkend="
+"\"fdl-modified\">Modified Version </link>."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:480 C/fdl-appendix.xml:480
+msgid "5. COMBINING DOCUMENTS"
+msgstr ""
+
+#. (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 "
+"<link linkend=\"fdl-section4\">section 4</link> above for modified versions, "
+"provided that you include in the combination all of the <link linkend=\"fdl-"
+"invariant\">Invariant Sections</link> of all of the original documents, "
+"unmodified, and list them all as Invariant Sections of your combined work in "
+"its license notice."
+msgstr ""
+
+#. (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 "
+"replaced with a single copy. If there are multiple Invariant Sections with "
+"the same name but different contents, make the title of each such section "
+"unique by adding at the end of it, in parentheses, the name of the original "
+"author or publisher of that section if known, or else a unique number. Make "
+"the same adjustment to the section titles in the list of Invariant Sections "
+"in the license notice of the combined work."
+msgstr ""
+
+#. (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>History</quote>; likewise combine any sections entitled "
+"<quote>Acknowledgements</quote>, and any sections entitled "
+"<quote>Dedications</quote>. You must delete all sections entitled "
+"<quote>Endorsements.</quote>"
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:516 C/fdl-appendix.xml:516
+msgid "6. COLLECTIONS OF DOCUMENTS"
+msgstr ""
+
+#. (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 "
+"replace the individual copies of this License in the various documents with "
+"a single copy that is included in the collection, provided that you follow "
+"the rules of this License for verbatim copying of each of the documents in "
+"all other respects."
+msgstr ""
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:527 C/fdl-appendix.xml:527
+msgid ""
+"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."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:537 C/fdl-appendix.xml:537
+msgid "7. AGGREGATION WITH INDEPENDENT WORKS"
+msgstr ""
+
+#. (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 "
+"a volume of a storage or distribution medium, does not as a whole count as a "
+"<link linkend=\"fdl-modified\">Modified Version</link> of the Document, "
+"provided no compilation copyright is claimed for the compilation. Such a "
+"compilation is called an <quote>aggregate</quote>, and this License does not "
+"apply to the other self-contained works thus compiled with the Document , on "
+"account of their being thus compiled, if they are not themselves derivative "
+"works of the Document. If the <link linkend=\"fdl-cover-texts\">Cover Text</"
+"link> requirement of <link linkend=\"fdl-section3\">section 3</link> is "
+"applicable to these copies of the Document, then if the Document is less "
+"than one quarter of the entire aggregate, the Document's Cover Texts may be "
+"placed on covers that surround only the Document within the aggregate. "
+"Otherwise they must appear on covers around the whole aggregate."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:561 C/fdl-appendix.xml:561
+msgid "8. TRANSLATION"
+msgstr ""
+
+#. (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 "
+"terms of <link linkend=\"fdl-section4\">section 4</link>. Replacing <link "
+"linkend=\"fdl-invariant\"> Invariant Sections</link> with translations "
+"requires special permission from their copyright holders, but you may "
+"include translations of some or all Invariant Sections in addition to the "
+"original versions of these Invariant Sections. You may include a translation "
+"of this License provided that you also include the original English version "
+"of this License. In case of a disagreement between the translation and the "
+"original English version of this License, the original English version will "
+"prevail."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:580 C/fdl-appendix.xml:580
+msgid "9. TERMINATION"
+msgstr ""
+
+#. (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 "
+"License. Any other attempt to copy, modify, sublicense or distribute the "
+"Document is void, and will automatically terminate your rights under this "
+"License. However, parties who have received copies, or rights, from you "
+"under this License will not have their licenses terminated so long as such "
+"parties remain in full compliance."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:594 C/fdl-appendix.xml:594
+msgid "10. FUTURE REVISIONS OF THIS LICENSE"
+msgstr ""
+
+#. (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 "
+"Free Documentation License from time to time. Such new versions will be "
+"similar in spirit to the present version, but may differ in detail to "
+"address new problems or concerns. See <ulink type=\"http\" url=\"http://www."
+"gnu.org/copyleft\">http://www.gnu.org/copyleft/</ulink>."
+msgstr ""
+
+#. (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 "
+"numbered version of this License <quote>or any later version</quote> applies "
+"to it, you have the option of following the terms and conditions either of "
+"that specified version or of any later version that has been published (not "
+"as a draft) by the Free Software Foundation. If the Document does not "
+"specify a version number of this License, you may choose any version ever "
+"published (not as a draft) by the Free Software Foundation."
+msgstr ""
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:621 C/fdl-appendix.xml:621
+msgid "Addendum"
+msgstr ""
+
+#. (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 "
+"just after the title page:"
+msgstr ""
+
+#. (itstool) path: blockquote/para
+#: C/index.docbook:629 C/fdl-appendix.xml:629
+msgid "Copyright YEAR YOUR NAME."
+msgstr ""
+
+#. (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 "
+"version published by the Free Software Foundation; with the <link linkend="
+"\"fdl-invariant\">Invariant Sections</link> being LIST THEIR TITLES, with "
+"the <link linkend=\"fdl-cover-texts\">Front-Cover Texts</link> being LIST, "
+"and with the <link linkend=\"fdl-cover-texts\">Back-Cover Texts</link> being "
+"LIST. A copy of the license is included in the section entitled <quote>GNU "
+"Free Documentation License</quote>."
+msgstr ""
+
+#. (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 "
+"are invariant. If you have no <link linkend=\"fdl-cover-texts\">Front-Cover "
+"Texts</link>, write <quote>no Front-Cover Texts</quote> instead of "
+"<quote>Front-Cover Texts being LIST</quote>; likewise for <link linkend="
+"\"fdl-cover-texts\">Back-Cover Texts</link>."
+msgstr ""
+
+#. (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 "
+"license, such as the <ulink type=\"http\" url=\"http://www.gnu.org/copyleft/"
+"gpl.html\"> GNU General Public License</ulink>, to permit their use in free "
+"software."
+msgstr ""
+
+#. (itstool) path: copyright/year
+#: C/fdl-appendix.xml:16
+msgid "2000"
+msgstr "2000"
+
+#. (itstool) path: copyright/holder
+#: C/fdl-appendix.xml:16
+msgid "Free Software Foundation, Inc."
+msgstr "Free Software Foundation, Inc."
+
+#. (itstool) path: address/street
+#: C/fdl-appendix.xml:20
+msgid "51 Franklin Street, Suite 330"
+msgstr "51 Franklin Street, Suite 330"
+
+#. (itstool) path: address/city
+#: C/fdl-appendix.xml:21
+msgid "Boston"
+msgstr "Boston"
+
+#. (itstool) path: address/state
+#: C/fdl-appendix.xml:21
+msgid "MA"
+msgstr "MA"
+
+#. (itstool) path: address/postcode
+#: C/fdl-appendix.xml:22
+msgid "02110-1301"
+msgstr "02110-1301"
+
+#. (itstool) path: address/country
+#: C/fdl-appendix.xml:22
+msgid "USA"
+msgstr "USA"
+
+#. (itstool) path: para/address
+#: C/fdl-appendix.xml:20
+msgid ""
+"Free Software Foundation, Inc. <_:street-1/>, <_:city-2/>, <_:state-3/> <_:"
+"postcode-4/> <_:country-5/>"
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:34
+msgid "free"
+msgstr ""
+
+#. (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 "
+"effective freedom to copy and redistribute it, with or without modifying it, "
+"either commercially or noncommercially. Secondarily, this License preserves "
+"for the author and publisher a way to get credit for their work, while not "
+"being considered responsible for modifications made by others."
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:44
+msgid "copyleft"
+msgstr ""
+
+#. (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 "
+"GNU General Public License, which is a copyleft license designed for free "
+"software."
+msgstr ""
+
+#. (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 ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:69
+msgid "you"
+msgstr ""
+
+#. (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 "
+"of this License. The <_:quote-1/>, below, refers to any such manual or work. "
+"Any member of the public is a licensee, and is addressed as <_:quote-2/>."
+msgstr ""
+
+#. (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 ""
+
+#. (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 "
+"translated into another language."
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:80
+msgid "Secondary Section"
+msgstr ""
+
+#. (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 "
+"authors of the Document to the Document's overall subject (or to related "
+"matters) and contains nothing that could fall directly within that overall "
+"subject. (For example, if the Document is in part a textbook of mathematics, "
+"a Secondary Section may not explain any mathematics.) The relationship could "
+"be a matter of historical connection with the subject or with related "
+"matters, or of legal, commercial, philosophical, ethical or political "
+"position regarding them."
+msgstr ""
+
+#. (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 ""
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:96 C/fdl-appendix.xml:435
+msgid "Secondary Sections"
+msgstr ""
+
+#. (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 <_:"
+"link-3/> is released under this License."
+msgstr ""
+
+#. (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 ""
+
+#. (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 <_:"
+"link-2/> is released under this License."
+msgstr ""
+
+#. (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 ""
+
+#. (itstool) path: para/quote
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:125 C/fdl-appendix.xml:204
+msgid "Opaque"
+msgstr ""
+
+#. (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 "
+"public, whose contents can be viewed and edited directly and "
+"straightforwardly with generic text editors or (for images composed of "
+"pixels) generic paint programs or (for drawings) some widely available "
+"drawing editor, and that is suitable for input to text formatters or for "
+"automatic translation to a variety of formats suitable for input to text "
+"formatters. A copy made in an otherwise Transparent file format whose markup "
+"has been designed to thwart or discourage subsequent modification by readers "
+"is not Transparent. A copy that is not <_:quote-3/> is called <_:quote-4/>."
+msgstr ""
+
+#. (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 ""
+
+#. (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 "
+"requires to appear in the title page. For works in formats which do not have "
+"any title page as such, <_:quote-2/> means the text near the most prominent "
+"appearance of the work's title, preceding the beginning of the body of the "
+"text."
+msgstr ""
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:166 C/fdl-appendix.xml:551
+msgid "section 3"
+msgstr ""
+
+#. (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 "
+"notices, and the license notice saying this License applies to the Document "
+"are reproduced in all copies, and that you add no other conditions "
+"whatsoever to those of this License. You may not use technical measures to "
+"obstruct or control the reading or further copying of the copies you make or "
+"distribute. However, you may accept compensation in exchange for copies. If "
+"you distribute a large enough number of copies you must also follow the "
+"conditions in <_:link-2/>."
+msgstr ""
+
+#. (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 "
+"copies in covers that carry, clearly and legibly, all these Cover Texts: "
+"Front-Cover Texts on the front cover, and Back-Cover Texts on the back "
+"cover. Both covers must also clearly and legibly identify you as the "
+"publisher of these copies. The front cover must present the full title with "
+"all words of the title equally prominent and visible. You may add other "
+"material on the covers in addition. Copying with changes limited to the "
+"covers, as long as they preserve the title of the <_:link-3/> and satisfy "
+"these conditions, can be treated as verbatim copying in other respects."
+msgstr ""
+
+#. (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 "
+"along with each Opaque copy, or state in or with each Opaque copy a publicly-"
+"accessible computer-network location containing a complete Transparent copy "
+"of the Document, free of added material, which the general network-using "
+"public has access to download anonymously at no charge using public-standard "
+"network protocols. If you use the latter option, you must take reasonably "
+"prudent steps, when you begin distribution of Opaque copies in quantity, to "
+"ensure that this Transparent copy will remain thus accessible at the stated "
+"location until at least one year after the last time you distribute an "
+"Opaque copy (directly or through your agents or retailers) of that edition "
+"to the public."
+msgstr ""
+
+#. (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 "
+"a chance to provide you with an updated version of the Document."
+msgstr ""
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:236
+msgid "2"
+msgstr "2"
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:237
+msgid "3"
+msgstr "3"
+
+#. (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 "
+"release the Modified Version under precisely this License, with the Modified "
+"Version filling the role of the Document, thus licensing distribution and "
+"modification of the Modified Version to whoever possesses a copy of it. In "
+"addition, you must do these things in the Modified Version:"
+msgstr ""
+
+#. (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, "
+"if there were any, be listed in the History section of the Document). You "
+"may use the same title as a previous version if the original publisher of "
+"that version gives permission."
+msgstr ""
+
+#. (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 "
+"with at least five of the principal authors of the <_:link-3/> (all of its "
+"principal authors, if it has less than five)."
+msgstr ""
+
+#. (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."
+msgstr ""
+
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:292
+msgid "Preserve all the copyright notices of the <_:link-1/>."
+msgstr ""
+
+#. (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 "
+"License, in the form shown in the Addendum below."
+msgstr ""
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:330
+msgid "Document's"
+msgstr ""
+
+#. (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."
+msgstr ""
+
+#. (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 ""
+
+#. (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 <_:"
+"link-2/> as given on the <_:link-3/>. If there is no section entitled <_:"
+"quote-4/> in the <_:link-5/>, create one stating the title, year, authors, "
+"and publisher of the Document as given on its Title Page, then add an item "
+"describing the Modified Version as stated in the previous sentence."
+msgstr ""
+
+#. (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 "
+"locations given in the Document for previous versions it was based on. These "
+"may be placed in the <_:quote-3/> section. You may omit a network location "
+"for a work that was published at least four years before the Document "
+"itself, or if the original publisher of the version it refers to gives "
+"permission."
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:385 C/fdl-appendix.xml:509
+msgid "Acknowledgements"
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:386 C/fdl-appendix.xml:510
+msgid "Dedications"
+msgstr ""
+
+#. (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 "
+"contributor acknowledgements and/or dedications given therein."
+msgstr ""
+
+#. (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 "
+"of the section titles."
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:412 C/fdl-appendix.xml:424 C/fdl-appendix.xml:445
+msgid "Endorsements"
+msgstr ""
+
+#. (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/>."
+msgstr ""
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:425
+msgid "Invariant Section"
+msgstr ""
+
+#. (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/>."
+msgstr ""
+
+#. (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 "
+"may at your option designate some or all of these sections as invariant. To "
+"do this, add their titles to the list of <_:link-3/> in the Modified "
+"Version's license notice. These titles must be distinct from any other "
+"section titles."
+msgstr ""
+
+#. (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, "
+"statements of peer review or that the text has been approved by an "
+"organization as the authoritative definition of a standard."
+msgstr ""
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:455
+msgid "Front-Cover Text"
+msgstr ""
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:457
+msgid "Back-Cover Text"
+msgstr ""
+
+#. (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 "
+"the <_:link-4/>. Only one passage of Front-Cover Text and one of Back-Cover "
+"Text may be added by (or through arrangements made by) any one entity. If "
+"the <_:link-5/> already includes a cover text for the same cover, previously "
+"added by you or by arrangement made by the same entity you are acting on "
+"behalf of, you may not add another; but you may replace the old one, on "
+"explicit permission from the previous publisher that added the old one."
+msgstr ""
+
+#. (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 "
+"endorsement of any <_:link-2/>."
+msgstr ""
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:484 C/fdl-appendix.xml:566
+msgid "section 4"
+msgstr ""
+
+#. (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, "
+"provided that you include in the combination all of the <_:link-3/> of all "
+"of the original documents, unmodified, and list them all as Invariant "
+"Sections of your combined work in its license notice."
+msgstr ""
+
+#. (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 "
+"multiple Invariant Sections with the same name but different contents, make "
+"the title of each such section unique by adding at the end of it, in "
+"parentheses, the name of the original author or publisher of that section if "
+"known, or else a unique number. Make the same adjustment to the section "
+"titles in the list of Invariant Sections in the license notice of the "
+"combined work."
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:511
+msgid "Endorsements."
+msgstr ""
+
+#. (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/>; "
+"likewise combine any sections entitled <_:quote-3/>, and any sections "
+"entitled <_:quote-4/>. You must delete all sections entitled <_:quote-5/>"
+msgstr ""
+
+#. (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 "
+"License in the various documents with a single copy that is included in the "
+"collection, provided that you follow the rules of this License for verbatim "
+"copying of each of the documents in all other respects."
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:546
+msgid "aggregate"
+msgstr ""
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:550
+msgid "Cover Text"
+msgstr ""
+
+#. (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 "
+"distribution medium, does not as a whole count as a <_:link-2/> of the "
+"Document, provided no compilation copyright is claimed for the compilation. "
+"Such a compilation is called an <_:quote-3/>, and this License does not "
+"apply to the other self-contained works thus compiled with the Document , on "
+"account of their being thus compiled, if they are not themselves derivative "
+"works of the Document. If the <_:link-4/> requirement of <_:link-5/> is "
+"applicable to these copies of the Document, then if the Document is less "
+"than one quarter of the entire aggregate, the Document's Cover Texts may be "
+"placed on covers that surround only the Document within the aggregate. "
+"Otherwise they must appear on covers around the whole aggregate."
+msgstr ""
+
+#. (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 <_:"
+"link-3/> with translations requires special permission from their copyright "
+"holders, but you may include translations of some or all Invariant Sections "
+"in addition to the original versions of these Invariant Sections. You may "
+"include a translation of this License provided that you also include the "
+"original English version of this License. In case of a disagreement between "
+"the translation and the original English version of this License, the "
+"original English version will prevail."
+msgstr ""
+
+#. (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, "
+"modify, sublicense or distribute the Document is void, and will "
+"automatically terminate your rights under this License. However, parties who "
+"have received copies, or rights, from you under this License will not have "
+"their licenses terminated so long as such parties remain in full compliance."
+msgstr ""
+
+#. (itstool) path: para/ulink
+#: C/fdl-appendix.xml:597
+msgid "Free Software Foundation"
+msgstr "Free Software Foundation"
+
+#. (itstool) path: para/ulink
+#: C/fdl-appendix.xml:603
+msgid "http://www.gnu.org/copyleft/"
+msgstr "http://www.gnu.org/copyleft/"
+
+#. (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 "
+"in spirit to the present version, but may differ in detail to address new "
+"problems or concerns. See <_:ulink-2/>."
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:610
+msgid "or any later version"
+msgstr ""
+
+#. (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 <_:"
+"quote-2/> applies to it, you have the option of following the terms and "
+"conditions either of that specified version or of any later version that has "
+"been published (not as a draft) by the Free Software Foundation. If the "
+"Document does not specify a version number of this License, you may choose "
+"any version ever published (not as a draft) by the Free Software Foundation."
+msgstr ""
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:639 C/fdl-appendix.xml:651
+msgid "Front-Cover Texts"
+msgstr ""
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:640 C/fdl-appendix.xml:654
+msgid "Back-Cover Texts"
+msgstr ""
+
+#. (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 "
+"version published by the Free Software Foundation; with the <_:link-1/> "
+"being LIST THEIR TITLES, with the <_:link-2/> being LIST, and with the <_:"
+"link-3/> being LIST. A copy of the license is included in the section "
+"entitled <_:quote-4/>."
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:649
+msgid "with no Invariant Sections"
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:652
+msgid "no Front-Cover Texts"
+msgstr ""
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:653
+msgid "Front-Cover Texts being LIST"
+msgstr ""
+
+#. (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 <_:"
+"quote-5/>; likewise for <_:link-6/>."
+msgstr ""
+
+#. (itstool) path: para/ulink
+#: C/fdl-appendix.xml:661
+msgid "GNU General Public License"
+msgstr ""
+
+#. (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 "
+"license, such as the <_:ulink-1/>, to permit their use in free software."
+msgstr ""
+
+#~ msgid "1.12"
+#~ msgstr "1.12"
+
+#~ msgid "Chris"
+#~ msgstr "Chris"
+
+#~ msgid "Lyttle"
+#~ msgstr "Lyttle"
+
+#~ msgid "chris@wilddev.net"
+#~ msgstr "chris@wilddev.net"
+
+#~ msgid "Dan"
+#~ msgstr "Dan"
+
+#~ msgid "Mueth"
+#~ msgstr "Mueth"
+
+#~ msgid "d-mueth@uchicago.edu"
+#~ msgstr "d-mueth@uchicago.edu"
+
+#~ msgid "Stefan"
+#~ msgstr "Stefan"
+
+#~ msgid "Kost"
+#~ msgstr "Kost"
+
+#~ msgid "ensonic@users.sf.net"
+#~ msgstr "ensonic@users.sf.net"
+
+#~ msgid "gtk-doc-list@gnome.org"
+#~ msgstr "gtk-doc-list@gnome.org"
+
+#~ msgid "2000, 2005, 2007-2009"
+#~ msgstr "2000, 2005, 2007-2009"
+
+#~ msgid "Dan Mueth and Chris Lyttle and Stefan Kost"
+#~ msgstr "Dan Mueth, Chris Lyttle a Stefan Kost"
+
+#~ msgid "1.11"
+#~ msgstr "1.11"
+
+#~ msgid "22 March 2008"
+#~ msgstr "22. březen 2008"
+
+#~ msgid "mal"
+#~ msgstr "mal"
+
+#~ msgid "GNOME doc-utils migration"
+#~ msgstr "Migrace GNOME doc-utils"
+
+#~ 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> - Jedná se o DocBook SGML DTD. "
+#~ "<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> - Jedná se o procesor DSSSL na převod SGML "
+#~ "do různých formátů. <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> (Modulární stylopisy "
+#~ "DocBook) Jedná se o kód DSSSL na převod DocBook na HTML (a několik "
+#~ "dalších formátů). Používá se dohromady spolu s jade. Máme mírně "
+#~ "přizpůsobený kód DSSSL v gtk-doc.dsl, který obarví programový kód seznamů/"
+#~ "deklarací a podporuje indexy globálních křížových odkazů v generovaném "
+#~ "HTML. <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> - pokud chcete vytvářet manuálové "
+#~ "stránky z DocBook. Máme mírně přizpůsobené „specifikace překladu“, aby se "
+#~ "hlavičky oddílů změnily na velká písmena a přidal se nadpis „GTK "
+#~ "Library“ (Knihovna GTK) na vrch stránky a datum revize na spodek stránky. "
+#~ "Zde je k tomu odkaz na <ulink url=\"http://www.ora.com/davenport\" type="
+#~ "\"http\">http://www.ora.com/davenport</ulink>. UPOZORNĚNÍ: Ještě to "
+#~ "nefunguje."
+
+#~ msgid ""
+#~ "There is no standard place where the DocBook Modular Stylesheets are "
+#~ "installed."
+#~ msgstr ""
+#~ "Není určeno žádné standardní místo, kam se mají Modular DocBook "
+#~ "Stylesheets nainstalovat."
+
+#~ msgid ""
+#~ "gtk-doc's configure script searches these 3 directories automatically:"
+#~ msgstr "Skript na nastavení gtk-doc prohledává automaticky tyto 3 složky:"
+
+#~ msgid ""
+#~ "<filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> (used by "
+#~ "RedHat)"
+#~ msgstr ""
+#~ "<filename>/usr/lib/sgml/stylesheets/nwalsh-modular</filename> (používá "
+#~ "RedHat)"
+
+#~ msgid ""
+#~ "<filename> /usr/lib/dsssl/stylesheets/docbook </filename> (used by Debian)"
+#~ msgstr ""
+#~ "<filename>/usr/lib/dsssl/stylesheets/docbook</filename> (používá Debian)"
+
+#~ msgid "<filename> /usr/share/sgml/docbkdsl </filename> (used by SuSE)"
+#~ msgstr "<filename>/usr/share/sgml/docbkdsl</filename> (používá 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 ""
+#~ "Pokud máte stylopisy nainstalované kdekoliv jinde, potřebujete nastavit "
+#~ "gtk-doc pomocí přepínače: <command> --with-dsssl-dir=<"
+#~ "CESTA_KE_SLOŽCE_NEJVYŠŠÍ_ÚROVNĚ_SE_STYLOPISY></command>"
+
+#~ msgid ""
+#~ "Besides checking for the required Gtk-Doc version, this adds two "
+#~ "configure switches:"
+#~ msgstr ""
+#~ "Mimo kontroly požadované verze GTK-Doc se tímto přidají dva přepínače "
+#~ "nastavení:"
+
+#~ msgid ""
+#~ "You may also want to enable gtk-doc for the distcheckmake target. Just "
+#~ "add then one-liner show in the next example to you top-level "
+#~ "<filename>Makefile.am</filename>:"
+#~ msgstr ""
+#~ "Můžete také chtít povolit gtk-doc pro provádění make distcheck. Na to "
+#~ "přidejte do nejvyšší úrovně <filename>Makefile.am</filename> jeden řádek "
+#~ "ukázaný v následujícím příkladu:"
+
+#~ msgid ""
+#~ "FIXME having @title here, would put this title into a newly generated "
+#~ "section file, but later would be obsolete (right?)"
+#~ msgstr ""
+#~ "DOPLNIT sem @title, měl vkládal by se do nově generovaného soubor oddílů, "
+#~ "ale později by byl zrušený (?)"
+
+#~ msgid "(FIXME) (stability) (glib-enums, ...)"
+#~ msgstr "(DOPLNIT) (stabilita) (glib-enums, ...)"
+
+#~ msgid ".types"
+#~ msgstr ".types"
+
+#~ msgid "explanation"
+#~ msgstr "vysvětlení"
+
+#~ msgid "Wrong naming in section file (see <placeholder-1/>)"
+#~ msgstr "Špatné pojmenování v souboru oddílů (viz <placeholder-1/>)"
+
+#~ msgid "FIXME (<index> tag in main sgml file)"
+#~ msgstr "DOPLNIT (značka <index> v hlavním souboru sgml)"
+
+#~ msgid "FIXME (added #,% or () ?)"
+#~ msgstr "DOPLNIT (přidat #,% or () ?)"
+
+#~ msgid "FIXME (section file, types file, main-sgml file)"
+#~ msgstr "DOPLNIT (soubor oddílů, soubor typů, hlavní soubor sgml)"
+
+#~ msgid "FIXME (section file, proper doc comment)"
+#~ msgstr "DOPLNIT (soubor oddílů, správný komentář dokumentace)"
--- /dev/null
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ The GNU Free Documentation License 1.1 in DocBook
+ Markup by Eric Baudais <baudais@okstate.edu>
+ Maintained by the GNOME Documentation Project
+ http://developer.gnome.org/projects/gdp
+ Version: 1.0.1
+ Last Modified: Nov 16, 2000
+-->
+<appendix id="fdl">
+ <appendixinfo>
+ <releaseinfo>Verze 1.1, březen 2000</releaseinfo>
+ <copyright>
+ <year>2000</year><holder>Free Software Foundation, Inc.</holder>
+ </copyright>
+ <legalnotice id="fdl-legalnotice">
+ <para><address>Free Software Foundation, Inc. <street>51 Franklin Street,
+ Suite 330</street>, <city>Boston</city>, <state>MA</state>
+ <postcode>02110-1301</postcode> <country>USA</country></address> Kdokoliv je oprávněn kopírovat a šířit doslovné kopie tohoto dokumentu s licencí, ale nesmí v něm provádět žádné změny.</para>
+ </legalnotice>
+ </appendixinfo>
+ <title>GNU Free Documentation License</title>
+
+ <sect1 id="fdl-preamble">
+ <title>0. PREAMBLE</title>
+ <para>
+ The purpose of this License is to make a manual, textbook, or
+ other written document <quote>free</quote> in the sense of
+ freedom: to assure everyone the effective freedom to copy and
+ redistribute it, with or without modifying it, either
+ commercially or noncommercially. Secondarily, this License
+ preserves for the author and publisher a way to get credit for
+ their work, while not being considered responsible for
+ modifications made by others.
+ </para>
+
+ <para>
+ This License is a kind of <quote>copyleft</quote>, which means
+ that derivative works of the document must themselves be free in
+ the same sense. It complements the GNU General Public License,
+ which is a copyleft license designed for free software.
+ </para>
+
+ <para>
+ We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a
+ free program should come with manuals providing the same
+ freedoms that the software does. But this License is not limited
+ to software manuals; it can be used for any textual work,
+ regardless of subject matter or whether it is published as a
+ printed book. We recommend this License principally for works
+ whose purpose is instruction or reference.
+ </para>
+ </sect1>
+ <sect1 id="fdl-section1">
+ <title>1. APPLICABILITY AND DEFINITIONS</title>
+ <para id="fdl-document">
+ This License applies to any manual or other work that contains a
+ notice placed by the copyright holder saying it can be
+ distributed under the terms of this License. The
+ <quote>Document</quote>, below, refers to any such manual or
+ work. Any member of the public is a licensee, and is addressed
+ as <quote>you</quote>.
+ </para>
+
+ <para id="fdl-modified">
+ A <quote>Modified Version</quote> of the Document means any work
+ containing the Document or a portion of it, either copied
+ verbatim, or with modifications and/or translated into another
+ language.
+ </para>
+
+ <para id="fdl-secondary">
+ A <quote>Secondary Section</quote> is a named appendix or a
+ front-matter section of the <link linkend="fdl-document">Document</link> that deals exclusively
+ with the relationship of the publishers or authors of the
+ Document to the Document's overall subject (or to related
+ matters) and contains nothing that could fall directly within
+ that overall subject. (For example, if the Document is in part a
+ textbook of mathematics, a Secondary Section may not explain any
+ mathematics.) The relationship could be a matter of historical
+ connection with the subject or with related matters, or of
+ legal, commercial, philosophical, ethical or political position
+ regarding them.
+ </para>
+
+ <para id="fdl-invariant">
+ The <quote>Invariant Sections</quote> are certain <link linkend="fdl-secondary"> Secondary Sections</link> whose titles
+ are designated, as being those of Invariant Sections, in the
+ notice that says that the <link linkend="fdl-document">Document</link> is released under this
+ License.
+ </para>
+
+ <para id="fdl-cover-texts">
+ The <quote>Cover Texts</quote> are certain short passages of
+ text that are listed, as Front-Cover Texts or Back-Cover Texts,
+ in the notice that says that the <link linkend="fdl-document">Document</link> is released under this
+ License.
+ </para>
+
+ <para id="fdl-transparent">
+ A <quote>Transparent</quote> copy of the <link linkend="fdl-document"> Document</link> means a machine-readable
+ copy, represented in a format whose specification is available
+ to the general public, whose contents can be viewed and edited
+ directly and straightforwardly with generic text editors or (for
+ images composed of pixels) generic paint programs or (for
+ drawings) some widely available drawing editor, and that is
+ suitable for input to text formatters or for automatic
+ translation to a variety of formats suitable for input to text
+ formatters. A copy made in an otherwise Transparent file format
+ whose markup has been designed to thwart or discourage
+ subsequent modification by readers is not Transparent. A copy
+ that is not <quote>Transparent</quote> is called
+ <quote>Opaque</quote>.
+ </para>
+
+ <para>
+ Examples of suitable formats for Transparent copies include
+ plain ASCII without markup, Texinfo input format, LaTeX input
+ format, SGML or XML using a publicly available DTD, and
+ standard-conforming simple HTML designed for human
+ modification. Opaque formats include PostScript, PDF,
+ proprietary formats that can be read and edited only by
+ proprietary word processors, SGML or XML for which the DTD
+ and/or processing tools are not generally available, and the
+ machine-generated HTML produced by some word processors for
+ output purposes only.
+ </para>
+
+ <para id="fdl-title-page">
+ The <quote>Title Page</quote> means, for a printed book, the
+ title page itself, plus such following pages as are needed to
+ hold, legibly, the material this License requires to appear in
+ the title page. For works in formats which do not have any title
+ page as such, <quote>Title Page</quote> means the text near the
+ most prominent appearance of the work's title, preceding the
+ beginning of the body of the text.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section2">
+ <title>2. VERBATIM COPYING</title>
+ <para>
+ You may copy and distribute the <link linkend="fdl-document">Document</link> in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License
+ applies to the Document are reproduced in all copies, and that
+ you add no other conditions whatsoever to those of this
+ License. You may not use technical measures to obstruct or
+ control the reading or further copying of the copies you make or
+ distribute. However, you may accept compensation in exchange for
+ copies. If you distribute a large enough number of copies you
+ must also follow the conditions in <link linkend="fdl-section3">section 3</link>.
+ </para>
+
+ <para>
+ You may also lend copies, under the same conditions stated
+ above, and you may publicly display copies.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section3">
+ <title>3. COPYING IN QUANTITY</title>
+ <para>
+ If you publish printed copies of the <link linkend="fdl-document">Document</link> numbering more than 100,
+ and the Document's license notice requires <link linkend="fdl-cover-texts">Cover Texts</link>, you must enclose
+ the copies in covers that carry, clearly and legibly, all these
+ Cover Texts: Front-Cover Texts on the front cover, and
+ Back-Cover Texts on the back cover. Both covers must also
+ clearly and legibly identify you as the publisher of these
+ copies. The front cover must present the full title with all
+ words of the title equally prominent and visible. You may add
+ other material on the covers in addition. Copying with changes
+ limited to the covers, as long as they preserve the title of the
+ <link linkend="fdl-document">Document</link> and satisfy these
+ conditions, can be treated as verbatim copying in other
+ respects.
+ </para>
+
+ <para>
+ 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 actual cover, and continue the rest onto
+ adjacent pages.
+ </para>
+
+ <para>
+ If you publish or distribute <link linkend="fdl-transparent">Opaque</link> copies of the <link linkend="fdl-document">Document</link> numbering more than 100,
+ you must either include a machine-readable <link linkend="fdl-transparent">Transparent</link> copy along with
+ each Opaque copy, or state in or with each Opaque copy a
+ publicly-accessible computer-network location containing a
+ complete Transparent copy of the Document, free of added
+ material, which the general network-using public has access to
+ download anonymously at no charge using public-standard network
+ protocols. If you use the latter option, you must take
+ reasonably prudent steps, when you begin distribution of Opaque
+ copies in quantity, to ensure that this Transparent copy will
+ remain thus accessible at the stated location until at least one
+ year after the last time you distribute an Opaque copy (directly
+ or through your agents or retailers) of that edition to the
+ public.
+ </para>
+
+ <para>
+ It is requested, but not required, that you contact the authors
+ of the <link linkend="fdl-document">Document</link> well before
+ redistributing any large number of copies, to give them a chance
+ to provide you with an updated version of the Document.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section4">
+ <title>4. MODIFICATIONS</title>
+ <para>
+ You may copy and distribute a <link linkend="fdl-modified">Modified Version</link> of the <link linkend="fdl-document">Document</link> under the conditions of
+ sections <link linkend="fdl-section2">2</link> and <link linkend="fdl-section3">3</link> above, provided that you release
+ the Modified Version under precisely this License, with the
+ Modified Version filling the role of the Document, thus
+ licensing distribution and modification of the Modified Version
+ to whoever possesses a copy of it. In addition, you must do
+ these things in the Modified Version:
+ </para>
+
+ <itemizedlist mark="opencircle">
+ <listitem>
+ <formalpara>
+ <title>A</title>
+ <para>
+ Use in the <link linkend="fdl-title-page">Title
+ Page</link> (and on the covers, if any) a title distinct
+ from that of the <link linkend="fdl-document">Document</link>, and from those of
+ previous versions (which should, if there were any, be
+ listed in the History section of the Document). You may
+ use the same title as a previous version if the original
+ publisher of that version gives permission.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>B</title>
+ <para>
+ List on the <link linkend="fdl-title-page">Title
+ Page</link>, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the
+ <link linkend="fdl-modified">Modified Version</link>,
+ together with at least five of the principal authors of
+ the <link linkend="fdl-document">Document</link> (all of
+ its principal authors, if it has less than five).
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>C</title>
+ <para>
+ State on the <link linkend="fdl-title-page">Title
+ Page</link> the name of the publisher of the <link linkend="fdl-modified">Modified Version</link>, as the
+ publisher.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>D</title>
+ <para>
+ Preserve all the copyright notices of the <link linkend="fdl-document">Document</link>.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>E</title>
+ <para>
+ Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>F</title>
+ <para>
+ Include, immediately after the copyright notices, a
+ license notice giving the public permission to use the
+ <link linkend="fdl-modified">Modified Version</link> under
+ the terms of this License, in the form shown in the
+ Addendum below.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>G</title>
+ <para>
+ Preserve in that license notice the full lists of <link linkend="fdl-invariant"> Invariant Sections</link> and
+ required <link linkend="fdl-cover-texts">Cover
+ Texts</link> given in the <link linkend="fdl-document">Document's</link> license notice.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>H</title>
+ <para>
+ Include an unaltered copy of this License.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>I</title>
+ <para>
+ Preserve the section entitled <quote>History</quote>, and
+ its title, and add to it an item stating at least the
+ title, year, new authors, and publisher of the <link linkend="fdl-modified">Modified Version</link> as given on
+ the <link linkend="fdl-title-page">Title Page</link>. If
+ there is no section entitled <quote>History</quote> in the
+ <link linkend="fdl-document">Document</link>, create one
+ stating the title, year, authors, and publisher of the
+ Document as given on its Title Page, then add an item
+ describing the Modified Version as stated in the previous
+ sentence.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>J</title>
+ <para>
+ Preserve the network location, if any, given in the <link linkend="fdl-document">Document</link> for public access
+ to a <link linkend="fdl-transparent">Transparent</link>
+ copy of the Document, and likewise the network locations
+ given in the Document for previous versions it was based
+ on. These may be placed in the <quote>History</quote>
+ section. You may omit a network location for a work that
+ was published at least four years before the Document
+ itself, or if the original publisher of the version it
+ refers to gives permission.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>K</title>
+ <para>
+ In any section entitled <quote>Acknowledgements</quote> or
+ <quote>Dedications</quote>, preserve the section's title,
+ and preserve in the section all the substance and tone of
+ each of the contributor acknowledgements and/or
+ dedications given therein.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>L</title>
+ <para>
+ Preserve all the <link linkend="fdl-invariant">Invariant
+ Sections</link> of the <link linkend="fdl-document">Document</link>, unaltered in their
+ text and in their titles. Section numbers or the
+ equivalent are not considered part of the section titles.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>M</title>
+ <para>
+ Delete any section entitled
+ <quote>Endorsements</quote>. Such a section may not be
+ included in the <link linkend="fdl-modified">Modified
+ Version</link>.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>N</title>
+ <para>
+ Do not retitle any existing section as
+ <quote>Endorsements</quote> or to conflict in title with
+ any <link linkend="fdl-invariant">Invariant
+ Section</link>.
+ </para>
+ </formalpara>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ If the <link linkend="fdl-modified">Modified Version</link>
+ includes new front-matter sections or appendices that qualify as
+ <link linkend="fdl-secondary">Secondary Sections</link> and
+ contain no material copied from the Document, you may at your
+ option designate some or all of these sections as invariant. To
+ do this, add their titles to the list of <link linkend="fdl-invariant">Invariant Sections</link> in the
+ Modified Version's license notice. These titles must be
+ distinct from any other section titles.
+ </para>
+
+ <para>
+ You may add a section entitled <quote>Endorsements</quote>,
+ provided it contains nothing but endorsements of your <link linkend="fdl-modified">Modified Version</link> by various
+ parties--for example, statements of peer review or that the text
+ has been approved by an organization as the authoritative
+ definition of a standard.
+ </para>
+
+ <para>
+ You may add a passage of up to five words as a <link linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage
+ of up to 25 words as a <link linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of
+ the list of <link linkend="fdl-cover-texts">Cover Texts</link>
+ in the <link linkend="fdl-modified">Modified Version</link>.
+ Only one passage of Front-Cover Text and one of Back-Cover Text
+ may be added by (or through arrangements made by) any one
+ entity. If the <link linkend="fdl-document">Document</link>
+ already includes a cover text for the same cover, previously
+ added by you or by arrangement made by the same entity you are
+ acting on behalf of, you may not add another; but you may
+ replace the old one, on explicit permission from the previous
+ publisher that added the old one.
+ </para>
+
+ <para>
+ The author(s) and publisher(s) of the <link linkend="fdl-document">Document</link> do not by this License
+ give permission to use their names for publicity for or to
+ assert or imply endorsement of any <link linkend="fdl-modified">Modified Version </link>.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section5">
+ <title>5. COMBINING DOCUMENTS</title>
+ <para>
+ You may combine the <link linkend="fdl-document">Document</link>
+ with other documents released under this License, under the
+ terms defined in <link linkend="fdl-section4">section 4</link>
+ above for modified versions, provided that you include in the
+ combination all of the <link linkend="fdl-invariant">Invariant
+ Sections</link> of all of the original documents, unmodified,
+ and list them all as Invariant Sections of your combined work in
+ its license notice.
+ </para>
+
+ <para>
+ The combined work need only contain one copy of this License,
+ and multiple identical <link linkend="fdl-invariant">Invariant
+ Sections</link> may be replaced with a single copy. If there are
+ multiple Invariant Sections with the same name but different
+ contents, make the title of each such section unique by adding
+ at the end of it, in parentheses, the name of the original
+ author or publisher of that section if known, or else a unique
+ number. Make the same adjustment to the section titles in the
+ list of Invariant Sections in the license notice of the combined
+ work.
+ </para>
+
+ <para>
+ In the combination, you must combine any sections entitled
+ <quote>History</quote> in the various original documents,
+ forming one section entitled <quote>History</quote>; likewise
+ combine any sections entitled <quote>Acknowledgements</quote>,
+ and any sections entitled <quote>Dedications</quote>. You must
+ delete all sections entitled <quote>Endorsements.</quote>
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section6">
+ <title>6. COLLECTIONS OF DOCUMENTS</title>
+ <para>
+ You may make a collection consisting of the <link linkend="fdl-document">Document</link> and other documents
+ released under this License, and replace the individual copies
+ of this License in the various documents with a single copy that
+ is included in the collection, provided that you follow the
+ rules of this License for verbatim copying of each of the
+ documents in all other respects.
+ </para>
+
+ <para>
+ 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.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section7">
+ <title>7. AGGREGATION WITH INDEPENDENT WORKS</title>
+ <para>
+ A compilation of the <link linkend="fdl-document">Document</link> or its derivatives with
+ other separate and independent documents or works, in or on a
+ volume of a storage or distribution medium, does not as a whole
+ count as a <link linkend="fdl-modified">Modified Version</link>
+ of the Document, provided no compilation copyright is claimed
+ for the compilation. Such a compilation is called an
+ <quote>aggregate</quote>, and this License does not apply to the
+ other self-contained works thus compiled with the Document , on
+ account of their being thus compiled, if they are not themselves
+ derivative works of the Document. If the <link linkend="fdl-cover-texts">Cover Text</link> requirement of <link linkend="fdl-section3">section 3</link> is applicable to these
+ copies of the Document, then if the Document is less than one
+ quarter of the entire aggregate, the Document's Cover Texts may
+ be placed on covers that surround only the Document within the
+ aggregate. Otherwise they must appear on covers around the whole
+ aggregate.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section8">
+ <title>8. TRANSLATION</title>
+ <para>
+ Translation is considered a kind of modification, so you may
+ distribute translations of the <link linkend="fdl-document">Document</link> under the terms of <link linkend="fdl-section4">section 4</link>. Replacing <link linkend="fdl-invariant"> Invariant Sections</link> with
+ translations requires special permission from their copyright
+ holders, but you may include translations of some or all
+ Invariant Sections in addition to the original versions of these
+ Invariant Sections. You may include a translation of this
+ License provided that you also include the original English
+ version of this License. In case of a disagreement between the
+ translation and the original English version of this License,
+ the original English version will prevail.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section9">
+ <title>9. TERMINATION</title>
+ <para>
+ You may not copy, modify, sublicense, or distribute the <link linkend="fdl-document">Document</link> except as expressly
+ provided for under this License. Any other attempt to copy,
+ modify, sublicense or distribute the Document is void, and will
+ automatically terminate your rights under this License. However,
+ parties who have received copies, or rights, from you under this
+ License will not have their licenses terminated so long as such
+ parties remain in full compliance.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section10">
+ <title>10. FUTURE REVISIONS OF THIS LICENSE</title>
+ <para>
+ The <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software
+ Foundation</ulink> may publish new, revised versions of the GNU
+ Free Documentation License from time to time. Such new versions
+ will be similar in spirit to the present version, but may differ
+ in detail to address new problems or concerns. See <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.
+ </para>
+
+ <para>
+ Each version of the License is given a distinguishing version
+ number. If the <link linkend="fdl-document">Document</link>
+ specifies that a particular numbered version of this License
+ <quote>or any later version</quote> applies to it, you have the
+ option of following the terms and conditions either of that
+ specified version or of any later version that has been
+ published (not as a draft) by the Free Software Foundation. If
+ the Document does not specify a version number of this License,
+ you may choose any version ever published (not as a draft) by
+ the Free Software Foundation.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-using">
+ <title>Addendum</title>
+ <para>
+ 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 just after the title page:
+ </para>
+
+ <blockquote>
+ <para>
+ Copyright YEAR YOUR NAME.
+ </para>
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation
+ License, Version 1.1 or any later version published by the
+ Free Software Foundation; with the <link linkend="fdl-invariant">Invariant Sections</link> being LIST
+ THEIR TITLES, with the <link linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST,
+ and with the <link linkend="fdl-cover-texts">Back-Cover
+ Texts</link> being LIST. A copy of the license is included in
+ the section entitled <quote>GNU Free Documentation
+ License</quote>.
+ </para>
+ </blockquote>
+
+ <para>
+ If you have no <link linkend="fdl-invariant">Invariant
+ Sections</link>, write <quote>with no Invariant Sections</quote>
+ instead of saying which ones are invariant. If you have no
+ <link linkend="fdl-cover-texts">Front-Cover Texts</link>, write
+ <quote>no Front-Cover Texts</quote> instead of
+ <quote>Front-Cover Texts being LIST</quote>; likewise for <link linkend="fdl-cover-texts">Back-Cover Texts</link>.
+ </para>
+
+ <para>
+ If your document contains nontrivial examples of program code,
+ we recommend releasing these examples in parallel under your
+ choice of free software license, such as the <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public
+ License</ulink>, to permit their use in free software.
+ </para>
+ </sect1>
+</appendix>
--- /dev/null
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<?xml-stylesheet type="text/xml" href="params.xsl"?>
+<!-- vim: set ai tw=80 ts=3 sw=3: -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "
+ http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY FDL SYSTEM "fdl-appendix.xml">
+<!ENTITY FDLlink "<link linkend='fdl'>included</link>">
+]>
+<!-- =============Document Header ============================= -->
+<book id="index" lang="cs">
+ <bookinfo>
+ <title>Příručka ke GTK-Doc</title>
+ <edition>1.24.1</edition>
+ <abstract role="description"><para>Uživatelská příručka pro vývojáře s instrukcemi k používání GTK-Doc.</para></abstract>
+ <authorgroup>
+ <author><firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation><address><email>chris@wilddev.net</email></address></affiliation></author>
+ <author><firstname>Dan</firstname> <surname>Mueth</surname> <affiliation><address><email>d-mueth@uchicago.edu</email></address></affiliation></author>
+ <author><firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> <affiliation><address><email>ensonic@users.sf.net</email></address></affiliation></author>
+ </authorgroup>
+ <publisher role="maintainer"><publishername>Projekt GTK-Doc</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
+ <copyright><year>2000, 2005</year> <holder>Dan Mueth and Chris Lyttle</holder></copyright>
+ <copyright><year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder></copyright>
+
+ <!-- translators: uncomment this:
+ <copyright>
+ <year>2000</year>
+ <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
+ </copyright>
+ -->
+
+ <legalnotice>
+ <para>Je povoleno kopírovat, šířit a/nebo upravovat tento dokument za podmínek <citetitle>GNU Free Documentation License</citetitle> ve verzi 1.1 nebo v jakékoli další verzi vydané nadací Free Software Foundation, s neměnnými oddíly, bez textů předních desek a bez textů zadních desek. Kopie licence je <link linkend="fdl">součástí</link>.</para>
+ <para>Mnoho názvů použitých firmami k zviditelnění produktů nebo služeb jsou ochranné známky. Na místech, kde jsou tyto názvy v dokumentaci použity a členové Dokumentačního projektu GNOME jsou si vědomi skutečnosti, že se jedná o ochrannou známku, je takovýto název psán velkými písmeny celý nebo s velkým písmenem na začátku.</para>
+ </legalnotice>
+
+ <revhistory>
+ <revision><revnumber>1.25.1</revnumber> <date>21. březen 2016</date> <authorinitials>ss</authorinitials> <revremark>development version</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.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>
+ <revision><revnumber>1.17</revnumber> <date>26. únor 2011</date> <authorinitials>sk</authorinitials> <revremark>aktualizace kvůli neodkladné opravě chyby</revremark></revision>
+ <revision><revnumber>1.16</revnumber> <date>14. leden 2011</date> <authorinitials>sk</authorinitials> <revremark>opravy chyb, vylepšení vzhledu</revremark></revision>
+ <revision><revnumber>1.15</revnumber> <date>21. květen 2010</date> <authorinitials>sk</authorinitials> <revremark>opravy chyb a regresí</revremark></revision>
+ <revision><revnumber>1.14</revnumber> <date>28. březen 2010</date> <authorinitials>sk</authorinitials> <revremark>opravy chyb a vylepšení výkonu</revremark></revision>
+ <revision><revnumber>1.13</revnumber> <date>18. prosinec 2009</date> <authorinitials>sk</authorinitials> <revremark>aktualizace poškozeného balíčku</revremark></revision>
+ <revision><revnumber>1.12</revnumber> <date>18. prosinec 2009</date> <authorinitials>sk</authorinitials> <revremark>nové funkce nástroje a opravy chyb</revremark></revision>
+ <revision><revnumber>1.11</revnumber> <date>16. listopad 2008</date> <authorinitials>mal</authorinitials> <revremark>přechod na doc-utils z GNOME</revremark></revision>
+ </revhistory>
+
+ </bookinfo>
+
+ <!-- ======== Chapter 1: Introduction ======================== -->
+
+ <chapter id="introduction">
+ <title>Úvod</title>
+
+ <para>Tato kapitola je úvodem do GTK-Doc a podává přehled o tom, co to je a jak to použít.</para>
+
+ <sect1 id="whatisgtkdoc">
+ <title>Co je to GTK-Doc?</title>
+
+ <para>GTK-Doc se používá k dokumentaci kódu jazyka C. Typické použití je pro dokumentaci veřejného API knihoven, jako jsou knihovny GTK+ a GNOME. Lze jej ale použít i k dokumentaci aplikačního kódu.</para>
+ </sect1>
+
+ <sect1 id="howdoesgtkdocwork">
+ <title>Jak GTK-Doc pracuje?</title>
+
+ <para>GTK-Doc pracuje na základě dokumentace funkcí umístěné přímo v souborech se zdrojovým kódem ve speciálně formátovaných komentářových blocích, nebo dokumentace přidané do souborů šablon, které GTK-Doc používá (ačkoliv je nutno poznamenat, že GTK-Doc dokumentuje pouze funkce, které jsou deklarované v hlavičkových souborech; pro statické funkce žádný výstup nevytváří).</para>
+
+ <para>GTK-Doc sestává z řady perlových skriptů, z nichž každý provádí jinou část procesu.</para>
+
+ <para>Celý proces se skládá z pěti hlavních kroků:</para>
+
+ <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>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Shromáždění informací o kódu.</guilabel> <application>gtkdoc-scan</application> projde hlavičkové soubory kódu a vyhledá při tom deklarace funkcí, maker, výčtů, struktur a sjednocení. Tím se vytvoří soubor <filename><module>-decl-list.txt</filename> obsahující seznam deklarací, které jsou rozdělené do oddílů podle hlavičkového souboru, ze kterého pochází. Při prvním spuštění se tento soubor zkopíruje do <filename><module>-sections.txt</filename>. Autor může změnit uspořádání oddílů a jejich pořadí v rámci deklarací tak, jak to požaduje ve výsledku. Druhý soubor, který se vytvoří, je <filename><module>-decl.txt</filename>. Tento soubor obsahuje úplné deklarace nalezené při procházení. Pokud byste z nějakého důvodu chtěli v dokumentaci zahrnout symbol, který při procházení nebyl nalezen, nebo jeho deklarace vypadá jinak, můžete jej umístit podobně jako v <filename><module>-decl.txt</filename> do <filename><module>-overrides.txt</filename>.</para>
+ <para>Dá se také použít <application>gtkdoc-scanobj</application> k dynamickým dotazům do knihoven na podtřídy objektu GObject, které exportují. Tím se uloží informace o pozici každého objektu v hierarchii tříd a o argumentech a signálech objektu GObject, které poskytují.</para>
+ <para><application>gtkdoc-scanobj</application> by se ale již používat nemělo. Bylo zapotřebí v minulosti, kdy byl GObject ještě GtkObject v rámci gtk+.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Generování XML a HTML/PDF.</guilabel> <application>gtkdoc-mkdb</application> přemění soubory šablon na soubory XML v podsložce <filename class="directory">xml/</filename>. Pokud zdrojový kód obsahuje dokumentaci funkcí za použití speciálních komentářových bloků, tak zde se sloučí. V případě, že není použitý žádný soubor šablon, načte se dokumentace pouze ze zdrojového kódu a introspektivních dat.</para>
+ <para><application>gtkdoc-mkhtml</application> převádí soubory XML na soubory HTML v podsložce <filename class="directory">html/</filename>. Obdobně <application>gtkdoc-mkpdf</application> převádí soubory XML na dokument PDF nazvaný <filename><balíček>.pdf</filename>.</para>
+ <para>Soubory ve složkách <filename class="directory">xml/</filename> a <filename class="directory">html/</filename> jsou vždy přepsány. Nikdy by neměly být upravovány přímo.</para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Opravy křížových odkazů mezi dokumenty.</guilabel> Po nainstalování souborů HTML můžete spustit <application>gtkdoc-fixxref</application>, aby se opravily křížové odkazy mezi samostanými dokumenty. Například dokumentace GTK+ obsahuje křížové odkazy na typy zdokumentované v příručce GLib. Když vytváříte zdrojový balíček pro distribuci, <application>gtkdoc-rebase</application> předělá všechny externí odkazy na webové odkazy. Když se distribuovaná (předgenerovaná) dokumentace instaluje, pokusí se tatáž aplikace předělat odkazy zpátky na místní odkazy (na dokumenty, které jsou nainstalované).</para>
+ </listitem>
+ </orderedlist>
+
+ </sect1>
+
+ <sect1 id="gettinggtkdoc">
+ <title>Jak získat GTK-Doc?</title>
+
+ <sect2 id="requirements">
+ <title>Požadavky</title>
+ <para><guilabel>Perl v5</guilabel> – hlavní skripty jsou v jazyce Perl.</para>
+ <para><guilabel>xsltproc</guilabel> – procesor xslt z knihovny libxslt <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink></para>
+ <para><guilabel>docbook-xsl</guilabel> – stylopisy XSL pro docbook <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink></para>
+ <para><guilabel>Python</guilabel> – pro gtkdoc-depscan (volitelné)</para>
+ <para>Něco z <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> nebo <guilabel>vim</guilabel> – (volitelné) používá se pro zvýraznění syntaxe u příkladů</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="aboutgtkdoc">
+ <title>O aplikaci GTK-Doc</title>
+
+ <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>
+
+ </sect1>
+
+ <sect1 id="aboutthismanual">
+ <title>O této příručce</title>
+
+ <para>(DOPLNIT)</para>
+
+ <para>(k čemu je určená, kde ji můžete získat, licence)</para>
+
+ </sect1>
+
+ </chapter>
+
+ <chapter id="settingup">
+ <title>Nastavení vašeho projektu</title>
+
+ <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>
+
+ <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>Ve výsledku to může vypadat nějak takto: <example><title>Příklad struktury složek</title>
+ <programlisting>
+meep/
+ docs/
+ reference/
+ libmeep/
+ meeper/
+ src/
+ libmeep/
+ meeper/
+</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>
+
+ <para>
+ <example><title>Integrace s autoconf</title>
+ <programlisting>
+# check for gtk-doc
+GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
+</programlisting>
+ </example>
+ </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>
+ <programlisting>
+# check for gtk-doc
+m4_ifdef([GTK_DOC_CHECK], [
+GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
+],[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+</programlisting>
+ </example></para>
+
+ <para>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>
+
+ <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>
+
+ <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>
+ <example><title>Příprava pro gtkdocize</title>
+ <programlisting>
+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>
+
+ <sect1 id="settingup_automake">
+ <title>Integrace s automake</title>
+
+ <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>
+
+ <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>
+
+ <!-- FIXME: explain options ? -->
+
+ </sect1>
+
+ <sect1 id="settingup_autogen">
+ <title>Integrace s autogen</title>
+
+ <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>
+ <example><title>Spuštění gtkdocize z autogen.sh</title>
+ <programlisting>
+gtkdocize || exit 1
+</programlisting>
+ </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>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>
+
+ <sect1 id="settingup_firstrun">
+ <title>Sestavení dokumentace</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>
+ </sect1>
+
+ <sect1 id="settingup_vcs">
+ <title>Integrace se systémem pro správu verzí</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>
+ </sect1>
+
+ <sect1 id="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>
+ <example><title>Kroky sestavení dokumentace</title>
+ <programlisting>
+DOC_MODULE=meep
+// sources have changed
+gtkdoc-scan --module=$(DOC_MODULE) <zdrojová-složka>
+gtkdoc-scangobj --module=$(DOC_MODULE)
+gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<zdrojová-složka>
+// xml files have changed
+mkdir html
+cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
+gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
+</programlisting>
+ </example>
+ </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
+)
+
+# 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>
+ </chapter>
+
+ <chapter id="documenting">
+ <title>Dokumentování v kódu</title>
+
+ <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>
+#ifndef __GTK_DOC_IGNORE__
+/* kód zde se nezpracovává */
+#endif
+</programlisting>
+ </example></para>
+
+ <note>
+ <title>Omezení</title>
+ <para>Uvědomte si, že GTK-Doc podporuje <code>#ifndef(__GTK_DOC_IGNORE__)</code>, ale ne <code>#if !defined(__GTK_DOC_IGNORE__)</code> nebo jiné kombinace.</para>
+ </note>
+
+ <!-- -->
+
+ <sect1 id="documenting_syntax">
+ <title>Dokumentační komentáře</title>
+
+ <para>Každý víceřádkový komentář, který je označený další „*“ navíc, je dokumentačním blokem a bude zpracovaný nástroji GTK-Doc. <example><title>Komentářový blok GTK-Doc</title>
+ <programlisting>
+/**
+ * identifikátor:
+ * dokumentace …
+ */
+</programlisting>
+ </example></para>
+
+ <para>„identifikátor“ je jeden řádek s názvem položky, ke které se komentář vztahuje. Syntaxe se částečně liší podle položky. (DOPLNIT: přidat tabulku se seznamem identifikátorů)</para>
+
+ <para>Blok „dokumentace“ se rovněž liší pro různé typy symbolů. Symboly, které přebírají parametry, jako jsou funkce nebo makra, mají nejdříve popsané parametry, za kterými následuje prázdný řádek (pouze „*“). Za ním pak následuje podrobný popis. Všechny řádky (mimo seznamu programů a oddílu CDATA), které obsahují „ *“ (mezera hvězdička) se převedou na zalomení odstavce. Pokud zalomení odstavce nechcete, změňte to na „ * “ (mezera hvězdička mezera mezera). To se hodí na text s pevným formátem (výpis kódu).</para>
+
+ <tip>
+ <para>Když píšete dokumentaci ke kódu, popište dva aspekty: <itemizedlist>
+ <listitem>
+ <para>Co to je: Název třídy nebo funkce může být občas matoucí pro lidi, kteří používají něco jiného.</para>
+ </listitem>
+ <listitem>
+ <para>K čemu to je: Uveďte běžném použití. Dejte ho do souvislosti se zbytkem API.</para>
+ </listitem>
+ </itemizedlist></para>
+ </tip>
+
+ <para>Jednou z výhod hypertextu, oproti prostému textu, je možnost mít v dokumentu odkazy. Zápis správných značek pro odkazy může být úmorná práce. GTK-Doc se vám snaží pomoci několika užitečnými zkratkami. <itemizedlist>
+ <listitem>
+ <para>Použijte funkce() pro odkaz na funkci nebo makro, které mají argumenty.</para>
+ </listitem>
+ <listitem>
+ <para>Použijte @parametr pro odkaz na parametry. Použijte to rovněž, když se odkazujete na parametry jiných funkcí, vztahujících se k popisované funkci.</para>
+ </listitem>
+ <listitem>
+ <para>Použijte %konstanta pro odkaz na konstantu, např. %G_TRAVERSE_LEAFS.</para>
+ </listitem>
+ <listitem>
+ <para>Použijte #symbol pro odkaz na jiný typ symbolu, např. strukturu, výčet a makro, který nemá argumenty.</para>
+ </listitem>
+ <listitem>
+ <para>Použijte #Objekt::signál pro odkaz na signál objektu GObject.</para>
+ </listitem>
+ <listitem>
+ <para>Použijte #Objekt:vlastnost pro odkaz na vlastnost objektu GObject.</para>
+ </listitem>
+ <listitem>
+ <para>Použijte #Struktura.pole pro odkaz na pole uvnitř struktury a #GObjectTřída.neco() pro odkaz na virtuální metodu.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <tip>
+ <para>V případě, že potřebujete ve své dokumentaci použít speciální znaky „<“, „>“, „()“, „@“, „%“ nebo „#“, aniž by je GTK-Doc změnilo, můžete místo nich použít použít entity XML „&lt;“, „&gt;“, „&lpar;“, „&rpar;“, „&commat;“, „&percnt;“ a „&num;“ nebo únikovou sekvenci se zpětným lomítkem „\“.</para>
+ </tip>
+
+ <para>DocBook toho ale umí více, než jen odkazy. Může mít také seznamy, příklady, nadpisy a obrázky. Od verze 1.20 je dána přednost použití jen podmnožiny ze základní syntaxe formátování textu. Tato podmnožina se nazývá <ulink url="http://daringfireball.net/projects/markdown/">Markdown</ulink>. Dokumentace ze starší verze GTK-Doc, která obsahuje Markdown, bude vygenerována tak, jak je. Například položky seznamu se objeví s pomlčkou na začátku.</para>
+
+ <para>I když je markdown v současnosti preferovaný, můžete míchat oba dohromady. Má to jediné omezení v tom, že můžete použít docbook xml v markdown, ale markdown v docbook xml podporován není.</para>
+
+ <para>Když ve starších vydáních GTK-Doc potřebujete podporu pro dodatečné formátování, musíte zapnout použití značek XML pro DocBook uvnitř dokumentačních komentářů pomocí <option>--xml-mode</option> (nebo <option>--sgml-mode</option>) v proměnné <symbol>MKDB_OPTIONS</symbol> v souboru <filename>Makefile.am</filename>.</para>
+
+ <para>
+ <example><title>Komentářový blok GTK-Doc používající značkovací jazyk</title>
+ <programlisting>
+/**
+ * identifikátor:
+ *
+ * odstavec dokumentace…
+ *
+ * # Podnadpis #
+ *
+ * ## Podnadpis druhé úrovně
+ *
+ * # Podnadpis s kotvou pro odkazy # {#heading-two}
+ *
+ * další dokumentace:
+ *
+ * - položka seznamu 1
+ *
+ * Odstavec v rámci položky seznamu.
+ *
+ * - položka seznamu 2
+ *
+ * 1. číslovaná položka seznamu
+ *
+ * 2. další číslovaná položka seznamu
+ *
+ * Další odstavec. [Odkazy na webové stránky GNOME](http://www.gnome.org/)
+ *
+ * 
+ *
+ * [Odkaz na nadpis pomocí kotvy uvedené výše][heading-two]
+ *
+ * Příklad v jazyce C:
+ * |[<!-- language="C" -->
+ * GtkWidget *label = gtk_label_new ("Paráda!");
+ * ]|
+ */
+</programlisting>
+ </example>
+ </para>
+
+ <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>
+ </tip>
+ </sect1>
+
+ <sect1 id="documenting_sections">
+ <title>Dokumentování oddílů</title>
+
+ <para>Každý oddíl dokumentace obsahuje informaci o jedné třídě nebo modulu. Můžete do oddílu napsat blok, ve kterém je představíte. Stručný popis se rovněž použije v rámci tabulky s obsahem. Všechna @pole jsou volitelná.</para>
+
+ <para>
+ <example><title>Komentářový blok oddílu</title>
+ <programlisting>
+/**
+ * SECTION:meepapp
+ * @short_description: třída plikace
+ * @title: Aplikace Meep
+ * @section_id:
+ * @see_also: #MeepSettings
+ * @stability: Stable
+ * @include: meep/app.h
+ * @image: application.png
+ *
+ * Třída aplikace starající se o…
+ */
+</programlisting>
+ </example>
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>SECTION:<název></term>
+ <listitem>
+ <para>
+ The name links the section documentation to the respective part in
+ the <filename><package>-sections.txt</filename> file. The
+ name given here should match the <FILE> tag in the
+ <filename><package>-sections.txt</filename> file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@short_description</term>
+ <listitem>
+ <para>Jednořádkový popis oddílu, který se později objeví za odkazy v tabulce s obsahem a na začátku stránky oddílu.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@title</term>
+ <listitem>
+ <para>Název oddílu se standardně zvolí podle <name> v deklaraci SECTION. Lze jej ale určit i přímo v poli @title.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@section_id</term>
+ <listitem>
+ <para>Přepíše použití názvu jako identifikátoru oddílu. Pro objekty GObject se jako section_id použije <title> a pro ostatní oddíly to je <MODULE>-<title>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@see_also</term>
+ <listitem>
+ <para>Seznam symbolů, které se vztahují k tomuto oddílu.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@stability</term>
+ <listitem>
+ <para>Informační popis úrovně stability tohoto API. Doporučujeme použít jeden z těchto termínů: <itemizedlist>
+ <listitem>
+ <para>Stable (stabilní) – Záměrem stabilního rozhraní je umožnit libovolné třetí straně vyvinout aplikace využívající toto rozhraní, vydat je a moci se spolehnout, že poběží na všech podružných vydáních produktu (po té, co je rozhraní vydáno a v rámci stejné hlavní verze). I mezi hlavními vydáními se nekompatibilní změny očekávají zřídka v opravdu odůvodněných případech.</para>
+ </listitem>
+ <listitem>
+ <para>Unstable (nestabilní) – Nestabilní rozhraní je experimentální a přechodné. Typicky bývá dáno vývojářům k dispozici kvůli včasnému přístupu k novým a rychle se měnícím technologiím nebo kvůli poskytnutí provizorního řešení problému, kdy je předpokládané více obecné řešení. Není žádná záruka ohledně zdrojové či binární kompatibility při přechodu z jedné podružné verze na následujíc.</para>
+ </listitem>
+ <listitem>
+ <para>Private (soukromé) – Rozhraní, které může být použité v rámci zásobníku GNOME, ale není dokumentované pro koncového uživatele. Takové funkce by se měly používat jen určeným a dokumentovaným způsobem.</para>
+ </listitem>
+ <listitem>
+ <para>Internal (interní) – Rozhraní, které je určené pro interní potřeby modulu a nevyžaduje dokumentaci pro koncového uživatele. Funkce, které jsou nedokumentované, jsou považované za interní.</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@include</term>
+ <listitem>
+ <para>Seznam souborů z <literal>#include</literal> oddělených čárkou, aby se zobrazily v oddílu anotace. Přepisuje globální hodnotu ze <link linkend="metafiles_sections">souboru oddílů</link> nebo příkazové řádky. Tato položka je volitelná.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>@image</term>
+ <listitem>
+ <para>Obrázek, který se má zobrazit na začátku referenční stránky k tomuto oddílu. Často se jedná o nějaký nákres, který schématicky znázorňuje podobu třídy nebo nákres se vztahy vůči jiným třídám. Tato položka je volitelná.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <tip>
+ <para>Aby se po změně dokumentace předešlo rekompilacím, které nejsou nutné, vložte, kde je to možné, dokumentaci oddílu do zdrojového kódu c.</para>
+ </tip>
+
+ </sect1>
+
+ <sect1 id="documenting_symbols">
+ <title>Dokumentování symbolů</title>
+
+ <para>Každý symbol (funkce, makro, struktura, výčet, signál a vlastnost) se dokumentuje v odděleném bloku. Blok je nejlepší umístit v rámci definice symbolu, protože se tak snadno udržuje synchronizovaný. Z tohoto důvodu se funkce obvykle dokumentují ve zdrojovém kódu C a makra, struktury a výčty v hlavičkovém souboru.</para>
+
+ <sect2><title>Obecné značky</title>
+
+ <para>Informace o verzích můžete přidat ke všem prvkům dokumentace, abyste sdělili, kdy bylo API zavedeno, nebo kdy bylo označeno za zastaralé.</para>
+
+ <variablelist><title>Značky pro verzování</title>
+ <varlistentry><term>Since:</term>
+ <listitem>
+ <para>Popisuje, od které verze kódu je API dostupné.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>Deprecated:</term>
+ <listitem>
+ <para>Odstavec upozorňující, že by se tato funkce neměla nadále používat. Popis by měl čtenáře odkazovat na nové API.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Můžete také ke všem prvkům dokumentace přidat informaci o stabilitě, abyste dali najevo, že je u API zaručena stabilita pro všechna následující minoritní vydání projektu.</para>
+
+ <para>Výchozí stabilitu pro všechny prvky dokumentace můžete pomocí argumentu <option>--default-stability</option> s jednou u níže uvedených hodnot předat do <application>gtkdoc-mkdb</application>.</para>
+
+ <variablelist><title>Značky pro stabilitu</title>
+ <varlistentry><term>Stability: Stable</term>
+ <listitem>
+ <para>Označuje prvek jako stabilní. Je to určeno pro veřejná API, která zaručují, že zůstanou stabilní po všechna minoritní vydání projektu.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>Stability: Unstable</term>
+ <listitem>
+ <para>Označuje prvek jako nestabilní. Je to určeno pro veřejná API, která jsou vydána jako ukázky před tím, než jsou stabilizována.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>Stability: Private</term>
+ <listitem>
+ <para>Označuje prvek jako soukromý. Je to určeno pro rozhraní, která mohou být použita přímo v modulu, ale ne kterýmikoliv třetími stranami.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <example><title>Obecné značky</title>
+ <programlisting>
+/**
+ * foo_get_bar:
+ * @foo: nějaké něco
+ *
+ * Získá @foo něčeho.
+ *
+ * Returns: @foo něčeho
+ *
+ * Since: 2.6
+ * Deprecated: 2.12: Místo toho použijte foo_baz_get_bar().
+ */
+Bar *
+foo_get_bar(Foo *foo)
+{
+...
+</programlisting>
+ </example>
+ </sect2>
+
+ <sect2><title>Anotace</title>
+
+ <para>Dokumentační bloky mohou obsahovat anotační štítky. Tyto štítky budou zpracovány jako vysvětlivky popisující jejich význam. Používají se introspekcí objektu GObjekt k vygenerování vazby na další jazyky. Podrobný seznam podporovaných štítků můžete najít na <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">wiki</ulink>.</para>
+
+ <example><title>Anotace</title>
+ <programlisting>
+/**
+ * foo_get_bar: (annotation)
+ * @foo: (annotation): nějaké něco
+ *
+ * Získá @foo něčeho.
+ *
+ * Returns: (annotation): @foo něčeho
+ */
+...
+/**
+ * foo_set_bar_using_the_frobnicator: (annotation) (annotation)
+ * (annotation) …
+ * @foo: (annotation) (annotation) …: nějaké něco
+ *
+ * Nastaví něco na @foo.
+ */
+</programlisting>
+ </example>
+ </sect2>
+
+ <sect2><title>Komentářový blok pro funkci</title>
+
+ <para>Nezapomeňte prosím: <itemizedlist>
+ <listitem>
+ <para>Zdokumentovat, jestli je třeba vracené objekty, seznamy, řetězce apod. uvolnit z paměti.</para>
+ </listitem>
+ <listitem>
+ <para>Zdokumentovat, jestli může parametr být NULL a co se stane, když tomu tak je.</para>
+ </listitem>
+ <listitem>
+ <para>Kde je to vhodné, zmínit úvodní a koncové podmínky.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>Gtk-doc předpokládá, že všechny symboly (makra, funkce) začínající znakem „_“, jsou soukromé. Potom se s nimi zachází jako se statickými funkcemi.</para>
+
+ <example><title>Komentářový blok pro funkci</title>
+ <programlisting>
+/**
+ * function_name:
+ * @par1: popis parametru 1. Může zabírat více jak
+ * jeden řádek.
+ * @par2: popis parametru 2
+ * @...: seznam proměnných parametrů zakončených NULL
+ *
+ * Zde pokračuje popis funkce. K odkazu na parametr můžete použit @par1,
+ * takže bude ve výstupu zvýrazněný. Můžete také použít %constant pro
+ * konstanty, function_name() pro funkce a #GtkWidget pro odkazy na jiné
+ * deklarace (které mohou být zdokumentované jinde).
+ *
+ * Returns: celé číslo.
+ *
+ * Since: 2.2
+ * Deprecated: 2.18: Místo toho použijte other_function().
+ */
+</programlisting>
+ </example>
+
+ <variablelist><title>Značky pro funkce</title>
+ <varlistentry><term>Returns:</term>
+ <listitem>
+ <para>Odstavec popisující vracený výsledek.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>@…:</term>
+ <listitem>
+ <para>Když má funkce proměnný počet argumentů, měli byste použít tuto značku (z historických důvodů funguje i @Varargs:).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2><title>Komentářový blok pro vlastnost</title>
+
+ <example><title>Komentářový blok pro vlastnost</title>
+ <programlisting>
+/**
+ * SomeWidget:some-property:
+ *
+ * Zde vlastnost zdokumentujte.
+ */
+g_object_class_install_property (object_class, PROP_SOME_PROPERTY, …);
+</programlisting>
+ </example>
+
+ </sect2>
+
+ <sect2><title>Komentářový blok pro signál</title>
+
+ <para>Nezapomeňte prosím: <itemizedlist>
+ <listitem>
+ <para>Zdokumentovat, kdy je signál vyslán a jestli je vyslána před nebo po ostatních signálech.</para>
+ </listitem>
+ <listitem>
+ <para>Zdokumentovat, co aplikace smí v obsluze signálu provádět.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <example><title>Komentářový blok pro signál</title>
+ <programlisting>
+/**
+ * FooWidget::foobarized:
+ * @widget: widget, který signál přijímá
+ * @foo: nějaké něco
+ * @bar: jiné něco
+ *
+ * Signál ::foobarized je vyslán pokaždé, když někdo zkusí něco s @widget.
+ */
+foo_signals[FOOBARIZE] =
+ g_signal_new ("foobarize",
+ ...
+</programlisting>
+ </example>
+
+ </sect2>
+
+ <sect2><title>Komentářový blok pro strukturu</title>
+ <example><title>Komentářový blok pro strukturu</title>
+ <programlisting>
+/**
+ * FooWidget:
+ * @bar: nějaká #gboolean
+ *
+ * Tohle je ten nejlepší widget.
+ */
+typedef struct _FooWidget {
+ GtkWidget parent_instance;
+
+ gboolean bar;
+} FooWidget;
+</programlisting>
+ </example>
+
+ <para>Před privátními poli struktury použijte <code>/*< private >*/</code>, abyste je skryli. K přesně opačnému účelu se používá <code>/*< public >*/</code>.</para>
+
+ <para>Pokud je prvním polem „g_iface“, „parent_instance“ nebo „parent_class“, bude za privátní považováno automaticky a není to zapotřebí zmiňovat v komentářovém bloku.</para>
+
+ <para>Komentářové bloky struktur můžete použít také pro objekty GObject a třídy GObjectClass. Obvykle je rozumné přidat komentářový blok pro třídu, pokud má virtuální metody (protože to je způsob, jakým je lze zdokumentovat). Pro vlastní GObject je možné použít příslušnou dokumentaci oddílu, který bude mít samostatný blok pro strukturu instance, což se může hodit, když má instance veřejná pole. Jedinou nevýhodou je, že se tím vytvoří dvě položky v rejstříku se stejným názvem (struktura a oddíl).</para>
+
+ </sect2>
+
+ <sect2><title>Komentářový blok pro výčty</title>
+ <example><title>Komentářový blok pro výčty</title>
+ <programlisting>
+/**
+ * Something:
+ * @SOMETHING_FOO: nějaké něco
+ * @SOMETHING_BAR: jiné něco
+ *
+ * Výčtové hodnoty používané pro určení věci.
+ */
+typedef enum {
+ SOMETHING_FOO,
+ SOMETHING_BAR,
+ /*< private >*/
+ SOMETHING_COUNT
+} Something;
+</programlisting>
+ </example>
+
+ <para>Před privátními výčtovými hodnotami použijte <code>/*< private >*/</code>, abyste je skryli. K přesně opačnému účelu se používá <code>/*< public >*/</code>.</para>
+
+ </sect2>
+ </sect1>
+
+
+ <sect1 id="documenting_inline_program">
+ <title>Dokumentaci k vloženým programům</title>
+ <para>Programy a jejich rozhraní příkazového řádku můžete zdokumentovat pomocí vložené dokumentace.</para>
+
+ <variablelist>
+ <title>Značky</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>Definuje začátek dokumentace k programu.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>Definuje krátký popis programu. (volitelné)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>Definuje argumenty nebo seznam argumentů, které program přebírá. (volitelné)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>Část stránky oddílu „Viz také“. (volitelné)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>Argument(y) předávané do programu a jejich popis. (volitelné)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>Úplný popis programu.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Returns:</term>
+ <listitem>
+ <para>Specifikuje, jakou hodnotu či více hodnot program vrací. (volitelné)</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Příklad dokumentace k programu.</title>
+ <example><title>Komentářový blok pro program</title>
+ <programlisting>
+/**
+ * PROGRAM:test-program
+ * @short_description: Testovací program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: nastaví arg1 do *arg*
+ * @--arg2 *arg*: nastaví arg2 do *arg*
+ * @-v, --version: Vypíše verzi programu
+ * @-h, --help: Vypíše nápovědu k programu
+ *
+ * Úplný popis programu.
+ *
+ * Returns: Vrací nulu při úspěchu, nenulovou hodnotu při selhání.
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+</programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
+ <sect1 id="documenting_docbook">
+ <title>Užitečné značky DocBook</title>
+
+ <para>Zde jsou některé značky DocBook, které mají pro dokumentaci kódu největší význam.</para>
+
+ <para>Odkaz na jiný oddíl v dokumentaci GTK: <informalexample>
+ <programlisting>
+<link linkend="glib-Hash-Tables">Hašovací tabulky</link>
+</programlisting>
+ </informalexample> Odkazem je id SGML/XML v první položce stránky, na kterou chcete odkazovat. Pro většinu stránek je to v současnosti část („gtk“, „gdk“, „glib“) a potom název stránky („Hašovací tabulka“). Pro ovládací prvky je to název třídy. Mezery a podtržítka se převedou na „-“, aby to vyhovovalo SGML/XML.</para>
+
+ <para>Odkaz na externí funkci, například standardní funkci C: <informalexample>
+ <programlisting>
+<function>…</function>
+</programlisting>
+ </informalexample></para>
+
+ <para>Vložení ukázky kódu: <informalexample>
+ <programlisting>
+<example>
+ <title>Používání GHashTable.</title>
+ <programlisting>
+ …
+ </programlisting>
+</example>
+</programlisting>
+ </informalexample> nebo pro velmi krátké úseky kódu, které nepotřebují nadpisy, je případně možné i: <informalexample>
+ <programlisting>
+<informalexample>
+ <programlisting>
+ …
+ </programlisting>
+</informalexample>
+</programlisting>
+ </informalexample> V novějších verzích GTK-Doc je také podporované zkracování: |[ … ]|</para>
+
+ <para>Vložení seznamu s odrážkami: <informalexample>
+ <programlisting>
+<itemizedlist>
+ <listitem>
+ <para>
+ …
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ …
+ </para>
+ </listitem>
+</itemizedlist>
+</programlisting>
+ </informalexample></para>
+
+ <para>Vložení poznámky, která se objeví mimo text: <informalexample>
+ <programlisting>
+<note>
+ <para>
+ Ujistěte se, že data po použití uvolníte.
+ </para>
+</note>
+</programlisting>
+ </informalexample></para>
+
+ <para>Odkaz na typ: <informalexample>
+ <programlisting>
+<type>unsigned char</type>
+</programlisting>
+ </informalexample></para>
+
+ <para>Odkaz na externí strukturu (která není popsaná v dokumentaci GTK): <informalexample>
+ <programlisting>
+<structname>XFontStruct</structname>
+</programlisting>
+ </informalexample></para>
+
+ <para>Odkaz na pole struktury: <informalexample>
+ <programlisting>
+<structfield>len</structfield>
+</programlisting>
+ </informalexample></para>
+
+ <para>Pro odkaz na název třídy by se dal nejspíše použít: <informalexample>
+ <programlisting>
+<classname>GtkWidget</classname>
+</programlisting>
+ </informalexample> ale pravděpodobně místo toho použijete #GtkWidget (aby se automaticky vytvořil odkaz na stránku ovládacího prvku, viz <link linkend="documenting_syntax">zkratky</link>).</para>
+
+ <para>Zvýrazněný text: <informalexample>
+ <programlisting>
+<emphasis>Toto je důležité</emphasis>
+</programlisting>
+ </informalexample></para>
+
+ <para>Pro název souboru použijte: <informalexample>
+ <programlisting>
+<filename>/home/user/documents</filename>
+</programlisting>
+ </informalexample></para>
+
+ <para>Odkaz na použití klávesy: <informalexample>
+ <programlisting>
+<keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo>
+</programlisting>
+ </informalexample></para>
+
+ </sect1>
+ </chapter>
+
+ <chapter id="metafiles">
+ <title>Vyplňování dodatečných souborů</title>
+
+ <para>Mimo komentářů vložených ve zdrojovém kódu je zde ještě pár dodatečných souborů, které je potřeba udržovat:<filename><balíček>.types</filename>, <filename><balíček>-docs.xml</filename> (dříve .sgml) a <filename><balíček>-sections.txt</filename>.</para>
+
+ <sect1 id="metafiles_types">
+ <title>Úprava souboru s typy</title>
+
+ <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>
+ <programlisting>
+#include <gtk/gtk.h>
+
+gtk_accel_label_get_type
+gtk_adjustment_get_type
+gtk_alignment_get_type
+gtk_arrow_get_type
+</programlisting>
+ </example>
+ </para>
+
+ <para>Od GTK-Doc verze 1.8 vám tento seznam vygeneruje <application>gtkdoc-scan</application>. Stačí jen přidat „--rebuild-types“ do SCAN_OPTIONS v <filename>Makefile.am</filename>. Pokud tento přístup použijete, neměli byste soubor s typy šířit do správy verzí.</para>
+
+ </sect1>
+
+ <sect1 id="metafiles_master">
+ <title>Úprava hlavního dokumentu</title>
+
+ <para>GTK-Doc produkuje dokumentaci v SGML/XML standardu DocBook. Když se zpracovávají komentáře vložené ve zdrojovém kódu, generují nástroje GTK-Doc pro každou třídu nebo modul jednu stránku dokumentace jako samostatný soubor. Všechny jsou pak uvedené seřazené v hlavním dokumentu.</para>
+
+ <para>Jakmile pro vás GTK-Doc vytvoří šablonu hlavního dokumentu, při pozdějším spuštění již do ní nezasahuje. To znamená, že můžete dokumentaci bez omezení strukturovat. A to včetně seskupování stránek a přidávání doplňujících stránek. GTK-Doc má v současnosti testovací sadu, ve které je také hlavní dokument vytvořen znovu od začátku. Je dobré se čas od času do něj nahlédnout, jestli se v něm neobjevily nějaké nové věci.</para>
+
+ <tip>
+ <para>Nevytvářejte výukové dokumenty (tutorial) jako zvláštní dokumenty. Napište je jako zvláštní kapitolu. Výhodou přímého spojení výukového dokumentu k vaší knihovně s dokumentací API je snadné vytváření odkazů pro symboly. Zvyšuje se tím také šance, že výukový dokument bude reflektovat aktualizace v knihovně.</para>
+ </tip>
+
+ <para>Nyní se podívejme, které věci můžete v hlavním dokumentu měnit. Pro začátek je to pouze název. Je zde několik zástupných hodnot (text v hranatých závorkách), o které byste se měli postarat.</para>
+
+ <para>
+ <example><title>Hlavička hlavního dokumentu</title>
+ <programlisting>
+<bookinfo>
+ <title>Referenční příručka k NÁZEV_MODULU</title>
+ <releaseinfo>
+ pro NÁZEV_MODULU [VERSION]
+ Nejvnovější verzi tohoto dokumentu můžete najít on-line na
+ <ulink role="online-location" url="http://[SERVER]/NÁZEV_MODULU/index.html">http://[SERVER]/NÁZEV_MODULU/</ulink>.
+ </releaseinfo>
+</bookinfo>
+
+<chapter>
+ <title>[Insert title here]</title>
+</programlisting>
+ </example>
+ </para>
+
+ <para>Navíc se vytvoří pár volitelných prvků ve formě komentáře. Můžete si je projít a případně povolit.</para>
+
+ <para>
+ <example><title>Volitelná část hlavního dokumentu</title>
+ <programlisting><![CDATA[
+ <!-- enable this when you use gobject introspection annotations
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+ -->
+]]></programlisting>
+ </example>
+ </para>
+
+ <para>Nakonec musíte přidat nový oddíl, kdekoliv chcete. Nástroj <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> vás upozorní na nově vygenerované soubory XML, které zatím nejsou v dokumentaci zahrnuté.</para>
+
+ <para>
+ <example><title>Vkládání generovaných oddílů</title>
+ <programlisting>
+ <chapter>
+ <title>moje knihovna</title>
+ <xi:include href="xml/object.xml"/>
+ …
+</programlisting>
+ </example>
+ </para>
+
+ </sect1>
+
+ <sect1 id="metafiles_sections">
+ <title>Úprava souboru oddílů</title>
+
+ <para>Soubor oddílů se používá k organizování výstupu dokumentace z GTK-Doc. Zde se určuje, který symbol náleží ke kterému modulu nebo třídě, a řídí se viditelnost (jestli je veřejný nebo soukromý).</para>
+
+ <para>Soubor oddílů je prostý textový soubor, ve kterém jsou oddíly oddělené značkami. Prázdné řádky se ignorují a s řádky začínajícími „#“ se zachází jako s komentářovými řádky.</para>
+
+ <note>
+ <para>Přestože díky značkám vypadá soubor podobně jako XML, není tomu tak. Neuzavírejte prosím značky jako je <SUBSECTION>.</para>
+ </note>
+
+ <para>
+ <example><title>Vkládání generovaných oddílů</title>
+ <programlisting>
+<INCLUDE>libmeep/meep.h</INCLUDE>
+
+<SECTION>
+<FILE>meepapp</FILE>
+<TITLE>MeepApp</TITLE>
+MeepApp
+<SUBSECTION Standard>
+MEEP_APP
+...
+MeepAppClass
+meep_app_get_type
+</SECTION>
+</programlisting>
+ </example>
+ </para>
+
+ <para>Značka <FILE> … </FILE> se používá k určení názvu souboru bez přípony. Například použití „<FILE>gnome-config</FILE>“ bude mít v deklaracích oddílu za následek výstup do souboru šablony <filename>tmpl/gnome-config.sgml</filename>, který bude převeden do souboru <filename>sgml/gnome-config.sgml</filename> ve formátu DocBook SGML nebo do souboru <filename>xml/gnome-config.xml</filename> ve formátu DocBook XML. (Název souboru HTML vychází z názvu modulu a názvu oddílu, případně pro GObject z názvu třídy GObject převedeného na malá písmena.)</para>
+
+ <para>Značka <TITLE> … </TITLE> se používá k určení názvu oddílu. To je použitelné pouze dříve, než je poprvé vytvořena šablona (pokud se používá), protože název nastavený v šabloně tento název přepíše. Navíc je považována za zastaralou v případě, že se používá komentář SECTION ve zdrojovém kódu.</para>
+
+ <para>Můžete také seskupovat položky v oddílu pomocí značky <SUBSECTION>. V současnosti způsobí prázdný řádek mezi pododdíly v souhrnné části. Můžete také použít <SUBSECTION Standard> pro standardní deklarace GObject (například funkce jako je g_object_get_type, makra jako G_OBJECT(), G_IS_OBJECT() atd.). V současnosti jsou tyto v dokumentaci vynechané. Můžete také použít <SUBSECTION Private> pro privátní deklarace, které ve výsledku nebudou (jedná se o ruční způsob, jak zabránit varovným hlášením o nepoužitých deklaracích). Pokud vaše knihovna obsahuje privátní typy, u kterých nechcete, aby se objevily v hierarchii objektů a v seznamu implementovaných nebo vyžadovaných rozhraní, přidejte je do pododdílu Private. Jestli umístit struktury jako GObject a GObjectClass do veřejné nebo standardní části záleží na tom, jestli mají veřejné položky (proměnné, virtuální metody).</para>
+
+ <para>Můžete také použít <INCLUDE> ... </INCLUDE> k určení #include souborů, které jsou zobrazené v souhrnné části. Obsahuje čárkami oddělený seznam jednotlivých #include souborů, bez lomených závorek. Když je nastavíte mimo kterýkoliv oddíl, budou fungovat pro všechny oddíly až do konce souboru. Když je nastavíte v konkrétním oddílu, použijí se jen pro něj.</para>
+
+ </sect1>
+
+ </chapter>
+
+ <chapter id="reports">
+ <title>Ovlivnění výsledku</title>
+
+ <para>Spuštění GTK-Doc vygeneruje ve složkách pro dokumentaci soubory s výstupními sestavami. Generované soubory jsou nazvané: <filename><balíček>-undocumented.txt</filename>, <filename><balíček>-undeclared.txt</filename> a <filename><balíček>-unused.txt</filename>. Všechno to jsou prosté textové soubory, které si lze jednoduše prohlížet a zpracovávat je.</para>
+
+ <para>Soubor <filename><balíček>-undocumented.txt</filename> začíná souhrnnými údaji o dokumentaci. Následují dva oddíly oddělené prázdnými řádky. První oddíl je seznam nezdokumentovaných nebo neúplných symbolů. Druhý oddíl je to stejné, ale pro dokumentace oddílů. Neúplné položky jsou takové, které mají dokumentaci, ale u kterých byl například přidán nový parametr.</para>
+
+ <para>Soubor <filename><balíček>-undeclared.txt</filename> uvádí symboly, které jsou zadané v <filename><balíček>-section.txt</filename>, ale nebyly nalezené ve zdrojových kódech. Ověřte, jestli nebyly odstraněny, nebo v nich není překlep.</para>
+
+ <para>Soubor <filename><balíček>-unused.txt</filename> uvádí názvy symbolů, které GTK-Doc při procházení dokumentace nalezl, ale neví, kam je zařadit. To znamená, že tyto symboly nejsou zatím zařazené v souboru <filename><balíček>-section.txt</filename>.</para>
+
+ <tip>
+ <para>Povolte nebo přidejte řádek <option>TESTS=($GTKDOC_CHECK)</option> v Makefile.am. Pokud máte nainstalované GTK-Doc ve verzi minimálně 1.9, bude se díky tomu při spuštění <command>make check</command> provádět kontrola správnosti údajů.</para>
+ </tip>
+
+ <para>Můžete se také podívat do souborů vytvořených skenerem zdrojového kódu: <filename><package>-decl-list.txt</filename> a <filename><package>-decl.txt</filename>. První můžete porovnat se souborem s oddíly, pokud je ručně spravován. Ve druhém jsou uvedené všechny deklarace z hlavičkových souborů. Pokud v dokumentaci schází některý symbol, můžete zkontrolovat, jestli se vyskytuje v tomto souboru.</para>
+
+ <para>Pokud je základem projektu GObject, můžete se také podívat do souborů vytvořených skenerem objektů: <filename><package>.args.txt</filename>, <filename><package>.hierarchy.txt</filename>, <filename><package>.interfaces.txt</filename>, <filename><package>.prerequisites.txt</filename> a <filename><package>.signals.txt</filename>. Jestliže v kterémkoliv z nich jsou chybějící symboly, můžete spuštěním <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command> požádat GTK-Doc, aby přechodně zachovat soubor pro pozdější analýzu.</para>
+ </chapter>
+
+ <chapter id="modernizing">
+ <title>Modernizace dokumentu</title>
+
+ <para>GTK-Doc existuje již nějakou dobu. V této části je uveden seznam nových funkcí spolu s číslem verze, od které je tato funkčnost k dispozici.</para>
+
+ <sect1 id="modernizing-gtk-doc-1-9">
+ <title>GTK-Doc 1.9</title>
+
+ <para>Když používáte XML namísto SGML, můžete ve skutečnosti pojmenovat hlavní dokument <filename><package>-docs.xml</filename>.</para>
+
+ <para>Tato verze podporuje <option>SCAN_OPTIONS=--rebuild-sections</option> v <filename>Makefile.am</filename>. Když je tato volba zapnutá, je <filename><package>-sections.txt</filename> generován automaticky a můžete jej odstranit ze správy verzí. To funguje hezky je u projektů, které mají pravidelnou strukturu (například jednotlivé páry souboru .c a .h vytvoří nový oddíl). Pokud máte projekt takto pečlivě organizovaný, vystačí si aktualizace ručně spravovaného souboru s oddíly s prostým spuštěním <code>meld <package>-decl-list.txt <package>-sections.txt</code>.</para>
+
+ <para>
+ 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.
+ </para>
+ </sect1>
+
+ <sect1 id="modernizing-gtk-doc-1-10">
+ <title>GTK-Doc 1.10</title>
+
+ <para>Tato verze podporuje <option>SCAN_OPTIONS=--rebuild-types</option> v <filename>Makefile.am</filename>. Když je tato volba zapnutá, je <filename><package>.types</filename> generován automaticky a můžete jej odstranit ze správy verzí. Jestliže tuto funkci využíváte, je důležité nastavit také <varname>IGNORE_HFILES</varname> v <filename>Makefile.am</filename> pro kód, který je sestavován podmíněně.</para>
+ </sect1>
+
+ <sect1 id="modernizing-gtk-doc-1-16">
+ <title>GTK-Doc 1.16</title>
+
+ <para>Součástí této verze je nový nástroj s názvem gtkdoc-check. Jeho spuštěním se provede kontrola správnosti vašeho dokumentu. Povolit jej můžete přidáním těchto řádků na konec souboru <filename>Makefile.am</filename>. <example><title>Povolení gtkdoc-check</title>
+ <programlisting>
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = \
+ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
+ SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
+TESTS = $(GTKDOC_CHECK)
+endif
+</programlisting>
+ </example></para>
+ </sect1>
+
+ <sect1 id="modernizing-gtk-doc-1-20">
+ <title>GTK-Doc 1.20</title>
+
+ <para>Verze 1.18 přinesla počáteční podporu pro Markdown. Jeho použití v dokumentačních komentářích je méně rušivé, než zápis XML z DocBook. Tato verze jeho podporu značně vylepšuje a přidává mnohem více stylů. Více podrobností je uvedeno v oddílu, který vysvětluje <link linkend="documenting_syntax">syntax komentářů</link>.</para>
+ </sect1>
+
+ <sect1 id="modernizing-gtk-doc-1-25">
+ <title>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
+ 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">
+ %gtkdocentities;
+]>
+<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>
+
+ <chapter id="documenting-others">
+ <title>Dokumentování ostatních rozhraní</title>
+
+ <para>Doposud jsme pomocí GTK-Doc dokumentovali API kódu. Následující oddíl obsahuje doporučení, jak se dají nástroje použít také k dokumentování dalších rozhraní.</para>
+
+ <sect1 id="commandline-interfaces">
+ <title>Přepínače příkazového řádku a manuálové stránky</title>
+
+ <para>Protože je stejně možné generovat manuálové stránky pro referenční položky DocBook, zní jako dobrý nápad použít to pro tento účel. Tímto způsobem se rozhraní stane součástí referenční příručky a získáte tak bez námahy manuálovou stránku.</para>
+
+ <sect2 id="commandline-interfaces-file">
+ <title>Dokumentování nástrojů</title>
+
+ <para>Vytvořte jeden soubor s referenční příručkou pro každý z nástrojů. V <link linkend="settingup_docfiles">našem příkladu</link> by se měl nazývat <filename>meep/docs/reference/meeper/meep.xml</filename>. Na značky XML, který by se měly použít, se podívejte do nějakého ukázkového vygenerovaného souboru v podsložce XML, například v glib.</para>
+ </sect2>
+
+ <sect2 id="commandline-interfaces-configure">
+ <title>Přidání doplňkových kontrol do configure</title>
+
+ <para>
+ <example><title>Dodatečné kontroly nastavení</title>
+ <programlisting>
+AC_ARG_ENABLE(man,
+ [AC_HELP_STRING([--enable-man],
+ [regenerate man pages from Docbook [default=no]])],enable_man=yes,
+ enable_man=no)
+
+AC_PATH_PROG([XSLTPROC], [xsltproc])
+AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)
+</programlisting>
+ </example>
+ </para>
+ </sect2>
+
+ <sect2 id="commandline-interfaces-make">
+ <title>Přidání doplňkových pravidel do Makefile</title>
+
+ <para>
+ <example><title>Dodatečné kontroly nastavení</title>
+ <programlisting>
+man_MANS = \
+ meeper.1
+
+if ENABLE_GTK_DOC
+if ENABLE_MAN
+
+%.1 : %.xml
+ @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
+endif
+endif
+
+BUILT_EXTRA_DIST = $(man_MANS)
+EXTRA_DIST += meep.xml
+</programlisting>
+ </example>
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="dbus-interfaces">
+ <title>Rozhraní D-Bus</title>
+
+ <para>(OPRAVIT: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)</para>
+ </sect1>
+
+ </chapter>
+
+ <chapter id="faq">
+ <title>Často kladené dotazy</title>
+
+ <segmentedlist>
+ <?dbhtml list-presentation="list"?>
+ <segtitle>Dotaz</segtitle>
+ <segtitle>Odpověď</segtitle>
+ <seglistitem>
+ <seg>Schází hierarchie třídy.</seg>
+ <seg>Do souboru <filename><balíček>.types</filename> nebyla vložena funkce objektu <function>xxx_get_type()</function>.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Stále schází hierarchie třídy.</seg>
+ <seg>Chybějící nebo nesprávné pojmenování souboru <filename><balíček>-sections.txt</filename> (viz <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">vysvětlení</ulink>).</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Do háje, pořád nemám hierarchii třídy.</seg>
+ <seg>Je název objektu (název struktury instance, například <type>GtkWidget</type>) součástí normálního oddílu? (Nedávejte je do pododdílu Standard nebo Private).</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Chybí rejstřík symbolů.</seg>
+ <seg>Obsahuje <filename><package>-docs.{xml,sgml}</filename> rejstřík, který vloží pomocí xi:include vygenerovaný rejstřík?</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Symbol nemá odkaz do svého oddílu dokumentace.</seg>
+ <seg>Používá dokumentační komentář správnou značku (přidané znaky #,% nebo ())? Podívejte se na varování gtkdoc-fixxref o nevyřešených křížových odkazech.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Nová třída se neobjevila v dokumentaci.</seg>
+ <seg>Je nový balíček vložený pomocí xi:include z <filename><package>-docs.{xml,sgml}</filename>.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Nový symbol se neobjevil v dokumentaci.</seg>
+ <seg>Je dokumentační komentář správně naformátovaný? Zkontrolujte překlepy na začátku komentáře. Podívejte se po varováních gtkdoc-fixxref o nevyřešených křížových odkazech. Zkontrolujte, jestli je symbol správně uvedený v <filename><package>-sections.txt</filename> ve veřejném pododdíle.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>V hierarchii třídy schází typ.</seg>
+ <seg>Jestliže je typ uvedený v <filename><package>.hierarchy</filename>, ale není v <filename>xml/tree_index.sgml</filename>, tak raději dvakrát zkontrolujte, jestli je typ správně uvedený v <filename><package>-sections.txt</filename>. Jestliže instance typu (například <type>GtkWidget</type>) není uvedená, nebo je nedopatřením označení jako privátní, nebude zobrazena.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Vytvořily se mi odkazy na složku s dokumentací pro všechny anotace k GObject</seg>
+ <seg>Zkontrolujte, že <filename>xml/annotation-glossary.xml</filename> je vložené pomocí xi:include z <filename><package>-docs.{xml,sgml}</filename>.</seg>
+ </seglistitem>
+
+ <!-- gtk-doc warnings: -->
+ <seglistitem>
+ <seg>Parametr je v komentářovém bloku zdrojového kódu popsaný, ale neexistuje.</seg>
+ <seg>Zkontrolujte, za nemá prototyp v hlavičkovém souboru jiné názvy parametrů, než ve zdrojovém kódu.</seg>
+ </seglistitem>
+
+ <!-- docbook warnings: -->
+ <seglistitem>
+ <seg>Více „ID“ pro tentýž cíl odkazu: XYZ</seg>
+ <seg>Symbol XYZ se v souboru <filename><package>-sections.txt</filename> objevuje dvakrát.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Element typename ve jmenném prostoru '' je uvedený v rodiči, ale neodpovídá mu žádná šablona.</seg>
+ <seg/>
+ </seglistitem>
+ </segmentedlist>
+ </chapter>
+
+ <chapter id="contrib">
+ <title>Nástroje související s GTK-Doc</title>
+
+ <para>GtkDocPlugin – zásuvný modul pro integraci <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">GTK-Doc do systému Track</ulink>, který přidává dokumentaci k API na sledovací web a integruje ji do vyhledávání.</para>
+ <para>Gtkdoc-depscan – nástroj (součást GTK-Doc), který kontroluje použité API vůči štítku since v API, aby určil minimální požadovanou verzi.</para>
+
+ </chapter>
+
+ <!-- ======== Appendix: FDL ================================== -->
+ <!--
+ The GNU Free Documentation License 1.1 in DocBook
+ Markup by Eric Baudais <baudais@okstate.edu>
+ Maintained by the GNOME Documentation Project
+ http://developer.gnome.org/projects/gdp
+ Version: 1.0.1
+ Last Modified: Nov 16, 2000
+-->
+
+<appendix id="fdl">
+ <appendixinfo>
+ <releaseinfo>Verze 1.1, březen 2000</releaseinfo>
+ <copyright><year>2000</year><holder>Free Software Foundation, Inc.</holder></copyright>
+ <legalnotice id="fdl-legalnotice">
+ <para><address>Free Software Foundation, Inc. <street>51 Franklin Street,
+ Suite 330</street>, <city>Boston</city>, <state>MA</state>
+ <postcode>02110-1301</postcode> <country>USA</country></address> Kdokoliv je oprávněn kopírovat a šířit doslovné kopie tohoto dokumentu s licencí, ale nesmí v něm provádět žádné změny.</para>
+ </legalnotice>
+ </appendixinfo>
+ <title>GNU Free Documentation License</title>
+
+ <sect1 id="fdl-preamble">
+ <title>0. PREAMBLE</title>
+ <para>
+ The purpose of this License is to make a manual, textbook, or
+ other written document <quote>free</quote> in the sense of
+ freedom: to assure everyone the effective freedom to copy and
+ redistribute it, with or without modifying it, either
+ commercially or noncommercially. Secondarily, this License
+ preserves for the author and publisher a way to get credit for
+ their work, while not being considered responsible for
+ modifications made by others.
+ </para>
+
+ <para>
+ This License is a kind of <quote>copyleft</quote>, which means
+ that derivative works of the document must themselves be free in
+ the same sense. It complements the GNU General Public License,
+ which is a copyleft license designed for free software.
+ </para>
+
+ <para>
+ We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a
+ free program should come with manuals providing the same
+ freedoms that the software does. But this License is not limited
+ to software manuals; it can be used for any textual work,
+ regardless of subject matter or whether it is published as a
+ printed book. We recommend this License principally for works
+ whose purpose is instruction or reference.
+ </para>
+ </sect1>
+ <sect1 id="fdl-section1">
+ <title>1. APPLICABILITY AND DEFINITIONS</title>
+ <para id="fdl-document">
+ This License applies to any manual or other work that contains a
+ notice placed by the copyright holder saying it can be
+ distributed under the terms of this License. The
+ <quote>Document</quote>, below, refers to any such manual or
+ work. Any member of the public is a licensee, and is addressed
+ as <quote>you</quote>.
+ </para>
+
+ <para id="fdl-modified">
+ A <quote>Modified Version</quote> of the Document means any work
+ containing the Document or a portion of it, either copied
+ verbatim, or with modifications and/or translated into another
+ language.
+ </para>
+
+ <para id="fdl-secondary">
+ A <quote>Secondary Section</quote> is a named appendix or a
+ front-matter section of the <link linkend="fdl-document">Document</link> that deals exclusively
+ with the relationship of the publishers or authors of the
+ Document to the Document's overall subject (or to related
+ matters) and contains nothing that could fall directly within
+ that overall subject. (For example, if the Document is in part a
+ textbook of mathematics, a Secondary Section may not explain any
+ mathematics.) The relationship could be a matter of historical
+ connection with the subject or with related matters, or of
+ legal, commercial, philosophical, ethical or political position
+ regarding them.
+ </para>
+
+ <para id="fdl-invariant">
+ The <quote>Invariant Sections</quote> are certain <link linkend="fdl-secondary"> Secondary Sections</link> whose titles
+ are designated, as being those of Invariant Sections, in the
+ notice that says that the <link linkend="fdl-document">Document</link> is released under this
+ License.
+ </para>
+
+ <para id="fdl-cover-texts">
+ The <quote>Cover Texts</quote> are certain short passages of
+ text that are listed, as Front-Cover Texts or Back-Cover Texts,
+ in the notice that says that the <link linkend="fdl-document">Document</link> is released under this
+ License.
+ </para>
+
+ <para id="fdl-transparent">
+ A <quote>Transparent</quote> copy of the <link linkend="fdl-document"> Document</link> means a machine-readable
+ copy, represented in a format whose specification is available
+ to the general public, whose contents can be viewed and edited
+ directly and straightforwardly with generic text editors or (for
+ images composed of pixels) generic paint programs or (for
+ drawings) some widely available drawing editor, and that is
+ suitable for input to text formatters or for automatic
+ translation to a variety of formats suitable for input to text
+ formatters. A copy made in an otherwise Transparent file format
+ whose markup has been designed to thwart or discourage
+ subsequent modification by readers is not Transparent. A copy
+ that is not <quote>Transparent</quote> is called
+ <quote>Opaque</quote>.
+ </para>
+
+ <para>
+ Examples of suitable formats for Transparent copies include
+ plain ASCII without markup, Texinfo input format, LaTeX input
+ format, SGML or XML using a publicly available DTD, and
+ standard-conforming simple HTML designed for human
+ modification. Opaque formats include PostScript, PDF,
+ proprietary formats that can be read and edited only by
+ proprietary word processors, SGML or XML for which the DTD
+ and/or processing tools are not generally available, and the
+ machine-generated HTML produced by some word processors for
+ output purposes only.
+ </para>
+
+ <para id="fdl-title-page">
+ The <quote>Title Page</quote> means, for a printed book, the
+ title page itself, plus such following pages as are needed to
+ hold, legibly, the material this License requires to appear in
+ the title page. For works in formats which do not have any title
+ page as such, <quote>Title Page</quote> means the text near the
+ most prominent appearance of the work's title, preceding the
+ beginning of the body of the text.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section2">
+ <title>2. VERBATIM COPYING</title>
+ <para>
+ You may copy and distribute the <link linkend="fdl-document">Document</link> in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License
+ applies to the Document are reproduced in all copies, and that
+ you add no other conditions whatsoever to those of this
+ License. You may not use technical measures to obstruct or
+ control the reading or further copying of the copies you make or
+ distribute. However, you may accept compensation in exchange for
+ copies. If you distribute a large enough number of copies you
+ must also follow the conditions in <link linkend="fdl-section3">section 3</link>.
+ </para>
+
+ <para>
+ You may also lend copies, under the same conditions stated
+ above, and you may publicly display copies.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section3">
+ <title>3. COPYING IN QUANTITY</title>
+ <para>
+ If you publish printed copies of the <link linkend="fdl-document">Document</link> numbering more than 100,
+ and the Document's license notice requires <link linkend="fdl-cover-texts">Cover Texts</link>, you must enclose
+ the copies in covers that carry, clearly and legibly, all these
+ Cover Texts: Front-Cover Texts on the front cover, and
+ Back-Cover Texts on the back cover. Both covers must also
+ clearly and legibly identify you as the publisher of these
+ copies. The front cover must present the full title with all
+ words of the title equally prominent and visible. You may add
+ other material on the covers in addition. Copying with changes
+ limited to the covers, as long as they preserve the title of the
+ <link linkend="fdl-document">Document</link> and satisfy these
+ conditions, can be treated as verbatim copying in other
+ respects.
+ </para>
+
+ <para>
+ 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 actual cover, and continue the rest onto
+ adjacent pages.
+ </para>
+
+ <para>
+ If you publish or distribute <link linkend="fdl-transparent">Opaque</link> copies of the <link linkend="fdl-document">Document</link> numbering more than 100,
+ you must either include a machine-readable <link linkend="fdl-transparent">Transparent</link> copy along with
+ each Opaque copy, or state in or with each Opaque copy a
+ publicly-accessible computer-network location containing a
+ complete Transparent copy of the Document, free of added
+ material, which the general network-using public has access to
+ download anonymously at no charge using public-standard network
+ protocols. If you use the latter option, you must take
+ reasonably prudent steps, when you begin distribution of Opaque
+ copies in quantity, to ensure that this Transparent copy will
+ remain thus accessible at the stated location until at least one
+ year after the last time you distribute an Opaque copy (directly
+ or through your agents or retailers) of that edition to the
+ public.
+ </para>
+
+ <para>
+ It is requested, but not required, that you contact the authors
+ of the <link linkend="fdl-document">Document</link> well before
+ redistributing any large number of copies, to give them a chance
+ to provide you with an updated version of the Document.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section4">
+ <title>4. MODIFICATIONS</title>
+ <para>
+ You may copy and distribute a <link linkend="fdl-modified">Modified Version</link> of the <link linkend="fdl-document">Document</link> under the conditions of
+ sections <link linkend="fdl-section2">2</link> and <link linkend="fdl-section3">3</link> above, provided that you release
+ the Modified Version under precisely this License, with the
+ Modified Version filling the role of the Document, thus
+ licensing distribution and modification of the Modified Version
+ to whoever possesses a copy of it. In addition, you must do
+ these things in the Modified Version:
+ </para>
+
+ <itemizedlist mark="opencircle">
+ <listitem>
+ <formalpara>
+ <title>A</title>
+ <para>
+ Use in the <link linkend="fdl-title-page">Title
+ Page</link> (and on the covers, if any) a title distinct
+ from that of the <link linkend="fdl-document">Document</link>, and from those of
+ previous versions (which should, if there were any, be
+ listed in the History section of the Document). You may
+ use the same title as a previous version if the original
+ publisher of that version gives permission.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>B</title>
+ <para>
+ List on the <link linkend="fdl-title-page">Title
+ Page</link>, as authors, one or more persons or entities
+ responsible for authorship of the modifications in the
+ <link linkend="fdl-modified">Modified Version</link>,
+ together with at least five of the principal authors of
+ the <link linkend="fdl-document">Document</link> (all of
+ its principal authors, if it has less than five).
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>C</title>
+ <para>
+ State on the <link linkend="fdl-title-page">Title
+ Page</link> the name of the publisher of the <link linkend="fdl-modified">Modified Version</link>, as the
+ publisher.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>D</title>
+ <para>
+ Preserve all the copyright notices of the <link linkend="fdl-document">Document</link>.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>E</title>
+ <para>
+ Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>F</title>
+ <para>
+ Include, immediately after the copyright notices, a
+ license notice giving the public permission to use the
+ <link linkend="fdl-modified">Modified Version</link> under
+ the terms of this License, in the form shown in the
+ Addendum below.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>G</title>
+ <para>
+ Preserve in that license notice the full lists of <link linkend="fdl-invariant"> Invariant Sections</link> and
+ required <link linkend="fdl-cover-texts">Cover
+ Texts</link> given in the <link linkend="fdl-document">Document's</link> license notice.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>H</title>
+ <para>
+ Include an unaltered copy of this License.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>I</title>
+ <para>
+ Preserve the section entitled <quote>History</quote>, and
+ its title, and add to it an item stating at least the
+ title, year, new authors, and publisher of the <link linkend="fdl-modified">Modified Version</link> as given on
+ the <link linkend="fdl-title-page">Title Page</link>. If
+ there is no section entitled <quote>History</quote> in the
+ <link linkend="fdl-document">Document</link>, create one
+ stating the title, year, authors, and publisher of the
+ Document as given on its Title Page, then add an item
+ describing the Modified Version as stated in the previous
+ sentence.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>J</title>
+ <para>
+ Preserve the network location, if any, given in the <link linkend="fdl-document">Document</link> for public access
+ to a <link linkend="fdl-transparent">Transparent</link>
+ copy of the Document, and likewise the network locations
+ given in the Document for previous versions it was based
+ on. These may be placed in the <quote>History</quote>
+ section. You may omit a network location for a work that
+ was published at least four years before the Document
+ itself, or if the original publisher of the version it
+ refers to gives permission.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>K</title>
+ <para>
+ In any section entitled <quote>Acknowledgements</quote> or
+ <quote>Dedications</quote>, preserve the section's title,
+ and preserve in the section all the substance and tone of
+ each of the contributor acknowledgements and/or
+ dedications given therein.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>L</title>
+ <para>
+ Preserve all the <link linkend="fdl-invariant">Invariant
+ Sections</link> of the <link linkend="fdl-document">Document</link>, unaltered in their
+ text and in their titles. Section numbers or the
+ equivalent are not considered part of the section titles.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>M</title>
+ <para>
+ Delete any section entitled
+ <quote>Endorsements</quote>. Such a section may not be
+ included in the <link linkend="fdl-modified">Modified
+ Version</link>.
+ </para>
+ </formalpara>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>N</title>
+ <para>
+ Do not retitle any existing section as
+ <quote>Endorsements</quote> or to conflict in title with
+ any <link linkend="fdl-invariant">Invariant
+ Section</link>.
+ </para>
+ </formalpara>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ If the <link linkend="fdl-modified">Modified Version</link>
+ includes new front-matter sections or appendices that qualify as
+ <link linkend="fdl-secondary">Secondary Sections</link> and
+ contain no material copied from the Document, you may at your
+ option designate some or all of these sections as invariant. To
+ do this, add their titles to the list of <link linkend="fdl-invariant">Invariant Sections</link> in the
+ Modified Version's license notice. These titles must be
+ distinct from any other section titles.
+ </para>
+
+ <para>
+ You may add a section entitled <quote>Endorsements</quote>,
+ provided it contains nothing but endorsements of your <link linkend="fdl-modified">Modified Version</link> by various
+ parties--for example, statements of peer review or that the text
+ has been approved by an organization as the authoritative
+ definition of a standard.
+ </para>
+
+ <para>
+ You may add a passage of up to five words as a <link linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage
+ of up to 25 words as a <link linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of
+ the list of <link linkend="fdl-cover-texts">Cover Texts</link>
+ in the <link linkend="fdl-modified">Modified Version</link>.
+ Only one passage of Front-Cover Text and one of Back-Cover Text
+ may be added by (or through arrangements made by) any one
+ entity. If the <link linkend="fdl-document">Document</link>
+ already includes a cover text for the same cover, previously
+ added by you or by arrangement made by the same entity you are
+ acting on behalf of, you may not add another; but you may
+ replace the old one, on explicit permission from the previous
+ publisher that added the old one.
+ </para>
+
+ <para>
+ The author(s) and publisher(s) of the <link linkend="fdl-document">Document</link> do not by this License
+ give permission to use their names for publicity for or to
+ assert or imply endorsement of any <link linkend="fdl-modified">Modified Version </link>.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section5">
+ <title>5. COMBINING DOCUMENTS</title>
+ <para>
+ You may combine the <link linkend="fdl-document">Document</link>
+ with other documents released under this License, under the
+ terms defined in <link linkend="fdl-section4">section 4</link>
+ above for modified versions, provided that you include in the
+ combination all of the <link linkend="fdl-invariant">Invariant
+ Sections</link> of all of the original documents, unmodified,
+ and list them all as Invariant Sections of your combined work in
+ its license notice.
+ </para>
+
+ <para>
+ The combined work need only contain one copy of this License,
+ and multiple identical <link linkend="fdl-invariant">Invariant
+ Sections</link> may be replaced with a single copy. If there are
+ multiple Invariant Sections with the same name but different
+ contents, make the title of each such section unique by adding
+ at the end of it, in parentheses, the name of the original
+ author or publisher of that section if known, or else a unique
+ number. Make the same adjustment to the section titles in the
+ list of Invariant Sections in the license notice of the combined
+ work.
+ </para>
+
+ <para>
+ In the combination, you must combine any sections entitled
+ <quote>History</quote> in the various original documents,
+ forming one section entitled <quote>History</quote>; likewise
+ combine any sections entitled <quote>Acknowledgements</quote>,
+ and any sections entitled <quote>Dedications</quote>. You must
+ delete all sections entitled <quote>Endorsements.</quote>
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section6">
+ <title>6. COLLECTIONS OF DOCUMENTS</title>
+ <para>
+ You may make a collection consisting of the <link linkend="fdl-document">Document</link> and other documents
+ released under this License, and replace the individual copies
+ of this License in the various documents with a single copy that
+ is included in the collection, provided that you follow the
+ rules of this License for verbatim copying of each of the
+ documents in all other respects.
+ </para>
+
+ <para>
+ 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.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section7">
+ <title>7. AGGREGATION WITH INDEPENDENT WORKS</title>
+ <para>
+ A compilation of the <link linkend="fdl-document">Document</link> or its derivatives with
+ other separate and independent documents or works, in or on a
+ volume of a storage or distribution medium, does not as a whole
+ count as a <link linkend="fdl-modified">Modified Version</link>
+ of the Document, provided no compilation copyright is claimed
+ for the compilation. Such a compilation is called an
+ <quote>aggregate</quote>, and this License does not apply to the
+ other self-contained works thus compiled with the Document , on
+ account of their being thus compiled, if they are not themselves
+ derivative works of the Document. If the <link linkend="fdl-cover-texts">Cover Text</link> requirement of <link linkend="fdl-section3">section 3</link> is applicable to these
+ copies of the Document, then if the Document is less than one
+ quarter of the entire aggregate, the Document's Cover Texts may
+ be placed on covers that surround only the Document within the
+ aggregate. Otherwise they must appear on covers around the whole
+ aggregate.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section8">
+ <title>8. TRANSLATION</title>
+ <para>
+ Translation is considered a kind of modification, so you may
+ distribute translations of the <link linkend="fdl-document">Document</link> under the terms of <link linkend="fdl-section4">section 4</link>. Replacing <link linkend="fdl-invariant"> Invariant Sections</link> with
+ translations requires special permission from their copyright
+ holders, but you may include translations of some or all
+ Invariant Sections in addition to the original versions of these
+ Invariant Sections. You may include a translation of this
+ License provided that you also include the original English
+ version of this License. In case of a disagreement between the
+ translation and the original English version of this License,
+ the original English version will prevail.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section9">
+ <title>9. TERMINATION</title>
+ <para>
+ You may not copy, modify, sublicense, or distribute the <link linkend="fdl-document">Document</link> except as expressly
+ provided for under this License. Any other attempt to copy,
+ modify, sublicense or distribute the Document is void, and will
+ automatically terminate your rights under this License. However,
+ parties who have received copies, or rights, from you under this
+ License will not have their licenses terminated so long as such
+ parties remain in full compliance.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-section10">
+ <title>10. FUTURE REVISIONS OF THIS LICENSE</title>
+ <para>
+ The <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software
+ Foundation</ulink> may publish new, revised versions of the GNU
+ Free Documentation License from time to time. Such new versions
+ will be similar in spirit to the present version, but may differ
+ in detail to address new problems or concerns. See <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.
+ </para>
+
+ <para>
+ Each version of the License is given a distinguishing version
+ number. If the <link linkend="fdl-document">Document</link>
+ specifies that a particular numbered version of this License
+ <quote>or any later version</quote> applies to it, you have the
+ option of following the terms and conditions either of that
+ specified version or of any later version that has been
+ published (not as a draft) by the Free Software Foundation. If
+ the Document does not specify a version number of this License,
+ you may choose any version ever published (not as a draft) by
+ the Free Software Foundation.
+ </para>
+ </sect1>
+
+ <sect1 id="fdl-using">
+ <title>Addendum</title>
+ <para>
+ 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 just after the title page:
+ </para>
+
+ <blockquote>
+ <para>
+ Copyright YEAR YOUR NAME.
+ </para>
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation
+ License, Version 1.1 or any later version published by the
+ Free Software Foundation; with the <link linkend="fdl-invariant">Invariant Sections</link> being LIST
+ THEIR TITLES, with the <link linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST,
+ and with the <link linkend="fdl-cover-texts">Back-Cover
+ Texts</link> being LIST. A copy of the license is included in
+ the section entitled <quote>GNU Free Documentation
+ License</quote>.
+ </para>
+ </blockquote>
+
+ <para>
+ If you have no <link linkend="fdl-invariant">Invariant
+ Sections</link>, write <quote>with no Invariant Sections</quote>
+ instead of saying which ones are invariant. If you have no
+ <link linkend="fdl-cover-texts">Front-Cover Texts</link>, write
+ <quote>no Front-Cover Texts</quote> instead of
+ <quote>Front-Cover Texts being LIST</quote>; likewise for <link linkend="fdl-cover-texts">Back-Cover Texts</link>.
+ </para>
+
+ <para>
+ If your document contains nontrivial examples of program code,
+ we recommend releasing these examples in parallel under your
+ choice of free software license, such as the <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public
+ License</ulink>, to permit their use in free software.
+ </para>
+ </sect1>
+</appendix>
+
+
+
+
+
+
+
+
+</book>
# German translation of the gtk-doc manual.
-# Mario Blättermann <mario.blaettermann@gmail.com>, 2009, 2010, 2012, 2013.
+# Mario Blättermann <mario.blaettermann@gmail.com>, 2009-2010, 2012-2013, 2016.
# Wolfgang Stöggl <c72578@yahoo.de>, 2015.
+# Christian Kirbach <christian.kirbach@gmail.com>, 2013, 2015.
#
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc help master\n"
-"POT-Creation-Date: 2015-11-19 07:07+0000\n"
-"PO-Revision-Date: 2015-12-05 11:15+0100\n"
-"Last-Translator: Wolfgang Stoeggl <c72578@yahoo.de>\n"
+"POT-Creation-Date: 2017-03-21 20:30+0000\n"
+"PO-Revision-Date: 2017-03-28 10:36+0200\n"
+"Last-Translator: Christian Kirbach <christian.kirbach@gmail.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 1.8.6\n"
+"X-Generator: Poedit 1.8.12\n"
#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
msgctxt "_"
msgid "translator-credits"
msgstr ""
-"Mario Blättermann <mario.blaettermann@gmail.com>, 2009-2013\n"
-"Christian Kirbach <christian.kirbach@gmail.com>, 2013, 2015"
+"Mario Blättermann <mario.blaettermann@gmail.com>, 2009-2013, 2016\n"
+"Christian Kirbach <christian.kirbach@gmail.com>, 2013, 2015, 2016, 2017"
#. (itstool) path: bookinfo/title
#: C/index.docbook:12
#. (itstool) path: revhistory/revision
#: C/index.docbook:83
msgid ""
-"<revnumber>1.2
4.1</revnumber> <date>30 May 2015</date> <authorinitials>ss</"
+"<revnumber>1.2
5.1</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>development version</revremark>"
msgstr ""
-"<revnumber>1.2
4.1</revnumber> <date>30. Mai 2015</date> <authorinitials>ss</"
+"<revnumber>1.2
5.1</revnumber> <date>21. März 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>Entwicklerversion</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
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. März 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>Fehlerbehebungen, Test-Cleanups</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
msgstr ""
"authorinitials> <revremark>Fehlerbehebungen</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
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:101
+#: C/index.docbook:107
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:107
+#: C/index.docbook:113
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:113
+#: C/index.docbook:119
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:119
+#: C/index.docbook:125
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:125
+#: C/index.docbook:131
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:131
+#: C/index.docbook:137
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:137
+#: C/index.docbook:143
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:143
+#: C/index.docbook:149
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:149
+#: C/index.docbook:155
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:155
+#: C/index.docbook:161
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:161
+#: C/index.docbook:167
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:167
+#: C/index.docbook:173
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:180
+#: C/index.docbook:186
msgid "Introduction"
msgstr "Einführung"
#. (itstool) path: chapter/para
-#: C/index.docbook:182
+#: C/index.docbook:188
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:188
+#: C/index.docbook:194
msgid "What is GTK-Doc?"
msgstr "Was ist GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:190
+#: C/index.docbook:196
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:198
+#: C/index.docbook:204
msgid "How Does GTK-Doc Work?"
msgstr "Wie funktioniert GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:200
+#: C/index.docbook:206
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:207
+#: C/index.docbook:213
msgid ""
"GTK-Doc consists of a number of perl scripts, each performing a different "
"step in the process."
"bestimmten Schritt in dem Prozess ausführt."
#. (itstool) path: sect1/para
-#: C/index.docbook:212
+#: C/index.docbook:218
msgid "There are 5 main steps in the process:"
msgstr "Dieser Vorgang umfasst fünf Hauptschritte:"
#. (itstool) path: listitem/para
-#: C/index.docbook:219
+#: C/index.docbook:225
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:229
+#: C/index.docbook:235
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:246
+#: C/index.docbook:252
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:252
+#: C/index.docbook:258
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:259
-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>Erstellen der »Vorlage«-Dateien.</guilabel> <application>gtkdoc-"
-"mktmpl</application> erstellt einige Dateien im Unterordner <filename class="
-"\"directory\">tmpl/</filename> mit Hilfe der Informationen aus dem ersten "
-"Schritt. (Bedenken Sie, dass dies wiederholt ausgeführt werden kann. Es wird "
-"versucht sicherzustellen, dass keine Dokumentation jemals verloren geht.)"
-
-#. (itstool) path: note/para
-#: C/index.docbook:268
-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 ""
-"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. 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."
-
-#. (itstool) path: listitem/para
-#: C/index.docbook:280
-#, 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."
+#: C/index.docbook:265
msgid ""
"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
"mkdb</application> turns the template files into XML files in the <filename "
"sources and introspection data."
msgstr ""
"<guilabel>Erstellen des SGML/XML und HTML/PDF.</guilabel> "
-"<application>gtkdoc-mkdb</application> wandelt die Vorlagen-Dateien in SGML- "
-"oder XML-Dateien in den Unterordner <filename class=\"directory\">sgml/</"
-"filename> oder <filename class=\"directory\">xml/</filename> um. Wenn der "
-"Quellcode Dokumentation über Funktionen mittels speziellen Kommentarblöcken "
-"enthält, so wird diese hier eingepflegt. Wenn keine tmpl-Dateien eingesetzt "
-"werden, so wird nur Dokumentation von den Quell- und introspection-Daten "
-"gelesen. Wir empfehlen Docbook XML zu verwenden."
+"<application>gtkdoc-mkdb</application> wandelt die Vorlagen-Dateien in XML-"
+"Dateien in den Unterordner <filename class=\"directory\">xml/</filename> um. "
+"Wenn der Quellcode Dokumentation über Funktionen mittels speziellen "
+"Kommentarblöcken enthält, so wird diese hier eingepflegt. Wenn keine tmpl-"
+"Dateien eingesetzt werden, so wird nur Dokumentation von den Quell- und "
+"introspection-Daten gelesen."
#. (itstool) path: listitem/para
-#: C/index.docbook:289
-#, 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>."
+#: C/index.docbook:274
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> konvertiert die SGML/XML-Dateien in "
-"HTML-Dateien im Unterordner <filename class=\"directory\">html/</filename>. "
-"Ebenso konvertiert <application>gtkdoc-mkpdf</application> die SGML/XML-"
-"Dateien in ein PDF-Dokument namens <filename><package>.pdf</filename>."
+"<application>gtkdoc-mkhtml</application> konvertiert die XML-Dateien in HTML-"
+"Dateien im Unterordner <filename class=\"directory\">html/</filename>. "
+"Ebenso konvertiert <application>gtkdoc-mkpdf</application> die XML-Dateien "
+"in ein PDF-Dokument namens <filename><package>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:295
-#, fuzzy
-#| 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."
+#: C/index.docbook:280
msgid ""
"Files in <filename class=\"directory\">xml/</filename> and <filename class="
"\"directory\">html/</filename> directories are always overwritten. One "
"should never edit them directly."
msgstr ""
-"Dateien in <filename class=\"directory\">sgml/</filename> oder <filename "
-"class=\"directory\">xml/</filename> und <filename class=\"directory\">html/</"
-"filename>-Ordnern werden immer überschrieben. Niemand sollte diese direkt "
-"bearbeiten."
+"Dateien in <filename class=\"directory\">xml/</filename> und <filename class="
+"\"directory\">html/</filename>-Ordnern werden immer überschrieben. Niemand "
+"sollte diese direkt bearbeiten."
#. (itstool) path: listitem/para
-#: C/index.docbook:303
+#: C/index.docbook:288
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:321
+#: C/index.docbook:306
msgid "Getting GTK-Doc"
msgstr "GTK-Doc bekommen"
#. (itstool) path: sect2/title
-#: C/index.docbook:324
+#: C/index.docbook:309
msgid "Requirements"
msgstr "Erfordernisse"
#. (itstool) path: sect2/para
-#: C/index.docbook:325
+#: C/index.docbook:310
msgid "<guilabel>Perl v5</guilabel> - the main scripts are in Perl."
msgstr ""
"<guilabel>Perl v5</guilabel> - Die Hauptskripte wurden in Perl geschrieben."
#. (itstool) path: sect2/para
-#: C/index.docbook:328
+#: C/index.docbook:313
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:332
+#: C/index.docbook:317
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:336
+#: C/index.docbook:321
msgid "<guilabel>Python</guilabel> - optional - for gtkdoc-depscan"
msgstr "<guilabel>Python</guilabel> - optional - für gtkdoc-depscan"
#. (itstool) path: sect2/para
-#: C/index.docbook:339
+#: C/index.docbook:324
msgid ""
"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
"examples"
msgstr ""
+"<guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> oder "
+"<guilabel>vim</guilabel> - optional - für Syntax-Hervorhebung von Beispielen"
#. (itstool) path: sect1/title
-#: C/index.docbook:347
+#: C/index.docbook:332
msgid "About GTK-Doc"
msgstr "Info zu GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:349 C/index.docbook:363
+#: C/index.docbook:334 C/index.docbook:348
msgid "(FIXME)"
msgstr "(FIXME)"
#. (itstool) path: sect1/para
-#: C/index.docbook:353
-#, fuzzy
-#| msgid ""
-#| "(History, authors, web pages, license, future plans, comparison with "
-#| "other similar systems.)"
+#: C/index.docbook:338
msgid ""
"(History, authors, web pages, mailing list, license, future plans, "
"comparison with other similar systems.)"
msgstr ""
-"(Geschichte, Autoren, Webseiten, Lizenz, Zukunftspläne, Vergleich mit "
-"ähnlichen Systemen)"
+"(Geschichte, Autoren, Webseiten, Mailingliste, Lizenz, Zukunftspläne, "
+"Vergleich mit ähnlichen Systemen)"
#. (itstool) path: sect1/title
-#: C/index.docbook:361
+#: C/index.docbook:346
msgid "About this Manual"
msgstr "Über dieses Handbuch"
#. (itstool) path: sect1/para
-#: C/index.docbook:367
+#: C/index.docbook:352
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:376
+#: C/index.docbook:361
msgid "Setting up your project"
msgstr "Einrichten Ihres Projekts"
#. (itstool) path: chapter/para
-#: C/index.docbook:378
+#: C/index.docbook:363
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:389
+#: C/index.docbook:374
msgid "Setting up a skeleton documentation"
msgstr "Einrichten des Grundgerüsts der Dokumentation"
#. (itstool) path: sect1/para
-#: C/index.docbook:391
+#: C/index.docbook:376
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:400
+#: C/index.docbook:385
msgid "Example directory structure"
msgstr "Beispiel für die Ordnerstruktur"
#. (itstool) path: example/programlisting
-#: C/index.docbook:401
+#: C/index.docbook:386
#, no-wrap
msgid ""
"\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:398
+#: C/index.docbook:383
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:416 C/index.docbook:423
+#: C/index.docbook:401 C/index.docbook:408
msgid "Integration with autoconf"
msgstr "Integration in autoconf"
#. (itstool) path: sect1/para
-#: C/index.docbook:418
+#: C/index.docbook:403
msgid ""
"Very easy! Just add one line to your <filename>configure.ac</filename> "
"script."
"filename>-Skript hinzu."
#. (itstool) path: example/programlisting
-#: C/index.docbook:424
+#: C/index.docbook:409
#, no-wrap
msgid ""
"\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
#. (itstool) path: example/title
-#: C/index.docbook:436
+#: C/index.docbook:421
msgid "Keep gtk-doc optional"
msgstr "Halten Sie gtk-doc optional"
#. (itstool) path: example/programlisting
-#: C/index.docbook:437
+#: C/index.docbook:422
#, no-wrap
msgid ""
"\n"
"])\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:431
+#: C/index.docbook:416
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:448
+#: C/index.docbook:433
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:454
+#: C/index.docbook:439
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:455
+#: C/index.docbook:440
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:456
+#: C/index.docbook:441
msgid ""
"--enable-gtk-doc-html : build documentation in html format [default=yes]"
msgstr ""
"[Vorgabe=yes]"
#. (itstool) path: listitem/para
-#: C/index.docbook:457
+#: C/index.docbook:442
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:461
+#: C/index.docbook:446
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:469
+#: C/index.docbook:454
msgid ""
"Furthermore it is recommended that you have the following line inside you "
"<filename>configure.ac</filename> script. This allows "
"<function>GTK_DOC_CHECK</function> in Ihr Projekt."
#. (itstool) path: example/title
-#: C/index.docbook:477
+#: C/index.docbook:462
msgid "Preparation for gtkdocize"
msgstr "Vorbereitung für gtkdocize"
#. (itstool) path: example/programlisting
-#: C/index.docbook:478
+#: C/index.docbook:463
#, no-wrap
msgid ""
"\n"
"AC_CONFIG_MACRO_DIR(m4)\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:483
+#: C/index.docbook:468
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 ""
+"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>."
#. (itstool) path: sect1/title
-#: C/index.docbook:491
+#: C/index.docbook:476
msgid "Integration with automake"
msgstr "Integration in automake"
#. (itstool) path: sect1/para
-#: C/index.docbook:493
-#, 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."
+#: C/index.docbook:478
msgid ""
"First copy the <filename>Makefile.am</filename> from the <filename class="
"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
"this for each one."
msgstr ""
"Kopieren Sie zunächst die Datei <filename>Makefile.am</filename> aus dem "
-"Beispiel-Unterordner der gtkdoc-sources in den API-Dokumentationsordner "
-"Ihres Projekts ( <filename class=\"directory\">./docs/reference/<"
-"package></filename>). Falls Sie mehrere Dokumentationspakete haben, "
-"müssen Sie dies für jedes davon wiederholen."
+"<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."
#. (itstool) path: sect1/para
-#: C/index.docbook:504
+#: C/index.docbook:489
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:518
+#: C/index.docbook:503
msgid "Integration with autogen"
msgstr "Integration in autogen"
#. (itstool) path: sect1/para
-#: C/index.docbook:520
+#: C/index.docbook:505
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:529
+#: C/index.docbook:514
msgid "Running gtkdocize from autogen.sh"
msgstr "Ausführen von gtkdocize durch autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:530
+#: C/index.docbook:515
#, no-wrap
msgid ""
"\n"
"gtkdocize || exit 1\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:536
+#: C/index.docbook:521
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:545
+#: C/index.docbook:530
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:562 C/index.docbook:579
+#: C/index.docbook:547 C/index.docbook:564
msgid "Running the doc build"
msgstr "Erstellung der Dokumentation"
#. (itstool) path: sect1/para
-#: C/index.docbook:564
+#: C/index.docbook:549
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:571
+#: C/index.docbook:556
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:580
+#: C/index.docbook:565
#, no-wrap
msgid ""
"\n"
"make\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:586
+#: C/index.docbook:571
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:594
+#: C/index.docbook:579
msgid "Integration with version control systems"
msgstr "Integration in Versionsverwaltungssysteme"
#. (itstool) path: sect1/para
-#: C/index.docbook:596
-#, 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>"
+#: C/index.docbook:581
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>."
"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>-"
+"package>-docs.xml</filename> (früher .sgml), <filename><package>-"
"sections.txt</filename>, <filename>Makefile.am</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:604
+#: C/index.docbook:589
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 ""
+"Dateien in den Ordnern <filename>xml/</filename> und <filename>html/</"
+"filename> sollten nicht unter Versionsverwaltung gestellt werden, ebenso "
+"keine der <filename>.stamp</filename>-Dateien."
#. (itstool) path: sect1/title
-#: C/index.docbook:612
+#: C/index.docbook:597
msgid "Integration with plain makefiles or other build systems"
msgstr "Integration in Klartext-Makefiles oder andere Erstellungssysteme"
#. (itstool) path: sect1/para
-#: C/index.docbook:614
+#: C/index.docbook:599
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:621
+#: C/index.docbook:606
msgid "Documentation build steps"
msgstr "Schritte zur Erstellung der Dokumentation"
#. (itstool) path: example/programlisting
-#: C/index.docbook:622
+#: C/index.docbook:607
#, no-wrap
msgid ""
"\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:636
+#: C/index.docbook:621
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:643
-#, fuzzy
-#| msgid "Integration with plain makefiles or other build systems"
+#: C/index.docbook:628
msgid "Integration with CMake build systems"
-msgstr "Integration in Klartext-Makefiles oder andere Erstellungssysteme"
+msgstr "Integration in CMake-Erstellungssysteme"
#. (itstool) path: sect1/para
-#: C/index.docbook:645
+#: C/index.docbook:630
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 ""
+"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."
#. (itstool) path: example/title
-#: C/index.docbook:655
+#: C/index.docbook:640
msgid "Example of using GTK-Doc from CMake"
-msgstr ""
+msgstr "Beispiel zur Verwendung von GTK-Doc mit CMake"
#. (itstool) path: example/programlisting
-#: C/index.docbook:656
+#: C/index.docbook:641
#, no-wrap
msgid ""
"\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:653
+#: C/index.docbook:638
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:681
+#: C/index.docbook:666
msgid "Documenting the code"
msgstr "Dokumentieren des Codes"
#. (itstool) path: chapter/para
-#: C/index.docbook:683
+#: C/index.docbook:668
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:691
+#: C/index.docbook:676
msgid "Documentation placement"
msgstr "Platzierung der Dokumentation"
#. (itstool) path: note/para
-#: C/index.docbook:692
+#: C/index.docbook:677
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:698
+#: C/index.docbook:683
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:709 C/index.docbook:735
+#: C/index.docbook:694 C/index.docbook:720
msgid "GTK-Doc comment block"
msgstr "GTK-Doc-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:710
+#: C/index.docbook:695
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:705
+#: C/index.docbook:690
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:719
+#: C/index.docbook:704
msgid "Limitations"
msgstr "Einschränkungen"
#. (itstool) path: note/para
-#: C/index.docbook:720
+#: C/index.docbook:705
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 ""
+"Beachten Sie, dass GTK-Doc zwar <code>#ifndef(__GTK_DOC_IGNORE__)</code> "
+"unterstützt, aber nicht <code>#if !defined(__GTK_DOC_IGNORE__)</code> oder "
+"andere Kombinationen."
#. (itstool) path: sect1/title
-#: C/index.docbook:730
+#: C/index.docbook:715
msgid "Documentation comments"
msgstr "Kommentare zur Dokumentation"
#. (itstool) path: example/programlisting
-#: C/index.docbook:736
+#: C/index.docbook:721
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:732
+#: C/index.docbook:717
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:745
+#: C/index.docbook:730
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:751
+#: C/index.docbook:736
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:768
+#: C/index.docbook:753
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:774
+#: C/index.docbook:759
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:764
+#: C/index.docbook:749
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:789
+#: C/index.docbook:774
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:794
+#: C/index.docbook:779
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:800
+#: C/index.docbook:785
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:805
+#: C/index.docbook:790
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:811
+#: C/index.docbook:796
msgid "Use #Object::signal to refer to a GObject signal."
msgstr "Verwenden Sie #Object::signal, um auf ein GObject-Signal zu verweisen"
#. (itstool) path: listitem/para
-#: C/index.docbook:816
+#: C/index.docbook:801
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:821
-#, fuzzy
-#| msgid "Use #Struct.field to refer to a field inside a structure."
+#: C/index.docbook:806
msgid ""
"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
"foo_bar() to refer to a vmethod."
msgstr ""
"Verwenden Sie #Struct.field, um auf ein Feld innerhalb einer Struktur zu "
-"verweisen."
+"verweisen und #GObjectClass.foo_bar() für eine vmethod."
#. (itstool) path: sect1/para
-#: C/index.docbook:783
+#: C/index.docbook:768
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:830
+#: C/index.docbook:815
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:839
+#: C/index.docbook:824
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 "
"versions any documentation that includes Markdown will be rendered as is. "
"For example, list items will appear as lines starting with a dash."
msgstr ""
+"DocBook kann mehr als nur Verweise zu erzeugen. Sie können Listen, "
+"Beispiele, Überschriften und Bilder einfügen. In Version 1.20 ist der "
+"bevorzugte Weg, ein Subset grundlegender Textformatierungssyntax namens "
+"<ulink url=\"http://daringfireball.net/projects/markdown/\">Markdown</ulink> "
+"zu verwenden. In älteren Versionen von GTK-Doc wird jede Dokumentation, die "
+"Markdown enthält, unverändert gerendert. Zum Beispiel erscheinen "
+"Listenobjekte als Zeilen, die mit einem Gedankenstrich beginnen."
#. (itstool) path: sect1/para
-#: C/index.docbook:850
+#: C/index.docbook:835
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 ""
+"Wenngleich Markdown bevorzugt wird, können Sie beide Formate mischen. Eine "
+"Einschränkung ist jedoch, dass Sie DocBook XML innerhalb von Markdown "
+"verwenden können, während Markdown in DocBook XML nicht unterstützt wird."
#. (itstool) path: sect1/para
-#: C/index.docbook:856
-#, 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>."
+#: C/index.docbook:841
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 "
"the variable <symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</"
"filename>."
msgstr ""
-"DocBook kann mehr als nur verknüpfen. Sie können auch Listen, Tabellen und "
-"Beispiele einbauen. Um die Nutzung der DocBook-SGML/XML-Tags innerhalb der "
+"Um die Nutzung der DocBook-XML-Markierungen innerhalb der "
"Dokumentationskommentare zu aktivieren, übergeben Sie der Variable "
"<symbol>MKDB_OPTIONS</symbol> in der Datei <filename>Makefile.am</filename> "
-"die Option <option>--xml-mode</option> oder <option>--sgml-mode</option>."
+"die Option <option>--xml-mode</option> (oder <option>--sgml-mode</option>)."
#. (itstool) path: example/title
-#: C/index.docbook:865
-#, fuzzy
-#| msgid "GTK-Doc comment block using markdown"
+#: C/index.docbook:850
msgid "GTK-Doc comment block using Markdown"
msgstr "GTK-Doc-Kommentarblock in Markdown-Syntax"
#. (itstool) path: example/programlisting
-#: C/index.docbook:866
+#: C/index.docbook:851
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:905
+#: C/index.docbook:890
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+ Documentation Markdown Syntax Reference</ulink>."
msgstr ""
+"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>."
#. (itstool) path: tip/para
-#: C/index.docbook:911
+#: C/index.docbook:896
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:925
+#: C/index.docbook:910
msgid "Documenting sections"
msgstr "Dokumentieren von Abschnitten"
#. (itstool) path: sect1/para
-#: C/index.docbook:927
+#: C/index.docbook:912
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:935
+#: C/index.docbook:920
msgid "Section comment block"
msgstr "Abschnitts-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:936
+#: C/index.docbook:921
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:955
+#: C/index.docbook:940
msgid "SECTION:<name>"
msgstr "SECTION:<name>"
#. (itstool) path: listitem/para
-#: C/index.docbook:957
+#: C/index.docbook:942
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> entsprechen."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:966
+#: C/index.docbook:951
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:968
+#: C/index.docbook:953
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:975
+#: C/index.docbook:960
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:977
+#: C/index.docbook:962
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:984
+#: C/index.docbook:969
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:986
+#: C/index.docbook:971
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:994
+#: C/index.docbook:979
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:996
+#: C/index.docbook:981
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:1002
+#: C/index.docbook:987
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1009
+#: C/index.docbook:994
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:1021
+#: C/index.docbook:1006
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:1033
+#: C/index.docbook:1018
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:1042
+#: C/index.docbook:1027
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:1004
+#: C/index.docbook:989
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:1054
+#: C/index.docbook:1039
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1056
+#: C/index.docbook:1041
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:1065
+#: C/index.docbook:1050
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1067
+#: C/index.docbook:1052
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:1078
+#: C/index.docbook:1063
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:1087
+#: C/index.docbook:1072
msgid "Documenting symbols"
msgstr "Dokumentieren von Symbolen"
#. (itstool) path: sect1/para
-#: C/index.docbook:1089
+#: C/index.docbook:1074
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:1097 C/index.docbook:1163
+#: C/index.docbook:1082 C/index.docbook:1148
msgid "General tags"
msgstr "Allgemeine Markierungen"
#. (itstool) path: sect2/para
-#: C/index.docbook:1099
+#: C/index.docbook:1084
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:1104
+#: C/index.docbook:1089
msgid "Versioning Tags"
msgstr "Versionierungs-Markierungen"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1105
+#: C/index.docbook:1090
msgid "Since:"
msgstr "Since:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1107
+#: C/index.docbook:1092
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:1112
+#: C/index.docbook:1097
msgid "Deprecated:"
msgstr "Deprecated:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1114
+#: C/index.docbook:1099
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:1122
-#, fuzzy
-#| msgid ""
-#| "You can add versioning information to all documentation elements to tell "
-#| "when an API was introduced, or when it was deprecated."
+#: C/index.docbook:1107
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 ""
-"Sie können Versionsinformationen zu allen Dokumentationselementen "
-"hinzufügen, um darauf hinzuweisen, wann eine API eingeführt oder wann sie "
-"als veraltet markiert wurde."
+"Sie können Stabilitätsinformationen zu allen Dokumentationselementen "
+"hinzufügen, um darauf hinzuweisen, ob API-Stabilität für alle Minor-"
+"Veröffentlichungen des Projekts garantiert wird."
#. (itstool) path: sect2/para
-#: C/index.docbook:1128
+#: C/index.docbook:1113
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 ""
+"Die Standard-Stabilitätsstufe für alle Dokumentationselemente setzen Sie "
+"durch Übergabe des Arguments <option>--default-stability</option> an "
+"<application>gtkdoc-mkdb</application> in einem der nachfolgend "
+"beschriebenen Werte."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1134
-#, fuzzy
-#| msgid "@stability"
+#: C/index.docbook:1119
msgid "Stability Tags"
-msgstr "@stability"
+msgstr "Stabilitäts-Markierungen"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1135
+#: C/index.docbook:1120
msgid "Stability: Stable"
-msgstr ""
+msgstr "Stability: Stable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1137
+#: C/index.docbook:1122
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 ""
+"Markiert das Element als stabil. Dies bezieht sich auf öffentliche APIs, für "
+"die für alle zukünftigen Minor-Veröffentlichungen des Projekts Stabilität "
+"gewährleistet ist."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1144
+#: C/index.docbook:1129
msgid "Stability: Unstable"
-msgstr ""
+msgstr "Stability: Unstable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1146
+#: C/index.docbook:1131
msgid ""
"Mark the element as unstable. This is for public APIs which are released as "
"a preview before being stabilised."
msgstr ""
+"Markiert das Element als instabil. Dies bezieht sich auf öffentliche APIs, "
+"die als Vorschau vor der endgültigen Stabilisierung gedacht sind."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1152
+#: C/index.docbook:1137
msgid "Stability: Private"
-msgstr ""
+msgstr "Stability: Private"
#. (itstool) path: listitem/para
-#: C/index.docbook:1154
+#: C/index.docbook:1139
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 ""
+"Markiert das Element als privat. Dies bezieht sich auf Schnittstellen, die "
+"von eng damit verknüpften Modulen genutzt werden kann, aber nicht von "
+"beliebigen Drittanbietern."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1164
+#: C/index.docbook:1149
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1184 C/index.docbook:1194
+#: C/index.docbook:1169 C/index.docbook:1179
msgid "Annotations"
msgstr "Anmerkungen"
#. (itstool) path: sect2/para
-#: C/index.docbook:1186
+#: C/index.docbook:1171
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"supported tags can be found on <ulink url=\"http://live.gnome.org/"
"GObjectIntrospection/Annotations\" type=\"http\">the wiki</ulink>."
msgstr ""
+"Dokumentationsblöcke können Anmerkungs-Markierungen enthalten. Diese "
+"Markierungen werden als Tooltips (Minihilfen) dargestellt, die die jeweilige "
+"Bedeutung anzeigen. Sie werden von gobject-introspection genutzt, um "
+"Sprachbindungen zu erzeugen. Eine detaillierte Liste der unterstützten "
+"Markierungen finden Sie im <ulink url=\"http://live.gnome.org/"
+"GObjectIntrospection/Annotations\" type=\"http\">Wiki</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1195
+#: C/index.docbook:1180
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1216 C/index.docbook:1245
+#: C/index.docbook:1201 C/index.docbook:1230
msgid "Function comment block"
msgstr "Kommentarblock einer Funktion"
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1207
msgid ""
"Document whether returned objects, lists, strings, etc, should be freed/"
"unrefed/released."
"dereferenziert/freigegeben werden."
#. (itstool) path: listitem/para
-#: C/index.docbook:1228
+#: C/index.docbook:1213
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:1233
+#: C/index.docbook:1218
msgid ""
"Mention interesting pre-conditions and post-conditions where appropriate."
msgstr ""
"es nützlich erscheint."
#. (itstool) path: sect2/para
-#: C/index.docbook:1218 C/index.docbook:1304
+#: C/index.docbook:1203 C/index.docbook:1289
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Bitte denken Sie an: <_:itemizedlist-1/>"
#. (itstool) path: sect2/para
-#: C/index.docbook:1240
+#: C/index.docbook:1225
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:1246
+#: C/index.docbook:1231
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1267
+#: C/index.docbook:1252
msgid "Function tags"
-msgstr "Funktions-Tags"
+msgstr "Funktions-Markierungen"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1268
+#: C/index.docbook:1253 C/index.docbook:1460
msgid "Returns:"
msgstr "Returns:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1270
+#: C/index.docbook:1255
msgid "Paragraph describing the returned result."
msgstr "Abschnitt, der das zurückgegebene Ergebnis beschreibt."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1275
+#: C/index.docbook:1260
msgid "@...:"
msgstr "@...:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1277
+#: C/index.docbook:1262
msgid ""
"In case the function has variadic arguments, you should use this tag "
"(@Varargs: does also work for historic reasons)."
msgstr ""
+"Wenn die Funktion variadische Argumente enthält, sollten Sie diese "
+"Markierung verwenden (@Varargs: funktioniert aus historischen Gründen "
+"ebenfalls)."
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1287 C/index.docbook:1289
+#: C/index.docbook:1272 C/index.docbook:1274
msgid "Property comment block"
msgstr "Property-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1290
+#: C/index.docbook:1275
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1302 C/index.docbook:1321
+#: C/index.docbook:1287 C/index.docbook:1306
msgid "Signal comment block"
msgstr "Signal-Kommentarblock"
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1293
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:1314
+#: C/index.docbook:1299
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:1322
+#: C/index.docbook:1307
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1339 C/index.docbook:1340
+#: C/index.docbook:1324 C/index.docbook:1325
msgid "Struct comment block"
msgstr "Struct-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1341
+#: C/index.docbook:1326
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1341
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:1362
+#: C/index.docbook:1347
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 ""
+"Wenn das erste Feld »g_iface«, »parent_instance« oder »parent_class« ist, "
+"wird es automatisch als privat angesehen und muss nicht im Kommentarblock "
+"erwähnt werden."
#. (itstool) path: sect2/para
-#: C/index.docbook:1368
+#: C/index.docbook:1353
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 "
"here is that this creates two index entries of the same name (the structure "
"and the section)."
msgstr ""
+"Struct-Kommentarblöcke können auch für GObjects und GObjectClasses verwendet "
+"werden. Es ist ratsam, einen Kommentarblock für eine Klasse hinzuzufügen, "
+"wenn diese vmethods enthält (dies ist die Art der Dokumentation dafür). Für "
+"GObject selbst können Sie die jeweiligen Abschnittsdokumentationen "
+"verwenden, wobei ein separater Block für das Instanz-Struct sinnvoll ist, "
+"sofern die Instanz öffentliche Felder enthält. Ein Nachteil ist hier, dass "
+"dadurch zwei gleichnamige Indexeinträge erstellt werden (die Struktur und "
+"der Abschnitt)."
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1380 C/index.docbook:1381
+#: C/index.docbook:1365 C/index.docbook:1366
msgid "Enum comment block"
msgstr "Enum-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1382
+#: C/index.docbook:1367
#, no-wrap
msgid ""
"\n"
"} Something;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1399
+#: C/index.docbook:1384
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:1409
+#: C/index.docbook:1395
+msgid "Inline program documentation"
+msgstr "Eingebettete Programmdokumentation"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1396
+msgid ""
+"You can document programs and their commandline interface using inline "
+"documentation."
+msgstr ""
+"Dokumentieren Sie ein Programm und dessen Befehlszeilen-Schnittstelle mit "
+"eingebetteter Dokumentation."
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1402
+msgid "Tags"
+msgstr "Schlagwörter"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1404
+msgid "PROGRAM"
+msgstr "PROGRAM"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1407
+msgid "Defines the start of a program documentation."
+msgstr "Definiert den Start einer Programmdokumentation"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1414
+msgid "@short_description:"
+msgstr "@short_description:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1416
+msgid "Defines a short description of the program. (Optional)"
+msgstr "Definiert eine Kurzbeschreibung des Programms (optional)."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1423
+msgid "@synopsis:"
+msgstr "@synopsis:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1425
+msgid ""
+"Defines the arguments, or list of arguments that the program can take. "
+"(Optional)"
+msgstr ""
+"Definiert die Argumente oder eine Liste von Argumenten, die das Programm "
+"akzeptiert (optional)."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1433
+msgid "@see_also:"
+msgstr "@see_also:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1435
+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:1442
+msgid "@arg:"
+msgstr "@arg:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1444
+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:1451
+msgid "Description:"
+msgstr "Description:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1453
+msgid "A longer description of the program."
+msgstr "Eine ausführlichere Beschreibung des Programms."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1462
+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:1471
+msgid "Example of program documentation."
+msgstr "Beispiel einer Programmdokumentation."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1472
+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:1473
+#, 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 ""
+"\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"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1499
msgid "Useful DocBook tags"
-msgstr "Nützliche DocBook-Tags"
+msgstr "Nützliche DocBook-Markierungen"
#. (itstool) path: sect1/para
-#: C/index.docbook:1411
+#: C/index.docbook:1501
msgid ""
"Here are some DocBook tags which are most useful when documenting the code."
msgstr ""
-"Nachfolgend finden Sie einige DocBook-Tags, die beim Dokumentieren von Code "
-"nützlich sein können."
+"Nachfolgend finden Sie einige DocBook-Markierungen, die beim Dokumentieren "
+"von Code nützlich sein können."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1420
+#: C/index.docbook:1510
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1416
+#: C/index.docbook:1506
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:1433
+#: C/index.docbook:1523
#, no-wrap
msgid ""
"\n"
"<function>...</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1430
+#: C/index.docbook:1520
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
"<_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1442
+#: C/index.docbook:1532
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1453
+#: C/index.docbook:1543
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1439
+#: C/index.docbook:1529
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:1472
+#: C/index.docbook:1562
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1469
+#: C/index.docbook:1559
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Für eine Liste mit Aufzählungszeichen: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1492
+#: C/index.docbook:1582
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1489
+#: C/index.docbook:1579
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:1505
+#: C/index.docbook:1595
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1502
+#: C/index.docbook:1592
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:1514
+#: C/index.docbook:1604
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1511
+#: C/index.docbook:1601
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:1523
+#: C/index.docbook:1613
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1520
+#: C/index.docbook:1610
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:1532
+#: C/index.docbook:1622
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1529
+#: C/index.docbook:1619
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:1543
+#: C/index.docbook:1633
#, no-wrap
msgid ""
"\n"
"<emphasis>This is important</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1540
+#: C/index.docbook:1630
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Zum Hervorheben von Text: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1552
+#: C/index.docbook:1642
#, no-wrap
msgid ""
"\n"
"<filename>/home/user/documents</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1549
+#: C/index.docbook:1639
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Für Dateinamen: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1561
+#: C/index.docbook:1651
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1558
+#: C/index.docbook:1648
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:1571
+#: C/index.docbook:1661
msgid "Filling the extra files"
msgstr "Füllen der zusätzlichen Dateien"
#. (itstool) path: chapter/para
-#: C/index.docbook:1573
+#: C/index.docbook:1663
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:1582
+#: C/index.docbook:1672
msgid "Editing the types file"
msgstr "Bearbeiten der Typendatei"
#. (itstool) path: sect1/para
-#: C/index.docbook:1584
+#: C/index.docbook:1674
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:1593
+#: C/index.docbook:1683
msgid "Example types file snippet"
msgstr "Beispiel-Schnipsel einer Typen-Datei"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1594
+#: C/index.docbook:1684
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1605
-#, fuzzy
+#: C/index.docbook:1695
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"Seit GTK-Doc 1.8 kann <application>gtkdoc-scan</application> diese Liste für "
"Sie erstellen. Fügen Sie einfach »--rebuild-types« zu SCAN_OPTIONS in "
"<filename>Makefile.am</filename> hinzu. Wenn Sie so vorgehen sollten Sie "
-"nicht ??"
+"weder Typen-Datei mit veröffentlichen noch diese unter Versionsverwaltung "
+"stellen."
#. (itstool) path: sect1/title
-#: C/index.docbook:1614
+#: C/index.docbook:1704
msgid "Editing the master document"
msgstr "Bearbeiten des Master-Dokuments"
#. (itstool) path: sect1/para
-#: C/index.docbook:1616
+#: C/index.docbook:1706
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:1623
-#, 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."
+#: C/index.docbook:1713
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 "
"scratch. Its a good idea to look at this from time to time to see if there "
"are some new goodies introduced there."
msgstr ""
-"Während GTK-Doc ein Vorlagen-Hauptdokument für Sie erstellt wird eine "
-"spätere Ausführung es nicht mehr verändern. Dies bedeutet, dass man das "
-"Dokument beliebig strukturieren kann. Dies schließt Gruppieren von Seiten "
+"Während GTK-Doc ein Vorlagen-Hauptdokument für Sie erstellt, wird eine "
+"spätere Ausführung es nicht mehr verändern. Das bedeutet, dass Sie das "
+"Dokument beliebig strukturieren können. Dies schließt Gruppieren von Seiten "
"und Hinzufügen von zusätzlichen Seiten ein. GTK-Doc hat eine neue Test-"
-"Garnitur, wo auch das Hauptdokument von Neuem erstellt wird. Es ist ratsam "
-"sich diese von Zeit zu Zeit anzusehen und zu schauen, ob dort einige "
+"Suite, wo auch das Hauptdokument von Grund auf neu erstellt wird. Es ist "
+"ratsam, sich diese von Zeit zu Zeit anzusehen und zu schauen, ob dort einige "
"Neuigkeiten eingeführt werden."
#. (itstool) path: tip/para
-#: C/index.docbook:1633
+#: C/index.docbook:1723
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:1642
+#: C/index.docbook:1732
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:1649
+#: C/index.docbook:1739
msgid "Master document header"
msgstr "Kopfzeile des Master-Dokuments"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1650
+#: C/index.docbook:1740
#, no-wrap
msgid ""
"\n"
" <title>[Insert title here]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1666
+#: C/index.docbook:1756
msgid ""
"In addition a few option elements are created in commented form. You can "
"review these and enable them as you like."
msgstr ""
+"Zusätzlich werden einige Optionselemente in Kommentarform erstellt. Sie "
+"können sich diese anschauen und aktivieren, wenn Sie wollen."
#. (itstool) path: example/title
-#: C/index.docbook:1672
-#, fuzzy
-#| msgid "Editing the master document"
+#: C/index.docbook:1762
msgid "Optional part in the master document"
-msgstr "Bearbeiten des Master-Dokuments"
+msgstr "Optionaler Teil im Master-Dokument"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1673
+#: C/index.docbook:1763
#, 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"
+" -->\n"
msgstr ""
"\n"
-" <!-- enable this when you use gobject introspection annotations\n"
+" <!-- aktivieren Sie dieses, wenn sie gobject introspection-Anmerkungen verwenden\n"
" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n"
" --> \n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1681
+#: C/index.docbook:1771
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 ""
+"Schlussendlich müssen Sie einen neuen Abschnitt explizit einfügen, sobald "
+"Sie einen öffnen. Das Werkzeug <link linkend=\"modernizing-gtk-"
+"doc-1-16\">gtkdoc-check</link> erinnert Sie an neu erzeugte XML-Dateien, die "
+"in der Dokumentation noch nicht erfasst sind."
#. (itstool) path: example/title
-#: C/index.docbook:1689 C/index.docbook:1724
+#: C/index.docbook:1779 C/index.docbook:1814
msgid "Including generated sections"
-msgstr ""
+msgstr "Einbeziehen erzeugter Abschnitte"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1690
+#: C/index.docbook:1780
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1702
+#: C/index.docbook:1792
msgid "Editing the section file"
msgstr "Bearbeiten der Abschnittsdatei"
#. (itstool) path: sect1/para
-#: C/index.docbook:1704
+#: C/index.docbook:1794
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:1710
-#, fuzzy
-#| msgid ""
-#| "The section file is a plain text file with XML-like syntax (using tags). "
-#| "Blank lines are ignored and lines starting with a '#' are treated as "
-#| "comment lines."
+#: C/index.docbook:1800
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."
msgstr ""
-"Die Abschnittsdatei ist eine reine Textdatei mit XML-ähnlicher Syntax (mit "
-"Tags). Leere Zeilen werden ignoriert und Zeilen, die mit »#« beginnen, "
-"werden als Kommentarzeilen behandelt."
+"Die Abschnittsdatei ist eine reine Textdatei mit Markierungen, welche die "
+"Abschnitte voneinander trennen. Leere Zeilen werden ignoriert und Zeilen, "
+"die mit »#« beginnen, werden als Kommentarzeilen behandelt."
#. (itstool) path: note/para
-#: C/index.docbook:1717
+#: C/index.docbook:1807
msgid ""
"While the tags make the file look like xml, it is not. Please do not close "
"tags like <SUBSECTION>."
msgstr ""
+"Zwar lassen die Markierungen die Datei wie XML erscheinen, doch der Schein "
+"trügt. Bitte schließen Sie keine Markierungen wie <SUBSECTION>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1725
+#: C/index.docbook:1815
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1742
-#, 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 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)."
+#: C/index.docbook:1832
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"title, or for GObjects it is based on the GObjects class name converted to "
"lower case)."
msgstr ""
-"Das Tag <FILE> ... </FILE> wird verwendet, um den Dateinamen "
-"ohne Suffix anzugeben. Zum Beispiel wird »<FILE>gnome-config</"
-"FILE>« dazu führen, dass der Deklarationsabschnitt in die Vorlage-Datei "
-"<filename>tmpl/gnome-config.sgml</filename> ausgegeben wird, welche in die "
-"DocBook SGML/XML-Datei <filename>sgml/gnome-config.sgml</filename> oder die "
-"DocBook XML-Datei <filename>xml/gnome-config.xml</filename> umgewandelt "
-"wird. (Der Name der HTML-Datei basiert auf dem Modulnamen und dem "
-"Abschnittstitel. Für GObject basiert er auf dem GObjekt-Klassennamen in "
+"Die Markierung <FILE> ... </FILE> wird verwendet, um den "
+"Dateinamen ohne Suffix anzugeben. Zum Beispiel wird »<FILE>gnome-"
+"config</FILE>« dazu führen, dass der Deklarationsabschnitt in die "
+"Vorlage-Datei <filename>tmpl/gnome-config.sgml</filename> ausgegeben wird, "
+"welche in die DocBook-XML-Datei <filename>sgml/gnome-config.sgml</filename> "
+"oder die DocBook-XML-Datei <filename>xml/gnome-config.xml</filename> "
+"umgewandelt wird. (Der Name der HTML-Datei basiert auf dem Modulnamen und "
+"dem Abschnittstitel. Für GObject basiert er auf dem GObject-Klassennamen in "
"Kleinbuchstaben)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1754
+#: C/index.docbook:1844
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:1761
-#, fuzzy
+#: C/index.docbook:1851
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"Whether you would place GObject and GObjectClass like structs in public or "
"Standard section depends if they have public entries (variables, vmethods)."
msgstr ""
-"Sie können Objekte im Abschnitt mittels des Tag <SUBSECTION> "
+"Sie können Objekte im Abschnitt mittels der Markierung <SUBSECTION> "
"gruppieren. Derzeit gibt es eine Leerzeile zwischen Unterabschnitten im "
"Inhaltsangabe-Abschnitt aus. Sie können auch <SUBSECTION Standard> für "
"Standard GObject-Deklarationen verwenden (z.B. Funktionen wie "
"g_object_get_type und Makros wie G_OBJECT(), G_IS_OBJECT() etc.). Derzeit "
-"werden diese nicht in die Dokumentation aufgenommen. Die können auch <"
+"werden diese nicht in die Dokumentation aufgenommen. Sie können auch <"
"SUBSECTION Private> für private Deklarationen verwenden, welche nicht "
-"ausgegeben werden …"
+"ausgegeben werden. Dies ist eine praktische Möglichkeit, Warnmeldungen "
+"bezüglich ungenutzter Deklarationen zu vermeiden. Wenn Ihre Bibliothek "
+"private Typen enthält, die nicht in der Objekthierarchie und der Liste der "
+"implementierten oder benötigten Schnittstellen erscheinen sollen, fügen Sie "
+"diese zu einem »Private«-Unterabschnitt hinzu. Ob Sie GObject oder "
+"GObjectClass wie Structs im öffentlichen oder im Standardabschnitt "
+"einsetzen, hängt davon ab, ob öffentliche Einträge vorhanden sind "
+"(Variablen, vmethods)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1780
+#: C/index.docbook:1870
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:1794
+#: C/index.docbook:1884
msgid "Controlling the result"
msgstr "Überprüfung des Ergebnisses"
#. (itstool) path: chapter/para
-#: C/index.docbook:1796
+#: C/index.docbook:1886
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:1805
+#: C/index.docbook:1895
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:1814
+#: C/index.docbook:1904
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:1821
+#: C/index.docbook:1911
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:1829
+#: C/index.docbook:1919
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:1836
+#: C/index.docbook:1926
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:1845
-#, 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, by running it as <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</"
-#| "command>."
+#: C/index.docbook:1935
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>, <filename><package>.hierarchy.txt</filename>, <filename><"
"package>.interfaces.txt</filename>, <filename><package>."
"prerequisites.txt</filename> und <filename><package>.signals.txt</"
-"filename>. Falls es in irgendeiner Datei fehlende Symbole gibt, kann man "
-"gtkdoc anweisen die zwischenläufige Scanner-Datei zur weiteren Analyse zu "
-"behalten, indem man <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command> "
-"ausführt."
+"filename>. Falls in irgendeiner Datei Symbole fehlen, können Sie Gtk-Doc "
+"anweisen, die zwischenläufige Scanner-Datei zur weiteren Analyse zu "
+"behalten, indem Sie <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command> "
+"ausführen."
#. (itstool) path: chapter/title
-#: C/index.docbook:1860
+#: C/index.docbook:1950
msgid "Modernizing the documentation"
msgstr "Die Dokumentation modernisieren"
#. (itstool) path: chapter/para
-#: C/index.docbook:1862
+#: C/index.docbook:1952
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 ""
+"GTK-Doc ist schon seit längerer Zeit verfügbar. In diesem Abschnitt zeigen "
+"wir neue Features und die Version, mit der sie eingeführt wurden."
#. (itstool) path: sect1/title
-#: C/index.docbook:1868
+#: C/index.docbook:1958
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1870
-#, fuzzy
-#| msgid ""
-#| "Is the new page xi:included from <filename><package>-docs.{xml,sgml}"
-#| "</filename>."
+#: C/index.docbook:1960
msgid ""
"When using xml instead of sgml, one can actually name the master document "
"<filename><package>-docs.xml</filename>."
msgstr ""
-"Ist die neue Seite xi:eingebunden von <filename><package>-docs.{xml,"
-"sgml}</filename>?"
+"Wenn Sie XML anstatt SGML verwenden, können Sie das Hauptdokument "
+"<filename><package>-docs.xml</filename> nennen."
#. (itstool) path: sect1/para
-#: C/index.docbook:1875
+#: C/index.docbook:1965
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-sections</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"simple as running <code>meld <package>-decl-list.txt <package>-"
"sections.txt</code>."
msgstr ""
+"Diese Version unterstützt <option>SCAN_OPTIONS=--rebuild-sections</option> "
+"in <filename>Makefile.am</filename>. Wenn dies aktiviert ist, wird die Datei "
+"<filename><package>-sections.txt</filename> automatisch erzeugt und "
+"kann aus der Versionsverwaltung entfernt werden. Dies funktioniert nur "
+"sauber in Projekten, die eine strikt »reguläre« Struktur haben (zum Beispiel "
+"erzeugt jedes .{c,h}-Paar einen neuen Abschnitt). In einem solch sauber "
+"organisierten Projekt kann dann mit dem Befehl <code>meld <package>-"
+"decl-list.txt <package>-sections.txt</code> eine manuell verwaltete "
+"Abschnittsdatei sehr einfach aktualisiert werden."
#. (itstool) path: sect1/para
-#: C/index.docbook:1886
+#: C/index.docbook:1976
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"control system and haven't yet switched, just add the flag to "
"<filename>configure.ac</filename> and you are done."
msgstr ""
+"In Version 1.8 wurde bereits die Syntax für Dokumentationsabschnitte in den "
+"Quelltexten anstelle von separaten Dateien unter <filename class=\"directory"
+"\">tmpl</filename> eingeführt. Diese Version fügt Optionen zur Umstellung "
+"des gesamten Dokumentationsmoduls auf das neue Verhalten hinzu, so dass kein "
+"zusätzlicher tmpl-Erstellungsschritt mehr nötig ist. Dazu dient die Option "
+"<option>--flavour no-tmpl</option> in <filename>configure.ac</filename>. "
+"Wenn Sie keinen Ordner namens <filename class=\"directory\">tmpl</filename> "
+"unter Versionsverwaltung haben und noch nicht umgestellt haben, fügen Sie "
+"einfach die Option zu <filename>configure.ac</filename> hinzu, und die Sache "
+"ist erledigt."
#. (itstool) path: sect1/title
-#: C/index.docbook:1898
+#: C/index.docbook:1988
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:1900
+#: C/index.docbook:1990
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"<varname>IGNORE_HFILES</varname> in <filename>Makefile.am</filename> for "
"code that is build conditionally."
msgstr ""
+"Diese Version unterstützt <option>SCAN_OPTIONS=--rebuild-typess</option> in "
+"<filename>Makefile.am</filename>. Wenn dies aktiviert ist, wird die Datei "
+"<filename><package>.types</filename> automatisch erzeugt und kann aus "
+"der Versionsverwaltung entfernt werden. Dieses Feature erfordert die "
+"Einrichtung von <varname>IGNORE_HFILES</varname> in <filename>Makefile.am</"
+"filename> für Code, der nur unter bestimmten Bedingungen erstellt werden "
+"soll."
#. (itstool) path: sect1/title
-#: C/index.docbook:1911
+#: C/index.docbook:2001
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:1917
+#: C/index.docbook:2007
msgid "Enable gtkdoc-check"
msgstr "gtkdoc-check einschalten"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1918
+#: C/index.docbook:2008
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1913
+#: C/index.docbook:2003
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 ""
+"Diese Version führt ein neues Werkzeug namens gtkdoc-check ein. Damit können "
+"Sie eine Reihe von Plausibilitätsprüfungen auf Ihre Dokumentation anwenden. "
+"Um es zu aktivieren, fügen Sie folgende Zeilen am Ende von "
+"<filename>Makefile.am</filename> hinzu. <_:example-1/>"
#. (itstool) path: sect1/title
-#: C/index.docbook:1931
+#: C/index.docbook:2021
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:1933
+#: C/index.docbook:2023
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 ""
+"In Version 1.18 wurde erstmals Unterstützung für Markdown eingeführt. Die "
+"Verwendung von Markdown in Dokumentationskommentaren ist weniger aufwändig "
+"als das Schreiben von DocBook XML. Diese Version bringt diesbezüglich "
+"wesentliche Verbesserungen und fügt zahlreiche weitere Stile hinzu. Alle "
+"Details hierzu finden Sie im Abschnitt zur <link linkend=\"documenting_syntax"
+"\">Kommentarsyntax</link>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1943
+#: C/index.docbook:2033
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:1953
+#: C/index.docbook:2043
msgid "Use pre-generated entities"
-msgstr ""
+msgstr "Vorerzeugte Entitäten verwenden"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1954
+#: C/index.docbook:2044
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1945
+#: C/index.docbook:2035
msgid ""
"The makefiles shipped with this version generate an entity file at "
"<filename>xml/gtkdocentities.ent</filename>, containing entities for e.g. "
"also be used in all generated files, GTK-Doc will use the same xml header in "
"generated xml files. <_:example-1/>"
msgstr ""
+"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-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1979
+#: C/index.docbook:2069
msgid "Documenting other interfaces"
msgstr "Dokumentieren anderer Schnittstellen"
#. (itstool) path: chapter/para
-#: C/index.docbook:1981
+#: C/index.docbook:2071
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:1988
+#: C/index.docbook:2078
msgid "Command line options and man pages"
msgstr "Befehlszeilenoptionen und Handbuchseiten"
#. (itstool) path: sect1/para
-#: C/index.docbook:1990
+#: C/index.docbook:2080
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:1997
+#: C/index.docbook:2087
msgid "Document the tool"
msgstr "Dokumentieren des Werkzeuges"
#. (itstool) path: sect2/para
-#: C/index.docbook:1999
-#, fuzzy
+#: C/index.docbook:2089
msgid ""
"Create one refentry file per tool. Following <link linkend="
"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
msgstr ""
"Erstellen Sie eine Referenzeintragsdatei pro Werkzeug. In <link linkend="
"\"settingup_docfiles\">unserem Beispiel</link> nennen wir sie <filename>meep/"
-"docs/reference/meeper/meep.xml</filename>. Für die zu verwendenden XML-Tags "
-"können Sie die generierte Datei im XML-Verzeichnis oder Beispiele (z.B. in "
-"glib) ansehen."
+"docs/reference/meeper/meep.xml</filename>. Für die zu verwendenden XML-"
+"Markierungen können Sie die generierte Datei im XML-Unterordner oder "
+"Beispiele (z.B. in glib) ansehen."
#. (itstool) path: sect2/title
-#: C/index.docbook:2009
+#: C/index.docbook:2099
msgid "Adding the extra configure check"
msgstr "Hinzufügen der zusätzlichen Configure-Überprüfungen"
#. (itstool) path: example/title
-#: C/index.docbook:2012 C/index.docbook:2030
+#: C/index.docbook:2102 C/index.docbook:2120
msgid "Extra configure checks"
msgstr "Zusätzliche Configure-Überprüfungen"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2013
+#: C/index.docbook:2103
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2027
+#: C/index.docbook:2117
msgid "Adding the extra makefile rules"
msgstr "Hinzufügen der zusätzlichen Makefile-Regeln"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2031
+#: C/index.docbook:2121
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2053
+#: C/index.docbook:2143
msgid "DBus interfaces"
msgstr "DBus-Schnittstellen"
#. (itstool) path: sect1/para
-#: C/index.docbook:2055
+#: C/index.docbook:2145
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:2064
+#: C/index.docbook:2154
msgid "Frequently asked questions"
msgstr "Häufig gestellte Fragen"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2068
+#: C/index.docbook:2158
msgid "Question"
msgstr "Frage"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2069
+#: C/index.docbook:2159
msgid "Answer"
msgstr "Antwort"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2071
+#: C/index.docbook:2161
msgid "No class hierarchy."
msgstr "Keine Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2072
+#: C/index.docbook:2162
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:2078
+#: C/index.docbook:2168
msgid "Still no class hierarchy."
msgstr "Noch immer keine Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2079
+#: C/index.docbook:2169
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:2085
+#: C/index.docbook:2175
msgid "Damn, I have still no class hierarchy."
msgstr "Verdammt, ich habe immer noch keine Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2086
+#: C/index.docbook:2176
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:2093
+#: C/index.docbook:2183
msgid "No symbol index."
msgstr "Kein Symbolindex."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2094
+#: C/index.docbook:2184
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:2100
+#: C/index.docbook:2190
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:2101
+#: C/index.docbook:2191
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:2107
+#: C/index.docbook:2197
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:2108
+#: C/index.docbook:2198
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"sgml}</filename>?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2114
+#: C/index.docbook:2204
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:2115
+#: C/index.docbook:2205
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:2123
+#: C/index.docbook:2213
msgid "A type is missing from the class hierarchy."
msgstr "Ein Typ fehlt in der Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2124
+#: C/index.docbook:2214
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:2133
+#: C/index.docbook:2223
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:2134
+#: C/index.docbook:2224
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:2142
+#: C/index.docbook:2232
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:2143
+#: C/index.docbook:2233
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
"Header unterschiedlich sind"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2148
-#, fuzzy
+#: C/index.docbook:2238
msgid "multiple \"IDs\" for constraint linkend: XYZ"
-msgstr "mehrfache »ID« für ?"
+msgstr "Mehrfache »IDs« für »constraint linkend: XYZ«"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2149
+#: C/index.docbook:2239
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"sections.txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2152
+#: C/index.docbook:2242
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
msgstr ""
+"Element-Typname im Namensraum '' in einem Abschnitt, der keiner Vorlage "
+"entspricht."
#. (itstool) path: chapter/title
-#: C/index.docbook:2159
+#: C/index.docbook:2249
msgid "Tools related to gtk-doc"
msgstr "Werkzeuge mit Bezug zu gtk-doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2161
+#: C/index.docbook:2251
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:2166
+#: C/index.docbook:2256
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."
#. (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 distribute it "
"individually under this License, provided you insert a copy of this License "
"wie der <_:ulink-1/>, zu veröffentlichen, um ihren Gebrauch in freier "
"Software zu erlauben."
+#~ 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>Erstellen der »Vorlage«-Dateien.</guilabel> <application>gtkdoc-"
+#~ "mktmpl</application> erstellt einige Dateien im Unterordner <filename "
+#~ "class=\"directory\">tmpl/</filename> mit Hilfe der Informationen aus dem "
+#~ "ersten Schritt. (Bedenken Sie, dass dies wiederholt ausgeführt werden "
+#~ "kann. Es wird versucht sicherzustellen, dass keine Dokumentation jemals "
+#~ "verloren geht.)"
+
+#~ 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 ""
+#~ "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. 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."
+
#~ msgid "1.18.1"
#~ msgstr "1.18.1"
<title>6. SAMMLUNGEN VON DOKUMENTEN</title>
<para>Sie dürfen eine Sammlung erstellen, die aus dem <link linkend="fdl-document">Dokument</link> und anderen, unter dieser Lizenz veröffentlichten Dokumenten besteht, und die individuellen Kopien der Lizenz in den einzelnen Dokumenten durch eine einzige Kopie ersetzen, die sich in der Sammlung befindet, vorausgesetzt, Sie folgen den Regeln dieser Lizenz für wortwörtliches Kopieren jedes dieser Dokumente in jeglicher Hinsicht.</para>
- <para>
- 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.
- </para>
+ <para>Sie dürfen ein einzelnes Dokument aus einer solchen Sammlung heraustrennen, und es individuell unter dieser Lizenz verteilen, vorausgesetzt, Sie fügen eine Kopie dieser Lizenz in das herausgetrennte Dokument ein und folgen der Lizenz in jeglicher Hinsicht bezüglich dem wortwörtlichen Kopieren des Dokuments.</para>
</sect1>
<sect1 id="fdl-section7">
</legalnotice>
<revhistory>
- <revision><revnumber>1.24.1</revnumber> <date>30. Mai 2015</date> <authorinitials>ss</authorinitials> <revremark>Entwicklerversion</revremark></revision>
+ <revision><revnumber>1.25.1</revnumber> <date>21. März 2016</date> <authorinitials>ss</authorinitials> <revremark>Entwicklerversion</revremark></revision>
+ <revision><revnumber>1.25</revnumber> <date>21. März 2015</date> <authorinitials>ss</authorinitials> <revremark>Fehlerbehebungen, Test-Cleanups</revremark></revision>
<revision><revnumber>1.24</revnumber> <date>29. Mai 2015</date> <authorinitials>sk</authorinitials> <revremark>Fehlerbehebungen</revremark></revision>
<revision><revnumber>1.23</revnumber> <date>17. Mai 2015</date> <authorinitials>sk</authorinitials> <revremark>Fehlerbehebungen</revremark></revision>
<revision><revnumber>1.22</revnumber> <date>7. Mai 2015</date> <authorinitials>sk</authorinitials> <revremark>Fehlerbehebungen, veraltete Funktionen verworfen</revremark></revision>
<year>2009-2013</year>
+ <year>2016</year>
+
<holder>Mario Blättermann</holder>
</copyright>
<year>2015</year>
+ <year>2016</year>
+
+ <year>2017</year>
+
<holder>Christian Kirbach</holder>
</copyright>
</bookinfo>
</listitem>
<listitem>
- <para><guilabel>Erstellen der »Vorlage«-Dateien.</guilabel> <application>gtkdoc-mktmpl</application> erstellt einige Dateien im Unterordner <filename class="directory">tmpl/</filename> mit Hilfe der Informationen aus dem ersten Schritt. (Bedenken Sie, dass dies wiederholt ausgeführt werden kann. Es wird versucht sicherzustellen, dass keine Dokumentation jemals verloren geht.)</para>
- <note>
- <para>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. 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>
- </note>
- </listitem>
-
- <listitem>
- <para>
- <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.
- </para>
- <para>
- <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>.
- </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><guilabel>Erstellen des SGML/XML und HTML/PDF.</guilabel> <application>gtkdoc-mkdb</application> wandelt die Vorlagen-Dateien in XML-Dateien in den Unterordner <filename class="directory">xml/</filename> um. Wenn der Quellcode Dokumentation über Funktionen mittels speziellen Kommentarblöcken enthält, so wird diese hier eingepflegt. Wenn keine tmpl-Dateien eingesetzt werden, so wird nur Dokumentation von den Quell- und introspection-Daten gelesen.</para>
+ <para><application>gtkdoc-mkhtml</application> konvertiert die XML-Dateien in HTML-Dateien im Unterordner <filename class="directory">html/</filename>. Ebenso konvertiert <application>gtkdoc-mkpdf</application> die XML-Dateien in ein PDF-Dokument namens <filename><package>.pdf</filename>.</para>
+ <para>Dateien in <filename class="directory">xml/</filename> und <filename class="directory">html/</filename>-Ordnern werden immer überschrieben. Niemand sollte diese direkt bearbeiten.</para>
</listitem>
<listitem>
<para><guilabel>xsltproc</guilabel> - der xslt-Verarbeiter von libxslt <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink></para>
<para><guilabel>docbook-xsl</guilabel> - die docbook xsl-Stilvorlagen <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink></para>
<para><guilabel>Python</guilabel> - optional - für gtkdoc-depscan</para>
- <para>
- One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> or
- <guilabel>vim</guilabel> - optional - used for syntax highlighting of examples
- </para>
+ <para><guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> oder <guilabel>vim</guilabel> - optional - für Syntax-Hervorhebung von Beispielen</para>
</sect2>
</sect1>
<para>(FIXME)</para>
- <para>
- (History, authors, web pages, mailing list, license, future plans,
- comparison with other similar systems.)
- </para>
+ <para>(Geschichte, Autoren, Webseiten, Mailingliste, Lizenz, Zukunftspläne, Vergleich mit ähnlichen Systemen)</para>
</sect1>
<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>
- <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>
+ <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>
<example><title>Vorbereitung für gtkdocize</title>
</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>
+ <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>
<sect1 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://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>
+ <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>
<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>
<sect1 id="settingup_vcs">
<title>Integration in Versionsverwaltungssysteme</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.
- </para>
+ <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>
<sect1 id="plain_makefiles">
</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[
+ <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.
# to set the CMAKE_INSTALL_DOCDIR variable correctly).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
</sect1>
</chapter>
<note>
<title>Einschränkungen</title>
- <para>
- Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
- <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
- </para>
+ <para>Beachten Sie, dass GTK-Doc zwar <code>#ifndef(__GTK_DOC_IGNORE__)</code> unterstützt, aber nicht <code>#if !defined(__GTK_DOC_IGNORE__)</code> oder andere Kombinationen.</para>
</note>
<!-- -->
<para>Verwenden Sie #Object:property, um auf eine GObject-Eigenschaft zu verweisen.</para>
</listitem>
<listitem>
- <para>
- Use #Struct.field to refer to a field inside a structure and
- #GObjectClass.foo_bar() to refer to a vmethod.
- </para>
+ <para>Verwenden Sie #Struct.field, um auf ein Feld innerhalb einer Struktur zu verweisen und #GObjectClass.foo_bar() für eine vmethod.</para>
</listitem>
</itemizedlist></para>
<para>Falls Sie die Sonderzeichen »<«, »>«, »()«, »@«, »%« oder »#« in Ihrer Dokumentation verwenden wollen, ohne dass GTK-Doc diese ändert, können Sie die XML-Entitäten »&lt;«, »&gt;«, »&lpar;«, »&rpar;«, »&commat;«, »&percnt;« und »&num;« verwenden oder die Zeichen mit einem Backslash »\« maskieren.</para>
</tip>
- <para>
- 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.
- </para>
+ <para>DocBook kann mehr als nur Verweise zu erzeugen. Sie können Listen, Beispiele, Überschriften und Bilder einfügen. In Version 1.20 ist der bevorzugte Weg, ein Subset grundlegender Textformatierungssyntax namens <ulink url="http://daringfireball.net/projects/markdown/">Markdown</ulink> zu verwenden. In älteren Versionen von GTK-Doc wird jede Dokumentation, die Markdown enthält, unverändert gerendert. Zum Beispiel erscheinen Listenobjekte als Zeilen, die mit einem Gedankenstrich beginnen.</para>
- <para>
- 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.
- </para>
+ <para>Wenngleich Markdown bevorzugt wird, können Sie beide Formate mischen. Eine Einschränkung ist jedoch, dass Sie DocBook XML innerhalb von Markdown verwenden können, während Markdown in DocBook XML nicht unterstützt wird.</para>
- <para>
- 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>.
- </para>
+ <para>Um die Nutzung der DocBook-XML-Markierungen innerhalb der Dokumentationskommentare zu aktivieren, übergeben Sie der Variable <symbol>MKDB_OPTIONS</symbol> in der Datei <filename>Makefile.am</filename> die Option <option>--xml-mode</option> (oder <option>--sgml-mode</option>).</para>
<para>
- <example><title>GTK-Doc comment block using Markdown</title>
+ <example><title>GTK-Doc-Kommentarblock in Markdown-Syntax</title>
<programlisting>
/**
* identifier:
</example>
</para>
- <para>
- 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>.
- </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>
<varlistentry>
<term>SECTION:<name></term>
<listitem>
- <para>Der Name verweist auf die Abschnittsdokumentation des entsprechenden Teils der Datei <filename><package>-sections.txt</filename>. Der hier angegebene Name sollte der Markierung <FILE> in der Datei <filename><package>-sections.txt</filename> entsprechen.</para>
+ <para>
+ The name links the section documentation to the respective part in
+ the <filename><package>-sections.txt</filename> file. The
+ name given here should match the <FILE> tag in the
+ <filename><package>-sections.txt</filename> file.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
</varlistentry>
</variablelist>
- <para>
- 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.
- </para>
+ <para>Sie können Stabilitätsinformationen zu allen Dokumentationselementen hinzufügen, um darauf hinzuweisen, ob API-Stabilität für alle Minor-Veröffentlichungen des Projekts garantiert wird.</para>
- <para>
- 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.
- </para>
+ <para>Die Standard-Stabilitätsstufe für alle Dokumentationselemente setzen Sie durch Übergabe des Arguments <option>--default-stability</option> an <application>gtkdoc-mkdb</application> in einem der nachfolgend beschriebenen Werte.</para>
- <variablelist><title>Stability Tags</title>
+ <variablelist><title>Stabilitäts-Markierungen</title>
<varlistentry><term>Stability: Stable</term>
<listitem>
- <para>
- Mark the element as stable. This is for public APIs which are
- guaranteed to remain stable for all future minor releases of the
- project.
- </para>
+ <para>Markiert das Element als stabil. Dies bezieht sich auf öffentliche APIs, für die für alle zukünftigen Minor-Veröffentlichungen des Projekts Stabilität gewährleistet ist.</para>
</listitem>
</varlistentry>
<varlistentry><term>Stability: Unstable</term>
<listitem>
- <para>
- Mark the element as unstable. This is for public APIs which are
- released as a preview before being stabilised.
- </para>
+ <para>Markiert das Element als instabil. Dies bezieht sich auf öffentliche APIs, die als Vorschau vor der endgültigen Stabilisierung gedacht sind.</para>
</listitem>
</varlistentry>
<varlistentry><term>Stability: Private</term>
<listitem>
- <para>
- Mark the element as private. This is for interfaces which can be
- used by tightly coupled modules, but not by arbitrary third
- parties.
- </para>
+ <para>Markiert das Element als privat. Dies bezieht sich auf Schnittstellen, die von eng damit verknüpften Modulen genutzt werden kann, aber nicht von beliebigen Drittanbietern.</para>
</listitem>
</varlistentry>
</variablelist>
<sect2><title>Anmerkungen</title>
- <para>
- 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>.
- </para>
+ <para>Dokumentationsblöcke können Anmerkungs-Markierungen enthalten. Diese Markierungen werden als Tooltips (Minihilfen) dargestellt, die die jeweilige Bedeutung anzeigen. Sie werden von gobject-introspection genutzt, um Sprachbindungen zu erzeugen. Eine detaillierte Liste der unterstützten Markierungen finden Sie im <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">Wiki</ulink>.</para>
<example><title>Anmerkungen</title>
<programlisting>
</programlisting>
</example>
- <variablelist><title>Funktions-Tags</title>
+ <variablelist><title>Funktions-Markierungen</title>
<varlistentry><term>Returns:</term>
<listitem>
<para>Abschnitt, der das zurückgegebene Ergebnis beschreibt.</para>
</varlistentry>
<varlistentry><term>@...:</term>
<listitem>
- <para>
- In case the function has variadic arguments, you should use this
- tag (@Varargs: does also work for historic reasons).
- </para>
+ <para>Wenn die Funktion variadische Argumente enthält, sollten Sie diese Markierung verwenden (@Varargs: funktioniert aus historischen Gründen ebenfalls).</para>
</listitem>
</varlistentry>
</variablelist>
<para>Verwenden Sie <code>/*< private >*/</code> vor den privaten »struct«-Feldern, die Sie verbergen wollen. Um das umgekehrte Verhalten zu erzielen, verwenden Sie <code>/*< public >*/</code>.</para>
- <para>
- 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.
- </para>
+ <para>Wenn das erste Feld »g_iface«, »parent_instance« oder »parent_class« ist, wird es automatisch als privat angesehen und muss nicht im Kommentarblock erwähnt werden.</para>
- <para>
- 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
- vmethods (as this is how they can be documented). For the GObject
- itself one can use the related section docs, having a separate block
- for the instance struct would be useful if the instance has public
- fields. One disadvantage here is that this creates two index entries
- of the same name (the structure and the section).
- </para>
+ <para>Struct-Kommentarblöcke können auch für GObjects und GObjectClasses verwendet werden. Es ist ratsam, einen Kommentarblock für eine Klasse hinzuzufügen, wenn diese vmethods enthält (dies ist die Art der Dokumentation dafür). Für GObject selbst können Sie die jeweiligen Abschnittsdokumentationen verwenden, wobei ein separater Block für das Instanz-Struct sinnvoll ist, sofern die Instanz öffentliche Felder enthält. Ein Nachteil ist hier, dass dadurch zwei gleichnamige Indexeinträge erstellt werden (die Struktur und der Abschnitt).</para>
</sect2>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Eingebettete Programmdokumentation</title>
+ <para>Dokumentieren Sie ein Programm und dessen Befehlszeilen-Schnittstelle mit eingebetteter Dokumentation.</para>
+
+ <variablelist>
+ <title>Schlagwörter</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>Definiert den Start einer Programmdokumentation</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>Definiert eine Kurzbeschreibung des Programms (optional).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>Definiert die Argumente oder eine Liste von Argumenten, die das Programm akzeptiert (optional).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>Der Abschnitt »SEE ALSO« in den man-Pages (Unix-Handbuchseiten, optional).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>Argument(e), die dem Programm übergeben wurden, und die zugehörige Beschreibung (optional).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>Eine ausführlichere Beschreibung des Programms.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Returns:</term>
+ <listitem>
+ <para>Geben Sie an, welche Wert(e) das Programm zurück gibt (optional).</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Beispiel einer Programmdokumentation.</title>
+ <example><title>Programm-Dokumentationsblock</title>
+ <programlisting>
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+</programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
- <title>Nützliche DocBook-Tags</title>
+ <title>Nützliche DocBook-Markierungen</title>
- <para>Nachfolgend finden Sie einige DocBook-Tags, die beim Dokumentieren von Code nützlich sein können.</para>
+ <para>Nachfolgend finden Sie einige DocBook-Markierungen, die beim Dokumentieren von Code nützlich sein können.</para>
<para>So erstellen Sie eine Verknüpfung zu einem anderen Abschnitt in den GTK-Docs: <informalexample>
<programlisting>
</example>
</para>
- <para>
- Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this list for you.
- Just add "--rebuild-types" to SCAN_OPTIONS in <filename>Makefile.am</filename>. If you
- use this approach you should not dist the types file nor have it under version control.
- </para>
+ <para>Seit GTK-Doc 1.8 kann <application>gtkdoc-scan</application> diese Liste für Sie erstellen. Fügen Sie einfach »--rebuild-types« zu SCAN_OPTIONS in <filename>Makefile.am</filename> hinzu. Wenn Sie so vorgehen sollten Sie weder Typen-Datei mit veröffentlichen noch diese unter Versionsverwaltung stellen.</para>
</sect1>
<para>GTK-Doc erstellt die Dokumentation in DocBook-SGML/XML. Beim Verarbeiten der in den Quellcode eingebetteten Kommentare erzeugt GTK-Doc eine Dokumentationsseite pro Klasse oder Modul als separate Datei. Das Hauptdokument schließt diese ein und setzt sie in die passende Reihenfolge.</para>
- <para>
- 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.
- </para>
+ <para>Während GTK-Doc ein Vorlagen-Hauptdokument für Sie erstellt, wird eine spätere Ausführung es nicht mehr verändern. Das bedeutet, dass Sie das Dokument beliebig strukturieren können. Dies schließt Gruppieren von Seiten und Hinzufügen von zusätzlichen Seiten ein. GTK-Doc hat eine neue Test-Suite, wo auch das Hauptdokument von Grund auf neu erstellt wird. Es ist ratsam, sich diese von Zeit zu Zeit anzusehen und zu schauen, ob dort einige Neuigkeiten eingeführt werden.</para>
<tip>
<para>Erstellen Sie keine Schritt-für-Schritt-Anleitungen als zusätzliche Dokumente. Schreiben Sie lediglich zusätzliche Kapitel. Der Vorteil des direkten Einbettens einer Anleitung für Ihre Bibliothek in die API ist die Möglichkeit der einfachen Verknüpfung der Schritt-für-Schritt-Anleitung zur Symboldokumentation. Außerdem sind die Chancen größer, dass die Anleitung die gleichen Aktualisierungen erfährt wie die Bibliothek selbst.</para>
</example>
</para>
+ <para>Zusätzlich werden einige Optionselemente in Kommentarform erstellt. Sie können sich diese anschauen und aktivieren, wenn Sie wollen.</para>
+
<para>
- In addition a few option elements are created in commented form. You can
- review these and enable them as you like.
- </para>
-
- <para>
- <example><title>Optional part in the master document</title>
+ <example><title>Optionaler Teil im Master-Dokument</title>
<programlisting>
- <!-- enable this when you use gobject introspection annotations
+ <!-- aktivieren Sie dieses, wenn sie gobject introspection-Anmerkungen verwenden
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-->
</programlisting>
</example>
</para>
-
- <para>
- 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.
- </para>
+
+ <para>Schlussendlich müssen Sie einen neuen Abschnitt explizit einfügen, sobald Sie einen öffnen. Das Werkzeug <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> erinnert Sie an neu erzeugte XML-Dateien, die in der Dokumentation noch nicht erfasst sind.</para>
<para>
- <example><title>Including generated sections</title>
+ <example><title>Einbeziehen erzeugter Abschnitte</title>
<programlisting>
<chapter>
<title>my library</title>
<para>Die Abschnittsdatei wird verwendet, um die Dokumentations-Ausgaben von GTK-Doc zu organisieren. Man gibt an, welches Symbol zu welchem Modul oder welcher Klasse gehört und regelt die Sichtbarkeit (öffentlich oder privat).</para>
- <para>
- 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.
- </para>
-
+ <para>Die Abschnittsdatei ist eine reine Textdatei mit Markierungen, welche die Abschnitte voneinander trennen. Leere Zeilen werden ignoriert und Zeilen, die mit »#« beginnen, werden als Kommentarzeilen behandelt.</para>
+
<note>
- <para>
- While the tags make the file look like xml, it is not. Please do not
- close tags like <SUBSECTION>.
- </para>
+ <para>Zwar lassen die Markierungen die Datei wie XML erscheinen, doch der Schein trügt. Bitte schließen Sie keine Markierungen wie <SUBSECTION>.</para>
</note>
<para>
- <example><title>Including generated sections</title>
+ <example><title>Einbeziehen erzeugter Abschnitte</title>
<programlisting>
<INCLUDE>libmeep/meep.h</INCLUDE>
</example>
</para>
- <para>
- 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 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).
- </para>
+ <para>Die Markierung <FILE> ... </FILE> wird verwendet, um den Dateinamen ohne Suffix anzugeben. Zum Beispiel wird »<FILE>gnome-config</FILE>« dazu führen, dass der Deklarationsabschnitt in die Vorlage-Datei <filename>tmpl/gnome-config.sgml</filename> ausgegeben wird, welche in die DocBook-XML-Datei <filename>sgml/gnome-config.sgml</filename> oder die DocBook-XML-Datei <filename>xml/gnome-config.xml</filename> umgewandelt wird. (Der Name der HTML-Datei basiert auf dem Modulnamen und dem Abschnittstitel. Für GObject basiert er auf dem GObject-Klassennamen in Kleinbuchstaben).</para>
<para>Das Tag <TITLE> ... </TITLE> wird zur Angabe des Abschnitttitels verwendet. Es ist nur nützlich bevor die Vorlagen (falls verwendet) anfangs erstellt werden, weil der Titel in der Vorlage diesen überschreibt. Wenn man das SECTION-Kommentar in den Quellen einsetzt, ist dies überflüssig.</para>
- <para>
- 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).
- </para>
+ <para>Sie können Objekte im Abschnitt mittels der Markierung <SUBSECTION> gruppieren. Derzeit gibt es eine Leerzeile zwischen Unterabschnitten im Inhaltsangabe-Abschnitt aus. Sie können auch <SUBSECTION Standard> für Standard GObject-Deklarationen verwenden (z.B. Funktionen wie g_object_get_type und Makros wie G_OBJECT(), G_IS_OBJECT() etc.). Derzeit werden diese nicht in die Dokumentation aufgenommen. Sie können auch <SUBSECTION Private> für private Deklarationen verwenden, welche nicht ausgegeben werden. Dies ist eine praktische Möglichkeit, Warnmeldungen bezüglich ungenutzter Deklarationen zu vermeiden. Wenn Ihre Bibliothek private Typen enthält, die nicht in der Objekthierarchie und der Liste der implementierten oder benötigten Schnittstellen erscheinen sollen, fügen Sie diese zu einem »Private«-Unterabschnitt hinzu. Ob Sie GObject oder GObjectClass wie Structs im öffentlichen oder im Standardabschnitt einsetzen, hängt davon ab, ob öffentliche Einträge vorhanden sind (Variablen, vmethods).</para>
<para>Sie können auch <INCLUDE> ... </INCLUDE> verwenden, um die #include-Dateien anzugeben, die in den Abschnitten zur Inhaltsangabe gezeigt werden. Es enthält eine durch Kommata getrennte Liste von #include-Dateien ohne eckige Klammern. Wenn Sie es außerhalb aller Abschnitte festlegen, wirkt es in allen Abschnitten bis zum Dateiende. Wenn Sie es innerhalb eines Abschnitts festlegen, wirkt es nur in diesem Abschnitt.</para>
<para>Man kann sich auch die Dateien ansehen, die durch den Quellcode-Scanner erzeugt wurden: <filename><package>-decl-list.txt</filename> und <filename><package>-decl.txt</filename>. Die erste kann mit der Abschnittsdatei verglichen werden, falls diese händisch verwaltet wird. Die zweite listet alle Deklarationen aus den Kopfdateien. Falls ein Symbol fehlt kann man prüfen, ob diese Datei es enthält.</para>
- <para>
- 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 GTK-Doc to keep the intermediate
- scanner file for further analysis, by running it as
- <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
- </para>
+ <para>Wenn das Projekt auf GObject basiert, kann man auch in die Dateien schauen, die der Objekt-Scanner erzeugt hat: <filename><package>.args.txt</filename>, <filename><package>.hierarchy.txt</filename>, <filename><package>.interfaces.txt</filename>, <filename><package>.prerequisites.txt</filename> und <filename><package>.signals.txt</filename>. Falls in irgendeiner Datei Symbole fehlen, können Sie Gtk-Doc anweisen, die zwischenläufige Scanner-Datei zur weiteren Analyse zu behalten, indem Sie <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command> ausführen.</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Die Dokumentation modernisieren</title>
-
- <para>
- 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.
- </para>
-
+
+ <para>GTK-Doc ist schon seit längerer Zeit verfügbar. In diesem Abschnitt zeigen wir neue Features und die Version, mit der sie eingeführt wurden.</para>
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
- <para>
- When using xml instead of sgml, one can actually name the master
- document <filename><package>-docs.xml</filename>.
- </para>
-
- <para>
- 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>.
- </para>
-
+ <para>Wenn Sie XML anstatt SGML verwenden, können Sie das Hauptdokument <filename><package>-docs.xml</filename> nennen.</para>
+
+ <para>Diese Version unterstützt <option>SCAN_OPTIONS=--rebuild-sections</option> in <filename>Makefile.am</filename>. Wenn dies aktiviert ist, wird die Datei <filename><package>-sections.txt</filename> automatisch erzeugt und kann aus der Versionsverwaltung entfernt werden. Dies funktioniert nur sauber in Projekten, die eine strikt »reguläre« Struktur haben (zum Beispiel erzeugt jedes .{c,h}-Paar einen neuen Abschnitt). In einem solch sauber organisierten Projekt kann dann mit dem Befehl <code>meld <package>-decl-list.txt <package>-sections.txt</code> eine manuell verwaltete Abschnittsdatei sehr einfach aktualisiert werden.</para>
+
<para>
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 you source control system and haven't yet switched, just
+ checked into your source control system and haven't yet switched, just
add the flag to <filename>configure.ac</filename> and you are done.
</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
- <para>
- 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.
- </para>
+ <para>Diese Version unterstützt <option>SCAN_OPTIONS=--rebuild-typess</option> in <filename>Makefile.am</filename>. Wenn dies aktiviert ist, wird die Datei <filename><package>.types</filename> automatisch erzeugt und kann aus der Versionsverwaltung entfernt werden. Dieses Feature erfordert die Einrichtung von <varname>IGNORE_HFILES</varname> in <filename>Makefile.am</filename> für Code, der nur unter bestimmten Bedingungen erstellt werden soll.</para>
</sect1>
<sect1 id="modernizing-gtk-doc-1-16">
<title>GTK-Doc 1.16</title>
- <para>
- 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><title>Enable gtkdoc-check</title>
- <programlisting><![CDATA[
+ <para>Diese Version führt ein neues Werkzeug namens gtkdoc-check ein. Damit können Sie eine Reihe von Plausibilitätsprüfungen auf Ihre Dokumentation anwenden. Um es zu aktivieren, fügen Sie folgende Zeilen am Ende von <filename>Makefile.am</filename> hinzu. <example><title>gtkdoc-check einschalten</title>
+ <programlisting>
if ENABLE_GTK_DOC
TESTS_ENVIRONMENT = \
DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
TESTS = $(GTKDOC_CHECK)
endif
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
</sect1>
<sect1 id="modernizing-gtk-doc-1-20">
<title>GTK-Doc 1.20</title>
- <para>
- 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.
- </para>
+ <para>In Version 1.18 wurde erstmals Unterstützung für Markdown eingeführt. Die Verwendung von Markdown in Dokumentationskommentaren ist weniger aufwändig als das Schreiben von DocBook XML. Diese Version bringt diesbezüglich wesentliche Verbesserungen und fügt zahlreiche weitere Stile hinzu. Alle Details hierzu finden Sie im Abschnitt zur <link linkend="documenting_syntax">Kommentarsyntax</link>.</para>
</sect1>
<sect1 id="modernizing-gtk-doc-1-25">
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 any example that shows how the entity file is included
+ 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.
<sect2 id="commandline-interfaces-file">
<title>Dokumentieren des Werkzeuges</title>
- <para>
- Create one refentry file per tool. Following
- <link linkend="settingup_docfiles">our example</link> we would call it
- <filename>meep/docs/reference/meeper/meep.xml</filename>. For the xml
- tags that should be used and can look at generated file in the xml
- subdirectory as well as examples e.g. in glib.
- </para>
+ <para>Erstellen Sie eine Referenzeintragsdatei pro Werkzeug. In <link linkend="settingup_docfiles">unserem Beispiel</link> nennen wir sie <filename>meep/docs/reference/meeper/meep.xml</filename>. Für die zu verwendenden XML-Markierungen können Sie die generierte Datei im XML-Unterordner oder Beispiele (z.B. in glib) ansehen.</para>
</sect2>
<sect2 id="commandline-interfaces-configure">
<!-- docbook warnings: -->
<seglistitem>
- <seg>multiple "IDs" for constraint linkend: XYZ</seg>
+ <seg>Mehrfache »IDs« für »constraint linkend: XYZ«</seg>
<seg>Das Symbol XYZ erscheint zweifach in der Datei <filename><package>-sections.txt</filename>.</seg>
</seglistitem>
<seglistitem>
- <seg>Element typename in namespace '' encountered in para, but no template matches.</seg>
+ <seg>Element-Typname im Namensraum '' in einem Abschnitt, der keiner Vorlage entspricht.</seg>
<seg/>
</seglistitem>
</segmentedlist>
<title>6. SAMMLUNGEN VON DOKUMENTEN</title>
<para>Sie dürfen eine Sammlung erstellen, die aus dem <link linkend="fdl-document">Dokument</link> und anderen, unter dieser Lizenz veröffentlichten Dokumenten besteht, und die individuellen Kopien der Lizenz in den einzelnen Dokumenten durch eine einzige Kopie ersetzen, die sich in der Sammlung befindet, vorausgesetzt, Sie folgen den Regeln dieser Lizenz für wortwörtliches Kopieren jedes dieser Dokumente in jeglicher Hinsicht.</para>
- <para>
- 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.
- </para>
+ <para>Sie dürfen ein einzelnes Dokument aus einer solchen Sammlung heraustrennen, und es individuell unter dieser Lizenz verteilen, vorausgesetzt, Sie fügen eine Kopie dieser Lizenz in das herausgetrennte Dokument ein und folgen der Lizenz in jeglicher Hinsicht bezüglich dem wortwörtlichen Kopieren des Dokuments.</para>
</sect1>
<sect1 id="fdl-section7">
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc-help.master\n"
-"POT-Creation-Date: 2015-11-19 07:07+0000\n"
-"PO-Revision-Date: 2016-03-14 12:06+0200\n"
+"POT-Creation-Date: 2016-03-21 21:32+0000\n"
+"PO-Revision-Date: 2016-04-10 22:03+0300\n"
"Last-Translator: Tom Tryfonidis <tomtryf@gmail.com>\n"
"Language-Team: team@lists.gnome.gr\n"
"Language: el\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 1.8.7\n"
+"X-Generator: Poedit 1.8.7.1\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.24.1</revnumber> <date>30 May 2015</date> "
+#| "<authorinitials>ss</authorinitials> <revremark>development version</"
+#| "revremark>"
msgid ""
-"<revnumber>1.2
4.1</revnumber> <date>30 May 2015</date> <authorinitials>ss</"
+"<revnumber>1.2
5.1</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>development version</revremark>"
msgstr ""
-"<revnumber>1.24.1</revnumber> <date>30 Μαΐου 2015</date> <authorinitials>ss</"
-"authorinitials> <revremark>έκδοση ανάπτυξης</revremark>"
+"<revnumber>1.25.1</revnumber> <date>21 Μαρτίου 2016</date> "
+"<authorinitials>ss</authorinitials> <revremark>έκδοση ανάπτυξης</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.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
+"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
+msgstr ""
+"<revnumber>1.25</revnumber> <date>21 Μαρτίου 2016</date> <authorinitials>ss</"
+"authorinitials> <revremark>διορθώσεις σφαλμάτων, εκαθάρριση δοκιμαστικού "
+"κώδικα</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>διόρθωση σφαλμάτων</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
msgid ""
"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>διόρθωση σφαλμάτων</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
+#: C/index.docbook:107
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:107
+#: C/index.docbook:113
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:113
+#: C/index.docbook:119
msgid ""
"<revnumber>1.20</revnumber> <date>16 Feb 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, markdown support, style improvements</"
"βελτιώσεις στυλ</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:119
+#: C/index.docbook:125
msgid ""
"<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
"authorinitials> <revremark>διόρθωση σφαλμάτων</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:125
+#: C/index.docbook:131
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:131
+#: C/index.docbook:137
msgid ""
"<revnumber>1.17</revnumber> <date>26 Feb 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>urgent bug fix update</revremark>"
"authorinitials> <revremark>επείγουσα διόρθωση σφάλματος</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:137
+#: C/index.docbook:143
msgid ""
"<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes, layout improvements</revremark>"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:143
+#: C/index.docbook:149
msgid ""
"<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bug and regression fixes</revremark>"
"authorinitials> <revremark>διορθώσεις σφαλμάτων και αναδρομής</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:149
+#: C/index.docbook:155
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:155
+#: C/index.docbook:161
msgid ""
"<revnumber>1.13</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>broken tarball update</"
"συμπιεσμένου αρχείου</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:161
+#: C/index.docbook:167
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:167
+#: C/index.docbook:173
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:180
+#: C/index.docbook:186
msgid "Introduction"
msgstr "Εισαγωγή"
#. (itstool) path: chapter/para
-#: C/index.docbook:182
+#: C/index.docbook:188
msgid ""
"This chapter introduces GTK-Doc and gives an overview of what it is and how "
"it is used."
"και τον τρόπο χρήσης του."
#. (itstool) path: sect1/title
-#: C/index.docbook:188
+#: C/index.docbook:194
msgid "What is GTK-Doc?"
msgstr "Τι είναι το GTK-Doc;"
#. (itstool) path: sect1/para
-#: C/index.docbook:190
+#: C/index.docbook:196
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 "
"εφαρμογών."
#. (itstool) path: sect1/title
-#: C/index.docbook:198
+#: C/index.docbook:204
msgid "How Does GTK-Doc Work?"
msgstr "Πώς λειτουργεί το GTK-Doc;"
#. (itstool) path: sect1/para
-#: C/index.docbook:200
+#: C/index.docbook:206
msgid ""
"GTK-Doc works by using documentation of functions placed inside the source "
"files in specially-formatted comment blocks, or documentation added to the "
"συναρτήσεις)."
#. (itstool) path: sect1/para
-#: C/index.docbook:207
+#: C/index.docbook:213
msgid ""
"GTK-Doc consists of a number of perl scripts, each performing a different "
"step in the process."
"οποία είναι υπεύθυνο για διαφορετικό στάδιο της όλης διαδικασίας."
#. (itstool) path: sect1/para
-#: C/index.docbook:212
+#: C/index.docbook:218
msgid "There are 5 main steps in the process:"
msgstr "Η διαδικασία περιλαμβάνει 5 κύρια στάδια:"
#. (itstool) path: listitem/para
-#: C/index.docbook:219
+#: C/index.docbook:225
msgid ""
"<guilabel>Writing the documentation.</guilabel> The author fills in the "
"source files with the documentation for each function, macro, union etc. (In "
"παράγονταν αυτόματα, αλλά αυτός ο τρόπος δεν συνιστάται πλέον.)"
#. (itstool) path: listitem/para
-#: C/index.docbook:229
+#: C/index.docbook:235
msgid ""
"<guilabel>Gathering information about the code.</guilabel> "
"<application>gtkdoc-scan</application> scans the header files of the code "
"<filename><module>-overrides.txt</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:246
+#: C/index.docbook:252
msgid ""
"<application>gtkdoc-scangobj</application> can also be used to dynamically "
"query a library about any GObject subclasses it exports. It saves "
"ιεραρχία κλάσεων καθώς και για τις ιδιότητες και σήματα GObject που περιέχει."
#. (itstool) path: listitem/para
-#: C/index.docbook:252
+#: C/index.docbook:258
msgid ""
"<application>gtkdoc-scanobj</application> should not be used anymore. It was "
"needed in the past when GObject was still GtkObject inside gtk+."
"gtk+."
#. (itstool) path: listitem/para
-#: C/index.docbook:259
+#: C/index.docbook:265
msgid ""
"<guilabel>Generating the \"template\" files.</guilabel> <application>gtkdoc-"
"mktmpl</application> creates a number of files in the <filename class="
"και κανενός είδους τεκμηρίωση.)"
#. (itstool) path: note/para
-#: C/index.docbook:268
+#: C/index.docbook:274
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 "
"σύστημα ελέγχου εκδόσεων)."
#. (itstool) path: listitem/para
-#: C/index.docbook:280
+#: C/index.docbook:286
msgid ""
"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
"mkdb</application> turns the template files into XML files in the <filename "
"αρχεία tmpl, διαβάζει μόνο έγγραφα από τα δεδομένα πηγών και αυτοελέγχου."
#. (itstool) path: listitem/para
-#: C/index.docbook:289
+#: C/index.docbook:295
msgid ""
"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
"σε ένα έγγραφο PDF που ονομάζεται <filename><package>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:295
+#: C/index.docbook:301
msgid ""
"Files in <filename class=\"directory\">xml/</filename> and <filename class="
"\"directory\">html/</filename> directories are always overwritten. One "
"Επομένως, δεν πρέπει να τα επεξεργάζεστε απευθείας."
#. (itstool) path: listitem/para
-#: C/index.docbook:303
+#: C/index.docbook:309
msgid ""
"<guilabel>Fixing up cross-references between documents.</guilabel> After "
"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
"εγκατεστημένη η τεκμηρίωση)."
#. (itstool) path: sect1/title
-#: C/index.docbook:321
+#: C/index.docbook:327
msgid "Getting GTK-Doc"
msgstr "Λήψη GTK-Doc"
#. (itstool) path: sect2/title
-#: C/index.docbook:324
+#: C/index.docbook:330
msgid "Requirements"
msgstr "Απαιτήσεις"
#. (itstool) path: sect2/para
-#: C/index.docbook:325
+#: C/index.docbook:331
msgid "<guilabel>Perl v5</guilabel> - the main scripts are in Perl."
msgstr ""
"<guilabel>Perl v5</guilabel> - οι κύριες δέσμες ενεργειών είναι γραμμένες σε "
"Perl."
#. (itstool) path: sect2/para
-#: C/index.docbook:328
+#: C/index.docbook:334
msgid ""
"<guilabel>xsltproc</guilabel> - the xslt processor from libxslt <ulink url="
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
"\">xmlsoft.org/XSLT/</ulink>"
#. (itstool) path: sect2/para
-#: C/index.docbook:332
+#: C/index.docbook:338
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:336
+#: C/index.docbook:342
msgid "<guilabel>Python</guilabel> - optional - for gtkdoc-depscan"
msgstr "<guilabel>Python</guilabel> - προαιρετική - για το gtkdoc-depscan"
#. (itstool) path: sect2/para
-#: C/index.docbook:339
+#: C/index.docbook:345
msgid ""
"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
"για την επισήμανση της σύνταξης στα παραδείγματα"
#. (itstool) path: sect1/title
-#: C/index.docbook:347
+#: C/index.docbook:353
msgid "About GTK-Doc"
msgstr "Περί GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:349 C/index.docbook:363
+#: C/index.docbook:355 C/index.docbook:369
msgid "(FIXME)"
msgstr "(ΠΡΟΣ ΔΙΟΡΘΩΣΗ)"
#. (itstool) path: sect1/para
-#: C/index.docbook:353
+#: C/index.docbook:359
msgid ""
"(History, authors, web pages, mailing list, license, future plans, "
"comparison with other similar systems.)"
"σχέδια, σύγκριση με άλλα παρόμοια συστήματα.)"
#. (itstool) path: sect1/title
-#: C/index.docbook:361
+#: C/index.docbook:367
msgid "About this Manual"
msgstr "Περί του εγχειριδίου"
#. (itstool) path: sect1/para
-#: C/index.docbook:367
+#: C/index.docbook:373
msgid "(who it is meant for, where you can get it, license)"
msgstr "(σε ποιους απευθύνεται, πού θα το βρείτε, άδεια)"
#. (itstool) path: chapter/title
-#: C/index.docbook:376
+#: C/index.docbook:382
msgid "Setting up your project"
msgstr "Δημιουργώντας το δικό σας έργο"
#. (itstool) path: chapter/para
-#: C/index.docbook:378
+#: C/index.docbook:384
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'. "
"μια διαφορετική δόμηση ρυθμίσεων."
#. (itstool) path: sect1/title
-#: C/index.docbook:389
+#: C/index.docbook:395
msgid "Setting up a skeleton documentation"
msgstr "Δημιουργία του σκελετού τεκμηρίωσης"
#. (itstool) path: sect1/para
-#: C/index.docbook:391
+#: C/index.docbook:397
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 "
"περιλαμβάνουν μόνο μία βιβλιοθήκη."
#. (itstool) path: example/title
-#: C/index.docbook:400
+#: C/index.docbook:406
msgid "Example directory structure"
msgstr "Παράδειγμα δομής καταλόγου"
#. (itstool) path: example/programlisting
-#: C/index.docbook:401
+#: C/index.docbook:407
#, no-wrap
msgid ""
"\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:398
+#: C/index.docbook:404
msgid "This can then look as shown below: <_:example-1/>"
msgstr "Αυτό θα φαίνεται, λοιπόν, όπως εμφανίζεται παρακάτω: <_:example-1/>"
#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:416 C/index.docbook:423
+#: C/index.docbook:422 C/index.docbook:429
msgid "Integration with autoconf"
msgstr "Ενσωμάτωση στο autoconf"
#. (itstool) path: sect1/para
-#: C/index.docbook:418
+#: C/index.docbook:424
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:424
+#: C/index.docbook:430
#, no-wrap
msgid ""
"\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
#. (itstool) path: example/title
-#: C/index.docbook:436
+#: C/index.docbook:442
msgid "Keep gtk-doc optional"
msgstr "Προαιρετικά διατηρήστε το gtk-doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:437
+#: C/index.docbook:443
#, no-wrap
msgid ""
"\n"
"])\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:431
+#: C/index.docbook:437
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>. <_:example-1/>"
#. (itstool) path: sect1/para
-#: C/index.docbook:448
+#: C/index.docbook:454
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> επίσης προσθέτει αρκετούς διακόπτες ρύθμισης:"
#. (itstool) path: listitem/para
-#: C/index.docbook:454
+#: C/index.docbook:460
msgid "--with-html-dir=PATH : path to installed docs"
msgstr "--with-html-dir= PATH : διαδρομή προς την εγκατεστημένη τεκμηρίωση"
#. (itstool) path: listitem/para
-#: C/index.docbook:455
+#: C/index.docbook:461
msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]"
msgstr ""
"--enable-gtk-doc : χρήση gtk-doc για τη δόμηση τεκμηρίωσης [προεπιλογή=no]"
#. (itstool) path: listitem/para
-#: C/index.docbook:456
+#: C/index.docbook:462
msgid ""
"--enable-gtk-doc-html : build documentation in html format [default=yes]"
msgstr ""
"--enable-gtk-doc-html : δόμηση τεκμηρίωσης σε μορφή html [προεπιλογή=yes]"
#. (itstool) path: listitem/para
-#: C/index.docbook:457
+#: C/index.docbook:463
msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
msgstr "--enable-gtk-doc-pdf : δόμηση τεκμηρίωσης σε μορφή pdf [προεπιλογή=no]"
#. (itstool) path: important/para
-#: C/index.docbook:461
+#: C/index.docbook:467
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"τον προγραμματιστή)."
#. (itstool) path: sect1/para
-#: C/index.docbook:469
+#: C/index.docbook:475
msgid ""
"Furthermore it is recommended that you have the following line inside you "
"<filename>configure.ac</filename> script. This allows "
"<function>GTK_DOC_CHECK</function> στο έργο σας."
#. (itstool) path: example/title
-#: C/index.docbook:477
+#: C/index.docbook:483
msgid "Preparation for gtkdocize"
msgstr "Προετοιμασία για το gtkdocize"
#. (itstool) path: example/programlisting
-#: C/index.docbook:478
+#: C/index.docbook:484
#, no-wrap
msgid ""
"\n"
"AC_CONFIG_MACRO_DIR(m4)\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:483
+#: C/index.docbook:489
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>."
#. (itstool) path: sect1/title
-#: C/index.docbook:491
+#: C/index.docbook:497
msgid "Integration with automake"
msgstr "Ενσωμάτωση στο automake"
#. (itstool) path: sect1/para
-#: C/index.docbook:493
+#: C/index.docbook:499
msgid ""
"First copy the <filename>Makefile.am</filename> from the <filename class="
"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
"επαναλάβετε αυτό το βήμα για το καθένα απο αυτά."
#. (itstool) path: sect1/para
-#: C/index.docbook:504
+#: C/index.docbook:510
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 "
"παραμέτρους."
#. (itstool) path: sect1/title
-#: C/index.docbook:518
+#: C/index.docbook:524
msgid "Integration with autogen"
msgstr "Ενσωμάτωση στο autogen"
#. (itstool) path: sect1/para
-#: C/index.docbook:520
+#: C/index.docbook:526
msgid ""
"Most projects will have an <filename>autogen.sh</filename> script to setup "
"the build infrastructure after a checkout from version control system (such "
"πρέπει να εκτελείται πριν το autoheader, το automake ή το autoconf."
#. (itstool) path: example/title
-#: C/index.docbook:529
+#: C/index.docbook:535
msgid "Running gtkdocize from autogen.sh"
msgstr "Εκτέλεση του gtkdocize από το autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:530
+#: C/index.docbook:536
#, no-wrap
msgid ""
"\n"
"gtkdocize || exit 1\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:536
+#: C/index.docbook:542
msgid ""
"When running <application>gtkdocize</application> it copies <filename>gtk-"
"doc.make</filename> to your project root (or any directory specified by the "
"function>."
#. (itstool) path: sect1/para
-#: C/index.docbook:545
+#: C/index.docbook:551
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:562 C/index.docbook:579
+#: C/index.docbook:568 C/index.docbook:585
msgid "Running the doc build"
msgstr "Εκτέλεση της δόμησης τεκμηρίωσης"
#. (itstool) path: sect1/para
-#: C/index.docbook:564
+#: C/index.docbook:570
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 "
"με αυτή την επιλογή."
#. (itstool) path: sect1/para
-#: C/index.docbook:571
+#: C/index.docbook:577
msgid ""
"The first make run generates several additional files in the doc-"
"directories. The important ones are: <filename><package>.types</"
"παρελθόν .sgml), <filename><package>-sections.txt</filename>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:580
+#: C/index.docbook:586
#, no-wrap
msgid ""
"\n"
"make\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:586
+#: C/index.docbook:592
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, "
"κεφάλαιο θα μάθετε πώς μπορείτε να ζωντανέψετε τις σελίδες σας."
#. (itstool) path: sect1/title
-#: C/index.docbook:594
+#: C/index.docbook:600
msgid "Integration with version control systems"
msgstr "Ενσωμάτωση σε συστήματα ελέγχου εκδόσεων"
#. (itstool) path: sect1/para
-#: C/index.docbook:596
+#: C/index.docbook:602
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:604
+#: C/index.docbook:610
msgid ""
"Files in the <filename>xml/</filename> and <filename>html/</filename> "
"directories should not go under version control. Neither should any of the "
"<filename>xml/</filename> and <filename>html/</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:612
+#: C/index.docbook:618
msgid "Integration with plain makefiles or other build systems"
msgstr "Ενσωμάτωση στα αρχεία makefiles ή άλλα συστήματα δόμησης"
#. (itstool) path: sect1/para
-#: C/index.docbook:614
+#: C/index.docbook:620
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 στη σωστή σειρά στα makefiles (ή άλλα εργαλεία δόμησης)."
#. (itstool) path: example/title
-#: C/index.docbook:621
+#: C/index.docbook:627
msgid "Documentation build steps"
msgstr "Βήματα δόμησης τεκμηρίωσης"
#. (itstool) path: example/programlisting
-#: C/index.docbook:622
+#: C/index.docbook:628
#, no-wrap
msgid ""
"\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:636
+#: C/index.docbook:642
msgid ""
"One will need to look at the <filename>Makefile.am</filename> and "
"<filename>gtk-doc.mak</filename> to pick the extra options needed."
"χρειάζονται."
#. (itstool) path: sect1/title
-#: C/index.docbook:643
+#: C/index.docbook:649
msgid "Integration with CMake build systems"
msgstr "Ενσωμάτωση με συστήματα δόμησης CMake"
#. (itstool) path: sect1/para
-#: C/index.docbook:645
+#: C/index.docbook:651
msgid ""
"GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module (and "
"the corresponding <filename>GtkDocConfigVersion.cmake</filename> module). "
"μπορείτε να ορίσετε στο αρχείο <filename>CMakeLists.txt</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:655
+#: C/index.docbook:661
msgid "Example of using GTK-Doc from CMake"
msgstr "Παράδειγμα χρήσης του GTK-Doc από το CMake"
#. (itstool) path: example/programlisting
-#: C/index.docbook:656
+#: C/index.docbook:662
#, no-wrap
msgid ""
"\n"
" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:653
+#: C/index.docbook:659
msgid "The following example shows how to use this command. <_:example-1/>"
msgstr ""
"Το ακόλουθο παράδειγμα δείχνει πως να χρησιμοποιήσετε την εντολή. <_:"
"example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:681
+#: C/index.docbook:687
msgid "Documenting the code"
msgstr "Τεκμηρίωση κώδικα"
#. (itstool) path: chapter/para
-#: C/index.docbook:683
+#: C/index.docbook:689
msgid ""
"GTK-Doc uses source code comment with a special syntax for code "
"documentation. Further it retrieves information about your project structure "
"λεπτομέρειες για τη σύνταξη αυτών των σχολίων."
#. (itstool) path: note/title
-#: C/index.docbook:691
+#: C/index.docbook:697
msgid "Documentation placement"
msgstr "Τοποθέτηση τεκμηρίωσης"
#. (itstool) path: note/para
-#: C/index.docbook:692
+#: C/index.docbook:698
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 "
"συγκρούσεις με τα συστήματα ελέγχου εκδόσεων."
#. (itstool) path: note/para
-#: C/index.docbook:698
+#: C/index.docbook:704
msgid ""
"The avoid the aforementioned problems we suggest putting the documentation "
"inside the sources. This manual will only describe this way of documenting "
"περιγράψουμε σε αυτό το εγχειρίδιο."
#. (itstool) path: example/title
-#: C/index.docbook:709 C/index.docbook:735
+#: C/index.docbook:715 C/index.docbook:741
msgid "GTK-Doc comment block"
msgstr "Μπλοκ σχολίου GTK-Doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:710
+#: C/index.docbook:716
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:705
+#: C/index.docbook:711
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 "
"παραλείψει. <_:example-1/>"
#. (itstool) path: note/title
-#: C/index.docbook:719
+#: C/index.docbook:725
msgid "Limitations"
msgstr "Περιορισμοί"
#. (itstool) path: note/para
-#: C/index.docbook:720
+#: C/index.docbook:726
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."
"συνδυασμούς."
#. (itstool) path: sect1/title
-#: C/index.docbook:730
+#: C/index.docbook:736
msgid "Documentation comments"
msgstr "Σχόλια τεκμηρίωσης"
#. (itstool) path: example/programlisting
-#: C/index.docbook:736
+#: C/index.docbook:742
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:732
+#: C/index.docbook:738
msgid ""
"A multiline comment that starts with an additional '*' marks a documentation "
"block that will be processed by the GTK-Doc tools. <_:example-1/>"
"Doc. <_:example-1/>"
#. (itstool) path: sect1/para
-#: C/index.docbook:745
+#: C/index.docbook:751
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 "
"στοιχείου. (ΜΕΛΛΟΝΤΙΚΑ: να προστεθεί πίνακας με τα αναγνωριστικά)"
#. (itstool) path: sect1/para
-#: C/index.docbook:751
+#: C/index.docbook:757
msgid ""
"The 'documentation' block is also different for each symbol type. Symbol "
"types that get parameters such as functions or macros have the parameter "
"κώδικα)."
#. (itstool) path: listitem/para
-#: C/index.docbook:768
+#: C/index.docbook:774
msgid ""
"What it is: The name for a class or function can sometimes be misleading for "
"people coming from a different background."
"παραπλανητικό για ανθρώπους που δεν έχουν τεχνογνωσία στο θέμα."
#. (itstool) path: listitem/para
-#: C/index.docbook:774
+#: C/index.docbook:780
msgid ""
"What it does: Tell about common uses. Put it in relation with the other API."
msgstr ""
"Τι κάνει: Αναφέρει τις κοινές χρήσεις και τις βάζει σε σχέση με άλλο API."
#. (itstool) path: tip/para
-#: C/index.docbook:764
+#: C/index.docbook:770
msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>"
msgstr "Όταν τεκμηριώνετε κώδικα, περιγράψτε δύο πλευρές: <_:itemizedlist-1/>"
#. (itstool) path: listitem/para
-#: C/index.docbook:789
+#: C/index.docbook:795
msgid "Use function() to refer to functions or macros which take arguments."
msgstr ""
"Χρησιμοποιήστε το function() για να αναφερθείτε σε συναρτήσεις ή "
"μακροεντολές που δέχονται ορίσματα."
#. (itstool) path: listitem/para
-#: C/index.docbook:794
+#: C/index.docbook:800
msgid ""
"Use @param to refer to parameters. Also use this when referring to "
"parameters of other functions, related to the one being described."
"συναρτήσεων, σχετικών με την περιγραφόμενη."
#. (itstool) path: listitem/para
-#: C/index.docbook:800
+#: C/index.docbook:806
msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS."
msgstr ""
"Χρησιμοποιήστε το %constant για να αναφερθείτε σε σταθερές, π.χ. "
"%G_TRAVERSE_LEAFS."
#. (itstool) path: listitem/para
-#: C/index.docbook:805
+#: C/index.docbook:811
msgid ""
"Use #symbol to refer to other types of symbol, e.g. structs and enums and "
"macros which don't take arguments."
"δομές, αριθμήσεις και μακροεντολές που δε δέχονται ορίσματα."
#. (itstool) path: listitem/para
-#: C/index.docbook:811
+#: C/index.docbook:817
msgid "Use #Object::signal to refer to a GObject signal."
msgstr ""
"Χρησιμοποιήστε το #Object::signal για να αναφερθείτε σε ένα σήμα GObject."
#. (itstool) path: listitem/para
-#: C/index.docbook:816
+#: C/index.docbook:822
msgid "Use #Object:property to refer to a GObject property."
msgstr ""
"Χρησιμοποιήστε το #Object::property για να αναφερθείτε σε μία ιδιότητα "
"GObject."
#. (itstool) path: listitem/para
-#: C/index.docbook:821
+#: C/index.docbook:827
msgid ""
"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
"foo_bar() to refer to a vmethod."
"δομή και #GObjectClass.foo_bar() για να αναφερθείτε σε μια vmethod."
#. (itstool) path: sect1/para
-#: C/index.docbook:783
+#: C/index.docbook:789
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:830
+#: C/index.docbook:836
msgid ""
"If you need to use the special characters '<', '>', '()', '@', '%', or "
"'#' in your documentation without GTK-Doc changing them you can use the XML "
"διαφυγής."
#. (itstool) path: sect1/para
-#: C/index.docbook:839
+#: C/index.docbook:845
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 "
"εμφανίζονται σαν γραμμές που αρχίζουν με μια παύλα."
#. (itstool) path: sect1/para
-#: C/index.docbook:850
+#: C/index.docbook:856
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 "
"υποστηρίζεται."
#. (itstool) path: sect1/para
-#: C/index.docbook:856
+#: C/index.docbook:862
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:865
+#: C/index.docbook:871
msgid "GTK-Doc comment block using Markdown"
msgstr "Μπλοκ σχολίου GTK-Doc χρησιμοποιώντας Markdown"
#. (itstool) path: example/programlisting
-#: C/index.docbook:866
+#: C/index.docbook:872
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:905
+#: C/index.docbook:911
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"
"Reference</ulink>."
#. (itstool) path: tip/para
-#: C/index.docbook:911
+#: C/index.docbook:917
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 "
"να εισαχθεί το όνομα του συμβόλου στην κατάλληλη θέση του αρχείου ενοτήτων."
#. (itstool) path: sect1/title
-#: C/index.docbook:925
+#: C/index.docbook:931
msgid "Documenting sections"
msgstr "Τεκμηρίωση ενοτήτων"
#. (itstool) path: sect1/para
-#: C/index.docbook:927
+#: C/index.docbook:933
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 "
"περιεχομένων. Όλα τα πεδία @fields είναι προαιρετικά."
#. (itstool) path: example/title
-#: C/index.docbook:935
+#: C/index.docbook:941
msgid "Section comment block"
msgstr "Μπλοκ σχολίου ενότητας"
#. (itstool) path: example/programlisting
-#: C/index.docbook:936
+#: C/index.docbook:942
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:955
+#: C/index.docbook:961
msgid "SECTION:<name>"
msgstr "SECTION:<name>"
#. (itstool) path: listitem/para
-#: C/index.docbook:957
+#: C/index.docbook:963
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>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:966
+#: C/index.docbook:972
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:968
+#: C/index.docbook:974
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."
"της ενότητας."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:975
+#: C/index.docbook:981
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:977
+#: C/index.docbook:983
msgid ""
"The section title defaults to <name> from the SECTION declaration. It "
"can be overridden with the @title field."
"SECTION. Μπορεί να παρακαμφθεί με το πεδίο @title."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:984
+#: C/index.docbook:990
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:986
+#: C/index.docbook:992
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:994
+#: C/index.docbook:1000
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:996
+#: C/index.docbook:1002
msgid "A list of symbols that are related to this section."
msgstr "Λίστα συμβόλων σχετικών με αυτή την ενότητα."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1002
+#: C/index.docbook:1008
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1009
+#: C/index.docbook:1015
msgid ""
"Stable - The intention of a Stable interface is to enable arbitrary third "
"parties to develop applications to these interfaces, release them, and have "
"λόγους."
#. (itstool) path: listitem/para
-#: C/index.docbook:1021
+#: C/index.docbook:1027
msgid ""
"Unstable - Unstable interfaces are experimental or transitional. They are "
"typically used to give outside developers early access to new or rapidly "
"συμβατότητας μεταξύ μιας ελάσσονας έκδοσης και της επόμενης."
#. (itstool) path: listitem/para
-#: C/index.docbook:1033
+#: C/index.docbook:1039
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 "
"σαφώς καθορισμένων και τεκμηριωμένων διαδικασιών."
#. (itstool) path: listitem/para
-#: C/index.docbook:1042
+#: C/index.docbook:1048
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 "
"περιέχουν τεκμηρίωση εκλαμβάνονται ως εσωτερικές."
#. (itstool) path: listitem/para
-#: C/index.docbook:1004
+#: C/index.docbook:1010
msgid ""
"An informal description of the stability level this API has. We recommend "
"the use of one of these terms: <_:itemizedlist-1/>"
"συνιστούμε τη χρήση ενός από τους ακόλουθους όρους: <_:itemizedlist-1/>"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1054
+#: C/index.docbook:1060
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1056
+#: C/index.docbook:1062
msgid ""
"The <literal>#include</literal> files to show in the section synopsis (a "
"comma separated list), overriding the global value from the <link linkend="
"link> ή στη γραμμή εντολών. Πρόκειται για προαιρετικό στοιχείο."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1065
+#: C/index.docbook:1071
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1067
+#: C/index.docbook:1073
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 "
"καταχώρηση είναι προαιρετική."
#. (itstool) path: tip/para
-#: C/index.docbook:1078
+#: C/index.docbook:1084
msgid ""
"To avoid unnecessary recompilation after doc-changes put the section docs "
"into the c-source where possible."
"αρχείο του πηγαίου κώδικα, όπου αυτό είναι δυνατό."
#. (itstool) path: sect1/title
-#: C/index.docbook:1087
+#: C/index.docbook:1093
msgid "Documenting symbols"
msgstr "Τεκμηρίωση συμβόλων"
#. (itstool) path: sect1/para
-#: C/index.docbook:1089
+#: C/index.docbook:1095
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:1097 C/index.docbook:1163
+#: C/index.docbook:1103 C/index.docbook:1169
msgid "General tags"
msgstr "Γενικές ετικέτες"
#. (itstool) path: sect2/para
-#: C/index.docbook:1099
+#: C/index.docbook:1105
msgid ""
"You can add versioning information to all documentation elements to tell "
"when an API was introduced, or when it was deprecated."
"τεκμηρίωσης για να πείτε πότε εισήχθηκε ένα API, ή πότε καταργήθηκε."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1104
+#: C/index.docbook:1110
msgid "Versioning Tags"
msgstr "Εκδόσεις Ετικετών"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1105
+#: C/index.docbook:1111
msgid "Since:"
msgstr "Από:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1107
+#: C/index.docbook:1113
msgid "Description since which version of the code the API is available."
msgstr "Περιγραφή οπό ποια έκδοση του κώδικα και μετά είναι διαθέσιμο το API."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1112
+#: C/index.docbook:1118
msgid "Deprecated:"
msgstr "Παρωχημένη:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1114
+#: C/index.docbook:1120
msgid ""
"Paragraph denoting that this function should no be used anymore. The "
"description should point the reader to the new API."
"συνάρτησης. Η περιγραφή θα πρέπει να παραπέμπει τον αναγνώστη στο νέο API."
#. (itstool) path: sect2/para
-#: C/index.docbook:1122
+#: C/index.docbook:1128
msgid ""
"You can also add stability information to all documentation elements to "
"indicate whether API stability is guaranteed for them for all future minor "
"για όλες τις μελλοντικές δευτερεύουσες εκδόσεις του έργου."
#. (itstool) path: sect2/para
-#: C/index.docbook:1128
+#: C/index.docbook:1134
msgid ""
"The default stability level for all documentation elements can be set by "
"passing the <option>--default-stability</option> argument to "
"τιμές."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1134
+#: C/index.docbook:1140
msgid "Stability Tags"
msgstr "Ετικέτες σταθερότητας"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1135
+#: C/index.docbook:1141
msgid "Stability: Stable"
msgstr "Σταθερότητα: σταθερό"
#. (itstool) path: listitem/para
-#: C/index.docbook:1137
+#: C/index.docbook:1143
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."
"εκδόσεις του έργου."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1144
+#: C/index.docbook:1150
msgid "Stability: Unstable"
msgstr "Σταθερότητα: ασταθές"
#. (itstool) path: listitem/para
-#: C/index.docbook:1146
+#: C/index.docbook:1152
msgid ""
"Mark the element as unstable. This is for public APIs which are released as "
"a preview before being stabilised."
"εκδίδονται ως μια προεπισκόπηση πριν να σταθεροποιηθούν."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1152
+#: C/index.docbook:1158
msgid "Stability: Private"
msgstr "Σταθερότητα: προσωπική"
#. (itstool) path: listitem/para
-#: C/index.docbook:1154
+#: C/index.docbook:1160
msgid ""
"Mark the element as private. This is for interfaces which can be used by "
"tightly coupled modules, but not by arbitrary third parties."
"μέρη."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1164
+#: C/index.docbook:1170
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1184 C/index.docbook:1194
+#: C/index.docbook:1190 C/index.docbook:1200
msgid "Annotations"
msgstr "Σχόλια"
#. (itstool) path: sect2/para
-#: C/index.docbook:1186
+#: C/index.docbook:1192
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"Annotations\" type=\"http\">η βίκι</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1195
+#: C/index.docbook:1201
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1216 C/index.docbook:1245
+#: C/index.docbook:1222 C/index.docbook:1251
msgid "Function comment block"
msgstr "Ομάδα σχολίων συνάρτησης"
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1228
msgid ""
"Document whether returned objects, lists, strings, etc, should be freed/"
"unrefed/released."
"λπ, θα πρέπει να ελευθερώνονται, να μην ελευθερώνονται ή να απορρίπτονται."
#. (itstool) path: listitem/para
-#: C/index.docbook:1228
+#: C/index.docbook:1234
msgid "Document whether parameters can be NULL, and what happens if they are."
msgstr ""
"Τεκμηριώσετε κατά πόσο οι παράμετροι μπορούν να είναι μηδενικές (NULL) και "
"τι συμβαίνει αν είναι."
#. (itstool) path: listitem/para
-#: C/index.docbook:1233
+#: C/index.docbook:1239
msgid ""
"Mention interesting pre-conditions and post-conditions where appropriate."
msgstr ""
"Αναφέρετε ενδιαφέρουσες προ-καταστάσεις και μετα-καταστάσεις όπου χρειάζεται."
#. (itstool) path: sect2/para
-#: C/index.docbook:1218 C/index.docbook:1304
+#: C/index.docbook:1224 C/index.docbook:1310
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Παρακαλούμε να θυμηθείτε να: <_:itemizedlist-1/>"
#. (itstool) path: sect2/para
-#: C/index.docbook:1240
+#: C/index.docbook:1246
msgid ""
"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
"private. They are treated like static functions."
"συναρτήσεις."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1246
+#: C/index.docbook:1252
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1267
+#: C/index.docbook:1273
msgid "Function tags"
msgstr "Ετικέτες συναρτήσεων"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1268
+#: C/index.docbook:1274
msgid "Returns:"
msgstr "Επιστροφές:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1270
+#: C/index.docbook:1276
msgid "Paragraph describing the returned result."
msgstr "Παράγραφος που περιγράφει το επιστρεφόμενο αποτέλεσμα."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1275
+#: C/index.docbook:1281
msgid "@...:"
msgstr "@...:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1277
+#: C/index.docbook:1283
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:1287 C/index.docbook:1289
+#: C/index.docbook:1293 C/index.docbook:1295
msgid "Property comment block"
msgstr "Ομάδα σχολίων ιδιότητας"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1290
+#: C/index.docbook:1296
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1302 C/index.docbook:1321
+#: C/index.docbook:1308 C/index.docbook:1327
msgid "Signal comment block"
msgstr "Ομάδα σχολίων σήματος"
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1314
msgid ""
"Document when the signal is emitted and whether it is emitted before or "
"after other signals."
"άλλα σήματα."
#. (itstool) path: listitem/para
-#: C/index.docbook:1314
+#: C/index.docbook:1320
msgid "Document what an application might do in the signal handler."
msgstr "Τεκμηριώστε τι μπορεί να κάνει μια εφαρμογή στον διαχειριστή σημάτων."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1322
+#: C/index.docbook:1328
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1339 C/index.docbook:1340
+#: C/index.docbook:1345 C/index.docbook:1346
msgid "Struct comment block"
msgstr "Ομάδα σχολίων δομής"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1341
+#: C/index.docbook:1347
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1362
msgid ""
"Use <code>/*< private >*/</code> before the private struct fields you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"public >*/</code>για την αντίστροφη συμπεριφορά."
#. (itstool) path: sect2/para
-#: C/index.docbook:1362
+#: C/index.docbook:1368
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 "
"των σχολίων."
#. (itstool) path: sect2/para
-#: C/index.docbook:1368
+#: C/index.docbook:1374
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:1380 C/index.docbook:1381
+#: C/index.docbook:1386 C/index.docbook:1387
msgid "Enum comment block"
msgstr "Ομάδα σχολίων Enum"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1382
+#: C/index.docbook:1388
#, no-wrap
msgid ""
"\n"
"} Something;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1399
+#: C/index.docbook:1405
msgid ""
"Use <code>/*< private >*/</code> before the private enum values you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
">*/</code> για την αντίστροφη συμπεριφορά."
#. (itstool) path: sect1/title
-#: C/index.docbook:1409
+#: C/index.docbook:1415
msgid "Useful DocBook tags"
msgstr "Χρήσιμες ετικέτες DocBook"
#. (itstool) path: sect1/para
-#: C/index.docbook:1411
+#: C/index.docbook:1417
msgid ""
"Here are some DocBook tags which are most useful when documenting the code."
msgstr ""
"του κώδικα."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1420
+#: C/index.docbook:1426
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1416
+#: C/index.docbook:1422
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. "
"υπάρχει συμμόρφωση με το SGML/XML."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1433
+#: C/index.docbook:1439
#, no-wrap
msgid ""
"\n"
"<function>...</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1430
+#: C/index.docbook:1436
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
"informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1442
+#: C/index.docbook:1448
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1453
+#: C/index.docbook:1459
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1439
+#: C/index.docbook:1445
msgid ""
"To include example code: <_:informalexample-1/> or possibly this, for very "
"short code fragments which don't need a title: <_:informalexample-2/> For "
"τελευταία περίπτωση το GTK-Doc υποστηρίζει επίσης μια συντόμευση: |[ ... ]|"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1472
+#: C/index.docbook:1478
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1469
+#: C/index.docbook:1475
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Συμπερίληψη λιστών με κουκκίδες: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1492
+#: C/index.docbook:1498
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1489
+#: C/index.docbook:1495
msgid ""
"To include a note which stands out from the text: <_:informalexample-1/>"
msgstr ""
"informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1505
+#: C/index.docbook:1511
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1502
+#: C/index.docbook:1508
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "Για να αναφερθείτε σε έναν τύπο: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1514
+#: C/index.docbook:1520
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1511
+#: C/index.docbook:1517
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:1523
+#: C/index.docbook:1529
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1520
+#: C/index.docbook:1526
msgid "To refer to a field of a structure: <_:informalexample-1/>"
msgstr "Για να αναφερθείτε σε ένα πεδίο μιας δομής: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1532
+#: C/index.docbook:1538
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1529
+#: C/index.docbook:1535
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 "
"linkend=\"documenting_syntax\">τις συντομεύσεις</link>)."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1543
+#: C/index.docbook:1549
#, no-wrap
msgid ""
"\n"
"<emphasis>This is important</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1540
+#: C/index.docbook:1546
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Χρήση έντονων χαρακτήρων: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1552
+#: C/index.docbook:1558
#, no-wrap
msgid ""
"\n"
"<filename>/home/user/documents</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1549
+#: C/index.docbook:1555
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Για ονόματα αρχείων χρησιμοποιήστε: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1561
+#: C/index.docbook:1567
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1558
+#: C/index.docbook:1564
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "Για να αναφερθείτε σε κλειδιά χρησιμοποιήστε: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1571
+#: C/index.docbook:1577
msgid "Filling the extra files"
msgstr "Συμπλήρωση των επιπλέον αρχείων"
#. (itstool) path: chapter/para
-#: C/index.docbook:1573
+#: C/index.docbook:1579
msgid ""
"There are a couple of extra files, that need to be maintained along with the "
"inline source code comments: <filename><package>.types</filename>, "
"sgml), <filename><package>-sections.txt</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1582
+#: C/index.docbook:1588
msgid "Editing the types file"
msgstr "Επεξεργασία του αρχείου types"
#. (itstool) path: sect1/para
-#: C/index.docbook:1584
+#: C/index.docbook:1590
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><package>.types</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:1593
+#: C/index.docbook:1599
msgid "Example types file snippet"
msgstr "Υπόδειγμα αποσπάσματος αρχείου types"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1594
+#: C/index.docbook:1600
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1605
+#: C/index.docbook:1611
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"types ούτε στη διανομή ούτε στον έλεγχο εκδόσεων."
#. (itstool) path: sect1/title
-#: C/index.docbook:1614
+#: C/index.docbook:1620
msgid "Editing the master document"
msgstr "Επεξεργασία κύριου εγγράφου (master)"
#. (itstool) path: sect1/para
-#: C/index.docbook:1616
+#: C/index.docbook:1622
msgid ""
"GTK-Doc produces documentation in DocBook SGML/XML. When processing the "
"inline source comments, the GTK-Doc tools generate one documentation page "
"ταξινομεί."
#. (itstool) path: sect1/para
-#: C/index.docbook:1623
+#: C/index.docbook:1629
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 "
"νέα καλούδια που εισήχθησαν εκεί."
#. (itstool) path: tip/para
-#: C/index.docbook:1633
+#: C/index.docbook:1639
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 "
"καθίσταται πιθανότερη η ενημέρωση του εγχειριδίου μαζί με τη βιβλιοθήκη."
#. (itstool) path: sect1/para
-#: C/index.docbook:1642
+#: C/index.docbook:1648
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 "
"αγκυλών) που πρέπει να διευκρινήσετε."
#. (itstool) path: example/title
-#: C/index.docbook:1649
+#: C/index.docbook:1655
msgid "Master document header"
msgstr "Κεφαλίδα κύριου εγγράφου"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1650
+#: C/index.docbook:1656
#, no-wrap
msgid ""
"\n"
" <title>[Insert title here]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1666
+#: C/index.docbook:1672
msgid ""
"In addition a few option elements are created in commented form. You can "
"review these and enable them as you like."
"να τα ελέγξετε και να τα ενεργοποιήσετε όπως θέλετε."
#. (itstool) path: example/title
-#: C/index.docbook:1672
+#: C/index.docbook:1678
msgid "Optional part in the master document"
msgstr "Προαιρετικό τμήμα στο κύριο έγγραφο"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1673
+#: C/index.docbook:1679
#, no-wrap
msgid ""
"\n"
" --> \n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1681
+#: C/index.docbook:1687
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 "
"έγγραφο."
#. (itstool) path: example/title
-#: C/index.docbook:1689 C/index.docbook:1724
+#: C/index.docbook:1695 C/index.docbook:1730
msgid "Including generated sections"
msgstr "Συμπερίληψη των δημιουργούμενων ενοτήτων"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1690
+#: C/index.docbook:1696
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1702
+#: C/index.docbook:1708
msgid "Editing the section file"
msgstr "Επεξεργασία αρχείου ενοτήτων"
#. (itstool) path: sect1/para
-#: C/index.docbook:1704
+#: C/index.docbook:1710
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 "
"σύμβολο και αποφασίζεται η ορατότητά του (αν θα είναι δημόσιο ή ιδιωτικό)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1710
+#: C/index.docbook:1716
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."
"αντιμετωπίζονται ως γραμμές σχολίων."
#. (itstool) path: note/para
-#: C/index.docbook:1717
+#: C/index.docbook:1723
msgid ""
"While the tags make the file look like xml, it is not. Please do not close "
"tags like <SUBSECTION>."
"είναι. Παρακαλούμε μην κλείνετε τις ετικέτες όπως <SUBSECTION>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1725
+#: C/index.docbook:1731
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1742
+#: C/index.docbook:1748
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"κλάσης GObjects που μετατράπηκε σε πεζά γράμματα)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1754
+#: C/index.docbook:1760
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 "
"αυτό είναι παρωχημένο."
#. (itstool) path: sect1/para
-#: C/index.docbook:1761
+#: C/index.docbook:1767
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"(μεταβλητές,vmethods)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1780
+#: C/index.docbook:1786
msgid ""
"You can also use <INCLUDE> ... </INCLUDE> to specify the "
"#include files which are shown in the synopsis sections. It contains a comma-"
"μόνο τη συγκεκριμένη ενότητα. "
#. (itstool) path: chapter/title
-#: C/index.docbook:1794
+#: C/index.docbook:1800
msgid "Controlling the result"
msgstr "Έλεγχος αποτελέσματος"
#. (itstool) path: chapter/para
-#: C/index.docbook:1796
+#: C/index.docbook:1802
msgid ""
"A GTK-Doc run generates report files inside the documentation directory. The "
"generated files are named: <filename><package>-undocumented.txt</"
"filename>. Είναι αρχεία απλού κειμένου, εύκολα στην ανάγνωση και επεξεργασία."
#. (itstool) path: chapter/para
-#: C/index.docbook:1805
+#: C/index.docbook:1811
msgid ""
"The <filename><package>-undocumented.txt</filename> file starts with "
"the documentation coverage summary. Below are two sections divided by blank "
"προστέθηκε μια νέα παράμετρος."
#. (itstool) path: chapter/para
-#: C/index.docbook:1814
+#: C/index.docbook:1820
msgid ""
"The <filename><package>-undeclared.txt</filename> file lists symbols "
"given in the <filename><package>-sections.txt</filename> but not found "
"έχουν αφαιρεθεί ή αν περιέχουν συντακτικά λάθη."
#. (itstool) path: chapter/para
-#: C/index.docbook:1821
+#: C/index.docbook:1827
msgid ""
"The <filename><package>-unused.txt</filename> file lists symbol names, "
"where the GTK-Doc scanner has found documentation, but does not know where "
"προστεθεί ακόμη στο αρχείο <filename><package>-sections.txt</filename>."
#. (itstool) path: tip/para
-#: C/index.docbook:1829
+#: C/index.docbook:1835
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 "
"<command>make check</command>."
#. (itstool) path: chapter/para
-#: C/index.docbook:1836
+#: C/index.docbook:1842
msgid ""
"One can also look at the files produced by the source code scanner: "
"<filename><package>-decl-list.txt</filename> and <filename><"
"περιέχεται σε αυτό το αρχείο."
#. (itstool) path: chapter/para
-#: C/index.docbook:1845
+#: C/index.docbook:1851
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:1860
+#: C/index.docbook:1866
msgid "Modernizing the documentation"
msgstr "Εκσυγχρονίζοντας την τεκμηρίωση"
#. (itstool) path: chapter/para
-#: C/index.docbook:1862
+#: C/index.docbook:1868
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."
"διαθέσιμες."
#. (itstool) path: sect1/title
-#: C/index.docbook:1868
+#: C/index.docbook:1874
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1870
+#: C/index.docbook:1876
msgid ""
"When using xml instead of sgml, one can actually name the master document "
"<filename><package>-docs.xml</filename>."
"το κύριο έγγραφο <filename><package>-docs.xml</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1875
+#: C/index.docbook:1881
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-sections</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"sections.txt</code>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1886
+#: C/index.docbook:1892
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"filename> και τελειώσατε."
#. (itstool) path: sect1/title
-#: C/index.docbook:1898
+#: C/index.docbook:1904
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:1900
+#: C/index.docbook:1906
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"am</filename> για τον κώδικα που δομείται υπό όρους."
#. (itstool) path: sect1/title
-#: C/index.docbook:1911
+#: C/index.docbook:1917
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:1917
+#: C/index.docbook:1923
msgid "Enable gtkdoc-check"
msgstr "Ενεργοποίηση του gtkdoc-check"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1918
+#: C/index.docbook:1924
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1913
+#: C/index.docbook:1919
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>. <_:example-1/>"
#. (itstool) path: sect1/title
-#: C/index.docbook:1931
+#: C/index.docbook:1937
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:1933
+#: C/index.docbook:1939
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 "
"\">σύνταξη σχολίων</link> έχει όλες τις λεπτομέρειες."
#. (itstool) path: sect1/title
-#: C/index.docbook:1943
+#: C/index.docbook:1949
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:1953
+#: C/index.docbook:1959
msgid "Use pre-generated entities"
msgstr "Χρήση προδημιουργημένων οντοτήτων"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1954
+#: C/index.docbook:1960
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1945
+#: C/index.docbook:1951
msgid ""
"The makefiles shipped with this version generate an entity file at "
"<filename>xml/gtkdocentities.ent</filename>, containing entities for e.g. "
"xml σε όλα τα δημιουργημένα αρχεία xml. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1979
+#: C/index.docbook:1985
msgid "Documenting other interfaces"
msgstr "Τεκμηρίωση άλλων διεπαφών"
#. (itstool) path: chapter/para
-#: C/index.docbook:1981
+#: C/index.docbook:1987
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 "
"μπορούν να χρησιμοποιηθούν για να καταγράφετε και άλλες διεπαφές."
#. (itstool) path: sect1/title
-#: C/index.docbook:1988
+#: C/index.docbook:1994
msgid "Command line options and man pages"
msgstr "Επιλογές γραμμής εντολών και σελίδες τεκμηρίωσης man"
#. (itstool) path: sect1/para
-#: C/index.docbook:1990
+#: C/index.docbook:1996
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 "
"δωρεάν την σελίδα-man."
#. (itstool) path: sect2/title
-#: C/index.docbook:1997
+#: C/index.docbook:2003
msgid "Document the tool"
msgstr "Τεκμηρίωση του εργαλείου"
#. (itstool) path: sect2/para
-#: C/index.docbook:1999
+#: C/index.docbook:2005
msgid ""
"Create one refentry file per tool. Following <link linkend="
"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
"αρχείο στον υποκατάλογο xml καθώς επίσης και τα παραδείγματα π.χ. στο glib."
#. (itstool) path: sect2/title
-#: C/index.docbook:2009
+#: C/index.docbook:2015
msgid "Adding the extra configure check"
msgstr "Προσθήκη του έξτρα ελέγχου διαμόρφωσης"
#. (itstool) path: example/title
-#: C/index.docbook:2012 C/index.docbook:2030
+#: C/index.docbook:2018 C/index.docbook:2036
msgid "Extra configure checks"
msgstr "Επιπλέον έλεγχοι ρυθμίσεων"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2013
+#: C/index.docbook:2019
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2027
+#: C/index.docbook:2033
msgid "Adding the extra makefile rules"
msgstr "Προσθήκη των επιπλέον κανόνων makefile"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2031
+#: C/index.docbook:2037
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2053
+#: C/index.docbook:2059
msgid "DBus interfaces"
msgstr "Διεπαφές DBus"
#. (itstool) path: sect1/para
-#: C/index.docbook:2055
+#: C/index.docbook:2061
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:2064
+#: C/index.docbook:2070
msgid "Frequently asked questions"
msgstr "Συχνές ερωτήσεις"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2068
+#: C/index.docbook:2074
msgid "Question"
msgstr "Ερώτηση"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2069
+#: C/index.docbook:2075
msgid "Answer"
msgstr "Απάντηση"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2071
+#: C/index.docbook:2077
msgid "No class hierarchy."
msgstr "Δεν υπάρχει ιεραρχία κλάσεων."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2072
+#: C/index.docbook:2078
msgid ""
"The objects <function>xxx_get_type()</function> function has not been "
"entered into the <filename><package>.types</filename> file."
"εισαχθεί στο αρχείο <filename><package>.types</filename>"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2078
+#: C/index.docbook:2084
msgid "Still no class hierarchy."
msgstr "Εξακολουθεί να μην υπάρχει ιεραρχία κλάσεων."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2079
+#: C/index.docbook:2085
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\">αιτιολόγηση</ulink>)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2085
+#: C/index.docbook:2091
msgid "Damn, I have still no class hierarchy."
msgstr "Στο καλό του, πάλι δεν έχω ιεραρχία κλάσεων."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2086
+#: C/index.docbook:2092
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:2093
+#: C/index.docbook:2099
msgid "No symbol index."
msgstr "Δεν υπάρχει ευρετήριο συμβόλων."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2094
+#: C/index.docbook:2100
msgid ""
"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
"index that xi:includes the generated index?"
"ευρετήριο το οποίο περιλαμβάνει με xi:includes το παραγόμενο ευρετήριο;"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2100
+#: C/index.docbook:2106
msgid "Symbols are not linked to their doc-section."
msgstr ""
"Δεν υπάρχουν σύνδεσμοι μεταξύ των συμβόλων και των κατάλληλων ενοτήτων της "
"τεκμηρίωσης."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2101
+#: C/index.docbook:2107
msgid ""
"Is the doc-comment using the correct markup (added #,% or ())? Check if the "
"gtkdoc-fixxref warns about unresolvable xrefs."
"()); Ελέγξτε αν το gtkdoc-fixxref προειδοποιεί για ανεπίλυτα xrefs."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2107
+#: C/index.docbook:2113
msgid "A new class does not appear in the docs."
msgstr "Μια νέα κλάση δεν εμφανίζεται στην τεκμηρίωση."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2108
+#: C/index.docbook:2114
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:2114
+#: C/index.docbook:2120
msgid "A new symbol does not appear in the docs."
msgstr "Ένα νέο σύμβολο δεν εμφανίζεται στην τεκμηρίωση."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2115
+#: C/index.docbook:2121
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> σε μια δημόσια υποενότητα."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2123
+#: C/index.docbook:2129
msgid "A type is missing from the class hierarchy."
msgstr "Λείπει ένας τύπος από την ιεραρχία κλάσεων."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2124
+#: C/index.docbook:2130
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 "
"εμφανιστεί."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2133
+#: C/index.docbook:2139
msgid "I get foldoc links for all gobject annotations."
msgstr "Λαμβάνω συνδέσμους foldoc για όλες τις σημειώσεις gobject."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2134
+#: C/index.docbook:2140
msgid ""
"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
"from <filename><package>-docs.{xml,sgml}</filename>."
"included από το <filename><package>-docs.{xml,sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2142
+#: C/index.docbook:2148
msgid "Parameter described in source code comment block but does not exist"
msgstr ""
"Μια παράμετρος περιγράφεται σε σχόλιο του πηγαίου κώδικα, αλλά δεν υπάρχει"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2143
+#: C/index.docbook:2149
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
"παράμετρο από αυτό που αναφέρεται στον κώδικα."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2148
+#: C/index.docbook:2154
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "Πολλαπλά \"Αναγνωριστικά\" για τον προορισμό συνδέσμου: XYZ"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2149
+#: C/index.docbook:2155
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"sections.txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2152
+#: C/index.docbook:2158
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"αντιστοιχεί σε κανένα πρότυπο."
#. (itstool) path: chapter/title
-#: C/index.docbook:2159
+#: C/index.docbook:2165
msgid "Tools related to gtk-doc"
msgstr "Εργαλεία σχετικά με το gtk-doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2161
+#: C/index.docbook:2167
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 "
"ιστοσελίδες trac και ενσωματώνεται με την αναζήτηση trac."
#. (itstool) path: chapter/para
-#: C/index.docbook:2166
+#: C/index.docbook:2172
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."
</legalnotice>
<revhistory>
- <revision><revnumber>1.24.1</revnumber> <date>30 Μαΐου 2015</date> <authorinitials>ss</authorinitials> <revremark>έκδοση ανάπτυξης</revremark></revision>
+ <revision><revnumber>1.25.1</revnumber> <date>21 Μαρτίου 2016</date> <authorinitials>ss</authorinitials> <revremark>έκδοση ανάπτυξης</revremark></revision>
+ <revision><revnumber>1.25</revnumber> <date>21 Μαρτίου 2016</date> <authorinitials>ss</authorinitials> <revremark>διορθώσεις σφαλμάτων, εκαθάρριση δοκιμαστικού κώδικα</revremark></revision>
<revision><revnumber>1.24</revnumber> <date>29 Μαΐου 2015</date> <authorinitials>ss</authorinitials> <revremark>διόρθωση σφαλμάτων</revremark></revision>
<revision><revnumber>1.23</revnumber> <date>17 Μαΐου 2015</date> <authorinitials>ss</authorinitials> <revremark>διόρθωση σφαλμάτων</revremark></revision>
<revision><revnumber>1.22</revnumber> <date>07 Μαΐου 2015</date> <authorinitials>ss</authorinitials> <revremark>διορθώσεις σφαλμάτων, απόρριψη παρωχημένων λειτουργιών</revremark></revision>
</othercredit>
<copyright>
- <year>2009-2015</year>
+ <year>2009-2016</year>
<holder>Ελληνική μεταφραστική ομάδα GNOME</holder>
</copyright>
<personname>
<firstname>Θάνος Τρυφωνίδης</firstname>
</personname>
- <email>tomtryf@gmail.com</email>
+ <email>tomtryf@gnome.org</email>
</othercredit>
<copyright>
<year>2015</year>
+ <year>2016</year>
+
<holder>Θάνος Τρυφωνίδης</holder>
</copyright>
<para>Το <application>gtkdoc-scanobj</application> δεν πρέπει να χρησιμοποιείται πλέον. Χρειαζόταν στο παρελθόν όταν το GObject ήταν ακόμα GtkObject μέσα στη gtk+.</para>
</listitem>
- <listitem>
- <para><guilabel>Δημιουργία "πρότυπων" αρχείων</guilabel> Το <application>gtkdoc-mktmpl</application> παράγει μια σειρά από αρχεία στον υποκατάλογο <filename class="directory">tmpl/</filename>, χρησιμοποιώντας τις πληροφορίες που συλλέχθηκαν κατά το πρώτο στάδιο. (Σημειώστε ότι μπορεί να εκτελεσθεί περισσότερες από μία φορές. Προσπαθεί να διασφαλίσει ότι δεν χάνεται ποτέ και κανενός είδους τεκμηρίωση.)</para>
- <note>
- <para>Από την έκδοση GTK-Doc 1.9 και μετά, τα πρότυπα αρχεία δεν είναι πλέον απαραίτητα. Σας συνιστούμε να διατηρείτε την τεκμηρίωση στον κώδικα. Το <application>gtkdocize</application> υποστηρίζει πλέον την επιλογή <option>--flavour no-tmpl</option> η οποία επιλέγει ένα αρχείο makefile που δεν χρησιμοποιεί καθόλου πρότυπα tmpl. Αν δεν έχετε κάνει ποτέ αλλαγές με το χέρι σε αρχεία προτύπων tmpl, παρακαλώ αφαιρέστε τον κατάλογο (π.χ. από ένα σύστημα ελέγχου εκδόσεων).</para>
- </note>
- </listitem>
-
<listitem>
<para><guilabel>Δημιουργία του XML και του HTML/PDF</guilabel>. Το <application>gtkdoc-mkdb</application> μετατρέπει τα αρχεία προτύπων σε αρχεία XML στον υποκατάλογο <filename class="directory">xml/</filename>. Αν ο πηγαίος κώδικας περιέχει τεκμηρίωση συναρτήσεων, χρησιμοποιώντας τις ειδικές ομάδες σχολίων, συγχωνεύεται εδώ. Αν δεν υπάρχουν χρησιμοποιούμενα αρχεία tmpl, διαβάζει μόνο έγγραφα από τα δεδομένα πηγών και αυτοελέγχου.</para>
<para>Το <application>gtkdoc-mkhtml</application> μετατρέπει τα αρχεία XML σε αρχεία HTML στον υποκατάλογο <filename class="directory">html/</filename>. Ομοίως, το <application>gtkdoc-mkpdf</application> μετατρέπει τα αρχεία XML σε ένα έγγραφο PDF που ονομάζεται <filename><package>.pdf</filename>.</para>
<para>Το GTK-Doc είναι απενεργοποιημένο από προεπιλογή! Να θυμάστε να χρησιμοποιείτε την επιλογή <option>'--enable-gtk-doc'</option> στην επόμενη εκτέλεση του <filename>configure</filename>. Διαφορετικά, εγκαθίσταται η προπαραχθείσα τεκμηρίωση (δυνατότητα χρήσιμη για τον χρήστη, αλλά όχι για τον προγραμματιστή).</para>
</important>
- <para>Επίσης, συνιστάται να προσθέσετε την ακόλουθη γραμμή στη δέσμη ενεργειών <filename>configure.ac</filename>. Αυτό επιτρέπει στο <filename>gtkdocize</filename> να αντιγράφει αυτόματα τον ορισμό της μακροεντολής για το <function>GTK_DOC_CHECK</function> στο έργο σας.</para>
+ <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>
<example><title>Προετοιμασία για το gtkdocize</title>
</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[
+ <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.
# to set the CMAKE_INSTALL_DOCDIR variable correctly).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
DESTINATION ${CMAKE_INSTALL_DOCDIR})
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
</sect1>
</chapter>
<varlistentry>
<term>SECTION:<name></term>
<listitem>
- <para>Το name συνδέει την τεκμηρίωση της ενότητας με το αντίστοιχο μέρος στο αρχείο <filename><package>-sections.txt</filename>. Το όνομα που δίνεται εδώ πρέπει να ταιριάζει με την ετικέτα <FILE> στο αρχείο <filename><package>-sections.txt</filename>.</para>
+ <para>
+ The name links the section documentation to the respective part in
+ the <filename><package>-sections.txt</filename> file. The
+ name given here should match the <FILE> tag in the
+ <filename><package>-sections.txt</filename> file.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Inline program documentation</title>
+ <para>
+ You can document programs and their commandline interface using inline
+ documentation.
+ </para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>
+ Defines the start of a program documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>
+ Defines a short description of the program. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>
+ Defines the arguments, or list of arguments that the program can take.
+ (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>
+ See Also manual page section. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>
+ Argument(s) passed to the program and their description. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ A longer description of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Επιστροφές:</term>
+ <listitem>
+ <para>
+ Specificy what value(s) the program returns. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Example of program documentation.</title>
+ <example><title>Program documentation block</title>
+ <programlisting><![CDATA[
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+]]></programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>Χρήσιμες ετικέτες DocBook</title>
</para>
<para>Επιπλέον κάποια στοιχεία επιλογής δημιουργούνται με μορφή σχολίου. Μπορείτε να τα ελέγξετε και να τα ενεργοποιήσετε όπως θέλετε.</para>
-
+
<para>
<example><title>Προαιρετικό τμήμα στο κύριο έγγραφο</title>
- <programlisting>
- <!-- ενεργοποιήστε το όταν χρησιμοποιείτε σχόλια αυτοελέγχου gobject
- <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
-</programlisting>
+ <programlisting><![CDATA[
+ <!-- enable this when you use gobject introspection annotations
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+ -->
+]]></programlisting>
</example>
</para>
-
+
<para>Τέλος, χρειάζεται να προσθέσετε νέα ενότητα όποτε εισάγετε μία. Το εργαλείο <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> θα σας θυμίσει τα νεοδημιουργούμενα αρχεία xml που δεν περιλαμβάνονται ακόμα στο έγγραφο.</para>
<para>
<para>Το αρχείο ενοτήτων χρησιμεύει στην οργάνωση της τεκμηρίωσης που παράγεται από το GTK-Doc. Εδώ διευκρινίζεται σε ποιο άρθρωμα ή κλάση ανήκει κάθε σύμβολο και αποφασίζεται η ορατότητά του (αν θα είναι δημόσιο ή ιδιωτικό).</para>
<para>Το αρχείο ενοτήτων είναι ένα αρχείο απλού κειμένου με ετικέτες οριοθετημένων περιοχών. Οι κενές γραμμές αγνοούνται, ενώ οι γραμμές που ξεκινούν με '#' αντιμετωπίζονται ως γραμμές σχολίων.</para>
-
+
<note>
<para>Ενώ οι ετικέτες δείχνουν πως είναι ένα αρχείο xml, στην πραγματικότητα δεν είναι. Παρακαλούμε μην κλείνετε τις ετικέτες όπως <SUBSECTION>.</para>
</note>
<para>Αν το έργο βασίζεται στο GObject, μπορείτε επίσης να δείτε τα αρχεία που παράγονται από το σαρωτή αντικειμένων: <filename><package>.args.txt</filename>, <filename><package>.hierarchy.txt</filename>, <filename><package>.interfaces.txt</filename>, <filename><package>.prerequisites.txt</filename> και <filename><package>.signals.txt</filename>. Αν υπάρχουν σύμβολα που λείπουν από οποιοδήποτε από αυτά, μπορείτε να ζητήσετε από το gtkdoc να κρατήσει το ενδιάμεσο αρχείο σάρωσης για περαιτέρω ανάλυση, εκτελώντας το ως μια εντολή <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Εκσυγχρονίζοντας την τεκμηρίωση</title>
-
+
<para>Το GTK-Doc κυκλοφορεί εδώ και αρκετό καιρό. Σε αυτό το κεφάλαιο θα παραθέσουμε τις νέες λειτουργίες μαζί με την έκδοση στην οποία είναι διαθέσιμες.</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
<para>Όταν χρησιμοποιείτε το xml αντί για το sgml, μπορείτε πράγματι να ονομάσετε το κύριο έγγραφο <filename><package>-docs.xml</filename>.</para>
-
+
<para>Αυτή η έκδοση υποστηρίζει <option>SCAN_OPTIONS=--rebuild-sections</option> στο <filename>Makefile.am</filename>. Αν αυτό ενεργοποιηθεί, το <filename><package>-sections.txt</filename> αυτοδημιουργείται και μπορεί να αφαιρεθεί από το vcs. Αυτό λειτουργεί καλά μόνο για έργα που έχουν μια πολύ κανονική δομή (π.χ. το κάθε ζεύγος .{c,h} θα δημιουργεί μια νέα ενότητα). Αν κάποιος οργανώσει ένα έργο κοντά σε αυτό, τότε η ενημέρωση μιας ενότητας αρχείων που συντηρούνται χειρονακτικά μπορεί να είναι τόσο απλή όσο και το να εκτελούμε <code>meld <package>-decl-list.txt <package>-sections.txt</code>.</para>
-
- <para>Η εκδοση 1.8 εισήγαγε ήδη τη σύνταξη για τις ενότητες τεκμηρίωσης στις πηγές, αντί για τα ξεχωριστά αρχεία, κάτω από το <filename class="directory">tmpl</filename>. Αυτή η έκδοση προσθέτει επιλογές για τη μετατροπή ολόκληρου του αρθρώματος doc ώστε να μη χρησιμοποιεί καθόλου το επιπλέον στάδιο δόμησης tmpl, με τη χρήση του <option>--flavour no-tmpl</option> στο <filename>configure.ac</filename>. Εάν δεν έχετε ένα <filename class="directory">tmpl</filename> σημειωμένο στο σύστημα ελέγχου πηγής και δεν έχετε ακόμα αλλάξει, προσθέστε απλά τη σημαία στο <filename>configure.ac</filename> και τελειώσατε.</para>
+
+ <para>
+ 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.
+ </para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
<sect1 id="modernizing-gtk-doc-1-25">
<title>GTK-Doc 1.25</title>
- <para>Τα αρχεία makefiles που έρχονται με αυτή την έκδοση παράγουν ένα αρχείο οντοτήτων στο <filename>xml/gtkdocentities.ent</filename>, το οποίο περιλαμβάνει οντότητες π.χ. package_name και package_version. Μπορείτε να το χρησιμοποιήσετε π.χ. στο κύριο αρχείο xml για να αποφύγετε τον στατικό ορισμό του αριθμού έκδοσης. Παρακάτω είναι ένα παράδειγμα που σας δείχνει πως συμπεριλαμβάνεται το αρχείο οντοτήτων και πως οι οντότητες χρησιμοποιούνται. Οι οντότητες μπορούν να χρησιμοποιηθούν και σε όλα τα δημιουργημένα αρχεία, καθώς το GTK-Doc θα χρησιμοποιήσει την ίδια κεφαλίδα xml σε όλα τα δημιουργημένα αρχεία xml. <example><title>Χρήση προδημιουργημένων οντοτήτων</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
+ 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>
<revhistory>
<revision>
- <revnumber>1.24.1</revnumber>
- <date>30 May 2015</date>
+ <revnumber>1.25.1</revnumber>
+ <date>21 March 2016</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development version</revremark>
+ </revision>
+ <revision>
+ <revnumber>1.25</revnumber>
+ <date>21 March 2016</date>
<authorinitials>ss</authorinitials>
- <revremark>development version</revremark>
+ <revremark>bug fixes, test cleanups</revremark>
</revision>
<revision>
<revnumber>1.24</revnumber>
</para>
</listitem>
- <listitem>
- <para>
- <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.)
- </para>
- <note>
- <para>
- 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).
- </para>
- </note>
- </listitem>
-
<listitem>
<para>
<guilabel>Generating the XML and HTML/PDF.</guilabel>
document called <filename><package>.pdf</filename>.
</para>
<para>
- Files in <filename class="directory">xml/</filename> and
+ 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>
Furthermore it is recommended that you have the following line inside
- you <filename>configure.ac</filename> script.
+ 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>
<title>Integration with automake</title>
<para>
- First copy the <filename>Makefile.am</filename> from the
+ 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.
+ 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>
<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.
+ hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<title>Limitations</title>
<para>
Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
+ <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
<code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
</para>
</note>
<para>
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>
+ 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>.
</para>
<para>
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
+ name given here should match the <FILE> tag in the
<filename><package>-sections.txt</filename> file.
</para>
</listitem>
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
+ of the supported tags can be found on
<ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
</para>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Inline program documentation</title>
+ <para>
+ You can document programs and their commandline interface using inline
+ documentation.
+ </para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>
+ Defines the start of a program documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>
+ Defines a short description of the program. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>
+ Defines the arguments, or list of arguments that the program can take.
+ (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>
+ See Also manual page section. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>
+ Argument(s) passed to the program and their description. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ A longer description of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Returns:</term>
+ <listitem>
+ <para>
+ Specificy what value(s) the program returns. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Example of program documentation.</title>
+ <example><title>Program documentation block</title>
+ <programlisting><![CDATA[
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+]]></programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>Useful DocBook tags</title>
In addition a few option elements are created in commented form. You can
review these and enable them as you like.
</para>
-
+
<para>
<example><title>Optional part in the master document</title>
<programlisting><![CDATA[
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
+ -->
]]></programlisting>
</example>
</para>
-
+
<para>
Finally you need to add new section whenever you introduce one. The
<link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
Blank lines are ignored and lines starting with a '#' are treated as
comment lines.
</para>
-
+
<note>
<para>
While the tags make the file look like xml, it is not. Please do not
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizing the documentation</title>
-
+
<para>
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.
</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
When using xml instead of sgml, one can actually name the master
document <filename><package>-docs.xml</filename>.
</para>
-
+
<para>
This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
in <filename>Makefile.am</filename>. When this is enabled, the
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
+ maintained section file can be as simple as running
<code>meld <package>-decl-list.txt <package>-sections.txt</code>.
</para>
-
+
<para>
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 you source control system and haven't yet switched, just
+ checked into your source control system and haven't yet switched, just
add the flag to <filename>configure.ac</filename> and you are done.
</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
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 any example that shows how the entity file is included
+ 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.
# Jorge Gonzalez <jorgegonz@svn.gnome.org>, 2009.\r
# Jorge González <jorgegonz@svn.gnome.org>, 2009, 2010, 2011.\r
# \r
-# Daniel Mustieles <daniel.mustieles@gmail.com>, 2011, 2012, 2013, 2014, 2015.\r, 2015.
+# Daniel Mustieles <daniel.mustieles@gmail.com>, 2011, 2012, 2013, 2014, 2015.\r, 2016, 2017.
#
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc-help.master\n"
-"POT-Creation-Date: 2015-11-19 07:07+0000\n"
-"PO-Revision-Date: 2015-11-23 10:31+0100\n"
+"POT-Creation-Date: 2017-04-23 16:21+0000\n"
+"PO-Revision-Date: 2017-07-25 10:11+0200\n"
"Last-Translator: Daniel Mustieles <daniel.mustieles@gmail.com>\n"
-"Language-Team: Español; Castellano <gnome-es-list@gnome.org>\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"
msgctxt "_"
msgid "translator-credits"
msgstr ""
-"Daniel Mustieles <daniel.mustieles@gmail.com>, 2009 - 2015\n"
+"Daniel Mustieles <daniel.mustieles@gmail.com>, 2009 - 2017\n"
"Jorge González <jorgegonz@svn.gnome.org>, 2009 - 2011\n"
"Francisco Javier F. Serrador <serrrador@svn.gnome.org>, 2009, 2010"
#. (itstool) path: revhistory/revision
#: C/index.docbook:83
msgid ""
-"<revnumber>1.2
4.1</revnumber> <date>30 May 2015</date> <authorinitials>ss</"
+"<revnumber>1.2
5.1</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>development version</revremark>"
msgstr ""
-"<revnumber>1.24.1</revnumber> <date>30 de mayo de 2015</date> "
+"<revnumber>1.25.1</revnumber> <date>21 de mayo de 2016</date> "
"<authorinitials>ss</authorinitials> <revremark>versión de desarrollo</"
"revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
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 de marzo de 2016</date> "
+"<authorinitials>ss</authorinitials> <revremark>correcciones de errores, "
+"limpieza</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
msgstr ""
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
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:101
+#: C/index.docbook:107
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:107
+#: C/index.docbook:113
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:113
+#: C/index.docbook:119
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:119
+#: C/index.docbook:125
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:125
+#: C/index.docbook:131
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:131
+#: C/index.docbook:137
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:137
+#: C/index.docbook:143
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:143
+#: C/index.docbook:149
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:149
+#: C/index.docbook:155
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:155
+#: C/index.docbook:161
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:161
+#: C/index.docbook:167
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:167
+#: C/index.docbook:173
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:180
+#: C/index.docbook:186
msgid "Introduction"
msgstr "Introducción"
#. (itstool) path: chapter/para
-#: C/index.docbook:182
+#: C/index.docbook:188
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:188
+#: C/index.docbook:194
msgid "What is GTK-Doc?"
msgstr "¿Qué es GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:190
+#: C/index.docbook:196
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:198
+#: C/index.docbook:204
msgid "How Does GTK-Doc Work?"
msgstr "¿Cómo funciona GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:200
+#: C/index.docbook:206
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:207
+#: C/index.docbook:213
msgid ""
"GTK-Doc consists of a number of perl scripts, each performing a different "
"step in the process."
"diferente en el proceso."
#. (itstool) path: sect1/para
-#: C/index.docbook:212
+#: C/index.docbook:218
msgid "There are 5 main steps in the process:"
msgstr "Existen 5 pasos importantes en el proceso:"
#. (itstool) path: listitem/para
-#: C/index.docbook:219
+#: C/index.docbook:225
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:229
+#: C/index.docbook:235
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:246
+#: C/index.docbook:252
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:252
+#: C/index.docbook:258
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:259
-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>Generar los archivos «plantilla».</guilabel> <application>gtkdoc-"
-"mktmpl</application> crea un número de archivos en la subcarpeta <filename "
-"class=\"directory\">tmpl/</filename>, usando la información obtenida en el "
-"primer paso. (Tenga en cuenta que esto se puede ejecutar de forma separada. "
-"Intentará asegurarse de que la documentación nunca se pierde.)"
-
-#. (itstool) path: note/para
-#: C/index.docbook:268
-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 ""
-"Desde de GTK-Doc 1.9 se pueden evitar las plantillas. Animamos a la gente a "
-"que mantenga la documentación en el código. <application>gtkdocize</"
-"application> ahora soporta una opción <command>--flavour no-tmpl</command> "
-"que elige un archivo makefile que omite completamente el uso de tmpl. Si "
-"nunca ha cambiado a mano el archivo tmpl, elimine la carpeta una vez (por "
-"ejemplo, desde el sistema de control de versiones)."
-
-#. (itstool) path: listitem/para
-#: C/index.docbook:280
+#: C/index.docbook:265
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:289
+#: C/index.docbook:274
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:295
+#: C/index.docbook:280
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:303
+#: C/index.docbook:288
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:321
+#: C/index.docbook:306
msgid "Getting GTK-Doc"
msgstr "Obtener GTK-Doc"
#. (itstool) path: sect2/title
-#: C/index.docbook:324
+#: C/index.docbook:309
msgid "Requirements"
msgstr "Requerimientos"
#. (itstool) path: sect2/para
-#: C/index.docbook:325
+#: C/index.docbook:310
msgid "<guilabel>Perl v5</guilabel> - the main scripts are in Perl."
msgstr "<guilabel>Perl v5</guilabel>: los scripts principales están en Perl."
#. (itstool) path: sect2/para
-#: C/index.docbook:328
+#: C/index.docbook:313
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:332
+#: C/index.docbook:317
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:336
+#: C/index.docbook:321
msgid "<guilabel>Python</guilabel> - optional - for gtkdoc-depscan"
msgstr "<guilabel>Python</guilabel>: opcional, para gtkdoc-depscan"
#. (itstool) path: sect2/para
-#: C/index.docbook:339
+#: C/index.docbook:324
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:347
+#: C/index.docbook:332
msgid "About GTK-Doc"
msgstr "Acerca de GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:349 C/index.docbook:363
+#: C/index.docbook:334 C/index.docbook:348
msgid "(FIXME)"
msgstr "(ARRÉGLAME)"
#. (itstool) path: sect1/para
-#: C/index.docbook:353
+#: C/index.docbook:338
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:361
+#: C/index.docbook:346
msgid "About this Manual"
msgstr "Acerca de este manual"
#. (itstool) path: sect1/para
-#: C/index.docbook:367
+#: C/index.docbook:352
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:376
+#: C/index.docbook:361
msgid "Setting up your project"
msgstr "Configurando su proyecto"
#. (itstool) path: chapter/para
-#: C/index.docbook:378
+#: C/index.docbook:363
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:389
+#: C/index.docbook:374
msgid "Setting up a skeleton documentation"
msgstr "Configurar el esquema de la documentación"
#. (itstool) path: sect1/para
-#: C/index.docbook:391
+#: C/index.docbook:376
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:400
+#: C/index.docbook:385
msgid "Example directory structure"
msgstr "Ejemplo de estructura de carpetas"
#. (itstool) path: example/programlisting
-#: C/index.docbook:401
+#: C/index.docbook:386
#, no-wrap
msgid ""
"\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:398
+#: C/index.docbook:383
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:416 C/index.docbook:423
+#: C/index.docbook:401 C/index.docbook:408
msgid "Integration with autoconf"
msgstr "Integración con autoconf"
#. (itstool) path: sect1/para
-#: C/index.docbook:418
+#: C/index.docbook:403
msgid ""
"Very easy! Just add one line to your <filename>configure.ac</filename> "
"script."
"filename>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:424
+#: C/index.docbook:409
#, no-wrap
msgid ""
"\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
#. (itstool) path: example/title
-#: C/index.docbook:436
+#: C/index.docbook:421
msgid "Keep gtk-doc optional"
msgstr "Mantener gtk-doc como opcional"
#. (itstool) path: example/programlisting
-#: C/index.docbook:437
+#: C/index.docbook:422
#, no-wrap
msgid ""
"\n"
"])\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:431
+#: C/index.docbook:416
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:448
+#: C/index.docbook:433
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:454
+#: C/index.docbook:439
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:455
+#: C/index.docbook:440
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:456
+#: C/index.docbook:441
msgid ""
"--enable-gtk-doc-html : build documentation in html format [default=yes]"
msgstr ""
"[predeterminado=sí]"
#. (itstool) path: listitem/para
-#: C/index.docbook:457
+#: C/index.docbook:442
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:461
+#: C/index.docbook:446
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:469
+#: C/index.docbook:454
+#| 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."
msgstr ""
"Aún más, se recomienda que tenga la siguiente línea en su script "
-"<filename>configure.ac</filename>. Esto permite que <filename>gtkdocize</"
-"filename> copie automáticamente la definición del macro para "
+"<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."
#. (itstool) path: example/title
-#: C/index.docbook:477
+#: C/index.docbook:462
msgid "Preparation for gtkdocize"
msgstr "Preparación para gtkdocize"
#. (itstool) path: example/programlisting
-#: C/index.docbook:478
+#: C/index.docbook:463
#, no-wrap
msgid ""
"\n"
"AC_CONFIG_MACRO_DIR(m4)\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:483
+#: C/index.docbook:468
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:491
+#: C/index.docbook:476
msgid "Integration with automake"
msgstr "Integración con automake"
#. (itstool) path: sect1/para
-#: C/index.docbook:493
+#: C/index.docbook:478
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:504
+#: C/index.docbook:489
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:518
+#: C/index.docbook:503
msgid "Integration with autogen"
msgstr "Integración con autogen"
#. (itstool) path: sect1/para
-#: C/index.docbook:520
+#: C/index.docbook:505
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:529
+#: C/index.docbook:514
msgid "Running gtkdocize from autogen.sh"
msgstr "Ejecutar gtkdocize desde autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:530
+#: C/index.docbook:515
#, no-wrap
msgid ""
"\n"
"gtkdocize || exit 1\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:536
+#: C/index.docbook:521
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:545
+#: C/index.docbook:530
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:562 C/index.docbook:579
+#: C/index.docbook:547 C/index.docbook:564
msgid "Running the doc build"
msgstr "Ejecutar la construcción de la documentación"
#. (itstool) path: sect1/para
-#: C/index.docbook:564
+#: C/index.docbook:549
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:571
+#: C/index.docbook:556
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:580
+#: C/index.docbook:565
#, no-wrap
msgid ""
"\n"
"make\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:586
+#: C/index.docbook:571
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:594
+#: C/index.docbook:579
msgid "Integration with version control systems"
msgstr "Integración con los sistemas de control de versiones"
#. (itstool) path: sect1/para
-#: C/index.docbook:596
+#: C/index.docbook:581
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:604
+#: C/index.docbook:589
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:612
+#: C/index.docbook:597
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:614
+#: C/index.docbook:599
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:621
+#: C/index.docbook:606
msgid "Documentation build steps"
msgstr "Pasos de construcción de la documentación"
#. (itstool) path: example/programlisting
-#: C/index.docbook:622
+#: C/index.docbook:607
#, no-wrap
msgid ""
"\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:636
+#: C/index.docbook:621
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:643
-#| msgid "Integration with plain makefiles or other build systems"
+#: C/index.docbook:628
msgid "Integration with CMake build systems"
msgstr "Integración con sistemas de construcción CMake"
#. (itstool) path: sect1/para
-#: C/index.docbook:645
+#: C/index.docbook:630
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:655
+#: C/index.docbook:640
msgid "Example of using GTK-Doc from CMake"
msgstr "Ejeplo de uso de GTK-Doc desde CMake"
#. (itstool) path: example/programlisting
-#: C/index.docbook:656
+#: C/index.docbook:641
#, no-wrap
msgid ""
"\n"
" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:653
+#: C/index.docbook:638
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:681
+#: C/index.docbook:666
msgid "Documenting the code"
msgstr "Documentar el código"
#. (itstool) path: chapter/para
-#: C/index.docbook:683
+#: C/index.docbook:668
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:691
+#: C/index.docbook:676
msgid "Documentation placement"
msgstr "Ubicación de la documentación"
#. (itstool) path: note/para
-#: C/index.docbook:692
+#: C/index.docbook:677
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:698
+#: C/index.docbook:683
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:709 C/index.docbook:735
+#: C/index.docbook:694 C/index.docbook:720
msgid "GTK-Doc comment block"
msgstr "Bloque de comentario de GTK-Doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:710
+#: C/index.docbook:695
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:705
+#: C/index.docbook:690
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:719
+#: C/index.docbook:704
msgid "Limitations"
msgstr "Limitaciones"
#. (itstool) path: note/para
-#: C/index.docbook:720
+#: C/index.docbook:705
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:730
+#: C/index.docbook:715
msgid "Documentation comments"
msgstr "Comentarios de la documentación"
#. (itstool) path: example/programlisting
-#: C/index.docbook:736
+#: C/index.docbook:721
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:732
+#: C/index.docbook:717
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:745
+#: C/index.docbook:730
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:751
+#: C/index.docbook:736
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:768
+#: C/index.docbook:753
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:774
+#: C/index.docbook:759
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:764
+#: C/index.docbook:749
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:789
+#: C/index.docbook:774
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:794
+#: C/index.docbook:779
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:800
+#: C/index.docbook:785
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:805
+#: C/index.docbook:790
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:811
+#: C/index.docbook:796
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:816
+#: C/index.docbook:801
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:821
+#: C/index.docbook:806
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:783
+#: C/index.docbook:768
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:830
+#: C/index.docbook:815
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:839
+#: C/index.docbook:824
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:850
+#: C/index.docbook:835
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:856
+#: C/index.docbook:841
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:865
+#: C/index.docbook:850
msgid "GTK-Doc comment block using Markdown"
msgstr "Bloque de comentario de GTK-Doc usando marcado"
#. (itstool) path: example/programlisting
-#: C/index.docbook:866
+#: C/index.docbook:851
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:905
+#: C/index.docbook:890
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:911
+#: C/index.docbook:896
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:925
+#: C/index.docbook:910
msgid "Documenting sections"
msgstr "Documentar secciones"
#. (itstool) path: sect1/para
-#: C/index.docbook:927
+#: C/index.docbook:912
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:935
+#: C/index.docbook:920
msgid "Section comment block"
msgstr "Bloque de comentarios en una sección"
#. (itstool) path: example/programlisting
-#: C/index.docbook:936
+#: C/index.docbook:921
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:955
+#: C/index.docbook:940
msgid "SECTION:<name>"
msgstr "SECCIÓN <nombre>"
#. (itstool) path: listitem/para
-#: C/index.docbook:957
+#: C/index.docbook:942
+#| 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 ""
"archivo <filename><paquete>-sections.txt</filename>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:966
+#: C/index.docbook:951
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:968
+#: C/index.docbook:953
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:975
+#: C/index.docbook:960
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:977
+#: C/index.docbook:962
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:984
+#: C/index.docbook:969
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:986
+#: C/index.docbook:971
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:994
+#: C/index.docbook:979
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:996
+#: C/index.docbook:981
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:1002
+#: C/index.docbook:987
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1009
+#: C/index.docbook:994
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:1021
+#: C/index.docbook:1006
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:1033
+#: C/index.docbook:1018
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:1042
+#: C/index.docbook:1027
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:1004
+#: C/index.docbook:989
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:1054
+#: C/index.docbook:1039
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1056
+#: C/index.docbook:1041
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:1065
+#: C/index.docbook:1050
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1067
+#: C/index.docbook:1052
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:1078
+#: C/index.docbook:1063
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:1087
+#: C/index.docbook:1072
msgid "Documenting symbols"
msgstr "Documentar símbolos"
#. (itstool) path: sect1/para
-#: C/index.docbook:1089
+#: C/index.docbook:1074
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:1097 C/index.docbook:1163
+#: C/index.docbook:1082 C/index.docbook:1148
msgid "General tags"
msgstr "Etiquetas generales"
#. (itstool) path: sect2/para
-#: C/index.docbook:1099
+#: C/index.docbook:1084
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:1104
+#: C/index.docbook:1089
msgid "Versioning Tags"
msgstr "Versionado de etiquetas"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1105
+#: C/index.docbook:1090
msgid "Since:"
msgstr "Desde:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1107
+#: C/index.docbook:1092
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:1112
+#: C/index.docbook:1097
msgid "Deprecated:"
msgstr "Obsoleto:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1114
+#: C/index.docbook:1099
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:1122
+#: C/index.docbook:1107
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:1128
+#: C/index.docbook:1113
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:1134
+#: C/index.docbook:1119
msgid "Stability Tags"
msgstr "Etiquetas de estabilidad"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1135
+#: C/index.docbook:1120
msgid "Stability: Stable"
msgstr "Estabilidad: estable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1137
+#: C/index.docbook:1122
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:1144
+#: C/index.docbook:1129
msgid "Stability: Unstable"
msgstr "Estabilidad: inestable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1146
+#: C/index.docbook:1131
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:1152
+#: C/index.docbook:1137
msgid "Stability: Private"
msgstr "Estabilidad: privado"
#. (itstool) path: listitem/para
-#: C/index.docbook:1154
+#: C/index.docbook:1139
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:1164
+#: C/index.docbook:1149
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1184 C/index.docbook:1194
+#: C/index.docbook:1169 C/index.docbook:1179
msgid "Annotations"
msgstr "Anotaciones"
#. (itstool) path: sect2/para
-#: C/index.docbook:1186
+#: C/index.docbook:1171
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:1195
+#: C/index.docbook:1180
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1216 C/index.docbook:1245
+#: C/index.docbook:1201 C/index.docbook:1230
msgid "Function comment block"
msgstr "Bloque de comentario de función"
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1207
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:1228
+#: C/index.docbook:1213
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:1233
+#: C/index.docbook:1218
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:1218 C/index.docbook:1304
+#: C/index.docbook:1203 C/index.docbook:1289
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Recuerde: <_:itemizedlist-1/>"
#. (itstool) path: sect2/para
-#: C/index.docbook:1240
+#: C/index.docbook:1225
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:1246
+#: C/index.docbook:1231
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1267
+#: C/index.docbook:1252
msgid "Function tags"
msgstr "Etiquetas de funciones"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1268
+#: C/index.docbook:1253 C/index.docbook:1460
msgid "Returns:"
msgstr "Devuelve:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1270
+#: C/index.docbook:1255
msgid "Paragraph describing the returned result."
msgstr "Párrafo que describe el resultado devuelto."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1275
+#: C/index.docbook:1260
msgid "@...:"
msgstr "@...:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1277
+#: C/index.docbook:1262
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:1287 C/index.docbook:1289
+#: C/index.docbook:1272 C/index.docbook:1274
msgid "Property comment block"
msgstr "Bloque de comentario de propiedad"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1290
+#: C/index.docbook:1275
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1302 C/index.docbook:1321
+#: C/index.docbook:1287 C/index.docbook:1306
msgid "Signal comment block"
msgstr "Bloque de comentario de señal"
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1293
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:1314
+#: C/index.docbook:1299
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:1322
+#: C/index.docbook:1307
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1339 C/index.docbook:1340
+#: C/index.docbook:1324 C/index.docbook:1325
msgid "Struct comment block"
msgstr "Bloque de comentario de estructura"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1341
+#: C/index.docbook:1326
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1341
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:1362
+#: C/index.docbook:1347
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:1368
+#: C/index.docbook:1353
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:1380 C/index.docbook:1381
+#: C/index.docbook:1365 C/index.docbook:1366
msgid "Enum comment block"
msgstr "Enumerar bloques de comentarios"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1382
+#: C/index.docbook:1367
#, no-wrap
msgid ""
"\n"
"} Something;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1399
+#: C/index.docbook:1384
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:1409
+#: C/index.docbook:1395
+msgid "Inline program documentation"
+msgstr "Documentación en línea del programa"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1396
+msgid ""
+"You can document programs and their commandline interface using inline "
+"documentation."
+msgstr ""
+"Puede documentar programas y su interfaz de línea de comandos usando la "
+"documentación en línea."
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1402
+msgid "Tags"
+msgstr "Etiquetas"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1404
+msgid "PROGRAM"
+msgstr "PROGRAM"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1407
+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:1414
+msgid "@short_description:"
+msgstr "@short_description:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1416
+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:1423
+msgid "@synopsis:"
+msgstr "@synopsis:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1425
+msgid ""
+"Defines the arguments, or list of arguments that the program can take. "
+"(Optional)"
+msgstr ""
+"Define el argumento o la lista de argumentos que el programa puede usar. "
+"(Opcional)"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1433
+msgid "@see_also:"
+msgstr "@see_also:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1435
+msgid "See Also manual page section. (Optional)"
+msgstr "Página del manual Ver también. (Opcional)"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1442
+msgid "@arg:"
+msgstr "@arg:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1444
+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:1451
+msgid "Description:"
+msgstr "Description:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1453
+msgid "A longer description of the program."
+msgstr "Una descripción más larga del programa."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1462
+msgid "Specificy what value(s) the program returns. (Optional)"
+msgstr "Especifique qué valores devuelve el programa. (Opcional)"
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:1471
+msgid "Example of program documentation."
+msgstr "Ejemplo de documentación de un programa."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1472
+msgid "Program documentation block"
+msgstr "Bloque de documentación del programa"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1473
+#, 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 ""
+"\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"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1499
msgid "Useful DocBook tags"
msgstr "Etiquetas DocBook útiles"
#. (itstool) path: sect1/para
-#: C/index.docbook:1411
+#: C/index.docbook:1501
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:1420
+#: C/index.docbook:1510
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1416
+#: C/index.docbook:1506
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:1433
+#: C/index.docbook:1523
#, no-wrap
msgid ""
"\n"
"<function>...</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1430
+#: C/index.docbook:1520
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
"informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1442
+#: C/index.docbook:1532
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1453
+#: C/index.docbook:1543
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1439
+#: C/index.docbook:1529
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:1472
+#: C/index.docbook:1562
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1469
+#: C/index.docbook:1559
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Para incluir listas de topos: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1492
+#: C/index.docbook:1582
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1489
+#: C/index.docbook:1579
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:1505
+#: C/index.docbook:1595
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1502
+#: C/index.docbook:1592
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "Para referirse a un tipo: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1514
+#: C/index.docbook:1604
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1511
+#: C/index.docbook:1601
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:1523
+#: C/index.docbook:1613
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1520
+#: C/index.docbook:1610
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:1532
+#: C/index.docbook:1622
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1529
+#: C/index.docbook:1619
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:1543
+#: C/index.docbook:1633
#, no-wrap
msgid ""
"\n"
"<emphasis>This is important</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1540
+#: C/index.docbook:1630
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Para enfatizar un texto: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1552
+#: C/index.docbook:1642
#, no-wrap
msgid ""
"\n"
"<filename>/home/user/documents</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1549
+#: C/index.docbook:1639
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Para uso de nombres de archivo: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1561
+#: C/index.docbook:1651
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1558
+#: C/index.docbook:1648
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "Para referirse a claves: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1571
+#: C/index.docbook:1661
msgid "Filling the extra files"
msgstr "Rellenar campos adicionales"
#. (itstool) path: chapter/para
-#: C/index.docbook:1573
+#: C/index.docbook:1663
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:1582
+#: C/index.docbook:1672
msgid "Editing the types file"
msgstr "Editar los tipos de archivo"
#. (itstool) path: sect1/para
-#: C/index.docbook:1584
+#: C/index.docbook:1674
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:1593
+#: C/index.docbook:1683
msgid "Example types file snippet"
msgstr "Fragmento de ejemplo de tipos de archivo"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1594
+#: C/index.docbook:1684
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1605
+#: C/index.docbook:1695
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:1614
+#: C/index.docbook:1704
msgid "Editing the master document"
msgstr "Editar la sección maestra del documento"
#. (itstool) path: sect1/para
-#: C/index.docbook:1616
+#: C/index.docbook:1706
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:1623
+#: C/index.docbook:1713
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:1633
+#: C/index.docbook:1723
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:1642
+#: C/index.docbook:1732
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:1649
+#: C/index.docbook:1739
msgid "Master document header"
msgstr "Cabecera del documento maestro"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1650
+#: C/index.docbook:1740
#, no-wrap
msgid ""
"\n"
" <title>[Insert title here]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1666
+#: C/index.docbook:1756
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:1672
+#: C/index.docbook:1762
msgid "Optional part in the master document"
msgstr "Parte opcional en el documento maestro"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1673
+#: C/index.docbook:1763
#, 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"
msgid ""
"\n"
" <!-- enable this when you use gobject introspection annotations\n"
" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n"
-" --> \n"
+" -->\n"
msgstr ""
"\n"
-" <!-- enable this when you use gobject introspection annotations\n"
+" <!-- active esto cuando use anotaciones de introspección de gobject\n"
" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n"
" --> \n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1681
+#: C/index.docbook:1771
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:1689 C/index.docbook:1724
+#: C/index.docbook:1779 C/index.docbook:1814
msgid "Including generated sections"
msgstr "Incluir secciones generadas"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1690
+#: C/index.docbook:1780
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1702
+#: C/index.docbook:1792
msgid "Editing the section file"
msgstr "Editar el archivo de sección"
#. (itstool) path: sect1/para
-#: C/index.docbook:1704
+#: C/index.docbook:1794
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:1710
+#: C/index.docbook:1800
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:1717
+#: C/index.docbook:1807
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:1725
+#: C/index.docbook:1815
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1742
+#: C/index.docbook:1832
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:1754
+#: C/index.docbook:1844
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:1761
+#: C/index.docbook:1851
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:1780
+#: C/index.docbook:1870
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:1794
+#: C/index.docbook:1884
msgid "Controlling the result"
msgstr "Controlar el resultado"
#. (itstool) path: chapter/para
-#: C/index.docbook:1796
+#: C/index.docbook:1886
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:1805
+#: C/index.docbook:1895
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:1814
+#: C/index.docbook:1904
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:1821
+#: C/index.docbook:1911
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:1829
+#: C/index.docbook:1919
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:1836
+#: C/index.docbook:1926
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:1845
+#: C/index.docbook:1935
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:1860
+#: C/index.docbook:1950
msgid "Modernizing the documentation"
msgstr "Modernizar la documentación"
#. (itstool) path: chapter/para
-#: C/index.docbook:1862
+#: C/index.docbook:1952
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:1868
+#: C/index.docbook:1958
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1870
+#: C/index.docbook:1960
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:1875
+#: C/index.docbook:1965
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:1886
+#: C/index.docbook:1976
+#| 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 "
+#| "you source control system and haven't yet switched, just add the flag to "
+#| "<filename>configure.ac</filename> and you are done."
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 you source "
+"<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 ""
"<filename>configure.ac</filename> y lo tendrá hecho."
#. (itstool) path: sect1/title
-#: C/index.docbook:1898
+#: C/index.docbook:1988
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:1900
+#: C/index.docbook:1990
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:1911
+#: C/index.docbook:2001
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:1917
+#: C/index.docbook:2007
msgid "Enable gtkdoc-check"
msgstr "Activar gtkdoc-check"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1918
+#: C/index.docbook:2008
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1913
+#: C/index.docbook:2003
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:1931
+#: C/index.docbook:2021
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:1933
+#: C/index.docbook:2023
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:1943
+#: C/index.docbook:2033
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:1953
+#: C/index.docbook:2043
msgid "Use pre-generated entities"
msgstr "Usar entidades generadas previamenet"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1954
+#: C/index.docbook:2044
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1945
+#: C/index.docbook:2035
+#| 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 any 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/>"
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 any example that shows how "
+"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/>"
"archivos XML generados. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1979
+#: C/index.docbook:2069
msgid "Documenting other interfaces"
msgstr "Documentar otras interfaces"
#. (itstool) path: chapter/para
-#: C/index.docbook:1981
+#: C/index.docbook:2071
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:1988
+#: C/index.docbook:2078
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:1990
+#: C/index.docbook:2080
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:1997
+#: C/index.docbook:2087
msgid "Document the tool"
msgstr "Documentar la herramienta"
#. (itstool) path: sect2/para
-#: C/index.docbook:1999
+#: C/index.docbook:2089
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:2009
+#: C/index.docbook:2099
msgid "Adding the extra configure check"
msgstr "Añadir la comprobación de configuración adicional"
#. (itstool) path: example/title
-#: C/index.docbook:2012 C/index.docbook:2030
+#: C/index.docbook:2102 C/index.docbook:2120
msgid "Extra configure checks"
msgstr "Comprobaciones de configuración adicionales"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2013
+#: C/index.docbook:2103
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2027
+#: C/index.docbook:2117
msgid "Adding the extra makefile rules"
msgstr "Añadir reglas de makefile adicionales"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2031
+#: C/index.docbook:2121
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2053
+#: C/index.docbook:2143
msgid "DBus interfaces"
msgstr "Interfaces de DBus"
#. (itstool) path: sect1/para
-#: C/index.docbook:2055
+#: C/index.docbook:2145
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:2064
+#: C/index.docbook:2154
msgid "Frequently asked questions"
msgstr "Preguntas más frecuentes"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2068
+#: C/index.docbook:2158
msgid "Question"
msgstr "Pregunta"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2069
+#: C/index.docbook:2159
msgid "Answer"
msgstr "Respuesta"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2071
+#: C/index.docbook:2161
msgid "No class hierarchy."
msgstr "Sin jerarquía de clases."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2072
+#: C/index.docbook:2162
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:2078
+#: C/index.docbook:2168
msgid "Still no class hierarchy."
msgstr "Aún sin jerarquía de clases."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2079
+#: C/index.docbook:2169
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:2085
+#: C/index.docbook:2175
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:2086
+#: C/index.docbook:2176
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:2093
+#: C/index.docbook:2183
msgid "No symbol index."
msgstr "Sin índice de símbolos."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2094
+#: C/index.docbook:2184
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:2100
+#: C/index.docbook:2190
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:2101
+#: C/index.docbook:2191
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:2107
+#: C/index.docbook:2197
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:2108
+#: C/index.docbook:2198
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2114
+#: C/index.docbook:2204
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:2115
+#: C/index.docbook:2205
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:2123
+#: C/index.docbook:2213
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:2124
+#: C/index.docbook:2214
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:2133
+#: C/index.docbook:2223
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:2134
+#: C/index.docbook:2224
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:2142
+#: C/index.docbook:2232
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:2143
+#: C/index.docbook:2233
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:2148
+#: C/index.docbook:2238
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "múltiples «ID» para la restricción enlazada: XYZ"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2149
+#: C/index.docbook:2239
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"sections.txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2152
+#: C/index.docbook:2242
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"coincide."
#. (itstool) path: chapter/title
-#: C/index.docbook:2159
+#: C/index.docbook:2249
msgid "Tools related to gtk-doc"
msgstr "Herramientas relacionadas con GTK-Doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2161
+#: C/index.docbook:2251
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:2166
+#: C/index.docbook:2256
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."
#: C/index.docbook:629 C/fdl-appendix.xml:629
msgid "Copyright YEAR YOUR NAME."
msgstr ""
+"Copyright 2009-2016 Daniel Mustieles\n"
"Copyright 2009-2010 Jorge González González\n"
-"Copyright 2009-2010 Francisco Javier Fernández Serrador\n"
-"Copyright 2009 Daniel Mustieles"
+"Copyright 2009-2010 Francisco Javier Fernández Serrador"
#. (itstool) path: blockquote/para
#: C/index.docbook:632
"libre que usted elija, como la <_:ulink-1/>, para permitir su uso en "
"software libre."
+#~ 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>Generar los archivos «plantilla».</guilabel> "
+#~ "<application>gtkdoc-mktmpl</application> crea un número de archivos en la "
+#~ "subcarpeta <filename class=\"directory\">tmpl/</filename>, usando la "
+#~ "información obtenida en el primer paso. (Tenga en cuenta que esto se "
+#~ "puede ejecutar de forma separada. Intentará asegurarse de que la "
+#~ "documentación nunca se pierde.)"
+
+#~ 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 ""
+#~ "Desde de GTK-Doc 1.9 se pueden evitar las plantillas. Animamos a la gente "
+#~ "a que mantenga la documentación en el código. <application>gtkdocize</"
+#~ "application> ahora soporta una opción <command>--flavour no-tmpl</"
+#~ "command> que elige un archivo makefile que omite completamente el uso de "
+#~ "tmpl. Si nunca ha cambiado a mano el archivo tmpl, elimine la carpeta una "
+#~ "vez (por ejemplo, desde el sistema de control de versiones)."
+
#~ msgid "(FIXME : Stability information)"
#~ msgstr "(ARREGLAR: estabilidad de la información)"
<para>Para usar esta licencia en un documento que ha escrito, incluya una copia de la Licencia en el documento y ponga el siguiente copyright y las notas justo después del título de la página.</para>
<blockquote>
- <para>Copyright 2009-2010 Jorge González González
-Copyright 2009-2010 Francisco Javier Fernández Serrador
-Copyright 2009 Daniel Mustieles</para>
+ <para>Copyright 2009-2016 Daniel Mustieles
+Copyright 2009-2010 Jorge González González
+Copyright 2009-2010 Francisco Javier Fernández Serrador</para>
<para>Se otorga permiso para copiar, distribuir y/o modificar este documento bajo los términos de la Licencia de Documentación Libre de GNU, Versión 1.1 o cualquier otra versión posterior publicada por la Free Software Foundation; con las <link linkend="fdl-invariant">Secciones invariantes</link> siendo su LISTE SUS TÍTULOS, con <link linkend="fdl-cover-texts">Textos de cubierta delantera</link> siendo LISTA, y con los <link linkend="fdl-cover-texts">Textos de cubierta trasera</link> siendo LISTA. Una copia de la licencia está incluida en la sección titulada <quote>Licencia de documentación libre de GNU</quote>.</para>
</blockquote>
</legalnotice>
<revhistory>
- <revision><revnumber>1.24.1</revnumber> <date>30 de mayo de 2015</date> <authorinitials>ss</authorinitials> <revremark>versión de desarrollo</revremark></revision>
+ <revision><revnumber>1.25.1</revnumber> <date>21 de mayo de 2016</date> <authorinitials>ss</authorinitials> <revremark>versión de desarrollo</revremark></revision>
+ <revision><revnumber>1.25</revnumber> <date>21 de marzo de 2016</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores, limpieza</revremark></revision>
<revision><revnumber>1.24</revnumber> <date>29 de mayo de 2015</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
<revision><revnumber>1.23</revnumber> <date>17 de mayo de 2015</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
<revision><revnumber>1.22</revnumber> <date>7 de mayo de 2015</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores, eliminadas funcionalidades obsoletas</revremark></revision>
</othercredit>
<copyright>
- <year>2009 - 2015</year>
+ <year>2009 - 2017</year>
<holder>Daniel Mustieles</holder>
</copyright>
<para><application>gtkdoc-scanobj</application> no se debería usar más. Se necesitó en el pasado, cuando GObject todavía era GtkObject dentro de GTK+.</para>
</listitem>
- <listitem>
- <para><guilabel>Generar los archivos «plantilla».</guilabel> <application>gtkdoc-mktmpl</application> crea un número de archivos en la subcarpeta <filename class="directory">tmpl/</filename>, usando la información obtenida en el primer paso. (Tenga en cuenta que esto se puede ejecutar de forma separada. Intentará asegurarse de que la documentación nunca se pierde.)</para>
- <note>
- <para>Desde de GTK-Doc 1.9 se pueden evitar las plantillas. Animamos a la gente a que mantenga la documentación en el código. <application>gtkdocize</application> ahora soporta una opción <command>--flavour no-tmpl</command> que elige un archivo makefile que omite completamente el uso de tmpl. Si nunca ha cambiado a mano el archivo tmpl, elimine la carpeta una vez (por ejemplo, desde el sistema de control de versiones).</para>
- </note>
- </listitem>
-
<listitem>
<para><guilabel>Generar el XML y el HTML/PDF.</guilabel><application>gtkdoc-mkdb</application> convierte los archivos de plantilla en archivos SGML o XML en la subcarpeta <filename class="directory">xml/</filename>. Si el código fuente contiene documentación de funciones, usando los bloques especiales de comentarios, entonces se mezclarán aquí. Si no se usan archivos tmpl sólo obtiene los documentos de los fuentes y los datos obtenidos en introspección.</para>
<para><application>gtkdoc-mkhtml</application> convierte los archivos XML en archivos HTML en la subcarpeta <filename class="directory">html/</filename>. De la misma forma <application>gtkdoc-mkpdf</application> convierte los archivos XML en un documento PDF llamado <filename><paquete>.pdf</filename>.</para>
<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>
- <para>Aún más, se recomienda que tenga la siguiente línea en su script <filename>configure.ac</filename>. Esto permite que <filename>gtkdocize</filename> copie automáticamente la definición del macro para <function>GTK_DOC_CHECK</function> a su proyecto.</para>
+ <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>
<para>
<example><title>Preparación para gtkdocize</title>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Documentación en línea del programa</title>
+ <para>Puede documentar programas y su interfaz de línea de comandos usando la documentación en línea.</para>
+
+ <variablelist>
+ <title>Etiquetas</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>Define el inicio de la documentación de un programa.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>Define una descripción corta del programa. (Opcional)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>Define el argumento o la lista de argumentos que el programa puede usar. (Opcional)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>Página del manual Ver también. (Opcional)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>Argumentos pasados al programa y su descripción. (Opcional)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>Una descripción más larga del programa.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Devuelve:</term>
+ <listitem>
+ <para>Especifique qué valores devuelve el programa. (Opcional)</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Ejemplo de documentación de un programa.</title>
+ <example><title>Bloque de documentación del programa</title>
+ <programlisting>
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+</programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>Etiquetas DocBook útiles</title>
</para>
<para>Se crean además unos pocos elementos de opciones de la manera comentada. Puede revisarlos y activarlos como quiera.</para>
-
+
<para>
<example><title>Parte opcional en el documento maestro</title>
<programlisting>
- <!-- enable this when you use gobject introspection annotations
+ <!-- active esto cuando use anotaciones de introspección de gobject
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-->
</programlisting>
</example>
</para>
-
+
<para>Por último, necesita añadir una sección nueva siempre que quiera introducir una. La herramienta <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> le recordará los nuevos archivos xml generados que no estén inclídos todavía en la documentación.</para>
<para>
<para>El archivo de sección se usa para organizar la salida de la documentación por GTK-Doc. Aquí se especifica qué símbolos pertenecen a qué módulo o clase y el control de la visibilidad (pública o privada).</para>
<para>El archivo de sección es un archivo de texto plano con etiquetas que delimitan las secciones. Se ignoran las líneas vacías y las líneas que comiencen con «#» se tratan como comentarios.</para>
-
+
<note>
<para>Aunque las etiquetas hacen que el archivo parezca XML, no lo es. No incluya etiquetas del tipo <SUBSECTION>.</para>
</note>
<para>Si el proyecto está basado en GObject, también se puede mirar en los archivos producidos por el analizador de objetos: <filename><paquete>.args.txt</filename>, <filename><paquete>.hierarchy.txt</filename>, <filename><paquete>.interfaces.txt</filename>, <filename><paquete>.prerequisites.txt</filename> y <filename><paquete>.signals.txt</filename>. Si faltan símbolos en cualquiera de ellos, puede hacer que GTK-Doc guarde el análisis de archivos para futuros análisis, pero ejecutándolo como <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizar la documentación</title>
-
+
<para>GTK-Doc ha existido durante mucho tiempo. En esta sección se listan las características nuevas junto con la versión desde la que están disponibles.</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
<para>Al usar XML en lugar de SGML, actualmente se puede nombrar el documento maestro <filename><paquete>-docs.xml</filename>.</para>
-
+
<para>Esta versión soporta <option>SCAN_OPTIONS=--rebuild-sections</option> en <filename>Makefile.am</filename>. Cuando está activada, el archivo <filename><paquete>-sections.txt</filename> se genera automáticamente y se puede quitar del control de versiones. Esto sólo funciona en proyectos que tienen una estructura regular (ej. cada pareja .{c,h} creará una sección nueva). Si se organiza un proyecto parecido a esto, actualizar una sección mantenida manualmente puede ser tan sencillo como ejecutar <code>meld <paquete>-decl-list.txt <paquete>-sections.txt</code>.</para>
-
+
<para>La versión 1.18 ya introdujo la sintaxis para documentar secciones en las fuentes en lugar de tener que hacerlo en archivos separados bajo <filename class="directory">tmpl</filename>. Esta versión añade opciones para cambiar todo el módulo «doc» del documento para que no realice el paso de construcción de tmpl adicional, usando <option>--flavour no-tmpl</option> en <filename>configure.ac</filename>. Si no tiene una <filename class="directory">tmpl</filename> marcada en su sistema de control de versiones y todavía no ha cambiado, simplemente añada la opción al archivo <filename>configure.ac</filename> y lo tendrá hecho.</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
<para>Para usar esta licencia en un documento que ha escrito, incluya una copia de la Licencia en el documento y ponga el siguiente copyright y las notas justo después del título de la página.</para>
<blockquote>
- <para>Copyright 2009-2010 Jorge González González
-Copyright 2009-2010 Francisco Javier Fernández Serrador
-Copyright 2009 Daniel Mustieles</para>
+ <para>Copyright 2009-2016 Daniel Mustieles
+Copyright 2009-2010 Jorge González González
+Copyright 2009-2010 Francisco Javier Fernández Serrador</para>
<para>Se otorga permiso para copiar, distribuir y/o modificar este documento bajo los términos de la Licencia de Documentación Libre de GNU, Versión 1.1 o cualquier otra versión posterior publicada por la Free Software Foundation; con las <link linkend="fdl-invariant">Secciones Invariantes</link> siendo su LISTE SUS TÍTULOS, con <link linkend="fdl-cover-texts">Textos de Cubierta Delantera</link> siendo LISTA, y con los <link linkend="fdl-cover-texts">Textos de Cubierta Trasera</link> siendo LISTA. Una copia de la licencia está incluida en la sección titulada <quote>GNU Free Documentation License</quote>.</para>
</blockquote>
<revhistory>
<revision>
- <revnumber>1.24.1</revnumber>
- <date>30 May 2015</date>
+ <revnumber>1.25.1</revnumber>
+ <date>21 March 2016</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development version</revremark>
+ </revision>
+ <revision>
+ <revnumber>1.25</revnumber>
+ <date>21 March 2016</date>
<authorinitials>ss</authorinitials>
- <revremark>development version</revremark>
+ <revremark>bug fixes, test cleanups</revremark>
</revision>
<revision>
<revnumber>1.24</revnumber>
<para><application>gtkdoc-scanobj</application> ne devrait plus être utilisé. Il était nécessaire par le passé lorsque GObject était encore GtkObject dans gtk+.</para>
</listitem>
- <listitem>
- <para><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).</para>
- <note>
- <para>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).</para>
- </note>
- </listitem>
-
<listitem>
<para>
<guilabel>Generating the XML and HTML/PDF.</guilabel>
document called <filename><package>.pdf</filename>.
</para>
<para>
- Files in <filename class="directory">xml/</filename> and
+ 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>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>
- <para>De plus, il est recommandé d'avoir la ligne suivante dans votre script <filename>configure.ac</filename>. Cela permet à <application>gtkdocize</application> de copier automatiquement les définitions de macro pour <function>GTK_DOC_CHECK</function> à votre projet.</para>
+ <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>
<example><title>Préparation pour gtkdocize</title>
<title>Intégration avec automake</title>
<para>
- First copy the <filename>Makefile.am</filename> from the
+ 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.
+ 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>
<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.
+ hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<title>Limitations</title>
<para>
Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
+ <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
<code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
</para>
</note>
<para>
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>
+ 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>.
</para>
<varlistentry>
<term>SECTION:<nom></term>
<listitem>
- <para>Le nom relie la section de la documentation à la partie respective dans le fichier <filename><package>-sections.txt</filename>. Le nom fourni ici doit correspondre à la balise <FILE> du fichier <filename><package>-sections.txt</filename>.</para>
+ <para>
+ The name links the section documentation to the respective part in
+ the <filename><package>-sections.txt</filename> file. The
+ name given here should match the <FILE> tag in the
+ <filename><package>-sections.txt</filename> file.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
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
+ of the supported tags can be found on
<ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
</para>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Inline program documentation</title>
+ <para>
+ You can document programs and their commandline interface using inline
+ documentation.
+ </para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>
+ Defines the start of a program documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>
+ Defines a short description of the program. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>
+ Defines the arguments, or list of arguments that the program can take.
+ (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>
+ See Also manual page section. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>
+ Argument(s) passed to the program and their description. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ A longer description of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>« Returns » :</term>
+ <listitem>
+ <para>
+ Specificy what value(s) the program returns. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Example of program documentation.</title>
+ <example><title>Program documentation block</title>
+ <programlisting><![CDATA[
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+]]></programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>Balises DocBook utiles</title>
In addition a few option elements are created in commented form. You can
review these and enable them as you like.
</para>
-
+
<para>
<example><title>Optional part in the master document</title>
<programlisting><![CDATA[
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
+ -->
]]></programlisting>
</example>
</para>
-
+
<para>
Finally you need to add new section whenever you introduce one. The
<link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
Blank lines are ignored and lines starting with a '#' are treated as
comment lines.
</para>
-
+
<note>
<para>
While the tags make the file look like xml, it is not. Please do not
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizing the documentation</title>
-
+
<para>
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.
</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
When using xml instead of sgml, one can actually name the master
document <filename><package>-docs.xml</filename>.
</para>
-
+
<para>
This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
in <filename>Makefile.am</filename>. When this is enabled, the
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
+ maintained section file can be as simple as running
<code>meld <package>-decl-list.txt <package>-sections.txt</code>.
</para>
-
+
<para>
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 you source control system and haven't yet switched, just
+ checked into your source control system and haven't yet switched, just
add the flag to <filename>configure.ac</filename> and you are done.
</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
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 any example that shows how the entity file is included
+ 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.
<revhistory>
<revision>
- <revnumber>1.24.1</revnumber>
- <date>30 May 2015</date>
+ <revnumber>1.25.1</revnumber>
+ <date>21 March 2016</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development version</revremark>
+ </revision>
+ <revision>
+ <revnumber>1.25</revnumber>
+ <date>21 March 2016</date>
<authorinitials>ss</authorinitials>
- <revremark>development version</revremark>
+ <revremark>bug fixes, test cleanups</revremark>
</revision>
<revision>
<revnumber>1.24</revnumber>
</para>
</listitem>
- <listitem>
- <para>
- <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.)
- </para>
- <note>
- <para>
- 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).
- </para>
- </note>
- </listitem>
-
<listitem>
<para>
<guilabel>Generating the XML and HTML/PDF.</guilabel>
document called <filename><package>.pdf</filename>.
</para>
<para>
- Files in <filename class="directory">xml/</filename> and
+ 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>
Furthermore it is recommended that you have the following line inside
- you <filename>configure.ac</filename> script.
+ 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>
<title>Integration with automake</title>
<para>
- First copy the <filename>Makefile.am</filename> from the
+ 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.
+ 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>
<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.
+ hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<title>Limitations</title>
<para>
Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
+ <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
<code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
</para>
</note>
<para>
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>
+ 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>.
</para>
<para>
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
+ name given here should match the <FILE> tag in the
<filename><package>-sections.txt</filename> file.
</para>
</listitem>
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
+ of the supported tags can be found on
<ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
</para>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Inline program documentation</title>
+ <para>
+ You can document programs and their commandline interface using inline
+ documentation.
+ </para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>
+ Defines the start of a program documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>
+ Defines a short description of the program. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>
+ Defines the arguments, or list of arguments that the program can take.
+ (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>
+ See Also manual page section. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>
+ Argument(s) passed to the program and their description. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ A longer description of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Returns:</term>
+ <listitem>
+ <para>
+ Specificy what value(s) the program returns. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Example of program documentation.</title>
+ <example><title>Program documentation block</title>
+ <programlisting><![CDATA[
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+]]></programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>Useful DocBook tags</title>
In addition a few option elements are created in commented form. You can
review these and enable them as you like.
</para>
-
+
<para>
<example><title>Optional part in the master document</title>
<programlisting><![CDATA[
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
+ -->
]]></programlisting>
</example>
</para>
-
+
<para>
Finally you need to add new section whenever you introduce one. The
<link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
Blank lines are ignored and lines starting with a '#' are treated as
comment lines.
</para>
-
+
<note>
<para>
While the tags make the file look like xml, it is not. Please do not
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizing the documentation</title>
-
+
<para>
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.
</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
When using xml instead of sgml, one can actually name the master
document <filename><package>-docs.xml</filename>.
</para>
-
+
<para>
This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
in <filename>Makefile.am</filename>. When this is enabled, the
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
+ maintained section file can be as simple as running
<code>meld <package>-decl-list.txt <package>-sections.txt</code>.
</para>
-
+
<para>
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 you source control system and haven't yet switched, just
+ checked into your source control system and haven't yet switched, just
add the flag to <filename>configure.ac</filename> and you are done.
</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
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 any example that shows how the entity file is included
+ 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.
<revhistory>
<revision>
- <revnumber>1.24.1</revnumber>
- <date>30 May 2015</date>
+ <revnumber>1.25.1</revnumber>
+ <date>21 March 2016</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development version</revremark>
+ </revision>
+ <revision>
+ <revnumber>1.25</revnumber>
+ <date>21 March 2016</date>
<authorinitials>ss</authorinitials>
- <revremark>development version</revremark>
+ <revremark>bug fixes, test cleanups</revremark>
</revision>
<revision>
<revnumber>1.24</revnumber>
</para>
</listitem>
- <listitem>
- <para>
- <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.)
- </para>
- <note>
- <para>
- 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).
- </para>
- </note>
- </listitem>
-
<listitem>
<para>
<guilabel>Generating the XML and HTML/PDF.</guilabel>
document called <filename><package>.pdf</filename>.
</para>
<para>
- Files in <filename class="directory">xml/</filename> and
+ 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>GTK-Doc એ મૂળભૂત રીતે નિષ્ક્રિય થયેલ છે! આગળનાં <filename>configure</filename> ને ચલાવવા માટે <option>'--enable-gtk-doc'</option> ને પસાર કરવાનું યાદ રાખો. નહિં તો પહેલીથી ઉત્પન્ન થયેલ દસ્તાવેજીકરણ સ્થાપિત થયેલ છે (કે જે વપરાશકર્તાઓ માટેનો અર્થ બને છે પરંતુ ડેવલપરો માટે નહિં).</para>
</important>
- <para>આગળ વધારે તે અગ્રહણીય થયેલ છે કે જે તમારી પાસે તમારી <filename>configure.ac</filename> સ્ક્રિપ્ટની અંદર નીચેનું વાક્ય છે. આ તમારા પ્રોજેક્ટમાં <function>GTK_DOC_CHECK</function> માટે મેક્રો વ્યાખ્યાને આપમેળે નકલ કરવા માટે પરવાનગી આપે છે.</para>
+ <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>
<example><title>gtkdocize માટે તૈયારી</title>
<title>automake સાથે એકત્રિકરણ</title>
<para>
- First copy the <filename>Makefile.am</filename> from the
+ 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.
+ 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>
<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.
+ hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<title>Limitations</title>
<para>
Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
+ <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
<code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
</para>
</note>
<para>
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>
+ 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>.
</para>
<para>
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
+ name given here should match the <FILE> tag in the
<filename><package>-sections.txt</filename> file.
</para>
</listitem>
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
+ of the supported tags can be found on
<ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
</para>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Inline program documentation</title>
+ <para>
+ You can document programs and their commandline interface using inline
+ documentation.
+ </para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>
+ Defines the start of a program documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>
+ Defines a short description of the program. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>
+ Defines the arguments, or list of arguments that the program can take.
+ (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>
+ See Also manual page section. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>
+ Argument(s) passed to the program and their description. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ A longer description of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>પાછુ આવે છે:</term>
+ <listitem>
+ <para>
+ Specificy what value(s) the program returns. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Example of program documentation.</title>
+ <example><title>Program documentation block</title>
+ <programlisting><![CDATA[
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+]]></programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>ઉપયોગી DocBook ટૅગ</title>
In addition a few option elements are created in commented form. You can
review these and enable them as you like.
</para>
-
+
<para>
<example><title>Optional part in the master document</title>
<programlisting><![CDATA[
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
+ -->
]]></programlisting>
</example>
</para>
-
+
<para>
Finally you need to add new section whenever you introduce one. The
<link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
Blank lines are ignored and lines starting with a '#' are treated as
comment lines.
</para>
-
+
<note>
<para>
While the tags make the file look like xml, it is not. Please do not
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizing the documentation</title>
-
+
<para>
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.
</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
When using xml instead of sgml, one can actually name the master
document <filename><package>-docs.xml</filename>.
</para>
-
+
<para>
This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
in <filename>Makefile.am</filename>. When this is enabled, the
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
+ maintained section file can be as simple as running
<code>meld <package>-decl-list.txt <package>-sections.txt</code>.
</para>
-
+
<para>
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 you source control system and haven't yet switched, just
+ checked into your source control system and haven't yet switched, just
add the flag to <filename>configure.ac</filename> and you are done.
</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
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 any example that shows how the entity file is included
+ 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.
<listitem>
<formalpara>
<title>A</title>
- <para>Usar na <link linkend="fdl-title-page">Título da página</link> (e nas capas, se existirem) um título distinto em relação ao do <link linkend="fdl-document">Documento</link>, e daqueles de versões anteriores (os quais devem, na existência de algum, ser listados na seção "Histórico" do Documento). Você pode usar o mesmo título de uma versão anterior se o editor original daquela versão conceder-lhe permissão.</para>
+ <para>Usar na <link linkend="fdl-title-page">Título da página</link> (e nas capas, se existirem) um título distinto em relação ao do <link linkend="fdl-document">Documento</link>, e daqueles de versões anteriores (os quais devem, na existência de algum, ser listados na seção “Histórico” do Documento). Você pode usar o mesmo título de uma versão anterior se o editor original daquela versão conceder-lhe permissão.</para>
</formalpara>
</listitem>
<title>6. COLEÇÕES DE DOCUMENTOS</title>
<para>Você pode fazer uma coleção que consiste do <link linkend="fdl-document">Documento</link> e outros documentos publicados sob esta Licença, e substituir as cópias individuais desta Licença, nos vários documentos, por uma única cópia a ser incluída na coleção, desde que você siga as regras desta Licença para cópias literais de cada documento em todos os outros aspectos.</para>
- <para>
- 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.
- </para>
+ <para>Você pode extrair um único documento desta coleção, e distribuí-lo individualmente sob esta Licença, desde que você insira uma cópia desta Licença no documento extraído, e siga esta Licença em todos os outros aspectos com relação à cópia literal do documento.</para>
</sect1>
<sect1 id="fdl-section7">
<para>Se você não tiver qualquer <link linkend="fdl-invariant">Sessões invariantes</link>, escreva <quote>sem Seções Invariantes</quote> ao invés de afirmar quais são invariantes. Se você não tem <link linkend="fdl-cover-texts">Textos de Capa Frontal</link>, escreva <quote>sem Textos de Capa Frontal</quote> ao invés de <quote>Textos de Capa Frontal sendo LISTADOS</quote>; O mesmo se aplica a <link linkend="fdl-cover-texts">Textos de Contracapa</link>.</para>
- <para>Se seu documento contiver exemplos não-triviais de código de programação, recomendamos publicar estes exemplos paralelamente, sob a licença de software livre que você escolher, como por exemplo a <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html">Licença Pública Geral GNU (GPL)</ulink> (GNU General Public License), para permitir seu uso em software livre.</para>
+ <para>Se seu documento contiver exemplos não-triviais de código de programação, recomendamos publicar estes exemplos paralelamente, sob a licença de software livre que você escolher, como, por exemplo, a <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html">Licença Pública Geral GNU (GPL)</ulink>, para permitir seu uso em software livre.</para>
</sect1>
</appendix>
</authorgroup>
<publisher role="maintainer"><publishername>Projeto GTK-Doc</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
<copyright><year>2000, 2005</year> <holder>Dan Mueth e 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>
</legalnotice>
<revhistory>
- <revision>
- <revnumber>1.24.1</revnumber>
- <date>30 May 2015</date>
- <authorinitials>ss</authorinitials>
- <revremark>development version</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.25.1</revnumber> <date>21 Março 2016</date> <authorinitials>ss</authorinitials> <revremark>versão de desenvolvimento</revremark></revision>
+ <revision><revnumber>1.25</revnumber> <date>21 Março 2016</date> <authorinitials>ss</authorinitials> <revremark>correção de erros, limpezas de testes</revremark></revision>
+ <revision><revnumber>1.24</revnumber> <date>29 Maio 2015</date> <authorinitials>ss</authorinitials> <revremark>correção de erros</revremark></revision>
+ <revision><revnumber>1.23</revnumber> <date>17 Maio 2015</date> <authorinitials>ss</authorinitials> <revremark>correção de erros</revremark></revision>
+ <revision><revnumber>1.22</revnumber> <date>07 Maio 2015</date> <authorinitials>ss</authorinitials> <revremark>correção de erros, desativadas funcionalidades obsoletas</revremark></revision>
<revision><revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</authorinitials> <revremark>correção de erros, desativadas funcionalidades obsoletas</revremark></revision>
<revision><revnumber>1.20</revnumber> <date>14 Fev 2014</date> <authorinitials>ss</authorinitials> <revremark>correção de erros, suporte a markdown, melhorias no estilo</revremark></revision>
<revision><revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</authorinitials> <revremark>correção de erros</revremark></revision>
<othercredit class="translator">
<personname>
- <firstname>Rafael Ferreira</firstname>
+ <firstname>Rafael Fontenelle</firstname>
</personname>
- <email>rafael.f.f1@gmail.com</email>
+ <email>rafaelff@gnome.org</email>
</othercredit>
<copyright>
<year>2014</year>
- <holder>Rafael Ferreira</holder>
+ <year>2016</year>
+
+ <year>2017</year>
+
+ <holder>Rafael Fontenelle</holder>
</copyright>
</bookinfo>
</listitem>
<listitem>
- <para><guilabel>Gerando os arquivos "template".</guilabel> <application>gtkdoc-mktmpl</application> cria uma quantidade de arquivos no subdiretório <filename class="directory">tmpl/</filename>, usando a informação coletada na primeira etapa. (Note que ele pode ser executado repetidas vezes e vai tentar garantir que nenhuma documentação será perdida, jamais.)</para>
- <note>
- <para>Desde o GTK-Doc 1.9, os modelos ("templates") podem ser evitados. Nós encorajamos as pessoas a manter a documentação no código. <application>gtkdocize</application> possui suporte a uma opção <option>--flavour no-tmpl</option> que escolhe um makefile que ignora totalmente o uso de tmpl. Se você nunca alterou o arquivo em tmpl manualmente, por favor remova o diretório (ex.: do sistema de controle de versão).</para>
- </note>
- </listitem>
-
- <listitem>
- <para>
- <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.
- </para>
- <para>
- <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>.
- </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><guilabel>Gerando o XML e HTML/PDF.</guilabel> <application>gtkdoc-mkdb</application> transforma os arquivos modelos em arquivos XML no subdiretório <filename class="directory">xml/</filename>. Se o código fonte contém documentação nas funções, usando os blocos de comentários especiais, ela é mesclada aqui. Se não há arquivos tmpl sendo usados, ele apenas lê documentos dos dados de introspecção e dos fontes.</para>
+ <para><application>gtkdoc-mkhtml</application> transforma os arquivos XML em arquivos HTML no subdiretório <filename class="directory">html/</filename>. Da mesma forma, <application>gtkdoc-mkpdf</application> transforma os arquivos XML em um documento PDF chamado <filename><pacote>.pdf</filename>.</para>
+ <para>Arquivos nos diretórios <filename class="directory">xml/</filename> e <filename class="directory">html/</filename> são sempre sobrescritos. Não devem ser editados manualmente.</para>
</listitem>
<listitem>
<chapter id="settingup">
<title>Preparando seu projeto</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>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>
<sect1 id="settingup_docfiles">
<title>Preparando o esqueleto de uma documentação</title>
<sect1 id="settingup_vcs">
<title>Integração com sistemas de controle de versão</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.
- </para>
+ <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>
<sect1 id="plain_makefiles">
<para>
<example><title>Etapas de compilação da documentação</title>
- <programlisting><![CDATA[
+ <programlisting>
DOC_MODULE=meep
-// sources have changed
-gtkdoc-scan --module=$(DOC_MODULE) <source-dir>
+// fontes foram alterados
+gtkdoc-scan --module=$(DOC_MODULE) <source-dir=>
gtkdoc-scangobj --module=$(DOC_MODULE)
-gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>
-// xml files have changed
+gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>
+// arquivos xml foram alterados
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>
</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[
+ <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)
-# Create the doc-libmeep target.
+# Cria o alvo doc-libmeep.
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.
+# 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>
+</programlisting>
+ </example></para>
</sect1>
</chapter>
</example></para>
<note>
- <title>Limitations</title>
- <para>
- Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
- <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
- </para>
+ <title>Limitações</title>
+ <para>Note que o GTK-Doc oferece suporte a <code>#ifndef(__GTK_DOC_IGNORE__)</code>, mas não a <code>#if !defined(__GTK_DOC_IGNORE__)</code> ou outras combinações.</para>
</note>
<!-- -->
<sect1 id="documenting_syntax">
<title>Comentários de documentação</title>
- <para>Um comentário multilinha que começa com um "*" adicional marca um bloco de documentação que será processado pelas ferramentas do GTK-Doc. <example><title>Bloco de comentário do GTK-Doc</title>
+ <para>Um comentário multilinha que começa com um “*” adicional marca um bloco de documentação que será processado pelas ferramentas do GTK-Doc. <example><title>Bloco de comentário do GTK-Doc</title>
<programlisting>
/**
* identificador:
</programlisting>
</example></para>
- <para>O "identificador" é uma linha com o nome do item ao qual o comentário está relacionado. A sintaxe difere um pouco dependendo do item.</para>
+ <para>O “identificador” é uma linha com o nome do item ao qual o comentário está relacionado. A sintaxe difere um pouco dependendo do item.</para>
- <para>O bloco "documentação" também é diferente para cada tipo de símbolo. Tipos de símbolos que levam parâmetros, como funções e macros, têm a descrição de parâmetro começando com uma linha vazia (apenas com um "*"). Posteriormente, segue com a descrição detalhada. Todas as linhas (fora das listagens do programa e seções CDATA) contendo apenas um " *" (espaço em branco e asterisco) são convertidas para quebras de parágrafos. Se você não quiser uma quebra de parágrafo, altere isso para " * " (espaço, asterisco, espaço e espaço). Isso é útil em textos pré-formatados (listagens de código).</para>
+ <para>O bloco “documentação” também é diferente para cada tipo de símbolo. Tipos de símbolos que levam parâmetros, como funções e macros, têm a descrição de parâmetro começando com uma linha vazia (apenas com um “*”). Posteriormente, segue com a descrição detalhada. Todas as linhas (fora das listagens do programa e seções CDATA) contendo apenas um “ *” (espaço em branco e asterisco) são convertidas para quebras de parágrafos. Se você não quiser uma quebra de parágrafo, altere isso para “ * “ (espaço, asterisco, espaço e espaço). Isso é útil em textos pré-formatados (listagens de código).</para>
<tip>
<para>Ao documentar um código, descreva dois aspectos: <itemizedlist>
</itemizedlist></para>
<tip>
- <para>Se você precisar usar os caracteres especiais "<", ">", "()", "@", "%" ou "#" em sua documentação sem GTK-Doc alterando-os, você pode usar as entidades XML "&lt;", "&gt;", "&lpar;", "&rpar;", "&commat;", "&percnt;" e "&num;", respectivamente, ou escapá-los com uma contrabarra "\".</para>
+ <para>Se você precisar usar os caracteres especiais “<”, “>”, “()”, “@”, “%” ou “#” em sua documentação sem GTK-Doc alterando-os, você pode usar as entidades XML “&lt;”, “&gt;”, “&lpar;”, “&rpar;”, “&commat;”, “&percnt;” e “&num;”, respectivamente, ou escapá-los com uma contrabarra “\”.</para>
</tip>
<para>DocBook pode fazer mais do que apenas links. Ele também pode ter listas, exemplos, títulos e imagens. A partir da versão 1.20, a forma preferível é usar um subconjunto de sintaxe de formatação de texto básica chamada <ulink url="http://daringfireball.net/projects/markdown/">Markdown</ulink>. Em versões mais antigas do GTK-Doc, qualquer documentação que inclui Markdown será renderizada como está. Por exemplo, itens de lista aparecerão como linhas começando com um traço.</para>
- <para>
- 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.
- </para>
+ <para>Enquanto markdown é agora preferível, é possível misturar ambos. Uma limitação aqui é que é possível usar docbook xml no markdown, mas não há suporte a markdown no docbook xml.</para>
- <para>
- 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>.
- </para>
+ <para>Em versões mais antigas do GTK-Doc, se você precisasse de suporte para formatação adicional, você precisaria de habilitar o uso de tags de XML de docbook dentro de comentários de documentação colocando <option>--xml-mode</option> (ou <option>--sgml-mode</option>) na variável <symbol>MKDB_OPTIONS</symbol> dentro de <filename>Makefile.am</filename>.</para>
<para>
<example><title>Bloco de comentário do GTK-Doc usando Markdown</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>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>
</tip>
</sect1>
<para>Privado - Uma interface que pode ser usada dentro da própria pilha do GNOME, mas que não está documentada para usuários finais. Tais funções deveriam ser usadas nas formas especificadas e documentadas.</para>
</listitem>
<listitem>
- <para>Interna - Uma interface que é interna a um módulo e não requer documentação para o usuário final. Funções que não estão documentadas são presumidas como sendo "Interna".</para>
+ <para>Interna - Uma interface que é interna a um módulo e não requer documentação para o usuário final. Funções que não estão documentadas são presumidas como sendo “Interna”.</para>
</listitem>
</itemizedlist></para>
</listitem>
</varlistentry>
</variablelist>
- <para>
- 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.
- </para>
+ <para>Você também pode adicionar informação sobre estabilidade em todos os elementos de documentação para indicar se a estabilidade de uma API é garantida para eles para futuros lançamentos menores do projeto.</para>
- <para>
- 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.
- </para>
+ <para>O nível de estabilidade padrão para todos os elementos de documentação pode ser definido passando o argumento <option>--default-stability</option> para <application>gtkdoc-mkdb</application> com um dos balores abaixo.</para>
- <variablelist><title>Stability Tags</title>
+ <variablelist><title>Tags de estabilidade</title>
<varlistentry><term>Stability: Stable</term>
<listitem>
- <para>
- Mark the element as stable. This is for public APIs which are
- guaranteed to remain stable for all future minor releases of the
- project.
- </para>
+ <para>Marca o elemento como estável. Isto é para APIs públicas cuja estabilidade é garantida para todos os próximos lançamentos menores do projeto.</para>
</listitem>
</varlistentry>
<varlistentry><term>Stability: Unstable</term>
<listitem>
- <para>
- Mark the element as unstable. This is for public APIs which are
- released as a preview before being stabilised.
- </para>
+ <para>Marca o elemento como instável. Isto é para APIs públicas que são publicados como versão de desenvolvimento antes de se tornar estável.</para>
</listitem>
</varlistentry>
<varlistentry><term>Stability: Private</term>
<listitem>
- <para>
- Mark the element as private. This is for interfaces which can be
- used by tightly coupled modules, but not by arbitrary third
- parties.
- </para>
+ <para>Marca o elemento como privado. Isto é para interfaces que podem ser usadas por um conjunto pequeno de módulos, mas não por terceiros.</para>
</listitem>
</varlistentry>
</variablelist>
</example>
</sect2>
- <sect2><title>Annotations</title>
+ <sect2><title>Anotações</title>
- <para>
- 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>.
- </para>
+ <para>Blocos de documentação podem conter tags de anotação. Essas tags serão renderizadas com dicas de ferramentas descrevendo seu significados. As tags são usadas pelo gobject-introspection para garantir associações (bindings) de linguagens. Uma lista detalhada tags aceitas podem ser encontrada <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">no wiki</ulink>.</para>
- <example><title>Annotations</title>
- <programlisting><![CDATA[
+ <example><title>Anotações</title>
+ <programlisting>
/**
- * foo_get_bar: (annotation)
- * @foo: (annotation): some foo
+ * foo_get_bar: (anotação)
+ * @foo: (anotação): algum foo
*
- * Retrieves @foo's bar.
+ * Obtém bar do @foo.
*
- * Returns: (annotation): @foo's bar
+ * Returns: (anotação): bar do @foo
*/
...
/**
- * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)
- * (and another annotation)
- * @foo: (annotation) (another annotation): some foo
+ * foo_set_bar_using_the_frobnicator: (anotação) (outra anotação)
+ * (e uma outra anotação)
+ * @foo: (anotação) (uma outra anotação): algum foo
*
- * Sets bar on @foo.
+ * Define bar no @foo.
*/
-]]></programlisting>
+</programlisting>
</example>
</sect2>
</listitem>
</itemizedlist></para>
- <para>Gtk-doc presume que todos os símbolos (macros, funções) começando com "_" são privadas. Elas são tratadas como funções estáticas.</para>
+ <para>Gtk-doc presume que todos os símbolos (macros, funções) começando com “_” são privadas. Elas são tratadas como funções estáticas.</para>
<example><title>Bloco de comentário de função</title>
<programlisting>
<sect2><title>Bloco de comentário de struct</title>
<example><title>Bloco de comentário de struct</title>
- <programlisting><![CDATA[
+ <programlisting>
/**
* FooWidget:
- * @bar: some #gboolean
+ * @bar: algum #gboolean
*
- * This is the best widget, ever.
+ * Este é o melhor widget, já mais visto.
*/
typedef struct _FooWidget {
- GtkWidget parent_instance;
+ GtkWidget parent_intance;
gboolean bar;
} FooWidget;
-]]></programlisting>
+</programlisting>
</example>
<para>Use <code>/*< private >*/</code> antes dos campos da struct privada que você deseja esconder. Use <code>/*< public >*/</code> para o comportamento inverso.</para>
- <para>
- 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.
- </para>
+ <para>Se o primeiro campo for “g_iface”, “parent_instance” ou “parent_class”, ele será automaticamente considerado como privado e não precisará ser mencionado no bloco de comentário.</para>
<para>Blocos de comentário de struct também podem ser usados para GObjects e GObjectClasses. É normalmente uma boa ideia adicionar um bloco de comentário para uma classe, se ela possui vmethods (pois assim é como elas podem ser documentadas). Para o próprio GOBject pode-se usar os documentos de seção relacionados, tendo um bloco separado para a instância do struct seria útil se a instância possui campos públicos. Uma desvantagem aqui é que isso cria duas entradas no índice do mesmo nome (a estrutura e a seção).</para>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Documentação de programa em-linha</title>
+ <para>Você pode documentar programas e sua interface de linha de comando usando documentação em-linha.</para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>Define o início da documentação de um programa.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>Define uma descrição breve do programa. (Opcional)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>Define os argumentos, ou lista de argumentos, que o programa pode receber. (Opcional)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>A seção “Veja Também” (See Also) de páginas de manual. (Opcional)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>Argumento(s) passado(s) para o programa e sua descrição. (Opcional)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>Um descrição mais longa do programa.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Returns:</term>
+ <listitem>
+ <para>Especifique quais valor(es) o programa retorna. (Opcional)</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Exemplo de documentação de programa.</title>
+ <example><title>Bloco de documentação de programa</title>
+ <programlisting>
+/**
+ * PROGRAM:programa-teste
+ * @short_description: Um programa teste
+ * @synopsis: programa-teste [*OPÇÕES*...] --arg1 *arg* *ARQUIVO*
+ * @see_also: teste(1)
+ * @--arg1 *arg*: define arg1 para *arg*
+ * @--arg2 *arg*: define arg2 para *arg*
+ * @-v, --version: Exibe o número da versão
+ * @-h, --help: Exibe a mensagem de ajuda
+ *
+ * Descrição longa do programa.
+ *
+ * Returns: Zero no caso de sucesso, não-zero no caso de falha
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+</programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>Tags úteis do DocBook</title>
<programlisting>
<link linkend="glib-Hash-Tables">Tabela de hashes</link>
</programlisting>
- </informalexample> O fim do link é o ID do SGML/XML no item superior da páginao a qual você deseja vincular. Para a maioria das páginas isto é atualmente a parte ("gtk", "gdk", "glib") e, então, o título da página ("Hash Tables"). Para os widgets isso é apenas o nome da classe. Espaços e sublinhados são convertidos em '-' para estar em conformidade com SGML/XML.</para>
+ </informalexample> O fim do link é o ID do SGML/XML no item superior da página a qual você deseja vincular. Para a maioria das páginas isto é atualmente a parte (“gtk”, “gdk”, “glib”) e, então, o título da página (“Hash Tables”). Para os widgets isso é apenas o nome da classe. Espaços e sublinhados são convertidos em '-' para estar em conformidade com SGML/XML.</para>
<para>Para se referir a uma função externa, como, por exemplo, uma função padrão do C: <informalexample>
<programlisting>
</example>
</para>
- <para>Desde o GTK-Doc 1.8, o <application>gtkdoc-scan</application> pode gerar esta lista para você. Basta adicionar "--rebuild-types" a SCAN_OPTIONS no <filename>Makefile.am</filename>. Se você usar esta abordagem, você não deveria distribuir o arquivo de tipos nem tê-lo sob um controle de versão.</para>
+ <para>Desde o GTK-Doc 1.8, o <application>gtkdoc-scan</application> pode gerar esta lista para você. Basta adicionar “--rebuild-types” a SCAN_OPTIONS no <filename>Makefile.am</filename>. Se você usar esta abordagem, você não deveria distribuir o arquivo de tipos nem tê-lo sob um controle de versão.</para>
</sect1>
<para>O Gtk-Doc produz documentação em DocBook SGML/XML. Ao processar os comentários inseridos nos fontes, as ferramentas do GTK-Doc geram uma página de documentação por classe ou módulo como um arquivo separado. O documento mestre os inclui e os coloca em uma ordem.</para>
- <para>
- 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.
- </para>
+ <para>Enquanto o Gtk-Doc cria um modelo de documento mestre para você, execuções posteriores não vão tocá-lo novamente. Isso significa que se pode estruturar a documentação livremente. Isso inclui agrupamento de páginas e adição de páginas extras. O Gtk-Doc agora possui uma suíte de teste, na qual também o documento mestre é recriado do zero. É uma boa ideia verificar isso de tempo em tempo para ver se há itens a serem introduzidos lá.</para>
<tip>
<para>Não crie tutoriais como documentos extras. Apenas escreva capítulos extras. O benefício de embutir diretamente o tutorial para sua biblioteca na documentação da API é que é mais fácil vincular o tutorial a um símbolo da documentação. Além disso, as chances são mais altas que o tutorial obtenha atualizações junto com a biblioteca.</para>
</example>
</para>
+ <para>Além disso, alguns elementos de opção são criados na forma comentada. Você pode revisá-los e habilitá-los como preferir.</para>
+
<para>
- In addition a few option elements are created in commented form. You can
- review these and enable them as you like.
- </para>
-
- <para>
- <example><title>Optional part in the master document</title>
- <programlisting><![CDATA[
- <!-- enable this when you use gobject introspection annotations
- <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
-]]></programlisting>
+ <example><title>Parte opcional do documento mestre</title>
+ <programlisting>
+ <!-- habilite isso se você usa anotações do gobject introspection
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+ -->
+</programlisting>
</example>
</para>
-
- <para>
- 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.
- </para>
+
+ <para>Finalmente você precisa adicionar nova seção sempre que você a introduzir. A ferramenta <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> vai lembrar você de arquivos xml recentemente gerados que ainda não foram incluídos na documentação.</para>
<para>
- <example><title>Including generated sections</title>
- <programlisting><![CDATA[
- <chapter>
- <title>my library</title>
- <xi:include href="xml/object.xml"/>
+ <example><title>Incluindo seções geradas</title>
+ <programlisting>
+ <chapter>
+ <title>minha biblioteca</title>
+ <xi:include href="xml/object.xml"/>
...
-]]></programlisting>
+</programlisting>
</example>
</para>
<para>O arquivo de seção é usado para organizar a saída da documentação pelo GTK-Doc. Aqui pode-se especificar qual símbolo pertence a qual módulo ou classe e controla a visibilidade (pública ou privada).</para>
- <para>
- 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.
- </para>
-
+ <para>O arquivo de seção é uma arquivo texto simples com seções delimitadas por tags. Linhas em branco são ignoradas e linhas começando com um “#” são tratadas como linhas de comentários.</para>
+
<note>
- <para>
- While the tags make the file look like xml, it is not. Please do not
- close tags like <SUBSECTION>.
- </para>
+ <para>Enquanto as tags fazem o arquivo se parecer xml, ele não é. Por favor, não feche tags como <SUBSECTION>.</para>
</note>
<para>
- <example><title>Including generated sections</title>
- <programlisting><![CDATA[
-<INCLUDE>libmeep/meep.h</INCLUDE>
+ <example><title>Incluindo seções geradas</title>
+ <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>
- <para>
- 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 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).
- </para>
+ <para>A tag <FILE> ... </FILE> é usada para especificar o nome de arquivo, sem qualquer sufixo. Por exemplo, ao usar “<FILE>gnome-config</FILE>” resultará nas declarações da seção serem retornadas no arquivo modelo <filename>tmpl/gnome-config.sgml</filename>, o qual será convertido no arquivo DocBook XML <filename>xml/gnome-config.sgml</filename> ou no arquivo DocBook XML <filename>xml/gnome-config.xml</filename>. (O nome do arquivo HTML é baseado no nome do módulo e no título da seção ou, para GObjects, é baseado no nome da classe GObjects convertidos os caracteres para minúsculos).</para>
<para>A tag <TITLE> ... </TITLE> é usada para especificar o título da seção. Ela é usada apenas antes do modelo (se usado) ser criado inicialmente, já que o título definido no arquivo de modelo sobrescreve este. Também, se for usado o comentário SECTION nos fontes, isso está obsoleto.</para>
- <para>Você pode agrupar itens na seção usando a tag <SUBSECTION>. Atualmente, ela retorna uma linha em branco entre as subseções na seção de sinópse. Você também pode usar <SUBSECTION Standard> para declarações padrão do GObject (ex.: as funções como g_object_get_type e macros como G_OBJECT(), G_IS_OBJECT() etc.). Atualmente, estas são deixadas fora da documentação. Você também pode usar <SUBSECTION Private> para declarações privadas que não serão retornadas (é uma forma prática de evitar mensagens de aviso sobre declarações não usadas). Se sua biblioteca contém tipos privados que você não deseja que apareçam na hierarquia do objeto e a linha de classes implementadas ou exigidas, adicione-as a uma subseção privada. Se você colocaria o GObject e GObjectClass como structs numa seção padrão ou pública depende se há entradas públicas (variáveis, vmethods).</para>
+ <para>Você pode agrupar itens na seção usando a tag <SUBSECTION>. Atualmente, ela retorna uma linha em branco entre as subseções na seção de sinopse. Você também pode usar <SUBSECTION Standard> para declarações padrão do GObject (ex.: as funções como g_object_get_type e macros como G_OBJECT(), G_IS_OBJECT() etc.). Atualmente, estas são deixadas fora da documentação. Você também pode usar <SUBSECTION Private> para declarações privadas que não serão retornadas (é uma forma prática de evitar mensagens de aviso sobre declarações não usadas). Se sua biblioteca contém tipos privados que você não deseja que apareçam na hierarquia do objeto e a linha de classes implementadas ou exigidas, adicione-as a uma subseção privada. Se você colocaria o GObject e GObjectClass como structs numa seção padrão ou pública depende se há entradas públicas (variáveis, vmethods).</para>
- <para>Você também pode usar <INCLUDE> ... </INCLUDE> para especificar os arquivos #include que são mostrados nas seções de sinópse. Ela contém uma lista separada por vírgula de arquivos #include, sem os sinais de maior que e menor que. Se você define-a fora de quaisquer seções, ela age para todas as seções até o fim do arquivo. Se você define-a em uma seção, ela só vai se aplicar àquela seção.</para>
+ <para>Você também pode usar <INCLUDE> ... </INCLUDE> para especificar os arquivos #include que são mostrados nas seções de sinopse. Ela contém uma lista separada por vírgula de arquivos #include, sem os sinais de maior que e menor que. Se você define-a fora de quaisquer seções, ela age para todas as seções até o fim do arquivo. Se você define-a em uma seção, ela só vai se aplicar àquela seção.</para>
</sect1>
<para>Se o projeto é baseado em GObject, pode-se também procurar nos arquivos produzidos pela varredura de objetos: <filename><pacote>.args.txt</filename>, <filename><pacote>.hierarchy.txt</filename>, <filename><pacote>.interfaces.txt</filename>, <filename><pacote>.prerequisites.txt</filename> e <filename><pacote>.signals.txt</filename>. Se há símbolos faltando em qualquer um deles, pode-se exigir que o GTK-Doc mantenha o arquivo intermediário de varredura para análise posterior, executando <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizando a documentação</title>
-
+
<para>GTK-Doc está por aí já faz um tempo. Nesta seção, nós listamos novas funcionalidades juntamente da versão desde a qual está disponível.</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
<para>Ao usar xml em vez de sgml, na verdade, é possível nomear o documento mestre <filename><pacote>-docs.xml</filename>.</para>
-
+
<para>Essa versão provê suporte <option>SCAN_OPTIONS=--rebuild-sections</option> em <filename>Makefile.am</filename>. Quando esta opção está habilitada, o <filename><package>-sections.txt</filename> é auto-gerado e pode ser removido a partir do VCS. Isso só funciona corretamente para projetos que têm uma estrutura muito regular (ex.: cada par .{c,h} vai criar uma nova seção). Se uma pessoa organiza um projeto próximo a isso atualizando um arquivo de seção mantido manualmente pode ser tão simples quanto executando <code>meld <package>-decl-list.txt <package>-sections.txt</code>.</para>
-
- <para>
- 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 you source control system and haven't yet switched, just
- add the flag to <filename>configure.ac</filename> and you are done.
- </para>
+
+ <para>A versão 1.8 já introduziu a sintaxe para documentação seções nos fontes em vez dos arquivos separados sob <filename class="directory">tmpl</filename>. Essa versão adiciona opções para alternar todo o módulo de documentação para não usar a etapa de compilação extra do tmpl, usando <option>--flavour no-tmpl</option> no <filename>configure.ac</filename>. Se você não possui um <filename class="directory">tmpl</filename> no seu sistema de controle de versão e ainda não trocou, basta adicionar uma opção ao <filename>configure.ac</filename> e está resolvido.</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
<sect1 id="modernizing-gtk-doc-1-25">
<title>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 any 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><title>Use pre-generated entities</title>
- <programlisting><![CDATA[
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ <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"
"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;.
- 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>
+]>
+<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>
</sect1>
</chapter>
</seglistitem>
<seglistitem>
<seg>Droga. Eu ainda não tenho hierarquia de classes.</seg>
- <seg>Por acaso o nome do objeto (nome da struct da instância, ex. <type>GtkWidget</type>) faz parte da seção normal (não coloque isso em subsções Standard ou Private)?</seg>
+ <seg>Por acaso o nome do objeto (nome da struct da instância, ex. <type>GtkWidget</type>) faz parte da seção normal (não coloque isso em subseções Standard ou Private)?</seg>
</seglistitem>
<seglistitem>
<seg>Nenhum símbolo de índice.</seg>
- <seg>O <filename><pacote>-docs.{xml,sgml}</filename> contém um índice que "xi:inclui" o índice gerado?</seg>
+ <seg>O <filename><pacote>-docs.{xml,sgml}</filename> contém um índice que “xi:inclui” o índice gerado?</seg>
</seglistitem>
<seglistitem>
<seg>Símbolos não estão vinculados ao seus doc-section.</seg>
</seglistitem>
<seglistitem>
<seg>Uma nova classe não aparece nos documentos.</seg>
- <seg>A nova página foi "xi:incluída" do <filename><pacote>-docs.{xml,sgml}</filename>?</seg>
+ <seg>A nova página foi “xi:incluída” do <filename><pacote>-docs.{xml,sgml}</filename>?</seg>
</seglistitem>
<seglistitem>
<seg>Um novo símbolo não aparece nos documentos.</seg>
</seglistitem>
<seglistitem>
<seg>Um tipo está faltando da hierarquia de classe.</seg>
- <seg>
- 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
- incidentally marked private it will not be shown.
- </seg>
+ <seg>Se o tipo está listado no <filename><pacote>.hierarchy</filename>, mas não em <filename>xml/tree_index.sgml</filename>, então certifique-se de que o tipo está colocado corretamente no <filename><pacote>-sections.txt</filename>. Se a instância do tipo (ex.: <type>GtkWidget</type>) não está listada ou incidentalmente marcada como privada, ela não será mostrada.</seg>
</seglistitem>
<seglistitem>
<seg>Obtenho links de seguimento de documentos para todas as anotações gobject.</seg>
- <seg>Verifique se <filename>xml/annotation-glossary.xml</filename> está "xi:incluído" de <filename><pacote>-docs.{xml,sgml}</filename>.</seg>
+ <seg>Verifique se <filename>xml/annotation-glossary.xml</filename> está “xi:incluído” de <filename><pacote>-docs.{xml,sgml}</filename>.</seg>
</seglistitem>
<!-- gtk-doc warnings: -->
<!-- docbook warnings: -->
<seglistitem>
- <seg>Múltiplos "IDs" para restrições do fim do link XYZ</seg>
+ <seg>múltiplos “IDs” para restrições do fim do link XYZ</seg>
<seg>O símbolo XYZ aparece duas vezes no arquivo <filename><pacote>-sections.txt</filename>.</seg>
</seglistitem>
<seglistitem>
<listitem>
<formalpara>
<title>A</title>
- <para>Usar na <link linkend="fdl-title-page">Página de Título</link> (e nas capas, se existirem) um título distinto em relação ao do <link linkend="fdl-document">Documento</link>, e daqueles de versões anteriores (os quais devem, na existência de algum, ser listados na seção "Histórico" do Documento). Você pode usar o mesmo título de uma versão anterior se o editor original daquela versão conceder-lhe permissão.</para>
+ <para>Usar na <link linkend="fdl-title-page">Página de Título</link> (e nas capas, se existirem) um título distinto em relação ao do <link linkend="fdl-document">Documento</link>, e daqueles de versões anteriores (os quais devem, na existência de algum, ser listados na seção “Histórico” do Documento). Você pode usar o mesmo título de uma versão anterior se o editor original daquela versão conceder-lhe permissão.</para>
</formalpara>
</listitem>
<title>6. COLEÇÕES DE DOCUMENTOS</title>
<para>Você pode fazer uma coleção que consiste do <link linkend="fdl-document">Documento</link> e outros documentos publicados sob esta Licença, e substituir as cópias individuais desta Licença, nos vários documentos, por uma única cópia a ser incluída na coleção, desde que você siga as regras desta Licença para cópias literais de cada documento em todos os outros aspectos.</para>
- <para>
- 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.
- </para>
+ <para>Você pode extrair um único documento desta coleção, e distribuí-lo individualmente sob esta Licença, desde que você insira uma cópia desta Licença no documento extraído, e siga esta Licença em todos os outros aspectos com relação à cópia literal do documento.</para>
</sect1>
<sect1 id="fdl-section7">
# Brazilian Portuguese translation for gtk-doc help.
-# Copyright (C) 2016 gtk-doc's COPYRIGHT HOLDER
+# Copyright (C) 2017 gtk-doc's COPYRIGHT HOLDER
# This file is distributed under the same license as the gtk-doc package.
# Marcelo Rodrigues <marcelopires@mmsantos.com.br>, 2010.
-# Rafael Fontenelle <rafaelff@gnome.org>, 2013, 2014, 2016.
+# Rafael Fontenelle <rafaelff@gnome.org>, 2013, 2014, 2016, 2017.
msgid ""
msgstr ""
"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: 2016-01-21 21:44+0000\n"
-"PO-Revision-Date: 2016-03-21 10:13-0200\n"
+"POT-Creation-Date: 2017-04-23 16:21+0000\n"
+"PO-Revision-Date: 2017-04-25 08:24-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"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n > 1);\n"
-"X-Generator: Virtaal 0.7.1\n"
+"X-Generator: Virtaal 1.0.0-beta1\n"
"X-Project-Style: gnome\n"
#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
msgid "translator-credits"
msgstr ""
"Marcelo Rodrigues <marcelopires@mmsantos.com.br>, 2010\n"
-"Rafael Fontenelle <rafaelff@gnome.org>, 2013, 2014, 2016"
+"Rafael Fontenelle <rafaelff@gnome.org>, 2013, 2014, 2016, 2017"
#. (itstool) path: bookinfo/title
#: C/index.docbook:12
#. (itstool) path: bookinfo/copyright
#: C/index.docbook:52
-#| msgid "<year>2007-2014</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>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:83
-#| msgid ""
-#| "<revnumber>1.21.1</revnumber> <date>18 Jul 2014</date> "
-#| "<authorinitials>ss</authorinitials> <revremark>development version</"
-#| "revremark>"
msgid ""
-"<revnumber>1.2
4.1</revnumber> <date>30 May 2015</date> <authorinitials>ss</"
+"<revnumber>1.2
5.1</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>development version</revremark>"
msgstr ""
-"<revnumber>1.24.1</revnumber> <date>30 Maio 2015</date> "
-"<authorinitials>ss</authorinitials> <revremark>versão de "
-"desenvolvimento</revremark>"
+"<revnumber>1.25.1</revnumber> <date>21 Março 2016</date> <authorinitials>ss</"
+"authorinitials> <revremark>versão de desenvolvimento</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
-#| msgid ""
-#| "<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
-#| "authorinitials> <revremark>bug fixes</revremark>"
+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ço 2016</date> <authorinitials>ss</"
+"authorinitials> <revremark>correção de erros, limpezas de testes</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
msgstr ""
-"<revnumber>1.24</revnumber> <date>29 Maio 2015</date> "
-"<authorinitials>ss</authorinitials> <revremark>correção de erros</revremark>"
+"<revnumber>1.24</revnumber> <date>29 Maio 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>correção de erros</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
-#| msgid ""
-#| "<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
-#| "authorinitials> <revremark>bug fixes</revremark>"
+#: C/index.docbook:101
msgid ""
"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
msgstr ""
-"<revnumber>1.23</revnumber> <date>17 Maio 2015</date> "
-"<authorinitials>ss</authorinitials> <revremark>correção de erros</revremark>"
+"<revnumber>1.23</revnumber> <date>17 Maio 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>correção de erros</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
-#| msgid ""
-#| "<revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</"
-#| "authorinitials> <revremark>bug fixes, dropping deprecated features</"
-#| "revremark>"
+#: C/index.docbook:107
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 Maio 2015</date> "
-"<authorinitials>ss</authorinitials> <revremark>correção de erros, "
-"desativadas funcionalidades obsoletas</revremark>"
+"<revnumber>1.22</revnumber> <date>07 Maio 2015</date> <authorinitials>ss</"
+"authorinitials> <revremark>correção de erros, desativadas funcionalidades "
+"obsoletas</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:107
+#: C/index.docbook:113
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:113
+#: C/index.docbook:119
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:119
+#: C/index.docbook:125
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:125
+#: C/index.docbook:131
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:131
+#: C/index.docbook:137
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:137
+#: C/index.docbook:143
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:143
+#: C/index.docbook:149
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:149
+#: C/index.docbook:155
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:155
+#: C/index.docbook:161
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:161
+#: C/index.docbook:167
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:167
+#: C/index.docbook:173
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:180
+#: C/index.docbook:186
msgid "Introduction"
msgstr "Introdução"
#. (itstool) path: chapter/para
-#: C/index.docbook:182
+#: C/index.docbook:188
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:188
+#: C/index.docbook:194
msgid "What is GTK-Doc?"
msgstr "O que é GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:190
+#: C/index.docbook:196
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:198
+#: C/index.docbook:204
msgid "How Does GTK-Doc Work?"
msgstr "Como o GTK-Doc funciona?"
#. (itstool) path: sect1/para
-#: C/index.docbook:200
+#: C/index.docbook:206
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:207
+#: C/index.docbook:213
msgid ""
"GTK-Doc consists of a number of perl scripts, each performing a different "
"step in the process."
"diferente no processo."
#. (itstool) path: sect1/para
-#: C/index.docbook:212
+#: C/index.docbook:218
msgid "There are 5 main steps in the process:"
msgstr "Há 5 etapas principais no processo:"
#. (itstool) path: listitem/para
-#: C/index.docbook:219
+#: C/index.docbook:225
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:229
+#: C/index.docbook:235
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:246
+#: C/index.docbook:252
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:252
+#: C/index.docbook:258
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:259
-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>Gerando os arquivos \"template\".</guilabel> <application>gtkdoc-"
-"mktmpl</application> cria uma quantidade de arquivos no subdiretório "
-"<filename class=\"directory\">tmpl/</filename>, usando a informação coletada "
-"na primeira etapa. (Note que ele pode ser executado repetidas vezes e vai "
-"tentar garantir que nenhuma documentação será perdida, jamais.)"
-
-#. (itstool) path: note/para
-#: C/index.docbook:268
-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 ""
-"Desde o GTK-Doc 1.9, os modelos (\"templates\") podem ser evitados. Nós "
-"encorajamos as pessoas a manter a documentação no código. "
-"<application>gtkdocize</application> possui suporte a uma opção <option>--"
-"flavour no-tmpl</option> que escolhe um makefile que ignora totalmente o uso "
-"de tmpl. Se você nunca alterou o arquivo em tmpl manualmente, por favor "
-"remova o diretório (ex.: do sistema de controle de versão)."
-
-#. (itstool) path: listitem/para
-#: C/index.docbook:280
-#| 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."
+#: C/index.docbook:265
msgid ""
"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
"mkdb</application> turns the template files into XML files in the <filename "
"gets merged in here. If there are no tmpl files used it only reads docs from "
"sources and introspection data."
msgstr ""
-"<guilabel>Gerando o XML e HTML/PDF.</guilabel> <application>gtkdoc-"
-"mkdb</application> transforma os arquivos modelos em arquivos XML no "
-"subdiretório <filename class=\"directory\">xml/</filename>. Se o código fonte "
-"contém documentação nas funções, usando os blocos de comentários especiais, "
-"ela é mesclada aqui. Se não há arquivos tmpl sendo usados, ele apenas lê "
+"<guilabel>Gerando o XML e HTML/PDF.</guilabel> <application>gtkdoc-mkdb</"
+"application> transforma os arquivos modelos em arquivos XML no subdiretório "
+"<filename class=\"directory\">xml/</filename>. Se o código fonte contém "
+"documentação nas funções, usando os blocos de comentários especiais, ela é "
+"mesclada aqui. Se não há arquivos tmpl sendo usados, ele apenas lê "
"documentos dos dados de introspecção e dos fontes."
#. (itstool) path: listitem/para
-#: C/index.docbook:289
-#| 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>."
+#: C/index.docbook:274
msgid ""
"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
"document called <filename><package>.pdf</filename>."
msgstr ""
"<application>gtkdoc-mkhtml</application> transforma os arquivos XML em "
-"arquivos HTML no subdiretório <filename class=\"directory\">html/</filename>. "
-"Da mesma forma, <application>gtkdoc-mkpdf</application> transforma os "
-"arquivos XML em um documento PDF chamado "
-"<filename><pacote>.pdf</filename>."
+"arquivos HTML no subdiretório <filename class=\"directory\">html/</"
+"filename>. Da mesma forma, <application>gtkdoc-mkpdf</application> "
+"transforma os arquivos XML em um documento PDF chamado <filename><"
+"pacote>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:295
-#| 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."
+#: C/index.docbook:280
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:303
+#: C/index.docbook:288
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:321
+#: C/index.docbook:306
msgid "Getting GTK-Doc"
msgstr "Obtendo GTK-Doc"
#. (itstool) path: sect2/title
-#: C/index.docbook:324
+#: C/index.docbook:309
msgid "Requirements"
msgstr "Requisitos"
#. (itstool) path: sect2/para
-#: C/index.docbook:325
+#: C/index.docbook:310
msgid "<guilabel>Perl v5</guilabel> - the main scripts are in Perl."
msgstr "<guilabel>Perl v5</guilabel> - os scripts principais são Perl."
#. (itstool) path: sect2/para
-#: C/index.docbook:328
+#: C/index.docbook:313
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:332
+#: C/index.docbook:317
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:336
+#: C/index.docbook:321
msgid "<guilabel>Python</guilabel> - optional - for gtkdoc-depscan"
msgstr "<guilabel>Python</guilabel> - opcional - para gtkdoc-depscan"
#. (itstool) path: sect2/para
-#: C/index.docbook:339
+#: C/index.docbook:324
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:347
+#: C/index.docbook:332
msgid "About GTK-Doc"
msgstr "Sobre GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:349 C/index.docbook:363
+#: C/index.docbook:334 C/index.docbook:348
msgid "(FIXME)"
msgstr "(CORRIJA-ME)"
#. (itstool) path: sect1/para
-#: C/index.docbook:353
+#: C/index.docbook:338
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:361
+#: C/index.docbook:346
msgid "About this Manual"
msgstr "Sobre este manual"
#. (itstool) path: sect1/para
-#: C/index.docbook:367
+#: C/index.docbook:352
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:376
+#: C/index.docbook:361
msgid "Setting up your project"
msgstr "Preparando seu projeto"
#. (itstool) path: chapter/para
-#: C/index.docbook:378
+#: C/index.docbook:363
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'. "
msgstr ""
"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."
+"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."
#. (itstool) path: sect1/title
-#: C/index.docbook:389
+#: C/index.docbook:374
msgid "Setting up a skeleton documentation"
msgstr "Preparando o esqueleto de uma documentação"
#. (itstool) path: sect1/para
-#: C/index.docbook:391
+#: C/index.docbook:376
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:400
+#: C/index.docbook:385
msgid "Example directory structure"
msgstr "Exemplo de estrutura de diretórios"
#. (itstool) path: example/programlisting
-#: C/index.docbook:401
+#: C/index.docbook:386
#, no-wrap
msgid ""
"\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:398
+#: C/index.docbook:383
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:416 C/index.docbook:423
+#: C/index.docbook:401 C/index.docbook:408
msgid "Integration with autoconf"
msgstr "Integração com autoconf"
#. (itstool) path: sect1/para
-#: C/index.docbook:418
+#: C/index.docbook:403
msgid ""
"Very easy! Just add one line to your <filename>configure.ac</filename> "
"script."
"filename>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:424
+#: C/index.docbook:409
#, no-wrap
msgid ""
"\n"
"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
#. (itstool) path: example/title
-#: C/index.docbook:436
+#: C/index.docbook:421
msgid "Keep gtk-doc optional"
msgstr "Mantenha o gtk-doc como opcional"
#. (itstool) path: example/programlisting
-#: C/index.docbook:437
+#: C/index.docbook:422
#, no-wrap
msgid ""
"\n"
"])\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:431
+#: C/index.docbook:416
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:448
+#: C/index.docbook:433
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:454
+#: C/index.docbook:439
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:455
+#: C/index.docbook:440
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:456
+#: C/index.docbook:441
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:457
+#: C/index.docbook:442
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:461
+#: C/index.docbook:446
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:469
+#: C/index.docbook:454
+#| 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."
"macro para <function>GTK_DOC_CHECK</function> para o seu projeto."
#. (itstool) path: example/title
-#: C/index.docbook:477
+#: C/index.docbook:462
msgid "Preparation for gtkdocize"
msgstr "Preparação para gtkdocize"
#. (itstool) path: example/programlisting
-#: C/index.docbook:478
+#: C/index.docbook:463
#, no-wrap
msgid ""
"\n"
"AC_CONFIG_MACRO_DIR(m4)\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:483
+#: C/index.docbook:468
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:491
+#: C/index.docbook:476
msgid "Integration with automake"
msgstr "Integração com automake"
#. (itstool) path: sect1/para
-#: C/index.docbook:493
+#: C/index.docbook:478
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:504
+#: C/index.docbook:489
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:518
+#: C/index.docbook:503
msgid "Integration with autogen"
msgstr "Integração com autogen"
#. (itstool) path: sect1/para
-#: C/index.docbook:520
+#: C/index.docbook:505
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:529
+#: C/index.docbook:514
msgid "Running gtkdocize from autogen.sh"
msgstr "Executando gtkdocize no autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:530
+#: C/index.docbook:515
#, no-wrap
msgid ""
"\n"
"gtkdocize || exit 1\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:536
+#: C/index.docbook:521
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:545
+#: C/index.docbook:530
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:562 C/index.docbook:579
+#: C/index.docbook:547 C/index.docbook:564
msgid "Running the doc build"
msgstr "Executando a compilação da documentação"
#. (itstool) path: sect1/para
-#: C/index.docbook:564
+#: C/index.docbook:549
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:571
+#: C/index.docbook:556
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:580
+#: C/index.docbook:565
#, no-wrap
msgid ""
"\n"
"make\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:586
+#: C/index.docbook:571
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:594
+#: C/index.docbook:579
msgid "Integration with version control systems"
msgstr "Integração com sistemas de controle de versão"
#. (itstool) path: sect1/para
-#: C/index.docbook:596
-#| 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>"
+#: C/index.docbook:581
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>."
msgstr ""
"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>"
+"<filename><pacote>.types</filename>, <filename><pacote>-docs."
+"xml</filename> (no passado, .sgml), <filename><pacote>-sections.txt</"
+"filename>, <filename>Makefile.am</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:604
+#: C/index.docbook:589
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 ""
-"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>."
+"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>."
#. (itstool) path: sect1/title
-#: C/index.docbook:612
+#: C/index.docbook:597
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:614
+#: C/index.docbook:599
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:621
+#: C/index.docbook:606
msgid "Documentation build steps"
msgstr "Etapas de compilação da documentação"
#. (itstool) path: example/programlisting
-#: C/index.docbook:622
+#: C/index.docbook:607
#, no-wrap
-#| msgid ""
-#| "\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"
msgid ""
"\n"
"DOC_MODULE=meep\n"
"// fontes foram alterados\n"
"gtkdoc-scan --module=$(DOC_MODULE) <source-dir=>\n"
"gtkdoc-scangobj --module=$(DOC_MODULE)\n"
-"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<"
-";source-dir>\n"
+"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>\n"
"// arquivos xml foram alterados \n"
"mkdir html\n"
"cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:636
+#: C/index.docbook:621
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:643
-#| msgid "Integration with plain makefiles or other build systems"
+#: C/index.docbook:628
msgid "Integration with CMake build systems"
msgstr "Integração com sistemas de compilação CMake"
#. (itstool) path: sect1/para
-#: C/index.docbook:645
+#: C/index.docbook:630
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:655
+#: C/index.docbook:640
msgid "Example of using GTK-Doc from CMake"
msgstr "Exemplo de uso do GTK-Doc no CMake"
#. (itstool) path: example/programlisting
-#: C/index.docbook:656
+#: C/index.docbook:641
#, no-wrap
msgid ""
"\n"
"# documentos.\n"
"add_custom_target(documentation ALL DEPENDS doc-libmeep)\n"
"\n"
-"# Install the docs. (This assumes you're using the GNUInstallDirs CMake "
-"module\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:653
+#: C/index.docbook:638
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:681
+#: C/index.docbook:666
msgid "Documenting the code"
msgstr "Documentando o código"
#. (itstool) path: chapter/para
-#: C/index.docbook:683
+#: C/index.docbook:668
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:691
+#: C/index.docbook:676
msgid "Documentation placement"
msgstr "Localização da documentação"
#. (itstool) path: note/para
-#: C/index.docbook:692
+#: C/index.docbook:677
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:698
+#: C/index.docbook:683
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:709 C/index.docbook:735
+#: C/index.docbook:694 C/index.docbook:720
msgid "GTK-Doc comment block"
msgstr "Bloco de comentário do GTK-Doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:710
+#: C/index.docbook:695
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:705
+#: C/index.docbook:690
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:719
-#| msgid "Dedications"
+#: C/index.docbook:704
msgid "Limitations"
msgstr "Limitações"
#. (itstool) path: note/para
-#: C/index.docbook:720
+#: C/index.docbook:705
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 ""
-"Note que o GTK-Doc oferece suporte a "
-"<code>#ifndef(__GTK_DOC_IGNORE__)</code>, mas não a <code>#if "
-"!defined(__GTK_DOC_IGNORE__)</code> ou outras combinações."
+"Note que o GTK-Doc oferece suporte a <code>#ifndef(__GTK_DOC_IGNORE__)</"
+"code>, mas não a <code>#if !defined(__GTK_DOC_IGNORE__)</code> ou outras "
+"combinações."
#. (itstool) path: sect1/title
-#: C/index.docbook:730
+#: C/index.docbook:715
msgid "Documentation comments"
msgstr "Comentários de documentação"
#. (itstool) path: example/programlisting
-#: C/index.docbook:736
+#: C/index.docbook:721
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:732
+#: C/index.docbook:717
msgid ""
"A multiline comment that starts with an additional '*' marks a documentation "
"block that will be processed by the GTK-Doc tools. <_:example-1/>"
msgstr ""
-"Um comentário multilinha que começa com um \"*\" adicional marca um bloco de "
+"Um comentário multilinha que começa com um “*” adicional marca um bloco de "
"documentação que será processado pelas ferramentas do GTK-Doc. <_:example-1/>"
# Ocultei o TODO da tradução. Para que server? :/
#. (itstool) path: sect1/para
-#: C/index.docbook:745
+#: C/index.docbook:730
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 "
"table showing identifiers)"
msgstr ""
-"O \"identificador\" é uma linha com o nome do item ao qual o comentário está "
+"O “identificador” é uma linha com o nome do item ao qual o comentário está "
"relacionado. A sintaxe difere um pouco dependendo do item."
#. (itstool) path: sect1/para
-#: C/index.docbook:751
+#: C/index.docbook:736
msgid ""
"The 'documentation' block is also different for each symbol type. Symbol "
"types that get parameters such as functions or macros have the parameter "
"breaks. If you don't want a paragraph break, change that into ' * ' (blank-"
"asterisk-blank-blank). This is useful in preformatted text (code listings)."
msgstr ""
-"O bloco \"documentação\" também é diferente para cada tipo de símbolo. Tipos "
+"O bloco “documentação” também é diferente para cada tipo de símbolo. Tipos "
"de símbolos que levam parâmetros, como funções e macros, têm a descrição de "
-"parâmetro começando com uma linha vazia (apenas com um \"*\"). "
-"Posteriormente, segue com a descrição detalhada. Todas as linhas (fora das "
-"listagens do programa e seções CDATA) contendo apenas um \" *\" (espaço em "
-"branco e asterisco) são convertidas para quebras de parágrafos. Se você não "
-"quiser uma quebra de parágrafo, altere isso para \" * \" (espaço, asterisco, "
-"espaço e espaço). Isso é útil em textos pré-formatados (listagens de código)."
+"parâmetro começando com uma linha vazia (apenas com um “*”). Posteriormente, "
+"segue com a descrição detalhada. Todas as linhas (fora das listagens do "
+"programa e seções CDATA) contendo apenas um “ *” (espaço em branco e "
+"asterisco) são convertidas para quebras de parágrafos. Se você não quiser "
+"uma quebra de parágrafo, altere isso para “ * “ (espaço, asterisco, espaço e "
+"espaço). Isso é útil em textos pré-formatados (listagens de código)."
#. (itstool) path: listitem/para
-#: C/index.docbook:768
+#: C/index.docbook:753
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:774
+#: C/index.docbook:759
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:764
+#: C/index.docbook:749
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:789
+#: C/index.docbook:774
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:794
+#: C/index.docbook:779
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:800
+#: C/index.docbook:785
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:805
+#: C/index.docbook:790
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:811
+#: C/index.docbook:796
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:816
+#: C/index.docbook:801
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:821
+#: C/index.docbook:806
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:783
+#: C/index.docbook:768
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:830
+#: C/index.docbook:815
msgid ""
"If you need to use the special characters '<', '>', '()', '@', '%', or "
"'#' in your documentation without GTK-Doc changing them you can use the XML "
"commat;\", \"&percnt;\" and \"&num;\" respectively or escape them "
"with a backslash '\\'."
msgstr ""
-"Se você precisar usar os caracteres especiais \"<\", \">\", \"()\", \"@"
-"\", \"%\" ou \"#\" em sua documentação sem GTK-Doc alterando-os, você pode "
-"usar as entidades XML \"&lt;\", \"&gt;\", \"&lpar;\", \"&"
-"rpar;\", \"&commat;\", \"&percnt;\" e \"&num;\", "
-"respectivamente, ou escapá-los com uma contrabarra \"\\\"."
+"Se você precisar usar os caracteres especiais “<”, “>”, “()”, “@”, “%” "
+"ou “#” em sua documentação sem GTK-Doc alterando-os, você pode usar as "
+"entidades XML “&lt;”, “&gt;”, “&lpar;”, “&rpar;”, “&"
+"commat;”, “&percnt;” e “&num;”, respectivamente, ou escapá-los com "
+"uma contrabarra “\\”."
#. (itstool) path: sect1/para
-#: C/index.docbook:839
+#: C/index.docbook:824
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:850
+#: C/index.docbook:835
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:856
-#| msgid ""
-#| "In older GTK-Doc releases, if you need support for additional formatting, "
-#| "you would need to enable the usage of docbook SGML/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>."
+#: C/index.docbook:841
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 "
msgstr ""
"Em versões mais antigas do GTK-Doc, se você precisasse de suporte para "
"formatação adicional, você precisaria de habilitar o uso de tags de XML de "
-"docbook dentro de comentários de documentação colocando <option>--xml-"
-"mode</option> (ou <option>--sgml-mode</option>) na variável "
-"<symbol>MKDB_OPTIONS</symbol> dentro de <filename>Makefile.am</filename>."
+"docbook dentro de comentários de documentação colocando <option>--xml-mode</"
+"option> (ou <option>--sgml-mode</option>) na variável <symbol>MKDB_OPTIONS</"
+"symbol> dentro de <filename>Makefile.am</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:865
+#: C/index.docbook:850
msgid "GTK-Doc comment block using Markdown"
msgstr "Bloco de comentário do GTK-Doc usando Markdown"
#. (itstool) path: example/programlisting
-#: C/index.docbook:866
+#: C/index.docbook:851
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:905
+#: C/index.docbook:890
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:911
+#: C/index.docbook:896
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 "
"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."
+"(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."
#. (itstool) path: sect1/title
-#: C/index.docbook:925
+#: C/index.docbook:910
msgid "Documenting sections"
msgstr "Documentando seções"
#. (itstool) path: sect1/para
-#: C/index.docbook:927
+#: C/index.docbook:912
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:935
+#: C/index.docbook:920
msgid "Section comment block"
msgstr "Bloco de comentário de sessão"
#. (itstool) path: example/programlisting
-#: C/index.docbook:936
+#: C/index.docbook:921
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:955
+#: C/index.docbook:940
msgid "SECTION:<name>"
msgstr "SECTION:<nome>"
#. (itstool) path: listitem/para
-#: C/index.docbook:957
+#: C/index.docbook:942
+#| 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 ""
"O nome vincula a documentação da seção à respectiva parte do arquivo "
"<filename><pacote>-sections.txt</filename>. O nome informado aqui deve "
-"corresponder à tag <FILE> no arquivo <filename><pacote>-sections."
-"txt</filename>."
+"corresponder à tag <FILE> no arquivo "
+"<filename><pacote>-sections.txt</filename>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:966
+#: C/index.docbook:951
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:968
+#: C/index.docbook:953
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:975
+#: C/index.docbook:960
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:977
+#: C/index.docbook:962
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:984
+#: C/index.docbook:969
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:986
+#: C/index.docbook:971
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:994
+#: C/index.docbook:979
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:996
+#: C/index.docbook:981
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:1002
+#: C/index.docbook:987
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1009
+#: C/index.docbook:994
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:1021
+#: C/index.docbook:1006
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:1033
+#: C/index.docbook:1018
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:1042
+#: C/index.docbook:1027
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 "
msgstr ""
"Interna - Uma interface que é interna a um módulo e não requer documentação "
"para o usuário final. Funções que não estão documentadas são presumidas como "
-"sendo \"Interna\"."
+"sendo “Interna”."
#. (itstool) path: listitem/para
-#: C/index.docbook:1004
+#: C/index.docbook:989
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:1054
+#: C/index.docbook:1039
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1056
+#: C/index.docbook:1041
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:1065
+#: C/index.docbook:1050
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1067
+#: C/index.docbook:1052
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:1078
+#: C/index.docbook:1063
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:1087
+#: C/index.docbook:1072
msgid "Documenting symbols"
msgstr "Documentando símbolos"
#. (itstool) path: sect1/para
-#: C/index.docbook:1089
+#: C/index.docbook:1074
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:1097 C/index.docbook:1163
+#: C/index.docbook:1082 C/index.docbook:1148
msgid "General tags"
msgstr "Tags gerais"
#. (itstool) path: sect2/para
-#: C/index.docbook:1099
+#: C/index.docbook:1084
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:1104
+#: C/index.docbook:1089
msgid "Versioning Tags"
msgstr "Tags de versionamento"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1105
+#: C/index.docbook:1090
msgid "Since:"
msgstr "Since:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1107
+#: C/index.docbook:1092
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:1112
+#: C/index.docbook:1097
msgid "Deprecated:"
msgstr "Deprecated:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1114
+#: C/index.docbook:1099
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:1122
-#| msgid ""
-#| "You can add versioning information to all documentation elements to tell "
-#| "when an API was introduced, or when it was deprecated."
+#: C/index.docbook:1107
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:1128
+#: C/index.docbook:1113
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:1134
-#| msgid "@stability"
+#: C/index.docbook:1119
msgid "Stability Tags"
msgstr "Tags de estabilidade"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1135
+#: C/index.docbook:1120
msgid "Stability: Stable"
msgstr "Stability: Stable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1137
+#: C/index.docbook:1122
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:1144
+#: C/index.docbook:1129
msgid "Stability: Unstable"
msgstr "Stability: Unstable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1146
+#: C/index.docbook:1131
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:1152
+#: C/index.docbook:1137
msgid "Stability: Private"
msgstr "Stability: Private"
#. (itstool) path: listitem/para
-#: C/index.docbook:1154
+#: C/index.docbook:1139
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:1164
+#: C/index.docbook:1149
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1184 C/index.docbook:1194
-#| msgid "Installation"
+#: C/index.docbook:1169 C/index.docbook:1179
msgid "Annotations"
msgstr "Anotações"
#. (itstool) path: sect2/para
-#: C/index.docbook:1186
+#: C/index.docbook:1171
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"renderizadas com dicas de ferramentas descrevendo seu significados. As tags "
"são usadas pelo gobject-introspection para garantir associações (bindings) "
"de linguagens. Uma lista detalhada tags aceitas podem ser encontrada <ulink "
-"url=\"http://live.gnome.org/GObjectIntrospection/Annotations\" type=\"http\">no "
-"wiki</ulink>."
+"url=\"http://live.gnome.org/GObjectIntrospection/Annotations\" type=\"http"
+"\">no wiki</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1195
+#: C/index.docbook:1180
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1216 C/index.docbook:1245
+#: C/index.docbook:1201 C/index.docbook:1230
msgid "Function comment block"
msgstr "Bloco de comentário de função"
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1207
msgid ""
"Document whether returned objects, lists, strings, etc, should be freed/"
"unrefed/released."
"não referenciados/liberada."
#. (itstool) path: listitem/para
-#: C/index.docbook:1228
+#: C/index.docbook:1213
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:1233
+#: C/index.docbook:1218
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:1218 C/index.docbook:1304
+#: C/index.docbook:1203 C/index.docbook:1289
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Por favor, lembre-se de: <_:itemizedlist-1/>"
#. (itstool) path: sect2/para
-#: C/index.docbook:1240
+#: C/index.docbook:1225
msgid ""
"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
"private. They are treated like static functions."
msgstr ""
-"Gtk-doc presume que todos os símbolos (macros, funções) começando com \"_\" "
+"Gtk-doc presume que todos os símbolos (macros, funções) começando com “_” "
"são privadas. Elas são tratadas como funções estáticas."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1246
+#: C/index.docbook:1231
#, no-wrap
msgid ""
"\n"
" * @par2: descrição do parâmetro 2\n"
" * @...: uma lista de bars terminada em %NULL\n"
" *\n"
-" * A descrição da função vai aqui. Você pode usar @par1 para se referir a "
-"parâmetros\n"
-" * de forma que eles ficam em destaque na saída. Você também pode usar %"
-"constant\n"
-" * para constantes, nome_da_função2() para funções e #GtkWidget para links "
-"para\n"
+" * A descrição da função vai aqui. Você pode usar @par1 para se referir a parâmetros\n"
+" * de forma que eles ficam em destaque na saída. Você também pode usar %constant\n"
+" * para constantes, nome_da_função2() para funções e #GtkWidget para links para\n"
" * outras declarações (que pode ser documentada em outro lugar).\n"
" *\n"
" * Returns: um inteiro.\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1267
+#: C/index.docbook:1252
msgid "Function tags"
msgstr "Tags de função"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1268
+#: C/index.docbook:1253 C/index.docbook:1460
msgid "Returns:"
msgstr "Returns:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1270
+#: C/index.docbook:1255
msgid "Paragraph describing the returned result."
msgstr "Parágrafo descrevendo o resultado retornado."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1275
+#: C/index.docbook:1260
msgid "@...:"
msgstr "@...:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1277
+#: C/index.docbook:1262
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:1287 C/index.docbook:1289
+#: C/index.docbook:1272 C/index.docbook:1274
msgid "Property comment block"
msgstr "Bloco de comentário de propriedade"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1290
+#: C/index.docbook:1275
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1302 C/index.docbook:1321
+#: C/index.docbook:1287 C/index.docbook:1306
msgid "Signal comment block"
msgstr "Bloco de comentário de sinal"
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1293
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:1314
+#: C/index.docbook:1299
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:1322
+#: C/index.docbook:1307
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1339 C/index.docbook:1340
+#: C/index.docbook:1324 C/index.docbook:1325
msgid "Struct comment block"
msgstr "Bloco de comentário de struct"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1341
+#: C/index.docbook:1326
#, no-wrap
-#| msgid ""
-#| "\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"
msgid ""
"\n"
"/**\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1341
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:1362
+#: C/index.docbook:1347
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 ""
-"Se o primeiro campo for \"g_iface\", \"parent_instance\" ou \"parent_class\", ele "
+"Se o primeiro campo for “g_iface”, “parent_instance” ou “parent_class”, ele "
"será automaticamente considerado como privado e não precisará ser mencionado "
"no bloco de comentário."
#. (itstool) path: sect2/para
-#: C/index.docbook:1368
+#: C/index.docbook:1353
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:1380 C/index.docbook:1381
+#: C/index.docbook:1365 C/index.docbook:1366
msgid "Enum comment block"
msgstr "Bloco de comentário de enum"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1382
+#: C/index.docbook:1367
#, no-wrap
msgid ""
"\n"
"} Alguma coisa;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1399
+#: C/index.docbook:1384
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:1409
+#: C/index.docbook:1395
+msgid "Inline program documentation"
+msgstr "Documentação de programa em-linha"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1396
+msgid ""
+"You can document programs and their commandline interface using inline "
+"documentation."
+msgstr ""
+"Você pode documentar programas e sua interface de linha de comando usando "
+"documentação em-linha."
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1402
+msgid "Tags"
+msgstr "Tags"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1404
+msgid "PROGRAM"
+msgstr "PROGRAM"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1407
+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:1414
+msgid "@short_description:"
+msgstr "@short_description:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1416
+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:1423
+msgid "@synopsis:"
+msgstr "@synopsis:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1425
+msgid ""
+"Defines the arguments, or list of arguments that the program can take. "
+"(Optional)"
+msgstr ""
+"Define os argumentos, ou lista de argumentos, que o programa pode receber. "
+"(Opcional)"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1433
+msgid "@see_also:"
+msgstr "@see_also:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1435
+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:1442
+msgid "@arg:"
+msgstr "@arg:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1444
+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:1451
+msgid "Description:"
+msgstr "Description:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1453
+msgid "A longer description of the program."
+msgstr "Um descrição mais longa do programa."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1462
+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:1471
+msgid "Example of program documentation."
+msgstr "Exemplo de documentação de programa."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1472
+msgid "Program documentation block"
+msgstr "Bloco de documentação de programa"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1473
+#, 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 ""
+"\n"
+"/**\n"
+" * PROGRAM:programa-teste\n"
+" * @short_description: Um programa teste\n"
+" * @synopsis: programa-teste [*OPÇÕES*...] --arg1 *arg* *ARQUIVO*\n"
+" * @see_also: teste(1)\n"
+" * @--arg1 *arg*: define arg1 para *arg*\n"
+" * @--arg2 *arg*: define arg2 para *arg*\n"
+" * @-v, --version: Exibe o número da versão\n"
+" * @-h, --help: Exibe a mensagem de ajuda\n"
+" *\n"
+" * Descrição longa do programa.\n"
+" *\n"
+" * Returns: Zero no caso de sucesso, não-zero no caso de falha\n"
+" */\n"
+"int main(int argc, char *argv[])\n"
+"{\n"
+"\treturn 0;\n"
+"}\n"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1499
msgid "Useful DocBook tags"
msgstr "Tags úteis do DocBook"
#. (itstool) path: sect1/para
-#: C/index.docbook:1411
+#: C/index.docbook:1501
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:1420
+#: C/index.docbook:1510
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Tabela de hashes</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1416
+#: C/index.docbook:1506
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. "
"name. Spaces and underscores are converted to '-' to conform to SGML/XML."
msgstr ""
"Para vincular a outra seção nas documentações do GTK: <_:informalexample-1/> "
-"O fim do link é o ID do SGML/XML no item superior da páginao a qual você "
-"deseja vincular. Para a maioria das páginas isto é atualmente a parte (\"gtk"
-"\", \"gdk\", \"glib\") e, então, o título da página (\"Hash Tables\"). Para "
-"os widgets isso é apenas o nome da classe. Espaços e sublinhados são "
+"O fim do link é o ID do SGML/XML no item superior da página a qual você "
+"deseja vincular. Para a maioria das páginas isto é atualmente a parte "
+"(“gtk”, “gdk”, “glib”) e, então, o título da página (“Hash Tables”). Para os "
+"widgets isso é apenas o nome da classe. Espaços e sublinhados são "
"convertidos em '-' para estar em conformidade com SGML/XML."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1433
+#: C/index.docbook:1523
#, no-wrap
msgid ""
"\n"
"<function>...</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1430
+#: C/index.docbook:1520
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:1442
+#: C/index.docbook:1532
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1453
+#: C/index.docbook:1543
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1439
+#: C/index.docbook:1529
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:1472
+#: C/index.docbook:1562
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1469
+#: C/index.docbook:1559
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Para incluir listas com marcadores: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1492
+#: C/index.docbook:1582
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1489
+#: C/index.docbook:1579
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:1505
+#: C/index.docbook:1595
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1502
+#: C/index.docbook:1592
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "Para se referir a um tipo: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1514
+#: C/index.docbook:1604
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1511
+#: C/index.docbook:1601
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:1523
+#: C/index.docbook:1613
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1520
+#: C/index.docbook:1610
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:1532
+#: C/index.docbook:1622
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1529
+#: C/index.docbook:1619
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:1543
+#: C/index.docbook:1633
#, no-wrap
msgid ""
"\n"
"<emphasis>Isso é importante</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1540
+#: C/index.docbook:1630
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Para enfatizar um texto: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1552
+#: C/index.docbook:1642
#, no-wrap
msgid ""
"\n"
"<filename>/home/usuario/documentos</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1549
+#: C/index.docbook:1639
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Para nome de arquivos use: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1561
+#: C/index.docbook:1651
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1558
+#: C/index.docbook:1648
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "Para se referir a chaves use: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1571
+#: C/index.docbook:1661
msgid "Filling the extra files"
msgstr "Preenchendo os arquivos extras"
#. (itstool) path: chapter/para
-#: C/index.docbook:1573
+#: C/index.docbook:1663
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:1582
+#: C/index.docbook:1672
msgid "Editing the types file"
msgstr "Editando o arquivo de tipos"
#. (itstool) path: sect1/para
-#: C/index.docbook:1584
+#: C/index.docbook:1674
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:1593
+#: C/index.docbook:1683
msgid "Example types file snippet"
msgstr "Trecho de exemplo de arquivo de tipos"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1594
+#: C/index.docbook:1684
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1605
+#: C/index.docbook:1695
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"dist the types file nor have it under version control."
msgstr ""
"Desde o GTK-Doc 1.8, o <application>gtkdoc-scan</application> pode gerar "
-"esta lista para você. Basta adicionar \"--rebuild-types\" a SCAN_OPTIONS no "
+"esta lista para você. Basta adicionar “--rebuild-types” a SCAN_OPTIONS no "
"<filename>Makefile.am</filename>. Se você usar esta abordagem, você não "
"deveria distribuir o arquivo de tipos nem tê-lo sob um controle de versão."
#. (itstool) path: sect1/title
-#: C/index.docbook:1614
+#: C/index.docbook:1704
msgid "Editing the master document"
msgstr "Editando o documento mestre"
#. (itstool) path: sect1/para
-#: C/index.docbook:1616
+#: C/index.docbook:1706
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:1623
-#| 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."
+#: C/index.docbook:1713
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:1633
+#: C/index.docbook:1723
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:1642
+#: C/index.docbook:1732
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:1649
+#: C/index.docbook:1739
msgid "Master document header"
msgstr "Cabeçalho do documento mestre"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1650
+#: C/index.docbook:1740
#, no-wrap
msgid ""
"\n"
" <title>[Insira o título aqui]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1666
+#: C/index.docbook:1756
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:1672
-#| msgid "Editing the master document"
+#: C/index.docbook:1762
msgid "Optional part in the master document"
msgstr "Parte opcional do documento mestre"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1673
+#: C/index.docbook:1763
#, 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"
+" -->\n"
msgstr ""
"\n"
" <!-- habilite isso se você usa anotações do gobject introspection\n"
-" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback "
-"/></xi:include>\n"
-" --> \n"
+" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n"
+" -->\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1681
+#: C/index.docbook:1771
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 ""
"Finalmente você precisa adicionar nova seção sempre que você a introduzir. A "
-"ferramenta <link linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> vai "
-"lembrar você de arquivos xml recentemente gerados que ainda não foram "
+"ferramenta <link linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> "
+"vai lembrar você de arquivos xml recentemente gerados que ainda não foram "
"incluídos na documentação."
#. (itstool) path: example/title
-#: C/index.docbook:1689 C/index.docbook:1724
+#: C/index.docbook:1779 C/index.docbook:1814
msgid "Including generated sections"
msgstr "Incluindo seções geradas"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1690
+#: C/index.docbook:1780
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1702
+#: C/index.docbook:1792
msgid "Editing the section file"
msgstr "Editando o arquivo de seção"
#. (itstool) path: sect1/para
-#: C/index.docbook:1704
+#: C/index.docbook:1794
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:1710
-#| msgid ""
-#| "The section file is a plain text file with XML-like syntax (using tags). "
-#| "Blank lines are ignored and lines starting with a '#' are treated as "
-#| "comment lines."
+#: C/index.docbook:1800
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."
msgstr ""
"O arquivo de seção é uma arquivo texto simples com seções delimitadas por "
-"tags. Linhas em branco são ignoradas e linhas começando com um \"#\" são "
+"tags. Linhas em branco são ignoradas e linhas começando com um “#” são "
"tratadas como linhas de comentários."
#. (itstool) path: note/para
-#: C/index.docbook:1717
+#: C/index.docbook:1807
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:1725
+#: C/index.docbook:1815
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1742
-#| 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 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)."
+#: C/index.docbook:1832
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"lower case)."
msgstr ""
"A tag <FILE> ... </FILE> é usada para especificar o nome de "
-"arquivo, sem qualquer sufixo. Por exemplo, ao usar \"<FILE>gnome-"
-"config</FILE>\" resultará nas declarações da seção serem retornadas no "
+"arquivo, sem qualquer sufixo. Por exemplo, ao usar “<FILE>gnome-"
+"config</FILE>” resultará nas declarações da seção serem retornadas no "
"arquivo modelo <filename>tmpl/gnome-config.sgml</filename>, o qual será "
"convertido no arquivo DocBook XML <filename>xml/gnome-config.sgml</filename> "
-"ou no arquivo DocBook XML <filename>xml/gnome-config.xml</filename>. (O "
-"nome do arquivo HTML é baseado no nome do módulo e no título da seção ou, "
-"para GObjects, é baseado no nome da classe GObjects convertidos os "
-"caracteres para minúsculos)."
+"ou no arquivo DocBook XML <filename>xml/gnome-config.xml</filename>. (O nome "
+"do arquivo HTML é baseado no nome do módulo e no título da seção ou, para "
+"GObjects, é baseado no nome da classe GObjects convertidos os caracteres "
+"para minúsculos)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1754
+#: C/index.docbook:1844
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:1761
+#: C/index.docbook:1851
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
msgstr ""
"Você pode agrupar itens na seção usando a tag <SUBSECTION>. "
"Atualmente, ela retorna uma linha em branco entre as subseções na seção de "
-"sinópse. Você também pode usar <SUBSECTION Standard> para declarações "
+"sinopse. Você também pode usar <SUBSECTION Standard> para declarações "
"padrão do GObject (ex.: as funções como g_object_get_type e macros como "
"G_OBJECT(), G_IS_OBJECT() etc.). Atualmente, estas são deixadas fora da "
"documentação. Você também pode usar <SUBSECTION Private> para "
"padrão ou pública depende se há entradas públicas (variáveis, vmethods)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1780
+#: C/index.docbook:1870
msgid ""
"You can also use <INCLUDE> ... </INCLUDE> to specify the "
"#include files which are shown in the synopsis sections. It contains a comma-"
"If you set it within a section, it only applies to that section."
msgstr ""
"Você também pode usar <INCLUDE> ... </INCLUDE> para especificar "
-"os arquivos #include que são mostrados nas seções de sinópse. Ela contém uma "
+"os arquivos #include que são mostrados nas seções de sinopse. Ela contém uma "
"lista separada por vírgula de arquivos #include, sem os sinais de maior que "
"e menor que. Se você define-a fora de quaisquer seções, ela age para todas "
"as seções até o fim do arquivo. Se você define-a em uma seção, ela só vai se "
"aplicar àquela seção."
#. (itstool) path: chapter/title
-#: C/index.docbook:1794
+#: C/index.docbook:1884
msgid "Controlling the result"
msgstr "Controlando o resultado"
#. (itstool) path: chapter/para
-#: C/index.docbook:1796
+#: C/index.docbook:1886
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:1805
+#: C/index.docbook:1895
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:1814
+#: C/index.docbook:1904
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:1821
+#: C/index.docbook:1911
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:1829
+#: C/index.docbook:1919
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:1836
+#: C/index.docbook:1926
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:1845
+#: C/index.docbook:1935
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:1860
+#: C/index.docbook:1950
msgid "Modernizing the documentation"
msgstr "Modernizando a documentação"
#. (itstool) path: chapter/para
-#: C/index.docbook:1862
+#: C/index.docbook:1952
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:1868
+#: C/index.docbook:1958
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1870
+#: C/index.docbook:1960
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:1875
+#: C/index.docbook:1965
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:1886
+#: C/index.docbook:1976
#| 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>."
+#| "flavour no-tmpl</option> in <filename>configure.ac</filename>. If you "
+#| "don't have a <filename class=\"directory\">tmpl</filename> checked into "
+#| "you source control system and haven't yet switched, just add the flag to "
+#| "<filename>configure.ac</filename> and you are done."
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 you source "
+"<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 ""
"A versão 1.8 já introduziu a sintaxe para documentação seções nos fontes em "
-"vez dos arquivos separados sob <filename class=\"directory\">tmpl</filename>. "
-"Essa versão adiciona opções para alternar todo o módulo de documentação para "
-"não usar a etapa de compilação extra do tmpl, usando <option>--flavour no-"
-"tmpl</option> no <filename>configure.ac</filename>. Se você não possui um "
+"vez dos arquivos separados sob <filename class=\"directory\">tmpl</filename>"
+". Essa versão adiciona opções para alternar todo o módulo de documentação "
+"para não usar a etapa de compilação extra do tmpl, usando <option>--flavour "
+"no-tmpl</option> no <filename>configure.ac</filename>. Se você não possui um "
"<filename class=\"directory\">tmpl</filename> no seu sistema de controle de "
"versão e ainda não trocou, basta adicionar uma opção ao "
"<filename>configure.ac</filename> e está resolvido."
#. (itstool) path: sect1/title
-#: C/index.docbook:1898
+#: C/index.docbook:1988
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:1900
+#: C/index.docbook:1990
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:1911
+#: C/index.docbook:2001
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:1917
+#: C/index.docbook:2007
msgid "Enable gtkdoc-check"
msgstr "Habilitar gtkdoc-check"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1918
+#: C/index.docbook:2008
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1913
+#: C/index.docbook:2003
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:1931
+#: C/index.docbook:2021
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:1933
+#: C/index.docbook:2023
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:1943
-#| msgid "GTK-Doc 1.20"
+#: C/index.docbook:2033
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:1953
+#: C/index.docbook:2043
msgid "Use pre-generated entities"
msgstr "Usando entradas geradas previamente"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1954
+#: C/index.docbook:2044
#, no-wrap
msgid ""
"\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 % local.common.attrib \"xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'\">\n"
" <!ENTITY % gtkdocentities SYSTEM \"xml/gtkdocentities.ent\">\n"
" %gtkdocentities;\n"
"]>\n"
" <releaseinfo>\n"
" para &versão-pacote;.\n"
" A última versão desta documentação pode ser encontra on-line em\n"
-" <ulink role=\"online-location\" url=\"http://[SERVIDOR]/&nome-"
-"pacote;/index.html\">http://[SERVIDOR]/&nome-pacote;/</ulink>.\n"
+" <ulink role=\"online-location\" url=\"http://[SERVIDOR]/&nome-pacote;/index.html\">http://[SERVIDOR]/&nome-pacote;/</ulink>.\n"
" </releaseinfo>\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1945
+#: C/index.docbook:2035
+#| 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 any 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/>"
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 any example that shows how "
+"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/>"
"xml nos arquivos xml gerados. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1979
+#: C/index.docbook:2069
msgid "Documenting other interfaces"
msgstr "Documentando outras interfaces"
#. (itstool) path: chapter/para
-#: C/index.docbook:1981
+#: C/index.docbook:2071
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:1988
+#: C/index.docbook:2078
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:1990
+#: C/index.docbook:2080
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:1997
+#: C/index.docbook:2087
msgid "Document the tool"
msgstr "Documentar a ferramenta"
#. (itstool) path: sect2/para
-#: C/index.docbook:1999
+#: C/index.docbook:2089
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:2009
+#: C/index.docbook:2099
msgid "Adding the extra configure check"
msgstr "Adicionando a verificação extra ao configure"
#. (itstool) path: example/title
-#: C/index.docbook:2012 C/index.docbook:2030
+#: C/index.docbook:2102 C/index.docbook:2120
msgid "Extra configure checks"
msgstr "Verificações extra no configure"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2013
+#: C/index.docbook:2103
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2027
+#: C/index.docbook:2117
msgid "Adding the extra makefile rules"
msgstr "Adicionando as regras extras ao makefile"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2031
+#: C/index.docbook:2121
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2053
+#: C/index.docbook:2143
msgid "DBus interfaces"
msgstr "Interfaces DBus"
#. (itstool) path: sect1/para
-#: C/index.docbook:2055
+#: C/index.docbook:2145
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:2064
+#: C/index.docbook:2154
msgid "Frequently asked questions"
msgstr "Perguntas frequentes"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2068
+#: C/index.docbook:2158
msgid "Question"
msgstr "Questão"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2069
+#: C/index.docbook:2159
msgid "Answer"
msgstr "Resposta"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2071
+#: C/index.docbook:2161
msgid "No class hierarchy."
msgstr "Sem hierarquia de classe."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2072
+#: C/index.docbook:2162
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:2078
+#: C/index.docbook:2168
msgid "Still no class hierarchy."
msgstr "Ainda sem hierarquia."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2079
+#: C/index.docbook:2169
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:2085
+#: C/index.docbook:2175
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:2086
+#: C/index.docbook:2176
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:2093
+#: C/index.docbook:2183
msgid "No symbol index."
msgstr "Nenhum símbolo de índice."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2094
+#: C/index.docbook:2184
msgid ""
"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
"index that xi:includes the generated index?"
msgstr ""
"O <filename><pacote>-docs.{xml,sgml}</filename> contém um índice que "
-"\"xi:inclui\" o índice gerado?"
+"“xi:inclui” o índice gerado?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2100
+#: C/index.docbook:2190
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:2101
+#: C/index.docbook:2191
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:2107
+#: C/index.docbook:2197
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:2108
+#: C/index.docbook:2198
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
msgstr ""
-"A nova página foi \"xi:incluída\" do <filename><pacote>-docs.{xml,sgml}"
-"</filename>?"
+"A nova página foi “xi:incluída” do <filename><pacote>-docs.{xml,sgml}</"
+"filename>?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2114
+#: C/index.docbook:2204
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:2115
+#: C/index.docbook:2205
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:2123
+#: C/index.docbook:2213
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:2124
-#| 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."
+#: C/index.docbook:2214
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 "
msgstr ""
"Se o tipo está listado no <filename><pacote>.hierarchy</filename>, mas "
"não em <filename>xml/tree_index.sgml</filename>, então certifique-se de que "
-"o tipo está colocado corretamente no "
-"<filename><pacote>-sections.txt</filename>. Se a instância do tipo "
-"(ex.: <type>GtkWidget</type>) não está listada ou incidentalmente marcada "
-"como privada, ela não será mostrada."
+"o tipo está colocado corretamente no <filename><pacote>-sections.txt</"
+"filename>. Se a instância do tipo (ex.: <type>GtkWidget</type>) não está "
+"listada ou incidentalmente marcada como privada, ela não será mostrada."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2133
+#: C/index.docbook:2223
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:2134
+#: C/index.docbook:2224
msgid ""
"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
"from <filename><package>-docs.{xml,sgml}</filename>."
msgstr ""
-"Verifique se <filename>xml/annotation-glossary.xml</filename> está \"xi:"
-"incluído\" de <filename><pacote>-docs.{xml,sgml}</filename>."
+"Verifique se <filename>xml/annotation-glossary.xml</filename> está “xi:"
+"incluído” de <filename><pacote>-docs.{xml,sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2142
+#: C/index.docbook:2232
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:2143
+#: C/index.docbook:2233
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
"fonte."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2148
+#: C/index.docbook:2238
msgid "multiple \"IDs\" for constraint linkend: XYZ"
-msgstr "Múltiplos \"IDs\" para restrições do fim do link XYZ"
+msgstr "múltiplos “IDs” para restrições do fim do link XYZ"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2149
+#: C/index.docbook:2239
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"sections.txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2152
+#: C/index.docbook:2242
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"correspondeu."
#. (itstool) path: chapter/title
-#: C/index.docbook:2159
+#: C/index.docbook:2249
msgid "Tools related to gtk-doc"
msgstr "Ferramentas relacionadas ao gtk-doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2161
+#: C/index.docbook:2251
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:2166
+#: C/index.docbook:2256
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."
"Usar na <link linkend=\"fdl-title-page\">Página de Título</link> (e nas "
"capas, se existirem) um título distinto em relação ao do <link linkend=\"fdl-"
"document\">Documento</link>, e daqueles de versões anteriores (os quais "
-"devem, na existência de algum, ser listados na seção \"Histórico\" do "
+"devem, na existência de algum, ser listados na seção “Histórico” do "
"Documento). Você pode usar o mesmo título de uma versão anterior se o editor "
"original daquela versão conceder-lhe permissão."
#. (itstool) path: sect1/para
#: C/index.docbook:527 C/fdl-appendix.xml:527
-#| 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 distribute it "
"individually under this License, provided you insert a copy of this License "
msgstr ""
"Usar na <_:link-1/> (e nas capas, se existirem) um título distinto em "
"relação ao do <_:link-2/>, e daqueles de versões anteriores (os quais devem, "
-"na existência de algum, ser listados na seção \"Histórico\" do Documento). "
+"na existência de algum, ser listados na seção “Histórico” do Documento). "
"Você pode usar o mesmo título de uma versão anterior se o editor original "
"daquela versão conceder-lhe permissão."
msgstr ""
"Se seu documento contiver exemplos não-triviais de código de programação, "
"recomendamos publicar estes exemplos paralelamente, sob a licença de "
-"software livre que você escolher, como por exemplo a <_:ulink-1/> (GNU "
-"General Public License), para permitir seu uso em software livre."
+"software livre que você escolher, como, por exemplo, a <_:ulink-1/>, para "
+"permitir seu uso em software livre."
+
+#~ 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>Gerando os arquivos \"template\".</guilabel> "
+#~ "<application>gtkdoc-mktmpl</application> cria uma quantidade de arquivos "
+#~ "no subdiretório <filename class=\"directory\">tmpl/</filename>, usando a "
+#~ "informação coletada na primeira etapa. (Note que ele pode ser executado "
+#~ "repetidas vezes e vai tentar garantir que nenhuma documentação será "
+#~ "perdida, jamais.)"
+
+#~ 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 ""
+#~ "Desde o GTK-Doc 1.9, os modelos (\"templates\") podem ser evitados. Nós "
+#~ "encorajamos as pessoas a manter a documentação no código. "
+#~ "<application>gtkdocize</application> possui suporte a uma opção <option>--"
+#~ "flavour no-tmpl</option> que escolhe um makefile que ignora totalmente o "
+#~ "uso de tmpl. Se você nunca alterou o arquivo em tmpl manualmente, por "
+#~ "favor remova o diretório (ex.: do sistema de controle de versão)."
#~ msgid "1.20"
#~ msgstr "1.20"
<revhistory>
<revision>
- <revnumber>1.24.1</revnumber>
- <date>30 May 2015</date>
+ <revnumber>1.25.1</revnumber>
+ <date>21 March 2016</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development version</revremark>
+ </revision>
+ <revision>
+ <revnumber>1.25</revnumber>
+ <date>21 March 2016</date>
<authorinitials>ss</authorinitials>
- <revremark>development version</revremark>
+ <revremark>bug fixes, test cleanups</revremark>
</revision>
<revision>
<revnumber>1.24</revnumber>
</para>
</listitem>
- <listitem>
- <para>
- <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.)
- </para>
- <note>
- <para>
- 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).
- </para>
- </note>
- </listitem>
-
<listitem>
<para>
<guilabel>Generating the XML and HTML/PDF.</guilabel>
document called <filename><package>.pdf</filename>.
</para>
<para>
- Files in <filename class="directory">xml/</filename> and
+ 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>
Furthermore it is recommended that you have the following line inside
- you <filename>configure.ac</filename> script.
+ 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>
<title>Integration with automake</title>
<para>
- First copy the <filename>Makefile.am</filename> from the
+ 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.
+ 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>
<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.
+ hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<title>Limitations</title>
<para>
Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
+ <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
<code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
</para>
</note>
<para>
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>
+ 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>.
</para>
<para>
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
+ name given here should match the <FILE> tag in the
<filename><package>-sections.txt</filename> file.
</para>
</listitem>
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
+ of the supported tags can be found on
<ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
</para>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Inline program documentation</title>
+ <para>
+ You can document programs and their commandline interface using inline
+ documentation.
+ </para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>
+ Defines the start of a program documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>
+ Defines a short description of the program. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>
+ Defines the arguments, or list of arguments that the program can take.
+ (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>
+ See Also manual page section. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>
+ Argument(s) passed to the program and their description. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ A longer description of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Returns:</term>
+ <listitem>
+ <para>
+ Specificy what value(s) the program returns. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Example of program documentation.</title>
+ <example><title>Program documentation block</title>
+ <programlisting><![CDATA[
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+]]></programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>Useful DocBook tags</title>
In addition a few option elements are created in commented form. You can
review these and enable them as you like.
</para>
-
+
<para>
<example><title>Optional part in the master document</title>
<programlisting><![CDATA[
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
+ -->
]]></programlisting>
</example>
</para>
-
+
<para>
Finally you need to add new section whenever you introduce one. The
<link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
Blank lines are ignored and lines starting with a '#' are treated as
comment lines.
</para>
-
+
<note>
<para>
While the tags make the file look like xml, it is not. Please do not
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizing the documentation</title>
-
+
<para>
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.
</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
When using xml instead of sgml, one can actually name the master
document <filename><package>-docs.xml</filename>.
</para>
-
+
<para>
This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
in <filename>Makefile.am</filename>. When this is enabled, the
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
+ maintained section file can be as simple as running
<code>meld <package>-decl-list.txt <package>-sections.txt</code>.
</para>
-
+
<para>
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 you source control system and haven't yet switched, just
+ checked into your source control system and haven't yet switched, just
add the flag to <filename>configure.ac</filename> and you are done.
</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
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 any example that shows how the entity file is included
+ 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.
<year>2000</year><holder>Free Software Foundation, Inc.</holder>
</copyright>
<legalnotice id="fdl-legalnotice">
- <para>
- <address>Free Software Foundation, Inc. <street>51 Franklin Street,
+ <para><address>Free Software Foundation, Inc. <street>51 Franklin Street,
Suite 330</street>, <city>Boston</city>, <state>MA</state>
- <postcode>02110-1301</postcode> <country>USA</country></address>
- Everyone is permitted to copy and distribute verbatim copies of this
- license document, but changing it is not allowed.
- </para>
+ <postcode>02110-1301</postcode> <country>USA</country></address>. Alla är tillåtna kopiera och distribuera ordagranna kopior av detta licensdokument, men att ändra det är ej tillåtet.</para>
</legalnotice>
</appendixinfo>
<title>GNU Free Documentation License</title>
<sect1 id="fdl-preamble">
<title>0. BAKGRUND</title>
- <para>
- The purpose of this License is to make a manual, textbook, or
- other written document <quote>free</quote> in the sense of
- freedom: to assure everyone the effective freedom to copy and
- redistribute it, with or without modifying it, either
- commercially or noncommercially. Secondarily, this License
- preserves for the author and publisher a way to get credit for
- their work, while not being considered responsible for
- modifications made by others.
- </para>
+ <para>Syftet med denna licens är att göra en handbok, bok, eller annat praktiskt och användbart dokument <quote>fritt</quote> som i frihet: att försäkra var och en den faktiska friheten att kopiera och sprida det vidare, med eller utan förändringar, antingen kommersiellt eller ideellt. Sekundärt bevarar denna licens ett sätt för författaren och förläggaren att få ära för deras arbete utan att de anses vara ansvariga för förändringar gjorda av andra.</para>
- <para>
- This License is a kind of <quote>copyleft</quote>, which means
- that derivative works of the document must themselves be free in
- the same sense. It complements the GNU General Public License,
- which is a copyleft license designed for free software.
- </para>
+ <para>Denna Licens är en sorts <quote>copyleft</quote>, vilket betyder att derivativa verk av detta dokument själva måste vara fria på samma sätt. Den kompletterar GNU General Public License, som är en copyleft-licens utformad för fri programvara.</para>
<para>Vi har utformat denna licens för att den skall användas för handböcker till fri programvara, eftersom fri programvara behöver fri dokumentation: ett fritt program bör ha en handbok som erbjuder samma friheter som programmet gör. Men denna licens är inte begränsad till programvaruhandböcker; den kan användas för vilket textverk som helst oavsett ämne eller huruvida det är en utgiven, tryckt bok. Vi rekommenderar denna licens huvudsakligen för alla verk vars syfte är instruktion eller referens.</para>
</sect1>
<sect1 id="fdl-section1">
- <title>TILLÄMPNINGSOMRÅDE OCH DEFINITIONER</title>
- <para id="fdl-document">
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be
- distributed under the terms of this License. The
- <quote>Document</quote>, below, refers to any such manual or
- work. Any member of the public is a licensee, and is addressed
- as <quote>you</quote>.
- </para>
+ <title>1. TILLÄMPNINGSOMRÅDE OCH DEFINITIONER</title>
+ <para id="fdl-document">Denna licens [det engelska originalet] gäller för varje handbok eller annat verk, oavsett uttrycksform, som innehåller ett meddelande där upphovsrättsinnehavaren stadgat att verket kan spridas enligt villkoren i GNU Free Documentation License. Ett sådant meddelande ger en internationell frihet utan krav på ersättning och utan tidsbegränsning att använda verket under villkoren i denna licens [det engelska originalet]. <quote>Dokument</quote> nedan syftar på godtycklig handbok eller verk. Var och en är licenstagare och benämns som <quote>du</quote>.</para>
- <para id="fdl-modified">
- A <quote>Modified Version</quote> of the Document means any work
- containing the Document or a portion of it, either copied
- verbatim, or with modifications and/or translated into another
- language.
- </para>
+ <para id="fdl-modified">En <quote>förändrad version</quote> av dokumentet avser varje verk som innehåller dokumentet eller en del av det, antingen ordagranna kopior, eller med ändringar och/eller översatt till ett annat språk.</para>
- <para id="fdl-secondary">
- A <quote>Secondary Section</quote> is a named appendix or a
- front-matter section of the <link linkend="fdl-document">Document</link> that deals exclusively
- with the relationship of the publishers or authors of the
- Document to the Document's overall subject (or to related
- matters) and contains nothing that could fall directly within
- that overall subject. (For example, if the Document is in part a
- textbook of mathematics, a Secondary Section may not explain any
- mathematics.) The relationship could be a matter of historical
- connection with the subject or with related matters, or of
- legal, commercial, philosophical, ethical or political position
- regarding them.
- </para>
+ <para id="fdl-secondary">Ett <quote>sekundärt avsnitt</quote> är en märkt bilaga eller förord till <link linkend="fdl-document">dokumentet</link> som exklusivt behandlar förhållandet mellan dokumentets förläggare eller författare och dokumentets huvudsakliga ämne (eller till relaterade ämnen) och som inte innehåller något som direkt faller under det huvudsakliga ämnet. (Således, om dokumentet delvis är en lärobok i matematik så får ett sekundärt avsnitt inte förklara någon matematik.) Förhållandet kan vara en historisk koppling till ämnet eller något relaterat, eller en juridisk, kommersiell, filosofisk, etisk eller politisk ställning till det.</para>
- <para id="fdl-invariant">
- The <quote>Invariant Sections</quote> are certain <link linkend="fdl-secondary"> Secondary Sections</link> whose titles
- are designated, as being those of Invariant Sections, in the
- notice that says that the <link linkend="fdl-document">Document</link> is released under this
- License.
- </para>
+ <para id="fdl-invariant">De <quote>oföränderliga avsnitten</quote> är <link linkend="fdl-secondary">sekundära avsnitt</link> vars titlar är angivna som oföränderliga avsnitt i meddelandet som stadgar att <link linkend="fdl-document">Dokument</link> är utgivet under denna licens [det engelska originalet].</para>
- <para id="fdl-cover-texts">
- The <quote>Cover Texts</quote> are certain short passages of
- text that are listed, as Front-Cover Texts or Back-Cover Texts,
- in the notice that says that the <link linkend="fdl-document">Document</link> is released under this
- License.
- </para>
+ <para id="fdl-cover-texts"><quote>Omslagstexterna</quote> är speciella korta ordföljder som är listade som framsidestexter eller baksidestexter i meddelandet som stadgar att <link linkend="fdl-document">Dokument</link> är utgivet under denna licens [det engelska originalet].</para>
- <para id="fdl-transparent">
- A <quote>Transparent</quote> copy of the <link linkend="fdl-document"> Document</link> means a machine-readable
- copy, represented in a format whose specification is available
- to the general public, whose contents can be viewed and edited
- directly and straightforwardly with generic text editors or (for
- images composed of pixels) generic paint programs or (for
- drawings) some widely available drawing editor, and that is
- suitable for input to text formatters or for automatic
- translation to a variety of formats suitable for input to text
- formatters. A copy made in an otherwise Transparent file format
- whose markup has been designed to thwart or discourage
- subsequent modification by readers is not Transparent. A copy
- that is not <quote>Transparent</quote> is called
- <quote>Opaque</quote>.
- </para>
+ <para id="fdl-transparent">En <quote>transparent</quote> kopia av <link linkend="fdl-document">Dokument</link> är en maskinläsbar kopia, representerad i ett format vars specifikation finns tillgänglig för allmänheten, som lämpar sig för att revidera dokumentet på ett enkelt sätt med generella textredigeringsprogram eller (för pixelbaserade bilder) generella grafikprogram eller (för ritningar) något väl tillgängligt ritprogram, och som är passande som indata till textformaterare eller för automatisk konvertering till en mängd format som passar som indata till textformaterare. En kopia i ett för övrigt transparent filformat vars markeringar, eller avsaknad av markeringar, har ordnats för att hindra eller motverka att vidare förändring vidtas av läsare är inte transparent. En kopia som inte är <quote>transparent</quote> kallas <quote>opak</quote>.</para>
- <para>Exempel på passande format för transparenta kopior innefattar ren ASCII utan markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript eller PDF utformat för mänsklig förändring. Exempel på transparenta bildformat innefattar PNG, XCF och JPG. Opaka format innefattar leverantörsspecifika format som bara kan läsas och editeras med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/eller verktyg för behandling inte finns allmänt tillgängliga, och den maskingenererade HTML, PostScript eller PDF som produceras av vissa ordbehandlare enbart avsett som utdata.</para>
+ <para>Exempel på passande format för transparenta kopior innefattar ren ASCII utan markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript eller PDF utformat för mänsklig förändring. Opaka format innefattar Postscript, PDF, leverantörsspecifika format som bara kan läsas och editeras med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/eller verktyg för behandling inte finns allmänt tillgängliga, och den maskingenererade HTML som produceras av vissa ordbehandlare enbart avsett som utdata.</para>
- <para id="fdl-title-page">
- The <quote>Title Page</quote> means, for a printed book, the
- title page itself, plus such following pages as are needed to
- hold, legibly, the material this License requires to appear in
- the title page. For works in formats which do not have any title
- page as such, <quote>Title Page</quote> means the text near the
- most prominent appearance of the work's title, preceding the
- beginning of the body of the text.
- </para>
+ <para id="fdl-title-page"><quote>Titelsidan</quote> innebär, för en tryckt bok, titelsidan själv, och sådana därpå följande sidor som krävs för att göra det material som enligt denna licens skall synas på titelsidan läsbart. För verk i sådana format som inte har någon egentlig titelsida, avses med <quote>Titelsidan</quote> den text som är närmast den mest framstående förekomsten av verkets titel, föregående den huvudsakliga textmassan.</para>
</sect1>
<sect1 id="fdl-section2">
<title>2. ORDAGRANN KOPIERING</title>
- <para>
- You may copy and distribute the <link linkend="fdl-document">Document</link> in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that
- you add no other conditions whatsoever to those of this
- License. You may not use technical measures to obstruct or
- control the reading or further copying of the copies you make or
- distribute. However, you may accept compensation in exchange for
- copies. If you distribute a large enough number of copies you
- must also follow the conditions in <link linkend="fdl-section3">section 3</link>.
- </para>
+ <para>Du äger kopiera och sprida <link linkend="fdl-document">Dokument</link> på valfritt medium, antingen kommersiellt eller ideellt, förutsatt att denna licens [det engelska originalet], upphovsrättsklausul, och meddelandet som stadgar att GNU Free Documentation License gäller för dokumentet finns med på alla kopior, och att du inte lägger till några som helst andra villkor än de som ingår i denna licens. Du äger inte vidta tekniska åtgärder för att begränsa eller kontrollera läsande eller vidare kopiering av de kopior du skapar eller sprider. Dock äger du ta emot kompensation i utbyte mot kopior. Om du sprider tillräckligt många kopior måste du också följa villkoren i <link linkend="fdl-section3">paragraf 3</link>.</para>
<para>Du äger också låna ut kopior, under samma villkor som ovan, och du äger visa kopior offentligt.</para>
</sect1>
<sect1 id="fdl-section3">
<title>3. OMFATTANDE KOPIERING</title>
- <para>
- If you publish printed copies of the <link linkend="fdl-document">Document</link> numbering more than 100,
- and the Document's license notice requires <link linkend="fdl-cover-texts">Cover Texts</link>, you must enclose
- the copies in covers that carry, clearly and legibly, all these
- Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also
- clearly and legibly identify you as the publisher of these
- copies. The front cover must present the full title with all
- words of the title equally prominent and visible. You may add
- other material on the covers in addition. Copying with changes
- limited to the covers, as long as they preserve the title of the
- <link linkend="fdl-document">Document</link> and satisfy these
- conditions, can be treated as verbatim copying in other
- respects.
- </para>
+ <para>Om du publicerar tryckta kopior (eller kopior i medier som normalt har tryckta omslag) av <link linkend="fdl-document">Dokument</link>, i en upplaga överstigande 100 exemplar, och dokumentets licensmeddelande kräver <link linkend="fdl-cover-texts">Omslagstexterna</link>, så måste du förse kopiorna med omslag som, klart och tydligt, visar alla omslagstexter: framsidestexter på framsidan och baksidestexter på baksidan. Båda omslagen måste klart och tydligt identifiera dig som utgivare av dessa kopior. Framsidan måste presentera dokumentets hela titel, med alla ord i titeln lika framträdande och synliga. Du äger lägga till ytterligare stoff på omslagen. Kopiering med förändringar gjorda bara på omslaget, så länge som de bevarar titeln för <link linkend="fdl-document">Dokument</link> och i övrigt uppfyller dessa krav kan anses vara ordagrann kopiering i andra avseenden.</para>
<para>Om de obligatoriska texterna för något omslag är för omfattande för att rymmas i läsbart skick skall du placera de första (så många som får plats) på det egentliga omslaget, och fortsätta med resten på de direkt intilliggande sidorna.</para>
- <para>
- If you publish or distribute <link linkend="fdl-transparent">Opaque</link> copies of the <link linkend="fdl-document">Document</link> numbering more than 100,
- you must either include a machine-readable <link linkend="fdl-transparent">Transparent</link> copy along with
- each Opaque copy, or state in or with each Opaque copy a
- publicly-accessible computer-network location containing a
- complete Transparent copy of the Document, free of added
- material, which the general network-using public has access to
- download anonymously at no charge using public-standard network
- protocols. If you use the latter option, you must take
- reasonably prudent steps, when you begin distribution of Opaque
- copies in quantity, to ensure that this Transparent copy will
- remain thus accessible at the stated location until at least one
- year after the last time you distribute an Opaque copy (directly
- or through your agents or retailers) of that edition to the
- public.
- </para>
+ <para>Om du publicerar <link linkend="fdl-transparent">opak</link>a kopior av <link linkend="fdl-document">Dokument</link> i upplagor om mer än 100, måste du antingen bifoga en maskinläsbar <link linkend="fdl-transparent">transparent</link> kopia med varje opak kopia, eller ange i eller med varje opak kopia en nätverksadress som är tillgänglig för den allmänna nätverksanvändande massan där man, med öppet standardiserade protokoll, anonymt och utan kostnad kan ladda ner en komplett transparent kopia av dokumentet, utan extra material. Om du väljer det senare alternativet, måste du vidta skäliga åtgärder, när du börjar sprida opaka kopior i kvantitet, för att denna transparenta kopia skall förbli tillgänglig på angivna platsen till åtminstone ett år efter den sista gången du spred en opak kopia (direkt eller via ombud eller återförsäljare) av den utgåvan till allmänheten.</para>
- <para>
- It is requested, but not required, that you contact the authors
- of the <link linkend="fdl-document">Document</link> well before
- redistributing any large number of copies, to give them a chance
- to provide you with an updated version of the Document.
- </para>
+ <para>Det är önskvärt, men inte ett krav, att du kontaktar författarna till <link linkend="fdl-document">Dokument</link> i god tid innan du sprider något större antal kopior, för att ge dem en chans att förse dig med en uppdaterad version av dokumentet.</para>
</sect1>
<sect1 id="fdl-section4">
<title>4. FÖRÄNDRINGAR</title>
- <para>
- You may copy and distribute a <link linkend="fdl-modified">Modified Version</link> of the <link linkend="fdl-document">Document</link> under the conditions of
- sections <link linkend="fdl-section2">2</link> and <link linkend="fdl-section3">3</link> above, provided that you release
- the Modified Version under precisely this License, with the
- Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version
- to whoever possesses a copy of it. In addition, you must do
- these things in the Modified Version:
- </para>
+ <para>Du äger kopiera och sprida en <link linkend="fdl-modified">förändrad version</link> av <link linkend="fdl-document">Dokument</link> under de villkor som beskrivs i paragraf <link linkend="fdl-section2">2</link> och <link linkend="fdl-section3">3</link> av GNU Free Documentation License, förutsatt att du släpper den förändrade versionen under exakt denna licens, och att den förändrade versionen antar dokumentets roll, och således medger spridning och förändring av den förändrade versionen till envar som erhåller en kopia av den. Utöver detta måste du göra följande med den ändrade versionen:</para>
<itemizedlist mark="opencircle">
<listitem>
<formalpara>
<title>A</title>
- <para>
- Use in the <link linkend="fdl-title-page">Title
- Page</link> (and on the covers, if any) a title distinct
- from that of the <link linkend="fdl-document">Document</link>, and from those of
- previous versions (which should, if there were any, be
- listed in the History section of the Document). You may
- use the same title as a previous version if the original
- publisher of that version gives permission.
- </para>
+ <para>På <link linkend="fdl-title-page">Titelsidan</link> (och omslagen om det finns några) använda en titel skild från den som [original]<link linkend="fdl-document">Dokument</link> har, och skild från tidigare versioners titel (som skall, om det finns några, finnas listade i historikavsnittet i dokumentet). Du äger använda samma titel som det föregående dokumentet om den ursprungliga utgivaren ger sitt tillstånd.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>B</title>
- <para>
- List on the <link linkend="fdl-title-page">Title
- Page</link>, as authors, one or more persons or entities
- responsible for authorship of the modifications in the
- <link linkend="fdl-modified">Modified Version</link>,
- together with at least five of the principal authors of
- the <link linkend="fdl-document">Document</link> (all of
- its principal authors, if it has less than five).
- </para>
+ <para>Lista på <link linkend="fdl-title-page">Titelsidan</link>, som författare, en eller flera personer eller juridiska personer som ansvarat för förändringarna i <link linkend="fdl-modified">förändrad version</link>, tillsammans med minst fem av de huvudsakliga författarna av <link linkend="fdl-document">Dokument</link> (alla dess huvudsakliga författare, om det har mindre än fem).</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>C</title>
- <para>
- State on the <link linkend="fdl-title-page">Title
- Page</link> the name of the publisher of the <link linkend="fdl-modified">Modified Version</link>, as the
- publisher.
- </para>
+ <para>Ange namnet på utgivaren av <link linkend="fdl-title-page">Titelsidan</link>, som utgivare, på <link linkend="fdl-modified">förändrad version</link>.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>D</title>
- <para>
- Preserve all the copyright notices of the <link linkend="fdl-document">Document</link>.
- </para>
+ <para>Bibehålla alla upphovsrättsklausuler för <link linkend="fdl-document">Dokument</link>.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>F</title>
- <para>
- Include, immediately after the copyright notices, a
- license notice giving the public permission to use the
- <link linkend="fdl-modified">Modified Version</link> under
- the terms of this License, in the form shown in the
- Addendum below.
- </para>
+ <para>Direkt efter upphovsrättsklausulerna innefatta ett meddelande som ger allmänheten tillstånd att använda <link linkend="fdl-modified">förändrad version</link> under villkoren i denna licens [det engelska originalet] i den form som visas i Tillägg nedan.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>G</title>
- <para>
- Preserve in that license notice the full lists of <link linkend="fdl-invariant"> Invariant Sections</link> and
- required <link linkend="fdl-cover-texts">Cover
- Texts</link> given in the <link linkend="fdl-document">Document's</link> license notice.
- </para>
+ <para>I meddelandet om licensen bevara den fullständiga listan över <link linkend="fdl-invariant">oföränderliga avsnitten</link> och obligatoriska <link linkend="fdl-cover-texts">Omslagstexterna</link> som finns i <link linkend="fdl-document">dokumentets</link> meddelande om licensen.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>I</title>
- <para>
- Preserve the section entitled <quote>History</quote>, and
- its title, and add to it an item stating at least the
- title, year, new authors, and publisher of the <link linkend="fdl-modified">Modified Version</link> as given on
- the <link linkend="fdl-title-page">Title Page</link>. If
- there is no section entitled <quote>History</quote> in the
- <link linkend="fdl-document">Document</link>, create one
- stating the title, year, authors, and publisher of the
- Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- </para>
+ <para>Bevara avsnittet med titeln <quote>historik</quote> (History), bevara dess titel och lägg i avsnittet till en post med åtminstone titeln, året, nya författare och utgivaren av <link linkend="fdl-modified">förändrad version</link> så som angivet på <link linkend="fdl-title-page">Titelsidan</link>. Om det inte finns något avsnitt med titeln <quote>historik</quote> (History) i <link linkend="fdl-document">Dokument</link> så skapa en med titeln, året, författare och utgivaren av dokumentet så som det står på [original]dokumentets titelsida. Lägg sedan till en post som beskriver den förändrade versionen så som beskrivits ovan.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>J</title>
- <para>
- Preserve the network location, if any, given in the <link linkend="fdl-document">Document</link> for public access
- to a <link linkend="fdl-transparent">Transparent</link>
- copy of the Document, and likewise the network locations
- given in the Document for previous versions it was based
- on. These may be placed in the <quote>History</quote>
- section. You may omit a network location for a work that
- was published at least four years before the Document
- itself, or if the original publisher of the version it
- refers to gives permission.
- </para>
+ <para>Bevara den nätverksadress, om det finns någon, angiven i <link linkend="fdl-document">Dokument</link> till den allmänt tillgängliga <link linkend="fdl-transparent">transparent</link>a kopian av dokumentet, och likaså nätverksadresserna till de föregående versioner som dokumentet baseras på. Dessa får placeras i avsnittet <quote>historik</quote> (History). Du äger utelämna en nätverksadress för ett verk som är publicerat mer än fyra år före dokumentet självt, eller om den ursprunglige utgivaren vars verk nätverksadressen hänvisar till ger sitt tillstånd.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>K</title>
- <para>
- In any section entitled <quote>Acknowledgements</quote> or
- <quote>Dedications</quote>, preserve the section's title,
- and preserve in the section all the substance and tone of
- each of the contributor acknowledgements and/or
- dedications given therein.
- </para>
+ <para>För alla avsnitt med titlarna <quote>tillkännagivanden</quote> (Acknowledgements) eller <quote>dedikationer</quote> (Dedications), bevara titeln på avsnittet, och bevara allt innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda av varje bidragsgivare.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>L</title>
- <para>
- Preserve all the <link linkend="fdl-invariant">Invariant
- Sections</link> of the <link linkend="fdl-document">Document</link>, unaltered in their
- text and in their titles. Section numbers or the
- equivalent are not considered part of the section titles.
- </para>
+ <para>Bevara alla <link linkend="fdl-invariant">oföränderliga avsnitten</link> i <link linkend="fdl-document">Dokument</link> oförändrade till text och titel. Avsnittsnummer eller motsvarande anses inte tillhöra avsnittets titel.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>M</title>
- <para>
- Delete any section entitled
- <quote>Endorsements</quote>. Such a section may not be
- included in the <link linkend="fdl-modified">Modified
- Version</link>.
- </para>
+ <para>Radera varje avsnitt med titeln <quote>endossering</quote> (Endorsements). Ett sådant avsnitt får inte inkluderas i en <link linkend="fdl-modified">förändrad version</link>.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>N</title>
- <para>
- Do not retitle any existing section as
- <quote>Endorsements</quote> or to conflict in title with
- any <link linkend="fdl-invariant">Invariant
- Section</link>.
- </para>
+ <para>Inte byta titel på något existerande avsnitt så att det blir <quote>endossering</quote> (Endorsements) eller så att titeln kan förväxlas med något <link linkend="fdl-invariant">oföränderligt avsnitt</link>.</para>
</formalpara>
</listitem>
</itemizedlist>
- <para>
- If the <link linkend="fdl-modified">Modified Version</link>
- includes new front-matter sections or appendices that qualify as
- <link linkend="fdl-secondary">Secondary Sections</link> and
- contain no material copied from the Document, you may at your
- option designate some or all of these sections as invariant. To
- do this, add their titles to the list of <link linkend="fdl-invariant">Invariant Sections</link> in the
- Modified Version's license notice. These titles must be
- distinct from any other section titles.
- </para>
+ <para>Om <link linkend="fdl-modified">förändrad version</link> innehåller nya framsidestexter eller bilagor som är att anses som <link linkend="fdl-secondary">sekundära avsnitt</link> och inte innehåller något material kopierat från dokumentet, så äger du, om du vill, benämna några eller samtliga av dessa som oföränderliga. För att göra detta, lägg deras titlar till listan över <link linkend="fdl-invariant">oföränderliga avsnitten</link> i den förändrade versionens licensmeddelande. Dessa titlar måste vara skilda från alla andra avsnitts titlar.</para>
- <para>
- You may add a section entitled <quote>Endorsements</quote>,
- provided it contains nothing but endorsements of your <link linkend="fdl-modified">Modified Version</link> by various
- parties--for example, statements of peer review or that the text
- has been approved by an organization as the authoritative
- definition of a standard.
- </para>
+ <para>Du äger lägga till ett avsnitt med titeln <quote>endossering</quote> (Endorsements), förutsatt att det inte innehåller något annat än endosseringar för din <link linkend="fdl-modified">förändrad version</link> från olika aktörer -- till exempel, meddelanden om utförd korrekturläsning eller att texten har godkänts av en organisation som en officiell definition av en standard.</para>
- <para>
- You may add a passage of up to five words as a <link linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage
- of up to 25 words as a <link linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of
- the list of <link linkend="fdl-cover-texts">Cover Texts</link>
- in the <link linkend="fdl-modified">Modified Version</link>.
- Only one passage of Front-Cover Text and one of Back-Cover Text
- may be added by (or through arrangements made by) any one
- entity. If the <link linkend="fdl-document">Document</link>
- already includes a cover text for the same cover, previously
- added by you or by arrangement made by the same entity you are
- acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
- </para>
+ <para>Du äger lägga till ett textavsnitt på upp till fem ord som <link linkend="fdl-cover-texts">framsidestext</link>, och ett textavsnitt på upp till 25 ord som <link linkend="fdl-cover-texts">baksidestext</link> i listan över <link linkend="fdl-cover-texts">Omslagstexterna</link> i <link linkend="fdl-modified">förändrad version</link>. Bara ett textavsnitt med framsidestexter och ett med baksidestexter får läggas till av (eller genom försorg av) en enda juridisk person. Om <link linkend="fdl-document">Dokument</link> redan innehåller en omslagstext för något av omslagen, tidigare tillagd av dig eller genom försorg av samma juridiska person som du företräder, äger du inte lägga till en till, men du äger ändra den gamla med tillstånd från den tidigare utgivaren som lade till den förra.</para>
- <para>
- The author(s) and publisher(s) of the <link linkend="fdl-document">Document</link> do not by this License
- give permission to use their names for publicity for or to
- assert or imply endorsement of any <link linkend="fdl-modified">Modified Version </link>.
- </para>
+ <para>Författaren (författarna) och utgivaren (utgivarna) av <link linkend="fdl-document">Dokument</link> ger inte via denna licens sitt tillstånd att använda sina namn för publicitet eller för att lägga till eller antyda endossering av någon <link linkend="fdl-modified">förändrad version</link>.</para>
</sect1>
<sect1 id="fdl-section5">
<title>5. KOMBINERA DOKUMENT</title>
- <para>
- You may combine the <link linkend="fdl-document">Document</link>
- with other documents released under this License, under the
- terms defined in <link linkend="fdl-section4">section 4</link>
- above for modified versions, provided that you include in the
- combination all of the <link linkend="fdl-invariant">Invariant
- Sections</link> of all of the original documents, unmodified,
- and list them all as Invariant Sections of your combined work in
- its license notice.
- </para>
+ <para>Du äger kombinera <link linkend="fdl-document">Dokument</link> med andra dokument som är utgivna under denna licens, under de villkor som definieras i <link linkend="fdl-section4">paragraf 4</link> av GNU Free Documentation License för förändrade versioner, förutsatt att du, i det kombinerade dokumentet, innefattar alla <link linkend="fdl-invariant">oföränderliga avsnitten</link> från originaldokumenten, omodifierade, och listar dem som oföränderliga avsnitt i ditt kombinerade verk i dess licensklausul, och att du bevarar alla deras garantiavsägelseklausuler.</para>
- <para>
- The combined work need only contain one copy of this License,
- and multiple identical <link linkend="fdl-invariant">Invariant
- Sections</link> may be replaced with a single copy. If there are
- multiple Invariant Sections with the same name but different
- contents, make the title of each such section unique by adding
- at the end of it, in parentheses, the name of the original
- author or publisher of that section if known, or else a unique
- number. Make the same adjustment to the section titles in the
- list of Invariant Sections in the license notice of the combined
- work.
- </para>
+ <para>Det kombinerade verket behöver bara innehålla en enstaka kopia av denna licens [engelska originalversionen], och flera identiska <link linkend="fdl-invariant">oföränderliga avsnitten</link> kan ersättas med en kopia. Om det finns flera oföränderliga stycken med samma namn men olika innehåll, se till att titeln på varje sådant avsnitt är unik genom att i slutet på den, inom parentes, lägga till namnet på den ursprunglige författaren eller utgivaren av det avsnittet om dessa är kända, annars ett unikt nummer. Gör samma justeringar av titlarna i listan över oföränderliga avsnitt i licensklausulen i det kombinerade verket.</para>
- <para>
- In the combination, you must combine any sections entitled
- <quote>History</quote> in the various original documents,
- forming one section entitled <quote>History</quote>; likewise
- combine any sections entitled <quote>Acknowledgements</quote>,
- and any sections entitled <quote>Dedications</quote>. You must
- delete all sections entitled <quote>Endorsements.</quote>
- </para>
+ <para>I det kombinerade verket måste du kombinera alla avsnitt med titlarna <quote>historik</quote> (History) i de ursprungliga dokumenten, till ett avsnitt med titeln <quote>historik</quote> (History); på samma sätt skall alla avsnitt med titlarna <quote>tillkännagivanden</quote> (Acknowledgements), alla avsnitt med titlarna <quote>dedikationer</quote> (Dedications) kombineras. Du måste ta bort alla avsnitt med titlarna <quote>endossering</quote> (Endorsements).</para>
</sect1>
<sect1 id="fdl-section6">
<title>6. SAMLINGAR AV DOKUMENT</title>
- <para>
- You may make a collection consisting of the <link linkend="fdl-document">Document</link> and other documents
- released under this License, and replace the individual copies
- of this License in the various documents with a single copy that
- is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
- </para>
+ <para>Du äger skapa en samling bestående av <link linkend="fdl-document">Dokument</link> och andra dokument som är släppta under GNU Free Documentation License, och ersätta individuella kopior i dokumenten av denna licens med en enda kopia [av den engelska originalversionen] som inkluderas i samlingen, förutsatt att du följer villkoren för ordagrann kopiering i denna licens för varje inkluderat dokument i alla andra avseenden.</para>
- <para>
- 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.
- </para>
+ <para>Du äger lyfta ut ett dokument från en sådan samling, och sprida det enskilt under GNU Free Documentation License, förutsatt att du lägger till en kopia av denna licens [den engelska originalversionen] i det utlyfta dokumentet, och följer villkoren för ordagrann kopiering i denna licens för det utlyfta dokumentet i alla andra avseenden.</para>
</sect1>
<sect1 id="fdl-section7">
<title>7. SAMMANSLAGNING MED OBEROENDE VERK</title>
- <para>
- A compilation of the <link linkend="fdl-document">Document</link> or its derivatives with
- other separate and independent documents or works, in or on a
- volume of a storage or distribution medium, does not as a whole
- count as a <link linkend="fdl-modified">Modified Version</link>
- of the Document, provided no compilation copyright is claimed
- for the compilation. Such a compilation is called an
- <quote>aggregate</quote>, and this License does not apply to the
- other self-contained works thus compiled with the Document , on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document. If the <link linkend="fdl-cover-texts">Cover Text</link> requirement of <link linkend="fdl-section3">section 3</link> is applicable to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may
- be placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
- </para>
+ <para>En samling av <link linkend="fdl-document">Dokument</link> eller av dess derivat med andra separata och oberoende dokument eller verk, på eller i en lagringsvolym eller ett spridningsmedium, kallas för en <quote>sammanslagning</quote> om den sammanslagna upphovsrätten inte används för att begränsa samlingens användares rättigheter som de enskilda dokumenten medger. När dokumentet ingår i en sådan sammanslagning, gäller inte denna licens de andra verken i samlingen som inte själva är deriverat av dokumentet. Om kravet på <link linkend="fdl-cover-texts">omslagstexter</link> enligt <link linkend="fdl-section3">paragraf 3</link> är tillämpligt på dessa kopior av dokumentet, så kan dokumentets omslagstexter, om dokumentet utgör mindre än en fjärdedel av hela samlingen, placeras på det omslag som omger dokumentet inuti samlingen, eller den elektroniska motsvarigheten till omslag om dokumentet är i elektronisk form. Annars måste de synas på det omslag som omger hela samlingen.</para>
</sect1>
<sect1 id="fdl-section8">
<title>8. ÖVERSÄTTNING</title>
- <para>
- Translation is considered a kind of modification, so you may
- distribute translations of the <link linkend="fdl-document">Document</link> under the terms of <link linkend="fdl-section4">section 4</link>. Replacing <link linkend="fdl-invariant"> Invariant Sections</link> with
- translations requires special permission from their copyright
- holders, but you may include translations of some or all
- Invariant Sections in addition to the original versions of these
- Invariant Sections. You may include a translation of this
- License provided that you also include the original English
- version of this License. In case of a disagreement between the
- translation and the original English version of this License,
- the original English version will prevail.
- </para>
+ <para>Översättning anses vara en sorts förändring, så du äger sprida översättningar av <link linkend="fdl-document">Dokument</link> enligt de villkor som sätts i <link linkend="fdl-section4">paragraf 4</link>. <link linkend="fdl-invariant">oföränderliga avsnitten</link> som ersätts med översättningar kräver tillstånd från deras upphovsrättsinnehavare, men du äger inkludera översättningar av alla eller vissa av dessa oföränderliga avsnitt tillsammans med originalversionerna av dessa oföränderliga avsnitt. Du äger inkludera en översättning av denna licens, och alla licensklausuler i dokumentet, och alla garantiavsägelser, förutsatt att du också innefattar den engelska originalversionen av denna licens och originalversionerna av dessa klausuler. Skulle det finnas skillnader mellan översättningen och originalversionen av denna licens eller någon klausul så gäller originalversionen.</para>
</sect1>
<sect1 id="fdl-section9">
<title>9. UPPHÖRANDE</title>
- <para>
- You may not copy, modify, sublicense, or distribute the <link linkend="fdl-document">Document</link> except as expressly
- provided for under this License. Any other attempt to copy,
- modify, sublicense or distribute the Document is void, and will
- automatically terminate your rights under this License. However,
- parties who have received copies, or rights, from you under this
- License will not have their licenses terminated so long as such
- parties remain in full compliance.
- </para>
+ <para>Du äger inte kopiera, förändra, omlicensiera eller sprida <link linkend="fdl-document">Dokument</link> annat än enligt villkoren i GNU Free Documentation License. Alla övriga försök att kopiera, modifiera, omlicensiera, eller sprida dokumentet är ogiltiga och kommer automatiskt medföra att du förlorar dina rättigheter enligt denna licens. Tredje man som har mottagit kopior eller rättigheter från dig enligt dessa licensvillkor kommer dock inte att förlora sina rättigheter så länge de följer licensvillkoren.</para>
</sect1>
<sect1 id="fdl-section10">
<title>10. FRAMTIDA VERSIONER AV DENNA LICENS</title>
- <para>
- The <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software
- Foundation</ulink> may publish new, revised versions of the GNU
- Free Documentation License from time to time. Such new versions
- will be similar in spirit to the present version, but may differ
- in detail to address new problems or concerns. See <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.
- </para>
+ <para><ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software Foundation</ulink> kan publicera nya, reviderade versioner av GNU Free Documentation License då och då. Sådana nya versioner kommer att vara likadana i andemening som den nuvarande versionen, men kan skilja i detalj för att behandla nya problem eller angelägenheter. Se <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.</para>
- <para>
- Each version of the License is given a distinguishing version
- number. If the <link linkend="fdl-document">Document</link>
- specifies that a particular numbered version of this License
- <quote>or any later version</quote> applies to it, you have the
- option of following the terms and conditions either of that
- specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by
- the Free Software Foundation.
- </para>
+ <para>Varje version av licensen ges ett unikt versionsnummer. Om <link linkend="fdl-document">Dokument</link> stadgar att en specifik numrerad version av denna licens <quote>eller valfri senare version</quote> gäller för det, så äger du rätten att följa villkoren enligt antingen den angivna versionen eller vilken senare version som helst som publicerats (inte som utkast) av Free Software Foundation. Om dokumentet inte anger en version av denna licens, äger du välja vilken version som helst som publicerats (inte som utkast) av Free Software Foundation.</para>
</sect1>
<sect1 id="fdl-using">
<para>För att använda GNU Free Documentation License för ett dokument du har skrivit, inkludera en kopia av licensen [det engelska originalet] i dokumentet och placera följande copyrightklausul omedelbart efter titelsidan:</para>
<blockquote>
- <para>Copyright (c) ÅRTAL DITT NAMN.</para>
- <para>
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation
- License, Version 1.1 or any later version published by the
- Free Software Foundation; with the <link linkend="fdl-invariant">Invariant Sections</link> being LIST
- THEIR TITLES, with the <link linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST,
- and with the <link linkend="fdl-cover-texts">Back-Cover
- Texts</link> being LIST. A copy of the license is included in
- the section entitled <quote>GNU Free Documentation
- License</quote>.
- </para>
+ <para>Copyright © YEAR YOUR NAME.</para>
+ <para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the <link linkend="fdl-invariant">oföränderliga avsnitten</link> being LIST THEIR TITLES, with the <link linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST, and with the <link linkend="fdl-cover-texts">Back-Cover Texts</link> being LIST. A copy of the license is included in the section entitled <quote>GNU Free Documentation License</quote>.</para>
</blockquote>
- <para>
- If you have no <link linkend="fdl-invariant">Invariant
- Sections</link>, write <quote>with no Invariant Sections</quote>
- instead of saying which ones are invariant. If you have no
- <link linkend="fdl-cover-texts">Front-Cover Texts</link>, write
- <quote>no Front-Cover Texts</quote> instead of
- <quote>Front-Cover Texts being LIST</quote>; likewise for <link linkend="fdl-cover-texts">Back-Cover Texts</link>.
- </para>
+ <para>Om du inte har några <link linkend="fdl-invariant">oföränderliga avsnitten</link>, skriv <quote>with no Invariant Sections</quote> istället för att ange vilka som är oföränderliga. Om du inte har några <link linkend="fdl-cover-texts">Front-Cover Texts</link>, skriv <quote>no Front-Cover Texts</quote> istället för <quote>Front-Cover Texts being LIST</quote>; såväl som för <link linkend="fdl-cover-texts">Back-Cover Texts</link>.</para>
- <para>
- If your document contains nontrivial examples of program code,
- we recommend releasing these examples in parallel under your
- choice of free software license, such as the <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public
- License</ulink>, to permit their use in free software.
- </para>
+ <para>Om ditt dokument innehåller icke-triviala exempel med programkod, så rekommenderar vi att du släpper dessa exempel parallellt under en, av dig vald, fri programvarulicens, som till exempel <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html">GNU General Public License</ulink>, för att möjliggöra deras användning i fri programvara.</para>
</sect1>
</appendix>
<edition>1.24.1</edition>
<abstract role="description"><para>Användarhandbok för utvecklare med användningsinstruktioner för GTK-Doc.</para></abstract>
<authorgroup>
- <author>
- <firstname>Chris</firstname>
- <surname>Lyttle</surname>
- <affiliation>
- <address>
- <email>chris@wilddev.net</email>
- </address>
- </affiliation>
- </author>
- <author>
- <firstname>Dan</firstname>
- <surname>Mueth</surname>
- <affiliation>
- <address>
- <email>d-mueth@uchicago.edu</email>
- </address>
- </affiliation>
- </author>
- <author>
- <firstname>Stefan</firstname>
- <surname>Sauer (Kost)</surname>
- <affiliation>
- <address>
- <email>ensonic@users.sf.net</email>
- </address>
- </affiliation>
- </author>
+ <author><firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation> <address> <email>chris@wilddev.net</email> </address> </affiliation></author>
+ <author><firstname>Dan</firstname> <surname>Mueth</surname> <affiliation> <address> <email>d-mueth@uchicago.edu</email> </address> </affiliation></author>
+ <author><firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> <affiliation> <address> <email>ensonic@users.sf.net</email> </address> </affiliation></author>
</authorgroup>
- <publisher role="maintainer">
- <publishername>GTK-Doc project</publishername>
- <address><email>gtk-doc-list@gnome.org</email></address>
- </publisher>
- <copyright>
- <year>2000, 2005</year>
- <holder>Dan Mueth and Chris Lyttle</holder>
- </copyright>
- <copyright>
- <year>2007-2015</year>
- <holder>Stefan Sauer (Kost)</holder>
- </copyright>
+ <publisher role="maintainer"><publishername>GTK-Doc-projektet</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
+ <copyright><year>2000, 2005</year> <holder>Dan Mueth and Chris Lyttle</holder></copyright>
+ <copyright><year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder></copyright>
<!-- translators: uncomment this:
<copyright>
</legalnotice>
<revhistory>
- <revision>
- <revnumber>1.24.1</revnumber>
- <date>30 May 2015</date>
- <authorinitials>ss</authorinitials>
- <revremark>development version</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.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.17</revnumber>
- <date>26 Feb 2011</date>
- <authorinitials>sk</authorinitials>
- <revremark>urgent bug fix update</revremark>
- </revision>
- <revision>
- <revnumber>1.16</revnumber>
- <date>14 Jan 2011</date>
- <authorinitials>sk</authorinitials>
- <revremark>bugfixes, layout improvements</revremark>
- </revision>
- <revision>
- <revnumber>1.15</revnumber>
- <date>21 May 2010</date>
- <authorinitials>sk</authorinitials>
- <revremark>bug and regression fixes</revremark>
- </revision>
- <revision>
- <revnumber>1.14</revnumber>
- <date>28 March 2010</date>
- <authorinitials>sk</authorinitials>
- <revremark>bugfixes and performance improvements</revremark>
- </revision>
- <revision>
- <revnumber>1.13</revnumber>
- <date>18 December 2009</date>
- <authorinitials>sk</authorinitials>
- <revremark>broken tarball update</revremark>
- </revision>
- <revision>
- <revnumber>1.12</revnumber>
- <date>18 December 2009</date>
- <authorinitials>sk</authorinitials>
- <revremark>new tool features and bugfixes</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.25.1</revnumber> <date>21 Mars 2016</date> <authorinitials>ss</authorinitials> <revremark>utvecklingsversion</revremark></revision>
+ <revision><revnumber>1.25</revnumber> <date>21 Mars 2016</date> <authorinitials>ss</authorinitials> <revremark>programfixar, uppstädning av tester</revremark></revision>
+ <revision><revnumber>1.24</revnumber> <date>29 Maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfix</revremark></revision>
+ <revision><revnumber>1.23</revnumber> <date>17 Maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfix</revremark></revision>
+ <revision><revnumber>1.22</revnumber> <date>07 Maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfixar, borttagning av föråldrade funktioner</revremark></revision>
+ <revision><revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</authorinitials> <revremark>programfixar, borttagning av föråldrade funktioner</revremark></revision>
+ <revision><revnumber>1.20</revnumber> <date>16 Feb 2014</date> <authorinitials>ss</authorinitials> <revremark>programfixar, stöd för markdown, stilförbättringar</revremark></revision>
+ <revision><revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</authorinitials> <revremark>programfixar</revremark></revision>
+ <revision><revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</authorinitials> <revremark>programfixar, uppsnabbningar, stöd för markdown</revremark></revision>
+ <revision><revnumber>1.17</revnumber> <date>26 Feb 2011</date> <authorinitials>sk</authorinitials> <revremark>brådskande programfixuppdatering</revremark></revision>
+ <revision><revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</authorinitials> <revremark>programfixar, layoutförbättringar</revremark></revision>
+ <revision><revnumber>1.15</revnumber> <date>21 Maj 2010</date> <authorinitials>sk</authorinitials> <revremark>program- och regressionsfixar</revremark></revision>
+ <revision><revnumber>1.14</revnumber> <date>28 Mars 2010</date> <authorinitials>sk</authorinitials> <revremark>programfixar och prestandaförbättringar</revremark></revision>
+ <revision><revnumber>1.13</revnumber> <date>18 December 2009</date> <authorinitials>sk</authorinitials> <revremark>uppdatering på grund av trasigt tar-arkiv</revremark></revision>
+ <revision><revnumber>1.12</revnumber> <date>18 December 2009</date> <authorinitials>sk</authorinitials> <revremark>nya verktygsfunktioner och programfixar</revremark></revision>
+ <revision><revnumber>1.11</revnumber> <date>16 November 2008</date> <authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</revremark></revision>
</revhistory>
+
+ <othercredit class="translator">
+ <personname>
+ <firstname>Sebastian Rasmussen</firstname>
+ </personname>
+ <email>sebras@gmail.com</email>
+ </othercredit>
+ <copyright>
+
+ <year>2016</year>
+
+ <holder>Sebastian Rasmussen</holder>
+ </copyright>
+
+ <othercredit class="translator">
+ <personname>
+ <firstname>Daniel Nylander</firstname>
+ </personname>
+ <email>po@danielnylander.se</email>
+ </othercredit>
+ <copyright>
+
+ <year>2009</year>
+
+ <holder>Daniel Nylander</holder>
+ </copyright>
+
+ <othercredit class="translator">
+ <personname>
+ <firstname>Marcus Rejås och Alexander Nordström</firstname>
+ </personname>
+ <email>info@se.linux.org</email>
+ </othercredit>
+ <copyright>
+
+ <year>2004</year>
+
+ <holder>Marcus Rejås och Alexander Nordström</holder>
+ </copyright>
</bookinfo>
<!-- ======== Chapter 1: Introduction ======================== -->
<chapter id="introduction">
<title>Introduktion</title>
- <para>
- This chapter introduces GTK-Doc and gives an overview of what it is and
- how it is used.
- </para>
+ <para>Detta kapitel introducerar GTK-Doc och ger en överblick över vad det är och hur det används.</para>
<sect1 id="whatisgtkdoc">
<title>Vad är GTK-Doc?</title>
- <para>
- GTK-Doc 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 also be
- used to document application code.
- </para>
+ <para>GTK-Doc används för att dokumentera C-kod. Det används vanligen för att dokumentera det publika API:t för bibliotek, så som GTK+- och GNOME-biblioteken. Men det kan också användas för att dokumentera programkod.</para>
</sect1>
<sect1 id="howdoesgtkdocwork">
<title>Hur fungerar GTK-Doc?</title>
- <para>
- GTK-Doc works by using documentation of functions placed inside the source files in
- specially-formatted comment blocks, or documentation added to the template files
- which GTK-Doc uses (though note that GTK-Doc will only document functions that
- are declared in header files; it won't produce output for static functions).
- </para>
+ <para>GTK-Doc fungerar så att det använder dokumentation för funktioner placerad inuti källkodsfilerna i speciellt formaterade kommentarsblock, eller dokumentation som lagts till i mallfilerna som GTK-Doc använder (notera dock att GTK-Doc endast kommer att dokumentera funktioner som deklarerats i huvudfiler; det kommer inte att producera utdata för statiska funktioner).</para>
- <para>
- GTK-Doc consists of a number of perl scripts, each performing a different step
- in the process.
- </para>
+ <para>GTK-Doc består av ett antal perl-skript som vart och ett utför olika steg i processen.</para>
- <para>
- There are 5 main steps in the process:
- </para>
+ <para>Det finns 5 huvudsteg i processen:</para>
<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 anymore).
- </para>
- </listitem>
-
- <listitem>
- <para>
- <guilabel>Gathering information about the code.</guilabel>
-
- <application>gtkdoc-scan</application> scans the header files of the
- code looking for declarations of functions, macros, enums, structs, and unions.
- It creates the file <filename><module>-decl-list.txt</filename> containing a list of the
- declarations, placing them into sections according to which header file they
- are in. On the first run this file is copied to <filename><module>-sections.txt</filename>.
- The author can rearrange the sections, and the order of the
- declarations within them, to produce the final desired order.
- The second file it generates is <filename><module>-decl.txt</filename>.
- This file contains the full declarations found by the scanner. If for
- some reason one would like some symbols to show up in the docs, where
- the full declaration cannot be found by the scanner or the declaration
- should appear differently, one can place entities similar to the ones in
- <filename><module>-decl.txt</filename> into <filename><module>-overrides.txt</filename>.
- </para>
- <para>
- <application>gtkdoc-scangobj</application> can also be used to dynamically query a library about
- any GObject subclasses it exports. It saves information about each
- object's position in the class hierarchy and about any GObject properties
- and signals it provides.
- </para>
- <para>
- <application>gtkdoc-scanobj</application> should not be used anymore.
- It was needed in the past when GObject was still GtkObject inside gtk+.
- </para>
+ <para><guilabel>Skriva dokumentationen.</guilabel> Författaren fyller i källkodsfilerna med dokumentation för varje funktion, makro, union, etc. (Tidigare matades informationen in i genererade mallfiler, något som inte rekommenderas längre).</para>
</listitem>
<listitem>
- <para>
- <guilabel>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.)
- </para>
- <note>
- <para>
- 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).
- </para>
- </note>
+ <para><guilabel>Samla ihop information om koden.</guilabel> <application>gtkdoc-scan</application> söker genom huvudfilerna för koden och letar efter deklarationer av funktioner, makron, uppräkningar, strukturer och unioner. Det skapar sedan filen <filename><module>-decl-list.txt</filename> som innehåller en lista över deklarationerna, och placerar dem i avsnitt efter vilken huvudfil de finns i. Vid första körningen kommer denna fil att kopieras till <filename><module>-sections.txt</filename>. Författaren kan, genom att omarrangera avsnitten och ändra ordningen för deklarationerna inom dem, framställa den önskade, slutgiltiga ordningen. Den andra filen det genererar är <filename><module>-decl.txt</filename>. Denna fil innehåller de fullständiga deklarationerna som hittats av detektorn. Om man av något skäl vill att vissa symboler ska visas i dokumentation då den fullständiga deklarationen inte kan hittas av detektorn, eller om deklarationen ska visas annorlunda, kan man placera rader liknande de som finns i <filename><module>-decl.txt</filename> i <filename><module>-overrides.txt</filename>.</para>
+ <para><application>gtkdoc-scangobj</application> kan också användas för att dynamiskt fråga ett bibliotek om vilka GObject-underklasser det exporterar. Det sparar information om varje objekts position i klasshierarkin och om vilka GObject-egenskaper och signaler det tillhandahåller.</para>
+ <para><application>gtkdoc-scanobj</application> bör inte användas längre. Det behövdes tidigare när GObject fortfarande var GtkObject inuti gtk+.</para>
</listitem>
<listitem>
- <para>
- <guilabel>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.
- </para>
- <para>
- <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>.
- </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><guilabel>Generera XML och HTML/PDF.</guilabel> <application>gtkdoc-mkdb</application> förvandlar mallfilerna till XML-filer i underkatalogen <filename class="directory">xml/</filename>. Om källkoden innehåller dokumentation över funktioner i speciella kommentarsblock, så kommer denna att sammanfogas här. Om det inte finns några tmpl-filer som används så kommer det endast att läsa dokumentation från källkoden och introspektionsdata.</para>
+ <para><application>gtkdoc-mkhtml</application> förvandlar XML-filer till HTML-filer i underkatalogen <filename class="directory">html/</filename>. På samma sätt förvandlar <application>gtkdoc-mkpdf</application> XML-filerna till ett PDF-dokument kallat <filename><package>.pdf</filename>.</para>
+ <para>Filer i <filename class="directory">xml/</filename>- och <filename class="directory">html/</filename>-katalogerna skrivs alltid över. Man bör aldrig redigera dem direkt.</para>
</listitem>
<listitem>
- <para>
- <guilabel>Fixing up cross-references between documents.</guilabel>
-
- After installing the HTML files, <application>gtkdoc-fixxref</application> can be run to fix up any
- cross-references between separate documents. For example, the GTK+
- documentation contains many cross-references to types documented in the GLib manual.
-
- When creating the source tarball for distribution, <application>gtkdoc-rebase</application>
- turns all external links into web-links. When installing distributed (pregenerated) docs
- the same application will try to turn links back to local links
- (where those docs are installed).
- </para>
+ <para><guilabel>Fixa korsreferenser mellan dokument.</guilabel> Efter att ha installerat HTML-filerna kan <application>gtkdoc-fixxref</application> köras för att fixa korsreferenser mellan separata dokument. Till exempel GTK+-dokumentationen innehåller många korsreferenser till typer som dokumenterats i GLib-manualen. När tar-arkivet med källkod skapas för distribution, förvandlar <application>gtkdoc-rebase</application> alla externa länkar till webblänkar. När (förgenererad) distribuerad dokumentation installeras kommer samma program att försöka att förvandla länkarna tillbaka till lokala länkar (i de fall där dokumentationen finns installerad).</para>
</listitem>
</orderedlist>
<sect2 id="requirements">
<title>Krav</title>
- <para>
- <guilabel>Perl v5</guilabel> - the main scripts are in Perl.
- </para>
- <para>
- <guilabel>xsltproc</guilabel> - the xslt processor from libxslt
- <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink>
- </para>
- <para>
- <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>
- </para>
- <para>
- <guilabel>Python</guilabel> - optional - for gtkdoc-depscan
- </para>
- <para>
- One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> or
- <guilabel>vim</guilabel> - optional - used for syntax highlighting of examples
- </para>
+ <para><guilabel>Perl v5</guilabel> - huvudskripten är skrivna i Perl.</para>
+ <para><guilabel>xsltproc</guilabel> - xslt-processorn från libxslt <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink></para>
+ <para><guilabel>docbook-xsl</guilabel> - docbook xsl-stilmallar <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink></para>
+ <para><guilabel>Python</guilabel> - valfritt - för gtkdoc-depscan</para>
+ <para>Endera av <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> eller <guilabel>vim</guilabel> - valfritt - används för syntaxfärgning av exempel</para>
</sect2>
</sect1>
<sect1 id="aboutgtkdoc">
<title>Om GTK-Doc</title>
- <para>
- (FIXME)
- </para>
+ <para>(FIXME)</para>
- <para>
- (History, authors, web pages, mailing list, license, future plans,
- comparison with other similar systems.)
- </para>
+ <para>(Historia, författare, webbsidor, sändlistor, licens, framtida planer, jämförelse med andra liknande system.)</para>
</sect1>
<sect1 id="aboutthismanual">
<title>Om denna handbok</title>
- <para>
- (FIXME)
- </para>
+ <para>(FIXME)</para>
- <para>
- (who it is meant for, where you can get it, license)
- </para>
+ <para>(vem är den avsett för, var kan du få tag i den, licens)</para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Setting up your project</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.
- </para>
+ <title>Att ställa in ditt projekt</title>
+
+ <para>De följande avsnitten beskriver vilka steg du måste utföra för att integrera GTK-Doc i ditt projekt. Dessa avsnitt förutsätter att vi arbetar på ett projekt kallat ”meep”. Detta projekt innehåller ett bibliotek kallat ”libmeep” och ett slutanvändarprogram kallat ”meeper”. Vi förutsätter också att du kommer att använda autoconf och automake. Dessutom kommer avsnittet <link linkend="plain_makefiles">vanliga makefiler eller andra byggsystem</link> att beskriva de grundläggande sakerna som behöver fungera i ett annat byggsystem.</para>
<sect1 id="settingup_docfiles">
- <title>Setting up a skeleton documentation</title>
+ <title>Att ställa in en skelettstruktur för dokumentation</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.
- </para>
+ <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>
- This can then look as shown below:
- <example><title>Example directory structure</title>
- <programlisting><![CDATA[
+ <para>Detta kan se ut enligt nedan: <example><title>Exempel på katalogstruktur</title>
+ <programlisting>
meep/
docs/
reference/
src/
libmeep/
meeper/
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
</sect1>
<sect1 id="settingup_autoconf">
- <title>Integration with autoconf</title>
+ <title>Integrering med autoconf</title>
- <para>
- Very easy! Just add one line to your <filename>configure.ac</filename> script.
- </para>
+ <para>Väldigt enkelt! Bara lägg till en rad till ditt <filename>configure.ac</filename>-skript.</para>
<para>
- <example><title>Integration with autoconf</title>
- <programlisting><![CDATA[
+ <example><title>Integrering med autoconf</title>
+ <programlisting>
# check for gtk-doc
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
-]]></programlisting>
+</programlisting>
</example>
</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[
+ <para>Detta kommer att kräva att alla utvecklare har gtk-doc installerat. Om det är okej för ditt projekt att ha ett valfritt api-dokumentation bygge, kan du lösa det enligt nedan. Behåll det som det är eftersom gtkdocize letar efter <function>GTK_DOC_CHECK</function> i början på en rad. <example><title>Låt gtk-doc vara valfritt</title>
+ <programlisting>
# check for gtk-doc
m4_ifdef([GTK_DOC_CHECK], [
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
-]]></programlisting>
- </example>
- </para>
+</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>
+ <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=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>
+ <listitem><para>--with-html-dir=SÖKVÄG : sökväg till installerad dokumentation</para></listitem>
+ <listitem><para>--enable-gtk-doc : använd gtk-doc för att bygga dokumentation [standardvärde=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc-html : bygg dokumentation i html-format [standardvärde=yes]</para></listitem>
+ <listitem><para>--enable-gtk-doc-pdf : bygg dokumentation i pdf-format [standardvärde=no]</para></listitem>
</orderedlist>
<important>
- <para>
- GTK-Doc 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>
+ <para>GTK-Doc är inaktiverat som standard! Kom ihåg att skicka flaggan <option>”--enable-gtk-doc”</option> vid nästa körning av <filename>configure</filename>. Annars kommer förgenererad dokumentation att installeras (vilket är rimligt för användare men inte för utvecklare).</para>
</important>
- <para>
- 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.
- </para>
+ <para>Vidare rekommenderas det att du har följande rad i ditt <filename>configure.ac</filename>-skript. Den låter <application>gtkdocize</application> automatiskt kopiera makrodefinitionen för <function>GTK_DOC_CHECK</function> till ditt projekt.</para>
<para>
<example><title>Förberedelse för gtkdocize</title>
- <programlisting><![CDATA[
+ <programlisting>
AC_CONFIG_MACRO_DIR(m4)
-]]></programlisting>
+</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>
+ <para>Efter att alla ändringar i <filename>configure.ac</filename> är gjorda, uppdatera filen <filename>configure</filename>. Detta kan göras genom att köra om <code>autoreconf -i</code> eller <code>autogen.sh</code>.</para>
</sect1>
<sect1 id="settingup_automake">
- <title>Integration med automake</title>
+ <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://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>
+ <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>
- <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>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>
<!-- FIXME: explain options ? -->
</sect1>
<sect1 id="settingup_autogen">
- <title>Integration with autogen</title>
+ <title>Integrering med autogen</title>
- <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>
+ <para>De flesta projekt kommer att ha ett <filename>autogen.sh</filename>-skript för att ställa in infrastrukturen för bygget efter utcheckning från ett versionshanteringssystem (så som cvs/svn/git). GTK-Doc tillhandahåller ett verktyg som heter <application>gtkdocize</application> som kan användas i ett sådant skript. Det bör köras före autoheader, automake eller autoconf.</para>
<para>
- <example><title>Running gtkdocize from autogen.sh</title>
- <programlisting><![CDATA[
+ <example><title>Köra gtkdocize från autogen.sh</title>
+ <programlisting>
gtkdocize || exit 1
-]]></programlisting>
+</programlisting>
</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>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>
- 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>
+ <para>Historiskt genererade GTK-Doc mallfiler i vilka utvecklare skrev in dokumentationen. Detta visade sig inte vara så bra (t.ex. på grund av behovet att ha genererade filer under versionskontroll). Sedan GTK-Doc 1.9 kan verktygen hämta all information från källkodskommentarer och mallar kan därför undvikas. Vi rekommenderar att hålla dokumentationen i koden. <application>gtkdocize</application> har nu stöd för flaggan <option>--flavour no-tmpl</option> som väljer en makefil som hoppar över tmpl-användning helt. Förutom att lägga till flaggan direkt vid körning av kommandot, kan den också läggas till i en miljövariabel kallad <symbol>GTKDOCIZE_FLAGS</symbol> eller inställd som en andra parameter i makrot <symbol>GTK_DOC_CHECK</symbol> i configure-skriptet. Om du inte har ändrat någon fil i tmpl för hand och migrerar från äldre gtkdoc-versioner, ta bort katalogen (t.ex. från versionshanteringssystemet).</para>
</sect1>
<sect1 id="settingup_firstrun">
- <title>Running the doc build</title>
+ <title>Att köra dokumentationsbygget</title>
+ <para>Efter de tidigare stegen är det dags att köra bygget. Först måste vi köra om <filename>autogen.sh</filename>. Om detta skript kör configure åt dig, kan du ge det flaggan <option>--enable-gtk-doc</option>. Annars kör manuellt <filename>configure</filename> med denna flagga efteråt.</para>
+ <para>Den första körningen av make genererar flera extra filer i doc-katalogerna. De viktiga är <filename><paket>.types</filename>, <filename><paket>-docs.xml</filename> (tidigare .sgml), <filename><paket>-sections.txt</filename>.</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[
+ <example><title>Att köra dokumentationsbygget</title>
+ <programlisting>
./autogen.sh --enable-gtk-doc
make
-]]></programlisting>
+</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>
+ <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>
</sect1>
<sect1 id="settingup_vcs">
- <title>Integration with version control systems</title>
+ <title>Integrering med versionshanteringssystem</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.
- </para>
+ <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>
<sect1 id="plain_makefiles">
- <title>Integration with plain makefiles or other build systems</title>
+ <title>Integrering med vanliga makefiler eller andra byggsystem</title>
- <para>
- 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 in own makefiles (or other build tools).
- </para>
+ <para>I det fall man inte vill använda automake och därför inte heller <filename>gtk-doc.mak</filename> kommer man att behöva anropa gtkdoc-verktygen i rätt ordning i sina egna makefiler (eller andra byggverktyg).</para>
<para>
- <example><title>Documentation build steps</title>
- <programlisting><![CDATA[
+ <example><title>Byggsteg för dokumentation</title>
+ <programlisting>
DOC_MODULE=meep
-// sources have changed
-gtkdoc-scan --module=$(DOC_MODULE) <source-dir>
+// källkod har ändrats
+gtkdoc-scan --module=$(DOC_MODULE) <källkodskatalog>
gtkdoc-scangobj --module=$(DOC_MODULE)
-gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>
-// xml files have changed
+gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<källkodskatalog>
+// xml-filer har ändrats
mkdir html
-cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
+cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
-]]></programlisting>
+</programlisting>
</example>
</para>
- <para>
- One will need to look at the <filename>Makefile.am</filename> and
- <filename>gtk-doc.mak</filename> to pick the extra options needed.
- </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>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[
+ <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)
-# Create the doc-libmeep target.
+# Skapa målet doc-libmeep.
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.
+# 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)
-# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
-# to set the CMAKE_INSTALL_DOCDIR variable correctly).
+# 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>
+</programlisting>
+ </example></para>
</sect1>
</chapter>
<chapter id="documenting">
- <title>Documenting the code</title>
+ <title>Att dokumentera koden</title>
- <para>
- GTK-Doc uses source code comment with a special syntax for code documentation.
- Further it retrieves information about your project structure from other
- sources. During the next section you will find all information about the
- syntax of the comments.
- </para>
+ <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>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>
+ <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>
- 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><title>GTK-Doc comment block</title>
- <programlisting><![CDATA[
+ <para>Detektorn kan hantera majoriteten av C-huvuden bra. I det fall när du får varningar från detektorn som ser ut som ett specialfall, kan du tipsa GTK-Doc att hoppa över dem. <example><title>GTK-Doc-kommentarsblock</title>
+ <programlisting>
#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
<note>
- <title>Limitations</title>
- <para>
- Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
- <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
- </para>
+ <title>Begränsningar</title>
+ <para>Notera att GTK-Doc har stöd för <code>#ifndef(__GTK_DOC_IGNORE__)</code> men inte <code>#if !defined(__GTK_DOC_IGNORE__)</code> eller andra kombinationer.</para>
</note>
<!-- -->
<sect1 id="documenting_syntax">
- <title>Documentation comments</title>
+ <title>Dokumentationskommentarer</title>
- <para>
- A multiline comment that starts with an additional '*' marks a
- documentation block that will be processed by the GTK-Doc tools.
- <example><title>GTK-Doc comment block</title>
- <programlisting><![CDATA[
+ <para>En flerradskommentar som börjar med en extra ”*” markerar ett dokumentationsblock som kommer att hanteras av GTK-Doc-verktygen. <example><title>GTK-Doc-kommentarsblock</title>
+ <programlisting>
/**
- * identifier:
- * documentation ...
+ * identifierare:
+ * dokumentation …
*/
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
- <para>
- 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 table showing identifiers)
- </para>
+ <para>'Identifierare' är en rad med namnet på det objekt som kommentaren är relaterad till. Syntaxen skiljer sig lite beroende på objekt. (TODO lägg till tabell som visar identifierare)</para>
- <para>
- 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).
- </para>
+ <para>Blocket 'dokumentation' skiljer sig också för varje symboltyp. Symboltyper som får parametrar så som funktioner eller makron har en parameterbeskrivning först, åtföljd av en blankrad (bara en ”*”). Efteråt följer den detaljerade beskrivningen. Alla rader (utanför programlistningar och CDATA-avsnitt) som endast innehåller ” *” (blanksteg-asterisk) konverteras till styckeavgränsare. Om du inte vill ha en styckeavgränsare, ändra till ” * ” (blanksteg-asterisk-blanksteg-blanksteg). Detta är användbart i förformaterad text (kodlistningar).</para>
<tip>
- <para>
- When documenting code, describe two aspects:
- <itemizedlist>
+ <para>När du dokumenterar kod, beskriv två aspekter: <itemizedlist>
<listitem>
- <para>
- What it is: The name for a class or function can sometimes
- be misleading for people coming from a different background.
- </para>
+ <para>Vad är detta: Namnet på en klass eller en funktion kan ibland vara vilseledande för personer med annan bakgrund.</para>
</listitem>
<listitem>
- <para>
- What it does: Tell about common uses. Put it in relation
- with the other API.
- </para>
+ <para>Vad gör det: Berättar om vanliga användningsfall. Sätter det i relation med det andra API:t.</para>
</listitem>
- </itemizedlist>
- </para>
+ </itemizedlist></para>
</tip>
- <para>
- 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. GTK-Doc comes to help by providing several useful abbreviations.
- <itemizedlist>
+ <para>En fördel med hypertext framför vanlig text är möjligheten att ha länkar i dokumentet. Att skriva korrekta taggar för en länk kan dock vara tröttsamt. GTK-Doc hjälper då till med att tillhandahålla flera användbara förkortningar. <itemizedlist>
<listitem>
- <para>
- Use function() to refer to functions or macros which take arguments.
- </para>
+ <para>Använd funktion() för att referera till funktioner eller makron som tar argument.</para>
</listitem>
<listitem>
- <para>
- Use @param to refer to parameters. Also use this when referring to
- parameters of other functions, related to the one being described.
- </para>
+ <para>Använd @param för att referera till parametrar. Använd också detta när du refererar till parametrar för andra funktioner, relaterade till den som beskrivs.</para>
</listitem>
<listitem>
- <para>
- Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.
- </para>
+ <para>Använd %konstant för att referera till en konstant, t.ex. %G_TRAVERSE_LEAFS.</para>
</listitem>
<listitem>
- <para>
- Use #symbol to refer to other types of symbol, e.g. structs and
- enums and macros which don't take arguments.
- </para>
+ <para>Använd #symbol för att referera till andra typer av symboler, t.ex. strukturer eller uppräkningar och makron som inte tar argument.</para>
</listitem>
<listitem>
- <para>
- Use #Object::signal to refer to a GObject signal.
- </para>
+ <para>Använd #Objekt::signal för att referera till en GObject-signal.</para>
</listitem>
<listitem>
- <para>
- Use #Object:property to refer to a GObject property.
- </para>
+ <para>Använd #Objekt:egenskap för att referera till en GObject-egenskap.</para>
</listitem>
<listitem>
- <para>
- Use #Struct.field to refer to a field inside a structure and
- #GObjectClass.foo_bar() to refer to a vmethod.
- </para>
+ <para>Använd #Struktur.fält för att referera till ett fält inuti en struktur och #GObjectKlass.foo_bar() för att referera till en virtuell metod.</para>
</listitem>
- </itemizedlist>
- </para>
+ </itemizedlist></para>
<tip>
- <para>
- If you need to use the special characters '<', '>', '()', '@',
- '%', or '#' in your documentation without GTK-Doc changing them you
- can use the XML entities "&lt;", "&gt;", "&lpar;",
- "&rpar;", "&commat;", "&percnt;" and "&num;"
- respectively or escape them with a backslash '\'.
- </para>
+ <para>Om du behöver använda specialtecken ”<”, ”>”, ”()”, ”@”, ”%” eller ”#” i din dokumentation utan att GTK-Doc ändrar dem kan du använda XML-entiteterna ”&lt;”, ”&gt;”, ”&lpar;”, ”&rpar;”, ”&commat;”, ”&percnt;” respektive ”&num;” eller använda kontrollsekvensen ”\”.</para>
</tip>
- <para>
- 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.
- </para>
+ <para>DocBook kan mer än bara länkar. Du kan också ha listor, exempel, rubriker och bilder. Från och med version 1.20, är det föredragna sättet att använda en delmängd av den grundläggande textformateringssyntaxen som kallas <ulink url="http://daringfireball.net/projects/markdown/">Markdown</ulink>. Äldre GTK-Doc-versioner kommer dokumentation som inkluderar markdown att renderas som den är. Till exempel kommer listobjekt att visas som att de börjar med ett bindestreck.</para>
- <para>
- 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.
- </para>
+ <para>Då markdown numera föredras kan du blanda båda. En begränsning här är att du kan använda docbook-xml inuti markdown, men markdown inuti docbook-xml stöds inte.</para>
- <para>
- 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>.
- </para>
+ <para>I äldre GTK-Doc-versioner var du tvungen, om du ville ha stöd för ytterligare formatering, att aktivera användningen av docbook-XML-taggar inuti dok-kommentarer genom att lägga till <option>--xml-mode</option> (eller <option>--sgml-mode</option>) i variabeln <symbol>MKDB_OPTIONS</symbol> inuti <filename>Makefile.am</filename>.</para>
<para>
- <example><title>GTK-Doc comment block using Markdown</title>
- <programlisting><
+ * Ett annat stycke. [En länk till GNOME:s webbplats](http://www.gnome.org/)
*
- * 
+ * 
*
- * [A link to the heading anchor above][heading-two]
+ * [En länk till rubrikankaret ovan][andra-rubriken]
*
- * A C-language example:
- * |[<!-- language="C" -->
- * GtkWidget *label = gtk_label_new ("Gorgeous!");
+ * Ett C-exempel:
+ * |[<!-- language="C" -->
+ * GtkWidget *label = gtk_label_new ("Vackert!");
* ]|
*/
-]]></programlisting>
+</programlisting>
</example>
</para>
- <para>
- 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>.
- </para>
+ <para>Fler exempel på vilka markdown-taggar som stöds hittas i <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">Referensen för GTK+-dokumentationens markdown-syntax</ulink>.</para>
<tip>
- <para>
- 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.
- 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>
+ <para>Som redan nämnts är GTK-Doc avsett för att dokumentera publika API:er. Du kan därför inte skriva dokumentation för statiska symboler. Likväl är det bra att kommentera dessa symboler. Det hjälper andra att förstå din kod. Därför rekommenderar vi att du kommenterar dessa med normala kommenterar (utan den andra ”*” på den första raden). Om funktionen vid ett senare tillfälle måste göras publik är allt du behöver göra att lägga till ytterligare en ”*” i kommentarsblocket och infoga symbolnamnet på rätt ställe i avsnittsfilen.</para>
</tip>
</sect1>
<sect1 id="documenting_sections">
- <title>Documenting sections</title>
+ <title>Dokumentationsavsnitt</title>
- <para>
- Each section of the documentation contains information about one class
- or module. To introduce the component one can write a section block.
- The short description is also used inside the table of contents.
- All the @fields are optional.
- </para>
+ <para>Varje avsnitt av dokumentation innehåller information om en klass eller en modul. För att introducera komponenten kan man skriva ett avsnittsblock. Den korta beskrivningen används också i innehållsförteckningen. Alla @fälten är valfria.</para>
<para>
- <example><title>Section comment block</title>
- <programlisting><![CDATA[
+ <example><title>Kommentarsblock för avsnitt</title>
+ <programlisting>
/**
* SECTION:meepapp
- * @short_description: the application class
- * @title: Meep application
+ * @short_description: programklassen
+ * @title: Meep-programmet
* @section_id:
* @see_also: #MeepSettings
* @stability: Stable
* @include: meep/app.h
* @image: application.png
*
- * The application class handles ...
+ * Programklassen hanterar …
*/
-]]></programlisting>
+</programlisting>
</example>
</para>
<variablelist>
<varlistentry>
- <term>SECTION:<name></term>
+ <term>SECTION:<namn></term>
<listitem>
- <para>
- 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.
- </para>
+ <para>Namnet länkar till avsnittsdokumentationen för respektive del i filen <filename><paket>-sections.txt</filename>. Namnet som anges här bör matcha taggen <FILE> i filen <filename><paket>-sections.txt</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@short_description</term>
<listitem>
- <para>
- 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.
- </para>
+ <para>En enradsbeskrivning av avsnittet som senare kommer att visas efter länkar i innehållsförteckningen och lägst upp på avsnittssidan.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@title</term>
<listitem>
- <para>
- The section title defaults to <name> from the SECTION
- declaration. It can be overridden with the @title field.
- </para>
+ <para>Avsnittstiteln är som standard <namn> från SECTION-deklarationen. Den kan åsidosättas med fältet @title.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@section_id</term>
<listitem>
- <para>
- 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>.
- </para>
+ <para>Åsidosätter användningen av titeln som avsnittsidentifierare. För GObjects används <title> som ett section_id och för andra avsnitt är det <MODULE>-<title>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@see_also</term>
<listitem>
- <para>
- A list of symbols that are related to this section.
- </para>
+ <para>En lista över symboler som är relaterade till detta avsnitt.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@stability</term>
<listitem>
- <para>
- An informal description of the stability level this API has.
- We recommend the use of one of these terms:
- <itemizedlist>
+ <para>En informell beskrivning över stabiliteten för detta API. Vi rekommenderar att använda en av dessa termer: <itemizedlist>
<listitem>
- <para>
- Stable
- - The intention of a Stable interface is to enable arbitrary
- third parties to develop applications to these interfaces,
- release them, and have confidence that they will run on all
- minor releases of the product (after the one in which the
- interface was introduced, and within the same major release).
- Even at a major release, incompatible changes are expected
- to be rare, and to have strong justifications.
- </para>
+ <para>Stable - Avsikten med ett stabilt gränssnitt är att möjliggöra för tredje parter att utveckla program mot dessa gränssnitt, släppa dem och vara säkra på att de kommer att köra på alla programfixversioner av produkten (efter den i vilken gränssnittet introducerats, och inom samma huvudversion). Även vid en ny huvudversion förväntas inkompatibla ändringar vara få och vara väl motiverade.</para>
</listitem>
<listitem>
- <para>
- Unstable
- - Unstable interfaces are experimental or transitional.
- They are typically used to give outside developers early
- access to new or rapidly changing technology, or to provide
- an interim solution to a problem where a more general
- solution is anticipated.
- No claims are made about either source or binary
- compatibility from one minor release to the next.
- </para>
+ <para>Unstable - Instabila gränssnitt är experimentella eller i en övergångsfas. De används typiskt för att ge utomstående utvecklare tidig tillgång till ny eller snabbt föränderlig teknologi, eller för att tillhandahålla provisoriska lösningar för ett problem där en mer generell lösning förutses. Inga påståenden görs om endera källkods- eller binärkompatibilitet från en programfixversion till nästa.</para>
</listitem>
<listitem>
- <para>
- Private
- - 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 specified and documented
- ways.
- </para>
+ <para>Private - Ett gränssnitt som kan användas inom GNOME-stacken i sig, men som inte dokumenterats för slutanvändare. Sådana funktioner bör endast användas på angivna och dokumenterade sätt.</para>
</listitem>
<listitem>
- <para>
- Internal
- - An interface that is internal to a module and does not
- require end-user documentation. Functions that are
- undocumented are assumed to be Internal.
- </para>
+ <para>Internal - ett gränssnitt som är internt för en modul och inte behöver slutanvändardokumentation. Funktioner som är odokumenterade förutsätts vara interna.</para>
</listitem>
- </itemizedlist>
- </para>
+ </itemizedlist></para>
</listitem>
</varlistentry>
<varlistentry>
<term>@include</term>
<listitem>
- <para>
- The <literal>#include</literal> files to show in the section
- synopsis (a comma separated list), overriding the global
- value from the <link linkend="metafiles_sections">section
- file</link> or command line. This item is optional.
- </para>
+ <para><literal>#include</literal>-filerna som ska visas i avsnittssammanfattningen (en kommaavgränsad lista), vilket åsidosätter det globala värdet från <link linkend="metafiles_sections">avsnittsfilen</link> eller kommandoraden. Detta objekt är valfritt.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@image</term>
<listitem>
- <para>
- 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 a class or a diagram of its relationship
- to other classes. This item is optional.
- </para>
+ <para>Bilden som ska visas längst upp på referenssidan för detta avsnitt. Detta kommer ofta att vara någon form av diagram för att illustrera det visuella utseendet för en klass eller ett diagram över dess relationer med andra klasser. Detta objekt är valfritt.</para>
</listitem>
</varlistentry>
</variablelist>
<tip>
- <para>
- To avoid unnecessary recompilation after doc-changes put the section
- docs into the c-source where possible.
- </para>
+ <para>För att undvika onödig omkompilering efter dokumentationsändringar, placera avsnittsdokumentationen i c-källkoden där möjligt.</para>
</tip>
</sect1>
<sect1 id="documenting_symbols">
- <title>Documenting symbols</title>
+ <title>Dokumentationssymboler</title>
- <para>
- Each symbol (function, macro, struct, enum, signal and property) is
- documented in a separate block. The block is best placed close to the
- definition of the symbols so that it is easy to keep them in sync.
- Thus functions are usually documented in the c-source and macros,
- structs and enums in the header file.
- </para>
+ <para>Varje symbol (funktion, makro, struktur, uppräkning, signal och egenskap) är dokumenterad i ett separat block. Blocket placeras bäst intill definitionen av symbolerna så att det är enkelt att hålla dem synkroniserade. Därför dokumenteras funktioner vanligtvis i c-källkoden och makron, strukturer och uppräkningar i huvudfilen.</para>
- <sect2><title>General tags</title>
+ <sect2><title>Generella taggar</title>
- <para>
- You can add versioning information to all documentation elements to tell
- when an API was introduced, or when it was deprecated.
- </para>
+ <para>Du kan lägga till versioneringsinformation i alla dokumentationselement för att berätta när ett API introducerats eller blev föråldrat.</para>
- <variablelist><title>Versioning Tags</title>
+ <variablelist><title>Versioneringstaggar</title>
<varlistentry><term>Since:</term>
<listitem>
- <para>
- Description since which version of the code the API is available.
- </para>
+ <para>Beskrivning över från och med vilken version av koden som API:t är tillgängligt.</para>
</listitem>
</varlistentry>
<varlistentry><term>Deprecated:</term>
<listitem>
- <para>
- Paragraph denoting that this function should no be used anymore.
- The description should point the reader to the new API.
- </para>
+ <para>Stycke som betecknar att denna funktion inte bör användas längre. Beskrivningen bör peka läsaren vidare till det nya API:t.</para>
</listitem>
</varlistentry>
</variablelist>
- <para>
- 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.
- </para>
+ <para>Du kan också lägga till stabilitetsinformation för alla dokumentationselement för att indikera huruvida API-stabilitet är garanterad för dem för alla framtida programfix-versioner av projektet.</para>
- <para>
- 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.
- </para>
+ <para>Standardvärdet för stabilitetsnivån för alla dokumentations element kan ställas in genom att ange argumentet <option>--default-stability</option> till <application>gtkdoc-mkdb</application> med endera av värdena nedan.</para>
- <variablelist><title>Stability Tags</title>
+ <variablelist><title>Stabilitetstaggar</title>
<varlistentry><term>Stability: Stable</term>
<listitem>
- <para>
- Mark the element as stable. This is for public APIs which are
- guaranteed to remain stable for all future minor releases of the
- project.
- </para>
+ <para>Markera elementet som stabilt. Detta är för publika API:er som är garanterade att hållas stabila i alla framtida programfix-versioner av projektet.</para>
</listitem>
</varlistentry>
<varlistentry><term>Stability: Unstable</term>
<listitem>
- <para>
- Mark the element as unstable. This is for public APIs which are
- released as a preview before being stabilised.
- </para>
+ <para>Markera elementet som instabilt. Detta är för publika API:er som är släppta på förhand innan de blivit stabiliserade.</para>
</listitem>
</varlistentry>
<varlistentry><term>Stability: Private</term>
<listitem>
- <para>
- Mark the element as private. This is for interfaces which can be
- used by tightly coupled modules, but not by arbitrary third
- parties.
- </para>
+ <para>Markera element som privat. Detta är avsett för gränssnitt som kan användas av tätt sammankopplade moduler, men inte av godtyckliga tredje parter.</para>
</listitem>
</varlistentry>
</variablelist>
- <example><title>General tags</title>
- <programlisting><![CDATA[
+ <example><title>Generella taggar</title>
+ <programlisting>
/**
* foo_get_bar:
- * @foo: some foo
+ * @foo: någon foo
*
- * Retrieves @foo's bar.
+ * Hämtar bar från @foo.
*
- * Returns: @foo's bar
+ * Returns: bar från @foo
*
* Since: 2.6
- * Deprecated: 2.12: Use foo_baz_get_bar() instead.
+ * Deprecated: 2.12: Använd foo_baz_get_bar() istället.
*/
Bar *
foo_get_bar(Foo *foo)
{
-...
-]]></programlisting>
+…
+</programlisting>
</example>
</sect2>
- <sect2><title>Annotations</title>
+ <sect2><title>Noteringar</title>
- <para>
- 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>.
- </para>
+ <para>Dokumentationsblock kan innehålla noteringstaggar. Dessa taggar kommer att renderas som verktygstips som beskriver deras syfte. Taggarna används av gobject-introspection för att generera språkbindningar. En detaljerad lista över vilka taggar som stöds hittas på <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">wikisidan</ulink>.</para>
- <example><title>Annotations</title>
- <programlisting><![CDATA[
+ <example><title>Noteringar</title>
+ <programlisting>
/**
- * foo_get_bar: (annotation)
- * @foo: (annotation): some foo
+ * foo_get_bar: (notering)
+ * @foo: (notering): någon foo
*
- * Retrieves @foo's bar.
+ * Hämtar bar från @foo.
*
- * Returns: (annotation): @foo's bar
+ * Returns: (notering): bar från @foo
*/
...
/**
- * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)
- * (and another annotation)
- * @foo: (annotation) (another annotation): some foo
+ * foo_set_bar_using_the_frobnicator: (notering) (an annan notering)
+ * (ytterligare en annan notering)
+ * @foo: (notering) (en annan notering): någon foo
*
- * Sets bar on @foo.
+ * Ställer in bar i @foo.
*/
-]]></programlisting>
+</programlisting>
</example>
</sect2>
- <sect2><title>Function comment block</title>
+ <sect2><title>Kommentarsblock för funktioner</title>
- <para>
- Please remember to:
- <itemizedlist>
+ <para>Kom ihåg att: <itemizedlist>
<listitem>
- <para>
- Document whether returned objects, lists, strings, etc, should be
- freed/unrefed/released.
- </para>
+ <para>Dokumentera huruvida returnerade objekt, listor, strängar, etc. bör frigöras/avrefereras/släppas.</para>
</listitem>
<listitem>
- <para>
- Document whether parameters can be NULL, and what happens if they are.
- </para>
+ <para>Dokumentera huruvida parametrar tillåts vara NULL och vad som händer om de är NULL.</para>
</listitem>
<listitem>
- <para>
- Mention interesting pre-conditions and post-conditions where appropriate.
- </para>
+ <para>Nämn intressanta förvillkor och eftervillkor där lämpligt.</para>
</listitem>
- </itemizedlist>
- </para>
+ </itemizedlist></para>
- <para>
- Gtk-doc assumes all symbols (macros, functions) starting with '_' are
- private. They are treated like static functions.
- </para>
+ <para>Gtk-doc förutsätter att alla symboler (makron, funktioner) som börjar med ”_” är privata. De behandlas på samma sätt som statiska funktioner.</para>
- <example><title>Function comment block</title>
- <programlisting><![CDATA[
+ <example><title>Kommentarsblock för funktioner</title>
+ <programlisting>
/**
- * function_name:
- * @par1: description of parameter 1. These can extend over more than
- * one line.
- * @par2: description of parameter 2
- * @...: a %NULL-terminated list of bars
+ * funktionsnamn:
+ * @par1: beskrivning av parameter 1. Dessa kan sträcka sig
+ * över mer än en rad.
+ * @par2: beskrivning av parameter 2
+ * @...: en %NULL-terminerad lista av flera bar
*
- * The function description goes here. You can use @par1 to refer to parameters
- * so that they are highlighted in the output. You can also use %constant
- * for constants, function_name2() for functions and #GtkWidget for links to
- * other declarations (which may be documented elsewhere).
+ * Funktionsbeskrivningen ska vara här. Du kan använda @par1 för att
+ * referera till parametrar så att de färgmarkeras i utdata. Du kan också
+ * använda %konstant för konstanter, funktionsnamn2() för funktioner och
+ * #GtkWidget för länkar till andra deklarationer (vilka kan vara dokumenterade
+ * på annat håll).
*
- * Returns: an integer.
+ * Returns: ett heltal.
*
* Since: 2.2
- * Deprecated: 2.18: Use other_function() instead.
+ * Deprecated: 2.18: Använd annan_funktion() istället.
*/
-]]></programlisting>
+</programlisting>
</example>
- <variablelist><title>Function tags</title>
+ <variablelist><title>Funktions-taggar</title>
<varlistentry><term>Returns:</term>
<listitem>
- <para>
- Paragraph describing the returned result.
- </para>
+ <para>Stycke som beskriver det returnerade resultatet.</para>
</listitem>
</varlistentry>
<varlistentry><term>@...:</term>
<listitem>
- <para>
- In case the function has variadic arguments, you should use this
- tag (@Varargs: does also work for historic reasons).
- </para>
+ <para>Om funktionen har variadiska argument bör du använda denna tagg (@Varargs: fungerar också på grund av historiska skäl).</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
- <sect2><title>Property comment block</title>
+ <sect2><title>Kommentarsblock för egenskaper</title>
- <example><title>Property comment block</title>
- <programlisting><![CDATA[
+ <example><title>Kommentarsblock för egenskaper</title>
+ <programlisting>
/**
- * SomeWidget:some-property:
+ * EnKomponent:en-egenskap:
*
- * Here you can document a property.
+ * Här kan du dokumentera en egenskap.
*/
-g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
-]]></programlisting>
+g_object_class_install_property (object_class, PROP_EN_EGENSKAP, …);
+</programlisting>
</example>
</sect2>
- <sect2><title>Signal comment block</title>
+ <sect2><title>Kommentarsblock för signaler</title>
- <para>
- Please remember to:
- <itemizedlist>
+ <para>Kom ihåg att: <itemizedlist>
<listitem>
- <para>
- Document when the signal is emitted and whether it is emitted before
- or after other signals.
- </para>
+ <para>Dokumentera när en signal sänds ut och huruvida den sänds ut före eller efter andra signaler.</para>
</listitem>
<listitem>
- <para>
- Document what an application might do in the signal handler.
- </para>
+ <para>Dokumentera vad ett program kan göra i signalhanteraren.</para>
</listitem>
- </itemizedlist>
- </para>
+ </itemizedlist></para>
- <example><title>Signal comment block</title>
- <programlisting><![CDATA[
+ <example><title>Kommentarsblock för signaler</title>
+ <programlisting>
/**
- * FooWidget::foobarized:
- * @widget: the widget that received the signal
- * @foo: some foo
- * @bar: some bar
+ * FooWidget::foobariserad:
+ * @widget: komponenten som erhåller signalen
+ * @foo: någon foo
+ * @bar: någon bar
*
- * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
+ * Signalen ::foobarized sänds ut varje gång någon försöker att foobarisera @widget.
*/
foo_signals[FOOBARIZE] =
- g_signal_new ("foobarize",
+ g_signal_new ("foobarisera",
...
-]]></programlisting>
+</programlisting>
</example>
</sect2>
- <sect2><title>Struct comment block</title>
- <example><title>Struct comment block</title>
- <programlisting><![CDATA[
+ <sect2><title>Kommentarsblock för strukturer</title>
+ <example><title>Kommentarsblock för strukturer</title>
+ <programlisting>
/**
* FooWidget:
- * @bar: some #gboolean
+ * @bar: någon #gboolean
*
- * This is the best widget, ever.
+ * Detta är den bästa komponenten någonsin.
*/
typedef struct _FooWidget {
GtkWidget parent_instance;
gboolean bar;
} FooWidget;
-]]></programlisting>
+</programlisting>
</example>
- <para>
- Use <code>/*< private >*/</code> before the private struct fields
- you want to hide. Use <code>/*< public >*/</code> for the reverse
- behaviour.
- </para>
+ <para>Använd<code>/*< private >*/</code> före privata strukturfält som du vill gömma. Använd <code>/*< public >*/</code> för det omvända beteendet.</para>
- <para>
- 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.
- </para>
+ <para>Om det första fältet är ”g_iface”, ”parent_instance” eller ”parent_class” kommer det att anses vara privat automatiskt och behöver inte nämnas i kommentarsblocket.</para>
- <para>
- 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
- vmethods (as this is how they can be documented). For the GObject
- itself one can use the related section docs, having a separate block
- for the instance struct would be useful if the instance has public
- fields. One disadvantage here is that this creates two index entries
- of the same name (the structure and the section).
- </para>
+ <para>Kommentarsblock för strukturer kan också användas för GObject och GObjectClass. Det är vanligtvis en bra idé att lägga till ett kommentarsblock för en klass om den har virtuella metoder (då detta är sättet på vilket de kan dokumenteras). För GObject i sig kan man använda den relaterade avsnittsdokumentationen, och ha ett separat block för varje instansstruktur vore användbart om instansen har publika fält. En nackdel här är att det skapar två indexposter med samma namn (strukturen och avsnittet).</para>
</sect2>
- <sect2><title>Enum comment block</title>
- <example><title>Enum comment block</title>
- <programlisting><![CDATA[
+ <sect2><title>Kommentarsblock för uppräkningar</title>
+ <example><title>Kommentarsblock för uppräkningar</title>
+ <programlisting>
/**
* Something:
- * @SOMETHING_FOO: something foo
- * @SOMETHING_BAR: something bar
+ * @SOMETHING_FOO: någonting foo
+ * @SOMETHING_BAR: någonting bar
*
- * Enum values used for the thing, to specify the thing.
+ * Uppräkningsvärden som används för saken, för att specificera saken.
*/
typedef enum {
SOMETHING_FOO,
SOMETHING_BAR,
- /*< private >*/
+ /*< private >*/
SOMETHING_COUNT
} Something;
-]]></programlisting>
+</programlisting>
</example>
- <para>
- Use <code>/*< private >*/</code> before the private enum values
- you want to hide. Use <code>/*< public >*/</code> for the reverse
- behaviour.
- </para>
+ <para>Använd <code>/*< private >*/</code> före privata uppräkningsvärden som du vill gömma. Använd <code>/*< public >*/</code> för det omvända beteendet.</para>
</sect2>
</sect1>
- <sect1 id="documenting_docbook">
- <title>Useful DocBook tags</title>
- <para>
- Here are some DocBook tags which are most useful when documenting the
- code.
- </para>
+ <sect1 id="documenting_inline_program">
+ <title>Infogad programdokumentation</title>
+ <para>Du kan dokumentera program och deras kommandoradsgränssnitt med infogad dokumentation.</para>
- <para>
- To link to another section in the GTK docs:
-
- <informalexample>
- <programlisting><![CDATA[
-<link linkend="glib-Hash-Tables">Hash Tables</link>
-]]></programlisting>
- </informalexample>
- The linkend is the SGML/XML id on the top item of the page you want to link to.
- For most pages this is currently the part ("gtk", "gdk", "glib") and then
- the page title ("Hash Tables"). For widgets it is just the class name.
- Spaces and underscores are converted to '-' to conform to SGML/XML.
- </para>
+ <variablelist>
+ <title>Taggar</title>
- <para>
- To refer to an external function, e.g. a standard C function:
- <informalexample>
- <programlisting><![CDATA[
-<function>...</function>
-]]></programlisting>
- </informalexample>
- </para>
+ <varlistentry><term>PROGRAM</term>
- <para>
- To include example code:
- <informalexample>
- <programlisting><![CDATA[
-<example>
- <title>Using a GHashTable.</title>
- <programlisting>
- ...
- </programlisting>
-</example>
-]]></programlisting>
- </informalexample>
- or possibly this, for very short code fragments which don't need a title:
- <informalexample>
- <programlisting><![CDATA[
-<informalexample>
- <programlisting>
- ...
- </programlisting>
-</informalexample>
-]]></programlisting>
- </informalexample>
- For the latter GTK-Doc also supports an abbreviation:
-<![CDATA[
-|[
- ...
-]|
-]]>
- </para>
+ <listitem>
+ <para>Definierar början av programdokumentationen.</para>
+ </listitem>
+ </varlistentry>
- <para>
- To include bulleted lists:
- <informalexample>
- <programlisting><![CDATA[
-<itemizedlist>
- <listitem>
- <para>
- ...
- </para>
- </listitem>
- <listitem>
- <para>
- ...
- </para>
- </listitem>
-</itemizedlist>
-]]></programlisting>
- </informalexample>
- </para>
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>Definierar en kort beskrivning av programmet. (Valfritt)</para>
+ </listitem>
+ </varlistentry>
- <para>
- To include a note which stands out from the text:
- <informalexample>
- <programlisting><![CDATA[
-<note>
- <para>
- Make sure you free the data after use.
- </para>
-</note>
-]]></programlisting>
- </informalexample>
- </para>
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>Definierar argumenten, eller en lista av argument som programmet kan ta. (Valfritt)</para>
+ </listitem>
+ </varlistentry>
- <para>
- To refer to a type:
- <informalexample>
- <programlisting><![CDATA[
-<type>unsigned char</type>
-]]></programlisting>
- </informalexample>
- </para>
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>Se vidare i manualavsnitt. (Valfritt)</para>
+ </listitem>
+ </varlistentry>
- <para>
- To refer to an external structure (not one described in the GTK docs):
- <informalexample>
- <programlisting><![CDATA[
-<structname>XFontStruct</structname>
-]]></programlisting>
- </informalexample>
- </para>
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>Argument som skickas vidare till programmet och deras beskrivningar. (Valfritt)</para>
+ </listitem>
+ </varlistentry>
- <para>
- To refer to a field of a structure:
- <informalexample>
- <programlisting><![CDATA[
-<structfield>len</structfield>
-]]></programlisting>
- </informalexample>
- </para>
+ <varlistentry>
+ <term>Beskrivning:</term>
+ <listitem>
+ <para>En längre beskrivning av programmet.</para>
+ </listitem>
+ </varlistentry>
- <para>
- To refer to a class name, we could possibly use:
- <informalexample>
- <programlisting><![CDATA[
-<classname>GtkWidget</classname>
-]]></programlisting>
- </informalexample>
- but you'll probably be using #GtkWidget instead (to automatically create
- a link to the GtkWidget page - see <link linkend="documenting_syntax">the abbreviations</link>).
- </para>
+ <varlistentry>
+ <term>Returns:</term>
+ <listitem>
+ <para>Ange vilka värden programmet returnerar. (Valfritt)</para>
+ </listitem>
+ </varlistentry>
- <para>
- To emphasize text:
- <informalexample>
- <programlisting><![CDATA[
-<emphasis>This is important</emphasis>
-]]></programlisting>
- </informalexample>
- </para>
+ </variablelist>
- <para>
- For filenames use:
- <informalexample>
- <programlisting><![CDATA[
-<filename>/home/user/documents</filename>
-]]></programlisting>
- </informalexample>
- </para>
+ <sect2>
+ <title>Exempel på programdokumentation.</title>
+ <example><title>Dokumentationsblock för program</title>
+ <programlisting>
+/**
+ * PROGRAM:test-program
+ * @short_description: Ett testprogram
+ * @synopsis: test-program [*FLAGGOR*...] --arg1 *arg* *FIL*
+ * @see_also: test(1)
+ * @--arg1 *arg*: ställ in arg1 på *arg*
+ * @--arg2 *arg*: ställ in arg2 på *arg*
+ * @-v, --version: Skriv ut versionsinformation
+ * @-h, --help: Skriv ut hjälpmeddelandet
+ *
+ * En längre beskrivning av programmet.
+ *
+ * Returns: Noll vid framgång, icke-noll vid fel
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+</programlisting>
+ </example>
- <para>
- To refer to keys use:
- <informalexample>
- <programlisting><![CDATA[
-<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
-]]></programlisting>
- </informalexample>
- </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="documenting_docbook">
+ <title>Användbara DocBook-taggar</title>
+
+ <para>Här är några DocBook-taggar som är användbara när man dokumenterar koden.</para>
+
+ <para>För att länka till ett annat avsnitt i GTK-dokumentationen: <informalexample>
+ <programlisting>
+<link linkend="glib-Hash-Tables">Hashtabeller</link>
+</programlisting>
+ </informalexample> Länkslutet är XGML/XML-id:t för toppnivåobjektet på sidan du vill länka till. För de flesta sidorna är detta för närvarande delen (”gtk”, ”gdk”, ”glib”) och sedan sidans titel (”Hashtabeller”). För komponenter är detta helt enkelt klassnamnet. Blanksteg och understreck konverteras till ”-” för att överensstämma med SGML/XML.</para>
+
+ <para>För att referera till en extern funktion, t.ex. en standardfunktion i C: <informalexample>
+ <programlisting>
+<function>…</function>
+</programlisting>
+ </informalexample></para>
+
+ <para>För att inkludera exempelkod: <informalexample>
+ <programlisting>
+<example>
+ <title>Att använda en hashtabell.</title>
+ <programlisting>
+ …
+ </programlisting>
+</example>
+</programlisting>
+ </informalexample> eller möjligen följande, för väldigt korta kodfragment som inte behöver en titel: <informalexample>
+ <programlisting>
+<informalexample>
+ <programlisting>
+ …
+ </programlisting>
+</informalexample>
+</programlisting>
+ </informalexample> För det senare fallet har GTK-Doc också stöd för förkortningen: |[ … ]|</para>
+
+ <para>För att inkludera punktlistor: <informalexample>
+ <programlisting>
+<itemizedlist>
+ <listitem>
+ <para>
+ …
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ …
+ </para>
+ </listitem>
+</itemizedlist>
+</programlisting>
+ </informalexample></para>
+
+ <para>För att inkludera en not som skiljer sig från texten: <informalexample>
+ <programlisting>
+<note>
+ <para>
+ Säkerställ att du frigjort data efter användning.
+ </para>
+</note>
+</programlisting>
+ </informalexample></para>
+
+ <para>För att refera till en typ: <informalexample>
+ <programlisting>
+<type>unsigned char</type>
+</programlisting>
+ </informalexample></para>
+
+ <para>För att referera till en extern struktur (som inte beskrivs i GTK-dokumentationen): <informalexample>
+ <programlisting>
+<structname>XFontStruct</structname>
+</programlisting>
+ </informalexample></para>
+
+ <para>För att referera till ett fält för en struktur: <informalexample>
+ <programlisting>
+<structfield>len</structfield>
+</programlisting>
+ </informalexample></para>
+
+ <para>För att referera till ett klassnamn kan vi möjligen använda: <informalexample>
+ <programlisting>
+<classname>GtkWidget</classname>
+</programlisting>
+ </informalexample> men du kommer troligt att använda #GtkWidget istället (för att automatiskt skapa en länk till GtkWidget-sidan - se <link linkend="documenting_syntax">förkortningarna</link>).</para>
+
+ <para>För att betona text: <informalexample>
+ <programlisting>
+<emphasis>Detta är viktigt</emphasis>
+</programlisting>
+ </informalexample></para>
+
+ <para>För filnamn använd: <informalexample>
+ <programlisting>
+<filename>/home/användare/dokument</filename>
+</programlisting>
+ </informalexample></para>
+
+ <para>För att referera till tangenter använd: <informalexample>
+ <programlisting>
+<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
+</programlisting>
+ </informalexample></para>
</sect1>
</chapter>
<chapter id="metafiles">
- <title>Filling the extra files</title>
+ <title>Fylla i de extra filerna</title>
- <para>
- 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>-docs.xml</filename> (in the past .sgml),
- <filename><package>-sections.txt</filename>.
- </para>
+ <para>Det finns ett antal extra filer som behöver underhållas tillsammans med de infogade källkodskommentarerna: <filename><paket>.types</filename>, <filename><paket>-docs.xml</filename> (tidigare .sgml), <filename><paket>-sections.txt</filename>.</para>
<sect1 id="metafiles_types">
- <title>Editing the types file</title>
+ <title>Redigera typfilen</title>
- <para>
- 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.
- </para>
+ <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>Example types file snippet</title>
- <programlisting><![CDATA[
-#include <gtk/gtk.h>
+ <example><title>Exempel på typfilsnutt</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>
- Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this list for you.
- Just add "--rebuild-types" to SCAN_OPTIONS in <filename>Makefile.am</filename>. If you
- use this approach you should not dist the types file nor have it under version control.
- </para>
+ <para>Sedan GTK-Doc 1.8 kan <application>gtkdoc-scan</application> generera denna lista åt dig. Lägg bara till ”--rebuild-types” i SCAN_OPTIONS i <filename>Makefile.am</filename>. Om du använder detta tillvägagångssätt bör du inte distribuera typfilen eller versionshantera den.</para>
</sect1>
<sect1 id="metafiles_master">
- <title>Editing the master document</title>
+ <title>Redigera huvuddokumentet</title>
- <para>
- GTK-Doc produces documentation in DocBook SGML/XML. When processing the
- inline source comments, the GTK-Doc tools generate one documentation
- page per class or module as a separate file. The master document
- includes them and place them in an order.
- </para>
+ <para>GTK-Doc producerar dokumentation i DocBook SGML/XML. När infogade källkodskommentarer behandlas genererar GTK-Doc en dokumentationssida per klass eller modul som en separat fil. Huvuddokumentet inkluderar dem och placerar dem i en ordning.</para>
- <para>
- 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.
- </para>
+ <para>Även om GTK-Doc skapar en mall för huvuddokumentet åt dig kommer senare körningar inte att röra det igen. Detta innebär att man är fri att strukturera om dokumentationen. Detta inkluderar att gruppera sidor och lägga till extra sidor. GTK-Doc har numera en testsvit där också huvuddokumentet återskapas från grunden. Det är en bra idé att titta på detta då och då för att se om några nya godsaker införts där.</para>
<tip>
- <para>
- Do not create tutorials as extra documents. Just write extra chapters.
- The benefit of directly embedding the tutorial for your library into
- the API documentation is that it is easy to link for the tutorial to
- symbol documentation. Apart chances are higher that the tutorial gets
- updates along with the library.
- </para>
+ <para>Skapa inte handledningar som extra dokument. Skriv bara extra kapitel. Fördelen med att bädda in handledningen direkt i ditt biblioteks gränssnittsdokumentation är att det är enkelt att länka från handledningen till symboldokumentationen. Inbäddad är det större chans att handledningen blir uppdaterad tillsammans med biblioteket.</para>
</tip>
- <para>
- 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 which you should take care of.
- </para>
+ <para>Så vilka saker ska ändras i huvuddokumentet? I början är det väldigt lite. Det finns en del platshållare (text i hakparenteser) som du bör ta hand om.</para>
<para>
- <example><title>Master document header</title>
- <programlisting><![CDATA[
-<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>
-
-<chapter>
- <title>[Insert title here]</title>
-]]></programlisting>
+ <example><title>Huvuddokumentets huvud</title>
+ <programlisting>
+<bookinfo>
+ <title>MODULNAMN handbok</title>
+ <releaseinfo>
+ för MODULNAMN [VERSION]
+ Den senaste versionen av detta dokument kan hittas på nätet på
+ <ulink role="online-location" url="http://[SERVER]/MODULNAMN/index.html">http://[SERVER]/MODULNAMN/</ulink>.
+ </releaseinfo>
+</bookinfo>
+
+<chapter>
+ <title>[Infoga titel här]</title>
+</programlisting>
</example>
</para>
+ <para>Dessutom finns det ett antal valfria element som skapas i kommenterad form. Du kan granska dessa och aktivera dem enligt dina egna önskemål.</para>
+
<para>
- In addition a few option elements are created in commented form. You can
- review these and enable them as you like.
- </para>
-
- <para>
- <example><title>Optional part in the master document</title>
- <programlisting><![CDATA[
- <!-- enable this when you use gobject introspection annotations
- <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
-]]></programlisting>
+ <example><title>Valfri del i huvuddokumentet</title>
+ <programlisting>
+ <!-- aktivera detta om du vill använda gobject introspection-noteringar
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+ -->
+</programlisting>
</example>
</para>
-
- <para>
- 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.
- </para>
+
+ <para>Slutligen behöver du lägga till ett nytt avsnitt när du infogar det. Verktyget <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> kommer att påminna dig om nyligen genererade xml-filer som ännu inte infogats i dokumentationen.</para>
<para>
- <example><title>Including generated sections</title>
- <programlisting><![CDATA[
- <chapter>
- <title>my library</title>
- <xi:include href="xml/object.xml"/>
+ <example><title>Inkludera genererade avsnitt</title>
+ <programlisting>
+ <chapter>
+ <title>mitt bibliotek</title>
+ <xi:include href="xml/object.xml"/>
...
-]]></programlisting>
+</programlisting>
</example>
</para>
</sect1>
<sect1 id="metafiles_sections">
- <title>Editing the section file</title>
+ <title>Redigera avsnittsfilen</title>
- <para>
- 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 the visibility (public or private).
- </para>
+ <para>Avsnittsfilen används för att organisera dokumentationsutdata från GTK-Doc. Här kan man ange vilken symbol som hör till vilken modul eller klass och styra synligheten (publik eller privat).</para>
+
+ <para>Avsnittsfilen är en vanlig textfil med taggar som avgränsar avsnitt. Blankrader ignoreras och rader som börjar med ett ”#” behandlas som kommentarsrader.</para>
- <para>
- 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.
- </para>
-
<note>
- <para>
- While the tags make the file look like xml, it is not. Please do not
- close tags like <SUBSECTION>.
- </para>
+ <para>Även om taggarna får filen att se ut som xml, är det inte det. Avsluta inte taggar så som <SUBSECTION>.</para>
</note>
<para>
- <example><title>Including generated sections</title>
- <programlisting><![CDATA[
-<INCLUDE>libmeep/meep.h</INCLUDE>
+ <example><title>Inkludera genererade avsnitt</title>
+ <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>
- <para>
- 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 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).
- </para>
+ <para>Taggen <FILE> … </FILE> används för att ange filnamnet, utan något suffix. Om man t.ex. använder ”<FILE>gnome-config</FILE>” blir resultatet att avsnittsdeklarationerna matas ut i mallfilen <filename>tmpl/gnome-config.sgml</filename>, som kommer att konverteras till DocBook XML-filen <filename>xml/gnome-config.sgml</filename> eller DocBook XML-filen <filename>xml/gnome-config.xml</filename>. (Namnet på HTML-filen baseras på modulnamnet och avsnittstiteln, för GObject baseras det på klassnamnet för GObjectet konverterat till gemener).</para>
- <para>
- The <TITLE> ... </TITLE> tag is used to specify the title of
- the section. It is only useful before the templates (if used) are
- initially created, since the title set in the template file overrides
- this. Also if one uses SECTION comment in the sources, this is obsolete.
- </para>
+ <para>Taggen <TITLE> … </TITLE> används för att ange titeln på avsnittet. Det är bara användbart före mallar skapas initialt (om de används), eftersom titeln som ställs in i avsnittsfilen åsidosätter denna. Vidare är detta föråldrat om man använder SECTIONS-kommentarer i källkoden.</para>
- <para>
- 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).
- </para>
+ <para>Du kan gruppera objekt i avsnittet genom att använda taggen <SUBSECTION>. För närvarande matas en blankrad ut mellan underavsnitt i sammanfattningsavsnittet. Du kan också använda <SUBSECTION Standard> för standard GObject-deklarationer (t.ex. funktioner så som g_object_get_type och makron som G_OBJECT(), G_IS_OBJECT(), etc.). För närvarande utelämnas dessa ur dokumentationen. Du kan också använda <SUBSECTION Private> för privata deklarationer som inte kommer att matas ut (det är ett bekvämt sätt att undvika varningsmeddelanden om oanvända deklarationer). Om ditt bibliotek innehåller privata typer som du inte vill ska dyka upp i objekthierarkin och i listan över implementerade eller krävda gränssnitt, lägg till dem i ett privat avsnitt. Huruvida du vill placera GObject och GObjectClass-liknande strukturer i publika eller standardavsnitt beror på om de har publika poster (variabler, virtuella metoder).</para>
- <para>
- You can also use <INCLUDE> ... </INCLUDE> to specify the
- #include files which are shown in the synopsis sections.
- It contains a comma-separate list of #include files, without the angle
- brackets. If you set it outside of any sections, it acts for all
- sections until the end of the file. If you set it within a section, it
- only applies to that section.
- </para>
+ <para>Du kan också använda <INCLUDE> ... </INCLUDE> för att ange #include-filerna som ska visas i sammanfattningsavsnitten. Den innehåller en kommaavgränsad lista av #include-filer, utan vinkelparenteser. Om du ställer in det utanför några avsnitt kommer det att påverka alla avsnitt tills slutet på filen. Om du ställer in det inom ett avsnitt kommer det bara att påverka det avsnittet.</para>
</sect1>
</chapter>
<chapter id="reports">
- <title>Controlling the result</title>
-
- <para>
- A GTK-Doc run generates report files inside the documentation directory.
- The generated files are named:
- <filename><package>-undocumented.txt</filename>,
- <filename><package>-undeclared.txt</filename> and
- <filename><package>-unused.txt</filename>.
- All those are plain text files that can be viewed and postprocessed easily.
- </para>
-
- <para>
- The <filename><package>-undocumented.txt</filename> file starts with
- the documentation coverage summary. Below are two sections divided by
- blank lines. The first section lists undocumented or incomplete symbols.
- The second section does the same for section docs. Incomplete entries are
- those, which have documentation, but where e.g. a new parameter has been
- added.
- </para>
-
- <para>
- The <filename><package>-undeclared.txt</filename> file lists symbols
- given in the <filename><package>-sections.txt</filename> but not
- found in the sources. Check if they have been removed or if they are
- misspelled.
- </para>
-
- <para>
- The <filename><package>-unused.txt</filename> file lists symbol
- names, where the GTK-Doc scanner has found documentation, but does not
- know where to put it. This means that the symbol has not yet been added to
- the <filename><package>-sections.txt</filename> file.
- </para>
+ <title>Kontrollera resultatet</title>
+
+ <para>En GTK-Doc-körning genererar rapportfiler inuti dokumentationskatalogen. De genererade filerna heter: <filename><paket>-undocumented.txt</filename>, <filename><paket>-undeclared.txt</filename> och <filename><paket>-unused.txt</filename>. Alla är vanliga textfiler och kan visas eller efterbehandlas enkelt.</para>
+
+ <para>Filen <filename><paket>-undocumented.txt</filename> inleds med en sammanfattning över hur mycket dokumentation som skrivits. Under det finns två avsnitt avgränsade av blankrader. Det första avsnittet listar odokumenterade eller ofullständiga symboler. Det andra avsnittet gör detsamma för avsnittsdokumentation. Ofullständiga poster är de som har dokumentation, men där en ny parameter har lagts till.</para>
+
+ <para>Filen <filename><paket>-undeclared.txt</filename> listar symboler som anges i <filename><paket>-sections.txt</filename> men inte hittas i källkoden. Kontrollera om de har tagits bort eller om de är felstavade.</para>
+
+ <para>Filen <filename><paket>-unused.txt</filename> listar symbolnamn där GTK-Doc-detektorn har hittat dokumentation men inte vet var den ska placeras. Detta innebär att symbolen ännu inte har lagts till i filen <filename><package>-sections.txt</filename>.</para>
<tip>
- <para>
- 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
- <command>make check</command> run.
- </para>
+ <para>Aktivera eller lägg till raden <option>TESTS=$(GTKDOC_CHECK)</option> i Makefile.am. Om åtminstone GTK-Doc 1.9 finns installerat kommer detta att köra rimlighetskontroller under körning av <command>make check</command>.</para>
</tip>
- <para>
- 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.
- </para>
-
- <para>
- 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 GTK-Doc to keep the intermediate
- scanner file for further analysis, by running it as
- <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
- </para>
+ <para>Man kan också titta på filerna som producerats av källkodsdetektorn: <filename><paket>-decl-list.txt</filename> och <filename><paket>-decl.txt</filename>. Den första kan jämföras med avsnittsfilen om den underhålls manuellt. Den andra listar alla deklarationer från huvudena. Om en symbol saknas bör man kontrollera om denna filen innehåller den.</para>
+
+ <para>Om projektet är GObject-baserat kan man också titta på filerna som producerats av objekt-detektorn: <filename><paket>.args.txt</filename>, <filename><paket>.hierarchy.txt</filename>, <filename><paket>.interfaces.txt</filename>, <filename><paket>.prerequisites.txt</filename> och <filename><paket>.signals.txt</filename>. Om det saknas symboler i någon av dem kan man be GTK-Doc att bibehålla de temporära detektorfilerna för vidare analys, genom att köra det som <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.</para>
</chapter>
-
+
<chapter id="modernizing">
- <title>Modernizing the documentation</title>
-
- <para>
- 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.
- </para>
-
+ <title>Modernisera dokumentationen</title>
+
+ <para>GTK-Doc har funnits ett tag. I detta avsnitt listar vi nya funktioner tillsammans med vilken version de gjordes tillgängliga.</para>
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
- <para>
- When using xml instead of sgml, one can actually name the master
- document <filename><package>-docs.xml</filename>.
- </para>
-
- <para>
- 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>.
- </para>
-
- <para>
- 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 you source control system and haven't yet switched, just
- add the flag to <filename>configure.ac</filename> and you are done.
- </para>
+ <para>När man använder xml istället för sgml, kan man faktiskt kalla huvuddokumentet <filename><paket>-docs.xml</filename>.</para>
+
+ <para>Denna version har stöd för <option>SCAN_OPTIONS=--rebuild-sections</option> i <filename>Makefile.am</filename>. När detta är aktiverat kommer <filename><paket>-sections.txt</filename> att autogenereras och kan tas bort från versionshanteringssystemet. Detta fungerar bra för projekt som har en väldigt standardiserad struktur (t.ex. kommer varje .{c,h}-par att skapa ett nytt avsnitt). Om man organiserar ett projekt likt detta kommer den manuella uppdateringen av en avsnittsfil att vara så enkelt som att köra <code>meld <paket>-decl-list.txt <paket>-sections.txt</code>.</para>
+
+ <para>Redan version 1.8 introducerade syntaxen för avsnittsdokumentation i källkoden istället för separata filer under <filename class="directory">tmpl</filename>. Denna version lägger till flaggor för att kunna ställa om hela dokumentationsmodulen till att inte använda det extra tmpl-byggsteget alls, genom att använda <option>--flavour no-tmpl</option> i <filename>configure.ac</filename>. Om du inte har <filename class="directory">tmpl</filename> incheckat i ditt versionshanteringssystem just nu och inte har gått över än bara lägg till flaggan i <filename>configure.ac</filename> så är du klar.</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
- <para>
- 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.
- </para>
+ <para>Denna version har stöd för <option>SCAN_OPTIONS=--rebuild-types</option> i <filename>Makefile.am</filename>. När det är aktiverat kommer <filename><package>.types</filename> att autogenereras och kan tas bort från versionshanteringssystemet. När denna funktion används är det viktigt att också ställa in <varname>IGNORE_HFILES</varname> i <filename>Makefile.am</filename> för kod som bara byggs ibland.</para>
</sect1>
<sect1 id="modernizing-gtk-doc-1-16">
<title>GTK-Doc 1.16</title>
- <para>
- 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><title>Enable gtkdoc-check</title>
- <programlisting><![CDATA[
+ <para>Denna version har stöd för ett nytt verktyg som heter gtkdoc-check. Detta verktyg kan köra en uppsättning kontroller på din dokumentation. Det aktiveras genom att lägga till dessa raderna i slutet av <filename>Makefile.am</filename>. <example><title>Aktivera gtkdoc-check</title>
+ <programlisting>
if ENABLE_GTK_DOC
TESTS_ENVIRONMENT = \
DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
TESTS = $(GTKDOC_CHECK)
endif
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
</sect1>
<sect1 id="modernizing-gtk-doc-1-20">
<title>GTK-Doc 1.20</title>
- <para>
- 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.
- </para>
+ <para>Version 1.18 införde inledande stöd för markdown. Att använda markdown i dokumentationskommentarer är mindre påträngande än att skriva docbook xml. Denna version förbättrar detta väsentligt och lägger till många fler stilar. Avsnittet som beskriver <link linkend="documenting_syntax">kommentarsyntax</link> finnas alla detaljer.</para>
</sect1>
<sect1 id="modernizing-gtk-doc-1-25">
<title>GTK-Doc 1.25</title>
- <para>
- 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 any 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><title>Use pre-generated entities</title>
- <programlisting><![CDATA[
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ <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"
"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;.
- 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>
+]>
+<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>
</sect1>
</chapter>
<chapter id="documenting-others">
- <title>Documenting other interfaces</title>
+ <title>Dokumentera andra gränssnitt</title>
- <para>
- 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
- interfaces too.
- </para>
+ <para>Så här långt har vi använt GTK-Doc för att dokumentera API:t för koden. Följande avsnitt innehåller förslag om hur verktyget kan användas för att också dokumentera andra gränssnitt.</para>
<sect1 id="commandline-interfaces">
- <title>Command line options and man pages</title>
+ <title>Kommandoradsflaggor och mansidor</title>
- <para>
- 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 the reference and one gets the man-page for free.
- </para>
+ <para>Då man också kan generera mansidor för ett docbook-refentry, låter det som en bra idé att använda det för detta ändamål. På detta sättet kommer gränssnittet att vara en del av referensen och man får mansidan gratis.</para>
<sect2 id="commandline-interfaces-file">
- <title>Document the tool</title>
+ <title>Dokumentera verktyget</title>
- <para>
- Create one refentry file per tool. Following
- <link linkend="settingup_docfiles">our example</link> we would call it
- <filename>meep/docs/reference/meeper/meep.xml</filename>. For the xml
- tags that should be used and can look at generated file in the xml
- subdirectory as well as examples e.g. in glib.
- </para>
+ <para>Skapa en refentry-fil per verktyg. Om du följer <link linkend="settingup_docfiles">vårt exempel</link> borde vi kalla det <filename>meep/docs/reference/meeper/meep.xml</filename>. För xml-taggarna bör detta användas och man kan studera den genererade filen i xml-underkatalogen så väl som exempel i glib.</para>
</sect2>
<sect2 id="commandline-interfaces-configure">
- <title>Adding the extra configure check</title>
+ <title>Lägga till den extra configure-kontrollen</title>
<para>
- <example><title>Extra configure checks</title>
- <programlisting><![CDATA[
+ <example><title>Lägga till extra configure-kontroller</title>
+ <programlisting>
AC_ARG_ENABLE(man,
[AC_HELP_STRING([--enable-man],
- [regenerate man pages from Docbook [default=no]])],enable_man=yes,
+ [omgenerera mansidor från Docbook [standardvärde=no]])],enable_man=yes,
enable_man=no)
AC_PATH_PROG([XSLTPROC], [xsltproc])
AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)
-]]></programlisting>
+</programlisting>
</example>
</para>
</sect2>
<sect2 id="commandline-interfaces-make">
- <title>Adding the extra makefile rules</title>
+ <title>Lägga till de extra makefilsreglerna</title>
<para>
- <example><title>Extra configure checks</title>
- <programlisting><![CDATA[
+ <example><title>Lägga till extra configure-kontroller</title>
+ <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>
</sect1>
<sect1 id="dbus-interfaces">
- <title>DBus interfaces</title>
+ <title>DBus-gränssnitt</title>
- <para>
- (FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html,
-http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)
- </para>
+ <para>(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)</para>
</sect1>
</chapter>
<chapter id="faq">
- <title>Frequently asked questions</title>
+ <title>Frågor och svar</title>
<segmentedlist>
<?dbhtml list-presentation="list"?>
<segtitle>Fråga</segtitle>
<segtitle>Svar</segtitle>
<seglistitem>
- <seg>No class hierarchy.</seg>
- <seg>
- The objects <function>xxx_get_type()</function> function has not been
- entered into the <filename><package>.types</filename> file.
- </seg>
+ <seg>Ingen klasshierarki.</seg>
+ <seg>Objektens <function>xxx_get_type()</function>-funktion har inte matats in i filen <filename><paket>.types</filename>.</seg>
</seglistitem>
<seglistitem>
- <seg>Still no class hierarchy.</seg>
- <seg>
- 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">explanation</ulink>).
- </seg>
+ <seg>Fortfarande ingen klasshierarki.</seg>
+ <seg>Saknat eller fel namn i filen <filename><paket>-sections.txt</filename> (se <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">förklaring</ulink>).</seg>
</seglistitem>
<seglistitem>
- <seg>Damn, I have still no class hierarchy.</seg>
- <seg>
- 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
- subsections).
- </seg>
+ <seg>Förbannat, jag har fortfarande ingen klasshierarki.</seg>
+ <seg>Är objektnamnet (namnet på instansstrukturen, t.ex. <type>GtkWidget</type>) del av det normala avsnittet (stoppa inte detta i underavsnitt så som Standard eller Private).</seg>
</seglistitem>
<seglistitem>
- <seg>No symbol index.</seg>
- <seg>
- Does the <filename><package>-docs.{xml,sgml}</filename> contain a
- index that xi:includes the generated index?
- </seg>
+ <seg>Inget symbolindex.</seg>
+ <seg>Innehåller <filename><paket>-docs.{xml,sgml}</filename> ett index som inkluderar det genererade indexet med xi:include?</seg>
</seglistitem>
<seglistitem>
- <seg>Symbols are not linked to their doc-section.</seg>
- <seg>
- Is the doc-comment using the correct markup (added #,% or ())?
- Check if the gtkdoc-fixxref warns about unresolvable xrefs.
- </seg>
+ <seg>Symboler är inte länkade till deras dokumentationsavsnitt.</seg>
+ <seg>Använder dokumentationskommentaren korrekta taggar (har du lagt till #, % eller ())? Kontrollera om gtkdoc-fixxref varnar om oupplösbara korsreferenser.</seg>
</seglistitem>
<seglistitem>
- <seg>A new class does not appear in the docs.</seg>
- <seg>
- Is the new page xi:included from
- <filename><package>-docs.{xml,sgml}</filename>.
- </seg>
+ <seg>En ny klass dyker inte upp i dokumentationen.</seg>
+ <seg>Är den nya sidan inkluderad med xi:include från <filename><package>-docs.{xml,sgml}</filename>.</seg>
</seglistitem>
<seglistitem>
- <seg>A new symbol does not appear in the docs.</seg>
- <seg>
- Is the doc-comment properly formatted. Check for spelling mistakes in
- the begin of the comment. Check if the gtkdoc-fixxref warns about
- unresolvable xrefs. Check if the symbol is correctly listed in the
- <filename><package>-sections.txt</filename> in a public subsection.
- </seg>
+ <seg>En ny symbol dyker inte upp i dokumentationen.</seg>
+ <seg>Är dokumentationskommentaren korrekt formaterad. Leta efter stavfel i början av kommentaren. Kontrollera om gtkdoc-fixxref varnar om oupplösbara korsreferenser. Kontrollera om symbolen finns korrekt listad i <filename><paket>-sections.txt</filename> i ett publikt avsnitt.</seg>
</seglistitem>
<seglistitem>
- <seg>A type is missing from the class hierarchy.</seg>
- <seg>
- 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
- incidentally marked private it will not be shown.
- </seg>
+ <seg>En typ saknas från klasshierarkin.</seg>
+ <seg>Om typen finns listad i <filename><paket>.hierarchy</filename> men inte i <filename>xml/tree_index.sgml</filename>, dubbelkolla då att typen finns korrekt placerad i <filename><paket>-sections.txt</filename>. Om typinstansen (t.ex. <type>GtkWidget</type>) inte visas eller är markerad privat kommer den inte att visas.</seg>
</seglistitem>
<seglistitem>
- <seg>I get foldoc links for all gobject annotations.</seg>
- <seg>
- Check that <filename>xml/annotation-glossary.xml</filename> is
- xi:included from <filename><package>-docs.{xml,sgml}</filename>.
- </seg>
+ <seg>Jag får foldoc-länkar för alla gobject-noteringar.</seg>
+ <seg>Kontrollera att <filename>xml/annotation-glossary.xml</filename> är inkluderad med xi:include från <filename><package>-docs.{xml,sgml}</filename>.</seg>
</seglistitem>
<!-- gtk-doc warnings: -->
<seglistitem>
- <seg>Parameter described in source code comment block but does not exist</seg>
- <seg>Check if the prototype in the header has different parameter names as in the source.</seg>
+ <seg>Parameter beskriven i kommentarsblock i källkoden men existerar inte</seg>
+ <seg>Kontrollera om prototypen i huvudet har andra parameternamn än i källkoden.</seg>
</seglistitem>
<!-- docbook warnings: -->
<seglistitem>
- <seg>multiple "IDs" for constraint linkend: XYZ</seg>
- <seg>Symbol XYZ appears twice in <filename><package>-sections.txt</filename> file.</seg>
+ <seg>multipla ”ID:n” för begränsat länkslut: XYZ</seg>
+ <seg>Symbolen XYZ förekommer två gånger i filen <filename><paket>-sections.txt</filename>.</seg>
</seglistitem>
<seglistitem>
- <seg>Element typename in namespace '' encountered in para, but no template matches.</seg>
+ <seg>Elementtypnamn i namnrymd ”” påträffat i para, men ingen mall matchar.</seg>
<seg/>
</seglistitem>
</segmentedlist>
</chapter>
<chapter id="contrib">
- <title>Tools related to 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>
- Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since
- tags in the API to determine the minimum required version.
- </para>
+ <title>Verktyg relaterade till gtk-doc</title>
+
+ <para>GtkDocPlugin - en insticksmodul för <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink>-integrering som lägger till API-dokumentation till en trac-webbplats och integrerar med trac-sökningen.</para>
+ <para>Gtkdoc-depscan - ett verktyg (del av gtk-doc) för att kontrollera använda API mot since-taggar i API:t för att avgöra minsta version som krävs.</para>
</chapter>
<appendix id="fdl">
<appendixinfo>
<releaseinfo>Version 1.1, mars 2000</releaseinfo>
- <copyright>
- <year>2000</year><holder>Free Software Foundation, Inc.</holder>
- </copyright>
+ <copyright><year>2000</year><holder>Free Software Foundation, Inc.</holder></copyright>
<legalnotice id="fdl-legalnotice">
- <para>
- <address>Free Software Foundation, Inc. <street>51 Franklin Street,
+ <para><address>Free Software Foundation, Inc. <street>51 Franklin Street,
Suite 330</street>, <city>Boston</city>, <state>MA</state>
- <postcode>02110-1301</postcode> <country>USA</country></address>
- Everyone is permitted to copy and distribute verbatim copies of this
- license document, but changing it is not allowed.
- </para>
+ <postcode>02110-1301</postcode> <country>USA</country></address>. Alla är tillåtna kopiera och distribuera ordagranna kopior av detta licensdokument, men att ändra det är ej tillåtet.</para>
</legalnotice>
</appendixinfo>
<title>GNU Free Documentation License</title>
<para>Vi har utformat denna licens för att den skall användas för handböcker till fri programvara, eftersom fri programvara behöver fri dokumentation: ett fritt program bör ha en handbok som erbjuder samma friheter som programmet gör. Men denna licens är inte begränsad till programvaruhandböcker; den kan användas för vilket textverk som helst oavsett ämne eller huruvida det är en utgiven, tryckt bok. Vi rekommenderar denna licens huvudsakligen för alla verk vars syfte är instruktion eller referens.</para>
</sect1>
<sect1 id="fdl-section1">
- <title>TILLÄMPNINGSOMRÅDE OCH DEFINITIONER</title>
+ <title>1. TILLÄMPNINGSOMRÅDE OCH DEFINITIONER</title>
<para id="fdl-document">Denna licens [det engelska originalet] gäller för varje handbok eller annat verk, oavsett uttrycksform, som innehåller ett meddelande där upphovsrättsinnehavaren stadgat att verket kan spridas enligt villkoren i GNU Free Documentation License. Ett sådant meddelande ger en internationell frihet utan krav på ersättning och utan tidsbegränsning att använda verket under villkoren i denna licens [det engelska originalet]. <quote>Dokument</quote> nedan syftar på godtycklig handbok eller verk. Var och en är licenstagare och benämns som <quote>du</quote>.</para>
<para id="fdl-modified">En <quote>förändrad version</quote> av dokumentet avser varje verk som innehåller dokumentet eller en del av det, antingen ordagranna kopior, eller med ändringar och/eller översatt till ett annat språk.</para>
<para id="fdl-cover-texts"><quote>Omslagstexterna</quote> är speciella korta ordföljder som är listade som framsidestexter eller baksidestexter i meddelandet som stadgar att <link linkend="fdl-document">dokumentet</link> är utgivet under denna licens [det engelska originalet].</para>
- <para id="fdl-transparent">En <quote>transparent</quote> kopia av <link linkend="fdl-document">dokumentet</link> är en maskinläsbar kopia, representerad i ett format vars specifikation finns tillgänglig för allmänheten, som lämpar sig för att revidera dokumentet på ett enkelt sätt med generella textredigeringsprogram eller (för pixelbaserade bilder) generella grafikprogram eller (för ritningar) något väl tillgängligt ritprogram, och som är passande som indata till textfomaterare eller för automatisk konvertering till en mängd format som passar som indata till textformaterare. En kopia i ett för övrigt transparent filformat vars markeringar, eller avsaknad av markeringar, har ordnats för att hindra eller motverka att vidare förändring vidtas av läsare är inte transparent. Ett bildformat är inte transparent om det används för någon betydande del text. En kopia som inte är <quote>transparent</quote> kallas <quote>opak</quote>.</para>
+ <para id="fdl-transparent">En <quote>transparent</quote> kopia av <link linkend="fdl-document">dokumentet</link> är en maskinläsbar kopia, representerad i ett format vars specifikation finns tillgänglig för allmänheten, som lämpar sig för att revidera dokumentet på ett enkelt sätt med generella textredigeringsprogram eller (för pixelbaserade bilder) generella grafikprogram eller (för ritningar) något väl tillgängligt ritprogram, och som är passande som indata till textformaterare eller för automatisk konvertering till en mängd format som passar som indata till textformaterare. En kopia i ett för övrigt transparent filformat vars markeringar, eller avsaknad av markeringar, har ordnats för att hindra eller motverka att vidare förändring vidtas av läsare är inte transparent. En kopia som inte är <quote>transparent</quote> kallas <quote>opak</quote>.</para>
- <para>Exempel på passande format för transparenta kopior innefattar ren ASCII utan markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript eller PDF utformat för mänsklig förändring. Exempel på transparenta bildformat innefattar PNG, XCF och JPG. Opaka format innefattar leverantörsspecifika format som bara kan läsas och editeras med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/eller verktyg för behandling inte finns allmänt tillgängliga, och den maskingenererade HTML, PostScript eller PDF som produceras av vissa ordbehandlare enbart avsett som utdata.</para>
+ <para>Exempel på passande format för transparenta kopior innefattar ren ASCII utan markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript eller PDF utformat för mänsklig förändring. Opaka format innefattar Postscript, PDF, leverantörsspecifika format som bara kan läsas och editeras med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/eller verktyg för behandling inte finns allmänt tillgängliga, och den maskingenererade HTML som produceras av vissa ordbehandlare enbart avsett som utdata.</para>
<para id="fdl-title-page"><quote>Titelsidan</quote> innebär, för en tryckt bok, titelsidan själv, och sådana därpå följande sidor som krävs för att göra det material som enligt denna licens skall synas på titelsidan läsbart. För verk i sådana format som inte har någon egentlig titelsida, avses med <quote>titelsida</quote> den text som är närmast den mest framstående förekomsten av verkets titel, föregående den huvudsakliga textmassan.</para>
</sect1>
<para>Om de obligatoriska texterna för något omslag är för omfattande för att rymmas i läsbart skick skall du placera de första (så många som får plats) på det egentliga omslaget, och fortsätta med resten på de direkt intilliggande sidorna.</para>
- <para>Om du publicerar <link linkend="fdl-transparent">opaka</link> kopior av <link linkend="fdl-document">dokumentet</link> i upplagor om mer än 100, måste du antingen bifoga en maskinläsbar <link linkend="fdl-transparent">transparent</link> kopia med varje opak kopia, eller ange i eller med varje opak kopia en nätverksadress som är tillgänglig för den allmänna nätverksanvändande massan där man, med öppet standardiserade protokoll, kan ladda ner en komplett transparent kopia av dokumentet, utan extra material. Om du väljer det senare alternativet, måste du vidta skäliga åtgärder, när du börjar sprida opaka kopior i kvantitet, för att denna transparenta kopia skall förbli tillgänglig på angivna platsen till åtminstone ett år efter den sista gången du spred en opak kopia (direkt eller via ombud eller återförsäljare) av den utgåvan till allmänheten.</para>
+ <para>Om du publicerar <link linkend="fdl-transparent">opaka</link> kopior av <link linkend="fdl-document">dokumentet</link> i upplagor om mer än 100, måste du antingen bifoga en maskinläsbar <link linkend="fdl-transparent">transparent</link> kopia med varje opak kopia, eller ange i eller med varje opak kopia en nätverksadress som är tillgänglig för den allmänna nätverksanvändande massan där man, med öppet standardiserade protokoll, anonymt och utan kostnad kan ladda ner en komplett transparent kopia av dokumentet, utan extra material. Om du väljer det senare alternativet, måste du vidta skäliga åtgärder, när du börjar sprida opaka kopior i kvantitet, för att denna transparenta kopia skall förbli tillgänglig på angivna platsen till åtminstone ett år efter den sista gången du spred en opak kopia (direkt eller via ombud eller återförsäljare) av den utgåvan till allmänheten.</para>
<para>Det är önskvärt, men inte ett krav, att du kontaktar författarna till <link linkend="fdl-document">dokumentet</link> i god tid innan du sprider något större antal kopior, för att ge dem en chans att förse dig med en uppdaterad version av dokumentet.</para>
</sect1>
<listitem>
<formalpara>
<title>I</title>
- <para>
- Preserve the section entitled <quote>History</quote>, and
- its title, and add to it an item stating at least the
- title, year, new authors, and publisher of the <link linkend="fdl-modified">Modified Version</link> as given on
- the <link linkend="fdl-title-page">Title Page</link>. If
- there is no section entitled <quote>History</quote> in the
- <link linkend="fdl-document">Document</link>, create one
- stating the title, year, authors, and publisher of the
- Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- </para>
+ <para>Bevara avsnittet med titeln <quote>historik</quote> (History), bevara dess titel och lägg i avsnittet till en post med åtminstone titeln, året, nya författare och utgivaren av den <link linkend="fdl-modified">förändrade versionen</link> så som angivet på <link linkend="fdl-title-page">titelsidan</link>. Om det inte finns något avsnitt med titeln <quote>historik</quote> (History) i <link linkend="fdl-document">dokumentet</link> så skapa en med titeln, året, författare och utgivaren av dokumentet så som det står på [original]dokumentets titelsida. Lägg sedan till en post som beskriver den förändrade versionen så som beskrivits ovan.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>K</title>
- <para>För alla avsnitt med titlarna <quote>tillkännagivanden</quote> (Acknowledgements) eller <quote>dedikationer</quote> (Dedications), bevara titeln på avsnittet, och bevara allt innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda av varje bidragare.</para>
+ <para>För alla avsnitt med titlarna <quote>tillkännagivanden</quote> (Acknowledgements) eller <quote>dedikationer</quote> (Dedications), bevara titeln på avsnittet, och bevara allt innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda av varje bidragsgivare.</para>
</formalpara>
</listitem>
<para>Du äger lägga till ett avsnitt med titeln <quote>endossering</quote> (Endorsements), förutsatt att det inte innehåller något annat än endosseringar för din <link linkend="fdl-modified">förändrade version</link> från olika aktörer -- till exempel, meddelanden om utförd korrekturläsning eller att texten har godkänts av en organisation som en officiell definition av en standard.</para>
- <para>Du äger lägga till ett textavsnitt på upp till fem ord som <link linkend="fdl-cover-texts">framsidestext</link>, och ett textavsnitt på upp till 25 ord som baksidestext i listan över <link linkend="fdl-cover-texts">omslagstexter</link> i den <link linkend="fdl-modified">förändrade versionen</link>. Bara ett textavsnitt med framsidestexter och ett med baksidestexter får läggas till av (eller genom försorg av) en enda juridisk person. Om <link linkend="fdl-document">dokumentet</link> redan innehåller en omlagstext för något av omslagen, tidigare tillagd av dig eller genom försorg av samma juridiska person som du företräder, äger du inte lägga till en till, men du äger ändra den gamla med tillstånd från den tidigare utgivaren som lade till den förra.</para>
+ <para>Du äger lägga till ett textavsnitt på upp till fem ord som <link linkend="fdl-cover-texts">framsidestext</link>, och ett textavsnitt på upp till 25 ord som <link linkend="fdl-cover-texts">baksidestext</link> i listan över <link linkend="fdl-cover-texts">omslagstexter</link> i den <link linkend="fdl-modified">förändrade versionen</link>. Bara ett textavsnitt med framsidestexter och ett med baksidestexter får läggas till av (eller genom försorg av) en enda juridisk person. Om <link linkend="fdl-document">dokumentet</link> redan innehåller en omslagstext för något av omslagen, tidigare tillagd av dig eller genom försorg av samma juridiska person som du företräder, äger du inte lägga till en till, men du äger ändra den gamla med tillstånd från den tidigare utgivaren som lade till den förra.</para>
<para>Författaren (författarna) och utgivaren (utgivarna) av <link linkend="fdl-document">dokumentet</link> ger inte via denna licens sitt tillstånd att använda sina namn för publicitet eller för att lägga till eller antyda endossering av någon <link linkend="fdl-modified">förändrad version</link>.</para>
</sect1>
<title>6. SAMLINGAR AV DOKUMENT</title>
<para>Du äger skapa en samling bestående av <link linkend="fdl-document">dokumentet</link> och andra dokument som är släppta under GNU Free Documentation License, och ersätta individuella kopior i dokumenten av denna licens med en enda kopia [av den engelska originalversionen] som inkluderas i samlingen, förutsatt att du följer villkoren för ordagrann kopiering i denna licens för varje inkluderat dokument i alla andra avseenden.</para>
- <para>
- 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.
- </para>
+ <para>Du äger lyfta ut ett dokument från en sådan samling, och sprida det enskilt under GNU Free Documentation License, förutsatt att du lägger till en kopia av denna licens [den engelska originalversionen] i det utlyfta dokumentet, och följer villkoren för ordagrann kopiering i denna licens för det utlyfta dokumentet i alla andra avseenden.</para>
</sect1>
<sect1 id="fdl-section7">
<title>7. SAMMANSLAGNING MED OBEROENDE VERK</title>
- <para>En samling av <link linkend="fdl-document">dokumentet</link> eller av dess derivat med andra separata och oberoende dokument eller verk, på eller i en lagringsvolym eller ett spridningsmedium, kallas för en <quote>sammanslagning</quote> om den sammanslagna upphovsrätten inte används för att begränsa samlingens användares rättigheter som de enskilda dokumenten medger. När dokumentet ingår i en sådan sammanslagning, gäller inte denna licens de andra verken i samlingen som inte själva är deriverat av dokumentet. Om kravet på <link linkend="fdl-cover-texts">omslagstexter</link> enligt <link linkend="fdl-section3">paragraf 3</link> är tillämpligt på dessa kopior av dokumentet, så kan dokumentets omslagstexter, om dokumentet utgör mindre än hälften av hela samlingen, placeras på det omslag som omger dokumentet inuti samlingen, eller den elektroniska motsvarigheten till omslag om dokumentet är i elektronisk form. Annars måste de synas på det omslag som omger hela samlingen.</para>
+ <para>En samling av <link linkend="fdl-document">dokumentet</link> eller av dess derivat med andra separata och oberoende dokument eller verk, på eller i en lagringsvolym eller ett spridningsmedium, kallas för en <quote>sammanslagning</quote> om den sammanslagna upphovsrätten inte används för att begränsa samlingens användares rättigheter som de enskilda dokumenten medger. När dokumentet ingår i en sådan sammanslagning, gäller inte denna licens de andra verken i samlingen som inte själva är deriverat av dokumentet. Om kravet på <link linkend="fdl-cover-texts">omslagstexter</link> enligt <link linkend="fdl-section3">paragraf 3</link> är tillämpligt på dessa kopior av dokumentet, så kan dokumentets omslagstexter, om dokumentet utgör mindre än en fjärdedel av hela samlingen, placeras på det omslag som omger dokumentet inuti samlingen, eller den elektroniska motsvarigheten till omslag om dokumentet är i elektronisk form. Annars måste de synas på det omslag som omger hela samlingen.</para>
</sect1>
<sect1 id="fdl-section8">
<para>För att använda GNU Free Documentation License för ett dokument du har skrivit, inkludera en kopia av licensen [det engelska originalet] i dokumentet och placera följande copyrightklausul omedelbart efter titelsidan:</para>
<blockquote>
- <para>Copyright (c) ÅRTAL DITT NAMN.</para>
+ <para>Copyright © YEAR YOUR NAME.</para>
<para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the <link linkend="fdl-invariant">Invariant Sections</link> being LIST THEIR TITLES, with the <link linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST, and with the <link linkend="fdl-cover-texts">Back-Cover Texts</link> being LIST. A copy of the license is included in the section entitled <quote>GNU Free Documentation License</quote>.</para>
</blockquote>
- <para>Om du inte har några <link linkend="fdl-invariant">oföränderliga avsnitt</link>, skriv <quote>utan oföränderliga avsnitt</quote> istället för att ange vilka som är oföränderliga. Om du inte har några <link linkend="fdl-cover-texts">framsidestexter</link>, skriv <quote>utan framsidestexter</quote> istället för <quote>framsidestexter som LISTAS</quote>; såväl som för <link linkend="fdl-cover-texts">baksidestexter</link>.</para>
+ <para>Om du inte har några <link linkend="fdl-invariant">oföränderliga avsnitt</link>, skriv <quote>with no Invariant Sections</quote> istället för att ange vilka som är oföränderliga. Om du inte har några <link linkend="fdl-cover-texts">framsidestexter</link>, skriv <quote>no Front-Cover Texts</quote> istället för <quote>Front-Cover Texts being LIST</quote>; såväl som för <link linkend="fdl-cover-texts">baksidestexter</link>.</para>
<para>Om ditt dokument innehåller icke-triviala exempel med programkod, så rekommenderar vi att du släpper dessa exempel parallellt under en, av dig vald, fri programvarulicens, som till exempel <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html">GNU General Public License</ulink>, för att möjliggöra deras användning i fri programvara.</para>
</sect1>
# Swedish translation of gtk-doc.
-# Copyright (C) 2009 Free Software Foundation, Inc.
+# Copyright © 2009-2017 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.
#
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc master\n"
-"POT-Creation-Date: 2009-07-07 22:07+0000\n"
-"PO-Revision-Date: 2009-07-09 12:31+0100\n"
-"Last-Translator: Daniel Nylander <po@danielnylander.se>\n"
+"POT-Creation-Date: 2017-04-23 16:21+0000\n"
+"PO-Revision-Date: 2017-04-28 23:38+0200\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 1.8.11\n"
-#: C/gtk-doc-manual.xml:12(title)
+#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
+msgctxt "_"
+msgid "translator-credits"
+msgstr ""
+"Sebastian Rasmussen <sebras@gmail.com>, 2016\n"
+"Daniel Nylander <po@danielnylander.se>, 2009\n"
+"Marcus Rejås och Alexander Nordström <info@se.linux.org>, 2004\n"
+"\n"
+"Skicka kommentarer om översättningen\n"
+"till svenska till <tp-sv@listor.tp-sv.se>"
+
+#. (itstool) path: bookinfo/title
+#: C/index.docbook:12
msgid "GTK-Doc Manual"
msgstr "Handbok för GTK-Doc"
-#: C/gtk-doc-manual.xml:13(edition)
-msgid "1.12"
-msgstr "1.12"
+#. (itstool) path: bookinfo/edition
+#: C/index.docbook:13
+msgid "1.24.1"
+msgstr "1.24.1"
-#: C/gtk-doc-manual.xml:14(para)
+#. (itstool) path: abstract/para
+#: C/index.docbook:14
msgid "User manual for developers with instructions of GTK-Doc usage."
-msgstr "Användarhandbok för utvecklare med användningsinstruktioner för GTK-Doc."
-
-#: C/gtk-doc-manual.xml:17(firstname)
-msgid "Chris"
-msgstr "Chris"
-
-#: C/gtk-doc-manual.xml:18(surname)
-msgid "Lyttle"
-msgstr "Lyttle"
-
-#: C/gtk-doc-manual.xml:21(email)
-msgid "chris@wilddev.net"
-msgstr "chris@wilddev.net"
-
-#: C/gtk-doc-manual.xml:26(firstname)
-msgid "Dan"
-msgstr "Dan"
-
-#: C/gtk-doc-manual.xml:27(surname)
-msgid "Mueth"
-msgstr "Mueth"
-
-#: C/gtk-doc-manual.xml:30(email)
-msgid "d-mueth@uchicago.edu"
-msgstr "d-mueth@uchicago.edu"
+msgstr ""
+"Användarhandbok för utvecklare med användningsinstruktioner för GTK-Doc."
-#: C/gtk-doc-manual.xml:35(firstname)
-msgid "Stefan"
-msgstr "Stefan"
+#. (itstool) path: authorgroup/author
+#: C/index.docbook:16
+msgid ""
+"<firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation> "
+"<address> <email>chris@wilddev.net</email> </address> </affiliation>"
+msgstr ""
+"<firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation> "
+"<address> <email>chris@wilddev.net</email> </address> </affiliation>"
-#: C/gtk-doc-manual.xml:36(surname)
-msgid "Kost"
-msgstr "Kost"
+#. (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>"
+msgstr ""
+"<firstname>Dan</firstname> <surname>Mueth</surname> <affiliation> <address> "
+"<email>d-mueth@uchicago.edu</email> </address> </affiliation>"
-#: C/gtk-doc-manual.xml:39(email)
-msgid "ensonic@users.sf.net"
-msgstr "ensonic@users.sf.net"
+#. (itstool) path: authorgroup/author
+#: C/index.docbook:34
+msgid ""
+"<firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> <affiliation> "
+"<address> <email>ensonic@users.sf.net</email> </address> </affiliation>"
+msgstr ""
+"<firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> <affiliation> "
+"<address> <email>ensonic@users.sf.net</email> </address> </affiliation>"
-#: C/gtk-doc-manual.xml:45(publishername)
+#. (itstool) path: publisher/publishername
+#: C/index.docbook:45
msgid "GTK-Doc project"
msgstr "GTK-Doc-projektet"
-#: C/gtk-doc-manual.xml:46(email)
-msgid "gtk-doc-list@gnome.org"
-msgstr "gtk-doc-list@gnome.org"
-
-#: C/gtk-doc-manual.xml:49(year)
-msgid "2000, 2005, 2007-2009"
-msgstr "2000, 2005, 2007-2009"
-
-#: C/gtk-doc-manual.xml:50(holder)
-msgid "Dan Mueth and Chris Lyttle and Stefan Kost"
-msgstr "Dan Mueth, Chris Lyttle och Stefan Kost"
-
-#: C/gtk-doc-manual.xml:61(para)
-msgid "Permission is granted to copy, distribute and/or modify this document under the terms of the <citetitle>GNU Free Documentation License</citetitle>, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is <link linkend=\"fdl\">included</link>."
-msgstr "Tillstånd att kopiera, distribuera och/eller modifiera detta dokument ges under villkoren i <citetitle>GNU Free Documentation License</citetitle>, version 1.1 eller senare, utgivet av Free Software Foundation utan standardavsnitt och omslagstexter. En kopia av licensen finns <link linkend=\"fdl\">inkluderad</link>."
-
-#: C/gtk-doc-manual.xml:69(para)
-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, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps."
-msgstr "Flera namn på produkter och tjänster är registrerade varumärken. I de fall dessa namn förekommer i GNOME-dokumentation - och medlemmarna i GNOME-dokumentationsprojektet är medvetna om dessa varumärken - är de skrivna med versaler eller med inledande versal."
-
-#: C/gtk-doc-manual.xml:80(revnumber)
-msgid "1.11"
-msgstr "1.11"
+#. (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/gtk-doc-manual.xml:81(date)
-msgid "22 March 2008"
-msgstr "22 mars 2008"
+#. (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 and Chris Lyttle</holder>"
-#: C/gtk-doc-manual.xml:82(authorinitials)
-msgid "mal"
-msgstr "mal"
+#. (itstool) path: bookinfo/copyright
+#: C/index.docbook:52
+msgid "<year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder>"
+msgstr "<year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder>"
-#: C/gtk-doc-manual.xml:83(revremark)
-msgid "GNOME doc-utils migration"
+#. (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>, "
+"Version 1.1 or any later version published by the Free Software Foundation "
+"with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A "
+"copy of the license is <link linkend=\"fdl\">included</link>."
+msgstr ""
+"Tillstånd att kopiera, distribuera och/eller modifiera detta dokument ges "
+"under villkoren i <citetitle>GNU Free Documentation License</citetitle>, "
+"version 1.1 eller senare, utgivet av Free Software Foundation utan "
+"standardavsnitt och omslagstexter. En kopia av licensen finns <link linkend="
+"\"fdl\">inkluderad</link>."
+
+#. (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, and those trademarks are made aware to the members of the "
+"GNOME Documentation Project, the names have been printed in caps or initial "
+"caps."
+msgstr ""
+"Flera namn på produkter och tjänster är registrerade varumärken. I de fall "
+"dessa namn förekommer i GNOME-dokumentation - och medlemmarna i GNOME-"
+"dokumentationsprojektet är medvetna om dessa varumärken - är de skrivna med "
+"versaler eller med inledande versal."
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:83
+msgid ""
+"<revnumber>1.25.1</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
+"authorinitials> <revremark>development version</revremark>"
msgstr ""
+"<revnumber>1.25.1</revnumber> <date>21 Mars 2016</date> <authorinitials>ss</"
+"authorinitials> <revremark>utvecklingsversion</revremark>"
-#: C/gtk-doc-manual.xml:92(title)
-msgid "Introduction"
-msgstr "Introduktion"
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:89
+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</"
+"authorinitials> <revremark>programfixar, uppstädning av tester</revremark>"
-#: C/gtk-doc-manual.xml:94(para)
-msgid "This chapter introduces GTK-Doc and gives an overview of what it is and how it is used."
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+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</"
+"authorinitials> <revremark>programfix</revremark>"
-#: C/gtk-doc-manual.xml:100(title)
-msgid "What is GTK-Doc?"
-msgstr "Vad är GTK-Doc?"
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:101
+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</"
+"authorinitials> <revremark>programfix</revremark>"
-#: C/gtk-doc-manual.xml:102(para)
-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 also be used to document application code."
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:107
+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</"
+"authorinitials> <revremark>programfixar, borttagning av föråldrade "
+"funktioner</revremark>"
-#: C/gtk-doc-manual.xml:110(title)
-msgid "How Does GTK-Doc Work?"
-msgstr "Hur fungerar GTK-Doc?"
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:113
+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>programfixar, borttagning av föråldrade "
+"funktioner</revremark>"
-#: C/gtk-doc-manual.xml:112(para)
-msgid "GTK-Doc works by using documentation of functions placed inside the source files in specially-formatted comment blocks, or documentation added to the template files which GTK-Doc uses (though note that GTK-Doc will only document functions that are declared in header files; it won't produce output for static functions)."
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:119
+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</"
+"authorinitials> <revremark>programfixar, stöd för markdown, "
+"stilförbättringar</revremark>"
-#: C/gtk-doc-manual.xml:119(para)
-msgid "GTK-Doc consists of a number of perl scripts, each performing a different step in the process."
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:125
+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>programfixar</revremark>"
-#: C/gtk-doc-manual.xml:124(para)
-msgid "There are 5 main steps in the process:"
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:131
+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>programfixar, uppsnabbningar, stöd för markdown</"
+"revremark>"
-#: C/gtk-doc-manual.xml:131(para)
-msgid "<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)."
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:137
+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</"
+"authorinitials> <revremark>brådskande programfixuppdatering</revremark>"
-#: C/gtk-doc-manual.xml:141(para)
-msgid "<guilabel>Gathering information about the code.</guilabel><application>gtkdoc-scan</application> scans the header files of the code looking for declarations of functions, macros, enums, structs, and unions. It creates the file <filename><module>-decl-list.txt</filename> containg a list of the declarations, placing them into sections according to which header file they are in. On the first run this file is copied to <filename><module>-sections.txt</filename> The author can rearrange the sections, and the order of the declarations within them, to produce the final desired order. The second file it generates is <filename><module>-decl.txt</filename>. This file contains the full declarations found by the scanner. If for some reason one would like some sybols to show up in the docs, where the full declaration cannot be found by th scanner or the declaration should appear differently, one can place enties similar to the ones in <filename><module>-decl.txt</filename> into <filename><module>-overrides.txt</filename>. <application>gtkdoc-scanobj</application> can also be used to dynamically query a library about any GtkObject subclasses it exports. It saves information about each object's position in the class hierarchy and about any GTK Args and Signals it provides."
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:143
+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</"
+"authorinitials> <revremark>programfixar, layoutförbättringar</revremark>"
-#: C/gtk-doc-manual.xml:166(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.)"
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:149
+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</"
+"authorinitials> <revremark>program- och regressionsfixar</revremark>"
-#: C/gtk-doc-manual.xml:175(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 <command>--flavour no-tmpl</command> option that chooses a makefile that skips tmpl usage totally. If you have never changed file in tmpl by hand, please remove the dir once."
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:155
+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</"
+"authorinitials> <revremark>programfixar och prestandaförbättringar</"
+"revremark>"
-#: C/gtk-doc-manual.xml:185(para)
-msgid "<guilabel>Generating the SGML/XML and HTML.</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 takes docs from sources and introspection data. <application>gtkdoc-mkhtml</application> turns the SGML files into HTML files in the <filename class=\"directory\">html/</filename> subdirectory. 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."
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:161
+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> "
+"<authorinitials>sk</authorinitials> <revremark>uppdatering på grund av "
+"trasigt tar-arkiv</revremark>"
-#: C/gtk-doc-manual.xml:205(para)
-msgid "<guilabel>Fixing up cross-references between documents.</guilabel> After installing the HTML files, <application>gtkdoc-fixxref</application> can be run to fix up any cross-references between separate documents. For example, the GTK+ documentation contains many cross-references to types documented in the GLib manual. When creating the source tarball for distribution, <application>gtkdoc-rebase</application> turns all external links into web-links. When installing distributed (pregenerated) docs the same application will try to turn links back to local links (where those docs are installed)."
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:167
+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> "
+"<authorinitials>sk</authorinitials> <revremark>nya verktygsfunktioner och "
+"programfixar</revremark>"
-#: C/gtk-doc-manual.xml:223(title)
-msgid "Getting GTK-Doc"
-msgstr "Hämta GTK-Doc"
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:173
+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> "
+"<authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</"
+"revremark>"
-#: C/gtk-doc-manual.xml:226(title)
-msgid "Requirements"
-msgstr "Krav"
+#. (itstool) path: chapter/title
+#: C/index.docbook:186
+msgid "Introduction"
+msgstr "Introduktion"
-#: C/gtk-doc-manual.xml:227(para)
-msgid "<guilabel>Perl v5</guilabel> - the main scripts are in Perl."
+#. (itstool) path: chapter/para
+#: C/index.docbook:188
+msgid ""
+"This chapter introduces GTK-Doc and gives an overview of what it is and how "
+"it is used."
msgstr ""
+"Detta kapitel introducerar GTK-Doc och ger en överblick över vad det är och "
+"hur det används."
-#: C/gtk-doc-manual.xml:230(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 ""
+#. (itstool) path: sect1/title
+#: C/index.docbook:194
+msgid "What is GTK-Doc?"
+msgstr "Vad är GTK-Doc?"
-#: C/gtk-doc-manual.xml:234(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>"
+#. (itstool) path: sect1/para
+#: C/index.docbook:196
+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 "
+"also be used to document application code."
msgstr ""
+"GTK-Doc används för att dokumentera C-kod. Det används vanligen för att "
+"dokumentera det publika API:t för bibliotek, så som GTK+- och GNOME-"
+"biblioteken. Men det kan också användas för att dokumentera programkod."
-#: C/gtk-doc-manual.xml:238(para)
-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 ""
+#. (itstool) path: sect1/title
+#: C/index.docbook:204
+msgid "How Does GTK-Doc Work?"
+msgstr "Hur fungerar GTK-Doc?"
-#: C/gtk-doc-manual.xml:247(para)
-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."
+# sebras: how do I translate header files?
+#. (itstool) path: sect1/para
+#: C/index.docbook:206
+msgid ""
+"GTK-Doc works by using documentation of functions placed inside the source "
+"files in specially-formatted comment blocks, or documentation added to the "
+"template files which GTK-Doc uses (though note that GTK-Doc will only "
+"document functions that are declared in header files; it won't produce "
+"output for static functions)."
+msgstr ""
+"GTK-Doc fungerar så att det använder dokumentation för funktioner placerad "
+"inuti källkodsfilerna i speciellt formaterade kommentarsblock, eller "
+"dokumentation som lagts till i mallfilerna som GTK-Doc använder (notera dock "
+"att GTK-Doc endast kommer att dokumentera funktioner som deklarerats i "
+"huvudfiler; det kommer inte att producera utdata för statiska funktioner)."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:213
+msgid ""
+"GTK-Doc consists of a number of perl scripts, each performing a different "
+"step in the process."
msgstr ""
+"GTK-Doc består av ett antal perl-skript som vart och ett utför olika steg i "
+"processen."
-#: C/gtk-doc-manual.xml:258(title)
-msgid "Installation"
-msgstr "Installation"
+#. (itstool) path: sect1/para
+#: C/index.docbook:218
+msgid "There are 5 main steps in the process:"
+msgstr "Det finns 5 huvudsteg i processen:"
-#: C/gtk-doc-manual.xml:259(para)
-msgid "There is no standard place where the DocBook Modular Stylesheets are installed."
+#. (itstool) path: listitem/para
+#: C/index.docbook:225
+msgid ""
+"<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)."
+msgstr ""
+"<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)."
+
+# sebras: more header files...
+#. (itstool) path: listitem/para
+#: C/index.docbook:235
+msgid ""
+"<guilabel>Gathering information about the code.</guilabel> "
+"<application>gtkdoc-scan</application> scans the header files of the code "
+"looking for declarations of functions, macros, enums, structs, and unions. "
+"It creates the file <filename><module>-decl-list.txt</filename> "
+"containing a list of the declarations, placing them into sections according "
+"to which header file they are in. On the first run this file is copied to "
+"<filename><module>-sections.txt</filename>. The author can rearrange "
+"the sections, and the order of the declarations within them, to produce the "
+"final desired order. The second file it generates is <filename><"
+"module>-decl.txt</filename>. This file contains the full declarations "
+"found by the scanner. If for some reason one would like some symbols to show "
+"up in the docs, where the full declaration cannot be found by the scanner or "
+"the declaration should appear differently, one can place entities similar to "
+"the ones in <filename><module>-decl.txt</filename> into <filename><"
+"module>-overrides.txt</filename>."
+msgstr ""
+"<guilabel>Samla ihop information om koden.</guilabel> <application>gtkdoc-"
+"scan</application> söker genom huvudfilerna för koden och letar efter "
+"deklarationer av funktioner, makron, uppräkningar, strukturer och unioner. "
+"Det skapar sedan filen <filename><module>-decl-list.txt</filename> som "
+"innehåller en lista över deklarationerna, och placerar dem i avsnitt efter "
+"vilken huvudfil de finns i. Vid första körningen kommer denna fil att "
+"kopieras till <filename><module>-sections.txt</filename>. Författaren "
+"kan, genom att omarrangera avsnitten och ändra ordningen för deklarationerna "
+"inom dem, framställa den önskade, slutgiltiga ordningen. Den andra filen det "
+"genererar är <filename><module>-decl.txt</filename>. Denna fil "
+"innehåller de fullständiga deklarationerna som hittats av detektorn. Om man "
+"av något skäl vill att vissa symboler ska visas i dokumentation då den "
+"fullständiga deklarationen inte kan hittas av detektorn, eller om "
+"deklarationen ska visas annorlunda, kan man placera rader liknande de som "
+"finns i <filename><module>-decl.txt</filename> i <filename><"
+"module>-overrides.txt</filename>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:252
+msgid ""
+"<application>gtkdoc-scangobj</application> can also be used to dynamically "
+"query a library about any GObject subclasses it exports. It saves "
+"information about each object's position in the class hierarchy and about "
+"any GObject properties and signals it provides."
+msgstr ""
+"<application>gtkdoc-scangobj</application> kan också användas för att "
+"dynamiskt fråga ett bibliotek om vilka GObject-underklasser det exporterar. "
+"Det sparar information om varje objekts position i klasshierarkin och om "
+"vilka GObject-egenskaper och signaler det tillhandahåller."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:258
+msgid ""
+"<application>gtkdoc-scanobj</application> should not be used anymore. It was "
+"needed in the past when GObject was still GtkObject inside gtk+."
msgstr ""
+"<application>gtkdoc-scanobj</application> bör inte användas längre. Det "
+"behövdes tidigare när GObject fortfarande var GtkObject inuti gtk+."
-#: C/gtk-doc-manual.xml:262(para)
-msgid "gtk-doc's configure script searches these 3 directories automatically:"
+#. (itstool) path: listitem/para
+#: C/index.docbook:265
+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."
+msgstr ""
+"<guilabel>Generera XML och HTML/PDF.</guilabel> <application>gtkdoc-mkdb</"
+"application> förvandlar mallfilerna till XML-filer i underkatalogen "
+"<filename class=\"directory\">xml/</filename>. Om källkoden innehåller "
+"dokumentation över funktioner i speciella kommentarsblock, så kommer denna "
+"att sammanfogas här. Om det inte finns några tmpl-filer som används så "
+"kommer det endast att läsa dokumentation från källkoden och "
+"introspektionsdata."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:274
+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> förvandlar XML-filer till HTML-"
+"filer i underkatalogen <filename class=\"directory\">html/</filename>. På "
+"samma sätt förvandlar <application>gtkdoc-mkpdf</application> XML-filerna "
+"till ett PDF-dokument kallat <filename><package>.pdf</filename>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:280
+msgid ""
+"Files in <filename class=\"directory\">xml/</filename> and <filename class="
+"\"directory\">html/</filename> directories are always overwritten. One "
+"should never edit them directly."
msgstr ""
+"Filer i <filename class=\"directory\">xml/</filename>- och <filename class="
+"\"directory\">html/</filename>-katalogerna skrivs alltid över. Man bör "
+"aldrig redigera dem direkt."
-#: C/gtk-doc-manual.xml:265(para)
-msgid "<filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> (used by RedHat)"
-msgstr ""
+#. (itstool) path: listitem/para
+#: C/index.docbook:288
+msgid ""
+"<guilabel>Fixing up cross-references between documents.</guilabel> After "
+"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
+"run to fix up any cross-references between separate documents. For example, "
+"the GTK+ documentation contains many cross-references to types documented in "
+"the GLib manual. When creating the source tarball for distribution, "
+"<application>gtkdoc-rebase</application> turns all external links into web-"
+"links. When installing distributed (pregenerated) docs the same application "
+"will try to turn links back to local links (where those docs are installed)."
+msgstr ""
+"<guilabel>Fixa korsreferenser mellan dokument.</guilabel> Efter att ha "
+"installerat HTML-filerna kan <application>gtkdoc-fixxref</application> köras "
+"för att fixa korsreferenser mellan separata dokument. Till exempel GTK+-"
+"dokumentationen innehåller många korsreferenser till typer som dokumenterats "
+"i GLib-manualen. När tar-arkivet med källkod skapas för distribution, "
+"förvandlar <application>gtkdoc-rebase</application> alla externa länkar till "
+"webblänkar. När (förgenererad) distribuerad dokumentation installeras kommer "
+"samma program att försöka att förvandla länkarna tillbaka till lokala länkar "
+"(i de fall där dokumentationen finns installerad)."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:306
+msgid "Getting GTK-Doc"
+msgstr "Hämta GTK-Doc"
-#: C/gtk-doc-manual.xml:268(para)
-msgid "<filename> /usr/lib/dsssl/stylesheets/docbook </filename> (used by Debian)"
-msgstr ""
+#. (itstool) path: sect2/title
+#: C/index.docbook:309
+msgid "Requirements"
+msgstr "Krav"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:310
+msgid "<guilabel>Perl v5</guilabel> - the main scripts are in Perl."
+msgstr "<guilabel>Perl v5</guilabel> - huvudskripten är skrivna i Perl."
-#: C/gtk-doc-manual.xml:271(para)
-msgid "<filename> /usr/share/sgml/docbkdsl </filename> (used by SuSE)"
+#. (itstool) path: sect2/para
+#: C/index.docbook:313
+msgid ""
+"<guilabel>xsltproc</guilabel> - the xslt processor from libxslt <ulink url="
+"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
msgstr ""
+"<guilabel>xsltproc</guilabel> - xslt-processorn från libxslt <ulink url="
+"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
-#: C/gtk-doc-manual.xml:274(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>"
+#. (itstool) path: sect2/para
+#: C/index.docbook:317
+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>"
+msgstr ""
+"<guilabel>docbook-xsl</guilabel> - docbook xsl-stilmallar <ulink url="
+"\"http://sourceforge.net/projects/docbook/files/docbook-xsl/\" type=\"http"
+"\">sourceforge.net/projects/docbook/files/docbook-xsl</ulink>"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:321
+msgid "<guilabel>Python</guilabel> - optional - for gtkdoc-depscan"
+msgstr "<guilabel>Python</guilabel> - valfritt - för gtkdoc-depscan"
+
+# sebras: remind me how was highlighting translated..?
+#. (itstool) path: sect2/para
+#: C/index.docbook:324
+msgid ""
+"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
+"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
+"examples"
msgstr ""
+"Endera av <guilabel>source-highlight</guilabel>, <guilabel>highlight</"
+"guilabel> eller <guilabel>vim</guilabel> - valfritt - används för "
+"syntaxfärgning av exempel"
-#: C/gtk-doc-manual.xml:297(title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:332
msgid "About GTK-Doc"
msgstr "Om GTK-Doc"
-#: C/gtk-doc-manual.xml:299(para)
-#: C/gtk-doc-manual.xml:313(para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:334 C/index.docbook:348
msgid "(FIXME)"
-msgstr ""
+msgstr "(FIXME)"
-#: C/gtk-doc-manual.xml:303(para)
-msgid "(History, authors, web pages, license, future plans, comparison with other similar systems.)"
+#. (itstool) path: sect1/para
+#: C/index.docbook:338
+msgid ""
+"(History, authors, web pages, mailing list, license, future plans, "
+"comparison with other similar systems.)"
msgstr ""
+"(Historia, författare, webbsidor, sändlistor, licens, framtida planer, "
+"jämförelse med andra liknande system.)"
-#: C/gtk-doc-manual.xml:311(title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:346
msgid "About this Manual"
msgstr "Om denna handbok"
-#: C/gtk-doc-manual.xml:317(para)
+#. (itstool) path: sect1/para
+#: C/index.docbook:352
msgid "(who it is meant for, where you can get it, license)"
-msgstr ""
+msgstr "(vem är den avsett för, var kan du få tag i den, licens)"
-#: C/gtk-doc-manual.xml:326(title)
+#. (itstool) path: chapter/title
+#: C/index.docbook:361
msgid "Setting up your project"
-msgstr ""
-
-#: C/gtk-doc-manual.xml:328(para)
-msgid "The next sections describe what steps to perform to integrate GTK-Doc into your project. Theses section assume we work on a project called 'meep'. This project contains a library called 'libmeep' and an end-user app called 'meeper'."
-msgstr ""
+msgstr "Att ställa in ditt projekt"
-#: C/gtk-doc-manual.xml:336(title)
+#. (itstool) path: chapter/para
+#: C/index.docbook:363
+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'. "
+"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."
+msgstr ""
+"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."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:374
msgid "Setting up a skeleton documentation"
-msgstr ""
-
-#: C/gtk-doc-manual.xml:338(para)
-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 recommended to create another subdirectory with the name of the doc-package. For packages with just one library this step is not necessary."
-msgstr ""
+msgstr "Att ställa in en skelettstruktur för dokumentation"
-#: C/gtk-doc-manual.xml:347(title)
+#. (itstool) path: sect1/para
+#: C/index.docbook:376
+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 "
+"recommended to create another subdirectory with the name of the doc-package. "
+"For packages with just one library this step is not necessary."
+msgstr ""
+"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."
+
+#. (itstool) path: example/title
+#: C/index.docbook:385
msgid "Example directory structure"
-msgstr ""
-
-#: C/gtk-doc-manual.xml:345(para)
-msgid "This can then look as show below: <placeholder-1/>"
-msgstr ""
+msgstr "Exempel på katalogstruktur"
-#: C/gtk-doc-manual.xml:365(title)
-#: C/gtk-doc-manual.xml:372(title)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:386
+#, no-wrap
+msgid ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/\n"
+" libmeep/\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+msgstr ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/\n"
+" libmeep/\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:383
+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:401 C/index.docbook:408
msgid "Integration with autoconf"
-msgstr ""
-
-#: C/gtk-doc-manual.xml:367(para)
-msgid "Very easy! Just add one line to your <filename>configure.ac</filename> script."
-msgstr ""
+msgstr "Integrering med autoconf"
-#: C/gtk-doc-manual.xml:382(para)
-msgid "Besides checking for the required Gtk-Doc version, this adds two configure switches:"
+#. (itstool) path: sect1/para
+#: C/index.docbook:403
+msgid ""
+"Very easy! Just add one line to your <filename>configure.ac</filename> "
+"script."
msgstr ""
+"Väldigt enkelt! Bara lägg till en rad till ditt <filename>configure.ac</"
+"filename>-skript."
-#: C/gtk-doc-manual.xml:387(para)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:409
+#, no-wrap
+msgid ""
+"\n"
+"# check for gtk-doc\n"
+"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+msgstr ""
+"\n"
+"# check for gtk-doc\n"
+"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+
+#. (itstool) path: example/title
+#: C/index.docbook:421
+msgid "Keep gtk-doc optional"
+msgstr "Låt gtk-doc vara valfritt"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:422
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\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"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:416
+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 "
+"below. Keep it as is, as gtkdocize is looking for <function>GTK_DOC_CHECK</"
+"function> at the start of a line. <_:example-1/>"
+msgstr ""
+"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-1/>"
+
+# sebras: <function> or <symbol>?
+#. (itstool) path: sect1/para
+#: C/index.docbook:433
+msgid ""
+"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:"
+msgstr ""
+"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:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:439
msgid "--with-html-dir=PATH : path to installed docs"
-msgstr ""
+msgstr "--with-html-dir=SÖKVÄG : sökväg till installerad dokumentation"
-#: C/gtk-doc-manual.xml:388(para)
-msgid "--enable-gtk-doc : use gtk-doc to build documentation"
+#. (itstool) path: listitem/para
+#: C/index.docbook:440
+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]"
-#: C/gtk-doc-manual.xml:392(para)
-msgid "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)."
+#. (itstool) path: listitem/para
+#: C/index.docbook:441
+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]"
-#: C/gtk-doc-manual.xml:400(para)
-msgid "Furthermore it is recommended that you have the following line inside you <filename>configure.ac</filename> script. This allows <filename>gtkdocize</filename> to automatically copy the macro definition for <function>GTK_DOC_CHECK</function> to your project."
+#. (itstool) path: listitem/para
+#: C/index.docbook:442
+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]"
-#: C/gtk-doc-manual.xml:408(title)
+#. (itstool) path: important/para
+#: C/index.docbook:446
+msgid ""
+"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)."
+msgstr ""
+"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)."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:454
+msgid ""
+"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."
+msgstr ""
+"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."
+
+#. (itstool) path: example/title
+#: C/index.docbook:462
msgid "Preparation for gtkdocize"
msgstr "Förberedelse för gtkdocize"
-#: C/gtk-doc-manual.xml:419(title)
-msgid "Integration with automake"
-msgstr "Integration med automake"
-
-#: C/gtk-doc-manual.xml:421(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."
-msgstr ""
-
-#: C/gtk-doc-manual.xml:428(para)
-msgid "The next step is to edit the setting 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."
+#. (itstool) path: example/programlisting
+#: C/index.docbook:463
+#, no-wrap
+msgid ""
+"\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
msgstr ""
+"\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
-#. FIXME: explain options ?
-#: C/gtk-doc-manual.xml:439(para)
-msgid "You may also want to enable gtk-doc for the distcheckmake target. Just add then one-liner show in the next example to you top-level <filename>Makefile.am</filename>:"
+#. (itstool) path: sect1/para
+#: C/index.docbook:468
+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 ""
+"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>."
-#: C/gtk-doc-manual.xml:446(title)
-msgid "Enable gtk-doc during make distcheck"
-msgstr ""
+#. (itstool) path: sect1/title
+#: C/index.docbook:476
+msgid "Integration with automake"
+msgstr "Integrering med automake"
-#: C/gtk-doc-manual.xml:458(title)
+#. (itstool) path: sect1/para
+#: C/index.docbook:478
+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 ""
+"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."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:489
+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 "
+"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."
+msgstr ""
+"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."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:503
msgid "Integration with autogen"
-msgstr ""
+msgstr "Integrering med autogen"
-#: C/gtk-doc-manual.xml:460(para)
-msgid "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). Gtk-Doc comes with a tool called <filename>gtkdocize</filename> which can be used in such a script. It should be run before autoheader, automake or autoconf."
-msgstr ""
-
-#: C/gtk-doc-manual.xml:469(title)
+#. (itstool) path: sect1/para
+#: C/index.docbook:505
+msgid ""
+"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."
+msgstr ""
+"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."
+
+#. (itstool) path: example/title
+#: C/index.docbook:514
msgid "Running gtkdocize from autogen.sh"
-msgstr ""
+msgstr "Köra gtkdocize från autogen.sh"
-#: C/gtk-doc-manual.xml:478(para)
-msgid "When running <filename>gtkdocize</filename> it copies <filename>gtk-doc.make</filename> to you project root (or any directory specified by the --docdir option). If also check you configure script for the <function>GTK_DOC_CHECK</function> invocation."
-msgstr ""
-
-#: C/gtk-doc-manual.xml:485(para)
-msgid "Historically gtk-doc was gerating template files where developers entered the docs. this turned out to be not so good. Since a few version gtk-doc could also get all the information from source comments. 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 --flavour=no-tmpl option that chooses a makefile that skips tmpl usage totally. If you have never changed file in tmpl by hand, please remove the dir once."
+#. (itstool) path: example/programlisting
+#: C/index.docbook:515
+#, no-wrap
+msgid ""
+"\n"
+"gtkdocize || exit 1\n"
msgstr ""
+"\n"
+"gtkdocize || exit 1\n"
-#: C/gtk-doc-manual.xml:497(title)
-#: C/gtk-doc-manual.xml:514(title)
+#. (itstool) path: sect1/para
+#: C/index.docbook:521
+msgid ""
+"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>."
+msgstr ""
+"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>."
+
+# 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:530
+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 "
+"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)."
+msgstr ""
+"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)."
+
+#. (itstool) path: sect1/title
+#. (itstool) path: example/title
+#: C/index.docbook:547 C/index.docbook:564
msgid "Running the doc build"
-msgstr ""
-
-#: C/gtk-doc-manual.xml:499(para)
-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 give it the <option>--enable-gtk-doc</option> option. Otherwise manually run <filename>configure</filename> with this option afterwards."
-msgstr ""
+msgstr "Att köra dokumentationsbygget"
-#: C/gtk-doc-manual.xml:506(para)
-msgid "The first make run generates several additional files in the doc-dirs. The important ones are: <filename><package>.types</filename>, <filename><package>-docs.sgml</filename>, <filename><package>-sections.txt</filename>."
+#. (itstool) path: sect1/para
+#: C/index.docbook:549
+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 "
+"give it the <option>--enable-gtk-doc</option> option. Otherwise manually run "
+"<filename>configure</filename> with this option afterwards."
+msgstr ""
+"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."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:556
+msgid ""
+"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>."
+msgstr ""
+"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>."
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:565
+#, no-wrap
+msgid ""
+"\n"
+"./autogen.sh --enable-gtk-doc\n"
+"make\n"
msgstr ""
+"\n"
+"./autogen.sh --enable-gtk-doc\n"
+"make\n"
-#: C/gtk-doc-manual.xml:523(para)
-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, during the next chapter we tell you how to fill the pages with life."
+#. (itstool) path: sect1/para
+#: C/index.docbook:571
+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, "
+"during the next chapter we tell you how to fill the pages with life."
msgstr ""
+"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."
-#: C/gtk-doc-manual.xml:531(title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:579
msgid "Integration with version control systems"
-msgstr ""
+msgstr "Integrering med versionshanteringssystem"
-#: C/gtk-doc-manual.xml:533(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.sgml</filename><filename><package>-sections.txt</filename><filename>Makefile.am</filename>"
+#. (itstool) path: sect1/para
+#: C/index.docbook:581
+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 ""
+"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>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:589
+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 ""
+"Filer i katalogerna <filename>xml/</filename> och <filename>html/</filename> "
+"bör inte versionshanteras. Detsamma gäller <filename>.stamp</filename>-"
+"filerna."
-#: C/gtk-doc-manual.xml:546(title)
-msgid "Documenting the code"
-msgstr ""
+#. (itstool) path: sect1/title
+#: C/index.docbook:597
+msgid "Integration with plain makefiles or other build systems"
+msgstr "Integrering med vanliga makefiler eller andra byggsystem"
-#: C/gtk-doc-manual.xml:548(para)
-msgid "GTK-Doc uses source code comment with a special syntax for code documentation. Further it retrieves information about your project structure from other sources. During the next section you find all information about the syntax of the comments."
+#. (itstool) path: sect1/para
+#: C/index.docbook:599
+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 "
+"in own makefiles (or other build tools)."
+msgstr ""
+"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)."
+
+#. (itstool) path: example/title
+#: C/index.docbook:606
+msgid "Documentation build steps"
+msgstr "Byggsteg för dokumentation"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:607
+#, no-wrap
+msgid ""
+"\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 --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"
+msgstr ""
+"\n"
+"DOC_MODULE=meep\n"
+"// källkod har ändrats\n"
+"gtkdoc-scan --module=$(DOC_MODULE) <källkodskatalog>\n"
+"gtkdoc-scangobj --module=$(DOC_MODULE)\n"
+"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<källkodskatalog>\n"
+"// xml-filer har ändrats\n"
+"mkdir html\n"
+"cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n"
+"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:621
+msgid ""
+"One will need to look at the <filename>Makefile.am</filename> and "
+"<filename>gtk-doc.mak</filename> to pick the extra options needed."
msgstr ""
+"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."
-#: C/gtk-doc-manual.xml:556(title)
-msgid "Documentation placement"
-msgstr ""
+#. (itstool) path: sect1/title
+#: C/index.docbook:628
+msgid "Integration with CMake build systems"
+msgstr "Integrering med CMake-byggsystem"
-#: C/gtk-doc-manual.xml:557(para)
-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 information is often not updated and also that the file tend to cause conflicts with version control systems."
-msgstr ""
+#. (itstool) path: sect1/para
+#: C/index.docbook:630
+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 ""
+"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."
+
+#. (itstool) path: example/title
+#: C/index.docbook:640
+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:641
+#, 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"
+"# Skapa målet doc-libmeep.\n"
+"gtk_doc_add_module(\n"
+" libmeep ${CMAKE_SOURCE_DIR}/libmeep\n"
+" XML meep-docs.xml\n"
+" LIBRARIES libmeep\n"
+")\n"
+"\n"
+"# Bygg doc-libmeep som standardmålet. Utan detta måste du uttryckligen\n"
+"# köra något i stil med `make doc-libmeep` för att bygga dokumentationen.\n"
+"add_custom_target(documentation ALL DEPENDS doc-libmeep)\n"
+"\n"
+"# Installera dokumentationen. (Detta förutsätter att du använder CMake-modulen\n"
+"# GNUInstallDirs för att ställa in variabeln CMAKE_INSTALL_DOCDIR korrekt).\n"
+"install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html\n"
+" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:638
+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:666
+msgid "Documenting the code"
+msgstr "Att dokumentera koden"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:668
+msgid ""
+"GTK-Doc uses source code comment with a special syntax for code "
+"documentation. Further it retrieves information about your project structure "
+"from other sources. During the next section you will find all information "
+"about the syntax of the comments."
+msgstr ""
+"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."
+
+#. (itstool) path: note/title
+#: C/index.docbook:676
+msgid "Documentation placement"
+msgstr "Dokumentationsplacering"
-#: C/gtk-doc-manual.xml:563(para)
-msgid "The avoid the aforementioned problems we suggest putting the documentation inside the sources. This manual will only describe this way of documenting code."
+#. (itstool) path: note/para
+#: C/index.docbook:677
+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 "
+"information is often not updated and also that the file tend to cause "
+"conflicts with version control systems."
+msgstr ""
+"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."
+
+#. (itstool) path: note/para
+#: C/index.docbook:683
+msgid ""
+"The avoid the aforementioned problems we suggest putting the documentation "
+"inside the sources. This manual will only describe this way of documenting "
+"code."
+msgstr ""
+"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."
+
+#. (itstool) path: example/title
+#: C/index.docbook:694 C/index.docbook:720
+msgid "GTK-Doc comment block"
+msgstr "GTK-Doc-kommentarsblock"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:695
+#, no-wrap
+msgid ""
+"\n"
+"#ifndef __GTK_DOC_IGNORE__\n"
+"/* unparseable code here */\n"
+"#endif\n"
+msgstr ""
+"\n"
+"#ifndef __GTK_DOC_IGNORE__\n"
+"/* unparseable code here */\n"
+"#endif\n"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:690
+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/>"
+msgstr ""
+"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-1/>"
+
+#. (itstool) path: note/title
+#: C/index.docbook:704
+msgid "Limitations"
+msgstr "Begränsningar"
+
+# sebras: no 's in the original
+#. (itstool) path: note/para
+#: C/index.docbook:705
+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 ""
+"Notera att GTK-Doc har stöd för <code>#ifndef(__GTK_DOC_IGNORE__)</code> men "
+"inte <code>#if !defined(__GTK_DOC_IGNORE__)</code> eller andra kombinationer."
-#: C/gtk-doc-manual.xml:573(title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:715
msgid "Documentation comments"
-msgstr ""
+msgstr "Dokumentationskommentarer"
-#: C/gtk-doc-manual.xml:578(title)
-msgid "Gtk-Doc comment block"
+#. (itstool) path: example/programlisting
+#: C/index.docbook:721
+#, no-wrap
+msgid ""
+"\n"
+"/**\n"
+" * identifier:\n"
+" * documentation ...\n"
+" */\n"
+msgstr ""
+"\n"
+"/**\n"
+" * identifierare:\n"
+" * dokumentation …\n"
+" */\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:717
+msgid ""
+"A multiline comment that starts with an additional '*' marks a documentation "
+"block that will be processed by the GTK-Doc tools. <_:example-1/>"
msgstr ""
+"En flerradskommentar som börjar med en extra ”*” markerar ett "
+"dokumentationsblock som kommer att hanteras av GTK-Doc-verktygen. <_:"
+"example-1/>"
-#: C/gtk-doc-manual.xml:575(para)
-msgid "A multiline comment that starts with an additional '*' marks a documentation block that will be processed by the Gtk-Doc tools. <placeholder-1/>"
+#. (itstool) path: sect1/para
+#: C/index.docbook:730
+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 "
+"table showing identifiers)"
msgstr ""
+"'Identifierare' är en rad med namnet på det objekt som kommentaren är "
+"relaterad till. Syntaxen skiljer sig lite beroende på objekt. (TODO lägg "
+"till tabell som visar identifierare)"
-#: C/gtk-doc-manual.xml:590(para)
-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 table showing identifiers)"
+#. (itstool) path: sect1/para
+#: C/index.docbook:736
+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)."
+msgstr ""
+"Blocket 'dokumentation' skiljer sig också för varje symboltyp. Symboltyper "
+"som får parametrar så som funktioner eller makron har en "
+"parameterbeskrivning först, åtföljd av en blankrad (bara en ”*”). Efteråt "
+"följer den detaljerade beskrivningen. Alla rader (utanför programlistningar "
+"och CDATA-avsnitt) som endast innehåller ” *” (blanksteg-asterisk) "
+"konverteras till styckeavgränsare. Om du inte vill ha en styckeavgränsare, "
+"ändra till ” * ” (blanksteg-asterisk-blanksteg-blanksteg). Detta är "
+"användbart i förformaterad text (kodlistningar)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:753
+msgid ""
+"What it is: The name for a class or function can sometimes be misleading for "
+"people coming from a different background."
msgstr ""
+"Vad är detta: Namnet på en klass eller en funktion kan ibland vara "
+"vilseledande för personer med annan bakgrund."
-#: C/gtk-doc-manual.xml:596(para)
-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)."
+#. (itstool) path: listitem/para
+#: C/index.docbook:759
+msgid ""
+"What it does: Tell about common uses. Put it in relation with the other API."
msgstr ""
+"Vad gör det: Berättar om vanliga användningsfall. Sätter det i relation med "
+"det andra API:t."
+
+#. (itstool) path: tip/para
+#: C/index.docbook:749
+msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>"
+msgstr "När du dokumenterar kod, beskriv två aspekter: <_:itemizedlist-1/>"
-#: C/gtk-doc-manual.xml:613(para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:774
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."
-#: C/gtk-doc-manual.xml:618(para)
-msgid "Use @param to refer to parameters. Also use this when referring to parameters of other functions, related to the one being described."
+#. (itstool) path: listitem/para
+#: C/index.docbook:779
+msgid ""
+"Use @param to refer to parameters. Also use this when referring to "
+"parameters of other functions, related to the one being described."
msgstr ""
+"Använd @param för att referera till parametrar. Använd också detta när du "
+"refererar till parametrar för andra funktioner, relaterade till den som "
+"beskrivs."
-#: C/gtk-doc-manual.xml:624(para)
+#. (itstool) path: listitem/para
+#: C/index.docbook:785
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."
-#: C/gtk-doc-manual.xml:629(para)
-msgid "Use #symbol to refer to other types of symbol, e.g. structs and enums and macros which don't take arguments."
+#. (itstool) path: listitem/para
+#: C/index.docbook:790
+msgid ""
+"Use #symbol to refer to other types of symbol, e.g. structs and enums and "
+"macros which don't take arguments."
msgstr ""
+"Använd #symbol för att referera till andra typer av symboler, t.ex. "
+"strukturer eller uppräkningar och makron som inte tar argument."
-#: C/gtk-doc-manual.xml:635(para)
-msgid "Use #Object::signal to refer to a GObject signal"
-msgstr ""
+#. (itstool) path: listitem/para
+#: C/index.docbook:796
+msgid "Use #Object::signal to refer to a GObject signal."
+msgstr "Använd #Objekt::signal för att referera till en GObject-signal."
-#: C/gtk-doc-manual.xml:640(para)
-msgid "Use #Object:property to refer to a GObject property"
-msgstr ""
+#. (itstool) path: listitem/para
+#: C/index.docbook:801
+msgid "Use #Object:property to refer to a GObject property."
+msgstr "Använd #Objekt:egenskap för att referera till en GObject-egenskap."
-#: C/gtk-doc-manual.xml:645(para)
-msgid "Use #Struct.field to refer to a field inside a structure."
+#. (itstool) path: listitem/para
+#: C/index.docbook:806
+msgid ""
+"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
+"foo_bar() to refer to a vmethod."
msgstr ""
+"Använd #Struktur.fält för att referera till ett fält inuti en struktur och "
+"#GObjectKlass.foo_bar() för att referera till en virtuell metod."
-#: C/gtk-doc-manual.xml:607(para)
-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. Gtk-Doc comes to help by providing several useful abbreviations. <placeholder-1/>"
+#. (itstool) path: sect1/para
+#: C/index.docbook:768
+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. "
+"GTK-Doc comes to help by providing several useful abbreviations. <_:"
+"itemizedlist-1/>"
+msgstr ""
+"En fördel med hypertext framför vanlig text är möjligheten att ha länkar i "
+"dokumentet. Att skriva korrekta taggar för en länk kan dock vara tröttsamt. "
+"GTK-Doc hjälper då till med att tillhandahålla flera användbara "
+"förkortningar. <_:itemizedlist-1/>"
+
+#. (itstool) path: tip/para
+#: C/index.docbook:815
+msgid ""
+"If you need to use the special characters '<', '>', '()', '@', '%', or "
+"'#' in your documentation without GTK-Doc changing them you can use the XML "
+"entities \"&lt;\", \"&gt;\", \"&lpar;\", \"&rpar;\", \"&"
+"commat;\", \"&percnt;\" and \"&num;\" respectively or escape them "
+"with a backslash '\\'."
+msgstr ""
+"Om du behöver använda specialtecken ”<”, ”>”, ”()”, ”@”, ”%” eller ”#” "
+"i din dokumentation utan att GTK-Doc ändrar dem kan du använda XML-"
+"entiteterna ”&lt;”, ”&gt;”, ”&lpar;”, ”&rpar;”, ”&"
+"commat;”, ”&percnt;” respektive ”&num;” eller använda "
+"kontrollsekvensen ”\\”."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:824
+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 "
+"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 ""
+"DocBook kan mer än bara länkar. Du kan också ha listor, exempel, rubriker "
+"och bilder. Från och med version 1.20, är det föredragna sättet att använda "
+"en delmängd av den grundläggande textformateringssyntaxen som kallas <ulink "
+"url=\"http://daringfireball.net/projects/markdown/\">Markdown</ulink>. Äldre "
+"GTK-Doc-versioner kommer dokumentation som inkluderar markdown att renderas "
+"som den är. Till exempel kommer listobjekt att visas som att de börjar med "
+"ett bindestreck."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:835
+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 ""
+"Då markdown numera föredras kan du blanda båda. En begränsning här är att du "
+"kan använda docbook-xml inuti markdown, men markdown inuti docbook-xml stöds "
+"inte."
-#: C/gtk-doc-manual.xml:653(para)
-msgid "If you need to use the special characters '()', '@', '%', or '#' in your documentation without gtk-doc changing them you can use the XML entities \"&lpar;\", \"&rpar;\", \"&commat;\", \"&percnt;\" and \"&num;\" respectively or escape them with a backslash '\\'."
+#. (itstool) path: sect1/para
+#: C/index.docbook:841
+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 ""
+"I äldre GTK-Doc-versioner var du tvungen, om du ville ha stöd för "
+"ytterligare formatering, att aktivera användningen av docbook-XML-taggar "
+"inuti dok-kommentarer genom att lägga till <option>--xml-mode</option> "
+"(eller <option>--sgml-mode</option>) i variabeln <symbol>MKDB_OPTIONS</"
+"symbol> inuti <filename>Makefile.am</filename>."
+
+# sebras: markdown or Markdown?
+#. (itstool) path: example/title
+#: C/index.docbook:850
+msgid "GTK-Doc comment block using Markdown"
+msgstr "GTK-Doc-kommentarsblock som använder Markdown"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:851
+#, no-wrap
+msgid ""
+"\n"
+"/**\n"
+" * identifier:\n"
+" *\n"
+" * documentation paragraph ...\n"
+" *\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"
+" * 1. numbered list item\n"
+" *\n"
+" * 2. another numbered list item\n"
+" *\n"
+" * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)\n"
+" *\n"
+" * \n"
+" *\n"
+" * [A link to the heading anchor above][heading-two]\n"
+" *\n"
+" * A C-language example:\n"
+" * |[<!-- language=\"C\" -->\n"
+" * GtkWidget *label = gtk_label_new (\"Gorgeous!\");\n"
+" * ]|\n"
+" */\n"
+msgstr ""
+"\n"
+"/**\n"
+" * Identifierare:\n"
+" *\n"
+" * stycke med dokumentation …\n"
+" *\n"
+" * # Underrubrik #\n"
+" *\n"
+" * ## Underunderrubrik\n"
+" *\n"
+" * # Underrubrik med länkankare # {#andra-rubriken}\n"
+" *\n"
+" * mer dokumentation:\n"
+" *\n"
+" * - listobjekt 1\n"
+" *\n"
+" * Stycke inuti listobjekt.\n"
+" *\n"
+" * - listobjekt 2\n"
+" *\n"
+" * 1. numrerat listobjekt\n"
+" *\n"
+" * 2. ytterligare ett numrerat listobjekt\n"
+" *\n"
+" * Ett annat stycke. [En länk till GNOME:s webbplats](http://www.gnome.org/)\n"
+" *\n"
+" * \n"
+" *\n"
+" * [En länk till rubrikankaret ovan][andra-rubriken]\n"
+" *\n"
+" * Ett C-exempel:\n"
+" * |[<!-- language=\"C\" -->\n"
+" * GtkWidget *label = gtk_label_new (\"Vackert!\");\n"
+" * ]|\n"
+" */\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:890
+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+ Documentation Markdown Syntax Reference</ulink>."
msgstr ""
+"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>."
-#: C/gtk-doc-manual.xml:662(para)
-msgid "DocBook can do more that just links. One can also have lists, tables and examples. To enable the usage of SGML/XML tags inside doc-comments you need to have <option>--sgml-mode</option> in the variable <symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</filename>."
-msgstr ""
+#. (itstool) path: tip/para
+#: C/index.docbook:896
+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 "
+"comment those symbols too. This helps other to understand you 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."
+msgstr ""
+"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."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:910
+msgid "Documenting sections"
+msgstr "Dokumentationsavsnitt"
-#: C/gtk-doc-manual.xml:670(para)
-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 comment those symbols too. This helps other to understand you 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."
-msgstr ""
+#. (itstool) path: sect1/para
+#: C/index.docbook:912
+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 "
+"description is also used inside the table of contents. All the @fields are "
+"optional."
+msgstr ""
+"Varje avsnitt av dokumentation innehåller information om en klass eller en "
+"modul. För att introducera komponenten kan man skriva ett avsnittsblock. Den "
+"korta beskrivningen används också i innehållsförteckningen. Alla @fälten är "
+"valfria."
+
+#. (itstool) path: example/title
+#: C/index.docbook:920
+msgid "Section comment block"
+msgstr "Kommentarsblock för avsnitt"
-#: C/gtk-doc-manual.xml:684(title)
-msgid "Documenting sections"
-msgstr ""
+#. (itstool) path: example/programlisting
+#: C/index.docbook:921
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\n"
+"/**\n"
+" * SECTION:meepapp\n"
+" * @short_description: programklassen\n"
+" * @title: Meep-programmet\n"
+" * @section_id:\n"
+" * @see_also: #MeepSettings\n"
+" * @stability: Stable\n"
+" * @include: meep/app.h\n"
+" * @image: application.png\n"
+" *\n"
+" * Programklassen hanterar …\n"
+" */\n"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:940
+msgid "SECTION:<name>"
+msgstr "SECTION:<namn>"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:942
+msgid ""
+"The name links the section documentation to the respective part in the "
+"<filename><package>-sections.txt</filename> file. The name given here "
+"should match the <FILE> tag in the <filename><package>-sections."
+"txt</filename> file."
+msgstr ""
+"Namnet länkar till avsnittsdokumentationen för respektive del i filen "
+"<filename><paket>-sections.txt</filename>. Namnet som anges här bör "
+"matcha taggen <FILE> i filen <filename><paket>-sections.txt</"
+"filename>."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:951
+msgid "@short_description"
+msgstr "@short_description"
-#: C/gtk-doc-manual.xml:686(para)
-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 description is also used inside the table of contents."
+#. (itstool) path: listitem/para
+#: C/index.docbook:953
+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."
msgstr ""
+"En enradsbeskrivning av avsnittet som senare kommer att visas efter länkar i "
+"innehållsförteckningen och lägst upp på avsnittssidan."
-#: C/gtk-doc-manual.xml:693(title)
-msgid "Section comment block"
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:960
+msgid "@title"
+msgstr "@title"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:962
+msgid ""
+"The section title defaults to <name> from the SECTION declaration. It "
+"can be overridden with the @title field."
msgstr ""
+"Avsnittstiteln är som standard <namn> från SECTION-deklarationen. Den "
+"kan åsidosättas med fältet @title."
-#: C/gtk-doc-manual.xml:712(term)
-msgid "@short_description"
-msgstr "@short_description"
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:969
+msgid "@section_id"
+msgstr "@section_id"
-#: C/gtk-doc-manual.xml:714(para)
-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."
+#. (itstool) path: listitem/para
+#: C/index.docbook:971
+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>."
msgstr ""
+"Åsidosätter användningen av titeln som avsnittsidentifierare. För GObjects "
+"används <title> som ett section_id och för andra avsnitt är det <"
+"MODULE>-<title>."
-#: C/gtk-doc-manual.xml:721(term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:979
msgid "@see_also"
msgstr "@see_also"
-#: C/gtk-doc-manual.xml:723(para)
-msgid "A list of symbols that are related to this section.."
-msgstr ""
+#. (itstool) path: listitem/para
+#: C/index.docbook:981
+msgid "A list of symbols that are related to this section."
+msgstr "En lista över symboler som är relaterade till detta avsnitt."
-#: C/gtk-doc-manual.xml:729(term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:987
msgid "@stability"
msgstr "@stability"
-#: C/gtk-doc-manual.xml:736(para)
-msgid "Stable - The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release). Even at a major release, incompatible changes are expected to be rare, and to have strong justifications."
-msgstr ""
-
-#: C/gtk-doc-manual.xml:748(para)
-msgid "Unstable - Unstable interfaces are experimental or transitional. They are typically used to give outside developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated. No claims are made about either source or binary compatibility from one minor release to the next."
-msgstr ""
-
-#: C/gtk-doc-manual.xml:760(para)
-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 specified and documented ways."
+#. (itstool) path: listitem/para
+#: C/index.docbook:994
+msgid ""
+"Stable - The intention of a Stable interface is to enable arbitrary third "
+"parties to develop applications to these interfaces, release them, and have "
+"confidence that they will run on all minor releases of the product (after "
+"the one in which the interface was introduced, and within the same major "
+"release). Even at a major release, incompatible changes are expected to be "
+"rare, and to have strong justifications."
+msgstr ""
+"Stable - Avsikten med ett stabilt gränssnitt är att möjliggöra för tredje "
+"parter att utveckla program mot dessa gränssnitt, släppa dem och vara säkra "
+"på att de kommer att köra på alla programfixversioner av produkten (efter "
+"den i vilken gränssnittet introducerats, och inom samma huvudversion). Även "
+"vid en ny huvudversion förväntas inkompatibla ändringar vara få och vara väl "
+"motiverade."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1006
+msgid ""
+"Unstable - Unstable interfaces are experimental or transitional. They are "
+"typically used to give outside developers early access to new or rapidly "
+"changing technology, or to provide an interim solution to a problem where a "
+"more general solution is anticipated. No claims are made about either source "
+"or binary compatibility from one minor release to the next."
+msgstr ""
+"Unstable - Instabila gränssnitt är experimentella eller i en övergångsfas. "
+"De används typiskt för att ge utomstående utvecklare tidig tillgång till ny "
+"eller snabbt föränderlig teknologi, eller för att tillhandahålla "
+"provisoriska lösningar för ett problem där en mer generell lösning förutses. "
+"Inga påståenden görs om endera källkods- eller binärkompatibilitet från en "
+"programfixversion till nästa."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1018
+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 "
+"specified and documented ways."
msgstr ""
+"Private - Ett gränssnitt som kan användas inom GNOME-stacken i sig, men som "
+"inte dokumenterats för slutanvändare. Sådana funktioner bör endast användas "
+"på angivna och dokumenterade sätt."
-#: C/gtk-doc-manual.xml:769(para)
-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 Internal."
+#. (itstool) path: listitem/para
+#: C/index.docbook:1027
+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 "
+"Internal."
msgstr ""
+"Internal - ett gränssnitt som är internt för en modul och inte behöver "
+"slutanvändardokumentation. Funktioner som är odokumenterade förutsätts vara "
+"interna."
-#: C/gtk-doc-manual.xml:731(para)
-msgid "A informal description of the stability level this API has. We recommend the use of one of these terms: <placeholder-1/>"
+#. (itstool) path: listitem/para
+#: C/index.docbook:989
+msgid ""
+"An informal description of the stability level this API has. We recommend "
+"the use of one of these terms: <_:itemizedlist-1/>"
msgstr ""
+"En informell beskrivning över stabiliteten för detta API. Vi rekommenderar "
+"att använda en av dessa termer: <_:itemizedlist-1/>"
-#: C/gtk-doc-manual.xml:781(term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1039
msgid "@include"
msgstr "@include"
-#: C/gtk-doc-manual.xml:783(para)
-msgid "The <literal>#include</literal> files to show in the section synopsis (a comma separated list), overriding the global value from the <link linkend=\"metafiles_sections\">section file</link> or command line. This item is optional."
-msgstr ""
-
-#: C/gtk-doc-manual.xml:793(para)
-msgid "FIXME having @title here, would put this title into a newly generated section file, but later would be obsolete (right?)"
-msgstr ""
-
-#: C/gtk-doc-manual.xml:800(para)
-msgid "To avoid unnecessary recompilation after doc-changes put the section docs into the c-source where possible."
+#. (itstool) path: listitem/para
+#: C/index.docbook:1041
+msgid ""
+"The <literal>#include</literal> files to show in the section synopsis (a "
+"comma separated list), overriding the global value from the <link linkend="
+"\"metafiles_sections\">section file</link> or command line. This item is "
+"optional."
+msgstr ""
+"<literal>#include</literal>-filerna som ska visas i avsnittssammanfattningen "
+"(en kommaavgränsad lista), vilket åsidosätter det globala värdet från <link "
+"linkend=\"metafiles_sections\">avsnittsfilen</link> eller kommandoraden. "
+"Detta objekt är valfritt."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1050
+msgid "@image"
+msgstr "@image"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1052
+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 "
+"a class or a diagram of its relationship to other classes. This item is "
+"optional."
+msgstr ""
+"Bilden som ska visas längst upp på referenssidan för detta avsnitt. Detta "
+"kommer ofta att vara någon form av diagram för att illustrera det visuella "
+"utseendet för en klass eller ett diagram över dess relationer med andra "
+"klasser. Detta objekt är valfritt."
+
+#. (itstool) path: tip/para
+#: C/index.docbook:1063
+msgid ""
+"To avoid unnecessary recompilation after doc-changes put the section docs "
+"into the c-source where possible."
msgstr ""
+"För att undvika onödig omkompilering efter dokumentationsändringar, placera "
+"avsnittsdokumentationen i c-källkoden där möjligt."
-#: C/gtk-doc-manual.xml:809(title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:1072
msgid "Documenting symbols"
-msgstr ""
+msgstr "Dokumentationssymboler"
-#: C/gtk-doc-manual.xml:811(para)
-msgid "Each symbol (function, macro, struct, enum, signal and property) is documented in a separate block. The block is best placed close to the definition of the symbols so that it is easy to keep them in sync. Thus function are usually documented in the c-source and macros, struct and enum in the header file."
+#. (itstool) path: sect1/para
+#: C/index.docbook:1074
+msgid ""
+"Each symbol (function, macro, struct, enum, signal and property) is "
+"documented in a separate block. The block is best placed close to the "
+"definition of the symbols so that it is easy to keep them in sync. Thus "
+"functions are usually documented in the c-source and macros, structs and "
+"enums in the header file."
+msgstr ""
+"Varje symbol (funktion, makro, struktur, uppräkning, signal och egenskap) är "
+"dokumenterad i ett separat block. Blocket placeras bäst intill definitionen "
+"av symbolerna så att det är enkelt att hålla dem synkroniserade. Därför "
+"dokumenteras funktioner vanligtvis i c-källkoden och makron, strukturer och "
+"uppräkningar i huvudfilen."
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1082 C/index.docbook:1148
+msgid "General tags"
+msgstr "Generella taggar"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1084
+msgid ""
+"You can add versioning information to all documentation elements to tell "
+"when an API was introduced, or when it was deprecated."
msgstr ""
+"Du kan lägga till versioneringsinformation i alla dokumentationselement för "
+"att berätta när ett API introducerats eller blev föråldrat."
-#: C/gtk-doc-manual.xml:820(title)
-msgid "Function comment block"
-msgstr ""
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1089
+msgid "Versioning Tags"
+msgstr "Versioneringstaggar"
-#: C/gtk-doc-manual.xml:843(term)
-msgid "Returns:"
-msgstr ""
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1090
+msgid "Since:"
+msgstr "Since:"
-#: C/gtk-doc-manual.xml:845(para)
-msgid "Paragraph describing the returned result."
+#. (itstool) path: listitem/para
+#: C/index.docbook:1092
+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."
-#: C/gtk-doc-manual.xml:851(term)
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1097
msgid "Deprecated:"
-msgstr ""
+msgstr "Deprecated:"
-#: C/gtk-doc-manual.xml:853(para)
-msgid "Paragraph denoting that this function should no be used anymore. The description should point the reader to the new API."
+#. (itstool) path: listitem/para
+#: C/index.docbook:1099
+msgid ""
+"Paragraph denoting that this function should no be used anymore. The "
+"description should point the reader to the new API."
msgstr ""
+"Stycke som betecknar att denna funktion inte bör användas längre. "
+"Beskrivningen bör peka läsaren vidare till det nya API:t."
-#: C/gtk-doc-manual.xml:860(term)
-msgid "Since:"
+#. (itstool) path: sect2/para
+#: C/index.docbook:1107
+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 ""
+"Du kan också lägga till stabilitetsinformation för alla "
+"dokumentationselement för att indikera huruvida API-stabilitet är garanterad "
+"för dem för alla framtida programfix-versioner av projektet."
-#: C/gtk-doc-manual.xml:862(para)
-msgid "Description since which version of the code the API is available."
+#. (itstool) path: sect2/para
+#: C/index.docbook:1113
+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 ""
+"Standardvärdet för stabilitetsnivån för alla dokumentations element kan "
+"ställas in genom att ange argumentet <option>--default-stability</option> "
+"till <application>gtkdoc-mkdb</application> med endera av värdena nedan."
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1119
+msgid "Stability Tags"
+msgstr "Stabilitetstaggar"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1120
+msgid "Stability: Stable"
+msgstr "Stability: Stable"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1122
+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 ""
+"Markera elementet som stabilt. Detta är för publika API:er som är "
+"garanterade att hållas stabila i alla framtida programfix-versioner av "
+"projektet."
-#: C/gtk-doc-manual.xml:869(para)
-msgid "Gtk-doc assumes all symbols (macros, functions) starting with '_' are private. They are treated like static functions."
-msgstr ""
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1129
+msgid "Stability: Unstable"
+msgstr "Stability: Unstable"
-#: C/gtk-doc-manual.xml:874(para)
-msgid "(FIXME) (stability) (glib-enums, ...)"
+#. (itstool) path: listitem/para
+#: C/index.docbook:1131
+msgid ""
+"Mark the element as unstable. This is for public APIs which are released as "
+"a preview before being stabilised."
msgstr ""
+"Markera elementet som instabilt. Detta är för publika API:er som är släppta "
+"på förhand innan de blivit stabiliserade."
-#: C/gtk-doc-manual.xml:880(title)
-msgid "Property comment block"
-msgstr ""
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1137
+msgid "Stability: Private"
+msgstr "Stability: Private"
-#: C/gtk-doc-manual.xml:892(title)
-msgid "Signal comment block"
+#. (itstool) path: listitem/para
+#: C/index.docbook:1139
+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 ""
+"Markera element som privat. Detta är avsett för gränssnitt som kan användas "
+"av tätt sammankopplade moduler, men inte av godtyckliga tredje parter."
-#: C/gtk-doc-manual.xml:909(title)
-msgid "Struct comment block"
-msgstr ""
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1149
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\n"
+"/**\n"
+" * foo_get_bar:\n"
+" * @foo: någon foo\n"
+" *\n"
+" * Hämtar bar från @foo.\n"
+" *\n"
+" * Returns: bar från @foo\n"
+" *\n"
+" * Since: 2.6\n"
+" * Deprecated: 2.12: Använd foo_baz_get_bar() istället.\n"
+" */\n"
+"Bar *\n"
+"foo_get_bar(Foo *foo)\n"
+"{\n"
+"…\n"
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1169 C/index.docbook:1179
+msgid "Annotations"
+msgstr "Noteringar"
+
+# sebras: was it called verkygstips? verktygshjälp? I forget...
+#. (itstool) path: sect2/para
+#: C/index.docbook:1171
+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 ""
+"Dokumentationsblock kan innehålla noteringstaggar. Dessa taggar kommer att "
+"renderas som verktygstips som beskriver deras syfte. Taggarna används av "
+"gobject-introspection för att generera språkbindningar. En detaljerad lista "
+"över vilka taggar som stöds hittas på <ulink url=\"http://live.gnome.org/"
+"GObjectIntrospection/Annotations\" type=\"http\">wikisidan</ulink>."
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1180
+#, 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 ""
+"\n"
+"/**\n"
+" * foo_get_bar: (notering)\n"
+" * @foo: (notering): någon foo\n"
+" *\n"
+" * Hämtar bar från @foo.\n"
+" *\n"
+" * Returns: (notering): bar från @foo\n"
+" */\n"
+"...\n"
+"/**\n"
+" * foo_set_bar_using_the_frobnicator: (notering) (an annan notering)\n"
+" * (ytterligare en annan notering)\n"
+" * @foo: (notering) (en annan notering): någon foo\n"
+" *\n"
+" * Ställer in bar i @foo.\n"
+" */\n"
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1201 C/index.docbook:1230
+msgid "Function comment block"
+msgstr "Kommentarsblock för funktioner"
-#: C/gtk-doc-manual.xml:928(title)
-msgid "Useful DocBook tags"
+#. (itstool) path: listitem/para
+#: C/index.docbook:1207
+msgid ""
+"Document whether returned objects, lists, strings, etc, should be freed/"
+"unrefed/released."
msgstr ""
+"Dokumentera huruvida returnerade objekt, listor, strängar, etc. bör frigöras/"
+"avrefereras/släppas."
-#: C/gtk-doc-manual.xml:930(para)
-msgid "Here are some DocBook tags which are most useful when documenting the code."
+#. (itstool) path: listitem/para
+#: C/index.docbook:1213
+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."
-#: C/gtk-doc-manual.xml:935(para)
-msgid "To link to another section in the GTK docs: <placeholder-1/> The linkend is the SGML id on the top item of the page you want to link to. For most pages this is currently the part (\"gtk\", \"gdk\", glib\") and then the page title (\"Hash Tables\"). For widgets it is just the class name. Spaces and underscores are converted to '-' to conform to SGML."
-msgstr ""
+#. (itstool) path: listitem/para
+#: C/index.docbook:1218
+msgid ""
+"Mention interesting pre-conditions and post-conditions where appropriate."
+msgstr "Nämn intressanta förvillkor och eftervillkor där lämpligt."
-#: C/gtk-doc-manual.xml:951(para)
-msgid "To refer to an external function, e.g. a standard C function: <placeholder-1/>"
-msgstr ""
+#. (itstool) path: sect2/para
+#: C/index.docbook:1203 C/index.docbook:1289
+msgid "Please remember to: <_:itemizedlist-1/>"
+msgstr "Kom ihåg att: <_:itemizedlist-1/>"
-#: C/gtk-doc-manual.xml:962(para)
+# sebras: Gtk-doc? GTK-Doc? gtk-doc? macros and functions?
+#. (itstool) path: sect2/para
+#: C/index.docbook:1225
msgid ""
-"To include example code: <placeholder-1/> or possibly this, for very short code fragments which don't need a title: <placeholder-2/> For the latter gtk-doc also supports an abbreviation: <![CDATA[\n"
-"|[\n"
-" ...\n"
-"]|\n"
-"]]>"
+"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
+"private. They are treated like static functions."
msgstr ""
+"Gtk-doc förutsätter att alla symboler (makron, funktioner) som börjar med "
+"”_” är privata. De behandlas på samma sätt som statiska funktioner."
-#: C/gtk-doc-manual.xml:996(para)
-msgid "To include bulleted lists: <placeholder-1/>"
-msgstr ""
+# sebras: how to translate highlight?
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1231
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\n"
+"/**\n"
+" * funktionsnamn:\n"
+" * @par1: beskrivning av parameter 1. Dessa kan sträcka sig\n"
+" * över mer än en rad.\n"
+" * @par2: beskrivning av parameter 2\n"
+" * @...: en %NULL-terminerad lista av flera bar\n"
+" *\n"
+" * Funktionsbeskrivningen ska vara här. Du kan använda @par1 för att\n"
+" * referera till parametrar så att de färgmarkeras i utdata. Du kan också\n"
+" * använda %konstant för konstanter, funktionsnamn2() för funktioner och\n"
+" * #GtkWidget för länkar till andra deklarationer (vilka kan vara dokumenterade\n"
+" * på annat håll).\n"
+" *\n"
+" * Returns: ett heltal.\n"
+" *\n"
+" * Since: 2.2\n"
+" * Deprecated: 2.18: Använd annan_funktion() istället.\n"
+" */\n"
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1252
+msgid "Function tags"
+msgstr "Funktions-taggar"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1253 C/index.docbook:1460
+msgid "Returns:"
+msgstr "Returns:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1255
+msgid "Paragraph describing the returned result."
+msgstr "Stycke som beskriver det returnerade resultatet."
-#: C/gtk-doc-manual.xml:1018(para)
-msgid "To include a note which stands out from the text: <placeholder-1/>"
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1260
+msgid "@...:"
+msgstr "@...:"
+
+# sebras: variadic?
+#. (itstool) path: listitem/para
+#: C/index.docbook:1262
+msgid ""
+"In case the function has variadic arguments, you should use this tag "
+"(@Varargs: does also work for historic reasons)."
msgstr ""
+"Om funktionen har variadiska argument bör du använda denna tagg (@Varargs: "
+"fungerar också på grund av historiska skäl)."
-#: C/gtk-doc-manual.xml:1033(para)
-msgid "To refer to a type: <placeholder-1/>"
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1272 C/index.docbook:1274
+msgid "Property comment block"
+msgstr "Kommentarsblock för egenskaper"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1275
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\n"
+"/**\n"
+" * EnKomponent:en-egenskap:\n"
+" *\n"
+" * Här kan du dokumentera en egenskap.\n"
+" */\n"
+"g_object_class_install_property (object_class, PROP_EN_EGENSKAP, …);\n"
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1287 C/index.docbook:1306
+msgid "Signal comment block"
+msgstr "Kommentarsblock för signaler"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1293
+msgid ""
+"Document when the signal is emitted and whether it is emitted before or "
+"after other signals."
msgstr ""
+"Dokumentera när en signal sänds ut och huruvida den sänds ut före eller "
+"efter andra signaler."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1299
+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:1307
+#, 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"
+msgstr ""
+"\n"
+"/**\n"
+" * FooWidget::foobariserad:\n"
+" * @widget: komponenten som erhåller signalen\n"
+" * @foo: någon foo\n"
+" * @bar: någon bar\n"
+" *\n"
+" * Signalen ::foobarized sänds ut varje gång någon försöker att foobarisera @widget.\n"
+" */\n"
+"foo_signals[FOOBARIZE] =\n"
+" g_signal_new (\"foobarisera\",\n"
+" ...\n"
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1324 C/index.docbook:1325
+msgid "Struct comment block"
+msgstr "Kommentarsblock för strukturer"
-#: C/gtk-doc-manual.xml:1044(para)
-msgid "To refer to an external structure (not one described in the GTK docs): <placeholder-1/>"
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1326
+#, no-wrap
+msgid ""
+"\n"
+"/**\n"
+" * FooWidget:\n"
+" * @bar: some #gboolean\n"
+" *\n"
+" * This is the best widget, ever.\n"
+" */\n"
+"typedef struct _FooWidget {\n"
+" GtkWidget parent_instance;\n"
+"\n"
+" gboolean bar;\n"
+"} FooWidget;\n"
+msgstr ""
+"\n"
+"/**\n"
+" * FooWidget:\n"
+" * @bar: någon #gboolean\n"
+" *\n"
+" * Detta är den bästa komponenten någonsin.\n"
+" */\n"
+"typedef struct _FooWidget {\n"
+" GtkWidget parent_instance;\n"
+"\n"
+" gboolean bar;\n"
+"} FooWidget;\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1341
+msgid ""
+"Use <code>/*< private >*/</code> before the private struct fields you "
+"want to hide. Use <code>/*< public >*/</code> for the reverse "
+"behaviour."
msgstr ""
+"Använd<code>/*< private >*/</code> före privata strukturfält som du "
+"vill gömma. Använd <code>/*< public >*/</code> för det omvända "
+"beteendet."
-#: C/gtk-doc-manual.xml:1055(para)
-msgid "To refer to a field of a structure: <placeholder-1/>"
+#. (itstool) path: sect2/para
+#: C/index.docbook:1347
+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 ""
+"Om det första fältet är ”g_iface”, ”parent_instance” eller ”parent_class” "
+"kommer det att anses vara privat automatiskt och behöver inte nämnas i "
+"kommentarsblocket."
-#: C/gtk-doc-manual.xml:1066(para)
-msgid "To refer to a class name, we could possibly use: <placeholder-1/> but you'll probably be using #GtkWidget instead (to automatically create a link to the GtkWidget page - see <link linkend=\"documenting_syntax\">the abbreviations</link>)."
+#. (itstool) path: sect2/para
+#: C/index.docbook:1353
+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 "
+"vmethods (as this is how they can be documented). For the GObject itself one "
+"can use the related section docs, having a separate block for the instance "
+"struct would be useful if the instance has public fields. One disadvantage "
+"here is that this creates two index entries of the same name (the structure "
+"and the section)."
+msgstr ""
+"Kommentarsblock för strukturer kan också användas för GObject och "
+"GObjectClass. Det är vanligtvis en bra idé att lägga till ett "
+"kommentarsblock för en klass om den har virtuella metoder (då detta är "
+"sättet på vilket de kan dokumenteras). För GObject i sig kan man använda den "
+"relaterade avsnittsdokumentationen, och ha ett separat block för varje "
+"instansstruktur vore användbart om instansen har publika fält. En nackdel "
+"här är att det skapar två indexposter med samma namn (strukturen och "
+"avsnittet)."
+
+#. (itstool) path: sect2/title
+#. (itstool) path: example/title
+#: C/index.docbook:1365 C/index.docbook:1366
+msgid "Enum comment block"
+msgstr "Kommentarsblock för uppräkningar"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1367
+#, no-wrap
+msgid ""
+"\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"
+"typedef enum {\n"
+" SOMETHING_FOO,\n"
+" SOMETHING_BAR,\n"
+" /*< private >*/\n"
+" SOMETHING_COUNT\n"
+"} Something;\n"
+msgstr ""
+"\n"
+"/**\n"
+" * Something:\n"
+" * @SOMETHING_FOO: någonting foo\n"
+" * @SOMETHING_BAR: någonting bar\n"
+" *\n"
+" * Uppräkningsvärden som används för saken, för att specificera saken.\n"
+" */\n"
+"typedef enum {\n"
+" SOMETHING_FOO,\n"
+" SOMETHING_BAR,\n"
+" /*< private >*/\n"
+" SOMETHING_COUNT\n"
+"} Something;\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:1384
+msgid ""
+"Use <code>/*< private >*/</code> before the private enum values you "
+"want to hide. Use <code>/*< public >*/</code> for the reverse "
+"behaviour."
+msgstr ""
+"Använd <code>/*< private >*/</code> före privata uppräkningsvärden som "
+"du vill gömma. Använd <code>/*< public >*/</code> för det omvända "
+"beteendet."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1395
+msgid "Inline program documentation"
+msgstr "Infogad programdokumentation"
+
+# sebras: how to translate inline?
+#. (itstool) path: sect1/para
+#: C/index.docbook:1396
+msgid ""
+"You can document programs and their commandline interface using inline "
+"documentation."
+msgstr ""
+"Du kan dokumentera program och deras kommandoradsgränssnitt med infogad "
+"dokumentation."
+
+#. (itstool) path: variablelist/title
+#: C/index.docbook:1402
+msgid "Tags"
+msgstr "Taggar"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1404
+msgid "PROGRAM"
+msgstr "PROGRAM"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1407
+msgid "Defines the start of a program documentation."
+msgstr "Definierar början av programdokumentationen."
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1414
+msgid "@short_description:"
+msgstr "@short_description:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1416
+msgid "Defines a short description of the program. (Optional)"
+msgstr "Definierar en kort beskrivning av programmet. (Valfritt)"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1423
+msgid "@synopsis:"
+msgstr "@synopsis:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1425
+msgid ""
+"Defines the arguments, or list of arguments that the program can take. "
+"(Optional)"
+msgstr ""
+"Definierar argumenten, eller en lista av argument som programmet kan ta. "
+"(Valfritt)"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1433
+msgid "@see_also:"
+msgstr "@see_also:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1435
+msgid "See Also manual page section. (Optional)"
+msgstr "Se vidare i manualavsnitt. (Valfritt)"
+
+#. (itstool) path: varlistentry/term
+#: C/index.docbook:1442
+msgid "@arg:"
+msgstr "@arg:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1444
+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:1451
+msgid "Description:"
+msgstr "Beskrivning:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1453
+msgid "A longer description of the program."
+msgstr "En längre beskrivning av programmet."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:1462
+msgid "Specificy what value(s) the program returns. (Optional)"
+msgstr "Ange vilka värden programmet returnerar. (Valfritt)"
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:1471
+msgid "Example of program documentation."
+msgstr "Exempel på programdokumentation."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1472
+msgid "Program documentation block"
+msgstr "Dokumentationsblock för program"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1473
+#, 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 ""
+"\n"
+"/**\n"
+" * PROGRAM:test-program\n"
+" * @short_description: Ett testprogram\n"
+" * @synopsis: test-program [*FLAGGOR*...] --arg1 *arg* *FIL*\n"
+" * @see_also: test(1)\n"
+" * @--arg1 *arg*: ställ in arg1 på *arg*\n"
+" * @--arg2 *arg*: ställ in arg2 på *arg*\n"
+" * @-v, --version: Skriv ut versionsinformation\n"
+" * @-h, --help: Skriv ut hjälpmeddelandet\n"
+" *\n"
+" * En längre beskrivning av programmet.\n"
+" *\n"
+" * Returns: Noll vid framgång, icke-noll vid fel\n"
+" */\n"
+"int main(int argc, char *argv[])\n"
+"{\n"
+"\treturn 0;\n"
+"}\n"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1499
+msgid "Useful DocBook tags"
+msgstr "Användbara DocBook-taggar"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1501
+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."
-#: C/gtk-doc-manual.xml:1079(para)
-msgid "To emphasize text: <placeholder-1/>"
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1510
+#, no-wrap
+msgid ""
+"\n"
+"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
msgstr ""
+"\n"
+"<link linkend=\"glib-Hash-Tables\">Hashtabeller</link>\n"
-#: C/gtk-doc-manual.xml:1090(para)
-msgid "For filenames use: <placeholder-1/>"
+#. (itstool) path: sect1/para
+#: C/index.docbook:1506
+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. "
+"For most pages this is currently the part (\"gtk\", \"gdk\", \"glib\") and "
+"then the page title (\"Hash Tables\"). For widgets it is just the class "
+"name. Spaces and underscores are converted to '-' to conform to SGML/XML."
+msgstr ""
+"För att länka till ett annat avsnitt i GTK-dokumentationen: <_:"
+"informalexample-1/> Länkslutet är XGML/XML-id:t för toppnivåobjektet på "
+"sidan du vill länka till. För de flesta sidorna är detta för närvarande "
+"delen (”gtk”, ”gdk”, ”glib”) och sedan sidans titel (”Hashtabeller”). För "
+"komponenter är detta helt enkelt klassnamnet. Blanksteg och understreck "
+"konverteras till ”-” för att överensstämma med SGML/XML."
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1523
+#, no-wrap
+msgid ""
+"\n"
+"<function>...</function>\n"
msgstr ""
+"\n"
+"<function>…</function>\n"
-#: C/gtk-doc-manual.xml:1105(title)
-msgid "Filling the extra files"
+#. (itstool) path: sect1/para
+#: C/index.docbook:1520
+msgid ""
+"To refer to an external function, e.g. a standard C function: <_:"
+"informalexample-1/>"
msgstr ""
+"För att referera till en extern funktion, t.ex. en standardfunktion i C: <_:"
+"informalexample-1/>"
-#: C/gtk-doc-manual.xml:1107(para)
-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>-docs.sgml</filename>, <filename><package>-sections.txt</filename>."
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1532
+#, no-wrap
+msgid ""
+"\n"
+"<example>\n"
+" <title>Using a GHashTable.</title>\n"
+" <programlisting>\n"
+" ...\n"
+" </programlisting>\n"
+"</example>\n"
+msgstr ""
+"\n"
+"<example>\n"
+" <title>Att använda en hashtabell.</title>\n"
+" <programlisting>\n"
+" …\n"
+" </programlisting>\n"
+"</example>\n"
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1543
+#, no-wrap
+msgid ""
+"\n"
+"<informalexample>\n"
+" <programlisting>\n"
+" ...\n"
+" </programlisting>\n"
+"</informalexample>\n"
+msgstr ""
+"\n"
+"<informalexample>\n"
+" <programlisting>\n"
+" …\n"
+" </programlisting>\n"
+"</informalexample>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1529
+msgid ""
+"To include example code: <_:informalexample-1/> or possibly this, for very "
+"short code fragments which don't need a title: <_:informalexample-2/> For "
+"the latter GTK-Doc also supports an abbreviation: |[ ... ]|"
+msgstr ""
+"För att inkludera exempelkod: <_:informalexample-1/> eller möjligen "
+"följande, för väldigt korta kodfragment som inte behöver en titel: <_:"
+"informalexample-2/> För det senare fallet har GTK-Doc också stöd för "
+"förkortningen: |[ … ]|"
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1562
+#, no-wrap
+msgid ""
+"\n"
+"<itemizedlist>\n"
+" <listitem>\n"
+" <para>\n"
+" ...\n"
+" </para>\n"
+" </listitem>\n"
+" <listitem>\n"
+" <para>\n"
+" ...\n"
+" </para>\n"
+" </listitem>\n"
+"</itemizedlist>\n"
+msgstr ""
+"\n"
+"<itemizedlist>\n"
+" <listitem>\n"
+" <para>\n"
+" …\n"
+" </para>\n"
+" </listitem>\n"
+" <listitem>\n"
+" <para>\n"
+" …\n"
+" </para>\n"
+" </listitem>\n"
+"</itemizedlist>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1559
+msgid "To include bulleted lists: <_:informalexample-1/>"
+msgstr "För att inkludera punktlistor: <_:informalexample-1/>"
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1582
+#, no-wrap
+msgid ""
+"\n"
+"<note>\n"
+" <para>\n"
+" Make sure you free the data after use.\n"
+" </para>\n"
+"</note>\n"
+msgstr ""
+"\n"
+"<note>\n"
+" <para>\n"
+" Säkerställ att du frigjort data efter användning.\n"
+" </para>\n"
+"</note>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1579
+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/>"
-#: C/gtk-doc-manual.xml:1116(title)
-msgid "Editing the types file"
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1595
+#, no-wrap
+msgid ""
+"\n"
+"<type>unsigned char</type>\n"
msgstr ""
+"\n"
+"<type>unsigned char</type>\n"
-#: C/gtk-doc-manual.xml:1118(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."
+#. (itstool) path: sect1/para
+#: C/index.docbook:1592
+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:1604
+#, no-wrap
+msgid ""
+"\n"
+"<structname>XFontStruct</structname>\n"
msgstr ""
+"\n"
+"<structname>XFontStruct</structname>\n"
-#: C/gtk-doc-manual.xml:1127(title)
-msgid "Example types file snippet"
+#. (itstool) path: sect1/para
+#: C/index.docbook:1601
+msgid ""
+"To refer to an external structure (not one described in the GTK docs): <_:"
+"informalexample-1/>"
msgstr ""
+"För att referera till en extern struktur (som inte beskrivs i GTK-"
+"dokumentationen): <_:informalexample-1/>"
-#: C/gtk-doc-manual.xml:1141(para)
-msgid "Since gtk-doc 1.8 <application>gtkdoc-scan</application> can generate this list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in <filename>Makefile.am</filename>. If you use this approach you should not dist the types file nor have it under version control."
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1613
+#, no-wrap
+msgid ""
+"\n"
+"<structfield>len</structfield>\n"
msgstr ""
+"\n"
+"<structfield>len</structfield>\n"
-#: C/gtk-doc-manual.xml:1150(title)
-msgid "Editing the master document"
+#. (itstool) path: sect1/para
+#: C/index.docbook:1610
+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:1622
+#, no-wrap
+msgid ""
+"\n"
+"<classname>GtkWidget</classname>\n"
msgstr ""
+"\n"
+"<classname>GtkWidget</classname>\n"
-#: C/gtk-doc-manual.xml:1152(para)
-msgid "Gtk-Doc produces documentation in DocBook SGML/XML. When processing the inline source comments, the Gtk-Doc tools generate one documentation page per class or module as a separate file. The master document includes them and place them in a order."
+#. (itstool) path: sect1/para
+#: C/index.docbook:1619
+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 "
+"to the GtkWidget page - see <link linkend=\"documenting_syntax\">the "
+"abbreviations</link>)."
+msgstr ""
+"För att referera till ett klassnamn kan vi möjligen använda: <_:"
+"informalexample-1/> men du kommer troligt att använda #GtkWidget istället "
+"(för att automatiskt skapa en länk till GtkWidget-sidan - se <link linkend="
+"\"documenting_syntax\">förkortningarna</link>)."
+
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1633
+#, no-wrap
+msgid ""
+"\n"
+"<emphasis>This is important</emphasis>\n"
msgstr ""
+"\n"
+"<emphasis>Detta är viktigt</emphasis>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1630
+msgid "To emphasize text: <_:informalexample-1/>"
+msgstr "För att betona text: <_:informalexample-1/>"
-#: C/gtk-doc-manual.xml:1159(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: informalexample/programlisting
+#: C/index.docbook:1642
+#, no-wrap
+msgid ""
+"\n"
+"<filename>/home/user/documents</filename>\n"
msgstr ""
+"\n"
+"<filename>/home/användare/dokument</filename>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1639
+msgid "For filenames use: <_:informalexample-1/>"
+msgstr "För filnamn använd: <_:informalexample-1/>"
-#: C/gtk-doc-manual.xml:1169(para)
-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 documentation is that it is easy to link for the tutorial to symbol documentation. Apart chances are higher that the tutorial gets updates along with the library."
+#. (itstool) path: informalexample/programlisting
+#: C/index.docbook:1651
+#, no-wrap
+msgid ""
+"\n"
+"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
msgstr ""
+"\n"
+"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1648
+msgid "To refer to keys use: <_:informalexample-1/>"
+msgstr "För att referera till tangenter använd: <_:informalexample-1/>"
-#: C/gtk-doc-manual.xml:1178(para)
-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 which you should take care of."
+#. (itstool) path: chapter/title
+#: C/index.docbook:1661
+msgid "Filling the extra files"
+msgstr "Fylla i de extra filerna"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1663
+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>-docs.xml</filename> (in the past .sgml), "
+"<filename><package>-sections.txt</filename>."
+msgstr ""
+"Det finns ett antal extra filer som behöver underhållas tillsammans med de "
+"infogade källkodskommentarerna: <filename><paket>.types</filename>, "
+"<filename><paket>-docs.xml</filename> (tidigare .sgml), <filename><"
+"paket>-sections.txt</filename>."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1672
+msgid "Editing the types file"
+msgstr "Redigera typfilen"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1674
+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 ""
+"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>."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1683
+msgid "Example types file snippet"
+msgstr "Exempel på typfilsnutt"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1684
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\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"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1695
+msgid ""
+"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
+"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
+"<filename>Makefile.am</filename>. If you use this approach you should not "
+"dist the types file nor have it under version control."
+msgstr ""
+"Sedan GTK-Doc 1.8 kan <application>gtkdoc-scan</application> generera denna "
+"lista åt dig. Lägg bara till ”--rebuild-types” i SCAN_OPTIONS i "
+"<filename>Makefile.am</filename>. Om du använder detta tillvägagångssätt bör "
+"du inte distribuera typfilen eller versionshantera den."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1704
+msgid "Editing the master document"
+msgstr "Redigera huvuddokumentet"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1706
+msgid ""
+"GTK-Doc produces documentation in DocBook SGML/XML. When processing the "
+"inline source comments, the GTK-Doc tools generate one documentation page "
+"per class or module as a separate file. The master document includes them "
+"and place them in an order."
+msgstr ""
+"GTK-Doc producerar dokumentation i DocBook SGML/XML. När infogade "
+"källkodskommentarer behandlas genererar GTK-Doc en dokumentationssida per "
+"klass eller modul som en separat fil. Huvuddokumentet inkluderar dem och "
+"placerar dem i en ordning."
+
+# sebras: Its -> it's
+#. (itstool) path: sect1/para
+#: C/index.docbook:1713
+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 ""
+"Även om GTK-Doc skapar en mall för huvuddokumentet åt dig kommer senare "
+"körningar inte att röra det igen. Detta innebär att man är fri att "
+"strukturera om dokumentationen. Detta inkluderar att gruppera sidor och "
+"lägga till extra sidor. GTK-Doc har numera en testsvit där också "
+"huvuddokumentet återskapas från grunden. Det är en bra idé att titta på "
+"detta då och då för att se om några nya godsaker införts där."
+
+# sebras: for -> from Apart -> together/embedded...
+#. (itstool) path: tip/para
+#: C/index.docbook:1723
+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 "
+"documentation is that it is easy to link for the tutorial to symbol "
+"documentation. Apart chances are higher that the tutorial gets updates along "
+"with the library."
+msgstr ""
+"Skapa inte handledningar som extra dokument. Skriv bara extra kapitel. "
+"Fördelen med att bädda in handledningen direkt i ditt biblioteks "
+"gränssnittsdokumentation är att det är enkelt att länka från handledningen "
+"till symboldokumentationen. Inbäddad är det större chans att handledningen "
+"blir uppdaterad tillsammans med biblioteket."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1732
+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 "
+"which you should take care of."
msgstr ""
+"Så vilka saker ska ändras i huvuddokumentet? I början är det väldigt lite. "
+"Det finns en del platshållare (text i hakparenteser) som du bör ta hand om."
-#: C/gtk-doc-manual.xml:1185(title)
+#. (itstool) path: example/title
+#: C/index.docbook:1739
msgid "Master document header"
+msgstr "Huvuddokumentets huvud"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1740
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\n"
+"<bookinfo>\n"
+" <title>MODULNAMN handbok</title>\n"
+" <releaseinfo>\n"
+" för MODULNAMN [VERSION]\n"
+" Den senaste versionen av detta dokument kan hittas på nätet på\n"
+" <ulink role=\"online-location\" url=\"http://[SERVER]/MODULNAMN/index.html\">http://[SERVER]/MODULNAMN/</ulink>.\n"
+" </releaseinfo>\n"
+"</bookinfo>\n"
+"\n"
+"<chapter>\n"
+" <title>[Infoga titel här]</title>\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1756
+msgid ""
+"In addition a few option elements are created in commented form. You can "
+"review these and enable them as you like."
msgstr ""
+"Dessutom finns det ett antal valfria element som skapas i kommenterad form. "
+"Du kan granska dessa och aktivera dem enligt dina egna önskemål."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1762
+msgid "Optional part in the master document"
+msgstr "Valfri del i huvuddokumentet"
-#: C/gtk-doc-manual.xml:1207(title)
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1763
+#, 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 ""
+"\n"
+" <!-- aktivera detta om du vill använda gobject introspection-noteringar\n"
+" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n"
+" -->\n"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1771
+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 ""
+"Slutligen behöver du lägga till ett nytt avsnitt när du infogar det. "
+"Verktyget <link linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> "
+"kommer att påminna dig om nyligen genererade xml-filer som ännu inte "
+"infogats i dokumentationen."
+
+#. (itstool) path: example/title
+#: C/index.docbook:1779 C/index.docbook:1814
+msgid "Including generated sections"
+msgstr "Inkludera genererade avsnitt"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1780
+#, no-wrap
+msgid ""
+"\n"
+" <chapter>\n"
+" <title>my library</title>\n"
+" <xi:include href=\"xml/object.xml\"/>\n"
+" ...\n"
+msgstr ""
+"\n"
+" <chapter>\n"
+" <title>mitt bibliotek</title>\n"
+" <xi:include href=\"xml/object.xml\"/>\n"
+" ...\n"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1792
msgid "Editing the section file"
-msgstr ""
+msgstr "Redigera avsnittsfilen"
-#: C/gtk-doc-manual.xml:1209(para)
-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 the visibility (public or private)."
+#. (itstool) path: sect1/para
+#: C/index.docbook:1794
+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 "
+"the visibility (public or private)."
msgstr ""
+"Avsnittsfilen används för att organisera dokumentationsutdata från GTK-Doc. "
+"Här kan man ange vilken symbol som hör till vilken modul eller klass och "
+"styra synligheten (publik eller privat)."
-#: C/gtk-doc-manual.xml:1215(para)
-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."
+#. (itstool) path: sect1/para
+#: C/index.docbook:1800
+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."
msgstr ""
+"Avsnittsfilen är en vanlig textfil med taggar som avgränsar avsnitt. "
+"Blankrader ignoreras och rader som börjar med ett ”#” behandlas som "
+"kommentarsrader."
-#: C/gtk-doc-manual.xml:1221(para)
-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 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)."
+#. (itstool) path: note/para
+#: C/index.docbook:1807
+msgid ""
+"While the tags make the file look like xml, it is not. Please do not close "
+"tags like <SUBSECTION>."
msgstr ""
+"Även om taggarna får filen att se ut som xml, är det inte det. Avsluta inte "
+"taggar så som <SUBSECTION>."
-#: C/gtk-doc-manual.xml:1233(para)
-msgid "The <TITLE> ... </TITLE> tag is used to specify the title of the section. It is only useful before the templates are initially created, since the title set in the template file overrides this."
-msgstr ""
+#. (itstool) path: example/programlisting
+#: C/index.docbook:1815
+#, 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:1832
+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 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 ""
+"Taggen <FILE> … </FILE> används för att ange filnamnet, utan "
+"något suffix. Om man t.ex. använder ”<FILE>gnome-config</FILE>” "
+"blir resultatet att avsnittsdeklarationerna matas ut i mallfilen "
+"<filename>tmpl/gnome-config.sgml</filename>, som kommer att konverteras till "
+"DocBook XML-filen <filename>xml/gnome-config.sgml</filename> eller DocBook "
+"XML-filen <filename>xml/gnome-config.xml</filename>. (Namnet på HTML-filen "
+"baseras på modulnamnet och avsnittstiteln, för GObject baseras det på "
+"klassnamnet för GObjectet konverterat till gemener)."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1844
+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 "
+"created, since the title set in the template file overrides this. Also if "
+"one uses SECTION comment in the sources, this is obsolete."
+msgstr ""
+"Taggen <TITLE> … </TITLE> används för att ange titeln på "
+"avsnittet. Det är bara användbart före mallar skapas initialt (om de "
+"används), eftersom titeln som ställs in i avsnittsfilen åsidosätter denna. "
+"Vidare är detta föråldrat om man använder SECTIONS-kommentarer i källkoden."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1851
+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)."
+msgstr ""
+"Du kan gruppera objekt i avsnittet genom att använda taggen <"
+"SUBSECTION>. För närvarande matas en blankrad ut mellan underavsnitt i "
+"sammanfattningsavsnittet. Du kan också använda <SUBSECTION Standard> "
+"för standard GObject-deklarationer (t.ex. funktioner så som "
+"g_object_get_type och makron som G_OBJECT(), G_IS_OBJECT(), etc.). För "
+"närvarande utelämnas dessa ur dokumentationen. Du kan också använda <"
+"SUBSECTION Private> för privata deklarationer som inte kommer att matas "
+"ut (det är ett bekvämt sätt att undvika varningsmeddelanden om oanvända "
+"deklarationer). Om ditt bibliotek innehåller privata typer som du inte vill "
+"ska dyka upp i objekthierarkin och i listan över implementerade eller krävda "
+"gränssnitt, lägg till dem i ett privat avsnitt. Huruvida du vill placera "
+"GObject och GObjectClass-liknande strukturer i publika eller standardavsnitt "
+"beror på om de har publika poster (variabler, virtuella metoder)."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1870
+msgid ""
+"You can also use <INCLUDE> ... </INCLUDE> to specify the "
+"#include files which are shown in the synopsis sections. It contains a comma-"
+"separate list of #include files, without the angle brackets. If you set it "
+"outside of any sections, it acts for all sections until the end of the file. "
+"If you set it within a section, it only applies to that section."
+msgstr ""
+"Du kan också använda <INCLUDE> ... </INCLUDE> för att ange "
+"#include-filerna som ska visas i sammanfattningsavsnitten. Den innehåller en "
+"kommaavgränsad lista av #include-filer, utan vinkelparenteser. Om du ställer "
+"in det utanför några avsnitt kommer det att påverka alla avsnitt tills "
+"slutet på filen. Om du ställer in det inom ett avsnitt kommer det bara att "
+"påverka det avsnittet."
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:1884
+msgid "Controlling the result"
+msgstr "Kontrollera resultatet"
-#: C/gtk-doc-manual.xml:1239(para)
-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."
+#. (itstool) path: chapter/para
+#: C/index.docbook:1886
+msgid ""
+"A GTK-Doc run generates report files inside the documentation directory. The "
+"generated files are named: <filename><package>-undocumented.txt</"
+"filename>, <filename><package>-undeclared.txt</filename> and "
+"<filename><package>-unused.txt</filename>. All those are plain text "
+"files that can be viewed and postprocessed easily."
+msgstr ""
+"En GTK-Doc-körning genererar rapportfiler inuti dokumentationskatalogen. De "
+"genererade filerna heter: <filename><paket>-undocumented.txt</"
+"filename>, <filename><paket>-undeclared.txt</filename> och "
+"<filename><paket>-unused.txt</filename>. Alla är vanliga textfiler och "
+"kan visas eller efterbehandlas enkelt."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1895
+msgid ""
+"The <filename><package>-undocumented.txt</filename> file starts with "
+"the documentation coverage summary. Below are two sections divided by blank "
+"lines. The first section lists undocumented or incomplete symbols. The "
+"second section does the same for section docs. Incomplete entries are those, "
+"which have documentation, but where e.g. a new parameter has been added."
+msgstr ""
+"Filen <filename><paket>-undocumented.txt</filename> inleds med en "
+"sammanfattning över hur mycket dokumentation som skrivits. Under det finns "
+"två avsnitt avgränsade av blankrader. Det första avsnittet listar "
+"odokumenterade eller ofullständiga symboler. Det andra avsnittet gör "
+"detsamma för avsnittsdokumentation. Ofullständiga poster är de som har "
+"dokumentation, men där en ny parameter har lagts till."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1904
+msgid ""
+"The <filename><package>-undeclared.txt</filename> file lists symbols "
+"given in the <filename><package>-sections.txt</filename> but not found "
+"in the sources. Check if they have been removed or if they are misspelled."
msgstr ""
+"Filen <filename><paket>-undeclared.txt</filename> listar symboler som "
+"anges i <filename><paket>-sections.txt</filename> men inte hittas i "
+"källkoden. Kontrollera om de har tagits bort eller om de är felstavade."
-#: C/gtk-doc-manual.xml:1255(para)
-msgid "You can also use <INCLUDE> ... </INCLUDE> to specify the #include files which are shown in the synopsis sections. It contains a comma-separate list of #include files, without the angle brackets. If you set it outside of any sections, it acts for all sections until the end of the file. If you set it within a section, it only applies to that section."
+#. (itstool) path: chapter/para
+#: C/index.docbook:1911
+msgid ""
+"The <filename><package>-unused.txt</filename> file lists symbol names, "
+"where the GTK-Doc scanner has found documentation, but does not know where "
+"to put it. This means that the symbol has not yet been added to the "
+"<filename><package>-sections.txt</filename> file."
+msgstr ""
+"Filen <filename><paket>-unused.txt</filename> listar symbolnamn där "
+"GTK-Doc-detektorn har hittat dokumentation men inte vet var den ska "
+"placeras. Detta innebär att symbolen ännu inte har lagts till i filen "
+"<filename><package>-sections.txt</filename>."
+
+# sebras: <filename>?
+#. (itstool) path: tip/para
+#: C/index.docbook:1919
+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 "
+"<command>make check</command> run."
msgstr ""
+"Aktivera eller lägg till raden <option>TESTS=$(GTKDOC_CHECK)</option> i "
+"Makefile.am. Om åtminstone GTK-Doc 1.9 finns installerat kommer detta att "
+"köra rimlighetskontroller under körning av <command>make check</command>."
-#: C/gtk-doc-manual.xml:1269(title)
-msgid "Controlling the result"
+#. (itstool) path: chapter/para
+#: C/index.docbook:1926
+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."
+msgstr ""
+"Man kan också titta på filerna som producerats av källkodsdetektorn: "
+"<filename><paket>-decl-list.txt</filename> och <filename><paket>-"
+"decl.txt</filename>. Den första kan jämföras med avsnittsfilen om den "
+"underhålls manuellt. Den andra listar alla deklarationer från huvudena. Om "
+"en symbol saknas bör man kontrollera om denna filen innehåller den."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1935
+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 GTK-Doc "
+"to keep the intermediate scanner file for further analysis, by running it as "
+"<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>."
+msgstr ""
+"Om projektet är GObject-baserat kan man också titta på filerna som "
+"producerats av objekt-detektorn: <filename><paket>.args.txt</"
+"filename>, <filename><paket>.hierarchy.txt</filename>, <filename><"
+"paket>.interfaces.txt</filename>, <filename><paket>.prerequisites."
+"txt</filename> och <filename><paket>.signals.txt</filename>. Om det "
+"saknas symboler i någon av dem kan man be GTK-Doc att bibehålla de temporära "
+"detektorfilerna för vidare analys, genom att köra det som "
+"<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>."
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:1950
+msgid "Modernizing the documentation"
+msgstr "Modernisera dokumentationen"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:1952
+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 ""
+"GTK-Doc har funnits ett tag. I detta avsnitt listar vi nya funktioner "
+"tillsammans med vilken version de gjordes tillgängliga."
-#: C/gtk-doc-manual.xml:1271(para)
-msgid "A Gtk-Doc run generates report files inside the documentation directory. The generated files are named: <filename><package>-undocumented.txt</filename>, <filename><package>-undeclared.txt</filename> and <filename><package>-unused.txt</filename>. All those are plain text files that can be viewed and postprocessed easily."
-msgstr ""
+#. (itstool) path: sect1/title
+#: C/index.docbook:1958
+msgid "GTK-Doc 1.9"
+msgstr "GTK-Doc 1.9"
-#: C/gtk-doc-manual.xml:1280(para)
-msgid "The <filename><package>-undocumented.txt</filename> file starts with the documentation coverage summary. Below are two sections divided by blank lines. The first section lists undocumented or incomplete symbols. The second section does the same for section docs. Incomplete entries are those, which have documentation, but where e.g. a new parameter has been added."
+#. (itstool) path: sect1/para
+#: C/index.docbook:1960
+msgid ""
+"When using xml instead of sgml, one can actually name the master document "
+"<filename><package>-docs.xml</filename>."
msgstr ""
+"När man använder xml istället för sgml, kan man faktiskt kalla "
+"huvuddokumentet <filename><paket>-docs.xml</filename>."
-#: C/gtk-doc-manual.xml:1289(para)
-msgid "The <filename><package>-undeclared.txt</filename> file lists symbols given in the <filename><package>-section.txt</filename> but not found in the sources. Check if they have been removed or if they are misspelled."
+#. (itstool) path: sect1/para
+#: C/index.docbook:1965
+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 ""
+"Denna version har stöd för <option>SCAN_OPTIONS=--rebuild-sections</option> "
+"i <filename>Makefile.am</filename>. När detta är aktiverat kommer "
+"<filename><paket>-sections.txt</filename> att autogenereras och kan "
+"tas bort från versionshanteringssystemet. Detta fungerar bra för projekt som "
+"har en väldigt standardiserad struktur (t.ex. kommer varje .{c,h}-par att "
+"skapa ett nytt avsnitt). Om man organiserar ett projekt likt detta kommer "
+"den manuella uppdateringen av en avsnittsfil att vara så enkelt som att köra "
+"<code>meld <paket>-decl-list.txt <paket>-sections.txt</code>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1976
+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 ""
+"Redan version 1.8 introducerade syntaxen för avsnittsdokumentation i "
+"källkoden istället för separata filer under <filename class=\"directory"
+"\">tmpl</filename>. Denna version lägger till flaggor för att kunna ställa "
+"om hela dokumentationsmodulen till att inte använda det extra tmpl-"
+"byggsteget alls, genom att använda <option>--flavour no-tmpl</option> i "
+"<filename>configure.ac</filename>. Om du inte har <filename class=\"directory"
+"\">tmpl</filename> incheckat i ditt versionshanteringssystem just nu och "
+"inte har gått över än bara lägg till flaggan i <filename>configure.ac</"
+"filename> så är du klar."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:1988
+msgid "GTK-Doc 1.10"
+msgstr "GTK-Doc 1.10"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:1990
+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 ""
+"Denna version har stöd för <option>SCAN_OPTIONS=--rebuild-types</option> i "
+"<filename>Makefile.am</filename>. När det är aktiverat kommer <filename><"
+"package>.types</filename> att autogenereras och kan tas bort från "
+"versionshanteringssystemet. När denna funktion används är det viktigt att "
+"också ställa in <varname>IGNORE_HFILES</varname> i <filename>Makefile.am</"
+"filename> för kod som bara byggs ibland."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2001
+msgid "GTK-Doc 1.16"
+msgstr "GTK-Doc 1.16"
+
+#. (itstool) path: example/title
+#: C/index.docbook:2007
+msgid "Enable gtkdoc-check"
+msgstr "Aktivera gtkdoc-check"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2008
+#, 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:2003
+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 ""
+"Denna version har stöd för ett nytt verktyg som heter gtkdoc-check. Detta "
+"verktyg kan köra en uppsättning kontroller på din dokumentation. Det "
+"aktiveras genom att lägga till dessa raderna i slutet av <filename>Makefile."
+"am</filename>. <_:example-1/>"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2021
+msgid "GTK-Doc 1.20"
+msgstr "GTK-Doc 1.20"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:2023
+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 ""
+"Version 1.18 införde inledande stöd för markdown. Att använda markdown i "
+"dokumentationskommentarer är mindre påträngande än att skriva docbook xml. "
+"Denna version förbättrar detta väsentligt och lägger till många fler stilar. "
+"Avsnittet som beskriver <link linkend=\"documenting_syntax"
+"\">kommentarsyntax</link> finnas alla detaljer."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2033
+msgid "GTK-Doc 1.25"
+msgstr "GTK-Doc 1.25"
+
+#. (itstool) path: example/title
+#: C/index.docbook:2043
+msgid "Use pre-generated entities"
+msgstr "Att använda förgenererade entiteter"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2044
+#, 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; handbok</title>\n"
+" <releaseinfo>\n"
+" för &package_string;.\n"
+" Den senaste versionen av detta dokument kan hittas på nätet på\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:2035
+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 ""
+"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-1/>"
+
+#. (itstool) path: chapter/title
+#: C/index.docbook:2069
+msgid "Documenting other interfaces"
+msgstr "Dokumentera andra gränssnitt"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:2071
+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 "
+"interfaces too."
msgstr ""
+"Så här långt har vi använt GTK-Doc för att dokumentera API:t för koden. "
+"Följande avsnitt innehåller förslag om hur verktyget kan användas för att "
+"också dokumentera andra gränssnitt."
-#: C/gtk-doc-manual.xml:1296(para)
-msgid "The <filename><package>-unused.txt</filename> file lists symbol names, where the Gtk-Doc scanner has found documentation, but does not know where to put it. This means that the symbol has not yet been added to the <filename><package>-section.txt</filename> file."
-msgstr ""
+#. (itstool) path: sect1/title
+#: C/index.docbook:2078
+msgid "Command line options and man pages"
+msgstr "Kommandoradsflaggor och mansidor"
-#: C/gtk-doc-manual.xml:1304(para)
-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 make check run."
+#. (itstool) path: sect1/para
+#: C/index.docbook:2080
+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 "
+"the reference and one gets the man-page for free."
+msgstr ""
+"Då man också kan generera mansidor för ett docbook-refentry, låter det som "
+"en bra idé att använda det för detta ändamål. På detta sättet kommer "
+"gränssnittet att vara en del av referensen och man får mansidan gratis."
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:2087
+msgid "Document the tool"
+msgstr "Dokumentera verktyget"
+
+# sebras: strange English
+#. (itstool) path: sect2/para
+#: C/index.docbook:2089
+msgid ""
+"Create one refentry file per tool. Following <link linkend="
+"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
+"docs/reference/meeper/meep.xml</filename>. For the xml tags that should be "
+"used and can look at generated file in the xml subdirectory as well as "
+"examples e.g. in glib."
+msgstr ""
+"Skapa en refentry-fil per verktyg. Om du följer <link linkend="
+"\"settingup_docfiles\">vårt exempel</link> borde vi kalla det <filename>meep/"
+"docs/reference/meeper/meep.xml</filename>. För xml-taggarna bör detta "
+"användas och man kan studera den genererade filen i xml-underkatalogen så "
+"väl som exempel i glib."
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:2099
+msgid "Adding the extra configure check"
+msgstr "Lägga till den extra configure-kontrollen"
+
+#. (itstool) path: example/title
+#: C/index.docbook:2102 C/index.docbook:2120
+msgid "Extra configure checks"
+msgstr "Lägga till extra configure-kontroller"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2103
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\n"
+"AC_ARG_ENABLE(man,\n"
+" [AC_HELP_STRING([--enable-man],\n"
+" [omgenerera mansidor från Docbook [standardvärde=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"
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:2117
+msgid "Adding the extra makefile rules"
+msgstr "Lägga till de extra makefilsreglerna"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:2121
+#, no-wrap
+msgid ""
+"\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"
+msgstr ""
+"\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"
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:2143
+msgid "DBus interfaces"
+msgstr "DBus-gränssnitt"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:2145
+msgid ""
+"(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://"
+"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
msgstr ""
+"(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://"
+"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)"
-#: C/gtk-doc-manual.xml:1314(title)
-msgid "Frequently asked question"
+#. (itstool) path: chapter/title
+#: C/index.docbook:2154
+msgid "Frequently asked questions"
msgstr "Frågor och svar"
-#: C/gtk-doc-manual.xml:1318(segtitle)
+#. (itstool) path: segmentedlist/segtitle
+#: C/index.docbook:2158
msgid "Question"
msgstr "Fråga"
-#: C/gtk-doc-manual.xml:1319(segtitle)
+#. (itstool) path: segmentedlist/segtitle
+#: C/index.docbook:2159
msgid "Answer"
msgstr "Svar"
-#: C/gtk-doc-manual.xml:1321(seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2161
msgid "No class hierarchy."
-msgstr ""
+msgstr "Ingen klasshierarki."
-#: C/gtk-doc-manual.xml:1322(filename)
-msgid ".types"
-msgstr ""
-
-#: C/gtk-doc-manual.xml:1322(seg)
-msgid "The objects _get_type() function has not been entered into the <placeholder-1/> file."
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2162
+msgid ""
+"The objects <function>xxx_get_type()</function> function has not been "
+"entered into the <filename><package>.types</filename> file."
msgstr ""
+"Objektens <function>xxx_get_type()</function>-funktion har inte matats in i "
+"filen <filename><paket>.types</filename>."
-#: C/gtk-doc-manual.xml:1325(seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2168
msgid "Still no class hierarchy."
-msgstr ""
-
-#: C/gtk-doc-manual.xml:1326(ulink)
-msgid "explanation"
-msgstr "förklaring"
+msgstr "Fortfarande ingen klasshierarki."
-#: C/gtk-doc-manual.xml:1326(seg)
-msgid "Wrong naming in section file (see <placeholder-1/>)"
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2169
+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\">explanation</ulink>)."
msgstr ""
+"Saknat eller fel namn i filen <filename><paket>-sections.txt</"
+"filename> (se <ulink url=\"http://mail.gnome.org/archives/gtk-doc-list/2003-"
+"October/msg00006.html\">förklaring</ulink>)."
-#: C/gtk-doc-manual.xml:1329(seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2175
msgid "Damn, I have still no class hierarchy."
-msgstr ""
+msgstr "Förbannat, jag har fortfarande ingen klasshierarki."
-#: C/gtk-doc-manual.xml:1330(seg)
-msgid "Is the object name (name of the instance struct) part of the normal section (don't put this into Standard or Private)."
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2176
+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 "
+"subsections)."
msgstr ""
+"Är objektnamnet (namnet på instansstrukturen, t.ex. <type>GtkWidget</type>) "
+"del av det normala avsnittet (stoppa inte detta i underavsnitt så som "
+"Standard eller Private)."
-#: C/gtk-doc-manual.xml:1333(seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2183
msgid "No symbol index."
-msgstr ""
+msgstr "Inget symbolindex."
-#: C/gtk-doc-manual.xml:1334(seg)
-msgid "FIXME (<index> tag in main sgml file)"
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2184
+msgid ""
+"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
+"index that xi:includes the generated index?"
msgstr ""
+"Innehåller <filename><paket>-docs.{xml,sgml}</filename> ett index som "
+"inkluderar det genererade indexet med xi:include?"
-#: C/gtk-doc-manual.xml:1337(seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2190
msgid "Symbols are not linked to their doc-section."
-msgstr ""
+msgstr "Symboler är inte länkade till deras dokumentationsavsnitt."
-#: C/gtk-doc-manual.xml:1338(seg)
-msgid "FIXME (added #,% or () ?)"
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2191
+msgid ""
+"Is the doc-comment using the correct markup (added #,% or ())? Check if the "
+"gtkdoc-fixxref warns about unresolvable xrefs."
msgstr ""
+"Använder dokumentationskommentaren korrekta taggar (har du lagt till #, % "
+"eller ())? Kontrollera om gtkdoc-fixxref varnar om oupplösbara "
+"korsreferenser."
-#: C/gtk-doc-manual.xml:1341(seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2197
msgid "A new class does not appear in the docs."
-msgstr ""
+msgstr "En ny klass dyker inte upp i dokumentationen."
-#: C/gtk-doc-manual.xml:1342(seg)
-msgid "FIXME (section file, types file, main-sgml file)"
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2198
+msgid ""
+"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
+"filename>."
msgstr ""
+"Är den nya sidan inkluderad med xi:include från <filename><package>-"
+"docs.{xml,sgml}</filename>."
-#: C/gtk-doc-manual.xml:1345(seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2204
msgid "A new symbol does not appear in the docs."
-msgstr ""
+msgstr "En ny symbol dyker inte upp i dokumentationen."
-#: C/gtk-doc-manual.xml:1346(seg)
-msgid "FIXME (section file, proper doc comment)"
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2205
+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 "
+"xrefs. Check if the symbol is correctly listed in the <filename><"
+"package>-sections.txt</filename> in a public subsection."
+msgstr ""
+"Är dokumentationskommentaren korrekt formaterad. Leta efter stavfel i början "
+"av kommentaren. Kontrollera om gtkdoc-fixxref varnar om oupplösbara "
+"korsreferenser. Kontrollera om symbolen finns korrekt listad i <filename><"
+"paket>-sections.txt</filename> i ett publikt avsnitt."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2213
+msgid "A type is missing from the class hierarchy."
+msgstr "En typ saknas från klasshierarkin."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2214
+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 incidentally marked private it will not be shown."
+msgstr ""
+"Om typen finns listad i <filename><paket>.hierarchy</filename> men "
+"inte i <filename>xml/tree_index.sgml</filename>, dubbelkolla då att typen "
+"finns korrekt placerad i <filename><paket>-sections.txt</filename>. Om "
+"typinstansen (t.ex. <type>GtkWidget</type>) inte visas eller är markerad "
+"privat kommer den inte att visas."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2223
+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:2224
+msgid ""
+"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
+"from <filename><package>-docs.{xml,sgml}</filename>."
msgstr ""
+"Kontrollera att <filename>xml/annotation-glossary.xml</filename> är "
+"inkluderad med xi:include från <filename><package>-docs.{xml,sgml}</"
+"filename>."
-#: C/gtk-doc-manual.xml:1351(seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2232
msgid "Parameter described in source code comment block but does not exist"
-msgstr ""
+msgstr "Parameter beskriven i kommentarsblock i källkoden men existerar inte"
-#: C/gtk-doc-manual.xml:1352(seg)
-msgid "Check if the prototype in the header has different parameter names as in the source."
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2233
+msgid ""
+"Check if the prototype in the header has different parameter names as in the "
+"source."
msgstr ""
+"Kontrollera om prototypen i huvudet har andra parameternamn än i källkoden."
-#: C/gtk-doc-manual.xml:1356(seg)
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2238
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:2239
+msgid ""
+"Symbol XYZ appears twice in <filename><package>-sections.txt</"
+"filename> file."
msgstr ""
+"Symbolen XYZ förekommer två gånger i filen <filename><paket>-sections."
+"txt</filename>."
+
+#. (itstool) path: seglistitem/seg
+#: C/index.docbook:2242
+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:2249
+msgid "Tools related to gtk-doc"
+msgstr "Verktyg relaterade till gtk-doc"
-#: C/gtk-doc-manual.xml:1357(seg)
-msgid "Symbol XYZ appears twice in -section.txt file."
+#. (itstool) path: chapter/para
+#: C/index.docbook:2251
+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 "
+"integrates with the trac search."
msgstr ""
+"GtkDocPlugin - en insticksmodul för <ulink url=\"http://trac-hacks.org/wiki/"
+"GtkDocPlugin\">Trac GTK-Doc</ulink>-integrering som lägger till API-"
+"dokumentation till en trac-webbplats och integrerar med trac-sökningen."
-#: C/gtk-doc-manual.xml:1360(seg)
-msgid "Element typename in namespace '' encountered in para, but no template matches."
+#. (itstool) path: chapter/para
+#: C/index.docbook:2256
+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."
msgstr ""
+"Gtkdoc-depscan - ett verktyg (del av gtk-doc) för att kontrollera använda "
+"API mot since-taggar i API:t för att avgöra minsta version som krävs."
-#: C/gtk-doc-manual.xml:12(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/gtk-doc-manual.xml:16(year)
-msgid "2000"
-msgstr "2000"
+#. (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/gtk-doc-manual.xml:16(holder)
-msgid "Free Software Foundation, Inc."
-msgstr "Free Software Foundation, Inc."
+#. (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>"
+msgstr ""
+"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/gtk-doc-manual.xml:19(para)
-msgid "<address>Free Software Foundation, Inc. <street>51 Franklin Street, Suite 330</street>, <city>Boston</city>, <state>MA</state><postcode>02110-1301</postcode><country>USA</country></address> Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed."
-msgstr "<address>Free Software Foundation, Inc. <street>51 Franklin Street, Suite 330</street>, <city>Boston</city>, <state>MA</state><postcode>02110-1301</postcode><country>USA</country></address>. Var och en äger kopiera och sprida ordagranna kopior av detta licensavtal [originalet och denna översättning], men att ändra det är inte tillåtet."
+#. (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."
+msgstr ""
+"<_:address-1/>. Alla är tillåtna kopiera och distribuera ordagranna kopior "
+"av detta licensdokument, men att ändra det är ej tillåtet."
-#: C/gtk-doc-manual.xml:28(title)
+#. (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 "GNU Free Documentation License"
-#: C/gtk-doc-manual.xml:31(title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:31 C/fdl-appendix.xml:31
msgid "0. PREAMBLE"
msgstr "0. BAKGRUND"
-#: C/gtk-doc-manual.xml:32(para)
-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 effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others."
-msgstr "Syftet med denna licens är att göra en handbok, bok, eller annat praktiskt och användbart dokument <quote>fritt</quote> som i frihet: att försäkra var och en den faktiska friheten att kopiera och sprida det vidare, med eller utan förändringar, antingen kommersiellt eller ideellt. Sekundärt bevarar denna licens ett sätt för författaren och förläggaren att få ära för deras arbete utan att de anses vara ansvariga för förändringar gjorda av andra."
-
-#: C/gtk-doc-manual.xml:43(para)
-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. It complements the GNU General Public License, which is a copyleft license designed for free software."
-msgstr "Denna Licens är en sorts <quote>copyleft</quote>, vilket betyder att derivativa verk av detta dokument själva måste vara fria på samma sätt. Den kompletterar GNU General Public License, som är en copyleft-licens utformad för fri programvara."
-
-#: C/gtk-doc-manual.xml:50(para)
-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 should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference."
-msgstr "Vi har utformat denna licens för att den skall användas för handböcker till fri programvara, eftersom fri programvara behöver fri dokumentation: ett fritt program bör ha en handbok som erbjuder samma friheter som programmet gör. Men denna licens är inte begränsad till programvaruhandböcker; den kan användas för vilket textverk som helst oavsett ämne eller huruvida det är en utgiven, tryckt bok. Vi rekommenderar denna licens huvudsakligen för alla verk vars syfte är instruktion eller referens."
-
-#: C/gtk-doc-manual.xml:62(title)
+#. (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 "
+"effective freedom to copy and redistribute it, with or without modifying it, "
+"either commercially or noncommercially. Secondarily, this License preserves "
+"for the author and publisher a way to get credit for their work, while not "
+"being considered responsible for modifications made by others."
+msgstr ""
+"Syftet med denna licens är att göra en handbok, bok, eller annat praktiskt "
+"och användbart dokument <quote>fritt</quote> som i frihet: att försäkra var "
+"och en den faktiska friheten att kopiera och sprida det vidare, med eller "
+"utan förändringar, antingen kommersiellt eller ideellt. Sekundärt bevarar "
+"denna licens ett sätt för författaren och förläggaren att få ära för deras "
+"arbete utan att de anses vara ansvariga för förändringar gjorda av andra."
+
+#. (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. "
+"It complements the GNU General Public License, which is a copyleft license "
+"designed for free software."
+msgstr ""
+"Denna Licens är en sorts <quote>copyleft</quote>, vilket betyder att "
+"derivativa verk av detta dokument själva måste vara fria på samma sätt. Den "
+"kompletterar GNU General Public License, som är en copyleft-licens utformad "
+"för fri programvara."
+
+#. (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 "
+"should come with manuals providing the same freedoms that the software does. "
+"But this License is not limited to software manuals; it can be used for any "
+"textual work, regardless of subject matter or whether it is published as a "
+"printed book. We recommend this License principally for works whose purpose "
+"is instruction or reference."
+msgstr ""
+"Vi har utformat denna licens för att den skall användas för handböcker till "
+"fri programvara, eftersom fri programvara behöver fri dokumentation: ett "
+"fritt program bör ha en handbok som erbjuder samma friheter som programmet "
+"gör. Men denna licens är inte begränsad till programvaruhandböcker; den kan "
+"användas för vilket textverk som helst oavsett ämne eller huruvida det är en "
+"utgiven, tryckt bok. Vi rekommenderar denna licens huvudsakligen för alla "
+"verk vars syfte är instruktion eller referens."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:62 C/fdl-appendix.xml:62
msgid "1. APPLICABILITY AND DEFINITIONS"
-msgstr "TILLÄMPNINGSOMRÅDE OCH DEFINITIONER"
-
-#: C/gtk-doc-manual.xml:63(para)
-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 of this License. The <quote>Document</quote>, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as <quote>you</quote>."
-msgstr "Denna licens [det engelska originalet] gäller för varje handbok eller annat verk, oavsett uttrycksform, som innehåller ett meddelande där upphovsrättsinnehavaren stadgat att verket kan spridas enligt villkoren i GNU Free Documentation License. Ett sådant meddelande ger en internationell frihet utan krav på ersättning och utan tidsbegränsning att använda verket under villkoren i denna licens [det engelska originalet]. <quote>Dokument</quote> nedan syftar på godtycklig handbok eller verk. Var och en är licenstagare och benämns som <quote>du</quote>."
-
-#: C/gtk-doc-manual.xml:72(para)
-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 modifications and/or translated into another language."
-msgstr "En <quote>förändrad version</quote> av dokumentet avser varje verk som innehåller dokumentet eller en del av det, antingen ordagranna kopior, eller med ändringar och/eller översatt till ett annat språk."
+msgstr "1. TILLÄMPNINGSOMRÅDE OCH DEFINITIONER"
-#: C/gtk-doc-manual.xml:79(para)
-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 exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them."
-msgstr "Ett <quote>sekundärt avsnitt</quote> är en märkt bilaga eller förord till <link linkend=\"fdl-document\">dokumentet</link> som exklusivt behandlar förhållandet mellan dokumentets förläggare eller författare och dokumentets huvudsakliga ämne (eller till relaterade ämnen) och som inte innehåller något som direkt faller under det huvudsakliga ämnet. (Således, om dokumentet delvis är en lärobok i matematik så får ett sekundärt avsnitt inte förklara någon matematik.) Förhållandet kan vara en historisk koppling till ämnet eller något relaterat, eller en juridisk, kommersiell, filosofisk, etisk eller politisk ställning till det."
-
-#: C/gtk-doc-manual.xml:94(para)
-msgid "The <quote>Invariant Sections</quote> are certain <link linkend=\"fdl-secondary\"> Secondary Sections</link> whose titles are designated, as being those of Invariant Sections, in the notice that says that the <link linkend=\"fdl-document\">Document</link> is released under this License."
-msgstr "De <quote>oföränderliga avsnitten</quote> är <link linkend=\"fdl-secondary\">sekundära avsnitt</link> vars titlar är angivna som oföränderliga avsnitt i meddelandet som stadgar att <link linkend=\"fdl-document\">dokumentet</link> är utgivet under denna licens [det engelska originalet]."
-
-#: C/gtk-doc-manual.xml:103(para)
-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 that the <link linkend=\"fdl-document\">Document</link> is released under this License."
-msgstr "<quote>Omslagstexterna</quote> är speciella korta ordföljder som är listade som framsidestexter eller baksidestexter i meddelandet som stadgar att <link linkend=\"fdl-document\">dokumentet</link> är utgivet under denna licens [det engelska originalet]."
-
-#: C/gtk-doc-manual.xml:111(para)
-msgid "A <quote>Transparent</quote> copy of the <link linkend=\"fdl-document\"> Document</link> means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not <quote>Transparent</quote> is called <quote>Opaque</quote>."
-msgstr "En <quote>transparent</quote> kopia av <link linkend=\"fdl-document\">dokumentet</link> är en maskinläsbar kopia, representerad i ett format vars specifikation finns tillgänglig för allmänheten, som lämpar sig för att revidera dokumentet på ett enkelt sätt med generella textredigeringsprogram eller (för pixelbaserade bilder) generella grafikprogram eller (för ritningar) något väl tillgängligt ritprogram, och som är passande som indata till textfomaterare eller för automatisk konvertering till en mängd format som passar som indata till textformaterare. En kopia i ett för övrigt transparent filformat vars markeringar, eller avsaknad av markeringar, har ordnats för att hindra eller motverka att vidare förändring vidtas av läsare är inte transparent. Ett bildformat är inte transparent om det används för någon betydande del text. En kopia som inte är <quote>transparent</quote> kallas <quote>opak</quote>."
-
-#: C/gtk-doc-manual.xml:128(para)
-msgid "Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only."
-msgstr "Exempel på passande format för transparenta kopior innefattar ren ASCII utan markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript eller PDF utformat för mänsklig förändring. Exempel på transparenta bildformat innefattar PNG, XCF och JPG. Opaka format innefattar leverantörsspecifika format som bara kan läsas och editeras med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/eller verktyg för behandling inte finns allmänt tillgängliga, och den maskingenererade HTML, PostScript eller PDF som produceras av vissa ordbehandlare enbart avsett som utdata."
-
-#: C/gtk-doc-manual.xml:141(para)
-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 material this License requires to appear in the title page. For works in formats which do not have any title page as such, <quote>Title Page</quote> means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text."
-msgstr "<quote>Titelsidan</quote> innebär, för en tryckt bok, titelsidan själv, och sådana därpå följande sidor som krävs för att göra det material som enligt denna licens skall synas på titelsidan läsbart. För verk i sådana format som inte har någon egentlig titelsida, avses med <quote>titelsida</quote> den text som är närmast den mest framstående förekomsten av verkets titel, föregående den huvudsakliga textmassan."
+#. (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 "
+"of this License. The <quote>Document</quote>, below, refers to any such "
+"manual or work. Any member of the public is a licensee, and is addressed as "
+"<quote>you</quote>."
+msgstr ""
+"Denna licens [det engelska originalet] gäller för varje handbok eller annat "
+"verk, oavsett uttrycksform, som innehåller ett meddelande där "
+"upphovsrättsinnehavaren stadgat att verket kan spridas enligt villkoren i "
+"GNU Free Documentation License. Ett sådant meddelande ger en internationell "
+"frihet utan krav på ersättning och utan tidsbegränsning att använda verket "
+"under villkoren i denna licens [det engelska originalet]. <quote>Dokument</"
+"quote> nedan syftar på godtycklig handbok eller verk. Var och en är "
+"licenstagare och benämns som <quote>du</quote>."
+
+#. (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 "
+"modifications and/or translated into another language."
+msgstr ""
+"En <quote>förändrad version</quote> av dokumentet avser varje verk som "
+"innehåller dokumentet eller en del av det, antingen ordagranna kopior, eller "
+"med ändringar och/eller översatt till ett annat språk."
-#: C/gtk-doc-manual.xml:153(title)
+#. (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 "
+"exclusively with the relationship of the publishers or authors of the "
+"Document to the Document's overall subject (or to related matters) and "
+"contains nothing that could fall directly within that overall subject. (For "
+"example, if the Document is in part a textbook of mathematics, a Secondary "
+"Section may not explain any mathematics.) The relationship could be a matter "
+"of historical connection with the subject or with related matters, or of "
+"legal, commercial, philosophical, ethical or political position regarding "
+"them."
+msgstr ""
+"Ett <quote>sekundärt avsnitt</quote> är en märkt bilaga eller förord till "
+"<link linkend=\"fdl-document\">dokumentet</link> som exklusivt behandlar "
+"förhållandet mellan dokumentets förläggare eller författare och dokumentets "
+"huvudsakliga ämne (eller till relaterade ämnen) och som inte innehåller "
+"något som direkt faller under det huvudsakliga ämnet. (Således, om "
+"dokumentet delvis är en lärobok i matematik så får ett sekundärt avsnitt "
+"inte förklara någon matematik.) Förhållandet kan vara en historisk koppling "
+"till ämnet eller något relaterat, eller en juridisk, kommersiell, "
+"filosofisk, etisk eller politisk ställning till det."
+
+#. (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 "
+"those of Invariant Sections, in the notice that says that the <link linkend="
+"\"fdl-document\">Document</link> is released under this License."
+msgstr ""
+"De <quote>oföränderliga avsnitten</quote> är <link linkend=\"fdl-secondary"
+"\">sekundära avsnitt</link> vars titlar är angivna som oföränderliga avsnitt "
+"i meddelandet som stadgar att <link linkend=\"fdl-document\">dokumentet</"
+"link> är utgivet under denna licens [det engelska originalet]."
+
+#. (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 "
+"that the <link linkend=\"fdl-document\">Document</link> is released under "
+"this License."
+msgstr ""
+"<quote>Omslagstexterna</quote> är speciella korta ordföljder som är listade "
+"som framsidestexter eller baksidestexter i meddelandet som stadgar att <link "
+"linkend=\"fdl-document\">dokumentet</link> är utgivet under denna licens "
+"[det engelska originalet]."
+
+#. (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 "
+"specification is available to the general public, whose contents can be "
+"viewed and edited directly and straightforwardly with generic text editors "
+"or (for images composed of pixels) generic paint programs or (for drawings) "
+"some widely available drawing editor, and that is suitable for input to text "
+"formatters or for automatic translation to a variety of formats suitable for "
+"input to text formatters. A copy made in an otherwise Transparent file "
+"format whose markup has been designed to thwart or discourage subsequent "
+"modification by readers is not Transparent. A copy that is not "
+"<quote>Transparent</quote> is called <quote>Opaque</quote>."
+msgstr ""
+"En <quote>transparent</quote> kopia av <link linkend=\"fdl-document"
+"\">dokumentet</link> är en maskinläsbar kopia, representerad i ett format "
+"vars specifikation finns tillgänglig för allmänheten, som lämpar sig för att "
+"revidera dokumentet på ett enkelt sätt med generella textredigeringsprogram "
+"eller (för pixelbaserade bilder) generella grafikprogram eller (för "
+"ritningar) något väl tillgängligt ritprogram, och som är passande som indata "
+"till textformaterare eller för automatisk konvertering till en mängd format "
+"som passar som indata till textformaterare. En kopia i ett för övrigt "
+"transparent filformat vars markeringar, eller avsaknad av markeringar, har "
+"ordnats för att hindra eller motverka att vidare förändring vidtas av läsare "
+"är inte transparent. En kopia som inte är <quote>transparent</quote> kallas "
+"<quote>opak</quote>."
+
+#. (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 "
+"a publicly available DTD, and standard-conforming simple HTML designed for "
+"human modification. Opaque formats include PostScript, PDF, proprietary "
+"formats that can be read and edited only by proprietary word processors, "
+"SGML or XML for which the DTD and/or processing tools are not generally "
+"available, and the machine-generated HTML produced by some word processors "
+"for output purposes only."
+msgstr ""
+"Exempel på passande format för transparenta kopior innefattar ren ASCII utan "
+"markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som "
+"använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript "
+"eller PDF utformat för mänsklig förändring. Opaka format innefattar "
+"Postscript, PDF, leverantörsspecifika format som bara kan läsas och editeras "
+"med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/"
+"eller verktyg för behandling inte finns allmänt tillgängliga, och den "
+"maskingenererade HTML som produceras av vissa ordbehandlare enbart avsett "
+"som utdata."
+
+#. (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 "
+"material this License requires to appear in the title page. For works in "
+"formats which do not have any title page as such, <quote>Title Page</quote> "
+"means the text near the most prominent appearance of the work's title, "
+"preceding the beginning of the body of the text."
+msgstr ""
+"<quote>Titelsidan</quote> innebär, för en tryckt bok, titelsidan själv, och "
+"sådana därpå följande sidor som krävs för att göra det material som enligt "
+"denna licens skall synas på titelsidan läsbart. För verk i sådana format som "
+"inte har någon egentlig titelsida, avses med <quote>titelsida</quote> den "
+"text som är närmast den mest framstående förekomsten av verkets titel, "
+"föregående den huvudsakliga textmassan."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:153 C/fdl-appendix.xml:153
msgid "2. VERBATIM COPYING"
msgstr "2. ORDAGRANN KOPIERING"
-#: C/gtk-doc-manual.xml:154(para)
-msgid "You may copy and distribute the <link linkend=\"fdl-document\">Document</link> in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in <link linkend=\"fdl-section3\">section 3</link>."
-msgstr "Du äger kopiera och sprida <link linkend=\"fdl-document\">dokumentet</link> på valfritt medium, antingen kommersiellt eller ideellt, förutsatt att denna licens [det engelska originalet], upphovsrättsklausul, och meddelandet som stadgar att GNU Free Documentation License gäller för dokumentet finns med på alla kopior, och att du inte lägger till några som helst andra villkor än de som ingår i denna licens. Du äger inte vidta tekniska åtgärder för att begränsa eller kontrollera läsande eller vidare kopiering av de kopior du skapar eller sprider. Dock äger du ta emot kompensation i utbyte mot kopior. Om du sprider tillräckligt många kopior måste du också följa villkoren i <link linkend=\"fdl-section3\">paragraf 3</link>."
-
-#: C/gtk-doc-manual.xml:169(para)
-msgid "You may also lend copies, under the same conditions stated above, and you may publicly display copies."
-msgstr "Du äger också låna ut kopior, under samma villkor som ovan, och du äger visa kopior offentligt."
+#. (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 "
+"this License, the copyright notices, and the license notice saying this "
+"License applies to the Document are reproduced in all copies, and that you "
+"add no other conditions whatsoever to those of this License. You may not use "
+"technical measures to obstruct or control the reading or further copying of "
+"the copies you make or distribute. However, you may accept compensation in "
+"exchange for copies. If you distribute a large enough number of copies you "
+"must also follow the conditions in <link linkend=\"fdl-section3\">section 3</"
+"link>."
+msgstr ""
+"Du äger kopiera och sprida <link linkend=\"fdl-document\">dokumentet</link> "
+"på valfritt medium, antingen kommersiellt eller ideellt, förutsatt att denna "
+"licens [det engelska originalet], upphovsrättsklausul, och meddelandet som "
+"stadgar att GNU Free Documentation License gäller för dokumentet finns med "
+"på alla kopior, och att du inte lägger till några som helst andra villkor än "
+"de som ingår i denna licens. Du äger inte vidta tekniska åtgärder för att "
+"begränsa eller kontrollera läsande eller vidare kopiering av de kopior du "
+"skapar eller sprider. Dock äger du ta emot kompensation i utbyte mot kopior. "
+"Om du sprider tillräckligt många kopior måste du också följa villkoren i "
+"<link linkend=\"fdl-section3\">paragraf 3</link>."
+
+#. (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."
+msgstr ""
+"Du äger också låna ut kopior, under samma villkor som ovan, och du äger visa "
+"kopior offentligt."
-#: C/gtk-doc-manual.xml:176(title)
+#. (itstool) path: sect1/title
+#: C/index.docbook:176 C/fdl-appendix.xml:176
msgid "3. COPYING IN QUANTITY"
msgstr "3. OMFATTANDE KOPIERING"
-#: C/gtk-doc-manual.xml:177(para)
-msgid "If you publish printed copies of the <link linkend=\"fdl-document\">Document</link> numbering more than 100, and the Document's license notice requires <link linkend=\"fdl-cover-texts\">Cover Texts</link>, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the <link linkend=\"fdl-document\">Document</link> and satisfy these conditions, can be treated as verbatim copying in other respects."
-msgstr "Om du publicerar tryckta kopior (eller kopior i medier som normalt har tryckta omslag) av <link linkend=\"fdl-document\">dokumentet</link>, i en upplaga överstigande 100 exemplar, och dokumentets licensmeddelande kräver <link linkend=\"fdl-cover-texts\">omslagstexter</link>, så måste du förse kopiorna med omslag som, klart och tydligt, visar alla omslagstexter: framsidestexter på framsidan och baksidestexter på baksidan. Båda omslagen måste klart och tydligt identifiera dig som utgivare av dessa kopior. Framsidan måste presentera dokumentets hela titel, med alla ord i titeln lika framträdande och synliga. Du äger lägga till ytterligare stoff på omslagen. Kopiering med förändringar gjorda bara på omslaget, så länge som de bevarar <link linkend=\"fdl-document\">dokumentets</link> titel och i övrigt uppfyller dessa krav kan anses vara ordagrann kopiering i andra avseenden."
-
-#: C/gtk-doc-manual.xml:195(para)
-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 actual cover, and continue the rest onto adjacent pages."
-msgstr "Om de obligatoriska texterna för något omslag är för omfattande för att rymmas i läsbart skick skall du placera de första (så många som får plats) på det egentliga omslaget, och fortsätta med resten på de direkt intilliggande sidorna."
-
-#: C/gtk-doc-manual.xml:202(para)
-msgid "If you publish or distribute <link linkend=\"fdl-transparent\">Opaque</link> copies of the <link linkend=\"fdl-document\">Document</link> numbering more than 100, you must either include a machine-readable <link linkend=\"fdl-transparent\">Transparent</link> copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public."
-msgstr "Om du publicerar <link linkend=\"fdl-transparent\">opaka</link> kopior av <link linkend=\"fdl-document\">dokumentet</link> i upplagor om mer än 100, måste du antingen bifoga en maskinläsbar <link linkend=\"fdl-transparent\">transparent</link> kopia med varje opak kopia, eller ange i eller med varje opak kopia en nätverksadress som är tillgänglig för den allmänna nätverksanvändande massan där man, med öppet standardiserade protokoll, kan ladda ner en komplett transparent kopia av dokumentet, utan extra material. Om du väljer det senare alternativet, måste du vidta skäliga åtgärder, när du börjar sprida opaka kopior i kvantitet, för att denna transparenta kopia skall förbli tillgänglig på angivna platsen till åtminstone ett år efter den sista gången du spred en opak kopia (direkt eller via ombud eller återförsäljare) av den utgåvan till allmänheten."
-
-#: C/gtk-doc-manual.xml:222(para)
-msgid "It is requested, but not required, that you contact the authors of the <link linkend=\"fdl-document\">Document</link> well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document."
-msgstr "Det är önskvärt, men inte ett krav, att du kontaktar författarna till <link linkend=\"fdl-document\">dokumentet</link> i god tid innan du sprider något större antal kopior, för att ge dem en chans att förse dig med en uppdaterad version av dokumentet."
+#. (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 "
+"notice requires <link linkend=\"fdl-cover-texts\">Cover Texts</link>, you "
+"must enclose the copies in covers that carry, clearly and legibly, all these "
+"Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on "
+"the back cover. Both covers must also clearly and legibly identify you as "
+"the publisher of these copies. The front cover must present the full title "
+"with all words of the title equally prominent and visible. You may add other "
+"material on the covers in addition. Copying with changes limited to the "
+"covers, as long as they preserve the title of the <link linkend=\"fdl-"
+"document\">Document</link> and satisfy these conditions, can be treated as "
+"verbatim copying in other respects."
+msgstr ""
+"Om du publicerar tryckta kopior (eller kopior i medier som normalt har "
+"tryckta omslag) av <link linkend=\"fdl-document\">dokumentet</link>, i en "
+"upplaga överstigande 100 exemplar, och dokumentets licensmeddelande kräver "
+"<link linkend=\"fdl-cover-texts\">omslagstexter</link>, så måste du förse "
+"kopiorna med omslag som, klart och tydligt, visar alla omslagstexter: "
+"framsidestexter på framsidan och baksidestexter på baksidan. Båda omslagen "
+"måste klart och tydligt identifiera dig som utgivare av dessa kopior. "
+"Framsidan måste presentera dokumentets hela titel, med alla ord i titeln "
+"lika framträdande och synliga. Du äger lägga till ytterligare stoff på "
+"omslagen. Kopiering med förändringar gjorda bara på omslaget, så länge som "
+"de bevarar <link linkend=\"fdl-document\">dokumentets</link> titel och i "
+"övrigt uppfyller dessa krav kan anses vara ordagrann kopiering i andra "
+"avseenden."
+
+#. (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 "
+"actual cover, and continue the rest onto adjacent pages."
+msgstr ""
+"Om de obligatoriska texterna för något omslag är för omfattande för att "
+"rymmas i läsbart skick skall du placera de första (så många som får plats) "
+"på det egentliga omslaget, och fortsätta med resten på de direkt "
+"intilliggande sidorna."
-#: C/gtk-doc-manual.xml:231(title)
+#. (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 "
+"than 100, you must either include a machine-readable <link linkend=\"fdl-"
+"transparent\">Transparent</link> copy along with each Opaque copy, or state "
+"in or with each Opaque copy a publicly-accessible computer-network location "
+"containing a complete Transparent copy of the Document, free of added "
+"material, which the general network-using public has access to download "
+"anonymously at no charge using public-standard network protocols. If you use "
+"the latter option, you must take reasonably prudent steps, when you begin "
+"distribution of Opaque copies in quantity, to ensure that this Transparent "
+"copy will remain thus accessible at the stated location until at least one "
+"year after the last time you distribute an Opaque copy (directly or through "
+"your agents or retailers) of that edition to the public."
+msgstr ""
+"Om du publicerar <link linkend=\"fdl-transparent\">opaka</link> kopior av "
+"<link linkend=\"fdl-document\">dokumentet</link> i upplagor om mer än 100, "
+"måste du antingen bifoga en maskinläsbar <link linkend=\"fdl-transparent"
+"\">transparent</link> kopia med varje opak kopia, eller ange i eller med "
+"varje opak kopia en nätverksadress som är tillgänglig för den allmänna "
+"nätverksanvändande massan där man, med öppet standardiserade protokoll, "
+"anonymt och utan kostnad kan ladda ner en komplett transparent kopia av "
+"dokumentet, utan extra material. Om du väljer det senare alternativet, måste "
+"du vidta skäliga åtgärder, när du börjar sprida opaka kopior i kvantitet, "
+"för att denna transparenta kopia skall förbli tillgänglig på angivna platsen "
+"till åtminstone ett år efter den sista gången du spred en opak kopia (direkt "
+"eller via ombud eller återförsäljare) av den utgåvan till allmänheten."
+
+#. (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 "
+"large number of copies, to give them a chance to provide you with an updated "
+"version of the Document."
+msgstr ""
+"Det är önskvärt, men inte ett krav, att du kontaktar författarna till <link "
+"linkend=\"fdl-document\">dokumentet</link> i god tid innan du sprider något "
+"större antal kopior, för att ge dem en chans att förse dig med en uppdaterad "
+"version av dokumentet."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:231 C/fdl-appendix.xml:231
msgid "4. MODIFICATIONS"
msgstr "4. FÖRÄNDRINGAR"
-#: C/gtk-doc-manual.xml:232(para)
-msgid "You may copy and distribute a <link linkend=\"fdl-modified\">Modified Version</link> of the <link linkend=\"fdl-document\">Document</link> under the conditions of sections <link linkend=\"fdl-section2\">2</link> and <link linkend=\"fdl-section3\">3</link> above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:"
-msgstr "Du äger kopiera och sprida en <link linkend=\"fdl-modified\">förändrad version</link> av <link linkend=\"fdl-document\">dokumentet</link> under de villkor som beskrivs i paragraf <link linkend=\"fdl-section2\">2</link> och <link linkend=\"fdl-section3\">3</link> av GNU Free Documentation License, förutsatt att du släpper den förändrade versionen under exakt denna licens, och att den förändrade versionen antar dokumentets roll, och således medger spridning och förändring av den förändrade versionen till envar som erhåller en kopia av den. Utöver detta måste du göra följande med den ändrade versionen:"
-
-#: C/gtk-doc-manual.xml:248(title)
+#. (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 "
+"the conditions of sections <link linkend=\"fdl-section2\">2</link> and <link "
+"linkend=\"fdl-section3\">3</link> above, provided that you release the "
+"Modified Version under precisely this License, with the Modified Version "
+"filling the role of the Document, thus licensing distribution and "
+"modification of the Modified Version to whoever possesses a copy of it. In "
+"addition, you must do these things in the Modified Version:"
+msgstr ""
+"Du äger kopiera och sprida en <link linkend=\"fdl-modified\">förändrad "
+"version</link> av <link linkend=\"fdl-document\">dokumentet</link> under de "
+"villkor som beskrivs i paragraf <link linkend=\"fdl-section2\">2</link> och "
+"<link linkend=\"fdl-section3\">3</link> av GNU Free Documentation License, "
+"förutsatt att du släpper den förändrade versionen under exakt denna licens, "
+"och att den förändrade versionen antar dokumentets roll, och således medger "
+"spridning och förändring av den förändrade versionen till envar som erhåller "
+"en kopia av den. Utöver detta måste du göra följande med den ändrade "
+"versionen:"
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:248 C/fdl-appendix.xml:248
msgid "A"
msgstr "A"
-#: C/gtk-doc-manual.xml:249(para)
-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-document\">Document</link>, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission."
-msgstr "På <link linkend=\"fdl-title-page\">titelsidan</link> (och omslagen om det finns några) använda en titel skild från den som [original]<link linkend=\"fdl-document\">dokumentet</link> har, och skild från tidigare versioners titel (som skall, om det finns några, finnas listade i historikavsnittet i dokumentet). Du äger använda samma titel som det föregående dokumentet om den ursprungliga utgivaren ger sitt tillstånd."
-
-#: C/gtk-doc-manual.xml:264(title)
+#. (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-"
+"document\">Document</link>, and from those of previous versions (which "
+"should, if there were any, be listed in the History section of the "
+"Document). You may use the same title as a previous version if the original "
+"publisher of that version gives permission."
+msgstr ""
+"På <link linkend=\"fdl-title-page\">titelsidan</link> (och omslagen om det "
+"finns några) använda en titel skild från den som [original]<link linkend="
+"\"fdl-document\">dokumentet</link> har, och skild från tidigare versioners "
+"titel (som skall, om det finns några, finnas listade i historikavsnittet i "
+"dokumentet). Du äger använda samma titel som det föregående dokumentet om "
+"den ursprungliga utgivaren ger sitt tillstånd."
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:264 C/fdl-appendix.xml:264
msgid "B"
msgstr "B"
-#: C/gtk-doc-manual.xml:265(para)
-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 modifications in the <link linkend=\"fdl-modified\">Modified Version</link>, together with at least five of the principal authors of the <link linkend=\"fdl-document\">Document</link> (all of its principal authors, if it has less than five)."
-msgstr "Lista på <link linkend=\"fdl-title-page\">titelsidan</link>, som författare, en eller flera personer eller juridiska personer som ansvarat för förändringarna i den <link linkend=\"fdl-modified\">förändrade versionen</link>, tillsammans med minst fem av de huvudsakliga författarna av <link linkend=\"fdl-document\">dokumentet</link> (alla dess huvudsakliga författare, om det har mindre än fem)."
-
-#: C/gtk-doc-manual.xml:279(title)
+#. (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 "
+"modifications in the <link linkend=\"fdl-modified\">Modified Version</link>, "
+"together with at least five of the principal authors of the <link linkend="
+"\"fdl-document\">Document</link> (all of its principal authors, if it has "
+"less than five)."
+msgstr ""
+"Lista på <link linkend=\"fdl-title-page\">titelsidan</link>, som författare, "
+"en eller flera personer eller juridiska personer som ansvarat för "
+"förändringarna i den <link linkend=\"fdl-modified\">förändrade versionen</"
+"link>, tillsammans med minst fem av de huvudsakliga författarna av <link "
+"linkend=\"fdl-document\">dokumentet</link> (alla dess huvudsakliga "
+"författare, om det har mindre än fem)."
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:279 C/fdl-appendix.xml:279
msgid "C"
msgstr "C"
-#: C/gtk-doc-manual.xml:280(para)
-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>, as the publisher."
-msgstr "Ange namnet på utgivaren av den <link linkend=\"fdl-modified\">förändrade versionen</link>, som utgivare, på <link linkend=\"fdl-title-page\">titelsidan</link>."
+#. (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>, "
+"as the publisher."
+msgstr ""
+"Ange namnet på utgivaren av den <link linkend=\"fdl-modified\">förändrade "
+"versionen</link>, som utgivare, på <link linkend=\"fdl-title-page"
+"\">titelsidan</link>."
-#: C/gtk-doc-manual.xml:291(title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:291 C/fdl-appendix.xml:291
msgid "D"
msgstr "D"
-#: C/gtk-doc-manual.xml:292(para)
-msgid "Preserve all the copyright notices of the <link linkend=\"fdl-document\">Document</link>."
-msgstr "Bibehålla <link linkend=\"fdl-document\">dokumentets</link> alla upphovsrättsklausuler."
+#. (itstool) path: formalpara/para
+#: C/index.docbook:292
+msgid ""
+"Preserve all the copyright notices of the <link linkend=\"fdl-document"
+"\">Document</link>."
+msgstr ""
+"Bibehålla <link linkend=\"fdl-document\">dokumentets</link> alla "
+"upphovsrättsklausuler."
-#: C/gtk-doc-manual.xml:301(title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:301 C/fdl-appendix.xml:301
msgid "E"
msgstr "E"
-#: C/gtk-doc-manual.xml:302(para)
-msgid "Add an appropriate copyright notice for your modifications adjacent to the other copyright notices."
-msgstr "Lägga till en upphovsrättsklausul för dina förändringar angränsande till de andra upphovsrättsklausulerna."
+#. (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."
+msgstr ""
+"Lägga till en upphovsrättsklausul för dina förändringar angränsande till de "
+"andra upphovsrättsklausulerna."
-#: C/gtk-doc-manual.xml:311(title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:311 C/fdl-appendix.xml:311
msgid "F"
msgstr "F"
-#: C/gtk-doc-manual.xml:312(para)
-msgid "Include, immediately after the copyright notices, a license notice giving the public permission to use the <link linkend=\"fdl-modified\">Modified Version</link> under the terms of this License, in the form shown in the Addendum below."
-msgstr "Direkt efter upphovsrättsklausulerna innefatta ett meddelande som ger allmänheten tillstånd att använda den <link linkend=\"fdl-modified\">förändrade versionen</link> under villkoren i denna licens [det engelska originalet] i den form som visas i Tillägg nedan."
-
-#: C/gtk-doc-manual.xml:324(title)
+#. (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</link> under the terms of this License, in the form shown in the "
+"Addendum below."
+msgstr ""
+"Direkt efter upphovsrättsklausulerna innefatta ett meddelande som ger "
+"allmänheten tillstånd att använda den <link linkend=\"fdl-modified"
+"\">förändrade versionen</link> under villkoren i denna licens [det engelska "
+"originalet] i den form som visas i Tillägg nedan."
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:324 C/fdl-appendix.xml:324
msgid "G"
msgstr "G"
-#: C/gtk-doc-manual.xml:325(para)
-msgid "Preserve in that license notice the full lists of <link linkend=\"fdl-invariant\"> Invariant Sections</link> and required <link linkend=\"fdl-cover-texts\">Cover Texts</link> given in the <link linkend=\"fdl-document\">Document's</link> license notice."
-msgstr "I meddelandet om licensen bevara den fullständiga listan över <link linkend=\"fdl-invariant\">oföränderliga avsnitt</link> och obligatoriska <link linkend=\"fdl-cover-texts\">omslagstexter</link> som finns i <link linkend=\"fdl-document\">dokumentets</link> meddelande om licensen."
-
-#: C/gtk-doc-manual.xml:337(title)
+#. (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-"
+"cover-texts\">Cover Texts</link> given in the <link linkend=\"fdl-document"
+"\">Document's</link> license notice."
+msgstr ""
+"I meddelandet om licensen bevara den fullständiga listan över <link linkend="
+"\"fdl-invariant\">oföränderliga avsnitt</link> och obligatoriska <link "
+"linkend=\"fdl-cover-texts\">omslagstexter</link> som finns i <link linkend="
+"\"fdl-document\">dokumentets</link> meddelande om licensen."
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:337 C/fdl-appendix.xml:337
msgid "H"
msgstr "H"
-#: C/gtk-doc-manual.xml:338(para)
+#. (itstool) path: formalpara/para
+#: C/index.docbook:338 C/fdl-appendix.xml:338
msgid "Include an unaltered copy of this License."
-msgstr "Inkludera en oförändrad kopia av denna licens [Det är den engelska originalversionen som avses]."
+msgstr ""
+"Inkludera en oförändrad kopia av denna licens [Det är den engelska "
+"originalversionen som avses]."
-#: C/gtk-doc-manual.xml:346(title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:346 C/fdl-appendix.xml:346
msgid "I"
msgstr "I"
-#: C/gtk-doc-manual.xml:347(para)
-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 of the <link linkend=\"fdl-modified\">Modified Version </link>as given on the <link linkend=\"fdl-title-page\">Title Page</link>. If there is no section entitled <quote>History</quote> in the <link linkend=\"fdl-document\">Document</link>, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence."
-msgstr "Bevara avsnittet med titeln <quote>historik</quote> (History), bevara dess titel och lägg i avsnittet till en post med åtminstone titeln, året, nya författare och utgivaren av den <link linkend=\"fdl-modified\">förändrade versionen</link> så som angivet på <link linkend=\"fdl-title-page\">titelsidan</link>. Om det inte finns något avsnitt med titeln <quote>historik</quote> (History) i <link linkend=\"fdl-document\">dokumentet</link> så skapa en med titeln, året, författare och utgivaren av dokumentet så som det står på [original]dokumentets titelsida. Lägg sedan till en post som beskriver den förändrade versionen så som beskrivits ovan."
-
-#: C/gtk-doc-manual.xml:365(title)
+#. (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 "
+"of the <link linkend=\"fdl-modified\">Modified Version</link> as given on "
+"the <link linkend=\"fdl-title-page\">Title Page</link>. If there is no "
+"section entitled <quote>History</quote> in the <link linkend=\"fdl-document"
+"\">Document</link>, create one stating the title, year, authors, and "
+"publisher of the Document as given on its Title Page, then add an item "
+"describing the Modified Version as stated in the previous sentence."
+msgstr ""
+"Bevara avsnittet med titeln <quote>historik</quote> (History), bevara dess "
+"titel och lägg i avsnittet till en post med åtminstone titeln, året, nya "
+"författare och utgivaren av den <link linkend=\"fdl-modified\">förändrade "
+"versionen</link> så som angivet på <link linkend=\"fdl-title-page"
+"\">titelsidan</link>. Om det inte finns något avsnitt med titeln "
+"<quote>historik</quote> (History) i <link linkend=\"fdl-document"
+"\">dokumentet</link> så skapa en med titeln, året, författare och utgivaren "
+"av dokumentet så som det står på [original]dokumentets titelsida. Lägg sedan "
+"till en post som beskriver den förändrade versionen så som beskrivits ovan."
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:365 C/fdl-appendix.xml:365
msgid "J"
msgstr "J"
-#: C/gtk-doc-manual.xml:366(para)
-msgid "Preserve the network location, if any, given in the <link linkend=\"fdl-document\">Document</link> for public access to a <link linkend=\"fdl-transparent\">Transparent</link> copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the <quote>History</quote> section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission."
-msgstr "Bevara den nätverksadress, om det finns någon, angiven i <link linkend=\"fdl-document\">dokumentet</link> till den allmänt tillgängliga <link linkend=\"fdl-transparent\">transparenta</link> kopian av dokumentet, och likaså nätverksadresserna till de föregående versioner som dokumentet baseras på. Dessa får placeras i avsnittet <quote>historik</quote> (History). Du äger utelämna en nätverksadress för ett verk som är publicerat mer än fyra år före dokumentet självt, eller om den ursprunglige utgivaren vars verk nätverksadressen hänvisar till ger sitt tillstånd."
-
-#: C/gtk-doc-manual.xml:383(title)
+#. (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-"
+"transparent\">Transparent</link> copy of the Document, and likewise the "
+"network locations given in the Document for previous versions it was based "
+"on. These may be placed in the <quote>History</quote> section. You may omit "
+"a network location for a work that was published at least four years before "
+"the Document itself, or if the original publisher of the version it refers "
+"to gives permission."
+msgstr ""
+"Bevara den nätverksadress, om det finns någon, angiven i <link linkend=\"fdl-"
+"document\">dokumentet</link> till den allmänt tillgängliga <link linkend="
+"\"fdl-transparent\">transparenta</link> kopian av dokumentet, och likaså "
+"nätverksadresserna till de föregående versioner som dokumentet baseras på. "
+"Dessa får placeras i avsnittet <quote>historik</quote> (History). Du äger "
+"utelämna en nätverksadress för ett verk som är publicerat mer än fyra år "
+"före dokumentet självt, eller om den ursprunglige utgivaren vars verk "
+"nätverksadressen hänvisar till ger sitt tillstånd."
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:383 C/fdl-appendix.xml:383
msgid "K"
msgstr "K"
-#: C/gtk-doc-manual.xml:384(para)
-msgid "In any section entitled <quote>Acknowledgements</quote> or <quote>Dedications</quote>, preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein."
-msgstr "För alla avsnitt med titlarna <quote>tillkännagivanden</quote> (Acknowledgements) eller <quote>dedikationer</quote> (Dedications), bevara titeln på avsnittet, och bevara allt innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda av varje bidragare."
-
-#: C/gtk-doc-manual.xml:396(title)
+#. (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 "
+"the section all the substance and tone of each of the contributor "
+"acknowledgements and/or dedications given therein."
+msgstr ""
+"För alla avsnitt med titlarna <quote>tillkännagivanden</quote> "
+"(Acknowledgements) eller <quote>dedikationer</quote> (Dedications), bevara "
+"titeln på avsnittet, och bevara allt innehåll och prägel på alla "
+"tillkännagivanden och/eller dedikationer gjorda av varje bidragsgivare."
+
+#. (itstool) path: formalpara/title
+#: C/index.docbook:396 C/fdl-appendix.xml:396
msgid "L"
msgstr "L"
-#: C/gtk-doc-manual.xml:397(para)
-msgid "Preserve all the <link linkend=\"fdl-invariant\">Invariant Sections</link> of the <link linkend=\"fdl-document\">Document</link>, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles."
-msgstr "Bevara alla <link linkend=\"fdl-invariant\">oföränderliga avsnitt</link> i <link linkend=\"fdl-document\">dokumentet</link> oförändrade till text och titel. Avsnittsnummer eller motsvarande anses inte tillhöra avsnittets titel."
+#. (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 "
+"text and in their titles. Section numbers or the equivalent are not "
+"considered part of the section titles."
+msgstr ""
+"Bevara alla <link linkend=\"fdl-invariant\">oföränderliga avsnitt</link> i "
+"<link linkend=\"fdl-document\">dokumentet</link> oförändrade till text och "
+"titel. Avsnittsnummer eller motsvarande anses inte tillhöra avsnittets titel."
-#: C/gtk-doc-manual.xml:409(title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:409 C/fdl-appendix.xml:409
msgid "M"
msgstr "M"
-#: C/gtk-doc-manual.xml:410(para)
-msgid "Delete any section entitled <quote>Endorsements</quote>. Such a section may not be included in the <link linkend=\"fdl-modified\">Modified Version</link>."
-msgstr "Radera varje avsnitt med titeln <quote>endossering</quote> (Endorsements). Ett sådant avsnitt får inte inkluderas i en <link linkend=\"fdl-modified\">förändrad version</link>."
+#. (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</"
+"link>."
+msgstr ""
+"Radera varje avsnitt med titeln <quote>endossering</quote> (Endorsements). "
+"Ett sådant avsnitt får inte inkluderas i en <link linkend=\"fdl-modified"
+"\">förändrad version</link>."
-#: C/gtk-doc-manual.xml:421(title)
+#. (itstool) path: formalpara/title
+#: C/index.docbook:421 C/fdl-appendix.xml:421
msgid "N"
msgstr "N"
-#: C/gtk-doc-manual.xml:422(para)
-msgid "Do not retitle any existing section as <quote>Endorsements</quote> or to conflict in title with any <link linkend=\"fdl-invariant\">Invariant Section</link>."
-msgstr "Inte byta titel på något existerande avsnitt så att det blir <quote>endossering</quote> (Endorsements) eller så att titeln kan förväxlas med något <link linkend=\"fdl-invariant\">oföränderligt avsnitt</link>."
-
-#: C/gtk-doc-manual.xml:432(para)
-msgid "If the <link linkend=\"fdl-modified\">Modified Version</link> includes new front-matter sections or appendices that qualify as <link linkend=\"fdl-secondary\">Secondary Sections</link> and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of <link linkend=\"fdl-invariant\">Invariant Sections</link> in the Modified Version's license notice. These titles must be distinct from any other section titles."
-msgstr "Om den <link linkend=\"fdl-modified\">förändrade versionen</link> innehåller nya framsidestexter eller bilagor som är att anses som <link linkend=\"fdl-secondary\">sekundära avsnitt</link> och inte innehåller något material kopierat från dokumentet, så äger du, om du vill, benämna några eller samtliga av dessa som oföränderliga. För att göra detta, lägg deras titlar till listan över <link linkend=\"fdl-invariant\">oföränderliga avsnitt</link> i den förändrade versionens licensmeddelande. Dessa titlar måste vara skilda från alla andra avsnitts titlar."
-
-#: C/gtk-doc-manual.xml:444(para)
-msgid "You may add a section entitled <quote>Endorsements</quote>, provided it contains nothing but endorsements of your <link linkend=\"fdl-modified\">Modified Version</link> by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard."
-msgstr "Du äger lägga till ett avsnitt med titeln <quote>endossering</quote> (Endorsements), förutsatt att det inte innehåller något annat än endosseringar för din <link linkend=\"fdl-modified\">förändrade version</link> från olika aktörer -- till exempel, meddelanden om utförd korrekturläsning eller att texten har godkänts av en organisation som en officiell definition av en standard."
-
-#: C/gtk-doc-manual.xml:453(para)
-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 linkend=\"fdl-cover-texts\">Back-Cover Text</link>, to the end of the list of <link linkend=\"fdl-cover-texts\">Cover Texts</link> in the <link linkend=\"fdl-modified\">Modified Version</link>. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the <link linkend=\"fdl-document\">Document</link> already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one."
-msgstr "Du äger lägga till ett textavsnitt på upp till fem ord som <link linkend=\"fdl-cover-texts\">framsidestext</link>, och ett textavsnitt på upp till 25 ord som baksidestext i listan över <link linkend=\"fdl-cover-texts\">omslagstexter</link> i den <link linkend=\"fdl-modified\">förändrade versionen</link>. Bara ett textavsnitt med framsidestexter och ett med baksidestexter får läggas till av (eller genom försorg av) en enda juridisk person. Om <link linkend=\"fdl-document\">dokumentet</link> redan innehåller en omlagstext för något av omslagen, tidigare tillagd av dig eller genom försorg av samma juridiska person som du företräder, äger du inte lägga till en till, men du äger ändra den gamla med tillstånd från den tidigare utgivaren som lade till den förra."
-
-#: C/gtk-doc-manual.xml:470(para)
-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 for publicity for or to assert or imply endorsement of any <link linkend=\"fdl-modified\">Modified Version </link>."
-msgstr "Författaren (författarna) och utgivaren (utgivarna) av <link linkend=\"fdl-document\">dokumentet</link> ger inte via denna licens sitt tillstånd att använda sina namn för publicitet eller för att lägga till eller antyda endossering av någon <link linkend=\"fdl-modified\">förändrad version</link>."
+#. (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 "
+"Section</link>."
+msgstr ""
+"Inte byta titel på något existerande avsnitt så att det blir "
+"<quote>endossering</quote> (Endorsements) eller så att titeln kan förväxlas "
+"med något <link linkend=\"fdl-invariant\">oföränderligt avsnitt</link>."
-#: C/gtk-doc-manual.xml:480(title)
+#. (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-"
+"secondary\">Secondary Sections</link> and contain no material copied from "
+"the Document, you may at your option designate some or all of these sections "
+"as invariant. To do this, add their titles to the list of <link linkend="
+"\"fdl-invariant\">Invariant Sections</link> in the Modified Version's "
+"license notice. These titles must be distinct from any other section titles."
+msgstr ""
+"Om den <link linkend=\"fdl-modified\">förändrade versionen</link> innehåller "
+"nya framsidestexter eller bilagor som är att anses som <link linkend=\"fdl-"
+"secondary\">sekundära avsnitt</link> och inte innehåller något material "
+"kopierat från dokumentet, så äger du, om du vill, benämna några eller "
+"samtliga av dessa som oföränderliga. För att göra detta, lägg deras titlar "
+"till listan över <link linkend=\"fdl-invariant\">oföränderliga avsnitt</"
+"link> i den förändrade versionens licensmeddelande. Dessa titlar måste vara "
+"skilda från alla andra avsnitts titlar."
+
+#. (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"
+"\">Modified Version</link> by various parties--for example, statements of "
+"peer review or that the text has been approved by an organization as the "
+"authoritative definition of a standard."
+msgstr ""
+"Du äger lägga till ett avsnitt med titeln <quote>endossering</quote> "
+"(Endorsements), förutsatt att det inte innehåller något annat än "
+"endosseringar för din <link linkend=\"fdl-modified\">förändrade version</"
+"link> från olika aktörer -- till exempel, meddelanden om utförd "
+"korrekturläsning eller att texten har godkänts av en organisation som en "
+"officiell definition av en standard."
+
+#. (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 "
+"linkend=\"fdl-cover-texts\">Back-Cover Text</link>, to the end of the list "
+"of <link linkend=\"fdl-cover-texts\">Cover Texts</link> in the <link linkend="
+"\"fdl-modified\">Modified Version</link>. Only one passage of Front-Cover "
+"Text and one of Back-Cover Text may be added by (or through arrangements "
+"made by) any one entity. If the <link linkend=\"fdl-document\">Document</"
+"link> already includes a cover text for the same cover, previously added by "
+"you or by arrangement made by the same entity you are acting on behalf of, "
+"you may not add another; but you may replace the old one, on explicit "
+"permission from the previous publisher that added the old one."
+msgstr ""
+"Du äger lägga till ett textavsnitt på upp till fem ord som <link linkend="
+"\"fdl-cover-texts\">framsidestext</link>, och ett textavsnitt på upp till 25 "
+"ord som <link linkend=\"fdl-cover-texts\">baksidestext</link> i listan över "
+"<link linkend=\"fdl-cover-texts\">omslagstexter</link> i den <link linkend="
+"\"fdl-modified\">förändrade versionen</link>. Bara ett textavsnitt med "
+"framsidestexter och ett med baksidestexter får läggas till av (eller genom "
+"försorg av) en enda juridisk person. Om <link linkend=\"fdl-document"
+"\">dokumentet</link> redan innehåller en omslagstext för något av omslagen, "
+"tidigare tillagd av dig eller genom försorg av samma juridiska person som du "
+"företräder, äger du inte lägga till en till, men du äger ändra den gamla med "
+"tillstånd från den tidigare utgivaren som lade till den förra."
+
+#. (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 "
+"for publicity for or to assert or imply endorsement of any <link linkend="
+"\"fdl-modified\">Modified Version </link>."
+msgstr ""
+"Författaren (författarna) och utgivaren (utgivarna) av <link linkend=\"fdl-"
+"document\">dokumentet</link> ger inte via denna licens sitt tillstånd att "
+"använda sina namn för publicitet eller för att lägga till eller antyda "
+"endossering av någon <link linkend=\"fdl-modified\">förändrad version</link>."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:480 C/fdl-appendix.xml:480
msgid "5. COMBINING DOCUMENTS"
msgstr "5. KOMBINERA DOKUMENT"
-#: C/gtk-doc-manual.xml:481(para)
-msgid "You may combine the <link linkend=\"fdl-document\">Document</link> with other documents released under this License, under the terms defined in <link linkend=\"fdl-section4\">section 4</link> above for modified versions, provided that you include in the combination all of the <link linkend=\"fdl-invariant\">Invariant Sections</link> of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice."
-msgstr "Du äger kombinera <link linkend=\"fdl-document\">dokumentet</link> med andra dokument som är utgivna under denna licens, under de villkor som definieras i <link linkend=\"fdl-section4\">paragraf 4</link> av GNU Free Documentation License för förändrade versioner, förutsatt att du, i det kombinerade dokumentet, innefattar alla <link linkend=\"fdl-invariant\">oföränderliga avsnitt</link> från originaldokumenten, omodifierade, och listar dem som oföränderliga avsnitt i ditt kombinerade verk i dess licensklausul, och att du bevarar alla deras garantiavsägelseklausuler."
-
-#: C/gtk-doc-manual.xml:492(para)
-msgid "The combined work need only contain one copy of this License, and multiple identical <link linkend=\"fdl-invariant\">Invariant Sections</link> may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work."
-msgstr "Det kombinerade verket behöver bara innehålla en enstaka kopia av denna licens [engelska originalversionen], och flera identiska <link linkend=\"fdl-invariant\">oföränderliga stycken</link> kan ersättas med en kopia. Om det finns flera oföränderliga stycken med samma namn men olika innehåll, se till att titeln på varje sådant avsnitt är unik genom att i slutet på den, inom parentes, lägga till namnet på den ursprunglige författaren eller utgivaren av det avsnittet om dessa är kända, annars ett unikt nummer. Gör samma justeringar av titlarna i listan över oföränderliga avsnitt i licensklausulen i det kombinerade verket."
-
-#: C/gtk-doc-manual.xml:505(para)
-msgid "In the combination, you must combine any sections entitled <quote>History</quote> in the various original documents, forming one section entitled <quote>History</quote>; likewise combine any sections entitled <quote>Acknowledgements</quote>, and any sections entitled <quote>Dedications</quote>. You must delete all sections entitled <quote>Endorsements.</quote>"
-msgstr "I det kombinerade verket måste du kombinera alla avsnitt med titlarna <quote>historik</quote> (History) i de ursprungliga dokumenten, till ett avsnitt med titeln <quote>historik</quote> (History); på samma sätt skall alla avsnitt med titlarna <quote>tillkännagivanden</quote> (Acknowledgements), alla avsnitt med titlarna <quote>dedikationer</quote> (Dedications) kombineras. Du måste ta bort alla avsnitt med titlarna <quote>endossering</quote> (Endorsements)."
-
-#: C/gtk-doc-manual.xml:516(title)
+#. (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 "
+"<link linkend=\"fdl-section4\">section 4</link> above for modified versions, "
+"provided that you include in the combination all of the <link linkend=\"fdl-"
+"invariant\">Invariant Sections</link> of all of the original documents, "
+"unmodified, and list them all as Invariant Sections of your combined work in "
+"its license notice."
+msgstr ""
+"Du äger kombinera <link linkend=\"fdl-document\">dokumentet</link> med andra "
+"dokument som är utgivna under denna licens, under de villkor som definieras "
+"i <link linkend=\"fdl-section4\">paragraf 4</link> av GNU Free Documentation "
+"License för förändrade versioner, förutsatt att du, i det kombinerade "
+"dokumentet, innefattar alla <link linkend=\"fdl-invariant\">oföränderliga "
+"avsnitt</link> från originaldokumenten, omodifierade, och listar dem som "
+"oföränderliga avsnitt i ditt kombinerade verk i dess licensklausul, och att "
+"du bevarar alla deras garantiavsägelseklausuler."
+
+#. (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 "
+"replaced with a single copy. If there are multiple Invariant Sections with "
+"the same name but different contents, make the title of each such section "
+"unique by adding at the end of it, in parentheses, the name of the original "
+"author or publisher of that section if known, or else a unique number. Make "
+"the same adjustment to the section titles in the list of Invariant Sections "
+"in the license notice of the combined work."
+msgstr ""
+"Det kombinerade verket behöver bara innehålla en enstaka kopia av denna "
+"licens [engelska originalversionen], och flera identiska <link linkend=\"fdl-"
+"invariant\">oföränderliga stycken</link> kan ersättas med en kopia. Om det "
+"finns flera oföränderliga stycken med samma namn men olika innehåll, se till "
+"att titeln på varje sådant avsnitt är unik genom att i slutet på den, inom "
+"parentes, lägga till namnet på den ursprunglige författaren eller utgivaren "
+"av det avsnittet om dessa är kända, annars ett unikt nummer. Gör samma "
+"justeringar av titlarna i listan över oföränderliga avsnitt i "
+"licensklausulen i det kombinerade verket."
+
+#. (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>History</quote>; likewise combine any sections entitled "
+"<quote>Acknowledgements</quote>, and any sections entitled "
+"<quote>Dedications</quote>. You must delete all sections entitled "
+"<quote>Endorsements.</quote>"
+msgstr ""
+"I det kombinerade verket måste du kombinera alla avsnitt med titlarna "
+"<quote>historik</quote> (History) i de ursprungliga dokumenten, till ett "
+"avsnitt med titeln <quote>historik</quote> (History); på samma sätt skall "
+"alla avsnitt med titlarna <quote>tillkännagivanden</quote> "
+"(Acknowledgements), alla avsnitt med titlarna <quote>dedikationer</quote> "
+"(Dedications) kombineras. Du måste ta bort alla avsnitt med titlarna "
+"<quote>endossering</quote> (Endorsements)."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:516 C/fdl-appendix.xml:516
msgid "6. COLLECTIONS OF DOCUMENTS"
msgstr "6. SAMLINGAR AV DOKUMENT"
-#: C/gtk-doc-manual.xml:517(para)
-msgid "You may make a collection consisting of the <link linkend=\"fdl-document\">Document</link> and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects."
-msgstr "Du äger skapa en samling bestående av <link linkend=\"fdl-document\">dokumentet</link> och andra dokument som är släppta under GNU Free Documentation License, och ersätta individuella kopior i dokumenten av denna licens med en enda kopia [av den engelska originalversionen] som inkluderas i samlingen, förutsatt att du följer villkoren för ordagrann kopiering i denna licens för varje inkluderat dokument i alla andra avseenden."
-
-#: C/gtk-doc-manual.xml:527(para)
-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."
-msgstr "Du äger lyfta ut ett dokument från en sådan samling, och sprida det enskilt under GNU Free Documentation License, förutsatt att du lägger till en kopia av denna licens [den engelska originalversionen] i det utlyfta dokumentet, och följer villkoren för ordagrann kopiering i denna licens för det utlyfta dokumentet i alla andra avseenden."
-
-#: C/gtk-doc-manual.xml:537(title)
+#. (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 "
+"replace the individual copies of this License in the various documents with "
+"a single copy that is included in the collection, provided that you follow "
+"the rules of this License for verbatim copying of each of the documents in "
+"all other respects."
+msgstr ""
+"Du äger skapa en samling bestående av <link linkend=\"fdl-document"
+"\">dokumentet</link> och andra dokument som är släppta under GNU Free "
+"Documentation License, och ersätta individuella kopior i dokumenten av denna "
+"licens med en enda kopia [av den engelska originalversionen] som inkluderas "
+"i samlingen, förutsatt att du följer villkoren för ordagrann kopiering i "
+"denna licens för varje inkluderat dokument i alla andra avseenden."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:527 C/fdl-appendix.xml:527
+msgid ""
+"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."
+msgstr ""
+"Du äger lyfta ut ett dokument från en sådan samling, och sprida det enskilt "
+"under GNU Free Documentation License, förutsatt att du lägger till en kopia "
+"av denna licens [den engelska originalversionen] i det utlyfta dokumentet, "
+"och följer villkoren för ordagrann kopiering i denna licens för det utlyfta "
+"dokumentet i alla andra avseenden."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:537 C/fdl-appendix.xml:537
msgid "7. AGGREGATION WITH INDEPENDENT WORKS"
msgstr "7. SAMMANSLAGNING MED OBEROENDE VERK"
-#: C/gtk-doc-manual.xml:538(para)
-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 a volume of a storage or distribution medium, does not as a whole count as a <link linkend=\"fdl-modified\">Modified Version</link> of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an <quote>aggregate</quote>, and this License does not apply to the other self-contained works thus compiled with the Document , on account of their being thus compiled, if they are not themselves derivative works of the Document. If the <link linkend=\"fdl-cover-texts\">Cover Text</link> requirement of <link linkend=\"fdl-section3\">section 3</link> is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate."
-msgstr "En samling av <link linkend=\"fdl-document\">dokumentet</link> eller av dess derivat med andra separata och oberoende dokument eller verk, på eller i en lagringsvolym eller ett spridningsmedium, kallas för en <quote>sammanslagning</quote> om den sammanslagna upphovsrätten inte används för att begränsa samlingens användares rättigheter som de enskilda dokumenten medger. När dokumentet ingår i en sådan sammanslagning, gäller inte denna licens de andra verken i samlingen som inte själva är deriverat av dokumentet. Om kravet på <link linkend=\"fdl-cover-texts\">omslagstexter</link> enligt <link linkend=\"fdl-section3\">paragraf 3</link> är tillämpligt på dessa kopior av dokumentet, så kan dokumentets omslagstexter, om dokumentet utgör mindre än hälften av hela samlingen, placeras på det omslag som omger dokumentet inuti samlingen, eller den elektroniska motsvarigheten till omslag om dokumentet är i elektronisk form. Annars måste de synas på det omslag som omger hela samlingen."
-
-#: C/gtk-doc-manual.xml:561(title)
+#. (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 "
+"a volume of a storage or distribution medium, does not as a whole count as a "
+"<link linkend=\"fdl-modified\">Modified Version</link> of the Document, "
+"provided no compilation copyright is claimed for the compilation. Such a "
+"compilation is called an <quote>aggregate</quote>, and this License does not "
+"apply to the other self-contained works thus compiled with the Document , on "
+"account of their being thus compiled, if they are not themselves derivative "
+"works of the Document. If the <link linkend=\"fdl-cover-texts\">Cover Text</"
+"link> requirement of <link linkend=\"fdl-section3\">section 3</link> is "
+"applicable to these copies of the Document, then if the Document is less "
+"than one quarter of the entire aggregate, the Document's Cover Texts may be "
+"placed on covers that surround only the Document within the aggregate. "
+"Otherwise they must appear on covers around the whole aggregate."
+msgstr ""
+"En samling av <link linkend=\"fdl-document\">dokumentet</link> eller av dess "
+"derivat med andra separata och oberoende dokument eller verk, på eller i en "
+"lagringsvolym eller ett spridningsmedium, kallas för en "
+"<quote>sammanslagning</quote> om den sammanslagna upphovsrätten inte används "
+"för att begränsa samlingens användares rättigheter som de enskilda "
+"dokumenten medger. När dokumentet ingår i en sådan sammanslagning, gäller "
+"inte denna licens de andra verken i samlingen som inte själva är deriverat "
+"av dokumentet. Om kravet på <link linkend=\"fdl-cover-texts\">omslagstexter</"
+"link> enligt <link linkend=\"fdl-section3\">paragraf 3</link> är tillämpligt "
+"på dessa kopior av dokumentet, så kan dokumentets omslagstexter, om "
+"dokumentet utgör mindre än en fjärdedel av hela samlingen, placeras på det "
+"omslag som omger dokumentet inuti samlingen, eller den elektroniska "
+"motsvarigheten till omslag om dokumentet är i elektronisk form. Annars måste "
+"de synas på det omslag som omger hela samlingen."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:561 C/fdl-appendix.xml:561
msgid "8. TRANSLATION"
msgstr "8. ÖVERSÄTTNING"
-#: C/gtk-doc-manual.xml:562(para)
-msgid "Translation is considered a kind of modification, so you may distribute translations of the <link linkend=\"fdl-document\">Document</link> under the terms of <link linkend=\"fdl-section4\">section 4</link>. Replacing <link linkend=\"fdl-invariant\"> Invariant Sections</link> with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail."
-msgstr "Översättning anses vara en sorts förändring, så du äger sprida översättningar av <link linkend=\"fdl-document\">dokumentet</link> enligt de villkor som sätts i <link linkend=\"fdl-section4\">paragraf 4</link>. <link linkend=\"fdl-invariant\">Oföränderliga avsnitt</link> som ersätts med översättningar kräver tillstånd från deras upphovsrättsinnehavare, men du äger inkludera översättningar av alla eller vissa av dessa oföränderliga avsnitt tillsammans med originalversionerna av dessa oföränderliga avsnitt. Du äger inkludera en översättning av denna licens, och alla licensklausuler i dokumentet, och alla garantiavsägelser, förutsatt att du också innefattar den engelska originalversionen av denna licens och originalversionerna av dessa klausuler. Skulle det finnas skillnader mellan översättningen och originalversionen av denna licens eller någon klausul så gäller originalversionen."
-
-#: C/gtk-doc-manual.xml:580(title)
+#. (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 "
+"terms of <link linkend=\"fdl-section4\">section 4</link>. Replacing <link "
+"linkend=\"fdl-invariant\"> Invariant Sections</link> with translations "
+"requires special permission from their copyright holders, but you may "
+"include translations of some or all Invariant Sections in addition to the "
+"original versions of these Invariant Sections. You may include a translation "
+"of this License provided that you also include the original English version "
+"of this License. In case of a disagreement between the translation and the "
+"original English version of this License, the original English version will "
+"prevail."
+msgstr ""
+"Översättning anses vara en sorts förändring, så du äger sprida "
+"översättningar av <link linkend=\"fdl-document\">dokumentet</link> enligt de "
+"villkor som sätts i <link linkend=\"fdl-section4\">paragraf 4</link>. <link "
+"linkend=\"fdl-invariant\">Oföränderliga avsnitt</link> som ersätts med "
+"översättningar kräver tillstånd från deras upphovsrättsinnehavare, men du "
+"äger inkludera översättningar av alla eller vissa av dessa oföränderliga "
+"avsnitt tillsammans med originalversionerna av dessa oföränderliga avsnitt. "
+"Du äger inkludera en översättning av denna licens, och alla licensklausuler "
+"i dokumentet, och alla garantiavsägelser, förutsatt att du också innefattar "
+"den engelska originalversionen av denna licens och originalversionerna av "
+"dessa klausuler. Skulle det finnas skillnader mellan översättningen och "
+"originalversionen av denna licens eller någon klausul så gäller "
+"originalversionen."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:580 C/fdl-appendix.xml:580
msgid "9. TERMINATION"
msgstr "9. UPPHÖRANDE"
-#: C/gtk-doc-manual.xml:581(para)
-msgid "You may not copy, modify, sublicense, or distribute the <link linkend=\"fdl-document\">Document</link> except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance."
-msgstr "Du äger inte kopiera, förändra, omlicensiera eller sprida <link linkend=\"fdl-document\">dokumentet</link> annat än enligt villkoren i GNU Free Documentation License. Alla övriga försök att kopiera, modifiera, omlicensiera, eller sprida dokumentet är ogiltiga och kommer automatiskt medföra att du förlorar dina rättigheter enligt denna licens. Tredje man som har mottagit kopior eller rättigheter från dig enligt dessa licensvillkor kommer dock inte att förlora sina rättigheter så länge de följer licensvillkoren."
-
-#: C/gtk-doc-manual.xml:594(title)
+#. (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 "
+"License. Any other attempt to copy, modify, sublicense or distribute the "
+"Document is void, and will automatically terminate your rights under this "
+"License. However, parties who have received copies, or rights, from you "
+"under this License will not have their licenses terminated so long as such "
+"parties remain in full compliance."
+msgstr ""
+"Du äger inte kopiera, förändra, omlicensiera eller sprida <link linkend="
+"\"fdl-document\">dokumentet</link> annat än enligt villkoren i GNU Free "
+"Documentation License. Alla övriga försök att kopiera, modifiera, "
+"omlicensiera, eller sprida dokumentet är ogiltiga och kommer automatiskt "
+"medföra att du förlorar dina rättigheter enligt denna licens. Tredje man som "
+"har mottagit kopior eller rättigheter från dig enligt dessa licensvillkor "
+"kommer dock inte att förlora sina rättigheter så länge de följer "
+"licensvillkoren."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:594 C/fdl-appendix.xml:594
msgid "10. FUTURE REVISIONS OF THIS LICENSE"
msgstr "10. FRAMTIDA VERSIONER AV DENNA LICENS"
-#: C/gtk-doc-manual.xml:595(para)
-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 Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See <ulink type=\"http\" url=\"http://www.gnu.org/copyleft\">http://www.gnu.org/copyleft/</ulink>."
-msgstr "<ulink type=\"http\" url=\"http://www.gnu.org/fsf/fsf.html\">Free Software Foundation</ulink> kan publicera nya, reviderade versioner av GNU Free Documentation License då och då. Sådana nya versioner kommer att vara likadana i andemening som den nuvarande versionen, men kan skilja i detalj för att behandla nya problem eller angelägenheter. Se <ulink type=\"http\" url=\"http://www.gnu.org/copyleft\">http://www.gnu.org/copyleft/</ulink>."
-
-#: C/gtk-doc-manual.xml:606(para)
-msgid "Each version of the License is given a distinguishing version number. If the <link linkend=\"fdl-document\">Document</link> specifies that a particular numbered version of this License <quote>or any later version</quote> applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation."
-msgstr "Varje version av licensen ges ett unikt versionsnummer. Om <link linkend=\"fdl-document\">dokumentet</link> stadgar att en specifik numrerad version av denna licens <quote>eller valfri senare version</quote> gäller för det, så äger du rätten att följa villkoren enligt antingen den angivna versionen eller vilken senare version som helst som publicerats (inte som utkast) av Free Software Foundation. Om dokumentet inte anger en version av denna licens, äger du välja vilken version som helst som publicerats (inte som utkast) av Free Software Foundation."
-
-#: C/gtk-doc-manual.xml:621(title)
+#. (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 "
+"Free Documentation License from time to time. Such new versions will be "
+"similar in spirit to the present version, but may differ in detail to "
+"address new problems or concerns. See <ulink type=\"http\" url=\"http://www."
+"gnu.org/copyleft\">http://www.gnu.org/copyleft/</ulink>."
+msgstr ""
+"<ulink type=\"http\" url=\"http://www.gnu.org/fsf/fsf.html\">Free Software "
+"Foundation</ulink> kan publicera nya, reviderade versioner av GNU Free "
+"Documentation License då och då. Sådana nya versioner kommer att vara "
+"likadana i andemening som den nuvarande versionen, men kan skilja i detalj "
+"för att behandla nya problem eller angelägenheter. Se <ulink type=\"http\" "
+"url=\"http://www.gnu.org/copyleft\">http://www.gnu.org/copyleft/</ulink>."
+
+#. (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 "
+"numbered version of this License <quote>or any later version</quote> applies "
+"to it, you have the option of following the terms and conditions either of "
+"that specified version or of any later version that has been published (not "
+"as a draft) by the Free Software Foundation. If the Document does not "
+"specify a version number of this License, you may choose any version ever "
+"published (not as a draft) by the Free Software Foundation."
+msgstr ""
+"Varje version av licensen ges ett unikt versionsnummer. Om <link linkend="
+"\"fdl-document\">dokumentet</link> stadgar att en specifik numrerad version "
+"av denna licens <quote>eller valfri senare version</quote> gäller för det, "
+"så äger du rätten att följa villkoren enligt antingen den angivna versionen "
+"eller vilken senare version som helst som publicerats (inte som utkast) av "
+"Free Software Foundation. Om dokumentet inte anger en version av denna "
+"licens, äger du välja vilken version som helst som publicerats (inte som "
+"utkast) av Free Software Foundation."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:621 C/fdl-appendix.xml:621
msgid "Addendum"
msgstr "TILLÄGG"
-#: C/gtk-doc-manual.xml:622(para)
-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 just after the title page:"
-msgstr "För att använda GNU Free Documentation License för ett dokument du har skrivit, inkludera en kopia av licensen [det engelska originalet] i dokumentet och placera följande copyrightklausul omedelbart efter titelsidan:"
+#. (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 "
+"just after the title page:"
+msgstr ""
+"För att använda GNU Free Documentation License för ett dokument du har "
+"skrivit, inkludera en kopia av licensen [det engelska originalet] i "
+"dokumentet och placera följande copyrightklausul omedelbart efter titelsidan:"
-#: C/gtk-doc-manual.xml:629(para)
+#. (itstool) path: blockquote/para
+#: C/index.docbook:629 C/fdl-appendix.xml:629
msgid "Copyright YEAR YOUR NAME."
-msgstr "Copyright (c) ÅRTAL DITT NAMN."
+msgstr "Copyright © YEAR YOUR NAME."
-#: C/gtk-doc-manual.xml:632(para)
-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 version published by the Free Software Foundation; with the <link linkend=\"fdl-invariant\">Invariant Sections</link> being LIST THEIR TITLES, with the <link linkend=\"fdl-cover-texts\">Front-Cover Texts</link> being LIST, and with the <link linkend=\"fdl-cover-texts\">Back-Cover Texts</link> being LIST. A copy of the license is included in the section entitled <quote>GNU Free Documentation License</quote>."
-msgstr "Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the <link linkend=\"fdl-invariant\">Invariant Sections</link> being LIST THEIR TITLES, with the <link linkend=\"fdl-cover-texts\">Front-Cover Texts</link> being LIST, and with the <link linkend=\"fdl-cover-texts\">Back-Cover Texts</link> being LIST. A copy of the license is included in the section entitled <quote>GNU Free Documentation License</quote>."
+#. (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 "
+"version published by the Free Software Foundation; with the <link linkend="
+"\"fdl-invariant\">Invariant Sections</link> being LIST THEIR TITLES, with "
+"the <link linkend=\"fdl-cover-texts\">Front-Cover Texts</link> being LIST, "
+"and with the <link linkend=\"fdl-cover-texts\">Back-Cover Texts</link> being "
+"LIST. A copy of the license is included in the section entitled <quote>GNU "
+"Free Documentation License</quote>."
+msgstr ""
+"Permission is granted to copy, distribute and/or modify this document under "
+"the terms of the GNU Free Documentation License, Version 1.1 or any later "
+"version published by the Free Software Foundation; with the <link linkend="
+"\"fdl-invariant\">Invariant Sections</link> being LIST THEIR TITLES, with "
+"the <link linkend=\"fdl-cover-texts\">Front-Cover Texts</link> being LIST, "
+"and with the <link linkend=\"fdl-cover-texts\">Back-Cover Texts</link> being "
+"LIST. A copy of the license is included in the section entitled <quote>GNU "
+"Free Documentation License</quote>."
+
+#. (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 "
+"are invariant. If you have no <link linkend=\"fdl-cover-texts\">Front-Cover "
+"Texts</link>, write <quote>no Front-Cover Texts</quote> instead of "
+"<quote>Front-Cover Texts being LIST</quote>; likewise for <link linkend="
+"\"fdl-cover-texts\">Back-Cover Texts</link>."
+msgstr ""
+"Om du inte har några <link linkend=\"fdl-invariant\">oföränderliga avsnitt</"
+"link>, skriv <quote>with no Invariant Sections</quote> istället för att ange "
+"vilka som är oföränderliga. Om du inte har några <link linkend=\"fdl-cover-"
+"texts\">framsidestexter</link>, skriv <quote>no Front-Cover Texts</quote> "
+"istället för <quote>Front-Cover Texts being LIST</quote>; såväl som för "
+"<link linkend=\"fdl-cover-texts\">baksidestexter</link>."
+
+#. (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 "
+"license, such as the <ulink type=\"http\" url=\"http://www.gnu.org/copyleft/"
+"gpl.html\"> GNU General Public License</ulink>, to permit their use in free "
+"software."
+msgstr ""
+"Om ditt dokument innehåller icke-triviala exempel med programkod, så "
+"rekommenderar vi att du släpper dessa exempel parallellt under en, av dig "
+"vald, fri programvarulicens, som till exempel <ulink type=\"http\" url="
+"\"http://www.gnu.org/copyleft/gpl.html\">GNU General Public License</ulink>, "
+"för att möjliggöra deras användning i fri programvara."
+
+#. (itstool) path: copyright/year
+#: C/fdl-appendix.xml:16
+msgid "2000"
+msgstr "2000"
-#: C/gtk-doc-manual.xml:647(para)
-msgid "If you have no <link linkend=\"fdl-invariant\">Invariant Sections</link>, write <quote>with no Invariant Sections</quote> instead of saying which ones are invariant. If you have no <link linkend=\"fdl-cover-texts\">Front-Cover Texts</link>, write <quote>no Front-Cover Texts</quote> instead of <quote>Front-Cover Texts being LIST</quote>; likewise for <link linkend=\"fdl-cover-texts\">Back-Cover Texts</link>."
-msgstr "Om du inte har några <link linkend=\"fdl-invariant\">oföränderliga avsnitt</link>, skriv <quote>utan oföränderliga avsnitt</quote> istället för att ange vilka som är oföränderliga. Om du inte har några <link linkend=\"fdl-cover-texts\">framsidestexter</link>, skriv <quote>utan framsidestexter</quote> istället för <quote>framsidestexter som LISTAS</quote>; såväl som för <link linkend=\"fdl-cover-texts\">baksidestexter</link>."
+#. (itstool) path: copyright/holder
+#: C/fdl-appendix.xml:16
+msgid "Free Software Foundation, Inc."
+msgstr "Free Software Foundation, Inc."
-#: C/gtk-doc-manual.xml:657(para)
-msgid "If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the <ulink type=\"http\" url=\"http://www.gnu.org/copyleft/gpl.html\"> GNU General Public License</ulink>, to permit their use in free software."
-msgstr "Om ditt dokument innehåller icke-triviala exempel med programkod, så rekommenderar vi att du släpper dessa exempel parallellt under en, av dig vald, fri programvarulicens, som till exempel <ulink type=\"http\" url=\"http://www.gnu.org/copyleft/gpl.html\">GNU General Public License</ulink>, för att möjliggöra deras användning i fri programvara."
+#. (itstool) path: address/street
+#: C/fdl-appendix.xml:20
+msgid "51 Franklin Street, Suite 330"
+msgstr "51 Franklin Street, Suite 330"
+
+#. (itstool) path: address/city
+#: C/fdl-appendix.xml:21
+msgid "Boston"
+msgstr "Boston"
+
+#. (itstool) path: address/state
+#: C/fdl-appendix.xml:21
+msgid "MA"
+msgstr "MA"
+
+#. (itstool) path: address/postcode
+#: C/fdl-appendix.xml:22
+msgid "02110-1301"
+msgstr "02110-1301"
+
+#. (itstool) path: address/country
+#: C/fdl-appendix.xml:22
+msgid "USA"
+msgstr "USA"
+
+#. (itstool) path: para/address
+#: C/fdl-appendix.xml:20
+msgid ""
+"Free Software Foundation, Inc. <_:street-1/>, <_:city-2/>, <_:state-3/> <_:"
+"postcode-4/> <_:country-5/>"
+msgstr ""
+"Free Software Foundation, Inc. <_:street-1/>, <_:city-2/>, <_:state-3/> <_:"
+"postcode-4/> <_:country-5/>"
-#. Put one translator per line, in the form of NAME <EMAIL>, YEAR1, YEAR2.
-#: C/gtk-doc-manual.xml:0(None)
-msgid "translator-credits"
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:34
+msgid "free"
+msgstr "fritt"
+
+#. (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 "
+"effective freedom to copy and redistribute it, with or without modifying it, "
+"either commercially or noncommercially. Secondarily, this License preserves "
+"for the author and publisher a way to get credit for their work, while not "
+"being considered responsible for modifications made by others."
+msgstr ""
+"Syftet med denna licens är att göra en handbok, bok, eller annat praktiskt "
+"och användbart dokument <_:quote-1/> som i frihet: att försäkra var och en "
+"den faktiska friheten att kopiera och sprida det vidare, med eller utan "
+"förändringar, antingen kommersiellt eller ideellt. Sekundärt bevarar denna "
+"licens ett sätt för författaren och förläggaren att få ära för deras arbete "
+"utan att de anses vara ansvariga för förändringar gjorda av andra."
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:44
+msgid "copyleft"
+msgstr "copyleft"
+
+#. (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 "
+"GNU General Public License, which is a copyleft license designed for free "
+"software."
+msgstr ""
+"Denna Licens är en sorts <_:quote-1/>, vilket betyder att derivativa verk av "
+"detta dokument själva måste vara fria på samma sätt. Den kompletterar GNU "
+"General Public License, som är en copyleft-licens utformad för fri "
+"programvara."
+
+#. (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 "Dokument"
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:69
+msgid "you"
+msgstr "du"
+
+#. (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 "
+"of this License. The <_:quote-1/>, below, refers to any such manual or work. "
+"Any member of the public is a licensee, and is addressed as <_:quote-2/>."
+msgstr ""
+"Denna licens [det engelska originalet] gäller för varje handbok eller annat "
+"verk, oavsett uttrycksform, som innehåller ett meddelande där "
+"upphovsrättsinnehavaren stadgat att verket kan spridas enligt villkoren i "
+"GNU Free Documentation License. Ett sådant meddelande ger en internationell "
+"frihet utan krav på ersättning och utan tidsbegränsning att använda verket "
+"under villkoren i denna licens [det engelska originalet]. <_:quote-1/> nedan "
+"syftar på godtycklig handbok eller verk. Var och en är licenstagare och "
+"benämns som <_:quote-2/>."
+
+#. (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 "förändrad version"
+
+#. (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 "
+"translated into another language."
msgstr ""
-"Daniel Nylander <po@danielnylander.se>, 2009\n"
-"Marcus Rejås och Alexander Nordström <info@se.linux.org>, 2004"
+"En <_:quote-1/> av dokumentet avser varje verk som innehåller dokumentet "
+"eller en del av det, antingen ordagranna kopior, eller med ändringar och/"
+"eller översatt till ett annat språk."
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:80
+msgid "Secondary Section"
+msgstr "sekundärt avsnitt"
+
+#. (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 "
+"authors of the Document to the Document's overall subject (or to related "
+"matters) and contains nothing that could fall directly within that overall "
+"subject. (For example, if the Document is in part a textbook of mathematics, "
+"a Secondary Section may not explain any mathematics.) The relationship could "
+"be a matter of historical connection with the subject or with related "
+"matters, or of legal, commercial, philosophical, ethical or political "
+"position regarding them."
+msgstr ""
+"Ett <_:quote-1/> är en märkt bilaga eller förord till <link linkend=\"fdl-"
+"document\">dokumentet</link> som exklusivt behandlar förhållandet mellan "
+"dokumentets förläggare eller författare och dokumentets huvudsakliga ämne "
+"(eller till relaterade ämnen) och som inte innehåller något som direkt "
+"faller under det huvudsakliga ämnet. (Således, om dokumentet delvis är en "
+"lärobok i matematik så får ett sekundärt avsnitt inte förklara någon "
+"matematik.) Förhållandet kan vara en historisk koppling till ämnet eller "
+"något relaterat, eller en juridisk, kommersiell, filosofisk, etisk eller "
+"politisk ställning till det."
+
+#. (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 "oföränderliga avsnitten"
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:96 C/fdl-appendix.xml:435
+msgid "Secondary Sections"
+msgstr "sekundära avsnitt"
+
+#. (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 <_:"
+"link-3/> is released under this License."
+msgstr ""
+"De <_:quote-1/> är <_:link-2/> vars titlar är angivna som oföränderliga "
+"avsnitt i meddelandet som stadgar att <_:link-3/> är utgivet under denna "
+"licens [det engelska originalet]."
+
+#. (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 "Omslagstexterna"
+
+#. (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 <_:"
+"link-2/> is released under this License."
+msgstr ""
+"<_:quote-1/> är speciella korta ordföljder som är listade som "
+"framsidestexter eller baksidestexter i meddelandet som stadgar att <_:link-2/"
+"> är utgivet under denna licens [det engelska originalet]."
+
+#. (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 "transparent"
+
+#. (itstool) path: para/quote
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:125 C/fdl-appendix.xml:204
+msgid "Opaque"
+msgstr "opak"
+
+#. (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 "
+"public, whose contents can be viewed and edited directly and "
+"straightforwardly with generic text editors or (for images composed of "
+"pixels) generic paint programs or (for drawings) some widely available "
+"drawing editor, and that is suitable for input to text formatters or for "
+"automatic translation to a variety of formats suitable for input to text "
+"formatters. A copy made in an otherwise Transparent file format whose markup "
+"has been designed to thwart or discourage subsequent modification by readers "
+"is not Transparent. A copy that is not <_:quote-3/> is called <_:quote-4/>."
+msgstr ""
+"En <_:quote-1/> kopia av <_:link-2/> är en maskinläsbar kopia, representerad "
+"i ett format vars specifikation finns tillgänglig för allmänheten, som "
+"lämpar sig för att revidera dokumentet på ett enkelt sätt med generella "
+"textredigeringsprogram eller (för pixelbaserade bilder) generella "
+"grafikprogram eller (för ritningar) något väl tillgängligt ritprogram, och "
+"som är passande som indata till textformaterare eller för automatisk "
+"konvertering till en mängd format som passar som indata till "
+"textformaterare. En kopia i ett för övrigt transparent filformat vars "
+"markeringar, eller avsaknad av markeringar, har ordnats för att hindra eller "
+"motverka att vidare förändring vidtas av läsare är inte transparent. En "
+"kopia som inte är <_:quote-3/> kallas <_:quote-4/>."
+
+#. (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 "Titelsidan"
+
+#. (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 "
+"requires to appear in the title page. For works in formats which do not have "
+"any title page as such, <_:quote-2/> means the text near the most prominent "
+"appearance of the work's title, preceding the beginning of the body of the "
+"text."
+msgstr ""
+"<_:quote-1/> innebär, för en tryckt bok, titelsidan själv, och sådana därpå "
+"följande sidor som krävs för att göra det material som enligt denna licens "
+"skall synas på titelsidan läsbart. För verk i sådana format som inte har "
+"någon egentlig titelsida, avses med <_:quote-2/> den text som är närmast den "
+"mest framstående förekomsten av verkets titel, föregående den huvudsakliga "
+"textmassan."
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:166 C/fdl-appendix.xml:551
+msgid "section 3"
+msgstr "paragraf 3"
+
+#. (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 "
+"notices, and the license notice saying this License applies to the Document "
+"are reproduced in all copies, and that you add no other conditions "
+"whatsoever to those of this License. You may not use technical measures to "
+"obstruct or control the reading or further copying of the copies you make or "
+"distribute. However, you may accept compensation in exchange for copies. If "
+"you distribute a large enough number of copies you must also follow the "
+"conditions in <_:link-2/>."
+msgstr ""
+"Du äger kopiera och sprida <_:link-1/> på valfritt medium, antingen "
+"kommersiellt eller ideellt, förutsatt att denna licens [det engelska "
+"originalet], upphovsrättsklausul, och meddelandet som stadgar att GNU Free "
+"Documentation License gäller för dokumentet finns med på alla kopior, och "
+"att du inte lägger till några som helst andra villkor än de som ingår i "
+"denna licens. Du äger inte vidta tekniska åtgärder för att begränsa eller "
+"kontrollera läsande eller vidare kopiering av de kopior du skapar eller "
+"sprider. Dock äger du ta emot kompensation i utbyte mot kopior. Om du "
+"sprider tillräckligt många kopior måste du också följa villkoren i <_:link-2/"
+">."
+
+#. (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 "
+"copies in covers that carry, clearly and legibly, all these Cover Texts: "
+"Front-Cover Texts on the front cover, and Back-Cover Texts on the back "
+"cover. Both covers must also clearly and legibly identify you as the "
+"publisher of these copies. The front cover must present the full title with "
+"all words of the title equally prominent and visible. You may add other "
+"material on the covers in addition. Copying with changes limited to the "
+"covers, as long as they preserve the title of the <_:link-3/> and satisfy "
+"these conditions, can be treated as verbatim copying in other respects."
+msgstr ""
+"Om du publicerar tryckta kopior (eller kopior i medier som normalt har "
+"tryckta omslag) av <_:link-1/>, i en upplaga överstigande 100 exemplar, och "
+"dokumentets licensmeddelande kräver <_:link-2/>, så måste du förse kopiorna "
+"med omslag som, klart och tydligt, visar alla omslagstexter: framsidestexter "
+"på framsidan och baksidestexter på baksidan. Båda omslagen måste klart och "
+"tydligt identifiera dig som utgivare av dessa kopior. Framsidan måste "
+"presentera dokumentets hela titel, med alla ord i titeln lika framträdande "
+"och synliga. Du äger lägga till ytterligare stoff på omslagen. Kopiering med "
+"förändringar gjorda bara på omslaget, så länge som de bevarar titeln för <_:"
+"link-3/> och i övrigt uppfyller dessa krav kan anses vara ordagrann "
+"kopiering i andra avseenden."
+
+#. (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 "
+"along with each Opaque copy, or state in or with each Opaque copy a publicly-"
+"accessible computer-network location containing a complete Transparent copy "
+"of the Document, free of added material, which the general network-using "
+"public has access to download anonymously at no charge using public-standard "
+"network protocols. If you use the latter option, you must take reasonably "
+"prudent steps, when you begin distribution of Opaque copies in quantity, to "
+"ensure that this Transparent copy will remain thus accessible at the stated "
+"location until at least one year after the last time you distribute an "
+"Opaque copy (directly or through your agents or retailers) of that edition "
+"to the public."
+msgstr ""
+"Om du publicerar <_:link-1/>a kopior av <_:link-2/> i upplagor om mer än "
+"100, måste du antingen bifoga en maskinläsbar <_:link-3/> kopia med varje "
+"opak kopia, eller ange i eller med varje opak kopia en nätverksadress som är "
+"tillgänglig för den allmänna nätverksanvändande massan där man, med öppet "
+"standardiserade protokoll, anonymt och utan kostnad kan ladda ner en "
+"komplett transparent kopia av dokumentet, utan extra material. Om du väljer "
+"det senare alternativet, måste du vidta skäliga åtgärder, när du börjar "
+"sprida opaka kopior i kvantitet, för att denna transparenta kopia skall "
+"förbli tillgänglig på angivna platsen till åtminstone ett år efter den sista "
+"gången du spred en opak kopia (direkt eller via ombud eller återförsäljare) "
+"av den utgåvan till allmänheten."
+
+#. (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 "
+"a chance to provide you with an updated version of the Document."
+msgstr ""
+"Det är önskvärt, men inte ett krav, att du kontaktar författarna till <_:"
+"link-1/> i god tid innan du sprider något större antal kopior, för att ge "
+"dem en chans att förse dig med en uppdaterad version av dokumentet."
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:236
+msgid "2"
+msgstr "2"
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:237
+msgid "3"
+msgstr "3"
+
+#. (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 "
+"release the Modified Version under precisely this License, with the Modified "
+"Version filling the role of the Document, thus licensing distribution and "
+"modification of the Modified Version to whoever possesses a copy of it. In "
+"addition, you must do these things in the Modified Version:"
+msgstr ""
+"Du äger kopiera och sprida en <_:link-1/> av <_:link-2/> under de villkor "
+"som beskrivs i paragraf <_:link-3/> och <_:link-4/> av GNU Free "
+"Documentation License, förutsatt att du släpper den förändrade versionen "
+"under exakt denna licens, och att den förändrade versionen antar dokumentets "
+"roll, och således medger spridning och förändring av den förändrade "
+"versionen till envar som erhåller en kopia av den. Utöver detta måste du "
+"göra följande med den ändrade versionen:"
+
+#. (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, "
+"if there were any, be listed in the History section of the Document). You "
+"may use the same title as a previous version if the original publisher of "
+"that version gives permission."
+msgstr ""
+"På <_:link-1/> (och omslagen om det finns några) använda en titel skild från "
+"den som [original]<_:link-2/> har, och skild från tidigare versioners titel "
+"(som skall, om det finns några, finnas listade i historikavsnittet i "
+"dokumentet). Du äger använda samma titel som det föregående dokumentet om "
+"den ursprungliga utgivaren ger sitt tillstånd."
+
+#. (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 "
+"with at least five of the principal authors of the <_:link-3/> (all of its "
+"principal authors, if it has less than five)."
+msgstr ""
+"Lista på <_:link-1/>, som författare, en eller flera personer eller "
+"juridiska personer som ansvarat för förändringarna i <_:link-2/>, "
+"tillsammans med minst fem av de huvudsakliga författarna av <_:link-3/> "
+"(alla dess huvudsakliga författare, om det har mindre än fem)."
+
+#. (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."
+msgstr "Ange namnet på utgivaren av <_:link-1/>, som utgivare, på <_:link-2/>."
+
+#. (itstool) path: formalpara/para
+#: C/fdl-appendix.xml:292
+msgid "Preserve all the copyright notices of the <_:link-1/>."
+msgstr "Bibehålla alla upphovsrättsklausuler för <_:link-1/>."
+
+#. (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 "
+"License, in the form shown in the Addendum below."
+msgstr ""
+"Direkt efter upphovsrättsklausulerna innefatta ett meddelande som ger "
+"allmänheten tillstånd att använda <_:link-1/> under villkoren i denna licens "
+"[det engelska originalet] i den form som visas i Tillägg nedan."
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:330
+msgid "Document's"
+msgstr "dokumentets"
+
+#. (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."
+msgstr ""
+"I meddelandet om licensen bevara den fullständiga listan över <_:link-1/> "
+"och obligatoriska <_:link-2/> som finns i <_:link-3/> meddelande om licensen."
+
+#. (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 "historik"
+
+#. (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 <_:"
+"link-2/> as given on the <_:link-3/>. If there is no section entitled <_:"
+"quote-4/> in the <_:link-5/>, create one stating the title, year, authors, "
+"and publisher of the Document as given on its Title Page, then add an item "
+"describing the Modified Version as stated in the previous sentence."
+msgstr ""
+"Bevara avsnittet med titeln <_:quote-1/> (History), bevara dess titel och "
+"lägg i avsnittet till en post med åtminstone titeln, året, nya författare "
+"och utgivaren av <_:link-2/> så som angivet på <_:link-3/>. Om det inte "
+"finns något avsnitt med titeln <_:quote-4/> (History) i <_:link-5/> så skapa "
+"en med titeln, året, författare och utgivaren av dokumentet så som det står "
+"på [original]dokumentets titelsida. Lägg sedan till en post som beskriver "
+"den förändrade versionen så som beskrivits ovan."
+
+#. (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 "
+"locations given in the Document for previous versions it was based on. These "
+"may be placed in the <_:quote-3/> section. You may omit a network location "
+"for a work that was published at least four years before the Document "
+"itself, or if the original publisher of the version it refers to gives "
+"permission."
+msgstr ""
+"Bevara den nätverksadress, om det finns någon, angiven i <_:link-1/> till "
+"den allmänt tillgängliga <_:link-2/>a kopian av dokumentet, och likaså "
+"nätverksadresserna till de föregående versioner som dokumentet baseras på. "
+"Dessa får placeras i avsnittet <_:quote-3/> (History). Du äger utelämna en "
+"nätverksadress för ett verk som är publicerat mer än fyra år före dokumentet "
+"självt, eller om den ursprunglige utgivaren vars verk nätverksadressen "
+"hänvisar till ger sitt tillstånd."
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:385 C/fdl-appendix.xml:509
+msgid "Acknowledgements"
+msgstr "tillkännagivanden"
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:386 C/fdl-appendix.xml:510
+msgid "Dedications"
+msgstr "dedikationer"
+
+#. (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 "
+"contributor acknowledgements and/or dedications given therein."
+msgstr ""
+"För alla avsnitt med titlarna <_:quote-1/> (Acknowledgements) eller <_:"
+"quote-2/> (Dedications), bevara titeln på avsnittet, och bevara allt "
+"innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda "
+"av varje bidragsgivare."
+
+#. (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 "
+"of the section titles."
+msgstr ""
+"Bevara alla <_:link-1/> i <_:link-2/> oförändrade till text och titel. "
+"Avsnittsnummer eller motsvarande anses inte tillhöra avsnittets titel."
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:412 C/fdl-appendix.xml:424 C/fdl-appendix.xml:445
+msgid "Endorsements"
+msgstr "endossering"
+
+#. (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/>."
+msgstr ""
+"Radera varje avsnitt med titeln <_:quote-1/> (Endorsements). Ett sådant "
+"avsnitt får inte inkluderas i en <_:link-2/>."
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:425
+msgid "Invariant Section"
+msgstr "oföränderligt avsnitt"
+
+#. (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/>."
+msgstr ""
+"Inte byta titel på något existerande avsnitt så att det blir <_:quote-1/> "
+"(Endorsements) eller så att titeln kan förväxlas med något <_:link-2/>."
+
+#. (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 "
+"may at your option designate some or all of these sections as invariant. To "
+"do this, add their titles to the list of <_:link-3/> in the Modified "
+"Version's license notice. These titles must be distinct from any other "
+"section titles."
+msgstr ""
+"Om <_:link-1/> innehåller nya framsidestexter eller bilagor som är att anses "
+"som <_:link-2/> och inte innehåller något material kopierat från dokumentet, "
+"så äger du, om du vill, benämna några eller samtliga av dessa som "
+"oföränderliga. För att göra detta, lägg deras titlar till listan över <_:"
+"link-3/> i den förändrade versionens licensmeddelande. Dessa titlar måste "
+"vara skilda från alla andra avsnitts titlar."
+
+#. (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, "
+"statements of peer review or that the text has been approved by an "
+"organization as the authoritative definition of a standard."
+msgstr ""
+"Du äger lägga till ett avsnitt med titeln <_:quote-1/> (Endorsements), "
+"förutsatt att det inte innehåller något annat än endosseringar för din <_:"
+"link-2/> från olika aktörer -- till exempel, meddelanden om utförd "
+"korrekturläsning eller att texten har godkänts av en organisation som en "
+"officiell definition av en standard."
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:455
+msgid "Front-Cover Text"
+msgstr "framsidestext"
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:457
+msgid "Back-Cover Text"
+msgstr "baksidestext"
+
+#. (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 "
+"the <_:link-4/>. Only one passage of Front-Cover Text and one of Back-Cover "
+"Text may be added by (or through arrangements made by) any one entity. If "
+"the <_:link-5/> already includes a cover text for the same cover, previously "
+"added by you or by arrangement made by the same entity you are acting on "
+"behalf of, you may not add another; but you may replace the old one, on "
+"explicit permission from the previous publisher that added the old one."
+msgstr ""
+"Du äger lägga till ett textavsnitt på upp till fem ord som <_:link-1/>, och "
+"ett textavsnitt på upp till 25 ord som <_:link-2/> i listan över <_:link-3/> "
+"i <_:link-4/>. Bara ett textavsnitt med framsidestexter och ett med "
+"baksidestexter får läggas till av (eller genom försorg av) en enda juridisk "
+"person. Om <_:link-5/> redan innehåller en omslagstext för något av "
+"omslagen, tidigare tillagd av dig eller genom försorg av samma juridiska "
+"person som du företräder, äger du inte lägga till en till, men du äger ändra "
+"den gamla med tillstånd från den tidigare utgivaren som lade till den förra."
+
+#. (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 "
+"endorsement of any <_:link-2/>."
+msgstr ""
+"Författaren (författarna) och utgivaren (utgivarna) av <_:link-1/> ger inte "
+"via denna licens sitt tillstånd att använda sina namn för publicitet eller "
+"för att lägga till eller antyda endossering av någon <_:link-2/>."
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:484 C/fdl-appendix.xml:566
+msgid "section 4"
+msgstr "paragraf 4"
+
+#. (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, "
+"provided that you include in the combination all of the <_:link-3/> of all "
+"of the original documents, unmodified, and list them all as Invariant "
+"Sections of your combined work in its license notice."
+msgstr ""
+"Du äger kombinera <_:link-1/> med andra dokument som är utgivna under denna "
+"licens, under de villkor som definieras i <_:link-2/> av GNU Free "
+"Documentation License för förändrade versioner, förutsatt att du, i det "
+"kombinerade dokumentet, innefattar alla <_:link-3/> från originaldokumenten, "
+"omodifierade, och listar dem som oföränderliga avsnitt i ditt kombinerade "
+"verk i dess licensklausul, och att du bevarar alla deras "
+"garantiavsägelseklausuler."
+
+#. (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 "
+"multiple Invariant Sections with the same name but different contents, make "
+"the title of each such section unique by adding at the end of it, in "
+"parentheses, the name of the original author or publisher of that section if "
+"known, or else a unique number. Make the same adjustment to the section "
+"titles in the list of Invariant Sections in the license notice of the "
+"combined work."
+msgstr ""
+"Det kombinerade verket behöver bara innehålla en enstaka kopia av denna "
+"licens [engelska originalversionen], och flera identiska <_:link-1/> kan "
+"ersättas med en kopia. Om det finns flera oföränderliga stycken med samma "
+"namn men olika innehåll, se till att titeln på varje sådant avsnitt är unik "
+"genom att i slutet på den, inom parentes, lägga till namnet på den "
+"ursprunglige författaren eller utgivaren av det avsnittet om dessa är kända, "
+"annars ett unikt nummer. Gör samma justeringar av titlarna i listan över "
+"oföränderliga avsnitt i licensklausulen i det kombinerade verket."
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:511
+msgid "Endorsements."
+msgstr "endossering"
+
+#. (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/>; "
+"likewise combine any sections entitled <_:quote-3/>, and any sections "
+"entitled <_:quote-4/>. You must delete all sections entitled <_:quote-5/>"
+msgstr ""
+"I det kombinerade verket måste du kombinera alla avsnitt med titlarna <_:"
+"quote-1/> (History) i de ursprungliga dokumenten, till ett avsnitt med "
+"titeln <_:quote-2/> (History); på samma sätt skall alla avsnitt med titlarna "
+"<_:quote-3/> (Acknowledgements), alla avsnitt med titlarna <_:quote-4/> "
+"(Dedications) kombineras. Du måste ta bort alla avsnitt med titlarna <_:"
+"quote-5/> (Endorsements)."
+
+#. (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 "
+"License in the various documents with a single copy that is included in the "
+"collection, provided that you follow the rules of this License for verbatim "
+"copying of each of the documents in all other respects."
+msgstr ""
+"Du äger skapa en samling bestående av <_:link-1/> och andra dokument som är "
+"släppta under GNU Free Documentation License, och ersätta individuella "
+"kopior i dokumenten av denna licens med en enda kopia [av den engelska "
+"originalversionen] som inkluderas i samlingen, förutsatt att du följer "
+"villkoren för ordagrann kopiering i denna licens för varje inkluderat "
+"dokument i alla andra avseenden."
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:546
+msgid "aggregate"
+msgstr "sammanslagning"
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:550
+msgid "Cover Text"
+msgstr "Omslagstext"
+
+# sebras
+#. (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 "
+"distribution medium, does not as a whole count as a <_:link-2/> of the "
+"Document, provided no compilation copyright is claimed for the compilation. "
+"Such a compilation is called an <_:quote-3/>, and this License does not "
+"apply to the other self-contained works thus compiled with the Document , on "
+"account of their being thus compiled, if they are not themselves derivative "
+"works of the Document. If the <_:link-4/> requirement of <_:link-5/> is "
+"applicable to these copies of the Document, then if the Document is less "
+"than one quarter of the entire aggregate, the Document's Cover Texts may be "
+"placed on covers that surround only the Document within the aggregate. "
+"Otherwise they must appear on covers around the whole aggregate."
+msgstr ""
+"En samling av <_:link-1/> eller av dess derivat med andra separata och "
+"oberoende dokument eller verk, på eller i en lagringsvolym eller ett "
+"spridningsmedium, kallas för en <quote>sammanslagning</quote> om den "
+"sammanslagna upphovsrätten inte används för att begränsa samlingens "
+"användares rättigheter som de enskilda dokumenten medger. När dokumentet "
+"ingår i en sådan sammanslagning, gäller inte denna licens de andra verken i "
+"samlingen som inte själva är deriverat av dokumentet. Om kravet på <link "
+"linkend=\"fdl-cover-texts\">omslagstexter</link> enligt <link linkend=\"fdl-"
+"section3\">paragraf 3</link> är tillämpligt på dessa kopior av dokumentet, "
+"så kan dokumentets omslagstexter, om dokumentet utgör mindre än en fjärdedel "
+"av hela samlingen, placeras på det omslag som omger dokumentet inuti "
+"samlingen, eller den elektroniska motsvarigheten till omslag om dokumentet "
+"är i elektronisk form. Annars måste de synas på det omslag som omger hela "
+"samlingen."
+
+#. (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 <_:"
+"link-3/> with translations requires special permission from their copyright "
+"holders, but you may include translations of some or all Invariant Sections "
+"in addition to the original versions of these Invariant Sections. You may "
+"include a translation of this License provided that you also include the "
+"original English version of this License. In case of a disagreement between "
+"the translation and the original English version of this License, the "
+"original English version will prevail."
+msgstr ""
+"Översättning anses vara en sorts förändring, så du äger sprida "
+"översättningar av <_:link-1/> enligt de villkor som sätts i <_:link-2/>. <_:"
+"link-3/> som ersätts med översättningar kräver tillstånd från deras "
+"upphovsrättsinnehavare, men du äger inkludera översättningar av alla eller "
+"vissa av dessa oföränderliga avsnitt tillsammans med originalversionerna av "
+"dessa oföränderliga avsnitt. Du äger inkludera en översättning av denna "
+"licens, och alla licensklausuler i dokumentet, och alla garantiavsägelser, "
+"förutsatt att du också innefattar den engelska originalversionen av denna "
+"licens och originalversionerna av dessa klausuler. Skulle det finnas "
+"skillnader mellan översättningen och originalversionen av denna licens eller "
+"någon klausul så gäller originalversionen."
+
+#. (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, "
+"modify, sublicense or distribute the Document is void, and will "
+"automatically terminate your rights under this License. However, parties who "
+"have received copies, or rights, from you under this License will not have "
+"their licenses terminated so long as such parties remain in full compliance."
+msgstr ""
+"Du äger inte kopiera, förändra, omlicensiera eller sprida <_:link-1/> annat "
+"än enligt villkoren i GNU Free Documentation License. Alla övriga försök att "
+"kopiera, modifiera, omlicensiera, eller sprida dokumentet är ogiltiga och "
+"kommer automatiskt medföra att du förlorar dina rättigheter enligt denna "
+"licens. Tredje man som har mottagit kopior eller rättigheter från dig enligt "
+"dessa licensvillkor kommer dock inte att förlora sina rättigheter så länge "
+"de följer licensvillkoren."
+
+#. (itstool) path: para/ulink
+#: C/fdl-appendix.xml:597
+msgid "Free Software Foundation"
+msgstr "Free Software Foundation"
+
+#. (itstool) path: para/ulink
+#: C/fdl-appendix.xml:603
+msgid "http://www.gnu.org/copyleft/"
+msgstr "http://www.gnu.org/copyleft/"
+
+#. (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 "
+"in spirit to the present version, but may differ in detail to address new "
+"problems or concerns. See <_:ulink-2/>."
+msgstr ""
+"<_:ulink-1/> kan publicera nya, reviderade versioner av GNU Free "
+"Documentation License då och då. Sådana nya versioner kommer att vara "
+"likadana i andemening som den nuvarande versionen, men kan skilja i detalj "
+"för att behandla nya problem eller angelägenheter. Se <_:ulink-2/>."
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:610
+msgid "or any later version"
+msgstr "eller valfri senare version"
+
+#. (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 <_:"
+"quote-2/> applies to it, you have the option of following the terms and "
+"conditions either of that specified version or of any later version that has "
+"been published (not as a draft) by the Free Software Foundation. If the "
+"Document does not specify a version number of this License, you may choose "
+"any version ever published (not as a draft) by the Free Software Foundation."
+msgstr ""
+"Varje version av licensen ges ett unikt versionsnummer. Om <_:link-1/> "
+"stadgar att en specifik numrerad version av denna licens <_:quote-2/> gäller "
+"för det, så äger du rätten att följa villkoren enligt antingen den angivna "
+"versionen eller vilken senare version som helst som publicerats (inte som "
+"utkast) av Free Software Foundation. Om dokumentet inte anger en version av "
+"denna licens, äger du välja vilken version som helst som publicerats (inte "
+"som utkast) av Free Software Foundation."
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:639 C/fdl-appendix.xml:651
+msgid "Front-Cover Texts"
+msgstr "Front-Cover Texts"
+
+#. (itstool) path: para/link
+#: C/fdl-appendix.xml:640 C/fdl-appendix.xml:654
+msgid "Back-Cover Texts"
+msgstr "Back-Cover Texts"
+
+# <_:link-1/> blir "oföränderliga avsnitten"
+#. (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 "
+"version published by the Free Software Foundation; with the <_:link-1/> "
+"being LIST THEIR TITLES, with the <_:link-2/> being LIST, and with the <_:"
+"link-3/> being LIST. A copy of the license is included in the section "
+"entitled <_:quote-4/>."
+msgstr ""
+"Permission is granted to copy, distribute and/or modify this document under "
+"the terms of the GNU Free Documentation License, Version 1.1 or any later "
+"version published by the Free Software Foundation; with the <_:link-1/> "
+"being LIST THEIR TITLES, with the <_:link-2/> being LIST, and with the <_:"
+"link-3/> being LIST. A copy of the license is included in the section "
+"entitled <_:quote-4/>."
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:649
+msgid "with no Invariant Sections"
+msgstr "with no Invariant Sections"
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:652
+msgid "no Front-Cover Texts"
+msgstr "no Front-Cover Texts"
+
+#. (itstool) path: para/quote
+#: C/fdl-appendix.xml:653
+msgid "Front-Cover Texts being LIST"
+msgstr "Front-Cover Texts being LIST"
+
+#. (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 <_:"
+"quote-5/>; likewise for <_:link-6/>."
+msgstr ""
+"Om du inte har några <_:link-1/>, skriv <_:quote-2/> istället för att ange "
+"vilka som är oföränderliga. Om du inte har några <_:link-3/>, skriv <_:"
+"quote-4/> istället för <_:quote-5/>; såväl som för <_:link-6/>."
+
+#. (itstool) path: para/ulink
+#: C/fdl-appendix.xml:661
+msgid "GNU General Public License"
+msgstr "GNU General Public License"
+
+#. (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 "
+"license, such as the <_:ulink-1/>, to permit their use in free software."
+msgstr ""
+"Om ditt dokument innehåller icke-triviala exempel med programkod, så "
+"rekommenderar vi att du släpper dessa exempel parallellt under en, av dig "
+"vald, fri programvarulicens, som till exempel <_:ulink-1/>, för att "
+"möjliggöra deras användning i fri programvara."
+
+#~ 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>Generera ”mall”-filerna.</guilabel> <application>gtkdoc-mktmpl</"
+#~ "application> skapar ett antal filer i underkatalogen <filename class="
+#~ "\"directory\">tmpl/</filename>, från information som samlats ihop i det "
+#~ "första steget. (Notera att detta kan köras upprepade gånger. Det kommer "
+#~ "att försöka att säkerställa att ingen dokumentation någonsin går "
+#~ "förlorad.)"
+
+#~ 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 ""
+#~ "Sedan GTK-Doc 1.9 kan mallar 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 "
+#~ "helt hoppar över tmpl-användning. Om du inte ändrat i någon fil i tmpl "
+#~ "för hand, ta bort katalogen (t.ex. från versionshanteringssystemet)."
+
+#~ msgid "1.12"
+#~ msgstr "1.12"
+
+#~ msgid "Chris"
+#~ msgstr "Chris"
+
+#~ msgid "Lyttle"
+#~ msgstr "Lyttle"
+
+#~ msgid "chris@wilddev.net"
+#~ msgstr "chris@wilddev.net"
+
+#~ msgid "Dan"
+#~ msgstr "Dan"
+
+#~ msgid "Mueth"
+#~ msgstr "Mueth"
+
+#~ msgid "d-mueth@uchicago.edu"
+#~ msgstr "d-mueth@uchicago.edu"
+
+#~ msgid "Stefan"
+#~ msgstr "Stefan"
+
+#~ msgid "Kost"
+#~ msgstr "Kost"
+
+#~ msgid "ensonic@users.sf.net"
+#~ msgstr "ensonic@users.sf.net"
+
+#~ msgid "gtk-doc-list@gnome.org"
+#~ msgstr "gtk-doc-list@gnome.org"
+
+#~ msgid "2000, 2005, 2007-2009"
+#~ msgstr "2000, 2005, 2007-2009"
+
+#~ msgid "Dan Mueth and Chris Lyttle and Stefan Kost"
+#~ msgstr "Dan Mueth, Chris Lyttle och Stefan Kost"
+
+#~ msgid "1.11"
+#~ msgstr "1.11"
+
+#~ msgid "22 March 2008"
+#~ msgstr "22 mars 2008"
+
+#~ msgid "mal"
+#~ msgstr "mal"
+
+#~ msgid "explanation"
+#~ msgstr "förklaring"
<revhistory>
<revision>
- <revnumber>1.24.1</revnumber>
- <date>30 May 2015</date>
+ <revnumber>1.25.1</revnumber>
+ <date>21 March 2016</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development version</revremark>
+ </revision>
+ <revision>
+ <revnumber>1.25</revnumber>
+ <date>21 March 2016</date>
<authorinitials>ss</authorinitials>
- <revremark>development version</revremark>
+ <revremark>bug fixes, test cleanups</revremark>
</revision>
<revision>
<revnumber>1.24</revnumber>
</para>
</listitem>
- <listitem>
- <para>
- <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.)
- </para>
- <note>
- <para>
- 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).
- </para>
- </note>
- </listitem>
-
<listitem>
<para>
<guilabel>Generating the XML and HTML/PDF.</guilabel>
document called <filename><package>.pdf</filename>.
</para>
<para>
- Files in <filename class="directory">xml/</filename> and
+ 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>ஜிடிகே டாக் GTK-Doc முன்னிருப்பாக செயலிழந்து இருக்கும்! ஆகவே அடுத்த <filename>configure</filename> இயக்கத்துக்கு இந்த தேர்வை செய்க: <option>'--enable-gtk-doc'</option> . இல்லையானால் முன் உருவாக்கிய ஆவணங்கள் நிறூவப்படும்.( இது பயனர்களுக்கு புரியும், நல்லது. ஆனால் உருவாக்குவோருக்கு அல்ல).</para>
</important>
- <para> மேலும் பின் வரும் வரியை உங்கள் <filename>configure.ac</filename> குறுநிரலில் அமைத்துக்கொள்க. இது <application>gtkdocize</application> நிரலை தானியங்கியாக <function>GTK_DOC_CHECK</function> இன் மேக்ரோ அறிதியீட்டை உங்கள் திட்டத்துக்கு பிரதி எடுக்கிறது.</para>
+ <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>
<example><title>gtkdocize க்கு முன்னேற்பாடு</title>
<title>ஆட்டோமேக் உடன் ஒருங்கிணைப்பு</title>
<para>
- First copy the <filename>Makefile.am</filename> from the
+ 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.
+ 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>
<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.
+ hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<title>Limitations</title>
<para>
Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
+ <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
<code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
</para>
</note>
<para>
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>
+ 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>.
</para>
<varlistentry>
<term>SECTION:<பெயர்></term>
<listitem>
- <para>பகுதி ஆவணத்தை பெயர் <filename><package>-sections.txt</filename>கோப்புக்கு இணைக்கிறது. கொடுக்கப்பட்ட பெயர் <filename><package>-sections.txt</filename> கோப்பில் <FILE> குறிப்புடன் பொருந்த வேண்டும்.</para>
+ <para>
+ The name links the section documentation to the respective part in
+ the <filename><package>-sections.txt</filename> file. The
+ name given here should match the <FILE> tag in the
+ <filename><package>-sections.txt</filename> file.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
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
+ of the supported tags can be found on
<ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
</para>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Inline program documentation</title>
+ <para>
+ You can document programs and their commandline interface using inline
+ documentation.
+ </para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>
+ Defines the start of a program documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>
+ Defines a short description of the program. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>
+ Defines the arguments, or list of arguments that the program can take.
+ (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>
+ See Also manual page section. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>
+ Argument(s) passed to the program and their description. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ A longer description of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>திருப்பிகிடைப்பவை:</term>
+ <listitem>
+ <para>
+ Specificy what value(s) the program returns. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Example of program documentation.</title>
+ <example><title>Program documentation block</title>
+ <programlisting><![CDATA[
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+]]></programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>Useful DocBook tags</title>
In addition a few option elements are created in commented form. You can
review these and enable them as you like.
</para>
-
+
<para>
<example><title>Optional part in the master document</title>
<programlisting><![CDATA[
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
+ -->
]]></programlisting>
</example>
</para>
-
+
<para>
Finally you need to add new section whenever you introduce one. The
<link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
Blank lines are ignored and lines starting with a '#' are treated as
comment lines.
</para>
-
+
<note>
<para>
While the tags make the file look like xml, it is not. Please do not
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizing the documentation</title>
-
+
<para>
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.
</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
When using xml instead of sgml, one can actually name the master
document <filename><package>-docs.xml</filename>.
</para>
-
+
<para>
This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
in <filename>Makefile.am</filename>. When this is enabled, the
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
+ maintained section file can be as simple as running
<code>meld <package>-decl-list.txt <package>-sections.txt</code>.
</para>
-
+
<para>
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 you source control system and haven't yet switched, just
+ checked into your source control system and haven't yet switched, just
add the flag to <filename>configure.ac</filename> and you are done.
</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
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 any example that shows how the entity file is included
+ 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.
<revhistory>
<revision>
- <revnumber>1.24.1</revnumber>
- <date>30 May 2015</date>
+ <revnumber>1.25.1</revnumber>
+ <date>21 March 2016</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development version</revremark>
+ </revision>
+ <revision>
+ <revnumber>1.25</revnumber>
+ <date>21 March 2016</date>
<authorinitials>ss</authorinitials>
- <revremark>development version</revremark>
+ <revremark>bug fixes, test cleanups</revremark>
</revision>
<revision>
<revnumber>1.24</revnumber>
</para>
</listitem>
- <listitem>
- <para>
- <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.)
- </para>
- <note>
- <para>
- 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).
- </para>
- </note>
- </listitem>
-
<listitem>
<para>
<guilabel>Generating the XML and HTML/PDF.</guilabel>
document called <filename><package>.pdf</filename>.
</para>
<para>
- Files in <filename class="directory">xml/</filename> and
+ 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>GTK-Doc అప్రమేయంగా అచేతనము చేయబడింది! ఐచ్చికము <option>'--enable-gtk-doc'</option>ను తరువాతి <filename>configure</filename>కు నడుపుట మర్చిపోవద్దు. లేకపోతే ముందుగా జనియింపచేసిన పత్రికీకరణ సంస్థాపించబడుతుంది (ఇది వినియోగదారులకు వుపయోగకరం అయితే అభివృద్దికారులకు కాదు).</para>
</important>
- <para>మీ <filename>configure.ac</filename> స్క్రిప్టునందు ఈ క్రింది వరుసను కలిగివుండుట చాలామంచిది. ఇది మీ ప్రోజెక్టునందు <function>GTK_DOC_CHECK</function> కొరకు స్వయంచాలకంగా మాక్రో నిర్వచనాన్ని నకలు తీయుటకు <application>gtkdocize</application>ను అనుమతిస్తుంది.</para>
+ <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>
<example><title>gtkdocize కొరకు సన్నాహం</title>
<title>automake తో విలీనం</title>
<para>
- First copy the <filename>Makefile.am</filename> from the
+ 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.
+ 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>
<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.
+ hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<title>Limitations</title>
<para>
Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
+ <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
<code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
</para>
</note>
<para>
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>
+ 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>.
</para>
<varlistentry>
<term>SECTION:<name></term>
<listitem>
- <para>నామము అనునది విభాగపు పత్రికీకరణను <filename><package>-sections.txt</filename> ఫైలునందలి సంభందిత భాగమునకు లింకుచేయును. ఇక్కడ యిచ్చిన నామము <filename><package>-sections.txt</filename> ఫైలునందలి <FILE> టాగ్తో సరిపోలవలెను.</para>
+ <para>
+ The name links the section documentation to the respective part in
+ the <filename><package>-sections.txt</filename> file. The
+ name given here should match the <FILE> tag in the
+ <filename><package>-sections.txt</filename> file.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
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
+ of the supported tags can be found on
<ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
</para>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Inline program documentation</title>
+ <para>
+ You can document programs and their commandline interface using inline
+ documentation.
+ </para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>
+ Defines the start of a program documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>
+ Defines a short description of the program. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>
+ Defines the arguments, or list of arguments that the program can take.
+ (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>
+ See Also manual page section. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>
+ Argument(s) passed to the program and their description. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ A longer description of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>తిరిగివచ్చినవి:</term>
+ <listitem>
+ <para>
+ Specificy what value(s) the program returns. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Example of program documentation.</title>
+ <example><title>Program documentation block</title>
+ <programlisting><![CDATA[
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+]]></programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>ఉపయోగకర DocBook టాగ్స్</title>
In addition a few option elements are created in commented form. You can
review these and enable them as you like.
</para>
-
+
<para>
<example><title>Optional part in the master document</title>
<programlisting><![CDATA[
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
+ -->
]]></programlisting>
</example>
</para>
-
+
<para>
Finally you need to add new section whenever you introduce one. The
<link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
Blank lines are ignored and lines starting with a '#' are treated as
comment lines.
</para>
-
+
<note>
<para>
While the tags make the file look like xml, it is not. Please do not
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizing the documentation</title>
-
+
<para>
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.
</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
When using xml instead of sgml, one can actually name the master
document <filename><package>-docs.xml</filename>.
</para>
-
+
<para>
This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
in <filename>Makefile.am</filename>. When this is enabled, the
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
+ maintained section file can be as simple as running
<code>meld <package>-decl-list.txt <package>-sections.txt</code>.
</para>
-
+
<para>
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 you source control system and haven't yet switched, just
+ checked into your source control system and haven't yet switched, just
add the flag to <filename>configure.ac</filename> and you are done.
</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
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 any example that shows how the entity file is included
+ 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.
<revhistory>
<revision>
- <revnumber>1.24.1</revnumber>
- <date>30 May 2015</date>
+ <revnumber>1.25.1</revnumber>
+ <date>21 March 2016</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>development version</revremark>
+ </revision>
+ <revision>
+ <revnumber>1.25</revnumber>
+ <date>21 March 2016</date>
<authorinitials>ss</authorinitials>
- <revremark>development version</revremark>
+ <revremark>bug fixes, test cleanups</revremark>
</revision>
<revision>
<revnumber>1.24</revnumber>
</para>
</listitem>
- <listitem>
- <para>
- <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.)
- </para>
- <note>
- <para>
- 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).
- </para>
- </note>
- </listitem>
-
<listitem>
<para>
<guilabel>Generating the XML and HTML/PDF.</guilabel>
document called <filename><package>.pdf</filename>.
</para>
<para>
- Files in <filename class="directory">xml/</filename> and
+ 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>GTK-Doc在默认情况下是关闭的！请记得给文本<filename>configure</filename>运作时传递<option>'--enable-gtk-doc'</option>选项。否则，将会安装预先生成的文档（对用户有意义但对开发人员没用处）。</para>
</important>
- <para>而且建议你在<filename>configure.ac</filename>脚本里拥有这样一行。它允许<application>gtkdocize</application>将<function>GTK_DOC_CHECK</function>的宏定义复制到您的项目中去。</para>
+ <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>
<example><title>准备gtkdocize</title>
<title>与automake集成</title>
<para>
- First copy the <filename>Makefile.am</filename> from the
+ 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.
+ 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>
<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.
+ hint GTK-Doc to skip over them.
<example><title>GTK-Doc comment block</title>
<programlisting><![CDATA[
#ifndef __GTK_DOC_IGNORE__
<title>Limitations</title>
<para>
Note, that GTK-Doc's supports
- <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
+ <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
<code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
</para>
</note>
<para>
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>
+ 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>.
</para>
<varlistentry>
<term>SECTION:<name></term>
<listitem>
- <para>名字链接这节文档到文件<filename><package>-sections.txt</filename>中对应的部分。这里的名字应匹配<filename><package>-sections.txt</filename>文件中的<FILE>标识。</para>
+ <para>
+ The name links the section documentation to the respective part in
+ the <filename><package>-sections.txt</filename> file. The
+ name given here should match the <FILE> tag in the
+ <filename><package>-sections.txt</filename> file.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
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
+ of the supported tags can be found on
<ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
</para>
</sect2>
</sect1>
+
+ <sect1 id="documenting_inline_program">
+ <title>Inline program documentation</title>
+ <para>
+ You can document programs and their commandline interface using inline
+ documentation.
+ </para>
+
+ <variablelist>
+ <title>Tags</title>
+
+ <varlistentry><term>PROGRAM</term>
+
+ <listitem>
+ <para>
+ Defines the start of a program documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@short_description:</term>
+ <listitem>
+ <para>
+ Defines a short description of the program. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@synopsis:</term>
+ <listitem>
+ <para>
+ Defines the arguments, or list of arguments that the program can take.
+ (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@see_also:</term>
+ <listitem>
+ <para>
+ See Also manual page section. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>@arg:</term>
+ <listitem>
+ <para>
+ Argument(s) passed to the program and their description. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Description:</term>
+ <listitem>
+ <para>
+ A longer description of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>返回值：</term>
+ <listitem>
+ <para>
+ Specificy what value(s) the program returns. (Optional)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect2>
+ <title>Example of program documentation.</title>
+ <example><title>Program documentation block</title>
+ <programlisting><![CDATA[
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @--arg2 *arg*: set arg2 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+int main(int argc, char *argv[])
+{
+ return 0;
+}
+]]></programlisting>
+ </example>
+
+ </sect2>
+ </sect1>
+
<sect1 id="documenting_docbook">
<title>有用的DocBook标记</title>
In addition a few option elements are created in commented form. You can
review these and enable them as you like.
</para>
-
+
<para>
<example><title>Optional part in the master document</title>
<programlisting><![CDATA[
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
- -->
+ -->
]]></programlisting>
</example>
</para>
-
+
<para>
Finally you need to add new section whenever you introduce one. The
<link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
Blank lines are ignored and lines starting with a '#' are treated as
comment lines.
</para>
-
+
<note>
<para>
While the tags make the file look like xml, it is not. Please do not
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
</para>
</chapter>
-
+
<chapter id="modernizing">
<title>Modernizing the documentation</title>
-
+
<para>
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.
</para>
-
+
<sect1 id="modernizing-gtk-doc-1-9">
<title>GTK-Doc 1.9</title>
When using xml instead of sgml, one can actually name the master
document <filename><package>-docs.xml</filename>.
</para>
-
+
<para>
This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
in <filename>Makefile.am</filename>. When this is enabled, the
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
+ maintained section file can be as simple as running
<code>meld <package>-decl-list.txt <package>-sections.txt</code>.
</para>
-
+
<para>
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 you source control system and haven't yet switched, just
+ checked into your source control system and haven't yet switched, just
add the flag to <filename>configure.ac</filename> and you are done.
</para>
</sect1>
-
+
<sect1 id="modernizing-gtk-doc-1-10">
<title>GTK-Doc 1.10</title>
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 any example that shows how the entity file is included
+ 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.
## Process this file with automake to produce Makefile.in
-SUBDIRS = gobject bugs annotations fail empty .
+SUBDIRS = gobject bugs annotations fail empty program .
if BUILD_TESTS
TESTS = \
- gtkdoc-common.t gtkdoc-fixxref.t gtkdoc-mkdb.t gtkdoc-rebase.t gtkdoc-scan.t \
- tools.sh gobject.sh bugs.sh annotations.sh fail.sh empty.sh sanity.sh
+ check.py common.py mk_to_db.py \
+ tools.sh gobject.sh bugs.sh annotations.sh fail.sh empty.sh sanity.sh \
+ program.sh
TESTS_ENVIRONMENT = \
BUILDDIR=$(abs_builddir) \
SRCDIR=$(abs_srcdir) \
ABS_TOP_BUILDDIR=$(abs_top_builddir) \
ABS_TOP_SRCDIR=$(abs_top_srcdir) \
PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
- PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
+ PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ GLIB_PREFIX="$(glib_prefix)"
endif
-EXTRA_DIST = gtkdoctest.sh tools.sh sanity.sh \
- gobject.sh bugs.sh annotations.sh fail.sh empty.sh \
- gtkdoc-common.t gtkdoc-fixxref.t gtkdoc-mkdb.t gtkdoc-rebase.t gtkdoc-scan.t
-
+EXTRA_DIST = gtkdoctest.sh $(TESTS)
# run any given test by running make <test>.check
%.check: %
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
-SUBDIRS = gobject bugs annotations fail empty .
+SUBDIRS = gobject bugs annotations fail empty program .
@BUILD_TESTS_TRUE@TESTS = \
-@BUILD_TESTS_TRUE@ gtkdoc-common.t gtkdoc-fixxref.t gtkdoc-mkdb.t gtkdoc-rebase.t gtkdoc-scan.t \
-@BUILD_TESTS_TRUE@ tools.sh gobject.sh bugs.sh annotations.sh fail.sh empty.sh sanity.sh
+@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@TESTS_ENVIRONMENT = \
@BUILD_TESTS_TRUE@ BUILDDIR=$(abs_builddir) \
@BUILD_TESTS_TRUE@ ABS_TOP_BUILDDIR=$(abs_top_builddir) \
@BUILD_TESTS_TRUE@ ABS_TOP_SRCDIR=$(abs_top_srcdir) \
@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
-@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
-
-EXTRA_DIST = gtkdoctest.sh tools.sh sanity.sh \
- gobject.sh bugs.sh annotations.sh fail.sh empty.sh \
- gtkdoc-common.t gtkdoc-fixxref.t gtkdoc-mkdb.t gtkdoc-rebase.t gtkdoc-scan.t
+@BUILD_TESTS_TRUE@ PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+@BUILD_TESTS_TRUE@ GLIB_PREFIX="$(glib_prefix)"
+EXTRA_DIST = gtkdoctest.sh $(TESTS)
all: all-recursive
.SUFFIXES:
am__force_recheck=am--force-recheck \
TEST_LOGS="$$log_list"; \
exit $$?
-gtkdoc-common.t.log: gtkdoc-common.t
- @p='gtkdoc-common.t'; \
- b='gtkdoc-common.t'; \
+check.py.log: check.py
+ @p='check.py'; \
+ b='check.py'; \
$(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)
-gtkdoc-fixxref.t.log: gtkdoc-fixxref.t
- @p='gtkdoc-fixxref.t'; \
- b='gtkdoc-fixxref.t'; \
+common.py.log: common.py
+ @p='common.py'; \
+ b='common.py'; \
$(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)
-gtkdoc-mkdb.t.log: gtkdoc-mkdb.t
- @p='gtkdoc-mkdb.t'; \
- b='gtkdoc-mkdb.t'; \
- $(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)
-gtkdoc-rebase.t.log: gtkdoc-rebase.t
- @p='gtkdoc-rebase.t'; \
- b='gtkdoc-rebase.t'; \
- $(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)
-gtkdoc-scan.t.log: gtkdoc-scan.t
- @p='gtkdoc-scan.t'; \
- b='gtkdoc-scan.t'; \
+mk_to_db.py.log: mk_to_db.py
+ @p='mk_to_db.py'; \
+ b='mk_to_db.py'; \
$(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)
+program.sh.log: program.sh
+ @p='program.sh'; \
+ b='program.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)
.test.log:
@p='$<'; \
$(am__set_b); \
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS=--xml-mode
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS=
-
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS=
GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/annotations/src/libtester.la
# include generic part
-include $(top_srcdir)/tests/gtk-doc.notmpl.make
+include $(top_srcdir)/tests/gtk-doc.make
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
-DIST_COMMON = $(top_srcdir)/tests/gtk-doc.notmpl.make \
- $(srcdir)/Makefile.in $(srcdir)/Makefile.am
+DIST_COMMON = $(top_srcdir)/tests/gtk-doc.make $(srcdir)/Makefile.in \
+ $(srcdir)/Makefile.am
subdir = tests/annotations/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS = --xml-mode
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS =
-
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS =
CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \
$(DOC_MODULE).pdf ts gtkdoc-scan.log gtkdoc-scangobj.log \
- gtkdoc-mktmpl.log gtkdoc-mkdb.log gtkdoc-mkhtml.log \
- gtkdoc-mkpdf.log gtkdoc-fixxref.log \
- $(DOC_MODULE)-overrides.txt
+ gtkdoc-mkdb.log gtkdoc-mkhtml.log gtkdoc-mkpdf.log \
+ gtkdoc-fixxref.log $(DOC_MODULE)-overrides.txt
GITIGNOREFILES = \
html.ref xml.ref
all: all-am
.SUFFIXES:
-$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.notmpl.make $(am__configure_deps)
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.make $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
esac;
-$(top_srcdir)/tests/gtk-doc.notmpl.make:
+$(top_srcdir)/tests/gtk-doc.make:
$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
setup-build.stamp: ts
-@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- echo ' DOC Preparing build'; \
- files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
- if test "x$$files" != "x" ; then \
- for file in $$files ; do \
- test -f $(abs_srcdir)/$$file && \
- cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
- done; \
- fi; \
+ echo ' DOC Preparing build'; \
+ files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
+ if test "x$$files" != "x" ; then \
+ for file in $$files ; do \
+ test -f $(abs_srcdir)/$$file && \
+ cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
+ done; \
+ fi; \
fi
@touch setup-build.stamp
echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files"
@_source_dir='' ; \
for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log
@if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
- scanobj_options=""; \
- if test "x$(V)" = "x1"; then \
- scanobj_options="--verbose"; \
- fi; \
- echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
- CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
- gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
+ scanobj_options=""; \
+ if test "x$(V)" = "x1"; then \
+ scanobj_options="--verbose"; \
+ fi; \
+ echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
+ gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
else \
- for i in $(SCANOBJ_FILES) ; do \
- test -f $$i || touch $$i ; \
- done \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
fi
@touch scan-build.stamp
_source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log
@touch sgml-build.stamp
mkhtml_options="$$mkhtml_options --verbose"; \
fi; \
echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \
- cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log
-@test "x$(HTML_IMAGES)" = "x" || \
for file in $(HTML_IMAGES) ; do \
@ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references"
@echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log
@touch html-build.stamp
done; \
fi; \
echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log
@touch pdf-build.stamp
annotation_skip_return
annotation_scope
annotation_rename_to
+annotation_attributes_single
+annotation_attributes_single_eq
stability_unstable
annotation_multiline_on_function
annotation_multiline_on_function2
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
{
}
+/**
+ * annotation_attributes_single: (attributes key value)
+ *
+ * Documentation for this function.
+ */
+void
+annotation_attributes_single (void)
+{
+}
+
+/**
+ * annotation_attributes_single_eq: (attributes key=value)
+ *
+ * Documentation for this function.
+ */
+void
+annotation_attributes_single_eq (void)
+{
+}
+
/**
* stability_unstable:
*
void annotation_rename_to (void);
+void annotation_attributes_single (void);
+void annotation_attributes_single_eq (void);
+
void stability_unstable(void);
void annotation_multiline_on_function (void);
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS=--xml-mode
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS=
-
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS=
GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/bugs/src/libtester.la
# include generic part
-include $(top_srcdir)/tests/gtk-doc.notmpl.make
+include $(top_srcdir)/tests/gtk-doc.make
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
-DIST_COMMON = $(top_srcdir)/tests/gtk-doc.notmpl.make \
- $(srcdir)/Makefile.in $(srcdir)/Makefile.am
+DIST_COMMON = $(top_srcdir)/tests/gtk-doc.make $(srcdir)/Makefile.in \
+ $(srcdir)/Makefile.am
subdir = tests/bugs/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS = --xml-mode
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS =
-
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS =
CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \
$(DOC_MODULE).pdf ts gtkdoc-scan.log gtkdoc-scangobj.log \
- gtkdoc-mktmpl.log gtkdoc-mkdb.log gtkdoc-mkhtml.log \
- gtkdoc-mkpdf.log gtkdoc-fixxref.log \
- $(DOC_MODULE)-overrides.txt $(DOC_MODULE).types
+ gtkdoc-mkdb.log gtkdoc-mkhtml.log gtkdoc-mkpdf.log \
+ gtkdoc-fixxref.log $(DOC_MODULE)-overrides.txt \
+ $(DOC_MODULE).types
GITIGNOREFILES = \
html.ref xml.ref
all: all-am
.SUFFIXES:
-$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.notmpl.make $(am__configure_deps)
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.make $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
esac;
-$(top_srcdir)/tests/gtk-doc.notmpl.make:
+$(top_srcdir)/tests/gtk-doc.make:
$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
setup-build.stamp: ts
-@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- echo ' DOC Preparing build'; \
- files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
- if test "x$$files" != "x" ; then \
- for file in $$files ; do \
- test -f $(abs_srcdir)/$$file && \
- cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
- done; \
- fi; \
+ echo ' DOC Preparing build'; \
+ files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
+ if test "x$$files" != "x" ; then \
+ for file in $$files ; do \
+ test -f $(abs_srcdir)/$$file && \
+ cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
+ done; \
+ fi; \
fi
@touch setup-build.stamp
echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files"
@_source_dir='' ; \
for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log
@if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
- scanobj_options=""; \
- if test "x$(V)" = "x1"; then \
- scanobj_options="--verbose"; \
- fi; \
- echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
- CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
- gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
+ scanobj_options=""; \
+ if test "x$(V)" = "x1"; then \
+ scanobj_options="--verbose"; \
+ fi; \
+ echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
+ gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
else \
- for i in $(SCANOBJ_FILES) ; do \
- test -f $$i || touch $$i ; \
- done \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
fi
@touch scan-build.stamp
_source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log
@touch sgml-build.stamp
mkhtml_options="$$mkhtml_options --verbose"; \
fi; \
echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \
- cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log
-@test "x$(HTML_IMAGES)" = "x" || \
for file in $(HTML_IMAGES) ; do \
@ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references"
@echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log
@touch html-build.stamp
done; \
fi; \
echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log
@touch pdf-build.stamp
deprecation_notice
bug_741941
bug_732689
+bug_783420
gst_play_marshal_BUFFER__BOXED
<SUBSECTION Standard>
<SUBSECTION Private>
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
}
-/**
- * Bug446648:
- * @BUG_446648_FOO: foo
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=446648
- **/
-
-
/**
* bug_552602:
*
bug_749142 (void)
{
}
+
+/**
+ * bug_783420:
+ * @in: input
+ * @out: output
+ *
+ * http://bugzilla.gnome.org/show_bug.cgi?id=783420
+ *
+ * |[
+ * #include <tester.h>
+ *
+ * int res;
+ * bug_783420(42, &res);
+ * ]|
+ *
+ * <refsect2 id="subsect">
+ * <title>Subsection</title>
+ * <para>
+ * Lorem ipsum ...
+ * |[
+ * #include <tester.h>
+ *
+ * int res;
+ * bug_783420(42, &res);
+ * ]|
+ * </para>
+ * </refsect2>
+ */
+void
+bug_783420 (int in, int *out)
+{
+}
\ No newline at end of file
/**
* Bug446648:
- * @BUG_446648_FOO: field
+ * @BUG_446648_FOO: foo
*
* http://bugzilla.gnome.org/show_bug.cgi?id=446648
*/
void bug_732689 (const gchar *spec);
void bug_749142 (void);
+void bug_783420 (int in, int *out);
/**
* BUG_731417_DEPRECATED:
*/
#define MACRO_FUNCTION(x) (x << 1)
+/**
+ * _:
+ * @str: a string
+ *
+ * https://bugzilla.gnome.org/show_bug.cgi?id=753052
+ */
+#define _(str) str
+
#endif // GTKDOC_TESTER_H
--- /dev/null
+#!/usr/bin/env python
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2017 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 unittest
+
+from gtkdoc import check
+
+
+class TestCheck(unittest.TestCase):
+
+ def test_grep_finds_token_in_one_line(self):
+ result = check.grep(r'^(foo)', ['foo'], 'foo')
+ self.assertEqual('foo', result)
+
+ def test_grep_does_not_find_token(self):
+ with self.assertRaises(check.FileFormatError) as ctx:
+ check.grep(r'^(foo)', ['bar'], 'foo')
+ self.assertEqual(str(ctx.exception), 'foo')
+
+ def test_get_variable_prefers_env(self):
+ result = check.get_variable({'foo': 'bar'}, ['foo=baz'], 'foo')
+ self.assertEqual('bar', result)
+
+ def test_get_variable_finds_in_file(self):
+ result = check.get_variable({}, ['foo=bar'], 'foo')
+ self.assertEqual('bar', result)
+
+ def test_get_variable_finds_in_file_with_whitespce(self):
+ result = check.get_variable({}, ['foo = bar'], 'foo')
+ self.assertEqual('bar', result)
+
+
+if __name__ == '__main__':
+ unittest.main()
--- /dev/null
+#!/usr/bin/env python
+#!/usr/bin/env python
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2017 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 mock
+import unittest
+
+from gtkdoc import common
+
+
+class TestUpdateFileIfChanged(unittest.TestCase):
+
+ @mock.patch('os.path.exists')
+ @mock.patch('os.rename')
+ def test_NoOldFile(self, os_rename, os_path_exists):
+ os_path_exists.return_value = False
+ res = common.UpdateFileIfChanged('/old', '/new', False)
+ os_rename.assert_called_with('/new', '/old')
+ self.assertTrue(res)
+
+ @mock.patch('os.path.exists')
+ @mock.patch('__builtin__.open', mock.mock_open(read_data='bar'))
+ @mock.patch('os.unlink')
+ def test_FilesAreTheSame(self, os_unlink, os_path_exists):
+ os_path_exists.return_value = True
+ res = common.UpdateFileIfChanged('/old', '/new', False)
+ os_unlink.assert_called_with('/new')
+ self.assertFalse(res)
+
+
+class TestGetModuleDocDir(unittest.TestCase):
+
+ @mock.patch('subprocess.check_output')
+ def test_ReturnsPath(self, subprocess_check_output):
+ subprocess_check_output.return_value = '/usr'
+ self.assertEquals(common.GetModuleDocDir('glib-2.0'), '/usr/share/gtk-doc/html')
+
+
+class TestCreateValidSGMLID(unittest.TestCase):
+
+ def test_AlreadyValid(self):
+ self.assertEquals(common.CreateValidSGMLID('x'), 'x')
+
+ def test_SpecialCharsBecomeDash(self):
+ self.assertEquals(common.CreateValidSGMLID('x_ y'), 'x--y')
+
+ def test_SpecialCharsGetRemoved(self):
+ self.assertEquals(common.CreateValidSGMLID('x,;y'), 'xy')
+
+
+if __name__ == '__main__':
+ unittest.main()
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS=--xml-mode
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS=
-
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS=
GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/empty/src/libtester.la
# include generic part
-include $(top_srcdir)/tests/gtk-doc.notmpl.make
+include $(top_srcdir)/tests/gtk-doc.make
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
-DIST_COMMON = $(top_srcdir)/tests/gtk-doc.notmpl.make \
- $(srcdir)/Makefile.in $(srcdir)/Makefile.am
+DIST_COMMON = $(top_srcdir)/tests/gtk-doc.make $(srcdir)/Makefile.in \
+ $(srcdir)/Makefile.am
subdir = tests/empty/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS = --xml-mode
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS =
-
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS =
CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \
$(DOC_MODULE).pdf ts gtkdoc-scan.log gtkdoc-scangobj.log \
- gtkdoc-mktmpl.log gtkdoc-mkdb.log gtkdoc-mkhtml.log \
- gtkdoc-mkpdf.log gtkdoc-fixxref.log \
- $(DOC_MODULE)-overrides.txt $(DOC_MODULE).types \
- tester-docs.xml tester-sections.txt
+ gtkdoc-mkdb.log gtkdoc-mkhtml.log gtkdoc-mkpdf.log \
+ gtkdoc-fixxref.log $(DOC_MODULE)-overrides.txt \
+ $(DOC_MODULE).types tester-docs.xml tester-sections.txt
GITIGNOREFILES = \
html.ref xml.ref
all: all-am
.SUFFIXES:
-$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.notmpl.make $(am__configure_deps)
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.make $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
esac;
-$(top_srcdir)/tests/gtk-doc.notmpl.make:
+$(top_srcdir)/tests/gtk-doc.make:
$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
setup-build.stamp: ts
-@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- echo ' DOC Preparing build'; \
- files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
- if test "x$$files" != "x" ; then \
- for file in $$files ; do \
- test -f $(abs_srcdir)/$$file && \
- cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
- done; \
- fi; \
+ echo ' DOC Preparing build'; \
+ files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
+ if test "x$$files" != "x" ; then \
+ for file in $$files ; do \
+ test -f $(abs_srcdir)/$$file && \
+ cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
+ done; \
+ fi; \
fi
@touch setup-build.stamp
echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files"
@_source_dir='' ; \
for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log
@if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
- scanobj_options=""; \
- if test "x$(V)" = "x1"; then \
- scanobj_options="--verbose"; \
- fi; \
- echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
- CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
- gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
+ scanobj_options=""; \
+ if test "x$(V)" = "x1"; then \
+ scanobj_options="--verbose"; \
+ fi; \
+ echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
+ gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
else \
- for i in $(SCANOBJ_FILES) ; do \
- test -f $$i || touch $$i ; \
- done \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
fi
@touch scan-build.stamp
_source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log
@touch sgml-build.stamp
mkhtml_options="$$mkhtml_options --verbose"; \
fi; \
echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \
- cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log
-@test "x$(HTML_IMAGES)" = "x" || \
for file in $(HTML_IMAGES) ; do \
@ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references"
@echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log
@touch html-build.stamp
done; \
fi; \
echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log
@touch pdf-build.stamp
<title>Index of deprecated API</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
+ <index id="api-index-0-1" role="0.1">
+ <title>Index of new API in 0.1</title>
+ <xi:include href="xml/api-index-0.1.xml"><xi:fallback /></xi:include>
+ </index>
<!-- enable this when you use gobject introspection annotations
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-->
<SECTION>
<FILE>tester</FILE>
<TITLE>GtkDocTestIf</TITLE>
+FOO
test
GtkDocTestIfInterface
GtkDocTestIf
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
#include <glib.h>
#include <glib-object.h>
+/**
+ * FOO:
+ *
+ * The FOO.
+ *
+ * Since: 0.1
+ */
+#define FOO "bar"
void test (gint a);
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS=
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS=
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS=
GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/fail/src/libtester.la
# include generic part
-include $(top_srcdir)/tests/gtk-doc.notmpl.make
+include $(top_srcdir)/tests/gtk-doc.make
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
-DIST_COMMON = $(top_srcdir)/tests/gtk-doc.notmpl.make \
- $(srcdir)/Makefile.in $(srcdir)/Makefile.am
+DIST_COMMON = $(top_srcdir)/tests/gtk-doc.make $(srcdir)/Makefile.in \
+ $(srcdir)/Makefile.am
subdir = tests/fail/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS =
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS =
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS =
CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \
$(DOC_MODULE).pdf ts gtkdoc-scan.log gtkdoc-scangobj.log \
- gtkdoc-mktmpl.log gtkdoc-mkdb.log gtkdoc-mkhtml.log \
- gtkdoc-mkpdf.log gtkdoc-fixxref.log \
- $(DOC_MODULE)-overrides.txt
+ gtkdoc-mkdb.log gtkdoc-mkhtml.log gtkdoc-mkpdf.log \
+ gtkdoc-fixxref.log $(DOC_MODULE)-overrides.txt
GITIGNOREFILES = \
html.ref xml.ref
all: all-am
.SUFFIXES:
-$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.notmpl.make $(am__configure_deps)
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.make $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
esac;
-$(top_srcdir)/tests/gtk-doc.notmpl.make:
+$(top_srcdir)/tests/gtk-doc.make:
$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
setup-build.stamp: ts
-@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- echo ' DOC Preparing build'; \
- files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
- if test "x$$files" != "x" ; then \
- for file in $$files ; do \
- test -f $(abs_srcdir)/$$file && \
- cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
- done; \
- fi; \
+ echo ' DOC Preparing build'; \
+ files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
+ if test "x$$files" != "x" ; then \
+ for file in $$files ; do \
+ test -f $(abs_srcdir)/$$file && \
+ cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
+ done; \
+ fi; \
fi
@touch setup-build.stamp
echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files"
@_source_dir='' ; \
for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log
@if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
- scanobj_options=""; \
- if test "x$(V)" = "x1"; then \
- scanobj_options="--verbose"; \
- fi; \
- echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
- CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
- gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
+ scanobj_options=""; \
+ if test "x$(V)" = "x1"; then \
+ scanobj_options="--verbose"; \
+ fi; \
+ echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
+ gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
else \
- for i in $(SCANOBJ_FILES) ; do \
- test -f $$i || touch $$i ; \
- done \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
fi
@touch scan-build.stamp
_source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log
@touch sgml-build.stamp
mkhtml_options="$$mkhtml_options --verbose"; \
fi; \
echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \
- cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log
-@test "x$(HTML_IMAGES)" = "x" || \
for file in $(HTML_IMAGES) ; do \
@ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references"
@echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log
@touch html-build.stamp
done; \
fi; \
echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log
@touch pdf-build.stamp
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS=--xml-mode
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS=
-
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS=
GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/gobject/src/libtester.la
# include generic part
-include $(top_srcdir)/tests/gtk-doc.notmpl.make
+include $(top_srcdir)/tests/gtk-doc.make
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
-DIST_COMMON = $(top_srcdir)/tests/gtk-doc.notmpl.make \
- $(srcdir)/Makefile.in $(srcdir)/Makefile.am
+DIST_COMMON = $(top_srcdir)/tests/gtk-doc.make $(srcdir)/Makefile.in \
+ $(srcdir)/Makefile.am
subdir = tests/gobject/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
# Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS = --xml-mode
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS =
-
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS =
CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \
$(DOC_MODULE).pdf ts gtkdoc-scan.log gtkdoc-scangobj.log \
- gtkdoc-mktmpl.log gtkdoc-mkdb.log gtkdoc-mkhtml.log \
- gtkdoc-mkpdf.log gtkdoc-fixxref.log \
- $(DOC_MODULE)-overrides.txt $(DOC_MODULE).types
+ gtkdoc-mkdb.log gtkdoc-mkhtml.log gtkdoc-mkpdf.log \
+ gtkdoc-fixxref.log $(DOC_MODULE)-overrides.txt \
+ $(DOC_MODULE).types
GITIGNOREFILES = \
html.ref xml.ref
all: all-am
.SUFFIXES:
-$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.notmpl.make $(am__configure_deps)
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.make $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
esac;
-$(top_srcdir)/tests/gtk-doc.notmpl.make:
+$(top_srcdir)/tests/gtk-doc.make:
$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
setup-build.stamp: ts
-@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- echo ' DOC Preparing build'; \
- files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
- if test "x$$files" != "x" ; then \
- for file in $$files ; do \
- test -f $(abs_srcdir)/$$file && \
- cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
- done; \
- fi; \
+ echo ' DOC Preparing build'; \
+ files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
+ if test "x$$files" != "x" ; then \
+ for file in $$files ; do \
+ test -f $(abs_srcdir)/$$file && \
+ cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
+ done; \
+ fi; \
fi
@touch setup-build.stamp
echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files"
@_source_dir='' ; \
for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log
@if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
- scanobj_options=""; \
- if test "x$(V)" = "x1"; then \
- scanobj_options="--verbose"; \
- fi; \
- echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
- CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
- gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
+ scanobj_options=""; \
+ if test "x$(V)" = "x1"; then \
+ scanobj_options="--verbose"; \
+ fi; \
+ echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
+ gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
else \
- for i in $(SCANOBJ_FILES) ; do \
- test -f $$i || touch $$i ; \
- done \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
fi
@touch scan-build.stamp
_source_dir="$${_source_dir} --source-dir=$$i" ; \
done ; \
echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log
@touch sgml-build.stamp
mkhtml_options="$$mkhtml_options --verbose"; \
fi; \
echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \
- cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log
-@test "x$(HTML_IMAGES)" = "x" || \
for file in $(HTML_IMAGES) ; do \
@ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references"
@echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log
@touch html-build.stamp
done; \
fi; \
echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log
@touch pdf-build.stamp
endif
-
-include $(top_srcdir)/git.mk
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
-PERL = @PERL@
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@
* A new instance can be created using the gtkdoc_object_new() function. The
* whole lifecycle usualy looks like shown in this example:
* |[<!-- language="C" -->
+ * #include <glib.h>
+ * #include <glib-object.h>
+ *
* GObject *myobj;
*
* myobj = gtkdoc_object_new();
--- /dev/null
+# -*- mode: makefile -*-
+
+####################################
+# Everything below here is generic #
+####################################
+
+if GTK_DOC_USE_LIBTOOL
+GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
+GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS)
+GTKDOC_RUN = $(LIBTOOL) --mode=execute
+else
+GTKDOC_CC = $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
+GTKDOC_LD = $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS)
+GTKDOC_RUN =
+endif
+
+# We set GPATH here; this gives us semantics for GNU make
+# which are more like other make's VPATH, when it comes to
+# whether a source that is a target of one rule is then
+# searched for in VPATH/GPATH.
+#
+GPATH = $(srcdir)
+
+# we don't install anything in tests
+#TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
+
+SETUP_FILES = \
+ $(content_files) \
+ $(DOC_MAIN_SGML_FILE) \
+ $(DOC_MODULE)-sections.txt \
+ $(DOC_MODULE)-overrides.txt
+
+EXTRA_DIST = \
+ $(HTML_IMAGES) \
+ $(SETUP_FILES)
+
+DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \
+ html-build.stamp pdf-build.stamp \
+ sgml.stamp html.stamp pdf.stamp
+
+SCANOBJ_FILES = \
+ $(DOC_MODULE).args \
+ $(DOC_MODULE).hierarchy \
+ $(DOC_MODULE).interfaces \
+ $(DOC_MODULE).prerequisites \
+ $(DOC_MODULE).signals
+
+REPORT_FILES = \
+ $(DOC_MODULE)-undocumented.txt \
+ $(DOC_MODULE)-undeclared.txt \
+ $(DOC_MODULE)-unused.txt
+
+CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \
+ $(DOC_MODULE).pdf \
+ ts \
+ gtkdoc-scan.log \
+ gtkdoc-scangobj.log \
+ gtkdoc-mkdb.log \
+ gtkdoc-mkhtml.log \
+ gtkdoc-mkpdf.log \
+ gtkdoc-fixxref.log
+
+GITIGNOREFILES = \
+ html.ref xml.ref
+
+check-local: html-build.stamp pdf-build.stamp
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: All done"
+
+docs: html-build.stamp pdf-build.stamp
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: All done"
+
+$(REPORT_FILES): sgml-build.stamp
+
+ts:
+ @echo >ts `date $(TS_FMT)`;
+
+#### setup ####
+
+setup-build.stamp: ts
+ -@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
+ echo ' DOC Preparing build'; \
+ files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
+ if test "x$$files" != "x" ; then \
+ for file in $$files ; do \
+ test -f $(abs_srcdir)/$$file && \
+ cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
+ done; \
+ fi; \
+ fi
+ @touch setup-build.stamp
+
+#### scan ####
+
+scan-build.stamp: ts setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files"
+ @_source_dir='' ; \
+ for i in $(DOC_SOURCE_DIR) ; do \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ done ; \
+ echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log
+ @if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
+ ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
+ scanobj_options=""; \
+ if test "x$(V)" = "x1"; then \
+ scanobj_options="--verbose"; \
+ fi; \
+ echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
+ gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
+ else \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
+ fi
+ @touch scan-build.stamp
+
+$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp
+ @true
+
+#### xml ####
+
+sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Building XML"
+ @_source_dir='' ; \
+ for i in $(DOC_SOURCE_DIR) ; do \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ done ; \
+ echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log
+ @touch sgml-build.stamp
+
+sgml.stamp: sgml-build.stamp
+ @true
+
+xml/gtkdocentities.ent: Makefile
+ @$(MKDIR_P) $(@D) && ( \
+ echo "<!ENTITY package \"$(PACKAGE)\">"; \
+ echo "<!ENTITY package_bugreport \"$(PACKAGE_BUGREPORT)\">"; \
+ echo "<!ENTITY package_name \"$(PACKAGE_NAME)\">"; \
+ echo "<!ENTITY package_string \"$(PACKAGE_STRING)\">"; \
+ echo "<!ENTITY package_tarname \"$(PACKAGE_TARNAME)\">"; \
+ echo "<!ENTITY package_url \"$(PACKAGE_URL)\">"; \
+ echo "<!ENTITY package_version \"$(PACKAGE_VERSION)\">"; \
+ ) > $@
+
+#### html ####
+
+html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Building HTML"
+ @rm -rf html
+ @mkdir html
+ @mkhtml_options=""; \
+ if test "x$(V)" = "x1"; then \
+ mkhtml_options="$$mkhtml_options --verbose"; \
+ fi; \
+ echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \
+ cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log
+ -@test "x$(HTML_IMAGES)" = "x" || \
+ for file in $(HTML_IMAGES) ; do \
+ if test -f $(abs_srcdir)/$$file ; then \
+ cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
+ fi; \
+ if test -f $(abs_builddir)/$$file ; then \
+ cp $(abs_builddir)/$$file $(abs_builddir)/html; \
+ fi; \
+ done;
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references"
+ @echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log
+ @touch html-build.stamp
+
+#### pdf ####
+
+pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Building PDF"
+ @rm -f $(DOC_MODULE).pdf
+ @mkpdf_options=""; \
+ if test "x$(V)" = "x1"; then \
+ mkpdf_options="$$mkpdf_options --verbose"; \
+ fi; \
+ if test "x$(HTML_IMAGES)" != "x"; then \
+ for img in $(HTML_IMAGES); do \
+ part=`dirname $$img`; \
+ echo $$mkpdf_options | grep >/dev/null "\-\-imgdir=$$part "; \
+ if test $$? != 0; then \
+ mkpdf_options="$$mkpdf_options --imgdir=$$part"; \
+ fi; \
+ done; \
+ fi; \
+ echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log
+ @touch pdf-build.stamp
+
+##############
+
+# we need to enforce a rebuild for the tests
+clean-local:
+ @rm -f *~ *.bak ts gtkdoc-*.log
+ @rm -rf .libs
+ @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \
+ rm -f $(DOC_MODULE).types; \
+ fi
+ $(MAKE) distclean-local
+
+distclean-local:
+ @rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \
+ $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
+ @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
+ rm -f $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types; \
+ fi
+
+maintainer-clean-local:
+ @rm -rf xml html
+
+.PHONY : dist-hook-local docs
+++ /dev/null
-# -*- mode: makefile -*-
-
-####################################
-# Everything below here is generic #
-####################################
-
-if GTK_DOC_USE_LIBTOOL
-GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
-GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS)
-GTKDOC_RUN = $(LIBTOOL) --mode=execute
-else
-GTKDOC_CC = $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
-GTKDOC_LD = $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS)
-GTKDOC_RUN =
-endif
-
-# We set GPATH here; this gives us semantics for GNU make
-# which are more like other make's VPATH, when it comes to
-# whether a source that is a target of one rule is then
-# searched for in VPATH/GPATH.
-#
-GPATH = $(srcdir)
-
-# we don't install anything in tests
-#TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
-
-SETUP_FILES = \
- $(content_files) \
- $(DOC_MAIN_SGML_FILE) \
- $(DOC_MODULE)-sections.txt \
- $(DOC_MODULE)-overrides.txt
-
-EXTRA_DIST = \
- $(HTML_IMAGES) \
- $(SETUP_FILES)
-
-DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \
- html-build.stamp pdf-build.stamp \
- sgml.stamp html.stamp pdf.stamp
-
-SCANOBJ_FILES = \
- $(DOC_MODULE).args \
- $(DOC_MODULE).hierarchy \
- $(DOC_MODULE).interfaces \
- $(DOC_MODULE).prerequisites \
- $(DOC_MODULE).signals
-
-REPORT_FILES = \
- $(DOC_MODULE)-undocumented.txt \
- $(DOC_MODULE)-undeclared.txt \
- $(DOC_MODULE)-unused.txt
-
-CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \
- $(DOC_MODULE).pdf \
- ts \
- gtkdoc-scan.log \
- gtkdoc-scangobj.log \
- gtkdoc-mktmpl.log \
- gtkdoc-mkdb.log \
- gtkdoc-mkhtml.log \
- gtkdoc-mkpdf.log \
- gtkdoc-fixxref.log
-
-GITIGNOREFILES = \
- html.ref xml.ref
-
-check-local: html-build.stamp pdf-build.stamp
- @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: All done"
-
-docs: html-build.stamp pdf-build.stamp
- @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: All done"
-
-$(REPORT_FILES): sgml-build.stamp
-
-ts:
- @echo >ts `date $(TS_FMT)`;
-
-#### setup ####
-
-setup-build.stamp: ts
- -@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- echo ' DOC Preparing build'; \
- files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
- if test "x$$files" != "x" ; then \
- for file in $$files ; do \
- test -f $(abs_srcdir)/$$file && \
- cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
- done; \
- fi; \
- fi
- @touch setup-build.stamp
-
-#### scan ####
-
-scan-build.stamp: ts setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
- @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files"
- @_source_dir='' ; \
- for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
- done ; \
- echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
- gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log
- @if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
- ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
- scanobj_options=""; \
- if test "x$(V)" = "x1"; then \
- scanobj_options="--verbose"; \
- fi; \
- echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
- CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
- gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
- else \
- for i in $(SCANOBJ_FILES) ; do \
- test -f $$i || touch $$i ; \
- done \
- fi
- @touch scan-build.stamp
-
-$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp
- @true
-
-#### xml ####
-
-sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent
- @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: Building XML"
- @_source_dir='' ; \
- for i in $(DOC_SOURCE_DIR) ; do \
- _source_dir="$${_source_dir} --source-dir=$$i" ; \
- done ; \
- echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
- gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log
- @touch sgml-build.stamp
-
-sgml.stamp: sgml-build.stamp
- @true
-
-xml/gtkdocentities.ent: Makefile
- @$(MKDIR_P) $(@D) && ( \
- echo "<!ENTITY package \"$(PACKAGE)\">"; \
- echo "<!ENTITY package_bugreport \"$(PACKAGE_BUGREPORT)\">"; \
- echo "<!ENTITY package_name \"$(PACKAGE_NAME)\">"; \
- echo "<!ENTITY package_string \"$(PACKAGE_STRING)\">"; \
- echo "<!ENTITY package_tarname \"$(PACKAGE_TARNAME)\">"; \
- echo "<!ENTITY package_url \"$(PACKAGE_URL)\">"; \
- echo "<!ENTITY package_version \"$(PACKAGE_VERSION)\">"; \
- ) > $@
-
-#### html ####
-
-html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
- @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: Building HTML"
- @rm -rf html
- @mkdir html
- @mkhtml_options=""; \
- if test "x$(V)" = "x1"; then \
- mkhtml_options="$$mkhtml_options --verbose"; \
- fi; \
- echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \
- cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
- gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log
- -@test "x$(HTML_IMAGES)" = "x" || \
- for file in $(HTML_IMAGES) ; do \
- if test -f $(abs_srcdir)/$$file ; then \
- cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
- fi; \
- if test -f $(abs_builddir)/$$file ; then \
- cp $(abs_builddir)/$$file $(abs_builddir)/html; \
- fi; \
- done;
- @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references"
- @echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \
- gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log
- @touch html-build.stamp
-
-#### pdf ####
-
-pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
- @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
- echo " DOC `$(DATE_FMT_CMD)$$tsd`: Building PDF"
- @rm -f $(DOC_MODULE).pdf
- @mkpdf_options=""; \
- if test "x$(V)" = "x1"; then \
- mkpdf_options="$$mkpdf_options --verbose"; \
- fi; \
- if test "x$(HTML_IMAGES)" != "x"; then \
- for img in $(HTML_IMAGES); do \
- part=`dirname $$img`; \
- echo $$mkpdf_options | grep >/dev/null "\-\-imgdir=$$part "; \
- if test $$? != 0; then \
- mkpdf_options="$$mkpdf_options --imgdir=$$part"; \
- fi; \
- done; \
- fi; \
- echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \
- PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
- gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log
- @touch pdf-build.stamp
-
-##############
-
-# we need to enforce a rebuild for the tests
-clean-local:
- @rm -f *~ *.bak ts gtkdoc-*.log
- @rm -rf .libs
- @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \
- rm -f $(DOC_MODULE).types; \
- fi
- $(MAKE) distclean-local
-
-distclean-local:
- @rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \
- $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
- @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
- rm -f $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types; \
- fi
-
-maintainer-clean-local:
- @rm -rf xml html
-
-.PHONY : dist-hook-local docs
+++ /dev/null
-#!/usr/bin/env perl
-# -*- cperl -*-
-#
-# gtk-doc - GTK DocBook documentation generator.
-# Copyright (C) 2015 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.
-#
-
-use diagnostics;
-use warnings;
-use strict;
-use Test::More;
-
-require_ok ("gtkdoc-common.pl");
-
-subtest 'CreateValidSGMLID' => sub {
- is(CreateValidSGMLID('x'), 'x', 'already valid id is keept');
- is(CreateValidSGMLID('x_ y'), 'x--y', '\'_\' and \' \' are converted to \'-\'');
- is(CreateValidSGMLID('x,;y'), 'xy', '\',\' and \';\' are dropped');
-};
-
-done_testing();
-
+++ /dev/null
-#!/usr/bin/env perl
-# -*- cperl -*-
-#
-# gtk-doc - GTK DocBook documentation generator.
-# Copyright (C) 2015 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.
-#
-
-use diagnostics;
-use warnings;
-use strict;
-use Test::More;
-
-require_ok ("gtkdoc-fixxref");
-
-done_testing();
-
+++ /dev/null
-#!/usr/bin/env perl
-# -*- cperl -*-
-#
-# gtk-doc - GTK DocBook documentation generator.
-# Copyright (C) 2015 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.
-#
-
-use diagnostics;
-use warnings;
-use strict;
-use Test::More;
-
-require_ok ("gtkdoc-mkdb");
-
-done_testing();
-
+++ /dev/null
-#!/usr/bin/env perl
-# -*- cperl -*-
-#
-# gtk-doc - GTK DocBook documentation generator.
-# Copyright (C) 2015 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.
-#
-
-use diagnostics;
-use warnings;
-use strict;
-use Test::More;
-
-require_ok ("gtkdoc-rebase");
-
-done_testing();
-
+++ /dev/null
-#!/usr/bin/env perl
-# -*- cperl -*-
-#
-# gtk-doc - GTK DocBook documentation generator.
-# Copyright (C) 2015 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.
-#
-
-use diagnostics;
-use warnings;
-use strict;
-use Test::More;
-
-require_ok ("gtkdoc-scan");
-
-done_testing();
-
--- /dev/null
+#!/usr/bin/env python
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2015 Christoph Reiter
+# 2017 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 unittest
+
+from gtkdoc import md_to_db
+
+
+class TestConverter(unittest.TestCase):
+
+ def setUp(self):
+ md_to_db.Init()
+
+ def test_main(self):
+ input_ = """\
+SUPPORTED MARKDOWN
+==================
+
+Atx-style Headers
+-----------------
+
+# Header 1
+
+## Header 2 ##
+
+Setext-style Headers
+--------------------
+
+Header 1
+========
+
+Header 2
+--------
+
+Ordered (unnested) Lists
+------------------------
+
+1. item 1
+
+1. item 2 with loooong *foo*
+ description
+
+3. item 3
+
+Note: we require a blank line above the list items
+"""
+
+ expexted = """\
+<para>SUPPORTED MARKDOWN</para>
+<para>Atx-style Headers</para>
+<refsect2><title>Header 1</title><refsect3><title>Header 2</title></refsect3>
+<refsect3><title>Setext-style Headers</title></refsect3>
+</refsect2>
+<refsect2><title>Header 1</title><para>Header 2</para>
+<para>Ordered (unnested) Lists</para>
+<orderedlist>
+<listitem>
+<para>item 1</para>
+</listitem>
+<listitem>
+<para>item 2 with loooong *foo*
+description</para>
+</listitem>
+<listitem>
+<para>item 3</para>
+</listitem>
+</orderedlist>
+<para>Note: we require a blank line above the list items</para>
+</refsect2>
+"""
+
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expexted, output)
+
+ def test_docbook(self):
+ input_ = """\
+<itemizedlist>
+ <listitem><para>foo</para></listitem>
+</itemizedlist>
+"""
+
+ # docbook should stay the same
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(input_, output)
+
+ def test_header(self):
+ input_ = """
+widget lifecycle, states and style.
+
+# Height-for-width Geometry Management # {#geometry-management}
+
+GTK+ uses a height-for-width (and wid
+"""
+
+ expected = """\
+<para>widget lifecycle, states and style.</para>
+<refsect2 id="geometry-management"><title>Height-for-width Geometry Management</title><para>GTK+ uses a height-for-width (and wid</para>
+</refsect2>
+"""
+
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
+ def test_lists(self):
+ input_ = """\
+bla bla
+bla:
+
+- The channel was just created, and has not been written to or read from yet.
+ bla
+
+- The channel is write-only.
+
+foo
+"""
+ expected = """\
+<para>bla bla
+bla:</para>
+<itemizedlist>
+<listitem>
+<para>The channel was just created, and has not been written to or read from yet.
+bla</para>
+</listitem>
+<listitem>
+<para>The channel is write-only.</para>
+</listitem>
+</itemizedlist>
+<para>foo</para>
+"""
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
+ def test_paragraphs(self):
+ input_ = """\
+foo,
+bar.
+
+foo,
+bar.
+
+foo,
+bar.
+"""
+ expected = """\
+<para>foo,
+bar.</para>
+<para>foo,
+bar.</para>
+<para>foo,
+bar.</para>
+"""
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
+ def test_reference(self):
+ input_ = """\
+The #GData struct is an opaque data structure to represent a
+[Keyed Data List][glib-Keyed-Data-Lists]. It should only be
+accessed via the following functions."""
+
+ expected = """\
+<para>The <link linkend="GData"><type>GData</type></link> struct is an opaque data structure to represent a
+<link linkend="glib-Keyed-Data-Lists">Keyed Data List</link>. It should only be
+accessed via the following functions.</para>
+"""
+
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
+ def test_reference2(self):
+ input_ = "a [foo][bar] b [quux][baz]"
+ expected = '<para>a <link linkend="bar">foo</link> b <link linkend="baz">quux</link></para>\n'
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
+ def test_reference_empty(self):
+ input_ = "[][]"
+ # expected = '<para><ulink url=""></ulink></para>\n'
+ expected = '<para><link linkend=""></link></para>\n'
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
+ def test_inline_code(self):
+ input_ = "a `abc`"
+ expected = '<para>a <literal>abc</literal></para>\n'
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
+ def test_inline_code2(self):
+ input_ = "a `[][]`"
+ expected = '<para>a <literal>[][]</literal></para>\n'
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
+ def test_code(self):
+ input_ = """\
+|[<!-- language="C" -->
+ GdkEvent *event;
+ GdkEventType type;
+
+ type = event->type;
+]|
+"""
+
+ expected = '''\
+<informalexample><programlisting language="C"><![CDATA[
+ GdkEvent *event;
+ GdkEventType type;
+
+ type = event->type;
+]]></programlisting></informalexample>
+<para></para>
+'''
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
+ def test_plain(self):
+ input_ = u"""\
+|[<!-- language="plain" -->
+frame
+├── border
+├── <label widget>
+╰── <child>
+]|
+"""
+
+ expected = u"""\
+<informalexample><screen><![CDATA[
+frame
+├── border
+├── <label widget>
+╰── <child>
+]]></screen></informalexample>
+<para></para>
+"""
+
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
+
+if __name__ == '__main__':
+ unittest.main()
--- /dev/null
+#!/bin/sh
+
+gtkdoctest.sh program
+
--- /dev/null
+## Process this file with automake to produce Makefile.in
+
+SUBDIRS = . src docs
+
+if BUILD_TESTS
+
+check-local: clean
+
+endif
+
+-include $(top_srcdir)/git.mk
--- /dev/null
+# Makefile.in generated by automake 1.14.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994-2013 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 = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)'
+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 = tests/program
+DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am
+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)
+mkinstalldirs = $(install_sh) -d
+CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_VPATH_FILES =
+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 =
+RECURSIVE_TARGETS = all-recursive check-recursive cscopelist-recursive \
+ ctags-recursive dvi-recursive html-recursive info-recursive \
+ install-data-recursive install-dvi-recursive \
+ install-exec-recursive install-html-recursive \
+ install-info-recursive install-pdf-recursive \
+ install-ps-recursive install-recursive installcheck-recursive \
+ installdirs-recursive pdf-recursive ps-recursive \
+ tags-recursive uninstall-recursive
+am__can_run_installinfo = \
+ case $$AM_UPDATE_INFO_DIR in \
+ n|no|NO) false;; \
+ *) (install-info --version) >/dev/null 2>&1;; \
+ esac
+RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \
+ distclean-recursive maintainer-clean-recursive
+am__recursive_targets = \
+ $(RECURSIVE_TARGETS) \
+ $(RECURSIVE_CLEAN_TARGETS) \
+ $(am__extra_recursive_targets)
+AM_RECURSIVE_TARGETS = $(am__recursive_targets:-recursive=) TAGS CTAGS \
+ distdir
+am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
+# Read a list of newline-separated strings from the standard input,
+# and print each of them once, without duplicates. Input order is
+# *not* preserved.
+am__uniquify_input = $(AWK) '\
+ BEGIN { nonempty = 0; } \
+ { items[$$0] = 1; nonempty = 1; } \
+ END { if (nonempty) { for (i in items) print i; }; } \
+'
+# Make sure the list of sources is unique. This is necessary because,
+# e.g., the same source file might be shared among _SOURCES variables
+# for different programs/libraries.
+am__define_uniq_tagged_files = \
+ list='$(am__tagged_files)'; \
+ unique=`for i in $$list; do \
+ if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
+ done | $(am__uniquify_input)`
+ETAGS = etags
+CTAGS = ctags
+DIST_SUBDIRS = $(SUBDIRS)
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+am__relativize = \
+ dir0=`pwd`; \
+ sed_first='s,^\([^/]*\)/.*$$,\1,'; \
+ sed_rest='s,^[^/]*/*,,'; \
+ sed_last='s,^.*/\([^/]*\)$$,\1,'; \
+ sed_butlast='s,/*[^/]*$$,,'; \
+ while test -n "$$dir1"; do \
+ first=`echo "$$dir1" | sed -e "$$sed_first"`; \
+ if test "$$first" != "."; then \
+ if test "$$first" = ".."; then \
+ dir2=`echo "$$dir0" | sed -e "$$sed_last"`/"$$dir2"; \
+ dir0=`echo "$$dir0" | sed -e "$$sed_butlast"`; \
+ else \
+ first2=`echo "$$dir2" | sed -e "$$sed_first"`; \
+ if test "$$first2" = "$$first"; then \
+ dir2=`echo "$$dir2" | sed -e "$$sed_rest"`; \
+ else \
+ dir2="../$$dir2"; \
+ fi; \
+ dir0="$$dir0"/"$$first"; \
+ fi; \
+ fi; \
+ dir1=`echo "$$dir1" | sed -e "$$sed_rest"`; \
+ done; \
+ reldir="$$dir2"
+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@
+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@
+TRACE = @TRACE@
+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@
+SUBDIRS = . src docs
+all: all-recursive
+
+.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 tests/program/Makefile'; \
+ $(am__cd) $(top_srcdir) && \
+ $(AUTOMAKE) --gnu tests/program/Makefile
+.PRECIOUS: 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):
+
+mostlyclean-libtool:
+ -rm -f *.lo
+
+clean-libtool:
+ -rm -rf .libs _libs
+
+# This directory's subdirectories are mostly independent; you can cd
+# into them and run 'make' without going through this Makefile.
+# To change the values of 'make' variables: instead of editing Makefiles,
+# (1) if the variable is set in 'config.status', edit 'config.status'
+# (which will cause the Makefiles to be regenerated when you run 'make');
+# (2) otherwise, pass the desired values on the 'make' command line.
+$(am__recursive_targets):
+ @fail=; \
+ if $(am__make_keepgoing); then \
+ failcom='fail=yes'; \
+ else \
+ failcom='exit 1'; \
+ fi; \
+ dot_seen=no; \
+ target=`echo $@ | sed s/-recursive//`; \
+ case "$@" in \
+ distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \
+ *) list='$(SUBDIRS)' ;; \
+ esac; \
+ for subdir in $$list; do \
+ echo "Making $$target in $$subdir"; \
+ if test "$$subdir" = "."; then \
+ dot_seen=yes; \
+ local_target="$$target-am"; \
+ else \
+ local_target="$$target"; \
+ fi; \
+ ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \
+ || eval $$failcom; \
+ done; \
+ if test "$$dot_seen" = "no"; then \
+ $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \
+ fi; test -z "$$fail"
+
+ID: $(am__tagged_files)
+ $(am__define_uniq_tagged_files); mkid -fID $$unique
+tags: tags-recursive
+TAGS: tags
+
+tags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files)
+ set x; \
+ here=`pwd`; \
+ if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \
+ include_option=--etags-include; \
+ empty_fix=.; \
+ else \
+ include_option=--include; \
+ empty_fix=; \
+ fi; \
+ list='$(SUBDIRS)'; for subdir in $$list; do \
+ if test "$$subdir" = .; then :; else \
+ test ! -f $$subdir/TAGS || \
+ set "$$@" "$$include_option=$$here/$$subdir/TAGS"; \
+ fi; \
+ done; \
+ $(am__define_uniq_tagged_files); \
+ shift; \
+ if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \
+ test -n "$$unique" || unique=$$empty_fix; \
+ if test $$# -gt 0; then \
+ $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
+ "$$@" $$unique; \
+ else \
+ $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
+ $$unique; \
+ fi; \
+ fi
+ctags: ctags-recursive
+
+CTAGS: ctags
+ctags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files)
+ $(am__define_uniq_tagged_files); \
+ test -z "$(CTAGS_ARGS)$$unique" \
+ || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \
+ $$unique
+
+GTAGS:
+ here=`$(am__cd) $(top_builddir) && pwd` \
+ && $(am__cd) $(top_srcdir) \
+ && gtags -i $(GTAGS_ARGS) "$$here"
+cscopelist: cscopelist-recursive
+
+cscopelist-am: $(am__tagged_files)
+ list='$(am__tagged_files)'; \
+ case "$(srcdir)" in \
+ [\\/]* | ?:[\\/]*) sdir="$(srcdir)" ;; \
+ *) sdir=$(subdir)/$(srcdir) ;; \
+ esac; \
+ for i in $$list; do \
+ if test -f "$$i"; then \
+ echo "$(subdir)/$$i"; \
+ else \
+ echo "$$sdir/$$i"; \
+ fi; \
+ done >> $(top_builddir)/cscope.files
+
+distclean-tags:
+ -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags
+
+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
+ @list='$(DIST_SUBDIRS)'; for subdir in $$list; do \
+ if test "$$subdir" = .; then :; else \
+ $(am__make_dryrun) \
+ || test -d "$(distdir)/$$subdir" \
+ || $(MKDIR_P) "$(distdir)/$$subdir" \
+ || exit 1; \
+ dir1=$$subdir; dir2="$(distdir)/$$subdir"; \
+ $(am__relativize); \
+ new_distdir=$$reldir; \
+ dir1=$$subdir; dir2="$(top_distdir)"; \
+ $(am__relativize); \
+ new_top_distdir=$$reldir; \
+ echo " (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) top_distdir="$$new_top_distdir" distdir="$$new_distdir" \\"; \
+ echo " am__remove_distdir=: am__skip_length_check=: am__skip_mode_fix=: distdir)"; \
+ ($(am__cd) $$subdir && \
+ $(MAKE) $(AM_MAKEFLAGS) \
+ top_distdir="$$new_top_distdir" \
+ distdir="$$new_distdir" \
+ am__remove_distdir=: \
+ am__skip_length_check=: \
+ am__skip_mode_fix=: \
+ distdir) \
+ || exit 1; \
+ fi; \
+ done
+@BUILD_TESTS_FALSE@check-local:
+check-am: all-am
+ $(MAKE) $(AM_MAKEFLAGS) check-local
+check: check-recursive
+all-am: Makefile
+installdirs: installdirs-recursive
+installdirs-am:
+install: install-recursive
+install-exec: install-exec-recursive
+install-data: install-data-recursive
+uninstall: uninstall-recursive
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-recursive
+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:
+
+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-recursive
+
+clean-am: clean-generic clean-libtool mostlyclean-am
+
+distclean: distclean-recursive
+ -rm -f Makefile
+distclean-am: clean-am distclean-generic distclean-tags
+
+dvi: dvi-recursive
+
+dvi-am:
+
+html: html-recursive
+
+html-am:
+
+info: info-recursive
+
+info-am:
+
+install-data-am:
+
+install-dvi: install-dvi-recursive
+
+install-dvi-am:
+
+install-exec-am:
+
+install-html: install-html-recursive
+
+install-html-am:
+
+install-info: install-info-recursive
+
+install-info-am:
+
+install-man:
+
+install-pdf: install-pdf-recursive
+
+install-pdf-am:
+
+install-ps: install-ps-recursive
+
+install-ps-am:
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-recursive
+ -rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-recursive
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-recursive
+
+pdf-am:
+
+ps: ps-recursive
+
+ps-am:
+
+uninstall-am:
+
+.MAKE: $(am__recursive_targets) check-am install-am install-strip
+
+.PHONY: $(am__recursive_targets) CTAGS GTAGS TAGS all all-am check \
+ check-am check-local clean clean-generic clean-libtool \
+ cscopelist-am ctags ctags-am distclean distclean-generic \
+ distclean-libtool distclean-tags distdir dvi dvi-am html \
+ html-am info info-am install install-am 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 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
+
+
+@BUILD_TESTS_TRUE@check-local: clean
+
+-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:
--- /dev/null
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=tester
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+DOC_SOURCE_DIR=$(top_srcdir)/tests/program/src
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \
+ --rebuild-types
+
+# Extra options to supply to gtkdoc-mkdb.
+MKDB_OPTIONS=--xml-mode
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# --html-dir=$(HTML_DIR)
+FIXXREF_OPTIONS=--extra-dir=$(glib_prefix)/share/gtk-doc/html
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+HFILE_GLOB=
+CFILE_GLOB=$(top_srcdir)/tests/program/src/*.c
+
+# Header files to ignore when scanning.
+IGNORE_HFILES=config.h
+
+# Images to copy into HTML directory.
+HTML_IMAGES =
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files =
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+GTKDOC_CFLAGS =
+GTKDOC_LIBS =
+
+# include generic part
+include $(top_srcdir)/tests/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST +=
+
+CLEANFILES += \
+ $(DOC_MODULE)-overrides.txt \
+ $(DOC_MODULE).types
+
+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)
+endif
+
+-include $(top_srcdir)/git.mk
--- /dev/null
+# Makefile.in generated by automake 1.14.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994-2013 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@
+
+# -*- mode: makefile -*-
+
+####################################
+# Everything below here is generic #
+####################################
+VPATH = @srcdir@
+am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)'
+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@
+DIST_COMMON = $(top_srcdir)/tests/gtk-doc.make $(srcdir)/Makefile.in \
+ $(srcdir)/Makefile.am
+subdir = tests/program/docs
+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)
+mkinstalldirs = $(install_sh) -d
+CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_VPATH_FILES =
+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
+am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
+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@
+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@
+TRACE = @TRACE@
+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@
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE = tester
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+DOC_SOURCE_DIR = $(top_srcdir)/tests/program/src
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS =
+
+# Extra options to supply to gtkdoc-scan.
+SCAN_OPTIONS = --deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \
+ --rebuild-types
+
+
+# Extra options to supply to gtkdoc-mkdb.
+MKDB_OPTIONS = --xml-mode
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS =
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# --html-dir=$(HTML_DIR)
+FIXXREF_OPTIONS = --extra-dir=$(glib_prefix)/share/gtk-doc/html
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+HFILE_GLOB =
+CFILE_GLOB = $(top_srcdir)/tests/program/src/*.c
+
+# Header files to ignore when scanning.
+IGNORE_HFILES = config.h
+
+# Images to copy into HTML directory.
+HTML_IMAGES =
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files =
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files =
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+GTKDOC_CFLAGS =
+GTKDOC_LIBS =
+@GTK_DOC_USE_LIBTOOL_FALSE@GTKDOC_CC = $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
+@GTK_DOC_USE_LIBTOOL_TRUE@GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
+@GTK_DOC_USE_LIBTOOL_FALSE@GTKDOC_LD = $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS)
+@GTK_DOC_USE_LIBTOOL_TRUE@GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS)
+@GTK_DOC_USE_LIBTOOL_FALSE@GTKDOC_RUN =
+@GTK_DOC_USE_LIBTOOL_TRUE@GTKDOC_RUN = $(LIBTOOL) --mode=execute
+
+# We set GPATH here; this gives us semantics for GNU make
+# which are more like other make's VPATH, when it comes to
+# whether a source that is a target of one rule is then
+# searched for in VPATH/GPATH.
+#
+GPATH = $(srcdir)
+
+# we don't install anything in tests
+#TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
+SETUP_FILES = \
+ $(content_files) \
+ $(DOC_MAIN_SGML_FILE) \
+ $(DOC_MODULE)-sections.txt \
+ $(DOC_MODULE)-overrides.txt
+
+
+# include generic part
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST = $(HTML_IMAGES) $(SETUP_FILES)
+DOC_STAMPS = setup-build.stamp scan-build.stamp sgml-build.stamp \
+ html-build.stamp pdf-build.stamp \
+ sgml.stamp html.stamp pdf.stamp
+
+SCANOBJ_FILES = \
+ $(DOC_MODULE).args \
+ $(DOC_MODULE).hierarchy \
+ $(DOC_MODULE).interfaces \
+ $(DOC_MODULE).prerequisites \
+ $(DOC_MODULE).signals
+
+REPORT_FILES = \
+ $(DOC_MODULE)-undocumented.txt \
+ $(DOC_MODULE)-undeclared.txt \
+ $(DOC_MODULE)-unused.txt
+
+CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \
+ $(DOC_MODULE).pdf ts gtkdoc-scan.log gtkdoc-scangobj.log \
+ gtkdoc-mkdb.log gtkdoc-mkhtml.log gtkdoc-mkpdf.log \
+ gtkdoc-fixxref.log $(DOC_MODULE)-overrides.txt \
+ $(DOC_MODULE).types
+GITIGNOREFILES = \
+ html.ref xml.ref
+
+@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)
+
+all: all-am
+
+.SUFFIXES:
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.make $(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 tests/program/docs/Makefile'; \
+ $(am__cd) $(top_srcdir) && \
+ $(AUTOMAKE) --gnu tests/program/docs/Makefile
+.PRECIOUS: 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_srcdir)/tests/gtk-doc.make:
+
+$(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):
+
+mostlyclean-libtool:
+ -rm -f *.lo
+
+clean-libtool:
+ -rm -rf .libs _libs
+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
+ $(MAKE) $(AM_MAKEFLAGS) check-local
+check: check-am
+all-am: Makefile
+installdirs:
+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 clean-local mostlyclean-am
+
+distclean: distclean-am
+ -rm -f Makefile
+distclean-am: clean-am distclean-generic distclean-local
+
+dvi: dvi-am
+
+dvi-am:
+
+html: html-am
+
+html-am:
+
+info: info-am
+
+info-am:
+
+install-data-am:
+
+install-dvi: install-dvi-am
+
+install-dvi-am:
+
+install-exec-am:
+
+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:
+
+maintainer-clean: maintainer-clean-am
+ -rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic \
+ maintainer-clean-local
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am:
+
+.MAKE: check-am install-am install-strip
+
+.PHONY: all all-am check check-am check-local clean clean-generic \
+ clean-libtool clean-local cscopelist-am ctags-am distclean \
+ distclean-generic distclean-libtool distclean-local distdir \
+ dvi dvi-am html html-am info info-am install install-am \
+ 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 installdirs maintainer-clean \
+ maintainer-clean-generic maintainer-clean-local mostlyclean \
+ mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \
+ tags-am uninstall uninstall-am
+
+
+check-local: html-build.stamp pdf-build.stamp
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: All done"
+
+docs: html-build.stamp pdf-build.stamp
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: All done"
+
+$(REPORT_FILES): sgml-build.stamp
+
+ts:
+ @echo >ts `date $(TS_FMT)`;
+
+#### setup ####
+
+setup-build.stamp: ts
+ -@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
+ echo ' DOC Preparing build'; \
+ files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \
+ if test "x$$files" != "x" ; then \
+ for file in $$files ; do \
+ test -f $(abs_srcdir)/$$file && \
+ cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \
+ done; \
+ fi; \
+ fi
+ @touch setup-build.stamp
+
+#### scan ####
+
+scan-build.stamp: ts setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB)
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files"
+ @_source_dir='' ; \
+ for i in $(DOC_SOURCE_DIR) ; do \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ done ; \
+ echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log
+ @if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \
+ ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \
+ scanobj_options=""; \
+ if test "x$(V)" = "x1"; then \
+ scanobj_options="--verbose"; \
+ fi; \
+ echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \
+ gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \
+ else \
+ for i in $(SCANOBJ_FILES) ; do \
+ test -f $$i || touch $$i ; \
+ done \
+ fi
+ @touch scan-build.stamp
+
+$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp
+ @true
+
+#### xml ####
+
+sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Building XML"
+ @_source_dir='' ; \
+ for i in $(DOC_SOURCE_DIR) ; do \
+ _source_dir="$${_source_dir} --source-dir=$$i" ; \
+ done ; \
+ echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log
+ @touch sgml-build.stamp
+
+sgml.stamp: sgml-build.stamp
+ @true
+
+xml/gtkdocentities.ent: Makefile
+ @$(MKDIR_P) $(@D) && ( \
+ echo "<!ENTITY package \"$(PACKAGE)\">"; \
+ echo "<!ENTITY package_bugreport \"$(PACKAGE_BUGREPORT)\">"; \
+ echo "<!ENTITY package_name \"$(PACKAGE_NAME)\">"; \
+ echo "<!ENTITY package_string \"$(PACKAGE_STRING)\">"; \
+ echo "<!ENTITY package_tarname \"$(PACKAGE_TARNAME)\">"; \
+ echo "<!ENTITY package_url \"$(PACKAGE_URL)\">"; \
+ echo "<!ENTITY package_version \"$(PACKAGE_VERSION)\">"; \
+ ) > $@
+
+#### html ####
+
+html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Building HTML"
+ @rm -rf html
+ @mkdir html
+ @mkhtml_options=""; \
+ if test "x$(V)" = "x1"; then \
+ mkhtml_options="$$mkhtml_options --verbose"; \
+ fi; \
+ echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \
+ cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log
+ -@test "x$(HTML_IMAGES)" = "x" || \
+ for file in $(HTML_IMAGES) ; do \
+ if test -f $(abs_srcdir)/$$file ; then \
+ cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
+ fi; \
+ if test -f $(abs_builddir)/$$file ; then \
+ cp $(abs_builddir)/$$file $(abs_builddir)/html; \
+ fi; \
+ done;
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references"
+ @echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log
+ @touch html-build.stamp
+
+#### pdf ####
+
+pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
+ @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \
+ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Building PDF"
+ @rm -f $(DOC_MODULE).pdf
+ @mkpdf_options=""; \
+ if test "x$(V)" = "x1"; then \
+ mkpdf_options="$$mkpdf_options --verbose"; \
+ fi; \
+ if test "x$(HTML_IMAGES)" != "x"; then \
+ for img in $(HTML_IMAGES); do \
+ part=`dirname $$img`; \
+ echo $$mkpdf_options | grep >/dev/null "\-\-imgdir=$$part "; \
+ if test $$? != 0; then \
+ mkpdf_options="$$mkpdf_options --imgdir=$$part"; \
+ fi; \
+ done; \
+ fi; \
+ echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \
+ PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \
+ gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log
+ @touch pdf-build.stamp
+
+##############
+
+# we need to enforce a rebuild for the tests
+clean-local:
+ @rm -f *~ *.bak ts gtkdoc-*.log
+ @rm -rf .libs
+ @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \
+ rm -f $(DOC_MODULE).types; \
+ fi
+ $(MAKE) distclean-local
+
+distclean-local:
+ @rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \
+ $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
+ @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
+ rm -f $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types; \
+ fi
+
+maintainer-clean-local:
+ @rm -rf xml html
+
+.PHONY : dist-hook-local docs
+
+-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:
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+ %gtkdocentities;
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+ <bookinfo>
+ <title>&package_name; 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>
+
+ <chapter>
+ <title>Programs</title>
+ <xi:include href="xml/test-program.xml"/>
+ </chapter>
+
+ <index id="api-index">
+ <title>API Index</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="deprecated-api-index" role="deprecated">
+ <title>Index of deprecated API</title>
+ <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+ </index>
+</book>
--- /dev/null
+## Process this file with automake to produce Makefile.in
+
+if BUILD_TESTS
+
+noinst_PROGRAMS = test-program
+
+endif
+
+
+-include $(top_srcdir)/git.mk
--- /dev/null
+# Makefile.in generated by automake 1.14.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994-2013 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 = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)'
+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@
+@BUILD_TESTS_TRUE@noinst_PROGRAMS = test-program$(EXEEXT)
+subdir = tests/program/src
+DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am \
+ $(top_srcdir)/build-aux/depcomp
+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)
+mkinstalldirs = $(install_sh) -d
+CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_VPATH_FILES =
+PROGRAMS = $(noinst_PROGRAMS)
+test_program_SOURCES = test-program.c
+test_program_OBJECTS = test-program.$(OBJEXT)
+test_program_LDADD = $(LDADD)
+AM_V_lt = $(am__v_lt_@AM_V@)
+am__v_lt_ = $(am__v_lt_@AM_DEFAULT_V@)
+am__v_lt_0 = --silent
+am__v_lt_1 =
+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 =
+DEFAULT_INCLUDES = -I.@am__isrc@
+depcomp = $(SHELL) $(top_srcdir)/build-aux/depcomp
+am__depfiles_maybe = depfiles
+am__mv = mv -f
+COMPILE = $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) \
+ $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
+LTCOMPILE = $(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) \
+ $(LIBTOOLFLAGS) --mode=compile $(CC) $(DEFS) \
+ $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) \
+ $(AM_CFLAGS) $(CFLAGS)
+AM_V_CC = $(am__v_CC_@AM_V@)
+am__v_CC_ = $(am__v_CC_@AM_DEFAULT_V@)
+am__v_CC_0 = @echo " CC " $@;
+am__v_CC_1 =
+CCLD = $(CC)
+LINK = $(LIBTOOL) $(AM_V_lt) --tag=CC $(AM_LIBTOOLFLAGS) \
+ $(LIBTOOLFLAGS) --mode=link $(CCLD) $(AM_CFLAGS) $(CFLAGS) \
+ $(AM_LDFLAGS) $(LDFLAGS) -o $@
+AM_V_CCLD = $(am__v_CCLD_@AM_V@)
+am__v_CCLD_ = $(am__v_CCLD_@AM_DEFAULT_V@)
+am__v_CCLD_0 = @echo " CCLD " $@;
+am__v_CCLD_1 =
+SOURCES = test-program.c
+DIST_SOURCES = test-program.c
+am__can_run_installinfo = \
+ case $$AM_UPDATE_INFO_DIR in \
+ n|no|NO) false;; \
+ *) (install-info --version) >/dev/null 2>&1;; \
+ esac
+am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
+# Read a list of newline-separated strings from the standard input,
+# and print each of them once, without duplicates. Input order is
+# *not* preserved.
+am__uniquify_input = $(AWK) '\
+ BEGIN { nonempty = 0; } \
+ { items[$$0] = 1; nonempty = 1; } \
+ END { if (nonempty) { for (i in items) print i; }; } \
+'
+# Make sure the list of sources is unique. This is necessary because,
+# e.g., the same source file might be shared among _SOURCES variables
+# for different programs/libraries.
+am__define_uniq_tagged_files = \
+ list='$(am__tagged_files)'; \
+ unique=`for i in $$list; do \
+ if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
+ done | $(am__uniquify_input)`
+ETAGS = etags
+CTAGS = ctags
+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@
+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@
+TRACE = @TRACE@
+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@
+all: all-am
+
+.SUFFIXES:
+.SUFFIXES: .c .lo .o .obj
+$(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 tests/program/src/Makefile'; \
+ $(am__cd) $(top_srcdir) && \
+ $(AUTOMAKE) --gnu tests/program/src/Makefile
+.PRECIOUS: 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):
+
+clean-noinstPROGRAMS:
+ @list='$(noinst_PROGRAMS)'; test -n "$$list" || exit 0; \
+ echo " rm -f" $$list; \
+ rm -f $$list || exit $$?; \
+ test -n "$(EXEEXT)" || exit 0; \
+ list=`for p in $$list; do echo "$$p"; done | sed 's/$(EXEEXT)$$//'`; \
+ echo " rm -f" $$list; \
+ rm -f $$list
+
+test-program$(EXEEXT): $(test_program_OBJECTS) $(test_program_DEPENDENCIES) $(EXTRA_test_program_DEPENDENCIES)
+ @rm -f test-program$(EXEEXT)
+ $(AM_V_CCLD)$(LINK) $(test_program_OBJECTS) $(test_program_LDADD) $(LIBS)
+
+mostlyclean-compile:
+ -rm -f *.$(OBJEXT)
+
+distclean-compile:
+ -rm -f *.tab.c
+
+@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/test-program.Po@am__quote@
+
+.c.o:
+@am__fastdepCC_TRUE@ $(AM_V_CC)$(COMPILE) -MT $@ -MD -MP -MF $(DEPDIR)/$*.Tpo -c -o $@ $<
+@am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/$*.Tpo $(DEPDIR)/$*.Po
+@AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='$<' object='$@' libtool=no @AMDEPBACKSLASH@
+@AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@
+@am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(COMPILE) -c -o $@ $<
+
+.c.obj:
+@am__fastdepCC_TRUE@ $(AM_V_CC)$(COMPILE) -MT $@ -MD -MP -MF $(DEPDIR)/$*.Tpo -c -o $@ `$(CYGPATH_W) '$<'`
+@am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/$*.Tpo $(DEPDIR)/$*.Po
+@AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='$<' object='$@' libtool=no @AMDEPBACKSLASH@
+@AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@
+@am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(COMPILE) -c -o $@ `$(CYGPATH_W) '$<'`
+
+.c.lo:
+@am__fastdepCC_TRUE@ $(AM_V_CC)$(LTCOMPILE) -MT $@ -MD -MP -MF $(DEPDIR)/$*.Tpo -c -o $@ $<
+@am__fastdepCC_TRUE@ $(AM_V_at)$(am__mv) $(DEPDIR)/$*.Tpo $(DEPDIR)/$*.Plo
+@AMDEP_TRUE@@am__fastdepCC_FALSE@ $(AM_V_CC)source='$<' object='$@' libtool=yes @AMDEPBACKSLASH@
+@AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@
+@am__fastdepCC_FALSE@ $(AM_V_CC@am__nodep@)$(LTCOMPILE) -c -o $@ $<
+
+mostlyclean-libtool:
+ -rm -f *.lo
+
+clean-libtool:
+ -rm -rf .libs _libs
+
+ID: $(am__tagged_files)
+ $(am__define_uniq_tagged_files); mkid -fID $$unique
+tags: tags-am
+TAGS: tags
+
+tags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files)
+ set x; \
+ here=`pwd`; \
+ $(am__define_uniq_tagged_files); \
+ shift; \
+ if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \
+ test -n "$$unique" || unique=$$empty_fix; \
+ if test $$# -gt 0; then \
+ $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
+ "$$@" $$unique; \
+ else \
+ $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
+ $$unique; \
+ fi; \
+ fi
+ctags: ctags-am
+
+CTAGS: ctags
+ctags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files)
+ $(am__define_uniq_tagged_files); \
+ test -z "$(CTAGS_ARGS)$$unique" \
+ || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \
+ $$unique
+
+GTAGS:
+ here=`$(am__cd) $(top_builddir) && pwd` \
+ && $(am__cd) $(top_srcdir) \
+ && gtags -i $(GTAGS_ARGS) "$$here"
+cscopelist: cscopelist-am
+
+cscopelist-am: $(am__tagged_files)
+ list='$(am__tagged_files)'; \
+ case "$(srcdir)" in \
+ [\\/]* | ?:[\\/]*) sdir="$(srcdir)" ;; \
+ *) sdir=$(subdir)/$(srcdir) ;; \
+ esac; \
+ for i in $$list; do \
+ if test -f "$$i"; then \
+ echo "$(subdir)/$$i"; \
+ else \
+ echo "$$sdir/$$i"; \
+ fi; \
+ done >> $(top_builddir)/cscope.files
+
+distclean-tags:
+ -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags
+
+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 $(PROGRAMS)
+installdirs:
+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:
+
+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 clean-noinstPROGRAMS \
+ mostlyclean-am
+
+distclean: distclean-am
+ -rm -rf ./$(DEPDIR)
+ -rm -f Makefile
+distclean-am: clean-am distclean-compile distclean-generic \
+ distclean-tags
+
+dvi: dvi-am
+
+dvi-am:
+
+html: html-am
+
+html-am:
+
+info: info-am
+
+info-am:
+
+install-data-am:
+
+install-dvi: install-dvi-am
+
+install-dvi-am:
+
+install-exec-am:
+
+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:
+
+maintainer-clean: maintainer-clean-am
+ -rm -rf ./$(DEPDIR)
+ -rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-compile mostlyclean-generic \
+ mostlyclean-libtool
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am:
+
+.MAKE: install-am install-strip
+
+.PHONY: CTAGS GTAGS TAGS all all-am check check-am clean clean-generic \
+ clean-libtool clean-noinstPROGRAMS cscopelist-am ctags \
+ ctags-am distclean distclean-compile distclean-generic \
+ distclean-libtool distclean-tags distdir dvi dvi-am html \
+ html-am info info-am install install-am 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 installdirs maintainer-clean \
+ maintainer-clean-generic mostlyclean mostlyclean-compile \
+ mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \
+ tags tags-am uninstall uninstall-am
+
+
+-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:
--- /dev/null
+
+/**
+ * PROGRAM:test-program
+ * @short_description: A test program
+ * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
+ * @see_also: test(1)
+ * @--arg1 *arg*: set arg1 to *arg*
+ * @-v, --version: Print the version number
+ * @-h, --help: Print the help message
+ *
+ * Long description of program.
+ *
+ * Returns: Zero on success, non-zero on failure
+ */
+
+int main(int argc, char **argv)
+{
+ return 0;
+}
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)
+nok=0
+for file in $dir/*/docs/gtkdoc-*.log; do
+ 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/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=`wc -l $file | 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
echo "Running suite(s): gtk-doc-$suite";
-# we can use which here as we override the path in TEST_ENVIRONMENT
-
-# test perl scripts
-for file in gtkdoc-check gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mktmpl gtkdoc-rebase gtkdoc-scan gtkdoc-scangobj ; do
- /usr/bin/perl -cwT `which $file`
- if test $? = 1 ; then failed=`expr $failed + 1`; fi
- tested=`expr $tested + 1`
-done
+# we use 'which' here as we override the path in TEST_ENVIRONMENT
# test shell scripts
-for file in gtkdoc-mkhtml gtkdoc-mkman gtkdoc-mkpdf gtkdocize; do
+for file in gtkdocize; do
sh -n `which $file`
if test $? != 0 ; then failed=`expr $failed + 1`; fi
tested=`expr $tested + 1`
# test python scripts
-/usr/bin/python -m py_compile `which gtkdoc-depscan`
-if test $? != 0 ; then failed=`expr $failed + 1`; fi
-tested=`expr $tested + 1`
+# 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
+ fullfile=`which $file`
+ /usr/bin/python -m py_compile $fullfile
+ if test $? != 0 ; then failed=`expr $failed + 1`; fi
+ tested=`expr $tested + 1`
+done
# summary
echo "Running suite(s): gtk-doc-$suite";
-# we can use which here as we override the path in TEST_ENVIRONMENT
-
-# test perl scripts
-for file in gtkdoc-check gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mktmpl gtkdoc-rebase gtkdoc-scan gtkdoc-scangobj ; do
- @PERL@ -cwT `which $file`
- if test $? = 1 ; then failed=`expr $failed + 1`; fi
- tested=`expr $tested + 1`
-done
+# we use 'which' here as we override the path in TEST_ENVIRONMENT
# test shell scripts
-for file in gtkdoc-mkhtml gtkdoc-mkman gtkdoc-mkpdf gtkdocize; do
+for file in gtkdocize; do
sh -n `which $file`
if test $? != 0 ; then failed=`expr $failed + 1`; fi
tested=`expr $tested + 1`
# test python scripts
-@PYTHON@ -m py_compile `which gtkdoc-depscan`
-if test $? != 0 ; then failed=`expr $failed + 1`; fi
-tested=`expr $tested + 1`
+# 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
+ fullfile=`which $file`
+ @PYTHON@ -m py_compile $fullfile
+ if test $? != 0 ; then failed=`expr $failed + 1`; fi
+ tested=`expr $tested + 1`
+done
# summary
projects / platform / upstream / gtk-doc.git / commitdiff