From df98e9462e2846aab4bf6a92f6a0296ae54fd0c5 Mon Sep 17 00:00:00 2001 From: DongHun Kwak Date: Tue, 27 Nov 2018 17:11:27 +0900 Subject: [PATCH] Imported Upstream version 1.29 Change-Id: I9b6f787deb476143703fd490daf201affdf892a4 Signed-off-by: DongHun Kwak --- Makefile.am | 15 +- Makefile.in | 83 +- NEWS | 31 + README | 59 +- TODO | 45 +- aclocal.m4 | 82 +- build-aux/compile | 11 +- build-aux/config.guess | 40 +- build-aux/config.sub | 29 +- build-aux/depcomp | 2 +- build-aux/install-sh | 25 +- build-aux/ltmain.sh | 37 +- build-aux/missing | 8 +- build-aux/test-driver | 8 +- buildsystems/autotools/Makefile.am | 20 + buildsystems/autotools/Makefile.in | 620 ++++ .../autotools/gtk-doc.flat.make | 1 + gtk-doc.m4 => buildsystems/autotools/gtk-doc.m4 | 0 .../autotools/gtk-doc.make | 1 + .../autotools/gtkdocize.in | 0 .../cmake}/GtkDocConfig.cmake.in | 0 .../cmake}/GtkDocConfigVersion.cmake.in | 0 .../cmake}/GtkDocScanGObjWrapper.cmake | 0 {cmake => buildsystems/cmake}/Makefile.am | 0 {cmake => buildsystems/cmake}/Makefile.in | 7 +- configure | 95 +- configure.ac | 13 +- gtkdoc-depscan.in | 0 gtkdoc-mkhtml.in | 0 gtkdoc-mkhtml2.in | 5 + gtkdoc-mkman.in | 0 gtkdoc-scangobj.in | 0 gtkdoc/check.py | 30 +- gtkdoc/common.py | 36 +- gtkdoc/config.py | 6 +- gtkdoc/fixxref.py | 126 +- gtkdoc/mkdb.py | 151 +- gtkdoc/mkhtml2.py | 1414 ++++++-- gtkdoc/mkpdf.py | 3 - gtkdoc/rebase.py | 21 +- gtkdoc/scan.py | 17 +- gtkdoc/scangobj.py | 4 +- help/Makefile.in | 1 - help/manual/C/index.docbook | 757 +++-- help/manual/Makefile.in | 1 - help/manual/bn_IN/index.docbook | 757 +++-- help/manual/cs/cs.po | 707 ++-- help/manual/cs/index.docbook | 696 +++- help/manual/de/de.po | 711 ++-- help/manual/de/index.docbook | 692 +++- help/manual/el/index.docbook | 651 +++- help/manual/en_GB/index.docbook | 735 ++-- help/manual/es/es.po | 713 ++-- help/manual/es/index.docbook | 690 +++- help/manual/fr/fr.po | 3591 ++++++++++++++------ help/manual/fr/index.docbook | 1028 ++++-- help/manual/gl/index.docbook | 757 +++-- help/manual/gu/index.docbook | 736 ++-- help/manual/pt_BR/index.docbook | 694 +++- help/manual/pt_BR/pt_BR.po | 741 ++-- help/manual/sl/index.docbook | 757 +++-- help/manual/sv/index.docbook | 724 +++- help/manual/sv/sv.po | 743 ++-- help/manual/ta/index.docbook | 726 ++-- help/manual/te/index.docbook | 726 ++-- help/manual/zh_CN/index.docbook | 752 ++-- m4/libtool.m4 | 33 +- tests/Makefile.am | 9 +- tests/Makefile.in | 32 +- tests/annotations.sh | 4 +- tests/annotations/Makefile.in | 1 - tests/annotations/docs/Makefile.am | 3 +- tests/annotations/docs/Makefile.in | 4 +- tests/annotations/src/Makefile.in | 1 - tests/bugs.sh | 4 +- tests/bugs/Makefile.in | 1 - tests/bugs/docs/Makefile.am | 3 +- tests/bugs/docs/Makefile.in | 4 +- tests/bugs/src/Makefile.in | 1 - tests/empty.sh | 4 +- tests/empty/Makefile.in | 1 - tests/empty/docs/Makefile.am | 3 +- tests/empty/docs/Makefile.in | 4 +- tests/empty/docs/tester-docs.xml | 5 +- tests/empty/src/Makefile.in | 1 - tests/fail/Makefile.in | 1 - tests/fail/docs/Makefile.am | 3 +- tests/fail/docs/Makefile.in | 4 +- tests/fail/src/Makefile.in | 1 - tests/gobject.sh | 4 +- tests/gobject/Makefile.in | 1 - tests/gobject/docs/Makefile.am | 3 +- tests/gobject/docs/Makefile.in | 4 +- tests/gobject/docs/tester-docs.xml | 8 +- tests/gobject/src/Makefile.in | 1 - tests/gobject/src/giface.c | 2 + tests/gobject/src/gobject.c | 5 +- tests/mk_to_db.py | 6 + tests/mkhtml2.py | 65 + tests/program.sh | 4 +- tests/program/Makefile.in | 1 - tests/program/docs/Makefile.am | 3 +- tests/program/docs/Makefile.in | 4 +- tests/program/src/Makefile.in | 1 - tests/repro/Makefile.in | 1 - tests/repro/docs/Makefile.am | 3 +- tests/repro/docs/Makefile.in | 4 +- tests/repro/src/Makefile.in | 1 - tests/sanity.sh | 154 - tests/tools.sh | 5 +- tests/tools.sh.in | 3 +- 111 files changed, 15581 insertions(+), 6960 deletions(-) create mode 100644 buildsystems/autotools/Makefile.am create mode 100644 buildsystems/autotools/Makefile.in rename gtk-doc.flat.make => buildsystems/autotools/gtk-doc.flat.make (99%) rename gtk-doc.m4 => buildsystems/autotools/gtk-doc.m4 (100%) rename gtk-doc.make => buildsystems/autotools/gtk-doc.make (99%) rename gtkdocize.in => buildsystems/autotools/gtkdocize.in (100%) mode change 100644 => 100755 rename {cmake => buildsystems/cmake}/GtkDocConfig.cmake.in (100%) rename {cmake => buildsystems/cmake}/GtkDocConfigVersion.cmake.in (100%) rename {cmake => buildsystems/cmake}/GtkDocScanGObjWrapper.cmake (100%) rename {cmake => buildsystems/cmake}/Makefile.am (100%) rename {cmake => buildsystems/cmake}/Makefile.in (99%) mode change 100644 => 100755 gtkdoc-depscan.in mode change 100644 => 100755 gtkdoc-mkhtml.in mode change 100644 => 100755 gtkdoc-mkhtml2.in mode change 100644 => 100755 gtkdoc-mkman.in mode change 100644 => 100755 gtkdoc-scangobj.in create mode 100755 tests/mkhtml2.py delete mode 100755 tests/sanity.sh diff --git a/Makefile.am b/Makefile.am index e23ed41..debfdfa 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,7 +1,7 @@ ## Process this file with automake to produce Makefile.in ACLOCAL_AMFLAGS=-I m4 ${ACLOCAL_FLAGS} -SUBDIRS = cmake help tests +SUBDIRS = buildsystems/autotools buildsystems/cmake help tests bin_SCRIPTS = \ gtkdoc-check \ @@ -14,8 +14,7 @@ bin_SCRIPTS = \ gtkdoc-mkpdf \ gtkdoc-rebase \ gtkdoc-scan \ - gtkdoc-scangobj \ - gtkdocize + gtkdoc-scangobj gtkdocdatadir = $(datadir)/gtk-doc/data gtkdocdata_DATA = \ @@ -23,8 +22,6 @@ gtkdocdata_DATA = \ version-greater-or-equal.xsl \ devhelp2.xsd \ devhelp2.xsl \ - gtk-doc.make \ - gtk-doc.flat.make \ style/home.png \ style/left.png \ style/left-insensitive.png \ @@ -54,18 +51,11 @@ pylibdata_DATA = \ pkgconfigdir = $(datadir)/pkgconfig pkgconfig_DATA = gtk-doc.pc -aclocaldir = $(datadir)/aclocal -aclocal_DATA = gtk-doc.m4 - -gtk-doc.flat.make: gtk-doc.make - @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ - EXTRA_DIST = \ MAINTAINERS \ $(gtkdocdata_DATA) \ $(pylibdata_DATA) \ gtk-doc.pc.in \ - gtk-doc.m4 \ gtk-doc.doap \ gtk-doc-fo.xsl \ doc/README \ @@ -81,7 +71,6 @@ EXTRA_DIST = \ COPYING-DOCS CLEANFILES = \ - gtk-doc.flat.make \ gtkdoc-checkc \ gtkdoc-depscanc \ gtkdoc-fixxrefc \ diff --git a/Makefile.in b/Makefile.in index cd55d13..07af564 100644 --- a/Makefile.in +++ b/Makefile.in @@ -106,7 +106,7 @@ mkinstalldirs = $(install_sh) -d CONFIG_CLEAN_FILES = gtk-doc.pc gtkdoc/config.py gtkdoc-check \ gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml \ gtkdoc-mkhtml2 gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase \ - gtkdoc-scan gtkdoc-scangobj gtkdocize + gtkdoc-scan gtkdoc-scangobj CONFIG_CLEAN_VPATH_FILES = am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; am__vpath_adj = case $$p in \ @@ -135,9 +135,8 @@ am__uninstall_files_from_dir = { \ || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ $(am__cd) "$$dir" && rm -f $$files; }; \ } -am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" \ - "$(DESTDIR)$(gtkdocdatadir)" "$(DESTDIR)$(pkgconfigdir)" \ - "$(DESTDIR)$(pylibdatadir)" +am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(gtkdocdatadir)" \ + "$(DESTDIR)$(pkgconfigdir)" "$(DESTDIR)$(pylibdatadir)" SCRIPTS = $(bin_SCRIPTS) AM_V_P = $(am__v_P_@AM_V@) am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) @@ -166,8 +165,7 @@ am__can_run_installinfo = \ n|no|NO) false;; \ *) (install-info --version) >/dev/null 2>&1;; \ esac -DATA = $(aclocal_DATA) $(gtkdocdata_DATA) $(pkgconfig_DATA) \ - $(pylibdata_DATA) +DATA = $(gtkdocdata_DATA) $(pkgconfig_DATA) $(pylibdata_DATA) RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \ distclean-recursive maintainer-clean-recursive am__recursive_targets = \ @@ -203,8 +201,7 @@ am__DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/gtk-doc.pc.in \ $(srcdir)/gtkdoc-mkhtml.in $(srcdir)/gtkdoc-mkhtml2.in \ $(srcdir)/gtkdoc-mkman.in $(srcdir)/gtkdoc-mkpdf.in \ $(srcdir)/gtkdoc-rebase.in $(srcdir)/gtkdoc-scan.in \ - $(srcdir)/gtkdoc-scangobj.in $(srcdir)/gtkdocize.in \ - $(top_srcdir)/build-aux/compile \ + $(srcdir)/gtkdoc-scangobj.in $(top_srcdir)/build-aux/compile \ $(top_srcdir)/build-aux/config.guess \ $(top_srcdir)/build-aux/config.sub \ $(top_srcdir)/build-aux/install-sh \ @@ -396,7 +393,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ @@ -406,7 +402,7 @@ top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS} -SUBDIRS = cmake help tests +SUBDIRS = buildsystems/autotools buildsystems/cmake help tests bin_SCRIPTS = \ gtkdoc-check \ gtkdoc-depscan \ @@ -418,8 +414,7 @@ bin_SCRIPTS = \ gtkdoc-mkpdf \ gtkdoc-rebase \ gtkdoc-scan \ - gtkdoc-scangobj \ - gtkdocize + gtkdoc-scangobj gtkdocdatadir = $(datadir)/gtk-doc/data gtkdocdata_DATA = \ @@ -427,8 +422,6 @@ gtkdocdata_DATA = \ version-greater-or-equal.xsl \ devhelp2.xsd \ devhelp2.xsl \ - gtk-doc.make \ - gtk-doc.flat.make \ style/home.png \ style/left.png \ style/left-insensitive.png \ @@ -457,14 +450,11 @@ pylibdata_DATA = \ pkgconfigdir = $(datadir)/pkgconfig pkgconfig_DATA = gtk-doc.pc -aclocaldir = $(datadir)/aclocal -aclocal_DATA = gtk-doc.m4 EXTRA_DIST = \ MAINTAINERS \ $(gtkdocdata_DATA) \ $(pylibdata_DATA) \ gtk-doc.pc.in \ - gtk-doc.m4 \ gtk-doc.doap \ gtk-doc-fo.xsl \ doc/README \ @@ -480,7 +470,6 @@ EXTRA_DIST = \ COPYING-DOCS CLEANFILES = \ - gtk-doc.flat.make \ gtkdoc-checkc \ gtkdoc-depscanc \ gtkdoc-fixxrefc \ @@ -595,8 +584,6 @@ gtkdoc-scan: $(top_builddir)/config.status $(srcdir)/gtkdoc-scan.in cd $(top_builddir) && $(SHELL) ./config.status $@ gtkdoc-scangobj: $(top_builddir)/config.status $(srcdir)/gtkdoc-scangobj.in cd $(top_builddir) && $(SHELL) ./config.status $@ -gtkdocize: $(top_builddir)/config.status $(srcdir)/gtkdocize.in - cd $(top_builddir) && $(SHELL) ./config.status $@ install-binSCRIPTS: $(bin_SCRIPTS) @$(NORMAL_INSTALL) @list='$(bin_SCRIPTS)'; test -n "$(bindir)" || list=; \ @@ -656,27 +643,6 @@ clean-libtool: distclean-libtool: -rm -f libtool config.lt -install-aclocalDATA: $(aclocal_DATA) - @$(NORMAL_INSTALL) - @list='$(aclocal_DATA)'; test -n "$(aclocaldir)" || list=; \ - if test -n "$$list"; then \ - echo " $(MKDIR_P) '$(DESTDIR)$(aclocaldir)'"; \ - $(MKDIR_P) "$(DESTDIR)$(aclocaldir)" || exit 1; \ - fi; \ - for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - echo "$$d$$p"; \ - done | $(am__base_list) | \ - while read files; do \ - echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(aclocaldir)'"; \ - $(INSTALL_DATA) $$files "$(DESTDIR)$(aclocaldir)" || exit $$?; \ - done - -uninstall-aclocalDATA: - @$(NORMAL_UNINSTALL) - @list='$(aclocal_DATA)'; test -n "$(aclocaldir)" || list=; \ - files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ - dir='$(DESTDIR)$(aclocaldir)'; $(am__uninstall_files_from_dir) install-gtkdocdataDATA: $(gtkdocdata_DATA) @$(NORMAL_INSTALL) @list='$(gtkdocdata_DATA)'; test -n "$(gtkdocdatadir)" || list=; \ @@ -1048,7 +1014,7 @@ check: check-recursive all-am: Makefile $(SCRIPTS) $(DATA) installdirs: installdirs-recursive installdirs-am: - for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" "$(DESTDIR)$(gtkdocdatadir)" "$(DESTDIR)$(pkgconfigdir)" "$(DESTDIR)$(pylibdatadir)"; do \ + for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(gtkdocdatadir)" "$(DESTDIR)$(pkgconfigdir)" "$(DESTDIR)$(pylibdatadir)"; do \ test -z "$$dir" || $(MKDIR_P) "$$dir"; \ done install: install-recursive @@ -1106,8 +1072,8 @@ info: info-recursive info-am: -install-data-am: install-aclocalDATA install-gtkdocdataDATA \ - install-pkgconfigDATA install-pylibdataDATA +install-data-am: install-gtkdocdataDATA install-pkgconfigDATA \ + install-pylibdataDATA install-dvi: install-dvi-recursive @@ -1153,9 +1119,8 @@ ps: ps-recursive ps-am: -uninstall-am: uninstall-aclocalDATA uninstall-binSCRIPTS \ - uninstall-gtkdocdataDATA uninstall-pkgconfigDATA \ - uninstall-pylibdataDATA +uninstall-am: uninstall-binSCRIPTS uninstall-gtkdocdataDATA \ + uninstall-pkgconfigDATA uninstall-pylibdataDATA .MAKE: $(am__recursive_targets) install-am install-strip @@ -1166,26 +1131,22 @@ uninstall-am: uninstall-aclocalDATA uninstall-binSCRIPTS \ dist-tarZ dist-xz dist-zip distcheck distclean \ distclean-generic distclean-libtool distclean-tags \ distcleancheck distdir distuninstallcheck dvi dvi-am html \ - html-am info info-am install install-aclocalDATA install-am \ - install-binSCRIPTS install-data install-data-am install-dvi \ - install-dvi-am install-exec install-exec-am \ - install-gtkdocdataDATA install-html install-html-am \ - install-info install-info-am install-man install-pdf \ - install-pdf-am install-pkgconfigDATA install-ps install-ps-am \ - install-pylibdataDATA install-strip installcheck \ - installcheck-am installcheck-binSCRIPTS installdirs \ - installdirs-am maintainer-clean maintainer-clean-generic \ - mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \ - ps ps-am tags tags-am uninstall uninstall-aclocalDATA \ + html-am info info-am install install-am install-binSCRIPTS \ + install-data install-data-am install-dvi install-dvi-am \ + install-exec install-exec-am install-gtkdocdataDATA \ + install-html install-html-am install-info install-info-am \ + install-man install-pdf install-pdf-am install-pkgconfigDATA \ + install-ps install-ps-am install-pylibdataDATA install-strip \ + installcheck installcheck-am installcheck-binSCRIPTS \ + installdirs installdirs-am maintainer-clean \ + maintainer-clean-generic mostlyclean mostlyclean-generic \ + mostlyclean-libtool pdf pdf-am ps ps-am tags tags-am uninstall \ uninstall-am uninstall-binSCRIPTS uninstall-gtkdocdataDATA \ uninstall-pkgconfigDATA uninstall-pylibdataDATA .PRECIOUS: Makefile -gtk-doc.flat.make: gtk-doc.make - @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ - -include $(top_srcdir)/git.mk dist-hook: diff --git a/NEWS b/NEWS index d8fc4f9..95c9878 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,34 @@ +GTK-Doc 1.29 (Aug 28 2018) +=============== + +GTK-Doc now requires python-3.X. It does not requires python-six anymore. + +Note that this is a nonmaintainer release and that tests are known to be broken. + + Changes + + o 674163 : –   html-build.stamp rule broken for out-of-tree builds with absolute paths + o 795744 : Too much escaped string - " & lt;child > " in description of " GtkOverlay as GtkBuildable " section + o 796011 : Crash in ScanDirectory caused by overlooked use of renamed `dir` variable + o 796012 : Several places in rebase.py incorrectly use `match.groups(1)` instead of `match.group(1)`, one causes a crash + + Contributors + + Adam Williamson + Anders Jonsson + Daniel Mustieles + David D + LRN + Marek Cernocky + Martin Blanchard + Michael Biebl + Michael Catanzaro + Rafael Fontenelle + Sebastian Geiger + Stefan Sauer + Tim Sabsch + + GTK-Doc 1.28 (Mar 24 2018) ============== diff --git a/README b/README index 6c89237..1cf00a7 100644 --- a/README +++ b/README @@ -41,9 +41,66 @@ The DocBook XSL Stylesheets. libxslt & libxml2 >= 2.3.6. http://xmlsoft.org/ - Most distributions now have packages for all of these, so I would strongly advise that you grab those. See the documentation in the help/manual directory for more information. You can read it e.g. with yelp file://$PWD/help/manual/C/gtk-doc-manual.xml + + +Building +======== + +We are supporting two build systems to build gtk-doc for some transitions time. + + +Build using auto* +----------------- + +In order to build with a the classic auto* system use these commands: + +Build from git: +./autogen.sh; make + +Build from dist tarball: +./configure; make + +There are a few parameters one can pass to ./configure, run ./configure --help +to see them. Also ./autogen.sh can take those settings (and will hand them +through to ./configure). + +To run the tests: +make check + +To install: +make install + +To make a release: +make distcheck +or +make dist + + +Build using meson +----------------- + +Support for meson is new and still experiemntal. + +Build it from git: +meson build . +ninja -C build + +There are some options one can specify too: +meson build . --prefix= +meson build . -Dautotools_support=false +meson build . -Dcmake_support=false +meson build . -Dyelp_manual=false + +To run tests: +ninja -C build test + +To install: +ninja -C build install + +To make a release: +ninja -C build dist diff --git a/TODO b/TODO index 9fe99fd..b1a35fe 100644 --- a/TODO +++ b/TODO @@ -121,23 +121,15 @@ libs can benefit from the extensions too. * would be good to be able to have page titles as a concatenation of document name and page name (gtk+:GtkWIdget) * formats - http://bugzilla.gnome.org/show_bug.cgi?id=531572 : html-single http://bugzilla.gnome.org/show_bug.cgi?id=466535 : pdf http://bugzilla.gnome.org/show_bug.cgi?id=467488 : man we need more configure options in gtk-doc.m4: - --(enable|disable)-gtk-doc-(html|pdf|man|html-single|rtf) + --(enable|disable)-gtk-doc-(html|pdf|man) - html : enabled by default - - html-single : is single page html * validation xmllint --noout --xinclude --postvalid tester-docs.xml xmllint --noout --postvalid tester-docs.fo --dtdvalid file://$HOME/download/fo.dtd - fo.dtd : http://www.renderx.com/Tests/validator/fo.zip -* single page - xsltproc --nonet --xinclude -o gtk-docs.html /home/ensonic/projects/gtk-doc/gtk-doc-single.xsl gtk-docs.sgml - * need to check if we can pass the style-sheet class as a parameter (--stringparam gtkdoc.stylesheet=(chunk|docbook)) - * we might also need to reflow some things, as gtk-doc.xsl also runs the devhelp/devhelp2 generation - - but then the urls in the devhelp file, refer to the chunked html anyway - = Warnings = Bugzilla has some requests for extra warnings. We should support a common @@ -414,10 +406,6 @@ grep "gst_caps_is_always_compatible" tags 0m33.282s 0m29.266s 0m4.012s - removing the gentext calls for nav-bar alt tags does not help - - - try plain docbook xslt to see if maybe we have bad xslt templates in the - customisation layer (gtk-doc.xsl) - - we could do the xinlcude processing once and use it for both html and pdf time /usr/bin/xsltproc 2>../xslt4.log --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --xinclude --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ../tester-docs.xml real user sys @@ -454,12 +442,35 @@ grep "gst_caps_is_always_compatible" tags - unfortunately there is no way to ask xsltproc to pre-transform an xslt, that could - strip comments - process xsl:import and xsl:include - - compile xslt - http://sourceforge.net/projects/xsltc/ - http://www.xmlhack.com/read.php?item=618 - extra xsltproc options: --novalid: saves ~ 0.12 sec - + + - strip DOCTYPES on xincludes + - there is a performance bottleneck in libxml, where it parses DTD for each fragment + - we're using the dtd to + - validate fragments + - inject package name/version etc. + - 1) we could provide a flags to gtkdoc-mkdb to not put any doctype on + generated file and manually result entities in generated files (and + expand_content_files) + - to get a list of entities: + - we could parse entities from the main doc-file header + - tricky as with xml/gtkdocentities.ent, they are in a extra file + - we could pass entities as args for gtkdoc-mkdb + - if the flag is used, we should warn if entities are in the header + - 2) if the doctype on the main doc, does not conatin entities, skip adding + the doctype to generated output + - 3) if the doctype on the main doc contains entities, only add the doctype + if the generated content contains entities ([&%][_a-zA-Z]*;) + - a quick check on the gnome modules showed: + - quite a few don't use entities + - those that use version.xml + - seem to mostly use it in the main doc + - but a few use it for man pages + find . -name "*.xml" -exec grep -Hn "&version;" {} \; | grep -v "\-docs.xml" + +find . -name "*.xml" -exec egrep --color -Hn '&[_a-zA-Z]*;' {} \; | egrep -v '&(amp|lt|gt|quot|apos|nbsp);' | egrep --color '&[_a-zA-Z]*;' +find . -name "*.xml" -exec egrep -o '&[_a-zA-Z]*;' {} \; | sort | uniq -c | sort -n = python = - consider swithcing to this markdown parser diff --git a/aclocal.m4 b/aclocal.m4 index 8af088d..cf4659f 100644 --- a/aclocal.m4 +++ b/aclocal.m4 @@ -20,9 +20,9 @@ You have another version of autoconf. It may work, but is not guaranteed to. If you have problems, you may need to regenerate the build system entirely. To do so, use the procedure documented by the package, typically 'autoreconf'.])]) -dnl pkg.m4 - Macros to locate and utilise pkg-config. -*- Autoconf -*- -dnl serial 11 (pkg-config-0.29) -dnl +# pkg.m4 - Macros to locate and utilise pkg-config. -*- Autoconf -*- +# serial 11 (pkg-config-0.29.1) + dnl Copyright © 2004 Scott James Remnant . dnl Copyright © 2012-2015 Dan Nicholson dnl @@ -63,7 +63,7 @@ dnl dnl See the "Since" comment for each macro you use to see what version dnl of the macros you require. m4_defun([PKG_PREREQ], -[m4_define([PKG_MACROS_VERSION], [0.29]) +[m4_define([PKG_MACROS_VERSION], [0.29.1]) m4_if(m4_version_compare(PKG_MACROS_VERSION, [$1]), -1, [m4_fatal([pkg.m4 version $1 or higher is required but ]PKG_MACROS_VERSION[ found])]) ])dnl PKG_PREREQ @@ -296,6 +296,74 @@ AS_VAR_COPY([$1], [pkg_cv_][$1]) 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]) @@ -438,8 +506,8 @@ check-help: xmlpath="$$lc:$(srcdir)/$$lc"; \ fi; \ for page in $(HELP_FILES); do \ - echo "$(XMLLINT) --noout --noent --path $$xmlpath --xinclude $$d$$lc/$$page"; \ - $(XMLLINT) --noout --noent --path "$$xmlpath" --xinclude "$$d$$lc/$$page"; \ + echo "$(XMLLINT) --nonet --noout --noent --path $$xmlpath --xinclude $$d$$lc/$$page"; \ + $(XMLLINT) --nonet --noout --noent --path "$$xmlpath" --xinclude "$$d$$lc/$$page"; \ done; \ done @@ -1373,7 +1441,7 @@ AC_DEFUN([AM_PATH_PYTHON], dnl supported. (2.0 was released on October 16, 2000). dnl FIXME: Remove the need to hard-code Python versions here. m4_define_default([_AM_PYTHON_INTERPRETER_LIST], -[python python2 python3 python3.8 python3.7 python3.6 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 dnl +[python python2 python3 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 dnl python2.6 python2.5 python2.4 python2.3 python2.2 python2.1 python2.0]) AC_ARG_VAR([PYTHON], [the Python interpreter]) diff --git a/build-aux/compile b/build-aux/compile index a85b723..de0005d 100755 --- a/build-aux/compile +++ b/build-aux/compile @@ -1,9 +1,9 @@ -#! /bin/sh +#!/bin/sh # Wrapper for compilers which do not understand '-c -o'. -scriptversion=2012-10-14.11; # UTC +scriptversion=2016-01-11.22; # UTC -# Copyright (C) 1999-2014 Free Software Foundation, Inc. +# Copyright (C) 1999-2017 Free Software Foundation, Inc. # Written by Tom Tromey . # # This program is free software; you can redistribute it and/or modify @@ -255,7 +255,8 @@ EOF echo "compile $scriptversion" exit $? ;; - cl | *[/\\]cl | cl.exe | *[/\\]cl.exe ) + cl | *[/\\]cl | cl.exe | *[/\\]cl.exe | \ + icl | *[/\\]icl | icl.exe | *[/\\]icl.exe ) func_cl_wrapper "$@" # Doesn't return... ;; esac @@ -342,6 +343,6 @@ exit $ret # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "scriptversion=" # time-stamp-format: "%:y-%02m-%02d.%02H" -# time-stamp-time-zone: "UTC" +# time-stamp-time-zone: "UTC0" # time-stamp-end: "; # UTC" # End: diff --git a/build-aux/config.guess b/build-aux/config.guess index 2e9ad7f..717b228 100755 --- a/build-aux/config.guess +++ b/build-aux/config.guess @@ -1,8 +1,8 @@ -#! /bin/sh +#!/bin/sh # Attempt to guess a canonical system name. -# Copyright 1992-2016 Free Software Foundation, Inc. +# Copyright 1992-2017 Free Software Foundation, Inc. -timestamp='2016-10-02' +timestamp='2017-08-08' # This file is free software; you can redistribute it and/or modify it # under the terms of the GNU General Public License as published by @@ -50,7 +50,7 @@ version="\ GNU config.guess ($timestamp) Originally written by Per Bothner. -Copyright 1992-2016 Free Software Foundation, Inc. +Copyright 1992-2017 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE." @@ -259,6 +259,9 @@ case "${UNAME_MACHINE}:${UNAME_SYSTEM}:${UNAME_RELEASE}:${UNAME_VERSION}" in *:Sortix:*:*) echo ${UNAME_MACHINE}-unknown-sortix exit ;; + *:Redox:*:*) + echo ${UNAME_MACHINE}-unknown-redox + exit ;; alpha:OSF1:*:*) case $UNAME_RELEASE in *4.0) @@ -837,10 +840,11 @@ EOF UNAME_PROCESSOR=`/usr/bin/uname -p` case ${UNAME_PROCESSOR} in amd64) - echo x86_64-unknown-freebsd`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'` ;; - *) - echo ${UNAME_PROCESSOR}-unknown-freebsd`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'` ;; + UNAME_PROCESSOR=x86_64 ;; + i386) + UNAME_PROCESSOR=i586 ;; esac + echo ${UNAME_PROCESSOR}-unknown-freebsd`echo ${UNAME_RELEASE}|sed -e 's/[-(].*//'` exit ;; i*:CYGWIN*:*) echo ${UNAME_MACHINE}-pc-cygwin @@ -1303,14 +1307,21 @@ EOF if test `echo "$UNAME_RELEASE" | sed -e 's/\..*//'` -le 10 ; then if [ "$CC_FOR_BUILD" != no_compiler_found ]; then if (echo '#ifdef __LP64__'; echo IS_64BIT_ARCH; echo '#endif') | \ - (CCOPTS="" $CC_FOR_BUILD -E - 2>/dev/null) | \ - grep IS_64BIT_ARCH >/dev/null + (CCOPTS="" $CC_FOR_BUILD -E - 2>/dev/null) | \ + grep IS_64BIT_ARCH >/dev/null then case $UNAME_PROCESSOR in i386) UNAME_PROCESSOR=x86_64 ;; powerpc) UNAME_PROCESSOR=powerpc64 ;; esac fi + # On 10.4-10.6 one might compile for PowerPC via gcc -arch ppc + if (echo '#ifdef __POWERPC__'; echo IS_PPC; echo '#endif') | \ + (CCOPTS="" $CC_FOR_BUILD -E - 2>/dev/null) | \ + grep IS_PPC >/dev/null + then + UNAME_PROCESSOR=powerpc + fi fi elif test "$UNAME_PROCESSOR" = i386 ; then # Avoid executing cc on OS X 10.9, as it ships with a stub @@ -1334,15 +1345,18 @@ EOF *:QNX:*:4*) echo i386-pc-qnx exit ;; - NEO-?:NONSTOP_KERNEL:*:*) + NEO-*:NONSTOP_KERNEL:*:*) echo neo-tandem-nsk${UNAME_RELEASE} exit ;; NSE-*:NONSTOP_KERNEL:*:*) echo nse-tandem-nsk${UNAME_RELEASE} exit ;; - NSR-?:NONSTOP_KERNEL:*:*) + NSR-*:NONSTOP_KERNEL:*:*) echo nsr-tandem-nsk${UNAME_RELEASE} exit ;; + NSX-*:NONSTOP_KERNEL:*:*) + echo nsx-tandem-nsk${UNAME_RELEASE} + exit ;; *:NonStop-UX:*:*) echo mips-compaq-nonstopux exit ;; @@ -1418,8 +1432,8 @@ cat >&2 <." version="\ GNU config.sub ($timestamp) -Copyright 1992-2016 Free Software Foundation, Inc. +Copyright 1992-2017 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE." @@ -263,7 +263,7 @@ case $basic_machine in | fido | fr30 | frv | ft32 \ | h8300 | h8500 | hppa | hppa1.[01] | hppa2.0 | hppa2.0[nw] | hppa64 \ | hexagon \ - | i370 | i860 | i960 | ia64 \ + | i370 | i860 | i960 | ia16 | ia64 \ | ip2k | iq2000 \ | k1om \ | le32 | le64 \ @@ -315,6 +315,7 @@ case $basic_machine in | ubicom32 \ | v850 | v850e | v850e1 | v850e2 | v850es | v850e2v3 \ | visium \ + | wasm32 \ | we32k \ | x86 | xc16x | xstormy16 | xtensa \ | z8k | z80) @@ -388,7 +389,7 @@ case $basic_machine in | h8300-* | h8500-* \ | hppa-* | hppa1.[01]-* | hppa2.0-* | hppa2.0[nw]-* | hppa64-* \ | hexagon-* \ - | i*86-* | i860-* | i960-* | ia64-* \ + | i*86-* | i860-* | i960-* | ia16-* | ia64-* \ | ip2k-* | iq2000-* \ | k1om-* \ | le32-* | le64-* \ @@ -446,6 +447,7 @@ case $basic_machine in | v850-* | v850e-* | v850e1-* | v850es-* | v850e2-* | v850e2v3-* \ | vax-* \ | visium-* \ + | wasm32-* \ | we32k-* \ | x86-* | x86_64-* | xc16x-* | xps100-* \ | xstormy16-* | xtensa*-* \ @@ -948,6 +950,9 @@ case $basic_machine in nsr-tandem) basic_machine=nsr-tandem ;; + nsx-tandem) + basic_machine=nsx-tandem + ;; op50n-* | op60c-*) basic_machine=hppa1.1-oki os=-proelf @@ -1040,7 +1045,7 @@ case $basic_machine in ;; ppc64) basic_machine=powerpc64-unknown ;; - ppc64-*) basic_machine=powerpc64-`echo $basic_machine | sed 's/^[^-]*-//'` + ppc64-* | ppc64p7-*) basic_machine=powerpc64-`echo $basic_machine | sed 's/^[^-]*-//'` ;; ppc64le | powerpc64little) basic_machine=powerpc64le-unknown @@ -1243,6 +1248,9 @@ case $basic_machine in basic_machine=a29k-wrs os=-vxworks ;; + wasm32) + basic_machine=wasm32-unknown + ;; w65*) basic_machine=w65-wdc os=-none @@ -1397,7 +1405,7 @@ case $os in | -bosx* | -nextstep* | -cxux* | -aout* | -elf* | -oabi* \ | -ptx* | -coff* | -ecoff* | -winnt* | -domain* | -vsta* \ | -udi* | -eabi* | -lites* | -ieee* | -go32* | -aux* \ - | -chorusos* | -chorusrdb* | -cegcc* \ + | -chorusos* | -chorusrdb* | -cegcc* | -glidix* \ | -cygwin* | -msys* | -pe* | -psos* | -moss* | -proelf* | -rtems* \ | -midipix* | -mingw32* | -mingw64* | -linux-gnu* | -linux-android* \ | -linux-newlib* | -linux-musl* | -linux-uclibc* \ @@ -1409,7 +1417,7 @@ case $os in | -morphos* | -superux* | -rtmk* | -rtmk-nova* | -windiss* \ | -powermax* | -dnix* | -nx6 | -nx7 | -sei* | -dragonfly* \ | -skyos* | -haiku* | -rdos* | -toppers* | -drops* | -es* \ - | -onefs* | -tirtos* | -phoenix* | -fuchsia*) + | -onefs* | -tirtos* | -phoenix* | -fuchsia* | -redox*) # Remember, each alternative MUST END IN *, to match a version number. ;; -qnx*) @@ -1638,6 +1646,9 @@ case $basic_machine in sparc-* | *-sun) os=-sunos4.1.1 ;; + pru-*) + os=-elf + ;; *-be) os=-beos ;; diff --git a/build-aux/depcomp b/build-aux/depcomp index b39f98f..30379e2 100755 --- a/build-aux/depcomp +++ b/build-aux/depcomp @@ -1,4 +1,4 @@ -#! /bin/sh +#!/bin/sh # depcomp - compile a program generating dependencies as side-effects scriptversion=2016-01-11.22; # UTC diff --git a/build-aux/install-sh b/build-aux/install-sh index 59990a1..0360b79 100755 --- a/build-aux/install-sh +++ b/build-aux/install-sh @@ -1,7 +1,7 @@ #!/bin/sh # install - install a program, script, or datafile -scriptversion=2014-09-12.12; # UTC +scriptversion=2016-01-11.22; # UTC # This originates from X11R5 (mit/util/scripts/install.sh), which was # later released in X11R6 (xc/config/util/install.sh) with the @@ -324,41 +324,34 @@ do # is incompatible with FreeBSD 'install' when (umask & 300) != 0. ;; *) - # $RANDOM is not portable (e.g. dash); use it when possible to - # lower collision chance tmpdir=${TMPDIR-/tmp}/ins$RANDOM-$$ - trap 'ret=$?; rmdir "$tmpdir/a/b" "$tmpdir/a" "$tmpdir" 2>/dev/null; exit $ret' 0 + trap 'ret=$?; rmdir "$tmpdir/d" "$tmpdir" 2>/dev/null; exit $ret' 0 - # As "mkdir -p" follows symlinks and we work in /tmp possibly; so - # create the $tmpdir first (and fail if unsuccessful) to make sure - # that nobody tries to guess the $tmpdir name. if (umask $mkdir_umask && - $mkdirprog $mkdir_mode "$tmpdir" && - exec $mkdirprog $mkdir_mode -p -- "$tmpdir/a/b") >/dev/null 2>&1 + exec $mkdirprog $mkdir_mode -p -- "$tmpdir/d") >/dev/null 2>&1 then if test -z "$dir_arg" || { # Check for POSIX incompatibilities with -m. # HP-UX 11.23 and IRIX 6.5 mkdir -m -p sets group- or # other-writable bit of parent directory when it shouldn't. # FreeBSD 6.1 mkdir -m -p sets mode of existing directory. - test_tmpdir="$tmpdir/a" - ls_ld_tmpdir=`ls -ld "$test_tmpdir"` + ls_ld_tmpdir=`ls -ld "$tmpdir"` case $ls_ld_tmpdir in d????-?r-*) different_mode=700;; d????-?--*) different_mode=755;; *) false;; esac && - $mkdirprog -m$different_mode -p -- "$test_tmpdir" && { - ls_ld_tmpdir_1=`ls -ld "$test_tmpdir"` + $mkdirprog -m$different_mode -p -- "$tmpdir" && { + ls_ld_tmpdir_1=`ls -ld "$tmpdir"` test "$ls_ld_tmpdir" = "$ls_ld_tmpdir_1" } } then posix_mkdir=: fi - rmdir "$tmpdir/a/b" "$tmpdir/a" "$tmpdir" + rmdir "$tmpdir/d" "$tmpdir" else # Remove any dirs left behind by ancient mkdir implementations. - rmdir ./$mkdir_mode ./-p ./-- "$tmpdir" 2>/dev/null + rmdir ./$mkdir_mode ./-p ./-- 2>/dev/null fi trap '' 0;; esac;; @@ -503,6 +496,6 @@ done # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "scriptversion=" # time-stamp-format: "%:y-%02m-%02d.%02H" -# time-stamp-time-zone: "UTC" +# time-stamp-time-zone: "UTC0" # time-stamp-end: "; # UTC" # End: diff --git a/build-aux/ltmain.sh b/build-aux/ltmain.sh index a736cf9..30be9c8 100644 --- a/build-aux/ltmain.sh +++ b/build-aux/ltmain.sh @@ -31,7 +31,7 @@ PROGRAM=libtool PACKAGE=libtool -VERSION="2.4.6 Debian-2.4.6-2" +VERSION=2.4.6 package_revision=2.4.6 @@ -2068,12 +2068,12 @@ include the following information: compiler: $LTCC compiler flags: $LTCFLAGS linker: $LD (gnu? $with_gnu_ld) - version: $progname $scriptversion Debian-2.4.6-2 + version: $progname (GNU libtool) 2.4.6 automake: `($AUTOMAKE --version) 2>/dev/null |$SED 1q` autoconf: `($AUTOCONF --version) 2>/dev/null |$SED 1q` Report bugs to . -GNU libtool home page: . +GNU libtool home page: . General help using GNU software: ." exit 0 } @@ -7274,11 +7274,10 @@ func_mode_link () # -O*, -g*, -flto*, -fwhopr*, -fuse-linker-plugin GCC link-time optimization # -specs=* GCC specs files # -stdlib=* select c++ std lib with clang - # -fsanitize=* Clang/GCC memory and address sanitizer -64|-mips[0-9]|-r[0-9][0-9]*|-xarch=*|-xtarget=*|+DA*|+DD*|-q*|-m*| \ -t[45]*|-txscale*|-p|-pg|--coverage|-fprofile-*|-F*|@*|-tp=*|--sysroot=*| \ -O*|-g*|-flto*|-fwhopr*|-fuse-linker-plugin|-fstack-protector*|-stdlib=*| \ - -specs=*|-fsanitize=*) + -specs=*) func_quote_for_eval "$arg" arg=$func_quote_for_eval_result func_append compile_command " $arg" @@ -7571,10 +7570,7 @@ func_mode_link () case $pass in dlopen) libs=$dlfiles ;; dlpreopen) libs=$dlprefiles ;; - link) - libs="$deplibs %DEPLIBS%" - test "X$link_all_deplibs" != Xno && libs="$libs $dependency_libs" - ;; + link) libs="$deplibs %DEPLIBS% $dependency_libs" ;; esac fi if test lib,dlpreopen = "$linkmode,$pass"; then @@ -7893,19 +7889,19 @@ func_mode_link () # 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 @@ -8829,9 +8825,6 @@ func_mode_link () revision=$number_minor lt_irix_increment=no ;; - *) - func_fatal_configuration "$modename: unknown library version type '$version_type'" - ;; esac ;; no) diff --git a/build-aux/missing b/build-aux/missing index f62bbae..b7e571e 100755 --- a/build-aux/missing +++ b/build-aux/missing @@ -1,9 +1,9 @@ -#! /bin/sh +#!/bin/sh # Common wrapper for a few potentially missing GNU programs. -scriptversion=2013-10-28.13; # UTC +scriptversion=2016-01-11.22; # UTC -# Copyright (C) 1996-2014 Free Software Foundation, Inc. +# Copyright (C) 1996-2017 Free Software Foundation, Inc. # Originally written by Fran,cois Pinard , 1996. # This program is free software; you can redistribute it and/or modify @@ -210,6 +210,6 @@ exit $st # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "scriptversion=" # time-stamp-format: "%:y-%02m-%02d.%02H" -# time-stamp-time-zone: "UTC" +# time-stamp-time-zone: "UTC0" # time-stamp-end: "; # UTC" # End: diff --git a/build-aux/test-driver b/build-aux/test-driver index 8e575b0..de1e61d 100755 --- a/build-aux/test-driver +++ b/build-aux/test-driver @@ -1,9 +1,9 @@ -#! /bin/sh +#!/bin/sh # test-driver - basic testsuite driver script. -scriptversion=2013-07-13.22; # UTC +scriptversion=2016-01-11.22; # UTC -# Copyright (C) 2011-2014 Free Software Foundation, Inc. +# Copyright (C) 2011-2017 Free Software Foundation, Inc. # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -143,6 +143,6 @@ echo ":copy-in-global-log: $gcopy" >> $trs_file # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "scriptversion=" # time-stamp-format: "%:y-%02m-%02d.%02H" -# time-stamp-time-zone: "UTC" +# time-stamp-time-zone: "UTC0" # time-stamp-end: "; # UTC" # End: diff --git a/buildsystems/autotools/Makefile.am b/buildsystems/autotools/Makefile.am new file mode 100644 index 0000000..bb921b7 --- /dev/null +++ b/buildsystems/autotools/Makefile.am @@ -0,0 +1,20 @@ +EXTRA_DIST = \ + $(autotoolsdata_DATA) \ + gtk-doc.m4 + +CLEANFILES = gtk-doc.flat.make + +bin_SCRIPTS = gtkdocize + +autotoolsdatadir = $(datadir)/gtk-doc/data +autotoolsdata_DATA = \ + gtk-doc.make \ + gtk-doc.flat.make + +aclocaldir = $(datadir)/aclocal +aclocal_DATA = gtk-doc.m4 + +gtk-doc.flat.make: gtk-doc.make + @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ + +-include $(top_srcdir)/git.mk diff --git a/buildsystems/autotools/Makefile.in b/buildsystems/autotools/Makefile.in new file mode 100644 index 0000000..591d5a2 --- /dev/null +++ b/buildsystems/autotools/Makefile.in @@ -0,0 +1,620 @@ +# Makefile.in generated by automake 1.15.1 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2017 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + + +VPATH = @srcdir@ +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = buildsystems/autotools +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \ + $(top_srcdir)/m4/gtkdoc_jh_path_xml_catalog.m4 \ + $(top_srcdir)/m4/libtool.m4 $(top_srcdir)/m4/ltoptions.m4 \ + $(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \ + $(top_srcdir)/m4/lt~obsolete.m4 $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON) +mkinstalldirs = $(install_sh) -d +CONFIG_CLEAN_FILES = gtkdocize +CONFIG_CLEAN_VPATH_FILES = +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__uninstall_files_from_dir = { \ + test -z "$$files" \ + || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && rm -f $$files; }; \ + } +am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" \ + "$(DESTDIR)$(autotoolsdatadir)" +SCRIPTS = $(bin_SCRIPTS) +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +SOURCES = +DIST_SOURCES = +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +DATA = $(aclocal_DATA) $(autotoolsdata_DATA) +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +am__DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/gtkdocize.in +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DATE_FMT_CMD = @DATE_FMT_CMD@ +DBLATEX = @DBLATEX@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +ELAPSED_FMT = @ELAPSED_FMT@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +FOP = @FOP@ +GREP = @GREP@ +HELP_DIR = @HELP_DIR@ +HIGHLIGHT = @HIGHLIGHT@ +HIGHLIGHT_OPTIONS = @HIGHLIGHT_OPTIONS@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +ITSTOOL = @ITSTOOL@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MKDIR_P = @MKDIR_P@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_DATA_DIR = @PACKAGE_DATA_DIR@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PKG_CONFIG = @PKG_CONFIG@ +PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ +PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ +PYTHON = @PYTHON@ +PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ +PYTHON_PLATFORM = @PYTHON_PLATFORM@ +PYTHON_PREFIX = @PYTHON_PREFIX@ +PYTHON_VERSION = @PYTHON_VERSION@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +TEST_DEPS_CFLAGS = @TEST_DEPS_CFLAGS@ +TEST_DEPS_LIBS = @TEST_DEPS_LIBS@ +TS_FMT = @TS_FMT@ +VERSION = @VERSION@ +XMLCATALOG = @XMLCATALOG@ +XMLLINT = @XMLLINT@ +XML_CATALOG_FILE = @XML_CATALOG_FILE@ +XSLTPROC = @XSLTPROC@ +YELP_LC_DIST = @YELP_LC_DIST@ +YELP_LC_MEDIA_LINKS = @YELP_LC_MEDIA_LINKS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +glib_prefix = @glib_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +pkgpyexecdir = @pkgpyexecdir@ +pkgpythondir = @pkgpythondir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +pyexecdir = @pyexecdir@ +pythondir = @pythondir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +EXTRA_DIST = \ + $(autotoolsdata_DATA) \ + gtk-doc.m4 + +CLEANFILES = gtk-doc.flat.make +bin_SCRIPTS = gtkdocize +autotoolsdatadir = $(datadir)/gtk-doc/data +autotoolsdata_DATA = \ + gtk-doc.make \ + gtk-doc.flat.make + +aclocaldir = $(datadir)/aclocal +aclocal_DATA = gtk-doc.m4 +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu buildsystems/autotools/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu buildsystems/autotools/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): +gtkdocize: $(top_builddir)/config.status $(srcdir)/gtkdocize.in + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ +install-binSCRIPTS: $(bin_SCRIPTS) + @$(NORMAL_INSTALL) + @list='$(bin_SCRIPTS)'; test -n "$(bindir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(bindir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(bindir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + if test -f "$$d$$p"; then echo "$$d$$p"; echo "$$p"; else :; fi; \ + done | \ + sed -e 'p;s,.*/,,;n' \ + -e 'h;s|.*|.|' \ + -e 'p;x;s,.*/,,;$(transform)' | sed 'N;N;N;s,\n, ,g' | \ + $(AWK) 'BEGIN { files["."] = ""; dirs["."] = 1; } \ + { d=$$3; if (dirs[d] != 1) { print "d", d; dirs[d] = 1 } \ + if ($$2 == $$4) { files[d] = files[d] " " $$1; \ + if (++n[d] == $(am__install_max)) { \ + print "f", d, files[d]; n[d] = 0; files[d] = "" } } \ + else { print "f", d "/" $$4, $$1 } } \ + END { for (d in files) print "f", d, files[d] }' | \ + while read type dir files; do \ + if test "$$dir" = .; then dir=; else dir=/$$dir; fi; \ + test -z "$$files" || { \ + echo " $(INSTALL_SCRIPT) $$files '$(DESTDIR)$(bindir)$$dir'"; \ + $(INSTALL_SCRIPT) $$files "$(DESTDIR)$(bindir)$$dir" || exit $$?; \ + } \ + ; done + +uninstall-binSCRIPTS: + @$(NORMAL_UNINSTALL) + @list='$(bin_SCRIPTS)'; test -n "$(bindir)" || exit 0; \ + files=`for p in $$list; do echo "$$p"; done | \ + sed -e 's,.*/,,;$(transform)'`; \ + dir='$(DESTDIR)$(bindir)'; $(am__uninstall_files_from_dir) + +installcheck-binSCRIPTS: $(bin_SCRIPTS) + bad=0; pid=$$$$; list="$(bin_SCRIPTS)"; for p in $$list; do \ + case ' $(AM_INSTALLCHECK_STD_OPTIONS_EXEMPT) ' in \ + *" $$p "* | *" $(srcdir)/$$p "*) continue;; \ + esac; \ + f=`echo "$$p" | sed 's,^.*/,,;$(transform)'`; \ + for opt in --help --version; do \ + if "$(DESTDIR)$(bindir)/$$f" $$opt >c$${pid}_.out \ + 2>c$${pid}_.err &2; bad=1; fi; \ + done; \ + done; rm -f c$${pid}_.???; exit $$bad + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-aclocalDATA: $(aclocal_DATA) + @$(NORMAL_INSTALL) + @list='$(aclocal_DATA)'; test -n "$(aclocaldir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(aclocaldir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(aclocaldir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(aclocaldir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(aclocaldir)" || exit $$?; \ + done + +uninstall-aclocalDATA: + @$(NORMAL_UNINSTALL) + @list='$(aclocal_DATA)'; test -n "$(aclocaldir)" || list=; \ + files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ + dir='$(DESTDIR)$(aclocaldir)'; $(am__uninstall_files_from_dir) +install-autotoolsdataDATA: $(autotoolsdata_DATA) + @$(NORMAL_INSTALL) + @list='$(autotoolsdata_DATA)'; test -n "$(autotoolsdatadir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(autotoolsdatadir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(autotoolsdatadir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(autotoolsdatadir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(autotoolsdatadir)" || exit $$?; \ + done + +uninstall-autotoolsdataDATA: + @$(NORMAL_UNINSTALL) + @list='$(autotoolsdata_DATA)'; test -n "$(autotoolsdatadir)" || list=; \ + files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ + dir='$(DESTDIR)$(autotoolsdatadir)'; $(am__uninstall_files_from_dir) +tags TAGS: + +ctags CTAGS: + +cscope cscopelist: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(SCRIPTS) $(DATA) +installdirs: + for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" "$(DESTDIR)$(autotoolsdatadir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: install-aclocalDATA install-autotoolsdataDATA + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: install-binSCRIPTS + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: installcheck-binSCRIPTS + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-aclocalDATA uninstall-autotoolsdataDATA \ + uninstall-binSCRIPTS + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + cscopelist-am ctags-am distclean distclean-generic \ + distclean-libtool distdir dvi dvi-am html html-am info info-am \ + install install-aclocalDATA install-am \ + install-autotoolsdataDATA install-binSCRIPTS install-data \ + install-data-am install-dvi install-dvi-am install-exec \ + install-exec-am install-html install-html-am install-info \ + install-info-am install-man install-pdf install-pdf-am \ + install-ps install-ps-am install-strip installcheck \ + installcheck-am installcheck-binSCRIPTS installdirs \ + maintainer-clean maintainer-clean-generic mostlyclean \ + mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ + tags-am uninstall uninstall-aclocalDATA uninstall-am \ + uninstall-autotoolsdataDATA uninstall-binSCRIPTS + +.PRECIOUS: Makefile + + +gtk-doc.flat.make: gtk-doc.make + @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ + +-include $(top_srcdir)/git.mk + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/gtk-doc.flat.make b/buildsystems/autotools/gtk-doc.flat.make similarity index 99% rename from gtk-doc.flat.make rename to buildsystems/autotools/gtk-doc.flat.make index 1ba29e1..41dd278 100644 --- a/gtk-doc.flat.make +++ b/buildsystems/autotools/gtk-doc.flat.make @@ -212,6 +212,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_con for file in $(HTML_IMAGES) ; do \ test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$file $(abs_builddir)/html; \ + test -f $$file && cp $$file $(abs_builddir)/html; \ done; $(GTK_DOC_V_XREF)gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) $(AM_V_at)touch html-build.stamp diff --git a/gtk-doc.m4 b/buildsystems/autotools/gtk-doc.m4 similarity index 100% rename from gtk-doc.m4 rename to buildsystems/autotools/gtk-doc.m4 diff --git a/gtk-doc.make b/buildsystems/autotools/gtk-doc.make similarity index 99% rename from gtk-doc.make rename to buildsystems/autotools/gtk-doc.make index f87eaab..7d9a27f 100644 --- a/gtk-doc.make +++ b/buildsystems/autotools/gtk-doc.make @@ -212,6 +212,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_con for file in $(HTML_IMAGES) ; do \ test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$file $(abs_builddir)/html; \ + test -f $$file && cp $$file $(abs_builddir)/html; \ done; $(GTK_DOC_V_XREF)gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) $(AM_V_at)touch html-build.stamp diff --git a/gtkdocize.in b/buildsystems/autotools/gtkdocize.in old mode 100644 new mode 100755 similarity index 100% rename from gtkdocize.in rename to buildsystems/autotools/gtkdocize.in diff --git a/cmake/GtkDocConfig.cmake.in b/buildsystems/cmake/GtkDocConfig.cmake.in similarity index 100% rename from cmake/GtkDocConfig.cmake.in rename to buildsystems/cmake/GtkDocConfig.cmake.in diff --git a/cmake/GtkDocConfigVersion.cmake.in b/buildsystems/cmake/GtkDocConfigVersion.cmake.in similarity index 100% rename from cmake/GtkDocConfigVersion.cmake.in rename to buildsystems/cmake/GtkDocConfigVersion.cmake.in diff --git a/cmake/GtkDocScanGObjWrapper.cmake b/buildsystems/cmake/GtkDocScanGObjWrapper.cmake similarity index 100% rename from cmake/GtkDocScanGObjWrapper.cmake rename to buildsystems/cmake/GtkDocScanGObjWrapper.cmake diff --git a/cmake/Makefile.am b/buildsystems/cmake/Makefile.am similarity index 100% rename from cmake/Makefile.am rename to buildsystems/cmake/Makefile.am diff --git a/cmake/Makefile.in b/buildsystems/cmake/Makefile.in similarity index 99% rename from cmake/Makefile.in rename to buildsystems/cmake/Makefile.in index 692946c..7c8701c 100644 --- a/cmake/Makefile.in +++ b/buildsystems/cmake/Makefile.in @@ -88,7 +88,7 @@ PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ -subdir = cmake +subdir = buildsystems/cmake ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \ $(top_srcdir)/m4/gtkdoc_jh_path_xml_catalog.m4 \ @@ -293,7 +293,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ @@ -329,9 +328,9 @@ $(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__confi exit 1;; \ esac; \ done; \ - echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu cmake/Makefile'; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu buildsystems/cmake/Makefile'; \ $(am__cd) $(top_srcdir) && \ - $(AUTOMAKE) --gnu cmake/Makefile + $(AUTOMAKE) --gnu buildsystems/cmake/Makefile Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status @case '$?' in \ *config.status*) \ diff --git a/configure b/configure index f14cb8e..11d5727 100755 --- a/configure +++ b/configure @@ -1,6 +1,6 @@ #! /bin/sh # Guess values for system-dependent variables and create Makefiles. -# Generated by GNU Autoconf 2.69 for gtk-doc 1.28. +# Generated by GNU Autoconf 2.69 for gtk-doc 1.29. # # Report bugs to . # @@ -591,8 +591,8 @@ MAKEFLAGS= # Identity of this package. PACKAGE_NAME='gtk-doc' PACKAGE_TARNAME='gtk-doc' -PACKAGE_VERSION='1.28' -PACKAGE_STRING='gtk-doc 1.28' +PACKAGE_VERSION='1.29' +PACKAGE_STRING='gtk-doc 1.29' PACKAGE_BUGREPORT='http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc' PACKAGE_URL='' @@ -773,7 +773,6 @@ infodir docdir oldincludedir includedir -runstatedir localstatedir sharedstatedir sysconfdir @@ -868,7 +867,6 @@ datadir='${datarootdir}' sysconfdir='${prefix}/etc' sharedstatedir='${prefix}/com' localstatedir='${prefix}/var' -runstatedir='${localstatedir}/run' includedir='${prefix}/include' oldincludedir='/usr/include' docdir='${datarootdir}/doc/${PACKAGE_TARNAME}' @@ -1121,15 +1119,6 @@ do | -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=* \ @@ -1267,7 +1256,7 @@ fi for ac_var in exec_prefix prefix bindir sbindir libexecdir datarootdir \ datadir sysconfdir sharedstatedir localstatedir includedir \ oldincludedir docdir infodir htmldir dvidir pdfdir psdir \ - libdir localedir mandir runstatedir + libdir localedir mandir do eval ac_val=\$$ac_var # Remove trailing slashes. @@ -1380,7 +1369,7 @@ if test "$ac_init_help" = "long"; then # Omit some internal or obsolete options to make the list less imposing. # This message is too long to be a string in the A/UX 3.1 sh. cat <<_ACEOF -\`configure' configures gtk-doc 1.28 to adapt to many kinds of systems. +\`configure' configures gtk-doc 1.29 to adapt to many kinds of systems. Usage: $0 [OPTION]... [VAR=VALUE]... @@ -1420,7 +1409,6 @@ Fine tuning of the installation directories: --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] @@ -1451,7 +1439,7 @@ fi if test -n "$ac_init_help"; then case $ac_init_help in - short | recursive ) echo "Configuration of gtk-doc 1.28:";; + short | recursive ) echo "Configuration of gtk-doc 1.29:";; esac cat <<\_ACEOF @@ -1582,7 +1570,7 @@ fi test -n "$ac_init_help" && exit $ac_status if $ac_init_version; then cat <<\_ACEOF -gtk-doc configure 1.28 +gtk-doc configure 1.29 generated by GNU Autoconf 2.69 Copyright (C) 2012 Free Software Foundation, Inc. @@ -1860,7 +1848,7 @@ cat >config.log <<_ACEOF This file contains any messages produced by compilers while running configure, to aid debugging if configure makes a mistake. -It was created by gtk-doc $as_me 1.28, which was +It was created by gtk-doc $as_me 1.29, which was generated by GNU Autoconf 2.69. Invocation command line was $ $0 $@ @@ -2727,7 +2715,7 @@ fi # Define the identity of the package. PACKAGE='gtk-doc' - VERSION='1.28' + VERSION='1.29' cat >>confdefs.h <<_ACEOF @@ -5355,7 +5343,7 @@ linux* | k*bsd*-gnu | kopensolaris*-gnu | gnu*) lt_cv_deplibs_check_method=pass_all ;; -netbsd* | netbsdelf*-gnu) +netbsd*) if echo __ELF__ | $CC -E - | $GREP __ELF__ > /dev/null; then lt_cv_deplibs_check_method='match_pattern /lib[^/]+(\.so\.[0-9]+\.[0-9]+|_pic\.a)$' else @@ -9048,9 +9036,6 @@ $as_echo_n "checking whether the $compiler linker ($LD) supports shared librarie openbsd* | bitrig*) with_gnu_ld=no ;; - linux* | k*bsd*-gnu | gnu*) - link_all_deplibs=no - ;; esac ld_shlibs=yes @@ -9305,7 +9290,7 @@ _LT_EOF fi ;; - netbsd* | netbsdelf*-gnu) + netbsd*) if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then archive_cmds='$LD -Bshareable $libobjs $deplibs $linker_flags -o $lib' wlarc= @@ -9975,7 +9960,6 @@ $as_echo "$lt_cv_irix_exported_symbol" >&6; } 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' @@ -9997,7 +9981,7 @@ $as_echo "$lt_cv_irix_exported_symbol" >&6; } esac ;; - netbsd* | netbsdelf*-gnu) + netbsd*) if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then archive_cmds='$LD -Bshareable -o $lib $libobjs $deplibs $linker_flags' # a.out else @@ -11092,6 +11076,9 @@ fi # 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 @@ -11100,7 +11087,7 @@ fi # appending ld.so.conf contents (and includes) to the search path. if test -f /etc/ld.so.conf; then lt_ld_extra=`awk '/^include / { system(sprintf("cd /etc; cat %s 2>/dev/null", \$2)); skip = 1; } { if (!skip) print \$0; skip = 0; }' < /etc/ld.so.conf | $SED -e 's/#.*//;/^[ ]*hwcap[ ]/d;s/[:, ]/ /g;s/=[^=]*$//;s/=[^= ]* / /g;s/"//g;/^$/d' | tr '\n' ' '` - sys_lib_dlsearch_path_spec="/lib /usr/lib $lt_ld_extra" + sys_lib_dlsearch_path_spec="$sys_lib_dlsearch_path_spec $lt_ld_extra" fi # We used to test for /lib/ld.so.1 and disable shared libraries on @@ -11112,18 +11099,6 @@ fi 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 @@ -12261,13 +12236,13 @@ fi if test -n "$PYTHON"; then # If the user set $PYTHON, use it and don't search something else. - { $as_echo "$as_me:${as_lineno-$LINENO}: checking whether $PYTHON version is >= 2.7" >&5 -$as_echo_n "checking whether $PYTHON version is >= 2.7... " >&6; } + { $as_echo "$as_me:${as_lineno-$LINENO}: checking whether $PYTHON version is >= 3.2" >&5 +$as_echo_n "checking whether $PYTHON version is >= 3.2... " >&6; } prog="import sys # split strings by '.' and convert to numeric. Append some zeros # because we need at least 4 digits for the hex conversion. # map returns an iterator in Python 3.0 and a list in 2.x -minver = list(map(int, '2.7'.split('.'))) + [0, 0, 0] +minver = list(map(int, '3.2'.split('.'))) + [0, 0, 0] minverhex = 0 # xrange is not present in Python 3.0 and range returns an iterator for i in list(range(0, 4)): minverhex = (minverhex << 8) + minver[i] @@ -12288,19 +12263,19 @@ fi else # Otherwise, try each interpreter until we find one that satisfies # VERSION. - { $as_echo "$as_me:${as_lineno-$LINENO}: checking for a Python interpreter with version >= 2.7" >&5 -$as_echo_n "checking for a Python interpreter with version >= 2.7... " >&6; } + { $as_echo "$as_me:${as_lineno-$LINENO}: checking for a Python interpreter with version >= 3.2" >&5 +$as_echo_n "checking for a Python interpreter with version >= 3.2... " >&6; } if ${am_cv_pathless_PYTHON+:} false; then : $as_echo_n "(cached) " >&6 else - for am_cv_pathless_PYTHON in python python2 python3 python3.8 python3.7 python3.6 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 python2.6 python2.5 python2.4 python2.3 python2.2 python2.1 python2.0 none; do + for am_cv_pathless_PYTHON in python python2 python3 python3.5 python3.4 python3.3 python3.2 python3.1 python3.0 python2.7 python2.6 python2.5 python2.4 python2.3 python2.2 python2.1 python2.0 none; do test "$am_cv_pathless_PYTHON" = none && break prog="import sys # split strings by '.' and convert to numeric. Append some zeros # because we need at least 4 digits for the hex conversion. # map returns an iterator in Python 3.0 and a list in 2.x -minver = list(map(int, '2.7'.split('.'))) + [0, 0, 0] +minver = list(map(int, '3.2'.split('.'))) + [0, 0, 0] minverhex = 0 # xrange is not present in Python 3.0 and range returns an iterator for i in list(range(0, 4)): minverhex = (minverhex << 8) + minver[i] @@ -13401,8 +13376,8 @@ check-help: xmlpath="$$lc:$(srcdir)/$$lc"; \ fi; \ for page in $(HELP_FILES); do \ - echo "$(XMLLINT) --noout --noent --path $$xmlpath --xinclude $$d$$lc/$$page"; \ - $(XMLLINT) --noout --noent --path "$$xmlpath" --xinclude "$$d$$lc/$$page"; \ + echo "$(XMLLINT) --nonet --noout --noent --path $$xmlpath --xinclude $$d$$lc/$$page"; \ + $(XMLLINT) --nonet --noout --noent --path "$$xmlpath" --xinclude "$$d$$lc/$$page"; \ done; \ done @@ -13487,8 +13462,8 @@ else fi -# cmake/GtkDocConfig.cmake is handled in the Makefile, not here. -ac_config_files="$ac_config_files Makefile gtk-doc.pc cmake/Makefile cmake/GtkDocConfigVersion.cmake gtkdoc/config.py help/Makefile help/manual/Makefile tests/Makefile tests/annotations/Makefile tests/annotations/src/Makefile tests/annotations/docs/Makefile tests/bugs/Makefile tests/bugs/src/Makefile tests/bugs/docs/Makefile tests/empty/Makefile tests/empty/src/Makefile tests/empty/docs/Makefile tests/fail/Makefile tests/fail/src/Makefile tests/fail/docs/Makefile tests/gobject/Makefile tests/gobject/src/Makefile tests/gobject/docs/Makefile tests/program/Makefile tests/program/src/Makefile tests/program/docs/Makefile tests/repro/Makefile tests/repro/src/Makefile tests/repro/docs/Makefile" +# buildsystems/cmake/GtkDocConfig.cmake is handled in the Makefile, not here. +ac_config_files="$ac_config_files Makefile gtk-doc.pc buildsystems/autotools/Makefile buildsystems/cmake/Makefile buildsystems/cmake/GtkDocConfigVersion.cmake gtkdoc/config.py help/Makefile help/manual/Makefile tests/Makefile tests/annotations/Makefile tests/annotations/src/Makefile tests/annotations/docs/Makefile tests/bugs/Makefile tests/bugs/src/Makefile tests/bugs/docs/Makefile tests/empty/Makefile tests/empty/src/Makefile tests/empty/docs/Makefile tests/fail/Makefile tests/fail/src/Makefile tests/fail/docs/Makefile tests/gobject/Makefile tests/gobject/src/Makefile tests/gobject/docs/Makefile tests/program/Makefile tests/program/src/Makefile tests/program/docs/Makefile tests/repro/Makefile tests/repro/src/Makefile tests/repro/docs/Makefile" ac_config_files="$ac_config_files gtkdoc-check" @@ -13513,7 +13488,7 @@ ac_config_files="$ac_config_files gtkdoc-scan" ac_config_files="$ac_config_files gtkdoc-scangobj" -ac_config_files="$ac_config_files gtkdocize" +ac_config_files="$ac_config_files buildsystems/autotools/gtkdocize" ac_config_files="$ac_config_files tests/tools.sh" @@ -14099,7 +14074,7 @@ cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 # report actual input values of CONFIG_FILES etc. instead of their # values after options handling. ac_log=" -This file was extended by gtk-doc $as_me 1.28, which was +This file was extended by gtk-doc $as_me 1.29, which was generated by GNU Autoconf 2.69. Invocation command line was CONFIG_FILES = $CONFIG_FILES @@ -14156,7 +14131,7 @@ _ACEOF cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`" ac_cs_version="\\ -gtk-doc config.status 1.28 +gtk-doc config.status 1.29 configured by $0, generated by GNU Autoconf 2.69, with options \\"\$ac_cs_config\\" @@ -14561,8 +14536,9 @@ do "libtool") CONFIG_COMMANDS="$CONFIG_COMMANDS libtool" ;; "Makefile") CONFIG_FILES="$CONFIG_FILES Makefile" ;; "gtk-doc.pc") CONFIG_FILES="$CONFIG_FILES gtk-doc.pc" ;; - "cmake/Makefile") CONFIG_FILES="$CONFIG_FILES cmake/Makefile" ;; - "cmake/GtkDocConfigVersion.cmake") CONFIG_FILES="$CONFIG_FILES cmake/GtkDocConfigVersion.cmake" ;; + "buildsystems/autotools/Makefile") CONFIG_FILES="$CONFIG_FILES buildsystems/autotools/Makefile" ;; + "buildsystems/cmake/Makefile") CONFIG_FILES="$CONFIG_FILES buildsystems/cmake/Makefile" ;; + "buildsystems/cmake/GtkDocConfigVersion.cmake") CONFIG_FILES="$CONFIG_FILES buildsystems/cmake/GtkDocConfigVersion.cmake" ;; "gtkdoc/config.py") CONFIG_FILES="$CONFIG_FILES gtkdoc/config.py" ;; "help/Makefile") CONFIG_FILES="$CONFIG_FILES help/Makefile" ;; "help/manual/Makefile") CONFIG_FILES="$CONFIG_FILES help/manual/Makefile" ;; @@ -14599,7 +14575,7 @@ do "gtkdoc-rebase") CONFIG_FILES="$CONFIG_FILES gtkdoc-rebase" ;; "gtkdoc-scan") CONFIG_FILES="$CONFIG_FILES gtkdoc-scan" ;; "gtkdoc-scangobj") CONFIG_FILES="$CONFIG_FILES gtkdoc-scangobj" ;; - "gtkdocize") CONFIG_FILES="$CONFIG_FILES gtkdocize" ;; + "buildsystems/autotools/gtkdocize") CONFIG_FILES="$CONFIG_FILES buildsystems/autotools/gtkdocize" ;; "tests/tools.sh") CONFIG_FILES="$CONFIG_FILES tests/tools.sh" ;; *) as_fn_error $? "invalid argument: \`$ac_config_target'" "$LINENO" 5;; @@ -15138,6 +15114,7 @@ $as_echo X"$file" | 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. @@ -15676,7 +15653,7 @@ ltmain=$ac_aux_dir/ltmain.sh "gtkdoc-rebase":F) chmod +x gtkdoc-rebase ;; "gtkdoc-scan":F) chmod +x gtkdoc-scan ;; "gtkdoc-scangobj":F) chmod +x gtkdoc-scangobj ;; - "gtkdocize":F) chmod +x gtkdocize ;; + "buildsystems/autotools/gtkdocize":F) chmod +x buildsystems/autotools/gtkdocize ;; "tests/tools.sh":F) chmod +x tests/tools.sh ;; esac diff --git a/configure.ac b/configure.ac index 05500b9..93d1b63 100644 --- a/configure.ac +++ b/configure.ac @@ -3,7 +3,7 @@ AC_PREREQ([2.63]) dnl We're using a two digit number for the releases and dnl a three digit number for the development version -m4_define(gtk_doc_version, 1.28) +m4_define(gtk_doc_version, 1.29) AC_INIT([gtk-doc],[gtk_doc_version],[http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc],[gtk-doc]) @@ -32,7 +32,7 @@ PKG_PROG_PKG_CONFIG([0.19]) dnl dnl Check for Python. dnl -AM_PATH_PYTHON([2.7]) +AM_PATH_PYTHON([3.2]) dnl dnl Check for xsltproc @@ -210,11 +210,12 @@ if test "x$have_yelp_tools" != "xyes"; then fi AM_CONDITIONAL([HAVE_YELP_TOOLS],[test x$have_yelp_tools = xyes]) -# cmake/GtkDocConfig.cmake is handled in the Makefile, not here. +# buildsystems/cmake/GtkDocConfig.cmake is handled in the Makefile, not here. AC_CONFIG_FILES([Makefile gtk-doc.pc -cmake/Makefile -cmake/GtkDocConfigVersion.cmake +buildsystems/autotools/Makefile +buildsystems/cmake/Makefile +buildsystems/cmake/GtkDocConfigVersion.cmake gtkdoc/config.py help/Makefile help/manual/Makefile @@ -254,7 +255,7 @@ AC_CONFIG_FILES([gtkdoc-mkpdf], [chmod +x gtkdoc-mkpdf]) AC_CONFIG_FILES([gtkdoc-rebase], [chmod +x gtkdoc-rebase]) AC_CONFIG_FILES([gtkdoc-scan], [chmod +x gtkdoc-scan]) AC_CONFIG_FILES([gtkdoc-scangobj], [chmod +x gtkdoc-scangobj]) -AC_CONFIG_FILES([gtkdocize], [chmod +x gtkdocize]) +AC_CONFIG_FILES([buildsystems/autotools/gtkdocize], [chmod +x buildsystems/autotools/gtkdocize]) AC_CONFIG_FILES([tests/tools.sh], [chmod +x tests/tools.sh]) AC_OUTPUT diff --git a/gtkdoc-depscan.in b/gtkdoc-depscan.in old mode 100644 new mode 100755 diff --git a/gtkdoc-mkhtml.in b/gtkdoc-mkhtml.in old mode 100644 new mode 100755 diff --git a/gtkdoc-mkhtml2.in b/gtkdoc-mkhtml2.in old mode 100644 new mode 100755 index 06355cc..0a0f315 --- a/gtkdoc-mkhtml2.in +++ b/gtkdoc-mkhtml2.in @@ -29,6 +29,11 @@ if __name__ == '__main__': parser = argparse.ArgumentParser( description='gtkdoc-mkhtml version %s - generate documentation in html format' % config.version) parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--path', default=[], action='append', + help='Extra source directories') + parser.add_argument('--src-lang', default='c', + help='Programing language used for syntax highlighting. This' + 'can be any language pygments supports.') parser.add_argument('args', nargs='*', help='MODULE DRIVER_FILE') # TODO: only for testing, replace with env-var diff --git a/gtkdoc-mkman.in b/gtkdoc-mkman.in old mode 100644 new mode 100755 diff --git a/gtkdoc-scangobj.in b/gtkdoc-scangobj.in old mode 100644 new mode 100755 diff --git a/gtkdoc/check.py b/gtkdoc/check.py index 7f32b60..b410910 100755 --- a/gtkdoc/check.py +++ b/gtkdoc/check.py @@ -25,9 +25,6 @@ results. Can be run druring make check, by adding this to the documentations Makefile.am: TESTS = $(GTKDOC_CHECK). """ -# Support both Python 2 and 3 -from __future__ import print_function - import os import re from glob import glob @@ -53,17 +50,21 @@ def check_empty(filename): return count +def read_file(filename): + with open(filename, 'r', encoding='utf-8') as f: + return f.read().splitlines() + + def check_includes(filename): # Check that each XML file in the xml directory is included in doc_main_file - with common.open_text(filename) as f: - lines = f.read().splitlines() - num_missing = 0 - for include in glob('xml/*.xml'): - try: - next(line for line in lines if include in line) - except StopIteration: - num_missing += 1 - print('%s:1:E: doesn\'t appear to include "%s"' % (filename, include)) + lines = read_file(filename) + num_missing = 0 + for include in glob('xml/*.xml'): + try: + next(line for line in lines if include in line) + except StopIteration: + num_missing += 1 + print('%s:1:E: doesn\'t appear to include "%s"' % (filename, include)) return num_missing @@ -74,11 +75,6 @@ def get_variable(env, lines, variable): return value -def read_file(filename): - with common.open_text(filename) as f: - return f.read().splitlines() - - def run_tests(workdir, doc_module, doc_main_file): checks = 4 diff --git a/gtkdoc/common.py b/gtkdoc/common.py index f62e6de..bd11950 100644 --- a/gtkdoc/common.py +++ b/gtkdoc/common.py @@ -19,44 +19,16 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -# Support both Python 2 and 3 -from __future__ import print_function - from collections import OrderedDict import logging import os import re import subprocess import sys -import six -import codecs from . import config -def open_text(filename, mode='r', encoding='utf-8'): - """An open() which removes some differences between Python 2 and 3 and - has saner defaults. - - Unlike the builtin open by default utf-8 is use and not the locale - encoding (which is ANSI on Windows for example, not very helpful) - - For Python 2, files are opened in text mode like with Python 3. - """ - - if mode not in ('r', 'w'): - raise ValueError("mode %r not supported, must be 'r' or 'w'" % mode) - - if six.PY3: - return open(filename, mode, encoding=encoding) - else: - # We can't use io.open() here as its write method is too strict and - # only allows unicode instances and not everything in the codebase - # forces unicode at the moment. codecs.open() on the other hand - # happily takes ASCII str and decodes it. - return codecs.open(filename, mode, encoding=encoding) - - def setup_logging(): """Check GTKDOC_TRACE environment variable. @@ -69,16 +41,12 @@ def setup_logging(): logging.basicConfig(stream=sys.stdout, level=logging.getLevelName(log_level.upper()), format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s') - # When redirecting the output on python2 or if run with a non utf-8 locale + # When redirecting the output and running with a non utf-8 locale # we get UnicodeEncodeError: encoding = sys.stdout.encoding if 'PYTHONIOENCODING' not in os.environ and (not encoding or encoding != 'UTF-8'): sys.stdout.flush() - if six.PY3: - sys.stdout = open(sys.stdout.fileno(), mode='w', encoding='utf8', buffering=1) - else: - import codecs - sys.stdout = codecs.getwriter('utf8')(sys.stdout) + sys.stdout = open(sys.stdout.fileno(), mode='w', encoding='utf8', buffering=1) def UpdateFileIfChanged(old_file, new_file, make_backup): diff --git a/gtkdoc/config.py b/gtkdoc/config.py index f3a95f5..81f9b67 100644 --- a/gtkdoc/config.py +++ b/gtkdoc/config.py @@ -1,7 +1,7 @@ -version = "1.28" +version = "1.29" # tools -dblatex = '/usr/bin/dblatex' +dblatex = '' fop = '' highlight = '/usr/bin/source-highlight' highlight_options = '-t4 -s$SRC_LANG -cstyle.css --no-doc -i' @@ -9,7 +9,7 @@ pkg_config = '/usr/bin/pkg-config' xsltproc = '/usr/bin/xsltproc' # configured directories -prefix = '/usr' +prefix = '/usr/local' datarootdir = "${prefix}/share".replace('${prefix}', prefix) datadir = "${datarootdir}".replace('${datarootdir}', datarootdir) diff --git a/gtkdoc/fixxref.py b/gtkdoc/fixxref.py index a5f3af2..daba928 100755 --- a/gtkdoc/fixxref.py +++ b/gtkdoc/fixxref.py @@ -21,9 +21,6 @@ ''"Fix cross-references in the HTML documentation.''" -# Support both Python 2 and 3 -from __future__ import print_function - import logging import os import re @@ -49,10 +46,6 @@ NoLinks = { 'unsigned', 'va-list', 'void', - 'GBoxed', - 'GEnum', - 'GFlags', - 'GInterface' } @@ -93,6 +86,11 @@ def LoadIndicies(module_dir, html_dir, extra_dirs): if dir != html_dir: logging.info('Scanning GLib directory: %s', dir) ScanIndices(dir, (re.search(prefix_match, dir) is None), dir_cache) + else: + NoLinks.add('GBoxed') + NoLinks.add('GEnum') + NoLinks.add('GFlags') + NoLinks.add('GInterface') path = os.environ.get('GNOME2_PATH') if path: @@ -182,7 +180,7 @@ def ReadDevhelp(file, use_absolute_links): logging.info('Scanning index file=%s, absolute=%d, dir=%s', file, use_absolute_links, dir) - for line in common.open_text(file): + for line in open(file, 'r', encoding='utf-8'): m = re.search(r' link="([^#]*)#([^"]*)"', line) if m: link = m.group(1) + '#' + m.group(2) @@ -192,7 +190,7 @@ def ReadDevhelp(file, use_absolute_links): def ReadSections(module): """We don't warn on missing links to non-public sysmbols.""" - for line in common.open_text(module + '-sections.txt'): + for line in open(module + '-sections.txt', 'r', encoding='utf-8'): m1 = re.search(r'^', line) if line.startswith('#') or line.strip() == '': continue @@ -227,7 +225,7 @@ def FixCrossReferences(module_dir, module, src_lang): def FixHTMLFile(src_lang, module, file): logging.info('Fixing file: %s', file) - content = common.open_text(file).read() + content = open(file, 'r', encoding='utf-8').read() if config.highlight: # FIXME: ideally we'd pass a clue about the example language to the highligher @@ -271,62 +269,88 @@ def FixHTMLFile(src_lang, module, file): new_file = file + '.new' content = '\n'.join(lines) - with common.open_text(new_file, 'w') as h: + with open(new_file, 'w', encoding='utf-8') as h: h.write(content) os.unlink(file) os.rename(new_file, file) -def MakeXRef(module, file, line, id, text): +def GetXRef(id): href = Links.get(id) + if href: + return (id, href) # This is a workaround for some inconsistency we have with CreateValidSGMLID - if not href and ':' in id: - href = Links.get(id.replace(':', '--')) + if ':' in id: + tid = id.replace(':', '--') + href = Links.get(tid) + if href: + return (tid, href) + # poor mans plural support - if not href and id.endswith('s'): + if id.endswith('s'): tid = id[:-1] href = Links.get(tid) - if not href: - href = Links.get(tid + '-struct') - if not href: - href = Links.get(id + '-struct') + if href: + return (tid, href) + tid += '-struct' + href = Links.get(tid) + if href: + return (tid, href) + tid = id + '-struct' + href = Links.get(tid) if href: - # if it is a link to same module, remove path to make it work uninstalled - m = re.search(r'^\.\./' + module + '/(.*)$', href) - if m: - href = m.group(1) - logging.info('Fixing link to uninstalled doc: %s, %s, %s', id, href, text) - else: - logging.info('Fixing link: %s, %s, %s', id, href, text) + return (tid, href) + + return (id, None) + + +def ReportBadXRef(file, line, id, text): + logging.info('no link for: id=%s, linktext=%s', id, text) + + # don't warn multiple times and also skip blacklisted (ctypes) + if id in NoLinks: + return + # if it's a function, don't warn if it does not contain a "_" + # (transformed to "-") + # - gnome coding style would use '_' + # - will avoid wrong warnings for ansi c functions + if re.search(r' class=\"function\"', text) and '-' not in id: + return + # if it's a 'return value', don't warn (implicitly created link) + if re.search(r' class=\"returnvalue\"', text): + return + # if it's a 'type', don't warn if it starts with lowercase + # - gnome coding style would use CamelCase + if re.search(r' class=\"type\"', text) and id[0].islower(): + return + # don't warn for self links + if text == id: + return + + common.LogWarning(file, line, 'no link for: "%s" -> (%s).' % (id, text)) + NoLinks.add(id) + + +def MakeRelativeXRef(module, href): + # if it is a link to same module, remove path to make it work uninstalled + m = re.search(r'^\.\./' + module + '/(.*)$', href) + if m: + href = m.group(1) + return href + + +def MakeXRef(module, file, line, id, text): + href = GetXRef(id)[1] + + if href: + href = MakeRelativeXRef(module, href) + logging.info('Fixing link: %s, %s, %s', id, href, text) return "%s" % (href, text) else: - logging.info('no link for: %s, %s', id, text) - - # don't warn multiple times and also skip blacklisted (ctypes) - if id in NoLinks: - return text - # if it's a function, don't warn if it does not contain a "_" - # (transformed to "-") - # - gnome coding style would use '_' - # - will avoid wrong warnings for ansi c functions - if re.search(r' class=\"function\"', text) and '-' not in id: - return text - # if it's a 'return value', don't warn (implicitly created link) - if re.search(r' class=\"returnvalue\"', text): - return text - # if it's a 'type', don't warn if it starts with lowercase - # - gnome coding style would use CamelCase - if re.search(r' class=\"type\"', text) and id[0].islower(): - return text - # don't warn for self links - if text == id: - return text - - common.LogWarning(file, line, 'no link for: "%s" -> (%s).' % (id, text)) - NoLinks.add(id) + ReportBadXRef(file, line, id, text) return text @@ -385,7 +409,7 @@ def HighlightSourceVim(src_lang, type, source): script += "%s -n -e -u NONE -T xterm >/dev/null" % config.highlight subprocess.check_call([script], shell=True) - highlighted_source = common.open_text(temp_source_file + ".html").read() + highlighted_source = open(temp_source_file + ".html", 'r', encoding='utf-8').read() highlighted_source = re.sub(r'.*]*>\n', '', highlighted_source, flags=re.DOTALL) highlighted_source = re.sub(r'.*', '', highlighted_source, flags=re.DOTALL) diff --git a/gtkdoc/mkdb.py b/gtkdoc/mkdb.py index f5e8995..37a6931 100644 --- a/gtkdoc/mkdb.py +++ b/gtkdoc/mkdb.py @@ -23,9 +23,6 @@ Creates the DocBook files from the source comments. """ -from __future__ import print_function -from six import iteritems, iterkeys - from collections import OrderedDict import logging import os @@ -318,7 +315,7 @@ def OutputObjectList(): old_object_index = os.path.join(DB_OUTPUT_DIR, "object_index.sgml") new_object_index = os.path.join(DB_OUTPUT_DIR, "object_index.new") - OUTPUT = common.open_text(new_object_index, 'w') + OUTPUT = open(new_object_index, 'w', encoding='utf-8') OUTPUT.write('''%s @@ -380,7 +377,7 @@ def OutputDB(file, options): """ logging.info("Reading: %s", file) - INPUT = common.open_text(file) + INPUT = open(file, 'r', encoding='utf-8') filename = '' book_top = '' book_bottom = '' @@ -817,7 +814,7 @@ def DetermineNamespace(): while True: prefix = {} letter = '' - for symbol in iterkeys(IndexEntriesFull): + for symbol in IndexEntriesFull.keys(): if name_space == '' or name_space.lower() in symbol.lower(): if len(symbol) > pos: letter = symbol[pos:pos + 1] @@ -839,7 +836,7 @@ def DetermineNamespace(): if letter != '' and letter != "_": maxletter = '' maxsymbols = 0 - for letter in iterkeys(prefix): + for letter in prefix.keys(): logging.debug("ns prefix: %s: %s", letter, prefix[letter]) if prefix[letter] > maxsymbols: maxletter = letter @@ -886,7 +883,7 @@ def OutputIndex(basename, apiindex): { 'original': x, 'short': re.sub(r'^' + NAME_SPACE + r'\_?(.*)', r'\1', x.upper(), flags=re.I), - } for x in iterkeys(apiindex)] + } for x in apiindex.keys()] sorted_keys = sorted(mapped_keys, key=lambda d: (d['short'], d['original'])) for key in sorted_keys: @@ -975,7 +972,7 @@ def OutputSinceIndexes(): """Generate the 'since' api index files.""" for version in set(Since.values()): logging.info("Since : [%s]", version) - index = {x: IndexEntriesSince[x] for x in iterkeys(IndexEntriesSince) if Since[x] == version} + index = {x: IndexEntriesSince[x] for x in IndexEntriesSince.keys() if Since[x] == version} OutputIndex("api-index-" + version, index) @@ -1006,14 +1003,14 @@ def OutputAnnotationGlossary(): rerun = True break - OUTPUT = common.open_text(new_glossary, 'w') + OUTPUT = open(new_glossary, 'w', encoding='utf-8') OUTPUT.write('''%s Annotation Glossary ''' % MakeDocHeader("glossary")) - for annotation in sorted(iterkeys(AnnotationsUsed), key=str.lower): + for annotation in sorted(AnnotationsUsed.keys(), key=str.lower): if annotation in AnnotationDefinition: definition = AnnotationDefinition[annotation] curletter = annotation[0].upper() @@ -1054,7 +1051,7 @@ def ReadKnownSymbols(file): subsection = '' logging.info("Reading: %s", file) - INPUT = common.open_text(file) + INPUT = open(file, 'r', encoding='utf-8') for line in INPUT: if line.startswith('#'): continue @@ -1444,7 +1441,7 @@ def OutputStruct(symbol, declaration): ''' % sid - for field_name, text in iteritems(fields): + for field_name, text in fields.items(): param_annotations = '' desc += "%s\n" % text @@ -1586,7 +1583,7 @@ def OutputUnion(symbol, declaration): ''' % sid - for field_name, text in iteritems(fields): + for field_name, text in fields.items(): param_annotations = '' desc += "%s\n" % text @@ -1908,7 +1905,7 @@ def OutputFunction(symbol, declaration, symbol_type): if param_annotations != '': desc += "\n%s" % param_annotations - desc += OutputParamDescriptions("FUNCTION", symbol, iterkeys(fields)) + desc += OutputParamDescriptions("FUNCTION", symbol, fields.keys()) desc += OutputSymbolTraits(symbol) desc += "\n" return (synop, desc) @@ -1948,7 +1945,7 @@ def OutputParamDescriptions(symbol_type, symbol, fields): missing_parameters = '' unused_parameters = '' - for param_name, param_desc in iteritems(params): + for param_name, param_desc in params.items(): (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc) param_desc = ConvertMarkDown(symbol, param_desc) # trim @@ -2169,7 +2166,7 @@ def OutputDBFile(file, title, section_id, includes, functions_synop, other_synop old_db_file = os.path.join(DB_OUTPUT_DIR, file + '.xml') new_db_file = os.path.join(DB_OUTPUT_DIR, file + '.xml.new') - OUTPUT = common.open_text(new_db_file, 'w') + OUTPUT = open(new_db_file, 'w', encoding='utf-8') object_anchors = '' for fobject in file_objects: @@ -2336,7 +2333,7 @@ def OutputProgramDBFile(program, section_id): old_db_file = os.path.join(DB_OUTPUT_DIR, program + ".xml") new_db_file = os.path.join(DB_OUTPUT_DIR, program + ".xml.new") - OUTPUT = common.open_text(new_db_file, 'w') + OUTPUT = open(new_db_file, 'w', encoding='utf-8') OUTPUT.write('''%s @@ -2379,18 +2376,17 @@ def OutputExtraFile(file): old_db_file = os.path.join(DB_OUTPUT_DIR, basename) new_db_file = os.path.join(DB_OUTPUT_DIR, basename + ".new") - contents = common.open_text(file).read() + contents = open(file, 'r', encoding='utf-8').read() - OUTPUT = common.open_text(new_db_file, 'w') - OUTPUT.write(ExpandAbbreviations(basename + " file", contents)) - OUTPUT.close() + with open(new_db_file, 'w', encoding='utf-8') as out: + out.write(ExpandAbbreviations(basename + " file", contents)) return common.UpdateFileIfChanged(old_db_file, new_db_file, 0) def GetDocbookHeader(main_file): if os.path.exists(main_file): - INPUT = common.open_text(main_file) + INPUT = open(main_file, 'r', encoding='utf-8') header = '' for line in INPUT: if re.search(r'^\s*<(book|chapter|article)', line): @@ -2433,30 +2429,28 @@ def OutputBook(main_file, book_top, book_bottom): old_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.top") new_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.top.new") - OUTPUT = common.open_text(new_file, 'w') - OUTPUT.write(book_top) - OUTPUT.close() + with open(new_file, 'w', encoding='utf-8') as out: + out.write(book_top) common.UpdateFileIfChanged(old_file, new_file, 0) old_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.bottom") new_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.bottom.new") - OUTPUT = common.open_text(new_file, 'w') - OUTPUT.write(book_bottom) - OUTPUT.close() + with open(new_file, 'w', encoding='utf-8') as out: + out.write(book_bottom) common.UpdateFileIfChanged(old_file, new_file, 0) # If the main docbook file hasn't been created yet, we create it here. # The user can tweak it later. if main_file and not os.path.exists(main_file): - OUTPUT = common.open_text(main_file, 'w') + OUTPUT = open(main_file, 'w', encoding='utf-8') logging.info("no master doc, create default one at: " + main_file) OUTPUT.write('''%s - + &package_name; Reference Manual @@ -2468,8 +2462,7 @@ def OutputBook(main_file, book_top, book_bottom): [Insert title here] - %s - +%s ''' % (MakeDocHeader("book"), book_bottom)) if os.path.exists('xml/tree_index.sgml'): OUTPUT.write(''' @@ -2562,7 +2555,9 @@ def ConvertSGMLChars(symbol, text): # For the simple non-sgml mode, convert to entities everywhere. text = re.sub(r'&(?![a-zA-Z#]+;)', r'&', text) # Do this first, or the others get messed up. - text = re.sub(r'<', r'<', text) + # Allow '<' in verbatim markdown + # TODO: we don't want to convert any of them between `` + text = re.sub(r'(?' at beginning of string for blockquote markdown text = re.sub(r'''(?<=[^\w\n"'\/-])>''', r'>', text) @@ -3678,7 +3673,7 @@ def ScanSourceFile(ifile, ignore_files): logging.info("Scanning source file: %s", ifile) - SRCFILE = common.open_text(ifile) + SRCFILE = open(ifile, 'r', encoding='utf-8') in_comment_block = False symbol = None in_part = '' @@ -3727,7 +3722,7 @@ def ScanSourceFile(ifile, ignore_files): # Convert special characters description = ConvertSGMLChars(symbol, description) - for (param_name, param_desc) in iteritems(params): + for (param_name, param_desc) in params.items(): params[param_name] = ConvertSGMLChars(symbol, param_desc) # Handle Section docs @@ -3742,7 +3737,7 @@ def ScanSourceFile(ifile, ignore_files): ifile, line_number, "Section %s is not defined in the %s-sections.txt file." % (real_symbol, MODULE)) logging.info("SECTION DOCS found in source for : '%s'", real_symbol) - for param_name, param_desc in iteritems(params): + for param_name, param_desc in params.items(): logging.info(" '" + param_name + "'") param_name = param_name.lower() key = None @@ -3775,7 +3770,7 @@ def ScanSourceFile(ifile, ignore_files): section_id = None logging.info("PROGRAM DOCS found in source for '%s'", real_symbol) - for param_name, param_desc in iteritems(params): + for param_name, param_desc in params.items(): logging.info("PROGRAM key %s: '%s'", real_symbol, param_name) param_name = param_name.lower() key = None @@ -3996,9 +3991,9 @@ def OutputMissingDocumentation(): buffer_deprecated = '' buffer_descriptions = '' - UNDOCUMENTED = common.open_text(new_undocumented_file, 'w') + UNDOCUMENTED = open(new_undocumented_file, 'w', encoding='utf-8') - for symbol in sorted(iterkeys(AllSymbols)): + for symbol in sorted(AllSymbols.keys()): # FIXME: should we print common.LogWarnings for undocumented stuff? # DEBUG # location = "defined at " + GetSymbolSourceFile(symbol) + ":" + GetSymbolSourceLine(symbol) + "\n" @@ -4072,14 +4067,11 @@ def OutputUndeclaredSymbols(): old_undeclared_file = os.path.join(ROOT_DIR, MODULE + "-undeclared.txt") new_undeclared_file = os.path.join(ROOT_DIR, MODULE + "-undeclared.new") - UNDECLARED = common.open_text(new_undeclared_file, 'w') - - if UndeclaredSymbols: - UNDECLARED.write("\n".join(sorted(iterkeys(UndeclaredSymbols)))) - UNDECLARED.write("\n") - print("See %s-undeclared.txt for the list of undeclared symbols." % MODULE) - - UNDECLARED.close() + with open(new_undeclared_file, 'w', encoding='utf-8') as out: + if UndeclaredSymbols: + out.write("\n".join(sorted(UndeclaredSymbols.keys()))) + out.write("\n") + print("See %s-undeclared.txt for the list of undeclared symbols." % MODULE) return common.UpdateFileIfChanged(old_undeclared_file, new_undeclared_file, 0) @@ -4097,18 +4089,17 @@ def OutputUnusedSymbols(): old_unused_file = os.path.join(ROOT_DIR, MODULE + "-unused.txt") new_unused_file = os.path.join(ROOT_DIR, MODULE + "-unused.new") - UNUSED = common.open_text(new_unused_file, 'w') + with open(new_unused_file, 'w', encoding='utf-8') as out: - for symbol in sorted(iterkeys(Declarations)): - if symbol not in DeclarationOutput: - UNUSED.write("%s\n" % symbol) - num_unused += 1 + for symbol in sorted(Declarations.keys()): + if symbol not in DeclarationOutput: + out.write("%s\n" % symbol) + num_unused += 1 - for symbol in sorted(iterkeys(AllUnusedSymbols)): - UNUSED.write(symbol + "(" + AllUnusedSymbols[symbol] + ")\n") - num_unused += 1 + for symbol in sorted(AllUnusedSymbols.keys()): + out.write(symbol + "(" + AllUnusedSymbols[symbol] + ")\n") + num_unused += 1 - UNUSED.close() if num_unused != 0: common.LogWarning( old_unused_file, 1, "%d unused declarations. They should be added to %s-sections.txt in the appropriate place." % (num_unused, MODULE)) @@ -4118,21 +4109,19 @@ def OutputUnusedSymbols(): def OutputAllSymbols(): """Outputs list of all symbols to a file.""" - SYMBOLS = common.open_text(os.path.join(ROOT_DIR, MODULE + "-symbols.txt"), 'w') - - for symbol in sorted(iterkeys(AllSymbols)): - SYMBOLS.write(symbol + "\n") - SYMBOLS.close() + new_symbols_file = os.path.join(ROOT_DIR, MODULE + "-symbols.txt") + with open(new_symbols_file, 'w', encoding='utf-8') as out: + for symbol in sorted(AllSymbols.keys()): + out.write(symbol + "\n") def OutputSymbolsWithoutSince(): """Outputs list of all symbols without a since tag to a file.""" - SYMBOLS = common.open_text(os.path.join(ROOT_DIR, MODULE + "-nosince.txt"), 'w') - - for symbol in sorted(iterkeys(SourceSymbolDocs)): - if symbol in Since: - SYMBOLS.write(symbol + "\n") - SYMBOLS.close() + new_nosince_file = os.path.join(ROOT_DIR, MODULE + "-nosince.txt") + with open(new_nosince_file, 'w', encoding='utf-8') as out: + for symbol in sorted(SourceSymbolDocs.keys()): + if symbol in Since: + out.write(symbol + "\n") def CheckParamsDocumented(symbol, params): @@ -4152,7 +4141,7 @@ def CheckParamsDocumented(symbol, params): if len(params) > 0: logging.info("params: %s", str(params)) - for (param_name, param_desc) in iteritems(params): + for (param_name, param_desc) in params.items(): # Output a warning if the parameter is empty and remember for stats. if param_name != "void" and not re.search(r'\S', param_desc): if symbol in AllIncompleteSymbols: @@ -4178,10 +4167,10 @@ def MergeSourceDocumentation(): """ # add whats found in the source - symbols = set(iterkeys(SourceSymbolDocs)) + symbols = set(SourceSymbolDocs.keys()) # and add known symbols from -sections.txt - for symbol in iterkeys(KnownSymbols): + for symbol in KnownSymbols.keys(): if KnownSymbols[symbol] == 1: symbols.add(symbol) @@ -4265,7 +4254,7 @@ def ReadDeclarationsFile(ifile, override): DeclarationConditional.clear() DeclarationOutput.clear() - INPUT = common.open_text(ifile) + INPUT = open(ifile, 'r', encoding='utf-8') declaration_type = '' declaration_name = None declaration = None @@ -4380,7 +4369,7 @@ def ReadSignalsFile(ifile): if not os.path.isfile(ifile): return - INPUT = common.open_text(ifile) + INPUT = open(ifile, 'r', encoding='utf-8') line_number = 0 for line in INPUT: line_number += 1 @@ -4446,7 +4435,7 @@ def ReadObjectHierarchy(ifile): logging.debug('no *-hierarchy.tx') return - INPUT = common.open_text(ifile) + INPUT = open(ifile, 'r', encoding='utf-8') # Only emit objects if they are supposed to be documented, or if # they have documented children. To implement this, we maintain a @@ -4497,9 +4486,11 @@ def ReadObjectHierarchy(ifile): logging.debug('got %d entries for hierarchy', len(tree)) - OUTPUT = common.open_text(new_tree_index, 'w') - OUTPUT.write(MakeDocHeader("screen") + "\n\n" + AddTreeLineArt(tree) + "\n\n") - OUTPUT.close() + with open(new_tree_index, 'w', encoding='utf-8') as out: + out.write(MakeDocHeader("screen")) + out.write("\n\n") + out.write(AddTreeLineArt(tree)) + out.write("\n\n") common.UpdateFileIfChanged(old_tree_index, new_tree_index, 0) @@ -4518,7 +4509,7 @@ def ReadInterfaces(ifile): if not os.path.isfile(ifile): return - INPUT = common.open_text(ifile) + INPUT = open(ifile, 'r', encoding='utf-8') for line in INPUT: line = line.strip() @@ -4551,7 +4542,7 @@ def ReadPrerequisites(ifile): if not os.path.isfile(ifile): return - INPUT = common.open_text(ifile) + INPUT = open(ifile, 'r', encoding='utf-8') for line in INPUT: line = line.strip() @@ -4602,7 +4593,7 @@ def ReadArgsFile(ifile): if not os.path.isfile(ifile): return - INPUT = common.open_text(ifile) + INPUT = open(ifile, 'r', encoding='utf-8') line_number = 0 for line in INPUT: line_number += 1 diff --git a/gtkdoc/mkhtml2.py b/gtkdoc/mkhtml2.py index f867f1a..fef4876 100644 --- a/gtkdoc/mkhtml2.py +++ b/gtkdoc/mkhtml2.py @@ -19,20 +19,62 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -"""Prototype for builtin docbook processing +"""Generate html from docbook The tool loads the main xml document (-docs.xml) and chunks it like the xsl-stylesheets would do. For that it resolves all the xml-includes. -Each chunk is converted to htnml using python functions. +Each chunk is converted to html using python functions. In contrast to our previous approach of running gtkdoc-mkhtml + gtkdoc-fixxref, this tools will replace both without relying on external tools such as xsltproc and source-highlight. +Please note, that we're not aiming for complete docbook-xml support. All tags +used in the generated xml are of course handled. More tags used in handwritten +xml can be easilly supported, but for some combinations of tags we prefer +simplicity. + TODO: -- more chunk converters +- tag converters: + - 'section'/'simplesect' - the first we convert as a chunk, the nested ones we + need to convert as 'sect{2,3,4,...}, we can track depth in 'ctx' + - inside 'footnote' one can have many tags, we only handle 'para'/'simpara' + - inside 'glossentry' we're only handling 'glossterm' and 'glossdef' + - convert_{figure,table} need counters. - check each docbook tag if it can contain #PCDATA, if not don't check for - xml.text + xml.text/xml.tail and add a comment (# no PCDATA allowed here) +- find a better way to print context for warnings + - we use 'xml.sourceline', but this all does not help a lot due to xi:include +- consolidate title handling: + - always use the titles-dict + - convert_title(): uses titles.get(tid)['title'] + - convert_xref(): uses titles[tid]['tag'], ['title'] and ['xml'] + - create_devhelp2_refsect2_keyword(): uses titles[tid]['title'] + - there only store what we have (xml, tag, ...) + - when chunking generate 'id's and add entries to titles-dict + - add accessors for title and raw_title that lazily get them + - see if any of the other ~10 places that call convert_title() could use this + cache +- performance + - consider some perf-warnings flag + - see 'No "id" attribute on' + - xinclude processing in libxml2 is slow + - if we disable it, we get '{http://www.w3.org/2003/XInclude}include' tags + and we could try handling them ourself, in some cases those are subtrees + that we extract for chunking anyway + +DIFFERENCES: +- titles + - we add the chunk label to the title in toc, on the page and in nav tooltips + - docbook xsl only sometimes adds the label to the titles and when it does it + adds name chunk type too (e.g. 'Part I.' instead of 'I.') +- navigation + - we always add an up-link except on the first page +- footer + - we're nov omitting the footer +- tocs + - we always add "Table of Contents' before a toc + - docbook does that for some pages, it is configurable OPTIONAL: - minify html: https://pypi.python.org/pypi/htmlmin/ @@ -65,54 +107,55 @@ 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 -# TODO: maybe use get_lexer_for_filename() -LEXER = CLexer() +# lazily constructed lexer cache +LEXERS = { + 'c': CLexer() +} HTML_FORMATTER = HtmlFormatter(nowrap=True) -# http://www.sagehill.net/docbookxsl/Chunking.html -CHUNK_TAGS = [ - 'appendix', - 'article', - 'bibliography', # in article or book - 'book', - 'chapter', - 'colophon', - 'glossary', # in article or book - 'index', # in article or book - 'part', - 'preface', - 'refentry', - 'reference', - 'sect1', # except first - 'section', # if equivalent to sect1 - 'set', - 'setindex', -] - class ChunkParams(object): - def __init__(self, prefix, parent=None): + def __init__(self, prefix, parent=None, min_idx=0): self.prefix = prefix - self.parent = None - self.count = 0 + self.parent = parent + self.min_idx = min_idx + self.idx = 1 -# TODO: look up the abbrevs and hierarchy for other tags +DONT_CHUNK = float('inf') +# docbook-xsl defines the chunk tags here. # http://www.sagehill.net/docbookxsl/Chunking.html#GeneratedFilenames # https://github.com/oreillymedia/HTMLBook/blob/master/htmlbook-xsl/chunk.xsl#L33 +# If not defined, we can just create an example without an 'id' attr and see +# docbook xsl does. +# +# For toc levels see http://www.sagehill.net/docbookxsl/TOCcontrol.html +# TODO: this list has also a flag that controls wheter we add the +# 'Table of Contents' heading in convert_chunk_with_toc() CHUNK_PARAMS = { 'appendix': ChunkParams('app', 'book'), 'book': ChunkParams('bk'), 'chapter': ChunkParams('ch', 'book'), + 'glossary': ChunkParams('go', 'book'), 'index': ChunkParams('ix', 'book'), 'part': ChunkParams('pt', 'book'), - 'sect1': ChunkParams('s', 'chapter'), - 'section': ChunkParams('s', 'chapter'), + 'preface': ChunkParams('pr', 'book'), + 'refentry': ChunkParams('re', 'book'), + 'reference': ChunkParams('rn', 'book'), + 'sect1': ChunkParams('s', 'chapter', 1), + 'section': ChunkParams('s', 'chapter', 1), + 'sect2': ChunkParams('s', 'sect1', DONT_CHUNK), + 'sect3': ChunkParams('s', 'sect2', DONT_CHUNK), + 'sect4': ChunkParams('s', 'sect3', DONT_CHUNK), + 'sect5': ChunkParams('s', 'sect4', DONT_CHUNK), } +# TAGS we don't support: +# 'article', 'bibliography', 'colophon', 'set', 'setindex' TITLE_XPATHS = { '_': (etree.XPath('./title'), None), @@ -123,94 +166,188 @@ TITLE_XPATHS = { ), } -ID_XPATH = etree.XPath('//@id') +ID_XPATH = etree.XPath('//*[@id]') +GLOSSENTRY_XPATH = etree.XPath('//glossentry') +glossary = {} -def gen_chunk_name(node): - if 'id' in node.attrib: - return node.attrib['id'] +footnote_idx = 1 - tag = node.tag - if tag not in CHUNK_PARAMS: - CHUNK_PARAMS[tag] = ChunkParams(node.tag[:2]) - logging.warning('Add CHUNK_PARAMS for "%s"', tag) - - naming = CHUNK_PARAMS[tag] - naming.count += 1 - name = ('%s%02d' % (naming.prefix, naming.count)) - # handle parents to make names of nested tags unique - # TODO: we only need to prepend the parent if there are > 1 of them in the - # xml - # while naming.parent: - # parent = naming.parent +# nested dict with subkeys: +# title: textual title +# tag: chunk tag +# xml: title xml node +titles = {} + +# files to copy +assets = set() + + +def encode_entities(text): + return text.replace('&', '&').replace('<', '<').replace('>', '>') + + +def raw_text(xml): + return etree.tostring(xml, method="text", encoding=str).strip() + + +def gen_chunk_name(node, chunk_params): + """Generate a chunk file name + + This is either based on the id or on the position in the doc. In the latter + case it uses a prefix from CHUNK_PARAMS and a sequence number for each chunk + type. + """ + idval = node.attrib.get('id') + if idval is not None: + return idval + + name = ('%s%02d' % (chunk_params.prefix, chunk_params.idx)) + chunk_params.idx += 1 + + # handle parents to make names of nested tags like in docbook + # - we only need to prepend the parent if there are > 1 of them in the + # xml. None, the parents we have are not sufficient, e.g. 'index' can + # be in 'book' or 'part' or ... Maybe we can track the chunk_parents + # when we chunk explicitly and on each level maintain the 'idx' + # while chunk_params.parent: + # parent = chunk_params.parent # if parent not in CHUNK_PARAMS: # break; - # naming = CHUNK_PARAMS[parent] - # name = ('%s%02d' % (naming.prefix, naming.count)) + name + # chunk_params = CHUNK_PARAMS[parent] + # name = ('%s%02d' % (chunk_params.prefix, chunk_params.idx)) + name + + logging.info('Gen chunk name: "%s"', name) return name -def get_chunk_titles(node): +def get_chunk_titles(module, node): tag = node.tag - if tag not in TITLE_XPATHS: - # Use defaults - (title, subtitle) = TITLE_XPATHS['_'] - else: - (title, subtitle) = TITLE_XPATHS[tag] + (title, subtitle) = TITLE_XPATHS.get(tag, TITLE_XPATHS['_']) - xml = title(node)[0] + ctx = { + 'module': module, + 'files': [], + } result = { - 'title': xml.text + 'title': None, + 'title_tag': None, + 'subtitle': None, + 'subtitle_tag': None } - if xml.tag != 'title': - result['title_tag'] = xml.tag - else: - result['title_tag'] = tag + res = title(node) + if res: + # handle chunk label for tocs + label = node.attrib.get('label') + if label: + label += '. ' + else: + label = '' + + xml = res[0] + # TODO: consider to eval 'title'/'raw_title' lazily + result['title'] = label + ''.join(convert_title(ctx, xml)) + result['raw_title'] = encode_entities(raw_text(xml)) + if xml.tag != 'title': + result['title_tag'] = xml.tag + else: + result['title_tag'] = tag if subtitle: - xml = subtitle(node)[0] - result['subtitle'] = xml.text - result['subtitle_tag'] = xml.tag - else: - result['subtitle'] = None - result['subtitle_tag'] = None + res = subtitle(node) + if res: + xml = res[0] + result['subtitle'] = ''.join(convert_title(ctx, xml)) + result['subtitle_tag'] = xml.tag return result -def chunk(xml_node, parent=None): +def chunk(xml_node, module, depth=0, idx=0, parent=None): """Chunk the tree. The first time, we're called with parent=None and in that case we return - the new_node as the root of the tree + the new_node as the root of the tree. For each tree-node we generate a + filename and process the children. """ - if xml_node.tag in CHUNK_TAGS: - if parent: - # remove the xml-node from the parent - sub_tree = etree.ElementTree(deepcopy(xml_node)).getroot() - xml_node.getparent().remove(xml_node) - xml_node = sub_tree - - title_args = get_chunk_titles(xml_node) - chunk_name = gen_chunk_name(xml_node) - parent = Node(xml_node.tag, parent=parent, xml=xml_node, - filename=chunk_name + '.html', **title_args) - - for child in xml_node: - chunk(child, parent) + tag = xml_node.tag + chunk_params = CHUNK_PARAMS.get(tag) + if chunk_params: + title_args = get_chunk_titles(module, xml_node) + chunk_name = gen_chunk_name(xml_node, chunk_params) + + # check idx to handle 'sect1'/'section' special casing and title-only + # segments + if idx >= chunk_params.min_idx: + logging.info('chunk tag: "%s"[%d]', tag, idx) + if parent: + # remove the xml-node from the parent + sub_tree = etree.ElementTree(deepcopy(xml_node)).getroot() + xml_node.getparent().remove(xml_node) + xml_node = sub_tree + + parent = Node(tag, parent=parent, xml=xml_node, depth=depth, + idx=idx, + filename=chunk_name + '.html', anchor=None, + **title_args) + else: + parent = Node(tag, parent=parent, xml=xml_node, depth=depth, + idx=idx, + filename=parent.filename, anchor='#' + chunk_name, + **title_args) + + depth += 1 + idx = 0 + for child in xml_node: + chunk(child, module, depth, idx, parent) + if child.tag in CHUNK_PARAMS: + idx += 1 return parent -def add_id_links(files, links): +def add_id_links_and_titles(files, links): for node in files: chunk_name = node.filename[:-5] chunk_base = node.filename + '#' - for attr in ID_XPATH(node.xml): + for elem in ID_XPATH(node.xml): + attr = elem.attrib['id'] if attr == chunk_name: links[attr] = node.filename else: links[attr] = chunk_base + attr + title = TITLE_XPATHS.get(elem.tag, TITLE_XPATHS['_'])[0] + res = title(elem) + if res: + xml = res[0] + # TODO: consider to eval 'title' lazily + titles[attr] = { + 'title': encode_entities(raw_text(xml)), + 'xml': xml, + 'tag': elem.tag, + } + + +def build_glossary(files): + for node in files: + if node.xml.tag != 'glossary': + continue + for term in GLOSSENTRY_XPATH(node.xml): + # TODO: there can be all kind of things in a glossary. This only supports + # what we commonly use, glossterm is mandatory + key_node = term.find('glossterm') + val_node = term.find('glossdef') + if key_node is not None and val_node is not None: + glossary[raw_text(key_node)] = raw_text(val_node) + else: + debug = [] + if key_node is None: + debug.append('missing key') + if val_node is None: + debug.append('missing val') + logging.warning('Broken glossentry "%s": %s', + term.attrib['id'], ','.join(debug)) + # conversion helpers @@ -227,7 +364,18 @@ def convert_ignore(ctx, xml): def convert_skip(ctx, xml): - return [''] + return [] + + +def append_idref(attrib, result): + idval = attrib.get('id') + if idval is not None: + result.append('' % idval) + + +def append_text(ctx, text, result): + if text and ('no-strip' in ctx or text.strip()): + result.append(encode_entities(text)) missing_tags = {} @@ -235,51 +383,95 @@ missing_tags = {} def convert__unknown(ctx, xml): # don't recurse on subchunks - if xml.tag in CHUNK_TAGS: + if xml.tag in CHUNK_PARAMS: return [] - # warn only once - if xml.tag not in missing_tags: - logging.warning('Add tag converter for "%s"', xml.tag) - missing_tags[xml.tag] = True - result = ['\n'] - convert_inner(ctx, xml, result) - result.append('\n') - return result - - -def convert_refsect(ctx, xml, h_tag, inner_func=convert_inner): + if isinstance(xml, etree._Comment): + return ['\n'] + else: + # warn only once + if xml.tag not in missing_tags: + logging.warning('Add tag converter for "%s"', xml.tag) + missing_tags[xml.tag] = True + result = ['\n'] + convert_inner(ctx, xml, result) + result.append('\n') + return result + + +def convert_mediaobject_children(ctx, xml, result): + # look for textobject/phrase + alt_text = '' + textobject = xml.find('textobject') + if textobject is not None: + phrase = textobject.findtext('phrase') + if phrase: + alt_text = ' alt="%s"' % phrase + + # look for imageobject/imagedata + imageobject = xml.find('imageobject') + if imageobject is not None: + imagedata = imageobject.find('imagedata') + if imagedata is not None: + # TODO(ensonic): warn on missing fileref attr? + fileref = imagedata.attrib.get('fileref', '') + if fileref: + assets.add(fileref) + result.append('' % (fileref, alt_text)) + + +def convert_sect(ctx, xml, h_tag, inner_func=convert_inner): result = ['
\n' % xml.tag] - title = xml.find('title') - if title is not None: - if 'id' in xml.attrib: - result.append('' % xml.attrib['id']) - result.append('<%s>%s' % (h_tag, title.text, h_tag)) - xml.remove(title) - if xml.text: - result.append(xml.text) + title_tag = xml.find('title') + if title_tag is not None: + append_idref(xml.attrib, result) + result.append('<%s>%s' % ( + h_tag, ''.join(convert_title(ctx, title_tag)), h_tag)) + append_text(ctx, xml.text, result) inner_func(ctx, xml, result) result.append('
') - if xml.tail: - result.append(xml.tail) + append_text(ctx, xml.tail, result) return result -def xml_get_title(xml): - title = xml.find('title') - if title is not None: - return title.text +def xml_get_title(ctx, xml): + title_tag = xml.find('title') + if title_tag is not None: + return ''.join(convert_title(ctx, title_tag)) else: - # TODO(ensonic): any way to get the file (inlcudes) too? logging.warning('%s: Expected title tag under "%s %s"', xml.sourceline, xml.tag, str(xml.attrib)) return '' # docbook tags + +def convert_abstract(ctx, xml): + result = ["""
+

Abstract

"""] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('
') + append_text(ctx, xml.tail, result) + return result + + +def convert_acronym(ctx, xml): + key = xml.text + title = glossary.get(key, '') + # TODO: print a sensible warning if missing + result = ['%s' % (title, key)] + if xml.tail: + result.append(xml.tail) + return result + + +def convert_anchor(ctx, xml): + return ['' % xml.attrib['id']] + + def convert_bookinfo(ctx, xml): result = ['
'] - for releaseinfo in xml.findall('releaseinfo'): - result.extend(convert_para(ctx, releaseinfo)) + convert_inner(ctx, xml, result) result.append("""
""") if xml.tail: @@ -289,64 +481,220 @@ def convert_bookinfo(ctx, xml): def convert_blockquote(ctx, xml): result = ['
\n
'] - if xml.text: - result.append(xml.text) + append_text(ctx, xml.text, result) convert_inner(ctx, xml, result) result.append('
\n
') - if xml.tail: - result.append(xml.tail) + append_text(ctx, xml.tail, result) + return result + + +def convert_code(ctx, xml): + result = ['' % xml.tag] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) return result def convert_colspec(ctx, xml): result = ['\n') # is in tgroup and there can be no 'text' return result +def convert_command(ctx, xml): + result = [''] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + +def convert_corpauthor(ctx, xml): + result = ['

\n'] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('

\n') + append_text(ctx, xml.tail, result) + return result + + def convert_div(ctx, xml): result = ['
\n' % xml.tag] - if xml.text: - result.append(xml.text) + append_text(ctx, xml.text, result) convert_inner(ctx, xml, result) result.append('
') - if xml.tail: - result.append(xml.tail) + append_text(ctx, xml.tail, result) + return result + + +def convert_emphasis(ctx, xml): + role = xml.attrib.get('role') + if role is not None: + result = ['' % role] + end = '' + else: + result = [''] + end = '' + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append(end) + append_text(ctx, xml.tail, result) return result -def convert_em_class(ctx, xml): +def convert_em(ctx, xml): + result = ['' % xml.tag] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + +def convert_em_code(ctx, xml): result = ['' % xml.tag] - if xml.text: - result.append(xml.text) + append_idref(xml.attrib, result) + append_text(ctx, xml.text, result) convert_inner(ctx, xml, result) result.append('') - if xml.tail: - result.append(xml.tail) + append_text(ctx, xml.tail, result) return result def convert_entry(ctx, xml): - result = ['' % xml.attrib['role']) + entry_type = ctx['table.entry'] + result = ['<' + entry_type] + role = xml.attrib.get('role') + if role is not None: + result.append(' class="%s"' % role) + morerows = xml.attrib.get('morerows') + if morerows is not None: + result.append(' rowspan="%s"' % (1 + int(morerows))) + result.append('>') + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + +def convert_figure(ctx, xml): + result = ['
\n'] + append_idref(xml.attrib, result) + title_tag = xml.find('title') + if title_tag is not None: + # TODO(ensonic): Add a 'Figure X. ' prefix, needs a figure counter + result.append('

%s

' % ''.join(convert_title(ctx, title_tag))) + result.append('
') + # TODO(ensonic): title can become alt on inner 'graphic' element + convert_inner(ctx, xml, result) + result.append('

') + append_text(ctx, xml.tail, result) + return result + + +def convert_footnote(ctx, xml): + footnotes = ctx.get('footnotes', []) + # footnotes idx is not per page, but per doc + global footnote_idx + idx = footnote_idx + footnote_idx += 1 + + # need a pair of ids for each footnote (docbook generates different ids) + this_id = 'footnote-%d' % idx + that_id = 'ftn.' + this_id + + inner = ['
' % that_id] + inner.append('

[%d] ' % ( + this_id, idx)) + # TODO(ensonic): this can contain all kind of tags, if we convert them we'll + # get double nested paras :/. + # convert_inner(ctx, xml, inner) + para = xml.find('para') + if para is None: + para = xml.find('simpara') + if para is not None: + inner.append(para.text) else: - result.append('>') - if xml.text: - result.append(xml.text) + logging.warning('%s: Unhandled footnote content: %s', xml.sourceline, raw_text(xml)) + inner.append('

') + footnotes.append(inner) + ctx['footnotes'] = footnotes + return ['[%s]' % ( + that_id, this_id, idx)] + + +def convert_formalpara(ctx, xml): + result = None + title_tag = xml.find('title') + result = ['

%s' % ''.join(convert_title(ctx, title_tag))] + para_tag = xml.find('para') + append_text(ctx, para_tag.text, result) + convert_inner(ctx, para_tag, result) + append_text(ctx, para_tag.tail, result) + result.append('

') + append_text(ctx, xml.tail, result) + return result + + +def convert_glossdef(ctx, xml): + result = ['
'] + convert_inner(ctx, xml, result) + result.append('
\n') + return result + + +def convert_glossdiv(ctx, xml): + title_tag = xml.find('title') + title = title_tag.text + xml.remove(title_tag) + result = [ + '

%s

' % (title, title) + ] + convert_inner(ctx, xml, result) + return result + + +def convert_glossentry(ctx, xml): + result = [] convert_inner(ctx, xml, result) - result.append('') - if xml.tail: - result.append(xml.tail) return result +def convert_glossterm(ctx, xml): + glossid = '' + text = '' + anchor = xml.find('anchor') + if anchor is not None: + glossid = anchor.attrib.get('id', '') + text += anchor.tail or '' + text += xml.text or '' + if glossid == '': + glossid = 'glossterm-' + text + return [ + '
%s
' % ( + glossid, text) + ] + + +def convert_graphic(ctx, xml): + # TODO(ensonic): warn on missing fileref attr? + fileref = xml.attrib.get('fileref', '') + if fileref: + assets.add(fileref) + return ['
' % fileref] + + def convert_indexdiv(ctx, xml): title_tag = xml.find('title') title = title_tag.text @@ -360,10 +708,9 @@ def convert_indexdiv(ctx, xml): def convert_informaltable(ctx, xml): result = ['
\n') convert_inner(ctx, xml, result) @@ -373,6 +720,23 @@ def convert_informaltable(ctx, xml): return result +def convert_inlinegraphic(ctx, xml): + # TODO(ensonic): warn on missing fileref attr? + fileref = xml.attrib.get('fileref', '') + if fileref: + assets.add(fileref) + return ['' % fileref] + + +def convert_inlinemediaobject(ctx, xml): + result = [''] + # no PCDATA allowed here + convert_mediaobject_children(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + def convert_itemizedlist(ctx, xml): result = ['
    '] convert_inner(ctx, xml, result) @@ -384,18 +748,30 @@ def convert_itemizedlist(ctx, xml): def convert_link(ctx, xml): linkend = xml.attrib['linkend'] - if linkend in fixxref.NoLinks: - linkend = None result = [] if linkend: link_text = [] + append_text(ctx, xml.text, link_text) convert_inner(ctx, xml, link_text) - if xml.text: - link_text.append(xml.text) - # TODO: fixxref does some weird checks in xml.text - result = [fixxref.MakeXRef(ctx['module'], '', 0, linkend, ''.join(link_text))] - if xml.tail: - result.append(xml.tail) + text = ''.join(link_text) + + (tid, href) = fixxref.GetXRef(linkend) + if href: + title_attr = '' + title = titles.get(tid) + if title: + title_attr = ' title="%s"' % title['title'] + + href = fixxref.MakeRelativeXRef(ctx['module'], href) + result = ['%s' % (href, title_attr, text)] + else: + # TODO: filename is for the output and xml.sourceline is on the masterdoc ... + fixxref.ReportBadXRef(ctx['node'].filename, 0, linkend, text) + result = [text] + else: + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + append_text(ctx, xml.tail, result) return result @@ -403,55 +779,73 @@ def convert_listitem(ctx, xml): result = ['
  • '] convert_inner(ctx, xml, result) result.append('
    • ') - # is in itemizedlist and there can be no 'text' + # no PCDATA allowed here, is in itemizedlist return result -def convert_literal(ctx, xml): - result = ['' % xml.tag] - if xml.text: - result.append(xml.text) +def convert_literallayout(ctx, xml): + result = ['


    \n'] + append_text(ctx, xml.text, result) convert_inner(ctx, xml, result) - result.append('    ') - if xml.tail: - result.append(xml.tail) + result.append('

    ') + append_text(ctx, xml.tail, result) + return result + + +def convert_mediaobject(ctx, xml): + result = ['
    \n'] + # no PCDATA allowed here + convert_mediaobject_children(ctx, xml, result) + result.append('
    ') + append_text(ctx, xml.tail, result) return result def convert_orderedlist(ctx, xml): - result = ['
      '] + result = ['
        '] convert_inner(ctx, xml, result) result.append('
      ') - if xml.tail: - result.append(xml.tail) + append_text(ctx, xml.tail, result) return result def convert_para(ctx, xml): - result = ['

      '] - if xml.tag != 'para': - result = ['

      ' % xml.tag] - if xml.text: - result.append(xml.text) + result = [] + role = xml.attrib.get('role') + if role is not None: + result.append('

      ' % role) + else: + result.append('

      ') + append_idref(xml.attrib, result) + append_text(ctx, xml.text, result) convert_inner(ctx, xml, result) result.append('

      ') - if xml.tail: - result.append(xml.tail) + append_text(ctx, xml.tail, result) + return result + + +def convert_para_like(ctx, xml): + result = [] + append_idref(xml.attrib, result) + result.append('

      ' % xml.tag) + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('

      ') + append_text(ctx, xml.tail, result) return result def convert_phrase(ctx, xml): result = ['' % xml.attrib['role']) + role = xml.attrib.get('role') + if role is not None: + result.append(' class="%s">' % role) else: result.append('>') - if xml.text: - result.append(xml.text) + append_text(ctx, xml.text, result) convert_inner(ctx, xml, result) result.append('') - if xml.tail: - result.append(xml.tail) + append_text(ctx, xml.tail, result) return result @@ -463,13 +857,14 @@ def convert_primaryie(ctx, xml): def convert_pre(ctx, xml): - result = ['
      \n' % xml.tag]
-    if xml.text:
-        result.append(xml.text)
+    # Since we're inside 
       don't skip newlines
+    ctx['no-strip'] = True
+    result = ['
      ' % xml.tag]
+    append_text(ctx, xml.text, result)
     convert_inner(ctx, xml, result)
     result.append('
      ')
-    if xml.tail:
-        result.append(xml.tail)
+    del ctx['no-strip']
+    append_text(ctx, xml.tail, result)
     return result
 
 
@@ -477,13 +872,17 @@ def convert_programlisting(ctx, xml):
     result = []
     if xml.attrib.get('role', '') == 'example':
         if xml.text:
-            # TODO: check 'language' attr and use respective lexer
-            highlighted = highlight(xml.text, LEXER, HTML_FORMATTER)
-
-            # we do own line-numbering
-            line_count = highlighted.count('\n')
-            source_lines = '\n'.join([str(i) for i in range(1, line_count + 1)])
-            result.append("""
+ lang = xml.attrib.get('language', ctx['src-lang']).lower() + if lang not in LEXERS: + LEXERS[lang] = get_lexer_by_name(lang) + lexer = LEXERS.get(lang, None) + if lexer: + highlighted = highlight(xml.text, lexer, HTML_FORMATTER) + + # we do own line-numbering + line_count = highlighted.count('\n') + source_lines = '\n'.join([str(i) for i in range(1, line_count + 1)]) + result.append("""
@@ -492,14 +891,26 @@ def convert_programlisting(ctx, xml): 
%s
""" % (source_lines, highlighted)) + else: + logging.warn('No pygments lexer for language="%s"', lang) + result.append('
')
+                result.append(xml.text)
+                result.append('
') else: result.append('
')
-        if xml.text:
-            result.append(xml.text)
+        append_text(ctx, xml.text, result)
         convert_inner(ctx, xml, result)
         result.append('
') - if xml.tail: - result.append(xml.tail) + append_text(ctx, xml.tail, result) + return result + + +def convert_quote(ctx, xml): + result = ['"'] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('"') + append_text(ctx, xml.tail, result) return result @@ -512,15 +923,15 @@ def convert_refsect1(ctx, xml): result.append('
\n') result.extend(convert_tags.get(child.tag, convert__unknown)(ctx, child)) prev = child - return convert_refsect(ctx, xml, 'h2', convert_inner) + return convert_sect(ctx, xml, 'h2', convert_inner) def convert_refsect2(ctx, xml): - return convert_refsect(ctx, xml, 'h3') + return convert_sect(ctx, xml, 'h3') def convert_refsect3(ctx, xml): - return convert_refsect(ctx, xml, 'h4') + return convert_sect(ctx, xml, 'h4') def convert_row(ctx, xml): @@ -530,29 +941,73 @@ def convert_row(ctx, xml): return result +def convert_sbr(ctx, xml): + return ['
'] + + +def convert_sect1_tag(ctx, xml): + return convert_sect(ctx, xml, 'h2') + + +def convert_sect2(ctx, xml): + return convert_sect(ctx, xml, 'h3') + + +def convert_sect3(ctx, xml): + return convert_sect(ctx, xml, 'h4') + + def convert_simpara(ctx, xml): result = ['

'] - if xml.text: - result.append(xml.text) + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) result.append('

') - if xml.tail: - result.append(xml.tail) + append_text(ctx, xml.tail, result) return result def convert_span(ctx, xml): result = ['' % xml.tag] - if xml.text: - result.append(xml.text) + append_text(ctx, xml.text, result) convert_inner(ctx, xml, result) result.append('') - if xml.tail: - result.append(xml.tail) + append_text(ctx, xml.tail, result) + return result + + +def convert_table(ctx, xml): + result = ['
'] + append_idref(xml.attrib, result) + title_tag = xml.find('title') + if title_tag is not None: + result.append('

') + # TODO(ensonic): Add a 'Table X. ' prefix, needs a table counter + result.extend(convert_title(ctx, title_tag)) + result.append('

') + result.append('
') + + convert_inner(ctx, xml, result) + + result.append('
') + append_text(ctx, xml.tail, result) + return result + + +def convert_tag(ctx, xml): + classval = xml.attrib.get('class') + if classval is not None: + result = ['' % classval] + else: + result = [''] + append_text(ctx, xml.text, result) + result.append('') + append_text(ctx, xml.tail, result) return result def convert_tbody(ctx, xml): result = [''] + ctx['table.entry'] = 'td' convert_inner(ctx, xml, result) result.append('') # is in tgroup and there can be no 'text' @@ -575,50 +1030,187 @@ def convert_tgroup(ctx, xml): return result +def convert_thead(ctx, xml): + result = [''] + ctx['table.entry'] = 'th' + convert_inner(ctx, xml, result) + result.append('') + # is in tgroup and there can be no 'text' + return result + + +def convert_title(ctx, xml): + # This is always explicitly called from some context + result = [] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + append_text(ctx, xml.tail, result) + return result + + def convert_ulink(ctx, xml): - result = ['%s' % (xml.tag, xml.attrib['url'], xml.text)] - if xml.tail: - result.append(xml.tail) + if xml.text: + result = ['%s' % (xml.tag, xml.attrib['url'], xml.text)] + else: + url = xml.attrib['url'] + result = ['%s' % (xml.tag, url, url)] + append_text(ctx, xml.tail, result) + return result + + +def convert_userinput(ctx, xml): + result = [''] + append_text(ctx, xml.text, result) + convert_inner(ctx, xml, result) + result.append('') + append_text(ctx, xml.tail, result) + return result + + +def convert_variablelist(ctx, xml): + result = ["""
++++ +"""] + convert_inner(ctx, xml, result) + result.append(""" +
""") + return result + + +def convert_varlistentry(ctx, xml): + result = [''] + + result.append('

') + term = xml.find('term') + result.extend(convert_span(ctx, term)) + result.append('

') + + result.append('') + listitem = xml.find('listitem') + convert_inner(ctx, listitem, result) + result.append('') + + result.append('') + return result + + +def convert_xref(ctx, xml): + result = [] + linkend = xml.attrib['linkend'] + (tid, href) = fixxref.GetXRef(linkend) + try: + title = titles[tid] + # all sectN need to become 'section + tag = title['tag'] + tag = { + 'sect1': 'section', + 'sect2': 'section', + 'sect3': 'section', + 'sect4': 'section', + 'sect5': 'section', + }.get(tag, tag) + result = [ + 'the %s called “%s”' % + (href, title['title'], tag, ''.join(convert_title(ctx, title['xml']))) + ] + except KeyError: + logging.warning('invalid linkend "%s"', tid) + + append_text(ctx, xml.tail, result) return result # TODO(ensonic): turn into class with converters as functions and ctx as self convert_tags = { + 'abstract': convert_abstract, + 'acronym': convert_acronym, + 'anchor': convert_anchor, + 'application': convert_span, 'bookinfo': convert_bookinfo, 'blockquote': convert_blockquote, + 'classname': convert_code, + 'caption': convert_div, + 'code': convert_code, 'colspec': convert_colspec, + 'constant': convert_code, + 'command': convert_command, + 'corpauthor': convert_corpauthor, + 'emphasis': convert_emphasis, 'entry': convert_entry, - 'function': convert_span, + 'envar': convert_code, + 'footnote': convert_footnote, + 'figure': convert_figure, + 'filename': convert_code, + 'firstterm': convert_em, + 'formalpara': convert_formalpara, + 'function': convert_code, + 'glossdef': convert_glossdef, + 'glossdiv': convert_glossdiv, + 'glossentry': convert_glossentry, + 'glossterm': convert_glossterm, + 'graphic': convert_graphic, 'indexdiv': convert_indexdiv, 'indexentry': convert_ignore, 'indexterm': convert_skip, 'informalexample': convert_div, 'informaltable': convert_informaltable, + 'inlinegraphic': convert_inlinegraphic, + 'inlinemediaobject': convert_inlinemediaobject, + 'interfacename': convert_code, 'itemizedlist': convert_itemizedlist, + 'legalnotice': convert_div, 'link': convert_link, 'listitem': convert_listitem, - 'literal': convert_literal, + 'literal': convert_code, + 'literallayout': convert_literallayout, + 'mediaobject': convert_mediaobject, 'note': convert_div, + 'option': convert_code, 'orderedlist': convert_orderedlist, 'para': convert_para, - 'parameter': convert_em_class, + 'partintro': convert_div, + 'parameter': convert_em_code, 'phrase': convert_phrase, 'primaryie': convert_primaryie, 'programlisting': convert_programlisting, - 'releaseinfo': convert_para, + 'quote': convert_quote, + 'releaseinfo': convert_para_like, 'refsect1': convert_refsect1, 'refsect2': convert_refsect2, 'refsect3': convert_refsect3, + 'replaceable': convert_em_code, 'returnvalue': convert_span, 'row': convert_row, + 'sbr': convert_sbr, 'screen': convert_pre, + 'section': convert_sect2, # FIXME: need tracking of nesting + 'sect1': convert_sect1_tag, + 'sect2': convert_sect2, + 'sect3': convert_sect3, 'simpara': convert_simpara, - 'structfield': convert_em_class, + 'simplesect': convert_sect2, # FIXME: need tracking of nesting + 'structfield': convert_em_code, + 'structname': convert_span, + 'synopsis': convert_pre, + 'symbol': convert_span, + 'table': convert_table, + 'tag': convert_tag, 'tbody': convert_tbody, + 'term': convert_span, 'tgroup': convert_tgroup, + 'thead': convert_thead, + 'title': convert_skip, 'type': convert_span, 'ulink': convert_ulink, + 'userinput': convert_userinput, + 'varname': convert_code, + 'variablelist': convert_variablelist, + 'varlistentry': convert_varlistentry, 'warning': convert_div, + 'xref': convert_xref, } # conversion helpers @@ -637,17 +1229,21 @@ HTML_HEADER = """ def generate_head_links(ctx): n = ctx['nav_home'] result = [ - '\n' % (n.filename, n.title) + '\n' % (n.filename, n.raw_title) ] - if 'nav_up' in ctx: - n = ctx['nav_up'] - result.append('\n' % (n.filename, n.title)) - if 'nav_prev' in ctx: - n = ctx['nav_prev'] - result.append('\n' % (n.filename, n.title)) - if 'nav_next' in ctx: - n = ctx['nav_next'] - result.append('\n' % (n.filename, n.title)) + + n = ctx.get('nav_up') + if n is not None: + result.append('\n' % (n.filename, n.raw_title)) + + n = ctx.get('nav_prev') + if n is not None: + result.append('\n' % (n.filename, n.raw_title)) + + n = ctx.get('nav_next') + if n is not None: + result.append('\n' % (n.filename, n.raw_title)) + return ''.join(result) @@ -656,20 +1252,23 @@ def generate_nav_links(ctx): result = [ 'Home' % n.filename ] - if 'nav_up' in ctx: - n = ctx['nav_up'] + + n = ctx.get('nav_up') + if n is not None: result.append( 'Up' % n.filename) else: result.append('') - if 'nav_prev' in ctx: - n = ctx['nav_prev'] + + n = ctx.get('nav_prev') + if n is not None: result.append( 'Prev' % n.filename) else: result.append('') - if 'nav_next' in ctx: - n = ctx['nav_next'] + + n = ctx.get('nav_next') + if n is not None: result.append( 'Next' % n.filename) else: @@ -682,8 +1281,11 @@ def generate_toc(ctx, node): result = [] for c in node.children: # TODO: urlencode the filename: urllib.parse.quote_plus() + link = c.filename + if c.anchor: + link += c.anchor result.append('
%s\n' % ( - c.title_tag, c.filename, c.title)) + c.title_tag, link, c.title)) if c.subtitle: result.append(' — %s' % (c.subtitle_tag, c.subtitle)) result.append('
\n') @@ -704,42 +1306,53 @@ def generate_basic_nav(ctx): """ % generate_nav_links(ctx) -def generate_index_nav(ctx, indexdivs): +def generate_alpha_nav(ctx, divs, prefix, span_id): ix_nav = [] - for s in indexdivs: - title = xml_get_title(s) - ix_nav.append('%s' % (title, title)) + for s in divs: + title = xml_get_title(ctx, s) + ix_nav.append('%s' % (prefix, title, title)) return """ %s - """ % ('\n|\n'.join(ix_nav), generate_nav_links(ctx)) + """ % (span_id, '\n|\n'.join(ix_nav), generate_nav_links(ctx)) def generate_refentry_nav(ctx, refsect1s, result): - result.append(""" + result.append(""" - %s @@ -748,24 +1361,87 @@ def generate_refentry_nav(ctx, refsect1s, result): """ % generate_nav_links(ctx)) -def get_id(node): - xml = node.xml - node_id = xml.attrib.get('id', None) - if node_id: - return node_id +def generate_footer(ctx): + footnotes = ctx.get('footnotes') + if footnotes is None: + return [] + + result = ["""
\n +
+"""] + for f in footnotes: + result.extend(f) + result.append('
\n') + return result - logging.warning('%d: No "id" attribute on "%s"', xml.sourceline, xml.tag) + +def get_id_path(node): + """ Generate the 'id'. + We need to walk up the xml-tree and check the positions for each sibling. + When reaching the top of the tree we collect remaining index entries from + the chunked-tree. + """ ix = [] - # Generate the 'id'. We need to walk up the xml-tree and check the positions - # for each sibling. + xml = node.xml parent = xml.getparent() while parent is not None: children = parent.getchildren() ix.insert(0, str(children.index(xml) + 1)) xml = parent parent = xml.getparent() + while node is not None: + ix.insert(0, str(node.idx + 1)) + node = node.parent + + return ix + + +def get_id(node): + xml = node.xml + node_id = xml.attrib.get('id', None) + if node_id: + return node_id + + # TODO: this is moot if nothing links to it, we could also consider to omit + # the tag. + logging.info('%d: No "id" attribute on "%s", generating one', + xml.sourceline, xml.tag) + ix = get_id_path(node) # logging.warning('%s: id indexes: %s', node.filename, str(ix)) - return 'id-1.' + '.'.join(ix) + return 'id-' + '.'.join(ix) + + +def convert_chunk_with_toc(ctx, div_class, title_tag): + node = ctx['node'] + result = [ + HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)), + generate_basic_nav(ctx), + '
' % div_class, + ] + if node.title: + result.append(""" +
+<%s class="title">%s +
""" % ( + title_tag, get_id(node), node.title, title_tag)) + + toc = generate_toc(ctx, node) + if toc: + # TODO: not all docbook page types use this extra heading + result.append("""

Table of Contents

+
+
+ """) + result.extend(toc) + result.append("""
+
+ """) + convert_inner(ctx, node.xml, result) + result.extend(generate_footer(ctx)) + result.append("""
+ +""") + return result # docbook chunks @@ -789,32 +1465,34 @@ def convert_book(ctx): result.extend(generate_toc(ctx, node.root)) result.append(""" - +""") + result.extend(generate_footer(ctx)) + result.append("""""") return result def convert_chapter(ctx): + return convert_chunk_with_toc(ctx, 'chapter', 'h2') + + +def convert_glossary(ctx): node = ctx['node'] + glossdivs = node.xml.findall('glossdiv') + result = [ HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)), - generate_basic_nav(ctx), - '
', + generate_alpha_nav(ctx, glossdivs, 'gls', 'glossary'), + """
+
+%s +
""" % (node.depth, get_id(node), node.title, node.depth) ] - title = node.xml.find('title') - if title is not None: - result.append('

%s

' % ( - get_id(node), title.text)) - node.xml.remove(title) - convert_inner(ctx, node.xml, result) - result.append("""
-
-""") - result.extend(generate_toc(ctx, node)) - result.append("""
-
-
+ for i in glossdivs: + result.extend(convert_glossdiv(ctx, i)) + result.extend(generate_footer(ctx)) + result.append("""
""") return result @@ -822,31 +1500,68 @@ def convert_chapter(ctx): def convert_index(ctx): node = ctx['node'] - node_id = get_id(node) # Get all indexdivs under indexdiv indexdivs = node.xml.find('indexdiv').findall('indexdiv') result = [ HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)), - generate_index_nav(ctx, indexdivs), + generate_alpha_nav(ctx, indexdivs, 'idx', 'index'), """
-

-%s

-
""" % (node_id, node.title) +
+%s +
""" % (node.depth, get_id(node), node.title, node.depth) ] for i in indexdivs: result.extend(convert_indexdiv(ctx, i)) + result.extend(generate_footer(ctx)) result.append("""
""") return result +def convert_part(ctx): + return convert_chunk_with_toc(ctx, 'part', 'h1') + + +def convert_preface(ctx): + node = ctx['node'] + result = [ + HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)), + generate_basic_nav(ctx), + '
' + ] + if node.title: + result.append(""" +
+

%s

+
""" % (get_id(node), node.title)) + convert_inner(ctx, node.xml, result) + result.extend(generate_footer(ctx)) + result.append("""
+ +""") + return result + + +def convert_reference(ctx): + return convert_chunk_with_toc(ctx, 'reference', 'h1') + + def convert_refentry(ctx): node = ctx['node'] node_id = get_id(node) refsect1s = node.xml.findall('refsect1') + gallery = '' + refmeta = node.xml.find('refmeta') + if refmeta is not None: + refmiscinfo = refmeta.find('refmiscinfo') + if refmiscinfo is not None: + inlinegraphic = refmiscinfo.find('inlinegraphic') + if inlinegraphic is not None: + gallery = ''.join(convert_inlinegraphic(ctx, inlinegraphic)) + result = [ HTML_HEADER % (node.title + ": " + node.root.title, generate_head_links(ctx)) ] @@ -858,27 +1573,42 @@ def convert_refentry(ctx): - +

%s

-

%s — module for gtk-doc unit test

+

%s — %s

%s
-""" % (node_id, node_id, node.title, node.title)) +""" % (node_id, node_id, node.title, node.title, node.subtitle, gallery)) for s in refsect1s: result.extend(convert_refsect1(ctx, s)) + result.extend(generate_footer(ctx)) result.append(""" """) return result +def convert_section(ctx): + return convert_chunk_with_toc(ctx, 'section', 'h2') + + +def convert_sect1(ctx): + return convert_chunk_with_toc(ctx, 'sect1', 'h2') + + # TODO(ensonic): turn into class with converters as functions and ctx as self convert_chunks = { 'book': convert_book, 'chapter': convert_chapter, + 'glossary': convert_glossary, 'index': convert_index, + 'part': convert_part, + 'preface': convert_preface, + 'reference': convert_reference, 'refentry': convert_refentry, + 'section': convert_section, + 'sect1': convert_sect1, } @@ -897,7 +1627,7 @@ def generate_nav_nodes(files, node): return nav -def convert(out_dir, module, files, node): +def convert(out_dir, module, files, node, src_lang): """Convert the docbook chunks to a html file. Args: @@ -907,45 +1637,57 @@ def convert(out_dir, module, files, node): """ logging.info('Writing: %s', node.filename) - with open(os.path.join(out_dir, node.filename), 'wt') as html: + with open(os.path.join(out_dir, node.filename), 'wt', + newline='\n', encoding='utf-8') as html: ctx = { 'module': module, 'files': files, 'node': node, + 'src-lang': src_lang, } ctx.update(generate_nav_nodes(files, node)) - if node.name in convert_chunks: - for line in convert_chunks[node.name](ctx): + converter = convert_chunks.get(node.name) + if converter is not None: + for line in converter(ctx): html.write(line) else: - logging.warning('Add converter/template for "%s"', node.name) + logging.warning('Add chunk converter for "%s"', node.name) def create_devhelp2_toc(node): result = [] for c in node.children: if c.children: - result.append('\n' % (c.title, c.filename)) + result.append('\n' % (c.raw_title, c.filename)) result.extend(create_devhelp2_toc(c)) result.append('\n') else: - result.append('\n' % (c.title, c.filename)) + result.append('\n' % (c.raw_title, c.filename)) return result def create_devhelp2_condition_attribs(node): - if 'condition' in node.attrib: + condition = node.attrib.get('condition') + if condition is not None: # condition -> since, deprecated, ... (separated with '|') - cond = node.attrib['condition'].replace('"', '"').split('|') - return' ' + ' '.join(['%s="%s"' % tuple(c.split(':', 1)) for c in cond]) + cond = condition.replace('"', '"').split('|') + keywords = [] + for c in cond: + if ':' in c: + keywords.append('{}="{}"'.format(*c.split(':', 1))) + else: + # deprecated can have no description + keywords.append('{}="{}"'.format(c, '')) + return ' ' + ' '.join(keywords) else: return '' def create_devhelp2_refsect2_keyword(node, base_link): + node_id = node.attrib['id'] return' \n' % ( - node.attrib['role'], xml_get_title(node), base_link + node.attrib['id'], + node.attrib['role'], titles[node_id]['title'], base_link + node_id, create_devhelp2_condition_attribs(node)) @@ -956,7 +1698,8 @@ def create_devhelp2_refsect3_keyword(node, base_link, title, name): def create_devhelp2(out_dir, module, xml, files): - with open(os.path.join(out_dir, module + '.devhelp2'), 'wt') as idx: + with open(os.path.join(out_dir, module + '.devhelp2'), 'wt', + newline='\n', encoding='utf-8') as idx: bookinfo_nodes = xml.xpath('/book/bookinfo') title = '' if bookinfo_nodes is not None: @@ -1020,36 +1763,98 @@ def get_dirs(uninstalled): return (gtkdocdir, styledir) -def main(module, index_file, out_dir, uninstalled): +def main(module, index_file, out_dir, uninstalled, src_lang, paths): + + # == Loading phase == + # the next 3 steps could be done in paralel + + # 1) load the docuemnt + _t = timer() + # does not seem to be faster + # parser = etree.XMLParser(dtd_validation=False, collect_ids=False) + # tree = etree.parse(index_file, parser) tree = etree.parse(index_file) + logging.warning("1a: %7.3lf: load doc", timer() - _t) + _t = timer() tree.xinclude() + logging.warning("1b: %7.3lf: xinclude doc", timer() - _t) + # 2) copy datafiles + _t = timer() + # TODO: handle additional images (gtkdocdir, styledir) = get_dirs(uninstalled) # copy navigation images and stylesheets to html directory ... css_file = os.path.join(styledir, 'style.css') for f in glob(os.path.join(styledir, '*.png')) + [css_file]: shutil.copy(f, out_dir) css_file = os.path.join(out_dir, 'style.css') - with open(css_file, 'at') as css: + with open(css_file, 'at', newline='\n', encoding='utf-8') as css: css.write(HTML_FORMATTER.get_style_defs()) + logging.warning("2: %7.3lf: copy datafiles", timer() - _t) + # 3) load xref targets + _t = timer() # TODO: migrate options from fixxref - # TODO: do in parallel with loading the xml above. + # TODO: ideally explicity specify the files we need, this will save us the + # globbing and we'll load less files. fixxref.LoadIndicies(out_dir, '/usr/share/gtk-doc/html', []) - - # We do multiple passes: - # 1) recursively walk the tree and chunk it into a python tree so that we - # can generate navigation and link tags. - files = chunk(tree.getroot()) - files = list(PreOrderIter(files)) - # 2) find all 'id' attribs and add them to the link map - add_id_links(files, fixxref.Links) - # 3) create a xxx.devhelp2 file, do this before 3), since we modify the tree + logging.warning("3: %7.3lf: load xrefs", timer() - _t) + + # == Processing phase == + + # 4) recursively walk the tree and chunk it into a python tree so that we + # can generate navigation and link tags. + _t = timer() + files = chunk(tree.getroot(), module) + files = [f for f in PreOrderIter(files) if f.anchor is None] + logging.warning("4: %7.3lf: chunk doc", timer() - _t) + + # 5) extract tables: + _t = timer() + # TODO: can be done in parallel + # - find all 'id' attribs and add them to the link map + # - .. get their titles and store them into the titles map + add_id_links_and_titles(files, fixxref.Links) + # - build glossary dict + build_glossary(files) + logging.warning("5: %7.3lf: extract tables", timer() - _t) + + # == Output phase == + # the next two step could be done in parllel + + # 6) create a xxx.devhelp2 file + _t = timer() create_devhelp2(out_dir, module, tree.getroot(), files) - # 4) iterate the tree and output files - # TODO: use multiprocessing + logging.warning("6: %7.3lf: create devhelp2", timer() - _t) + + # 7) iterate the tree and output files + _t = timer() + # TODO: can be done in parallel, figure out why this is not faster + # from multiprocessing.pool import Pool + # with Pool(4) as p: + # p.apply_async(convert, args=(out_dir, module, files)) + # from multiprocessing.pool import ThreadPool + # with ThreadPool(4) as p: + # p.apply_async(convert, args=(out_dir, module, files)) for node in files: - convert(out_dir, module, files, node) + convert(out_dir, module, files, node, src_lang) + logging.warning("7: %7.3lf: create html", timer() - _t) + + # 8) copy assets over + _t = timer() + paths = set(paths + [os.getcwd()]) + for a in assets: + logging.info('trying %s in %s', a, str(paths)) + copied = False + for p in paths: + try: + shutil.copy(os.path.join(p, a), out_dir) + copied = True + except FileNotFoundError: + pass + if not copied: + logging.warning('file %s not found in path (did you add --path?)', a) + logging.warning("8: %7.3lf: copy assets", timer() - _t) def run(options): @@ -1067,4 +1872,5 @@ def run(options): if e.errno != errno.EEXIST: raise - sys.exit(main(module, document, out_dir, options.uninstalled)) + sys.exit(main(module, document, out_dir, options.uninstalled, options.src_lang, + options.path)) diff --git a/gtkdoc/mkpdf.py b/gtkdoc/mkpdf.py index 6a034da..beaaf5c 100755 --- a/gtkdoc/mkpdf.py +++ b/gtkdoc/mkpdf.py @@ -19,9 +19,6 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -# Support both Python 2 and 3 -from __future__ import print_function - import logging import os import sys diff --git a/gtkdoc/rebase.py b/gtkdoc/rebase.py index 75713ce..4b0266c 100755 --- a/gtkdoc/rebase.py +++ b/gtkdoc/rebase.py @@ -24,9 +24,6 @@ The rebase tool rewrites URI references in installed HTML documentation. """ -from __future__ import print_function -from six import iteritems, iterkeys - import logging import os import re @@ -111,7 +108,7 @@ def ScanDirectory(scan_dir, options): if onlinedir and entry == "index.sgml": log(options, "Reading index from index.sgml") - onlinedir = ReadIndex(dir, entry) + onlinedir = ReadIndex(scan_dir, entry) have_index = True elif entry == "index.sgml.gz" and not os.path.exists(os.path.join(scan_dir, 'index.sgml')): # debian/ubuntu started to compress this as index.sgml.gz :/ @@ -136,7 +133,7 @@ gunzip %s/%s def ReadDevhelp(dir, file): onlinedir = None - for line in common.open_text(os.path.join(dir, file)): + for line in open(os.path.join(dir, file), mode='r', encoding='utf-8'): # online must come before chapter/functions if '''', line) if match: # Remove trailing non-directory component. - onlinedir = re.sub(r'''(.*/).*''', r'\1', match.groups(1)) + onlinedir = re.sub(r'''(.*/).*''', r'\1', match.group(1)) return onlinedir @@ -207,10 +204,10 @@ def RebaseFile(filename, options): def repl_func(match): return match.group(1) + RebaseLink(match.group(2), options) + match.group(3) - contents = common.open_text(filename).read() + contents = open(filename, mode='r', encoding='utf-8').read() processed = re.sub(regex, repl_func, contents) newfilename = filename + '.new' - with common.open_text(newfilename, 'w') as h: + with open(newfilename, mode='w', encoding='utf-8') as h: h.write(processed) os.unlink(filename) os.rename(newfilename, filename) @@ -229,10 +226,10 @@ def RebaseLink(href, options): else: match = re.match(r'\.\./([^/]+)', href) if match is not None: - package = match.groups(1) + package = match.group(1) elif options.aggressive: match = re.search(r'''([^/]+)/$''', href) - package = match.groups(1) + package = match.group(1) if package: if options.online and package in OnlineMap: @@ -252,6 +249,6 @@ def RebaseLink(href, options): def PrintWhatWeHaveDone(): - for origdir in sorted(iterkeys(Mapped)): + for origdir in sorted(Mapped.keys()): info = Mapped[origdir] print(origdir, "->", info[0], "(%s)" % info[1]) diff --git a/gtkdoc/scan.py b/gtkdoc/scan.py index cd0725e..f1f1672 100644 --- a/gtkdoc/scan.py +++ b/gtkdoc/scan.py @@ -33,9 +33,6 @@ This second list file is typically copied to '$MODULE-sections.txt' and organized into sections ready to output the XML pages. """ -from __future__ import print_function -from six import iteritems, iterkeys - import logging import os import re @@ -77,16 +74,16 @@ def Run(options): for dir in options.source_dir: ScanHeaders(dir, section_list, decl_list, get_types, options) - with common.open_text(new_decl_list, 'w') as f: - for section in sorted(iterkeys(section_list)): + with open(new_decl_list, 'w', encoding='utf-8') as f: + for section in sorted(section_list.keys()): f.write(section_list[section]) - with common.open_text(new_decl, 'w') as f: + with open(new_decl, 'w', encoding='utf-8') as f: for decl in decl_list: f.write(decl) if options.rebuild_types: - with common.open_text(new_types, 'w') as f: + with open(new_types, 'w', encoding='utf-8') as f: for func in sorted(get_types): f.write(func + '\n') @@ -113,7 +110,7 @@ def Run(options): # because EXTRA_DIST in gtk-doc.make requires it. overrides_file = base_filename + '-overrides.txt' if not os.path.exists(overrides_file): - open(overrides_file, 'w').close() + open(overrides_file, 'w', encoding='utf-8').close() # @@ -226,7 +223,7 @@ def ScanHeader(input_file, section_list, decl_list, get_types, options): logging.info('Scanning %s', input_file) - for line in common.open_text(input_file): + for line in open(input_file, 'r', encoding='utf-8'): # If this is a private header, skip it. if re.search(r'^\s*/\*\s*<\s*private_header\s*>\s*\*/', line): return @@ -773,7 +770,7 @@ def ScanHeader(input_file, section_list, decl_list, get_types, options): previous_line = line # print remaining forward declarations - for symbol in sorted(iterkeys(forward_decls)): + for symbol in sorted(forward_decls.keys()): if forward_decls[symbol]: AddSymbolToList(slist, symbol) decl_list.append(forward_decls[symbol]) diff --git a/gtkdoc/scangobj.py b/gtkdoc/scangobj.py index 4ad2717..237863c 100644 --- a/gtkdoc/scangobj.py +++ b/gtkdoc/scangobj.py @@ -1206,7 +1206,7 @@ def run(options): logging.info('options: %s', str(options.__dict__)) c_file = options.module + '-scan.c' - output = common.open_text(c_file, 'w') + output = open(c_file, 'w', encoding='utf-8') base_filename = os.path.join(options.output_dir, options.module) old_signals_filename = base_filename + '.signals' @@ -1227,7 +1227,7 @@ def run(options): get_types = "" ntypes = 1 - for line in common.open_text(options.types): + for line in open(options.types, 'r', encoding='utf-8'): if line.startswith('#include'): includes += line elif line.startswith('%') or line.strip() == '': diff --git a/help/Makefile.in b/help/Makefile.in index b555769..f1c81ef 100644 --- a/help/Makefile.in +++ b/help/Makefile.in @@ -322,7 +322,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/help/manual/C/index.docbook b/help/manual/C/index.docbook index 0980f3f..961adf1 100644 --- a/help/manual/C/index.docbook +++ b/help/manual/C/index.docbook @@ -81,6 +81,12 @@ + 1.29 + 28 Aug 2018 + ss + development + + 1.28 24 Mar 2018 ss @@ -238,8 +244,7 @@ Writing the documentation. The author fills in the source files with the documentation for each - function, macro, union etc. (In the past information was entered in - generated template files, which is not recommended anymore). + function, macro, structs or unions, etc. @@ -341,11 +346,21 @@ About GTK-Doc + 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. + + + (FIXME) - (History, authors, web pages, mailing list, license, future plans, + (authors, web pages, mailing list, license, future plans, comparison with other similar systems.) @@ -367,37 +382,94 @@ - Setting up your project + Project Setup - 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 plain - makefiles or other build systems will describe the basics needed to - work in a different build setup. + This Chapter describes the steps that are necessary to integrate GTK-Doc + into your project. The integration of GTK-Doc into a project includes the + following steps: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + + + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. Setting up a skeleton documentation - 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 + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. - This can then look as shown below: - Example directory structure + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project - - Integration with autoconf - + + Integration with Autotools - Very easy! Just add one line to your configure.ac script. + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + + + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - Integration with autoconf - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - - 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 - GTK_DOC_CHECK at the start of a line. - Keep gtk-doc optional - + + Integration with automake + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + + +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ + - - - The first argument is used to check for the gtkdocversion at configure time. - The 2nd, optional argument is used by gtkdocize. - The GTK_DOC_CHECK macro also adds several configure switches: - - - --with-html-dir=PATH : path to installed docs - --enable-gtk-doc : use gtk-doc to build documentation [default=no] - --enable-gtk-doc-html : build documentation in html format [default=yes] - --enable-gtk-doc-pdf : build documentation in pdf format [default=no] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. + + All settings have a comment above them that describes their purpose + and how to customize the setting. - - - GTK-Doc is disabled by default! Remember to pass the option - to the next - configure run. Otherwise pregenerated documentation is installed - (which makes sense for users but not for developers). + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). + + All the tools support to list the supported + options. - - - Furthermore it is recommended that you have the following line inside - your configure.ac script. - This allows gtkdocize to automatically copy the - macro definition for GTK_DOC_CHECK to your project. - + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. - - Preparation for gtkdocize - + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + Integration with autoconf + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - - After all changes to configure.ac are made, update - the configure file. This can be done by re-running - autoreconf -i or autogen.sh. - - + + - - Integration with automake + + 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: - - First copy the Makefile.am from the - examples sub directory of the - gtkdoc-sources - to your project's API documentation directory ( - ./docs/reference/<package>). - A local copy should be available under e.g. - /usr/share/doc/gtk-doc-tools/examples/Makefile.am. - If you have multiple doc-packages repeat this for each one. - + + Integration with optional gtk-doc dependency + + + - - The next step is to edit the settings inside the Makefile.am. - 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 . - All the tools support to list the supported - parameters. - + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - + + --with-html-dir=PATH : path to installed docs + --enable-gtk-doc : use gtk-doc to build documentation [default=no] + --enable-gtk-doc-html : build documentation in html format [default=yes] + --enable-gtk-doc-pdf : build documentation in pdf format [default=no] + - + + + GTK-Doc is disabled by default! Remember to pass the option + to the next + configure run. Otherwise pregenerated documentation is installed + (which makes sense for users but not for developers). + + - - Integration with autogen + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - - Most projects will have an autogen.sh 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 - gtkdocize which can be used in such a script. - It should be run before autoheader, automake or autoconf. - + + Integration with autogen - - Running gtkdocize from autogen.sh - + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + + + + It should be run before autoreconf, autoheader, automake or autoconf. + + + + Running gtkdocize from autogen.sh + - - + + - - When running gtkdocize it copies - gtk-doc.make to your project root (or any directory - specified by the option). - It also checks you configure script for the GTK_DOC_CHECK - invocation. This macro can be used to pass extra parameters to - gtkdocize. - + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - - 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. gtkdocize supports now - a 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 GTKDOCIZE_FLAGS - or set as a 2nd parameter in GTK_DOC_CHECK 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). - - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - Running the doc build + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - - After the previous steps it's time to run the build. First we need to - rerun autogen.sh. If this script runs configure for - you, then give it the option. - Otherwise manually run configure with this option - afterwards. - - - The first make run generates several additional files in the doc-directories. - The important ones are: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt. - - - Running the doc build - + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + + After the previous steps it's time to run the build. First we need to + rerun autogen.sh. If this script runs configure + for you, then give it the option. + Otherwise manually run configure with this option + afterwards. + + + The first make run generates several additional files in the doc-directories. + The important ones are: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt. + + + Running the doc build + - - - - Now you can point your browser to docs/reference/<package>/index.html. - Yes, it's a bit disappointing still. But hang-on, during the next chapter we - tell you how to fill the pages with life. - + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - Integration with version control systems + + Integration with CMake build systems - As a rule of thumb, it's the files you edit which should go under - version control. For typical projects it's these files: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt, - Makefile.am. + GTK-Doc now provides a GtkDocConfig.cmake module + (and the corresponding GtkDocConfigVersion.cmake + module). This provides a gtk_doc_add_module + command that you can set in your CMakeLists.txt + file. + - Files in the xml/ and html/ - directories should not go under version control. Neither should any of - the .stamp files. + The following example shows how to use this command. + Example of using GTK-Doc from CMake + + - + Integration with plain makefiles or other build systems @@ -633,42 +961,24 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html - - Integration with CMake build systems - - - GTK-Doc now provides a GtkDocConfig.cmake module - (and the corresponding GtkDocConfigVersion.cmake - module). This provides a gtk_doc_add_module - command that you can set in your CMakeLists.txt - file. - - - - The following example shows how to use this command. - Example of using GTK-Doc from CMake - + Integration with version control systems -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + + As a rule of thumb, it's the files you edit which should go under + version control. For typical projects it's these files: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt, + Makefile.am. + + + Files in the xml/ and html/ + directories should not go under version control. Neither should any of + the .stamp files. + + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - - @@ -681,25 +991,10 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html syntax of the comments. - - Documentation placement - - In the past most documentation had to be filled into files residing - inside the tmpl 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. - - - The avoid the aforementioned problems we suggest putting the - documentation inside the sources. This manual will only describe this - way of documenting code. - - - - The scanner can handle the majority of C headers fine. In the case of - receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + The GTK-Doc scanner can handle the majority of C headers fine. In the + case of receiving warnings from the scanner that look like a special + case, one can hint GTK-Doc to skip over them. GTK-Doc comment block As already mentioned earlier GTK-Doc is for documenting public API. Thus one cannot write documentation for static symbols. Nevertheless it is good - to comment those symbols too. This helps other to understand you code. + to comment those symbols too. This helps other developers to understand + your code. Therefore we recommend to comment these using normal comments (without the 2nd '*' in the first line). If later the function needs to be made public, all one needs to do is to @@ -1689,7 +1985,7 @@ int main(int argc, char *argv[]) - Example types file snippet + Example <package>.types file @@ -2046,7 +2342,8 @@ endif containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included - and how the entities are used. The entities can also be used in all + in the master template and how the entities are used. + The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities diff --git a/help/manual/Makefile.in b/help/manual/Makefile.in index 92933a2..3800516 100644 --- a/help/manual/Makefile.in +++ b/help/manual/Makefile.in @@ -262,7 +262,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/help/manual/bn_IN/index.docbook b/help/manual/bn_IN/index.docbook index af19a6e..33e1427 100644 --- a/help/manual/bn_IN/index.docbook +++ b/help/manual/bn_IN/index.docbook @@ -81,6 +81,12 @@ + 1.29 + 28 Aug 2018 + ss + development + + 1.28 24 Mar 2018 ss @@ -229,8 +235,7 @@ Writing the documentation. The author fills in the source files with the documentation for each - function, macro, union etc. (In the past information was entered in - generated template files, which is not recommended anymore). + function, macro, structs or unions, etc. @@ -331,10 +336,20 @@ GTK-Doc পরিচিতি + + 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. + + (FIXME) - (History, authors, web pages, mailing list, license, future plans, + (authors, web pages, mailing list, license, future plans, comparison with other similar systems.) @@ -352,37 +367,94 @@ - প্রজেক্ট প্রস্তুত করার প্রণালী + Project Setup + + + This Chapter describes the steps that are necessary to integrate GTK-Doc + into your project. The integration of GTK-Doc into a project includes the + following steps: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + - 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 plain - makefiles or other build systems will describe the basics needed to - work in a different build setup. + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. নথির একটি পরিকাঠামো নির্ধারণের প্রণালী - 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 + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. - This can then look as shown below: - Example directory structure + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project - - autoconf সহযোগে একত্রিত করার প্রণালী + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + - এই কাজ অতিমাত্রায় সহজ! configure.ac স্ক্রিপ্টের মধ্যে একটি পংক্তি যোগ করুন। + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - autoconf সহযোগে একত্রিত করার প্রণালী - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - - 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 - GTK_DOC_CHECK at the start of a line. - Keep gtk-doc optional - + + automake সহযোগে একত্রিত করার প্রণালী + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + + +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ + - - - The first argument is used to check for the gtkdocversion at configure time. - The 2nd, optional argument is used by gtkdocize. - The GTK_DOC_CHECK macro also adds several configure switches: - - - --with-html-dir=PATH : ইনস্টল করা ডকুমেন্টের পাথ - --enable-gtk-doc : use gtk-doc to build documentation [default=no] - --enable-gtk-doc-html : build documentation in html format [default=yes] - --enable-gtk-doc-pdf : build documentation in pdf format [default=no] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. + + All settings have a comment above them that describes their purpose + and how to customize the setting. - - - GTK-Doc is disabled by default! Remember to pass the option - to the next - configure run. Otherwise pregenerated documentation is installed - (which makes sense for users but not for developers). + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). + + All the tools support to list the supported + options. - - - Furthermore it is recommended that you have the following line inside - your configure.ac script. - This allows gtkdocize to automatically copy the - macro definition for GTK_DOC_CHECK to your project. - + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. - - gtkdocize-র প্রস্তুতি - + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + autoconf সহযোগে একত্রিত করার প্রণালী + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - - After all changes to configure.ac are made, update - the configure file. This can be done by re-running - autoreconf -i or autogen.sh. - - + + - - automake সহযোগে একত্রিত করার প্রণালী + + 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: - - First copy the Makefile.am from the - examples sub directory of the - gtkdoc-sources - to your project's API documentation directory ( - ./docs/reference/<package>). - A local copy should be available under e.g. - /usr/share/doc/gtk-doc-tools/examples/Makefile.am. - If you have multiple doc-packages repeat this for each one. - + + Integration with optional gtk-doc dependency + + + - - The next step is to edit the settings inside the Makefile.am. - 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 . - All the tools support to list the supported - parameters. - + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - + + --with-html-dir=PATH : ইনস্টল করা ডকুমেন্টের পাথ + --enable-gtk-doc : use gtk-doc to build documentation [default=no] + --enable-gtk-doc-html : build documentation in html format [default=yes] + --enable-gtk-doc-pdf : build documentation in pdf format [default=no] + - + + + GTK-Doc is disabled by default! Remember to pass the option + to the next + configure run. Otherwise pregenerated documentation is installed + (which makes sense for users but not for developers). + + - - autogen সহযোগে একত্রিত করার প্রণালী + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - - Most projects will have an autogen.sh 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 - gtkdocize which can be used in such a script. - It should be run before autoheader, automake or autoconf. - + + autogen সহযোগে একত্রিত করার প্রণালী - - autogen.sh থেকে gtkdocsize সঞ্চালনার প্রণালী - + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + + + + It should be run before autoreconf, autoheader, automake or autoconf. + + + + autogen.sh থেকে gtkdocsize সঞ্চালনার প্রণালী + - - + + - - When running gtkdocize it copies - gtk-doc.make to your project root (or any directory - specified by the option). - It also checks you configure script for the GTK_DOC_CHECK - invocation. This macro can be used to pass extra parameters to - gtkdocize. - + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - - 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. gtkdocize supports now - a 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 GTKDOCIZE_FLAGS - or set as a 2nd parameter in GTK_DOC_CHECK 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). - - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - doc build সঞ্চালনার প্রণালী + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - - After the previous steps it's time to run the build. First we need to - rerun autogen.sh. If this script runs configure for - you, then give it the option. - Otherwise manually run configure with this option - afterwards. - - - The first make run generates several additional files in the doc-directories. - The important ones are: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt. - - - doc build সঞ্চালনার প্রণালী - + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + + After the previous steps it's time to run the build. First we need to + rerun autogen.sh. If this script runs configure + for you, then give it the option. + Otherwise manually run configure with this option + afterwards. + + + The first make run generates several additional files in the doc-directories. + The important ones are: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt. + + + doc build সঞ্চালনার প্রণালী + - - - - Now you can point your browser to docs/reference/<package>/index.html. - Yes, it's a bit disappointing still. But hang-on, during the next chapter we - tell you how to fill the pages with life. - + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - ভার্সান কনট্রোল সিস্টেমের সাথে একত্রিত করার প্রণালী + + Integration with CMake build systems - As a rule of thumb, it's the files you edit which should go under - version control. For typical projects it's these files: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt, - Makefile.am. + GTK-Doc now provides a GtkDocConfig.cmake module + (and the corresponding GtkDocConfigVersion.cmake + module). This provides a gtk_doc_add_module + command that you can set in your CMakeLists.txt + file. + - Files in the xml/ and html/ - directories should not go under version control. Neither should any of - the .stamp files. + The following example shows how to use this command. + Example of using GTK-Doc from CMake + + - + Integration with plain makefiles or other build systems @@ -616,42 +946,24 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html - - Integration with CMake build systems - - - GTK-Doc now provides a GtkDocConfig.cmake module - (and the corresponding GtkDocConfigVersion.cmake - module). This provides a gtk_doc_add_module - command that you can set in your CMakeLists.txt - file. - - - - The following example shows how to use this command. - Example of using GTK-Doc from CMake - + ভার্সান কনট্রোল সিস্টেমের সাথে একত্রিত করার প্রণালী -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + + As a rule of thumb, it's the files you edit which should go under + version control. For typical projects it's these files: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt, + Makefile.am. + + + Files in the xml/ and html/ + directories should not go under version control. Neither should any of + the .stamp files. + + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - - @@ -664,25 +976,10 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html syntax of the comments. - - নথিপত্রের স্থাপনা - - In the past most documentation had to be filled into files residing - inside the tmpl 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. - - - The avoid the aforementioned problems we suggest putting the - documentation inside the sources. This manual will only describe this - way of documenting code. - - - - The scanner can handle the majority of C headers fine. In the case of - receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + The GTK-Doc scanner can handle the majority of C headers fine. In the + case of receiving warnings from the scanner that look like a special + case, one can hint GTK-Doc to skip over them. GTK-Doc comment block As already mentioned earlier GTK-Doc is for documenting public API. Thus one cannot write documentation for static symbols. Nevertheless it is good - to comment those symbols too. This helps other to understand you code. + to comment those symbols too. This helps other developers to understand + your code. Therefore we recommend to comment these using normal comments (without the 2nd '*' in the first line). If later the function needs to be made public, all one needs to do is to @@ -1653,7 +1951,7 @@ int main(int argc, char *argv[]) - Example types file snippet + Example <package>.types file @@ -2010,7 +2308,8 @@ endif containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included - and how the entities are used. The entities can also be used in all + in the master template and how the entities are used. + The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities diff --git a/help/manual/cs/cs.po b/help/manual/cs/cs.po index 94983c6..5fa540c 100644 --- a/help/manual/cs/cs.po +++ b/help/manual/cs/cs.po @@ -6,8 +6,8 @@ msgid "" msgstr "" "Project-Id-Version: gtk-doc master\n" -"POT-Creation-Date: 2017-12-28 10:31+0000\n" -"PO-Revision-Date: 2018-03-03 07:23+0100\n" +"POT-Creation-Date: 2018-03-24 15:17+0000\n" +"PO-Revision-Date: 2018-04-03 13:41+0200\n" "Last-Translator: Marek Černocký \n" "Language-Team: čeština \n" "Language: cs\n" @@ -122,15 +122,24 @@ msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:83 msgid "" -"1.27.1 07 Dec 2017 ss1.28.1 24 Mar 2018 ss development" msgstr "" -"1.27.1 7. prosince 2017 " +"1.28.1 24. března 2018 " "ss vývoj" #. (itstool) path: revhistory/revision #: C/index.docbook:89 msgid "" +"1.28 24 Mar 2018 ss bug fixes" +msgstr "" +"1.28 24. března 2018 ss opravy chyb" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:95 +msgid "" "1.27 07 Dec 2017 ss fine tuning of the python port" msgstr "" @@ -139,7 +148,7 @@ msgstr "" "jazyce Python" #. (itstool) path: revhistory/revision -#: C/index.docbook:95 +#: C/index.docbook:101 msgid "" "1.26 11 Aug 2017 ss port all tools from perl/bash to python" #. (itstool) path: revhistory/revision -#: C/index.docbook:101 +#: C/index.docbook:107 msgid "" "1.25 21 March 2016 ss bug fixes, test cleanups" @@ -159,7 +168,7 @@ msgstr "" "authorinitials> opravy chyb, pročištění testů" #. (itstool) path: revhistory/revision -#: C/index.docbook:107 +#: C/index.docbook:113 msgid "" "1.24 29 May 2015 ss bug fix" @@ -168,7 +177,7 @@ msgstr "" "authorinitials> oprava chyby" #. (itstool) path: revhistory/revision -#: C/index.docbook:113 +#: C/index.docbook:119 msgid "" "1.23 17 May 2015 ss bug fix" @@ -177,29 +186,29 @@ msgstr "" "authorinitials> oprava chyby" #. (itstool) path: revhistory/revision -#: C/index.docbook:119 +#: C/index.docbook:125 msgid "" "1.22 07 May 2015 ss bug fixes, dropping deprecated features" msgstr "" "1.22 07. květen 2015 ss oprava chyb, odstranění zastaralých věcí opravy chyb, odstranění zastaralých věcí" #. (itstool) path: revhistory/revision -#: C/index.docbook:125 +#: C/index.docbook:131 msgid "" "1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" msgstr "" "1.21 17. červenec 2014 " -"ss oprava chyb, odstranění " +"ss opravy chyb, odstranění " "zastaralých věcí" #. (itstool) path: revhistory/revision -#: C/index.docbook:131 +#: C/index.docbook:137 msgid "" "1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" #. (itstool) path: revhistory/revision -#: C/index.docbook:137 +#: C/index.docbook:143 msgid "" "1.19 05 Jun 2013 ss bug fixes" @@ -219,7 +228,7 @@ msgstr "" "authorinitials> opravy chyb" #. (itstool) path: revhistory/revision -#: C/index.docbook:143 +#: C/index.docbook:149 msgid "" "1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" @@ -229,7 +238,7 @@ msgstr "" "jazyka" #. (itstool) path: revhistory/revision -#: C/index.docbook:149 +#: C/index.docbook:155 msgid "" "1.17 26 Feb 2011 sk urgent bug fix update" @@ -239,7 +248,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:155 +#: C/index.docbook:161 msgid "" "1.16 14 Jan 2011 sk bugfixes, layout improvements" @@ -248,7 +257,7 @@ msgstr "" "authorinitials> opravy chyb, vylepšení vzhledu" #. (itstool) path: revhistory/revision -#: C/index.docbook:161 +#: C/index.docbook:167 msgid "" "1.15 21 May 2010 sk bug and regression fixes" @@ -257,7 +266,7 @@ msgstr "" "authorinitials> opravy chyb a regresí" #. (itstool) path: revhistory/revision -#: C/index.docbook:167 +#: C/index.docbook:173 msgid "" "1.14 28 March 2010 sk bugfixes and performance improvements" @@ -266,7 +275,7 @@ msgstr "" "authorinitials> opravy chyb a vylepšení výkonu" #. (itstool) path: revhistory/revision -#: C/index.docbook:173 +#: C/index.docbook:179 msgid "" "1.13 18 December 2009 " "sk broken tarball update" #. (itstool) path: revhistory/revision -#: C/index.docbook:179 +#: C/index.docbook:185 msgid "" "1.12 18 December 2009 " "sk new tool features and " @@ -288,7 +297,7 @@ msgstr "" "chyb" #. (itstool) path: revhistory/revision -#: C/index.docbook:185 +#: C/index.docbook:191 msgid "" "1.11 16 November 2008 " "mal GNOME doc-utils migration" #. (itstool) path: chapter/title -#: C/index.docbook:198 +#: C/index.docbook:204 msgid "Introduction" msgstr "Úvod" #. (itstool) path: chapter/para -#: C/index.docbook:200 +#: C/index.docbook:206 msgid "" "This chapter introduces GTK-Doc and gives an overview of what it is and how " "it is used." @@ -313,12 +322,12 @@ msgstr "" "použít." #. (itstool) path: sect1/title -#: C/index.docbook:206 +#: C/index.docbook:212 msgid "What is GTK-Doc?" msgstr "Co je to GTK-Doc?" #. (itstool) path: sect1/para -#: C/index.docbook:208 +#: C/index.docbook:214 msgid "" "GTK-Doc is used to document C code. It is typically used to document the " "public API of libraries, such as the GTK+ and GNOME libraries. But it can " @@ -329,12 +338,12 @@ msgstr "" "ale použít i k dokumentaci aplikačního kódu." #. (itstool) path: sect1/title -#: C/index.docbook:216 +#: C/index.docbook:222 msgid "How Does GTK-Doc Work?" msgstr "Jak GTK-Doc pracuje?" #. (itstool) path: sect1/para -#: C/index.docbook:218 +#: C/index.docbook:224 msgid "" "GTK-Doc works by using documentation of functions placed inside the source " "files in specially-formatted comment blocks, or documentation added to the " @@ -350,7 +359,7 @@ msgstr "" "nevytváří)." #. (itstool) path: sect1/para -#: C/index.docbook:225 +#: C/index.docbook:231 msgid "" "GTK-Doc consists of a number of python scripts, each performing a different " "step in the process." @@ -359,12 +368,12 @@ msgstr "" "část procesu." #. (itstool) path: sect1/para -#: C/index.docbook:230 +#: C/index.docbook:236 msgid "There are 5 main steps in the process:" msgstr "Celý proces se skládá z pěti hlavních kroků:" #. (itstool) path: listitem/para -#: C/index.docbook:237 +#: C/index.docbook:243 msgid "" "Writing the documentation. The author fills in the " "source files with the documentation for each function, macro, union etc. (In " @@ -377,7 +386,7 @@ msgstr "" "nedoporučuje)." #. (itstool) path: listitem/para -#: C/index.docbook:247 +#: C/index.docbook:253 msgid "" "Gathering information about the code. " "gtkdoc-scan scans the header files of the code " @@ -411,7 +420,7 @@ msgstr "" "filename> do <module>-overrides.txt." #. (itstool) path: listitem/para -#: C/index.docbook:264 +#: C/index.docbook:270 msgid "" "gtkdoc-scangobj can also be used to dynamically " "query a library about any GObject subclasses it exports. It saves " @@ -424,7 +433,7 @@ msgstr "" "signálech objektu GObject, které poskytují." #. (itstool) path: listitem/para -#: C/index.docbook:270 +#: C/index.docbook:276 msgid "" "gtkdoc-scanobj should not be used anymore. It was " "needed in the past when GObject was still GtkObject inside gtk+." @@ -433,7 +442,7 @@ msgstr "" "Bylo zapotřebí v minulosti, kdy byl GObject ještě GtkObject v rámci gtk+." #. (itstool) path: listitem/para -#: C/index.docbook:277 +#: C/index.docbook:283 msgid "" "Generating the XML and HTML/PDF. gtkdoc-" "mkdb turns the template files into XML files in the gtkdoc-mkhtml turns the XML files into HTML files " "in the html/ subdirectory. Likewise " @@ -463,7 +472,7 @@ msgstr "" "nazvaný <balíček>.pdf." #. (itstool) path: listitem/para -#: C/index.docbook:292 +#: C/index.docbook:298 msgid "" "Files in xml/ and html/ directories are always overwritten. One " @@ -474,7 +483,7 @@ msgstr "" "neměly být upravovány přímo." #. (itstool) path: listitem/para -#: C/index.docbook:300 +#: C/index.docbook:306 msgid "" "Fixing up cross-references between documents. After " "installing the HTML files, gtkdoc-fixxref can be " @@ -496,23 +505,23 @@ msgstr "" "dokumenty, které jsou nainstalované)." #. (itstool) path: sect1/title -#: C/index.docbook:318 +#: C/index.docbook:324 msgid "Getting GTK-Doc" msgstr "Jak získat GTK-Doc?" #. (itstool) path: sect2/title -#: C/index.docbook:321 +#: C/index.docbook:327 msgid "Requirements" msgstr "Požadavky" #. (itstool) path: sect2/para -#: C/index.docbook:322 +#: C/index.docbook:328 msgid "" "python 2/3 - the main scripts are written in python." msgstr "Python 2/3 – hlavní skripty jsou v jazyce Python." #. (itstool) path: sect2/para -#: C/index.docbook:325 +#: C/index.docbook:331 msgid "" "xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" @@ -521,7 +530,7 @@ msgstr "" "\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/" #. (itstool) path: sect2/para -#: C/index.docbook:329 +#: C/index.docbook:335 msgid "" "docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" #. (itstool) path: sect2/para -#: C/index.docbook:333 +#: C/index.docbook:339 msgid "" "One of source-highlight, highlight " "or vim - optional - used for syntax highlighting of " @@ -543,17 +552,17 @@ msgstr "" "syntaxe u příkladů" #. (itstool) path: sect1/title -#: C/index.docbook:341 +#: C/index.docbook:347 msgid "About GTK-Doc" msgstr "O aplikaci GTK-Doc" #. (itstool) path: sect1/para -#: C/index.docbook:343 C/index.docbook:357 +#: C/index.docbook:349 C/index.docbook:363 msgid "(FIXME)" msgstr "(DOPLNIT)" #. (itstool) path: sect1/para -#: C/index.docbook:347 +#: C/index.docbook:353 msgid "" "(History, authors, web pages, mailing list, license, future plans, " "comparison with other similar systems.)" @@ -562,22 +571,22 @@ msgstr "" "budoucna, srovnání s ostatními podobnými systémy.)" #. (itstool) path: sect1/title -#: C/index.docbook:355 +#: C/index.docbook:361 msgid "About this Manual" msgstr "O této příručce" #. (itstool) path: sect1/para -#: C/index.docbook:361 +#: C/index.docbook:367 msgid "(who it is meant for, where you can get it, license)" msgstr "(k čemu je určená, kde ji můžete získat, licence)" #. (itstool) path: chapter/title -#: C/index.docbook:370 +#: C/index.docbook:376 msgid "Setting up your project" msgstr "Nastavení vašeho projektu" #. (itstool) path: chapter/para -#: C/index.docbook:372 +#: C/index.docbook:378 msgid "" "The next sections describe what steps to perform to integrate GTK-Doc into " "your project. Theses sections assume we work on a project called 'meep'. " @@ -596,12 +605,12 @@ msgstr "" "popsány základní požadavky pro fungování s jinými postupy sestavování." #. (itstool) path: sect1/title -#: C/index.docbook:383 +#: C/index.docbook:389 msgid "Setting up a skeleton documentation" msgstr "Nastavení kostry dokumentace" #. (itstool) path: sect1/para -#: C/index.docbook:385 +#: C/index.docbook:391 msgid "" "Under your top-level project directory create folders called docs/reference " "(this way you can also have docs/help for end-user documentation). It is " @@ -614,12 +623,12 @@ msgstr "" "jedinou knihovnou není tento krok nutný." #. (itstool) path: example/title -#: C/index.docbook:394 +#: C/index.docbook:400 msgid "Example directory structure" msgstr "Příklad struktury složek" #. (itstool) path: example/programlisting -#: C/index.docbook:395 +#: C/index.docbook:401 #, no-wrap msgid "" "\n" @@ -643,18 +652,18 @@ msgstr "" " meeper/\n" #. (itstool) path: sect1/para -#: C/index.docbook:392 +#: C/index.docbook:398 msgid "This can then look as shown below: <_:example-1/>" msgstr "Ve výsledku to může vypadat nějak takto: <_:example-1/>" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:410 C/index.docbook:417 +#: C/index.docbook:416 C/index.docbook:423 msgid "Integration with autoconf" msgstr "Integrace s autoconf" #. (itstool) path: sect1/para -#: C/index.docbook:412 +#: C/index.docbook:418 msgid "" "Very easy! Just add one line to your configure.ac " "script." @@ -663,7 +672,7 @@ msgstr "" "configure.ac." #. (itstool) path: example/programlisting -#: C/index.docbook:418 +#: C/index.docbook:424 #, no-wrap msgid "" "\n" @@ -675,12 +684,12 @@ msgstr "" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" #. (itstool) path: example/title -#: C/index.docbook:430 +#: C/index.docbook:436 msgid "Keep gtk-doc optional" msgstr "Ponechání gtk-doc jako volitelného" #. (itstool) path: example/programlisting -#: C/index.docbook:431 +#: C/index.docbook:437 #, no-wrap msgid "" "\n" @@ -700,7 +709,7 @@ msgstr "" "])\n" #. (itstool) path: sect1/para -#: C/index.docbook:425 +#: C/index.docbook:431 msgid "" "This will require all developers to have gtk-doc installed. If it is okay " "for your project to have optional api-doc build setup, you can solve this as " @@ -714,7 +723,7 @@ msgstr "" "example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:442 +#: C/index.docbook:448 msgid "" "The first argument is used to check for the gtkdocversion at configure time. " "The 2nd, optional argument is used by gtkdocize. " @@ -727,31 +736,31 @@ msgstr "" "přepínačů pro configure:" #. (itstool) path: listitem/para -#: C/index.docbook:448 +#: C/index.docbook:454 msgid "--with-html-dir=PATH : path to installed docs" msgstr "--with-html-dir=CESTA: cesta, kam se má dokumentace nainstalovat" #. (itstool) path: listitem/para -#: C/index.docbook:449 +#: C/index.docbook:455 msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "" "--enable-gtk-doc: použít k sestavení dokumentace gtk-doc [výchozí je ne]" #. (itstool) path: listitem/para -#: C/index.docbook:450 +#: C/index.docbook:456 msgid "" "--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" "--enable-gtk-doc-html: sestavit dokumentaci ve formátu HTML [výchozí je ano]" #. (itstool) path: listitem/para -#: C/index.docbook:451 +#: C/index.docbook:457 msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" msgstr "" "--enable-gtk-doc-pdf: sestavit dokumentaci ve formátu PDF [výchozí je ne]" #. (itstool) path: important/para -#: C/index.docbook:455 +#: C/index.docbook:461 msgid "" "GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " @@ -764,7 +773,7 @@ msgstr "" "uživatele, ale ne pro vývojáře)." #. (itstool) path: sect1/para -#: C/index.docbook:463 +#: C/index.docbook:469 msgid "" "Furthermore it is recommended that you have the following line inside your " "configure.ac script. This allows " @@ -777,12 +786,12 @@ msgstr "" "function> do vašeho projektu." #. (itstool) path: example/title -#: C/index.docbook:471 +#: C/index.docbook:477 msgid "Preparation for gtkdocize" msgstr "Příprava pro gtkdocize" #. (itstool) path: example/programlisting -#: C/index.docbook:472 +#: C/index.docbook:478 #, no-wrap msgid "" "\n" @@ -792,7 +801,7 @@ msgstr "" "AC_CONFIG_MACRO_DIR(m4)\n" #. (itstool) path: sect1/para -#: C/index.docbook:477 +#: C/index.docbook:483 msgid "" "After all changes to configure.ac are made, update the " "configure file. This can be done by re-running " @@ -803,12 +812,12 @@ msgstr "" "autoreconf -i nebo autogen.sh." #. (itstool) path: sect1/title -#: C/index.docbook:485 +#: C/index.docbook:491 msgid "Integration with automake" msgstr "Integrace s automake" #. (itstool) path: sect1/para -#: C/index.docbook:487 +#: C/index.docbook:493 msgid "" "First copy the Makefile.am from the examples sub directory of the Makefile.am. All the settings have a comment above that describes their " @@ -846,12 +855,12 @@ msgstr "" "přepínačů." #. (itstool) path: sect1/title -#: C/index.docbook:512 +#: C/index.docbook:518 msgid "Integration with autogen" msgstr "Integrace s autogen" #. (itstool) path: sect1/para -#: C/index.docbook:514 +#: C/index.docbook:520 msgid "" "Most projects will have an autogen.sh script to setup " "the build infrastructure after a checkout from version control system (such " @@ -866,12 +875,12 @@ msgstr "" "Měl by být spuštěný před autoheader, automake nebo autoconf." #. (itstool) path: example/title -#: C/index.docbook:523 +#: C/index.docbook:529 msgid "Running gtkdocize from autogen.sh" msgstr "Spuštění gtkdocize z autogen.sh" #. (itstool) path: example/programlisting -#: C/index.docbook:524 +#: C/index.docbook:530 #, no-wrap msgid "" "\n" @@ -881,7 +890,7 @@ msgstr "" "gtkdocize || exit 1\n" #. (itstool) path: sect1/para -#: C/index.docbook:530 +#: C/index.docbook:536 msgid "" "When running gtkdocize it copies gtk-" "doc.make to your project root (or any directory specified by the " @@ -897,7 +906,7 @@ msgstr "" "application>." #. (itstool) path: sect1/para -#: C/index.docbook:539 +#: C/index.docbook:545 msgid "" "Historically GTK-Doc was generating template files where developers entered " "the docs. This turned out to be not so good (e.g. the need for having " @@ -929,12 +938,12 @@ msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:556 C/index.docbook:573 +#: C/index.docbook:562 C/index.docbook:579 msgid "Running the doc build" msgstr "Sestavení dokumentace" #. (itstool) path: sect1/para -#: C/index.docbook:558 +#: C/index.docbook:564 msgid "" "After the previous steps it's time to run the build. First we need to rerun " "autogen.sh. If this script runs configure for you, then " @@ -947,7 +956,7 @@ msgstr "" "Jinak potom ručně spusťte configure s tímto přepínačem." #. (itstool) path: sect1/para -#: C/index.docbook:565 +#: C/index.docbook:571 msgid "" "The first make run generates several additional files in the doc-" "directories. The important ones are: <package>.types." #. (itstool) path: example/programlisting -#: C/index.docbook:574 +#: C/index.docbook:580 #, no-wrap msgid "" "\n" @@ -972,7 +981,7 @@ msgstr "" "make\n" #. (itstool) path: sect1/para -#: C/index.docbook:580 +#: C/index.docbook:586 msgid "" "Now you can point your browser to docs/reference/<package>/" "index.html. Yes, it's a bit disappointing still. But hang-on, " @@ -983,12 +992,12 @@ msgstr "" "nebojte, v následující kapitole vám řekneme, jak stránky uvést do života." #. (itstool) path: sect1/title -#: C/index.docbook:588 +#: C/index.docbook:594 msgid "Integration with version control systems" msgstr "Integrace se systémem pro správu verzí" #. (itstool) path: sect1/para -#: C/index.docbook:590 +#: C/index.docbook:596 msgid "" "As a rule of thumb, it's the files you edit which should go under version " "control. For typical projects it's these files: <package>." @@ -1003,7 +1012,7 @@ msgstr "" "Makefile.am." #. (itstool) path: sect1/para -#: C/index.docbook:598 +#: C/index.docbook:604 msgid "" "Files in the xml/ and html/ " "directories should not go under version control. Neither should any of the " @@ -1014,13 +1023,13 @@ msgstr "" "filename>." #. (itstool) path: sect1/title -#: C/index.docbook:606 +#: C/index.docbook:612 msgid "Integration with plain makefiles or other build systems" msgstr "" "Integrace s prostými soubory Makefile nebo jinými sestavovacími systémy" #. (itstool) path: sect1/para -#: C/index.docbook:608 +#: C/index.docbook:614 msgid "" "In the case one does not want to use automake and therefore gtk-" "doc.mak one will need to call the gtkdoc tools in the right order " @@ -1031,12 +1040,12 @@ msgstr "" "souborech make (nebo jiných nástrojích)." #. (itstool) path: example/title -#: C/index.docbook:615 +#: C/index.docbook:621 msgid "Documentation build steps" msgstr "Kroky sestavení dokumentace" #. (itstool) path: example/programlisting -#: C/index.docbook:616 +#: C/index.docbook:622 #, no-wrap msgid "" "\n" @@ -1062,7 +1071,7 @@ msgstr "" "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" #. (itstool) path: sect1/para -#: C/index.docbook:630 +#: C/index.docbook:636 msgid "" "One will need to look at the Makefile.am and " "gtk-doc.mak to pick the extra options needed." @@ -1071,12 +1080,12 @@ msgstr "" "am a gtk-doc.mak." #. (itstool) path: sect1/title -#: C/index.docbook:637 +#: C/index.docbook:643 msgid "Integration with CMake build systems" msgstr "Integrace se sestavovacím systémem CMake" #. (itstool) path: sect1/para -#: C/index.docbook:639 +#: C/index.docbook:645 msgid "" "GTK-Doc now provides a GtkDocConfig.cmake module (and " "the corresponding GtkDocConfigVersion.cmake module). " @@ -1089,12 +1098,12 @@ msgstr "" "nastavit ve svém souboru CMakeLists.txt." #. (itstool) path: example/title -#: C/index.docbook:649 +#: C/index.docbook:655 msgid "Example of using GTK-Doc from CMake" msgstr "Příklad použití GTK-Doc z CMake" #. (itstool) path: example/programlisting -#: C/index.docbook:650 +#: C/index.docbook:656 #, no-wrap msgid "" "\n" @@ -1136,17 +1145,17 @@ msgstr "" " DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" #. (itstool) path: sect1/para -#: C/index.docbook:647 +#: C/index.docbook:653 msgid "The following example shows how to use this command. <_:example-1/>" msgstr "Následující příklad ukazuje, jak tento příkaz použít: <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:675 +#: C/index.docbook:681 msgid "Documenting the code" msgstr "Dokumentování v kódu" #. (itstool) path: chapter/para -#: C/index.docbook:677 +#: C/index.docbook:683 msgid "" "GTK-Doc uses source code comment with a special syntax for code " "documentation. Further it retrieves information about your project structure " @@ -1159,12 +1168,12 @@ msgstr "" "syntaxi komentářů." #. (itstool) path: note/title -#: C/index.docbook:685 +#: C/index.docbook:691 msgid "Documentation placement" msgstr "Umístění dokumentace" #. (itstool) path: note/para -#: C/index.docbook:686 +#: C/index.docbook:692 msgid "" "In the past most documentation had to be filled into files residing inside " "the tmpl directory. This has the disadvantages that the " @@ -1177,7 +1186,7 @@ msgstr "" "systémech pro správu verzí." #. (itstool) path: note/para -#: C/index.docbook:692 +#: C/index.docbook:698 msgid "" "The avoid the aforementioned problems we suggest putting the documentation " "inside the sources. This manual will only describe this way of documenting " @@ -1188,12 +1197,12 @@ msgstr "" "tento způsob dokumentování kódu." #. (itstool) path: example/title -#: C/index.docbook:703 C/index.docbook:729 +#: C/index.docbook:709 C/index.docbook:735 msgid "GTK-Doc comment block" msgstr "Komentářový blok GTK-Doc" #. (itstool) path: example/programlisting -#: C/index.docbook:704 +#: C/index.docbook:710 #, no-wrap msgid "" "\n" @@ -1207,7 +1216,7 @@ msgstr "" "#endif\n" #. (itstool) path: chapter/para -#: C/index.docbook:699 +#: C/index.docbook:705 msgid "" "The scanner can handle the majority of C headers fine. In the case of " "receiving warnings from the scanner that look like a special case, one can " @@ -1218,12 +1227,12 @@ msgstr "" "poradit, aby jej přeskakovala. <_:example-1/>" #. (itstool) path: note/title -#: C/index.docbook:713 +#: C/index.docbook:719 msgid "Limitations" msgstr "Omezení" #. (itstool) path: note/para -#: C/index.docbook:714 +#: C/index.docbook:720 msgid "" "Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but " "not #if !defined(__GTK_DOC_IGNORE__) or other combinations." @@ -1232,12 +1241,12 @@ msgstr "" "ale ne #if !defined(__GTK_DOC_IGNORE__) nebo jiné kombinace." #. (itstool) path: sect1/title -#: C/index.docbook:724 +#: C/index.docbook:730 msgid "Documentation comments" msgstr "Dokumentační komentáře" #. (itstool) path: example/programlisting -#: C/index.docbook:730 +#: C/index.docbook:736 #, no-wrap msgid "" "\n" @@ -1253,7 +1262,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:726 +#: C/index.docbook:732 msgid "" "A multiline comment that starts with an additional '*' marks a documentation " "block that will be processed by the GTK-Doc tools. <_:example-1/>" @@ -1262,7 +1271,7 @@ msgstr "" "dokumentačním blokem a bude zpracovaný nástroji GTK-Doc. <_:example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:739 +#: C/index.docbook:745 msgid "" "The 'identifier' is one line with the name of the item the comment is " "related to. The syntax differs a little depending on the item. (TODO add " @@ -1273,7 +1282,7 @@ msgstr "" "se seznamem identifikátorů)" #. (itstool) path: sect1/para -#: C/index.docbook:745 +#: C/index.docbook:751 msgid "" "The 'documentation' block is also different for each symbol type. Symbol " "types that get parameters such as functions or macros have the parameter " @@ -1292,7 +1301,7 @@ msgstr "" "hvězdička mezera mezera). To se hodí na text s pevným formátem (výpis kódu)." #. (itstool) path: listitem/para -#: C/index.docbook:762 +#: C/index.docbook:768 msgid "" "What it is: The name for a class or function can sometimes be misleading for " "people coming from a different background." @@ -1301,26 +1310,26 @@ msgstr "" "používají něco jiného." #. (itstool) path: listitem/para -#: C/index.docbook:768 +#: C/index.docbook:774 msgid "" "What it does: Tell about common uses. Put it in relation with the other API." msgstr "" "K čemu to je: Uveďte běžném použití. Dejte ho do souvislosti se zbytkem API." #. (itstool) path: tip/para -#: C/index.docbook:758 +#: C/index.docbook:764 msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" msgstr "" "Když píšete dokumentaci ke kódu, popište dva aspekty: <_:itemizedlist-1/>" #. (itstool) path: listitem/para -#: C/index.docbook:783 +#: C/index.docbook:789 msgid "Use function() to refer to functions or macros which take arguments." msgstr "" "Použijte funkce() pro odkaz na funkci nebo makro, které mají argumenty." #. (itstool) path: listitem/para -#: C/index.docbook:788 +#: C/index.docbook:794 msgid "" "Use @param to refer to parameters. Also use this when referring to " "parameters of other functions, related to the one being described." @@ -1329,12 +1338,12 @@ msgstr "" "odkazujete na parametry jiných funkcí, vztahujících se k popisované funkci." #. (itstool) path: listitem/para -#: C/index.docbook:794 +#: C/index.docbook:800 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "Použijte %konstanta pro odkaz na konstantu, např. %G_TRAVERSE_LEAFS." #. (itstool) path: listitem/para -#: C/index.docbook:799 +#: C/index.docbook:805 msgid "" "Use #symbol to refer to other types of symbol, e.g. structs and enums and " "macros which don't take arguments." @@ -1343,17 +1352,17 @@ msgstr "" "makro, který nemá argumenty." #. (itstool) path: listitem/para -#: C/index.docbook:805 +#: C/index.docbook:811 msgid "Use #Object::signal to refer to a GObject signal." msgstr "Použijte #Objekt::signál pro odkaz na signál objektu GObject." #. (itstool) path: listitem/para -#: C/index.docbook:810 +#: C/index.docbook:816 msgid "Use #Object:property to refer to a GObject property." msgstr "Použijte #Objekt:vlastnost pro odkaz na vlastnost objektu GObject." #. (itstool) path: listitem/para -#: C/index.docbook:815 +#: C/index.docbook:821 msgid "" "Use #Struct.field to refer to a field inside a structure and #GObjectClass." "foo_bar() to refer to a vmethod." @@ -1362,7 +1371,7 @@ msgstr "" "neco() pro odkaz na virtuální metodu." #. (itstool) path: sect1/para -#: C/index.docbook:777 +#: C/index.docbook:783 msgid "" "One advantage of hyper-text over plain-text is the ability to have links in " "the document. Writing the correct markup for a link can be tedious though. " @@ -1374,7 +1383,7 @@ msgstr "" "vám snaží pomoci několika užitečnými zkratkami. <_:itemizedlist-1/>" #. (itstool) path: tip/para -#: C/index.docbook:824 +#: C/index.docbook:830 msgid "" "If you need to use the special characters '<', '>', '()', '@', '%', or " "'#' in your documentation without GTK-Doc changing them you can use the XML " @@ -1389,7 +1398,7 @@ msgstr "" "se zpětným lomítkem „\\“." #. (itstool) path: sect1/para -#: C/index.docbook:833 +#: C/index.docbook:839 msgid "" "DocBook can do more than just links. One can also have lists, examples, " "headings, and images. As of version 1.20, the preferred way is to use a " @@ -1407,7 +1416,7 @@ msgstr "" "začátku." #. (itstool) path: sect1/para -#: C/index.docbook:844 +#: C/index.docbook:850 msgid "" "While markdown is now preferred one can mix both. One limitation here is " "that one can use docbook xml within markdown, but markdown within docbook " @@ -1418,7 +1427,7 @@ msgstr "" "markdown v docbook xml podporován není." #. (itstool) path: sect1/para -#: C/index.docbook:850 +#: C/index.docbook:856 msgid "" "In older GTK-Doc releases, if you need support for additional formatting, " "you would need to enable the usage of docbook XML tags inside doc-comments " @@ -1433,12 +1442,12 @@ msgstr "" "Makefile.am." #. (itstool) path: example/title -#: C/index.docbook:859 +#: C/index.docbook:865 msgid "GTK-Doc comment block using Markdown" msgstr "Komentářový blok GTK-Doc používající značkovací jazyk" #. (itstool) path: example/programlisting -#: C/index.docbook:860 +#: C/index.docbook:866 #, no-wrap msgid "" "\n" @@ -1514,7 +1523,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:899 +#: C/index.docbook:905 msgid "" "More examples of what markdown tags are supported can be found in the Referenční příručce k syntaxi Markdown pro dokumentaci GTK+." #. (itstool) path: tip/para -#: C/index.docbook:905 +#: C/index.docbook:911 msgid "" "As already mentioned earlier GTK-Doc is for documenting public API. Thus one " "cannot write documentation for static symbols. Nevertheless it is good to " @@ -1544,12 +1553,12 @@ msgstr "" "správné místo v souboru oddílů vložit název symbolu." #. (itstool) path: sect1/title -#: C/index.docbook:919 +#: C/index.docbook:925 msgid "Documenting sections" msgstr "Dokumentování oddílů" #. (itstool) path: sect1/para -#: C/index.docbook:921 +#: C/index.docbook:927 msgid "" "Each section of the documentation contains information about one class or " "module. To introduce the component one can write a section block. The short " @@ -1561,12 +1570,12 @@ msgstr "" "použije v rámci tabulky s obsahem. Všechna @pole jsou volitelná." #. (itstool) path: example/title -#: C/index.docbook:929 +#: C/index.docbook:935 msgid "Section comment block" msgstr "Komentářový blok oddílu" #. (itstool) path: example/programlisting -#: C/index.docbook:930 +#: C/index.docbook:936 #, no-wrap msgid "" "\n" @@ -1598,12 +1607,12 @@ msgstr "" " */\n" #. (itstool) path: varlistentry/term -#: C/index.docbook:949 +#: C/index.docbook:955 msgid "SECTION:<name>" msgstr "SECTION:<název>" #. (itstool) path: listitem/para -#: C/index.docbook:951 +#: C/index.docbook:957 msgid "" "The name links the section documentation to the respective part in the " "<package>-sections.txt file. The name given here " @@ -1615,12 +1624,12 @@ msgstr "" "<SOUBOR> v souboru <package>-sections.txt." #. (itstool) path: varlistentry/term -#: C/index.docbook:960 +#: C/index.docbook:966 msgid "@short_description" msgstr "@short_description" #. (itstool) path: listitem/para -#: C/index.docbook:962 +#: C/index.docbook:968 msgid "" "A one line description of the section, that later will appear after the " "links in the TOC and at the top of the section page." @@ -1629,12 +1638,12 @@ msgstr "" "obsahem a na začátku stránky oddílu." #. (itstool) path: varlistentry/term -#: C/index.docbook:969 +#: C/index.docbook:975 msgid "@title" msgstr "@title" #. (itstool) path: listitem/para -#: C/index.docbook:971 +#: C/index.docbook:977 msgid "" "The section title defaults to <name> from the SECTION declaration. It " "can be overridden with the @title field." @@ -1643,12 +1652,12 @@ msgstr "" "jej ale určit i přímo v poli @title." #. (itstool) path: varlistentry/term -#: C/index.docbook:978 +#: C/index.docbook:984 msgid "@section_id" msgstr "@section_id" #. (itstool) path: listitem/para -#: C/index.docbook:980 +#: C/index.docbook:986 msgid "" "Overrides the use of title as a section identifier. For GObjects the <" "title> is used as a section_id and for other sections it is <" @@ -1659,22 +1668,22 @@ msgstr "" "MODULE>-<title>." #. (itstool) path: varlistentry/term -#: C/index.docbook:988 +#: C/index.docbook:994 msgid "@see_also" msgstr "@see_also" #. (itstool) path: listitem/para -#: C/index.docbook:990 +#: C/index.docbook:996 msgid "A list of symbols that are related to this section." msgstr "Seznam symbolů, které se vztahují k tomuto oddílu." #. (itstool) path: varlistentry/term -#: C/index.docbook:996 +#: C/index.docbook:1002 msgid "@stability" msgstr "@stability" #. (itstool) path: listitem/para -#: C/index.docbook:1003 +#: C/index.docbook:1009 msgid "" "Stable - The intention of a Stable interface is to enable arbitrary third " "parties to develop applications to these interfaces, release them, and have " @@ -1690,7 +1699,7 @@ msgstr "" "nekompatibilní změny očekávají zřídka v opravdu odůvodněných případech." #. (itstool) path: listitem/para -#: C/index.docbook:1015 +#: C/index.docbook:1021 msgid "" "Unstable - Unstable interfaces are experimental or transitional. They are " "typically used to give outside developers early access to new or rapidly " @@ -1706,7 +1715,7 @@ msgstr "" "následujíc." #. (itstool) path: listitem/para -#: C/index.docbook:1027 +#: C/index.docbook:1033 msgid "" "Private - An interface that can be used within the GNOME stack itself, but " "that is not documented for end-users. Such functions should only be used in " @@ -1717,7 +1726,7 @@ msgstr "" "měly používat jen určeným a dokumentovaným způsobem." #. (itstool) path: listitem/para -#: C/index.docbook:1036 +#: C/index.docbook:1042 msgid "" "Internal - An interface that is internal to a module and does not require " "end-user documentation. Functions that are undocumented are assumed to be " @@ -1728,7 +1737,7 @@ msgstr "" "nedokumentované, jsou považované za interní." #. (itstool) path: listitem/para -#: C/index.docbook:998 +#: C/index.docbook:1004 msgid "" "An informal description of the stability level this API has. We recommend " "the use of one of these terms: <_:itemizedlist-1/>" @@ -1737,12 +1746,12 @@ msgstr "" "těchto termínů: <_:itemizedlist-1/>" #. (itstool) path: varlistentry/term -#: C/index.docbook:1048 +#: C/index.docbook:1054 msgid "@include" msgstr "@include" #. (itstool) path: listitem/para -#: C/index.docbook:1050 +#: C/index.docbook:1056 msgid "" "The #include files to show in the section synopsis (a " "comma separated list), overriding the global value from the --default-stability argument to " @@ -1867,17 +1876,17 @@ msgstr "" "do gtkdoc-mkdb." #. (itstool) path: variablelist/title -#: C/index.docbook:1128 +#: C/index.docbook:1134 msgid "Stability Tags" msgstr "Značky pro stabilitu" #. (itstool) path: varlistentry/term -#: C/index.docbook:1129 +#: C/index.docbook:1135 msgid "Stability: Stable" msgstr "Stability: Stable" #. (itstool) path: listitem/para -#: C/index.docbook:1131 +#: C/index.docbook:1137 msgid "" "Mark the element as stable. This is for public APIs which are guaranteed to " "remain stable for all future minor releases of the project." @@ -1886,12 +1895,12 @@ msgstr "" "že zůstanou stabilní po všechna minoritní vydání projektu." #. (itstool) path: varlistentry/term -#: C/index.docbook:1138 +#: C/index.docbook:1144 msgid "Stability: Unstable" msgstr "Stability: Unstable" #. (itstool) path: listitem/para -#: C/index.docbook:1140 +#: C/index.docbook:1146 msgid "" "Mark the element as unstable. This is for public APIs which are released as " "a preview before being stabilised." @@ -1900,12 +1909,12 @@ msgstr "" "vydána jako ukázky před tím, než jsou stabilizována." #. (itstool) path: varlistentry/term -#: C/index.docbook:1146 +#: C/index.docbook:1152 msgid "Stability: Private" msgstr "Stability: Private" #. (itstool) path: listitem/para -#: C/index.docbook:1148 +#: C/index.docbook:1154 msgid "" "Mark the element as private. This is for interfaces which can be used by " "tightly coupled modules, but not by arbitrary third parties." @@ -1914,7 +1923,7 @@ msgstr "" "použita přímo v modulu, ale ne kterýmikoliv třetími stranami." #. (itstool) path: example/programlisting -#: C/index.docbook:1158 +#: C/index.docbook:1164 #, no-wrap msgid "" "\n" @@ -1953,12 +1962,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1178 C/index.docbook:1188 +#: C/index.docbook:1184 C/index.docbook:1194 msgid "Annotations" msgstr "Anotace" #. (itstool) path: sect2/para -#: C/index.docbook:1180 +#: C/index.docbook:1186 msgid "" "Documentation blocks can contain annotation-tags. These tags will be " "rendered with tooltips describing their meaning. The tags are used by " @@ -1973,7 +1982,7 @@ msgstr "" "org/GObjectIntrospection/Annotations\" type=\"http\">wiki." #. (itstool) path: example/programlisting -#: C/index.docbook:1189 +#: C/index.docbook:1195 #, no-wrap msgid "" "\n" @@ -2014,12 +2023,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1210 C/index.docbook:1239 +#: C/index.docbook:1216 C/index.docbook:1245 msgid "Function comment block" msgstr "Komentářový blok pro funkci" #. (itstool) path: listitem/para -#: C/index.docbook:1216 +#: C/index.docbook:1222 msgid "" "Document whether returned objects, lists, strings, etc, should be freed/" "unrefed/released." @@ -2028,24 +2037,24 @@ msgstr "" "uvolnit z paměti." #. (itstool) path: listitem/para -#: C/index.docbook:1222 +#: C/index.docbook:1228 msgid "Document whether parameters can be NULL, and what happens if they are." msgstr "" "Zdokumentovat, jestli může parametr být NULL a co se stane, když tomu tak je." #. (itstool) path: listitem/para -#: C/index.docbook:1227 +#: C/index.docbook:1233 msgid "" "Mention interesting pre-conditions and post-conditions where appropriate." msgstr "Kde je to vhodné, zmínit úvodní a koncové podmínky." #. (itstool) path: sect2/para -#: C/index.docbook:1212 C/index.docbook:1298 +#: C/index.docbook:1218 C/index.docbook:1304 msgid "Please remember to: <_:itemizedlist-1/>" msgstr "Nezapomeňte prosím: <_:itemizedlist-1/>" #. (itstool) path: sect2/para -#: C/index.docbook:1234 +#: C/index.docbook:1240 msgid "" "Gtk-doc assumes all symbols (macros, functions) starting with '_' are " "private. They are treated like static functions." @@ -2054,7 +2063,7 @@ msgstr "" "„_“, jsou soukromé. Potom se s nimi zachází jako se statickými funkcemi." #. (itstool) path: example/programlisting -#: C/index.docbook:1240 +#: C/index.docbook:1246 #, no-wrap msgid "" "\n" @@ -2096,27 +2105,27 @@ msgstr "" " */\n" #. (itstool) path: variablelist/title -#: C/index.docbook:1261 +#: C/index.docbook:1267 msgid "Function tags" msgstr "Značky pro funkce" #. (itstool) path: varlistentry/term -#: C/index.docbook:1262 C/index.docbook:1469 +#: C/index.docbook:1268 C/index.docbook:1475 msgid "Returns:" msgstr "Returns:" #. (itstool) path: listitem/para -#: C/index.docbook:1264 +#: C/index.docbook:1270 msgid "Paragraph describing the returned result." msgstr "Odstavec popisující vracený výsledek." #. (itstool) path: varlistentry/term -#: C/index.docbook:1269 +#: C/index.docbook:1275 msgid "@...:" msgstr "@…:" #. (itstool) path: listitem/para -#: C/index.docbook:1271 +#: C/index.docbook:1277 msgid "" "In case the function has variadic arguments, you should use this tag " "(@Varargs: does also work for historic reasons)." @@ -2126,12 +2135,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1281 C/index.docbook:1283 +#: C/index.docbook:1287 C/index.docbook:1289 msgid "Property comment block" msgstr "Komentářový blok pro vlastnost" #. (itstool) path: example/programlisting -#: C/index.docbook:1284 +#: C/index.docbook:1290 #, no-wrap msgid "" "\n" @@ -2152,12 +2161,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1296 C/index.docbook:1315 +#: C/index.docbook:1302 C/index.docbook:1321 msgid "Signal comment block" msgstr "Komentářový blok pro signál" #. (itstool) path: listitem/para -#: C/index.docbook:1302 +#: C/index.docbook:1308 msgid "" "Document when the signal is emitted and whether it is emitted before or " "after other signals." @@ -2166,12 +2175,12 @@ msgstr "" "ostatních signálech." #. (itstool) path: listitem/para -#: C/index.docbook:1308 +#: C/index.docbook:1314 msgid "Document what an application might do in the signal handler." msgstr "Zdokumentovat, co aplikace smí v obsluze signálu provádět." #. (itstool) path: example/programlisting -#: C/index.docbook:1316 +#: C/index.docbook:1322 #, no-wrap msgid "" "\n" @@ -2202,12 +2211,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1333 C/index.docbook:1334 +#: C/index.docbook:1339 C/index.docbook:1340 msgid "Struct comment block" msgstr "Komentářový blok pro strukturu" #. (itstool) path: example/programlisting -#: C/index.docbook:1335 +#: C/index.docbook:1341 #, no-wrap msgid "" "\n" @@ -2237,7 +2246,7 @@ msgstr "" "} FooWidget;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1350 +#: C/index.docbook:1356 msgid "" "Use /*< private >*/ before the private struct fields you " "want to hide. Use /*< public >*/ for the reverse " @@ -2248,7 +2257,7 @@ msgstr "" "*/." #. (itstool) path: sect2/para -#: C/index.docbook:1356 +#: C/index.docbook:1362 msgid "" "If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" " "it will be considered private automatically and doesn't need to be mentioned " @@ -2259,7 +2268,7 @@ msgstr "" "komentářovém bloku." #. (itstool) path: sect2/para -#: C/index.docbook:1362 +#: C/index.docbook:1368 msgid "" "Struct comment blocks can also be used for GObjects and GObjectClasses. It " "is usually a good idea to add a comment block for a class, if it has " @@ -2279,12 +2288,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1374 C/index.docbook:1375 +#: C/index.docbook:1380 C/index.docbook:1381 msgid "Enum comment block" msgstr "Komentářový blok pro výčty" #. (itstool) path: example/programlisting -#: C/index.docbook:1376 +#: C/index.docbook:1382 #, no-wrap msgid "" "\n" @@ -2318,7 +2327,7 @@ msgstr "" "} Something;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1393 +#: C/index.docbook:1399 msgid "" "Use /*< private >*/ before the private enum values you " "want to hide. Use /*< public >*/ for the reverse " @@ -2329,12 +2338,12 @@ msgstr "" "public >*/." #. (itstool) path: sect1/title -#: C/index.docbook:1404 +#: C/index.docbook:1410 msgid "Inline program documentation" msgstr "Dokumentaci k vloženým programům" #. (itstool) path: sect1/para -#: C/index.docbook:1405 +#: C/index.docbook:1411 msgid "" "You can document programs and their commandline interface using inline " "documentation." @@ -2343,37 +2352,37 @@ msgstr "" "vložené dokumentace." #. (itstool) path: variablelist/title -#: C/index.docbook:1411 +#: C/index.docbook:1417 msgid "Tags" msgstr "Značky" #. (itstool) path: varlistentry/term -#: C/index.docbook:1413 +#: C/index.docbook:1419 msgid "PROGRAM" msgstr "PROGRAM" #. (itstool) path: listitem/para -#: C/index.docbook:1416 +#: C/index.docbook:1422 msgid "Defines the start of a program documentation." msgstr "Definuje začátek dokumentace k programu." #. (itstool) path: varlistentry/term -#: C/index.docbook:1423 +#: C/index.docbook:1429 msgid "@short_description:" msgstr "@short_description:" #. (itstool) path: listitem/para -#: C/index.docbook:1425 +#: C/index.docbook:1431 msgid "Defines a short description of the program. (Optional)" msgstr "Definuje krátký popis programu. (volitelné)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1432 +#: C/index.docbook:1438 msgid "@synopsis:" msgstr "@synopsis:" #. (itstool) path: listitem/para -#: C/index.docbook:1434 +#: C/index.docbook:1440 msgid "" "Defines the arguments, or list of arguments that the program can take. " "(Optional)" @@ -2381,52 +2390,52 @@ msgstr "" "Definuje argumenty nebo seznam argumentů, které program přebírá. (volitelné)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1442 +#: C/index.docbook:1448 msgid "@see_also:" msgstr "@see_also:" #. (itstool) path: listitem/para -#: C/index.docbook:1444 +#: C/index.docbook:1450 msgid "See Also manual page section. (Optional)" msgstr "Část stránky oddílu „Viz také“. (volitelné)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1451 +#: C/index.docbook:1457 msgid "@arg:" msgstr "@arg:" #. (itstool) path: listitem/para -#: C/index.docbook:1453 +#: C/index.docbook:1459 msgid "Argument(s) passed to the program and their description. (Optional)" msgstr "Argument(y) předávané do programu a jejich popis. (volitelné)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1460 +#: C/index.docbook:1466 msgid "Description:" msgstr "Description:" #. (itstool) path: listitem/para -#: C/index.docbook:1462 +#: C/index.docbook:1468 msgid "A longer description of the program." msgstr "Úplný popis programu." #. (itstool) path: listitem/para -#: C/index.docbook:1471 +#: C/index.docbook:1477 msgid "Specificy what value(s) the program returns. (Optional)" msgstr "Specifikuje, jakou hodnotu či více hodnot program vrací. (volitelné)" #. (itstool) path: sect2/title -#: C/index.docbook:1480 +#: C/index.docbook:1486 msgid "Example of program documentation." msgstr "Příklad dokumentace k programu." #. (itstool) path: example/title -#: C/index.docbook:1481 +#: C/index.docbook:1487 msgid "Program documentation block" msgstr "Komentářový blok pro program" #. (itstool) path: example/programlisting -#: C/index.docbook:1482 +#: C/index.docbook:1488 #, no-wrap msgid "" "\n" @@ -2470,12 +2479,12 @@ msgstr "" "}\n" #. (itstool) path: sect1/title -#: C/index.docbook:1508 +#: C/index.docbook:1514 msgid "Useful DocBook tags" msgstr "Užitečné značky DocBook" #. (itstool) path: sect1/para -#: C/index.docbook:1510 +#: C/index.docbook:1516 msgid "" "Here are some DocBook tags which are most useful when documenting the code." msgstr "" @@ -2483,7 +2492,7 @@ msgstr "" "význam." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1519 +#: C/index.docbook:1525 #, no-wrap msgid "" "\n" @@ -2493,7 +2502,7 @@ msgstr "" "<link linkend=\"glib-Hash-Tables\">Hašovací tabulky</link>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1515 +#: C/index.docbook:1521 msgid "" "To link to another section in the GTK docs: <_:informalexample-1/> The " "linkend is the SGML/XML id on the top item of the page you want to link to. " @@ -2508,7 +2517,7 @@ msgstr "" "podtržítka se převedou na „-“, aby to vyhovovalo SGML/XML." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1532 +#: C/index.docbook:1538 #, no-wrap msgid "" "\n" @@ -2518,7 +2527,7 @@ msgstr "" "<function>…</function>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1529 +#: C/index.docbook:1535 msgid "" "To refer to an external function, e.g. a standard C function: <_:" "informalexample-1/>" @@ -2527,7 +2536,7 @@ msgstr "" ">" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1541 +#: C/index.docbook:1547 #, no-wrap msgid "" "\n" @@ -2547,7 +2556,7 @@ msgstr "" "</example>\n" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1552 +#: C/index.docbook:1558 #, no-wrap msgid "" "\n" @@ -2565,7 +2574,7 @@ msgstr "" "</informalexample>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1538 +#: C/index.docbook:1544 msgid "" "To include example code: <_:informalexample-1/> or possibly this, for very " "short code fragments which don't need a title: <_:informalexample-2/> For " @@ -2576,7 +2585,7 @@ msgstr "" "V novějších verzích GTK-Doc je také podporované zkracování: |[ … ]|" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1571 +#: C/index.docbook:1577 #, no-wrap msgid "" "\n" @@ -2608,12 +2617,12 @@ msgstr "" "</itemizedlist>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1568 +#: C/index.docbook:1574 msgid "To include bulleted lists: <_:informalexample-1/>" msgstr "Vložení seznamu s odrážkami: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1591 +#: C/index.docbook:1597 #, no-wrap msgid "" "\n" @@ -2631,13 +2640,13 @@ msgstr "" "</note>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1588 +#: C/index.docbook:1594 msgid "" "To include a note which stands out from the text: <_:informalexample-1/>" msgstr "Vložení poznámky, která se objeví mimo text: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1604 +#: C/index.docbook:1610 #, no-wrap msgid "" "\n" @@ -2647,12 +2656,12 @@ msgstr "" "<type>unsigned char</type>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1601 +#: C/index.docbook:1607 msgid "To refer to a type: <_:informalexample-1/>" msgstr "Odkaz na typ: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1613 +#: C/index.docbook:1619 #, no-wrap msgid "" "\n" @@ -2662,7 +2671,7 @@ msgstr "" "<structname>XFontStruct</structname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1610 +#: C/index.docbook:1616 msgid "" "To refer to an external structure (not one described in the GTK docs): <_:" "informalexample-1/>" @@ -2671,7 +2680,7 @@ msgstr "" "informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1622 +#: C/index.docbook:1628 #, no-wrap msgid "" "\n" @@ -2681,12 +2690,12 @@ msgstr "" "<structfield>len</structfield>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1619 +#: C/index.docbook:1625 msgid "To refer to a field of a structure: <_:informalexample-1/>" msgstr "Odkaz na pole struktury: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1631 +#: C/index.docbook:1637 #, no-wrap msgid "" "\n" @@ -2696,7 +2705,7 @@ msgstr "" "<classname>GtkWidget</classname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1628 +#: C/index.docbook:1634 msgid "" "To refer to a class name, we could possibly use: <_:informalexample-1/> but " "you'll probably be using #GtkWidget instead (to automatically create a link " @@ -2709,7 +2718,7 @@ msgstr "" "\"documenting_syntax\">zkratky)." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1642 +#: C/index.docbook:1648 #, no-wrap msgid "" "\n" @@ -2719,12 +2728,12 @@ msgstr "" "<emphasis>Toto je důležité</emphasis>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1639 +#: C/index.docbook:1645 msgid "To emphasize text: <_:informalexample-1/>" msgstr "Zvýrazněný text: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1651 +#: C/index.docbook:1657 #, no-wrap msgid "" "\n" @@ -2734,12 +2743,12 @@ msgstr "" "<filename>/home/user/documents</filename>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1648 +#: C/index.docbook:1654 msgid "For filenames use: <_:informalexample-1/>" msgstr "Pro název souboru použijte: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1660 +#: C/index.docbook:1666 #, no-wrap msgid "" "\n" @@ -2749,17 +2758,17 @@ msgstr "" "<keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1657 +#: C/index.docbook:1663 msgid "To refer to keys use: <_:informalexample-1/>" msgstr "Odkaz na použití klávesy: <_:informalexample-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1670 +#: C/index.docbook:1676 msgid "Filling the extra files" msgstr "Vyplňování dodatečných souborů" #. (itstool) path: chapter/para -#: C/index.docbook:1672 +#: C/index.docbook:1678 msgid "" "There are a couple of extra files, that need to be maintained along with the " "inline source code comments: <package>.types, " @@ -2772,12 +2781,12 @@ msgstr "" "<balíček>-sections.txt." #. (itstool) path: sect1/title -#: C/index.docbook:1681 +#: C/index.docbook:1687 msgid "Editing the types file" msgstr "Úprava souboru s typy" #. (itstool) path: sect1/para -#: C/index.docbook:1683 +#: C/index.docbook:1689 msgid "" "If your library or application includes GObjects, you want their signals, " "arguments/parameters and position in the hierarchy to be shown in the " @@ -2792,12 +2801,12 @@ msgstr "" "filename>." #. (itstool) path: example/title -#: C/index.docbook:1692 +#: C/index.docbook:1698 msgid "Example types file snippet" msgstr "Příklad úryvku ze souboru typů" #. (itstool) path: example/programlisting -#: C/index.docbook:1693 +#: C/index.docbook:1699 #, no-wrap msgid "" "\n" @@ -2817,7 +2826,7 @@ msgstr "" "gtk_arrow_get_type\n" #. (itstool) path: sect1/para -#: C/index.docbook:1704 +#: C/index.docbook:1710 msgid "" "Since GTK-Doc 1.8 gtkdoc-scan can generate this " "list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in " @@ -2830,12 +2839,12 @@ msgstr "" "byste soubor s typy šířit do správy verzí." #. (itstool) path: sect1/title -#: C/index.docbook:1713 +#: C/index.docbook:1719 msgid "Editing the master document" msgstr "Úprava hlavního dokumentu" #. (itstool) path: sect1/para -#: C/index.docbook:1715 +#: C/index.docbook:1721 msgid "" "GTK-Doc produces documentation in DocBook SGML/XML. When processing the " "inline source comments, the GTK-Doc tools generate one documentation page " @@ -2848,7 +2857,7 @@ msgstr "" "soubor. Všechny jsou pak uvedené seřazené v hlavním dokumentu." #. (itstool) path: sect1/para -#: C/index.docbook:1722 +#: C/index.docbook:1728 msgid "" "While GTK-Doc creates a template master document for you, later runs will " "not touch it again. This means that one can freely structure the " @@ -2865,7 +2874,7 @@ msgstr "" "nahlédnout, jestli se v něm neobjevily nějaké nové věci." #. (itstool) path: tip/para -#: C/index.docbook:1732 +#: C/index.docbook:1738 msgid "" "Do not create tutorials as extra documents. Just write extra chapters. The " "benefit of directly embedding the tutorial for your library into the API " @@ -2880,7 +2889,7 @@ msgstr "" "v knihovně." #. (itstool) path: sect1/para -#: C/index.docbook:1741 +#: C/index.docbook:1747 msgid "" "So what are the things to change inside the master document? For a start is " "only a little. There are some placeholders (text in square brackets) there " @@ -2891,12 +2900,12 @@ msgstr "" "závorkách), o které byste se měli postarat." #. (itstool) path: example/title -#: C/index.docbook:1748 +#: C/index.docbook:1754 msgid "Master document header" msgstr "Hlavička hlavního dokumentu" #. (itstool) path: example/programlisting -#: C/index.docbook:1749 +#: C/index.docbook:1755 #, no-wrap msgid "" "\n" @@ -2926,7 +2935,7 @@ msgstr "" " <title>[Insert title here]</title>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1765 +#: C/index.docbook:1771 msgid "" "In addition a few option elements are created in commented form. You can " "review these and enable them as you like." @@ -2935,12 +2944,12 @@ msgstr "" "projít a případně povolit." #. (itstool) path: example/title -#: C/index.docbook:1771 +#: C/index.docbook:1777 msgid "Optional part in the master document" msgstr "Volitelná část hlavního dokumentu" #. (itstool) path: example/programlisting -#: C/index.docbook:1772 +#: C/index.docbook:1778 #, no-wrap msgid "" "\n" @@ -2954,7 +2963,7 @@ msgstr "" " -->\n" #. (itstool) path: sect1/para -#: C/index.docbook:1780 +#: C/index.docbook:1786 msgid "" "Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind " @@ -2965,12 +2974,12 @@ msgstr "" "vygenerované soubory XML, které zatím nejsou v dokumentaci zahrnuté." #. (itstool) path: example/title -#: C/index.docbook:1788 C/index.docbook:1823 +#: C/index.docbook:1794 C/index.docbook:1829 msgid "Including generated sections" msgstr "Vkládání generovaných oddílů" #. (itstool) path: example/programlisting -#: C/index.docbook:1789 +#: C/index.docbook:1795 #, no-wrap msgid "" "\n" @@ -2986,12 +2995,12 @@ msgstr "" " …\n" #. (itstool) path: sect1/title -#: C/index.docbook:1801 +#: C/index.docbook:1807 msgid "Editing the section file" msgstr "Úprava souboru oddílů" #. (itstool) path: sect1/para -#: C/index.docbook:1803 +#: C/index.docbook:1809 msgid "" "The section file is used to organise the documentation output by GTK-Doc. " "Here one specifies which symbol belongs to which module or class and control " @@ -3002,7 +3011,7 @@ msgstr "" "viditelnost (jestli je veřejný nebo soukromý)." #. (itstool) path: sect1/para -#: C/index.docbook:1809 +#: C/index.docbook:1815 msgid "" "The section file is a plain text file with tags delimiting sections. Blank " "lines are ignored and lines starting with a '#' are treated as comment lines." @@ -3012,7 +3021,7 @@ msgstr "" "jako s komentářovými řádky." #. (itstool) path: note/para -#: C/index.docbook:1816 +#: C/index.docbook:1822 msgid "" "While the tags make the file look like xml, it is not. Please do not close " "tags like <SUBSECTION>." @@ -3021,7 +3030,7 @@ msgstr "" "Neuzavírejte prosím značky jako je <SUBSECTION>." #. (itstool) path: example/programlisting -#: C/index.docbook:1824 +#: C/index.docbook:1830 #, no-wrap msgid "" "\n" @@ -3053,7 +3062,7 @@ msgstr "" "</SECTION>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1841 +#: C/index.docbook:1847 msgid "" "The <FILE> ... </FILE> tag is used to specify the file name, " "without any suffix. For example, using '<FILE>gnome-config</" @@ -3075,7 +3084,7 @@ msgstr "" "názvu třídy GObject převedeného na malá písmena.)" #. (itstool) path: sect1/para -#: C/index.docbook:1853 +#: C/index.docbook:1859 msgid "" "The <TITLE> ... </TITLE> tag is used to specify the title of the " "section. It is only useful before the templates (if used) are initially " @@ -3089,7 +3098,7 @@ msgstr "" "zdrojovém kódu." #. (itstool) path: sect1/para -#: C/index.docbook:1860 +#: C/index.docbook:1866 msgid "" "You can group items in the section by using the <SUBSECTION> tag. " "Currently it outputs a blank line between subsections in the synopsis " @@ -3119,7 +3128,7 @@ msgstr "" "virtuální metody)." #. (itstool) path: sect1/para -#: C/index.docbook:1879 +#: C/index.docbook:1885 msgid "" "You can also use <INCLUDE> ... </INCLUDE> to specify the " "#include files which are shown in the synopsis sections. It contains a comma-" @@ -3134,12 +3143,12 @@ msgstr "" "konce souboru. Když je nastavíte v konkrétním oddílu, použijí se jen pro něj." #. (itstool) path: chapter/title -#: C/index.docbook:1893 +#: C/index.docbook:1899 msgid "Controlling the result" msgstr "Ovlivnění výsledku" #. (itstool) path: chapter/para -#: C/index.docbook:1895 +#: C/index.docbook:1901 msgid "" "A GTK-Doc run generates report files inside the documentation directory. The " "generated files are named: <package>-undocumented.txt<package>-undocumented.txt file starts with " "the documentation coverage summary. Below are two sections divided by blank " @@ -3170,7 +3179,7 @@ msgstr "" "parametr." #. (itstool) path: chapter/para -#: C/index.docbook:1913 +#: C/index.docbook:1919 msgid "" "The <package>-undeclared.txt file lists symbols " "given in the <package>-sections.txt but not found " @@ -3182,7 +3191,7 @@ msgstr "" "v nich není překlep." #. (itstool) path: chapter/para -#: C/index.docbook:1920 +#: C/index.docbook:1926 msgid "" "The <package>-unused.txt file lists symbol names, " "where the GTK-Doc scanner has found documentation, but does not know where " @@ -3195,7 +3204,7 @@ msgstr "" "balíček>-section.txt." #. (itstool) path: tip/para -#: C/index.docbook:1928 +#: C/index.docbook:1934 msgid "" "Enable or add the line in Makefile." "am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during " @@ -3207,7 +3216,7 @@ msgstr "" "správnosti údajů." #. (itstool) path: chapter/para -#: C/index.docbook:1935 +#: C/index.docbook:1941 msgid "" "One can also look at the files produced by the source code scanner: " "<package>-decl-list.txt and <" @@ -3224,7 +3233,7 @@ msgstr "" "zkontrolovat, jestli se vyskytuje v tomto souboru." #. (itstool) path: chapter/para -#: C/index.docbook:1944 +#: C/index.docbook:1950 msgid "" "If the project is GObject based, one can also look into the files produced " "by the object scanner: <package>.args.txt, " @@ -3245,12 +3254,12 @@ msgstr "" "Doc, aby přechodně zachovat soubor pro pozdější analýzu." #. (itstool) path: chapter/title -#: C/index.docbook:1959 +#: C/index.docbook:1965 msgid "Modernizing the documentation" msgstr "Modernizace dokumentu" #. (itstool) path: chapter/para -#: C/index.docbook:1961 +#: C/index.docbook:1967 msgid "" "GTK-Doc has been around for quite some time. In this section we list new " "features together with the version since when it is available." @@ -3259,12 +3268,12 @@ msgstr "" "funkcí spolu s číslem verze, od které je tato funkčnost k dispozici." #. (itstool) path: sect1/title -#: C/index.docbook:1967 +#: C/index.docbook:1973 msgid "GTK-Doc 1.9" msgstr "GTK-Doc 1.9" #. (itstool) path: sect1/para -#: C/index.docbook:1969 +#: C/index.docbook:1975 msgid "" "When using xml instead of sgml, one can actually name the master document " "<package>-docs.xml." @@ -3273,7 +3282,7 @@ msgstr "" "dokument <package>-docs.xml." #. (itstool) path: sect1/para -#: C/index.docbook:1974 +#: C/index.docbook:1980 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3294,7 +3303,7 @@ msgstr "" "meld <package>-decl-list.txt <package>-sections.txt." #. (itstool) path: sect1/para -#: C/index.docbook:1985 +#: C/index.docbook:1991 msgid "" "Version 1.8 already introduced the syntax for documenting sections in the " "sources instead of the separate files under configure.ac a je to." #. (itstool) path: sect1/title -#: C/index.docbook:1997 +#: C/index.docbook:2003 msgid "GTK-Doc 1.10" msgstr "GTK-Doc 1.10" #. (itstool) path: sect1/para -#: C/index.docbook:1999 +#: C/index.docbook:2005 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3337,17 +3346,17 @@ msgstr "" "filename> pro kód, který je sestavován podmíněně." #. (itstool) path: sect1/title -#: C/index.docbook:2010 +#: C/index.docbook:2016 msgid "GTK-Doc 1.16" msgstr "GTK-Doc 1.16" #. (itstool) path: example/title -#: C/index.docbook:2016 +#: C/index.docbook:2022 msgid "Enable gtkdoc-check" msgstr "Povolení gtkdoc-check" #. (itstool) path: example/programlisting -#: C/index.docbook:2017 +#: C/index.docbook:2023 #, no-wrap msgid "" "\n" @@ -3367,7 +3376,7 @@ msgstr "" "endif\n" #. (itstool) path: sect1/para -#: C/index.docbook:2012 +#: C/index.docbook:2018 msgid "" "This version includes a new tool called gtkdoc-check. This tool can run a " "set of sanity checks on your documentation. It is enabled by adding these " @@ -3379,12 +3388,12 @@ msgstr "" ">" #. (itstool) path: sect1/title -#: C/index.docbook:2030 +#: C/index.docbook:2036 msgid "GTK-Doc 1.20" msgstr "GTK-Doc 1.20" #. (itstool) path: sect1/para -#: C/index.docbook:2032 +#: C/index.docbook:2038 msgid "" "Version 1.18 brought some initial markdown support. Using markdown in doc " "comments is less intrusive than writing docbook xml. This version improves a " @@ -3398,17 +3407,17 @@ msgstr "" "\"documenting_syntax\">syntax komentářů." #. (itstool) path: sect1/title -#: C/index.docbook:2042 +#: C/index.docbook:2048 msgid "GTK-Doc 1.25" msgstr "GTK-Doc 1.25" #. (itstool) path: example/title -#: C/index.docbook:2052 +#: C/index.docbook:2058 msgid "Use pre-generated entities" msgstr "Používání předgenerovaných entit" #. (itstool) path: example/programlisting -#: C/index.docbook:2053 +#: C/index.docbook:2059 #, no-wrap msgid "" "\n" @@ -3450,7 +3459,7 @@ msgstr "" " </bookinfo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:2044 +#: C/index.docbook:2050 msgid "" "The makefiles shipped with this version generate an entity file at " "xml/gtkdocentities.ent, containing entities for e.g. " @@ -3469,12 +3478,12 @@ msgstr "" "hlavičku XML v generovaných souborech XML. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:2078 +#: C/index.docbook:2084 msgid "Documenting other interfaces" msgstr "Dokumentování ostatních rozhraní" #. (itstool) path: chapter/para -#: C/index.docbook:2080 +#: C/index.docbook:2086 msgid "" "So far we have been using GTK-Doc to document the API of code. The next " "sections contain suggestions how the tools can be used to document other " @@ -3485,12 +3494,12 @@ msgstr "" "dalších rozhraní." #. (itstool) path: sect1/title -#: C/index.docbook:2087 +#: C/index.docbook:2093 msgid "Command line options and man pages" msgstr "Přepínače příkazového řádku a manuálové stránky" #. (itstool) path: sect1/para -#: C/index.docbook:2089 +#: C/index.docbook:2095 msgid "" "As one can generate man pages for a docbook refentry as well, it sounds like " "a good idea to use it for that purpose. This way the interface is part of " @@ -3502,12 +3511,12 @@ msgstr "" "manuálovou stránku." #. (itstool) path: sect2/title -#: C/index.docbook:2096 +#: C/index.docbook:2102 msgid "Document the tool" msgstr "Dokumentování nástrojů" #. (itstool) path: sect2/para -#: C/index.docbook:2098 +#: C/index.docbook:2104 msgid "" "Create one refentry file per tool. Following our example we would call it meep/" @@ -3522,17 +3531,17 @@ msgstr "" "souboru v podsložce XML, například v glib." #. (itstool) path: sect2/title -#: C/index.docbook:2108 +#: C/index.docbook:2114 msgid "Adding the extra configure check" msgstr "Přidání doplňkových kontrol do configure" #. (itstool) path: example/title -#: C/index.docbook:2111 C/index.docbook:2129 +#: C/index.docbook:2117 C/index.docbook:2135 msgid "Extra configure checks" msgstr "Dodatečné kontroly nastavení" #. (itstool) path: example/programlisting -#: C/index.docbook:2112 +#: C/index.docbook:2118 #, no-wrap msgid "" "\n" @@ -3554,12 +3563,12 @@ msgstr "" "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" #. (itstool) path: sect2/title -#: C/index.docbook:2126 +#: C/index.docbook:2132 msgid "Adding the extra makefile rules" msgstr "Přidání doplňkových pravidel do Makefile" #. (itstool) path: example/programlisting -#: C/index.docbook:2130 +#: C/index.docbook:2136 #, no-wrap msgid "" "\n" @@ -3595,12 +3604,12 @@ msgstr "" "EXTRA_DIST += meep.xml\n" #. (itstool) path: sect1/title -#: C/index.docbook:2152 +#: C/index.docbook:2158 msgid "DBus interfaces" msgstr "Rozhraní D-Bus" #. (itstool) path: sect1/para -#: C/index.docbook:2154 +#: C/index.docbook:2160 msgid "" "(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" @@ -3609,27 +3618,27 @@ msgstr "" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" #. (itstool) path: chapter/title -#: C/index.docbook:2163 +#: C/index.docbook:2169 msgid "Frequently asked questions" msgstr "Často kladené dotazy" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2167 +#: C/index.docbook:2173 msgid "Question" msgstr "Dotaz" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2168 +#: C/index.docbook:2174 msgid "Answer" msgstr "Odpověď" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2170 +#: C/index.docbook:2176 msgid "No class hierarchy." msgstr "Schází hierarchie třídy." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2171 +#: C/index.docbook:2177 msgid "" "The objects xxx_get_type() function has not been " "entered into the <package>.types file." @@ -3638,12 +3647,12 @@ msgstr "" "objektu xxx_get_type()." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2177 +#: C/index.docbook:2183 msgid "Still no class hierarchy." msgstr "Stále schází hierarchie třídy." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2178 +#: C/index.docbook:2184 msgid "" "Missing or wrong naming in <package>-sections.txt " "file (see vysvětlení)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2184 +#: C/index.docbook:2190 msgid "Damn, I have still no class hierarchy." msgstr "Do háje, pořád nemám hierarchii třídy." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2185 +#: C/index.docbook:2191 msgid "" "Is the object name (name of the instance struct, e.g. GtkWidget) part of the normal section (don't put this into Standard or Private " @@ -3670,12 +3679,12 @@ msgstr "" "Private)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2192 +#: C/index.docbook:2198 msgid "No symbol index." msgstr "Chybí rejstřík symbolů." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2193 +#: C/index.docbook:2199 msgid "" "Does the <package>-docs.{xml,sgml} contain a " "index that xi:includes the generated index?" @@ -3684,12 +3693,12 @@ msgstr "" "který vloží pomocí xi:include vygenerovaný rejstřík?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2199 +#: C/index.docbook:2205 msgid "Symbols are not linked to their doc-section." msgstr "Symbol nemá odkaz do svého oddílu dokumentace." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2200 +#: C/index.docbook:2206 msgid "" "Is the doc-comment using the correct markup (added #,% or ())? Check if the " "gtkdoc-fixxref warns about unresolvable xrefs." @@ -3698,12 +3707,12 @@ msgstr "" "Podívejte se na varování gtkdoc-fixxref o nevyřešených křížových odkazech." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2206 +#: C/index.docbook:2212 msgid "A new class does not appear in the docs." msgstr "Nová třída se neobjevila v dokumentaci." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2207 +#: C/index.docbook:2213 msgid "" "Is the new page xi:included from <package>-docs.{xml,sgml}." @@ -3712,12 +3721,12 @@ msgstr "" "{xml,sgml}." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2213 +#: C/index.docbook:2219 msgid "A new symbol does not appear in the docs." msgstr "Nový symbol se neobjevil v dokumentaci." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2214 +#: C/index.docbook:2220 msgid "" "Is the doc-comment properly formatted. Check for spelling mistakes in the " "begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable " @@ -3730,12 +3739,12 @@ msgstr "" "<package>-sections.txt ve veřejném pododdíle." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2222 +#: C/index.docbook:2228 msgid "A type is missing from the class hierarchy." msgstr "V hierarchii třídy schází typ." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2223 +#: C/index.docbook:2229 msgid "" "If the type is listed in <package>.hierarchy but " "not in xml/tree_index.sgml then double check that the " @@ -3751,13 +3760,13 @@ msgstr "" "zobrazena." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2232 +#: C/index.docbook:2238 msgid "I get foldoc links for all gobject annotations." msgstr "" "Vytvořily se mi odkazy na složku s dokumentací pro všechny anotace k GObject" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2233 +#: C/index.docbook:2239 msgid "" "Check that xml/annotation-glossary.xml is xi:included " "from <package>-docs.{xml,sgml}." @@ -3766,13 +3775,13 @@ msgstr "" "pomocí xi:include z <package>-docs.{xml,sgml}." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2241 +#: C/index.docbook:2247 msgid "Parameter described in source code comment block but does not exist" msgstr "" "Parametr je v komentářovém bloku zdrojového kódu popsaný, ale neexistuje." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2242 +#: C/index.docbook:2248 msgid "" "Check if the prototype in the header has different parameter names as in the " "source." @@ -3781,12 +3790,12 @@ msgstr "" "než ve zdrojovém kódu." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2247 +#: C/index.docbook:2253 msgid "multiple \"IDs\" for constraint linkend: XYZ" msgstr "Více „ID“ pro tentýž cíl odkazu: XYZ" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2248 +#: C/index.docbook:2254 msgid "" "Symbol XYZ appears twice in <package>-sections.txt file." @@ -3795,7 +3804,7 @@ msgstr "" "objevuje dvakrát." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2251 +#: C/index.docbook:2257 msgid "" "Element typename in namespace '' encountered in para, but no template " "matches." @@ -3804,12 +3813,12 @@ msgstr "" "mu žádná šablona." #. (itstool) path: chapter/title -#: C/index.docbook:2258 +#: C/index.docbook:2264 msgid "Tools related to gtk-doc" msgstr "Nástroje související s GTK-Doc" #. (itstool) path: chapter/para -#: C/index.docbook:2260 +#: C/index.docbook:2266 msgid "" "GtkDocPlugin - a Trac " "GTK-Doc integration plugin, that adds API docs to a trac site and " @@ -3820,7 +3829,7 @@ msgstr "" "dokumentaci k API na sledovací web a integruje ji do vyhledávání." #. (itstool) path: chapter/para -#: C/index.docbook:2265 +#: C/index.docbook:2271 msgid "" "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " "tags in the API to determine the minimum required version." diff --git a/help/manual/cs/index.docbook b/help/manual/cs/index.docbook index 410e0cf..88912c9 100644 --- a/help/manual/cs/index.docbook +++ b/help/manual/cs/index.docbook @@ -35,18 +35,19 @@ - 1.28 - 24 Mar 2018 + 1.29 + 28 Aug 2018 ss - bug fixes + development + 1.28 24. března 2018 ss opravy chyb 1.27 7. prosince 2017 ss detailní vyladění portu v jazyce Python 1.26 11. srpen 2017 ss přenesení všech nástrojů z jazyků Perl/Bash do jazyka Python 1.25 21. březen 2016 ss opravy chyb, pročištění testů 1.24 29. května 2015 ss oprava chyby 1.23 17. květen 2015 ss oprava chyby - 1.22 07. květen 2015 ss oprava chyb, odstranění zastaralých věcí - 1.21 17. červenec 2014 ss oprava chyb, odstranění zastaralých věcí + 1.22 07. květen 2015 ss opravy chyb, odstranění zastaralých věcí + 1.21 17. červenec 2014 ss opravy chyb, odstranění zastaralých věcí 1.20 16. únor 2014 ss opravy chyb, podpora značkovacího jazyka, vylepšení stylů 1.19 05. červen 2013 ss opravy chyb 1.18 14. září 2011 ss opravy chyb, zrychlení, podpora značkovacího jazyka @@ -86,7 +87,12 @@ - Psaní dokumentace. 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). + + Writing the documentation. + + The author fills in the source files with the documentation for each + function, macro, structs or unions, etc. + @@ -123,9 +129,22 @@ O aplikaci GTK-Doc + + 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. + + (DOPLNIT) - (Historie, autoři, webové stránky, poštovní konference, licence, plány do budoucna, srovnání s ostatními podobnými systémy.) + + (authors, web pages, mailing list, license, future plans, + comparison with other similar systems.) + @@ -141,131 +160,529 @@ - Nastavení vašeho projektu + Project Setup + + + This Chapter describes the steps that are necessary to integrate GTK-Doc + into your project. The integration of GTK-Doc into a project includes the + following steps: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + - 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 prosté soubory Makefile nebo jiné sestavovací systémy budou popsány základní požadavky pro fungování s jinými postupy sestavování. + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. + Nastavení kostry dokumentace - 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ý. + + A common convention is to place documentation into a folder called + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. + - Ve výsledku to může vypadat nějak takto: Příklad struktury složek - + + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project + - +]]> + + - - Integrace s autoconf - - Velmi snadné! Stačí jen přidat jeden řádek do vašeho skriptu configure.ac. + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + + + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - Integrace s autoconf - -# check for gtk-doc -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - 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á GTK_DOC_CHECK na začátku řádku. Ponechání gtk-doc jako volitelného + + Integrace s automake + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + -# check for gtk-doc -m4_ifdef([GTK_DOC_CHECK], [ -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) -],[ -AM_CONDITIONAL([ENABLE_GTK_DOC], false) -]) +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ - + - První argument se používá ke kontrole gtkdocversion v průběhu konfigurace. Druhý, volitelný argument používá nástroj gtkdocize. Makro GTK_DOC_CHECK také přidává několik přepínačů pro configure: - - --with-html-dir=CESTA: cesta, kam se má dokumentace nainstalovat - --enable-gtk-doc: použít k sestavení dokumentace gtk-doc [výchozí je ne] - --enable-gtk-doc-html: sestavit dokumentaci ve formátu HTML [výchozí je ano] - --enable-gtk-doc-pdf: sestavit dokumentaci ve formátu PDF [výchozí je ne] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. - - GTK-Doc je standardně vypnuté! Nezapomeňte zadat přepínač „“ při dalším spuštění configure. Jinak se nainstaluje předgenerovaná dokumentace (která může mít význam pro uživatele, ale ne pro vývojáře). - + All settings have a comment above them that describes their purpose + and how to customize the setting. - Mimo to je ještě doporučeno, abyste měli ve skriptu configure.ac následující řádek. Umožní to gtkdocize automaticky nakopírovat definice maker pro GTK_DOC_CHECK do vašeho projektu. + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). - - Příprava pro gtkdocize - + All the tools support to list the supported + options. + + + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. + + + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + Integrace s autoconf + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - Po provedení změn v configure.ac aktualizujte soubor configure. To se dá udělat opětovným spuštěním autoreconf -i nebo autogen.sh. - +# optional: register gtk-doc in configure +GTK_DOC_CHECK([1.28]) +]]> + + + + + 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: + + + Integration with optional gtk-doc dependency + + + - - Integrace s automake + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - Jako první nakopírujte Makefile.am z podsložky examples ve složce gtkdoc-sources do složky s dokumentací API svého projektu (./docs/reference/<package>). Místní kopie by měla být k dispozici např. pod /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Pokud máte více balíčků s dokumentací, opakujte tento krok pro každý z nich. + + --with-html-dir=CESTA: cesta, kam se má dokumentace nainstalovat + --enable-gtk-doc: použít k sestavení dokumentace gtk-doc [výchozí je ne] + --enable-gtk-doc-html: sestavit dokumentaci ve formátu HTML [výchozí je ano] + --enable-gtk-doc-pdf: sestavit dokumentaci ve formátu PDF [výchozí je ne] + - Dalším krokem je úprava nastavení v Makefile.am. 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 . Všechny nástroje podporují pro vypsání podporovaných přepínačů. + + GTK-Doc je standardně vypnuté! Nezapomeňte zadat přepínač „“ při dalším spuštění configure. Jinak se nainstaluje předgenerovaná dokumentace (která může mít význam pro uživatele, ale ne pro vývojáře). + - + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - + + Integrace s autogen - - Integrace s autogen + + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + - Většina projektů má skript autogen.sh, 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 gtkdocize, který lze v takovémto skriptu využít. Měl by být spuštěný před autoheader, automake nebo autoconf. + + It should be run before autoreconf, autoheader, automake or autoconf. + - - Spuštění gtkdocize z autogen.sh - + + Spuštění gtkdocize z autogen.sh + gtkdocize || exit 1 - - + + - Když spustíte gtkdocize, tak nakopíruje do kořenové složky vašeho projektu (nebo složky určené přepínačem ) soubor gtk-doc.make. Navíc zkontroluje váš skript configure, jestli volá GTK_DOC_CHECK. Toto makro můžete použít k předání dalších parametrů do gtkdocize. + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - 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. gtkdocize nyní podporuje přepínač , 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 GTKDOCIZE_FLAGS, nebo nastavit jako druhý parametr v makru GTK_DOC_CHECK 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í). - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - Sestavení dokumentace + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - Po dokončení předchozích kroků nastal čas spustit sestavení. Nejdříve musíte znovu spustit autogen.sh. Pokud tento skript pro vás provádí nastavení, předejte mu přepínač . Jinak potom ručně spusťte configure s tímto přepínačem. - První make spustí vygenerování několika doplňujících souborů ve složkách doc. Podstatné jsou tyto: <package>.types, <package>-docs.xml (dříve .sgml) a <package>-sections.txt. - - Sestavení dokumentace - + + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + Po dokončení předchozích kroků nastal čas spustit sestavení. Nejdříve musíte znovu spustit autogen.sh. Pokud tento skript pro vás provádí nastavení, předejte mu přepínač . Jinak potom ručně spusťte configure s tímto přepínačem. + První make spustí vygenerování několika doplňujících souborů ve složkách doc. Podstatné jsou tyto: <package>.types, <package>-docs.xml (dříve .sgml) a <package>-sections.txt. + + Sestavení dokumentace + ./autogen.sh --enable-gtk-doc make - - - Nyní se můžete ve svém prohlížeči podívat na docs/reference/<package>/index.html. 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. + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - Integrace se systémem pro správu verzí + + Integrace se sestavovacím systémem 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: <balíček>.types, <balíček>-docs.xml (dříve .sgml), <balíček>-sections.txt a Makefile.am. - Soubory ze složek xml/ a html/ by neměly být zařazeny do správy verzí. A ani žádné soubory .stamp. + GTK-Doc nyní nabízí modul GtkDocConfig.cmake (a příslušný modul GtkDocConfigVersion.cmake). Ten poskytuje příkaz gtk_doc_add_module, který můžete nastavit ve svém souboru CMakeLists.txt. + + Následující příklad ukazuje, jak tento příkaz použít: Příklad použití GTK-Doc z CMake + +find_package(GtkDoc 1.25 REQUIRED) + +# Vytvoření cíle doc-libmeep. +gtk_doc_add_module( + libmeep ${CMAKE_SOURCE_DIR}/libmeep + XML meep-docs.xml + LIBRARIES libmeep +) + +# Sestavení doc-libmeep jako součásti výchozího cíle. Bez tohoto byste museli +# ručně spouštět něco jako `make doc-libmeep`, aby se dokumentace sestavila. +add_custom_target(documentation ALL DEPENDS doc-libmeep) + +# Instalace dokumentace. (Předpokládá to, že používáte modul CMake GNUInstallDirs +# ke správnému nastavení proměnné CMAKE_INSTALL_DOCDIR). +install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html + DESTINATION ${CMAKE_INSTALL_DOCDIR}) + + - + Integrace s prostými soubory Makefile nebo jinými sestavovacími systémy Když někdo nechce používat automake, a tím pádem gtk-doc.mak, bude muset volat nástroje gtkdoc ve správném pořadí ve vlastních souborech make (nebo jiných nástrojích). @@ -289,33 +706,13 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html Na výběr dalších potřebných voleb se musíte se podívat do Makefile.am a gtk-doc.mak. - - Integrace se sestavovacím systémem CMake - - GTK-Doc nyní nabízí modul GtkDocConfig.cmake (a příslušný modul GtkDocConfigVersion.cmake). Ten poskytuje příkaz gtk_doc_add_module, který můžete nastavit ve svém souboru CMakeLists.txt. - - Následující příklad ukazuje, jak tento příkaz použít: Příklad použití GTK-Doc z CMake - -find_package(GtkDoc 1.25 REQUIRED) - -# Vytvoření cíle doc-libmeep. -gtk_doc_add_module( - libmeep ${CMAKE_SOURCE_DIR}/libmeep - XML meep-docs.xml - LIBRARIES libmeep -) + + Integrace se systémem pro správu verzí -# Sestavení doc-libmeep jako součásti výchozího cíle. Bez tohoto byste museli -# ručně spouštět něco jako `make doc-libmeep`, aby se dokumentace sestavila. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + Podle nepsaných pravidel byste soubory, které upravujete, měli udržovat ve správě verzí. U typických projektů to jsou tyto soubory: <balíček>.types, <balíček>-docs.xml (dříve .sgml), <balíček>-sections.txt a Makefile.am. + Soubory ze složek xml/ a html/ by neměly být zařazeny do správy verzí. A ani žádné soubory .stamp. + -# Instalace dokumentace. (Předpokládá to, že používáte modul CMake GNUInstallDirs -# ke správnému nastavení proměnné CMAKE_INSTALL_DOCDIR). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) - - - @@ -323,19 +720,18 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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ářů. - - Umístění dokumentace - Dříve musela být většina dokumentace doplněná do souborů umístěných ve složce tmpl. Následkem toho bylo, že informace byly často neaktualizované a soubory měli tendenci způsobovat konflikty v systémech pro správu verzí. - 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. - - - Skener zvládá dobře většinu hlavičkových souborů C. V případě, že od něj obdržíte varování, které vypadá jako speciální případ, můžete GTK-Doc poradit, aby jej přeskakovala. Komentářový blok GTK-Doc - + + 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. + GTK-Doc comment block + - +]]> + + Omezení @@ -449,7 +845,17 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Více příkladů k podporovaným značkám Markdown můžete najít v Referenční příručce k syntaxi Markdown pro dokumentaci GTK+. - 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. + + 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. + @@ -990,7 +1396,7 @@ int main(int argc, char *argv[]) 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 xxx_get_type spolu s jejich include v souboru <balíček>.types. - Příklad úryvku ze souboru typů + Example <package>.types file #include <gtk/gtk.h> @@ -1171,27 +1577,37 @@ endif GTK-Doc 1.25 - Soubory Makefile dodávané s touto verzí generují do xml/gtkdocentities.ent 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. Používání předgenerovaných entit - -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + + The makefiles shipped with this version generate an entity file at xml/gtkdocentities.ent, + 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. + Use pre-generated entities + + + %gtkdocentities; -]> -<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> - <bookinfo> - <title>&Referenční příručka k package_name;</title> - <releaseinfo> - for &package_string;. - Nejnovější verzi této dokumentace můžete najít on-line na - <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>. - </releaseinfo> - </bookinfo> - - +]> + + + &package_name; Reference Manual + + for &package_string;. + The latest version of this documentation can be found on-line at + http://[SERVER]/&package_name;/. + + +]]> + + diff --git a/help/manual/de/de.po b/help/manual/de/de.po index 81e8b4a..2504037 100644 --- a/help/manual/de/de.po +++ b/help/manual/de/de.po @@ -6,15 +6,15 @@ msgid "" msgstr "" "Project-Id-Version: gtk-doc help master\n" -"POT-Creation-Date: 2018-01-12 10:35+0000\n" -"PO-Revision-Date: 2018-01-14 13:39+0100\n" +"POT-Creation-Date: 2018-05-20 18:37+0000\n" +"PO-Revision-Date: 2018-08-09 18:25+0200\n" "Last-Translator: Tim Sabsch \n" "Language-Team: German \n" "Language: de\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" -"X-Generator: Poedit 2.0.5\n" +"X-Generator: Poedit 2.0.9\n" #. Put one translator per line, in the form NAME , YEAR1, YEAR2 msgctxt "_" @@ -125,15 +125,24 @@ msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:83 msgid "" -"1.27.1 07 Dec 2017 ss1.28.1 24 Mar 2018 ss development" msgstr "" -"1.27.1 07. Dezember 2017 " -"ss Entwicklerversion" +"1.28.1 24. März 2018 ss Entwicklerversion" #. (itstool) path: revhistory/revision #: C/index.docbook:89 msgid "" +"1.28 24 Mar 2018 ss bug fixes" +msgstr "" +"1.28 24. März 2018 ss Fehlerbehebungen" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:95 +msgid "" "1.27 07 Dec 2017 ss fine tuning of the python port" msgstr "" @@ -142,7 +151,7 @@ msgstr "" "Portierung" #. (itstool) path: revhistory/revision -#: C/index.docbook:95 +#: C/index.docbook:101 msgid "" "1.26 11 Aug 2017 ss port all tools from perl/bash to python" #. (itstool) path: revhistory/revision -#: C/index.docbook:101 +#: C/index.docbook:107 msgid "" "1.25 21 March 2016 ss bug fixes, test cleanups" @@ -162,7 +171,7 @@ msgstr "" "authorinitials> Fehlerbehebungen, Test-Cleanups" #. (itstool) path: revhistory/revision -#: C/index.docbook:107 +#: C/index.docbook:113 msgid "" "1.24 29 May 2015 ss bug fix" @@ -171,7 +180,7 @@ msgstr "" "authorinitials> Fehlerbehebungen" #. (itstool) path: revhistory/revision -#: C/index.docbook:113 +#: C/index.docbook:119 msgid "" "1.23 17 May 2015 ss bug fix" @@ -180,7 +189,7 @@ msgstr "" "authorinitials> Fehlerbehebungen" #. (itstool) path: revhistory/revision -#: C/index.docbook:119 +#: C/index.docbook:125 msgid "" "1.22 07 May 2015 ss bug fixes, dropping deprecated features" #. (itstool) path: revhistory/revision -#: C/index.docbook:125 +#: C/index.docbook:131 msgid "" "1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" #. (itstool) path: revhistory/revision -#: C/index.docbook:131 +#: C/index.docbook:137 msgid "" "1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" #. (itstool) path: revhistory/revision -#: C/index.docbook:137 +#: C/index.docbook:143 msgid "" "1.19 05 Jun 2013 ss bug fixes" @@ -222,7 +231,7 @@ msgstr "" "authorinitials> Fehlerbehebungen" #. (itstool) path: revhistory/revision -#: C/index.docbook:143 +#: C/index.docbook:149 msgid "" "1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" @@ -232,7 +241,7 @@ msgstr "" "Geschwindigkeit, Unterstützung für markdown" #. (itstool) path: revhistory/revision -#: C/index.docbook:149 +#: C/index.docbook:155 msgid "" "1.17 26 Feb 2011 sk urgent bug fix update" @@ -242,7 +251,7 @@ msgstr "" "Aktualisierung" #. (itstool) path: revhistory/revision -#: C/index.docbook:155 +#: C/index.docbook:161 msgid "" "1.16 14 Jan 2011 sk bugfixes, layout improvements" @@ -251,7 +260,7 @@ msgstr "" "authorinitials> Bugfixes, Layoutverbesserungen" #. (itstool) path: revhistory/revision -#: C/index.docbook:161 +#: C/index.docbook:167 msgid "" "1.15 21 May 2010 sk bug and regression fixes" @@ -260,7 +269,7 @@ msgstr "" "authorinitials> Bug- und Regressionsfixes" #. (itstool) path: revhistory/revision -#: C/index.docbook:167 +#: C/index.docbook:173 msgid "" "1.14 28 March 2010 sk bugfixes and performance improvements" @@ -269,7 +278,7 @@ msgstr "" "authorinitials> Bugfixes und Leistungsverbesserungen" #. (itstool) path: revhistory/revision -#: C/index.docbook:173 +#: C/index.docbook:179 msgid "" "1.13 18 December 2009 " "sk broken tarball update" #. (itstool) path: revhistory/revision -#: C/index.docbook:179 +#: C/index.docbook:185 msgid "" "1.12 18 December 2009 " "sk new tool features and " @@ -291,7 +300,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:185 +#: C/index.docbook:191 msgid "" "1.11 16 November 2008 " "mal GNOME doc-utils migration" #. (itstool) path: chapter/title -#: C/index.docbook:198 +#: C/index.docbook:204 msgid "Introduction" msgstr "Einführung" #. (itstool) path: chapter/para -#: C/index.docbook:200 +#: C/index.docbook:206 msgid "" "This chapter introduces GTK-Doc and gives an overview of what it is and how " "it is used." @@ -316,12 +325,12 @@ msgstr "" "es sich dabei handelt und wie es benutzt wird." #. (itstool) path: sect1/title -#: C/index.docbook:206 +#: C/index.docbook:212 msgid "What is GTK-Doc?" msgstr "Was ist GTK-Doc?" #. (itstool) path: sect1/para -#: C/index.docbook:208 +#: C/index.docbook:214 msgid "" "GTK-Doc is used to document C code. It is typically used to document the " "public API of libraries, such as the GTK+ and GNOME libraries. But it can " @@ -333,12 +342,12 @@ msgstr "" "Anwendungscode verwendet werden." #. (itstool) path: sect1/title -#: C/index.docbook:216 +#: C/index.docbook:222 msgid "How Does GTK-Doc Work?" msgstr "Wie funktioniert GTK-Doc?" #. (itstool) path: sect1/para -#: C/index.docbook:218 +#: C/index.docbook:224 msgid "" "GTK-Doc works by using documentation of functions placed inside the source " "files in specially-formatted comment blocks, or documentation added to the " @@ -354,7 +363,7 @@ msgstr "" "keine Ausgaben für statische Funktionen." #. (itstool) path: sect1/para -#: C/index.docbook:225 +#: C/index.docbook:231 msgid "" "GTK-Doc consists of a number of python scripts, each performing a different " "step in the process." @@ -363,12 +372,12 @@ msgstr "" "bestimmten Schritt in dem Prozess ausführt." #. (itstool) path: sect1/para -#: C/index.docbook:230 +#: C/index.docbook:236 msgid "There are 5 main steps in the process:" msgstr "Dieser Vorgang umfasst fünf Hauptschritte:" #. (itstool) path: listitem/para -#: C/index.docbook:237 +#: C/index.docbook:243 msgid "" "Writing the documentation. The author fills in the " "source files with the documentation for each function, macro, union etc. (In " @@ -381,7 +390,7 @@ msgstr "" "eingegeben. Dies wird nicht mehr empfohlen." #. (itstool) path: listitem/para -#: C/index.docbook:247 +#: C/index.docbook:253 msgid "" "Gathering information about the code. " "gtkdoc-scan scans the header files of the code " @@ -417,7 +426,7 @@ msgstr "" "<module>-overrides.txt platzieren." #. (itstool) path: listitem/para -#: C/index.docbook:264 +#: C/index.docbook:270 msgid "" "gtkdoc-scangobj can also be used to dynamically " "query a library about any GObject subclasses it exports. It saves " @@ -431,7 +440,7 @@ msgstr "" "und -Signale, die es bietet." #. (itstool) path: listitem/para -#: C/index.docbook:270 +#: C/index.docbook:276 msgid "" "gtkdoc-scanobj should not be used anymore. It was " "needed in the past when GObject was still GtkObject inside gtk+." @@ -441,7 +450,7 @@ msgstr "" "GtkObject innerhalb von gtk+ war." #. (itstool) path: listitem/para -#: C/index.docbook:277 +#: C/index.docbook:283 msgid "" "Generating the XML and HTML/PDF. gtkdoc-" "mkdb turns the template files into XML files in the gtkdoc-mkhtml turns the XML files into HTML files " "in the html/ subdirectory. Likewise " @@ -472,7 +481,7 @@ msgstr "" "in ein PDF-Dokument namens <package>.pdf." #. (itstool) path: listitem/para -#: C/index.docbook:292 +#: C/index.docbook:298 msgid "" "Files in xml/ and html/ directories are always overwritten. One " @@ -483,7 +492,7 @@ msgstr "" "sollte diese direkt bearbeiten." #. (itstool) path: listitem/para -#: C/index.docbook:300 +#: C/index.docbook:306 msgid "" "Fixing up cross-references between documents. After " "installing the HTML files, gtkdoc-fixxref can be " @@ -505,17 +514,17 @@ msgstr "" "lokale Verweise umzuwandeln (wo diese Dokumente installiert werden)." #. (itstool) path: sect1/title -#: C/index.docbook:318 +#: C/index.docbook:324 msgid "Getting GTK-Doc" msgstr "GTK-Doc bekommen" #. (itstool) path: sect2/title -#: C/index.docbook:321 +#: C/index.docbook:327 msgid "Requirements" msgstr "Erfordernisse" #. (itstool) path: sect2/para -#: C/index.docbook:322 +#: C/index.docbook:328 msgid "" "python 2/3 - the main scripts are written in python." msgstr "" @@ -523,7 +532,7 @@ msgstr "" "geschrieben." #. (itstool) path: sect2/para -#: C/index.docbook:325 +#: C/index.docbook:331 msgid "" "xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" @@ -532,7 +541,7 @@ msgstr "" "\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/" #. (itstool) path: sect2/para -#: C/index.docbook:329 +#: C/index.docbook:335 msgid "" "docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" #. (itstool) path: sect2/para -#: C/index.docbook:333 +#: C/index.docbook:339 msgid "" "One of source-highlight, highlight " "or vim - optional - used for syntax highlighting of " @@ -553,17 +562,17 @@ msgstr "" "vim - optional - für Syntax-Hervorhebung von Beispielen" #. (itstool) path: sect1/title -#: C/index.docbook:341 +#: C/index.docbook:347 msgid "About GTK-Doc" msgstr "Info zu GTK-Doc" #. (itstool) path: sect1/para -#: C/index.docbook:343 C/index.docbook:357 +#: C/index.docbook:349 C/index.docbook:363 msgid "(FIXME)" msgstr "(FIXME)" #. (itstool) path: sect1/para -#: C/index.docbook:347 +#: C/index.docbook:353 msgid "" "(History, authors, web pages, mailing list, license, future plans, " "comparison with other similar systems.)" @@ -572,22 +581,22 @@ msgstr "" "Vergleich mit ähnlichen Systemen)" #. (itstool) path: sect1/title -#: C/index.docbook:355 +#: C/index.docbook:361 msgid "About this Manual" msgstr "Über dieses Handbuch" #. (itstool) path: sect1/para -#: C/index.docbook:361 +#: C/index.docbook:367 msgid "(who it is meant for, where you can get it, license)" msgstr "(wofür es bestimmt ist, wo Sie es erhalten können, Lizenz)" #. (itstool) path: chapter/title -#: C/index.docbook:370 +#: C/index.docbook:376 msgid "Setting up your project" msgstr "Einrichten Ihres Projekts" #. (itstool) path: chapter/para -#: C/index.docbook:372 +#: C/index.docbook:378 msgid "" "The next sections describe what steps to perform to integrate GTK-Doc into " "your project. Theses sections assume we work on a project called 'meep'. " @@ -607,12 +616,12 @@ msgstr "" "Erstellungsumgebung." #. (itstool) path: sect1/title -#: C/index.docbook:383 +#: C/index.docbook:389 msgid "Setting up a skeleton documentation" msgstr "Einrichten des Grundgerüsts der Dokumentation" #. (itstool) path: sect1/para -#: C/index.docbook:385 +#: C/index.docbook:391 msgid "" "Under your top-level project directory create folders called docs/reference " "(this way you can also have docs/help for end-user documentation). It is " @@ -627,12 +636,12 @@ msgstr "" "notwendig." #. (itstool) path: example/title -#: C/index.docbook:394 +#: C/index.docbook:400 msgid "Example directory structure" msgstr "Beispiel für die Ordnerstruktur" #. (itstool) path: example/programlisting -#: C/index.docbook:395 +#: C/index.docbook:401 #, no-wrap msgid "" "\n" @@ -656,18 +665,18 @@ msgstr "" " meeper/\n" #. (itstool) path: sect1/para -#: C/index.docbook:392 +#: C/index.docbook:398 msgid "This can then look as shown below: <_:example-1/>" msgstr "Dies kann dann wie nachstehend angezeigt aussehen: <_:example-1/>" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:410 C/index.docbook:417 +#: C/index.docbook:416 C/index.docbook:423 msgid "Integration with autoconf" msgstr "Integration in autoconf" #. (itstool) path: sect1/para -#: C/index.docbook:412 +#: C/index.docbook:418 msgid "" "Very easy! Just add one line to your configure.ac " "script." @@ -676,7 +685,7 @@ msgstr "" "filename>-Skript hinzu." #. (itstool) path: example/programlisting -#: C/index.docbook:418 +#: C/index.docbook:424 #, no-wrap msgid "" "\n" @@ -688,12 +697,12 @@ msgstr "" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" #. (itstool) path: example/title -#: C/index.docbook:430 +#: C/index.docbook:436 msgid "Keep gtk-doc optional" msgstr "Halten Sie gtk-doc optional" #. (itstool) path: example/programlisting -#: C/index.docbook:431 +#: C/index.docbook:437 #, no-wrap msgid "" "\n" @@ -713,7 +722,7 @@ msgstr "" "])\n" #. (itstool) path: sect1/para -#: C/index.docbook:425 +#: C/index.docbook:431 msgid "" "This will require all developers to have gtk-doc installed. If it is okay " "for your project to have optional api-doc build setup, you can solve this as " @@ -727,7 +736,7 @@ msgstr "" "Zeile sucht. <_:example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:442 +#: C/index.docbook:448 msgid "" "The first argument is used to check for the gtkdocversion at configure time. " "The 2nd, optional argument is used by gtkdocize. " @@ -741,19 +750,19 @@ msgstr "" "hinzu:" #. (itstool) path: listitem/para -#: C/index.docbook:448 +#: C/index.docbook:454 msgid "--with-html-dir=PATH : path to installed docs" msgstr "--with-html-dir=PATH : Pfad zur installierten Dokumentation" #. (itstool) path: listitem/para -#: C/index.docbook:449 +#: C/index.docbook:455 msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "" "--enable-gtk-doc : gtk-doc zur Erstellung der Dokumentation verwenden " "[Vorgabe=no]" #. (itstool) path: listitem/para -#: C/index.docbook:450 +#: C/index.docbook:456 msgid "" "--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" @@ -761,14 +770,14 @@ msgstr "" "[Vorgabe=yes]" #. (itstool) path: listitem/para -#: C/index.docbook:451 +#: C/index.docbook:457 msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" msgstr "" "--enable-gtk-doc-pdf : Erstellung der Dokumentation im PDF-Format " "[Vorgabe=no]" #. (itstool) path: important/para -#: C/index.docbook:455 +#: C/index.docbook:461 msgid "" "GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " @@ -782,7 +791,7 @@ msgstr "" "aber nicht für Entwickler." #. (itstool) path: sect1/para -#: C/index.docbook:463 +#: C/index.docbook:469 msgid "" "Furthermore it is recommended that you have the following line inside your " "configure.ac script. This allows " @@ -795,12 +804,12 @@ msgstr "" "GTK_DOC_CHECK in Ihr Projekt." #. (itstool) path: example/title -#: C/index.docbook:471 +#: C/index.docbook:477 msgid "Preparation for gtkdocize" msgstr "Vorbereitung für gtkdocize" #. (itstool) path: example/programlisting -#: C/index.docbook:472 +#: C/index.docbook:478 #, no-wrap msgid "" "\n" @@ -810,7 +819,7 @@ msgstr "" "AC_CONFIG_MACRO_DIR(m4)\n" #. (itstool) path: sect1/para -#: C/index.docbook:477 +#: C/index.docbook:483 msgid "" "After all changes to configure.ac are made, update the " "configure file. This can be done by re-running " @@ -822,12 +831,12 @@ msgstr "" "autogen.sh." #. (itstool) path: sect1/title -#: C/index.docbook:485 +#: C/index.docbook:491 msgid "Integration with automake" msgstr "Integration in automake" #. (itstool) path: sect1/para -#: C/index.docbook:487 +#: C/index.docbook:493 msgid "" "First copy the Makefile.am from the examples sub directory of the Makefile.am. All the settings have a comment above that describes their " @@ -866,12 +875,12 @@ msgstr "" "unterstützten Parameter." #. (itstool) path: sect1/title -#: C/index.docbook:512 +#: C/index.docbook:518 msgid "Integration with autogen" msgstr "Integration in autogen" #. (itstool) path: sect1/para -#: C/index.docbook:514 +#: C/index.docbook:520 msgid "" "Most projects will have an autogen.sh script to setup " "the build infrastructure after a checkout from version control system (such " @@ -887,12 +896,12 @@ msgstr "" "oder autoconf ausgeführt werden." #. (itstool) path: example/title -#: C/index.docbook:523 +#: C/index.docbook:529 msgid "Running gtkdocize from autogen.sh" msgstr "Ausführen von gtkdocize durch autogen.sh" #. (itstool) path: example/programlisting -#: C/index.docbook:524 +#: C/index.docbook:530 #, no-wrap msgid "" "\n" @@ -902,7 +911,7 @@ msgstr "" "gtkdocize || exit 1\n" #. (itstool) path: sect1/para -#: C/index.docbook:530 +#: C/index.docbook:536 msgid "" "When running gtkdocize it copies gtk-" "doc.make to your project root (or any directory specified by the " @@ -918,7 +927,7 @@ msgstr "" "Parameter an gtkdocize zu übergeben." #. (itstool) path: sect1/para -#: C/index.docbook:539 +#: C/index.docbook:545 msgid "" "Historically GTK-Doc was generating template files where developers entered " "the docs. This turned out to be not so good (e.g. the need for having " @@ -953,12 +962,12 @@ msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:556 C/index.docbook:573 +#: C/index.docbook:562 C/index.docbook:579 msgid "Running the doc build" msgstr "Erstellung der Dokumentation" #. (itstool) path: sect1/para -#: C/index.docbook:558 +#: C/index.docbook:564 msgid "" "After the previous steps it's time to run the build. First we need to rerun " "autogen.sh. If this script runs configure for you, then " @@ -973,7 +982,7 @@ msgstr "" "Option." #. (itstool) path: sect1/para -#: C/index.docbook:565 +#: C/index.docbook:571 msgid "" "The first make run generates several additional files in the doc-" "directories. The important ones are: <package>.types<package>-sections.txt." #. (itstool) path: example/programlisting -#: C/index.docbook:574 +#: C/index.docbook:580 #, no-wrap msgid "" "\n" @@ -998,7 +1007,7 @@ msgstr "" "make\n" #. (itstool) path: sect1/para -#: C/index.docbook:580 +#: C/index.docbook:586 msgid "" "Now you can point your browser to docs/reference/<package>/" "index.html. Yes, it's a bit disappointing still. But hang-on, " @@ -1010,12 +1019,12 @@ msgstr "" "Seiten mit Leben füllen können." #. (itstool) path: sect1/title -#: C/index.docbook:588 +#: C/index.docbook:594 msgid "Integration with version control systems" msgstr "Integration in Versionsverwaltungssysteme" #. (itstool) path: sect1/para -#: C/index.docbook:590 +#: C/index.docbook:596 msgid "" "As a rule of thumb, it's the files you edit which should go under version " "control. For typical projects it's these files: <package>." @@ -1030,7 +1039,7 @@ msgstr "" "sections.txt, Makefile.am." #. (itstool) path: sect1/para -#: C/index.docbook:598 +#: C/index.docbook:604 msgid "" "Files in the xml/ and html/ " "directories should not go under version control. Neither should any of the " @@ -1041,12 +1050,12 @@ msgstr "" "keine der .stamp-Dateien." #. (itstool) path: sect1/title -#: C/index.docbook:606 +#: C/index.docbook:612 msgid "Integration with plain makefiles or other build systems" msgstr "Integration in Klartext-Makefiles oder andere Erstellungssysteme" #. (itstool) path: sect1/para -#: C/index.docbook:608 +#: C/index.docbook:614 msgid "" "In the case one does not want to use automake and therefore gtk-" "doc.mak one will need to call the gtkdoc tools in the right order " @@ -1057,12 +1066,12 @@ msgstr "" "(oder andere Werkzeuge) in der richtigen Reihenfolge aufrufen." #. (itstool) path: example/title -#: C/index.docbook:615 +#: C/index.docbook:621 msgid "Documentation build steps" msgstr "Schritte zur Erstellung der Dokumentation" #. (itstool) path: example/programlisting -#: C/index.docbook:616 +#: C/index.docbook:622 #, no-wrap msgid "" "\n" @@ -1088,7 +1097,7 @@ msgstr "" "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" #. (itstool) path: sect1/para -#: C/index.docbook:630 +#: C/index.docbook:636 msgid "" "One will need to look at the Makefile.am and " "gtk-doc.mak to pick the extra options needed." @@ -1097,12 +1106,12 @@ msgstr "" "filename> anschauen, um die zusätzlich notwendigen Optionen herauszusuchen." #. (itstool) path: sect1/title -#: C/index.docbook:637 +#: C/index.docbook:643 msgid "Integration with CMake build systems" msgstr "Integration in CMake-Erstellungssysteme" #. (itstool) path: sect1/para -#: C/index.docbook:639 +#: C/index.docbook:645 msgid "" "GTK-Doc now provides a GtkDocConfig.cmake module (and " "the corresponding GtkDocConfigVersion.cmake module). " @@ -1116,12 +1125,12 @@ msgstr "" "integrieren können." #. (itstool) path: example/title -#: C/index.docbook:649 +#: C/index.docbook:655 msgid "Example of using GTK-Doc from CMake" msgstr "Beispiel zur Verwendung von GTK-Doc mit CMake" #. (itstool) path: example/programlisting -#: C/index.docbook:650 +#: C/index.docbook:656 #, no-wrap msgid "" "\n" @@ -1163,19 +1172,19 @@ msgstr "" " DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" #. (itstool) path: sect1/para -#: C/index.docbook:647 +#: C/index.docbook:653 msgid "The following example shows how to use this command. <_:example-1/>" msgstr "" "Das folgende Beispiel zeigt, wie dieser Befehl eingesetzt wird. <_:example-1/" ">" #. (itstool) path: chapter/title -#: C/index.docbook:675 +#: C/index.docbook:681 msgid "Documenting the code" msgstr "Dokumentieren des Codes" #. (itstool) path: chapter/para -#: C/index.docbook:677 +#: C/index.docbook:683 msgid "" "GTK-Doc uses source code comment with a special syntax for code " "documentation. Further it retrieves information about your project structure " @@ -1188,12 +1197,12 @@ msgstr "" "Informationen über die Syntax der Kommentare." #. (itstool) path: note/title -#: C/index.docbook:685 +#: C/index.docbook:691 msgid "Documentation placement" msgstr "Platzierung der Dokumentation" #. (itstool) path: note/para -#: C/index.docbook:686 +#: C/index.docbook:692 msgid "" "In the past most documentation had to be filled into files residing inside " "the tmpl directory. This has the disadvantages that the " @@ -1206,7 +1215,7 @@ msgstr "" "Konflikte mit Versionsverwaltungssystemen verursachen kann." #. (itstool) path: note/para -#: C/index.docbook:692 +#: C/index.docbook:698 msgid "" "The avoid the aforementioned problems we suggest putting the documentation " "inside the sources. This manual will only describe this way of documenting " @@ -1217,12 +1226,12 @@ msgstr "" "ausschließlich dieser Weg des Dokumentierens des Quellcodes beschrieben." #. (itstool) path: example/title -#: C/index.docbook:703 C/index.docbook:729 +#: C/index.docbook:709 C/index.docbook:735 msgid "GTK-Doc comment block" msgstr "GTK-Doc-Kommentarblock" #. (itstool) path: example/programlisting -#: C/index.docbook:704 +#: C/index.docbook:710 #, no-wrap msgid "" "\n" @@ -1236,7 +1245,7 @@ msgstr "" "#endif\n" #. (itstool) path: chapter/para -#: C/index.docbook:699 +#: C/index.docbook:705 msgid "" "The scanner can handle the majority of C headers fine. In the case of " "receiving warnings from the scanner that look like a special case, one can " @@ -1247,12 +1256,12 @@ msgstr "" "anweisen diese zu überspringen. <_:example-1/>" #. (itstool) path: note/title -#: C/index.docbook:713 +#: C/index.docbook:719 msgid "Limitations" msgstr "Einschränkungen" #. (itstool) path: note/para -#: C/index.docbook:714 +#: C/index.docbook:720 msgid "" "Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but " "not #if !defined(__GTK_DOC_IGNORE__) or other combinations." @@ -1262,12 +1271,12 @@ msgstr "" "andere Kombinationen." #. (itstool) path: sect1/title -#: C/index.docbook:724 +#: C/index.docbook:730 msgid "Documentation comments" msgstr "Kommentare zur Dokumentation" #. (itstool) path: example/programlisting -#: C/index.docbook:730 +#: C/index.docbook:736 #, no-wrap msgid "" "\n" @@ -1283,7 +1292,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:726 +#: C/index.docbook:732 msgid "" "A multiline comment that starts with an additional '*' marks a documentation " "block that will be processed by the GTK-Doc tools. <_:example-1/>" @@ -1293,7 +1302,7 @@ msgstr "" "example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:739 +#: C/index.docbook:745 msgid "" "The 'identifier' is one line with the name of the item the comment is " "related to. The syntax differs a little depending on the item. (TODO add " @@ -1304,7 +1313,7 @@ msgstr "" "variieren." #. (itstool) path: sect1/para -#: C/index.docbook:745 +#: C/index.docbook:751 msgid "" "The 'documentation' block is also different for each symbol type. Symbol " "types that get parameters such as functions or macros have the parameter " @@ -1325,7 +1334,7 @@ msgstr "" "dahinter. Dies ist in vorformatiertem Text nützlich (Code-Auflistungen)." #. (itstool) path: listitem/para -#: C/index.docbook:762 +#: C/index.docbook:768 msgid "" "What it is: The name for a class or function can sometimes be misleading for " "people coming from a different background." @@ -1334,7 +1343,7 @@ msgstr "" "führend sein für Personen, die einen anderen Hintergrund haben." #. (itstool) path: listitem/para -#: C/index.docbook:768 +#: C/index.docbook:774 msgid "" "What it does: Tell about common uses. Put it in relation with the other API." msgstr "" @@ -1342,20 +1351,20 @@ msgstr "" "Verhältnis mit der anderen API." #. (itstool) path: tip/para -#: C/index.docbook:758 +#: C/index.docbook:764 msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" msgstr "" "Beim Dokumentieren von Code beschreiben Sie zwei Aspekte: <_:itemizedlist-1/>" #. (itstool) path: listitem/para -#: C/index.docbook:783 +#: C/index.docbook:789 msgid "Use function() to refer to functions or macros which take arguments." msgstr "" "Verwenden Sie function(), um einen Bezug zu Funktionen oder Makros " "herzustellen, die Argumente akzeptieren." #. (itstool) path: listitem/para -#: C/index.docbook:788 +#: C/index.docbook:794 msgid "" "Use @param to refer to parameters. Also use this when referring to " "parameters of other functions, related to the one being described." @@ -1365,14 +1374,14 @@ msgstr "" "bezogen auf jene, die Sie gerade beschreiben." #. (itstool) path: listitem/para -#: C/index.docbook:794 +#: C/index.docbook:800 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "" "Benutzen Sie %constant, um einen Bezug auf eine Konstante herzustellen, z.B. " "%G_TRAVERSE_LEAFS." #. (itstool) path: listitem/para -#: C/index.docbook:799 +#: C/index.docbook:805 msgid "" "Use #symbol to refer to other types of symbol, e.g. structs and enums and " "macros which don't take arguments." @@ -1381,18 +1390,18 @@ msgstr "" "»structs« und »enums« und Makros, die keine Argumente benötigen." #. (itstool) path: listitem/para -#: C/index.docbook:805 +#: C/index.docbook:811 msgid "Use #Object::signal to refer to a GObject signal." -msgstr "Verwenden Sie #Object::signal, um auf ein GObject-Signal zu verweisen" +msgstr "Verwenden Sie #Object::signal, um auf ein GObject-Signal zu verweisen." #. (itstool) path: listitem/para -#: C/index.docbook:810 +#: C/index.docbook:816 msgid "Use #Object:property to refer to a GObject property." msgstr "" "Verwenden Sie #Object:property, um auf eine GObject-Eigenschaft zu verweisen." #. (itstool) path: listitem/para -#: C/index.docbook:815 +#: C/index.docbook:821 msgid "" "Use #Struct.field to refer to a field inside a structure and #GObjectClass." "foo_bar() to refer to a vmethod." @@ -1401,7 +1410,7 @@ msgstr "" "verweisen und #GObjectClass.foo_bar() für eine vmethod." #. (itstool) path: sect1/para -#: C/index.docbook:777 +#: C/index.docbook:783 msgid "" "One advantage of hyper-text over plain-text is the ability to have links in " "the document. Writing the correct markup for a link can be tedious though. " @@ -1415,7 +1424,7 @@ msgstr "" "itemizedlist-1/>" #. (itstool) path: tip/para -#: C/index.docbook:824 +#: C/index.docbook:830 msgid "" "If you need to use the special characters '<', '>', '()', '@', '%', or " "'#' in your documentation without GTK-Doc changing them you can use the XML " @@ -1430,7 +1439,7 @@ msgstr "" "einem Backslash »\\« maskieren." #. (itstool) path: sect1/para -#: C/index.docbook:833 +#: C/index.docbook:839 msgid "" "DocBook can do more than just links. One can also have lists, examples, " "headings, and images. As of version 1.20, the preferred way is to use a " @@ -1448,7 +1457,7 @@ msgstr "" "Listenobjekte als Zeilen, die mit einem Gedankenstrich beginnen." #. (itstool) path: sect1/para -#: C/index.docbook:844 +#: C/index.docbook:850 msgid "" "While markdown is now preferred one can mix both. One limitation here is " "that one can use docbook xml within markdown, but markdown within docbook " @@ -1459,7 +1468,7 @@ msgstr "" "verwenden können, während Markdown in DocBook XML nicht unterstützt wird." #. (itstool) path: sect1/para -#: C/index.docbook:850 +#: C/index.docbook:856 msgid "" "In older GTK-Doc releases, if you need support for additional formatting, " "you would need to enable the usage of docbook XML tags inside doc-comments " @@ -1473,12 +1482,12 @@ msgstr "" "die Option (oder )." #. (itstool) path: example/title -#: C/index.docbook:859 +#: C/index.docbook:865 msgid "GTK-Doc comment block using Markdown" msgstr "GTK-Doc-Kommentarblock in Markdown-Syntax" #. (itstool) path: example/programlisting -#: C/index.docbook:860 +#: C/index.docbook:866 #, no-wrap msgid "" "\n" @@ -1554,7 +1563,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:899 +#: C/index.docbook:905 msgid "" "More examples of what markdown tags are supported can be found in the GTK+ Documentation Markdown Syntax Reference." #. (itstool) path: tip/para -#: C/index.docbook:905 +#: C/index.docbook:911 msgid "" "As already mentioned earlier GTK-Doc is for documenting public API. Thus one " "cannot write documentation for static symbols. Nevertheless it is good to " @@ -1586,12 +1595,12 @@ msgstr "" "Abschnittsdatei einzubauen." #. (itstool) path: sect1/title -#: C/index.docbook:919 +#: C/index.docbook:925 msgid "Documenting sections" msgstr "Dokumentieren von Abschnitten" #. (itstool) path: sect1/para -#: C/index.docbook:921 +#: C/index.docbook:927 msgid "" "Each section of the documentation contains information about one class or " "module. To introduce the component one can write a section block. The short " @@ -1604,12 +1613,12 @@ msgstr "" "Inhaltsverzeichnis verwendet. Alle @-Felder sind optional." #. (itstool) path: example/title -#: C/index.docbook:929 +#: C/index.docbook:935 msgid "Section comment block" msgstr "Abschnitts-Kommentarblock" #. (itstool) path: example/programlisting -#: C/index.docbook:930 +#: C/index.docbook:936 #, no-wrap msgid "" "\n" @@ -1641,12 +1650,12 @@ msgstr "" " */\n" #. (itstool) path: varlistentry/term -#: C/index.docbook:949 +#: C/index.docbook:955 msgid "SECTION:<name>" msgstr "SECTION:<name>" #. (itstool) path: listitem/para -#: C/index.docbook:951 +#: C/index.docbook:957 msgid "" "The name links the section documentation to the respective part in the " "<package>-sections.txt file. The name given here " @@ -1659,12 +1668,12 @@ msgstr "" "<package>-sections.txt entsprechen." #. (itstool) path: varlistentry/term -#: C/index.docbook:960 +#: C/index.docbook:966 msgid "@short_description" msgstr "@short_description" #. (itstool) path: listitem/para -#: C/index.docbook:962 +#: C/index.docbook:968 msgid "" "A one line description of the section, that later will appear after the " "links in the TOC and at the top of the section page." @@ -1673,12 +1682,12 @@ msgstr "" "im Inhaltsverzeichnis und oben in der Abschnittsseite erscheint." #. (itstool) path: varlistentry/term -#: C/index.docbook:969 +#: C/index.docbook:975 msgid "@title" msgstr "@title" #. (itstool) path: listitem/para -#: C/index.docbook:971 +#: C/index.docbook:977 msgid "" "The section title defaults to <name> from the SECTION declaration. It " "can be overridden with the @title field." @@ -1687,12 +1696,12 @@ msgstr "" "kann im Feld @title überschrieben werden." #. (itstool) path: varlistentry/term -#: C/index.docbook:978 +#: C/index.docbook:984 msgid "@section_id" msgstr "@section_id" #. (itstool) path: listitem/para -#: C/index.docbook:980 +#: C/index.docbook:986 msgid "" "Overrides the use of title as a section identifier. For GObjects the <" "title> is used as a section_id and for other sections it is <" @@ -1703,22 +1712,22 @@ msgstr "" "<MODUL>-<Titel>." #. (itstool) path: varlistentry/term -#: C/index.docbook:988 +#: C/index.docbook:994 msgid "@see_also" msgstr "@see_also" #. (itstool) path: listitem/para -#: C/index.docbook:990 +#: C/index.docbook:996 msgid "A list of symbols that are related to this section." msgstr "Eine Liste von Symbolen, welche sich auf diesen Abschnitt beziehen." #. (itstool) path: varlistentry/term -#: C/index.docbook:996 +#: C/index.docbook:1002 msgid "@stability" msgstr "@stability" #. (itstool) path: listitem/para -#: C/index.docbook:1003 +#: C/index.docbook:1009 msgid "" "Stable - The intention of a Stable interface is to enable arbitrary third " "parties to develop applications to these interfaces, release them, and have " @@ -1736,7 +1745,7 @@ msgstr "" "von stark berechtigten." #. (itstool) path: listitem/para -#: C/index.docbook:1015 +#: C/index.docbook:1021 msgid "" "Unstable - Unstable interfaces are experimental or transitional. They are " "typically used to give outside developers early access to new or rapidly " @@ -1752,7 +1761,7 @@ msgstr "" "Binärkompatibilität von einer minor-Freigabe zur nächsten gegeben." #. (itstool) path: listitem/para -#: C/index.docbook:1027 +#: C/index.docbook:1033 msgid "" "Private - An interface that can be used within the GNOME stack itself, but " "that is not documented for end-users. Such functions should only be used in " @@ -1763,7 +1772,7 @@ msgstr "" "nur auf spezifizierte und dokumentierte Weisen verwendet werden." #. (itstool) path: listitem/para -#: C/index.docbook:1036 +#: C/index.docbook:1042 msgid "" "Internal - An interface that is internal to a module and does not require " "end-user documentation. Functions that are undocumented are assumed to be " @@ -1774,7 +1783,7 @@ msgstr "" "intern angesehen." #. (itstool) path: listitem/para -#: C/index.docbook:998 +#: C/index.docbook:1004 msgid "" "An informal description of the stability level this API has. We recommend " "the use of one of these terms: <_:itemizedlist-1/>" @@ -1783,12 +1792,12 @@ msgstr "" "dafür einen der folgenden Begriffe: <_:itemizedlist-1/>" #. (itstool) path: varlistentry/term -#: C/index.docbook:1048 +#: C/index.docbook:1054 msgid "@include" msgstr "@include" #. (itstool) path: listitem/para -#: C/index.docbook:1050 +#: C/index.docbook:1056 msgid "" "The #include files to show in the section synopsis (a " "comma separated list), overriding the global value from the --default-stability argument to " @@ -1918,17 +1927,17 @@ msgstr "" "beschriebenen Werte." #. (itstool) path: variablelist/title -#: C/index.docbook:1128 +#: C/index.docbook:1134 msgid "Stability Tags" msgstr "Stabilitäts-Markierungen" #. (itstool) path: varlistentry/term -#: C/index.docbook:1129 +#: C/index.docbook:1135 msgid "Stability: Stable" msgstr "Stability: Stable" #. (itstool) path: listitem/para -#: C/index.docbook:1131 +#: C/index.docbook:1137 msgid "" "Mark the element as stable. This is for public APIs which are guaranteed to " "remain stable for all future minor releases of the project." @@ -1938,12 +1947,12 @@ msgstr "" "gewährleistet ist." #. (itstool) path: varlistentry/term -#: C/index.docbook:1138 +#: C/index.docbook:1144 msgid "Stability: Unstable" msgstr "Stability: Unstable" #. (itstool) path: listitem/para -#: C/index.docbook:1140 +#: C/index.docbook:1146 msgid "" "Mark the element as unstable. This is for public APIs which are released as " "a preview before being stabilised." @@ -1952,12 +1961,12 @@ msgstr "" "die als Vorschau vor der endgültigen Stabilisierung gedacht sind." #. (itstool) path: varlistentry/term -#: C/index.docbook:1146 +#: C/index.docbook:1152 msgid "Stability: Private" msgstr "Stability: Private" #. (itstool) path: listitem/para -#: C/index.docbook:1148 +#: C/index.docbook:1154 msgid "" "Mark the element as private. This is for interfaces which can be used by " "tightly coupled modules, but not by arbitrary third parties." @@ -1967,7 +1976,7 @@ msgstr "" "beliebigen Drittanbietern." #. (itstool) path: example/programlisting -#: C/index.docbook:1158 +#: C/index.docbook:1164 #, no-wrap msgid "" "\n" @@ -2006,12 +2015,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1178 C/index.docbook:1188 +#: C/index.docbook:1184 C/index.docbook:1194 msgid "Annotations" msgstr "Anmerkungen" #. (itstool) path: sect2/para -#: C/index.docbook:1180 +#: C/index.docbook:1186 msgid "" "Documentation blocks can contain annotation-tags. These tags will be " "rendered with tooltips describing their meaning. The tags are used by " @@ -2027,7 +2036,7 @@ msgstr "" "GObjectIntrospection/Annotations\" type=\"http\">Wiki." #. (itstool) path: example/programlisting -#: C/index.docbook:1189 +#: C/index.docbook:1195 #, no-wrap msgid "" "\n" @@ -2068,12 +2077,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1210 C/index.docbook:1239 +#: C/index.docbook:1216 C/index.docbook:1245 msgid "Function comment block" msgstr "Kommentarblock einer Funktion" #. (itstool) path: listitem/para -#: C/index.docbook:1216 +#: C/index.docbook:1222 msgid "" "Document whether returned objects, lists, strings, etc, should be freed/" "unrefed/released." @@ -2082,14 +2091,14 @@ msgstr "" "dereferenziert/freigegeben werden." #. (itstool) path: listitem/para -#: C/index.docbook:1222 +#: C/index.docbook:1228 msgid "Document whether parameters can be NULL, and what happens if they are." msgstr "" "Dokumentiert, ob Parameter NULL sein können, und was in diesem Fall " "geschieht." #. (itstool) path: listitem/para -#: C/index.docbook:1227 +#: C/index.docbook:1233 msgid "" "Mention interesting pre-conditions and post-conditions where appropriate." msgstr "" @@ -2097,12 +2106,12 @@ msgstr "" "es nützlich erscheint." #. (itstool) path: sect2/para -#: C/index.docbook:1212 C/index.docbook:1298 +#: C/index.docbook:1218 C/index.docbook:1304 msgid "Please remember to: <_:itemizedlist-1/>" msgstr "Bitte denken Sie an: <_:itemizedlist-1/>" #. (itstool) path: sect2/para -#: C/index.docbook:1234 +#: C/index.docbook:1240 msgid "" "Gtk-doc assumes all symbols (macros, functions) starting with '_' are " "private. They are treated like static functions." @@ -2111,7 +2120,7 @@ msgstr "" "beginnen, privat sind. Sie werden wie statische Funktionen behandelt." #. (itstool) path: example/programlisting -#: C/index.docbook:1240 +#: C/index.docbook:1246 #, no-wrap msgid "" "\n" @@ -2153,27 +2162,27 @@ msgstr "" " */\n" #. (itstool) path: variablelist/title -#: C/index.docbook:1261 +#: C/index.docbook:1267 msgid "Function tags" msgstr "Funktions-Markierungen" #. (itstool) path: varlistentry/term -#: C/index.docbook:1262 C/index.docbook:1469 +#: C/index.docbook:1268 C/index.docbook:1475 msgid "Returns:" msgstr "Returns:" #. (itstool) path: listitem/para -#: C/index.docbook:1264 +#: C/index.docbook:1270 msgid "Paragraph describing the returned result." msgstr "Abschnitt, der das zurückgegebene Ergebnis beschreibt." #. (itstool) path: varlistentry/term -#: C/index.docbook:1269 +#: C/index.docbook:1275 msgid "@...:" msgstr "@...:" #. (itstool) path: listitem/para -#: C/index.docbook:1271 +#: C/index.docbook:1277 msgid "" "In case the function has variadic arguments, you should use this tag " "(@Varargs: does also work for historic reasons)." @@ -2184,12 +2193,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1281 C/index.docbook:1283 +#: C/index.docbook:1287 C/index.docbook:1289 msgid "Property comment block" msgstr "Property-Kommentarblock" #. (itstool) path: example/programlisting -#: C/index.docbook:1284 +#: C/index.docbook:1290 #, no-wrap msgid "" "\n" @@ -2210,12 +2219,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1296 C/index.docbook:1315 +#: C/index.docbook:1302 C/index.docbook:1321 msgid "Signal comment block" msgstr "Signal-Kommentarblock" #. (itstool) path: listitem/para -#: C/index.docbook:1302 +#: C/index.docbook:1308 msgid "" "Document when the signal is emitted and whether it is emitted before or " "after other signals." @@ -2224,12 +2233,12 @@ msgstr "" "anderen Signalen ausgegeben wird." #. (itstool) path: listitem/para -#: C/index.docbook:1308 +#: C/index.docbook:1314 msgid "Document what an application might do in the signal handler." msgstr "Dokumentiert, was eine Anwendung in dem Signal-Handler tun könnte." #. (itstool) path: example/programlisting -#: C/index.docbook:1316 +#: C/index.docbook:1322 #, no-wrap msgid "" "\n" @@ -2260,12 +2269,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1333 C/index.docbook:1334 +#: C/index.docbook:1339 C/index.docbook:1340 msgid "Struct comment block" msgstr "Struct-Kommentarblock" #. (itstool) path: example/programlisting -#: C/index.docbook:1335 +#: C/index.docbook:1341 #, no-wrap msgid "" "\n" @@ -2295,7 +2304,7 @@ msgstr "" "} FooWidget;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1350 +#: C/index.docbook:1356 msgid "" "Use /*< private >*/ before the private struct fields you " "want to hide. Use /*< public >*/ for the reverse " @@ -2306,7 +2315,7 @@ msgstr "" "verwenden Sie /*< public >*/." #. (itstool) path: sect2/para -#: C/index.docbook:1356 +#: C/index.docbook:1362 msgid "" "If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" " "it will be considered private automatically and doesn't need to be mentioned " @@ -2317,7 +2326,7 @@ msgstr "" "erwähnt werden." #. (itstool) path: sect2/para -#: C/index.docbook:1362 +#: C/index.docbook:1368 msgid "" "Struct comment blocks can also be used for GObjects and GObjectClasses. It " "is usually a good idea to add a comment block for a class, if it has " @@ -2338,12 +2347,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1374 C/index.docbook:1375 +#: C/index.docbook:1380 C/index.docbook:1381 msgid "Enum comment block" msgstr "Enum-Kommentarblock" #. (itstool) path: example/programlisting -#: C/index.docbook:1376 +#: C/index.docbook:1382 #, no-wrap msgid "" "\n" @@ -2377,7 +2386,7 @@ msgstr "" "} Something;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1393 +#: C/index.docbook:1399 msgid "" "Use /*< private >*/ before the private enum values you " "want to hide. Use /*< public >*/ for the reverse " @@ -2388,12 +2397,12 @@ msgstr "" "verwenden Sie /*< public >*/." #. (itstool) path: sect1/title -#: C/index.docbook:1404 +#: C/index.docbook:1410 msgid "Inline program documentation" msgstr "Eingebettete Programmdokumentation" #. (itstool) path: sect1/para -#: C/index.docbook:1405 +#: C/index.docbook:1411 msgid "" "You can document programs and their commandline interface using inline " "documentation." @@ -2402,37 +2411,37 @@ msgstr "" "eingebetteter Dokumentation." #. (itstool) path: variablelist/title -#: C/index.docbook:1411 +#: C/index.docbook:1417 msgid "Tags" msgstr "Schlagwörter" #. (itstool) path: varlistentry/term -#: C/index.docbook:1413 +#: C/index.docbook:1419 msgid "PROGRAM" msgstr "PROGRAM" #. (itstool) path: listitem/para -#: C/index.docbook:1416 +#: C/index.docbook:1422 msgid "Defines the start of a program documentation." msgstr "Definiert den Start einer Programmdokumentation" #. (itstool) path: varlistentry/term -#: C/index.docbook:1423 +#: C/index.docbook:1429 msgid "@short_description:" msgstr "@short_description:" #. (itstool) path: listitem/para -#: C/index.docbook:1425 +#: C/index.docbook:1431 msgid "Defines a short description of the program. (Optional)" msgstr "Definiert eine Kurzbeschreibung des Programms (optional)." #. (itstool) path: varlistentry/term -#: C/index.docbook:1432 +#: C/index.docbook:1438 msgid "@synopsis:" msgstr "@synopsis:" #. (itstool) path: listitem/para -#: C/index.docbook:1434 +#: C/index.docbook:1440 msgid "" "Defines the arguments, or list of arguments that the program can take. " "(Optional)" @@ -2441,57 +2450,57 @@ msgstr "" "akzeptiert (optional)." #. (itstool) path: varlistentry/term -#: C/index.docbook:1442 +#: C/index.docbook:1448 msgid "@see_also:" msgstr "@see_also:" #. (itstool) path: listitem/para -#: C/index.docbook:1444 +#: C/index.docbook:1450 msgid "See Also manual page section. (Optional)" msgstr "" "Der Abschnitt »SEE ALSO« in den man-Pages (Unix-Handbuchseiten, optional)." #. (itstool) path: varlistentry/term -#: C/index.docbook:1451 +#: C/index.docbook:1457 msgid "@arg:" msgstr "@arg:" #. (itstool) path: listitem/para -#: C/index.docbook:1453 +#: C/index.docbook:1459 msgid "Argument(s) passed to the program and their description. (Optional)" msgstr "" "Argument(e), die dem Programm übergeben wurden, und die zugehörige " "Beschreibung (optional)." #. (itstool) path: varlistentry/term -#: C/index.docbook:1460 +#: C/index.docbook:1466 msgid "Description:" msgstr "Description:" #. (itstool) path: listitem/para -#: C/index.docbook:1462 +#: C/index.docbook:1468 msgid "A longer description of the program." msgstr "Eine ausführlichere Beschreibung des Programms." #. (itstool) path: listitem/para -#: C/index.docbook:1471 +#: C/index.docbook:1477 msgid "Specificy what value(s) the program returns. (Optional)" msgstr "Geben Sie an, welche Wert(e) das Programm zurück gibt (optional)." #. (itstool) path: sect2/title -#: C/index.docbook:1480 +#: C/index.docbook:1486 msgid "Example of program documentation." msgstr "Beispiel einer Programmdokumentation." #. (itstool) path: example/title -#: C/index.docbook:1481 +#: C/index.docbook:1487 msgid "Program documentation block" msgstr "Programm-Dokumentationsblock" # Würde ich nicht übersetzen. Ein Entwickler schreibt stets in Englisch, # die Übersetzung ist unsere Sache. #. (itstool) path: example/programlisting -#: C/index.docbook:1482 +#: C/index.docbook:1488 #, no-wrap msgid "" "\n" @@ -2535,12 +2544,12 @@ msgstr "" "}\n" #. (itstool) path: sect1/title -#: C/index.docbook:1508 +#: C/index.docbook:1514 msgid "Useful DocBook tags" msgstr "Nützliche DocBook-Markierungen" #. (itstool) path: sect1/para -#: C/index.docbook:1510 +#: C/index.docbook:1516 msgid "" "Here are some DocBook tags which are most useful when documenting the code." msgstr "" @@ -2548,7 +2557,7 @@ msgstr "" "von Code nützlich sein können." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1519 +#: C/index.docbook:1525 #, no-wrap msgid "" "\n" @@ -2558,7 +2567,7 @@ msgstr "" "<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1515 +#: C/index.docbook:1521 msgid "" "To link to another section in the GTK docs: <_:informalexample-1/> The " "linkend is the SGML/XML id on the top item of the page you want to link to. " @@ -2574,7 +2583,7 @@ msgstr "" "konform in »-« umgewandelt. " #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1532 +#: C/index.docbook:1538 #, no-wrap msgid "" "\n" @@ -2584,7 +2593,7 @@ msgstr "" "<function>...</function>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1529 +#: C/index.docbook:1535 msgid "" "To refer to an external function, e.g. a standard C function: <_:" "informalexample-1/>" @@ -2593,7 +2602,7 @@ msgstr "" "<_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1541 +#: C/index.docbook:1547 #, no-wrap msgid "" "\n" @@ -2613,7 +2622,7 @@ msgstr "" "</example>\n" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1552 +#: C/index.docbook:1558 #, no-wrap msgid "" "\n" @@ -2631,7 +2640,7 @@ msgstr "" "</informalexample>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1538 +#: C/index.docbook:1544 msgid "" "To include example code: <_:informalexample-1/> or possibly this, for very " "short code fragments which don't need a title: <_:informalexample-2/> For " @@ -2642,7 +2651,7 @@ msgstr "" "Außerdem unterstützt GTK-Doc auch eine Abkürzung: |[ ... ]|" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1571 +#: C/index.docbook:1577 #, no-wrap msgid "" "\n" @@ -2674,12 +2683,12 @@ msgstr "" "</itemizedlist>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1568 +#: C/index.docbook:1574 msgid "To include bulleted lists: <_:informalexample-1/>" msgstr "Für eine Liste mit Aufzählungszeichen: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1591 +#: C/index.docbook:1597 #, no-wrap msgid "" "\n" @@ -2697,14 +2706,14 @@ msgstr "" "</note>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1588 +#: C/index.docbook:1594 msgid "" "To include a note which stands out from the text: <_:informalexample-1/>" msgstr "" "Für eine nicht zum eigentlichen Text gehörende Notiz: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1604 +#: C/index.docbook:1610 #, no-wrap msgid "" "\n" @@ -2714,12 +2723,12 @@ msgstr "" "<type>unsigned char</type>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1601 +#: C/index.docbook:1607 msgid "To refer to a type: <_:informalexample-1/>" msgstr "Für einen Bezug zu einem Typ: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1613 +#: C/index.docbook:1619 #, no-wrap msgid "" "\n" @@ -2729,7 +2738,7 @@ msgstr "" "<structname>XFontStruct</structname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1610 +#: C/index.docbook:1616 msgid "" "To refer to an external structure (not one described in the GTK docs): <_:" "informalexample-1/>" @@ -2738,7 +2747,7 @@ msgstr "" "beschrieben wird): <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1622 +#: C/index.docbook:1628 #, no-wrap msgid "" "\n" @@ -2748,12 +2757,12 @@ msgstr "" "<structfield>len</structfield>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1619 +#: C/index.docbook:1625 msgid "To refer to a field of a structure: <_:informalexample-1/>" msgstr "Für einen Bezug zu einem Feld einer Struktur: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1631 +#: C/index.docbook:1637 #, no-wrap msgid "" "\n" @@ -2763,7 +2772,7 @@ msgstr "" "<classname>GtkWidget</classname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1628 +#: C/index.docbook:1634 msgid "" "To refer to a class name, we could possibly use: <_:informalexample-1/> but " "you'll probably be using #GtkWidget instead (to automatically create a link " @@ -2776,7 +2785,7 @@ msgstr "" "- lesen Sie die Abkürzungen)." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1642 +#: C/index.docbook:1648 #, no-wrap msgid "" "\n" @@ -2786,12 +2795,12 @@ msgstr "" "<emphasis>This is important</emphasis>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1639 +#: C/index.docbook:1645 msgid "To emphasize text: <_:informalexample-1/>" msgstr "Zum Hervorheben von Text: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1651 +#: C/index.docbook:1657 #, no-wrap msgid "" "\n" @@ -2801,12 +2810,12 @@ msgstr "" "<filename>/home/user/documents</filename>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1648 +#: C/index.docbook:1654 msgid "For filenames use: <_:informalexample-1/>" msgstr "Für Dateinamen: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1660 +#: C/index.docbook:1666 #, no-wrap msgid "" "\n" @@ -2816,17 +2825,17 @@ msgstr "" "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1657 +#: C/index.docbook:1663 msgid "To refer to keys use: <_:informalexample-1/>" msgstr "Für einen Bezug zu einem Schlüssel: <_:informalexample-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1670 +#: C/index.docbook:1676 msgid "Filling the extra files" msgstr "Füllen der zusätzlichen Dateien" #. (itstool) path: chapter/para -#: C/index.docbook:1672 +#: C/index.docbook:1678 msgid "" "There are a couple of extra files, that need to be maintained along with the " "inline source code comments: <package>.types, " @@ -2839,12 +2848,12 @@ msgstr "" "<package>-sections.txt." #. (itstool) path: sect1/title -#: C/index.docbook:1681 +#: C/index.docbook:1687 msgid "Editing the types file" msgstr "Bearbeiten der Typendatei" #. (itstool) path: sect1/para -#: C/index.docbook:1683 +#: C/index.docbook:1689 msgid "" "If your library or application includes GObjects, you want their signals, " "arguments/parameters and position in the hierarchy to be shown in the " @@ -2859,12 +2868,12 @@ msgstr "" "der Datei <package>.types aufzulisten." #. (itstool) path: example/title -#: C/index.docbook:1692 +#: C/index.docbook:1698 msgid "Example types file snippet" msgstr "Beispiel-Schnipsel einer Typen-Datei" #. (itstool) path: example/programlisting -#: C/index.docbook:1693 +#: C/index.docbook:1699 #, no-wrap msgid "" "\n" @@ -2884,7 +2893,7 @@ msgstr "" "gtk_arrow_get_type\n" #. (itstool) path: sect1/para -#: C/index.docbook:1704 +#: C/index.docbook:1710 msgid "" "Since GTK-Doc 1.8 gtkdoc-scan can generate this " "list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in " @@ -2898,12 +2907,12 @@ msgstr "" "stellen." #. (itstool) path: sect1/title -#: C/index.docbook:1713 +#: C/index.docbook:1719 msgid "Editing the master document" msgstr "Bearbeiten des Master-Dokuments" #. (itstool) path: sect1/para -#: C/index.docbook:1715 +#: C/index.docbook:1721 msgid "" "GTK-Doc produces documentation in DocBook SGML/XML. When processing the " "inline source comments, the GTK-Doc tools generate one documentation page " @@ -2916,7 +2925,7 @@ msgstr "" "Hauptdokument schließt diese ein und setzt sie in die passende Reihenfolge." #. (itstool) path: sect1/para -#: C/index.docbook:1722 +#: C/index.docbook:1728 msgid "" "While GTK-Doc creates a template master document for you, later runs will " "not touch it again. This means that one can freely structure the " @@ -2934,7 +2943,7 @@ msgstr "" "Neuigkeiten eingeführt werden." #. (itstool) path: tip/para -#: C/index.docbook:1732 +#: C/index.docbook:1738 msgid "" "Do not create tutorials as extra documents. Just write extra chapters. The " "benefit of directly embedding the tutorial for your library into the API " @@ -2950,7 +2959,7 @@ msgstr "" "die gleichen Aktualisierungen erfährt wie die Bibliothek selbst." #. (itstool) path: sect1/para -#: C/index.docbook:1741 +#: C/index.docbook:1747 msgid "" "So what are the things to change inside the master document? For a start is " "only a little. There are some placeholders (text in square brackets) there " @@ -2961,12 +2970,12 @@ msgstr "" "beachten sollten." #. (itstool) path: example/title -#: C/index.docbook:1748 +#: C/index.docbook:1754 msgid "Master document header" msgstr "Kopfzeile des Master-Dokuments" #. (itstool) path: example/programlisting -#: C/index.docbook:1749 +#: C/index.docbook:1755 #, no-wrap msgid "" "\n" @@ -2996,7 +3005,7 @@ msgstr "" " <title>[Insert title here]</title>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1765 +#: C/index.docbook:1771 msgid "" "In addition a few option elements are created in commented form. You can " "review these and enable them as you like." @@ -3005,12 +3014,12 @@ msgstr "" "können sich diese anschauen und aktivieren, wenn Sie wollen." #. (itstool) path: example/title -#: C/index.docbook:1771 +#: C/index.docbook:1777 msgid "Optional part in the master document" msgstr "Optionaler Teil im Master-Dokument" #. (itstool) path: example/programlisting -#: C/index.docbook:1772 +#: C/index.docbook:1778 #, no-wrap msgid "" "\n" @@ -3024,7 +3033,7 @@ msgstr "" " --> \n" #. (itstool) path: sect1/para -#: C/index.docbook:1780 +#: C/index.docbook:1786 msgid "" "Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind " @@ -3036,12 +3045,12 @@ msgstr "" "in der Dokumentation noch nicht erfasst sind." #. (itstool) path: example/title -#: C/index.docbook:1788 C/index.docbook:1823 +#: C/index.docbook:1794 C/index.docbook:1829 msgid "Including generated sections" msgstr "Einbeziehen erzeugter Abschnitte" #. (itstool) path: example/programlisting -#: C/index.docbook:1789 +#: C/index.docbook:1795 #, no-wrap msgid "" "\n" @@ -3057,12 +3066,12 @@ msgstr "" " ...\n" #. (itstool) path: sect1/title -#: C/index.docbook:1801 +#: C/index.docbook:1807 msgid "Editing the section file" msgstr "Bearbeiten der Abschnittsdatei" #. (itstool) path: sect1/para -#: C/index.docbook:1803 +#: C/index.docbook:1809 msgid "" "The section file is used to organise the documentation output by GTK-Doc. " "Here one specifies which symbol belongs to which module or class and control " @@ -3073,7 +3082,7 @@ msgstr "" "welcher Klasse gehört und regelt die Sichtbarkeit (öffentlich oder privat)." #. (itstool) path: sect1/para -#: C/index.docbook:1809 +#: C/index.docbook:1815 msgid "" "The section file is a plain text file with tags delimiting sections. Blank " "lines are ignored and lines starting with a '#' are treated as comment lines." @@ -3083,7 +3092,7 @@ msgstr "" "die mit »#« beginnen, werden als Kommentarzeilen behandelt." #. (itstool) path: note/para -#: C/index.docbook:1816 +#: C/index.docbook:1822 msgid "" "While the tags make the file look like xml, it is not. Please do not close " "tags like <SUBSECTION>." @@ -3092,7 +3101,7 @@ msgstr "" "trügt. Bitte schließen Sie keine Markierungen wie <SUBSECTION>." #. (itstool) path: example/programlisting -#: C/index.docbook:1824 +#: C/index.docbook:1830 #, no-wrap msgid "" "\n" @@ -3124,7 +3133,7 @@ msgstr "" "</SECTION>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1841 +#: C/index.docbook:1847 msgid "" "The <FILE> ... </FILE> tag is used to specify the file name, " "without any suffix. For example, using '<FILE>gnome-config</" @@ -3147,7 +3156,7 @@ msgstr "" "Kleinbuchstaben)." #. (itstool) path: sect1/para -#: C/index.docbook:1853 +#: C/index.docbook:1859 msgid "" "The <TITLE> ... </TITLE> tag is used to specify the title of the " "section. It is only useful before the templates (if used) are initially " @@ -3160,7 +3169,7 @@ msgstr "" "das SECTION-Kommentar in den Quellen einsetzt, ist dies überflüssig." #. (itstool) path: sect1/para -#: C/index.docbook:1860 +#: C/index.docbook:1866 msgid "" "You can group items in the section by using the <SUBSECTION> tag. " "Currently it outputs a blank line between subsections in the synopsis " @@ -3192,7 +3201,7 @@ msgstr "" "(Variablen, vmethods)." #. (itstool) path: sect1/para -#: C/index.docbook:1879 +#: C/index.docbook:1885 msgid "" "You can also use <INCLUDE> ... </INCLUDE> to specify the " "#include files which are shown in the synopsis sections. It contains a comma-" @@ -3208,12 +3217,12 @@ msgstr "" "Abschnitts festlegen, wirkt es nur in diesem Abschnitt." #. (itstool) path: chapter/title -#: C/index.docbook:1893 +#: C/index.docbook:1899 msgid "Controlling the result" msgstr "Überprüfung des Ergebnisses" #. (itstool) path: chapter/para -#: C/index.docbook:1895 +#: C/index.docbook:1901 msgid "" "A GTK-Doc run generates report files inside the documentation directory. The " "generated files are named: <package>-undocumented.txt<package>-undocumented.txt file starts with " "the documentation coverage summary. Below are two sections divided by blank " @@ -3245,7 +3254,7 @@ msgstr "" "Dokumentation haben, aber z.B. ein neuer Parameter hinzugefügt worden ist." #. (itstool) path: chapter/para -#: C/index.docbook:1913 +#: C/index.docbook:1919 msgid "" "The <package>-undeclared.txt file lists symbols " "given in the <package>-sections.txt but not found " @@ -3257,7 +3266,7 @@ msgstr "" "geschrieben wurden." #. (itstool) path: chapter/para -#: C/index.docbook:1920 +#: C/index.docbook:1926 msgid "" "The <package>-unused.txt file lists symbol names, " "where the GTK-Doc scanner has found documentation, but does not know where " @@ -3271,7 +3280,7 @@ msgstr "" "wurde." #. (itstool) path: tip/para -#: C/index.docbook:1928 +#: C/index.docbook:1934 msgid "" "Enable or add the line in Makefile." "am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during " @@ -3283,7 +3292,7 @@ msgstr "" "ausgeführt." #. (itstool) path: chapter/para -#: C/index.docbook:1935 +#: C/index.docbook:1941 msgid "" "One can also look at the files produced by the source code scanner: " "<package>-decl-list.txt and <" @@ -3300,7 +3309,7 @@ msgstr "" "kann man prüfen, ob diese Datei es enthält." #. (itstool) path: chapter/para -#: C/index.docbook:1944 +#: C/index.docbook:1950 msgid "" "If the project is GObject based, one can also look into the files produced " "by the object scanner: <package>.args.txt, " @@ -3322,12 +3331,12 @@ msgstr "" "ausführen." #. (itstool) path: chapter/title -#: C/index.docbook:1959 +#: C/index.docbook:1965 msgid "Modernizing the documentation" msgstr "Die Dokumentation modernisieren" #. (itstool) path: chapter/para -#: C/index.docbook:1961 +#: C/index.docbook:1967 msgid "" "GTK-Doc has been around for quite some time. In this section we list new " "features together with the version since when it is available." @@ -3336,12 +3345,12 @@ msgstr "" "wir neue Features und die Version, mit der sie eingeführt wurden." #. (itstool) path: sect1/title -#: C/index.docbook:1967 +#: C/index.docbook:1973 msgid "GTK-Doc 1.9" msgstr "GTK-Doc 1.9" #. (itstool) path: sect1/para -#: C/index.docbook:1969 +#: C/index.docbook:1975 msgid "" "When using xml instead of sgml, one can actually name the master document " "<package>-docs.xml." @@ -3350,7 +3359,7 @@ msgstr "" "<package>-docs.xml nennen." #. (itstool) path: sect1/para -#: C/index.docbook:1974 +#: C/index.docbook:1980 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3372,7 +3381,7 @@ msgstr "" "Abschnittsdatei sehr einfach aktualisiert werden." #. (itstool) path: sect1/para -#: C/index.docbook:1985 +#: C/index.docbook:1991 msgid "" "Version 1.8 already introduced the syntax for documenting sections in the " "sources instead of the separate files under SCAN_OPTIONS=--rebuild-types in " "Makefile.am. When this is enabled, the <" @@ -3418,17 +3427,17 @@ msgstr "" "soll." #. (itstool) path: sect1/title -#: C/index.docbook:2010 +#: C/index.docbook:2016 msgid "GTK-Doc 1.16" msgstr "GTK-Doc 1.16" #. (itstool) path: example/title -#: C/index.docbook:2016 +#: C/index.docbook:2022 msgid "Enable gtkdoc-check" msgstr "gtkdoc-check einschalten" #. (itstool) path: example/programlisting -#: C/index.docbook:2017 +#: C/index.docbook:2023 #, no-wrap msgid "" "\n" @@ -3448,7 +3457,7 @@ msgstr "" "endif\n" #. (itstool) path: sect1/para -#: C/index.docbook:2012 +#: C/index.docbook:2018 msgid "" "This version includes a new tool called gtkdoc-check. This tool can run a " "set of sanity checks on your documentation. It is enabled by adding these " @@ -3460,12 +3469,12 @@ msgstr "" "Makefile.am hinzu. <_:example-1/>" #. (itstool) path: sect1/title -#: C/index.docbook:2030 +#: C/index.docbook:2036 msgid "GTK-Doc 1.20" msgstr "GTK-Doc 1.20" #. (itstool) path: sect1/para -#: C/index.docbook:2032 +#: C/index.docbook:2038 msgid "" "Version 1.18 brought some initial markdown support. Using markdown in doc " "comments is less intrusive than writing docbook xml. This version improves a " @@ -3480,17 +3489,17 @@ msgstr "" "\">Kommentarsyntax." #. (itstool) path: sect1/title -#: C/index.docbook:2042 +#: C/index.docbook:2048 msgid "GTK-Doc 1.25" msgstr "GTK-Doc 1.25" #. (itstool) path: example/title -#: C/index.docbook:2052 +#: C/index.docbook:2058 msgid "Use pre-generated entities" msgstr "Vorerzeugte Entitäten verwenden" #. (itstool) path: example/programlisting -#: C/index.docbook:2053 +#: C/index.docbook:2059 #, no-wrap msgid "" "\n" @@ -3532,7 +3541,7 @@ msgstr "" " </bookinfo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:2044 +#: C/index.docbook:2050 msgid "" "The makefiles shipped with this version generate an entity file at " "xml/gtkdocentities.ent, containing entities for e.g. " @@ -3552,12 +3561,12 @@ msgstr "" "die gleichen XML-Kopfeinträge auch in generierten Dateien. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:2078 +#: C/index.docbook:2084 msgid "Documenting other interfaces" msgstr "Dokumentieren anderer Schnittstellen" #. (itstool) path: chapter/para -#: C/index.docbook:2080 +#: C/index.docbook:2086 msgid "" "So far we have been using GTK-Doc to document the API of code. The next " "sections contain suggestions how the tools can be used to document other " @@ -3568,12 +3577,12 @@ msgstr "" "Werkzeuge zum Dokumentieren anderer Schnittstellen eingesetzt werden können." #. (itstool) path: sect1/title -#: C/index.docbook:2087 +#: C/index.docbook:2093 msgid "Command line options and man pages" msgstr "Befehlszeilenoptionen und Handbuchseiten" #. (itstool) path: sect1/para -#: C/index.docbook:2089 +#: C/index.docbook:2095 msgid "" "As one can generate man pages for a docbook refentry as well, it sounds like " "a good idea to use it for that purpose. This way the interface is part of " @@ -3585,12 +3594,12 @@ msgstr "" "kostenfrei die man-Hilfeseite." #. (itstool) path: sect2/title -#: C/index.docbook:2096 +#: C/index.docbook:2102 msgid "Document the tool" msgstr "Dokumentieren des Werkzeuges" #. (itstool) path: sect2/para -#: C/index.docbook:2098 +#: C/index.docbook:2104 msgid "" "Create one refentry file per tool. Following our example we would call it meep/" @@ -3605,17 +3614,17 @@ msgstr "" "Beispiele (z.B. in glib) ansehen." #. (itstool) path: sect2/title -#: C/index.docbook:2108 +#: C/index.docbook:2114 msgid "Adding the extra configure check" msgstr "Hinzufügen der zusätzlichen Configure-Überprüfungen" #. (itstool) path: example/title -#: C/index.docbook:2111 C/index.docbook:2129 +#: C/index.docbook:2117 C/index.docbook:2135 msgid "Extra configure checks" msgstr "Zusätzliche Configure-Überprüfungen" #. (itstool) path: example/programlisting -#: C/index.docbook:2112 +#: C/index.docbook:2118 #, no-wrap msgid "" "\n" @@ -3637,12 +3646,12 @@ msgstr "" "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" #. (itstool) path: sect2/title -#: C/index.docbook:2126 +#: C/index.docbook:2132 msgid "Adding the extra makefile rules" msgstr "Hinzufügen der zusätzlichen Makefile-Regeln" #. (itstool) path: example/programlisting -#: C/index.docbook:2130 +#: C/index.docbook:2136 #, no-wrap msgid "" "\n" @@ -3678,12 +3687,12 @@ msgstr "" "EXTRA_DIST += meep.xml\n" #. (itstool) path: sect1/title -#: C/index.docbook:2152 +#: C/index.docbook:2158 msgid "DBus interfaces" msgstr "DBus-Schnittstellen" #. (itstool) path: sect1/para -#: C/index.docbook:2154 +#: C/index.docbook:2160 msgid "" "(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" @@ -3692,27 +3701,27 @@ msgstr "" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" #. (itstool) path: chapter/title -#: C/index.docbook:2163 +#: C/index.docbook:2169 msgid "Frequently asked questions" msgstr "Häufig gestellte Fragen" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2167 +#: C/index.docbook:2173 msgid "Question" msgstr "Frage" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2168 +#: C/index.docbook:2174 msgid "Answer" msgstr "Antwort" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2170 +#: C/index.docbook:2176 msgid "No class hierarchy." msgstr "Keine Klassenhierarchie." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2171 +#: C/index.docbook:2177 msgid "" "The objects xxx_get_type() function has not been " "entered into the <package>.types file." @@ -3721,12 +3730,12 @@ msgstr "" "die Datei <package>.types eingegeben." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2177 +#: C/index.docbook:2183 msgid "Still no class hierarchy." msgstr "Noch immer keine Klassenhierarchie." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2178 +#: C/index.docbook:2184 msgid "" "Missing or wrong naming in <package>-sections.txt " "file (see Erklärung)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2184 +#: C/index.docbook:2190 msgid "Damn, I have still no class hierarchy." msgstr "Verdammt, ich habe immer noch keine Klassenhierarchie." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2185 +#: C/index.docbook:2191 msgid "" "Is the object name (name of the instance struct, e.g. GtkWidget) part of the normal section (don't put this into Standard or Private " @@ -3752,12 +3761,12 @@ msgstr "" "Teil des normalen Abschnitts (nicht in den Standard- oder Unterabschnitte)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2192 +#: C/index.docbook:2198 msgid "No symbol index." msgstr "Kein Symbolindex." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2193 +#: C/index.docbook:2199 msgid "" "Does the <package>-docs.{xml,sgml} contain a " "index that xi:includes the generated index?" @@ -3766,12 +3775,12 @@ msgstr "" "der den erstellten Index xi:enthält?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2199 +#: C/index.docbook:2205 msgid "Symbols are not linked to their doc-section." msgstr "Symbole werden nicht mit deren Dokumentationsbschnitt verknüpft." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2200 +#: C/index.docbook:2206 msgid "" "Is the doc-comment using the correct markup (added #,% or ())? Check if the " "gtkdoc-fixxref warns about unresolvable xrefs." @@ -3780,12 +3789,12 @@ msgstr "" "»()«)? Prüfen Sie, ob gtkdoc-fixxref wegen nicht auflösbarer xrefs warnt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2206 +#: C/index.docbook:2212 msgid "A new class does not appear in the docs." msgstr "Eine neue Klasse erscheint nicht in der Dokumentation." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2207 +#: C/index.docbook:2213 msgid "" "Is the new page xi:included from <package>-docs.{xml,sgml}." @@ -3794,12 +3803,12 @@ msgstr "" "sgml}?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2213 +#: C/index.docbook:2219 msgid "A new symbol does not appear in the docs." msgstr "Ein neues Symbol erscheint nicht in der Dokumentation." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2214 +#: C/index.docbook:2220 msgid "" "Is the doc-comment properly formatted. Check for spelling mistakes in the " "begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable " @@ -3813,12 +3822,12 @@ msgstr "" "Abschnitt gelistet ist." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2222 +#: C/index.docbook:2228 msgid "A type is missing from the class hierarchy." msgstr "Ein Typ fehlt in der Klassenhierarchie." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2223 +#: C/index.docbook:2229 msgid "" "If the type is listed in <package>.hierarchy but " "not in xml/tree_index.sgml then double check that the " @@ -3834,12 +3843,12 @@ msgstr "" "sie nicht angezeigt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2232 +#: C/index.docbook:2238 msgid "I get foldoc links for all gobject annotations." msgstr "Ich erhalte foldoc-Verweise für alle gobjekt-Anmerkungen." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2233 +#: C/index.docbook:2239 msgid "" "Check that xml/annotation-glossary.xml is xi:included " "from <package>-docs.{xml,sgml}." @@ -3848,28 +3857,28 @@ msgstr "" "<package>-docs.{xml,sgml} xi:eingebunden ist." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2241 +#: C/index.docbook:2247 msgid "Parameter described in source code comment block but does not exist" msgstr "" "Parameter wird im Kommentarblock des Quellcodes beschrieben, aber existiert " "nicht" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2242 +#: C/index.docbook:2248 msgid "" "Check if the prototype in the header has different parameter names as in the " "source." msgstr "" "Überprüfen Sie, ob die Parameternamen der Prototypen in der Quelle und im " -"Header unterschiedlich sind" +"Header unterschiedlich sind." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2247 +#: C/index.docbook:2253 msgid "multiple \"IDs\" for constraint linkend: XYZ" msgstr "Mehrfache »IDs« für »constraint linkend: XYZ«" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2248 +#: C/index.docbook:2254 msgid "" "Symbol XYZ appears twice in <package>-sections.txt file." @@ -3878,7 +3887,7 @@ msgstr "" "sections.txt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2251 +#: C/index.docbook:2257 msgid "" "Element typename in namespace '' encountered in para, but no template " "matches." @@ -3887,12 +3896,12 @@ msgstr "" "entspricht." #. (itstool) path: chapter/title -#: C/index.docbook:2258 +#: C/index.docbook:2264 msgid "Tools related to gtk-doc" msgstr "Werkzeuge mit Bezug zu gtk-doc" #. (itstool) path: chapter/para -#: C/index.docbook:2260 +#: C/index.docbook:2266 msgid "" "GtkDocPlugin - a Trac " "GTK-Doc integration plugin, that adds API docs to a trac site and " @@ -3903,7 +3912,7 @@ msgstr "" "Seite hinzufügt und die trac-Suche einbindet." #. (itstool) path: chapter/para -#: C/index.docbook:2265 +#: C/index.docbook:2271 msgid "" "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " "tags in the API to determine the minimum required version." diff --git a/help/manual/de/index.docbook b/help/manual/de/index.docbook index 43643b9..8ec419f 100644 --- a/help/manual/de/index.docbook +++ b/help/manual/de/index.docbook @@ -35,11 +35,12 @@ - 1.28 - 24 Mar 2018 + 1.29 + 28 Aug 2018 ss - bug fixes + development + 1.28 24. März 2018 ss Fehlerbehebungen 1.27 07. Dezember 2017> ss Detailanpassungen der Python-Portierung 1.26.1 11. August 2017 ss Alle Werkzeuge von Perl/Bash nach Python portiert 1.25 21. März 2015 ss Fehlerbehebungen, Test-Cleanups @@ -122,7 +123,12 @@ - Schreiben der Dokumentation. 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. + + Writing the documentation. + + The author fills in the source files with the documentation for each + function, macro, structs or unions, etc. + @@ -159,9 +165,22 @@ Info zu GTK-Doc + + 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. + + (FIXME) - (Geschichte, Autoren, Webseiten, Mailingliste, Lizenz, Zukunftspläne, Vergleich mit ähnlichen Systemen) + + (authors, web pages, mailing list, license, future plans, + comparison with other similar systems.) + @@ -177,131 +196,529 @@ - Einrichten Ihres Projekts + Project Setup - 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 Klartext-Makefiles oder andere Erstellungssysteme die Grundlagen für die Arbeit in einer anderen Erstellungsumgebung. + + 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: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + + + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. + Einrichten des Grundgerüsts der Dokumentation - 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. + + A common convention is to place documentation into a folder called + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. + - Dies kann dann wie nachstehend angezeigt aussehen: Beispiel für die Ordnerstruktur - + + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project + - +]]> + + - - Integration in autoconf - - Sehr einfach! Fügen Sie eine Zeile zu Ihrem configure.ac-Skript hinzu. + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + + + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - Integration in autoconf - -# check for gtk-doc -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - 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 GTK_DOC_CHECK am Anfang einer Zeile sucht. Halten Sie gtk-doc optional + + Integration in automake + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + -# check for gtk-doc -m4_ifdef([GTK_DOC_CHECK], [ -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) -],[ -AM_CONDITIONAL([ENABLE_GTK_DOC], false) -]) +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ - + - Das erste Argument wird zur Überprüfung von gtkdocversion während des configure-Durchlaufs benutzt. Das zweite, optionale Argument wird von gtkdocize verwendet. Das Makro GTK_DOC_CHECK fügt verschiedene Schalter für configure hinzu: - - --with-html-dir=PATH : Pfad zur installierten Dokumentation - --enable-gtk-doc : gtk-doc zur Erstellung der Dokumentation verwenden [Vorgabe=no] - --enable-gtk-doc-html : Erstellung der Dokumentation im HTML-Format [Vorgabe=yes] - --enable-gtk-doc-pdf : Erstellung der Dokumentation im PDF-Format [Vorgabe=no] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. - - GTK-Doc ist standardmäßig deaktiviert! Denken Sie daran, die Option beim nächsten Durchlauf von configure zu übergeben. Anderenfalls wird die vorher erstellte Dokumentation installiert. Dies ergibt für Benutzer durchaus Sinn, aber nicht für Entwickler. - + All settings have a comment above them that describes their purpose + and how to customize the setting. - Weiterhin ist es empfehlenswert, dass das configure.ac-Skript die folgende Zeile enthält. Dies erlaubt gtkdocize das automatische Kopieren der Makrodefinition für GTK_DOC_CHECK in Ihr Projekt. + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). - - Vorbereitung für gtkdocize - + All the tools support to list the supported + options. + + + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. + + + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + Integration in autoconf + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - Nachdem alle Änderungen auf configure.ac angewendet wurden, aktualisieren Sie die Datei configure. Dies geschieht durch erneutes Ausführen von autoreconf -i oder autogen.sh. - +# optional: register gtk-doc in configure +GTK_DOC_CHECK([1.28]) +]]> + + + + + 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: + + + Integration with optional gtk-doc dependency + + + - - Integration in automake + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - Kopieren Sie zunächst die Datei Makefile.am aus dem Beispiel-Unterordner der gtkdoc-sources in den API-Dokumentationsordner Ihres Projekts ( ./docs/reference/<package>). Eine lokale Kopie sollte beispielsweise unter /usr/share/doc/gtk-doc-tools/examples/Makefile.am verfügbar sein. Falls Sie mehrere Dokumentationspakete haben, müssen Sie dies für jedes davon wiederholen. + + --with-html-dir=PATH : Pfad zur installierten Dokumentation + --enable-gtk-doc : gtk-doc zur Erstellung der Dokumentation verwenden [Vorgabe=no] + --enable-gtk-doc-html : Erstellung der Dokumentation im HTML-Format [Vorgabe=yes] + --enable-gtk-doc-pdf : Erstellung der Dokumentation im PDF-Format [Vorgabe=no] + - Im nächsten Schritt bearbeiten Sie die Einstellungen in Makefile.am. 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 . Alle Werkzeuge unterstützen zur Auflistung der unterstützten Parameter. + + GTK-Doc ist standardmäßig deaktiviert! Denken Sie daran, die Option beim nächsten Durchlauf von configure zu übergeben. Anderenfalls wird die vorher erstellte Dokumentation installiert. Dies ergibt für Benutzer durchaus Sinn, aber nicht für Entwickler. + - + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - + + Integration in autogen - - Integration in autogen + + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + - Die meisten Projekte dürften über ein autogen.sh-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 gtkdocize mit, das in einem solchen Skript verwendet werden kann. Es sollte vor autoheader, automake oder autoconf ausgeführt werden. + + It should be run before autoreconf, autoheader, automake or autoconf. + - - Ausführen von gtkdocize durch autogen.sh - + + Ausführen von gtkdocize durch autogen.sh + gtkdocize || exit 1 - - + + - Beim Ausführen von gtkdocize wird gtk-doc.make in die Wurzel Ihres Projekts oder in jeden anderen durch die Option festgelegten Ordner kopiert. Außerdem wird das configure-Skript daraufhin überprüft, ob GTK_DOC_CHECK enthalten ist. Dieses Makro kann verwendet werden, um weitere Parameter an gtkdocize zu übergeben. + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - 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. gtkdocize unterstützt nun die 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 GTKDOCIZE_FLAGS hinzugefügt oder als zweiter Parameter im GTK_DOC_CHECK-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. - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - Erstellung der Dokumentation + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - Nach den bisher absolvierten Schritten ist es Zeit für den Build-Vorgang. Zunächst muss autogen.sh erneut ausgeführt werden. Falls dieses Skript auch den configure-Aufruf enthält, sollten Sie die Option hinzufügen. Anderenfalls führen Sie danach configure manuell aus, ebenfalls mit dieser Option. - Der erste Durchlauf von make erstellt verschiedene zusätzliche Dateien in den Dokumentationsordnern. Die bedeutendsten davon sind: <package>.types, <package>-docs.xml (früher .sgml), <package>-sections.txt. - - Erstellung der Dokumentation - + + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + Nach den bisher absolvierten Schritten ist es Zeit für den Build-Vorgang. Zunächst muss autogen.sh erneut ausgeführt werden. Falls dieses Skript auch den configure-Aufruf enthält, sollten Sie die Option hinzufügen. Anderenfalls führen Sie danach configure manuell aus, ebenfalls mit dieser Option. + Der erste Durchlauf von make erstellt verschiedene zusätzliche Dateien in den Dokumentationsordnern. Die bedeutendsten davon sind: <package>.types, <package>-docs.xml (früher .sgml), <package>-sections.txt. + + Erstellung der Dokumentation + ./autogen.sh --enable-gtk-doc make - - - Nun können Sie docs/reference/<package>/index.html 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. + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - Integration in Versionsverwaltungssysteme + + Integration in CMake-Erstellungssysteme - Als Faustregel gilt, dass alle von Ihnen bearbeiteten Dateien auch unter Versionsverwaltung stehen sollten. In typischen Projekten sind das folgende Dateien: <package>.types, <package>-docs.xml (früher .sgml), <package>-sections.txt, Makefile.am. - Dateien in den Ordnern xml/ und html/ sollten nicht unter Versionsverwaltung gestellt werden, ebenso keine der .stamp-Dateien. + GTK-Doc stellt nun ein GtkDocConfig.cmake-Modul (und das korrespondierende GtkDocConfigVersion.cmake-Modul) bereit. Dadurch steht Ihnen der Befehl gtk_doc_add_module zur Verfügung, den Sie in die Datei CMakeLists.txt integrieren können. + + Das folgende Beispiel zeigt, wie dieser Befehl eingesetzt wird. Beispiel zur Verwendung von GTK-Doc mit CMake + +find_package(GtkDoc 1.25 REQUIRED) + +# Create the doc-libmeep target. +gtk_doc_add_module( + libmeep ${CMAKE_SOURCE_DIR}/libmeep + XML meep-docs.xml + LIBRARIES libmeep +) + +# Build doc-libmeep as part of the default target. Without this, you would +# have to explicitly run something like `make doc-libmeep` to build the docs. +add_custom_target(documentation ALL DEPENDS doc-libmeep) + +# Install the docs. (This assumes you're using the GNUInstallDirs CMake module +# to set the CMAKE_INSTALL_DOCDIR variable correctly). +install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html + DESTINATION ${CMAKE_INSTALL_DOCDIR}) + + - + Integration in Klartext-Makefiles oder andere Erstellungssysteme Für den Fall, dass jemand nicht automake und damit gtk-doc.mak einsetzen will, muss man die gtkdoc-Werkzeuge in eigenen makefiles (oder andere Werkzeuge) in der richtigen Reihenfolge aufrufen. @@ -325,33 +742,13 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html Man muss sich Makefile.am und gtk-doc.mak anschauen, um die zusätzlich notwendigen Optionen herauszusuchen. - - Integration in CMake-Erstellungssysteme - - GTK-Doc stellt nun ein GtkDocConfig.cmake-Modul (und das korrespondierende GtkDocConfigVersion.cmake-Modul) bereit. Dadurch steht Ihnen der Befehl gtk_doc_add_module zur Verfügung, den Sie in die Datei CMakeLists.txt integrieren können. - - Das folgende Beispiel zeigt, wie dieser Befehl eingesetzt wird. Beispiel zur Verwendung von GTK-Doc mit CMake - -find_package(GtkDoc 1.25 REQUIRED) - -# Create the doc-libmeep target. -gtk_doc_add_module( - libmeep ${CMAKE_SOURCE_DIR}/libmeep - XML meep-docs.xml - LIBRARIES libmeep -) + + Integration in Versionsverwaltungssysteme -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + Als Faustregel gilt, dass alle von Ihnen bearbeiteten Dateien auch unter Versionsverwaltung stehen sollten. In typischen Projekten sind das folgende Dateien: <package>.types, <package>-docs.xml (früher .sgml), <package>-sections.txt, Makefile.am. + Dateien in den Ordnern xml/ und html/ sollten nicht unter Versionsverwaltung gestellt werden, ebenso keine der .stamp-Dateien. + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) - - - @@ -359,19 +756,18 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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. - - Platzierung der Dokumentation - In der Vergangenheit wurde die Dokumentation oft in Dateien gespeichert, die im Ordner tmpl liegen. Das hat den Nachteil, dass die Informationen oft nicht aktualisiert wurden und die Datei tendenziell Konflikte mit Versionsverwaltungssystemen verursachen kann. - 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. - - - 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. GTK-Doc-Kommentarblock - + + 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. + GTK-Doc comment block + - +]]> + + Einschränkungen @@ -421,7 +817,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Verwenden Sie #symbol, um auf andere Symboltypen zu verweisen, z.B. »structs« und »enums« und Makros, die keine Argumente benötigen. - Verwenden Sie #Object::signal, um auf ein GObject-Signal zu verweisen + Verwenden Sie #Object::signal, um auf ein GObject-Signal zu verweisen. Verwenden Sie #Object:property, um auf eine GObject-Eigenschaft zu verweisen. @@ -485,7 +881,17 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Weitere Beispiele zu den unterstützten Markdown-Formatierungen finden Sie in der GTK+ Documentation Markdown Syntax Reference. - 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. + + 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. + @@ -1017,7 +1423,7 @@ int main(int argc, char *argv[]) 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 xxx_get_type-Funktionen zusammen mit deren Includes in der Datei <package>.types aufzulisten. - Beispiel-Schnipsel einer Typen-Datei + Example <package>.types file #include <gtk/gtk.h> @@ -1198,27 +1604,37 @@ endif GTK-Doc 1.25 - Die in dieser Version enthaltenen Make-Steuerdateien erzeugen die Entitätsdatei xml/gtkdocentities.ent, 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. Vorerzeugte Entitäten verwenden - -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + + The makefiles shipped with this version generate an entity file at xml/gtkdocentities.ent, + 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. + Use pre-generated entities + + + %gtkdocentities; -]> -<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> - <bookinfo> - <title>&package_name; Reference Manual</title> - <releaseinfo> - for &package_string;. +]> + + + &package_name; Reference Manual + + 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> - - + http://[SERVER]/&package_name;/. + + +]]> + + @@ -1337,7 +1753,7 @@ EXTRA_DIST += meep.xml Parameter wird im Kommentarblock des Quellcodes beschrieben, aber existiert nicht - Überprüfen Sie, ob die Parameternamen der Prototypen in der Quelle und im Header unterschiedlich sind + Überprüfen Sie, ob die Parameternamen der Prototypen in der Quelle und im Header unterschiedlich sind. diff --git a/help/manual/el/index.docbook b/help/manual/el/index.docbook index 649d6b1..37f3a26 100644 --- a/help/manual/el/index.docbook +++ b/help/manual/el/index.docbook @@ -35,6 +35,12 @@ + 1.29 + 28 Aug 2018 + ss + development + + 1.28 24 Mar 2018 ss @@ -181,7 +187,12 @@ - Συγγραφή της τεκμηρίωσης Ο συγγραφέας συμπληρώνει τα πηγαία αρχεία με τεκμηρίωση για όλες τις συναρτήσεις, μακροεντολές, ενώσεις κτλ. (Στο παρελθόν, οι πληροφορίες συμπληρώνονταν σε πρότυπα αρχεία που παράγονταν αυτόματα, αλλά αυτός ο τρόπος δεν συνιστάται πλέον.) + + Writing the documentation. + + The author fills in the source files with the documentation for each + function, macro, structs or unions, etc. + @@ -220,9 +231,22 @@ Περί GTK-Doc + + 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. + + (ΠΡΟΣ ΔΙΟΡΘΩΣΗ) - (Ιστορικό, συγγραφείς, ιστοσελίδες, λίστα αλληλογραφίας, άδεια, μελλοντικά σχέδια, σύγκριση με άλλα παρόμοια συστήματα.) + + (authors, web pages, mailing list, license, future plans, + comparison with other similar systems.) + @@ -238,136 +262,529 @@ - Δημιουργώντας το δικό σας έργο + Project Setup + + + This Chapter describes the steps that are necessary to integrate GTK-Doc + into your project. The integration of GTK-Doc into a project includes the + following steps: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + - Οι επόμενες ενότητες περιγράφουν τα βήματα που απαιτούνται για να ενσωματώσετε το GTK-Doc στο έργο σας. Αυτές οι ενότητες προϋποθέτουν ότι εργάζεσθε σε ένα έργο που λέγεται 'meep'. Το έργο περιέχει τη βιβλιοθήκη 'libmeep' και την εφαρμογή 'meeper' για τον τελικό χρήστη. Θεωρούμε επίσης, ότι θα χρησιμοποιείτε το autoconf και το automake. Επιπλέον, η ενότητα αρχεία makefiles ή άλλα συστήματα ανάπτυξης θα περιγράψει τα βασικά στοιχεία που απαιτούνται για να εργαστείτε σε μια διαφορετική δόμηση ρυθμίσεων. + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. + Δημιουργία του σκελετού τεκμηρίωσης - Εντός του ριζικού καταλόγου του έργου δημιουργήστε το φάκελο docs/reference (ώστε να μπορείτε να χρησιμοποιήσετε το όνομα docs/help για την τεκμηρίωση του τελικού χρήστη). Συνιστάται να δημιουργήσετε έναν ακόμη υποκατάλογο με το όνομα του πακέτου τεκμηρίωσης. Αυτό δε χρειάζεται για πακέτα που περιλαμβάνουν μόνο μία βιβλιοθήκη. + + A common convention is to place documentation into a folder called + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. + - Αυτό θα φαίνεται, λοιπόν, όπως εμφανίζεται παρακάτω: Παράδειγμα δομής καταλόγου - + + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project + - +]]> + + - - Ενσωμάτωση στο autoconf - - Πολύ εύκολα! Απλά προσθέτετε μία γραμμή στη δέσμη ενεργειών configure.ac. + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + + + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - Ενσωμάτωση στο autoconf - -# έλεγχος για gtk-doc -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - Αυτό απαιτεί από όλους τους προγραμματιστές να έχουν εγκατεστημένο το gtk-doc. Αν είναι εντάξει για το έργο σας να έχετε μια επιπλέον δόμηση ρυθμίσεων για το api-doc, μπορείτε να το επιλύσετε όπως αναφέρεται παρακάτω. Αφήστε το ως έχει, όσο το gtkdocize αναζητά την αρχή της σειράς για το GTK_DOC_CHECK. Προαιρετικά διατηρήστε το gtk-doc + + Ενσωμάτωση στο automake + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + -# έλεγχος για gtk-doc -m4_ifdef([GTK_DOC_CHECK], [ -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) -],[ -AM_CONDITIONAL([ENABLE_GTK_DOC], false) -]) +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ - + - Το πρώτο όρισμα χρησιμοποιείται για έλεγχο του gtkdocversion κατά τη ρύθμιση. Το δεύτερο, προαιρετικό όρισμα χρησιμοποιείται από το gtkdocize. Η μακροεντολή GTK_DOC_CHECK επίσης προσθέτει αρκετούς διακόπτες ρύθμισης: - - --with-html-dir= PATH : διαδρομή προς την εγκατεστημένη τεκμηρίωση - --enable-gtk-doc : χρήση gtk-doc για τη δόμηση τεκμηρίωσης [προεπιλογή=no] - --enable-gtk-doc-html : δόμηση τεκμηρίωσης σε μορφή html [προεπιλογή=yes] - --enable-gtk-doc-pdf : δόμηση τεκμηρίωσης σε μορφή pdf [προεπιλογή=no] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. - - Το GTK-Doc είναι απενεργοποιημένο από προεπιλογή! Να θυμάστε να χρησιμοποιείτε την επιλογή στην επόμενη εκτέλεση του configure. Διαφορετικά, εγκαθίσταται η προπαραχθείσα τεκμηρίωση (δυνατότητα χρήσιμη για τον χρήστη, αλλά όχι για τον προγραμματιστή). - + All settings have a comment above them that describes their purpose + and how to customize the setting. - - Furthermore it is recommended that you have the following line inside - your configure.ac script. - This allows gtkdocize to automatically copy the - macro definition for GTK_DOC_CHECK to your project. - + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). - - Προετοιμασία για το gtkdocize - + All the tools support to list the supported + options. + + + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. + + + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + Ενσωμάτωση στο autoconf + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - Όταν όλες οι αλλαγές στο configure.ac έχουν γίνει, ενημερώστε το αρχείο configure. Αυτό μπορείτε να το κάνετε επανεκετελώντας το autoreconf -i ή το autogen.sh. - +# optional: register gtk-doc in configure +GTK_DOC_CHECK([1.28]) +]]> + + - - Ενσωμάτωση στο automake + + 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: - Πρώτα αντιγράψτε το Makefile.am από τον υποκατάλογο με τα παραδείγματα των gtkdoc-sources στον κατάλογο της τεκμηρίωσης API του έργου σας ( ./docs/reference/<package>). Ένα τοπικό αντίγραφο θα πρέπει να είναι διαθέσιμο π.χ. στο /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Αν έχετε πολλά doc-packages επαναλάβετε αυτό το βήμα για το καθένα απο αυτά. + + Integration with optional gtk-doc dependency + + + - Το επόμενο βήμα είναι να τροποποιήσετε τις ρυθμίσεις στο Makefile.am. Πριν από κάθε ρύθμιση υπάρχει ένα σχόλιο που εξηγεί τη χρησιμότητά της. Οι περισσότερες είναι σημαίες που στέλνονται στα αντίστοιχα εργαλεία. Κάθε εργαλείο διαθέτει μια μεταβλητή της μορφής . Όλα τα εργαλεία υποστηρίζουν την επιλογή για την παραγωγή λίστας με τις υποστηριζόμενες παραμέτρους. + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - + + --with-html-dir= PATH : διαδρομή προς την εγκατεστημένη τεκμηρίωση + --enable-gtk-doc : χρήση gtk-doc για τη δόμηση τεκμηρίωσης [προεπιλογή=no] + --enable-gtk-doc-html : δόμηση τεκμηρίωσης σε μορφή html [προεπιλογή=yes] + --enable-gtk-doc-pdf : δόμηση τεκμηρίωσης σε μορφή pdf [προεπιλογή=no] + - + + Το GTK-Doc είναι απενεργοποιημένο από προεπιλογή! Να θυμάστε να χρησιμοποιείτε την επιλογή στην επόμενη εκτέλεση του configure. Διαφορετικά, εγκαθίσταται η προπαραχθείσα τεκμηρίωση (δυνατότητα χρήσιμη για τον χρήστη, αλλά όχι για τον προγραμματιστή). + - - Ενσωμάτωση στο autogen + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - Τα περισσότερα έργα διαθέτουν ένα σενάριο autogen.sh για τη δόμηση υποδομών μετά από έναν έλεγχο από το σύστημα ελέγχου εκδόσεων (π.χ., cvs/svn/git). Το GTK-Doc διαθέτει το εργαλείο gtkdocize, το οποίο μπορεί να χρησιμοποιηθεί για ένα τέτοιο σενάριο. Θα πρέπει να εκτελείται πριν το autoheader, το automake ή το autoconf. + + Ενσωμάτωση στο autogen - - Εκτέλεση του gtkdocize από το autogen.sh - + + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + + + + It should be run before autoreconf, autoheader, automake or autoconf. + + + + Εκτέλεση του gtkdocize από το autogen.sh + gtkdocize || exit 1 - - + + - Κατά την εκτέλεσή του, το gtkdocize αντιγράφει το gtk-doc.make στο ριζικό κατάλογο του έργου σας (ή στον κατάλογο που ορίζει η επιλογή ). Επίσης, ελέγχει τη δέσμη ενεργειών configure για να βρει την κλήση στο GTK_DOC_CHECK. + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - Αρχικά, το GTK-Doc δημιουργούσε αρχεία προτύπων εκεί που οι προγραμματιστές εισήγαγαν την τεκμηρίωση. Δυστυχώς, αυτή η προσέγγιση δεν ήταν ιδιαίτερα επιτυχής (π.χ η ανάγκη για παραγωγή αρχείων στο σύστημα ελέγχου εκδόσεων). Από την έκδοση 1.9 και μετά, τα πρότυπα αρχεία δεν είναι πλέον απαραίτητα. Σας συνιστούμε να διατηρείτε την τεκμηρίωση στον κώδικα. To gtkdocize υποστηρίζει πλέον την επιλογή που επιλέγει ένα αρχείο makefile που δεν χρησιμοποιεί καθόλου πρότυπα tmpl. Πέρα από την άμεση προσθήκη της επιλογής στην κλήση της εντολής, μπορεί να προστεθεί και σε μια μεταβλητή περιβάλλοντος που ονομάζεται GTKDOCIZE_FLAGS ή να ορισθεί ως δεύτερη παράμετρος στη μακροεντολή GTK_DOC_CHECK στο σενάριο configure. Αν δεν έχετε κάνει ποτέ αλλαγές με το χέρι σε αρχεία προτύπων και μεταβαίνετε από μια παλιότερη έκδοση του gtkdoc, παρακαλώ αφαιρέστε τον κατάλογο (π.χ. από το σύστημα ελέγχου εκδόσεων). - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - Εκτέλεση της δόμησης τεκμηρίωσης + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - Αφού ολοκληρωθούν τα προηγούμενα βήματα, προχωρήστε στην δόμηση. Πρώτα, θα πρέπει να εκτελεσθεί εκ νέου το autogen.sh. Αν το σενάριο εκτελεί και το configure, προσθέστε την επιλογή . Διαφορετικά, εκτελέστε εσείς τοconfigure με αυτή την επιλογή. - Η πρώτη εκτέλεση του make δημιουργεί μια σειρά από πρόσθετα αρχεία στους καταλόγους της τεκμηρίωσης. Τα σημαντικά είναι τα: <package>.types, <package>-docs.xml (στο παρελθόν .sgml), <package>-sections.txt. - - Εκτέλεση της δόμησης τεκμηρίωσης - + + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + Αφού ολοκληρωθούν τα προηγούμενα βήματα, προχωρήστε στην δόμηση. Πρώτα, θα πρέπει να εκτελεσθεί εκ νέου το autogen.sh. Αν το σενάριο εκτελεί και το configure, προσθέστε την επιλογή . Διαφορετικά, εκτελέστε εσείς τοconfigure με αυτή την επιλογή. + Η πρώτη εκτέλεση του make δημιουργεί μια σειρά από πρόσθετα αρχεία στους καταλόγους της τεκμηρίωσης. Τα σημαντικά είναι τα: <package>.types, <package>-docs.xml (στο παρελθόν .sgml), <package>-sections.txt. + + Εκτέλεση της δόμησης τεκμηρίωσης + ./autogen.sh --enable-gtk-doc make - - - Τώρα, μπορείτε να εμφανίσετε το docs/reference/<package>/index.html στον περιηγητή σας. Είναι αλήθεια ότι προς το παρόν το αποτέλεσμα είναι μάλλον απογοητευτικό. Μην ανησυχείτε όμως. Στο επόμενο κεφάλαιο θα μάθετε πώς μπορείτε να ζωντανέψετε τις σελίδες σας. + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - Ενσωμάτωση σε συστήματα ελέγχου εκδόσεων + + Ενσωμάτωση με συστήματα δόμησης CMake - Ο εμπειρικός κανόνας είναι ότι αυτά τα αρχεία που επεξεργασθήκατε πρέπει να περάσουν από τον έλεγχο έκδοσης. Για τυπικά έργα, πρόκειται για τα αρχεία: <package>.types, <package>-docs.xml (στο παρελθόν .sgml), <package>-sections.txt, Makefile.am. - Αρχεία στους καταλόγους xml/ και html/ δεν θα πρέπει να υποβληθούν σε έλεγχο έκδοσης. Ούτε και αρχεία xml/ and html/. + Το GTK-Doc παρέχει το άρθρωμα GtkDocConfig.cmake (και το αντίστοιχο άρθρωμα GtkDocConfigVersion.cmake). Επίσης παρέχει την εντολή gtk_doc_add_module την οποία μπορείτε να ορίσετε στο αρχείο CMakeLists.txt. + + Το ακόλουθο παράδειγμα δείχνει πως να χρησιμοποιήσετε την εντολή. Παράδειγμα χρήσης του GTK-Doc από το CMake + +find_package(GtkDoc 1.25 REQUIRED) + +# Create the doc-libmeep target. +gtk_doc_add_module( + libmeep ${CMAKE_SOURCE_DIR}/libmeep + XML meep-docs.xml + LIBRARIES libmeep +) + +# Build doc-libmeep as part of the default target. Without this, you would +# have to explicitly run something like `make doc-libmeep` to build the docs. +add_custom_target(documentation ALL DEPENDS doc-libmeep) + +# Install the docs. (This assumes you're using the GNUInstallDirs CMake module +# to set the CMAKE_INSTALL_DOCDIR variable correctly). +install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html + DESTINATION ${CMAKE_INSTALL_DOCDIR}) + + - + Ενσωμάτωση στα αρχεία makefiles ή άλλα συστήματα δόμησης Στην περίπτωση που κάποιος δε θέλει να χρησιμοποιήσει το automake και, επομένως, το gtk-doc.mak θα χρειαστεί να καλέσει τα εργαλεία του gtkdoc στη σωστή σειρά στα makefiles (ή άλλα εργαλεία δόμησης). @@ -391,33 +808,13 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html Πρέπει να κοιτάξετε στα αρχεία Makefile.am και gtk-doc.mak για να επιλέξετε τις ρυθμίσεις που χρειάζονται. - - Ενσωμάτωση με συστήματα δόμησης CMake - - Το GTK-Doc παρέχει το άρθρωμα GtkDocConfig.cmake (και το αντίστοιχο άρθρωμα GtkDocConfigVersion.cmake). Επίσης παρέχει την εντολή gtk_doc_add_module την οποία μπορείτε να ορίσετε στο αρχείο CMakeLists.txt. - - Το ακόλουθο παράδειγμα δείχνει πως να χρησιμοποιήσετε την εντολή. Παράδειγμα χρήσης του GTK-Doc από το CMake - -find_package(GtkDoc 1.25 REQUIRED) - -# Create the doc-libmeep target. -gtk_doc_add_module( - libmeep ${CMAKE_SOURCE_DIR}/libmeep - XML meep-docs.xml - LIBRARIES libmeep -) + + Ενσωμάτωση σε συστήματα ελέγχου εκδόσεων -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + Ο εμπειρικός κανόνας είναι ότι αυτά τα αρχεία που επεξεργασθήκατε πρέπει να περάσουν από τον έλεγχο έκδοσης. Για τυπικά έργα, πρόκειται για τα αρχεία: <package>.types, <package>-docs.xml (στο παρελθόν .sgml), <package>-sections.txt, Makefile.am. + Αρχεία στους καταλόγους xml/ και html/ δεν θα πρέπει να υποβληθούν σε έλεγχο έκδοσης. Ούτε και αρχεία xml/ and html/. + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) - - - @@ -425,19 +822,18 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Το GTK-Doc χρησιμοποιεί σχόλια με ειδική σύνταξη για την προσθήκη τεκμηρίωσης στον κώδικα. Παράλληλα, ανακαλεί πληροφορίες για τη δομή του έργου σας από άλλες πηγές. Στην επόμενη ενότητα περιέχονται όλες οι λεπτομέρειες για τη σύνταξη αυτών των σχολίων. - - Τοποθέτηση τεκμηρίωσης - Στο παρελθόν, η τεκμηρίωση έπρεπε να συμπληρώνεται σε αρχεία του καταλόγου tmpl. Αυτή η προσέγγιση εμφανίζει το μειονέκτημα ότι οι πληροφορίες δεν ενημερώνονται συχνά, καθώς και το ότι προκύπτουν περιοδικές συγκρούσεις με τα συστήματα ελέγχου εκδόσεων. - Για να αποφύγετε αυτά τα προβλήματα, σας προτείνουμε να ενσωματώνετε την τεκμηρίωση στον πηγαίο κώδικα. Αυτή είναι και η μόνη μέθοδος που θα περιγράψουμε σε αυτό το εγχειρίδιο. - - - Ο σαρωτής μπορεί να χειρισθεί άνετα την πλειοψηφία των κεφαλίδων C. Σε περίπτωση που παίρνετε προειδοποιήσεις από τον σαρωτή οι οποίες μοιάζουν με έναν ειδικό χαρακτήρα, μπορείτε να υποδείξετε στο GTK-Doc να τους παραλείψει. Μπλοκ σχολίου GTK-Doc - + + 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. + GTK-Doc comment block + - +]]> + + Περιορισμοί @@ -551,7 +947,17 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Μπορείτε να βρείτε περισσότερα παραδείγματα για το ποιες ετικέτες markdown υποστηρίζονται στη διεύθυνση GTK+ Documentation Markdown Syntax Reference. - Όπως αναφέρθηκε και προηγουμένως το GTK-Doc στοχεύει στην τεκμηρίωση του δημόσιου API. Άρα, δεν μπορεί κάποιος να γράψει τεκμηρίωση για στατικά σύμβολα. Παρόλα αυτά, συνιστάται ο σχολιασμός και αυτών των συμβόλων, γιατί βοηθά στην κατανόηση του κώδικα. Σας προτείνουμε λοιπόν να τα σχολιάζετε χρησιμοποιώντας κανονικά σχόλια (χωρίς το δεύτερο «*» στην πρώτη γραμμή). Αν αργότερα χρειαστεί να μετατραπεί η συνάρτηση σε δημόσια, το μόνο που θα πρέπει να γίνει είναι να προστεθεί άλλο ένα «*» στο μπλοκ του σχολίου, και να εισαχθεί το όνομα του συμβόλου στην κατάλληλη θέση του αρχείου ενοτήτων. + + 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. + @@ -1115,7 +1521,7 @@ int main(int argc, char *argv[]) Αν η βιβλιοθήκη ή η εφαρμογή σας περιέχει GObjects, θα θέλετε να εμφανίζονται στην τεκμηρίωση τα σήματα, τα ορίσματα/παράμετροι καθώς και η θέση τους στην ιεραρχία. Για να το πετύχετε, απλά καταγράψτε τις συναρτήσεις xxx_get_type μαζί με την συμπερίληψή τους στο αρχείο <package>.types. - Υπόδειγμα αποσπάσματος αρχείου types + Example <package>.types file #include <gtk/gtk.h> @@ -1309,7 +1715,8 @@ endif containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included - and how the entities are used. The entities can also be used in all + in the master template and how the entities are used. + The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities diff --git a/help/manual/en_GB/index.docbook b/help/manual/en_GB/index.docbook index 9f6faa7..c3afcec 100644 --- a/help/manual/en_GB/index.docbook +++ b/help/manual/en_GB/index.docbook @@ -68,6 +68,12 @@ + 1.29 + 28 Aug 2018 + ss + development + + 1.28 24 Mar 2018 ss @@ -207,7 +213,12 @@ - Writing the documentation. The author fills in the source files with the documentation for each function, macro, union etc. (In the past information was entered in generated template files, which is not recommended any more). + + Writing the documentation. + + The author fills in the source files with the documentation for each + function, macro, structs or unions, etc. + @@ -296,10 +307,20 @@ About GTK-Doc + + 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. + + (FIXME) - (History, authors, web pages, mailing list, license, future plans, + (authors, web pages, mailing list, license, future plans, comparison with other similar systems.) @@ -317,32 +338,94 @@ - Setting up your project + Project Setup - 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 plain - makefiles or other build systems will describe the basics needed to - work in a different build setup. + This Chapter describes the steps that are necessary to integrate GTK-Doc + into your project. The integration of GTK-Doc into a project includes the + following steps: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + + + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. Setting up a skeleton documentation - Under your top-level project directory create a folder 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 + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. + - This can then look as shown below: - Example directory structure + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project - - Integration with autoconf + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + - Very easy! Just add one line to your configure.ac script. + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - Integration with autoconf - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - - 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 - GTK_DOC_CHECK at the start of a line. - Keep gtk-doc optional - + + Integration with automake + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + + +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ + - - - The first argument is used to check for the gtkdocversion at configure time. - The 2nd, optional argument is used by gtkdocize. - The GTK_DOC_CHECK macro also adds several configure switches: - - - --with-html-dir=PATH : path to installed docs - --enable-gtk-doc : use gtk-doc to build documentation [default=no] - --enable-gtk-doc-html : build documentation in html format [default=yes] - --enable-gtk-doc-pdf : build documentation in pdf format [default=no] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. + + 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 + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). - - - GTK-Doc is disabled by default! Remember to pass the option - to the next - configure run. Otherwise pregenerated documentation is installed - (which makes sense for users but not for developers). + All the tools support to list the supported + options. - - - Furthermore it is recommended that you have the following line inside - your configure.ac script. - This allows gtkdocize to automatically copy the - macro definition for GTK_DOC_CHECK to your project. - + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. - - Preparation for gtkdocize - + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + Integration with autoconf + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - - After all changes to configure.ac are made, update - the configure file. This can be done by re-running - autoreconf -i or autogen.sh. - - + + - - Integration with automake + + 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: - - First copy the Makefile.am from the - examples sub directory of the - gtkdoc-sources - to your project's API documentation directory ( - ./docs/reference/<package>). - A local copy should be available under e.g. - /usr/share/doc/gtk-doc-tools/examples/Makefile.am. - If you have multiple doc-packages repeat this for each one. - + + Integration with optional gtk-doc dependency + + + - - The next step is to edit the settings inside the Makefile.am. - 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 . - All the tools support to list the supported - parameters. - + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - + + --with-html-dir=PATH : path to installed docs + --enable-gtk-doc : use gtk-doc to build documentation [default=no] + --enable-gtk-doc-html : build documentation in html format [default=yes] + --enable-gtk-doc-pdf : build documentation in pdf format [default=no] + - + + + GTK-Doc is disabled by default! Remember to pass the option + to the next + configure run. Otherwise pregenerated documentation is installed + (which makes sense for users but not for developers). + + - - Integration with autogen + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - - Most projects will have an autogen.sh 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 - gtkdocize which can be used in such a script. - It should be run before autoheader, automake or autoconf. - + + Integration with autogen - - Running gtkdocize from autogen.sh - + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + + + + It should be run before autoreconf, autoheader, automake or autoconf. + + + + Running gtkdocize from autogen.sh + - - + + - - When running gtkdocize it copies - gtk-doc.make to your project root (or any directory - specified by the option). - It also checks you configure script for the GTK_DOC_CHECK - invocation. This macro can be used to pass extra parameters to - gtkdocize. - + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - - 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. gtkdocize supports now - a 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 GTKDOCIZE_FLAGS - or set as a 2nd parameter in GTK_DOC_CHECK 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). - - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - Running the doc build + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - After the previous steps it is time to run the build. First we need to rerun autogen.sh. If this script runs configure for you, then give it the option. Otherwise manually run configure with this option afterwards. - - The first make run generates several additional files in the doc-directories. - The important ones are: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt. - - - Running the doc build - + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + After the previous steps it is time to run the build. First we need to rerun autogen.sh. If this script runs configure for you, then give it the option. Otherwise manually run configure with this option afterwards. + + The first make run generates several additional files in the doc-directories. + The important ones are: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt. + + + Running the doc build + - - - Now you can point your browser to docs/reference/package/index.html. Yes, it's a bit disappointing still. But hang on; during the next chapter we tell you how to fill the pages with life. + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - Integration with version control systems + + Integration with CMake build systems - As a rule of thumb, it's the files you edit which should go under - version control. For typical projects it's these files: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt, - Makefile.am. + GTK-Doc now provides a GtkDocConfig.cmake module + (and the corresponding GtkDocConfigVersion.cmake + module). This provides a gtk_doc_add_module + command that you can set in your CMakeLists.txt + file. + - Files in the xml/ and html/ - directories should not go under version control. Neither should any of - the .stamp files. + The following example shows how to use this command. + Example of using GTK-Doc from CMake + + - + Integration with plain makefiles or other build systems @@ -566,42 +911,24 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html - - Integration with CMake build systems - - - GTK-Doc now provides a GtkDocConfig.cmake module - (and the corresponding GtkDocConfigVersion.cmake - module). This provides a gtk_doc_add_module - command that you can set in your CMakeLists.txt - file. - - - - The following example shows how to use this command. - Example of using GTK-Doc from CMake - + Integration with version control systems -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + + As a rule of thumb, it's the files you edit which should go under + version control. For typical projects it's these files: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt, + Makefile.am. + + + Files in the xml/ and html/ + directories should not go under version control. Neither should any of + the .stamp files. + + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - - @@ -614,16 +941,10 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html syntax of the comments. - - Documentation placement - In the past most documentation had to be filled into files residing inside the tmpl 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. - To avoid the aforementioned problems we suggest putting the documentation inside the sources. This manual will only describe this way of documenting code. - - - The scanner can handle the majority of C headers fine. In the case of - receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + The GTK-Doc scanner can handle the majority of C headers fine. In the + case of receiving warnings from the scanner that look like a special + case, one can hint GTK-Doc to skip over them. GTK-Doc comment block As already mentioned earlier GTK-Doc is for documenting public API. Thus one cannot write documentation for static symbols. Nevertheless it is good - to comment those symbols too. This helps other to understand you code. + to comment those symbols too. This helps other developers to understand + your code. Therefore we recommend to comment these using normal comments (without the 2nd '*' in the first line). If later the function needs to be made public, all one needs to do is to @@ -1585,7 +1907,7 @@ int main(int argc, char *argv[]) - Example types file snippet + Example <package>.types file @@ -1918,7 +2240,8 @@ endif containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included - and how the entities are used. The entities can also be used in all + in the master template and how the entities are used. + The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities diff --git a/help/manual/es/es.po b/help/manual/es/es.po index d3b136f..969e81e 100644 --- a/help/manual/es/es.po +++ b/help/manual/es/es.po @@ -8,22 +8,22 @@ msgid "" msgstr "" "Project-Id-Version: gtk-doc-help.master\n" -"POT-Creation-Date: 2017-12-28 10:31+0000\n" -"PO-Revision-Date: 2018-02-22 12:50+0100\n" +"POT-Creation-Date: 2018-05-20 18:37+0000\n" +"PO-Revision-Date: 2018-07-31 12:18+0200\n" "Last-Translator: Daniel Mustieles \n" "Language-Team: es \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" -"X-Generator: Gtranslator 2.91.6\n" +"X-Generator: Gtranslator 2.91.7\n" "Plural-Forms: nplurals=2; plural=(n != 1);\n" #. Put one translator per line, in the form NAME , YEAR1, YEAR2 msgctxt "_" msgid "translator-credits" msgstr "" -"Daniel Mustieles , 2009 - 2017\n" +"Daniel Mustieles , 2009 - 2018\n" "Jorge González , 2009 - 2011\n" "Francisco Javier F. Serrador , 2009, 2010" @@ -127,16 +127,29 @@ msgstr "" #: C/index.docbook:83 #| msgid "" #| "1.27.1 07 Dec 2017 " -#| "ss developemnt" +#| "ss development" msgid "" -"1.27.1 07 Dec 2017 ss1.28.1 24 Mar 2018 ss development" msgstr "" -"1.27.1 07 de diciembre de 2017 " +"1.28.1 24 de marzo de 2018 " "ss desarrollo" #. (itstool) path: revhistory/revision #: C/index.docbook:89 +#| msgid "" +#| "1.24 29 May 2015 ss bug fix" +msgid "" +"1.28 24 Mar 2018 ss bug fixes" +msgstr "" +"1.28 24 de marzo de 2018 " +"ss correcciones de errores" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:95 msgid "" "1.27 07 Dec 2017 ss fine tuning of the python port" @@ -146,7 +159,7 @@ msgstr "" "python" #. (itstool) path: revhistory/revision -#: C/index.docbook:95 +#: C/index.docbook:101 msgid "" "1.26 11 Aug 2017 ss port all tools from perl/bash to python" #. (itstool) path: revhistory/revision -#: C/index.docbook:101 +#: C/index.docbook:107 msgid "" "1.25 21 March 2016 ss bug fixes, test cleanups" @@ -167,7 +180,7 @@ msgstr "" "limpieza" #. (itstool) path: revhistory/revision -#: C/index.docbook:107 +#: C/index.docbook:113 msgid "" "1.24 29 May 2015 ss bug fix" @@ -177,7 +190,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:113 +#: C/index.docbook:119 msgid "" "1.23 17 May 2015 ss bug fix" @@ -187,7 +200,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:119 +#: C/index.docbook:125 msgid "" "1.22 07 May 2015 ss bug fixes, dropping deprecated features" #. (itstool) path: revhistory/revision -#: C/index.docbook:125 +#: C/index.docbook:131 msgid "" "1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" #. (itstool) path: revhistory/revision -#: C/index.docbook:131 +#: C/index.docbook:137 msgid "" "1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" #. (itstool) path: revhistory/revision -#: C/index.docbook:137 +#: C/index.docbook:143 msgid "" "1.19 05 Jun 2013 ss bug fixes" @@ -230,7 +243,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:143 +#: C/index.docbook:149 msgid "" "1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" @@ -240,7 +253,7 @@ msgstr "" "mejoras en la velocidad y soporte de marcado" #. (itstool) path: revhistory/revision -#: C/index.docbook:149 +#: C/index.docbook:155 msgid "" "1.17 26 Feb 2011 sk urgent bug fix update" @@ -250,7 +263,7 @@ msgstr "" "corrección de error" #. (itstool) path: revhistory/revision -#: C/index.docbook:155 +#: C/index.docbook:161 msgid "" "1.16 14 Jan 2011 sk bugfixes, layout improvements" @@ -260,7 +273,7 @@ msgstr "" "mejoras en la distribución" #. (itstool) path: revhistory/revision -#: C/index.docbook:161 +#: C/index.docbook:167 msgid "" "1.15 21 May 2010 sk bug and regression fixes" @@ -270,7 +283,7 @@ msgstr "" "regresiones" #. (itstool) path: revhistory/revision -#: C/index.docbook:167 +#: C/index.docbook:173 msgid "" "1.14 28 March 2010 sk bugfixes and performance improvements" @@ -280,7 +293,7 @@ msgstr "" "mejoras en el rendimiento" #. (itstool) path: revhistory/revision -#: C/index.docbook:173 +#: C/index.docbook:179 msgid "" "1.13 18 December 2009 " "sk broken tarball update" #. (itstool) path: revhistory/revision -#: C/index.docbook:179 +#: C/index.docbook:185 msgid "" "1.12 18 December 2009 " "sk new tool features and " @@ -302,7 +315,7 @@ msgstr "" "nuevas características" #. (itstool) path: revhistory/revision -#: C/index.docbook:185 +#: C/index.docbook:191 msgid "" "1.11 16 November 2008 " "mal GNOME doc-utils migration" #. (itstool) path: chapter/title -#: C/index.docbook:198 +#: C/index.docbook:204 msgid "Introduction" msgstr "Introducción" #. (itstool) path: chapter/para -#: C/index.docbook:200 +#: C/index.docbook:206 msgid "" "This chapter introduces GTK-Doc and gives an overview of what it is and how " "it is used." @@ -327,12 +340,12 @@ msgstr "" "es y cómo usarlo." #. (itstool) path: sect1/title -#: C/index.docbook:206 +#: C/index.docbook:212 msgid "What is GTK-Doc?" msgstr "¿Qué es GTK-Doc?" #. (itstool) path: sect1/para -#: C/index.docbook:208 +#: C/index.docbook:214 msgid "" "GTK-Doc is used to document C code. It is typically used to document the " "public API of libraries, such as the GTK+ and GNOME libraries. But it can " @@ -343,12 +356,12 @@ msgstr "" "Pero también se puede usar para documentar código de aplicaciones." #. (itstool) path: sect1/title -#: C/index.docbook:216 +#: C/index.docbook:222 msgid "How Does GTK-Doc Work?" msgstr "¿Cómo funciona GTK-Doc?" #. (itstool) path: sect1/para -#: C/index.docbook:218 +#: C/index.docbook:224 msgid "" "GTK-Doc works by using documentation of functions placed inside the source " "files in specially-formatted comment blocks, or documentation added to the " @@ -363,7 +376,7 @@ msgstr "" "archivos de cabecera; no produce salida para funciones estáticas)." #. (itstool) path: sect1/para -#: C/index.docbook:225 +#: C/index.docbook:231 msgid "" "GTK-Doc consists of a number of python scripts, each performing a different " "step in the process." @@ -372,12 +385,12 @@ msgstr "" "diferente en el proceso." #. (itstool) path: sect1/para -#: C/index.docbook:230 +#: C/index.docbook:236 msgid "There are 5 main steps in the process:" msgstr "Existen 5 pasos importantes en el proceso:" #. (itstool) path: listitem/para -#: C/index.docbook:237 +#: C/index.docbook:243 msgid "" "Writing the documentation. The author fills in the " "source files with the documentation for each function, macro, union etc. (In " @@ -390,7 +403,7 @@ msgstr "" "lo que ya no se recomienda)." #. (itstool) path: listitem/para -#: C/index.docbook:247 +#: C/index.docbook:253 msgid "" "Gathering information about the code. " "gtkdoc-scan scans the header files of the code " @@ -426,7 +439,7 @@ msgstr "" "txt dentro de <module>-overrides.txt." #. (itstool) path: listitem/para -#: C/index.docbook:264 +#: C/index.docbook:270 msgid "" "gtkdoc-scangobj can also be used to dynamically " "query a library about any GObject subclasses it exports. It saves " @@ -440,7 +453,7 @@ msgstr "" "que proporciona." #. (itstool) path: listitem/para -#: C/index.docbook:270 +#: C/index.docbook:276 msgid "" "gtkdoc-scanobj should not be used anymore. It was " "needed in the past when GObject was still GtkObject inside gtk+." @@ -449,7 +462,7 @@ msgstr "" "necesitó en el pasado, cuando GObject todavía era GtkObject dentro de GTK+." #. (itstool) path: listitem/para -#: C/index.docbook:277 +#: C/index.docbook:283 msgid "" "Generating the XML and HTML/PDF. gtkdoc-" "mkdb turns the template files into XML files in the gtkdoc-mkhtml turns the XML files into HTML files " "in the html/ subdirectory. Likewise " @@ -480,7 +493,7 @@ msgstr "" "paquete>.pdf." #. (itstool) path: listitem/para -#: C/index.docbook:292 +#: C/index.docbook:298 msgid "" "Files in xml/ and html/ directories are always overwritten. One " @@ -491,7 +504,7 @@ msgstr "" "Nunca se deben editar directamente." #. (itstool) path: listitem/para -#: C/index.docbook:300 +#: C/index.docbook:306 msgid "" "Fixing up cross-references between documents. After " "installing the HTML files, gtkdoc-fixxref can be " @@ -514,17 +527,17 @@ msgstr "" "esa documentación está instalada)." #. (itstool) path: sect1/title -#: C/index.docbook:318 +#: C/index.docbook:324 msgid "Getting GTK-Doc" msgstr "Obtener GTK-Doc" #. (itstool) path: sect2/title -#: C/index.docbook:321 +#: C/index.docbook:327 msgid "Requirements" msgstr "Requerimientos" #. (itstool) path: sect2/para -#: C/index.docbook:322 +#: C/index.docbook:328 msgid "" "python 2/3 - the main scripts are written in python." msgstr "" @@ -532,7 +545,7 @@ msgstr "" "python." #. (itstool) path: sect2/para -#: C/index.docbook:325 +#: C/index.docbook:331 msgid "" "xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" @@ -541,7 +554,7 @@ msgstr "" "\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/" #. (itstool) path: sect2/para -#: C/index.docbook:329 +#: C/index.docbook:335 msgid "" "docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" #. (itstool) path: sect2/para -#: C/index.docbook:333 +#: C/index.docbook:339 msgid "" "One of source-highlight, highlight " "or vim - optional - used for syntax highlighting of " @@ -563,17 +576,17 @@ msgstr "" "los ejemplos." #. (itstool) path: sect1/title -#: C/index.docbook:341 +#: C/index.docbook:347 msgid "About GTK-Doc" msgstr "Acerca de GTK-Doc" #. (itstool) path: sect1/para -#: C/index.docbook:343 C/index.docbook:357 +#: C/index.docbook:349 C/index.docbook:363 msgid "(FIXME)" msgstr "(ARRÉGLAME)" #. (itstool) path: sect1/para -#: C/index.docbook:347 +#: C/index.docbook:353 msgid "" "(History, authors, web pages, mailing list, license, future plans, " "comparison with other similar systems.)" @@ -582,22 +595,22 @@ msgstr "" "futuros, comparación con otros sistemas similares.)" #. (itstool) path: sect1/title -#: C/index.docbook:355 +#: C/index.docbook:361 msgid "About this Manual" msgstr "Acerca de este manual" #. (itstool) path: sect1/para -#: C/index.docbook:361 +#: C/index.docbook:367 msgid "(who it is meant for, where you can get it, license)" msgstr "(a quién está dirigido, dónde puede obtenerse, licencia)" #. (itstool) path: chapter/title -#: C/index.docbook:370 +#: C/index.docbook:376 msgid "Setting up your project" msgstr "Configurando su proyecto" #. (itstool) path: chapter/para -#: C/index.docbook:372 +#: C/index.docbook:378 msgid "" "The next sections describe what steps to perform to integrate GTK-Doc into " "your project. Theses sections assume we work on a project called 'meep'. " @@ -617,12 +630,12 @@ msgstr "" "construcción diferente." #. (itstool) path: sect1/title -#: C/index.docbook:383 +#: C/index.docbook:389 msgid "Setting up a skeleton documentation" msgstr "Configurar el esquema de la documentación" #. (itstool) path: sect1/para -#: C/index.docbook:385 +#: C/index.docbook:391 msgid "" "Under your top-level project directory create folders called docs/reference " "(this way you can also have docs/help for end-user documentation). It is " @@ -635,12 +648,12 @@ msgstr "" "Para paquetes con una sola biblioteca este paso no es necesario." #. (itstool) path: example/title -#: C/index.docbook:394 +#: C/index.docbook:400 msgid "Example directory structure" msgstr "Ejemplo de estructura de carpetas" #. (itstool) path: example/programlisting -#: C/index.docbook:395 +#: C/index.docbook:401 #, no-wrap msgid "" "\n" @@ -664,18 +677,18 @@ msgstr "" " meeper/\n" #. (itstool) path: sect1/para -#: C/index.docbook:392 +#: C/index.docbook:398 msgid "This can then look as shown below: <_:example-1/>" msgstr "Esto después aparecerá como se muestra debajo: <_:example-1/>" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:410 C/index.docbook:417 +#: C/index.docbook:416 C/index.docbook:423 msgid "Integration with autoconf" msgstr "Integración con autoconf" #. (itstool) path: sect1/para -#: C/index.docbook:412 +#: C/index.docbook:418 msgid "" "Very easy! Just add one line to your configure.ac " "script." @@ -684,7 +697,7 @@ msgstr "" "filename>." #. (itstool) path: example/programlisting -#: C/index.docbook:418 +#: C/index.docbook:424 #, no-wrap msgid "" "\n" @@ -696,12 +709,12 @@ msgstr "" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" #. (itstool) path: example/title -#: C/index.docbook:430 +#: C/index.docbook:436 msgid "Keep gtk-doc optional" msgstr "Mantener gtk-doc como opcional" #. (itstool) path: example/programlisting -#: C/index.docbook:431 +#: C/index.docbook:437 #, no-wrap msgid "" "\n" @@ -721,7 +734,7 @@ msgstr "" "])\n" #. (itstool) path: sect1/para -#: C/index.docbook:425 +#: C/index.docbook:431 msgid "" "This will require all developers to have gtk-doc installed. If it is okay " "for your project to have optional api-doc build setup, you can solve this as " @@ -735,7 +748,7 @@ msgstr "" "<_:example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:442 +#: C/index.docbook:448 msgid "" "The first argument is used to check for the gtkdocversion at configure time. " "The 2nd, optional argument is used by gtkdocize. " @@ -748,19 +761,19 @@ msgstr "" "symbol> también añade diversas opciones de configuración:" #. (itstool) path: listitem/para -#: C/index.docbook:448 +#: C/index.docbook:454 msgid "--with-html-dir=PATH : path to installed docs" msgstr "--with-html-dir=RUTA: ruta a los documentos instalados" #. (itstool) path: listitem/para -#: C/index.docbook:449 +#: C/index.docbook:455 msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "" "--enable-gtk-doc: usar gtk-doc para construir la documentación " "[predeterminado=no]" #. (itstool) path: listitem/para -#: C/index.docbook:450 +#: C/index.docbook:456 msgid "" "--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" @@ -768,14 +781,14 @@ msgstr "" "[predeterminado=sí]" #. (itstool) path: listitem/para -#: C/index.docbook:451 +#: C/index.docbook:457 msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" msgstr "" "--enable-gtk-doc: usar gtk-doc para construir la documentación " "[predeterminado=no]" #. (itstool) path: important/para -#: C/index.docbook:455 +#: C/index.docbook:461 msgid "" "GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " @@ -789,7 +802,7 @@ msgstr "" "desarrolladores)." #. (itstool) path: sect1/para -#: C/index.docbook:463 +#: C/index.docbook:469 msgid "" "Furthermore it is recommended that you have the following line inside your " "configure.ac script. This allows " @@ -802,12 +815,12 @@ msgstr "" "GTK_DOC_CHECK a su proyecto." #. (itstool) path: example/title -#: C/index.docbook:471 +#: C/index.docbook:477 msgid "Preparation for gtkdocize" msgstr "Preparación para gtkdocize" #. (itstool) path: example/programlisting -#: C/index.docbook:472 +#: C/index.docbook:478 #, no-wrap msgid "" "\n" @@ -817,7 +830,7 @@ msgstr "" "AC_CONFIG_MACRO_DIR(m4)\n" #. (itstool) path: sect1/para -#: C/index.docbook:477 +#: C/index.docbook:483 msgid "" "After all changes to configure.ac are made, update the " "configure file. This can be done by re-running " @@ -828,12 +841,12 @@ msgstr "" "volviendo a ejecutar autoreconf -i o autogen.sh." #. (itstool) path: sect1/title -#: C/index.docbook:485 +#: C/index.docbook:491 msgid "Integration with automake" msgstr "Integración con automake" #. (itstool) path: sect1/para -#: C/index.docbook:487 +#: C/index.docbook:493 msgid "" "First copy the Makefile.am from the examples sub directory of the Makefile.am. All the settings have a comment above that describes their " @@ -871,12 +884,12 @@ msgstr "" "soportan para listar los parámetros que soportan." #. (itstool) path: sect1/title -#: C/index.docbook:512 +#: C/index.docbook:518 msgid "Integration with autogen" msgstr "Integración con autogen" #. (itstool) path: sect1/para -#: C/index.docbook:514 +#: C/index.docbook:520 msgid "" "Most projects will have an autogen.sh script to setup " "the build infrastructure after a checkout from version control system (such " @@ -892,12 +905,12 @@ msgstr "" "automake o autoconf." #. (itstool) path: example/title -#: C/index.docbook:523 +#: C/index.docbook:529 msgid "Running gtkdocize from autogen.sh" msgstr "Ejecutar gtkdocize desde autogen.sh" #. (itstool) path: example/programlisting -#: C/index.docbook:524 +#: C/index.docbook:530 #, no-wrap msgid "" "\n" @@ -907,7 +920,7 @@ msgstr "" "gtkdocize || exit 1\n" #. (itstool) path: sect1/para -#: C/index.docbook:530 +#: C/index.docbook:536 msgid "" "When running gtkdocize it copies gtk-" "doc.make to your project root (or any directory specified by the " @@ -923,7 +936,7 @@ msgstr "" "gtkdocize." #. (itstool) path: sect1/para -#: C/index.docbook:539 +#: C/index.docbook:545 msgid "" "Historically GTK-Doc was generating template files where developers entered " "the docs. This turned out to be not so good (e.g. the need for having " @@ -957,12 +970,12 @@ msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:556 C/index.docbook:573 +#: C/index.docbook:562 C/index.docbook:579 msgid "Running the doc build" msgstr "Ejecutar la construcción de la documentación" #. (itstool) path: sect1/para -#: C/index.docbook:558 +#: C/index.docbook:564 msgid "" "After the previous steps it's time to run the build. First we need to rerun " "autogen.sh. If this script runs configure for you, then " @@ -976,7 +989,7 @@ msgstr "" "configure con esta opción." #. (itstool) path: sect1/para -#: C/index.docbook:565 +#: C/index.docbook:571 msgid "" "The first make run generates several additional files in the doc-" "directories. The important ones are: <package>.types<paquete>-sections.txt." #. (itstool) path: example/programlisting -#: C/index.docbook:574 +#: C/index.docbook:580 #, no-wrap msgid "" "\n" @@ -1001,7 +1014,7 @@ msgstr "" "make\n" #. (itstool) path: sect1/para -#: C/index.docbook:580 +#: C/index.docbook:586 msgid "" "Now you can point your browser to docs/reference/<package>/" "index.html. Yes, it's a bit disappointing still. But hang-on, " @@ -1013,12 +1026,12 @@ msgstr "" "información." #. (itstool) path: sect1/title -#: C/index.docbook:588 +#: C/index.docbook:594 msgid "Integration with version control systems" msgstr "Integración con los sistemas de control de versiones" #. (itstool) path: sect1/para -#: C/index.docbook:590 +#: C/index.docbook:596 msgid "" "As a rule of thumb, it's the files you edit which should go under version " "control. For typical projects it's these files: <package>." @@ -1033,7 +1046,7 @@ msgstr "" "txt, Makefile.am." #. (itstool) path: sect1/para -#: C/index.docbook:598 +#: C/index.docbook:604 msgid "" "Files in the xml/ and html/ " "directories should not go under version control. Neither should any of the " @@ -1044,12 +1057,12 @@ msgstr "" "los archivos .stamp." #. (itstool) path: sect1/title -#: C/index.docbook:606 +#: C/index.docbook:612 msgid "Integration with plain makefiles or other build systems" msgstr "Integración con makefiles u otros sistemas de construcción" #. (itstool) path: sect1/para -#: C/index.docbook:608 +#: C/index.docbook:614 msgid "" "In the case one does not want to use automake and therefore gtk-" "doc.mak one will need to call the gtkdoc tools in the right order " @@ -1060,12 +1073,12 @@ msgstr "" "makefiles propios (o en otras herramientas de construcción)." #. (itstool) path: example/title -#: C/index.docbook:615 +#: C/index.docbook:621 msgid "Documentation build steps" msgstr "Pasos de construcción de la documentación" #. (itstool) path: example/programlisting -#: C/index.docbook:616 +#: C/index.docbook:622 #, no-wrap msgid "" "\n" @@ -1091,7 +1104,7 @@ msgstr "" "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" #. (itstool) path: sect1/para -#: C/index.docbook:630 +#: C/index.docbook:636 msgid "" "One will need to look at the Makefile.am and " "gtk-doc.mak to pick the extra options needed." @@ -1100,12 +1113,12 @@ msgstr "" "doc.mak para elegir las opciones adicionales necesarias." #. (itstool) path: sect1/title -#: C/index.docbook:637 +#: C/index.docbook:643 msgid "Integration with CMake build systems" msgstr "Integración con sistemas de construcción CMake" #. (itstool) path: sect1/para -#: C/index.docbook:639 +#: C/index.docbook:645 msgid "" "GTK-Doc now provides a GtkDocConfig.cmake module (and " "the corresponding GtkDocConfigVersion.cmake module). " @@ -1119,12 +1132,12 @@ msgstr "" "filename>." #. (itstool) path: example/title -#: C/index.docbook:649 +#: C/index.docbook:655 msgid "Example of using GTK-Doc from CMake" msgstr "Ejeplo de uso de GTK-Doc desde CMake" #. (itstool) path: example/programlisting -#: C/index.docbook:650 +#: C/index.docbook:656 #, no-wrap msgid "" "\n" @@ -1166,17 +1179,17 @@ msgstr "" " DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" #. (itstool) path: sect1/para -#: C/index.docbook:647 +#: C/index.docbook:653 msgid "The following example shows how to use this command. <_:example-1/>" msgstr "El siguiente ejemplo muestra cómo usar este comando. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:675 +#: C/index.docbook:681 msgid "Documenting the code" msgstr "Documentar el código" #. (itstool) path: chapter/para -#: C/index.docbook:677 +#: C/index.docbook:683 msgid "" "GTK-Doc uses source code comment with a special syntax for code " "documentation. Further it retrieves information about your project structure " @@ -1189,12 +1202,12 @@ msgstr "" "acerca de la sintaxis de los comentarios." #. (itstool) path: note/title -#: C/index.docbook:685 +#: C/index.docbook:691 msgid "Documentation placement" msgstr "Ubicación de la documentación" #. (itstool) path: note/para -#: C/index.docbook:686 +#: C/index.docbook:692 msgid "" "In the past most documentation had to be filled into files residing inside " "the tmpl directory. This has the disadvantages that the " @@ -1208,7 +1221,7 @@ msgstr "" "conflictos con los sistemas de control de versiones." #. (itstool) path: note/para -#: C/index.docbook:692 +#: C/index.docbook:698 msgid "" "The avoid the aforementioned problems we suggest putting the documentation " "inside the sources. This manual will only describe this way of documenting " @@ -1219,12 +1232,12 @@ msgstr "" "documentar el código." #. (itstool) path: example/title -#: C/index.docbook:703 C/index.docbook:729 +#: C/index.docbook:709 C/index.docbook:735 msgid "GTK-Doc comment block" msgstr "Bloque de comentario de GTK-Doc" #. (itstool) path: example/programlisting -#: C/index.docbook:704 +#: C/index.docbook:710 #, no-wrap msgid "" "\n" @@ -1238,7 +1251,7 @@ msgstr "" "#endif\n" #. (itstool) path: chapter/para -#: C/index.docbook:699 +#: C/index.docbook:705 msgid "" "The scanner can handle the majority of C headers fine. In the case of " "receiving warnings from the scanner that look like a special case, one can " @@ -1249,12 +1262,12 @@ msgstr "" "GTK-Doc que los omita. <_:example-1/>" #. (itstool) path: note/title -#: C/index.docbook:713 +#: C/index.docbook:719 msgid "Limitations" msgstr "Limitaciones" #. (itstool) path: note/para -#: C/index.docbook:714 +#: C/index.docbook:720 msgid "" "Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but " "not #if !defined(__GTK_DOC_IGNORE__) or other combinations." @@ -1263,12 +1276,12 @@ msgstr "" "pero #if !defined(__GTK_DOC_IGNORE__) u otras combinaciones." #. (itstool) path: sect1/title -#: C/index.docbook:724 +#: C/index.docbook:730 msgid "Documentation comments" msgstr "Comentarios de la documentación" #. (itstool) path: example/programlisting -#: C/index.docbook:730 +#: C/index.docbook:736 #, no-wrap msgid "" "\n" @@ -1284,7 +1297,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:726 +#: C/index.docbook:732 msgid "" "A multiline comment that starts with an additional '*' marks a documentation " "block that will be processed by the GTK-Doc tools. <_:example-1/>" @@ -1293,7 +1306,7 @@ msgstr "" "bloque de documentación que GTK-Doc tools procesarán. <_:example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:739 +#: C/index.docbook:745 msgid "" "The 'identifier' is one line with the name of the item the comment is " "related to. The syntax differs a little depending on the item. (TODO add " @@ -1304,7 +1317,7 @@ msgstr "" "hacer: añadir una tabla mostrando los identificadores)" #. (itstool) path: sect1/para -#: C/index.docbook:745 +#: C/index.docbook:751 msgid "" "The 'documentation' block is also different for each symbol type. Symbol " "types that get parameters such as functions or macros have the parameter " @@ -1324,7 +1337,7 @@ msgstr "" "espacio). Esto es útil para texto preformateado (listados de código)." #. (itstool) path: listitem/para -#: C/index.docbook:762 +#: C/index.docbook:768 msgid "" "What it is: The name for a class or function can sometimes be misleading for " "people coming from a different background." @@ -1333,24 +1346,24 @@ msgstr "" "personas que provengan de otros entornos." #. (itstool) path: listitem/para -#: C/index.docbook:768 +#: C/index.docbook:774 msgid "" "What it does: Tell about common uses. Put it in relation with the other API." msgstr "Qué hace: indique los usos comunes, en relación con las otras API." #. (itstool) path: tip/para -#: C/index.docbook:758 +#: C/index.docbook:764 msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" msgstr "Al documentar código, describa dos aspectos: <_:itemizedlist-1/>" #. (itstool) path: listitem/para -#: C/index.docbook:783 +#: C/index.docbook:789 msgid "Use function() to refer to functions or macros which take arguments." msgstr "" "Use función() para referirse a funciones o macros que toman argumentos." #. (itstool) path: listitem/para -#: C/index.docbook:788 +#: C/index.docbook:794 msgid "" "Use @param to refer to parameters. Also use this when referring to " "parameters of other functions, related to the one being described." @@ -1359,12 +1372,12 @@ msgstr "" "parámetros de otras funciones, relacionados al que se describe." #. (itstool) path: listitem/para -#: C/index.docbook:794 +#: C/index.docbook:800 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "Use %constant para referirse a una constante, ej: %G_TRAVERSE_LEAFS." #. (itstool) path: listitem/para -#: C/index.docbook:799 +#: C/index.docbook:805 msgid "" "Use #symbol to refer to other types of symbol, e.g. structs and enums and " "macros which don't take arguments." @@ -1373,17 +1386,17 @@ msgstr "" "estructuras, enumeraciones y macros que no toman argumentos." #. (itstool) path: listitem/para -#: C/index.docbook:805 +#: C/index.docbook:811 msgid "Use #Object::signal to refer to a GObject signal." msgstr "Use #Object::signal para referirse a una señal de GObject." #. (itstool) path: listitem/para -#: C/index.docbook:810 +#: C/index.docbook:816 msgid "Use #Object:property to refer to a GObject property." msgstr "Use #Object:property para referirse a una propiedad de GObject." #. (itstool) path: listitem/para -#: C/index.docbook:815 +#: C/index.docbook:821 msgid "" "Use #Struct.field to refer to a field inside a structure and #GObjectClass." "foo_bar() to refer to a vmethod." @@ -1392,7 +1405,7 @@ msgstr "" "#GObjectClass.foo_bar() para referirse a un vmethod." #. (itstool) path: sect1/para -#: C/index.docbook:777 +#: C/index.docbook:783 msgid "" "One advantage of hyper-text over plain-text is the ability to have links in " "the document. Writing the correct markup for a link can be tedious though. " @@ -1405,7 +1418,7 @@ msgstr "" "itemizedlist-1/>" #. (itstool) path: tip/para -#: C/index.docbook:824 +#: C/index.docbook:830 msgid "" "If you need to use the special characters '<', '>', '()', '@', '%', or " "'#' in your documentation without GTK-Doc changing them you can use the XML " @@ -1420,7 +1433,7 @@ msgstr "" "doble «\\»." #. (itstool) path: sect1/para -#: C/index.docbook:833 +#: C/index.docbook:839 msgid "" "DocBook can do more than just links. One can also have lists, examples, " "headings, and images. As of version 1.20, the preferred way is to use a " @@ -1438,7 +1451,7 @@ msgstr "" "elementos de una lista aparecerán como líneas que empiezan con un guión." #. (itstool) path: sect1/para -#: C/index.docbook:844 +#: C/index.docbook:850 msgid "" "While markdown is now preferred one can mix both. One limitation here is " "that one can use docbook xml within markdown, but markdown within docbook " @@ -1449,7 +1462,7 @@ msgstr "" "xml no está soportado." #. (itstool) path: sect1/para -#: C/index.docbook:850 +#: C/index.docbook:856 msgid "" "In older GTK-Doc releases, if you need support for additional formatting, " "you would need to enable the usage of docbook XML tags inside doc-comments " @@ -1464,12 +1477,12 @@ msgstr "" "Makefile.am." #. (itstool) path: example/title -#: C/index.docbook:859 +#: C/index.docbook:865 msgid "GTK-Doc comment block using Markdown" msgstr "Bloque de comentario de GTK-Doc usando marcado" #. (itstool) path: example/programlisting -#: C/index.docbook:860 +#: C/index.docbook:866 #, no-wrap msgid "" "\n" @@ -1545,7 +1558,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:899 +#: C/index.docbook:905 msgid "" "More examples of what markdown tags are supported can be found in the ." #. (itstool) path: tip/para -#: C/index.docbook:905 +#: C/index.docbook:911 msgid "" "As already mentioned earlier GTK-Doc is for documenting public API. Thus one " "cannot write documentation for static symbols. Nevertheless it is good to " @@ -1578,12 +1591,12 @@ msgstr "" "secciones." #. (itstool) path: sect1/title -#: C/index.docbook:919 +#: C/index.docbook:925 msgid "Documenting sections" msgstr "Documentar secciones" #. (itstool) path: sect1/para -#: C/index.docbook:921 +#: C/index.docbook:927 msgid "" "Each section of the documentation contains information about one class or " "module. To introduce the component one can write a section block. The short " @@ -1596,12 +1609,12 @@ msgstr "" "los campos @ son opcionales." #. (itstool) path: example/title -#: C/index.docbook:929 +#: C/index.docbook:935 msgid "Section comment block" msgstr "Bloque de comentarios en una sección" #. (itstool) path: example/programlisting -#: C/index.docbook:930 +#: C/index.docbook:936 #, no-wrap msgid "" "\n" @@ -1633,12 +1646,12 @@ msgstr "" " */\n" #. (itstool) path: varlistentry/term -#: C/index.docbook:949 +#: C/index.docbook:955 msgid "SECTION:<name>" msgstr "SECCIÓN <nombre>" #. (itstool) path: listitem/para -#: C/index.docbook:951 +#: C/index.docbook:957 msgid "" "The name links the section documentation to the respective part in the " "<package>-sections.txt file. The name given here " @@ -1651,12 +1664,12 @@ msgstr "" "archivo <paquete>-sections.txt." #. (itstool) path: varlistentry/term -#: C/index.docbook:960 +#: C/index.docbook:966 msgid "@short_description" msgstr "@short_description" #. (itstool) path: listitem/para -#: C/index.docbook:962 +#: C/index.docbook:968 msgid "" "A one line description of the section, that later will appear after the " "links in the TOC and at the top of the section page." @@ -1665,12 +1678,12 @@ msgstr "" "TOC y en la página de la sección." #. (itstool) path: varlistentry/term -#: C/index.docbook:969 +#: C/index.docbook:975 msgid "@title" msgstr "@title" #. (itstool) path: listitem/para -#: C/index.docbook:971 +#: C/index.docbook:977 msgid "" "The section title defaults to <name> from the SECTION declaration. It " "can be overridden with the @title field." @@ -1679,12 +1692,12 @@ msgstr "" "declaración SECTION. Se puede sobrescribir con el campo @title." #. (itstool) path: varlistentry/term -#: C/index.docbook:978 +#: C/index.docbook:984 msgid "@section_id" msgstr "@section_id" #. (itstool) path: listitem/para -#: C/index.docbook:980 +#: C/index.docbook:986 msgid "" "Overrides the use of title as a section identifier. For GObjects the <" "title> is used as a section_id and for other sections it is <" @@ -1695,22 +1708,22 @@ msgstr "" "para otra sección es <MÓDULO>-<title>." #. (itstool) path: varlistentry/term -#: C/index.docbook:988 +#: C/index.docbook:994 msgid "@see_also" msgstr "@see_also" #. (itstool) path: listitem/para -#: C/index.docbook:990 +#: C/index.docbook:996 msgid "A list of symbols that are related to this section." msgstr "Una lista de símbolos relacionados con esta sección." #. (itstool) path: varlistentry/term -#: C/index.docbook:996 +#: C/index.docbook:1002 msgid "@stability" msgstr "@stability" #. (itstool) path: listitem/para -#: C/index.docbook:1003 +#: C/index.docbook:1009 msgid "" "Stable - The intention of a Stable interface is to enable arbitrary third " "parties to develop applications to these interfaces, release them, and have " @@ -1728,7 +1741,7 @@ msgstr "" "de haberlos habrá buenas razones para ello." #. (itstool) path: listitem/para -#: C/index.docbook:1015 +#: C/index.docbook:1021 msgid "" "Unstable - Unstable interfaces are experimental or transitional. They are " "typically used to give outside developers early access to new or rapidly " @@ -1744,7 +1757,7 @@ msgstr "" "publicación menor a la siguiente." #. (itstool) path: listitem/para -#: C/index.docbook:1027 +#: C/index.docbook:1033 msgid "" "Private - An interface that can be used within the GNOME stack itself, but " "that is not documented for end-users. Such functions should only be used in " @@ -1755,7 +1768,7 @@ msgstr "" "deberían usar de formas especificadas y documentadas." #. (itstool) path: listitem/para -#: C/index.docbook:1036 +#: C/index.docbook:1042 msgid "" "Internal - An interface that is internal to a module and does not require " "end-user documentation. Functions that are undocumented are assumed to be " @@ -1766,7 +1779,7 @@ msgstr "" "son internas." #. (itstool) path: listitem/para -#: C/index.docbook:998 +#: C/index.docbook:1004 msgid "" "An informal description of the stability level this API has. We recommend " "the use of one of these terms: <_:itemizedlist-1/>" @@ -1775,12 +1788,12 @@ msgstr "" "recomienda el uso de uno de estos términos: <_:itemizedlist-1/>" #. (itstool) path: varlistentry/term -#: C/index.docbook:1048 +#: C/index.docbook:1054 msgid "@include" msgstr "@include" #. (itstool) path: listitem/para -#: C/index.docbook:1050 +#: C/index.docbook:1056 msgid "" "The #include files to show in the section synopsis (a " "comma separated list), overriding the global value from the --default-stability argument to " @@ -1909,17 +1922,17 @@ msgstr "" "siguientes valores." #. (itstool) path: variablelist/title -#: C/index.docbook:1128 +#: C/index.docbook:1134 msgid "Stability Tags" msgstr "Etiquetas de estabilidad" #. (itstool) path: varlistentry/term -#: C/index.docbook:1129 +#: C/index.docbook:1135 msgid "Stability: Stable" msgstr "Estabilidad: estable" #. (itstool) path: listitem/para -#: C/index.docbook:1131 +#: C/index.docbook:1137 msgid "" "Mark the element as stable. This is for public APIs which are guaranteed to " "remain stable for all future minor releases of the project." @@ -1929,12 +1942,12 @@ msgstr "" "proyecto." #. (itstool) path: varlistentry/term -#: C/index.docbook:1138 +#: C/index.docbook:1144 msgid "Stability: Unstable" msgstr "Estabilidad: inestable" #. (itstool) path: listitem/para -#: C/index.docbook:1140 +#: C/index.docbook:1146 msgid "" "Mark the element as unstable. This is for public APIs which are released as " "a preview before being stabilised." @@ -1943,12 +1956,12 @@ msgstr "" "publican como versión previa antes de estabilizarse." #. (itstool) path: varlistentry/term -#: C/index.docbook:1146 +#: C/index.docbook:1152 msgid "Stability: Private" msgstr "Estabilidad: privado" #. (itstool) path: listitem/para -#: C/index.docbook:1148 +#: C/index.docbook:1154 msgid "" "Mark the element as private. This is for interfaces which can be used by " "tightly coupled modules, but not by arbitrary third parties." @@ -1957,7 +1970,7 @@ msgstr "" "en módulos fuertemente acoplados, pero no en terceras partes aleatorias." #. (itstool) path: example/programlisting -#: C/index.docbook:1158 +#: C/index.docbook:1164 #, no-wrap msgid "" "\n" @@ -1996,12 +2009,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1178 C/index.docbook:1188 +#: C/index.docbook:1184 C/index.docbook:1194 msgid "Annotations" msgstr "Anotaciones" #. (itstool) path: sect2/para -#: C/index.docbook:1180 +#: C/index.docbook:1186 msgid "" "Documentation blocks can contain annotation-tags. These tags will be " "rendered with tooltips describing their meaning. The tags are used by " @@ -2017,7 +2030,7 @@ msgstr "" "type=\"http\">el wiki." #. (itstool) path: example/programlisting -#: C/index.docbook:1189 +#: C/index.docbook:1195 #, no-wrap msgid "" "\n" @@ -2058,12 +2071,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1210 C/index.docbook:1239 +#: C/index.docbook:1216 C/index.docbook:1245 msgid "Function comment block" msgstr "Bloque de comentario de función" #. (itstool) path: listitem/para -#: C/index.docbook:1216 +#: C/index.docbook:1222 msgid "" "Document whether returned objects, lists, strings, etc, should be freed/" "unrefed/released." @@ -2072,26 +2085,26 @@ msgstr "" "debería liberarse/desreferenciarse/etc." #. (itstool) path: listitem/para -#: C/index.docbook:1222 +#: C/index.docbook:1228 msgid "Document whether parameters can be NULL, and what happens if they are." msgstr "" "El documento, dependiendo de si sus parámetros pueden ser nulos, y qué " "sucede si lo son." #. (itstool) path: listitem/para -#: C/index.docbook:1227 +#: C/index.docbook:1233 msgid "" "Mention interesting pre-conditions and post-conditions where appropriate." msgstr "" "Mencionar precondiciones y postcondiciones interesantes donde sea apropiado." #. (itstool) path: sect2/para -#: C/index.docbook:1212 C/index.docbook:1298 +#: C/index.docbook:1218 C/index.docbook:1304 msgid "Please remember to: <_:itemizedlist-1/>" msgstr "Recuerde: <_:itemizedlist-1/>" #. (itstool) path: sect2/para -#: C/index.docbook:1234 +#: C/index.docbook:1240 msgid "" "Gtk-doc assumes all symbols (macros, functions) starting with '_' are " "private. They are treated like static functions." @@ -2100,7 +2113,7 @@ msgstr "" "«_» son privados. Se tratan como funciones estáticas." #. (itstool) path: example/programlisting -#: C/index.docbook:1240 +#: C/index.docbook:1246 #, no-wrap msgid "" "\n" @@ -2142,27 +2155,27 @@ msgstr "" " */\n" #. (itstool) path: variablelist/title -#: C/index.docbook:1261 +#: C/index.docbook:1267 msgid "Function tags" msgstr "Etiquetas de funciones" #. (itstool) path: varlistentry/term -#: C/index.docbook:1262 C/index.docbook:1469 +#: C/index.docbook:1268 C/index.docbook:1475 msgid "Returns:" msgstr "Devuelve:" #. (itstool) path: listitem/para -#: C/index.docbook:1264 +#: C/index.docbook:1270 msgid "Paragraph describing the returned result." msgstr "Párrafo que describe el resultado devuelto." #. (itstool) path: varlistentry/term -#: C/index.docbook:1269 +#: C/index.docbook:1275 msgid "@...:" msgstr "@...:" #. (itstool) path: listitem/para -#: C/index.docbook:1271 +#: C/index.docbook:1277 msgid "" "In case the function has variadic arguments, you should use this tag " "(@Varargs: does also work for historic reasons)." @@ -2172,12 +2185,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1281 C/index.docbook:1283 +#: C/index.docbook:1287 C/index.docbook:1289 msgid "Property comment block" msgstr "Bloque de comentario de propiedad" #. (itstool) path: example/programlisting -#: C/index.docbook:1284 +#: C/index.docbook:1290 #, no-wrap msgid "" "\n" @@ -2198,12 +2211,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1296 C/index.docbook:1315 +#: C/index.docbook:1302 C/index.docbook:1321 msgid "Signal comment block" msgstr "Bloque de comentario de señal" #. (itstool) path: listitem/para -#: C/index.docbook:1302 +#: C/index.docbook:1308 msgid "" "Document when the signal is emitted and whether it is emitted before or " "after other signals." @@ -2212,12 +2225,12 @@ msgstr "" "otras señales." #. (itstool) path: listitem/para -#: C/index.docbook:1308 +#: C/index.docbook:1314 msgid "Document what an application might do in the signal handler." msgstr "Documentar qué aplicación debe gestionar las señales." #. (itstool) path: example/programlisting -#: C/index.docbook:1316 +#: C/index.docbook:1322 #, no-wrap msgid "" "\n" @@ -2248,12 +2261,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1333 C/index.docbook:1334 +#: C/index.docbook:1339 C/index.docbook:1340 msgid "Struct comment block" msgstr "Bloque de comentario de estructura" #. (itstool) path: example/programlisting -#: C/index.docbook:1335 +#: C/index.docbook:1341 #, no-wrap msgid "" "\n" @@ -2283,7 +2296,7 @@ msgstr "" "} FooWidget;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1350 +#: C/index.docbook:1356 msgid "" "Use /*< private >*/ before the private struct fields you " "want to hide. Use /*< public >*/ for the reverse " @@ -2294,7 +2307,7 @@ msgstr "" "revertir el comportamiento anterior." #. (itstool) path: sect2/para -#: C/index.docbook:1356 +#: C/index.docbook:1362 msgid "" "If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" " "it will be considered private automatically and doesn't need to be mentioned " @@ -2305,7 +2318,7 @@ msgstr "" "bloque de comentario." #. (itstool) path: sect2/para -#: C/index.docbook:1362 +#: C/index.docbook:1368 msgid "" "Struct comment blocks can also be used for GObjects and GObjectClasses. It " "is usually a good idea to add a comment block for a class, if it has " @@ -2325,12 +2338,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1374 C/index.docbook:1375 +#: C/index.docbook:1380 C/index.docbook:1381 msgid "Enum comment block" msgstr "Enumerar bloques de comentarios" #. (itstool) path: example/programlisting -#: C/index.docbook:1376 +#: C/index.docbook:1382 #, no-wrap msgid "" "\n" @@ -2364,7 +2377,7 @@ msgstr "" "} Something;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1393 +#: C/index.docbook:1399 msgid "" "Use /*< private >*/ before the private enum values you " "want to hide. Use /*< public >*/ for the reverse " @@ -2375,12 +2388,12 @@ msgstr "" "comportamiento anterior." #. (itstool) path: sect1/title -#: C/index.docbook:1404 +#: C/index.docbook:1410 msgid "Inline program documentation" msgstr "Documentación en línea del programa" #. (itstool) path: sect1/para -#: C/index.docbook:1405 +#: C/index.docbook:1411 msgid "" "You can document programs and their commandline interface using inline " "documentation." @@ -2389,37 +2402,37 @@ msgstr "" "documentación en línea." #. (itstool) path: variablelist/title -#: C/index.docbook:1411 +#: C/index.docbook:1417 msgid "Tags" msgstr "Etiquetas" #. (itstool) path: varlistentry/term -#: C/index.docbook:1413 +#: C/index.docbook:1419 msgid "PROGRAM" msgstr "PROGRAM" #. (itstool) path: listitem/para -#: C/index.docbook:1416 +#: C/index.docbook:1422 msgid "Defines the start of a program documentation." msgstr "Define el inicio de la documentación de un programa." #. (itstool) path: varlistentry/term -#: C/index.docbook:1423 +#: C/index.docbook:1429 msgid "@short_description:" msgstr "@short_description:" #. (itstool) path: listitem/para -#: C/index.docbook:1425 +#: C/index.docbook:1431 msgid "Defines a short description of the program. (Optional)" msgstr "Define una descripción corta del programa. (Opcional)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1432 +#: C/index.docbook:1438 msgid "@synopsis:" msgstr "@synopsis:" #. (itstool) path: listitem/para -#: C/index.docbook:1434 +#: C/index.docbook:1440 msgid "" "Defines the arguments, or list of arguments that the program can take. " "(Optional)" @@ -2428,52 +2441,52 @@ msgstr "" "(Opcional)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1442 +#: C/index.docbook:1448 msgid "@see_also:" msgstr "@see_also:" #. (itstool) path: listitem/para -#: C/index.docbook:1444 +#: C/index.docbook:1450 msgid "See Also manual page section. (Optional)" msgstr "Página del manual Ver también. (Opcional)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1451 +#: C/index.docbook:1457 msgid "@arg:" msgstr "@arg:" #. (itstool) path: listitem/para -#: C/index.docbook:1453 +#: C/index.docbook:1459 msgid "Argument(s) passed to the program and their description. (Optional)" msgstr "Argumentos pasados al programa y su descripción. (Opcional)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1460 +#: C/index.docbook:1466 msgid "Description:" msgstr "Description:" #. (itstool) path: listitem/para -#: C/index.docbook:1462 +#: C/index.docbook:1468 msgid "A longer description of the program." msgstr "Una descripción más larga del programa." #. (itstool) path: listitem/para -#: C/index.docbook:1471 +#: C/index.docbook:1477 msgid "Specificy what value(s) the program returns. (Optional)" msgstr "Especifique qué valores devuelve el programa. (Opcional)" #. (itstool) path: sect2/title -#: C/index.docbook:1480 +#: C/index.docbook:1486 msgid "Example of program documentation." msgstr "Ejemplo de documentación de un programa." #. (itstool) path: example/title -#: C/index.docbook:1481 +#: C/index.docbook:1487 msgid "Program documentation block" msgstr "Bloque de documentación del programa" #. (itstool) path: example/programlisting -#: C/index.docbook:1482 +#: C/index.docbook:1488 #, no-wrap msgid "" "\n" @@ -2517,19 +2530,19 @@ msgstr "" "}\n" #. (itstool) path: sect1/title -#: C/index.docbook:1508 +#: C/index.docbook:1514 msgid "Useful DocBook tags" msgstr "Etiquetas DocBook útiles" #. (itstool) path: sect1/para -#: C/index.docbook:1510 +#: C/index.docbook:1516 msgid "" "Here are some DocBook tags which are most useful when documenting the code." msgstr "" "Aquí están varias etiquetas de DocBook muy útiles al documentar código." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1519 +#: C/index.docbook:1525 #, no-wrap msgid "" "\n" @@ -2539,7 +2552,7 @@ msgstr "" "<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1515 +#: C/index.docbook:1521 msgid "" "To link to another section in the GTK docs: <_:informalexample-1/> The " "linkend is the SGML/XML id on the top item of the page you want to link to. " @@ -2555,7 +2568,7 @@ msgstr "" "ajustarse a SGML/XML." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1532 +#: C/index.docbook:1538 #, no-wrap msgid "" "\n" @@ -2565,7 +2578,7 @@ msgstr "" "<function>...</function>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1529 +#: C/index.docbook:1535 msgid "" "To refer to an external function, e.g. a standard C function: <_:" "informalexample-1/>" @@ -2574,7 +2587,7 @@ msgstr "" "informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1541 +#: C/index.docbook:1547 #, no-wrap msgid "" "\n" @@ -2594,7 +2607,7 @@ msgstr "" "</example>\n" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1552 +#: C/index.docbook:1558 #, no-wrap msgid "" "\n" @@ -2612,7 +2625,7 @@ msgstr "" "</informalexample>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1538 +#: C/index.docbook:1544 msgid "" "To include example code: <_:informalexample-1/> or possibly this, for very " "short code fragments which don't need a title: <_:informalexample-2/> For " @@ -2623,7 +2636,7 @@ msgstr "" "informalexample-2/>. El último GTK-Doc también soporta abreviación: |[ ... ]|" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1571 +#: C/index.docbook:1577 #, no-wrap msgid "" "\n" @@ -2655,12 +2668,12 @@ msgstr "" "</itemizedlist>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1568 +#: C/index.docbook:1574 msgid "To include bulleted lists: <_:informalexample-1/>" msgstr "Para incluir listas de topos: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1591 +#: C/index.docbook:1597 #, no-wrap msgid "" "\n" @@ -2678,13 +2691,13 @@ msgstr "" "</note>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1588 +#: C/index.docbook:1594 msgid "" "To include a note which stands out from the text: <_:informalexample-1/>" msgstr "Para incluir una nota que sobresale del texto: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1604 +#: C/index.docbook:1610 #, no-wrap msgid "" "\n" @@ -2694,12 +2707,12 @@ msgstr "" "<type>unsigned char</type>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1601 +#: C/index.docbook:1607 msgid "To refer to a type: <_:informalexample-1/>" msgstr "Para referirse a un tipo: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1613 +#: C/index.docbook:1619 #, no-wrap msgid "" "\n" @@ -2709,7 +2722,7 @@ msgstr "" "<structname>XFontStruct</structname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1610 +#: C/index.docbook:1616 msgid "" "To refer to an external structure (not one described in the GTK docs): <_:" "informalexample-1/>" @@ -2718,7 +2731,7 @@ msgstr "" "de GTK): <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1622 +#: C/index.docbook:1628 #, no-wrap msgid "" "\n" @@ -2728,12 +2741,12 @@ msgstr "" "<structfield>len</structfield>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1619 +#: C/index.docbook:1625 msgid "To refer to a field of a structure: <_:informalexample-1/>" msgstr "Para referirse a un campo o a una estructura: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1631 +#: C/index.docbook:1637 #, no-wrap msgid "" "\n" @@ -2743,7 +2756,7 @@ msgstr "" "<classname>GtkWidget</classname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1628 +#: C/index.docbook:1634 msgid "" "To refer to a class name, we could possibly use: <_:informalexample-1/> but " "you'll probably be using #GtkWidget instead (to automatically create a link " @@ -2756,7 +2769,7 @@ msgstr "" "\"documenting_syntax\">abreviaciones)." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1642 +#: C/index.docbook:1648 #, no-wrap msgid "" "\n" @@ -2766,12 +2779,12 @@ msgstr "" "<emphasis>This is important</emphasis>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1639 +#: C/index.docbook:1645 msgid "To emphasize text: <_:informalexample-1/>" msgstr "Para enfatizar un texto: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1651 +#: C/index.docbook:1657 #, no-wrap msgid "" "\n" @@ -2781,12 +2794,12 @@ msgstr "" "<filename>/home/user/documents</filename>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1648 +#: C/index.docbook:1654 msgid "For filenames use: <_:informalexample-1/>" msgstr "Para uso de nombres de archivo: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1660 +#: C/index.docbook:1666 #, no-wrap msgid "" "\n" @@ -2796,17 +2809,17 @@ msgstr "" "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1657 +#: C/index.docbook:1663 msgid "To refer to keys use: <_:informalexample-1/>" msgstr "Para referirse a claves: <_:informalexample-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1670 +#: C/index.docbook:1676 msgid "Filling the extra files" msgstr "Rellenar campos adicionales" #. (itstool) path: chapter/para -#: C/index.docbook:1672 +#: C/index.docbook:1678 msgid "" "There are a couple of extra files, that need to be maintained along with the " "inline source code comments: <package>.types, " @@ -2819,12 +2832,12 @@ msgstr "" "pasado) y <paquete>-sections.txt." #. (itstool) path: sect1/title -#: C/index.docbook:1681 +#: C/index.docbook:1687 msgid "Editing the types file" msgstr "Editar los tipos de archivo" #. (itstool) path: sect1/para -#: C/index.docbook:1683 +#: C/index.docbook:1689 msgid "" "If your library or application includes GObjects, you want their signals, " "arguments/parameters and position in the hierarchy to be shown in the " @@ -2839,12 +2852,12 @@ msgstr "" "<paquete>.types." #. (itstool) path: example/title -#: C/index.docbook:1692 +#: C/index.docbook:1698 msgid "Example types file snippet" msgstr "Fragmento de ejemplo de tipos de archivo" #. (itstool) path: example/programlisting -#: C/index.docbook:1693 +#: C/index.docbook:1699 #, no-wrap msgid "" "\n" @@ -2864,7 +2877,7 @@ msgstr "" "gtk_arrow_get_type\n" #. (itstool) path: sect1/para -#: C/index.docbook:1704 +#: C/index.docbook:1710 msgid "" "Since GTK-Doc 1.8 gtkdoc-scan can generate this " "list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in " @@ -2877,12 +2890,12 @@ msgstr "" "los tipos de archivo ni tenerlos bajo el control de versiones." #. (itstool) path: sect1/title -#: C/index.docbook:1713 +#: C/index.docbook:1719 msgid "Editing the master document" msgstr "Editar la sección maestra del documento" #. (itstool) path: sect1/para -#: C/index.docbook:1715 +#: C/index.docbook:1721 msgid "" "GTK-Doc produces documentation in DocBook SGML/XML. When processing the " "inline source comments, the GTK-Doc tools generate one documentation page " @@ -2895,7 +2908,7 @@ msgstr "" "documento maestro las incluye y ordena." #. (itstool) path: sect1/para -#: C/index.docbook:1722 +#: C/index.docbook:1728 msgid "" "While GTK-Doc creates a template master document for you, later runs will " "not touch it again. This means that one can freely structure the " @@ -2912,7 +2925,7 @@ msgstr "" "vez en cuando para ver si se han introducido algunas mejoras." #. (itstool) path: tip/para -#: C/index.docbook:1732 +#: C/index.docbook:1738 msgid "" "Do not create tutorials as extra documents. Just write extra chapters. The " "benefit of directly embedding the tutorial for your library into the API " @@ -2927,7 +2940,7 @@ msgstr "" "el tutorial junto con la biblioteca son mayores." #. (itstool) path: sect1/para -#: C/index.docbook:1741 +#: C/index.docbook:1747 msgid "" "So what are the things to change inside the master document? For a start is " "only a little. There are some placeholders (text in square brackets) there " @@ -2938,12 +2951,12 @@ msgstr "" "que habría que encargarse." #. (itstool) path: example/title -#: C/index.docbook:1748 +#: C/index.docbook:1754 msgid "Master document header" msgstr "Cabecera del documento maestro" #. (itstool) path: example/programlisting -#: C/index.docbook:1749 +#: C/index.docbook:1755 #, no-wrap msgid "" "\n" @@ -2973,7 +2986,7 @@ msgstr "" " <title>[Insert title here]</title>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1765 +#: C/index.docbook:1771 msgid "" "In addition a few option elements are created in commented form. You can " "review these and enable them as you like." @@ -2982,12 +2995,12 @@ msgstr "" "Puede revisarlos y activarlos como quiera." #. (itstool) path: example/title -#: C/index.docbook:1771 +#: C/index.docbook:1777 msgid "Optional part in the master document" msgstr "Parte opcional en el documento maestro" #. (itstool) path: example/programlisting -#: C/index.docbook:1772 +#: C/index.docbook:1778 #, no-wrap msgid "" "\n" @@ -3001,7 +3014,7 @@ msgstr "" " --> \n" #. (itstool) path: sect1/para -#: C/index.docbook:1780 +#: C/index.docbook:1786 msgid "" "Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind " @@ -3013,12 +3026,12 @@ msgstr "" "todavía en la documentación." #. (itstool) path: example/title -#: C/index.docbook:1788 C/index.docbook:1823 +#: C/index.docbook:1794 C/index.docbook:1829 msgid "Including generated sections" msgstr "Incluir secciones generadas" #. (itstool) path: example/programlisting -#: C/index.docbook:1789 +#: C/index.docbook:1795 #, no-wrap msgid "" "\n" @@ -3034,12 +3047,12 @@ msgstr "" " ...\n" #. (itstool) path: sect1/title -#: C/index.docbook:1801 +#: C/index.docbook:1807 msgid "Editing the section file" msgstr "Editar el archivo de sección" #. (itstool) path: sect1/para -#: C/index.docbook:1803 +#: C/index.docbook:1809 msgid "" "The section file is used to organise the documentation output by GTK-Doc. " "Here one specifies which symbol belongs to which module or class and control " @@ -3050,7 +3063,7 @@ msgstr "" "y el control de la visibilidad (pública o privada)." #. (itstool) path: sect1/para -#: C/index.docbook:1809 +#: C/index.docbook:1815 msgid "" "The section file is a plain text file with tags delimiting sections. Blank " "lines are ignored and lines starting with a '#' are treated as comment lines." @@ -3060,7 +3073,7 @@ msgstr "" "comiencen con «#» se tratan como comentarios." #. (itstool) path: note/para -#: C/index.docbook:1816 +#: C/index.docbook:1822 msgid "" "While the tags make the file look like xml, it is not. Please do not close " "tags like <SUBSECTION>." @@ -3069,7 +3082,7 @@ msgstr "" "etiquetas del tipo <SUBSECTION>." #. (itstool) path: example/programlisting -#: C/index.docbook:1824 +#: C/index.docbook:1830 #, no-wrap msgid "" "\n" @@ -3101,7 +3114,7 @@ msgstr "" "</SECTION>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1841 +#: C/index.docbook:1847 msgid "" "The <FILE> ... </FILE> tag is used to specify the file name, " "without any suffix. For example, using '<FILE>gnome-config</" @@ -3124,7 +3137,7 @@ msgstr "" "clase de GObject convertido a minúscula.)" #. (itstool) path: sect1/para -#: C/index.docbook:1853 +#: C/index.docbook:1859 msgid "" "The <TITLE> ... </TITLE> tag is used to specify the title of the " "section. It is only useful before the templates (if used) are initially " @@ -3138,7 +3151,7 @@ msgstr "" "obsoleto." #. (itstool) path: sect1/para -#: C/index.docbook:1860 +#: C/index.docbook:1866 msgid "" "You can group items in the section by using the <SUBSECTION> tag. " "Currently it outputs a blank line between subsections in the synopsis " @@ -3168,7 +3181,7 @@ msgstr "" "públicas (variables, vmethods)." #. (itstool) path: sect1/para -#: C/index.docbook:1879 +#: C/index.docbook:1885 msgid "" "You can also use <INCLUDE> ... </INCLUDE> to specify the " "#include files which are shown in the synopsis sections. It contains a comma-" @@ -3184,12 +3197,12 @@ msgstr "" "a esa sección." #. (itstool) path: chapter/title -#: C/index.docbook:1893 +#: C/index.docbook:1899 msgid "Controlling the result" msgstr "Controlar el resultado" #. (itstool) path: chapter/para -#: C/index.docbook:1895 +#: C/index.docbook:1901 msgid "" "A GTK-Doc run generates report files inside the documentation directory. The " "generated files are named: <package>-undocumented.txt<package>-undocumented.txt file starts with " "the documentation coverage summary. Below are two sections divided by blank " @@ -3220,7 +3233,7 @@ msgstr "" "documentación pero dónde; p.e. se ha añadido un parámetro nuevo." #. (itstool) path: chapter/para -#: C/index.docbook:1913 +#: C/index.docbook:1919 msgid "" "The <package>-undeclared.txt file lists symbols " "given in the <package>-sections.txt but not found " @@ -3232,7 +3245,7 @@ msgstr "" "eliminado o no se han escrito correctamente." #. (itstool) path: chapter/para -#: C/index.docbook:1920 +#: C/index.docbook:1926 msgid "" "The <package>-unused.txt file lists symbol names, " "where the GTK-Doc scanner has found documentation, but does not know where " @@ -3245,7 +3258,7 @@ msgstr "" "todavía al archivo <paquete>-sections.txt." #. (itstool) path: tip/para -#: C/index.docbook:1928 +#: C/index.docbook:1934 msgid "" "Enable or add the line in Makefile." "am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during " @@ -3256,7 +3269,7 @@ msgstr "" "de integridad durante la ejecución de make check." #. (itstool) path: chapter/para -#: C/index.docbook:1935 +#: C/index.docbook:1941 msgid "" "One can also look at the files produced by the source code scanner: " "<package>-decl-list.txt and <" @@ -3273,7 +3286,7 @@ msgstr "" "si este archivo lo contiene." #. (itstool) path: chapter/para -#: C/index.docbook:1944 +#: C/index.docbook:1950 msgid "" "If the project is GObject based, one can also look into the files produced " "by the object scanner: <package>.args.txt, " @@ -3294,12 +3307,12 @@ msgstr "" "ejecutándolo como GTK_DOC_KEEP_INTERMEDIATE=1 make." #. (itstool) path: chapter/title -#: C/index.docbook:1959 +#: C/index.docbook:1965 msgid "Modernizing the documentation" msgstr "Modernizar la documentación" #. (itstool) path: chapter/para -#: C/index.docbook:1961 +#: C/index.docbook:1967 msgid "" "GTK-Doc has been around for quite some time. In this section we list new " "features together with the version since when it is available." @@ -3308,12 +3321,12 @@ msgstr "" "características nuevas junto con la versión desde la que están disponibles." #. (itstool) path: sect1/title -#: C/index.docbook:1967 +#: C/index.docbook:1973 msgid "GTK-Doc 1.9" msgstr "GTK-Doc 1.9" #. (itstool) path: sect1/para -#: C/index.docbook:1969 +#: C/index.docbook:1975 msgid "" "When using xml instead of sgml, one can actually name the master document " "<package>-docs.xml." @@ -3322,7 +3335,7 @@ msgstr "" "maestro <paquete>-docs.xml." #. (itstool) path: sect1/para -#: C/index.docbook:1974 +#: C/index.docbook:1980 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3343,7 +3356,7 @@ msgstr "" "paquete>-decl-list.txt <paquete>-sections.txt." #. (itstool) path: sect1/para -#: C/index.docbook:1985 +#: C/index.docbook:1991 msgid "" "Version 1.8 already introduced the syntax for documenting sections in the " "sources instead of the separate files under configure.ac y lo tendrá hecho." #. (itstool) path: sect1/title -#: C/index.docbook:1997 +#: C/index.docbook:2003 msgid "GTK-Doc 1.10" msgstr "GTK-Doc 1.10" #. (itstool) path: sect1/para -#: C/index.docbook:1999 +#: C/index.docbook:2005 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3388,17 +3401,17 @@ msgstr "" "condicional." #. (itstool) path: sect1/title -#: C/index.docbook:2010 +#: C/index.docbook:2016 msgid "GTK-Doc 1.16" msgstr "GTK-Doc 1.16" #. (itstool) path: example/title -#: C/index.docbook:2016 +#: C/index.docbook:2022 msgid "Enable gtkdoc-check" msgstr "Activar gtkdoc-check" #. (itstool) path: example/programlisting -#: C/index.docbook:2017 +#: C/index.docbook:2023 #, no-wrap msgid "" "\n" @@ -3418,7 +3431,7 @@ msgstr "" "endif\n" #. (itstool) path: sect1/para -#: C/index.docbook:2012 +#: C/index.docbook:2018 msgid "" "This version includes a new tool called gtkdoc-check. This tool can run a " "set of sanity checks on your documentation. It is enabled by adding these " @@ -3430,12 +3443,12 @@ msgstr "" "archivo Makefile.am. <_:example-1/>" #. (itstool) path: sect1/title -#: C/index.docbook:2030 +#: C/index.docbook:2036 msgid "GTK-Doc 1.20" msgstr "GTK-Doc 1.20" #. (itstool) path: sect1/para -#: C/index.docbook:2032 +#: C/index.docbook:2038 msgid "" "Version 1.18 brought some initial markdown support. Using markdown in doc " "comments is less intrusive than writing docbook xml. This version improves a " @@ -3449,17 +3462,17 @@ msgstr "" "comentarios contiene todos los detalles." #. (itstool) path: sect1/title -#: C/index.docbook:2042 +#: C/index.docbook:2048 msgid "GTK-Doc 1.25" msgstr "GTK-Doc 1.25" #. (itstool) path: example/title -#: C/index.docbook:2052 +#: C/index.docbook:2058 msgid "Use pre-generated entities" msgstr "Usar entidades generadas previamenet" #. (itstool) path: example/programlisting -#: C/index.docbook:2053 +#: C/index.docbook:2059 #, no-wrap msgid "" "\n" @@ -3501,7 +3514,7 @@ msgstr "" " </bookinfo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:2044 +#: C/index.docbook:2050 msgid "" "The makefiles shipped with this version generate an entity file at " "xml/gtkdocentities.ent, containing entities for e.g. " @@ -3521,12 +3534,12 @@ msgstr "" "archivos XML generados. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:2078 +#: C/index.docbook:2084 msgid "Documenting other interfaces" msgstr "Documentar otras interfaces" #. (itstool) path: chapter/para -#: C/index.docbook:2080 +#: C/index.docbook:2086 msgid "" "So far we have been using GTK-Doc to document the API of code. The next " "sections contain suggestions how the tools can be used to document other " @@ -3537,12 +3550,12 @@ msgstr "" "herramientas para documentar otras interfaces." #. (itstool) path: sect1/title -#: C/index.docbook:2087 +#: C/index.docbook:2093 msgid "Command line options and man pages" msgstr "Opciones de la línea de comandos y páginas man" #. (itstool) path: sect1/para -#: C/index.docbook:2089 +#: C/index.docbook:2095 msgid "" "As one can generate man pages for a docbook refentry as well, it sounds like " "a good idea to use it for that purpose. This way the interface is part of " @@ -3553,12 +3566,12 @@ msgstr "" "interfaz es parte de la referencia y se obtienen las páginas man sin trabajo." #. (itstool) path: sect2/title -#: C/index.docbook:2096 +#: C/index.docbook:2102 msgid "Document the tool" msgstr "Documentar la herramienta" #. (itstool) path: sect2/para -#: C/index.docbook:2098 +#: C/index.docbook:2104 msgid "" "Create one refentry file per tool. Following our example we would call it meep/" @@ -3573,17 +3586,17 @@ msgstr "" "así como los ejemplos en, por ejemplo, glib." #. (itstool) path: sect2/title -#: C/index.docbook:2108 +#: C/index.docbook:2114 msgid "Adding the extra configure check" msgstr "Añadir la comprobación de configuración adicional" #. (itstool) path: example/title -#: C/index.docbook:2111 C/index.docbook:2129 +#: C/index.docbook:2117 C/index.docbook:2135 msgid "Extra configure checks" msgstr "Comprobaciones de configuración adicionales" #. (itstool) path: example/programlisting -#: C/index.docbook:2112 +#: C/index.docbook:2118 #, no-wrap msgid "" "\n" @@ -3605,12 +3618,12 @@ msgstr "" "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" #. (itstool) path: sect2/title -#: C/index.docbook:2126 +#: C/index.docbook:2132 msgid "Adding the extra makefile rules" msgstr "Añadir reglas de makefile adicionales" #. (itstool) path: example/programlisting -#: C/index.docbook:2130 +#: C/index.docbook:2136 #, no-wrap msgid "" "\n" @@ -3646,12 +3659,12 @@ msgstr "" "EXTRA_DIST += meep.xml\n" #. (itstool) path: sect1/title -#: C/index.docbook:2152 +#: C/index.docbook:2158 msgid "DBus interfaces" msgstr "Interfaces de DBus" #. (itstool) path: sect1/para -#: C/index.docbook:2154 +#: C/index.docbook:2160 msgid "" "(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" @@ -3660,27 +3673,27 @@ msgstr "" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" #. (itstool) path: chapter/title -#: C/index.docbook:2163 +#: C/index.docbook:2169 msgid "Frequently asked questions" msgstr "Preguntas más frecuentes" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2167 +#: C/index.docbook:2173 msgid "Question" msgstr "Pregunta" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2168 +#: C/index.docbook:2174 msgid "Answer" msgstr "Respuesta" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2170 +#: C/index.docbook:2176 msgid "No class hierarchy." msgstr "Sin jerarquía de clases." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2171 +#: C/index.docbook:2177 msgid "" "The objects xxx_get_type() function has not been " "entered into the <package>.types file." @@ -3689,12 +3702,12 @@ msgstr "" "introducido en el archivo <package>.types." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2177 +#: C/index.docbook:2183 msgid "Still no class hierarchy." msgstr "Aún sin jerarquía de clases." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2178 +#: C/index.docbook:2184 msgid "" "Missing or wrong naming in <package>-sections.txt " "file (see explicación)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2184 +#: C/index.docbook:2190 msgid "Damn, I have still no class hierarchy." msgstr "Maldición, aún no hay una jerarquía de clases." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2185 +#: C/index.docbook:2191 msgid "" "Is the object name (name of the instance struct, e.g. GtkWidget) part of the normal section (don't put this into Standard or Private " @@ -3721,12 +3734,12 @@ msgstr "" "Estándar o Privado)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2192 +#: C/index.docbook:2198 msgid "No symbol index." msgstr "Sin índice de símbolos." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2193 +#: C/index.docbook:2199 msgid "" "Does the <package>-docs.{xml,sgml} contain a " "index that xi:includes the generated index?" @@ -3735,12 +3748,12 @@ msgstr "" "«xi:includes» el índice generado?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2199 +#: C/index.docbook:2205 msgid "Symbols are not linked to their doc-section." msgstr "Los símbolos no se enlazan con su sección en el documento." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2200 +#: C/index.docbook:2206 msgid "" "Is the doc-comment using the correct markup (added #,% or ())? Check if the " "gtkdoc-fixxref warns about unresolvable xrefs." @@ -3749,12 +3762,12 @@ msgstr "" "si gtk-doc-fixxref avisa de alguna referencia xref sin resolver." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2206 +#: C/index.docbook:2212 msgid "A new class does not appear in the docs." msgstr "Una clase nueva no aparece en la documentación." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2207 +#: C/index.docbook:2213 msgid "" "Is the new page xi:included from <package>-docs.{xml,sgml}." @@ -3763,12 +3776,12 @@ msgstr "" "sgml}." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2213 +#: C/index.docbook:2219 msgid "A new symbol does not appear in the docs." msgstr "Un símbolo nuevo no aparece en la documentación." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2214 +#: C/index.docbook:2220 msgid "" "Is the doc-comment properly formatted. Check for spelling mistakes in the " "begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable " @@ -3782,12 +3795,12 @@ msgstr "" "txt en una subsección pública." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2222 +#: C/index.docbook:2228 msgid "A type is missing from the class hierarchy." msgstr "Falta un tipo en la clase de jerarquías" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2223 +#: C/index.docbook:2229 msgid "" "If the type is listed in <package>.hierarchy but " "not in xml/tree_index.sgml then double check that the " @@ -3803,14 +3816,14 @@ msgstr "" "privada." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2232 +#: C/index.docbook:2238 msgid "I get foldoc links for all gobject annotations." msgstr "" "Obtengo enlaces de seguimiento de documentos para todas las anotaciones " "gobject." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2233 +#: C/index.docbook:2239 msgid "" "Check that xml/annotation-glossary.xml is xi:included " "from <package>-docs.{xml,sgml}." @@ -3819,14 +3832,14 @@ msgstr "" "included» desde <package>-docs.{xml,sgml}." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2241 +#: C/index.docbook:2247 msgid "Parameter described in source code comment block but does not exist" msgstr "" "Parámetro descrito en el bloque de comentarios del código fuente pero no " "existe" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2242 +#: C/index.docbook:2248 msgid "" "Check if the prototype in the header has different parameter names as in the " "source." @@ -3835,12 +3848,12 @@ msgstr "" "diferentes de la fuente." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2247 +#: C/index.docbook:2253 msgid "multiple \"IDs\" for constraint linkend: XYZ" msgstr "múltiples «ID» para la restricción enlazada: XYZ" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2248 +#: C/index.docbook:2254 msgid "" "Symbol XYZ appears twice in <package>-sections.txt file." @@ -3849,7 +3862,7 @@ msgstr "" "sections.txt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2251 +#: C/index.docbook:2257 msgid "" "Element typename in namespace '' encountered in para, but no template " "matches." @@ -3858,12 +3871,12 @@ msgstr "" "coincide." #. (itstool) path: chapter/title -#: C/index.docbook:2258 +#: C/index.docbook:2264 msgid "Tools related to gtk-doc" msgstr "Herramientas relacionadas con GTK-Doc" #. (itstool) path: chapter/para -#: C/index.docbook:2260 +#: C/index.docbook:2266 msgid "" "GtkDocPlugin - a Trac " "GTK-Doc integration plugin, that adds API docs to a trac site and " @@ -3874,7 +3887,7 @@ msgstr "" "a un sitio «trac» y se integra con la búsqueda de «trac»." #. (itstool) path: chapter/para -#: C/index.docbook:2265 +#: C/index.docbook:2271 msgid "" "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " "tags in the API to determine the minimum required version." diff --git a/help/manual/es/index.docbook b/help/manual/es/index.docbook index 6ebf18d..5fed083 100644 --- a/help/manual/es/index.docbook +++ b/help/manual/es/index.docbook @@ -35,11 +35,12 @@ - 1.28 - 24 Mar 2018 + 1.29 + 28 Aug 2018 ss - bug fixes + development + 1.28 24 de marzo de 2018 ss correcciones de errores 1.27 07 de diciembre de 2017 ss ajustes para la migración a python 1.26 11 de agosto de 2017 ss portar todas las herramientas de perl/bash a python 1.25 21 de marzo de 2016 ss correcciones de errores, limpieza @@ -68,7 +69,7 @@ - 2009 - 2017 + 2009 - 2018 Daniel Mustieles @@ -127,7 +128,12 @@ - Escribir la documentación. El autor rellena los archivos de fuentes con la documentación para cada función, macro, unión, etc. (En el pasado la información se introducía en archivos de plantillas, lo que ya no se recomienda). + + Writing the documentation. + + The author fills in the source files with the documentation for each + function, macro, structs or unions, etc. + @@ -164,9 +170,22 @@ Acerca de GTK-Doc + + 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. + + (ARRÉGLAME) - (Historia, autores, páginas web, listas de correo, licencias, planes futuros, comparación con otros sistemas similares.) + + (authors, web pages, mailing list, license, future plans, + comparison with other similar systems.) + @@ -182,131 +201,529 @@ - Configurando su proyecto + Project Setup - 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 Integración con makefiles u otros sistemas de construcción se describen las necesidades básicas para trabajar con un sistema de construcción diferente. + + 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: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + + + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. + Configurar el esquema de la documentación - 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. + + A common convention is to place documentation into a folder called + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. + - Esto después aparecerá como se muestra debajo: Ejemplo de estructura de carpetas - + + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project + - +]]> + + - - Integración con autoconf - - Muy fácil, simplemente añada una línea a su script configure.ac. + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + + + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - Integración con autoconf - -# check for gtk-doc -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - 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 GTK_DOC_CHECK al inicio de la línea. Mantener gtk-doc como opcional + + Integración con automake + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + -# check for gtk-doc -m4_ifdef([GTK_DOC_CHECK], [ -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) -],[ -AM_CONDITIONAL([ENABLE_GTK_DOC], false) -]) +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ - + - El primer argumento se usa para comprobar gtkdocversion durante la configuración. El segundo, y opcional, argumento lo usa gtkdocize. La macro GTK_DOC_CHECK también añade diversas opciones de configuración: - - --with-html-dir=RUTA: ruta a los documentos instalados - --enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no] - --enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=sí] - --enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. - - GTK-Doc está desactivado de forma predeterminada. Recuerde pasar la opción en la siguiente ejecución de configure. De otra forma, la documentación pregenerada se instala (lo que tiene sentido para usuarios, pero no para desarrolladores). - + All settings have a comment above them that describes their purpose + and how to customize the setting. - Aún más, se recomienda que tenga la siguiente línea en su script configure.ac. Esto permite que gtkdocize copie automáticamente la definición de la macro para GTK_DOC_CHECK a su proyecto. + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). - - Preparación para gtkdocize - + All the tools support to list the supported + options. + + + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. + + + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + Integración con autoconf + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - Después de hacer los cambios en el configure.ac actualice el archivo configure. Esto se puede hacer volviendo a ejecutar autoreconf -i o autogen.sh. - +# optional: register gtk-doc in configure +GTK_DOC_CHECK([1.28]) +]]> + + + + + 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: + + + Integration with optional gtk-doc dependency + + + - - Integración con automake + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - Primero copie el archivo Makefile.am de la subcarpeta examples de gtkdoc-sources a la carpeta de documentación de la API de su proyecto (./docs/reference/<package>). Debería haber una copia local disponible en /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Si tiene varios paquetes de documentación, repítalo para cada uno de ellos. + + --with-html-dir=RUTA: ruta a los documentos instalados + --enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no] + --enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=sí] + --enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no] + - El siguiente paso es editar la configuración dentro de Makefile.am. 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 . Todas las herramientas soportan para listar los parámetros que soportan. + + GTK-Doc está desactivado de forma predeterminada. Recuerde pasar la opción en la siguiente ejecución de configure. De otra forma, la documentación pregenerada se instala (lo que tiene sentido para usuarios, pero no para desarrolladores). + - + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - + + Integración con autogen - - Integración con autogen + + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + - La mayoría de los proyectos tienen un script autogen.sh para configurar la infraestructura de construcción después de hacer un «checkout» desde los sistemas de control de versiones (tales como cvs/svn/git). GTK-Doc tiene una herramienta llamada gtkdocize que se puede usar en tal script. Se debería ejecutar antes que autoheader, automake o autoconf. + + It should be run before autoreconf, autoheader, automake or autoconf. + - - Ejecutar gtkdocize desde autogen.sh - + + Ejecutar gtkdocize desde autogen.sh + gtkdocize || exit 1 - - + + - Al ejecutar gtkdocize copia gtk-doc.make a la raíz de su proyecto (o cualquier carpeta especificada por la opción ). También comprueba su script de configuración para la invocación de GTK_DOC_CHECK. Esta macro se puede usar para pasar parámetros adicionales a gtkdocize. + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - 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. gtkdocize ahora soporta una opción 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 GTKDOCIZE_FLAGS o configurar como un segundo parámetro en la macro GTK_DOC_CHECK 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). - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - Ejecutar la construcción de la documentación + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - Después de los pasos anteriores es hora de ejecutar el constructor. Primero se debe volver a ejecutar autogen.sh. Si este script ejecuta configure automáticamente, entonces debe pasar la opción . De otra forma, ejecute posteriormente configure con esta opción. - El primer make genera diversas líneas adicionales en las carpetas de documentación. Las importantes son: <paquete>.types, <paquete>-docs.xml (.sgml en el pasado), <paquete>-sections.txt. - - Ejecutar la construcción de la documentación - + + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + Después de los pasos anteriores es hora de ejecutar el constructor. Primero se debe volver a ejecutar autogen.sh. Si este script ejecuta configure automáticamente, entonces debe pasar la opción . De otra forma, ejecute posteriormente configure con esta opción. + El primer make genera diversas líneas adicionales en las carpetas de documentación. Las importantes son: <paquete>.types, <paquete>-docs.xml (.sgml en el pasado), <paquete>-sections.txt. + + Ejecutar la construcción de la documentación + ./autogen.sh --enable-gtk-doc make - - - Ahora puede apuntar su navegador a docs/reference/<paquete>/index.html. Sí, aún es un poco decepcionante. Pero espere, durante el siguiente capítulo aprenderá a rellenar las páginas con información. + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - Integración con los sistemas de control de versiones + + Integración con sistemas de construcción CMake - 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: <paquete>.types, <paquete>-docs.xml (anteriormente .sgml), <paquete>-sections.txt, Makefile.am. - Los archivos de las carpetas xml/ y html/ No deberían estar bajo control de versiones. Tampoco ninguno de los archivos .stamp. + Ahroa, GTK-Doc proporciona un módulo GtkDocConfig.cmake (y el correspondiente módulo GtkDocConfigVersion.cmake). Esto proporciona un comando gtk_doc_add_module que puede configurar en su archivo CMakeLists.txt. + + El siguiente ejemplo muestra cómo usar este comando. Ejeplo de uso de GTK-Doc desde CMake + +find_package(GtkDoc 1.25 REQUIRED) + +# Create the doc-libmeep target. +gtk_doc_add_module( + libmeep ${CMAKE_SOURCE_DIR}/libmeep + XML meep-docs.xml + LIBRARIES libmeep +) + +# Build doc-libmeep as part of the default target. Without this, you would +# have to explicitly run something like `make doc-libmeep` to build the docs. +add_custom_target(documentation ALL DEPENDS doc-libmeep) + +# Install the docs. (This assumes you're using the GNUInstallDirs CMake module +# to set the CMAKE_INSTALL_DOCDIR variable correctly). +install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html + DESTINATION ${CMAKE_INSTALL_DOCDIR}) + + - + Integración con makefiles u otros sistemas de construcción En el caso de que no quiera usar automake y por ello gtk-doc.mak deberá llamar a las herramientas gtkdoc en el orden correcto en makefiles propios (o en otras herramientas de construcción). @@ -330,33 +747,13 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html Deberá mirar en el archivo Makefile.am y gtk-doc.mak para elegir las opciones adicionales necesarias. - - Integración con sistemas de construcción CMake - - Ahroa, GTK-Doc proporciona un módulo GtkDocConfig.cmake (y el correspondiente módulo GtkDocConfigVersion.cmake). Esto proporciona un comando gtk_doc_add_module que puede configurar en su archivo CMakeLists.txt. - - El siguiente ejemplo muestra cómo usar este comando. Ejeplo de uso de GTK-Doc desde CMake - -find_package(GtkDoc 1.25 REQUIRED) - -# Create the doc-libmeep target. -gtk_doc_add_module( - libmeep ${CMAKE_SOURCE_DIR}/libmeep - XML meep-docs.xml - LIBRARIES libmeep -) + + Integración con los sistemas de control de versiones -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + 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: <paquete>.types, <paquete>-docs.xml (anteriormente .sgml), <paquete>-sections.txt, Makefile.am. + Los archivos de las carpetas xml/ y html/ No deberían estar bajo control de versiones. Tampoco ninguno de los archivos .stamp. + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) - - - @@ -364,19 +761,18 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html GTK-Doc usa código fuente comentado con una sintaxis especial para documentar el código. Además obtiene información acerca de la estructura de su proyecto de otras fuentes. En la siguiente sección encontrará información acerca de la sintaxis de los comentarios. - - Ubicación de la documentación - En el pasado la mayoría de la documentación se debía rellenar en campos dentro de la carpeta tmpl. Esto tiene las desventajas de que la información. Esto tiene las desventajas de que la información no se actualiza muy a menudo y que el archivo tiene tendencia a causar conflictos con los sistemas de control de versiones. - Para 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. - - - 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. Bloque de comentario de GTK-Doc - + + 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. + GTK-Doc comment block + - +]]> + + Limitaciones @@ -490,7 +886,17 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Se pueden encontrar más ejemplos de las etiquetas de marcado soportadas en el Manual de referencia de sintaxis de marcado de documentación de GTK+. - Tal y como se ha mencionado antes, la documentación anterior de GTK-Doc es para documentar la API pública .Por ello, no se puede escribir documentación para los símbolos estáticos. No obstante es una buena práctica comentar los símbolos. Esto ayuda a que otros entiendan su código. Por ello se recomienda comentarlos usando comentarios normales (sin el segundo «*» en la primera línea). Si la función, posteriormente, se debe hacer pública, todo lo que el programador debe hacer es añadir otro «*» en el bloque de comentario e introducir el nombre del símbolo en la parte derecha dentro del archivo de secciones. + + 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. + @@ -1031,7 +1437,7 @@ int main(int argc, char *argv[]) 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 xxx_get_type junto con sus «include» en el archivo <paquete>.types. - Fragmento de ejemplo de tipos de archivo + Example <package>.types file #include <gtk/gtk.h> @@ -1212,27 +1618,37 @@ endif GTK-Doc 1.25 - El makefile distribuído con esta versión genera un archivo de entidad en xml/gtkdocentities.ent, que contiene las entidades para, por ejemplo nombre_paquete y versión_paquete. Puede usar este ejemplo en el archivo main.xml para evitar escribir a mano el número de versión. A continuación se muestra un ejemplo que muestra cómo se incluye el archivo de entidad y cómo se usan las entidades. Las entidades también se pueden usar en todos los archivos generados, GTK-Doc usará la misma cabecera XML en los archivos XML generados. Usar entidades generadas previamenet - -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + + The makefiles shipped with this version generate an entity file at xml/gtkdocentities.ent, + 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. + Use pre-generated entities + + + %gtkdocentities; -]> -<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> - <bookinfo> - <title>&package_name; Reference Manual</title> - <releaseinfo> - for &package_string;. +]> + + + &package_name; Reference Manual + + 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> - - + http://[SERVER]/&package_name;/. + + +]]> + + diff --git a/help/manual/fr/fr.po b/help/manual/fr/fr.po index a80d05d..c7a3b05 100644 --- a/help/manual/fr/fr.po +++ b/help/manual/fr/fr.po @@ -15,15 +15,16 @@ msgid "" msgstr "" "Project-Id-Version: gtk-doc-help HEAD\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2012-10-15 08:49+0000\n" -"PO-Revision-Date: 2013-01-23 12:34+0100\n" +"POT-Creation-Date: 2017-08-11 11:08+0000\n" +"PO-Revision-Date: 2017-10-19 11:24+0200\n" "Last-Translator: Daniel Mustieles \n" "Language-Team: Español \n" -"Language: \n" +"Language: fr\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=n>1;\n" +"X-Generator: Poedit 2.0.1\n" #. Put one translator per line, in the form NAME , YEAR1, YEAR2 msgctxt "_" @@ -36,21 +37,25 @@ msgstr "" "Gérard Baylard , 2010\n" "Luc Pionchon , 2011" -#: C/index.docbook:12(bookinfo/title) +#. (itstool) path: bookinfo/title +#: C/index.docbook:12 msgid "GTK-Doc Manual" msgstr "Manuel de GTK-Doc" -#: C/index.docbook:13(bookinfo/edition) -msgid "1.18.1" -msgstr "1.18.1" +#. (itstool) path: bookinfo/edition +#: C/index.docbook:13 +msgid "1.24.1" +msgstr "1.24.1" -#: C/index.docbook:14(abstract/para) +#. (itstool) path: abstract/para +#: C/index.docbook:14 msgid "User manual for developers with instructions of GTK-Doc usage." msgstr "" "Manuel utilisateur pour les développeurs contenant les instructions sur " "l'usage de GTK-Doc." -#: C/index.docbook:16(authorgroup/author) +#. (itstool) path: authorgroup/author +#: C/index.docbook:16 msgid "" "Chris Lyttle " "
chris@wilddev.net
" @@ -58,7 +63,8 @@ msgstr "" "Chris Lyttle " "
chris@wilddev.net
" -#: C/index.docbook:25(authorgroup/author) +#. (itstool) path: authorgroup/author +#: C/index.docbook:25 msgid "" "Dan Mueth
" "d-mueth@uchicago.edu
" @@ -66,33 +72,43 @@ msgstr "" "Dan Mueth
" "d-mueth@uchicago.edu
" -#: C/index.docbook:34(authorgroup/author) +#. (itstool) path: authorgroup/author +#: C/index.docbook:34 +#| msgid "" +#| "Stefan Kost " +#| "
ensonic@users.sf.net
" msgid "" -"Stefan Kost " +"Stefan Sauer (Kost) " "
ensonic@users.sf.net
" msgstr "" -"Stefan Kost " +"Stefan Sauer (Kost) " "
ensonic@users.sf.net
" -#: C/index.docbook:45(publisher/publishername) +#. (itstool) path: publisher/publishername +#: C/index.docbook:45 msgid "GTK-Doc project" msgstr "Projet GTK-Doc" -#: C/index.docbook:44(bookinfo/publisher) +#. (itstool) path: bookinfo/publisher +#: C/index.docbook:44 msgid "" "<_:publishername-1/>
gtk-doc-list@gnome.org
" msgstr "" "<_:publishername-1/>
gtk-doc-list@gnome.org
" -#: C/index.docbook:48(bookinfo/copyright) +#. (itstool) path: bookinfo/copyright +#: C/index.docbook:48 msgid "2000, 2005 Dan Mueth and Chris Lyttle" msgstr "2000, 2005 Dan Mueth et Chris Lyttle" -#: C/index.docbook:52(bookinfo/copyright) -msgid "2007-2011 Stefan Sauer (Kost)" -msgstr "2007-2011 Stefan Sauer (Kost)" +#. (itstool) path: bookinfo/copyright +#: C/index.docbook:52 +#| msgid "2007-2011 Stefan Sauer (Kost)" +msgid "2007-2015 Stefan Sauer (Kost)" +msgstr "2007-2015 Stefan Sauer (Kost)" -#: C/index.docbook:65(legalnotice/para) +#. (itstool) path: legalnotice/para +#: C/index.docbook:65 msgid "" "Permission is granted to copy, distribute and/or modify this document under " "the terms of the GNU Free Documentation License, " @@ -107,7 +123,8 @@ msgstr "" "couverture ni texte de dernière page de couverture. Vous trouverez un " "exemplaire de cette licence en suivant ce lien." -#: C/index.docbook:73(legalnotice/para) +#. (itstool) path: legalnotice/para +#: C/index.docbook:73 msgid "" "Many of the names used by companies to distinguish their products and " "services are claimed as trademarks. Where those names appear in any GNOME " @@ -121,26 +138,143 @@ msgstr "" "Documentation GNOME sont informés de l'existence de ces marques déposées, " "soit ces noms entiers, soit leur première lettre est en majuscule." -#: C/index.docbook:83(revhistory/revision) +#. (itstool) path: revhistory/revision +#: C/index.docbook:83 +#| msgid "" +#| "1.18.1 20 Sep 2011 " +#| "ss development version" msgid "" -"1.18.1 20 Sep 2011 ss development version" +"1.26.1 11 Aug 2017 ss development" msgstr "" -"1.18.1 20 septembre 2011 " -"ss version de développement1.26.1 11 Aug 2017 ss développement" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:89 +#| msgid "" +#| "1.18.1 20 Sep 2011 " +#| "ss development version" +msgid "" +"1.26 11 Aug 2017 ss port all tools from perl/bash to python" +msgstr "" +"1.26 11 Aug 2017 ss portage de tous les outils depuis perl/bash vers " +"python" -#: C/index.docbook:89(revhistory/revision) +#. (itstool) path: revhistory/revision +#: C/index.docbook:95 +#| msgid "" +#| "1.15 21 May 2010 sk bug and regression fixes" msgid "" -"1.18 14 sep 2011 ss bug fixes, speedups, markdown support" +"1.25 21 March 2016 ss bug fixes, test cleanups" +msgstr "" +"1.25 21 March 2016 ss corrections d'anomalies, nettoyages de test" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:101 +#| msgid "" +#| "1.15 21 May 2010 sk bug and regression fixes" +msgid "" +"1.24 29 May 2015 ss bug fix" msgstr "" -"1.18 14 septembre 2011 " -"ss correction de bogues, " -"amélioration de la vitesse de traitement, prise en charge de markdown1.24 29 May 2015 ss corrections d'anomalies" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:107 +#| msgid "" +#| "1.15 21 May 2010 sk bug and regression fixes" +msgid "" +"1.23 17 May 2015 ss bug fix" +msgstr "" +"1.23 17 May 2015 ss corrections d'anomalies\n" +"" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:113 +#| msgid "" +#| "1.16 14 Jan 2011 sk bugfixes, layout improvements" +msgid "" +"1.22 07 May 2015 ss bug fixes, dropping deprecated features" +msgstr "" +"1.22 07 May 2015 ss corrections d'anomalies, abandon de " +"fonctionnalités obsolètes" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:119 +#| msgid "" +#| "1.16 14 Jan 2011 sk bugfixes, layout improvements" +msgid "" +"1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" +msgstr "" +"1.21 17 Jul 2014 ss corrections d'anomalies, abandon de " +"fonctionnalités obsolètes" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:125 +#, fuzzy +#| msgid "" +#| "1.16 14 Jan 2011 sk bugfixes, layout improvements" +msgid "" +"1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" +msgstr "" +"1.16 14 janvier 2011 sk correctifs et améliorations de mise en page" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:131 +#| msgid "" +#| "1.17 26 Feb 2011 sk urgent bug fix update" +msgid "" +"1.19 05 Jun 2013 ss bug fixes" +msgstr "" +"1.19 05 Jun 2013 ss corrections d'anomalies" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:137 +#| msgid "" +#| "1.18 14 sep 2011 ss bug fixes, speedups, markdown support" +msgid "" +"1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" +msgstr "" +"1.18 14 Sep 2011 ss correction de bogues, amélioration de la vitesse " +"de traitement, prise en charge de markdown" -#: C/index.docbook:95(revhistory/revision) +#. (itstool) path: revhistory/revision +#: C/index.docbook:143 msgid "" "1.17 26 Feb 2011 sk urgent bug fix update" @@ -149,7 +283,8 @@ msgstr "" "authorinitials> mise à jour pour une correction de bogue urgente" -#: C/index.docbook:101(revhistory/revision) +#. (itstool) path: revhistory/revision +#: C/index.docbook:149 msgid "" "1.16 14 Jan 2011 sk bugfixes, layout improvements" @@ -158,7 +293,8 @@ msgstr "" "authorinitials> correctifs et améliorations de mise en page" -#: C/index.docbook:107(revhistory/revision) +#. (itstool) path: revhistory/revision +#: C/index.docbook:155 msgid "" "1.15 21 May 2010 sk bug and regression fixes" @@ -167,7 +303,8 @@ msgstr "" "authorinitials> corrections d'anomalies et de régressions" -#: C/index.docbook:113(revhistory/revision) +#. (itstool) path: revhistory/revision +#: C/index.docbook:161 msgid "" "1.14 28 March 2010 sk bugfixes and performance improvements" @@ -176,7 +313,8 @@ msgstr "" "authorinitials> correctifs et amélioration de performances" -#: C/index.docbook:119(revhistory/revision) +#. (itstool) path: revhistory/revision +#: C/index.docbook:167 msgid "" "1.13 18 December 2009 " "sk broken tarball updatesk mise à jour du tarball brisé" -#: C/index.docbook:125(revhistory/revision) +#. (itstool) path: revhistory/revision +#: C/index.docbook:173 msgid "" "1.12 18 December 2009 " "sk new tool features and " @@ -196,7 +335,8 @@ msgstr "" "sk nouvelles fonctionnalités aux " "outils et résolution de bogues" -#: C/index.docbook:131(revhistory/revision) +#. (itstool) path: revhistory/revision +#: C/index.docbook:179 msgid "" "1.11 16 November 2008 " "mal GNOME doc-utils migrationmal Migration à GNOME doc-utils" -#: C/index.docbook:144(chapter/title) +#. (itstool) path: chapter/title +#: C/index.docbook:192 msgid "Introduction" msgstr "Introduction" -#: C/index.docbook:146(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:194 msgid "" "This chapter introduces GTK-Doc and gives an overview of what it is and how " "it is used." @@ -218,11 +360,13 @@ msgstr "" "Ce chapitre présente GTK-Doc et fournit un aperçu de ce que c'est et de la " "manière de l'utiliser." -#: C/index.docbook:152(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:200 msgid "What is GTK-Doc?" msgstr "Qu'est-ce que GTK-Doc ?" -#: C/index.docbook:154(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:202 msgid "" "GTK-Doc is used to document C code. It is typically used to document the " "public API of libraries, such as the GTK+ and GNOME libraries. But it can " @@ -233,11 +377,13 @@ msgstr "" "GTK+ et GNOME. Mais il peut aussi être utilisé pour documenter du code " "d'application." -#: C/index.docbook:162(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:210 msgid "How Does GTK-Doc Work?" msgstr "Fonctionnement de GTK-Doc ?" -#: C/index.docbook:164(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:212 msgid "" "GTK-Doc works by using documentation of functions placed inside the source " "files in specially-formatted comment blocks, or documentation added to the " @@ -252,19 +398,22 @@ msgstr "" "déclarées dans des fichiers d'en-tête ; il ne fait rien pour les fonctions " "statiques)." -#: C/index.docbook:171(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:219 msgid "" -"GTK-Doc consists of a number of perl scripts, each performing a different " +"GTK-Doc consists of a number of python scripts, each performing a different " "step in the process." msgstr "" -"GTK-Doc consiste en un certain nombre de scripts Perl, chacun réalisant une " -"étape du processus." +"GTK-Doc consiste en un certain nombre de scripts Python, chacun réalisant " +"une étape du processus." -#: C/index.docbook:176(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:224 msgid "There are 5 main steps in the process:" msgstr "Il y a 5 étapes principales :" -#: C/index.docbook:183(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:231 msgid "" "Writing the documentation. The author fills in the " "source files with the documentation for each function, macro, union etc. (In " @@ -276,7 +425,8 @@ msgstr "" "etc. (dans le passé, l'information était saisie dans les fichiers prototypes " "générés mais ce n'est plus recommandé)." -#: C/index.docbook:193(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:241 msgid "" "Gathering information about the code. " "gtkdoc-scan scans the header files of the code " @@ -311,7 +461,8 @@ msgstr "" "possible d'ajouter des entrées dans <module>-overrides.txt similaires à celle de <module>-decl.txt." -#: C/index.docbook:210(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:258 msgid "" "gtkdoc-scangobj can also be used to dynamically " "query a library about any GObject subclasses it exports. It saves " @@ -324,7 +475,8 @@ msgstr "" "informations sur la position de chaque objet dans la hiérarchie de classe et " "sur tous les arguments et signaux GTK fournis." -#: C/index.docbook:216(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:264 msgid "" "gtkdoc-scanobj should not be used anymore. It was " "needed in the past when GObject was still GtkObject inside gtk+." @@ -333,46 +485,25 @@ msgstr "" "était nécessaire par le passé lorsque GObject était encore GtkObject dans gtk" "+." -#: C/index.docbook:223(listitem/para) -msgid "" -"Generating the \"template\" files. gtkdoc-" -"mktmpl creates a number of files in the tmpl/ 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 "" -"Génération des fichiers « prototypes ». " -"gtkdoc-mktmpl crée un certain nombre de fichiers " -"dans le sous-répertoire tmpl/, en " -"utilisant les informations récoltées lors de la première étape (notez que le " -"script peut être exécuté plusieurs fois, il est fait en sorte qu'aucune " -"donnée ne soit jamais perdue)." - -#: C/index.docbook:232(note/para) -msgid "" -"Since GTK-Doc 1.9 the templates can be avoided. We encourage people to keep " -"documentation in the code. gtkdocize supports now " -"a option that chooses a makefile that " -"skips tmpl usage totally. If you have never changed file in tmpl by hand, " -"please remove the directory (e.g. from version control system)." -msgstr "" -"Depuis GTK-Doc 1.9, les prototypes peuvent être évités. Nous encourageons " -"tout le monde à conserver la documentation dans le code. " -"gtkdocize prend maintenant en charge l'option " -" qui choisit un makefile qui évite " -"complètement l'utilisation de tmpl. Si vous n'avez jamais modifié de " -"fichiers à la main dans tmpl, effacez le répertoire (par ex. à partir d'un " -"système de gestion de versions)." - -#: C/index.docbook:244(listitem/para) -msgid "" -"Generating the SGML/XML and HTML/PDF. " -"gtkdoc-mkdb turns the template files into SGML or " -"XML files in the sgml/ or Generating the SGML/XML and HTML/PDF. " +#| "gtkdoc-mkdb turns the template files into SGML " +#| "or XML files in the sgml/ or " +#| "xml/ subdirectory. If the source " +#| "code contains documentation on functions, using the special comment " +#| "blocks, it gets merged in here. If there are no tmpl files used it only " +#| "reads docs from sources and introspection data. We recommend to use " +#| "Docbook XML." +msgid "" +"Generating the XML and HTML/PDF. gtkdoc-" +"mkdb turns the template files into XML files in the xml/ subdirectory. If the source code " "contains documentation on functions, using the special comment blocks, it " "gets merged in here. If there are no tmpl files used it only reads docs from " -"sources and introspection data. We recommend to use Docbook XML." +"sources and introspection data." msgstr "" "Génération du SGML/XML et du HTML/PDF. " "gtkdoc-mkdb transforme les fichiers prototypes en " @@ -384,12 +515,20 @@ msgstr "" "données d'introspection seront lues. Nous recommandons l'utilisation de XML " "DocBook." -#: C/index.docbook:255(listitem/para) -msgid "" -"gtkdoc-mkhtml turns the SGML/XML files into HTML " -"files in the html/ subdirectory. " -"Likewise gtkdoc-mkpdf turns the SGML/XML files " -"into a PDF document called <package>.pdf." +#. (itstool) path: listitem/para +#: C/index.docbook:280 +#, fuzzy +#| msgid "" +#| "gtkdoc-mkhtml turns the SGML/XML files into " +#| "HTML files in the html/ " +#| "subdirectory. Likewise gtkdoc-mkpdf turns the " +#| "SGML/XML files into a PDF document called <package>.pdf." +msgid "" +"gtkdoc-mkhtml turns the XML files into HTML files " +"in the html/ subdirectory. Likewise " +"gtkdoc-mkpdf turns the XML files into a PDF " +"document called <package>.pdf." msgstr "" "gtkdoc-mkhtml transforme les fichiers SGML/XML en " "fichiers HTML dans le répertoire html/<package>.pdf." -#: C/index.docbook:261(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:286 msgid "" -"Files in sgml/ or xml/ and html/ directories are always overwritten. One should never edit them " -"directly." +"Files in xml/ and html/ directories are always overwritten. One " +"should never edit them directly." msgstr "" -"Les fichiers dans les répertoires sgml/ ou xml/ et html/ sont toujours écrasés. Il ne faut pas " -"les modifier directement." +"Les fichiers dans les répertoires xml/ et html/ sont toujours " +"écrasés. Il ne faut pas les modifier directement." -#: C/index.docbook:269(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:294 msgid "" "Fixing up cross-references between documents. After " "installing the HTML files, gtkdoc-fixxref can be " @@ -431,150 +570,83 @@ msgstr "" "distribuée (pré-générée), la même application va essayer de retransformer " "les liens en liens locaux (là où ces documentations sont installées)." -#: C/index.docbook:287(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:312 msgid "Getting GTK-Doc" msgstr "Obtention de GTK-Doc" -#: C/index.docbook:290(sect2/title) +#. (itstool) path: sect2/title +#: C/index.docbook:315 msgid "Requirements" msgstr "Pré-requis" -#: C/index.docbook:291(sect2/para) -msgid "Perl v5 - the main scripts are in Perl." -msgstr "" -"Perl v5 - les principaux scripts sont écrits en Perl." - -#: C/index.docbook:294(sect2/para) -msgid "" -"DocBook DTD v3.0 - This is the DocBook SGML DTD. http://www.ora.com/" -"davenport" -msgstr "" -"DocBook DTD v3.0 - ce sont les DTD DocBook SGML. http://www.ora.com/" -"davenport" - -#: C/index.docbook:298(sect2/para) -msgid "" -"Jade v1.1 - This is a DSSSL processor for converting " -"SGML to various formats. http://www.jclark.com/jade" -msgstr "" -"Jade v1.1 - c'est un moteur DSSSL pour convertir le " -"SGML en divers formats. http://www.jclark.com/jade" - -#: C/index.docbook:302(sect2/para) +#. (itstool) path: sect2/para +#: C/index.docbook:316 msgid "" -"Modular DocBook Stylesheets 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. http://nwalsh.com/docbook/dsssl" +"python 2/3 - the main scripts are written in python." msgstr "" -"Modular DocBook Stylesheets - c'est le code DSSSL " -"utilisé pour convertir de DocBook vers HTML (ainsi que quelques autres " -"formats). Il est utilisé conjointement avec Jade. J'ai légèrement " -"personnalisé le code DSSSL, dans gtk-doc.dsl, pour coloriser les listings de " -"code du programme et les déclarations ainsi que pour prendre en charge les " -"indices globaux des références croisées dans le HTML généré. http://nwalsh.com/docbook/" -"dsssl" +"python 2/3 - les principaux scripts sont écrits en " +"Python." -#: C/index.docbook:311(sect2/para) +#. (itstool) path: sect2/para +#: C/index.docbook:319 msgid "" -"docbook-to-man - 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 http://www.ora.com/davenport NOTE: This does not work yet." +"xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" msgstr "" -"docbook-to-man - si vous souhaitez créer des pages de " -"manuel depuis DocBook. J'ai légèrement adapté les « spécifications de " -"traduction » pour mettre en majuscule les en-têtes de section et pour " -"ajouter le titre « GTK Library » en haut des pages et la date de révision en " -"bas. Il y a un lien sur cela ici http://www.ora.com/davenport. Note : cela ne " -"fonctionne pas encore." - -#: C/index.docbook:322(sect2/title) -msgid "Installation" -msgstr "Installation" -#: C/index.docbook:323(sect2/para) +#. (itstool) path: sect2/para +#: C/index.docbook:323 msgid "" -"There is no standard place where the DocBook Modular Stylesheets are " -"installed." -msgstr "" -"Il n'y a pas d'emplacement standard pour l'installation des feuilles de " -"styles modulaires de DocBook." - -#: C/index.docbook:326(sect2/para) -msgid "GTK-Doc's configure script searches these 3 directories automatically:" +"docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" msgstr "" -"Les scripts d'installation de GTK-Doc cherchent dans ces trois répertoires " -"automatiquement :" -#: C/index.docbook:329(sect2/para) +#. (itstool) path: sect2/para +#: C/index.docbook:327 msgid "" -" /usr/lib/sgml/stylesheets/nwalsh-modular (used by " -"RedHat)" +"One of source-highlight, highlight " +"or vim - optional - used for syntax highlighting of " +"examples" msgstr "" -" /usr/lib/sgml/stylesheets/nwalsh-modular (utilisé par " -"Red Hat)" -#: C/index.docbook:332(sect2/para) -msgid "" -" /usr/lib/dsssl/stylesheets/docbook (used by Debian)" -msgstr "" -" /usr/lib/dsssl/stylesheets/docbook (utilisé par " -"Debian)" - -#: C/index.docbook:335(sect2/para) -msgid " /usr/share/sgml/docbkdsl (used by SuSE)" -msgstr " /usr/share/sgml/docbkdsl (utilisé par SuSE)" - -#: C/index.docbook:338(sect2/para) -msgid "" -"If you have the stylesheets installed somewhere else, you need to configure " -"GTK-Doc using the option: --with-dsssl-dir=<" -"PATH_TO_TOPLEVEL_STYLESHEETS_DIR> " -msgstr "" -"Si les feuilles de styles sont installées autre part, vous devez configurer " -"GTK-Doc en utilisant l'option : --with-dsssl-dir=<" -"CHEMIN_VERS_REPERTOIRE_RACINE_FEUILLES2STYLEs>." - -#: C/index.docbook:362(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:335 msgid "About GTK-Doc" msgstr "À propos de GTK-Doc" -#: C/index.docbook:364(sect1/para) C/index.docbook:378(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:337 C/index.docbook:351 msgid "(FIXME)" msgstr "(À COMPLETER)" -#: C/index.docbook:368(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:341 msgid "" -"(History, authors, web pages, license, future plans, comparison with other " -"similar systems.)" +"(History, authors, web pages, mailing list, license, future plans, " +"comparison with other similar systems.)" msgstr "" -"(Historique, auteurs, pages Web, licence, projets futurs, comparaison avec " -"des systèmes similaires.)" +"(Historique, auteurs, pages Web, liste de diffusion, licence, projets " +"futurs, comparaison avec des systèmes similaires.)" -#: C/index.docbook:376(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:349 msgid "About this Manual" msgstr "À propos de ce manuel" -#: C/index.docbook:382(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:355 msgid "(who it is meant for, where you can get it, license)" msgstr "(qui est concerné, où le récupérer, licence)" -#: C/index.docbook:391(chapter/title) +#. (itstool) path: chapter/title +#: C/index.docbook:364 msgid "Setting up your project" msgstr "Mise en place de votre projet" -#: C/index.docbook:393(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:366 msgid "" "The next sections describe what steps to perform to integrate GTK-Doc into " "your project. Theses sections assume we work on a project called 'meep'. " @@ -593,11 +665,13 @@ msgstr "" "link> décrit les éléments de base à respecter pour travailler dans une autre " "configuration de construction." -#: C/index.docbook:404(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:377 msgid "Setting up a skeleton documentation" msgstr "Mise en place du squelette de documentation" -#: C/index.docbook:406(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:379 msgid "" "Under your top-level project directory create folders called docs/reference " "(this way you can also have docs/help for end-user documentation). It is " @@ -610,15 +684,29 @@ msgstr "" "répertoire portant le nom du paquet de documentation. Pour les paquets qui " "contiennent seulement une bibliothèque, cette étape n'est pas nécessaire." -#: C/index.docbook:415(example/title) +#. (itstool) path: example/title +#: C/index.docbook:388 msgid "Example directory structure" msgstr "Exemple d'arborescence de répertoires" -#: C/index.docbook:416(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:389 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "meep/\n" +#| " docs/\n" +#| " reference/\n" +#| " libmeep/\n" +#| " meeper/\n" +#| " src/\n" +#| " libmeep/\n" +#| " meeper/\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "meep/\n" " docs/\n" " reference/\n" @@ -627,11 +715,8 @@ msgid "" " src/\n" " libmeep/\n" " meeper/\n" -"\n" -" " msgstr "" "\n" -"\n" "meep/\n" " docs/\n" " reference/\n" @@ -640,18 +725,20 @@ msgstr "" " src/\n" " libmeep/\n" " meeper/\n" -"\n" -" " -#: C/index.docbook:413(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:386 msgid "This can then look as shown below: <_:example-1/>" msgstr "Cela peut ressembler à ce qui suit : <_:example-1/>" -#: C/index.docbook:433(sect1/title) C/index.docbook:440(example/title) +#. (itstool) path: sect1/title +#. (itstool) path: example/title +#: C/index.docbook:404 C/index.docbook:411 msgid "Integration with autoconf" msgstr "Intégration avec autoconf" -#: C/index.docbook:435(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:406 msgid "" "Very easy! Just add one line to your configure.ac " "script." @@ -659,53 +746,45 @@ msgstr "" "C'est très simple ! Il faut juste ajouter une ligne dans votre script " "configure.ac." -#: C/index.docbook:441(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:412 #, no-wrap msgid "" "\n" -"\n" "# check for gtk-doc\n" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" -"\n" -" " msgstr "" "\n" -"\n" "# check for gtk-doc\n" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" -"\n" -" " -#: C/index.docbook:455(example/title) +#. (itstool) path: example/title +#: C/index.docbook:424 msgid "Keep gtk-doc optional" msgstr "Laisser gtk-doc optionnel" -#: C/index.docbook:456(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:425 #, no-wrap msgid "" "\n" -"\n" "# check for gtk-doc\n" "m4_ifdef([GTK_DOC_CHECK], [\n" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" "],[\n" "AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n" "])\n" -"\n" -" " msgstr "" "\n" -"\n" "# check for gtk-doc\n" "m4_ifdef([GTK_DOC_CHECK], [\n" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" "],[\n" "AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n" "])\n" -"\n" -" " -#: C/index.docbook:450(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:419 msgid "" "This will require all developers to have gtk-doc installed. If it is okay " "for your project to have optional api-doc build setup, you can solve this as " @@ -718,7 +797,8 @@ msgstr "" "modifiez pas car gtkdocize recherche GTK_DOC_CHECK au " "début d'une ligne. <_:example-1/>" -#: C/index.docbook:469(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:436 msgid "" "The first argument is used to check for the gtkdocversion at configure time. " "The 2nd, optional argument is used by gtkdocize. " @@ -730,31 +810,34 @@ msgstr "" "gtkdocize. La macro GTK_DOC_CHECK ajoute également plusieurs drapeaux de configuration :" -#: C/index.docbook:475(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:442 msgid "--with-html-dir=PATH : path to installed docs" msgstr "" "--with-html-dir=CHEMIN : répertoire d'installation de la documentation," -#: C/index.docbook:476(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:443 msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "" "--enable-gtk-doc : utilisation de gtk-doc pour construire la documentation " "[par défaut=no]," -#: C/index.docbook:477(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:444 msgid "" "--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" "--enable-gtk-doc-html : construction de la documentation au format html [par " "défaut=yes]," -#: C/index.docbook:478(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:445 msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" -msgstr "" -"--enable-gtk-doc-pdf : construction de la documentation au format pdf [par " -"défaut=no]." +msgstr "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" -#: C/index.docbook:482(important/para) +#. (itstool) path: important/para +#: C/index.docbook:449 msgid "" "GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " @@ -767,9 +850,16 @@ msgstr "" "générée est installée (ce qui a du sens pour les utilisateurs mais pas pour " "les développeurs)." -#: C/index.docbook:490(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:457 +#, fuzzy +#| msgid "" +#| "Furthermore it is recommended that you have the following line inside you " +#| "configure.ac script. This allows " +#| "gtkdocize to automatically copy the macro " +#| "definition for GTK_DOC_CHECK to your project." msgid "" -"Furthermore it is recommended that you have the following line inside you " +"Furthermore it is recommended that you have the following line inside your " "configure.ac script. This allows " "gtkdocize to automatically copy the macro " "definition for GTK_DOC_CHECK to your project." @@ -779,35 +869,57 @@ msgstr "" "application> de copier automatiquement les définitions de macro pour " "GTK_DOC_CHECK à votre projet." -#: C/index.docbook:498(example/title) +#. (itstool) path: example/title +#: C/index.docbook:465 msgid "Preparation for gtkdocize" msgstr "Préparation pour gtkdocize" -#: C/index.docbook:499(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:466 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "AC_CONFIG_MACRO_DIR(m4)\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "AC_CONFIG_MACRO_DIR(m4)\n" -"\n" -" " msgstr "" "\n" -"\n" "AC_CONFIG_MACRO_DIR(m4)\n" -"\n" -" " -#: C/index.docbook:509(sect1/title) +#. (itstool) path: sect1/para +#: C/index.docbook:471 +msgid "" +"After all changes to configure.ac are made, update the " +"configure file. This can be done by re-running " +"autoreconf -i or autogen.sh." +msgstr "" + +#. (itstool) path: sect1/title +#: C/index.docbook:479 msgid "Integration with automake" msgstr "Intégration avec automake" -#: C/index.docbook:511(sect1/para) -msgid "" -"First copy the Makefile.am from the examples " -"subdirectory of the gtkdoc-sources to your project's API documentation " -"directory ( ./docs/reference/<package>). If you have multiple doc-packages repeat this for each one." +#. (itstool) path: sect1/para +#: C/index.docbook:481 +#, fuzzy +#| msgid "" +#| "First copy the Makefile.am from the examples " +#| "subdirectory of the gtkdoc-sources to your project's API documentation " +#| "directory ( ./docs/reference/<package>" +#| "). If you have multiple doc-packages repeat this for each one." +msgid "" +"First copy the Makefile.am from the examples sub directory of the gtkdoc-sources to your project's API documentation directory ( ./docs/reference/<package>). A local copy " +"should be available under e.g. /usr/share/doc/gtk-doc-tools/" +"examples/Makefile.am. If you have multiple doc-packages repeat " +"this for each one." msgstr "" "Pour commencer, copiez le fichier Makefile.am depuis le " "sous-répertoire des exemples de gtkdoc-sources vers le répertoire de " @@ -815,7 +927,8 @@ msgstr "" "reference/<paquet>). S'il y a plusieurs paquets de " "documentation, répétez cette étape pour chacun d'eux." -#: C/index.docbook:518(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:492 msgid "" "The next step is to edit the settings inside the Makefile.am. All the settings have a comment above that describes their " @@ -832,40 +945,13 @@ msgstr "" "_OPTIONS. Tous les outils prennent en charge l'option qui affiche la liste des options prises en charge." -#: C/index.docbook:529(sect1/para) -msgid "" -"You may also want to enable GTK-Doc for the distcheck make target. Just add " -"the one line shown in the next example to your top-level Makefile." -"am:" -msgstr "" -"Il est aussi possible d'activer GTK-Doc pour la cible distcheck de make. Il " -"faut juste ajouter la ligne suivante au fichier Makefile.am du répertoire racine :" - -#: C/index.docbook:536(example/title) -msgid "Enable GTK-Doc during make distcheck" -msgstr "Activation de GTK-Doc pendant le « make distcheck »" - -#: C/index.docbook:537(example/programlisting) -#, no-wrap -msgid "" -"\n" -"\n" -"DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc\n" -"\n" -" " -msgstr "" -"\n" -"\n" -"DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc\n" -"\n" -" " - -#: C/index.docbook:548(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:506 msgid "Integration with autogen" msgstr "Intégration avec autogen" -#: C/index.docbook:550(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:508 msgid "" "Most projects will have an autogen.sh script to setup " "the build infrastructure after a checkout from version control system (such " @@ -880,26 +966,29 @@ msgstr "" "utilisé dans un script comme celui-ci. Il doit être lancé avant autoheader, " "automake ou autoconf." -#: C/index.docbook:559(example/title) +#. (itstool) path: example/title +#: C/index.docbook:517 msgid "Running gtkdocize from autogen.sh" msgstr "Exécution de gtkdocize depuis autogen.sh" -#: C/index.docbook:560(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:518 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "gtkdocize || exit 1\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "gtkdocize || exit 1\n" -"\n" -" " msgstr "" "\n" -"\n" "gtkdocize || exit 1\n" -"\n" -" " -#: C/index.docbook:568(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:524 msgid "" "When running gtkdocize it copies gtk-" "doc.make to your project root (or any directory specified by the " @@ -914,7 +1003,8 @@ msgstr "" "configure. Cette macro peut être utilisée pour transmettre des paramètres " "supplémentaires à gtkdocize." -#: C/index.docbook:577(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:533 msgid "" "Historically GTK-Doc was generating template files where developers entered " "the docs. This turned out to be not so good (e.g. the need for having " @@ -948,11 +1038,14 @@ msgstr "" "d'anciennes versions de gtkdoc, supprimez le répertoire (par ex. à partir du " "système de gestion de versions)." -#: C/index.docbook:594(sect1/title) C/index.docbook:611(example/title) +#. (itstool) path: sect1/title +#. (itstool) path: example/title +#: C/index.docbook:550 C/index.docbook:567 msgid "Running the doc build" msgstr "Lancement de la construction de la documentation" -#: C/index.docbook:596(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:552 msgid "" "After the previous steps it's time to run the build. First we need to rerun " "autogen.sh. If this script runs configure for you, then " @@ -965,7 +1058,8 @@ msgstr "" "enable-gtk-doc, sinon lancez manuellement configure suivi de cette option." -#: C/index.docbook:603(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:559 msgid "" "The first make run generates several additional files in the doc-" "directories. The important ones are: <package>.types (anciennement .sgml), <paquet>-sections." "txt." -#: C/index.docbook:612(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:568 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "./autogen.sh --enable-gtk-doc\n" +#| "make\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "./autogen.sh --enable-gtk-doc\n" "make\n" -"\n" -" " msgstr "" "\n" -"\n" "./autogen.sh --enable-gtk-doc\n" "make\n" -"\n" -" " -#: C/index.docbook:620(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:574 msgid "" "Now you can point your browser to docs/reference/<package>/" "index.html. Yes, it's a bit disappointing still. But hang-on, " @@ -1006,17 +1103,26 @@ msgstr "" "encore un peu décevant mais le prochain chapitre va expliquer comment donner " "de la vie à ces pages." -#: C/index.docbook:628(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:582 msgid "Integration with version control systems" msgstr "Intégration avec des systèmes de gestion de versions" -#: C/index.docbook:630(sect1/para) -msgid "" -"As a rule of the thumb, it's those files you edit, that should go under " -"version control. For typical projects it's these files: <" -"package>.types, <package>-docs..xml " -"(in the past .sgml), <package>-sections.txt, " -"Makefile.am" +#. (itstool) path: sect1/para +#: C/index.docbook:584 +#, fuzzy +#| msgid "" +#| "As a rule of the thumb, it's those files you edit, that should go under " +#| "version control. For typical projects it's these files: <" +#| "package>.types, <package>-docs..xml (in the past .sgml), <package>-sections.txt, Makefile.am" +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: <package>." +"types, <package>-docs.xml (in the " +"past .sgml), <package>-sections.txt, " +"Makefile.am." msgstr "" "Comme le veut la règle de base, ce sont les fichiers que vous modifiez qui " "doivent être placés dans le système de gestion de versions. Pour les projets " @@ -1025,13 +1131,23 @@ msgstr "" "<paquet>-sections.txt, Makefile.am" -#: C/index.docbook:641(sect1/title) +#. (itstool) path: sect1/para +#: C/index.docbook:592 +msgid "" +"Files in the xml/ and html/ " +"directories should not go under version control. Neither should any of the " +".stamp files." +msgstr "" + +#. (itstool) path: sect1/title +#: C/index.docbook:600 msgid "Integration with plain makefiles or other build systems" msgstr "" "Intégration avec des « makefiles » simples et d'autres systèmes de " "compilation" -#: C/index.docbook:643(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:602 msgid "" "In the case one does not want to use automake and therefore gtk-" "doc.mak one will need to call the gtkdoc tools in the right order " @@ -1042,42 +1158,53 @@ msgstr "" "gtkdoc dans le bon ordre dans les fichiers « makefiles » ad hoc (ou d'autres " "systèmes)." -#: C/index.docbook:650(example/title) +#. (itstool) path: example/title +#: C/index.docbook:609 msgid "Documentation build steps" msgstr "Étapes de construction de la documentation" -#: C/index.docbook:651(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:610 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "DOC_MODULE=meep\n" +#| "// sources have changed\n" +#| "gtkdoc-scan --module=$(DOC_MODULE) --source-dir=...\n" +#| "gtkdoc-scangobj --module=$(DOC_MODULE)\n" +#| "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml\n" +#| "// xml files have changed\n" +#| "mkdir html\n" +#| "cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n" +#| "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "DOC_MODULE=meep\n" "// sources have changed\n" -"gtkdoc-scan --module=$(DOC_MODULE) --source-dir=...\n" +"gtkdoc-scan --module=$(DOC_MODULE) <source-dir>\n" "gtkdoc-scangobj --module=$(DOC_MODULE)\n" -"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml\n" +"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>\n" "// xml files have changed\n" "mkdir html\n" "cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n" "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" -"\n" -" " msgstr "" "\n" -"\n" "DOC_MODULE=meep\n" "// sources have changed\n" -"gtkdoc-scan --module=$(DOC_MODULE) --source-dir=...\n" +"gtkdoc-scan --module=$(DOC_MODULE) <source-dir>\n" "gtkdoc-scangobj --module=$(DOC_MODULE)\n" -"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml\n" +"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>\n" "// xml files have changed\n" "mkdir html\n" "cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n" "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" -"\n" -" " -#: C/index.docbook:667(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:624 msgid "" "One will need to look at the Makefile.am and " "gtk-doc.mak to pick the extra options needed." @@ -1086,11 +1213,84 @@ msgstr "" "gtk-doc.mak pour y trouver les options supplémentaires " "nécessaires." -#: C/index.docbook:676(chapter/title) +#. (itstool) path: sect1/title +#: C/index.docbook:631 +#, fuzzy +#| msgid "Integration with plain makefiles or other build systems" +msgid "Integration with CMake build systems" +msgstr "" +"Intégration avec des « makefiles » simples et d'autres systèmes de " +"compilation" + +#. (itstool) path: sect1/para +#: C/index.docbook:633 +msgid "" +"GTK-Doc now provides a GtkDocConfig.cmake module (and " +"the corresponding GtkDocConfigVersion.cmake module). " +"This provides a gtk_doc_add_module command that you can " +"set in your CMakeLists.txt file." +msgstr "" + +#. (itstool) path: example/title +#: C/index.docbook:643 +msgid "Example of using GTK-Doc from CMake" +msgstr "Exemple d'utilisation de GTK-Doc depuis CMake" + +#. (itstool) path: example/programlisting +#: C/index.docbook:644 +#, no-wrap +msgid "" +"\n" +"find_package(GtkDoc 1.25 REQUIRED)\n" +"\n" +"# Create the doc-libmeep target.\n" +"gtk_doc_add_module(\n" +" libmeep ${CMAKE_SOURCE_DIR}/libmeep\n" +" XML meep-docs.xml\n" +" LIBRARIES libmeep\n" +")\n" +"\n" +"# Build doc-libmeep as part of the default target. Without this, you would\n" +"# have to explicitly run something like `make doc-libmeep` to build the docs.\n" +"add_custom_target(documentation ALL DEPENDS doc-libmeep)\n" +"\n" +"# Install the docs. (This assumes you're using the GNUInstallDirs CMake module\n" +"# to set the CMAKE_INSTALL_DOCDIR variable correctly).\n" +"install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html\n" +" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" +msgstr "" +"\n" +"find_package(GtkDoc 1.25 REQUIRED)\n" +"\n" +"# Create the doc-libmeep target.\n" +"gtk_doc_add_module(\n" +" libmeep ${CMAKE_SOURCE_DIR}/libmeep\n" +" XML meep-docs.xml\n" +" LIBRARIES libmeep\n" +")\n" +"\n" +"# Build doc-libmeep as part of the default target. Without this, you would\n" +"# have to explicitly run something like `make doc-libmeep` to build the docs.\n" +"add_custom_target(documentation ALL DEPENDS doc-libmeep)\n" +"\n" +"# Install the docs. (This assumes you're using the GNUInstallDirs CMake module\n" +"# to set the CMAKE_INSTALL_DOCDIR variable correctly).\n" +"install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html\n" +" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:641 +msgid "The following example shows how to use this command. <_:example-1/>" +msgstr "" +"L'exemple suivant montre comment utiliser cette commande. <_:example-1/>" + +#. (itstool) path: chapter/title +#: C/index.docbook:669 msgid "Documenting the code" msgstr "Documentation du code" -#: C/index.docbook:678(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:671 msgid "" "GTK-Doc uses source code comment with a special syntax for code " "documentation. Further it retrieves information about your project structure " @@ -1102,11 +1302,13 @@ msgstr "" "structure de votre projet à partir d'autres sources. La section suivante " "vous donne toutes les informations concernant la syntaxe des commentaires." -#: C/index.docbook:686(note/title) +#. (itstool) path: note/title +#: C/index.docbook:679 msgid "Documentation placement" msgstr "Emplacement de la documentation" -#: C/index.docbook:687(note/para) +#. (itstool) path: note/para +#: C/index.docbook:680 msgid "" "In the past most documentation had to be filled into files residing inside " "the tmpl directory. This has the disadvantages that the " @@ -1119,7 +1321,8 @@ msgstr "" "fichiers avaient tendance à provoquer des conflits avec les systèmes de " "gestion de versions." -#: C/index.docbook:693(note/para) +#. (itstool) path: note/para +#: C/index.docbook:686 msgid "" "The avoid the aforementioned problems we suggest putting the documentation " "inside the sources. This manual will only describe this way of documenting " @@ -1128,32 +1331,42 @@ msgstr "" "Pour éviter ces problèmes, il est conseillé de placer la documentation dans " "le code source. Ce manuel ne décrit que cette manière de documenter du code." -#: C/index.docbook:704(example/title) C/index.docbook:723(example/title) +#. (itstool) path: example/title +#: C/index.docbook:697 C/index.docbook:723 msgid "GTK-Doc comment block" msgstr "Bloc de commentaire GTK-Doc" -#: C/index.docbook:705(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:698 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "#ifndef __GTK_DOC_IGNORE__\n" +#| "/* unparseable code here */\n" +#| "#endif\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "#ifndef __GTK_DOC_IGNORE__\n" "/* unparseable code here */\n" "#endif\n" -"\n" -" " msgstr "" "\n" -"\n" "#ifndef __GTK_DOC_IGNORE__\n" "/* unparseable code here */\n" "#endif\n" -"\n" -" " -#: C/index.docbook:700(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:693 +#, fuzzy +#| msgid "" +#| "The scanner can handle the majority of c headers fine. In the case of " +#| "receiving warnings from the scanner that look like a special case, one " +#| "can hint GTK-Doc to skip over them. <_:example-1/>" msgid "" -"The scanner can handle the majority of c headers fine. In the case of " +"The scanner can handle the majority of C headers fine. In the case of " "receiving warnings from the scanner that look like a special case, one can " "hint GTK-Doc to skip over them. <_:example-1/>" msgstr "" @@ -1162,32 +1375,51 @@ msgstr "" "l'air d'être des cas spéciaux, vous pouvez indiquer à GTK-Doc de les passer. " "<_:example-1/>" -#: C/index.docbook:718(sect1/title) +#. (itstool) path: note/title +#: C/index.docbook:707 +#| msgid "Dedications" +msgid "Limitations" +msgstr "Limitations" + +#. (itstool) path: note/para +#: C/index.docbook:708 +msgid "" +"Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but " +"not #if !defined(__GTK_DOC_IGNORE__) or other combinations." +msgstr "" + +#. (itstool) path: sect1/title +#: C/index.docbook:718 msgid "Documentation comments" msgstr "Commentaires de documentation" -#: C/index.docbook:724(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:724 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "/**\n" +#| " * identifier:\n" +#| " * documentation ...\n" +#| " */\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "/**\n" " * identifier:\n" " * documentation ...\n" " */\n" -"\n" -" " msgstr "" "\n" -"\n" "/**\n" " * identifier:\n" " * documentation ...\n" " */\n" -"\n" -" " -#: C/index.docbook:720(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:720 msgid "" "A multiline comment that starts with an additional '*' marks a documentation " "block that will be processed by the GTK-Doc tools. <_:example-1/>" @@ -1196,7 +1428,8 @@ msgstr "" "indique un bloc de documentation qui sera traité par les outils GTK-Doc. <_:" "example-1/>" -#: C/index.docbook:735(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:733 msgid "" "The 'identifier' is one line with the name of the item the comment is " "related to. The syntax differs a little depending on the item. (TODO add " @@ -1207,12 +1440,23 @@ msgstr "" "fonction de l'élément. (À FAIRE : ajouter un tableau montrant les " "identifiants)" -#: C/index.docbook:741(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:739 +#, fuzzy +#| msgid "" +#| "The 'documentation' block is also different for each symbol type. Symbol " +#| "types that get parameters such as functions or macros have the parameter " +#| "description first followed by a blank line (just a '*'). Afterwards " +#| "follows the detailed description. All lines (outside program- listings " +#| "and CDATA sections) just containing a ' *' (blank-asterisk) are converted " +#| "to paragraph breaks. If you don't want a paragraph break, change that " +#| "into ' * ' (blank-asterisk-blank-blank). This is useful in preformatted " +#| "text (code listings)." msgid "" "The 'documentation' block is also different for each symbol type. Symbol " "types that get parameters such as functions or macros have the parameter " "description first followed by a blank line (just a '*'). Afterwards follows " -"the detailed description. All lines (outside program- listings and CDATA " +"the detailed description. All lines (outside program listings and CDATA " "sections) just containing a ' *' (blank-asterisk) are converted to paragraph " "breaks. If you don't want a paragraph break, change that into ' * ' (blank-" "asterisk-blank-blank). This is useful in preformatted text (code listings)." @@ -1226,7 +1470,8 @@ msgstr "" "paragraphe. Si vous ne désirez pas de saut de paragraphe, modifiez-les en " "«  *   » (espace-astérisque-espace-espace)." -#: C/index.docbook:758(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:756 msgid "" "What it is: The name for a class or function can sometimes be misleading for " "people coming from a different background." @@ -1234,26 +1479,30 @@ msgstr "" "Ce que c'est : le nom d'une classe ou d'une fonction peut parfois être " "trompeur pour les personnes habituées à d'autres environnements." -#: C/index.docbook:764(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:762 msgid "" "What it does: Tell about common uses. Put it in relation with the other API." msgstr "" "Ce qu'il fait : indiquer les usages courants. À mettre en relation avec les " "autres API." -#: C/index.docbook:754(tip/para) +#. (itstool) path: tip/para +#: C/index.docbook:752 msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" msgstr "" "En documentant le code, deux aspects doivent être abordés : <_:" "itemizedlist-1/>" -#: C/index.docbook:779(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:777 msgid "Use function() to refer to functions or macros which take arguments." msgstr "" "Utilisez fonction() pour vous référer à des fonctions ou des macros qui " "prennent des arguments." -#: C/index.docbook:784(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:782 msgid "" "Use @param to refer to parameters. Also use this when referring to " "parameters of other functions, related to the one being described." @@ -1261,13 +1510,15 @@ msgstr "" "Utilisez @paramètre pour vous référer aux paramètres. Utilisez-le aussi pour " "les paramètres d'autres fonctions, en relation avec celle décrite." -#: C/index.docbook:790(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:788 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "" "Utilisez %constante pour vous référer à une constante, par ex. : " "%MA_CONSTANTE." -#: C/index.docbook:795(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:793 msgid "" "Use #symbol to refer to other types of symbol, e.g. structs and enums and " "macros which don't take arguments." @@ -1275,19 +1526,31 @@ msgstr "" "Utilisez #symbole pour vous référer à d'autres types de symbole. Par exemple " "des structures, énumérations ou macros qui ne prennent pas d'arguments." -#: C/index.docbook:801(listitem/para) -msgid "Use #Object::signal to refer to a GObject signal" +#. (itstool) path: listitem/para +#: C/index.docbook:799 +#, fuzzy +#| msgid "Use #Object::signal to refer to a GObject signal" +msgid "Use #Object::signal to refer to a GObject signal." msgstr "Utilisez #Objet::signal pour vous référer à un signal GObject." -#: C/index.docbook:806(listitem/para) -msgid "Use #Object:property to refer to a GObject property" +#. (itstool) path: listitem/para +#: C/index.docbook:804 +#, fuzzy +#| msgid "Use #Object:property to refer to a GObject property" +msgid "Use #Object:property to refer to a GObject property." msgstr "Utilisez #Objet::propriété pour vous référer à une propriété GObject." -#: C/index.docbook:811(listitem/para) -msgid "Use #Struct.field to refer to a field inside a structure." +#. (itstool) path: listitem/para +#: C/index.docbook:809 +#, fuzzy +#| msgid "Use #Struct.field to refer to a field inside a structure." +msgid "" +"Use #Struct.field to refer to a field inside a structure and #GObjectClass." +"foo_bar() to refer to a vmethod." msgstr "Utilisez #Structure.champ pour vous référer au champ d'une stucture." -#: C/index.docbook:773(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:771 msgid "" "One advantage of hyper-text over plain-text is the ability to have links in " "the document. Writing the correct markup for a link can be tedious though. " @@ -1299,7 +1562,8 @@ msgstr "" "balisage d'un lien peut être fastidieux. GTK-Doc fournit plusieurs " "raccourcis utiles pour vous aider. <_:itemizedlist-1/>" -#: C/index.docbook:819(tip/para) +#. (itstool) path: tip/para +#: C/index.docbook:818 msgid "" "If you need to use the special characters '<', '>', '()', '@', '%', or " "'#' in your documentation without GTK-Doc changing them you can use the XML " @@ -1313,12 +1577,39 @@ msgstr "" "gt; », « &lpar; », « &rpar; », « &commat; », « &percnt; », " "« &num; » ou les échapper en les précédant d'un antislash « \\ »." -#: C/index.docbook:828(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:827 msgid "" -"DocBook can do more than just links. One can also have lists, tables and " -"examples. To enable the usage of docbook SGML/XML tags inside doc-comments " -"you need to have or " -"in the variable MKDB_OPTIONS inside Makefile.amMarkdown. On older GTK-Doc " +"versions any documentation that includes Markdown will be rendered as is. " +"For example, list items will appear as lines starting with a dash." +msgstr "" + +#. (itstool) path: sect1/para +#: C/index.docbook:838 +msgid "" +"While markdown is now preferred one can mix both. One limitation here is " +"that one can use docbook xml within markdown, but markdown within docbook " +"xml is not supported." +msgstr "" + +#. (itstool) path: sect1/para +#: C/index.docbook:844 +#, fuzzy +#| msgid "" +#| "DocBook can do more than just links. One can also have lists, tables and " +#| "examples. To enable the usage of docbook SGML/XML tags inside doc-" +#| "comments you need to have or in the variable MKDB_OPTIONS inside " +#| "Makefile.am." +msgid "" +"In older GTK-Doc releases, if you need support for additional formatting, " +"you would need to enable the usage of docbook XML tags inside doc-comments " +"by putting (or ) in " +"the variable MKDB_OPTIONS inside Makefile.am." msgstr "" "DocBook peut faire plus que des liens. Il peut aussi générer des listes, des " @@ -1328,65 +1619,64 @@ msgstr "" "variable MKDB_OPTIONS du fichier Makefile.am." -#: C/index.docbook:842(example/title) -msgid "GTK-Doc comment block using markdown" +#. (itstool) path: example/title +#: C/index.docbook:853 +#, fuzzy +#| msgid "GTK-Doc comment block using markdown" +msgid "GTK-Doc comment block using Markdown" msgstr "Bloc de commentaire GTK-Doc utilisant la syntaxe markdown" -#: C/index.docbook:843(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:854 #, no-wrap msgid "" "\n" -"\n" "/**\n" " * identifier:\n" " *\n" -" * documentation ...\n" +" * documentation paragraph ...\n" " *\n" -" * # Sub heading #\n" +" * # Sub Heading #\n" +" *\n" +" * ## Second Sub Heading\n" +" *\n" +" * # Sub Heading With a Link Anchor # {#heading-two}\n" " *\n" " * more documentation:\n" +" *\n" " * - list item 1\n" +" *\n" +" * Paragraph inside a list item.\n" +" *\n" " * - list item 2\n" " *\n" -" * Even more docs.\n" -" */\n" -"\n" -" " -msgstr "" -"\n" -"\n" -"/**\n" -" * identifier:\n" +" * 1. numbered list item\n" " *\n" -" * documentation ...\n" +" * 2. another numbered list item\n" " *\n" -" * # Sub heading #\n" +" * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)\n" " *\n" -" * more documentation:\n" -" * - list item 1\n" -" * - list item 2\n" +" * ![an inline image](plot-result.png)\n" +" *\n" +" * [A link to the heading anchor above][heading-two]\n" " *\n" -" * Even more docs.\n" +" * A C-language example:\n" +" * |[<!-- language=\"C\" -->\n" +" * GtkWidget *label = gtk_label_new (\"Gorgeous!\");\n" +" * ]|\n" " */\n" -"\n" -" " +msgstr "" -#: C/index.docbook:836(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:893 msgid "" -"Since GTK-Doc-1.18 the tool supports a subset or the markdown language. One can " -"use it for sub-headings and simple itemized lists. On older GTK-Doc versions " -"the content will be rendered as it (the list items will appear in one line " -"separated by dashes). <_:example-1/>" +"More examples of what markdown tags are supported can be found in the GTK+ Documentation Markdown Syntax Reference." msgstr "" -"À partir de GTK-Doc 1.18, il est possible d'utiliser un sous-ensemble de la " -"syntaxe " -"markdown. On peut l'utiliser pour les sous-titres et les listes à " -"puces simples. Dans des versions plus anciennes de GTK-Doc, le contenu est " -"affiché tel quel (les éléments d'une liste sont affichés sur une seule " -"ligne, séparés par des tirets). <_:example-1/>" -#: C/index.docbook:864(tip/para) +#. (itstool) path: tip/para +#: C/index.docbook:899 msgid "" "As already mentioned earlier GTK-Doc is for documenting public API. Thus one " "cannot write documentation for static symbols. Nevertheless it is good to " @@ -1405,11 +1695,13 @@ msgstr "" "d'ajouter un « * » dans le bloc de commentaires et d'ajouter le nom du " "symbole à la bonne place à l'intérieur du fichier des sections." -#: C/index.docbook:878(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:913 msgid "Documenting sections" msgstr "Documentation des sections" -#: C/index.docbook:880(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:915 msgid "" "Each section of the documentation contains information about one class or " "module. To introduce the component one can write a section block. The short " @@ -1421,15 +1713,33 @@ msgstr "" "de section. La description courte est également utilisée dans la table des " "matières. Tous les @champs sont facultatifs." -#: C/index.docbook:888(example/title) +#. (itstool) path: example/title +#: C/index.docbook:923 msgid "Section comment block" msgstr "Bloc de commentaires de section" -#: C/index.docbook:889(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:924 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "/**\n" +#| " * SECTION:meepapp\n" +#| " * @short_description: the application class\n" +#| " * @title: Meep application\n" +#| " * @section_id:\n" +#| " * @see_also: #MeepSettings\n" +#| " * @stability: Stable\n" +#| " * @include: meep/app.h\n" +#| " * @image: application.png\n" +#| " *\n" +#| " * The application class handles ...\n" +#| " */\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "/**\n" " * SECTION:meepapp\n" " * @short_description: the application class\n" @@ -1442,11 +1752,8 @@ msgid "" " *\n" " * The application class handles ...\n" " */\n" -"\n" -" " msgstr "" "\n" -"\n" "/**\n" " * SECTION:meepapp\n" " * @short_description: the application class\n" @@ -1459,17 +1766,23 @@ msgstr "" " *\n" " * The application class handles ...\n" " */\n" -"\n" -" " -#: C/index.docbook:910(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:943 msgid "SECTION:<name>" msgstr "SECTION:<nom>" -#: C/index.docbook:912(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:945 +#, fuzzy +#| msgid "" +#| "The name links the section documentation to the respective part in the " +#| "<package>-sections.txt file. The name give " +#| "here should match the <FILE> tag in the <package>-" +#| "sections.txt file." msgid "" "The name links the section documentation to the respective part in the " -"<package>-sections.txt file. The name give here " +"<package>-sections.txt file. The name given here " "should match the <FILE> tag in the <package>-sections." "txt file." msgstr "" @@ -1478,11 +1791,13 @@ msgstr "" "doit correspondre à la balise <FILE> du fichier <" "package>-sections.txt." -#: C/index.docbook:921(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:954 msgid "@short_description" msgstr "@short_description" -#: C/index.docbook:923(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:956 msgid "" "A one line description of the section, that later will appear after the " "links in the TOC and at the top of the section page." @@ -1490,11 +1805,13 @@ msgstr "" "Une description de la section en une seule ligne, elle apparaîtra derrière " "les liens dans la table des matières et au début de la page de la section." -#: C/index.docbook:930(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:963 msgid "@title" msgstr "@title" -#: C/index.docbook:932(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:965 msgid "" "The section title defaults to <name> from the SECTION declaration. It " "can be overridden with the @title field." @@ -1502,11 +1819,13 @@ msgstr "" "Par défaut, la section titre est celle de la déclaration SECTION: <" "nom>. Elle peut être modifiée grâce au champ @title." -#: C/index.docbook:939(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:972 msgid "@section_id" msgstr "@section_id" -#: C/index.docbook:941(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:974 msgid "" "Overrides the use of title as a section identifier. For GObjects the <" "title> is used as a section_id and for other sections it is <" @@ -1516,19 +1835,23 @@ msgstr "" "GObjects, <title> est utilisé à la place de section_id et pour les " "autres sections, c'est <MODULE>-<title>." -#: C/index.docbook:949(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:982 msgid "@see_also" msgstr "@see_also" -#: C/index.docbook:951(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:984 msgid "A list of symbols that are related to this section." msgstr "Une liste de symboles qui ont un lien avec cette section." -#: C/index.docbook:957(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:990 msgid "@stability" msgstr "@stability" -#: C/index.docbook:964(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:997 msgid "" "Stable - The intention of a Stable interface is to enable arbitrary third " "parties to develop applications to these interfaces, release them, and have " @@ -1545,7 +1868,8 @@ msgstr "" "les modifications incompatibles doivent être rares et être sérieusement " "justifiées." -#: C/index.docbook:976(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1009 msgid "" "Unstable - Unstable interfaces are experimental or transitional. They are " "typically used to give outside developers early access to new or rapidly " @@ -1561,7 +1885,8 @@ msgstr "" "de la compatibilité binaire ou de celle des sources, d'une version mineure à " "l'autre." -#: C/index.docbook:988(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1021 msgid "" "Private - An interface that can be used within the GNOME stack itself, but " "that is not documented for end-users. Such functions should only be used in " @@ -1572,7 +1897,8 @@ msgstr "" "type de fonctions ne doit être utilisé que dans des cas spécifiques et " "documentés." -#: C/index.docbook:997(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1030 msgid "" "Internal - An interface that is internal to a module and does not require " "end-user documentation. Functions that are undocumented are assumed to be " @@ -1582,19 +1908,26 @@ msgstr "" "nécessite pas de documentation pour l'utilisateur final. Les fonctions non " "documentées sont considérées comme internes." -#: C/index.docbook:959(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:992 +#, fuzzy +#| msgid "" +#| "A informal description of the stability level this API has. We recommend " +#| "the use of one of these terms: <_:itemizedlist-1/>" msgid "" -"A informal description of the stability level this API has. We recommend the " -"use of one of these terms: <_:itemizedlist-1/>" +"An informal description of the stability level this API has. We recommend " +"the use of one of these terms: <_:itemizedlist-1/>" msgstr "" "Une description informelle du niveau de stabilité de cet API. Il est " "recommandé d'utiliser l'un de ces termes : <_:itemizedlist-1/>" -#: C/index.docbook:1009(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:1042 msgid "@include" msgstr "@include" -#: C/index.docbook:1011(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1044 msgid "" "The #include files to show in the section synopsis (a " "comma separated list), overriding the global value from the fichier de section ou de la ligne de commande. Cet élément est facultatif." -#: C/index.docbook:1020(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:1053 msgid "@image" msgstr "@image" -#: C/index.docbook:1022(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1055 msgid "" "The image to display at the top of the reference page for this section. This " "will often be some sort of a diagram to illustrate the visual appearance of " @@ -1622,7 +1957,8 @@ msgstr "" "d'une classe ou un diagramme de ses relations avec d'autres classes. Cet " "élément est facultatif." -#: C/index.docbook:1033(tip/para) +#. (itstool) path: tip/para +#: C/index.docbook:1066 msgid "" "To avoid unnecessary recompilation after doc-changes put the section docs " "into the c-source where possible." @@ -1631,11 +1967,13 @@ msgstr "" "documentation, placez la documentation de section dans les fichiers sources " "C, lorsque cela est possible." -#: C/index.docbook:1042(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:1075 msgid "Documenting symbols" msgstr "Documentation des symboles" -#: C/index.docbook:1044(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1077 msgid "" "Each symbol (function, macro, struct, enum, signal and property) is " "documented in a separate block. The block is best placed close to the " @@ -1650,11 +1988,14 @@ msgstr "" "sources C et les macros et les structures et les énumérations le sont dans " "le fichier d'en-tête." -#: C/index.docbook:1052(sect2/title) C/index.docbook:1081(example/title) +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1085 C/index.docbook:1151 msgid "General tags" msgstr "Étiquettes générales" -#: C/index.docbook:1054(sect2/para) +#. (itstool) path: sect2/para +#: C/index.docbook:1087 msgid "" "You can add versioning information to all documentation elements to tell " "when an API was introduced, or when it was deprecated." @@ -1663,24 +2004,29 @@ msgstr "" "documentation pour indiquer quand l'API a été introduite ou quand elle est " "devenue obsolète." -#: C/index.docbook:1059(variablelist/title) +#. (itstool) path: variablelist/title +#: C/index.docbook:1092 msgid "Versioning Tags" msgstr "Étiquettes de version" -#: C/index.docbook:1060(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:1093 msgid "Since:" msgstr "« Since »:" -#: C/index.docbook:1062(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1095 msgid "Description since which version of the code the API is available." msgstr "" "Texte indiquant depuis quelle version du code cette API est disponible." -#: C/index.docbook:1067(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:1100 msgid "Deprecated:" msgstr "« Deprecated » :" -#: C/index.docbook:1069(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1102 msgid "" "Paragraph denoting that this function should no be used anymore. The " "description should point the reader to the new API." @@ -1688,15 +2034,97 @@ msgstr "" "Texte indiquant que cette fonction ne doit plus être utilisée. La " "description doit rediriger le lecteur vers la nouvelle API." -#: C/index.docbook:1077(sect2/para) -msgid "(FIXME : Stability information)" -msgstr "(FIXME : informations de stabilité)" +#. (itstool) path: sect2/para +#: C/index.docbook:1110 +#, fuzzy +#| msgid "" +#| "You can add versioning information to all documentation elements to tell " +#| "when an API was introduced, or when it was deprecated." +msgid "" +"You can also add stability information to all documentation elements to " +"indicate whether API stability is guaranteed for them for all future minor " +"releases of the project." +msgstr "" +"Vous pouvez ajouter des informations de version à tous les éléments de " +"documentation pour indiquer quand l'API a été introduite ou quand elle est " +"devenue obsolète." + +#. (itstool) path: sect2/para +#: C/index.docbook:1116 +msgid "" +"The default stability level for all documentation elements can be set by " +"passing the argument to " +"gtkdoc-mkdb with one of the values below." +msgstr "" + +#. (itstool) path: variablelist/title +#: C/index.docbook:1122 +#, fuzzy +#| msgid "@stability" +msgid "Stability Tags" +msgstr "@stability" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1123 +msgid "Stability: Stable" +msgstr "" + +#. (itstool) path: listitem/para +#: C/index.docbook:1125 +msgid "" +"Mark the element as stable. This is for public APIs which are guaranteed to " +"remain stable for all future minor releases of the project." +msgstr "" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1132 +msgid "Stability: Unstable" +msgstr "" + +#. (itstool) path: listitem/para +#: C/index.docbook:1134 +msgid "" +"Mark the element as unstable. This is for public APIs which are released as " +"a preview before being stabilised." +msgstr "" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1140 +msgid "Stability: Private" +msgstr "" + +#. (itstool) path: listitem/para +#: C/index.docbook:1142 +msgid "" +"Mark the element as private. This is for interfaces which can be used by " +"tightly coupled modules, but not by arbitrary third parties." +msgstr "" -#: C/index.docbook:1082(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:1152 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "/**\n" +#| " * foo_get_bar:\n" +#| " * @foo: some foo\n" +#| " *\n" +#| " * Retrieves @foo's bar.\n" +#| " *\n" +#| " * Returns: @foo's bar\n" +#| " *\n" +#| " * Since: 2.6\n" +#| " * Deprecated: 2.12: Use foo_baz_get_bar() instead.\n" +#| " **/\n" +#| "Bar *\n" +#| "foo_get_bar(Foo *foo)\n" +#| "{\n" +#| "...\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "/**\n" " * foo_get_bar:\n" " * @foo: some foo\n" @@ -1707,16 +2135,13 @@ msgid "" " *\n" " * Since: 2.6\n" " * Deprecated: 2.12: Use foo_baz_get_bar() instead.\n" -" **/\n" +" */\n" "Bar *\n" "foo_get_bar(Foo *foo)\n" "{\n" "...\n" -"\n" -" " msgstr "" "\n" -"\n" "/**\n" " * foo_get_bar:\n" " * @foo: some foo\n" @@ -1727,19 +2152,60 @@ msgstr "" " *\n" " * Since: 2.6\n" " * Deprecated: 2.12: Use foo_baz_get_bar() instead.\n" -" **/\n" +" */\n" "Bar *\n" "foo_get_bar(Foo *foo)\n" "{\n" "...\n" + +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1172 C/index.docbook:1182 +#| msgid "Installation" +msgid "Annotations" +msgstr "Annotations" + +#. (itstool) path: sect2/para +#: C/index.docbook:1174 +msgid "" +"Documentation blocks can contain annotation-tags. These tags will be " +"rendered with tooltips describing their meaning. The tags are used by " +"gobject-introspection to generate language bindings. A detailed list of the " +"supported tags can be found on the wiki." +msgstr "" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1183 +#, no-wrap +msgid "" "\n" -" " +"/**\n" +" * foo_get_bar: (annotation)\n" +" * @foo: (annotation): some foo\n" +" *\n" +" * Retrieves @foo's bar.\n" +" *\n" +" * Returns: (annotation): @foo's bar\n" +" */\n" +"...\n" +"/**\n" +" * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)\n" +" * (and another annotation)\n" +" * @foo: (annotation) (another annotation): some foo\n" +" *\n" +" * Sets bar on @foo.\n" +" */\n" +msgstr "" -#: C/index.docbook:1104(sect2/title) C/index.docbook:1140(example/title) +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1204 C/index.docbook:1233 msgid "Function comment block" msgstr "Bloc de commentaires pour les fonctions" -#: C/index.docbook:1110(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1210 msgid "" "Document whether returned objects, lists, strings, etc, should be freed/" "unrefed/released." @@ -1747,24 +2213,27 @@ msgstr "" "d'indiquer si les objets, listes, chaînes, etc. retournés doivent être freed/" "unfreed/released," -#: C/index.docbook:1116(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1216 msgid "Document whether parameters can be NULL, and what happens if they are." msgstr "" "d'indiquer si les paramètres peuvent être NULL et ce qui se passe dans ce " -"cas," +"cas." -#: C/index.docbook:1121(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1221 msgid "" "Mention interesting pre-conditions and post-conditions where appropriate." msgstr "" -"de mentionner les pré-conditions et post-conditions intéressantes si " -"nécessaire." +"Mentionner les pré-conditions et post-conditions intéressantes si nécessaire." -#: C/index.docbook:1106(sect2/para) C/index.docbook:1203(sect2/para) +#. (itstool) path: sect2/para +#: C/index.docbook:1206 C/index.docbook:1292 msgid "Please remember to: <_:itemizedlist-1/>" msgstr "N'oubliez pas : <_:itemizedlist-1/>" -#: C/index.docbook:1128(sect2/para) +#. (itstool) path: sect2/para +#: C/index.docbook:1228 msgid "" "Gtk-doc assumes all symbols (macros, functions) starting with '_' are " "private. They are treated like static functions." @@ -1772,19 +2241,33 @@ msgstr "" "GTK-Doc considère que tous les symboles (macros, fonctions) commençant par " "« _ » sont privés. Ils sont traités comme des fonctions statiques." -#: C/index.docbook:1133(sect2/para) -msgid "" -"Also, take a look at gobject introspection annotation tags: http://live." -"gnome.org/GObjectIntrospection/Annotations" -msgstr "" -"Jetez un coup d'œil aux étiquettes d'annotation de l'introspection gobject : " -"http://live.gnome.org/GObjectIntrospection/Annotations" - -#: C/index.docbook:1141(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:1234 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "/**\n" +#| " * function_name:\n" +#| " * @par1: description of parameter 1. These can extend over more than\n" +#| " * one line.\n" +#| " * @par2: description of parameter 2\n" +#| " * @...: a %NULL-terminated list of bars\n" +#| " *\n" +#| " * The function description goes here. You can use @par1 to refer to parameters\n" +#| " * so that they are highlighted in the output. You can also use %constant\n" +#| " * for constants, function_name2() for functions and #GtkWidget for links to\n" +#| " * other declarations (which may be documented elsewhere).\n" +#| " *\n" +#| " * Returns: an integer.\n" +#| " *\n" +#| " * Since: 2.2\n" +#| " * Deprecated: 2.18: Use other_function() instead.\n" +#| " */\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "/**\n" " * function_name:\n" " * @par1: description of parameter 1. These can extend over more than\n" @@ -1802,11 +2285,8 @@ msgid "" " * Since: 2.2\n" " * Deprecated: 2.18: Use other_function() instead.\n" " */\n" -"\n" -" " msgstr "" "\n" -"\n" "/**\n" " * function_name:\n" " * @par1: description of parameter 1. These can extend over more than\n" @@ -1824,26 +2304,29 @@ msgstr "" " * Since: 2.2\n" " * Deprecated: 2.18: Use other_function() instead.\n" " */\n" -"\n" -" " -#: C/index.docbook:1164(variablelist/title) +#. (itstool) path: variablelist/title +#: C/index.docbook:1255 msgid "Function tags" msgstr "Étiquettes de fonction" -#: C/index.docbook:1165(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:1256 C/index.docbook:1463 msgid "Returns:" msgstr "« Returns » :" -#: C/index.docbook:1167(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1258 msgid "Paragraph describing the returned result." msgstr "Paragraphe décrivant le résultat retourné." -#: C/index.docbook:1172(varlistentry/term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:1263 msgid "@...:" msgstr "@...:" -#: C/index.docbook:1174(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1265 msgid "" "In case the function has variadic arguments, you should use this tag " "(@Varargs: does also work for historic reasons)." @@ -1852,57 +2335,86 @@ msgstr "" "cette étiquette (@Varargs : peut également être utilisé pour des raisons " "historiques)." -#: C/index.docbook:1184(sect2/title) C/index.docbook:1186(example/title) +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1275 C/index.docbook:1277 msgid "Property comment block" msgstr "Bloc de commentaires pour les propriétés" -#: C/index.docbook:1187(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:1278 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "/**\n" +#| " * SomeWidget:some-property:\n" +#| " *\n" +#| " * Here you can document a property.\n" +#| " */\n" +#| "g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "/**\n" " * SomeWidget:some-property:\n" " *\n" " * Here you can document a property.\n" " */\n" "g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);\n" -"\n" -" " msgstr "" "\n" -"\n" "/**\n" " * SomeWidget:some-property:\n" " *\n" " * Here you can document a property.\n" " */\n" "g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);\n" -"\n" -" " -#: C/index.docbook:1201(sect2/title) C/index.docbook:1220(example/title) +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1290 C/index.docbook:1309 msgid "Signal comment block" msgstr "Bloc de commentaires pour les signaux" -#: C/index.docbook:1207(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1296 msgid "" "Document when the signal is emitted and whether it is emitted before or " "after other signals." msgstr "" -"d'indiquer quand le signal est émis et s'il est émis avant ou après d'autres " -"signaux," +"Documenter lorsque le signal est émis et s'il est émis avant ou après " +"d'autres signaux," -#: C/index.docbook:1213(listitem/para) +#. (itstool) path: listitem/para +#: C/index.docbook:1302 msgid "Document what an application might do in the signal handler." msgstr "" -"d'indiquer ce qu'une application peut faire dans le gestionnaire du signal." +"Documenter ce qu'une application pourrait faire dans le gestionnaire du " +"signal." -#: C/index.docbook:1221(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:1310 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "/**\n" +#| " * FooWidget::foobarized:\n" +#| " * @widget: the widget that received the signal\n" +#| " * @foo: some foo\n" +#| " * @bar: some bar\n" +#| " *\n" +#| " * The ::foobarized signal is emitted each time someone tries to foobarize @widget.\n" +#| " */\n" +#| "foo_signals[FOOBARIZE] =\n" +#| " g_signal_new (\"foobarize\",\n" +#| " ...\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "/**\n" " * FooWidget::foobarized:\n" " * @widget: the widget that received the signal\n" @@ -1914,11 +2426,8 @@ msgid "" "foo_signals[FOOBARIZE] =\n" " g_signal_new (\"foobarize\",\n" " ...\n" -"\n" -" " msgstr "" "\n" -"\n" "/**\n" " * FooWidget::foobarized:\n" " * @widget: the widget that received the signal\n" @@ -1930,18 +2439,36 @@ msgstr "" "foo_signals[FOOBARIZE] =\n" " g_signal_new (\"foobarize\",\n" " ...\n" -"\n" -" " -#: C/index.docbook:1240(sect2/title) C/index.docbook:1241(example/title) +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1327 C/index.docbook:1328 msgid "Struct comment block" msgstr "Bloc de commentaire pour les structures" -#: C/index.docbook:1242(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:1329 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "/**\n" +#| " * FooWidget:\n" +#| " * @bar: some #gboolean\n" +#| " *\n" +#| " * This is the best widget, ever.\n" +#| " */\n" +#| "typedef struct _FooWidget {\n" +#| " /*< private >*/\n" +#| " GtkWidget parent;\n" +#| "\n" +#| " /*< public >*/\n" +#| " gboolean bar;\n" +#| "} FooWidget;\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "/**\n" " * FooWidget:\n" " * @bar: some #gboolean\n" @@ -1949,17 +2476,12 @@ msgid "" " * This is the best widget, ever.\n" " */\n" "typedef struct _FooWidget {\n" -" /*< private >*/\n" -" GtkWidget parent;\n" +" GtkWidget parent_instance;\n" "\n" -" /*< public >*/\n" " gboolean bar;\n" "} FooWidget;\n" -"\n" -" " msgstr "" "\n" -"\n" "/**\n" " * FooWidget:\n" " * @bar: some #gboolean\n" @@ -1967,16 +2489,13 @@ msgstr "" " * This is the best widget, ever.\n" " */\n" "typedef struct _FooWidget {\n" -" /*< private >*/\n" -" GtkWidget parent;\n" +" GtkWidget parent_instance;\n" "\n" -" /*< public >*/\n" " gboolean bar;\n" "} FooWidget;\n" -"\n" -" " -#: C/index.docbook:1261(sect2/para) +#. (itstool) path: sect2/para +#: C/index.docbook:1344 msgid "" "Use /*< private >*/ before the private struct fields you " "want to hide. Use /*< public >*/ for the reverse " @@ -1986,7 +2505,16 @@ msgstr "" "privées que vous voulez cacher. Utilisez /*< public >*/ " "dans le cas contraire." -#: C/index.docbook:1267(sect2/para) +#. (itstool) path: sect2/para +#: C/index.docbook:1350 +msgid "" +"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" " +"it will be considered private automatically and doesn't need to be mentioned " +"in the comment block." +msgstr "" + +#. (itstool) path: sect2/para +#: C/index.docbook:1356 msgid "" "Struct comment blocks can also be used for GObjects and GObjectClasses. It " "is usually a good idea to add a comment block for a class, if it has " @@ -2005,52 +2533,67 @@ msgstr "" "possède des champs publics. Le désavantage ici étant que cela crée deux " "entrées d'index pour le même nom (la structure et la section)." -#: C/index.docbook:1279(sect2/title) C/index.docbook:1280(example/title) +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1368 C/index.docbook:1369 msgid "Enum comment block" msgstr "Bloc de commentaire pour les énumérations" -#: C/index.docbook:1281(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:1370 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "/**\n" +#| " * Something:\n" +#| " * @SOMETHING_FOO: something foo\n" +#| " * @SOMETHING_BAR: something bar\n" +#| " *\n" +#| " * Enum values used for the thing, to specify the thing.\n" +#| " *\n" +#| " **/\n" +#| "typedef enum {\n" +#| " SOMETHING_FOO,\n" +#| " SOMETHING_BAR,\n" +#| " /*< private >*/\n" +#| " SOMETHING_COUNT\n" +#| "} Something;\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "/**\n" " * Something:\n" " * @SOMETHING_FOO: something foo\n" " * @SOMETHING_BAR: something bar\n" " *\n" " * Enum values used for the thing, to specify the thing.\n" -" *\n" -" **/\n" +" */\n" "typedef enum {\n" " SOMETHING_FOO,\n" " SOMETHING_BAR,\n" " /*< private >*/\n" " SOMETHING_COUNT\n" "} Something;\n" -"\n" -" " msgstr "" "\n" -"\n" "/**\n" " * Something:\n" " * @SOMETHING_FOO: something foo\n" " * @SOMETHING_BAR: something bar\n" " *\n" " * Enum values used for the thing, to specify the thing.\n" -" *\n" -" **/\n" +" */\n" "typedef enum {\n" " SOMETHING_FOO,\n" " SOMETHING_BAR,\n" " /*< private >*/\n" " SOMETHING_COUNT\n" "} Something;\n" -"\n" -" " -#: C/index.docbook:1301(sect2/para) +#. (itstool) path: sect2/para +#: C/index.docbook:1387 msgid "" "Use /*< private >*/ before the private enum values you " "want to hide. Use /*< public >*/ for the reverse " @@ -2060,33 +2603,161 @@ msgstr "" "privées que vous voulez cacher. Utilisez /*< public >*/ " "dans le cas contraire." -#: C/index.docbook:1311(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:1398 +#, fuzzy +#| msgid "Setting up a skeleton documentation" +msgid "Inline program documentation" +msgstr "Mise en place du squelette de documentation" + +#. (itstool) path: sect1/para +#: C/index.docbook:1399 +msgid "" +"You can document programs and their commandline interface using inline " +"documentation." +msgstr "" + +#. (itstool) path: variablelist/title +#: C/index.docbook:1405 +msgid "Tags" +msgstr "" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1407 +msgid "PROGRAM" +msgstr "" + +#. (itstool) path: listitem/para +#: C/index.docbook:1410 +msgid "Defines the start of a program documentation." +msgstr "" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1417 +#| msgid "@short_description" +msgid "@short_description:" +msgstr "@short_description:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1419 +msgid "Defines a short description of the program. (Optional)" +msgstr "" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1426 +msgid "@synopsis:" +msgstr "" + +#. (itstool) path: listitem/para +#: C/index.docbook:1428 +msgid "" +"Defines the arguments, or list of arguments that the program can take. " +"(Optional)" +msgstr "" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1436 +#| msgid "@see_also" +msgid "@see_also:" +msgstr "@see_also:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1438 +msgid "See Also manual page section. (Optional)" +msgstr "" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1445 +msgid "@arg:" +msgstr "" + +#. (itstool) path: listitem/para +#: C/index.docbook:1447 +msgid "Argument(s) passed to the program and their description. (Optional)" +msgstr "" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1454 +#| msgid "@short_description" +msgid "Description:" +msgstr "Description:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1456 +msgid "A longer description of the program." +msgstr "" + +#. (itstool) path: listitem/para +#: C/index.docbook:1465 +msgid "Specificy what value(s) the program returns. (Optional)" +msgstr "" + +#. (itstool) path: sect2/title +#: C/index.docbook:1474 +msgid "Example of program documentation." +msgstr "" + +#. (itstool) path: example/title +#: C/index.docbook:1475 +msgid "Program documentation block" +msgstr "Bloc de documentation programme" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1476 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * PROGRAM:test-program\n" +" * @short_description: A test program\n" +" * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*\n" +" * @see_also: test(1)\n" +" * @--arg1 *arg*: set arg1 to *arg*\n" +" * @--arg2 *arg*: set arg2 to *arg*\n" +" * @-v, --version: Print the version number\n" +" * @-h, --help: Print the help message\n" +" *\n" +" * Long description of program.\n" +" *\n" +" * Returns: Zero on success, non-zero on failure\n" +" */\n" +"int main(int argc, char *argv[])\n" +"{\n" +"\treturn 0;\n" +"}\n" +msgstr "" + +#. (itstool) path: sect1/title +#: C/index.docbook:1502 msgid "Useful DocBook tags" msgstr "Balises DocBook utiles" -#: C/index.docbook:1313(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1504 msgid "" "Here are some DocBook tags which are most useful when documenting the code." msgstr "" "Voici quelques balises DocBook très utiles pendant la conception de la " "documentation d'un code." -#: C/index.docbook:1322(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1513 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n" -"\n" -" " msgstr "" "\n" -"\n" "<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n" -"\n" -" " -#: C/index.docbook:1318(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1509 msgid "" "To link to another section in the GTK docs: <_:informalexample-1/> The " "linkend is the SGML/XML id on the top item of the page you want to link to. " @@ -2103,22 +2774,24 @@ msgstr "" "caractères de soulignement sont convertis en « - » pour être conforme au " "SGML/XML." -#: C/index.docbook:1337(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1526 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<function>...</function>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<function>...</function>\n" -"\n" -" " msgstr "" "\n" -"\n" "<function>...</function>\n" -"\n" -" " -#: C/index.docbook:1334(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1523 msgid "" "To refer to an external function, e.g. a standard C function: <_:" "informalexample-1/>" @@ -2126,55 +2799,67 @@ msgstr "" "Pour faire référence à une fonction externe comme, par exemple, à une " "fonction C standard : <_:informalexample-1/>" -#: C/index.docbook:1348(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1535 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<example>\n" +#| " <title>Using a GHashTable.</title>\n" +#| " <programlisting>\n" +#| " ...\n" +#| " </programlisting>\n" +#| "</example>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<example>\n" " <title>Using a GHashTable.</title>\n" " <programlisting>\n" " ...\n" " </programlisting>\n" "</example>\n" -"\n" -" " msgstr "" "\n" -"\n" "<example>\n" " <title>Using a GHashTable.</title>\n" " <programlisting>\n" " ...\n" " </programlisting>\n" "</example>\n" -"\n" -" " -#: C/index.docbook:1361(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1546 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<informalexample>\n" +#| " <programlisting>\n" +#| " ...\n" +#| " </programlisting>\n" +#| "</informalexample>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<informalexample>\n" " <programlisting>\n" " ...\n" " </programlisting>\n" "</informalexample>\n" -"\n" -" " msgstr "" "\n" -"\n" "<informalexample>\n" " <programlisting>\n" " ...\n" " </programlisting>\n" "</informalexample>\n" -"\n" -" " -#: C/index.docbook:1345(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1532 msgid "" "To include example code: <_:informalexample-1/> or possibly this, for very " "short code fragments which don't need a title: <_:informalexample-2/> For " @@ -2185,11 +2870,28 @@ msgstr "" "informalexample-2/> Pour ces derniers, GTK-Doc prend également en charge une " "abréviation : |[ ... ]|" -#: C/index.docbook:1382(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1565 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<itemizedlist>\n" +#| " <listitem>\n" +#| " <para>\n" +#| " ...\n" +#| " </para>\n" +#| " </listitem>\n" +#| " <listitem>\n" +#| " <para>\n" +#| " ...\n" +#| " </para>\n" +#| " </listitem>\n" +#| "</itemizedlist>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<itemizedlist>\n" " <listitem>\n" " <para>\n" @@ -2202,11 +2904,8 @@ msgid "" " </para>\n" " </listitem>\n" "</itemizedlist>\n" -"\n" -" " msgstr "" "\n" -"\n" "<itemizedlist>\n" " <listitem>\n" " <para>\n" @@ -2219,76 +2918,85 @@ msgstr "" " </para>\n" " </listitem>\n" "</itemizedlist>\n" -"\n" -" " -#: C/index.docbook:1379(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1562 msgid "To include bulleted lists: <_:informalexample-1/>" msgstr "Pour ajouter une liste à puces : <_:informalexample-1/>" -#: C/index.docbook:1404(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1585 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<note>\n" +#| " <para>\n" +#| " Make sure you free the data after use.\n" +#| " </para>\n" +#| "</note>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<note>\n" " <para>\n" " Make sure you free the data after use.\n" " </para>\n" "</note>\n" -"\n" -" " msgstr "" "\n" -"\n" "<note>\n" " <para>\n" " Make sure you free the data after use.\n" " </para>\n" "</note>\n" -"\n" -" " -#: C/index.docbook:1401(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1582 msgid "" "To include a note which stands out from the text: <_:informalexample-1/>" msgstr "Pour ajouter une note de bas de page : <_:informalexample-1/>" -#: C/index.docbook:1419(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1598 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<type>unsigned char</type>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<type>unsigned char</type>\n" -"\n" -" " msgstr "" "\n" -"\n" "<type>unsigned char</type>\n" -"\n" -" " -#: C/index.docbook:1416(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1595 msgid "To refer to a type: <_:informalexample-1/>" msgstr "Pour se référer à un type : <_:informalexample-1/>" -#: C/index.docbook:1430(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1607 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<structname>XFontStruct</structname>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<structname>XFontStruct</structname>\n" -"\n" -" " msgstr "" "\n" -"\n" "<structname>XFontStruct</structname>\n" -"\n" -" " -#: C/index.docbook:1427(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1604 msgid "" "To refer to an external structure (not one described in the GTK docs): <_:" "informalexample-1/>" @@ -2296,41 +3004,45 @@ msgstr "" "Pour se référer à une structure externe (non décrite dans la documentation " "GTK) : <_:informalexample-1/>" -#: C/index.docbook:1441(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1616 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<structfield>len</structfield>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<structfield>len</structfield>\n" -"\n" -" " msgstr "" "\n" -"\n" "<structfield>len</structfield>\n" -"\n" -" " -#: C/index.docbook:1438(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1613 msgid "To refer to a field of a structure: <_:informalexample-1/>" msgstr "Pour se référer à un champ d'une structure : <_:informalexample-1/>" -#: C/index.docbook:1452(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1625 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<classname>GtkWidget</classname>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<classname>GtkWidget</classname>\n" -"\n" -" " msgstr "" "\n" -"\n" "<classname>GtkWidget</classname>\n" -"\n" -" " -#: C/index.docbook:1449(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1622 msgid "" "To refer to a class name, we could possibly use: <_:informalexample-1/> but " "you'll probably be using #GtkWidget instead (to automatically create a link " @@ -2342,68 +3054,76 @@ msgstr "" "(pour créer automatiquement un lien vers la page GtkWidget - consultez les raccourcis)." -#: C/index.docbook:1465(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1636 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<emphasis>This is important</emphasis>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<emphasis>This is important</emphasis>\n" -"\n" -" " msgstr "" "\n" -"\n" "<emphasis>This is important</emphasis>\n" -"\n" -" " -#: C/index.docbook:1462(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1633 msgid "To emphasize text: <_:informalexample-1/>" msgstr "Pour mettre en évidence un texte : <_:informalexample-1/>" -#: C/index.docbook:1476(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1645 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<filename>/home/user/documents</filename>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<filename>/home/user/documents</filename>\n" -"\n" -" " msgstr "" "\n" -"\n" "<filename>/home/user/documents</filename>\n" -"\n" -" " -#: C/index.docbook:1473(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1642 msgid "For filenames use: <_:informalexample-1/>" msgstr "Pour les noms de fichiers : <_:informalexample-1/>" -#: C/index.docbook:1487(informalexample/programlisting) +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1654 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" -"\n" -" " msgstr "" "\n" -"\n" "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" -"\n" -" " -#: C/index.docbook:1484(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1651 msgid "To refer to keys use: <_:informalexample-1/>" msgstr "Pour se référer à des touches : <_:informalexample-1/>" -#: C/index.docbook:1499(chapter/title) +#. (itstool) path: chapter/title +#: C/index.docbook:1664 msgid "Filling the extra files" msgstr "Remplissage des fichiers supplémentaires" -#: C/index.docbook:1501(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:1666 msgid "" "There are a couple of extra files, that need to be maintained along with the " "inline source code comments: <package>.types, " @@ -2415,17 +3135,26 @@ msgstr "" "package>.types, <package>-docs.xml " "(anciennement .sgml), <package>-sections.txt." -#: C/index.docbook:1510(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:1675 msgid "Editing the types file" -msgstr "Édition du fichier « types »" - -#: C/index.docbook:1512(sect1/para) -msgid "" -"If your library or application includes GtkObjects/GObjects, you want their " -"signals, arguments/parameters and position in the hierarchy to be shown in " -"the documentation. All you need to do, is to list the " -"xxx_get_type functions together with their include " -"inside the <package>.types file." +msgstr "Édition des fichiers types" + +#. (itstool) path: sect1/para +#: C/index.docbook:1677 +#, fuzzy +#| msgid "" +#| "If your library or application includes GtkObjects/GObjects, you want " +#| "their signals, arguments/parameters and position in the hierarchy to be " +#| "shown in the documentation. All you need to do, is to list the " +#| "xxx_get_type functions together with their include " +#| "inside the <package>.types file." +msgid "" +"If your library or application includes GObjects, you want their signals, " +"arguments/parameters and position in the hierarchy to be shown in the " +"documentation. All you need to do, is to list the xxx_get_type functions together with their include inside the <" +"package>.types file." msgstr "" "Si votre bibliothèque ou application contient des GtkObjects ou GObjects, " "vous voudrez que leurs signaux, arguments/paramètres et position dans la " @@ -2433,36 +3162,44 @@ msgstr "" "lister les fonctions xxx_get_type ainsi que leur " "fichier inclus dans le fichier <package>.types." -#: C/index.docbook:1521(example/title) +#. (itstool) path: example/title +#: C/index.docbook:1686 msgid "Example types file snippet" -msgstr "Extrait d'un exemple de fichier « types »" +msgstr "Extrait d'un exemple de fichiers types" -#: C/index.docbook:1522(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:1687 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "#include <gtk/gtk.h>\n" +#| "\n" +#| "gtk_accel_label_get_type\n" +#| "gtk_adjustment_get_type\n" +#| "gtk_alignment_get_type\n" +#| "gtk_arrow_get_type\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "#include <gtk/gtk.h>\n" "\n" "gtk_accel_label_get_type\n" "gtk_adjustment_get_type\n" "gtk_alignment_get_type\n" "gtk_arrow_get_type\n" -"\n" -" " msgstr "" "\n" -"\n" "#include <gtk/gtk.h>\n" "\n" "gtk_accel_label_get_type\n" "gtk_adjustment_get_type\n" "gtk_alignment_get_type\n" "gtk_arrow_get_type\n" -"\n" -" " -#: C/index.docbook:1535(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1698 msgid "" "Since GTK-Doc 1.8 gtkdoc-scan can generate this " "list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in " @@ -2475,11 +3212,13 @@ msgstr "" "utilisez cette approche vous ne devriez pas distribuer le fichier « types », " "ni l'avoir dans le système de gestion de versions." -#: C/index.docbook:1544(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:1707 msgid "Editing the master document" msgstr "Édition du document maître" -#: C/index.docbook:1546(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1709 msgid "" "GTK-Doc produces documentation in DocBook SGML/XML. When processing the " "inline source comments, the GTK-Doc tools generate one documentation page " @@ -2491,14 +3230,23 @@ msgstr "" "génèrent une page de documentation par classe ou par module dans un fichier " "séparé. Le document maître les inclut et les place dans l'ordre." -#: C/index.docbook:1553(sect1/para) -msgid "" -"While GTK-Doc creates a template master document for you, later run will not " -"touch it again. This means that one can freely structure the documentation. " -"That includes grouping pages and adding extra pages. GTK-Doc has now a test " -"suite, where also the master-document is recreated from scratch. Its a good " -"idea to look at this from time to time to see if there are some new goodies " -"introduced there." +#. (itstool) path: sect1/para +#: C/index.docbook:1716 +#, fuzzy +#| msgid "" +#| "While GTK-Doc creates a template master document for you, later run will " +#| "not touch it again. This means that one can freely structure the " +#| "documentation. That includes grouping pages and adding extra pages. GTK-" +#| "Doc has now a test suite, where also the master-document is recreated " +#| "from scratch. Its a good idea to look at this from time to time to see if " +#| "there are some new goodies introduced there." +msgid "" +"While GTK-Doc creates a template master document for you, later runs will " +"not touch it again. This means that one can freely structure the " +"documentation. That includes grouping pages and adding extra pages. GTK-Doc " +"has now a test suite, where also the master-document is recreated from " +"scratch. Its a good idea to look at this from time to time to see if there " +"are some new goodies introduced there." msgstr "" "Une fois que GTK-Doc a créé un prototype de document maître pour vous, il ne " "va plus y toucher par la suite. Vous pouvez ainsi structurer votre " @@ -2508,7 +3256,8 @@ msgstr "" "regarder cela de temps en temps pour voir s'il n'y a pas des nouveautés " "intéressantes." -#: C/index.docbook:1563(tip/para) +#. (itstool) path: tip/para +#: C/index.docbook:1726 msgid "" "Do not create tutorials as extra documents. Just write extra chapters. The " "benefit of directly embedding the tutorial for your library into the API " @@ -2523,7 +3272,8 @@ msgstr "" "plus, il y aura plus de chance que votre tutoriel soit mis à jour en même " "temps que la bibliothèque." -#: C/index.docbook:1572(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1735 msgid "" "So what are the things to change inside the master document? For a start is " "only a little. There are some placeholders (text in square brackets) there " @@ -2533,15 +3283,32 @@ msgstr "" "commencer, très peu de choses. Il n'y a quelques paramètres substituables " "(texte entre crochets) que vous devrez prendre en charge." -#: C/index.docbook:1579(example/title) +#. (itstool) path: example/title +#: C/index.docbook:1742 msgid "Master document header" msgstr "En-tête du document maître" -#: C/index.docbook:1580(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:1743 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "<bookinfo>\n" +#| " <title>MODULENAME Reference Manual</title>\n" +#| " <releaseinfo>\n" +#| " for MODULENAME [VERSION]\n" +#| " The latest version of this documentation can be found on-line at\n" +#| " <ulink role=\"online-location\" url=\"http://[SERVER]/MODULENAME/index.html\">http://[SERVER]/MODULENAME/</ulink>.\n" +#| " </releaseinfo>\n" +#| "</bookinfo>\n" +#| "\n" +#| "<chapter>\n" +#| " <title>[Insert title here]</title>\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "<bookinfo>\n" " <title>MODULENAME Reference Manual</title>\n" " <releaseinfo>\n" @@ -2553,11 +3320,8 @@ msgid "" "\n" "<chapter>\n" " <title>[Insert title here]</title>\n" -"\n" -" " msgstr "" "\n" -"\n" "<bookinfo>\n" " <title>MODULENAME Reference Manual</title>\n" " <releaseinfo>\n" @@ -2569,14 +3333,65 @@ msgstr "" "\n" "<chapter>\n" " <title>[Insert title here]</title>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1759 +msgid "" +"In addition a few option elements are created in commented form. You can " +"review these and enable them as you like." +msgstr "" + +#. (itstool) path: example/title +#: C/index.docbook:1765 +msgid "Optional part in the master document" +msgstr "Partie optionnelle dans le document maître" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1766 +#, no-wrap +msgid "" +"\n" +" <!-- enable this when you use gobject introspection annotations\n" +" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n" +" -->\n" +msgstr "" + +#. (itstool) path: sect1/para +#: C/index.docbook:1774 +msgid "" +"Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind " +"you of newly generated xml files that are not yet included into the doc." +msgstr "" + +#. (itstool) path: example/title +#: C/index.docbook:1782 C/index.docbook:1817 +msgid "Including generated sections" +msgstr "" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1783 +#, no-wrap +msgid "" +"\n" +" <chapter>\n" +" <title>my library</title>\n" +" <xi:include href=\"xml/object.xml\"/>\n" +" ...\n" +msgstr "" "\n" -" " +" <chapter>\n" +" <title>my library</title>\n" +" <xi:include href=\"xml/object.xml\"/>\n" +" ...\n" -#: C/index.docbook:1601(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:1795 msgid "Editing the section file" msgstr "Édition du fichier section" -#: C/index.docbook:1603(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1797 msgid "" "The section file is used to organise the documentation output by GTK-Doc. " "Here one specifies which symbol belongs to which module or class and control " @@ -2586,26 +3401,82 @@ msgstr "" "GTK-Doc. C'est ici qu'il faut indiquer quels symboles sont attachés à quels " "modules ou classes et contrôler la visibilité (« public » ou « private »)." -#: C/index.docbook:1609(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1803 +#, fuzzy +#| msgid "" +#| "The section file is a plain test file with xml like syntax (using tags). " +#| "Blank lines are ignored and lines starting with a '#' are treated as " +#| "comment lines." msgid "" -"The section file is a plain test file with xml like syntax (using tags). " -"Blank lines are ignored and lines starting with a '#' are treated as comment " -"lines." +"The section file is a plain text file with tags delimiting sections. Blank " +"lines are ignored and lines starting with a '#' are treated as comment lines." msgstr "" "Le fichier section est un fichier texte plat, avec une syntaxe type XML " "(utilisant des balises). Les lignes blanches sont ignorées et celles " "commençant par un « # » sont considérées comme des lignes de commentaires." -#: C/index.docbook:1615(sect1/para) +#. (itstool) path: note/para +#: C/index.docbook:1810 +msgid "" +"While the tags make the file look like xml, it is not. Please do not close " +"tags like <SUBSECTION>." +msgstr "" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1818 +#, no-wrap +msgid "" +"\n" +"<INCLUDE>libmeep/meep.h</INCLUDE>\n" +"\n" +"<SECTION>\n" +"<FILE>meepapp</FILE>\n" +"<TITLE>MeepApp</TITLE>\n" +"MeepApp\n" +"<SUBSECTION Standard>\n" +"MEEP_APP\n" +"...\n" +"MeepAppClass\n" +"meep_app_get_type\n" +"</SECTION>\n" +msgstr "" +"\n" +"<INCLUDE>libmeep/meep.h</INCLUDE>\n" +"\n" +"<SECTION>\n" +"<FILE>meepapp</FILE>\n" +"<TITLE>MeepApp</TITLE>\n" +"MeepApp\n" +"<SUBSECTION Standard>\n" +"MEEP_APP\n" +"...\n" +"MeepAppClass\n" +"meep_app_get_type\n" +"</SECTION>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1835 +#, fuzzy +#| msgid "" +#| "The <FILE> ... </FILE> tag is used to specify the file name, " +#| "without any suffix. For example, using '<FILE>gnome-config</" +#| "FILE>' will result in the section declarations being output in the " +#| "template file tmpl/gnome-config.sgml, which will be " +#| "converted into the DocBook SGML/XML file sgml/gnome-config." +#| "sgml or .DocBook XML file xml/gnome-config.xml. (The name of the html file is based on the module name and the " +#| "section title, or for gobjects it is based on the gobjects class name " +#| "converted to lower case)." msgid "" "The <FILE> ... </FILE> tag is used to specify the file name, " "without any suffix. For example, using '<FILE>gnome-config</" "FILE>' will result in the section declarations being output in the " "template file tmpl/gnome-config.sgml, which will be " -"converted into the DocBook SGML/XML file sgml/gnome-config.sgml or .DocBook XML file xml/gnome-config.xml. " -"(The name of the html file is based on the module name and the section " -"title, or for gobjects it is based on the gobjects class name converted to " +"converted into the DocBook XML file xml/gnome-config.sgml or the DocBook XML file xml/gnome-config.xml. " +"(The name of the HTML file is based on the module name and the section " +"title, or for GObjects it is based on the GObjects class name converted to " "lower case)." msgstr "" "La balise <FILE> ... </FILE> est utilisée pour indiquer le nom " @@ -2618,7 +3489,8 @@ msgstr "" "de la section, ou, pour les gobjects, sur le nom de la classe gobjects " "converti en minuscule)." -#: C/index.docbook:1627(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1847 msgid "" "The <TITLE> ... </TITLE> tag is used to specify the title of the " "section. It is only useful before the templates (if used) are initially " @@ -2631,7 +3503,23 @@ msgstr "" "Elle est également obsolète si des commentaires de SECTION sont utilisés " "dans les fichiers sources." -#: C/index.docbook:1634(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:1854 +#, fuzzy +#| msgid "" +#| "You can group items in the section by using the <SUBSECTION> tag. " +#| "Currently it outputs a blank line between subsections in the synopsis " +#| "section. You can also use <SUBSECTION Standard> for standard " +#| "GObject declarations (e.g. the functions like g_object_get_type and " +#| "macros like G_OBJECT(), G_IS_OBJECT() etc.). Currently these are left out " +#| "of the documentation. You can also use <SUBSECTION Private> for " +#| "private declarations which will not be output (It is a handy way to avoid " +#| "warning messages about unused declarations.). If your library contains " +#| "private types which you don't want to appear in the object hierarchy and " +#| "the list of implemented or required interfaces, add them to a Private " +#| "subsection. Whether you would place GObject and GObjectClass like structs " +#| "in public or Standard section depends if they have public entries " +#| "(variables, vmethods)." msgid "" "You can group items in the section by using the <SUBSECTION> tag. " "Currently it outputs a blank line between subsections in the synopsis " @@ -2639,8 +3527,8 @@ msgid "" "declarations (e.g. the functions like g_object_get_type and macros like " "G_OBJECT(), G_IS_OBJECT() etc.). Currently these are left out of the " "documentation. You can also use <SUBSECTION Private> for private " -"declarations which will not be output (It is a handy way to avoid warning " -"messages about unused declarations.). If your library contains private types " +"declarations which will not be output (it is a handy way to avoid warning " +"messages about unused declarations). If your library contains private types " "which you don't want to appear in the object hierarchy and the list of " "implemented or required interfaces, add them to a Private subsection. " "Whether you would place GObject and GObjectClass like structs in public or " @@ -2650,19 +3538,20 @@ msgstr "" "<SUBSECTION>. Actuellement, une ligne blanche est ajoutée entre les " "sous-sections dans la section résumé. Vous pouvez également utiliser <" "SUBSECTION Standard> pour les déclarations GObject standards (par " -"exemple, les fonctions comme g_object_get_type et les macros comme G_OBJECT" -"(), G_IS_OBJECT(), etc.). Actuellement, elles ne sont pas intégrées dans la " -"documentation. Vous pouvez utiliser <SUBSECTION Private> pour les " -"déclarations privées qui ne seront pas affichées (c'est un moyen pratique " -"d'éviter les messages d'avertissement sur les déclarations inutilisées). Si " -"votre bibliothèque contient des types privés que vous ne souhaitez pas voir " -"apparaître dans la hiérarchie des objets et dans la liste des interfaces " -"implémentées ou nécessaires, ajoutez-les à une sous-section privée. Le choix " -"de placer des GObject ou GObjectClass comme des structures dans une section " -"standard ou publique dépend de la présence d'éléments publics (variables, " -"vmethods)." - -#: C/index.docbook:1653(sect1/para) +"exemple, les fonctions comme g_object_get_type et les macros comme " +"G_OBJECT(), G_IS_OBJECT(), etc.). Actuellement, elles ne sont pas intégrées " +"dans la documentation. Vous pouvez utiliser <SUBSECTION Private> pour " +"les déclarations privées qui ne seront pas affichées (c'est un moyen " +"pratique d'éviter les messages d'avertissement sur les déclarations " +"inutilisées). Si votre bibliothèque contient des types privés que vous ne " +"souhaitez pas voir apparaître dans la hiérarchie des objets et dans la liste " +"des interfaces implémentées ou nécessaires, ajoutez-les à une sous-section " +"privée. Le choix de placer des GObject ou GObjectClass comme des structures " +"dans une section standard ou publique dépend de la présence d'éléments " +"publics (variables, vmethods)." + +#. (itstool) path: sect1/para +#: C/index.docbook:1873 msgid "" "You can also use <INCLUDE> ... </INCLUDE> to specify the " "#include files which are shown in the synopsis sections. It contains a comma-" @@ -2677,11 +3566,13 @@ msgstr "" "s'appliquent à toutes les sections jusqu'à la fin du fichier. Si vous les " "placez dans une section, elles s'appliquent seulement à cette section." -#: C/index.docbook:1667(chapter/title) +#. (itstool) path: chapter/title +#: C/index.docbook:1887 msgid "Controlling the result" msgstr "Contrôle du résultat" -#: C/index.docbook:1669(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:1889 msgid "" "A GTK-Doc run generates report files inside the documentation directory. The " "generated files are named: <package>-undocumented.txt. Tous ces fichiers texte peuvent être lus et post-traités " "facilement." -#: C/index.docbook:1678(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:1898 msgid "" "The <package>-undocumented.txt file starts with " "the documentation coverage summary. Below are two sections divided by blank " @@ -2711,7 +3603,8 @@ msgstr "" "documentations de sections. Les éléments incomplets sont ceux qui possèdent " "une documentation mais auxquels, par exemple, un paramètre a été ajouté." -#: C/index.docbook:1687(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:1907 msgid "" "The <package>-undeclared.txt file lists symbols " "given in the <package>-sections.txt but not found " @@ -2722,7 +3615,8 @@ msgstr "" "filename> mais non trouvés dans les fichiers sources. Vérifiez s'ils n'ont " "pas été supprimés ou mal orthographiés." -#: C/index.docbook:1694(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:1914 msgid "" "The <package>-unused.txt file lists symbol names, " "where the GTK-Doc scanner has found documentation, but does not know where " @@ -2734,7 +3628,8 @@ msgstr "" "mais ne sait pas où la placer. Cela signifie que le symbole n'a pas encore " "été ajouté au fichier <package>-sections.txt." -#: C/index.docbook:1702(tip/para) +#. (itstool) path: tip/para +#: C/index.docbook:1922 msgid "" "Enable or add the line in Makefile." "am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during " @@ -2745,14 +3640,23 @@ msgstr "" "1.9, des contrôles de validité seront lancés pendant l'exécution de " "make check." -#: C/index.docbook:1709(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:1929 +#, fuzzy +#| msgid "" +#| "One can also look at the files produced by the source code scanner: " +#| "<package>-decl-list.txt and <" +#| "package>-decl.txt. The first one can be compared with the " +#| "section file if that is manually maintained. The second lists all " +#| "declarations from the headers If a symbol is missing one could check if " +#| "this file contains it." msgid "" "One can also look at the files produced by the source code scanner: " "<package>-decl-list.txt and <" "package>-decl.txt. The first one can be compared with the " "section file if that is manually maintained. The second lists all " -"declarations from the headers If a symbol is missing one could check if this " -"file contains it." +"declarations from the headers. If a symbol is missing one could check if " +"this file contains it." msgstr "" "Vous pouvez également regarder les fichiers produits par le scanneur de code " "source : <package>-decl-list.txt et <" @@ -2761,16 +3665,28 @@ msgstr "" "déclarations contenues dans les fichiers en-tête. Si un symbole est " "manquant, il faut vérifier si ce fichier le contient." -#: C/index.docbook:1718(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:1938 +#, fuzzy +#| msgid "" +#| "If the project is GObject based, one can also look into the files " +#| "produced by the object scanner: <package>.args.txt, <package>.hierarchy.txt, " +#| "<package>.interfaces.txt, <" +#| "package>.prerequisites.txt and <package>." +#| "signals.txt. If there are missing symbols in any of those, one " +#| "can ask gtkdoc to keep the intermediate scanner file for further " +#| "analysis, but running it as GTK_DOC_KEEP_INTERMEDIATE=1 make." msgid "" "If the project is GObject based, one can also look into the files produced " "by the object scanner: <package>.args.txt, " "<package>.hierarchy.txt, <" "package>.interfaces.txt, <package>." "prerequisites.txt and <package>.signals.txt. If there are missing symbols in any of those, one can ask gtkdoc " -"to keep the intermediate scanner file for further analysis, but running it " -"as GTK_DOC_KEEP_INTERMEDIATE=1 make." +"filename>. If there are missing symbols in any of those, one can ask GTK-Doc " +"to keep the intermediate scanner file for further analysis, by running it as " +"GTK_DOC_KEEP_INTERMEDIATE=1 make." msgstr "" "Si le projet est basé sur GObject, il est possible de regarder dans les " "fichiersgénérés par le scanneur d'objet : <package>.args." @@ -2782,11 +3698,201 @@ msgstr "" "intermédiaire pour en faire une analyse ultérieure mais en le lançant comme " "GTK_DOC_KEEP_INTERMEDIATE=1 make." -#: C/index.docbook:1733(chapter/title) +#. (itstool) path: chapter/title +#: C/index.docbook:1953 +msgid "Modernizing the documentation" +msgstr "Modernisation de la documentation" + +#. (itstool) path: chapter/para +#: C/index.docbook:1955 +msgid "" +"GTK-Doc has been around for quite some time. In this section we list new " +"features together with the version since when it is available." +msgstr "" + +#. (itstool) path: sect1/title +#: C/index.docbook:1961 +msgid "GTK-Doc 1.9" +msgstr "Manuel de GTK-Doc 1.9" + +#. (itstool) path: sect1/para +#: C/index.docbook:1963 +#, fuzzy +#| msgid "" +#| "Is the new page xi:included from <package>-docs.{xml,sgml}" +#| "." +msgid "" +"When using xml instead of sgml, one can actually name the master document " +"<package>-docs.xml." +msgstr "" +"Est-ce que la nouvelle page est xi:included à partir de <" +"module>-docs.{xml,sgml}." + +#. (itstool) path: sect1/para +#: C/index.docbook:1968 +msgid "" +"This version supports in " +"Makefile.am. When this is enabled, the <" +"package>-sections.txt is autogenerated and can be removed from " +"the vcs. This only works nicely for projects that have a very regular " +"structure (e.g. each .{c,h} pair will create new section). If one organize a " +"project close to that updating a manually maintained section file can be as " +"simple as running meld <package>-decl-list.txt <package>-" +"sections.txt." +msgstr "" + +#. (itstool) path: sect1/para +#: C/index.docbook:1979 +msgid "" +"Version 1.8 already introduced the syntax for documenting sections in the " +"sources instead of the separate files under tmpl. This version adds options to switch the whole doc module " +"to not use the extra tmpl build step at all, by using in configure.ac. If you don't have a " +"tmpl checked into your source " +"control system and haven't yet switched, just add the flag to " +"configure.ac and you are done." +msgstr "" + +#. (itstool) path: sect1/title +#: C/index.docbook:1991 +msgid "GTK-Doc 1.10" +msgstr "Manuel de GTK-Doc 1.10" + +#. (itstool) path: sect1/para +#: C/index.docbook:1993 +msgid "" +"This version supports in " +"Makefile.am. When this is enabled, the <" +"package>.types is autogenerated and can be removed from the " +"vcs. When using this feature it is important to also setup the " +"IGNORE_HFILES in Makefile.am for " +"code that is build conditionally." +msgstr "" + +#. (itstool) path: sect1/title +#: C/index.docbook:2004 +msgid "GTK-Doc 1.16" +msgstr "Manuel de GTK-Doc 1.16" + +#. (itstool) path: example/title +#: C/index.docbook:2010 +msgid "Enable gtkdoc-check" +msgstr "" + +#. (itstool) path: example/programlisting +#: C/index.docbook:2011 +#, no-wrap +msgid "" +"\n" +"if ENABLE_GTK_DOC\n" +"TESTS_ENVIRONMENT = \\\n" +" DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \\\n" +" SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)\n" +"TESTS = $(GTKDOC_CHECK)\n" +"endif\n" +msgstr "" +"\n" +"if ENABLE_GTK_DOC\n" +"TESTS_ENVIRONMENT = \\\n" +" DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \\\n" +" SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)\n" +"TESTS = $(GTKDOC_CHECK)\n" +"endif\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:2006 +msgid "" +"This version includes a new tool called gtkdoc-check. This tool can run a " +"set of sanity checks on your documentation. It is enabled by adding these " +"lines to the end of Makefile.am. <_:example-1/>" +msgstr "" + +#. (itstool) path: sect1/title +#: C/index.docbook:2024 +msgid "GTK-Doc 1.20" +msgstr "Manuel de GTK-Doc 1.20" + +#. (itstool) path: sect1/para +#: C/index.docbook:2026 +msgid "" +"Version 1.18 brought some initial markdown support. Using markdown in doc " +"comments is less intrusive than writing docbook xml. This version improves a " +"lot on this and add a lot more styles. The section that explains the comment syntax has all the details." +msgstr "" + +#. (itstool) path: sect1/title +#: C/index.docbook:2036 +msgid "GTK-Doc 1.25" +msgstr "Manuel de GTK-Doc 1.25" + +#. (itstool) path: example/title +#: C/index.docbook:2046 +msgid "Use pre-generated entities" +msgstr "" + +#. (itstool) path: example/programlisting +#: C/index.docbook:2047 +#, no-wrap +msgid "" +"\n" +"<?xml version=\"1.0\"?>\n" +"<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"\n" +" \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"\n" +"[\n" +" <!ENTITY % local.common.attrib \"xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'\">\n" +" <!ENTITY % gtkdocentities SYSTEM \"xml/gtkdocentities.ent\">\n" +" %gtkdocentities;\n" +"]>\n" +"<book id=\"index\" xmlns:xi=\"http://www.w3.org/2003/XInclude\">\n" +" <bookinfo>\n" +" <title>&package_name; Reference Manual</title>\n" +" <releaseinfo>\n" +" for &package_string;.\n" +" The latest version of this documentation can be found on-line at\n" +" <ulink role=\"online-location\" url=\"http://[SERVER]/&package_name;/index.html\">http://[SERVER]/&package_name;/</ulink>.\n" +" </releaseinfo>\n" +" </bookinfo>\n" +msgstr "" +"\n" +"<?xml version=\"1.0\"?>\n" +"<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"\n" +" \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"\n" +"[\n" +" <!ENTITY % local.common.attrib \"xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'\">\n" +" <!ENTITY % gtkdocentities SYSTEM \"xml/gtkdocentities.ent\">\n" +" %gtkdocentities;\n" +"]>\n" +"<book id=\"index\" xmlns:xi=\"http://www.w3.org/2003/XInclude\">\n" +" <bookinfo>\n" +" <title>&package_name; Reference Manual</title>\n" +" <releaseinfo>\n" +" for &package_string;.\n" +" The latest version of this documentation can be found on-line at\n" +" <ulink role=\"online-location\" url=\"http://[SERVER]/&package_name;/index.html\">http://[SERVER]/&package_name;/</ulink>.\n" +" </releaseinfo>\n" +" </bookinfo>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:2038 +msgid "" +"The makefiles shipped with this version generate an entity file at " +"xml/gtkdocentities.ent, containing entities for e.g. " +"package_name and package_version. You can use this e.g. in the main xml file " +"to avoid hardcoding the version number. Below is an example that shows how " +"the entity file is included and how the entities are used. The entities can " +"also be used in all generated files, GTK-Doc will use the same xml header in " +"generated xml files. <_:example-1/>" +msgstr "" + +#. (itstool) path: chapter/title +#: C/index.docbook:2072 msgid "Documenting other interfaces" msgstr "Documentation d'autres interfaces" -#: C/index.docbook:1735(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:2074 msgid "" "So far we have been using GTK-Doc to document the API of code. The next " "sections contain suggestions how the tools can be used to document other " @@ -2796,11 +3902,13 @@ msgstr "" "sections qui suivent contiennent des suggestions sur la manière d'utiliser " "les outils pour documenter aussi d'autres interfaces." -#: C/index.docbook:1742(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:2081 msgid "Command line options and man pages" msgstr "Options de ligne de commande et pages de manuel" -#: C/index.docbook:1744(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:2083 msgid "" "As one can generate man pages for a docbook refentry as well, it sounds like " "a good idea to use it for that purpose. This way the interface is part of " @@ -2811,11 +3919,13 @@ msgstr "" "Ainsi, l'interface fait partie de la référence et l'on obtient en cadeau la " "page de manuel." -#: C/index.docbook:1751(sect2/title) +#. (itstool) path: sect2/title +#: C/index.docbook:2090 msgid "Document the tool" msgstr "Documentation de l'outil" -#: C/index.docbook:1753(sect2/para) +#. (itstool) path: sect2/para +#: C/index.docbook:2092 msgid "" "Create one refentry file per tool. Following our example we would call it meep/" @@ -2829,19 +3939,33 @@ msgstr "" "balises XML pouvant être utilisées, on peut observer le fichier généré dans " "le sous-répertoire xml ou des exemples comme dans glib." -#: C/index.docbook:1763(sect2/title) +#. (itstool) path: sect2/title +#: C/index.docbook:2102 msgid "Adding the extra configure check" msgstr "Ajout de contrôles « configure » supplémentaires" -#: C/index.docbook:1766(example/title) C/index.docbook:1786(example/title) +#. (itstool) path: example/title +#: C/index.docbook:2105 C/index.docbook:2123 msgid "Extra configure checks" msgstr "Contrôles « configure » supplémentaires" -#: C/index.docbook:1767(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:2106 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "AC_ARG_ENABLE(man,\n" +#| " [AC_HELP_STRING([--enable-man],\n" +#| " [regenerate man pages from Docbook [default=no]])],enable_man=yes,\n" +#| " enable_man=no)\n" +#| "\n" +#| "AC_PATH_PROG([XSLTPROC], [xsltproc])\n" +#| "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "AC_ARG_ENABLE(man,\n" " [AC_HELP_STRING([--enable-man],\n" " [regenerate man pages from Docbook [default=no]])],enable_man=yes,\n" @@ -2849,11 +3973,8 @@ msgid "" "\n" "AC_PATH_PROG([XSLTPROC], [xsltproc])\n" "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" -"\n" -" " msgstr "" "\n" -"\n" "AC_ARG_ENABLE(man,\n" " [AC_HELP_STRING([--enable-man],\n" " [regenerate man pages from Docbook [default=no]])],enable_man=yes,\n" @@ -2861,18 +3982,36 @@ msgstr "" "\n" "AC_PATH_PROG([XSLTPROC], [xsltproc])\n" "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" -"\n" -" " -#: C/index.docbook:1783(sect2/title) +#. (itstool) path: sect2/title +#: C/index.docbook:2120 msgid "Adding the extra makefile rules" msgstr "Ajout de règles « makefile » supplémentaires" -#: C/index.docbook:1787(example/programlisting) +#. (itstool) path: example/programlisting +#: C/index.docbook:2124 #, no-wrap +#| msgid "" +#| "\n" +#| "\n" +#| "man_MANS = \\\n" +#| " meeper.1\n" +#| "\n" +#| "if ENABLE_GTK_DOC\n" +#| "if ENABLE_MAN\n" +#| "\n" +#| "%.1 : %.xml\n" +#| " @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<\n" +#| "\n" +#| "endif\n" +#| "endif\n" +#| "\n" +#| "BUILT_EXTRA_DIST = $(man_MANS)\n" +#| "EXTRA_DIST += meep.xml\n" +#| "\n" +#| " " msgid "" "\n" -"\n" "man_MANS = \\\n" " meeper.1\n" "\n" @@ -2887,11 +4026,8 @@ msgid "" "\n" "BUILT_EXTRA_DIST = $(man_MANS)\n" "EXTRA_DIST += meep.xml\n" -"\n" -" " msgstr "" "\n" -"\n" "man_MANS = \\\n" " meeper.1\n" "\n" @@ -2906,14 +4042,14 @@ msgstr "" "\n" "BUILT_EXTRA_DIST = $(man_MANS)\n" "EXTRA_DIST += meep.xml\n" -"\n" -" " -#: C/index.docbook:1811(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:2146 msgid "DBus interfaces" msgstr "Interfaces DBus" -#: C/index.docbook:1813(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:2148 msgid "" "(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" @@ -2921,23 +4057,28 @@ msgstr "" "(À_CORRIGER : http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, " "http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" -#: C/index.docbook:1822(chapter/title) +#. (itstool) path: chapter/title +#: C/index.docbook:2157 msgid "Frequently asked questions" msgstr "Foire aux questions" -#: C/index.docbook:1826(segmentedlist/segtitle) +#. (itstool) path: segmentedlist/segtitle +#: C/index.docbook:2161 msgid "Question" -msgstr "Question " +msgstr "Question" -#: C/index.docbook:1827(segmentedlist/segtitle) +#. (itstool) path: segmentedlist/segtitle +#: C/index.docbook:2162 msgid "Answer" -msgstr "Réponse " +msgstr "Réponse" -#: C/index.docbook:1829(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2164 msgid "No class hierarchy." msgstr "Pas de hiérarchie de classe." -#: C/index.docbook:1830(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2165 msgid "" "The objects xxx_get_type() function has not been " "entered into the <package>.types file." @@ -2945,11 +4086,13 @@ msgstr "" "Les fonctions objet xxx_get_type() n'ont pas été " "saisies dans le fichier <module>.types." -#: C/index.docbook:1836(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2171 msgid "Still no class hierarchy." msgstr "Toujours pas de hiérarchie de classe." -#: C/index.docbook:1837(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2172 msgid "" "Missing or wrong naming in <package>-sections.txt " "file (see (consultez une explication)." -#: C/index.docbook:1843(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2178 msgid "Damn, I have still no class hierarchy." msgstr "Zut, je n'ai toujours pas de hiérarchie de classe." -#: C/index.docbook:1844(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2179 msgid "" "Is the object name (name of the instance struct, e.g. GtkWidget) part of the normal section (don't put this into Standard or Private " @@ -2973,11 +4118,13 @@ msgstr "" "GtkWidget) fait parti de la section « normal » (ne pas le " "mettre dans les sous-sections « Standard » ou « Private »)." -#: C/index.docbook:1851(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2186 msgid "No symbol index." msgstr "Pas d'index des symboles." -#: C/index.docbook:1852(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2187 msgid "" "Does the <package>-docs.{xml,sgml} contain a " "index that xi:includes the generated index?" @@ -2985,11 +4132,13 @@ msgstr "" "Est-ce que <module>-docs.{xml,sgml} contient un " "index qui « xi:includes » l'index généré ?" -#: C/index.docbook:1858(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2193 msgid "Symbols are not linked to their doc-section." msgstr "Les symboles ne sont pas liés à leur section de documentation." -#: C/index.docbook:1859(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2194 msgid "" "Is the doc-comment using the correct markup (added #,% or ())? Check if the " "gtkdoc-fixxref warns about unresolvable xrefs." @@ -2998,11 +4147,13 @@ msgstr "" "Contrôlez si gtkdoc-fixxref affiche des avertissements à propos de xrefs non " "résolus." -#: C/index.docbook:1865(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2200 msgid "A new class does not appear in the docs." msgstr "Une nouvelle classe n'apparaît pas dans les documents." -#: C/index.docbook:1866(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2201 msgid "" "Is the new page xi:included from <package>-docs.{xml,sgml}." @@ -3010,11 +4161,13 @@ msgstr "" "Est-ce que la nouvelle page est xi:included à partir de <" "module>-docs.{xml,sgml}." -#: C/index.docbook:1872(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2207 msgid "A new symbol does not appear in the docs." msgstr "Un nouveau symbole n'apparaît pas dans les documents." -#: C/index.docbook:1873(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2208 msgid "" "Is the doc-comment properly formatted. Check for spelling mistakes in the " "begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable " @@ -3027,17 +4180,26 @@ msgstr "" "correctement listé dans une section publique de <module>-" "sections.txt." -#: C/index.docbook:1881(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2216 msgid "A type is missing from the class hierarchy." msgstr "Un type est absent dans la hiérarchie de classe." -#: C/index.docbook:1882(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2217 +#, fuzzy +#| msgid "" +#| "If the type is listed in <package>.hierarchy " +#| "but not in xml/tree_index.sgml then double check " +#| "that the type is correctly placed in the <package>-" +#| "sections.txt. If the type instance (e.g. GtkWidget) is not listed or incidentialy makred private it will not be shown." msgid "" "If the type is listed in <package>.hierarchy but " "not in xml/tree_index.sgml then double check that the " "type is correctly placed in the <package>-sections.txt. If the type instance (e.g. GtkWidget) is not listed " -"or incidentialy makred private it will not be shown." +"or incidentally marked private it will not be shown." msgstr "" "Si le type est listé dans <module>.hierarchy mais " "pas dans xml/tree_index.sgml alors contrôlez deux-fois " @@ -3045,11 +4207,13 @@ msgstr "" "txt. Si l'instance du type (par ex. GtkWidget) n'est " "pas listée ou marquée par accident comme privée, elle ne sera pas affichée." -#: C/index.docbook:1891(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2226 msgid "I get foldoc links for all gobject annotations." msgstr "J'obtiens des liens foldoc pour toutes les annotations gobject." -#: C/index.docbook:1892(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2227 msgid "" "Check that xml/annotation-glossary.xml is xi:included " "from <package>-docs.{xml,sgml}." @@ -3057,13 +4221,15 @@ msgstr "" "Vérifiez que xml/annotation-glossary.xml est xi:" "included à partir de <module>-docs.{xml,sgml}." -#: C/index.docbook:1900(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2235 msgid "Parameter described in source code comment block but does not exist" msgstr "" "Un paramètre est décrit dans le bloc de commentaires dans le code source " "mais il n'existe pas." -#: C/index.docbook:1901(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2236 msgid "" "Check if the prototype in the header has different parameter names as in the " "source." @@ -3071,19 +4237,22 @@ msgstr "" "Vérifiez si le prototype dans le fichier d'en-tête possède des noms de " "paramètres différents de ceux du fichier source." -#: C/index.docbook:1906(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2241 msgid "multiple \"IDs\" for constraint linkend: XYZ" msgstr "« ID » multiples pour le linkend: XYZ contraint" -#: C/index.docbook:1907(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2242 msgid "" "Symbol XYZ appears twice in <package>-sections.txt file." msgstr "" -"Le symbole XYZ apparaît en double dans le fichier <module>-" +"Le symbole XYZ apparaît en double dans le fichier <package>-" "sections.txt." -#: C/index.docbook:1910(seglistitem/seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2245 msgid "" "Element typename in namespace '' encountered in para, but no template " "matches." @@ -3091,38 +4260,47 @@ msgstr "" "Élément typename dans l'espace de nom '' rencontré dans para mais aucun " "prototype ne correspond." -#: C/index.docbook:1917(chapter/title) +#. (itstool) path: chapter/title +#: C/index.docbook:2252 msgid "Tools related to gtk-doc" msgstr "Outils liés à gtk-doc" -#: C/index.docbook:1919(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:2254 msgid "" "GtkDocPlugin - a Trac " -"GTK-Doc integration plugin, that adds api docs to a trac site and " +"GTK-Doc integration plugin, that adds API docs to a trac site and " "integrates with the trac search." msgstr "" "GtkDocPlugin - un greffon d'intégration à Trac, qui ajoute la documentation d'API à un " -"site Trac et s'intègre à la recherche Trac." +"wiki/GtkDocPlugin\">Trac GTK-Doc, qui ajoute la documentation d'API " +"à un site Trac et s'intègre à la recherche Trac." -#: C/index.docbook:1924(chapter/para) +#. (itstool) path: chapter/para +#: C/index.docbook:2259 +#, fuzzy +#| msgid "" +#| "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " +#| "tags in the api to determine the minimum required version." msgid "" "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " -"tags in the api to determine the minimum required version." +"tags in the API to determine the minimum required version." msgstr "" "Gtkdoc-depscan - un outil (intégré à gtk-doc) qui vérifie les API utilisées " "pour déterminer la version minimale requise." -#: C/index.docbook:12(appendixinfo/releaseinfo) -#: C/fdl-appendix.xml:12(appendixinfo/releaseinfo) +#. (itstool) path: appendixinfo/releaseinfo +#: C/index.docbook:12 C/fdl-appendix.xml:12 msgid "Version 1.1, March 2000" msgstr "Version 1.1, mars 2000" -#: C/index.docbook:15(appendixinfo/copyright) +#. (itstool) path: appendixinfo/copyright +#: C/index.docbook:15 msgid "2000Free Software Foundation, Inc." msgstr "2000Free Software Foundation, Inc." -#: C/index.docbook:20(para/address) +#. (itstool) path: para/address +#: C/index.docbook:20 #, no-wrap msgid "" "Free Software Foundation, Inc. 51 Franklin Street, \n" @@ -3133,8 +4311,8 @@ msgstr "" " Suite 330, Boston, MA \n" " 02110-1301 USA" -#: C/index.docbook:19(legalnotice/para) -#: C/fdl-appendix.xml:19(legalnotice/para) +#. (itstool) path: legalnotice/para +#: C/index.docbook:19 C/fdl-appendix.xml:19 msgid "" "<_:address-1/> Everyone is permitted to copy and distribute verbatim copies " "of this license document, but changing it is not allowed." @@ -3142,16 +4320,19 @@ msgstr "" "<_:address-1/> Chacun est libre de copier et de distribuer des copies " "conformes de cette Licence, mais nul n'est autorisé à la modifier." -#: C/index.docbook:28(appendix/title) C/fdl-appendix.xml:28(appendix/title) -#: C/fdl-appendix.xml:642(para/quote) +#. (itstool) path: appendix/title +#. (itstool) path: para/quote +#: C/index.docbook:28 C/fdl-appendix.xml:28 C/fdl-appendix.xml:642 msgid "GNU Free Documentation License" msgstr "Licence de Documentation Libre GNU" -#: C/index.docbook:31(sect1/title) C/fdl-appendix.xml:31(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:31 C/fdl-appendix.xml:31 msgid "0. PREAMBLE" msgstr "0. Préambule" -#: C/index.docbook:32(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:32 msgid "" "The purpose of this License is to make a manual, textbook, or other written " "document free in the sense of freedom: to assure everyone the " @@ -3168,7 +4349,8 @@ msgstr "" "qu'ils soient pour autant considérés comme responsables des modifications " "réalisées par des tiers." -#: C/index.docbook:43(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:43 msgid "" "This License is a kind of copyleft, which means that " "derivative works of the document must themselves be free in the same sense. " @@ -3180,7 +4362,8 @@ msgstr "" "les mêmes termes. Elle complète la Licence Publique Générale GNU, qui est " "également une Licence copyleft, conçue pour les logiciels libres." -#: C/index.docbook:50(sect1/para) C/fdl-appendix.xml:50(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:50 C/fdl-appendix.xml:50 msgid "" "We have designed this License in order to use it for manuals for free " "software, because free software needs free documentation: a free program " @@ -3200,11 +4383,13 @@ msgstr "" "Licence principalement pour les travaux destinés à des fins d'enseignement " "ou devant servir de documents de référence." -#: C/index.docbook:62(sect1/title) C/fdl-appendix.xml:62(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:62 C/fdl-appendix.xml:62 msgid "1. APPLICABILITY AND DEFINITIONS" msgstr "1. APPLICABILITÉ ET DÉFINITIONS" -#: C/index.docbook:63(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:63 msgid "" "This License applies to any manual or other work that contains a notice " "placed by the copyright holder saying it can be distributed under the terms " @@ -3218,7 +4403,8 @@ msgstr "" "ou travail. Toute personne en est par définition concessionnaire et est " "référencée ci-après par le terme Vous." -#: C/index.docbook:72(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:72 msgid "" "A Modified Version of the Document means any work containing " "the Document or a portion of it, either copied verbatim, or with " @@ -3228,7 +4414,8 @@ msgstr "" "contenant la totalité ou seulement une portion de celui-ci, copiée mot pour " "mot, modifiée et/ou traduite dans une autre langue." -#: C/index.docbook:79(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:79 msgid "" "A Secondary Section is a named appendix or a front-matter " "section of the Document that deals " @@ -3252,7 +4439,8 @@ msgstr "" "philosophiques, ou des positions éthiques ou politiques susceptibles de " "concerner le sujet traité." -#: C/index.docbook:94(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:94 msgid "" "The Invariant Sections are certain Secondary Sections whose titles are designated, as being " @@ -3264,7 +4452,8 @@ msgstr "" "modifiées et citées comme telles dans la notice légale qui place le Document sous cette Licence." -#: C/index.docbook:103(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:103 msgid "" "The Cover Texts are certain short passages of text that are " "listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says " @@ -3276,7 +4465,8 @@ msgstr "" "\">Document, et cités comme tels dans la mention légale de ce Document." -#: C/index.docbook:111(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:111 msgid "" "A Transparent copy of the " "Document means a machine-readable copy, represented in a format whose " @@ -3305,7 +4495,8 @@ msgstr "" "Une copie qui n'est pas Transparente est considérée, par " "opposition, comme Opaque." -#: C/index.docbook:128(sect1/para) C/fdl-appendix.xml:128(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:128 C/fdl-appendix.xml:128 msgid "" "Examples of suitable formats for Transparent copies include plain ASCII " "without markup, Texinfo input format, LaTeX input format, SGML or XML using " @@ -3329,7 +4520,8 @@ msgstr "" "d'un traitement de texte quelconque et dans le seul but de la génération " "d'un format de sortie." -#: C/index.docbook:141(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:141 msgid "" "The Title Page means, for a printed book, the title page " "itself, plus such following pages as are needed to hold, legibly, the " @@ -3345,11 +4537,13 @@ msgstr "" "décrit ci-dessus, la Page de titre désigne le texte qui " "s'apparente le plus au titre du document et situé avant le texte principal." -#: C/index.docbook:153(sect1/title) C/fdl-appendix.xml:153(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:153 C/fdl-appendix.xml:153 msgid "2. VERBATIM COPYING" msgstr "2. COPIES CONFORMES" -#: C/index.docbook:154(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:154 msgid "" "You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that " @@ -3374,7 +4568,8 @@ msgstr "" "grande quantité de copies, référez-vous aux dispositions de la section 3." -#: C/index.docbook:169(sect1/para) C/fdl-appendix.xml:169(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:169 C/fdl-appendix.xml:169 msgid "" "You may also lend copies, under the same conditions stated above, and you " "may publicly display copies." @@ -3383,11 +4578,13 @@ msgstr "" "celles suscitées, et vous pouvez afficher publiquement des copies de ce " "Document." -#: C/index.docbook:176(sect1/title) C/fdl-appendix.xml:176(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:176 C/fdl-appendix.xml:176 msgid "3. COPYING IN QUANTITY" msgstr "3. COPIES EN NOMBRE" -#: C/index.docbook:177(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:177 msgid "" "If you publish printed copies of the Document numbering more than 100, and the Document's license " @@ -3417,7 +4614,8 @@ msgstr "" "document\">Document soit préservé et que les conditions indiquées " "précédemment soient respectées." -#: C/index.docbook:195(sect1/para) C/fdl-appendix.xml:195(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:195 C/fdl-appendix.xml:195 msgid "" "If the required texts for either cover are too voluminous to fit legibly, " "you should put the first ones listed (as many as fit reasonably) on the " @@ -3427,7 +4625,8 @@ msgstr "" "y tenir de manière claire, vous pouvez ne placer que les premiers sur la " "première page et placer les suivants sur les pages consécutives." -#: C/index.docbook:202(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:202 msgid "" "If you publish or distribute Opaque " "copies of the Document numbering more " @@ -3456,7 +4655,8 @@ msgstr "" "durant une année pleine après la diffusion publique de la dernière Copie " "opaque(directement ou via vos revendeurs)." -#: C/index.docbook:222(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:222 msgid "" "It is requested, but not required, that you contact the authors of the Document well before redistributing any " @@ -3468,11 +4668,13 @@ msgstr "" "avant toute publication d'un grand nombre de copies, afin de lui permettre " "de vous donner une version à jour du Document." -#: C/index.docbook:231(sect1/title) C/fdl-appendix.xml:231(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:231 C/fdl-appendix.xml:231 msgid "4. MODIFICATIONS" msgstr "4. MODIFICATIONS" -#: C/index.docbook:232(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:232 msgid "" "You may copy and distribute a Modified " "Version of the Document under " @@ -3493,12 +4695,13 @@ msgstr "" "modifiée à quiconque en possède une copie. De plus, vous devez effectuer les " "actions suivantes dans la Version modifiée :" -#: C/index.docbook:248(formalpara/title) -#: C/fdl-appendix.xml:248(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:248 C/fdl-appendix.xml:248 msgid "A" msgstr "A" -#: C/index.docbook:249(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:249 msgid "" "Use in the Title Page (and on the " "covers, if any) a title distinct from that of the Title Page, as authors, " "one or more persons or entities responsible for authorship of the " @@ -3534,12 +4738,13 @@ msgstr "" "avec au moins les cinq principaux auteurs du Document (ou tous les auteurs s'il y en a moins de cinq)." -#: C/index.docbook:279(formalpara/title) -#: C/fdl-appendix.xml:279(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:279 C/fdl-appendix.xml:279 msgid "C" msgstr "C" -#: C/index.docbook:280(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:280 msgid "" "State on the Title Page the name of " "the publisher of the Modified Version, " @@ -3549,12 +4754,13 @@ msgstr "" "de l'éditeur de la Version modifiée, " "en tant qu'éditeur du Document." -#: C/index.docbook:291(formalpara/title) -#: C/fdl-appendix.xml:291(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:291 C/fdl-appendix.xml:291 msgid "D" msgstr "D" -#: C/index.docbook:292(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:292 msgid "" "Preserve all the copyright notices of the Document." @@ -3562,13 +4768,13 @@ msgstr "" "Préserver intégralement toutes les notices de copyright du Document." -#: C/index.docbook:301(formalpara/title) -#: C/fdl-appendix.xml:301(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:301 C/fdl-appendix.xml:301 msgid "E" msgstr "E" -#: C/index.docbook:302(formalpara/para) -#: C/fdl-appendix.xml:302(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:302 C/fdl-appendix.xml:302 msgid "" "Add an appropriate copyright notice for your modifications adjacent to the " "other copyright notices." @@ -3576,12 +4782,13 @@ msgstr "" "Ajouter une notice de copyright adjacente aux autres notices pour vos " "propres modifications." -#: C/index.docbook:311(formalpara/title) -#: C/fdl-appendix.xml:311(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:311 C/fdl-appendix.xml:311 msgid "F" msgstr "F" -#: C/index.docbook:312(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:312 msgid "" "Include, immediately after the copyright notices, a license notice giving " "the public permission to use the Modified " @@ -3593,12 +4800,13 @@ msgstr "" "\">Version modifiée selon les termes de cette Licence, sous la forme " "présentée dans l'annexe indiquée ci-dessous." -#: C/index.docbook:324(formalpara/title) -#: C/fdl-appendix.xml:324(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:324 C/fdl-appendix.xml:324 msgid "G" msgstr "G" -#: C/index.docbook:325(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:325 msgid "" "Preserve in that license notice the full lists of Invariant Sections and required Textes de couverture donnés avec la notice de la Licence du " "Document." -#: C/index.docbook:337(formalpara/title) -#: C/fdl-appendix.xml:337(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:337 C/fdl-appendix.xml:337 msgid "H" msgstr "H" -#: C/index.docbook:338(formalpara/para) -#: C/fdl-appendix.xml:338(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:338 C/fdl-appendix.xml:338 msgid "Include an unaltered copy of this License." msgstr "Inclure une copie non modifiée de cette Licence." -#: C/index.docbook:346(formalpara/title) -#: C/fdl-appendix.xml:346(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:346 C/fdl-appendix.xml:346 msgid "I" msgstr "I" -#: C/index.docbook:347(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:347 msgid "" "Preserve the section entitled History, and its title, and add " "to it an item stating at least the title, year, new authors, and publisher " @@ -3648,12 +4857,13 @@ msgstr "" "titre, et ajouter une entrée décrivant la Version modifiée tel que précisé dans la phrase précédente." -#: C/index.docbook:365(formalpara/title) -#: C/fdl-appendix.xml:365(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:365 C/fdl-appendix.xml:365 msgid "J" msgstr "J" -#: C/index.docbook:366(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:366 msgid "" "Preserve the network location, if any, given in the Document for public access to a Acknowledgements or " "Dedications, preserve the section's title, and preserve in " @@ -3690,12 +4901,13 @@ msgstr "" "contributeurs et les personnes auxquelles s'adressent ces remerciements " "doivent être conservées, ainsi que le titre de ces sections." -#: C/index.docbook:396(formalpara/title) -#: C/fdl-appendix.xml:396(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:396 C/fdl-appendix.xml:396 msgid "L" msgstr "L" -#: C/index.docbook:397(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:397 msgid "" "Preserve all the Invariant Sections " "of the Document, unaltered in their " @@ -3707,12 +4919,13 @@ msgstr "" "dans leurs textes, ni dans leurs titres. Les numéros de sections ne sont pas " "considérés comme faisant partie du texte des sections." -#: C/index.docbook:409(formalpara/title) -#: C/fdl-appendix.xml:409(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:409 C/fdl-appendix.xml:409 msgid "M" msgstr "M" -#: C/index.docbook:410(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:410 msgid "" "Delete any section entitled Endorsements. Such a section may " "not be included in the Modified VersionVersion modifiée." -#: C/index.docbook:421(formalpara/title) -#: C/fdl-appendix.xml:421(formalpara/title) +#. (itstool) path: formalpara/title +#: C/index.docbook:421 C/fdl-appendix.xml:421 msgid "N" msgstr "N" -#: C/index.docbook:422(formalpara/para) +#. (itstool) path: formalpara/para +#: C/index.docbook:422 msgid "" "Do not retitle any existing section as Endorsements or to " "conflict in title with any Invariant " @@ -3737,7 +4951,8 @@ msgstr "" "quote> ou sous un autre titre entrant en conflit avec le titre d'une Section inaltérable." -#: C/index.docbook:432(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:432 msgid "" "If the Modified Version includes new " "front-matter sections or appendices that qualify as Endorsements, provided it " "contains nothing but endorsements of your Front-Cover Text, and a passage of up to 25 words as a Document do not by this License give permission to use their names " @@ -3812,11 +5030,13 @@ msgstr "" "publicitaires ou pour prétendre à l'approbation d'une Version modifiée." -#: C/index.docbook:480(sect1/title) C/fdl-appendix.xml:480(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:480 C/fdl-appendix.xml:480 msgid "5. COMBINING DOCUMENTS" msgstr "5. FUSION DE DOCUMENTS" -#: C/index.docbook:481(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:481 msgid "" "You may combine the Document with " "other documents released under this License, under the terms defined in " @@ -3834,7 +5054,8 @@ msgstr "" "modification, et de toutes les lister dans la liste des Sections " "inaltérables de la notice de Licence du document résultant de la fusion." -#: C/index.docbook:492(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:492 msgid "" "The combined work need only contain one copy of this License, and multiple " "identical Invariant Sections may be " @@ -3855,7 +5076,8 @@ msgstr "" "être réalisées dans la liste des Sections inaltérables de la notice de " "Licence du document final." -#: C/index.docbook:505(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:505 msgid "" "In the combination, you must combine any sections entitled History in the various original documents, forming one section entitled " @@ -3870,11 +5092,13 @@ msgstr "" "Dédicaces. Vous devez supprimer toutes les sections " "Approbations." -#: C/index.docbook:516(sect1/title) C/fdl-appendix.xml:516(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:516 C/fdl-appendix.xml:516 msgid "6. COLLECTIONS OF DOCUMENTS" msgstr "6. REGROUPEMENTS DE DOCUMENTS" -#: C/index.docbook:517(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:517 msgid "" "You may make a collection consisting of the Document and other documents released under this License, and " @@ -3890,9 +5114,16 @@ msgstr "" "documents, à condition de respecter pour chacun de ces documents l'ensemble " "des règles de cette Licence concernant les copies conformes." -#: C/index.docbook:527(sect1/para) C/fdl-appendix.xml:527(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:527 C/fdl-appendix.xml:527 +#, fuzzy +#| msgid "" +#| "You may extract a single document from such a collection, and dispbibute " +#| "it individually under this License, provided you insert a copy of this " +#| "License into the extracted document, and follow this License in all other " +#| "respects regarding verbatim copying of that document." msgid "" -"You may extract a single document from such a collection, and dispbibute it " +"You may extract a single document from such a collection, and distribute it " "individually under this License, provided you insert a copy of this License " "into the extracted document, and follow this License in all other respects " "regarding verbatim copying of that document." @@ -3902,11 +5133,13 @@ msgstr "" "copie de cette Licence et d'en respecter l'ensemble des règles concernant " "les copies conformes." -#: C/index.docbook:537(sect1/title) C/fdl-appendix.xml:537(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:537 C/fdl-appendix.xml:537 msgid "7. AGGREGATION WITH INDEPENDENT WORKS" msgstr "7. AGRÉGATION AVEC DES TRAVAUX INDÉPENDANTS" -#: C/index.docbook:538(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:538 msgid "" "A compilation of the Document or its " "derivatives with other separate and independent documents or works, in or on " @@ -3939,11 +5172,13 @@ msgstr "" "que le Document au sein de l'agrégat. Dans le cas contraire, ils doivent " "apparaître sur les pages de couverture de l'agrégat complet." -#: C/index.docbook:561(sect1/title) C/fdl-appendix.xml:561(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:561 C/fdl-appendix.xml:561 msgid "8. TRANSLATION" msgstr "8. TRADUCTION" -#: C/index.docbook:562(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:562 msgid "" "Translation is considered a kind of modification, so you may distribute " "translations of the Document under the " @@ -3968,11 +5203,13 @@ msgstr "" "originale en anglais. En cas de contradiction entre la traduction et la " "version originale en anglais, c'est cette dernière qui prévaut." -#: C/index.docbook:580(sect1/title) C/fdl-appendix.xml:580(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:580 C/fdl-appendix.xml:580 msgid "9. TERMINATION" msgstr "9. RÉVOCATION" -#: C/index.docbook:581(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:581 msgid "" "You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this " @@ -3991,11 +5228,13 @@ msgstr "" "cette Licence ne voient pas leurs droits révoqués tant qu'elles en " "respectent les principes." -#: C/index.docbook:594(sect1/title) C/fdl-appendix.xml:594(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:594 C/fdl-appendix.xml:594 msgid "10. FUTURE REVISIONS OF THIS LICENSE" msgstr "10. RÉVISIONS FUTURES DE CETTE LICENCE" -#: C/index.docbook:595(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:595 msgid "" "The Free " "Software Foundation may publish new, revised versions of the GNU " @@ -4012,7 +5251,8 @@ msgstr "" "http://www.gnu.org/" "copyleft/ pour plus de détails." -#: C/index.docbook:606(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:606 msgid "" "Each version of the License is given a distinguishing version number. If the " "Document specifies that a particular " @@ -4032,11 +5272,13 @@ msgstr "" "spécifié, vous pouvez choisir n'importe quelle version officielle publiée " "par la Free Software Foundation." -#: C/index.docbook:621(sect1/title) C/fdl-appendix.xml:621(sect1/title) +#. (itstool) path: sect1/title +#: C/index.docbook:621 C/fdl-appendix.xml:621 msgid "Addendum" msgstr "Addendum" -#: C/index.docbook:622(sect1/para) C/fdl-appendix.xml:622(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:622 C/fdl-appendix.xml:622 msgid "" "To use this License in a document you have written, include a copy of the " "License in the document and put the following copyright and license notices " @@ -4046,12 +5288,13 @@ msgstr "" "une copie du texte de cette Licence en anglais et placez le texte ci-dessous " "juste après la page de titre :" -#: C/index.docbook:629(blockquote/para) -#: C/fdl-appendix.xml:629(blockquote/para) +#. (itstool) path: blockquote/para +#: C/index.docbook:629 C/fdl-appendix.xml:629 msgid "Copyright YEAR YOUR NAME." msgstr "Copyright © 2010 Bruno Brouard." -#: C/index.docbook:632(blockquote/para) +#. (itstool) path: blockquote/para +#: C/index.docbook:632 msgid "" "Permission is granted to copy, distribute and/or modify this document under " "the terms of the GNU Free Documentation License, Version 1.1 or any later " @@ -4073,7 +5316,8 @@ msgstr "" "COUVERTURE. Une copie de cette Licence est incluse dans la section appelée " "GNU Free Documentation License de ce document." -#: C/index.docbook:647(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:647 msgid "" "If you have no Invariant Sections, " "write with no Invariant Sections instead of saying which ones " @@ -4091,7 +5335,8 @@ msgstr "" "PREMIÈRE PAGE DE COUVERTURE ; de même pour le texte de dernière page de couverture." -#: C/index.docbook:657(sect1/para) +#. (itstool) path: sect1/para +#: C/index.docbook:657 msgid "" "If your document contains nontrivial examples of program code, we recommend " "releasing these examples in parallel under your choice of free software " @@ -4104,35 +5349,43 @@ msgstr "" "\" url=\"http://www.gnu.org/copyleft/gpl.html\">Licence GNU General Public " "License, qui permet leur usage dans les logiciels libres." -#: C/fdl-appendix.xml:16(copyright/year) +#. (itstool) path: copyright/year +#: C/fdl-appendix.xml:16 msgid "2000" msgstr "2000" -#: C/fdl-appendix.xml:16(copyright/holder) +#. (itstool) path: copyright/holder +#: C/fdl-appendix.xml:16 msgid "Free Software Foundation, Inc." msgstr "Free Software Foundation, Inc." -#: C/fdl-appendix.xml:20(address/street) +#. (itstool) path: address/street +#: C/fdl-appendix.xml:20 msgid "51 Franklin Street, Suite 330" msgstr "51 Franklin Street, Suite 330" -#: C/fdl-appendix.xml:21(address/city) +#. (itstool) path: address/city +#: C/fdl-appendix.xml:21 msgid "Boston" msgstr "Boston" -#: C/fdl-appendix.xml:21(address/state) +#. (itstool) path: address/state +#: C/fdl-appendix.xml:21 msgid "MA" msgstr "MA" -#: C/fdl-appendix.xml:22(address/postcode) +#. (itstool) path: address/postcode +#: C/fdl-appendix.xml:22 msgid "02110-1301" msgstr "02110-1301" -#: C/fdl-appendix.xml:22(address/country) +#. (itstool) path: address/country +#: C/fdl-appendix.xml:22 msgid "USA" msgstr "USA" -#: C/fdl-appendix.xml:20(para/address) +#. (itstool) path: para/address +#: C/fdl-appendix.xml:20 msgid "" "Free Software Foundation, Inc. <_:street-1/>, <_:city-2/>, <_:state-3/> <_:" "postcode-4/> <_:country-5/>" @@ -4140,11 +5393,13 @@ msgstr "" "Free Software Foundation, Inc. <_:street-1/>, <_:city-2/>, <_:state-3/> <_:" "postcode-4/> <_:country-5/>" -#: C/fdl-appendix.xml:34(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:34 msgid "free" msgstr "libre" -#: C/fdl-appendix.xml:32(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:32 msgid "" "The purpose of this License is to make a manual, textbook, or other written " "document <_:quote-1/> in the sense of freedom: to assure everyone the " @@ -4161,11 +5416,13 @@ msgstr "" "qu'ils soient pour autant considérés comme responsables des modifications " "réalisées par des tiers." -#: C/fdl-appendix.xml:44(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:44 msgid "copyleft" msgstr "copyleft" -#: C/fdl-appendix.xml:43(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:43 msgid "" "This License is a kind of <_:quote-1/>, which means that derivative works of " "the document must themselves be free in the same sense. It complements the " @@ -4177,27 +5434,27 @@ msgstr "" "termes. Elle complète la Licence Publique Générale GNU, qui est également " "une Licence copyleft, conçue pour les logiciels libres." -#: C/fdl-appendix.xml:67(para/quote) C/fdl-appendix.xml:82(para/link) -#: C/fdl-appendix.xml:99(para/link) C/fdl-appendix.xml:107(para/link) -#: C/fdl-appendix.xml:113(para/link) C/fdl-appendix.xml:156(para/link) -#: C/fdl-appendix.xml:179(para/link) C/fdl-appendix.xml:190(para/link) -#: C/fdl-appendix.xml:205(para/link) C/fdl-appendix.xml:224(para/link) -#: C/fdl-appendix.xml:235(para/link) C/fdl-appendix.xml:253(para/link) -#: C/fdl-appendix.xml:271(para/link) C/fdl-appendix.xml:294(para/link) -#: C/fdl-appendix.xml:354(para/link) C/fdl-appendix.xml:368(para/link) -#: C/fdl-appendix.xml:400(para/link) C/fdl-appendix.xml:462(para/link) -#: C/fdl-appendix.xml:472(para/link) C/fdl-appendix.xml:482(para/link) -#: C/fdl-appendix.xml:519(para/link) C/fdl-appendix.xml:540(para/link) -#: C/fdl-appendix.xml:565(para/link) C/fdl-appendix.xml:583(para/link) -#: C/fdl-appendix.xml:608(para/link) +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:67 C/fdl-appendix.xml:82 C/fdl-appendix.xml:99 +#: C/fdl-appendix.xml:107 C/fdl-appendix.xml:113 C/fdl-appendix.xml:156 +#: C/fdl-appendix.xml:179 C/fdl-appendix.xml:190 C/fdl-appendix.xml:205 +#: C/fdl-appendix.xml:224 C/fdl-appendix.xml:235 C/fdl-appendix.xml:253 +#: C/fdl-appendix.xml:271 C/fdl-appendix.xml:294 C/fdl-appendix.xml:354 +#: C/fdl-appendix.xml:368 C/fdl-appendix.xml:400 C/fdl-appendix.xml:462 +#: C/fdl-appendix.xml:472 C/fdl-appendix.xml:482 C/fdl-appendix.xml:519 +#: C/fdl-appendix.xml:540 C/fdl-appendix.xml:565 C/fdl-appendix.xml:583 +#: C/fdl-appendix.xml:608 msgid "Document" msgstr "Document" -#: C/fdl-appendix.xml:69(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:69 msgid "you" msgstr "Vous" -#: C/fdl-appendix.xml:63(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:63 msgid "" "This License applies to any manual or other work that contains a notice " "placed by the copyright holder saying it can be distributed under the terms " @@ -4210,16 +5467,17 @@ msgstr "" "Toute personne en est par définition concessionnaire et est référencée ci-" "après par le terme <_:quote-2/>." -#: C/fdl-appendix.xml:73(para/quote) C/fdl-appendix.xml:234(para/link) -#: C/fdl-appendix.xml:269(para/link) C/fdl-appendix.xml:283(para/link) -#: C/fdl-appendix.xml:315(para/link) C/fdl-appendix.xml:351(para/link) -#: C/fdl-appendix.xml:413(para/link) C/fdl-appendix.xml:433(para/link) -#: C/fdl-appendix.xml:447(para/link) C/fdl-appendix.xml:459(para/link) -#: C/fdl-appendix.xml:475(para/link) C/fdl-appendix.xml:543(para/link) +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:73 C/fdl-appendix.xml:234 C/fdl-appendix.xml:269 +#: C/fdl-appendix.xml:283 C/fdl-appendix.xml:315 C/fdl-appendix.xml:351 +#: C/fdl-appendix.xml:413 C/fdl-appendix.xml:433 C/fdl-appendix.xml:447 +#: C/fdl-appendix.xml:459 C/fdl-appendix.xml:475 C/fdl-appendix.xml:543 msgid "Modified Version" msgstr "Version modifiée" -#: C/fdl-appendix.xml:72(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:72 msgid "" "A <_:quote-1/> of the Document means any work containing the Document or a " "portion of it, either copied verbatim, or with modifications and/or " @@ -4229,11 +5487,13 @@ msgstr "" "ou seulement une portion de celui-ci, copiée mot pour mot, modifiée et/ou " "traduite dans une autre langue." -#: C/fdl-appendix.xml:80(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:80 msgid "Secondary Section" msgstr "Section secondaire" -#: C/fdl-appendix.xml:79(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:79 msgid "" "A <_:quote-1/> is a named appendix or a front-matter section of the <_:" "link-2/> that deals exclusively with the relationship of the publishers or " @@ -4255,19 +5515,21 @@ msgstr "" "légales, commerciales, philosophiques, ou des positions éthiques ou " "politiques susceptibles de concerner le sujet traité." -#: C/fdl-appendix.xml:95(para/quote) C/fdl-appendix.xml:327(para/link) -#: C/fdl-appendix.xml:398(para/link) C/fdl-appendix.xml:439(para/link) -#: C/fdl-appendix.xml:486(para/link) C/fdl-appendix.xml:494(para/link) -#: C/fdl-appendix.xml:567(para/link) C/fdl-appendix.xml:637(para/link) -#: C/fdl-appendix.xml:648(para/link) +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:95 C/fdl-appendix.xml:327 C/fdl-appendix.xml:398 +#: C/fdl-appendix.xml:439 C/fdl-appendix.xml:486 C/fdl-appendix.xml:494 +#: C/fdl-appendix.xml:567 C/fdl-appendix.xml:637 C/fdl-appendix.xml:648 msgid "Invariant Sections" msgstr "Sections inaltérables" -#: C/fdl-appendix.xml:96(para/link) C/fdl-appendix.xml:435(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:96 C/fdl-appendix.xml:435 msgid "Secondary Sections" msgstr "sections secondaires" -#: C/fdl-appendix.xml:94(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:94 msgid "" "The <_:quote-1/> are certain <_:link-2/> whose titles are designated, as " "being those of Invariant Sections, in the notice that says that the <_:" @@ -4277,12 +5539,15 @@ msgstr "" "modifiées et citées comme telles dans la notice légale qui place le <_:" "link-3/> sous cette Licence." -#: C/fdl-appendix.xml:104(para/quote) C/fdl-appendix.xml:181(para/link) -#: C/fdl-appendix.xml:328(para/link) C/fdl-appendix.xml:458(para/link) +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:104 C/fdl-appendix.xml:181 C/fdl-appendix.xml:328 +#: C/fdl-appendix.xml:458 msgid "Cover Texts" msgstr "Textes de couverture" -#: C/fdl-appendix.xml:103(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:103 msgid "" "The <_:quote-1/> are certain short passages of text that are listed, as " "Front-Cover Texts or Back-Cover Texts, in the notice that says that the <_:" @@ -4292,16 +5557,21 @@ msgstr "" "avant et arrière, et cités comme tels dans la mention légale de ce <_:link-2/" ">." -#: C/fdl-appendix.xml:112(para/quote) C/fdl-appendix.xml:124(para/quote) -#: C/fdl-appendix.xml:207(para/link) C/fdl-appendix.xml:369(para/link) +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:112 C/fdl-appendix.xml:124 C/fdl-appendix.xml:207 +#: C/fdl-appendix.xml:369 msgid "Transparent" msgstr "Copie transparente" -#: C/fdl-appendix.xml:125(para/quote) C/fdl-appendix.xml:204(para/link) +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:125 C/fdl-appendix.xml:204 msgid "Opaque" msgstr "Opaque" -#: C/fdl-appendix.xml:111(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:111 msgid "" "A <_:quote-1/> copy of the <_:link-2/> means a machine-readable copy, " "represented in a format whose specification is available to the general " @@ -4328,13 +5598,15 @@ msgstr "" "comme une Copie Transparente. Une copie qui n'est pas <_:quote-3/> est " "considérée, par opposition, comme <_:quote-4/>." -#: C/fdl-appendix.xml:142(para/quote) C/fdl-appendix.xml:146(para/quote) -#: C/fdl-appendix.xml:250(para/link) C/fdl-appendix.xml:266(para/link) -#: C/fdl-appendix.xml:281(para/link) C/fdl-appendix.xml:352(para/link) +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:142 C/fdl-appendix.xml:146 C/fdl-appendix.xml:250 +#: C/fdl-appendix.xml:266 C/fdl-appendix.xml:281 C/fdl-appendix.xml:352 msgid "Title Page" msgstr "Page de titre" -#: C/fdl-appendix.xml:141(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:141 msgid "" "The <_:quote-1/> means, for a printed book, the title page itself, plus such " "following pages as are needed to hold, legibly, the material this License " @@ -4350,11 +5622,13 @@ msgstr "" "dessus, la <_:quote-2/> désigne le texte qui s'apparente le plus au titre du " "document et situé avant le texte principal." -#: C/fdl-appendix.xml:166(para/link) C/fdl-appendix.xml:551(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:166 C/fdl-appendix.xml:551 msgid "section 3" msgstr "section 3" -#: C/fdl-appendix.xml:154(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:154 msgid "" "You may copy and distribute the <_:link-1/> in any medium, either " "commercially or noncommercially, provided that this License, the copyright " @@ -4377,7 +5651,8 @@ msgstr "" "des copies. Si vous distribuez une grande quantité de copies, référez-vous " "aux dispositions de la <_:link-2/>." -#: C/fdl-appendix.xml:177(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:177 msgid "" "If you publish printed copies of the <_:link-1/> numbering more than 100, " "and the Document's license notice requires <_:link-2/>, you must enclose the " @@ -4403,7 +5678,8 @@ msgstr "" "comme des copies conformes, à condition que le titre du <_:link-3/> soit " "préservé et que les conditions indiquées précédemment soient respectées." -#: C/fdl-appendix.xml:202(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:202 msgid "" "If you publish or distribute <_:link-1/> copies of the <_:link-2/> numbering " "more than 100, you must either include a machine-readable <_:link-3/> copy " @@ -4429,7 +5705,8 @@ msgstr "" "transparente durant une année pleine après la diffusion publique de la " "dernière Copie opaque(directement ou via vos revendeurs)." -#: C/fdl-appendix.xml:222(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:222 msgid "" "It is requested, but not required, that you contact the authors of the <_:" "link-1/> well before redistributing any large number of copies, to give them " @@ -4440,15 +5717,18 @@ msgstr "" "nombre de copies, afin de lui permettre de vous donner une version à jour du " "Document." -#: C/fdl-appendix.xml:236(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:236 msgid "2" msgstr "2" -#: C/fdl-appendix.xml:237(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:237 msgid "3" msgstr "3" -#: C/fdl-appendix.xml:232(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:232 msgid "" "You may copy and distribute a <_:link-1/> of the <_:link-2/> under the " "conditions of sections <_:link-3/> and <_:link-4/> above, provided that you " @@ -4465,7 +5745,8 @@ msgstr "" "de modifier cette Version modifiée à quiconque en possède une copie. De " "plus, vous devez effectuer les actions suivantes dans la Version modifiée :" -#: C/fdl-appendix.xml:249(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:249 msgid "" "Use in the <_:link-1/> (and on the covers, if any) a title distinct from " "that of the <_:link-2/>, and from those of previous versions (which should, " @@ -4479,7 +5760,8 @@ msgstr "" "dans la section Historique du Document). Vous pouvez utiliser le même titre " "si l'éditeur d'origine vous en a donné expressément la permission." -#: C/fdl-appendix.xml:265(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:265 msgid "" "List on the <_:link-1/>, as authors, one or more persons or entities " "responsible for authorship of the modifications in the <_:link-2/>, together " @@ -4491,7 +5773,8 @@ msgstr "" "au moins les cinq principaux auteurs du <_:link-3/> (ou tous les auteurs " "s'il y en a moins de cinq)." -#: C/fdl-appendix.xml:280(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:280 msgid "" "State on the <_:link-1/> the name of the publisher of the <_:link-2/>, as " "the publisher." @@ -4499,12 +5782,14 @@ msgstr "" "Préciser sur la <_:link-1/> le nom de l'éditeur de la <_:link-2/>, en tant " "qu'éditeur du Document." -#: C/fdl-appendix.xml:292(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:292 msgid "Preserve all the copyright notices of the <_:link-1/>." msgstr "" "Préserver intégralement toutes les notices de copyright du <_:link-1/>." -#: C/fdl-appendix.xml:312(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:312 msgid "" "Include, immediately after the copyright notices, a license notice giving " "the public permission to use the <_:link-1/> under the terms of this " @@ -4514,11 +5799,13 @@ msgstr "" "quiconque l'autorisation d'utiliser la <_:link-1/> selon les termes de cette " "Licence, sous la forme présentée dans l'annexe indiquée ci-dessous." -#: C/fdl-appendix.xml:330(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:330 msgid "Document's" msgstr "Document" -#: C/fdl-appendix.xml:325(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:325 msgid "" "Preserve in that license notice the full lists of <_:link-1/> and required " "<_:link-2/> given in the <_:link-3/> license notice." @@ -4526,13 +5813,14 @@ msgstr "" "Préserver dans cette notice la liste complète des <_:link-1/> et les <_:" "link-2/> donnés avec la notice de la Licence du <_:link-3/>." -#: C/fdl-appendix.xml:348(para/quote) C/fdl-appendix.xml:353(para/quote) -#: C/fdl-appendix.xml:372(para/quote) C/fdl-appendix.xml:507(para/quote) -#: C/fdl-appendix.xml:508(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:348 C/fdl-appendix.xml:353 C/fdl-appendix.xml:372 +#: C/fdl-appendix.xml:507 C/fdl-appendix.xml:508 msgid "History" msgstr "Historique" -#: C/fdl-appendix.xml:347(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:347 msgid "" "Preserve the section entitled <_:quote-1/>, and its title, and add to it an " "item stating at least the title, year, new authors, and publisher of the <_:" @@ -4550,7 +5838,8 @@ msgstr "" "Document tel que précisé sur la Page de titre,et ajouter une entrée " "décrivant la Version modifiée tel que précisé dans la phrase précédente." -#: C/fdl-appendix.xml:366(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:366 msgid "" "Preserve the network location, if any, given in the <_:link-1/> for public " "access to a <_:link-2/> copy of the Document, and likewise the network " @@ -4568,15 +5857,18 @@ msgstr "" "datant de plus de quatre ans avant la version courante ou si l'éditeur " "d'origine vous en accorde la permission." -#: C/fdl-appendix.xml:385(para/quote) C/fdl-appendix.xml:509(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:385 C/fdl-appendix.xml:509 msgid "Acknowledgements" msgstr "Remerciements" -#: C/fdl-appendix.xml:386(para/quote) C/fdl-appendix.xml:510(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:386 C/fdl-appendix.xml:510 msgid "Dedications" msgstr "Dédicaces" -#: C/fdl-appendix.xml:384(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:384 msgid "" "In any section entitled <_:quote-1/> or <_:quote-2/>, preserve the section's " "title, and preserve in the section all the substance and tone of each of the " @@ -4587,7 +5879,8 @@ msgstr "" "personnes auxquelles s'adressent ces remerciements doivent être conservées, " "ainsi que le titre de ces sections." -#: C/fdl-appendix.xml:397(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:397 msgid "" "Preserve all the <_:link-1/> of the <_:link-2/>, unaltered in their text and " "in their titles. Section numbers or the equivalent are not considered part " @@ -4597,12 +5890,13 @@ msgstr "" "textes, ni dans leurs titres. Les numéros de sections ne sont pas considérés " "comme faisant partie du texte des sections." -#: C/fdl-appendix.xml:412(para/quote) C/fdl-appendix.xml:424(para/quote) -#: C/fdl-appendix.xml:445(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:412 C/fdl-appendix.xml:424 C/fdl-appendix.xml:445 msgid "Endorsements" msgstr "Approbations" -#: C/fdl-appendix.xml:410(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:410 msgid "" "Delete any section entitled <_:quote-1/>. Such a section may not be included " "in the <_:link-2/>." @@ -4610,11 +5904,13 @@ msgstr "" "Effacer toute section intitulée <_:quote-1/>. Une telle section ne peut pas " "être incluse dans une <_:link-2/>." -#: C/fdl-appendix.xml:425(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:425 msgid "Invariant Section" msgstr "Section inaltérable" -#: C/fdl-appendix.xml:422(formalpara/para) +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:422 msgid "" "Do not retitle any existing section as <_:quote-1/> or to conflict in title " "with any <_:link-2/>." @@ -4622,7 +5918,8 @@ msgstr "" "Ne pas renommer une section existante sous le titre <_:quote-1/> ou sous un " "autre titre entrant en conflit avec le titre d'une <_:link-2/>." -#: C/fdl-appendix.xml:432(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:432 msgid "" "If the <_:link-1/> includes new front-matter sections or appendices that " "qualify as <_:link-2/> and contain no material copied from the Document, you " @@ -4639,7 +5936,8 @@ msgstr "" "link-3/> au sein de la notice de Licence de la Version modifiée. Ces titres " "doivent êtres distincts des titres des autres sections." -#: C/fdl-appendix.xml:444(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:444 msgid "" "You may add a section entitled <_:quote-1/>, provided it contains nothing " "but endorsements of your <_:link-2/> by various parties--for example, " @@ -4652,15 +5950,18 @@ msgstr "" "du texte par une organisation le reconnaissant comme étant la définition " "d'un standard)." -#: C/fdl-appendix.xml:455(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:455 msgid "Front-Cover Text" msgstr "première page de couverture" -#: C/fdl-appendix.xml:457(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:457 msgid "Back-Cover Text" msgstr "dernière page de couverture" -#: C/fdl-appendix.xml:453(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:453 msgid "" "You may add a passage of up to five words as a <_:link-1/>, and a passage of " "up to 25 words as a <_:link-2/>, to the end of the list of <_:link-3/> in " @@ -4682,7 +5983,8 @@ msgstr "" "passage si vous avez expressément obtenu l'autorisation de l'éditeur de " "celui-ci." -#: C/fdl-appendix.xml:470(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:470 msgid "" "The author(s) and publisher(s) of the <_:link-1/> do not by this License " "give permission to use their names for publicity for or to assert or imply " @@ -4692,11 +5994,13 @@ msgstr "" "des éditeurs de ce <_:link-1/> à des fins publicitaires ou pour prétendre à " "l'approbation d'une <_:link-2/>." -#: C/fdl-appendix.xml:484(para/link) C/fdl-appendix.xml:566(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:484 C/fdl-appendix.xml:566 msgid "section 4" msgstr "section 4" -#: C/fdl-appendix.xml:481(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:481 msgid "" "You may combine the <_:link-1/> with other documents released under this " "License, under the terms defined in <_:link-2/> above for modified versions, " @@ -4711,7 +6015,8 @@ msgstr "" "dans la liste des Sections inaltérables de la notice de Licence du document " "résultant de la fusion." -#: C/fdl-appendix.xml:492(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:492 msgid "" "The combined work need only contain one copy of this License, and multiple " "identical <_:link-1/> may be replaced with a single copy. If there are " @@ -4731,11 +6036,13 @@ msgstr "" "mêmes modifications doivent être réalisées dans la liste des Sections " "inaltérables de la notice de Licence du document final." -#: C/fdl-appendix.xml:511(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:511 msgid "Endorsements." msgstr "Approbations" -#: C/fdl-appendix.xml:505(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:505 msgid "" "In the combination, you must combine any sections entitled <_:quote-1/> in " "the various original documents, forming one section entitled <_:quote-2/>; " @@ -4747,7 +6054,8 @@ msgstr "" ">. De même, vous devez rassembler les sections <_:quote-3/> et <_:quote-4/>. " "Vous devez supprimer toutes les sections <_:quote-5/>." -#: C/fdl-appendix.xml:517(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:517 msgid "" "You may make a collection consisting of the <_:link-1/> and other documents " "released under this License, and replace the individual copies of this " @@ -4762,15 +6070,18 @@ msgstr "" "chacun de ces documents l'ensemble des règles de cette Licence concernant " "les copies conformes." -#: C/fdl-appendix.xml:546(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:546 msgid "aggregate" msgstr "agrégat" -#: C/fdl-appendix.xml:550(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:550 msgid "Cover Text" msgstr "Textes de couverture" -#: C/fdl-appendix.xml:538(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:538 msgid "" "A compilation of the <_:link-1/> or its derivatives with other separate and " "independent documents or works, in or on a volume of a storage or " @@ -4799,7 +6110,8 @@ msgstr "" "Dans le cas contraire, ils doivent apparaître sur les pages de couverture de " "l'agrégat complet." -#: C/fdl-appendix.xml:562(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:562 msgid "" "Translation is considered a kind of modification, so you may distribute " "translations of the <_:link-1/> under the terms of <_:link-2/>. Replacing <_:" @@ -4821,7 +6133,8 @@ msgstr "" "traduction et la version originale en anglais, c'est cette dernière qui " "prévaut." -#: C/fdl-appendix.xml:581(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:581 msgid "" "You may not copy, modify, sublicense, or distribute the <_:link-1/> except " "as expressly provided for under this License. Any other attempt to copy, " @@ -4838,15 +6151,18 @@ msgstr "" "sur le document sous couvert de cette Licence ne voient pas leurs droits " "révoqués tant qu'elles en respectent les principes." -#: C/fdl-appendix.xml:597(para/ulink) +#. (itstool) path: para/ulink +#: C/fdl-appendix.xml:597 msgid "Free Software Foundation" msgstr "Free Software Foundation" -#: C/fdl-appendix.xml:603(para/ulink) +#. (itstool) path: para/ulink +#: C/fdl-appendix.xml:603 msgid "http://www.gnu.org/copyleft/" msgstr "http://www.gnu.org/copyleft/" -#: C/fdl-appendix.xml:595(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:595 msgid "" "The <_:ulink-1/> may publish new, revised versions of the GNU Free " "Documentation License from time to time. Such new versions will be similar " @@ -4859,11 +6175,13 @@ msgstr "" "particuliers en fonction de nouvelles questions ou nouveaux problèmes. Voyez " "<_:ulink-2/> pour plus de détails." -#: C/fdl-appendix.xml:610(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:610 msgid "or any later version" msgstr "ou toute autre version ultérieure" -#: C/fdl-appendix.xml:606(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:606 msgid "" "Each version of the License is given a distinguishing version number. If the " "<_:link-1/> specifies that a particular numbered version of this License <_:" @@ -4881,15 +6199,18 @@ msgstr "" "version n'est spécifié, vous pouvez choisir n'importe quelle version " "officielle publiée par la Free Software Foundation." -#: C/fdl-appendix.xml:639(para/link) C/fdl-appendix.xml:651(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:639 C/fdl-appendix.xml:651 msgid "Front-Cover Texts" msgstr "texte de première page de couverture" -#: C/fdl-appendix.xml:640(para/link) C/fdl-appendix.xml:654(para/link) +#. (itstool) path: para/link +#: C/fdl-appendix.xml:640 C/fdl-appendix.xml:654 msgid "Back-Cover Texts" msgstr "texte de dernière page de couverture" -#: C/fdl-appendix.xml:632(blockquote/para) +#. (itstool) path: blockquote/para +#: C/fdl-appendix.xml:632 msgid "" "Permission is granted to copy, distribute and/or modify this document under " "the terms of the GNU Free Documentation License, Version 1.1 or any later " @@ -4906,21 +6227,25 @@ msgstr "" "TEXTE DE DERNIÈRE PAGE DE COUVERTURE. Une copie de cette Licence est incluse " "dans la section appelée <_:quote-4/> de ce document." -#: C/fdl-appendix.xml:649(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:649 msgid "with no Invariant Sections" msgstr "pas de section inaltérable" -#: C/fdl-appendix.xml:652(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:652 msgid "no Front-Cover Texts" msgstr "pas de texte de première page de couverture" -#: C/fdl-appendix.xml:653(para/quote) +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:653 msgid "Front-Cover Texts being LIST" msgstr "" "texte de première page de couverture suivant TEXTE DE PREMIÈRE PAGE DE " "COUVERTURE" -#: C/fdl-appendix.xml:647(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:647 msgid "" "If you have no <_:link-1/>, write <_:quote-2/> instead of saying which ones " "are invariant. If you have no <_:link-3/>, write <_:quote-4/> instead of <_:" @@ -4931,11 +6256,13 @@ msgstr "" "pas de <_:link-3/>, écrivez <_:quote-4/> au lieu de <_:quote-5/>; de même " "pour le <_:link-6/>." -#: C/fdl-appendix.xml:661(para/ulink) +#. (itstool) path: para/ulink +#: C/fdl-appendix.xml:661 msgid "GNU General Public License" msgstr "Licence Publique Générale GNU" -#: C/fdl-appendix.xml:657(sect1/para) +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:657 msgid "" "If your document contains nontrivial examples of program code, we recommend " "releasing these examples in parallel under your choice of free software " @@ -4945,6 +6272,214 @@ msgstr "" "recommandons de distribuer ces exemples en parallèle sous <_:ulink-1/>, qui " "permet leur usage dans les logiciels libres." +#~ msgid "1.18.1" +#~ msgstr "1.18.1" + +#~ msgid "" +#~ "Generating the \"template\" files. " +#~ "gtkdoc-mktmpl creates a number of files in the " +#~ "tmpl/ 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 "" +#~ "Génération des fichiers « prototypes ». " +#~ "gtkdoc-mktmpl crée un certain nombre de " +#~ "fichiers dans le sous-répertoire tmpl/, en utilisant les informations récoltées lors de la première " +#~ "étape (notez que le script peut être exécuté plusieurs fois, il est fait " +#~ "en sorte qu'aucune donnée ne soit jamais perdue)." + +#~ msgid "" +#~ "Since GTK-Doc 1.9 the templates can be avoided. We encourage people to " +#~ "keep documentation in the code. gtkdocize " +#~ "supports now a option that chooses a " +#~ "makefile that skips tmpl usage totally. If you have never changed file in " +#~ "tmpl by hand, please remove the directory (e.g. from version control " +#~ "system)." +#~ msgstr "" +#~ "Depuis GTK-Doc 1.9, les prototypes peuvent être évités. Nous encourageons " +#~ "tout le monde à conserver la documentation dans le code. " +#~ "gtkdocize prend maintenant en charge l'option " +#~ " qui choisit un makefile qui évite " +#~ "complètement l'utilisation de tmpl. Si vous n'avez jamais modifié de " +#~ "fichiers à la main dans tmpl, effacez le répertoire (par ex. à partir " +#~ "d'un système de gestion de versions)." + +#~ msgid "" +#~ "DocBook DTD v3.0 - This is the DocBook SGML DTD. " +#~ "http://www.ora." +#~ "com/davenport" +#~ msgstr "" +#~ "DocBook DTD v3.0 - ce sont les DTD DocBook SGML. " +#~ "http://www.ora." +#~ "com/davenport" + +#~ msgid "" +#~ "Jade v1.1 - This is a DSSSL processor for converting " +#~ "SGML to various formats. http://www.jclark.com/jade" +#~ msgstr "" +#~ "Jade v1.1 - c'est un moteur DSSSL pour convertir le " +#~ "SGML en divers formats. http://www.jclark.com/jade" + +#~ msgid "" +#~ "Modular DocBook Stylesheets 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. http://nwalsh.com/docbook/dsssl" +#~ msgstr "" +#~ "Modular DocBook Stylesheets - c'est le code DSSSL " +#~ "utilisé pour convertir de DocBook vers HTML (ainsi que quelques autres " +#~ "formats). Il est utilisé conjointement avec Jade. J'ai légèrement " +#~ "personnalisé le code DSSSL, dans gtk-doc.dsl, pour coloriser les listings " +#~ "de code du programme et les déclarations ainsi que pour prendre en charge " +#~ "les indices globaux des références croisées dans le HTML généré. http://nwalsh.com/" +#~ "docbook/dsssl" + +#~ msgid "" +#~ "docbook-to-man - 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 " +#~ "http://www.ora." +#~ "com/davenport NOTE: This does not work yet." +#~ msgstr "" +#~ "docbook-to-man - si vous souhaitez créer des pages " +#~ "de manuel depuis DocBook. J'ai légèrement adapté les « spécifications de " +#~ "traduction » pour mettre en majuscule les en-têtes de section et pour " +#~ "ajouter le titre « GTK Library » en haut des pages et la date de révision " +#~ "en bas. Il y a un lien sur cela ici http://www.ora.com/davenport. Note : " +#~ "cela ne fonctionne pas encore." + +#~ msgid "" +#~ "There is no standard place where the DocBook Modular Stylesheets are " +#~ "installed." +#~ msgstr "" +#~ "Il n'y a pas d'emplacement standard pour l'installation des feuilles de " +#~ "styles modulaires de DocBook." + +#~ msgid "" +#~ "GTK-Doc's configure script searches these 3 directories automatically:" +#~ msgstr "" +#~ "Les scripts d'installation de GTK-Doc cherchent dans ces trois " +#~ "répertoires automatiquement :" + +#~ msgid "" +#~ " /usr/lib/sgml/stylesheets/nwalsh-modular (used by " +#~ "RedHat)" +#~ msgstr "" +#~ " /usr/lib/sgml/stylesheets/nwalsh-modular (utilisé " +#~ "par Red Hat)" + +#~ msgid "" +#~ " /usr/lib/dsssl/stylesheets/docbook (used by Debian)" +#~ msgstr "" +#~ " /usr/lib/dsssl/stylesheets/docbook (utilisé par " +#~ "Debian)" + +#~ msgid " /usr/share/sgml/docbkdsl (used by SuSE)" +#~ msgstr " /usr/share/sgml/docbkdsl (utilisé par SuSE)" + +#~ msgid "" +#~ "If you have the stylesheets installed somewhere else, you need to " +#~ "configure GTK-Doc using the option: --with-dsssl-dir=<" +#~ "PATH_TO_TOPLEVEL_STYLESHEETS_DIR> " +#~ msgstr "" +#~ "Si les feuilles de styles sont installées autre part, vous devez " +#~ "configurer GTK-Doc en utilisant l'option : --with-dsssl-dir=<" +#~ "CHEMIN_VERS_REPERTOIRE_RACINE_FEUILLES2STYLEs>." + +#~ 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 " +#~ "Makefile.am:" +#~ msgstr "" +#~ "Il est aussi possible d'activer GTK-Doc pour la cible distcheck de make. " +#~ "Il faut juste ajouter la ligne suivante au fichier Makefile.am du répertoire racine :" + +#~ msgid "Enable GTK-Doc during make distcheck" +#~ msgstr "Activation de GTK-Doc pendant le « make distcheck »" + +#~ msgid "" +#~ "\n" +#~ "\n" +#~ "DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc\n" +#~ "\n" +#~ " " +#~ msgstr "" +#~ "\n" +#~ "\n" +#~ "DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc\n" +#~ "\n" +#~ " " + +#~ msgid "" +#~ "\n" +#~ "\n" +#~ "/**\n" +#~ " * identifier:\n" +#~ " *\n" +#~ " * documentation ...\n" +#~ " *\n" +#~ " * # Sub heading #\n" +#~ " *\n" +#~ " * more documentation:\n" +#~ " * - list item 1\n" +#~ " * - list item 2\n" +#~ " *\n" +#~ " * Even more docs.\n" +#~ " */\n" +#~ "\n" +#~ " " +#~ msgstr "" +#~ "\n" +#~ "\n" +#~ "/**\n" +#~ " * identifier:\n" +#~ " *\n" +#~ " * documentation ...\n" +#~ " *\n" +#~ " * # Sub heading #\n" +#~ " *\n" +#~ " * more documentation:\n" +#~ " * - list item 1\n" +#~ " * - list item 2\n" +#~ " *\n" +#~ " * Even more docs.\n" +#~ " */\n" +#~ "\n" +#~ " " + +#~ msgid "" +#~ "Since GTK-Doc-1.18 the tool supports a subset or the markdown language. One " +#~ "can use it for sub-headings and simple itemized lists. On older GTK-Doc " +#~ "versions the content will be rendered as it (the list items will appear " +#~ "in one line separated by dashes). <_:example-1/>" +#~ msgstr "" +#~ "À partir de GTK-Doc 1.18, il est possible d'utiliser un sous-ensemble de " +#~ "la syntaxe " +#~ "markdown. On peut l'utiliser pour les sous-titres et les listes à " +#~ "puces simples. Dans des versions plus anciennes de GTK-Doc, le contenu " +#~ "est affiché tel quel (les éléments d'une liste sont affichés sur une " +#~ "seule ligne, séparés par des tirets). <_:example-1/>" + +#~ msgid "(FIXME : Stability information)" +#~ msgstr "(FIXME : informations de stabilité)" + +#~ msgid "" +#~ "Also, take a look at gobject introspection annotation tags: http://live." +#~ "gnome.org/GObjectIntrospection/Annotations" +#~ msgstr "" +#~ "Jetez un coup d'œil aux étiquettes d'annotation de l'introspection " +#~ "gobject : http://live.gnome.org/GObjectIntrospection/Annotations" + #~ msgid "Chris" #~ msgstr "Chris" diff --git a/help/manual/fr/index.docbook b/help/manual/fr/index.docbook index e624249..5365f61 100644 --- a/help/manual/fr/index.docbook +++ b/help/manual/fr/index.docbook @@ -15,22 +15,11 @@ Chris Lyttle
chris@wilddev.net
Dan Mueth
d-mueth@uchicago.edu
- - Stefan - Sauer (Kost) - -
- ensonic@users.sf.net -
- - + Stefan Sauer (Kost)
ensonic@users.sf.net
Projet GTK-Doc
gtk-doc-list@gnome.org
 2000, 2005 Dan Mueth et Chris Lyttle - - 2007-2015 - Stefan Sauer (Kost) - + 2007-2015 Stefan Sauer (Kost) + + --with-html-dir=CHEMIN : répertoire d'installation de la documentation, + --enable-gtk-doc : utilisation de gtk-doc pour construire la documentation [par défaut=no], + --enable-gtk-doc-html : construction de la documentation au format html [par défaut=yes], + --enable-gtk-doc-pdf : build documentation in pdf format [default=no] + - + + GTK-Doc est désactivé par défaut ! N'oubliez pas de passer l'option lors de la prochaine exécution du script configure. Dans le cas contraire, la documentation pré-générée est installée (ce qui a du sens pour les utilisateurs mais pas pour les développeurs). + - - Intégration avec autogen + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - La plupart des projets possède un script autogen.sh pour configurer l'infrastructure de compilation après un « checkout » depuis un système de gestion de versions (comme cvs/svn/git). GTK-Doc est livré avec un outil appelé gtkdocize, qui peut être utilisé dans un script comme celui-ci. Il doit être lancé avant autoheader, automake ou autoconf. + + Intégration avec autogen - - Exécution de gtkdocize depuis autogen.sh - + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + + + + It should be run before autoreconf, autoheader, automake or autoconf. + + + + Exécution de gtkdocize depuis autogen.sh + gtkdocize || exit 1 + + + + + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi ]]> - - + + - Lorsque gtkdocize est exécuté, il copie gtk-doc.make vers le répertoire racine de votre projet (ou tout autre répertoire désigné par l'option ). Il vérifie également l'invocation de GTK_DOC_CHECK dans le script configure. Cette macro peut être utilisée pour transmettre des paramètres supplémentaires à gtkdocize. + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - Historiquement, GTK-Doc générait des fichiers prototypes dans lesquels les développeurs saisissaient la documentation. Il s'est avéré que ce n'était pas une bonne idée (comme le besoin de placer les fichiers générés dans le gestionnaire de versions). Depuis GTK-Doc 1.9, les outils peuvent récupérer toutes les informations à partir des commentaires dans les sources, ce qui permet d'éviter d'avoir des prototypes. Nous vous encourageons à conserver la documentation dans le code. gtkdocize prend maintenant en charge une option qui choisit un makefile qui s'affranchit totalement de l'utilisation des fichiers prototypes (tmpl). En plus d'ajouter les options directement au moment de l'appel de la commande, elles peuvent être ajoutées également dans une variable d'environnement appelée GTKDOCIZE_FLAGS ou choisies comme deuxième paramètre dans la macro GTK_DOC_CHECK dans le script de configuration. Si aucune modification n'a été faite à la main dans les fichiers prototypes et si vous migrez à partir d'anciennes versions de gtkdoc, supprimez le répertoire (par ex. à partir du système de gestion de versions). - + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - - Lancement de la construction de la documentation + + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + - Après toutes ces étapes, il est temps de lancer la construction. Tout d'abord, il faut relancer autogen.sh. Si ce script lance « configure » pour vous, alors il faut ajouter l'option , sinon lancez manuellement configure suivi de cette option. - La première exécution de make génère plusieurs fichiers supplémentaires dans les répertoires de documentation (doc-directories). Les plus importants sont : <paquet>.types, <paquet>-docs.xml (anciennement .sgml), <paquet>-sections.txt. - - Lancement de la construction de la documentation - + + + Executing GTK-Doc from the Build System + + Après toutes ces étapes, il est temps de lancer la construction. Tout d'abord, il faut relancer autogen.sh. Si ce script lance « configure » pour vous, alors il faut ajouter l'option , sinon lancez manuellement configure suivi de cette option. + La première exécution de make génère plusieurs fichiers supplémentaires dans les répertoires de documentation (doc-directories). Les plus importants sont : <paquet>.types, <paquet>-docs.xml (anciennement .sgml), <paquet>-sections.txt. + + Lancement de la construction de la documentation + ./autogen.sh --enable-gtk-doc make -]]> - - - Maintenant, vous pouvez saisir l'adresse docs/reference/<paquet>/index.html dans votre navigateur. Le résultat est encore un peu décevant mais le prochain chapitre va expliquer comment donner de la vie à ces pages. + + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - Intégration avec des systèmes de gestion de versions + + Integration with CMake build systems - As a rule of thumb, it's the files you edit which should go under - version control. For typical projects it's these files: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt, - Makefile.am. - - - Files in the xml/ and html/ - directories should not go under version control. Neither should any of - the .stamp files. + GTK-Doc now provides a GtkDocConfig.cmake module + (and the corresponding GtkDocConfigVersion.cmake + module). This provides a gtk_doc_add_module + command that you can set in your CMakeLists.txt + file. + + L'exemple suivant montre comment utiliser cette commande. Exemple d'utilisation de GTK-Doc depuis CMake + +find_package(GtkDoc 1.25 REQUIRED) + +# Create the doc-libmeep target. +gtk_doc_add_module( + libmeep ${CMAKE_SOURCE_DIR}/libmeep + XML meep-docs.xml + LIBRARIES libmeep +) + +# Build doc-libmeep as part of the default target. Without this, you would +# have to explicitly run something like `make doc-libmeep` to build the docs. +add_custom_target(documentation ALL DEPENDS doc-libmeep) + +# Install the docs. (This assumes you're using the GNUInstallDirs CMake module +# to set the CMAKE_INSTALL_DOCDIR variable correctly). +install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html + DESTINATION ${CMAKE_INSTALL_DOCDIR}) + + - + Intégration avec des « makefiles » simples et d'autres systèmes de compilation Dans les cas où l'emploi de automake n'est pas souhaité et donc sans fichier gtk-doc.mak, il s'agit alors d'appeler les outils gtkdoc dans le bon ordre dans les fichiers « makefiles » ad hoc (ou d'autres systèmes). Étapes de construction de la documentation - DOC_MODULE=meep // sources have changed -gtkdoc-scan --module=$(DOC_MODULE) +gtkdoc-scan --module=$(DOC_MODULE) <source-dir> gtkdoc-scangobj --module=$(DOC_MODULE) -gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir= +gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir> // xml files have changed mkdir html -cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml +cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html -]]> + Il s'agit d'examiner les fichiers Makefile.am et gtk-doc.mak pour y trouver les options supplémentaires nécessaires. - - Integration with CMake build systems - - - GTK-Doc now provides a GtkDocConfig.cmake module - (and the corresponding GtkDocConfigVersion.cmake - module). This provides a gtk_doc_add_module - command that you can set in your CMakeLists.txt - file. - - - - The following example shows how to use this command. - Example of using GTK-Doc from CMake - + Intégration avec des systèmes de gestion de versions -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + + As a rule of thumb, it's the files you edit which should go under + version control. For typical projects it's these files: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt, + Makefile.am. + + + Files in the xml/ and html/ + directories should not go under version control. Neither should any of + the .stamp files. + + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - - @@ -536,16 +855,10 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html GTK-Doc utilise les commentaires du code source, avec une syntaxe spéciale pour la documentation du code. En outre, il récupère des informations sur la structure de votre projet à partir d'autres sources. La section suivante vous donne toutes les informations concernant la syntaxe des commentaires. - - Emplacement de la documentation - Par le passé, la plupart de la documentation devait être placé dans des fichiers dans le répertoire tmpl. Les inconvénients étaient que l'information n'était pas souvent mise à jour et que ces fichiers avaient tendance à provoquer des conflits avec les systèmes de gestion de versions. - Pour éviter ces problèmes, il est conseillé de placer la documentation dans le code source. Ce manuel ne décrit que cette manière de documenter du code. - - - The scanner can handle the majority of C headers fine. In the case of - receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + The GTK-Doc scanner can handle the majority of C headers fine. In the + case of receiving warnings from the scanner that look like a special + case, one can hint GTK-Doc to skip over them. GTK-Doc comment block Commentaires de documentation Un commentaire multi-ligne qui commence avec un symbole « * » supplémentaire indique un bloc de documentation qui sera traité par les outils GTK-Doc. Bloc de commentaire GTK-Doc - /** * identifier: * documentation ... */ -]]> + L'« identifier » (identifiant) est une ligne contenant le nom de l'élément avec lequel le commentaire est lié. La syntaxe diffère légèrement en fonction de l'élément. (À FAIRE : ajouter un tableau montrant les identifiants) @@ -710,7 +1023,17 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - Comme indiqué plus tôt, GTK-Doc est fait pour documenter les API publiques. On ne peut donc pas écrire de la documentation pour les symboles statiques. Néanmoins, il est bon de commenter ces symboles aussi. Cela aide les autres à comprendre votre code. Par conséquent, nous recommandons de les documenter à l'aide de commentaires normaux (sans le second « * » à la première ligne). Si, plus tard, la fonction doit être rendue publique, il suffira juste d'ajouter un « * » dans le bloc de commentaires et d'ajouter le nom du symbole à la bonne place à l'intérieur du fichier des sections. + + 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. + @@ -721,7 +1044,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Bloc de commentaires de section - /** * SECTION:meepapp * @short_description: the application class @@ -734,7 +1057,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html * * The application class handles ... */ -]]> + @@ -910,7 +1233,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Étiquettes générales - /** * foo_get_bar: * @foo: some foo @@ -926,7 +1249,7 @@ Bar * foo_get_bar(Foo *foo) { ... -]]> + @@ -969,17 +1292,17 @@ foo_get_bar(Foo *foo) d'indiquer si les objets, listes, chaînes, etc. retournés doivent être freed/unfreed/released, - d'indiquer si les paramètres peuvent être NULL et ce qui se passe dans ce cas, + d'indiquer si les paramètres peuvent être NULL et ce qui se passe dans ce cas. - de mentionner les pré-conditions et post-conditions intéressantes si nécessaire. + Mentionner les pré-conditions et post-conditions intéressantes si nécessaire. GTK-Doc considère que tous les symboles (macros, fonctions) commençant par « _ » sont privés. Ils sont traités comme des fonctions statiques. Bloc de commentaires pour les fonctions - /** * function_name: * @par1: description of parameter 1. These can extend over more than @@ -997,7 +1320,7 @@ foo_get_bar(Foo *foo) * Since: 2.2 * Deprecated: 2.18: Use other_function() instead. */ -]]> + Étiquettes de fonction @@ -1018,14 +1341,14 @@ foo_get_bar(Foo *foo) Bloc de commentaires pour les propriétés Bloc de commentaires pour les propriétés - /** * SomeWidget:some-property: * * Here you can document a property. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...); -]]> + @@ -1034,10 +1357,10 @@ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...); N'oubliez pas : - d'indiquer quand le signal est émis et s'il est émis avant ou après d'autres signaux, + Documenter lorsque le signal est émis et s'il est émis avant ou après d'autres signaux, - d'indiquer ce qu'une application peut faire dans le gestionnaire du signal. + Documenter ce qu'une application pourrait faire dans le gestionnaire du signal. @@ -1061,7 +1384,7 @@ foo_signals[FOOBARIZED] = Bloc de commentaire pour les structures Bloc de commentaire pour les structures - /** * FooWidget: * @bar: some #gboolean @@ -1073,7 +1396,7 @@ typedef struct _FooWidget { gboolean bar; } FooWidget; -]]> + Utilisez /*< private >*/ avant les champs de structures privées que vous voulez cacher. Utilisez /*< public >*/ dans le cas contraire. @@ -1090,7 +1413,7 @@ typedef struct _FooWidget { Bloc de commentaire pour les énumérations Bloc de commentaire pour les énumérations - /** * Something: * @SOMETHING_FOO: something foo @@ -1101,10 +1424,10 @@ typedef struct _FooWidget { typedef enum { SOMETHING_FOO, SOMETHING_BAR, - /*< private >*/ + /*< private >*/ SOMETHING_COUNT } Something; -]]> + Utilisez /*< private >*/ avant les valeurs d'énumérations privées que vous voulez cacher. Utilisez /*< public >*/ dans le cas contraire. @@ -1191,7 +1514,7 @@ typedef enum { Example of program documentation. - Program documentation block + Bloc de documentation programme Voici quelques balises DocBook très utiles pendant la conception de la documentation d'un code. Pour créer un lien vers une autre section dans la documentation GTK : - Hash Tables -]]> + +<link linkend="glib-Hash-Tables">Hash Tables</link> + l'élément « linkend » est l'identifiant SGML/XML de l'élément le plus haut sur la page vers laquelle vous voulez pointer. Pour la plupart des pages, c'est en général la partie (« gtk », « gdk », « glib ») suivi du titre de la page (« Hash Tables »). Pour les éléments graphiques, c'est simplement le nom de la classe. Les espaces et les caractères de soulignement sont convertis en « - » pour être conforme au SGML/XML. Pour faire référence à une fonction externe comme, par exemple, à une fonction C standard : - ... -]]> + +<function>...</function> + Pour inclure des extraits de code : - - Using a GHashTable. - + +<example> + <title>Using a GHashTable.</title> + <programlisting> ... - - -]]> + </programlisting> +</example> + ou ceci, pour des petits fragments de code qui ne nécessitent pas de titre : - - + +<informalexample> + <programlisting> ... - - -]]> + </programlisting> +</informalexample> + Pour ces derniers, GTK-Doc prend également en charge une abréviation : |[ ... ]| Pour ajouter une liste à puces : - - - + +<itemizedlist> + <listitem> + <para> ... - - - - + </para> + </listitem> + <listitem> + <para> ... - - - -]]> + </para> + </listitem> +</itemizedlist> + Pour ajouter une note de bas de page : - - + +<note> + <para> Make sure you free the data after use. - - -]]> + </para> +</note> + Pour se référer à un type : - unsigned char -]]> + +<type>unsigned char</type> + Pour se référer à une structure externe (non décrite dans la documentation GTK) : - XFontStruct -]]> + +<structname>XFontStruct</structname> + Pour se référer à un champ d'une structure : - len -]]> + +<structfield>len</structfield> + Pour se référer au nom d'une classe, il est possible d'utiliser : - GtkWidget -]]> + +<classname>GtkWidget</classname> + mais vous utiliserez probablement #GtkWidget à la place (pour créer automatiquement un lien vers la page GtkWidget - consultez les raccourcis). Pour mettre en évidence un texte : - This is important -]]> + +<emphasis>This is important</emphasis> + Pour les noms de fichiers : - /home/user/documents -]]> + +<filename>/home/user/documents</filename> + Pour se référer à des touches : - ControlL -]]> + +<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo> + @@ -1331,7 +1654,7 @@ int main(int argc, char *argv[]) Il y a plusieurs fichiers supplémentaires, qui ont besoin d'être maintenus en parallèle aux commentaires dans le code source : <package>.types, <package>-docs.xml (anciennement .sgml), <package>-sections.txt. - Édition du fichier « types » + Édition des fichiers types If your library or application includes GObjects, you want @@ -1342,15 +1665,15 @@ int main(int argc, char *argv[]) - Extrait d'un exemple de fichier « types » - + Example <package>.types file + +#include <gtk/gtk.h> gtk_accel_label_get_type gtk_adjustment_get_type gtk_alignment_get_type gtk_arrow_get_type -]]> + @@ -1380,19 +1703,19 @@ gtk_arrow_get_type En-tête du document maître - - MODULENAME Reference Manual - + +<bookinfo> + <title>MODULENAME Reference Manual</title> + <releaseinfo> for MODULENAME [VERSION] The latest version of this documentation can be found on-line at - http://[SERVER]/MODULENAME/. - - + <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>. + </releaseinfo> +</bookinfo> - - [Insert title here] -]]> +<chapter> + <title>[Insert title here]</title> + @@ -1402,7 +1725,7 @@ gtk_arrow_get_type - Optional part in the master document + Partie optionnelle dans le document maître @@ -1420,12 +1743,12 @@ gtk_arrow_get_type Including generated sections - - my library - + + <chapter> + <title>my library</title> + <xi:include href="xml/object.xml"/> ... -]]> + @@ -1451,20 +1774,20 @@ gtk_arrow_get_type Including generated sections - libmeep/meep.h + +<INCLUDE>libmeep/meep.h</INCLUDE> -
-meepapp -MeepApp +<SECTION> +<FILE>meepapp</FILE> +<TITLE>MeepApp</TITLE> MeepApp - +<SUBSECTION Standard> MEEP_APP ... MeepAppClass meep_app_get_type -
-]]> +</SECTION> + @@ -1546,7 +1869,7 @@ meep_app_get_type - Modernizing the documentation + Modernisation de la documentation GTK-Doc has been around for quite some time. In this section we list new @@ -1554,7 +1877,7 @@ meep_app_get_type - GTK-Doc 1.9 + Manuel de GTK-Doc 1.9 When using xml instead of sgml, one can actually name the master @@ -1584,7 +1907,7 @@ meep_app_get_type - GTK-Doc 1.10 + Manuel de GTK-Doc 1.10 This version supports in @@ -1597,7 +1920,7 @@ meep_app_get_type - GTK-Doc 1.16 + Manuel de GTK-Doc 1.16 This version includes a new tool called gtkdoc-check. This tool can run @@ -1617,7 +1940,7 @@ endif - GTK-Doc 1.20 + Manuel de GTK-Doc 1.20 Version 1.18 brought some initial markdown support. Using markdown in @@ -1629,14 +1952,15 @@ endif - GTK-Doc 1.25 + Manuel de GTK-Doc 1.25 The makefiles shipped with this version generate an entity file at xml/gtkdocentities.ent, containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included - and how the entities are used. The entities can also be used in all + in the master template and how the entities are used. + The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities @@ -1685,7 +2009,7 @@ endif Contrôles « configure » supplémentaires - AC_ARG_ENABLE(man, [AC_HELP_STRING([--enable-man], [regenerate man pages from Docbook [default=no]])],enable_man=yes, @@ -1693,7 +2017,7 @@ AC_ARG_ENABLE(man, AC_PATH_PROG([XSLTPROC], [xsltproc]) AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno) -]]> + @@ -1703,7 +2027,7 @@ AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno) Contrôles « configure » supplémentaires - man_MANS = \ meeper.1 @@ -1711,14 +2035,14 @@ if ENABLE_GTK_DOC if ENABLE_MAN %.1 : %.xml - @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< + @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< endif endif BUILT_EXTRA_DIST = $(man_MANS) EXTRA_DIST += meep.xml -]]> + @@ -1737,8 +2061,8 @@ EXTRA_DIST += meep.xml - Question  - Réponse  + Question + Réponse Pas de hiérarchie de classe. Les fonctions objet xxx_get_type() n'ont pas été saisies dans le fichier <module>.types. @@ -1791,7 +2115,7 @@ EXTRA_DIST += meep.xml « ID » multiples pour le linkend: XYZ contraint - Le symbole XYZ apparaît en double dans le fichier <module>-sections.txt. + Le symbole XYZ apparaît en double dans le fichier <package>-sections.txt. Élément typename dans l'espace de nom '' rencontré dans para mais aucun prototype ne correspond. @@ -1803,11 +2127,7 @@ EXTRA_DIST += meep.xml Outils liés à gtk-doc - - GtkDocPlugin - a Trac GTK-Doc - integration plugin, that adds API docs to a trac site and integrates with - the trac search. - + GtkDocPlugin - un greffon d'intégration à Trac GTK-Doc, qui ajoute la documentation d'API à un site Trac et s'intègre à la recherche Trac. Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since tags in the API to determine the minimum required version. diff --git a/help/manual/gl/index.docbook b/help/manual/gl/index.docbook index 9903633..e77653c 100644 --- a/help/manual/gl/index.docbook +++ b/help/manual/gl/index.docbook @@ -44,6 +44,12 @@ + 1.29 + 28 Aug 2018 + ss + development + + 1.28 24 Mar 2018 ss @@ -194,8 +200,7 @@ Writing the documentation. The author fills in the source files with the documentation for each - function, macro, union etc. (In the past information was entered in - generated template files, which is not recommended anymore). + function, macro, structs or unions, etc. @@ -297,11 +302,21 @@ About GTK-Doc + 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. + + + (FIXME) - (History, authors, web pages, mailing list, license, future plans, + (authors, web pages, mailing list, license, future plans, comparison with other similar systems.) @@ -323,37 +338,94 @@ - Setting up your project + Project Setup + + + This Chapter describes the steps that are necessary to integrate GTK-Doc + into your project. The integration of GTK-Doc into a project includes the + following steps: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + - 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 plain - makefiles or other build systems will describe the basics needed to - work in a different build setup. + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. Setting up a skeleton documentation - 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 + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. - This can then look as shown below: - Example directory structure + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project - - Integration with autoconf - + + Integration with Autotools - Very easy! Just add one line to your configure.ac script. + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + + + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - Integration with autoconf - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - - 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 - GTK_DOC_CHECK at the start of a line. - Keep gtk-doc optional - + + Integration with automake + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + + +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ + - - - The first argument is used to check for the gtkdocversion at configure time. - The 2nd, optional argument is used by gtkdocize. - The GTK_DOC_CHECK macro also adds several configure switches: - - - --with-html-dir=PATH : path to installed docs - --enable-gtk-doc : use gtk-doc to build documentation [default=no] - --enable-gtk-doc-html : build documentation in html format [default=yes] - --enable-gtk-doc-pdf : build documentation in pdf format [default=no] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. + + All settings have a comment above them that describes their purpose + and how to customize the setting. - - - GTK-Doc is disabled by default! Remember to pass the option - to the next - configure run. Otherwise pregenerated documentation is installed - (which makes sense for users but not for developers). + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). + + All the tools support to list the supported + options. - - - Furthermore it is recommended that you have the following line inside - your configure.ac script. - This allows gtkdocize to automatically copy the - macro definition for GTK_DOC_CHECK to your project. - + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. - - Preparation for gtkdocize - + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + Integration with autoconf + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - - After all changes to configure.ac are made, update - the configure file. This can be done by re-running - autoreconf -i or autogen.sh. - - + + - - Integration with automake + + 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: - - First copy the Makefile.am from the - examples sub directory of the - gtkdoc-sources - to your project's API documentation directory ( - ./docs/reference/<package>). - A local copy should be available under e.g. - /usr/share/doc/gtk-doc-tools/examples/Makefile.am. - If you have multiple doc-packages repeat this for each one. - + + Integration with optional gtk-doc dependency + + + - - The next step is to edit the settings inside the Makefile.am. - 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 . - All the tools support to list the supported - parameters. - + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - + + --with-html-dir=PATH : path to installed docs + --enable-gtk-doc : use gtk-doc to build documentation [default=no] + --enable-gtk-doc-html : build documentation in html format [default=yes] + --enable-gtk-doc-pdf : build documentation in pdf format [default=no] + - + + + GTK-Doc is disabled by default! Remember to pass the option + to the next + configure run. Otherwise pregenerated documentation is installed + (which makes sense for users but not for developers). + + - - Integration with autogen + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - - Most projects will have an autogen.sh 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 - gtkdocize which can be used in such a script. - It should be run before autoheader, automake or autoconf. - + + Integration with autogen - - Running gtkdocize from autogen.sh - + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + + + + It should be run before autoreconf, autoheader, automake or autoconf. + + + + Running gtkdocize from autogen.sh + - - + + - - When running gtkdocize it copies - gtk-doc.make to your project root (or any directory - specified by the option). - It also checks you configure script for the GTK_DOC_CHECK - invocation. This macro can be used to pass extra parameters to - gtkdocize. - + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - - 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. gtkdocize supports now - a 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 GTKDOCIZE_FLAGS - or set as a 2nd parameter in GTK_DOC_CHECK 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). - - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - Running the doc build + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - - After the previous steps it's time to run the build. First we need to - rerun autogen.sh. If this script runs configure for - you, then give it the option. - Otherwise manually run configure with this option - afterwards. - - - The first make run generates several additional files in the doc-directories. - The important ones are: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt. - - - Running the doc build - + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + + After the previous steps it's time to run the build. First we need to + rerun autogen.sh. If this script runs configure + for you, then give it the option. + Otherwise manually run configure with this option + afterwards. + + + The first make run generates several additional files in the doc-directories. + The important ones are: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt. + + + Running the doc build + - - - - Now you can point your browser to docs/reference/<package>/index.html. - Yes, it's a bit disappointing still. But hang-on, during the next chapter we - tell you how to fill the pages with life. - + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - Integration with version control systems + + Integration with CMake build systems - As a rule of thumb, it's the files you edit which should go under - version control. For typical projects it's these files: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt, - Makefile.am. + GTK-Doc now provides a GtkDocConfig.cmake module + (and the corresponding GtkDocConfigVersion.cmake + module). This provides a gtk_doc_add_module + command that you can set in your CMakeLists.txt + file. + - Files in the xml/ and html/ - directories should not go under version control. Neither should any of - the .stamp files. + The following example shows how to use this command. + Example of using GTK-Doc from CMake + + - + Integration with plain makefiles or other build systems @@ -589,42 +917,24 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html - - Integration with CMake build systems - - - GTK-Doc now provides a GtkDocConfig.cmake module - (and the corresponding GtkDocConfigVersion.cmake - module). This provides a gtk_doc_add_module - command that you can set in your CMakeLists.txt - file. - - - - The following example shows how to use this command. - Example of using GTK-Doc from CMake - + Integration with version control systems -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + + As a rule of thumb, it's the files you edit which should go under + version control. For typical projects it's these files: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt, + Makefile.am. + + + Files in the xml/ and html/ + directories should not go under version control. Neither should any of + the .stamp files. + + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - - @@ -637,25 +947,10 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html syntax of the comments. - - Documentation placement - - In the past most documentation had to be filled into files residing - inside the tmpl 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. - - - The avoid the aforementioned problems we suggest putting the - documentation inside the sources. This manual will only describe this - way of documenting code. - - - - The scanner can handle the majority of C headers fine. In the case of - receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + The GTK-Doc scanner can handle the majority of C headers fine. In the + case of receiving warnings from the scanner that look like a special + case, one can hint GTK-Doc to skip over them. GTK-Doc comment block As already mentioned earlier GTK-Doc is for documenting public API. Thus one cannot write documentation for static symbols. Nevertheless it is good - to comment those symbols too. This helps other to understand you code. + to comment those symbols too. This helps other developers to understand + your code. Therefore we recommend to comment these using normal comments (without the 2nd '*' in the first line). If later the function needs to be made public, all one needs to do is to @@ -1645,7 +1941,7 @@ int main(int argc, char *argv[]) - Example types file snippet + Example <package>.types file @@ -2002,7 +2298,8 @@ endif containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included - and how the entities are used. The entities can also be used in all + in the master template and how the entities are used. + The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities diff --git a/help/manual/gu/index.docbook b/help/manual/gu/index.docbook index 22c0156..176f3b9 100644 --- a/help/manual/gu/index.docbook +++ b/help/manual/gu/index.docbook @@ -68,6 +68,12 @@ + 1.29 + 28 Aug 2018 + ss + development + + 1.28 24 Mar 2018 ss @@ -207,7 +213,12 @@ - દસ્તાવેજીકરણને લખી રહ્યા છે. લેખક એ દરેક વિધેયને, મેક્રો, યુનિયન વગેરે માટે દસ્તાવેજીકરણ સાથે સ્ત્રોત ફાઇલોમાં ભરે છે. (ઉત્પન્ન થયેલ ટેમ્પલેટ ફાઇલમાં ભૂતકાળની જાણકારી દાખલ થયેલ હતી, કે જે કોઇપણ રીતે અગ્રહણીય થયેલ નથી) + + Writing the documentation. + + The author fills in the source files with the documentation for each + function, macro, structs or unions, etc. + @@ -307,10 +318,20 @@ GTK-Doc વિશે + + 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. + + (FIXME) - (History, authors, web pages, mailing list, license, future plans, + (authors, web pages, mailing list, license, future plans, comparison with other similar systems.) @@ -330,37 +351,94 @@ - તમારા પ્રોજેક્ટને સુયોજિત કરી રહ્યા છે + Project Setup - 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 plain - makefiles or other build systems will describe the basics needed to - work in a different build setup. + This Chapter describes the steps that are necessary to integrate GTK-Doc + into your project. The integration of GTK-Doc into a project includes the + following steps: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + + + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. સ્કેલેટન દસ્તાવેજીકરણને સુયોજિત કરી રહ્યા છે - 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 + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. - This can then look as shown below: - Example directory structure + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project - - autoconf સાથે એકત્રિકરણ + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + - ઘણું સરળ છે! ફક્ત તમારી configure.ac સ્ક્રિપ્ટમાં એક વાક્ય ને ઉમેરો. + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - autoconf સાથે એકત્રિકરણ - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - - 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 - GTK_DOC_CHECK at the start of a line. - Keep gtk-doc optional - + + automake સાથે એકત્રિકરણ + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + + +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ + - - પહેલી દલીલ રૂપરેખાંકિત સમયે gtkdocversion માટે ચકાસવા વપરાયેલ છે. બીજી, વૈકલ્પિક દલીલ એ gtkdocize દ્દારા વપરાયેલ છે. GTK_DOC_CHECK મેક્રો પણ ઘણીબધા રૂપરેખાંકિત ફેરબદલોને ઉમેરે છે: - - --with-html-dir=PATH : સ્થાપિત થયેલ દસ્તાવેજોનો પાથ - --enable-gtk-doc : દસ્તાવેજીકરણ ને બિલ્ડ કરવા માટે gtk-doc ને વાપરો [default=no] - --enable-gtk-doc-html : html બંધારણમાં દસ્તાવેજીકરણ બિલ્ડ કરો [default=yes] - --enable-gtk-doc-pdf : pdf બંધારણમાં દસ્તાવેજીકરણને બિલ્ડ કરો [default=no] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. - - GTK-Doc એ મૂળભૂત રીતે નિષ્ક્રિય થયેલ છે! આગળનાં configure ને ચલાવવા માટે ને પસાર કરવાનું યાદ રાખો. નહિં તો પહેલીથી ઉત્પન્ન થયેલ દસ્તાવેજીકરણ સ્થાપિત થયેલ છે (કે જે વપરાશકર્તાઓ માટેનો અર્થ બને છે પરંતુ ડેવલપરો માટે નહિં). - + All settings have a comment above them that describes their purpose + and how to customize the setting. - - Furthermore it is recommended that you have the following line inside - your configure.ac script. - This allows gtkdocize to automatically copy the - macro definition for GTK_DOC_CHECK to your project. - + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). - - gtkdocize માટે તૈયારી - --help to list the supported + options. + + + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. + + + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + autoconf સાથે એકત્રિકરણ + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - - After all changes to configure.ac are made, update - the configure file. This can be done by re-running - autoreconf -i or autogen.sh. - - + + - - automake સાથે એકત્રિકરણ + + 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: - - First copy the Makefile.am from the - examples sub directory of the - gtkdoc-sources - to your project's API documentation directory ( - ./docs/reference/<package>). - A local copy should be available under e.g. - /usr/share/doc/gtk-doc-tools/examples/Makefile.am. - If you have multiple doc-packages repeat this for each one. - + + Integration with optional gtk-doc dependency + + + - - The next step is to edit the settings inside the Makefile.am. - 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 . - All the tools support to list the supported - parameters. - + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - + + --with-html-dir=PATH : સ્થાપિત થયેલ દસ્તાવેજોનો પાથ + --enable-gtk-doc : દસ્તાવેજીકરણ ને બિલ્ડ કરવા માટે gtk-doc ને વાપરો [default=no] + --enable-gtk-doc-html : html બંધારણમાં દસ્તાવેજીકરણ બિલ્ડ કરો [default=yes] + --enable-gtk-doc-pdf : pdf બંધારણમાં દસ્તાવેજીકરણને બિલ્ડ કરો [default=no] + - + + GTK-Doc એ મૂળભૂત રીતે નિષ્ક્રિય થયેલ છે! આગળનાં configure ને ચલાવવા માટે ને પસાર કરવાનું યાદ રાખો. નહિં તો પહેલીથી ઉત્પન્ન થયેલ દસ્તાવેજીકરણ સ્થાપિત થયેલ છે (કે જે વપરાશકર્તાઓ માટેનો અર્થ બને છે પરંતુ ડેવલપરો માટે નહિં). + - - autogen સાથે એકત્રિકરણ + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - મોટાભાગનાં પ્રોજેક્ટો પાસે આવૃત્તિ નિયંત્રણ સિસ્ટમ (જેવી કે cvs/svn/git) માંથી ચેકઆઉટ પછી ઇન્ફ્રાસ્ટ્રક્ચરને બિલ્ડ કરવાનું સુયોજિત કરવા માટે autogen.sh સ્ક્રિપ્ટ હશે. GTK-Doc એ સાધન gtkdocize તરીકે કહેવાતા સાધન સાથે આવે છે કે જે આવી સ્ક્રિપ્ટમાં વાપરી શકાય છે. તે autoheader, automake અથવા autoconf પહેલાં ચાલવુ જોઇએ. + + autogen સાથે એકત્રિકરણ - - autogen.sh માંથી gtkdocize ને ચલાવી રહ્યા છે - + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + + + + It should be run before autoreconf, autoheader, automake or autoconf. + + + + autogen.sh માંથી gtkdocize ને ચલાવી રહ્યા છે + - - + + - - When running gtkdocize it copies - gtk-doc.make to your project root (or any directory - specified by the option). - It also checks you configure script for the GTK_DOC_CHECK - invocation. This macro can be used to pass extra parameters to - gtkdocize. - + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - - 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. gtkdocize supports now - a 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 GTKDOCIZE_FLAGS - or set as a 2nd parameter in GTK_DOC_CHECK 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). - - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + + + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - - દસ્તાવેજ બિલ્ડને ચલાવી રહ્યા છે + + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + - પહેલાનાં પગલાઓ પછી બિલ્ડ ને ચલાવવા માટે સમય થઇ ગયો છે. પહેલાં આપણે autogen.sh પુન:ચલાવવાની જરૂર છે. નહિં તો પછીથી આ વિકલ્પ સાથે configure ને જાતે જ ચલાવો. - - The first make run generates several additional files in the doc-directories. - The important ones are: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt. - - - દસ્તાવેજ બિલ્ડને ચલાવી રહ્યા છે - + + + Executing GTK-Doc from the Build System + + પહેલાનાં પગલાઓ પછી બિલ્ડ ને ચલાવવા માટે સમય થઇ ગયો છે. પહેલાં આપણે autogen.sh પુન:ચલાવવાની જરૂર છે. નહિં તો પછીથી આ વિકલ્પ સાથે configure ને જાતે જ ચલાવો. + + The first make run generates several additional files in the doc-directories. + The important ones are: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt. + + + દસ્તાવેજ બિલ્ડને ચલાવી રહ્યા છે + - - - હવે તમે docs/reference/<package>/index.html માટે તમારા બ્રાઉઝર પર આંગળી ચીંધી શકો છો. હાં, તે થોડુ હજુ નિરાશ કરે તેવુ છે. પરંતુ આગળનામ વિષય માટે આપણે તને કહીએ છે કે જીદંગી સાથે પાનાંઓને કેવી રીતે ભરવા તે દરમ્યાન થોડા સમય માટે અટકી જાય છે + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - આવૃત્તિ નિયંત્રણ સિસ્ટમો સાથે એકત્રિકરણ + + Integration with CMake build systems - As a rule of thumb, it's the files you edit which should go under - version control. For typical projects it's these files: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt, - Makefile.am. + GTK-Doc now provides a GtkDocConfig.cmake module + (and the corresponding GtkDocConfigVersion.cmake + module). This provides a gtk_doc_add_module + command that you can set in your CMakeLists.txt + file. + - Files in the xml/ and html/ - directories should not go under version control. Neither should any of - the .stamp files. + The following example shows how to use this command. + Example of using GTK-Doc from CMake + + - + Integration with plain makefiles or other build systems @@ -569,42 +919,24 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html - - Integration with CMake build systems - - - GTK-Doc now provides a GtkDocConfig.cmake module - (and the corresponding GtkDocConfigVersion.cmake - module). This provides a gtk_doc_add_module - command that you can set in your CMakeLists.txt - file. - - - - The following example shows how to use this command. - Example of using GTK-Doc from CMake - + આવૃત્તિ નિયંત્રણ સિસ્ટમો સાથે એકત્રિકરણ -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + + As a rule of thumb, it's the files you edit which should go under + version control. For typical projects it's these files: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt, + Makefile.am. + + + Files in the xml/ and html/ + directories should not go under version control. Neither should any of + the .stamp files. + + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - - @@ -617,25 +949,10 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html syntax of the comments. - - દસ્તાવેજીકરણ નિયુક્તિ - - In the past most documentation had to be filled into files residing - inside the tmpl 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. - - - The avoid the aforementioned problems we suggest putting the - documentation inside the sources. This manual will only describe this - way of documenting code. - - - - The scanner can handle the majority of C headers fine. In the case of - receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + The GTK-Doc scanner can handle the majority of C headers fine. In the + case of receiving warnings from the scanner that look like a special + case, one can hint GTK-Doc to skip over them. GTK-Doc comment block - પહેલાનાં GTK-Doc માં પહેલેથી જણાવેલ પ્રમાણે સાર્વજનિક API દસ્તાવેજીકરણ માટે છે. છતાં એક એ સ્થિર સંકેતો માટે દસ્તાવેજીકરણ ને લખી શકતુ નથી. તેમ છતાં તે પેલાં સંકેતો પર ટિપ્પણી કરવા માટે સારુ છે. આ તમારાં કોડને સમજવા માટે બીજાને મદદ કરે છે. માટે આપણે સામાન્ય ટિપ્પણીઓની મદદથી આ ટિપ્પણી એ અગ્રહણીય કરેલ છે (પહેલાં વાક્યમાં બીજા '*' વગર). જો પછી વિધેયને સાર્વજનિક બનાવવાની જરૂર છે, ટિપ્પણી બ્લોકમાં બીજા '*' ઉમેરવા માટે બધાને કરવાની જરૂર છે અને ફાઇલ વિભાગોની અંદર જમણી જગ્યા પર સંકેત નામને દાખલ કરો. + + 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. + @@ -1586,7 +1913,7 @@ int main(int argc, char *argv[]) - Example types file snippet + Example <package>.types file @@ -1925,7 +2252,8 @@ endif containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included - and how the entities are used. The entities can also be used in all + in the master template and how the entities are used. + The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities diff --git a/help/manual/pt_BR/index.docbook b/help/manual/pt_BR/index.docbook index c20227c..ddee6e8 100644 --- a/help/manual/pt_BR/index.docbook +++ b/help/manual/pt_BR/index.docbook @@ -35,11 +35,12 @@ - 1.28 - 24 Mar 2018 + 1.29 + 28 Aug 2018 ss - bug fixes + development + 1.28 24 Mar 2018 ss correçãoõesão de erros 1.27 07 Maio 2017 ss ajustes do porte para Python 1.26 11 Ago 2017 ss portadas todas ferramentas de perl/bash para Python 1.25 21 Mar 2016 ss correção de erros, limpezas de testes @@ -112,7 +113,12 @@ - Escrevendo a documentação. 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). + + Writing the documentation. + + The author fills in the source files with the documentation for each + function, macro, structs or unions, etc. + @@ -149,9 +155,22 @@ Sobre GTK-Doc + + 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. + + (CORRIJA-ME) - (História, autores, páginas web, lista de discussão, licença, planos futuros, comparação com outros sistemas similares.) + + (authors, web pages, mailing list, license, future plans, + comparison with other similar systems.) + @@ -167,131 +186,530 @@ - Preparando seu projeto + Project Setup - 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 makefiles simples ou outros sistemas de compilação vai descrever as necessidades básicas para trabalhar em uma configuração de compilação diferente. + + 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: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + + + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. + Preparando o esqueleto de uma documentação - 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. + + A common convention is to place documentation into a folder called + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. + - Isto pode, então, parecer como exibido abaixo: Exemplo de estrutura de diretórios - + + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project + - +]]> + + - - Integração com autoconf - - Muito fácil! Basta adicionar uma linha ao seu script configure.ac. + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + + + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - Integração com autoconf - -# verifica por gtk-doc -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - 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 GTK_DOC_CHECK no começo de uma linha. Mantenha o gtk-doc como opcional + + Integração com automake + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + -# verifica por gtk-doc -m4_ifdef([GTK_DOC_CHECK], [ -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) -],[ -AM_CONDITIONAL([ENABLE_GTK_DOC], false) -]) +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ - + - O primeiro argumento é usado para verificar a gtkdocversion em tempo de compilação. O segundo argumento é opcional, sendo usado por gtkdocize. A macro GTK_DOC_CHECK também adiciona várias opções de configuração: - - --with-html-dir=CAMINHO : caminho para as documentações instaladas - --enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=no] - --enable-gtk-doc-html : compila documentação em formato html [padrão=sim] - --enable-gtk-doc-pdf : compila documentação em formato pdf [padrão=não] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. - - GTK-Doc está desabilitado por padrão! Lembre-se de passar a opção à próxima execução do configure. Do contrário, uma documentação gerada previamente é instalada (o que faz sentido para usuários, mas não para desenvolvedores). - + All settings have a comment above them that describes their purpose + and how to customize the setting. - Além disso, é recomendado que você tenha a seguinte linha dentro do seu script configure.ac. Ela permite que gtkdocize copie automaticamente a definição de macro para GTK_DOC_CHECK para o seu projeto. + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). - - Preparação para gtkdocize - + All the tools support to list the supported + options. + + + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. + + + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + Integração com autoconf + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - Após todas as alterações do configure.ac serem feitas, atualize o arquivo configure. Isso pode ser feito executando novamente autoreconf -i ou autogen.sh. - +# optional: register gtk-doc in configure +GTK_DOC_CHECK([1.28]) +]]> + + + + + 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: + + + Integration with optional gtk-doc dependency + + + - - Integração com automake + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - Primeiro copie o Makefile.am dos subdiretório do exemplo do gtkdoc-sources para o diretório de documentação da API do seu projeto ( ./docs/reference/<pacote>). Uma cópia local deveria estar disponível sob, por exemplo, /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Se você tiver múltiplos pacotes de documentação, repita isso para cada um. + + --with-html-dir=CAMINHO : caminho para as documentações instaladas + --enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=no] + --enable-gtk-doc-html : compila documentação em formato html [padrão=sim] + --enable-gtk-doc-pdf : compila documentação em formato pdf [padrão=não] + - A próxima etapa é editar as configurações dentro do Makefile.am. 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 . Todas as ferramentas têm suporte a pra listar os parâmetros disponíveis. + + GTK-Doc está desabilitado por padrão! Lembre-se de passar a opção à próxima execução do configure. Do contrário, uma documentação gerada previamente é instalada (o que faz sentido para usuários, mas não para desenvolvedores). + - + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - + + Integração com autogen - - Integração com autogen + + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + - A maioria dos projetos têm um script autogen.sh 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 gtkdocize que pode ser usada em um script assim. O gtkdocize deveria ser executado antes de autoheader, automake ou autoconf. + + It should be run before autoreconf, autoheader, automake or autoconf. + - - Executando gtkdocize no autogen.sh - + + Executando gtkdocize no autogen.sh + gtkdocize || exit 1 - - + + - Ao executar gtkdocize, ele copia gtk-doc.make para a raiz do seu projeto (ou qualquer diretório especificado pela opção ). Ele também verifica se seu script de configuração pela chamada de GTK_DOC_CHECK. Esta macro pode ser usada para passar parâmetros extras para gtkdocize. + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - 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 gtkdocize possui agora suporte à opção 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 GTKDOCIZE_FLAGS ou definidas como um segundo parâmetro na macro GTK_DOC_CHECK 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). - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + + + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + + + + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + - - Executando a compilação da documentação + - Após as etapas anteriores, é hora de executar a compilação. Primeiro, nós queremos executar novamente o autogen.sh. Se este script executa o configure para você, então forneça a este a opção . Do contrário, execute manualmente configure com esta opção em seguida. - A primeira execução do make cria vários arquivos adicionais nos diretórios de documentação. Os importantes são: <pacote>.types, <pacote>-docs.xml (no passado, .sgml), <pacote>-sections.txt. - - Executando a compilação da documentação - + + Executing GTK-Doc from the Build System + + Após as etapas anteriores, é hora de executar a compilação. Primeiro, nós queremos executar novamente o autogen.sh. Se este script executa o configure para você, então forneça a este a opção . Do contrário, execute manualmente configure com esta opção em seguida. + A primeira execução do make cria vários arquivos adicionais nos diretórios de documentação. Os importantes são: <pacote>.types, <pacote>-docs.xml (no passado, .sgml), <pacote>-sections.txt. + + Executando a compilação da documentação + ./autogen.sh --enable-gtk-doc make - - - Agora você pode apontar seu navegador para docs/reference/<pacote>/index.html. 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. + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - Integração com sistemas de controle de versão + + Integração com sistemas de compilação CMake - 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: <pacote>.types, <pacote>-docs.xml (no passado, .sgml), <pacote>-sections.txt, Makefile.am. - Arquivos nos diretórios xml/ e html/ não deveriam entrar no controle de versão. Da mesma forma, não deveriam entrar arquivos .stamp. + GTK-Doc agora fornece um módulo GtkDocConfig.cmake (e o module GtkDocConfigVersion.cmake correspondente). Ele fornece um comando gtk_doc_add_module que você pode usar em seu arquivo CMakeLists.txt. + + O exemplo a seguir mostra como usar este comando. Exemplo de uso do GTK-Doc no CMake + +find_package(GtkDoc 1.25 REQUIRED) + +# Cria o alvo doc-libmeep. +gtk_doc_add_module( + libmeep ${CMAKE_SOURCE_DIR}/libmeep + XML meep-docs.xml + LIBRARIES libmeep +) + +# Compila doc-libmeep como parte do alvo padrão. Sem isso, você precisaria +# executar explicitamente algo como `make doc-libmeep` para compilar os +# documentos. +add_custom_target(documentation ALL DEPENDS doc-libmeep) + +# Install the docs. (This assumes you're using the GNUInstallDirs CMake module +# to set the CMAKE_INSTALL_DOCDIR variable correctly). +install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html + DESTINATION ${CMAKE_INSTALL_DOCDIR}) + + - + Integração com makefiles simples ou outros sistemas de compilação Neste caso, não se deseja usar o automake e, portanto, gtk-doc.mak. Será necessário chamar as ferramentas do gtkdoc na ordem correta nos makefiles devidos (ou outras ferramentas de compilação). @@ -315,34 +733,13 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html Será necessário olhar no Makefile.am e no gtk-doc.mak para obter as opções extras necessárias. - - Integração com sistemas de compilação CMake - - GTK-Doc agora fornece um módulo GtkDocConfig.cmake (e o module GtkDocConfigVersion.cmake correspondente). Ele fornece um comando gtk_doc_add_module que você pode usar em seu arquivo CMakeLists.txt. - - O exemplo a seguir mostra como usar este comando. Exemplo de uso do GTK-Doc no CMake - -find_package(GtkDoc 1.25 REQUIRED) - -# Cria o alvo doc-libmeep. -gtk_doc_add_module( - libmeep ${CMAKE_SOURCE_DIR}/libmeep - XML meep-docs.xml - LIBRARIES libmeep -) + + Integração com sistemas de controle de versão -# Compila doc-libmeep como parte do alvo padrão. Sem isso, você precisaria -# executar explicitamente algo como `make doc-libmeep` para compilar os -# documentos. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + 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: <pacote>.types, <pacote>-docs.xml (no passado, .sgml), <pacote>-sections.txt, Makefile.am. + Arquivos nos diretórios xml/ e html/ não deveriam entrar no controle de versão. Da mesma forma, não deveriam entrar arquivos .stamp. + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) - - - @@ -350,19 +747,18 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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. - - Localização da documentação - Antigamente, a maioria das documentações tinha que ser preenchida em arquivos residentes dentro do diretório tmpl. Isso tem as desvantagens das informações frequentemente não serem atualizadas e também que o arquivo tende a causar conflitos com sistemas de controle de versão. - Para 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. - - - 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. Bloco de comentário do GTK-Doc - + + 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. + GTK-Doc comment block + - +]]> + + Limitações @@ -476,7 +872,17 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Mais exemplos do quais tags de markdown tags tem suporte pode ser encontrado na Referência de sintaxe de markdown de documentação. - 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. + + 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. + @@ -1017,7 +1423,7 @@ int main(int argc, char *argv[]) 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 xxx_get_type junto com seus include dentro do arquivo <pacote>.types. - Trecho de exemplo de arquivo de tipos + Example <package>.types file #include <gtk/gtk.h> @@ -1198,27 +1604,37 @@ endif GTK-Doc 1.25 - Os makefiles fornecidos com esta versão geram um arquivo de entidade em xml/gtkdocentities.ent, 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. Usando entradas geradas previamente - -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + + The makefiles shipped with this version generate an entity file at xml/gtkdocentities.ent, + 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. + Use pre-generated entities + + + %gtkdocentities; -]> -<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> - <bookinfo> - <title>Manual de referência do &nome-pacote;</title> - <releaseinfo> - para &versão-pacote;. - A última versão desta documentação pode ser encontra on-line em - <ulink role="online-location" url="http://[SERVIDOR]/&nome-pacote;/index.html">http://[SERVIDOR]/&nome-pacote;/</ulink>. - </releaseinfo> - </bookinfo> - - +]> + + + &package_name; Reference Manual + + for &package_string;. + The latest version of this documentation can be found on-line at + http://[SERVER]/&package_name;/. + + +]]> + + diff --git a/help/manual/pt_BR/pt_BR.po b/help/manual/pt_BR/pt_BR.po index f8b7167..7ad38fd 100644 --- a/help/manual/pt_BR/pt_BR.po +++ b/help/manual/pt_BR/pt_BR.po @@ -8,8 +8,8 @@ msgstr "" "Project-Id-Version: gtk-doc help\n" "Report-Msgid-Bugs-To: http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-" "doc&keywords=I18N+L10N&component=general\n" -"POT-Creation-Date: 2017-12-28 10:31+0000\n" -"PO-Revision-Date: 2018-01-23 11:16-0200\n" +"POT-Creation-Date: 2018-03-24 15:17+0000\n" +"PO-Revision-Date: 2018-03-28 23:03-0200\n" "Last-Translator: Rafael Fontenelle \n" "Language-Team: Brazilian Portuguese \n" "Language: pt_BR\n" @@ -126,48 +126,59 @@ msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:83 #| msgid "" -#| "1.26.1 11 Aug 2017 " +#| "1.27.1 07 Dec 2017 " #| "ss development" msgid "" -"1.27.1 07 Dec 2017 ss1.28.1 24 Mar 2018 ss development" msgstr "" -"1.27.1 07 Dez 2017 " +"1.28.1 24 Mar 2018 " "ss desenvolvimento" #. (itstool) path: revhistory/revision #: C/index.docbook:89 +#| msgid "" +#| "1.24 29 May 2015 ss bug fix" +msgid "" +"1.28 24 Mar 2018 ss bug fixes" +msgstr "" +"1.28 24 Mar 2018 " +"ss correçãoõesão de " +"erros" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:95 msgid "" "1.27 07 Dec 2017 ss fine tuning of the python port" msgstr "" -"1.27 07 Maio 2017 " -"ss ajustes do porte para " -"Python" +"1.27 07 Maio 2017 ss ajustes do porte para Python" #. (itstool) path: revhistory/revision -#: C/index.docbook:95 +#: C/index.docbook:101 msgid "" "1.26 11 Aug 2017 ss port all tools from perl/bash to python" msgstr "" -"1.26 11 Ago 2017 " -"ss portadas todas ferramentas de " -"perl/bash para Python" +"1.26 11 Ago 2017 ss portadas todas ferramentas de perl/bash para " +"Python" #. (itstool) path: revhistory/revision -#: C/index.docbook:101 +#: C/index.docbook:107 msgid "" "1.25 21 March 2016 ss bug fixes, test cleanups" msgstr "" -"1.25 21 Mar 2016 " -"ss correção de erros, limpezas " -"de testes" +"1.25 21 Mar 2016 ss correção de erros, limpezas de testes" #. (itstool) path: revhistory/revision -#: C/index.docbook:107 +#: C/index.docbook:113 msgid "" "1.24 29 May 2015 ss bug fix" @@ -176,7 +187,7 @@ msgstr "" "authorinitials> correção de erros" #. (itstool) path: revhistory/revision -#: C/index.docbook:113 +#: C/index.docbook:119 msgid "" "1.23 17 May 2015 ss bug fix" @@ -185,7 +196,7 @@ msgstr "" "authorinitials> correção de erros" #. (itstool) path: revhistory/revision -#: C/index.docbook:119 +#: C/index.docbook:125 msgid "" "1.22 07 May 2015 ss bug fixes, dropping deprecated features" #. (itstool) path: revhistory/revision -#: C/index.docbook:125 +#: C/index.docbook:131 msgid "" "1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" #. (itstool) path: revhistory/revision -#: C/index.docbook:131 +#: C/index.docbook:137 msgid "" "1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" #. (itstool) path: revhistory/revision -#: C/index.docbook:137 +#: C/index.docbook:143 msgid "" "1.19 05 Jun 2013 ss bug fixes" @@ -227,7 +238,7 @@ msgstr "" "authorinitials> correção de erros" #. (itstool) path: revhistory/revision -#: C/index.docbook:143 +#: C/index.docbook:149 msgid "" "1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" @@ -237,7 +248,7 @@ msgstr "" "markdown" #. (itstool) path: revhistory/revision -#: C/index.docbook:149 +#: C/index.docbook:155 msgid "" "1.17 26 Feb 2011 sk urgent bug fix update" @@ -247,7 +258,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:155 +#: C/index.docbook:161 msgid "" "1.16 14 Jan 2011 sk bugfixes, layout improvements" @@ -256,7 +267,7 @@ msgstr "" "authorinitials> correção de erros, melhorias no layout" #. (itstool) path: revhistory/revision -#: C/index.docbook:161 +#: C/index.docbook:167 msgid "" "1.15 21 May 2010 sk bug and regression fixes" @@ -265,7 +276,7 @@ msgstr "" "authorinitials> correção de erros e regressões" #. (itstool) path: revhistory/revision -#: C/index.docbook:167 +#: C/index.docbook:173 msgid "" "1.14 28 March 2010 sk bugfixes and performance improvements" @@ -275,7 +286,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:173 +#: C/index.docbook:179 msgid "" "1.13 18 December 2009 " "sk broken tarball update atualização de tarball defeituoso" #. (itstool) path: revhistory/revision -#: C/index.docbook:179 +#: C/index.docbook:185 msgid "" "1.12 18 December 2009 " "sk new tool features and " @@ -296,7 +307,7 @@ msgstr "" "erros" #. (itstool) path: revhistory/revision -#: C/index.docbook:185 +#: C/index.docbook:191 msgid "" "1.11 16 November 2008 " "mal GNOME doc-utils migration migração do GNOME doc-utils" #. (itstool) path: chapter/title -#: C/index.docbook:198 +#: C/index.docbook:204 msgid "Introduction" msgstr "Introdução" #. (itstool) path: chapter/para -#: C/index.docbook:200 +#: C/index.docbook:206 msgid "" "This chapter introduces GTK-Doc and gives an overview of what it is and how " "it is used." @@ -320,12 +331,12 @@ msgstr "" "usado." #. (itstool) path: sect1/title -#: C/index.docbook:206 +#: C/index.docbook:212 msgid "What is GTK-Doc?" msgstr "O que é GTK-Doc?" #. (itstool) path: sect1/para -#: C/index.docbook:208 +#: C/index.docbook:214 msgid "" "GTK-Doc is used to document C code. It is typically used to document the " "public API of libraries, such as the GTK+ and GNOME libraries. But it can " @@ -336,12 +347,12 @@ msgstr "" "GNOME. Mas ele também pode ser usado para documentar código de aplicativos." #. (itstool) path: sect1/title -#: C/index.docbook:216 +#: C/index.docbook:222 msgid "How Does GTK-Doc Work?" msgstr "Como o GTK-Doc funciona?" #. (itstool) path: sect1/para -#: C/index.docbook:218 +#: C/index.docbook:224 msgid "" "GTK-Doc works by using documentation of functions placed inside the source " "files in specially-formatted comment blocks, or documentation added to the " @@ -356,7 +367,7 @@ msgstr "" "arquivos de cabeçalho; ele não irá produzir saída para funções estáticas)." #. (itstool) path: sect1/para -#: C/index.docbook:225 +#: C/index.docbook:231 msgid "" "GTK-Doc consists of a number of python scripts, each performing a different " "step in the process." @@ -365,12 +376,12 @@ msgstr "" "etapa diferente no processo." #. (itstool) path: sect1/para -#: C/index.docbook:230 +#: C/index.docbook:236 msgid "There are 5 main steps in the process:" msgstr "Há 5 etapas principais no processo:" #. (itstool) path: listitem/para -#: C/index.docbook:237 +#: C/index.docbook:243 msgid "" "Writing the documentation. The author fills in the " "source files with the documentation for each function, macro, union etc. (In " @@ -383,7 +394,7 @@ msgstr "" "que não é mais recomendado)." #. (itstool) path: listitem/para -#: C/index.docbook:247 +#: C/index.docbook:253 msgid "" "Gathering information about the code. " "gtkdoc-scan scans the header files of the code " @@ -418,7 +429,7 @@ msgstr "" "txt no <módulo>-overrides.txt." #. (itstool) path: listitem/para -#: C/index.docbook:264 +#: C/index.docbook:270 msgid "" "gtkdoc-scangobj can also be used to dynamically " "query a library about any GObject subclasses it exports. It saves " @@ -432,7 +443,7 @@ msgstr "" "fornece." #. (itstool) path: listitem/para -#: C/index.docbook:270 +#: C/index.docbook:276 msgid "" "gtkdoc-scanobj should not be used anymore. It was " "needed in the past when GObject was still GtkObject inside gtk+." @@ -441,7 +452,7 @@ msgstr "" "era necessário no passado, quando GObject ainda era GtkObject dentro do gtk+." #. (itstool) path: listitem/para -#: C/index.docbook:277 +#: C/index.docbook:283 msgid "" "Generating the XML and HTML/PDF. gtkdoc-" "mkdb turns the template files into XML files in the gtkdoc-mkhtml turns the XML files into HTML files " "in the html/ subdirectory. Likewise " @@ -472,7 +483,7 @@ msgstr "" "pacote>.pdf." #. (itstool) path: listitem/para -#: C/index.docbook:292 +#: C/index.docbook:298 msgid "" "Files in xml/ and html/ directories are always overwritten. One " @@ -483,7 +494,7 @@ msgstr "" "devem ser editados manualmente." #. (itstool) path: listitem/para -#: C/index.docbook:300 +#: C/index.docbook:306 msgid "" "Fixing up cross-references between documents. After " "installing the HTML files, gtkdoc-fixxref can be " @@ -505,17 +516,17 @@ msgstr "" "volta para links locais (onde aquelas documentações estão instaladas)." #. (itstool) path: sect1/title -#: C/index.docbook:318 +#: C/index.docbook:324 msgid "Getting GTK-Doc" msgstr "Obtendo GTK-Doc" #. (itstool) path: sect2/title -#: C/index.docbook:321 +#: C/index.docbook:327 msgid "Requirements" msgstr "Requisitos" #. (itstool) path: sect2/para -#: C/index.docbook:322 +#: C/index.docbook:328 msgid "" "python 2/3 - the main scripts are written in python." msgstr "" @@ -523,7 +534,7 @@ msgstr "" "Python." #. (itstool) path: sect2/para -#: C/index.docbook:325 +#: C/index.docbook:331 msgid "" "xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" @@ -532,7 +543,7 @@ msgstr "" "\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/" #. (itstool) path: sect2/para -#: C/index.docbook:329 +#: C/index.docbook:335 msgid "" "docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" #. (itstool) path: sect2/para -#: C/index.docbook:333 +#: C/index.docbook:339 msgid "" "One of source-highlight, highlight " "or vim - optional - used for syntax highlighting of " @@ -554,17 +565,17 @@ msgstr "" "sintaxe de exemplos" #. (itstool) path: sect1/title -#: C/index.docbook:341 +#: C/index.docbook:347 msgid "About GTK-Doc" msgstr "Sobre GTK-Doc" #. (itstool) path: sect1/para -#: C/index.docbook:343 C/index.docbook:357 +#: C/index.docbook:349 C/index.docbook:363 msgid "(FIXME)" msgstr "(CORRIJA-ME)" #. (itstool) path: sect1/para -#: C/index.docbook:347 +#: C/index.docbook:353 msgid "" "(History, authors, web pages, mailing list, license, future plans, " "comparison with other similar systems.)" @@ -573,22 +584,22 @@ msgstr "" "futuros, comparação com outros sistemas similares.)" #. (itstool) path: sect1/title -#: C/index.docbook:355 +#: C/index.docbook:361 msgid "About this Manual" msgstr "Sobre este manual" #. (itstool) path: sect1/para -#: C/index.docbook:361 +#: C/index.docbook:367 msgid "(who it is meant for, where you can get it, license)" msgstr "(pra quem ele serve, onde você pode obtê-lo, licença)" #. (itstool) path: chapter/title -#: C/index.docbook:370 +#: C/index.docbook:376 msgid "Setting up your project" msgstr "Preparando seu projeto" #. (itstool) path: chapter/para -#: C/index.docbook:372 +#: C/index.docbook:378 msgid "" "The next sections describe what steps to perform to integrate GTK-Doc into " "your project. Theses sections assume we work on a project called 'meep'. " @@ -608,12 +619,12 @@ msgstr "" "uma configuração de compilação diferente." #. (itstool) path: sect1/title -#: C/index.docbook:383 +#: C/index.docbook:389 msgid "Setting up a skeleton documentation" msgstr "Preparando o esqueleto de uma documentação" #. (itstool) path: sect1/para -#: C/index.docbook:385 +#: C/index.docbook:391 msgid "" "Under your top-level project directory create folders called docs/reference " "(this way you can also have docs/help for end-user documentation). It is " @@ -627,12 +638,12 @@ msgstr "" "obrigatória." #. (itstool) path: example/title -#: C/index.docbook:394 +#: C/index.docbook:400 msgid "Example directory structure" msgstr "Exemplo de estrutura de diretórios" #. (itstool) path: example/programlisting -#: C/index.docbook:395 +#: C/index.docbook:401 #, no-wrap msgid "" "\n" @@ -656,18 +667,18 @@ msgstr "" " meeper/\n" #. (itstool) path: sect1/para -#: C/index.docbook:392 +#: C/index.docbook:398 msgid "This can then look as shown below: <_:example-1/>" msgstr "Isto pode, então, parecer como exibido abaixo: <_:example-1/>" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:410 C/index.docbook:417 +#: C/index.docbook:416 C/index.docbook:423 msgid "Integration with autoconf" msgstr "Integração com autoconf" #. (itstool) path: sect1/para -#: C/index.docbook:412 +#: C/index.docbook:418 msgid "" "Very easy! Just add one line to your configure.ac " "script." @@ -676,7 +687,7 @@ msgstr "" "filename>." #. (itstool) path: example/programlisting -#: C/index.docbook:418 +#: C/index.docbook:424 #, no-wrap msgid "" "\n" @@ -688,12 +699,12 @@ msgstr "" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" #. (itstool) path: example/title -#: C/index.docbook:430 +#: C/index.docbook:436 msgid "Keep gtk-doc optional" msgstr "Mantenha o gtk-doc como opcional" #. (itstool) path: example/programlisting -#: C/index.docbook:431 +#: C/index.docbook:437 #, no-wrap msgid "" "\n" @@ -713,7 +724,7 @@ msgstr "" "])\n" #. (itstool) path: sect1/para -#: C/index.docbook:425 +#: C/index.docbook:431 msgid "" "This will require all developers to have gtk-doc installed. If it is okay " "for your project to have optional api-doc build setup, you can solve this as " @@ -727,7 +738,7 @@ msgstr "" "GTK_DOC_CHECK no começo de uma linha. <_:example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:442 +#: C/index.docbook:448 msgid "" "The first argument is used to check for the gtkdocversion at configure time. " "The 2nd, optional argument is used by gtkdocize. " @@ -740,30 +751,30 @@ msgstr "" "também adiciona várias opções de configuração:" #. (itstool) path: listitem/para -#: C/index.docbook:448 +#: C/index.docbook:454 msgid "--with-html-dir=PATH : path to installed docs" msgstr "--with-html-dir=CAMINHO : caminho para as documentações instaladas" #. (itstool) path: listitem/para -#: C/index.docbook:449 +#: C/index.docbook:455 msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "--enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=no]" #. (itstool) path: listitem/para -#: C/index.docbook:450 +#: C/index.docbook:456 msgid "" "--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" "--enable-gtk-doc-html : compila documentação em formato html [padrão=sim]" #. (itstool) path: listitem/para -#: C/index.docbook:451 +#: C/index.docbook:457 msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" msgstr "" "--enable-gtk-doc-pdf : compila documentação em formato pdf [padrão=não]" #. (itstool) path: important/para -#: C/index.docbook:455 +#: C/index.docbook:461 msgid "" "GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " @@ -776,7 +787,7 @@ msgstr "" "que faz sentido para usuários, mas não para desenvolvedores)." #. (itstool) path: sect1/para -#: C/index.docbook:463 +#: C/index.docbook:469 msgid "" "Furthermore it is recommended that you have the following line inside your " "configure.ac script. This allows " @@ -789,12 +800,12 @@ msgstr "" "macro para GTK_DOC_CHECK para o seu projeto." #. (itstool) path: example/title -#: C/index.docbook:471 +#: C/index.docbook:477 msgid "Preparation for gtkdocize" msgstr "Preparação para gtkdocize" #. (itstool) path: example/programlisting -#: C/index.docbook:472 +#: C/index.docbook:478 #, no-wrap msgid "" "\n" @@ -804,7 +815,7 @@ msgstr "" "AC_CONFIG_MACRO_DIR(m4)\n" #. (itstool) path: sect1/para -#: C/index.docbook:477 +#: C/index.docbook:483 msgid "" "After all changes to configure.ac are made, update the " "configure file. This can be done by re-running " @@ -815,12 +826,12 @@ msgstr "" "executando novamente autoreconf -i ou autogen.sh." #. (itstool) path: sect1/title -#: C/index.docbook:485 +#: C/index.docbook:491 msgid "Integration with automake" msgstr "Integração com automake" #. (itstool) path: sect1/para -#: C/index.docbook:487 +#: C/index.docbook:493 msgid "" "First copy the Makefile.am from the examples sub directory of the Makefile.am. All the settings have a comment above that describes their " @@ -858,12 +869,12 @@ msgstr "" "suporte a pra listar os parâmetros disponíveis." #. (itstool) path: sect1/title -#: C/index.docbook:512 +#: C/index.docbook:518 msgid "Integration with autogen" msgstr "Integração com autogen" #. (itstool) path: sect1/para -#: C/index.docbook:514 +#: C/index.docbook:520 msgid "" "Most projects will have an autogen.sh script to setup " "the build infrastructure after a checkout from version control system (such " @@ -878,12 +889,12 @@ msgstr "" "O gtkdocize deveria ser executado antes de autoheader, automake ou autoconf." #. (itstool) path: example/title -#: C/index.docbook:523 +#: C/index.docbook:529 msgid "Running gtkdocize from autogen.sh" msgstr "Executando gtkdocize no autogen.sh" #. (itstool) path: example/programlisting -#: C/index.docbook:524 +#: C/index.docbook:530 #, no-wrap msgid "" "\n" @@ -893,7 +904,7 @@ msgstr "" "gtkdocize || exit 1\n" #. (itstool) path: sect1/para -#: C/index.docbook:530 +#: C/index.docbook:536 msgid "" "When running gtkdocize it copies gtk-" "doc.make to your project root (or any directory specified by the " @@ -909,7 +920,7 @@ msgstr "" "gtkdocize." #. (itstool) path: sect1/para -#: C/index.docbook:539 +#: C/index.docbook:545 msgid "" "Historically GTK-Doc was generating template files where developers entered " "the docs. This turned out to be not so good (e.g. the need for having " @@ -942,12 +953,12 @@ msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:556 C/index.docbook:573 +#: C/index.docbook:562 C/index.docbook:579 msgid "Running the doc build" msgstr "Executando a compilação da documentação" #. (itstool) path: sect1/para -#: C/index.docbook:558 +#: C/index.docbook:564 msgid "" "After the previous steps it's time to run the build. First we need to rerun " "autogen.sh. If this script runs configure for you, then " @@ -961,7 +972,7 @@ msgstr "" "configure com esta opção em seguida." #. (itstool) path: sect1/para -#: C/index.docbook:565 +#: C/index.docbook:571 msgid "" "The first make run generates several additional files in the doc-" "directories. The important ones are: <package>.types<pacote>-sections.txt." #. (itstool) path: example/programlisting -#: C/index.docbook:574 +#: C/index.docbook:580 #, no-wrap msgid "" "\n" @@ -986,7 +997,7 @@ msgstr "" "make\n" #. (itstool) path: sect1/para -#: C/index.docbook:580 +#: C/index.docbook:586 msgid "" "Now you can point your browser to docs/reference/<package>/" "index.html. Yes, it's a bit disappointing still. But hang-on, " @@ -998,12 +1009,12 @@ msgstr "" "páginas com vida." #. (itstool) path: sect1/title -#: C/index.docbook:588 +#: C/index.docbook:594 msgid "Integration with version control systems" msgstr "Integração com sistemas de controle de versão" #. (itstool) path: sect1/para -#: C/index.docbook:590 +#: C/index.docbook:596 msgid "" "As a rule of thumb, it's the files you edit which should go under version " "control. For typical projects it's these files: <package>." @@ -1018,7 +1029,7 @@ msgstr "" "filename>, Makefile.am." #. (itstool) path: sect1/para -#: C/index.docbook:598 +#: C/index.docbook:604 msgid "" "Files in the xml/ and html/ " "directories should not go under version control. Neither should any of the " @@ -1029,12 +1040,12 @@ msgstr "" "deveriam entrar arquivos .stamp." #. (itstool) path: sect1/title -#: C/index.docbook:606 +#: C/index.docbook:612 msgid "Integration with plain makefiles or other build systems" msgstr "Integração com makefiles simples ou outros sistemas de compilação" #. (itstool) path: sect1/para -#: C/index.docbook:608 +#: C/index.docbook:614 msgid "" "In the case one does not want to use automake and therefore gtk-" "doc.mak one will need to call the gtkdoc tools in the right order " @@ -1045,12 +1056,12 @@ msgstr "" "correta nos makefiles devidos (ou outras ferramentas de compilação)." #. (itstool) path: example/title -#: C/index.docbook:615 +#: C/index.docbook:621 msgid "Documentation build steps" msgstr "Etapas de compilação da documentação" #. (itstool) path: example/programlisting -#: C/index.docbook:616 +#: C/index.docbook:622 #, no-wrap msgid "" "\n" @@ -1076,7 +1087,7 @@ msgstr "" "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" #. (itstool) path: sect1/para -#: C/index.docbook:630 +#: C/index.docbook:636 msgid "" "One will need to look at the Makefile.am and " "gtk-doc.mak to pick the extra options needed." @@ -1085,12 +1096,12 @@ msgstr "" "doc.mak para obter as opções extras necessárias." #. (itstool) path: sect1/title -#: C/index.docbook:637 +#: C/index.docbook:643 msgid "Integration with CMake build systems" msgstr "Integração com sistemas de compilação CMake" #. (itstool) path: sect1/para -#: C/index.docbook:639 +#: C/index.docbook:645 msgid "" "GTK-Doc now provides a GtkDocConfig.cmake module (and " "the corresponding GtkDocConfigVersion.cmake module). " @@ -1103,12 +1114,12 @@ msgstr "" "em seu arquivo CMakeLists.txt." #. (itstool) path: example/title -#: C/index.docbook:649 +#: C/index.docbook:655 msgid "Example of using GTK-Doc from CMake" msgstr "Exemplo de uso do GTK-Doc no CMake" #. (itstool) path: example/programlisting -#: C/index.docbook:650 +#: C/index.docbook:656 #, no-wrap msgid "" "\n" @@ -1151,17 +1162,17 @@ msgstr "" " DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" #. (itstool) path: sect1/para -#: C/index.docbook:647 +#: C/index.docbook:653 msgid "The following example shows how to use this command. <_:example-1/>" msgstr "O exemplo a seguir mostra como usar este comando. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:675 +#: C/index.docbook:681 msgid "Documenting the code" msgstr "Documentando o código" #. (itstool) path: chapter/para -#: C/index.docbook:677 +#: C/index.docbook:683 msgid "" "GTK-Doc uses source code comment with a special syntax for code " "documentation. Further it retrieves information about your project structure " @@ -1174,12 +1185,12 @@ msgstr "" "descobrir todas as informações sobre a sintaxe dos comentários." #. (itstool) path: note/title -#: C/index.docbook:685 +#: C/index.docbook:691 msgid "Documentation placement" msgstr "Localização da documentação" #. (itstool) path: note/para -#: C/index.docbook:686 +#: C/index.docbook:692 msgid "" "In the past most documentation had to be filled into files residing inside " "the tmpl directory. This has the disadvantages that the " @@ -1193,7 +1204,7 @@ msgstr "" "versão." #. (itstool) path: note/para -#: C/index.docbook:692 +#: C/index.docbook:698 msgid "" "The avoid the aforementioned problems we suggest putting the documentation " "inside the sources. This manual will only describe this way of documenting " @@ -1204,12 +1215,12 @@ msgstr "" "descrever esta forma de documentar código." #. (itstool) path: example/title -#: C/index.docbook:703 C/index.docbook:729 +#: C/index.docbook:709 C/index.docbook:735 msgid "GTK-Doc comment block" msgstr "Bloco de comentário do GTK-Doc" #. (itstool) path: example/programlisting -#: C/index.docbook:704 +#: C/index.docbook:710 #, no-wrap msgid "" "\n" @@ -1223,7 +1234,7 @@ msgstr "" "#endif\n" #. (itstool) path: chapter/para -#: C/index.docbook:699 +#: C/index.docbook:705 msgid "" "The scanner can handle the majority of C headers fine. In the case of " "receiving warnings from the scanner that look like a special case, one can " @@ -1234,12 +1245,12 @@ msgstr "" "pode-se informar ao GTK-Doc para ignorá-los. <_:example-1/>" #. (itstool) path: note/title -#: C/index.docbook:713 +#: C/index.docbook:719 msgid "Limitations" msgstr "Limitações" #. (itstool) path: note/para -#: C/index.docbook:714 +#: C/index.docbook:720 msgid "" "Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but " "not #if !defined(__GTK_DOC_IGNORE__) or other combinations." @@ -1249,12 +1260,12 @@ msgstr "" "combinações." #. (itstool) path: sect1/title -#: C/index.docbook:724 +#: C/index.docbook:730 msgid "Documentation comments" msgstr "Comentários de documentação" #. (itstool) path: example/programlisting -#: C/index.docbook:730 +#: C/index.docbook:736 #, no-wrap msgid "" "\n" @@ -1270,7 +1281,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:726 +#: C/index.docbook:732 msgid "" "A multiline comment that starts with an additional '*' marks a documentation " "block that will be processed by the GTK-Doc tools. <_:example-1/>" @@ -1280,7 +1291,7 @@ msgstr "" # Ocultei o TODO da tradução. Para que server? :/ #. (itstool) path: sect1/para -#: C/index.docbook:739 +#: C/index.docbook:745 msgid "" "The 'identifier' is one line with the name of the item the comment is " "related to. The syntax differs a little depending on the item. (TODO add " @@ -1290,7 +1301,7 @@ msgstr "" "relacionado. A sintaxe difere um pouco dependendo do item." #. (itstool) path: sect1/para -#: C/index.docbook:745 +#: C/index.docbook:751 msgid "" "The 'documentation' block is also different for each symbol type. Symbol " "types that get parameters such as functions or macros have the parameter " @@ -1310,7 +1321,7 @@ msgstr "" "espaço). Isso é útil em textos pré-formatados (listagens de código)." #. (itstool) path: listitem/para -#: C/index.docbook:762 +#: C/index.docbook:768 msgid "" "What it is: The name for a class or function can sometimes be misleading for " "people coming from a different background." @@ -1319,24 +1330,24 @@ msgstr "" "entendimento equivocado pessoas com experiências diferentes." #. (itstool) path: listitem/para -#: C/index.docbook:768 +#: C/index.docbook:774 msgid "" "What it does: Tell about common uses. Put it in relation with the other API." msgstr "" "O que isso faz: Fale sobre usos comuns. Coloque em relação com a outra API." #. (itstool) path: tip/para -#: C/index.docbook:758 +#: C/index.docbook:764 msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" msgstr "Ao documentar um código, descreva dois aspectos: <_:itemizedlist-1/>" #. (itstool) path: listitem/para -#: C/index.docbook:783 +#: C/index.docbook:789 msgid "Use function() to refer to functions or macros which take arguments." msgstr "Use function() para referir às funções ou macros que levam argumentos." #. (itstool) path: listitem/para -#: C/index.docbook:788 +#: C/index.docbook:794 msgid "" "Use @param to refer to parameters. Also use this when referring to " "parameters of other functions, related to the one being described." @@ -1345,12 +1356,12 @@ msgstr "" "parâmetros de outras funções, relacionadas àquele sendo descrito." #. (itstool) path: listitem/para -#: C/index.docbook:794 +#: C/index.docbook:800 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "Use %constant para se referir a uma constante, ex.: %G_TRAVERSE_LEAFS." #. (itstool) path: listitem/para -#: C/index.docbook:799 +#: C/index.docbook:805 msgid "" "Use #symbol to refer to other types of symbol, e.g. structs and enums and " "macros which don't take arguments." @@ -1359,17 +1370,17 @@ msgstr "" "e macros que não levam argumentos." #. (itstool) path: listitem/para -#: C/index.docbook:805 +#: C/index.docbook:811 msgid "Use #Object::signal to refer to a GObject signal." msgstr "Use #Object::signal para se referir a um sinal de GObject." #. (itstool) path: listitem/para -#: C/index.docbook:810 +#: C/index.docbook:816 msgid "Use #Object:property to refer to a GObject property." msgstr "Use #Object:property para se referir a uma propriedade de GObject." #. (itstool) path: listitem/para -#: C/index.docbook:815 +#: C/index.docbook:821 msgid "" "Use #Struct.field to refer to a field inside a structure and #GObjectClass." "foo_bar() to refer to a vmethod." @@ -1378,7 +1389,7 @@ msgstr "" "#GObjectClass.foo_bar() para se referir a um vmethod." #. (itstool) path: sect1/para -#: C/index.docbook:777 +#: C/index.docbook:783 msgid "" "One advantage of hyper-text over plain-text is the ability to have links in " "the document. Writing the correct markup for a link can be tedious though. " @@ -1391,7 +1402,7 @@ msgstr "" "itemizedlist-1/>" #. (itstool) path: tip/para -#: C/index.docbook:824 +#: C/index.docbook:830 msgid "" "If you need to use the special characters '<', '>', '()', '@', '%', or " "'#' in your documentation without GTK-Doc changing them you can use the XML " @@ -1406,7 +1417,7 @@ msgstr "" "uma contrabarra “\\”." #. (itstool) path: sect1/para -#: C/index.docbook:833 +#: C/index.docbook:839 msgid "" "DocBook can do more than just links. One can also have lists, examples, " "headings, and images. As of version 1.20, the preferred way is to use a " @@ -1424,7 +1435,7 @@ msgstr "" "linhas começando com um traço." #. (itstool) path: sect1/para -#: C/index.docbook:844 +#: C/index.docbook:850 msgid "" "While markdown is now preferred one can mix both. One limitation here is " "that one can use docbook xml within markdown, but markdown within docbook " @@ -1435,7 +1446,7 @@ msgstr "" "suporte a markdown no docbook xml." #. (itstool) path: sect1/para -#: C/index.docbook:850 +#: C/index.docbook:856 msgid "" "In older GTK-Doc releases, if you need support for additional formatting, " "you would need to enable the usage of docbook XML tags inside doc-comments " @@ -1450,12 +1461,12 @@ msgstr "" "symbol> dentro de Makefile.am." #. (itstool) path: example/title -#: C/index.docbook:859 +#: C/index.docbook:865 msgid "GTK-Doc comment block using Markdown" msgstr "Bloco de comentário do GTK-Doc usando Markdown" #. (itstool) path: example/programlisting -#: C/index.docbook:860 +#: C/index.docbook:866 #, no-wrap msgid "" "\n" @@ -1531,7 +1542,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:899 +#: C/index.docbook:905 msgid "" "More examples of what markdown tags are supported can be found in the Referência de sintaxe de markdown de documentação." #. (itstool) path: tip/para -#: C/index.docbook:905 +#: C/index.docbook:911 msgid "" "As already mentioned earlier GTK-Doc is for documenting public API. Thus one " "cannot write documentation for static symbols. Nevertheless it is good to " @@ -1561,12 +1572,12 @@ msgstr "" "comentário e inserir o nome do símbolo no lugar correto do arquivo e seções." #. (itstool) path: sect1/title -#: C/index.docbook:919 +#: C/index.docbook:925 msgid "Documenting sections" msgstr "Documentando seções" #. (itstool) path: sect1/para -#: C/index.docbook:921 +#: C/index.docbook:927 msgid "" "Each section of the documentation contains information about one class or " "module. To introduce the component one can write a section block. The short " @@ -1579,12 +1590,12 @@ msgstr "" "os @fields são opcionais." #. (itstool) path: example/title -#: C/index.docbook:929 +#: C/index.docbook:935 msgid "Section comment block" msgstr "Bloco de comentário de sessão" #. (itstool) path: example/programlisting -#: C/index.docbook:930 +#: C/index.docbook:936 #, no-wrap msgid "" "\n" @@ -1616,12 +1627,12 @@ msgstr "" " */\n" #. (itstool) path: varlistentry/term -#: C/index.docbook:949 +#: C/index.docbook:955 msgid "SECTION:<name>" msgstr "SECTION:<nome>" #. (itstool) path: listitem/para -#: C/index.docbook:951 +#: C/index.docbook:957 msgid "" "The name links the section documentation to the respective part in the " "<package>-sections.txt file. The name given here " @@ -1634,12 +1645,12 @@ msgstr "" "txt." #. (itstool) path: varlistentry/term -#: C/index.docbook:960 +#: C/index.docbook:966 msgid "@short_description" msgstr "@short_description" #. (itstool) path: listitem/para -#: C/index.docbook:962 +#: C/index.docbook:968 msgid "" "A one line description of the section, that later will appear after the " "links in the TOC and at the top of the section page." @@ -1648,12 +1659,12 @@ msgstr "" "no TOC (sumário) no topo da página da sessão." #. (itstool) path: varlistentry/term -#: C/index.docbook:969 +#: C/index.docbook:975 msgid "@title" msgstr "@title" #. (itstool) path: listitem/para -#: C/index.docbook:971 +#: C/index.docbook:977 msgid "" "The section title defaults to <name> from the SECTION declaration. It " "can be overridden with the @title field." @@ -1662,12 +1673,12 @@ msgstr "" "pode ser sobrescrito com o campo @title." #. (itstool) path: varlistentry/term -#: C/index.docbook:978 +#: C/index.docbook:984 msgid "@section_id" msgstr "@section_id" #. (itstool) path: listitem/para -#: C/index.docbook:980 +#: C/index.docbook:986 msgid "" "Overrides the use of title as a section identifier. For GObjects the <" "title> is used as a section_id and for other sections it is <" @@ -1678,22 +1689,22 @@ msgstr "" "MÓDULO>-<title>." #. (itstool) path: varlistentry/term -#: C/index.docbook:988 +#: C/index.docbook:994 msgid "@see_also" msgstr "@see_also" #. (itstool) path: listitem/para -#: C/index.docbook:990 +#: C/index.docbook:996 msgid "A list of symbols that are related to this section." msgstr "Uma lista de símbolos que estão relacionados a esta sessão." #. (itstool) path: varlistentry/term -#: C/index.docbook:996 +#: C/index.docbook:1002 msgid "@stability" msgstr "@stability" #. (itstool) path: listitem/para -#: C/index.docbook:1003 +#: C/index.docbook:1009 msgid "" "Stable - The intention of a Stable interface is to enable arbitrary third " "parties to develop applications to these interfaces, release them, and have " @@ -1710,7 +1721,7 @@ msgstr "" "alterações incompatíveis sejam raras e que tenham fortes justificativas." #. (itstool) path: listitem/para -#: C/index.docbook:1015 +#: C/index.docbook:1021 msgid "" "Unstable - Unstable interfaces are experimental or transitional. They are " "typically used to give outside developers early access to new or rapidly " @@ -1726,7 +1737,7 @@ msgstr "" "fontes de uma versão menor para a próxima." #. (itstool) path: listitem/para -#: C/index.docbook:1027 +#: C/index.docbook:1033 msgid "" "Private - An interface that can be used within the GNOME stack itself, but " "that is not documented for end-users. Such functions should only be used in " @@ -1737,7 +1748,7 @@ msgstr "" "usadas nas formas especificadas e documentadas." #. (itstool) path: listitem/para -#: C/index.docbook:1036 +#: C/index.docbook:1042 msgid "" "Internal - An interface that is internal to a module and does not require " "end-user documentation. Functions that are undocumented are assumed to be " @@ -1748,7 +1759,7 @@ msgstr "" "sendo “Interna”." #. (itstool) path: listitem/para -#: C/index.docbook:998 +#: C/index.docbook:1004 msgid "" "An informal description of the stability level this API has. We recommend " "the use of one of these terms: <_:itemizedlist-1/>" @@ -1757,12 +1768,12 @@ msgstr "" "recomendamos o uso de um desses termos: <_:itemizedlist-1/>" #. (itstool) path: varlistentry/term -#: C/index.docbook:1048 +#: C/index.docbook:1054 msgid "@include" msgstr "@include" #. (itstool) path: listitem/para -#: C/index.docbook:1050 +#: C/index.docbook:1056 msgid "" "The #include files to show in the section synopsis (a " "comma separated list), overriding the global value from the --default-stability argument to " @@ -1889,17 +1900,17 @@ msgstr "" "gtkdoc-mkdb com um dos balores abaixo." #. (itstool) path: variablelist/title -#: C/index.docbook:1128 +#: C/index.docbook:1134 msgid "Stability Tags" msgstr "Tags de estabilidade" #. (itstool) path: varlistentry/term -#: C/index.docbook:1129 +#: C/index.docbook:1135 msgid "Stability: Stable" msgstr "Stability: Stable" #. (itstool) path: listitem/para -#: C/index.docbook:1131 +#: C/index.docbook:1137 msgid "" "Mark the element as stable. This is for public APIs which are guaranteed to " "remain stable for all future minor releases of the project." @@ -1908,12 +1919,12 @@ msgstr "" "garantida para todos os próximos lançamentos menores do projeto." #. (itstool) path: varlistentry/term -#: C/index.docbook:1138 +#: C/index.docbook:1144 msgid "Stability: Unstable" msgstr "Stability: Unstable" #. (itstool) path: listitem/para -#: C/index.docbook:1140 +#: C/index.docbook:1146 msgid "" "Mark the element as unstable. This is for public APIs which are released as " "a preview before being stabilised." @@ -1922,12 +1933,12 @@ msgstr "" "como versão de desenvolvimento antes de se tornar estável." #. (itstool) path: varlistentry/term -#: C/index.docbook:1146 +#: C/index.docbook:1152 msgid "Stability: Private" msgstr "Stability: Private" #. (itstool) path: listitem/para -#: C/index.docbook:1148 +#: C/index.docbook:1154 msgid "" "Mark the element as private. This is for interfaces which can be used by " "tightly coupled modules, but not by arbitrary third parties." @@ -1936,7 +1947,7 @@ msgstr "" "por um conjunto pequeno de módulos, mas não por terceiros." #. (itstool) path: example/programlisting -#: C/index.docbook:1158 +#: C/index.docbook:1164 #, no-wrap msgid "" "\n" @@ -1975,12 +1986,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1178 C/index.docbook:1188 +#: C/index.docbook:1184 C/index.docbook:1194 msgid "Annotations" msgstr "Anotações" #. (itstool) path: sect2/para -#: C/index.docbook:1180 +#: C/index.docbook:1186 msgid "" "Documentation blocks can contain annotation-tags. These tags will be " "rendered with tooltips describing their meaning. The tags are used by " @@ -1996,7 +2007,7 @@ msgstr "" "\">no wiki." #. (itstool) path: example/programlisting -#: C/index.docbook:1189 +#: C/index.docbook:1195 #, no-wrap msgid "" "\n" @@ -2037,12 +2048,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1210 C/index.docbook:1239 +#: C/index.docbook:1216 C/index.docbook:1245 msgid "Function comment block" msgstr "Bloco de comentário de função" #. (itstool) path: listitem/para -#: C/index.docbook:1216 +#: C/index.docbook:1222 msgid "" "Document whether returned objects, lists, strings, etc, should be freed/" "unrefed/released." @@ -2051,25 +2062,25 @@ msgstr "" "não referenciados/liberada." #. (itstool) path: listitem/para -#: C/index.docbook:1222 +#: C/index.docbook:1228 msgid "Document whether parameters can be NULL, and what happens if they are." msgstr "" "Documente se parâmetros pode ser NULL e o que acontece se eles o forem." #. (itstool) path: listitem/para -#: C/index.docbook:1227 +#: C/index.docbook:1233 msgid "" "Mention interesting pre-conditions and post-conditions where appropriate." msgstr "" "Mencione pré-condições e pós-condições interessantes onde for apropriado." #. (itstool) path: sect2/para -#: C/index.docbook:1212 C/index.docbook:1298 +#: C/index.docbook:1218 C/index.docbook:1304 msgid "Please remember to: <_:itemizedlist-1/>" msgstr "Por favor, lembre-se de: <_:itemizedlist-1/>" #. (itstool) path: sect2/para -#: C/index.docbook:1234 +#: C/index.docbook:1240 msgid "" "Gtk-doc assumes all symbols (macros, functions) starting with '_' are " "private. They are treated like static functions." @@ -2078,7 +2089,7 @@ msgstr "" "são privadas. Elas são tratadas como funções estáticas." #. (itstool) path: example/programlisting -#: C/index.docbook:1240 +#: C/index.docbook:1246 #, no-wrap msgid "" "\n" @@ -2120,27 +2131,27 @@ msgstr "" " */\n" #. (itstool) path: variablelist/title -#: C/index.docbook:1261 +#: C/index.docbook:1267 msgid "Function tags" msgstr "Tags de função" #. (itstool) path: varlistentry/term -#: C/index.docbook:1262 C/index.docbook:1469 +#: C/index.docbook:1268 C/index.docbook:1475 msgid "Returns:" msgstr "Returns:" #. (itstool) path: listitem/para -#: C/index.docbook:1264 +#: C/index.docbook:1270 msgid "Paragraph describing the returned result." msgstr "Parágrafo descrevendo o resultado retornado." #. (itstool) path: varlistentry/term -#: C/index.docbook:1269 +#: C/index.docbook:1275 msgid "@...:" msgstr "@...:" #. (itstool) path: listitem/para -#: C/index.docbook:1271 +#: C/index.docbook:1277 msgid "" "In case the function has variadic arguments, you should use this tag " "(@Varargs: does also work for historic reasons)." @@ -2150,12 +2161,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1281 C/index.docbook:1283 +#: C/index.docbook:1287 C/index.docbook:1289 msgid "Property comment block" msgstr "Bloco de comentário de propriedade" #. (itstool) path: example/programlisting -#: C/index.docbook:1284 +#: C/index.docbook:1290 #, no-wrap msgid "" "\n" @@ -2176,12 +2187,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1296 C/index.docbook:1315 +#: C/index.docbook:1302 C/index.docbook:1321 msgid "Signal comment block" msgstr "Bloco de comentário de sinal" #. (itstool) path: listitem/para -#: C/index.docbook:1302 +#: C/index.docbook:1308 msgid "" "Document when the signal is emitted and whether it is emitted before or " "after other signals." @@ -2190,26 +2201,13 @@ msgstr "" "sinais." #. (itstool) path: listitem/para -#: C/index.docbook:1308 +#: C/index.docbook:1314 msgid "Document what an application might do in the signal handler." msgstr "Documente o que um aplicativo pode fazer no manipulador do sinal." #. (itstool) path: example/programlisting -#: C/index.docbook:1316 +#: C/index.docbook:1322 #, no-wrap -#| msgid "" -#| "\n" -#| "/**\n" -#| " * FooWidget::foobarized:\n" -#| " * @widget: the widget that received the signal\n" -#| " * @foo: some foo\n" -#| " * @bar: some bar\n" -#| " *\n" -#| " * The ::foobarized signal is emitted each time someone tries to foobarize @widget.\n" -#| " */\n" -#| "foo_signals[FOOBARIZE] =\n" -#| " g_signal_new (\"foobarize\",\n" -#| " ...\n" msgid "" "\n" "/**\n" @@ -2231,8 +2229,7 @@ msgstr "" " * @foo: algum foo\n" " * @bar: algum bar\n" " *\n" -" * O sinal ::foobarized é emitido cada vez que alguém tenta foobarizar " -"@widget.\n" +" * O sinal ::foobarized é emitido cada vez que alguém tenta foobarizar @widget.\n" " */\n" "foo_sinais[FOOBARIZADO] =\n" " g_signal_novo (\"foobarizado\",\n" @@ -2240,12 +2237,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1333 C/index.docbook:1334 +#: C/index.docbook:1339 C/index.docbook:1340 msgid "Struct comment block" msgstr "Bloco de comentário de struct" #. (itstool) path: example/programlisting -#: C/index.docbook:1335 +#: C/index.docbook:1341 #, no-wrap msgid "" "\n" @@ -2275,7 +2272,7 @@ msgstr "" "} FooWidget;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1350 +#: C/index.docbook:1356 msgid "" "Use /*< private >*/ before the private struct fields you " "want to hide. Use /*< public >*/ for the reverse " @@ -2286,7 +2283,7 @@ msgstr "" "comportamento inverso." #. (itstool) path: sect2/para -#: C/index.docbook:1356 +#: C/index.docbook:1362 msgid "" "If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" " "it will be considered private automatically and doesn't need to be mentioned " @@ -2297,7 +2294,7 @@ msgstr "" "no bloco de comentário." #. (itstool) path: sect2/para -#: C/index.docbook:1362 +#: C/index.docbook:1368 msgid "" "Struct comment blocks can also be used for GObjects and GObjectClasses. It " "is usually a good idea to add a comment block for a class, if it has " @@ -2317,12 +2314,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1374 C/index.docbook:1375 +#: C/index.docbook:1380 C/index.docbook:1381 msgid "Enum comment block" msgstr "Bloco de comentário de enum" #. (itstool) path: example/programlisting -#: C/index.docbook:1376 +#: C/index.docbook:1382 #, no-wrap msgid "" "\n" @@ -2356,7 +2353,7 @@ msgstr "" "} Alguma coisa;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1393 +#: C/index.docbook:1399 msgid "" "Use /*< private >*/ before the private enum values you " "want to hide. Use /*< public >*/ for the reverse " @@ -2367,12 +2364,12 @@ msgstr "" "comportamento inverso." #. (itstool) path: sect1/title -#: C/index.docbook:1404 +#: C/index.docbook:1410 msgid "Inline program documentation" msgstr "Documentação de programa em-linha" #. (itstool) path: sect1/para -#: C/index.docbook:1405 +#: C/index.docbook:1411 msgid "" "You can document programs and their commandline interface using inline " "documentation." @@ -2381,37 +2378,37 @@ msgstr "" "documentação em-linha." #. (itstool) path: variablelist/title -#: C/index.docbook:1411 +#: C/index.docbook:1417 msgid "Tags" msgstr "Tags" #. (itstool) path: varlistentry/term -#: C/index.docbook:1413 +#: C/index.docbook:1419 msgid "PROGRAM" msgstr "PROGRAM" #. (itstool) path: listitem/para -#: C/index.docbook:1416 +#: C/index.docbook:1422 msgid "Defines the start of a program documentation." msgstr "Define o início da documentação de um programa." #. (itstool) path: varlistentry/term -#: C/index.docbook:1423 +#: C/index.docbook:1429 msgid "@short_description:" msgstr "@short_description:" #. (itstool) path: listitem/para -#: C/index.docbook:1425 +#: C/index.docbook:1431 msgid "Defines a short description of the program. (Optional)" msgstr "Define uma descrição breve do programa. (Opcional)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1432 +#: C/index.docbook:1438 msgid "@synopsis:" msgstr "@synopsis:" #. (itstool) path: listitem/para -#: C/index.docbook:1434 +#: C/index.docbook:1440 msgid "" "Defines the arguments, or list of arguments that the program can take. " "(Optional)" @@ -2420,52 +2417,52 @@ msgstr "" "(Opcional)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1442 +#: C/index.docbook:1448 msgid "@see_also:" msgstr "@see_also:" #. (itstool) path: listitem/para -#: C/index.docbook:1444 +#: C/index.docbook:1450 msgid "See Also manual page section. (Optional)" msgstr "A seção “Veja Também” (See Also) de páginas de manual. (Opcional)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1451 +#: C/index.docbook:1457 msgid "@arg:" msgstr "@arg:" #. (itstool) path: listitem/para -#: C/index.docbook:1453 +#: C/index.docbook:1459 msgid "Argument(s) passed to the program and their description. (Optional)" msgstr "Argumento(s) passado(s) para o programa e sua descrição. (Opcional)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1460 +#: C/index.docbook:1466 msgid "Description:" msgstr "Description:" #. (itstool) path: listitem/para -#: C/index.docbook:1462 +#: C/index.docbook:1468 msgid "A longer description of the program." msgstr "Um descrição mais longa do programa." #. (itstool) path: listitem/para -#: C/index.docbook:1471 +#: C/index.docbook:1477 msgid "Specificy what value(s) the program returns. (Optional)" msgstr "Especifique quais valor(es) o programa retorna. (Opcional)" #. (itstool) path: sect2/title -#: C/index.docbook:1480 +#: C/index.docbook:1486 msgid "Example of program documentation." msgstr "Exemplo de documentação de programa." #. (itstool) path: example/title -#: C/index.docbook:1481 +#: C/index.docbook:1487 msgid "Program documentation block" msgstr "Bloco de documentação de programa" #. (itstool) path: example/programlisting -#: C/index.docbook:1482 +#: C/index.docbook:1488 #, no-wrap msgid "" "\n" @@ -2509,12 +2506,12 @@ msgstr "" "}\n" #. (itstool) path: sect1/title -#: C/index.docbook:1508 +#: C/index.docbook:1514 msgid "Useful DocBook tags" msgstr "Tags úteis do DocBook" #. (itstool) path: sect1/para -#: C/index.docbook:1510 +#: C/index.docbook:1516 msgid "" "Here are some DocBook tags which are most useful when documenting the code." msgstr "" @@ -2522,7 +2519,7 @@ msgstr "" "documentado o código." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1519 +#: C/index.docbook:1525 #, no-wrap msgid "" "\n" @@ -2532,7 +2529,7 @@ msgstr "" "<link linkend=\"glib-Hash-Tables\">Tabela de hashes</link>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1515 +#: C/index.docbook:1521 msgid "" "To link to another section in the GTK docs: <_:informalexample-1/> The " "linkend is the SGML/XML id on the top item of the page you want to link to. " @@ -2548,7 +2545,7 @@ msgstr "" "convertidos em '-' para estar em conformidade com SGML/XML." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1532 +#: C/index.docbook:1538 #, no-wrap msgid "" "\n" @@ -2558,7 +2555,7 @@ msgstr "" "<function>...</function>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1529 +#: C/index.docbook:1535 msgid "" "To refer to an external function, e.g. a standard C function: <_:" "informalexample-1/>" @@ -2567,7 +2564,7 @@ msgstr "" "do C: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1541 +#: C/index.docbook:1547 #, no-wrap msgid "" "\n" @@ -2587,7 +2584,7 @@ msgstr "" "</example>\n" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1552 +#: C/index.docbook:1558 #, no-wrap msgid "" "\n" @@ -2605,7 +2602,7 @@ msgstr "" "</informalexample>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1538 +#: C/index.docbook:1544 msgid "" "To include example code: <_:informalexample-1/> or possibly this, for very " "short code fragments which don't need a title: <_:informalexample-2/> For " @@ -2617,7 +2614,7 @@ msgstr "" "abreviação: |[ ... ]|" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1571 +#: C/index.docbook:1577 #, no-wrap msgid "" "\n" @@ -2649,12 +2646,12 @@ msgstr "" "</itemizedlist>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1568 +#: C/index.docbook:1574 msgid "To include bulleted lists: <_:informalexample-1/>" msgstr "Para incluir listas com marcadores: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1591 +#: C/index.docbook:1597 #, no-wrap msgid "" "\n" @@ -2672,13 +2669,13 @@ msgstr "" "</note>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1588 +#: C/index.docbook:1594 msgid "" "To include a note which stands out from the text: <_:informalexample-1/>" msgstr "Para incluir uma nota que fique fora do texto: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1604 +#: C/index.docbook:1610 #, no-wrap msgid "" "\n" @@ -2688,12 +2685,12 @@ msgstr "" "<type>unsigned char</type>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1601 +#: C/index.docbook:1607 msgid "To refer to a type: <_:informalexample-1/>" msgstr "Para se referir a um tipo: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1613 +#: C/index.docbook:1619 #, no-wrap msgid "" "\n" @@ -2703,7 +2700,7 @@ msgstr "" "<structname>XFontStruct</structname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1610 +#: C/index.docbook:1616 msgid "" "To refer to an external structure (not one described in the GTK docs): <_:" "informalexample-1/>" @@ -2712,7 +2709,7 @@ msgstr "" "GTK): <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1622 +#: C/index.docbook:1628 #, no-wrap msgid "" "\n" @@ -2722,12 +2719,12 @@ msgstr "" "<structfield>len</structfield>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1619 +#: C/index.docbook:1625 msgid "To refer to a field of a structure: <_:informalexample-1/>" msgstr "Para se referir a um campo de uma estrutura: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1631 +#: C/index.docbook:1637 #, no-wrap msgid "" "\n" @@ -2737,7 +2734,7 @@ msgstr "" "<classname>GtkWidget</classname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1628 +#: C/index.docbook:1634 msgid "" "To refer to a class name, we could possibly use: <_:informalexample-1/> but " "you'll probably be using #GtkWidget instead (to automatically create a link " @@ -2750,7 +2747,7 @@ msgstr "" "veja as abreviações)." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1642 +#: C/index.docbook:1648 #, no-wrap msgid "" "\n" @@ -2760,12 +2757,12 @@ msgstr "" "<emphasis>Isso é importante</emphasis>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1639 +#: C/index.docbook:1645 msgid "To emphasize text: <_:informalexample-1/>" msgstr "Para enfatizar um texto: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1651 +#: C/index.docbook:1657 #, no-wrap msgid "" "\n" @@ -2775,12 +2772,12 @@ msgstr "" "<filename>/home/usuario/documentos</filename>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1648 +#: C/index.docbook:1654 msgid "For filenames use: <_:informalexample-1/>" msgstr "Para nome de arquivos use: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1660 +#: C/index.docbook:1666 #, no-wrap msgid "" "\n" @@ -2790,17 +2787,17 @@ msgstr "" "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1657 +#: C/index.docbook:1663 msgid "To refer to keys use: <_:informalexample-1/>" msgstr "Para se referir a chaves use: <_:informalexample-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1670 +#: C/index.docbook:1676 msgid "Filling the extra files" msgstr "Preenchendo os arquivos extras" #. (itstool) path: chapter/para -#: C/index.docbook:1672 +#: C/index.docbook:1678 msgid "" "There are a couple of extra files, that need to be maintained along with the " "inline source code comments: <package>.types, " @@ -2813,12 +2810,12 @@ msgstr "" "<pacote>-sections.txt." #. (itstool) path: sect1/title -#: C/index.docbook:1681 +#: C/index.docbook:1687 msgid "Editing the types file" msgstr "Editando o arquivo de tipos" #. (itstool) path: sect1/para -#: C/index.docbook:1683 +#: C/index.docbook:1689 msgid "" "If your library or application includes GObjects, you want their signals, " "arguments/parameters and position in the hierarchy to be shown in the " @@ -2833,12 +2830,12 @@ msgstr "" "<pacote>.types." #. (itstool) path: example/title -#: C/index.docbook:1692 +#: C/index.docbook:1698 msgid "Example types file snippet" msgstr "Trecho de exemplo de arquivo de tipos" #. (itstool) path: example/programlisting -#: C/index.docbook:1693 +#: C/index.docbook:1699 #, no-wrap msgid "" "\n" @@ -2858,7 +2855,7 @@ msgstr "" "gtk_arrow_get_type\n" #. (itstool) path: sect1/para -#: C/index.docbook:1704 +#: C/index.docbook:1710 msgid "" "Since GTK-Doc 1.8 gtkdoc-scan can generate this " "list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in " @@ -2871,12 +2868,12 @@ msgstr "" "deveria distribuir o arquivo de tipos nem tê-lo sob um controle de versão." #. (itstool) path: sect1/title -#: C/index.docbook:1713 +#: C/index.docbook:1719 msgid "Editing the master document" msgstr "Editando o documento mestre" #. (itstool) path: sect1/para -#: C/index.docbook:1715 +#: C/index.docbook:1721 msgid "" "GTK-Doc produces documentation in DocBook SGML/XML. When processing the " "inline source comments, the GTK-Doc tools generate one documentation page " @@ -2889,7 +2886,7 @@ msgstr "" "mestre os inclui e os coloca em uma ordem." #. (itstool) path: sect1/para -#: C/index.docbook:1722 +#: C/index.docbook:1728 msgid "" "While GTK-Doc creates a template master document for you, later runs will " "not touch it again. This means that one can freely structure the " @@ -2906,7 +2903,7 @@ msgstr "" "em tempo para ver se há itens a serem introduzidos lá." #. (itstool) path: tip/para -#: C/index.docbook:1732 +#: C/index.docbook:1738 msgid "" "Do not create tutorials as extra documents. Just write extra chapters. The " "benefit of directly embedding the tutorial for your library into the API " @@ -2921,7 +2918,7 @@ msgstr "" "atualizações junto com a biblioteca." #. (itstool) path: sect1/para -#: C/index.docbook:1741 +#: C/index.docbook:1747 msgid "" "So what are the things to change inside the master document? For a start is " "only a little. There are some placeholders (text in square brackets) there " @@ -2932,12 +2929,12 @@ msgstr "" "colchetes) que você deve cuidar." #. (itstool) path: example/title -#: C/index.docbook:1748 +#: C/index.docbook:1754 msgid "Master document header" msgstr "Cabeçalho do documento mestre" #. (itstool) path: example/programlisting -#: C/index.docbook:1749 +#: C/index.docbook:1755 #, no-wrap msgid "" "\n" @@ -2967,7 +2964,7 @@ msgstr "" " <title>[Insira o título aqui]</title>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1765 +#: C/index.docbook:1771 msgid "" "In addition a few option elements are created in commented form. You can " "review these and enable them as you like." @@ -2976,12 +2973,12 @@ msgstr "" "pode revisá-los e habilitá-los como preferir." #. (itstool) path: example/title -#: C/index.docbook:1771 +#: C/index.docbook:1777 msgid "Optional part in the master document" msgstr "Parte opcional do documento mestre" #. (itstool) path: example/programlisting -#: C/index.docbook:1772 +#: C/index.docbook:1778 #, no-wrap msgid "" "\n" @@ -2995,7 +2992,7 @@ msgstr "" " -->\n" #. (itstool) path: sect1/para -#: C/index.docbook:1780 +#: C/index.docbook:1786 msgid "" "Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind " @@ -3007,12 +3004,12 @@ msgstr "" "incluídos na documentação." #. (itstool) path: example/title -#: C/index.docbook:1788 C/index.docbook:1823 +#: C/index.docbook:1794 C/index.docbook:1829 msgid "Including generated sections" msgstr "Incluindo seções geradas" #. (itstool) path: example/programlisting -#: C/index.docbook:1789 +#: C/index.docbook:1795 #, no-wrap msgid "" "\n" @@ -3028,12 +3025,12 @@ msgstr "" " ...\n" #. (itstool) path: sect1/title -#: C/index.docbook:1801 +#: C/index.docbook:1807 msgid "Editing the section file" msgstr "Editando o arquivo de seção" #. (itstool) path: sect1/para -#: C/index.docbook:1803 +#: C/index.docbook:1809 msgid "" "The section file is used to organise the documentation output by GTK-Doc. " "Here one specifies which symbol belongs to which module or class and control " @@ -3044,7 +3041,7 @@ msgstr "" "e controla a visibilidade (pública ou privada)." #. (itstool) path: sect1/para -#: C/index.docbook:1809 +#: C/index.docbook:1815 msgid "" "The section file is a plain text file with tags delimiting sections. Blank " "lines are ignored and lines starting with a '#' are treated as comment lines." @@ -3054,7 +3051,7 @@ msgstr "" "tratadas como linhas de comentários." #. (itstool) path: note/para -#: C/index.docbook:1816 +#: C/index.docbook:1822 msgid "" "While the tags make the file look like xml, it is not. Please do not close " "tags like <SUBSECTION>." @@ -3063,7 +3060,7 @@ msgstr "" "feche tags como <SUBSECTION>." #. (itstool) path: example/programlisting -#: C/index.docbook:1824 +#: C/index.docbook:1830 #, no-wrap msgid "" "\n" @@ -3095,7 +3092,7 @@ msgstr "" "</SECTION>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1841 +#: C/index.docbook:1847 msgid "" "The <FILE> ... </FILE> tag is used to specify the file name, " "without any suffix. For example, using '<FILE>gnome-config</" @@ -3118,7 +3115,7 @@ msgstr "" "para minúsculos)." #. (itstool) path: sect1/para -#: C/index.docbook:1853 +#: C/index.docbook:1859 msgid "" "The <TITLE> ... </TITLE> tag is used to specify the title of the " "section. It is only useful before the templates (if used) are initially " @@ -3132,7 +3129,7 @@ msgstr "" "obsoleto." #. (itstool) path: sect1/para -#: C/index.docbook:1860 +#: C/index.docbook:1866 msgid "" "You can group items in the section by using the <SUBSECTION> tag. " "Currently it outputs a blank line between subsections in the synopsis " @@ -3161,7 +3158,7 @@ msgstr "" "padrão ou pública depende se há entradas públicas (variáveis, vmethods)." #. (itstool) path: sect1/para -#: C/index.docbook:1879 +#: C/index.docbook:1885 msgid "" "You can also use <INCLUDE> ... </INCLUDE> to specify the " "#include files which are shown in the synopsis sections. It contains a comma-" @@ -3177,12 +3174,12 @@ msgstr "" "aplicar àquela seção." #. (itstool) path: chapter/title -#: C/index.docbook:1893 +#: C/index.docbook:1899 msgid "Controlling the result" msgstr "Controlando o resultado" #. (itstool) path: chapter/para -#: C/index.docbook:1895 +#: C/index.docbook:1901 msgid "" "A GTK-Doc run generates report files inside the documentation directory. The " "generated files are named: <package>-undocumented.txt<package>-undocumented.txt file starts with " "the documentation coverage summary. Below are two sections divided by blank " @@ -3214,7 +3211,7 @@ msgstr "" "exemplo, um novo parâmetro foi adicionado." #. (itstool) path: chapter/para -#: C/index.docbook:1913 +#: C/index.docbook:1919 msgid "" "The <package>-undeclared.txt file lists symbols " "given in the <package>-sections.txt but not found " @@ -3226,7 +3223,7 @@ msgstr "" "escritos incorretamente." #. (itstool) path: chapter/para -#: C/index.docbook:1920 +#: C/index.docbook:1926 msgid "" "The <package>-unused.txt file lists symbol names, " "where the GTK-Doc scanner has found documentation, but does not know where " @@ -3239,7 +3236,7 @@ msgstr "" "ainda ao arquivo <pacote>-sections.txt." #. (itstool) path: tip/para -#: C/index.docbook:1928 +#: C/index.docbook:1934 msgid "" "Enable or add the line in Makefile." "am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during " @@ -3250,7 +3247,7 @@ msgstr "" "verificações de sanidade durante a execução de make check." #. (itstool) path: chapter/para -#: C/index.docbook:1935 +#: C/index.docbook:1941 msgid "" "One can also look at the files produced by the source code scanner: " "<package>-decl-list.txt and <" @@ -3267,7 +3264,7 @@ msgstr "" "este arquivo o contém." #. (itstool) path: chapter/para -#: C/index.docbook:1944 +#: C/index.docbook:1950 msgid "" "If the project is GObject based, one can also look into the files produced " "by the object scanner: <package>.args.txt, " @@ -3288,12 +3285,12 @@ msgstr "" "executando GTK_DOC_KEEP_INTERMEDIATE=1 make." #. (itstool) path: chapter/title -#: C/index.docbook:1959 +#: C/index.docbook:1965 msgid "Modernizing the documentation" msgstr "Modernizando a documentação" #. (itstool) path: chapter/para -#: C/index.docbook:1961 +#: C/index.docbook:1967 msgid "" "GTK-Doc has been around for quite some time. In this section we list new " "features together with the version since when it is available." @@ -3302,12 +3299,12 @@ msgstr "" "funcionalidades juntamente da versão desde a qual está disponível." #. (itstool) path: sect1/title -#: C/index.docbook:1967 +#: C/index.docbook:1973 msgid "GTK-Doc 1.9" msgstr "GTK-Doc 1.9" #. (itstool) path: sect1/para -#: C/index.docbook:1969 +#: C/index.docbook:1975 msgid "" "When using xml instead of sgml, one can actually name the master document " "<package>-docs.xml." @@ -3316,7 +3313,7 @@ msgstr "" "<pacote>-docs.xml." #. (itstool) path: sect1/para -#: C/index.docbook:1974 +#: C/index.docbook:1980 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3337,7 +3334,7 @@ msgstr "" "meld <package>-decl-list.txt <package>-sections.txt." #. (itstool) path: sect1/para -#: C/index.docbook:1985 +#: C/index.docbook:1991 msgid "" "Version 1.8 already introduced the syntax for documenting sections in the " "sources instead of the separate files under configure.ac e está resolvido." #. (itstool) path: sect1/title -#: C/index.docbook:1997 +#: C/index.docbook:2003 msgid "GTK-Doc 1.10" msgstr "GTK-Doc 1.10" #. (itstool) path: sect1/para -#: C/index.docbook:1999 +#: C/index.docbook:2005 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3380,17 +3377,17 @@ msgstr "" "código que é compilado condicionalmente." #. (itstool) path: sect1/title -#: C/index.docbook:2010 +#: C/index.docbook:2016 msgid "GTK-Doc 1.16" msgstr "GTK-Doc 1.16" #. (itstool) path: example/title -#: C/index.docbook:2016 +#: C/index.docbook:2022 msgid "Enable gtkdoc-check" msgstr "Habilitar gtkdoc-check" #. (itstool) path: example/programlisting -#: C/index.docbook:2017 +#: C/index.docbook:2023 #, no-wrap msgid "" "\n" @@ -3410,7 +3407,7 @@ msgstr "" "endif\n" #. (itstool) path: sect1/para -#: C/index.docbook:2012 +#: C/index.docbook:2018 msgid "" "This version includes a new tool called gtkdoc-check. This tool can run a " "set of sanity checks on your documentation. It is enabled by adding these " @@ -3422,12 +3419,12 @@ msgstr "" "filename>. <_:example-1/>" #. (itstool) path: sect1/title -#: C/index.docbook:2030 +#: C/index.docbook:2036 msgid "GTK-Doc 1.20" msgstr "GTK-Doc 1.20" #. (itstool) path: sect1/para -#: C/index.docbook:2032 +#: C/index.docbook:2038 msgid "" "Version 1.18 brought some initial markdown support. Using markdown in doc " "comments is less intrusive than writing docbook xml. This version improves a " @@ -3441,17 +3438,17 @@ msgstr "" "comentário tem todos os detalhes." #. (itstool) path: sect1/title -#: C/index.docbook:2042 +#: C/index.docbook:2048 msgid "GTK-Doc 1.25" msgstr "GTK-Doc 1.25" #. (itstool) path: example/title -#: C/index.docbook:2052 +#: C/index.docbook:2058 msgid "Use pre-generated entities" msgstr "Usando entradas geradas previamente" #. (itstool) path: example/programlisting -#: C/index.docbook:2053 +#: C/index.docbook:2059 #, no-wrap msgid "" "\n" @@ -3493,7 +3490,7 @@ msgstr "" " </bookinfo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:2044 +#: C/index.docbook:2050 msgid "" "The makefiles shipped with this version generate an entity file at " "xml/gtkdocentities.ent, containing entities for e.g. " @@ -3513,12 +3510,12 @@ msgstr "" "xml nos arquivos xml gerados. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:2078 +#: C/index.docbook:2084 msgid "Documenting other interfaces" msgstr "Documentando outras interfaces" #. (itstool) path: chapter/para -#: C/index.docbook:2080 +#: C/index.docbook:2086 msgid "" "So far we have been using GTK-Doc to document the API of code. The next " "sections contain suggestions how the tools can be used to document other " @@ -3529,13 +3526,13 @@ msgstr "" "para documentar outras interfaces, também." #. (itstool) path: sect1/title -#: C/index.docbook:2087 +#: C/index.docbook:2093 msgid "Command line options and man pages" msgstr "Opções de linha de comando e de páginas man" # RefEntry é uma página de referência do DocBook (http://www.docbook.org/tdg/en/html/refentry.html) #. (itstool) path: sect1/para -#: C/index.docbook:2089 +#: C/index.docbook:2095 msgid "" "As one can generate man pages for a docbook refentry as well, it sounds like " "a good idea to use it for that purpose. This way the interface is part of " @@ -3546,12 +3543,12 @@ msgstr "" "parte da referência e é possível obter a página man de graça." #. (itstool) path: sect2/title -#: C/index.docbook:2096 +#: C/index.docbook:2102 msgid "Document the tool" msgstr "Documentar a ferramenta" #. (itstool) path: sect2/para -#: C/index.docbook:2098 +#: C/index.docbook:2104 msgid "" "Create one refentry file per tool. Following our example we would call it meep/" @@ -3566,17 +3563,17 @@ msgstr "" "assim como exemplos, por exemplo, em glib." #. (itstool) path: sect2/title -#: C/index.docbook:2108 +#: C/index.docbook:2114 msgid "Adding the extra configure check" msgstr "Adicionando a verificação extra ao configure" #. (itstool) path: example/title -#: C/index.docbook:2111 C/index.docbook:2129 +#: C/index.docbook:2117 C/index.docbook:2135 msgid "Extra configure checks" msgstr "Verificações extra no configure" #. (itstool) path: example/programlisting -#: C/index.docbook:2112 +#: C/index.docbook:2118 #, no-wrap msgid "" "\n" @@ -3598,12 +3595,12 @@ msgstr "" "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" #. (itstool) path: sect2/title -#: C/index.docbook:2126 +#: C/index.docbook:2132 msgid "Adding the extra makefile rules" msgstr "Adicionando as regras extras ao makefile" #. (itstool) path: example/programlisting -#: C/index.docbook:2130 +#: C/index.docbook:2136 #, no-wrap msgid "" "\n" @@ -3639,12 +3636,12 @@ msgstr "" "EXTRA_DIST += meep.xml\n" #. (itstool) path: sect1/title -#: C/index.docbook:2152 +#: C/index.docbook:2158 msgid "DBus interfaces" msgstr "Interfaces DBus" #. (itstool) path: sect1/para -#: C/index.docbook:2154 +#: C/index.docbook:2160 msgid "" "(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" @@ -3653,27 +3650,27 @@ msgstr "" "http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" #. (itstool) path: chapter/title -#: C/index.docbook:2163 +#: C/index.docbook:2169 msgid "Frequently asked questions" msgstr "Perguntas frequentes" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2167 +#: C/index.docbook:2173 msgid "Question" msgstr "Questão" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2168 +#: C/index.docbook:2174 msgid "Answer" msgstr "Resposta" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2170 +#: C/index.docbook:2176 msgid "No class hierarchy." msgstr "Sem hierarquia de classe." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2171 +#: C/index.docbook:2177 msgid "" "The objects xxx_get_type() function has not been " "entered into the <package>.types file." @@ -3682,12 +3679,12 @@ msgstr "" "arquivo <pacote>.types." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2177 +#: C/index.docbook:2183 msgid "Still no class hierarchy." msgstr "Ainda sem hierarquia." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2178 +#: C/index.docbook:2184 msgid "" "Missing or wrong naming in <package>-sections.txt " "file (see explicação)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2184 +#: C/index.docbook:2190 msgid "Damn, I have still no class hierarchy." msgstr "Droga. Eu ainda não tenho hierarquia de classes." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2185 +#: C/index.docbook:2191 msgid "" "Is the object name (name of the instance struct, e.g. GtkWidget) part of the normal section (don't put this into Standard or Private " @@ -3714,12 +3711,12 @@ msgstr "" "subseções Standard ou Private)?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2192 +#: C/index.docbook:2198 msgid "No symbol index." msgstr "Nenhum símbolo de índice." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2193 +#: C/index.docbook:2199 msgid "" "Does the <package>-docs.{xml,sgml} contain a " "index that xi:includes the generated index?" @@ -3728,12 +3725,12 @@ msgstr "" "“xi:inclui” o índice gerado?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2199 +#: C/index.docbook:2205 msgid "Symbols are not linked to their doc-section." msgstr "Símbolos não estão vinculados ao seus doc-section." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2200 +#: C/index.docbook:2206 msgid "" "Is the doc-comment using the correct markup (added #,% or ())? Check if the " "gtkdoc-fixxref warns about unresolvable xrefs." @@ -3742,12 +3739,12 @@ msgstr "" "Verifique se o gtkdoc-fixxref avisa sobre xrefs não resolvidos." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2206 +#: C/index.docbook:2212 msgid "A new class does not appear in the docs." msgstr "Uma nova classe não aparece nos documentos." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2207 +#: C/index.docbook:2213 msgid "" "Is the new page xi:included from <package>-docs.{xml,sgml}." @@ -3756,12 +3753,12 @@ msgstr "" "filename>?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2213 +#: C/index.docbook:2219 msgid "A new symbol does not appear in the docs." msgstr "Um novo símbolo não aparece nos documentos." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2214 +#: C/index.docbook:2220 msgid "" "Is the doc-comment properly formatted. Check for spelling mistakes in the " "begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable " @@ -3774,12 +3771,12 @@ msgstr "" "<pacote>-sections.txt em uma subseção pública." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2222 +#: C/index.docbook:2228 msgid "A type is missing from the class hierarchy." msgstr "Um tipo está faltando da hierarquia de classe." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2223 +#: C/index.docbook:2229 msgid "" "If the type is listed in <package>.hierarchy but " "not in xml/tree_index.sgml then double check that the " @@ -3794,13 +3791,13 @@ msgstr "" "listada ou incidentalmente marcada como privada, ela não será mostrada." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2232 +#: C/index.docbook:2238 msgid "I get foldoc links for all gobject annotations." msgstr "" "Obtenho links de seguimento de documentos para todas as anotações gobject." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2233 +#: C/index.docbook:2239 msgid "" "Check that xml/annotation-glossary.xml is xi:included " "from <package>-docs.{xml,sgml}." @@ -3809,12 +3806,12 @@ msgstr "" "incluído” de <pacote>-docs.{xml,sgml}." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2241 +#: C/index.docbook:2247 msgid "Parameter described in source code comment block but does not exist" msgstr "Parâmetro descrito no bloco de comentário do código fonte não existe" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2242 +#: C/index.docbook:2248 msgid "" "Check if the prototype in the header has different parameter names as in the " "source." @@ -3823,12 +3820,12 @@ msgstr "" "fonte." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2247 +#: C/index.docbook:2253 msgid "multiple \"IDs\" for constraint linkend: XYZ" msgstr "múltiplos “IDs” para restrições do fim do link XYZ" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2248 +#: C/index.docbook:2254 msgid "" "Symbol XYZ appears twice in <package>-sections.txt file." @@ -3837,7 +3834,7 @@ msgstr "" "sections.txt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2251 +#: C/index.docbook:2257 msgid "" "Element typename in namespace '' encountered in para, but no template " "matches." @@ -3846,12 +3843,12 @@ msgstr "" "correspondeu." #. (itstool) path: chapter/title -#: C/index.docbook:2258 +#: C/index.docbook:2264 msgid "Tools related to gtk-doc" msgstr "Ferramentas relacionadas ao gtk-doc" #. (itstool) path: chapter/para -#: C/index.docbook:2260 +#: C/index.docbook:2266 msgid "" "GtkDocPlugin - a Trac " "GTK-Doc integration plugin, that adds API docs to a trac site and " @@ -3862,7 +3859,7 @@ msgstr "" "a um site trac e integra com a pesquisa do trac." #. (itstool) path: chapter/para -#: C/index.docbook:2265 +#: C/index.docbook:2271 msgid "" "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " "tags in the API to determine the minimum required version." diff --git a/help/manual/sl/index.docbook b/help/manual/sl/index.docbook index 2fd8f4b..c7011f9 100644 --- a/help/manual/sl/index.docbook +++ b/help/manual/sl/index.docbook @@ -81,6 +81,12 @@ + 1.29 + 28 Aug 2018 + ss + development + + 1.28 24 Mar 2018 ss @@ -238,8 +244,7 @@ Writing the documentation. The author fills in the source files with the documentation for each - function, macro, union etc. (In the past information was entered in - generated template files, which is not recommended anymore). + function, macro, structs or unions, etc. @@ -341,11 +346,21 @@ About GTK-Doc + 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. + + + (FIXME) - (History, authors, web pages, mailing list, license, future plans, + (authors, web pages, mailing list, license, future plans, comparison with other similar systems.) @@ -367,37 +382,94 @@ - Setting up your project + Project Setup + + + This Chapter describes the steps that are necessary to integrate GTK-Doc + into your project. The integration of GTK-Doc into a project includes the + following steps: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + - 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 plain - makefiles or other build systems will describe the basics needed to - work in a different build setup. + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. Setting up a skeleton documentation - 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 + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. - This can then look as shown below: - Example directory structure + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project - - Integration with autoconf - + + Integration with Autotools - Very easy! Just add one line to your configure.ac script. + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + + + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - Integration with autoconf - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - - 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 - GTK_DOC_CHECK at the start of a line. - Keep gtk-doc optional - + + Integration with automake + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + + +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ + - - - The first argument is used to check for the gtkdocversion at configure time. - The 2nd, optional argument is used by gtkdocize. - The GTK_DOC_CHECK macro also adds several configure switches: - - - --with-html-dir=PATH : path to installed docs - --enable-gtk-doc : use gtk-doc to build documentation [default=no] - --enable-gtk-doc-html : build documentation in html format [default=yes] - --enable-gtk-doc-pdf : build documentation in pdf format [default=no] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. + + All settings have a comment above them that describes their purpose + and how to customize the setting. - - - GTK-Doc is disabled by default! Remember to pass the option - to the next - configure run. Otherwise pregenerated documentation is installed - (which makes sense for users but not for developers). + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). + + All the tools support to list the supported + options. - - - Furthermore it is recommended that you have the following line inside - your configure.ac script. - This allows gtkdocize to automatically copy the - macro definition for GTK_DOC_CHECK to your project. - + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. - - Preparation for gtkdocize - + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + Integration with autoconf + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - - After all changes to configure.ac are made, update - the configure file. This can be done by re-running - autoreconf -i or autogen.sh. - - + + - - Integration with automake + + 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: - - First copy the Makefile.am from the - examples sub directory of the - gtkdoc-sources - to your project's API documentation directory ( - ./docs/reference/<package>). - A local copy should be available under e.g. - /usr/share/doc/gtk-doc-tools/examples/Makefile.am. - If you have multiple doc-packages repeat this for each one. - + + Integration with optional gtk-doc dependency + + + - - The next step is to edit the settings inside the Makefile.am. - 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 . - All the tools support to list the supported - parameters. - + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - + + --with-html-dir=PATH : path to installed docs + --enable-gtk-doc : use gtk-doc to build documentation [default=no] + --enable-gtk-doc-html : build documentation in html format [default=yes] + --enable-gtk-doc-pdf : build documentation in pdf format [default=no] + - + + + GTK-Doc is disabled by default! Remember to pass the option + to the next + configure run. Otherwise pregenerated documentation is installed + (which makes sense for users but not for developers). + + - - Integration with autogen + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - - Most projects will have an autogen.sh 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 - gtkdocize which can be used in such a script. - It should be run before autoheader, automake or autoconf. - + + Integration with autogen - - Running gtkdocize from autogen.sh - + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + + + + It should be run before autoreconf, autoheader, automake or autoconf. + + + + Running gtkdocize from autogen.sh + - - + + - - When running gtkdocize it copies - gtk-doc.make to your project root (or any directory - specified by the option). - It also checks you configure script for the GTK_DOC_CHECK - invocation. This macro can be used to pass extra parameters to - gtkdocize. - + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - - 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. gtkdocize supports now - a 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 GTKDOCIZE_FLAGS - or set as a 2nd parameter in GTK_DOC_CHECK 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). - - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - Running the doc build + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - - After the previous steps it's time to run the build. First we need to - rerun autogen.sh. If this script runs configure for - you, then give it the option. - Otherwise manually run configure with this option - afterwards. - - - The first make run generates several additional files in the doc-directories. - The important ones are: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt. - - - Running the doc build - + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + + After the previous steps it's time to run the build. First we need to + rerun autogen.sh. If this script runs configure + for you, then give it the option. + Otherwise manually run configure with this option + afterwards. + + + The first make run generates several additional files in the doc-directories. + The important ones are: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt. + + + Running the doc build + - - - - Now you can point your browser to docs/reference/<package>/index.html. - Yes, it's a bit disappointing still. But hang-on, during the next chapter we - tell you how to fill the pages with life. - + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - Integration with version control systems + + Integration with CMake build systems - As a rule of thumb, it's the files you edit which should go under - version control. For typical projects it's these files: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt, - Makefile.am. + GTK-Doc now provides a GtkDocConfig.cmake module + (and the corresponding GtkDocConfigVersion.cmake + module). This provides a gtk_doc_add_module + command that you can set in your CMakeLists.txt + file. + - Files in the xml/ and html/ - directories should not go under version control. Neither should any of - the .stamp files. + The following example shows how to use this command. + Example of using GTK-Doc from CMake + + - + Integration with plain makefiles or other build systems @@ -633,42 +961,24 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html - - Integration with CMake build systems - - - GTK-Doc now provides a GtkDocConfig.cmake module - (and the corresponding GtkDocConfigVersion.cmake - module). This provides a gtk_doc_add_module - command that you can set in your CMakeLists.txt - file. - - - - The following example shows how to use this command. - Example of using GTK-Doc from CMake - + Integration with version control systems -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + + As a rule of thumb, it's the files you edit which should go under + version control. For typical projects it's these files: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt, + Makefile.am. + + + Files in the xml/ and html/ + directories should not go under version control. Neither should any of + the .stamp files. + + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - - @@ -681,25 +991,10 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html syntax of the comments. - - Documentation placement - - In the past most documentation had to be filled into files residing - inside the tmpl 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. - - - The avoid the aforementioned problems we suggest putting the - documentation inside the sources. This manual will only describe this - way of documenting code. - - - - The scanner can handle the majority of C headers fine. In the case of - receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + The GTK-Doc scanner can handle the majority of C headers fine. In the + case of receiving warnings from the scanner that look like a special + case, one can hint GTK-Doc to skip over them. GTK-Doc comment block As already mentioned earlier GTK-Doc is for documenting public API. Thus one cannot write documentation for static symbols. Nevertheless it is good - to comment those symbols too. This helps other to understand you code. + to comment those symbols too. This helps other developers to understand + your code. Therefore we recommend to comment these using normal comments (without the 2nd '*' in the first line). If later the function needs to be made public, all one needs to do is to @@ -1689,7 +1985,7 @@ int main(int argc, char *argv[]) - Example types file snippet + Example <package>.types file @@ -2046,7 +2342,8 @@ endif containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included - and how the entities are used. The entities can also be used in all + in the master template and how the entities are used. + The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities diff --git a/help/manual/sv/index.docbook b/help/manual/sv/index.docbook index 34ff0de..94291c5 100644 --- a/help/manual/sv/index.docbook +++ b/help/manual/sv/index.docbook @@ -35,28 +35,29 @@ - 1.28 - 24 Mar 2018 + 1.29 + 28 Aug 2018 ss - bug fixes + development - 1.27 07 Dec 2017 ss finjustering av python-porteringen - 1.26 11 Aug 2017 ss portera alla verktyg från perl/bash till python - 1.25 21 Mars 2016 ss programfixar, uppstädning av tester - 1.24 29 Maj 2015 ss programfix - 1.23 17 Maj 2015 ss programfix - 1.22 07 Maj 2015 ss programfixar, borttagning av föråldrade funktioner - 1.21 17 Jul 2014 ss programfixar, borttagning av föråldrade funktioner - 1.20 16 Feb 2014 ss programfixar, stöd för markdown, stilförbättringar - 1.19 05 Jun 2013 ss programfixar - 1.18 14 Sep 2011 ss programfixar, uppsnabbningar, stöd för markdown - 1.17 26 Feb 2011 sk brådskande programfixuppdatering - 1.16 14 Jan 2011 sk programfixar, layoutförbättringar - 1.15 21 Maj 2010 sk program- och regressionsfixar - 1.14 28 Mars 2010 sk programfixar och prestandaförbättringar - 1.13 18 December 2009 sk uppdatering på grund av trasigt tar-arkiv - 1.12 18 December 2009 sk nya verktygsfunktioner och programfixar - 1.11 16 November 2008 mal GNOME doc-utils migration + 1.28 24 mar 2018 ss programfixar + 1.27 07 dec 2017 ss finjustering av python-porteringen + 1.26 11 aug 2017 ss portera alla verktyg från perl/bash till python + 1.25 21 mars 2016 ss programfixar, uppstädning av tester + 1.24 29 maj 2015 ss programfix + 1.23 17 maj 2015 ss programfix + 1.22 07 maj 2015 ss programfixar, borttagning av föråldrade funktioner + 1.21 17 jul 2014 ss programfixar, borttagning av föråldrade funktioner + 1.20 16 feb 2014 ss programfixar, stöd för markdown, stilförbättringar + 1.19 05 jun 2013 ss programfixar + 1.18 14 sep 2011 ss programfixar, uppsnabbningar, stöd för markdown + 1.17 26 feb 2011 sk brådskande programfixuppdatering + 1.16 14 jan 2011 sk programfixar, layoutförbättringar + 1.15 21 maj 2010 sk program- och regressionsfixar + 1.14 28 mars 2010 sk programfixar och prestandaförbättringar + 1.13 18 december 2009 sk uppdatering på grund av trasigt tar-arkiv + 1.12 18 december 2009 sk nya verktygsfunktioner och programfixar + 1.11 16 november 2008 mal GNOME doc-utils migration @@ -125,7 +126,12 @@ - Skriva dokumentationen. 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). + + Writing the documentation. + + The author fills in the source files with the documentation for each + function, macro, structs or unions, etc. + @@ -162,9 +168,22 @@ Om GTK-Doc + + 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. + + (FIXME) - (Historia, författare, webbsidor, sändlistor, licens, framtida planer, jämförelse med andra liknande system.) + + (authors, web pages, mailing list, license, future plans, + comparison with other similar systems.) + @@ -180,131 +199,529 @@ - Att ställa in ditt projekt + Project Setup - 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 vanliga makefiler eller andra byggsystem att beskriva de grundläggande sakerna som behöver fungera i ett annat byggsystem. + + 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: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + + + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. + Att ställa in en skelettstruktur för dokumentation - 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. + + A common convention is to place documentation into a folder called + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. + - Detta kan se ut enligt nedan: Exempel på katalogstruktur - + + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project + - +]]> + + - - Integrering med autoconf - - Väldigt enkelt! Bara lägg till en rad till ditt configure.ac-skript. + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + + + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - Integrering med autoconf - -# check for gtk-doc -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - 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 GTK_DOC_CHECK i början på en rad. Låt gtk-doc vara valfritt + + Integrering med automake + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + -# check for gtk-doc -m4_ifdef([GTK_DOC_CHECK], [ -GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) -],[ -AM_CONDITIONAL([ENABLE_GTK_DOC], false) -]) +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ - + - Det första argumentet används för att leta efter gtkdoc-versionen under konfigurationen. Det andra, valfria, argumentet används av gtkdocize. Makrot GTK_DOC_CHECK lägger också till flera configure-flaggor: - - --with-html-dir=SÖKVÄG : sökväg till installerad dokumentation - --enable-gtk-doc : använd gtk-doc för att bygga dokumentation [standardvärde=no] - --enable-gtk-doc-html : bygg dokumentation i html-format [standardvärde=yes] - --enable-gtk-doc-pdf : bygg dokumentation i pdf-format [standardvärde=no] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. - - GTK-Doc är inaktiverat som standard! Kom ihåg att skicka flaggan vid nästa körning av configure. Annars kommer förgenererad dokumentation att installeras (vilket är rimligt för användare men inte för utvecklare). - + All settings have a comment above them that describes their purpose + and how to customize the setting. - Vidare rekommenderas det att du har följande rad i ditt configure.ac-skript. Den låter gtkdocize automatiskt kopiera makrodefinitionen för GTK_DOC_CHECK till ditt projekt. + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). - - Förberedelse för gtkdocize - + All the tools support to list the supported + options. + + + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. + + + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + Integrering med autoconf + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - Efter att alla ändringar i configure.ac är gjorda, uppdatera filen configure. Detta kan göras genom att köra om autoreconf -i eller autogen.sh. - +# optional: register gtk-doc in configure +GTK_DOC_CHECK([1.28]) +]]> + + + + + 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: + + + Integration with optional gtk-doc dependency + + + - - Integrering med automake + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - Kopiera först Makefile.am från underkatalogen examples från gtkdoc-sources till ditt projekts API-dokumentationskatalog ( ./docs/reference/<paket>). En lokal kopia bör finnas tillgänglig under t.ex. /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Om du har flera dok-paket, repetera detta för vart och ett. + + --with-html-dir=SÖKVÄG : sökväg till installerad dokumentation + --enable-gtk-doc : använd gtk-doc för att bygga dokumentation [standardvärde=no] + --enable-gtk-doc-html : bygg dokumentation i html-format [standardvärde=yes] + --enable-gtk-doc-pdf : bygg dokumentation i pdf-format [standardvärde=no] + - Nästa steg är att redigera inställningarna inuti Makefile.am. 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 . Alla verktygen har stöd för för att lista de parametrar som stöds. + + GTK-Doc är inaktiverat som standard! Kom ihåg att skicka flaggan vid nästa körning av configure. Annars kommer förgenererad dokumentation att installeras (vilket är rimligt för användare men inte för utvecklare). + - + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - + + Integrering med autogen - - Integrering med autogen + + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + - De flesta projekt kommer att ha ett autogen.sh-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 gtkdocize som kan användas i ett sådant skript. Det bör köras före autoheader, automake eller autoconf. + + It should be run before autoreconf, autoheader, automake or autoconf. + - - Köra gtkdocize från autogen.sh - + + Köra gtkdocize från autogen.sh + gtkdocize || exit 1 - - + + - När gtkdocize kör kopierar det gtk-doc.make till din projektrot (eller den katalog som anges med flaggan ). Det kontrollerar också ditt configure-skript efter ett anrop till GTK_DOC_CHECK. Detta makro kan användas för att skicka extra parametrar till gtkdocize. + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - 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. gtkdocize har nu stöd för flaggan 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 GTKDOCIZE_FLAGS eller inställd som en andra parameter i makrot GTK_DOC_CHECK 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). - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - Att köra dokumentationsbygget + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - Efter de tidigare stegen är det dags att köra bygget. Först måste vi köra om autogen.sh. Om detta skript kör configure åt dig, kan du ge det flaggan . Annars kör manuellt configure med denna flagga efteråt. - Den första körningen av make genererar flera extra filer i doc-katalogerna. De viktiga är <paket>.types, <paket>-docs.xml (tidigare .sgml), <paket>-sections.txt. - - Att köra dokumentationsbygget - + + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + Efter de tidigare stegen är det dags att köra bygget. Först måste vi köra om autogen.sh. Om detta skript kör configure åt dig, kan du ge det flaggan . Annars kör manuellt configure med denna flagga efteråt. + Den första körningen av make genererar flera extra filer i doc-katalogerna. De viktiga är <paket>.types, <paket>-docs.xml (tidigare .sgml), <paket>-sections.txt. + + Att köra dokumentationsbygget + ./autogen.sh --enable-gtk-doc make - - - Du kan nu peka din webbläsare till docs/reference/<paket>/index.html. 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. + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - Integrering med versionshanteringssystem + + Integrering med CMake-byggsystem - Som en tumregel är det filerna du redigerar som bör versionshanteras. För typiska projekt är det följande filer: <paket>.types, <paket>-docs.xml (tidigare .sgml), <paket>-sections.txt, Makefile.am. - Filer i katalogerna xml/ och html/ bör inte versionshanteras. Detsamma gäller .stamp-filerna. + GTK-Doc kommer nu att producera en GtkDocConfig.cmake-modul (och motsvarande GtkDocConfigVersion.cmake-modul). Detta tillhandahåller ett gtk_doc_add_module-kommando som du kan ställa in i din CMakeLists.txt-fil. + + Det följande exemplet visar hur du använder detta kommando. Exempel på användning av GTK-Doc från CMake + +find_package(GtkDoc 1.25 REQUIRED) + +# Skapa målet doc-libmeep. +gtk_doc_add_module( + libmeep ${CMAKE_SOURCE_DIR}/libmeep + XML meep-docs.xml + LIBRARIES libmeep +) + +# Bygg doc-libmeep som standardmålet. Utan detta måste du uttryckligen +# köra något i stil med `make doc-libmeep` för att bygga dokumentationen. +add_custom_target(documentation ALL DEPENDS doc-libmeep) + +# Installera dokumentationen. (Detta förutsätter att du använder CMake-modulen +# GNUInstallDirs för att ställa in variabeln CMAKE_INSTALL_DOCDIR korrekt). +install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html + DESTINATION ${CMAKE_INSTALL_DOCDIR}) + + - + Integrering med vanliga makefiler eller andra byggsystem I det fall man inte vill använda automake och därför inte heller gtk-doc.mak kommer man att behöva anropa gtkdoc-verktygen i rätt ordning i sina egna makefiler (eller andra byggverktyg). @@ -328,33 +745,13 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html Man kommer att behöva titta i Makefile.am och gtk-doc.mak för att plocka ut de extra flaggor som behövs. - - Integrering med CMake-byggsystem - - GTK-Doc kommer nu att producera en GtkDocConfig.cmake-modul (och motsvarande GtkDocConfigVersion.cmake-modul). Detta tillhandahåller ett gtk_doc_add_module-kommando som du kan ställa in i din CMakeLists.txt-fil. - - Det följande exemplet visar hur du använder detta kommando. Exempel på användning av GTK-Doc från CMake - -find_package(GtkDoc 1.25 REQUIRED) - -# Skapa målet doc-libmeep. -gtk_doc_add_module( - libmeep ${CMAKE_SOURCE_DIR}/libmeep - XML meep-docs.xml - LIBRARIES libmeep -) + + Integrering med versionshanteringssystem -# Bygg doc-libmeep som standardmålet. Utan detta måste du uttryckligen -# köra något i stil med `make doc-libmeep` för att bygga dokumentationen. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + Som en tumregel är det filerna du redigerar som bör versionshanteras. För typiska projekt är det följande filer: <paket>.types, <paket>-docs.xml (tidigare .sgml), <paket>-sections.txt, Makefile.am. + Filer i katalogerna xml/ och html/ bör inte versionshanteras. Detsamma gäller .stamp-filerna. + -# Installera dokumentationen. (Detta förutsätter att du använder CMake-modulen -# GNUInstallDirs för att ställa in variabeln CMAKE_INSTALL_DOCDIR korrekt). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) - - - @@ -362,19 +759,18 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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. - - Dokumentationsplacering - Tidigare var det tvunget att fylla i största delen av dokumentationen i filer som fanns i katalogen tmpl. Detta hade nackdelen att informationen ofta inte uppdaterades och att filen också ofta orsakade konflikter med versionshanteringssystem. - 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. - - - 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. GTK-Doc-kommentarsblock - + + 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. + GTK-Doc comment block + - +]]> + + Begränsningar @@ -488,7 +884,17 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Fler exempel på vilka markdown-taggar som stöds hittas i Referensen för GTK+-dokumentationens markdown-syntax. - Som redan nämnts är GTK-Doc avsett för att dokumentera publika API:er. Du kan därför inte skriva dokumentation för statiska symboler. Likväl är det bra att kommentera dessa symboler. Det hjälper andra att förstå din kod. Därför rekommenderar vi att du kommenterar dessa med normala kommenterar (utan den andra ”*” på den första raden). Om funktionen vid ett senare tillfälle måste göras publik är allt du behöver göra att lägga till ytterligare en ”*” i kommentarsblocket och infoga symbolnamnet på rätt ställe i avsnittsfilen. + + 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. + @@ -1030,7 +1436,7 @@ int main(int argc, char *argv[]) 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 xxx_get_type-funktionerna tillsammans med deras huvudfil i filen <package>.types. - Exempel på typfilsnutt + Example <package>.types file #include <gtk/gtk.h> @@ -1211,27 +1617,37 @@ endif GTK-Doc 1.25 - Makefilerna som skeppas med denna version genererar en entitetsfil vid namn xml/gtkdocentities.ent 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. Att använda förgenererade entiteter - -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + + The makefiles shipped with this version generate an entity file at xml/gtkdocentities.ent, + 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. + Use pre-generated entities + + + %gtkdocentities; -]> -<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> - <bookinfo> - <title>&package_name; handbok</title> - <releaseinfo> - för &package_string;. - Den senaste versionen av detta dokument kan hittas på nätet på - <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>. - </releaseinfo> - </bookinfo> - - +]> + + + &package_name; Reference Manual + + for &package_string;. + The latest version of this documentation can be found on-line at + http://[SERVER]/&package_name;/. + + +]]> + + diff --git a/help/manual/sv/sv.po b/help/manual/sv/sv.po index e838e49..6adf467 100644 --- a/help/manual/sv/sv.po +++ b/help/manual/sv/sv.po @@ -1,22 +1,22 @@ # Swedish translation of gtk-doc. -# Copyright © 2009-2017 Free Software Foundation, Inc. +# Copyright © 2009-2018 Free Software Foundation, Inc. # This file is distributed under the same license as the gtk-doc package. # Daniel Nylander , 2009. # Sebastian Rasmussen , 2016. -# Anders Jonsson , 2017. +# Anders Jonsson , 2017, 2018. # msgid "" msgstr "" "Project-Id-Version: gtk-doc master\n" -"POT-Creation-Date: 2017-12-28 10:31+0000\n" -"PO-Revision-Date: 2018-01-04 01:06+0100\n" +"POT-Creation-Date: 2018-03-24 15:17+0000\n" +"PO-Revision-Date: 2018-03-24 22:40+0100\n" "Last-Translator: Anders Jonsson \n" "Language-Team: Swedish \n" "Language: sv\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" -"X-Generator: Poedit 2.0.5\n" +"X-Generator: Poedit 2.0.6\n" #. Put one translator per line, in the form NAME , YEAR1, YEAR2 msgctxt "_" @@ -126,188 +126,197 @@ msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:83 msgid "" -"1.27.1 07 Dec 2017 ss1.28.1 24 Mar 2018 ss development" msgstr "" -"1.27.1 07 Dec 2017 ss1.28.1 24 mar 2018 ss utveckling" #. (itstool) path: revhistory/revision #: C/index.docbook:89 msgid "" +"1.28 24 Mar 2018 ss bug fixes" +msgstr "" +"1.28 24 mar 2018 ss programfixar" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:95 +msgid "" "1.27 07 Dec 2017 ss fine tuning of the python port" msgstr "" -"1.27 07 Dec 2017 ss1.27 07 dec 2017 ss finjustering av python-porteringen" #. (itstool) path: revhistory/revision -#: C/index.docbook:95 +#: C/index.docbook:101 msgid "" "1.26 11 Aug 2017 ss port all tools from perl/bash to python" msgstr "" -"1.26 11 Aug 2017 ss1.26 11 aug 2017 ss portera alla verktyg från perl/bash till python" #. (itstool) path: revhistory/revision -#: C/index.docbook:101 +#: C/index.docbook:107 msgid "" "1.25 21 March 2016 ss bug fixes, test cleanups" msgstr "" -"1.25 21 Mars 2016 ss1.25 21 mars 2016 ss programfixar, uppstädning av tester" #. (itstool) path: revhistory/revision -#: C/index.docbook:107 +#: C/index.docbook:113 msgid "" "1.24 29 May 2015 ss bug fix" msgstr "" -"1.24 29 Maj 2015 ss1.24 29 maj 2015 ss programfix" #. (itstool) path: revhistory/revision -#: C/index.docbook:113 +#: C/index.docbook:119 msgid "" "1.23 17 May 2015 ss bug fix" msgstr "" -"1.23 17 Maj 2015 ss1.23 17 maj 2015 ss programfix" #. (itstool) path: revhistory/revision -#: C/index.docbook:119 +#: C/index.docbook:125 msgid "" "1.22 07 May 2015 ss bug fixes, dropping deprecated features" msgstr "" -"1.22 07 Maj 2015 ss1.22 07 maj 2015 ss programfixar, borttagning av föråldrade " "funktioner" #. (itstool) path: revhistory/revision -#: C/index.docbook:125 +#: C/index.docbook:131 msgid "" "1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" msgstr "" -"1.21 17 Jul 2014 ss1.21 17 jul 2014 ss programfixar, borttagning av föråldrade " "funktioner" #. (itstool) path: revhistory/revision -#: C/index.docbook:131 +#: C/index.docbook:137 msgid "" "1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" msgstr "" -"1.20 16 Feb 2014 ss1.20 16 feb 2014 ss programfixar, stöd för markdown, " "stilförbättringar" #. (itstool) path: revhistory/revision -#: C/index.docbook:137 +#: C/index.docbook:143 msgid "" "1.19 05 Jun 2013 ss bug fixes" msgstr "" -"1.19 05 Jun 2013 ss1.19 05 jun 2013 ss programfixar" #. (itstool) path: revhistory/revision -#: C/index.docbook:143 +#: C/index.docbook:149 msgid "" "1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" msgstr "" -"1.18 14 Sep 2011 ss1.18 14 sep 2011 ss programfixar, uppsnabbningar, stöd för markdown" #. (itstool) path: revhistory/revision -#: C/index.docbook:149 +#: C/index.docbook:155 msgid "" "1.17 26 Feb 2011 sk urgent bug fix update" msgstr "" -"1.17 26 Feb 2011 sk1.17 26 feb 2011 sk brådskande programfixuppdatering" #. (itstool) path: revhistory/revision -#: C/index.docbook:155 +#: C/index.docbook:161 msgid "" "1.16 14 Jan 2011 sk bugfixes, layout improvements" msgstr "" -"1.16 14 Jan 2011 sk1.16 14 jan 2011 sk programfixar, layoutförbättringar" #. (itstool) path: revhistory/revision -#: C/index.docbook:161 +#: C/index.docbook:167 msgid "" "1.15 21 May 2010 sk bug and regression fixes" msgstr "" -"1.15 21 Maj 2010 sk1.15 21 maj 2010 sk program- och regressionsfixar" #. (itstool) path: revhistory/revision -#: C/index.docbook:167 +#: C/index.docbook:173 msgid "" "1.14 28 March 2010 sk bugfixes and performance improvements" msgstr "" -"1.14 28 Mars 2010 sk1.14 28 mars 2010 sk programfixar och prestandaförbättringar" #. (itstool) path: revhistory/revision -#: C/index.docbook:173 +#: C/index.docbook:179 msgid "" "1.13 18 December 2009 " "sk broken tarball update" msgstr "" -"1.13 18 December 2009 " +"1.13 18 december 2009 " "sk uppdatering på grund av " "trasigt tar-arkiv" #. (itstool) path: revhistory/revision -#: C/index.docbook:179 +#: C/index.docbook:185 msgid "" "1.12 18 December 2009 " "sk new tool features and " "bugfixes" msgstr "" -"1.12 18 December 2009 " +"1.12 18 december 2009 " "sk nya verktygsfunktioner och " "programfixar" #. (itstool) path: revhistory/revision -#: C/index.docbook:185 +#: C/index.docbook:191 msgid "" "1.11 16 November 2008 " "mal GNOME doc-utils migration" msgstr "" -"1.11 16 November 2008 " +"1.11 16 november 2008 " "mal GNOME doc-utils migration" #. (itstool) path: chapter/title -#: C/index.docbook:198 +#: C/index.docbook:204 msgid "Introduction" msgstr "Introduktion" #. (itstool) path: chapter/para -#: C/index.docbook:200 +#: C/index.docbook:206 msgid "" "This chapter introduces GTK-Doc and gives an overview of what it is and how " "it is used." @@ -316,12 +325,12 @@ msgstr "" "hur det används." #. (itstool) path: sect1/title -#: C/index.docbook:206 +#: C/index.docbook:212 msgid "What is GTK-Doc?" msgstr "Vad är GTK-Doc?" #. (itstool) path: sect1/para -#: C/index.docbook:208 +#: C/index.docbook:214 msgid "" "GTK-Doc is used to document C code. It is typically used to document the " "public API of libraries, such as the GTK+ and GNOME libraries. But it can " @@ -332,13 +341,13 @@ msgstr "" "biblioteken. Men det kan också användas för att dokumentera programkod." #. (itstool) path: sect1/title -#: C/index.docbook:216 +#: C/index.docbook:222 msgid "How Does GTK-Doc Work?" msgstr "Hur fungerar GTK-Doc?" # sebras: how do I translate header files? #. (itstool) path: sect1/para -#: C/index.docbook:218 +#: C/index.docbook:224 msgid "" "GTK-Doc works by using documentation of functions placed inside the source " "files in specially-formatted comment blocks, or documentation added to the " @@ -353,7 +362,7 @@ msgstr "" "huvudfiler; det kommer inte att producera utdata för statiska funktioner)." #. (itstool) path: sect1/para -#: C/index.docbook:225 +#: C/index.docbook:231 msgid "" "GTK-Doc consists of a number of python scripts, each performing a different " "step in the process." @@ -362,12 +371,12 @@ msgstr "" "i processen." #. (itstool) path: sect1/para -#: C/index.docbook:230 +#: C/index.docbook:236 msgid "There are 5 main steps in the process:" msgstr "Det finns 5 huvudsteg i processen:" #. (itstool) path: listitem/para -#: C/index.docbook:237 +#: C/index.docbook:243 msgid "" "Writing the documentation. The author fills in the " "source files with the documentation for each function, macro, union etc. (In " @@ -381,7 +390,7 @@ msgstr "" # sebras: more header files... #. (itstool) path: listitem/para -#: C/index.docbook:247 +#: C/index.docbook:253 msgid "" "Gathering information about the code. " "gtkdoc-scan scans the header files of the code " @@ -417,7 +426,7 @@ msgstr "" "module>-overrides.txt." #. (itstool) path: listitem/para -#: C/index.docbook:264 +#: C/index.docbook:270 msgid "" "gtkdoc-scangobj can also be used to dynamically " "query a library about any GObject subclasses it exports. It saves " @@ -430,7 +439,7 @@ msgstr "" "vilka GObject-egenskaper och signaler det tillhandahåller." #. (itstool) path: listitem/para -#: C/index.docbook:270 +#: C/index.docbook:276 msgid "" "gtkdoc-scanobj should not be used anymore. It was " "needed in the past when GObject was still GtkObject inside gtk+." @@ -439,7 +448,7 @@ msgstr "" "behövdes tidigare när GObject fortfarande var GtkObject inuti gtk+." #. (itstool) path: listitem/para -#: C/index.docbook:277 +#: C/index.docbook:283 msgid "" "Generating the XML and HTML/PDF. gtkdoc-" "mkdb turns the template files into XML files in the gtkdoc-mkhtml turns the XML files into HTML files " "in the html/ subdirectory. Likewise " @@ -470,7 +479,7 @@ msgstr "" "till ett PDF-dokument kallat <package>.pdf." #. (itstool) path: listitem/para -#: C/index.docbook:292 +#: C/index.docbook:298 msgid "" "Files in xml/ and html/ directories are always overwritten. One " @@ -481,7 +490,7 @@ msgstr "" "aldrig redigera dem direkt." #. (itstool) path: listitem/para -#: C/index.docbook:300 +#: C/index.docbook:306 msgid "" "Fixing up cross-references between documents. After " "installing the HTML files, gtkdoc-fixxref can be " @@ -503,23 +512,23 @@ msgstr "" "(i de fall där dokumentationen finns installerad)." #. (itstool) path: sect1/title -#: C/index.docbook:318 +#: C/index.docbook:324 msgid "Getting GTK-Doc" msgstr "Hämta GTK-Doc" #. (itstool) path: sect2/title -#: C/index.docbook:321 +#: C/index.docbook:327 msgid "Requirements" msgstr "Krav" #. (itstool) path: sect2/para -#: C/index.docbook:322 +#: C/index.docbook:328 msgid "" "python 2/3 - the main scripts are written in python." msgstr "python 2/3 - huvudskripten är skrivna i python." #. (itstool) path: sect2/para -#: C/index.docbook:325 +#: C/index.docbook:331 msgid "" "xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" @@ -528,7 +537,7 @@ msgstr "" "\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/" #. (itstool) path: sect2/para -#: C/index.docbook:329 +#: C/index.docbook:335 msgid "" "docbook-xsl - the docbook xsl stylesheets source-highlight, highlight " "or vim - optional - used for syntax highlighting of " @@ -551,17 +560,17 @@ msgstr "" "syntaxfärgning av exempel" #. (itstool) path: sect1/title -#: C/index.docbook:341 +#: C/index.docbook:347 msgid "About GTK-Doc" msgstr "Om GTK-Doc" #. (itstool) path: sect1/para -#: C/index.docbook:343 C/index.docbook:357 +#: C/index.docbook:349 C/index.docbook:363 msgid "(FIXME)" msgstr "(FIXME)" #. (itstool) path: sect1/para -#: C/index.docbook:347 +#: C/index.docbook:353 msgid "" "(History, authors, web pages, mailing list, license, future plans, " "comparison with other similar systems.)" @@ -570,22 +579,22 @@ msgstr "" "jämförelse med andra liknande system.)" #. (itstool) path: sect1/title -#: C/index.docbook:355 +#: C/index.docbook:361 msgid "About this Manual" msgstr "Om denna handbok" #. (itstool) path: sect1/para -#: C/index.docbook:361 +#: C/index.docbook:367 msgid "(who it is meant for, where you can get it, license)" msgstr "(vem är den avsett för, var kan du få tag i den, licens)" #. (itstool) path: chapter/title -#: C/index.docbook:370 +#: C/index.docbook:376 msgid "Setting up your project" msgstr "Att ställa in ditt projekt" #. (itstool) path: chapter/para -#: C/index.docbook:372 +#: C/index.docbook:378 msgid "" "The next sections describe what steps to perform to integrate GTK-Doc into " "your project. Theses sections assume we work on a project called 'meep'. " @@ -605,12 +614,12 @@ msgstr "" "byggsystem." #. (itstool) path: sect1/title -#: C/index.docbook:383 +#: C/index.docbook:389 msgid "Setting up a skeleton documentation" msgstr "Att ställa in en skelettstruktur för dokumentation" #. (itstool) path: sect1/para -#: C/index.docbook:385 +#: C/index.docbook:391 msgid "" "Under your top-level project directory create folders called docs/reference " "(this way you can also have docs/help for end-user documentation). It is " @@ -624,12 +633,12 @@ msgstr "" "bibliotek är detta steg inte nödvändigt." #. (itstool) path: example/title -#: C/index.docbook:394 +#: C/index.docbook:400 msgid "Example directory structure" msgstr "Exempel på katalogstruktur" #. (itstool) path: example/programlisting -#: C/index.docbook:395 +#: C/index.docbook:401 #, no-wrap msgid "" "\n" @@ -653,18 +662,18 @@ msgstr "" " meeper/\n" #. (itstool) path: sect1/para -#: C/index.docbook:392 +#: C/index.docbook:398 msgid "This can then look as shown below: <_:example-1/>" msgstr "Detta kan se ut enligt nedan: <_:example-1/>" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:410 C/index.docbook:417 +#: C/index.docbook:416 C/index.docbook:423 msgid "Integration with autoconf" msgstr "Integrering med autoconf" #. (itstool) path: sect1/para -#: C/index.docbook:412 +#: C/index.docbook:418 msgid "" "Very easy! Just add one line to your configure.ac " "script." @@ -673,7 +682,7 @@ msgstr "" "filename>-skript." #. (itstool) path: example/programlisting -#: C/index.docbook:418 +#: C/index.docbook:424 #, no-wrap msgid "" "\n" @@ -685,12 +694,12 @@ msgstr "" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" #. (itstool) path: example/title -#: C/index.docbook:430 +#: C/index.docbook:436 msgid "Keep gtk-doc optional" msgstr "Låt gtk-doc vara valfritt" #. (itstool) path: example/programlisting -#: C/index.docbook:431 +#: C/index.docbook:437 #, no-wrap msgid "" "\n" @@ -710,7 +719,7 @@ msgstr "" "])\n" #. (itstool) path: sect1/para -#: C/index.docbook:425 +#: C/index.docbook:431 msgid "" "This will require all developers to have gtk-doc installed. If it is okay " "for your project to have optional api-doc build setup, you can solve this as " @@ -724,7 +733,7 @@ msgstr "" # sebras: or ? #. (itstool) path: sect1/para -#: C/index.docbook:442 +#: C/index.docbook:448 msgid "" "The first argument is used to check for the gtkdocversion at configure time. " "The 2nd, optional argument is used by gtkdocize. " @@ -737,32 +746,32 @@ msgstr "" "lägger också till flera configure-flaggor:" #. (itstool) path: listitem/para -#: C/index.docbook:448 +#: C/index.docbook:454 msgid "--with-html-dir=PATH : path to installed docs" msgstr "--with-html-dir=SÖKVÄG : sökväg till installerad dokumentation" #. (itstool) path: listitem/para -#: C/index.docbook:449 +#: C/index.docbook:455 msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "" "--enable-gtk-doc : använd gtk-doc för att bygga dokumentation " "[standardvärde=no]" #. (itstool) path: listitem/para -#: C/index.docbook:450 +#: C/index.docbook:456 msgid "" "--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" "--enable-gtk-doc-html : bygg dokumentation i html-format [standardvärde=yes]" #. (itstool) path: listitem/para -#: C/index.docbook:451 +#: C/index.docbook:457 msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" msgstr "" "--enable-gtk-doc-pdf : bygg dokumentation i pdf-format [standardvärde=no]" #. (itstool) path: important/para -#: C/index.docbook:455 +#: C/index.docbook:461 msgid "" "GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " @@ -775,7 +784,7 @@ msgstr "" "är rimligt för användare men inte för utvecklare)." #. (itstool) path: sect1/para -#: C/index.docbook:463 +#: C/index.docbook:469 msgid "" "Furthermore it is recommended that you have the following line inside your " "configure.ac script. This allows " @@ -788,12 +797,12 @@ msgstr "" "till ditt projekt." #. (itstool) path: example/title -#: C/index.docbook:471 +#: C/index.docbook:477 msgid "Preparation for gtkdocize" msgstr "Förberedelse för gtkdocize" #. (itstool) path: example/programlisting -#: C/index.docbook:472 +#: C/index.docbook:478 #, no-wrap msgid "" "\n" @@ -803,7 +812,7 @@ msgstr "" "AC_CONFIG_MACRO_DIR(m4)\n" #. (itstool) path: sect1/para -#: C/index.docbook:477 +#: C/index.docbook:483 msgid "" "After all changes to configure.ac are made, update the " "configure file. This can be done by re-running " @@ -814,12 +823,12 @@ msgstr "" "köra om autoreconf -i eller autogen.sh." #. (itstool) path: sect1/title -#: C/index.docbook:485 +#: C/index.docbook:491 msgid "Integration with automake" msgstr "Integrering med automake" #. (itstool) path: sect1/para -#: C/index.docbook:487 +#: C/index.docbook:493 msgid "" "First copy the Makefile.am from the examples sub directory of the Makefile.am. All the settings have a comment above that describes their " @@ -857,12 +866,12 @@ msgstr "" "att lista de parametrar som stöds." #. (itstool) path: sect1/title -#: C/index.docbook:512 +#: C/index.docbook:518 msgid "Integration with autogen" msgstr "Integrering med autogen" #. (itstool) path: sect1/para -#: C/index.docbook:514 +#: C/index.docbook:520 msgid "" "Most projects will have an autogen.sh script to setup " "the build infrastructure after a checkout from version control system (such " @@ -877,12 +886,12 @@ msgstr "" "ett sådant skript. Det bör köras före autoheader, automake eller autoconf." #. (itstool) path: example/title -#: C/index.docbook:523 +#: C/index.docbook:529 msgid "Running gtkdocize from autogen.sh" msgstr "Köra gtkdocize från autogen.sh" #. (itstool) path: example/programlisting -#: C/index.docbook:524 +#: C/index.docbook:530 #, no-wrap msgid "" "\n" @@ -892,7 +901,7 @@ msgstr "" "gtkdocize || exit 1\n" #. (itstool) path: sect1/para -#: C/index.docbook:530 +#: C/index.docbook:536 msgid "" "When running gtkdocize it copies gtk-" "doc.make to your project root (or any directory specified by the " @@ -909,7 +918,7 @@ msgstr "" # sebras: e.g. because of,... it can be...any files in tmpl...and is migrating... or ? gtkdoc or GTK-Doc #. (itstool) path: sect1/para -#: C/index.docbook:539 +#: C/index.docbook:545 msgid "" "Historically GTK-Doc was generating template files where developers entered " "the docs. This turned out to be not so good (e.g. the need for having " @@ -941,12 +950,12 @@ msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:556 C/index.docbook:573 +#: C/index.docbook:562 C/index.docbook:579 msgid "Running the doc build" msgstr "Att köra dokumentationsbygget" #. (itstool) path: sect1/para -#: C/index.docbook:558 +#: C/index.docbook:564 msgid "" "After the previous steps it's time to run the build. First we need to rerun " "autogen.sh. If this script runs configure for you, then " @@ -959,7 +968,7 @@ msgstr "" "configure med denna flagga efteråt." #. (itstool) path: sect1/para -#: C/index.docbook:565 +#: C/index.docbook:571 msgid "" "The first make run generates several additional files in the doc-" "directories. The important ones are: <package>.types." #. (itstool) path: example/programlisting -#: C/index.docbook:574 +#: C/index.docbook:580 #, no-wrap msgid "" "\n" @@ -984,7 +993,7 @@ msgstr "" "make\n" #. (itstool) path: sect1/para -#: C/index.docbook:580 +#: C/index.docbook:586 msgid "" "Now you can point your browser to docs/reference/<package>/" "index.html. Yes, it's a bit disappointing still. But hang-on, " @@ -995,12 +1004,12 @@ msgstr "" "nästa kapitel kommer vi att berätta för dig hur du fyller sidorna med liv." #. (itstool) path: sect1/title -#: C/index.docbook:588 +#: C/index.docbook:594 msgid "Integration with version control systems" msgstr "Integrering med versionshanteringssystem" #. (itstool) path: sect1/para -#: C/index.docbook:590 +#: C/index.docbook:596 msgid "" "As a rule of thumb, it's the files you edit which should go under version " "control. For typical projects it's these files: <package>." @@ -1015,7 +1024,7 @@ msgstr "" "filename>." #. (itstool) path: sect1/para -#: C/index.docbook:598 +#: C/index.docbook:604 msgid "" "Files in the xml/ and html/ " "directories should not go under version control. Neither should any of the " @@ -1026,12 +1035,12 @@ msgstr "" "filerna." #. (itstool) path: sect1/title -#: C/index.docbook:606 +#: C/index.docbook:612 msgid "Integration with plain makefiles or other build systems" msgstr "Integrering med vanliga makefiler eller andra byggsystem" #. (itstool) path: sect1/para -#: C/index.docbook:608 +#: C/index.docbook:614 msgid "" "In the case one does not want to use automake and therefore gtk-" "doc.mak one will need to call the gtkdoc tools in the right order " @@ -1042,12 +1051,12 @@ msgstr "" "verktygen i rätt ordning i sina egna makefiler (eller andra byggverktyg)." #. (itstool) path: example/title -#: C/index.docbook:615 +#: C/index.docbook:621 msgid "Documentation build steps" msgstr "Byggsteg för dokumentation" #. (itstool) path: example/programlisting -#: C/index.docbook:616 +#: C/index.docbook:622 #, no-wrap msgid "" "\n" @@ -1073,7 +1082,7 @@ msgstr "" "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" #. (itstool) path: sect1/para -#: C/index.docbook:630 +#: C/index.docbook:636 msgid "" "One will need to look at the Makefile.am and " "gtk-doc.mak to pick the extra options needed." @@ -1083,12 +1092,12 @@ msgstr "" "behövs." #. (itstool) path: sect1/title -#: C/index.docbook:637 +#: C/index.docbook:643 msgid "Integration with CMake build systems" msgstr "Integrering med CMake-byggsystem" #. (itstool) path: sect1/para -#: C/index.docbook:639 +#: C/index.docbook:645 msgid "" "GTK-Doc now provides a GtkDocConfig.cmake module (and " "the corresponding GtkDocConfigVersion.cmake module). " @@ -1101,12 +1110,12 @@ msgstr "" "kommando som du kan ställa in i din CMakeLists.txt-fil." #. (itstool) path: example/title -#: C/index.docbook:649 +#: C/index.docbook:655 msgid "Example of using GTK-Doc from CMake" msgstr "Exempel på användning av GTK-Doc från CMake" #. (itstool) path: example/programlisting -#: C/index.docbook:650 +#: C/index.docbook:656 #, no-wrap msgid "" "\n" @@ -1148,18 +1157,18 @@ msgstr "" " DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" #. (itstool) path: sect1/para -#: C/index.docbook:647 +#: C/index.docbook:653 msgid "The following example shows how to use this command. <_:example-1/>" msgstr "" "Det följande exemplet visar hur du använder detta kommando. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:675 +#: C/index.docbook:681 msgid "Documenting the code" msgstr "Att dokumentera koden" #. (itstool) path: chapter/para -#: C/index.docbook:677 +#: C/index.docbook:683 msgid "" "GTK-Doc uses source code comment with a special syntax for code " "documentation. Further it retrieves information about your project structure " @@ -1172,12 +1181,12 @@ msgstr "" "syntaxen i kommentarerna." #. (itstool) path: note/title -#: C/index.docbook:685 +#: C/index.docbook:691 msgid "Documentation placement" msgstr "Dokumentationsplacering" #. (itstool) path: note/para -#: C/index.docbook:686 +#: C/index.docbook:692 msgid "" "In the past most documentation had to be filled into files residing inside " "the tmpl directory. This has the disadvantages that the " @@ -1190,7 +1199,7 @@ msgstr "" "konflikter med versionshanteringssystem." #. (itstool) path: note/para -#: C/index.docbook:692 +#: C/index.docbook:698 msgid "" "The avoid the aforementioned problems we suggest putting the documentation " "inside the sources. This manual will only describe this way of documenting " @@ -1201,12 +1210,12 @@ msgstr "" "dokumentera kod." #. (itstool) path: example/title -#: C/index.docbook:703 C/index.docbook:729 +#: C/index.docbook:709 C/index.docbook:735 msgid "GTK-Doc comment block" msgstr "GTK-Doc-kommentarsblock" #. (itstool) path: example/programlisting -#: C/index.docbook:704 +#: C/index.docbook:710 #, no-wrap msgid "" "\n" @@ -1220,7 +1229,7 @@ msgstr "" "#endif\n" #. (itstool) path: chapter/para -#: C/index.docbook:699 +#: C/index.docbook:705 msgid "" "The scanner can handle the majority of C headers fine. In the case of " "receiving warnings from the scanner that look like a special case, one can " @@ -1231,13 +1240,13 @@ msgstr "" "Doc att hoppa över dem. <_:example-1/>" #. (itstool) path: note/title -#: C/index.docbook:713 +#: C/index.docbook:719 msgid "Limitations" msgstr "Begränsningar" # sebras: no 's in the original #. (itstool) path: note/para -#: C/index.docbook:714 +#: C/index.docbook:720 msgid "" "Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but " "not #if !defined(__GTK_DOC_IGNORE__) or other combinations." @@ -1246,12 +1255,12 @@ msgstr "" "inte #if !defined(__GTK_DOC_IGNORE__) eller andra kombinationer." #. (itstool) path: sect1/title -#: C/index.docbook:724 +#: C/index.docbook:730 msgid "Documentation comments" msgstr "Dokumentationskommentarer" #. (itstool) path: example/programlisting -#: C/index.docbook:730 +#: C/index.docbook:736 #, no-wrap msgid "" "\n" @@ -1267,7 +1276,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:726 +#: C/index.docbook:732 msgid "" "A multiline comment that starts with an additional '*' marks a documentation " "block that will be processed by the GTK-Doc tools. <_:example-1/>" @@ -1277,7 +1286,7 @@ msgstr "" "example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:739 +#: C/index.docbook:745 msgid "" "The 'identifier' is one line with the name of the item the comment is " "related to. The syntax differs a little depending on the item. (TODO add " @@ -1288,7 +1297,7 @@ msgstr "" "till tabell som visar identifierare)" #. (itstool) path: sect1/para -#: C/index.docbook:745 +#: C/index.docbook:751 msgid "" "The 'documentation' block is also different for each symbol type. Symbol " "types that get parameters such as functions or macros have the parameter " @@ -1308,7 +1317,7 @@ msgstr "" "användbart i förformaterad text (kodlistningar)." #. (itstool) path: listitem/para -#: C/index.docbook:762 +#: C/index.docbook:768 msgid "" "What it is: The name for a class or function can sometimes be misleading for " "people coming from a different background." @@ -1317,7 +1326,7 @@ msgstr "" "vilseledande för personer med annan bakgrund." #. (itstool) path: listitem/para -#: C/index.docbook:768 +#: C/index.docbook:774 msgid "" "What it does: Tell about common uses. Put it in relation with the other API." msgstr "" @@ -1325,19 +1334,19 @@ msgstr "" "det andra API:t." #. (itstool) path: tip/para -#: C/index.docbook:758 +#: C/index.docbook:764 msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" msgstr "När du dokumenterar kod, beskriv två aspekter: <_:itemizedlist-1/>" #. (itstool) path: listitem/para -#: C/index.docbook:783 +#: C/index.docbook:789 msgid "Use function() to refer to functions or macros which take arguments." msgstr "" "Använd funktion() för att referera till funktioner eller makron som tar " "argument." #. (itstool) path: listitem/para -#: C/index.docbook:788 +#: C/index.docbook:794 msgid "" "Use @param to refer to parameters. Also use this when referring to " "parameters of other functions, related to the one being described." @@ -1347,13 +1356,13 @@ msgstr "" "beskrivs." #. (itstool) path: listitem/para -#: C/index.docbook:794 +#: C/index.docbook:800 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "" "Använd %konstant för att referera till en konstant, t.ex. %G_TRAVERSE_LEAFS." #. (itstool) path: listitem/para -#: C/index.docbook:799 +#: C/index.docbook:805 msgid "" "Use #symbol to refer to other types of symbol, e.g. structs and enums and " "macros which don't take arguments." @@ -1362,17 +1371,17 @@ msgstr "" "strukturer eller uppräkningar och makron som inte tar argument." #. (itstool) path: listitem/para -#: C/index.docbook:805 +#: C/index.docbook:811 msgid "Use #Object::signal to refer to a GObject signal." msgstr "Använd #Objekt::signal för att referera till en GObject-signal." #. (itstool) path: listitem/para -#: C/index.docbook:810 +#: C/index.docbook:816 msgid "Use #Object:property to refer to a GObject property." msgstr "Använd #Objekt:egenskap för att referera till en GObject-egenskap." #. (itstool) path: listitem/para -#: C/index.docbook:815 +#: C/index.docbook:821 msgid "" "Use #Struct.field to refer to a field inside a structure and #GObjectClass." "foo_bar() to refer to a vmethod." @@ -1381,7 +1390,7 @@ msgstr "" "#GObjectKlass.foo_bar() för att referera till en virtuell metod." #. (itstool) path: sect1/para -#: C/index.docbook:777 +#: C/index.docbook:783 msgid "" "One advantage of hyper-text over plain-text is the ability to have links in " "the document. Writing the correct markup for a link can be tedious though. " @@ -1394,7 +1403,7 @@ msgstr "" "förkortningar. <_:itemizedlist-1/>" #. (itstool) path: tip/para -#: C/index.docbook:824 +#: C/index.docbook:830 msgid "" "If you need to use the special characters '<', '>', '()', '@', '%', or " "'#' in your documentation without GTK-Doc changing them you can use the XML " @@ -1409,7 +1418,7 @@ msgstr "" "kontrollsekvensen ”\\”." #. (itstool) path: sect1/para -#: C/index.docbook:833 +#: C/index.docbook:839 msgid "" "DocBook can do more than just links. One can also have lists, examples, " "headings, and images. As of version 1.20, the preferred way is to use a " @@ -1427,7 +1436,7 @@ msgstr "" "ett bindestreck." #. (itstool) path: sect1/para -#: C/index.docbook:844 +#: C/index.docbook:850 msgid "" "While markdown is now preferred one can mix both. One limitation here is " "that one can use docbook xml within markdown, but markdown within docbook " @@ -1438,7 +1447,7 @@ msgstr "" "inte." #. (itstool) path: sect1/para -#: C/index.docbook:850 +#: C/index.docbook:856 msgid "" "In older GTK-Doc releases, if you need support for additional formatting, " "you would need to enable the usage of docbook XML tags inside doc-comments " @@ -1454,12 +1463,12 @@ msgstr "" # sebras: markdown or Markdown? #. (itstool) path: example/title -#: C/index.docbook:859 +#: C/index.docbook:865 msgid "GTK-Doc comment block using Markdown" msgstr "GTK-Doc-kommentarsblock som använder Markdown" #. (itstool) path: example/programlisting -#: C/index.docbook:860 +#: C/index.docbook:866 #, no-wrap msgid "" "\n" @@ -1535,7 +1544,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:899 +#: C/index.docbook:905 msgid "" "More examples of what markdown tags are supported can be found in the Referensen för GTK+-dokumentationens markdown-syntax." #. (itstool) path: tip/para -#: C/index.docbook:905 +#: C/index.docbook:911 msgid "" "As already mentioned earlier GTK-Doc is for documenting public API. Thus one " "cannot write documentation for static symbols. Nevertheless it is good to " @@ -1566,12 +1575,12 @@ msgstr "" "ställe i avsnittsfilen." #. (itstool) path: sect1/title -#: C/index.docbook:919 +#: C/index.docbook:925 msgid "Documenting sections" msgstr "Dokumentationsavsnitt" #. (itstool) path: sect1/para -#: C/index.docbook:921 +#: C/index.docbook:927 msgid "" "Each section of the documentation contains information about one class or " "module. To introduce the component one can write a section block. The short " @@ -1584,12 +1593,12 @@ msgstr "" "valfria." #. (itstool) path: example/title -#: C/index.docbook:929 +#: C/index.docbook:935 msgid "Section comment block" msgstr "Kommentarsblock för avsnitt" #. (itstool) path: example/programlisting -#: C/index.docbook:930 +#: C/index.docbook:936 #, no-wrap msgid "" "\n" @@ -1621,12 +1630,12 @@ msgstr "" " */\n" #. (itstool) path: varlistentry/term -#: C/index.docbook:949 +#: C/index.docbook:955 msgid "SECTION:<name>" msgstr "SECTION:<namn>" #. (itstool) path: listitem/para -#: C/index.docbook:951 +#: C/index.docbook:957 msgid "" "The name links the section documentation to the respective part in the " "<package>-sections.txt file. The name given here " @@ -1639,12 +1648,12 @@ msgstr "" "filename>." #. (itstool) path: varlistentry/term -#: C/index.docbook:960 +#: C/index.docbook:966 msgid "@short_description" msgstr "@short_description" #. (itstool) path: listitem/para -#: C/index.docbook:962 +#: C/index.docbook:968 msgid "" "A one line description of the section, that later will appear after the " "links in the TOC and at the top of the section page." @@ -1653,12 +1662,12 @@ msgstr "" "innehållsförteckningen och lägst upp på avsnittssidan." #. (itstool) path: varlistentry/term -#: C/index.docbook:969 +#: C/index.docbook:975 msgid "@title" msgstr "@title" #. (itstool) path: listitem/para -#: C/index.docbook:971 +#: C/index.docbook:977 msgid "" "The section title defaults to <name> from the SECTION declaration. It " "can be overridden with the @title field." @@ -1667,12 +1676,12 @@ msgstr "" "kan åsidosättas med fältet @title." #. (itstool) path: varlistentry/term -#: C/index.docbook:978 +#: C/index.docbook:984 msgid "@section_id" msgstr "@section_id" #. (itstool) path: listitem/para -#: C/index.docbook:980 +#: C/index.docbook:986 msgid "" "Overrides the use of title as a section identifier. For GObjects the <" "title> is used as a section_id and for other sections it is <" @@ -1683,22 +1692,22 @@ msgstr "" "MODULE>-<title>." #. (itstool) path: varlistentry/term -#: C/index.docbook:988 +#: C/index.docbook:994 msgid "@see_also" msgstr "@see_also" #. (itstool) path: listitem/para -#: C/index.docbook:990 +#: C/index.docbook:996 msgid "A list of symbols that are related to this section." msgstr "En lista över symboler som är relaterade till detta avsnitt." #. (itstool) path: varlistentry/term -#: C/index.docbook:996 +#: C/index.docbook:1002 msgid "@stability" msgstr "@stability" #. (itstool) path: listitem/para -#: C/index.docbook:1003 +#: C/index.docbook:1009 msgid "" "Stable - The intention of a Stable interface is to enable arbitrary third " "parties to develop applications to these interfaces, release them, and have " @@ -1715,7 +1724,7 @@ msgstr "" "motiverade." #. (itstool) path: listitem/para -#: C/index.docbook:1015 +#: C/index.docbook:1021 msgid "" "Unstable - Unstable interfaces are experimental or transitional. They are " "typically used to give outside developers early access to new or rapidly " @@ -1731,7 +1740,7 @@ msgstr "" "programfixversion till nästa." #. (itstool) path: listitem/para -#: C/index.docbook:1027 +#: C/index.docbook:1033 msgid "" "Private - An interface that can be used within the GNOME stack itself, but " "that is not documented for end-users. Such functions should only be used in " @@ -1742,7 +1751,7 @@ msgstr "" "på angivna och dokumenterade sätt." #. (itstool) path: listitem/para -#: C/index.docbook:1036 +#: C/index.docbook:1042 msgid "" "Internal - An interface that is internal to a module and does not require " "end-user documentation. Functions that are undocumented are assumed to be " @@ -1753,7 +1762,7 @@ msgstr "" "interna." #. (itstool) path: listitem/para -#: C/index.docbook:998 +#: C/index.docbook:1004 msgid "" "An informal description of the stability level this API has. We recommend " "the use of one of these terms: <_:itemizedlist-1/>" @@ -1762,12 +1771,12 @@ msgstr "" "att använda en av dessa termer: <_:itemizedlist-1/>" #. (itstool) path: varlistentry/term -#: C/index.docbook:1048 +#: C/index.docbook:1054 msgid "@include" msgstr "@include" #. (itstool) path: listitem/para -#: C/index.docbook:1050 +#: C/index.docbook:1056 msgid "" "The #include files to show in the section synopsis (a " "comma separated list), overriding the global value from the --default-stability argument to " @@ -1895,17 +1904,17 @@ msgstr "" "till gtkdoc-mkdb med endera av värdena nedan." #. (itstool) path: variablelist/title -#: C/index.docbook:1128 +#: C/index.docbook:1134 msgid "Stability Tags" msgstr "Stabilitetstaggar" #. (itstool) path: varlistentry/term -#: C/index.docbook:1129 +#: C/index.docbook:1135 msgid "Stability: Stable" msgstr "Stability: Stable" #. (itstool) path: listitem/para -#: C/index.docbook:1131 +#: C/index.docbook:1137 msgid "" "Mark the element as stable. This is for public APIs which are guaranteed to " "remain stable for all future minor releases of the project." @@ -1915,12 +1924,12 @@ msgstr "" "projektet." #. (itstool) path: varlistentry/term -#: C/index.docbook:1138 +#: C/index.docbook:1144 msgid "Stability: Unstable" msgstr "Stability: Unstable" #. (itstool) path: listitem/para -#: C/index.docbook:1140 +#: C/index.docbook:1146 msgid "" "Mark the element as unstable. This is for public APIs which are released as " "a preview before being stabilised." @@ -1929,12 +1938,12 @@ msgstr "" "på förhand innan de blivit stabiliserade." #. (itstool) path: varlistentry/term -#: C/index.docbook:1146 +#: C/index.docbook:1152 msgid "Stability: Private" msgstr "Stability: Private" #. (itstool) path: listitem/para -#: C/index.docbook:1148 +#: C/index.docbook:1154 msgid "" "Mark the element as private. This is for interfaces which can be used by " "tightly coupled modules, but not by arbitrary third parties." @@ -1943,7 +1952,7 @@ msgstr "" "av tätt sammankopplade moduler, men inte av godtyckliga tredje parter." #. (itstool) path: example/programlisting -#: C/index.docbook:1158 +#: C/index.docbook:1164 #, no-wrap msgid "" "\n" @@ -1982,13 +1991,13 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1178 C/index.docbook:1188 +#: C/index.docbook:1184 C/index.docbook:1194 msgid "Annotations" msgstr "Noteringar" # sebras: was it called verkygstips? verktygshjälp? I forget... #. (itstool) path: sect2/para -#: C/index.docbook:1180 +#: C/index.docbook:1186 msgid "" "Documentation blocks can contain annotation-tags. These tags will be " "rendered with tooltips describing their meaning. The tags are used by " @@ -2003,7 +2012,7 @@ msgstr "" "GObjectIntrospection/Annotations\" type=\"http\">wikisidan." #. (itstool) path: example/programlisting -#: C/index.docbook:1189 +#: C/index.docbook:1195 #, no-wrap msgid "" "\n" @@ -2044,12 +2053,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1210 C/index.docbook:1239 +#: C/index.docbook:1216 C/index.docbook:1245 msgid "Function comment block" msgstr "Kommentarsblock för funktioner" #. (itstool) path: listitem/para -#: C/index.docbook:1216 +#: C/index.docbook:1222 msgid "" "Document whether returned objects, lists, strings, etc, should be freed/" "unrefed/released." @@ -2058,26 +2067,26 @@ msgstr "" "avrefereras/släppas." #. (itstool) path: listitem/para -#: C/index.docbook:1222 +#: C/index.docbook:1228 msgid "Document whether parameters can be NULL, and what happens if they are." msgstr "" "Dokumentera huruvida parametrar tillåts vara NULL och vad som händer om de " "är NULL." #. (itstool) path: listitem/para -#: C/index.docbook:1227 +#: C/index.docbook:1233 msgid "" "Mention interesting pre-conditions and post-conditions where appropriate." msgstr "Nämn intressanta förvillkor och eftervillkor där lämpligt." #. (itstool) path: sect2/para -#: C/index.docbook:1212 C/index.docbook:1298 +#: C/index.docbook:1218 C/index.docbook:1304 msgid "Please remember to: <_:itemizedlist-1/>" msgstr "Kom ihåg att: <_:itemizedlist-1/>" # sebras: Gtk-doc? GTK-Doc? gtk-doc? macros and functions? #. (itstool) path: sect2/para -#: C/index.docbook:1234 +#: C/index.docbook:1240 msgid "" "Gtk-doc assumes all symbols (macros, functions) starting with '_' are " "private. They are treated like static functions." @@ -2087,7 +2096,7 @@ msgstr "" # sebras: how to translate highlight? #. (itstool) path: example/programlisting -#: C/index.docbook:1240 +#: C/index.docbook:1246 #, no-wrap msgid "" "\n" @@ -2130,28 +2139,28 @@ msgstr "" " */\n" #. (itstool) path: variablelist/title -#: C/index.docbook:1261 +#: C/index.docbook:1267 msgid "Function tags" msgstr "Funktions-taggar" #. (itstool) path: varlistentry/term -#: C/index.docbook:1262 C/index.docbook:1469 +#: C/index.docbook:1268 C/index.docbook:1475 msgid "Returns:" msgstr "Returns:" #. (itstool) path: listitem/para -#: C/index.docbook:1264 +#: C/index.docbook:1270 msgid "Paragraph describing the returned result." msgstr "Stycke som beskriver det returnerade resultatet." #. (itstool) path: varlistentry/term -#: C/index.docbook:1269 +#: C/index.docbook:1275 msgid "@...:" msgstr "@...:" # sebras: variadic? #. (itstool) path: listitem/para -#: C/index.docbook:1271 +#: C/index.docbook:1277 msgid "" "In case the function has variadic arguments, you should use this tag " "(@Varargs: does also work for historic reasons)." @@ -2161,12 +2170,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1281 C/index.docbook:1283 +#: C/index.docbook:1287 C/index.docbook:1289 msgid "Property comment block" msgstr "Kommentarsblock för egenskaper" #. (itstool) path: example/programlisting -#: C/index.docbook:1284 +#: C/index.docbook:1290 #, no-wrap msgid "" "\n" @@ -2187,12 +2196,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1296 C/index.docbook:1315 +#: C/index.docbook:1302 C/index.docbook:1321 msgid "Signal comment block" msgstr "Kommentarsblock för signaler" #. (itstool) path: listitem/para -#: C/index.docbook:1302 +#: C/index.docbook:1308 msgid "" "Document when the signal is emitted and whether it is emitted before or " "after other signals." @@ -2201,12 +2210,12 @@ msgstr "" "efter andra signaler." #. (itstool) path: listitem/para -#: C/index.docbook:1308 +#: C/index.docbook:1314 msgid "Document what an application might do in the signal handler." msgstr "Dokumentera vad ett program kan göra i signalhanteraren." #. (itstool) path: example/programlisting -#: C/index.docbook:1316 +#: C/index.docbook:1322 #, no-wrap msgid "" "\n" @@ -2237,12 +2246,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1333 C/index.docbook:1334 +#: C/index.docbook:1339 C/index.docbook:1340 msgid "Struct comment block" msgstr "Kommentarsblock för strukturer" #. (itstool) path: example/programlisting -#: C/index.docbook:1335 +#: C/index.docbook:1341 #, no-wrap msgid "" "\n" @@ -2272,7 +2281,7 @@ msgstr "" "} FooWidget;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1350 +#: C/index.docbook:1356 msgid "" "Use /*< private >*/ before the private struct fields you " "want to hide. Use /*< public >*/ for the reverse " @@ -2283,7 +2292,7 @@ msgstr "" "beteendet." #. (itstool) path: sect2/para -#: C/index.docbook:1356 +#: C/index.docbook:1362 msgid "" "If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" " "it will be considered private automatically and doesn't need to be mentioned " @@ -2294,7 +2303,7 @@ msgstr "" "kommentarsblocket." #. (itstool) path: sect2/para -#: C/index.docbook:1362 +#: C/index.docbook:1368 msgid "" "Struct comment blocks can also be used for GObjects and GObjectClasses. It " "is usually a good idea to add a comment block for a class, if it has " @@ -2315,12 +2324,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1374 C/index.docbook:1375 +#: C/index.docbook:1380 C/index.docbook:1381 msgid "Enum comment block" msgstr "Kommentarsblock för uppräkningar" #. (itstool) path: example/programlisting -#: C/index.docbook:1376 +#: C/index.docbook:1382 #, no-wrap msgid "" "\n" @@ -2354,7 +2363,7 @@ msgstr "" "} Something;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1393 +#: C/index.docbook:1399 msgid "" "Use /*< private >*/ before the private enum values you " "want to hide. Use /*< public >*/ for the reverse " @@ -2365,13 +2374,13 @@ msgstr "" "beteendet." #. (itstool) path: sect1/title -#: C/index.docbook:1404 +#: C/index.docbook:1410 msgid "Inline program documentation" msgstr "Infogad programdokumentation" # sebras: how to translate inline? #. (itstool) path: sect1/para -#: C/index.docbook:1405 +#: C/index.docbook:1411 msgid "" "You can document programs and their commandline interface using inline " "documentation." @@ -2380,37 +2389,37 @@ msgstr "" "dokumentation." #. (itstool) path: variablelist/title -#: C/index.docbook:1411 +#: C/index.docbook:1417 msgid "Tags" msgstr "Taggar" #. (itstool) path: varlistentry/term -#: C/index.docbook:1413 +#: C/index.docbook:1419 msgid "PROGRAM" msgstr "PROGRAM" #. (itstool) path: listitem/para -#: C/index.docbook:1416 +#: C/index.docbook:1422 msgid "Defines the start of a program documentation." msgstr "Definierar början av programdokumentationen." #. (itstool) path: varlistentry/term -#: C/index.docbook:1423 +#: C/index.docbook:1429 msgid "@short_description:" msgstr "@short_description:" #. (itstool) path: listitem/para -#: C/index.docbook:1425 +#: C/index.docbook:1431 msgid "Defines a short description of the program. (Optional)" msgstr "Definierar en kort beskrivning av programmet. (Valfritt)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1432 +#: C/index.docbook:1438 msgid "@synopsis:" msgstr "@synopsis:" #. (itstool) path: listitem/para -#: C/index.docbook:1434 +#: C/index.docbook:1440 msgid "" "Defines the arguments, or list of arguments that the program can take. " "(Optional)" @@ -2419,54 +2428,54 @@ msgstr "" "(Valfritt)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1442 +#: C/index.docbook:1448 msgid "@see_also:" msgstr "@see_also:" #. (itstool) path: listitem/para -#: C/index.docbook:1444 +#: C/index.docbook:1450 msgid "See Also manual page section. (Optional)" msgstr "Se vidare i manualavsnitt. (Valfritt)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1451 +#: C/index.docbook:1457 msgid "@arg:" msgstr "@arg:" #. (itstool) path: listitem/para -#: C/index.docbook:1453 +#: C/index.docbook:1459 msgid "Argument(s) passed to the program and their description. (Optional)" msgstr "" "Argument som skickas vidare till programmet och deras beskrivningar. " "(Valfritt)" #. (itstool) path: varlistentry/term -#: C/index.docbook:1460 +#: C/index.docbook:1466 msgid "Description:" msgstr "Beskrivning:" #. (itstool) path: listitem/para -#: C/index.docbook:1462 +#: C/index.docbook:1468 msgid "A longer description of the program." msgstr "En längre beskrivning av programmet." #. (itstool) path: listitem/para -#: C/index.docbook:1471 +#: C/index.docbook:1477 msgid "Specificy what value(s) the program returns. (Optional)" msgstr "Ange vilka värden programmet returnerar. (Valfritt)" #. (itstool) path: sect2/title -#: C/index.docbook:1480 +#: C/index.docbook:1486 msgid "Example of program documentation." msgstr "Exempel på programdokumentation." #. (itstool) path: example/title -#: C/index.docbook:1481 +#: C/index.docbook:1487 msgid "Program documentation block" msgstr "Dokumentationsblock för program" #. (itstool) path: example/programlisting -#: C/index.docbook:1482 +#: C/index.docbook:1488 #, no-wrap msgid "" "\n" @@ -2510,19 +2519,19 @@ msgstr "" "}\n" #. (itstool) path: sect1/title -#: C/index.docbook:1508 +#: C/index.docbook:1514 msgid "Useful DocBook tags" msgstr "Användbara DocBook-taggar" #. (itstool) path: sect1/para -#: C/index.docbook:1510 +#: C/index.docbook:1516 msgid "" "Here are some DocBook tags which are most useful when documenting the code." msgstr "" "Här är några DocBook-taggar som är användbara när man dokumenterar koden." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1519 +#: C/index.docbook:1525 #, no-wrap msgid "" "\n" @@ -2532,7 +2541,7 @@ msgstr "" "<link linkend=\"glib-Hash-Tables\">Hashtabeller</link>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1515 +#: C/index.docbook:1521 msgid "" "To link to another section in the GTK docs: <_:informalexample-1/> The " "linkend is the SGML/XML id on the top item of the page you want to link to. " @@ -2548,7 +2557,7 @@ msgstr "" "konverteras till ”-” för att överensstämma med SGML/XML." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1532 +#: C/index.docbook:1538 #, no-wrap msgid "" "\n" @@ -2558,7 +2567,7 @@ msgstr "" "<function>…</function>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1529 +#: C/index.docbook:1535 msgid "" "To refer to an external function, e.g. a standard C function: <_:" "informalexample-1/>" @@ -2567,7 +2576,7 @@ msgstr "" "informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1541 +#: C/index.docbook:1547 #, no-wrap msgid "" "\n" @@ -2587,7 +2596,7 @@ msgstr "" "</example>\n" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1552 +#: C/index.docbook:1558 #, no-wrap msgid "" "\n" @@ -2605,7 +2614,7 @@ msgstr "" "</informalexample>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1538 +#: C/index.docbook:1544 msgid "" "To include example code: <_:informalexample-1/> or possibly this, for very " "short code fragments which don't need a title: <_:informalexample-2/> For " @@ -2617,7 +2626,7 @@ msgstr "" "förkortningen: |[ … ]|" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1571 +#: C/index.docbook:1577 #, no-wrap msgid "" "\n" @@ -2649,12 +2658,12 @@ msgstr "" "</itemizedlist>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1568 +#: C/index.docbook:1574 msgid "To include bulleted lists: <_:informalexample-1/>" msgstr "För att inkludera punktlistor: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1591 +#: C/index.docbook:1597 #, no-wrap msgid "" "\n" @@ -2672,14 +2681,14 @@ msgstr "" "</note>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1588 +#: C/index.docbook:1594 msgid "" "To include a note which stands out from the text: <_:informalexample-1/>" msgstr "" "För att inkludera en not som skiljer sig från texten: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1604 +#: C/index.docbook:1610 #, no-wrap msgid "" "\n" @@ -2689,12 +2698,12 @@ msgstr "" "<type>unsigned char</type>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1601 +#: C/index.docbook:1607 msgid "To refer to a type: <_:informalexample-1/>" msgstr "För att refera till en typ: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1613 +#: C/index.docbook:1619 #, no-wrap msgid "" "\n" @@ -2704,7 +2713,7 @@ msgstr "" "<structname>XFontStruct</structname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1610 +#: C/index.docbook:1616 msgid "" "To refer to an external structure (not one described in the GTK docs): <_:" "informalexample-1/>" @@ -2713,7 +2722,7 @@ msgstr "" "dokumentationen): <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1622 +#: C/index.docbook:1628 #, no-wrap msgid "" "\n" @@ -2723,12 +2732,12 @@ msgstr "" "<structfield>len</structfield>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1619 +#: C/index.docbook:1625 msgid "To refer to a field of a structure: <_:informalexample-1/>" msgstr "För att referera till ett fält för en struktur: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1631 +#: C/index.docbook:1637 #, no-wrap msgid "" "\n" @@ -2738,7 +2747,7 @@ msgstr "" "<classname>GtkWidget</classname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1628 +#: C/index.docbook:1634 msgid "" "To refer to a class name, we could possibly use: <_:informalexample-1/> but " "you'll probably be using #GtkWidget instead (to automatically create a link " @@ -2751,7 +2760,7 @@ msgstr "" "\"documenting_syntax\">förkortningarna)." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1642 +#: C/index.docbook:1648 #, no-wrap msgid "" "\n" @@ -2761,12 +2770,12 @@ msgstr "" "<emphasis>Detta är viktigt</emphasis>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1639 +#: C/index.docbook:1645 msgid "To emphasize text: <_:informalexample-1/>" msgstr "För att betona text: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1651 +#: C/index.docbook:1657 #, no-wrap msgid "" "\n" @@ -2776,12 +2785,12 @@ msgstr "" "<filename>/home/användare/dokument</filename>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1648 +#: C/index.docbook:1654 msgid "For filenames use: <_:informalexample-1/>" msgstr "För filnamn använd: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1660 +#: C/index.docbook:1666 #, no-wrap msgid "" "\n" @@ -2791,17 +2800,17 @@ msgstr "" "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1657 +#: C/index.docbook:1663 msgid "To refer to keys use: <_:informalexample-1/>" msgstr "För att referera till tangenter använd: <_:informalexample-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1670 +#: C/index.docbook:1676 msgid "Filling the extra files" msgstr "Fylla i de extra filerna" #. (itstool) path: chapter/para -#: C/index.docbook:1672 +#: C/index.docbook:1678 msgid "" "There are a couple of extra files, that need to be maintained along with the " "inline source code comments: <package>.types, " @@ -2814,12 +2823,12 @@ msgstr "" "paket>-sections.txt." #. (itstool) path: sect1/title -#: C/index.docbook:1681 +#: C/index.docbook:1687 msgid "Editing the types file" msgstr "Redigera typfilen" #. (itstool) path: sect1/para -#: C/index.docbook:1683 +#: C/index.docbook:1689 msgid "" "If your library or application includes GObjects, you want their signals, " "arguments/parameters and position in the hierarchy to be shown in the " @@ -2834,12 +2843,12 @@ msgstr "" "package>.types." #. (itstool) path: example/title -#: C/index.docbook:1692 +#: C/index.docbook:1698 msgid "Example types file snippet" msgstr "Exempel på typfilsnutt" #. (itstool) path: example/programlisting -#: C/index.docbook:1693 +#: C/index.docbook:1699 #, no-wrap msgid "" "\n" @@ -2859,7 +2868,7 @@ msgstr "" "gtk_arrow_get_type\n" #. (itstool) path: sect1/para -#: C/index.docbook:1704 +#: C/index.docbook:1710 msgid "" "Since GTK-Doc 1.8 gtkdoc-scan can generate this " "list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in " @@ -2872,12 +2881,12 @@ msgstr "" "du inte distribuera typfilen eller versionshantera den." #. (itstool) path: sect1/title -#: C/index.docbook:1713 +#: C/index.docbook:1719 msgid "Editing the master document" msgstr "Redigera huvuddokumentet" #. (itstool) path: sect1/para -#: C/index.docbook:1715 +#: C/index.docbook:1721 msgid "" "GTK-Doc produces documentation in DocBook SGML/XML. When processing the " "inline source comments, the GTK-Doc tools generate one documentation page " @@ -2891,7 +2900,7 @@ msgstr "" # sebras: Its -> it's #. (itstool) path: sect1/para -#: C/index.docbook:1722 +#: C/index.docbook:1728 msgid "" "While GTK-Doc creates a template master document for you, later runs will " "not touch it again. This means that one can freely structure the " @@ -2909,7 +2918,7 @@ msgstr "" # sebras: for -> from Apart -> together/embedded... #. (itstool) path: tip/para -#: C/index.docbook:1732 +#: C/index.docbook:1738 msgid "" "Do not create tutorials as extra documents. Just write extra chapters. The " "benefit of directly embedding the tutorial for your library into the API " @@ -2924,7 +2933,7 @@ msgstr "" "blir uppdaterad tillsammans med biblioteket." #. (itstool) path: sect1/para -#: C/index.docbook:1741 +#: C/index.docbook:1747 msgid "" "So what are the things to change inside the master document? For a start is " "only a little. There are some placeholders (text in square brackets) there " @@ -2934,12 +2943,12 @@ msgstr "" "Det finns en del platshållare (text i hakparenteser) som du bör ta hand om." #. (itstool) path: example/title -#: C/index.docbook:1748 +#: C/index.docbook:1754 msgid "Master document header" msgstr "Huvuddokumentets huvud" #. (itstool) path: example/programlisting -#: C/index.docbook:1749 +#: C/index.docbook:1755 #, no-wrap msgid "" "\n" @@ -2969,7 +2978,7 @@ msgstr "" " <title>[Infoga titel här]</title>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1765 +#: C/index.docbook:1771 msgid "" "In addition a few option elements are created in commented form. You can " "review these and enable them as you like." @@ -2978,12 +2987,12 @@ msgstr "" "Du kan granska dessa och aktivera dem enligt dina egna önskemål." #. (itstool) path: example/title -#: C/index.docbook:1771 +#: C/index.docbook:1777 msgid "Optional part in the master document" msgstr "Valfri del i huvuddokumentet" #. (itstool) path: example/programlisting -#: C/index.docbook:1772 +#: C/index.docbook:1778 #, no-wrap msgid "" "\n" @@ -2997,7 +3006,7 @@ msgstr "" " -->\n" #. (itstool) path: sect1/para -#: C/index.docbook:1780 +#: C/index.docbook:1786 msgid "" "Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind " @@ -3009,12 +3018,12 @@ msgstr "" "infogats i dokumentationen." #. (itstool) path: example/title -#: C/index.docbook:1788 C/index.docbook:1823 +#: C/index.docbook:1794 C/index.docbook:1829 msgid "Including generated sections" msgstr "Inkludera genererade avsnitt" #. (itstool) path: example/programlisting -#: C/index.docbook:1789 +#: C/index.docbook:1795 #, no-wrap msgid "" "\n" @@ -3030,12 +3039,12 @@ msgstr "" " ...\n" #. (itstool) path: sect1/title -#: C/index.docbook:1801 +#: C/index.docbook:1807 msgid "Editing the section file" msgstr "Redigera avsnittsfilen" #. (itstool) path: sect1/para -#: C/index.docbook:1803 +#: C/index.docbook:1809 msgid "" "The section file is used to organise the documentation output by GTK-Doc. " "Here one specifies which symbol belongs to which module or class and control " @@ -3046,7 +3055,7 @@ msgstr "" "styra synligheten (publik eller privat)." #. (itstool) path: sect1/para -#: C/index.docbook:1809 +#: C/index.docbook:1815 msgid "" "The section file is a plain text file with tags delimiting sections. Blank " "lines are ignored and lines starting with a '#' are treated as comment lines." @@ -3056,7 +3065,7 @@ msgstr "" "kommentarsrader." #. (itstool) path: note/para -#: C/index.docbook:1816 +#: C/index.docbook:1822 msgid "" "While the tags make the file look like xml, it is not. Please do not close " "tags like <SUBSECTION>." @@ -3065,7 +3074,7 @@ msgstr "" "taggar så som <SUBSECTION>." #. (itstool) path: example/programlisting -#: C/index.docbook:1824 +#: C/index.docbook:1830 #, no-wrap msgid "" "\n" @@ -3097,7 +3106,7 @@ msgstr "" "</SECTION>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1841 +#: C/index.docbook:1847 msgid "" "The <FILE> ... </FILE> tag is used to specify the file name, " "without any suffix. For example, using '<FILE>gnome-config</" @@ -3119,7 +3128,7 @@ msgstr "" "klassnamnet för GObjectet konverterat till gemener)." #. (itstool) path: sect1/para -#: C/index.docbook:1853 +#: C/index.docbook:1859 msgid "" "The <TITLE> ... </TITLE> tag is used to specify the title of the " "section. It is only useful before the templates (if used) are initially " @@ -3132,7 +3141,7 @@ msgstr "" "Vidare är detta föråldrat om man använder SECTIONS-kommentarer i källkoden." #. (itstool) path: sect1/para -#: C/index.docbook:1860 +#: C/index.docbook:1866 msgid "" "You can group items in the section by using the <SUBSECTION> tag. " "Currently it outputs a blank line between subsections in the synopsis " @@ -3162,7 +3171,7 @@ msgstr "" "beror på om de har publika poster (variabler, virtuella metoder)." #. (itstool) path: sect1/para -#: C/index.docbook:1879 +#: C/index.docbook:1885 msgid "" "You can also use <INCLUDE> ... </INCLUDE> to specify the " "#include files which are shown in the synopsis sections. It contains a comma-" @@ -3178,12 +3187,12 @@ msgstr "" "påverka det avsnittet." #. (itstool) path: chapter/title -#: C/index.docbook:1893 +#: C/index.docbook:1899 msgid "Controlling the result" msgstr "Kontrollera resultatet" #. (itstool) path: chapter/para -#: C/index.docbook:1895 +#: C/index.docbook:1901 msgid "" "A GTK-Doc run generates report files inside the documentation directory. The " "generated files are named: <package>-undocumented.txt<package>-undocumented.txt file starts with " "the documentation coverage summary. Below are two sections divided by blank " @@ -3214,7 +3223,7 @@ msgstr "" "dokumentation, men där en ny parameter har lagts till." #. (itstool) path: chapter/para -#: C/index.docbook:1913 +#: C/index.docbook:1919 msgid "" "The <package>-undeclared.txt file lists symbols " "given in the <package>-sections.txt but not found " @@ -3225,7 +3234,7 @@ msgstr "" "källkoden. Kontrollera om de har tagits bort eller om de är felstavade." #. (itstool) path: chapter/para -#: C/index.docbook:1920 +#: C/index.docbook:1926 msgid "" "The <package>-unused.txt file lists symbol names, " "where the GTK-Doc scanner has found documentation, but does not know where " @@ -3239,7 +3248,7 @@ msgstr "" # sebras: ? #. (itstool) path: tip/para -#: C/index.docbook:1928 +#: C/index.docbook:1934 msgid "" "Enable or add the line in Makefile." "am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during " @@ -3250,7 +3259,7 @@ msgstr "" "köra rimlighetskontroller under körning av make check." #. (itstool) path: chapter/para -#: C/index.docbook:1935 +#: C/index.docbook:1941 msgid "" "One can also look at the files produced by the source code scanner: " "<package>-decl-list.txt and <" @@ -3266,7 +3275,7 @@ msgstr "" "en symbol saknas bör man kontrollera om denna filen innehåller den." #. (itstool) path: chapter/para -#: C/index.docbook:1944 +#: C/index.docbook:1950 msgid "" "If the project is GObject based, one can also look into the files produced " "by the object scanner: <package>.args.txt, " @@ -3287,12 +3296,12 @@ msgstr "" "GTK_DOC_KEEP_INTERMEDIATE=1 make." #. (itstool) path: chapter/title -#: C/index.docbook:1959 +#: C/index.docbook:1965 msgid "Modernizing the documentation" msgstr "Modernisera dokumentationen" #. (itstool) path: chapter/para -#: C/index.docbook:1961 +#: C/index.docbook:1967 msgid "" "GTK-Doc has been around for quite some time. In this section we list new " "features together with the version since when it is available." @@ -3301,12 +3310,12 @@ msgstr "" "tillsammans med vilken version de gjordes tillgängliga." #. (itstool) path: sect1/title -#: C/index.docbook:1967 +#: C/index.docbook:1973 msgid "GTK-Doc 1.9" msgstr "GTK-Doc 1.9" #. (itstool) path: sect1/para -#: C/index.docbook:1969 +#: C/index.docbook:1975 msgid "" "When using xml instead of sgml, one can actually name the master document " "<package>-docs.xml." @@ -3315,7 +3324,7 @@ msgstr "" "huvuddokumentet <paket>-docs.xml." #. (itstool) path: sect1/para -#: C/index.docbook:1974 +#: C/index.docbook:1980 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3336,7 +3345,7 @@ msgstr "" "meld <paket>-decl-list.txt <paket>-sections.txt." #. (itstool) path: sect1/para -#: C/index.docbook:1985 +#: C/index.docbook:1991 msgid "" "Version 1.8 already introduced the syntax for documenting sections in the " "sources instead of the separate files under så är du klar." #. (itstool) path: sect1/title -#: C/index.docbook:1997 +#: C/index.docbook:2003 msgid "GTK-Doc 1.10" msgstr "GTK-Doc 1.10" #. (itstool) path: sect1/para -#: C/index.docbook:1999 +#: C/index.docbook:2005 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3380,17 +3389,17 @@ msgstr "" "filename> för kod som bara byggs ibland." #. (itstool) path: sect1/title -#: C/index.docbook:2010 +#: C/index.docbook:2016 msgid "GTK-Doc 1.16" msgstr "GTK-Doc 1.16" #. (itstool) path: example/title -#: C/index.docbook:2016 +#: C/index.docbook:2022 msgid "Enable gtkdoc-check" msgstr "Aktivera gtkdoc-check" #. (itstool) path: example/programlisting -#: C/index.docbook:2017 +#: C/index.docbook:2023 #, no-wrap msgid "" "\n" @@ -3410,7 +3419,7 @@ msgstr "" "endif\n" #. (itstool) path: sect1/para -#: C/index.docbook:2012 +#: C/index.docbook:2018 msgid "" "This version includes a new tool called gtkdoc-check. This tool can run a " "set of sanity checks on your documentation. It is enabled by adding these " @@ -3422,12 +3431,12 @@ msgstr "" "am. <_:example-1/>" #. (itstool) path: sect1/title -#: C/index.docbook:2030 +#: C/index.docbook:2036 msgid "GTK-Doc 1.20" msgstr "GTK-Doc 1.20" #. (itstool) path: sect1/para -#: C/index.docbook:2032 +#: C/index.docbook:2038 msgid "" "Version 1.18 brought some initial markdown support. Using markdown in doc " "comments is less intrusive than writing docbook xml. This version improves a " @@ -3441,17 +3450,17 @@ msgstr "" "\">kommentarsyntax finnas alla detaljer." #. (itstool) path: sect1/title -#: C/index.docbook:2042 +#: C/index.docbook:2048 msgid "GTK-Doc 1.25" msgstr "GTK-Doc 1.25" #. (itstool) path: example/title -#: C/index.docbook:2052 +#: C/index.docbook:2058 msgid "Use pre-generated entities" msgstr "Att använda förgenererade entiteter" #. (itstool) path: example/programlisting -#: C/index.docbook:2053 +#: C/index.docbook:2059 #, no-wrap msgid "" "\n" @@ -3493,7 +3502,7 @@ msgstr "" " </bookinfo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:2044 +#: C/index.docbook:2050 msgid "" "The makefiles shipped with this version generate an entity file at " "xml/gtkdocentities.ent, containing entities for e.g. " @@ -3512,12 +3521,12 @@ msgstr "" "använda samma xml-huvud i genererade xml-filer. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:2078 +#: C/index.docbook:2084 msgid "Documenting other interfaces" msgstr "Dokumentera andra gränssnitt" #. (itstool) path: chapter/para -#: C/index.docbook:2080 +#: C/index.docbook:2086 msgid "" "So far we have been using GTK-Doc to document the API of code. The next " "sections contain suggestions how the tools can be used to document other " @@ -3528,12 +3537,12 @@ msgstr "" "också dokumentera andra gränssnitt." #. (itstool) path: sect1/title -#: C/index.docbook:2087 +#: C/index.docbook:2093 msgid "Command line options and man pages" msgstr "Kommandoradsflaggor och mansidor" #. (itstool) path: sect1/para -#: C/index.docbook:2089 +#: C/index.docbook:2095 msgid "" "As one can generate man pages for a docbook refentry as well, it sounds like " "a good idea to use it for that purpose. This way the interface is part of " @@ -3544,13 +3553,13 @@ msgstr "" "gränssnittet att vara en del av referensen och man får mansidan gratis." #. (itstool) path: sect2/title -#: C/index.docbook:2096 +#: C/index.docbook:2102 msgid "Document the tool" msgstr "Dokumentera verktyget" # sebras: strange English #. (itstool) path: sect2/para -#: C/index.docbook:2098 +#: C/index.docbook:2104 msgid "" "Create one refentry file per tool. Following our example we would call it meep/" @@ -3565,17 +3574,17 @@ msgstr "" "väl som exempel i glib." #. (itstool) path: sect2/title -#: C/index.docbook:2108 +#: C/index.docbook:2114 msgid "Adding the extra configure check" msgstr "Lägga till den extra configure-kontrollen" #. (itstool) path: example/title -#: C/index.docbook:2111 C/index.docbook:2129 +#: C/index.docbook:2117 C/index.docbook:2135 msgid "Extra configure checks" msgstr "Lägga till extra configure-kontroller" #. (itstool) path: example/programlisting -#: C/index.docbook:2112 +#: C/index.docbook:2118 #, no-wrap msgid "" "\n" @@ -3597,12 +3606,12 @@ msgstr "" "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" #. (itstool) path: sect2/title -#: C/index.docbook:2126 +#: C/index.docbook:2132 msgid "Adding the extra makefile rules" msgstr "Lägga till de extra makefilsreglerna" #. (itstool) path: example/programlisting -#: C/index.docbook:2130 +#: C/index.docbook:2136 #, no-wrap msgid "" "\n" @@ -3638,12 +3647,12 @@ msgstr "" "EXTRA_DIST += meep.xml\n" #. (itstool) path: sect1/title -#: C/index.docbook:2152 +#: C/index.docbook:2158 msgid "DBus interfaces" msgstr "DBus-gränssnitt" #. (itstool) path: sect1/para -#: C/index.docbook:2154 +#: C/index.docbook:2160 msgid "" "(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" @@ -3652,27 +3661,27 @@ msgstr "" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" #. (itstool) path: chapter/title -#: C/index.docbook:2163 +#: C/index.docbook:2169 msgid "Frequently asked questions" msgstr "Frågor och svar" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2167 +#: C/index.docbook:2173 msgid "Question" msgstr "Fråga" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2168 +#: C/index.docbook:2174 msgid "Answer" msgstr "Svar" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2170 +#: C/index.docbook:2176 msgid "No class hierarchy." msgstr "Ingen klasshierarki." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2171 +#: C/index.docbook:2177 msgid "" "The objects xxx_get_type() function has not been " "entered into the <package>.types file." @@ -3681,12 +3690,12 @@ msgstr "" "filen <paket>.types." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2177 +#: C/index.docbook:2183 msgid "Still no class hierarchy." msgstr "Fortfarande ingen klasshierarki." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2178 +#: C/index.docbook:2184 msgid "" "Missing or wrong naming in <package>-sections.txt " "file (see förklaring)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2184 +#: C/index.docbook:2190 msgid "Damn, I have still no class hierarchy." msgstr "Förbannat, jag har fortfarande ingen klasshierarki." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2185 +#: C/index.docbook:2191 msgid "" "Is the object name (name of the instance struct, e.g. GtkWidget) part of the normal section (don't put this into Standard or Private " @@ -3713,12 +3722,12 @@ msgstr "" "Standard eller Private)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2192 +#: C/index.docbook:2198 msgid "No symbol index." msgstr "Inget symbolindex." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2193 +#: C/index.docbook:2199 msgid "" "Does the <package>-docs.{xml,sgml} contain a " "index that xi:includes the generated index?" @@ -3727,12 +3736,12 @@ msgstr "" "inkluderar det genererade indexet med xi:include?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2199 +#: C/index.docbook:2205 msgid "Symbols are not linked to their doc-section." msgstr "Symboler är inte länkade till deras dokumentationsavsnitt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2200 +#: C/index.docbook:2206 msgid "" "Is the doc-comment using the correct markup (added #,% or ())? Check if the " "gtkdoc-fixxref warns about unresolvable xrefs." @@ -3742,12 +3751,12 @@ msgstr "" "korsreferenser." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2206 +#: C/index.docbook:2212 msgid "A new class does not appear in the docs." msgstr "En ny klass dyker inte upp i dokumentationen." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2207 +#: C/index.docbook:2213 msgid "" "Is the new page xi:included from <package>-docs.{xml,sgml}." @@ -3756,12 +3765,12 @@ msgstr "" "docs.{xml,sgml}." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2213 +#: C/index.docbook:2219 msgid "A new symbol does not appear in the docs." msgstr "En ny symbol dyker inte upp i dokumentationen." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2214 +#: C/index.docbook:2220 msgid "" "Is the doc-comment properly formatted. Check for spelling mistakes in the " "begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable " @@ -3774,12 +3783,12 @@ msgstr "" "paket>-sections.txt i ett publikt avsnitt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2222 +#: C/index.docbook:2228 msgid "A type is missing from the class hierarchy." msgstr "En typ saknas från klasshierarkin." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2223 +#: C/index.docbook:2229 msgid "" "If the type is listed in <package>.hierarchy but " "not in xml/tree_index.sgml then double check that the " @@ -3794,12 +3803,12 @@ msgstr "" "privat kommer den inte att visas." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2232 +#: C/index.docbook:2238 msgid "I get foldoc links for all gobject annotations." msgstr "Jag får foldoc-länkar för alla gobject-noteringar." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2233 +#: C/index.docbook:2239 msgid "" "Check that xml/annotation-glossary.xml is xi:included " "from <package>-docs.{xml,sgml}." @@ -3809,12 +3818,12 @@ msgstr "" "filename>." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2241 +#: C/index.docbook:2247 msgid "Parameter described in source code comment block but does not exist" msgstr "Parameter beskriven i kommentarsblock i källkoden men existerar inte" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2242 +#: C/index.docbook:2248 msgid "" "Check if the prototype in the header has different parameter names as in the " "source." @@ -3822,12 +3831,12 @@ msgstr "" "Kontrollera om prototypen i huvudet har andra parameternamn än i källkoden." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2247 +#: C/index.docbook:2253 msgid "multiple \"IDs\" for constraint linkend: XYZ" msgstr "multipla ”ID:n” för begränsat länkslut: XYZ" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2248 +#: C/index.docbook:2254 msgid "" "Symbol XYZ appears twice in <package>-sections.txt file." @@ -3836,19 +3845,19 @@ msgstr "" "txt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2251 +#: C/index.docbook:2257 msgid "" "Element typename in namespace '' encountered in para, but no template " "matches." msgstr "Elementtypnamn i namnrymd ”” påträffat i para, men ingen mall matchar." #. (itstool) path: chapter/title -#: C/index.docbook:2258 +#: C/index.docbook:2264 msgid "Tools related to gtk-doc" msgstr "Verktyg relaterade till gtk-doc" #. (itstool) path: chapter/para -#: C/index.docbook:2260 +#: C/index.docbook:2266 msgid "" "GtkDocPlugin - a Trac " "GTK-Doc integration plugin, that adds API docs to a trac site and " @@ -3859,7 +3868,7 @@ msgstr "" "dokumentation till en trac-webbplats och integrerar med trac-sökningen." #. (itstool) path: chapter/para -#: C/index.docbook:2265 +#: C/index.docbook:2271 msgid "" "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " "tags in the API to determine the minimum required version." diff --git a/help/manual/ta/index.docbook b/help/manual/ta/index.docbook index ece6308..217f47e 100644 --- a/help/manual/ta/index.docbook +++ b/help/manual/ta/index.docbook @@ -68,6 +68,12 @@ + 1.29 + 28 Aug 2018 + ss + development + + 1.28 24 Mar 2018 ss @@ -207,7 +213,12 @@ - ஆவணம் எழுதும் முறை. ஆசிரியர் மூல கோப்பை ஒவ்வொரு செயல், மேக்ரோ, இணைப்புக்கும் ஆவணங்களால் நிரப்புவார். (முன்னே விவரங்கள் உருவாக்கப்பட்ட வார்ப்புரு கோப்புக்களால் உள்ளிடப்பட்டது. அப்படி இனி செய்ய பரிந்துரைக்கவில்லை.) + + Writing the documentation. + + The author fills in the source files with the documentation for each + function, macro, structs or unions, etc. + @@ -296,10 +307,20 @@ ஜிடிகே டாக் பற்றி + + 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. + + (FIXME) - (History, authors, web pages, mailing list, license, future plans, + (authors, web pages, mailing list, license, future plans, comparison with other similar systems.) @@ -317,32 +338,94 @@ - உங்கள் திட்டத்தை அமைத்தல் + Project Setup - 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 plain - makefiles or other build systems will describe the basics needed to - work in a different build setup. + This Chapter describes the steps that are necessary to integrate GTK-Doc + into your project. The integration of GTK-Doc into a project includes the + following steps: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + + + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. தோராய ஆவணம் அமைத்தல் - உங்கள் தலை மட்ட திட்ட அடைவில் இந்த மாதிரி அடைவுகளை உருவாக்குக.docs/reference (இதனால் உங்களுக்கு பயனர் ஆவணம் docs/help உம் கிடைக்கும்). இன்னொரு துணை அடைவு doc-package என் பெயரிட்டு உருவாக்கவும். ஒரே ஒரு நூலகம் உள்ள பொதிகளுக்கு இந்த படி தேவையில்லை + + A common convention is to place documentation into a folder called + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. + - This can then look as shown below: - Example directory structure + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project - - ஆட்டோ கான்ஃப் உடன் ஒருங்கிணைப்பு + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + - ரொம்ப சுலபம். configure.ac குறுநிரலுக்கு ஒரே ஒரு வரி மட்டும் சேருங்கள். + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - ஆட்டோ கான்ஃப் உடன் ஒருங்கிணைப்பு - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - - 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 - GTK_DOC_CHECK at the start of a line. - Keep gtk-doc optional - + + ஆட்டோமேக் உடன் ஒருங்கிணைப்பு + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + + +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ + - - முதல் தரு மதிப்பு வடிவமைப்பு நேரத்தில் ஜிடிகே டாக் இன் பதிப்பை சோதிக்கிறது. இரண்டாவது தெர்வு தருமதிப்பு. இது இந்த நிரலால் பயன்படுத்தப்படுகிறது. gtkdocize. GTK_DOC_CHECK மேக்ரோ பல மாற்றிகளை வடிவமைத்து சேர்க்கிறது: - - --with-html-dir=PATH : நிறுவிய ஆவணங்களுக்கான பாதை - ""--enable-gtk-doc :ஆவணமாக்கத்துக்கு ஜிடிகே டாக் ஐ பயன்படுத்துக. [முன்னிருப்பு=இல்லை] - --enable-gtk-doc-html : html ஒழுங்கில் ஆவணத்தை உருவாக்குக[முன்னிருப்பு=ஆம்] - --enable-gtk-doc-pdf : pdf ஒழுங்கில் ஆவணத்தை உருவாக்குக [முன்னிருப்பு=இல்லை] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. - - ஜிடிகே டாக் GTK-Doc முன்னிருப்பாக செயலிழந்து இருக்கும்! ஆகவே அடுத்த configure இயக்கத்துக்கு இந்த தேர்வை செய்க: . இல்லையானால் முன் உருவாக்கிய ஆவணங்கள் நிறூவப்படும்.( இது பயனர்களுக்கு புரியும், நல்லது. ஆனால் உருவாக்குவோருக்கு அல்ல). - + All settings have a comment above them that describes their purpose + and how to customize the setting. - - Furthermore it is recommended that you have the following line inside - your configure.ac script. - This allows gtkdocize to automatically copy the - macro definition for GTK_DOC_CHECK to your project. - + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). - - gtkdocize க்கு முன்னேற்பாடு - --help to list the supported + options. + + + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. + + + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + ஆட்டோ கான்ஃப் உடன் ஒருங்கிணைப்பு + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - - After all changes to configure.ac are made, update - the configure file. This can be done by re-running - autoreconf -i or autogen.sh. - - + + - - ஆட்டோமேக் உடன் ஒருங்கிணைப்பு + + 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: - - First copy the Makefile.am from the - examples sub directory of the - gtkdoc-sources - to your project's API documentation directory ( - ./docs/reference/<package>). - A local copy should be available under e.g. - /usr/share/doc/gtk-doc-tools/examples/Makefile.am. - If you have multiple doc-packages repeat this for each one. - + + Integration with optional gtk-doc dependency + + + - - The next step is to edit the settings inside the Makefile.am. - 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 . - All the tools support to list the supported - parameters. - + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - + + --with-html-dir=PATH : நிறுவிய ஆவணங்களுக்கான பாதை + ""--enable-gtk-doc :ஆவணமாக்கத்துக்கு ஜிடிகே டாக் ஐ பயன்படுத்துக. [முன்னிருப்பு=இல்லை] + --enable-gtk-doc-html : html ஒழுங்கில் ஆவணத்தை உருவாக்குக[முன்னிருப்பு=ஆம்] + --enable-gtk-doc-pdf : pdf ஒழுங்கில் ஆவணத்தை உருவாக்குக [முன்னிருப்பு=இல்லை] + - + + ஜிடிகே டாக் GTK-Doc முன்னிருப்பாக செயலிழந்து இருக்கும்! ஆகவே அடுத்த configure இயக்கத்துக்கு இந்த தேர்வை செய்க: . இல்லையானால் முன் உருவாக்கிய ஆவணங்கள் நிறூவப்படும்.( இது பயனர்களுக்கு புரியும், நல்லது. ஆனால் உருவாக்குவோருக்கு அல்ல). + - - ஆட்டொஜென் உடன் ஒருங்கிணைத்தல் + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - முக்கால்வாசி திட்டங்களில் (cvs/svn/git போன்ற) வெர்ஷன் கட்டுப்பாடு அமைப்பில் இருந்து பெறப்பட்டதும் அடிக்கட்டுமான பணியை செய்ய autogen.sh குறுநிரல் இருக்கும். ஜிடிகே டாக் (GTK-Doc) இல் gtkdocize என ஒரு கருவி உண்டு. இது அது போன்ற குறுநிரலுடன் வேலை செய்யும்.இது autoheader, automake அல்லது autoconf க்கு முன்னால் இயக்கப்பட வேண்டும். + + ஆட்டொஜென் உடன் ஒருங்கிணைத்தல் - - autogen.sh இலிருந்து gtkdocize ஐ இயக்குதல் - + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + + + + It should be run before autoreconf, autoheader, automake or autoconf. + + + + autogen.sh இலிருந்து gtkdocize ஐ இயக்குதல் + - - + + - - When running gtkdocize it copies - gtk-doc.make to your project root (or any directory - specified by the option). - It also checks you configure script for the GTK_DOC_CHECK - invocation. This macro can be used to pass extra parameters to - gtkdocize. - + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - - 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. gtkdocize supports now - a 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 GTKDOCIZE_FLAGS - or set as a 2nd parameter in GTK_DOC_CHECK 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). - - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - டாக் உருவாக்கியை (doc build) இயக்குதல் + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - இப்போது கட்டுமானத்திற்கு ஆயத்தமாகிவிட்டோம். முதலில் நாம் மீன்டும் autogen.sh ஐ இயக்கவேண்டும். இது உங்களுக்கு கட்டமைப்பை இயக்கினால் அதற்கு தேர்வை தரவும். இல்லையானால் கைமுறையாக இதே தேர்வுடன் configure ஐ பிரிதொரு முறை இயக்கவும். - - The first make run generates several additional files in the doc-directories. - The important ones are: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt. - - - டாக் உருவாக்கியை (doc build) இயக்குதல் - + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + இப்போது கட்டுமானத்திற்கு ஆயத்தமாகிவிட்டோம். முதலில் நாம் மீன்டும் autogen.sh ஐ இயக்கவேண்டும். இது உங்களுக்கு கட்டமைப்பை இயக்கினால் அதற்கு தேர்வை தரவும். இல்லையானால் கைமுறையாக இதே தேர்வுடன் configure ஐ பிரிதொரு முறை இயக்கவும். + + The first make run generates several additional files in the doc-directories. + The important ones are: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt. + + + டாக் உருவாக்கியை (doc build) இயக்குதல் + - - - இப்போது உங்கள் உலாவியை docs/reference/<package>/index.html க்கு சுட்டிக்காட்டலாம். ஆமாம், இது கொஞ்சம் ஏமாற்றமாகத்தான் இருக்கிறது. கவலை வேண்டாம். அடுத்த அத்தியாயத்தில் எப்படி இவற்றை உயிருக்கு கொண்டு வருவது என பார்க்கலாம். + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - வெர்ஷன் கன்ட்ரோல் அமைப்புகளுடன் ஒருங்கிணைத்தல் + + Integration with CMake build systems - As a rule of thumb, it's the files you edit which should go under - version control. For typical projects it's these files: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt, - Makefile.am. + GTK-Doc now provides a GtkDocConfig.cmake module + (and the corresponding GtkDocConfigVersion.cmake + module). This provides a gtk_doc_add_module + command that you can set in your CMakeLists.txt + file. + - Files in the xml/ and html/ - directories should not go under version control. Neither should any of - the .stamp files. + The following example shows how to use this command. + Example of using GTK-Doc from CMake + + - + Integration with plain makefiles or other build systems @@ -551,42 +906,24 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html - - Integration with CMake build systems - - - GTK-Doc now provides a GtkDocConfig.cmake module - (and the corresponding GtkDocConfigVersion.cmake - module). This provides a gtk_doc_add_module - command that you can set in your CMakeLists.txt - file. - - - - The following example shows how to use this command. - Example of using GTK-Doc from CMake - + வெர்ஷன் கன்ட்ரோல் அமைப்புகளுடன் ஒருங்கிணைத்தல் -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + + As a rule of thumb, it's the files you edit which should go under + version control. For typical projects it's these files: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt, + Makefile.am. + + + Files in the xml/ and html/ + directories should not go under version control. Neither should any of + the .stamp files. + + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - - @@ -599,16 +936,10 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html syntax of the comments. - - ஆவணம் இடுதல் - முன் காலத்தில் பெரும்பாலான ஆவணங்கள் tmpl அடைவில் இருக்கும் கோப்புகளில் நிரப்பப்பட வேண்டி இருந்தது. இதில் நஷ்டமாக தகவல்கள் அவ்வப்போது புதுப்பிக்கப்படவில்லை. மேலும் இவை வெர்ஷன் கட்டுப்பாடு அமைப்புகளுடன் பொருந்தவில்லை - மேற்கூறிய காரணங்களால் நாங்கள் ஆவணங்களை மூலத்துடன் வைக்கு மாறூ சொல்கிறோம். இந்த கையேடு இந்த முறையை மட்டுமே விவாதிக்கும். - - - The scanner can handle the majority of C headers fine. In the case of - receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + The GTK-Doc scanner can handle the majority of C headers fine. In the + case of receiving warnings from the scanner that look like a special + case, one can hint GTK-Doc to skip over them. GTK-Doc comment block - ஜிடிகே டாக் + + 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. + @@ -1568,7 +1909,7 @@ int main(int argc, char *argv[]) - Example types file snippet + Example <package>.types file @@ -1901,7 +2242,8 @@ endif containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included - and how the entities are used. The entities can also be used in all + in the master template and how the entities are used. + The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities diff --git a/help/manual/te/index.docbook b/help/manual/te/index.docbook index bdd3f61..a83c469 100644 --- a/help/manual/te/index.docbook +++ b/help/manual/te/index.docbook @@ -68,6 +68,12 @@ + 1.29 + 28 Aug 2018 + ss + development + + 1.28 24 Mar 2018 ss @@ -207,7 +213,12 @@ - పత్రికీకరణను వ్రాయుట. మూలకర్త(ఆథర్) సోర్స్ ఫైళ్ళనందు ప్రతి ఫంక్షన్‌కు, మాక్రోకు, యూనియన్‌కు పత్రకీకరణను యిస్తాడు. (గతంలో సమాచారమును మాదిరి ఫైళ్ళనందు ప్రవేశపెట్టేవారు, యిది యిప్పడు సమర్ధించబడదు). + + Writing the documentation. + + The author fills in the source files with the documentation for each + function, macro, structs or unions, etc. + @@ -296,10 +307,20 @@ GTK-Doc గురించి + + 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. + + (FIXME) - (History, authors, web pages, mailing list, license, future plans, + (authors, web pages, mailing list, license, future plans, comparison with other similar systems.) @@ -317,32 +338,94 @@ - మీ ప్రోజెక్టును అమర్చుట + Project Setup - 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 plain - makefiles or other build systems will describe the basics needed to - work in a different build setup. + This Chapter describes the steps that are necessary to integrate GTK-Doc + into your project. The integration of GTK-Doc into a project includes the + following steps: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + + + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. స్కెల్టెన్ పత్రికీకరణను అమర్చుచున్నది - మీ పై-స్థాయి ప్రోజెక్టు డైరెక్టరీ క్రింద docs/reference అను ఫోల్డర్లను సృష్టించుము (ఈ విధంగా మీరు docs/helpను అంత్య-వినియోగదారి పత్రికీకరణ కొరకు కలిగివుండవచ్చును). doc-package నామముతో వేరొక వుపసంచయంను సృష్టించుకొనుట సిఫార్సు చేయబడింది. కేవలం వొక లైబ్రరీ మాత్రమే వున్న ప్యాకేజీలకు యిది అవసరములేదు. + + A common convention is to place documentation into a folder called + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. + - This can then look as shown below: - Example directory structure + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project - - autoconf తో విలీనం + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + - చాలా సులువు! మీ configure.ac స్క్రిప్టునకు వొక లైను మాత్రమే జతచేయుము. + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - autoconf తో విలీనం - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - - 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 - GTK_DOC_CHECK at the start of a line. - Keep gtk-doc optional - + + automake తో విలీనం + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + + +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ + - - ఆకృతీకరణ సమయము వద్ద gtkdocversion కొరకు పరిశీలించుటకు మొదటి ఆర్గుమెంటు వుపయోగించబడింది. 2వది, gtkdocize చేత వుపయోగించబడిన ఐచ్చిక ఆర్గుమెంట్. GTK_DOC_CHECK మాక్రో చాలా ఆకృతీకరణ స్విచ్‌లను జతచేస్తుంది: - - --with-html-dir=PATH : సంస్థాపించిన పత్రములకు పాత్ - --enable-gtk-doc : పత్రికీకరణను నిర్మించుటకు gtk-doc వుపయోగించుము [default=no] - --enable-gtk-doc-html : పత్రికీకరణను html ఫార్మాట్‌నందు నిర్మించుము [default=yes] - --enable-gtk-doc-pdf : పత్రికీకరణను pdf ఫార్మాట్ నందు నిర్మించుము [default=no] - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. - - GTK-Doc అప్రమేయంగా అచేతనము చేయబడింది! ఐచ్చికము ను తరువాతి configureకు నడుపుట మర్చిపోవద్దు. లేకపోతే ముందుగా జనియింపచేసిన పత్రికీకరణ సంస్థాపించబడుతుంది (ఇది వినియోగదారులకు వుపయోగకరం అయితే అభివృద్దికారులకు కాదు). - + All settings have a comment above them that describes their purpose + and how to customize the setting. - - Furthermore it is recommended that you have the following line inside - your configure.ac script. - This allows gtkdocize to automatically copy the - macro definition for GTK_DOC_CHECK to your project. - + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). - - gtkdocize కొరకు సన్నాహం - --help to list the supported + options. + + + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. + + + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + autoconf తో విలీనం + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - - After all changes to configure.ac are made, update - the configure file. This can be done by re-running - autoreconf -i or autogen.sh. - - + + - - automake తో విలీనం + + 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: - - First copy the Makefile.am from the - examples sub directory of the - gtkdoc-sources - to your project's API documentation directory ( - ./docs/reference/<package>). - A local copy should be available under e.g. - /usr/share/doc/gtk-doc-tools/examples/Makefile.am. - If you have multiple doc-packages repeat this for each one. - + + Integration with optional gtk-doc dependency + + + - - The next step is to edit the settings inside the Makefile.am. - 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 . - All the tools support to list the supported - parameters. - + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - + + --with-html-dir=PATH : సంస్థాపించిన పత్రములకు పాత్ + --enable-gtk-doc : పత్రికీకరణను నిర్మించుటకు gtk-doc వుపయోగించుము [default=no] + --enable-gtk-doc-html : పత్రికీకరణను html ఫార్మాట్‌నందు నిర్మించుము [default=yes] + --enable-gtk-doc-pdf : పత్రికీకరణను pdf ఫార్మాట్ నందు నిర్మించుము [default=no] + - + + GTK-Doc అప్రమేయంగా అచేతనము చేయబడింది! ఐచ్చికము ను తరువాతి configureకు నడుపుట మర్చిపోవద్దు. లేకపోతే ముందుగా జనియింపచేసిన పత్రికీకరణ సంస్థాపించబడుతుంది (ఇది వినియోగదారులకు వుపయోగకరం అయితే అభివృద్దికారులకు కాదు). + - - autogen తో విలీనం + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - వర్షన్ కంట్రోల్ సిస్టమ్ (cvs/svn/git వంటి) నుండి చెక్అవుట్ తర్వాత బుల్డ్ నిర్మాణం అమర్చుటకు చాలా ప్రోజెక్టులు autogen.sh స్క్రిప్టును కలిగివుంటాయి. GTK-Doc అనునది gtkdocize అనబడు సాధనంతో వస్తుంది దీనిని అటువంటి స్క్రిప్టు నందు వుపయోగించవచ్చును. ఇది autoheader, automake లేదా autoconf ముందు నడుపవలెను. + + autogen తో విలీనం - - autogen.sh నుండి gtkdocize నడుపుతోంది - + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + + + + It should be run before autoreconf, autoheader, automake or autoconf. + + + + autogen.sh నుండి gtkdocize నడుపుతోంది + - - + + - - When running gtkdocize it copies - gtk-doc.make to your project root (or any directory - specified by the option). - It also checks you configure script for the GTK_DOC_CHECK - invocation. This macro can be used to pass extra parameters to - gtkdocize. - + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - - 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. gtkdocize supports now - a 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 GTKDOCIZE_FLAGS - or set as a 2nd parameter in GTK_DOC_CHECK 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). - - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - doc బుల్డును నడుపుట + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - గతంలో జరిపిన స్టెప్పుల తర్వాత యిప్పుడు బుల్డును నడుపవలెను. ముందుగా మనము autogen.shను తిరిగి నడుపవలెను. ఈ స్క్రిప్టు మీ కొరకు ఆకృతీకరణను నడిపితే, దానికి ఐచ్చికాన్ని యివ్వుము. లేదా తరువాత ఈ ఐచ్చికముతో మానవీయంగా configureను నడుపుము. - - The first make run generates several additional files in the doc-directories. - The important ones are: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt. - - - doc బుల్డును నడుపుట - + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + గతంలో జరిపిన స్టెప్పుల తర్వాత యిప్పుడు బుల్డును నడుపవలెను. ముందుగా మనము autogen.shను తిరిగి నడుపవలెను. ఈ స్క్రిప్టు మీ కొరకు ఆకృతీకరణను నడిపితే, దానికి ఐచ్చికాన్ని యివ్వుము. లేదా తరువాత ఈ ఐచ్చికముతో మానవీయంగా configureను నడుపుము. + + The first make run generates several additional files in the doc-directories. + The important ones are: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt. + + + doc బుల్డును నడుపుట + - - - ఇప్పుడు మీ బ్రౌజర్‌కు మీరు docs/reference/<package>/index.htmlను సూచించవచ్చును. అవును, యిప్పటికి యిది కొంత నిరుత్సాహపరుస్తోంది. అయితే ఆగండి, తరువాతి అధ్యాయమునందు పేజీలను యెలా నింపాలో చెబుతాము. + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - వర్షన్ కంట్రోల్ సిస్టమ్‌తో విలీనం + + Integration with CMake build systems - As a rule of thumb, it's the files you edit which should go under - version control. For typical projects it's these files: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt, - Makefile.am. + GTK-Doc now provides a GtkDocConfig.cmake module + (and the corresponding GtkDocConfigVersion.cmake + module). This provides a gtk_doc_add_module + command that you can set in your CMakeLists.txt + file. + - Files in the xml/ and html/ - directories should not go under version control. Neither should any of - the .stamp files. + The following example shows how to use this command. + Example of using GTK-Doc from CMake + + - + Integration with plain makefiles or other build systems @@ -551,42 +906,24 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html - - Integration with CMake build systems - - - GTK-Doc now provides a GtkDocConfig.cmake module - (and the corresponding GtkDocConfigVersion.cmake - module). This provides a gtk_doc_add_module - command that you can set in your CMakeLists.txt - file. - - - - The following example shows how to use this command. - Example of using GTK-Doc from CMake - + వర్షన్ కంట్రోల్ సిస్టమ్‌తో విలీనం -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + + As a rule of thumb, it's the files you edit which should go under + version control. For typical projects it's these files: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt, + Makefile.am. + + + Files in the xml/ and html/ + directories should not go under version control. Neither should any of + the .stamp files. + + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - - @@ -599,16 +936,10 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html syntax of the comments. - - పత్రికీకరణ స్థానము - గతంలో చాలా వరకు పత్రికీకరణ అనునది tmpl డైరెక్టరీ క్రిందని ఫైళ్ళలో నింపవలసివుండేది. సమాచారము సరిగా నవీకరించబడక పోవుట మరియు ఆ ఫైలు వర్షన్ కంట్రోల్ సిస్టమ్సుతో విభేదించుట వంటి లోపాలను యిది కలిగివుంది. - ముందుగా తెలిపిన సమస్యలను తప్పించుటకు మేము పత్రికీకరణను మూలముల లోపలే వుంచమని సూచించుచున్నాము. ఈ మాన్యుయల్ ఈ విధంగా కోడ్ పత్రికీకరణను మాత్రమే వివరించును. - - - The scanner can handle the majority of C headers fine. In the case of - receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + The GTK-Doc scanner can handle the majority of C headers fine. In the + case of receiving warnings from the scanner that look like a special + case, one can hint GTK-Doc to skip over them. GTK-Doc comment block - ముందుగా చెప్పినట్లుగా GTK-Doc అనునది పబ్లిక్ API పత్రికీకరణ కొరకు. స్థిర చిహ్నములకు వొక్కరే పత్రికీకరణ వ్రాయలేరు. ఆ చిహ్నములను కూడా వ్యాఖ్యానించుట మంచిది. ఇది యితరులు కూడా మీ కోడ్‌ను అర్ధము చేసుకొనుటకు సహాయపడును. అందుకని వీటిని సాదారణ వ్యాఖ్యలు (మొదటి వరుసనందు 2వ '*' లేకుండా) వుపయోగించి వ్యాఖ్యానించమని సూచించడమైంది. తరువాత ఆ ఫంక్షన్ పబ్లిక్‌గా మార్చవలసివుంటే, చేయవలసినదల్లా వేరొక '*'ను వ్యాఖ్య బ్లాక్ నందు చేర్చి మరియు చిహ్నపు నామాన్నివిభగాముల ఫైలునందు సరైన స్థానములో వుంచడమే. + + 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. + @@ -1539,7 +1880,7 @@ int main(int argc, char *argv[]) - Example types file snippet + Example <package>.types file @@ -1896,7 +2237,8 @@ endif containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included - and how the entities are used. The entities can also be used in all + in the master template and how the entities are used. + The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities diff --git a/help/manual/zh_CN/index.docbook b/help/manual/zh_CN/index.docbook index 10352de..fbabc2a 100644 --- a/help/manual/zh_CN/index.docbook +++ b/help/manual/zh_CN/index.docbook @@ -46,6 +46,12 @@ + 1.29 + 28 Aug 2018 + ss + development + + 1.28 24 Mar 2018 ss @@ -198,8 +204,7 @@ Writing the documentation. The author fills in the source files with the documentation for each - function, macro, union etc. (In the past information was entered in - generated template files, which is not recommended anymore). + function, macro, structs or unions, etc. @@ -301,11 +306,21 @@ 关于 GTK-Doc + 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. + + + (FIXME) - (History, authors, web pages, mailing list, license, future plans, + (authors, web pages, mailing list, license, future plans, comparison with other similar systems.) @@ -325,232 +340,550 @@ - 设置您的项目 + Project Setup - 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 plain - makefiles or other build systems will describe the basics needed to - work in a different build setup. + This Chapter describes the steps that are necessary to integrate GTK-Doc + into your project. The integration of GTK-Doc into a project includes the + following steps: + + + + + + Preparation of the directory structure and creating required + configuration files for your GTK-Doc documentation (see + + Setting up a skeleton documentation). + + + + + 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 + Autotools, + CMake, and + plain Makefiles. + + + + + Adding GTK-Doc specific files to version control and deciding which + files to ignore (see + Integration with version control systems). + + + + + + The following sections assume we work on a project called + meep. + This project contains two packages (or modules), + a library called libmeep and an end-user app + called meeper. 设置一个框架文档 - 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 + docs inside your top-level project directory. + We usually distinguish between reference + documentation intended for developers and an + user manual intended for end-users. + Again the convention is to have separate folders for both. + We usually place the reference documentation in a folder named + reference and the end-user manual in a folder named + help as. + + According to the above convention the documentation for our + libmeep package would be placed into: + docs/reference/libmeep. + + For packages with just one library or application + the documentation could also be placed directly into + docs/reference. + + 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. - 目录结构将会如下所示：范例目录结构 + + In the following sections we will assume a directory structure + for our meep project that uses the above + conventions. + + + Example directory structure of <emphasis>meep</emphasis> + project - + + - - 与autoconf集成 + + Integration with Autotools + + Integration of GTK-Doc into an autotools-based build system requires the + following steps: + + + + + Ensure that gtkdocize is run once before + the configure script. If an + autogen.sh script is present, adjust it to + check for GTK-Doc and add a call to + gtkdocize. + - 非常容易！只需在您的 configure.ac 脚本中添加一行。 + + The main purpose of gtkdocize is to + make the gtk-doc.make Makefile and the + gtk-doc.m4 macro definition file available + to the build system, either by copying or linking it + into the project. + + + + + Add the necessary autoconf macros to + configure.ac to enable GTK-Doc in your build + system to allow configuration of GTK-Doc via the generated + configure script. + + + Among others with registers the --enable-gtk-doc + option with the configure script. + + + + + Create an automake script for each + application or library in your project. In the example used in this + documentation this step applies to both meeper and + libmeep. + + + - 与autoconf集成 - - + In the following sections, we will perform the above steps in reverse + order. We start with the automake scripts + and work our way up to configure.ac and + autogen.sh. + Then we show how enable Gtk-Doc in the build system and + how to build the documentation. - - 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 - GTK_DOC_CHECK at the start of a line. - Keep gtk-doc optional - + + 与automake集成 + + + First copy the Makefile.am from the + examples sub-directory of the + + gtkdoc-sources + to your project's reference documentation directory (e.g. + docs/reference/<package>). + A local copy should be available under e.g. + /usr/share/doc/gtk-doc-tools/examples/Makefile.am. + If you have multiple packages repeat this for each one. + + + + + Do not forget to add each Makefile.am + to the AC_CONFIG_FILES macro in + configure.ac. For + docs/reference/libmeep/Makefile.am you will + need to add the entry + docs/reference/libmeep/Makefile + to AC_CONFIG_FILES. + + + + + + Example directory structure with <filename>Makefiles.am</filename> + + +meep/ + docs/ + reference/ # reference documentation + libmeep/ + Makefile.am + meeper/ + Makefile.am + help/ # optional: user manual + meeper/ + src/ + libmeep/ + meeper/ + - - - The first argument is used to check for the gtkdocversion at configure time. - The 2nd, optional argument is used by gtkdocize. - The GTK_DOC_CHECK macro also adds several configure switches: - - - --with-html-dir=PATH : 安装文档的路径 - --enable-gtk-doc : 用gtk-doc构建文档［默认值：no］ - --enable-gtk-doc-html :用html格式构建文档［默认值：yes］ - --enable-gtk-doc-pdf : 以PDF格式构建文档［默认值：no］ - + + Next, you need to customize the copied Makefiles + and provide values for the various parameters in each + Makefile.am. - - GTK-Doc在默认情况下是关闭的！请记得给文本configure运作时传递选项。否则，将会安装预先生成的文档（对用户有意义但对开发人员没用处）。 - + All settings have a comment above them that describes their purpose + and how to customize the setting. - - Furthermore it is recommended that you have the following line inside - your configure.ac script. - This allows gtkdocize to automatically copy the - macro definition for GTK_DOC_CHECK to your project. - + Most settings are used to supply extra flags to the respective tools + to which they apply. Every tool + has a variable of the form + (e.g. the tool gtkdoc-mkhtml has + an option named MKHTML_OPTIONS). - - 准备gtkdocize - --help to list the supported + options. + + + + The following list explains the most relevant options. Check the + example Makefile.am for additional options. + + + + + is used to provide the name of the + package that is being documentated (e.g. meeper, or + libmeep). + + + + + + is used to specify the location + of source directory which GTK-Doc searches for your API + documentation. This will usually be + + DOC_SOURCE_DIR=$(top_srcdir)/src + + or a sub-directory of that directory. + + + + + + + and + + are used for dependencies. Each option take a file-glob (e.g. + HFILE_GLOB=$(top_srcdir)/src/*.c). + The documentation will be rebuilt if any of the matched files + change. + + + + + + + allows to specify extra header files + to include when scanning for API documentation, which are not + found under DOC_SOURCE_DIR (e.g. + EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). + + + + + + + allows to specify header files + or directories to ignore when scanning for API documentation. + Use the basename of the file or directory (e.g. + IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). + + + + + + + allows to specify images files which + will be copied into the html/ directory of + the generated documentation. + If your API documentation includes any images they need to be + added to this + option (e.g. + HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). + + + + + + + allows to specify extra files + that are included by + $(DOC_MAIN_SGML_FILE) + (e.g. + content_files=running.xml building.xml changes-2.0.xml). + + + + + + + allows to specify files + where gtk-doc abbrevations such as + #GtkWidget + are expanded (e.g. + expand_content_files=running.xml). + + + + + + + + + 与autoconf集成 + + + Integration with autoconf is very simple + and includes one required step and an additional optional + (but recommended) step. + + The first step is to add the GTK_DOC_CHECK macro + to your configure.ac script. This registers + several configure options to enable GTK-Doc and allows you + to set default arguments for gtkdocize. + + + + + Make sure that the GTK_DOC_CHECK macro is not indented. + The macro must start at the beginning of the line and should not + start with whitespace. + + + + + The second step is to add the AC_CONFIG_MACRO_DIR(m4) + to your configure.ac. This is not required + but helps gtkdocize to automatically copy + the macro definition (e.g gtk-doc.m4) which + contains the GTK_DOC_CHECK 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 + aclocal tool where to find the macro + definition file. + + + + Minimal integration with autoconf + - - - - After all changes to configure.ac are made, update - the configure file. This can be done by re-running - autoreconf -i or autogen.sh. - - + + - - 与automake集成 + + 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: - - First copy the Makefile.am from the - examples sub directory of the - gtkdoc-sources - to your project's API documentation directory ( - ./docs/reference/<package>). - A local copy should be available under e.g. - /usr/share/doc/gtk-doc-tools/examples/Makefile.am. - If you have multiple doc-packages repeat this for each one. - + + Integration with optional gtk-doc dependency + + + - - The next step is to edit the settings inside the Makefile.am. - 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 . - All the tools support to list the supported - parameters. - + + The first argument is used to check for the Gtk-Doc version at + configure time. The 2nd, optional argument is used by + gtkdocize. + The GTK_DOC_CHECK macro also adds several configure + switches: + - + + --with-html-dir=PATH : 安装文档的路径 + --enable-gtk-doc : 用gtk-doc构建文档［默认值：no］ + --enable-gtk-doc-html :用html格式构建文档［默认值：yes］ + --enable-gtk-doc-pdf : 以PDF格式构建文档［默认值：no］ + - + + GTK-Doc在默认情况下是关闭的！请记得给文本configure运作时传递选项。否则，将会安装预先生成的文档（对用户有意义但对开发人员没用处）。 + - - 与autogen集成 + + After all changes to configure.ac are made, + update the configure file. This can be done by + re-running autogen.sh. + + - - Most projects will have an autogen.sh 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 - gtkdocize which can be used in such a script. - It should be run before autoheader, automake or autoconf. - + + 与autogen集成 - - 从autogen.sh中运行gtkdocize - + Most projects will have an autogen.sh 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 gtkdocize which can be used + to copy the necessary files needed by Gtk-Doc to the source directory. + + + + It should be run before autoreconf, autoheader, automake or autoconf. + + + + 从autogen.sh中运行gtkdocize + - - + + - - When running gtkdocize it copies - gtk-doc.make to your project root (or any directory - specified by the option). - It also checks you configure script for the GTK_DOC_CHECK - invocation. This macro can be used to pass extra parameters to - gtkdocize. - + + + Conditionally run gtkdocize from autogen.sh + /dev/null) +if test $? -ne 0; then + echo "No gtk-doc support found. You can't build the docs." +else + $GTKDOCIZE || exit 1 +fi +]]> + + - - 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. gtkdocize supports now - a 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 GTKDOCIZE_FLAGS - or set as a 2nd parameter in GTK_DOC_CHECK 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). - - + + When running gtkdocize it copies + gtk-doc.make to your project root (or any + directory specified by the option). + - - 运行文档构建 + + gtkdocize checks your + configure.ac script for + the GTK_DOC_CHECK macro. + The GTK_DOC_CHECK macro can be used to pass + extra arguments to the gtkdocize script. + the 2nd parameter in the GTK_DOC_CHECK macro. + - - After the previous steps it's time to run the build. First we need to - rerun autogen.sh. If this script runs configure for - you, then give it the option. - Otherwise manually run configure with this option - afterwards. - - - The first make run generates several additional files in the doc-directories. - The important ones are: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt. - - - 运行文档构建 - + Alternatively, additional arguments can also be passed to + gtkdocize via the + GTKDOCIZE_FLAGS environment variable, or by + directly specifying them to gtkdocize + in autogen.sh. + + + + + + Executing GTK-Doc from the Build System + + + After the previous steps it's time to run the build. First we need to + rerun autogen.sh. If this script runs configure + for you, then give it the option. + Otherwise manually run configure with this option + afterwards. + + + The first make run generates several additional files in the doc-directories. + The important ones are: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt. + + + 运行文档构建 + - - - - Now you can point your browser to docs/reference/<package>/index.html. - Yes, it's a bit disappointing still. But hang-on, during the next chapter we - tell you how to fill the pages with life. - + + + + + Now you can point your browser to + docs/reference/<package>/index.html. + 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 + additional files and shows how to + edit the master template to + add additional chapters and sections to your documentation files. + + + + - - 与版本控制系统集成 + + Integration with CMake build systems - As a rule of thumb, it's the files you edit which should go under - version control. For typical projects it's these files: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt, - Makefile.am. + GTK-Doc now provides a GtkDocConfig.cmake module + (and the corresponding GtkDocConfigVersion.cmake + module). This provides a gtk_doc_add_module + command that you can set in your CMakeLists.txt + file. + - Files in the xml/ and html/ - directories should not go under version control. Neither should any of - the .stamp files. + The following example shows how to use this command. + Example of using GTK-Doc from CMake + + - + 与普通makefile或其它构建系统整合 @@ -578,42 +911,24 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html 您必须查阅Makefile.am 和 gtk-doc.mak以获取所须的额外选项。 - - Integration with CMake build systems - - - GTK-Doc now provides a GtkDocConfig.cmake module - (and the corresponding GtkDocConfigVersion.cmake - module). This provides a gtk_doc_add_module - command that you can set in your CMakeLists.txt - file. - - - - The following example shows how to use this command. - Example of using GTK-Doc from CMake - + 与版本控制系统集成 -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. -add_custom_target(documentation ALL DEPENDS doc-libmeep) + + As a rule of thumb, it's the files you edit which should go under + version control. For typical projects it's these files: + <package>.types, + <package>-docs.xml (in the past .sgml), + <package>-sections.txt, + Makefile.am. + + + Files in the xml/ and html/ + directories should not go under version control. Neither should any of + the .stamp files. + + -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). -install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - - @@ -626,16 +941,10 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html syntax of the comments. - - 文档位置 - 在过去，多数文档不得不写入驻留在tmpl目录的文件中。这样会出现一些糟糕的情况：其信息常常没有更新，而且文件也倾向于与版本控制系统发生冲突。 - 为避免上述的问题，我们建议把注释文档放入源代码中去。本手册仅描述此种编写代码文档的方法。 - - - The scanner can handle the majority of C headers fine. In the case of - receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + The GTK-Doc scanner can handle the majority of C headers fine. In the + case of receiving warnings from the scanner that look like a special + case, one can hint GTK-Doc to skip over them. GTK-Doc comment block - 如早先所述，GTK-Doc是为编写公共的API而作的。所以你不能够为静态符号编写文档。尽管如此，它也可以很好地为那些符号作注释。这有助于他人理解你的代码。因此我们建议你用普通的注释来注释它们（不使用第一行的第二个'*'号）。如果以后函数须要作为public，你须做的只是在注释块中加入另一个 '*'号并且在区段文件里插入正确的标识符名称。 + + 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. + @@ -1462,7 +1781,7 @@ int main(int argc, char *argv[]) - 示例类型文件代码段 + Example <package>.types file @@ -1791,7 +2110,8 @@ endif containing entities for e.g. package_name and package_version. You can use this e.g. in the main xml file to avoid hardcoding the version number. Below is an example that shows how the entity file is included - and how the entities are used. The entities can also be used in all + in the master template and how the entities are used. + The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. Use pre-generated entities diff --git a/m4/libtool.m4 b/m4/libtool.m4 index ee80844..a644432 100644 --- a/m4/libtool.m4 +++ b/m4/libtool.m4 @@ -728,6 +728,7 @@ _LT_CONFIG_SAVE_COMMANDS([ 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. @@ -2866,6 +2867,9 @@ linux* | k*bsd*-gnu | kopensolaris*-gnu | gnu*) # 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 @@ -2874,7 +2878,7 @@ linux* | k*bsd*-gnu | kopensolaris*-gnu | gnu*) # appending ld.so.conf contents (and includes) to the search path. if test -f /etc/ld.so.conf; then lt_ld_extra=`awk '/^include / { system(sprintf("cd /etc; cat %s 2>/dev/null", \[$]2)); skip = 1; } { if (!skip) print \[$]0; skip = 0; }' < /etc/ld.so.conf | $SED -e 's/#.*//;/^[ ]*hwcap[ ]/d;s/[:, ]/ /g;s/=[^=]*$//;s/=[^= ]* / /g;s/"//g;/^$/d' | tr '\n' ' '` - sys_lib_dlsearch_path_spec="/lib /usr/lib $lt_ld_extra" + sys_lib_dlsearch_path_spec="$sys_lib_dlsearch_path_spec $lt_ld_extra" fi # We used to test for /lib/ld.so.1 and disable shared libraries on @@ -2886,18 +2890,6 @@ linux* | k*bsd*-gnu | kopensolaris*-gnu | gnu*) 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 @@ -3557,7 +3549,7 @@ linux* | k*bsd*-gnu | kopensolaris*-gnu | gnu*) lt_cv_deplibs_check_method=pass_all ;; -netbsd* | netbsdelf*-gnu) +netbsd*) if echo __ELF__ | $CC -E - | $GREP __ELF__ > /dev/null; then lt_cv_deplibs_check_method='match_pattern /lib[[^/]]+(\.so\.[[0-9]]+\.[[0-9]]+|_pic\.a)$' else @@ -4435,7 +4427,7 @@ m4_if([$1], [CXX], [ ;; esac ;; - netbsd* | netbsdelf*-gnu) + netbsd*) ;; *qnx* | *nto*) # QNX uses GNU C++, but need to define -shared option too, otherwise @@ -4947,9 +4939,6 @@ m4_if([$1], [CXX], [ ;; 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' ;; @@ -5012,9 +5001,6 @@ dnl Note also adjust exclude_expsyms for C++ above. 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 @@ -5269,7 +5255,7 @@ _LT_EOF fi ;; - netbsd* | netbsdelf*-gnu) + netbsd*) if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then _LT_TAGVAR(archive_cmds, $1)='$LD -Bshareable $libobjs $deplibs $linker_flags -o $lib' wlarc= @@ -5790,7 +5776,6 @@ _LT_EOF 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' @@ -5812,7 +5797,7 @@ _LT_EOF esac ;; - netbsd* | netbsdelf*-gnu) + netbsd*) if echo __ELF__ | $CC -E - | $GREP __ELF__ >/dev/null; then _LT_TAGVAR(archive_cmds, $1)='$LD -Bshareable -o $lib $libobjs $deplibs $linker_flags' # a.out else diff --git a/tests/Makefile.am b/tests/Makefile.am index 429f2f4..3be6ce0 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -7,9 +7,10 @@ SUBDIRS = annotations bugs empty fail gobject program repro . if BUILD_TESTS TESTS = \ - check.py common.py mk_to_db.py \ - tools.sh gobject.sh bugs.sh annotations.sh fail.sh empty.sh sanity.sh \ - program.sh + check.py common.py mk_to_db.py mkhtml2.py \ + tools.sh \ + annotations.sh bugs.sh empty.sh fail.sh gobject.sh program.sh + TESTS_ENVIRONMENT = \ BUILDDIR=$(abs_builddir) \ SRCDIR=$(abs_srcdir) \ @@ -18,8 +19,10 @@ TESTS_ENVIRONMENT = \ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ GLIB_PREFIX="$(glib_prefix)" + TEST_EXTENSIONS = .py PY_LOG_COMPILER = $(PYTHON) + endif EXTRA_DIST = gtkdoctest.sh $(TESTS) diff --git a/tests/Makefile.in b/tests/Makefile.in index e70de14..a28b57a 100644 --- a/tests/Makefile.in +++ b/tests/Makefile.in @@ -524,7 +524,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ @@ -538,9 +537,9 @@ top_srcdir = @top_srcdir@ # maybe move it to a subdir? SUBDIRS = annotations bugs empty fail gobject program repro . @BUILD_TESTS_TRUE@TESTS = \ -@BUILD_TESTS_TRUE@ check.py common.py mk_to_db.py \ -@BUILD_TESTS_TRUE@ tools.sh gobject.sh bugs.sh annotations.sh fail.sh empty.sh sanity.sh \ -@BUILD_TESTS_TRUE@ program.sh +@BUILD_TESTS_TRUE@ check.py common.py mk_to_db.py mkhtml2.py \ +@BUILD_TESTS_TRUE@ tools.sh \ +@BUILD_TESTS_TRUE@ annotations.sh bugs.sh empty.sh fail.sh gobject.sh program.sh @BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \ @BUILD_TESTS_TRUE@ BUILDDIR=$(abs_builddir) \ @@ -843,9 +842,9 @@ tools.sh.log: tools.sh --log-file $$b.log --trs-file $$b.trs \ $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ "$$tst" $(AM_TESTS_FD_REDIRECT) -gobject.sh.log: gobject.sh - @p='gobject.sh'; \ - b='gobject.sh'; \ +annotations.sh.log: annotations.sh + @p='annotations.sh'; \ + b='annotations.sh'; \ $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \ --log-file $$b.log --trs-file $$b.trs \ $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ @@ -857,9 +856,9 @@ bugs.sh.log: bugs.sh --log-file $$b.log --trs-file $$b.trs \ $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ "$$tst" $(AM_TESTS_FD_REDIRECT) -annotations.sh.log: annotations.sh - @p='annotations.sh'; \ - b='annotations.sh'; \ +empty.sh.log: empty.sh + @p='empty.sh'; \ + b='empty.sh'; \ $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \ --log-file $$b.log --trs-file $$b.trs \ $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ @@ -871,16 +870,9 @@ fail.sh.log: fail.sh --log-file $$b.log --trs-file $$b.trs \ $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ "$$tst" $(AM_TESTS_FD_REDIRECT) -empty.sh.log: empty.sh - @p='empty.sh'; \ - b='empty.sh'; \ - $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \ - --log-file $$b.log --trs-file $$b.trs \ - $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ - "$$tst" $(AM_TESTS_FD_REDIRECT) -sanity.sh.log: sanity.sh - @p='sanity.sh'; \ - b='sanity.sh'; \ +gobject.sh.log: gobject.sh + @p='gobject.sh'; \ + b='gobject.sh'; \ $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \ --log-file $$b.log --trs-file $$b.trs \ $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ diff --git a/tests/annotations.sh b/tests/annotations.sh index c2cdc48..1b9c724 100755 --- a/tests/annotations.sh +++ b/tests/annotations.sh @@ -1,4 +1,6 @@ #!/bin/sh -gtkdoctest.sh annotations +set -e +gtkdoctest.sh annotations +sanity.sh annotations diff --git a/tests/annotations/Makefile.in b/tests/annotations/Makefile.in index 2d9c96f..80aa81b 100644 --- a/tests/annotations/Makefile.in +++ b/tests/annotations/Makefile.in @@ -322,7 +322,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/annotations/docs/Makefile.am b/tests/annotations/docs/Makefile.am index 7f8a752..08e6d4b 100644 --- a/tests/annotations/docs/Makefile.am +++ b/tests/annotations/docs/Makefile.am @@ -69,8 +69,7 @@ CLEANFILES += \ if BUILD_TESTS TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ - PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ - PERL5LIB=$(abs_top_builddir):$(PERL5LIB) + PATH=$(abs_top_builddir):$(srcdir):$(PATH) endif -include $(top_srcdir)/git.mk diff --git a/tests/annotations/docs/Makefile.in b/tests/annotations/docs/Makefile.in index 65e370b..e09885f 100644 --- a/tests/annotations/docs/Makefile.in +++ b/tests/annotations/docs/Makefile.in @@ -269,7 +269,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ @@ -388,8 +387,7 @@ GITIGNOREFILES = \ @BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \ @BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ -@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ -@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB) +@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) all: all-am diff --git a/tests/annotations/src/Makefile.in b/tests/annotations/src/Makefile.in index 1103d55..5b2fa3d 100644 --- a/tests/annotations/src/Makefile.in +++ b/tests/annotations/src/Makefile.in @@ -314,7 +314,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/bugs.sh b/tests/bugs.sh index 6cfef4c..3b49af5 100755 --- a/tests/bugs.sh +++ b/tests/bugs.sh @@ -1,4 +1,6 @@ #!/bin/sh -gtkdoctest.sh bugs +set -e +gtkdoctest.sh bugs +sanity.sh bugs diff --git a/tests/bugs/Makefile.in b/tests/bugs/Makefile.in index b640c3d..55f1463 100644 --- a/tests/bugs/Makefile.in +++ b/tests/bugs/Makefile.in @@ -322,7 +322,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/bugs/docs/Makefile.am b/tests/bugs/docs/Makefile.am index 97c4702..24052f7 100644 --- a/tests/bugs/docs/Makefile.am +++ b/tests/bugs/docs/Makefile.am @@ -71,8 +71,7 @@ CLEANFILES += \ if BUILD_TESTS TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ - PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ - PERL5LIB=$(abs_top_builddir):$(PERL5LIB) + PATH=$(abs_top_builddir):$(srcdir):$(PATH) endif -include $(top_srcdir)/git.mk diff --git a/tests/bugs/docs/Makefile.in b/tests/bugs/docs/Makefile.in index 2121504..e8285b2 100644 --- a/tests/bugs/docs/Makefile.in +++ b/tests/bugs/docs/Makefile.in @@ -269,7 +269,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ @@ -390,8 +389,7 @@ GITIGNOREFILES = \ @BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \ @BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ -@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ -@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB) +@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) all: all-am diff --git a/tests/bugs/src/Makefile.in b/tests/bugs/src/Makefile.in index 2370a27..7dc4573 100644 --- a/tests/bugs/src/Makefile.in +++ b/tests/bugs/src/Makefile.in @@ -314,7 +314,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/empty.sh b/tests/empty.sh index b4e824a..c929fff 100755 --- a/tests/empty.sh +++ b/tests/empty.sh @@ -1,9 +1,11 @@ #!/bin/sh +set -e + if ! grep -q ^GtkDocTestIf$ empty/docs/tester-sections.txt; then echo "Test for bug https://bugzilla.gnome.org/show_bug.cgi?id=705633 has failed." exit 1 fi gtkdoctest.sh empty - +sanity.sh empty diff --git a/tests/empty/Makefile.in b/tests/empty/Makefile.in index d93da81..83e9e11 100644 --- a/tests/empty/Makefile.in +++ b/tests/empty/Makefile.in @@ -322,7 +322,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/empty/docs/Makefile.am b/tests/empty/docs/Makefile.am index 4733cb3..600c3ea 100644 --- a/tests/empty/docs/Makefile.am +++ b/tests/empty/docs/Makefile.am @@ -76,8 +76,7 @@ CLEANFILES += \ if BUILD_TESTS TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ - PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ - PERL5LIB=$(abs_top_builddir):$(PERL5LIB) + PATH=$(abs_top_builddir):$(srcdir):$(PATH) endif CLEANFILES += \ diff --git a/tests/empty/docs/Makefile.in b/tests/empty/docs/Makefile.in index 7055681..ce00c3e 100644 --- a/tests/empty/docs/Makefile.in +++ b/tests/empty/docs/Makefile.in @@ -269,7 +269,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ @@ -395,8 +394,7 @@ GITIGNOREFILES = \ @BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \ @BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ -@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ -@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB) +@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) all: all-am diff --git a/tests/empty/docs/tester-docs.xml b/tests/empty/docs/tester-docs.xml index 6531a77..14286af 100644 --- a/tests/empty/docs/tester-docs.xml +++ b/tests/empty/docs/tester-docs.xml @@ -6,7 +6,7 @@ %gtkdocentities; ]> - + &package_name; Reference Manual @@ -18,8 +18,7 @@ [Insert title here] - - + Object Hierarchy diff --git a/tests/empty/src/Makefile.in b/tests/empty/src/Makefile.in index a65836a..78dfa10 100644 --- a/tests/empty/src/Makefile.in +++ b/tests/empty/src/Makefile.in @@ -314,7 +314,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/fail/Makefile.in b/tests/fail/Makefile.in index b6e7ad0..83219e4 100644 --- a/tests/fail/Makefile.in +++ b/tests/fail/Makefile.in @@ -322,7 +322,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/fail/docs/Makefile.am b/tests/fail/docs/Makefile.am index 8210a80..27222d4 100644 --- a/tests/fail/docs/Makefile.am +++ b/tests/fail/docs/Makefile.am @@ -69,8 +69,7 @@ CLEANFILES += \ if BUILD_TESTS TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ - PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ - PERL5LIB=$(abs_top_builddir):$(PERL5LIB) + PATH=$(abs_top_builddir):$(srcdir):$(PATH) endif -include $(top_srcdir)/git.mk diff --git a/tests/fail/docs/Makefile.in b/tests/fail/docs/Makefile.in index 67c5fa5..f5b75db 100644 --- a/tests/fail/docs/Makefile.in +++ b/tests/fail/docs/Makefile.in @@ -269,7 +269,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ @@ -388,8 +387,7 @@ GITIGNOREFILES = \ @BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \ @BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ -@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ -@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB) +@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) all: all-am diff --git a/tests/fail/src/Makefile.in b/tests/fail/src/Makefile.in index ddf1f5d..cc223cc 100644 --- a/tests/fail/src/Makefile.in +++ b/tests/fail/src/Makefile.in @@ -314,7 +314,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/gobject.sh b/tests/gobject.sh index 2983140..97cf356 100755 --- a/tests/gobject.sh +++ b/tests/gobject.sh @@ -1,4 +1,6 @@ #!/bin/sh -gtkdoctest.sh gobject +set -e +gtkdoctest.sh gobject +sanity.sh gobject diff --git a/tests/gobject/Makefile.in b/tests/gobject/Makefile.in index 4bde973..d0eca7a 100644 --- a/tests/gobject/Makefile.in +++ b/tests/gobject/Makefile.in @@ -322,7 +322,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/gobject/docs/Makefile.am b/tests/gobject/docs/Makefile.am index c5b6bd0..45a5b46 100644 --- a/tests/gobject/docs/Makefile.am +++ b/tests/gobject/docs/Makefile.am @@ -74,8 +74,7 @@ CLEANFILES += \ if BUILD_TESTS TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ - PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ - PERL5LIB=$(abs_top_builddir):$(PERL5LIB) + PATH=$(abs_top_builddir):$(srcdir):$(PATH) endif -include $(top_srcdir)/git.mk diff --git a/tests/gobject/docs/Makefile.in b/tests/gobject/docs/Makefile.in index 0bb78f4..07a9512 100644 --- a/tests/gobject/docs/Makefile.in +++ b/tests/gobject/docs/Makefile.in @@ -269,7 +269,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ @@ -394,8 +393,7 @@ GITIGNOREFILES = \ @BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \ @BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ -@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ -@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB) +@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) all: all-am diff --git a/tests/gobject/docs/tester-docs.xml b/tests/gobject/docs/tester-docs.xml index 05117ef..cb78ca8 100644 --- a/tests/gobject/docs/tester-docs.xml +++ b/tests/gobject/docs/tester-docs.xml @@ -8,7 +8,7 @@ ]> - &package_name; Reference Manual + &package_name; Reference Manual The gtk-doc team. @@ -36,7 +36,7 @@ - + Overview @@ -87,7 +87,7 @@ Index of new API in 0.5 - + Glossary A @@ -113,7 +113,7 @@ - + diff --git a/tests/gobject/src/Makefile.in b/tests/gobject/src/Makefile.in index cac37ca..b5b96e5 100644 --- a/tests/gobject/src/Makefile.in +++ b/tests/gobject/src/Makefile.in @@ -316,7 +316,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/gobject/src/giface.c b/tests/gobject/src/giface.c index 10625ce..5378a80 100644 --- a/tests/gobject/src/giface.c +++ b/tests/gobject/src/giface.c @@ -17,6 +17,8 @@ * * Just incase you wonder, special caracters can be escaped with a \ like in \% * or \# or even \@. + * + * We also support verbatim spans - lets test escaping of a `` block. */ /** * SECTION:iface2 diff --git a/tests/gobject/src/gobject.c b/tests/gobject/src/gobject.c index 21fc8f8..f4a783c 100644 --- a/tests/gobject/src/gobject.c +++ b/tests/gobject/src/gobject.c @@ -68,9 +68,8 @@ * * This is a section with a heading without a trailing hash mark. * - * > Do not confuse the GtkUIManager UI Definitions described here with - * > the similarly named GtkBuilder UI - * > Definitions. + * > This is a bloclquote with a link to + * > GtkdocObject2. * * > Single line quote * diff --git a/tests/mk_to_db.py b/tests/mk_to_db.py index 8cc5978..133509a 100755 --- a/tests/mk_to_db.py +++ b/tests/mk_to_db.py @@ -210,6 +210,12 @@ accessed via the following functions. output = md_to_db.MarkDownParse(input_, "") self.assertEqual(expected, output) + def test_verbatim(self): + input_ = "a `` element" + expected = 'a <child> element\n' + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(expected, output) + def test_code(self): input_ = """\ |[ diff --git a/tests/mkhtml2.py b/tests/mkhtml2.py new file mode 100755 index 0000000..c65df80 --- /dev/null +++ b/tests/mkhtml2.py @@ -0,0 +1,65 @@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2018 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import logging +import unittest + +from lxml import etree + +from gtkdoc import mkhtml2 + + +class TestChunking(unittest.TestCase): + + def setUp(self): + logging.basicConfig( + level=logging.INFO, + format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s') + + def test_chunk_only_root_gives_single_chunk(self): + root = etree.XML('') + files = mkhtml2.chunk(root, 'test') + self.assertEqual('book', files.name) + self.assertEqual(0, len(files.descendants)) + + def test_chunk_single_chapter_gives_two_chunks(self): + root = etree.XML('') + files = mkhtml2.chunk(root, 'test') + descendants = [f for f in files.descendants if f.anchor is None] + logging.info('descendants : %s', str(descendants)) + self.assertEqual(1, len(descendants)) + + def test_chunk_first_sect1_is_inlined(self): + root = etree.XML('') + files = mkhtml2.chunk(root, 'test') + descendants = [f for f in files.descendants if f.anchor is None] + logging.info('descendants : %s', str(descendants)) + self.assertEqual(1, len(descendants)) + + def test_chunk_second_sect1_is_not_inlined(self): + root = etree.XML('') + files = mkhtml2.chunk(root, 'test') + descendants = [f for f in files.descendants if f.anchor is None] + logging.info('descendants : %s', str(descendants)) + self.assertEqual(2, len(descendants)) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/program.sh b/tests/program.sh index eb5d511..4f44eae 100755 --- a/tests/program.sh +++ b/tests/program.sh @@ -1,4 +1,6 @@ #!/bin/sh -gtkdoctest.sh program +set -e +gtkdoctest.sh program +sanity.sh program diff --git a/tests/program/Makefile.in b/tests/program/Makefile.in index 996a8ec..156c564 100644 --- a/tests/program/Makefile.in +++ b/tests/program/Makefile.in @@ -322,7 +322,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/program/docs/Makefile.am b/tests/program/docs/Makefile.am index 2bbb4d2..fdcd2b5 100644 --- a/tests/program/docs/Makefile.am +++ b/tests/program/docs/Makefile.am @@ -70,8 +70,7 @@ CLEANFILES += \ if BUILD_TESTS TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ - PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ - PERL5LIB=$(abs_top_builddir):$(PERL5LIB) + PATH=$(abs_top_builddir):$(srcdir):$(PATH) endif -include $(top_srcdir)/git.mk diff --git a/tests/program/docs/Makefile.in b/tests/program/docs/Makefile.in index dcae16b..c7c886d 100644 --- a/tests/program/docs/Makefile.in +++ b/tests/program/docs/Makefile.in @@ -269,7 +269,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ @@ -389,8 +388,7 @@ GITIGNOREFILES = \ @BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \ @BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ -@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ -@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB) +@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) all: all-am diff --git a/tests/program/src/Makefile.in b/tests/program/src/Makefile.in index f5b8a40..b43cb85 100644 --- a/tests/program/src/Makefile.in +++ b/tests/program/src/Makefile.in @@ -313,7 +313,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/repro/Makefile.in b/tests/repro/Makefile.in index 46153a0..73e106e 100644 --- a/tests/repro/Makefile.in +++ b/tests/repro/Makefile.in @@ -322,7 +322,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/repro/docs/Makefile.am b/tests/repro/docs/Makefile.am index e8a17fc..5480011 100644 --- a/tests/repro/docs/Makefile.am +++ b/tests/repro/docs/Makefile.am @@ -69,8 +69,7 @@ CLEANFILES += \ if BUILD_TESTS TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ - PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ - PERL5LIB=$(abs_top_builddir):$(PERL5LIB) + PATH=$(abs_top_builddir):$(srcdir):$(PATH) endif CLEANFILES += \ diff --git a/tests/repro/docs/Makefile.in b/tests/repro/docs/Makefile.in index cda34b7..e43f646 100644 --- a/tests/repro/docs/Makefile.in +++ b/tests/repro/docs/Makefile.in @@ -269,7 +269,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ @@ -387,8 +386,7 @@ GITIGNOREFILES = \ @BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \ @BUILD_TESTS_TRUE@ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ -@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ -@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB) +@BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) all: all-am diff --git a/tests/repro/src/Makefile.in b/tests/repro/src/Makefile.in index c4e2492..f403fb5 100644 --- a/tests/repro/src/Makefile.in +++ b/tests/repro/src/Makefile.in @@ -314,7 +314,6 @@ program_transform_name = @program_transform_name@ psdir = @psdir@ pyexecdir = @pyexecdir@ pythondir = @pythondir@ -runstatedir = @runstatedir@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ srcdir = @srcdir@ diff --git a/tests/sanity.sh b/tests/sanity.sh deleted file mode 100755 index 5a79f18..0000000 --- a/tests/sanity.sh +++ /dev/null @@ -1,154 +0,0 @@ -#!/bin/sh - -dir=$BUILDDIR -#`dirname $0` -suite="sanity" - -failed=0 -tested=0 - -echo "Running suite(s): gtk-doc-$suite"; - -# check the presence and non-emptyness of certain files -nok=0 -for path in $dir/*/docs/html; do - if test ! -s $path/index.html ; then - echo 1>&2 "no or empty $path/index.html" - nok=`expr $nok + 1`; break; - fi - if test ! -s $path/home.png ; then - echo 1>&2 "no or empty $path/home.png" - nok=`expr $nok + 1`; break; - fi - file=`echo $path/*.devhelp2` - if test ! -s $file ; then - echo 1>&2 "no or empty $file" - nok=`expr $nok + 1`; break; - fi -done -if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi -tested=`expr $tested + 1` - -# TODO: if we have pdf support check for ./tests/*/docs/tester.pdf -nok=0 -for path in $dir/*/docs; do - if test ! -s $path/tester.pdf ; then - if test -s $path/gtkdoc-mkpdf.log; then - if ! grep >/dev/null 2>&1 "must be installed to use gtkdoc-mkpdf" $path/gtkdoc-mkpdf.log; then - echo 1>&2 "no or empty $path/tester.pdf" - nok=`expr $nok + 1`; break; - fi - fi - fi -done -if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi -tested=`expr $tested + 1` - -# check validity of generated xml files -nok=0 -for file in $dir/*/docs/xml/*.xml; do - xmllint --noout --noent $file - if test $? != 0 ; then - echo 1>&2 "xml validity check failed for $file" - nok=`expr $nok + 1`; - fi -done -if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi -tested=`expr $tested + 1` - - -# check validity of generated sgml files -nok=0 -for file in $dir/*/docs/xml/*.sgml; do - xmllint --noout --noent $file - if test $? != 0 ; then - echo 1>&2 "sgml validity check failed for $file" - nok=`expr $nok + 1`; - fi -done -if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi -tested=`expr $tested + 1` - -# check validity of devhelp2 files -nok=0 -for file in $dir/*/docs/html/*.devhelp2; do - xmllint --noout --nonet --schema $ABS_TOP_SRCDIR/devhelp2.xsd $file - if test $? != 0 ; then - echo 1>&2 "devhelp2 xml validity check failed for $file" - nok=`expr $nok + 1`; - fi -done -if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi -tested=`expr $tested + 1` - -# check that log files have only one line (the command) -# discard references to launchapd bugs -nok=0 -DISCARD_PATTERN='Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/[0-9]* . For now run: -gunzip .*.gz - -' -for file in $dir/*/docs/gtkdoc-*.log; do - # skip this in verbose mode as we'll have more text - if test "x${V}" = "x1"; then - continue - fi - - expected_lines="1" - # adjust for known files - if test $file = "$dir/fail/docs/gtkdoc-mkdb.log"; then - expected_lines="16" - fi - if test $file = "$dir/bugs/docs/gtkdoc-mkdb.log"; then - expected_lines="2" - fi - if test $file = "$dir/gobject/docs/gtkdoc-fixxref.log"; then - expected_lines="2" - fi - case $file in - *gtkdoc-fixxref.log) - # if there is no /usr/share/gtk-doc/html/gobject we should skip fixxref logs - if test ! -d "$GLIB_PREFIX/share/gtk-doc/html/gobject"; then - continue - fi - ;; - esac - - lines=`grep -v -x -G -e "$DISCARD_PATTERN" $file | wc -l | cut -d' ' -f1` - if test $lines -gt $expected_lines; then - echo 1>&2 "expected no more than $expected_lines log line in $file, but got $lines" - nok=`expr $nok + 1`; - fi -done -if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi -tested=`expr $tested + 1` - -# check stability of generated xml/html -nok=0 -for path in $dir/*/docs*; do - if test -d $path/xml.ref; then - diff -u $path/xml.ref $path/xml - if test $? = 1 ; then - echo 1>&2 "difference in generated xml for $path" - nok=`expr $nok + 1`; - fi - fi - if test -d $path/html.ref; then - diff -u $path/html.ref $path/html - if test $? = 1 ; then - echo 1>&2 "difference in generated html for $path" - nok=`expr $nok + 1`; - fi - fi -done -if test $nok -gt 0 ; then failed=`expr $failed + 1`; fi -tested=`expr $tested + 1` - - -# summary -successes=`expr $tested - $failed` -rate=`expr 100 \* $successes / $tested`; -echo "$rate %: Checks $tested, Failures: $failed" - -test $failed = 0 -exit $? diff --git a/tests/tools.sh b/tests/tools.sh index 6aebe94..e8690ec 100755 --- a/tests/tools.sh +++ b/tests/tools.sh @@ -28,10 +28,9 @@ done # test python scripts # TODO: also test the module files -# TODO: test python 2 and 3 (python3 -mcompileall gtkdoc/*.py) -for file in gtkdoc-check gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase gtkdoc-scangobj; do +for file in gtkdoc-check gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkhtml2 gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase gtkdoc-scangobj; do fullfile=`which $file` - /usr/bin/python -m py_compile $fullfile + /usr/bin/python3 -m py_compile $fullfile if test $? != 0 ; then failed=`expr $failed + 1`; fi tested=`expr $tested + 1` done diff --git a/tests/tools.sh.in b/tests/tools.sh.in index 4d301d0..343844a 100644 --- a/tests/tools.sh.in +++ b/tests/tools.sh.in @@ -28,8 +28,7 @@ done # test python scripts # TODO: also test the module files -# TODO: test python 2 and 3 (python3 -mcompileall gtkdoc/*.py) -for file in gtkdoc-check gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase gtkdoc-scangobj; do +for file in gtkdoc-check gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkhtml2 gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase gtkdoc-scangobj; do fullfile=`which $file` @PYTHON@ -m py_compile $fullfile if test $? != 0 ; then failed=`expr $failed + 1`; fi -- 2.7.4