* configure.in:
Add automake support for more distcheck. Use a real sourcefile for the
- srcdir (something that we wont remove one day).
+ srcdir (something that we won't remove one day).
* tests/annotations/docs/Makefile.am:
* tests/annotations/src/Makefile.am:
2009-01-07 Stefan Kost <ensonic@users.sf.net>
* TODO:
- Ideas about syntax highlighing.
+ Ideas about syntax highlighting.
* style-classic.css:
Old color scheme.
2008-12-05 Stefan Kost <ensonic@users.sf.net>
* style.css:
- Hightlight deprecation warnings.
+ Highlight deprecation warnings.
2008-12-04 Stefan Kost <ensonic@users.sf.net>
* gtk-doc.notmpl.make:
* tests/gtk-doc.make:
* tests/gtk-doc.notmpl.make:
- Correct check for existance of gtkdoc-rebase (better fix than the
+ Correct check for existence of gtkdoc-rebase (better fix than the
previous one #508897). Fixes #559281.
2008-10-27 Stefan Kost <ensonic@users.sf.net>
2008-09-04 Stefan Kost <ensonic@users.sf.net>
* gtkdoc-mkhtml.in:
- Fix comparision.
+ Fix comparison.
* TODO:
ideas.
* tests/gobject/examples/gobject.c:
* tests/gobject/src/gobject.c:
- Demostrate how to include source fragments from external files.
+ Demonstrate how to include source fragments from external files.
* tests/gobject/src/giface.h:
* tests/gobject/src/gobject.h:
* gtkdoc-mkdb.in:
Warn about repeated symbols in sections. Also give line of previous
- occurrance. Also give that info for double file entries. Fixes #473342
- Give correct error locate for one warning. Fixes #532395 partialy
+ occurrence. Also give that info for double file entries. Fixes #473342
+ Give correct error locate for one warning. Fixes #532395 partially
2008-06-04 Stefan Kost <ensonic@users.sf.net>
* gtkdoc-mkdb.in:
- Don't warn about overriden docs comment if its the same text.
+ Don't warn about overridden docs comment if its the same text.
2008-06-03 Stefan Kost <ensonic@users.sf.net>
tody up and add some comments regarding HTML_DIR.
* gtkdoc-fixxref.in:
- HTML_DIR is not neccesarily set.
+ HTML_DIR is not necessarily set.
* gtkdoc-mkhtml.in:
Fix uninstalled.
2008-06-02 Stefan Kost <ensonic@users.sf.net>
* style.css:
- Improve spacing on indicies and glossaries.
+ Improve spacing on indices and glossaries.
2008-06-02 Stefan Kost <ensonic@users.sf.net>
2007-12-17 Mathias Hasselmann <mathias@openismus.com>
* configure.in:
- Use AM_PATH_PYTHON instread of AC_PATH_PROG to find Python.
+ Use AM_PATH_PYTHON instead of AC_PATH_PROG to find Python.
(#503710)
2007-12-17 Stefan Kost <ensonic@users.sf.net>
patch by: Kouhei Sutou <kou@cozmixng.org>
* gtk-doc.xsl:
- Consitently use UTF-8 instead of US-ASCII for output encoding.
+ Consistently use UTF-8 instead of US-ASCII for output encoding.
Fixes #497367
2007-12-10 Mathias Hasselmann <mathias@openismus.com>
2007-09-26 Stefan Kost <ensonic@users.sf.net>
* gtk-doc.make:
- And actually saving before commiting might greatly help.
+ And actually saving before committing might greatly help.
2007-09-26 Stefan Kost <ensonic@users.sf.net>
* Makefile.am (pkgconfigdir): put the .pc file in $(datadir) rather
than $(libdir), since gtk-doc is architecture-independant. (#120950)
- * configure.in: removed the hard dependancy on openjade or jade, since
+ * configure.in: removed the hard dependency on openjade or jade, since
XML is used mostly now rather than SGML. We just output a warning
rather than an error if neither openjade or jade are found.
* gtkdoc-mkdb.in:
fix parsing const after type (#322556)
* gtkdoc-mktmpl.in:
- fix parseing multiline macro heads (#320588)
+ fix parsing multiline macro heads (#320588)
* gtkdoc-scangobj.in:
allow additional root types (#323581)
2004-05-10 Geert Stappers <stappers@stappers.nl>
- * TODO: new file, basicly a reference to bugzilla.
+ * TODO: new file, basically a reference to bugzilla.
* examples/README: tell about gtk-doc.make.
2003-02-12 James Henstridge <james@daa.com.au>
- * gtk-doc.make: add some chmod calls to work arround distcheck on
+ * gtk-doc.make: add some chmod calls to work around distcheck on
automake >= 1.6.
(install-data-local): copy the images as well as the html files
during install.
than a <literallayout>, since the Docbook XSL stylesheets don't
handle <link>s inside <literallayout>.
- * gtkdoc-mkdb.in: Decide wether to generate standalone documents
+ * gtkdoc-mkdb.in: Decide whether to generate standalone documents
for XIncluding or entities based on the presence of the XInclude
namespace declaration on the document element.
2001-05-19 Damon Chaplin <damon@ximian.com>
* gtkdoc-mkdb.in: added --help option and changed output slightly to
- make more compatable with XML. Patch from Toshio Kuratomi
+ make more compatible with XML. Patch from Toshio Kuratomi
<badger@prtr-13.ucsc.edu>
2001-05-19 Damon Chaplin <damon@ximian.com>
1999-12-15 Raja R Harinath <harinath@cs.umn.edu>
* gtk-doc.dsl.in ($generate-chapter-toc$): Add missing close
- paranthesis.
+ parenthesis.
1999-11-23 Raja R Harinath <harinath@cs.umn.edu>
Wed Aug 4 03:30:19 1999 Owen Taylor <otaylor@redhat.com>
* doc/style-guide.txt: Removed references to creating
- tables explicitely in favor of demonstrating new
+ tables explicitly in favor of demonstrating new
syntax. Added a short section on /<* public >*/
and /*< private *>/.
enumeration have a description in a @... line, then
we don't generate the table at all.
- Also, gtkdoc-mktmpl now loads up the object heirarchy,
+ Also, gtkdoc-mktmpl now loads up the object hierarchy,
because we need to be able to check if structures
are widget structures.
In general, the coding here is pretty clean, though
- the style is a little different. (I'm interating
+ the style is a little different. (I'm iterating
through strings with m/.../msg; instead of
s/^...//; for one thing.) However, there are a some
of FIXME's where I've whimped out on try to handle
1998-12-16 Damon Chaplin <DAChaplin@msn.com>
- * gtkdoc-mkdb (ExpandAbbreviations): Allow -ve contants, e.g. %-1.
+ * gtkdoc-mkdb (ExpandAbbreviations): Allow -ve contents, e.g. %-1.
(ScanSourceFile): Try to handle function descriptions that start
with 'Returns'. It was assuming that they were describing the return
value before.
gtkdoc/common.py \
gtkdoc/config.py \
gtkdoc/fixxref.py \
+ gtkdoc/highlight.py \
gtkdoc/md_to_db.py \
gtkdoc/mkdb.py \
gtkdoc/mkhtml.py \
host_triplet = @host@
subdir = .
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
gtkdoc/common.py \
gtkdoc/config.py \
gtkdoc/fixxref.py \
+ gtkdoc/highlight.py \
gtkdoc/md_to_db.py \
gtkdoc/mkdb.py \
gtkdoc/mkhtml.py \
+GTK-Doc 1.30 (May 08 2019)
+===============
+
+GTK-Doc is now using python-pygments to do the syntax highlighing. It is not
+depending on highligh or source-highligh anymore.
+
+This version ships with a new expermiental gtkdoc-mkhtml2 toolchain replacing
+gktdoc-mkhtml+gtkdoc-fixxref.
+
+Contributors
+
+ Aleksander Morgado
+ Anders Jonsson
+ Andre Klapper
+ Bastien Nocera
+ Christian Kirbach
+ Corentin Noël
+ Daniel Mustieles
+ Emmanuele Bassi
+ Ignacio Casal Quinteiro
+ Lubomir Rintel
+ Marco Trevisan (Treviño)
+ Marek Cernocky
+ Mario Blättermann
+ Mathieu Bridon
+ Michael Catanzaro
+ Nicola Fontana
+ Philip Withnall
+ Piotr Drąg
+ Rafael Fontenelle
+ Stefan Sauer
+ Ting-Wei Lan
+ Руслан Ижбулатов
+
GTK-Doc 1.29 (Aug 28 2018)
===============
o 791928 : gtk-doc doesn't understand 'stability: Obsolete'
o 792148 : cmake: Installed GtkDocConfig.cmake has incorrect bindir path
- o 792661 : use pygments to do syntax highlighing
+ o 792661 : use pygments to do syntax highlighting
o 793599 : Please run testsuite with V=0
o 794051 : rebase: fix on-line location extraction from devhelp files
o 794182 : private_header regex is broken
o 554718 : gtk-doc needs to allow versioned TARGET_DIR
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
+ o 559281 : Correct check for existence of gtkdoc-rebase
Contributors
GTK-Doc 1.6 (Apr 9 2006)
===========
- o Removed the hard dependancy on openjade or jade, since XML is used mainly
+ o Removed the hard dependency on openjade or jade, since XML is used mainly
now rather than SGML.
o Install the .pc file in $(datadir) rather than $(libdir) since gtk-doc is
architecture-independant.
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).
+(see https://wiki.gnome.org/Apps/Devhelp).
-Please use DoxBook XML instead of DocBook SGML - support for the later will be
-dropped.
Requirements
============
-Python 2.7, 3.x - the secondary scripts are written in Python
+Python 3.x
http:///www.python.org
-Python-six - for python 2,3 compatibility
+Additional python modules:
+ For the tests: unittest, parameterized
+ For mkhtml2 (experimental): anytree, lxml and pygments
+ For fixxref: pygments
For XML output (recommended):
-
The TODO list for the gtk-doc project is at Bugzilla,
the bugtracking system of the GNOME project.
Visit
http://bugzilla.gnome.org/buglist.cgi?product=gtk-doc&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED
-to see what is allready requested, or where you can help. :-)
+to see what is already requested, or where you can help. :-)
To put an other request on the TODO list, visit
http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc
* if one has "@InSection: xxxx" in a section comment we could patch the
main.xml file and insert then xi:include line (would possibly rely on a
special comment-pair there, we might also need to rewrite these
- auto-generated xi:includes everytime as the placements could have been
- changed, or we have a xi:inlcude for each chapter, that we regenerate).
-* we need a way to specify subsections (Standart, Private)
+ auto-generated xi:includes every time as the placements could have been
+ changed, or we have a xi:include for each chapter, that we regenerate).
+* we need a way to specify subsections (Standard, Private)
this could be done in the SECTION comment
e.g.: "@HideSymbols: <list-of-symbols-to-hide>
* we could allow to have a SUBSECTION:xxx comment block too
* api - classic api docs
* tutorial & examples - integrated to keep it up-to-date and cross referenced
* migration - how to for api changes, deprecations
- * (releated) tools - tools part of the package or recommended for development
+ * (related) tools - tools part of the package or recommended for development
* indexes - api-index, depretations, new api since xxx
proposed structure in docbook xml:
- l10n.language is slow
bug: https://sourceforge.net/tracker/index.php?func=detail&aid=2918673&group_id=21935&atid=373750
see: http://www.mail-archive.com/docbook-apps@lists.oasis-open.org/msg05412.html
- - overide l10n.language
+ - override l10n.language
glib/gobject
real user sys
2m15.221s 1m58.740s 0m1.456s
- tricky as with xml/gtkdocentities.ent, they are in a extra file
- we could pass entities as args for gtkdoc-mkdb
- if the flag is used, we should warn if entities are in the header
- - 2) if the doctype on the main doc, does not conatin entities, skip adding
+ - 2) if the doctype on the main doc, does not cotnain entities, skip adding
the doctype to generated output
- 3) if the doctype on the main doc contains entities, only add the doctype
if the generated content contains entities ([&%][_a-zA-Z]*;)
- consider swithcing to this markdown parser
https://pythonhosted.org/Markdown/index.html
- switch intermediate files to json/yaml
- - we need to pick something, that we can easilly output from plain c (produced by gtkdoc-scangobj)
+ - we need to pick something, that we can easily output from plain c (produced by gtkdoc-scangobj)
- decl-list.txt and .types would need to stay
- maybe maintain one file per sourcefile (in a subdir) to eventually be able to
do incremental builds
If you have problems, you may need to regenerate the build system entirely.
To do so, use the procedure documented by the package, typically 'autoreconf'.])])
-# pkg.m4 - Macros to locate and utilise pkg-config. -*- Autoconf -*-
-# serial 11 (pkg-config-0.29.1)
-
+dnl pkg.m4 - Macros to locate and utilise pkg-config. -*- Autoconf -*-
+dnl serial 11 (pkg-config-0.29)
+dnl
dnl Copyright © 2004 Scott James Remnant <scott@netsplit.com>.
dnl Copyright © 2012-2015 Dan Nicholson <dbn.lists@gmail.com>
dnl
dnl See the "Since" comment for each macro you use to see what version
dnl of the macros you require.
m4_defun([PKG_PREREQ],
-[m4_define([PKG_MACROS_VERSION], [0.29.1])
+[m4_define([PKG_MACROS_VERSION], [0.29])
m4_if(m4_version_compare(PKG_MACROS_VERSION, [$1]), -1,
[m4_fatal([pkg.m4 version $1 or higher is required but ]PKG_MACROS_VERSION[ found])])
])dnl PKG_PREREQ
AS_VAR_IF([$1], [""], [$5], [$4])dnl
])dnl PKG_CHECK_VAR
-dnl PKG_WITH_MODULES(VARIABLE-PREFIX, MODULES,
-dnl [ACTION-IF-FOUND],[ACTION-IF-NOT-FOUND],
-dnl [DESCRIPTION], [DEFAULT])
-dnl ------------------------------------------
-dnl
-dnl Prepare a "--with-" configure option using the lowercase
-dnl [VARIABLE-PREFIX] name, merging the behaviour of AC_ARG_WITH and
-dnl PKG_CHECK_MODULES in a single macro.
-AC_DEFUN([PKG_WITH_MODULES],
-[
-m4_pushdef([with_arg], m4_tolower([$1]))
-
-m4_pushdef([description],
- [m4_default([$5], [build with ]with_arg[ support])])
-
-m4_pushdef([def_arg], [m4_default([$6], [auto])])
-m4_pushdef([def_action_if_found], [AS_TR_SH([with_]with_arg)=yes])
-m4_pushdef([def_action_if_not_found], [AS_TR_SH([with_]with_arg)=no])
-
-m4_case(def_arg,
- [yes],[m4_pushdef([with_without], [--without-]with_arg)],
- [m4_pushdef([with_without],[--with-]with_arg)])
-
-AC_ARG_WITH(with_arg,
- AS_HELP_STRING(with_without, description[ @<:@default=]def_arg[@:>@]),,
- [AS_TR_SH([with_]with_arg)=def_arg])
-
-AS_CASE([$AS_TR_SH([with_]with_arg)],
- [yes],[PKG_CHECK_MODULES([$1],[$2],$3,$4)],
- [auto],[PKG_CHECK_MODULES([$1],[$2],
- [m4_n([def_action_if_found]) $3],
- [m4_n([def_action_if_not_found]) $4])])
-
-m4_popdef([with_arg])
-m4_popdef([description])
-m4_popdef([def_arg])
-
-])dnl PKG_WITH_MODULES
-
-dnl PKG_HAVE_WITH_MODULES(VARIABLE-PREFIX, MODULES,
-dnl [DESCRIPTION], [DEFAULT])
-dnl -----------------------------------------------
-dnl
-dnl Convenience macro to trigger AM_CONDITIONAL after PKG_WITH_MODULES
-dnl check._[VARIABLE-PREFIX] is exported as make variable.
-AC_DEFUN([PKG_HAVE_WITH_MODULES],
-[
-PKG_WITH_MODULES([$1],[$2],,,[$3],[$4])
-
-AM_CONDITIONAL([HAVE_][$1],
- [test "$AS_TR_SH([with_]m4_tolower([$1]))" = "yes"])
-])dnl PKG_HAVE_WITH_MODULES
-
-dnl PKG_HAVE_DEFINE_WITH_MODULES(VARIABLE-PREFIX, MODULES,
-dnl [DESCRIPTION], [DEFAULT])
-dnl ------------------------------------------------------
-dnl
-dnl Convenience macro to run AM_CONDITIONAL and AC_DEFINE after
-dnl PKG_WITH_MODULES check. HAVE_[VARIABLE-PREFIX] is exported as make
-dnl and preprocessor variable.
-AC_DEFUN([PKG_HAVE_DEFINE_WITH_MODULES],
-[
-PKG_HAVE_WITH_MODULES([$1],[$2],[$3],[$4])
-
-AS_IF([test "$AS_TR_SH([with_]m4_tolower([$1]))" = "yes"],
- [AC_DEFINE([HAVE_][$1], 1, [Enable ]m4_tolower([$1])[ support])])
-])dnl PKG_HAVE_DEFINE_WITH_MODULES
-
AC_DEFUN([YELP_HELP_INIT],
[
AC_REQUIRE([AC_PROG_LN_S])
elif test "x$$lc" != "xC"; then \
if test "x$(YELP_LC_MEDIA_LINKS)" != "x"; then \
echo "$(LN_S) -f $(HELP_DIR)/C/$(HELP_ID)/$$f $$helpdir$$f"; \
- $(LN_S) -f "$(HELP_DIR)/C/$(HELP_ID)/$$f" "$$helpdir$$f" || exit 1; \
+ dname="$$f"; \
+ pars="../"; \
+ while test "$$dname" != "." -a "$$dname" != "/"; do \
+ pars="../$$pars"; \
+ dname=$$(dirname "$$dname"); \
+ done; \
+ $(LN_S) -f $$pars"C/$(HELP_ID)/$$f" "$$helpdir$$f" || exit 1; \
fi; \
fi; \
done; \
dnl supported. (2.0 was released on October 16, 2000).
dnl FIXME: Remove the need to hard-code Python versions here.
m4_define_default([_AM_PYTHON_INTERPRETER_LIST],
-[python python2 python3 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 dnl
+[python python2 python3 python3.8 python3.7 python3.6 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 dnl
python2.6 python2.5 python2.4 python2.3 python2.2 python2.1 python2.0])
AC_ARG_VAR([PYTHON], [the Python interpreter])
AC_SUBST([am__untar])
]) # _AM_PROG_TAR
+m4_include([m4/ax_python_module.m4])
m4_include([m4/gtkdoc_jh_check_xml_catalog.m4])
m4_include([m4/gtkdoc_jh_path_xml_catalog.m4])
m4_include([m4/libtool.m4])
-#!/bin/sh
+#! /bin/sh
# Wrapper for compilers which do not understand '-c -o'.
-scriptversion=2016-01-11.22; # UTC
+scriptversion=2012-10-14.11; # UTC
-# Copyright (C) 1999-2017 Free Software Foundation, Inc.
+# Copyright (C) 1999-2014 Free Software Foundation, Inc.
# Written by Tom Tromey <tromey@cygnus.com>.
#
# This program is free software; you can redistribute it and/or modify
echo "compile $scriptversion"
exit $?
;;
- cl | *[/\\]cl | cl.exe | *[/\\]cl.exe | \
- icl | *[/\\]icl | icl.exe | *[/\\]icl.exe )
+ cl | *[/\\]cl | cl.exe | *[/\\]cl.exe )
func_cl_wrapper "$@" # Doesn't return...
;;
esac
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-time-zone: "UTC0"
+# time-stamp-time-zone: "UTC"
# time-stamp-end: "; # UTC"
# End:
-#!/bin/sh
+#! /bin/sh
# Attempt to guess a canonical system name.
# Copyright 1992-2017 Free Software Foundation, Inc.
-timestamp='2017-08-08'
+timestamp='2017-11-07'
# This file is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
-# along with this program; if not, see <http://www.gnu.org/licenses/>.
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
#
# As a special exception to the GNU General Public License, if you
# distribute this file as part of a program that contains a
# Originally written by Per Bothner; maintained since 2000 by Ben Elliston.
#
# You can get the latest version of this script from:
-# http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess
+# https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess
#
# Please send patches to <config-patches@gnu.org>.
Output the configuration name of the system \`$me' is run on.
-Operation modes:
+Options:
-h, --help print this help, then exit
-t, --time-stamp print date of last modification, then exit
-v, --version print version number, then exit
UNAME_MACHINE_ARCH=`arch | sed 's/^.*BSD\.//'`
echo ${UNAME_MACHINE_ARCH}-unknown-libertybsd${UNAME_RELEASE}
exit ;;
+ *:MidnightBSD:*:*)
+ echo ${UNAME_MACHINE}-unknown-midnightbsd${UNAME_RELEASE}
+ exit ;;
*:ekkoBSD:*:*)
echo ${UNAME_MACHINE}-unknown-ekkobsd${UNAME_RELEASE}
exit ;;
exitcode=$?
trap '' 0
exit $exitcode ;;
- Alpha\ *:Windows_NT*:*)
- # How do we know it's Interix rather than the generic POSIX subsystem?
- # Should we change UNAME_MACHINE based on the output of uname instead
- # of the specific Alpha model?
- echo alpha-pc-interix
- exit ;;
- 21064:Windows_NT:50:3)
- echo alpha-dec-winnt3.5
- exit ;;
Amiga*:UNIX_System_V:4.0:*)
echo m68k-unknown-sysv4
exit ;;
#endif
#if defined (host_mips) && defined (MIPSEB)
#if defined (SYSTYPE_SYSV)
- printf ("mips-mips-riscos%ssysv\n", argv[1]); exit (0);
+ printf ("mips-mips-riscos%ssysv\\n", argv[1]); exit (0);
#endif
#if defined (SYSTYPE_SVR4)
- printf ("mips-mips-riscos%ssvr4\n", argv[1]); exit (0);
+ printf ("mips-mips-riscos%ssvr4\\n", argv[1]); exit (0);
#endif
#if defined (SYSTYPE_BSD43) || defined(SYSTYPE_BSD)
- printf ("mips-mips-riscos%sbsd\n", argv[1]); exit (0);
+ printf ("mips-mips-riscos%sbsd\\n", argv[1]); exit (0);
#endif
#endif
exit (-1);
*:AIX:*:*)
echo rs6000-ibm-aix
exit ;;
- ibmrt:4.4BSD:*|romp-ibm:BSD:*)
+ ibmrt:4.4BSD:*|romp-ibm:4.4BSD:*)
echo romp-ibm-bsd4.4
exit ;;
ibmrt:*BSD:*|romp-ibm:BSD:*) # covers RT/PC BSD and
9000/[34678]??:HP-UX:*:*)
HPUX_REV=`echo ${UNAME_RELEASE}|sed -e 's/[^.]*.[0B]*//'`
case "${UNAME_MACHINE}" in
- 9000/31? ) HP_ARCH=m68000 ;;
- 9000/[34]?? ) HP_ARCH=m68k ;;
+ 9000/31?) HP_ARCH=m68000 ;;
+ 9000/[34]??) HP_ARCH=m68k ;;
9000/[678][0-9][0-9])
if [ -x /usr/bin/getconf ]; then
sc_cpu_version=`/usr/bin/getconf SC_CPU_VERSION 2>/dev/null`
{ echo "$SYSTEM_NAME"; exit; }
echo unknown-hitachi-hiuxwe2
exit ;;
- 9000/7??:4.3bsd:*:* | 9000/8?[79]:4.3bsd:*:* )
+ 9000/7??:4.3bsd:*:* | 9000/8?[79]:4.3bsd:*:*)
echo hppa1.1-hp-bsd
exit ;;
9000/8??:4.3bsd:*:*)
*9??*:MPE/iX:*:* | *3000*:MPE/iX:*:*)
echo hppa1.0-hp-mpeix
exit ;;
- hp7??:OSF1:*:* | hp8?[79]:OSF1:*:* )
+ hp7??:OSF1:*:* | hp8?[79]:OSF1:*:*)
echo hppa1.1-hp-osf
exit ;;
hp8??:OSF1:*:*)
*:MSYS*:*)
echo ${UNAME_MACHINE}-pc-msys
exit ;;
- i*:windows32*:*)
- # uname -m includes "-pc" on this system.
- echo ${UNAME_MACHINE}-mingw32
- exit ;;
i*:PW*:*)
echo ${UNAME_MACHINE}-pc-pw32
exit ;;
echo ia64-unknown-interix${UNAME_RELEASE}
exit ;;
esac ;;
- [345]86:Windows_95:* | [345]86:Windows_98:* | [345]86:Windows_NT:*)
- echo i${UNAME_MACHINE}-pc-mks
- exit ;;
- 8664:Windows_NT:*)
- echo x86_64-pc-mks
- exit ;;
- i*:Windows_NT*:* | Pentium*:Windows_NT*:*)
- # How do we know it's Interix rather than the generic POSIX subsystem?
- # It also conflicts with pre-2.0 versions of AT&T UWIN. Should we
- # UNAME_MACHINE based on the output of uname instead of i386?
- echo i586-pc-interix
- exit ;;
i*:UWIN*:*)
echo ${UNAME_MACHINE}-pc-uwin
exit ;;
amd64:CYGWIN*:*:* | x86_64:CYGWIN*:*:*)
echo x86_64-unknown-cygwin
exit ;;
- p*:CYGWIN*:*)
- echo powerpcle-unknown-cygwin
- exit ;;
prep*:SunOS:5.*:*)
echo powerpcle-unknown-solaris2`echo ${UNAME_RELEASE}|sed -e 's/[^.]*//'`
exit ;;
i*86:*DOS:*:*)
echo ${UNAME_MACHINE}-pc-msdosdjgpp
exit ;;
- i*86:*:4.*:* | i*86:SYSTEM_V:4.*:*)
+ i*86:*:4.*:*)
UNAME_REL=`echo ${UNAME_RELEASE} | sed 's/\/MP$//'`
if grep Novell /usr/include/link.h >/dev/null 2>/dev/null; then
echo ${UNAME_MACHINE}-univel-sysv${UNAME_REL}
exit ;;
esac
+echo "$0: unable to guess system type" >&2
+
+case "${UNAME_MACHINE}:${UNAME_SYSTEM}" in
+ mips:Linux | mips64:Linux)
+ # If we got here on MIPS GNU/Linux, output extra information.
+ cat >&2 <<EOF
+
+NOTE: MIPS GNU/Linux systems require a C compiler to fully recognize
+the system type. Please install a C compiler and try again.
+EOF
+ ;;
+esac
+
cat >&2 <<EOF
-$0: unable to guess system type
This script (version $timestamp), has failed to recognize the
operating system you are using. If your script is old, overwrite *all*
copies of config.guess and config.sub with the latest versions from:
- http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess
+ https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess
and
- http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub
+ https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub
If $0 has already been updated, send the following data and any
information you think might be pertinent to config-patches@gnu.org to
exit 1
# Local variables:
-# eval: (add-hook 'write-file-hooks 'time-stamp)
+# eval: (add-hook 'write-file-functions 'time-stamp)
# time-stamp-start: "timestamp='"
# time-stamp-format: "%:y-%02m-%02d"
# time-stamp-end: "'"
-#!/bin/sh
+#! /bin/sh
# Configuration validation subroutine script.
# Copyright 1992-2017 Free Software Foundation, Inc.
-timestamp='2017-04-02'
+timestamp='2017-11-23'
# This file is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
-# along with this program; if not, see <http://www.gnu.org/licenses/>.
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
#
# As a special exception to the GNU General Public License, if you
# distribute this file as part of a program that contains a
# Otherwise, we print the canonical config type on stdout and succeed.
# You can get the latest version of this script from:
-# http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub
+# https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub
# This file is supposed to be the same for all GNU packages
# and recognize all the CPU types, system types and aliases
Canonicalize a configuration name.
-Operation modes:
+Options:
-h, --help print this help, then exit
-t, --time-stamp print date of last modification, then exit
-v, --version print version number, then exit
-ptx*)
basic_machine=`echo $1 | sed -e 's/86-.*/86-sequent/'`
;;
- -windowsnt*)
- os=`echo $os | sed -e 's/windowsnt/winnt/'`
- ;;
-psos*)
os=-psos
;;
| v850 | v850e | v850e1 | v850e2 | v850es | v850e2v3 \
| visium \
| wasm32 \
- | we32k \
| x86 | xc16x | xstormy16 | xtensa \
| z8k | z80)
basic_machine=$basic_machine-unknown
basic_machine=rs6000-bull
os=-bosx
;;
- dpx2* | dpx2*-bull)
+ dpx2*)
basic_machine=m68k-bull
os=-sysv3
;;
basic_machine=v70-nec
os=-sysv
;;
- next | m*-next )
+ next | m*-next)
basic_machine=m68k-next
case $os in
-nextstep* )
;;
ppc64) basic_machine=powerpc64-unknown
;;
- ppc64-* | ppc64p7-*) basic_machine=powerpc64-`echo $basic_machine | sed 's/^[^-]*-//'`
+ ppc64-*) basic_machine=powerpc64-`echo $basic_machine | sed 's/^[^-]*-//'`
;;
ppc64le | powerpc64little)
basic_machine=powerpc64le-unknown
basic_machine=hppa1.1-winbond
os=-proelf
;;
+ x64)
+ basic_machine=x86_64-pc
+ ;;
xbox)
basic_machine=i686-pc
os=-mingw32
if [ x"$os" != x"" ]
then
case $os in
- # First match some system type aliases
- # that might get confused with valid system types.
+ # First match some system type aliases that might get confused
+ # with valid system types.
# -solaris* is a basic system type, with this one exception.
-auroraux)
os=-auroraux
-gnu/linux*)
os=`echo $os | sed -e 's|gnu/linux|linux-gnu|'`
;;
- # First accept the basic system types.
+ # Now accept the basic system types.
# The portable systems comes first.
- # Each alternative MUST END IN A *, to match a version number.
+ # Each alternative MUST end in a * to match a version number.
# -sysv* is not here because it comes later, after sysvr4.
-gnu* | -bsd* | -mach* | -minix* | -genix* | -ultrix* | -irix* \
| -*vms* | -sco* | -esix* | -isc* | -aix* | -cnk* | -sunos | -sunos[34]*\
-nova*)
os=-rtmk-nova
;;
- -ns2 )
+ -ns2)
os=-nextstep2
;;
-nsk*)
-dicos*)
os=-dicos
;;
+ -pikeos*)
+ # Until real need of OS specific support for
+ # particular features comes up, bare metal
+ # configurations are quite functional.
+ case $basic_machine in
+ arm*)
+ os=-eabi
+ ;;
+ *)
+ os=-elf
+ ;;
+ esac
+ ;;
-nacl*)
;;
-ios)
m88k-omron*)
os=-luna
;;
- *-next )
+ *-next)
os=-nextstep
;;
*-sequent)
exit
# Local variables:
-# eval: (add-hook 'write-file-hooks 'time-stamp)
+# eval: (add-hook 'write-file-functions 'time-stamp)
# time-stamp-start: "timestamp='"
# time-stamp-format: "%:y-%02m-%02d"
# time-stamp-end: "'"
-#!/bin/sh
+#! /bin/sh
# depcomp - compile a program generating dependencies as side-effects
scriptversion=2016-01-11.22; # UTC
#!/bin/sh
# install - install a program, script, or datafile
-scriptversion=2016-01-11.22; # UTC
+scriptversion=2014-09-12.12; # UTC
# This originates from X11R5 (mit/util/scripts/install.sh), which was
# later released in X11R6 (xc/config/util/install.sh) with the
# is incompatible with FreeBSD 'install' when (umask & 300) != 0.
;;
*)
+ # $RANDOM is not portable (e.g. dash); use it when possible to
+ # lower collision chance
tmpdir=${TMPDIR-/tmp}/ins$RANDOM-$$
- trap 'ret=$?; rmdir "$tmpdir/d" "$tmpdir" 2>/dev/null; exit $ret' 0
+ trap 'ret=$?; rmdir "$tmpdir/a/b" "$tmpdir/a" "$tmpdir" 2>/dev/null; exit $ret' 0
+ # As "mkdir -p" follows symlinks and we work in /tmp possibly; so
+ # create the $tmpdir first (and fail if unsuccessful) to make sure
+ # that nobody tries to guess the $tmpdir name.
if (umask $mkdir_umask &&
- exec $mkdirprog $mkdir_mode -p -- "$tmpdir/d") >/dev/null 2>&1
+ $mkdirprog $mkdir_mode "$tmpdir" &&
+ exec $mkdirprog $mkdir_mode -p -- "$tmpdir/a/b") >/dev/null 2>&1
then
if test -z "$dir_arg" || {
# Check for POSIX incompatibilities with -m.
# HP-UX 11.23 and IRIX 6.5 mkdir -m -p sets group- or
# other-writable bit of parent directory when it shouldn't.
# FreeBSD 6.1 mkdir -m -p sets mode of existing directory.
- ls_ld_tmpdir=`ls -ld "$tmpdir"`
+ test_tmpdir="$tmpdir/a"
+ ls_ld_tmpdir=`ls -ld "$test_tmpdir"`
case $ls_ld_tmpdir in
d????-?r-*) different_mode=700;;
d????-?--*) different_mode=755;;
*) false;;
esac &&
- $mkdirprog -m$different_mode -p -- "$tmpdir" && {
- ls_ld_tmpdir_1=`ls -ld "$tmpdir"`
+ $mkdirprog -m$different_mode -p -- "$test_tmpdir" && {
+ ls_ld_tmpdir_1=`ls -ld "$test_tmpdir"`
test "$ls_ld_tmpdir" = "$ls_ld_tmpdir_1"
}
}
then posix_mkdir=:
fi
- rmdir "$tmpdir/d" "$tmpdir"
+ rmdir "$tmpdir/a/b" "$tmpdir/a" "$tmpdir"
else
# Remove any dirs left behind by ancient mkdir implementations.
- rmdir ./$mkdir_mode ./-p ./-- 2>/dev/null
+ rmdir ./$mkdir_mode ./-p ./-- "$tmpdir" 2>/dev/null
fi
trap '' 0;;
esac;;
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-time-zone: "UTC0"
+# time-stamp-time-zone: "UTC"
# time-stamp-end: "; # UTC"
# End:
PROGRAM=libtool
PACKAGE=libtool
-VERSION=2.4.6
+VERSION="2.4.6 Debian-2.4.6-2"
package_revision=2.4.6
compiler: $LTCC
compiler flags: $LTCFLAGS
linker: $LD (gnu? $with_gnu_ld)
- version: $progname (GNU libtool) 2.4.6
+ version: $progname $scriptversion Debian-2.4.6-2
automake: `($AUTOMAKE --version) 2>/dev/null |$SED 1q`
autoconf: `($AUTOCONF --version) 2>/dev/null |$SED 1q`
Report bugs to <bug-libtool@gnu.org>.
-GNU libtool home page: <http://www.gnu.org/software/libtool/>.
+GNU libtool home page: <http://www.gnu.org/s/libtool/>.
General help using GNU software: <http://www.gnu.org/gethelp/>."
exit 0
}
# -O*, -g*, -flto*, -fwhopr*, -fuse-linker-plugin GCC link-time optimization
# -specs=* GCC specs files
# -stdlib=* select c++ std lib with clang
+ # -fsanitize=* Clang/GCC memory and address sanitizer
-64|-mips[0-9]|-r[0-9][0-9]*|-xarch=*|-xtarget=*|+DA*|+DD*|-q*|-m*| \
-t[45]*|-txscale*|-p|-pg|--coverage|-fprofile-*|-F*|@*|-tp=*|--sysroot=*| \
-O*|-g*|-flto*|-fwhopr*|-fuse-linker-plugin|-fstack-protector*|-stdlib=*| \
- -specs=*)
+ -specs=*|-fsanitize=*)
func_quote_for_eval "$arg"
arg=$func_quote_for_eval_result
func_append compile_command " $arg"
case $pass in
dlopen) libs=$dlfiles ;;
dlpreopen) libs=$dlprefiles ;;
- link) libs="$deplibs %DEPLIBS% $dependency_libs" ;;
+ link)
+ libs="$deplibs %DEPLIBS%"
+ test "X$link_all_deplibs" != Xno && libs="$libs $dependency_libs"
+ ;;
esac
fi
if test lib,dlpreopen = "$linkmode,$pass"; then
# It is a libtool convenience library, so add in its objects.
func_append convenience " $ladir/$objdir/$old_library"
func_append old_convenience " $ladir/$objdir/$old_library"
+ tmp_libs=
+ for deplib in $dependency_libs; do
+ deplibs="$deplib $deplibs"
+ if $opt_preserve_dup_deps; then
+ case "$tmp_libs " in
+ *" $deplib "*) func_append specialdeplibs " $deplib" ;;
+ esac
+ fi
+ func_append tmp_libs " $deplib"
+ done
elif test prog != "$linkmode" && test lib != "$linkmode"; then
func_fatal_error "'$lib' is not a convenience library"
fi
- tmp_libs=
- for deplib in $dependency_libs; do
- deplibs="$deplib $deplibs"
- if $opt_preserve_dup_deps; then
- case "$tmp_libs " in
- *" $deplib "*) func_append specialdeplibs " $deplib" ;;
- esac
- fi
- func_append tmp_libs " $deplib"
- done
continue
fi # $pass = conv
revision=$number_minor
lt_irix_increment=no
;;
+ *)
+ func_fatal_configuration "$modename: unknown library version type '$version_type'"
+ ;;
esac
;;
no)
-#!/bin/sh
+#! /bin/sh
# Common wrapper for a few potentially missing GNU programs.
-scriptversion=2016-01-11.22; # UTC
+scriptversion=2013-10-28.13; # UTC
-# Copyright (C) 1996-2017 Free Software Foundation, Inc.
+# Copyright (C) 1996-2014 Free Software Foundation, Inc.
# Originally written by Fran,cois Pinard <pinard@iro.umontreal.ca>, 1996.
# This program is free software; you can redistribute it and/or modify
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-time-zone: "UTC0"
+# time-stamp-time-zone: "UTC"
# time-stamp-end: "; # UTC"
# End:
-#!/bin/sh
+#! /bin/sh
# test-driver - basic testsuite driver script.
-scriptversion=2016-01-11.22; # UTC
+scriptversion=2013-07-13.22; # UTC
-# Copyright (C) 2011-2017 Free Software Foundation, Inc.
+# Copyright (C) 2011-2014 Free Software Foundation, Inc.
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-time-zone: "UTC0"
+# time-stamp-time-zone: "UTC"
# time-stamp-end: "; # UTC"
# End:
$(autotoolsdata_DATA) \
gtk-doc.m4
-CLEANFILES = gtk-doc.flat.make
+CLEANFILES = gtk-doc.flat.make gtk-doc.no-xslt-flat.make
bin_SCRIPTS = gtkdocize
autotoolsdatadir = $(datadir)/gtk-doc/data
autotoolsdata_DATA = \
- gtk-doc.make \
- gtk-doc.flat.make
+ gtk-doc.make \
+ gtk-doc.flat.make \
+ gtk-doc.no-xslt.make \
+ gtk-doc.no-xslt-flat.make
aclocaldir = $(datadir)/aclocal
aclocal_DATA = gtk-doc.m4
gtk-doc.flat.make: gtk-doc.make
@$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@
+gtk-doc.no-xslt-flat.make: gtk-doc.no-xslt.make
+ @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@
+
-include $(top_srcdir)/git.mk
host_triplet = @host@
subdir = buildsystems/autotools
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
$(autotoolsdata_DATA) \
gtk-doc.m4
-CLEANFILES = gtk-doc.flat.make
+CLEANFILES = gtk-doc.flat.make gtk-doc.no-xslt-flat.make
bin_SCRIPTS = gtkdocize
autotoolsdatadir = $(datadir)/gtk-doc/data
autotoolsdata_DATA = \
- gtk-doc.make \
- gtk-doc.flat.make
+ gtk-doc.make \
+ gtk-doc.flat.make \
+ gtk-doc.no-xslt.make \
+ gtk-doc.no-xslt-flat.make
aclocaldir = $(datadir)/aclocal
aclocal_DATA = gtk-doc.m4
gtk-doc.flat.make: gtk-doc.make
@$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@
+gtk-doc.no-xslt-flat.make: gtk-doc.no-xslt.make
+ @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@
+
-include $(top_srcdir)/git.mk
# Tell versions [3.59,3.63) of GNU make to not export all variables.
--- /dev/null
+# -*- mode: makefile -*-
+#
+# gtk-doc.make - make rules for gtk-doc
+# Copyright (C) 2003 James Henstridge
+# 2004-2007 Damon Chaplin
+# 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 3 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, see <http://www.gnu.org/licenses/>.
+
+####################################
+# 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_@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; \
+ fi
+ $(AM_V_at)touch setup-build.stamp
+
+#### scan ####
+
+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_@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" ; \
+ 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_@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: 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
+
+$(DOC_MAIN_SGML_FILE): 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_@AM_V@)
+GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_@AM_DEFAULT_V@)
+GTK_DOC_V_HTML_0=@echo " DOC Building HTML";
+
+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="--path=\"$(abs_srcdir)\""; \
+ if test "x$(V)" = "x1"; then \
+ mkhtml_options="$$mkhtml_options --verbose"; \
+ fi; \
+ cd html && gtkdoc-mkhtml2 $$mkhtml_options $(MKHTML_OPTIONS) $(FIXXREF_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+ -@test "x$(HTML_IMAGES)" = "x" || \
+ for file in $(HTML_IMAGES) ; do \
+ test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
+ test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$file $(abs_builddir)/html; \
+ test -f $$file && cp $$file $(abs_builddir)/html; \
+ done;
+ $(AM_V_at)touch html-build.stamp
+
+#### pdf ####
+
+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)
+ $(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 -*-
+#
+# gtk-doc.make - make rules for gtk-doc
+# Copyright (C) 2003 James Henstridge
+# 2004-2007 Damon Chaplin
+# 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 3 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, see <http://www.gnu.org/licenses/>.
+
+####################################
+# 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_@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; \
+ fi
+ $(AM_V_at)touch setup-build.stamp
+
+#### scan ####
+
+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_@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" ; \
+ 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_@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: 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
+
+$(DOC_MAIN_SGML_FILE): 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_@AM_V@)
+GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_@AM_DEFAULT_V@)
+GTK_DOC_V_HTML_0=@echo " DOC Building HTML";
+
+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="--path=\"$(abs_srcdir)\""; \
+ if test "x$(V)" = "x1"; then \
+ mkhtml_options="$$mkhtml_options --verbose"; \
+ fi; \
+ cd html && gtkdoc-mkhtml2 $$mkhtml_options $(MKHTML_OPTIONS) $(FIXXREF_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+ -@test "x$(HTML_IMAGES)" = "x" || \
+ for file in $(HTML_IMAGES) ; do \
+ test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \
+ test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$file $(abs_builddir)/html; \
+ test -f $$file && cp $$file $(abs_builddir)/html; \
+ done;
+ $(AM_V_at)touch html-build.stamp
+
+#### pdf ####
+
+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)
+ $(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
# mini help
usage="\
-usage: $progname [ --copy ] [ --docdir DIR ] [ --flavour {legacy|legacy-flat|no-tmpl|no-tmpl-flat} ] [ --srcdir DIR ]"
+usage: $progname [ --copy ] [ --docdir DIR ] [ --flavour {legacy|legacy-flat|no-tmpl|no-tmpl-flat|no-xslt|no-xslt-flat} ] [ --srcdir DIR ]"
# Find the srcdir early (and ignore a srcdir set in configure).
# https://bugzilla.gnome.org/show_bug.cgi?id=707426
legacy-flat|no-tmpl-flat)
makefile=gtk-doc.flat.make
;;
+ no-xslt)
+ makefile=gtk-doc.no-xslt.make
+ ;;
+ no-xslt-flat)
+ makefile=gtk-doc.no-xslt-flat.make
+ ;;
legacy|no-tmpl)
;;
*)
--- /dev/null
+# CMake macros to use the GtkDoc documentation system
+#
+# See the GTK-Doc manual (help/manual/C/index.docbook) for an example of how to
+# use this.
+
+# Output variables:
+#
+# GTKDOC_FOUND ... set to 1
+#
+# GTKDOC_SCAN_EXE ... the location of the gtkdoc-scan executable
+# GTKDOC_SCANGOBJ_EXE ... the location of the gtkdoc-scangobj executable
+# GTKDOC_MKDB_EXE ... the location of the gtkdoc-mkdb executable
+# GTKDOC_MKHTML_EXE ... the location of the gtkdoc-mkhtml executable
+# GTKDOC_FIXXREF_EXE ... the location of the gtkdoc-fixxref executable
+
+
+#=============================================================================
+# Copyright 2009 Rich Wareham
+# Copyright 2015 Lautsprecher Teufel GmbH
+#
+# 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, see <http://www.gnu.org/licenses/>.
+#=============================================================================
+
+include(CMakeParseArguments)
+
+set(GTKDOC_FOUND 1)
+
+find_program(GTKDOC_SCAN_EXE gtkdoc-scan)
+find_program(GTKDOC_SCANGOBJ_EXE gtkdoc-scangobj)
+find_program(GTKDOC_MKDB_EXE gtkdoc-mkdb)
+find_program(GTKDOC_MKHTML_EXE gtkdoc-mkhtml)
+find_program(GTKDOC_FIXXREF_EXE gtkdoc-fixxref)
+
+get_filename_component(_this_dir ${CMAKE_CURRENT_LIST_FILE} PATH)
+find_file(GTKDOC_SCANGOBJ_WRAPPER GtkDocScanGObjWrapper.cmake PATH ${_this_dir})
+
+# ::
+#
+# gtk_doc_add_module(doc_prefix
+# SOURCE <sourcedir> [...]
+# XML xmlfile
+# [LIBRARIES depend1...]
+# [FIXXREFOPTS fixxrefoption1...]
+# [IGNOREHEADERS header1...]
+# [CONTENT_FILES example1...]
+# [SCANOPTS scanoption1...]
+# [SCANOBJOPTS scanobjoption1...]
+# [MKDBOPTS mkdboption1...]
+# [HTMLOPTS htmloption1...])
+#
+# Add a module with documentation to be processed with GTK-Doc.
+#
+# <sourcedir> must be the *full* path to the source directory.
+#
+# If omitted, xmlfile defaults to the auto generated ${doc_prefix}/${doc_prefix}-docs.xml.
+#
+# The `gtkdoc-scangobj` program is used to get introspection information for
+# the module. You should pass the target(s) to be scanned as LIRARIES. This
+# will try to set the correct compiler and link flags for the introspection
+# build to use, and the correct LD_LIBRARY_PATH for it to run, and the correct
+# dependencies for the doc target.
+#
+# You *can* also set the compile and link flags manually, using the 'CFLAGS'
+# and 'LDFLAGS' options. The 'LDPATH' option controls the LD_LIBRARY_PATH. You
+# can also manually add additional targets as dependencies of the
+# documentation build with the DEPENDS option.
+#
+# The 'CONTENT_FILES' option is here to copy the files extending the documentation
+# such as exemples and custom xml files.
+#
+# The 'SCANOPTS' option is here to pass arguments to 'gtkdoc-scan'
+# The 'SCANOBJOPTS' option is here to pass arguments to 'gtkdoc-scangobj'
+# The 'MKDBOPTS' option is here to pass arguments to 'gtkdoc-mkdb'
+# The 'HTMLOPTS' option is here to pass arguments to 'gtkdoc-mkhtml'
+#
+# This function a target named "doc-${doc_prefix}". You will need to manually
+# add it to the ALL target if you want it to be built by default, you can do
+# something like this:
+#
+# gtk_doc_add_module(doc-mymodule
+# SOURCE ${CMAKE_SOURCE_DIR}/module ${CMAKE_BINARY_DIR}/module
+# LIBRARIES mylibrary
+# LIBRARY_DIRS ${GLIB_LIBRARY_DIRS} ${FOO_LIBRARY_DIRS}
+# add_custom_target(all-documentation ALL)
+# add_dependencies(all-documentation doc-mymodule)
+#
+function(gtk_doc_add_module _doc_prefix)
+ set(_one_value_args "XML")
+ set(_multi_value_args "FIXXREFOPTS" "IGNOREHEADERS" "LIBRARIES" "LIBRARY_DIRS" "SOURCE" "SUFFIXES"
+ "CFLAGS" "DEPENDS" "LDFLAGS" "LDPATH" "CONTENT_FILES" "SCANOPTS" "SCANOBJOPTS"
+ "MKDBOPTS" "HTMLOPTS")
+ cmake_parse_arguments("GTK_DOC" "" "${_one_value_args}" "${_multi_value_args}" ${ARGN})
+
+ if(NOT GTK_DOC_SOURCE)
+ message(FATAL_ERROR "No SOURCE specified for gtk_doc_add_module ${_doc_prefix}")
+ endif()
+
+ set(_xml_file ${GTK_DOC_XML})
+
+ set(_fixxrefopts ${GTK_DOC_FIXXREFOPTS})
+ set(_ignore_headers ${GTK_DOC_IGNOREHEADERS})
+ set(_libraries ${GTK_DOC_LIBRARIES})
+ set(_library_dirs ${GTK_DOC_LIBRARY_DIRS})
+ set(_suffixes ${GTK_DOC_SUFFIXES})
+
+ set(_content_files ${GTK_DOC_CONTENT_FILES})
+ set(_scanopts ${GTK_DOC_SCANOPTS})
+ set(_scanobjopts ${GTK_DOC_SCANOBJOPTS})
+ set(_mkdbopts ${GTK_DOC_MKDBOPTS})
+ set(_htmlopts ${GTK_DOC_HTMLOPTS})
+
+ set(_extra_cflags ${GTK_DOC_CFLAGS})
+ set(_depends ${GTK_DOC_DEPENDS})
+ set(_extra_ldflags ${GTK_DOC_LDFLAGS})
+ set(_extra_ldpath ${GTK_DOC_LDPATH})
+
+ if(_suffixes)
+ set(_doc_source_suffixes "")
+ foreach(_suffix ${_suffixes})
+ if(_doc_source_suffixes)
+ set(_doc_source_suffixes "${_doc_source_suffixes},${_suffix}")
+ else(_doc_source_suffixes)
+ set(_doc_source_suffixes "${_suffix}")
+ endif(_doc_source_suffixes)
+ endforeach(_suffix)
+ else(_suffixes)
+ set(_doc_source_suffixes "h")
+ endif(_suffixes)
+
+ # Parse the LIBRARIES option and collect compile and link flags for those
+ # targets.
+ foreach(target ${_libraries})
+ _gtk_doc_get_cflags_for_target(_target_cflags ${target})
+ _gtk_doc_get_ldflags_for_target(_target_ldflags ${target} "${_libraries}")
+ list(APPEND _extra_cflags ${_target_cflags})
+ list(APPEND _extra_ldflags ${_target_ldflags})
+ list(APPEND _extra_ldpath $<TARGET_FILE_DIR:${target}>)
+
+ list(APPEND _depends ${target})
+ endforeach()
+
+ # Link directories can't be specified per target, only for every target
+ # under a given directory.
+ get_property(all_library_directories DIRECTORY PROPERTY LINK_DIRECTORIES)
+ foreach(library_dir ${all_library_directories})
+ list(APPEND _extra_ldflags ${CMAKE_LIBRARY_PATH_FLAG}${library_dir})
+ list(APPEND _extra_ldpath ${library_dir})
+ endforeach()
+
+ list(REMOVE_DUPLICATES _extra_cflags)
+ list(SORT _extra_cflags)
+
+ list(REMOVE_DUPLICATES _extra_ldflags)
+ list(SORT _extra_ldflags)
+
+ list(REMOVE_DUPLICATES _extra_ldpath)
+ list(SORT _extra_ldpath)
+
+ # a directory to store output.
+ set(_output_dir "${CMAKE_CURRENT_BINARY_DIR}")
+ set(_output_dir_stamp "${_output_dir}/dir.stamp")
+
+ # set default sgml file if not specified
+ set(_default_xml_file "${_output_dir}/${_doc_prefix}-docs.xml")
+ get_filename_component(_default_xml_file ${_default_xml_file} ABSOLUTE)
+
+ # a directory to store html output.
+ set(_output_html_dir "${_output_dir}/html")
+ set(_output_html_dir_stamp "${_output_dir}/html_dir.stamp")
+
+ # The output files
+ set(_output_decl_list "${_output_dir}/${_doc_prefix}-decl-list.txt")
+ set(_output_decl "${_output_dir}/${_doc_prefix}-decl.txt")
+ set(_output_overrides "${_output_dir}/${_doc_prefix}-overrides.txt")
+ set(_output_sections "${_output_dir}/${_doc_prefix}-sections.txt")
+ set(_output_types "${_output_dir}/${_doc_prefix}.types")
+
+ set(_output_signals "${_output_dir}/${_doc_prefix}.signals")
+
+ set(_output_unused "${_output_dir}/${_doc_prefix}-unused.txt")
+ set(_output_undeclared "${_output_dir}/${_doc_prefix}-undeclared.txt")
+ set(_output_undocumented "${_output_dir}/${_doc_prefix}-undocumented.txt")
+
+ set(_output_xml_dir "${_output_dir}/xml")
+ set(_output_sgml_stamp "${_output_dir}/sgml.stamp")
+
+ set(_output_html_stamp "${_output_dir}/html.stamp")
+
+ # we depend on the content files being there before doing anything
+ if(_content_files)
+ list(APPEND _depends ${_content_files})
+ endif(_content_files)
+
+ # add a command to create output directory
+ add_custom_command(
+ OUTPUT "${_output_dir_stamp}" "${_output_dir}"
+ COMMAND ${CMAKE_COMMAND} -E make_directory "${_output_dir}"
+ COMMAND ${CMAKE_COMMAND} -E touch ${_output_dir_stamp}
+ VERBATIM)
+
+ set(_ignore_headers_opt "")
+ if(_ignore_headers)
+ set(_ignore_headers_opt "--ignore-headers=")
+ foreach(_header ${_ignore_headers})
+ set(_ignore_headers_opt "${_ignore_headers_opt}${_header} ")
+ endforeach(_header ${_ignore_headers})
+ endif(_ignore_headers)
+
+ foreach(source_dir ${GTK_DOC_SOURCE})
+ set(_source_dirs_opt ${_source_dirs_opt} --source-dir=${source_dir})
+ endforeach()
+
+ # add a command to scan the input
+ add_custom_command(
+ OUTPUT
+ "${_output_decl_list}"
+ "${_output_decl}"
+ "${_output_overrides}"
+ "${_output_sections}"
+ "${_output_types}"
+ DEPENDS
+ "${_output_dir_stamp}"
+ ${_depends}
+ COMMAND
+ ${GTKDOC_SCAN_EXE}
+ --module=${_doc_prefix}
+ ${_ignore_headers_opt}
+ ${_source_dirs_opt}
+ --rebuild-sections
+ --rebuild-types
+ ${_scanopts}
+ WORKING_DIRECTORY ${_output_dir}
+ VERBATIM)
+
+ # add a command to scan the input via gtkdoc-scangobj
+ # This is such a disgusting hack!
+ add_custom_command(
+ OUTPUT
+ ${_output_signals}
+ DEPENDS
+ ${_output_types}
+ COMMAND ${CMAKE_COMMAND}
+ -D "GTKDOC_SCANGOBJ_EXE:STRING=${GTKDOC_SCANGOBJ_EXE}"
+ -D "_scanobjopts:STRING=${_scanobjopts}"
+ -D "doc_prefix:STRING=${_doc_prefix}"
+ -D "output_types:STRING=${_output_types}"
+ -D "output_dir:STRING=${_output_dir}"
+ -D "EXTRA_CFLAGS:STRING=${_extra_cflags}"
+ -D "EXTRA_LDFLAGS:STRING=${_extra_ldflags}"
+ -D "EXTRA_LDPATH:STRING=${_extra_ldpath}"
+ -P ${GTKDOC_SCANGOBJ_WRAPPER}
+ WORKING_DIRECTORY "${_output_dir}"
+ VERBATIM)
+
+ set(_copy_xml_if_needed "")
+ if(_xml_file)
+ get_filename_component(_xml_file ${_xml_file} ABSOLUTE)
+ set(_copy_xml_if_needed
+ COMMAND ${CMAKE_COMMAND} -E copy "${_xml_file}" "${_default_xml_file}")
+ endif(_xml_file)
+
+ set(_remove_xml_if_needed "")
+ if(_xml_file)
+ set(_remove_xml_if_needed
+ COMMAND ${CMAKE_COMMAND} -E remove ${_default_xml_file})
+ endif(_xml_file)
+
+ set(_copy_content_files_if_needed "")
+ if(_content_files)
+ foreach(_content_file ${_content_files})
+ # We need to copy the content files to the build directory.
+ # We respect the folder tree if the file comes from the current
+ # source or binary directory but copy the file to the current binary
+ # directory if it comes from somewhere else.
+ get_filename_component(_content_file ${_content_file} ABSOLUTE)
+ string(REGEX MATCH "^${CMAKE_CURRENT_SOURCE_DIR}" _is_in_source ${_content_file})
+ string(REGEX MATCH "^${CMAKE_CURRENT_BINARY_DIR}" _is_in_binary ${_content_file})
+ if (_is_in_source OR _is_in_binary)
+ if(_is_in_source)
+ file(RELATIVE_PATH _content_file_relative ${CMAKE_CURRENT_SOURCE_DIR} ${_content_file})
+ else(_is_in_source)
+ file(RELATIVE_PATH _content_file_relative ${CMAKE_CURRENT_BINARY_DIR} ${_content_file})
+ endif(_is_in_source)
+ set(_content_file_destination
+ "${_output_dir}/${_content_file_relative}")
+ else(_is_in_source OR _is_in_binary)
+ get_filename_component(_content_file_name ${_content_file} NAME)
+ set(_content_file_destination
+ "${_output_dir}/${_content_file_name}")
+ endif(_is_in_source OR _is_in_binary)
+ get_filename_component(_content_file_destination ${_content_file_destination} ABSOLUTE)
+ if(NOT ${_content_file_destination} EQUAL ${_content_file})
+ set(_copy_content_files_if_needed
+ ${_copy_content_files_if_needed}
+ COMMAND ${CMAKE_COMMAND} -E copy "${_content_file}" "${_content_file_destination}")
+ endif(NOT ${_content_file_destination} EQUAL ${_content_file})
+ endforeach(_content_file)
+ endif(_content_files)
+
+ # add a command to make the database
+ add_custom_command(
+ OUTPUT
+ ${_output_sgml_stamp}
+ ${_default_xml_file}
+ DEPENDS
+ ${_output_types}
+ ${_output_signals}
+ ${_output_sections}
+ ${_output_overrides}
+ ${_depends}
+ ${_remove_xml_if_needed}
+ COMMAND ${CMAKE_COMMAND} -E remove_directory ${_output_xml_dir}
+ ${_copy_xml_if_needed}
+ ${_copy_content_files_if_needed}
+ COMMAND ${GTKDOC_MKDB_EXE}
+ --module=${_doc_prefix}
+ ${_source_dirs_opt}
+ --source-suffixes=${_doc_source_suffixes}
+ --output-format=xml
+ --main-sgml-file=${_default_xml_file}
+ ${_mkdbopts}
+ WORKING_DIRECTORY "${_output_dir}"
+ VERBATIM)
+
+ # add a command to create html directory
+ add_custom_command(
+ OUTPUT "${_output_html_dir_stamp}" "${_output_html_dir}"
+ COMMAND ${CMAKE_COMMAND} -E make_directory ${_output_html_dir}
+ COMMAND ${CMAKE_COMMAND} -E touch ${_output_html_dir_stamp}
+ VERBATIM)
+
+ # add a command to output HTML
+ add_custom_command(
+ OUTPUT
+ ${_output_html_stamp}
+ DEPENDS
+ ${_output_html_dir_stamp}
+ ${_output_sgml_stamp}
+ ${_xml_file}
+ ${_depends}
+ ${_copy_xml_if_needed}
+ # The binary dir needs adding to --path in order for mkhtml to pick up
+ # any version.xml file there might be in there
+ COMMAND
+ cd ${_output_html_dir} && ${GTKDOC_MKHTML_EXE}
+ ${_doc_prefix}
+ ${_default_xml_file}
+ ${_htmlopts}
+ COMMAND
+ cd ${_output_dir} && ${GTKDOC_FIXXREF_EXE}
+ --module=${_doc_prefix}
+ --module-dir=${_output_html_dir}
+ ${_fixxrefopts}
+ COMMENT
+ "Generating HTML documentation for ${_doc_prefix} module with gtkdoc-mkhtml"
+ VERBATIM)
+
+ add_custom_target(doc-${_doc_prefix}
+ DEPENDS "${_output_html_stamp}")
+endfunction(gtk_doc_add_module)
+
+# These two functions reimplement some of the core logic of CMake, in order
+# to generate compiler and linker flags from the relevant target properties.
+# It sucks that we have to do this, but CMake's own code for this doesn't seem
+# to be reusable -- there's no way to say "tell me the flags that you would
+# pass to a linker for this target".
+
+function(_gtk_doc_get_cflags_for_target result_var target)
+ get_target_property(target_definitions ${target} COMPILE_DEFINITIONS)
+ if(target_definitions)
+ foreach(target_definition ${target_definitions})
+ # We need to prepend -D to the definition flag
+ list(APPEND cflags -D${target_definition})
+ endforeach()
+ endif()
+
+ get_target_property(target_options ${target} COMPILE_OPTIONS)
+ if(target_options)
+ list(APPEND cflags ${target_options})
+ endif()
+
+ get_target_property(target_include_dirs ${target} INCLUDE_DIRECTORIES)
+ foreach(target_include_dir ${target_include_dirs})
+ list(APPEND cflags -I${target_include_dir})
+ endforeach()
+
+ list(REMOVE_DUPLICATES cflags)
+ list(SORT cflags)
+
+ set(${result_var} ${cflags} PARENT_SCOPE)
+endfunction()
+
+function(_gtk_doc_get_ldflags_for_target result_var target all_targets)
+ get_target_property(target_link_flags ${target} LINK_FLAGS)
+ if(target_link_flags)
+ list(APPEND ldflags ${target_link_flags})
+ endif()
+
+ get_target_property(target_link_libraries ${target} LINK_LIBRARIES)
+ foreach(target_library ${target_link_libraries})
+ # The IN_LIST operator is new in CMake 3.3, so I've tried to avoid using it.
+ list(FIND all_targets ${target_library} target_library_is_explicit_dependency)
+ if(NOT ${target_library_is_explicit_dependency} EQUAL -1)
+ # This target is part of the current project. We will add it to
+ # LDFLAGS explicitly, so don't try to add it as well.
+ # In fact, we can't do that, as the containing directory
+ # probably won't be in the linker search path, and we can't find
+ # that out and add it ourselves.
+ else()
+ list(APPEND ldflags "${target_library}")
+ endif()
+ endforeach()
+
+ # Link in the actual target, as well.
+ list(APPEND ldflags $<TARGET_FILE:${target}>)
+
+ list(REMOVE_DUPLICATES ldflags)
+ list(SORT ldflags)
+
+ set(${result_var} ${ldflags} PARENT_SCOPE)
+endfunction()
+++ /dev/null
-# CMake macros to use the GtkDoc documentation system
-#
-# See the GTK-Doc manual (help/manual/C/index.docbook) for an example of how to
-# use this.
-
-# Output variables:
-#
-# GTKDOC_FOUND ... set to 1
-#
-# GTKDOC_SCAN_EXE ... the location of the gtkdoc-scan executable
-# GTKDOC_SCANGOBJ_EXE ... the location of the gtkdoc-scangobj executable
-# GTKDOC_MKDB_EXE ... the location of the gtkdoc-mkdb executable
-# GTKDOC_MKHTML_EXE ... the location of the gtkdoc-mkhtml executable
-# GTKDOC_FIXXREF_EXE ... the location of the gtkdoc-fixxref executable
-
-
-#=============================================================================
-# Copyright 2009 Rich Wareham
-# Copyright 2015 Lautsprecher Teufel GmbH
-#
-# 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, see <http://www.gnu.org/licenses/>.
-#=============================================================================
-
-include(CMakeParseArguments)
-
-set(GTKDOC_FOUND 1)
-
-set(GTKDOC_SCAN_EXE @bindir@/gtkdoc-scan)
-set(GTKDOC_SCANGOBJ_EXE @bindir@/gtkdoc-scangobj)
-set(GTKDOC_MKDB_EXE @bindir@/gtkdoc-mkdb)
-set(GTKDOC_MKHTML_EXE @bindir@/gtkdoc-mkhtml)
-set(GTKDOC_FIXXREF_EXE @bindir@/gtkdoc-fixxref)
-
-get_filename_component(_this_dir ${CMAKE_CURRENT_LIST_FILE} PATH)
-find_file(GTKDOC_SCANGOBJ_WRAPPER GtkDocScanGObjWrapper.cmake PATH ${_this_dir})
-
-# ::
-#
-# gtk_doc_add_module(doc_prefix
-# SOURCE <sourcedir> [...]
-# XML xmlfile
-# [LIBRARIES depend1...]
-# [FIXXREFOPTS fixxrefoption1...]
-# [IGNOREHEADERS header1...])
-#
-# Add a module with documentation to be processed with GTK-Doc.
-#
-# <sourcedir> must be the *full* path to the source directory.
-#
-# If omitted, xmlfile defaults to the auto generated ${doc_prefix}/${doc_prefix}-docs.xml.
-#
-# The `gtkdoc-scangobj` program is used to get introspection information for
-# the module. You should pass the target(s) to be scanned as LIRARIES. This
-# will try to set the correct compiler and link flags for the introspection
-# build to use, and the correct LD_LIBRARY_PATH for it to run, and the correct
-# dependencies for the doc target.
-#
-# You *can* also set the compile and link flags manually, using the 'CFLAGS'
-# and 'LDFLAGS' options. The 'LDPATH' option controls the LD_LIBRARY_PATH. You
-# can also manually add additional targets as dependencies of the
-# documentation build with the DEPENDS option.
-#
-# This function a target named "doc-${doc_prefix}". You will need to manually
-# add it to the ALL target if you want it to be built by default, you can do
-# something like this:
-#
-# gtk_doc_add_module(doc-mymodule
-# SOURCE ${CMAKE_SOURCE_DIR}/module ${CMAKE_BINARY_DIR}/module
-# LIBRARIES mylibrary
-# LIBRARY_DIRS ${GLIB_LIBRARY_DIRS} ${FOO_LIBRARY_DIRS}
-# add_custom_target(all-documentation ALL)
-# add_dependencies(all-documentation doc-mymodule)
-#
-function(gtk_doc_add_module _doc_prefix)
- set(_one_value_args "XML")
- set(_multi_value_args "FIXXREFOPTS" "IGNOREHEADERS" "LIBRARIES" "LIBRARY_DIRS" "SOURCE" "SUFFIXES"
- "CFLAGS" "DEPENDS" "LDFLAGS" "LDPATH")
- cmake_parse_arguments("GTK_DOC" "" "${_one_value_args}" "${_multi_value_args}" ${ARGN})
-
- if(NOT GTK_DOC_SOURCE)
- message(FATAL_ERROR "No SOURCE specified for gtk_doc_add_module ${_doc_prefix}")
- endif()
-
- set(_xml_file ${GTK_DOC_XML})
-
- set(_fixxrefopts ${GTK_DOC_FIXXREFOPTS})
- set(_ignore_headers ${GTK_DOC_IGNOREHEADERS})
- set(_libraries ${GTK_DOC_LIBRARIES})
- set(_library_dirs ${GTK_DOC_LIBRARY_DIRS})
- set(_suffixes ${GTK_DOC_SUFFIXES})
-
- set(_extra_cflags ${GTK_DOC_CFLAGS})
- set(_depends ${GTK_DOC_DEPENDS})
- set(_extra_ldflags ${GTK_DOC_LDFLAGS})
- set(_extra_ldpath ${GTK_DOC_LDPATH})
-
- if(_suffixes)
- set(_doc_source_suffixes "")
- foreach(_suffix ${_suffixes})
- if(_doc_source_suffixes)
- set(_doc_source_suffixes "${_doc_source_suffixes},${_suffix}")
- else(_doc_source_suffixes)
- set(_doc_source_suffixes "${_suffix}")
- endif(_doc_source_suffixes)
- endforeach(_suffix)
- else(_suffixes)
- set(_doc_source_suffixes "h")
- endif(_suffixes)
-
- # Parse the LIBRARIES option and collect compile and link flags for those
- # targets.
- foreach(target ${_libraries})
- _gtk_doc_get_cflags_for_target(_target_cflags ${target})
- _gtk_doc_get_ldflags_for_target(_target_ldflags ${target} "${_libraries}")
- list(APPEND _extra_cflags ${_target_cflags})
- list(APPEND _extra_ldflags ${_target_ldflags})
- list(APPEND _extra_ldpath $<TARGET_FILE_DIR:${target}>)
-
- list(APPEND _depends ${target})
- endforeach()
-
- # Link directories can't be specified per target, only for every target
- # under a given directory.
- get_property(all_library_directories DIRECTORY PROPERTY LINK_DIRECTORIES)
- foreach(library_dir ${all_library_directories})
- list(APPEND _extra_ldflags ${CMAKE_LIBRARY_PATH_FLAG}${library_dir})
- list(APPEND _extra_ldpath ${library_dir})
- endforeach()
-
- # a directory to store output.
- set(_output_dir "${CMAKE_CURRENT_BINARY_DIR}/${_doc_prefix}")
- set(_output_dir_stamp "${_output_dir}/dir.stamp")
-
- # set default sgml file if not specified
- set(_default_xml_file "${_output_dir}/${_doc_prefix}-docs.xml")
- get_filename_component(_default_xml_file ${_default_xml_file} ABSOLUTE)
-
- # a directory to store html output.
- set(_output_html_dir "${_output_dir}/html")
- set(_output_html_dir_stamp "${_output_dir}/html_dir.stamp")
-
- # The output files
- set(_output_decl_list "${_output_dir}/${_doc_prefix}-decl-list.txt")
- set(_output_decl "${_output_dir}/${_doc_prefix}-decl.txt")
- set(_output_overrides "${_output_dir}/${_doc_prefix}-overrides.txt")
- set(_output_sections "${_output_dir}/${_doc_prefix}-sections.txt")
- set(_output_types "${_output_dir}/${_doc_prefix}.types")
-
- set(_output_signals "${_output_dir}/${_doc_prefix}.signals")
-
- set(_output_unused "${_output_dir}/${_doc_prefix}-unused.txt")
- set(_output_undeclared "${_output_dir}/${_doc_prefix}-undeclared.txt")
- set(_output_undocumented "${_output_dir}/${_doc_prefix}-undocumented.txt")
-
- set(_output_xml_dir "${_output_dir}/xml")
- set(_output_sgml_stamp "${_output_dir}/sgml.stamp")
-
- set(_output_html_stamp "${_output_dir}/html.stamp")
-
- # add a command to create output directory
- add_custom_command(
- OUTPUT "${_output_dir_stamp}" "${_output_dir}"
- COMMAND ${CMAKE_COMMAND} -E make_directory "${_output_dir}"
- COMMAND ${CMAKE_COMMAND} -E touch ${_output_dir_stamp}
- VERBATIM)
-
- set(_ignore_headers_opt "")
- if(_ignore_headers)
- set(_ignore_headers_opt "--ignore-headers=")
- foreach(_header ${_ignore_headers})
- set(_ignore_headers_opt "${_ignore_headers_opt}${_header} ")
- endforeach(_header ${_ignore_headers})
- endif(_ignore_headers)
-
- foreach(source_dir ${GTK_DOC_SOURCE})
- set(_source_dirs_opt ${_source_dirs_opt} --source-dir=${source_dir})
- endforeach()
-
- # add a command to scan the input
- add_custom_command(
- OUTPUT
- "${_output_decl_list}"
- "${_output_decl}"
- "${_output_overrides}"
- "${_output_sections}"
- "${_output_types}"
- DEPENDS
- "${_output_dir_stamp}"
- ${_depends}
- COMMAND
- ${GTKDOC_SCAN_EXE}
- --module=${_doc_prefix}
- ${_ignore_headers_opt}
- ${_source_dirs_opt}
- --rebuild-sections
- --rebuild-types
- WORKING_DIRECTORY ${_output_dir}
- VERBATIM)
-
- # add a command to scan the input via gtkdoc-scangobj
- # This is such a disgusting hack!
- add_custom_command(
- OUTPUT
- ${_output_signals}
- DEPENDS
- ${_output_types}
- COMMAND ${CMAKE_COMMAND}
- -D "GTKDOC_SCANGOBJ_EXE:STRING=${GTKDOC_SCANGOBJ_EXE}"
- -D "doc_prefix:STRING=${_doc_prefix}"
- -D "output_types:STRING=${_output_types}"
- -D "output_dir:STRING=${_output_dir}"
- -D "EXTRA_CFLAGS:STRING=${_extra_cflags}"
- -D "EXTRA_LDFLAGS:STRING=${_extra_ldflags}"
- -D "EXTRA_LDPATH:STRING=${_extra_ldpath}"
- -P ${GTKDOC_SCANGOBJ_WRAPPER}
- WORKING_DIRECTORY "${_output_dir}"
- VERBATIM)
-
- set(_copy_xml_if_needed "")
- if(_xml_file)
- get_filename_component(_xml_file ${_xml_file} ABSOLUTE)
- set(_copy_xml_if_needed
- COMMAND ${CMAKE_COMMAND} -E copy "${_xml_file}" "${_default_xml_file}")
- endif(_xml_file)
-
- set(_remove_xml_if_needed "")
- if(_xml_file)
- set(_remove_xml_if_needed
- COMMAND ${CMAKE_COMMAND} -E remove ${_default_xml_file})
- endif(_xml_file)
-
- # add a command to make the database
- add_custom_command(
- OUTPUT
- ${_output_sgml_stamp}
- ${_default_xml_file}
- DEPENDS
- ${_output_types}
- ${_output_signals}
- ${_output_sections}
- ${_output_overrides}
- ${_depends}
- ${_remove_xml_if_needed}
- COMMAND ${CMAKE_COMMAND} -E remove_directory ${_output_xml_dir}
- COMMAND ${GTKDOC_MKDB_EXE}
- --module=${_doc_prefix}
- ${_source_dirs_opt}
- --source-suffixes=${_doc_source_suffixes}
- --output-format=xml
- --main-sgml-file=${_default_xml_file}
- ${_copy_xml_if_needed}
- WORKING_DIRECTORY "${_output_dir}"
- VERBATIM)
-
- # add a command to create html directory
- add_custom_command(
- OUTPUT "${_output_html_dir_stamp}" "${_output_html_dir}"
- COMMAND ${CMAKE_COMMAND} -E make_directory ${_output_html_dir}
- COMMAND ${CMAKE_COMMAND} -E touch ${_output_html_dir_stamp}
- VERBATIM)
-
- # add a command to output HTML
- add_custom_command(
- OUTPUT
- ${_output_html_stamp}
- DEPENDS
- ${_output_html_dir_stamp}
- ${_output_sgml_stamp}
- ${_xml_file}
- ${_depends}
- ${_copy_xml_if_needed}
- # The binary dir needs adding to --path in order for mkhtml to pick up
- # any version.xml file there might be in there
- COMMAND
- cd ${_output_html_dir} && ${GTKDOC_MKHTML_EXE}
- ${_doc_prefix}
- ${_default_xml_file}
- COMMAND
- cd ${_output_dir} && ${GTKDOC_FIXXREF_EXE}
- --module=${_doc_prefix}
- --module-dir=${_output_html_dir}
- ${_fixxref_opts}
- COMMENT
- "Generating HTML documentation for ${_doc_prefix} module with gtkdoc-mkhtml"
- VERBATIM)
-
- add_custom_target(doc-${_doc_prefix}
- DEPENDS "${_output_html_stamp}")
-endfunction(gtk_doc_add_module)
-
-# These two functions reimplement some of the core logic of CMake, in order
-# to generate compiler and linker flags from the relevant target properties.
-# It sucks that we have to do this, but CMake's own code for this doesn't seem
-# to be reusable -- there's no way to say "tell me the flags that you would
-# pass to a linker for this target".
-
-function(_gtk_doc_get_cflags_for_target result_var target)
- get_target_property(target_definitions ${target} COMPILE_DEFINITIONS)
- if(target_definitions)
- list(APPEND cflags ${target_definitions})
- endif()
-
- get_target_property(target_options ${target} COMPILE_OPTIONS)
- if(target_options)
- list(APPEND cflags ${target_options})
- endif()
-
- get_target_property(target_include_dirs ${target} INCLUDE_DIRECTORIES)
- foreach(target_include_dir ${target_include_dirs})
- list(APPEND cflags -I${target_include_dir})
- endforeach()
-
- list(REMOVE_DUPLICATES cflags)
- list(SORT cflags)
-
- set(${result_var} ${cflags} PARENT_SCOPE)
-endfunction()
-
-function(_gtk_doc_get_ldflags_for_target result_var target all_targets)
- get_target_property(target_link_flags ${target} LINK_FLAGS)
- if(target_link_flags)
- list(APPEND ldflags ${target_link_flags})
- endif()
-
- get_target_property(target_link_libraries ${target} LINK_LIBRARIES)
- foreach(target_library ${target_link_libraries})
- # The IN_LIST operator is new in CMake 3.3, so I've tried to avoid using it.
- list(FIND all_targets ${target_library} target_library_is_explicit_dependency)
- if(NOT ${target_library_is_explicit_dependency} EQUAL -1)
- # This target is part of the current project. We will add it to
- # LDFLAGS explicitly, so don't try to add it with -l<target> as
- # well. In fact, we can't do that, as the containing directory
- # probably won't be in the linker search path, and we can't find
- # that out and add it ourselves.
- elseif(EXISTS ${target_library})
- # Pass the filename directly to the linker.
- list(APPEND ldflags "${target_library}")
- else()
- # Pass -l<filename> to the linker.
- list(APPEND ldflags "${CMAKE_LINK_LIBRARY_FLAG}${target_library}")
- endif()
- endforeach()
-
- # Link in the actual target, as well.
- list(APPEND ldflags $<TARGET_FILE:${target}>)
-
- list(REMOVE_DUPLICATES ldflags)
- list(SORT ldflags)
-
- set(${result_var} ${ldflags} PARENT_SCOPE)
-endfunction()
pkg_check_modules(GLIB REQUIRED glib-2.0 gobject-2.0)
foreach(_flag ${EXTRA_CFLAGS} ${GLIB_CFLAGS})
- set(ENV{CFLAGS} "$ENV{CFLAGS} \"${_flag}\"")
+ set(ENV{CFLAGS} "$ENV{CFLAGS} '${_flag}'")
endforeach(_flag)
foreach(_flag ${EXTRA_LDFLAGS} ${GLIB_LDFLAGS})
- set(ENV{LDFLAGS} "$ENV{LDFLAGS} \"${_flag}\"")
+ set(ENV{LDFLAGS} "$ENV{LDFLAGS} '${_flag}'")
endforeach(_flag)
foreach(_flag ${EXTRA_LDPATH})
- if(ENV{LD_LIBRARY_PATH})
- set(ENV{LD_LIBRARY_PATH} "$ENV{LD_LIBRARY_PATH}:\"${_flag}\"")
- else(ENV{LD_LIBRARY_PATH})
+ if(DEFINED ENV{LD_LIBRARY_PATH})
+ set(ENV{LD_LIBRARY_PATH} "$ENV{LD_LIBRARY_PATH}:${_flag}")
+ else(DEFINED ENV{LD_LIBRARY_PATH})
set(ENV{LD_LIBRARY_PATH} "${_flag}")
- endif(ENV{LD_LIBRARY_PATH})
+ endif(DEFINED ENV{LD_LIBRARY_PATH})
endforeach(_flag)
message(STATUS "Executing gtkdoc-scangobj with:")
"--module=${doc_prefix}"
"--types=${output_types}"
"--output-dir=${output_dir}"
+ ${_scanobjopts}
WORKING_DIRECTORY "${output_dir}"
RESULT_VARIABLE _scan_result)
EXTRA_DIST = \
- GtkDocConfig.cmake.in \
+ GtkDocConfig.cmake \
GtkDocConfigVersion.cmake.in \
GtkDocScanGObjWrapper.cmake
CLEANFILES = \
- GtkDocConfig.cmake \
GtkDocConfigVersion.cmake
-# Generate this here rather than via configure.ac so that
-# bindir is substituted as an expanded path rather than
-# using ${exec_prefix} as it would if substituted via
-# configure.ac.
-GtkDocConfig.cmake: GtkDocConfig.cmake.in
- $(SED) -e 's|[@]bindir@|$(bindir)|g' < "$<" > "$@"
-
-cmakedir = $(libdir)/cmake/GtkDoc
+cmakedir = $(datadir)/cmake/GtkDoc
cmake_DATA = \
GtkDocConfig.cmake \
GtkDocConfigVersion.cmake \
host_triplet = @host@
subdir = buildsystems/cmake
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
EXTRA_DIST = \
- GtkDocConfig.cmake.in \
+ GtkDocConfig.cmake \
GtkDocConfigVersion.cmake.in \
GtkDocScanGObjWrapper.cmake
CLEANFILES = \
- GtkDocConfig.cmake \
GtkDocConfigVersion.cmake
-cmakedir = $(libdir)/cmake/GtkDoc
+cmakedir = $(datadir)/cmake/GtkDoc
cmake_DATA = \
GtkDocConfig.cmake \
GtkDocConfigVersion.cmake \
.PRECIOUS: Makefile
-# Generate this here rather than via configure.ac so that
-# bindir is substituted as an expanded path rather than
-# using ${exec_prefix} as it would if substituted via
-# configure.ac.
-GtkDocConfig.cmake: GtkDocConfig.cmake.in
- $(SED) -e 's|[@]bindir@|$(bindir)|g' < "$<" > "$@"
-
-include $(top_srcdir)/git.mk
# Tell versions [3.59,3.63) of GNU make to not export all variables.
#! /bin/sh
# Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.69 for gtk-doc 1.29.
+# Generated by GNU Autoconf 2.69 for gtk-doc 1.30.
#
# 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.29'
-PACKAGE_STRING='gtk-doc 1.29'
+PACKAGE_VERSION='1.30'
+PACKAGE_STRING='gtk-doc 1.30'
PACKAGE_BUGREPORT='http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc'
PACKAGE_URL=''
TEST_DEPS_CFLAGS
PYTHON_PACKAGE_DIR
PACKAGE_DATA_DIR
-HIGHLIGHT_OPTIONS
-HIGHLIGHT
XMLCATALOG
XML_CATALOG_FILE
FOP
docdir
oldincludedir
includedir
+runstatedir
localstatedir
sharedstatedir
sysconfdir
with_sysroot
enable_libtool_lock
with_xml_catalog
-with_highlight
enable_debug
with_help_dir
'
sysconfdir='${prefix}/etc'
sharedstatedir='${prefix}/com'
localstatedir='${prefix}/var'
+runstatedir='${localstatedir}/run'
includedir='${prefix}/include'
oldincludedir='/usr/include'
docdir='${datarootdir}/doc/${PACKAGE_TARNAME}'
| -silent | --silent | --silen | --sile | --sil)
silent=yes ;;
+ -runstatedir | --runstatedir | --runstatedi | --runstated \
+ | --runstate | --runstat | --runsta | --runst | --runs \
+ | --run | --ru | --r)
+ ac_prev=runstatedir ;;
+ -runstatedir=* | --runstatedir=* | --runstatedi=* | --runstated=* \
+ | --runstate=* | --runstat=* | --runsta=* | --runst=* | --runs=* \
+ | --run=* | --ru=* | --r=*)
+ runstatedir=$ac_optarg ;;
+
-sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb)
ac_prev=sbindir ;;
-sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \
for ac_var in exec_prefix prefix bindir sbindir libexecdir datarootdir \
datadir sysconfdir sharedstatedir localstatedir includedir \
oldincludedir docdir infodir htmldir dvidir pdfdir psdir \
- libdir localedir mandir
+ libdir localedir mandir runstatedir
do
eval ac_val=\$$ac_var
# Remove trailing slashes.
# Omit some internal or obsolete options to make the list less imposing.
# This message is too long to be a string in the A/UX 3.1 sh.
cat <<_ACEOF
-\`configure' configures gtk-doc 1.29 to adapt to many kinds of systems.
+\`configure' configures gtk-doc 1.30 to adapt to many kinds of systems.
Usage: $0 [OPTION]... [VAR=VALUE]...
--sysconfdir=DIR read-only single-machine data [PREFIX/etc]
--sharedstatedir=DIR modifiable architecture-independent data [PREFIX/com]
--localstatedir=DIR modifiable single-machine data [PREFIX/var]
+ --runstatedir=DIR modifiable per-process data [LOCALSTATEDIR/run]
--libdir=DIR object code libraries [EPREFIX/lib]
--includedir=DIR C header files [PREFIX/include]
--oldincludedir=DIR C header files for non-gcc [/usr/include]
if test -n "$ac_init_help"; then
case $ac_init_help in
- short | recursive ) echo "Configuration of gtk-doc 1.29:";;
+ short | recursive ) echo "Configuration of gtk-doc 1.30:";;
esac
cat <<\_ACEOF
compiler's sysroot if not specified).
--with-xml-catalog=CATALOG
path to xml catalog to use
- --with-highlight Select source code syntax highlighter
- (no|source-highlight|highlight|vim|auto)
--with-help-dir=DIR path where help files are installed
Some influential environment variables:
test -n "$ac_init_help" && exit $ac_status
if $ac_init_version; then
cat <<\_ACEOF
-gtk-doc configure 1.29
+gtk-doc configure 1.30
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.29, which was
+It was created by gtk-doc $as_me 1.30, which was
generated by GNU Autoconf 2.69. Invocation command line was
$ $0 $@
# Define the identity of the package.
PACKAGE='gtk-doc'
- VERSION='1.29'
+ VERSION='1.30'
cat >>confdefs.h <<_ACEOF
lt_cv_deplibs_check_method=pass_all
;;
-netbsd*)
+netbsd* | netbsdelf*-gnu)
if echo __ELF__ | $CC -E - | $GREP __ELF__ > /dev/null; then
lt_cv_deplibs_check_method='match_pattern /lib[^/]+(\.so\.[0-9]+\.[0-9]+|_pic\.a)$'
else
openbsd* | bitrig*)
with_gnu_ld=no
;;
+ linux* | k*bsd*-gnu | gnu*)
+ link_all_deplibs=no
+ ;;
esac
ld_shlibs=yes
fi
;;
- netbsd*)
+ netbsd* | netbsdelf*-gnu)
if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then
archive_cmds='$LD -Bshareable $libobjs $deplibs $linker_flags -o $lib'
wlarc=
if test yes = "$lt_cv_irix_exported_symbol"; then
archive_expsym_cmds='$CC -shared $pic_flag $libobjs $deplibs $compiler_flags $wl-soname $wl$soname `test -n "$verstring" && func_echo_all "$wl-set_version $wl$verstring"` $wl-update_registry $wl$output_objdir/so_locations $wl-exports_file $wl$export_symbols -o $lib'
fi
+ link_all_deplibs=no
else
archive_cmds='$CC -shared $libobjs $deplibs $compiler_flags -soname $soname `test -n "$verstring" && func_echo_all "-set_version $verstring"` -update_registry $output_objdir/so_locations -o $lib'
archive_expsym_cmds='$CC -shared $libobjs $deplibs $compiler_flags -soname $soname `test -n "$verstring" && func_echo_all "-set_version $verstring"` -update_registry $output_objdir/so_locations -exports_file $export_symbols -o $lib'
esac
;;
- netbsd*)
+ netbsd* | netbsdelf*-gnu)
if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then
archive_cmds='$LD -Bshareable -o $lib $libobjs $deplibs $linker_flags' # a.out
else
# before this can be enabled.
hardcode_into_libs=yes
- # Add ABI-specific directories to the system library path.
- sys_lib_dlsearch_path_spec="/lib64 /usr/lib64 /lib /usr/lib"
-
# Ideally, we could use ldconfig to report *all* directores which are
# searched for libraries, however this is still not possible. Aside from not
# being certain /sbin/ldconfig is available, command
# appending ld.so.conf contents (and includes) to the search path.
if test -f /etc/ld.so.conf; then
lt_ld_extra=`awk '/^include / { system(sprintf("cd /etc; cat %s 2>/dev/null", \$2)); skip = 1; } { if (!skip) print \$0; skip = 0; }' < /etc/ld.so.conf | $SED -e 's/#.*//;/^[ ]*hwcap[ ]/d;s/[:, ]/ /g;s/=[^=]*$//;s/=[^= ]* / /g;s/"//g;/^$/d' | tr '\n' ' '`
- sys_lib_dlsearch_path_spec="$sys_lib_dlsearch_path_spec $lt_ld_extra"
+ sys_lib_dlsearch_path_spec="/lib /usr/lib $lt_ld_extra"
fi
# We used to test for /lib/ld.so.1 and disable shared libraries on
dynamic_linker='GNU/Linux ld.so'
;;
+netbsdelf*-gnu)
+ version_type=linux
+ need_lib_prefix=no
+ need_version=no
+ library_names_spec='${libname}${release}${shared_ext}$versuffix ${libname}${release}${shared_ext}$major ${libname}${shared_ext}'
+ soname_spec='${libname}${release}${shared_ext}$major'
+ shlibpath_var=LD_LIBRARY_PATH
+ shlibpath_overrides_runpath=no
+ hardcode_into_libs=yes
+ dynamic_linker='NetBSD ld.elf_so'
+ ;;
+
netbsd*)
version_type=sunos
need_lib_prefix=no
$as_echo_n "(cached) " >&6
else
- for am_cv_pathless_PYTHON in python python2 python3 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 python2.6 python2.5 python2.4 python2.3 python2.2 python2.1 python2.0 none; do
+ for am_cv_pathless_PYTHON in python python2 python3 python3.8 python3.7 python3.6 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 python2.6 python2.5 python2.4 python2.3 python2.2 python2.1 python2.0 none; do
test "$am_cv_pathless_PYTHON" = none && break
prog="import sys
# split strings by '.' and convert to numeric. Append some zeros
-# Check whether --with-highlight was given.
-if test "${with_highlight+set}" = set; then :
- withval=$with_highlight;
-else
- with_highlight=auto
-fi
-
-
-case $with_highlight in
- no|source-highlight|highlight|vim|auto) ;;
- *) as_fn_error $? "Invalid value for syntax highlighting option." "$LINENO" 5 ;;
-esac
-
-HIGHLIGHT_OPTIONS=""
-if test "$with_highlight" = "auto"; then
- # Extract the first word of "source-highlight", so it can be a program name with args.
-set dummy source-highlight; 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_HIGHLIGHT+:} false; then :
- $as_echo_n "(cached) " >&6
-else
- case $HIGHLIGHT in
- [\\/]* | ?:[\\/]*)
- ac_cv_path_HIGHLIGHT="$HIGHLIGHT" # 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_HIGHLIGHT="$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
-HIGHLIGHT=$ac_cv_path_HIGHLIGHT
-if test -n "$HIGHLIGHT"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: $HIGHLIGHT" >&5
-$as_echo "$HIGHLIGHT" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
-fi
-
-
- if test -n "$HIGHLIGHT"; then
- HIGHLIGHT_OPTIONS="-t4 -s\$SRC_LANG -cstyle.css --no-doc -i"
- else
- # Extract the first word of "highlight", so it can be a program name with args.
-set dummy highlight; 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_HIGHLIGHT+:} false; then :
- $as_echo_n "(cached) " >&6
-else
- case $HIGHLIGHT in
- [\\/]* | ?:[\\/]*)
- ac_cv_path_HIGHLIGHT="$HIGHLIGHT" # 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_HIGHLIGHT="$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
-HIGHLIGHT=$ac_cv_path_HIGHLIGHT
-if test -n "$HIGHLIGHT"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: $HIGHLIGHT" >&5
-$as_echo "$HIGHLIGHT" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
-fi
-
-
- if test -n "$HIGHLIGHT"; then
- HIGHLIGHT_OPTIONS="--syntax=\$SRC_LANG --out-format=xhtml -f --class-name=gtkdoc "
- else
- # Extract the first word of "vim", so it can be a program name with args.
-set dummy vim; 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_HIGHLIGHT+:} false; then :
- $as_echo_n "(cached) " >&6
-else
- case $HIGHLIGHT in
- [\\/]* | ?:[\\/]*)
- ac_cv_path_HIGHLIGHT="$HIGHLIGHT" # 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_HIGHLIGHT="$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
-HIGHLIGHT=$ac_cv_path_HIGHLIGHT
-if test -n "$HIGHLIGHT"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: $HIGHLIGHT" >&5
-$as_echo "$HIGHLIGHT" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
-fi
-
-
- if test -n "$HIGHLIGHT"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: checking whether vim has +syntax feature" >&5
-$as_echo_n "checking whether vim has +syntax feature... " >&6; }
- if $HIGHLIGHT --version | grep '+syntax' >/dev/null; 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; }
- HIGHLIGHT=
- fi
- fi
- fi
- fi
-else
- if test "$with_highlight" != "no"; then
- # Extract the first word of "$with_highlight", so it can be a program name with args.
-set dummy $with_highlight; 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_HIGHLIGHT+:} false; then :
- $as_echo_n "(cached) " >&6
-else
- case $HIGHLIGHT in
- [\\/]* | ?:[\\/]*)
- ac_cv_path_HIGHLIGHT="$HIGHLIGHT" # 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_HIGHLIGHT="$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
-
- test -z "$ac_cv_path_HIGHLIGHT" && ac_cv_path_HIGHLIGHT="no"
- ;;
-esac
-fi
-HIGHLIGHT=$ac_cv_path_HIGHLIGHT
-if test -n "$HIGHLIGHT"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: $HIGHLIGHT" >&5
-$as_echo "$HIGHLIGHT" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
-fi
-
-
- fi
-
- case $with_highlight in
- source-highlight) HIGHLIGHT_OPTIONS="-t4 -s\$SRC_LANG -cstyle.css --no-doc -i";;
- highlight) HIGHLIGHT_OPTIONS="--syntax=\$SRC_LANG --out-format=xhtml -f --class-name=gtkdoc ";;
- vim)
- { $as_echo "$as_me:${as_lineno-$LINENO}: checking whether vim has +syntax feature" >&5
-$as_echo_n "checking whether vim has +syntax feature... " >&6; }
- if $HIGHLIGHT --version | grep '+syntax' >/dev/null; 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; }
- HIGHLIGHT=no
- fi
- ;;
- esac
-
- if test "$HIGHLIGHT" = "no" && test "$with_highlight" != "no"; then
- as_fn_error $? "Could not find requested syntax highlighter" "$LINENO" 5
- fi
-fi
-
-
-
PACKAGE_DATA_DIR="${datadir}/${PACKAGE}/data"
prefix_NONE=
elif test "x$$lc" != "xC"; then \
if test "x$(YELP_LC_MEDIA_LINKS)" != "x"; then \
echo "$(LN_S) -f $(HELP_DIR)/C/$(HELP_ID)/$$f $$helpdir$$f"; \
- $(LN_S) -f "$(HELP_DIR)/C/$(HELP_ID)/$$f" "$$helpdir$$f" || exit 1; \
+ dname="$$f"; \
+ pars="../"; \
+ while test "$$dname" != "." -a "$$dname" != "/"; do \
+ pars="../$$pars"; \
+ dname=$$(dirname "$$dname"); \
+ done; \
+ $(LN_S) -f $$pars"C/$(HELP_ID)/$$f" "$$helpdir$$f" || exit 1; \
fi; \
fi; \
done; \
fi
-# buildsystems/cmake/GtkDocConfig.cmake is handled in the Makefile, not here.
+
+ if test -z $PYTHON;
+ then
+ if test -z "";
+ then
+ PYTHON="python3"
+ else
+ PYTHON=""
+ fi
+ fi
+ PYTHON_NAME=`basename $PYTHON`
+ { $as_echo "$as_me:${as_lineno-$LINENO}: checking $PYTHON_NAME module: \"pygments\"" >&5
+$as_echo_n "checking $PYTHON_NAME module: \"pygments\"... " >&6; }
+ $PYTHON -c "import "pygments"" 2>/dev/null
+ if test $? -eq 0;
+ then
+ { $as_echo "$as_me:${as_lineno-$LINENO}: result: yes" >&5
+$as_echo "yes" >&6; }
+ eval `$as_echo "HAVE_PYMOD_"pygments"" | $as_tr_cpp`=yes
+ else
+ { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+ eval `$as_echo "HAVE_PYMOD_"pygments"" | $as_tr_cpp`=no
+ #
+ if test -n ""
+ then
+ as_fn_error $? "failed to find required module \"pygments\"" "$LINENO" 5
+ exit 1
+ fi
+ fi
+
+
ac_config_files="$ac_config_files Makefile gtk-doc.pc buildsystems/autotools/Makefile buildsystems/cmake/Makefile buildsystems/cmake/GtkDocConfigVersion.cmake gtkdoc/config.py help/Makefile help/manual/Makefile tests/Makefile tests/annotations/Makefile tests/annotations/src/Makefile tests/annotations/docs/Makefile tests/bugs/Makefile tests/bugs/src/Makefile tests/bugs/docs/Makefile tests/empty/Makefile tests/empty/src/Makefile tests/empty/docs/Makefile tests/fail/Makefile tests/fail/src/Makefile tests/fail/docs/Makefile tests/gobject/Makefile tests/gobject/src/Makefile tests/gobject/docs/Makefile tests/program/Makefile tests/program/src/Makefile tests/program/docs/Makefile tests/repro/Makefile tests/repro/src/Makefile tests/repro/docs/Makefile"
# 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.29, which was
+This file was extended by gtk-doc $as_me 1.30, 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.29
+gtk-doc config.status 1.30
configured by $0, generated by GNU Autoconf 2.69,
with options \\"\$ac_cs_config\\"
cat <<_LT_EOF >> "$cfgfile"
#! $SHELL
# Generated automatically by $as_me ($PACKAGE) $VERSION
-# Libtool was configured on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
# NOTE: Changes made to this file will be lost: look at ltmain.sh.
# Provide generalized library-building support services.
$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;} \
- || { $as_echo "$as_me:${as_lineno-$LINENO}: Syntax highlighting of examples disabled" >&5
-$as_echo "$as_me: Syntax highlighting of examples disabled" >&6;}
test "x$build_tests" != "xno" \
&& { $as_echo "$as_me:${as_lineno-$LINENO}: ** Building regression tests" >&5
$as_echo "$as_me: ** Building regression tests" >&6;} \
dnl We're using a two digit number for the releases and
dnl a three digit number for the development version
-m4_define(gtk_doc_version, 1.29)
+m4_define(gtk_doc_version, 1.30)
AC_INIT([gtk-doc],[gtk_doc_version],[http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc],[gtk-doc])
JH_CHECK_XML_CATALOG([-//OASIS//DTD DocBook XML V4.3//EN], [DocBook XML DTD V4.3])
JH_CHECK_XML_CATALOG([http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl], [DocBook XSL Stylesheets])
-dnl
-dnl Check for syntax highlighters
-dnl
-AC_ARG_WITH([highlight],
- AS_HELP_STRING([--with-highlight], [Select source code syntax highlighter (no|source-highlight|highlight|vim|auto)]),
- , [with_highlight=auto])
-
-case $with_highlight in
- no|source-highlight|highlight|vim|auto) ;;
- *) AC_MSG_ERROR([Invalid value for syntax highlighting option.]) ;;
-esac
-
-HIGHLIGHT_OPTIONS=""
-if test "$with_highlight" = "auto"; then
- AC_PATH_PROG([HIGHLIGHT], [source-highlight])
- if test -n "$HIGHLIGHT"; then
- HIGHLIGHT_OPTIONS="-t4 -s\$SRC_LANG -cstyle.css --no-doc -i"
- else
- AC_PATH_PROG([HIGHLIGHT], [highlight])
- if test -n "$HIGHLIGHT"; then
- HIGHLIGHT_OPTIONS="--syntax=\$SRC_LANG --out-format=xhtml -f --class-name=gtkdoc "
- else
- AC_PATH_PROG([HIGHLIGHT], [vim])
- if test -n "$HIGHLIGHT"; then
- dnl vim is useless if it does not support syntax highlighting
- AC_MSG_CHECKING([whether vim has +syntax feature])
- if $HIGHLIGHT --version | grep '+syntax' >/dev/null; then
- AC_MSG_RESULT([yes])
- else
- AC_MSG_RESULT([no])
- HIGHLIGHT=
- fi
- fi
- fi
- fi
-else
- if test "$with_highlight" != "no"; then
- AC_PATH_PROG([HIGHLIGHT], [$with_highlight], [no])
- fi
-
- case $with_highlight in
- source-highlight) HIGHLIGHT_OPTIONS="-t4 -s\$SRC_LANG -cstyle.css --no-doc -i";;
- highlight) HIGHLIGHT_OPTIONS="--syntax=\$SRC_LANG --out-format=xhtml -f --class-name=gtkdoc ";;
- vim)
- AC_MSG_CHECKING([whether vim has +syntax feature])
- if $HIGHLIGHT --version | grep '+syntax' >/dev/null; then
- AC_MSG_RESULT([yes])
- else
- AC_MSG_RESULT([no])
- HIGHLIGHT=no
- fi
- ;;
- esac
-
- if test "$HIGHLIGHT" = "no" && test "$with_highlight" != "no"; then
- AC_MSG_ERROR([Could not find requested syntax highlighter])
- fi
-fi
-AC_SUBST([HIGHLIGHT_OPTIONS])
-
dnl
dnl Set runtime package dirs so we can find the script containing common routines.
dnl
fi
AM_CONDITIONAL([HAVE_YELP_TOOLS],[test x$have_yelp_tools = xyes])
-# buildsystems/cmake/GtkDocConfig.cmake is handled in the Makefile, not here.
+dnl
+dnl Python modules
+dnl
+AX_PYTHON_MODULE("pygments")
+
AC_CONFIG_FILES([Makefile
gtk-doc.pc
buildsystems/autotools/Makefile
test -n "$DBLATEX$FOP" \
&& 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])
test "x$build_tests" != "xno" \
&& AC_MSG_NOTICE([** Building regression tests]) \
|| AC_MSG_NOTICE([ Skipping regression tests])
<xsd:simpleType name="language-type">
<xsd:annotation>
<xsd:documentation>
- Known programing languages.
+ Known programming languages.
</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:element name="sub">
<xsd:annotation>
<xsd:documentation>
- Sub tags for the hierachy of the chapters and parts.
+ Sub tags for the hierarchy of the chapters and parts.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:attribute name="language" type="language-type">
<xsd:annotation>
<xsd:documentation>
- Programing language this manual refers to.
+ Programming language this manual refers to.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
# e.g. content_files=running.xml building.xml changes-2.0.xml
content_files=
-# Files where gtk-doc abbrevations (#GtkWidget) are expanded
+# Files where gtk-doc abbreviations (#GtkWidget) are expanded
# e.g. expand_content_files=running.xml
expand_content_files=
<homepage rdf:resource="http://www.gtk.org/gtk-doc/" />
<mailing-list rdf:resource="http://mail.gnome.org/mailman/listinfo/gtk-doc-devel-list" />
<download-page rdf:resource="http://download.gnome.org/sources/gtk-doc/" />
- <bug-database rdf:resource="http://bugzilla.gnome.org/browse.cgi?product=gtk-doc" />
+ <bug-database rdf:resource="https://gitlab.gnome.org/GNOME/gtk-doc/issues/" />
<category rdf:resource="http://api.gnome.org/doap-extensions#core" />
<programming-language>C</programming-language>
<!-- import the chunked XSL stylesheet -->
<!-- http://www.sagehill.net/docbookxsl/Chunking.html#FastChunking says we should use
- "chunkfast.xsl", but I can't see a difference. Also it is not clear wheter
+ "chunkfast.xsl", but I can't see a difference. Also it is not clear whether
one should still set "chunk.fast". Again, no meassuable difference. -->
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>
<xsl:include href="devhelp2.xsl"/>
<!-- ========================================================= -->
<!-- l10n is slow, we don't ue it, so we'd like to turn it off
- this atleast avoid the re-evaluation -->
+ this at least avoid the re-evaluation -->
<xsl:template name="l10n.language">en</xsl:template>
<xsl:param name="gtkdoc.l10n.xml" select="document('http://docbook.sourceforge.net/release/xsl/current/common/en.xml')"/>
</xsl:when>
<!-- this is not yet very nice, as it requires all glossdic/indexdiv
elements having a anchor element. maybe we can customize the xsl
- to automaticaly create local anchors
+ to automatically create local anchors
-->
<xsl:when test="count($glssections) > 0">
<span id="nav_glossary">
parser.add_argument('--version', action='version', version=config.version)
parser.add_argument('--path', default=[], action='append',
help='Extra source directories')
+ parser.add_argument('--extra-dir', default=[], action='append',
+ help='Directories to recursively scan for indices (*.devhelp2)'
+ 'in addition to HTML_DIR')
parser.add_argument('--src-lang', default='c',
help='Programing language used for syntax highlighting. This'
'can be any language pygments supports.')
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('--cflags', type=str, default=[], help='Compiler flags',
+ action='append')
+ parser.add_argument('--ldflags', type=str, default=[], help='Linker flags',
+ action='append')
parser.add_argument('--run', default='',
help='Command for running the scanner')
parser.add_argument('--verbose', action='store_true', default=False,
if options.types == '':
options.types = os.path.join(options.output_dir, options.module + '.types')
+ if options.cflags:
+ options.cflags = ' '.join(options.cflags)
+ if options.ldflags:
+ options.ldflags = ' '.join(options.ldflags)
if not options.cc:
options.cc = os.environ.get('CC', 'gcc')
import re
from glob import glob
-from . import common
-
class FileFormatError(Exception):
pass
def get_variable(env, lines, variable):
- value = env.get(variable,
- grep(r'^\s*' + variable + r'\s*=\s*(\S+)', lines, variable))
+ value = env.get(variable, None)
+ if value is None:
+ value = grep(r'^\s*' + variable + r'\s*=\s*(\S+)', lines, variable)
return value
param_num += 1
continue
- logging.warning('Cannnot parse args for function in "%s"', declaration)
+ logging.warning('Cannot parse args for function in "%s"', declaration)
break
return result
-version = "1.29"
+version = "1.30"
# tools
-dblatex = ''
+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/local'
+prefix = '/usr'
datarootdir = "${prefix}/share".replace('${prefix}', prefix)
datadir = "${datarootdir}".replace('${datarootdir}', datarootdir)
# tools
dblatex = '@DBLATEX@'
fop = '@FOP@'
-highlight = '@HIGHLIGHT@'
-highlight_options = '@HIGHLIGHT_OPTIONS@'
pkg_config = '@PKG_CONFIG@'
xsltproc = '@XSLTPROC@'
import logging
import os
import re
-import shlex
-import subprocess
-import sys
-import tempfile
-from . import common, config
+from . import common, highlight
# This contains all the entities and their relative URLs.
Links = {}
LoadIndicies(options.module_dir, options.html_dir, options.extra_dir)
ReadSections(options.module)
FixCrossReferences(options.module_dir, options.module, options.src_lang)
+ highlight.append_style_defs(os.path.join(options.module_dir, 'style.css'))
# TODO(ensonic): try to refactor so that we get a list of path's and then just
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.
+ # first, but these will be overridden by any later scans.
dir = common.GetModuleDocDir('glib-2.0')
if dir and os.path.exists(dir):
# Some predefined link targets to get links into type hierarchies as these
content = open(file, 'r', encoding='utf-8').read()
- if config.highlight:
- # FIXME: ideally we'd pass a clue about the example language to the highligher
- # 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(src_lang, 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(src_lang, 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)
+ # 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>
+ def repl_func(m):
+ return HighlightSourcePygments(src_lang, 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')
return (tid, href)
# poor mans plural support
- if id.endswith('s'):
+ if id.endswith('es'):
+ tid = id[:-2]
+ href = Links.get(tid)
+ if href:
+ return (tid, href)
+ tid += '-struct'
+ href = Links.get(tid)
+ if href:
+ return (tid, href)
+ elif id.endswith('s'):
tid = id[:-1]
href = Links.get(tid)
if href:
def MakeGtkDocLink(pre, symbol, post):
id = common.CreateValidSGMLID(symbol)
- # these are implicitely created links in highlighed sources
+ # these are implicitly created links in highlighted 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(src_lang, 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', 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(src_lang, 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! plugin/tohtml.vim|run! syntax/2html.vim|w! %s.html|qa!' | " % (
- temp_source_file, 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", 'r', encoding='utf-8').read()
- highlighted_source = re.sub(r'.*<pre\b[^>]*>\n', '', highlighted_source, flags=re.DOTALL)
- highlighted_source = re.sub(r'</pre>.*', '', highlighted_source, flags=re.DOTALL)
-
- # 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):
+def HighlightSourcePygments(src_lang, div_class, source):
# chop of leading and trailing empty lines, leave leading space in first real line
source = source.strip(' ')
source = source.strip('\n')
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
+ highlighted_source = highlight.highlight_code(source, src_lang)
+ if not highlighted_source:
+ highlighted_source = source
-def HighlightSourcePostprocess(type, highlighted_source):
# chop of leading and trailing empty lines
highlighted_source = highlighted_source.strip()
</tbody>
</table>
</div>
-""" % (type, source_lines, highlighted_source)
+""" % (div_class, source_lines, highlighted_source)
--- /dev/null
+#!/usr/bin/env python3
+# -*- python; coding: utf-8 -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2018 Stefan Sauer
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+
+"""
+Highlight sourcecode snippets.
+"""
+import os
+import stat
+
+from pygments import highlight
+from pygments.lexers import CLexer
+from pygments.lexers import get_lexer_by_name
+from pygments.formatters import HtmlFormatter
+
+# lazily constructed lexer cache
+LEXERS = {
+ 'c': CLexer()
+}
+HTML_FORMATTER = HtmlFormatter(nowrap=True)
+
+
+def highlight_code(code, lang='c'):
+ if lang not in LEXERS:
+ LEXERS[lang] = get_lexer_by_name(lang)
+ lexer = LEXERS.get(lang, None)
+ if not lexer:
+ return None
+ return highlight(code, lexer, HTML_FORMATTER)
+
+
+def append_style_defs(css_file_name):
+ os.chmod(css_file_name, stat.S_IWRITE)
+ with open(css_file_name, 'at', newline='\n', encoding='utf-8') as css:
+ css.write(HTML_FORMATTER.get_style_defs())
MODULE = None
DB_OUTPUT_DIR = None
INLINE_MARKUP_MODE = None
-DEFAULT_STABILITY = None
NAME_SPACE = ''
ROOT_DIR = '.'
Deprecated = {}
Since = {}
StabilityLevel = {}
+# TODO; we can eliminate this, one case that we need to fix is to combine
+# struct/union decls with a separate typedef. This works right now since we
+# parse the tyedef after the struct/enum decl and thus have the dict filled
+# before we output the struct/typedef.
StructHasTypedef = {}
# These global hashes store the existing documentation.
# holds the symbols which are mentioned in <MODULE>-sections.txt and in which
# section they are defined
-KnownSymbols = {}
+KnownSymbols = {} # values are 1 for public symbols and 0 otherwise
SymbolSection = {}
SymbolSectionId = {}
'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).",
+ 'default': "Default parameter value (in case a function which shadows this one via <acronym>rename-to</acronym> has fewer 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.",
def Run(options):
- global MODULE, INLINE_MARKUP_MODE, DEFAULT_STABILITY, NAME_SPACE, \
- DB_OUTPUT_DIR, doctype_header
+ global MODULE, INLINE_MARKUP_MODE, NAME_SPACE, DB_OUTPUT_DIR, doctype_header
logging.info('options: %s', str(options.__dict__))
# 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
else:
main_sgml_file = MODULE + "-docs.xml"
+ # -- phase 1: read files produced by previous tools and scane sources
+
# 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"))
+ obj_tree = ReadObjectHierarchy(os.path.join(ROOT_DIR, MODULE + ".hierarchy"))
ReadInterfaces(os.path.join(ROOT_DIR, MODULE + ".interfaces"))
ReadPrerequisites(os.path.join(ROOT_DIR, MODULE + ".prerequisites"))
if os.path.isfile(os.path.join(ROOT_DIR, MODULE + "-overrides.txt")):
ReadDeclarationsFile(os.path.join(ROOT_DIR, MODULE + "-overrides.txt"), 1)
+ logging.info("Data files read")
+
+ # -- phase 2: scan sources
+
+ # TODO: move this to phase 3 once we fixed the call to OutputProgramDBFile()
+ 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)
+
# Scan sources
if options.source_suffixes:
suffix_list = ['.' + ext for ext in options.source_suffixes.split(',')]
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("Sources scanned")
- logging.info("All files created: %d", changed)
+ # -- phase 3: write docbook files
+
+ changed, book_top, book_bottom = OutputDB(os.path.join(ROOT_DIR, MODULE + "-sections.txt"), options)
+ OutputBook(main_sgml_file, book_top, book_bottom, obj_tree)
# 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")):
+ # TODO: MakeIndexterms() uses NAME_SPACE, but also fills IndexEntriesFull
+ # which DetermineNamespace is using
+ # Can we use something else?
+ # no: AllSymbols, KnownSymbols
+ # IndexEntriesFull: consist of all symbols from sections file + signals and properties
+ #
+ # logging.info('# index_entries_full=%d, # declarations=%d',
+ # len(IndexEntriesFull), len(Declarations))
+ # logging.info('known_symbols - index_entries_full: ' + str(Declarations.keys() - IndexEntriesFull.keys()))
# try to detect the common prefix
# GtkWidget, GTK_WIDGET, gtk_widget -> gtk
if NAME_SPACE == '':
- NAME_SPACE = DetermineNamespace()
+ NAME_SPACE = DetermineNamespace(IndexEntriesFull.keys())
logging.info('namespace prefix ="%s"', NAME_SPACE)
+ OutputObjectTree(obj_tree)
+ OutputObjectList()
+
OutputIndex("api-index-full", IndexEntriesFull)
OutputIndex("api-index-deprecated", IndexEntriesDeprecated)
OutputSinceIndexes()
with open(os.path.join(ROOT_DIR, 'sgml.stamp'), 'w') as h:
h.write('timestamp')
+ logging.info("All files created: %d", changed)
+
+ # TODO: eliminate some of those global collections
+ logging.info('# symbol_docs=%d, source_symbol_docs=%d',
+ len(SymbolDocs), len(SourceSymbolDocs))
+ logging.info('# symbol_params=%d, source_symbol_params=%d',
+ len(SymbolParams), len(SourceSymbolParams))
+
def OutputObjectList():
"""This outputs the alphabetical list of objects, in a columned table."""
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"
+ key = filename + ":title"
if key in SourceSymbolDocs:
title = SourceSymbolDocs[key].rstrip()
elif re.search(r'^<\/SECTION>', line):
logging.info("End of section: %s", title)
# TODO: also output if we have sections docs?
- # long_desc = SymbolDocs.get(filename + ":Long_Description")
+ # long_desc = SymbolDocs.get(filename + ":long_description")
if num_symbols > 0:
# collect documents
book_bottom += " <xi:include href=\"xml/%s.xml\"/>\n" % filename
- key = filename + ":Include"
+ key = filename + ":include"
if key in SourceSymbolDocs:
if section_includes:
common.LogWarning(file, line_number, "Section <INCLUDE> being overridden by inline comments.")
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">
+<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="name" colwidth="150px"/>
<colspec colname="description"/>
hierarchy_str, interfaces,
implementations,
prerequisites, derived,
- file_objects)
+ file_objects,
+ options.default_stability)
if file_changed:
changed = True
filename = filename.replace(' ', '_')
- section_id = SourceSymbolDocs.get(filename + ":Section_Id")
+ 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()
return (changed, book_top, book_bottom)
-def DetermineNamespace():
- """Find common set of characters."""
+def DetermineNamespace(symbols):
+ """Find common set of characters.
+
+ Args:
+ symbols (list): a list of symbols to scan for a common prefix
+
+ Returns:
+ str: a common namespace prefix (might be empty)
+ """
name_space = ''
pos = 0
ratio = 0.0
while True:
prefix = {}
letter = ''
- for symbol in IndexEntriesFull.keys():
+ for symbol in symbols:
if name_space == '' or name_space.lower() in symbol.lower():
if len(symbol) > pos:
letter = symbol[pos:pos + 1]
maxletter = letter
maxsymbols = prefix[letter]
- ratio = float(len(IndexEntriesFull)) / prefix[maxletter]
+ ratio = float(len(symbols)) / prefix[maxletter]
logging.debug('most symbols start with %s, that is %f', maxletter, (100 * ratio))
if ratio > 0.9:
# do another round
common.UpdateFileIfChanged(old_glossary, new_glossary, 0)
+def OutputObjectTree(tree):
+ if not tree:
+ return
+
+ # FIXME: use 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")
+
+ with open(new_tree_index, 'w', encoding='utf-8') as out:
+ out.write(MakeDocHeader("screen"))
+ out.write("\n<screen>\n")
+ out.write(AddTreeLineArt(tree))
+ out.write("\n</screen>\n")
+
+ common.UpdateFileIfChanged(old_tree_index, new_tree_index, 0)
+
+
def ReadKnownSymbols(file):
"""Collect the names of non-private symbols from the $MODULE-sections.txt file.
m = re.search(r'^<FILE>(.*)<\/FILE>', line)
if m:
- KnownSymbols[m.group(1) + ":Long_Description"] = 1
- KnownSymbols[m.group(1) + ":Short_Description"] = 1
+ KnownSymbols[m.group(1) + ":long_description"] = 1
+ KnownSymbols[m.group(1) + ":short_description"] = 1
continue
m = re.search(r'^<INCLUDE>(.*)<\/INCLUDE>', line)
declaration (str): the declaration of the macro.
Returns:
- str: the formated docs
+ str: the formatted docs
"""
sid = common.CreateValidSGMLID(symbol)
condition = MakeConditionDescription(symbol)
e.g. 'typedef unsigned int guint;'
Returns:
- str: the formated docs
+ str: the formatted docs
"""
sid = common.CreateValidSGMLID(symbol)
condition = MakeConditionDescription(symbol)
declaration (str): the declaration of the struct.
Returns:
- str: the formated docs
+ str: the formatted docs
"""
is_gtype = False
default_to_public = True
has_typedef = False
if symbol in StructHasTypedef or re.search(r'^\s*typedef\s+', declaration):
has_typedef = True
+ logging.info('symbol "%s" has decl "%s"', symbol, declaration)
type_output = None
desc = None
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)
+ field_descrs, found = GetSymbolParams(symbol)
if found:
- field_descrs = params
missing_parameters = ''
unused_parameters = ''
sid = common.CreateValidSGMLID(symbol + ".members")
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, 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)
declaration (str): the declaration of the union.
Returns:
- str: the formated docs
+ str: the formatted docs
"""
is_gtype = False
if CheckIsObject(symbol):
has_typedef = False
if symbol in StructHasTypedef or re.search(r'^\s*typedef\s+', declaration):
has_typedef = True
+ logging.info('symbol "%s" has decl "%s"', symbol, declaration)
type_output = None
desc = None
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)
+ field_descrs, found = GetSymbolParams(symbol)
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 += "<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, param_annotations = ExpandAnnotation(symbol, field_descrs[field_name])
field_descr = ConvertMarkDown(symbol, field_descr)
# trim
declaration (str): the declaration of the enum.
Returns:
- str: the formated docs
+ str: the formatted docs
"""
is_gtype = False
if CheckIsObject(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 = {}
+ field_descrs, found = GetSymbolParams(symbol)
missing_parameters = ''
unused_parameters = ''
declaration (str): the declaration of the variable.
Returns:
- str: the formated docs
+ str: the formatted docs
"""
sid = common.CreateValidSGMLID(symbol)
condition = MakeConditionDescription(symbol)
if symbol in SymbolAnnotations:
param_desc = SymbolAnnotations[symbol]
- param_annotations = ''
- (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc)
+ param_desc, param_annotations = ExpandAnnotation(symbol, param_desc)
if param_annotations != '':
desc += "\n<para>%s</para>" % param_annotations
declaration (str): the declaration of the function.
Returns:
- str: the formated docs
+ str: the formatted docs
"""
sid = common.CreateValidSGMLID(symbol)
condition = MakeConditionDescription(symbol)
if symbol in SymbolAnnotations:
param_desc = SymbolAnnotations[symbol]
- (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc)
+ param_desc, param_annotations = ExpandAnnotation(symbol, param_desc)
if param_annotations != '':
desc += "\n<para>%s</para>" % param_annotations
undocumented/unused entries
Returns:
- str: the formated parameter docs
+ str: the formatted parameter docs
"""
output = ''
num_params = 0
unused_parameters = ''
for param_name, param_desc in params.items():
- (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc)
+ 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)
return str(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):
+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, default_stability):
"""Outputs the final DocBook file for one section.
Args:
prerequisites (str): the DocBook for the Prerequisites part
derived (str): the DocBook for the Derived Interfaces part
file_objects (list): objects in this file
+ default_stability (str): fallback if no api-stability is set (optional)
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")
+ 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")
+ 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)
+ short_desc = ExpandAbbreviations(title + ":short_description", short_desc)
logging.info("Found short_desc: %s", short_desc)
- long_desc = SymbolDocs.get(file + ":Long_Description")
+ 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)
+ long_desc = ConvertMarkDown(title + ":long_description", long_desc)
logging.info("Found long_desc: %s", long_desc)
- see_also = SymbolDocs.get(file + ":See_Also")
+ 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)
+ 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")
+ stability = SymbolDocs.get(file + ":stability")
if not stability or re.search(r'^\s*$', stability):
stability = ''
else:
- line_number = GetSymbolSourceLine(file + ":Stability_Level")
+ line_number = GetSymbolSourceLine(file + ":stability")
stability = ParseStabilityLevel(stability, file, line_number, "Section stability level")
logging.info("Found stability: %s", stability)
if not stability:
- stability = DEFAULT_STABILITY or ''
+ stability = default_stability or ''
if stability:
if stability in AnnotationDefinition:
stability = "<refsect1 id=\"%s.stability-level\">\n<title>Stability Level</title>\n%s, unless otherwise indicated\n</refsect1>\n" % (
section_id, stability)
- image = SymbolDocs.get(file + ":Image")
+ image = SymbolDocs.get(file + ":image")
if not image or re.search(r'^\s*$', image):
image = ''
else:
"""
logging.info("Output program docbook for %s", program)
- short_desc = SourceSymbolDocs.get(program + ":Short_Description")
+ short_desc = SourceSymbolDocs.get(program + ":short_description")
if not short_desc or short_desc.strip() == '':
short_desc = ''
else:
short_desc = ExpandAbbreviations(program, short_desc)
logging.info("Found short_desc: %s", short_desc)
- synopsis = SourceSymbolDocs.get(program + ":Synopsis")
+ synopsis = SourceSymbolDocs.get(program + ":synopsis")
if synopsis and synopsis.strip() != '':
items = synopsis.split(' ')
for i in range(0, len(items)):
else:
synopsis = "<command>%s</command>" % program
- long_desc = SourceSymbolDocs.get(program + ":Long_Description")
+ 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)
+ long_desc = ConvertMarkDown("%s:long_description" % program, long_desc)
logging.info("Found long_desc: %s", long_desc)
options = ''
- o = program + ":Options"
+ o = program + ":options"
if o in SourceSymbolDocs:
opts = SourceSymbolDocs[o].split('\t')
options += "</variablelist></refsect1>\n"
- exit_status = SourceSymbolDocs.get(program + ":Returns")
+ exit_status = SourceSymbolDocs.get(program + ":returns")
if exit_status and exit_status != '':
- exit_status = ConvertMarkDown("%s:Returns" % program, 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")
+ 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)
+ see_also = ConvertMarkDown("%s:see_also" % program, see_also)
logging.info("Found see_also: %s", see_also)
if see_also:
return header
-def OutputBook(main_file, book_top, book_bottom):
+def OutputBook(main_file, book_top, book_bottom, obj_tree):
"""Outputs the entities that need to be included into the main docbook file for the module.
Args:
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.
+ obj_tree (list): object tree list
"""
old_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.top")
<title>[Insert title here]</title>
%s </chapter>
''' % (MakeDocHeader("book"), book_bottom))
- if os.path.exists('xml/tree_index.sgml'):
+ if obj_tree:
OUTPUT.write(''' <chapter id="object-tree">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
return text
-def ConvertSGMLChars(symbol, text):
+def ConvertXMLChars(symbol, text):
"""Escape XML chars.
This is used for text in source code comment blocks, to turn
"""
if INLINE_MARKUP_MODE:
- # For the XML/SGML mode only convert to entities outside CDATA sections.
+ # For the XML mode only convert to entities outside CDATA sections.
return ModifyXMLElements(text, symbol,
"<!\\[CDATA\\[|<programlisting[^>]*>",
- ConvertSGMLCharsEndTag,
- ConvertSGMLCharsCallback)
+ ConvertXMLCharsEndTag,
+ ConvertXMLCharsCallback)
# 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.
return text
-def ConvertSGMLCharsEndTag(start_tag):
+def ConvertXMLCharsEndTag(start_tag):
if start_tag == '<![CDATA[':
return "]]>"
return "</programlisting>"
-def ConvertSGMLCharsCallback(text, symbol, tag):
+def ConvertXMLCharsCallback(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)
+ ConvertXMLCharsEndTag,
+ ConvertXMLCharsCallback2)
elif tag == '':
logging.debug('replace entities')
# If we're not in CDATA convert to entities.
return text
-def ConvertSGMLCharsCallback2(text, symbol, tag):
+def ConvertXMLCharsCallback2(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 == '':
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)
+ text = md_to_db.ReplaceEntities(text, symbol)
return text
terms = ''
sortas = ''
- # make the index useful, by ommiting the namespace when sorting
+ # make the index useful, by omitting the namespace when sorting
if NAME_SPACE != '':
m = re.search(r'^%s\_?(.*)' % NAME_SPACE, symbol, flags=re.I)
if m:
def MakeConditionDescription(symbol):
- """This returns a sumary of conditions for the given symbol.
+ """This returns a summary of conditions for the given symbol.
Args:
- symbol (str): the symbol to create the sumary for.
+ symbol (str): the symbol to create the summary for.
Returns:
str: formatted text or empty string if no special conditions apply.
if not found:
return hierarchy
- logging.info("=== Hierachy for: %s (%d existing entries) ===", gobject, len(hierarchy))
+ logging.info("=== Hierarchy for: %s (%d existing entries) ===", gobject, len(hierarchy))
# Walk up the hierarchy, pushing ancestors onto the ancestors array.
ancestors = [gobject]
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
+ # we're missing 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 symbol in SymbolAnnotations:
param_desc = SymbolAnnotations[symbol]
- (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc)
+ param_desc, param_annotations = ExpandAnnotation(symbol, param_desc)
if param_annotations != '':
desc += "\n<para>%s</para>" % param_annotations
arg_desc += blurb
if symbol in SymbolAnnotations:
param_desc = SymbolAnnotations[symbol]
- (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc)
+ param_desc, param_annotations = ExpandAnnotation(symbol, param_desc)
if param_annotations != '':
arg_desc += "\n<para>%s</para>" % param_annotations
suppressed/ignored.
Args:
- file (str): the file to scan.
+ ifile (str): the file to scan.
"""
m = re.search(r'^.*[\/\\]([^\/\\]*)$', ifile)
if m:
logging.info("Skipping source file: %s", ifile)
return
- logging.info("Scanning source file: %s", ifile)
+ logging.info("Scanning %s", ifile)
+
+ with open(ifile, 'r', encoding='utf-8') as src:
+ input_lines = src.readlines()
+
+ for c in ScanSourceContent(input_lines, ifile):
+ ParseCommentBlock(c[0], c[1], ifile)
+
+ logging.info("Scanning %s done", ifile)
+
+
+def ScanSourceContent(input_lines, ifile=''):
+ """Scans the source code lines for specially-formatted comment blocks.
+
+ Updates global state in SourceSymbolDocs, SourceSymbolSourceFile,
+ SourceSymbolSourceLine. Since, StabilityLevel, Deprecated,
+ SymbolAnnotations.
- SRCFILE = open(ifile, 'r', encoding='utf-8')
+ Might read from global state in DeclarationTypes
+
+ Args:
+ input_lines (list): list of source code lines
+ ifile (str): file name of the source file (for reporting)
+
+ Returns:
+ list: tuples with comment block and its starting line
+ """
+ comments = []
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:
+ comment = []
+ starting_line = 0
+ for line in input_lines:
line_number += 1
- # Look for the start of a comment block.
+
if not in_comment_block:
+ # Look for the start of a comment block.
if re.search(r'^\s*/\*.*\*/', line):
# one-line comment - not gtkdoc
pass
logging.info("Found comment block start")
in_comment_block = True
+ comment = []
+ starting_line = line_number + 1
+ else:
+ # Look for end of comment
+ if re.search(r'^\s*\*+/', line):
+ comments.append((comment, starting_line))
+ in_comment_block = False
+ continue
- # Reset all the symbol data.
- symbol = ''
- in_part = ''
- description = ''
- return_desc = ''
- since_desc = ''
- deprecated_desc = ''
- stability_desc = ''
- params = OrderedDict()
- param_name = None
+ # 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 += "\n"
- continue
+ logging.info("scanning :%s", line.strip())
+ comment.append(line)
- # 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 params.items():
- 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 params.items():
- 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 params.items():
- 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)
+ return comments
- 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"
+def SegmentCommentBlock(lines, line_number=0, ifile=''):
+ """Cut a single comment block into segments.
- logging.info("scanning :%s", line.strip())
+ Args:
+ lines (list): the comment block
+ line_number (int): the first line of the block (for reporting)
+ ifile (str): file name of the source file (for reporting)
+
+ Returns:
+ (str, dict): symbol name and dict of comment segments
+ """
+ symbol = None
+ in_part = ''
+ segments = {'body': ''}
+ params = OrderedDict()
+ param_name = None
+ param_indent = None
+ line_number -= 1
+ for line in lines:
+ line_number += 1
+ logging.info("scanning[%s] :%s", in_part, 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)
+ m1 = re.search(r'^\s*((SECTION|PROGRAM):\s*\S+)', line)
+ m2 = 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)
+ logging.info("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()
+ logging.info("docs found in source for : '%s'", symbol)
+ if m2.group(2):
+ annotation = m2.group(2).strip()
if annotation != '':
SymbolAnnotations[symbol] = annotation
logging.info("remaining text for %s: '%s'", symbol, annotation)
continue
- if in_part == "description":
+ if in_part == "body":
# Get rid of 'Description:'
line = re.sub(r'^\s*Description:', '', line)
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"
+ segments[in_part] = line[m1.end():]
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"
+ segments[in_part] = line[m2.end():]
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"
+ segments[in_part] = line[m3.end():]
continue
-
elif m4:
- stability_desc = line[m4.end():]
in_part = "stability"
+ segments[in_part] = line[m4.end():]
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"
+ if in_part in ["body", "return", "since", "stability", "deprecated"]:
+ segments[in_part] += line
continue
# Look for a parameter name.
if m:
param_name = m.group(1)
param_desc = line[m.end():]
+ param_indent = None
- 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 == '':
+
+ # We must be in the parameters (or no-part). Check for the empty line below them.
+ if re.search(r'^\s*$', line):
+ logging.info("blank line, switching from '%s' to 'body'")
+ # TODO: only switch if next line starts without indent?
+ in_part = "body"
+ continue
+
+ if in_part == '':
logging.info("continuation for %s annotation '%s'", symbol, line)
annotation = re.sub(r'^\s+|\s+$', '', line)
if symbol in SymbolAnnotations:
# 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)
+ common.LogWarning(ifile, line_number,
+ "Parsing comment block file : parameter expected, but got '%s'" % line)
else:
+ if not param_indent:
+ # determine indentation of first continuation line
+ spc = len(line) - len(line.lstrip(' '))
+ if spc > 0:
+ param_indent = spc
+ logging.debug("Found param-indentation of %d", param_indent)
+ if param_indent:
+ # cut common indentation (after double checking that it is all spaces)
+ if line[:param_indent].strip() == '':
+ line = line[param_indent:]
+ else:
+ logging.warning("Not cutting param-indentation for %s: '%s'",
+ param_name, line[:param_indent])
+
params[param_name] += line
- SRCFILE.close()
+ return (symbol, segments, params)
+
+
+def ParseCommentBlockSegments(symbol, segments, params, line_number=0, ifile=''):
+ """Parse the comemnts block segments.
+
+ Args:
+ symbol (str): the symbol name
+ segments(dict): the comment block segments (except params)
+ parans (dict): the comment block params
+ line_number (int): the first line of the block (for reporting)
+ ifile (str): file name of the source file (for reporting)
+
+ """
+ # Add the return value description to the end of the params.
+ if "return" in segments:
+ # TODO(ensonic): check for duplicated Return docs
+ # common.LogWarning(file, line_number, "Multiple Returns for %s." % symbol)
+ params['Returns'] = segments["return"]
+
+ # Convert special characters
+ segments["body"] = ConvertXMLChars(symbol, segments["body"])
+ for (param_name, param_desc) in params.items():
+ params[param_name] = ConvertXMLChars(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)
+
+ logging.info("SECTION DOCS found in source for : '%s'", real_symbol)
+ for param_name, param_desc in params.items():
+ logging.info(" '" + param_name + "'")
+ param_name = param_name.lower()
+ if param_name in ['image', 'include', 'section_id', 'see_also', 'short_description', 'stability', 'title']:
+ key = real_symbol + ':' + param_name
+ SourceSymbolDocs[key] = param_desc
+ SourceSymbolSourceFile[key] = ifile
+ SourceSymbolSourceLine[key] = line_number
+
+ key = real_symbol + ":long_description"
+ if key not in KnownSymbols or KnownSymbols[key] != 1:
+ common.LogWarning(
+ ifile, line_number, "Section %s is not defined in the %s-sections.txt file." % (real_symbol, MODULE))
+ SourceSymbolDocs[key] = segments["body"]
+ SourceSymbolSourceFile[key] = ifile
+ SourceSymbolSourceLine[key] = line_number
+ elif m2:
+ real_symbol = m2.group(1)
+ section_id = None
+
+ logging.info("PROGRAM DOCS found in source for '%s'", real_symbol)
+ for param_name, param_desc in params.items():
+ logging.info("PROGRAM key %s: '%s'", real_symbol, param_name)
+ param_name = param_name.lower()
+ if param_name in ['returns', 'section_id', 'see_also', 'short_description', 'synopsis']:
+ key = real_symbol + ':' + param_name
+ logging.info("PROGRAM value %s: '%s'", real_symbol, param_desc.rstrip())
+ SourceSymbolDocs[key] = param_desc.rstrip()
+ SourceSymbolSourceFile[key] = ifile
+ SourceSymbolSourceLine[key] = line_number
+ 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)
+
+ key = real_symbol + ":long_description"
+ SourceSymbolDocs[key] = segments["body"]
+ SourceSymbolSourceFile[key] = ifile
+ SourceSymbolSourceLine[key] = line_number
+
+ # TODO(ensonic): we need to track these somehow and output the files
+ # later, see comment in Run()
+ 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] = segments["body"]
+ SourceSymbolParams[symbol] = params
+ SourceSymbolSourceFile[symbol] = ifile
+ SourceSymbolSourceLine[symbol] = line_number
+
+ if "since" in segments:
+ arr = segments["since"].splitlines()
+ desc = arr[0].strip()
+ extra_lines = arr[1:]
+ logging.info("Since(%s) : [%s]", symbol, desc)
+ Since[symbol] = ConvertXMLChars(symbol, desc)
+ if len(extra_lines) > 1:
+ common.LogWarning(ifile, line_number, "multi-line since docs found")
+
+ if "stability" in segments:
+ desc = ParseStabilityLevel(
+ segments["stability"], ifile, line_number, "Stability level for %s" % symbol)
+ StabilityLevel[symbol] = ConvertXMLChars(symbol, desc)
+
+ if "deprecated" in segments:
+ 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] = ConvertXMLChars(symbol, segments["deprecated"])
+
+
+def ParseCommentBlock(lines, line_number=0, ifile=''):
+ """Parse a single comment block.
+
+ Args:
+ lines (list): the comment block
+ line_number (int): the first line of the block (for reporting)
+ ifile (str): file name of the source file (for reporting)
+ """
+ (symbol, segments, params) = SegmentCommentBlock(lines, line_number, ifile)
+ 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.")
+ return
+
+ ParseCommentBlockSegments(symbol, segments, params, line_number, ifile)
def OutputMissingDocumentation():
# 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)
+ r':(title|long_description|short_description|see_also|stability|include|section_id|image)', symbol)
+ m2 = re.search(r':(long_description|short_description)', symbol)
if not m:
total += 1
if symbol in AllDocumentedSymbols:
the template files.
"""
- # add whats found in the source
+ # add what's found in the source
symbols = set(SourceSymbolDocs.keys())
# and add known symbols from -sections.txt
else:
logging.info("[%s] undocumented", symbol)
- logging.info("num doc entries: %d", len(SymbolDocs))
+ logging.info("num doc entries: %d / %d", len(SymbolDocs), len(SourceSymbolDocs))
def IsEmptyDoc(doc):
def ReadObjectHierarchy(ifile):
- """Reads the $MODULE-hierarchy.txt file.
+ """Reads the $MODULE-hierarchy file.
This contains all the GObject subclasses described in this module (and their
ancestors).
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')
+ logging.debug('no %s file found', ifile)
return
+ Objects[:] = []
+ ObjectLevels[:] = []
+
INPUT = open(ifile, 'r', encoding='utf-8')
# Only emit objects if they are supposed to be documented, or if
#
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))
-
- with open(new_tree_index, 'w', encoding='utf-8') as out:
- out.write(MakeDocHeader("screen"))
- out.write("\n<screen>\n")
- out.write(AddTreeLineArt(tree))
- out.write("\n</screen>\n")
-
- common.UpdateFileIfChanged(old_tree_index, new_tree_index, 0)
-
- OutputObjectList()
+ return tree
def ReadInterfaces(ifile):
return root and root != 'GEnum' and root != 'GFlags'
+def GetSymbolParams(symbol):
+ """Get the symbol params and check that they are not empty.
+
+ If no parameters are filled in, we don't generate the description table,
+ for backwards compatibility.
+
+ Args:
+ symbol: the symbol to check the parameters for
+
+ Returns:
+ dict: The parameters
+ bool: True if empty
+ """
+ params = SymbolParams.get(symbol, {})
+ # TODO: strip at parsing stage?
+ found = next((True for p in params.values() if p.strip() != ''), False)
+ return (params, found)
+
+
def GetSymbolSourceFile(symbol):
"""Get the filename where the symbol docs where taken from."""
return SourceSymbolSourceFile.get(symbol, '')
Please note, that we're not aiming for complete docbook-xml support. All tags
used in the generated xml are of course handled. More tags used in handwritten
-xml can be easilly supported, but for some combinations of tags we prefer
+xml can be easily supported, but for some combinations of tags we prefer
simplicity.
TODO:
Example invocation:
cd tests/bugs/docs/
-../../../gtkdoc-mkhtml2 tester tester-docs.xml
+mkdir -p db2html
+cd dbhtml
+../../../../gtkdoc-mkhtml2 tester ../tester-docs.xml
+cd ..
xdg-open db2html/index.html
meld html db2html
rm html-build.stamp; time make html-build.stamp
"""
-import argparse
-import errno
import logging
import os
import shutil
from copy import deepcopy
from glob import glob
from lxml import etree
-from pygments import highlight
-from pygments.lexers import CLexer
-from pygments.formatters import HtmlFormatter
from timeit import default_timer as timer
-from . import config, fixxref
-
-# pygments setup
-# lazily constructed lexer cache
-LEXERS = {
- 'c': CLexer()
-}
-HTML_FORMATTER = HtmlFormatter(nowrap=True)
+from . import config, highlight, fixxref
class ChunkParams(object):
# docbook xsl does.
#
# For toc levels see http://www.sagehill.net/docbookxsl/TOCcontrol.html
-# TODO: this list has also a flag that controls wheter we add the
+# TODO: this list has also a flag that controls whether we add the
# 'Table of Contents' heading in convert_chunk_with_toc()
CHUNK_PARAMS = {
'appendix': ChunkParams('app', 'book'),
return name
-def get_chunk_titles(module, node):
+def get_chunk_titles(module, node, tree_node):
tag = node.tag
(title, subtitle) = TITLE_XPATHS.get(tag, TITLE_XPATHS['_'])
ctx = {
'module': module,
'files': [],
+ 'node': tree_node,
}
result = {
'title': None,
tag = xml_node.tag
chunk_params = CHUNK_PARAMS.get(tag)
if chunk_params:
- title_args = get_chunk_titles(module, xml_node)
+ title_args = get_chunk_titles(module, xml_node, parent)
chunk_name = gen_chunk_name(xml_node, chunk_params)
# check idx to handle 'sect1'/'section' special casing and title-only
if xml.attrib.get('role', '') == 'example':
if xml.text:
lang = xml.attrib.get('language', ctx['src-lang']).lower()
- if lang not in LEXERS:
- LEXERS[lang] = get_lexer_by_name(lang)
- lexer = LEXERS.get(lang, None)
- if lexer:
- highlighted = highlight(xml.text, lexer, HTML_FORMATTER)
-
+ highlighted = highlight.highlight_code(xml.text, lang)
+ if highlighted:
# we do own line-numbering
line_count = highlighted.count('\n')
source_lines = '\n'.join([str(i) for i in range(1, line_count + 1)])
def convert_index(ctx):
node = ctx['node']
# Get all indexdivs under indexdiv
- indexdivs = node.xml.find('indexdiv').findall('indexdiv')
+ indexdivs = []
+ indexdiv = node.xml.find('indexdiv')
+ if indexdiv is not None:
+ indexdivs = indexdiv.findall('indexdiv')
result = [
HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)),
return nav
+def convert_content(module, files, node, src_lang):
+ converter = convert_chunks.get(node.name)
+ if converter is None:
+ logging.warning('Add chunk converter for "%s"', node.name)
+ return []
+
+ ctx = {
+ 'module': module,
+ 'files': files,
+ 'node': node,
+ 'src-lang': src_lang,
+ }
+ ctx.update(generate_nav_nodes(files, node))
+ return converter(ctx)
+
+
def convert(out_dir, module, files, node, src_lang):
"""Convert the docbook chunks to a html file.
logging.info('Writing: %s', node.filename)
with open(os.path.join(out_dir, node.filename), 'wt',
newline='\n', encoding='utf-8') as html:
- ctx = {
- 'module': module,
- 'files': files,
- 'node': node,
- 'src-lang': src_lang,
- }
- ctx.update(generate_nav_nodes(files, node))
-
- converter = convert_chunks.get(node.name)
- if converter is not None:
- for line in converter(ctx):
- html.write(line)
- else:
- logging.warning('Add chunk converter for "%s"', node.name)
+ for line in convert_content(module, files, node, src_lang):
+ html.write(line)
def create_devhelp2_toc(node):
create_devhelp2_condition_attribs(node))
-def create_devhelp2(out_dir, module, xml, files):
- with open(os.path.join(out_dir, module + '.devhelp2'), 'wt',
- newline='\n', encoding='utf-8') as idx:
- bookinfo_nodes = xml.xpath('/book/bookinfo')
- title = ''
- if bookinfo_nodes is not None:
- bookinfo = bookinfo_nodes[0]
- title = bookinfo.xpath('./title/text()')[0]
- online_url = bookinfo.xpath('./releaseinfo/ulink[@role="online-location"]/@url')[0]
- # TODO: support author too (see devhelp2.xsl)
- # TODO: fixxref uses '--src-lang' to set the language
- result = [
- """<?xml version="1.0" encoding="utf-8" standalone="no"?>
-<book xmlns="http://www.devhelp.net/book" title="%s" link="index.html" author="" name="%s" version="2" language="c" online="%s">
+def create_devhelp2_content(module, xml, files):
+ title = ''
+ online_attr = ''
+ bookinfo_nodes = xml.xpath('/book/bookinfo')
+ if len(bookinfo_nodes):
+ bookinfo = bookinfo_nodes[0]
+ title = bookinfo.xpath('./title/text()')[0]
+ online_url = bookinfo.xpath('./releaseinfo/ulink[@role="online-location"]/@url')
+ if len(online_url):
+ online_attr = ' online="' + online_url[0] + '"'
+ # TODO: support author too (see devhelp2.xsl), it is hardly used though
+ # locate *.devhelp2 | xargs grep -Hn --color ' author="[^"]'
+ # TODO: fixxref uses '--src-lang' to set the language, we have this in options too
+ result = [
+ """<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<book xmlns="http://www.devhelp.net/book" title="%s" link="index.html" author="" name="%s" version="2" language="c"%s>
<chapters>
-""" % (title, module, online_url)
- ]
- # toc
- result.extend(create_devhelp2_toc(files[0].root))
- result.append(""" </chapters>
+""" % (title, module, online_attr)
+ ]
+ # toc
+ result.extend(create_devhelp2_toc(files[0].root))
+ result.append(""" </chapters>
<functions>
""")
- # keywords from all refsect2 and refsect3
- refsect2 = etree.XPath('//refsect2[@role]')
- refsect3_enum = etree.XPath('refsect3[@role="enum_members"]/informaltable/tgroup/tbody/row[@role="constant"]')
- refsect3_enum_details = etree.XPath('entry[@role="enum_member_name"]/para')
- refsect3_struct = etree.XPath('refsect3[@role="struct_members"]/informaltable/tgroup/tbody/row[@role="member"]')
- refsect3_struct_details = etree.XPath('entry[@role="struct_member_name"]/para/structfield')
- for node in files:
- base_link = node.filename + '#'
- refsect2_nodes = refsect2(node.xml)
- for refsect2_node in refsect2_nodes:
- result.append(create_devhelp2_refsect2_keyword(refsect2_node, base_link))
- refsect3_nodes = refsect3_enum(refsect2_node)
- for refsect3_node in refsect3_nodes:
- details_node = refsect3_enum_details(refsect3_node)[0]
- name = details_node.attrib['id']
- result.append(create_devhelp2_refsect3_keyword(refsect3_node, base_link, details_node.text, name))
- refsect3_nodes = refsect3_struct(refsect2_node)
- for refsect3_node in refsect3_nodes:
- details_node = refsect3_struct_details(refsect3_node)[0]
- name = details_node.attrib['id']
- result.append(create_devhelp2_refsect3_keyword(refsect3_node, base_link, name, name))
-
- result.append(""" </functions>
+ # keywords from all refsect2 and refsect3
+ refsect2 = etree.XPath('//refsect2[@role]')
+ refsect3_enum = etree.XPath('refsect3[@role="enum_members"]/informaltable/tgroup/tbody/row[@role="constant"]')
+ refsect3_enum_details = etree.XPath('entry[@role="enum_member_name"]/para')
+ refsect3_struct = etree.XPath('refsect3[@role="struct_members"]/informaltable/tgroup/tbody/row[@role="member"]')
+ refsect3_struct_details = etree.XPath('entry[@role="struct_member_name"]/para/structfield')
+ for node in files:
+ base_link = node.filename + '#'
+ refsect2_nodes = refsect2(node.xml)
+ for refsect2_node in refsect2_nodes:
+ result.append(create_devhelp2_refsect2_keyword(refsect2_node, base_link))
+ refsect3_nodes = refsect3_enum(refsect2_node)
+ for refsect3_node in refsect3_nodes:
+ details_node = refsect3_enum_details(refsect3_node)[0]
+ name = details_node.attrib['id']
+ result.append(create_devhelp2_refsect3_keyword(refsect3_node, base_link, details_node.text, name))
+ refsect3_nodes = refsect3_struct(refsect2_node)
+ for refsect3_node in refsect3_nodes:
+ details_node = refsect3_struct_details(refsect3_node)[0]
+ name = details_node.attrib['id']
+ result.append(create_devhelp2_refsect3_keyword(refsect3_node, base_link, name, name))
+
+ result.append(""" </functions>
</book>
""")
- for line in result:
+ return result
+
+
+def create_devhelp2(out_dir, module, xml, files):
+ with open(os.path.join(out_dir, module + '.devhelp2'), 'wt',
+ newline='\n', encoding='utf-8') as idx:
+ for line in create_devhelp2_content(module, xml, files):
idx.write(line)
def main(module, index_file, out_dir, uninstalled, src_lang, paths):
# == Loading phase ==
- # the next 3 steps could be done in paralel
+ # the next 3 steps could be done in parallel
# 1) load the docuemnt
_t = timer()
css_file = os.path.join(styledir, 'style.css')
for f in glob(os.path.join(styledir, '*.png')) + [css_file]:
shutil.copy(f, out_dir)
- css_file = os.path.join(out_dir, 'style.css')
- with open(css_file, 'at', newline='\n', encoding='utf-8') as css:
- css.write(HTML_FORMATTER.get_style_defs())
+ highlight.append_style_defs(os.path.join(out_dir, 'style.css'))
logging.warning("2: %7.3lf: copy datafiles", timer() - _t)
# 3) load xref targets
_t = timer()
# TODO: migrate options from fixxref
- # TODO: ideally explicity specify the files we need, this will save us the
+ # TODO: ideally explicitly specify the files we need, this will save us the
# globbing and we'll load less files.
fixxref.LoadIndicies(out_dir, '/usr/share/gtk-doc/html', [])
logging.warning("3: %7.3lf: load xrefs", timer() - _t)
module = options.args[0]
document = options.args[1]
- # TODO: rename to 'html' later on
- # - right now in mkhtml, the dir is created by the Makefile and mkhtml
- # outputs into the working directory
- out_dir = os.path.join(os.path.dirname(document), 'db2html')
- try:
- os.mkdir(out_dir)
- except OSError as e:
- if e.errno != errno.EEXIST:
- raise
-
- sys.exit(main(module, document, out_dir, options.uninstalled, options.src_lang,
+ # TODO: pass options.extra_dir
+ sys.exit(main(module, document, os.getcwd(), options.uninstalled, options.src_lang,
options.path))
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
+import logging
import subprocess
from . import config
import logging
import os
import re
-import subprocess
from . import common
other_dirs = []
# We scan the directory containing GLib and any directories in GNOME2_PATH
- # first, but these will be overriden by any later scans.
+ # first, but these will be overridden 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")
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 = {}
+TYPE_MODIFIERS = ['const', 'signed', 'unsigned', 'long', 'short', 'struct', 'union', 'enum']
+VAR_TYPE_MODIFIER = '(?:' + '|'.join([t + '\s+' for t in TYPE_MODIFIERS]) + ')*'
+RET_TYPE_MODIFIER = '(?:' + '|'.join([t + '\s+' for t in TYPE_MODIFIERS + ['G_CONST_RETURN']]) + ')*'
+
+# Matchers for current line
+CLINE_MATCHER = [
+ # 0: MACROS
+ re.compile(
+ r"""^\s*\#\s*define\s+
+ (\w+) # 1: name
+ """, re.VERBOSE),
+ # 1-4: TYPEDEF'D FUNCTIONS
+ re.compile(
+ r"""^\s*typedef\s+
+ (%s\w+) # 1: return type
+ (\s+const)?\s* # 2: 2nd const
+ (\**)\s* # 3: ptr
+ \(\*\s*
+ (\w+) # 4: name
+ \)\s*\(""" % RET_TYPE_MODIFIER, re.VERBOSE),
+ re.compile(
+ r"""^\s*
+ (%s?\w+) # 1: return type
+ (\s+const)?\s* # 2: 2nd const
+ (\**)\s* # 3: ptr
+ \(\*\s*
+ (\w+) # 4: name
+ \)\s*\(""" % RET_TYPE_MODIFIER, re.VERBOSE),
+ re.compile(
+ r"""^\s*
+ (\**)\s* # 1: ptr
+ \(\*\s*
+ (\w+) # 2: name
+ \)\s*\(""", re.VERBOSE),
+ # 4: FUNCTION POINTER VARIABLES
+ None, # in ScanHeaderContent()
+ # 5-7: ENUMS
+ re.compile(
+ r"""^\s*enum\s+
+ _?(\w+) # 1: name
+ \s+\{""", re.VERBOSE),
+ re.compile(r'^\s*typedef\s+enum\s+_?(\w+)\s+\1\s*;'),
+ re.compile(r'^\s*typedef\s+enum'),
+ # 8-11: STRUCTS AND UNIONS
+ re.compile(
+ r"""^\s*typedef\s+
+ (struct|union)\s+ # 1: struct/union
+ _(\w+) # 2: name
+ \s+\2\s*;""", re.VERBOSE),
+ re.compile(r'^\s*(?:struct|union)\s+_(\w+)\s*;'),
+ re.compile(
+ r"""^\s*
+ (struct|union)\s+ # 1: struct/union
+ (\w+) # 2: name
+ \s*;""", re.VERBOSE),
+ re.compile(
+ r"""^\s*typedef\s+
+ (struct|union)\s*
+ \w*\s*{""", re.VERBOSE),
+ # 12-14: OTHER TYPEDEFS
+ re.compile(
+ r"""^\s*typedef\s+
+ (?:struct|union)\s+\w+[\s\*]+
+ (\w+) # 1: name
+ \s*;""", re.VERBOSE),
+ re.compile(
+ r"""^\s*
+ (?:G_GNUC_EXTENSION\s+)?
+ typedef\s+
+ (.+[\s\*]) # 1: e.g. 'unsigned int'
+ (\w+) # 2: name
+ (?:\s*\[[^\]]+\])*
+ \s*;""", re.VERBOSE),
+ re.compile(r'^\s*typedef\s+'),
+ # 15: VARIABLES (extern'ed variables)
+ None, # in ScanHeaderContent()
+ # 16: VARIABLES
+ re.compile(
+ r"""^\s*
+ (?:%s\w+)
+ (?:\s+\*+|\*+|\s)\s*
+ (?:const\s+)*
+ ([A-Za-z]\w*) # 1: name
+ \s*\=""" % VAR_TYPE_MODIFIER, re.VERBOSE),
+ # 17: G_DECLARE_*
+ re.compile(
+ r""".*G_DECLARE_
+ (FINAL_TYPE|DERIVABLE_TYPE|INTERFACE) # 1: variant
+ \s*\(""", re.VERBOSE),
+ # 18-21: FUNCTIONS
+ None, # in ScanHeaderContent()
+ None, # in ScanHeaderContent()
+ re.compile(r'^\s*([A-Za-z]\w*)\s*\('),
+ re.compile(r'^\s*\('),
+ # 22-23: STRUCTS
+ re.compile(r'^\s*struct\s+_?(\w+)\s*\*'),
+ re.compile(r'^\s*struct\s+_?(\w+)'),
+ # 24-25: UNIONS
+ re.compile(r'^\s*union\s+_(\w+)\s*\*'),
+ re.compile(r'^\s*union\s+_?(\w+)'),
+]
+
+# Matchers for previous line
+PLINE_MATCHER = [
+ # 0-1: TYPEDEF'D FUNCTIONS
+ re.compile(
+ r"""^\s*typedef\s*
+ (%s\w+) # 1: return type
+ (\s+const)?\s* # 2: 2nd const
+ (\**)\s* # 3: ptr
+ """ % RET_TYPE_MODIFIER, re.VERBOSE),
+ re.compile(r'^\s*typedef\s*'),
+ # 2-4 :FUNCTIONS
+ None, # in ScanHeaderContent()
+ None, # in ScanHeaderContent()
+ None, # in ScanHeaderContent()
+]
+
+# Matchers for sub expressions
+SUB_MATCHER = [
+ # 0: STRUCTS AND UNIONS
+ re.compile(r'^(\S+)(Class|Iface|Interface)\b'),
+]
def Run(options):
decl_list = []
get_types = []
+ # do not read files twice; checking it here permits to give both srcdir and
+ # builddir as --source-dir without fear of duplicities
+ seen_headers = {}
+
for file in options.headers:
- ScanHeader(file, section_list, decl_list, get_types, options)
+ ScanHeader(file, section_list, decl_list, get_types, seen_headers, options)
for dir in options.source_dir:
- ScanHeaders(dir, section_list, decl_list, get_types, options)
+ ScanHeaders(dir, section_list, decl_list, get_types, seen_headers, options)
with open(new_decl_list, 'w', encoding='utf-8') as f:
for section in sorted(section_list.keys()):
f.write(section_list[section])
+ common.UpdateFileIfChanged(old_decl_list, new_decl_list, True)
with open(new_decl, 'w', encoding='utf-8') as f:
for decl in decl_list:
f.write(decl)
+ common.UpdateFileIfChanged(old_decl, new_decl, True)
if options.rebuild_types:
with open(new_types, 'w', encoding='utf-8') as f:
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.
# 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.
+# Arguments : source_dir - the directory to scan.
+# section_list - a reference to the hashmap of sections.
+# seen_headers - set to avoid scanning headers twice
#
-def ScanHeaders(source_dir, section_list, decl_list, get_types, options):
+def ScanHeaders(source_dir, section_list, decl_list, get_types, seen_headers, options):
logging.info('Scanning source directory: %s', source_dir)
# This array holds any subdirectories found.
if os.path.isdir(fullname):
subdirs.append(file)
elif file.endswith('.h'):
- ScanHeader(fullname, section_list, decl_list, get_types, options)
+ ScanHeader(fullname, section_list, decl_list, get_types,
+ seen_headers, options)
# Now recursively scan the subdirectories.
for dir in subdirs:
if re.search(matchstr, options.ignore_headers):
continue
ScanHeaders(os.path.join(source_dir, dir), section_list, decl_list,
- get_types, options)
+ get_types, seen_headers, options)
#
# 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
+# Arguments : input_file - the header file to scan.
+# section_list - a map of sections.
+# decl_list - a list of declarations
+# seen_headers - set to avoid scanning headers twice
# 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 = ''
-
+def ScanHeader(input_file, section_list, decl_list, get_types, seen_headers, options):
# Don't scan headers twice
canonical_input_file = os.path.realpath(input_file)
if canonical_input_file in seen_headers:
logging.info('Scanning %s', input_file)
- for line in open(input_file, 'r', encoding='utf-8'):
+ with open(input_file, 'r', encoding='utf-8') as hdr:
+ input_lines = hdr.readlines()
+
+ slist, doc_comments = ScanHeaderContent(input_lines, decl_list, get_types, options)
+
+ logging.info("Scanning %s done", input_file)
+
+ liststr = SeparateSubSections(slist, doc_comments)
+ 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)
+
+
+# Scan the the given content lines.
+# Returns: a list of symbols found and a set of symbols for which we have a
+# doc-comment
+def ScanHeaderContent(input_lines, decl_list, get_types, options):
+ # Holds the resulting list of declarations.
+ slist = []
+ # Holds the title of the section
+ title = None
+ # True if we are in a comment.
+ in_comment = 0
+ # The type of declaration we are in, e.g. 'function' or 'macro'.
+ in_declaration = ''
+ # True if we should skip a block.
+ skip_block = 0
+ # The current symbol being declared.
+ symbol = None
+ # Holds the declaration of the current symbol.
+ decl = ''
+ # For functions and function typedefs this holds the function's return type.
+ ret_type = None
+ # 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.
+ pre_previous_line = ''
+ # The previous line read in - some Gnome functions have the return type on
+ # one line and the rest of the declaration after.
+ previous_line = ''
+ # Used to try to skip the standard #ifdef XXX #define XXX at the start of
+ # headers.
+ first_macro = 1
+ # Used to handle structs/unions which contain nested structs or unions.
+ level = None
+ # Set to 1 for internal symbols, we need to fully parse, but don't add them
+ # to docs
+ internal = 0
+ # Dict of forward declarations, we skip them if we find the real declaration
+ # later.
+ forward_decls = {}
+ # Dict of doc-comments we found. The key is lowercase symbol name, val=1.
+ doc_comments = {}
+
+ deprecated_conditional_nest = 0
+ ignore_conditional_nest = 0
+
+ deprecated = ''
+ doc_comment = ''
+
+ # avoid generating regex with |'' (matching no string)
+ ignore_decorators = ''
+ if options.ignore_decorators:
+ ignore_decorators = '|' + options.ignore_decorators
+
+ # FUNCTION POINTER VARIABLES
+ CLINE_MATCHER[4] = re.compile(
+ r"""^\s*(?:\b(?:extern|static|inline|G_INLINE_FUNC%s)\s*)*
+ ((?:const\s+|G_CONST_RETURN\s+)?\w+) # 1: 1st const
+ (\s+const)?\s* # 2: 2nd const
+ (\**)\s* # 3: ptr
+ \(\*\s*
+ (\w+) # 4: name
+ \)\s*\(""" % ignore_decorators, re.VERBOSE)
+ # OTHER TYPEDEFS
+ CLINE_MATCHER[15] = re.compile(
+ r"""^\s*
+ (?:extern|[A-Za-z_]+VAR%s)\s+
+ (?:%s\w+)
+ (?:\s+\*+|\*+|\s)\s*
+ (?:const\s+)*
+ ([A-Za-z]\w*) # 1: name
+ \s*;""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+ # FUNCTIONS
+ CLINE_MATCHER[18] = re.compile(
+ r"""^\s*
+ (?:\b(?:extern|static|inline|G_INLINE_FUNC%s)\s*)*
+ (%s\w+) # 1: return type
+ ([\s*]+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s* # 2: .. cont'
+ (_[A-Za-z]\w*) # 3: name
+ \s*\(""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+ CLINE_MATCHER[19] = re.compile(
+ r"""^\s*
+ (?:\b(?:extern|static|inline|G_INLINE_FUNC%s)\s*)*
+ (%s\w+) # 1: return type
+ ([\s*]+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s* # 2: .. cont'
+ ([A-Za-z]\w*) # 3: name
+ \s*\(""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+
+ PLINE_MATCHER[2] = re.compile(
+ r"""^\s*
+ (?:\b(?:extern%s)\s*)*
+ (%s\w+) # 1: retun type
+ ((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*) # 2: .. cont'
+ \s*$""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+
+ PLINE_MATCHER[3] = re.compile(
+ r"""^\s*(?:\b(?:extern|static|inline|G_INLINE_FUNC%s)\s*)*
+ (%s\w+) # 1: return type
+ ((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*) # 2: .. cont'
+ \s*$""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+
+ PLINE_MATCHER[4] = re.compile(
+ r"""^\s*(?:\b(?:extern|static|inline|G_INLINE_FUNC%s)\s*)*
+ (%s\w+) # 1: return type
+ (\s+\*+|\*+|\s)\s* # 2: ptr?
+ ([A-Za-z]\w*) # 3: symbols
+ \s*$""" % (ignore_decorators, RET_TYPE_MODIFIER), re.VERBOSE)
+
+ for line in input_lines:
# If this is a private header, skip it.
+ # TODO: consider scanning this first, so that we don't modify: decl_list
+ # and get_types
if re.search(r'^\s*/\*\s*<\s*private_header\s*>\s*\*/', line):
- return
+ return [], {}
# Skip to the end of the current comment.
if in_comment:
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.
+ # guard, unless it's a macro definition or the end of a deprecation
+ # section (#endif /* XXX_DEPRECATED */
if deprecated_conditional_nest == 0 and '_DEPRECATED' in line:
- m = re.search(r'^\s*#\s*(if*|define)', line)
+ m = re.search(r'^\s*#\s*(if*|define|endif)', line)
if not (m or in_declaration == 'enum'):
logging.info('Found deprecation annotation (decl: "%s"): "%s"',
in_declaration, line.strip())
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)
+ cm = [m.match(line) for m in CLINE_MATCHER]
+ pm = [m.match(previous_line) for m in PLINE_MATCHER]
# MACROS
- if m:
- symbol = m.group(1)
+ if cm[0]:
+ symbol = cm[0].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
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():]
+ elif cm[1]:
+ ret_type = format_ret_type(cm[1].group(1), cm[1].group(2), cm[1].group(3))
+ symbol = cm[1].group(4)
+ decl = line[cm[1].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():]
+ elif pm[1] and cm[2]:
+ ret_type = format_ret_type(cm[2].group(1), cm[2].group(2), cm[2].group(3))
+ symbol = cm[2].group(4)
+ decl = line[cm[2].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)
+ elif pm[1] and cm[3]:
+ ret_type = cm[3].group(1)
+ symbol = cm[3].group(2)
+ decl = line[cm[3].end():]
+ if pm[0]:
+ ret_type = format_ret_type(pm[0].group(1), pm[0].group(2), pm[0].group(3)) + 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():]
+ elif cm[4]:
+ ret_type = format_ret_type(cm[4].group(1), cm[4].group(2), cm[4].group(3))
+ symbol = cm[4].group(4)
+ decl = line[cm[4].end():]
in_declaration = 'user_function'
logging.info('function pointer variable: "%s", Returns: "%s"', symbol, ret_type)
# ENUMS
- elif m7:
+ elif cm[5]:
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)
+ symbol = cm[5].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):
+ elif cm[6]:
# We skip 'typedef enum <enum_name> _<enum_name>;' as the enum will
# be declared elsewhere.
logging.info('skipping enum typedef: "%s"', line)
- elif m8:
+
+ elif cm[7]:
symbol = ''
decl = line
in_declaration = 'enum'
# STRUCTS AND UNIONS
- elif m9:
+ elif cm[8]:
# 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)
+ # will override this (technically if will just be another entry
+ # in the output file and will be joined when reading the file).
+ structsym = cm[8].group(1).upper()
+ logging.info('%s typedef: "%s"', structsym, cm[8].group(2))
+ forward_decls[cm[8].group(2)] = '<%s>\n<NAME>%s</NAME>\n%s</%s>\n' % (
+ structsym, cm[8].group(2), deprecated, structsym)
+
+ m = SUB_MATCHER[0].match(cm[8].group(2))
+ if m:
+ objectname = m.group(1)
+ logging.info('Found object: "%s"', objectname)
+ title = '<TITLE>%s</TITLE>' % objectname
- elif re.search(r'^\s*(?:struct|union)\s+_(\w+)\s*;', line):
+ elif cm[9]:
# Skip private structs/unions.
logging.info('private struct/union')
- elif m10:
+ elif cm[10]:
# 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)
+ structsym = cm[10].group(1).upper()
+ logging.info('%s:%s', structsym, cm[10].group(2))
+ forward_decls[cm[10].group(2)] = '<%s>\n<NAME>%s</NAME>\n%s%s</%s>\n' % (
+ structsym, cm[10].group(2), line, deprecated, structsym)
- elif m11:
+ elif cm[11]:
symbol = ''
decl = line
level = 0
- in_declaration = m11.group(1)
+ in_declaration = cm[11].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 cm[12]:
+ logging.info('Found struct/union(*) typedef "%s": "%s"', cm[12].group(1), line)
+ if AddSymbolToList(slist, cm[12].group(1)):
+ decl_list.append('<TYPEDEF>\n<NAME>%s</NAME>\n%s%s</TYPEDEF>\n' %
+ (cm[12].group(1), deprecated, line))
- elif m13:
- if m13.group(2).split()[0] not in ('struct', 'union'):
+ elif cm[13]:
+ if cm[13].group(1).split()[0] not in ('struct', 'union'):
logging.info('Found typedef: "%s"', line)
- if AddSymbolToList(slist, m13.group(3)):
+ if AddSymbolToList(slist, cm[13].group(2)):
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):
+ '<TYPEDEF>\n<NAME>%s</NAME>\n%s%s</TYPEDEF>\n' % (cm[13].group(2), deprecated, line))
+ elif cm[14]:
logging.info('Skipping typedef: "%s"', line)
# VARIABLES (extern'ed variables)
- elif m14:
- symbol = m14.group(6)
+ elif cm[15]:
+ symbol = cm[15].group(1)
line = re.sub(r'^\s*([A-Za-z_]+VAR)\b', r'extern', line)
decl = line
logging.info('Possible extern var "%s": "%s"', symbol, decl)
# VARIABLES
- elif m15:
- symbol = m15.group(5)
+ elif cm[16]:
+ symbol = cm[16].group(1)
decl = line
logging.info('Possible global var" %s": "%s"', symbol, decl)
if AddSymbolToList(slist, symbol):
# G_DECLARE_*
- elif m16:
+ elif cm[17]:
in_declaration = 'g-declare'
- symbol = 'G_DECLARE_' + m16.group(1)
- decl = line[m16.end():]
+ symbol = 'G_DECLARE_' + cm[17].group(1)
+ decl = line[cm[17].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))
+ elif cm[18]:
+ # We assume that functions starting with '_' are private and skip them.
+ ret_type = format_ret_type(cm[18].group(1), None, cm[18].group(2))
+ symbol = cm[18].group(3)
+ decl = line[cm[18].end():]
+ logging.info('internal Function: "%s", Returns: "%s""%s"', symbol, cm[18].group(1), cm[18].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
+ skip_block |= is_inline_func(line)
- 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))
+ elif cm[19]:
+ ret_type = format_ret_type(cm[19].group(1), None, cm[19].group(2))
+ symbol = cm[19].group(3)
+ decl = line[cm[19].end():]
+ logging.info('Function (1): "%s", Returns: "%s""%s"', symbol, cm[19].group(1), cm[19].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
+ skip_block |= is_inline_func(line)
# 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_strip = previous_line.strip()
- 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'
+ elif cm[20]:
+ symbol = cm[20].group(1)
+ decl = line[cm[20].end():]
+
+ if is_inline_func(previous_line):
+ skip_block = 1
+ if pm[3]:
+ ret_type = format_ret_type(pm[3].group(1), None, pm[3].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'
+ if pm[2]:
+ ret_type = format_ret_type(pm[2].group(1), None, pm[2].group(2))
+ logging.info('Function (2): "%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)
+ elif cm[21]:
+ decl = line[cm[21].end():]
+ ppm = re.search(
+ r"""^\s*(?:\b(?:extern|static|inline|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, re.VERBOSE)
+
+ if pm[4]:
+ ret_type = pm[4].group(1) + ' ' + pm[4].group(2).strip()
+ symbol = pm[4].group(3)
in_declaration = 'function'
logging.info('Function (5): "%s", Returns: "%s"', symbol, ret_type)
# print "DEBUG: Skipping extern: $_"
# STRUCTS
- elif re.search(r'^\s*struct\s+_?(\w+)\s*\*', line):
+ elif cm[22]:
# Skip 'struct _<struct_name> *', since it could be a
# return type on its own line.
pass
- elif m21:
+ elif cm[23]:
# We assume that 'struct _<struct_name>' is really the
# declaration of struct <struct_name>.
- symbol = m21.group(1)
+ symbol = cm[23].group(1)
decl = line
# we will find the correct level as below we do $level += tr/{//
level = 0
logging.info('Struct(_): "%s"', symbol)
# UNIONS
- elif re.search(r'^\s*union\s+_(\w+)\s*\*', line):
+ elif cm[24]:
# Skip 'union _<union_name> *' (see above)
pass
- elif m22:
- symbol = m22.group(1)
+ elif cm[25]:
+ symbol = cm[25].group(1)
decl = line
level = 0
in_declaration = 'union'
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)
+ decl = re.sub(r'\s*\n\s*(?!$)', ' ', decl, flags=re.MULTILINE) # remove newlines
# consolidate whitespace at start/end of lines.
decl = decl.strip()
- ret_type = re.sub(r'/\*.*?\*/', '', ret_type) # remove comments in ret type.
+ ret_type = re.sub(r'/\*.*?\*/', '', ret_type).strip() # 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))
# 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)
+ "Adding get-type: [%s] [%s] [%s]", ret_type, symbol, decl)
get_types.append(symbol)
else:
internal = 0
if in_declaration == 'user_function':
if re.search(r'\).*$', decl):
decl = re.sub(r'\).*$', '', decl)
+ # TODO: same as above
+ decl = re.sub(r'/\*.*?\*/', '', decl, flags=re.MULTILINE) # remove comments.
+ decl = re.sub(r'\s*\n\s*(?!$)', ' ', decl, flags=re.MULTILINE) # remove newlines
+ # TODO: don't stip here (it works above, but fails some test
+ # consolidate whitespace at start/end of lines.
+ # decl = decl.strip()
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 = ''
- # We try to handle nested stucts/unions, but unmatched brackets in
+ # We try to handle nested structs/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)
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
+ if title:
+ slist = [title] + slist
+ return slist, doc_comments
+
+
+def is_inline_func(line):
+ line = line.strip()
+ if line.startswith('G_INLINE_FUNC'):
+ logging.info('skip block after G_INLINE_FUNC function')
+ return 1
+ if re.search(r'static\s+inline', line):
+ logging.info('skip block after static inline function')
+ return 1
+ return 0
+
+
+def format_ret_type(base_type, const, ptr):
+ ret_type = base_type
+ if const:
+ ret_type += const
+ if ptr:
+ ret_type += ' ' + ptr.strip()
+ return ret_type
+
+
+# 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
+def SeparateSubSections(slist, doc_comments):
klass = lclass = prefix = lprefix = None
standard_decl = []
liststr = '\n'.join(s for s in slist if s) + '\n'
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_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)
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)
+ return liststr
def replace_once(liststr, standard_decl, regex):
#ifdef GTK_IS_WIDGET_CLASS
#include <gtk/gtk.h>
#endif
-static GType object_types[$ntypes];
+static GType object_types[${ntypes}];
static GType *
get_object_types (void)
*/
/* 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";
+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,
FILE *fp;
gint i,j;
GType root, type;
- GType root_types[$ntypes] = { G_TYPE_INVALID, };
+ GType root_types[${ntypes}] = { G_TYPE_INVALID, };
fp = fopen (hierarchy_filename, "w");
if (fp == NULL) {
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");
+ if (desc == NULL) {
+ 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)
elif "argc" not in type_init_func and "argv" not in type_init_func:
main_func_params = "void"
+ # TODO: we should explicitly reference the vars that we substitute
+ # template_vars = {
+ # 'get_types': get_types,
+ # 'ntypes': ntypes,
+ # 'main_func_params', main_func_params,
+ # 'new_args_filename': new_args_filename,
+ # 'new_hierarchy_filename': new_hierarchy_filename,
+ # 'new_interfaces_filename': new_interfaces_filename,
+ # 'new_prerequisites_filename': new_prerequisites_filename,
+ # 'new_signals_filename': new_signals_filename,
+ # 'type_init_func': type_init_func
+ # }
+ # output.write(string.Template(MAIN_CODE).substitute(template_vars))
output.write(string.Template(MAIN_CODE).substitute(locals()))
if options.query_child_properties:
host_triplet = @host@
subdir = help
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
<holder>Dan Mueth and Chris Lyttle</holder>
</copyright>
<copyright>
- <year>2007-2015</year>
+ <year>2007-2019</year>
<holder>Stefan Sauer (Kost)</holder>
</copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision>
<revnumber>1.28</revnumber>
<title>About GTK-Doc</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
<term>Returns:</term>
<listitem>
<para>
- Specificy what value(s) the program returns. (Optional)
+ Specify what value(s) the program returns. (Optional)
</para>
</listitem>
</varlistentry>
<programlisting><![CDATA[
<example>
<title>Using a GHashTable.</title>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</example>
<informalexample>
<programlisting><![CDATA[
<informalexample>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</informalexample>
]]></programlisting>
</informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
For the latter GTK-Doc also supports an abbreviation:
-<![CDATA[
-|[
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
...
]|
-]]>
+]]></programlisting>
+ </informalexample>
</para>
<para>
host_triplet = @host@
subdir = help/manual
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
<holder>Dan Mueth and Chris Lyttle</holder>
</copyright>
<copyright>
- <year>2007-2015</year>
+ <year>2007-2019</year>
<holder>Stefan Sauer (Kost)</holder>
</copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision>
<revnumber>1.28</revnumber>
<title>GTK-Doc পরিচিতি</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>(FIXME)</para>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
<term>প্রাপ্ত মান:</term>
<listitem>
<para>
- Specificy what value(s) the program returns. (Optional)
+ Specify what value(s) the program returns. (Optional)
</para>
</listitem>
</varlistentry>
<programlisting><![CDATA[
<example>
<title>Using a GHashTable.</title>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</example>
<informalexample>
<programlisting><![CDATA[
<informalexample>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</informalexample>
]]></programlisting>
</informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
For the latter GTK-Doc also supports an abbreviation:
-<![CDATA[
-|[
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
...
]|
-]]>
+]]></programlisting>
+ </informalexample>
</para>
<para>
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc master\n"
-"POT-Creation-Date: 2018-03-24 15:17+0000\n"
-"PO-Revision-Date: 2018-04-03 13:41+0200\n"
+"POT-Creation-Date: 2018-10-03 08:17+0000\n"
+"PO-Revision-Date: 2018-10-03 14:43+0200\n"
"Last-Translator: Marek Černocký <marek@manet.cz>\n"
"Language-Team: čeština <gnome-cs-list@gnome.org>\n"
"Language: cs\n"
#. (itstool) path: revhistory/revision
#: C/index.docbook:83
msgid ""
-"<revnumber>1.2
8.1</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
+"<revnumber>1.2
9.1</revnumber> <date>28 Aug 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>development</revremark>"
msgstr ""
-"<revnumber>1.28.1</revnumber> <date>24. března 2018</date> "
+"<revnumber>1.29.1</revnumber> <date>28. srpna 2018</date> "
"<authorinitials>ss</authorinitials> <revremark>vývoj</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
msgid ""
+"<revnumber>1.29</revnumber> <date>28 Aug 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>development</revremark>"
+msgstr ""
+"<revnumber>1.29</revnumber> <date>28. srpna 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>vývoj</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+msgid ""
"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
msgstr ""
"authorinitials> <revremark>opravy chyb</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
msgid ""
"<revnumber>1.27</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>fine tuning of the python port</revremark>"
"jazyce Python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
+#: C/index.docbook:107
msgid ""
"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>port all tools from perl/bash to python</"
"jazyka Python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:107
+#: C/index.docbook:113
msgid ""
"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
"authorinitials> <revremark>opravy chyb, pročištění testů</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:113
+#: C/index.docbook:119
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>oprava chyby</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:119
+#: C/index.docbook:125
msgid ""
"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>oprava chyby</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:125
+#: C/index.docbook:131
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:131
+#: C/index.docbook:137
msgid ""
"<revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"zastaralých věcí</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:137
+#: C/index.docbook:143
msgid ""
"<revnumber>1.20</revnumber> <date>16 Feb 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, markdown support, style improvements</"
"vylepšení stylů</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:143
+#: C/index.docbook:149
msgid ""
"<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
"authorinitials> <revremark>opravy chyb</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:149
+#: C/index.docbook:155
msgid ""
"<revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, speedups, markdown support</revremark>"
"jazyka</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:155
+#: C/index.docbook:161
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:161
+#: C/index.docbook:167
msgid ""
"<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes, layout improvements</revremark>"
"authorinitials> <revremark>opravy chyb, vylepšení vzhledu</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:167
+#: C/index.docbook:173
msgid ""
"<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bug and regression fixes</revremark>"
"authorinitials> <revremark>opravy chyb a regresí</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:173
+#: C/index.docbook:179
msgid ""
"<revnumber>1.14</revnumber> <date>28 March 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes and performance improvements</revremark>"
"authorinitials> <revremark>opravy chyb a vylepšení výkonu</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:179
+#: C/index.docbook:185
msgid ""
"<revnumber>1.13</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>broken tarball update</"
"balíčku</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:185
+#: C/index.docbook:191
msgid ""
"<revnumber>1.12</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>new tool features and "
"chyb</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:191
+#: C/index.docbook:197
msgid ""
"<revnumber>1.11</revnumber> <date>16 November 2008</date> "
"<authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</"
"GNOME</revremark>"
#. (itstool) path: chapter/title
-#: C/index.docbook:204
+#: C/index.docbook:210
msgid "Introduction"
msgstr "Úvod"
#. (itstool) path: chapter/para
-#: C/index.docbook:206
+#: C/index.docbook:212
msgid ""
"This chapter introduces GTK-Doc and gives an overview of what it is and how "
"it is used."
"použít."
#. (itstool) path: sect1/title
-#: C/index.docbook:212
+#: C/index.docbook:218
msgid "What is GTK-Doc?"
msgstr "Co je to GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:214
+#: C/index.docbook:220
msgid ""
"GTK-Doc is used to document C code. It is typically used to document the "
"public API of libraries, such as the GTK+ and GNOME libraries. But it can "
"ale použít i k dokumentaci aplikačního kódu."
#. (itstool) path: sect1/title
-#: C/index.docbook:222
+#: C/index.docbook:228
msgid "How Does GTK-Doc Work?"
msgstr "Jak GTK-Doc pracuje?"
#. (itstool) path: sect1/para
-#: C/index.docbook:224
+#: C/index.docbook:230
msgid ""
"GTK-Doc works by using documentation of functions placed inside the source "
"files in specially-formatted comment blocks, or documentation added to the "
"nevytváří)."
#. (itstool) path: sect1/para
-#: C/index.docbook:231
+#: C/index.docbook:237
msgid ""
"GTK-Doc consists of a number of python scripts, each performing a different "
"step in the process."
"část procesu."
#. (itstool) path: sect1/para
-#: C/index.docbook:236
+#: C/index.docbook:242
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:243
+#: C/index.docbook:249
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)."
+"source files with the documentation for each function, macro, structs or "
+"unions, etc."
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)."
+"kódem s dokumentací pro každou funkci, makro, strukturu, výčet atd."
#. (itstool) path: listitem/para
-#: C/index.docbook:253
+#: C/index.docbook:258
msgid ""
"<guilabel>Gathering information about the code.</guilabel> "
"<application>gtkdoc-scan</application> scans the header files of the code "
"filename> do <filename><module>-overrides.txt</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:270
+#: C/index.docbook:275
msgid ""
"<application>gtkdoc-scangobj</application> can also be used to dynamically "
"query a library about any GObject subclasses it exports. It saves "
"signálech objektu GObject, které poskytují."
#. (itstool) path: listitem/para
-#: C/index.docbook:276
+#: C/index.docbook:281
msgid ""
"<application>gtkdoc-scanobj</application> should not be used anymore. It was "
"needed in the past when GObject was still GtkObject inside gtk+."
"Bylo zapotřebí v minulosti, kdy byl GObject ještě GtkObject v rámci gtk+."
#. (itstool) path: listitem/para
-#: C/index.docbook:283
+#: C/index.docbook:288
msgid ""
"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
"mkdb</application> turns the template files into XML files in the <filename "
"zdrojového kódu a introspektivních dat."
#. (itstool) path: listitem/para
-#: C/index.docbook:292
+#: C/index.docbook:297
msgid ""
"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
"nazvaný <filename><balíček>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:298
+#: C/index.docbook:303
msgid ""
"Files in <filename class=\"directory\">xml/</filename> and <filename class="
"\"directory\">html/</filename> directories are always overwritten. One "
"neměly být upravovány přímo."
#. (itstool) path: listitem/para
-#: C/index.docbook:306
+#: C/index.docbook:311
msgid ""
"<guilabel>Fixing up cross-references between documents.</guilabel> After "
"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
"dokumenty, které jsou nainstalované)."
#. (itstool) path: sect1/title
-#: C/index.docbook:324
+#: C/index.docbook:329
msgid "Getting GTK-Doc"
msgstr "Jak získat GTK-Doc?"
#. (itstool) path: sect2/title
-#: C/index.docbook:327
+#: C/index.docbook:332
msgid "Requirements"
msgstr "Požadavky"
#. (itstool) path: sect2/para
-#: C/index.docbook:328
+#: C/index.docbook:333
msgid ""
"<guilabel>python 2/3</guilabel> - the main scripts are written in python."
msgstr "<guilabel>Python 2/3</guilabel> – hlavní skripty jsou v jazyce Python."
#. (itstool) path: sect2/para
-#: C/index.docbook:331
+#: C/index.docbook:336
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:335
+#: C/index.docbook:340
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:339
+#: C/index.docbook:344
msgid ""
"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
"syntaxe u příkladů"
#. (itstool) path: sect1/title
-#: C/index.docbook:347
+#: C/index.docbook:352
msgid "About GTK-Doc"
msgstr "O aplikaci GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:349 C/index.docbook:363
+#: C/index.docbook:354
+msgid ""
+"Historically GTK-Doc was used to generate template files from the sources "
+"code. These template files could be used by developers to enter the API "
+"documentation. This approach was rather inconvenient because it required to "
+"keep the generated files under version control. Since GTK-Doc 1.9 it became "
+"possible to place all API information into source comments, which made the "
+"template support obsolete. In version 1.26 template support has been removed."
+msgstr ""
+"Historicky se GTK-Doc používalo ke generování šablonových souborů ze "
+"zdrojových kódů. Tyto šablonové soubory pak mohli vývojáři používat ke "
+"vkládání dokumentace k API. Tento postup byl dosti nepohodlný, protože "
+"vyžadovat udržování vygenerovaných souborů ve správě verzí. Proto od verze "
+"1.9 přichází GTK-Doc s možností vkládat všechny informace o API do komentářů "
+"ve zdrojových kódech, čímž se podpora šablon stává nadbytečnou. Ve verzi "
+"1.26 byla podpora šablon odstraněna."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:364 C/index.docbook:378
msgid "(FIXME)"
msgstr "(DOPLNIT)"
#. (itstool) path: sect1/para
-#: C/index.docbook:353
+#: C/index.docbook:368
msgid ""
-"(History, authors, web pages, mailing list, license, future plans, "
-"comparison with other similar systems.)"
+"(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.)"
+"(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:361
+#: C/index.docbook:376
msgid "About this Manual"
msgstr "O této příručce"
#. (itstool) path: sect1/para
-#: C/index.docbook:367
+#: C/index.docbook:382
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:376
-msgid "Setting up your project"
-msgstr "Nastavení vašeho projektu"
+#: C/index.docbook:391
+msgid "Project Setup"
+msgstr "Nastavení projektu"
#. (itstool) path: chapter/para
-#: C/index.docbook:378
-msgid ""
-"The next sections describe what steps to perform to integrate GTK-Doc into "
-"your project. Theses sections assume we work on a project called 'meep'. "
-"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í."
+#: C/index.docbook:393
+msgid ""
+"This Chapter describes the steps that are necessary to integrate GTK-Doc "
+"into your project. The integration of GTK-Doc into a project includes the "
+"following steps:"
+msgstr ""
+"Tato kapitola popisuje kroky, které jsou nutné pro integraci GTK-Doc do "
+"vašeho projektu. Integrace GTK-Doc do projektu zahrnuje následující kroky:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:401
+msgid ""
+"Preparation of the directory structure and creating required configuration "
+"files for your GTK-Doc documentation (see <link linkend=\"settingup_docfiles"
+"\"> Setting up a skeleton documentation</link>)."
+msgstr ""
+"Přípravu struktury složek a vytvoření požadovaných konfiguračních souborů "
+"pro dokumentaci GTK-Doc (viz <link linkend=\"settingup_docfiles\">Nastavení "
+"kostry dokumentace</link>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:409
+msgid ""
+"Adjusting the build system to build your documentation using the GTK-Doc "
+"tools. Multiple build systems are supported, in this manual we describe how "
+"to integrate GTK-Doc with <link linkend=\"settingup_autotools\">Autotools</"
+"link>, <link linkend=\"settingup_cmake\">CMake</link>, and <link linkend="
+"\"settingup_plain_makefiles\">plain Makefiles</link>."
+msgstr ""
+"Přizpůsobení sestavovacího systému, aby sestavoval vaši dokumentaci pomocí "
+"nástrojů GTK-Doc. Je podporováno více sestavovacích systémů, v této příručce "
+"je popsáno, jak integrovat GTK-Doc s <link linkend=\"settingup_autotools"
+"\">Autotools</link>, <link linkend=\"settingup_cmake\">CMake</link> a <link "
+"linkend=\"settingup_plain_makefiles\">prostými soubory Makefiles</link>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:419
+msgid ""
+"Adding GTK-Doc specific files to version control and deciding which files to "
+"ignore (see <link linkend=\"settingup_vcs\"> Integration with version "
+"control systems</link>)."
+msgstr ""
+"Přidání souborů specifických pro GTK-Doc do správy verzí a rozhodnutí, které "
+"soubory se mají ignorovat (viz <link linkend=\"settingup_vcs\">Integrace se "
+"systémem správy verzí</link>)."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:427
+msgid ""
+"The following sections assume we work on a project called <code>meep</code>. "
+"This project contains two packages (or modules), a library called "
+"<code>libmeep</code> and an end-user app called <code>meeper</code>."
+msgstr ""
+"Následující oddíly předpokládají, že pracujeme na projektu nazvaném "
+"<code>meep</code>. Tento projekt obsahuje dva balíčky (nebo moduly), "
+"knihovnu nazvanou <code>libmeep</code> a uživatelskou aplikaci nazvanou "
+"<code>meeper</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:389
+#: C/index.docbook:436
msgid "Setting up a skeleton documentation"
msgstr "Nastavení kostry dokumentace"
#. (itstool) path: sect1/para
-#: C/index.docbook:391
-msgid ""
-"Under your top-level project directory create folders called docs/reference "
-"(this way you can also have docs/help for end-user documentation). It is "
-"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ý."
+#: C/index.docbook:438
+msgid ""
+"A common convention is to place documentation into a folder called "
+"<code>docs</code> inside your top-level project directory. We usually "
+"distinguish between <emphasis>reference documentation</emphasis> intended "
+"for developers and an <emphasis>user manual</emphasis> intended for end-"
+"users. Again the convention is to have separate folders for both. We usually "
+"place the reference documentation in a folder named <code>reference</code> "
+"and the end-user manual in a folder named <code>help</code> as. According to "
+"the above convention the documentation for our <code>libmeep</code> package "
+"would be placed into: <code>docs/reference/libmeep</code>. For packages with "
+"just one library or application the documentation could also be placed "
+"directly into <code>docs/reference</code>. It is not mandatory to use the "
+"above convention, but if you choose to use a different directory structure "
+"you must adjust your build system configuration to match your directory "
+"structure."
+msgstr ""
+"Zaběhnutým zvykem je umístit dokumentaci do složky nazvané <code>docs</code> "
+"ve složce nejvyšší úrovně projektu. Obvykle rozlišujeme mezi "
+"<emphasis>referenční dokumentací</emphasis> zaměřenou na vývojáře a "
+"<emphasis>uživatelskou příručkou</emphasis> zaměřenou na koncového "
+"uživatele. Opět je zvykem mít zvláštní složku pro každou z obou zmíněných. "
+"Obvykle umisťujeme referenční dokumentaci do složky nazvané <code>reference</"
+"code> a uživatelskou příručku do složky nazvané <code>help</code>. V souladu "
+"se zmíněnými zvyky by dokumentace pro naši knihovnu <code>libmeep</code> "
+"byla umístěna do <code>docs/reference/libmeep</code>. U balíčků s jedinou "
+"knihovnou nebo referenční dokumentací by bylo možné ji umístit přímo do "
+"<code>docs/reference</code>. Není povinné použít uvedenou konvenci, ale "
+"pokud se rozhodnete použít jinou strukturu složek, musíte upravit "
+"konfiguraci sestavovacího systému, aby se s ní shodoval."
#. (itstool) path: example/title
-#: C/index.docbook:400
-msgid "Example directory structure"
-msgstr "Příklad struktury složek"
+#: C/index.docbook:469
+msgid "Example directory structure of <emphasis>meep</emphasis> project"
+msgstr "Příklad struktury složek projektu <emphasis>meep</emphasis>"
#. (itstool) path: example/programlisting
-#: C/index.docbook:401
+#: C/index.docbook:471
#, no-wrap
msgid ""
"\n"
"meep/\n"
" docs/\n"
-" reference/\n"
+" reference/ # reference documentation\n"
" libmeep/\n"
" meeper/\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
"\n"
"meep/\n"
" docs/\n"
-" reference/\n"
+" reference/ # referenční dokumentace\n"
" libmeep/\n"
" meeper/\n"
+" help/ # volitelné: uživatelská příručka\n"
+" meeper/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:398
-msgid "This can then look as shown below: <_:example-1/>"
-msgstr "Ve výsledku to může vypadat nějak takto: <_:example-1/>"
+#: C/index.docbook:463
+msgid ""
+"In the following sections we will assume a directory structure for our "
+"<emphasis>meep</emphasis> project that uses the above conventions. <_:"
+"example-1/>"
+msgstr ""
+"V následujících oddílech budeme uvažovat strukturu složek pro náš projekt "
+"<emphasis>meep</emphasis>, který používá výše uvedené konvence. <_:example-1/"
+">"
#. (itstool) path: sect1/title
+#: C/index.docbook:488
+msgid "Integration with Autotools"
+msgstr "Integrace s Autotools"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:489
+msgid ""
+"Integration of GTK-Doc into an autotools-based build system requires the "
+"following steps:"
+msgstr ""
+"Integrace GTK-Doc do sestavovacího systému založeného na Autotools vyžaduje "
+"následující kroky:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:495
+msgid ""
+"Ensure that <application>gtkdocize</application> is run once before the "
+"<filename>configure</filename> script. If an <filename>autogen.sh</filename> "
+"script is present, adjust it to check for GTK-Doc and add a call to "
+"<application>gtkdocize</application>."
+msgstr ""
+"Zajistit, že <application>gtkdocize</application> se spustí právě jednou "
+"před skriptem <filename>configure</filename>. Pokud je přítomen skript "
+"<filename>autogen.sh</filename>, upravte jej, aby kontroloval GTK-Doc a "
+"přidejte volání <application>gtkdocize</application>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:503
+msgid ""
+"The main purpose of <application>gtkdocize</application> is to make the "
+"<filename>gtk-doc.make</filename> Makefile and the <filename>gtk-doc.m4</"
+"filename> macro definition file available to the build system, either by "
+"copying or linking it into the project."
+msgstr ""
+"Hlavním účelem <application>gtkdocize</application> je vytvořit Makefile "
+"<filename>gtk-doc.make</filename> a definici makra <filename>gtk-doc.m4</"
+"filename> dostupnou sestavovacímu systému, buď zkopírováním do projektu nebo "
+"vytvořením odkazu."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:512
+msgid ""
+"Add the necessary <application>autoconf</application> macros to "
+"<filename>configure.ac</filename> to enable GTK-Doc in your build system to "
+"allow configuration of GTK-Doc via the generated <filename>configure</"
+"filename> script."
+msgstr ""
+"Přidat potřebná makra <application>autoconf</application> do "
+"<filename>configure.ac</filename>, abyste povolili GTK-Doc v sestavovacím "
+"systému a konfigurace GTK-Doc mohla jít přes generovaný skript "
+"<filename>configure</filename>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:518
+msgid ""
+"Among others with registers the <code>--enable-gtk-doc</code> option with "
+"the <filename>configure</filename> script."
+msgstr ""
+"Mimo jiné pomocí registrace přepínače <code>--enable-gtk-doc</code> ve "
+"skriptu <filename>configure</filename>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:524
+msgid ""
+"Create an <application>automake</application> script for each application or "
+"library in your project. In the example used in this documentation this step "
+"applies to both <code>meeper</code> and <code>libmeep</code>."
+msgstr ""
+"Vytvořit skript <application>automake</application> pro jednotlivé aplikace "
+"a knihovny ve svém projektu. V příkladu použitém v této dokumentaci je tento "
+"krok použit jak pro <code>meeper</code>, tak pro <code>libmeep</code>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:533
+msgid ""
+"In the following sections, we will perform the above steps in reverse order. "
+"We start with the <application>automake</application> scripts and work our "
+"way up to <filename>configure.ac</filename> and <filename>autogen.sh</"
+"filename>. Then we show how enable Gtk-Doc in the build system and how to "
+"build the documentation."
+msgstr ""
+"V následujícím oddíle provedeme výše zmíněné kroky v opačném pořadí. Začneme "
+"se skripty <application>automake</application> a budeme postupovat až k "
+"<filename>configure.ac</filename> a <filename>autogen.sh</filename>. Pak si "
+"ukážeme, jak povolit GTK-Doc v sestavovacím systému a jak sestavit "
+"dokumentaci."
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:543
+msgid "Integration with automake"
+msgstr "Integrace s automake"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:545
+msgid ""
+"First copy the <filename>Makefile.am</filename> from the <filename class="
+"\"directory\">examples</filename> sub-directory of the <ulink url=\"https://"
+"gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am\"> gtkdoc-"
+"sources</ulink> to your project's reference documentation directory (e.g. "
+"<filename class=\"directory\">docs/reference/<package></filename>). A "
+"local copy should be available under e.g. <filename>/usr/share/doc/gtk-doc-"
+"tools/examples/Makefile.am</filename>. If you have multiple packages repeat "
+"this for each one."
+msgstr ""
+"Jako první nakopírujte <filename>Makefile.am</filename> z podsložky "
+"<filename class=\"directory\">examples</filename> ve složce <ulink url="
+"\"https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am"
+"\">gtkdoc-sources</ulink> do složky s referenční dokumentací svého projektu "
+"(např. <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: note/simpara
+#: C/index.docbook:558
+msgid ""
+"Do not forget to add each <filename>Makefile.am</filename> to the "
+"<function>AC_CONFIG_FILES</function> macro in <filename>configure.ac</"
+"filename>. For <filename>docs/reference/libmeep/Makefile.am</filename> you "
+"will need to add the entry <filename>docs/reference/libmeep/Makefile</"
+"filename> to <function>AC_CONFIG_FILES</function>."
+msgstr ""
+"Nezapomeňte přidat jednotlivé <filename>Makefile.am</filename> do makra "
+"<function>AC_CONFIG_FILES</function> v <filename>configure.ac</filename>. "
+"Pro <filename>docs/reference/libmeep/Makefile.am</filename> budete "
+"potřebovat přidat záznam <filename>docs/reference/libmeep/Makefile</"
+"filename> do <function>AC_CONFIG_FILES</function>."
+
#. (itstool) path: example/title
-#: C/index.docbook:416 C/index.docbook:423
+#: C/index.docbook:570
+msgid "Example directory structure with <filename>Makefiles.am</filename>"
+msgstr "Příklad struktury složek s <filename>Makefiles.am</filename>"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:573
+#, no-wrap
+msgid ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/ # reference documentation\n"
+" libmeep/\n"
+" Makefile.am\n"
+" meeper/\n"
+" Makefile.am\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+msgstr ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/ # referenční dokumentace\n"
+" libmeep/\n"
+" Makefile.am\n"
+" meeper/\n"
+" Makefile.am\n"
+" help/ # volitelné: uživatelská příručka\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:589
+msgid ""
+"Next, you need to customize the copied Makefiles and provide values for the "
+"various parameters in each <filename>Makefile.am</filename>. All settings "
+"have a comment above them that describes their purpose and how to customize "
+"the setting. Most settings are used to supply extra flags to the respective "
+"tools to which they apply. Every tool has a variable of the form <option><"
+"TOOLNAME>_OPTIONS</option> (e.g. the tool <application>gtkdoc-mkhtml</"
+"application> has an option named <code>MKHTML_OPTIONS</code>). All the tools "
+"support <option>--help</option> to list the supported options."
+msgstr ""
+"Dále je třeba přizpůsobit zkopírované soubory Makefile a dodat hodnoty pro "
+"různé parametry v jednotlivých <filename>Makefile.am</filename>. Všechna "
+"nastavení mají komentáře s popisem svého účelu a jak nastavení přizpůsobit. "
+"Většina nastavení má doplňující příznaky předávané do dotyčných nástrojů, "
+"které je umí použít. Každý nástroj má proměnnou ve formátu <option><"
+"NÁZEVNÁSTROJE>_OPTIONS</option> (např. nástroj <application>gtkdoc-"
+"mkhtml</application> má volbu nazvanou <code>MKHTML_OPTIONS</code>). Všechny "
+"nástroje podporují <option>--help</option> pro vypsání podporovaných "
+"přepínačů."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:613
+msgid ""
+"<option>DOC_MODULE</option> is used to provide the name of the package that "
+"is being documentated (e.g. <code>meeper</code>, or <code>libmeep</code>)."
+msgstr ""
+"<option>DOC_MODULE</option> se používá k poskytnutí názvu balíčku, který je "
+"dokumentován (např. <code>meeper</code> nebo <code>libmeep</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:620
+msgid ""
+"<option>DOC_SOURCE_DIR</option> is used to specify the location of source "
+"directory which GTK-Doc searches for your API documentation. This will "
+"usually be <code> DOC_SOURCE_DIR=$(top_srcdir)/src </code> or a sub-"
+"directory of that directory."
+msgstr ""
+"<option>DOC_SOURCE_DIR</option> se používá k určení umístění zdrojové "
+"složky, ve které GTK-Doc hledá dokumentaci API. Obvykle to je "
+"<code>DOC_SOURCE_DIR=$(top_srcdir)/src </code> nebo podsložka této složky."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:633
+msgid ""
+"<option>HFILE_GLOB</option> and <option>CFILE_GLOB</option> are used for "
+"dependencies. Each option take a file-glob (e.g. <code>HFILE_GLOB="
+"$(top_srcdir)/src/*.c</code>). The documentation will be rebuilt if any of "
+"the matched files change."
+msgstr ""
+"<option>HFILE_GLOB</option> a <option>CFILE_GLOB</option> se používají pro "
+"závislosti. Obě volby přebírají file-glob (např. <code>HFILE_GLOB="
+"$(top_srcdir)/src/*.c</code>). Dokumentace se znovu sestaví, když se "
+"kterýkoliv z odpovídajících souborů změní."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:645
+msgid ""
+"<option>EXTRA_HFILES</option> allows to specify extra header files to "
+"include when scanning for API documentation, which are not found under "
+"<code>DOC_SOURCE_DIR</code> (e.g. <code> EXTRA_HFILES=$(top_srcdir}/contrib/"
+"extra.h</code>)."
+msgstr ""
+"<option>EXTRA_HFILES</option> umožňuje určit dodatečné hlavičkové soubory, "
+"které se mají zahrnout při procházení pro dokumentaci k API, a které nejsou "
+"k nalezení pod složkou <code>DOC_SOURCE_DIR</code> (např. <code>EXTRA_HFILES="
+"$(top_srcdir}/contrib/extra.h</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:655
+msgid ""
+"<option>IGNORE_HFILES</option> allows to specify header files or directories "
+"to ignore when scanning for API documentation. Use the basename of the file "
+"or directory (e.g. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h "
+"private_code_folder</code>)."
+msgstr ""
+"<option>IGNORE_HFILES</option> umožňuje určit dodatečné hlavičkové soubory "
+"nebo složky, které se mají ignorovat při procházení pro dokumentaci k API. "
+"Použijte základní název ze souboru nebo složky (např. "
+"<code>IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:665
+msgid ""
+"<option>HTML_IMAGES</option> allows to specify images files which will be "
+"copied into the <filename>html/</filename> directory of the generated "
+"documentation. If your API documentation includes any images they need to be "
+"added to this option (e.g. <code> HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/"
+"stock_about_24.png</code>)."
+msgstr ""
+"<option>HTML_IMAGES</option> umožňuje určit soubory s obrázky, které se "
+"zkopírují do složky <option>html/</option> s generovanou dokumentací. Pokud "
+"jsou součástí vaší dokumentace API nějaké obrázky, je třeba je přidat do "
+"této volby (např. <code>HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/"
+"stock_about_24.png</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:678
+msgid ""
+"<option>content_files</option> allows to specify extra files that are "
+"included by <code>$(DOC_MAIN_SGML_FILE)</code> (e.g. <code> "
+"content_files=running.xml building.xml changes-2.0.xml</code>)."
+msgstr ""
+"<option>content_files</option> umožňuje určit dodatečné soubory, které se "
+"mají vložit pomocí <code>$(DOC_MAIN_SGML_FILE)</code> (např. "
+"<code>content_files=running.xml building.xml changes-2.0.xml</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:689
+msgid ""
+"<option>expand_content_files</option> allows to specify files where "
+"<emphasis>gtk-doc abbreviations</emphasis> such as <code>#GtkWidget</code> "
+"are expanded (e.g. <code> expand_content_files=running.xml</code>)."
+msgstr ""
+"<option>expand_content_files</option> umožňuje určit soubory, ve kterých "
+"jsou rozvinuty <emphasis>zkratky gtk-doc</emphasis>, jako je třeba "
+"<code>#GtkWidget</code> (např. <code>expand_content_files=running.xml</"
+"code>)."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:607
+msgid ""
+"The following list explains the most relevant options. Check the example "
+"<filename>Makefile.am</filename> for additional options. <_:itemizedlist-1/>"
+msgstr ""
+"Následující seznam vysvětluje nejpodstatnější volby. Na další volby se "
+"podívejte do ukázkového <filename>Makefile.am</filename>. <_:itemizedlist-1/>"
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:704
msgid "Integration with autoconf"
msgstr "Integrace s autoconf"
-#. (itstool) path: sect1/para
-#: C/index.docbook:418
+#. (itstool) path: sect2/para
+#: C/index.docbook:706
+msgid ""
+"Integration with <application>autoconf</application> is very simple and "
+"includes one required step and an additional optional (but recommended) "
+"step. The first step is to add the <function>GTK_DOC_CHECK</function> macro "
+"to your <filename>configure.ac</filename> script. This registers several "
+"configure options to enable GTK-Doc and allows you to set default arguments "
+"for <application>gtkdocize</application>."
+msgstr ""
+"Integrace s <application>autoconf</application> je velmi jednoduchá a skládá "
+"se z jednoho povinného kroku a dalšího volitelného (ale doporučeného) kroku. "
+"Prvním krokem je přidat makro <function>GTK_DOC_CHECK</function> do skriptu "
+"<filename>configure.ac</filename>. Tím se zaregistruje několik "
+"konfiguračních voleb, které povolí GTK-Doc a umožní vám nastavit výchozí "
+"argumenty pro <application>gtkdocize</application>."
+
+#. (itstool) path: warning/simpara
+#: C/index.docbook:718
msgid ""
-"Very easy! Just add one line to your <filename>configure.ac</filename> "
-"script."
+"Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented. The "
+"macro must start at the beginning of the line and should not start with "
+"whitespace."
msgstr ""
-"Velmi snadné! Stačí jen přidat jeden řádek do vašeho skriptu "
-"<filename>configure.ac</filename>."
+"Ujistěte se, že makro <code>GTK_DOC_CHECK</code> není odsazené od kraje. "
+"Makro musí začínat na začátku řádku a nesmí začínat bílými znaky."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:725
+msgid ""
+"The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code> to your "
+"<filename>configure.ac</filename>. This is not required but helps "
+"<application>gtkdocize</application> to automatically copy the macro "
+"definition (e.g <filename>gtk-doc.m4</filename>) which contains the "
+"<function>GTK_DOC_CHECK</function> macro to your project's macro directory. "
+"Without this, the GTK_DOC_CHECK macro might not be found and you would need "
+"to explicitly tell the <application>aclocal</application> tool where to find "
+"the macro definition file."
+msgstr ""
+"Druhým krokem je přidat do <filename>configure.ac</filename> makro "
+"<code>AC_CONFIG_MACRO_DIR(m4)</code>. Není to sice nutné, ale pomůže to "
+"<application>gtkdocize</application> automaticky zkopírovat definici makra "
+"(např. <filename>gtk-doc.m4</filename>), která obsahuje makro "
+"<function>GTK_DOC_CHECK</function>, do složky s makry ve vašem projektu. Bez "
+"toho se může stát, že makro <function>GTK_DOC_CHECK</function> nemusí být "
+"nalezeno a budete muset nástroji <application>aclocal</application> výslovně "
+"uvést, kde soubor s definicí makra najít."
+
+#. (itstool) path: example/title
+#: C/index.docbook:738
+msgid "Minimal integration with autoconf"
+msgstr "Minimální integrace s autoconf"
#. (itstool) path: example/programlisting
-#: C/index.docbook:424
+#: C/index.docbook:739
#, no-wrap
msgid ""
"\n"
-"# check for gtk-doc\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
msgstr ""
"\n"
-"# check for gtk-doc\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# doporučeno: nastaví složku m4\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# volitelné: zaregistruje gtk-doc v configure\n"
+"GTK_DOC_CHECK([1.28])\n"
#. (itstool) path: example/title
-#: C/index.docbook:436
-msgid "Keep gtk-doc optional"
-msgstr "Ponechání gtk-doc jako volitelného"
+#: C/index.docbook:754
+msgid "Integration with optional gtk-doc dependency"
+msgstr "Integrace s volitelnými závislostttmi gtk-doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:437
+#: C/index.docbook:755
#, no-wrap
msgid ""
"\n"
-"# check for gtk-doc\n"
"m4_ifdef([GTK_DOC_CHECK], [\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\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"
+"# doporučeno: nastaví složku m4\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# volitelné: zaregistruje gtk-doc v configure\n"
+"GTK_DOC_CHECK([1.28])\n"
"],[\n"
"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n"
"])\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:431
+#. (itstool) path: sect2/para
+#: C/index.docbook:748
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/>"
+"The above example works, but will require all developers to have gtk-doc "
+"installed. A better way is to make building the documentation optional as "
+"shown in the next example: <_:example-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/>"
+"Výše uvedený příklad funguje, ale vyžaduje, aby všichni vývojáři měli "
+"nainstalováno gtk-doc. Lepším způsobem je zařídit, aby sestavení dokumentace "
+"bylo volitelné, jak je ukázáno v následujícím příkladu: <_:example-1/>"
-#. (itstool) path: sect1/para
-#: C/index.docbook:448
+#. (itstool) path: sect2/para
+#: C/index.docbook:768
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:"
+"The first argument is used to check for the Gtk-Doc version at configure "
+"time. The 2nd, optional argument is used by <application>gtkdocize</"
+"application>. The <symbol>GTK_DOC_CHECK</symbol> macro also adds several "
+"configure switches:"
msgstr ""
-"První argument se používá ke kontrole gtkdocversion v průběhu konfigurace. "
+"První argument se používá ke kontrole verze GTK-Doc 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:454
+#: C/index.docbook:777
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:455
+#: C/index.docbook:778
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:456
+#: C/index.docbook:779
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:457
+#: C/index.docbook:780
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:461
+#: C/index.docbook:784
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"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:469
-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 ""
-"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:477
-msgid "Preparation for gtkdocize"
-msgstr "Příprava pro gtkdocize"
-
-#. (itstool) path: example/programlisting
-#: C/index.docbook:478
-#, 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:483
+#. (itstool) path: sect2/para
+#: C/index.docbook:792
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>."
+"<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>."
+"<code>autogen.sh</code>."
-#. (itstool) path: sect1/title
-#: C/index.docbook:491
-msgid "Integration with automake"
-msgstr "Integrace s automake"
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:493
-msgid ""
-"First copy the <filename>Makefile.am</filename> from the <filename class="
-"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
-"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:504
-msgid ""
-"The next step is to edit the settings inside the <filename>Makefile.am</"
-"filename>. All the settings have a comment above that describes their "
-"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:518
+#. (itstool) path: sect2/title
+#: C/index.docbook:800
msgid "Integration with autogen"
msgstr "Integrace s autogen"
-#. (itstool) path: sect1/para
-#: C/index.docbook:520
+#. (itstool) path: sect2/para
+#: C/index.docbook:802
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."
+"the build infrastructure after the project was checked out from a version "
+"control system (such as git or svn). GTK-Doc comes with a script called "
+"<application>gtkdocize</application> which can be used to copy the necessary "
+"files needed by Gtk-Doc to the source directory."
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."
+"projektu ze systému pro správu verzí (jako je Git nebo SVN), nastaví "
+"infrastrukturu pro sestavení. GTK-Doc se dodává se skriptem nazvaným "
+"<application>gtkdocize</application>, který lze použít ke zkopírování "
+"nezbytných souborů požadovaných GTK-Doc do zdrojové složky."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:810
+msgid "It should be run before autoreconf, autoheader, automake or autoconf."
+msgstr "Měl by být spuštěn před autoheader, automake nebo autoconf."
#. (itstool) path: example/title
-#: C/index.docbook:529
+#: C/index.docbook:815
msgid "Running gtkdocize from autogen.sh"
msgstr "Spuštění gtkdocize z autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:530
+#: C/index.docbook:816
#, no-wrap
msgid ""
"\n"
"\n"
"gtkdocize || exit 1\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:536
+#. (itstool) path: example/title
+#: C/index.docbook:824
+msgid "Conditionally run gtkdocize from autogen.sh"
+msgstr "Podmíněné spuštění gtkdocize z autogen.sh"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:825
+#, no-wrap
+msgid ""
+"\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+" echo \"No gtk-doc support found. You can't build the docs.\"\n"
+"else\n"
+" $GTKDOCIZE || exit 1\n"
+"fi\n"
+msgstr ""
+"\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+" echo \"No gtk-doc support found. You can't build the docs.\"\n"
+"else\n"
+" $GTKDOCIZE || exit 1\n"
+"fi\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:836
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>."
+"<option>--docdir</option> option)."
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>."
+"option>) soubor <filename>gtk-doc.make</filename>."
-#. (itstool) path: sect1/para
-#: C/index.docbook:545
+#. (itstool) path: sect2/para
+#: C/index.docbook:842
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í)."
+"<application>gtkdocize</application> checks your <filename>configure.ac</"
+"filename> script for the <function>GTK_DOC_CHECK</function> macro. The "
+"<function>GTK_DOC_CHECK</function> macro can be used to pass extra arguments "
+"to the <application>gtkdocize</application> script. the 2nd parameter in the "
+"<function>GTK_DOC_CHECK</function> macro."
+msgstr ""
+"<filename>gtkdocize</filename> kontroluje váš skript <filename>configure.ac</"
+"filename> ohledně makra <function>GTK_DOC_CHECK</function>. Toto makro "
+"můžete použít k předání dalších parametrů do skriptu <application>gtkdocize</"
+"application>. Konkrétně k tomu slouží druhý argument makra."
-#. (itstool) path: sect1/title
-#. (itstool) path: example/title
-#: C/index.docbook:562 C/index.docbook:579
-msgid "Running the doc build"
-msgstr "Sestavení dokumentace"
+#. (itstool) path: sect2/para
+#: C/index.docbook:851
+msgid ""
+"Alternatively, additional arguments can also be passed to "
+"<application>gtkdocize</application> via the <function>GTKDOCIZE_FLAGS</"
+"function> environment variable, or by directly specifying them to "
+"<application>gtkdocize</application> in <filename>autogen.sh</filename>."
+msgstr ""
+"Alternativně lze další argumenty skriptu <application>gtkdocize</"
+"application> předat přes proměnnou prostředí <function>GTKDOCIZE_FLAGS</"
+"function> nebo je zadat přímo za volání <application>gtkdocize</application> "
+"v <filename>autogen.sh</filename>."
-#. (itstool) path: sect1/para
-#: C/index.docbook:564
+#. (itstool) path: sect2/title
+#: C/index.docbook:862
+msgid "Executing GTK-Doc from the Build System"
+msgstr "Spouštění GTK-Doc ze sestavovacího systému"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:864
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 "
"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:571
+#. (itstool) path: sect2/para
+#: C/index.docbook:871
msgid ""
"The first make run generates several additional files in the doc-"
"directories. The important ones are: <filename><package>.types</"
"<filename><package>-docs.xml</filename> (dříve .sgml) a <filename><"
"package>-sections.txt</filename>."
+#. (itstool) path: example/title
+#: C/index.docbook:879
+msgid "Running the doc build"
+msgstr "Sestavení dokumentace"
+
#. (itstool) path: example/programlisting
-#: C/index.docbook:580
+#: C/index.docbook:880
#, no-wrap
msgid ""
"\n"
"./autogen.sh --enable-gtk-doc\n"
"make\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:586
+#. (itstool) path: sect2/para
+#: C/index.docbook:887
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."
+"index.html</filename>. With this initial setup you will only see a very "
+"simple document. The next chapter will teach you how to add API "
+"documentation to your code via special comment blocks. The Chapter "
+"afterwards introduces <link linkend=\"metafiles\">additional files</link> "
+"and shows how to edit the <link linkend=\"metafiles_master\">master "
+"template</link> to add additional chapters and sections to your "
+"documentation files."
+msgstr ""
+"Nyní si můžete ve svém webovém prohlížeči zobrazit <filename>docs/reference/"
+"<package>/index.html</filename>. S tímto počátečním nastavením uvidíte "
+"jen velmi jednoduchý dokument. Následující kapitola vás naučí, jak do svého "
+"zdrojového kódu přidat dokumentaci k API pomocí speciálních komentářových "
+"bloků. Dále pak kapitola seznamuje s <link linkend=\"metafiles\">dodatečnými "
+"soubory</link> a ukazuje, jak upravit <link linkend=\"metafiles_master"
+"\">hlavní šablonu</link>, abyste do svých souborů s dokumentací dostali "
+"doplňující kapitoly a oddíly."
#. (itstool) path: sect1/title
-#: C/index.docbook:594
-msgid "Integration with version control systems"
-msgstr "Integrace se systémem pro správu verzí"
+#: C/index.docbook:903
+msgid "Integration with CMake build systems"
+msgstr "Integrace se sestavovacím systémem CMake"
#. (itstool) path: sect1/para
-#: C/index.docbook:596
+#: C/index.docbook:905
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>."
+"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 ""
-"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>."
+"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: sect1/para
-#: C/index.docbook:604
+#. (itstool) path: example/title
+#: C/index.docbook:915
+msgid "Example of using GTK-Doc from CMake"
+msgstr "Příklad použití GTK-Doc z CMake"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:916
+#, no-wrap
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."
+"\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 ""
-"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>."
+"\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:913
+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: sect1/title
-#: C/index.docbook:612
+#: C/index.docbook:940
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:614
+#: C/index.docbook:942
msgid ""
"In the case one does not want to use automake and therefore <filename>gtk-"
"doc.mak</filename> one will need to call the gtkdoc tools in the right order "
"souborech make (nebo jiných nástrojích)."
#. (itstool) path: example/title
-#: C/index.docbook:621
+#: C/index.docbook:949
msgid "Documentation build steps"
msgstr "Kroky sestavení dokumentace"
#. (itstool) path: example/programlisting
-#: C/index.docbook:622
+#: C/index.docbook:950
#, no-wrap
msgid ""
"\n"
"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:636
+#: C/index.docbook:964
msgid ""
"One will need to look at the <filename>Makefile.am</filename> and "
"<filename>gtk-doc.mak</filename> to pick the extra options needed."
"am</filename> a <filename>gtk-doc.mak</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:643
-msgid "Integration with CMake build systems"
-msgstr "Integrace se sestavovacím systémem CMake"
+#: C/index.docbook:971
+msgid "Integration with version control systems"
+msgstr "Integrace se systémem pro správu verzí"
#. (itstool) path: sect1/para
-#: C/index.docbook:645
+#: C/index.docbook:973
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."
+"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 ""
-"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:655
-msgid "Example of using GTK-Doc from CMake"
-msgstr "Příklad použití GTK-Doc z CMake"
+"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: example/programlisting
-#: C/index.docbook:656
-#, no-wrap
+#. (itstool) path: sect1/para
+#: C/index.docbook:981
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"
+"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 ""
-"\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:653
-msgid "The following example shows how to use this command. <_:example-1/>"
-msgstr "Následující příklad ukazuje, jak tento příkaz použít: <_:example-1/>"
+"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: chapter/title
-#: C/index.docbook:681
+#: C/index.docbook:991
msgid "Documenting the code"
msgstr "Dokumentování v kódu"
#. (itstool) path: chapter/para
-#: C/index.docbook:683
+#: C/index.docbook:993
msgid ""
"GTK-Doc uses source code comment with a special syntax for code "
"documentation. Further it retrieves information about your project structure "
"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:691
-msgid "Documentation placement"
-msgstr "Umístění dokumentace"
-
-#. (itstool) path: note/para
-#: C/index.docbook:692
-msgid ""
-"In the past most documentation had to be filled into files residing inside "
-"the <filename>tmpl</filename> directory. This has the disadvantages that the "
-"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:698
-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:709 C/index.docbook:735
+#: C/index.docbook:1004 C/index.docbook:1030
msgid "GTK-Doc comment block"
msgstr "Komentářový blok GTK-Doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:710
+#: C/index.docbook:1005
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:705
+#: C/index.docbook:1000
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/>"
+"The GTK-Doc scanner can handle the majority of C headers fine. In the case "
+"of receiving warnings from the scanner that look like a special case, one "
+"can hint GTK-Doc to skip over them. <_:example-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 "
+"Skener GTK-Doc 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:719
+#: C/index.docbook:1014
msgid "Limitations"
msgstr "Omezení"
#. (itstool) path: note/para
-#: C/index.docbook:720
+#: C/index.docbook:1015
msgid ""
"Note, that GTK-Doc's supports <code>#ifndef(__GTK_DOC_IGNORE__)</code> but "
"not <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations."
"ale ne <code>#if !defined(__GTK_DOC_IGNORE__)</code> nebo jiné kombinace."
#. (itstool) path: sect1/title
-#: C/index.docbook:730
+#: C/index.docbook:1025
msgid "Documentation comments"
msgstr "Dokumentační komentáře"
#. (itstool) path: example/programlisting
-#: C/index.docbook:736
+#: C/index.docbook:1031
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:732
+#: C/index.docbook:1027
msgid ""
"A multiline comment that starts with an additional '*' marks a documentation "
"block that will be processed by the GTK-Doc tools. <_:example-1/>"
"dokumentačním blokem a bude zpracovaný nástroji GTK-Doc. <_:example-1/>"
#. (itstool) path: sect1/para
-#: C/index.docbook:745
+#: C/index.docbook:1040
msgid ""
"The 'identifier' is one line with the name of the item the comment is "
"related to. The syntax differs a little depending on the item. (TODO add "
"se seznamem identifikátorů)"
#. (itstool) path: sect1/para
-#: C/index.docbook:751
+#: C/index.docbook:1046
msgid ""
"The 'documentation' block is also different for each symbol type. Symbol "
"types that get parameters such as functions or macros have the parameter "
"hvězdička mezera mezera). To se hodí na text s pevným formátem (výpis kódu)."
#. (itstool) path: listitem/para
-#: C/index.docbook:768
+#: C/index.docbook:1063
msgid ""
"What it is: The name for a class or function can sometimes be misleading for "
"people coming from a different background."
"používají něco jiného."
#. (itstool) path: listitem/para
-#: C/index.docbook:774
+#: C/index.docbook:1069
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:764
+#: C/index.docbook:1059
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:789
+#: C/index.docbook:1084
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:794
+#: C/index.docbook:1089
msgid ""
"Use @param to refer to parameters. Also use this when referring to "
"parameters of other functions, related to the one being described."
"odkazujete na parametry jiných funkcí, vztahujících se k popisované funkci."
#. (itstool) path: listitem/para
-#: C/index.docbook:800
+#: C/index.docbook:1095
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:805
+#: C/index.docbook:1100
msgid ""
"Use #symbol to refer to other types of symbol, e.g. structs and enums and "
"macros which don't take arguments."
"makro, který nemá argumenty."
#. (itstool) path: listitem/para
-#: C/index.docbook:811
+#: C/index.docbook:1106
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:816
+#: C/index.docbook:1111
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:821
+#: C/index.docbook:1116
msgid ""
"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
"foo_bar() to refer to a vmethod."
"neco() pro odkaz na virtuální metodu."
#. (itstool) path: sect1/para
-#: C/index.docbook:783
+#: C/index.docbook:1078
msgid ""
"One advantage of hyper-text over plain-text is the ability to have links in "
"the document. Writing the correct markup for a link can be tedious though. "
"vám snaží pomoci několika užitečnými zkratkami. <_:itemizedlist-1/>"
#. (itstool) path: tip/para
-#: C/index.docbook:830
+#: C/index.docbook:1125
msgid ""
"If you need to use the special characters '<', '>', '()', '@', '%', or "
"'#' in your documentation without GTK-Doc changing them you can use the XML "
"se zpětným lomítkem „\\“."
#. (itstool) path: sect1/para
-#: C/index.docbook:839
+#: C/index.docbook:1134
msgid ""
"DocBook can do more than just links. One can also have lists, examples, "
"headings, and images. As of version 1.20, the preferred way is to use a "
"začátku."
#. (itstool) path: sect1/para
-#: C/index.docbook:850
+#: C/index.docbook:1145
msgid ""
"While markdown is now preferred one can mix both. One limitation here is "
"that one can use docbook xml within markdown, but markdown within docbook "
"markdown v docbook xml podporován není."
#. (itstool) path: sect1/para
-#: C/index.docbook:856
+#: C/index.docbook:1151
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:1160
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:866
+#: C/index.docbook:1161
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:905
+#: C/index.docbook:1200
msgid ""
"More examples of what markdown tags are supported can be found in the <ulink "
"url=\"https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown"
"\">Referenční příručce k syntaxi Markdown pro dokumentaci GTK+</ulink>."
#. (itstool) path: tip/para
-#: C/index.docbook:911
+#: C/index.docbook:1206
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."
+"comment those symbols too. This helps other developers to understand your "
+"code. Therefore we recommend to comment these using normal comments (without "
+"the 2nd '*' in the first line). If later the function needs to be made "
+"public, all one needs to do is to add another '*' in the comment block and "
+"insert the symbol name at the right place inside the sections file."
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."
+"komentovat i tyto symboly. Pomůže to ostatním vývojářů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:925
+#: C/index.docbook:1221
msgid "Documenting sections"
msgstr "Dokumentování oddílů"
#. (itstool) path: sect1/para
-#: C/index.docbook:927
+#: C/index.docbook:1223
msgid ""
"Each section of the documentation contains information about one class or "
"module. To introduce the component one can write a section block. The short "
"použije v rámci tabulky s obsahem. Všechna @pole jsou volitelná."
#. (itstool) path: example/title
-#: C/index.docbook:935
+#: C/index.docbook:1231
msgid "Section comment block"
msgstr "Komentářový blok oddílu"
#. (itstool) path: example/programlisting
-#: C/index.docbook:936
+#: C/index.docbook:1232
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:955
+#: C/index.docbook:1251
msgid "SECTION:<name>"
msgstr "SECTION:<název>"
#. (itstool) path: listitem/para
-#: C/index.docbook:957
+#: C/index.docbook:1253
msgid ""
"The name links the section documentation to the respective part in the "
"<filename><package>-sections.txt</filename> file. The name given here "
"<SOUBOR> v souboru <filename><package>-sections.txt</filename>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:966
+#: C/index.docbook:1262
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:968
+#: C/index.docbook:1264
msgid ""
"A one line description of the section, that later will appear after the "
"links in the TOC and at the top of the section page."
"obsahem a na začátku stránky oddílu."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:975
+#: C/index.docbook:1271
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:977
+#: C/index.docbook:1273
msgid ""
"The section title defaults to <name> from the SECTION declaration. It "
"can be overridden with the @title field."
"jej ale určit i přímo v poli @title."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:984
+#: C/index.docbook:1280
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:986
+#: C/index.docbook:1282
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:1290
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:996
+#: C/index.docbook:1292
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:1002
+#: C/index.docbook:1298
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1009
+#: C/index.docbook:1305
msgid ""
"Stable - The intention of a Stable interface is to enable arbitrary third "
"parties to develop applications to these interfaces, release them, and have "
"nekompatibilní změny očekávají zřídka v opravdu odůvodněných případech."
#. (itstool) path: listitem/para
-#: C/index.docbook:1021
+#: C/index.docbook:1317
msgid ""
"Unstable - Unstable interfaces are experimental or transitional. They are "
"typically used to give outside developers early access to new or rapidly "
"následujíc."
#. (itstool) path: listitem/para
-#: C/index.docbook:1033
+#: C/index.docbook:1329
msgid ""
"Private - An interface that can be used within the GNOME stack itself, but "
"that is not documented for end-users. Such functions should only be used in "
"měly používat jen určeným a dokumentovaným způsobem."
#. (itstool) path: listitem/para
-#: C/index.docbook:1042
+#: C/index.docbook:1338
msgid ""
"Internal - An interface that is internal to a module and does not require "
"end-user documentation. Functions that are undocumented are assumed to be "
"nedokumentované, jsou považované za interní."
#. (itstool) path: listitem/para
-#: C/index.docbook:1004
+#: C/index.docbook:1300
msgid ""
"An informal description of the stability level this API has. We recommend "
"the use of one of these terms: <_:itemizedlist-1/>"
"těchto termínů: <_:itemizedlist-1/>"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1054
+#: C/index.docbook:1350
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1056
+#: C/index.docbook:1352
msgid ""
"The <literal>#include</literal> files to show in the section synopsis (a "
"comma separated list), overriding the global value from the <link linkend="
"položka je volitelná."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1065
+#: C/index.docbook:1361
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1067
+#: C/index.docbook:1363
msgid ""
"The image to display at the top of the reference page for this section. This "
"will often be some sort of a diagram to illustrate the visual appearance of "
"nebo nákres se vztahy vůči jiným třídám. Tato položka je volitelná."
#. (itstool) path: tip/para
-#: C/index.docbook:1078
+#: C/index.docbook:1374
msgid ""
"To avoid unnecessary recompilation after doc-changes put the section docs "
"into the c-source where possible."
"vložte, kde je to možné, dokumentaci oddílu do zdrojového kódu c."
#. (itstool) path: sect1/title
-#: C/index.docbook:1087
+#: C/index.docbook:1383
msgid "Documenting symbols"
msgstr "Dokumentování symbolů"
#. (itstool) path: sect1/para
-#: C/index.docbook:1089
+#: C/index.docbook:1385
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:1393 C/index.docbook:1459
msgid "General tags"
msgstr "Obecné značky"
#. (itstool) path: sect2/para
-#: C/index.docbook:1099
+#: C/index.docbook:1395
msgid ""
"You can add versioning information to all documentation elements to tell "
"when an API was introduced, or when it was deprecated."
"sdělili, kdy bylo API zavedeno, nebo kdy bylo označeno za zastaralé."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1104
+#: C/index.docbook:1400
msgid "Versioning Tags"
msgstr "Značky pro verzování"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1105
+#: C/index.docbook:1401
msgid "Since:"
msgstr "Since:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1107
+#: C/index.docbook:1403
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:1112
+#: C/index.docbook:1408
msgid "Deprecated:"
msgstr "Deprecated:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1114
+#: C/index.docbook:1410
msgid ""
"Paragraph denoting that this function should no be used anymore. The "
"description should point the reader to the new API."
"měl čtenáře odkazovat na nové API."
#. (itstool) path: sect2/para
-#: C/index.docbook:1122
+#: C/index.docbook:1418
msgid ""
"You can also add stability information to all documentation elements to "
"indicate whether API stability is guaranteed for them for all future minor "
"minoritní vydání projektu."
#. (itstool) path: sect2/para
-#: C/index.docbook:1128
+#: C/index.docbook:1424
msgid ""
"The default stability level for all documentation elements can be set by "
"passing the <option>--default-stability</option> argument to "
"do <application>gtkdoc-mkdb</application>."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1134
+#: C/index.docbook:1430
msgid "Stability Tags"
msgstr "Značky pro stabilitu"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1135
+#: C/index.docbook:1431
msgid "Stability: Stable"
msgstr "Stability: Stable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1137
+#: C/index.docbook:1433
msgid ""
"Mark the element as stable. This is for public APIs which are guaranteed to "
"remain stable for all future minor releases of the project."
"že zůstanou stabilní po všechna minoritní vydání projektu."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1144
+#: C/index.docbook:1440
msgid "Stability: Unstable"
msgstr "Stability: Unstable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1146
+#: C/index.docbook:1442
msgid ""
"Mark the element as unstable. This is for public APIs which are released as "
"a preview before being stabilised."
"vydána jako ukázky před tím, než jsou stabilizována."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1152
+#: C/index.docbook:1448
msgid "Stability: Private"
msgstr "Stability: Private"
#. (itstool) path: listitem/para
-#: C/index.docbook:1154
+#: C/index.docbook:1450
msgid ""
"Mark the element as private. This is for interfaces which can be used by "
"tightly coupled modules, but not by arbitrary third parties."
"použita přímo v modulu, ale ne kterýmikoliv třetími stranami."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1164
+#: C/index.docbook:1460
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1184 C/index.docbook:1194
+#: C/index.docbook:1480 C/index.docbook:1490
msgid "Annotations"
msgstr "Anotace"
#. (itstool) path: sect2/para
-#: C/index.docbook:1186
+#: C/index.docbook:1482
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"org/GObjectIntrospection/Annotations\" type=\"http\">wiki</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1195
+#: C/index.docbook:1491
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1216 C/index.docbook:1245
+#: C/index.docbook:1512 C/index.docbook:1541
msgid "Function comment block"
msgstr "Komentářový blok pro funkci"
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1518
msgid ""
"Document whether returned objects, lists, strings, etc, should be freed/"
"unrefed/released."
"uvolnit z paměti."
#. (itstool) path: listitem/para
-#: C/index.docbook:1228
+#: C/index.docbook:1524
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:1233
+#: C/index.docbook:1529
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:1218 C/index.docbook:1304
+#: C/index.docbook:1514 C/index.docbook:1600
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Nezapomeňte prosím: <_:itemizedlist-1/>"
#. (itstool) path: sect2/para
-#: C/index.docbook:1240
+#: C/index.docbook:1536
msgid ""
"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
"private. They are treated like static functions."
"„_“, jsou soukromé. Potom se s nimi zachází jako se statickými funkcemi."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1246
+#: C/index.docbook:1542
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1267
+#: C/index.docbook:1563
msgid "Function tags"
msgstr "Značky pro funkce"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1268 C/index.docbook:1475
+#: C/index.docbook:1564 C/index.docbook:1771
msgid "Returns:"
msgstr "Returns:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1270
+#: C/index.docbook:1566
msgid "Paragraph describing the returned result."
msgstr "Odstavec popisující vracený výsledek."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1275
+#: C/index.docbook:1571
msgid "@...:"
msgstr "@…:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1277
+#: C/index.docbook:1573
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:1583 C/index.docbook:1585
msgid "Property comment block"
msgstr "Komentářový blok pro vlastnost"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1290
+#: C/index.docbook:1586
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1302 C/index.docbook:1321
+#: C/index.docbook:1598 C/index.docbook:1617
msgid "Signal comment block"
msgstr "Komentářový blok pro signál"
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1604
msgid ""
"Document when the signal is emitted and whether it is emitted before or "
"after other signals."
"ostatních signálech."
#. (itstool) path: listitem/para
-#: C/index.docbook:1314
+#: C/index.docbook:1610
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:1322
+#: C/index.docbook:1618
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1339 C/index.docbook:1340
+#: C/index.docbook:1635 C/index.docbook:1636
msgid "Struct comment block"
msgstr "Komentářový blok pro strukturu"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1341
+#: C/index.docbook:1637
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1652
msgid ""
"Use <code>/*< private >*/</code> before the private struct fields you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"*/</code>."
#. (itstool) path: sect2/para
-#: C/index.docbook:1362
+#: C/index.docbook:1658
msgid ""
"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" "
"it will be considered private automatically and doesn't need to be mentioned "
"komentářovém bloku."
#. (itstool) path: sect2/para
-#: C/index.docbook:1368
+#: C/index.docbook:1664
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:1676 C/index.docbook:1677
msgid "Enum comment block"
msgstr "Komentářový blok pro výčty"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1382
+#: C/index.docbook:1678
#, no-wrap
msgid ""
"\n"
"} Something;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1399
+#: C/index.docbook:1695
msgid ""
"Use <code>/*< private >*/</code> before the private enum values you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"public >*/</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1410
+#: C/index.docbook:1706
msgid "Inline program documentation"
msgstr "Dokumentaci k vloženým programům"
#. (itstool) path: sect1/para
-#: C/index.docbook:1411
+#: C/index.docbook:1707
msgid ""
"You can document programs and their commandline interface using inline "
"documentation."
"vložené dokumentace."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1417
+#: C/index.docbook:1713
msgid "Tags"
msgstr "Značky"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1419
+#: C/index.docbook:1715
msgid "PROGRAM"
msgstr "PROGRAM"
#. (itstool) path: listitem/para
-#: C/index.docbook:1422
+#: C/index.docbook:1718
msgid "Defines the start of a program documentation."
msgstr "Definuje začátek dokumentace k programu."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1429
+#: C/index.docbook:1725
msgid "@short_description:"
msgstr "@short_description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1431
+#: C/index.docbook:1727
msgid "Defines a short description of the program. (Optional)"
msgstr "Definuje krátký popis programu. (volitelné)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1438
+#: C/index.docbook:1734
msgid "@synopsis:"
msgstr "@synopsis:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1440
+#: C/index.docbook:1736
msgid ""
"Defines the arguments, or list of arguments that the program can take. "
"(Optional)"
"Definuje argumenty nebo seznam argumentů, které program přebírá. (volitelné)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1448
+#: C/index.docbook:1744
msgid "@see_also:"
msgstr "@see_also:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1450
+#: C/index.docbook:1746
msgid "See Also manual page section. (Optional)"
msgstr "Část stránky oddílu „Viz také“. (volitelné)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1457
+#: C/index.docbook:1753
msgid "@arg:"
msgstr "@arg:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1459
+#: C/index.docbook:1755
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:1466
+#: C/index.docbook:1762
msgid "Description:"
msgstr "Description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1468
+#: C/index.docbook:1764
msgid "A longer description of the program."
msgstr "Úplný popis programu."
#. (itstool) path: listitem/para
-#: C/index.docbook:1477
-msgid "Specificy what value(s) the program returns. (Optional)"
+#: C/index.docbook:1773
+msgid "Specify 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:1486
+#: C/index.docbook:1782
msgid "Example of program documentation."
msgstr "Příklad dokumentace k programu."
#. (itstool) path: example/title
-#: C/index.docbook:1487
+#: C/index.docbook:1783
msgid "Program documentation block"
msgstr "Komentářový blok pro program"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1488
+#: C/index.docbook:1784
#, no-wrap
msgid ""
"\n"
"}\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1514
+#: C/index.docbook:1810
msgid "Useful DocBook tags"
msgstr "Užitečné značky DocBook"
#. (itstool) path: sect1/para
-#: C/index.docbook:1516
+#: C/index.docbook:1812
msgid ""
"Here are some DocBook tags which are most useful when documenting the code."
msgstr ""
"význam."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1525
+#: C/index.docbook:1821
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Hašovací tabulky</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1521
+#: C/index.docbook:1817
msgid ""
"To link to another section in the GTK docs: <_:informalexample-1/> The "
"linkend is the SGML/XML id on the top item of the page you want to link to. "
"podtržítka se převedou na „-“, aby to vyhovovalo SGML/XML."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1538
+#: C/index.docbook:1834
#, no-wrap
msgid ""
"\n"
"<function>…</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1535
+#: C/index.docbook:1831
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
">"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1547
+#: C/index.docbook:1843
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1558
+#: C/index.docbook:1854
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1544
+#: C/index.docbook:1840
msgid ""
"To include example code: <_:informalexample-1/> or possibly this, for very "
"short code fragments which don't need a title: <_:informalexample-2/> For "
"V novějších verzích GTK-Doc je také podporované zkracování: |[ … ]|"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1577
+#: C/index.docbook:1873
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1574
+#: C/index.docbook:1870
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Vložení seznamu s odrážkami: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1597
+#: C/index.docbook:1893
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1594
+#: C/index.docbook:1890
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:1610
+#: C/index.docbook:1906
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1607
+#: C/index.docbook:1903
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "Odkaz na typ: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1619
+#: C/index.docbook:1915
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1616
+#: C/index.docbook:1912
msgid ""
"To refer to an external structure (not one described in the GTK docs): <_:"
"informalexample-1/>"
"informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1628
+#: C/index.docbook:1924
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1625
+#: C/index.docbook:1921
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:1637
+#: C/index.docbook:1933
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1634
+#: C/index.docbook:1930
msgid ""
"To refer to a class name, we could possibly use: <_:informalexample-1/> but "
"you'll probably be using #GtkWidget instead (to automatically create a link "
"\"documenting_syntax\">zkratky</link>)."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1648
+#: C/index.docbook:1944
#, no-wrap
msgid ""
"\n"
"<emphasis>Toto je důležité</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1645
+#: C/index.docbook:1941
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Zvýrazněný text: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1657
+#: C/index.docbook:1953
#, no-wrap
msgid ""
"\n"
"<filename>/home/user/documents</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1654
+#: C/index.docbook:1950
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Pro název souboru použijte: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1666
+#: C/index.docbook:1962
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1663
+#: C/index.docbook:1959
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "Odkaz na použití klávesy: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1676
+#: C/index.docbook:1972
msgid "Filling the extra files"
msgstr "Vyplňování dodatečných souborů"
#. (itstool) path: chapter/para
-#: C/index.docbook:1678
+#: C/index.docbook:1974
msgid ""
"There are a couple of extra files, that need to be maintained along with the "
"inline source code comments: <filename><package>.types</filename>, "
"<filename><balíček>-sections.txt</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1687
+#: C/index.docbook:1983
msgid "Editing the types file"
msgstr "Úprava souboru s typy"
#. (itstool) path: sect1/para
-#: C/index.docbook:1689
+#: C/index.docbook:1985
msgid ""
"If your library or application includes GObjects, you want their signals, "
"arguments/parameters and position in the hierarchy to be shown in the "
"filename>."
#. (itstool) path: example/title
-#: C/index.docbook:1698
-msgid "Example types file snippet"
-msgstr "Příklad úryvku ze souboru typů"
+#: C/index.docbook:1994
+msgid "Example <package>.types file"
+msgstr "Příklad souboru <balíček>.types"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1699
+#: C/index.docbook:1995
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1710
+#: C/index.docbook:2006
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"byste soubor s typy šířit do správy verzí."
#. (itstool) path: sect1/title
-#: C/index.docbook:1719
+#: C/index.docbook:2015
msgid "Editing the master document"
msgstr "Úprava hlavního dokumentu"
#. (itstool) path: sect1/para
-#: C/index.docbook:1721
+#: C/index.docbook:2017
msgid ""
"GTK-Doc produces documentation in DocBook SGML/XML. When processing the "
"inline source comments, the GTK-Doc tools generate one documentation page "
"soubor. Všechny jsou pak uvedené seřazené v hlavním dokumentu."
#. (itstool) path: sect1/para
-#: C/index.docbook:1728
+#: C/index.docbook:2024
msgid ""
"While GTK-Doc creates a template master document for you, later runs will "
"not touch it again. This means that one can freely structure the "
"nahlédnout, jestli se v něm neobjevily nějaké nové věci."
#. (itstool) path: tip/para
-#: C/index.docbook:1738
+#: C/index.docbook:2034
msgid ""
"Do not create tutorials as extra documents. Just write extra chapters. The "
"benefit of directly embedding the tutorial for your library into the API "
"v knihovně."
#. (itstool) path: sect1/para
-#: C/index.docbook:1747
+#: C/index.docbook:2043
msgid ""
"So what are the things to change inside the master document? For a start is "
"only a little. There are some placeholders (text in square brackets) there "
"závorkách), o které byste se měli postarat."
#. (itstool) path: example/title
-#: C/index.docbook:1754
+#: C/index.docbook:2050
msgid "Master document header"
msgstr "Hlavička hlavního dokumentu"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1755
+#: C/index.docbook:2051
#, no-wrap
msgid ""
"\n"
" <title>[Insert title here]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1771
+#: C/index.docbook:2067
msgid ""
"In addition a few option elements are created in commented form. You can "
"review these and enable them as you like."
"projít a případně povolit."
#. (itstool) path: example/title
-#: C/index.docbook:1777
+#: C/index.docbook:2073
msgid "Optional part in the master document"
msgstr "Volitelná část hlavního dokumentu"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1778
+#: C/index.docbook:2074
#, no-wrap
msgid ""
"\n"
" -->\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1786
+#: C/index.docbook:2082
msgid ""
"Finally you need to add new section whenever you introduce one. The <link "
"linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> tool will remind "
"vygenerované soubory XML, které zatím nejsou v dokumentaci zahrnuté."
#. (itstool) path: example/title
-#: C/index.docbook:1794 C/index.docbook:1829
+#: C/index.docbook:2090 C/index.docbook:2125
msgid "Including generated sections"
msgstr "Vkládání generovaných oddílů"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1795
+#: C/index.docbook:2091
#, no-wrap
msgid ""
"\n"
" …\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1807
+#: C/index.docbook:2103
msgid "Editing the section file"
msgstr "Úprava souboru oddílů"
#. (itstool) path: sect1/para
-#: C/index.docbook:1809
+#: C/index.docbook:2105
msgid ""
"The section file is used to organise the documentation output by GTK-Doc. "
"Here one specifies which symbol belongs to which module or class and control "
"viditelnost (jestli je veřejný nebo soukromý)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1815
+#: C/index.docbook:2111
msgid ""
"The section file is a plain text file with tags delimiting sections. Blank "
"lines are ignored and lines starting with a '#' are treated as comment lines."
"jako s komentářovými řádky."
#. (itstool) path: note/para
-#: C/index.docbook:1822
+#: C/index.docbook:2118
msgid ""
"While the tags make the file look like xml, it is not. Please do not close "
"tags like <SUBSECTION>."
"Neuzavírejte prosím značky jako je <SUBSECTION>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1830
+#: C/index.docbook:2126
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1847
+#: C/index.docbook:2143
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"názvu třídy GObject převedeného na malá písmena.)"
#. (itstool) path: sect1/para
-#: C/index.docbook:1859
+#: C/index.docbook:2155
msgid ""
"The <TITLE> ... </TITLE> tag is used to specify the title of the "
"section. It is only useful before the templates (if used) are initially "
"zdrojovém kódu."
#. (itstool) path: sect1/para
-#: C/index.docbook:1866
+#: C/index.docbook:2162
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"virtuální metody)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1885
+#: C/index.docbook:2181
msgid ""
"You can also use <INCLUDE> ... </INCLUDE> to specify the "
"#include files which are shown in the synopsis sections. It contains a comma-"
"konce souboru. Když je nastavíte v konkrétním oddílu, použijí se jen pro něj."
#. (itstool) path: chapter/title
-#: C/index.docbook:1899
+#: C/index.docbook:2195
msgid "Controlling the result"
msgstr "Ovlivnění výsledku"
#. (itstool) path: chapter/para
-#: C/index.docbook:1901
+#: C/index.docbook:2197
msgid ""
"A GTK-Doc run generates report files inside the documentation directory. The "
"generated files are named: <filename><package>-undocumented.txt</"
"prosté textové soubory, které si lze jednoduše prohlížet a zpracovávat je."
#. (itstool) path: chapter/para
-#: C/index.docbook:1910
+#: C/index.docbook:2206
msgid ""
"The <filename><package>-undocumented.txt</filename> file starts with "
"the documentation coverage summary. Below are two sections divided by blank "
"parametr."
#. (itstool) path: chapter/para
-#: C/index.docbook:1919
+#: C/index.docbook:2215
msgid ""
"The <filename><package>-undeclared.txt</filename> file lists symbols "
"given in the <filename><package>-sections.txt</filename> but not found "
"v nich není překlep."
#. (itstool) path: chapter/para
-#: C/index.docbook:1926
+#: C/index.docbook:2222
msgid ""
"The <filename><package>-unused.txt</filename> file lists symbol names, "
"where the GTK-Doc scanner has found documentation, but does not know where "
"balíček>-section.txt</filename>."
#. (itstool) path: tip/para
-#: C/index.docbook:1934
+#: C/index.docbook:2230
msgid ""
"Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile."
"am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during "
"správnosti údajů."
#. (itstool) path: chapter/para
-#: C/index.docbook:1941
+#: C/index.docbook:2237
msgid ""
"One can also look at the files produced by the source code scanner: "
"<filename><package>-decl-list.txt</filename> and <filename><"
"zkontrolovat, jestli se vyskytuje v tomto souboru."
#. (itstool) path: chapter/para
-#: C/index.docbook:1950
+#: C/index.docbook:2246
msgid ""
"If the project is GObject based, one can also look into the files produced "
"by the object scanner: <filename><package>.args.txt</filename>, "
"Doc, aby přechodně zachovat soubor pro pozdější analýzu."
#. (itstool) path: chapter/title
-#: C/index.docbook:1965
+#: C/index.docbook:2261
msgid "Modernizing the documentation"
msgstr "Modernizace dokumentu"
#. (itstool) path: chapter/para
-#: C/index.docbook:1967
+#: C/index.docbook:2263
msgid ""
"GTK-Doc has been around for quite some time. In this section we list new "
"features together with the version since when it is available."
"funkcí spolu s číslem verze, od které je tato funkčnost k dispozici."
#. (itstool) path: sect1/title
-#: C/index.docbook:1973
+#: C/index.docbook:2269
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1975
+#: C/index.docbook:2271
msgid ""
"When using xml instead of sgml, one can actually name the master document "
"<filename><package>-docs.xml</filename>."
"dokument <filename><package>-docs.xml</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1980
+#: C/index.docbook:2276
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:1991
+#: C/index.docbook:2287
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"tuto volbu do <filename>configure.ac</filename> a je to."
#. (itstool) path: sect1/title
-#: C/index.docbook:2003
+#: C/index.docbook:2299
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:2005
+#: C/index.docbook:2301
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"filename> pro kód, který je sestavován podmíněně."
#. (itstool) path: sect1/title
-#: C/index.docbook:2016
+#: C/index.docbook:2312
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:2022
+#: C/index.docbook:2318
msgid "Enable gtkdoc-check"
msgstr "Povolení gtkdoc-check"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2023
+#: C/index.docbook:2319
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2018
+#: C/index.docbook:2314
msgid ""
"This version includes a new tool called gtkdoc-check. This tool can run a "
"set of sanity checks on your documentation. It is enabled by adding these "
">"
#. (itstool) path: sect1/title
-#: C/index.docbook:2036
+#: C/index.docbook:2332
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:2038
+#: C/index.docbook:2334
msgid ""
"Version 1.18 brought some initial markdown support. Using markdown in doc "
"comments is less intrusive than writing docbook xml. This version improves a "
"\"documenting_syntax\">syntax komentářů</link>."
#. (itstool) path: sect1/title
-#: C/index.docbook:2048
+#: C/index.docbook:2344
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:2058
+#: C/index.docbook:2355
msgid "Use pre-generated entities"
msgstr "Používání předgenerovaných entit"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2059
+#: C/index.docbook:2356
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2050
+#: C/index.docbook:2346
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/>"
+"the entity file is included in the master template and how the entities are "
+"used. The entities can also be used in all generated files, GTK-Doc will use "
+"the same xml header in generated xml files. <_:example-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/>"
+"je uveden příklad, jak soubor s entitami vložit do hlavní šablony 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:2084
+#: C/index.docbook:2381
msgid "Documenting other interfaces"
msgstr "Dokumentování ostatních rozhraní"
#. (itstool) path: chapter/para
-#: C/index.docbook:2086
+#: C/index.docbook:2383
msgid ""
"So far we have been using GTK-Doc to document the API of code. The next "
"sections contain suggestions how the tools can be used to document other "
"dalších rozhraní."
#. (itstool) path: sect1/title
-#: C/index.docbook:2093
+#: C/index.docbook:2390
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:2095
+#: C/index.docbook:2392
msgid ""
"As one can generate man pages for a docbook refentry as well, it sounds like "
"a good idea to use it for that purpose. This way the interface is part of "
"manuálovou stránku."
#. (itstool) path: sect2/title
-#: C/index.docbook:2102
+#: C/index.docbook:2399
msgid "Document the tool"
msgstr "Dokumentování nástrojů"
#. (itstool) path: sect2/para
-#: C/index.docbook:2104
+#: C/index.docbook:2401
msgid ""
"Create one refentry file per tool. Following <link linkend="
"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
"souboru v podsložce XML, například v glib."
#. (itstool) path: sect2/title
-#: C/index.docbook:2114
+#: C/index.docbook:2411
msgid "Adding the extra configure check"
msgstr "Přidání doplňkových kontrol do configure"
#. (itstool) path: example/title
-#: C/index.docbook:2117 C/index.docbook:2135
+#: C/index.docbook:2414 C/index.docbook:2432
msgid "Extra configure checks"
msgstr "Dodatečné kontroly nastavení"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2118
+#: C/index.docbook:2415
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2132
+#: C/index.docbook:2429
msgid "Adding the extra makefile rules"
msgstr "Přidání doplňkových pravidel do Makefile"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2136
+#: C/index.docbook:2433
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2158
+#: C/index.docbook:2455
msgid "DBus interfaces"
msgstr "Rozhraní D-Bus"
#. (itstool) path: sect1/para
-#: C/index.docbook:2160
+#: C/index.docbook:2457
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:2169
+#: C/index.docbook:2466
msgid "Frequently asked questions"
msgstr "Často kladené dotazy"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2173
+#: C/index.docbook:2470
msgid "Question"
msgstr "Dotaz"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2174
+#: C/index.docbook:2471
msgid "Answer"
msgstr "Odpověď"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2176
+#: C/index.docbook:2473
msgid "No class hierarchy."
msgstr "Schází hierarchie třídy."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2177
+#: C/index.docbook:2474
msgid ""
"The objects <function>xxx_get_type()</function> function has not been "
"entered into the <filename><package>.types</filename> file."
"objektu <function>xxx_get_type()</function>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2183
+#: C/index.docbook:2480
msgid "Still no class hierarchy."
msgstr "Stále schází hierarchie třídy."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2184
+#: C/index.docbook:2481
msgid ""
"Missing or wrong naming in <filename><package>-sections.txt</filename> "
"file (see <ulink url=\"http://mail.gnome.org/archives/gtk-doc-list/2003-"
"doc-list/2003-October/msg00006.html\">vysvětlení</ulink>)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2190
+#: C/index.docbook:2487
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:2191
+#: C/index.docbook:2488
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:2198
+#: C/index.docbook:2495
msgid "No symbol index."
msgstr "Chybí rejstřík symbolů."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2199
+#: C/index.docbook:2496
msgid ""
"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
"index that xi:includes the generated index?"
"který vloží pomocí xi:include vygenerovaný rejstřík?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2205
+#: C/index.docbook:2502
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:2206
+#: C/index.docbook:2503
msgid ""
"Is the doc-comment using the correct markup (added #,% or ())? Check if the "
"gtkdoc-fixxref warns about unresolvable xrefs."
"Podívejte se na varování gtkdoc-fixxref o nevyřešených křížových odkazech."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2212
+#: C/index.docbook:2509
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:2213
+#: C/index.docbook:2510
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"{xml,sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2219
+#: C/index.docbook:2516
msgid "A new symbol does not appear in the docs."
msgstr "Nový symbol se neobjevil v dokumentaci."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2220
+#: C/index.docbook:2517
msgid ""
"Is the doc-comment properly formatted. Check for spelling mistakes in the "
"begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable "
"<filename><package>-sections.txt</filename> ve veřejném pododdíle."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2228
+#: C/index.docbook:2525
msgid "A type is missing from the class hierarchy."
msgstr "V hierarchii třídy schází typ."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2229
+#: C/index.docbook:2526
msgid ""
"If the type is listed in <filename><package>.hierarchy</filename> but "
"not in <filename>xml/tree_index.sgml</filename> then double check that the "
"zobrazena."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2238
+#: C/index.docbook:2535
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:2239
+#: C/index.docbook:2536
msgid ""
"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
"from <filename><package>-docs.{xml,sgml}</filename>."
"pomocí xi:include z <filename><package>-docs.{xml,sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2247
+#: C/index.docbook:2544
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:2248
+#: C/index.docbook:2545
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
"než ve zdrojovém kódu."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2253
+#: C/index.docbook:2550
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "Více „ID“ pro tentýž cíl odkazu: XYZ"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2254
+#: C/index.docbook:2551
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"objevuje dvakrát."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2257
+#: C/index.docbook:2554
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"mu žádná šablona."
#. (itstool) path: chapter/title
-#: C/index.docbook:2264
+#: C/index.docbook:2561
msgid "Tools related to gtk-doc"
msgstr "Nástroje související s GTK-Doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2266
+#: C/index.docbook:2563
msgid ""
"GtkDocPlugin - a <ulink url=\"http://trac-hacks.org/wiki/GtkDocPlugin\">Trac "
"GTK-Doc</ulink> integration plugin, that adds API docs to a trac site and "
"dokumentaci k API na sledovací web a integruje ji do vyhledávání."
#. (itstool) path: chapter/para
-#: C/index.docbook:2271
+#: C/index.docbook:2568
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."
"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 "Setting up your project"
+#~ msgstr "Nastavení vašeho projektu"
+
+#~ 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í."
+
+#~ 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ý."
+
+#~ msgid "Example directory structure"
+#~ msgstr "Příklad struktury složek"
+
+#~ msgid "This can then look as shown below: <_:example-1/>"
+#~ msgstr "Ve výsledku to může vypadat nějak takto: <_:example-1/>"
+
+#~ 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>."
+
+#~ 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"
+
+#~ msgid "Keep gtk-doc optional"
+#~ msgstr "Ponechání gtk-doc jako volitelného"
+
+#~ 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"
+
+#~ 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/>"
+
+#~ 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 ""
+#~ "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."
+
+#~ msgid "Preparation for gtkdocize"
+#~ msgstr "Příprava pro gtkdocize"
+
+#~ msgid ""
+#~ "\n"
+#~ "AC_CONFIG_MACRO_DIR(m4)\n"
+#~ msgstr ""
+#~ "\n"
+#~ "AC_CONFIG_MACRO_DIR(m4)\n"
+
+#~ 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í)."
+
+#~ 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."
+
+#~ msgid "Documentation placement"
+#~ msgstr "Umístění dokumentace"
+
+#~ 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í."
+
+#~ 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."
</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>
+ <copyright>
+ <year>2007-2019</year>
+ <holder>Stefan Sauer (Kost)</holder>
+ </copyright>
<!-- translators: uncomment this:
<copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision><revnumber>1.28</revnumber> <date>24. března 2018</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb</revremark></revision>
<revision><revnumber>1.27</revnumber> <date>7. prosince 2017</date> <authorinitials>ss</authorinitials> <revremark>detailní vyladění portu v jazyce Python</revremark></revision>
<orderedlist>
<listitem>
- <para>
- <guilabel>Writing the documentation.</guilabel>
-
- The author fills in the source files with the documentation for each
- function, macro, structs or unions, etc.
- </para>
+ <para><guilabel>Psaní dokumentace.</guilabel> Autor doplní soubory se zdrojovým kódem s dokumentací pro každou funkci, makro, strukturu, výčet atd.</para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>O aplikaci GTK-Doc</title>
- <para>
- Historically GTK-Doc was used to generate template files from the soures
- code. These template files could be used by developers to enter the
- API documentation. This approach was rather inconvenient because it
- required to keep the generated files under version control.
- Since GTK-Doc 1.9 it became possible to place all API information
- into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
- </para>
+ <para>Historicky se GTK-Doc používalo ke generování šablonových souborů ze zdrojových kódů. Tyto šablonové soubory pak mohli vývojáři používat ke vkládání dokumentace k API. Tento postup byl dosti nepohodlný, protože vyžadovat udržování vygenerovaných souborů ve správě verzí. Proto od verze 1.9 přichází GTK-Doc s možností vkládat všechny informace o API do komentářů ve zdrojových kódech, čímž se podpora šablon stává nadbytečnou. Ve verzi 1.26 byla podpora šablon odstraněna.</para>
<para>(DOPLNIT)</para>
- <para>
- (authors, web pages, mailing list, license, future plans,
- comparison with other similar systems.)
- </para>
+ <para>(autoři, webové stránky, poštovní konference, licence, plány do budoucna, srovnání s ostatními podobnými systémy.)</para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Project Setup</title>
+ <title>Nastavení projektu</title>
- <para>
- This Chapter describes the steps that are necessary to integrate GTK-Doc
- into your project. The integration of GTK-Doc into a project includes the
- following steps:
- </para>
+ <para>Tato kapitola popisuje kroky, které jsou nutné pro integraci GTK-Doc do vašeho projektu. Integrace GTK-Doc do projektu zahrnuje následující kroky:</para>
<itemizedlist>
<listitem>
- <para>
- Preparation of the directory structure and creating required
- configuration files for your GTK-Doc documentation (see
- <link linkend="settingup_docfiles">
- Setting up a skeleton documentation</link>).
- </para>
+ <para>Přípravu struktury složek a vytvoření požadovaných konfiguračních souborů pro dokumentaci GTK-Doc (viz <link linkend="settingup_docfiles">Nastavení kostry dokumentace</link>).</para>
</listitem>
<listitem>
- <para>
- Adjusting the build system to build your documentation using the
- GTK-Doc tools. Multiple build systems are supported, in
- this manual we describe how to integrate GTK-Doc with
- <link linkend="settingup_autotools">Autotools</link>,
- <link linkend="settingup_cmake">CMake</link>, and
- <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
- </para>
+ <para>Přizpůsobení sestavovacího systému, aby sestavoval vaši dokumentaci pomocí nástrojů GTK-Doc. Je podporováno více sestavovacích systémů, v této příručce je popsáno, jak integrovat GTK-Doc s <link linkend="settingup_autotools">Autotools</link>, <link linkend="settingup_cmake">CMake</link> a <link linkend="settingup_plain_makefiles">prostými soubory Makefiles</link>.</para>
</listitem>
<listitem>
- <para>
- Adding GTK-Doc specific files to version control and deciding which
- files to ignore (see <link linkend="settingup_vcs">
- Integration with version control systems</link>).
- </para>
+ <para>Přidání souborů specifických pro GTK-Doc do správy verzí a rozhodnutí, které soubory se mají ignorovat (viz <link linkend="settingup_vcs">Integrace se systémem správy verzí</link>).</para>
</listitem>
</itemizedlist>
- <para>
- The following sections assume we work on a project called
- <code>meep</code>.
- This project contains two packages (or modules),
- a library called <code>libmeep</code> and an end-user app
- called <code>meeper</code>.
- </para>
+ <para>Následující oddíly předpokládají, že pracujeme na projektu nazvaném <code>meep</code>. Tento projekt obsahuje dva balíčky (nebo moduly), knihovnu nazvanou <code>libmeep</code> a uživatelskou aplikaci nazvanou <code>meeper</code>.</para>
<sect1 id="settingup_docfiles">
<title>Nastavení kostry dokumentace</title>
- <para>
- A common convention is to place documentation into a folder called
- <code>docs</code> inside your top-level project directory.
- We usually distinguish between <emphasis>reference
- documentation</emphasis> intended for developers and an
- <emphasis>user manual</emphasis> intended for end-users.
- Again the convention is to have separate folders for both.
- We usually place the reference documentation in a folder named
- <code>reference</code> and the end-user manual in a folder named
- <code>help</code> as.
-
- According to the above convention the documentation for our
- <code>libmeep</code> package would be placed into:
- <code>docs/reference/libmeep</code>.
-
- For packages with just one library or application
- the documentation could also be placed directly into
- <code>docs/reference</code>.
-
- It is not mandatory to use the above convention, but if you
- choose to use a different directory structure you must adjust
- your build system configuration to match your directory
- structure.
- </para>
-
- <para>
- In the following sections we will assume a directory structure
- for our <emphasis>meep</emphasis> project that uses the above
- conventions.
+ <para>Zaběhnutým zvykem je umístit dokumentaci do složky nazvané <code>docs</code> ve složce nejvyšší úrovně projektu. Obvykle rozlišujeme mezi <emphasis>referenční dokumentací</emphasis> zaměřenou na vývojáře a <emphasis>uživatelskou příručkou</emphasis> zaměřenou na koncového uživatele. Opět je zvykem mít zvláštní složku pro každou z obou zmíněných. Obvykle umisťujeme referenční dokumentaci do složky nazvané <code>reference</code> a uživatelskou příručku do složky nazvané <code>help</code>. V souladu se zmíněnými zvyky by dokumentace pro naši knihovnu <code>libmeep</code> byla umístěna do <code>docs/reference/libmeep</code>. U balíčků s jedinou knihovnou nebo referenční dokumentací by bylo možné ji umístit přímo do <code>docs/reference</code>. Není povinné použít uvedenou konvenci, ale pokud se rozhodnete použít jinou strukturu složek, musíte upravit konfiguraci sestavovacího systému, aby se s ní shodoval.</para>
- <example>
- <title>Example directory structure of <emphasis>meep</emphasis>
- project</title>
- <programlisting><![CDATA[
+ <para>V následujících oddílech budeme uvažovat strukturu složek pro náš projekt <emphasis>meep</emphasis>, který používá výše uvedené konvence. <example>
+ <title>Příklad struktury složek projektu <emphasis>meep</emphasis></title>
+ <programlisting>
meep/
docs/
- reference/ # reference documentation
+ reference/ # referenční dokumentace
libmeep/
meeper/
- help/ # optional: user manual
+ help/ # volitelné: uživatelská příručka
meeper/
src/
libmeep/
meeper/
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
</sect1>
<sect1 id="settingup_autotools">
- <title>Integration with Autotools</title>
- <para>
- Integration of GTK-Doc into an autotools-based build system requires the
- following steps:
- </para>
+ <title>Integrace s Autotools</title>
+ <para>Integrace GTK-Doc do sestavovacího systému založeného na Autotools vyžaduje následující kroky:</para>
<itemizedlist>
<listitem>
- <para>
- Ensure that <application>gtkdocize</application> is run once before
- the <filename>configure</filename> script. If an
- <filename>autogen.sh</filename> script is present, adjust it to
- check for GTK-Doc and add a call to
- <application>gtkdocize</application>.
- </para>
-
- <para>
- The main purpose of <application>gtkdocize</application> is to
- make the <filename>gtk-doc.make</filename> Makefile and the
- <filename>gtk-doc.m4</filename> macro definition file available
- to the build system, either by copying or linking it
- into the project.
- </para>
+ <para>Zajistit, že <application>gtkdocize</application> se spustí právě jednou před skriptem <filename>configure</filename>. Pokud je přítomen skript <filename>autogen.sh</filename>, upravte jej, aby kontroloval GTK-Doc a přidejte volání <application>gtkdocize</application>.</para>
+
+ <para>Hlavním účelem <application>gtkdocize</application> je vytvořit Makefile <filename>gtk-doc.make</filename> a definici makra <filename>gtk-doc.m4</filename> dostupnou sestavovacímu systému, buď zkopírováním do projektu nebo vytvořením odkazu.</para>
</listitem>
<listitem>
- <para>
- Add the necessary <application>autoconf</application> macros to
- <filename>configure.ac</filename> to enable GTK-Doc in your build
- system to allow configuration of GTK-Doc via the generated
- <filename>configure</filename> script.
- </para>
- <para>
- Among others with registers the <code>--enable-gtk-doc</code>
- option with the <filename>configure</filename> script.
- </para>
+ <para>Přidat potřebná makra <application>autoconf</application> do <filename>configure.ac</filename>, abyste povolili GTK-Doc v sestavovacím systému a konfigurace GTK-Doc mohla jít přes generovaný skript <filename>configure</filename>.</para>
+ <para>Mimo jiné pomocí registrace přepínače <code>--enable-gtk-doc</code> ve skriptu <filename>configure</filename>.</para>
</listitem>
<listitem>
- <para>
- Create an <application>automake</application> script for each
- application or library in your project. In the example used in this
- documentation this step applies to both <code>meeper</code> and
- <code>libmeep</code>.
- </para>
+ <para>Vytvořit skript <application>automake</application> pro jednotlivé aplikace a knihovny ve svém projektu. V příkladu použitém v této dokumentaci je tento krok použit jak pro <code>meeper</code>, tak pro <code>libmeep</code>.</para>
</listitem>
</itemizedlist>
- <para>
- In the following sections, we will perform the above steps in reverse
- order. We start with the <application>automake</application> scripts
- and work our way up to <filename>configure.ac</filename> and
- <filename>autogen.sh</filename>.
- Then we show how enable Gtk-Doc in the build system and
- how to build the documentation.
- </para>
+ <para>V následujícím oddíle provedeme výše zmíněné kroky v opačném pořadí. Začneme se skripty <application>automake</application> a budeme postupovat až k <filename>configure.ac</filename> a <filename>autogen.sh</filename>. Pak si ukážeme, jak povolit GTK-Doc v sestavovacím systému a jak sestavit dokumentaci.</para>
<sect2 id="settingup_automake">
<title>Integrace s automake</title>
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub-directory of the
- <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
- gtkdoc-sources</ulink>
- to your project's reference documentation directory (e.g.
- <filename class="directory">docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple packages repeat this for each one.
- </para>
+ <para>Jako první nakopírujte <filename>Makefile.am</filename> z podsložky <filename class="directory">examples</filename> ve složce <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">gtkdoc-sources</ulink> do složky s referenční dokumentací svého projektu (např. <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>
<note>
- <simpara>
- Do not forget to add each <filename>Makefile.am</filename>
- to the <function>AC_CONFIG_FILES</function> macro in
- <filename>configure.ac</filename>. For
- <filename>docs/reference/libmeep/Makefile.am</filename> you will
- need to add the entry
- <filename>docs/reference/libmeep/Makefile</filename>
- to <function>AC_CONFIG_FILES</function>.
- </simpara>
+ <simpara>Nezapomeňte přidat jednotlivé <filename>Makefile.am</filename> do makra <function>AC_CONFIG_FILES</function> v <filename>configure.ac</filename>. Pro <filename>docs/reference/libmeep/Makefile.am</filename> budete potřebovat přidat záznam <filename>docs/reference/libmeep/Makefile</filename> do <function>AC_CONFIG_FILES</function>.</simpara>
</note>
<example>
- <title>
- Example directory structure with <filename>Makefiles.am</filename>
- </title>
+ <title>Příklad struktury složek s <filename>Makefiles.am</filename></title>
<programlisting>
meep/
docs/
- reference/ # reference documentation
+ reference/ # referenční dokumentace
libmeep/
Makefile.am
meeper/
Makefile.am
- help/ # optional: user manual
+ help/ # volitelné: uživatelská příručka
meeper/
src/
libmeep/
</programlisting>
</example>
- <para>
- Next, you need to customize the copied Makefiles
- and provide values for the various parameters in each
- <filename>Makefile.am</filename>.
-
- All settings have a comment above them that describes their purpose
- and how to customize the setting.
-
- Most settings are used to supply extra flags to the respective tools
- to which they apply. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>
- (e.g. the tool <application>gtkdoc-mkhtml</application> has
- an option named <code>MKHTML_OPTIONS</code>).
-
- All the tools support <option>--help</option> to list the supported
- options.
- </para>
-
- <para>
- The following list explains the most relevant options. Check the
- example <filename>Makefile.am</filename> for additional options.
+ <para>Dále je třeba přizpůsobit zkopírované soubory Makefile a dodat hodnoty pro různé parametry v jednotlivých <filename>Makefile.am</filename>. Všechna nastavení mají komentáře s popisem svého účelu a jak nastavení přizpůsobit. Většina nastavení má doplňující příznaky předávané do dotyčných nástrojů, které je umí použít. Každý nástroj má proměnnou ve formátu <option><NÁZEVNÁSTROJE>_OPTIONS</option> (např. nástroj <application>gtkdoc-mkhtml</application> má volbu nazvanou <code>MKHTML_OPTIONS</code>). Všechny nástroje podporují <option>--help</option> pro vypsání podporovaných přepínačů.</para>
- <itemizedlist>
+ <para>Následující seznam vysvětluje nejpodstatnější volby. Na další volby se podívejte do ukázkového <filename>Makefile.am</filename>. <itemizedlist>
<listitem>
- <para>
- <option>DOC_MODULE</option> is used to provide the name of the
- package that is being documentated (e.g. <code>meeper</code>, or
- <code>libmeep</code>).
- </para>
+ <para><option>DOC_MODULE</option> se používá k poskytnutí názvu balíčku, který je dokumentován (např. <code>meeper</code> nebo <code>libmeep</code>).</para>
</listitem>
<listitem>
- <para>
- <option>DOC_SOURCE_DIR</option>
- is used to specify the location
- of source directory which GTK-Doc searches for your API
- documentation. This will usually be
- <code>
- DOC_SOURCE_DIR=$(top_srcdir)/src
- </code>
- or a sub-directory of that directory.
- </para>
+ <para><option>DOC_SOURCE_DIR</option> se používá k určení umístění zdrojové složky, ve které GTK-Doc hledá dokumentaci API. Obvykle to je <code>DOC_SOURCE_DIR=$(top_srcdir)/src </code> nebo podsložka této složky.</para>
</listitem>
<listitem>
- <para>
- <option>HFILE_GLOB</option>
- and
- <option>CFILE_GLOB</option>
- are used for dependencies. Each option take a file-glob (e.g.
- <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
- The documentation will be rebuilt if any of the matched files
- change.
- </para>
+ <para><option>HFILE_GLOB</option> a <option>CFILE_GLOB</option> se používají pro závislosti. Obě volby přebírají file-glob (např. <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>). Dokumentace se znovu sestaví, když se kterýkoliv z odpovídajících souborů změní.</para>
</listitem>
<listitem>
- <para>
- <option>EXTRA_HFILES</option>
- allows to specify extra header files
- to include when scanning for API documentation, which are not
- found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
- EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
- </para>
+ <para><option>EXTRA_HFILES</option> umožňuje určit dodatečné hlavičkové soubory, které se mají zahrnout při procházení pro dokumentaci k API, a které nejsou k nalezení pod složkou <code>DOC_SOURCE_DIR</code> (např. <code>EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).</para>
</listitem>
<listitem>
- <para>
- <option>IGNORE_HFILES</option>
- allows to specify header files
- or directories to ignore when scanning for API documentation.
- Use the basename of the file or directory (e.g. <code>
- IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
- </para>
+ <para><option>IGNORE_HFILES</option> umožňuje určit dodatečné hlavičkové soubory nebo složky, které se mají ignorovat při procházení pro dokumentaci k API. Použijte základní název ze souboru nebo složky (např. <code>IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).</para>
</listitem>
<listitem>
- <para>
- <option>HTML_IMAGES</option>
- allows to specify images files which
- will be copied into the <filename>html/</filename> directory of
- the generated documentation.
- If your API documentation includes any images they need to be
- added to this
- option (e.g. <code>
- HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
- </para>
+ <para><option>HTML_IMAGES</option> umožňuje určit soubory s obrázky, které se zkopírují do složky <option>html/</option> s generovanou dokumentací. Pokud jsou součástí vaší dokumentace API nějaké obrázky, je třeba je přidat do této volby (např. <code>HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).</para>
</listitem>
<listitem>
- <para>
- <option>content_files</option>
- allows to specify extra files
- that are included by
- <code>$(DOC_MAIN_SGML_FILE)</code>
- (e.g. <code>
- content_files=running.xml building.xml changes-2.0.xml</code>).
- </para>
+ <para><option>content_files</option> umožňuje určit dodatečné soubory, které se mají vložit pomocí <code>$(DOC_MAIN_SGML_FILE)</code> (např. <code>content_files=running.xml building.xml changes-2.0.xml</code>).</para>
</listitem>
<listitem>
- <para>
- <option>expand_content_files</option>
- allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
- <code>#GtkWidget</code>
- are expanded (e.g. <code>
- expand_content_files=running.xml</code>).
- </para>
+ <para><option>expand_content_files</option> umožňuje určit soubory, ve kterých jsou rozvinuty <emphasis>zkratky gtk-doc</emphasis>, jako je třeba <code>#GtkWidget</code> (např. <code>expand_content_files=running.xml</code>).</para>
</listitem>
- </itemizedlist>
- </para>
+ </itemizedlist></para>
</sect2>
<sect2 id="settingup_autoconf">
<title>Integrace s autoconf</title>
- <para>
- Integration with <application>autoconf</application> is very simple
- and includes one required step and an additional optional
- (but recommended) step.
-
- The first step is to add the <function>GTK_DOC_CHECK</function> macro
- to your <filename>configure.ac</filename> script. This registers
- several configure options to enable GTK-Doc and allows you
- to set default arguments for <application>gtkdocize</application>.
- </para>
+ <para>Integrace s <application>autoconf</application> je velmi jednoduchá a skládá se z jednoho povinného kroku a dalšího volitelného (ale doporučeného) kroku. Prvním krokem je přidat makro <function>GTK_DOC_CHECK</function> do skriptu <filename>configure.ac</filename>. Tím se zaregistruje několik konfiguračních voleb, které povolí GTK-Doc a umožní vám nastavit výchozí argumenty pro <application>gtkdocize</application>.</para>
<warning>
- <simpara>
- Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
- The macro must start at the beginning of the line and should not
- start with whitespace.
- </simpara>
+ <simpara>Ujistěte se, že makro <code>GTK_DOC_CHECK</code> není odsazené od kraje. Makro musí začínat na začátku řádku a nesmí začínat bílými znaky.</simpara>
</warning>
- <para>
- The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
- to your <filename>configure.ac</filename>. This is not required
- but helps <application>gtkdocize</application> to automatically copy
- the macro definition (e.g <filename>gtk-doc.m4</filename>) which
- contains the <function>GTK_DOC_CHECK</function> macro to your
- project's macro directory. Without this, the GTK_DOC_CHECK macro
- might not be found and you would need to explicitly tell the
- <application>aclocal</application> tool where to find the macro
- definition file.
- </para>
+ <para>Druhým krokem je přidat do <filename>configure.ac</filename> makro <code>AC_CONFIG_MACRO_DIR(m4)</code>. Není to sice nutné, ale pomůže to <application>gtkdocize</application> automaticky zkopírovat definici makra (např. <filename>gtk-doc.m4</filename>), která obsahuje makro <function>GTK_DOC_CHECK</function>, do složky s makry ve vašem projektu. Bez toho se může stát, že makro <function>GTK_DOC_CHECK</function> nemusí být nalezeno a budete muset nástroji <application>aclocal</application> výslovně uvést, kde soubor s definicí makra najít.</para>
<para>
- <example><title>Minimal integration with autoconf</title>
- <programlisting><![CDATA[
-# recommended: set m4 directory
+ <example><title>Minimální integrace s autoconf</title>
+ <programlisting>
+# doporučeno: nastaví složku m4
AC_CONFIG_MACRO_DIR(m4)
-# optional: register gtk-doc in configure
+# volitelné: zaregistruje gtk-doc v configure
GTK_DOC_CHECK([1.28])
-]]></programlisting>
+</programlisting>
</example>
</para>
- <para>
- The above example works, but will require all developers to have
- gtk-doc installed. A better way is to make building the documentation
- optional as shown in the next example:
-
- <example>
- <title>Integration with optional gtk-doc dependency</title>
- <programlisting><![CDATA[
+ <para>Výše uvedený příklad funguje, ale vyžaduje, aby všichni vývojáři měli nainstalováno gtk-doc. Lepším způsobem je zařídit, aby sestavení dokumentace bylo volitelné, jak je ukázáno v následujícím příkladu: <example>
+ <title>Integrace s volitelnými závislostttmi gtk-doc</title>
+ <programlisting>
m4_ifdef([GTK_DOC_CHECK], [
-# recommended: set m4 directory
+# doporučeno: nastaví složku m4
AC_CONFIG_MACRO_DIR(m4)
-# optional: register gtk-doc in configure
+# volitelné: zaregistruje gtk-doc v configure
GTK_DOC_CHECK([1.28])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
- <para>
- The first argument is used to check for the Gtk-Doc version at
- configure time. The 2nd, optional argument is used by
- <application>gtkdocize</application>.
- The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
- switches:
- </para>
+ <para>První argument se používá ke kontrole verze GTK-Doc 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>
<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>
- After all changes to <filename>configure.ac</filename> are made,
- update the <filename>configure</filename> file. This can be done by
- re-running <code>autogen.sh</code>.
- </para>
+ <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>autogen.sh</code>.</para>
</sect2>
<sect2 id="settingup_autogen">
<title>Integrace s autogen</title>
- <para>
- Most projects will have an <filename>autogen.sh</filename> script to
- setup the build infrastructure after the project was checked out from
- a version control system (such as git or svn). GTK-Doc comes with a
- script called <application>gtkdocize</application> which can be used
- to copy the necessary files needed by Gtk-Doc to the source directory.
- </para>
+ <para>Většina projektů má skript <filename>autogen.sh</filename>, který po stažení projektu ze systému pro správu verzí (jako je Git nebo SVN), nastaví infrastrukturu pro sestavení. GTK-Doc se dodává se skriptem nazvaným <application>gtkdocize</application>, který lze použít ke zkopírování nezbytných souborů požadovaných GTK-Doc do zdrojové složky.</para>
- <para>
- It should be run before autoreconf, autoheader, automake or autoconf.
- </para>
+ <para>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>
<para>
<example>
- <title>Conditionally run gtkdocize from autogen.sh</title>
- <programlisting><![CDATA[
-GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+ <title>Podmíněné spuštění gtkdocize z autogen.sh</title>
+ <programlisting>
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
if test $? -ne 0; then
echo "No gtk-doc support found. You can't build the docs."
else
$GTKDOCIZE || exit 1
fi
-]]></programlisting>
+</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).
- </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>.</para>
- <para>
- <application>gtkdocize</application> checks your
- <filename>configure.ac</filename> script for
- the <function>GTK_DOC_CHECK</function> macro.
- The <function>GTK_DOC_CHECK</function> macro can be used to pass
- extra arguments to the <application>gtkdocize</application> script.
- the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
- </para>
+ <para><filename>gtkdocize</filename> kontroluje váš skript <filename>configure.ac</filename> ohledně makra <function>GTK_DOC_CHECK</function>. Toto makro můžete použít k předání dalších parametrů do skriptu <application>gtkdocize</application>. Konkrétně k tomu slouží druhý argument makra.</para>
- <para>
- Alternatively, additional arguments can also be passed to
- <application>gtkdocize</application> via the
- <function>GTKDOCIZE_FLAGS</function> environment variable, or by
- directly specifying them to <application>gtkdocize</application>
- in <filename>autogen.sh</filename>.
- </para>
+ <para>Alternativně lze další argumenty skriptu <application>gtkdocize</application> předat přes proměnnou prostředí <function>GTKDOCIZE_FLAGS</function> nebo je zadat přímo za volání <application>gtkdocize</application> v <filename>autogen.sh</filename>.</para>
</sect2>
<sect2 id="settingup_firstrun">
- <title>Executing GTK-Doc from the Build System</title>
+ <title>Spouštění GTK-Doc ze sestavovacího systému</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>
</example>
</para>
- <para>
- Now you can point your browser to
- <filename>docs/reference/<package>/index.html</filename>.
- With this initial setup you will only see a very simple document.
- The next chapter will teach you how to add API documentation to your
- code via special comment blocks. The Chapter afterwards introduces
- <link linkend="metafiles">additional files</link> and shows how to
- edit the <link linkend="metafiles_master">master template</link> to
- add additional chapters and sections to your documentation files.
- </para>
+ <para>Nyní si můžete ve svém webovém prohlížeči zobrazit <filename>docs/reference/<package>/index.html</filename>. S tímto počátečním nastavením uvidíte jen velmi jednoduchý dokument. Následující kapitola vás naučí, jak do svého zdrojového kódu přidat dokumentaci k API pomocí speciálních komentářových bloků. Dále pak kapitola seznamuje s <link linkend="metafiles">dodatečnými soubory</link> a ukazuje, jak upravit <link linkend="metafiles_master">hlavní šablonu</link>, abyste do svých souborů s dokumentací dostali doplňující kapitoly a oddíly.</para>
</sect2>
<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>
- <para>
- The GTK-Doc scanner can handle the majority of C headers fine. In the
- case of receiving warnings from the scanner that look like a special
- case, one can hint GTK-Doc to skip over them.
- <example><title>GTK-Doc comment block</title>
- <programlisting><![CDATA[
+ <para>Skener GTK-Doc 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__
-/* unparseable code here */
+/* kód zde se nezpracovává */
#endif
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
<note>
<title>Omezení</title>
<para>Více příkladů k podporovaným značkám Markdown můžete najít v <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">Referenční příručce k syntaxi Markdown pro dokumentaci GTK+</ulink>.</para>
<tip>
- <para>
- As already mentioned earlier GTK-Doc is for documenting public API. Thus
- one cannot write documentation for static symbols. Nevertheless it is good
- to comment those symbols too. This helps other developers to understand
- your code.
- Therefore we recommend to comment these using normal comments (without the
- 2nd '*' in the first line).
- If later the function needs to be made public, all one needs to do is to
- add another '*' in the comment block and insert the symbol name at the
- right place inside the sections file.
- </para>
+ <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 vývojářů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>
</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>
+ To include example code:
+ <informalexample>
+ <programlisting><![CDATA[
+<example>
+ <title>Using a GHashTable.</title>
+ <programlisting language="C">
+ ...
+ </programlisting>
+</example>
+]]></programlisting>
+ </informalexample>
+ or possibly this, for very short code fragments which don't need a title:
+ <informalexample>
+ <programlisting><![CDATA[
+<informalexample>
+ <programlisting language="C">
+ ...
+ </programlisting>
+</informalexample>
+]]></programlisting>
+ </informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
+ For the latter GTK-Doc also supports an abbreviation:
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
+ ...
+]|
+]]></programlisting>
+ </informalexample>
+ </para>
<para>Vložení seznamu s odrážkami: <informalexample>
<programlisting>
<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>Example <package>.types file</title>
+ <example><title>Příklad souboru <balíček>.types</title>
<programlisting>
#include <gtk/gtk.h>
<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
- in the master template and how the entities are used.
- The entities can also be used in all
- generated files, GTK-Doc will use the same xml header in generated xml
- files.
- <example><title>Use pre-generated entities</title>
- <programlisting><![CDATA[
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ <para>Soubory Makefile dodávané s touto verzí generují do <filename>xml/gtkdocentities.ent</filename> soubor s entitami, který obsahuje entity například pro package_name a package_version. Můžete je použít třeba v hlavním souboru XML, abyste nemuseli mít číslo verze zapsané natvrdo. Níže je uveden příklad, jak soubor s entitami vložit do hlavní šablony a jak entity použít. Použít je lze také ve všech generovaných souborech, GTK-Doc bude používat tu samou hlavičku XML v generovaných souborech XML. <example><title>Používání předgenerovaných entit</title>
+ <programlisting>
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"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>&Referenční příručka k package_name;</title>
+ <releaseinfo>
+ for &package_string;.
+ Nejnovější verzi této dokumentace můžete najít on-line na
+ <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
+ </releaseinfo>
+ </bookinfo>
+</programlisting>
+ </example></para>
</sect1>
</chapter>
# German translation of the gtk-doc manual.
-# Mario Blättermann <mario.blaettermann@gmail.com>, 2009-2010, 2012-2013, 2016.
+# Mario Blättermann <mario.blaettermann@gmail.com>, 2009-2010, 2012-2013, 2016, 2018.
# Wolfgang Stöggl <c72578@yahoo.de>, 2015.
-# Christian Kirbach <christian.kirbach@gmail.com>, 2013, 2015.
+# Christian Kirbach <christian.kirbach@gmail.com>, 2013, 2015, 2018.
#
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc help master\n"
-"POT-Creation-Date: 2018-05-20 18:37+0000\n"
-"PO-Revision-Date: 2018-08-09 18:25+0200\n"
-"Last-Translator: Tim Sabsch <tim@sabsch.com>\n"
+"POT-Creation-Date: 2018-10-03 08:17+0000\n"
+"PO-Revision-Date: 2019-03-25 01:57+0100\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 2.0.9\n"
+"X-Generator: Poedit 2.2.1\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, 2016\n"
-"Christian Kirbach <christian.kirbach@gmail.com>, 2013, 2015, 2016, 2017, 2018"
+"Mario Blättermann <mario.blaettermann@gmail.com>, 2009-2013, 2016, 2018\n"
+"Christian Kirbach <christian.kirbach@gmail.com>, 2013, 2015-2019"
#. (itstool) path: bookinfo/title
#: C/index.docbook:12
#. (itstool) path: revhistory/revision
#: C/index.docbook:83
msgid ""
-"<revnumber>1.2
8.1</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
+"<revnumber>1.2
9.1</revnumber> <date>28 Aug 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>development</revremark>"
msgstr ""
-"<revnumber>1.28.1</revnumber> <date>24. März 2018</date> <authorinitials>ss</"
-"authorinitials> <revremark>Entwicklerversion</revremark>"
+"<revnumber>1.29.1</revnumber> <date>28. August 2018</date> "
+"<authorinitials>ss</authorinitials> <revremark>Entwicklerversion</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
msgid ""
+"<revnumber>1.29</revnumber> <date>28 Aug 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>development</revremark>"
+msgstr ""
+"<revnumber>1.29</revnumber> <date>28. August 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>Entwicklerversion</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+msgid ""
"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
msgstr ""
"authorinitials> <revremark>Fehlerbehebungen</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
msgid ""
"<revnumber>1.27</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>fine tuning of the python port</revremark>"
"Portierung</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
+#: C/index.docbook:107
msgid ""
"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>port all tools from perl/bash to python</"
"nach Python portiert</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:107
+#: C/index.docbook:113
msgid ""
"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
"authorinitials> <revremark>Fehlerbehebungen, Test-Cleanups</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:113
+#: C/index.docbook:119
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>Fehlerbehebungen</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:119
+#: C/index.docbook:125
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:125
+#: C/index.docbook:131
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:131
+#: C/index.docbook:137
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:137
+#: C/index.docbook:143
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:143
+#: C/index.docbook:149
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:149
+#: C/index.docbook:155
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:155
+#: C/index.docbook:161
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:161
+#: C/index.docbook:167
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:167
+#: C/index.docbook:173
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:173
+#: C/index.docbook:179
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:179
+#: C/index.docbook:185
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:185
+#: C/index.docbook:191
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:191
+#: C/index.docbook:197
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:204
+#: C/index.docbook:210
msgid "Introduction"
msgstr "Einführung"
#. (itstool) path: chapter/para
-#: C/index.docbook:206
+#: C/index.docbook:212
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:212
+#: C/index.docbook:218
msgid "What is GTK-Doc?"
msgstr "Was ist GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:214
+#: C/index.docbook:220
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:222
+#: C/index.docbook:228
msgid "How Does GTK-Doc Work?"
msgstr "Wie funktioniert GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:224
+#: C/index.docbook:230
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:231
+#: C/index.docbook:237
msgid ""
"GTK-Doc consists of a number of python scripts, each performing a different "
"step in the process."
"bestimmten Schritt in dem Prozess ausführt."
#. (itstool) path: sect1/para
-#: C/index.docbook:236
+#: C/index.docbook:242
msgid "There are 5 main steps in the process:"
msgstr "Dieser Vorgang umfasst fünf Hauptschritte:"
#. (itstool) path: listitem/para
-#: C/index.docbook:243
+#: C/index.docbook:249
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)."
+"source files with the documentation for each function, macro, structs or "
+"unions, etc."
msgstr ""
"<guilabel>Schreiben der Dokumentation.</guilabel> Der Autor ergänzt die "
-"Quelldateien um die Dokumentation für jede Funktion, jedes Makro usw. In der "
-"Vergangenheit wurden diese Informationen in erstellte Vorlagendateien "
-"eingegeben. Dies wird nicht mehr empfohlen."
+"Quelldateien um die Dokumentation für jede Funktion, jedes Makro usw."
#. (itstool) path: listitem/para
-#: C/index.docbook:253
+#: C/index.docbook:258
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:270
+#: C/index.docbook:275
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:276
+#: C/index.docbook:281
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:283
+#: C/index.docbook:288
msgid ""
"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
"mkdb</application> turns the template files into XML files in the <filename "
"introspection-Daten gelesen."
#. (itstool) path: listitem/para
-#: C/index.docbook:292
+#: C/index.docbook:297
msgid ""
"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
"in ein PDF-Dokument namens <filename><package>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:298
+#: C/index.docbook:303
msgid ""
"Files in <filename class=\"directory\">xml/</filename> and <filename class="
"\"directory\">html/</filename> directories are always overwritten. One "
"sollte diese direkt bearbeiten."
#. (itstool) path: listitem/para
-#: C/index.docbook:306
+#: C/index.docbook:311
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:324
+#: C/index.docbook:329
msgid "Getting GTK-Doc"
msgstr "GTK-Doc bekommen"
#. (itstool) path: sect2/title
-#: C/index.docbook:327
+#: C/index.docbook:332
msgid "Requirements"
msgstr "Erfordernisse"
#. (itstool) path: sect2/para
-#: C/index.docbook:328
+#: C/index.docbook:333
msgid ""
"<guilabel>python 2/3</guilabel> - the main scripts are written in python."
msgstr ""
"geschrieben."
#. (itstool) path: sect2/para
-#: C/index.docbook:331
+#: C/index.docbook:336
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:335
+#: C/index.docbook:340
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:339
+#: C/index.docbook:344
msgid ""
"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
"<guilabel>vim</guilabel> - optional - für Syntax-Hervorhebung von Beispielen"
#. (itstool) path: sect1/title
-#: C/index.docbook:347
+#: C/index.docbook:352
msgid "About GTK-Doc"
msgstr "Info zu GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:349 C/index.docbook:363
+#: C/index.docbook:354
+msgid ""
+"Historically GTK-Doc was used to generate template files from the sources "
+"code. These template files could be used by developers to enter the API "
+"documentation. This approach was rather inconvenient because it required to "
+"keep the generated files under version control. Since GTK-Doc 1.9 it became "
+"possible to place all API information into source comments, which made the "
+"template support obsolete. In version 1.26 template support has been removed."
+msgstr ""
+"In der Vergangenheit wurde GTK-Doc zur Erstellung von Vorlagendateien aus "
+"dem Quellcode verwendet. Diese Vorlagendateien konnten von Entwicklern zur "
+"Eingabe der API-Dokumentation verwendet werden. Jedoch war dieser Ansatz "
+"eher unbequem, weil die erzeugten Dateien unter Versionskontrolle gehalten "
+"werden mussten. Ab GTK-Doc 1.9 wurde es möglich, sämtliche API-Informationen "
+"in Quellcode-Kommentaren zu platzieren, wodurch die Unterstützung für "
+"Vorlagen obsolet wurde. In der Version 1.26 wurde die Vorlagenunterstützung "
+"gänzlich entfernt."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:364 C/index.docbook:378
msgid "(FIXME)"
msgstr "(FIXME)"
#. (itstool) path: sect1/para
-#: C/index.docbook:353
+#: C/index.docbook:368
msgid ""
-"(History, authors, web pages, mailing list, license, future plans, "
-"comparison with other similar systems.)"
+"(authors, web pages, mailing list, license, future plans, comparison with "
+"other similar systems.)"
msgstr ""
-"(Geschichte, Autoren, Webseiten, Mailingliste, Lizenz, Zukunftspläne, "
-"Vergleich mit ähnlichen Systemen)"
+"(Autoren, Webseiten, Mailingliste, Lizenz, Zukunftspläne, Vergleich mit "
+"ähnlichen Systemen)"
#. (itstool) path: sect1/title
-#: C/index.docbook:361
+#: C/index.docbook:376
msgid "About this Manual"
msgstr "Über dieses Handbuch"
#. (itstool) path: sect1/para
-#: C/index.docbook:367
+#: C/index.docbook:382
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
-msgid "Setting up your project"
-msgstr "Einrichten Ihres Projekts"
+#: C/index.docbook:391
+msgid "Project Setup"
+msgstr "Einrichtung in einem Projekt"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:393
+msgid ""
+"This Chapter describes the steps that are necessary to integrate GTK-Doc "
+"into your project. The integration of GTK-Doc into a project includes the "
+"following steps:"
+msgstr ""
+"Dieses Kapitel beschreibt die notwendigen Schritte, um GTK-Doc in Ihr "
+"Projekt zu integrieren. Im einzelnen sind dies folgende Schritte:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:401
+msgid ""
+"Preparation of the directory structure and creating required configuration "
+"files for your GTK-Doc documentation (see <link linkend=\"settingup_docfiles"
+"\"> Setting up a skeleton documentation</link>)."
+msgstr ""
+"Vorbereitung der Ordnerstruktur und Erstellung der erforderlichen "
+"Konfigurationsdateien für Ihre GTK-Doc-Dokumentation (siehe <link linkend="
+"\"settingup_docfiles\">Einrichten des Grundgerüsts der Dokumentation</link>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:409
+msgid ""
+"Adjusting the build system to build your documentation using the GTK-Doc "
+"tools. Multiple build systems are supported, in this manual we describe how "
+"to integrate GTK-Doc with <link linkend=\"settingup_autotools\">Autotools</"
+"link>, <link linkend=\"settingup_cmake\">CMake</link>, and <link linkend="
+"\"settingup_plain_makefiles\">plain Makefiles</link>."
+msgstr ""
+"Anpassen des Erstellungssystems, so dass Ihre Dokumentation durch die "
+"Werkzeuge von GTK-Doc erstellt wird. Es werden mehrere Erstellungssysteme "
+"unterstützt. In diesem Handbuch beschreiben wir die Integration von GTK-Doc "
+"in <link linkend=\"settingup_autotools\">Autotools</link>, <link linkend="
+"\"settingup_cmake\">CMake</link> und <link linkend="
+"\"settingup_plain_makefiles\">einfache Makefiles</link>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:419
+msgid ""
+"Adding GTK-Doc specific files to version control and deciding which files to "
+"ignore (see <link linkend=\"settingup_vcs\"> Integration with version "
+"control systems</link>)."
+msgstr ""
+"Hinzufügen GTK-Doc-spezifischer Dateien zur Versionsverwaltung, wobei zu "
+"entscheiden ist, welche Dateien ignoriert werden sollen (siehe <link linkend="
+"\"settingup_vcs\">Integration in Versionsverwaltungssysteme</link>)."
#. (itstool) path: chapter/para
-#: C/index.docbook:378
-msgid ""
-"The next sections describe what steps to perform to integrate GTK-Doc into "
-"your project. Theses sections assume we work on a project called 'meep'. "
-"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 ""
-"Die nächsten Abschnitte beschreiben die notwendigen Schritte, um GTK-Doc in "
-"Ihr Projekt zu integrieren. Nehmen wir an, wir arbeiten an einem Projekt "
-"namens »meep«. Das Projekt enthält eine Bibliothek namens »libmeep« sowie "
-"eine Endbenutzer-Anwendung namens »meeper«. Weiterhin gehen wir davon aus, "
-"dass wir autoconf und automake verwenden. Zusätzlich beschreibt der "
-"Abschnitt <link linkend=\"plain_makefiles\">Klartext-Makefiles oder andere "
-"Erstellungssysteme</link> die Grundlagen für die Arbeit in einer anderen "
-"Erstellungsumgebung."
+#: C/index.docbook:427
+msgid ""
+"The following sections assume we work on a project called <code>meep</code>. "
+"This project contains two packages (or modules), a library called "
+"<code>libmeep</code> and an end-user app called <code>meeper</code>."
+msgstr ""
+"In den folgenden Abschnitten wird ein fiktives Projekt namens <code>meep</"
+"code> angenommen, an dem wir arbeiten. Das Projekt enthält zwei Pakete (oder "
+"Module), eine Bibliothek namens <code>libmeep</code> und eine Endbenutzer-"
+"Anwendung namens <code>meeper</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:389
+#: C/index.docbook:436
msgid "Setting up a skeleton documentation"
msgstr "Einrichten des Grundgerüsts der Dokumentation"
#. (itstool) path: sect1/para
-#: C/index.docbook:391
-msgid ""
-"Under your top-level project directory create folders called docs/reference "
-"(this way you can also have docs/help for end-user documentation). It is "
-"recommended to create another subdirectory with the name of the doc-package. "
-"For packages with just one library this step is not necessary."
-msgstr ""
-"Erstellen Sie in dem Ordner der obersten Ebene des Projekts die Unterordner "
-"namens docs/reference. Auf diese Weise können Sie auch docs/help für die "
-"Endbenutzerdokumentation anlegen. Es ist empfehlenswert, einen weiteren "
-"Unterordner mit dem Namen des Dokumentationspakets anzulegen. Für Pakete, "
-"die nur eine einzige Bibliothek enthalten, ist dieser Schritt nicht "
-"notwendig."
+#: C/index.docbook:438
+msgid ""
+"A common convention is to place documentation into a folder called "
+"<code>docs</code> inside your top-level project directory. We usually "
+"distinguish between <emphasis>reference documentation</emphasis> intended "
+"for developers and an <emphasis>user manual</emphasis> intended for end-"
+"users. Again the convention is to have separate folders for both. We usually "
+"place the reference documentation in a folder named <code>reference</code> "
+"and the end-user manual in a folder named <code>help</code> as. According to "
+"the above convention the documentation for our <code>libmeep</code> package "
+"would be placed into: <code>docs/reference/libmeep</code>. For packages with "
+"just one library or application the documentation could also be placed "
+"directly into <code>docs/reference</code>. It is not mandatory to use the "
+"above convention, but if you choose to use a different directory structure "
+"you must adjust your build system configuration to match your directory "
+"structure."
+msgstr ""
+"Üblicherweise wir die Dokumentation in einem Ordner namens <code>docs</code> "
+"in der obersten Ebene Ihres Projektordners platziert. Wir unterscheiden "
+"stets zwischen der für Entwickler bestimmten "
+"<emphasis>Referenzdokumentation</emphasis> und dem "
+"<emphasis>Benutzerhandbuch</emphasis>, das sich an Endbenutzer richtet. Es "
+"ist wiederum üblich, dass für beide Werke getrennte Ordner verwendet werden. "
+"Wir legen die Referenzdokumentation in einem Ordner namens <code>reference</"
+"code> und das Benutzerhandbuch in <code>help</code>. Nach der oben gennanten "
+"Konvention würde dann die Dokumentation für unser <code>libmeep</code>-Paket "
+"in <code>docs/reference/libmeep</code> platziert werden. Bei Paketen, die "
+"nur eine Bibliothek oder Anwendung enthalten, kann die Dokumentation auch "
+"direkt in <code>docs/reference</code> abgelegt werden. Es ist nicht "
+"obligatorisch, genau nach diesem Schema vorzugehen, aber wenn Sie von dieser "
+"Ordnerstruktur abweichen, müssen Sie die Konfiguration Ihres "
+"Erstellungssystems entsprechend anpassen."
#. (itstool) path: example/title
-#: C/index.docbook:400
-msgid "Example directory structure"
-msgstr "Beispiel für die Ordnerstruktur"
+#: C/index.docbook:469
+msgid "Example directory structure of <emphasis>meep</emphasis> project"
+msgstr "Beispielhafte Ordnerstruktur des <emphasis>meep</emphasis>-Projekts"
#. (itstool) path: example/programlisting
-#: C/index.docbook:401
+#: C/index.docbook:471
#, no-wrap
msgid ""
"\n"
"meep/\n"
" docs/\n"
-" reference/\n"
+" reference/ # reference documentation\n"
" libmeep/\n"
" meeper/\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
"\n"
"meep/\n"
" docs/\n"
-" reference/\n"
+" reference/ # reference documentation\n"
" libmeep/\n"
" meeper/\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:398
-msgid "This can then look as shown below: <_:example-1/>"
-msgstr "Dies kann dann wie nachstehend angezeigt aussehen: <_:example-1/>"
+#: C/index.docbook:463
+msgid ""
+"In the following sections we will assume a directory structure for our "
+"<emphasis>meep</emphasis> project that uses the above conventions. <_:"
+"example-1/>"
+msgstr ""
+"In den folgenden Abschnitten gehen wir für unser <emphasis>meep</emphasis>-"
+"Projekt von einer Ordnerstruktur aus, die die oben genannten Konventionen "
+"berücksichtigt. <_:example-1/>"
#. (itstool) path: sect1/title
+#: C/index.docbook:488
+msgid "Integration with Autotools"
+msgstr "Integration in Autotools"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:489
+msgid ""
+"Integration of GTK-Doc into an autotools-based build system requires the "
+"following steps:"
+msgstr ""
+"Für die Integration von GTK-Doc in ein Autotools-basiertes Projekt sind die "
+"folgenden Schritte auszuführen:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:495
+msgid ""
+"Ensure that <application>gtkdocize</application> is run once before the "
+"<filename>configure</filename> script. If an <filename>autogen.sh</filename> "
+"script is present, adjust it to check for GTK-Doc and add a call to "
+"<application>gtkdocize</application>."
+msgstr ""
+"Stellen Sie sicher, dass <application>gtkdocize</application> einmal vor dem "
+"<filename>configure</filename>-Skript ausgeführt wird. Falls es ein "
+"<filename>autogen.sh</filename>-Skript gibt, passen Sie es so an, dass es "
+"nach GTK-Doc sucht und einen <application>gtkdocize</application>-Aufruf "
+"hinzufügt."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:503
+msgid ""
+"The main purpose of <application>gtkdocize</application> is to make the "
+"<filename>gtk-doc.make</filename> Makefile and the <filename>gtk-doc.m4</"
+"filename> macro definition file available to the build system, either by "
+"copying or linking it into the project."
+msgstr ""
+"Der Hauptzweck von <application>gtkdocize</application> ist die Erstellung "
+"der <filename>gtk-doc.make</filename>-Steuerdatei und der Makro-"
+"Definitionsdatei <filename>gtk-doc.m4</filename> für das Erstellungssystem, "
+"entweder durch Kopieren oder Verlinken im Projekt."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:512
+msgid ""
+"Add the necessary <application>autoconf</application> macros to "
+"<filename>configure.ac</filename> to enable GTK-Doc in your build system to "
+"allow configuration of GTK-Doc via the generated <filename>configure</"
+"filename> script."
+msgstr ""
+"Fügen Sie die notwendigen <application>autoconf</application>-Makros zu "
+"<filename>configure.ac</filename> hinzu, um GTK-Doc in Ihrem "
+"Erstellungssystem zu aktivieren, so dass die Konfiguration von GTK-Doc über "
+"das erzeugte <filename>configure</filename>-Skript erfolgt."
+
+# Das hier verstehe ich nicht so recht...
+# CK: Das Original ist kein richtiges Englisch.
+#. (itstool) path: listitem/para
+#: C/index.docbook:518
+msgid ""
+"Among others with registers the <code>--enable-gtk-doc</code> option with "
+"the <filename>configure</filename> script."
+msgstr ""
+"Unter anderem wird die Option <code>--enable-gtk-doc</code> mit dem "
+"<filename>configure</filename>-Skript registriert."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:524
+msgid ""
+"Create an <application>automake</application> script for each application or "
+"library in your project. In the example used in this documentation this step "
+"applies to both <code>meeper</code> and <code>libmeep</code>."
+msgstr ""
+"Erstellen Sie ein <application>automake</application>-Skript für jede "
+"Anwendung oder Bibliothek in Ihrem Projekt. In dem in dieser Dokumentation "
+"verwendeten Beispiel wird dieser Schritt sowohl auf <code>meeper</code> als "
+"auch <code>libmeep</code> angewendet."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:533
+msgid ""
+"In the following sections, we will perform the above steps in reverse order. "
+"We start with the <application>automake</application> scripts and work our "
+"way up to <filename>configure.ac</filename> and <filename>autogen.sh</"
+"filename>. Then we show how enable Gtk-Doc in the build system and how to "
+"build the documentation."
+msgstr ""
+"In den folgenden Abschnitten führen wir die oben beschriebenen Schritte in "
+"umgekehrter Reihenfolge aus. Wir beginnen mit den <application>automake</"
+"application>-Skripten und arbeiten uns bis hinauf zu <filename>configure.ac</"
+"filename> und <filename>autogen.sh</filename>. Dann zeigen wir, wie GTK-Doc "
+"im Erstellungssystem aktiviert und wie die Dokumentation erstellt wird."
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:543
+msgid "Integration with automake"
+msgstr "Integration in automake"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:545
+msgid ""
+"First copy the <filename>Makefile.am</filename> from the <filename class="
+"\"directory\">examples</filename> sub-directory of the <ulink url=\"https://"
+"gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am\"> gtkdoc-"
+"sources</ulink> to your project's reference documentation directory (e.g. "
+"<filename class=\"directory\">docs/reference/<package></filename>). A "
+"local copy should be available under e.g. <filename>/usr/share/doc/gtk-doc-"
+"tools/examples/Makefile.am</filename>. If you have multiple packages repeat "
+"this for each one."
+msgstr ""
+"Kopieren Sie zunächst die Datei <filename>Makefile.am</filename> aus dem "
+"<filename class=\"directory\">examples</filename>-Unterordner der <ulink url="
+"\"https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am"
+"\">gtkdoc-Quellen</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: note/simpara
+#: C/index.docbook:558
+msgid ""
+"Do not forget to add each <filename>Makefile.am</filename> to the "
+"<function>AC_CONFIG_FILES</function> macro in <filename>configure.ac</"
+"filename>. For <filename>docs/reference/libmeep/Makefile.am</filename> you "
+"will need to add the entry <filename>docs/reference/libmeep/Makefile</"
+"filename> to <function>AC_CONFIG_FILES</function>."
+msgstr ""
+"Vergessen Sie nicht, jedes <filename>Makefile.am</filename> zum Makro "
+"<function>AC_CONFIG_FILES</function> in <filename>configure.ac</filename> "
+"hinzuzufügen. Für <filename>docs/reference/libmeep/Makefile.am</filename> "
+"müssen Sie den Eintrag <filename>docs/reference/libmeep/Makefile</filename> "
+"zu <function>AC_CONFIG_FILES</function> hinzufügen."
+
#. (itstool) path: example/title
-#: C/index.docbook:416 C/index.docbook:423
+#: C/index.docbook:570
+msgid "Example directory structure with <filename>Makefiles.am</filename>"
+msgstr "Beispielhafte Ordnerstruktur mit <filename>Makefiles.am</filename>"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:573
+#, no-wrap
+msgid ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/ # reference documentation\n"
+" libmeep/\n"
+" Makefile.am\n"
+" meeper/\n"
+" Makefile.am\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+msgstr ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/ # reference documentation\n"
+" libmeep/\n"
+" Makefile.am\n"
+" meeper/\n"
+" Makefile.am\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:589
+msgid ""
+"Next, you need to customize the copied Makefiles and provide values for the "
+"various parameters in each <filename>Makefile.am</filename>. All settings "
+"have a comment above them that describes their purpose and how to customize "
+"the setting. Most settings are used to supply extra flags to the respective "
+"tools to which they apply. Every tool has a variable of the form <option><"
+"TOOLNAME>_OPTIONS</option> (e.g. the tool <application>gtkdoc-mkhtml</"
+"application> has an option named <code>MKHTML_OPTIONS</code>). All the tools "
+"support <option>--help</option> to list the supported options."
+msgstr ""
+"Im nächsten Schritt passen Sie die kopierten Makefiles an und geben Werte "
+"für die verschiedenen Parameter in jedem <filename>Makefile.am</filename> "
+"an. 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."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:613
+msgid ""
+"<option>DOC_MODULE</option> is used to provide the name of the package that "
+"is being documentated (e.g. <code>meeper</code>, or <code>libmeep</code>)."
+msgstr ""
+"<option>DOC_MODULE</option> stellt den Namen des Pakets bereit, das "
+"dokumentiert werden soll (z.B. <code>meeper</code> oder <code>libmeep</"
+"code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:620
+msgid ""
+"<option>DOC_SOURCE_DIR</option> is used to specify the location of source "
+"directory which GTK-Doc searches for your API documentation. This will "
+"usually be <code> DOC_SOURCE_DIR=$(top_srcdir)/src </code> or a sub-"
+"directory of that directory."
+msgstr ""
+"<option>DOC_SOURCE_DIR</option> gibt den Ort des Quellordners an, wo GTK-Doc "
+"nach Ihrer API-Dokumentation suchen soll. Üblicherweise ist das <code> "
+"DOC_SOURCE_DIR=$(top_srcdir)/src </code> oder einer von dessen Unterordnern."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:633
+msgid ""
+"<option>HFILE_GLOB</option> and <option>CFILE_GLOB</option> are used for "
+"dependencies. Each option take a file-glob (e.g. <code>HFILE_GLOB="
+"$(top_srcdir)/src/*.c</code>). The documentation will be rebuilt if any of "
+"the matched files change."
+msgstr ""
+"<option>HFILE_GLOB</option> und <option>CFILE_GLOB</option> werden für "
+"Abhängigkeiten verwendet. Jed Option akzeptiert ein file-glob (z.B. "
+"<code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>). Die Dokumentation wird neu "
+"erstellt, wenn sich eine der Dateien ändert."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:645
+msgid ""
+"<option>EXTRA_HFILES</option> allows to specify extra header files to "
+"include when scanning for API documentation, which are not found under "
+"<code>DOC_SOURCE_DIR</code> (e.g. <code> EXTRA_HFILES=$(top_srcdir}/contrib/"
+"extra.h</code>)."
+msgstr ""
+"Mit <option>EXTRA_HFILES</option> können Sie zusätzliche einzuschließende "
+"Header-Dateien angeben, wenn nach API-Dokumentation gesucht wird, falls "
+"diese nicht unter <code>DOC_SOURCE_DIR</code> zu finden ist (z.B. <code> "
+"EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:655
+msgid ""
+"<option>IGNORE_HFILES</option> allows to specify header files or directories "
+"to ignore when scanning for API documentation. Use the basename of the file "
+"or directory (e.g. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h "
+"private_code_folder</code>)."
+msgstr ""
+"Mit <option>IGNORE_HFILES</option> können Sie zu ignorierende Header-Dateien "
+"angeben, wenn nach API-Dokumentation gesucht wird. Verwenden Sie dabei den "
+"Basisnamen der Datei oder des Ordners (z.B. <code> IGNORE_HFILES=gtkdebug.h "
+"gtkintl.h private_code_folder</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:665
+msgid ""
+"<option>HTML_IMAGES</option> allows to specify images files which will be "
+"copied into the <filename>html/</filename> directory of the generated "
+"documentation. If your API documentation includes any images they need to be "
+"added to this option (e.g. <code> HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/"
+"stock_about_24.png</code>)."
+msgstr ""
+"In <option>HTML_IMAGES</option> können Sie Bilder angeben, die in den "
+"<filename>html/</filename>-Ordner der erzeugten Dokumentation kopiert "
+"werden. Falls Ihre API-Dokumentation Bilder enthält, müssen diese zu dieser "
+"Option hinzugefügt werden (z.B. <code> HTML_IMAGES=$(top_srcdir)/gtk/stock-"
+"icons/stock_about_24.png</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:678
+msgid ""
+"<option>content_files</option> allows to specify extra files that are "
+"included by <code>$(DOC_MAIN_SGML_FILE)</code> (e.g. <code> "
+"content_files=running.xml building.xml changes-2.0.xml</code>)."
+msgstr ""
+"In <option>content_files</option> können Sie zusätzliche Dateien angeben, "
+"die in <code>$(DOC_MAIN_SGML_FILE)</code> einbezogen werden sollen (z.B. "
+"<code> content_files=running.xml building.xml changes-2.0.xml</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:689
+msgid ""
+"<option>expand_content_files</option> allows to specify files where "
+"<emphasis>gtk-doc abbreviations</emphasis> such as <code>#GtkWidget</code> "
+"are expanded (e.g. <code> expand_content_files=running.xml</code>)."
+msgstr ""
+"In <option>expand_content_files</option> geben Sie Dateien an, in denen "
+"<emphasis>gtk-doc Abkürzungen</emphasis> wie <code>#GtkWidget</code> "
+"expandiert werden (z.B. <code> expand_content_files=running.xml</code>)."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:607
+msgid ""
+"The following list explains the most relevant options. Check the example "
+"<filename>Makefile.am</filename> for additional options. <_:itemizedlist-1/>"
+msgstr ""
+"In der folgenden Liste werden einige der relevantesten Optionen erläutert. "
+"Im Beispiel für <filename>Makefile.am</filename> finden Sie weitere "
+"Optionen. <_:itemizedlist-1/>"
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:704
msgid "Integration with autoconf"
msgstr "Integration in autoconf"
-#. (itstool) path: sect1/para
-#: C/index.docbook:418
+#. (itstool) path: sect2/para
+#: C/index.docbook:706
+msgid ""
+"Integration with <application>autoconf</application> is very simple and "
+"includes one required step and an additional optional (but recommended) "
+"step. The first step is to add the <function>GTK_DOC_CHECK</function> macro "
+"to your <filename>configure.ac</filename> script. This registers several "
+"configure options to enable GTK-Doc and allows you to set default arguments "
+"for <application>gtkdocize</application>."
+msgstr ""
+"Die Integration in <application>autoconf</application> ist recht einfach. Es "
+"ist nur ein Schritt zwingend erforderlich sowie ein weiterer optional (aber "
+"empfehlenswert). Zunächst fügen Sie das Makro <function>GTK_DOC_CHECK</"
+"function> zu Ihrem <filename>configure.ac</filename> Skript hinzu. Dadurch "
+"werden verschiedene Konfigurationsoptionen zur Aktivierung von GTK-Doc "
+"registriert sowie Standardargumente für <application>gtkdocize</application> "
+"gesetzt."
+
+#. (itstool) path: warning/simpara
+#: C/index.docbook:718
+msgid ""
+"Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented. The "
+"macro must start at the beginning of the line and should not start with "
+"whitespace."
+msgstr ""
+"Achten Sie darauf, dass das <code>GTK_DOC_CHECK</code>-Makro nicht "
+"eingerückt ist. Es muss zwingend am Anfang der Zeile stehen und sollte nicht "
+"mit einem Leerzeichen beginnen."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:725
msgid ""
-"Very easy! Just add one line to your <filename>configure.ac</filename> "
-"script."
-msgstr ""
-"Sehr einfach! Fügen Sie eine Zeile zu Ihrem <filename>configure.ac</"
-"filename>-Skript hinzu."
+"The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code> to your "
+"<filename>configure.ac</filename>. This is not required but helps "
+"<application>gtkdocize</application> to automatically copy the macro "
+"definition (e.g <filename>gtk-doc.m4</filename>) which contains the "
+"<function>GTK_DOC_CHECK</function> macro to your project's macro directory. "
+"Without this, the GTK_DOC_CHECK macro might not be found and you would need "
+"to explicitly tell the <application>aclocal</application> tool where to find "
+"the macro definition file."
+msgstr ""
+"Danach fügen Sie <code>AC_CONFIG_MACRO_DIR(m4)</code> zu Ihrer "
+"<filename>configure.ac</filename>-Datei hinzu. Dies ist nicht zwingend "
+"erforderlich, aber hilft <application>gtkdocize</application> dabei, die "
+"Makrodefinition (e.g <filename>gtk-doc.m4</filename>), welche das Makro "
+"<function>GTK_DOC_CHECK</function> enthält, in den Makro-Ordner Ihres "
+"Projekts zu kopieren. Wenn Sie diesen Schritt auslassen, könnte das Makro "
+"GTK_DOC_CHECK möglicherweise nicht gefunden werden, und Sie müssten den Ort "
+"der Makro-Definitionsdatei explizit für <application>aclocal</application> "
+"angeben."
+
+#. (itstool) path: example/title
+#: C/index.docbook:738
+msgid "Minimal integration with autoconf"
+msgstr "Minimale Integration in autoconf"
#. (itstool) path: example/programlisting
-#: C/index.docbook:424
+#: C/index.docbook:739
#, no-wrap
msgid ""
"\n"
-"# check for gtk-doc\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
msgstr ""
"\n"
-"# check for gtk-doc\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
#. (itstool) path: example/title
-#: C/index.docbook:436
-msgid "Keep gtk-doc optional"
-msgstr "Halten Sie gtk-doc optional"
+#: C/index.docbook:754
+msgid "Integration with optional gtk-doc dependency"
+msgstr "Integration mit optionaler Abhängigkeit zu gtk-doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:437
+#: C/index.docbook:755
#, no-wrap
msgid ""
"\n"
-"# check for gtk-doc\n"
"m4_ifdef([GTK_DOC_CHECK], [\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\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"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
"],[\n"
"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n"
"])\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:431
+#. (itstool) path: sect2/para
+#: C/index.docbook:748
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/>"
+"The above example works, but will require all developers to have gtk-doc "
+"installed. A better way is to make building the documentation optional as "
+"shown in the next example: <_:example-1/>"
msgstr ""
-"Dazu müssen alle Entwickler gtk-doc installiert haben. Wenn es für das "
-"Projekt vertretbar ist, einen optionalen Erstellungsschritt für die api-doc "
-"zu haben, so können Sie es wie im Folgenden lösen. Lassen Sie es so, wie es "
-"ist, weil gtkdocize nach <function>GTK_DOC_CHECK</function> am Anfang einer "
-"Zeile sucht. <_:example-1/>"
+"Das obige Beispiel funktioniert, aber es erfordert, dass alle Entwickler gtk-"
+"doc installiert haben. Eine bessere Lösung ist die optional Erstellung der "
+"Dokumentation, wie das nächste Beispiel zeigt: <_:example-1/>"
-#. (itstool) path: sect1/para
-#: C/index.docbook:448
+#. (itstool) path: sect2/para
+#: C/index.docbook:768
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:"
+"The first argument is used to check for the Gtk-Doc version at configure "
+"time. The 2nd, optional argument is used by <application>gtkdocize</"
+"application>. The <symbol>GTK_DOC_CHECK</symbol> macro also adds several "
+"configure switches:"
msgstr ""
-"Das erste Argument wird zur Überprüfung von gtkdocversion während des "
-"configure-Durchlaufs benutzt. Das zweite, optionale Argument wird von "
+"Das erste Argument wird zur Überprüfung von der Version von GTK-Doc während "
+"des configure-Durchlaufs benutzt. Das zweite, optionale Argument wird von "
"<application>gtkdocize</application> verwendet. Das Makro "
"<symbol>GTK_DOC_CHECK</symbol> fügt verschiedene Schalter für configure "
"hinzu:"
#. (itstool) path: listitem/para
-#: C/index.docbook:454
+#: C/index.docbook:777
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:778
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:779
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:780
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:784
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"erstellte Dokumentation installiert. Dies ergibt für Benutzer durchaus Sinn, "
"aber nicht für Entwickler."
-#. (itstool) path: sect1/para
-#: C/index.docbook:469
-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 ""
-"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."
-
-#. (itstool) path: example/title
-#: C/index.docbook:477
-msgid "Preparation for gtkdocize"
-msgstr "Vorbereitung für gtkdocize"
-
-#. (itstool) path: example/programlisting
-#: C/index.docbook:478
-#, 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:483
+#. (itstool) path: sect2/para
+#: C/index.docbook:792
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>."
+"<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
-msgid "Integration with automake"
-msgstr "Integration in automake"
+"geschieht durch erneutes Ausführen von <code>autogen.sh</code>."
-#. (itstool) path: sect1/para
-#: C/index.docbook:493
-msgid ""
-"First copy the <filename>Makefile.am</filename> from the <filename class="
-"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
-"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 ""
-"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."
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:504
-msgid ""
-"The next step is to edit the settings inside the <filename>Makefile.am</"
-"filename>. All the settings have a comment above that describes their "
-"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 ""
-"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."
-
-#. (itstool) path: sect1/title
-#: C/index.docbook:518
+#. (itstool) path: sect2/title
+#: C/index.docbook:800
msgid "Integration with autogen"
msgstr "Integration in autogen"
-#. (itstool) path: sect1/para
-#: C/index.docbook:520
+#. (itstool) path: sect2/para
+#: C/index.docbook:802
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."
+"the build infrastructure after the project was checked out from a version "
+"control system (such as git or svn). GTK-Doc comes with a script called "
+"<application>gtkdocize</application> which can be used to copy the necessary "
+"files needed by Gtk-Doc to the source directory."
msgstr ""
"Die meisten Projekte dürften über ein <filename>autogen.sh</filename>-Skript "
"verfügen, welches die Build-Infrastruktur nach dem Auschecken aus einem "
-"Versionsverwaltungssystem wie CVS, SVN oder Git erzeugt. GTK-Doc liefert ein "
-"Werkzeug namens <application>gtkdocize</application> mit, das in einem "
-"solchen Skript verwendet werden kann. Es sollte vor autoheader, automake "
-"oder autoconf ausgeführt werden."
+"Versionsverwaltungssystem wie SVN oder Git erzeugt. GTK-Doc liefert ein "
+"Werkzeug namens <application>gtkdocize</application> mit, das zum Kopieren "
+"der für GTK-Doc erforderlichen Dateien in den Quellordner verwendet werden "
+"kann."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:810
+msgid "It should be run before autoreconf, autoheader, automake or autoconf."
+msgstr ""
+"Es sollte vor autoreconf, autoheader, automake oder autoconf ausgeführt "
+"werden."
#. (itstool) path: example/title
-#: C/index.docbook:529
+#: C/index.docbook:815
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:816
#, no-wrap
msgid ""
"\n"
"\n"
"gtkdocize || exit 1\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:536
+#. (itstool) path: example/title
+#: C/index.docbook:824
+msgid "Conditionally run gtkdocize from autogen.sh"
+msgstr "Bedingtes Ausführen von gtkdocize durch autogen.sh"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:825
+#, no-wrap
+msgid ""
+"\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+" echo \"No gtk-doc support found. You can't build the docs.\"\n"
+"else\n"
+" $GTKDOCIZE || exit 1\n"
+"fi\n"
+msgstr ""
+"\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+" echo \"No gtk-doc support found. You can't build the docs.\"\n"
+"else\n"
+" $GTKDOCIZE || exit 1\n"
+"fi\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:836
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>."
+"<option>--docdir</option> option)."
msgstr ""
"Beim Ausführen von <application>gtkdocize</application> wird <filename>gtk-"
"doc.make</filename> in die Wurzel Ihres Projekts oder in jeden anderen durch "
-"die Option <option>--docdir</option> festgelegten Ordner kopiert. Außerdem "
-"wird das configure-Skript daraufhin überprüft, ob <function>GTK_DOC_CHECK</"
-"function> enthalten ist. Dieses Makro kann verwendet werden, um weitere "
-"Parameter an <application>gtkdocize</application> zu übergeben."
+"die Option <option>--docdir</option> festgelegten Ordner kopiert."
-#. (itstool) path: sect1/para
-#: C/index.docbook:545
+#. (itstool) path: sect2/para
+#: C/index.docbook:842
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 ""
-"In früherer Zeit erzeugte GTK-Doc die Vorlagendateien dort, wo die "
-"Entwickler die Dokumentation platzierten. Das stellte sich als nicht optimal "
-"heraus, beispielsweise um generierte Dateien unter Versionskontrolle zu "
-"haben. Seit einigen Versionen kann GTK-Doc auch sämtliche Informationen aus "
-"Quellcode-Kommentaren ermitteln. Seit GTK-Doc 1.9 sind diese Vorlagen nicht "
-"mehr notwendig. Wir ermutigen die Entwickler, die Dokumentation innerhalb "
-"des Codes zu halten. <application>gtkdocize</application> unterstützt nun "
-"die Option <option>--flavour no-tmpl</option>, wodurch ein Makefile gewählt "
-"wird, welches die Verwendung der Vorlagen komplett umgeht. Neben der "
-"Möglichkeit, diese Option direkt beim Befehlsaufruf zu übergeben, kann Sie "
-"auch zu einer Umgebungsvariable namens <symbol>GTKDOCIZE_FLAGS</symbol> "
-"hinzugefügt oder als zweiter Parameter im <symbol>GTK_DOC_CHECK</symbol>-"
-"Makro im Konfigurationsskript aufgeführt werden. Falls Sie niemals Dateien "
-"im Vorlagenordner manuell bearbeitet oder aus älteren GTK-Doc-Versionen "
-"importiert haben, sollten Sie den Ordner löschen, z.B. in der "
-"Versionsverwaltung."
+"<application>gtkdocize</application> checks your <filename>configure.ac</"
+"filename> script for the <function>GTK_DOC_CHECK</function> macro. The "
+"<function>GTK_DOC_CHECK</function> macro can be used to pass extra arguments "
+"to the <application>gtkdocize</application> script. the 2nd parameter in the "
+"<function>GTK_DOC_CHECK</function> macro."
+msgstr ""
+"<application>gtkdocize</application> überprüft das <filename>configure.ac</"
+"filename>-Skript daraufhin, ob <function>GTK_DOC_CHECK</function> enthalten "
+"ist. Dieses Makro kann verwendet werden, um weitere Parameter an "
+"<application>gtkdocize</application> zu übergeben, den zweiten Parameter im "
+"<function>GTK_DOC_CHECK</function>-Makro."
-#. (itstool) path: sect1/title
-#. (itstool) path: example/title
-#: C/index.docbook:562 C/index.docbook:579
-msgid "Running the doc build"
-msgstr "Erstellung der Dokumentation"
+#. (itstool) path: sect2/para
+#: C/index.docbook:851
+msgid ""
+"Alternatively, additional arguments can also be passed to "
+"<application>gtkdocize</application> via the <function>GTKDOCIZE_FLAGS</"
+"function> environment variable, or by directly specifying them to "
+"<application>gtkdocize</application> in <filename>autogen.sh</filename>."
+msgstr ""
+"Alternativ können zusätzliche Argumente auch über die Umgebungsvariable "
+"<function>GTKDOCIZE_FLAGS</function> an <application>gtkdocize</application> "
+"übergeben werden, oder durch direktes Anfügen an <application>gtkdocize</"
+"application> in <filename>autogen.sh</filename>."
-#. (itstool) path: sect1/para
-#: C/index.docbook:564
+#. (itstool) path: sect2/title
+#: C/index.docbook:862
+msgid "Executing GTK-Doc from the Build System"
+msgstr "Aufruf von GTK-Doc aus dem Erstellungssystem heraus"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:864
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 "
"danach <filename>configure</filename> manuell aus, ebenfalls mit dieser "
"Option."
-#. (itstool) path: sect1/para
-#: C/index.docbook:571
+#. (itstool) path: sect2/para
+#: C/index.docbook:871
msgid ""
"The first make run generates several additional files in the doc-"
"directories. The important ones are: <filename><package>.types</"
"package>.types</filename>, <filename><package>-docs.xml</filename> "
"(früher .sgml), <filename><package>-sections.txt</filename>."
+#. (itstool) path: example/title
+#: C/index.docbook:879
+msgid "Running the doc build"
+msgstr "Erstellung der Dokumentation"
+
#. (itstool) path: example/programlisting
-#: C/index.docbook:580
+#: C/index.docbook:880
#, no-wrap
msgid ""
"\n"
"./autogen.sh --enable-gtk-doc\n"
"make\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:586
+#. (itstool) path: sect2/para
+#: C/index.docbook:887
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 ""
-"Nun können Sie <filename>docs/reference/<package>/index.html</"
-"filename> in Ihrem Browser öffnen. Zugegeben, das Ergebnis ist noch ein "
-"wenig enttäuschend. Im nächsten Abschnitt zeigen wir Ihnen, wie Sie die "
-"Seiten mit Leben füllen können."
+"index.html</filename>. With this initial setup you will only see a very "
+"simple document. The next chapter will teach you how to add API "
+"documentation to your code via special comment blocks. The Chapter "
+"afterwards introduces <link linkend=\"metafiles\">additional files</link> "
+"and shows how to edit the <link linkend=\"metafiles_master\">master "
+"template</link> to add additional chapters and sections to your "
+"documentation files."
+msgstr ""
+"Nun können Sie Ihren Browser auf <filename>docs/reference/<package>/"
+"index.html</filename> stellen. Mit dieser initialen Einrichtung werden Sie "
+"allerdings nur ein sehr simples Dokument sehen. Im nächsten Kapitel "
+"erläutern wir, wie Sie API-Dokumentation mittels spezieller Kommentarblöcke "
+"in Ihren Code einbauen können. Das Kapitel danach führt in <link linkend="
+"\"metafiles\">zusätzliche Dateien</link> ein und zeigt, wie die <link "
+"linkend=\"metafiles_master\">Master-Vorlage</link> bearbeitet wird, um "
+"zusätzliche Kapitel und Abschnitte zu Ihren Dokumentationsdateien "
+"hinzuzufügen."
#. (itstool) path: sect1/title
-#: C/index.docbook:594
-msgid "Integration with version control systems"
-msgstr "Integration in Versionsverwaltungssysteme"
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:596
-msgid ""
-"As a rule of thumb, it's the files you edit which should go under version "
-"control. For typical projects it's these files: <filename><package>."
-"types</filename>, <filename><package>-docs.xml</filename> (in the "
-"past .sgml), <filename><package>-sections.txt</filename>, "
-"<filename>Makefile.am</filename>."
-msgstr ""
-"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>."
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:604
-msgid ""
-"Files in the <filename>xml/</filename> and <filename>html/</filename> "
-"directories should not go under version control. Neither should any of the "
-"<filename>.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
-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
-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 ""
-"Für den Fall, dass jemand nicht automake und damit <filename>gtk-doc.mak</"
-"filename> einsetzen will, muss man die gtkdoc-Werkzeuge in eigenen makefiles "
-"(oder andere Werkzeuge) in der richtigen Reihenfolge aufrufen."
-
-#. (itstool) path: example/title
-#: C/index.docbook:621
-msgid "Documentation build steps"
-msgstr "Schritte zur Erstellung der Dokumentation"
-
-#. (itstool) path: example/programlisting
-#: C/index.docbook:622
-#, 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) <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"
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:636
-msgid ""
-"One will need to look at the <filename>Makefile.am</filename> and "
-"<filename>gtk-doc.mak</filename> to pick the extra options needed."
-msgstr ""
-"Man muss sich <filename>Makefile.am</filename> und <filename>gtk-doc.mak</"
-"filename> anschauen, um die zusätzlich notwendigen Optionen herauszusuchen."
-
-#. (itstool) path: sect1/title
-#: C/index.docbook:643
+#: C/index.docbook:903
msgid "Integration with CMake build systems"
msgstr "Integration in CMake-Erstellungssysteme"
#. (itstool) path: sect1/para
-#: C/index.docbook:645
+#: C/index.docbook:905
msgid ""
"GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module (and "
"the corresponding <filename>GtkDocConfigVersion.cmake</filename> module). "
"integrieren können."
#. (itstool) path: example/title
-#: C/index.docbook:655
+#: C/index.docbook:915
msgid "Example of using GTK-Doc from CMake"
msgstr "Beispiel zur Verwendung von GTK-Doc mit CMake"
#. (itstool) path: example/programlisting
-#: C/index.docbook:656
+#: C/index.docbook:916
#, no-wrap
msgid ""
"\n"
" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:653
+#: C/index.docbook:913
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: sect1/title
+#: C/index.docbook:940
+msgid "Integration with plain makefiles or other build systems"
+msgstr "Integration in Klartext-Makefiles oder andere Erstellungssysteme"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:942
+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 ""
+"Für den Fall, dass jemand nicht automake und damit <filename>gtk-doc.mak</"
+"filename> einsetzen will, muss man die gtkdoc-Werkzeuge in eigenen Makefiles "
+"(oder andere Werkzeugen) in der richtigen Reihenfolge aufrufen."
+
+#. (itstool) path: example/title
+#: C/index.docbook:949
+msgid "Documentation build steps"
+msgstr "Schritte zur Erstellung der Dokumentation"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:950
+#, 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) <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"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:964
+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 muss sich <filename>Makefile.am</filename> und <filename>gtk-doc.mak</"
+"filename> anschauen, um die zusätzlich notwendigen Optionen herauszusuchen."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:971
+msgid "Integration with version control systems"
+msgstr "Integration in Versionsverwaltungssysteme"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:973
+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 ""
+"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>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:981
+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: chapter/title
-#: C/index.docbook:681
+#: C/index.docbook:991
msgid "Documenting the code"
msgstr "Dokumentieren des Codes"
#. (itstool) path: chapter/para
-#: C/index.docbook:683
+#: C/index.docbook:993
msgid ""
"GTK-Doc uses source code comment with a special syntax for code "
"documentation. Further it retrieves information about your project structure "
"anderen Quellen geholt. Im nächsten Abschnitt finden Sie umfassende "
"Informationen über die Syntax der Kommentare."
-#. (itstool) path: note/title
-#: C/index.docbook:691
-msgid "Documentation placement"
-msgstr "Platzierung der Dokumentation"
-
-#. (itstool) path: note/para
-#: C/index.docbook:692
-msgid ""
-"In the past most documentation had to be filled into files residing inside "
-"the <filename>tmpl</filename> directory. This has the disadvantages that the "
-"information is often not updated and also that the file tend to cause "
-"conflicts with version control systems."
-msgstr ""
-"In der Vergangenheit wurde die Dokumentation oft in Dateien gespeichert, die "
-"im Ordner <filename>tmpl</filename> liegen. Das hat den Nachteil, dass die "
-"Informationen oft nicht aktualisiert wurden und die Datei tendenziell "
-"Konflikte mit Versionsverwaltungssystemen verursachen kann."
-
-#. (itstool) path: note/para
-#: C/index.docbook:698
-msgid ""
-"The avoid the aforementioned problems we suggest putting the documentation "
-"inside the sources. This manual will only describe this way of documenting "
-"code."
-msgstr ""
-"Um die bereits genannten Probleme zu vermeiden, empfehlen wir, die "
-"Dokumentation innerhalb der Quellen zu halten. In diesem Handbuch wird "
-"ausschließlich dieser Weg des Dokumentierens des Quellcodes beschrieben."
-
#. (itstool) path: example/title
-#: C/index.docbook:709 C/index.docbook:735
+#: C/index.docbook:1004 C/index.docbook:1030
msgid "GTK-Doc comment block"
msgstr "GTK-Doc-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:710
+#: C/index.docbook:1005
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:705
+#: C/index.docbook:1000
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/>"
+"The GTK-Doc scanner can handle the majority of C headers fine. In the case "
+"of receiving warnings from the scanner that look like a special case, one "
+"can hint GTK-Doc to skip over them. <_:example-1/>"
msgstr ""
-"Der Scanner kann mit den meisten C-Kopfdateien umgehen. Im Falle von "
-"Warnungen des Scanners, die wie ein Spezialfall aussehen, kann man GTK-Doc "
-"anweisen diese zu überspringen. <_:example-1/>"
+"Der Scanner von GTK-Doc kann mit den meisten C-Kopfdateien umgehen. Im Falle "
+"von Warnungen des Scanners, die wie ein Spezialfall aussehen, kann man GTK-"
+"Doc anweisen, diese zu überspringen. <_:example-1/>"
#. (itstool) path: note/title
-#: C/index.docbook:719
+#: C/index.docbook:1014
msgid "Limitations"
msgstr "Einschränkungen"
#. (itstool) path: note/para
-#: C/index.docbook:720
+#: C/index.docbook:1015
msgid ""
"Note, that GTK-Doc's supports <code>#ifndef(__GTK_DOC_IGNORE__)</code> but "
"not <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations."
"andere Kombinationen."
#. (itstool) path: sect1/title
-#: C/index.docbook:730
+#: C/index.docbook:1025
msgid "Documentation comments"
msgstr "Kommentare zur Dokumentation"
#. (itstool) path: example/programlisting
-#: C/index.docbook:736
+#: C/index.docbook:1031
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:732
+#: C/index.docbook:1027
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:1040
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:1046
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:1063
msgid ""
"What it is: The name for a class or function can sometimes be misleading for "
"people coming from a different background."
msgstr ""
-"Was es ist: Der Name für eine Klasse oder Funktion kann manchmal Irre "
-"führend sein für Personen, die einen anderen Hintergrund haben."
+"Was es ist: Der Name für eine Klasse oder Funktion kann manchmal irreführend "
+"sein für Personen, die einen anderen Hintergrund haben."
#. (itstool) path: listitem/para
-#: C/index.docbook:774
+#: C/index.docbook:1069
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:1059
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:1084
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:1089
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:1095
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:1100
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:1106
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:1111
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
+#: C/index.docbook:1116
msgid ""
"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
"foo_bar() to refer to a vmethod."
"verweisen und #GObjectClass.foo_bar() für eine vmethod."
#. (itstool) path: sect1/para
-#: C/index.docbook:783
+#: C/index.docbook:1078
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:1125
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:1134
msgid ""
"DocBook can do more than just links. One can also have lists, examples, "
"headings, and images. As of version 1.20, the preferred way is to use a "
"Listenobjekte als Zeilen, die mit einem Gedankenstrich beginnen."
#. (itstool) path: sect1/para
-#: C/index.docbook:850
+#: C/index.docbook:1145
msgid ""
"While markdown is now preferred one can mix both. One limitation here is "
"that one can use docbook xml within markdown, but markdown within docbook "
"verwenden können, während Markdown in DocBook XML nicht unterstützt wird."
#. (itstool) path: sect1/para
-#: C/index.docbook:856
+#: C/index.docbook:1151
msgid ""
"In older GTK-Doc releases, if you need support for additional formatting, "
"you would need to enable the usage of docbook XML tags inside doc-comments "
"die Option <option>--xml-mode</option> (oder <option>--sgml-mode</option>)."
#. (itstool) path: example/title
-#: C/index.docbook:865
+#: C/index.docbook:1160
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:1161
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:905
+#: C/index.docbook:1200
msgid ""
"More examples of what markdown tags are supported can be found in the <ulink "
"url=\"https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown"
"Markdown\">GTK+ Documentation Markdown Syntax Reference</ulink>."
#. (itstool) path: tip/para
-#: C/index.docbook:911
+#: C/index.docbook:1206
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."
+"comment those symbols too. This helps other developers to understand your "
+"code. Therefore we recommend to comment these using normal comments (without "
+"the 2nd '*' in the first line). If later the function needs to be made "
+"public, all one needs to do is to add another '*' in the comment block and "
+"insert the symbol name at the right place inside the sections file."
msgstr ""
"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 "
"Abschnittsdatei einzubauen."
#. (itstool) path: sect1/title
-#: C/index.docbook:925
+#: C/index.docbook:1221
msgid "Documenting sections"
-msgstr "Dokumentieren von Abschnitten"
+msgstr "Dokumentieren in Abschnitten"
#. (itstool) path: sect1/para
-#: C/index.docbook:927
+#: C/index.docbook:1223
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:1231
msgid "Section comment block"
msgstr "Abschnitts-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:936
+#: C/index.docbook:1232
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:955
+#: C/index.docbook:1251
msgid "SECTION:<name>"
msgstr "SECTION:<name>"
#. (itstool) path: listitem/para
-#: C/index.docbook:957
+#: C/index.docbook:1253
msgid ""
"The name links the section documentation to the respective part in the "
"<filename><package>-sections.txt</filename> file. The name given here "
"<filename><package>-sections.txt</filename> entsprechen."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:966
+#: C/index.docbook:1262
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:968
+#: C/index.docbook:1264
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:1271
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:977
+#: C/index.docbook:1273
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:1280
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:986
+#: C/index.docbook:1282
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:1290
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:996
+#: C/index.docbook:1292
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:1298
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1009
+#: C/index.docbook:1305
msgid ""
"Stable - The intention of a Stable interface is to enable arbitrary third "
"parties to develop applications to these interfaces, release them, and have "
"release). Even at a major release, incompatible changes are expected to be "
"rare, and to have strong justifications."
msgstr ""
-"Stabil - Die Absicht einer stabilen Schnittstelle ist es beliebigen Dritten "
-"es zu ermöglichen Anwendungen zu diesen Schnittstellen zu entwickeln, diese "
+"Stabil - Die Absicht einer stabilen Schnittstelle ist es, beliebigen Dritten "
+"es zu ermöglichen, Anwendungen zu diesen Schnittstellen zu entwickeln, diese "
"freizugeben und sich darauf verlassen zu können, dass diese mit allen "
"Unterversionen des Produkts laufen (nach derjenigen, wo die Schnittstelle "
"eingeführt wurde, und innerhalb der gleichen Hauptversion). Selbst bei einer "
"von stark berechtigten."
#. (itstool) path: listitem/para
-#: C/index.docbook:1021
+#: C/index.docbook:1317
msgid ""
"Unstable - Unstable interfaces are experimental or transitional. They are "
"typically used to give outside developers early access to new or rapidly "
msgstr ""
"Instabil - Instabile Schnittstellen sind experimentell oder vorübergehend. "
"Sie werden typischerweise verwendet, um außenstehenden Entwicklern frühen "
-"Zugang zu neuen oder sich schnell ändernder Technologie zu geben, oder um "
+"Zugang zu neuen oder sich schnell ändernden Technologien zu geben, oder um "
"eine Übergangslösung für ein Problem zu liefern, für das eine allgemeinere "
"Lösung erwartet wird. Es werden keine Garantien zu Quell- oder "
"Binärkompatibilität von einer minor-Freigabe zur nächsten gegeben."
#. (itstool) path: listitem/para
-#: C/index.docbook:1033
+#: C/index.docbook:1329
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:1338
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:1300
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:1350
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1056
+#: C/index.docbook:1352
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 ""
-"Die <literal>#include</literal> -Dateien werden im Abschnitt Zusammenfassung "
+"Die <literal>#include</literal> -Dateien werden im Abschnitt »synopsis« "
"angezeigt (eine durch Kommata getrennte Liste). Der globale Wert aus der "
"<link linkend=\"metafiles_sections\">Abschnittsdatei</link> oder von der "
"Befehlszeile wird überschrieben. Dieser Punkt ist optional."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1065
+#: C/index.docbook:1361
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1067
+#: C/index.docbook:1363
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 "
"optional."
msgstr ""
"Das Bild, das am Beginn einer Referenzseite für diesen Abschnitt angezeigt "
-"wird. Meist wird es eine Art Diagramm für visuelle Erscheinungsbild einer "
-"Klasse oder ein Diagramm sein, das die Beziehungen zu anderen Klassen "
+"wird. Meist wird es eine Art Diagramm für das visuelle Erscheinungsbild "
+"einer Klasse oder ein Diagramm sein, das die Beziehungen zu anderen Klassen "
"darstellt. Dieses Objekt ist optional."
#. (itstool) path: tip/para
-#: C/index.docbook:1078
+#: C/index.docbook:1374
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:1383
msgid "Documenting symbols"
msgstr "Dokumentieren von Symbolen"
#. (itstool) path: sect1/para
-#: C/index.docbook:1089
+#: C/index.docbook:1385
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:1393 C/index.docbook:1459
msgid "General tags"
msgstr "Allgemeine Markierungen"
#. (itstool) path: sect2/para
-#: C/index.docbook:1099
+#: C/index.docbook:1395
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:1400
msgid "Versioning Tags"
msgstr "Versionierungs-Markierungen"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1105
+#: C/index.docbook:1401
msgid "Since:"
msgstr "Since:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1107
+#: C/index.docbook:1403
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:1408
msgid "Deprecated:"
msgstr "Deprecated:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1114
+#: C/index.docbook:1410
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
+#: C/index.docbook:1418
msgid ""
"You can also add stability information to all documentation elements to "
"indicate whether API stability is guaranteed for them for all future minor "
"Veröffentlichungen des Projekts garantiert wird."
#. (itstool) path: sect2/para
-#: C/index.docbook:1128
+#: C/index.docbook:1424
msgid ""
"The default stability level for all documentation elements can be set by "
"passing the <option>--default-stability</option> argument to "
"beschriebenen Werte."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1134
+#: C/index.docbook:1430
msgid "Stability Tags"
msgstr "Stabilitäts-Markierungen"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1135
+#: C/index.docbook:1431
msgid "Stability: Stable"
msgstr "Stability: Stable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1137
+#: C/index.docbook:1433
msgid ""
"Mark the element as stable. This is for public APIs which are guaranteed to "
"remain stable for all future minor releases of the project."
"gewährleistet ist."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1144
+#: C/index.docbook:1440
msgid "Stability: Unstable"
msgstr "Stability: Unstable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1146
+#: C/index.docbook:1442
msgid ""
"Mark the element as unstable. This is for public APIs which are released as "
"a preview before being stabilised."
"die als Vorschau vor der endgültigen Stabilisierung gedacht sind."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1152
+#: C/index.docbook:1448
msgid "Stability: Private"
msgstr "Stability: Private"
#. (itstool) path: listitem/para
-#: C/index.docbook:1154
+#: C/index.docbook:1450
msgid ""
"Mark the element as private. This is for interfaces which can be used by "
"tightly coupled modules, but not by arbitrary third parties."
"beliebigen Drittanbietern."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1164
+#: C/index.docbook:1460
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1184 C/index.docbook:1194
+#: C/index.docbook:1480 C/index.docbook:1490
msgid "Annotations"
msgstr "Anmerkungen"
#. (itstool) path: sect2/para
-#: C/index.docbook:1186
+#: C/index.docbook:1482
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"GObjectIntrospection/Annotations\" type=\"http\">Wiki</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1195
+#: C/index.docbook:1491
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1216 C/index.docbook:1245
+#: C/index.docbook:1512 C/index.docbook:1541
msgid "Function comment block"
msgstr "Kommentarblock einer Funktion"
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1518
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:1524
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:1529
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:1514 C/index.docbook:1600
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Bitte denken Sie an: <_:itemizedlist-1/>"
#. (itstool) path: sect2/para
-#: C/index.docbook:1240
+#: C/index.docbook:1536
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:1542
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1267
+#: C/index.docbook:1563
msgid "Function tags"
msgstr "Funktions-Markierungen"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1268 C/index.docbook:1475
+#: C/index.docbook:1564 C/index.docbook:1771
msgid "Returns:"
msgstr "Returns:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1270
+#: C/index.docbook:1566
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:1571
msgid "@...:"
msgstr "@...:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1277
+#: C/index.docbook:1573
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:1583 C/index.docbook:1585
msgid "Property comment block"
msgstr "Property-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1290
+#: C/index.docbook:1586
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1302 C/index.docbook:1321
+#: C/index.docbook:1598 C/index.docbook:1617
msgid "Signal comment block"
msgstr "Signal-Kommentarblock"
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1604
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:1610
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:1618
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1339 C/index.docbook:1340
+#: C/index.docbook:1635 C/index.docbook:1636
msgid "Struct comment block"
msgstr "Struct-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1341
+#: C/index.docbook:1637
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1652
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:1658
msgid ""
"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" "
"it will be considered private automatically and doesn't need to be mentioned "
"erwähnt werden."
#. (itstool) path: sect2/para
-#: C/index.docbook:1368
+#: C/index.docbook:1664
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:1676 C/index.docbook:1677
msgid "Enum comment block"
msgstr "Enum-Kommentarblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1382
+#: C/index.docbook:1678
#, no-wrap
msgid ""
"\n"
"} Something;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1399
+#: C/index.docbook:1695
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:1410
+#: C/index.docbook:1706
msgid "Inline program documentation"
msgstr "Eingebettete Programmdokumentation"
#. (itstool) path: sect1/para
-#: C/index.docbook:1411
+#: C/index.docbook:1707
msgid ""
"You can document programs and their commandline interface using inline "
"documentation."
"eingebetteter Dokumentation."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1417
+#: C/index.docbook:1713
msgid "Tags"
-msgstr "Schlagwörter"
+msgstr "Markierungen"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1419
+#: C/index.docbook:1715
msgid "PROGRAM"
msgstr "PROGRAM"
#. (itstool) path: listitem/para
-#: C/index.docbook:1422
+#: C/index.docbook:1718
msgid "Defines the start of a program documentation."
-msgstr "Definiert den Start einer Programmdokumentation"
+msgstr "Definiert den Start einer Programmdokumentation."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1429
+#: C/index.docbook:1725
msgid "@short_description:"
msgstr "@short_description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1431
+#: C/index.docbook:1727
msgid "Defines a short description of the program. (Optional)"
msgstr "Definiert eine Kurzbeschreibung des Programms (optional)."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1438
+#: C/index.docbook:1734
msgid "@synopsis:"
msgstr "@synopsis:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1440
+#: C/index.docbook:1736
msgid ""
"Defines the arguments, or list of arguments that the program can take. "
"(Optional)"
"akzeptiert (optional)."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1448
+#: C/index.docbook:1744
msgid "@see_also:"
msgstr "@see_also:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1450
+#: C/index.docbook:1746
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:1457
+#: C/index.docbook:1753
msgid "@arg:"
msgstr "@arg:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1459
+#: C/index.docbook:1755
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:1466
+#: C/index.docbook:1762
msgid "Description:"
msgstr "Description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1468
+#: C/index.docbook:1764
msgid "A longer description of the program."
msgstr "Eine ausführlichere Beschreibung des Programms."
#. (itstool) path: listitem/para
-#: C/index.docbook:1477
-msgid "Specificy what value(s) the program returns. (Optional)"
+#: C/index.docbook:1773
+msgid "Specify 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:1486
+#: C/index.docbook:1782
msgid "Example of program documentation."
msgstr "Beispiel einer Programmdokumentation."
#. (itstool) path: example/title
-#: C/index.docbook:1487
+#: C/index.docbook:1783
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:1488
+#: C/index.docbook:1784
#, no-wrap
msgid ""
"\n"
"}\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1514
+#: C/index.docbook:1810
msgid "Useful DocBook tags"
msgstr "Nützliche DocBook-Markierungen"
#. (itstool) path: sect1/para
-#: C/index.docbook:1516
+#: C/index.docbook:1812
msgid ""
"Here are some DocBook tags which are most useful when documenting the code."
msgstr ""
"von Code nützlich sein können."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1525
+#: C/index.docbook:1821
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1521
+#: C/index.docbook:1817
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. "
"obersten Elements der Seite, auf welche die Verknüpfung zielt (»gtk«, »gdk«, "
"»glib«), danach folgt der Seitentitel (\"Hash Tables\"). Für Widgets ist "
"dies einfach der Klassenname. Leerzeichen und Unterstriche werden SGML/XML-"
-"konform in »-« umgewandelt. "
+"konform in »-« umgewandelt."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1538
+#: C/index.docbook:1834
#, no-wrap
msgid ""
"\n"
"<function>...</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1535
+#: C/index.docbook:1831
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
"<_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1547
+#: C/index.docbook:1843
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1558
+#: C/index.docbook:1854
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1544
+#: C/index.docbook:1840
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:1577
+#: C/index.docbook:1873
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1574
+#: C/index.docbook:1870
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Für eine Liste mit Aufzählungszeichen: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1597
+#: C/index.docbook:1893
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1594
+#: C/index.docbook:1890
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:1610
+#: C/index.docbook:1906
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1607
+#: C/index.docbook:1903
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:1619
+#: C/index.docbook:1915
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1616
+#: C/index.docbook:1912
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:1628
+#: C/index.docbook:1924
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1625
+#: C/index.docbook:1921
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:1637
+#: C/index.docbook:1933
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1634
+#: C/index.docbook:1930
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 ""
-"Um sich auf einen Klassennamen zu beziehen kann man möglicherweise folgendes "
-"verwenden: <_:informalexample-1/> Aber Sie verwenden vermutlich stattdessen "
-"#GtkWidget (um automatisch eine Verknüpfung zur GtkWidget-Seite zu erstellen "
-"- lesen Sie <link linkend=\"documenting_syntax\">die Abkürzungen</link>)."
+"Um sich auf einen Klassennamen zu beziehen, kann man möglicherweise "
+"folgendes verwenden: <_:informalexample-1/> Aber Sie verwenden vermutlich "
+"stattdessen #GtkWidget (um automatisch eine Verknüpfung zur GtkWidget-Seite "
+"zu erstellen - lesen Sie <link linkend=\"documenting_syntax\">die "
+"Abkürzungen</link>)."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1648
+#: C/index.docbook:1944
#, no-wrap
msgid ""
"\n"
"<emphasis>This is important</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1645
+#: C/index.docbook:1941
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Zum Hervorheben von Text: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1657
+#: C/index.docbook:1953
#, no-wrap
msgid ""
"\n"
"<filename>/home/user/documents</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1654
+#: C/index.docbook:1950
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Für Dateinamen: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1666
+#: C/index.docbook:1962
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1663
+#: C/index.docbook:1959
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:1676
+#: C/index.docbook:1972
msgid "Filling the extra files"
msgstr "Füllen der zusätzlichen Dateien"
#. (itstool) path: chapter/para
-#: C/index.docbook:1678
+#: C/index.docbook:1974
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:1687
+#: C/index.docbook:1983
msgid "Editing the types file"
msgstr "Bearbeiten der Typendatei"
#. (itstool) path: sect1/para
-#: C/index.docbook:1689
+#: C/index.docbook:1985
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:1698
-msgid "Example types file snippet"
-msgstr "Beispiel-Schnipsel einer Typen-Datei"
+#: C/index.docbook:1994
+msgid "Example <package>.types file"
+msgstr "Beispiel-Schnipsel einer <package>.types-Datei"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1699
+#: C/index.docbook:1995
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1710
+#: C/index.docbook:2006
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
msgstr ""
"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 "
+"<filename>Makefile.am</filename> hinzu. Wenn Sie so vorgehen, sollten Sie "
"weder Typen-Datei mit veröffentlichen noch diese unter Versionsverwaltung "
"stellen."
#. (itstool) path: sect1/title
-#: C/index.docbook:1719
+#: C/index.docbook:2015
msgid "Editing the master document"
msgstr "Bearbeiten des Master-Dokuments"
#. (itstool) path: sect1/para
-#: C/index.docbook:1721
+#: C/index.docbook:2017
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:1728
+#: C/index.docbook:2024
msgid ""
"While GTK-Doc creates a template master document for you, later runs will "
"not touch it again. This means that one can freely structure the "
"Neuigkeiten eingeführt werden."
#. (itstool) path: tip/para
-#: C/index.docbook:1738
+#: C/index.docbook:2034
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:1747
+#: C/index.docbook:2043
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:1754
+#: C/index.docbook:2050
msgid "Master document header"
msgstr "Kopfzeile des Master-Dokuments"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1755
+#: C/index.docbook:2051
#, no-wrap
msgid ""
"\n"
" <title>[Insert title here]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1771
+#: C/index.docbook:2067
msgid ""
"In addition a few option elements are created in commented form. You can "
"review these and enable them as you like."
"können sich diese anschauen und aktivieren, wenn Sie wollen."
#. (itstool) path: example/title
-#: C/index.docbook:1777
+#: C/index.docbook:2073
msgid "Optional part in the master document"
msgstr "Optionaler Teil im Master-Dokument"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1778
+#: C/index.docbook:2074
#, no-wrap
msgid ""
"\n"
" --> \n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1786
+#: C/index.docbook:2082
msgid ""
"Finally you need to add new section whenever you introduce one. The <link "
"linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> tool will remind "
"in der Dokumentation noch nicht erfasst sind."
#. (itstool) path: example/title
-#: C/index.docbook:1794 C/index.docbook:1829
+#: C/index.docbook:2090 C/index.docbook:2125
msgid "Including generated sections"
msgstr "Einbeziehen erzeugter Abschnitte"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1795
+#: C/index.docbook:2091
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1807
+#: C/index.docbook:2103
msgid "Editing the section file"
msgstr "Bearbeiten der Abschnittsdatei"
#. (itstool) path: sect1/para
-#: C/index.docbook:1809
+#: C/index.docbook:2105
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:1815
+#: C/index.docbook:2111
msgid ""
"The section file is a plain text file with tags delimiting sections. Blank "
"lines are ignored and lines starting with a '#' are treated as comment lines."
"die mit »#« beginnen, werden als Kommentarzeilen behandelt."
#. (itstool) path: note/para
-#: C/index.docbook:1822
+#: C/index.docbook:2118
msgid ""
"While the tags make the file look like xml, it is not. Please do not close "
"tags like <SUBSECTION>."
"trügt. Bitte schließen Sie keine Markierungen wie <SUBSECTION>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1830
+#: C/index.docbook:2126
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1847
+#: C/index.docbook:2143
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"Kleinbuchstaben)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1859
+#: C/index.docbook:2155
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:1866
+#: C/index.docbook:2162
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"(Variablen, vmethods)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1885
+#: C/index.docbook:2181
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:1899
+#: C/index.docbook:2195
msgid "Controlling the result"
msgstr "Überprüfung des Ergebnisses"
#. (itstool) path: chapter/para
-#: C/index.docbook:1901
+#: C/index.docbook:2197
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:1910
+#: C/index.docbook:2206
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:1919
+#: C/index.docbook:2215
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:1926
+#: C/index.docbook:2222
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:1934
+#: C/index.docbook:2230
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:1941
+#: C/index.docbook:2237
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:1950
+#: C/index.docbook:2246
msgid ""
"If the project is GObject based, one can also look into the files produced "
"by the object scanner: <filename><package>.args.txt</filename>, "
"ausführen."
#. (itstool) path: chapter/title
-#: C/index.docbook:1965
+#: C/index.docbook:2261
msgid "Modernizing the documentation"
msgstr "Die Dokumentation modernisieren"
#. (itstool) path: chapter/para
-#: C/index.docbook:1967
+#: C/index.docbook:2263
msgid ""
"GTK-Doc has been around for quite some time. In this section we list new "
"features together with the version since when it is available."
"wir neue Features und die Version, mit der sie eingeführt wurden."
#. (itstool) path: sect1/title
-#: C/index.docbook:1973
+#: C/index.docbook:2269
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1975
+#: C/index.docbook:2271
msgid ""
"When using xml instead of sgml, one can actually name the master document "
"<filename><package>-docs.xml</filename>."
"<filename><package>-docs.xml</filename> nennen."
#. (itstool) path: sect1/para
-#: C/index.docbook:1980
+#: C/index.docbook:2276
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-sections</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"Abschnittsdatei sehr einfach aktualisiert werden."
#. (itstool) path: sect1/para
-#: C/index.docbook:1991
+#: C/index.docbook:2287
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"die Sache ist erledigt."
#. (itstool) path: sect1/title
-#: C/index.docbook:2003
+#: C/index.docbook:2299
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:2005
+#: C/index.docbook:2301
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"soll."
#. (itstool) path: sect1/title
-#: C/index.docbook:2016
+#: C/index.docbook:2312
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:2022
+#: C/index.docbook:2318
msgid "Enable gtkdoc-check"
msgstr "gtkdoc-check einschalten"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2023
+#: C/index.docbook:2319
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2018
+#: C/index.docbook:2314
msgid ""
"This version includes a new tool called gtkdoc-check. This tool can run a "
"set of sanity checks on your documentation. It is enabled by adding these "
"<filename>Makefile.am</filename> hinzu. <_:example-1/>"
#. (itstool) path: sect1/title
-#: C/index.docbook:2036
+#: C/index.docbook:2332
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:2038
+#: C/index.docbook:2334
msgid ""
"Version 1.18 brought some initial markdown support. Using markdown in doc "
"comments is less intrusive than writing docbook xml. This version improves a "
"\">Kommentarsyntax</link>."
#. (itstool) path: sect1/title
-#: C/index.docbook:2048
+#: C/index.docbook:2344
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:2058
+#: C/index.docbook:2355
msgid "Use pre-generated entities"
msgstr "Vorerzeugte Entitäten verwenden"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2059
+#: C/index.docbook:2356
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2050
+#: C/index.docbook:2346
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/>"
+"the entity file is included in the master template and how the entities are "
+"used. The entities can also be used in all generated files, GTK-Doc will use "
+"the same xml header in generated xml files. <_:example-1/>"
msgstr ""
"Die in dieser Version enthaltenen Make-Steuerdateien erzeugen die "
"Entitätsdatei <filename>xml/gtkdocentities.ent</filename>, die Entitäten für "
"die gleichen XML-Kopfeinträge auch in generierten Dateien. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:2084
+#: C/index.docbook:2381
msgid "Documenting other interfaces"
msgstr "Dokumentieren anderer Schnittstellen"
#. (itstool) path: chapter/para
-#: C/index.docbook:2086
+#: C/index.docbook:2383
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:2093
+#: C/index.docbook:2390
msgid "Command line options and man pages"
msgstr "Befehlszeilenoptionen und Handbuchseiten"
#. (itstool) path: sect1/para
-#: C/index.docbook:2095
+#: C/index.docbook:2392
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:2102
+#: C/index.docbook:2399
msgid "Document the tool"
msgstr "Dokumentieren des Werkzeuges"
#. (itstool) path: sect2/para
-#: C/index.docbook:2104
+#: C/index.docbook:2401
msgid ""
"Create one refentry file per tool. Following <link linkend="
"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
"Beispiele (z.B. in glib) ansehen."
#. (itstool) path: sect2/title
-#: C/index.docbook:2114
+#: C/index.docbook:2411
msgid "Adding the extra configure check"
msgstr "Hinzufügen der zusätzlichen Configure-Überprüfungen"
#. (itstool) path: example/title
-#: C/index.docbook:2117 C/index.docbook:2135
+#: C/index.docbook:2414 C/index.docbook:2432
msgid "Extra configure checks"
msgstr "Zusätzliche Configure-Überprüfungen"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2118
+#: C/index.docbook:2415
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2132
+#: C/index.docbook:2429
msgid "Adding the extra makefile rules"
msgstr "Hinzufügen der zusätzlichen Makefile-Regeln"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2136
+#: C/index.docbook:2433
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2158
+#: C/index.docbook:2455
msgid "DBus interfaces"
msgstr "DBus-Schnittstellen"
#. (itstool) path: sect1/para
-#: C/index.docbook:2160
+#: C/index.docbook:2457
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:2169
+#: C/index.docbook:2466
msgid "Frequently asked questions"
msgstr "Häufig gestellte Fragen"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2173
+#: C/index.docbook:2470
msgid "Question"
msgstr "Frage"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2174
+#: C/index.docbook:2471
msgid "Answer"
msgstr "Antwort"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2176
+#: C/index.docbook:2473
msgid "No class hierarchy."
msgstr "Keine Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2177
+#: C/index.docbook:2474
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:2183
+#: C/index.docbook:2480
msgid "Still no class hierarchy."
msgstr "Noch immer keine Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2184
+#: C/index.docbook:2481
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:2190
+#: C/index.docbook:2487
msgid "Damn, I have still no class hierarchy."
msgstr "Verdammt, ich habe immer noch keine Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2191
+#: C/index.docbook:2488
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 ""
"Ist der Objektname (Name des Instanz-struct, z.B. <type>GtkWidget</type>) "
-"Teil des normalen Abschnitts (nicht in den Standard- oder Unterabschnitte)."
+"Teil des normalen Abschnitts (nicht in den Standard- oder Unterabschnitten)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2198
+#: C/index.docbook:2495
msgid "No symbol index."
msgstr "Kein Symbolindex."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2199
+#: C/index.docbook:2496
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:2205
+#: C/index.docbook:2502
msgid "Symbols are not linked to their doc-section."
-msgstr "Symbole werden nicht mit deren Dokumentationsbschnitt verknüpft."
+msgstr "Symbole werden nicht mit deren Dokumentationsabschnitt verknüpft."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2206
+#: C/index.docbook:2503
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:2212
+#: C/index.docbook:2509
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:2213
+#: C/index.docbook:2510
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"sgml}</filename>?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2219
+#: C/index.docbook:2516
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:2220
+#: C/index.docbook:2517
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 ""
-"ist doc-comment ordnungsgemäß formatiert? Prüfen Sie den Anfang des "
-"Dokuments auf Rechtschreibfehler im Kommentar. Prüfen Sie ob gtkdoc-fixxref "
+"Ist doc-comment ordnungsgemäß formatiert? Prüfen Sie den Anfang des "
+"Dokuments auf Rechtschreibfehler im Kommentar. Prüfen Sie, ob gtkdoc-fixxref "
"wegen unauflösbarer xrefs warnt. Prüfen Sie, ob das Symbol richtig in "
"<filename><package>-sections.txt</filename> in einem öffentlichen "
"Abschnitt gelistet ist."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2228
+#: C/index.docbook:2525
msgid "A type is missing from the class hierarchy."
msgstr "Ein Typ fehlt in der Klassenhierarchie."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2229
+#: C/index.docbook:2526
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:2238
+#: C/index.docbook:2535
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:2239
+#: C/index.docbook:2536
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:2247
+#: C/index.docbook:2544
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:2248
+#: C/index.docbook:2545
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:2253
+#: C/index.docbook:2550
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "Mehrfache »IDs« für »constraint linkend: XYZ«"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2254
+#: C/index.docbook:2551
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"sections.txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2257
+#: C/index.docbook:2554
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"entspricht."
#. (itstool) path: chapter/title
-#: C/index.docbook:2264
+#: C/index.docbook:2561
msgid "Tools related to gtk-doc"
msgstr "Werkzeuge mit Bezug zu gtk-doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2266
+#: C/index.docbook:2563
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:2271
+#: C/index.docbook:2568
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: blockquote/para
#: C/index.docbook:629 C/fdl-appendix.xml:629
msgid "Copyright YEAR YOUR NAME."
-msgstr "Copyright (c) JAHR IHR NAME."
+msgstr "Copyright (c) JAHR IHR NAME."
#. (itstool) path: blockquote/para
#: C/index.docbook:632
msgstr ""
"Sie dürfen einen Abschnitt <_:quote-1/> hinzufügen, vorausgesetzt, er "
"enthält nichts außer Bewilligungen Ihrer <_:link-2/> von verschiedenen "
-"Seiten -- zum Beispiel Aussagen von Beurteilungen, oder dass der Text von "
+"Seiten – zum Beispiel Aussagen von Beurteilungen, oder dass der Text von "
"einer Organisation als für die autoritäre Definition eines Standards "
"befunden wurde."
"für die entsprechende Seite schon einen Covertext hat, der vorher von Ihnen "
"oder durch Abmachungen von demselben Wesen, in dessen Namen Sie handeln, "
"hinzugefügt wurde, dürfen Sie keinen anderen hinzufügen; aber Sie dürfen den "
-"alten, wenn es der ursprüngliche Veröffentlicher, der den alten hinzugefügt "
-"hat, explizit erlaubt, ersetzen."
+"alten ersetzen, wenn es der ursprüngliche Veröffentlicher, der den alten "
+"hinzugefügt hat, explizit erlaubt."
#. (itstool) path: sect1/para
#: C/fdl-appendix.xml:470
"empfehlen wir, diese Beispiele parallel unter einer freien Software-Lizenz, "
"wie der <_:ulink-1/>, zu veröffentlichen, um ihren Gebrauch in freier "
"Software zu erlauben."
-
-#~ msgid "<guilabel>Python</guilabel> - optional - for gtkdoc-depscan"
-#~ msgstr "<guilabel>Python</guilabel> - optional - für gtkdoc-depscan"
-
-#~ 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"
-
-#~ 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> - Die DTD für DocBook SGML. <ulink "
-#~ "url=\"http://www.ora.com/davenport\" type=\"http\">http://www.ora.com/"
-#~ "davenport</ulink>"
-
-#~ msgid ""
-#~ "<guilabel>Jade v1.1</guilabel> - This is a DSSSL processor for converting "
-#~ "SGML to various formats. <ulink url=\"http://www.jclark.com/jade\" type="
-#~ "\"http\">http://www.jclark.com/jade</ulink>"
-#~ msgstr ""
-#~ "<guilabel>Jade v1.1</guilabel> - Dies ist ein DSSSL-Prozessor zur "
-#~ "Umwandlung von SGML in verschiedene Formate. <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>Modulare DocBook-Stilvorlagen</guilabel> Dies ist der DSSSL-"
-#~ "Code zur Umwandlung von DocBook in HTML und einige andere Formate. Es "
-#~ "wird zusammen mit Jade benutzt. Ich habe den DSSSL-Code in gtk-doc.dsl "
-#~ "etwas angepasst, um die Programmcode-Listings und -Deklarationen "
-#~ "einzufärben und um globale Cross-Reference-Indizes im erzeugten HTML zu "
-#~ "unterstützen. <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> - Wenn Sie man-Hilfeseiten vom "
-#~ "DocBook erstellen möchten. Ich habe die »translation spec« geringfügig "
-#~ "angepasst, um Abschnittüberschriften groß zu schreiben und den Titel »GTK-"
-#~ "bibliothek« oben auf jeder Seite und das Überarbeitungsdatum unten zu "
-#~ "platzieren. Dazu gibt es einen Verweis auf <ulink url=\"http://www.ora."
-#~ "com/davenport\" type=\"http\">http://www.ora.com/davenport</ulink> "
-#~ "HINWEIS: Das funktioniert noch nicht."
-
-#~ msgid ""
-#~ "There is no standard place where the DocBook Modular Stylesheets are "
-#~ "installed."
-#~ msgstr ""
-#~ "Es gibt keinen Standardort, an welchem die Modularen DocBook-Stilvorlagen "
-#~ "installiert werden."
-
-#~ msgid ""
-#~ "GTK-Doc's configure script searches these 3 directories automatically:"
-#~ msgstr ""
-#~ "Das Configure-Skript von GTK-Doc durchsucht folgende drei Ordner "
-#~ "automatisch:"
-
-#~ msgid ""
-#~ "<filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> (used by "
-#~ "RedHat)"
-#~ msgstr ""
-#~ "<filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> "
-#~ "(verwendet von RedHat)"
-
-#~ msgid ""
-#~ "<filename> /usr/lib/dsssl/stylesheets/docbook </filename> (used by Debian)"
-#~ msgstr ""
-#~ "<filename> /usr/lib/dsssl/stylesheets/docbook </filename> (verwendet von "
-#~ "Debian)"
-
-#~ msgid "<filename> /usr/share/sgml/docbkdsl </filename> (used by SuSE)"
-#~ msgstr ""
-#~ "<filename> /usr/share/sgml/docbkdsl </filename> (verwendet von 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 ""
-#~ "Falls sie Stilvorlagen an anderen Orten installiert haben, müssen Sie GTK-"
-#~ "Doc mit folgender Option konfigurieren: <command>--with-dsssl-dir=<"
-#~ "PFAD_ZUM_BASISORDNER_DER_STILVORLAGEN> </command>"
-
-#~ msgid ""
-#~ "You may also want to enable GTK-Doc for the distcheck make target. Just "
-#~ "add the one line shown in the next example to your top-level "
-#~ "<filename>Makefile.am</filename>:"
-#~ msgstr ""
-#~ "Vielleicht möchten Sie auch GTK-Doc für das distcheckmake-Ziel "
-#~ "aktivieren. Fügen Sie dazu den im nächsten Beispiel gezeigten Einzeiler "
-#~ "zur Datei <filename>Makefile.am</filename> der obersten Ebene hinzu:"
-
-#~ msgid "Enable GTK-Doc during make distcheck"
-#~ msgstr "GTK-Doc während »make distcheck« aktivieren"
-
-#~ msgid ""
-#~ "\n"
-#~ "\n"
-#~ "DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc\n"
-#~ "\n"
-#~ " "
-#~ msgstr ""
-#~ "\n"
-#~ "\n"
-#~ "DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc\n"
-#~ "\n"
-#~ " "
-
-#~ msgid ""
-#~ "\n"
-#~ "\n"
-#~ "/**\n"
-#~ " * identifier:\n"
-#~ " *\n"
-#~ " * documentation ...\n"
-#~ " *\n"
-#~ " * # Sub heading #\n"
-#~ " *\n"
-#~ " * more documentation:\n"
-#~ " * - list item 1\n"
-#~ " * - list item 2\n"
-#~ " *\n"
-#~ " * Even more docs.\n"
-#~ " */\n"
-#~ "\n"
-#~ " "
-#~ msgstr ""
-#~ "\n"
-#~ "\n"
-#~ "/**\n"
-#~ " * identifier:\n"
-#~ " *\n"
-#~ " * documentation ...\n"
-#~ " *\n"
-#~ " * # Sub heading #\n"
-#~ " *\n"
-#~ " * more documentation:\n"
-#~ " * - list item 1\n"
-#~ " * - list item 2\n"
-#~ " *\n"
-#~ " * Even more docs.\n"
-#~ " */\n"
-#~ "\n"
-#~ " "
-
-#~ msgid ""
-#~ "Since GTK-Doc-1.18 the tool supports a subset or the <ulink url=\"http://"
-#~ "daringfireball.net/projects/markdown/\">markdown language</ulink>. One "
-#~ "can use it for sub-headings and simple itemized lists. On older GTK-Doc "
-#~ "versions the content will be rendered as it (the list items will appear "
-#~ "in one line separated by dashes). <_:example-1/>"
-#~ msgstr ""
-#~ "Seit GTK-Doc-1.18 unterstützt das Werkzeug eine Teilmenge, d.h. die "
-#~ "<ulink url=\"http://daringfireball.net/projects/markdown/\">markdown "
-#~ "language</ulink>. Man kann sie verwenden für Untertitel und einfache "
-#~ "aufgegliederte Listen. In älteren Versionen von GTK-Doc wird der Inhalt "
-#~ "unverändert dargestellt (Die Listeneinträge erscheinen in einer Zeile "
-#~ "durch Bindestriche getrennt). <_:example-1/>"
-
-#~ msgid "(FIXME : Stability information)"
-#~ msgstr "(FIXME : Stabilitätsinformation)"
-
-#~ msgid ""
-#~ "Also, take a look at GObject Introspection annotation tags: http://live."
-#~ "gnome.org/GObjectIntrospection/Annotations"
-#~ msgstr ""
-#~ "Werfen Sie auch einen Blick auf die »GObject introspection annotation "
-#~ "tags«: http://live.gnome.org/GObjectIntrospection/Annotations"
<para>Wenn die <link linkend="fdl-modified">Modifizierte Version</link> neue wichtige Abschnitte enthält oder Anhänge, die <link linkend="fdl-secondary">Sekundäre Abschnitte</link> darstellen, und kein Material enthalten, das aus dem Dokument kopiert wurde, dürfen Sie nach Ihrer Wahl einige oder alle diese Abschnitte als Unveränderlich bezeichnen. Um dies zu tun, fügen Sie ihre Titel der Liste der <link linkend="fdl-invariant">Unveränderliche Abschnitte</link> in dem Lizenzhinweis der Modifizierten Version hinzu. Diese Titel müssen sich von allen anderen Abschnittstiteln unterscheiden.</para>
- <para>Sie dürfen einen Abschnitt <quote>Billigungen</quote> hinzufügen, vorausgesetzt, er enthält nichts außer Bewilligungen Ihrer <link linkend="fdl-modified">Modifizierte Version</link> von verschiedenen Seiten -- zum Beispiel Aussagen von Beurteilungen, oder dass der Text von einer Organisation als für die autoritäre Definition eines Standards befunden wurde.</para>
+ <para>Sie dürfen einen Abschnitt <quote>Billigungen</quote> hinzufügen, vorausgesetzt, er enthält nichts außer Bewilligungen Ihrer <link linkend="fdl-modified">Modifizierte Version</link> von verschiedenen Seiten – zum Beispiel Aussagen von Beurteilungen, oder dass der Text von einer Organisation als für die autoritäre Definition eines Standards befunden wurde.</para>
- <para>Sie dürfen eine Passage aus bis zu fünf Wörtern als <link linkend="fdl-cover-texts">Vorderseitentext</link> hinzufügen, und eine Passage von bis zu 25 Wörtern als <link linkend="fdl-cover-texts">Rückseitentext</link>, ans Ende der Liste von <link linkend="fdl-cover-texts">Cover-Texte</link> in der <link linkend="fdl-modified">Modifizierte Version</link>. Höchstens eine Passage von Vorderseitentexten und eine von Rückseitentexten darf von (oder durch Abmachungen von) irgendeinem Wesen hinzugefügt werden. Wenn das <link linkend="fdl-document">Dokument</link> für die entsprechende Seite schon einen Covertext hat, der vorher von Ihnen oder durch Abmachungen von demselben Wesen, in dessen Namen Sie handeln, hinzugefügt wurde, dürfen Sie keinen anderen hinzufügen; aber Sie dürfen den alten, wenn es der ursprüngliche Veröffentlicher, der den alten hinzugefügt hat, explizit erlaubt, ersetzen.</para>
+ <para>Sie dürfen eine Passage aus bis zu fünf Wörtern als <link linkend="fdl-cover-texts">Vorderseitentext</link> hinzufügen, und eine Passage von bis zu 25 Wörtern als <link linkend="fdl-cover-texts">Rückseitentext</link>, ans Ende der Liste von <link linkend="fdl-cover-texts">Cover-Texte</link> in der <link linkend="fdl-modified">Modifizierte Version</link>. Höchstens eine Passage von Vorderseitentexten und eine von Rückseitentexten darf von (oder durch Abmachungen von) irgendeinem Wesen hinzugefügt werden. Wenn das <link linkend="fdl-document">Dokument</link> für die entsprechende Seite schon einen Covertext hat, der vorher von Ihnen oder durch Abmachungen von demselben Wesen, in dessen Namen Sie handeln, hinzugefügt wurde, dürfen Sie keinen anderen hinzufügen; aber Sie dürfen den alten ersetzen, wenn es der ursprüngliche Veröffentlicher, der den alten hinzugefügt hat, explizit erlaubt.</para>
<para>Der/die Autor(en) und Veröffentlicher des <link linkend="fdl-document">Dokument</link> erteilen durch diese Lizenz nicht die Erlaubnis, ihre Namen für Veröffentlichungen für Bewilligungen irgendeiner <link linkend="fdl-modified">Modifizierte Version</link> oder deren Durchsetzungen oder Andeutungen zu nutzen.</para>
</sect1>
<para>Um diese Lizenz in einem von Ihnen geschriebenen Dokument nutzen zu können, fügen Sie eine Kopie der Lizenz in das Dokument ein und setzen Sie die folgenden Copyright- und Lizenzhinweise gleich hinter die Titelseite:</para>
<blockquote>
- <para>Copyright (c) JAHR IHR NAME.</para>
+ <para>Copyright (c) JAHR IHR NAME.</para>
<para>Es wird die Erlaubnis gegeben, dieses Dokument zu kopieren, verteilen und/oder zu verändern unter den Bedingungen der GNU Free Documentation License, Version 1.1 oder einer späteren, von der Free Software Foundation veröffentlichten Version; mit den <link linkend="fdl-invariant">Unveränderlichen Abschnitten</link>. DEREN TITEL AUFGEZÄHLT sind, mit den <link linkend="fdl-cover-texts">Vorderseitentexten</link>, die AUFGEZÄHLT sind, und mit den <link linkend="fdl-cover-texts">Rückseitentexten</link>, die AUFGEZÄHLT sind. Eine Kopie dieser Lizenz ist im Abschnitt <quote>GNU Freie Dokumentationslizenz</quote> enthalten.</para>
</blockquote>
</authorgroup>
<publisher role="maintainer"><publishername>GTK-Doc-Projekt</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
<copyright><year>2000, 2005</year> <holder>Dan Mueth und Chris Lyttle</holder></copyright>
- <copyright><year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder></copyright>
+ <copyright>
+ <year>2007-2019</year>
+ <holder>Stefan Sauer (Kost)</holder>
+ </copyright>
<!-- translators: uncomment this:
<copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision><revnumber>1.28</revnumber> <date>24. März 2018</date> <authorinitials>ss</authorinitials> <revremark>Fehlerbehebungen</revremark></revision>
<revision><revnumber>1.27</revnumber> <date>07. Dezember 2017</date>> <authorinitials>ss</authorinitials> <revremark>Detailanpassungen der Python-Portierung</revremark></revision>
<year>2016</year>
+ <year>2018</year>
+
<holder>Mario Blättermann</holder>
</copyright>
<year>2013</year>
- <year>2015</year>
-
- <year>2016</year>
-
- <year>2017</year>
-
- <year>2018</year>
+ <year>2015-2019</year>
<holder>Christian Kirbach</holder>
</copyright>
<orderedlist>
<listitem>
- <para>
- <guilabel>Writing the documentation.</guilabel>
-
- The author fills in the source files with the documentation for each
- function, macro, structs or unions, etc.
- </para>
+ <para><guilabel>Schreiben der Dokumentation.</guilabel> Der Autor ergänzt die Quelldateien um die Dokumentation für jede Funktion, jedes Makro usw.</para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>Info zu GTK-Doc</title>
- <para>
- Historically GTK-Doc was used to generate template files from the soures
- code. These template files could be used by developers to enter the
- API documentation. This approach was rather inconvenient because it
- required to keep the generated files under version control.
- Since GTK-Doc 1.9 it became possible to place all API information
- into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
- </para>
+ <para>In der Vergangenheit wurde GTK-Doc zur Erstellung von Vorlagendateien aus dem Quellcode verwendet. Diese Vorlagendateien konnten von Entwicklern zur Eingabe der API-Dokumentation verwendet werden. Jedoch war dieser Ansatz eher unbequem, weil die erzeugten Dateien unter Versionskontrolle gehalten werden mussten. Ab GTK-Doc 1.9 wurde es möglich, sämtliche API-Informationen in Quellcode-Kommentaren zu platzieren, wodurch die Unterstützung für Vorlagen obsolet wurde. In der Version 1.26 wurde die Vorlagenunterstützung gänzlich entfernt.</para>
<para>(FIXME)</para>
- <para>
- (authors, web pages, mailing list, license, future plans,
- comparison with other similar systems.)
- </para>
+ <para>(Autoren, Webseiten, Mailingliste, Lizenz, Zukunftspläne, Vergleich mit ähnlichen Systemen)</para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Project Setup</title>
+ <title>Einrichtung in einem Projekt</title>
- <para>
- This Chapter describes the steps that are necessary to integrate GTK-Doc
- into your project. The integration of GTK-Doc into a project includes the
- following steps:
- </para>
+ <para>Dieses Kapitel beschreibt die notwendigen Schritte, um GTK-Doc in Ihr Projekt zu integrieren. Im einzelnen sind dies folgende Schritte:</para>
<itemizedlist>
<listitem>
- <para>
- Preparation of the directory structure and creating required
- configuration files for your GTK-Doc documentation (see
- <link linkend="settingup_docfiles">
- Setting up a skeleton documentation</link>).
- </para>
+ <para>Vorbereitung der Ordnerstruktur und Erstellung der erforderlichen Konfigurationsdateien für Ihre GTK-Doc-Dokumentation (siehe <link linkend="settingup_docfiles">Einrichten des Grundgerüsts der Dokumentation</link>).</para>
</listitem>
<listitem>
- <para>
- Adjusting the build system to build your documentation using the
- GTK-Doc tools. Multiple build systems are supported, in
- this manual we describe how to integrate GTK-Doc with
- <link linkend="settingup_autotools">Autotools</link>,
- <link linkend="settingup_cmake">CMake</link>, and
- <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
- </para>
+ <para>Anpassen des Erstellungssystems, so dass Ihre Dokumentation durch die Werkzeuge von GTK-Doc erstellt wird. Es werden mehrere Erstellungssysteme unterstützt. In diesem Handbuch beschreiben wir die Integration von GTK-Doc in <link linkend="settingup_autotools">Autotools</link>, <link linkend="settingup_cmake">CMake</link> und <link linkend="settingup_plain_makefiles">einfache Makefiles</link>.</para>
</listitem>
<listitem>
- <para>
- Adding GTK-Doc specific files to version control and deciding which
- files to ignore (see <link linkend="settingup_vcs">
- Integration with version control systems</link>).
- </para>
+ <para>Hinzufügen GTK-Doc-spezifischer Dateien zur Versionsverwaltung, wobei zu entscheiden ist, welche Dateien ignoriert werden sollen (siehe <link linkend="settingup_vcs">Integration in Versionsverwaltungssysteme</link>).</para>
</listitem>
</itemizedlist>
- <para>
- The following sections assume we work on a project called
- <code>meep</code>.
- This project contains two packages (or modules),
- a library called <code>libmeep</code> and an end-user app
- called <code>meeper</code>.
- </para>
+ <para>In den folgenden Abschnitten wird ein fiktives Projekt namens <code>meep</code> angenommen, an dem wir arbeiten. Das Projekt enthält zwei Pakete (oder Module), eine Bibliothek namens <code>libmeep</code> und eine Endbenutzer-Anwendung namens <code>meeper</code>.</para>
<sect1 id="settingup_docfiles">
<title>Einrichten des Grundgerüsts der Dokumentation</title>
- <para>
- A common convention is to place documentation into a folder called
- <code>docs</code> inside your top-level project directory.
- We usually distinguish between <emphasis>reference
- documentation</emphasis> intended for developers and an
- <emphasis>user manual</emphasis> intended for end-users.
- Again the convention is to have separate folders for both.
- We usually place the reference documentation in a folder named
- <code>reference</code> and the end-user manual in a folder named
- <code>help</code> as.
-
- According to the above convention the documentation for our
- <code>libmeep</code> package would be placed into:
- <code>docs/reference/libmeep</code>.
-
- For packages with just one library or application
- the documentation could also be placed directly into
- <code>docs/reference</code>.
-
- It is not mandatory to use the above convention, but if you
- choose to use a different directory structure you must adjust
- your build system configuration to match your directory
- structure.
- </para>
+ <para>Üblicherweise wir die Dokumentation in einem Ordner namens <code>docs</code> in der obersten Ebene Ihres Projektordners platziert. Wir unterscheiden stets zwischen der für Entwickler bestimmten <emphasis>Referenzdokumentation</emphasis> und dem <emphasis>Benutzerhandbuch</emphasis>, das sich an Endbenutzer richtet. Es ist wiederum üblich, dass für beide Werke getrennte Ordner verwendet werden. Wir legen die Referenzdokumentation in einem Ordner namens <code>reference</code> und das Benutzerhandbuch in <code>help</code>. Nach der oben gennanten Konvention würde dann die Dokumentation für unser <code>libmeep</code>-Paket in <code>docs/reference/libmeep</code> platziert werden. Bei Paketen, die nur eine Bibliothek oder Anwendung enthalten, kann die Dokumentation auch direkt in <code>docs/reference</code> abgelegt werden. Es ist nicht obligatorisch, genau nach diesem Schema vorzugehen, aber wenn Sie von dieser Ordnerstruktur abweichen, müssen Sie die Konfiguration Ihres Erstellungssystems entsprechend anpassen.</para>
- <para>
- In the following sections we will assume a directory structure
- for our <emphasis>meep</emphasis> project that uses the above
- conventions.
-
- <example>
- <title>Example directory structure of <emphasis>meep</emphasis>
- project</title>
- <programlisting><![CDATA[
+ <para>In den folgenden Abschnitten gehen wir für unser <emphasis>meep</emphasis>-Projekt von einer Ordnerstruktur aus, die die oben genannten Konventionen berücksichtigt. <example>
+ <title>Beispielhafte Ordnerstruktur des <emphasis>meep</emphasis>-Projekts</title>
+ <programlisting>
meep/
docs/
reference/ # reference documentation
src/
libmeep/
meeper/
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
</sect1>
<sect1 id="settingup_autotools">
- <title>Integration with Autotools</title>
- <para>
- Integration of GTK-Doc into an autotools-based build system requires the
- following steps:
- </para>
+ <title>Integration in Autotools</title>
+ <para>Für die Integration von GTK-Doc in ein Autotools-basiertes Projekt sind die folgenden Schritte auszuführen:</para>
<itemizedlist>
<listitem>
- <para>
- Ensure that <application>gtkdocize</application> is run once before
- the <filename>configure</filename> script. If an
- <filename>autogen.sh</filename> script is present, adjust it to
- check for GTK-Doc and add a call to
- <application>gtkdocize</application>.
- </para>
-
- <para>
- The main purpose of <application>gtkdocize</application> is to
- make the <filename>gtk-doc.make</filename> Makefile and the
- <filename>gtk-doc.m4</filename> macro definition file available
- to the build system, either by copying or linking it
- into the project.
- </para>
+ <para>Stellen Sie sicher, dass <application>gtkdocize</application> einmal vor dem <filename>configure</filename>-Skript ausgeführt wird. Falls es ein <filename>autogen.sh</filename>-Skript gibt, passen Sie es so an, dass es nach GTK-Doc sucht und einen <application>gtkdocize</application>-Aufruf hinzufügt.</para>
+
+ <para>Der Hauptzweck von <application>gtkdocize</application> ist die Erstellung der <filename>gtk-doc.make</filename>-Steuerdatei und der Makro-Definitionsdatei <filename>gtk-doc.m4</filename> für das Erstellungssystem, entweder durch Kopieren oder Verlinken im Projekt.</para>
</listitem>
<listitem>
- <para>
- Add the necessary <application>autoconf</application> macros to
- <filename>configure.ac</filename> to enable GTK-Doc in your build
- system to allow configuration of GTK-Doc via the generated
- <filename>configure</filename> script.
- </para>
- <para>
- Among others with registers the <code>--enable-gtk-doc</code>
- option with the <filename>configure</filename> script.
- </para>
+ <para>Fügen Sie die notwendigen <application>autoconf</application>-Makros zu <filename>configure.ac</filename> hinzu, um GTK-Doc in Ihrem Erstellungssystem zu aktivieren, so dass die Konfiguration von GTK-Doc über das erzeugte <filename>configure</filename>-Skript erfolgt.</para>
+ <para>Unter anderem wird die Option <code>--enable-gtk-doc</code> mit dem <filename>configure</filename>-Skript registriert.</para>
</listitem>
<listitem>
- <para>
- Create an <application>automake</application> script for each
- application or library in your project. In the example used in this
- documentation this step applies to both <code>meeper</code> and
- <code>libmeep</code>.
- </para>
+ <para>Erstellen Sie ein <application>automake</application>-Skript für jede Anwendung oder Bibliothek in Ihrem Projekt. In dem in dieser Dokumentation verwendeten Beispiel wird dieser Schritt sowohl auf <code>meeper</code> als auch <code>libmeep</code> angewendet.</para>
</listitem>
</itemizedlist>
- <para>
- In the following sections, we will perform the above steps in reverse
- order. We start with the <application>automake</application> scripts
- and work our way up to <filename>configure.ac</filename> and
- <filename>autogen.sh</filename>.
- Then we show how enable Gtk-Doc in the build system and
- how to build the documentation.
- </para>
+ <para>In den folgenden Abschnitten führen wir die oben beschriebenen Schritte in umgekehrter Reihenfolge aus. Wir beginnen mit den <application>automake</application>-Skripten und arbeiten uns bis hinauf zu <filename>configure.ac</filename> und <filename>autogen.sh</filename>. Dann zeigen wir, wie GTK-Doc im Erstellungssystem aktiviert und wie die Dokumentation erstellt wird.</para>
<sect2 id="settingup_automake">
<title>Integration in automake</title>
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub-directory of the
- <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
- gtkdoc-sources</ulink>
- to your project's reference documentation directory (e.g.
- <filename class="directory">docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple packages repeat this for each one.
- </para>
+ <para>Kopieren Sie zunächst die Datei <filename>Makefile.am</filename> aus dem <filename class="directory">examples</filename>-Unterordner der <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">gtkdoc-Quellen</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>
<note>
- <simpara>
- Do not forget to add each <filename>Makefile.am</filename>
- to the <function>AC_CONFIG_FILES</function> macro in
- <filename>configure.ac</filename>. For
- <filename>docs/reference/libmeep/Makefile.am</filename> you will
- need to add the entry
- <filename>docs/reference/libmeep/Makefile</filename>
- to <function>AC_CONFIG_FILES</function>.
- </simpara>
+ <simpara>Vergessen Sie nicht, jedes <filename>Makefile.am</filename> zum Makro <function>AC_CONFIG_FILES</function> in <filename>configure.ac</filename> hinzuzufügen. Für <filename>docs/reference/libmeep/Makefile.am</filename> müssen Sie den Eintrag <filename>docs/reference/libmeep/Makefile</filename> zu <function>AC_CONFIG_FILES</function> hinzufügen.</simpara>
</note>
<example>
- <title>
- Example directory structure with <filename>Makefiles.am</filename>
- </title>
+ <title>Beispielhafte Ordnerstruktur mit <filename>Makefiles.am</filename></title>
<programlisting>
meep/
docs/
</programlisting>
</example>
- <para>
- Next, you need to customize the copied Makefiles
- and provide values for the various parameters in each
- <filename>Makefile.am</filename>.
-
- All settings have a comment above them that describes their purpose
- and how to customize the setting.
-
- Most settings are used to supply extra flags to the respective tools
- to which they apply. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>
- (e.g. the tool <application>gtkdoc-mkhtml</application> has
- an option named <code>MKHTML_OPTIONS</code>).
-
- All the tools support <option>--help</option> to list the supported
- options.
- </para>
+ <para>Im nächsten Schritt passen Sie die kopierten Makefiles an und geben Werte für die verschiedenen Parameter in jedem <filename>Makefile.am</filename> an. 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>
- <para>
- The following list explains the most relevant options. Check the
- example <filename>Makefile.am</filename> for additional options.
-
- <itemizedlist>
+ <para>In der folgenden Liste werden einige der relevantesten Optionen erläutert. Im Beispiel für <filename>Makefile.am</filename> finden Sie weitere Optionen. <itemizedlist>
<listitem>
- <para>
- <option>DOC_MODULE</option> is used to provide the name of the
- package that is being documentated (e.g. <code>meeper</code>, or
- <code>libmeep</code>).
- </para>
+ <para><option>DOC_MODULE</option> stellt den Namen des Pakets bereit, das dokumentiert werden soll (z.B. <code>meeper</code> oder <code>libmeep</code>).</para>
</listitem>
<listitem>
- <para>
- <option>DOC_SOURCE_DIR</option>
- is used to specify the location
- of source directory which GTK-Doc searches for your API
- documentation. This will usually be
- <code>
- DOC_SOURCE_DIR=$(top_srcdir)/src
- </code>
- or a sub-directory of that directory.
- </para>
+ <para><option>DOC_SOURCE_DIR</option> gibt den Ort des Quellordners an, wo GTK-Doc nach Ihrer API-Dokumentation suchen soll. Üblicherweise ist das <code> DOC_SOURCE_DIR=$(top_srcdir)/src </code> oder einer von dessen Unterordnern.</para>
</listitem>
<listitem>
- <para>
- <option>HFILE_GLOB</option>
- and
- <option>CFILE_GLOB</option>
- are used for dependencies. Each option take a file-glob (e.g.
- <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
- The documentation will be rebuilt if any of the matched files
- change.
- </para>
+ <para><option>HFILE_GLOB</option> und <option>CFILE_GLOB</option> werden für Abhängigkeiten verwendet. Jed Option akzeptiert ein file-glob (z.B. <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>). Die Dokumentation wird neu erstellt, wenn sich eine der Dateien ändert.</para>
</listitem>
<listitem>
- <para>
- <option>EXTRA_HFILES</option>
- allows to specify extra header files
- to include when scanning for API documentation, which are not
- found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
- EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
- </para>
+ <para>Mit <option>EXTRA_HFILES</option> können Sie zusätzliche einzuschließende Header-Dateien angeben, wenn nach API-Dokumentation gesucht wird, falls diese nicht unter <code>DOC_SOURCE_DIR</code> zu finden ist (z.B. <code> EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).</para>
</listitem>
<listitem>
- <para>
- <option>IGNORE_HFILES</option>
- allows to specify header files
- or directories to ignore when scanning for API documentation.
- Use the basename of the file or directory (e.g. <code>
- IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
- </para>
+ <para>Mit <option>IGNORE_HFILES</option> können Sie zu ignorierende Header-Dateien angeben, wenn nach API-Dokumentation gesucht wird. Verwenden Sie dabei den Basisnamen der Datei oder des Ordners (z.B. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).</para>
</listitem>
<listitem>
- <para>
- <option>HTML_IMAGES</option>
- allows to specify images files which
- will be copied into the <filename>html/</filename> directory of
- the generated documentation.
- If your API documentation includes any images they need to be
- added to this
- option (e.g. <code>
- HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
- </para>
+ <para>In <option>HTML_IMAGES</option> können Sie Bilder angeben, die in den <filename>html/</filename>-Ordner der erzeugten Dokumentation kopiert werden. Falls Ihre API-Dokumentation Bilder enthält, müssen diese zu dieser Option hinzugefügt werden (z.B. <code> HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).</para>
</listitem>
<listitem>
- <para>
- <option>content_files</option>
- allows to specify extra files
- that are included by
- <code>$(DOC_MAIN_SGML_FILE)</code>
- (e.g. <code>
- content_files=running.xml building.xml changes-2.0.xml</code>).
- </para>
+ <para>In <option>content_files</option> können Sie zusätzliche Dateien angeben, die in <code>$(DOC_MAIN_SGML_FILE)</code> einbezogen werden sollen (z.B. <code> content_files=running.xml building.xml changes-2.0.xml</code>).</para>
</listitem>
<listitem>
- <para>
- <option>expand_content_files</option>
- allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
- <code>#GtkWidget</code>
- are expanded (e.g. <code>
- expand_content_files=running.xml</code>).
- </para>
+ <para>In <option>expand_content_files</option> geben Sie Dateien an, in denen <emphasis>gtk-doc Abkürzungen</emphasis> wie <code>#GtkWidget</code> expandiert werden (z.B. <code> expand_content_files=running.xml</code>).</para>
</listitem>
- </itemizedlist>
- </para>
+ </itemizedlist></para>
</sect2>
<sect2 id="settingup_autoconf">
<title>Integration in autoconf</title>
- <para>
- Integration with <application>autoconf</application> is very simple
- and includes one required step and an additional optional
- (but recommended) step.
-
- The first step is to add the <function>GTK_DOC_CHECK</function> macro
- to your <filename>configure.ac</filename> script. This registers
- several configure options to enable GTK-Doc and allows you
- to set default arguments for <application>gtkdocize</application>.
- </para>
+ <para>Die Integration in <application>autoconf</application> ist recht einfach. Es ist nur ein Schritt zwingend erforderlich sowie ein weiterer optional (aber empfehlenswert). Zunächst fügen Sie das Makro <function>GTK_DOC_CHECK</function> zu Ihrem <filename>configure.ac</filename> Skript hinzu. Dadurch werden verschiedene Konfigurationsoptionen zur Aktivierung von GTK-Doc registriert sowie Standardargumente für <application>gtkdocize</application> gesetzt.</para>
<warning>
- <simpara>
- Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
- The macro must start at the beginning of the line and should not
- start with whitespace.
- </simpara>
+ <simpara>Achten Sie darauf, dass das <code>GTK_DOC_CHECK</code>-Makro nicht eingerückt ist. Es muss zwingend am Anfang der Zeile stehen und sollte nicht mit einem Leerzeichen beginnen.</simpara>
</warning>
- <para>
- The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
- to your <filename>configure.ac</filename>. This is not required
- but helps <application>gtkdocize</application> to automatically copy
- the macro definition (e.g <filename>gtk-doc.m4</filename>) which
- contains the <function>GTK_DOC_CHECK</function> macro to your
- project's macro directory. Without this, the GTK_DOC_CHECK macro
- might not be found and you would need to explicitly tell the
- <application>aclocal</application> tool where to find the macro
- definition file.
- </para>
+ <para>Danach fügen Sie <code>AC_CONFIG_MACRO_DIR(m4)</code> zu Ihrer <filename>configure.ac</filename>-Datei hinzu. Dies ist nicht zwingend erforderlich, aber hilft <application>gtkdocize</application> dabei, die Makrodefinition (e.g <filename>gtk-doc.m4</filename>), welche das Makro <function>GTK_DOC_CHECK</function> enthält, in den Makro-Ordner Ihres Projekts zu kopieren. Wenn Sie diesen Schritt auslassen, könnte das Makro GTK_DOC_CHECK möglicherweise nicht gefunden werden, und Sie müssten den Ort der Makro-Definitionsdatei explizit für <application>aclocal</application> angeben.</para>
<para>
- <example><title>Minimal integration with autoconf</title>
- <programlisting><![CDATA[
+ <example><title>Minimale Integration in autoconf</title>
+ <programlisting>
# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
# optional: register gtk-doc in configure
GTK_DOC_CHECK([1.28])
-]]></programlisting>
+</programlisting>
</example>
</para>
- <para>
- The above example works, but will require all developers to have
- gtk-doc installed. A better way is to make building the documentation
- optional as shown in the next example:
-
- <example>
- <title>Integration with optional gtk-doc dependency</title>
- <programlisting><![CDATA[
+ <para>Das obige Beispiel funktioniert, aber es erfordert, dass alle Entwickler gtk-doc installiert haben. Eine bessere Lösung ist die optional Erstellung der Dokumentation, wie das nächste Beispiel zeigt: <example>
+ <title>Integration mit optionaler Abhängigkeit zu gtk-doc</title>
+ <programlisting>
m4_ifdef([GTK_DOC_CHECK], [
# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
- <para>
- The first argument is used to check for the Gtk-Doc version at
- configure time. The 2nd, optional argument is used by
- <application>gtkdocize</application>.
- The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
- switches:
- </para>
+ <para>Das erste Argument wird zur Überprüfung von der Version von GTK-Doc während des configure-Durchlaufs benutzt. Das zweite, optionale Argument wird von <application>gtkdocize</application> verwendet. Das Makro <symbol>GTK_DOC_CHECK</symbol> fügt verschiedene Schalter für configure hinzu:</para>
<orderedlist>
<listitem><para>--with-html-dir=PATH : Pfad zur installierten Dokumentation</para></listitem>
<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>
- After all changes to <filename>configure.ac</filename> are made,
- update the <filename>configure</filename> file. This can be done by
- re-running <code>autogen.sh</code>.
- </para>
+ <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>autogen.sh</code>.</para>
</sect2>
<sect2 id="settingup_autogen">
<title>Integration in autogen</title>
- <para>
- Most projects will have an <filename>autogen.sh</filename> script to
- setup the build infrastructure after the project was checked out from
- a version control system (such as git or svn). GTK-Doc comes with a
- script called <application>gtkdocize</application> which can be used
- to copy the necessary files needed by Gtk-Doc to the source directory.
- </para>
+ <para>Die meisten Projekte dürften über ein <filename>autogen.sh</filename>-Skript verfügen, welches die Build-Infrastruktur nach dem Auschecken aus einem Versionsverwaltungssystem wie SVN oder Git erzeugt. GTK-Doc liefert ein Werkzeug namens <application>gtkdocize</application> mit, das zum Kopieren der für GTK-Doc erforderlichen Dateien in den Quellordner verwendet werden kann.</para>
- <para>
- It should be run before autoreconf, autoheader, automake or autoconf.
- </para>
+ <para>Es sollte vor autoreconf, autoheader, automake oder autoconf ausgeführt werden.</para>
<para>
<example><title>Ausführen von gtkdocize durch autogen.sh</title>
<para>
<example>
- <title>Conditionally run gtkdocize from autogen.sh</title>
- <programlisting><![CDATA[
-GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+ <title>Bedingtes Ausführen von gtkdocize durch autogen.sh</title>
+ <programlisting>
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
if test $? -ne 0; then
echo "No gtk-doc support found. You can't build the docs."
else
$GTKDOCIZE || exit 1
fi
-]]></programlisting>
+</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).
- </para>
+ <para>Beim Ausführen von <application>gtkdocize</application> wird <filename>gtk-doc.make</filename> in die Wurzel Ihres Projekts oder in jeden anderen durch die Option <option>--docdir</option> festgelegten Ordner kopiert.</para>
- <para>
- <application>gtkdocize</application> checks your
- <filename>configure.ac</filename> script for
- the <function>GTK_DOC_CHECK</function> macro.
- The <function>GTK_DOC_CHECK</function> macro can be used to pass
- extra arguments to the <application>gtkdocize</application> script.
- the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
- </para>
+ <para><application>gtkdocize</application> überprüft das <filename>configure.ac</filename>-Skript daraufhin, ob <function>GTK_DOC_CHECK</function> enthalten ist. Dieses Makro kann verwendet werden, um weitere Parameter an <application>gtkdocize</application> zu übergeben, den zweiten Parameter im <function>GTK_DOC_CHECK</function>-Makro.</para>
- <para>
- Alternatively, additional arguments can also be passed to
- <application>gtkdocize</application> via the
- <function>GTKDOCIZE_FLAGS</function> environment variable, or by
- directly specifying them to <application>gtkdocize</application>
- in <filename>autogen.sh</filename>.
- </para>
+ <para>Alternativ können zusätzliche Argumente auch über die Umgebungsvariable <function>GTKDOCIZE_FLAGS</function> an <application>gtkdocize</application> übergeben werden, oder durch direktes Anfügen an <application>gtkdocize</application> in <filename>autogen.sh</filename>.</para>
</sect2>
<sect2 id="settingup_firstrun">
- <title>Executing GTK-Doc from the Build System</title>
+ <title>Aufruf von GTK-Doc aus dem Erstellungssystem heraus</title>
<para>Nach den bisher absolvierten Schritten ist es Zeit für den Build-Vorgang. Zunächst muss <filename>autogen.sh</filename> erneut ausgeführt werden. Falls dieses Skript auch den configure-Aufruf enthält, sollten Sie die Option <option>--enable-gtk-doc</option> hinzufügen. Anderenfalls führen Sie danach <filename>configure</filename> manuell aus, ebenfalls mit dieser Option.</para>
<para>Der erste Durchlauf von make erstellt verschiedene zusätzliche Dateien in den Dokumentationsordnern. Die bedeutendsten davon sind: <filename><package>.types</filename>, <filename><package>-docs.xml</filename> (früher .sgml), <filename><package>-sections.txt</filename>.</para>
</example>
</para>
- <para>
- Now you can point your browser to
- <filename>docs/reference/<package>/index.html</filename>.
- With this initial setup you will only see a very simple document.
- The next chapter will teach you how to add API documentation to your
- code via special comment blocks. The Chapter afterwards introduces
- <link linkend="metafiles">additional files</link> and shows how to
- edit the <link linkend="metafiles_master">master template</link> to
- add additional chapters and sections to your documentation files.
- </para>
+ <para>Nun können Sie Ihren Browser auf <filename>docs/reference/<package>/index.html</filename> stellen. Mit dieser initialen Einrichtung werden Sie allerdings nur ein sehr simples Dokument sehen. Im nächsten Kapitel erläutern wir, wie Sie API-Dokumentation mittels spezieller Kommentarblöcke in Ihren Code einbauen können. Das Kapitel danach führt in <link linkend="metafiles">zusätzliche Dateien</link> ein und zeigt, wie die <link linkend="metafiles_master">Master-Vorlage</link> bearbeitet wird, um zusätzliche Kapitel und Abschnitte zu Ihren Dokumentationsdateien hinzuzufügen.</para>
</sect2>
<sect1 id="settingup_plain_makefiles">
<title>Integration in Klartext-Makefiles oder andere Erstellungssysteme</title>
- <para>Für den Fall, dass jemand nicht automake und damit <filename>gtk-doc.mak</filename> einsetzen will, muss man die gtkdoc-Werkzeuge in eigenen makefiles (oder andere Werkzeuge) in der richtigen Reihenfolge aufrufen.</para>
+ <para>Für den Fall, dass jemand nicht automake und damit <filename>gtk-doc.mak</filename> einsetzen will, muss man die gtkdoc-Werkzeuge in eigenen Makefiles (oder andere Werkzeugen) in der richtigen Reihenfolge aufrufen.</para>
<para>
<example><title>Schritte zur Erstellung der Dokumentation</title>
<para>GTK-Doc benutzt Quellcode-Kommentare mit einer speziellen Syntax für Code-Dokumentation. Weiterhin werden Informationen über Ihre Projektstruktur aus anderen Quellen geholt. Im nächsten Abschnitt finden Sie umfassende Informationen über die Syntax der Kommentare.</para>
- <para>
- The GTK-Doc scanner can handle the majority of C headers fine. In the
- case of receiving warnings from the scanner that look like a special
- case, one can hint GTK-Doc to skip over them.
- <example><title>GTK-Doc comment block</title>
- <programlisting><![CDATA[
+ <para>Der Scanner von GTK-Doc kann mit den meisten C-Kopfdateien umgehen. Im Falle von Warnungen des Scanners, die wie ein Spezialfall aussehen, kann man GTK-Doc anweisen, diese zu überspringen. <example><title>GTK-Doc-Kommentarblock</title>
+ <programlisting>
#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
<note>
<title>Einschränkungen</title>
<tip>
<para>Beim Dokumentieren von Code beschreiben Sie zwei Aspekte: <itemizedlist>
<listitem>
- <para>Was es ist: Der Name für eine Klasse oder Funktion kann manchmal Irre führend sein für Personen, die einen anderen Hintergrund haben.</para>
+ <para>Was es ist: Der Name für eine Klasse oder Funktion kann manchmal irreführend sein für Personen, die einen anderen Hintergrund haben.</para>
</listitem>
<listitem>
<para>Was es ist: Berichtet über normale Anwendungsfälle. Stellen Sie es ins Verhältnis mit der anderen API.</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>
- As already mentioned earlier GTK-Doc is for documenting public API. Thus
- one cannot write documentation for static symbols. Nevertheless it is good
- to comment those symbols too. This helps other developers to understand
- your code.
- Therefore we recommend to comment these using normal comments (without the
- 2nd '*' in the first line).
- If later the function needs to be made public, all one needs to do is to
- add another '*' in the comment block and insert the symbol name at the
- right place inside the sections file.
- </para>
+ <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>
</tip>
</sect1>
<sect1 id="documenting_sections">
- <title>Dokumentieren von Abschnitten</title>
+ <title>Dokumentieren in Abschnitten</title>
<para>Jeder Abschnitt der Dokumentation enthält Informationen über eine Klasse oder ein Modul. Um eine Komponente hinzuzufügen, können Sie einen Abschnittsblock schreiben. Die Kurzbeschreibung wird auch im Inhaltsverzeichnis verwendet. Alle @-Felder sind optional.</para>
<listitem>
<para>Eine informelle Beschreibung der Stabilitätsstufe dieser API. Wir empfehlen dafür einen der folgenden Begriffe: <itemizedlist>
<listitem>
- <para>Stabil - Die Absicht einer stabilen Schnittstelle ist es beliebigen Dritten es zu ermöglichen Anwendungen zu diesen Schnittstellen zu entwickeln, diese freizugeben und sich darauf verlassen zu können, dass diese mit allen Unterversionen des Produkts laufen (nach derjenigen, wo die Schnittstelle eingeführt wurde, und innerhalb der gleichen Hauptversion). Selbst bei einer Hauptversion kann man nicht von inkompatiblen Änderungen ausgehen, abgesehen von stark berechtigten.</para>
+ <para>Stabil - Die Absicht einer stabilen Schnittstelle ist es, beliebigen Dritten es zu ermöglichen, Anwendungen zu diesen Schnittstellen zu entwickeln, diese freizugeben und sich darauf verlassen zu können, dass diese mit allen Unterversionen des Produkts laufen (nach derjenigen, wo die Schnittstelle eingeführt wurde, und innerhalb der gleichen Hauptversion). Selbst bei einer Hauptversion kann man nicht von inkompatiblen Änderungen ausgehen, abgesehen von stark berechtigten.</para>
</listitem>
<listitem>
- <para>Instabil - Instabile Schnittstellen sind experimentell oder vorübergehend. Sie werden typischerweise verwendet, um außenstehenden Entwicklern frühen Zugang zu neuen oder sich schnell ändernder Technologie zu geben, oder um eine Übergangslösung für ein Problem zu liefern, für das eine allgemeinere Lösung erwartet wird. Es werden keine Garantien zu Quell- oder Binärkompatibilität von einer minor-Freigabe zur nächsten gegeben.</para>
+ <para>Instabil - Instabile Schnittstellen sind experimentell oder vorübergehend. Sie werden typischerweise verwendet, um außenstehenden Entwicklern frühen Zugang zu neuen oder sich schnell ändernden Technologien zu geben, oder um eine Übergangslösung für ein Problem zu liefern, für das eine allgemeinere Lösung erwartet wird. Es werden keine Garantien zu Quell- oder Binärkompatibilität von einer minor-Freigabe zur nächsten gegeben.</para>
</listitem>
<listitem>
<para>Privat - Eine Schnittstelle, die im GNOME-Stack selbst verwendet werden kann, aber nicht für Endanwender dokumentiert ist. Solche Funktionen sollten nur auf spezifizierte und dokumentierte Weisen verwendet werden.</para>
<varlistentry>
<term>@include</term>
<listitem>
- <para>Die <literal>#include</literal> -Dateien werden im Abschnitt Zusammenfassung angezeigt (eine durch Kommata getrennte Liste). Der globale Wert aus der <link linkend="metafiles_sections">Abschnittsdatei</link> oder von der Befehlszeile wird überschrieben. Dieser Punkt ist optional.</para>
+ <para>Die <literal>#include</literal> -Dateien werden im Abschnitt »synopsis« angezeigt (eine durch Kommata getrennte Liste). Der globale Wert aus der <link linkend="metafiles_sections">Abschnittsdatei</link> oder von der Befehlszeile wird überschrieben. Dieser Punkt ist optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@image</term>
<listitem>
- <para>Das Bild, das am Beginn einer Referenzseite für diesen Abschnitt angezeigt wird. Meist wird es eine Art Diagramm für visuelle Erscheinungsbild einer Klasse oder ein Diagramm sein, das die Beziehungen zu anderen Klassen darstellt. Dieses Objekt ist optional.</para>
+ <para>Das Bild, das am Beginn einer Referenzseite für diesen Abschnitt angezeigt wird. Meist wird es eine Art Diagramm für das visuelle Erscheinungsbild einer Klasse oder ein Diagramm sein, das die Beziehungen zu anderen Klassen darstellt. Dieses Objekt ist optional.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Dokumentieren Sie ein Programm und dessen Befehlszeilen-Schnittstelle mit eingebetteter Dokumentation.</para>
<variablelist>
- <title>Schlagwörter</title>
+ <title>Markierungen</title>
<varlistentry><term>PROGRAM</term>
<listitem>
- <para>Definiert den Start einer Programmdokumentation</para>
+ <para>Definiert den Start einer Programmdokumentation.</para>
</listitem>
</varlistentry>
<programlisting>
<link linkend="glib-Hash-Tables">Hash Tables</link>
</programlisting>
- </informalexample> »linkend« ist dabei die SGML-XML-Kennung des obersten Elements der Seite, auf welche die Verknüpfung zielt (»gtk«, »gdk«, »glib«), danach folgt der Seitentitel ("Hash Tables"). Für Widgets ist dies einfach der Klassenname. Leerzeichen und Unterstriche werden SGML/XML-konform in »-« umgewandelt. </para>
+ </informalexample> »linkend« ist dabei die SGML-XML-Kennung des obersten Elements der Seite, auf welche die Verknüpfung zielt (»gtk«, »gdk«, »glib«), danach folgt der Seitentitel ("Hash Tables"). Für Widgets ist dies einfach der Klassenname. Leerzeichen und Unterstriche werden SGML/XML-konform in »-« umgewandelt.</para>
<para>Für einen Bezug zu einer externen Funktion, z.B. einer C-Standardfunktion: <informalexample>
<programlisting>
</programlisting>
</informalexample></para>
- <para>So fügen Sie Beispielcode ein: <placeholder-1/> Vielleicht auch so, für sehr kurze Codeschnipsel, die keinen Titel benötigen: <informalexample>
- <programlisting>
-<informalexample>
- <programlisting>
+ <para>
+ To include example code:
+ <informalexample>
+ <programlisting><![CDATA[
+<example>
+ <title>Using a GHashTable.</title>
+ <programlisting language="C">
+ ...
+ </programlisting>
+</example>
+]]></programlisting>
+ </informalexample>
+ or possibly this, for very short code fragments which don't need a title:
+ <informalexample>
+ <programlisting><![CDATA[
+<informalexample>
+ <programlisting language="C">
...
- </programlisting>
-</informalexample>
-</programlisting>
- </informalexample> Außerdem unterstützt GTK-Doc auch eine Abkürzung: |[ ... ]|</para>
+ </programlisting>
+</informalexample>
+]]></programlisting>
+ </informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
+ For the latter GTK-Doc also supports an abbreviation:
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
+ ...
+]|
+]]></programlisting>
+ </informalexample>
+ </para>
<para>Für eine Liste mit Aufzählungszeichen: <informalexample>
<programlisting>
</programlisting>
</informalexample></para>
- <para>Um sich auf einen Klassennamen zu beziehen kann man möglicherweise folgendes verwenden: <informalexample>
+ <para>Um sich auf einen Klassennamen zu beziehen, kann man möglicherweise folgendes verwenden: <informalexample>
<programlisting>
<classname>GtkWidget</classname>
</programlisting>
<para>Falls Ihre Bibliothek oder Anwendung GObjects beinhaltet, sollten deren Signale, Argumente/Parameter und Positionen in der Hierarchie in der Dokumentation erscheinen. Alles was Sie tun müssen, ist die <function>xxx_get_type</function>-Funktionen zusammen mit deren Includes in der Datei <filename><package>.types</filename> aufzulisten.</para>
<para>
- <example><title>Example <package>.types file</title>
+ <example><title>Beispiel-Schnipsel einer <package>.types-Datei</title>
<programlisting>
#include <gtk/gtk.h>
</example>
</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>
+ <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>
<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
- in the master template and how the entities are used.
- The entities can also be used in all
- generated files, GTK-Doc will use the same xml header in generated xml
- files.
- <example><title>Use pre-generated entities</title>
- <programlisting><![CDATA[
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ <para>Die in dieser Version enthaltenen Make-Steuerdateien erzeugen die Entitätsdatei <filename>xml/gtkdocentities.ent</filename>, die Entitäten für beispielsweise package_name und package_version enthält. Sie können diese in der XML-Hauptdatei verwenden, um eine fest codierte Versionsnummer zu vermeiden. Nachfolgend finden Sie ein Beispiel, wie die Entitätsdatei einbezogen wird und und wie die Einträge verwendet werden. Die Entitäten können auch in allen generierten Dateien verwendet werden. GTK-Doc verwendet die gleichen XML-Kopfeinträge auch in generierten Dateien. <example><title>Vorerzeugte Entitäten verwenden</title>
+ <programlisting>
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"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>
</seglistitem>
<seglistitem>
<seg>Verdammt, ich habe immer noch keine Klassenhierarchie.</seg>
- <seg>Ist der Objektname (Name des Instanz-struct, z.B. <type>GtkWidget</type>) Teil des normalen Abschnitts (nicht in den Standard- oder Unterabschnitte).</seg>
+ <seg>Ist der Objektname (Name des Instanz-struct, z.B. <type>GtkWidget</type>) Teil des normalen Abschnitts (nicht in den Standard- oder Unterabschnitten).</seg>
</seglistitem>
<seglistitem>
<seg>Kein Symbolindex.</seg>
<seg>Enthält <filename><package>-docs.{xml,sgml}</filename> einen Index, der den erstellten Index xi:enthält?</seg>
</seglistitem>
<seglistitem>
- <seg>Symbole werden nicht mit deren Dokumentationsbschnitt verknüpft.</seg>
+ <seg>Symbole werden nicht mit deren Dokumentationsabschnitt verknüpft.</seg>
<seg>Verwendet das doc-comment das richtige Markup (hinzugefügtes »#«,»%« oder »()«)? Prüfen Sie, ob gtkdoc-fixxref wegen nicht auflösbarer xrefs warnt.</seg>
</seglistitem>
<seglistitem>
</seglistitem>
<seglistitem>
<seg>Ein neues Symbol erscheint nicht in der Dokumentation.</seg>
- <seg>ist doc-comment ordnungsgemäß formatiert? Prüfen Sie den Anfang des Dokuments auf Rechtschreibfehler im Kommentar. Prüfen Sie ob gtkdoc-fixxref wegen unauflösbarer xrefs warnt. Prüfen Sie, ob das Symbol richtig in <filename><package>-sections.txt</filename> in einem öffentlichen Abschnitt gelistet ist.</seg>
+ <seg>Ist doc-comment ordnungsgemäß formatiert? Prüfen Sie den Anfang des Dokuments auf Rechtschreibfehler im Kommentar. Prüfen Sie, ob gtkdoc-fixxref wegen unauflösbarer xrefs warnt. Prüfen Sie, ob das Symbol richtig in <filename><package>-sections.txt</filename> in einem öffentlichen Abschnitt gelistet ist.</seg>
</seglistitem>
<seglistitem>
<seg>Ein Typ fehlt in der Klassenhierarchie.</seg>
<para>Um diese Lizenz in einem von Ihnen geschriebenen Dokument nutzen zu können, fügen Sie eine Kopie der Lizenz in das Dokument ein und setzen Sie die folgenden Copyright- und Lizenzhinweise gleich hinter die Titelseite:</para>
<blockquote>
- <para>Copyright (c) JAHR IHR NAME.</para>
+ <para>Copyright (c) JAHR IHR NAME.</para>
<para>Es wird die Erlaubnis gegeben, dieses Dokument zu kopieren, verteilen und/oder zu verändern unter den Bedingungen der GNU Free Documentation License, Version 1.1 oder einer späteren, von der Free Software Foundation veröffentlichten Version; mit den <link linkend="fdl-invariant">Unveränderlichen Abschnitten</link>. DEREN TITEL AUFGEZÄHLT sind, mit den <link linkend="fdl-cover-texts">Vorderseitentexten</link>, die AUFGEZÄHLT sind, und mit den <link linkend="fdl-cover-texts">Rückseitentexten</link>, die AUFGEZÄHLT sind. Eine Kopie dieser Lizenz ist in dem Abschnitt enthalten, der mit <quote>GNU Free Documentation License</quote> betitelt ist.</para>
</blockquote>
</authorgroup>
<publisher role="maintainer"><publishername>Έργο GTK-Doc</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
<copyright><year>2000, 2005</year> <holder>Dan Mueth και Chris Lyttle</holder></copyright>
- <copyright><year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder></copyright>
+ <copyright>
+ <year>2007-2019</year>
+ <holder>Stefan Sauer (Kost)</holder>
+ </copyright>
<!-- translators: uncomment this:
<copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision>
<revnumber>1.28</revnumber>
<title>Περί GTK-Doc</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>(ΠΡΟΣ ΔΙΟΡΘΩΣΗ)</para>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
<term>Επιστροφές:</term>
<listitem>
<para>
- Specificy what value(s) the program returns. (Optional)
+ Specify what value(s) the program returns. (Optional)
</para>
</listitem>
</varlistentry>
</programlisting>
</informalexample></para>
- <para>Συμπερίληψη παραδειγμάτων κώδικα: <informalexample>
- <programlisting>
-<example>
- <title>Using a GHashTable.</title>
- <programlisting>
+ <para>
+ To include example code:
+ <informalexample>
+ <programlisting><![CDATA[
+<example>
+ <title>Using a GHashTable.</title>
+ <programlisting language="C">
...
- </programlisting>
-</example>
-</programlisting>
- </informalexample> ή, ενδεχομένως, για πολύ σύντομο κώδικα που δεν χρειάζεται τίτλο: <informalexample>
- <programlisting>
-<informalexample>
- <programlisting>
+ </programlisting>
+</example>
+]]></programlisting>
+ </informalexample>
+ or possibly this, for very short code fragments which don't need a title:
+ <informalexample>
+ <programlisting><![CDATA[
+<informalexample>
+ <programlisting language="C">
...
- </programlisting>
-</informalexample>
-</programlisting>
- </informalexample>. Στην τελευταία περίπτωση το GTK-Doc υποστηρίζει επίσης μια συντόμευση: |[ ... ]|</para>
+ </programlisting>
+</informalexample>
+]]></programlisting>
+ </informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
+ For the latter GTK-Doc also supports an abbreviation:
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
+ ...
+]|
+]]></programlisting>
+ </informalexample>
+ </para>
<para>Συμπερίληψη λιστών με κουκκίδες: <informalexample>
<programlisting>
<holder>Dan Mueth and Chris Lyttle</holder>
</copyright>
<copyright>
- <year>2007-2015</year>
+ <year>2007-2019</year>
<holder>Stefan Sauer (Kost)</holder>
</copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision>
<revnumber>1.28</revnumber>
<title>About GTK-Doc</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>(FIXME)</para>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
<term>Returns:</term>
<listitem>
<para>
- Specificy what value(s) the program returns. (Optional)
+ Specify what value(s) the program returns. (Optional)
</para>
</listitem>
</varlistentry>
<programlisting><![CDATA[
<example>
<title>Using a GHashTable.</title>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</example>
<informalexample>
<programlisting><![CDATA[
<informalexample>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</informalexample>
]]></programlisting>
</informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
For the latter GTK-Doc also supports an abbreviation:
-<![CDATA[
-|[
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
...
]|
-]]>
+]]></programlisting>
+ </informalexample>
</para>
<para>
# 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, 2016, 2017, 2018.
+# Daniel Mustieles <daniel.mustieles@gmail.com>, 2019.
#
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc-help.master\n"
-"POT-Creation-Date: 2018-05-20 18:37+0000\n"
-"PO-Revision-Date: 2018-07-31 12:18+0200\n"
+"POT-Creation-Date: 2018-10-03 08:17+0000\n"
+"PO-Revision-Date: 2019-03-14 15:46+0100\n"
"Last-Translator: Daniel Mustieles <daniel.mustieles@gmail.com>\n"
"Language-Team: es <gnome-es-list@gnome.org>\n"
-"Language: \n"
+"Language: es\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
-"X-Generator: Gtranslator 2.91.7\n"
+"X-Generator: Gtranslator 3.31.90\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
msgctxt "_"
msgid "translator-credits"
msgstr ""
-"Daniel Mustieles <daniel.mustieles@gmail.com>, 2009 - 2018\n"
+"Daniel Mustieles <daniel.mustieles@gmail.com>, 2009 - 2019\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.27.1</revnumber> <date>07 Dec 2017</date> "
-#| "<authorinitials>ss</authorinitials> <revremark>development</revremark>"
msgid ""
-"<revnumber>1.2
8.1</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
+"<revnumber>1.2
9.1</revnumber> <date>28 Aug 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>development</revremark>"
msgstr ""
-"<revnumber>1.28.1</revnumber> <date>24 de marzo de 2018</date> "
+"<revnumber>1.29.1</revnumber> <date>28 de agosto de 2018</date> "
"<authorinitials>ss</authorinitials> <revremark>desarrollo</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
-#| msgid ""
-#| "<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
-#| "authorinitials> <revremark>bug fix</revremark>"
+msgid ""
+"<revnumber>1.29</revnumber> <date>28 Aug 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>development</revremark>"
+msgstr ""
+"<revnumber>1.29</revnumber> <date>28 de agosto de 2018</date> "
+"<authorinitials>ss</authorinitials> <revremark>desarrollo</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
msgid ""
"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
msgid ""
"<revnumber>1.27</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>fine tuning of the python port</revremark>"
"python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
+#: C/index.docbook:107
msgid ""
"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>port all tools from perl/bash to python</"
"de perl/bash a python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:107
+#: C/index.docbook:113
msgid ""
"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
"limpieza</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:113
+#: C/index.docbook:119
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:119
+#: C/index.docbook:125
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:125
+#: C/index.docbook:131
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:131
+#: C/index.docbook:137
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:137
+#: C/index.docbook:143
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:143
+#: C/index.docbook:149
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:149
+#: C/index.docbook:155
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:155
+#: C/index.docbook:161
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:161
+#: C/index.docbook:167
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:167
+#: C/index.docbook:173
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:173
+#: C/index.docbook:179
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:179
+#: C/index.docbook:185
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:185
+#: C/index.docbook:191
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:191
+#: C/index.docbook:197
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:204
+#: C/index.docbook:210
msgid "Introduction"
msgstr "Introducción"
#. (itstool) path: chapter/para
-#: C/index.docbook:206
+#: C/index.docbook:212
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:212
+#: C/index.docbook:218
msgid "What is GTK-Doc?"
msgstr "¿Qué es GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:214
+#: C/index.docbook:220
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:222
+#: C/index.docbook:228
msgid "How Does GTK-Doc Work?"
msgstr "¿Cómo funciona GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:224
+#: C/index.docbook:230
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:231
+#: C/index.docbook:237
msgid ""
"GTK-Doc consists of a number of python scripts, each performing a different "
"step in the process."
"diferente en el proceso."
#. (itstool) path: sect1/para
-#: C/index.docbook:236
+#: C/index.docbook:242
msgid "There are 5 main steps in the process:"
msgstr "Existen 5 pasos importantes en el proceso:"
#. (itstool) path: listitem/para
-#: C/index.docbook:243
+#: C/index.docbook:249
+#, fuzzy
+#| 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)."
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)."
+"source files with the documentation for each function, macro, structs or "
+"unions, etc."
msgstr ""
"<guilabel>Escribir la documentación.</guilabel> El autor rellena los "
"archivos de fuentes con la documentación para cada función, macro, unión, "
"lo que ya no se recomienda)."
#. (itstool) path: listitem/para
-#: C/index.docbook:253
+#: C/index.docbook:258
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:270
+#: C/index.docbook:275
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:276
+#: C/index.docbook:281
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:283
+#: C/index.docbook:288
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:292
+#: C/index.docbook:297
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:298
+#: C/index.docbook:303
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:306
+#: C/index.docbook:311
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:324
+#: C/index.docbook:329
msgid "Getting GTK-Doc"
msgstr "Obtener GTK-Doc"
#. (itstool) path: sect2/title
-#: C/index.docbook:327
+#: C/index.docbook:332
msgid "Requirements"
msgstr "Requerimientos"
#. (itstool) path: sect2/para
-#: C/index.docbook:328
+#: C/index.docbook:333
msgid ""
"<guilabel>python 2/3</guilabel> - the main scripts are written in python."
msgstr ""
"python."
#. (itstool) path: sect2/para
-#: C/index.docbook:331
+#: C/index.docbook:336
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:335
+#: C/index.docbook:340
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:339
+#: C/index.docbook:344
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:352
msgid "About GTK-Doc"
msgstr "Acerca de GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:349 C/index.docbook:363
+#: C/index.docbook:354
+msgid ""
+"Historically GTK-Doc was used to generate template files from the sources "
+"code. These template files could be used by developers to enter the API "
+"documentation. This approach was rather inconvenient because it required to "
+"keep the generated files under version control. Since GTK-Doc 1.9 it became "
+"possible to place all API information into source comments, which made the "
+"template support obsolete. In version 1.26 template support has been removed."
+msgstr ""
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:364 C/index.docbook:378
msgid "(FIXME)"
msgstr "(ARRÉGLAME)"
#. (itstool) path: sect1/para
-#: C/index.docbook:353
+#: C/index.docbook:368
+#| msgid ""
+#| "(History, authors, web pages, mailing list, license, future plans, "
+#| "comparison with other similar systems.)"
msgid ""
-"(History, authors, web pages, mailing list, license, future plans, "
-"comparison with other similar systems.)"
+"(authors, web pages, mailing list, license, future plans, comparison with "
+"other similar systems.)"
msgstr ""
-"(Historia, autores, páginas web, listas de correo, licencias, planes "
-"futuros, comparación con otros sistemas similares.)"
+"(autores, páginas web, listas de correo, licencias, planes futuros, "
+"comparación con otros sistemas similares.)"
#. (itstool) path: sect1/title
-#: C/index.docbook:361
+#: C/index.docbook:376
msgid "About this Manual"
msgstr "Acerca de este manual"
#. (itstool) path: sect1/para
-#: C/index.docbook:367
+#: C/index.docbook:382
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
-msgid "Setting up your project"
-msgstr "Configurando su proyecto"
+#: C/index.docbook:391
+msgid "Project Setup"
+msgstr "Configuración del proyecto"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:393
+msgid ""
+"This Chapter describes the steps that are necessary to integrate GTK-Doc "
+"into your project. The integration of GTK-Doc into a project includes the "
+"following steps:"
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:401
+msgid ""
+"Preparation of the directory structure and creating required configuration "
+"files for your GTK-Doc documentation (see <link linkend=\"settingup_docfiles"
+"\"> Setting up a skeleton documentation</link>)."
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:409
+msgid ""
+"Adjusting the build system to build your documentation using the GTK-Doc "
+"tools. Multiple build systems are supported, in this manual we describe how "
+"to integrate GTK-Doc with <link linkend=\"settingup_autotools\">Autotools</"
+"link>, <link linkend=\"settingup_cmake\">CMake</link>, and <link linkend="
+"\"settingup_plain_makefiles\">plain Makefiles</link>."
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:419
+msgid ""
+"Adding GTK-Doc specific files to version control and deciding which files to "
+"ignore (see <link linkend=\"settingup_vcs\"> Integration with version "
+"control systems</link>)."
+msgstr ""
#. (itstool) path: chapter/para
-#: C/index.docbook:378
-msgid ""
-"The next sections describe what steps to perform to integrate GTK-Doc into "
-"your project. Theses sections assume we work on a project called 'meep'. "
-"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 ""
-"Las siguientes secciones describen los pasos que realizar para integrar GTK-"
-"Doc en su proyecto. Estas secciones asumen que se trabaja en un proyecto "
-"llamado «meep». Este proyecto contiene una biblioteca llamada «libmeep» y "
-"una aplicación final de usuario llamada «meeper». También se asume que usará "
-"«autoconf» y «automake». En la sección <link linkend=\"plain_makefiles"
-"\">Integración con makefiles u otros sistemas de construcción</link> se "
-"describen las necesidades básicas para trabajar con un sistema de "
-"construcción diferente."
+#: C/index.docbook:427
+msgid ""
+"The following sections assume we work on a project called <code>meep</code>. "
+"This project contains two packages (or modules), a library called "
+"<code>libmeep</code> and an end-user app called <code>meeper</code>."
+msgstr ""
+"La siguiente sección asume que se trabaja con un proyecto llamado "
+"<code>meep</code>. Este proyecto contiene dos paquetes (o módulos), una "
+"biblioteca llamada <code>libmeep</code> y una aplicación de usuario final "
+"llamada <code>meeper</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:389
+#: C/index.docbook:436
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:438
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."
+"A common convention is to place documentation into a folder called "
+"<code>docs</code> inside your top-level project directory. We usually "
+"distinguish between <emphasis>reference documentation</emphasis> intended "
+"for developers and an <emphasis>user manual</emphasis> intended for end-"
+"users. Again the convention is to have separate folders for both. We usually "
+"place the reference documentation in a folder named <code>reference</code> "
+"and the end-user manual in a folder named <code>help</code> as. According to "
+"the above convention the documentation for our <code>libmeep</code> package "
+"would be placed into: <code>docs/reference/libmeep</code>. For packages with "
+"just one library or application the documentation could also be placed "
+"directly into <code>docs/reference</code>. It is not mandatory to use the "
+"above convention, but if you choose to use a different directory structure "
+"you must adjust your build system configuration to match your directory "
+"structure."
msgstr ""
-"Bajo su carpeta de nivel superior cree carpetas llamadas docs/reference (de "
-"esta forma también puede tener docs/help para la documentación final de "
-"usuario). Se recomienda crear otra subcarpeta con el nombre doc-package. "
-"Para paquetes con una sola biblioteca este paso no es necesario."
#. (itstool) path: example/title
-#: C/index.docbook:400
-msgid "Example directory structure"
-msgstr "Ejemplo de estructura de carpetas"
+#: C/index.docbook:469
+msgid "Example directory structure of <emphasis>meep</emphasis> project"
+msgstr ""
+"Ejemplo de estructura de carpetas para el proyecto <emphasis>meep</emphasis>"
#. (itstool) path: example/programlisting
-#: C/index.docbook:401
+#: C/index.docbook:471
#, no-wrap
msgid ""
"\n"
"meep/\n"
" docs/\n"
-" reference/\n"
+" reference/ # reference documentation\n"
" libmeep/\n"
" meeper/\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
"\n"
"meep/\n"
" docs/\n"
-" reference/\n"
+" reference/ # reference documentation\n"
" libmeep/\n"
" meeper/\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:398
-msgid "This can then look as shown below: <_:example-1/>"
-msgstr "Esto después aparecerá como se muestra debajo: <_:example-1/>"
+#: C/index.docbook:463
+msgid ""
+"In the following sections we will assume a directory structure for our "
+"<emphasis>meep</emphasis> project that uses the above conventions. <_:"
+"example-1/>"
+msgstr ""
#. (itstool) path: sect1/title
+#: C/index.docbook:488
+#| msgid "Integration with autoconf"
+msgid "Integration with Autotools"
+msgstr "Integración con Autotools"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:489
+msgid ""
+"Integration of GTK-Doc into an autotools-based build system requires the "
+"following steps:"
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:495
+msgid ""
+"Ensure that <application>gtkdocize</application> is run once before the "
+"<filename>configure</filename> script. If an <filename>autogen.sh</filename> "
+"script is present, adjust it to check for GTK-Doc and add a call to "
+"<application>gtkdocize</application>."
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:503
+msgid ""
+"The main purpose of <application>gtkdocize</application> is to make the "
+"<filename>gtk-doc.make</filename> Makefile and the <filename>gtk-doc.m4</"
+"filename> macro definition file available to the build system, either by "
+"copying or linking it into the project."
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:512
+msgid ""
+"Add the necessary <application>autoconf</application> macros to "
+"<filename>configure.ac</filename> to enable GTK-Doc in your build system to "
+"allow configuration of GTK-Doc via the generated <filename>configure</"
+"filename> script."
+msgstr ""
+"Añada las macros de <application>autoconf</application> necesarias a "
+"<filename>configure.ac</filename> para activar GTK-Doc en su sistema de "
+"construcción y permitir la configuración de GTK-Doc generada en el script "
+"<filename>configure</filename>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:518
+msgid ""
+"Among others with registers the <code>--enable-gtk-doc</code> option with "
+"the <filename>configure</filename> script."
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:524
+msgid ""
+"Create an <application>automake</application> script for each application or "
+"library in your project. In the example used in this documentation this step "
+"applies to both <code>meeper</code> and <code>libmeep</code>."
+msgstr ""
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:533
+msgid ""
+"In the following sections, we will perform the above steps in reverse order. "
+"We start with the <application>automake</application> scripts and work our "
+"way up to <filename>configure.ac</filename> and <filename>autogen.sh</"
+"filename>. Then we show how enable Gtk-Doc in the build system and how to "
+"build the documentation."
+msgstr ""
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:543
+msgid "Integration with automake"
+msgstr "Integración con automake"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:545
+#| 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."
+msgid ""
+"First copy the <filename>Makefile.am</filename> from the <filename class="
+"\"directory\">examples</filename> sub-directory of the <ulink url=\"https://"
+"gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am\"> gtkdoc-"
+"sources</ulink> to your project's reference documentation directory (e.g. "
+"<filename class=\"directory\">docs/reference/<package></filename>). A "
+"local copy should be available under e.g. <filename>/usr/share/doc/gtk-doc-"
+"tools/examples/Makefile.am</filename>. If you have multiple packages repeat "
+"this for each one."
+msgstr ""
+"Primero copie el archivo <filename>Makefile.am</filename> de la subcarpeta "
+"<filename class=\"directory\">examples</filename> de <ulink url=\"https://"
+"gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am\"> gtkdoc-"
+"sources</ulink> a la carpeta de documentación de la API de su proyecto "
+"(<filename class=\"directory\">./docs/reference/<paquete></filename>). "
+"Debería haber una copia local disponible en <filename>/usr/share/doc/gtk-doc-"
+"tools/examples/Makefile.am</filename>. Si tiene varios paquetes de "
+"documentación, repítalo para cada uno de ellos."
+
+#. (itstool) path: note/simpara
+#: C/index.docbook:558
+msgid ""
+"Do not forget to add each <filename>Makefile.am</filename> to the "
+"<function>AC_CONFIG_FILES</function> macro in <filename>configure.ac</"
+"filename>. For <filename>docs/reference/libmeep/Makefile.am</filename> you "
+"will need to add the entry <filename>docs/reference/libmeep/Makefile</"
+"filename> to <function>AC_CONFIG_FILES</function>."
+msgstr ""
+"No olvide añadir cada <filename>Makefile.am</filename> a la macro "
+"<function>AC_CONFIG_FILES</function> en <filename>configure.ac</filename>. "
+"Para <filename>docs/reference/libmeep/Makefile.am</filename> deberá añadir "
+"la entrada <filename>docs/reference/libmeep/Makefile</filename> a "
+"<function>AC_CONFIG_FILES</function>."
+
#. (itstool) path: example/title
-#: C/index.docbook:416 C/index.docbook:423
+#: C/index.docbook:570
+msgid "Example directory structure with <filename>Makefiles.am</filename>"
+msgstr ""
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:573
+#, no-wrap
+msgid ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/ # reference documentation\n"
+" libmeep/\n"
+" Makefile.am\n"
+" meeper/\n"
+" Makefile.am\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+msgstr ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/ # reference documentation\n"
+" libmeep/\n"
+" Makefile.am\n"
+" meeper/\n"
+" Makefile.am\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:589
+#, fuzzy
+#| 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."
+msgid ""
+"Next, you need to customize the copied Makefiles and provide values for the "
+"various parameters in each <filename>Makefile.am</filename>. All settings "
+"have a comment above them that describes their purpose and how to customize "
+"the setting. Most settings are used to supply extra flags to the respective "
+"tools to which they apply. Every tool has a variable of the form <option><"
+"TOOLNAME>_OPTIONS</option> (e.g. the tool <application>gtkdoc-mkhtml</"
+"application> has an option named <code>MKHTML_OPTIONS</code>). All the tools "
+"support <option>--help</option> to list the supported options."
+msgstr ""
+"El siguiente paso es editar la configuración dentro de <filename>Makefile."
+"am</filename>. Todos los ajustes tienen un comentario encima que describe su "
+"propósito. Muchos ajustes son opciones adicionales pasadas a las respectivas "
+"herramientas. Cada herramienta tiene una variable de la forma <option><"
+"NOMBRE_DE_LA_HERRAMIENTA>_OPCIONES</option>. Todas las herramientas "
+"soportan <option>--help</option> para listar los parámetros que soportan."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:613
+msgid ""
+"<option>DOC_MODULE</option> is used to provide the name of the package that "
+"is being documentated (e.g. <code>meeper</code>, or <code>libmeep</code>)."
+msgstr ""
+"<option>DOC_MODULE</option> se usa para proporcionar el nombre del paquete "
+"que se está documentando (ej. <code>meeper</code>, o <code>libmeep</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:620
+msgid ""
+"<option>DOC_SOURCE_DIR</option> is used to specify the location of source "
+"directory which GTK-Doc searches for your API documentation. This will "
+"usually be <code> DOC_SOURCE_DIR=$(top_srcdir)/src </code> or a sub-"
+"directory of that directory."
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:633
+msgid ""
+"<option>HFILE_GLOB</option> and <option>CFILE_GLOB</option> are used for "
+"dependencies. Each option take a file-glob (e.g. <code>HFILE_GLOB="
+"$(top_srcdir)/src/*.c</code>). The documentation will be rebuilt if any of "
+"the matched files change."
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:645
+msgid ""
+"<option>EXTRA_HFILES</option> allows to specify extra header files to "
+"include when scanning for API documentation, which are not found under "
+"<code>DOC_SOURCE_DIR</code> (e.g. <code> EXTRA_HFILES=$(top_srcdir}/contrib/"
+"extra.h</code>)."
+msgstr ""
+"<option>EXTRA_HFILES</option> permite especificar archivos de cabeceras "
+"adicionales que incluir al analizar la documentación de la API y que no "
+"están en <code>DOC_SOURCE_DIR</code> (ej. <code> EXTRA_HFILES=$(top_srcdir}/"
+"contrib/extra.h</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:655
+msgid ""
+"<option>IGNORE_HFILES</option> allows to specify header files or directories "
+"to ignore when scanning for API documentation. Use the basename of the file "
+"or directory (e.g. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h "
+"private_code_folder</code>)."
+msgstr ""
+"<option>IGNORE_HFILES</option> permite especificar archivos de cabeceras o "
+"carpetas que ignorar al analizar la documentación de la API. Use el nombre "
+"base del archivo o la carpta (ej. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h "
+"private_code_folder</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:665
+msgid ""
+"<option>HTML_IMAGES</option> allows to specify images files which will be "
+"copied into the <filename>html/</filename> directory of the generated "
+"documentation. If your API documentation includes any images they need to be "
+"added to this option (e.g. <code> HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/"
+"stock_about_24.png</code>)."
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:678
+msgid ""
+"<option>content_files</option> allows to specify extra files that are "
+"included by <code>$(DOC_MAIN_SGML_FILE)</code> (e.g. <code> "
+"content_files=running.xml building.xml changes-2.0.xml</code>)."
+msgstr ""
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:689
+msgid ""
+"<option>expand_content_files</option> allows to specify files where "
+"<emphasis>gtk-doc abbreviations</emphasis> such as <code>#GtkWidget</code> "
+"are expanded (e.g. <code> expand_content_files=running.xml</code>)."
+msgstr ""
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:607
+msgid ""
+"The following list explains the most relevant options. Check the example "
+"<filename>Makefile.am</filename> for additional options. <_:itemizedlist-1/>"
+msgstr ""
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:704
msgid "Integration with autoconf"
msgstr "Integración con autoconf"
-#. (itstool) path: sect1/para
-#: C/index.docbook:418
+#. (itstool) path: sect2/para
+#: C/index.docbook:706
msgid ""
-"Very easy! Just add one line to your <filename>configure.ac</filename> "
-"script."
+"Integration with <application>autoconf</application> is very simple and "
+"includes one required step and an additional optional (but recommended) "
+"step. The first step is to add the <function>GTK_DOC_CHECK</function> macro "
+"to your <filename>configure.ac</filename> script. This registers several "
+"configure options to enable GTK-Doc and allows you to set default arguments "
+"for <application>gtkdocize</application>."
msgstr ""
-"Muy fácil, simplemente añada una línea a su script <filename>configure.ac</"
-"filename>."
+
+#. (itstool) path: warning/simpara
+#: C/index.docbook:718
+msgid ""
+"Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented. The "
+"macro must start at the beginning of the line and should not start with "
+"whitespace."
+msgstr ""
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:725
+msgid ""
+"The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code> to your "
+"<filename>configure.ac</filename>. This is not required but helps "
+"<application>gtkdocize</application> to automatically copy the macro "
+"definition (e.g <filename>gtk-doc.m4</filename>) which contains the "
+"<function>GTK_DOC_CHECK</function> macro to your project's macro directory. "
+"Without this, the GTK_DOC_CHECK macro might not be found and you would need "
+"to explicitly tell the <application>aclocal</application> tool where to find "
+"the macro definition file."
+msgstr ""
+
+#. (itstool) path: example/title
+#: C/index.docbook:738
+#| msgid "Integration with autoconf"
+msgid "Minimal integration with autoconf"
+msgstr "Integración mínima con autoconf"
#. (itstool) path: example/programlisting
-#: C/index.docbook:424
+#: C/index.docbook:739
#, no-wrap
msgid ""
"\n"
-"# check for gtk-doc\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
msgstr ""
"\n"
-"# check for gtk-doc\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
#. (itstool) path: example/title
-#: C/index.docbook:436
-msgid "Keep gtk-doc optional"
-msgstr "Mantener gtk-doc como opcional"
+#: C/index.docbook:754
+#| msgid "Integration with autogen"
+msgid "Integration with optional gtk-doc dependency"
+msgstr "Integración con dependencias opcionales de gtk-doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:437
+#: C/index.docbook:755
#, no-wrap
msgid ""
"\n"
-"# check for gtk-doc\n"
"m4_ifdef([GTK_DOC_CHECK], [\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\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"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
"],[\n"
"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n"
"])\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:431
+#. (itstool) path: sect2/para
+#: C/index.docbook:748
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/>"
+"The above example works, but will require all developers to have gtk-doc "
+"installed. A better way is to make building the documentation optional as "
+"shown in the next example: <_:example-1/>"
msgstr ""
-"Esto requerirá que todos los desarrolladores tengan gtk-doc instalado. Si "
-"para su proyecto es correcto tener una configuración de construcción de api-"
-"doc opcional, puede resolver esto como sigue. Manténgalo como está, ya que "
-"gtkdocize busca en <function>GTK_DOC_CHECK</function> al inicio de la línea. "
-"<_:example-1/>"
-#. (itstool) path: sect1/para
-#: C/index.docbook:448
+#. (itstool) path: sect2/para
+#: C/index.docbook:768
+#, fuzzy
+#| 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:"
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:"
+"The first argument is used to check for the Gtk-Doc version at configure "
+"time. The 2nd, optional argument is used by <application>gtkdocize</"
+"application>. The <symbol>GTK_DOC_CHECK</symbol> macro also adds several "
+"configure switches:"
msgstr ""
"El primer argumento se usa para comprobar gtkdocversion durante la "
"configuración. El segundo, y opcional, argumento lo usa "
"symbol> también añade diversas opciones de configuración:"
#. (itstool) path: listitem/para
-#: C/index.docbook:454
+#: C/index.docbook:777
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:778
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:779
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:780
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:784
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"se instala (lo que tiene sentido para usuarios, pero no para "
"desarrolladores)."
-#. (itstool) path: sect1/para
-#: C/index.docbook:469
-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 ""
-"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."
-
-#. (itstool) path: example/title
-#: C/index.docbook:477
-msgid "Preparation for gtkdocize"
-msgstr "Preparación para gtkdocize"
-
-#. (itstool) path: example/programlisting
-#: C/index.docbook:478
-#, 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:483
+#. (itstool) path: sect2/para
+#: C/index.docbook:792
+#, fuzzy
+#| 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>."
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>."
+"<code>autogen.sh</code>."
msgstr ""
"Después de hacer los cambios en el <filename>configure.ac</filename> "
"actualice el archivo <filename>configure</filename>. Esto se puede hacer "
"volviendo a ejecutar <code>autoreconf -i</code> o <code>autogen.sh</code>."
-#. (itstool) path: sect1/title
-#: C/index.docbook:491
-msgid "Integration with automake"
-msgstr "Integración con automake"
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:493
-msgid ""
-"First copy the <filename>Makefile.am</filename> from the <filename class="
-"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
-"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 ""
-"Primero copie el archivo <filename>Makefile.am</filename> de la subcarpeta "
-"<filename class=\"directory\">examples</filename> de <ulink url=\"https://"
-"git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am\">gtkdoc-sources</"
-"ulink> a la carpeta de documentación de la API de su proyecto (<filename "
-"class=\"directory\">./docs/reference/<package></filename>). Debería "
-"haber una copia local disponible en <filename>/usr/share/doc/gtk-doc-tools/"
-"examples/Makefile.am</filename>. Si tiene varios paquetes de documentación, "
-"repítalo para cada uno de ellos."
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:504
-msgid ""
-"The next step is to edit the settings inside the <filename>Makefile.am</"
-"filename>. All the settings have a comment above that describes their "
-"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 ""
-"El siguiente paso es editar la configuración dentro de <filename>Makefile."
-"am</filename>. Todos los ajustes tienen un comentario encima que describe su "
-"propósito. Muchos ajustes son opciones adicionales pasadas a las respectivas "
-"herramientas. Cada herramienta tiene una variable de la forma <option><"
-"NOMBRE_DE_LA_HERRAMIENTA>_OPCIONES</option>. Todas las herramientas "
-"soportan <option>--help</option> para listar los parámetros que soportan."
-
-#. (itstool) path: sect1/title
-#: C/index.docbook:518
+#. (itstool) path: sect2/title
+#: C/index.docbook:800
msgid "Integration with autogen"
msgstr "Integración con autogen"
-#. (itstool) path: sect1/para
-#: C/index.docbook:520
+#. (itstool) path: sect2/para
+#: C/index.docbook:802
+#, fuzzy
+#| 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."
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."
+"the build infrastructure after the project was checked out from a version "
+"control system (such as git or svn). GTK-Doc comes with a script called "
+"<application>gtkdocize</application> which can be used to copy the necessary "
+"files needed by Gtk-Doc to the source directory."
msgstr ""
"La mayoría de los proyectos tienen un script <filename>autogen.sh</filename> "
"para configurar la infraestructura de construcción después de hacer un "
"que se puede usar en tal script. Se debería ejecutar antes que autoheader, "
"automake o autoconf."
+#. (itstool) path: sect2/para
+#: C/index.docbook:810
+msgid "It should be run before autoreconf, autoheader, automake or autoconf."
+msgstr ""
+
#. (itstool) path: example/title
-#: C/index.docbook:529
+#: C/index.docbook:815
msgid "Running gtkdocize from autogen.sh"
msgstr "Ejecutar gtkdocize desde autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:530
+#: C/index.docbook:816
#, no-wrap
msgid ""
"\n"
"\n"
"gtkdocize || exit 1\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:536
-msgid ""
-"When running <application>gtkdocize</application> it copies <filename>gtk-"
-"doc.make</filename> to your project root (or any directory specified by the "
-"<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 ""
-"Al ejecutar <filename>gtkdocize</filename> copia <filename>gtk-doc.make</"
-"filename> a la raíz de su proyecto (o cualquier carpeta especificada por la "
-"opción <option>--docdir</option>). También comprueba su script de "
-"configuración para la invocación de <function>GTK_DOC_CHECK</function>. Esta "
-"macro se puede usar para pasar parámetros adicionales a "
-"<application>gtkdocize</application>."
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:545
-msgid ""
-"Historically GTK-Doc was generating template files where developers entered "
-"the docs. This turned out to be not so good (e.g. the need for having "
-"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 ""
-"Históricamente GTK-Doc generaba plantillas de archivos donde los "
-"desarrolladores introducían los documentos. Al final esto resulto no ser muy "
-"bueno (por ejemplo, por la necesidad de tener archivos generados bajo un "
-"control de versiones). Desde la versión de DTK-Doc 1.9 las herramientas "
-"pueden obtener toda la información desde los comentarios del código fuente y "
-"por ello se pueden evitar las plantillas. Se anima a los desarrolladores a "
-"mantener su documentación en el código. <application>gtkdocize</application> "
-"ahora soporta una opción <option>--flavour no-tmpl</option> que elije un "
-"makefile que omite completamente el uso de plantillas. Además de añadir la "
-"opción directamente a la línea de comandos al invocarlo, se pueden añadir a "
-"una variable de entorno llamada <symbol>GTKDOCIZE_FLAGS</symbol> o "
-"configurar como un segundo parámetro en la macro <symbol>GTK_DOC_CHECK</"
-"symbol> en el script de configuración. Si nunca ha cambiado un archivo tmpl "
-"(plantilla) a mano, elimine la carpeta una vez (ej. desde el sistema de "
-"control de versiones)."
-
-#. (itstool) path: sect1/title
#. (itstool) path: example/title
-#: C/index.docbook:562 C/index.docbook:579
-msgid "Running the doc build"
-msgstr "Ejecutar la construcción de la documentación"
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:564
-msgid ""
-"After the previous steps it's time to run the build. First we need to rerun "
-"<filename>autogen.sh</filename>. If this script runs configure for you, then "
-"give it the <option>--enable-gtk-doc</option> option. Otherwise manually run "
-"<filename>configure</filename> with this option afterwards."
-msgstr ""
-"Después de los pasos anteriores es hora de ejecutar el constructor. Primero "
-"se debe volver a ejecutar <filename>autogen.sh</filename>. Si este script "
-"ejecuta configure automáticamente, entonces debe pasar la opción <option>--"
-"enable-gtk-doc</option>. De otra forma, ejecute posteriormente "
-"<filename>configure</filename> con esta opción."
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:571
-msgid ""
-"The first make run generates several additional files in the doc-"
-"directories. The important ones are: <filename><package>.types</"
-"filename>, <filename><package>-docs.xml</filename> (in the past ."
-"sgml), <filename><package>-sections.txt</filename>."
-msgstr ""
-"El primer make genera diversas líneas adicionales en las carpetas de "
-"documentación. Las importantes son: <filename><paquete>.types</"
-"filename>, <filename><paquete>-docs.xml</filename> (.sgml en el "
-"pasado), <filename><paquete>-sections.txt</filename>."
+#: C/index.docbook:824
+#| msgid "Running gtkdocize from autogen.sh"
+msgid "Conditionally run gtkdocize from autogen.sh"
+msgstr "Condicionalmente, ejecutar gtkdocize desde autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:580
+#: C/index.docbook:825
#, no-wrap
msgid ""
"\n"
-"./autogen.sh --enable-gtk-doc\n"
-"make\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+" echo \"No gtk-doc support found. You can't build the docs.\"\n"
+"else\n"
+" $GTKDOCIZE || exit 1\n"
+"fi\n"
msgstr ""
"\n"
-"./autogen.sh --enable-gtk-doc\n"
-"make\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+" echo \"No gtk-doc support found. You can't build the docs.\"\n"
+"else\n"
+" $GTKDOCIZE || exit 1\n"
+"fi\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:586
+#. (itstool) path: sect2/para
+#: C/index.docbook:836
+#, fuzzy
+#| 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>."
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."
+"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)."
msgstr ""
-"Ahora puede apuntar su navegador a <filename>docs/reference/<paquete>/"
-"index.html</filename>. Sí, aún es un poco decepcionante. Pero espere, "
-"durante el siguiente capítulo aprenderá a rellenar las páginas con "
-"información."
-
-#. (itstool) path: sect1/title
-#: C/index.docbook:594
-msgid "Integration with version control systems"
-msgstr "Integración con los sistemas de control de versiones"
+"Al ejecutar <filename>gtkdocize</filename> copia <filename>gtk-doc.make</"
+"filename> a la raíz de su proyecto (o cualquier carpeta especificada por la "
+"opción <option>--docdir</option>). También comprueba su script de "
+"configuración para la invocación de <function>GTK_DOC_CHECK</function>. Esta "
+"macro se puede usar para pasar parámetros adicionales a "
+"<application>gtkdocize</application>."
-#. (itstool) path: sect1/para
-#: C/index.docbook:596
-msgid ""
-"As a rule of thumb, it's the files you edit which should go under version "
-"control. For typical projects it's these files: <filename><package>."
-"types</filename>, <filename><package>-docs.xml</filename> (in the "
-"past .sgml), <filename><package>-sections.txt</filename>, "
-"<filename>Makefile.am</filename>."
+#. (itstool) path: sect2/para
+#: C/index.docbook:842
+#, fuzzy
+#| 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>."
+msgid ""
+"<application>gtkdocize</application> checks your <filename>configure.ac</"
+"filename> script for the <function>GTK_DOC_CHECK</function> macro. The "
+"<function>GTK_DOC_CHECK</function> macro can be used to pass extra arguments "
+"to the <application>gtkdocize</application> script. the 2nd parameter in the "
+"<function>GTK_DOC_CHECK</function> macro."
msgstr ""
-"Como regla principal, son los archivos que edita los que deberían estar bajo "
-"el control de versiones. Para proyectos típicos son los archivos: "
-"<filename><paquete>.types</filename>, <filename><paquete>-docs."
-"xml</filename> (anteriormente .sgml), <filename><paquete>-sections."
-"txt</filename>, <filename>Makefile.am</filename>."
+"Al ejecutar <filename>gtkdocize</filename> copia <filename>gtk-doc.make</"
+"filename> a la raíz de su proyecto (o cualquier carpeta especificada por la "
+"opción <option>--docdir</option>). También comprueba su script de "
+"configuración para la invocación de <function>GTK_DOC_CHECK</function>. Esta "
+"macro se puede usar para pasar parámetros adicionales a "
+"<application>gtkdocize</application>."
-#. (itstool) path: sect1/para
-#: C/index.docbook:604
+#. (itstool) path: sect2/para
+#: C/index.docbook:851
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."
+"Alternatively, additional arguments can also be passed to "
+"<application>gtkdocize</application> via the <function>GTKDOCIZE_FLAGS</"
+"function> environment variable, or by directly specifying them to "
+"<application>gtkdocize</application> in <filename>autogen.sh</filename>."
msgstr ""
-"Los archivos de las carpetas <filename>xml/</filename> y <filename>html/</"
-"filename> No deberían estar bajo control de versiones. Tampoco ninguno de "
-"los archivos <filename>.stamp</filename>."
-#. (itstool) path: sect1/title
-#: C/index.docbook:612
-msgid "Integration with plain makefiles or other build systems"
-msgstr "Integración con makefiles u otros sistemas de construcción"
+#. (itstool) path: sect2/title
+#: C/index.docbook:862
+msgid "Executing GTK-Doc from the Build System"
+msgstr "Ejecutar GTH-Doc desde el sistema de construcción"
-#. (itstool) path: sect1/para
-#: C/index.docbook:614
+#. (itstool) path: sect2/para
+#: C/index.docbook:864
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)."
+"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 ""
-"En el caso de que no quiera usar automake y por ello <filename>gtk-doc.mak</"
-"filename> deberá llamar a las herramientas gtkdoc en el orden correcto en "
-"makefiles propios (o en otras herramientas de construcción)."
+"Después de los pasos anteriores es hora de ejecutar el constructor. Primero "
+"se debe volver a ejecutar <filename>autogen.sh</filename>. Si este script "
+"ejecuta configure automáticamente, entonces debe pasar la opción <option>--"
+"enable-gtk-doc</option>. De otra forma, ejecute posteriormente "
+"<filename>configure</filename> con esta opción."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:871
+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 ""
+"El primer make genera diversas líneas adicionales en las carpetas de "
+"documentación. Las importantes son: <filename><paquete>.types</"
+"filename>, <filename><paquete>-docs.xml</filename> (.sgml en el "
+"pasado), <filename><paquete>-sections.txt</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:621
-msgid "Documentation build steps"
-msgstr "Pasos de construcción de la documentación"
+#: C/index.docbook:879
+msgid "Running the doc build"
+msgstr "Ejecutar la construcción de la documentación"
#. (itstool) path: example/programlisting
-#: C/index.docbook:622
+#: C/index.docbook:880
#, 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"
+"./autogen.sh --enable-gtk-doc\n"
+"make\n"
msgstr ""
"\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"
+"./autogen.sh --enable-gtk-doc\n"
+"make\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:636
+#. (itstool) path: sect2/para
+#: C/index.docbook:887
msgid ""
-"One will need to look at the <filename>Makefile.am</filename> and "
-"<filename>gtk-doc.mak</filename> to pick the extra options needed."
+"Now you can point your browser to <filename>docs/reference/<package>/"
+"index.html</filename>. With this initial setup you will only see a very "
+"simple document. The next chapter will teach you how to add API "
+"documentation to your code via special comment blocks. The Chapter "
+"afterwards introduces <link linkend=\"metafiles\">additional files</link> "
+"and shows how to edit the <link linkend=\"metafiles_master\">master "
+"template</link> to add additional chapters and sections to your "
+"documentation files."
msgstr ""
-"Deberá mirar en el archivo <filename>Makefile.am</filename> y <filename>gtk-"
-"doc.mak</filename> para elegir las opciones adicionales necesarias."
#. (itstool) path: sect1/title
-#: C/index.docbook:643
+#: C/index.docbook:903
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:905
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:915
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:916
#, no-wrap
msgid ""
"\n"
" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:653
+#: C/index.docbook:913
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: sect1/title
+#: C/index.docbook:940
+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:942
+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 ""
+"En el caso de que no quiera usar automake y por ello <filename>gtk-doc.mak</"
+"filename> deberá llamar a las herramientas gtkdoc en el orden correcto en "
+"makefiles propios (o en otras herramientas de construcción)."
+
+#. (itstool) path: example/title
+#: C/index.docbook:949
+msgid "Documentation build steps"
+msgstr "Pasos de construcción de la documentación"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:950
+#, 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) <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"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:964
+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 ""
+"Deberá mirar en el archivo <filename>Makefile.am</filename> y <filename>gtk-"
+"doc.mak</filename> para elegir las opciones adicionales necesarias."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:971
+msgid "Integration with version control systems"
+msgstr "Integración con los sistemas de control de versiones"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:973
+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 ""
+"Como regla principal, son los archivos que edita los que deberían estar bajo "
+"el control de versiones. Para proyectos típicos son los archivos: "
+"<filename><paquete>.types</filename>, <filename><paquete>-docs."
+"xml</filename> (anteriormente .sgml), <filename><paquete>-sections."
+"txt</filename>, <filename>Makefile.am</filename>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:981
+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 ""
+"Los archivos de las carpetas <filename>xml/</filename> y <filename>html/</"
+"filename> No deberían estar bajo control de versiones. Tampoco ninguno de "
+"los archivos <filename>.stamp</filename>."
+
#. (itstool) path: chapter/title
-#: C/index.docbook:681
+#: C/index.docbook:991
msgid "Documenting the code"
msgstr "Documentar el código"
#. (itstool) path: chapter/para
-#: C/index.docbook:683
+#: C/index.docbook:993
msgid ""
"GTK-Doc uses source code comment with a special syntax for code "
"documentation. Further it retrieves information about your project structure "
"su proyecto de otras fuentes. En la siguiente sección encontrará información "
"acerca de la sintaxis de los comentarios."
-#. (itstool) path: note/title
-#: C/index.docbook:691
-msgid "Documentation placement"
-msgstr "Ubicación de la documentación"
-
-#. (itstool) path: note/para
-#: C/index.docbook:692
-msgid ""
-"In the past most documentation had to be filled into files residing inside "
-"the <filename>tmpl</filename> directory. This has the disadvantages that the "
-"information is often not updated and also that the file tend to cause "
-"conflicts with version control systems."
-msgstr ""
-"En el pasado la mayoría de la documentación se debía rellenar en campos "
-"dentro de la carpeta <filename>tmpl</filename>. Esto tiene las desventajas "
-"de que la información. Esto tiene las desventajas de que la información no "
-"se actualiza muy a menudo y que el archivo tiene tendencia a causar "
-"conflictos con los sistemas de control de versiones."
-
-#. (itstool) path: note/para
-#: C/index.docbook:698
-msgid ""
-"The avoid the aforementioned problems we suggest putting the documentation "
-"inside the sources. This manual will only describe this way of documenting "
-"code."
-msgstr ""
-"Para evitar los problemas anteriormente mencionados, se sugiere dejar la "
-"documentación dentro de los fuentes. Este manual sólo describe esta forma de "
-"documentar el código."
-
#. (itstool) path: example/title
-#: C/index.docbook:709 C/index.docbook:735
+#: C/index.docbook:1004 C/index.docbook:1030
msgid "GTK-Doc comment block"
msgstr "Bloque de comentario de GTK-Doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:710
+#: C/index.docbook:1005
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:705
+#: C/index.docbook:1000
+#, fuzzy
+#| msgid ""
+#| "The scanner can handle the majority of C headers fine. In the case of "
+#| "receiving warnings from the scanner that look like a special case, one "
+#| "can hint GTK-Doc to skip over them. <_:example-1/>"
msgid ""
-"The scanner can handle the majority of C headers fine. In the case of "
-"receiving warnings from the scanner that look like a special case, one can "
-"hint GTK-Doc to skip over them. <_:example-1/>"
+"The GTK-Doc scanner can handle the majority of C headers fine. In the case "
+"of receiving warnings from the scanner that look like a special case, one "
+"can hint GTK-Doc to skip over them. <_:example-1/>"
msgstr ""
"El analizador puede manejar bien la mayoría de cabeceras de C. En el caso de "
"recibir avisos del analizador que parecen casos especiales, puede sugerir a "
"GTK-Doc que los omita. <_:example-1/>"
#. (itstool) path: note/title
-#: C/index.docbook:719
+#: C/index.docbook:1014
msgid "Limitations"
msgstr "Limitaciones"
#. (itstool) path: note/para
-#: C/index.docbook:720
+#: C/index.docbook:1015
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:1025
msgid "Documentation comments"
msgstr "Comentarios de la documentación"
#. (itstool) path: example/programlisting
-#: C/index.docbook:736
+#: C/index.docbook:1031
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:732
+#: C/index.docbook:1027
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:1040
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:1046
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:1063
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:1069
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:1059
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:1084
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:1089
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:1095
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:1100
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:1106
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:1111
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:1116
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:1078
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:1125
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:1134
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:1145
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:1151
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:1160
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:1161
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:905
+#: C/index.docbook:1200
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:1206
+#, fuzzy
+#| 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."
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."
+"comment those symbols too. This helps other developers to understand your "
+"code. Therefore we recommend to comment these using normal comments (without "
+"the 2nd '*' in the first line). If later the function needs to be made "
+"public, all one needs to do is to add another '*' in the comment block and "
+"insert the symbol name at the right place inside the sections file."
msgstr ""
"Tal y como se ha mencionado antes, la documentación anterior de GTK-Doc es "
"para documentar la API pública .Por ello, no se puede escribir documentación "
"secciones."
#. (itstool) path: sect1/title
-#: C/index.docbook:925
+#: C/index.docbook:1221
msgid "Documenting sections"
msgstr "Documentar secciones"
#. (itstool) path: sect1/para
-#: C/index.docbook:927
+#: C/index.docbook:1223
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:1231
msgid "Section comment block"
msgstr "Bloque de comentarios en una sección"
#. (itstool) path: example/programlisting
-#: C/index.docbook:936
+#: C/index.docbook:1232
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:955
+#: C/index.docbook:1251
msgid "SECTION:<name>"
msgstr "SECCIÓN <nombre>"
#. (itstool) path: listitem/para
-#: C/index.docbook:957
+#: C/index.docbook:1253
msgid ""
"The name links the section documentation to the respective part in the "
"<filename><package>-sections.txt</filename> file. The name given here "
"archivo <filename><paquete>-sections.txt</filename>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:966
+#: C/index.docbook:1262
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:968
+#: C/index.docbook:1264
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:1271
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:977
+#: C/index.docbook:1273
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:1280
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:986
+#: C/index.docbook:1282
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:1290
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:996
+#: C/index.docbook:1292
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:1298
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1009
+#: C/index.docbook:1305
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:1317
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:1329
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:1338
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:1300
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:1350
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1056
+#: C/index.docbook:1352
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:1361
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1067
+#: C/index.docbook:1363
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:1374
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:1383
msgid "Documenting symbols"
msgstr "Documentar símbolos"
#. (itstool) path: sect1/para
-#: C/index.docbook:1089
+#: C/index.docbook:1385
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:1393 C/index.docbook:1459
msgid "General tags"
msgstr "Etiquetas generales"
#. (itstool) path: sect2/para
-#: C/index.docbook:1099
+#: C/index.docbook:1395
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:1400
msgid "Versioning Tags"
msgstr "Versionado de etiquetas"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1105
+#: C/index.docbook:1401
msgid "Since:"
msgstr "Desde:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1107
+#: C/index.docbook:1403
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:1408
msgid "Deprecated:"
msgstr "Obsoleto:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1114
+#: C/index.docbook:1410
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:1418
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:1424
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:1430
msgid "Stability Tags"
msgstr "Etiquetas de estabilidad"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1135
+#: C/index.docbook:1431
msgid "Stability: Stable"
msgstr "Estabilidad: estable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1137
+#: C/index.docbook:1433
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:1440
msgid "Stability: Unstable"
msgstr "Estabilidad: inestable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1146
+#: C/index.docbook:1442
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:1448
msgid "Stability: Private"
msgstr "Estabilidad: privado"
#. (itstool) path: listitem/para
-#: C/index.docbook:1154
+#: C/index.docbook:1450
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:1460
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1184 C/index.docbook:1194
+#: C/index.docbook:1480 C/index.docbook:1490
msgid "Annotations"
msgstr "Anotaciones"
#. (itstool) path: sect2/para
-#: C/index.docbook:1186
+#: C/index.docbook:1482
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:1491
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1216 C/index.docbook:1245
+#: C/index.docbook:1512 C/index.docbook:1541
msgid "Function comment block"
msgstr "Bloque de comentario de función"
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1518
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:1524
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:1529
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:1514 C/index.docbook:1600
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Recuerde: <_:itemizedlist-1/>"
#. (itstool) path: sect2/para
-#: C/index.docbook:1240
+#: C/index.docbook:1536
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:1542
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1267
+#: C/index.docbook:1563
msgid "Function tags"
msgstr "Etiquetas de funciones"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1268 C/index.docbook:1475
+#: C/index.docbook:1564 C/index.docbook:1771
msgid "Returns:"
msgstr "Devuelve:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1270
+#: C/index.docbook:1566
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:1571
msgid "@...:"
msgstr "@...:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1277
+#: C/index.docbook:1573
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:1583 C/index.docbook:1585
msgid "Property comment block"
msgstr "Bloque de comentario de propiedad"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1290
+#: C/index.docbook:1586
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1302 C/index.docbook:1321
+#: C/index.docbook:1598 C/index.docbook:1617
msgid "Signal comment block"
msgstr "Bloque de comentario de señal"
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1604
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:1610
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:1618
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1339 C/index.docbook:1340
+#: C/index.docbook:1635 C/index.docbook:1636
msgid "Struct comment block"
msgstr "Bloque de comentario de estructura"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1341
+#: C/index.docbook:1637
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1652
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:1658
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:1664
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:1676 C/index.docbook:1677
msgid "Enum comment block"
msgstr "Enumerar bloques de comentarios"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1382
+#: C/index.docbook:1678
#, no-wrap
msgid ""
"\n"
"} Something;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1399
+#: C/index.docbook:1695
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:1410
+#: C/index.docbook:1706
msgid "Inline program documentation"
msgstr "Documentación en línea del programa"
#. (itstool) path: sect1/para
-#: C/index.docbook:1411
+#: C/index.docbook:1707
msgid ""
"You can document programs and their commandline interface using inline "
"documentation."
"documentación en línea."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1417
+#: C/index.docbook:1713
msgid "Tags"
msgstr "Etiquetas"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1419
+#: C/index.docbook:1715
msgid "PROGRAM"
msgstr "PROGRAM"
#. (itstool) path: listitem/para
-#: C/index.docbook:1422
+#: C/index.docbook:1718
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:1429
+#: C/index.docbook:1725
msgid "@short_description:"
msgstr "@short_description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1431
+#: C/index.docbook:1727
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:1438
+#: C/index.docbook:1734
msgid "@synopsis:"
msgstr "@synopsis:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1440
+#: C/index.docbook:1736
msgid ""
"Defines the arguments, or list of arguments that the program can take. "
"(Optional)"
"(Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1448
+#: C/index.docbook:1744
msgid "@see_also:"
msgstr "@see_also:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1450
+#: C/index.docbook:1746
msgid "See Also manual page section. (Optional)"
msgstr "Página del manual Ver también. (Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1457
+#: C/index.docbook:1753
msgid "@arg:"
msgstr "@arg:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1459
+#: C/index.docbook:1755
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:1466
+#: C/index.docbook:1762
msgid "Description:"
msgstr "Description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1468
+#: C/index.docbook:1764
msgid "A longer description of the program."
msgstr "Una descripción más larga del programa."
#. (itstool) path: listitem/para
-#: C/index.docbook:1477
-msgid "Specificy what value(s) the program returns. (Optional)"
+#: C/index.docbook:1773
+#, fuzzy
+#| msgid "Specificy what value(s) the program returns. (Optional)"
+msgid "Specify what value(s) the program returns. (Optional)"
msgstr "Especifique qué valores devuelve el programa. (Opcional)"
#. (itstool) path: sect2/title
-#: C/index.docbook:1486
+#: C/index.docbook:1782
msgid "Example of program documentation."
msgstr "Ejemplo de documentación de un programa."
#. (itstool) path: example/title
-#: C/index.docbook:1487
+#: C/index.docbook:1783
msgid "Program documentation block"
msgstr "Bloque de documentación del programa"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1488
+#: C/index.docbook:1784
#, no-wrap
msgid ""
"\n"
"}\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1514
+#: C/index.docbook:1810
msgid "Useful DocBook tags"
msgstr "Etiquetas DocBook útiles"
#. (itstool) path: sect1/para
-#: C/index.docbook:1516
+#: C/index.docbook:1812
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:1525
+#: C/index.docbook:1821
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1521
+#: C/index.docbook:1817
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:1538
+#: C/index.docbook:1834
#, no-wrap
msgid ""
"\n"
"<function>...</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1535
+#: C/index.docbook:1831
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
"informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1547
+#: C/index.docbook:1843
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1558
+#: C/index.docbook:1854
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1544
+#: C/index.docbook:1840
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:1577
+#: C/index.docbook:1873
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1574
+#: C/index.docbook:1870
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Para incluir listas de topos: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1597
+#: C/index.docbook:1893
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1594
+#: C/index.docbook:1890
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:1610
+#: C/index.docbook:1906
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1607
+#: C/index.docbook:1903
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "Para referirse a un tipo: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1619
+#: C/index.docbook:1915
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1616
+#: C/index.docbook:1912
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:1628
+#: C/index.docbook:1924
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1625
+#: C/index.docbook:1921
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:1637
+#: C/index.docbook:1933
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1634
+#: C/index.docbook:1930
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:1648
+#: C/index.docbook:1944
#, no-wrap
msgid ""
"\n"
"<emphasis>This is important</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1645
+#: C/index.docbook:1941
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Para enfatizar un texto: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1657
+#: C/index.docbook:1953
#, no-wrap
msgid ""
"\n"
"<filename>/home/user/documents</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1654
+#: C/index.docbook:1950
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Para uso de nombres de archivo: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1666
+#: C/index.docbook:1962
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1663
+#: C/index.docbook:1959
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "Para referirse a claves: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1676
+#: C/index.docbook:1972
msgid "Filling the extra files"
msgstr "Rellenar campos adicionales"
#. (itstool) path: chapter/para
-#: C/index.docbook:1678
+#: C/index.docbook:1974
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:1687
+#: C/index.docbook:1983
msgid "Editing the types file"
msgstr "Editar los tipos de archivo"
#. (itstool) path: sect1/para
-#: C/index.docbook:1689
+#: C/index.docbook:1985
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:1698
-msgid "Example types file snippet"
-msgstr "Fragmento de ejemplo de tipos de archivo"
+#: C/index.docbook:1994
+#| msgid "<package>.types"
+msgid "Example <package>.types file"
+msgstr "Ejemplo de archivo <paquete>.tipos"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1699
+#: C/index.docbook:1995
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1710
+#: C/index.docbook:2006
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:1719
+#: C/index.docbook:2015
msgid "Editing the master document"
msgstr "Editar la sección maestra del documento"
#. (itstool) path: sect1/para
-#: C/index.docbook:1721
+#: C/index.docbook:2017
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:1728
+#: C/index.docbook:2024
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:1738
+#: C/index.docbook:2034
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:1747
+#: C/index.docbook:2043
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:1754
+#: C/index.docbook:2050
msgid "Master document header"
msgstr "Cabecera del documento maestro"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1755
+#: C/index.docbook:2051
#, no-wrap
msgid ""
"\n"
" <title>[Insert title here]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1771
+#: C/index.docbook:2067
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:1777
+#: C/index.docbook:2073
msgid "Optional part in the master document"
msgstr "Parte opcional en el documento maestro"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1778
+#: C/index.docbook:2074
#, no-wrap
msgid ""
"\n"
" --> \n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1786
+#: C/index.docbook:2082
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:1794 C/index.docbook:1829
+#: C/index.docbook:2090 C/index.docbook:2125
msgid "Including generated sections"
msgstr "Incluir secciones generadas"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1795
+#: C/index.docbook:2091
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1807
+#: C/index.docbook:2103
msgid "Editing the section file"
msgstr "Editar el archivo de sección"
#. (itstool) path: sect1/para
-#: C/index.docbook:1809
+#: C/index.docbook:2105
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:1815
+#: C/index.docbook:2111
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:1822
+#: C/index.docbook:2118
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:1830
+#: C/index.docbook:2126
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1847
+#: C/index.docbook:2143
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:1859
+#: C/index.docbook:2155
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:1866
+#: C/index.docbook:2162
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:1885
+#: C/index.docbook:2181
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:1899
+#: C/index.docbook:2195
msgid "Controlling the result"
msgstr "Controlar el resultado"
#. (itstool) path: chapter/para
-#: C/index.docbook:1901
+#: C/index.docbook:2197
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:1910
+#: C/index.docbook:2206
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:1919
+#: C/index.docbook:2215
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:1926
+#: C/index.docbook:2222
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:1934
+#: C/index.docbook:2230
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:1941
+#: C/index.docbook:2237
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:1950
+#: C/index.docbook:2246
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:1965
+#: C/index.docbook:2261
msgid "Modernizing the documentation"
msgstr "Modernizar la documentación"
#. (itstool) path: chapter/para
-#: C/index.docbook:1967
+#: C/index.docbook:2263
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:1973
+#: C/index.docbook:2269
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1975
+#: C/index.docbook:2271
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:1980
+#: C/index.docbook:2276
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:1991
+#: C/index.docbook:2287
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"<filename>configure.ac</filename> y lo tendrá hecho."
#. (itstool) path: sect1/title
-#: C/index.docbook:2003
+#: C/index.docbook:2299
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:2005
+#: C/index.docbook:2301
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:2016
+#: C/index.docbook:2312
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:2022
+#: C/index.docbook:2318
msgid "Enable gtkdoc-check"
msgstr "Activar gtkdoc-check"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2023
+#: C/index.docbook:2319
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2018
+#: C/index.docbook:2314
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:2036
+#: C/index.docbook:2332
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:2038
+#: C/index.docbook:2334
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:2048
+#: C/index.docbook:2344
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:2058
+#: C/index.docbook:2355
msgid "Use pre-generated entities"
msgstr "Usar entidades generadas previamenet"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2059
+#: C/index.docbook:2356
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2050
+#: C/index.docbook:2346
+#, fuzzy
+#| 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/>"
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/>"
+"the entity file is included in the master template and how the entities are "
+"used. The entities can also be used in all generated files, GTK-Doc will use "
+"the same xml header in generated xml files. <_:example-1/>"
msgstr ""
"El makefile distribuído con esta versión genera un archivo de entidad en "
"<filename>xml/gtkdocentities.ent</filename>, que contiene las entidades "
"archivos XML generados. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:2084
+#: C/index.docbook:2381
msgid "Documenting other interfaces"
msgstr "Documentar otras interfaces"
#. (itstool) path: chapter/para
-#: C/index.docbook:2086
+#: C/index.docbook:2383
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:2093
+#: C/index.docbook:2390
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:2095
+#: C/index.docbook:2392
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:2102
+#: C/index.docbook:2399
msgid "Document the tool"
msgstr "Documentar la herramienta"
#. (itstool) path: sect2/para
-#: C/index.docbook:2104
+#: C/index.docbook:2401
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:2114
+#: C/index.docbook:2411
msgid "Adding the extra configure check"
msgstr "Añadir la comprobación de configuración adicional"
#. (itstool) path: example/title
-#: C/index.docbook:2117 C/index.docbook:2135
+#: C/index.docbook:2414 C/index.docbook:2432
msgid "Extra configure checks"
msgstr "Comprobaciones de configuración adicionales"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2118
+#: C/index.docbook:2415
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2132
+#: C/index.docbook:2429
msgid "Adding the extra makefile rules"
msgstr "Añadir reglas de makefile adicionales"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2136
+#: C/index.docbook:2433
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2158
+#: C/index.docbook:2455
msgid "DBus interfaces"
msgstr "Interfaces de DBus"
#. (itstool) path: sect1/para
-#: C/index.docbook:2160
+#: C/index.docbook:2457
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:2169
+#: C/index.docbook:2466
msgid "Frequently asked questions"
msgstr "Preguntas más frecuentes"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2173
+#: C/index.docbook:2470
msgid "Question"
msgstr "Pregunta"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2174
+#: C/index.docbook:2471
msgid "Answer"
msgstr "Respuesta"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2176
+#: C/index.docbook:2473
msgid "No class hierarchy."
msgstr "Sin jerarquía de clases."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2177
+#: C/index.docbook:2474
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:2183
+#: C/index.docbook:2480
msgid "Still no class hierarchy."
msgstr "Aún sin jerarquía de clases."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2184
+#: C/index.docbook:2481
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:2190
+#: C/index.docbook:2487
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:2191
+#: C/index.docbook:2488
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:2198
+#: C/index.docbook:2495
msgid "No symbol index."
msgstr "Sin índice de símbolos."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2199
+#: C/index.docbook:2496
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:2205
+#: C/index.docbook:2502
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:2206
+#: C/index.docbook:2503
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:2212
+#: C/index.docbook:2509
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:2213
+#: C/index.docbook:2510
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2219
+#: C/index.docbook:2516
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:2220
+#: C/index.docbook:2517
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:2228
+#: C/index.docbook:2525
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:2229
+#: C/index.docbook:2526
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:2238
+#: C/index.docbook:2535
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:2239
+#: C/index.docbook:2536
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:2247
+#: C/index.docbook:2544
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:2248
+#: C/index.docbook:2545
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:2253
+#: C/index.docbook:2550
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "múltiples «ID» para la restricción enlazada: XYZ"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2254
+#: C/index.docbook:2551
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"sections.txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2257
+#: C/index.docbook:2554
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"coincide."
#. (itstool) path: chapter/title
-#: C/index.docbook:2264
+#: C/index.docbook:2561
msgid "Tools related to gtk-doc"
msgstr "Herramientas relacionadas con GTK-Doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2266
+#: C/index.docbook:2563
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:2271
+#: C/index.docbook:2568
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."
"libre que usted elija, como la <_:ulink-1/>, para permitir su uso en "
"software libre."
+#~ msgid "Setting up your project"
+#~ msgstr "Configurando su proyecto"
+
+#~ 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 ""
+#~ "Las siguientes secciones describen los pasos que realizar para integrar "
+#~ "GTK-Doc en su proyecto. Estas secciones asumen que se trabaja en un "
+#~ "proyecto llamado «meep». Este proyecto contiene una biblioteca llamada "
+#~ "«libmeep» y una aplicación final de usuario llamada «meeper». También se "
+#~ "asume que usará «autoconf» y «automake». En la sección <link linkend="
+#~ "\"plain_makefiles\">Integración con makefiles u otros sistemas de "
+#~ "construcción</link> se describen las necesidades básicas para trabajar "
+#~ "con un sistema de construcción diferente."
+
+#~ 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 ""
+#~ "Bajo su carpeta de nivel superior cree carpetas llamadas docs/reference "
+#~ "(de esta forma también puede tener docs/help para la documentación final "
+#~ "de usuario). Se recomienda crear otra subcarpeta con el nombre doc-"
+#~ "package. Para paquetes con una sola biblioteca este paso no es necesario."
+
+#~ msgid "Example directory structure"
+#~ msgstr "Ejemplo de estructura de carpetas"
+
+#~ msgid "This can then look as shown below: <_:example-1/>"
+#~ msgstr "Esto después aparecerá como se muestra debajo: <_:example-1/>"
+
+#~ msgid ""
+#~ "Very easy! Just add one line to your <filename>configure.ac</filename> "
+#~ "script."
+#~ msgstr ""
+#~ "Muy fácil, simplemente añada una línea a su script <filename>configure."
+#~ "ac</filename>."
+
+#~ 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"
+
+#~ msgid "Keep gtk-doc optional"
+#~ msgstr "Mantener gtk-doc como opcional"
+
+#~ 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"
+
+#~ 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 ""
+#~ "Esto requerirá que todos los desarrolladores tengan gtk-doc instalado. Si "
+#~ "para su proyecto es correcto tener una configuración de construcción de "
+#~ "api-doc opcional, puede resolver esto como sigue. Manténgalo como está, "
+#~ "ya que gtkdocize busca en <function>GTK_DOC_CHECK</function> al inicio de "
+#~ "la línea. <_:example-1/>"
+
+#~ 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 ""
+#~ "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."
+
+#~ msgid "Preparation for gtkdocize"
+#~ msgstr "Preparación para gtkdocize"
+
+#~ msgid ""
+#~ "\n"
+#~ "AC_CONFIG_MACRO_DIR(m4)\n"
+#~ msgstr ""
+#~ "\n"
+#~ "AC_CONFIG_MACRO_DIR(m4)\n"
+
+#~ 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 ""
+#~ "Históricamente GTK-Doc generaba plantillas de archivos donde los "
+#~ "desarrolladores introducían los documentos. Al final esto resulto no ser "
+#~ "muy bueno (por ejemplo, por la necesidad de tener archivos generados bajo "
+#~ "un control de versiones). Desde la versión de DTK-Doc 1.9 las "
+#~ "herramientas pueden obtener toda la información desde los comentarios del "
+#~ "código fuente y por ello se pueden evitar las plantillas. Se anima a los "
+#~ "desarrolladores a mantener su documentación en el código. "
+#~ "<application>gtkdocize</application> ahora soporta una opción <option>--"
+#~ "flavour no-tmpl</option> que elije un makefile que omite completamente el "
+#~ "uso de plantillas. Además de añadir la opción directamente a la línea de "
+#~ "comandos al invocarlo, se pueden añadir a una variable de entorno llamada "
+#~ "<symbol>GTKDOCIZE_FLAGS</symbol> o configurar como un segundo parámetro "
+#~ "en la macro <symbol>GTK_DOC_CHECK</symbol> en el script de configuración. "
+#~ "Si nunca ha cambiado un archivo tmpl (plantilla) a mano, elimine la "
+#~ "carpeta una vez (ej. desde el sistema de control de versiones)."
+
+#~ 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 ""
+#~ "Ahora puede apuntar su navegador a <filename>docs/reference/<"
+#~ "paquete>/index.html</filename>. Sí, aún es un poco decepcionante. Pero "
+#~ "espere, durante el siguiente capítulo aprenderá a rellenar las páginas "
+#~ "con información."
+
+#~ msgid "Documentation placement"
+#~ msgstr "Ubicación de la documentación"
+
+#~ 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 ""
+#~ "En el pasado la mayoría de la documentación se debía rellenar en campos "
+#~ "dentro de la carpeta <filename>tmpl</filename>. Esto tiene las "
+#~ "desventajas de que la información. Esto tiene las desventajas de que la "
+#~ "información no se actualiza muy a menudo y que el archivo tiene tendencia "
+#~ "a causar conflictos con los sistemas de control de versiones."
+
+#~ 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 ""
+#~ "Para evitar los problemas anteriormente mencionados, se sugiere dejar la "
+#~ "documentación dentro de los fuentes. Este manual sólo describe esta forma "
+#~ "de documentar el código."
+
+#~ msgid "Example types file snippet"
+#~ msgstr "Fragmento de ejemplo de tipos de archivo"
+
#~ msgid "<guilabel>Python</guilabel> - optional - for gtkdoc-depscan"
#~ msgstr "<guilabel>Python</guilabel>: opcional, para gtkdoc-depscan"
#~ msgid "xxx_get_type()"
#~ msgstr "xxx_get_type()"
-#~ msgid "<package>.types"
-#~ msgstr "<paquete>.tipos"
-
#~ msgid "<package>-sections.txt"
#~ msgstr "<paquete>-sections.txt"
</authorgroup>
<publisher role="maintainer"><publishername>Proyecto 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>
+ <copyright>
+ <year>2007-2019</year>
+ <holder>Stefan Sauer (Kost)</holder>
+ </copyright>
<!-- translators: uncomment this:
<copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision><revnumber>1.28</revnumber> <date>24 de marzo de 2018</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
<revision><revnumber>1.27</revnumber> <date>07 de diciembre de 2017</date> <authorinitials>ss</authorinitials> <revremark>ajustes para la migración a python</revremark></revision>
</othercredit>
<copyright>
- <year>2009 - 2018</year>
+ <year>2009 - 2019</year>
<holder>Daniel Mustieles</holder>
</copyright>
<title>Acerca de GTK-Doc</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>(ARRÉGLAME)</para>
- <para>
- (authors, web pages, mailing list, license, future plans,
- comparison with other similar systems.)
- </para>
+ <para>(autores, páginas web, listas de correo, licencias, planes futuros, comparación con otros sistemas similares.)</para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Project Setup</title>
+ <title>Configuración del proyecto</title>
<para>
This Chapter describes the steps that are necessary to integrate GTK-Doc
</listitem>
</itemizedlist>
- <para>
- The following sections assume we work on a project called
- <code>meep</code>.
- This project contains two packages (or modules),
- a library called <code>libmeep</code> and an end-user app
- called <code>meeper</code>.
- </para>
+ <para>La siguiente sección asume que se trabaja con un proyecto llamado <code>meep</code>. Este proyecto contiene dos paquetes (o módulos), una biblioteca llamada <code>libmeep</code> y una aplicación de usuario final llamada <code>meeper</code>.</para>
<sect1 id="settingup_docfiles">
<title>Configurar el esquema de la documentación</title>
</sect1>
<sect1 id="settingup_autotools">
- <title>Integration with Autotools</title>
+ <title>Integración con Autotools</title>
<para>
Integration of GTK-Doc into an autotools-based build system requires the
following steps:
</para>
</listitem>
<listitem>
- <para>
- Add the necessary <application>autoconf</application> macros to
- <filename>configure.ac</filename> to enable GTK-Doc in your build
- system to allow configuration of GTK-Doc via the generated
- <filename>configure</filename> script.
- </para>
+ <para>Añada las macros de <application>autoconf</application> necesarias a <filename>configure.ac</filename> para activar GTK-Doc en su sistema de construcción y permitir la configuración de GTK-Doc generada en el script <filename>configure</filename>.</para>
<para>
Among others with registers the <code>--enable-gtk-doc</code>
option with the <filename>configure</filename> script.
<sect2 id="settingup_automake">
<title>Integración con automake</title>
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub-directory of the
- <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
- gtkdoc-sources</ulink>
- to your project's reference documentation directory (e.g.
- <filename class="directory">docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple packages repeat this for each one.
- </para>
+ <para>Primero copie el archivo <filename>Makefile.am</filename> de la subcarpeta <filename class="directory">examples</filename> de <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am"> gtkdoc-sources</ulink> a la carpeta de documentación de la API de su proyecto (<filename class="directory">./docs/reference/<paquete></filename>). Debería haber una copia local disponible en <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Si tiene varios paquetes de documentación, repítalo para cada uno de ellos.</para>
<note>
- <simpara>
- Do not forget to add each <filename>Makefile.am</filename>
- to the <function>AC_CONFIG_FILES</function> macro in
- <filename>configure.ac</filename>. For
- <filename>docs/reference/libmeep/Makefile.am</filename> you will
- need to add the entry
- <filename>docs/reference/libmeep/Makefile</filename>
- to <function>AC_CONFIG_FILES</function>.
- </simpara>
+ <simpara>No olvide añadir cada <filename>Makefile.am</filename> a la macro <function>AC_CONFIG_FILES</function> en <filename>configure.ac</filename>. Para <filename>docs/reference/libmeep/Makefile.am</filename> deberá añadir la entrada <filename>docs/reference/libmeep/Makefile</filename> a <function>AC_CONFIG_FILES</function>.</simpara>
</note>
<example>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
</para>
<para>
- <example><title>Minimal integration with autoconf</title>
- <programlisting><![CDATA[
+ <example><title>Integración mínima con autoconf</title>
+ <programlisting>
# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
# optional: register gtk-doc in configure
GTK_DOC_CHECK([1.28])
-]]></programlisting>
+</programlisting>
</example>
</para>
<para>
<example>
- <title>Conditionally run gtkdocize from autogen.sh</title>
- <programlisting><![CDATA[
-GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+ <title>Condicionalmente, ejecutar gtkdocize desde autogen.sh</title>
+ <programlisting>
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
if test $? -ne 0; then
echo "No gtk-doc support found. You can't build the docs."
else
$GTKDOCIZE || exit 1
fi
-]]></programlisting>
+</programlisting>
</example>
</para>
</sect2>
<sect2 id="settingup_firstrun">
- <title>Executing GTK-Doc from the Build System</title>
+ <title>Ejecutar GTH-Doc desde el sistema de construcción</title>
<para>Después de los pasos anteriores es hora de ejecutar el constructor. Primero se debe volver a ejecutar <filename>autogen.sh</filename>. Si este script ejecuta configure automáticamente, entonces debe pasar la opción <option>--enable-gtk-doc</option>. De otra forma, ejecute posteriormente <filename>configure</filename> con esta opción.</para>
<para>El primer make genera diversas líneas adicionales en las carpetas de documentación. Las importantes son: <filename><paquete>.types</filename>, <filename><paquete>-docs.xml</filename> (.sgml en el pasado), <filename><paquete>-sections.txt</filename>.</para>
<varlistentry>
<term>Devuelve:</term>
<listitem>
- <para>Especifique qué valores devuelve el programa. (Opcional)</para>
+ <para>
+ Specify what value(s) the program returns. (Optional)
+ </para>
</listitem>
</varlistentry>
</programlisting>
</informalexample></para>
- <para>Para incluir un código de ejemplo: <informalexample>
- <programlisting>
-<example>
- <title>Using a GHashTable.</title>
- <programlisting>
+ <para>
+ To include example code:
+ <informalexample>
+ <programlisting><![CDATA[
+<example>
+ <title>Using a GHashTable.</title>
+ <programlisting language="C">
...
- </programlisting>
-</example>
-</programlisting>
- </informalexample> o posiblemente este, para fragmentos de código muy cortos que no necesitan título: <informalexample>
- <programlisting>
-<informalexample>
- <programlisting>
+ </programlisting>
+</example>
+]]></programlisting>
+ </informalexample>
+ or possibly this, for very short code fragments which don't need a title:
+ <informalexample>
+ <programlisting><![CDATA[
+<informalexample>
+ <programlisting language="C">
...
- </programlisting>
-</informalexample>
-</programlisting>
- </informalexample>. El último GTK-Doc también soporta abreviación: |[ ... ]|</para>
+ </programlisting>
+</informalexample>
+]]></programlisting>
+ </informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
+ For the latter GTK-Doc also supports an abbreviation:
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
+ ...
+]|
+]]></programlisting>
+ </informalexample>
+ </para>
<para>Para incluir listas de topos: <informalexample>
<programlisting>
<para>Si su biblioteca o aplicación incluye GObjects puede querer que sus señales, argumentos y/o parámetros y posición en la jerarquía se muestre en la documentación. Todo lo que debe hacer es listar las funciones <function>xxx_get_type</function> junto con sus «include» en el archivo <filename><paquete>.types</filename>.</para>
<para>
- <example><title>Example <package>.types file</title>
+ <example><title>Ejemplo de archivo <paquete>.tipos</title>
<programlisting>
#include <gtk/gtk.h>
</authorgroup>
<publisher role="maintainer"><publishername>Projet GTK-Doc</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
<copyright><year>2000, 2005</year> <holder>Dan Mueth et Chris Lyttle</holder></copyright>
- <copyright><year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder></copyright>
+ <copyright>
+ <year>2007-2019</year>
+ <holder>Stefan Sauer (Kost)</holder>
+ </copyright>
<!-- translators: uncomment this:
<copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision>
<revnumber>1.28</revnumber>
<title>À propos de GTK-Doc</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>(À COMPLETER)</para>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
<term>« Returns » :</term>
<listitem>
<para>
- Specificy what value(s) the program returns. (Optional)
+ Specify what value(s) the program returns. (Optional)
</para>
</listitem>
</varlistentry>
</programlisting>
</informalexample></para>
- <para>Pour inclure des extraits de code : <informalexample>
- <programlisting>
-<example>
- <title>Using a GHashTable.</title>
- <programlisting>
+ <para>
+ To include example code:
+ <informalexample>
+ <programlisting><![CDATA[
+<example>
+ <title>Using a GHashTable.</title>
+ <programlisting language="C">
...
- </programlisting>
-</example>
-</programlisting>
- </informalexample> ou ceci, pour des petits fragments de code qui ne nécessitent pas de titre : <informalexample>
- <programlisting>
-<informalexample>
- <programlisting>
+ </programlisting>
+</example>
+]]></programlisting>
+ </informalexample>
+ or possibly this, for very short code fragments which don't need a title:
+ <informalexample>
+ <programlisting><![CDATA[
+<informalexample>
+ <programlisting language="C">
...
- </programlisting>
-</informalexample>
-</programlisting>
- </informalexample> Pour ces derniers, GTK-Doc prend également en charge une abréviation : |[ ... ]|</para>
+ </programlisting>
+</informalexample>
+]]></programlisting>
+ </informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
+ For the latter GTK-Doc also supports an abbreviation:
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
+ ...
+]|
+]]></programlisting>
+ </informalexample>
+ </para>
<para>Pour ajouter une liste à puces : <informalexample>
<programlisting>
<publisher role="maintainer"><publishername>Proxecto 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>
+ <year>2007-2019</year>
<holder>Stefan Sauer (Kost)</holder>
</copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision>
<revnumber>1.28</revnumber>
<title>About GTK-Doc</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
<term>Returns:</term>
<listitem>
<para>
- Specificy what value(s) the program returns. (Optional)
+ Specify what value(s) the program returns. (Optional)
</para>
</listitem>
</varlistentry>
<programlisting><![CDATA[
<example>
<title>Using a GHashTable.</title>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</example>
<informalexample>
<programlisting><![CDATA[
<informalexample>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</informalexample>
]]></programlisting>
</informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
For the latter GTK-Doc also supports an abbreviation:
-<![CDATA[
-|[
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
...
]|
-]]>
+]]></programlisting>
+ </informalexample>
</para>
<para>
<holder>Dan Mueth and Chris Lyttle</holder>
</copyright>
<copyright>
- <year>2007-2015</year>
+ <year>2007-2019</year>
<holder>Stefan Sauer (Kost)</holder>
</copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision>
<revnumber>1.28</revnumber>
<title>GTK-Doc વિશે</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>(FIXME)</para>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
<term>પાછુ આવે છે:</term>
<listitem>
<para>
- Specificy what value(s) the program returns. (Optional)
+ Specify what value(s) the program returns. (Optional)
</para>
</listitem>
</varlistentry>
<programlisting><![CDATA[
<example>
<title>Using a GHashTable.</title>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</example>
<informalexample>
<programlisting><![CDATA[
<informalexample>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</informalexample>
]]></programlisting>
</informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
For the latter GTK-Doc also supports an abbreviation:
-<![CDATA[
-|[
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
...
]|
-]]>
+]]></programlisting>
+ </informalexample>
</para>
<para>
<title>Licença de Documentação Livre GNU</title>
<sect1 id="fdl-preamble">
- <title>0. INTRODUÇÃO</title>
+ <title>0. PREÂMBULO</title>
<para>O propósito desta Licença é fazer um manual, livro-texto, ou outro documento escrito <quote>livre</quote> em seu sentido de liberdade: para garantir a todos a liberdade efetiva de copiá-lo e redistribui-lo, com ou sem modificações, tanto comercialmente como não comercialmente. Em segundo lugar, esta Licença preserva ao autor e ao editor uma forma de obter crédito pelo seu trabalho, enquanto não é considerado responsável por modificações feitas por outros.</para>
<para>Esta licença é um tipo de <quote>copyleft</quote>, que significa que trabalhos derivados do documento precisam ser, por sua vez, livres no mesmo sentido. Ela complementa a Licença Pública Geral GNU (GNU General Public License), que é uma licença copyleft projetada para softwares livres.</para>
- <para>Nós projetamos esta Licença a fim de ser utilizada em manuais de software livre, já que softwares livres precisam de documentações livres: um programa livre deveria vir com manuais que ofereçam as mesmas liberdades que o software proporciona. Mas esta Licença não é limitada a manuais de software; ela pode ser usada para qualquer trabalho de texto, independente do assunto ou se é publicado como um livro impresso. Nós recomendamos esta Licença principalmente para trabalhos cujo propósito seja instrução ou referência.</para>
+ <para>Criamos esta Licença para usá-la para manuais para software livre, porque software livre precisa de documentação livre: um programa livre deve ser fornecido com manuais que proporcionam as mesmas liberdades que o software. Mas esta Licença não está limitada aos manuais de software; pode ser usada para qualquer trabalho textual, independentemente do assunto ou dele ser publicado como um livro impresso. Recomendamos esta Licença principalmente para trabalhos cujo propósito seja instrução ou referência.</para>
</sect1>
<sect1 id="fdl-section1">
<title>1. APLICABILIDADE E DEFINIÇÕES</title>
<para id="fdl-transparent">Uma cópia <quote>Transparente</quote> do <link linkend="fdl-document">Documento</link> significa uma cópia legível por máquina, representada em um formato cuja especificação esteja disponível ao público geral e que cujo conteúdo possa ser visualizado e editado de forma clara e direta por editores de texto genéricos ou programas genéricos de desenho (para imagens compostas de pixels) ou para alguns dos editores de desenho amplamente disponíveis (para desenhos) e que seja apropriado para inclusão em formatadores de texto ou para a tradução automática em uma variedade de formatos apropriados de entrada em formatadores de texto. Uma cópia feita em outro formato de arquivo Transparente cuja marcação, ou ausência desta, tenha sido manipulada para impedir ou desencorajar modificação subsequente pelos leitores não é Transparente. Uma cópia que não é <quote>Transparente</quote> é chamada <quote>Opaco</quote>.</para>
- <para>Exemplos de formatos apropriados para cópias Transparentes incluem ASCII puro sem marcação, formato de entrada Texinfo, formato de entrada LaTex, SGML ou XML usando um DTD publicamente disponível, e HTML simples em conformidade padrão projetado para modificação por humanos. Formatos Opacos incluem PostScript, PDF, formatos proprietários que podem ser lidos ou editados somente por processadores de texto proprietários, SGML ou XML cujos DTD e/ou ferramenta de processamento não estão largamente disponibilizados, e o HTML gerado por máquina produzido por algum processador de texto com propósito apenas de saída.</para>
+ <para>Exemplos de formatos adequados para cópias Transparentes incluem ASCII simples sem marcação, formato de entrada Texinfo, formato de entrada LaTeX, SGML ou XML usando DTD publicamente disponível e HTML simples, conforme padrão, projetados para modificação humana. Os formatos Opacos incluem PostScript, PDF, formatos proprietários que podem ser lidos e editados apenas por processadores de texto proprietários, SGML ou XML para os quais o DTD e/ou ferramentas de processamento não estão geralmente disponíveis e o HTML gerado por máquina produzido por alguns processadores de texto para apenas para fins de saída.</para>
<para id="fdl-title-page">A <quote>Título da página</quote> significa, para um livro impresso, a própria página do título, além das páginas subsequentes necessárias para conter, de forma legível, o material que esta Licença requer que apareça na página do título. Para trabalhos em formatos que não possuem qualquer página de título semelhante, <quote>Título da página</quote> significa o texto próximo à ocorrência mais proeminente do título do trabalho, precedendo o início do corpo do texto.</para>
</sect1>
<sect1 id="fdl-section2">
- <title>2. CÓPIA ESCRITA</title>
+ <title>2. CÓPIA LITERAL</title>
<para>Você pode copiar e distribuir o <link linkend="fdl-document">Documento</link> em qualquer meio, seja este de forma comercial ou não, desde que esta licença, as notas de direitos autorais (copyright), e a nota de licença afirmando que esta Licença se aplica ao Documento sejam reproduzidas em todas as cópias, e que você não inclua outras condições, quaisquer que sejam, às condições desta Licença. Você não pode usar de medidas técnicas para obstruir ou controlar a leitura ou cópia futura das cópias que você fizer ou distribuir. Contudo, você pode aceitar compensação em troca das cópias. Se você distribuir um número suficientemente grande de cópias, você deve também respeitar as condições descritas na <link linkend="fdl-section3">seção 3</link>.</para>
- <para>Você também pode emprestar cópias, sob as mesmas condições relacionadas acima, e você pode publicamente exibir cópias.</para>
+ <para>Você também pode emprestar cópias, nas mesmas condições acima mencionadas, e você pode publicar cópias.</para>
</sect1>
<sect1 id="fdl-section3">
<title>3. COPIANDO EM QUANTIDADE</title>
<para>Se você publicar cópias impressas do <link linkend="fdl-document">Documento</link>, em número maior que 100, e a nota de licença do Documento exigir <link linkend="fdl-cover-texts">Textos de Capa</link>, você deve encadernar as cópias em capas que carreguem, de forma clara e legível, todos estes Textos de Capa: Textos de Capa Frontal na capa frontal e Textos de Contracapa na contracapa. Ambas as capas devem também identificar, de forma clara e legível, você como o editor das cópias. A capa frontal deve apresentar o título completo com todas as palavras deste igualmente proeminentes e visíveis. Além disso, você pode adicionar outro material nas capas. As cópias com mudanças limitadas às capas, desde que preservem o título do <link linkend="fdl-document">Documento</link> e satisfaçam estas condições podem ser tratadas como cópias literais em outros aspectos.</para>
- <para>Se os textos necessários a qualquer uma das capas forem muito volumosos para serem incluídos de forma legível, você deve colocar os primeiros textos listados (quantos couberem razoavelmente) na própria capa, e continuar o resto em páginas adjacentes.</para>
+ <para>Se os textos necessários para qualquer uma das coberturas forem demasiado volumosos para se ajustar de forma legível, você deve colocar os primeiros listados (tanto quanto encaixar razoavelmente) na capa real e continuar o resto em páginas adjacentes.</para>
<para>Se você publicar ou distribuir cópias <link linkend="fdl-transparent">Opaco</link> do <link linkend="fdl-document">Documento</link> em número maior que 100, você deve incluir uma cópia <link linkend="fdl-transparent">Transparente</link> legível por máquina juntamente com cada cópia Opaca, ou dizer em (ou juntamente com) cada cópia Opaca, um endereço de rede a partir do qual o público geral de usuários possam acessar e obter de forma anônima e sob nenhum custo, usando protocolos de rede públicos padrão, uma cópia Transparente completa do Documento, livre de materiais adicionados. Se você decidir pela segunda opção, você deve seguir passos com certa prudência ao começar a distribuir as cópias Opacas em quantidade, a fim de garantir que esta cópia transparente permanecerá acessível no local indicado por pelo menos um ano após a última vez que você distribuir uma cópia Opaca (diretamente ou através de seus agentes ou distribuidores) desta edição ao público.</para>
<listitem>
<formalpara>
<title>E</title>
- <para>Adicionar uma nota apropriada de direitos autorais para suas modificações, adjacente às outras notas de direitos autorais.</para>
+ <para>Adicionar um aviso de direitos autorais apropriado para suas modificações adjacentes aos outros avisos de direitos autorais.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>H</title>
- <para>Inclua uma cópia inalterada desta Licença.</para>
+ <para>Incluir uma cópia inalterada desta Licença.</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>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>
+ <para>Você pode extrair um único documento de tal 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 referentes à cópia literal desse documento.</para>
</sect1>
<sect1 id="fdl-section7">
<title>7. AGREGAÇÃO COM TRABALHOS INDEPENDENTES</title>
- <para>Uma compilação do <link linkend="fdl-document">Documento</link> ou seus derivados com outros documentos ou trabalhos separados e independentes, dentro de ou sob um volume de um meio de armazenamento ou distribuição, não conta como um todo para uma <link linkend="fdl-modified">Versão modificada</link> do Documento, contanto que nenhum direito autoral de compilação seja reivindicado para esta compilação. Tal compilação configura um <quote>agregação</quote> e esta Licença não se aplica aos outros trabalhos contidos na compilação do Documento, levando em conta serem compilados, caso eles mesmos não forem trabalhos derivados do Documento. Se o requisito de <link linkend="fdl-cover-texts">Capa de Texto</link> da <link linkend="fdl-section3">seção 3</link> é aplicável a estas cópias do Documento, e ainda se o Documento é menor do que um quarto do agregado inteiro, os Textos de Capa do Documento podem ser inseridos nas capas que envolvem somente o Documento no agregado. Caso contrário, eles devem aparecer em capas em volta do agregado como um todo.</para>
+ <para>Uma compilação do <link linkend="fdl-document">Documento</link> ou seus derivados com outros documentos ou trabalhos separados e independentes, dentro de ou sob um volume de um meio de armazenamento ou distribuição, não conta como um todo para uma <link linkend="fdl-modified">Versão modificada</link> do Documento, contanto que nenhum direito autoral de compilação seja reivindicado para esta compilação. Tal compilação configura um <quote>agregação</quote> e esta Licença não se aplica aos outros trabalhos contidos na compilação do Documento, levando em conta serem compilados, caso eles mesmos não forem trabalhos derivados do Documento. Se o requisito de <link linkend="fdl-cover-texts">Texto de Capa</link> da <link linkend="fdl-section3">seção 3</link> é aplicável a estas cópias do Documento, e ainda se o Documento é menor do que um quarto do agregado inteiro, os Textos de Capa do Documento podem ser inseridos nas capas que envolvem somente o Documento no agregado. Caso contrário, eles devem aparecer em capas em volta do agregado como um todo.</para>
</sect1>
<sect1 id="fdl-section8">
</sect1>
<sect1 id="fdl-section9">
- <title>9. TÉRMINO</title>
+ <title>9. TERMINAÇÃO</title>
<para>Você não pode copiar, modificar, sublicenciar, ou distribuir o <link linkend="fdl-document">Documento</link> com exceção do que foi expressamente previsto sob esta Licença. Qualquer outra tentativa de cópia, modificação, sublicenciamento ou distribuição do Documento é nula, e implicará na rescisão automática de seus direitos sob esta Licença. Contudo, as partes que receberam as cópias, ou direitos, de você sob esta Licença não terão suas licenças rescindidas enquanto tais partes permanecerem em total acordo com a Licença.</para>
</sect1>
<sect1 id="fdl-using">
<title>Adendo</title>
- <para>Para usar esta Licença em um documento que você escreveu, inclua uma cópia desta no documento e adicione as seguintes notas de direitos autorais e licença logo após a página de título:</para>
+ <para>Para usar esta Licença em um documento que você escreveu, inclua uma cópia da Licença no documento e coloque os seguintes avisos de direitos autorais e de licenças logo após a página de título:</para>
<blockquote>
<para>Copyright ANO SEU NOME.</para>
- <para>Permissão concedida para copiar, distribuir e/ou modificar este documento sob os termos da Licença de Documentação Livre GNU (GNU Free Documentation License), Versão 1.1 ou qualquer versão mais recente publicada pela Free Software Foundation; com as <link linkend="fdl-invariant">Sessões invariantes</link>, sendo LISTADO SEUS TÍTULOS, com os <link linkend="fdl-cover-texts">Textos de Capa Frontal</link> sendo LISTADOS, e com os <link linkend="fdl-cover-texts">Textos de Contracapa</link> sendo LISTADOS. Uma cópia da licença está inclusa na seção intitulada <quote>Licença de Documentação Livre GNU</quote>.</para>
+ <para>Permissão concedida para copiar, distribuir e/ou modificar este documento sob os termos da Licença de Documentação Livre GNU (GNU Free Documentation License), Versão 1.1 ou qualquer versão mais recente publicada pela Free Software Foundation; com as <link linkend="fdl-invariant">Sessões invariantes</link>, sendo LISTE SEUS TÍTULOS, com os <link linkend="fdl-cover-texts">Textos de Capa Frontal</link> sendo LISTA, e com os <link linkend="fdl-cover-texts">Textos de Contracapa</link> sendo LISTA. Uma cópia da licença está inclusa na seção intitulada <quote>Licença de Documentação Livre GNU</quote>.</para>
</blockquote>
<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>
</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-2019</year>
+ <holder>Stefan Sauer (Kost)</holder>
+ </copyright>
<!-- translators: uncomment this:
<copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
- <revision><revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</authorinitials> <revremark>correçãoõesão de erros</revremark></revision>
+ <revision><revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</authorinitials> <revremark>correções de erros</revremark></revision>
<revision><revnumber>1.27</revnumber> <date>07 Maio 2017</date> <authorinitials>ss</authorinitials> <revremark>ajustes do porte para Python</revremark></revision>
<revision><revnumber>1.26</revnumber> <date>11 Ago 2017</date> <authorinitials>ss</authorinitials> <revremark>portadas todas ferramentas de perl/bash para Python</revremark></revision>
<revision><revnumber>1.25</revnumber> <date>21 Mar 2016</date> <authorinitials>ss</authorinitials> <revremark>correção de erros, limpezas de testes</revremark></revision>
<para>O GTK-Doc funciona usando a documentação de funções colocadas dentro dos arquivos fonte em blocos de comentários especialmente formatados ou documentação adicionada aos arquivos modelo que o GTK-Doc usa (apesar disso, note que o GTK-Doc vai documentar apenas funções que são declaradas em arquivos de cabeçalho; ele não irá produzir saída para funções estáticas).</para>
- <para>GTK-Doc consiste de um número de scripts em Python, cada um executando uma etapa diferente no processo.</para>
+ <para>GTK-Doc consiste em um número de scripts em Python, cada um executando uma etapa diferente no processo.</para>
<para>Há 5 etapas principais no processo:</para>
<orderedlist>
<listitem>
- <para>
- <guilabel>Writing the documentation.</guilabel>
-
- The author fills in the source files with the documentation for each
- function, macro, structs or unions, etc.
- </para>
+ <para><guilabel>Escrita da documentação.</guilabel> O autor preenche os arquivos fonte com a documentação para cada função, macro, structs ou unions, etc.</para>
</listitem>
<listitem>
- <para><guilabel>Juntando informação sobre o código.</guilabel> <application>gtkdoc-scan</application> varre os arquivos de cabeçalho do código buscando por declarações de funções, macros, enums, structs e unions. Ele cria o arquivo <filename><módulo>-decl-list.txt</filename> contendo uma lista de declarações, inserindo-as em seções da acordo com o arquivo de cabeçalho no qual se encontram. Na primeira execução, este arquivo é copiado para <filename><módulo>-sections.txt</filename>. O autor pode reorganizar as seções, e a ordem das declarações dentro delas, para produzir a ordem final desejada. O segundo arquivo que ele gera é <filename><módulo>-decl.txt</filename>. Este arquivo contém as declarações completas encontradas pela varredura. Se por algum motivo se queira que alguns apareçam nos documentos, no qual declarações completas não puderam ser encontradas pela varredura ou a declaração deveria aparecer de outra forma, pode-se colocar entidades similares aos do <filename><módulo>-decl.txt</filename> no <filename><módulo>-overrides.txt</filename>.</para>
+ <para><guilabel>Coleta de informação sobre o código.</guilabel> <application>gtkdoc-scan</application> varre os arquivos de cabeçalho do código buscando por declarações de funções, macros, enums, structs e unions. Ele cria o arquivo <filename><módulo>-decl-list.txt</filename> contendo uma lista de declarações, inserindo-as em seções da acordo com o arquivo de cabeçalho no qual se encontram. Na primeira execução, este arquivo é copiado para <filename><módulo>-sections.txt</filename>. O autor pode reorganizar as seções, e a ordem das declarações dentro delas, para produzir a ordem final desejada. O segundo arquivo que ele gera é <filename><módulo>-decl.txt</filename>. Este arquivo contém as declarações completas encontradas pela varredura. Se por algum motivo se quiser que alguns símbolos apareçam nos documentos, nos quais declarações completas não puderam ser encontradas pela varredura ou a declaração deveria aparecer de outra forma, pode-se colocar entidades similares aos do <filename><módulo>-decl.txt</filename> no <filename><módulo>-overrides.txt</filename>.</para>
<para><application>gtkdoc-scangobj</application> também pode ser usado para consultar dinamicamente uma biblioteca sobre qualquer subclasse GObject que ele exporta. Ele salva informações sobre cada posição do objeto na hierarquia de classe e sobre quaisquer propriedades GObject e sinais que ela fornece.</para>
- <para><application>gtkdoc-scanobj</application> não deveria mais ser usada. Ele era necessário no passado, quando GObject ainda era GtkObject dentro do gtk+.</para>
+ <para><application>gtkdoc-scanobj</application> não deve mais ser usado. Ele era necessário no passado, quando GObject ainda era GtkObject dentro do gtk+.</para>
</listitem>
<listitem>
- <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><guilabel>Geração do XML e do 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>
- <para><guilabel>Co
nsertando referências cruzadas entre documentos.</guilabel> Após a instalação dos arquivos HTML, <application>gtkdoc-fixxref</application> pode ser executado para consertar referências cruzadas entre documentos separados. Por exemplo, a documentação do GTK+ contém muitas referências cruzadas a tipos documentados no manual do GLib. Ao criar um tarball fonte para distribuição, <application>gtkdoc-rebase</application> transforma todos os links externos em web-links. Ao instalar documentações distribuídas (geradas previamente), o mesmo aplicativo vai tentar transformar links de volta para links locais (onde aquelas documentações estão instaladas).</para>
+ <para><guilabel>Co
rreção de referências cruzadas entre documentos.</guilabel> Após a instalação dos arquivos HTML, <application>gtkdoc-fixxref</application> pode ser executado para consertar referências cruzadas entre documentos separados. Por exemplo, a documentação do GTK+ contém muitas referências cruzadas a tipos documentados no manual do GLib. Ao criar um tarball fonte para distribuição, <application>gtkdoc-rebase</application> transforma todos os links externos em web-links. Ao instalar documentações distribuídas (geradas previamente), o mesmo aplicativo vai tentar transformar links de volta para links locais (onde aquelas documentações estão instaladas).</para>
</listitem>
</orderedlist>
<sect2 id="requirements">
<title>Requisitos</title>
- <para><guilabel>python 2/3</guilabel> - os scripts principais são escritos em Python.</para>
- <para><guilabel>xsltproc</guilabel>
- o processador de xslt do libxslt <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink></para>
- <para><guilabel>docbook-xsl</guilabel>
- as folhas de estilo xsl de docbook <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink></para>
- <para>Um dentre <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> ou <guilabel>vim</guilabel> - opcional - usado para destaque de sintaxe de exemplos</para>
+ <para><guilabel>python 2/3</guilabel> – os scripts principais são escritos em Python.</para>
+ <para><guilabel>xsltproc</guilabel>
– o processador de xslt do libxslt <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink></para>
+ <para><guilabel>docbook-xsl</guilabel>
– as folhas de estilo xsl de docbook <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink></para>
+ <para>Um dentre <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> ou <guilabel>vim</guilabel> – opcional - usado para destaque de sintaxe de exemplos</para>
</sect2>
</sect1>
<sect1 id="aboutgtkdoc">
<title>Sobre GTK-Doc</title>
- <para>
- Historically GTK-Doc was used to generate template files from the soures
- code. These template files could be used by developers to enter the
- API documentation. This approach was rather inconvenient because it
- required to keep the generated files under version control.
- Since GTK-Doc 1.9 it became possible to place all API information
- into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
- </para>
+ <para>Historicamente, o GTK-Doc foi usado para gerar arquivos de modelo a partir do código-fonte. Esses arquivos de modelo poderiam ser usados pelos desenvolvedores para inserir a documentação da API. Essa abordagem era bastante inconveniente porque exigia manter os arquivos gerados sob controle de versão. Desde o GTK-Doc 1.9, tornou-se possível colocar todas as informações da API em comentários no fonte, o que tornou o suporte ao modelo obsoleto. Na versão 1.26 suporte ao modelo foi removido.</para>
<para>(CORRIJA-ME)</para>
- <para>
- (authors, web pages, mailing list, license, future plans,
- comparison with other similar systems.)
- </para>
+ <para>(autores, páginas web, lista de discussão, licença, planos futuros, comparação com outros sistemas similares.)</para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Project Setup</title>
+ <title>Configurando o projeto</title>
- <para>
- This Chapter describes the steps that are necessary to integrate GTK-Doc
- into your project. The integration of GTK-Doc into a project includes the
- following steps:
- </para>
+ <para>Este capítulo descreve os passos necessários para integrar o GTK-Doc ao seu projeto. A integração do GTK-Doc em um projeto inclui as seguintes etapas:</para>
<itemizedlist>
<listitem>
- <para>
- Preparation of the directory structure and creating required
- configuration files for your GTK-Doc documentation (see
- <link linkend="settingup_docfiles">
- Setting up a skeleton documentation</link>).
- </para>
+ <para>Preparação da estrutura de diretórios e criação dos arquivos de configuração necessários para sua documentação do GTK-Doc (consulte <link linkend="settingup_docfiles">Preparando o esqueleto de uma documentação</link>).</para>
</listitem>
<listitem>
- <para>
- Adjusting the build system to build your documentation using the
- GTK-Doc tools. Multiple build systems are supported, in
- this manual we describe how to integrate GTK-Doc with
- <link linkend="settingup_autotools">Autotools</link>,
- <link linkend="settingup_cmake">CMake</link>, and
- <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
- </para>
+ <para>Ajuste do sistema de compilação para compilar sua documentação usando as ferramentas do GTK-Doc. Há suporte a vários sistemas de compilação, neste manual descrevemos como integrar o GTK-Doc com <link linkend="settingup_autotools">Autotools</link>, <link linkend="settingup_cmake">CMake</link> e <link linkend="settingup_plain_makefiles">Makefiles simples</link>.</para>
</listitem>
<listitem>
- <para>
- Adding GTK-Doc specific files to version control and deciding which
- files to ignore (see <link linkend="settingup_vcs">
- Integration with version control systems</link>).
- </para>
+ <para>Adição de arquivos específicos do GTK-Doc para o controle de versão e decisão de quais arquivos ignorar (veja <link linkend="settingup_vcs"> Integração com sistemas de controle de versão</link>).</para>
</listitem>
</itemizedlist>
- <para>
- The following sections assume we work on a project called
- <code>meep</code>.
- This project contains two packages (or modules),
- a library called <code>libmeep</code> and an end-user app
- called <code>meeper</code>.
- </para>
+ <para>As seções a seguir presumem que trabalhamos em um projeto chamado <code>meep</code>. Este projeto contém dois pacotes (ou módulos), uma biblioteca chamada <code>libmeep</code> e um aplicativo de usuário final chamado <code>meeper</code>.</para>
<sect1 id="settingup_docfiles">
<title>Preparando o esqueleto de uma documentação</title>
- <para>
- A common convention is to place documentation into a folder called
- <code>docs</code> inside your top-level project directory.
- We usually distinguish between <emphasis>reference
- documentation</emphasis> intended for developers and an
- <emphasis>user manual</emphasis> intended for end-users.
- Again the convention is to have separate folders for both.
- We usually place the reference documentation in a folder named
- <code>reference</code> and the end-user manual in a folder named
- <code>help</code> as.
-
- According to the above convention the documentation for our
- <code>libmeep</code> package would be placed into:
- <code>docs/reference/libmeep</code>.
-
- For packages with just one library or application
- the documentation could also be placed directly into
- <code>docs/reference</code>.
-
- It is not mandatory to use the above convention, but if you
- choose to use a different directory structure you must adjust
- your build system configuration to match your directory
- structure.
- </para>
+ <para>Uma convenção comum é colocar a documentação em uma pasta chamada <code>docs</code> dentro do seu diretório de projeto de nível superior. Costumamos distinguir entre a <emphasis>documentação de referência</emphasis> destinada aos programadores e um <emphasis>manual do usuário</emphasis> destinado aos usuários-finais. Novamente a convenção é ter pastas separadas para ambos. Geralmente, colocamos a documentação de referência em uma pasta chamada <code>reference</code> e o manual do usuário final em uma pasta chamada <code>help</code>. De acordo com a convenção acima, a documentação do nosso pacote <code>libmeep</code> seria colocada em: <code>docs/reference/libmeep</code>. Para pacotes com apenas uma biblioteca ou aplicativo, a documentação também pode ser colocada diretamente em <code>docs/reference</code>. Não é obrigatório usar a convenção acima, mas se você optar por usar uma estrutura de diretórios diferente, deverá ajustar a configuração do sistema de compilação para que corresponda à estrutura do diretório.</para>
- <para>
- In the following sections we will assume a directory structure
- for our <emphasis>meep</emphasis> project that uses the above
- conventions.
-
- <example>
- <title>Example directory structure of <emphasis>meep</emphasis>
- project</title>
- <programlisting><![CDATA[
+ <para>Nas seções a seguir, vamos presumir uma estrutura de diretórios para o nosso projeto <emphasis>meep</emphasis> que usa as convenções acima. <example>
+ <title>Exemplo de estrutura de diretórios de projeto <emphasis>meep</emphasis></title>
+ <programlisting>
meep/
docs/
- reference/ # reference documentation
+ reference/ # documentação de referência
libmeep/
meeper/
- help/ # optional: user manual
+ help/ # opcional: manual de usuário
meeper/
src/
libmeep/
meeper/
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
</sect1>
<sect1 id="settingup_autotools">
- <title>Integration with Autotools</title>
- <para>
- Integration of GTK-Doc into an autotools-based build system requires the
- following steps:
- </para>
+ <title>Integração com Autotools</title>
+ <para>A integração do GTK-Doc em um sistema de compilação baseado em autotools requer as seguintes etapas:</para>
<itemizedlist>
<listitem>
- <para>
- Ensure that <application>gtkdocize</application> is run once before
- the <filename>configure</filename> script. If an
- <filename>autogen.sh</filename> script is present, adjust it to
- check for GTK-Doc and add a call to
- <application>gtkdocize</application>.
- </para>
-
- <para>
- The main purpose of <application>gtkdocize</application> is to
- make the <filename>gtk-doc.make</filename> Makefile and the
- <filename>gtk-doc.m4</filename> macro definition file available
- to the build system, either by copying or linking it
- into the project.
- </para>
+ <para>Certificar-se de que <application>gtkdocize</application> seja executado uma vez antes do script <filename>configure</filename>. Se um script <filename>autogen.sh</filename> estiver presente, ajuste-o para verificar o GTK-Doc e adicione uma chamada ao <application>gtkdocize</application>.</para>
+
+ <para>O principal objetivo do <application>gtkdocize</application> é fazer com que o arquivo Makefile <filename>gtk-doc.make</filename> e o arquivo de definição de macro <filename>gtk-doc.m4</filename> estejam disponíveis para a compilação sistema, seja copiando ou vinculando-o ao projeto.</para>
</listitem>
<listitem>
- <para>
- Add the necessary <application>autoconf</application> macros to
- <filename>configure.ac</filename> to enable GTK-Doc in your build
- system to allow configuration of GTK-Doc via the generated
- <filename>configure</filename> script.
- </para>
- <para>
- Among others with registers the <code>--enable-gtk-doc</code>
- option with the <filename>configure</filename> script.
- </para>
+ <para>Adicionar as macros <application>autoconf</application> necessárias ao <filename>configure.ac</filename> para ativar o GTK-Doc em seu sistema de compilação para permitir a configuração do GTK-Doc através do script <filename>configure</filename> gerado.</para>
+ <para>Entre outros, registra a opção <code>--enable-gtk-doc</code> com o script <filename>configure</filename>.</para>
</listitem>
<listitem>
- <para>
- Create an <application>automake</application> script for each
- application or library in your project. In the example used in this
- documentation this step applies to both <code>meeper</code> and
- <code>libmeep</code>.
- </para>
+ <para>Criar um script <application>automake</application> para cada aplicativo ou biblioteca em seu projeto. No exemplo usado nesta documentação, esta etapa se aplica tanto a <code>meeper</code> quanto a <code>libmeep</code>.</para>
</listitem>
</itemizedlist>
- <para>
- In the following sections, we will perform the above steps in reverse
- order. We start with the <application>automake</application> scripts
- and work our way up to <filename>configure.ac</filename> and
- <filename>autogen.sh</filename>.
- Then we show how enable Gtk-Doc in the build system and
- how to build the documentation.
- </para>
+ <para>Nas seções a seguir, executaremos as etapas acima na ordem inversa. Começamos com os scripts <application>automake</application> e vamos trabalhando até o <filename>configure.ac</filename> e <filename>autogen.sh</filename>. Então, mostramos como habilitar o Gtk-Doc no sistema de compilação e como compilar a documentação.</para>
<sect2 id="settingup_automake">
<title>Integração com automake</title>
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub-directory of the
- <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
- gtkdoc-sources</ulink>
- to your project's reference documentation directory (e.g.
- <filename class="directory">docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple packages repeat this for each one.
- </para>
+ <para>Primeiro copie o <filename>Makefile.am</filename> do subdiretório do <filename class="directory">exemplo</filename> do <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am"> gtkdoc-sources</ulink> para o diretório da documentação de referência do seu projeto (por exemplo, <filename class="directory">./docs/reference/<pacote></filename>). Uma cópia local deveria estar disponível sob, por exemplo, <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Se você tiver múltiplos pacotes de documentação, repita isso para cada um.</para>
<note>
- <simpara>
- Do not forget to add each <filename>Makefile.am</filename>
- to the <function>AC_CONFIG_FILES</function> macro in
- <filename>configure.ac</filename>. For
- <filename>docs/reference/libmeep/Makefile.am</filename> you will
- need to add the entry
- <filename>docs/reference/libmeep/Makefile</filename>
- to <function>AC_CONFIG_FILES</function>.
- </simpara>
+ <simpara>Não se esqueça de adicionar cada <filename>Makefile.am</filename> à macro <function>AC_CONFIG_FILES</function> em <filename>configure.ac</filename>. Para <filename>docs/reference/libmeep/Makefile.am</filename> você precisará adicionar a entrada <filename>docs/reference/libmeep/Makefile</filename> para <function>AC_CONFIG_FILES</function>.</simpara>
</note>
<example>
- <title>
- Example directory structure with <filename>Makefiles.am</filename>
- </title>
+ <title>Exemplo de estrutura de diretório com <filename>Makefiles.am</filename></title>
<programlisting>
meep/
docs/
- reference/ # reference documentation
+ reference/ # documentação de referência
libmeep/
Makefile.am
meeper/
Makefile.am
- help/ # optional: user manual
+ help/ # opcional: manual de usuário
meeper/
src/
libmeep/
</programlisting>
</example>
- <para>
- Next, you need to customize the copied Makefiles
- and provide values for the various parameters in each
- <filename>Makefile.am</filename>.
-
- All settings have a comment above them that describes their purpose
- and how to customize the setting.
-
- Most settings are used to supply extra flags to the respective tools
- to which they apply. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>
- (e.g. the tool <application>gtkdoc-mkhtml</application> has
- an option named <code>MKHTML_OPTIONS</code>).
+ <para>Em seguida, você precisa personalizar os Makefiles copiados e fornecer valores para os vários parâmetros em cada <filename>Makefile.am</filename>. Todas as configurações têm um comentário sobre elas que descreve seu propósito e como personalizar a configuração. A maioria das configurações são usadas para fornecer opções extras para as respectivas ferramentas às quais elas se aplicam. Cada ferramenta tem uma variável na forma <option><NOME-FERRAMENTA>_OPTIONS</option> (por exemplo, a ferramenta <application>gtkdoc-mkhtml</application> tem uma opção chamada <code>MKHTML_OPTIONS</code>). Todas as ferramentas têm suporte a <option>--help</option> pra listar os parâmetros disponíveis.</para>
- All the tools support <option>--help</option> to list the supported
- options.
- </para>
-
- <para>
- The following list explains the most relevant options. Check the
- example <filename>Makefile.am</filename> for additional options.
-
- <itemizedlist>
+ <para>A lista a seguir explica as opções mais relevantes. Verifique o exemplo <filename>Makefile.am</filename> para opções adicionais. <itemizedlist>
<listitem>
- <para>
- <option>DOC_MODULE</option> is used to provide the name of the
- package that is being documentated (e.g. <code>meeper</code>, or
- <code>libmeep</code>).
- </para>
+ <para><option>DOC_MODULE</option> é usado para fornecer o nome do pacote que está sendo documentado (por exemplo, <code>meeper</code> ou <code>libmeep</code>).</para>
</listitem>
<listitem>
- <para>
- <option>DOC_SOURCE_DIR</option>
- is used to specify the location
- of source directory which GTK-Doc searches for your API
- documentation. This will usually be
- <code>
- DOC_SOURCE_DIR=$(top_srcdir)/src
- </code>
- or a sub-directory of that directory.
- </para>
+ <para><option>DOC_SOURCE_DIR</option> é usado para especificar a localização do diretório fonte que o GTK-Doc pesquisa na documentação da API. Isso geralmente será <code>DOC_SOURCE_DIR=$(top_srcdir)/src </code> ou um subdiretório desse diretório.</para>
</listitem>
<listitem>
- <para>
- <option>HFILE_GLOB</option>
- and
- <option>CFILE_GLOB</option>
- are used for dependencies. Each option take a file-glob (e.g.
- <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
- The documentation will be rebuilt if any of the matched files
- change.
- </para>
+ <para><option>HFILE_GLOB</option> e <option>CFILE_GLOB</option> são usados para dependências. Cada opção pega um arquivo glob (por exemplo, <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>). A documentação será recompilada se qualquer um dos arquivos correspondentes for alterado.</para>
</listitem>
<listitem>
- <para>
- <option>EXTRA_HFILES</option>
- allows to specify extra header files
- to include when scanning for API documentation, which are not
- found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
- EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
- </para>
+ <para><option>EXTRA_HFILES</option> permite especificar arquivos de cabeçalho extras para incluir ao verificar a documentação da API, que não são encontrados em <code>DOC_SOURCE_DIR</code> (por exemplo, <code>EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).</para>
</listitem>
<listitem>
- <para>
- <option>IGNORE_HFILES</option>
- allows to specify header files
- or directories to ignore when scanning for API documentation.
- Use the basename of the file or directory (e.g. <code>
- IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
- </para>
+ <para><option>IGNORE_HFILES</option> permite especificar arquivos ou diretórios de cabeçalho a serem ignorados ao verificar a documentação da API. Use o nome de base do arquivo ou diretório (por exemplo, <code>IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).</para>
</listitem>
<listitem>
- <para>
- <option>HTML_IMAGES</option>
- allows to specify images files which
- will be copied into the <filename>html/</filename> directory of
- the generated documentation.
- If your API documentation includes any images they need to be
- added to this
- option (e.g. <code>
- HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
- </para>
+ <para><option>HTML_IMAGES</option> permite especificar arquivos de imagens que serão copiados para o diretório <filename>html/</filename> da documentação gerada. Se a documentação da API incluir imagens, elas precisam ser adicionadas a essa opção (por exemplo, <code>HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).</para>
</listitem>
<listitem>
- <para>
- <option>content_files</option>
- allows to specify extra files
- that are included by
- <code>$(DOC_MAIN_SGML_FILE)</code>
- (e.g. <code>
- content_files=running.xml building.xml changes-2.0.xml</code>).
- </para>
+ <para><option>content_files</option> permite especificar arquivos extras incluídos por <code>$(DOC_MAIN_SGML_FILE)</code> (por exemplo, <code>content_files=running.xml building.xml changes-2.0.xml</code>).</para>
</listitem>
<listitem>
- <para>
- <option>expand_content_files</option>
- allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
- <code>#GtkWidget</code>
- are expanded (e.g. <code>
- expand_content_files=running.xml</code>).
- </para>
+ <para><option>expand_content_files</option> permite especificar arquivos onde as <emphasis>abreviaturas gtk-doc</emphasis> como <code>#GtkWidget</code> são expandidas (por exemplo, <code>expand_content_files=running.xml</code>).</para>
</listitem>
- </itemizedlist>
- </para>
+ </itemizedlist></para>
</sect2>
<sect2 id="settingup_autoconf">
<title>Integração com autoconf</title>
- <para>
- Integration with <application>autoconf</application> is very simple
- and includes one required step and an additional optional
- (but recommended) step.
-
- The first step is to add the <function>GTK_DOC_CHECK</function> macro
- to your <filename>configure.ac</filename> script. This registers
- several configure options to enable GTK-Doc and allows you
- to set default arguments for <application>gtkdocize</application>.
- </para>
+ <para>A integração com <application>autoconf</application> é muito simples e inclui uma etapa obrigatória e uma etapa adicional opcional (mas recomendada). O primeiro passo é adicionar a macro <function>GTK_DOC_CHECK</function> ao seu script <filename>configure.ac</filename>. Isso registra várias opções de configuração para habilitar o GTK-Doc e permite definir argumentos padrão para <application>gtkdocize</application>.</para>
<warning>
- <simpara>
- Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
- The macro must start at the beginning of the line and should not
- start with whitespace.
- </simpara>
+ <simpara>Certifique-se de que a macro <code>GTK_DOC_CHECK</code> não esteja recuada. A macro deve começar no início da linha e não deve começar com espaço em branco.</simpara>
</warning>
- <para>
- The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
- to your <filename>configure.ac</filename>. This is not required
- but helps <application>gtkdocize</application> to automatically copy
- the macro definition (e.g <filename>gtk-doc.m4</filename>) which
- contains the <function>GTK_DOC_CHECK</function> macro to your
- project's macro directory. Without this, the GTK_DOC_CHECK macro
- might not be found and you would need to explicitly tell the
- <application>aclocal</application> tool where to find the macro
- definition file.
- </para>
+ <para>O segundo passo é adicionar o <code>AC_CONFIG_MACRO_DIR(m4)</code> ao seu <filename>configure.ac</filename>. Isso não é necessário, mas ajuda o <application>gtkdocize</application> a copiar automaticamente a definição da macro (por exemplo, <filename>gtk-doc.m4</filename>) que contém a macro <function>GTK_DOC_CHECK</function> para o diretório de macro do seu projeto. Sem isso, a macro GTK_DOC_CHECK pode não ser encontrada e você precisaria informar explicitamente à ferramenta <application>aclocal</application> onde encontrar o arquivo de definição de macro.</para>
<para>
- <example><title>Minimal integration with autoconf</title>
- <programlisting><![CDATA[
-# recommended: set m4 directory
+ <example><title>Integração mínima com autoconf</title>
+ <programlisting>
+# recomendado: defina o diretório m4
AC_CONFIG_MACRO_DIR(m4)
-# optional: register gtk-doc in configure
+# opcional: registre gtk-doc no configure
GTK_DOC_CHECK([1.28])
-]]></programlisting>
+</programlisting>
</example>
</para>
- <para>
- The above example works, but will require all developers to have
- gtk-doc installed. A better way is to make building the documentation
- optional as shown in the next example:
-
- <example>
- <title>Integration with optional gtk-doc dependency</title>
- <programlisting><![CDATA[
+ <para>O exemplo acima funciona, mas exigirá que todos os desenvolvedores tenham o gtk-doc instalado. Uma maneira melhor é tornar a documentação opcional, conforme mostrado no próximo exemplo: <example>
+ <title>Integração com dependência opcional do gtk-doc</title>
+ <programlisting>
m4_ifdef([GTK_DOC_CHECK], [
-# recommended: set m4 directory
+# recomendado: defina diretório m4
AC_CONFIG_MACRO_DIR(m4)
-# optional: register gtk-doc in configure
+# opcional: registre gtk-doc no configure
GTK_DOC_CHECK([1.28])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
- <para>
- The first argument is used to check for the Gtk-Doc version at
- configure time. The 2nd, optional argument is used by
- <application>gtkdocize</application>.
- The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
- switches:
- </para>
+ <para>O primeiro argumento é usado para verificar a versão do Gtk-Doc em tempo de compilação. O segundo argumento é opcional, sendo usado por <application>gtkdocize</application>. A macro <symbol>GTK_DOC_CHECK</symbol> também adiciona várias opções de configuração:</para>
<orderedlist>
<listitem><para>--with-html-dir=CAMINHO : caminho para as documentações instaladas</para></listitem>
- <listitem><para>--enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=no]</para></listitem>
+ <listitem><para>--enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=não]</para></listitem>
<listitem><para>--enable-gtk-doc-html : compila documentação em formato html [padrão=sim]</para></listitem>
<listitem><para>--enable-gtk-doc-pdf : compila documentação em formato pdf [padrão=não]</para></listitem>
</orderedlist>
<para>GTK-Doc está desabilitado por padrão! Lembre-se de passar a opção <option>"--enable-gtk-doc"</option> à próxima execução do <filename>configure</filename>. Do contrário, uma documentação gerada previamente é instalada (o que faz sentido para usuários, mas não para desenvolvedores).</para>
</important>
- <para>
- After all changes to <filename>configure.ac</filename> are made,
- update the <filename>configure</filename> file. This can be done by
- re-running <code>autogen.sh</code>.
- </para>
+ <para>Após todas as alterações do <filename>configure.ac</filename> serem feitas, atualize o arquivo <filename>configure</filename>. Isso pode ser feito executando novamente <code>autogen.sh</code>.</para>
</sect2>
<sect2 id="settingup_autogen">
<title>Integração com autogen</title>
- <para>
- Most projects will have an <filename>autogen.sh</filename> script to
- setup the build infrastructure after the project was checked out from
- a version control system (such as git or svn). GTK-Doc comes with a
- script called <application>gtkdocize</application> which can be used
- to copy the necessary files needed by Gtk-Doc to the source directory.
- </para>
+ <para>A maioria dos projetos tem um script <filename>autogen.sh</filename> para configurar a infraestrutura de compilação após o checkout do projeto sistema de um controle de versão (como git ou svn). GTK-Doc vêm com um script chamado <application>gtkdocize</application> que pode ser usado para copiar os arquivos necessários pelo Gtk-Doc para o diretório fonte.</para>
- <para>
- It should be run before autoreconf, autoheader, automake or autoconf.
- </para>
+ <para>Ele deve ser executado antes de autoreconf, autoheader, automake or autoconf.</para>
<para>
<example><title>Executando gtkdocize no autogen.sh</title>
<para>
<example>
- <title>Conditionally run gtkdocize from autogen.sh</title>
- <programlisting><![CDATA[
-GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+ <title>Executa condicionalmente gtkdocize no autogen.sh</title>
+ <programlisting>
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
if test $? -ne 0; then
echo "No gtk-doc support found. You can't build the docs."
else
$GTKDOCIZE || exit 1
fi
-]]></programlisting>
+</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).
- </para>
+ <para>Ao executar <application>gtkdocize</application>, ele copia <filename>gtk-doc.make</filename> para a raiz do seu projeto (ou qualquer diretório especificado pela opção <option>--docdir</option>).</para>
- <para>
- <application>gtkdocize</application> checks your
- <filename>configure.ac</filename> script for
- the <function>GTK_DOC_CHECK</function> macro.
- The <function>GTK_DOC_CHECK</function> macro can be used to pass
- extra arguments to the <application>gtkdocize</application> script.
- the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
- </para>
+ <para><application>gtkdocize</application> verifica seu script <filename>configure.ac</filename> para <function>GTK_DOC_CHECK</function>. A macro <function>GTK_DOC_CHECK</function> pode ser usada para passar parâmetros extras para o script <application>gtkdocize</application>.</para>
- <para>
- Alternatively, additional arguments can also be passed to
- <application>gtkdocize</application> via the
- <function>GTKDOCIZE_FLAGS</function> environment variable, or by
- directly specifying them to <application>gtkdocize</application>
- in <filename>autogen.sh</filename>.
- </para>
+ <para>Alternativamente, argumentos adicionais também podem ser passados para <application>gtkdocsize</application> por meio da variável de ambiente <function>GTKDOCIZE_FLAGS</function> ou especificando-os diretamente ao <application>gtkdocsize</application> no <filename>autogen.sh</filename>.</para>
</sect2>
<sect2 id="settingup_firstrun">
- <title>Executing GTK-Doc from the Build System</title>
+ <title>Executando GTK-Doc a partir do sistema de compilação</title>
<para>Após as etapas anteriores, é hora de executar a compilação. Primeiro, nós queremos executar novamente o <filename>autogen.sh</filename>. Se este script executa o configure para você, então forneça a este a opção <option>--enable-gtk-doc</option>. Do contrário, execute manualmente <filename>configure</filename> com esta opção em seguida.</para>
<para>A primeira execução do make cria vários arquivos adicionais nos diretórios de documentação. Os importantes são: <filename><pacote>.types</filename>, <filename><pacote>-docs.xml</filename> (no passado, .sgml), <filename><pacote>-sections.txt</filename>.</para>
</example>
</para>
- <para>
- Now you can point your browser to
- <filename>docs/reference/<package>/index.html</filename>.
- With this initial setup you will only see a very simple document.
- The next chapter will teach you how to add API documentation to your
- code via special comment blocks. The Chapter afterwards introduces
- <link linkend="metafiles">additional files</link> and shows how to
- edit the <link linkend="metafiles_master">master template</link> to
- add additional chapters and sections to your documentation files.
- </para>
+ <para>Agora você pode apontar seu navegador para <filename>docs/reference/<pacote>/index.html </filename>. Com esta configuração inicial, você verá apenas um documento muito simples. O próximo capítulo ensinará como adicionar documentação da API ao seu código por meio de blocos de comentários especiais. O capítulo seguinte depois introduz <link linkend="metafiles">arquivos adicionais</link> e mostra como editar o <link linkend="metafiles_master">modelo mestre</link> para adicionar capítulos e seções adicionais aos seus arquivos de documentação.</para>
</sect2>
# 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).
+# Instala os documentos. (Isso presume que você está usando o módulo
+# GNUInstallDirs do CMake para definir a variável CMAKE_INSTALL_DOCDIR
+# corretamente).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
DESTINATION ${CMAKE_INSTALL_DOCDIR})
</programlisting>
<sect1 id="settingup_vcs">
<title>Integração com sistemas de controle de versão</title>
- <para>Como uma regra de ouro, são aqueles arquivos que você edita que deveriam entrar no controle de versão. Para projetos normais, esses são os arquivos: <filename><pacote>.types</filename>, <filename><pacote>-docs.xml</filename> (no passado, .sgml), <filename><pacote>-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
- <para>Arquivos nos diretórios <filename>xml/</filename> e <filename>html/</filename> não deveriam entrar no controle de versão. Da mesma forma, não deveriam entrar arquivos <filename>.stamp</filename>.</para>
+ <para>Como uma regra de ouro, são aqueles arquivos que você edita que devem 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 devem entrar no controle de versão. Da mesma forma, não devem entrar arquivos <filename>.stamp</filename>.</para>
</sect1>
</chapter>
<chapter id="documenting">
<title>Documentando o código</title>
- <para>GTK-Doc usa comentários do código fonte com uma sintaxe especial para documentação do código. Além disso, ele obtém informações sobre a estrutura do seu projeto a partir de outros fontes. Na próxima seção, você vai descobrir todas as informações sobre a sintaxe dos comentários.</para>
+ <para>GTK-Doc usa comentários do código-fonte com uma sintaxe especial para documentação do código. Além disso, ele obtém informações sobre a estrutura do seu projeto a partir de outros fontes. Na próxima seção, você vai descobrir todas as informações sobre a sintaxe dos comentários.</para>
- <para>
- The GTK-Doc scanner can handle the majority of C headers fine. In the
- case of receiving warnings from the scanner that look like a special
- case, one can hint GTK-Doc to skip over them.
- <example><title>GTK-Doc comment block</title>
- <programlisting><![CDATA[
+ <para>O verificador do GTK-Doc sabe lidar com a maioria dos cabeçalhos de C sem problemas. Caso se receba avisos (warnings) na varredura que pareça ser um caso especial, pode-se informar ao GTK-Doc para ignorá-los. <example><title>Bloco de comentário do GTK-Doc</title>
+ <programlisting>
#ifndef __GTK_DOC_IGNORE__
-/* unparseable code here */
+/* código não analisável aqui */
#endif
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
<note>
<title>Limitações</title>
<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 comece 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:
<para>O que é: O nome de uma classe ou função pode, em alguns casos, levar a um entendimento equivocado pessoas com experiências diferentes.</para>
</listitem>
<listitem>
- <para>O que isso faz: Fale sobre usos comuns. Coloque em relação com a outra API.</para>
+ <para>O que ele faz: Fale sobre usos comuns. Coloque em relação com a outra API.</para>
</listitem>
</itemizedlist></para>
</tip>
<para>Uma vantagem do hipertexto de texto simples é a habilidade de ter links no documento. Porém, escrever a marcação correta para cada link pode ser entediante. GTK-Doc vem para ajudar fornecendo abreviações úteis. <itemizedlist>
<listitem>
- <para>Use function() para referir às funções ou macros que levam argumentos.</para>
+ <para>Use function() para se referir às funções ou macros que levam argumentos.</para>
</listitem>
<listitem>
<para>Use @param para se referir a parâmetros. Também, use isso ao se referir a parâmetros de outras funções, relacionadas àquele sendo descrito.</para>
</example>
</para>
- <para>Mais exemplos d
o 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>
+ <para>Mais exemplos d
e quais tags de markdown tags possui suporte podem ser encontrados 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>
- As already mentioned earlier GTK-Doc is for documenting public API. Thus
- one cannot write documentation for static symbols. Nevertheless it is good
- to comment those symbols too. This helps other developers to understand
- your code.
- Therefore we recommend to comment these using normal comments (without the
- 2nd '*' in the first line).
- If later the function needs to be made public, all one needs to do is to
- add another '*' in the comment block and insert the symbol name at the
- right place inside the sections file.
- </para>
+ <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 desenvolvedores 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>
<listitem>
<para>Uma descrição informal do nível de estabilidade que esta API tem. Nós recomendamos o uso de um desses termos: <itemizedlist>
<listitem>
- <para>Estável - A intenção de uma interface estável é permitir terceiros arbitrários desenvolverem aplicativos para essas interfaces, lançá-los e ter a confiança de que eles vão funcionar em todos os lançamentos menores do produto (após aquele no qual a interface foi introduzida e naquele mesmo lançamento maior). Atém mesmo em um lançamento maior, espera-se que alterações incompatíveis sejam raras e que tenham fortes justificativas.</para>
+ <para>Estável – A intenção de uma interface estável é permitir terceiros arbitrários desenvolverem aplicativos para essas interfaces, lançá-los e ter a confiança de que eles vão funcionar em todos os lançamentos menores do produto (após aquele no qual a interface foi introduzida e naquele mesmo lançamento maior). Atém mesmo em um lançamento maior, espera-se que alterações incompatíveis sejam raras e que tenham fortes justificativas.</para>
</listitem>
<listitem>
- <para>Instável - Interfaces instáveis são experimentais ou transicionais. Elas são normalmente usadas para dar a desenvolvedores externos um acesso prévio a nova tecnologia ou em rápida alteração, ou para fornecer uma solução interina para um problema que uma solução mais genérica foi antecipada. Nenhuma responsabilidade é assumida pela compatbilidade dos binários ou dos fontes de uma versão menor para a próxima.</para>
+ <para>Instável – Interfaces instáveis são experimentais ou transicionais. Elas são normalmente usadas para dar a desenvolvedores externos um acesso prévio a nova tecnologia ou em rápida alteração, ou para fornecer uma solução interina para um problema que uma solução mais genérica foi antecipada. Nenhuma responsabilidade é assumida pela compatbilidade dos binários ou dos fontes de uma versão menor para a próxima.</para>
</listitem>
<listitem>
- <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>
+ <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>
<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>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>
+ <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 valores abaixo.</para>
<variablelist><title>Tags de estabilidade</title>
<varlistentry><term>Stability: Stable</term>
</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 privados. Eles são tratados como funções estáticas.</para>
<example><title>Bloco de comentário de função</title>
<programlisting>
<varlistentry>
<term>@see_also:</term>
<listitem>
- <para>A seção “Veja Também” (See Also) de páginas de manual. (Opcional)</para>
+ <para>A seção “See Also” (Veja Também) de páginas de manual. (Opcional)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Returns:</term>
<listitem>
- <para>Especifique quais valor(es) o programa retorna. (Opcional)</para>
+ <para>Especifique qual(is) valor(es) o programa retorna. (Opcional)</para>
</listitem>
</varlistentry>
<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á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>
+ </informalexample> O "linked" é a identificação 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>
</programlisting>
</informalexample></para>
- <para>Para incluir um código de exemplo: <informalexample>
- <programlisting>
-<example>
- <title>Usando uma GHashTable.</title>
- <programlisting>
+ <para>
+ To include example code:
+ <informalexample>
+ <programlisting><![CDATA[
+<example>
+ <title>Using a GHashTable.</title>
+ <programlisting language="C">
...
- </programlisting>
-</example>
-</programlisting>
- </informalexample> ou possivelmente este, para fragmentos de código bem curtos que não precisam de um título: <informalexample>
- <programlisting>
-<informalexample>
- <programlisting>
+ </programlisting>
+</example>
+]]></programlisting>
+ </informalexample>
+ or possibly this, for very short code fragments which don't need a title:
+ <informalexample>
+ <programlisting><![CDATA[
+<informalexample>
+ <programlisting language="C">
...
- </programlisting>
-</informalexample>
-</programlisting>
- </informalexample> Para este último, GTK-Doc também possui suporte a uma abreviação: |[ ... ]|</para>
+ </programlisting>
+</informalexample>
+]]></programlisting>
+ </informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
+ For the latter GTK-Doc also supports an abbreviation:
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
+ ...
+]|
+]]></programlisting>
+ </informalexample>
+ </para>
<para>Para incluir listas com marcadores: <informalexample>
<programlisting>
<programlisting>
<classname>GtkWidget</classname>
</programlisting>
- </informalexample> mas você provavelmente vai estar usando #GtkWidget em vez disso (para criar automaticamente um link para a página do GtkWidget - veja <link linkend="documenting_syntax">as abreviações</link>).</para>
+ </informalexample> mas você provavelmente vai estar usando #GtkWidget em vez disso (para criar automaticamente um link para a página do GtkWidget – veja <link linkend="documenting_syntax">as abreviações</link>).</para>
<para>Para enfatizar um texto: <informalexample>
<programlisting>
<chapter id="metafiles">
<title>Preenchendo os arquivos extras</title>
- <para>Há alguns poucos arquivos extras, que precisam ser mantidos junto com os comentários inseridos no código fonte: <filename><pacote>.types</filename>, <filename><pacote>-docs.xml</filename> (no passado, .sgml), <filename><pacote>-sections.txt</filename>.</para>
+ <para>Há alguns poucos arquivos extras, que precisam ser mantidos junto com os comentários inseridos no código-fonte: <filename><pacote>.types</filename>, <filename><pacote>-docs.xml</filename> (no passado, .sgml), <filename><pacote>-sections.txt</filename>.</para>
<sect1 id="metafiles_types">
<title>Editando o arquivo de tipos</title>
<para>Se sua biblioteca ou aplicativo inclui GObjects, você deseja que seus sinais, argumentos/parâmetros e posição na hierarquia sejam mostrados na documentação. Tudo que você precisa fazer é listar as funções <function>xxx_get_type</function> junto com seus include dentro do arquivo <filename><pacote>.types</filename>.</para>
<para>
- <example><title>Example <package>.types file</title>
+ <example><title>Exemplo de arquivo <pacote>.types</title>
<programlisting>
#include <gtk/gtk.h>
<para>Habilite ou adicione a linha <option>TESTS=$(GTKDOC_CHECK)</option> no Makefile.am. Se pelo menos GTK-Doc 1.9 estiver instalado, isso vai executar verificações de sanidade durante a execução de <command>make check</command>.</para>
</tip>
- <para>Também pode-se buscar nos arquivos produzidos pela varredura do código aberto: <filename><pacote>-decl-list.txt</filename> e <filename><pacote>-decl.txt</filename>. O primeiro pode ser comparado com o arquivo de seção, se ele for mantido manualmente. O segundo lista todas as declarações de cabeçalhos. Se um símbolo está faltando, pode-se verificar se este arquivo o contém.</para>
+ <para>Também pode-se buscar nos arquivos produzidos pela varredura do código-fonte: <filename><pacote>-decl-list.txt</filename> e <filename><pacote>-decl.txt</filename>. O primeiro pode ser comparado com o arquivo de seção, se ele for mantido manualmente. O segundo lista todas as declarações de cabeçalhos. Se um símbolo está faltando, pode-se verificar se este arquivo o contém.</para>
<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>
<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
- in the master template and how the entities are used.
- The entities can also be used in all
- generated files, GTK-Doc will use the same xml header in generated xml
- files.
- <example><title>Use pre-generated entities</title>
- <programlisting><![CDATA[
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ <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 no modelo mestre 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>
<sect1 id="commandline-interfaces">
<title>Opções de linha de comando e de páginas man</title>
- <para>Já que também é possível gerar páginas man para um refentry do docbook, soa como uma boa ideia usá-lo para este propósito. Desta forma, a interface é parte da referência e é possível obter a página man de graça.</para>
+ <para>Já que também é possível gerar páginas man para um refentry do docbook, soa como uma boa ideia usá-lo para este propósito. Desta forma, a interface é parte da referência e é possível obter a página man livremente.</para>
<sect2 id="commandline-interfaces-file">
<title>Documentar a ferramenta</title>
<!-- gtk-doc warnings: -->
<seglistitem>
- <seg>Parâmetro descrito no bloco de comentário do código fonte não existe</seg>
+ <seg>Parâmetro descrito no bloco de comentário do código-fonte não existe</seg>
<seg>Verifique se o protótipo no cabeçalho tem nomes de parâmetros diferentes da fonte.</seg>
</seglistitem>
<chapter id="contrib">
<title>Ferramentas relacionadas ao gtk-doc</title>
- <para>GtkDocPlugin
- um plug-in de integração com <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink>, que adiciona documentos de API a um site trac e integra com a pesquisa do trac.</para>
- <para>Gtkdoc-depscan - uma ferramenta (parte do gtk-doc) para verificar APIs usadas, a partir de suas tags, para determinar a versão mínima necessária.</para>
+ <para>GtkDocPlugin
– um plug-in de integração com <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink>, que adiciona documentos de API a um site trac e integra com a pesquisa do trac.</para>
+ <para>Gtkdoc-depscan – uma ferramenta (parte do gtk-doc) para verificar APIs usadas, a partir de suas tags, para determinar a versão mínima necessária.</para>
</chapter>
<title>Licença de Documentação Livre GNU</title>
<sect1 id="fdl-preamble">
- <title>0. INTRODUÇÃO</title>
- <para>O propósito desta Licença é fazer um manual, livro-texto, ou outro documento escrito <quote>livre</quote> em seu sentido de liberdade: para garantir a todos a liberdade efetiva de copiá-lo e redistribui-lo, com ou sem modificações, tanto comercialmente como não comercialmente. Em segundo lugar, esta Licença preserva ao autor e ao editor uma forma de obter crédito pelo seu trabalho, enquanto não é considerado responsável por modificações feitas por outros.</para>
+ <title>0. PREÂMBULO</title>
+ <para>O objetivo desta Licença é tornar um manual, livro didático ou outro documento funcional e útil “livre” no sentido de liberdade: assegurar a todos a liberdade efetiva de copiá-lo e redistribuí-lo, com ou sem modificação do mesmo, comercialmente ou não. Em segundo lugar, esta Licença preserva para o autor e o editor uma maneira de obter crédito por seu trabalho, sem ser considerado responsável por modificações feitas por outros.</para>
- <para>Esta licença é um tipo de <quote>copyleft</quote>, que significa que trabalhos derivados do documento precisam ser, por sua vez, livres no mesmo sentido. Ela complementa a Licença Pública Geral GNU (GNU General Public License), que é uma licença copyleft projetada para softwares livres.</para>
+ <para>Esta licença é um tipo de “copyleft”, o que significa que trabalhos derivados do documento devem ser livres no mesmo sentido. Ela complementa a Licença Pública Geral GNU (GNU General Public License), que é uma licença com copyleft projetada para software livre.</para>
- <para>Nós projetamos esta Licença a fim de ser utilizada em manuais de software livre, já que softwares livres precisam de documentações livres: um programa livre deveria vir com manuais que ofereçam as mesmas liberdades que o software proporciona. Mas esta Licença não é limitada a manuais de software; ela pode ser usada para qualquer trabalho de texto, independente do assunto ou se é publicado como um livro impresso. Nós recomendamos esta Licença principalmente para trabalhos cujo propósito seja instrução ou referência.</para>
+ <para>Criamos esta Licença para usá-la para manuais para software livre, porque software livre precisa de documentação livre: um programa livre deve ser fornecido com manuais que proporcionam as mesmas liberdades que o software. Mas esta Licença não está limitada aos manuais de software; pode ser usada para qualquer trabalho textual, independentemente do assunto ou dele ser publicado como um livro impresso. Recomendamos esta Licença principalmente para trabalhos cujo propósito seja instrução ou referência.</para>
</sect1>
<sect1 id="fdl-section1">
<title>1. APLICABILIDADE E DEFINIÇÕES</title>
- <para id="fdl-document">Esta Licença se aplica a qualquer manual ou outro trabalho que contenha um aviso colocado pelo detentor dos direitos autorais dizendo que o documento pode ser distribuído sob os termos desta. O <quote>Documento</quote>, abaixo, refere-se a qualquer manual ou trabalho. Qualquer membro do público é um licenciado, e será referenciado como <quote>você</quote>.</para>
+ <para id="fdl-document">Esta Licença aplica-se a qualquer manual ou outro trabalho, em qualquer meio, que contenha um aviso colocado pelo detentor dos direitos autorais dizendo que pode ser distribuído nos termos desta Licença. Tal aviso concede uma licença mundial, sem royalties, de duração ilimitada, para usar esse trabalho nas condições aqui estabelecidas. O “Documento”, a seguir, refere-se a qualquer manual ou trabalho. Qualquer membro do público é um licenciado e é referido como “você”. Você aceita a licença se você copiar, modificar ou distribuir o trabalho de forma a exigir permissão de acordo com a lei de direitos autorais.</para>
- <para id="fdl-modified">Uma <quote>Versão Modificada</quote> do Documento significa qualquer trabalho contendo o Documento ou uma porção deste, seja uma cópia literal ou com modificações e/ou traduzido em outro idioma.</para>
+ <para id="fdl-modified">Uma “Versão Modificada” do Documento significa qualquer trabalho contendo o Documento ou uma porção deste, seja uma cópia literal ou com modificações e/ou traduzido em outro idioma.</para>
- <para id="fdl-secondary">Uma <quote>Seção Secundária</quote> é um apêndice com nome ou uma seção inicial do <link linkend="fdl-document">Documento</link> que trata exclusivamente da relação dos editores ou autores do Documento com seu assunto geral (ou temas relacionados) e não contém nada que possa estar diretamente dentro do assunto geral. (Por exemplo, se o Documento é em parte um livro-texto de matemática, uma Seção Secundária não pode explicar nada de matemática). Tal relação pode ser uma questão de conexão histórica com o assunto ou com temas relacionados, ou tratar de questões legais, comerciais, filosóficas, éticas ou políticas com relação a eles.</para>
+ <para id="fdl-secondary">A “Seção Secundária” é um apêndice nomeado ou uma seção anterior do Documento que trata exclusivamente do relacionamento dos editores ou autores do <link linkend="fdl-document">Documento</link> com o assunto geral do documento (ou assuntos relacionados) e não contém nada que possa estar diretamente dentro desse assunto geral. (Assim, se o Documento for, em parte, um livro de texto de matemática, uma Seção Secundária pode não explicar qualquer matemática.) O relacionamento poderia ser uma questão de conexão histórica com o assunto ou com assuntos relacionados, ou de posição legal, comercial, filosófica, ética ou política em relação a eles.</para>
- <para id="fdl-invariant">As <quote>Seções Invariantes</quote> são certas <link linkend="fdl-secondary">Seções Secundárias</link> cujos títulos são designados como sendo de Seções Invariantes na nota que afirma que o <link linkend="fdl-document">Documento</link> é publicado sob esta Licença.</para>
+ <para id="fdl-invariant">As “Seções Invariantes” são certas <link linkend="fdl-secondary">Seções Secundárias</link> cujos títulos são designados, como sendo daquelas de Seções Invariantes, no aviso que diz que o <link linkend="fdl-document">Documento</link> é liberado sob esta Licença.</para>
- <para id="fdl-cover-texts">Os <quote>Textos de Capa</quote> são certas passagens de texto curtas que são listadas, como Textos de Capa Frontal ou Texto de Contra Capa, na nota que afirma que o <link linkend="fdl-document">Documento</link> é publicado sob esta Licença.</para>
+ <para id="fdl-cover-texts">Os “Textos de Capa” são certas passagens de texto que são listadas como Textos de Capa Frontal ou Textos de Contracapa, no aviso que afirma que o <link linkend="fdl-document">Documento</link> foi publicado sob esta Licença.</para>
- <para id="fdl-transparent">Uma cópia <quote>Transparente</quote> do <link linkend="fdl-document">Documento</link> significa uma cópia legível por máquina, representada em um formato cuja especificação esteja disponível ao público geral e que cujo conteúdo possa ser visualizado e editado de forma clara e direta por editores de texto genéricos ou programas genéricos de desenho (para imagens compostas de pixels) ou para alguns dos editores de desenho amplamente disponíveis (para desenhos) e que seja apropriado para inclusão em formatadores de texto ou para a tradução automática em uma variedade de formatos apropriados de entrada em formatadores de texto. Uma cópia feita em outro formato de arquivo Transparente cuja marcação, ou ausência desta, tenha sido manipulada para impedir ou desencorajar modificação subsequente pelos leitores não é Transparente. Uma cópia que não é <quote>Transparente</quote> é chamada <quote>Opaca</quote>.</para>
+ <para id="fdl-transparent">Uma cópia “Transparente” do <link linkend="fdl-document"> Documento</link> significa uma cópia legível por máquina, representada em um formato cuja especificação está disponível para o público em geral, cujo conteúdo possa ser visto e editado diretamente com editores de texto genéricos ou (para imagens compostas de pixels) programas gráficos genéricos ou (para desenhos) algum editor de desenho amplamente disponível, e isso seja adequado para entrada para formatadores de texto ou para tradução automática para uma variedade de formatos adequados para entrada de formatadores de texto. Uma cópia feita em um formato de arquivo Transparente cuja marcação tenha sido projetada para frustrar ou desencorajar a modificação subsequente pelos leitores não é Transparente. Uma cópia que não é “Transparente” é chamada de “Opaca”.</para>
- <para>Exemplos de formatos apropriados para cópias Transparentes incluem ASCII puro sem marcação, formato de entrada Texinfo, formato de entrada LaTex, SGML ou XML usando um DTD publicamente disponível, e HTML simples em conformidade padrão projetado para modificação por humanos. Formatos Opacos incluem PostScript, PDF, formatos proprietários que podem ser lidos ou editados somente por processadores de texto proprietários, SGML ou XML cujos DTD e/ou ferramenta de processamento não estão largamente disponibilizados, e o HTML gerado por máquina produzido por algum processador de texto com propósito apenas de saída.</para>
+ <para>Exemplos de formatos adequados para cópias Transparentes incluem ASCII simples sem marcação, formato de entrada Texinfo, formato de entrada LaTeX, SGML ou XML usando DTD publicamente disponível e HTML simples, conforme padrão, projetados para modificação humana. Os formatos Opacos incluem PostScript, PDF, formatos proprietários que podem ser lidos e editados apenas por processadores de texto proprietários, SGML ou XML para os quais o DTD e/ou ferramentas de processamento não estão geralmente disponíveis e o HTML gerado por máquina produzido por alguns processadores de texto para apenas para fins de saída.</para>
- <para id="fdl-title-page">A <quote>Página de Título</quote> significa, para um livro impresso, a própria página do título, além das páginas subsequentes necessárias para conter, de forma legível, o material que esta Licença requer que apareça na página do título. Para trabalhos em formatos que não possuem qualquer página de título semelhante, <quote>Página de Título</quote> significa o texto próximo à ocorrência mais proeminente do título do trabalho, precedendo o início do corpo do texto.</para>
+ <para id="fdl-title-page">A “Página de Título” significa, para um livro impresso, a própria página do título, além das páginas subsequentes necessárias para conter, de forma legível, o material que esta Licença requer que apareça na página do título. Para trabalhos em formatos que não possuem qualquer página de título semelhante, “Página de Título” significa o texto próximo à ocorrência mais proeminente do título do trabalho, precedendo o início do corpo do texto.</para>
</sect1>
<sect1 id="fdl-section2">
- <title>2. CÓPIA ESCRITA</title>
- <para>Você pode copiar e distribuir o <link linkend="fdl-document">Documento</link> em qualquer meio, seja este de forma comercial ou não, desde que esta licença, as notas de direitos autorais (copyright), e a nota de licença afirmando que esta Licença se aplica ao Documento sejam reproduzidas em todas as cópias, e que você não inclua outras condições, quaisquer que sejam, às condições desta Licença. Você não pode usar de medidas técnicas para obstruir ou controlar a leitura ou cópia futura das cópias que você fizer ou distribuir. Contudo, você pode aceitar compensação em troca das cópias. Se você distribuir um número suficientemente grande de cópias, você deve também respeitar as condições descritas na <link linkend="fdl-section3">seção 3</link>.</para>
+ <title>2. CÓPIA LITERAL</title>
+ <para>Você pode copiar e distribuir o <link linkend="fdl-document">Documento</link> em qualquer meio, seja este de forma comercial ou não, desde que esta Licença, os avisos de direitos autorais e o aviso de licença afirmando que esta Licença se aplica ao Documento sejam reproduzidos em todas as cópias, e que você adicione nenhuma outra condição, qualquer que seja, às condições desta Licença. Você não pode usar de medidas técnicas para obstruir ou controlar a leitura ou cópia futura das cópias que você fizer ou distribuir. Contudo, você pode aceitar compensação em troca das cópias. Se você distribuir um número suficientemente grande de cópias, você deve também respeitar as condições descritas na <link linkend="fdl-section3">seção 3</link>.</para>
- <para>Você também pode emprestar cópias, sob as mesmas condições relacionadas acima, e você pode publicamente exibir cópias.</para>
+ <para>Você também pode emprestar cópias, nas mesmas condições acima mencionadas, e você pode publicar cópias.</para>
</sect1>
<sect1 id="fdl-section3">
<title>3. COPIANDO EM QUANTIDADE</title>
- <para>Se você publicar cópias impressas do <link linkend="fdl-document">Documento</link>, em número maior que 100, e a nota de licença do Documento exigir <link linkend="fdl-cover-texts">Textos de Capa</link>, você deve encadernar as cópias em capas que carreguem, de forma clara e legível, todos estes Textos de Capa: Textos de Capa Frontal na capa frontal e Textos de Contracapa na contracapa. Ambas as capas devem também identificar, de forma clara e legível, você como o editor das cópias. A capa frontal deve apresentar o título completo com todas as palavras deste igualmente proeminentes e visíveis. Além disso, você pode adicionar outro material nas capas. As cópias com mudanças limitadas às capas, desde que preservem o título do <link linkend="fdl-document">Documento</link> e satisfaçam estas condições podem ser tratadas como cópias literais em outros aspectos.</para>
+ <para>Se você publicar cópias impressas do <link linkend="fdl-document">Documento</link> em número maior que 100, e o aviso de licença do Documento exigir os <link linkend="fdl-cover-texts">Textos de Capa</link>, você deve incluir as cópias nas capas que carregam, de forma clara e legível, todas essas Textos de Capa: Textos de Capa Frontal na capa frontal e Textos de Contracapa na contracapa. Ambas as capas também devem identificá-lo claramente e legivelmente como o editor dessas cópias. A capa frontal deve apresentar o título completo com todas as palavras do título igualmente proeminentes e visíveis. Você também pode adicionar outros materiais nas capas. Copiar com as alterações limitadas às capas, desde que preservem o título do <link linkend="fdl-document">Documento</link> e satisfaçam estas condições, podem ser tratadas como cópias literais em outros aspectos.</para>
- <para>Se os textos necessários a qualquer uma das capas forem muito volumosos para serem incluídos de forma legível, você deve colocar os primeiros textos listados (quantos couberem razoavelmente) na própria capa, e continuar o resto em páginas adjacentes.</para>
+ <para>Se os textos necessários para qualquer uma das coberturas forem demasiado volumosos para se ajustar de forma legível, você deve colocar os primeiros listados (tanto quanto encaixar razoavelmente) na capa real e continuar o resto em páginas adjacentes.</para>
- <para>Se você publicar ou distribuir cópias <link linkend="fdl-transparent">Opacas</link> do <link linkend="fdl-document">Documento</link> em número maior que 100, você deve incluir uma cópia <link linkend="fdl-transparent">Transparente</link> legível por máquina juntamente com cada cópia Opaca, ou dizer em (ou juntamente com) cada cópia Opaca, um endereço de rede a partir do qual o público geral de usuários possam acessar e obter de forma anônima e sob nenhum custo, usando protocolos de rede públicos padrão, uma cópia Transparente completa do Documento, livre de materiais adicionados. Se você decidir pela segunda opção, você deve seguir passos com certa prudência ao começar a distribuir as cópias Opacas em quantidade, a fim de garantir que esta cópia transparente permanecerá acessível no local indicado por pelo menos um ano após a última vez que você distribuir uma cópia Opaca (diretamente ou através de seus agentes ou distribuidores) desta edição ao público.</para>
+ <para>Se você publicar ou distribuir cópias <link linkend="fdl-transparent">Opacas</link> do <link linkend="fdl-document">Documento</link> em número superior a 100, você deve incluir uma cópia <link linkend="fdl-transparent">Transparente</link> legível por máquina junto com cada cópia Opaca ou estabelecer em ou com cada cópia Opaca uma localização de rede de computador publicamente acessível contendo uma cópia transparente completa do documento, sem material adicional, a partir da qual o público geral usuário de rede tem acesso para baixar anonimamente sem custo, usando protocolos de rede padrão público. Se você usar a última opção, você deve tomar medidas razoavelmente prudentes, quando você começar a distribuir cópias Opacas em quantidade, para garantir que esta cópia Transparente permanecerá acessível no local indicado até pelo menos um ano após a última vez que você distribuir uma cópia Opaca (diretamente ou através de seus agentes ou varejistas) dessa edição para o público.</para>
- <para>É solicitado, mas não exigido, que você contate os autores do <link linkend="fdl-document">Documento</link> muito antes de redistribuir qualquer grande número de cópias, para dar a eles uma chance de lhe fornecer uma versão atualizada do Documento.</para>
+ <para>É solicitado, mas não é necessário, que você contate os autores do <link linkend="fdl-document">Documento</link> muito antes de redistribuir qualquer grande número de cópias, para dar a eles uma chance de lhe fornecer uma versão atualizada do Documento.</para>
</sect1>
<sect1 id="fdl-section4">
<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, havendo 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 lhe conceder permissão.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>B</title>
- <para>Listar na <link linkend="fdl-title-page">Página de Título</link> como autores, uma ou mais pessoas ou entidades responsáveis pela autoria das modificações na <link linkend="fdl-modified">Versão Modificada</link>, juntamente com pelo menos cinco autores principais do <link linkend="fdl-document">Documento</link> (todos seus autores principais, se houver menos que cinco).</para>
+ <para>Listar na <link linkend="fdl-title-page">Página de Título</link>, como autores, uma ou mais pessoas ou entidades responsáveis pela autoria das modificações na <link linkend="fdl-modified">Versão Modificada</link>, juntamente com pelo menos cinco dos autores principais do <link linkend="fdl-document">Documento</link> (todos os seus principais autores, se tiverem menos de cinco).</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>C</title>
- <para>Declarar na <link linkend="fdl-title-page">Página de Título</link> o nome do editor da <link linkend="fdl-modified">Versão Modificada</link>, como seu editor.</para>
+ <para>Indicar na <link linkend="fdl-title-page">Página de Título</link> o nome do editor da <link linkend="fdl-modified">Versão Modificada</link>, como editor.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>D</title>
- <para>Preservar todas as notas de direitos autorais (copyright) do <link linkend="fdl-document">Documento</link>.</para>
+ <para>Preservar todas as avisos de direitos autorais do <link linkend="fdl-document">Documento</link>.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>E</title>
- <para>Adicionar uma nota apropriada de direitos autorais para suas modificações, adjacente às outras notas de direitos autorais.</para>
+ <para>Adicionar um aviso de direitos autorais apropriado para suas modificações adjacentes aos outros avisos de direitos autorais.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>F</title>
- <para>Incluir, imediatamente após as notas de direitos autorais, uma nota de licença concedendo permissão pública para o uso da <link linkend="fdl-modified">Versão Modificada</link> sob os termos desta Licença, na forma mostrada no Adendo abaixo.</para>
+ <para>Incluir, imediatamente após os avisos de direitos autorais, um aviso de licença que dê permissão ao público para usar a <link linkend="fdl-modified">Versão Modificada</link> sob os termos desta Licença, na forma mostrada no Adendo abaixo.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>G</title>
- <para>Preservar na referida nota de licença a lista completa de <link linkend="fdl-invariant">Seções Invariantes</link> e <link linkend="fdl-cover-texts">Textos de Capa</link> obrigatórios, dados na nota de licença do <link linkend="fdl-document">Documento</link>.</para>
+ <para>Preservar nesse aviso de licença as listas completas de <link linkend="fdl-invariant">Seções Invariantes</link> e os <link linkend="fdl-cover-texts">Textos de Capa</link> necessários fornecidos no aviso de licença do <link linkend="fdl-document">Documento</link>.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>H</title>
- <para>Inclua uma cópia inalterada desta Licença.</para>
+ <para>Incluir uma cópia inalterada desta Licença.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>I</title>
- <para>Preservar a seção intitulada <quote>Histórico</quote>, preservar seu título, e adicionar a esta um item declarando ao menos o título, o ano, novos autores, e o editor da <link linkend="fdl-modified">Versão Modificada</link> conforme incluído na <link linkend="fdl-title-page">Página de Título</link>. Se nenhuma seção intitulada <quote>Histórico</quote> estiver presente no <link linkend="fdl-document">Documento</link>, crie uma informando o título, o ano, os autores e o editor do Documento como evidenciado na Página de Título, em seguida adicione um item descrevendo a Versão Modificada como mencionado na sentença anterior.</para>
+ <para>Preservar a seção intitulada “Histórico”, e seu título, e adicionar a ele um item que indique pelo menos o título, o ano, os novos autores e o editor da <link linkend="fdl-modified">Versão Modificada</link> conforme indicado na <link linkend="fdl-title-page">Página de Título</link>. Se não houver uma seção intitulada “Histórico” no <link linkend="fdl-document">Documento</link>, crie um que declare o título, o ano, os autores e o editor do Documento conforme indicado em sua Página de Título e, em seguida, adicione um item descrevendo a Versão Modificada, como indicado na frase anterior.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>J</title>
- <para>Preservar o endereço de rede, se existir algum, informado pelo <link linkend="fdl-document">Documento</link> para acesso público a uma cópia <link linkend="fdl-transparent">Transparente</link> deste e, da mesma maneira, os endereços de rede dados no Documento para versões anteriores nas quais este se baseia. Estes podem ser colocados na seção <quote>Histórico</quote>. Você pode omitir um endereço de rede para um trabalho que foi publicado pelo menos quatro anos antes do Documento em si, ou se o editor original da versão à qual o endereço se refere der permissão.</para>
+ <para>Preservar a localização de rede, se for o caso, fornecida no <link linkend="fdl-document">Documento</link> para acesso público a uma cópia <link linkend="fdl-transparent">Transparente</link> do Documento, e também as localizações de rede fornecidas no Documento para versões anteriores nas quais ele foi baseado. Estas podem ser colocadas na seção “Histórico”. Você pode omitir uma localização de rede para um trabalho que foi publicado pelo menos quatro anos antes do Documento em si, ou se o editor original da versão a que se refere der permissão.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>K</title>
- <para>Preservar o título da seção para qualquer seção intitulada <quote>Agradecimentos</quote> ou <quote>Dedicatórias</quote> e preservar dentro da seção toda a substância e tom de cada um dos agradecimentos e/ou dedicatórias lá mencionados.</para>
+ <para>Em qualquer seção intitulada “Agradecimentos” ou “Dedicatórias”, preservar o título da seção, e preservar na seção toda a substância e tom de cada um dos agradecimentos e/ou das dedicatórias dados nela.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>L</title>
- <para>Preservar todas as <link linkend="fdl-invariant">Seções Invariantes</link> do <link linkend="fdl-document">Documento</link>, sem alterações em seus textos e títulos. Números de seção ou o equivalente não são considerados parte dos títulos das seções.</para>
+ <para>Preservar todas as <link linkend="fdl-invariant">Seções Invariantes</link> do <link linkend="fdl-document">Documento</link>, inalteradas em seus textos e em seus títulos. Os números de seção ou o equivalente não são considerados parte dos títulos das seções.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>M</title>
- <para>Apagar qualquer seção intitulada <quote>Apoio</quote>. Tal seção não deve ser incluída na <link linkend="fdl-modified">Versão Modificada</link>.</para>
+ <para>Excluir qualquer seção intitulada “Endossos”. Essa seção pode não estar incluída na <link linkend="fdl-modified">Versão Modificada</link>.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title>N</title>
- <para>Não renomear o título de qualquer seção existente como <quote>Apoio</quote> ou que resulte em conflito com o título de qualquer <link linkend="fdl-invariant">Seção Invariante</link>.</para>
+ <para>Não mudar o título de qualquer seção existente para “Endossos” ou para conflitar em título com qualquer <link linkend="fdl-invariant">Seção Invariante</link>.</para>
</formalpara>
</listitem>
</itemizedlist>
- <para>Se a <link linkend="fdl-modified">Versão Modificada</link> incluir novas seções iniciais ou apêndices que sejam qualificados como <link linkend="fdl-secondary">Seções Secundárias</link>, e não contiver material copiado do Documento, você pode, a seu critério, tornar algumas dessas ou todas essas seções em invariantes. Para fazer isso, adicione seus títulos à lista de <link linkend="fdl-invariant">Seções Invariantes</link> na nota de licença da Versão Modificada. Estes títulos devem ser distintos de quaisquer outros títulos de seções.</para>
+ <para>Se a <link linkend="fdl-modified">Versão Modificada</link> incluir novas seções ou apêndices de primeira linha que se qualifiquem como <link linkend="fdl-secondary">Seções Secundárias</link> e não contenham material copiado do Documento, você pode, a sua escolha, designar algumas ou todas essas seções como invariantes. Para fazer isso, adicione seus títulos à lista de <link linkend="fdl-invariant">Seções Invariantes</link> no aviso de licença da Versão Modificada. Esses títulos devem ser distintos de qualquer outro título de seção.</para>
- <para>Você pode incluir uma seção intitulada <quote>Apoio</quote>, desde que esta contenha apenas apoios recebidos limitados a sua <link linkend="fdl-modified">Versão Modificada</link> por várias fontes -- por exemplo, notas do revisor ou de que o texto foi aprovado por uma organização como a definição oficial de um padrão.</para>
+ <para>Você pode incluir uma seção intitulada “Endossos”, desde que contenha nada além do endosso da sua <link linkend="fdl-modified">Versão Modificada</link> por várias terceiros – por exemplo, declarações de revisão por pares ou de que o texto foi aprovado por uma organização como a definição oficial de um padrão.</para>
- <para>Você pode adicionar uma passagem de até cinco palavras como <link linkend="fdl-cover-texts">Texto de Capa Frontal</link>, e uma passagem de até 25 palavras como <link linkend="fdl-cover-texts">Texto de Contracapa</link>, ao fim da lista de <link linkend="fdl-cover-texts">Textos de Capa</link> na <link linkend="fdl-modified">Versão Modificada</link>. Somente uma passagem de Texto de Capa Frontal e uma de Texto de Contracapa podem ser adicionados por (ou através de arranjos feitos por) uma entidade qualquer. Caso o <link linkend="fdl-document">Documento</link> já incluir um texto de capa para a mesma capa, previamente incluído por você ou pelo arranjo feito pela mesma entidade em cujo nome você está agindo, você não poderá adicionar outro; mas você poderá substituir o antigo, com a permissão explícita do editor anterior, que o incluiu.</para>
+ <para>Você pode adicionar uma passagem de até cinco palavras como um <link linkend="fdl-cover-texts">Texto de Capa Frontal</link> e uma passagem de até 25 palavras como um <link linkend="fdl-cover-texts">Texto de Contracapa</link>, até o final da lista de <link linkend="fdl-cover-texts">Textos de Capa</link> na <link linkend="fdl-modified">Versão Modificada</link>. Apenas uma passagem de Texto de Capa Frontal e um de Texto de Contracapa pode ser adicionada por (ou por meio de acordos feitos por) qualquer entidade. Se o <link linkend="fdl-document">Documento</link> já incluir um texto de capa para a mesma capa, previamente adicionado por você ou por acordo feito pela mesma entidade em que você está agindo em nome de, você não pode adicionar outro; mas você pode substituir o antigo, mediante permissão explícita do editor anterior que adicionou o antigo.</para>
- <para>O(s) autor(es) e editor(es) do <link linkend="fdl-document">Documento</link>, por esta Licença, não concedem permissão para que seus nomes sejam usados a fins de publicidade, para defesa ou para apoio implícito de qualquer <link linkend="fdl-modified">Versão Modificada</link>.</para>
+ <para>O(s) autor(es) e editor(es) do <link linkend="fdl-document">Documento</link> não concedem por esta Licença permissão para usar seus nomes para publicidade ou afirmar ou implicar o endosso de qualquer <link linkend="fdl-modified">Versão Modificada</link>.</para>
</sect1>
<sect1 id="fdl-section5">
<title>5. COMBINANDO DOCUMENTOS</title>
- <para>Você pode combinar o <link linkend="fdl-document">Documento</link> com outros documentos publicados sob esta Licença, sob os termos definidos na <link linkend="fdl-section4">seção 4</link> acima para versões modificadas, desde que você inclua na combinação todas as <link linkend="fdl-invariant">Seções Invariantes</link> de todos os documentos originais, sem modificações, e as liste como Seções Invariantes de seu trabalho combinado, na sua nota de licença.</para>
+ <para>Você pode combinar o <link linkend="fdl-document">Documento</link> com outros documentos publicados sob esta Licença, nos termos definidos na <link linkend="fdl-section4">seção 4</link> acima para versões modificadas, desde que você inclua na combinação de todas as <link linkend="fdl-invariant">Seções Invariantes</link> de todos os documentos originais, não modificados, e liste todos eles como Seções Invariantes do seu trabalho combinado em seu aviso de licença.</para>
- <para>O trabalho combinado precisa conter somente uma cópia desta Licença, e várias <link linkend="fdl-invariant">Seções Invariantes</link> idênticas podem ser substituídas por uma única cópia. Se existirem várias Seções Invariantes de mesmo nome, porém com conteúdos diferentes, você deve tornar o título de cada uma destas seções único, adicionando ao fim destes, entre parênteses, o nome do autor ou, se conhecido, o editor original desta seção, ou ainda um número único. Faça o mesmo ajuste nos títulos de seção na lista de Seções Invariantes na nota de licença do trabalho combinado.</para>
+ <para>O trabalho combinado precisa conter somente uma cópia desta Licença, e várias <link linkend="fdl-invariant">Seções Invariantes</link> idênticas podem ser substituídas por uma única cópia. Se existirem várias Seções Invariantes de mesmo nome, porém com conteúdos diferentes, você deve tornar o título de cada uma destas seções único, adicionando ao fim deste, entre parênteses, o nome do autor ou, se conhecido, o editor original desta seção, ou ainda um número único. Faça o mesmo ajuste nos títulos de seção na lista de Seções Invariantes no aviso de licença do trabalho combinado.</para>
- <para>Na combinação, você deve combinar quaisquer seções intituladas <quote>Histórico</quote> nos vários documentos originais, formando uma seção intitulada <quote>Histórico</quote>; do mesmo modo, combine quaisquer seções intituladas <quote>Agradecimentos</quote>, e quaisquer seções intituladas <quote>Dedicatórias</quote>. Você deve apagar todas as seções intituladas <quote>Apoio</quote>.</para>
+ <para>Na combinação, você deve combinar todas as seções intituladas “Histórico” nos vários documentos originais, formando uma seção intitulada “Histórico”; da mesma forma, combinar todas as seções intituladas “Agradecimentos” e quaisquer seções intituladas “Dedicatórias”. Você deve excluir todas as seções intituladas “Endossos”.</para>
</sect1>
<sect1 id="fdl-section6">
<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>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>
+ <para>Você pode extrair um único documento de tal 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 referentes à cópia literal desse documento.</para>
</sect1>
<sect1 id="fdl-section7">
<title>7. AGREGAÇÃO COM TRABALHOS INDEPENDENTES</title>
- <para>Uma compilação do <link linkend="fdl-document">Documento</link> ou seus derivados com outros documentos ou trabalhos separados e independentes, dentro de ou sob um volume de um meio de armazenamento ou distribuição, não conta como um todo para uma <link linkend="fdl-modified">Versão Modificada</link> do Documento, contanto que nenhum direito autoral de compilação seja reivindicado para esta compilação. Tal compilação configura um <quote>agregado</quote> e esta Licença não se aplica aos outros trabalhos contidos na compilação do Documento, levando em conta serem compilados, caso eles mesmos não forem trabalhos derivados do Documento. Se o requisito de <link linkend="fdl-cover-texts">Texto da Capa</link> da <link linkend="fdl-section3">seção 3</link> é aplicável a estas cópias do Documento, e ainda se o Documento é menor do que um quarto do agregado inteiro, os Textos de Capa do Documento podem ser inseridos nas capas que envolvem somente o Documento no agregado. Caso contrário, eles devem aparecer em capas em volta do agregado como um todo.</para>
+ <para>Uma compilação do <link linkend="fdl-document">Documento</link> ou seus derivados com outros documentos ou trabalhos separados e independentes, em ou sobre um volume de um meio de armazenamento ou distribuição, não como um todo conta como uma <link linkend="fdl-modified">Versão Modificada</link> do Documento, desde que nenhuma compilação de direitos autorais seja reivindicada para a compilação. Tal compilação é chamada de “agregado” (aggregate), e esta Licença não se aplica aos outros trabalhos autônomos assim compilados com o Documento, por conta de serem assim compilados, se eles não forem eles próprios trabalhos derivados do Documento. Se o requisito do <link linkend="fdl-cover-texts">Texto da Capa</link> da <link linkend="fdl-section3">seção 3</link> for aplicável a essas cópias do Documento, então, se o Documento for inferior a um quarto do agregado inteiro, os Textos de Capa do Documento poderão ser colocados em capas que envolvam apenas o Documento no agregado. Caso contrário, eles devem aparecer nas capas envolvem todo o agregado.</para>
</sect1>
<sect1 id="fdl-section8">
<title>8. TRADUÇÃO</title>
- <para>Uma tradução é considerada como sendo um tipo de modificação, desta forma você pode distribuir traduções do <link linkend="fdl-document">Documento</link> sob os termos da <link linkend="fdl-section4">seção 4</link>. A substituição das <link linkend="fdl-invariant">Seções Invariantes</link> por traduções requer permissão especial dos detentores dos direitos autorais, embora você possa incluir traduções de algumas ou todas as Seções Invariantes juntamente às versões originais destas. Você pode incluir uma tradução desta Licença, desde que você também inclua a versão original em Inglês desta Licença. Em caso de discordância entre a tradução e a versão original desta Licença ou nota de licença, a versão original em inglês prevalecerá.</para>
+ <para>A tradução é considerada um tipo de modificação, então você pode distribuir as traduções do <link linkend="fdl-document">Documento</link> nos termos da <link linkend="fdl-section4">seção 4</link>. A substituição das <link linkend="fdl-invariant">Seções Invariantes</link> com traduções requer permissão especial de seus detentores de direitos autorais, mas você pode incluir traduções de algumas ou todas as Seções Invariantes além das versões originais destas Seções Invariantes. Você pode incluir uma tradução desta Licença, desde que você também inclua a versão original em inglês desta Licença. Em caso de desacordo entre a tradução e a versão original desta Licença, a versão original prevalecerá.</para>
</sect1>
<sect1 id="fdl-section9">
- <title>9. TÉRMINO</title>
- <para>Você não pode copiar, modificar, sublicenciar, ou distribuir o <link linkend="fdl-document">Documento</link> com exceção do que foi expressamente previsto sob esta Licença. Qualquer outra tentativa de cópia, modificação, sublicenciamento ou distribuição do Documento é nula, e implicará na rescisão automática de seus direitos sob esta Licença. Contudo, as partes que receberam as cópias, ou direitos, de você sob esta Licença não terão suas licenças rescindidas enquanto tais partes permanecerem em total acordo com a Licença.</para>
+ <title>9. TERMINAÇÃO</title>
+ <para>Você não pode copiar, modificar, sublicenciar ou distribuir o <link linkend="fdl-document">Documento</link>, exceto conforme expressamente previsto nesta Licença. Qualquer tentativa de copiar, modificar, sublicenciar ou distribuir o Documento é anulada e terminará automaticamente seus direitos sob esta Licença. No entanto, as partes que receberam cópias ou direitos de você sob esta Licença não terão suas licenças terminadas, desde que tais partes permaneçam em plena conformidade.</para>
</sect1>
<sect1 id="fdl-section10">
<title>10. FUTURAS REVISÕES DESTA LICENÇA</title>
- <para>A <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software Foundation</ulink> pode publicar novas versões, revisadas, da Licença de Documentação Livre GNU de tempos em tempos. Tais versões posteriores terão ideologia similar à presente versão, embora possam diferir em detalhes a fim de abordar novos problemas ou preocupações. Consulte: <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.</para>
+ <para>A <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software Foundation</ulink> pode publicar novas
e revisadas versões da Licença de Documentação Livre GNU de vez em quando. Essas novas versões serão semelhantes em espírito à versão atual, mas podem diferir em detalhes para resolver novos problemas ou preocupações. Veja <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.A <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software Foundation</ulink> pode publicar novas versões, revisadas, da Licença de Documentação Livre GNU de tempos em tempos. Tais versões posteriores terão ideologia similar à presente versão, embora possam diferir em detalhes a fim de abordar novos problemas ou preocupações. Consulte: <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.</para>
- <para>É dado, a cada versão da Licença, um número de versão distinto. Se o <link linkend="fdl-document">Documento</link> especificar que um número de versão em específico desta Licença <quote>ou qualquer versão posterior</quote> se aplica a ele, você tem a opção de seguir os termos e condições tanto da versão especificada quanto de qualquer versão posterior que tenha sido publicada (não como rascunho) pela Free Software Foundation. Se o documento não especificar um número de versão desta Licença, você pode escolher qualquer versão já publicada (não como rascunho) pela Free Software Foundation.</para>
+ <para>Cada versão da Licença recebe um número de versão distinto. Se o <link linkend="fdl-document">Documento</link> especifica que uma versão numerada específica desta Licença “ou qualquer versão posterior” aplica-se a ele, você tem a opção de seguir os termos e condições daquela versão especificada ou de qualquer versão posterior que tenha sido publicada (não como um rascunho) pela Free Software Foundation. Se o Documento não especificar um número de versão desta Licença, você pode escolher qualquer versão publicada (não como um rascunho) pela Free Software Foundation.</para>
</sect1>
<sect1 id="fdl-using">
<title>Adendo</title>
- <para>Para usar esta Licença em um documento que você escreveu, inclua uma cópia desta no documento e adicione as seguintes notas de direitos autorais e licença logo após a página de título:</para>
+ <para>Para usar esta Licença em um documento que você escreveu, inclua uma cópia da Licença no documento e coloque os seguintes avisos de direitos autorais e de licenças logo após a página de título:</para>
<blockquote>
<para>Copyright ANO SEU NOME.</para>
- <para>Permissão concedida para copiar, distribuir e/ou modificar este documento sob os termos da Licença de Documentação Livre GNU (GNU Free Documentation License), Versão 1.1 ou qualquer versão mais recente publicada pela Free Software Foundation; com as <link linkend="fdl-invariant">Seções Invariantes</link>, sendo LISTADO SEUS TÍTULOS, com os <link linkend="fdl-cover-texts">Textos de Capa Frontal</link> sendo LISTADOS, e com os <link linkend="fdl-cover-texts">Textos de Contracapa</link> sendo LISTADOS. Uma cópia da licença está inclusa na seção entitulada <quote>Licença de Documentação Livre GNU (GNU Free Documentation License)</quote>.</para>
+ <para>Permissão concedida para copiar, distribuir e/ou modificar este documento sob os termos da Licença de Documentação Livre GNU, Versão 1.1 ou qualquer versão mais recente publicada pela Free Software Foundation; com as <link linkend="fdl-invariant">Seções Invariantes</link> sendo LISTE SEUS TÍTULOS, com os <link linkend="fdl-cover-texts">Textos de Capa Frontal</link> sendo LISTA e os <link linkend="fdl-cover-texts">Textos de Contracapa</link> sendo LISTA. Uma cópia da licença está incluída na seção intitulada "Licença de Documentação Livre GNU" (GNU Free Documentation License).</para>
</blockquote>
- <para>Se você não tiver qualquer <link linkend="fdl-invariant">Seção Invariante</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 você não tiver <link linkend="fdl-invariant">Seção Invariante</link>, escreva “sem Seções Invariantes” em vez de dizer quais são invariantes. Se você não tiver <link linkend="fdl-cover-texts">Textos de Capa Frontal</link>, escreva “sem Textos da Capa Frontal” em vez de “Textos de Capa Frontal sendo LIST”; Da mesma forma para <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</ulink> (GNU General Public License), para permitir seu uso em software livre.</para>
+ <para>Se o seu documento contiver exemplos não triviais do código do programa, recomendamos que apresente esses exemplos em paralelo, sob sua escolha de licença de software livre, como a <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html">Licença Pública Geral GNU</ulink> (GNU General Public License), para permitir sua utilização em software livre.</para>
</sect1>
</appendix>
"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: 2018-03-24 15:17+0000\n"
-"PO-Revision-Date: 2018-03-28 23:03-0200\n"
+"POT-Creation-Date: 2018-10-03 08:17+0000\n"
+"PO-Revision-Date: 2018-10-05 17:26-0200\n"
"Last-Translator: Rafael Fontenelle <rafaelff@gnome.org>\n"
"Language-Team: Brazilian Portuguese <gnome-pt_br-list@gnome.org>\n"
"Language: pt_BR\n"
#. (itstool) path: revhistory/revision
#: C/index.docbook:83
-#| msgid ""
-#| "<revnumber>1.27.1</revnumber> <date>07 Dec 2017</date> "
-#| "<authorinitials>ss</authorinitials> <revremark>development</revremark>"
msgid ""
-"<revnumber>1.2
8.1</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
+"<revnumber>1.2
9.1</revnumber> <date>28 Aug 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>development</revremark>"
msgstr ""
-"<revnumber>1.28.1</revnumber> <date>24 Mar 2018</date> "
-"<authorinitials>ss</authorinitials> <revremark>desenvolvimento</revremark>"
+"<revnumber>1.29.1</revnumber> <date>24 Ago 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>desenvolvimento</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
-#| msgid ""
-#| "<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
-#| "authorinitials> <revremark>bug fix</revremark>"
+msgid ""
+"<revnumber>1.29</revnumber> <date>28 Aug 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>development</revremark>"
+msgstr ""
+"<revnumber>1.29</revnumber> <date>28 Ago 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>desenvolvimento</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
msgid ""
"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
msgstr ""
-"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> "
-"<authorinitials>ss</authorinitials> <revremark>correçãoõesão de "
-"erros</revremark>"
+"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>correções de erros</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
msgid ""
"<revnumber>1.27</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>fine tuning of the python port</revremark>"
"authorinitials> <revremark>ajustes do porte para Python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
+#: C/index.docbook:107
msgid ""
"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>port all tools from perl/bash to python</"
"Python</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:107
+#: C/index.docbook:113
msgid ""
"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
"authorinitials> <revremark>correção de erros, limpezas de testes</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:113
+#: C/index.docbook:119
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>correção de erros</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:119
+#: C/index.docbook:125
msgid ""
"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>correção de erros</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:125
+#: C/index.docbook:131
msgid ""
"<revnumber>1.22</revnumber> <date>07 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"obsoletas</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:131
+#: C/index.docbook:137
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:137
+#: C/index.docbook:143
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:143
+#: C/index.docbook:149
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:149
+#: C/index.docbook:155
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:155
+#: C/index.docbook:161
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:161
+#: C/index.docbook:167
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:167
+#: C/index.docbook:173
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:173
+#: C/index.docbook:179
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:179
+#: C/index.docbook:185
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:185
+#: C/index.docbook:191
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:191
+#: C/index.docbook:197
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:204
+#: C/index.docbook:210
msgid "Introduction"
msgstr "Introdução"
#. (itstool) path: chapter/para
-#: C/index.docbook:206
+#: C/index.docbook:212
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:212
+#: C/index.docbook:218
msgid "What is GTK-Doc?"
msgstr "O que é GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:214
+#: C/index.docbook:220
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:222
+#: C/index.docbook:228
msgid "How Does GTK-Doc Work?"
msgstr "Como o GTK-Doc funciona?"
#. (itstool) path: sect1/para
-#: C/index.docbook:224
+#: C/index.docbook:230
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:231
+#: C/index.docbook:237
msgid ""
"GTK-Doc consists of a number of python scripts, each performing a different "
"step in the process."
msgstr ""
-"GTK-Doc consiste de um número de scripts em Python, cada um executando uma "
+"GTK-Doc consiste em um número de scripts em Python, cada um executando uma "
"etapa diferente no processo."
#. (itstool) path: sect1/para
-#: C/index.docbook:236
+#: C/index.docbook:242
msgid "There are 5 main steps in the process:"
msgstr "Há 5 etapas principais no processo:"
#. (itstool) path: listitem/para
-#: C/index.docbook:243
+#: C/index.docbook:249
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)."
+"source files with the documentation for each function, macro, structs or "
+"unions, etc."
msgstr ""
-"<guilabel>Escrevendo a documentação.</guilabel> O autor preenche os arquivos "
-"fonte com a documentação para cada função, macro, union, etc. "
-"(Anteriormente, a informação era inserida em arquivos de modelo gerados, o "
-"que não é mais recomendado)."
+"<guilabel>Escrita da documentação.</guilabel> O autor preenche os arquivos "
+"fonte com a documentação para cada função, macro, structs ou unions, etc."
#. (itstool) path: listitem/para
-#: C/index.docbook:253
+#: C/index.docbook:258
msgid ""
"<guilabel>Gathering information about the code.</guilabel> "
"<application>gtkdoc-scan</application> scans the header files of the code "
"the ones in <filename><module>-decl.txt</filename> into <filename><"
"module>-overrides.txt</filename>."
msgstr ""
-"<guilabel>Juntando informação sobre o código.</guilabel> <application>gtkdoc-"
-"scan</application> varre os arquivos de cabeçalho do código buscando por "
-"declarações de funções, macros, enums, structs e unions. Ele cria o arquivo "
-"<filename><módulo>-decl-list.txt</filename> contendo uma lista de "
-"declarações, inserindo-as em seções da acordo com o arquivo de cabeçalho no "
-"qual se encontram. Na primeira execução, este arquivo é copiado para "
-"<filename><módulo>-sections.txt</filename>. O autor pode reorganizar "
-"as seções, e a ordem das declarações dentro delas, para produzir a ordem "
-"final desejada. O segundo arquivo que ele gera é <filename><módulo>-"
-"decl.txt</filename>. Este arquivo contém as declarações completas "
-"encontradas pela varredura. Se por algum motivo se queira que alguns "
-"apareçam nos documentos, no qual declarações completas não puderam ser "
-"encontradas pela varredura ou a declaração deveria aparecer de outra forma, "
-"pode-se colocar entidades similares aos do <filename><módulo>-decl."
-"txt</filename> no <filename><módulo>-overrides.txt</filename>."
+"<guilabel>Coleta de informação sobre o código.</guilabel> "
+"<application>gtkdoc-scan</application> varre os arquivos de cabeçalho do "
+"código buscando por declarações de funções, macros, enums, structs e unions. "
+"Ele cria o arquivo <filename><módulo>-decl-list.txt</filename> "
+"contendo uma lista de declarações, inserindo-as em seções da acordo com o "
+"arquivo de cabeçalho no qual se encontram. Na primeira execução, este "
+"arquivo é copiado para <filename><módulo>-sections.txt</filename>. O "
+"autor pode reorganizar as seções, e a ordem das declarações dentro delas, "
+"para produzir a ordem final desejada. O segundo arquivo que ele gera é "
+"<filename><módulo>-decl.txt</filename>. Este arquivo contém as "
+"declarações completas encontradas pela varredura. Se por algum motivo se "
+"quiser que alguns símbolos apareçam nos documentos, nos quais declarações "
+"completas não puderam ser encontradas pela varredura ou a declaração deveria "
+"aparecer de outra forma, pode-se colocar entidades similares aos do "
+"<filename><módulo>-decl.txt</filename> no <filename><módulo>-"
+"overrides.txt</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:270
+#: C/index.docbook:275
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:276
+#: C/index.docbook:281
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> não deveria mais ser usada. Ele "
-"era necessário no passado, quando GObject ainda era GtkObject dentro do gtk+."
+"<application>gtkdoc-scanobj</application> não deve mais ser usado. Ele era "
+"necessário no passado, quando GObject ainda era GtkObject dentro do gtk+."
#. (itstool) path: listitem/para
-#: C/index.docbook:283
+#: C/index.docbook:288
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>Gera
ndo o XML e HTML/PDF.</guilabel> <application>gtkdoc-mkdb</"
+"<guilabel>Gera
ção do XML e do 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 "
+"<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:292
+#: C/index.docbook:297
msgid ""
"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
"pacote>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:298
+#: C/index.docbook:303
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:306
+#: C/index.docbook:311
msgid ""
"<guilabel>Fixing up cross-references between documents.</guilabel> After "
"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
"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>Consertando referências cruzadas entre documentos.</guilabel> Após "
+"<guilabel>Correção de referências cruzadas entre documentos.</guilabel> Após "
"a instalação dos arquivos HTML, <application>gtkdoc-fixxref</application> "
"pode ser executado para consertar referências cruzadas entre documentos "
"separados. Por exemplo, a documentação do GTK+ contém muitas referências "
"volta para links locais (onde aquelas documentações estão instaladas)."
#. (itstool) path: sect1/title
-#: C/index.docbook:324
+#: C/index.docbook:329
msgid "Getting GTK-Doc"
msgstr "Obtendo GTK-Doc"
#. (itstool) path: sect2/title
-#: C/index.docbook:327
+#: C/index.docbook:332
msgid "Requirements"
msgstr "Requisitos"
#. (itstool) path: sect2/para
-#: C/index.docbook:328
+#: C/index.docbook:333
msgid ""
"<guilabel>python 2/3</guilabel> - the main scripts are written in python."
msgstr ""
-"<guilabel>python 2/3</guilabel> - os scripts principais são escritos em "
+"<guilabel>python 2/3</guilabel> – os scripts principais são escritos em "
"Python."
#. (itstool) path: sect2/para
-#: C/index.docbook:331
+#: C/index.docbook:336
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>
- o processador de xslt do libxslt <ulink url="
+"<guilabel>xsltproc</guilabel>
– o processador de xslt do libxslt <ulink url="
"\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/</ulink>"
#. (itstool) path: sect2/para
-#: C/index.docbook:335
+#: C/index.docbook:340
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>
- as folhas de estilo xsl de docbook <ulink "
+"<guilabel>docbook-xsl</guilabel>
– as folhas de estilo xsl de 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:339
+#: C/index.docbook:344
msgid ""
"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
"examples"
msgstr ""
"Um dentre <guilabel>source-highlight</guilabel>, <guilabel>highlight</"
-"guilabel> ou <guilabel>vim</guilabel> - opcional - usado para destaque de "
+"guilabel> ou <guilabel>vim</guilabel> – opcional - usado para destaque de "
"sintaxe de exemplos"
#. (itstool) path: sect1/title
-#: C/index.docbook:347
+#: C/index.docbook:352
msgid "About GTK-Doc"
msgstr "Sobre GTK-Doc"
#. (itstool) path: sect1/para
-#: C/index.docbook:349 C/index.docbook:363
+#: C/index.docbook:354
+#| msgid ""
+#| "Historically GTK-Doc was used to generate template files from the soures "
+#| "code. These template files could be used by developers to enter the API "
+#| "documentation. This approach was rather inconvenient because it required "
+#| "to keep the generated files under version control. Since GTK-Doc 1.9 it "
+#| "became possible to place all API information into source comments, which "
+#| "made the template support obsolete. In version 1.26 template support has "
+#| "been removed."
+msgid ""
+"Historically GTK-Doc was used to generate template files from the sources "
+"code. These template files could be used by developers to enter the API "
+"documentation. This approach was rather inconvenient because it required to "
+"keep the generated files under version control. Since GTK-Doc 1.9 it became "
+"possible to place all API information into source comments, which made the "
+"template support obsolete. In version 1.26 template support has been removed."
+msgstr ""
+"Historicamente, o GTK-Doc foi usado para gerar arquivos de modelo a partir "
+"do código-fonte. Esses arquivos de modelo poderiam ser usados pelos "
+"desenvolvedores para inserir a documentação da API. Essa abordagem era "
+"bastante inconveniente porque exigia manter os arquivos gerados sob controle "
+"de versão. Desde o GTK-Doc 1.9, tornou-se possível colocar todas as "
+"informações da API em comentários no fonte, o que tornou o suporte ao modelo "
+"obsoleto. Na versão 1.26 suporte ao modelo foi removido."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:364 C/index.docbook:378
msgid "(FIXME)"
msgstr "(CORRIJA-ME)"
#. (itstool) path: sect1/para
-#: C/index.docbook:353
+#: C/index.docbook:368
msgid ""
-"(History, authors, web pages, mailing list, license, future plans, "
-"comparison with other similar systems.)"
+"(authors, web pages, mailing list, license, future plans, comparison with "
+"other similar systems.)"
msgstr ""
-"(História, autores, páginas web, lista de discussão, licença, planos "
-"futuros, comparação com outros sistemas similares.)"
+"(autores, páginas web, lista de discussão, licença, planos futuros, "
+"comparação com outros sistemas similares.)"
#. (itstool) path: sect1/title
-#: C/index.docbook:361
+#: C/index.docbook:376
msgid "About this Manual"
msgstr "Sobre este manual"
#. (itstool) path: sect1/para
-#: C/index.docbook:367
+#: C/index.docbook:382
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
-msgid "Setting up your project"
-msgstr "Preparando seu projeto"
+#: C/index.docbook:391
+msgid "Project Setup"
+msgstr "Configurando o projeto"
#. (itstool) path: chapter/para
-#: C/index.docbook:378
-msgid ""
-"The next sections describe what steps to perform to integrate GTK-Doc into "
-"your project. Theses sections assume we work on a project called 'meep'. "
-"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 ""
-"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."
+#: C/index.docbook:393
+msgid ""
+"This Chapter describes the steps that are necessary to integrate GTK-Doc "
+"into your project. The integration of GTK-Doc into a project includes the "
+"following steps:"
+msgstr ""
+"Este capítulo descreve os passos necessários para integrar o GTK-Doc ao seu "
+"projeto. A integração do GTK-Doc em um projeto inclui as seguintes etapas:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:401
+msgid ""
+"Preparation of the directory structure and creating required configuration "
+"files for your GTK-Doc documentation (see <link linkend=\"settingup_docfiles"
+"\"> Setting up a skeleton documentation</link>)."
+msgstr ""
+"Preparação da estrutura de diretórios e criação dos arquivos de configuração "
+"necessários para sua documentação do GTK-Doc (consulte <link linkend="
+"\"settingup_docfiles\">Preparando o esqueleto de uma documentação</link>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:409
+msgid ""
+"Adjusting the build system to build your documentation using the GTK-Doc "
+"tools. Multiple build systems are supported, in this manual we describe how "
+"to integrate GTK-Doc with <link linkend=\"settingup_autotools\">Autotools</"
+"link>, <link linkend=\"settingup_cmake\">CMake</link>, and <link linkend="
+"\"settingup_plain_makefiles\">plain Makefiles</link>."
+msgstr ""
+"Ajuste do sistema de compilação para compilar sua documentação usando as "
+"ferramentas do GTK-Doc. Há suporte a vários sistemas de compilação, neste "
+"manual descrevemos como integrar o GTK-Doc com <link linkend="
+"\"settingup_autotools\">Autotools</link>, <link linkend=\"settingup_cmake"
+"\">CMake</link> e <link linkend=\"settingup_plain_makefiles\">Makefiles "
+"simples</link>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:419
+msgid ""
+"Adding GTK-Doc specific files to version control and deciding which files to "
+"ignore (see <link linkend=\"settingup_vcs\"> Integration with version "
+"control systems</link>)."
+msgstr ""
+"Adição de arquivos específicos do GTK-Doc para o controle de versão e "
+"decisão de quais arquivos ignorar (veja <link linkend=\"settingup_vcs\"> "
+"Integração com sistemas de controle de versão</link>)."
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:427
+msgid ""
+"The following sections assume we work on a project called <code>meep</code>. "
+"This project contains two packages (or modules), a library called "
+"<code>libmeep</code> and an end-user app called <code>meeper</code>."
+msgstr ""
+"As seções a seguir presumem que trabalhamos em um projeto chamado "
+"<code>meep</code>. Este projeto contém dois pacotes (ou módulos), uma "
+"biblioteca chamada <code>libmeep</code> e um aplicativo de usuário final "
+"chamado <code>meeper</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:389
+#: C/index.docbook:436
msgid "Setting up a skeleton documentation"
msgstr "Preparando o esqueleto de uma documentação"
#. (itstool) path: sect1/para
-#: C/index.docbook:391
-msgid ""
-"Under your top-level project directory create folders called docs/reference "
-"(this way you can also have docs/help for end-user documentation). It is "
-"recommended to create another subdirectory with the name of the doc-package. "
-"For packages with just one library this step is not necessary."
-msgstr ""
-"No diretório raiz do seu projeto, crie pastas chamadas docs/reference (desta "
-"forma, você também pode ter docs/help para documentação para usuário final). "
-"É recomendado criar um outro subdiretório com o nome do pacote de "
-"documentação. Para pacotes com apenas uma biblioteca, esta etapa não é "
-"obrigatória."
+#: C/index.docbook:438
+msgid ""
+"A common convention is to place documentation into a folder called "
+"<code>docs</code> inside your top-level project directory. We usually "
+"distinguish between <emphasis>reference documentation</emphasis> intended "
+"for developers and an <emphasis>user manual</emphasis> intended for end-"
+"users. Again the convention is to have separate folders for both. We usually "
+"place the reference documentation in a folder named <code>reference</code> "
+"and the end-user manual in a folder named <code>help</code> as. According to "
+"the above convention the documentation for our <code>libmeep</code> package "
+"would be placed into: <code>docs/reference/libmeep</code>. For packages with "
+"just one library or application the documentation could also be placed "
+"directly into <code>docs/reference</code>. It is not mandatory to use the "
+"above convention, but if you choose to use a different directory structure "
+"you must adjust your build system configuration to match your directory "
+"structure."
+msgstr ""
+"Uma convenção comum é colocar a documentação em uma pasta chamada "
+"<code>docs</code> dentro do seu diretório de projeto de nível superior. "
+"Costumamos distinguir entre a <emphasis>documentação de referência</"
+"emphasis> destinada aos programadores e um <emphasis>manual do usuário</"
+"emphasis> destinado aos usuários-finais. Novamente a convenção é ter pastas "
+"separadas para ambos. Geralmente, colocamos a documentação de referência em "
+"uma pasta chamada <code>reference</code> e o manual do usuário final em uma "
+"pasta chamada <code>help</code>. De acordo com a convenção acima, a "
+"documentação do nosso pacote <code>libmeep</code> seria colocada em: "
+"<code>docs/reference/libmeep</code>. Para pacotes com apenas uma biblioteca "
+"ou aplicativo, a documentação também pode ser colocada diretamente em "
+"<code>docs/reference</code>. Não é obrigatório usar a convenção acima, mas "
+"se você optar por usar uma estrutura de diretórios diferente, deverá ajustar "
+"a configuração do sistema de compilação para que corresponda à estrutura do "
+"diretório."
#. (itstool) path: example/title
-#: C/index.docbook:400
-msgid "Example directory structure"
-msgstr "Exemplo de estrutura de diretórios"
+#: C/index.docbook:469
+msgid "Example directory structure of <emphasis>meep</emphasis> project"
+msgstr ""
+"Exemplo de estrutura de diretórios de projeto <emphasis>meep</emphasis>"
#. (itstool) path: example/programlisting
-#: C/index.docbook:401
+#: C/index.docbook:471
#, no-wrap
msgid ""
"\n"
"meep/\n"
" docs/\n"
-" reference/\n"
+" reference/ # reference documentation\n"
" libmeep/\n"
" meeper/\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
"\n"
"meep/\n"
" docs/\n"
-" reference/\n"
+" reference/ # documentação de referência\n"
" libmeep/\n"
" meeper/\n"
+" help/ # opcional: manual de usuário\n"
+" meeper/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:398
-msgid "This can then look as shown below: <_:example-1/>"
-msgstr "Isto pode, então, parecer como exibido abaixo: <_:example-1/>"
+#: C/index.docbook:463
+msgid ""
+"In the following sections we will assume a directory structure for our "
+"<emphasis>meep</emphasis> project that uses the above conventions. <_:"
+"example-1/>"
+msgstr ""
+"Nas seções a seguir, vamos presumir uma estrutura de diretórios para o nosso "
+"projeto <emphasis>meep</emphasis> que usa as convenções acima. <_:example-1/>"
#. (itstool) path: sect1/title
+#: C/index.docbook:488
+msgid "Integration with Autotools"
+msgstr "Integração com Autotools"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:489
+msgid ""
+"Integration of GTK-Doc into an autotools-based build system requires the "
+"following steps:"
+msgstr ""
+"A integração do GTK-Doc em um sistema de compilação baseado em autotools "
+"requer as seguintes etapas:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:495
+msgid ""
+"Ensure that <application>gtkdocize</application> is run once before the "
+"<filename>configure</filename> script. If an <filename>autogen.sh</filename> "
+"script is present, adjust it to check for GTK-Doc and add a call to "
+"<application>gtkdocize</application>."
+msgstr ""
+"Certificar-se de que <application>gtkdocize</application> seja executado uma "
+"vez antes do script <filename>configure</filename>. Se um script "
+"<filename>autogen.sh</filename> estiver presente, ajuste-o para verificar o "
+"GTK-Doc e adicione uma chamada ao <application>gtkdocize</application>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:503
+msgid ""
+"The main purpose of <application>gtkdocize</application> is to make the "
+"<filename>gtk-doc.make</filename> Makefile and the <filename>gtk-doc.m4</"
+"filename> macro definition file available to the build system, either by "
+"copying or linking it into the project."
+msgstr ""
+"O principal objetivo do <application>gtkdocize</application> é fazer com que "
+"o arquivo Makefile <filename>gtk-doc.make</filename> e o arquivo de "
+"definição de macro <filename>gtk-doc.m4</filename> estejam disponíveis para "
+"a compilação sistema, seja copiando ou vinculando-o ao projeto."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:512
+msgid ""
+"Add the necessary <application>autoconf</application> macros to "
+"<filename>configure.ac</filename> to enable GTK-Doc in your build system to "
+"allow configuration of GTK-Doc via the generated <filename>configure</"
+"filename> script."
+msgstr ""
+"Adicionar as macros <application>autoconf</application> necessárias ao "
+"<filename>configure.ac</filename> para ativar o GTK-Doc em seu sistema de "
+"compilação para permitir a configuração do GTK-Doc através do script "
+"<filename>configure</filename> gerado."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:518
+msgid ""
+"Among others with registers the <code>--enable-gtk-doc</code> option with "
+"the <filename>configure</filename> script."
+msgstr ""
+"Entre outros, registra a opção <code>--enable-gtk-doc</code> com o script "
+"<filename>configure</filename>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:524
+msgid ""
+"Create an <application>automake</application> script for each application or "
+"library in your project. In the example used in this documentation this step "
+"applies to both <code>meeper</code> and <code>libmeep</code>."
+msgstr ""
+"Criar um script <application>automake</application> para cada aplicativo ou "
+"biblioteca em seu projeto. No exemplo usado nesta documentação, esta etapa "
+"se aplica tanto a <code>meeper</code> quanto a <code>libmeep</code>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:533
+msgid ""
+"In the following sections, we will perform the above steps in reverse order. "
+"We start with the <application>automake</application> scripts and work our "
+"way up to <filename>configure.ac</filename> and <filename>autogen.sh</"
+"filename>. Then we show how enable Gtk-Doc in the build system and how to "
+"build the documentation."
+msgstr ""
+"Nas seções a seguir, executaremos as etapas acima na ordem inversa. "
+"Começamos com os scripts <application>automake</application> e vamos "
+"trabalhando até o <filename>configure.ac</filename> e <filename>autogen.sh</"
+"filename>. Então, mostramos como habilitar o Gtk-Doc no sistema de "
+"compilação e como compilar a documentação."
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:543
+msgid "Integration with automake"
+msgstr "Integração com automake"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:545
+msgid ""
+"First copy the <filename>Makefile.am</filename> from the <filename class="
+"\"directory\">examples</filename> sub-directory of the <ulink url=\"https://"
+"gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am\"> gtkdoc-"
+"sources</ulink> to your project's reference documentation directory (e.g. "
+"<filename class=\"directory\">docs/reference/<package></filename>). A "
+"local copy should be available under e.g. <filename>/usr/share/doc/gtk-doc-"
+"tools/examples/Makefile.am</filename>. If you have multiple packages repeat "
+"this for each one."
+msgstr ""
+"Primeiro copie o <filename>Makefile.am</filename> do subdiretório do "
+"<filename class=\"directory\">exemplo</filename> do <ulink url=\"https://"
+"gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am\"> gtkdoc-"
+"sources</ulink> para o diretório da documentação de referência do seu "
+"projeto (por exemplo, <filename class=\"directory\">./docs/reference/<"
+"pacote></filename>). Uma cópia local deveria estar disponível sob, por "
+"exemplo, <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</"
+"filename>. Se você tiver múltiplos pacotes de documentação, repita isso para "
+"cada um."
+
+#. (itstool) path: note/simpara
+#: C/index.docbook:558
+msgid ""
+"Do not forget to add each <filename>Makefile.am</filename> to the "
+"<function>AC_CONFIG_FILES</function> macro in <filename>configure.ac</"
+"filename>. For <filename>docs/reference/libmeep/Makefile.am</filename> you "
+"will need to add the entry <filename>docs/reference/libmeep/Makefile</"
+"filename> to <function>AC_CONFIG_FILES</function>."
+msgstr ""
+"Não se esqueça de adicionar cada <filename>Makefile.am</filename> à macro "
+"<function>AC_CONFIG_FILES</function> em <filename>configure.ac</filename>. "
+"Para <filename>docs/reference/libmeep/Makefile.am</filename> você precisará "
+"adicionar a entrada <filename>docs/reference/libmeep/Makefile</filename> "
+"para <function>AC_CONFIG_FILES</function>."
+
#. (itstool) path: example/title
-#: C/index.docbook:416 C/index.docbook:423
+#: C/index.docbook:570
+msgid "Example directory structure with <filename>Makefiles.am</filename>"
+msgstr ""
+"Exemplo de estrutura de diretório com <filename>Makefiles.am</filename>"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:573
+#, no-wrap
+msgid ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/ # reference documentation\n"
+" libmeep/\n"
+" Makefile.am\n"
+" meeper/\n"
+" Makefile.am\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+msgstr ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/ # documentação de referência\n"
+" libmeep/\n"
+" Makefile.am\n"
+" meeper/\n"
+" Makefile.am\n"
+" help/ # opcional: manual de usuário\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:589
+msgid ""
+"Next, you need to customize the copied Makefiles and provide values for the "
+"various parameters in each <filename>Makefile.am</filename>. All settings "
+"have a comment above them that describes their purpose and how to customize "
+"the setting. Most settings are used to supply extra flags to the respective "
+"tools to which they apply. Every tool has a variable of the form <option><"
+"TOOLNAME>_OPTIONS</option> (e.g. the tool <application>gtkdoc-mkhtml</"
+"application> has an option named <code>MKHTML_OPTIONS</code>). All the tools "
+"support <option>--help</option> to list the supported options."
+msgstr ""
+"Em seguida, você precisa personalizar os Makefiles copiados e fornecer "
+"valores para os vários parâmetros em cada <filename>Makefile.am</filename>. "
+"Todas as configurações têm um comentário sobre elas que descreve seu "
+"propósito e como personalizar a configuração. A maioria das configurações "
+"são usadas para fornecer opções extras para as respectivas ferramentas às "
+"quais elas se aplicam. Cada ferramenta tem uma variável na forma <option><"
+"NOME-FERRAMENTA>_OPTIONS</option> (por exemplo, a ferramenta "
+"<application>gtkdoc-mkhtml</application> tem uma opção chamada "
+"<code>MKHTML_OPTIONS</code>). Todas as ferramentas têm suporte a <option>--"
+"help</option> pra listar os parâmetros disponíveis."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:613
+msgid ""
+"<option>DOC_MODULE</option> is used to provide the name of the package that "
+"is being documentated (e.g. <code>meeper</code>, or <code>libmeep</code>)."
+msgstr ""
+"<option>DOC_MODULE</option> é usado para fornecer o nome do pacote que está "
+"sendo documentado (por exemplo, <code>meeper</code> ou <code>libmeep</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:620
+msgid ""
+"<option>DOC_SOURCE_DIR</option> is used to specify the location of source "
+"directory which GTK-Doc searches for your API documentation. This will "
+"usually be <code> DOC_SOURCE_DIR=$(top_srcdir)/src </code> or a sub-"
+"directory of that directory."
+msgstr ""
+"<option>DOC_SOURCE_DIR</option> é usado para especificar a localização do "
+"diretório fonte que o GTK-Doc pesquisa na documentação da API. Isso "
+"geralmente será <code>DOC_SOURCE_DIR=$(top_srcdir)/src </code> ou um "
+"subdiretório desse diretório."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:633
+msgid ""
+"<option>HFILE_GLOB</option> and <option>CFILE_GLOB</option> are used for "
+"dependencies. Each option take a file-glob (e.g. <code>HFILE_GLOB="
+"$(top_srcdir)/src/*.c</code>). The documentation will be rebuilt if any of "
+"the matched files change."
+msgstr ""
+"<option>HFILE_GLOB</option> e <option>CFILE_GLOB</option> são usados para "
+"dependências. Cada opção pega um arquivo glob (por exemplo, <code>HFILE_GLOB="
+"$(top_srcdir)/src/*.c</code>). A documentação será recompilada se qualquer "
+"um dos arquivos correspondentes for alterado."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:645
+msgid ""
+"<option>EXTRA_HFILES</option> allows to specify extra header files to "
+"include when scanning for API documentation, which are not found under "
+"<code>DOC_SOURCE_DIR</code> (e.g. <code> EXTRA_HFILES=$(top_srcdir}/contrib/"
+"extra.h</code>)."
+msgstr ""
+"<option>EXTRA_HFILES</option> permite especificar arquivos de cabeçalho "
+"extras para incluir ao verificar a documentação da API, que não são "
+"encontrados em <code>DOC_SOURCE_DIR</code> (por exemplo, <code>EXTRA_HFILES="
+"$(top_srcdir}/contrib/extra.h</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:655
+msgid ""
+"<option>IGNORE_HFILES</option> allows to specify header files or directories "
+"to ignore when scanning for API documentation. Use the basename of the file "
+"or directory (e.g. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h "
+"private_code_folder</code>)."
+msgstr ""
+"<option>IGNORE_HFILES</option> permite especificar arquivos ou diretórios de "
+"cabeçalho a serem ignorados ao verificar a documentação da API. Use o nome "
+"de base do arquivo ou diretório (por exemplo, <code>IGNORE_HFILES=gtkdebug.h "
+"gtkintl.h private_code_folder</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:665
+msgid ""
+"<option>HTML_IMAGES</option> allows to specify images files which will be "
+"copied into the <filename>html/</filename> directory of the generated "
+"documentation. If your API documentation includes any images they need to be "
+"added to this option (e.g. <code> HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/"
+"stock_about_24.png</code>)."
+msgstr ""
+"<option>HTML_IMAGES</option> permite especificar arquivos de imagens que "
+"serão copiados para o diretório <filename>html/</filename> da documentação "
+"gerada. Se a documentação da API incluir imagens, elas precisam ser "
+"adicionadas a essa opção (por exemplo, <code>HTML_IMAGES=$(top_srcdir)/gtk/"
+"stock-icons/stock_about_24.png</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:678
+msgid ""
+"<option>content_files</option> allows to specify extra files that are "
+"included by <code>$(DOC_MAIN_SGML_FILE)</code> (e.g. <code> "
+"content_files=running.xml building.xml changes-2.0.xml</code>)."
+msgstr ""
+"<option>content_files</option> permite especificar arquivos extras incluídos "
+"por <code>$(DOC_MAIN_SGML_FILE)</code> (por exemplo, "
+"<code>content_files=running.xml building.xml changes-2.0.xml</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:689
+#| msgid ""
+#| "<option>expand_content_files</option> allows to specify files where "
+#| "<emphasis>gtk-doc abbrevations</emphasis> such as <code>#GtkWidget</code> "
+#| "are expanded (e.g. <code> expand_content_files=running.xml</code>)."
+msgid ""
+"<option>expand_content_files</option> allows to specify files where "
+"<emphasis>gtk-doc abbreviations</emphasis> such as <code>#GtkWidget</code> "
+"are expanded (e.g. <code> expand_content_files=running.xml</code>)."
+msgstr ""
+"<option>expand_content_files</option> permite especificar arquivos onde as "
+"<emphasis>abreviaturas gtk-doc</emphasis> como <code>#GtkWidget</code> são "
+"expandidas (por exemplo, <code>expand_content_files=running.xml</code>)."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:607
+msgid ""
+"The following list explains the most relevant options. Check the example "
+"<filename>Makefile.am</filename> for additional options. <_:itemizedlist-1/>"
+msgstr ""
+"A lista a seguir explica as opções mais relevantes. Verifique o exemplo "
+"<filename>Makefile.am</filename> para opções adicionais. <_:itemizedlist-1/>"
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:704
msgid "Integration with autoconf"
msgstr "Integração com autoconf"
-#. (itstool) path: sect1/para
-#: C/index.docbook:418
+#. (itstool) path: sect2/para
+#: C/index.docbook:706
msgid ""
-"Very easy! Just add one line to your <filename>configure.ac</filename> "
-"script."
+"Integration with <application>autoconf</application> is very simple and "
+"includes one required step and an additional optional (but recommended) "
+"step. The first step is to add the <function>GTK_DOC_CHECK</function> macro "
+"to your <filename>configure.ac</filename> script. This registers several "
+"configure options to enable GTK-Doc and allows you to set default arguments "
+"for <application>gtkdocize</application>."
msgstr ""
-"Muito fácil! Basta adicionar uma linha ao seu script <filename>configure.ac</"
-"filename>."
+"A integração com <application>autoconf</application> é muito simples e "
+"inclui uma etapa obrigatória e uma etapa adicional opcional (mas "
+"recomendada). O primeiro passo é adicionar a macro <function>GTK_DOC_CHECK</"
+"function> ao seu script <filename>configure.ac</filename>. Isso registra "
+"várias opções de configuração para habilitar o GTK-Doc e permite definir "
+"argumentos padrão para <application>gtkdocize</application>."
+
+#. (itstool) path: warning/simpara
+#: C/index.docbook:718
+msgid ""
+"Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented. The "
+"macro must start at the beginning of the line and should not start with "
+"whitespace."
+msgstr ""
+"Certifique-se de que a macro <code>GTK_DOC_CHECK</code> não esteja recuada. "
+"A macro deve começar no início da linha e não deve começar com espaço em "
+"branco."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:725
+msgid ""
+"The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code> to your "
+"<filename>configure.ac</filename>. This is not required but helps "
+"<application>gtkdocize</application> to automatically copy the macro "
+"definition (e.g <filename>gtk-doc.m4</filename>) which contains the "
+"<function>GTK_DOC_CHECK</function> macro to your project's macro directory. "
+"Without this, the GTK_DOC_CHECK macro might not be found and you would need "
+"to explicitly tell the <application>aclocal</application> tool where to find "
+"the macro definition file."
+msgstr ""
+"O segundo passo é adicionar o <code>AC_CONFIG_MACRO_DIR(m4)</code> ao seu "
+"<filename>configure.ac</filename>. Isso não é necessário, mas ajuda o "
+"<application>gtkdocize</application> a copiar automaticamente a definição da "
+"macro (por exemplo, <filename>gtk-doc.m4</filename>) que contém a macro "
+"<function>GTK_DOC_CHECK</function> para o diretório de macro do seu projeto. "
+"Sem isso, a macro GTK_DOC_CHECK pode não ser encontrada e você precisaria "
+"informar explicitamente à ferramenta <application>aclocal</application> onde "
+"encontrar o arquivo de definição de macro."
+
+#. (itstool) path: example/title
+#: C/index.docbook:738
+msgid "Minimal integration with autoconf"
+msgstr "Integração mínima com autoconf"
#. (itstool) path: example/programlisting
-#: C/index.docbook:424
+#: C/index.docbook:739
#, no-wrap
msgid ""
"\n"
-"# check for gtk-doc\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
msgstr ""
"\n"
-"# verifica por gtk-doc\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recomendado: defina o diretório m4\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# opcional: registre gtk-doc no configure\n"
+"GTK_DOC_CHECK([1.28])\n"
#. (itstool) path: example/title
-#: C/index.docbook:436
-msgid "Keep gtk-doc optional"
-msgstr "Mantenha o gtk-doc como opcional"
+#: C/index.docbook:754
+msgid "Integration with optional gtk-doc dependency"
+msgstr "Integração com dependência opcional do gtk-doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:437
+#: C/index.docbook:755
#, no-wrap
msgid ""
"\n"
-"# check for gtk-doc\n"
"m4_ifdef([GTK_DOC_CHECK], [\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
"],[\n"
"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n"
"])\n"
msgstr ""
"\n"
-"# verifica por gtk-doc\n"
"m4_ifdef([GTK_DOC_CHECK], [\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recomendado: defina diretório m4\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# opcional: registre gtk-doc no configure\n"
+"GTK_DOC_CHECK([1.28])\n"
"],[\n"
"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n"
"])\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:431
+#. (itstool) path: sect2/para
+#: C/index.docbook:748
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/>"
+"The above example works, but will require all developers to have gtk-doc "
+"installed. A better way is to make building the documentation optional as "
+"shown in the next example: <_:example-1/>"
msgstr ""
-"Isso vai exigir que todos os desenvolvedores tenham o gtk-doc instalado. Se "
-"não houver problema para seu projeto ter uma configuração opcional de "
-"compilação de documentação de API, você pode resolver isso como mostrado "
-"abaixo. Mantenha assim, pois o gtkdocize está procurando por "
-"<function>GTK_DOC_CHECK</function> no começo de uma linha. <_:example-1/>"
+"O exemplo acima funciona, mas exigirá que todos os desenvolvedores tenham o "
+"gtk-doc instalado. Uma maneira melhor é tornar a documentação opcional, "
+"conforme mostrado no próximo exemplo: <_:example-1/>"
-#. (itstool) path: sect1/para
-#: C/index.docbook:448
+#. (itstool) path: sect2/para
+#: C/index.docbook:768
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:"
+"The first argument is used to check for the Gtk-Doc version at configure "
+"time. The 2nd, optional argument is used by <application>gtkdocize</"
+"application>. The <symbol>GTK_DOC_CHECK</symbol> macro also adds several "
+"configure switches:"
msgstr ""
-"O primeiro argumento é usado para verificar a gtkdocversion em tempo de "
+"O primeiro argumento é usado para verificar a versão do Gtk-Doc em tempo de "
"compilação. O segundo argumento é opcional, sendo usado por "
"<application>gtkdocize</application>. A macro <symbol>GTK_DOC_CHECK</symbol> "
"também adiciona várias opções de configuração:"
#. (itstool) path: listitem/para
-#: C/index.docbook:454
+#: C/index.docbook:777
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:778
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]"
+msgstr "--enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=não]"
#. (itstool) path: listitem/para
-#: C/index.docbook:456
+#: C/index.docbook:779
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:780
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:784
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"filename>. Do contrário, uma documentação gerada previamente é instalada (o "
"que faz sentido para usuários, mas não para desenvolvedores)."
-#. (itstool) path: sect1/para
-#: C/index.docbook:469
-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 ""
-"Além disso, é recomendado que você tenha a seguinte linha dentro do seu "
-"script <filename>configure.ac</filename>. Ela permite que "
-"<application>gtkdocize</application> copie automaticamente a definição de "
-"macro para <function>GTK_DOC_CHECK</function> para o seu projeto."
-
-#. (itstool) path: example/title
-#: C/index.docbook:477
-msgid "Preparation for gtkdocize"
-msgstr "Preparação para gtkdocize"
-
-#. (itstool) path: example/programlisting
-#: C/index.docbook:478
-#, 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:483
+#. (itstool) path: sect2/para
+#: C/index.docbook:792
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>."
+"<code>autogen.sh</code>."
msgstr ""
"Após todas as alterações do <filename>configure.ac</filename> serem feitas, "
"atualize o arquivo <filename>configure</filename>. Isso pode ser feito "
-"executando novamente <code>autoreconf -i</code> ou <code>autogen.sh</code>."
+"executando novamente <code>autogen.sh</code>."
-#. (itstool) path: sect1/title
-#: C/index.docbook:491
-msgid "Integration with automake"
-msgstr "Integração com automake"
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:493
-msgid ""
-"First copy the <filename>Makefile.am</filename> from the <filename class="
-"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
-"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 ""
-"Primeiro copie o <filename>Makefile.am</filename> dos subdiretório do "
-"<filename class=\"directory\">exemplo</filename> do <ulink url=\"https://git."
-"gnome.org/browse/gtk-doc/tree/examples/Makefile.am\">gtkdoc-sources</ulink> "
-"para o diretório de documentação da API do seu projeto ( <filename class="
-"\"directory\">./docs/reference/<pacote></filename>). Uma cópia local "
-"deveria estar disponível sob, por exemplo, <filename>/usr/share/doc/gtk-doc-"
-"tools/examples/Makefile.am</filename>. Se você tiver múltiplos pacotes de "
-"documentação, repita isso para cada um."
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:504
-msgid ""
-"The next step is to edit the settings inside the <filename>Makefile.am</"
-"filename>. All the settings have a comment above that describes their "
-"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 ""
-"A próxima etapa é editar as configurações dentro do <filename>Makefile.am</"
-"filename>. Todas as configurações tem um comentário em cima que descreve seu "
-"propósito. A maioria das configurações são opções extras passadas para as "
-"respectivas ferramentas. Cada ferramenta tem uma variável na forma "
-"<option><NOME-FERRAMENTA>_OPTIONS</option>. Todas as ferramentas têm "
-"suporte a <option>--help</option> pra listar os parâmetros disponíveis."
-
-#. (itstool) path: sect1/title
-#: C/index.docbook:518
+#. (itstool) path: sect2/title
+#: C/index.docbook:800
msgid "Integration with autogen"
msgstr "Integração com autogen"
-#. (itstool) path: sect1/para
-#: C/index.docbook:520
+#. (itstool) path: sect2/para
+#: C/index.docbook:802
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."
+"the build infrastructure after the project was checked out from a version "
+"control system (such as git or svn). GTK-Doc comes with a script called "
+"<application>gtkdocize</application> which can be used to copy the necessary "
+"files needed by Gtk-Doc to the source directory."
+msgstr ""
+"A maioria dos projetos tem um script <filename>autogen.sh</filename> para "
+"configurar a infraestrutura de compilação após o checkout do projeto sistema "
+"de um controle de versão (como git ou svn). GTK-Doc vêm com um script "
+"chamado <application>gtkdocize</application> que pode ser usado para copiar "
+"os arquivos necessários pelo Gtk-Doc para o diretório fonte."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:810
+msgid "It should be run before autoreconf, autoheader, automake or autoconf."
msgstr ""
-"A maioria dos projetos têm um script <filename>autogen.sh</filename> para "
-"configurar a infraestrutura de compilação após baixar do sistema de controle "
-"de versão (como cvs/svn/git). GTK-Doc vêm com uma ferramenta chamada "
-"<application>gtkdocize</application> que pode ser usada em um script assim. "
-"O gtkdocize deveria ser executado antes de autoheader, automake ou autoconf."
+"Ele deve ser executado antes de autoreconf, autoheader, automake or autoconf."
#. (itstool) path: example/title
-#: C/index.docbook:529
+#: C/index.docbook:815
msgid "Running gtkdocize from autogen.sh"
msgstr "Executando gtkdocize no autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:530
+#: C/index.docbook:816
#, no-wrap
msgid ""
"\n"
"\n"
"gtkdocize || exit 1\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:536
+#. (itstool) path: example/title
+#: C/index.docbook:824
+msgid "Conditionally run gtkdocize from autogen.sh"
+msgstr "Executa condicionalmente gtkdocize no autogen.sh"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:825
+#, no-wrap
+msgid ""
+"\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+" echo \"No gtk-doc support found. You can't build the docs.\"\n"
+"else\n"
+" $GTKDOCIZE || exit 1\n"
+"fi\n"
+msgstr ""
+"\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+" echo \"No gtk-doc support found. You can't build the docs.\"\n"
+"else\n"
+" $GTKDOCIZE || exit 1\n"
+"fi\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:836
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>."
+"<option>--docdir</option> option)."
msgstr ""
"Ao executar <application>gtkdocize</application>, ele copia <filename>gtk-"
"doc.make</filename> para a raiz do seu projeto (ou qualquer diretório "
-"especificado pela opção <option>--docdir</option>). Ele também verifica se "
-"seu script de configuração pela chamada de <function>GTK_DOC_CHECK</"
-"function>. Esta macro pode ser usada para passar parâmetros extras para "
-"<application>gtkdocize</application>."
+"especificado pela opção <option>--docdir</option>)."
-#. (itstool) path: sect1/para
-#: C/index.docbook:545
+#. (itstool) path: sect2/para
+#: C/index.docbook:842
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 ""
-"Historicamente, GTK-Doc estava gerando arquivos modelo (template) nos quais "
-"os desenvolvedores inseriam as documentações. Isso acabou sendo não tão bom "
-"(ex.: a necessidade de serem gerados arquivos sob controle de versão). Desde "
-"o GTK-Doc 1.9 as ferramentas podem obter todas as informações dos "
-"comentários no fonte e, portanto, os arquivos modelo podem ser evitados. Nós "
-"encorajamos as pessoas a manter a documentação no código. O "
-"<application>gtkdocize</application> possui agora suporte à opção <option>--"
-"flavour no-tmpl</option> que escolhe um makefile que ignora totalmente o uso "
-"de tmpl. Além de adicionar a opção diretamente à chamada do comando, elas "
-"também podem ser adicionadas a uma variável de ambiente chamada "
-"<symbol>GTKDOCIZE_FLAGS</symbol> ou definidas como um segundo parâmetro na "
-"macro <symbol>GTK_DOC_CHECK</symbol> no script configure. Se você nunca "
-"alterou um arquivo tmpl a mão e está migrando de versões antigas do gtkdoc, "
-"por favor remova o diretório (ex.: do sistema de controle de versão)."
+"<application>gtkdocize</application> checks your <filename>configure.ac</"
+"filename> script for the <function>GTK_DOC_CHECK</function> macro. The "
+"<function>GTK_DOC_CHECK</function> macro can be used to pass extra arguments "
+"to the <application>gtkdocize</application> script. the 2nd parameter in the "
+"<function>GTK_DOC_CHECK</function> macro."
+msgstr ""
+"<application>gtkdocize</application> verifica seu script <filename>configure."
+"ac</filename> para <function>GTK_DOC_CHECK</function>. A macro "
+"<function>GTK_DOC_CHECK</function> pode ser usada para passar parâmetros "
+"extras para o script <application>gtkdocize</application>."
-#. (itstool) path: sect1/title
-#. (itstool) path: example/title
-#: C/index.docbook:562 C/index.docbook:579
-msgid "Running the doc build"
-msgstr "Executando a compilação da documentação"
+#. (itstool) path: sect2/para
+#: C/index.docbook:851
+msgid ""
+"Alternatively, additional arguments can also be passed to "
+"<application>gtkdocize</application> via the <function>GTKDOCIZE_FLAGS</"
+"function> environment variable, or by directly specifying them to "
+"<application>gtkdocize</application> in <filename>autogen.sh</filename>."
+msgstr ""
+"Alternativamente, argumentos adicionais também podem ser passados para "
+"<application>gtkdocsize</application> por meio da variável de ambiente "
+"<function>GTKDOCIZE_FLAGS</function> ou especificando-os diretamente ao "
+"<application>gtkdocsize</application> no <filename>autogen.sh</filename>."
-#. (itstool) path: sect1/para
-#: C/index.docbook:564
+#. (itstool) path: sect2/title
+#: C/index.docbook:862
+msgid "Executing GTK-Doc from the Build System"
+msgstr "Executando GTK-Doc a partir do sistema de compilação"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:864
msgid ""
"After the previous steps it's time to run the build. First we need to rerun "
"<filename>autogen.sh</filename>. If this script runs configure for you, then "
"enable-gtk-doc</option>. Do contrário, execute manualmente "
"<filename>configure</filename> com esta opção em seguida."
-#. (itstool) path: sect1/para
-#: C/index.docbook:571
-msgid ""
-"The first make run generates several additional files in the doc-"
-"directories. The important ones are: <filename><package>.types</"
-"filename>, <filename><package>-docs.xml</filename> (in the past ."
-"sgml), <filename><package>-sections.txt</filename>."
-msgstr ""
-"A primeira execução do make cria vários arquivos adicionais nos diretórios "
-"de documentação. Os importantes são: <filename><pacote>.types</"
-"filename>, <filename><pacote>-docs.xml</filename> (no passado, .sgml), "
-"<filename><pacote>-sections.txt</filename>."
-
-#. (itstool) path: example/programlisting
-#: C/index.docbook:580
-#, 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:586
-msgid ""
-"Now you can point your browser to <filename>docs/reference/<package>/"
-"index.html</filename>. Yes, it's a bit disappointing still. But hang-on, "
-"during the next chapter we tell you how to fill the pages with life."
-msgstr ""
-"Agora você pode apontar seu navegador para <filename>docs/reference/<"
-"pacote>/index.html</filename>. Sim, é um pouco desapontador. Mas aguente "
-"aí, durante o próximo capítulo nós vamos dizer como você pode preencher as "
-"páginas com vida."
-
-#. (itstool) path: sect1/title
-#: C/index.docbook:594
-msgid "Integration with version control systems"
-msgstr "Integração com sistemas de controle de versão"
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:596
-msgid ""
-"As a rule of thumb, it's the files you edit which should go under version "
-"control. For typical projects it's these files: <filename><package>."
-"types</filename>, <filename><package>-docs.xml</filename> (in the "
-"past .sgml), <filename><package>-sections.txt</filename>, "
-"<filename>Makefile.am</filename>."
-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>."
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:604
-msgid ""
-"Files in the <filename>xml/</filename> and <filename>html/</filename> "
-"directories should not go under version control. Neither should any of the "
-"<filename>.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>."
-
-#. (itstool) path: sect1/title
-#: C/index.docbook:612
-msgid "Integration with plain makefiles or other build systems"
-msgstr "Integração com makefiles simples ou outros sistemas de compilação"
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:614
-msgid ""
-"In the case one does not want to use automake and therefore <filename>gtk-"
-"doc.mak</filename> one will need to call the gtkdoc tools in the right order "
-"in own makefiles (or other build tools)."
+#. (itstool) path: sect2/para
+#: C/index.docbook:871
+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 ""
-"Neste caso, não se deseja usar o automake e, portanto, <filename>gtk-doc."
-"mak</filename>. Será necessário chamar as ferramentas do gtkdoc na ordem "
-"correta nos makefiles devidos (ou outras ferramentas de compilação)."
+"A primeira execução do make cria vários arquivos adicionais nos diretórios "
+"de documentação. Os importantes são: <filename><pacote>.types</"
+"filename>, <filename><pacote>-docs.xml</filename> (no passado, .sgml), "
+"<filename><pacote>-sections.txt</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:621
-msgid "Documentation build steps"
-msgstr "Etapas de compilação da documentação"
+#: C/index.docbook:879
+msgid "Running the doc build"
+msgstr "Executando a compilação da documentação"
#. (itstool) path: example/programlisting
-#: C/index.docbook:622
+#: C/index.docbook:880
#, 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"
+"./autogen.sh --enable-gtk-doc\n"
+"make\n"
msgstr ""
"\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"
-"// 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"
+"./autogen.sh --enable-gtk-doc\n"
+"make\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:636
+#. (itstool) path: sect2/para
+#: C/index.docbook:887
msgid ""
-"One will need to look at the <filename>Makefile.am</filename> and "
-"<filename>gtk-doc.mak</filename> to pick the extra options needed."
+"Now you can point your browser to <filename>docs/reference/<package>/"
+"index.html</filename>. With this initial setup you will only see a very "
+"simple document. The next chapter will teach you how to add API "
+"documentation to your code via special comment blocks. The Chapter "
+"afterwards introduces <link linkend=\"metafiles\">additional files</link> "
+"and shows how to edit the <link linkend=\"metafiles_master\">master "
+"template</link> to add additional chapters and sections to your "
+"documentation files."
msgstr ""
-"Será necessário olhar no <filename>Makefile.am</filename> e no <filename>gtk-"
-"doc.mak</filename> para obter as opções extras necessárias."
+"Agora você pode apontar seu navegador para <filename>docs/reference/<"
+"pacote>/index.html </filename>. Com esta configuração inicial, você verá "
+"apenas um documento muito simples. O próximo capítulo ensinará como "
+"adicionar documentação da API ao seu código por meio de blocos de "
+"comentários especiais. O capítulo seguinte depois introduz <link linkend="
+"\"metafiles\">arquivos adicionais</link> e mostra como editar o <link "
+"linkend=\"metafiles_master\">modelo mestre</link> para adicionar capítulos e "
+"seções adicionais aos seus arquivos de documentação."
#. (itstool) path: sect1/title
-#: C/index.docbook:643
+#: C/index.docbook:903
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:905
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:915
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:916
#, 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"
-"# to set the CMAKE_INSTALL_DOCDIR variable correctly).\n"
+"# Instala os documentos. (Isso presume que você está usando o módulo\n"
+"# GNUInstallDirs do CMake para definir a variável CMAKE_INSTALL_DOCDIR\n"
+"# corretamente).\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:913
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: sect1/title
+#: C/index.docbook:940
+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:942
+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 ""
+"Neste caso, não se deseja usar o automake e, portanto, <filename>gtk-doc."
+"mak</filename>. Será necessário chamar as ferramentas do gtkdoc na ordem "
+"correta nos makefiles devidos (ou outras ferramentas de compilação)."
+
+#. (itstool) path: example/title
+#: C/index.docbook:949
+msgid "Documentation build steps"
+msgstr "Etapas de compilação da documentação"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:950
+#, 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"
+"// 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"
+"// 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:964
+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 ""
+"Será necessário olhar no <filename>Makefile.am</filename> e no <filename>gtk-"
+"doc.mak</filename> para obter as opções extras necessárias."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:971
+msgid "Integration with version control systems"
+msgstr "Integração com sistemas de controle de versão"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:973
+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 ""
+"Como uma regra de ouro, são aqueles arquivos que você edita que devem 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>."
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:981
+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 devem entrar no controle de versão. Da mesma forma, não devem "
+"entrar arquivos <filename>.stamp</filename>."
+
#. (itstool) path: chapter/title
-#: C/index.docbook:681
+#: C/index.docbook:991
msgid "Documenting the code"
msgstr "Documentando o código"
#. (itstool) path: chapter/para
-#: C/index.docbook:683
+#: C/index.docbook:993
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 usa comentários do código fonte com uma sintaxe especial para "
+"GTK-Doc usa comentários do código-fonte com uma sintaxe especial para "
"documentação do código. Além disso, ele obtém informações sobre a estrutura "
"do seu projeto a partir de outros fontes. Na próxima seção, você vai "
"descobrir todas as informações sobre a sintaxe dos comentários."
-#. (itstool) path: note/title
-#: C/index.docbook:691
-msgid "Documentation placement"
-msgstr "Localização da documentação"
-
-#. (itstool) path: note/para
-#: C/index.docbook:692
-msgid ""
-"In the past most documentation had to be filled into files residing inside "
-"the <filename>tmpl</filename> directory. This has the disadvantages that the "
-"information is often not updated and also that the file tend to cause "
-"conflicts with version control systems."
-msgstr ""
-"Antigamente, a maioria das documentações tinha que ser preenchida em "
-"arquivos residentes dentro do diretório <filename>tmpl</filename>. Isso tem "
-"as desvantagens das informações frequentemente não serem atualizadas e "
-"também que o arquivo tende a causar conflitos com sistemas de controle de "
-"versão."
-
-#. (itstool) path: note/para
-#: C/index.docbook:698
-msgid ""
-"The avoid the aforementioned problems we suggest putting the documentation "
-"inside the sources. This manual will only describe this way of documenting "
-"code."
-msgstr ""
-"Para evitar os problemas mencionados a seguir nós sugerimos que a "
-"documentação seja colocada dentro das fontes. Este manual vai apenas "
-"descrever esta forma de documentar código."
-
#. (itstool) path: example/title
-#: C/index.docbook:709 C/index.docbook:735
+#: C/index.docbook:1004 C/index.docbook:1030
msgid "GTK-Doc comment block"
msgstr "Bloco de comentário do GTK-Doc"
#. (itstool) path: example/programlisting
-#: C/index.docbook:710
+#: C/index.docbook:1005
#, no-wrap
msgid ""
"\n"
msgstr ""
"\n"
"#ifndef __GTK_DOC_IGNORE__\n"
-"/* código não analisável arqui */\n"
+"/* código não analisável aqui */\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:705
+#: C/index.docbook:1000
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/>"
+"The GTK-Doc scanner can handle the majority of C headers fine. In the case "
+"of receiving warnings from the scanner that look like a special case, one "
+"can hint GTK-Doc to skip over them. <_:example-1/>"
msgstr ""
-"A varredura sabe lidar com a maioria dos cabeçalhos de C sem problemas. Caso "
-"se receba avisos (warnings) na varredura que pareça ser um caso especial, "
-"pode-se informar ao GTK-Doc para ignorá-los. <_:example-1/>"
+"O verificador do GTK-Doc sabe lidar com a maioria dos cabeçalhos de C sem "
+"problemas. Caso se receba avisos (warnings) na varredura que pareça ser um "
+"caso especial, pode-se informar ao GTK-Doc para ignorá-los. <_:example-1/>"
#. (itstool) path: note/title
-#: C/index.docbook:719
+#: C/index.docbook:1014
msgid "Limitations"
msgstr "Limitações"
#. (itstool) path: note/para
-#: C/index.docbook:720
+#: C/index.docbook:1015
msgid ""
"Note, that GTK-Doc's supports <code>#ifndef(__GTK_DOC_IGNORE__)</code> but "
"not <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations."
"combinações."
#. (itstool) path: sect1/title
-#: C/index.docbook:730
+#: C/index.docbook:1025
msgid "Documentation comments"
msgstr "Comentários de documentação"
#. (itstool) path: example/programlisting
-#: C/index.docbook:736
+#: C/index.docbook:1031
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:732
+#: C/index.docbook:1027
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 comece 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:1040
msgid ""
"The 'identifier' is one line with the name of the item the comment is "
"related to. The syntax differs a little depending on the item. (TODO add "
"relacionado. A sintaxe difere um pouco dependendo do item."
#. (itstool) path: sect1/para
-#: C/index.docbook:751
+#: C/index.docbook:1046
msgid ""
"The 'documentation' block is also different for each symbol type. Symbol "
"types that get parameters such as functions or macros have the parameter "
"espaço). Isso é útil em textos pré-formatados (listagens de código)."
#. (itstool) path: listitem/para
-#: C/index.docbook:768
+#: C/index.docbook:1063
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:1069
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."
+"O que ele faz: Fale sobre usos comuns. Coloque em relação com a outra API."
#. (itstool) path: tip/para
-#: C/index.docbook:764
+#: C/index.docbook:1059
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:1084
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."
+msgstr ""
+"Use function() para se referir às funções ou macros que levam argumentos."
#. (itstool) path: listitem/para
-#: C/index.docbook:794
+#: C/index.docbook:1089
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:1095
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:1100
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:1106
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:1111
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:1116
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:1078
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:1125
msgid ""
"If you need to use the special characters '<', '>', '()', '@', '%', or "
"'#' in your documentation without GTK-Doc changing them you can use the XML "
"uma contrabarra “\\”."
#. (itstool) path: sect1/para
-#: C/index.docbook:839
+#: C/index.docbook:1134
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:1145
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
+#: C/index.docbook:1151
msgid ""
"In older GTK-Doc releases, if you need support for additional formatting, "
"you would need to enable the usage of docbook XML tags inside doc-comments "
"symbol> dentro de <filename>Makefile.am</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:865
+#: C/index.docbook:1160
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:1161
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:905
+#: C/index.docbook:1200
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 ""
-"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>."
+"Mais exemplos de quais tags de markdown tags possui suporte podem ser "
+"encontrados na <ulink url=\"https://wiki.gnome.org/Projects/GTK%2B/"
+"DocumentationSyntax/Markdown\">Referência de sintaxe de markdown de "
+"documentação</ulink>."
#. (itstool) path: tip/para
-#: C/index.docbook:911
+#: C/index.docbook:1206
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."
+"comment those symbols too. This helps other developers to understand your "
+"code. Therefore we recommend to comment these using normal comments (without "
+"the 2nd '*' in the first line). If later the function needs to be made "
+"public, all one needs to do is to add another '*' in the comment block and "
+"insert the symbol name at the right place inside the sections file."
msgstr ""
"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."
+"obstante, é bom comentar estes símbolos também. Isso ajuda outros "
+"desenvolvedores 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."
#. (itstool) path: sect1/title
-#: C/index.docbook:925
+#: C/index.docbook:1221
msgid "Documenting sections"
msgstr "Documentando seções"
#. (itstool) path: sect1/para
-#: C/index.docbook:927
+#: C/index.docbook:1223
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:1231
msgid "Section comment block"
msgstr "Bloco de comentário de sessão"
#. (itstool) path: example/programlisting
-#: C/index.docbook:936
+#: C/index.docbook:1232
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:955
+#: C/index.docbook:1251
msgid "SECTION:<name>"
msgstr "SECTION:<nome>"
#. (itstool) path: listitem/para
-#: C/index.docbook:957
+#: C/index.docbook:1253
msgid ""
"The name links the section documentation to the respective part in the "
"<filename><package>-sections.txt</filename> file. The name given here "
"txt</filename>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:966
+#: C/index.docbook:1262
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:968
+#: C/index.docbook:1264
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:1271
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:977
+#: C/index.docbook:1273
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:1280
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:986
+#: C/index.docbook:1282
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:1290
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:996
+#: C/index.docbook:1292
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:1298
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1009
+#: C/index.docbook:1305
msgid ""
"Stable - The intention of a Stable interface is to enable arbitrary third "
"parties to develop applications to these interfaces, release them, and have "
"release). Even at a major release, incompatible changes are expected to be "
"rare, and to have strong justifications."
msgstr ""
-"Estável - A intenção de uma interface estável é permitir terceiros "
+"Estável – A intenção de uma interface estável é permitir terceiros "
"arbitrários desenvolverem aplicativos para essas interfaces, lançá-los e ter "
"a confiança de que eles vão funcionar em todos os lançamentos menores do "
"produto (após aquele no qual a interface foi introduzida e naquele mesmo "
"alterações incompatíveis sejam raras e que tenham fortes justificativas."
#. (itstool) path: listitem/para
-#: C/index.docbook:1021
+#: C/index.docbook:1317
msgid ""
"Unstable - Unstable interfaces are experimental or transitional. They are "
"typically used to give outside developers early access to new or rapidly "
"more general solution is anticipated. No claims are made about either source "
"or binary compatibility from one minor release to the next."
msgstr ""
-"Instável - Interfaces instáveis são experimentais ou transicionais. Elas são "
+"Instável – Interfaces instáveis são experimentais ou transicionais. Elas são "
"normalmente usadas para dar a desenvolvedores externos um acesso prévio a "
"nova tecnologia ou em rápida alteração, ou para fornecer uma solução "
"interina para um problema que uma solução mais genérica foi antecipada. "
"fontes de uma versão menor para a próxima."
#. (itstool) path: listitem/para
-#: C/index.docbook:1033
+#: C/index.docbook:1329
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 ""
-"Privado - Uma interface que pode ser usada dentro da própria pilha do GNOME, "
+"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."
#. (itstool) path: listitem/para
-#: C/index.docbook:1042
+#: C/index.docbook:1338
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 ""
-"Interna - Uma interface que é interna a um módulo e não requer documentação "
+"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”."
#. (itstool) path: listitem/para
-#: C/index.docbook:1004
+#: C/index.docbook:1300
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:1350
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1056
+#: C/index.docbook:1352
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:1361
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1067
+#: C/index.docbook:1363
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:1374
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:1383
msgid "Documenting symbols"
msgstr "Documentando símbolos"
#. (itstool) path: sect1/para
-#: C/index.docbook:1089
+#: C/index.docbook:1385
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:1393 C/index.docbook:1459
msgid "General tags"
msgstr "Tags gerais"
#. (itstool) path: sect2/para
-#: C/index.docbook:1099
+#: C/index.docbook:1395
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:1400
msgid "Versioning Tags"
msgstr "Tags de versionamento"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1105
+#: C/index.docbook:1401
msgid "Since:"
msgstr "Since:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1107
+#: C/index.docbook:1403
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:1408
msgid "Deprecated:"
msgstr "Deprecated:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1114
+#: C/index.docbook:1410
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
+#: C/index.docbook:1418
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:1424
msgid ""
"The default stability level for all documentation elements can be set by "
"passing the <option>--default-stability</option> argument to "
msgstr ""
"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."
+"<application>gtkdoc-mkdb</application> com um dos valores abaixo."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1134
+#: C/index.docbook:1430
msgid "Stability Tags"
msgstr "Tags de estabilidade"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1135
+#: C/index.docbook:1431
msgid "Stability: Stable"
msgstr "Stability: Stable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1137
+#: C/index.docbook:1433
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:1440
msgid "Stability: Unstable"
msgstr "Stability: Unstable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1146
+#: C/index.docbook:1442
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:1448
msgid "Stability: Private"
msgstr "Stability: Private"
#. (itstool) path: listitem/para
-#: C/index.docbook:1154
+#: C/index.docbook:1450
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:1460
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1184 C/index.docbook:1194
+#: C/index.docbook:1480 C/index.docbook:1490
msgid "Annotations"
msgstr "Anotações"
#. (itstool) path: sect2/para
-#: C/index.docbook:1186
+#: C/index.docbook:1482
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"\">no wiki</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1195
+#: C/index.docbook:1491
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1216 C/index.docbook:1245
+#: C/index.docbook:1512 C/index.docbook:1541
msgid "Function comment block"
msgstr "Bloco de comentário de função"
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1518
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:1524
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:1529
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:1514 C/index.docbook:1600
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:1536
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 “_” "
-"são privadas. Elas são tratadas como funções estáticas."
+"são privados. Eles são tratados como funções estáticas."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1246
+#: C/index.docbook:1542
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1267
+#: C/index.docbook:1563
msgid "Function tags"
msgstr "Tags de função"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1268 C/index.docbook:1475
+#: C/index.docbook:1564 C/index.docbook:1771
msgid "Returns:"
msgstr "Returns:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1270
+#: C/index.docbook:1566
msgid "Paragraph describing the returned result."
msgstr "Parágrafo descrevendo o resultado retornado."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1275
+#: C/index.docbook:1571
msgid "@...:"
msgstr "@...:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1277
+#: C/index.docbook:1573
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:1583 C/index.docbook:1585
msgid "Property comment block"
msgstr "Bloco de comentário de propriedade"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1290
+#: C/index.docbook:1586
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1302 C/index.docbook:1321
+#: C/index.docbook:1598 C/index.docbook:1617
msgid "Signal comment block"
msgstr "Bloco de comentário de sinal"
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1604
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:1610
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:1618
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1339 C/index.docbook:1340
+#: C/index.docbook:1635 C/index.docbook:1636
msgid "Struct comment block"
msgstr "Bloco de comentário de struct"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1341
+#: C/index.docbook:1637
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1652
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:1658
msgid ""
"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" "
"it will be considered private automatically and doesn't need to be mentioned "
"no bloco de comentário."
#. (itstool) path: sect2/para
-#: C/index.docbook:1368
+#: C/index.docbook:1664
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:1676 C/index.docbook:1677
msgid "Enum comment block"
msgstr "Bloco de comentário de enum"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1382
+#: C/index.docbook:1678
#, no-wrap
msgid ""
"\n"
"} Alguma coisa;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1399
+#: C/index.docbook:1695
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:1410
+#: C/index.docbook:1706
msgid "Inline program documentation"
msgstr "Documentação de programa em-linha"
#. (itstool) path: sect1/para
-#: C/index.docbook:1411
+#: C/index.docbook:1707
msgid ""
"You can document programs and their commandline interface using inline "
"documentation."
"documentação em-linha."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1417
+#: C/index.docbook:1713
msgid "Tags"
msgstr "Tags"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1419
+#: C/index.docbook:1715
msgid "PROGRAM"
msgstr "PROGRAM"
#. (itstool) path: listitem/para
-#: C/index.docbook:1422
+#: C/index.docbook:1718
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:1429
+#: C/index.docbook:1725
msgid "@short_description:"
msgstr "@short_description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1431
+#: C/index.docbook:1727
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:1438
+#: C/index.docbook:1734
msgid "@synopsis:"
msgstr "@synopsis:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1440
+#: C/index.docbook:1736
msgid ""
"Defines the arguments, or list of arguments that the program can take. "
"(Optional)"
"(Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1448
+#: C/index.docbook:1744
msgid "@see_also:"
msgstr "@see_also:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1450
+#: C/index.docbook:1746
msgid "See Also manual page section. (Optional)"
-msgstr "A seção “Veja Também” (See Also) de páginas de manual. (Opcional)"
+msgstr "A seção “See Also” (Veja Também) de páginas de manual. (Opcional)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1457
+#: C/index.docbook:1753
msgid "@arg:"
msgstr "@arg:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1459
+#: C/index.docbook:1755
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:1466
+#: C/index.docbook:1762
msgid "Description:"
msgstr "Description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1468
+#: C/index.docbook:1764
msgid "A longer description of the program."
msgstr "Um descrição mais longa do programa."
#. (itstool) path: listitem/para
-#: C/index.docbook:1477
-msgid "Specificy what value(s) the program returns. (Optional)"
-msgstr "Especifique quais valor(es) o programa retorna. (Opcional)"
+#: C/index.docbook:1773
+#| msgid "Specificy what value(s) the program returns. (Optional)"
+msgid "Specify what value(s) the program returns. (Optional)"
+msgstr "Especifique qual(is) valor(es) o programa retorna. (Opcional)"
#. (itstool) path: sect2/title
-#: C/index.docbook:1486
+#: C/index.docbook:1782
msgid "Example of program documentation."
msgstr "Exemplo de documentação de programa."
#. (itstool) path: example/title
-#: C/index.docbook:1487
+#: C/index.docbook:1783
msgid "Program documentation block"
msgstr "Bloco de documentação de programa"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1488
+#: C/index.docbook:1784
#, no-wrap
msgid ""
"\n"
"}\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1514
+#: C/index.docbook:1810
msgid "Useful DocBook tags"
msgstr "Tags úteis do DocBook"
#. (itstool) path: sect1/para
-#: C/index.docbook:1516
+#: C/index.docbook:1812
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:1525
+#: C/index.docbook:1821
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Tabela de hashes</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1521
+#: C/index.docbook:1817
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ágina a qual você "
-"deseja vincular. Para a maioria das páginas isto é atualmente a parte "
+"O \"linked\" é a identificação 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:1538
+#: C/index.docbook:1834
#, no-wrap
msgid ""
"\n"
"<function>...</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1535
+#: C/index.docbook:1831
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:1547
+#: C/index.docbook:1843
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1558
+#: C/index.docbook:1854
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1544
+#: C/index.docbook:1840
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:1577
+#: C/index.docbook:1873
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1574
+#: C/index.docbook:1870
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "Para incluir listas com marcadores: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1597
+#: C/index.docbook:1893
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1594
+#: C/index.docbook:1890
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:1610
+#: C/index.docbook:1906
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1607
+#: C/index.docbook:1903
msgid "To refer to a type: <_:informalexample-1/>"
msgstr "Para se referir a um tipo: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1619
+#: C/index.docbook:1915
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1616
+#: C/index.docbook:1912
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:1628
+#: C/index.docbook:1924
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1625
+#: C/index.docbook:1921
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:1637
+#: C/index.docbook:1933
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1634
+#: C/index.docbook:1930
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 "
msgstr ""
"Para se referir a um nome de classe, nós possivelmente poderíamos usar: <_:"
"informalexample-1/> mas você provavelmente vai estar usando #GtkWidget em "
-"vez disso (para criar automaticamente um link para a página do GtkWidget - "
+"vez disso (para criar automaticamente um link para a página do GtkWidget – "
"veja <link linkend=\"documenting_syntax\">as abreviações</link>)."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1648
+#: C/index.docbook:1944
#, no-wrap
msgid ""
"\n"
"<emphasis>Isso é importante</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1645
+#: C/index.docbook:1941
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "Para enfatizar um texto: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1657
+#: C/index.docbook:1953
#, no-wrap
msgid ""
"\n"
"<filename>/home/usuario/documentos</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1654
+#: C/index.docbook:1950
msgid "For filenames use: <_:informalexample-1/>"
msgstr "Para nome de arquivos use: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1666
+#: C/index.docbook:1962
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1663
+#: C/index.docbook:1959
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "Para se referir a chaves use: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1676
+#: C/index.docbook:1972
msgid "Filling the extra files"
msgstr "Preenchendo os arquivos extras"
#. (itstool) path: chapter/para
-#: C/index.docbook:1678
+#: C/index.docbook:1974
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>."
msgstr ""
"Há alguns poucos arquivos extras, que precisam ser mantidos junto com os "
-"comentários inseridos no código fonte: <filename><pacote>.types</"
+"comentários inseridos no código-fonte: <filename><pacote>.types</"
"filename>, <filename><pacote>-docs.xml</filename> (no passado, .sgml), "
"<filename><pacote>-sections.txt</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1687
+#: C/index.docbook:1983
msgid "Editing the types file"
msgstr "Editando o arquivo de tipos"
#. (itstool) path: sect1/para
-#: C/index.docbook:1689
+#: C/index.docbook:1985
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:1698
-msgid "Example types file snippet"
-msgstr "Trecho de exemplo de arquivo de tipos"
+#: C/index.docbook:1994
+msgid "Example <package>.types file"
+msgstr "Exemplo de arquivo <pacote>.types"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1699
+#: C/index.docbook:1995
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1710
+#: C/index.docbook:2006
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"deveria distribuir o arquivo de tipos nem tê-lo sob um controle de versão."
#. (itstool) path: sect1/title
-#: C/index.docbook:1719
+#: C/index.docbook:2015
msgid "Editing the master document"
msgstr "Editando o documento mestre"
#. (itstool) path: sect1/para
-#: C/index.docbook:1721
+#: C/index.docbook:2017
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:1728
+#: C/index.docbook:2024
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:1738
+#: C/index.docbook:2034
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:1747
+#: C/index.docbook:2043
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:1754
+#: C/index.docbook:2050
msgid "Master document header"
msgstr "Cabeçalho do documento mestre"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1755
+#: C/index.docbook:2051
#, no-wrap
msgid ""
"\n"
" <title>[Insira o título aqui]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1771
+#: C/index.docbook:2067
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:1777
+#: C/index.docbook:2073
msgid "Optional part in the master document"
msgstr "Parte opcional do documento mestre"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1778
+#: C/index.docbook:2074
#, no-wrap
msgid ""
"\n"
" -->\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1786
+#: C/index.docbook:2082
msgid ""
"Finally you need to add new section whenever you introduce one. The <link "
"linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> tool will remind "
"incluídos na documentação."
#. (itstool) path: example/title
-#: C/index.docbook:1794 C/index.docbook:1829
+#: C/index.docbook:2090 C/index.docbook:2125
msgid "Including generated sections"
msgstr "Incluindo seções geradas"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1795
+#: C/index.docbook:2091
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1807
+#: C/index.docbook:2103
msgid "Editing the section file"
msgstr "Editando o arquivo de seção"
#. (itstool) path: sect1/para
-#: C/index.docbook:1809
+#: C/index.docbook:2105
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:1815
+#: C/index.docbook:2111
msgid ""
"The section file is a plain text file with tags delimiting sections. Blank "
"lines are ignored and lines starting with a '#' are treated as comment lines."
"tratadas como linhas de comentários."
#. (itstool) path: note/para
-#: C/index.docbook:1822
+#: C/index.docbook:2118
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:1830
+#: C/index.docbook:2126
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1847
+#: C/index.docbook:2143
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"para minúsculos)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1859
+#: C/index.docbook:2155
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:1866
+#: C/index.docbook:2162
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"padrão ou pública depende se há entradas públicas (variáveis, vmethods)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1885
+#: C/index.docbook:2181
msgid ""
"You can also use <INCLUDE> ... </INCLUDE> to specify the "
"#include files which are shown in the synopsis sections. It contains a comma-"
"aplicar àquela seção."
#. (itstool) path: chapter/title
-#: C/index.docbook:1899
+#: C/index.docbook:2195
msgid "Controlling the result"
msgstr "Controlando o resultado"
#. (itstool) path: chapter/para
-#: C/index.docbook:1901
+#: C/index.docbook:2197
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:1910
+#: C/index.docbook:2206
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:1919
+#: C/index.docbook:2215
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:1926
+#: C/index.docbook:2222
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:1934
+#: C/index.docbook:2230
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:1941
+#: C/index.docbook:2237
msgid ""
"One can also look at the files produced by the source code scanner: "
"<filename><package>-decl-list.txt</filename> and <filename><"
"declarations from the headers. If a symbol is missing one could check if "
"this file contains it."
msgstr ""
-"Também pode-se buscar nos arquivos produzidos pela varredura do código "
-"aberto: <filename><pacote>-decl-list.txt</filename> e <filename><"
+"Também pode-se buscar nos arquivos produzidos pela varredura do código-"
+"fonte: <filename><pacote>-decl-list.txt</filename> e <filename><"
"pacote>-decl.txt</filename>. O primeiro pode ser comparado com o arquivo "
"de seção, se ele for mantido manualmente. O segundo lista todas as "
"declarações de cabeçalhos. Se um símbolo está faltando, pode-se verificar se "
"este arquivo o contém."
#. (itstool) path: chapter/para
-#: C/index.docbook:1950
+#: C/index.docbook:2246
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:1965
+#: C/index.docbook:2261
msgid "Modernizing the documentation"
msgstr "Modernizando a documentação"
#. (itstool) path: chapter/para
-#: C/index.docbook:1967
+#: C/index.docbook:2263
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:1973
+#: C/index.docbook:2269
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1975
+#: C/index.docbook:2271
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:1980
+#: C/index.docbook:2276
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:1991
+#: C/index.docbook:2287
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"ao <filename>configure.ac</filename> e está resolvido."
#. (itstool) path: sect1/title
-#: C/index.docbook:2003
+#: C/index.docbook:2299
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:2005
+#: C/index.docbook:2301
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:2016
+#: C/index.docbook:2312
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:2022
+#: C/index.docbook:2318
msgid "Enable gtkdoc-check"
msgstr "Habilitar gtkdoc-check"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2023
+#: C/index.docbook:2319
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2018
+#: C/index.docbook:2314
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:2036
+#: C/index.docbook:2332
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:2038
+#: C/index.docbook:2334
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:2048
+#: C/index.docbook:2344
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:2058
+#: C/index.docbook:2355
msgid "Use pre-generated entities"
msgstr "Usando entradas geradas previamente"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2059
+#: C/index.docbook:2356
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2050
+#: C/index.docbook:2346
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/>"
+"the entity file is included in the master template and how the entities are "
+"used. The entities can also be used in all generated files, GTK-Doc will use "
+"the same xml header in generated xml files. <_:example-1/>"
msgstr ""
"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-1/>"
+"entidade é incluído no modelo mestre 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-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:2084
+#: C/index.docbook:2381
msgid "Documenting other interfaces"
msgstr "Documentando outras interfaces"
#. (itstool) path: chapter/para
-#: C/index.docbook:2086
+#: C/index.docbook:2383
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:2093
+#: C/index.docbook:2390
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:2095
+#: C/index.docbook:2392
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 "
msgstr ""
"Já que também é possível gerar páginas man para um refentry do docbook, soa "
"como uma boa ideia usá-lo para este propósito. Desta forma, a interface é "
-"parte da referência e é possível obter a página man de graça."
+"parte da referência e é possível obter a página man livremente."
#. (itstool) path: sect2/title
-#: C/index.docbook:2102
+#: C/index.docbook:2399
msgid "Document the tool"
msgstr "Documentar a ferramenta"
#. (itstool) path: sect2/para
-#: C/index.docbook:2104
+#: C/index.docbook:2401
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:2114
+#: C/index.docbook:2411
msgid "Adding the extra configure check"
msgstr "Adicionando a verificação extra ao configure"
#. (itstool) path: example/title
-#: C/index.docbook:2117 C/index.docbook:2135
+#: C/index.docbook:2414 C/index.docbook:2432
msgid "Extra configure checks"
msgstr "Verificações extra no configure"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2118
+#: C/index.docbook:2415
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2132
+#: C/index.docbook:2429
msgid "Adding the extra makefile rules"
msgstr "Adicionando as regras extras ao makefile"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2136
+#: C/index.docbook:2433
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2158
+#: C/index.docbook:2455
msgid "DBus interfaces"
msgstr "Interfaces DBus"
#. (itstool) path: sect1/para
-#: C/index.docbook:2160
+#: C/index.docbook:2457
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:2169
+#: C/index.docbook:2466
msgid "Frequently asked questions"
msgstr "Perguntas frequentes"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2173
+#: C/index.docbook:2470
msgid "Question"
msgstr "Questão"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2174
+#: C/index.docbook:2471
msgid "Answer"
msgstr "Resposta"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2176
+#: C/index.docbook:2473
msgid "No class hierarchy."
msgstr "Sem hierarquia de classe."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2177
+#: C/index.docbook:2474
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:2183
+#: C/index.docbook:2480
msgid "Still no class hierarchy."
msgstr "Ainda sem hierarquia."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2184
+#: C/index.docbook:2481
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:2190
+#: C/index.docbook:2487
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:2191
+#: C/index.docbook:2488
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:2198
+#: C/index.docbook:2495
msgid "No symbol index."
msgstr "Nenhum símbolo de índice."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2199
+#: C/index.docbook:2496
msgid ""
"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
"index that xi:includes the generated index?"
"“xi:inclui” o índice gerado?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2205
+#: C/index.docbook:2502
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:2206
+#: C/index.docbook:2503
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:2212
+#: C/index.docbook:2509
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:2213
+#: C/index.docbook:2510
msgid ""
"Is the new page xi:included from <filename><package>-docs.{xml,sgml}</"
"filename>."
"filename>?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2219
+#: C/index.docbook:2516
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:2220
+#: C/index.docbook:2517
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:2228
+#: C/index.docbook:2525
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:2229
+#: C/index.docbook:2526
msgid ""
"If the type is listed in <filename><package>.hierarchy</filename> but "
"not in <filename>xml/tree_index.sgml</filename> then double check that the "
"listada ou incidentalmente marcada como privada, ela não será mostrada."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2238
+#: C/index.docbook:2535
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:2239
+#: C/index.docbook:2536
msgid ""
"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
"from <filename><package>-docs.{xml,sgml}</filename>."
"incluído” de <filename><pacote>-docs.{xml,sgml}</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2247
+#: C/index.docbook:2544
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"
+msgstr "Parâmetro descrito no bloco de comentário do código-fonte não existe"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2248
+#: C/index.docbook:2545
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
"fonte."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2253
+#: C/index.docbook:2550
msgid "multiple \"IDs\" for constraint linkend: XYZ"
msgstr "múltiplos “IDs” para restrições do fim do link XYZ"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2254
+#: C/index.docbook:2551
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"sections.txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2257
+#: C/index.docbook:2554
msgid ""
"Element typename in namespace '' encountered in para, but no template "
"matches."
"correspondeu."
#. (itstool) path: chapter/title
-#: C/index.docbook:2264
+#: C/index.docbook:2561
msgid "Tools related to gtk-doc"
msgstr "Ferramentas relacionadas ao gtk-doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2266
+#: C/index.docbook:2563
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
- um plug-in de integração com <ulink url=\"http://trac-hacks."
+"GtkDocPlugin
– um plug-in de integração com <ulink url=\"http://trac-hacks."
"org/wiki/GtkDocPlugin\">Trac GTK-Doc</ulink>, que adiciona documentos de API "
"a um site trac e integra com a pesquisa do trac."
#. (itstool) path: chapter/para
-#: C/index.docbook:2271
+#: C/index.docbook:2568
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 - uma ferramenta (parte do gtk-doc) para verificar APIs "
+"Gtkdoc-depscan – uma ferramenta (parte do gtk-doc) para verificar APIs "
"usadas, a partir de suas tags, para determinar a versão mínima necessária."
#. (itstool) path: appendixinfo/releaseinfo
#. (itstool) path: sect1/title
#: C/index.docbook:31 C/fdl-appendix.xml:31
msgid "0. PREAMBLE"
-msgstr "0. INTRODUÇÃO"
+msgstr "0. PREÂMBULO"
#. (itstool) path: sect1/para
#: C/index.docbook:32
"for the author and publisher a way to get credit for their work, while not "
"being considered responsible for modifications made by others."
msgstr ""
-"O propósito desta Licença é fazer um manual, livro-texto, ou outro documento "
-"escrito <quote>livre</quote> em seu sentido de liberdade: para garantir a "
-"todos a liberdade efetiva de copiá-lo e redistribui-lo, com ou sem "
-"modificações, tanto comercialmente como não comercialmente. Em segundo "
-"lugar, esta Licença preserva ao autor e ao editor uma forma de obter crédito "
-"pelo seu trabalho, enquanto não é considerado responsável por modificações "
-"feitas por outros."
+"O objetivo desta Licença é tornar um manual, livro didático ou outro "
+"documento funcional e útil “livre” no sentido de liberdade: assegurar a "
+"todos a liberdade efetiva de copiá-lo e redistribuí-lo, com ou sem "
+"modificação do mesmo, comercialmente ou não. Em segundo lugar, esta Licença "
+"preserva para o autor e o editor uma maneira de obter crédito por seu "
+"trabalho, sem ser considerado responsável por modificações feitas por outros."
#. (itstool) path: sect1/para
#: C/index.docbook:43
"It complements the GNU General Public License, which is a copyleft license "
"designed for free software."
msgstr ""
-"Esta licença é um tipo de <quote>copyleft</quote>, que significa que "
-"trabalhos derivados do documento precisam ser, por sua vez, livres no mesmo "
-"sentido. Ela complementa a Licença Pública Geral GNU (GNU General Public "
-"License), que é uma licença copyleft projetada para softwares livres."
+"Esta licença é um tipo de “copyleft”, o que significa que trabalhos "
+"derivados do documento devem ser livres no mesmo sentido. Ela complementa a "
+"Licença Pública Geral GNU (GNU General Public License), que é uma licença "
+"com copyleft projetada para software livre."
#. (itstool) path: sect1/para
#: C/index.docbook:50 C/fdl-appendix.xml:50
"printed book. We recommend this License principally for works whose purpose "
"is instruction or reference."
msgstr ""
-"Nós projetamos esta Licença a fim de ser utilizada em manuais de software "
-"livre, já que softwares livres precisam de documentações livres: um programa "
-"livre deveria vir com manuais que ofereçam as mesmas liberdades que o "
-"software proporciona. Mas esta Licença não é limitada a manuais de software; "
-"ela pode ser usada para qualquer trabalho de texto, independente do assunto "
-"ou se é publicado como um livro impresso. Nós recomendamos esta Licença "
-"principalmente para trabalhos cujo propósito seja instrução ou referência."
+"Criamos esta Licença para usá-la para manuais para software livre, porque "
+"software livre precisa de documentação livre: um programa livre deve ser "
+"fornecido com manuais que proporcionam as mesmas liberdades que o software. "
+"Mas esta Licença não está limitada aos manuais de software; pode ser usada "
+"para qualquer trabalho textual, independentemente do assunto ou dele ser "
+"publicado como um livro impresso. Recomendamos esta Licença principalmente "
+"para trabalhos cujo propósito seja instrução ou referência."
#. (itstool) path: sect1/title
#: C/index.docbook:62 C/fdl-appendix.xml:62
"manual or work. Any member of the public is a licensee, and is addressed as "
"<quote>you</quote>."
msgstr ""
-"Esta Licença se aplica a qualquer manual ou outro trabalho que contenha um "
-"aviso colocado pelo detentor dos direitos autorais dizendo que o documento "
-"pode ser distribuído sob os termos desta. O <quote>Documento</quote>, "
-"abaixo, refere-se a qualquer manual ou trabalho. Qualquer membro do público "
-"é um licenciado, e será referenciado como <quote>você</quote>."
+"Esta Licença aplica-se a qualquer manual ou outro trabalho, em qualquer "
+"meio, que contenha um aviso colocado pelo detentor dos direitos autorais "
+"dizendo que pode ser distribuído nos termos desta Licença. Tal aviso concede "
+"uma licença mundial, sem royalties, de duração ilimitada, para usar esse "
+"trabalho nas condições aqui estabelecidas. O “Documento”, a seguir, refere-"
+"se a qualquer manual ou trabalho. Qualquer membro do público é um licenciado "
+"e é referido como “você”. Você aceita a licença se você copiar, modificar ou "
+"distribuir o trabalho de forma a exigir permissão de acordo com a lei de "
+"direitos autorais."
#. (itstool) path: sect1/para
#: C/index.docbook:72
"the Document or a portion of it, either copied verbatim, or with "
"modifications and/or translated into another language."
msgstr ""
-"Uma <quote>Versão Modificada</quote> do Documento significa qualquer "
-"trabalho contendo o Documento ou uma porção deste, seja uma cópia literal ou "
-"com modificações e/ou traduzido em outro idioma."
+"Uma “Versão Modificada” do Documento significa qualquer trabalho contendo o "
+"Documento ou uma porção deste, seja uma cópia literal ou com modificações e/"
+"ou traduzido em outro idioma."
#. (itstool) path: sect1/para
#: C/index.docbook:79
"legal, commercial, philosophical, ethical or political position regarding "
"them."
msgstr ""
-"Uma <quote>Seção Secundária</quote> é um apêndice com nome ou uma seção "
-"inicial do <link linkend=\"fdl-document\">Documento</link> que trata "
-"exclusivamente da relação dos editores ou autores do Documento com seu "
-"assunto geral (ou temas relacionados) e não contém nada que possa estar "
-"diretamente dentro do assunto geral. (Por exemplo, se o Documento é em parte "
-"um livro-texto de matemática, uma Seção Secundária não pode explicar nada de "
-"matemática). Tal relação pode ser uma questão de conexão histórica com o "
-"assunto ou com temas relacionados, ou tratar de questões legais, comerciais, "
-"filosóficas, éticas ou políticas com relação a eles."
+"A “Seção Secundária” é um apêndice nomeado ou uma seção anterior do "
+"Documento que trata exclusivamente do relacionamento dos editores ou autores "
+"do <link linkend=\"fdl-document\">Documento</link> com o assunto geral do "
+"documento (ou assuntos relacionados) e não contém nada que possa estar "
+"diretamente dentro desse assunto geral. (Assim, se o Documento for, em "
+"parte, um livro de texto de matemática, uma Seção Secundária pode não "
+"explicar qualquer matemática.) O relacionamento poderia ser uma questão de "
+"conexão histórica com o assunto ou com assuntos relacionados, ou de posição "
+"legal, comercial, filosófica, ética ou política em relação a eles."
#. (itstool) path: sect1/para
#: C/index.docbook:94
"those of Invariant Sections, in the notice that says that the <link linkend="
"\"fdl-document\">Document</link> is released under this License."
msgstr ""
-"As <quote>Seções Invariantes</quote> são certas <link linkend=\"fdl-secondary"
-"\">Seções Secundárias</link> cujos títulos são designados como sendo de "
-"Seções Invariantes na nota que afirma que o <link linkend=\"fdl-document"
-"\">Documento</link> é publicado sob esta Licença."
+"As “Seções Invariantes” são certas <link linkend=\"fdl-secondary\">Seções "
+"Secundárias</link> cujos títulos são designados, como sendo daquelas de "
+"Seções Invariantes, no aviso que diz que o <link linkend=\"fdl-document"
+"\">Documento</link> é liberado sob esta Licença."
#. (itstool) path: sect1/para
#: C/index.docbook:103
"that the <link linkend=\"fdl-document\">Document</link> is released under "
"this License."
msgstr ""
-"Os <quote>Textos de Capa</quote> são certas passagens de texto curtas que "
-"são listadas, como Textos de Capa Frontal ou Texto de Contra Capa, na nota "
-"que afirma que o <link linkend=\"fdl-document\">Documento</link> é publicado "
-"sob esta Licença."
+"Os “Textos de Capa” são certas passagens de texto que são listadas como "
+"Textos de Capa Frontal ou Textos de Contracapa, no aviso que afirma que o "
+"<link linkend=\"fdl-document\">Documento</link> foi publicado sob esta "
+"Licença."
#. (itstool) path: sect1/para
#: C/index.docbook:111
"modification by readers is not Transparent. A copy that is not "
"<quote>Transparent</quote> is called <quote>Opaque</quote>."
msgstr ""
-"Uma cópia <quote>Transparente</quote> do <link linkend=\"fdl-document"
-"\">Documento</link> significa uma cópia legível por máquina, representada em "
-"um formato cuja especificação esteja disponível ao público geral e que cujo "
-"conteúdo possa ser visualizado e editado de forma clara e direta por "
-"editores de texto genéricos ou programas genéricos de desenho (para imagens "
-"compostas de pixels) ou para alguns dos editores de desenho amplamente "
-"disponíveis (para desenhos) e que seja apropriado para inclusão em "
-"formatadores de texto ou para a tradução automática em uma variedade de "
-"formatos apropriados de entrada em formatadores de texto. Uma cópia feita em "
-"outro formato de arquivo Transparente cuja marcação, ou ausência desta, "
-"tenha sido manipulada para impedir ou desencorajar modificação subsequente "
-"pelos leitores não é Transparente. Uma cópia que não é <quote>Transparente</"
-"quote> é chamada <quote>Opaca</quote>."
+"Uma cópia “Transparente” do <link linkend=\"fdl-document\"> Documento</link> "
+"significa uma cópia legível por máquina, representada em um formato cuja "
+"especificação está disponível para o público em geral, cujo conteúdo possa "
+"ser visto e editado diretamente com editores de texto genéricos ou (para "
+"imagens compostas de pixels) programas gráficos genéricos ou (para desenhos) "
+"algum editor de desenho amplamente disponível, e isso seja adequado para "
+"entrada para formatadores de texto ou para tradução automática para uma "
+"variedade de formatos adequados para entrada de formatadores de texto. Uma "
+"cópia feita em um formato de arquivo Transparente cuja marcação tenha sido "
+"projetada para frustrar ou desencorajar a modificação subsequente pelos "
+"leitores não é Transparente. Uma cópia que não é “Transparente” é chamada de "
+"“Opaca”."
#. (itstool) path: sect1/para
#: C/index.docbook:128 C/fdl-appendix.xml:128
"available, and the machine-generated HTML produced by some word processors "
"for output purposes only."
msgstr ""
-"Exemplos de formatos apropriados para cópias Transparentes incluem ASCII "
-"puro sem marcação, formato de entrada Texinfo, formato de entrada LaTex, "
-"SGML ou XML usando um DTD publicamente disponível, e HTML simples em "
-"conformidade padrão projetado para modificação por humanos. Formatos Opacos "
-"incluem PostScript, PDF, formatos proprietários que podem ser lidos ou "
-"editados somente por processadores de texto proprietários, SGML ou XML cujos "
-"DTD e/ou ferramenta de processamento não estão largamente disponibilizados, "
-"e o HTML gerado por máquina produzido por algum processador de texto com "
-"propósito apenas de saída."
+"Exemplos de formatos adequados para cópias Transparentes incluem ASCII "
+"simples sem marcação, formato de entrada Texinfo, formato de entrada LaTeX, "
+"SGML ou XML usando DTD publicamente disponível e HTML simples, conforme "
+"padrão, projetados para modificação humana. Os formatos Opacos incluem "
+"PostScript, PDF, formatos proprietários que podem ser lidos e editados "
+"apenas por processadores de texto proprietários, SGML ou XML para os quais o "
+"DTD e/ou ferramentas de processamento não estão geralmente disponíveis e o "
+"HTML gerado por máquina produzido por alguns processadores de texto para "
+"apenas para fins de saída."
#. (itstool) path: sect1/para
#: C/index.docbook:141
"means the text near the most prominent appearance of the work's title, "
"preceding the beginning of the body of the text."
msgstr ""
-"A <quote>Página de Título</quote> significa, para um livro impresso, a "
-"própria página do título, além das páginas subsequentes necessárias para "
-"conter, de forma legível, o material que esta Licença requer que apareça na "
-"página do título. Para trabalhos em formatos que não possuem qualquer página "
-"de título semelhante, <quote>Página de Título</quote> significa o texto "
-"próximo à ocorrência mais proeminente do título do trabalho, precedendo o "
-"início do corpo do texto."
+"A “Página de Título” significa, para um livro impresso, a própria página do "
+"título, além das páginas subsequentes necessárias para conter, de forma "
+"legível, o material que esta Licença requer que apareça na página do título. "
+"Para trabalhos em formatos que não possuem qualquer página de título "
+"semelhante, “Página de Título” significa o texto próximo à ocorrência mais "
+"proeminente do título do trabalho, precedendo o início do corpo do texto."
#. (itstool) path: sect1/title
#: C/index.docbook:153 C/fdl-appendix.xml:153
msgid "2. VERBATIM COPYING"
-msgstr "2. CÓPIA ESCRITA"
+msgstr "2. CÓPIA LITERAL"
#. (itstool) path: sect1/para
#: C/index.docbook:154
msgstr ""
"Você pode copiar e distribuir o <link linkend=\"fdl-document\">Documento</"
"link> em qualquer meio, seja este de forma comercial ou não, desde que esta "
-"licença, as notas de direitos autorais (copyright), e a nota de licença "
-"afirmando que esta Licença se aplica ao Documento sejam reproduzidas em "
-"todas as cópias, e que você não inclua outras condições, quaisquer que "
-"sejam, às condições desta Licença. Você não pode usar de medidas técnicas "
-"para obstruir ou controlar a leitura ou cópia futura das cópias que você "
-"fizer ou distribuir. Contudo, você pode aceitar compensação em troca das "
-"cópias. Se você distribuir um número suficientemente grande de cópias, você "
-"deve também respeitar as condições descritas na <link linkend=\"fdl-"
-"section3\">seção 3</link>."
+"Licença, os avisos de direitos autorais e o aviso de licença afirmando que "
+"esta Licença se aplica ao Documento sejam reproduzidos em todas as cópias, e "
+"que você adicione nenhuma outra condição, qualquer que seja, às condições "
+"desta Licença. Você não pode usar de medidas técnicas para obstruir ou "
+"controlar a leitura ou cópia futura das cópias que você fizer ou distribuir. "
+"Contudo, você pode aceitar compensação em troca das cópias. Se você "
+"distribuir um número suficientemente grande de cópias, você deve também "
+"respeitar as condições descritas na <link linkend=\"fdl-section3\">seção 3</"
+"link>."
#. (itstool) path: sect1/para
#: C/index.docbook:169 C/fdl-appendix.xml:169
"You may also lend copies, under the same conditions stated above, and you "
"may publicly display copies."
msgstr ""
-"Você também pode emprestar cópias, sob as mesmas condições relacionadas "
-"acima, e você pode publicamente exibir cópias."
+"Você também pode emprestar cópias, nas mesmas condições acima mencionadas, e "
+"você pode publicar cópias."
#. (itstool) path: sect1/title
#: C/index.docbook:176 C/fdl-appendix.xml:176
"verbatim copying in other respects."
msgstr ""
"Se você publicar cópias impressas do <link linkend=\"fdl-document"
-"\">Documento</link>, em número maior que 100, e a nota de licença do "
-"Documento exigir <link linkend=\"fdl-cover-texts\">Textos de Capa</link>, "
-"você deve encadernar as cópias em capas que carreguem, de forma clara e "
-"legível, todos estes Textos de Capa: Textos de Capa Frontal na capa frontal "
-"e Textos de Contracapa na contracapa. Ambas as capas devem também "
-"identificar, de forma clara e legível, você como o editor das cópias. A capa "
-"frontal deve apresentar o título completo com todas as palavras deste "
-"igualmente proeminentes e visíveis. Além disso, você pode adicionar outro "
-"material nas capas. As cópias com mudanças limitadas às capas, desde que "
-"preservem o título do <link linkend=\"fdl-document\">Documento</link> e "
-"satisfaçam estas condições podem ser tratadas como cópias literais em outros "
-"aspectos."
+"\">Documento</link> em número maior que 100, e o aviso de licença do "
+"Documento exigir os <link linkend=\"fdl-cover-texts\">Textos de Capa</link>, "
+"você deve incluir as cópias nas capas que carregam, de forma clara e "
+"legível, todas essas Textos de Capa: Textos de Capa Frontal na capa frontal "
+"e Textos de Contracapa na contracapa. Ambas as capas também devem identificá-"
+"lo claramente e legivelmente como o editor dessas cópias. A capa frontal "
+"deve apresentar o título completo com todas as palavras do título igualmente "
+"proeminentes e visíveis. Você também pode adicionar outros materiais nas "
+"capas. Copiar com as alterações limitadas às capas, desde que preservem o "
+"título do <link linkend=\"fdl-document\">Documento</link> e satisfaçam estas "
+"condições, podem ser tratadas como cópias literais em outros aspectos."
#. (itstool) path: sect1/para
#: C/index.docbook:195 C/fdl-appendix.xml:195
"you should put the first ones listed (as many as fit reasonably) on the "
"actual cover, and continue the rest onto adjacent pages."
msgstr ""
-"Se os textos necessários a qualquer uma das capas forem muito volumosos para "
-"serem incluídos de forma legível, você deve colocar os primeiros textos "
-"listados (quantos couberem razoavelmente) na própria capa, e continuar o "
+"Se os textos necessários para qualquer uma das coberturas forem demasiado "
+"volumosos para se ajustar de forma legível, você deve colocar os primeiros "
+"listados (tanto quanto encaixar razoavelmente) na capa real e continuar o "
"resto em páginas adjacentes."
#. (itstool) path: sect1/para
msgstr ""
"Se você publicar ou distribuir cópias <link linkend=\"fdl-transparent"
"\">Opacas</link> do <link linkend=\"fdl-document\">Documento</link> em "
-"número maior que 100, você deve incluir uma cópia <link linkend=\"fdl-"
-"transparent\">Transparente</link> legível por máquina juntamente com cada "
-"cópia Opaca, ou dizer em (ou juntamente com) cada cópia Opaca, um endereço "
-"de rede a partir do qual o público geral de usuários possam acessar e obter "
-"de forma anônima e sob nenhum custo, usando protocolos de rede públicos "
-"padrão, uma cópia Transparente completa do Documento, livre de materiais "
-"adicionados. Se você decidir pela segunda opção, você deve seguir passos com "
-"certa prudência ao começar a distribuir as cópias Opacas em quantidade, a "
-"fim de garantir que esta cópia transparente permanecerá acessível no local "
-"indicado por pelo menos um ano após a última vez que você distribuir uma "
-"cópia Opaca (diretamente ou através de seus agentes ou distribuidores) desta "
-"edição ao público."
+"número superior a 100, você deve incluir uma cópia <link linkend=\"fdl-"
+"transparent\">Transparente</link> legível por máquina junto com cada cópia "
+"Opaca ou estabelecer em ou com cada cópia Opaca uma localização de rede de "
+"computador publicamente acessível contendo uma cópia transparente completa "
+"do documento, sem material adicional, a partir da qual o público geral "
+"usuário de rede tem acesso para baixar anonimamente sem custo, usando "
+"protocolos de rede padrão público. Se você usar a última opção, você deve "
+"tomar medidas razoavelmente prudentes, quando você começar a distribuir "
+"cópias Opacas em quantidade, para garantir que esta cópia Transparente "
+"permanecerá acessível no local indicado até pelo menos um ano após a última "
+"vez que você distribuir uma cópia Opaca (diretamente ou através de seus "
+"agentes ou varejistas) dessa edição para o público."
#. (itstool) path: sect1/para
#: C/index.docbook:222
"large number of copies, to give them a chance to provide you with an updated "
"version of the Document."
msgstr ""
-"É solicitado, mas não exigido, que você contate os autores do <link linkend="
-"\"fdl-document\">Documento</link> muito antes de redistribuir qualquer "
-"grande número de cópias, para dar a eles uma chance de lhe fornecer uma "
-"versão atualizada do Documento."
+"É solicitado, mas não é necessário, que você contate os autores do <link "
+"linkend=\"fdl-document\">Documento</link> muito antes de redistribuir "
+"qualquer grande número de cópias, para dar a eles uma chance de lhe fornecer "
+"uma versão atualizada do Documento."
#. (itstool) path: sect1/title
#: C/index.docbook:231 C/fdl-appendix.xml:231
"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."
+"devem, havendo 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 lhe conceder permissão."
#. (itstool) path: formalpara/title
#: C/index.docbook:264 C/fdl-appendix.xml:264
"\"fdl-document\">Document</link> (all of its principal authors, if it has "
"less than five)."
msgstr ""
-"Listar na <link linkend=\"fdl-title-page\">Página de Título</link> como "
+"Listar na <link linkend=\"fdl-title-page\">Página de Título</link>, como "
"autores, uma ou mais pessoas ou entidades responsáveis pela autoria das "
"modificações na <link linkend=\"fdl-modified\">Versão Modificada</link>, "
-"juntamente com pelo menos cinco autores principais do <link linkend=\"fdl-"
-"document\">Documento</link> (todos seus autores principais, se houver menos "
-"que cinco)."
+"juntamente com pelo menos cinco dos autores principais do <link linkend="
+"\"fdl-document\">Documento</link> (todos os seus principais autores, se "
+"tiverem menos de cinco)."
#. (itstool) path: formalpara/title
#: C/index.docbook:279 C/fdl-appendix.xml:279
"the publisher of the <link linkend=\"fdl-modified\">Modified Version</link>, "
"as the publisher."
msgstr ""
-"Declarar na <link linkend=\"fdl-title-page\">Página de Título</link> o nome "
+"Indicar na <link linkend=\"fdl-title-page\">Página de Título</link> o nome "
"do editor da <link linkend=\"fdl-modified\">Versão Modificada</link>, como "
-"seu editor."
+"editor."
#. (itstool) path: formalpara/title
#: C/index.docbook:291 C/fdl-appendix.xml:291
"Preserve all the copyright notices of the <link linkend=\"fdl-document"
"\">Document</link>."
msgstr ""
-"Preservar todas as notas de direitos autorais (copyright) do <link linkend="
-"\"fdl-document\">Documento</link>."
+"Preservar todas as avisos de direitos autorais do <link linkend=\"fdl-"
+"document\">Documento</link>."
#. (itstool) path: formalpara/title
#: C/index.docbook:301 C/fdl-appendix.xml:301
"Add an appropriate copyright notice for your modifications adjacent to the "
"other copyright notices."
msgstr ""
-"Adicionar uma nota apropriada de direitos autorais para suas modificações, "
-"adjacente às outras notas de direitos autorais."
+"Adicionar um aviso de direitos autorais apropriado para suas modificações "
+"adjacentes aos outros avisos de direitos autorais."
#. (itstool) path: formalpara/title
#: C/index.docbook:311 C/fdl-appendix.xml:311
"Version</link> under the terms of this License, in the form shown in the "
"Addendum below."
msgstr ""
-"Incluir, imediatamente após as notas de direitos autorais, uma nota de "
-"licença concedendo permissão pública para o uso da <link linkend=\"fdl-"
-"modified\">Versão Modificada</link> sob os termos desta Licença, na forma "
-"mostrada no Adendo abaixo."
+"Incluir, imediatamente após os avisos de direitos autorais, um aviso de "
+"licença que dê permissão ao público para usar a <link linkend=\"fdl-modified"
+"\">Versão Modificada</link> sob os termos desta Licença, na forma mostrada "
+"no Adendo abaixo."
#. (itstool) path: formalpara/title
#: C/index.docbook:324 C/fdl-appendix.xml:324
"cover-texts\">Cover Texts</link> given in the <link linkend=\"fdl-document"
"\">Document's</link> license notice."
msgstr ""
-"Preservar na referida nota de licença a lista completa de <link linkend="
-"\"fdl-invariant\">Seções Invariantes</link> e <link linkend=\"fdl-cover-texts"
-"\">Textos de Capa</link> obrigatórios, dados na nota de licença do <link "
+"Preservar nesse aviso de licença as listas completas de <link linkend=\"fdl-"
+"invariant\">Seções Invariantes</link> e os <link linkend=\"fdl-cover-texts"
+"\">Textos de Capa</link> necessários fornecidos no aviso de licença do <link "
"linkend=\"fdl-document\">Documento</link>."
#. (itstool) path: formalpara/title
#. (itstool) path: formalpara/para
#: C/index.docbook:338 C/fdl-appendix.xml:338
msgid "Include an unaltered copy of this License."
-msgstr "Inclua uma cópia inalterada desta Licença."
+msgstr "Incluir uma cópia inalterada desta Licença."
#. (itstool) path: formalpara/title
#: C/index.docbook:346 C/fdl-appendix.xml:346
"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 ""
-"Preservar a seção intitulada <quote>Histórico</quote>, preservar seu título, "
-"e adicionar a esta um item declarando ao menos o título, o ano, novos "
-"autores, e o editor da <link linkend=\"fdl-modified\">Versão Modificada</"
-"link> conforme incluído na <link linkend=\"fdl-title-page\">Página de "
-"Título</link>. Se nenhuma seção intitulada <quote>Histórico</quote> estiver "
-"presente no <link linkend=\"fdl-document\">Documento</link>, crie uma "
-"informando o título, o ano, os autores e o editor do Documento como "
-"evidenciado na Página de Título, em seguida adicione um item descrevendo a "
-"Versão Modificada como mencionado na sentença anterior."
+"Preservar a seção intitulada “Histórico”, e seu título, e adicionar a ele um "
+"item que indique pelo menos o título, o ano, os novos autores e o editor da "
+"<link linkend=\"fdl-modified\">Versão Modificada</link> conforme indicado na "
+"<link linkend=\"fdl-title-page\">Página de Título</link>. Se não houver uma "
+"seção intitulada “Histórico” no <link linkend=\"fdl-document\">Documento</"
+"link>, crie um que declare o título, o ano, os autores e o editor do "
+"Documento conforme indicado em sua Página de Título e, em seguida, adicione "
+"um item descrevendo a Versão Modificada, como indicado na frase anterior."
#. (itstool) path: formalpara/title
#: C/index.docbook:365 C/fdl-appendix.xml:365
"the Document itself, or if the original publisher of the version it refers "
"to gives permission."
msgstr ""
-"Preservar o endereço de rede, se existir algum, informado pelo <link linkend="
+"Preservar a localização de rede, se for o caso, fornecida no <link linkend="
"\"fdl-document\">Documento</link> para acesso público a uma cópia <link "
-"linkend=\"fdl-transparent\">Transparente</link> deste e, da mesma maneira, "
-"os endereços de rede dados no Documento para versões anteriores nas quais "
-"este se baseia. Estes podem ser colocados na seção <quote>Histórico</quote>. "
-"Você pode omitir um endereço de rede para um trabalho que foi publicado pelo "
+"linkend=\"fdl-transparent\">Transparente</link> do Documento, e também as "
+"localizações de rede fornecidas no Documento para versões anteriores nas "
+"quais ele foi baseado. Estas podem ser colocadas na seção “Histórico”. Você "
+"pode omitir uma localização de rede para um trabalho que foi publicado pelo "
"menos quatro anos antes do Documento em si, ou se o editor original da "
-"versão à qual o endereço se refere der permissão."
+"versão a que se refere der permissão."
#. (itstool) path: formalpara/title
#: C/index.docbook:383 C/fdl-appendix.xml:383
"the section all the substance and tone of each of the contributor "
"acknowledgements and/or dedications given therein."
msgstr ""
-"Preservar o título da seção para qualquer seção intitulada "
-"<quote>Agradecimentos</quote> ou <quote>Dedicatórias</quote> e preservar "
-"dentro da seção toda a substância e tom de cada um dos agradecimentos e/ou "
-"dedicatórias lá mencionados."
+"Em qualquer seção intitulada “Agradecimentos” ou “Dedicatórias”, preservar o "
+"título da seção, e preservar na seção toda a substância e tom de cada um dos "
+"agradecimentos e/ou das dedicatórias dados nela."
#. (itstool) path: formalpara/title
#: C/index.docbook:396 C/fdl-appendix.xml:396
"considered part of the section titles."
msgstr ""
"Preservar todas as <link linkend=\"fdl-invariant\">Seções Invariantes</link> "
-"do <link linkend=\"fdl-document\">Documento</link>, sem alterações em seus "
-"textos e títulos. Números de seção ou o equivalente não são considerados "
-"parte dos títulos das seções."
+"do <link linkend=\"fdl-document\">Documento</link>, inalteradas em seus "
+"textos e em seus títulos. Os números de seção ou o equivalente não são "
+"considerados parte dos títulos das seções."
#. (itstool) path: formalpara/title
#: C/index.docbook:409 C/fdl-appendix.xml:409
"not be included in the <link linkend=\"fdl-modified\">Modified Version</"
"link>."
msgstr ""
-"Apagar qualquer seção intitulada <quote>Apoio</quote>. Tal seção não deve "
-"ser incluída na <link linkend=\"fdl-modified\">Versão Modificada</link>."
+"Excluir qualquer seção intitulada “Endossos”. Essa seção pode não estar "
+"incluída na <link linkend=\"fdl-modified\">Versão Modificada</link>."
#. (itstool) path: formalpara/title
#: C/index.docbook:421 C/fdl-appendix.xml:421
"conflict in title with any <link linkend=\"fdl-invariant\">Invariant "
"Section</link>."
msgstr ""
-"Não renomear o título de qualquer seção existente como <quote>Apoio</quote> "
-"ou que resulte em conflito com o título de qualquer <link linkend=\"fdl-"
-"invariant\">Seção Invariante</link>."
+"Não mudar o título de qualquer seção existente para “Endossos” ou para "
+"conflitar em título com qualquer <link linkend=\"fdl-invariant\">Seção "
+"Invariante</link>."
#. (itstool) path: sect1/para
#: C/index.docbook:432
"license notice. These titles must be distinct from any other section titles."
msgstr ""
"Se a <link linkend=\"fdl-modified\">Versão Modificada</link> incluir novas "
-"seções iniciais ou apêndices que sejam qualificados como <link linkend=\"fdl-"
-"secondary\">Seções Secundárias</link>, e não contiver material copiado do "
-"Documento, você pode, a seu critério, tornar algumas dessas ou todas essas "
-"seções em invariantes. Para fazer isso, adicione seus títulos à lista de "
-"<link linkend=\"fdl-invariant\">Seções Invariantes</link> na nota de licença "
-"da Versão Modificada. Estes títulos devem ser distintos de quaisquer outros "
-"títulos de seções."
+"seções ou apêndices de primeira linha que se qualifiquem como <link linkend="
+"\"fdl-secondary\">Seções Secundárias</link> e não contenham material copiado "
+"do Documento, você pode, a sua escolha, designar algumas ou todas essas "
+"seções como invariantes. Para fazer isso, adicione seus títulos à lista de "
+"<link linkend=\"fdl-invariant\">Seções Invariantes</link> no aviso de "
+"licença da Versão Modificada. Esses títulos devem ser distintos de qualquer "
+"outro título de seção."
#. (itstool) path: sect1/para
#: C/index.docbook:444
"peer review or that the text has been approved by an organization as the "
"authoritative definition of a standard."
msgstr ""
-"Você pode incluir uma seção intitulada <quote>Apoio</quote>, desde que esta "
-"contenha apenas apoios recebidos limitados a sua <link linkend=\"fdl-modified"
-"\">Versão Modificada</link> por várias fontes -- por exemplo, notas do "
-"revisor ou de que o texto foi aprovado por uma organização como a definição "
-"oficial de um padrão."
+"Você pode incluir uma seção intitulada “Endossos”, desde que contenha nada "
+"além do endosso da sua <link linkend=\"fdl-modified\">Versão Modificada</"
+"link> por várias terceiros – por exemplo, declarações de revisão por pares "
+"ou de que o texto foi aprovado por uma organização como a definição oficial "
+"de um padrão."
#. (itstool) path: sect1/para
#: C/index.docbook:453
"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 ""
-"Você pode adicionar uma passagem de até cinco palavras como <link linkend="
-"\"fdl-cover-texts\">Texto de Capa Frontal</link>, e uma passagem de até 25 "
-"palavras como <link linkend=\"fdl-cover-texts\">Texto de Contracapa</link>, "
-"ao fim da lista de <link linkend=\"fdl-cover-texts\">Textos de Capa</link> "
-"na <link linkend=\"fdl-modified\">Versão Modificada</link>. Somente uma "
-"passagem de Texto de Capa Frontal e uma de Texto de Contracapa podem ser "
-"adicionados por (ou através de arranjos feitos por) uma entidade qualquer. "
-"Caso o <link linkend=\"fdl-document\">Documento</link> já incluir um texto "
-"de capa para a mesma capa, previamente incluído por você ou pelo arranjo "
-"feito pela mesma entidade em cujo nome você está agindo, você não poderá "
-"adicionar outro; mas você poderá substituir o antigo, com a permissão "
-"explícita do editor anterior, que o incluiu."
+"Você pode adicionar uma passagem de até cinco palavras como um <link linkend="
+"\"fdl-cover-texts\">Texto de Capa Frontal</link> e uma passagem de até 25 "
+"palavras como um <link linkend=\"fdl-cover-texts\">Texto de Contracapa</"
+"link>, até o final da lista de <link linkend=\"fdl-cover-texts\">Textos de "
+"Capa</link> na <link linkend=\"fdl-modified\">Versão Modificada</link>. "
+"Apenas uma passagem de Texto de Capa Frontal e um de Texto de Contracapa "
+"pode ser adicionada por (ou por meio de acordos feitos por) qualquer "
+"entidade. Se o <link linkend=\"fdl-document\">Documento</link> já incluir um "
+"texto de capa para a mesma capa, previamente adicionado por você ou por "
+"acordo feito pela mesma entidade em que você está agindo em nome de, você "
+"não pode adicionar outro; mas você pode substituir o antigo, mediante "
+"permissão explícita do editor anterior que adicionou o antigo."
#. (itstool) path: sect1/para
#: C/index.docbook:470
"\"fdl-modified\">Modified Version </link>."
msgstr ""
"O(s) autor(es) e editor(es) do <link linkend=\"fdl-document\">Documento</"
-"link>, por esta Licença, não concedem permissão para que seus nomes sejam "
-"usados a fins de publicidade, para defesa ou para apoio implícito de "
-"qualquer <link linkend=\"fdl-modified\">Versão Modificada</link>."
+"link> não concedem por esta Licença permissão para usar seus nomes para "
+"publicidade ou afirmar ou implicar o endosso de qualquer <link linkend=\"fdl-"
+"modified\">Versão Modificada</link>."
#. (itstool) path: sect1/title
#: C/index.docbook:480 C/fdl-appendix.xml:480
"its license notice."
msgstr ""
"Você pode combinar o <link linkend=\"fdl-document\">Documento</link> com "
-"outros documentos publicados sob esta Licença, sob os termos definidos na "
-"<link linkend=\"fdl-section4\">seção 4</link> acima para versões "
-"modificadas, desde que você inclua na combinação todas as <link linkend="
-"\"fdl-invariant\">Seções Invariantes</link> de todos os documentos "
-"originais, sem modificações, e as liste como Seções Invariantes de seu "
-"trabalho combinado, na sua nota de licença."
+"outros documentos publicados sob esta Licença, nos termos definidos na <link "
+"linkend=\"fdl-section4\">seção 4</link> acima para versões modificadas, "
+"desde que você inclua na combinação de todas as <link linkend=\"fdl-invariant"
+"\">Seções Invariantes</link> de todos os documentos originais, não "
+"modificados, e liste todos eles como Seções Invariantes do seu trabalho "
+"combinado em seu aviso de licença."
#. (itstool) path: sect1/para
#: C/index.docbook:492
"várias <link linkend=\"fdl-invariant\">Seções Invariantes</link> idênticas "
"podem ser substituídas por uma única cópia. Se existirem várias Seções "
"Invariantes de mesmo nome, porém com conteúdos diferentes, você deve tornar "
-"o título de cada uma destas seções único, adicionando ao fim destes, entre "
+"o título de cada uma destas seções único, adicionando ao fim deste, entre "
"parênteses, o nome do autor ou, se conhecido, o editor original desta seção, "
"ou ainda um número único. Faça o mesmo ajuste nos títulos de seção na lista "
-"de Seções Invariantes na nota de licença do trabalho combinado."
+"de Seções Invariantes no aviso de licença do trabalho combinado."
#. (itstool) path: sect1/para
#: C/index.docbook:505
"<quote>Dedications</quote>. You must delete all sections entitled "
"<quote>Endorsements.</quote>"
msgstr ""
-"Na combinação, você deve combinar quaisquer seções intituladas "
-"<quote>Histórico</quote> nos vários documentos originais, formando uma seção "
-"intitulada <quote>Histórico</quote>; do mesmo modo, combine quaisquer seções "
-"intituladas <quote>Agradecimentos</quote>, e quaisquer seções intituladas "
-"<quote>Dedicatórias</quote>. Você deve apagar todas as seções intituladas "
-"<quote>Apoio</quote>."
+"Na combinação, você deve combinar todas as seções intituladas “Histórico” "
+"nos vários documentos originais, formando uma seção intitulada “Histórico”; "
+"da mesma forma, combinar todas as seções intituladas “Agradecimentos” e "
+"quaisquer seções intituladas “Dedicatórias”. Você deve excluir todas as "
+"seções intituladas “Endossos”."
#. (itstool) path: sect1/title
#: C/index.docbook:516 C/fdl-appendix.xml:516
"into the extracted document, and follow this License in all other respects "
"regarding verbatim copying of that document."
msgstr ""
-"Você pode extrair um único documento desta coleção, e distribuí-lo "
+"Você pode extrair um único documento de tal 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."
+"Licença no documento extraído e siga esta Licença em todos os outros "
+"aspectos referentes à cópia literal desse documento."
#. (itstool) path: sect1/title
#: C/index.docbook:537 C/fdl-appendix.xml:537
"Otherwise they must appear on covers around the whole aggregate."
msgstr ""
"Uma compilação do <link linkend=\"fdl-document\">Documento</link> ou seus "
-"derivados com outros documentos ou trabalhos separados e independentes, "
-"dentro de ou sob um volume de um meio de armazenamento ou distribuição, não "
-"conta como um todo para uma <link linkend=\"fdl-modified\">Versão "
-"Modificada</link> do Documento, contanto que nenhum direito autoral de "
-"compilação seja reivindicado para esta compilação. Tal compilação configura "
-"um <quote>agregado</quote> e esta Licença não se aplica aos outros trabalhos "
-"contidos na compilação do Documento, levando em conta serem compilados, caso "
-"eles mesmos não forem trabalhos derivados do Documento. Se o requisito de "
-"<link linkend=\"fdl-cover-texts\">Texto da Capa</link> da <link linkend="
-"\"fdl-section3\">seção 3</link> é aplicável a estas cópias do Documento, e "
-"ainda se o Documento é menor do que um quarto do agregado inteiro, os Textos "
-"de Capa do Documento podem ser inseridos nas capas que envolvem somente o "
-"Documento no agregado. Caso contrário, eles devem aparecer em capas em volta "
-"do agregado como um todo."
+"derivados com outros documentos ou trabalhos separados e independentes, em "
+"ou sobre um volume de um meio de armazenamento ou distribuição, não como um "
+"todo conta como uma <link linkend=\"fdl-modified\">Versão Modificada</link> "
+"do Documento, desde que nenhuma compilação de direitos autorais seja "
+"reivindicada para a compilação. Tal compilação é chamada de "
+"“agregado” (aggregate), e esta Licença não se aplica aos outros trabalhos "
+"autônomos assim compilados com o Documento, por conta de serem assim "
+"compilados, se eles não forem eles próprios trabalhos derivados do "
+"Documento. Se o requisito do <link linkend=\"fdl-cover-texts\">Texto da "
+"Capa</link> da <link linkend=\"fdl-section3\">seção 3</link> for aplicável a "
+"essas cópias do Documento, então, se o Documento for inferior a um quarto do "
+"agregado inteiro, os Textos de Capa do Documento poderão ser colocados em "
+"capas que envolvam apenas o Documento no agregado. Caso contrário, eles "
+"devem aparecer nas capas envolvem todo o agregado."
#. (itstool) path: sect1/title
#: C/index.docbook:561 C/fdl-appendix.xml:561
"original English version of this License, the original English version will "
"prevail."
msgstr ""
-"Uma tradução é considerada como sendo um tipo de modificação, desta forma "
-"você pode distribuir traduções do <link linkend=\"fdl-document\">Documento</"
-"link> sob os termos da <link linkend=\"fdl-section4\">seção 4</link>. A "
-"substituição das <link linkend=\"fdl-invariant\">Seções Invariantes</link> "
-"por traduções requer permissão especial dos detentores dos direitos "
-"autorais, embora você possa incluir traduções de algumas ou todas as Seções "
-"Invariantes juntamente às versões originais destas. Você pode incluir uma "
-"tradução desta Licença, desde que você também inclua a versão original em "
-"Inglês desta Licença. Em caso de discordância entre a tradução e a versão "
-"original desta Licença ou nota de licença, a versão original em inglês "
-"prevalecerá."
+"A tradução é considerada um tipo de modificação, então você pode distribuir "
+"as traduções do <link linkend=\"fdl-document\">Documento</link> nos termos "
+"da <link linkend=\"fdl-section4\">seção 4</link>. A substituição das <link "
+"linkend=\"fdl-invariant\">Seções Invariantes</link> com traduções requer "
+"permissão especial de seus detentores de direitos autorais, mas você pode "
+"incluir traduções de algumas ou todas as Seções Invariantes além das versões "
+"originais destas Seções Invariantes. Você pode incluir uma tradução desta "
+"Licença, desde que você também inclua a versão original em inglês desta "
+"Licença. Em caso de desacordo entre a tradução e a versão original desta "
+"Licença, a versão original prevalecerá."
#. (itstool) path: sect1/title
#: C/index.docbook:580 C/fdl-appendix.xml:580
msgid "9. TERMINATION"
-msgstr "9. TÉRMINO"
+msgstr "9. TERMINAÇÃO"
#. (itstool) path: sect1/para
#: C/index.docbook:581
"under this License will not have their licenses terminated so long as such "
"parties remain in full compliance."
msgstr ""
-"Você não pode copiar, modificar, sublicenciar, ou distribuir o <link linkend="
-"\"fdl-document\">Documento</link> com exceção do que foi expressamente "
-"previsto sob esta Licença. Qualquer outra tentativa de cópia, modificação, "
-"sublicenciamento ou distribuição do Documento é nula, e implicará na "
-"rescisão automática de seus direitos sob esta Licença. Contudo, as partes "
-"que receberam as cópias, ou direitos, de você sob esta Licença não terão "
-"suas licenças rescindidas enquanto tais partes permanecerem em total acordo "
-"com a Licença."
+"Você não pode copiar, modificar, sublicenciar ou distribuir o <link linkend="
+"\"fdl-document\">Documento</link>, exceto conforme expressamente previsto "
+"nesta Licença. Qualquer tentativa de copiar, modificar, sublicenciar ou "
+"distribuir o Documento é anulada e terminará automaticamente seus direitos "
+"sob esta Licença. No entanto, as partes que receberam cópias ou direitos de "
+"você sob esta Licença não terão suas licenças terminadas, desde que tais "
+"partes permaneçam em plena conformidade."
#. (itstool) path: sect1/title
#: C/index.docbook:594 C/fdl-appendix.xml:594
"gnu.org/copyleft\">http://www.gnu.org/copyleft/</ulink>."
msgstr ""
"A <ulink type=\"http\" url=\"http://www.gnu.org/fsf/fsf.html\">Free Software "
+"Foundation</ulink> pode publicar novas e revisadas versões da Licença de "
+"Documentação Livre GNU de vez em quando. Essas novas versões serão "
+"semelhantes em espírito à versão atual, mas podem diferir em detalhes para "
+"resolver novos problemas ou preocupações. Veja <ulink type=\"http\" url="
+"\"http://www.gnu.org/copyleft\">http://www.gnu.org/copyleft/</ulink>.A "
+"<ulink type=\"http\" url=\"http://www.gnu.org/fsf/fsf.html\">Free Software "
"Foundation</ulink> pode publicar novas versões, revisadas, da Licença de "
"Documentação Livre GNU de tempos em tempos. Tais versões posteriores terão "
"ideologia similar à presente versão, embora possam diferir em detalhes a fim "
"specify a version number of this License, you may choose any version ever "
"published (not as a draft) by the Free Software Foundation."
msgstr ""
-"É dado, a cada versão da Licença, um número de versão distinto. Se o <link "
-"linkend=\"fdl-document\">Documento</link> especificar que um número de "
-"versão em específico desta Licença <quote>ou qualquer versão posterior</"
-"quote> se aplica a ele, você tem a opção de seguir os termos e condições "
-"tanto da versão especificada quanto de qualquer versão posterior que tenha "
-"sido publicada (não como rascunho) pela Free Software Foundation. Se o "
-"documento não especificar um número de versão desta Licença, você pode "
-"escolher qualquer versão já publicada (não como rascunho) pela Free Software "
-"Foundation."
+"Cada versão da Licença recebe um número de versão distinto. Se o <link "
+"linkend=\"fdl-document\">Documento</link> especifica que uma versão numerada "
+"específica desta Licença “ou qualquer versão posterior” aplica-se a ele, "
+"você tem a opção de seguir os termos e condições daquela versão especificada "
+"ou de qualquer versão posterior que tenha sido publicada (não como um "
+"rascunho) pela Free Software Foundation. Se o Documento não especificar um "
+"número de versão desta Licença, você pode escolher qualquer versão publicada "
+"(não como um rascunho) pela Free Software Foundation."
#. (itstool) path: sect1/title
#: C/index.docbook:621 C/fdl-appendix.xml:621
"just after the title page:"
msgstr ""
"Para usar esta Licença em um documento que você escreveu, inclua uma cópia "
-"desta no documento e adicione as seguintes notas de direitos autorais e "
-"licença logo após a página de título:"
+"da Licença no documento e coloque os seguintes avisos de direitos autorais e "
+"de licenças logo após a página de título:"
#. (itstool) path: blockquote/para
#: C/index.docbook:629 C/fdl-appendix.xml:629
"Free Documentation License</quote>."
msgstr ""
"Permissão concedida para copiar, distribuir e/ou modificar este documento "
-"sob os termos da Licença de Documentação Livre GNU (GNU Free Documentation "
-"License), Versão 1.1 ou qualquer versão mais recente publicada pela Free "
-"Software Foundation; com as <link linkend=\"fdl-invariant\">Seções "
-"Invariantes</link>, sendo LISTADO SEUS TÍTULOS, com os <link linkend=\"fdl-"
-"cover-texts\">Textos de Capa Frontal</link> sendo LISTADOS, e com os <link "
-"linkend=\"fdl-cover-texts\">Textos de Contracapa</link> sendo LISTADOS. Uma "
-"cópia da licença está inclusa na seção entitulada <quote>Licença de "
-"Documentação Livre GNU (GNU Free Documentation License)</quote>."
+"sob os termos da Licença de Documentação Livre GNU, Versão 1.1 ou qualquer "
+"versão mais recente publicada pela Free Software Foundation; com as <link "
+"linkend=\"fdl-invariant\">Seções Invariantes</link> sendo LISTE SEUS "
+"TÍTULOS, com os <link linkend=\"fdl-cover-texts\">Textos de Capa Frontal</"
+"link> sendo LISTA e os <link linkend=\"fdl-cover-texts\">Textos de "
+"Contracapa</link> sendo LISTA. Uma cópia da licença está incluída na seção "
+"intitulada \"Licença de Documentação Livre GNU\" (GNU Free Documentation "
+"License)."
#. (itstool) path: sect1/para
#: C/index.docbook:647
"<quote>Front-Cover Texts being LIST</quote>; likewise for <link linkend="
"\"fdl-cover-texts\">Back-Cover Texts</link>."
msgstr ""
-"Se você não tiver qualquer <link linkend=\"fdl-invariant\">Seção Invariante</"
-"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>."
+"Se você não tiver <link linkend=\"fdl-invariant\">Seção Invariante</link>, "
+"escreva “sem Seções Invariantes” em vez de dizer quais são invariantes. Se "
+"você não tiver <link linkend=\"fdl-cover-texts\">Textos de Capa Frontal</"
+"link>, escreva “sem Textos da Capa Frontal” em vez de “Textos de Capa "
+"Frontal sendo LIST”; Da mesma forma para <link linkend=\"fdl-cover-texts"
+"\">Textos de Contracapa</link>."
#. (itstool) path: sect1/para
#: C/index.docbook:657
"gpl.html\"> GNU General Public License</ulink>, to permit their use in free "
"software."
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 type=\"http\" "
-"url=\"http://www.gnu.org/copyleft/gpl.html\">Licença Pública Geral GNU</"
-"ulink> (GNU General Public License), para permitir seu uso em software livre."
+"Se o seu documento contiver exemplos não triviais do código do programa, "
+"recomendamos que apresente esses exemplos em paralelo, sob sua escolha de "
+"licença de software livre, como a <ulink type=\"http\" url=\"http://www.gnu."
+"org/copyleft/gpl.html\">Licença Pública Geral GNU</ulink> (GNU General "
+"Public License), para permitir sua utilização em software livre."
#. (itstool) path: copyright/year
#: C/fdl-appendix.xml:16
#. (itstool) path: para/link
#: C/fdl-appendix.xml:550
msgid "Cover Text"
-msgstr "Capa de Texto"
+msgstr "Texto de Capa"
#. (itstool) path: sect1/para
#: C/fdl-appendix.xml:538
"Permissão concedida para copiar, distribuir e/ou modificar este documento "
"sob os termos da Licença de Documentação Livre GNU (GNU Free Documentation "
"License), Versão 1.1 ou qualquer versão mais recente publicada pela Free "
-"Software Foundation; com as <_:link-1/>, sendo LISTADO SEUS TÍTULOS, com os "
-"<_:link-2/> sendo LISTADOS, e com os <_:link-3/> sendo LISTADOS. Uma cópia "
-"da licença está inclusa na seção intitulada <_:quote-4/>."
+"Software Foundation; com as <_:link-1/>, sendo LISTE SEUS TÍTULOS, com os <_:"
+"link-2/> sendo LISTA, e com os <_:link-3/> sendo LISTA. Uma cópia da licença "
+"está inclusa na seção intitulada <_:quote-4/>."
#. (itstool) path: para/quote
#: C/fdl-appendix.xml:649
"software livre que você escolher, como, por exemplo, a <_:ulink-1/>, para "
"permitir seu uso em software livre."
+#~ msgid "Setting up your project"
+#~ msgstr "Preparando seu projeto"
+
+#~ 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 ""
+#~ "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."
+
+#~ 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 ""
+#~ "No diretório raiz do seu projeto, crie pastas chamadas docs/reference "
+#~ "(desta forma, você também pode ter docs/help para documentação para "
+#~ "usuário final). É recomendado criar um outro subdiretório com o nome do "
+#~ "pacote de documentação. Para pacotes com apenas uma biblioteca, esta "
+#~ "etapa não é obrigatória."
+
+#~ msgid "Example directory structure"
+#~ msgstr "Exemplo de estrutura de diretórios"
+
+#~ msgid "This can then look as shown below: <_:example-1/>"
+#~ msgstr "Isto pode, então, parecer como exibido abaixo: <_:example-1/>"
+
+#~ msgid ""
+#~ "Very easy! Just add one line to your <filename>configure.ac</filename> "
+#~ "script."
+#~ msgstr ""
+#~ "Muito fácil! Basta adicionar uma linha ao seu script <filename>configure."
+#~ "ac</filename>."
+
+#~ msgid ""
+#~ "\n"
+#~ "# check for gtk-doc\n"
+#~ "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+#~ msgstr ""
+#~ "\n"
+#~ "# verifica por gtk-doc\n"
+#~ "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+
+#~ msgid "Keep gtk-doc optional"
+#~ msgstr "Mantenha o gtk-doc como opcional"
+
+#~ 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"
+#~ "# verifica por 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"
+
+#~ 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 ""
+#~ "Isso vai exigir que todos os desenvolvedores tenham o gtk-doc instalado. "
+#~ "Se não houver problema para seu projeto ter uma configuração opcional de "
+#~ "compilação de documentação de API, você pode resolver isso como mostrado "
+#~ "abaixo. Mantenha assim, pois o gtkdocize está procurando por "
+#~ "<function>GTK_DOC_CHECK</function> no começo de uma linha. <_:example-1/>"
+
+#~ 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 ""
+#~ "Além disso, é recomendado que você tenha a seguinte linha dentro do seu "
+#~ "script <filename>configure.ac</filename>. Ela permite que "
+#~ "<application>gtkdocize</application> copie automaticamente a definição de "
+#~ "macro para <function>GTK_DOC_CHECK</function> para o seu projeto."
+
+#~ msgid "Preparation for gtkdocize"
+#~ msgstr "Preparação para gtkdocize"
+
+#~ msgid ""
+#~ "\n"
+#~ "AC_CONFIG_MACRO_DIR(m4)\n"
+#~ msgstr ""
+#~ "\n"
+#~ "AC_CONFIG_MACRO_DIR(m4)\n"
+
+#~ 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 ""
+#~ "Historicamente, GTK-Doc estava gerando arquivos modelo (template) nos "
+#~ "quais os desenvolvedores inseriam as documentações. Isso acabou sendo não "
+#~ "tão bom (ex.: a necessidade de serem gerados arquivos sob controle de "
+#~ "versão). Desde o GTK-Doc 1.9 as ferramentas podem obter todas as "
+#~ "informações dos comentários no fonte e, portanto, os arquivos modelo "
+#~ "podem ser evitados. Nós encorajamos as pessoas a manter a documentação no "
+#~ "código. O <application>gtkdocize</application> possui agora suporte à "
+#~ "opção <option>--flavour no-tmpl</option> que escolhe um makefile que "
+#~ "ignora totalmente o uso de tmpl. Além de adicionar a opção diretamente à "
+#~ "chamada do comando, elas também podem ser adicionadas a uma variável de "
+#~ "ambiente chamada <symbol>GTKDOCIZE_FLAGS</symbol> ou definidas como um "
+#~ "segundo parâmetro na macro <symbol>GTK_DOC_CHECK</symbol> no script "
+#~ "configure. Se você nunca alterou um arquivo tmpl a mão e está migrando de "
+#~ "versões antigas do gtkdoc, por favor remova o diretório (ex.: do sistema "
+#~ "de controle de versão)."
+
+#~ 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 ""
+#~ "Agora você pode apontar seu navegador para <filename>docs/reference/<"
+#~ "pacote>/index.html</filename>. Sim, é um pouco desapontador. Mas "
+#~ "aguente aí, durante o próximo capítulo nós vamos dizer como você pode "
+#~ "preencher as páginas com vida."
+
+#~ msgid "Documentation placement"
+#~ msgstr "Localização da documentação"
+
+#~ 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 ""
+#~ "Antigamente, a maioria das documentações tinha que ser preenchida em "
+#~ "arquivos residentes dentro do diretório <filename>tmpl</filename>. Isso "
+#~ "tem as desvantagens das informações frequentemente não serem atualizadas "
+#~ "e também que o arquivo tende a causar conflitos com sistemas de controle "
+#~ "de versão."
+
+#~ 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 ""
+#~ "Para evitar os problemas mencionados a seguir nós sugerimos que a "
+#~ "documentação seja colocada dentro das fontes. Este manual vai apenas "
+#~ "descrever esta forma de documentar código."
+
#~ msgid "<guilabel>Python</guilabel> - optional - for gtkdoc-depscan"
#~ msgstr "<guilabel>Python</guilabel> - opcional - para gtkdoc-depscan"
<holder>Dan Mueth and Chris Lyttle</holder>
</copyright>
<copyright>
- <year>2007-2015</year>
+ <year>2007-2019</year>
<holder>Stefan Sauer (Kost)</holder>
</copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision>
<revnumber>1.28</revnumber>
<title>About GTK-Doc</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
<term>Returns:</term>
<listitem>
<para>
- Specificy what value(s) the program returns. (Optional)
+ Specify what value(s) the program returns. (Optional)
</para>
</listitem>
</varlistentry>
<programlisting><![CDATA[
<example>
<title>Using a GHashTable.</title>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</example>
<informalexample>
<programlisting><![CDATA[
<informalexample>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</informalexample>
]]></programlisting>
</informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
For the latter GTK-Doc also supports an abbreviation:
-<![CDATA[
-|[
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
...
]|
-]]>
+]]></programlisting>
+ </informalexample>
</para>
<para>
</authorgroup>
<publisher role="maintainer"><publishername>GTK-Doc-projektet</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
<copyright><year>2000, 2005</year> <holder>Dan Mueth and Chris Lyttle</holder></copyright>
- <copyright><year>2007-2015</year> <holder>Stefan Sauer (Kost)</holder></copyright>
+ <copyright>
+ <year>2007-2019</year>
+ <holder>Stefan Sauer (Kost)</holder>
+ </copyright>
<!-- translators: uncomment this:
<copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision><revnumber>1.28</revnumber> <date>24 mar 2018</date> <authorinitials>ss</authorinitials> <revremark>programfixar</revremark></revision>
<revision><revnumber>1.27</revnumber> <date>07 dec 2017</date> <authorinitials>ss</authorinitials> <revremark>finjustering av python-porteringen</revremark></revision>
<orderedlist>
<listitem>
- <para>
- <guilabel>Writing the documentation.</guilabel>
-
- The author fills in the source files with the documentation for each
- function, macro, structs or unions, etc.
- </para>
+ <para><guilabel>Skriva dokumentationen.</guilabel> Författaren fyller i källkodsfilerna med dokumentation för varje funktion, makro, struct eller union, o.s.v.</para>
</listitem>
<listitem>
<sect1 id="aboutgtkdoc">
<title>Om GTK-Doc</title>
- <para>
- Historically GTK-Doc was used to generate template files from the soures
- code. These template files could be used by developers to enter the
- API documentation. This approach was rather inconvenient because it
- required to keep the generated files under version control.
- Since GTK-Doc 1.9 it became possible to place all API information
- into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
- </para>
+ <para>Historiskt användes GTK-Doc för att generera mallfiler från källkoden. Dessa mallfiler kunde användas av utvecklare för att ange API-dokumentationen. Detta tillvägagångssätt var ganska obekvämt då det krävde att genererade filer hölls under versionshantering. Sedan GTK-Doc 1.9 är det möjligt att placera all API-information i källkodskommentarer, vilket gör mallstödet föråldrat. I version 1.26 har mallstödet tagits bort.</para>
<para>(FIXME)</para>
- <para>
- (authors, web pages, mailing list, license, future plans,
- comparison with other similar systems.)
- </para>
+ <para>(författare, webbsidor, sändlistor, licens, framtida planer, jämförelse med andra liknande system.)</para>
</sect1>
</chapter>
<chapter id="settingup">
- <title>Project Setup</title>
+ <title>Projektkonfiguration</title>
- <para>
- This Chapter describes the steps that are necessary to integrate GTK-Doc
- into your project. The integration of GTK-Doc into a project includes the
- following steps:
- </para>
+ <para>Detta kapitel beskriver stegen som är nödvändiga för att integrera GTK-Doc i ditt projekt. Integreringen av GTK-Doc till ett projekt inkluderar följande steg:</para>
<itemizedlist>
<listitem>
- <para>
- Preparation of the directory structure and creating required
- configuration files for your GTK-Doc documentation (see
- <link linkend="settingup_docfiles">
- Setting up a skeleton documentation</link>).
- </para>
+ <para>Förberedelse av katalogstrukturen och skapande av konfigurationsfiler som krävs för din GTK-Doc-dokumentation (se <link linkend="settingup_docfiles"> Att ställa in en skelettstruktur för dokumentation</link>).</para>
</listitem>
<listitem>
- <para>
- Adjusting the build system to build your documentation using the
- GTK-Doc tools. Multiple build systems are supported, in
- this manual we describe how to integrate GTK-Doc with
- <link linkend="settingup_autotools">Autotools</link>,
- <link linkend="settingup_cmake">CMake</link>, and
- <link linkend="settingup_plain_makefiles">plain Makefiles</link>.
- </para>
+ <para>Justering av byggsystemet för att bygga din dokumentation med GTK-Doc-verktygen. Flera byggsystem stöds, i denna handbok beskriver vi hur GTK-Doc kan integreras med <link linkend="settingup_autotools">Autotools</link>, <link linkend="settingup_cmake">CMake</link> och <link linkend="settingup_plain_makefiles">vanliga Makefiler</link>.</para>
</listitem>
<listitem>
- <para>
- Adding GTK-Doc specific files to version control and deciding which
- files to ignore (see <link linkend="settingup_vcs">
- Integration with version control systems</link>).
- </para>
+ <para>Tillägg av GTK-Doc-specifika filer till versionshantering och att bestämma vilka filer som ska ignoreras (se <link linkend="settingup_vcs"> Integrering med versionshanteringssystem</link>).</para>
</listitem>
</itemizedlist>
- <para>
- The following sections assume we work on a project called
- <code>meep</code>.
- This project contains two packages (or modules),
- a library called <code>libmeep</code> and an end-user app
- called <code>meeper</code>.
- </para>
+ <para>De följande avsnitten utgår från att vi arbetar på ett projekt som kallas <code>meep</code>. Detta projekt innehåller två paket (eller moduler), ett bibliotek som kallas <code>libmeep</code> och ett program för slutanvändare som kallas <code>meeper</code>.</para>
<sect1 id="settingup_docfiles">
<title>Att ställa in en skelettstruktur för dokumentation</title>
- <para>
- A common convention is to place documentation into a folder called
- <code>docs</code> inside your top-level project directory.
- We usually distinguish between <emphasis>reference
- documentation</emphasis> intended for developers and an
- <emphasis>user manual</emphasis> intended for end-users.
- Again the convention is to have separate folders for both.
- We usually place the reference documentation in a folder named
- <code>reference</code> and the end-user manual in a folder named
- <code>help</code> as.
-
- According to the above convention the documentation for our
- <code>libmeep</code> package would be placed into:
- <code>docs/reference/libmeep</code>.
-
- For packages with just one library or application
- the documentation could also be placed directly into
- <code>docs/reference</code>.
-
- It is not mandatory to use the above convention, but if you
- choose to use a different directory structure you must adjust
- your build system configuration to match your directory
- structure.
- </para>
+ <para>En vanlig konvention är att placera dokumentation i en mapp kallad <code>docs</code> i toppnivåkatalogen för ditt projekt. Vi skiljer vanligen mellan <emphasis>referensdokumentation</emphasis> som är avsedd för utvecklare och en <emphasis>användarhandbok</emphasis> som är avsedd för slutanvändare. Konventionen är återigen att ha olika mappar för båda. Vi placerar vanligen referensdokumentationen i en mapp med namnet <code>reference</code> handboken för slutanvändare i en mapp med namnet <code>help</code>. Enligt konventionen ovan skulle dokumentationen för vårt paket <code>libmeep</code> placeras i: <code>docs/reference/libmeep</code>. För paket med bara ett bibliotek eller program kan dokumentationen också placeras direkt i <code>docs/reference</code>. Det är inte obligatoriskt att använda konventionen ovan, men om du väljer att använda en annan katalogstruktur måste du anpassa din konfiguration för byggsystemet så att den matchar din katalogstruktur.</para>
- <para>
- In the following sections we will assume a directory structure
- for our <emphasis>meep</emphasis> project that uses the above
- conventions.
-
- <example>
- <title>Example directory structure of <emphasis>meep</emphasis>
- project</title>
- <programlisting><![CDATA[
+ <para>I avsnitten som följer kommer vi anta en katalogstruktur för vårt projekt <emphasis>meep</emphasis> som följer konventionerna ovan. <example>
+ <title>Exempel på katalogstruktur för projektet <emphasis>meep</emphasis></title>
+ <programlisting>
meep/
docs/
- reference/ # reference documentation
+ reference/ # referensdokumentation
libmeep/
meeper/
- help/ # optional: user manual
+ help/ # valfritt: användarhandbok
meeper/
src/
libmeep/
meeper/
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
</sect1>
<sect1 id="settingup_autotools">
- <title>Integration with Autotools</title>
- <para>
- Integration of GTK-Doc into an autotools-based build system requires the
- following steps:
- </para>
+ <title>Integrering med Autotools</title>
+ <para>Integrering av GTK-Doc i ett autotools-baserat byggsystem kräver följande steg:</para>
<itemizedlist>
<listitem>
- <para>
- Ensure that <application>gtkdocize</application> is run once before
- the <filename>configure</filename> script. If an
- <filename>autogen.sh</filename> script is present, adjust it to
- check for GTK-Doc and add a call to
- <application>gtkdocize</application>.
- </para>
-
- <para>
- The main purpose of <application>gtkdocize</application> is to
- make the <filename>gtk-doc.make</filename> Makefile and the
- <filename>gtk-doc.m4</filename> macro definition file available
- to the build system, either by copying or linking it
- into the project.
- </para>
+ <para>Säkerställ att <application>gtkdocize</application> körs en gång innan skriptet <filename>configure</filename>. Om skriptet <filename>autogen.sh</filename> finns tillgängligt, justera det så att det söker efter GTK-Doc och lägg till ett anrop till <application>gtkdocize</application>.</para>
+
+ <para>Huvudsyftet med <application>gtkdocize</application> är att göra Makefilen <filename>gtk-doc.make</filename> och makrodefinitionsfilen <filename>gtk-doc.m4</filename> tillgängliga för byggsystemet, antingen genom att kopiera eller länka in dem i projektet.</para>
</listitem>
<listitem>
- <para>
- Add the necessary <application>autoconf</application> macros to
- <filename>configure.ac</filename> to enable GTK-Doc in your build
- system to allow configuration of GTK-Doc via the generated
- <filename>configure</filename> script.
- </para>
- <para>
- Among others with registers the <code>--enable-gtk-doc</code>
- option with the <filename>configure</filename> script.
- </para>
+ <para>Lägg till de nödvändiga <application>autoconf</application>-makrona till <filename>configure.ac</filename> för att aktivera GTK-Doc i ditt byggsystem för att tillåta konfiguration av GTK-Doc via det genererade <filename>configure</filename>-skriptet.</para>
+ <para>Bland andra med register flaggan <code>--enable-gtk-doc</code> med <filename>configure</filename>-skriptet.</para>
</listitem>
<listitem>
- <para>
- Create an <application>automake</application> script for each
- application or library in your project. In the example used in this
- documentation this step applies to both <code>meeper</code> and
- <code>libmeep</code>.
- </para>
+ <para>Skapa ett <application>automake</application>-skript för varje program eller bibliotek i ditt projekt. I exemplet som används i denna dokumentation tillämpas detta steg för både <code>meeper</code> och <code>libmeep</code>.</para>
</listitem>
</itemizedlist>
- <para>
- In the following sections, we will perform the above steps in reverse
- order. We start with the <application>automake</application> scripts
- and work our way up to <filename>configure.ac</filename> and
- <filename>autogen.sh</filename>.
- Then we show how enable Gtk-Doc in the build system and
- how to build the documentation.
- </para>
+ <para>I de följande avsnitten utför vi stegen ovan i omvänd ordning. Vi börjar med <application>automake</application>-skripten och arbetar vår väg upp till <filename>configure.ac</filename> och <filename>autogen.sh</filename>. Sedan visar vi hur Gtk-Doc aktiveras i byggsystemet och hur dokumentationen byggs.</para>
<sect2 id="settingup_automake">
<title>Integrering med automake</title>
- <para>
- First copy the <filename>Makefile.am</filename> from the
- <filename class="directory">examples</filename> sub-directory of the
- <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">
- gtkdoc-sources</ulink>
- to your project's reference documentation directory (e.g.
- <filename class="directory">docs/reference/<package></filename>).
- A local copy should be available under e.g.
- <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
- If you have multiple packages repeat this for each one.
- </para>
+ <para>Kopiera först <filename>Makefile.am</filename> från underkatalogen <filename class="directory">examples</filename> från <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">gtkdoc-sources</ulink> till ditt projekts referensdokumentationskatalog (t.ex. <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 paket, repetera detta för vart och ett.</para>
<note>
- <simpara>
- Do not forget to add each <filename>Makefile.am</filename>
- to the <function>AC_CONFIG_FILES</function> macro in
- <filename>configure.ac</filename>. For
- <filename>docs/reference/libmeep/Makefile.am</filename> you will
- need to add the entry
- <filename>docs/reference/libmeep/Makefile</filename>
- to <function>AC_CONFIG_FILES</function>.
- </simpara>
+ <simpara>Glöm inte att lägga till varje <filename>Makefile.am</filename> till makrot <function>AC_CONFIG_FILES</function> i <filename>configure.ac</filename>. För <filename>docs/reference/libmeep/Makefile.am</filename> kommer du behöva lägga till posten <filename>docs/reference/libmeep/Makefile</filename> till <function>AC_CONFIG_FILES</function>.</simpara>
</note>
<example>
- <title>
- Example directory structure with <filename>Makefiles.am</filename>
- </title>
+ <title>Exempelkatalogstruktur med <filename>Makefiles.am</filename></title>
<programlisting>
meep/
docs/
- reference/ # reference documentation
+ reference/ # referensdokumentation
libmeep/
Makefile.am
meeper/
Makefile.am
- help/ # optional: user manual
+ help/ # valfritt: användarhandbok
meeper/
src/
libmeep/
</programlisting>
</example>
- <para>
- Next, you need to customize the copied Makefiles
- and provide values for the various parameters in each
- <filename>Makefile.am</filename>.
-
- All settings have a comment above them that describes their purpose
- and how to customize the setting.
-
- Most settings are used to supply extra flags to the respective tools
- to which they apply. Every tool
- has a variable of the form <option><TOOLNAME>_OPTIONS</option>
- (e.g. the tool <application>gtkdoc-mkhtml</application> has
- an option named <code>MKHTML_OPTIONS</code>).
+ <para>Härnäst behöver du anpassa de kopierade Makefilerna och tillhandahålla värden för de olika parametrarna i varje <filename>Makefile.am</filename>. Alla inställningarna har en kommentar ovanför som beskriver deras syfte och hur inställningen kan anpassas. De flesta inställningarna används för att tillhandahålla extraflaggor till respektive verktyg för vilket de är aktuella. Varje verktyg har en variabel på formen <option><VERKTYGSNAMN>_OPTIONS</option> (t.ex. har verktyget <application>gtkdoc-mkhtml</application> en flagga med namnet <code>MKHTML_OPTIONS</code>). Alla verktygen har stöd för <option>--help</option> för att lista de flaggor som stöds.</para>
- All the tools support <option>--help</option> to list the supported
- options.
- </para>
-
- <para>
- The following list explains the most relevant options. Check the
- example <filename>Makefile.am</filename> for additional options.
-
- <itemizedlist>
+ <para>Följande lista förklarar de mest relevanta flaggorna. Se <filename>Makefile.am</filename>-exemplet för ytterligare flaggor. <itemizedlist>
<listitem>
- <para>
- <option>DOC_MODULE</option> is used to provide the name of the
- package that is being documentated (e.g. <code>meeper</code>, or
- <code>libmeep</code>).
- </para>
+ <para><option>DOC_MODULE</option> används för att tillhandahålla namnet på paketet som dokumenteras (t.ex. <code>meeper</code> eller <code>libmeep</code>).</para>
</listitem>
<listitem>
- <para>
- <option>DOC_SOURCE_DIR</option>
- is used to specify the location
- of source directory which GTK-Doc searches for your API
- documentation. This will usually be
- <code>
- DOC_SOURCE_DIR=$(top_srcdir)/src
- </code>
- or a sub-directory of that directory.
- </para>
+ <para><option>DOC_SOURCE_DIR</option> används för att ange platsen för källkatalogen där GTK-Doc söker efter din API-dokumentation. Detta kommer vanligen vara <code> DOC_SOURCE_DIR=$(top_srcdir)/src </code> eller en underkatalog till den katalogen.</para>
</listitem>
<listitem>
- <para>
- <option>HFILE_GLOB</option>
- and
- <option>CFILE_GLOB</option>
- are used for dependencies. Each option take a file-glob (e.g.
- <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>).
- The documentation will be rebuilt if any of the matched files
- change.
- </para>
+ <para><option>HFILE_GLOB</option> och <option>CFILE_GLOB</option> används för beroenden. Varje flagga tar en file-glob (t.ex. <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>). Dokumentationen kommer att byggas om ifall någon av de matchande filerna ändras.</para>
</listitem>
<listitem>
- <para>
- <option>EXTRA_HFILES</option>
- allows to specify extra header files
- to include when scanning for API documentation, which are not
- found under <code>DOC_SOURCE_DIR</code> (e.g. <code>
- EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).
- </para>
+ <para><option>EXTRA_HFILES</option> låter dig ange extra huvudfiler som ska inkluderas då API-dokumentation eftersöks, vilka inte hittas under <code>DOC_SOURCE_DIR</code> (t.ex. <code> EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).</para>
</listitem>
<listitem>
- <para>
- <option>IGNORE_HFILES</option>
- allows to specify header files
- or directories to ignore when scanning for API documentation.
- Use the basename of the file or directory (e.g. <code>
- IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).
- </para>
+ <para><option>IGNORE_HFILES</option> låter dig ange huvudfiler eller kataloger som ska ignoreras då API-dokumentation eftersöks. Använd basnamnet på filen eller katalogen (t.ex. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).</para>
</listitem>
<listitem>
- <para>
- <option>HTML_IMAGES</option>
- allows to specify images files which
- will be copied into the <filename>html/</filename> directory of
- the generated documentation.
- If your API documentation includes any images they need to be
- added to this
- option (e.g. <code>
- HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).
- </para>
+ <para><option>HTML_IMAGES</option> låter dig ange bildfiler som kommer att kopieras till katalogen <filename>html/</filename> av den genererade dokumentationen. Om din API-dokumentation inkluderar några bilder behöver de läggas till i denna flagga (t.ex. <code> HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).</para>
</listitem>
<listitem>
- <para>
- <option>content_files</option>
- allows to specify extra files
- that are included by
- <code>$(DOC_MAIN_SGML_FILE)</code>
- (e.g. <code>
- content_files=running.xml building.xml changes-2.0.xml</code>).
- </para>
+ <para><option>content_files</option> låter dig ange extrafiler som inkluderas av <code>$(DOC_MAIN_SGML_FILE)</code> (t.ex. <code> content_files=running.xml building.xml changes-2.0.xml</code>).</para>
</listitem>
<listitem>
- <para>
- <option>expand_content_files</option>
- allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
- <code>#GtkWidget</code>
- are expanded (e.g. <code>
- expand_content_files=running.xml</code>).
- </para>
+ <para><option>expand_content_files</option> låter dig ange filer där <emphasis>gtk-doc-förkortningar</emphasis> så som <code>#GtkWidget</code> expanderas (t.ex. <code> expand_content_files=running.xml</code>).</para>
</listitem>
- </itemizedlist>
- </para>
+ </itemizedlist></para>
</sect2>
<sect2 id="settingup_autoconf">
<title>Integrering med autoconf</title>
- <para>
- Integration with <application>autoconf</application> is very simple
- and includes one required step and an additional optional
- (but recommended) step.
-
- The first step is to add the <function>GTK_DOC_CHECK</function> macro
- to your <filename>configure.ac</filename> script. This registers
- several configure options to enable GTK-Doc and allows you
- to set default arguments for <application>gtkdocize</application>.
- </para>
+ <para>Integrering med <application>autoconf</application> är väldigt enkel och inkluderar ett obligatoriskt steg och ett ytterligare valfritt (men rekommenderat) steg. Det första steget är att lägga till <function>GTK_DOC_CHECK</function>-makrot till ditt <filename>configure.ac</filename>-skript. Detta registrerar flera konfigurationsflaggor för att aktivera GTK-Doc och låter dig ställa in standardargument för <application>gtkdocize</application>.</para>
<warning>
- <simpara>
- Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented.
- The macro must start at the beginning of the line and should not
- start with whitespace.
- </simpara>
+ <simpara>Säkerställ att makrot <code>GTK_DOC_CHECK</code> inte är indenterat. Makrot måste inledas på början av raden och får inte börja med blanktecken.</simpara>
</warning>
- <para>
- The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code>
- to your <filename>configure.ac</filename>. This is not required
- but helps <application>gtkdocize</application> to automatically copy
- the macro definition (e.g <filename>gtk-doc.m4</filename>) which
- contains the <function>GTK_DOC_CHECK</function> macro to your
- project's macro directory. Without this, the GTK_DOC_CHECK macro
- might not be found and you would need to explicitly tell the
- <application>aclocal</application> tool where to find the macro
- definition file.
- </para>
+ <para>Det andra steget är att lägga till <code>AC_CONFIG_MACRO_DIR(m4)</code> till din <filename>configure.ac</filename>. Detta krävs inte men hjälper <application>gtkdocize</application> att automatiskt kopiera makrodefinitionen (t.ex. <filename>gtk-doc.m4</filename>) som innehåller <function>GTK_DOC_CHECK</function>-makrot till ditt projekts makrokatalog. Utan detta kanske GTK_DOC_CHECK-makrot inte hittas och du skulle behöva explicit berätta för <application>aclocal</application>-verktyget var makrodefinitionsfilen kan hittas.</para>
<para>
- <example><title>Minimal integration with autoconf</title>
- <programlisting><![CDATA[
-# recommended: set m4 directory
+ <example><title>Minimal integrering med autoconf</title>
+ <programlisting>
+# rekommenderat: ställ in m4-katalog
AC_CONFIG_MACRO_DIR(m4)
-# optional: register gtk-doc in configure
+# valfritt: registrera gtk-doc i configure
GTK_DOC_CHECK([1.28])
-]]></programlisting>
+</programlisting>
</example>
</para>
- <para>
- The above example works, but will require all developers to have
- gtk-doc installed. A better way is to make building the documentation
- optional as shown in the next example:
-
- <example>
- <title>Integration with optional gtk-doc dependency</title>
- <programlisting><![CDATA[
+ <para>Exemplet ovan fungerar, men skulle kräva att alla utvecklare har gtk-doc installerat. Ett bättre sätt är att göra byggande av dokumentationen valfritt på det sätt som visas i nästa exempel: <example>
+ <title>Integrering med valfritt gtk-doc-beroende</title>
+ <programlisting>
m4_ifdef([GTK_DOC_CHECK], [
-# recommended: set m4 directory
+# rekommenderat: ställ in m4-katalog
AC_CONFIG_MACRO_DIR(m4)
-# optional: register gtk-doc in configure
+# valfritt: registrera gtk-doc i configure
GTK_DOC_CHECK([1.28])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
- <para>
- The first argument is used to check for the Gtk-Doc version at
- configure time. The 2nd, optional argument is used by
- <application>gtkdocize</application>.
- The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure
- switches:
- </para>
+ <para>Det första argumentet används för att leta efter Gtk-Doc-versionen under konfigurationen. Det andra, valfria, argumentet används av <application>gtkdocize</application>. Makrot <symbol>GTK_DOC_CHECK</symbol> lägger också till flera configure-flaggor:</para>
<orderedlist>
<listitem><para>--with-html-dir=SÖKVÄG : sökväg till installerad dokumentation</para></listitem>
<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>
- After all changes to <filename>configure.ac</filename> are made,
- update the <filename>configure</filename> file. This can be done by
- re-running <code>autogen.sh</code>.
- </para>
+ <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>autogen.sh</code>.</para>
</sect2>
<sect2 id="settingup_autogen">
<title>Integrering med autogen</title>
- <para>
- Most projects will have an <filename>autogen.sh</filename> script to
- setup the build infrastructure after the project was checked out from
- a version control system (such as git or svn). GTK-Doc comes with a
- script called <application>gtkdocize</application> which can be used
- to copy the necessary files needed by Gtk-Doc to the source directory.
- </para>
+ <para>De flesta projekt kommer att ha ett <filename>autogen.sh</filename>-skript för att ställa in infrastrukturen för bygget efter utcheckning från ett versionshanteringssystem (så som git eller svn). GTK-Doc kommer med ett skript som heter <application>gtkdocize</application> som kan användas för att kopiera nödvändiga filer som behövs av Gtk-Doc till källkatalogen.</para>
- <para>
- It should be run before autoreconf, autoheader, automake or autoconf.
- </para>
+ <para>Det bör köras före autoreconf, autoheader, automake eller autoconf.</para>
<para>
<example><title>Köra gtkdocize från autogen.sh</title>
<para>
<example>
- <title>Conditionally run gtkdocize from autogen.sh</title>
- <programlisting><![CDATA[
-GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+ <title>Köra gtkdocize villkorligt från autogen.sh</title>
+ <programlisting>
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
if test $? -ne 0; then
- echo "No gtk-doc support found. You can't build the docs."
+ echo "Inget gtk-doc-stöd funnet. Du kan inte bygga dokumentationen."
else
$GTKDOCIZE || exit 1
fi
-]]></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).
- </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>).</para>
- <para>
- <application>gtkdocize</application> checks your
- <filename>configure.ac</filename> script for
- the <function>GTK_DOC_CHECK</function> macro.
- The <function>GTK_DOC_CHECK</function> macro can be used to pass
- extra arguments to the <application>gtkdocize</application> script.
- the 2nd parameter in the <function>GTK_DOC_CHECK</function> macro.
- </para>
+ <para><application>gtkdocize</application> söker i ditt <filename>configure.ac</filename>-skript efter makrot <function>GTK_DOC_CHECK</function>. Makrot <function>GTK_DOC_CHECK</function> kan användas för att skicka extra argument till skriptet <application>gtkdocize</application>. den andra parametern i <function>GTK_DOC_CHECK</function>-makrot.</para>
- <para>
- Alternatively, additional arguments can also be passed to
- <application>gtkdocize</application> via the
- <function>GTKDOCIZE_FLAGS</function> environment variable, or by
- directly specifying them to <application>gtkdocize</application>
- in <filename>autogen.sh</filename>.
- </para>
+ <para>Alternativt kan ytterligare argument också skickas till <application>gtkdocize</application> via miljövariabeln <function>GTKDOCIZE_FLAGS</function>, eller genom att ange dem direkt till <application>gtkdocize</application> i <filename>autogen.sh</filename>.</para>
</sect2>
<sect2 id="settingup_firstrun">
- <title>Executing GTK-Doc from the Build System</title>
+ <title>Köra GTK-Doc från byggsystemet</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>
</example>
</para>
- <para>
- Now you can point your browser to
- <filename>docs/reference/<package>/index.html</filename>.
- With this initial setup you will only see a very simple document.
- The next chapter will teach you how to add API documentation to your
- code via special comment blocks. The Chapter afterwards introduces
- <link linkend="metafiles">additional files</link> and shows how to
- edit the <link linkend="metafiles_master">master template</link> to
- add additional chapters and sections to your documentation files.
- </para>
+ <para>Nu kan du peka din webbläsare till <filename>docs/reference/<paket>/index.html</filename>. Med denna ursprungliga konfiguration kommer du bara se ett väldigt enkelt dokument. Nästa kapitel kommer att lära dig hur du lägger till API-dokumentation till din kod via speciella kommentarsblock. Kapitlet efteråt introducerar <link linkend="metafiles">ytterligare filer</link> och visar hur <link linkend="metafiles_master">huvudmallen</link> redigeras för att lägga till ytterligare kapitel och avsnitt till dina dokumentationsfiler.</para>
</sect2>
<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>
- <para>
- The GTK-Doc scanner can handle the majority of C headers fine. In the
- case of receiving warnings from the scanner that look like a special
- case, one can hint GTK-Doc to skip over them.
- <example><title>GTK-Doc comment block</title>
- <programlisting><![CDATA[
+ <para>GTK-Doc-detektorn kan hantera majoriteten av C-huvuden bra. I det fall när du får varningar från detektorn som ser ut som ett specialfall, kan du tipsa GTK-Doc att hoppa över dem. <example><title>GTK-Doc-kommentarsblock</title>
+ <programlisting>
#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif
-]]></programlisting>
- </example>
- </para>
+</programlisting>
+ </example></para>
<note>
<title>Begränsningar</title>
<para>Fler exempel på vilka markdown-taggar som stöds hittas i <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">Referensen för GTK+-dokumentationens markdown-syntax</ulink>.</para>
<tip>
- <para>
- As already mentioned earlier GTK-Doc is for documenting public API. Thus
- one cannot write documentation for static symbols. Nevertheless it is good
- to comment those symbols too. This helps other developers to understand
- your code.
- Therefore we recommend to comment these using normal comments (without the
- 2nd '*' in the first line).
- If later the function needs to be made public, all one needs to do is to
- add another '*' in the comment block and insert the symbol name at the
- right place inside the sections file.
- </para>
+ <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 även dessa symboler. Det hjälper andra utvecklare att förstå din kod. Därför rekommenderar vi att du kommenterar dessa med normala kommentarer (utan den andra ”*” på den första raden). Om funktionen vid ett senare tillfälle måste göras publik är allt du behöver göra att lägga till ytterligare en ”*” i kommentarsblocket och infoga symbolnamnet på rätt ställe i avsnittsfilen.</para>
</tip>
</sect1>
</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>
+ To include example code:
+ <informalexample>
+ <programlisting><![CDATA[
+<example>
+ <title>Using a GHashTable.</title>
+ <programlisting language="C">
+ ...
+ </programlisting>
+</example>
+]]></programlisting>
+ </informalexample>
+ or possibly this, for very short code fragments which don't need a title:
+ <informalexample>
+ <programlisting><![CDATA[
+<informalexample>
+ <programlisting language="C">
+ ...
+ </programlisting>
+</informalexample>
+]]></programlisting>
+ </informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
+ For the latter GTK-Doc also supports an abbreviation:
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
+ ...
+]|
+]]></programlisting>
+ </informalexample>
+ </para>
<para>För att inkludera punktlistor: <informalexample>
<programlisting>
<sect1 id="metafiles_types">
<title>Redigera typfilen</title>
- <para>Om ditt bibliotek eller program inkluderar GObject så kommer du att vilja att deras signaler, argument/parametrar och position i hierarkin visas i dokumentationen. Allt du behöver göra är att lista <function>xxx_get_type</function>-funktionerna tillsammans med deras huvudfil i filen <filename><package>.types</filename>.</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><paket>.types</filename>.</para>
<para>
- <example><title>Example <package>.types file</title>
+ <example><title>Exempel på filen <paket>.types</title>
<programlisting>
#include <gtk/gtk.h>
<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
- in the master template and how the entities are used.
- The entities can also be used in all
- generated files, GTK-Doc will use the same xml header in generated xml
- files.
- <example><title>Use pre-generated entities</title>
- <programlisting><![CDATA[
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ <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 i huvudmallen och hur entiteterna används. Entiteterna kan också användas i alla genererade filer, GTK-Doc kommer att använda samma xml-huvud i genererade xml-filer. <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>
msgid ""
msgstr ""
"Project-Id-Version: gtk-doc master\n"
-"POT-Creation-Date: 2018-03-24 15:17+0000\n"
-"PO-Revision-Date: 2018-03-24 22:40+0100\n"
+"POT-Creation-Date: 2018-10-03 08:17+0000\n"
+"PO-Revision-Date: 2018-11-24 22:38+0100\n"
"Last-Translator: Anders Jonsson <anders.jonsson@norsjovallen.se>\n"
"Language-Team: Swedish <tp-sv@listor.tp-sv.se>\n"
"Language: sv\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
-"X-Generator: Poedit 2.0.6\n"
+"X-Generator: Poedit 2.2\n"
#. Put one translator per line, in the form NAME <EMAIL>, YEAR1, YEAR2
msgctxt "_"
#. (itstool) path: revhistory/revision
#: C/index.docbook:83
msgid ""
-"<revnumber>1.2
8.1</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
+"<revnumber>1.2
9.1</revnumber> <date>28 Aug 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>development</revremark>"
msgstr ""
-"<revnumber>1.2
8.1</revnumber> <date>24 mar 2018</date> <authorinitials>ss</"
+"<revnumber>1.2
9.1</revnumber> <date>28 aug 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>utveckling</revremark>"
#. (itstool) path: revhistory/revision
#: C/index.docbook:89
msgid ""
+"<revnumber>1.29</revnumber> <date>28 Aug 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>development</revremark>"
+msgstr ""
+"<revnumber>1.29</revnumber> <date>28 aug 2018</date> <authorinitials>ss</"
+"authorinitials> <revremark>utveckling</revremark>"
+
+#. (itstool) path: revhistory/revision
+#: C/index.docbook:95
+msgid ""
"<revnumber>1.28</revnumber> <date>24 Mar 2018</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
msgstr ""
"authorinitials> <revremark>programfixar</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:95
+#: C/index.docbook:101
msgid ""
"<revnumber>1.27</revnumber> <date>07 Dec 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>fine tuning of the python port</revremark>"
"authorinitials> <revremark>finjustering av python-porteringen</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:101
+#: C/index.docbook:107
msgid ""
"<revnumber>1.26</revnumber> <date>11 Aug 2017</date> <authorinitials>ss</"
"authorinitials> <revremark>port all tools from perl/bash to python</"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:107
+#: C/index.docbook:113
msgid ""
"<revnumber>1.25</revnumber> <date>21 March 2016</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, test cleanups</revremark>"
"authorinitials> <revremark>programfixar, uppstädning av tester</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:113
+#: C/index.docbook:119
msgid ""
"<revnumber>1.24</revnumber> <date>29 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>programfix</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:119
+#: C/index.docbook:125
msgid ""
"<revnumber>1.23</revnumber> <date>17 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fix</revremark>"
"authorinitials> <revremark>programfix</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:125
+#: C/index.docbook:131
msgid ""
"<revnumber>1.22</revnumber> <date>07 May 2015</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"funktioner</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:131
+#: C/index.docbook:137
msgid ""
"<revnumber>1.21</revnumber> <date>17 Jul 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, dropping deprecated features</"
"funktioner</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:137
+#: C/index.docbook:143
msgid ""
"<revnumber>1.20</revnumber> <date>16 Feb 2014</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, markdown support, style improvements</"
"stilförbättringar</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:143
+#: C/index.docbook:149
msgid ""
"<revnumber>1.19</revnumber> <date>05 Jun 2013</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes</revremark>"
"authorinitials> <revremark>programfixar</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:149
+#: C/index.docbook:155
msgid ""
"<revnumber>1.18</revnumber> <date>14 Sep 2011</date> <authorinitials>ss</"
"authorinitials> <revremark>bug fixes, speedups, markdown support</revremark>"
"revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:155
+#: C/index.docbook:161
msgid ""
"<revnumber>1.17</revnumber> <date>26 Feb 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>urgent bug fix update</revremark>"
"authorinitials> <revremark>brådskande programfixuppdatering</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:161
+#: C/index.docbook:167
msgid ""
"<revnumber>1.16</revnumber> <date>14 Jan 2011</date> <authorinitials>sk</"
"authorinitials> <revremark>bugfixes, layout improvements</revremark>"
"authorinitials> <revremark>programfixar, layoutförbättringar</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:167
+#: C/index.docbook:173
msgid ""
"<revnumber>1.15</revnumber> <date>21 May 2010</date> <authorinitials>sk</"
"authorinitials> <revremark>bug and regression fixes</revremark>"
"authorinitials> <revremark>program- och regressionsfixar</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:173
+#: C/index.docbook:179
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:179
+#: C/index.docbook:185
msgid ""
"<revnumber>1.13</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>broken tarball update</"
"trasigt tar-arkiv</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:185
+#: C/index.docbook:191
msgid ""
"<revnumber>1.12</revnumber> <date>18 December 2009</date> "
"<authorinitials>sk</authorinitials> <revremark>new tool features and "
"programfixar</revremark>"
#. (itstool) path: revhistory/revision
-#: C/index.docbook:191
+#: C/index.docbook:197
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:204
+#: C/index.docbook:210
msgid "Introduction"
msgstr "Introduktion"
#. (itstool) path: chapter/para
-#: C/index.docbook:206
+#: C/index.docbook:212
msgid ""
"This chapter introduces GTK-Doc and gives an overview of what it is and how "
"it is used."
"hur det används."
#. (itstool) path: sect1/title
-#: C/index.docbook:212
+#: C/index.docbook:218
msgid "What is GTK-Doc?"
msgstr "Vad är GTK-Doc?"
#. (itstool) path: sect1/para
-#: C/index.docbook:214
+#: C/index.docbook:220
msgid ""
"GTK-Doc is used to document C code. It is typically used to document the "
"public API of libraries, such as the GTK+ and GNOME libraries. But it can "
"biblioteken. Men det kan också användas för att dokumentera programkod."
#. (itstool) path: sect1/title
-#: C/index.docbook:222
+#: C/index.docbook:228
msgid "How Does GTK-Doc Work?"
msgstr "Hur fungerar GTK-Doc?"
# sebras: how do I translate header files?
#. (itstool) path: sect1/para
-#: C/index.docbook:224
+#: C/index.docbook:230
msgid ""
"GTK-Doc works by using documentation of functions placed inside the source "
"files in specially-formatted comment blocks, or documentation added to the "
"huvudfiler; det kommer inte att producera utdata för statiska funktioner)."
#. (itstool) path: sect1/para
-#: C/index.docbook:231
+#: C/index.docbook:237
msgid ""
"GTK-Doc consists of a number of python scripts, each performing a different "
"step in the process."
"i processen."
#. (itstool) path: sect1/para
-#: C/index.docbook:236
+#: C/index.docbook:242
msgid "There are 5 main steps in the process:"
msgstr "Det finns 5 huvudsteg i processen:"
#. (itstool) path: listitem/para
-#: C/index.docbook:243
+#: C/index.docbook:249
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)."
+"source files with the documentation for each function, macro, structs or "
+"unions, etc."
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)."
+"källkodsfilerna med dokumentation för varje funktion, makro, struct eller "
+"union, o.s.v."
# sebras: more header files...
#. (itstool) path: listitem/para
-#: C/index.docbook:253
+#: C/index.docbook:258
msgid ""
"<guilabel>Gathering information about the code.</guilabel> "
"<application>gtkdoc-scan</application> scans the header files of the code "
"module>-overrides.txt</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:270
+#: C/index.docbook:275
msgid ""
"<application>gtkdoc-scangobj</application> can also be used to dynamically "
"query a library about any GObject subclasses it exports. It saves "
"vilka GObject-egenskaper och signaler det tillhandahåller."
#. (itstool) path: listitem/para
-#: C/index.docbook:276
+#: C/index.docbook:281
msgid ""
"<application>gtkdoc-scanobj</application> should not be used anymore. It was "
"needed in the past when GObject was still GtkObject inside gtk+."
"behövdes tidigare när GObject fortfarande var GtkObject inuti gtk+."
#. (itstool) path: listitem/para
-#: C/index.docbook:283
+#: C/index.docbook:288
msgid ""
"<guilabel>Generating the XML and HTML/PDF.</guilabel> <application>gtkdoc-"
"mkdb</application> turns the template files into XML files in the <filename "
"introspektionsdata."
#. (itstool) path: listitem/para
-#: C/index.docbook:292
+#: C/index.docbook:297
msgid ""
"<application>gtkdoc-mkhtml</application> turns the XML files into HTML files "
"in the <filename class=\"directory\">html/</filename> subdirectory. Likewise "
"till ett PDF-dokument kallat <filename><package>.pdf</filename>."
#. (itstool) path: listitem/para
-#: C/index.docbook:298
+#: C/index.docbook:303
msgid ""
"Files in <filename class=\"directory\">xml/</filename> and <filename class="
"\"directory\">html/</filename> directories are always overwritten. One "
"aldrig redigera dem direkt."
#. (itstool) path: listitem/para
-#: C/index.docbook:306
+#: C/index.docbook:311
msgid ""
"<guilabel>Fixing up cross-references between documents.</guilabel> After "
"installing the HTML files, <application>gtkdoc-fixxref</application> can be "
"(i de fall där dokumentationen finns installerad)."
#. (itstool) path: sect1/title
-#: C/index.docbook:324
+#: C/index.docbook:329
msgid "Getting GTK-Doc"
msgstr "Hämta GTK-Doc"
#. (itstool) path: sect2/title
-#: C/index.docbook:327
+#: C/index.docbook:332
msgid "Requirements"
msgstr "Krav"
#. (itstool) path: sect2/para
-#: C/index.docbook:328
+#: C/index.docbook:333
msgid ""
"<guilabel>python 2/3</guilabel> - the main scripts are written in python."
msgstr "<guilabel>python 2/3</guilabel> - huvudskripten är skrivna i python."
#. (itstool) path: sect2/para
-#: C/index.docbook:331
+#: C/index.docbook:336
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:335
+#: C/index.docbook:340
msgid ""
"<guilabel>docbook-xsl</guilabel> - the docbook xsl stylesheets <ulink url="
"\"http://sourceforge.net/projects/docbook/files/docbook-xsl/\" type=\"http"
# sebras: remind me how was highlighting translated..?
#. (itstool) path: sect2/para
-#: C/index.docbook:339
+#: C/index.docbook:344
msgid ""
"One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> "
"or <guilabel>vim</guilabel> - optional - used for syntax highlighting of "
"syntaxfärgning av exempel"
#. (itstool) path: sect1/title
-#: C/index.docbook:347
+#: C/index.docbook:352
msgid "About GTK-Doc"
msgstr "Om GTK-Doc"
+# TODO: https://gitlab.gnome.org/GNOME/gtk-doc/issues/52
+# +sources code
+#. (itstool) path: sect1/para
+#: C/index.docbook:354
+msgid ""
+"Historically GTK-Doc was used to generate template files from the sources "
+"code. These template files could be used by developers to enter the API "
+"documentation. This approach was rather inconvenient because it required to "
+"keep the generated files under version control. Since GTK-Doc 1.9 it became "
+"possible to place all API information into source comments, which made the "
+"template support obsolete. In version 1.26 template support has been removed."
+msgstr ""
+"Historiskt användes GTK-Doc för att generera mallfiler från källkoden. Dessa "
+"mallfiler kunde användas av utvecklare för att ange API-dokumentationen. "
+"Detta tillvägagångssätt var ganska obekvämt då det krävde att genererade "
+"filer hölls under versionshantering. Sedan GTK-Doc 1.9 är det möjligt att "
+"placera all API-information i källkodskommentarer, vilket gör mallstödet "
+"föråldrat. I version 1.26 har mallstödet tagits bort."
+
#. (itstool) path: sect1/para
-#: C/index.docbook:349 C/index.docbook:363
+#: C/index.docbook:364 C/index.docbook:378
msgid "(FIXME)"
msgstr "(FIXME)"
#. (itstool) path: sect1/para
-#: C/index.docbook:353
+#: C/index.docbook:368
msgid ""
-"(History, authors, web pages, mailing list, license, future plans, "
-"comparison with other similar systems.)"
+"(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.)"
+"(författare, webbsidor, sändlistor, licens, framtida planer, jämförelse med "
+"andra liknande system.)"
#. (itstool) path: sect1/title
-#: C/index.docbook:361
+#: C/index.docbook:376
msgid "About this Manual"
msgstr "Om denna handbok"
#. (itstool) path: sect1/para
-#: C/index.docbook:367
+#: C/index.docbook:382
msgid "(who it is meant for, where you can get it, license)"
msgstr "(vem är den avsett för, var kan du få tag i den, licens)"
#. (itstool) path: chapter/title
-#: C/index.docbook:376
-msgid "Setting up your project"
-msgstr "Att ställa in ditt projekt"
+#: C/index.docbook:391
+msgid "Project Setup"
+msgstr "Projektkonfiguration"
+
+#. (itstool) path: chapter/para
+#: C/index.docbook:393
+msgid ""
+"This Chapter describes the steps that are necessary to integrate GTK-Doc "
+"into your project. The integration of GTK-Doc into a project includes the "
+"following steps:"
+msgstr ""
+"Detta kapitel beskriver stegen som är nödvändiga för att integrera GTK-Doc i "
+"ditt projekt. Integreringen av GTK-Doc till ett projekt inkluderar följande "
+"steg:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:401
+msgid ""
+"Preparation of the directory structure and creating required configuration "
+"files for your GTK-Doc documentation (see <link linkend=\"settingup_docfiles"
+"\"> Setting up a skeleton documentation</link>)."
+msgstr ""
+"Förberedelse av katalogstrukturen och skapande av konfigurationsfiler som "
+"krävs för din GTK-Doc-dokumentation (se <link linkend=\"settingup_docfiles"
+"\"> Att ställa in en skelettstruktur för dokumentation</link>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:409
+msgid ""
+"Adjusting the build system to build your documentation using the GTK-Doc "
+"tools. Multiple build systems are supported, in this manual we describe how "
+"to integrate GTK-Doc with <link linkend=\"settingup_autotools\">Autotools</"
+"link>, <link linkend=\"settingup_cmake\">CMake</link>, and <link linkend="
+"\"settingup_plain_makefiles\">plain Makefiles</link>."
+msgstr ""
+"Justering av byggsystemet för att bygga din dokumentation med GTK-Doc-"
+"verktygen. Flera byggsystem stöds, i denna handbok beskriver vi hur GTK-Doc "
+"kan integreras med <link linkend=\"settingup_autotools\">Autotools</link>, "
+"<link linkend=\"settingup_cmake\">CMake</link> och <link linkend="
+"\"settingup_plain_makefiles\">vanliga Makefiler</link>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:419
+msgid ""
+"Adding GTK-Doc specific files to version control and deciding which files to "
+"ignore (see <link linkend=\"settingup_vcs\"> Integration with version "
+"control systems</link>)."
+msgstr ""
+"Tillägg av GTK-Doc-specifika filer till versionshantering och att bestämma "
+"vilka filer som ska ignoreras (se <link linkend=\"settingup_vcs\"> "
+"Integrering med versionshanteringssystem</link>)."
#. (itstool) path: chapter/para
-#: C/index.docbook:378
-msgid ""
-"The next sections describe what steps to perform to integrate GTK-Doc into "
-"your project. Theses sections assume we work on a project called 'meep'. "
-"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."
+#: C/index.docbook:427
+msgid ""
+"The following sections assume we work on a project called <code>meep</code>. "
+"This project contains two packages (or modules), a library called "
+"<code>libmeep</code> and an end-user app called <code>meeper</code>."
+msgstr ""
+"De följande avsnitten utgår från att vi arbetar på ett projekt som kallas "
+"<code>meep</code>. Detta projekt innehåller två paket (eller moduler), ett "
+"bibliotek som kallas <code>libmeep</code> och ett program för slutanvändare "
+"som kallas <code>meeper</code>."
#. (itstool) path: sect1/title
-#: C/index.docbook:389
+#: C/index.docbook:436
msgid "Setting up a skeleton documentation"
msgstr "Att ställa in en skelettstruktur för dokumentation"
-#. (itstool) path: sect1/para
-#: C/index.docbook:391
-msgid ""
-"Under your top-level project directory create folders called docs/reference "
-"(this way you can also have docs/help for end-user documentation). It is "
-"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."
+# https://gitlab.gnome.org/GNOME/gtk-doc/issues/52
+#. (itstool) path: sect1/para
+#: C/index.docbook:438
+msgid ""
+"A common convention is to place documentation into a folder called "
+"<code>docs</code> inside your top-level project directory. We usually "
+"distinguish between <emphasis>reference documentation</emphasis> intended "
+"for developers and an <emphasis>user manual</emphasis> intended for end-"
+"users. Again the convention is to have separate folders for both. We usually "
+"place the reference documentation in a folder named <code>reference</code> "
+"and the end-user manual in a folder named <code>help</code> as. According to "
+"the above convention the documentation for our <code>libmeep</code> package "
+"would be placed into: <code>docs/reference/libmeep</code>. For packages with "
+"just one library or application the documentation could also be placed "
+"directly into <code>docs/reference</code>. It is not mandatory to use the "
+"above convention, but if you choose to use a different directory structure "
+"you must adjust your build system configuration to match your directory "
+"structure."
+msgstr ""
+"En vanlig konvention är att placera dokumentation i en mapp kallad "
+"<code>docs</code> i toppnivåkatalogen för ditt projekt. Vi skiljer vanligen "
+"mellan <emphasis>referensdokumentation</emphasis> som är avsedd för "
+"utvecklare och en <emphasis>användarhandbok</emphasis> som är avsedd för "
+"slutanvändare. Konventionen är återigen att ha olika mappar för båda. Vi "
+"placerar vanligen referensdokumentationen i en mapp med namnet "
+"<code>reference</code> handboken för slutanvändare i en mapp med namnet "
+"<code>help</code>. Enligt konventionen ovan skulle dokumentationen för vårt "
+"paket <code>libmeep</code> placeras i: <code>docs/reference/libmeep</code>. "
+"För paket med bara ett bibliotek eller program kan dokumentationen också "
+"placeras direkt i <code>docs/reference</code>. Det är inte obligatoriskt att "
+"använda konventionen ovan, men om du väljer att använda en annan "
+"katalogstruktur måste du anpassa din konfiguration för byggsystemet så att "
+"den matchar din katalogstruktur."
#. (itstool) path: example/title
-#: C/index.docbook:400
-msgid "Example directory structure"
-msgstr "Exempel på katalogstruktur"
+#: C/index.docbook:469
+msgid "Example directory structure of <emphasis>meep</emphasis> project"
+msgstr "Exempel på katalogstruktur för projektet <emphasis>meep</emphasis>"
#. (itstool) path: example/programlisting
-#: C/index.docbook:401
+#: C/index.docbook:471
#, no-wrap
msgid ""
"\n"
"meep/\n"
" docs/\n"
-" reference/\n"
+" reference/ # reference documentation\n"
" libmeep/\n"
" meeper/\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
"\n"
"meep/\n"
" docs/\n"
-" reference/\n"
+" reference/ # referensdokumentation\n"
" libmeep/\n"
" meeper/\n"
+" help/ # valfritt: användarhandbok\n"
+" meeper/\n"
" src/\n"
" libmeep/\n"
" meeper/\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:398
-msgid "This can then look as shown below: <_:example-1/>"
-msgstr "Detta kan se ut enligt nedan: <_:example-1/>"
+#: C/index.docbook:463
+msgid ""
+"In the following sections we will assume a directory structure for our "
+"<emphasis>meep</emphasis> project that uses the above conventions. <_:"
+"example-1/>"
+msgstr ""
+"I avsnitten som följer kommer vi anta en katalogstruktur för vårt projekt "
+"<emphasis>meep</emphasis> som följer konventionerna ovan. <_:example-1/>"
#. (itstool) path: sect1/title
+#: C/index.docbook:488
+msgid "Integration with Autotools"
+msgstr "Integrering med Autotools"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:489
+msgid ""
+"Integration of GTK-Doc into an autotools-based build system requires the "
+"following steps:"
+msgstr ""
+"Integrering av GTK-Doc i ett autotools-baserat byggsystem kräver följande "
+"steg:"
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:495
+msgid ""
+"Ensure that <application>gtkdocize</application> is run once before the "
+"<filename>configure</filename> script. If an <filename>autogen.sh</filename> "
+"script is present, adjust it to check for GTK-Doc and add a call to "
+"<application>gtkdocize</application>."
+msgstr ""
+"Säkerställ att <application>gtkdocize</application> körs en gång innan "
+"skriptet <filename>configure</filename>. Om skriptet <filename>autogen.sh</"
+"filename> finns tillgängligt, justera det så att det söker efter GTK-Doc och "
+"lägg till ett anrop till <application>gtkdocize</application>."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:503
+msgid ""
+"The main purpose of <application>gtkdocize</application> is to make the "
+"<filename>gtk-doc.make</filename> Makefile and the <filename>gtk-doc.m4</"
+"filename> macro definition file available to the build system, either by "
+"copying or linking it into the project."
+msgstr ""
+"Huvudsyftet med <application>gtkdocize</application> är att göra Makefilen "
+"<filename>gtk-doc.make</filename> och makrodefinitionsfilen <filename>gtk-"
+"doc.m4</filename> tillgängliga för byggsystemet, antingen genom att kopiera "
+"eller länka in dem i projektet."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:512
+msgid ""
+"Add the necessary <application>autoconf</application> macros to "
+"<filename>configure.ac</filename> to enable GTK-Doc in your build system to "
+"allow configuration of GTK-Doc via the generated <filename>configure</"
+"filename> script."
+msgstr ""
+"Lägg till de nödvändiga <application>autoconf</application>-makrona till "
+"<filename>configure.ac</filename> för att aktivera GTK-Doc i ditt byggsystem "
+"för att tillåta konfiguration av GTK-Doc via det genererade "
+"<filename>configure</filename>-skriptet."
+
+# TODO: What? Can't parse this one.
+#. (itstool) path: listitem/para
+#: C/index.docbook:518
+msgid ""
+"Among others with registers the <code>--enable-gtk-doc</code> option with "
+"the <filename>configure</filename> script."
+msgstr ""
+"Bland andra med register flaggan <code>--enable-gtk-doc</code> med "
+"<filename>configure</filename>-skriptet."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:524
+msgid ""
+"Create an <application>automake</application> script for each application or "
+"library in your project. In the example used in this documentation this step "
+"applies to both <code>meeper</code> and <code>libmeep</code>."
+msgstr ""
+"Skapa ett <application>automake</application>-skript för varje program eller "
+"bibliotek i ditt projekt. I exemplet som används i denna dokumentation "
+"tillämpas detta steg för både <code>meeper</code> och <code>libmeep</code>."
+
+# TODO: how *TO* enable
+#. (itstool) path: sect1/para
+#: C/index.docbook:533
+msgid ""
+"In the following sections, we will perform the above steps in reverse order. "
+"We start with the <application>automake</application> scripts and work our "
+"way up to <filename>configure.ac</filename> and <filename>autogen.sh</"
+"filename>. Then we show how enable Gtk-Doc in the build system and how to "
+"build the documentation."
+msgstr ""
+"I de följande avsnitten utför vi stegen ovan i omvänd ordning. Vi börjar med "
+"<application>automake</application>-skripten och arbetar vår väg upp till "
+"<filename>configure.ac</filename> och <filename>autogen.sh</filename>. Sedan "
+"visar vi hur Gtk-Doc aktiveras i byggsystemet och hur dokumentationen byggs."
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:543
+msgid "Integration with automake"
+msgstr "Integrering med automake"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:545
+msgid ""
+"First copy the <filename>Makefile.am</filename> from the <filename class="
+"\"directory\">examples</filename> sub-directory of the <ulink url=\"https://"
+"gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am\"> gtkdoc-"
+"sources</ulink> to your project's reference documentation directory (e.g. "
+"<filename class=\"directory\">docs/reference/<package></filename>). A "
+"local copy should be available under e.g. <filename>/usr/share/doc/gtk-doc-"
+"tools/examples/Makefile.am</filename>. If you have multiple packages repeat "
+"this for each one."
+msgstr ""
+"Kopiera först <filename>Makefile.am</filename> från underkatalogen <filename "
+"class=\"directory\">examples</filename> från <ulink url=\"https://gitlab."
+"gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am\">gtkdoc-sources</"
+"ulink> till ditt projekts referensdokumentationskatalog (t.ex. <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 paket, repetera detta för "
+"vart och ett."
+
+#. (itstool) path: note/simpara
+#: C/index.docbook:558
+msgid ""
+"Do not forget to add each <filename>Makefile.am</filename> to the "
+"<function>AC_CONFIG_FILES</function> macro in <filename>configure.ac</"
+"filename>. For <filename>docs/reference/libmeep/Makefile.am</filename> you "
+"will need to add the entry <filename>docs/reference/libmeep/Makefile</"
+"filename> to <function>AC_CONFIG_FILES</function>."
+msgstr ""
+"Glöm inte att lägga till varje <filename>Makefile.am</filename> till makrot "
+"<function>AC_CONFIG_FILES</function> i <filename>configure.ac</filename>. "
+"För <filename>docs/reference/libmeep/Makefile.am</filename> kommer du behöva "
+"lägga till posten <filename>docs/reference/libmeep/Makefile</filename> till "
+"<function>AC_CONFIG_FILES</function>."
+
#. (itstool) path: example/title
-#: C/index.docbook:416 C/index.docbook:423
+#: C/index.docbook:570
+msgid "Example directory structure with <filename>Makefiles.am</filename>"
+msgstr "Exempelkatalogstruktur med <filename>Makefiles.am</filename>"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:573
+#, no-wrap
+msgid ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/ # reference documentation\n"
+" libmeep/\n"
+" Makefile.am\n"
+" meeper/\n"
+" Makefile.am\n"
+" help/ # optional: user manual\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+msgstr ""
+"\n"
+"meep/\n"
+" docs/\n"
+" reference/ # referensdokumentation\n"
+" libmeep/\n"
+" Makefile.am\n"
+" meeper/\n"
+" Makefile.am\n"
+" help/ # valfritt: användarhandbok\n"
+" meeper/\n"
+" src/\n"
+" libmeep/\n"
+" meeper/\n"
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:589
+msgid ""
+"Next, you need to customize the copied Makefiles and provide values for the "
+"various parameters in each <filename>Makefile.am</filename>. All settings "
+"have a comment above them that describes their purpose and how to customize "
+"the setting. Most settings are used to supply extra flags to the respective "
+"tools to which they apply. Every tool has a variable of the form <option><"
+"TOOLNAME>_OPTIONS</option> (e.g. the tool <application>gtkdoc-mkhtml</"
+"application> has an option named <code>MKHTML_OPTIONS</code>). All the tools "
+"support <option>--help</option> to list the supported options."
+msgstr ""
+"Härnäst behöver du anpassa de kopierade Makefilerna och tillhandahålla "
+"värden för de olika parametrarna i varje <filename>Makefile.am</filename>. "
+"Alla inställningarna har en kommentar ovanför som beskriver deras syfte och "
+"hur inställningen kan anpassas. De flesta inställningarna används för att "
+"tillhandahålla extraflaggor till respektive verktyg för vilket de är "
+"aktuella. Varje verktyg har en variabel på formen <option><"
+"VERKTYGSNAMN>_OPTIONS</option> (t.ex. har verktyget <application>gtkdoc-"
+"mkhtml</application> en flagga med namnet <code>MKHTML_OPTIONS</code>). Alla "
+"verktygen har stöd för <option>--help</option> för att lista de flaggor som "
+"stöds."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:613
+msgid ""
+"<option>DOC_MODULE</option> is used to provide the name of the package that "
+"is being documentated (e.g. <code>meeper</code>, or <code>libmeep</code>)."
+msgstr ""
+"<option>DOC_MODULE</option> används för att tillhandahålla namnet på paketet "
+"som dokumenteras (t.ex. <code>meeper</code> eller <code>libmeep</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:620
+msgid ""
+"<option>DOC_SOURCE_DIR</option> is used to specify the location of source "
+"directory which GTK-Doc searches for your API documentation. This will "
+"usually be <code> DOC_SOURCE_DIR=$(top_srcdir)/src </code> or a sub-"
+"directory of that directory."
+msgstr ""
+"<option>DOC_SOURCE_DIR</option> används för att ange platsen för "
+"källkatalogen där GTK-Doc söker efter din API-dokumentation. Detta kommer "
+"vanligen vara <code> DOC_SOURCE_DIR=$(top_srcdir)/src </code> eller en "
+"underkatalog till den katalogen."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:633
+msgid ""
+"<option>HFILE_GLOB</option> and <option>CFILE_GLOB</option> are used for "
+"dependencies. Each option take a file-glob (e.g. <code>HFILE_GLOB="
+"$(top_srcdir)/src/*.c</code>). The documentation will be rebuilt if any of "
+"the matched files change."
+msgstr ""
+"<option>HFILE_GLOB</option> och <option>CFILE_GLOB</option> används för "
+"beroenden. Varje flagga tar en file-glob (t.ex. <code>HFILE_GLOB="
+"$(top_srcdir)/src/*.c</code>). Dokumentationen kommer att byggas om ifall "
+"någon av de matchande filerna ändras."
+
+# TODO: (top_srcdir)
+#. (itstool) path: listitem/para
+#: C/index.docbook:645
+msgid ""
+"<option>EXTRA_HFILES</option> allows to specify extra header files to "
+"include when scanning for API documentation, which are not found under "
+"<code>DOC_SOURCE_DIR</code> (e.g. <code> EXTRA_HFILES=$(top_srcdir}/contrib/"
+"extra.h</code>)."
+msgstr ""
+"<option>EXTRA_HFILES</option> låter dig ange extra huvudfiler som ska "
+"inkluderas då API-dokumentation eftersöks, vilka inte hittas under "
+"<code>DOC_SOURCE_DIR</code> (t.ex. <code> EXTRA_HFILES=$(top_srcdir}/contrib/"
+"extra.h</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:655
+msgid ""
+"<option>IGNORE_HFILES</option> allows to specify header files or directories "
+"to ignore when scanning for API documentation. Use the basename of the file "
+"or directory (e.g. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h "
+"private_code_folder</code>)."
+msgstr ""
+"<option>IGNORE_HFILES</option> låter dig ange huvudfiler eller kataloger som "
+"ska ignoreras då API-dokumentation eftersöks. Använd basnamnet på filen "
+"eller katalogen (t.ex. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h "
+"private_code_folder</code>)."
+
+# TODO: *image files*
+#. (itstool) path: listitem/para
+#: C/index.docbook:665
+msgid ""
+"<option>HTML_IMAGES</option> allows to specify images files which will be "
+"copied into the <filename>html/</filename> directory of the generated "
+"documentation. If your API documentation includes any images they need to be "
+"added to this option (e.g. <code> HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/"
+"stock_about_24.png</code>)."
+msgstr ""
+"<option>HTML_IMAGES</option> låter dig ange bildfiler som kommer att "
+"kopieras till katalogen <filename>html/</filename> av den genererade "
+"dokumentationen. Om din API-dokumentation inkluderar några bilder behöver de "
+"läggas till i denna flagga (t.ex. <code> HTML_IMAGES=$(top_srcdir)/gtk/stock-"
+"icons/stock_about_24.png</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:678
+msgid ""
+"<option>content_files</option> allows to specify extra files that are "
+"included by <code>$(DOC_MAIN_SGML_FILE)</code> (e.g. <code> "
+"content_files=running.xml building.xml changes-2.0.xml</code>)."
+msgstr ""
+"<option>content_files</option> låter dig ange extrafiler som inkluderas av "
+"<code>$(DOC_MAIN_SGML_FILE)</code> (t.ex. <code> content_files=running.xml "
+"building.xml changes-2.0.xml</code>)."
+
+#. (itstool) path: listitem/para
+#: C/index.docbook:689
+msgid ""
+"<option>expand_content_files</option> allows to specify files where "
+"<emphasis>gtk-doc abbreviations</emphasis> such as <code>#GtkWidget</code> "
+"are expanded (e.g. <code> expand_content_files=running.xml</code>)."
+msgstr ""
+"<option>expand_content_files</option> låter dig ange filer där <emphasis>gtk-"
+"doc-förkortningar</emphasis> så som <code>#GtkWidget</code> expanderas (t."
+"ex. <code> expand_content_files=running.xml</code>)."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:607
+msgid ""
+"The following list explains the most relevant options. Check the example "
+"<filename>Makefile.am</filename> for additional options. <_:itemizedlist-1/>"
+msgstr ""
+"Följande lista förklarar de mest relevanta flaggorna. Se <filename>Makefile."
+"am</filename>-exemplet för ytterligare flaggor. <_:itemizedlist-1/>"
+
+#. (itstool) path: sect2/title
+#: C/index.docbook:704
msgid "Integration with autoconf"
msgstr "Integrering med autoconf"
-#. (itstool) path: sect1/para
-#: C/index.docbook:418
+#. (itstool) path: sect2/para
+#: C/index.docbook:706
+msgid ""
+"Integration with <application>autoconf</application> is very simple and "
+"includes one required step and an additional optional (but recommended) "
+"step. The first step is to add the <function>GTK_DOC_CHECK</function> macro "
+"to your <filename>configure.ac</filename> script. This registers several "
+"configure options to enable GTK-Doc and allows you to set default arguments "
+"for <application>gtkdocize</application>."
+msgstr ""
+"Integrering med <application>autoconf</application> är väldigt enkel och "
+"inkluderar ett obligatoriskt steg och ett ytterligare valfritt (men "
+"rekommenderat) steg. Det första steget är att lägga till "
+"<function>GTK_DOC_CHECK</function>-makrot till ditt <filename>configure.ac</"
+"filename>-skript. Detta registrerar flera konfigurationsflaggor för att "
+"aktivera GTK-Doc och låter dig ställa in standardargument för "
+"<application>gtkdocize</application>."
+
+#. (itstool) path: warning/simpara
+#: C/index.docbook:718
msgid ""
-"Very easy! Just add one line to your <filename>configure.ac</filename> "
-"script."
+"Make sure that the <code>GTK_DOC_CHECK</code> macro is not indented. The "
+"macro must start at the beginning of the line and should not start with "
+"whitespace."
msgstr ""
-"Väldigt enkelt! Bara lägg till en rad till ditt <filename>configure.ac</"
-"filename>-skript."
+"Säkerställ att makrot <code>GTK_DOC_CHECK</code> inte är indenterat. Makrot "
+"måste inledas på början av raden och får inte börja med blanktecken."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:725
+msgid ""
+"The second step is to add the <code>AC_CONFIG_MACRO_DIR(m4)</code> to your "
+"<filename>configure.ac</filename>. This is not required but helps "
+"<application>gtkdocize</application> to automatically copy the macro "
+"definition (e.g <filename>gtk-doc.m4</filename>) which contains the "
+"<function>GTK_DOC_CHECK</function> macro to your project's macro directory. "
+"Without this, the GTK_DOC_CHECK macro might not be found and you would need "
+"to explicitly tell the <application>aclocal</application> tool where to find "
+"the macro definition file."
+msgstr ""
+"Det andra steget är att lägga till <code>AC_CONFIG_MACRO_DIR(m4)</code> till "
+"din <filename>configure.ac</filename>. Detta krävs inte men hjälper "
+"<application>gtkdocize</application> att automatiskt kopiera "
+"makrodefinitionen (t.ex. <filename>gtk-doc.m4</filename>) som innehåller "
+"<function>GTK_DOC_CHECK</function>-makrot till ditt projekts makrokatalog. "
+"Utan detta kanske GTK_DOC_CHECK-makrot inte hittas och du skulle behöva "
+"explicit berätta för <application>aclocal</application>-verktyget var "
+"makrodefinitionsfilen kan hittas."
+
+#. (itstool) path: example/title
+#: C/index.docbook:738
+msgid "Minimal integration with autoconf"
+msgstr "Minimal integrering med autoconf"
#. (itstool) path: example/programlisting
-#: C/index.docbook:424
+#: C/index.docbook:739
#, no-wrap
msgid ""
"\n"
-"# check for gtk-doc\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\n"
msgstr ""
"\n"
-"# check for gtk-doc\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# rekommenderat: ställ in m4-katalog\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# valfritt: registrera gtk-doc i configure\n"
+"GTK_DOC_CHECK([1.28])\n"
#. (itstool) path: example/title
-#: C/index.docbook:436
-msgid "Keep gtk-doc optional"
-msgstr "Låt gtk-doc vara valfritt"
+#: C/index.docbook:754
+msgid "Integration with optional gtk-doc dependency"
+msgstr "Integrering med valfritt gtk-doc-beroende"
#. (itstool) path: example/programlisting
-#: C/index.docbook:437
+#: C/index.docbook:755
#, no-wrap
msgid ""
"\n"
-"# check for gtk-doc\n"
"m4_ifdef([GTK_DOC_CHECK], [\n"
-"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n"
+"# recommended: set m4 directory\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# optional: register gtk-doc in configure\n"
+"GTK_DOC_CHECK([1.28])\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"
+"# rekommenderat: ställ in m4-katalog\n"
+"AC_CONFIG_MACRO_DIR(m4)\n"
+"# valfritt: registrera gtk-doc i configure\n"
+"GTK_DOC_CHECK([1.28])\n"
"],[\n"
"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n"
"])\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:431
+#. (itstool) path: sect2/para
+#: C/index.docbook:748
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/>"
+"The above example works, but will require all developers to have gtk-doc "
+"installed. A better way is to make building the documentation optional as "
+"shown in the next example: <_:example-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/>"
+"Exemplet ovan fungerar, men skulle kräva att alla utvecklare har gtk-doc "
+"installerat. Ett bättre sätt är att göra byggande av dokumentationen "
+"valfritt på det sätt som visas i nästa exempel: <_:example-1/>"
# sebras: <function> or <symbol>?
-#. (itstool) path: sect1/para
-#: C/index.docbook:448
+#. (itstool) path: sect2/para
+#: C/index.docbook:768
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:"
+"The first argument is used to check for the Gtk-Doc version at configure "
+"time. The 2nd, optional argument is used by <application>gtkdocize</"
+"application>. The <symbol>GTK_DOC_CHECK</symbol> macro also adds several "
+"configure switches:"
msgstr ""
-"Det första argumentet används för att leta efter gtkdoc-versionen under "
+"Det första argumentet används för att leta efter Gtk-Doc-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:454
+#: C/index.docbook:777
msgid "--with-html-dir=PATH : path to installed docs"
msgstr "--with-html-dir=SÖKVÄG : sökväg till installerad dokumentation"
#. (itstool) path: listitem/para
-#: C/index.docbook:455
+#: C/index.docbook:778
msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]"
msgstr ""
"--enable-gtk-doc : använd gtk-doc för att bygga dokumentation "
"[standardvärde=no]"
#. (itstool) path: listitem/para
-#: C/index.docbook:456
+#: C/index.docbook:779
msgid ""
"--enable-gtk-doc-html : build documentation in html format [default=yes]"
msgstr ""
"--enable-gtk-doc-html : bygg dokumentation i html-format [standardvärde=yes]"
#. (itstool) path: listitem/para
-#: C/index.docbook:457
+#: C/index.docbook:780
msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]"
msgstr ""
"--enable-gtk-doc-pdf : bygg dokumentation i pdf-format [standardvärde=no]"
#. (itstool) path: important/para
-#: C/index.docbook:461
+#: C/index.docbook:784
msgid ""
"GTK-Doc is disabled by default! Remember to pass the option <option>'--"
"enable-gtk-doc'</option> to the next <filename>configure</filename> run. "
"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:469
-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:477
-msgid "Preparation for gtkdocize"
-msgstr "Förberedelse för gtkdocize"
-
-#. (itstool) path: example/programlisting
-#: C/index.docbook:478
-#, 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:483
+#. (itstool) path: sect2/para
+#: C/index.docbook:792
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>."
+"<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>."
-
-#. (itstool) path: sect1/title
-#: C/index.docbook:491
-msgid "Integration with automake"
-msgstr "Integrering med automake"
+"köra om <code>autogen.sh</code>."
-#. (itstool) path: sect1/para
-#: C/index.docbook:493
-msgid ""
-"First copy the <filename>Makefile.am</filename> from the <filename class="
-"\"directory\">examples</filename> sub directory of the <ulink url=\"https://"
-"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:504
-msgid ""
-"The next step is to edit the settings inside the <filename>Makefile.am</"
-"filename>. All the settings have a comment above that describes their "
-"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:518
+#. (itstool) path: sect2/title
+#: C/index.docbook:800
msgid "Integration with autogen"
msgstr "Integrering med autogen"
-#. (itstool) path: sect1/para
-#: C/index.docbook:520
+#. (itstool) path: sect2/para
+#: C/index.docbook:802
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."
+"the build infrastructure after the project was checked out from a version "
+"control system (such as git or svn). GTK-Doc comes with a script called "
+"<application>gtkdocize</application> which can be used to copy the necessary "
+"files needed by Gtk-Doc to the source directory."
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."
+"versionshanteringssystem (så som git eller svn). GTK-Doc kommer med ett "
+"skript som heter <application>gtkdocize</application> som kan användas för "
+"att kopiera nödvändiga filer som behövs av Gtk-Doc till källkatalogen."
+
+#. (itstool) path: sect2/para
+#: C/index.docbook:810
+msgid "It should be run before autoreconf, autoheader, automake or autoconf."
+msgstr "Det bör köras före autoreconf, autoheader, automake eller autoconf."
#. (itstool) path: example/title
-#: C/index.docbook:529
+#: C/index.docbook:815
msgid "Running gtkdocize from autogen.sh"
msgstr "Köra gtkdocize från autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:530
+#: C/index.docbook:816
#, no-wrap
msgid ""
"\n"
"\n"
"gtkdocize || exit 1\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:536
-msgid ""
-"When running <application>gtkdocize</application> it copies <filename>gtk-"
-"doc.make</filename> to your project root (or any directory specified by the "
-"<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:545
-msgid ""
-"Historically GTK-Doc was generating template files where developers entered "
-"the docs. This turned out to be not so good (e.g. the need for having "
-"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:562 C/index.docbook:579
-msgid "Running the doc build"
-msgstr "Att köra dokumentationsbygget"
-
-#. (itstool) path: sect1/para
-#: C/index.docbook:564
-msgid ""
-"After the previous steps it's time to run the build. First we need to rerun "
-"<filename>autogen.sh</filename>. If this script runs configure for you, then "
-"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:571
-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>."
+#: C/index.docbook:824
+msgid "Conditionally run gtkdocize from autogen.sh"
+msgstr "Köra gtkdocize villkorligt från autogen.sh"
#. (itstool) path: example/programlisting
-#: C/index.docbook:580
+#: C/index.docbook:825
#, no-wrap
msgid ""
"\n"
-"./autogen.sh --enable-gtk-doc\n"
-"make\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+" echo \"No gtk-doc support found. You can't build the docs.\"\n"
+"else\n"
+" $GTKDOCIZE || exit 1\n"
+"fi\n"
msgstr ""
"\n"
-"./autogen.sh --enable-gtk-doc\n"
-"make\n"
+"GTKDOCIZE=$(which gtkdocize 2>/dev/null)\n"
+"if test $? -ne 0; then\n"
+" echo \"Inget gtk-doc-stöd funnet. Du kan inte bygga dokumentationen.\"\n"
+"else\n"
+" $GTKDOCIZE || exit 1\n"
+"fi\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:586
+#. (itstool) path: sect2/para
+#: C/index.docbook:836
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."
+"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)."
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."
-
-#. (itstool) path: sect1/title
-#: C/index.docbook:594
-msgid "Integration with version control systems"
-msgstr "Integrering med versionshanteringssystem"
+"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>)."
-#. (itstool) path: sect1/para
-#: C/index.docbook:596
-msgid ""
-"As a rule of thumb, it's the files you edit which should go under version "
-"control. For typical projects it's these files: <filename><package>."
-"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>."
+# TODO: Strange last sentence
+#. (itstool) path: sect2/para
+#: C/index.docbook:842
+msgid ""
+"<application>gtkdocize</application> checks your <filename>configure.ac</"
+"filename> script for the <function>GTK_DOC_CHECK</function> macro. The "
+"<function>GTK_DOC_CHECK</function> macro can be used to pass extra arguments "
+"to the <application>gtkdocize</application> script. the 2nd parameter in the "
+"<function>GTK_DOC_CHECK</function> macro."
+msgstr ""
+"<application>gtkdocize</application> söker i ditt <filename>configure.ac</"
+"filename>-skript efter makrot <function>GTK_DOC_CHECK</function>. Makrot "
+"<function>GTK_DOC_CHECK</function> kan användas för att skicka extra "
+"argument till skriptet <application>gtkdocize</application>. den andra "
+"parametern i <function>GTK_DOC_CHECK</function>-makrot."
-#. (itstool) path: sect1/para
-#: C/index.docbook:604
+#. (itstool) path: sect2/para
+#: C/index.docbook:851
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."
+"Alternatively, additional arguments can also be passed to "
+"<application>gtkdocize</application> via the <function>GTKDOCIZE_FLAGS</"
+"function> environment variable, or by directly specifying them to "
+"<application>gtkdocize</application> in <filename>autogen.sh</filename>."
msgstr ""
-"Filer i katalogerna <filename>xml/</filename> och <filename>html/</filename> "
-"bör inte versionshanteras. Detsamma gäller <filename>.stamp</filename>-"
-"filerna."
+"Alternativt kan ytterligare argument också skickas till "
+"<application>gtkdocize</application> via miljövariabeln "
+"<function>GTKDOCIZE_FLAGS</function>, eller genom att ange dem direkt till "
+"<application>gtkdocize</application> i <filename>autogen.sh</filename>."
-#. (itstool) path: sect1/title
-#: C/index.docbook:612
-msgid "Integration with plain makefiles or other build systems"
-msgstr "Integrering med vanliga makefiler eller andra byggsystem"
+#. (itstool) path: sect2/title
+#: C/index.docbook:862
+msgid "Executing GTK-Doc from the Build System"
+msgstr "Köra GTK-Doc från byggsystemet"
-#. (itstool) path: sect1/para
-#: C/index.docbook:614
+#. (itstool) path: sect2/para
+#: C/index.docbook:864
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)."
+"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 ""
-"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)."
+"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: sect2/para
+#: C/index.docbook:871
+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/title
-#: C/index.docbook:621
-msgid "Documentation build steps"
-msgstr "Byggsteg för dokumentation"
+#: C/index.docbook:879
+msgid "Running the doc build"
+msgstr "Att köra dokumentationsbygget"
#. (itstool) path: example/programlisting
-#: C/index.docbook:622
+#: C/index.docbook:880
#, 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"
+"./autogen.sh --enable-gtk-doc\n"
+"make\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"
+"./autogen.sh --enable-gtk-doc\n"
+"make\n"
-#. (itstool) path: sect1/para
-#: C/index.docbook:636
+#. (itstool) path: sect2/para
+#: C/index.docbook:887
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."
+"Now you can point your browser to <filename>docs/reference/<package>/"
+"index.html</filename>. With this initial setup you will only see a very "
+"simple document. The next chapter will teach you how to add API "
+"documentation to your code via special comment blocks. The Chapter "
+"afterwards introduces <link linkend=\"metafiles\">additional files</link> "
+"and shows how to edit the <link linkend=\"metafiles_master\">master "
+"template</link> to add additional chapters and sections to your "
+"documentation files."
+msgstr ""
+"Nu kan du peka din webbläsare till <filename>docs/reference/<paket>/"
+"index.html</filename>. Med denna ursprungliga konfiguration kommer du bara "
+"se ett väldigt enkelt dokument. Nästa kapitel kommer att lära dig hur du "
+"lägger till API-dokumentation till din kod via speciella kommentarsblock. "
+"Kapitlet efteråt introducerar <link linkend=\"metafiles\">ytterligare filer</"
+"link> och visar hur <link linkend=\"metafiles_master\">huvudmallen</link> "
+"redigeras för att lägga till ytterligare kapitel och avsnitt till dina "
+"dokumentationsfiler."
#. (itstool) path: sect1/title
-#: C/index.docbook:643
+#: C/index.docbook:903
msgid "Integration with CMake build systems"
msgstr "Integrering med CMake-byggsystem"
#. (itstool) path: sect1/para
-#: C/index.docbook:645
+#: C/index.docbook:905
msgid ""
"GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module (and "
"the corresponding <filename>GtkDocConfigVersion.cmake</filename> module). "
"kommando som du kan ställa in i din <filename>CMakeLists.txt</filename>-fil."
#. (itstool) path: example/title
-#: C/index.docbook:655
+#: C/index.docbook:915
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:656
+#: C/index.docbook:916
#, no-wrap
msgid ""
"\n"
" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:653
+#: C/index.docbook:913
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: sect1/title
+#: C/index.docbook:940
+msgid "Integration with plain makefiles or other build systems"
+msgstr "Integrering med vanliga makefiler eller andra byggsystem"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:942
+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:949
+msgid "Documentation build steps"
+msgstr "Byggsteg för dokumentation"
+
+#. (itstool) path: example/programlisting
+#: C/index.docbook:950
+#, 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:964
+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."
+
+#. (itstool) path: sect1/title
+#: C/index.docbook:971
+msgid "Integration with version control systems"
+msgstr "Integrering med versionshanteringssystem"
+
+#. (itstool) path: sect1/para
+#: C/index.docbook:973
+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:981
+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."
+
#. (itstool) path: chapter/title
-#: C/index.docbook:681
+#: C/index.docbook:991
msgid "Documenting the code"
msgstr "Att dokumentera koden"
#. (itstool) path: chapter/para
-#: C/index.docbook:683
+#: C/index.docbook:993
msgid ""
"GTK-Doc uses source code comment with a special syntax for code "
"documentation. Further it retrieves information about your project structure "
"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:691
-msgid "Documentation placement"
-msgstr "Dokumentationsplacering"
-
-#. (itstool) path: note/para
-#: C/index.docbook:692
-msgid ""
-"In the past most documentation had to be filled into files residing inside "
-"the <filename>tmpl</filename> directory. This has the disadvantages that the "
-"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:698
-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:709 C/index.docbook:735
+#: C/index.docbook:1004 C/index.docbook:1030
msgid "GTK-Doc comment block"
msgstr "GTK-Doc-kommentarsblock"
#. (itstool) path: example/programlisting
-#: C/index.docbook:710
+#: C/index.docbook:1005
#, no-wrap
msgid ""
"\n"
"#endif\n"
#. (itstool) path: chapter/para
-#: C/index.docbook:705
+#: C/index.docbook:1000
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/>"
+"The GTK-Doc scanner can handle the majority of C headers fine. In the case "
+"of receiving warnings from the scanner that look like a special case, one "
+"can hint GTK-Doc to skip over them. <_:example-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/>"
+"GTK-Doc-detektorn kan hantera majoriteten av C-huvuden bra. I det fall när "
+"du får varningar från detektorn som ser ut som ett specialfall, kan du tipsa "
+"GTK-Doc att hoppa över dem. <_:example-1/>"
#. (itstool) path: note/title
-#: C/index.docbook:719
+#: C/index.docbook:1014
msgid "Limitations"
msgstr "Begränsningar"
# sebras: no 's in the original
#. (itstool) path: note/para
-#: C/index.docbook:720
+#: C/index.docbook:1015
msgid ""
"Note, that GTK-Doc's supports <code>#ifndef(__GTK_DOC_IGNORE__)</code> but "
"not <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations."
"inte <code>#if !defined(__GTK_DOC_IGNORE__)</code> eller andra kombinationer."
#. (itstool) path: sect1/title
-#: C/index.docbook:730
+#: C/index.docbook:1025
msgid "Documentation comments"
msgstr "Dokumentationskommentarer"
#. (itstool) path: example/programlisting
-#: C/index.docbook:736
+#: C/index.docbook:1031
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:732
+#: C/index.docbook:1027
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:1040
msgid ""
"The 'identifier' is one line with the name of the item the comment is "
"related to. The syntax differs a little depending on the item. (TODO add "
"till tabell som visar identifierare)"
#. (itstool) path: sect1/para
-#: C/index.docbook:751
+#: C/index.docbook:1046
msgid ""
"The 'documentation' block is also different for each symbol type. Symbol "
"types that get parameters such as functions or macros have the parameter "
"användbart i förformaterad text (kodlistningar)."
#. (itstool) path: listitem/para
-#: C/index.docbook:768
+#: C/index.docbook:1063
msgid ""
"What it is: The name for a class or function can sometimes be misleading for "
"people coming from a different background."
"vilseledande för personer med annan bakgrund."
#. (itstool) path: listitem/para
-#: C/index.docbook:774
+#: C/index.docbook:1069
msgid ""
"What it does: Tell about common uses. Put it in relation with the other API."
msgstr ""
"det andra API:t."
#. (itstool) path: tip/para
-#: C/index.docbook:764
+#: C/index.docbook:1059
msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>"
msgstr "När du dokumenterar kod, beskriv två aspekter: <_:itemizedlist-1/>"
#. (itstool) path: listitem/para
-#: C/index.docbook:789
+#: C/index.docbook:1084
msgid "Use function() to refer to functions or macros which take arguments."
msgstr ""
"Använd funktion() för att referera till funktioner eller makron som tar "
"argument."
#. (itstool) path: listitem/para
-#: C/index.docbook:794
+#: C/index.docbook:1089
msgid ""
"Use @param to refer to parameters. Also use this when referring to "
"parameters of other functions, related to the one being described."
"beskrivs."
#. (itstool) path: listitem/para
-#: C/index.docbook:800
+#: C/index.docbook:1095
msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS."
msgstr ""
"Använd %konstant för att referera till en konstant, t.ex. %G_TRAVERSE_LEAFS."
#. (itstool) path: listitem/para
-#: C/index.docbook:805
+#: C/index.docbook:1100
msgid ""
"Use #symbol to refer to other types of symbol, e.g. structs and enums and "
"macros which don't take arguments."
"strukturer eller uppräkningar och makron som inte tar argument."
#. (itstool) path: listitem/para
-#: C/index.docbook:811
+#: C/index.docbook:1106
msgid "Use #Object::signal to refer to a GObject signal."
msgstr "Använd #Objekt::signal för att referera till en GObject-signal."
#. (itstool) path: listitem/para
-#: C/index.docbook:816
+#: C/index.docbook:1111
msgid "Use #Object:property to refer to a GObject property."
msgstr "Använd #Objekt:egenskap för att referera till en GObject-egenskap."
#. (itstool) path: listitem/para
-#: C/index.docbook:821
+#: C/index.docbook:1116
msgid ""
"Use #Struct.field to refer to a field inside a structure and #GObjectClass."
"foo_bar() to refer to a vmethod."
"#GObjectKlass.foo_bar() för att referera till en virtuell metod."
#. (itstool) path: sect1/para
-#: C/index.docbook:783
+#: C/index.docbook:1078
msgid ""
"One advantage of hyper-text over plain-text is the ability to have links in "
"the document. Writing the correct markup for a link can be tedious though. "
"förkortningar. <_:itemizedlist-1/>"
#. (itstool) path: tip/para
-#: C/index.docbook:830
+#: C/index.docbook:1125
msgid ""
"If you need to use the special characters '<', '>', '()', '@', '%', or "
"'#' in your documentation without GTK-Doc changing them you can use the XML "
"kontrollsekvensen ”\\”."
#. (itstool) path: sect1/para
-#: C/index.docbook:839
+#: C/index.docbook:1134
msgid ""
"DocBook can do more than just links. One can also have lists, examples, "
"headings, and images. As of version 1.20, the preferred way is to use a "
"ett bindestreck."
#. (itstool) path: sect1/para
-#: C/index.docbook:850
+#: C/index.docbook:1145
msgid ""
"While markdown is now preferred one can mix both. One limitation here is "
"that one can use docbook xml within markdown, but markdown within docbook "
"inte."
#. (itstool) path: sect1/para
-#: C/index.docbook:856
+#: C/index.docbook:1151
msgid ""
"In older GTK-Doc releases, if you need support for additional formatting, "
"you would need to enable the usage of docbook XML tags inside doc-comments "
# sebras: markdown or Markdown?
#. (itstool) path: example/title
-#: C/index.docbook:865
+#: C/index.docbook:1160
msgid "GTK-Doc comment block using Markdown"
msgstr "GTK-Doc-kommentarsblock som använder Markdown"
#. (itstool) path: example/programlisting
-#: C/index.docbook:866
+#: C/index.docbook:1161
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:905
+#: C/index.docbook:1200
msgid ""
"More examples of what markdown tags are supported can be found in the <ulink "
"url=\"https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown"
"\">Referensen för GTK+-dokumentationens markdown-syntax</ulink>."
#. (itstool) path: tip/para
-#: C/index.docbook:911
+#: C/index.docbook:1206
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."
+"comment those symbols too. This helps other developers to understand your "
+"code. Therefore we recommend to comment these using normal comments (without "
+"the 2nd '*' in the first line). If later the function needs to be made "
+"public, all one needs to do is to add another '*' in the comment block and "
+"insert the symbol name at the right place inside the sections file."
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 "
+"bra att kommentera även dessa symboler. Det hjälper andra utvecklare att "
+"förstå din kod. Därför rekommenderar vi att du kommenterar dessa med normala "
+"kommentarer (utan den andra ”*” på den första raden). Om funktionen vid ett "
+"senare tillfälle måste göras publik är allt du behöver göra att lägga till "
"ytterligare en ”*” i kommentarsblocket och infoga symbolnamnet på rätt "
"ställe i avsnittsfilen."
#. (itstool) path: sect1/title
-#: C/index.docbook:925
+#: C/index.docbook:1221
msgid "Documenting sections"
msgstr "Dokumentationsavsnitt"
#. (itstool) path: sect1/para
-#: C/index.docbook:927
+#: C/index.docbook:1223
msgid ""
"Each section of the documentation contains information about one class or "
"module. To introduce the component one can write a section block. The short "
"valfria."
#. (itstool) path: example/title
-#: C/index.docbook:935
+#: C/index.docbook:1231
msgid "Section comment block"
msgstr "Kommentarsblock för avsnitt"
#. (itstool) path: example/programlisting
-#: C/index.docbook:936
+#: C/index.docbook:1232
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:955
+#: C/index.docbook:1251
msgid "SECTION:<name>"
msgstr "SECTION:<namn>"
#. (itstool) path: listitem/para
-#: C/index.docbook:957
+#: C/index.docbook:1253
msgid ""
"The name links the section documentation to the respective part in the "
"<filename><package>-sections.txt</filename> file. The name given here "
"filename>."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:966
+#: C/index.docbook:1262
msgid "@short_description"
msgstr "@short_description"
#. (itstool) path: listitem/para
-#: C/index.docbook:968
+#: C/index.docbook:1264
msgid ""
"A one line description of the section, that later will appear after the "
"links in the TOC and at the top of the section page."
"innehållsförteckningen och lägst upp på avsnittssidan."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:975
+#: C/index.docbook:1271
msgid "@title"
msgstr "@title"
#. (itstool) path: listitem/para
-#: C/index.docbook:977
+#: C/index.docbook:1273
msgid ""
"The section title defaults to <name> from the SECTION declaration. It "
"can be overridden with the @title field."
"kan åsidosättas med fältet @title."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:984
+#: C/index.docbook:1280
msgid "@section_id"
msgstr "@section_id"
#. (itstool) path: listitem/para
-#: C/index.docbook:986
+#: C/index.docbook:1282
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:1290
msgid "@see_also"
msgstr "@see_also"
#. (itstool) path: listitem/para
-#: C/index.docbook:996
+#: C/index.docbook:1292
msgid "A list of symbols that are related to this section."
msgstr "En lista över symboler som är relaterade till detta avsnitt."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1002
+#: C/index.docbook:1298
msgid "@stability"
msgstr "@stability"
#. (itstool) path: listitem/para
-#: C/index.docbook:1009
+#: C/index.docbook:1305
msgid ""
"Stable - The intention of a Stable interface is to enable arbitrary third "
"parties to develop applications to these interfaces, release them, and have "
"motiverade."
#. (itstool) path: listitem/para
-#: C/index.docbook:1021
+#: C/index.docbook:1317
msgid ""
"Unstable - Unstable interfaces are experimental or transitional. They are "
"typically used to give outside developers early access to new or rapidly "
"programfixversion till nästa."
#. (itstool) path: listitem/para
-#: C/index.docbook:1033
+#: C/index.docbook:1329
msgid ""
"Private - An interface that can be used within the GNOME stack itself, but "
"that is not documented for end-users. Such functions should only be used in "
"på angivna och dokumenterade sätt."
#. (itstool) path: listitem/para
-#: C/index.docbook:1042
+#: C/index.docbook:1338
msgid ""
"Internal - An interface that is internal to a module and does not require "
"end-user documentation. Functions that are undocumented are assumed to be "
"interna."
#. (itstool) path: listitem/para
-#: C/index.docbook:1004
+#: C/index.docbook:1300
msgid ""
"An informal description of the stability level this API has. We recommend "
"the use of one of these terms: <_:itemizedlist-1/>"
"att använda en av dessa termer: <_:itemizedlist-1/>"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1054
+#: C/index.docbook:1350
msgid "@include"
msgstr "@include"
#. (itstool) path: listitem/para
-#: C/index.docbook:1056
+#: C/index.docbook:1352
msgid ""
"The <literal>#include</literal> files to show in the section synopsis (a "
"comma separated list), overriding the global value from the <link linkend="
"Detta objekt är valfritt."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1065
+#: C/index.docbook:1361
msgid "@image"
msgstr "@image"
#. (itstool) path: listitem/para
-#: C/index.docbook:1067
+#: C/index.docbook:1363
msgid ""
"The image to display at the top of the reference page for this section. This "
"will often be some sort of a diagram to illustrate the visual appearance of "
"klasser. Detta objekt är valfritt."
#. (itstool) path: tip/para
-#: C/index.docbook:1078
+#: C/index.docbook:1374
msgid ""
"To avoid unnecessary recompilation after doc-changes put the section docs "
"into the c-source where possible."
"avsnittsdokumentationen i c-källkoden där möjligt."
#. (itstool) path: sect1/title
-#: C/index.docbook:1087
+#: C/index.docbook:1383
msgid "Documenting symbols"
msgstr "Dokumentationssymboler"
#. (itstool) path: sect1/para
-#: C/index.docbook:1089
+#: C/index.docbook:1385
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:1393 C/index.docbook:1459
msgid "General tags"
msgstr "Generella taggar"
#. (itstool) path: sect2/para
-#: C/index.docbook:1099
+#: C/index.docbook:1395
msgid ""
"You can add versioning information to all documentation elements to tell "
"when an API was introduced, or when it was deprecated."
"att berätta när ett API introducerats eller blev föråldrat."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1104
+#: C/index.docbook:1400
msgid "Versioning Tags"
msgstr "Versioneringstaggar"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1105
+#: C/index.docbook:1401
msgid "Since:"
msgstr "Since:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1107
+#: C/index.docbook:1403
msgid "Description since which version of the code the API is available."
msgstr ""
"Beskrivning över från och med vilken version av koden som API:t är "
"tillgängligt."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1112
+#: C/index.docbook:1408
msgid "Deprecated:"
msgstr "Deprecated:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1114
+#: C/index.docbook:1410
msgid ""
"Paragraph denoting that this function should no be used anymore. The "
"description should point the reader to the new API."
"Beskrivningen bör peka läsaren vidare till det nya API:t."
#. (itstool) path: sect2/para
-#: C/index.docbook:1122
+#: C/index.docbook:1418
msgid ""
"You can also add stability information to all documentation elements to "
"indicate whether API stability is guaranteed for them for all future minor "
"för dem för alla framtida programfix-versioner av projektet."
#. (itstool) path: sect2/para
-#: C/index.docbook:1128
+#: C/index.docbook:1424
msgid ""
"The default stability level for all documentation elements can be set by "
"passing the <option>--default-stability</option> argument to "
"till <application>gtkdoc-mkdb</application> med endera av värdena nedan."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1134
+#: C/index.docbook:1430
msgid "Stability Tags"
msgstr "Stabilitetstaggar"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1135
+#: C/index.docbook:1431
msgid "Stability: Stable"
msgstr "Stability: Stable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1137
+#: C/index.docbook:1433
msgid ""
"Mark the element as stable. This is for public APIs which are guaranteed to "
"remain stable for all future minor releases of the project."
"projektet."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1144
+#: C/index.docbook:1440
msgid "Stability: Unstable"
msgstr "Stability: Unstable"
#. (itstool) path: listitem/para
-#: C/index.docbook:1146
+#: C/index.docbook:1442
msgid ""
"Mark the element as unstable. This is for public APIs which are released as "
"a preview before being stabilised."
"på förhand innan de blivit stabiliserade."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1152
+#: C/index.docbook:1448
msgid "Stability: Private"
msgstr "Stability: Private"
#. (itstool) path: listitem/para
-#: C/index.docbook:1154
+#: C/index.docbook:1450
msgid ""
"Mark the element as private. This is for interfaces which can be used by "
"tightly coupled modules, but not by arbitrary third parties."
"av tätt sammankopplade moduler, men inte av godtyckliga tredje parter."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1164
+#: C/index.docbook:1460
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1184 C/index.docbook:1194
+#: C/index.docbook:1480 C/index.docbook:1490
msgid "Annotations"
msgstr "Noteringar"
# sebras: was it called verkygstips? verktygshjälp? I forget...
#. (itstool) path: sect2/para
-#: C/index.docbook:1186
+#: C/index.docbook:1482
msgid ""
"Documentation blocks can contain annotation-tags. These tags will be "
"rendered with tooltips describing their meaning. The tags are used by "
"GObjectIntrospection/Annotations\" type=\"http\">wikisidan</ulink>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1195
+#: C/index.docbook:1491
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1216 C/index.docbook:1245
+#: C/index.docbook:1512 C/index.docbook:1541
msgid "Function comment block"
msgstr "Kommentarsblock för funktioner"
#. (itstool) path: listitem/para
-#: C/index.docbook:1222
+#: C/index.docbook:1518
msgid ""
"Document whether returned objects, lists, strings, etc, should be freed/"
"unrefed/released."
"avrefereras/släppas."
#. (itstool) path: listitem/para
-#: C/index.docbook:1228
+#: C/index.docbook:1524
msgid "Document whether parameters can be NULL, and what happens if they are."
msgstr ""
"Dokumentera huruvida parametrar tillåts vara NULL och vad som händer om de "
"är NULL."
#. (itstool) path: listitem/para
-#: C/index.docbook:1233
+#: C/index.docbook:1529
msgid ""
"Mention interesting pre-conditions and post-conditions where appropriate."
msgstr "Nämn intressanta förvillkor och eftervillkor där lämpligt."
#. (itstool) path: sect2/para
-#: C/index.docbook:1218 C/index.docbook:1304
+#: C/index.docbook:1514 C/index.docbook:1600
msgid "Please remember to: <_:itemizedlist-1/>"
msgstr "Kom ihåg att: <_:itemizedlist-1/>"
# sebras: Gtk-doc? GTK-Doc? gtk-doc? macros and functions?
#. (itstool) path: sect2/para
-#: C/index.docbook:1240
+#: C/index.docbook:1536
msgid ""
"Gtk-doc assumes all symbols (macros, functions) starting with '_' are "
"private. They are treated like static functions."
# sebras: how to translate highlight?
#. (itstool) path: example/programlisting
-#: C/index.docbook:1246
+#: C/index.docbook:1542
#, no-wrap
msgid ""
"\n"
" */\n"
#. (itstool) path: variablelist/title
-#: C/index.docbook:1267
+#: C/index.docbook:1563
msgid "Function tags"
msgstr "Funktions-taggar"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1268 C/index.docbook:1475
+#: C/index.docbook:1564 C/index.docbook:1771
msgid "Returns:"
msgstr "Returns:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1270
+#: C/index.docbook:1566
msgid "Paragraph describing the returned result."
msgstr "Stycke som beskriver det returnerade resultatet."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1275
+#: C/index.docbook:1571
msgid "@...:"
msgstr "@...:"
# sebras: variadic?
#. (itstool) path: listitem/para
-#: C/index.docbook:1277
+#: C/index.docbook:1573
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:1583 C/index.docbook:1585
msgid "Property comment block"
msgstr "Kommentarsblock för egenskaper"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1290
+#: C/index.docbook:1586
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1302 C/index.docbook:1321
+#: C/index.docbook:1598 C/index.docbook:1617
msgid "Signal comment block"
msgstr "Kommentarsblock för signaler"
#. (itstool) path: listitem/para
-#: C/index.docbook:1308
+#: C/index.docbook:1604
msgid ""
"Document when the signal is emitted and whether it is emitted before or "
"after other signals."
"efter andra signaler."
#. (itstool) path: listitem/para
-#: C/index.docbook:1314
+#: C/index.docbook:1610
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:1322
+#: C/index.docbook:1618
#, no-wrap
msgid ""
"\n"
#. (itstool) path: sect2/title
#. (itstool) path: example/title
-#: C/index.docbook:1339 C/index.docbook:1340
+#: C/index.docbook:1635 C/index.docbook:1636
msgid "Struct comment block"
msgstr "Kommentarsblock för strukturer"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1341
+#: C/index.docbook:1637
#, no-wrap
msgid ""
"\n"
"} FooWidget;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1356
+#: C/index.docbook:1652
msgid ""
"Use <code>/*< private >*/</code> before the private struct fields you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"beteendet."
#. (itstool) path: sect2/para
-#: C/index.docbook:1362
+#: C/index.docbook:1658
msgid ""
"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" "
"it will be considered private automatically and doesn't need to be mentioned "
"kommentarsblocket."
#. (itstool) path: sect2/para
-#: C/index.docbook:1368
+#: C/index.docbook:1664
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:1676 C/index.docbook:1677
msgid "Enum comment block"
msgstr "Kommentarsblock för uppräkningar"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1382
+#: C/index.docbook:1678
#, no-wrap
msgid ""
"\n"
"} Something;\n"
#. (itstool) path: sect2/para
-#: C/index.docbook:1399
+#: C/index.docbook:1695
msgid ""
"Use <code>/*< private >*/</code> before the private enum values you "
"want to hide. Use <code>/*< public >*/</code> for the reverse "
"beteendet."
#. (itstool) path: sect1/title
-#: C/index.docbook:1410
+#: C/index.docbook:1706
msgid "Inline program documentation"
msgstr "Infogad programdokumentation"
# sebras: how to translate inline?
#. (itstool) path: sect1/para
-#: C/index.docbook:1411
+#: C/index.docbook:1707
msgid ""
"You can document programs and their commandline interface using inline "
"documentation."
"dokumentation."
#. (itstool) path: variablelist/title
-#: C/index.docbook:1417
+#: C/index.docbook:1713
msgid "Tags"
msgstr "Taggar"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1419
+#: C/index.docbook:1715
msgid "PROGRAM"
msgstr "PROGRAM"
#. (itstool) path: listitem/para
-#: C/index.docbook:1422
+#: C/index.docbook:1718
msgid "Defines the start of a program documentation."
msgstr "Definierar början av programdokumentationen."
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1429
+#: C/index.docbook:1725
msgid "@short_description:"
msgstr "@short_description:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1431
+#: C/index.docbook:1727
msgid "Defines a short description of the program. (Optional)"
msgstr "Definierar en kort beskrivning av programmet. (Valfritt)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1438
+#: C/index.docbook:1734
msgid "@synopsis:"
msgstr "@synopsis:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1440
+#: C/index.docbook:1736
msgid ""
"Defines the arguments, or list of arguments that the program can take. "
"(Optional)"
"(Valfritt)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1448
+#: C/index.docbook:1744
msgid "@see_also:"
msgstr "@see_also:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1450
+#: C/index.docbook:1746
msgid "See Also manual page section. (Optional)"
msgstr "Se vidare i manualavsnitt. (Valfritt)"
#. (itstool) path: varlistentry/term
-#: C/index.docbook:1457
+#: C/index.docbook:1753
msgid "@arg:"
msgstr "@arg:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1459
+#: C/index.docbook:1755
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:1466
+#: C/index.docbook:1762
msgid "Description:"
msgstr "Beskrivning:"
#. (itstool) path: listitem/para
-#: C/index.docbook:1468
+#: C/index.docbook:1764
msgid "A longer description of the program."
msgstr "En längre beskrivning av programmet."
#. (itstool) path: listitem/para
-#: C/index.docbook:1477
-msgid "Specificy what value(s) the program returns. (Optional)"
+#: C/index.docbook:1773
+msgid "Specify what value(s) the program returns. (Optional)"
msgstr "Ange vilka värden programmet returnerar. (Valfritt)"
#. (itstool) path: sect2/title
-#: C/index.docbook:1486
+#: C/index.docbook:1782
msgid "Example of program documentation."
msgstr "Exempel på programdokumentation."
#. (itstool) path: example/title
-#: C/index.docbook:1487
+#: C/index.docbook:1783
msgid "Program documentation block"
msgstr "Dokumentationsblock för program"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1488
+#: C/index.docbook:1784
#, no-wrap
msgid ""
"\n"
"}\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1514
+#: C/index.docbook:1810
msgid "Useful DocBook tags"
msgstr "Användbara DocBook-taggar"
#. (itstool) path: sect1/para
-#: C/index.docbook:1516
+#: C/index.docbook:1812
msgid ""
"Here are some DocBook tags which are most useful when documenting the code."
msgstr ""
"Här är några DocBook-taggar som är användbara när man dokumenterar koden."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1525
+#: C/index.docbook:1821
#, no-wrap
msgid ""
"\n"
"<link linkend=\"glib-Hash-Tables\">Hashtabeller</link>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1521
+#: C/index.docbook:1817
msgid ""
"To link to another section in the GTK docs: <_:informalexample-1/> The "
"linkend is the SGML/XML id on the top item of the page you want to link to. "
"konverteras till ”-” för att överensstämma med SGML/XML."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1538
+#: C/index.docbook:1834
#, no-wrap
msgid ""
"\n"
"<function>…</function>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1535
+#: C/index.docbook:1831
msgid ""
"To refer to an external function, e.g. a standard C function: <_:"
"informalexample-1/>"
"informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1547
+#: C/index.docbook:1843
#, no-wrap
msgid ""
"\n"
"</example>\n"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1558
+#: C/index.docbook:1854
#, no-wrap
msgid ""
"\n"
"</informalexample>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1544
+#: C/index.docbook:1840
msgid ""
"To include example code: <_:informalexample-1/> or possibly this, for very "
"short code fragments which don't need a title: <_:informalexample-2/> For "
"förkortningen: |[ … ]|"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1577
+#: C/index.docbook:1873
#, no-wrap
msgid ""
"\n"
"</itemizedlist>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1574
+#: C/index.docbook:1870
msgid "To include bulleted lists: <_:informalexample-1/>"
msgstr "För att inkludera punktlistor: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1597
+#: C/index.docbook:1893
#, no-wrap
msgid ""
"\n"
"</note>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1594
+#: C/index.docbook:1890
msgid ""
"To include a note which stands out from the text: <_:informalexample-1/>"
msgstr ""
"För att inkludera en not som skiljer sig från texten: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1610
+#: C/index.docbook:1906
#, no-wrap
msgid ""
"\n"
"<type>unsigned char</type>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1607
+#: C/index.docbook:1903
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:1619
+#: C/index.docbook:1915
#, no-wrap
msgid ""
"\n"
"<structname>XFontStruct</structname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1616
+#: C/index.docbook:1912
msgid ""
"To refer to an external structure (not one described in the GTK docs): <_:"
"informalexample-1/>"
"dokumentationen): <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1628
+#: C/index.docbook:1924
#, no-wrap
msgid ""
"\n"
"<structfield>len</structfield>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1625
+#: C/index.docbook:1921
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:1637
+#: C/index.docbook:1933
#, no-wrap
msgid ""
"\n"
"<classname>GtkWidget</classname>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1634
+#: C/index.docbook:1930
msgid ""
"To refer to a class name, we could possibly use: <_:informalexample-1/> but "
"you'll probably be using #GtkWidget instead (to automatically create a link "
"\"documenting_syntax\">förkortningarna</link>)."
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1648
+#: C/index.docbook:1944
#, no-wrap
msgid ""
"\n"
"<emphasis>Detta är viktigt</emphasis>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1645
+#: C/index.docbook:1941
msgid "To emphasize text: <_:informalexample-1/>"
msgstr "För att betona text: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1657
+#: C/index.docbook:1953
#, no-wrap
msgid ""
"\n"
"<filename>/home/användare/dokument</filename>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1654
+#: C/index.docbook:1950
msgid "For filenames use: <_:informalexample-1/>"
msgstr "För filnamn använd: <_:informalexample-1/>"
#. (itstool) path: informalexample/programlisting
-#: C/index.docbook:1666
+#: C/index.docbook:1962
#, no-wrap
msgid ""
"\n"
"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1663
+#: C/index.docbook:1959
msgid "To refer to keys use: <_:informalexample-1/>"
msgstr "För att referera till tangenter använd: <_:informalexample-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:1676
+#: C/index.docbook:1972
msgid "Filling the extra files"
msgstr "Fylla i de extra filerna"
#. (itstool) path: chapter/para
-#: C/index.docbook:1678
+#: C/index.docbook:1974
msgid ""
"There are a couple of extra files, that need to be maintained along with the "
"inline source code comments: <filename><package>.types</filename>, "
"paket>-sections.txt</filename>."
#. (itstool) path: sect1/title
-#: C/index.docbook:1687
+#: C/index.docbook:1983
msgid "Editing the types file"
msgstr "Redigera typfilen"
#. (itstool) path: sect1/para
-#: C/index.docbook:1689
+#: C/index.docbook:1985
msgid ""
"If your library or application includes GObjects, you want their signals, "
"arguments/parameters and position in the hierarchy to be shown in the "
"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>."
+"paket>.types</filename>."
#. (itstool) path: example/title
-#: C/index.docbook:1698
-msgid "Example types file snippet"
-msgstr "Exempel på typfilsnutt"
+#: C/index.docbook:1994
+msgid "Example <package>.types file"
+msgstr "Exempel på filen <paket>.types"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1699
+#: C/index.docbook:1995
#, no-wrap
msgid ""
"\n"
"gtk_arrow_get_type\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1710
+#: C/index.docbook:2006
msgid ""
"Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this "
"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in "
"du inte distribuera typfilen eller versionshantera den."
#. (itstool) path: sect1/title
-#: C/index.docbook:1719
+#: C/index.docbook:2015
msgid "Editing the master document"
msgstr "Redigera huvuddokumentet"
#. (itstool) path: sect1/para
-#: C/index.docbook:1721
+#: C/index.docbook:2017
msgid ""
"GTK-Doc produces documentation in DocBook SGML/XML. When processing the "
"inline source comments, the GTK-Doc tools generate one documentation page "
# sebras: Its -> it's
#. (itstool) path: sect1/para
-#: C/index.docbook:1728
+#: C/index.docbook:2024
msgid ""
"While GTK-Doc creates a template master document for you, later runs will "
"not touch it again. This means that one can freely structure the "
# sebras: for -> from Apart -> together/embedded...
#. (itstool) path: tip/para
-#: C/index.docbook:1738
+#: C/index.docbook:2034
msgid ""
"Do not create tutorials as extra documents. Just write extra chapters. The "
"benefit of directly embedding the tutorial for your library into the API "
"blir uppdaterad tillsammans med biblioteket."
#. (itstool) path: sect1/para
-#: C/index.docbook:1747
+#: C/index.docbook:2043
msgid ""
"So what are the things to change inside the master document? For a start is "
"only a little. There are some placeholders (text in square brackets) there "
"Det finns en del platshållare (text i hakparenteser) som du bör ta hand om."
#. (itstool) path: example/title
-#: C/index.docbook:1754
+#: C/index.docbook:2050
msgid "Master document header"
msgstr "Huvuddokumentets huvud"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1755
+#: C/index.docbook:2051
#, no-wrap
msgid ""
"\n"
" <title>[Infoga titel här]</title>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1771
+#: C/index.docbook:2067
msgid ""
"In addition a few option elements are created in commented form. You can "
"review these and enable them as you like."
"Du kan granska dessa och aktivera dem enligt dina egna önskemål."
#. (itstool) path: example/title
-#: C/index.docbook:1777
+#: C/index.docbook:2073
msgid "Optional part in the master document"
msgstr "Valfri del i huvuddokumentet"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1778
+#: C/index.docbook:2074
#, no-wrap
msgid ""
"\n"
" -->\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1786
+#: C/index.docbook:2082
msgid ""
"Finally you need to add new section whenever you introduce one. The <link "
"linkend=\"modernizing-gtk-doc-1-16\">gtkdoc-check</link> tool will remind "
"infogats i dokumentationen."
#. (itstool) path: example/title
-#: C/index.docbook:1794 C/index.docbook:1829
+#: C/index.docbook:2090 C/index.docbook:2125
msgid "Including generated sections"
msgstr "Inkludera genererade avsnitt"
#. (itstool) path: example/programlisting
-#: C/index.docbook:1795
+#: C/index.docbook:2091
#, no-wrap
msgid ""
"\n"
" ...\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:1807
+#: C/index.docbook:2103
msgid "Editing the section file"
msgstr "Redigera avsnittsfilen"
#. (itstool) path: sect1/para
-#: C/index.docbook:1809
+#: C/index.docbook:2105
msgid ""
"The section file is used to organise the documentation output by GTK-Doc. "
"Here one specifies which symbol belongs to which module or class and control "
"styra synligheten (publik eller privat)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1815
+#: C/index.docbook:2111
msgid ""
"The section file is a plain text file with tags delimiting sections. Blank "
"lines are ignored and lines starting with a '#' are treated as comment lines."
"kommentarsrader."
#. (itstool) path: note/para
-#: C/index.docbook:1822
+#: C/index.docbook:2118
msgid ""
"While the tags make the file look like xml, it is not. Please do not close "
"tags like <SUBSECTION>."
"taggar så som <SUBSECTION>."
#. (itstool) path: example/programlisting
-#: C/index.docbook:1830
+#: C/index.docbook:2126
#, no-wrap
msgid ""
"\n"
"</SECTION>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:1847
+#: C/index.docbook:2143
msgid ""
"The <FILE> ... </FILE> tag is used to specify the file name, "
"without any suffix. For example, using '<FILE>gnome-config</"
"klassnamnet för GObjectet konverterat till gemener)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1859
+#: C/index.docbook:2155
msgid ""
"The <TITLE> ... </TITLE> tag is used to specify the title of the "
"section. It is only useful before the templates (if used) are initially "
"Vidare är detta föråldrat om man använder SECTIONS-kommentarer i källkoden."
#. (itstool) path: sect1/para
-#: C/index.docbook:1866
+#: C/index.docbook:2162
msgid ""
"You can group items in the section by using the <SUBSECTION> tag. "
"Currently it outputs a blank line between subsections in the synopsis "
"beror på om de har publika poster (variabler, virtuella metoder)."
#. (itstool) path: sect1/para
-#: C/index.docbook:1885
+#: C/index.docbook:2181
msgid ""
"You can also use <INCLUDE> ... </INCLUDE> to specify the "
"#include files which are shown in the synopsis sections. It contains a comma-"
"påverka det avsnittet."
#. (itstool) path: chapter/title
-#: C/index.docbook:1899
+#: C/index.docbook:2195
msgid "Controlling the result"
msgstr "Kontrollera resultatet"
#. (itstool) path: chapter/para
-#: C/index.docbook:1901
+#: C/index.docbook:2197
msgid ""
"A GTK-Doc run generates report files inside the documentation directory. The "
"generated files are named: <filename><package>-undocumented.txt</"
"kan visas eller efterbehandlas enkelt."
#. (itstool) path: chapter/para
-#: C/index.docbook:1910
+#: C/index.docbook:2206
msgid ""
"The <filename><package>-undocumented.txt</filename> file starts with "
"the documentation coverage summary. Below are two sections divided by blank "
"dokumentation, men där en ny parameter har lagts till."
#. (itstool) path: chapter/para
-#: C/index.docbook:1919
+#: C/index.docbook:2215
msgid ""
"The <filename><package>-undeclared.txt</filename> file lists symbols "
"given in the <filename><package>-sections.txt</filename> but not found "
"källkoden. Kontrollera om de har tagits bort eller om de är felstavade."
#. (itstool) path: chapter/para
-#: C/index.docbook:1926
+#: C/index.docbook:2222
msgid ""
"The <filename><package>-unused.txt</filename> file lists symbol names, "
"where the GTK-Doc scanner has found documentation, but does not know where "
# sebras: <filename>?
#. (itstool) path: tip/para
-#: C/index.docbook:1934
+#: C/index.docbook:2230
msgid ""
"Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile."
"am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during "
"köra rimlighetskontroller under körning av <command>make check</command>."
#. (itstool) path: chapter/para
-#: C/index.docbook:1941
+#: C/index.docbook:2237
msgid ""
"One can also look at the files produced by the source code scanner: "
"<filename><package>-decl-list.txt</filename> and <filename><"
"en symbol saknas bör man kontrollera om denna filen innehåller den."
#. (itstool) path: chapter/para
-#: C/index.docbook:1950
+#: C/index.docbook:2246
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:1965
+#: C/index.docbook:2261
msgid "Modernizing the documentation"
msgstr "Modernisera dokumentationen"
#. (itstool) path: chapter/para
-#: C/index.docbook:1967
+#: C/index.docbook:2263
msgid ""
"GTK-Doc has been around for quite some time. In this section we list new "
"features together with the version since when it is available."
"tillsammans med vilken version de gjordes tillgängliga."
#. (itstool) path: sect1/title
-#: C/index.docbook:1973
+#: C/index.docbook:2269
msgid "GTK-Doc 1.9"
msgstr "GTK-Doc 1.9"
#. (itstool) path: sect1/para
-#: C/index.docbook:1975
+#: C/index.docbook:2271
msgid ""
"When using xml instead of sgml, one can actually name the master document "
"<filename><package>-docs.xml</filename>."
"huvuddokumentet <filename><paket>-docs.xml</filename>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1980
+#: C/index.docbook:2276
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-sections</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"<code>meld <paket>-decl-list.txt <paket>-sections.txt</code>."
#. (itstool) path: sect1/para
-#: C/index.docbook:1991
+#: C/index.docbook:2287
msgid ""
"Version 1.8 already introduced the syntax for documenting sections in the "
"sources instead of the separate files under <filename class=\"directory"
"filename> så är du klar."
#. (itstool) path: sect1/title
-#: C/index.docbook:2003
+#: C/index.docbook:2299
msgid "GTK-Doc 1.10"
msgstr "GTK-Doc 1.10"
#. (itstool) path: sect1/para
-#: C/index.docbook:2005
+#: C/index.docbook:2301
msgid ""
"This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in "
"<filename>Makefile.am</filename>. When this is enabled, the <filename><"
"filename> för kod som bara byggs ibland."
#. (itstool) path: sect1/title
-#: C/index.docbook:2016
+#: C/index.docbook:2312
msgid "GTK-Doc 1.16"
msgstr "GTK-Doc 1.16"
#. (itstool) path: example/title
-#: C/index.docbook:2022
+#: C/index.docbook:2318
msgid "Enable gtkdoc-check"
msgstr "Aktivera gtkdoc-check"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2023
+#: C/index.docbook:2319
#, no-wrap
msgid ""
"\n"
"endif\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2018
+#: C/index.docbook:2314
msgid ""
"This version includes a new tool called gtkdoc-check. This tool can run a "
"set of sanity checks on your documentation. It is enabled by adding these "
"am</filename>. <_:example-1/>"
#. (itstool) path: sect1/title
-#: C/index.docbook:2036
+#: C/index.docbook:2332
msgid "GTK-Doc 1.20"
msgstr "GTK-Doc 1.20"
#. (itstool) path: sect1/para
-#: C/index.docbook:2038
+#: C/index.docbook:2334
msgid ""
"Version 1.18 brought some initial markdown support. Using markdown in doc "
"comments is less intrusive than writing docbook xml. This version improves a "
"\">kommentarsyntax</link> finnas alla detaljer."
#. (itstool) path: sect1/title
-#: C/index.docbook:2048
+#: C/index.docbook:2344
msgid "GTK-Doc 1.25"
msgstr "GTK-Doc 1.25"
#. (itstool) path: example/title
-#: C/index.docbook:2058
+#: C/index.docbook:2355
msgid "Use pre-generated entities"
msgstr "Att använda förgenererade entiteter"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2059
+#: C/index.docbook:2356
#, no-wrap
msgid ""
"\n"
" </bookinfo>\n"
#. (itstool) path: sect1/para
-#: C/index.docbook:2050
+#: C/index.docbook:2346
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/>"
+"the entity file is included in the master template and how the entities are "
+"used. The entities can also be used in all generated files, GTK-Doc will use "
+"the same xml header in generated xml files. <_:example-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/>"
+"som visar hur entitetsfilen inkluderas i huvudmallen och hur entiteterna "
+"används. Entiteterna kan också användas i alla genererade filer, GTK-Doc "
+"kommer att använda samma xml-huvud i genererade xml-filer. <_:example-1/>"
#. (itstool) path: chapter/title
-#: C/index.docbook:2084
+#: C/index.docbook:2381
msgid "Documenting other interfaces"
msgstr "Dokumentera andra gränssnitt"
#. (itstool) path: chapter/para
-#: C/index.docbook:2086
+#: C/index.docbook:2383
msgid ""
"So far we have been using GTK-Doc to document the API of code. The next "
"sections contain suggestions how the tools can be used to document other "
"också dokumentera andra gränssnitt."
#. (itstool) path: sect1/title
-#: C/index.docbook:2093
+#: C/index.docbook:2390
msgid "Command line options and man pages"
msgstr "Kommandoradsflaggor och mansidor"
#. (itstool) path: sect1/para
-#: C/index.docbook:2095
+#: C/index.docbook:2392
msgid ""
"As one can generate man pages for a docbook refentry as well, it sounds like "
"a good idea to use it for that purpose. This way the interface is part of "
"gränssnittet att vara en del av referensen och man får mansidan gratis."
#. (itstool) path: sect2/title
-#: C/index.docbook:2102
+#: C/index.docbook:2399
msgid "Document the tool"
msgstr "Dokumentera verktyget"
# sebras: strange English
#. (itstool) path: sect2/para
-#: C/index.docbook:2104
+#: C/index.docbook:2401
msgid ""
"Create one refentry file per tool. Following <link linkend="
"\"settingup_docfiles\">our example</link> we would call it <filename>meep/"
"väl som exempel i glib."
#. (itstool) path: sect2/title
-#: C/index.docbook:2114
+#: C/index.docbook:2411
msgid "Adding the extra configure check"
msgstr "Lägga till den extra configure-kontrollen"
#. (itstool) path: example/title
-#: C/index.docbook:2117 C/index.docbook:2135
+#: C/index.docbook:2414 C/index.docbook:2432
msgid "Extra configure checks"
msgstr "Lägga till extra configure-kontroller"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2118
+#: C/index.docbook:2415
#, no-wrap
msgid ""
"\n"
"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n"
#. (itstool) path: sect2/title
-#: C/index.docbook:2132
+#: C/index.docbook:2429
msgid "Adding the extra makefile rules"
msgstr "Lägga till de extra makefilsreglerna"
#. (itstool) path: example/programlisting
-#: C/index.docbook:2136
+#: C/index.docbook:2433
#, no-wrap
msgid ""
"\n"
"EXTRA_DIST += meep.xml\n"
#. (itstool) path: sect1/title
-#: C/index.docbook:2158
+#: C/index.docbook:2455
msgid "DBus interfaces"
msgstr "DBus-gränssnitt"
#. (itstool) path: sect1/para
-#: C/index.docbook:2160
+#: C/index.docbook:2457
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:2169
+#: C/index.docbook:2466
msgid "Frequently asked questions"
msgstr "Frågor och svar"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2173
+#: C/index.docbook:2470
msgid "Question"
msgstr "Fråga"
#. (itstool) path: segmentedlist/segtitle
-#: C/index.docbook:2174
+#: C/index.docbook:2471
msgid "Answer"
msgstr "Svar"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2176
+#: C/index.docbook:2473
msgid "No class hierarchy."
msgstr "Ingen klasshierarki."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2177
+#: C/index.docbook:2474
msgid ""
"The objects <function>xxx_get_type()</function> function has not been "
"entered into the <filename><package>.types</filename> file."
"filen <filename><paket>.types</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2183
+#: C/index.docbook:2480
msgid "Still no class hierarchy."
msgstr "Fortfarande ingen klasshierarki."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2184
+#: C/index.docbook:2481
msgid ""
"Missing or wrong naming in <filename><package>-sections.txt</filename> "
"file (see <ulink url=\"http://mail.gnome.org/archives/gtk-doc-list/2003-"
"October/msg00006.html\">förklaring</ulink>)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2190
+#: C/index.docbook:2487
msgid "Damn, I have still no class hierarchy."
msgstr "Förbannat, jag har fortfarande ingen klasshierarki."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2191
+#: C/index.docbook:2488
msgid ""
"Is the object name (name of the instance struct, e.g. <type>GtkWidget</"
"type>) part of the normal section (don't put this into Standard or Private "
"Standard eller Private)."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2198
+#: C/index.docbook:2495
msgid "No symbol index."
msgstr "Inget symbolindex."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2199
+#: C/index.docbook:2496
msgid ""
"Does the <filename><package>-docs.{xml,sgml}</filename> contain a "
"index that xi:includes the generated index?"
"inkluderar det genererade indexet med xi:include?"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2205
+#: C/index.docbook:2502
msgid "Symbols are not linked to their doc-section."
msgstr "Symboler är inte länkade till deras dokumentationsavsnitt."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2206
+#: C/index.docbook:2503
msgid ""
"Is the doc-comment using the correct markup (added #,% or ())? Check if the "
"gtkdoc-fixxref warns about unresolvable xrefs."
"korsreferenser."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2212
+#: C/index.docbook:2509
msgid "A new class does not appear in the docs."
msgstr "En ny klass dyker inte upp i dokumentationen."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2213
+#: C/index.docbook:2510
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:2219
+#: C/index.docbook:2516
msgid "A new symbol does not appear in the docs."
msgstr "En ny symbol dyker inte upp i dokumentationen."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2220
+#: C/index.docbook:2517
msgid ""
"Is the doc-comment properly formatted. Check for spelling mistakes in the "
"begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable "
"paket>-sections.txt</filename> i ett publikt avsnitt."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2228
+#: C/index.docbook:2525
msgid "A type is missing from the class hierarchy."
msgstr "En typ saknas från klasshierarkin."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2229
+#: C/index.docbook:2526
msgid ""
"If the type is listed in <filename><package>.hierarchy</filename> but "
"not in <filename>xml/tree_index.sgml</filename> then double check that the "
"privat kommer den inte att visas."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2238
+#: C/index.docbook:2535
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:2239
+#: C/index.docbook:2536
msgid ""
"Check that <filename>xml/annotation-glossary.xml</filename> is xi:included "
"from <filename><package>-docs.{xml,sgml}</filename>."
"filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2247
+#: C/index.docbook:2544
msgid "Parameter described in source code comment block but does not exist"
msgstr "Parameter beskriven i kommentarsblock i källkoden men existerar inte"
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2248
+#: C/index.docbook:2545
msgid ""
"Check if the prototype in the header has different parameter names as in the "
"source."
"Kontrollera om prototypen i huvudet har andra parameternamn än i källkoden."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2253
+#: C/index.docbook:2550
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:2254
+#: C/index.docbook:2551
msgid ""
"Symbol XYZ appears twice in <filename><package>-sections.txt</"
"filename> file."
"txt</filename>."
#. (itstool) path: seglistitem/seg
-#: C/index.docbook:2257
+#: C/index.docbook:2554
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:2264
+#: C/index.docbook:2561
msgid "Tools related to gtk-doc"
msgstr "Verktyg relaterade till gtk-doc"
#. (itstool) path: chapter/para
-#: C/index.docbook:2266
+#: C/index.docbook:2563
msgid ""
"GtkDocPlugin - a <ulink url=\"http://trac-hacks.org/wiki/GtkDocPlugin\">Trac "
"GTK-Doc</ulink> integration plugin, that adds API docs to a trac site and "
"dokumentation till en trac-webbplats och integrerar med trac-sökningen."
#. (itstool) path: chapter/para
-#: C/index.docbook:2271
+#: C/index.docbook:2568
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."
"vald, fri programvarulicens, som till exempel <_:ulink-1/>, för att "
"möjliggöra deras användning i fri programvara."
+#~ msgid "Setting up your project"
+#~ msgstr "Att ställa in ditt projekt"
+
+#~ 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."
+
+#~ 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."
+
+#~ msgid "Example directory structure"
+#~ msgstr "Exempel på katalogstruktur"
+
+#~ msgid "This can then look as shown below: <_:example-1/>"
+#~ msgstr "Detta kan se ut enligt nedan: <_:example-1/>"
+
+#~ 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."
+
+#~ 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"
+
+#~ msgid "Keep gtk-doc optional"
+#~ msgstr "Låt gtk-doc vara valfritt"
+
+#~ 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"
+
+#~ 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/>"
+
+#~ 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."
+
+#~ msgid "Preparation for gtkdocize"
+#~ msgstr "Förberedelse för gtkdocize"
+
+#~ msgid ""
+#~ "\n"
+#~ "AC_CONFIG_MACRO_DIR(m4)\n"
+#~ msgstr ""
+#~ "\n"
+#~ "AC_CONFIG_MACRO_DIR(m4)\n"
+
+# sebras: e.g. because of,... it can be...any files in tmpl...and is migrating...<symbol> or <function>? gtkdoc or GTK-Doc
+#~ 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)."
+
+#~ 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."
+
+#~ msgid "Documentation placement"
+#~ msgstr "Dokumentationsplacering"
+
+#~ 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."
+
+#~ 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."
+
#~ msgid "<guilabel>Python</guilabel> - optional - for gtkdoc-depscan"
#~ msgstr "<guilabel>Python</guilabel> - valfritt - för gtkdoc-depscan"
<holder>Dan Mueth and Chris Lyttle</holder>
</copyright>
<copyright>
- <year>2007-2015</year>
+ <year>2007-2019</year>
<holder>Stefan Sauer (Kost)</holder>
</copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision>
<revnumber>1.28</revnumber>
<title>ஜிடிகே டாக் பற்றி</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>(FIXME)</para>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
<term>திருப்பிகிடைப்பவை:</term>
<listitem>
<para>
- Specificy what value(s) the program returns. (Optional)
+ Specify what value(s) the program returns. (Optional)
</para>
</listitem>
</varlistentry>
<programlisting><![CDATA[
<example>
<title>Using a GHashTable.</title>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</example>
<informalexample>
<programlisting><![CDATA[
<informalexample>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</informalexample>
]]></programlisting>
</informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
For the latter GTK-Doc also supports an abbreviation:
-<![CDATA[
-|[
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
...
]|
-]]>
+]]></programlisting>
+ </informalexample>
</para>
<para>
<holder>Dan Mueth and Chris Lyttle</holder>
</copyright>
<copyright>
- <year>2007-2015</year>
+ <year>2007-2019</year>
<holder>Stefan Sauer (Kost)</holder>
</copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision>
<revnumber>1.28</revnumber>
<title>GTK-Doc గురించి</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>(FIXME)</para>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
<term>తిరిగివచ్చినవి:</term>
<listitem>
<para>
- Specificy what value(s) the program returns. (Optional)
+ Specify what value(s) the program returns. (Optional)
</para>
</listitem>
</varlistentry>
<programlisting><![CDATA[
<example>
<title>Using a GHashTable.</title>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</example>
<informalexample>
<programlisting><![CDATA[
<informalexample>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</informalexample>
]]></programlisting>
</informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
For the latter GTK-Doc also supports an abbreviation:
-<![CDATA[
-|[
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
...
]|
-]]>
+]]></programlisting>
+ </informalexample>
</para>
<para>
<publisher role="maintainer"><publishername>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>
+ <year>2007-2019</year>
<holder>Stefan Sauer (Kost)</holder>
</copyright>
</legalnotice>
<revhistory>
+ <revision>
+ <revnumber>1.30</revnumber>
+ <date>08 May 2019</date>
+ <authorinitials>ss</authorinitials>
+ <revremark>more test coverage</revremark>
+ </revision>
<revision>
<revnumber>1.29</revnumber>
<date>28 Aug 2018</date>
<authorinitials>ss</authorinitials>
- <revremark>development</revremark>
+ <revremark>bug fixes</revremark>
</revision>
<revision>
<revnumber>1.28</revnumber>
<title>关于 GTK-Doc</title>
<para>
- Historically GTK-Doc was used to generate template files from the soures
+ Historically GTK-Doc was used to generate template files from the sources
code. These template files could be used by developers to enter the
API documentation. This approach was rather inconvenient because it
required to keep the generated files under version control.
Since GTK-Doc 1.9 it became possible to place all API information
into source comments, which made the template support obsolete.
- In version 1.26 template support has been.
+ In version 1.26 template support has been removed.
</para>
<para>
<para>
<option>expand_content_files</option>
allows to specify files
- where <emphasis>gtk-doc abbrevations</emphasis> such as
+ where <emphasis>gtk-doc abbreviations</emphasis> such as
<code>#GtkWidget</code>
are expanded (e.g. <code>
expand_content_files=running.xml</code>).
<term>返回值：</term>
<listitem>
<para>
- Specificy what value(s) the program returns. (Optional)
+ Specify what value(s) the program returns. (Optional)
</para>
</listitem>
</varlistentry>
]]></programlisting>
</informalexample></para>
- <para>要包含示例代码：<informalexample>
+ <para>
+ To include example code:
+ <informalexample>
<programlisting><![CDATA[
<example>
<title>Using a GHashTable.</title>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</example>
]]></programlisting>
- </informalexample> 或类似的，很短的不需要标题的代码段：<informalexample>
+ </informalexample>
+ or possibly this, for very short code fragments which don't need a title:
+ <informalexample>
<programlisting><![CDATA[
<informalexample>
- <programlisting>
+ <programlisting language="C">
...
</programlisting>
</informalexample>
]]></programlisting>
- </informalexample> 对后者，GTK-Doc 还支持一种缩写方式：|[ ... ]|</para>
+ </informalexample>
+ In both cases, the language attribute is optional and is used as a hint
+ to the syntax highlighting engine (pygments for html output).
+ For the latter GTK-Doc also supports an abbreviation:
+ <informalexample>
+ <programlisting><![CDATA[
+|[<!-- language="C" -->
+ ...
+]|
+]]></programlisting>
+ </informalexample>
+ </para>
<para>要包含符号列表：<informalexample>
<programlisting><![CDATA[
--- /dev/null
+# ===========================================================================
+# https://www.gnu.org/software/autoconf-archive/ax_python_module.html
+# ===========================================================================
+#
+# SYNOPSIS
+#
+# AX_PYTHON_MODULE(modname[, fatal, python])
+#
+# DESCRIPTION
+#
+# Checks for Python module.
+#
+# If fatal is non-empty then absence of a module will trigger an error.
+# The third parameter can either be "python" for Python 2 or "python3" for
+# Python 3; defaults to Python 3.
+#
+# LICENSE
+#
+# Copyright (c) 2008 Andrew Collier
+#
+# Copying and distribution of this file, with or without modification, are
+# permitted in any medium without royalty provided the copyright notice
+# and this notice are preserved. This file is offered as-is, without any
+# warranty.
+
+#serial 9
+
+AU_ALIAS([AC_PYTHON_MODULE], [AX_PYTHON_MODULE])
+AC_DEFUN([AX_PYTHON_MODULE],[
+ if test -z $PYTHON;
+ then
+ if test -z "$3";
+ then
+ PYTHON="python3"
+ else
+ PYTHON="$3"
+ fi
+ fi
+ PYTHON_NAME=`basename $PYTHON`
+ AC_MSG_CHECKING($PYTHON_NAME module: $1)
+ $PYTHON -c "import $1" 2>/dev/null
+ if test $? -eq 0;
+ then
+ AC_MSG_RESULT(yes)
+ eval AS_TR_CPP(HAVE_PYMOD_$1)=yes
+ else
+ AC_MSG_RESULT(no)
+ eval AS_TR_CPP(HAVE_PYMOD_$1)=no
+ #
+ if test -n "$2"
+ then
+ AC_MSG_ERROR(failed to find required module $1)
+ exit 1
+ fi
+ fi
+])
cat <<_LT_EOF >> "$cfgfile"
#! $SHELL
# Generated automatically by $as_me ($PACKAGE) $VERSION
-# Libtool was configured on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
# NOTE: Changes made to this file will be lost: look at ltmain.sh.
# Provide generalized library-building support services.
# before this can be enabled.
hardcode_into_libs=yes
- # Add ABI-specific directories to the system library path.
- sys_lib_dlsearch_path_spec="/lib64 /usr/lib64 /lib /usr/lib"
-
# Ideally, we could use ldconfig to report *all* directores which are
# searched for libraries, however this is still not possible. Aside from not
# being certain /sbin/ldconfig is available, command
# appending ld.so.conf contents (and includes) to the search path.
if test -f /etc/ld.so.conf; then
lt_ld_extra=`awk '/^include / { system(sprintf("cd /etc; cat %s 2>/dev/null", \[$]2)); skip = 1; } { if (!skip) print \[$]0; skip = 0; }' < /etc/ld.so.conf | $SED -e 's/#.*//;/^[ ]*hwcap[ ]/d;s/[:, ]/ /g;s/=[^=]*$//;s/=[^= ]* / /g;s/"//g;/^$/d' | tr '\n' ' '`
- sys_lib_dlsearch_path_spec="$sys_lib_dlsearch_path_spec $lt_ld_extra"
+ sys_lib_dlsearch_path_spec="/lib /usr/lib $lt_ld_extra"
fi
# We used to test for /lib/ld.so.1 and disable shared libraries on
dynamic_linker='GNU/Linux ld.so'
;;
+netbsdelf*-gnu)
+ version_type=linux
+ need_lib_prefix=no
+ need_version=no
+ library_names_spec='${libname}${release}${shared_ext}$versuffix ${libname}${release}${shared_ext}$major ${libname}${shared_ext}'
+ soname_spec='${libname}${release}${shared_ext}$major'
+ shlibpath_var=LD_LIBRARY_PATH
+ shlibpath_overrides_runpath=no
+ hardcode_into_libs=yes
+ dynamic_linker='NetBSD ld.elf_so'
+ ;;
+
netbsd*)
version_type=sunos
need_lib_prefix=no
lt_cv_deplibs_check_method=pass_all
;;
-netbsd*)
+netbsd* | netbsdelf*-gnu)
if echo __ELF__ | $CC -E - | $GREP __ELF__ > /dev/null; then
lt_cv_deplibs_check_method='match_pattern /lib[[^/]]+(\.so\.[[0-9]]+\.[[0-9]]+|_pic\.a)$'
else
;;
esac
;;
- netbsd*)
+ netbsd* | netbsdelf*-gnu)
;;
*qnx* | *nto*)
# QNX uses GNU C++, but need to define -shared option too, otherwise
;;
esac
;;
+ linux* | k*bsd*-gnu | gnu*)
+ _LT_TAGVAR(link_all_deplibs, $1)=no
+ ;;
*)
_LT_TAGVAR(export_symbols_cmds, $1)='$NM $libobjs $convenience | $global_symbol_pipe | $SED '\''s/.* //'\'' | sort | uniq > $export_symbols'
;;
openbsd* | bitrig*)
with_gnu_ld=no
;;
+ linux* | k*bsd*-gnu | gnu*)
+ _LT_TAGVAR(link_all_deplibs, $1)=no
+ ;;
esac
_LT_TAGVAR(ld_shlibs, $1)=yes
fi
;;
- netbsd*)
+ netbsd* | netbsdelf*-gnu)
if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then
_LT_TAGVAR(archive_cmds, $1)='$LD -Bshareable $libobjs $deplibs $linker_flags -o $lib'
wlarc=
if test yes = "$lt_cv_irix_exported_symbol"; then
_LT_TAGVAR(archive_expsym_cmds, $1)='$CC -shared $pic_flag $libobjs $deplibs $compiler_flags $wl-soname $wl$soname `test -n "$verstring" && func_echo_all "$wl-set_version $wl$verstring"` $wl-update_registry $wl$output_objdir/so_locations $wl-exports_file $wl$export_symbols -o $lib'
fi
+ _LT_TAGVAR(link_all_deplibs, $1)=no
else
_LT_TAGVAR(archive_cmds, $1)='$CC -shared $libobjs $deplibs $compiler_flags -soname $soname `test -n "$verstring" && func_echo_all "-set_version $verstring"` -update_registry $output_objdir/so_locations -o $lib'
_LT_TAGVAR(archive_expsym_cmds, $1)='$CC -shared $libobjs $deplibs $compiler_flags -soname $soname `test -n "$verstring" && func_echo_all "-set_version $verstring"` -update_registry $output_objdir/so_locations -exports_file $export_symbols -o $lib'
esac
;;
- netbsd*)
+ netbsd* | netbsdelf*-gnu)
if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then
_LT_TAGVAR(archive_cmds, $1)='$LD -Bshareable -o $lib $libobjs $deplibs $linker_flags' # a.out
else
font-weight: normal;
}
-acronym,abbr
+acronym,abbr
{
border-bottom: 1px dotted gray;
}
-/* code listings */
-
-.listing_code .programlisting .normal,
-.listing_code .programlisting .normal a,
-.listing_code .programlisting .number,
-.listing_code .programlisting .cbracket,
-.listing_code .programlisting .symbol { color: #555753; }
-.listing_code .programlisting .comment,
-.listing_code .programlisting .linenum { color: #babdb6; } /* tango: aluminium 3 */
-.listing_code .programlisting .function,
-.listing_code .programlisting .function a,
-.listing_code .programlisting .preproc { color: #204a87; } /* tango: sky blue 3 */
-.listing_code .programlisting .string { color: #ad7fa8; } /* tango: plum */
-.listing_code .programlisting .keyword,
-.listing_code .programlisting .usertype,
-.listing_code .programlisting .type,
-.listing_code .programlisting .type a { color: #4e9a06; } /* tango: chameleon 3 */
-
.listing_frame {
/* tango:sky blue 1 */
border: solid 1px #729fcf;
## Process this file with automake to produce Makefile.in
-# we need to run '.' last so that sanity processes the generated docs
-# maybe move it to a subdir?
-SUBDIRS = annotations bugs empty fail gobject program repro .
+SUBDIRS =
+TESTS = \
+ tools.sh check.py common.py highlight.py mkdb.py mk_to_db.py mkhtml2.py \
+ scan.py
if BUILD_TESTS
-
-TESTS = \
- check.py common.py mk_to_db.py mkhtml2.py \
- tools.sh \
- annotations.sh bugs.sh empty.sh fail.sh gobject.sh program.sh
+# we need to run '.' last so that sanity processes the generated docs
+# maybe move it to a subdir?
+SUBDIRS += annotations bugs empty fail gobject program repro .
+TESTS += annotations.sh bugs.sh empty.sh fail.sh gobject.sh program.sh
+endif
TESTS_ENVIRONMENT = \
BUILDDIR=$(abs_builddir) \
TEST_EXTENSIONS = .py
PY_LOG_COMPILER = $(PYTHON)
-endif
-
-EXTRA_DIST = gtkdoctest.sh $(TESTS)
+EXTRA_DIST = gtkdoctest.sh sanity.sh $(TESTS)
# run any given test by running make <test>.check
%.check: %
fi; \
done
+coverage:
+ @python3-coverage erase; \
+ for f in *.py; do \
+ $(TESTS_ENVIRONMENT) python3-coverage run -a $$f; \
+ done; \
+ python3-coverage html --include="*/gtkdoc/*.py"; \
+ python3-coverage report --include="*/gtkdoc/*.py"
+
+
.PHONY: snapshot
-include $(top_srcdir)/git.mk
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
+
+# we need to run '.' last so that sanity processes the generated docs
+# maybe move it to a subdir?
+@BUILD_TESTS_TRUE@am__append_1 = annotations bugs empty fail gobject program repro .
+@BUILD_TESTS_TRUE@am__append_2 = annotations.sh bugs.sh empty.sh fail.sh gobject.sh program.sh
subdir = tests
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
TEST_LOGS = $(am__test_logs2:.py.log=.log)
PY_LOG_DRIVER = $(SHELL) $(top_srcdir)/build-aux/test-driver
PY_LOG_COMPILE = $(PY_LOG_COMPILER) $(AM_PY_LOG_FLAGS) $(PY_LOG_FLAGS)
-DIST_SUBDIRS = $(SUBDIRS)
+DIST_SUBDIRS = annotations bugs empty fail gobject program repro .
am__DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/tools.sh.in \
$(top_srcdir)/build-aux/test-driver
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
-
-# we need to run '.' last so that sanity processes the generated docs
-# maybe move it to a subdir?
-SUBDIRS = annotations bugs empty fail gobject program repro .
-@BUILD_TESTS_TRUE@TESTS = \
-@BUILD_TESTS_TRUE@ check.py common.py mk_to_db.py mkhtml2.py \
-@BUILD_TESTS_TRUE@ tools.sh \
-@BUILD_TESTS_TRUE@ annotations.sh bugs.sh empty.sh fail.sh gobject.sh program.sh
-
-@BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \
-@BUILD_TESTS_TRUE@ BUILDDIR=$(abs_builddir) \
-@BUILD_TESTS_TRUE@ SRCDIR=$(abs_srcdir) \
-@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@ PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
-@BUILD_TESTS_TRUE@ GLIB_PREFIX="$(glib_prefix)"
-
-@BUILD_TESTS_TRUE@TEST_EXTENSIONS = .py
-@BUILD_TESTS_TRUE@PY_LOG_COMPILER = $(PYTHON)
-EXTRA_DIST = gtkdoctest.sh $(TESTS)
+SUBDIRS = $(am__append_1)
+TESTS = tools.sh check.py common.py highlight.py mkdb.py mk_to_db.py \
+ mkhtml2.py scan.py $(am__append_2)
+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) \
+ PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \
+ GLIB_PREFIX="$(glib_prefix)"
+
+TEST_EXTENSIONS = .py
+PY_LOG_COMPILER = $(PYTHON)
+EXTRA_DIST = gtkdoctest.sh sanity.sh $(TESTS)
all: all-recursive
.SUFFIXES:
fi; \
done
+coverage:
+ @python3-coverage erase; \
+ for f in *.py; do \
+ $(TESTS_ENVIRONMENT) python3-coverage run -a $$f; \
+ done; \
+ python3-coverage html --include="*/gtkdoc/*.py"; \
+ python3-coverage report --include="*/gtkdoc/*.py"
+
.PHONY: snapshot
-include $(top_srcdir)/git.mk
host_triplet = @host@
subdir = tests/annotations
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files=
host_triplet = @host@
subdir = tests/annotations/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files =
host_triplet = @host@
subdir = tests/annotations/src
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
/**
* GtkdocAnnotation:
- * @that: (allow-none): eventualy points to something
+ * @that: (allow-none): eventually points to something
*
* small struct
*/
host_triplet = @host@
subdir = tests/bugs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files=
host_triplet = @host@
subdir = tests/bugs/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files =
<SUBSECTION Compounds>
Bug165425a
Bug165425b
-Bug324535
Bug446648
Bug512154
-Bug642998
Bug644291
Bug000000Scope
-bug_411739_rettype
+Bug76
<SUBSECTION Functions>
bug_000000_va1
BUG_000000_VA2
BUG_000000_VA3
-bug_141869_a
-bug_141869_b
-bug_379466
bug_380824
-bug_411739
bug_419997
bug_445693
bug_460127
bug_471014
bug_477532
-bug_481811
bug_501038
bug_512155a_function_pointer_t
bug_512155b_function_pointer_t
bug_512155c_function_pointer_t
-bug_532395a
-bug_532395b
-bug_544172
-bug_552602
bug_554833
bug_574654a
bug_574654b
bug_624200a
bug_624200b
bug_638330
-BUG_656773a
-BUG_656773b
-BUG_656773c
-BUG_656946
bug_624001a
bug_624001b
bug_624001c
GLIB_DEPRECATED
BUG_711598_DEPRECATED_FOR
bug_554833_new
-BUG_731417_DEPRECATED
-Bug730658
G_GNUC_NONNULL
</SECTION>
-
host_triplet = @host@
subdir = tests/bugs/src
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
#include "tester.h"
-/**
- * bug_141869_a:
- * @pid: arg
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=141869
- */
-void bug_141869_a (unsigned pid) {
- /* just silence a compiler warning */
- bug_481811((double)pid);
-}
-
-/**
- * bug_141869_b:
- * @pid: arg
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=141869
- */
-void bug_141869_b (signed pid) {
-}
-
-
-/**
- * bug_379466:
- * @pid: arg
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=379466
- */
-void bug_379466 (int
- pid) {
-}
-
-
/**
* bug_380824:
* @arg: arg
}
-/**
- * bug_411739:
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=411739
- *
- * Returns: result
- */
-struct bug_411739_rettype *
-bug_411739 (void) {
- return NULL;
-}
-
-
/**
* bug_419997:
* @const_values: arg
return NULL;
}
-
-/**
- * bug_552602:
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=552602
- *
- * Returns: result
- */
-const char* const * bug_552602 (void) {
- return NULL;
-}
-
/**
* bug_574654a:
*
void
bug_783420 (int in, int *out)
{
-}
\ No newline at end of file
+}
#include <glib.h>
-/**
- * Bug324535:
- * @BUG_324535_A: enum 1
- * @BUG_324535_B: enum 2
- * @BUG_324535_C: enum 3
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=324535
- */
-typedef enum {
- BUG_324535_A,
-#ifdef GTK_DISABLE_DEPRECATED
- BUG_324535_B,
-#endif
- BUG_324535_C
-} Bug324535;
-
-
-
-/**
- * bug_481811:
- * @x: argument
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=481811
- **/
-static inline double
-bug_481811(double x)
-{
- return g_random_double_range(x,x*x);
-}
-
/**
* bug_501038:
*/
GLIB_VAR guint64 (*bug_477532) (void);
-
-
-void bug_141869_a (unsigned pid);
-void bug_141869_b (signed pid);
-
-void bug_379466 (int
- pid);
-
int bug_380824 (int arg);
-
-/**
- * bug_411739_rettype:
- * @test: field
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=411739
- */
-struct bug_411739_rettype {
- int test;
-};
-
-struct bug_411739_rettype *
-bug_411739 (void);
-
void bug_419997 (int const_values);
void bug_445693 (unsigned long pid);
G_CONST_RETURN gchar* G_CONST_RETURN *
bug_471014 (void);
-const char* const * bug_552602 (void);
-
/**
* Bug446648:
* @BUG_446648_FOO: foo
#define BUG_530758 "dummy"
-/**
- * bug_532395a:
- * @number: a number
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=532395
- *
- * Returns: number
- */
-/**
- * bug_532395b:
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=532395
- */
-G_INLINE_FUNC guint
-bug_532395a (gulong number)
-{
-#if defined(__GNUC__) && (__GNUC__ >= 4) && defined(__OPTIMIZE__)
- return G_LIKELY (number) ?
- ((GLIB_SIZEOF_LONG * 8 - 1) ^ __builtin_clzl(number)) + 1 : 1;
-#else
- return 0;
-#endif
-}
-G_INLINE_FUNC void
-bug_532395b (void)
-{
-}
-
-
-/**
- * bug_544172:
- * @self: object pointer.
- *
- * http://bugzilla.gnome.org/show_bug.cgi?id=544172
- *
- * Returns: result or %NULL.
- */
-typedef char const * (*bug_544172) (char const *self);
-
-
/**
* bug_554833:
* @i: value;
const char ** const bug_624200b(void);
-/* internal function and macro */
+/* internal function */
gchar *_bug_000000a (const gchar *name);
-#define _BUG_000000b (a) (a*a);
-
-#ifndef __GTK_DOC_IGNORE__
-extern int bug_512565(void);
-#endif
void (*bug_638330) (void *arg1,
const unsigned char *data,
unsigned int length);
-/**
- * Bug642998:
- * @red: red color intensity, from 0–255
- * @green: green color intensity, from 0–255
- * @blue: blue color intensity, from 0–255
- *
- * https://bugzilla.gnome.org/show_bug.cgi?id=642998
- */
-typedef struct {
- guint16 red;
- guint16 green;
- guint16 blue;
-} Bug642998;
-
-
/**
* Bug644291:
* @BUG_644291_START: foo
gpointer marshal_data);
-/**
- * BUG_656773a:
- *
- * https://bugzilla.gnome.org/show_bug.cgi?id=656773
- */
-extern const char* const BUG_656773a;
-
-/**
- * BUG_656773b:
- *
- * https://bugzilla.gnome.org/show_bug.cgi?id=656773
- */
-extern const char* BUG_656773b;
-
-/**
- * BUG_656773c:
- *
- * https://bugzilla.gnome.org/show_bug.cgi?id=656773
- */
-const char* const BUG_656773c = "bug";
-
-/**
- * BUG_656946:
- *
- * https://bugzilla.gnome.org/show_bug.cgi?id=656946
- */
-extern short int BUG_656946;
-
#ifndef G_GNUC_DEPRECATED
#define G_GNUC_DEPRECATED
#endif
void bug_783420 (int in, int *out);
-/**
- * BUG_731417_DEPRECATED:
- *
- * https://bugzilla.gnome.org/show_bug.cgi?id=731417
- */
-#define BUG_731417_DEPRECATED 1
-
-/**
- * Bug730658:
- * @BUG_730658_CAN_READ: Can read
- * @BUG_730658_CAN_WRITE: Can write
- * @BUG_730658_IS_DEPRECATED: Is deprecated
- *
- * https://bugzilla.gnome.org/show_bug.cgi?id=730658
- */
-typedef enum
-{
- BUG_730658_CAN_READ = 1 << 0,
- BUG_730658_CAN_WRITE = 1 << 1,
- BUG_730658_IS_DEPRECATED = 1 << 2
-} Bug730658;
-
/**
* MACRO_VALUE:
*
*/
#define BUG_791928 1
+/**
+ * Bug76:
+ * @arg: The type of the option, as a #GOptionArg
+ * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data
+ * must point to a #GOptionArgFunc callback function, which will be
+ * called to handle the extra argument. Otherwise, @arg_data is a
+ * pointer to a location to store the value, the required type of
+ * the location depends on the @arg type:
+ * - %G_OPTION_ARG_NONE: %gboolean
+ * - %G_OPTION_ARG_STRING: %gchar*
+ * - %G_OPTION_ARG_INT: %gint
+ * - %G_OPTION_ARG_FILENAME: %gchar*
+ * - %G_OPTION_ARG_STRING_ARRAY: %gchar**
+ * - %G_OPTION_ARG_FILENAME_ARRAY: %gchar**
+ * - %G_OPTION_ARG_DOUBLE: %gdouble
+ * If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME,
+ * the location will contain a newly allocated string if the option
+ * was given. That string needs to be freed by the callee using g_free().
+ * Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or
+ * %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev().
+ * @description: the description for the option in `--help`
+ * output. The @description is translated using the @translate_func
+ * of the group, see g_option_group_set_translation_domain().
+ *
+ * https://gitlab.gnome.org/GNOME/gtk-doc/issues/76
+ */
+struct _Bug76
+{
+ int arg;
+ void * arg_data;
+ char * description;
+};
+typedef struct _Bug76 Bug76;
#endif // GTKDOC_TESTER_H
def test_get_variable_empty_file(self):
with self.assertRaises(check.FileFormatError) as ctx:
- check.get_variable({'foo': 'bar'}, [], 'foo')
+ check.get_variable({}, [], 'foo')
self.assertEqual(str(ctx.exception), 'foo')
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
-try:
- from unittest import mock
-except ImportError:
- import mock
-
+from unittest import mock
import unittest
-from six import PY2
from gtkdoc import common
-if PY2:
- openname = '__builtin__.open'
-else:
- openname = 'builtins.open'
-
-
class TestUpdateFileIfChanged(unittest.TestCase):
@mock.patch('os.path.exists')
self.assertTrue(res)
@mock.patch('os.path.exists')
- @mock.patch(openname, mock.mock_open(read_data='bar'))
+ @mock.patch('builtins.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
@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')
+ self.assertEqual(common.GetModuleDocDir('glib-2.0'), '/usr/share/gtk-doc/html')
class TestCreateValidSGMLID(unittest.TestCase):
def test_AlreadyValid(self):
- self.assertEquals(common.CreateValidSGMLID('x'), 'x')
+ self.assertEqual(common.CreateValidSGMLID('x'), 'x')
def test_SpecialCharsBecomeDash(self):
- self.assertEquals(common.CreateValidSGMLID('x_ y'), 'x--y')
+ self.assertEqual(common.CreateValidSGMLID('x_ y'), 'x--y')
def test_SpecialCharsGetRemoved(self):
- self.assertEquals(common.CreateValidSGMLID('x,;y'), 'xy')
+ self.assertEqual(common.CreateValidSGMLID('x,;y'), 'xy')
if __name__ == '__main__':
host_triplet = @host@
subdir = tests/empty
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files=
host_triplet = @host@
subdir = tests/empty/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files =
<title>[Insert title here]</title>
<xi:include href="xml/tester.xml"/>
</chapter>
+ <!-- enable this when you use gobject types
<chapter id="object-tree">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</chapter>
+ -->
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
host_triplet = @host@
subdir = tests/empty/src
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# tests
# check missing section description
# we can't just check for a missing "tester_nodocs" entry
-grep >/dev/null "tester_nodocs:Long_Description" $DOC_MODULE-undocumented.txt
+grep >/dev/null "tester_nodocs:long_description" $DOC_MODULE-undocumented.txt
if test $? = 1 ; then failed=`expr $failed + 1`; fi
tested=`expr $tested + 1`
# check missing section long description
-grep >/dev/null "tester_nolongdesc:Long_Description" $DOC_MODULE-undocumented.txt
+grep >/dev/null "tester_nolongdesc:long_description" $DOC_MODULE-undocumented.txt
if test $? = 1 ; then failed=`expr $failed + 1`; fi
tested=`expr $tested + 1`
# check missing section short description
-grep >/dev/null "tester_noshortdesc:Short_Description" $DOC_MODULE-undocumented.txt
+grep >/dev/null "tester_noshortdesc:short_description" $DOC_MODULE-undocumented.txt
if test $? = 1 ; then failed=`expr $failed + 1`; fi
tested=`expr $tested + 1`
host_triplet = @host@
subdir = tests/fail
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files=
host_triplet = @host@
subdir = tests/fail/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files =
host_triplet = @host@
subdir = tests/fail/src
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
host_triplet = @host@
subdir = tests/gobject
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files=
host_triplet = @host@
subdir = tests/gobject/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files =
host_triplet = @host@
subdir = tests/gobject/src
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
* <caption><para>Home sweet home.</para></caption>
* </mediaobject>
*
- * Just incase you wonder, special caracters can be escaped with a \ like in \%
- * or \# or even \@.
+ * Just in case you wonder, special characters can be escaped with a \ like
+ * in \% or \# or even \@.
*
* We also support verbatim spans - lets test escaping of a `<tag>` block.
*/
*
* Configure a new instance
*
- * Returns: %TRUE for sucess or %FALSE in case of an error
+ * Returns: %TRUE for success or %FALSE in case of an error
*
* Since: 0.1
*/
* frobnicator.
*
* A new instance can be created using the gtkdoc_object_new() function. The
- * whole lifecycle usualy looks like shown in this example:
+ * whole lifecycle usually looks like shown in this example:
* |[<!-- language="C" -->
* #include <glib.h>
* #include <glib-object.h>
--- /dev/null
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2018 Stefan Sauer
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+
+import unittest
+
+from gtkdoc import highlight
+
+
+class HighlightTestCase(unittest.TestCase):
+
+ def test_AlwaysKnowsCLang(self):
+ code = highlight.highlight_code('void main(int argc, char **argv')
+ self.assertIsNotNone(code)
+
+
+if __name__ == '__main__':
+ unittest.main()
</listitem>
</itemizedlist>
<para>foo</para>
+"""
+ output = md_to_db.MarkDownParse(input_, "")
+ self.assertEqual(expected, output)
+
+ # like previous, but no newlines beweteen items
+ def test_lists_in_paragraphs(self):
+ input_ = """\
+before:
+- item 1
+- item 2
+
+after
+"""
+ # TODO(ensonic): figure out why we insert '\n' for 2nd listitem
+ expected = """\
+<para>before:</para>
+<itemizedlist>
+<listitem><para>item 1</para></listitem>
+<listitem>
+<para>item 2</para>
+</listitem>
+</itemizedlist>
+<para>after</para>
"""
output = md_to_db.MarkDownParse(input_, "")
self.assertEqual(expected, output)
--- /dev/null
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2018 Stefan Sauer
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+
+import textwrap
+import unittest
+
+from gtkdoc import mkdb
+
+
+class ScanSourceContentTestCase(unittest.TestCase):
+ """Baseclass for the source scanner tests."""
+
+ def setUp(self):
+ mkdb.MODULE = 'test'
+ mkdb.SymbolDocs = {}
+
+
+class ScanSourceContent(ScanSourceContentTestCase):
+
+ def test_EmptyInput(self):
+ blocks = mkdb.ScanSourceContent([])
+ self.assertEqual(0, len(blocks))
+
+ def test_SkipsSingleLineComment(self):
+ blocks = mkdb.ScanSourceContent("/** foo */")
+ self.assertEqual(0, len(blocks))
+
+ def test_FindsSingleDocComment(self):
+ blocks = mkdb.ScanSourceContent("""\
+ /**
+ * symbol:
+ *
+ * Description.
+ */""".splitlines(keepends=True))
+ self.assertEqual(1, len(blocks))
+
+
+class ParseCommentBlock(ScanSourceContentTestCase):
+
+ def test_EmptyInput(self):
+ mkdb.ParseCommentBlock([])
+ self.assertEqual({}, mkdb.SourceSymbolDocs)
+
+ def test_FindsDocComment(self):
+ mkdb.ParseCommentBlock(textwrap.dedent("""\
+ symbol:
+
+ Description.
+ """).splitlines(keepends=True))
+ self.assertEqual({'symbol': 'Description.\n'}, mkdb.SourceSymbolDocs)
+
+ def test_FindsDocCommentWithParam(self):
+ mkdb.ParseCommentBlock(textwrap.dedent("""\
+ symbol:
+ @par: value
+
+ Description.
+ """).splitlines(keepends=True))
+ self.assertEqual({'symbol': 'Description.\n'}, mkdb.SourceSymbolDocs)
+ self.assertIn('symbol', mkdb.SourceSymbolParams)
+ self.assertEqual({'par': 'value\n'}, mkdb.SourceSymbolParams['symbol'])
+
+ def test_FindsDocCommentWithMultilineParam(self):
+ mkdb.ParseCommentBlock(textwrap.dedent("""\
+ symbol:
+ @par: value docs with
+ two lines
+
+ Description.
+ """).splitlines(keepends=True))
+ self.assertEqual({'symbol': 'Description.\n'}, mkdb.SourceSymbolDocs)
+ self.assertIn('symbol', mkdb.SourceSymbolParams)
+ self.assertEqual({'par': 'value docs with\ntwo lines\n'}, mkdb.SourceSymbolParams['symbol'])
+
+ def test_FindsDocCommentWithReturns(self):
+ mkdb.ParseCommentBlock(textwrap.dedent("""\
+ symbol:
+
+ Description.
+
+ Returns: result
+ """).splitlines(keepends=True))
+ # TODO: trim multiple newlines in code
+ self.assertEqual({'symbol': 'Description.\n\n'}, mkdb.SourceSymbolDocs)
+ self.assertIn('symbol', mkdb.SourceSymbolParams)
+ # TODO: trim whitespace in code
+ self.assertEqual({'Returns': ' result\n'}, mkdb.SourceSymbolParams['symbol'])
+
+ def test_FindsDocCommentWithSince(self):
+ mkdb.ParseCommentBlock(textwrap.dedent("""\
+ symbol:
+
+ Since: 0.1
+ """).splitlines(keepends=True))
+ self.assertIn('symbol', mkdb.Since)
+ self.assertEqual('0.1', mkdb.Since['symbol'])
+
+ def test_FindsDocCommentWithDeprecated(self):
+ mkdb.ParseCommentBlock(textwrap.dedent("""\
+ symbol:
+
+ Deprecated: use function() instead
+ """).splitlines(keepends=True))
+ self.assertIn('symbol', mkdb.Deprecated)
+ # TODO: trim whitespace in code
+ self.assertEqual(' use function() instead\n', mkdb.Deprecated['symbol'])
+
+ def test_FindsDocCommentWithStability(self):
+ mkdb.ParseCommentBlock(textwrap.dedent("""\
+ symbol:
+
+ Stability: stable
+ """).splitlines(keepends=True))
+ self.assertIn('symbol', mkdb.StabilityLevel)
+ self.assertEqual('Stable', mkdb.StabilityLevel['symbol'])
+
+ def test_HandlesHTMLEntities(self):
+ mkdb.ParseCommentBlock(textwrap.dedent("""\
+ symbol:
+
+ < & >.
+ """).splitlines(keepends=True))
+ self.assertEqual({'symbol': '< & >.\n'}, mkdb.SourceSymbolDocs)
+
+
+class ParseSectionCommentBlock(ScanSourceContentTestCase):
+
+ def test_FindsSectionBlock(self):
+ # TODO: maybe override common.LogWarning() instead and capture the messages
+ # Suppress: 'Section symbol is not defined in the test-sections.txt file'
+ mkdb.KnownSymbols['symbol:long_description'] = 1
+ mkdb.ParseCommentBlock(textwrap.dedent("""\
+ SECTION:symbol
+ @short_description: short module description
+
+ Module description.
+ """).splitlines(keepends=True))
+ self.assertIn('symbol:short_description', mkdb.SourceSymbolDocs)
+ self.assertEqual('short module description\n', mkdb.SourceSymbolDocs['symbol:short_description'])
+ self.assertIn('symbol:long_description', mkdb.SourceSymbolDocs)
+ self.assertEqual('Module description.\n', mkdb.SourceSymbolDocs['symbol:long_description'])
+
+ # TODO(ensonic): we need to refactor the code first (see comment there)
+ # def test_FindsProgramBlock(self):
+ # mkdb.ParseCommentBlock(textwrap.dedent("""\
+ # PROGRAM:symbol
+ # @short_description: short program description
+ # @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
+ #
+ # Program description.
+ # """).splitlines(keepends=True))
+ # self.assertIn('symbol:short_description', mkdb.SourceSymbolDocs)
+ # self.assertEqual('short program description\n', mkdb.SourceSymbolDocs['symbol:short_description'])
+ # self.assertIn('symbol:long_description', mkdb.SourceSymbolDocs)
+ # self.assertEqual('Program description.\n', mkdb.SourceSymbolDocs['symbol:long_description'])
+
+
+class ScanSourceContentAnnotations(ScanSourceContentTestCase):
+
+ def test_ParamAnnotation(self):
+ mkdb.ParseCommentBlock(textwrap.dedent("""\
+ symbol:
+ @par: (allow-none): value
+
+ description.
+ """).splitlines(keepends=True))
+ # TODO: we only extract those when outputting docbook, thats silly
+ # self.assertEqual({'par': 'value\n'}, mkdb.SourceSymbolParams['symbol'])
+ self.assertEqual({}, mkdb.SymbolAnnotations)
+
+ def test_RetunsAnnotation(self):
+ mkdb.ParseCommentBlock(textwrap.dedent("""\
+ symbol:
+
+ description.
+
+ Returns: (transfer full) result.
+ """).splitlines(keepends=True))
+ # TODO: we only extract those when outputting docbook, thats silly
+ self.assertEqual({}, mkdb.SymbolAnnotations)
+
+ # multiple annotations, multiline annotations, symbol-level ...
+
+
+if __name__ == '__main__':
+ unittest.main()
#
import logging
+import textwrap
import unittest
+from anytree import PreOrderIter
from lxml import etree
+from parameterized import parameterized
from gtkdoc import mkhtml2
class TestChunking(unittest.TestCase):
- def setUp(self):
- logging.basicConfig(
- level=logging.INFO,
- format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s')
+ # def setUp(self):
+ # logging.basicConfig(
+ # level=logging.INFO,
+ # format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s')
def test_chunk_only_root_gives_single_chunk(self):
root = etree.XML('<book />')
self.assertEqual(2, len(descendants))
+class TestDataExtraction(unittest.TestCase):
+
+ # def setUp(self):
+ # logging.basicConfig(
+ # level=logging.INFO,
+ # format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s')
+
+ def chunk_db(self, xml):
+ root = etree.XML(xml)
+ files = mkhtml2.chunk(root, 'test')
+ return [f for f in PreOrderIter(files) if f.anchor is None]
+
+ def test_extract_ids(self):
+ files = self.chunk_db('<book><chapter id="chap1"></chapter></book>')
+ links = {}
+ mkhtml2.add_id_links_and_titles(files, links)
+ self.assertIn('chap1', links)
+
+ def test_extract_titles(self):
+ files = self.chunk_db('<book><chapter id="chap1"><title>Intro</title></chapter></book>')
+ links = {}
+ mkhtml2.add_id_links_and_titles(files, links)
+ self.assertIn('chap1', mkhtml2.titles)
+ self.assertEqual('Intro', mkhtml2.titles['chap1']['title'])
+ self.assertEqual('chapter', mkhtml2.titles['chap1']['tag'])
+
+ def test_extract_glossaries(self):
+ files = self.chunk_db(textwrap.dedent("""\
+ <book>
+ <glossary id="glossary">
+ <glossentry>
+ <glossterm><anchor id="glossterm-API"/>API</glossterm>
+ <glossdef>
+ <para>Application Programming Interface</para>
+ </glossdef>
+ </glossentry>
+ </glossary>
+ </book>"""))
+ mkhtml2.build_glossary(files)
+ self.assertIn('API', mkhtml2.glossary)
+ self.assertEqual('Application Programming Interface', mkhtml2.glossary['API'])
+
+
+class TestDevhelp(unittest.TestCase):
+
+ xml_minimal = textwrap.dedent("""\
+ <book>
+ <chapter id="chap1"><title>Intro</title></chapter>
+ </book>""")
+
+ xml_basic = textwrap.dedent("""\
+ <book>
+ <bookinfo>
+ <title>test Reference Manual</title>
+ <releaseinfo>
+ The latest version of this documentation can be found on-line at
+ <ulink role="online-location" url="http://www.example.com/tester/index.html">online-site</ulink>.
+ </releaseinfo>
+ </bookinfo>
+ <chapter id="chap1"><title>Intro</title></chapter>
+ </book>""")
+
+ # TODO: need one with multiple conditions
+ xml_full = textwrap.dedent("""\
+ <book>
+ <bookinfo>
+ <title>test Reference Manual</title>
+ </bookinfo>
+ <chapter id="chap1">
+ <title>Reference</title>
+ <refentry id="GtkdocObject">
+ <refmeta>
+ <refentrytitle role="top_of_page" id="GtkdocObject.top_of_page">GtkdocObject</refentrytitle>
+ <refmiscinfo>TESTER Library</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>GtkdocObject</refname>
+ <refpurpose>class for gtk-doc unit test</refpurpose>
+ </refnamediv>
+ <refsect1 id="GtkdocObject.functions" role="functions_proto">
+ <title role="functions_proto.title">Functions</title>
+ </refsect1>
+ <refsect1 id="GtkdocObject.functions_details" role="details">
+ <title role="details.title">Functions</title>
+ <refsect2 id="gtkdoc-object-new" role="function" condition="since:0.1">
+ <title>gtkdoc_object_new ()</title>
+ <refsect3 id="GtkdocObjectClass.members" role="struct_members">
+ <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>
+ <row role="member">
+ <entry role="struct_member_name">
+ <para>
+ GtkdocObjectClass
+ <structfield id="GtkdocObjectClass.parent">parent</structfield>;
+ </para>
+ </entry>
+ <entry role="struct_member_description">
+ <para>parent/</para>
+ </entry>
+ <entry role="struct_member_annotations"></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect3>
+ </refsect2>
+ </refsect1>
+ <refsect1 id="tester-GtkdocTypes.other_details" role="details">
+ <title role="details.title">Types and Values</title>
+ <refsect2 id="GtkdocEnum" role="enum">
+ <title>enum GtkdocEnum</title>
+ <indexterm zone="GtkdocEnum">
+ <primary>GtkdocEnum</primary>
+ </indexterm>
+ <para>Enum values for the <link linkend="GtkdocEnum"><type>GtkdocEnum</type>
+ </link> type.</para>
+ <refsect3 id="GtkdocEnum.members" role="enum_members">
+ <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>
+ <row role="constant">
+ <entry role="enum_member_name">
+ <para id="GTKDOC-ENUM-V1:CAPS">GTKDOC_ENUM_V1</para>
+ </entry>
+ <entry role="enum_member_description">
+ <para>first</para>
+ </entry>
+ <entry role="enum_member_annotations"></entry>
+ </row>
+ <row role="constant">
+ <entry role="enum_member_name">
+ <para id="GTKDOC-ENUM-V2:CAPS">GTKDOC_ENUM_V2</para>
+ </entry>
+ <entry role="enum_member_description">
+ <para>second Since: 0.5</para>
+ </entry>
+ <entry role="enum_member_annotations"></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect3>
+ </refsect2>
+ </refsect1>
+ </refentry>
+ </chapter>
+ </book>""")
+
+ # def setUp(self):
+ # logging.basicConfig(
+ # level=logging.INFO,
+ # format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s')
+
+ def convert(self, xml):
+ root = etree.XML(xml)
+ files = mkhtml2.chunk(root, 'test')
+ files = [f for f in PreOrderIter(files) if f.anchor is None]
+ mkhtml2.add_id_links_and_titles(files, {})
+ return '\n'.join(mkhtml2.create_devhelp2_content('test', root, files))
+
+ def test_create_devhelp_has_minimal_structure(self):
+ devhelp = self.convert(self.xml_minimal)
+ self.assertIn('<book xmlns', devhelp)
+ self.assertIn('<chapters', devhelp)
+ self.assertIn('<functions', devhelp)
+
+ def test_create_devhelp_without_bookinfo(self):
+ devhelp = self.convert(self.xml_minimal)
+ self.assertNotIn('online', devhelp)
+
+ def test_create_devhelp_with_bookinfo(self):
+ devhelp = self.convert(self.xml_basic)
+ self.assertIn('online="http://www.example.com/tester/index.html"', devhelp)
+ self.assertIn('title="test Reference Manual"', devhelp)
+
+ def test_create_devhelp_with_refentry_has_chapters(self):
+ devhelp = self.convert(self.xml_full)
+ self.assertIn('<sub name="Reference" link="chap1.html">', devhelp)
+ self.assertIn('<sub name="GtkdocObject" link="GtkdocObject.html"/>', devhelp)
+
+ def test_create_devhelp_with_refentry_has_keywords(self):
+ devhelp = self.convert(self.xml_full)
+ self.assertIn(
+ '<keyword type="function" name="gtkdoc_object_new ()" '
+ 'link="GtkdocObject.html#gtkdoc-object-new" since="0.1"/>',
+ devhelp)
+
+ def test_create_devhelp_with_refesect3_has_member_keywords(self):
+ devhelp = self.convert(self.xml_full)
+ self.assertIn(
+ '<keyword type="member" name="GtkdocObjectClass.parent" '
+ 'link="GtkdocObject.html#GtkdocObjectClass.parent"/>',
+ devhelp)
+
+ def test_create_devhelp_with_refesect3_has_constant_keywords(self):
+ devhelp = self.convert(self.xml_full)
+ self.assertIn(
+ '<keyword type="constant" name="GTKDOC_ENUM_V1" '
+ 'link="GtkdocObject.html#GTKDOC-ENUM-V1:CAPS"/>',
+ devhelp)
+
+
+class TestNavNodes(unittest.TestCase):
+
+ # def setUp(self):
+ # logging.basicConfig(
+ # level=logging.INFO,
+ # format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s')
+
+ def chunk_db(self, xml):
+ root = etree.XML(xml)
+ files = mkhtml2.chunk(root, 'test')
+ return [f for f in PreOrderIter(files) if f.anchor is None]
+
+ def test_nav_nodes_contains_home(self):
+ files = self.chunk_db(textwrap.dedent("""\
+ <book>
+ </book>"""))
+ nav = mkhtml2.generate_nav_nodes(files, files[0])
+ self.assertEqual(1, len(nav))
+ self.assertIn('nav_home', nav)
+
+ def test_nav_nodes_contains_up_and_prev(self):
+ files = self.chunk_db(textwrap.dedent("""\
+ <book>
+ <chapter id="chap1"><title>Intro</title></chapter>
+ </book>"""))
+ nav = mkhtml2.generate_nav_nodes(files, files[1])
+ self.assertEqual(3, len(nav))
+ self.assertIn('nav_up', nav)
+ self.assertIn('nav_prev', nav)
+ self.assertNotIn('nav_next', nav)
+
+ def test_nav_nodes_contains_next(self):
+ files = self.chunk_db(textwrap.dedent("""\
+ <book>
+ <chapter id="chap1"><title>Intro</title></chapter>
+ <chapter id="chap2"><title>Content</title></chapter>
+ </book>"""))
+ nav = mkhtml2.generate_nav_nodes(files, files[1])
+ self.assertEqual(4, len(nav))
+ self.assertIn('nav_next', nav)
+
+
+class TestConverter(unittest.TestCase):
+
+ xml_book_beg = textwrap.dedent("""\
+ <book>
+ <bookinfo>
+ <title>test Reference Manual</title>
+ </bookinfo>""")
+ xml_book_end = textwrap.dedent("""\
+ </book>""")
+ xml_book = '\n'.join([xml_book_beg, xml_book_end])
+
+ xml_book_preface = '\n'.join([
+ xml_book_beg,
+ ' <preface id="intro"><title>Intro</title></preface>',
+ xml_book_end])
+
+ xml_book_chapter = '\n'.join([
+ xml_book_beg,
+ ' <chapter id="chap1"><title>Intro</title></chapter>',
+ xml_book_end])
+
+ xml_book_reference = '\n'.join([
+ xml_book_beg,
+ ' <reference id="part.i"><title>Reference</title></reference>',
+ xml_book_end])
+
+ xml_book_part_chapter = '\n'.join([
+ xml_book_beg,
+ textwrap.dedent("""\
+ <part label="1" id="part.i">
+ <title>Overview</title>
+ <chapter id="chap1"><title>Intro</title></chapter>
+ </part>"""),
+ xml_book_end])
+
+ # 2 sections since the first one is not chunked
+ xml_book_chapter_secton = '\n'.join([
+ xml_book_beg,
+ textwrap.dedent("""\
+ <chapter id="chap1">
+ <title>Overview</title>
+ <section id="s1"><title>Intro</title></section>
+ <section id="s2"><title>getting started</title></section>
+ </chapter>"""),
+ xml_book_end])
+ xml_book_chapter_sect1 = xml_book_chapter_secton.replace('section', 'sect1')
+
+ xml_book_chapter_refentry_beg = '\n'.join([
+ xml_book_beg,
+ textwrap.dedent("""\
+ <chapter id="chap1">
+ <title>Reference</title>
+ <refentry id="GtkdocObject">
+ <refmeta>
+ <refentrytitle role="top_of_page" id="GtkdocObject.top_of_page">GtkdocObject</refentrytitle>
+ </refmeta>""")])
+
+ xml_book_chapter_refentry_end = '\n'.join([
+ textwrap.dedent("""\
+ </refentry>
+ </chapter>"""),
+ xml_book_end])
+ xml_book_chapter_refentry = '\n'.join([xml_book_chapter_refentry_beg, xml_book_chapter_refentry_end])
+
+ xml_book_index_empty = '\n'.join([
+ xml_book_beg,
+ ' <index id="api-index-full"><title>API Index</title></index>',
+ xml_book_end])
+
+ xml_book_index = '\n'.join([
+ xml_book_beg,
+ textwrap.dedent("""\
+ <index id="api-index-full">
+ <title>API Index</title>
+ <indexdiv id="api-index-full">
+ <indexdiv><title>O</title>
+ <!-- we get a link warning, since we we don't include the 'refentry' -->
+ <!--indexentry>
+ <primaryie linkends="gtkdoc-object-new">
+ <link linkend="gtkdoc-object-new">gtkdoc_object_new</link>,
+ function in <link linkend="GtkdocObject">GtkdocObject</link>
+ </primaryie>
+ </indexentry-->
+ </indexdiv>
+ </indexdiv>
+ </index>"""),
+ xml_book_end])
+
+ xml_book_glossary_empty = '\n'.join([
+ xml_book_beg,
+ ' <glossary id="glossary"><title>Glossary</title></glossary>',
+ xml_book_end])
+
+ xml_book_glossary = '\n'.join([
+ xml_book_beg,
+ textwrap.dedent("""\
+ <glossary id="glossary">
+ <title>Glossary</title>
+ <glossdiv><title>A</title>
+ <glossentry>
+ <glossterm><anchor id="glossterm-API"/>API</glossterm>
+ <glossdef>
+ <para>Application Programming Interface</para>
+ </glossdef>
+ </glossentry>
+ </glossdiv>
+ </glossary>"""),
+ xml_book_end])
+
+ # def setUp(self):
+ # logging.basicConfig(
+ # level=logging.INFO,
+ # format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s')
+
+ def convert(self, xml, ix):
+ root = etree.XML(xml)
+ files = mkhtml2.chunk(root, 'test')
+ nodes = [f for f in PreOrderIter(files) if f.anchor is None]
+ return '\n'.join(mkhtml2.convert_content('test', nodes, nodes[ix], 'c'))
+
+ @parameterized.expand([
+ ('book', (xml_book, 0)),
+ ('preface', (xml_book_preface, 1)),
+ ('reference', (xml_book_reference, 1)),
+ ('chapter', (xml_book_chapter, 1)),
+ ('part', (xml_book_part_chapter, 1)),
+ ('section', (xml_book_chapter_secton, 2)),
+ ('sect1', (xml_book_chapter_sect1, 2)),
+ ('refentry', (xml_book_chapter_refentry, 2)),
+ ('index', (xml_book_index, 1)),
+ ('index_empty', (xml_book_index_empty, 1)),
+ ('glossary', (xml_book_glossary, 1)),
+ ('glossary_empty', (xml_book_glossary_empty, 1)),
+ ])
+ def test_convert_produces_html(self, _, params):
+ html = self.convert(params[0], params[1])
+ self.assertIn('<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">', html)
+ self.assertIn('<html>', html)
+ self.assertIn('</html>', html)
+
+ def test_convert_book_has_title(self):
+ html = self.convert(self.xml_book, 0)
+ self.assertIn('<title>test Reference Manual</title>', html)
+
+ def test_refnav_includes_normal_refsect1(self):
+ xml = '\n'.join([
+ self.xml_book_chapter_refentry_beg,
+ textwrap.dedent("""\
+ <refsect1 id="GtkdocObject.description" role="desc">
+ <title role="desc.title">Description</title>
+ </refsect1>
+ """),
+ self.xml_book_chapter_refentry_end])
+ html = self.convert(xml, 2)
+ self.assertIn('class="shortcut">Description</a>', html)
+
+ def test_refnav_skips_protos_refsect1(self):
+ xml = '\n'.join([
+ self.xml_book_chapter_refentry_beg,
+ textwrap.dedent("""\
+ <refsect1 id="GtkdocObject.functions" role="functions_proto">
+ <title role="functions_proto.title">Functions</title>
+ </refsect1>
+ """),
+ self.xml_book_chapter_refentry_end])
+ html = self.convert(xml, 2)
+ self.assertNotIn('class="shortcut">Functions</a>', html)
+
+
if __name__ == '__main__':
unittest.main()
host_triplet = @host@
subdir = tests/program
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files=
host_triplet = @host@
subdir = tests/program/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files =
@BUILD_TESTS_TRUE@noinst_PROGRAMS = test-program$(EXEEXT)
subdir = tests/program/src
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
host_triplet = @host@
subdir = tests/repro
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files=
host_triplet = @host@
subdir = tests/repro/docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files =
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# SGML files where gtk-doc abbreviations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files =
host_triplet = @host@
subdir = tests/repro/src
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
-am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \
+am__aclocal_m4_deps = $(top_srcdir)/m4/ax_python_module.m4 \
+ $(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 \
FOP = @FOP@
GREP = @GREP@
HELP_DIR = @HELP_DIR@
-HIGHLIGHT = @HIGHLIGHT@
-HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
psdir = @psdir@
pyexecdir = @pyexecdir@
pythondir = @pythondir@
+runstatedir = @runstatedir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
--- /dev/null
+#!/bin/sh
+
+suite=$1
+dir=$BUILDDIR
+
+failed=0
+tested=0
+
+echo "Running suite(s): gtk-doc-sanity $suite";
+
+# check the presence and non-emptyness of certain files
+nok=0
+for path in $dir/$suite/docs/html; do
+ if test ! -s $path/index.html ; then
+ echo 1>&2 "no or empty $path/index.html"
+ nok=`expr $nok + 1`; break;
+ fi
+ if test ! -s $path/home.png ; then
+ echo 1>&2 "no or empty $path/home.png"
+ nok=`expr $nok + 1`; break;
+ fi
+ file=`echo $path/*.devhelp2`
+ if test ! -s $file ; then
+ echo 1>&2 "no or empty $file"
+ nok=`expr $nok + 1`; break;
+ fi
+done
+if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
+tested=`expr $tested + 1`
+
+# TODO: if we have pdf support check for ./tests/$suite/docs/tester.pdf
+nok=0
+for path in $dir/$suite/docs; do
+ if test ! -s $path/tester.pdf ; then
+ if test -s $path/gtkdoc-mkpdf.log; then
+ if ! grep >/dev/null 2>&1 "must be installed to use gtkdoc-mkpdf" $path/gtkdoc-mkpdf.log; then
+ echo 1>&2 "no or empty $path/tester.pdf"
+ nok=`expr $nok + 1`; break;
+ fi
+ fi
+ fi
+done
+if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
+tested=`expr $tested + 1`
+
+# check validity of generated xml files
+nok=0
+for file in $dir/$suite/docs/xml/*.xml; do
+ xmllint --noout --noent $file
+ if test $? != 0 ; then
+ echo 1>&2 "xml validity check failed for $file"
+ nok=`expr $nok + 1`;
+ fi
+done
+if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
+tested=`expr $tested + 1`
+
+
+# check validity of generated sgml files
+nok=0
+for file in $dir/$suite/docs/xml/*.sgml; do
+ xmllint --noout --noent $file
+ if test $? != 0 ; then
+ echo 1>&2 "sgml validity check failed for $file"
+ nok=`expr $nok + 1`;
+ fi
+done
+if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
+tested=`expr $tested + 1`
+
+# check validity of devhelp2 files
+nok=0
+for file in $dir/$suite/docs/html/*.devhelp2; do
+ xmllint --noout --nonet --schema $ABS_TOP_SRCDIR/devhelp2.xsd $file
+ if test $? != 0 ; then
+ echo 1>&2 "devhelp2 xml validity check failed for $file"
+ nok=`expr $nok + 1`;
+ fi
+done
+if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
+tested=`expr $tested + 1`
+
+# check that log files have only one line (the command)
+# discard references to launchapd bugs
+nok=0
+DISCARD_PATTERN='Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/[0-9]* . For now run:
+gunzip .*.gz
+
+'
+for file in $dir/$suite/docs/gtkdoc-*.log; do
+ # skip this in verbose mode as we'll have more text
+ if test "x${V}" = "x1"; then
+ continue
+ fi
+
+ expected_lines="1"
+ # adjust for known files
+ if test $file = "$dir/bugs/docs/gtkdoc-mkdb.log"; then
+ expected_lines="2"
+ fi
+ if test $file = "$dir/gobject/docs/gtkdoc-fixxref.log"; then
+ expected_lines="2"
+ fi
+ case $file in
+ *gtkdoc-fixxref.log)
+ # if there is no /usr/share/gtk-doc/html/gobject we should skip fixxref logs
+ if test ! -d "$GLIB_PREFIX/share/gtk-doc/html/gobject"; then
+ continue
+ fi
+ ;;
+ esac
+
+ lines=`grep -v -x -G -e "$DISCARD_PATTERN" $file | wc -l | cut -d' ' -f1`
+ if test $lines -gt $expected_lines; then
+ echo 1>&2 "expected no more than $expected_lines log line in $file, but got $lines"
+ nok=`expr $nok + 1`;
+ fi
+done
+if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
+tested=`expr $tested + 1`
+
+# check stability of generated xml/html
+nok=0
+for path in $dir/$suite/docs*; do
+ if test -d $path/xml.ref; then
+ diff -u $path/xml.ref $path/xml
+ if test $? = 1 ; then
+ echo 1>&2 "difference in generated xml for $path"
+ nok=`expr $nok + 1`;
+ fi
+ fi
+ if test -d $path/html.ref; then
+ diff -u $path/html.ref $path/html
+ if test $? = 1 ; then
+ echo 1>&2 "difference in generated html for $path"
+ nok=`expr $nok + 1`;
+ fi
+ fi
+done
+if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi
+tested=`expr $tested + 1`
+
+
+# summary
+successes=`expr $tested - $failed`
+rate=`expr 100 \* $successes / $tested`;
+echo "$rate %: Checks $tested, Failures: $failed"
+
+test $failed = 0
+exit $?
--- /dev/null
+# -*- python -*-
+#
+# gtk-doc - GTK DocBook documentation generator.
+# Copyright (C) 2018 Stefan Sauer
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+
+import argparse
+import textwrap
+import unittest
+
+from parameterized import parameterized
+
+from gtkdoc import scan
+
+
+BASIC_TYPES = [
+ "char",
+ "signed char",
+ "unsigned char",
+ "short",
+ "signed short",
+ "unsigned short",
+ "long",
+ "signed long",
+ "unsigned long",
+ "int",
+ "signed int",
+ "unsigned int",
+ "short int",
+ "signed short int",
+ "unsigned short int",
+ "long int",
+ "signed long int",
+ "unsigned long int",
+ "signed",
+ "unsigned",
+ "float",
+ "double",
+ "long double",
+ "enum e",
+ "struct s",
+ "union u",
+]
+
+BASIC_TYPES_WITH_VOID = ['void'] + BASIC_TYPES
+
+INLINE_MODIFIERS = [('g_inline', 'G_INLINE_FUNC'), ('static_inline', 'static inline')]
+
+
+class ScanHeaderContentTestCase(unittest.TestCase):
+ """Baseclass for the header scanner tests."""
+
+ def setUp(self):
+ self.decls = []
+ self.types = []
+ self.options = argparse.Namespace(
+ deprecated_guards='GTKDOC_TESTER_DISABLE_DEPRECATED',
+ ignore_decorators='',
+ rebuild_types=False)
+
+ def scanHeaderContent(self, content):
+ return scan.ScanHeaderContent(content, self.decls, self.types,
+ self.options)
+
+ def assertNoDeclFound(self, slist):
+ self.assertEqual([], slist)
+ self.assertEqual([], self.decls)
+ self.assertEqual([], self.types)
+
+ def assertNothingFound(self, slist, doc_comments):
+ self.assertEqual({}, doc_comments)
+ self.assertNoDeclFound(slist)
+
+
+class ScanHeaderContent(ScanHeaderContentTestCase):
+ """Test generic scanner behaviour."""
+
+ def test_EmptyInput(self):
+ slist, doc_comments = self.scanHeaderContent([])
+ self.assertNothingFound(slist, doc_comments)
+
+ def test_IgnoresOneLineComments(self):
+ slist, doc_comments = self.scanHeaderContent(['/* test */'])
+ self.assertNothingFound(slist, doc_comments)
+
+ def test_IgnoresOneLineCommentsDoubleStar(self):
+ slist, doc_comments = self.scanHeaderContent(['/** test */'])
+ self.assertNothingFound(slist, doc_comments)
+
+ def test_FindsDocComment(self):
+ slist, doc_comments = self.scanHeaderContent("""\
+ /**
+ * Symbol:
+ */""".splitlines(keepends=True))
+ self.assertEqual(1, len(doc_comments))
+ self.assertIn('symbol', doc_comments)
+
+ def test_DocDoesNotChangeSlistDeclAndTypes(self):
+ slist, doc_comments = self.scanHeaderContent("""\
+ /**
+ * Symbol:
+ */""".splitlines(keepends=True))
+ self.assertNoDeclFound(slist)
+
+ def test_SkipInternalHeaders(self):
+ header = textwrap.dedent("""\
+ /* < private_header > */
+ /**
+ * symbol:
+ */
+ void symbols(void);""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertNothingFound(slist, doc_comments)
+
+ def test_SkipSymbolWithPreprocessor(self):
+ slist, doc_comments = self.scanHeaderContent("""\
+ #ifndef __GTK_DOC_IGNORE__
+ extern int bug_512565(void);
+ #endif""".splitlines(keepends=True))
+ self.assertNoDeclFound(slist)
+
+ def test_AddDeprecatedFlagForSymbolsWithinDeprecationGuards(self):
+ header = textwrap.dedent("""\
+ #ifndef GTKDOC_TESTER_DISABLE_DEPRECATED
+ /**
+ * SYMBOL:
+ *
+ * Deprecated: 1.1. Use NEW_SYMBOL instead.
+ */
+ #define SYMBOL "value"
+ #endif /* GTKDOC_TESTER_DISABLE_DEPRECATED */""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertEqual(1, len(self.decls))
+ self.assertIn('<DEPRECATED/>', self.decls[0])
+
+ def test_NoDeprecatedFlagForSymbolsOutsideDeprecationGuards(self):
+ header = textwrap.dedent("""\
+ #ifndef GTKDOC_TESTER_DISABLE_DEPRECATED
+ /**
+ * SYMBOL1:
+ *
+ * Deprecated: 1.1. Use NEW_SYMBOL1 instead.
+ */
+ #define SYMBOL1 "value"
+ #endif /* GTKDOC_TESTER_DISABLE_DEPRECATED */
+ /**
+ * SYMBOL2:
+ */
+ #define SYMBOL2 "value"
+ """)
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertEqual(2, len(self.decls))
+ self.assertNotIn('<DEPRECATED/>', self.decls[1])
+
+
+class ScanHeaderContentEnum(ScanHeaderContentTestCase):
+ """Test parsing of enum declarations."""
+
+ def assertDecl(self, name, decl, slist):
+ self.assertEqual([name], slist)
+ d = '<ENUM>\n<NAME>%s</NAME>\n%s</ENUM>\n' % (name, decl)
+ self.assertEqual([d], self.decls)
+ self.assertEqual([], self.types)
+
+ def test_FindsEnum(self):
+ header = textwrap.dedent("""\
+ enum data {
+ TEST,
+ };""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('data', header, slist)
+
+ def test_FindsTypedefEnum(self):
+ header = textwrap.dedent("""\
+ typedef enum {
+ ENUM
+ } Data;""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('Data', header, slist)
+
+ def test_HandleEnumWithDeprecatedMember(self):
+ header = textwrap.dedent("""\
+ enum data {
+ TEST_A,
+ #ifndef GTKDOC_TESTER_DISABLE_DEPRECATED
+ TEST_B,
+ #endif
+ TEST_C
+ };""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('data', header, slist)
+
+ def test_HandleDeprecatedInMemberName(self):
+ header = textwrap.dedent("""\
+ typedef enum {
+ VAL_DEFAULT,
+ VAL_DEPRECATED,
+ } Data;""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('Data', header, slist)
+
+
+class ScanHeaderContentFunctions(ScanHeaderContentTestCase):
+ """Test parsing of function declarations."""
+
+ def assertDecl(self, name, ret, params, slist):
+ self.assertEqual([name], slist)
+ d = '<FUNCTION>\n<NAME>%s</NAME>\n<RETURNS>%s</RETURNS>\n%s\n</FUNCTION>\n' % (name, ret, params)
+ self.assertEqual([d], self.decls)
+ self.assertEqual([], self.types)
+
+ def test_FindsFunctionVoid(self):
+ header = 'void func();'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', 'void', '', slist)
+
+ def test_IgnoresInternalFunction(self):
+ slist, doc_comments = self.scanHeaderContent([
+ 'void _internal(void);'
+ ])
+ self.assertNoDeclFound(slist)
+
+ @parameterized.expand(INLINE_MODIFIERS)
+ def test_IgnoresInternalInlineFunction(self, _, modifier):
+ header = textwrap.dedent("""\
+ %s void _internal(void) {
+ }""" % modifier)
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertNoDeclFound(slist)
+
+ @parameterized.expand([(t.replace(' ', '_'), t) for t in BASIC_TYPES_WITH_VOID])
+ def test_HandlesReturnValue(self, _, ret_type):
+ header = '%s func(void);' % ret_type
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', ret_type, 'void', slist)
+
+ @parameterized.expand([(t.replace(' ', '_'), t) for t in BASIC_TYPES_WITH_VOID])
+ def test_HandlesReturnValuePtr(self, _, ret_type):
+ header = '%s* func(void);' % ret_type
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', ret_type + ' *', 'void', slist)
+
+ @parameterized.expand([(t.replace(' ', '_'), t) for t in BASIC_TYPES_WITH_VOID])
+ def test_HandlesReturnValueConstPtr(self, _, ret_type):
+ header = 'const %s* func(void);' % ret_type
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', 'const ' + ret_type + ' *', 'void', slist)
+
+ # TODO: also do parametrized?
+ def test_FindsFunctionConstCharPtConstPtr_Void(self):
+ header = 'const char* const * func(void);'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', 'const char * const *', 'void', slist)
+
+ @parameterized.expand([(t.replace(' ', '_'), t) for t in BASIC_TYPES])
+ def test_HandlesParameter(self, _, param_type):
+ header = 'void func(%s);' % param_type
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', 'void', param_type, slist)
+
+ @parameterized.expand([(t.replace(' ', '_'), t) for t in BASIC_TYPES])
+ def test_HandlesNamedParameter(self, _, param_type):
+ header = 'void func(%s a);' % param_type
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', 'void', param_type + ' a', slist)
+
+ def test_HandlesMultipleParameterd(self):
+ header = 'int func(char c, long l);'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', 'int', 'char c, long l', slist)
+
+ def test_FindsFunctionStruct_Void_WithLinebreakAfterRetType(self):
+ header = textwrap.dedent("""\
+ struct ret *
+ func (void);""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('func', 'struct ret *', 'void', slist)
+
+ def test_FindsFunctionStruct_Void_WithLinebreakAfterFuncName(self):
+ header = textwrap.dedent("""\
+ struct ret * func
+ (void);""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('func', 'struct ret *', 'void', slist)
+
+ def test_FindsFunctionVoid_Int_WithLinebreakAfterParamType(self):
+ header = textwrap.dedent("""\
+ void func (int
+ a);""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('func', 'void', 'int a', slist)
+
+ @parameterized.expand(INLINE_MODIFIERS)
+ def test_FindsInlineFunction(self, _, modifier):
+ header = textwrap.dedent("""\
+ %s void func (void)
+ {
+ }
+ """ % modifier)
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('func', 'void', 'void', slist)
+
+ @parameterized.expand(INLINE_MODIFIERS)
+ def test_FindsInlineFunctionWithNewlineAfterType(self, _, modifier):
+ header = textwrap.dedent("""\
+ %s void
+ func (void)
+ {
+ }
+ """ % modifier)
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('func', 'void', 'void', slist)
+
+ @parameterized.expand(INLINE_MODIFIERS)
+ def test_FindsInlineFunctionWithConditionalBody(self, _, modifier):
+ header = textwrap.dedent("""\
+ %s int
+ func (int a)
+ {
+ #if defined(__GNUC__) && (__GNUC__ >= 4) && defined(__OPTIMIZE__)
+ return a;
+ #else
+ return 0;
+ #endif
+ }
+ """ % modifier)
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('func', 'int', 'int a', slist)
+
+
+class ScanHeaderContentMacros(ScanHeaderContentTestCase):
+ """Test parsing of macro declarations."""
+
+ def assertDecl(self, name, decl, slist):
+ self.assertEqual([name], slist)
+ d = '<MACRO>\n<NAME>%s</NAME>\n%s</MACRO>\n' % (name, decl)
+ self.assertEqual([d], self.decls)
+ self.assertEqual([], self.types)
+
+ def test_FindsMacroNumber(self):
+ header = '#define FOO 1'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('FOO', header, slist)
+
+ def test_FindsMacroExpression(self):
+ header = '#define FOO (1 << 1)'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('FOO', header, slist)
+
+ def test_FindsMacroFunction(self):
+ header = '#define FOO(x) (x << 1)'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('FOO', header, slist)
+
+ def test_IgnoresInternalMacro(self):
+ slist, doc_comments = self.scanHeaderContent([
+ '#define _INTERNAL (a) (a)'
+ ])
+ self.assertNoDeclFound(slist)
+
+ def test_FindsDocCommentForDeprecationGuard(self):
+ header = textwrap.dedent("""\
+ /**
+ * GTKDOC_TESTER_DISABLE_DEPRECATED:
+ *
+ * Documentation for a deprecation guard.
+ */
+ #define GTKDOC_TESTER_DISABLE_DEPRECATED 1""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertEqual(1, len(doc_comments))
+ self.assertIn('gtkdoc_tester_disable_deprecated', doc_comments)
+ self.assertDecl('GTKDOC_TESTER_DISABLE_DEPRECATED',
+ '#define GTKDOC_TESTER_DISABLE_DEPRECATED 1', slist)
+
+
+class ScanHeaderContentStructs(ScanHeaderContentTestCase):
+ """Test parsing of struct declarations."""
+
+ def assertDecl(self, name, decl, slist):
+ self.assertEqual([name], slist)
+ d = '<STRUCT>\n<NAME>%s</NAME>\n%s</STRUCT>\n' % (name, decl)
+ self.assertEqual([d], self.decls)
+ self.assertEqual([], self.types)
+
+ def test_FindsStruct(self):
+ header = textwrap.dedent("""\
+ struct data {
+ int test;
+ };""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('data', header, slist)
+
+ def test_FindsTypedefStruct(self):
+ header = textwrap.dedent("""\
+ typedef struct {
+ int test;
+ } Data;""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('Data', header, slist)
+
+ def test_HandleStructWithDeprecatedMember(self):
+ header = textwrap.dedent("""\
+ struct data {
+ int test_a;
+ #ifndef GTKDOC_TESTER_DISABLE_DEPRECATED
+ int deprecated;
+ #endif
+ int test_b;
+ };""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('data', header, slist)
+
+ def test_IgnoresInternalStruct(self):
+ header = 'struct _internal *x;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertNoDeclFound(slist)
+
+ def test_IgnoresPrivteStruct(self):
+ header = 'struct _x;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertNoDeclFound(slist)
+
+ def test_OpaqueStructTypedefGeneratesEmptyDecl(self):
+ header = 'typedef struct _data data;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('data', '', slist)
+
+ def test_OpaqueStructGeneratesEmptyDecl(self):
+ header = 'struct data;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('data', header, slist)
+
+ def test_GetTitleFromGObjectClassStruct(self):
+ header = textwrap.dedent("""\
+ struct _GtkdocObjectClass {
+ GObjectClass parent;
+ };""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertIn('<TITLE>GtkdocObject</TITLE>', slist)
+
+
+class ScanHeaderContentUnions(ScanHeaderContentTestCase):
+ """Test parsing of union declarations."""
+
+ def assertDecl(self, name, decl, slist):
+ self.assertEqual([name], slist)
+ d = '<UNION>\n<NAME>%s</NAME>\n%s</UNION>\n' % (name, decl)
+ self.assertEqual([d], self.decls)
+ self.assertEqual([], self.types)
+
+ def test_FindsUnion(self):
+ header = textwrap.dedent("""\
+ union data {
+ int i;
+ float f;
+ };""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('data', header, slist)
+
+ def test_FindsTypedefUnion(self):
+ header = textwrap.dedent("""\
+ typedef union {
+ int i;
+ float f;
+ } Data;""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('Data', header, slist)
+
+ def test_IgnoresInternalUnion(self):
+ header = 'union _internal *x;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertNoDeclFound(slist)
+
+ def test_IgnoresPrivteStruct(self):
+ header = 'union _x x;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertNoDeclFound(slist)
+
+ def test_OpaqueUnionTypedefGeneratesEmptyDecl(self):
+ header = 'typedef union _data data;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('data', '', slist)
+
+ def test_OpaqueUnionGeneratesEmptyDecl(self):
+ header = 'union data;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('data', header, slist)
+
+
+class ScanHeaderContentUserFunction(ScanHeaderContentTestCase):
+ """Test parsing of function pointer declarations."""
+
+ def assertDecl(self, name, ret, params, slist):
+ self.assertEqual([name], slist)
+ d = '<USER_FUNCTION>\n<NAME>%s</NAME>\n<RETURNS>%s</RETURNS>\n%s</USER_FUNCTION>\n' % (name, ret, params)
+ self.assertEqual([d], self.decls)
+ self.assertEqual([], self.types)
+
+ def test_FindsFunctionVoid(self):
+ header = 'typedef void (*func)();'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', 'void', '', slist)
+
+ @parameterized.expand([(t.replace(' ', '_'), t) for t in BASIC_TYPES_WITH_VOID])
+ def test_HandlesReturnValue(self, _, ret_type):
+ header = 'typedef %s (*func)(void);' % ret_type
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', ret_type, 'void', slist)
+
+ @parameterized.expand([(t.replace(' ', '_'), t) for t in BASIC_TYPES_WITH_VOID])
+ def test_HandlesReturnValuePtr(self, _, ret_type):
+ header = 'typedef %s* (*func)(void);' % ret_type
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', ret_type + ' *', 'void', slist)
+
+ @parameterized.expand([(t.replace(' ', '_'), t) for t in BASIC_TYPES_WITH_VOID])
+ def test_HandlesReturnValueConstPtr(self, _, ret_type):
+ header = 'typedef const %s* (*func)(void);' % ret_type
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', 'const ' + ret_type + ' *', 'void', slist)
+
+ def test_FindsFunctionVoid_Int_WithLinebreakAfterTypedef(self):
+ header = textwrap.dedent("""\
+ typedef
+ void (*func) (int a);""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('func', 'void', 'int a', slist)
+
+ def test_FindsFunctionStruct_Void_WithLinebreakAfterRetType(self):
+ header = textwrap.dedent("""\
+ typedef struct ret *
+ (*func) (void);""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('func', 'struct ret *', 'void', slist)
+
+ # TODO: not found
+ # def test_FindsFunctionStruct_Void_WithLinebreakAfterFuncName(self):
+ # header = textwrap.dedent("""\
+ # typedef struct ret * (*func)
+ # (void);""")
+ # slist, doc_comments = self.scanHeaderContent(
+ # header.splitlines(keepends=True))
+ # self.assertDecl('func', 'struct ret *', 'void', slist)
+
+ def test_FindsFunctionVoid_Int_WithLinebreakAfterParamType(self):
+ header = textwrap.dedent("""\
+ typedef void (*func) (int
+ a);""")
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('func', 'void', 'int a', slist)
+
+ @parameterized.expand([('void', 'void'), ('const_int', 'const int')])
+ def test_FindsFunctionPointerVar(self, _, ret_type):
+ header = '%s (*func)();' % ret_type
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('func', ret_type, '', slist)
+
+
+class ScanHeaderContentVariabless(ScanHeaderContentTestCase):
+ """Test parsing of variable declarations."""
+
+ def assertDecl(self, name, decl, slist):
+ self.assertEqual([name], slist)
+ d = '<VARIABLE>\n<NAME>%s</NAME>\n%s</VARIABLE>\n' % (name, decl)
+ self.assertEqual([d], self.decls)
+ self.assertEqual([], self.types)
+
+ @parameterized.expand([(t.replace(' ', '_'), t) for t in BASIC_TYPES])
+ def test_FindsExternVar(self, _, var_type):
+ header = 'extern %s var;' % var_type
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('var', header, slist)
+
+ @parameterized.expand([(t.replace(' ', '_'), t) for t in BASIC_TYPES])
+ def test_FindsExternPtrVar(self, _, var_type):
+ header = 'extern %s* var;' % var_type
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('var', header, slist)
+
+ def test_FindsConstInt(self):
+ header = 'const int var = 42;'
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('var', header, slist)
+
+ def test_FindConstCharPtr(self):
+ header = 'const char* var = "foo";'
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ self.assertDecl('var', header, slist)
+
+
+class ScanHeaderContentTypedefs(ScanHeaderContentTestCase):
+ """Test parsing of typedef declarations."""
+
+ def assertDecl(self, name, decl, slist):
+ self.assertEqual([name], slist)
+ d = '<TYPEDEF>\n<NAME>%s</NAME>\n%s</TYPEDEF>\n' % (name, decl)
+ self.assertEqual([d], self.decls)
+ self.assertEqual([], self.types)
+
+ def test_FindsTypedefStructPointer(self):
+ header = 'typedef struct data *dataptr;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('dataptr', header, slist)
+
+ def test_FindsTypedefUnionPointer(self):
+ header = 'typedef union data *dataptr;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('dataptr', header, slist)
+
+ def test_FindsTypedef(self):
+ header = 'typedef unsigned int uint;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertDecl('uint', header, slist)
+
+ def test_SkipsEnumTypedefDifferentName(self):
+ header = 'typedef enum data dateenum;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertNoDeclFound(slist)
+
+ def test_SkipsEnumTypedefUnderscoreName(self):
+ header = 'typedef enum _data data;'
+ slist, doc_comments = self.scanHeaderContent([header])
+ self.assertNoDeclFound(slist)
+
+
+class SeparateSubSections(ScanHeaderContentTestCase):
+
+ def test_NoSymbolsGiveEmptyResult(self):
+ liststr = scan.SeparateSubSections([], {})
+ self.assertEqual('\n', liststr)
+
+ def test_CreatesStandardSectionFromIsObjectMacro(self):
+ header = textwrap.dedent("""\
+ #define GTKDOC_IS_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTKDOC_TYPE_OBJECT))
+ void gtkdoc_object_function(void);
+ """)
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ liststr = scan.SeparateSubSections(slist, doc_comments)
+ self.assertEqual(
+ ['gtkdoc_object_function', '<SUBSECTION Standard>', 'GTKDOC_IS_OBJECT'],
+ liststr.splitlines())
+
+ def test_CreatesStandardSectionFromIsObjectClassMacro(self):
+ header = textwrap.dedent("""\
+ #define GTKDOC_IS_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GTKDOC_TYPE_OBJECT))
+ void gtkdoc_object_function(void);
+ """)
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ liststr = scan.SeparateSubSections(slist, doc_comments)
+ self.assertEqual(
+ ['gtkdoc_object_function', '<SUBSECTION Standard>', 'GTKDOC_IS_OBJECT_CLASS'],
+ liststr.splitlines())
+
+ def test_CreatesStandardSectionFromGetTypeFunction(self):
+ header = textwrap.dedent("""\
+ GType gtkdoc_object_get_type(void) G_GNUC_CONST;
+ void gtkdoc_object_function(void);
+ """)
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ liststr = scan.SeparateSubSections(slist, doc_comments)
+ self.assertEqual(
+ ['gtkdoc_object_function', '<SUBSECTION Standard>', 'gtkdoc_object_get_type'],
+ liststr.splitlines())
+
+ def test_CreatesStandardSectionAllMacros(self):
+ header = textwrap.dedent("""\
+ #define GTKDOC_TYPE_OBJECT (gtkdoc_object_get_type())
+ #define GTKDOC_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), GTKDOC_TYPE_OBJECT, GtkdocObject))
+ #define GTKDOC_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), GTKDOC_TYPE_OBJECT, GtkdocObjectClass))
+ #define GTKDOC_IS_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), GTKDOC_TYPE_OBJECT))
+ #define GTKDOC_IS_OBJECT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), GTKDOC_TYPE_OBJECT))
+ #define GTKDOC_OBJECT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), GTKDOC_TYPE_OBJECT, GtkdocObjectClass))
+ """)
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ liststr = scan.SeparateSubSections(slist, doc_comments)
+ self.assertEqual(
+ ['<SUBSECTION Standard>', 'GTKDOC_IS_OBJECT', 'GTKDOC_IS_OBJECT_CLASS',
+ 'GTKDOC_OBJECT', 'GTKDOC_OBJECT_CLASS', 'GTKDOC_OBJECT_GET_CLASS',
+ 'GTKDOC_TYPE_OBJECT'],
+ liststr.splitlines())
+
+ def test_MovesSymbolIfUndocumented(self):
+ header = textwrap.dedent("""\
+ struct _GtkdocObject {
+ GObject parent;
+ };
+ GType gtkdoc_object_get_type(void) G_GNUC_CONST;
+ void gtkdoc_object_function(void);
+ """)
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ liststr = scan.SeparateSubSections(slist, doc_comments)
+ self.assertEqual(
+ ['gtkdoc_object_function', '<SUBSECTION Standard>', 'GtkdocObject', 'gtkdoc_object_get_type'],
+ liststr.splitlines())
+
+ def test_DoesNotMoveSymbolIfDocumented(self):
+ header = textwrap.dedent("""\
+ /**
+ * GtkdocObject:
+ *
+ * instance data of gtk-doc unit test class
+ */
+ struct _GtkdocObject {
+ GObject parent;
+ };
+ GType gtkdoc_object_get_type(void) G_GNUC_CONST;
+ void gtkdoc_object_function(void);
+ """)
+ slist, doc_comments = self.scanHeaderContent(
+ header.splitlines(keepends=True))
+ liststr = scan.SeparateSubSections(slist, doc_comments)
+ self.assertEqual(
+ ['GtkdocObject', 'gtkdoc_object_function', '<SUBSECTION Standard>', 'gtkdoc_object_get_type'],
+ liststr.splitlines())
+
+
+if __name__ == '__main__':
+ unittest.main()
+
+ # from gtkdoc import common
+ # common.setup_logging()
+ #
+ # t = ScanHeaderContentUserFunction()
+ # t.setUp()
+ # t.test_FindsFunctionStruct_Void_WithLinebreakAfterRetType()
projects / platform / upstream / gtk-doc.git / commitdiff