From d7bc53cd38995524315ca5c4a63baca4a0abeb28 Mon Sep 17 00:00:00 2001 From: DongHun Kwak Date: Fri, 29 Sep 2017 11:05:41 +0900 Subject: [PATCH] Imported Upstream version 1.26 Change-Id: I0cd79e3d1a22af483b866f361bb2046f1a08b14b Signed-off-by: DongHun Kwak --- MAINTAINERS | 4 +- Makefile.am | 79 +- Makefile.in | 160 +- NEWS | 78 +- README | 36 +- TODO | 15 +- cmake/Makefile.am | 2 + cmake/Makefile.in | 4 +- configure | 147 +- configure.ac | 47 +- db2man/README | 14 - db2man/docbook-to-man | 178 - db2man/docbook-to-man.ts | 2019 ------ gtk-doc.cat.in | 6 - gtk-doc.dcl | 106 - gtk-doc.doap | 20 +- gtk-doc.dsl | 464 -- gtk-doc.dsl.in | 464 -- gtk-doc.flat.make | 115 +- gtk-doc.make | 115 +- gtk-doc.notmpl-flat.make | 304 - gtk-doc.notmpl.make | 304 - gtk-doc.spec | 93 - gtk-doc.spec.in | 93 - gtkdoc-check.in | 168 +- gtkdoc-common.pl | 552 -- gtkdoc-common.pl.in | 552 -- gtkdoc-depscan.in | 24 +- gtkdoc-fixxref.in | 616 +- gtkdoc-mkdb.in | 6282 +------------------ gtkdoc-mkhtml.in | 156 +- gtkdoc-mkman.in | 130 +- gtkdoc-mkpdf.in | 167 +- gtkdoc-mktmpl.in | 1274 ---- gtkdoc-rebase.in | 388 +- gtkdoc-scan.in | 1017 +-- gtkdoc-scangobj.in | 1384 +--- gtkdoc/__init__.py | 0 gtkdoc/check.py | 149 + gtkdoc/common.py | 577 ++ gtkdoc/config.py | 16 + gtkdoc/config.py.in | 16 + gtkdoc/fixxref.py | 447 ++ gtkdoc/md_to_db.py | 744 +++ gtkdoc/mkdb.py | 4728 ++++++++++++++ gtkdoc/mkhtml.py | 94 + gtkdoc/mkman.py | 62 + gtkdoc/mkpdf.py | 122 + gtkdoc/rebase.py | 254 + gtkdoc/scan.py | 892 +++ gtkdoc/scangobj.py | 1295 ++++ gtkdocize.in | 10 +- help/Makefile.in | 2 +- help/manual/C/index.docbook | 183 +- help/manual/Makefile.am | 2 +- help/manual/Makefile.in | 4 +- help/manual/bn_IN/index.docbook | 182 +- help/manual/cs/cs.po | 5427 ++++++++++++++++ help/manual/cs/cs.stamp | 0 help/manual/cs/fdl-appendix.xml | 615 ++ help/manual/cs/index.docbook | 1979 ++++++ help/manual/de/de.po | 1287 ++-- help/manual/de/fdl-appendix.xml | 8 +- help/manual/de/index.docbook | 499 +- help/manual/el/el.po | 677 +- help/manual/el/index.docbook | 241 +- help/manual/en_GB/index.docbook | 182 +- help/manual/es/es.po | 923 +-- help/manual/es/fdl-appendix.xml | 6 +- help/manual/es/index.docbook | 127 +- help/manual/fr/index.docbook | 178 +- help/manual/gl/index.docbook | 182 +- help/manual/gu/index.docbook | 187 +- help/manual/pt_BR/fdl-appendix.xml | 12 +- help/manual/pt_BR/index.docbook | 534 +- help/manual/pt_BR/pt_BR.po | 1232 ++-- help/manual/sl/index.docbook | 182 +- help/manual/sv/fdl-appendix.xml | 443 +- help/manual/sv/index.docbook | 2179 ++----- help/manual/sv/sv.po | 6172 +++++++++++++++--- help/manual/ta/index.docbook | 192 +- help/manual/te/index.docbook | 192 +- help/manual/zh_CN/index.docbook | 192 +- tests/Makefile.am | 15 +- tests/Makefile.in | 56 +- tests/annotations/Makefile.in | 2 +- tests/annotations/docs/Makefile.am | 6 +- tests/annotations/docs/Makefile.in | 71 +- tests/annotations/docs/tester-sections.txt | 2 + tests/annotations/src/Makefile.in | 2 +- tests/annotations/src/tester.c | 20 + tests/annotations/src/tester.h | 3 + tests/bugs/Makefile.in | 2 +- tests/bugs/docs/Makefile.am | 6 +- tests/bugs/docs/Makefile.in | 72 +- tests/bugs/docs/tester-sections.txt | 1 + tests/bugs/src/Makefile.in | 2 +- tests/bugs/src/tester.c | 40 +- tests/bugs/src/tester.h | 11 +- tests/check.py | 52 + tests/common.py | 70 + tests/empty/Makefile.in | 2 +- tests/empty/docs/Makefile.am | 6 +- tests/empty/docs/Makefile.in | 73 +- tests/empty/docs/tester-docs.xml | 4 + tests/empty/docs/tester-sections.txt | 1 + tests/empty/src/Makefile.in | 2 +- tests/empty/src/tester.h | 8 + tests/fail/Makefile.in | 2 +- tests/fail/docs/Makefile.am | 5 +- tests/fail/docs/Makefile.in | 70 +- tests/fail/src/Makefile.in | 2 +- tests/gobject/Makefile.in | 2 +- tests/gobject/docs/Makefile.am | 6 +- tests/gobject/docs/Makefile.in | 72 +- tests/gobject/src/Makefile.am | 1 - tests/gobject/src/Makefile.in | 2 +- tests/gobject/src/gobject.c | 3 + tests/{gtk-doc.notmpl.make => gtk-doc.make} | 53 +- tests/gtkdoc-common.t | 36 - tests/gtkdoc-fixxref.t | 30 - tests/gtkdoc-mkdb.t | 30 - tests/gtkdoc-rebase.t | 30 - tests/gtkdoc-scan.t | 30 - tests/mk_to_db.py | 261 + tests/program.sh | 4 + tests/program/Makefile.am | 11 + tests/program/Makefile.in | 643 ++ tests/program/docs/Makefile.am | 77 + tests/program/docs/Makefile.in | 749 +++ tests/program/docs/tester-docs.xml | 32 + tests/program/docs/tester-overrides.txt | 0 tests/program/docs/tester-sections.txt | 0 tests/program/src/Makefile.am | 10 + tests/program/src/Makefile.in | 604 ++ tests/program/src/test-program.c | 19 + tests/sanity.sh | 28 + tests/tools.sh | 22 +- tests/tools.sh.in | 22 +- 139 files changed, 31626 insertions(+), 22963 deletions(-) delete mode 100644 db2man/README delete mode 100755 db2man/docbook-to-man delete mode 100644 db2man/docbook-to-man.ts delete mode 100644 gtk-doc.cat.in delete mode 100755 gtk-doc.dcl delete mode 100644 gtk-doc.dsl delete mode 100644 gtk-doc.dsl.in delete mode 100644 gtk-doc.notmpl-flat.make delete mode 100644 gtk-doc.notmpl.make delete mode 100644 gtk-doc.spec delete mode 100644 gtk-doc.spec.in delete mode 100644 gtkdoc-common.pl delete mode 100644 gtkdoc-common.pl.in mode change 100644 => 100755 gtkdoc-mkpdf.in delete mode 100755 gtkdoc-mktmpl.in mode change 100644 => 100755 gtkdoc-rebase.in create mode 100644 gtkdoc/__init__.py create mode 100755 gtkdoc/check.py create mode 100644 gtkdoc/common.py create mode 100644 gtkdoc/config.py create mode 100644 gtkdoc/config.py.in create mode 100755 gtkdoc/fixxref.py create mode 100644 gtkdoc/md_to_db.py create mode 100644 gtkdoc/mkdb.py create mode 100644 gtkdoc/mkhtml.py create mode 100644 gtkdoc/mkman.py create mode 100755 gtkdoc/mkpdf.py create mode 100755 gtkdoc/rebase.py create mode 100644 gtkdoc/scan.py create mode 100644 gtkdoc/scangobj.py create mode 100644 help/manual/cs/cs.po create mode 100644 help/manual/cs/cs.stamp create mode 100644 help/manual/cs/fdl-appendix.xml create mode 100644 help/manual/cs/index.docbook create mode 100755 tests/check.py create mode 100755 tests/common.py rename tests/{gtk-doc.notmpl.make => gtk-doc.make} (81%) delete mode 100755 tests/gtkdoc-common.t delete mode 100755 tests/gtkdoc-fixxref.t delete mode 100755 tests/gtkdoc-mkdb.t delete mode 100755 tests/gtkdoc-rebase.t delete mode 100755 tests/gtkdoc-scan.t create mode 100755 tests/mk_to_db.py create mode 100755 tests/program.sh create mode 100644 tests/program/Makefile.am create mode 100644 tests/program/Makefile.in create mode 100644 tests/program/docs/Makefile.am create mode 100644 tests/program/docs/Makefile.in create mode 100644 tests/program/docs/tester-docs.xml create mode 100644 tests/program/docs/tester-overrides.txt create mode 100644 tests/program/docs/tester-sections.txt create mode 100644 tests/program/src/Makefile.am create mode 100644 tests/program/src/Makefile.in create mode 100644 tests/program/src/test-program.c diff --git a/MAINTAINERS b/MAINTAINERS index 1a07b97..fbc8f30 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1,4 +1,4 @@ -Stefan Kost +Stefan Sauer Email: ensonic@hora-obscura.de Userid: stefkost @@ -15,7 +15,7 @@ Email: mclasen@redhat.com Userid: matthiasc -Note that several people are contributing to gtk-doc, and some parts of it +Note that several people are contributing to gtk-doc, and some parts of it are technically maintained by other people. The people listed above are meant as contacts for administrative questions. Other questions are best directed to the mailing list gtk-doc-list@gnome.org. diff --git a/Makefile.am b/Makefile.am index 3fe249d..4d69bf1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -5,35 +5,25 @@ SUBDIRS = cmake help tests bin_SCRIPTS = \ gtkdoc-check \ + gtkdoc-depscan \ gtkdoc-fixxref \ gtkdoc-mkdb \ gtkdoc-mkhtml \ gtkdoc-mkman \ - gtkdoc-mkpdf \ - gtkdoc-mktmpl \ + gtkdoc-mkpdf \ gtkdoc-rebase \ gtkdoc-scan \ gtkdoc-scangobj \ gtkdocize -if HAVE_PYTHON -bin_SCRIPTS += \ - gtkdoc-depscan -endif - gtkdocdatadir = $(datadir)/gtk-doc/data gtkdocdata_DATA = \ - gtkdoc-common.pl \ - gtk-doc.dsl \ - gtk-doc.dcl \ gtk-doc.xsl \ version-greater-or-equal.xsl \ devhelp2.xsd \ devhelp2.xsl \ gtk-doc.make \ - gtk-doc.notmpl.make \ gtk-doc.flat.make \ - gtk-doc.notmpl-flat.make \ style/home.png \ style/left.png \ style/left-insensitive.png \ @@ -43,40 +33,45 @@ gtkdocdata_DATA = \ style/up-insensitive.png \ style/style.css +pylibdatadir = $(datadir)/gtk-doc/python/gtkdoc +pylibdata_DATA = \ + gtkdoc/__init__.py \ + gtkdoc/check.py \ + gtkdoc/common.py \ + gtkdoc/config.py \ + gtkdoc/fixxref.py \ + gtkdoc/md_to_db.py \ + gtkdoc/mkdb.py \ + gtkdoc/mkhtml.py \ + gtkdoc/mkman.py \ + gtkdoc/mkpdf.py \ + gtkdoc/rebase.py \ + gtkdoc/scan.py \ + gtkdoc/scangobj.py + pkgconfigdir = $(datadir)/pkgconfig pkgconfig_DATA = gtk-doc.pc aclocaldir = $(datadir)/aclocal aclocal_DATA = gtk-doc.m4 -sgmldir = $(datadir)/sgml/gtk-doc -sgml_DATA = gtk-doc.cat - gtk-doc.flat.make: gtk-doc.make @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ -gtk-doc.notmpl-flat.make: gtk-doc.notmpl.make - @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ - EXTRA_DIST = \ MAINTAINERS \ $(gtkdocdata_DATA) \ + $(pylibdata_DATA) \ gtk-doc.pc.in \ gtk-doc.m4 \ gtk-doc.doap \ - gtk-doc.spec.in \ - gtk-doc.spec \ gtk-doc-fo.xsl \ - gtk-doc.cat.in \ doc/README \ doc/authors.txt \ doc/gnome.txt \ doc/sections-file.txt \ doc/setting-up.txt \ doc/style-guide.txt \ - db2man/README \ - db2man/docbook-to-man \ - db2man/docbook-to-man.ts \ examples/README \ examples/Makefile.am \ tools/docpercentages.pl \ @@ -85,28 +80,43 @@ EXTRA_DIST = \ CLEANFILES = \ gtk-doc.flat.make \ - gtk-doc.notmpl-flat.make \ - gtkdoc-depscanc - + gtkdoc-checkc \ + gtkdoc-depscanc \ + gtkdoc-fixxrefc \ + gtkdoc-mkdbc \ + gtkdoc-mkhtmlc \ + gtkdoc-mkmanc \ + gtkdoc-mkpdfc \ + gtkdoc-rebasec \ + gtkdoc-scangobjc \ + gtkdoc/__init__.pyc \ + gtkdoc/check.pyc \ + gtkdoc/common.pyc \ + gtkdoc/config.pyc \ + gtkdoc/fixxref.pyc \ + gtkdoc/md_to_db.pyc \ + gtkdoc/mkdb.pyc \ + gtkdoc/mkhtml.pyc \ + gtkdoc/mkman.pyc \ + gtkdoc/mkpdf.pyc \ + gtkdoc/rebase.pyc \ + gtkdoc/scan.pyc \ + gtkdoc/scangobj.pyc + DISTCLEANFILES = \ - gtk-doc.cat \ gtkdoc-check \ - gtkdoc-common.pl \ gtkdoc-depscan \ - gtk-doc.dsl \ gtkdoc-fixxref \ gtkdocize \ gtkdoc-mkdb \ gtkdoc-mkhtml \ gtkdoc-mkman \ gtkdoc-mkpdf \ - gtkdoc-mktmpl \ gtk-doc.pc \ gtkdoc-rebase \ gtkdoc-scangobj \ gtkdoc-scan \ - gtk-doc.spec - + gtkdoc/config.py MAINTAINERCLEANFILES = \ $(GITIGNORE_MAINTAINERCLEANFILES_TOPLEVEL) \ @@ -116,7 +126,8 @@ MAINTAINERCLEANFILES = \ RELNOTES.txt \ ChangeLog-?.?? \ gtk-doc-*.tar.xz \ - build-aux + build-aux \ + __pycache__ gtkdoc/__pycache__ tests/__pycache__ -include $(top_srcdir)/git.mk diff --git a/Makefile.in b/Makefile.in index 4eb8d5e..7261979 100644 --- a/Makefile.in +++ b/Makefile.in @@ -79,20 +79,15 @@ PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ -@HAVE_PYTHON_TRUE@am__append_1 = \ -@HAVE_PYTHON_TRUE@ gtkdoc-depscan - subdir = . DIST_COMMON = INSTALL NEWS README AUTHORS ChangeLog \ $(srcdir)/Makefile.in $(srcdir)/Makefile.am \ $(top_srcdir)/configure $(am__configure_deps) \ - $(srcdir)/gtk-doc.pc.in $(srcdir)/gtk-doc.dsl.in \ - $(srcdir)/gtk-doc.spec.in $(srcdir)/gtk-doc.cat.in \ - $(srcdir)/gtkdoc-common.pl.in $(srcdir)/gtkdoc-check.in \ - $(srcdir)/gtkdoc-depscan.in $(srcdir)/gtkdoc-fixxref.in \ - $(srcdir)/gtkdoc-mkdb.in $(srcdir)/gtkdoc-mkhtml.in \ - $(srcdir)/gtkdoc-mkman.in $(srcdir)/gtkdoc-mkpdf.in \ - $(srcdir)/gtkdoc-mktmpl.in $(srcdir)/gtkdoc-rebase.in \ + $(srcdir)/gtk-doc.pc.in $(top_srcdir)/gtkdoc/config.py.in \ + $(srcdir)/gtkdoc-check.in $(srcdir)/gtkdoc-depscan.in \ + $(srcdir)/gtkdoc-fixxref.in $(srcdir)/gtkdoc-mkdb.in \ + $(srcdir)/gtkdoc-mkhtml.in $(srcdir)/gtkdoc-mkman.in \ + $(srcdir)/gtkdoc-mkpdf.in $(srcdir)/gtkdoc-rebase.in \ $(srcdir)/gtkdoc-scan.in $(srcdir)/gtkdoc-scangobj.in \ $(srcdir)/gtkdocize.in COPYING TODO build-aux/compile \ build-aux/config.guess build-aux/config.sub build-aux/depcomp \ @@ -114,11 +109,10 @@ am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ am__CONFIG_DISTCLEAN_FILES = config.status config.cache config.log \ configure.lineno config.status.lineno mkinstalldirs = $(install_sh) -d -CONFIG_CLEAN_FILES = gtk-doc.pc gtk-doc.dsl gtk-doc.spec gtk-doc.cat \ - gtkdoc-common.pl gtkdoc-check gtkdoc-depscan gtkdoc-fixxref \ - gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkman gtkdoc-mkpdf \ - gtkdoc-mktmpl gtkdoc-rebase gtkdoc-scan gtkdoc-scangobj \ - gtkdocize +CONFIG_CLEAN_FILES = gtk-doc.pc gtkdoc/config.py gtkdoc-check \ + gtkdoc-depscan gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml \ + gtkdoc-mkman gtkdoc-mkpdf gtkdoc-rebase gtkdoc-scan \ + gtkdoc-scangobj gtkdocize CONFIG_CLEAN_VPATH_FILES = am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; am__vpath_adj = case $$p in \ @@ -149,7 +143,7 @@ am__uninstall_files_from_dir = { \ } am__installdirs = "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" \ "$(DESTDIR)$(gtkdocdatadir)" "$(DESTDIR)$(pkgconfigdir)" \ - "$(DESTDIR)$(sgmldir)" + "$(DESTDIR)$(pylibdatadir)" SCRIPTS = $(bin_SCRIPTS) AM_V_P = $(am__v_P_@AM_V@) am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) @@ -179,7 +173,7 @@ am__can_run_installinfo = \ *) (install-info --version) >/dev/null 2>&1;; \ esac DATA = $(aclocal_DATA) $(gtkdocdata_DATA) $(pkgconfig_DATA) \ - $(sgml_DATA) + $(pylibdata_DATA) RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \ distclean-recursive maintainer-clean-recursive am__recursive_targets = \ @@ -317,12 +311,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ @@ -401,22 +395,27 @@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS} SUBDIRS = cmake help tests -bin_SCRIPTS = gtkdoc-check gtkdoc-fixxref gtkdoc-mkdb gtkdoc-mkhtml \ - gtkdoc-mkman gtkdoc-mkpdf gtkdoc-mktmpl gtkdoc-rebase \ - gtkdoc-scan gtkdoc-scangobj gtkdocize $(am__append_1) +bin_SCRIPTS = \ + gtkdoc-check \ + gtkdoc-depscan \ + gtkdoc-fixxref \ + gtkdoc-mkdb \ + gtkdoc-mkhtml \ + gtkdoc-mkman \ + gtkdoc-mkpdf \ + gtkdoc-rebase \ + gtkdoc-scan \ + gtkdoc-scangobj \ + gtkdocize + gtkdocdatadir = $(datadir)/gtk-doc/data gtkdocdata_DATA = \ - gtkdoc-common.pl \ - gtk-doc.dsl \ - gtk-doc.dcl \ gtk-doc.xsl \ version-greater-or-equal.xsl \ devhelp2.xsd \ devhelp2.xsl \ gtk-doc.make \ - gtk-doc.notmpl.make \ gtk-doc.flat.make \ - gtk-doc.notmpl-flat.make \ style/home.png \ style/left.png \ style/left-insensitive.png \ @@ -426,31 +425,40 @@ gtkdocdata_DATA = \ style/up-insensitive.png \ style/style.css +pylibdatadir = $(datadir)/gtk-doc/python/gtkdoc +pylibdata_DATA = \ + gtkdoc/__init__.py \ + gtkdoc/check.py \ + gtkdoc/common.py \ + gtkdoc/config.py \ + gtkdoc/fixxref.py \ + gtkdoc/md_to_db.py \ + gtkdoc/mkdb.py \ + gtkdoc/mkhtml.py \ + gtkdoc/mkman.py \ + gtkdoc/mkpdf.py \ + gtkdoc/rebase.py \ + gtkdoc/scan.py \ + gtkdoc/scangobj.py + pkgconfigdir = $(datadir)/pkgconfig pkgconfig_DATA = gtk-doc.pc aclocaldir = $(datadir)/aclocal aclocal_DATA = gtk-doc.m4 -sgmldir = $(datadir)/sgml/gtk-doc -sgml_DATA = gtk-doc.cat EXTRA_DIST = \ MAINTAINERS \ $(gtkdocdata_DATA) \ + $(pylibdata_DATA) \ gtk-doc.pc.in \ gtk-doc.m4 \ gtk-doc.doap \ - gtk-doc.spec.in \ - gtk-doc.spec \ gtk-doc-fo.xsl \ - gtk-doc.cat.in \ doc/README \ doc/authors.txt \ doc/gnome.txt \ doc/sections-file.txt \ doc/setting-up.txt \ doc/style-guide.txt \ - db2man/README \ - db2man/docbook-to-man \ - db2man/docbook-to-man.ts \ examples/README \ examples/Makefile.am \ tools/docpercentages.pl \ @@ -459,27 +467,43 @@ EXTRA_DIST = \ CLEANFILES = \ gtk-doc.flat.make \ - gtk-doc.notmpl-flat.make \ - gtkdoc-depscanc + gtkdoc-checkc \ + gtkdoc-depscanc \ + gtkdoc-fixxrefc \ + gtkdoc-mkdbc \ + gtkdoc-mkhtmlc \ + gtkdoc-mkmanc \ + gtkdoc-mkpdfc \ + gtkdoc-rebasec \ + gtkdoc-scangobjc \ + gtkdoc/__init__.pyc \ + gtkdoc/check.pyc \ + gtkdoc/common.pyc \ + gtkdoc/config.pyc \ + gtkdoc/fixxref.pyc \ + gtkdoc/md_to_db.pyc \ + gtkdoc/mkdb.pyc \ + gtkdoc/mkhtml.pyc \ + gtkdoc/mkman.pyc \ + gtkdoc/mkpdf.pyc \ + gtkdoc/rebase.pyc \ + gtkdoc/scan.pyc \ + gtkdoc/scangobj.pyc DISTCLEANFILES = \ - gtk-doc.cat \ gtkdoc-check \ - gtkdoc-common.pl \ gtkdoc-depscan \ - gtk-doc.dsl \ gtkdoc-fixxref \ gtkdocize \ gtkdoc-mkdb \ gtkdoc-mkhtml \ gtkdoc-mkman \ gtkdoc-mkpdf \ - gtkdoc-mktmpl \ gtk-doc.pc \ gtkdoc-rebase \ gtkdoc-scangobj \ gtkdoc-scan \ - gtk-doc.spec + gtkdoc/config.py MAINTAINERCLEANFILES = \ $(GITIGNORE_MAINTAINERCLEANFILES_TOPLEVEL) \ @@ -489,7 +513,8 @@ MAINTAINERCLEANFILES = \ RELNOTES.txt \ ChangeLog-?.?? \ gtk-doc-*.tar.xz \ - build-aux + build-aux \ + __pycache__ gtkdoc/__pycache__ tests/__pycache__ all: all-recursive @@ -530,13 +555,7 @@ $(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) $(am__aclocal_m4_deps): gtk-doc.pc: $(top_builddir)/config.status $(srcdir)/gtk-doc.pc.in cd $(top_builddir) && $(SHELL) ./config.status $@ -gtk-doc.dsl: $(top_builddir)/config.status $(srcdir)/gtk-doc.dsl.in - cd $(top_builddir) && $(SHELL) ./config.status $@ -gtk-doc.spec: $(top_builddir)/config.status $(srcdir)/gtk-doc.spec.in - cd $(top_builddir) && $(SHELL) ./config.status $@ -gtk-doc.cat: $(top_builddir)/config.status $(srcdir)/gtk-doc.cat.in - cd $(top_builddir) && $(SHELL) ./config.status $@ -gtkdoc-common.pl: $(top_builddir)/config.status $(srcdir)/gtkdoc-common.pl.in +gtkdoc/config.py: $(top_builddir)/config.status $(top_srcdir)/gtkdoc/config.py.in cd $(top_builddir) && $(SHELL) ./config.status $@ gtkdoc-check: $(top_builddir)/config.status $(srcdir)/gtkdoc-check.in cd $(top_builddir) && $(SHELL) ./config.status $@ @@ -552,8 +571,6 @@ gtkdoc-mkman: $(top_builddir)/config.status $(srcdir)/gtkdoc-mkman.in cd $(top_builddir) && $(SHELL) ./config.status $@ gtkdoc-mkpdf: $(top_builddir)/config.status $(srcdir)/gtkdoc-mkpdf.in cd $(top_builddir) && $(SHELL) ./config.status $@ -gtkdoc-mktmpl: $(top_builddir)/config.status $(srcdir)/gtkdoc-mktmpl.in - cd $(top_builddir) && $(SHELL) ./config.status $@ gtkdoc-rebase: $(top_builddir)/config.status $(srcdir)/gtkdoc-rebase.in cd $(top_builddir) && $(SHELL) ./config.status $@ gtkdoc-scan: $(top_builddir)/config.status $(srcdir)/gtkdoc-scan.in @@ -684,27 +701,27 @@ uninstall-pkgconfigDATA: @list='$(pkgconfig_DATA)'; test -n "$(pkgconfigdir)" || list=; \ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ dir='$(DESTDIR)$(pkgconfigdir)'; $(am__uninstall_files_from_dir) -install-sgmlDATA: $(sgml_DATA) +install-pylibdataDATA: $(pylibdata_DATA) @$(NORMAL_INSTALL) - @list='$(sgml_DATA)'; test -n "$(sgmldir)" || list=; \ + @list='$(pylibdata_DATA)'; test -n "$(pylibdatadir)" || list=; \ if test -n "$$list"; then \ - echo " $(MKDIR_P) '$(DESTDIR)$(sgmldir)'"; \ - $(MKDIR_P) "$(DESTDIR)$(sgmldir)" || exit 1; \ + echo " $(MKDIR_P) '$(DESTDIR)$(pylibdatadir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(pylibdatadir)" || exit 1; \ fi; \ for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ echo "$$d$$p"; \ done | $(am__base_list) | \ while read files; do \ - echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(sgmldir)'"; \ - $(INSTALL_DATA) $$files "$(DESTDIR)$(sgmldir)" || exit $$?; \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pylibdatadir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(pylibdatadir)" || exit $$?; \ done -uninstall-sgmlDATA: +uninstall-pylibdataDATA: @$(NORMAL_UNINSTALL) - @list='$(sgml_DATA)'; test -n "$(sgmldir)" || list=; \ + @list='$(pylibdata_DATA)'; test -n "$(pylibdatadir)" || list=; \ files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ - dir='$(DESTDIR)$(sgmldir)'; $(am__uninstall_files_from_dir) + dir='$(DESTDIR)$(pylibdatadir)'; $(am__uninstall_files_from_dir) # This directory's subdirectories are mostly independent; you can cd # into them and run 'make' without going through this Makefile. @@ -1013,7 +1030,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)$(sgmldir)"; do \ + for dir in "$(DESTDIR)$(bindir)" "$(DESTDIR)$(aclocaldir)" "$(DESTDIR)$(gtkdocdatadir)" "$(DESTDIR)$(pkgconfigdir)" "$(DESTDIR)$(pylibdatadir)"; do \ test -z "$$dir" || $(MKDIR_P) "$$dir"; \ done install: install-recursive @@ -1072,7 +1089,7 @@ info: info-recursive info-am: install-data-am: install-aclocalDATA install-gtkdocdataDATA \ - install-pkgconfigDATA install-sgmlDATA + install-pkgconfigDATA install-pylibdataDATA install-dvi: install-dvi-recursive @@ -1120,7 +1137,7 @@ ps-am: uninstall-am: uninstall-aclocalDATA uninstall-binSCRIPTS \ uninstall-gtkdocdataDATA uninstall-pkgconfigDATA \ - uninstall-sgmlDATA + uninstall-pylibdataDATA .MAKE: $(am__recursive_targets) install-am install-strip @@ -1137,21 +1154,18 @@ uninstall-am: uninstall-aclocalDATA uninstall-binSCRIPTS \ install-gtkdocdataDATA install-html install-html-am \ install-info install-info-am install-man install-pdf \ install-pdf-am install-pkgconfigDATA install-ps install-ps-am \ - install-sgmlDATA install-strip installcheck installcheck-am \ - installcheck-binSCRIPTS installdirs installdirs-am \ - maintainer-clean maintainer-clean-generic mostlyclean \ - mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ - tags tags-am uninstall uninstall-aclocalDATA uninstall-am \ - uninstall-binSCRIPTS uninstall-gtkdocdataDATA \ - uninstall-pkgconfigDATA uninstall-sgmlDATA + install-pylibdataDATA install-strip installcheck \ + installcheck-am installcheck-binSCRIPTS installdirs \ + installdirs-am maintainer-clean maintainer-clean-generic \ + mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \ + ps ps-am tags tags-am uninstall uninstall-aclocalDATA \ + uninstall-am uninstall-binSCRIPTS uninstall-gtkdocdataDATA \ + uninstall-pkgconfigDATA uninstall-pylibdataDATA gtk-doc.flat.make: gtk-doc.make @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ -gtk-doc.notmpl-flat.make: gtk-doc.notmpl.make - @$(SED) -e "s/EXTRA_DIST =/EXTRA_DIST +=/" $< >$@ - -include $(top_srcdir)/git.mk dist-hook: diff --git a/NEWS b/NEWS index a93adf0..44df039 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,55 @@ +GTK-Doc 1.26 (Aug 11 2017) +============== + +Remove tmpl support (gtkdoc-mktmpl). Port all tools from bash/perl to python. + + Changes + + o 773879 : –   scangobj: Do not generate unused parameters + o 780789 : Convert gtkdoc-scan from Perl to Python + o 752126 : Add support for inline program documentation + o 753052 : _() causes element a: validity error : ID idx already defined + o 758137 : GtkLabel and GtkShortcutsShortcut notes on escaping character entities don't render properly + o 764407 : Broken links to structs in function definitions + o 764543 : /usr/bin/gtkdoc-mkpdf always exits with an error + o 768675 : make check fails on master + o 769125 : gtkdoc-mkhtml/pdf fails on spaces in search path + o 769341 : gtkdoc-mkdb line 3966 triggers " Negative repeat count does nothing " warnings + o 771255 : " Symbol name not found at the start of comment block " warning with " attributes " annotation. + o 773151 : configure: Lower perl dependency to 5.16.0 + o 774168 : gobject introspection annotations and gtk-doc parser do not agree + o 774812 : Error messages from xsltproc are hidden by gtkdoc-mkhtml + o 778144 : Allow disabling introspection for ancillary property mechanisms + o 779566 : Replace shell executables with Python + + Contributors + + Anders Jonsson + Bernhard M. Wiedemann + Carlos Garcia Campos + Christian Kirbach + Daniel Mustieles + Emmanuele Bassi + Ernestas Kulik + HorimotoYasuhiro + Jussi Pakkanen + Kalev Lember + Marek Černocký + Mario Blättermann + Marius Vlad + Marvin Schmidt + Nirbheek Chauhan + Philip Withnall + Rafael Fontenelle + Sam Thursfield + Sebastian Rasmussen + Simon Josefsson + Stefan Sauer + Thomas Wood + Ting-Wei Lan + Tom Tryfonidis + Víctor Manuel Jáquez Leal + GTK-Doc 1.25 (Mar 21 2016) ============== @@ -195,7 +247,7 @@ GTK-Doc 1.20 (Feb 16 2014) o 706404 : Minor bug in gtkdoc-mkdb o 706438 : Empty lines added at the beginning and at the end of a programlisting o 707426 : master is broken in picking up flavour from configure.ac - o 707717 : Support " Deprecated: X.Y " + o 707717 : Support " Deprecated: X.Y " o 708268 : New *-insensitive.png files are not distributes o 710478 : gtkdoc-mkdb: Don't complain about annotations with hyphen o 711111 : gtkdoc-mkdb: sort entries in the glossary @@ -255,7 +307,7 @@ GTK-Doc 1.19 (Jun 05 2013) o 671960 : make dist fails without html/* o 672710 : Use new documentation infrastructure o 676685 : Allow to order functions without using $MODULE-sections.txt - o 685365 : (PATCH) Fix contents of warning message, should be " -sections.txt " not " -section.txt " + o 685365 : (PATCH) Fix contents of warning message, should be " -sections.txt " not " -section.txt " o 686148 : [patch] suggested parameters for gtkdoc-scangobj o 687685 : 'g_type_init' is deprecated o 688204 : undocumented enum values missing in indexes @@ -309,7 +361,7 @@ GTK-Doc 1.18 (Sep 14 2011) o gtk-doc does not generate old devhelp files any more. This cuts down doc generation time and works for devhelp >=0.11 (was released in 2005). o changes for out-of-source dir build caused breakage for projects using - DOC_SOURCE_DIR with a relative path (to builddir). It is recommended to use + DOC_SOURCE_DIR with a relative path (to builddir). It is recommended to use DOC_SOURCE_DIR=$(top_srcdir)/src/xxx. Changes @@ -452,7 +504,7 @@ GTK-Doc 1.14 (Mar 28 2010) o 512155 : gets confused by multiline typedef o 568711 : undocumented enum values are not reported o 590602 : secondly running gtkdoc-mkdb will generate DOCTYPE missing XML files - o 590625 : $(DOC_MODULE)-overrides.txt is required by " make dist " + o 590625 : $(DOC_MODULE)-overrides.txt is required by " make dist " o 591975 : Section_Id always embeds a trailing newline o 604885 : Fix the use of gtkdocize --flavour option o 604992 : gtkdoc-fixxref broken link warning is broken for functions @@ -472,7 +524,7 @@ GTK-Doc 1.14 (Mar 28 2010) o 609194 : sort interface implementers o 610255 : Self-test failure in git as of 2010-02-17: FAIL: gobject.sh o 610257 : Patch to make GTK-DOC notice functions/variables with 'signed' prototypes - o 611848 : gtk-doc produces invalid DocBook markup if the SECTION ends with a tag that cannot be nested inside < para > + o 611848 : gtk-doc produces invalid DocBook markup if the SECTION ends with a tag that cannot be nested inside < para > Contributors @@ -598,10 +650,10 @@ GTK-Doc 1.11 (Nov 16 2008) o 552822 : Add rules to create $(REPORT_FILES) o 553407 : Example Makefile.am uses obsolete INCLUDES instead of AM_... o 554718 : gtk-doc needs to allow versioned TARGET_DIR - o 554833 : Be more careful with " struct _ < struct_name > " + o 554833 : Be more careful with " struct _ < struct_name > " o 558082 : evince docs build fails with GTK_DISABLE_SINGLE_INCLUDES o 559281 : Correct check for existance of gtkdoc-rebase - + Contributors Behdad Esfahbod @@ -677,7 +729,7 @@ GTK-Doc 1.9 (Sep 30 2007) o 379466 : Improve C parser to handle TYPE\nVARIABLE in function pro... o 380824 : docs are truncated if line begins with '* returns ' o 383456 : ' make check ' test for 100% documentation - o 411739 : Gtk-doc fails to handle ' struct tm * function_name (); ' + o 411739 : Gtk-doc fails to handle ' struct tm * function_name (); ' o 415388 : Please clean -undocumented.txt files o 418027 : gtkdoc-mkdb does not handle #ifdef in enum {} o 419997 : parameter name trouble @@ -693,7 +745,7 @@ GTK-Doc 1.9 (Sep 30 2007) o 459725 : ' jhbuild build gtk-doc ' fails on make o 460127 : parsing nested union/structs confuses public/private state o 465365 : [PATCH] gtk-doc does not compile - o 466559 : [CSS] styling
; + o 466559 : [CSS] styling
; o 471014 : G_CONST_RETURN * G_CONST_RETURN * function not picked up o 477532 : function variables o 479913 : gtk-doc.notmpl.make is not distributed @@ -812,7 +864,7 @@ GTK-Doc 1.2 (Feb 16 2004) o Emit "Since:" information for signals and properties. o Added derived subclasses and interfaces to the widget hierarchies. o Added .cat SGML catalog file. - o Support properties on interfaces. + o Support properties on interfaces. o Added "--help" options to the scripts. @@ -848,15 +900,15 @@ GTK-Doc 1.0 (Jan 20 2003) GTK-Doc 0.10 (Nov 14 2002) ============ - o --output-format option to select whether SGML or XML is generated. + o --output-format option to select whether SGML or XML is generated. o Use openjade or jade when converting SGML to HTML. o Use xsltproc to convert XML to HTML, with a new look. o In XML mode, support XIncludes as an alternative to entities. - o In XML mode, create .devhelp files. + o In XML mode, create .devhelp files. o List interfaces in the object hierarchy. o Create docs for signals on interfaces. o Generate links between interface and their implementations and prerequisites. o Create docs for child and style properties. o Use blurbs for property documentation. - o Allow inline documentation for signals and properties. + o Allow inline documentation for signals and properties. diff --git a/README b/README index 51d35ea..6c89237 100644 --- a/README +++ b/README @@ -13,28 +13,22 @@ at Doxygen (http://www.doxygen.org/). However GTK-Doc has some special code to document the signals and properties of GTK+ widgets and GObject classes which other tools may not have. -GTK-Doc allows your documentation to be written in 2 ways: - a) Embedded inside the source code in specially-formatted comments. - or - b) Added to the 'template' files which gtk-doc outputs after scanning all - the header files and parsing the declarations (deprecated now). - -From these source code comments and template files GTK-Doc generates a Docbook -XML (or SGML) document, which is then transformed into HTML. +From your source code comments GTK-Doc generates a Docbook XML document, which +is then transformed into HTML and/or PDF. The generated HTML documentation can be browsed in an ordinary web browser or by using the special Devhelp API browser (see http://developer.imendio.com/wiki/Devhelp). -Please don't use template files in new projects. Support for for those will -be removed at some point in the future (together with gtkdoc-mktmpl). Please -also use DoxBook XML instead of DocBook SGML. +Please use DoxBook XML instead of DocBook SGML - support for the later will be +dropped. Requirements ============ -Perl v5 - the main scripts are in Perl. - http://www.perl.com/ +Python 2.7, 3.x - the secondary scripts are written in Python + http:///www.python.org +Python-six - for python 2,3 compatibility For XML output (recommended): @@ -48,22 +42,6 @@ libxslt & libxml2 >= 2.3.6. http://xmlsoft.org/ -For SGML output (not actively maintained any more): - -The DocBook SGML DTD. - http://www.oasis-open.org/docbook/ - -Jade v1.1 or OpenJade 1.3.1. - http://www.jclark.com/jade - http://sourceforge.net/projects/openjade - -The DocBook DSSSL Stylesheets (I've got 1.40, but v1.19+ may be OK). - I've customized the DSSSL code slightly, in gtk-doc.dsl, to colour - the program code listings/declarations, and to support global - cross-reference indices in the generated HTML. - http://docbook.sourceforge.net/projects/dsssl/ - - Most distributions now have packages for all of these, so I would strongly advise that you grab those. diff --git a/TODO b/TODO index 1b3c576..9049f6b 100644 --- a/TODO +++ b/TODO @@ -30,13 +30,13 @@ files: file * we need to check if this works well for all kind of _types (e.g. boxed) https://bugzilla.gnome.org/show_bug.cgi?id=605025 - + == -section.txt == https://bugzilla.gnome.org/show_bug.cgi?id=646094 * using SCAN_OPTION="--rebuild-sections" can be used to use the audogenerated sections file -* when scanning a header file, everything of the header and the respective .c +* when scanning a header file, everything of the header and the respective .c file will be put to one section * symbols can be hidden using __GTK_DOC_IGNORE__ @@ -75,11 +75,20 @@ diff -u --exclude="Makefile*" docs docs-tmpl | diffstat = Running = gtk-doc is using a makefile with several targets to get from sources to docs. It uses makefile variables for configuration. -It might be easier to have a gtk-doc tool that can run the other gtk-doc tools +It might be easier to have a gtkdoc tool that can run the other gtkdoc tools in the right order (ev. by importing them as modules). This could handle a few things nicer that the makefiles don't do well. This would also make it easy to run it manually or integrate into other build systems. += Intermediate files = +Can we change the intermediate files into a perl-module? So that all we need to +do is to import it. Ideally we have just one outfile for each tool: +gtkdoc-scan -> scan.pm (decl.txt, decl-list.txt, types.txt, sections.txt) +gtkdoc-scangobj -> scanobj.pm (interfacs, prerequisites, ...) + +Can we drop the decl-list.txt file (or rename to make sure this is what a +generated section.txt would look like) + = Issues = * gtkdoc-fixxref makefile targets use $HTML_DIR * HTML_DIR: The directory where gtk-doc generated documentation is installed diff --git a/cmake/Makefile.am b/cmake/Makefile.am index ea47259..737946c 100644 --- a/cmake/Makefile.am +++ b/cmake/Makefile.am @@ -8,3 +8,5 @@ cmake_DATA = \ GtkDocConfig.cmake \ GtkDocConfigVersion.cmake \ GtkDocScanGObjWrapper.cmake + +-include $(top_srcdir)/git.mk diff --git a/cmake/Makefile.in b/cmake/Makefile.in index 10135a8..c8c620a 100644 --- a/cmake/Makefile.in +++ b/cmake/Makefile.in @@ -209,12 +209,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ @@ -522,6 +522,8 @@ uninstall-am: uninstall-cmakeDATA uninstall-am uninstall-cmakeDATA +-include $(top_srcdir)/git.mk + # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. .NOEXPORT: diff --git a/configure b/configure index e32158d..494356d 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.25. +# Generated by GNU Autoconf 2.69 for gtk-doc 1.26. # # Report bugs to . # @@ -591,12 +591,12 @@ MAKEFLAGS= # Identity of this package. PACKAGE_NAME='gtk-doc' PACKAGE_TARNAME='gtk-doc' -PACKAGE_VERSION='1.25' -PACKAGE_STRING='gtk-doc 1.25' +PACKAGE_VERSION='1.26' +PACKAGE_STRING='gtk-doc 1.26' PACKAGE_BUGREPORT='http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc' PACKAGE_URL='' -ac_unique_file="gtkdoc-common.pl.in" +ac_unique_file="gtk-doc.pc.in" # Factoring default headers for most tests. ac_includes_default="\ #include @@ -656,6 +656,7 @@ GTK_DOC_USE_LIBTOOL_FALSE GTK_DOC_USE_LIBTOOL_TRUE TEST_DEPS_LIBS TEST_DEPS_CFLAGS +PYTHON_PACKAGE_DIR PACKAGE_DATA_DIR HIGHLIGHT_OPTIONS HIGHLIGHT @@ -664,8 +665,6 @@ XML_CATALOG_FILE FOP DBLATEX XSLTPROC -HAVE_PYTHON_FALSE -HAVE_PYTHON_TRUE pkgpyexecdir pyexecdir pkgpythondir @@ -675,7 +674,6 @@ PYTHON_EXEC_PREFIX PYTHON_PREFIX PYTHON_VERSION PYTHON -PERL PKG_CONFIG_LIBDIR PKG_CONFIG_PATH PKG_CONFIG @@ -1369,7 +1367,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.25 to adapt to many kinds of systems. +\`configure' configures gtk-doc 1.26 to adapt to many kinds of systems. Usage: $0 [OPTION]... [VAR=VALUE]... @@ -1439,7 +1437,7 @@ fi if test -n "$ac_init_help"; then case $ac_init_help in - short | recursive ) echo "Configuration of gtk-doc 1.25:";; + short | recursive ) echo "Configuration of gtk-doc 1.26:";; esac cat <<\_ACEOF @@ -1565,7 +1563,7 @@ fi test -n "$ac_init_help" && exit $ac_status if $ac_init_version; then cat <<\_ACEOF -gtk-doc configure 1.25 +gtk-doc configure 1.26 generated by GNU Autoconf 2.69 Copyright (C) 2012 Free Software Foundation, Inc. @@ -1843,7 +1841,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.25, which was +It was created by gtk-doc $as_me 1.26, which was generated by GNU Autoconf 2.69. Invocation command line was $ $0 $@ @@ -2710,7 +2708,7 @@ fi # Define the identity of the package. PACKAGE='gtk-doc' - VERSION='1.25' + VERSION='1.26' cat >>confdefs.h <<_ACEOF @@ -11747,61 +11745,6 @@ $as_echo "no" >&6; } fi fi -# Extract the first word of "perl", so it can be a program name with args. -set dummy perl; ac_word=$2 -{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 -$as_echo_n "checking for $ac_word... " >&6; } -if ${ac_cv_path_PERL+:} false; then : - $as_echo_n "(cached) " >&6 -else - case $PERL in - [\\/]* | ?:[\\/]*) - ac_cv_path_PERL="$PERL" # Let the user override the test with a path. - ;; - *) - as_save_IFS=$IFS; IFS=$PATH_SEPARATOR -for as_dir in $PATH -do - IFS=$as_save_IFS - test -z "$as_dir" && as_dir=. - for ac_exec_ext in '' $ac_executable_extensions; do - if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then - ac_cv_path_PERL="$as_dir/$ac_word$ac_exec_ext" - $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5 - break 2 - fi -done - done -IFS=$as_save_IFS - - ;; -esac -fi -PERL=$ac_cv_path_PERL -if test -n "$PERL"; then - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $PERL" >&5 -$as_echo "$PERL" >&6; } -else - { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 -$as_echo "no" >&6; } -fi - - -if test -z "$PERL"; then - as_fn_error $? "perl not found" "$LINENO" 5 -fi - -{ $as_echo "$as_me:${as_lineno-$LINENO}: checking if Perl version >= 5.18.0" >&5 -$as_echo_n "checking if Perl version >= 5.18.0... " >&6; } -if "$PERL" -e "require v5.18.0"; then - { $as_echo "$as_me:${as_lineno-$LINENO}: result: yes" >&5 -$as_echo "yes" >&6; } -else - { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 -$as_echo "no" >&6; } - as_fn_error $? "perl >= 5.18.0 is required for gtk-doc" "$LINENO" 5 -fi - @@ -11810,13 +11753,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.3" >&5 -$as_echo_n "checking whether $PYTHON version is >= 2.3... " >&6; } + { $as_echo "$as_me:${as_lineno-$LINENO}: checking whether $PYTHON version is >= 2.7" >&5 +$as_echo_n "checking whether $PYTHON version is >= 2.7... " >&6; } prog="import sys # split strings by '.' and convert to numeric. Append some zeros # because we need at least 4 digits for the hex conversion. # map returns an iterator in Python 3.0 and a list in 2.x -minver = list(map(int, '2.3'.split('.'))) + [0, 0, 0] +minver = list(map(int, '2.7'.split('.'))) + [0, 0, 0] minverhex = 0 # xrange is not present in Python 3.0 and range returns an iterator for i in list(range(0, 4)): minverhex = (minverhex << 8) + minver[i] @@ -11837,8 +11780,8 @@ 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.3" >&5 -$as_echo_n "checking for a Python interpreter with version >= 2.3... " >&6; } + { $as_echo "$as_me:${as_lineno-$LINENO}: checking for a Python interpreter with version >= 2.7" >&5 +$as_echo_n "checking for a Python interpreter with version >= 2.7... " >&6; } if ${am_cv_pathless_PYTHON+:} false; then : $as_echo_n "(cached) " >&6 else @@ -11849,7 +11792,7 @@ else # split strings by '.' and convert to numeric. Append some zeros # because we need at least 4 digits for the hex conversion. # map returns an iterator in Python 3.0 and a list in 2.x -minver = list(map(int, '2.3'.split('.'))) + [0, 0, 0] +minver = list(map(int, '2.7'.split('.'))) + [0, 0, 0] minverhex = 0 # xrange is not present in Python 3.0 and range returns an iterator for i in list(range(0, 4)): minverhex = (minverhex << 8) + minver[i] @@ -11915,7 +11858,7 @@ fi if test "$PYTHON" = :; then - : + as_fn_error $? "no suitable Python interpreter found" "$LINENO" 5 else @@ -12063,14 +12006,6 @@ $as_echo "$am_cv_python_pyexecdir" >&6; } fi - if test "$PYTHON" != :; then - HAVE_PYTHON_TRUE= - HAVE_PYTHON_FALSE='#' -else - HAVE_PYTHON_TRUE='#' - HAVE_PYTHON_FALSE= -fi - # Extract the first word of "xsltproc", so it can be a program name with args. set dummy xsltproc; ac_word=$2 @@ -12574,6 +12509,19 @@ PACKAGE_DATA_DIR="${datadir}/${PACKAGE}/data" test "$prefix_NONE" && prefix=NONE test "$exec_prefix_NONE" && exec_prefix=NONE +PYTHON_PACKAGE_DIR="${datadir}/${PACKAGE}/python" + + prefix_NONE= + exec_prefix_NONE= + test "x$prefix" = xNONE && prefix_NONE=yes && prefix=$ac_default_prefix + test "x$exec_prefix" = xNONE && exec_prefix_NONE=yes && exec_prefix=$prefix + eval ac_define_dir="\"$PYTHON_PACKAGE_DIR\"" + eval ac_define_dir="\"$ac_define_dir\"" + PYTHON_PACKAGE_DIR="$ac_define_dir" + + test "$prefix_NONE" && prefix=NONE + test "$exec_prefix_NONE" && exec_prefix=NONE + if test "x$GCC" = "xyes"; then if test -z "`echo "$CFLAGS" | grep "\-Wall" 2> /dev/null`" ; then @@ -13038,7 +12986,7 @@ else fi -ac_config_files="$ac_config_files Makefile gtk-doc.pc gtk-doc.dsl gtk-doc.spec gtk-doc.cat gtkdoc-common.pl cmake/Makefile cmake/GtkDocConfig.cmake cmake/GtkDocConfigVersion.cmake help/Makefile help/manual/Makefile tests/Makefile tests/gobject/Makefile tests/gobject/src/Makefile tests/gobject/docs/Makefile tests/bugs/Makefile tests/bugs/src/Makefile tests/bugs/docs/Makefile tests/annotations/Makefile tests/annotations/src/Makefile tests/annotations/docs/Makefile tests/fail/Makefile tests/fail/src/Makefile tests/fail/docs/Makefile tests/empty/Makefile tests/empty/src/Makefile tests/empty/docs/Makefile" +ac_config_files="$ac_config_files Makefile gtk-doc.pc cmake/Makefile cmake/GtkDocConfig.cmake cmake/GtkDocConfigVersion.cmake gtkdoc/config.py help/Makefile help/manual/Makefile tests/Makefile tests/gobject/Makefile tests/gobject/src/Makefile tests/gobject/docs/Makefile tests/bugs/Makefile tests/bugs/src/Makefile tests/bugs/docs/Makefile tests/annotations/Makefile tests/annotations/src/Makefile tests/annotations/docs/Makefile tests/fail/Makefile tests/fail/src/Makefile tests/fail/docs/Makefile tests/empty/Makefile tests/empty/src/Makefile tests/empty/docs/Makefile tests/program/Makefile tests/program/src/Makefile tests/program/docs/Makefile" ac_config_files="$ac_config_files gtkdoc-check" @@ -13055,8 +13003,6 @@ ac_config_files="$ac_config_files gtkdoc-mkman" ac_config_files="$ac_config_files gtkdoc-mkpdf" -ac_config_files="$ac_config_files gtkdoc-mktmpl" - ac_config_files="$ac_config_files gtkdoc-rebase" ac_config_files="$ac_config_files gtkdoc-scan" @@ -13240,10 +13186,6 @@ if test -z "${am__fastdepCC_TRUE}" && test -z "${am__fastdepCC_FALSE}"; then as_fn_error $? "conditional \"am__fastdepCC\" was never defined. Usually this means the macro was only invoked conditionally." "$LINENO" 5 fi -if test -z "${HAVE_PYTHON_TRUE}" && test -z "${HAVE_PYTHON_FALSE}"; then - as_fn_error $? "conditional \"HAVE_PYTHON\" was never defined. -Usually this means the macro was only invoked conditionally." "$LINENO" 5 -fi if test -z "${GTK_DOC_USE_LIBTOOL_TRUE}" && test -z "${GTK_DOC_USE_LIBTOOL_FALSE}"; then as_fn_error $? "conditional \"GTK_DOC_USE_LIBTOOL\" was never defined. Usually this means the macro was only invoked conditionally." "$LINENO" 5 @@ -13653,7 +13595,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.25, which was +This file was extended by gtk-doc $as_me 1.26, which was generated by GNU Autoconf 2.69. Invocation command line was CONFIG_FILES = $CONFIG_FILES @@ -13710,7 +13652,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.25 +gtk-doc config.status 1.26 configured by $0, generated by GNU Autoconf 2.69, with options \\"\$ac_cs_config\\" @@ -14109,13 +14051,10 @@ do "libtool") CONFIG_COMMANDS="$CONFIG_COMMANDS libtool" ;; "Makefile") CONFIG_FILES="$CONFIG_FILES Makefile" ;; "gtk-doc.pc") CONFIG_FILES="$CONFIG_FILES gtk-doc.pc" ;; - "gtk-doc.dsl") CONFIG_FILES="$CONFIG_FILES gtk-doc.dsl" ;; - "gtk-doc.spec") CONFIG_FILES="$CONFIG_FILES gtk-doc.spec" ;; - "gtk-doc.cat") CONFIG_FILES="$CONFIG_FILES gtk-doc.cat" ;; - "gtkdoc-common.pl") CONFIG_FILES="$CONFIG_FILES gtkdoc-common.pl" ;; "cmake/Makefile") CONFIG_FILES="$CONFIG_FILES cmake/Makefile" ;; "cmake/GtkDocConfig.cmake") CONFIG_FILES="$CONFIG_FILES cmake/GtkDocConfig.cmake" ;; "cmake/GtkDocConfigVersion.cmake") CONFIG_FILES="$CONFIG_FILES cmake/GtkDocConfigVersion.cmake" ;; + "gtkdoc/config.py") CONFIG_FILES="$CONFIG_FILES gtkdoc/config.py" ;; "help/Makefile") CONFIG_FILES="$CONFIG_FILES help/Makefile" ;; "help/manual/Makefile") CONFIG_FILES="$CONFIG_FILES help/manual/Makefile" ;; "tests/Makefile") CONFIG_FILES="$CONFIG_FILES tests/Makefile" ;; @@ -14134,6 +14073,9 @@ do "tests/empty/Makefile") CONFIG_FILES="$CONFIG_FILES tests/empty/Makefile" ;; "tests/empty/src/Makefile") CONFIG_FILES="$CONFIG_FILES tests/empty/src/Makefile" ;; "tests/empty/docs/Makefile") CONFIG_FILES="$CONFIG_FILES tests/empty/docs/Makefile" ;; + "tests/program/Makefile") CONFIG_FILES="$CONFIG_FILES tests/program/Makefile" ;; + "tests/program/src/Makefile") CONFIG_FILES="$CONFIG_FILES tests/program/src/Makefile" ;; + "tests/program/docs/Makefile") CONFIG_FILES="$CONFIG_FILES tests/program/docs/Makefile" ;; "gtkdoc-check") CONFIG_FILES="$CONFIG_FILES gtkdoc-check" ;; "gtkdoc-depscan") CONFIG_FILES="$CONFIG_FILES gtkdoc-depscan" ;; "gtkdoc-fixxref") CONFIG_FILES="$CONFIG_FILES gtkdoc-fixxref" ;; @@ -14141,7 +14083,6 @@ do "gtkdoc-mkhtml") CONFIG_FILES="$CONFIG_FILES gtkdoc-mkhtml" ;; "gtkdoc-mkman") CONFIG_FILES="$CONFIG_FILES gtkdoc-mkman" ;; "gtkdoc-mkpdf") CONFIG_FILES="$CONFIG_FILES gtkdoc-mkpdf" ;; - "gtkdoc-mktmpl") CONFIG_FILES="$CONFIG_FILES gtkdoc-mktmpl" ;; "gtkdoc-rebase") CONFIG_FILES="$CONFIG_FILES gtkdoc-rebase" ;; "gtkdoc-scan") CONFIG_FILES="$CONFIG_FILES gtkdoc-scan" ;; "gtkdoc-scangobj") CONFIG_FILES="$CONFIG_FILES gtkdoc-scangobj" ;; @@ -15306,7 +15247,6 @@ fi "gtkdoc-mkhtml":F) chmod +x gtkdoc-mkhtml ;; "gtkdoc-mkman":F) chmod +x gtkdoc-mkman ;; "gtkdoc-mkpdf":F) chmod +x gtkdoc-mkpdf ;; - "gtkdoc-mktmpl":F) chmod +x gtkdoc-mktmpl ;; "gtkdoc-rebase":F) chmod +x gtkdoc-rebase ;; "gtkdoc-scan":F) chmod +x gtkdoc-scan ;; "gtkdoc-scangobj":F) chmod +x gtkdoc-scangobj ;; @@ -15358,16 +15298,11 @@ $as_echo "$as_me: gtk-doc was configured with the following options: ==================================================" >&6;} -test "$PYTHON" != : \ - && { $as_echo "$as_me:${as_lineno-$LINENO}: ** Python based tools enabled, using $PYTHON" >&5 -$as_echo "$as_me: ** Python based tools enabled, using $PYTHON" >&6;} \ - || { $as_echo "$as_me:${as_lineno-$LINENO}: Python based tools disabled" >&5 -$as_echo "$as_me: Python based tools disabled" >&6;} test -n "$DBLATEX$FOP" \ - && { $as_echo "$as_me:${as_lineno-$LINENO}: ** XML PDF support enabled, using $DBLATEX$FOP" >&5 -$as_echo "$as_me: ** XML PDF support enabled, using $DBLATEX$FOP" >&6;} \ - || { $as_echo "$as_me:${as_lineno-$LINENO}: XML PDF support disabled, no dblatex or fop available" >&5 -$as_echo "$as_me: XML PDF support disabled, no dblatex or fop available" >&6;} + && { $as_echo "$as_me:${as_lineno-$LINENO}: ** PDF support enabled, using $DBLATEX$FOP" >&5 +$as_echo "$as_me: ** PDF support enabled, using $DBLATEX$FOP" >&6;} \ + || { $as_echo "$as_me:${as_lineno-$LINENO}: PDF support disabled, no dblatex or fop available" >&5 +$as_echo "$as_me: PDF support disabled, no dblatex or fop available" >&6;} test -n "$HIGHLIGHT" \ && { $as_echo "$as_me:${as_lineno-$LINENO}: ** Syntax highlighting of examples enabled, using $HIGHLIGHT" >&5 $as_echo "$as_me: ** Syntax highlighting of examples enabled, using $HIGHLIGHT" >&6;} \ diff --git a/configure.ac b/configure.ac index eae0aa7..92644d9 100644 --- a/configure.ac +++ b/configure.ac @@ -5,12 +5,12 @@ dnl Use a simple 2-digit version number for a while, since our old example dnl Makefile can only cope with that, i.e. use 1.1, 1.2, 1.3 ... 9.9. dnl FIXME: I can't see anything failing (1.14.1), lets try to use a three digit dnl number for the development version -m4_define(gtk_doc_version, 1.25) +m4_define(gtk_doc_version, 1.26) AC_INIT([gtk-doc],[gtk_doc_version],[http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc],[gtk-doc]) AC_CONFIG_MACRO_DIR([m4]) -AC_CONFIG_SRCDIR([gtkdoc-common.pl.in]) +AC_CONFIG_SRCDIR([gtk-doc.pc.in]) AC_CONFIG_AUX_DIR([build-aux]) AM_INIT_AUTOMAKE([1.11 check-news std-options -Wno-portability tar-ustar no-dist-gzip dist-xz]) @@ -31,27 +31,10 @@ LT_INIT dnl Make sure we have pkg-config >= 0.19, so installing in $(datadir) is OK. PKG_PROG_PKG_CONFIG([0.19]) -dnl -dnl Check for Perl. -dnl -AC_PATH_PROG([PERL], [perl]) -if test -z "$PERL"; then - AC_MSG_ERROR([perl not found]) -fi - -AC_MSG_CHECKING([if Perl version >= 5.18.0]) -if "$PERL" -e "require v5.18.0"; then - AC_MSG_RESULT([yes]) -else - AC_MSG_RESULT([no]) - AC_MSG_ERROR([perl >= 5.18.0 is required for gtk-doc]) -fi - dnl dnl Check for Python. dnl -AM_PATH_PYTHON([2.3],,[:]) -AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :]) +AM_PATH_PYTHON([2.7]) dnl dnl Check for xsltproc @@ -137,7 +120,7 @@ fi AC_SUBST([HIGHLIGHT_OPTIONS]) dnl -dnl Set PACKAGE_DATA_DIR so we can find the script containing common routines. +dnl Set runtime package dirs so we can find the script containing common routines. dnl dnl From Autoconf Macro Archive: m4_define([AC_DEFINE_DIR], [ @@ -153,6 +136,8 @@ m4_define([AC_DEFINE_DIR], [ ]) PACKAGE_DATA_DIR="${datadir}/${PACKAGE}/data" AC_DEFINE_DIR([PACKAGE_DATA_DIR], [PACKAGE_DATA_DIR]) +PYTHON_PACKAGE_DIR="${datadir}/${PACKAGE}/python" +AC_DEFINE_DIR([PYTHON_PACKAGE_DIR], [PYTHON_PACKAGE_DIR]) dnl Only use -Wall if we have gcc if test "x$GCC" = "xyes"; then @@ -172,7 +157,7 @@ PKG_CHECK_MODULES(TEST_DEPS, [glib-2.0 >= 2.6.0 gobject-2.0 >= 2.6.0], ] ) AM_CONDITIONAL(GTK_DOC_USE_LIBTOOL, test -n "$LIBTOOL" -a x$gtk_doc_use_libtool = xyes ) -dnl this enable the rule in test/Makefile.am +dnl this enables the rule in test/Makefile.am AM_CONDITIONAL(BUILD_TESTS, test x$build_tests = xyes) AC_SUBST(glib_prefix) @@ -236,13 +221,10 @@ AM_CONDITIONAL([HAVE_YELP_TOOLS],[test x$have_yelp_tools = xyes]) AC_CONFIG_FILES([Makefile gtk-doc.pc -gtk-doc.dsl -gtk-doc.spec -gtk-doc.cat -gtkdoc-common.pl cmake/Makefile cmake/GtkDocConfig.cmake cmake/GtkDocConfigVersion.cmake +gtkdoc/config.py help/Makefile help/manual/Makefile tests/Makefile @@ -261,19 +243,19 @@ tests/fail/docs/Makefile tests/empty/Makefile tests/empty/src/Makefile tests/empty/docs/Makefile +tests/program/Makefile +tests/program/src/Makefile +tests/program/docs/Makefile ]) dnl run chmod on these after parsing them. AC_CONFIG_FILES([gtkdoc-check], [chmod +x gtkdoc-check]) AC_CONFIG_FILES([gtkdoc-depscan], [chmod +x gtkdoc-depscan]) AC_CONFIG_FILES([gtkdoc-fixxref], [chmod +x gtkdoc-fixxref]) -dnl that would be nice, but would fail if perl is in a non-std path -dnl AC_CONFIG_FILES([gtkdoc-mkdb], [chmod +x gtkdoc-mkdb && perl -cwT gtkdoc-mkdb]) AC_CONFIG_FILES([gtkdoc-mkdb], [chmod +x gtkdoc-mkdb]) AC_CONFIG_FILES([gtkdoc-mkhtml], [chmod +x gtkdoc-mkhtml]) AC_CONFIG_FILES([gtkdoc-mkman], [chmod +x gtkdoc-mkman]) AC_CONFIG_FILES([gtkdoc-mkpdf], [chmod +x gtkdoc-mkpdf]) -AC_CONFIG_FILES([gtkdoc-mktmpl], [chmod +x gtkdoc-mktmpl]) AC_CONFIG_FILES([gtkdoc-rebase], [chmod +x gtkdoc-rebase]) AC_CONFIG_FILES([gtkdoc-scan], [chmod +x gtkdoc-scan]) AC_CONFIG_FILES([gtkdoc-scangobj], [chmod +x gtkdoc-scangobj]) @@ -285,12 +267,9 @@ AC_MSG_NOTICE([ gtk-doc was configured with the following options: ==================================================]) -test "$PYTHON" != : \ - && AC_MSG_NOTICE([** Python based tools enabled, using $PYTHON]) \ - || AC_MSG_NOTICE([ Python based tools disabled]) test -n "$DBLATEX$FOP" \ - && AC_MSG_NOTICE([** XML PDF support enabled, using $DBLATEX$FOP]) \ - || AC_MSG_NOTICE([ XML PDF support disabled, no dblatex or fop available]) + && AC_MSG_NOTICE([** PDF support enabled, using $DBLATEX$FOP]) \ + || AC_MSG_NOTICE([ PDF support disabled, no dblatex or fop available]) test -n "$HIGHLIGHT" \ && AC_MSG_NOTICE([** Syntax highlighting of examples enabled, using $HIGHLIGHT]) \ || AC_MSG_NOTICE([ Syntax highlighting of examples disabled]) diff --git a/db2man/README b/db2man/README deleted file mode 100644 index 6c48fc2..0000000 --- a/db2man/README +++ /dev/null @@ -1,14 +0,0 @@ - -FILES -===== - -docbook-to-man - my customized version of the docbook-to-man script. Note that it has - paths in it that you may need to change. - I also used the PROLOG stuff to specify the DocBook DTD when passing - the man pages to instant. - -docbook-to-man.ts - my customized version of the instant 'translation spec'. - I added support for the central title at the top of the pages, and the - revision date at the end. I also converted section 1 headings to all caps. \ No newline at end of file diff --git a/db2man/docbook-to-man b/db2man/docbook-to-man deleted file mode 100755 index fd85da6..0000000 --- a/db2man/docbook-to-man +++ /dev/null @@ -1,178 +0,0 @@ -#!/bin/sh -############################################################################# -# -# docbook-to-man.sh -# -############################################################################# -# -# Copyright (c) 1996 X Consortium -# Copyright (c) 1996 Dalrymple Consulting -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in -# all copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# X CONSORTIUM OR DALRYMPLE CONSULTING BE LIABLE FOR ANY CLAIM, DAMAGES OR -# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -# OTHER DEALINGS IN THE SOFTWARE. -# -# Except as contained in this notice, the names of the X Consortium and -# Dalrymple Consulting shall not be used in advertising or otherwise to -# promote the sale, use or other dealings in this Software without prior -# written authorization. -# -############################################################################# -# -# Written 5/29/96 by Fred Dalrymple -# -############################################################################# - -# ***** change the following paths if your installation of nsgmls and / or -# ***** DocBook isn't into the default places. - -ROOT=/usr -SGMLS=$ROOT/lib/sgml -DOCBOOK=$SGMLS/davenport - - -# ***** modify the following line (to "=false") if you're not using the -# ***** Elan Documentor's Workbench - -doElanPSInclude=false - - - -# Everything below this line should be pretty standard and not require -# modification. - -#ulimit -c unlimited - -PARSER=nsgmls -INSTANT=instant -INSTANT_OPT=-d - -#CATALOG=$DOCBOOK/docbook.cat -CATALOG=/etc/sgml.catalog -DECL=$DOCBOOK/docbook.dcl - -error=false - -if [ $# -eq 1 ] -then INSTANCE=$1 -else error=true -fi - -if `$error` -then echo "usage: docbook-to-man docbook-instance" - exit 1 -fi - -if `$doElanPSInclude` -then cat > /tmp/dtm.$$.psinc <<\! -...\" $Header$ -...\" -...\" transcript compatibility for postscript use. -...\" -...\" synopsis: .P! -...\" -.de P! -\\&. -.fl \" force out current output buffer -\\!%PB -\\!/showpage{}def -...\" the following is from Ken Flowers -- it prevents dictionary overflows -\\!/tempdict 200 dict def tempdict begin -.fl \" prolog -.sy cat \\$1\" bring in postscript file -...\" the following line matches the tempdict above -\\!end % tempdict % -\\!PE -\\!. -.sp \\$2u \" move below the image -.. -! -else cat > /tmp/dtm.$$.psinc <<\! -...\" $Header$ -...\" -...\" transcript compatibility for postscript use. -...\" -...\" synopsis: .P! -...\" -.de P! -.fl -\!!1 setgray -.fl -\\&.\" -.fl -\!!0 setgray -.fl \" force out current output buffer -\!!save /psv exch def currentpoint translate 0 0 moveto -\!!/showpage{}def -.fl \" prolog -.sy sed -e 's/^/!/' \\$1\" bring in postscript file -\!!psv restore -. -! -fi - -cat >> /tmp/dtm.$$.psinc <<\! -.de pF -.ie \\*(f1 .ds f1 \\n(.f -.el .ie \\*(f2 .ds f2 \\n(.f -.el .ie \\*(f3 .ds f3 \\n(.f -.el .ie \\*(f4 .ds f4 \\n(.f -.el .tm ? font overflow -.ft \\$1 -.. -.de fP -.ie !\\*(f4 \{\ -. ft \\*(f4 -. ds f4\" -' br \} -.el .ie !\\*(f3 \{\ -. ft \\*(f3 -. ds f3\" -' br \} -.el .ie !\\*(f2 \{\ -. ft \\*(f2 -. ds f2\" -' br \} -.el .ie !\\*(f1 \{\ -. ft \\*(f1 -. ds f1\" -' br \} -.el .tm ? font underflow -.. -.ds f1\" -.ds f2\" -.ds f3\" -.ds f4\" -! - - -cat > /tmp/dtm.$$.prolog < -]> -! - -(cat /tmp/dtm.$$.psinc; - $PARSER -gl -wno-idref -m$CATALOG $DECL /tmp/dtm.$$.prolog $INSTANCE | - $INSTANT $INSTANT_OPT -croff.cmap -sroff.sdata -tdocbook-to-man.ts) - -#(cat /tmp/dtm.$$.psinc; -# $PARSER -gl -wno-idref -m$CATALOG $DECL $INSTANCE | -# $INSTANT $INSTANT_OPT -croff.cmap -sroff.sdata -tdocbook-to-man.ts) - -rm -f /tmp/dtm.$$.psinc -rm -f /tmp/dtm.$$.prolog diff --git a/db2man/docbook-to-man.ts b/db2man/docbook-to-man.ts deleted file mode 100644 index 7faa417..0000000 --- a/db2man/docbook-to-man.ts +++ /dev/null @@ -1,2019 +0,0 @@ -############################################################################# -# -# docbook-to-man.ts -# -############################################################################# -# -# Copyright (c) 1996 X Consortium -# Copyright (c) 1996 Dalrymple Consulting -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in -# all copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# X CONSORTIUM OR DALRYMPLE CONSULTING BE LIABLE FOR ANY CLAIM, DAMAGES OR -# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -# OTHER DEALINGS IN THE SOFTWARE. -# -# Except as contained in this notice, the names of the X Consortium and -# Dalrymple Consulting shall not be used in advertising or otherwise to -# promote the sale, use or other dealings in this Software without prior -# written authorization. -# -############################################################################# -# -# Written 5/29/96 by Fred Dalrymple -# -############################################################################# -# -# Variables -# -Var: callout 0 -Var: orderlist 0 -Var: procstep 0 -Var: procsubstep 0 -# -# -# -# -############################################################################# -# -# Hierarchy (and document meta stuff) -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: REFENTRY -StartText: ^.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n - ^.TH "${_followrel descendant REFENTRYTITLE 1000}" - "${_followrel descendant MANVOLNUM 1000}" - "${REVISION}" "" - "${_followrel descendant REFMISCINFO 1000}"^ -EndText: ^...\\" created by instant / docbook-to-man, ${date}^ -- -# -GI: DOCINFO -Ignore: all -- -# -GI: TITLE -Context: DOCINFO -# inside DocInfo, which we're ignoring -- -# -GI: REFMETA -Ignore: all -- -# -GI: REFNAMEDIV -StartText: ^.SH "NAME"^ -- -# -GI: REFDESCRIPTOR -StartText: \\fB -EndText: \\fR\s -- -# -GI: REFNAME -Relation: sibling- REFDESCRIPTOR -# inhibit REFNAMEs when a REFDESCRIPTOR is present -Ignore: all -- -# -GI: REFNAME -StartText: ${_isset refnameseen xxx 20} -EndText: ${_set refnameseen xxx} -- -# -GI: _refname -SpecID: 20 -StartText: ,\s -- -# -GI: REFPURPOSE -StartText: \s\\-\s -EndText: ^ -- -# -GI: REFCLASS -StartText: ^.PP^ -EndText: ^ -- -# -GI: REFSYNOPSISDIV -StartText: ^.SH "SYNOPSIS"^ -EndText: ^ -- -# -GI: REFSECT1 -StartText: ^.SH "${_followrel child TITLE 1001}"^ -EndText: ^ -- -# -GI: REFSECT2 -StartText: ^.SS "${_followrel child TITLE 1000}"^ -EndText: ^ -- -# -GI: REFSECT3 -StartText: ^.SS "${_followrel child TITLE 1000}"^ -EndText: ^ -- -# -GI: BRIDGEHEAD -StartText: ^.PP^\\fB -EndText: \\fP^.PP^ -- -# -GI: TITLE -Context: REFSECT1 -Ignore: all -- -# -GI: TITLE -Context: REFSECT2 -Ignore: all -- -# -GI: TITLE -Context: REFSECT3 -Ignore: all -- -# -GI: LEGALNOTICE -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -GI: TITLE -Context: LEGALNOTICE -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -GI: REFENTRYTITLE -Context: REFMETA -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -GI: MANVOLNUM -Context: REFMETA -# part of the DocInfo structure, which is ignored, though this element -# if accessed directly by the _followrel call from the REFENTRY element. -Ignore: all -- -# -GI: REFMISCINFO -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -GI: SUBTITLE -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -GI: AUTHORGROUP -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -GI: AUTHOR -Context: AUTHORGROUP -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -GI: EDITOR -Context: AUTHORGROUP -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -GI: COLLAB -Context: AUTHORGROUP -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -GI: COLLABNAME -Context: COLLAB -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -GI: CORPAUTHOR -Context: AUTHORGROUP -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -GI: OTHERCREDIT -Context: AUTHORGROUP -# part of the DocInfo structure, which is ignored -Ignore: all -- -# -# -############################################################################# -# -# (before we get into the branch stuff, we turn off paragraphs in some -# contexts where they would break the flow. Generally, this happens -# within indented areas, such as within lists. -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: PARA -Context: LISTITEM -NthChild: 1 -# nothing in this context -- -# -GI: PARA -Context: GLOSSDEF -NthChild: 1 -# nothing in this context -- -# -GI: PARA -Context: STEP -NthChild: 1 -# nothing in this context -- -# -GI: PARA -Context: CALLOUT -NthChild: 1 -# nothing in this context -- -# -GI: PARA -Context: MSGTEXT -NthChild: 1 -# nothing in this context -- -# -GI: PARA -Relation: parent ENTRY -NthChild: 1 -# first one does nothing in this context -- -# -GI: PARA -Relation: parent ENTRY -StartText: ^.br^ -- -# -# -# -############################################################################# -# -# Regular "branch" stuff -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: FORMALPARA -# it's all done in TITLE (FORMALPARA) and PARA -- -# -GI: TITLE -Context: FORMALPARA -StartText: ^.PP^\\fB -EndText: \\fR^ -- -# -GI: PARA -Relation: ancestor LISTITEM -StartText: ^.IP "" 10^ -- -# -GI: PARA -Relation: ancestor STEP -StartText: ^.IP "" 10^ -- -# -GI: PARA -StartText: ^.PP^ -- -# -GI: SIMPARA -StartText: ^.PP^ -- -# -GI: PROGRAMLISTING -StartText: ^.PP^.nf^\\f(CW -EndText: \\fR^.fi^.PP^ -- -# -GI: LITERALLAYOUT -StartText: ^.PP^.nf^ -EndText: ^.fi^ -- -# -GI: BLOCKQUOTE -StartText: ^.PP^.RS^ -EndText: ^.RE^ -- -# -GI: TITLE -Context: BLOCKQUOTE -StartText: ^\\fB -EndText: \\fR^.PP^ -- -# -GI: EPIGRAPH -StartText: ^.PP^.RS^ -EndText: ^.RE^ -- -# -GI: ATTRIBUTION -StartText: ^\\fI -EndText: \\fR^.PP^ -- -# -GI: ABSTRACT -Relation: child TITLE -- -# -GI: ABSTRACT -StartText: ^.SS "Abstract"^ -- -# -GI: TITLE -Context: ABSTRACT -StartText: ^.SS " -EndText: "^ -Substitute: " "" -- -# -GI: REVHISTORY -StartText: ^.SS "Revision History"^ -EndText: ^ -- -# -GI: REVISION -StartText: ^.PP^\\fBRevision:\\fR\s -EndText: ^ -- -# -GI: REVNUMBER -StartText: #\s -EndText: ;\s -- -# -GI: DATE -EndText: ;\s -- -# -GI: AUTHORINITIALS -Context: REVISION -StartText: \s -- -# -GI: REVREMARK -StartText: ;\s\s -EndText: ^ -- -# -GI: PROGRAMLISTINGCO -# nothing to do specifically in ProgramListingCO -- it falls to -# the content of ProgramListing and any callout list -- -# -GI: SCREEN -StartText: ^.PP^.nf^ -EndText: ^.fi^ -- -# -GI: SCREENCO -# nothing to do specifically in ScreenCO -- it falls to -# the content of Screen and any callout list -- -# -GI: SCREENSHOT -# nothing specific to do here -- defer to any ScreenInfo or the -# included graphic -- -# -GI: SCREENINFO -StartText: ^.PP^\\fI -EndText: \\fR^.PP^ -- -# -GI: GRAPHICCO -# nothing to do specifically in GraphicCO -- it falls to -# the content of Graphic and any callout list -- -# -GI: INFORMALEXAMPLE -# nothing special to do here -- it falls to the content. -- -# -GI: EXAMPLE -# nothing special to do here -- it falls to the content. -- -# -GI: TITLE -Context: EXAMPLE -StartText: ^.PP^\\fB -EndText: \\fR^ -- -# -GI: FIGURE -# nothing special to do here -- it falls to the content. -- -# -GI: TITLE -Context: FIGURE -StartText: ^.PP^\\fB -EndText: \\fR^ -- -# -GI: SIDEBAR -Relation: child TITLE -StartText: ^.PP^.RS^ -EndText: ^.RE^ -- -# -GI: SIDEBAR -StartText: ^.PP^.RS^\\fB[ Sidebar ]\\fR^ -EndText: ^.RE^ -- -# -GI: TITLE -Context: SIDEBAR -StartText: ^\\fB[ Sidebar:\s -EndText: \s]\\fR^ -- -# -GI: HIGHLIGHTS -StartText: ^.SS "Highlights"^ -- -# -GI: AUTHORBLURB -# nothing to do specially -- an included title may occur -- -# -GI: TITLE -Context: AUTHORBLURB -StartText: ^.PP^\\fB -EndText: \\fR^ -- -# -# -############################################################################# -# -# Call-out material -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: CO -# nothing to do for the anchor of a callout -- -# -GI: AREASPEC -Ignore: all -# not much to do with representing the anchor of callouts in n/troff -- -# -GI: AREA -Ignore: all -# part of AreaSpec, which is being ignored -- -# -GI: AREASET -Ignore: all -# part of AreaSpec, which is being ignored -- -# -# -############################################################################# -# -# Address block -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: ADDRESS -StartText: ^.PP^.nf^ -EndText: ^.fi^ -- -# -GI: STREET -# just the content... -- -# -GI: POB -# just the content... -- -# -GI: POSTCODE -# just the content... -- -# -GI: CITY -EndText: ,\s -- -# -GI: STATE -# just the content -- -# -GI: COUNTRY -# just the content -- -# -GI: PHONE -StartText: ^voice:\s -- -# -GI: FAX -StartText: ^fax:\s -- -# -GI: OTHERADDR -# just the content.. -- -# -GI: EMAIL -Context: ADDRESS -# just the content.. -- -# -# -############################################################################# -# -# Lists -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: GLOSSLIST -Relation: ancestor ITEMIZEDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: GLOSSLIST -Relation: ancestor GLOSSLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: GLOSSLIST -Relation: ancestor ORDEREDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: GLOSSLIST -Relation: ancestor SIMPLELIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: GLOSSLIST -Relation: ancestor VARIABLELIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: GLOSSLIST -Relation: ancestor SEGMENTEDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: GLOSSLIST -# Nothing to do here.. see glossentry, etc -- -# -GI: GLOSSENTRY -# nothing to do.. -- -# -GI: GLOSSTERM -Context: GLOSSENTRY -StartText: ^.IP " -EndText: " 10^ -Substitute: " "" -- -# -GI: GLOSSTERM -StartText: \\fB -EndText: \\fP -- -# -GI: ACRONYM -Context: GLOSSENTRY -StartText: (\\fIacronym:\s\\fR -EndText: )\s\s -- -# -GI: ABBREV -Context: GLOSSENTRY -StartText: (\\fIabbreviation:\s\\fR -EndText: )\s\s -- -# -GI: GLOSSSEE -StartText: ^\\fISee \\fR -- -# -GI: GLOSSDEF -# nothing special to do -- just pass the content. -- -# -GI: GLOSSSEEALSO -StartText: ^^\\fISee Also \\fR -- -# -GI: ITEMIZEDLIST -Relation: ancestor ITEMIZEDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ITEMIZEDLIST -Relation: ancestor GLOSSLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ITEMIZEDLIST -Relation: ancestor ORDEREDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ITEMIZEDLIST -Relation: ancestor SIMPLELIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ITEMIZEDLIST -Relation: ancestor VARIABLELIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ITEMIZEDLIST -Relation: ancestor SEGMENTEDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ITEMIZEDLIST -# nothing to do.. -- -# -GI: LISTITEM -Context: ITEMIZEDLIST -StartText: ^.IP "\ \ \ \\(bu" 6^ -- -# -GI: ORDEREDLIST -Relation: ancestor ITEMIZEDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ORDEREDLIST -Relation: ancestor GLOSSLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ORDEREDLIST -Relation: ancestor ORDEREDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ORDEREDLIST -Relation: ancestor SIMPLELIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ORDEREDLIST -Relation: ancestor VARIABLELIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ORDEREDLIST -Relation: ancestor SEGMENTEDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: ORDEREDLIST -StartText: ${_set orderlist 1} -- -# -GI: LISTITEM -Context: ORDEREDLIST -StartText: ^.IP "\ \ \ ${orderlist}." 6^ -Increment: orderlist -- -# -GI: SIMPLELIST -Relation: ancestor ITEMIZEDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: SIMPLELIST -Relation: ancestor GLOSSLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: SIMPLELIST -Relation: ancestor ORDEREDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: SIMPLELIST -Relation: ancestor SIMPLELIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: SIMPLELIST -Relation: ancestor VARIABLELIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: SIMPLELIST -Relation: ancestor SEGMENTEDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: SIMPLELIST -# nothing to do here.. -- -# -GI: MEMBER -PAttSet: TYPE INLINE -NthChild: 1 -- -# -GI: MEMBER -PAttSet: TYPE INLINE -StartText: ,\s -- -# -GI: MEMBER -PAttSet: TYPE HORIZ -NthChild: 1 -StartText: ^.PP^\t -- -# -GI: MEMBER -PAttSet: TYPE HORIZ -StartText: \t -- -# -GI: MEMBER -PAttSet: TYPE VERT -StartText: ^.IP "" 10^ -EndText: ^ -- -# -GI: VARIABLELIST -Relation: ancestor ITEMIZEDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: VARIABLELIST -Relation: ancestor GLOSSLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: VARIABLELIST -Relation: ancestor ORDEREDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: VARIABLELIST -Relation: ancestor SIMPLELIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: VARIABLELIST -Relation: ancestor VARIABLELIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: VARIABLELIST -Relation: ancestor SEGMENTEDLIST -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: VARIABLELIST -# nothing to do now, see VarListEntry -- -# -GI: VARLISTENTRY -# nothing to do now, see Term -- -# -GI: TERM -StartText: ^.IP " -EndText: " 10^ -Substitute: " "" -- -# -GI: LISTITEM -Context: VARLISTENTRY -# nothing special to do.. -- -# -GI: SEGMENTEDLIST -Relation: ancestor ITEMIZEDLIST -StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab();^l l l l l l l l l l l l l l l l l l.^ -EndText: ^.TE^.RE^ -- -# -GI: SEGMENTEDLIST -Relation: ancestor GLOSSLIST -StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab();^l l l l l l l l l l l l l l l l l l.^ -EndText: ^.TE^.RE^ -- -# -GI: SEGMENTEDLIST -Relation: ancestor ORDEREDLIST -StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab();^l l l l l l l l l l l l l l l l l l.^ -EndText: ^.TE^.RE^ -- -# -GI: SEGMENTEDLIST -Relation: ancestor SIMPLELIST -StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab();^l l l l l l l l l l l l l l l l l l.^ -EndText: ^.TE^.RE^ -- -# -GI: SEGMENTEDLIST -Relation: ancestor VARIABLELIST -StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab();^l l l l l l l l l l l l l l l l l l.^ -EndText: ^.TE^.RE^ -- -# -GI: SEGMENTEDLIST -Relation: ancestor SEGMENTEDLIST -StartText: ^.RS^${_followrel child TITLE 400}^.TS^tab();^l l l l l l l l l l l l l l l l l l.^ -EndText: ^.TE^.RE^ -- -# -GI: SEGMENTEDLIST -Relation: child TITLE -StartText: ^${_followrel child TITLE 400}^.TS^tab();^l l l l l l l l l l l l l l l l l l.^ -EndText: ^.TE^ -- -# -GI: TITLE -Context: SEGMENTEDLIST -# ignored by default -- must be called by SEGMENTEDLIST gi -Ignore: all -- -# -GI: _segmentedlist_title -SpecID: 400 -StartText: ^.sp 1^\\fB -EndText: \\fR^ -- -# -GI: SEGTITLE -StartText: \\fB -EndText: \\fR -- -# -GI: SEGLISTITEM -StartText: ^ -EndText: ^ -- -# -GI: SEG -EndText:  -- -# -GI: PROCEDURE -# defer to the content... -StartText: ${_set procstep 1}${_set procsubstep 1} -- -# -GI: TITLE -Context: PROCEDURE -StartText: ^.PP^\\fB -EndText: \\fR^ -- -# -GI: STEP -Context: SUBSTEPS -StartText: ^.PP^\\fISubstep ${procsubstep}.\s\s -EndText: ^ -Increment: procsubstep 1 -- -# -GI: STEP -StartText: ^.PP^\\fIStep ${procstep}.\s\s -EndText: ^ -Increment: procstep 1 -- -# -GI: TITLE -Context: STEP -StartText: ^\\fB -EndText: \\fR^.PP^ -- -# -GI: SUBSTEPS -StartText: ^.RS^ -EndText: ^.RE^ -- -# -GI: CALLOUTLIST -StartText: ${_set callout 1} -# nothing to do specifically, defer to the content... -- -# -GI: TITLE -Context: CALLOUTLIST -StartText: ^\\fB -EndText: \\fR^.PP^ -- -# -GI: CALLOUT -StartText: ^.PP^\\fICallout ${callout}.\s\s\\fR -EndText: ^ -Increment: callout -- -# -# -############################################################################# -# -# Messages -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: MSGSET -StartText: ^.SS "Message Set"^ -- -# -GI: MSGENTRY -StartText: ^.PP^\\fBMessage Entry\\fR^.RS^ -EndText: ^.RE^ -- -# -GI: MSG -Relation: child TITLE -StartText: ^.PP^ -EndText: ^ -- -# -GI: MSG -StartText: ^.PP^\\fBMessage:\\fR^.PP^ -EndText: ^ -- -# -GI: TITLE -Context: MSG -StartText: ^.PP^\\fB -EndText: \\fR^.PP^ -- -# -GI: MSGINFO -# nothing specific -- just groups (MsgLevel | MsgOrig | MsgAud)* -- -# -GI: MSGEXPLAN -# nothing special -- defer to content -- -# -GI: TITLE -Context: MSGEXPLAN -StartText: ^.PP^\\fB -EndText: \\fR^ -- -# -GI: MSGMAIN -# defer to content -- -# -GI: TITLE -Context: MSGMAIN -StartText: ^\\fB -EndText: \\fR^ -- -# -GI: MSGSUB -# defer to content -- -# -GI: TITLE -Context: MSGSUB -StartText: ^.PP^\\fB -EndText: \\fR^ -- -# -GI: MSGREL -# defer to content -- -# -GI: TITLE -Context: MSGREL -StartText: ^.PP^\\fB -EndText: \\fR^ -- -# -GI: MSGLEVEL -StartText: ^.PP^\\fIMessage level:\s\s\\fR -EndText: ^ -- -# -GI: MSGORIG -StartText: ^.PP^\\fIMessage origin:\s\s\\fR -EndText: ^ -- -# -GI: MSGAUD -StartText: ^.PP^\\fIMessage audience:\s\s\\fR -EndText: ^ -- -# -GI: MSGTEXT -Context: PARA -StartText: \\fI -EndText: \\fP -- -# -GI: MSGTEXT -StartText: \\fR^\\fIMessage text:\\fR\s\s -EndText: ^ -- -# -# -############################################################################# -# -# Admonitions -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: CAUTION -Relation: child TITLE -StartText: ^.PP^.RS -EndText: ^.RE^ -- -# -GI: CAUTION -StartText: ^.PP^.RS^\\fBCaution:\s\s -EndText: ^.RE^ -- -# -GI: TITLE -Context: CAUTION -StartText: ^\\fBCaution:\s\s -EndText: \\fR^.PP^ -- -# -GI: IMPORTANT -Relation: child TITLE -StartText: ^.PP^.RS^ -EndText: ^.RE^ -- -# -GI: IMPORTANT -StartText: ^.PP^.RS^\\fBImportant:\s\s -EndText: ^.RE^ -- -# -GI: TITLE -Context: IMPORTANT -StartText: ^\\fBImportant:\s\s -EndText: \\fR^.PP^ -- -# -GI: NOTE -Relation: child TITLE -StartText: ^.PP^.RS -EndText: ^.RE^ -- -# -GI: NOTE -StartText: ^.PP^.RS^\\fBNote:\s\s -EndText: ^.RE^ -- -# -GI: TITLE -Context: NOTE -StartText: ^\\fBNote:\s\s -EndText: \\fR^.PP^ -- -# -GI: TIP -Relation: child TITLE -StartText: ^.PP^.RS -EndText: ^.RE^ -- -# -GI: TIP -StartText: ^.PP^.RS^\\fBTip:\s\s -EndText: ^.RE^ -- -# -GI: TITLE -Context: TIP -StartText: ^\\fBTip:\s\s -EndText: \\fR^.PP^ -- -# -GI: WARNING -Relation: child TITLE -StartText: ^.PP^.RS -EndText: ^.RE^ -- -# -GI: WARNING -StartText: ^.PP^.RS^\\fBWarning:\s\s -EndText: ^.RE^ -- -# -GI: TITLE -Context: WARNING -StartText: ^\\fBWarning:\s\s -EndText: \\fR^.PP^ -- -# -# -############################################################################# -# -# Synopses -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: SYNOPSIS -StartText: ^.PP^.nf^ -EndText: ^.fi^ -- -# -GI: CMDSYNOPSIS -StartText: ^.PP^ -EndText: ^ -- -# -GI: ARG -Context: GROUP -NthChild: 1 -EndText: ${_attval REP REPEAT 505}\s -- -# -GI: ARG -Context: GROUP -StartText: \s|\s -EndText: ${_attval REP REPEAT 505}\s -- -# -GI: ARG -AttValue: CHOICE OPT -StartText: \s[ -EndText: ${_attval REP REPEAT 505}]\s -- -# -GI: ARG -# no special attrs -- just pass content through -EndText: ${_attval REP REPEAT 505}\s -- -# -GI: _arg_group -SpecID: 505 -StartText: \s\\&... -Ignore: all -- -# -GI: GROUP -AttValue: CHOICE OPT -StartText: \s[ -EndText: ]\s${_attval REP REPEAT 505} -- -# -GI: GROUP -AttValue: CHOICE REQ -StartText: \s{ -EndText: }\s${_attval REP REPEAT 505} -- -# -GI: GROUP -AttValue: CHOICE OPTMULT -StartText: \s[[ -EndText: ]]\s${_attval REP REPEAT 505} -- -# -GI: GROUP -AttValue: CHOICE REQMULT -StartText: \s{{ -EndText: }}\s${_attval REP REPEAT 505} -- -# -GI: GROUP -AttValue: CHOICE PLAIN -EndText: ${_attval REP REPEAT 505} -- -# -GI: SBR -StartText: ^.br^ -- -# -GI: SYNOPFRAGMENT -# nothing special to do here -- just pass through content (Arg | Group)+ -- -# -GI: SYNOPFRAGMENTREF -# WHAT TO DO HERE?? pass through the content, but what about the -# linkend? (will call it across...) -EndText: \s\\fI(refers to: ${_followlink LINKEND 1000})\\fR -- -# -GI: FUNCSYNOPSIS -StartText: ^.PP^.nf^ -EndText: ^.fi^ -- -# -GI: FUNCSYNOPSISINFO -StartText: ^ -EndText: ^ -- -# -GI: FUNCPROTOTYPE -# nothing special -- just pass through content (looks like -# a function def -StartText: ^.sp 1^ -- -# -GI: FUNCDEF -StartText: ^\\fB -EndText: \\fR( -- -# -GI: FUNCPARAMS -StartText: ^\t\t\t\\fB -EndText: \\fR^ -- -# -GI: VOID -StartText: \\fBvoid\\fR); -- -# -GI: VARARGS -StartText: \\fB\\&...\\fR); -- -# -GI: PARAMDEF -Relation: sibling+ PARAMDEF -StartText: ^\\fB -EndText: \\fR,^ -- -# -GI: PARAMDEF -StartText: ^\\fB -EndText: \\fR);^ -- -# -# -############################################################################# -# -# Links -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: LINK -StartText: \\fI -EndText: \\fR -- -# -GI: OLINK -StartText: \\fI -EndText: \s(link to external document ${TargetDocEnt})\s\\fR -- -# -GI: ULINK -StartText: \\fI -EndText: \s(link to URL ${URL})\s\\fR -- -# -GI: FOOTNOTEREF -# just let the footnote ref mark come through -- -# -GI: FOOTNOTE -# just let footnote body come through (-man doesn't support footnotes) -- -# -GI: XREF -AttValue: ENDTERM -StartText: \\fI(cross-reference to ``${_followlink ENDTERM 1000}'')\\fR\s -- -# -GI: XREF -StartText: \\fI(cross-reference to ``${_followlink LINKEND 600})''\\fR\s -- -# -GI: _xref -SpecID: 600 -StartText: ${XREFLABEL} -Ignore: all -- -# -GI: ANCHOR -# nothing to do -- this just marks a place.. -- -# -# -############################################################################# -# -# Graphics and Equations -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: GRAPHIC -AttValue: ENTITYREF -StartText: ^.PP^.if t .P! "${_filename}"^ -- -# -GI: INLINEGRAPHIC -StartText: ^.if t .P! "${_filename}"^ -- -# -GI: INFORMALEQUATION -# nothing special to do -- defer to graphic content.. -- -# -GI: EQUATION -# nothing special to do -- defer to graphic content.. -- -# -GI: TITLE -Context: EQUATION -StartText: ^.PP^\\fB -EndText: \\fR^ -- -# -GI: INLINEEQUATION -# nothing special to do -- defer to graphic content.. -- -# -# -############################################################################# -# -# Tables -# -# #### ##### ##### ##### ##### ##### #### ##### -# -# -GI: INFORMALTABLE -StartText: ^${_calstable tbl tablestart}^ -EndText: ^${_calstable tbl tableend}^ -- -# -GI: TABLE -StartText: ^.PP^\\fB${_followrel child TITLE 1000}\\fR - ^${_calstable tbl tablestart}^ -EndText: ^${_calstable tbl tableend}^ -- -# -GI: TITLE -Context: TABLE -# handled in TABLE element -Ignore: all -- -# -GI: TGROUP -StartText: ^${_calstable tbl tablegroup}^${_followrel child THEAD 700}${_followrel child TBODY 700}${_followrel child TFOOT 701} -EndText: ${_calstable tbl tablegroupend} -- -# -GI: COLSPEC -Ignore: all -- -# -GI: SPANSPEC -Ignore: all -- -# -GI: THEAD TBODY TFOOT -# they're called explicitly from TGROUP, but ignored here -Ignore: all -- -# -GI: _thead_tbody -SpecID: 700 -# nothing special to do -- just pass through content -- -# -GI: _tfoot -SpecID: 701 -StartText: ^${_calstable tbl tablefoot}^ -- -# -GI: ROW -StartText: ^${_calstable tbl rowstart} -EndText: ${_calstable tbl rowend} -- -# -GI: ENTRY -StartText: ${_calstable tbl entrystart} -EndText: ${_calstable tbl entryend} -- -# -GI: ENTRYTBL -StartText: -EndText: -Message: ^IMPLEMENT <${_gi} ${_allatts}>^ -- -# -# -############################################################################# -# -# Index terms -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: INDEXTERM -StartText: ^.iX\s -EndText: ^ -- -# -GI: PRIMARY -StartText: " -EndText: " -- -# -GI: SECONDARY -StartText: \s" -EndText: " -- -# -GI: TERTIARY -StartText: \s" -EndText: " -- -# -GI: SEE -StartText: \s"See:\s -EndText: " -- -# -GI: SEEALSO -StartText: \s"SeeAlso:\s -EndText: " -- -# -# -############################################################################# -# -# Author / OtherCredit material -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: OTHERCREDIT -# nothing specific -- defer to content -- -# -GI: HONORIFIC -# nothing specific -- defer to content -EndText: \s -- -# -GI: FIRSTNAME -# nothing specific -- defer to content -EndText: \s -- -# -GI: SURNAME -# nothing specific -- defer to content -EndText: \s -- -# -GI: LINEAGE -# nothing specific -- defer to content -EndText: \s -- -# -GI: OTHERNAME -# nothing specific -- defer to content -StartText: ( -EndText: )\s -- -# -GI: AFFILIATION -# nothing specific -- defer to content -EndText: \s -- -# -GI: SHORTAFFIL -# nothing specific -- defer to content -EndText: \s -- -# -GI: JOBTITLE -# nothing specific -- defer to content -EndText: \s -- -# -GI: ORGNAME -# nothing specific -- defer to content -EndText: \s -- -# -GI: ORGDIV -# nothing specific -- defer to content -EndText: \s -- -# -GI: CONTRIB -# nothing specific -- defer to content -EndText: \s -- -# -# -############################################################################# -# -# "Leaf" material -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: ABBREV -# no special presentation -- -# -GI: ACCEL -# no special presentation -- -# -GI: ACRONYM -# no special presentation -- -# -GI: AUTHORINITIALS -# no special presentation -- -# -GI: CITATION -StartText: \\fI -EndText: \\fP -- -# -GI: CITETITLE -AttValue: PUBWORK -StartText: \\fI -EndText: \\fP (${PUBWORK})\s -- -# -GI: CITETITLE -StartText: \\fI -EndText: \\fP -- -# -GI: CITEREFENTRY -# defer to content.. -- -# -GI: REFENTRYTITLE -StartText: \\fB -EndText: \\fP -- -# -GI: MANVOLNUM -StartText: \\fB( -EndText: )\\fP -- -# -GI: COMMENT -# docbook says to inhibit this from finished products... -Ignore: all -- -# -GI: EMAIL -# no special presentation -- -# -GI: EMPHASIS -StartText: \\fI -EndText: \\fP -- -# -GI: FIRSTTERM -StartText: \\fI -EndText: \\fR -- -# -GI: FOREIGNPHRASE -# no special presentation -- -# -GI: PHRASE -# no special presentation -- -# -GI: QUOTE -StartText: ``\\fI -EndText: \\fP'' -- -# -GI: TRADEMARK -EndText: \\u\\s-2TM\\s+2\\d -- -# -GI: WORDASWORD -# no special presentation -- -# -GI: ACTION -# no special presentation -- -# -GI: APPLICATION -StartText: \\fB -EndText: \\fP -- -# -GI: CLASSNAME -StartText: \\fB -EndText: \\fP -- -# -GI: COMMAND -StartText: \\fB -EndText: \\fP -- -# -GI: COMPUTEROUTPUT -StartText: \\f(CW -EndText: \\fP -- -# -GI: DATABASE -# no special presentation -- -# -GI: ERRORNAME -StartText: \\fB -EndText: \\fP -- -# -GI: ERRORTYPE -# no special presentation -- -# -GI: FILENAME -StartText: \\fB -EndText: \\fP -- -# -GI: FUNCTION -StartText: \\fB -EndText: \\fP -- -# -GI: GUIBUTTON -StartText: \\fB -EndText: \\fP -- -# -GI: GUIICON -StartText: \\fB -EndText: \\fP -- -# -GI: GUILABEL -# no special presentation -- -# -GI: GUIMENU -# no special presentation -- -# -GI: GUIMENUITEM -# no special presentation -- -# -GI: GUISUBMENU -# no special presentation -- -# -GI: HARDWARE -# no special presentation -- -# -GI: INTERFACE -# no special presentation -- -# -GI: INTERFACEDEFINITION -StartText: \\fB -EndText: \\fP -- -# -GI: KEYCAP -StartText: \\fB< -EndText: >\\fP -- -# -GI: KEYCODE -# no special presentation -- -# -GI: KEYCOMBO -# no special presentation -- defer to the content -- -# -GI: KEYSYM -StartText: \\fB< -EndText: >\\fP -- -# -GI: LINEANNOTATION -StartText: \\fI -EndText: \\fP -- -# -GI: LITERAL -StartText: \\fB -EndText: \\fP -- -# -GI: MARKUP -StartText: \\f(CW -EndText: \\fP -- -# -GI: MEDIALABEL -# no special presentation -- -# -GI: MENUCHOICE -# no special presentation -- -# -GI: SHORTCUT -# no special presentation -- -# -GI: MOUSEBUTTON -# no special presentation -- -# -GI: OPTION -StartText: \\fB -EndText: \\fP -- -# -GI: OPTIONAL -StartText: [ -EndText: ] -- -# -GI: PARAMETER -StartText: \\fB -EndText: \\fR -- -# -GI: PROPERTY -StartText: \\fB -EndText: \\fP -- -# -GI: REPLACEABLE -StartText: \\fI -EndText: \\fP -- -# -GI: RETURNVALUE -StartText: \\fB -EndText: \\fR -- -# -GI: SGMLTAG -AttValue: CLASS ELEMENT -StartText: \\fB< -EndText: >\\fP -- -# -GI: SGMLTAG -StartText: \\fB -EndText: \\fP -- -# -GI: STRUCTFIELD -StartText: \\fB -EndText: \\fR -- -# -GI: STRUCTNAME -StartText: \\fB -EndText: \\fR -- -# -GI: SYMBOL -AttValue: ROLE Variable -StartText: \\fI -EndText: \\fP -- -# -GI: SYMBOL -StartText: \\fI -EndText: \\fP -- -# -GI: SYSTEMITEM -AttValue: CLASS CONSTANT -StartText: \\fB -EndText: \\fP -- -# -GI: SYSTEMITEM -AttValue: CLASS ENVIRONVAR -StartText: \\fB -EndText: \\fP -- -# -GI: SYSTEMITEM -AttValue: CLASS RESOURCE -StartText: \\fB -EndText: \\fP -- -# -GI: SYSTEMITEM -StartText: \\fB -EndText: \\fP -- -# -GI: TOKEN -StartText: \\fB -EndText: \\fP -- -# -GI: TYPE -StartText: \\fB -EndText: \\fP -- -# -GI: USERINPUT -StartText: \\fB -EndText: \\fP -- -# -GI: AUTHOR -# no special presentation - defer to content -- -# -GI: CORPAUTHOR -# no special presentation -- -# -GI: MODESPEC -# nothing to render (this is meta information for Links) -- -# -GI: PRODUCTNAME -StartText: \\fB -EndText: \\fP -- -# -GI: PRODUCTNUMBER -# no special presentation -- -# -GI: SUBSCRIPT -StartText: \\d -EndText: \\u -- -# -GI: SUPERSCRIPT -StartText: \\u -EndText: \\d -- -# -# -############################################################################# -# -# stuff that gets ignored (and doesn't belong elsewhere) -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: TITLEABBREV -# this element is ignored in favor of the real title -Ignore: all -- -# -# -# -############################################################################# -# -# handle layout-specific stuff and PIs -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: BEGINPAGE -StartText: ^.br\s -EndText: ^ -- -# -GI: _x-break -StartText: ^.br\s -EndText: ^ -- -# -GI: _sml-break -StartText: ^.br\s -EndText: ^ -- -# -GI: _sml-need -StartText: ^.ne\s -EndText: ^ -- -# -GI: _sml-size -StartText: ^.ps\s -EndText: ^ -- -# -GI: _sml-indent -StartText: ^.in\s -EndText: ^ -- -# -GI: _sml-space -StartText: ^.sp\s -EndText: ^ -- -# -GI: _sml-tabset -StartText: ^.ta\s -EndText: ^ -- -# -# -############################################################################# -# -# General purpose transpecs -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: _passthrough -SpecID: 1000 -- -# -GI: _passthrough2 -SpecID: 1001 -StartText: ${+caps} -Ignore: all -- -# -GI: _doTitle -SpecID: 1010 -StartText: ^.PP^\\fB -EndText: \\fR^.PP^ -- -# -# -############################################################################# -# -# Catch-all for unknown PIs -- ignore them... -# -# #### ##### ##### ##### ##### ##### #### ##### -# -GI: _* -Ignore: data -- -# -# -############################################################################# -# -# Catch-all for unknown elements -- just output their content.. -# -# #### ##### ##### ##### ##### ##### #### ##### -# -#GI: * -#- -# diff --git a/gtk-doc.cat.in b/gtk-doc.cat.in deleted file mode 100644 index d900724..0000000 --- a/gtk-doc.cat.in +++ /dev/null @@ -1,6 +0,0 @@ - -- ...................................................................... -- - -- DSSL stylesheet ...................................................... -- - -- ...................................................................... -- - -PUBLIC "-//Gtk//DOCUMENT Gtk-doc HTML Stylesheet//EN" - "@PACKAGE_DATA_DIR@/gtk-doc.dsl" diff --git a/gtk-doc.dcl b/gtk-doc.dcl deleted file mode 100755 index 9cc44ed..0000000 --- a/gtk-doc.dcl +++ /dev/null @@ -1,106 +0,0 @@ - diff --git a/gtk-doc.doap b/gtk-doc.doap index f44baab..b34b2af 100644 --- a/gtk-doc.doap +++ b/gtk-doc.doap @@ -6,11 +6,12 @@ gtk-doc - GTK-Doc is used to document C code. + Documentation generator for C code. + GTK-Doc is used to document C code. It is typically used to document the public API of libraries, such as the GTK+ and GNOME libraries, but it can also be used to document application code. - + @@ -23,24 +24,11 @@ used to document application code. - Stefan Kost + Stefan Sauer stefkost - - - Damon Chaplin - damon - - - - - Owen Taylor - - otaylor - - Matthias Clasen diff --git a/gtk-doc.dsl b/gtk-doc.dsl deleted file mode 100644 index c33ada8..0000000 --- a/gtk-doc.dsl +++ /dev/null @@ -1,464 +0,0 @@ - -]> - - - - - -(define gtkdoc-version "") -(define gtkdoc-bookname "") - -;; These are some customizations to the standard HTML output produced by the -;; Modular DocBook Stylesheets. -;; I've copied parts of a few functions from the stylesheets so these should -;; be checked occasionally to ensure they are up to date. -;; -;; The last check was with version 1.40 of the stylesheets. -;; It will not work with versions < 1.19 since the $shade-verbatim-attr$ -;; function was added then. Versions 1.19 to 1.39 may be OK, if you're lucky! - -;;(define %generate-book-toc% #f) - -;; If a Chapter has role="no-toc" we don't generate a table of contents. -;; This is useful if a better contents page has been added manually, e.g. for -;; the GTK+ Widgets & Objects page. (But it is a bit of a hack.) -(define ($generate-chapter-toc$) - (not (equal? (attribute-string (normalize "role") (current-node)) "no-toc"))) - -(define %chapter-autolabel% - ;; Are chapters enumerated? - #f) - -(define %use-id-as-filename% #t) - -(define %html-ext% ".html") - -(define ($user-html-header$ #!optional - (home (empty-node-list)) - (up (empty-node-list)) - (prev (empty-node-list)) - (next (empty-node-list))) - (make sequence - (if (not (string=? gtkdoc-version "")) - (make empty-element gi: "META" - attributes: (list - (list "NAME" "GENERATOR") - (list "CONTENT" (string-append - "GTK-Doc V" - gtkdoc-version - " (SGML mode)")))) - (empty-sosofo)) - (make element gi: "STYLE" - attributes: (list (list "TYPE" "text/css")) - (literal ".synopsis, .classsynopsis { - background: #eeeeee; - border: solid 1px #aaaaaa; - padding: 0.5em; -} -.programlisting { - background: #eeeeff; - border: solid 1px #aaaaff; - padding: 0.5em; -} -.variablelist { - padding: 4px; - margin-left: 3em; -} -.navigation { - background: #ffeeee; - border: solid 1px #ffaaaa; - margin-top: 0.5em; - margin-bottom: 0.5em; -} -.navigation a { - color: #770000; -} -.navigation a:visited { - color: #550000; -} -.navigation .title { - font-size: 200%; -}")))) - - -(mode book-titlepage-recto-mode - (element title - (make element gi: "TABLE" - attributes: (list - (list "CLASS" "navigation") - (list "WIDTH" %gentext-nav-tblwidth%) - (list "CELLPADDING" "2") - (list "CELLSPACING" "0")) - (make element gi: "TR" - (make element gi: "TH" - attributes: (list - (list "ALIGN" "center") - (list "VALIGN" "MIDDLE")) - (make element gi: "P" - attributes: (list (list "CLASS" (gi))) - (process-children-trim) - (make empty-element gi: "A" - attributes: (list (list "NAME" (element-id)))))))))) - -(define (book-titlepage-separator side) - (empty-sosofo)) - - -;; This overrides the variablelist definition (copied from 1.76, -;; dblists.dsl). It changes the table background color, cell spacing -;; and cell padding. -;; -;; I have also removed the code to handle the non-table case. -(element variablelist - (make sequence - (if %spacing-paras% - (make element gi: "P" (empty-sosofo)) - (empty-sosofo)) - (para-check) - - (make element gi: "TABLE" - attributes: '(("CLASS" "variablelist") - ("BORDER" "0") - ("CELLSPACING" "0") - ("CELLPADDING" "4")) - (if %html40% - (make element gi: "TBODY" - (with-mode variablelist-table - (process-children))) - (with-mode variablelist-table - (process-children)))) - (para-check 'restart))) - -(mode variablelist-table - (element (variablelist title) - (make element gi: "TR" - attributes: '(("CLASS" "TITLE")) - (make element gi: "TH" - attributes: '(("ALIGN" "LEFT") - ("VALIGN" "TOP") - ("COLSPAN" "2")) - (process-children)))) - - (element varlistentry - (let* ((terms (select-elements (children (current-node)) - (normalize "term"))) - (listitem (select-elements (children (current-node)) - (normalize "listitem")))) - - (make element gi: "TR" - (make element gi: "TD" - attributes: '(("ALIGN" "LEFT") - ("VALIGN" "TOP")) - (make empty-element gi: "A" - attributes: (list - (list "NAME" (element-id)))) - (process-node-list terms)) - (make element gi: "TD" - attributes: '(("ALIGN" "LEFT") - ("VALIGN" "TOP")) - (process-node-list listitem))))) - - (element (varlistentry term) - (make sequence - (if %css-decoration% - (make element gi: "SPAN" - attributes: '(("STYLE" "white-space: nowrap")) - (process-children-trim)) - (make element gi: "NOBR" - (process-children-trim))) - (if (not (last-sibling?)) - (literal ", ") - (literal "")))) - - (element (varlistentry listitem) - (process-children)) -) - - -;; This overrides the refsect2 definition (copied from 1.20, dbrfntry.dsl). -;; It puts a horizontal rule before each function/struct/... description, -;; except the first one in the refsect1. -(element refsect2 - (make sequence - (if (first-sibling?) - (empty-sosofo) - (make empty-element gi: "HR")) - ($block-container$))) - -;; Override the book declaration, so that we generate a crossreference -;; for the book - -(element book - (let* ((bookinfo (select-elements (children (current-node)) (normalize "bookinfo"))) - (ititle (select-elements (children bookinfo) (normalize "title"))) - (title (if (node-list-empty? ititle) - (select-elements (children (current-node)) (normalize "title")) - (node-list-first ititle))) - (nl (titlepage-info-elements (current-node) bookinfo)) - (tsosofo (with-mode head-title-mode - (process-node-list title))) - (dedication (select-elements (children (current-node)) (normalize "dedication")))) - (make sequence - (html-document - tsosofo - (make element gi: "DIV" - attributes: '(("CLASS" "BOOK")) - (if %generate-book-titlepage% - (make sequence - (book-titlepage nl 'recto) - (book-titlepage nl 'verso)) - (empty-sosofo)) - - (if (node-list-empty? dedication) - (empty-sosofo) - (with-mode dedication-page-mode - (process-node-list dedication))) - - (if (not (generate-toc-in-front)) - (process-children) - (empty-sosofo)) - - (if %generate-book-toc% - (build-toc (current-node) (toc-depth (current-node))) - (empty-sosofo)) - - ;; (let loop ((gilist %generate-book-lot-list%)) - ;; (if (null? gilist) - ;; (empty-sosofo) - ;; (if (not (node-list-empty? - ;; (select-elements (descendants (current-node)) - ;; (car gilist)))) - ;; (make sequence - ;; (build-lot (current-node) (car gilist)) - ;; (loop (cdr gilist))) - ;; (loop (cdr gilist))))) - - (if (generate-toc-in-front) - (process-children) - (empty-sosofo)))) - (make entity - system-id: "index.sgml" - (with-mode generate-index-mode - (process-children)))))) - -;; Mode for generating cross references - -(define (process-child-elements) - (process-node-list - (node-list-map (lambda (snl) - (if (equal? (node-property 'class-name snl) 'element) - snl - (empty-node-list))) - (children (current-node))))) - -(mode generate-index-mode - (element anchor - (if (attribute-string "href" (current-node)) - (empty-sosofo) - (make formatting-instruction data: - (string-append "\less-than-sign;ANCHOR id =\"" - (attribute-string "id" (current-node)) - "\" href=\"" - (if (not (string=? gtkdoc-bookname "")) - (string-append gtkdoc-bookname "/") - "") - (href-to (current-node)) - "\"\greater-than-sign; -")))) - - ;; We also want to be able to link to complete RefEntry. - (element refentry - (make sequence - (make formatting-instruction data: - (string-append "\less-than-sign;ANCHOR id =\"" - (attribute-string "id" (current-node)) - "\" href=\"" - (if (not (string=? gtkdoc-bookname "")) - (string-append gtkdoc-bookname "/") - "") - (href-to (current-node)) - "\"\greater-than-sign; -")) - (process-child-elements))) - - (default - (process-child-elements))) - -;; For hypertext links for which no target is found in the document, we output -;; our own special tag which we use later to resolve cross-document links. -(element link - (let* ((target (element-with-id (attribute-string (normalize "linkend"))))) - (if (node-list-empty? target) - (make element gi: "GTKDOCLINK" - attributes: (list - (list "HREF" (attribute-string (normalize "linkend")))) - (process-children)) - (make element gi: "A" - attributes: (list - (list "HREF" (href-to target))) - (process-children))))) - - -;; This overrides default-header-nav-tbl-noff (copied from 1.20, dbnavig.dsl). -;; I want 'Home' and 'Up' links at the top of each page, and white text on -;; black. -(define (default-header-nav-tbl-noff elemnode prev next prevsib nextsib) - (let* ((up (parent elemnode)) - (home (nav-home elemnode)) - (show-title? (nav-banner? elemnode)) - (title-sosofo - (make element gi: "TH" - attributes: (list - (list "WIDTH" "100%") - (list "align" "center")) - (if show-title? - (nav-banner elemnode) - (empty-sosofo)))) - (show-banner? (or show-title? - (not (node-list-empty? prev)) - (not (node-list-empty? next)) - (nav-context? elemnode))) - (banner-sosofo - (make element gi: "TR" - attributes: (list - (list "VALIGN" "middle")) - (if (not (node-list-empty? prev)) - (make element gi: "TD" - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "p") - (list "HREF" - (href-to prev))) - (make empty-element gi: "IMG" - attributes: (list - (list "SRC" "left.png") - (list "WIDTH" "16") - (list "HEIGHT" "16") - (list "BORDER" "0") - (list "ALT" "Prev"))))) - (empty-sosofo)) - (if (nav-up? elemnode) - (make element gi: "TD" - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "u") - (list "HREF" - (href-to up))) - (make empty-element gi: "IMG" - attributes: (list - (list "SRC" "up.png") - (list "WIDTH" "16") - (list "HEIGHT" "16") - (list "BORDER" "0") - (list "ALT" "Up"))))) - (empty-sosofo)) - (if (nav-home? elemnode) - (make element gi: "TD" - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "h") - (list "HREF" - (href-to home))) - (make empty-element gi: "IMG" - attributes: (list - (list "SRC" "home.png") - (list "WIDTH" "16") - (list "HEIGHT" "16") - (list "BORDER" "0") - (list "ALT" "Home"))))) - (empty-sosofo)) - title-sosofo - (if (not (node-list-empty? next)) - (make element gi: "TD" - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "n") - (list "HREF" - (href-to next))) - (make empty-element gi: "IMG" - attributes: (list - (list "SRC" "right.png") - (list "WIDTH" "16") - (list "HEIGHT" "16") - (list "BORDER" "0") - (list "ALT" "Next"))))) - (empty-sosofo))))) - - (if show-banner? - (make element gi: "TABLE" - attributes: (list - (list "WIDTH" %gentext-nav-tblwidth%) - (list "CLASS" "navigation") - (list "SUMMARY" "Navigation header") - (list "CELLPADDING" "2") - (list "CELLSPACING" "2")) - banner-sosofo) - (empty-sosofo)))) - -;; This overrides default-footer-nav-tbl (copied from 1.20, dbnavig.dsl). -;; It matches the header above. -(define (default-footer-nav-tbl elemnode prev next prevsib nextsib) - (let* ((show-footer? (or (not (node-list-empty? prev)) - (not (node-list-empty? next)))) - (footer-sosofo - (make element gi: "TR" - attributes: (list - (list "VALIGN" "middle")) - (make element gi: "TD" - attributes: (list - (list "ALIGN" "left")) - (if (not (node-list-empty? prev)) - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "p") - (list "HREF" (href-to prev))) - (make element gi: "B" - (make entity-ref name: "lt") - (make entity-ref name: "lt") - (make entity-ref name: "lt") - (make entity-ref name: "nbsp") - (element-title-sosofo prev))) - (empty-sosofo))) - (make element gi: "TD" - attributes: (list - (list "ALIGN" "right")) - (if (not (node-list-empty? next)) - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "n") - (list "HREF" (href-to next))) - (make element gi: "B" - (element-title-sosofo next) - (make entity-ref name: "nbsp") - (make entity-ref name: "gt") - (make entity-ref name: "gt") - (make entity-ref name: "gt"))) - (empty-sosofo)))))) - - (if show-footer? - (make element gi: "TABLE" - attributes: (list - (list "CLASS" "navigation") - (list "WIDTH" %gentext-nav-tblwidth%) - (list "SUMMARY" "Navigation footer") - (list "CELLPADDING" "2") - (list "CELLSPACING" "2")) - footer-sosofo) - (empty-sosofo)))) - - -(define ($section-body$) - (make sequence - (make empty-element gi: "BR" - attributes: (list (list "CLEAR" "all"))) - (make element gi: "DIV" - attributes: (list (list "CLASS" (gi))) - ($section-separator$) - ($section-title$) - (process-children)))) - - - - - diff --git a/gtk-doc.dsl.in b/gtk-doc.dsl.in deleted file mode 100644 index c33ada8..0000000 --- a/gtk-doc.dsl.in +++ /dev/null @@ -1,464 +0,0 @@ - -]> - - - - - -(define gtkdoc-version "") -(define gtkdoc-bookname "") - -;; These are some customizations to the standard HTML output produced by the -;; Modular DocBook Stylesheets. -;; I've copied parts of a few functions from the stylesheets so these should -;; be checked occasionally to ensure they are up to date. -;; -;; The last check was with version 1.40 of the stylesheets. -;; It will not work with versions < 1.19 since the $shade-verbatim-attr$ -;; function was added then. Versions 1.19 to 1.39 may be OK, if you're lucky! - -;;(define %generate-book-toc% #f) - -;; If a Chapter has role="no-toc" we don't generate a table of contents. -;; This is useful if a better contents page has been added manually, e.g. for -;; the GTK+ Widgets & Objects page. (But it is a bit of a hack.) -(define ($generate-chapter-toc$) - (not (equal? (attribute-string (normalize "role") (current-node)) "no-toc"))) - -(define %chapter-autolabel% - ;; Are chapters enumerated? - #f) - -(define %use-id-as-filename% #t) - -(define %html-ext% ".html") - -(define ($user-html-header$ #!optional - (home (empty-node-list)) - (up (empty-node-list)) - (prev (empty-node-list)) - (next (empty-node-list))) - (make sequence - (if (not (string=? gtkdoc-version "")) - (make empty-element gi: "META" - attributes: (list - (list "NAME" "GENERATOR") - (list "CONTENT" (string-append - "GTK-Doc V" - gtkdoc-version - " (SGML mode)")))) - (empty-sosofo)) - (make element gi: "STYLE" - attributes: (list (list "TYPE" "text/css")) - (literal ".synopsis, .classsynopsis { - background: #eeeeee; - border: solid 1px #aaaaaa; - padding: 0.5em; -} -.programlisting { - background: #eeeeff; - border: solid 1px #aaaaff; - padding: 0.5em; -} -.variablelist { - padding: 4px; - margin-left: 3em; -} -.navigation { - background: #ffeeee; - border: solid 1px #ffaaaa; - margin-top: 0.5em; - margin-bottom: 0.5em; -} -.navigation a { - color: #770000; -} -.navigation a:visited { - color: #550000; -} -.navigation .title { - font-size: 200%; -}")))) - - -(mode book-titlepage-recto-mode - (element title - (make element gi: "TABLE" - attributes: (list - (list "CLASS" "navigation") - (list "WIDTH" %gentext-nav-tblwidth%) - (list "CELLPADDING" "2") - (list "CELLSPACING" "0")) - (make element gi: "TR" - (make element gi: "TH" - attributes: (list - (list "ALIGN" "center") - (list "VALIGN" "MIDDLE")) - (make element gi: "P" - attributes: (list (list "CLASS" (gi))) - (process-children-trim) - (make empty-element gi: "A" - attributes: (list (list "NAME" (element-id)))))))))) - -(define (book-titlepage-separator side) - (empty-sosofo)) - - -;; This overrides the variablelist definition (copied from 1.76, -;; dblists.dsl). It changes the table background color, cell spacing -;; and cell padding. -;; -;; I have also removed the code to handle the non-table case. -(element variablelist - (make sequence - (if %spacing-paras% - (make element gi: "P" (empty-sosofo)) - (empty-sosofo)) - (para-check) - - (make element gi: "TABLE" - attributes: '(("CLASS" "variablelist") - ("BORDER" "0") - ("CELLSPACING" "0") - ("CELLPADDING" "4")) - (if %html40% - (make element gi: "TBODY" - (with-mode variablelist-table - (process-children))) - (with-mode variablelist-table - (process-children)))) - (para-check 'restart))) - -(mode variablelist-table - (element (variablelist title) - (make element gi: "TR" - attributes: '(("CLASS" "TITLE")) - (make element gi: "TH" - attributes: '(("ALIGN" "LEFT") - ("VALIGN" "TOP") - ("COLSPAN" "2")) - (process-children)))) - - (element varlistentry - (let* ((terms (select-elements (children (current-node)) - (normalize "term"))) - (listitem (select-elements (children (current-node)) - (normalize "listitem")))) - - (make element gi: "TR" - (make element gi: "TD" - attributes: '(("ALIGN" "LEFT") - ("VALIGN" "TOP")) - (make empty-element gi: "A" - attributes: (list - (list "NAME" (element-id)))) - (process-node-list terms)) - (make element gi: "TD" - attributes: '(("ALIGN" "LEFT") - ("VALIGN" "TOP")) - (process-node-list listitem))))) - - (element (varlistentry term) - (make sequence - (if %css-decoration% - (make element gi: "SPAN" - attributes: '(("STYLE" "white-space: nowrap")) - (process-children-trim)) - (make element gi: "NOBR" - (process-children-trim))) - (if (not (last-sibling?)) - (literal ", ") - (literal "")))) - - (element (varlistentry listitem) - (process-children)) -) - - -;; This overrides the refsect2 definition (copied from 1.20, dbrfntry.dsl). -;; It puts a horizontal rule before each function/struct/... description, -;; except the first one in the refsect1. -(element refsect2 - (make sequence - (if (first-sibling?) - (empty-sosofo) - (make empty-element gi: "HR")) - ($block-container$))) - -;; Override the book declaration, so that we generate a crossreference -;; for the book - -(element book - (let* ((bookinfo (select-elements (children (current-node)) (normalize "bookinfo"))) - (ititle (select-elements (children bookinfo) (normalize "title"))) - (title (if (node-list-empty? ititle) - (select-elements (children (current-node)) (normalize "title")) - (node-list-first ititle))) - (nl (titlepage-info-elements (current-node) bookinfo)) - (tsosofo (with-mode head-title-mode - (process-node-list title))) - (dedication (select-elements (children (current-node)) (normalize "dedication")))) - (make sequence - (html-document - tsosofo - (make element gi: "DIV" - attributes: '(("CLASS" "BOOK")) - (if %generate-book-titlepage% - (make sequence - (book-titlepage nl 'recto) - (book-titlepage nl 'verso)) - (empty-sosofo)) - - (if (node-list-empty? dedication) - (empty-sosofo) - (with-mode dedication-page-mode - (process-node-list dedication))) - - (if (not (generate-toc-in-front)) - (process-children) - (empty-sosofo)) - - (if %generate-book-toc% - (build-toc (current-node) (toc-depth (current-node))) - (empty-sosofo)) - - ;; (let loop ((gilist %generate-book-lot-list%)) - ;; (if (null? gilist) - ;; (empty-sosofo) - ;; (if (not (node-list-empty? - ;; (select-elements (descendants (current-node)) - ;; (car gilist)))) - ;; (make sequence - ;; (build-lot (current-node) (car gilist)) - ;; (loop (cdr gilist))) - ;; (loop (cdr gilist))))) - - (if (generate-toc-in-front) - (process-children) - (empty-sosofo)))) - (make entity - system-id: "index.sgml" - (with-mode generate-index-mode - (process-children)))))) - -;; Mode for generating cross references - -(define (process-child-elements) - (process-node-list - (node-list-map (lambda (snl) - (if (equal? (node-property 'class-name snl) 'element) - snl - (empty-node-list))) - (children (current-node))))) - -(mode generate-index-mode - (element anchor - (if (attribute-string "href" (current-node)) - (empty-sosofo) - (make formatting-instruction data: - (string-append "\less-than-sign;ANCHOR id =\"" - (attribute-string "id" (current-node)) - "\" href=\"" - (if (not (string=? gtkdoc-bookname "")) - (string-append gtkdoc-bookname "/") - "") - (href-to (current-node)) - "\"\greater-than-sign; -")))) - - ;; We also want to be able to link to complete RefEntry. - (element refentry - (make sequence - (make formatting-instruction data: - (string-append "\less-than-sign;ANCHOR id =\"" - (attribute-string "id" (current-node)) - "\" href=\"" - (if (not (string=? gtkdoc-bookname "")) - (string-append gtkdoc-bookname "/") - "") - (href-to (current-node)) - "\"\greater-than-sign; -")) - (process-child-elements))) - - (default - (process-child-elements))) - -;; For hypertext links for which no target is found in the document, we output -;; our own special tag which we use later to resolve cross-document links. -(element link - (let* ((target (element-with-id (attribute-string (normalize "linkend"))))) - (if (node-list-empty? target) - (make element gi: "GTKDOCLINK" - attributes: (list - (list "HREF" (attribute-string (normalize "linkend")))) - (process-children)) - (make element gi: "A" - attributes: (list - (list "HREF" (href-to target))) - (process-children))))) - - -;; This overrides default-header-nav-tbl-noff (copied from 1.20, dbnavig.dsl). -;; I want 'Home' and 'Up' links at the top of each page, and white text on -;; black. -(define (default-header-nav-tbl-noff elemnode prev next prevsib nextsib) - (let* ((up (parent elemnode)) - (home (nav-home elemnode)) - (show-title? (nav-banner? elemnode)) - (title-sosofo - (make element gi: "TH" - attributes: (list - (list "WIDTH" "100%") - (list "align" "center")) - (if show-title? - (nav-banner elemnode) - (empty-sosofo)))) - (show-banner? (or show-title? - (not (node-list-empty? prev)) - (not (node-list-empty? next)) - (nav-context? elemnode))) - (banner-sosofo - (make element gi: "TR" - attributes: (list - (list "VALIGN" "middle")) - (if (not (node-list-empty? prev)) - (make element gi: "TD" - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "p") - (list "HREF" - (href-to prev))) - (make empty-element gi: "IMG" - attributes: (list - (list "SRC" "left.png") - (list "WIDTH" "16") - (list "HEIGHT" "16") - (list "BORDER" "0") - (list "ALT" "Prev"))))) - (empty-sosofo)) - (if (nav-up? elemnode) - (make element gi: "TD" - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "u") - (list "HREF" - (href-to up))) - (make empty-element gi: "IMG" - attributes: (list - (list "SRC" "up.png") - (list "WIDTH" "16") - (list "HEIGHT" "16") - (list "BORDER" "0") - (list "ALT" "Up"))))) - (empty-sosofo)) - (if (nav-home? elemnode) - (make element gi: "TD" - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "h") - (list "HREF" - (href-to home))) - (make empty-element gi: "IMG" - attributes: (list - (list "SRC" "home.png") - (list "WIDTH" "16") - (list "HEIGHT" "16") - (list "BORDER" "0") - (list "ALT" "Home"))))) - (empty-sosofo)) - title-sosofo - (if (not (node-list-empty? next)) - (make element gi: "TD" - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "n") - (list "HREF" - (href-to next))) - (make empty-element gi: "IMG" - attributes: (list - (list "SRC" "right.png") - (list "WIDTH" "16") - (list "HEIGHT" "16") - (list "BORDER" "0") - (list "ALT" "Next"))))) - (empty-sosofo))))) - - (if show-banner? - (make element gi: "TABLE" - attributes: (list - (list "WIDTH" %gentext-nav-tblwidth%) - (list "CLASS" "navigation") - (list "SUMMARY" "Navigation header") - (list "CELLPADDING" "2") - (list "CELLSPACING" "2")) - banner-sosofo) - (empty-sosofo)))) - -;; This overrides default-footer-nav-tbl (copied from 1.20, dbnavig.dsl). -;; It matches the header above. -(define (default-footer-nav-tbl elemnode prev next prevsib nextsib) - (let* ((show-footer? (or (not (node-list-empty? prev)) - (not (node-list-empty? next)))) - (footer-sosofo - (make element gi: "TR" - attributes: (list - (list "VALIGN" "middle")) - (make element gi: "TD" - attributes: (list - (list "ALIGN" "left")) - (if (not (node-list-empty? prev)) - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "p") - (list "HREF" (href-to prev))) - (make element gi: "B" - (make entity-ref name: "lt") - (make entity-ref name: "lt") - (make entity-ref name: "lt") - (make entity-ref name: "nbsp") - (element-title-sosofo prev))) - (empty-sosofo))) - (make element gi: "TD" - attributes: (list - (list "ALIGN" "right")) - (if (not (node-list-empty? next)) - (make element gi: "A" - attributes: (list - (list "ACCESSKEY" "n") - (list "HREF" (href-to next))) - (make element gi: "B" - (element-title-sosofo next) - (make entity-ref name: "nbsp") - (make entity-ref name: "gt") - (make entity-ref name: "gt") - (make entity-ref name: "gt"))) - (empty-sosofo)))))) - - (if show-footer? - (make element gi: "TABLE" - attributes: (list - (list "CLASS" "navigation") - (list "WIDTH" %gentext-nav-tblwidth%) - (list "SUMMARY" "Navigation footer") - (list "CELLPADDING" "2") - (list "CELLSPACING" "2")) - footer-sosofo) - (empty-sosofo)))) - - -(define ($section-body$) - (make sequence - (make empty-element gi: "BR" - attributes: (list (list "CLEAR" "all"))) - (make element gi: "DIV" - attributes: (list (list "CLASS" (gi))) - ($section-separator$) - ($section-title$) - (process-children)))) - - - - - diff --git a/gtk-doc.flat.make b/gtk-doc.flat.make index 7114b06..0f23900 100644 --- a/gtk-doc.flat.make +++ b/gtk-doc.flat.make @@ -34,9 +34,9 @@ EXTRA_DIST += \ $(HTML_IMAGES) \ $(SETUP_FILES) -DOC_STAMPS=setup-build.stamp scan-build.stamp tmpl-build.stamp sgml-build.stamp \ +DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \ html-build.stamp pdf-build.stamp \ - tmpl.stamp sgml.stamp html.stamp pdf.stamp + sgml.stamp html.stamp pdf.stamp SCANOBJ_FILES = \ $(DOC_MODULE).args \ @@ -81,94 +81,70 @@ $(REPORT_FILES): sgml-build.stamp #### setup #### -GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_$(V)) -GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_@AM_V@) +GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_@AM_DEFAULT_V@) GTK_DOC_V_SETUP_0=@echo " DOC Preparing build"; setup-build.stamp: -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \ - if test "x$$files" != "x" ; then \ - for file in $$files ; do \ - destdir=`dirname $(abs_builddir)/$$file` ;\ - test -d "$$destdir" || mkdir -p "$$destdir"; \ - test -f $(abs_srcdir)/$$file && \ - cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \ - done; \ - fi; \ - test -d $(abs_srcdir)/tmpl && \ - { cp -pR $(abs_srcdir)/tmpl $(abs_builddir)/; \ - chmod -R u+w $(abs_builddir)/tmpl; } \ + files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \ + if test "x$$files" != "x" ; then \ + for file in $$files ; do \ + destdir=`dirname $(abs_builddir)/$$file`; \ + test -d "$$destdir" || mkdir -p "$$destdir"; \ + test -f $(abs_srcdir)/$$file && \ + cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \ + done; \ + fi; \ fi $(AM_V_at)touch setup-build.stamp #### scan #### -GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_$(V)) -GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_@AM_V@) +GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_@AM_DEFAULT_V@) GTK_DOC_V_SCAN_0=@echo " DOC Scanning header files"; -GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_$(V)) -GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_@AM_V@) +GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_@AM_DEFAULT_V@) GTK_DOC_V_INTROSPECT_0=@echo " DOC Introspecting gobjects"; scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) $(GTK_DOC_V_SCAN)_source_dir='' ; \ for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) $(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ - scanobj_options=""; \ - gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \ - if test "$$?" = "0"; then \ - if test "x$(V)" = "x1"; then \ - scanobj_options="--verbose"; \ - fi; \ + scanobj_options=""; \ + gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \ + if test "$$?" = "0"; then \ + if test "x$(V)" = "x1"; then \ + scanobj_options="--verbose"; \ fi; \ - CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ - gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \ + fi; \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ + gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \ else \ - for i in $(SCANOBJ_FILES) ; do \ - test -f $$i || touch $$i ; \ - done \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ fi $(AM_V_at)touch scan-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp @true -#### templates #### - -GTK_DOC_V_TMPL=$(GTK_DOC_V_TMPL_$(V)) -GTK_DOC_V_TMPL_=$(GTK_DOC_V_TMPL_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_TMPL_0=@echo " DOC Rebuilding template files"; - -tmpl-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt - $(GTK_DOC_V_TMPL)gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS) - $(AM_V_at)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - if test -w $(abs_srcdir) ; then \ - cp -pR $(abs_builddir)/tmpl $(abs_srcdir)/; \ - fi \ - fi - $(AM_V_at)touch tmpl-build.stamp - -tmpl.stamp: tmpl-build.stamp - @true - -$(srcdir)/tmpl/*.sgml: - @true - #### xml #### -GTK_DOC_V_XML=$(GTK_DOC_V_XML_$(V)) -GTK_DOC_V_XML_=$(GTK_DOC_V_XML_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_XML=$(GTK_DOC_V_XML_@AM_V@) +GTK_DOC_V_XML_=$(GTK_DOC_V_XML_@AM_DEFAULT_V@) GTK_DOC_V_XML_0=@echo " DOC Building XML"; -sgml-build.stamp: tmpl.stamp $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files) xml/gtkdocentities.ent - -$(GTK_DOC_V_XML)chmod -R u+w $(srcdir) && _source_dir='' ; \ +sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent + $(GTK_DOC_V_XML)_source_dir='' ; \ for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) $(AM_V_at)touch sgml-build.stamp @@ -189,12 +165,12 @@ xml/gtkdocentities.ent: Makefile #### html #### -GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_$(V)) -GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_@AM_V@) +GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_@AM_DEFAULT_V@) GTK_DOC_V_HTML_0=@echo " DOC Building HTML"; -GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_$(V)) -GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_@AM_V@) +GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_@AM_DEFAULT_V@) GTK_DOC_V_XREF_0=@echo " DOC Fixing cross-references"; html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) @@ -213,20 +189,16 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_con cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) -@test "x$(HTML_IMAGES)" = "x" || \ for file in $(HTML_IMAGES) ; do \ - if test -f $(abs_srcdir)/$$file ; then \ - cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ - fi; \ - if test -f $(abs_builddir)/$$file ; then \ - cp $(abs_builddir)/$$file $(abs_builddir)/html; \ - fi; \ + test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ + test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$file $(abs_builddir)/html; \ done; $(GTK_DOC_V_XREF)gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) $(AM_V_at)touch html-build.stamp #### pdf #### -GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_$(V)) -GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_@AM_V@) +GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_@AM_DEFAULT_V@) GTK_DOC_V_PDF_0=@echo " DOC Building PDF"; pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) @@ -267,7 +239,6 @@ distclean-local: $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ rm -f $(SETUP_FILES) $(DOC_MODULE).types; \ - rm -rf tmpl; \ fi maintainer-clean-local: @@ -317,9 +288,7 @@ dist-check-gtkdoc: endif dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local - @mkdir $(distdir)/tmpl @mkdir $(distdir)/html - @-cp ./tmpl/*.sgml $(distdir)/tmpl @cp ./html/* $(distdir)/html @-cp ./$(DOC_MODULE).pdf $(distdir)/ @-cp ./$(DOC_MODULE).types $(distdir)/ diff --git a/gtk-doc.make b/gtk-doc.make index d7c5fea..e5777b6 100644 --- a/gtk-doc.make +++ b/gtk-doc.make @@ -34,9 +34,9 @@ EXTRA_DIST = \ $(HTML_IMAGES) \ $(SETUP_FILES) -DOC_STAMPS=setup-build.stamp scan-build.stamp tmpl-build.stamp sgml-build.stamp \ +DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \ html-build.stamp pdf-build.stamp \ - tmpl.stamp sgml.stamp html.stamp pdf.stamp + sgml.stamp html.stamp pdf.stamp SCANOBJ_FILES = \ $(DOC_MODULE).args \ @@ -81,94 +81,70 @@ $(REPORT_FILES): sgml-build.stamp #### setup #### -GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_$(V)) -GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_@AM_V@) +GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_@AM_DEFAULT_V@) GTK_DOC_V_SETUP_0=@echo " DOC Preparing build"; setup-build.stamp: -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \ - if test "x$$files" != "x" ; then \ - for file in $$files ; do \ - destdir=`dirname $(abs_builddir)/$$file` ;\ - test -d "$$destdir" || mkdir -p "$$destdir"; \ - test -f $(abs_srcdir)/$$file && \ - cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \ - done; \ - fi; \ - test -d $(abs_srcdir)/tmpl && \ - { cp -pR $(abs_srcdir)/tmpl $(abs_builddir)/; \ - chmod -R u+w $(abs_builddir)/tmpl; } \ + files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \ + if test "x$$files" != "x" ; then \ + for file in $$files ; do \ + destdir=`dirname $(abs_builddir)/$$file`; \ + test -d "$$destdir" || mkdir -p "$$destdir"; \ + test -f $(abs_srcdir)/$$file && \ + cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \ + done; \ + fi; \ fi $(AM_V_at)touch setup-build.stamp #### scan #### -GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_$(V)) -GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_@AM_V@) +GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_@AM_DEFAULT_V@) GTK_DOC_V_SCAN_0=@echo " DOC Scanning header files"; -GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_$(V)) -GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_@AM_V@) +GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_@AM_DEFAULT_V@) GTK_DOC_V_INTROSPECT_0=@echo " DOC Introspecting gobjects"; scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) $(GTK_DOC_V_SCAN)_source_dir='' ; \ for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) $(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ - scanobj_options=""; \ - gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \ - if test "$$?" = "0"; then \ - if test "x$(V)" = "x1"; then \ - scanobj_options="--verbose"; \ - fi; \ + scanobj_options=""; \ + gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \ + if test "$$?" = "0"; then \ + if test "x$(V)" = "x1"; then \ + scanobj_options="--verbose"; \ fi; \ - CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ - gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \ + fi; \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ + gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \ else \ - for i in $(SCANOBJ_FILES) ; do \ - test -f $$i || touch $$i ; \ - done \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ fi $(AM_V_at)touch scan-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp @true -#### templates #### - -GTK_DOC_V_TMPL=$(GTK_DOC_V_TMPL_$(V)) -GTK_DOC_V_TMPL_=$(GTK_DOC_V_TMPL_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_TMPL_0=@echo " DOC Rebuilding template files"; - -tmpl-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt - $(GTK_DOC_V_TMPL)gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS) - $(AM_V_at)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - if test -w $(abs_srcdir) ; then \ - cp -pR $(abs_builddir)/tmpl $(abs_srcdir)/; \ - fi \ - fi - $(AM_V_at)touch tmpl-build.stamp - -tmpl.stamp: tmpl-build.stamp - @true - -$(srcdir)/tmpl/*.sgml: - @true - #### xml #### -GTK_DOC_V_XML=$(GTK_DOC_V_XML_$(V)) -GTK_DOC_V_XML_=$(GTK_DOC_V_XML_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_XML=$(GTK_DOC_V_XML_@AM_V@) +GTK_DOC_V_XML_=$(GTK_DOC_V_XML_@AM_DEFAULT_V@) GTK_DOC_V_XML_0=@echo " DOC Building XML"; -sgml-build.stamp: tmpl.stamp $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files) xml/gtkdocentities.ent - -$(GTK_DOC_V_XML)chmod -R u+w $(srcdir) && _source_dir='' ; \ +sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent + $(GTK_DOC_V_XML)_source_dir='' ; \ for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) $(AM_V_at)touch sgml-build.stamp @@ -189,12 +165,12 @@ xml/gtkdocentities.ent: Makefile #### html #### -GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_$(V)) -GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_@AM_V@) +GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_@AM_DEFAULT_V@) GTK_DOC_V_HTML_0=@echo " DOC Building HTML"; -GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_$(V)) -GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_@AM_V@) +GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_@AM_DEFAULT_V@) GTK_DOC_V_XREF_0=@echo " DOC Fixing cross-references"; html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) @@ -213,20 +189,16 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_con cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) -@test "x$(HTML_IMAGES)" = "x" || \ for file in $(HTML_IMAGES) ; do \ - if test -f $(abs_srcdir)/$$file ; then \ - cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ - fi; \ - if test -f $(abs_builddir)/$$file ; then \ - cp $(abs_builddir)/$$file $(abs_builddir)/html; \ - fi; \ + test -f $(abs_srcdir)/$$file && cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ + test -f $(abs_builddir)/$$file && cp $(abs_builddir)/$$file $(abs_builddir)/html; \ done; $(GTK_DOC_V_XREF)gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) $(AM_V_at)touch html-build.stamp #### pdf #### -GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_$(V)) -GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_@AM_V@) +GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_@AM_DEFAULT_V@) GTK_DOC_V_PDF_0=@echo " DOC Building PDF"; pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) @@ -267,7 +239,6 @@ distclean-local: $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ rm -f $(SETUP_FILES) $(DOC_MODULE).types; \ - rm -rf tmpl; \ fi maintainer-clean-local: @@ -317,9 +288,7 @@ dist-check-gtkdoc: endif dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local - @mkdir $(distdir)/tmpl @mkdir $(distdir)/html - @-cp ./tmpl/*.sgml $(distdir)/tmpl @cp ./html/* $(distdir)/html @-cp ./$(DOC_MODULE).pdf $(distdir)/ @-cp ./$(DOC_MODULE).types $(distdir)/ diff --git a/gtk-doc.notmpl-flat.make b/gtk-doc.notmpl-flat.make deleted file mode 100644 index 1fa38af..0000000 --- a/gtk-doc.notmpl-flat.make +++ /dev/null @@ -1,304 +0,0 @@ -# -*- mode: makefile -*- - -#################################### -# Everything below here is generic # -#################################### - -if GTK_DOC_USE_LIBTOOL -GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) -GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -GTKDOC_RUN = $(LIBTOOL) --mode=execute -else -GTKDOC_CC = $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) -GTKDOC_LD = $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -GTKDOC_RUN = -endif - -# We set GPATH here; this gives us semantics for GNU make -# which are more like other make's VPATH, when it comes to -# whether a source that is a target of one rule is then -# searched for in VPATH/GPATH. -# -GPATH = $(srcdir) - -TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) - -SETUP_FILES = \ - $(content_files) \ - $(expand_content_files) \ - $(DOC_MAIN_SGML_FILE) \ - $(DOC_MODULE)-sections.txt \ - $(DOC_MODULE)-overrides.txt - -EXTRA_DIST += \ - $(HTML_IMAGES) \ - $(SETUP_FILES) - -DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \ - html-build.stamp pdf-build.stamp \ - sgml.stamp html.stamp pdf.stamp - -SCANOBJ_FILES = \ - $(DOC_MODULE).args \ - $(DOC_MODULE).hierarchy \ - $(DOC_MODULE).interfaces \ - $(DOC_MODULE).prerequisites \ - $(DOC_MODULE).signals - -REPORT_FILES = \ - $(DOC_MODULE)-undocumented.txt \ - $(DOC_MODULE)-undeclared.txt \ - $(DOC_MODULE)-unused.txt - -gtkdoc-check.test: Makefile - $(AM_V_GEN)echo "#!/bin/sh -e" > $@; \ - echo "$(GTKDOC_CHECK_PATH) || exit 1" >> $@; \ - chmod +x $@ - -CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) gtkdoc-check.test - -if GTK_DOC_BUILD_HTML -HTML_BUILD_STAMP=html-build.stamp -else -HTML_BUILD_STAMP= -endif -if GTK_DOC_BUILD_PDF -PDF_BUILD_STAMP=pdf-build.stamp -else -PDF_BUILD_STAMP= -endif - -all-gtk-doc: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) -.PHONY: all-gtk-doc - -if ENABLE_GTK_DOC -all-local: all-gtk-doc -endif - -docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) - -$(REPORT_FILES): sgml-build.stamp - -#### setup #### - -GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_$(V)) -GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_SETUP_0=@echo " DOC Preparing build"; - -setup-build.stamp: - -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \ - if test "x$$files" != "x" ; then \ - for file in $$files ; do \ - destdir=`dirname $(abs_builddir)/$$file`; \ - test -d "$$destdir" || mkdir -p "$$destdir"; \ - test -f $(abs_srcdir)/$$file && \ - cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \ - done; \ - fi; \ - fi - $(AM_V_at)touch setup-build.stamp - - -#### scan #### - -GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_$(V)) -GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_SCAN_0=@echo " DOC Scanning header files"; - -GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_$(V)) -GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_INTROSPECT_0=@echo " DOC Introspecting gobjects"; - -scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) - $(GTK_DOC_V_SCAN)_source_dir='' ; \ - for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ - done ; \ - gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) - $(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ - scanobj_options=""; \ - gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \ - if test "$$?" = "0"; then \ - if test "x$(V)" = "x1"; then \ - scanobj_options="--verbose"; \ - fi; \ - fi; \ - CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ - gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \ - else \ - for i in $(SCANOBJ_FILES) ; do \ - test -f $$i || touch $$i ; \ - done \ - fi - $(AM_V_at)touch scan-build.stamp - -$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp - @true - -#### xml #### - -GTK_DOC_V_XML=$(GTK_DOC_V_XML_$(V)) -GTK_DOC_V_XML_=$(GTK_DOC_V_XML_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_XML_0=@echo " DOC Building XML"; - -sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent - $(GTK_DOC_V_XML)_source_dir='' ; \ - for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ - done ; \ - gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) - $(AM_V_at)touch sgml-build.stamp - -sgml.stamp: sgml-build.stamp - @true - -xml/gtkdocentities.ent: Makefile - $(GTK_DOC_V_XML)$(MKDIR_P) $(@D) && ( \ - echo ""; \ - echo ""; \ - echo ""; \ - echo ""; \ - echo ""; \ - echo ""; \ - echo ""; \ - ) > $@ - -#### html #### - -GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_$(V)) -GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_HTML_0=@echo " DOC Building HTML"; - -GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_$(V)) -GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_XREF_0=@echo " DOC Fixing cross-references"; - -html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) - $(GTK_DOC_V_HTML)rm -rf html && mkdir html && \ - mkhtml_options=""; \ - gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-verbose"; \ - if test "$$?" = "0"; then \ - if test "x$(V)" = "x1"; then \ - mkhtml_options="$$mkhtml_options --verbose"; \ - fi; \ - fi; \ - gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-path"; \ - if test "$$?" = "0"; then \ - mkhtml_options="$$mkhtml_options --path=\"$(abs_srcdir)\""; \ - fi; \ - cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) - -@test "x$(HTML_IMAGES)" = "x" || \ - for file in $(HTML_IMAGES) ; do \ - if test -f $(abs_srcdir)/$$file ; then \ - cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ - fi; \ - if test -f $(abs_builddir)/$$file ; then \ - cp $(abs_builddir)/$$file $(abs_builddir)/html; \ - fi; \ - done; - $(GTK_DOC_V_XREF)gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) - $(AM_V_at)touch html-build.stamp - -#### pdf #### - -GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_$(V)) -GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_PDF_0=@echo " DOC Building PDF"; - -pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) - $(GTK_DOC_V_PDF)rm -f $(DOC_MODULE).pdf && \ - mkpdf_options=""; \ - gtkdoc-mkpdf 2>&1 --help | grep >/dev/null "\-\-verbose"; \ - if test "$$?" = "0"; then \ - if test "x$(V)" = "x1"; then \ - mkpdf_options="$$mkpdf_options --verbose"; \ - fi; \ - fi; \ - if test "x$(HTML_IMAGES)" != "x"; then \ - for img in $(HTML_IMAGES); do \ - part=`dirname $$img`; \ - echo $$mkpdf_options | grep >/dev/null "\-\-imgdir=$$part "; \ - if test $$? != 0; then \ - mkpdf_options="$$mkpdf_options --imgdir=$$part"; \ - fi; \ - done; \ - fi; \ - gtkdoc-mkpdf --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) - $(AM_V_at)touch pdf-build.stamp - -############## - -clean-local: - @rm -f *~ *.bak - @rm -rf .libs - @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \ - rm -f $(DOC_MODULE).types; \ - fi - @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-sections" ; then \ - rm -f $(DOC_MODULE)-sections.txt; \ - fi - -distclean-local: - @rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \ - $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt - @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - rm -f $(SETUP_FILES) $(DOC_MODULE).types; \ - fi - -maintainer-clean-local: - @rm -rf xml html - -install-data-local: - @installfiles=`echo $(builddir)/html/*`; \ - if test "$$installfiles" = '$(builddir)/html/*'; \ - then echo 1>&2 'Nothing to install' ; \ - else \ - if test -n "$(DOC_MODULE_VERSION)"; then \ - installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ - else \ - installdir="$(DESTDIR)$(TARGET_DIR)"; \ - fi; \ - $(mkinstalldirs) $${installdir} ; \ - for i in $$installfiles; do \ - echo ' $(INSTALL_DATA) '$$i ; \ - $(INSTALL_DATA) $$i $${installdir}; \ - done; \ - if test -n "$(DOC_MODULE_VERSION)"; then \ - mv -f $${installdir}/$(DOC_MODULE).devhelp2 \ - $${installdir}/$(DOC_MODULE)-$(DOC_MODULE_VERSION).devhelp2; \ - fi; \ - $(GTKDOC_REBASE) --relative --dest-dir=$(DESTDIR) --html-dir=$${installdir}; \ - fi - -uninstall-local: - @if test -n "$(DOC_MODULE_VERSION)"; then \ - installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ - else \ - installdir="$(DESTDIR)$(TARGET_DIR)"; \ - fi; \ - rm -rf $${installdir} - -# -# Require gtk-doc when making dist -# -if HAVE_GTK_DOC -dist-check-gtkdoc: docs -else -dist-check-gtkdoc: - @echo "*** gtk-doc is needed to run 'make dist'. ***" - @echo "*** gtk-doc was not found when 'configure' ran. ***" - @echo "*** please install gtk-doc and rerun 'configure'. ***" - @false -endif - -dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local - @mkdir $(distdir)/html - @cp ./html/* $(distdir)/html - @-cp ./$(DOC_MODULE).pdf $(distdir)/ - @-cp ./$(DOC_MODULE).types $(distdir)/ - @-cp ./$(DOC_MODULE)-sections.txt $(distdir)/ - @cd $(distdir) && rm -f $(DISTCLEANFILES) - @$(GTKDOC_REBASE) --online --relative --html-dir=$(distdir)/html - -.PHONY : dist-hook-local docs diff --git a/gtk-doc.notmpl.make b/gtk-doc.notmpl.make deleted file mode 100644 index e4a12a5..0000000 --- a/gtk-doc.notmpl.make +++ /dev/null @@ -1,304 +0,0 @@ -# -*- mode: makefile -*- - -#################################### -# Everything below here is generic # -#################################### - -if GTK_DOC_USE_LIBTOOL -GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) -GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -GTKDOC_RUN = $(LIBTOOL) --mode=execute -else -GTKDOC_CC = $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) -GTKDOC_LD = $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -GTKDOC_RUN = -endif - -# We set GPATH here; this gives us semantics for GNU make -# which are more like other make's VPATH, when it comes to -# whether a source that is a target of one rule is then -# searched for in VPATH/GPATH. -# -GPATH = $(srcdir) - -TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) - -SETUP_FILES = \ - $(content_files) \ - $(expand_content_files) \ - $(DOC_MAIN_SGML_FILE) \ - $(DOC_MODULE)-sections.txt \ - $(DOC_MODULE)-overrides.txt - -EXTRA_DIST = \ - $(HTML_IMAGES) \ - $(SETUP_FILES) - -DOC_STAMPS=setup-build.stamp scan-build.stamp sgml-build.stamp \ - html-build.stamp pdf-build.stamp \ - sgml.stamp html.stamp pdf.stamp - -SCANOBJ_FILES = \ - $(DOC_MODULE).args \ - $(DOC_MODULE).hierarchy \ - $(DOC_MODULE).interfaces \ - $(DOC_MODULE).prerequisites \ - $(DOC_MODULE).signals - -REPORT_FILES = \ - $(DOC_MODULE)-undocumented.txt \ - $(DOC_MODULE)-undeclared.txt \ - $(DOC_MODULE)-unused.txt - -gtkdoc-check.test: Makefile - $(AM_V_GEN)echo "#!/bin/sh -e" > $@; \ - echo "$(GTKDOC_CHECK_PATH) || exit 1" >> $@; \ - chmod +x $@ - -CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) gtkdoc-check.test - -if GTK_DOC_BUILD_HTML -HTML_BUILD_STAMP=html-build.stamp -else -HTML_BUILD_STAMP= -endif -if GTK_DOC_BUILD_PDF -PDF_BUILD_STAMP=pdf-build.stamp -else -PDF_BUILD_STAMP= -endif - -all-gtk-doc: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) -.PHONY: all-gtk-doc - -if ENABLE_GTK_DOC -all-local: all-gtk-doc -endif - -docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) - -$(REPORT_FILES): sgml-build.stamp - -#### setup #### - -GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_$(V)) -GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_SETUP_0=@echo " DOC Preparing build"; - -setup-build.stamp: - -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \ - if test "x$$files" != "x" ; then \ - for file in $$files ; do \ - destdir=`dirname $(abs_builddir)/$$file`; \ - test -d "$$destdir" || mkdir -p "$$destdir"; \ - test -f $(abs_srcdir)/$$file && \ - cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \ - done; \ - fi; \ - fi - $(AM_V_at)touch setup-build.stamp - - -#### scan #### - -GTK_DOC_V_SCAN=$(GTK_DOC_V_SCAN_$(V)) -GTK_DOC_V_SCAN_=$(GTK_DOC_V_SCAN_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_SCAN_0=@echo " DOC Scanning header files"; - -GTK_DOC_V_INTROSPECT=$(GTK_DOC_V_INTROSPECT_$(V)) -GTK_DOC_V_INTROSPECT_=$(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_INTROSPECT_0=@echo " DOC Introspecting gobjects"; - -scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) - $(GTK_DOC_V_SCAN)_source_dir='' ; \ - for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ - done ; \ - gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) - $(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ - scanobj_options=""; \ - gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \ - if test "$$?" = "0"; then \ - if test "x$(V)" = "x1"; then \ - scanobj_options="--verbose"; \ - fi; \ - fi; \ - CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ - gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \ - else \ - for i in $(SCANOBJ_FILES) ; do \ - test -f $$i || touch $$i ; \ - done \ - fi - $(AM_V_at)touch scan-build.stamp - -$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp - @true - -#### xml #### - -GTK_DOC_V_XML=$(GTK_DOC_V_XML_$(V)) -GTK_DOC_V_XML_=$(GTK_DOC_V_XML_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_XML_0=@echo " DOC Building XML"; - -sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt $(expand_content_files) xml/gtkdocentities.ent - $(GTK_DOC_V_XML)_source_dir='' ; \ - for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ - done ; \ - gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) - $(AM_V_at)touch sgml-build.stamp - -sgml.stamp: sgml-build.stamp - @true - -xml/gtkdocentities.ent: Makefile - $(GTK_DOC_V_XML)$(MKDIR_P) $(@D) && ( \ - echo ""; \ - echo ""; \ - echo ""; \ - echo ""; \ - echo ""; \ - echo ""; \ - echo ""; \ - ) > $@ - -#### html #### - -GTK_DOC_V_HTML=$(GTK_DOC_V_HTML_$(V)) -GTK_DOC_V_HTML_=$(GTK_DOC_V_HTML_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_HTML_0=@echo " DOC Building HTML"; - -GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_$(V)) -GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_XREF_0=@echo " DOC Fixing cross-references"; - -html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) - $(GTK_DOC_V_HTML)rm -rf html && mkdir html && \ - mkhtml_options=""; \ - gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-verbose"; \ - if test "$$?" = "0"; then \ - if test "x$(V)" = "x1"; then \ - mkhtml_options="$$mkhtml_options --verbose"; \ - fi; \ - fi; \ - gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-path"; \ - if test "$$?" = "0"; then \ - mkhtml_options="$$mkhtml_options --path=\"$(abs_srcdir)\""; \ - fi; \ - cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) - -@test "x$(HTML_IMAGES)" = "x" || \ - for file in $(HTML_IMAGES) ; do \ - if test -f $(abs_srcdir)/$$file ; then \ - cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ - fi; \ - if test -f $(abs_builddir)/$$file ; then \ - cp $(abs_builddir)/$$file $(abs_builddir)/html; \ - fi; \ - done; - $(GTK_DOC_V_XREF)gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) - $(AM_V_at)touch html-build.stamp - -#### pdf #### - -GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_$(V)) -GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_$(AM_DEFAULT_VERBOSITY)) -GTK_DOC_V_PDF_0=@echo " DOC Building PDF"; - -pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) - $(GTK_DOC_V_PDF)rm -f $(DOC_MODULE).pdf && \ - mkpdf_options=""; \ - gtkdoc-mkpdf 2>&1 --help | grep >/dev/null "\-\-verbose"; \ - if test "$$?" = "0"; then \ - if test "x$(V)" = "x1"; then \ - mkpdf_options="$$mkpdf_options --verbose"; \ - fi; \ - fi; \ - if test "x$(HTML_IMAGES)" != "x"; then \ - for img in $(HTML_IMAGES); do \ - part=`dirname $$img`; \ - echo $$mkpdf_options | grep >/dev/null "\-\-imgdir=$$part "; \ - if test $$? != 0; then \ - mkpdf_options="$$mkpdf_options --imgdir=$$part"; \ - fi; \ - done; \ - fi; \ - gtkdoc-mkpdf --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) - $(AM_V_at)touch pdf-build.stamp - -############## - -clean-local: - @rm -f *~ *.bak - @rm -rf .libs - @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \ - rm -f $(DOC_MODULE).types; \ - fi - @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-sections" ; then \ - rm -f $(DOC_MODULE)-sections.txt; \ - fi - -distclean-local: - @rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \ - $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt - @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - rm -f $(SETUP_FILES) $(DOC_MODULE).types; \ - fi - -maintainer-clean-local: - @rm -rf xml html - -install-data-local: - @installfiles=`echo $(builddir)/html/*`; \ - if test "$$installfiles" = '$(builddir)/html/*'; \ - then echo 1>&2 'Nothing to install' ; \ - else \ - if test -n "$(DOC_MODULE_VERSION)"; then \ - installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ - else \ - installdir="$(DESTDIR)$(TARGET_DIR)"; \ - fi; \ - $(mkinstalldirs) $${installdir} ; \ - for i in $$installfiles; do \ - echo ' $(INSTALL_DATA) '$$i ; \ - $(INSTALL_DATA) $$i $${installdir}; \ - done; \ - if test -n "$(DOC_MODULE_VERSION)"; then \ - mv -f $${installdir}/$(DOC_MODULE).devhelp2 \ - $${installdir}/$(DOC_MODULE)-$(DOC_MODULE_VERSION).devhelp2; \ - fi; \ - $(GTKDOC_REBASE) --relative --dest-dir=$(DESTDIR) --html-dir=$${installdir}; \ - fi - -uninstall-local: - @if test -n "$(DOC_MODULE_VERSION)"; then \ - installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ - else \ - installdir="$(DESTDIR)$(TARGET_DIR)"; \ - fi; \ - rm -rf $${installdir} - -# -# Require gtk-doc when making dist -# -if HAVE_GTK_DOC -dist-check-gtkdoc: docs -else -dist-check-gtkdoc: - @echo "*** gtk-doc is needed to run 'make dist'. ***" - @echo "*** gtk-doc was not found when 'configure' ran. ***" - @echo "*** please install gtk-doc and rerun 'configure'. ***" - @false -endif - -dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local - @mkdir $(distdir)/html - @cp ./html/* $(distdir)/html - @-cp ./$(DOC_MODULE).pdf $(distdir)/ - @-cp ./$(DOC_MODULE).types $(distdir)/ - @-cp ./$(DOC_MODULE)-sections.txt $(distdir)/ - @cd $(distdir) && rm -f $(DISTCLEANFILES) - @$(GTKDOC_REBASE) --online --relative --html-dir=$(distdir)/html - -.PHONY : dist-hook-local docs diff --git a/gtk-doc.spec b/gtk-doc.spec deleted file mode 100644 index 7b5aff4..0000000 --- a/gtk-doc.spec +++ /dev/null @@ -1,93 +0,0 @@ -# -*- mode: rpm-spec -*- - -Summary: GTK+ DocBook Documentation Generator -Name: gtk-doc -Version: 1.25 -Release: 1 -License: GPL -Group: Utilities/Text -Source: ftp://ftp.gtk.org/pub/gtk/v1.1/docs/rdp/gtk-doc-%{version}.tar.gz -BuildRoot: /var/tmp/%{name}-%{version}-root -URL: http://www.gtk.org/rdp/ -BuildArchitectures: noarch -Requires: openjade -Requires: perl >= 5.6.0 -Requires: libxslt -Requires: docbook-dtds -Requires: docbook-style-xsl -Provides: perl(gtkdoc-common.pl) - -BuildRequires: perl, openjade, libxslt, docbook-dtds, docbook-style-xsl - -%description -gtk-doc is a set of perl scripts that generate API reference documention in -DocBook format. It can extract documentation from source code comments in a -manner similar to java-doc. It is used to generate the documentation for -GLib, Gtk+, and GNOME. - -%prep -%setup -q - -# Move this doc file to avoid name collisions -mv doc/README doc/README.docs - -%build -CFLAGS="$RPM_OPT_FLAGS" ./configure $MYARCH_FLAGS --prefix=%{_prefix} \ - --sysconfdir=%{_sysconfdir} --datadir=%{_datadir} - -make - -%install -rm -rf $RPM_BUILD_ROOT - -make prefix=$RPM_BUILD_ROOT%{_prefix} \ - sysconfdir=$RPM_BUILD_ROOT%{_sysconfdir} \ - datadir=$RPM_BUILD_ROOT%{_datadir} install - -%clean -rm -rf $RPM_BUILD_ROOT - -%files -%defattr(-, root, root) - -%doc AUTHORS COPYING ChangeLog README doc/* examples -# INSTALL is generic instructions from autoconf -# NEWS is currently empty -# %doc INSTALL -%doc NEWS - -%{_bindir}/* -%dir %{_datadir}/gtk-doc -%dir %{_datadir}/gtk-doc/html -%dir %{_datadir}/gtk-doc/data -%{_datadir}/gtk-doc/data/* -%{_libdir}/pkgconfig/* - -%changelog -* Tue Jun 03 2003 Matthias Clasen -- Add a missing Provides: and include the .pc file. - (#106568, Joe Pranevich) - -* Sun Aug 12 2001 Jens Finke -- Modified to match GPP standard: - - Changed to Copyright to License - - Don't use hardcoded path, use rpm macros instead - - Moved ChangeLog to the end of the file. - - Removed packager - - Don't set docdir path. - - Use /var/tmp as installation prefix - -* Fri Apr 27 2001 Toshio Kuratomi -- Merge in some of the features of the redhat spec file. - -* Wed Nov 15 2000 John Gotts -- Minor updates for 0.4. -* Thu Aug 26 1999 John E. Gotts -- Created spec file. - - - - - - - diff --git a/gtk-doc.spec.in b/gtk-doc.spec.in deleted file mode 100644 index 1b188e6..0000000 --- a/gtk-doc.spec.in +++ /dev/null @@ -1,93 +0,0 @@ -# -*- mode: rpm-spec -*- - -Summary: GTK+ DocBook Documentation Generator -Name: gtk-doc -Version: @VERSION@ -Release: 1 -License: GPL -Group: Utilities/Text -Source: ftp://ftp.gtk.org/pub/gtk/v1.1/docs/rdp/gtk-doc-%{version}.tar.gz -BuildRoot: /var/tmp/%{name}-%{version}-root -URL: http://www.gtk.org/rdp/ -BuildArchitectures: noarch -Requires: openjade -Requires: perl >= 5.6.0 -Requires: libxslt -Requires: docbook-dtds -Requires: docbook-style-xsl -Provides: perl(gtkdoc-common.pl) - -BuildRequires: perl, openjade, libxslt, docbook-dtds, docbook-style-xsl - -%description -gtk-doc is a set of perl scripts that generate API reference documention in -DocBook format. It can extract documentation from source code comments in a -manner similar to java-doc. It is used to generate the documentation for -GLib, Gtk+, and GNOME. - -%prep -%setup -q - -# Move this doc file to avoid name collisions -mv doc/README doc/README.docs - -%build -CFLAGS="$RPM_OPT_FLAGS" ./configure $MYARCH_FLAGS --prefix=%{_prefix} \ - --sysconfdir=%{_sysconfdir} --datadir=%{_datadir} - -make - -%install -rm -rf $RPM_BUILD_ROOT - -make prefix=$RPM_BUILD_ROOT%{_prefix} \ - sysconfdir=$RPM_BUILD_ROOT%{_sysconfdir} \ - datadir=$RPM_BUILD_ROOT%{_datadir} install - -%clean -rm -rf $RPM_BUILD_ROOT - -%files -%defattr(-, root, root) - -%doc AUTHORS COPYING ChangeLog README doc/* examples -# INSTALL is generic instructions from autoconf -# NEWS is currently empty -# %doc INSTALL -%doc NEWS - -%{_bindir}/* -%dir %{_datadir}/gtk-doc -%dir %{_datadir}/gtk-doc/html -%dir %{_datadir}/gtk-doc/data -%{_datadir}/gtk-doc/data/* -%{_libdir}/pkgconfig/* - -%changelog -* Tue Jun 03 2003 Matthias Clasen -- Add a missing Provides: and include the .pc file. - (#106568, Joe Pranevich) - -* Sun Aug 12 2001 Jens Finke -- Modified to match GPP standard: - - Changed to Copyright to License - - Don't use hardcoded path, use rpm macros instead - - Moved ChangeLog to the end of the file. - - Removed packager - - Don't set docdir path. - - Use /var/tmp as installation prefix - -* Fri Apr 27 2001 Toshio Kuratomi -- Merge in some of the features of the redhat spec file. - -* Wed Nov 15 2000 John Gotts -- Minor updates for 0.4. -* Thu Aug 26 1999 John E. Gotts -- Created spec file. - - - - - - - diff --git a/gtkdoc-check.in b/gtkdoc-check.in index 560d69b..8c8e917 100755 --- a/gtkdoc-check.in +++ b/gtkdoc-check.in @@ -1,8 +1,9 @@ -#!@PERL@ -w -# -*- cperl -*- +#!@PYTHON@ +# -*- python; coding: utf-8 -*- # # gtk-doc - GTK DocBook documentation generator. # Copyright (C) 2007 David Nečas +# 2007-2017 Stefan Sauer # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -19,159 +20,18 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -############################################################################# -# Script : gtkdoc-check -# Description : Runs various checks on built documentation and outputs test -# results. Can be run druring make check, by adding this to the -# documentations Makefile.am: TESTS = $(GTKDOC_CHECK) -############################################################################# +import argparse +import sys +sys.path.append('@PYTHON_PACKAGE_DIR@') -use strict; -use Getopt::Long; +from gtkdoc import common, check, config -my $PRINT_VERSION; -my $PRINT_HELP; +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-check version %s - run documentation unit tests' % config.version) + parser.add_argument('--version', action='version', version=config.version) + options = parser.parse_args() -my %optctl = ('version' => \$PRINT_VERSION, - 'help' => \$PRINT_HELP); -GetOptions(\%optctl, "version", "help"); + common.setup_logging() -if ($PRINT_VERSION) { - print "@VERSION@\n"; - exit 0; -} - -if ($PRINT_HELP) { - print < 0) + ($undeclared != 0) + ($unused != 0) + ($missing_includes != 0); -my $rate = 100.0*($checks - $failed)/$checks; -printf "%.1f%%: Checks %d, Failures: %d\n", $rate, $checks, $failed; -exit ($failed != 0); - -sub Grep() { - my ($regexp, $filename, $what) = @_; - my $retval; - - if (not open GFILE, "<$filename") { - die "Cannot open $filename: $!\n"; - } - while () { - next if not m/$regexp/; - $retval = $1; - last; - } - close GFILE; - if (not defined $retval) { - die "Cannot find $what in $filename\n"; - } - return $retval; -} - -sub CheckEmpty() { - my ($filename, $what) = @_; - my $count = 0; - - if (not open GFILE, "<$filename") { - return $count; - } - while () { - if (m/\S/) { - $count++ - } - } - close GFILE; - if ($count) { - print "$filename:1:E: $count $what\n" - } - return $count; -} - -sub CheckIncludes() { - my ($main_sgml_file) = @_; - - if (not open GFILE, "<$main_sgml_file") { - die "Cannot open $main_sgml_file: $!\n"; - } - - # Check that each of the XML files in the xml directory are included in $DOC_MAIN_SGML_FILE - my @xml_files = ; - my $num_missing = 0; - - foreach my $xml_file (@xml_files) { - my $regex = quotemeta ($xml_file); - my $found = 0; - - while () { - next if not m/"$regex"/; - $found = 1; - last; - } - - if (!$found) { - $num_missing++; - print "$main_sgml_file doesn't appear to include \"$xml_file\"\n"; - } - - seek (GFILE, 0, 0); - } - - close (GFILE); - - return $num_missing; -} + sys.exit(check.run(options)) diff --git a/gtkdoc-common.pl b/gtkdoc-common.pl deleted file mode 100644 index 04f22f5..0000000 --- a/gtkdoc-common.pl +++ /dev/null @@ -1,552 +0,0 @@ -#!/usr/bin/perl -w -# -*- cperl -*- -# -# gtk-doc - GTK DocBook documentation generator. -# Copyright (C) 2001 Damon Chaplin -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -# - -# -# These are functions used by several of the gtk-doc Perl scripts. -# We'll move more of the common routines here eventually, though they need to -# stop using global variables first. -# - -1; - - -############################################################################# -# Function : UpdateFileIfChanged -# Description : Compares the old version of the file with the new version and -# if the file has changed it moves the new version into the old -# versions place. This is used so we only change files if -# needed, so we can do proper dependency tracking and we don't -# needlessly check files into version control systems that haven't -# changed. -# It returns 0 if the file hasn't changed, and 1 if it has. -# Arguments : $old_file - the pathname of the old file. -# $new_file - the pathname of the new version of the file. -# $make_backup - 1 if a backup of the old file should be kept. -# It will have the .bak suffix added to the file name. -############################################################################# - -sub UpdateFileIfChanged { - my ($old_file, $new_file, $make_backup) = @_; - - #LogTrace("Comparing $old_file with $new_file..."); - - # If the old file doesn't exist we want this to default to 1. - my $exit_code = 1; - - if (-e $old_file) { - `cmp -s "$old_file" "$new_file"`; - $exit_code = $? >> 8; - #LogTrace(" cmp exit code: $exit_code ($?)"); - } - - if ($exit_code > 1) { - die "Error running 'cmp $old_file $new_file'"; - } - - if ($exit_code == 1) { - #LogTrace(" files changed - replacing old version with new version."); - if ($make_backup && -e $old_file) { - rename ($old_file, "$old_file.bak") - || die "Can't move $old_file to $old_file.bak: $!"; - } - rename ($new_file, $old_file) - || die "Can't move $new_file to $old_file: $!"; - - return 1; - } else { - #LogTrace(" files the same - deleting new version."); - unlink ("$new_file") - || die "Can't delete file: $new_file: $!"; - - return 0; - } -} - - -############################################################################# -# Function : ParseStructDeclaration -# Description : This function takes a structure declaration and -# breaks it into individual type declarations. -# Arguments : $declaration - the declaration to parse -# $is_object - true if this is an object structure -# $output_function_params - true if full type is wanted for -# function pointer members -# $typefunc - function reference to apply to type -# $namefunc - function reference to apply to name -############################################################################# - -sub ParseStructDeclaration { - my ($declaration, $is_object, $output_function_params, $typefunc, $namefunc) = @_; - - # For forward struct declarations just return an empty array. - if ($declaration =~ m/(?:struct|union)\s+\S+\s*;/msg) { - return (); - } - - # Remove all private parts of the declaration - - # For objects, assume private - if ($is_object) { - $declaration =~ s!((?:struct|union)\s+\w*\s*\{) - .*? - (?:/\*\s*<\s*public\s*>\s*\*/|(?=\}))!$1!msgx; - } - - # Remove private symbols - # Assume end of declaration if line begins with '}' - $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx; - - # Remove all other comments - $declaration =~ s@\n\s*/\*([^*]+|\*(?!/))*\*/\s*\n@\n@msg; - $declaration =~ s@/\*([^*]+|\*(?!/))*\*/@ @g; - $declaration =~ s@\n\s*//.*?\n@\n@msg; - $declaration =~ s@//.*@@g; - - # Remove g_iface, parent_instance and parent_class if they are first member - $declaration =~ s/(\{)\s*(\w)+\s+(g_iface|parent_instance|parent_class)\s*;/$1/g; - - my @result = (); - - if ($declaration =~ /^\s*$/) { - return @result; - } - - # Prime match after "struct/union {" declaration - if (!scalar($declaration =~ m/(?:struct|union)\s+\w*\s*\{/msg)) { - die "Declaration '$declaration' does not begin with struct/union [NAME] {\n"; - } - - #LogTrace("public fields in struct/union: $declaration"); - - # Treat lines in sequence, allowing singly nested anonymous structs - # and unions. - while ($declaration =~ m/\s*([^{;]+(\{[^\}]*\}[^{;]+)?);/msg) { - my $line = $1; - - last if $line =~ /^\s*\}\s*\w*\s*$/; - - # FIXME: Just ignore nested structs and unions for now - next if $line =~ /{/; - - # ignore preprocessor directives - while ($line =~ /^#.*?\n\s*(.*)/msg) { - $line=$1; - } - - last if $line =~ /^\s*\}\s*\w*\s*$/; - - # Try to match structure members which are functions - if ($line =~ m/^ - (const\s+|G_CONST_RETURN\s+|unsigned\s+|signed\s+|long\s+|short\s+)*(struct\s+|enum\s+)? # mod1 - (\w+)\s* # type - (\**(?:\s*restrict)?)\s* # ptr1 - (const\s+)? # mod2 - (\**\s*) # ptr2 - (const\s+)? # mod3 - \(\s*\*\s*(\w+)\s*\)\s* # name - \(([^)]*)\)\s* # func_params - $/x) { - - my $mod1 = defined($1) ? $1 : ""; - if (defined($2)) { $mod1 .= $2; } - my $type = $3; - my $ptr1 = $4; - my $mod2 = defined($5) ? $5 : ""; - my $ptr2 = $6; - my $mod3 = defined($7) ? $7 : ""; - my $name = $8; - my $func_params = $9; - my $ptype = defined $typefunc ? $typefunc->($type, "$type") : $type; - my $pname = defined $namefunc ? $namefunc->($name) : $name; - - push @result, $name; - - if ($output_function_params) { - push @result, "$mod1$ptype$ptr1$mod2$ptr2$mod3 (*$pname) ($func_params)"; - } else { - push @result, "$pname ()"; - } - - - # Try to match normal struct fields of comma-separated variables/ - } elsif ($line =~ m/^ - ((?:const\s+|volatile\s+|unsigned\s+|signed\s+|short\s+|long\s+)?)(struct\s+|enum\s+)? # mod1 - (\w+)\s* # type - (\** \s* const\s+)? # mod2 - (.*) # variables - $/x) { - - my $mod1 = defined($1) ? $1 : ""; - if (defined($2)) { $mod1 .= $2; } - my $type = $3; - my $ptype = defined $typefunc ? $typefunc->($type, "$type") : $type; - my $mod2 = defined($4) ? " " . $4 : ""; - my $list = $5; - - #LogTrace("'$mod1' '$type' '$mod2' '$list'"); - - $mod1 =~ s/ / /g; - $mod2 =~ s/ / /g; - - my @names = split /,/, $list; - for my $n (@names) { - # Each variable can have any number of '*' before the - # identifier, and be followed by any number of pairs of - # brackets or a bit field specifier. - # e.g. *foo, ***bar, *baz[12][23], foo : 25. - if ($n =~ m/^\s* (\**(?:\s*restrict\b)?) \s* (\w+) \s* (?: ((?:\[[^\]]*\]\s*)+) | (:\s*\d+)?) \s* $/x) { - my $ptrs = $1; - my $name = $2; - my $array = defined($3) ? $3 : ""; - my $bits = defined($4) ? " $4" : ""; - - if ($ptrs && $ptrs !~ m/\*$/) { $ptrs .= " "; } - $array =~ s/ / /g; - $bits =~ s/ / /g; - - push @result, $name; - if (defined $namefunc) { - $name = $namefunc->($name); - } - push @result, "$mod1$ptype$mod2 $ptrs$name$array$bits;"; - - #LogTrace("Matched line: $mod1$ptype$mod2 $ptrs$name$array$bits"); - } else { - print "WARNING: Couldn't parse struct field: $n\n"; - } - } - - } else { - print "WARNING: Cannot parse structure field: \"$line\"\n"; - } - } - - return @result; -} - - -############################################################################# -# Function : ParseEnumDeclaration -# Description : This function takes a enumeration declaration and -# breaks it into individual enum member declarations. -# Arguments : $declaration - the declaration to parse -############################################################################# - -sub ParseEnumDeclaration { - my ($declaration, $is_object) = @_; - - # For forward enum declarations just return an empty array. - if ($declaration =~ m/enum\s+\S+\s*;/msg) { - return (); - } - - # Remove private symbols - # Assume end of declaration if line begins with '}' - $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx; - - # Remove all other comments - $declaration =~ s@\n\s*/\*([^*]+|\*(?!/))*\*/\s*\n@\n@msg; - $declaration =~ s@/\*([^*]+|\*(?!/))*\*/@ @g; - $declaration =~ s@\n\s*//.*?\n@\n@msg; - $declaration =~ s@//.*@@g; - - my @result = (); - - if ($declaration =~ /^\s*$/) { - return @result; - } - - # Remove parenthesized expressions (in macros like GTK_BLAH = BLAH(1,3)) - # to avoid getting confused by commas they might contain. This - # doesn't handle nested parentheses correctly. - - $declaration =~ s/\([^)\n]+\)//g; - - # Remove apostrophed characters (e.g. '}' or ',') values to avoid getting - # confused with end of enumeration. - # See https://bugzilla.gnome.org/show_bug.cgi?id=741305 - - $declaration =~ s/\'.\'//g; - - # Remove comma from comma - possible whitespace - closing brace sequence - # since it is legal in GNU C and C99 to have a trailing comma but doesn't - # result in an actual enum member - - $declaration =~ s/,(\s*})/$1/g; - - # Prime match after "typedef enum {" declaration - if (!scalar($declaration =~ m/(typedef\s+)?enum\s*(\S+\s*)?\{/msg)) { - die "Enum declaration '$declaration' does not begin with 'typedef enum {' or 'enum XXX {'\n"; - } - - #LogTrace("public fields in enum: $declaration"); - - # Treat lines in sequence. - while ($declaration =~ m/\s*([^,\}]+)([,\}])/msg) { - my $line = $1; - my $terminator = $2; - - # ignore preprocessor directives - while ($line =~ /^#.*?\n\s*(.*)/msg) { - $line=$1; - } - - if ($line =~ m/^(\w+)\s*(=.*)?$/msg) { - push @result, $1; - - # Special case for GIOCondition, where the values are specified by - # macros which expand to include the equal sign like '=1'. - } elsif ($line =~ m/^(\w+)\s*GLIB_SYSDEF_POLL/msg) { - push @result, $1; - - # Special case include of , just ignore it - } elsif ($line =~ m/^#include/) { - last; - - # Special case for #ifdef/#else/#endif, just ignore it - } elsif ($line =~ m/^#(?:if|else|endif)/) { - last; - - } else { - warn "Cannot parse enumeration member \"$line\""; - } - - last if $terminator eq '}'; - } - - return @result; -} - - -############################################################################# -# Function : ParseFunctionDeclaration -# Description : This function takes a function declaration and -# breaks it into individual parameter declarations. -# Arguments : $declaration - the declaration to parse -# $typefunc - function reference to apply to type -# $namefunc - function reference to apply to name -############################################################################# - -sub ParseFunctionDeclaration { - my ($declaration, $typefunc, $namefunc) = @_; - - my @result = (); - - my ($param_num) = 0; - while ($declaration ne "") { - #LogTrace("[$declaration]"); - - if ($declaration =~ s/^[\s,]+//) { - # skip whitespace and commas - next; - - } elsif ($declaration =~ s/^void\s*[,\n]//) { - if ($param_num != 0) { - # FIXME: whats the problem here? - warn "void used as parameter in function $declaration"; - } - push @result, "void"; - my $xref = "void"; - my $label = defined $namefunc ? $namefunc->($xref) : $xref; - push @result, $label; - - } elsif ($declaration =~ s/^\s*[_a-zA-Z0-9]*\.\.\.\s*[,\n]//) { - push @result, "..."; - my $label = defined $namefunc ? $namefunc->("...") : "..."; - push @result, $label; - - # allow alphanumerics, '_', '[' & ']' in param names - # Try to match a standard parameter - # $1 $2 $3 $4 $5 - } elsif ($declaration =~ s/^\s*((?:(?:G_CONST_RETURN|G_GNUC_[A-Z_]+\s+|unsigned long|unsigned short|signed long|signed short|unsigned|signed|long|short|volatile|const)\s+)*)((?:struct\b|enum\b)?\s*\w+)\s*((?:(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*\*?\s*(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*)*)(\w+)?\s*((?:\[\S*\])*)\s*(?:G_GNUC_[A-Z_]+)?\s*[,\n]//) { - my $pre = defined($1) ? $1 : ""; - my $type = $2; - my $ptr = defined($3) ? $3 : ""; - my $name = defined($4) ? $4 : ""; - my $array = defined($5) ? $5 : ""; - - $pre =~ s/\s+/ /g; - $type =~ s/\s+/ /g; - $ptr =~ s/\s+/ /g; - $ptr =~ s/\s+$//; - if ($ptr && $ptr !~ m/\*$/) { $ptr .= " "; } - - #LogTrace("$symbol: '$pre' '$type' '$ptr' '$name' '$array'"); - - if (($name eq "") && $pre =~ m/^((un)?signed .*)\s?/ ) { - $name = $type; - $type = "$1"; - $pre = ""; - } - - if ($name eq "") { - $name = "Param" . ($param_num + 1); - } - - #LogTrace("$symbol: '$pre' '$type' '$ptr' '$name' '$array'"); - - push @result, $name; - my $xref = defined $typefunc ? $typefunc->($type, "$type") : $type; - my $label = "$pre$xref $ptr$name$array"; - if (defined $namefunc) { - $label = $namefunc->($label) - } - push @result, $label; - - # Try to match parameters which are functions - # $1 $2 $3 $4 $5 $6 $7 $8 - } elsif ($declaration =~ s/^(const\s+|G_CONST_RETURN\s+|G_GNUC_[A-Z_]+\s+|signed\s+|unsigned\s+)*(struct\s+)?(\w+)\s*(\**)\s*(?:restrict\b)?\s*(const\s+)?\(\s*(\*[\s\*]*)\s*(\w+)\s*\)\s*\(([^)]*)\)\s*[,\n]//) { - my $mod1 = defined($1) ? $1 : ""; - if (defined($2)) { $mod1 .= $2; } - my $type = $3; - my $ptr1 = $4; - my $mod2 = defined($5) ? $5 : ""; - my $func_ptr = $6; - my $name = $7; - my $func_params = defined($8) ? $8 : ""; - - #if (!defined($type)) { print "## no type\n"; }; - #if (!defined($ptr1)) { print "## no ptr1\n"; }; - #if (!defined($func_ptr)) { print "## no func_ptr\n"; }; - #if (!defined($name)) { print "## no name\n"; }; - - if ($ptr1 && $ptr1 !~ m/\*$/) { $ptr1 .= " "; } - $func_ptr =~ s/\s+//g; - - push @result, $name; - my $xref = defined $typefunc ? $typefunc->($type, "$type") : $type; - #LogTrace("Type: [$mod1][$xref][$ptr1][$mod2] ([$func_ptr][$name]) ($func_params)"); - my $label = "$mod1$xref$ptr1$mod2 ($func_ptr$name) ($func_params)"; - if (defined $namefunc) { - $label = $namefunc->($label) - } - push @result, $label; - } else { - warn "Can't parse args for function in \"$declaration\""; - last; - } - $param_num++; - } - - return @result; -} - - -############################################################################# -# Function : ParseMacroDeclaration -# Description : This function takes a macro declaration and -# breaks it into individual parameter declarations. -# Arguments : $declaration - the declaration to parse -# $namefunc - function reference to apply to name -############################################################################# - -sub ParseMacroDeclaration { - my ($declaration, $namefunc) = @_; - - my @result = (); - - if ($declaration =~ m/^\s*#\s*define\s+\w+\(([^\)]*)\)/) { - my $params = $1; - - $params =~ s/\\\n//g; - foreach $param (split (/,/, $params)) { - $param =~ s/^\s+//; - $param =~ s/\s*$//; - # Allow varargs variations - if ($param =~ m/^.*\.\.\.$/) { - $param = "..."; - } - if ($param =~ m/\S/) { - push @result, $param; - push @result, defined $namefunc ? $namefunc->($param) : $param; - } - } - } - - return @result; -} - - -############################################################################# -# Function : LogWarning -# Description : Log a warning in gcc style format -# Arguments : $file - the file the error comes from -# $line - line number for the wrong entry -# $message - description of the issue -############################################################################# - -sub LogWarning { - my ($file, $line, $message) = @_; - - $file="unknown" if !defined($file); - $line="0" if !defined($line); - - print "$file:$line: warning: $message\n" -} - -sub LogTrace { - my ($message) = @_; - - if (defined($ENV{"GTKDOC_TRACE"})) { - my (undef, $file, $line) = caller; - - chomp($message); - print "$file:$line: trace: $message\n" - } -} - - -############################################################################# -# Function : CreateValidSGMLID -# Description : Creates a valid SGML 'id' from the given string. -# According to http://www.w3.org/TR/html4/types.html#type-id -# "ID and NAME tokens must begin with a letter ([A-Za-z]) and -# may be followed by any number of letters, digits ([0-9]), -# hyphens ("-"), underscores ("_"), colons (":"), and -# periods (".")." -# -# NOTE: When creating SGML IDS, we append ":CAPS" to all -# all-caps identifiers to prevent name clashes (SGML ids are -# case-insensitive). (It basically never is the case that -# mixed-case identifiers would collide.) -# Arguments : $id - the string to be converted into a valid SGML id. -############################################################################# - -sub CreateValidSGMLID { - my ($id) = $_[0]; - - # Special case, '_' would end up as '' so we use 'gettext-macro' instead. - if ($id eq "_") { return "gettext-macro"; } - - $id =~ s/[_ ]/-/g; - $id =~ s/[,;]//g; - $id =~ s/^-*//; - $id =~ s/::/-/g; - $id =~ s/:/--/g; - - # Append ":CAPS" to all all-caps identifiers - # FIXME: there are some inconsistencies here, we have sgml.index files - # containing e.g. TRUE--CAPS - if ($id !~ /[a-z]/ && $id !~ /-CAPS$/) { $id .= ":CAPS" }; - - return $id; -} - diff --git a/gtkdoc-common.pl.in b/gtkdoc-common.pl.in deleted file mode 100644 index 4747396..0000000 --- a/gtkdoc-common.pl.in +++ /dev/null @@ -1,552 +0,0 @@ -#!@PERL@ -w -# -*- cperl -*- -# -# gtk-doc - GTK DocBook documentation generator. -# Copyright (C) 2001 Damon Chaplin -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -# - -# -# These are functions used by several of the gtk-doc Perl scripts. -# We'll move more of the common routines here eventually, though they need to -# stop using global variables first. -# - -1; - - -############################################################################# -# Function : UpdateFileIfChanged -# Description : Compares the old version of the file with the new version and -# if the file has changed it moves the new version into the old -# versions place. This is used so we only change files if -# needed, so we can do proper dependency tracking and we don't -# needlessly check files into version control systems that haven't -# changed. -# It returns 0 if the file hasn't changed, and 1 if it has. -# Arguments : $old_file - the pathname of the old file. -# $new_file - the pathname of the new version of the file. -# $make_backup - 1 if a backup of the old file should be kept. -# It will have the .bak suffix added to the file name. -############################################################################# - -sub UpdateFileIfChanged { - my ($old_file, $new_file, $make_backup) = @_; - - #@TRACE@("Comparing $old_file with $new_file..."); - - # If the old file doesn't exist we want this to default to 1. - my $exit_code = 1; - - if (-e $old_file) { - `cmp -s "$old_file" "$new_file"`; - $exit_code = $? >> 8; - #@TRACE@(" cmp exit code: $exit_code ($?)"); - } - - if ($exit_code > 1) { - die "Error running 'cmp $old_file $new_file'"; - } - - if ($exit_code == 1) { - #@TRACE@(" files changed - replacing old version with new version."); - if ($make_backup && -e $old_file) { - rename ($old_file, "$old_file.bak") - || die "Can't move $old_file to $old_file.bak: $!"; - } - rename ($new_file, $old_file) - || die "Can't move $new_file to $old_file: $!"; - - return 1; - } else { - #@TRACE@(" files the same - deleting new version."); - unlink ("$new_file") - || die "Can't delete file: $new_file: $!"; - - return 0; - } -} - - -############################################################################# -# Function : ParseStructDeclaration -# Description : This function takes a structure declaration and -# breaks it into individual type declarations. -# Arguments : $declaration - the declaration to parse -# $is_object - true if this is an object structure -# $output_function_params - true if full type is wanted for -# function pointer members -# $typefunc - function reference to apply to type -# $namefunc - function reference to apply to name -############################################################################# - -sub ParseStructDeclaration { - my ($declaration, $is_object, $output_function_params, $typefunc, $namefunc) = @_; - - # For forward struct declarations just return an empty array. - if ($declaration =~ m/(?:struct|union)\s+\S+\s*;/msg) { - return (); - } - - # Remove all private parts of the declaration - - # For objects, assume private - if ($is_object) { - $declaration =~ s!((?:struct|union)\s+\w*\s*\{) - .*? - (?:/\*\s*<\s*public\s*>\s*\*/|(?=\}))!$1!msgx; - } - - # Remove private symbols - # Assume end of declaration if line begins with '}' - $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx; - - # Remove all other comments - $declaration =~ s@\n\s*/\*([^*]+|\*(?!/))*\*/\s*\n@\n@msg; - $declaration =~ s@/\*([^*]+|\*(?!/))*\*/@ @g; - $declaration =~ s@\n\s*//.*?\n@\n@msg; - $declaration =~ s@//.*@@g; - - # Remove g_iface, parent_instance and parent_class if they are first member - $declaration =~ s/(\{)\s*(\w)+\s+(g_iface|parent_instance|parent_class)\s*;/$1/g; - - my @result = (); - - if ($declaration =~ /^\s*$/) { - return @result; - } - - # Prime match after "struct/union {" declaration - if (!scalar($declaration =~ m/(?:struct|union)\s+\w*\s*\{/msg)) { - die "Declaration '$declaration' does not begin with struct/union [NAME] {\n"; - } - - #@TRACE@("public fields in struct/union: $declaration"); - - # Treat lines in sequence, allowing singly nested anonymous structs - # and unions. - while ($declaration =~ m/\s*([^{;]+(\{[^\}]*\}[^{;]+)?);/msg) { - my $line = $1; - - last if $line =~ /^\s*\}\s*\w*\s*$/; - - # FIXME: Just ignore nested structs and unions for now - next if $line =~ /{/; - - # ignore preprocessor directives - while ($line =~ /^#.*?\n\s*(.*)/msg) { - $line=$1; - } - - last if $line =~ /^\s*\}\s*\w*\s*$/; - - # Try to match structure members which are functions - if ($line =~ m/^ - (const\s+|G_CONST_RETURN\s+|unsigned\s+|signed\s+|long\s+|short\s+)*(struct\s+|enum\s+)? # mod1 - (\w+)\s* # type - (\**(?:\s*restrict)?)\s* # ptr1 - (const\s+)? # mod2 - (\**\s*) # ptr2 - (const\s+)? # mod3 - \(\s*\*\s*(\w+)\s*\)\s* # name - \(([^)]*)\)\s* # func_params - $/x) { - - my $mod1 = defined($1) ? $1 : ""; - if (defined($2)) { $mod1 .= $2; } - my $type = $3; - my $ptr1 = $4; - my $mod2 = defined($5) ? $5 : ""; - my $ptr2 = $6; - my $mod3 = defined($7) ? $7 : ""; - my $name = $8; - my $func_params = $9; - my $ptype = defined $typefunc ? $typefunc->($type, "$type") : $type; - my $pname = defined $namefunc ? $namefunc->($name) : $name; - - push @result, $name; - - if ($output_function_params) { - push @result, "$mod1$ptype$ptr1$mod2$ptr2$mod3 (*$pname) ($func_params)"; - } else { - push @result, "$pname ()"; - } - - - # Try to match normal struct fields of comma-separated variables/ - } elsif ($line =~ m/^ - ((?:const\s+|volatile\s+|unsigned\s+|signed\s+|short\s+|long\s+)?)(struct\s+|enum\s+)? # mod1 - (\w+)\s* # type - (\** \s* const\s+)? # mod2 - (.*) # variables - $/x) { - - my $mod1 = defined($1) ? $1 : ""; - if (defined($2)) { $mod1 .= $2; } - my $type = $3; - my $ptype = defined $typefunc ? $typefunc->($type, "$type") : $type; - my $mod2 = defined($4) ? " " . $4 : ""; - my $list = $5; - - #@TRACE@("'$mod1' '$type' '$mod2' '$list'"); - - $mod1 =~ s/ / /g; - $mod2 =~ s/ / /g; - - my @names = split /,/, $list; - for my $n (@names) { - # Each variable can have any number of '*' before the - # identifier, and be followed by any number of pairs of - # brackets or a bit field specifier. - # e.g. *foo, ***bar, *baz[12][23], foo : 25. - if ($n =~ m/^\s* (\**(?:\s*restrict\b)?) \s* (\w+) \s* (?: ((?:\[[^\]]*\]\s*)+) | (:\s*\d+)?) \s* $/x) { - my $ptrs = $1; - my $name = $2; - my $array = defined($3) ? $3 : ""; - my $bits = defined($4) ? " $4" : ""; - - if ($ptrs && $ptrs !~ m/\*$/) { $ptrs .= " "; } - $array =~ s/ / /g; - $bits =~ s/ / /g; - - push @result, $name; - if (defined $namefunc) { - $name = $namefunc->($name); - } - push @result, "$mod1$ptype$mod2 $ptrs$name$array$bits;"; - - #@TRACE@("Matched line: $mod1$ptype$mod2 $ptrs$name$array$bits"); - } else { - print "WARNING: Couldn't parse struct field: $n\n"; - } - } - - } else { - print "WARNING: Cannot parse structure field: \"$line\"\n"; - } - } - - return @result; -} - - -############################################################################# -# Function : ParseEnumDeclaration -# Description : This function takes a enumeration declaration and -# breaks it into individual enum member declarations. -# Arguments : $declaration - the declaration to parse -############################################################################# - -sub ParseEnumDeclaration { - my ($declaration, $is_object) = @_; - - # For forward enum declarations just return an empty array. - if ($declaration =~ m/enum\s+\S+\s*;/msg) { - return (); - } - - # Remove private symbols - # Assume end of declaration if line begins with '}' - $declaration =~ s!\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))!!msgx; - - # Remove all other comments - $declaration =~ s@\n\s*/\*([^*]+|\*(?!/))*\*/\s*\n@\n@msg; - $declaration =~ s@/\*([^*]+|\*(?!/))*\*/@ @g; - $declaration =~ s@\n\s*//.*?\n@\n@msg; - $declaration =~ s@//.*@@g; - - my @result = (); - - if ($declaration =~ /^\s*$/) { - return @result; - } - - # Remove parenthesized expressions (in macros like GTK_BLAH = BLAH(1,3)) - # to avoid getting confused by commas they might contain. This - # doesn't handle nested parentheses correctly. - - $declaration =~ s/\([^)\n]+\)//g; - - # Remove apostrophed characters (e.g. '}' or ',') values to avoid getting - # confused with end of enumeration. - # See https://bugzilla.gnome.org/show_bug.cgi?id=741305 - - $declaration =~ s/\'.\'//g; - - # Remove comma from comma - possible whitespace - closing brace sequence - # since it is legal in GNU C and C99 to have a trailing comma but doesn't - # result in an actual enum member - - $declaration =~ s/,(\s*})/$1/g; - - # Prime match after "typedef enum {" declaration - if (!scalar($declaration =~ m/(typedef\s+)?enum\s*(\S+\s*)?\{/msg)) { - die "Enum declaration '$declaration' does not begin with 'typedef enum {' or 'enum XXX {'\n"; - } - - #@TRACE@("public fields in enum: $declaration"); - - # Treat lines in sequence. - while ($declaration =~ m/\s*([^,\}]+)([,\}])/msg) { - my $line = $1; - my $terminator = $2; - - # ignore preprocessor directives - while ($line =~ /^#.*?\n\s*(.*)/msg) { - $line=$1; - } - - if ($line =~ m/^(\w+)\s*(=.*)?$/msg) { - push @result, $1; - - # Special case for GIOCondition, where the values are specified by - # macros which expand to include the equal sign like '=1'. - } elsif ($line =~ m/^(\w+)\s*GLIB_SYSDEF_POLL/msg) { - push @result, $1; - - # Special case include of , just ignore it - } elsif ($line =~ m/^#include/) { - last; - - # Special case for #ifdef/#else/#endif, just ignore it - } elsif ($line =~ m/^#(?:if|else|endif)/) { - last; - - } else { - warn "Cannot parse enumeration member \"$line\""; - } - - last if $terminator eq '}'; - } - - return @result; -} - - -############################################################################# -# Function : ParseFunctionDeclaration -# Description : This function takes a function declaration and -# breaks it into individual parameter declarations. -# Arguments : $declaration - the declaration to parse -# $typefunc - function reference to apply to type -# $namefunc - function reference to apply to name -############################################################################# - -sub ParseFunctionDeclaration { - my ($declaration, $typefunc, $namefunc) = @_; - - my @result = (); - - my ($param_num) = 0; - while ($declaration ne "") { - #@TRACE@("[$declaration]"); - - if ($declaration =~ s/^[\s,]+//) { - # skip whitespace and commas - next; - - } elsif ($declaration =~ s/^void\s*[,\n]//) { - if ($param_num != 0) { - # FIXME: whats the problem here? - warn "void used as parameter in function $declaration"; - } - push @result, "void"; - my $xref = "void"; - my $label = defined $namefunc ? $namefunc->($xref) : $xref; - push @result, $label; - - } elsif ($declaration =~ s/^\s*[_a-zA-Z0-9]*\.\.\.\s*[,\n]//) { - push @result, "..."; - my $label = defined $namefunc ? $namefunc->("...") : "..."; - push @result, $label; - - # allow alphanumerics, '_', '[' & ']' in param names - # Try to match a standard parameter - # $1 $2 $3 $4 $5 - } elsif ($declaration =~ s/^\s*((?:(?:G_CONST_RETURN|G_GNUC_[A-Z_]+\s+|unsigned long|unsigned short|signed long|signed short|unsigned|signed|long|short|volatile|const)\s+)*)((?:struct\b|enum\b)?\s*\w+)\s*((?:(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*\*?\s*(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*)*)(\w+)?\s*((?:\[\S*\])*)\s*(?:G_GNUC_[A-Z_]+)?\s*[,\n]//) { - my $pre = defined($1) ? $1 : ""; - my $type = $2; - my $ptr = defined($3) ? $3 : ""; - my $name = defined($4) ? $4 : ""; - my $array = defined($5) ? $5 : ""; - - $pre =~ s/\s+/ /g; - $type =~ s/\s+/ /g; - $ptr =~ s/\s+/ /g; - $ptr =~ s/\s+$//; - if ($ptr && $ptr !~ m/\*$/) { $ptr .= " "; } - - #@TRACE@("$symbol: '$pre' '$type' '$ptr' '$name' '$array'"); - - if (($name eq "") && $pre =~ m/^((un)?signed .*)\s?/ ) { - $name = $type; - $type = "$1"; - $pre = ""; - } - - if ($name eq "") { - $name = "Param" . ($param_num + 1); - } - - #@TRACE@("$symbol: '$pre' '$type' '$ptr' '$name' '$array'"); - - push @result, $name; - my $xref = defined $typefunc ? $typefunc->($type, "$type") : $type; - my $label = "$pre$xref $ptr$name$array"; - if (defined $namefunc) { - $label = $namefunc->($label) - } - push @result, $label; - - # Try to match parameters which are functions - # $1 $2 $3 $4 $5 $6 $7 $8 - } elsif ($declaration =~ s/^(const\s+|G_CONST_RETURN\s+|G_GNUC_[A-Z_]+\s+|signed\s+|unsigned\s+)*(struct\s+)?(\w+)\s*(\**)\s*(?:restrict\b)?\s*(const\s+)?\(\s*(\*[\s\*]*)\s*(\w+)\s*\)\s*\(([^)]*)\)\s*[,\n]//) { - my $mod1 = defined($1) ? $1 : ""; - if (defined($2)) { $mod1 .= $2; } - my $type = $3; - my $ptr1 = $4; - my $mod2 = defined($5) ? $5 : ""; - my $func_ptr = $6; - my $name = $7; - my $func_params = defined($8) ? $8 : ""; - - #if (!defined($type)) { print "## no type\n"; }; - #if (!defined($ptr1)) { print "## no ptr1\n"; }; - #if (!defined($func_ptr)) { print "## no func_ptr\n"; }; - #if (!defined($name)) { print "## no name\n"; }; - - if ($ptr1 && $ptr1 !~ m/\*$/) { $ptr1 .= " "; } - $func_ptr =~ s/\s+//g; - - push @result, $name; - my $xref = defined $typefunc ? $typefunc->($type, "$type") : $type; - #@TRACE@("Type: [$mod1][$xref][$ptr1][$mod2] ([$func_ptr][$name]) ($func_params)"); - my $label = "$mod1$xref$ptr1$mod2 ($func_ptr$name) ($func_params)"; - if (defined $namefunc) { - $label = $namefunc->($label) - } - push @result, $label; - } else { - warn "Can't parse args for function in \"$declaration\""; - last; - } - $param_num++; - } - - return @result; -} - - -############################################################################# -# Function : ParseMacroDeclaration -# Description : This function takes a macro declaration and -# breaks it into individual parameter declarations. -# Arguments : $declaration - the declaration to parse -# $namefunc - function reference to apply to name -############################################################################# - -sub ParseMacroDeclaration { - my ($declaration, $namefunc) = @_; - - my @result = (); - - if ($declaration =~ m/^\s*#\s*define\s+\w+\(([^\)]*)\)/) { - my $params = $1; - - $params =~ s/\\\n//g; - foreach $param (split (/,/, $params)) { - $param =~ s/^\s+//; - $param =~ s/\s*$//; - # Allow varargs variations - if ($param =~ m/^.*\.\.\.$/) { - $param = "..."; - } - if ($param =~ m/\S/) { - push @result, $param; - push @result, defined $namefunc ? $namefunc->($param) : $param; - } - } - } - - return @result; -} - - -############################################################################# -# Function : LogWarning -# Description : Log a warning in gcc style format -# Arguments : $file - the file the error comes from -# $line - line number for the wrong entry -# $message - description of the issue -############################################################################# - -sub LogWarning { - my ($file, $line, $message) = @_; - - $file="unknown" if !defined($file); - $line="0" if !defined($line); - - print "$file:$line: warning: $message\n" -} - -sub LogTrace { - my ($message) = @_; - - if (defined($ENV{"GTKDOC_TRACE"})) { - my (undef, $file, $line) = caller; - - chomp($message); - print "$file:$line: trace: $message\n" - } -} - - -############################################################################# -# Function : CreateValidSGMLID -# Description : Creates a valid SGML 'id' from the given string. -# According to http://www.w3.org/TR/html4/types.html#type-id -# "ID and NAME tokens must begin with a letter ([A-Za-z]) and -# may be followed by any number of letters, digits ([0-9]), -# hyphens ("-"), underscores ("_"), colons (":"), and -# periods (".")." -# -# NOTE: When creating SGML IDS, we append ":CAPS" to all -# all-caps identifiers to prevent name clashes (SGML ids are -# case-insensitive). (It basically never is the case that -# mixed-case identifiers would collide.) -# Arguments : $id - the string to be converted into a valid SGML id. -############################################################################# - -sub CreateValidSGMLID { - my ($id) = $_[0]; - - # Special case, '_' would end up as '' so we use 'gettext-macro' instead. - if ($id eq "_") { return "gettext-macro"; } - - $id =~ s/[_ ]/-/g; - $id =~ s/[,;]//g; - $id =~ s/^-*//; - $id =~ s/::/-/g; - $id =~ s/:/--/g; - - # Append ":CAPS" to all all-caps identifiers - # FIXME: there are some inconsistencies here, we have sgml.index files - # containing e.g. TRUE--CAPS - if ($id !~ /[a-z]/ && $id !~ /-CAPS$/) { $id .= ":CAPS" }; - - return $id; -} - diff --git a/gtkdoc-depscan.in b/gtkdoc-depscan.in index 83af01b..9bfaf30 100644 --- a/gtkdoc-depscan.in +++ b/gtkdoc-depscan.in @@ -1,5 +1,7 @@ #!@PYTHON@ +from __future__ import print_function + import gzip, os.path, re from os import environ, popen, walk @@ -40,7 +42,7 @@ class Book(object): break if not self.__catalog: - raise IOError, 'No devhelp book found for "%s"' % name + raise IOError('No devhelp book found for "%s"' % name) def __cmp__(self, other): if isinstance(other, Book): @@ -264,7 +266,7 @@ def merge_gnome_path(options): path = path and path.split(':') or [] prefix = popen( - 'pkg-config --variable=prefix glib-2.0' + '@PKG_CONFIG@ --variable=prefix glib-2.0' ).readline().rstrip() path.insert(0, prefix) @@ -285,7 +287,7 @@ def summarize_matches(matches): for filename, lineno, symbol in matches: if not isinstance(symbol, Symbol): if options.verbose: - print '%s:%d: unknown symbol %s' % (filename, lineno, symbol) + print('%s:%d: unknown symbol %s' % (filename, lineno, symbol)) continue since = '%s-%s' % (symbol.book.name, symbol.since) @@ -308,7 +310,7 @@ if '__main__' == __name__: options.books = default_books def trace(message, *args): - if options.verbose: print message % args + if options.verbose: print(message % args) def parse_book(name): try: @@ -319,7 +321,7 @@ if '__main__' == __name__: version = version and Symbol.VersionInfo(version) return name, Book(name, options.dirs, version) - except IOError, e: + except IOError as e: print >>stderr, 'WARNING: %s.' % e def scan_source_file(name): @@ -328,7 +330,7 @@ if '__main__' == __name__: try: contents = __comment_regex.sub('', file(name).read()) - except IOError, e: + except IOError as e: print >>stderr, e if contents: @@ -380,23 +382,23 @@ if '__main__' == __name__: if options.summarize: summary = summarize_matches(matches) for since in sorted(summary.keys()): - print '%s required for' % since + print('%s required for' % since) for x in summary[since]: - print ' %u %s' % (x[1], x[0]) + print(' %u %s' % (x[1], x[0])) else: for filename, lineno, symbol in matches: if isinstance(symbol, Symbol): args = filename, lineno, symbol.book.name, symbol.since, symbol.name - print '%s:%d: %s-%s required for %s' % args + print('%s:%d: %s-%s required for %s' % args) elif options.verbose: - print '%s:%d: unknown symbol %s' % (filename, lineno, symbol) + print('%s:%d: unknown symbol %s' % (filename, lineno, symbol)) if options.unknown: unknown = [m[2].split('_')[0].lower() for m in unknown_symbols] unknown = list(set(unknown)) unknown.sort() - print 'unknown prefixes: %s' % ', '.join(unknown) + print('unknown prefixes: %s' % ', '.join(unknown)) raise SystemExit(matches and 1 or 0) diff --git a/gtkdoc-fixxref.in b/gtkdoc-fixxref.in index 3d9e8d0..0ea02d4 100755 --- a/gtkdoc-fixxref.in +++ b/gtkdoc-fixxref.in @@ -1,8 +1,9 @@ -#!@PERL@ -w -# -*- cperl -*- +#!@PYTHON@ +# -*- python -*- # # gtk-doc - GTK DocBook documentation generator. # Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -19,579 +20,38 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -############################################################################# -# Script : gtkdoc-fixxref -# Description : This fixes cross-references in the HTML documentation. -############################################################################# - -use strict; -use bytes; -use Getopt::Long; - -push @INC, '@PACKAGE_DATA_DIR@'; -require "gtkdoc-common.pl"; - -# Options - -# name of documentation module -my $MODULE; -my $MODULE_DIR; -my $HTML_DIR = ""; -my @EXTRA_DIRS; -my $PRINT_VERSION; -my $PRINT_HELP; -my $SRC_LANG; - -# This contains all the entities and their relative URLs. -my %Links; - -# failing link targets we don't warn about even once -my %NoLinks = ( - 'char' => 1, - 'double' => 1, - 'float' => 1, - 'int' => 1, - 'long' => 1, - 'main' => 1, - 'signed' => 1, - 'unsigned' => 1, - 'va-list' => 1, - 'void' => 1, - 'GBoxed' => 1, - 'GEnum' => 1, - 'GFlags' => 1, - 'GInterface' => 1 -); - -# Cache of dirs we already scanned for index files -my %DirCache; - -run() unless caller; # Run program unless loaded as a module - - -sub run { - my %optctl = ('module' => \$MODULE, - 'module-dir' => \$MODULE_DIR, - 'html-dir' => \$HTML_DIR, - 'extra-dir' => \@EXTRA_DIRS, - 'version' => \$PRINT_VERSION, - 'help' => \$PRINT_HELP, - 'src-lang' => \$SRC_LANG); - - GetOptions(\%optctl, "module=s", "module-dir=s", "html-dir:s", "extra-dir=s@", - "src-lang=s", "version", "help"); - - if ($PRINT_VERSION) { - print "@VERSION@\n"; - exit 0; - } - - if ($PRINT_HELP) { - print <) { - if (m/ link="([^#]*)#([^"]*)"/) { - @TRACE@("Found id: $2 href: $1#$2"); - $Links{$2} = "$dir$1#$2"; - } - } - close (INDEXFILE); -} - - -sub ReadSections { - if (!defined($MODULE)) { - return; - } - - open (INPUT, "$MODULE-sections.txt") - || die "Can't open $MODULE-sections.txt: $!"; - my $subsection = ""; - while () { - if (m/^#/) { - next; - - } elsif (m/^
/) { - $subsection = ""; - } elsif (m/^/i) { - $subsection = $1; - } elsif (m/^/) { - next; - } elsif (m/^(.*)<\/TITLE>/) { - next; - } elsif (m/^<FILE>(.*)<\/FILE>/) { - next; - } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) { - next; - } elsif (m/^<\/SECTION>/) { - next; - } elsif (m/^(\S+)/) { - my $symbol=$1; - - if ($subsection eq "Standard" || $subsection eq "Private") { - $NoLinks{CreateValidSGMLID($symbol)} = 1; - } - } - } - close (INPUT); -} - - -sub FixCrossReferences { - my ($scan_dir) = @_; - - opendir (HTMLDIR, $scan_dir) - || die "Can't open HTML directory $scan_dir: $!"; - my $file; - foreach $file (readdir (HTMLDIR)) { - if ($file eq '.' || $file eq '..') { - next; - } elsif ($file =~ m/.html?$/) { - &FixHTMLFile ("$scan_dir/$file"); - } - } - closedir (HTMLDIR); -} - - -sub FixHTMLFile { - my ($file) = @_; - @TRACE@("Fixing file: $file"); - - open (HTMLFILE, $file) - || die "Can't open $file: $!"; - undef $/; - my $entire_file = <HTMLFILE>; - close (HTMLFILE); - - if ("@HIGHLIGHT@" ne "") { - # FIXME: ideally we'd pass a clue about the example language to the highligher - # unfortunately the "language" attribute is not appearing in the html output - # we could patch the customization to have <code class="xxx"> inside of <pre> - if ("@HIGHLIGHT@" =~ m%/vim$%) { - $entire_file =~ s%<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>%&HighlightSourceVim($1,$2);%gse; - } - else { - $entire_file =~ s%<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>%&HighlightSource($1,$2);%gse; - } - # this just broke existing GTKDOCLINK tags - # <GTKDOCLINK HREF="GST-PAD-SINK:CAPS">GST_PAD_SINK</GTKDOCLINK> - $entire_file =~ s%\<GTKDOCLINK\s+HREF=\"(.*?)\"\>(.*?)\</GTKDOCLINK\>%\<GTKDOCLINK\ HREF=\"$1\"\>$2\</GTKDOCLINK\>%gs; - - # from the highlighter we get all the functions marked up - # now we could turn them into GTKDOCLINK items - $entire_file =~ s%(<span class=\"function\">)(.*?)(</span>)%&MakeGtkDocLink($1,$2,$3);%gse; - # we could also try the first item in stuff marked up as 'normal' - $entire_file =~ s%(<span class=\"normal\">\s*)(.+?)((\s+.+?)?\s*</span>)%&MakeGtkDocLink($1,$2,$3);%gse; - } - - my @lines = split(/\n/, $entire_file); - for (my $i=0; $i<$#lines; $i++) { - $lines[$i] =~ s%<GTKDOCLINK\s+HREF="([^"]*)"\s*>(.*?)</GTKDOCLINK\s*>% &MakeXRef($file,$i+1,$1,$2); %ge; - #if ($lines[$i] =~ m/GTKDOCLINK/) { - # print "make xref failed for line: ",$lines[$i], "\n"; - #} - } - $entire_file = join("\n",@lines); - - open (NEWFILE, ">$file.new") - || die "Can't open $file: $!"; - print NEWFILE $entire_file; - close (NEWFILE); - - unlink ($file) - || die "Can't delete $file: $!"; - rename ("$file.new", $file) - || die "Can't rename $file.new: $!"; -} - -sub MakeXRef { - my ($file, $line, $id, $text) = @_; - - my $href = $Links{$id}; - - # this is a workaround for some inconsistency we have with CreateValidSGMLID - if (!$href && $id =~ m/:/) { - my $tid = $id; - $tid =~ s/:/--/g; - $href = $Links{$tid}; - } - # poor mans plural support - if (!$href && $id =~ m/s$/) { - my $tid = $id; - $tid =~ s/s$//g; - $href = $Links{$tid}; - if (!$href && defined $Links{"$tid-struct"}) { - $href = $Links{"$tid-struct"}; - } - } - if (!$href && defined $Links{"$id-struct"}) { - $href = $Links{"$id-struct"}; - } - - if ($href) { - # if it is a link to same module, remove path to make it work - # uninstalled - if (defined($MODULE) && $href =~ m%^\.\./$MODULE/(.*)$%) { - $href=$1; - @TRACE@(" Fixing link to uninstalled doc: $id, $href, $text"); - } else { - @TRACE@(" Fixing link: $id, $href, $text"); - } - return "<a href=\"$href\">$text</a>"; - } else { - my $warn = 1; - @TRACE@(" no link for: $id, $text"); - - # don't warn multiple times and also skip blacklisted (ctypes) - $warn = 0 if exists $NoLinks{$id}; - # if it's a function, don't warn if it does not contain a "_" - # (transformed to "-") - # - gnome coding style would use '_' - # - will avoid wrong warnings for ansi c functions - $warn = 0 if ($text =~ m/ class=\"function\"/ && $id !~ m/-/); - # if it's a 'return value', don't warn (implicitly created link) - $warn = 0 if ($text =~ m/ class=\"returnvalue\"/); - # if it's a 'type', don't warn if it starts with lowercase - # - gnome coding style would use CamelCase - $warn = 0 if ($text =~ m/ class=\"type\"/ && ($id =~ m/^[a-z]/)); - # don't warn for self links - $warn = 0 if ($text eq $id); - - if ($warn == 1) { - &LogWarning ($file, $line, "no link for: '$id' -> ($text)."); - $NoLinks{$id} = 1; - } - return $text; - } -} - - -sub MakeGtkDocLink { - my ($pre,$symbol,$post) = @_; - - my $id=CreateValidSGMLID($symbol); - - # these are implicitely created links in highlighed sources - # we don't want warnings for those if the links cannot be resolved. - $NoLinks{$id} = 1; - - #return "<span class=\"$type\"><GTKDOCLINK HREF=\"$id\">$symbol</GTKDOCLINK></span>"; - return "$pre<GTKDOCLINK HREF=\"$id\">$symbol</GTKDOCLINK>$post"; -} - - -sub HighlightSource { - my ($type, $source) = @_; - - # chop of leading and trailing empty lines - $source =~ s/^\s*\n+//gs; - $source =~ s/[\s\n]+$//gs; - # cut common indent - $source =~ m/^(\s*)/; - $source =~ s/^$1//gms; - # avoid double entity replacement - $source =~ s/</</g; - $source =~ s/>/>/g; - $source =~ s/&/&/g; - - # write source to a temp file - # FIXME: use .c for now to hint the language to the highlighter - my $temp_source_file="$MODULE_DIR/_temp_src.$$.c"; - open (NEWFILE, ">$temp_source_file") || die "Can't open $temp_source_file: $!"; - print NEWFILE $source; - close (NEWFILE); - - @TRACE@(" running @HIGHLIGHT@ @HIGHLIGHT_OPTIONS@$temp_source_file "); - - # format source - my $highlighted_source=`@HIGHLIGHT@ @HIGHLIGHT_OPTIONS@$temp_source_file`; - if ("@HIGHLIGHT@" =~ m%/source-highlight$%) { - $highlighted_source =~ s%^<\!-- .*? -->%%gs; - $highlighted_source =~ s%<pre><tt>(.*?)</tt></pre>%$1%gs; - } - elsif ("@HIGHLIGHT@" =~ m%/highlight$%) { - # need to rewrite the stylesheet classes - $highlighted_source =~ s%<span class="gtkdoc com">%<span class="comment">%gs; - $highlighted_source =~ s%<span class="gtkdoc dir">%<span class="preproc">%gs; - $highlighted_source =~ s%<span class="gtkdoc kwd">%<span class="function">%gs; - $highlighted_source =~ s%<span class="gtkdoc kwa">%<span class="keyword">%gs; - $highlighted_source =~ s%<span class="gtkdoc line">%<span class="linenum">%gs; - $highlighted_source =~ s%<span class="gtkdoc num">%<span class="number">%gs; - $highlighted_source =~ s%<span class="gtkdoc str">%<span class="string">%gs; - $highlighted_source =~ s%<span class="gtkdoc sym">%<span class="symbol">%gs; - # maybe also do - # $highlighted_source =~ s%</span>(.+)<span%</span><span class="normal">$1</span><span%gs; - } - # remove temp file - unlink ($temp_source_file) - || die "Can't delete $temp_source_file: $!"; - - return &HighlightSourcePostprocess($type, $highlighted_source); -} - - -sub HighlightSourceVim { - my ($type, $source) = @_; - - # chop of leading and trailing empty lines - $source =~ s/^\s*\n+//gs; - $source =~ s/[\s\n]+$//gs; - # cut common indent - $source =~ m/^(\s*)/; - $source =~ s/^$1//gms; - # avoid double entity replacement - $source =~ s/</</g; - $source =~ s/>/>/g; - $source =~ s/&/&/g; - - # write source to a temp file - my $temp_source_file="$MODULE_DIR/_temp_src.$$.h"; - open (NEWFILE, ">$temp_source_file") || die "Can't open $temp_source_file: $!"; - print NEWFILE $source; - close (NEWFILE); - - # format source - system "echo 'let html_number_lines=0|let html_use_css=1|let html_use_xhtml=1|e $temp_source_file|syn on|set syntax=$SRC_LANG|run! syntax/2html.vim|w! $temp_source_file.html|qa!' | @HIGHLIGHT@ -n -e -u NONE -T xterm >/dev/null"; - - my $highlighted_source; - { - local $/; - open (NEWFILE, "<$temp_source_file.html"); - $highlighted_source = <NEWFILE>; - close (NEWFILE); - } - $highlighted_source =~ s#.*<pre\b[^>]*>\n##s; - $highlighted_source =~ s#</pre>.*##s; - - # need to rewrite the stylesheet classes - # FIXME: Vim has somewhat different syntax groups - $highlighted_source =~ s%<span class="Comment">%<span class="comment">%gs; - $highlighted_source =~ s%<span class="PreProc">%<span class="preproc">%gs; - $highlighted_source =~ s%<span class="Statement">%<span class="keyword">%gs; - $highlighted_source =~ s%<span class="Identifier">%<span class="function">%gs; - $highlighted_source =~ s%<span class="Constant">%<span class="number">%gs; - $highlighted_source =~ s%<span class="Special">%<span class="symbol">%gs; - $highlighted_source =~ s%<span class="Type">%<span class="type">%gs; - - # remove temp files - unlink ($temp_source_file) - || die "Can't delete $temp_source_file: $!"; - unlink ("$temp_source_file.html") - || die "Can't delete $temp_source_file.html: $!"; - - return &HighlightSourcePostprocess($type, $highlighted_source); -} - - -sub HighlightSourcePostprocess { - my ($type, $highlighted_source) = @_; - - # chop of leading and trailing empty lines - $highlighted_source =~ s/^[\s\n]+//gs; - $highlighted_source =~ s/[\s\n]+$//gs; - - # turn common urls in comments into links - $highlighted_source =~ s%<span class="url">(.*?)</span>%<span class="url"><a href="$1">$1</a></span>%gs; - - # we do own line-numbering - my $source_lines=""; - my $line_count = () = $highlighted_source =~ /\n/gs; - for (my $i=1; $i < ($line_count+2); $i++) { - $source_lines.="$i\n"; - } - $source_lines =~ s/\n\Z//; - - return <<END_OF_HTML -<div class="$type"> - <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> - <tbody> - <tr> - <td class="listing_lines" align="right"><pre>$source_lines</pre></td> - <td class="listing_code"><pre class="programlisting">$highlighted_source</pre></td> - </tr> - </tbody> - </table> -</div> -END_OF_HTML -} +import argparse +import os +import sys +sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, fixxref + + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-fixxref version %s - fix cross references in html files' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--module', required=True, + help='Name of the doc module being processed.') + parser.add_argument('--module-dir', default='', + help='The directory which contains the generated HTML.') + parser.add_argument('--html-dir', default='', + help='The directory where gtk-doc generated documentation is' + 'installed.') + parser.add_argument('--extra-dir', default=[], action='append', + help='Directories to recursively scan for indices (index.sgml)' + 'in addition to HTML_DIR') + parser.add_argument('--src-lang', default='c', + help='Programing language used for syntax highlighting. The' + 'available languages depend on the source' + 'highlighter you use.') + + options = parser.parse_args() + + if not options.module_dir: + options.module_dir = os.path.join(options.html_dir, options.module) + + common.setup_logging() + + fixxref.Run(options) diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in index 8dd6d5e..42d5731 100755 --- a/gtkdoc-mkdb.in +++ b/gtkdoc-mkdb.in @@ -1,9 +1,9 @@ -#!@PERL@ -w -# -*- cperl -*- +#!@PYTHON@ +# -*- python; coding: utf-8 -*- # # gtk-doc - GTK DocBook documentation generator. # Copyright (C) 1998 Damon Chaplin -# 2007,2008,2009 Stefan Kost +# 2007-2016 Stefan Sauer # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -20,6240 +20,42 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -############################################################################# -# Script : gtkdoc-mkdb -# Description : This creates the DocBook files from the edited templates. -############################################################################# - -use warnings; -use strict; -use Getopt::Long; - -push @INC, '@PACKAGE_DATA_DIR@'; -require "gtkdoc-common.pl"; - -# Options - -# name of documentation module -my $MODULE; -my $TMPL_DIR; -my $DB_OUTPUT_DIR; -my @SOURCE_DIRS; -my $SOURCE_SUFFIXES = ""; -my $IGNORE_FILES = ""; -my $PRINT_VERSION; -my $PRINT_HELP; -my $MAIN_SGML_FILE; -my $EXPAND_CONTENT_FILES = ""; -my $INLINE_MARKUP_MODE; -my $DEFAULT_STABILITY; -my $DEFAULT_INCLUDES; -my $OUTPUT_FORMAT; -my $NAME_SPACE = ""; -my $OUTPUT_ALL_SYMBOLS; -my $OUTPUT_SYMBOLS_WITHOUT_SINCE; -my $ROOT_DIR = "."; -my $OBJECT_TREE_FILE; -my $INTERFACES_FILE; -my $PREREQUISITES_FILE; -my $SIGNALS_FILE; -my $ARGS_FILE; - -# These global arrays store information on signals. Each signal has an entry -# in each of these arrays at the same index, like a multi-dimensional array. -my @SignalObjects; # The GtkObject which emits the signal. -my @SignalNames; # The signal name. -my @SignalReturns; # The return type. -my @SignalFlags; # Flags for the signal -my @SignalPrototypes; # The rest of the prototype of the signal handler. - -# These global arrays store information on Args. Each Arg has an entry -# in each of these arrays at the same index, like a multi-dimensional array. -my @ArgObjects; # The GtkObject which has the Arg. -my @ArgNames; # The Arg name. -my @ArgTypes; # The Arg type - gint, GtkArrowType etc. -my @ArgFlags; # How the Arg can be used - readable/writable etc. -my @ArgNicks; # The nickname of the Arg. -my @ArgBlurbs; # Docstring of the Arg. -my @ArgDefaults; # Default value of the Arg. -my @ArgRanges; # The range of the Arg type -# These global hashes store declaration info keyed on a symbol name. -my %Declarations; -my %DeclarationTypes; -my %DeclarationConditional; -my %DeclarationOutput; -my %Deprecated; -my %Since; -my %StabilityLevel; -my %StructHasTypedef; - -# These global hashes store the existing documentation. -my %SymbolDocs; -my %SymbolTypes; -my %SymbolParams; -my %SymbolSourceFile; -my %SymbolSourceLine; -my %SymbolAnnotations; - -# These global hashes store documentation scanned from the source files. -my %SourceSymbolDocs; -my %SourceSymbolParams; -my %SourceSymbolSourceFile; -my %SourceSymbolSourceLine; - -# all documentation goes in here, so we can do coverage analysis -my %AllSymbols; -my %AllIncompleteSymbols; -my %AllUnusedSymbols; -my %AllDocumentedSymbols; - -# Undeclared yet documented symbols -my %UndeclaredSymbols; - -# These global arrays store GObject, subclasses and the hierarchy (also of -# non-object derived types). -my @Objects; -my @ObjectLevels; -my %ObjectRoots; - -my %Interfaces; -my %Prerequisites; - -# holds the symbols which are mentioned in $MODULE-sections.txt and in which -# section they are defined -my %KnownSymbols; -my %SymbolSection; -my %SymbolSectionId; - -# collects index entries -my %IndexEntriesFull; -my %IndexEntriesSince; -my %IndexEntriesDeprecated; - -# Standard C preprocessor directives, which we ignore for '#' abbreviations. -my %PreProcessorDirectives = ( - 'assert' => 1, - 'define' => 1, - 'elif' => 1, - 'else' => 1, - 'endif' => 1, - 'error' => 1, - 'if' => 1, - 'ifdef' => 1, - 'ifndef' => 1, - 'include' => 1, - 'line' => 1, - 'pragma' => 1, - 'unassert' => 1, - 'undef' => 1, - 'warning' => 1 -); - -# remember used annotation (to write minimal glossary) -my %AnnotationsUsed; - -my %AnnotationDefinition = ( - # the GObjectIntrospection annotations are defined at: - # https://live.gnome.org/GObjectIntrospection/Annotations - 'allow-none' => "NULL is OK, both for passing and for returning.", - 'nullable' => "NULL may be passed as the value in, out, in-out; or as a return value.", - 'not nullable' => "NULL must not be passed as the value in, out, in-out; or as a return value.", - 'optional' => "NULL may be passed instead of a pointer to a location.", - 'array' => "Parameter points to an array of items.", - 'attribute' => "Deprecated free-form custom annotation, replaced by (attributes) annotation.", - 'attributes' => "Free-form key-value pairs.", - 'closure' => "This parameter is a 'user_data', for callbacks; many bindings can pass NULL here.", - 'constructor' => "This symbol is a constructor, not a static method.", - 'destroy' => "This parameter is a 'destroy_data', for callbacks.", - 'default' => "Default parameter value (for in case the <acronym>shadows</acronym>-to function has less parameters).", - 'element-type' => "Generics and defining elements of containers and arrays.", - 'error-domains' => "Typed errors. Similar to throws in Java.", - 'foreign' => "This is a foreign struct.", - 'get-value-func' => "The specified function is used to convert a struct from a GValue, must be a GTypeInstance.", - 'in' => "Parameter for input. Default is <acronym>transfer none</acronym>.", - 'inout' => "Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.", - 'in-out' => "Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.", - 'method' => "This is a method", - 'not-error' => "A GError parameter is not to be handled like a normal GError.", - 'out' => "Parameter for returning results. Default is <acronym>transfer full</acronym>.", - 'out caller-allocates' => "Out parameter, where caller must allocate storage.", - 'out callee-allocates' => "Out parameter, where caller must allocate storage.", - 'ref-func' => "The specified function is used to ref a struct, must be a GTypeInstance.", - 'rename-to' => "Rename the original symbol's name to SYMBOL.", - 'scope call' => "The callback is valid only during the call to the method.", - 'scope async' => "The callback is valid until first called.", - 'scope notified' => "The callback is valid until the GDestroyNotify argument is called.", - 'set-value-func' => "The specified function is used to convert from a struct to a GValue, must be a GTypeInstance.", - 'skip' => "Exposed in C code, not necessarily available in other languages.", - 'transfer container' => "Free data container after the code is done.", - 'transfer floating' => "Alias for <acronym>transfer none</acronym>, used for objects with floating refs.", - 'transfer full' => "Free data after the code is done.", - 'transfer none' => "Don't free data after the code is done.", - 'type' => "Override the parsed C type with given type.", - 'unref-func' => "The specified function is used to unref a struct, must be a GTypeInstance.", - 'virtual' => "This is the invoker for a virtual method.", - 'value' => "The specified value overrides the evaluated value of the constant.", - # Stability Level definition - # https://bugzilla.gnome.org/show_bug.cgi?id=170860 - 'Stable' => <<EOF, -The intention of a Stable interface is to enable arbitrary third parties to -develop applications to these interfaces, release them, and have confidence that -they will run on all minor releases of the product (after the one in which the -interface was introduced, and within the same major release). Even at a major -release, incompatible changes are expected to be rare, and to have strong -justifications. -EOF - 'Unstable' => <<EOF, -Unstable interfaces are experimental or transitional. They are typically used to -give outside developers early access to new or rapidly changing technology, or -to provide an interim solution to a problem where a more general solution is -anticipated. No claims are made about either source or binary compatibility from -one minor release to the next. - -The Unstable interface level is a warning that these interfaces are subject to -change without warning and should not be used in unbundled products. - -Given such caveats, customer impact need not be a factor when considering -incompatible changes to an Unstable interface in a major or minor release. -Nonetheless, when such changes are introduced, the changes should still be -mentioned in the release notes for the affected release. -EOF - 'Private' => <<EOF -An interface that can be used within the GNOME stack itself, but that is not -documented for end-users. Such functions should only be used in specified and -documented ways. -EOF -); - -# Elements to consider non-block items in MarkDown parsing -my %MD_TEXT_LEVEL_ELEMENTS = ( "literal" => 1, - "emphasis" => 1, - "envar" => 1, - "filename" => 1, - "firstterm" => 1, - "footnote" => 1, - "function" => 1, - "manvolnum" => 1, - "option" => 1, - "replaceable" => 1, - "structfield" => 1, - "structname" => 1, - "title" => 1, - "varname" => 1 ); -my %MD_ESCAPABLE_CHARS = ( "\\" => 1, - "`" => 1, - "*" => 1, - "_" => 1, - "{" => 1, - "}" => 1, - "[" => 1, - "]" => 1, - "(" => 1, - ")" => 1, - ">" => 1, - "#" => 1, - "+" => 1, - "-" => 1, - "." => 1, - "!" => 1 ); -my %MD_GTK_ESCAPABLE_CHARS = ( "@" => 1, - "%" => 1 ); - -# Function and other declaration output settings. -my $RETURN_TYPE_FIELD_WIDTH = 20; -my $SYMBOL_FIELD_WIDTH = 36; -my $MAX_SYMBOL_FIELD_WIDTH = 40; -my $SIGNAL_FIELD_WIDTH = 16; -my $PARAM_FIELD_COUNT = 2; - -# XML, SGML formatting helper -my $doctype_header; - - -run() unless caller; # Run program unless loaded as a module - - -sub run { - my %optctl = ('module' => \$MODULE, - 'source-dir' => \@SOURCE_DIRS, - 'source-suffixes' => \$SOURCE_SUFFIXES, - 'ignore-files' => \$IGNORE_FILES, - 'output-dir' => \$DB_OUTPUT_DIR, - 'tmpl-dir' => \$TMPL_DIR, - 'version' => \$PRINT_VERSION, - 'help' => \$PRINT_HELP, - 'main-sgml-file' => \$MAIN_SGML_FILE, - 'expand-content-files' => \$EXPAND_CONTENT_FILES, - 'sgml-mode' => \$INLINE_MARKUP_MODE, - 'xml-mode' => \$INLINE_MARKUP_MODE, - 'default-stability' => \$DEFAULT_STABILITY, - 'default-includes' => \$DEFAULT_INCLUDES, - 'output-format' => \$OUTPUT_FORMAT, - 'name-space' => \$NAME_SPACE, - 'outputallsymbols' => \$OUTPUT_ALL_SYMBOLS, - 'outputsymbolswithoutsince' => \$OUTPUT_SYMBOLS_WITHOUT_SINCE - ); - GetOptions(\%optctl, "module=s", "source-dir:s", "source-suffixes:s", - "ignore-files:s", "output-dir:s", "tmpl-dir:s", "version", - "outputallsymbols", "outputsymbolswithoutsince", - "expand-content-files:s", "main-sgml-file:s", "extra-db-files:s", "help", - "sgml-mode", "xml-mode", "default-stability:s", "default-includes:s", - "output-format:s", "name-space:s"); - - if ($PRINT_VERSION) { - print "@VERSION@\n"; - exit 0; - } - - if (!$MODULE) { - $PRINT_HELP = 1; - } - - if ($DEFAULT_STABILITY && $DEFAULT_STABILITY ne "Stable" - && $DEFAULT_STABILITY ne "Private" && $DEFAULT_STABILITY ne "Unstable") { - $PRINT_HELP = 1; - } - - if ($PRINT_HELP) { - print <<EOF; -gtkdoc-mkdb version @VERSION@ - generate docbook files - ---module=MODULE_NAME Name of the doc module being parsed ---source-dir=DIRNAME Directories which contain inline reference material ---source-suffixes=SUFFIXES Suffixes of source files to scan, comma-separated ---ignore-files=FILES A space-separated list of header files/dirs not to - scan ---output-dir=DIRNAME Directory to put the generated DocBook files in ---tmpl-dir=DIRNAME Directory in which template files may be found ---main-sgml-file=FILE File containing the toplevel DocBook file. ---expand-content-files=FILES Extra DocBook files to expand abbreviations in. ---output-format=FORMAT Format to use for the generated docbook, XML or SGML. ---{xml,sgml}-mode Allow DocBook markup in inline documentation. ---default-stability=LEVEL Specify default stability Level. Valid values are - Stable, Unstable, or Private. ---default-includes=FILENAMES Specify default includes for section Synopsis ---name-space=NS Omit namespace in index. ---version Print the version of this program ---help Print this help -EOF - exit 0; - } - - @TRACE@(" ignore files: [$IGNORE_FILES]\n"); - - # check output format - if (! defined($OUTPUT_FORMAT) || ($OUTPUT_FORMAT eq "")) { - $OUTPUT_FORMAT = "xml"; - } else { - $OUTPUT_FORMAT = lc($OUTPUT_FORMAT); - } - if ($OUTPUT_FORMAT ne "xml") { - die "Invalid format '$OUTPUT_FORMAT' passed to --output.format" - } - - if (!$MAIN_SGML_FILE) { - # backwards compatibility - if (-e "${MODULE}-docs.sgml") { - $MAIN_SGML_FILE = "${MODULE}-docs.sgml"; - } else { - $MAIN_SGML_FILE = "${MODULE}-docs.xml"; - } - } - - # extract docbook header or define default - if (-e $MAIN_SGML_FILE) { - open(INPUT, "<$MAIN_SGML_FILE") || die "Can't open $MAIN_SGML_FILE"; - $doctype_header = ""; - while (<INPUT>) { - if (/^\s*<(book|chapter|article)/) { - # check that the top-level tagSYSTEM or the doctype decl contain the xinclude namespace decl - if (($_ !~ m/http:\/\/www.w3.org\/200[13]\/XInclude/) && ($doctype_header !~ m/http:\/\/www.w3.org\/200[13]\/XInclude/m)) { - $doctype_header = ""; - } - last; - } - # if there are SYSTEM ENTITIES here, we should prepend "../" to the path - # FIXME: not sure if we can do this now, as people already work-around the problem - # s#<!ENTITY % ([a-zA-Z-]+) SYSTEM \"([^/][a-zA-Z./]+)\">#<!ENTITY % $1 SYSTEM \"../$2\">#; - s#<!ENTITY % gtkdocentities SYSTEM \"([^"]*)\">#<!ENTITY % gtkdocentities SYSTEM \"../$1\">#; - $doctype_header .= $_; - } - close(INPUT); - } else { - $doctype_header = <<EOF; -<?xml version="1.0"?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" -[ - <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> - <!ENTITY % gtkdocentities SYSTEM "../xml/gtkdocentities.ent"> - %gtkdocentities; -]> -EOF - } - chomp($doctype_header); - - # All the files are written in subdirectories beneath here. - $TMPL_DIR = $TMPL_DIR ? $TMPL_DIR : "$ROOT_DIR/tmpl"; - - # This is where we put all the DocBook output. - $DB_OUTPUT_DIR = $DB_OUTPUT_DIR ? $DB_OUTPUT_DIR : "$ROOT_DIR/xml"; - - # This file contains the object hierarchy. - $OBJECT_TREE_FILE = "$ROOT_DIR/$MODULE.hierarchy"; - - # This file contains the interfaces. - $INTERFACES_FILE = "$ROOT_DIR/$MODULE.interfaces"; - - # This file contains the prerequisites. - $PREREQUISITES_FILE = "$ROOT_DIR/$MODULE.prerequisites"; - - # This file contains signal arguments and names. - $SIGNALS_FILE = "$ROOT_DIR/$MODULE.signals"; - - # The file containing Arg information. - $ARGS_FILE = "$ROOT_DIR/$MODULE.args"; - - # Create the root DocBook output directory if it doens't exist. - if (! -e $DB_OUTPUT_DIR) { - mkdir ("$DB_OUTPUT_DIR", 0777) - || die "Can't create directory: $DB_OUTPUT_DIR"; - } - - &ReadKnownSymbols ("$ROOT_DIR/$MODULE-sections.txt"); - &ReadSignalsFile ($SIGNALS_FILE); - &ReadArgsFile ($ARGS_FILE); - &ReadObjectHierarchy; - &ReadInterfaces; - &ReadPrerequisites; - - &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-decl.txt", 0); - if (-f "$ROOT_DIR/$MODULE-overrides.txt") { - &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-overrides.txt", 1); - } - - for my $dir (@SOURCE_DIRS) { - &ReadSourceDocumentation ($dir); - } - - my $changed = &OutputDB ("$ROOT_DIR/$MODULE-sections.txt"); - - # If any of the DocBook files have changed, update the timestamp file (so - # it can be used for Makefile dependencies). - if ($changed || ! -e "$ROOT_DIR/sgml.stamp") { - - # try to detect the common prefix - # GtkWidget, GTK_WIDGET, gtk_widget -> gtk - if ($NAME_SPACE eq "") { - $NAME_SPACE=""; - my $pos=0; - my $ratio=0.0; - do { - my %prefix; - my $letter=""; - foreach my $symbol (keys(%IndexEntriesFull)) { - if(($NAME_SPACE eq "") || $symbol =~ /^$NAME_SPACE/i) { - if (length($symbol)>$pos) { - $letter=substr($symbol,$pos,1); - # stop prefix scanning - if ($letter eq "_") { - # stop on "_" - last; - } - # Should we also stop on a uppercase char, if last was lowercase - # GtkWidget, if we have the 'W' and had the 't' before - # or should we count upper and lowercase, and stop one 2nd uppercase, if we already had a lowercase - # GtkWidget, the 'W' would be the 2nd uppercase and with 't','k' we had lowercase chars before - # need to recound each time as this is per symbol - $prefix{uc($letter)}++; - } - } - } - if ($letter ne "" && $letter ne "_") { - my $maxletter=""; - my $maxsymbols=0; - foreach $letter (keys(%prefix)) { - #print "$letter: $prefix{$letter}.\n"; - if ($prefix{$letter}>$maxsymbols) { - $maxletter=$letter; - $maxsymbols=$prefix{$letter}; - } - } - $ratio = scalar(keys(%IndexEntriesFull)) / $prefix{$maxletter}; - #print "most symbols start with $maxletter, that is ". (100 * $ratio) ." %\n"; - if ($ratio > 0.9) { - # do another round - $NAME_SPACE .= $maxletter; - } - $pos++; - } - else { - $ratio=0.0; - } - } while ($ratio > 0.9); - #print "most symbols start with $NAME_SPACE\n"; - } - - &OutputIndexFull; - &OutputDeprecatedIndex; - &OutputSinceIndexes; - &OutputAnnotationGlossary; - - open (TIMESTAMP, ">$ROOT_DIR/sgml.stamp") - || die "Can't create $ROOT_DIR/sgml.stamp: $!"; - print (TIMESTAMP "timestamp"); - close (TIMESTAMP); - } -} - -############################################################################# -# Function : OutputObjectList -# Description : This outputs the alphabetical list of objects, in a columned -# table. -# FIXME: Currently this also outputs ancestor objects -# which may not actually be in this module. -# Arguments : none -############################################################################# - -sub OutputObjectList { - my $cols = 3; - - # FIXME: use .xml - # my $old_object_index = "$DB_OUTPUT_DIR/object_index.xml"; - my $old_object_index = "$DB_OUTPUT_DIR/object_index.sgml"; - my $new_object_index = "$DB_OUTPUT_DIR/object_index.new"; - - open (OUTPUT, ">$new_object_index") - || die "Can't create $new_object_index: $!"; - - print (OUTPUT <<EOF); -${\( MakeDocHeader ("informaltable") )} -<informaltable pgwide="1" frame="none"> -<tgroup cols="$cols"> -<colspec colwidth="1*"/> -<colspec colwidth="1*"/> -<colspec colwidth="1*"/> -<tbody> -EOF - - my $count = 0; - my $object; - foreach $object (sort (@Objects)) { - my $xref = &MakeXRef ($object); - if ($count % $cols == 0) { print (OUTPUT "<row>\n"); } - print (OUTPUT "<entry>$xref</entry>\n"); - if ($count % $cols == ($cols - 1)) { print (OUTPUT "</row>\n"); } - $count++; - } - if ($count == 0) { - # emit an empty row, since empty tables are invalid - print (OUTPUT "<row><entry> </entry></row>\n"); - } - else { - if ($count % $cols > 0) { - print (OUTPUT "</row>\n"); - } - } - - print (OUTPUT <<EOF); -</tbody></tgroup></informaltable> -EOF - close (OUTPUT); - - &UpdateFileIfChanged ($old_object_index, $new_object_index, 0); -} - -############################################################################# -# Function : TrimTextBlock -# Description : Trims extra whitespace. Empty lines inside a block are -# preserved. -# Arguments : $desc - the text block to trim. May contain newlines. -############################################################################# - -sub TrimTextBlock { - my ($desc) = @_; - - # strip leading spaces on the block - $desc =~ s/^\s+//s; - # strip trailing spaces on every line - $desc =~ s/\s+$/\n/mg; - - return $desc; -} - - -############################################################################# -# Function : OutputDB -# Description : This collects the output for each section of the docs, and -# outputs each file when the end of the section is found. -# Arguments : $file - the $MODULE-sections.txt file which contains all of -# the functions/macros/structs etc. being documented, organised -# into sections and subsections. -############################################################################# - -sub OutputDB { - my ($file) = @_; - - @TRACE@("Reading: $file\n"); - open (INPUT, $file) - || die "Can't open $file: $!"; - my $filename = ""; - my $book_top = ""; - my $book_bottom = ""; - my $includes = (defined $DEFAULT_INCLUDES) ? $DEFAULT_INCLUDES : ""; - my $section_includes = ""; - my $in_section = 0; - my $title = ""; - my $section_id = ""; - my $subsection = ""; - my $num_symbols; - my $changed = 0; - my $functions_synop = ""; - my $other_synop = ""; - my $functions_details = ""; - my $other_details = ""; - my $signals_synop = ""; - my $signals_desc = ""; - my $args_synop = ""; - my $child_args_synop = ""; - my $style_args_synop = ""; - my $args_desc = ""; - my $child_args_desc = ""; - my $style_args_desc = ""; - my $hierarchy_str = ""; - my @hierarchy = (); - my $interfaces = ""; - my $implementations = ""; - my $prerequisites = ""; - my $derived = ""; - my @file_objects = (); - my %templates = (); - my %symbol_def_line = (); - - # merge the source docs, in case there are no templates - &MergeSourceDocumentation; - - while (<INPUT>) { - if (m/^#/) { - next; - - } elsif (m/^<SECTION>/) { - $num_symbols = 0; - $in_section = 1; - @file_objects = (); - %symbol_def_line = (); - - } elsif (m/^<SUBSECTION\s*(.*)>/i) { - $other_synop .= "\n"; - $functions_synop .= "\n"; - $subsection = $1; - - } elsif (m/^<SUBSECTION>/) { - - } elsif (m/^<TITLE>(.*)<\/TITLE>/) { - $title = $1; - @TRACE@("Section: $title\n"); - - # We don't want warnings if object & class structs aren't used. - $DeclarationOutput{$title} = 1; - $DeclarationOutput{"${title}Class"} = 1; - $DeclarationOutput{"${title}Iface"} = 1; - $DeclarationOutput{"${title}Interface"} = 1; - - } elsif (m/^<FILE>(.*)<\/FILE>/) { - $filename = $1; - if (! defined $templates{$filename}) { - if (&ReadTemplateFile ("$TMPL_DIR/$filename", 1)) { - &MergeSourceDocumentation; - $templates{$filename}=$.; - } - } else { - &LogWarning ($file, $., "Double <FILE>$filename</FILE> entry. ". - "Previous occurrence on line ".$templates{$filename}."."); - } - if (($title eq "") and (defined $SourceSymbolDocs{"$TMPL_DIR/$filename:Title"})) { - $title = $SourceSymbolDocs{"$TMPL_DIR/$filename:Title"}; - # Remove trailing blanks - $title =~ s/\s+$//; - } - - } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) { - if ($in_section) { - $section_includes = $1; - } else { - if (defined $DEFAULT_INCLUDES) { - &LogWarning ($file, $., "Default <INCLUDE> being overridden by command line option."); - } - else { - $includes = $1; - } - } - - } elsif (m/^<\/SECTION>/) { - @TRACE@("End of section: $title\n"); - if ($num_symbols > 0) { - # collect documents - $book_bottom .= " <xi:include href=\"xml/$filename.xml\"/>\n"; - - if (defined ($SourceSymbolDocs{"$TMPL_DIR/$filename:Include"})) { - if ($section_includes) { - &LogWarning ($file, $., "Section <INCLUDE> being overridden by inline comments."); - } - $section_includes = $SourceSymbolDocs{"$TMPL_DIR/$filename:Include"}; - } - if ($section_includes eq "") { - $section_includes = $includes; - } - - $signals_synop =~ s/^\n*//g; - $signals_synop =~ s/\n+$/\n/g; - if ($signals_synop ne '') { - $signals_synop = <<EOF; -<refsect1 id="$section_id.signals" role="signal_proto"> -<title role="signal_proto.title">Signals - - - - - - -${signals_synop} - - - - -EOF - $signals_desc = TrimTextBlock($signals_desc); - $signals_desc = < -Signal Details -$signals_desc - -EOF - } - - $args_synop =~ s/^\n*//g; - $args_synop =~ s/\n+$/\n/g; - if ($args_synop ne '') { - $args_synop = < -Properties - - - - - - -${args_synop} - - - - -EOF - $args_desc = TrimTextBlock($args_desc); - $args_desc = < -Property Details -$args_desc - -EOF - } - - $child_args_synop =~ s/^\n*//g; - $child_args_synop =~ s/\n+$/\n/g; - if ($child_args_synop ne '') { - $args_synop .= < -Child Properties - - - - - - -${child_args_synop} - - - - -EOF - $child_args_desc = TrimTextBlock($child_args_desc); - $args_desc .= < -Child Property Details -$child_args_desc - -EOF - } - - $style_args_synop =~ s/^\n*//g; - $style_args_synop =~ s/\n+$/\n/g; - if ($style_args_synop ne '') { - $args_synop .= < -Style Properties - - - - - - -${style_args_synop} - - - - -EOF - $style_args_desc = TrimTextBlock($style_args_desc); - $args_desc .= < -Style Property Details -$style_args_desc - -EOF - } - - $hierarchy_str = &AddTreeLineArt(\@hierarchy); - if ($hierarchy_str ne "") { - $hierarchy_str = < -Object Hierarchy -$hierarchy_str - - -EOF - } - - $interfaces =~ TrimTextBlock($interfaces); - if ($interfaces ne "") { - $interfaces = < -Implemented Interfaces -$interfaces - -EOF - } - - $implementations = TrimTextBlock($implementations); - if ($implementations ne "") { - $implementations = < -Known Implementations -$implementations - -EOF - } - - $prerequisites = TrimTextBlock($prerequisites); - if ($prerequisites ne "") { - $prerequisites = < -Prerequisites -$prerequisites - -EOF - } - - $derived = TrimTextBlock($derived); - if ($derived ne "") { - $derived = < -Known Derived Interfaces -$derived - -EOF - } - - $functions_synop =~ s/^\n*//g; - $functions_synop =~ s/\n+$/\n/g; - if ($functions_synop ne '') { - $functions_synop = < -Functions - - - - - -${functions_synop} - - - - -EOF - } - - $other_synop =~ s/^\n*//g; - $other_synop =~ s/\n+$/\n/g; - if ($other_synop ne '') { - $other_synop = < -Types and Values - - - - - -${other_synop} - - - - -EOF - } - - my $file_changed = &OutputDBFile ($filename, $title, $section_id, - $section_includes, - \$functions_synop, \$other_synop, - \$functions_details, \$other_details, - \$signals_synop, \$signals_desc, - \$args_synop, \$args_desc, - \$hierarchy_str, \$interfaces, - \$implementations, - \$prerequisites, \$derived, - \@file_objects); - if ($file_changed) { - $changed = 1; - } - } - $title = ""; - $section_id = ""; - $subsection = ""; - $in_section = 0; - $section_includes = ""; - $functions_synop = ""; - $other_synop = ""; - $functions_details = ""; - $other_details = ""; - $signals_synop = ""; - $signals_desc = ""; - $args_synop = ""; - $child_args_synop = ""; - $style_args_synop = ""; - $args_desc = ""; - $child_args_desc = ""; - $style_args_desc = ""; - $hierarchy_str = ""; - @hierarchy = (); - $interfaces = ""; - $implementations = ""; - $prerequisites = ""; - $derived = ""; - - } elsif (m/^(\S+)/) { - my $symbol = $1; - @TRACE@(" Symbol: $symbol in subsection: $subsection\n"); - - # check for duplicate entries - if (! defined $symbol_def_line{$symbol}) { - my $declaration = $Declarations{$symbol}; - if (defined ($declaration)) { - if (&CheckIsObject ($symbol)) { - push @file_objects, $symbol; - } - # We don't want standard macros/functions of GObjects, - # or private declarations. - if ($subsection ne "Standard" && $subsection ne "Private") { - my ($synop, $desc) = &OutputDeclaration ($symbol, - $declaration); - my $type = $DeclarationTypes {$symbol}; - - if ($type eq 'FUNCTION' || $type eq 'USER_FUNCTION') { - $functions_synop .= $synop; - $functions_details .= $desc; - } elsif ($type eq 'MACRO' && $declaration =~ /$symbol\(/) { - $functions_synop .= $synop; - $functions_details .= $desc; - } else { - $other_synop .= $synop; - $other_details .= $desc; - } - } - my ($sig_synop, $sig_desc) = &GetSignals ($symbol); - my ($arg_synop, $child_arg_synop, $style_arg_synop, - $arg_desc, $child_arg_desc, $style_arg_desc) = &GetArgs ($symbol); - my $ifaces = &GetInterfaces ($symbol); - my $impls = &GetImplementations ($symbol); - my $prereqs = &GetPrerequisites ($symbol); - my $der = &GetDerived ($symbol); - @hierarchy = &GetHierarchy ($symbol, \@hierarchy); - - $signals_synop .= $sig_synop; - $signals_desc .= $sig_desc; - $args_synop .= $arg_synop; - $child_args_synop .= $child_arg_synop; - $style_args_synop .= $style_arg_synop; - $args_desc .= $arg_desc; - $child_args_desc .= $child_arg_desc; - $style_args_desc .= $style_arg_desc; - $interfaces .= $ifaces; - $implementations .= $impls; - $prerequisites .= $prereqs; - $derived .= $der; - - # Note that the declaration has been output. - $DeclarationOutput{$symbol} = 1; - } elsif ($subsection ne "Standard" && $subsection ne "Private") { - $UndeclaredSymbols{$symbol} = 1; - &LogWarning ($file, $., "No declaration found for $symbol."); - } - $num_symbols++; - $symbol_def_line{$symbol}=$.; - - if ($section_id eq "") { - if($title eq "" && $filename eq "") { - &LogWarning ($file, $., "Section has no title and no file."); - } - # FIXME: one of those would be enough - # filename should be an internal detail for gtk-doc - if ($title eq "") { - $title = $filename; - } elsif ($filename eq "") { - $filename = $title; - } - $filename =~ s/\s/_/g; - - $section_id = $SourceSymbolDocs{"$TMPL_DIR/$filename:Section_Id"}; - if (defined ($section_id) && $section_id !~ m/^\s*$/) { - # Remove trailing blanks and use as is - $section_id =~ s/\s+$//; - } elsif (&CheckIsObject ($title)) { - # GObjects use their class name as the ID. - $section_id = &CreateValidSGMLID ($title); - } else { - $section_id = &CreateValidSGMLID ("$MODULE-$title"); - } - } - $SymbolSection{$symbol}=$title; - $SymbolSectionId{$symbol}=$section_id; - } - else { - &LogWarning ($file, $., "Double symbol entry for $symbol. ". - "Previous occurrence on line ".$symbol_def_line{$symbol}."."); - } - } - } - close (INPUT); - - &OutputMissingDocumentation; - &OutputUndeclaredSymbols; - &OutputUnusedSymbols; - - if ($OUTPUT_ALL_SYMBOLS) { - &OutputAllSymbols; - } - if ($OUTPUT_SYMBOLS_WITHOUT_SINCE) { - &OutputSymbolsWithoutSince; - } - - for $filename (split (' ', $EXPAND_CONTENT_FILES)) { - my $file_changed = &OutputExtraFile ($filename); - if ($file_changed) { - $changed = 1; - } - } - - &OutputBook ($book_top, $book_bottom); - - return $changed; -} - -############################################################################# -# Function : OutputIndex -# Description : This writes an indexlist that can be included into the main- -# document into an tag. -############################################################################# - -sub OutputIndex { - my ($basename, $apiindexref ) = @_; - my %apiindex = %{$apiindexref}; - my $old_index = "$DB_OUTPUT_DIR/$basename.xml"; - my $new_index = "$DB_OUTPUT_DIR/$basename.new"; - my $lastletter = " "; - my $divopen = 0; - my $symbol; - my $short_symbol; - - open (OUTPUT, ">$new_index") - || die "Can't create $new_index"; - - print (OUTPUT &MakeDocHeader ("indexdiv")."\n\n"); - - @TRACE@("generate $basename index (".%apiindex." entries)\n"); - - # do a case insensitive sort while chopping off the prefix - foreach my $hash ( - sort { $$a{criteria} cmp $$b{criteria} or $$a{original} cmp $$b{original} } - map { my $x = uc($_); $x =~ s/^$NAME_SPACE\_?(.*)/$1/i; { criteria => $x, original => $_, short => $1 } } - keys %apiindex) { - - $symbol = $$hash{original}; - if (defined($$hash{short})) { - $short_symbol = $$hash{short}; - } else { - $short_symbol = $symbol; - } - - # generate a short symbol description - my $symbol_desc = ""; - my $symbol_section = ""; - my $symbol_section_id = ""; - my $symbol_type = ""; - if (defined($DeclarationTypes{$symbol})) { - $symbol_type = lc($DeclarationTypes{$symbol}); - } - if ($symbol_type eq "") { - @TRACE@("trying symbol $symbol\n"); - if ($symbol =~ m/(.*)::(.*)/) { - my $oname = $1; - my $osym = $2; - my $i; - @TRACE@(" trying object signal ${oname}:$osym in ".$#SignalNames." signals\n"); - for ($i = 0; $i <= $#SignalNames; $i++) { - if ($SignalNames[$i] eq $osym) { - $symbol_type = "object signal"; - if (defined($SymbolSection{$oname})) { - $symbol_section = $SymbolSection{$oname}; - $symbol_section_id = $SymbolSectionId{$oname}; - } - last; - } - } - } elsif ($symbol =~ m/(.*):(.*)/) { - my $oname = $1; - my $osym = $2; - my $i; - @TRACE@(" trying object property ${oname}::$osym in ".$#ArgNames." properties\n"); - for ($i = 0; $i <= $#ArgNames; $i++) { - @TRACE@(" ".$ArgNames[$i]."\n"); - if ($ArgNames[$i] eq $osym) { - $symbol_type = "object property"; - if (defined($SymbolSection{$oname})) { - $symbol_section = $SymbolSection{$oname}; - $symbol_section_id = $SymbolSectionId{$oname}; - } - last; - } - } - } - } else { - if (defined($SymbolSection{$symbol})) { - $symbol_section = $SymbolSection{$symbol}; - $symbol_section_id = $SymbolSectionId{$symbol}; - } - } - if ($symbol_type ne "") { - $symbol_desc=", $symbol_type"; - if ($symbol_section ne "") { - $symbol_desc.=" in $symbol_section"; - #$symbol_desc.=" in ". &ExpandAbbreviations($symbol, "#$symbol_section"); - } - } - - my $curletter = uc(substr($short_symbol,0,1)); - my $id = $apiindex{$symbol}; - - @TRACE@(" add symbol $symbol with $id to index in section $curletter\n"); - - if ($curletter ne $lastletter) { - $lastletter = $curletter; - - if ($divopen == 1) { - print (OUTPUT "\n"); - } - print (OUTPUT "$curletter\n"); - $divopen = 1; - } - - print (OUTPUT <$symbol$symbol_desc -EOF - } - - if ($divopen == 1) { - print (OUTPUT "\n"); - } - print (OUTPUT "\n"); - close (OUTPUT); - - &UpdateFileIfChanged ($old_index, $new_index, 0); -} - - -############################################################################# -# Function : OutputIndexFull -# Description : This writes the full api indexlist that can be included into the -# main document into an tag. -############################################################################# - -sub OutputIndexFull { - &OutputIndex ("api-index-full", \%IndexEntriesFull); -} - - -############################################################################# -# Function : OutputDeprecatedIndex -# Description : This writes the deprecated api indexlist that can be included -# into the main document into an tag. -############################################################################# - -sub OutputDeprecatedIndex { - &OutputIndex ("api-index-deprecated", \%IndexEntriesDeprecated); -} - - -############################################################################# -# Function : OutputSinceIndexes -# Description : This writes the 'since' api indexlists that can be included into -# the main document into an tag. -############################################################################# - -sub OutputSinceIndexes { - my @sinces = keys %{{ map { $_ => 1 } values %Since }}; - - foreach my $version (@sinces) { - @TRACE@("Since : [$version]\n"); - # TODO make filtered hash - #my %index = grep { $Since{$_} eq $version } %IndexEntriesSince; - my %index = map { $_ => $IndexEntriesSince{$_} } grep { $Since{$_} eq $version } keys %IndexEntriesSince; - - &OutputIndex ("api-index-$version", \%index); - } -} - -############################################################################# -# Function : OutputAnnotationGlossary -# Description : This writes a glossary of the used annotation terms into a -# separate glossary file that can be included into the main -# document. -############################################################################# - -sub OutputAnnotationGlossary { - my $old_glossary = "$DB_OUTPUT_DIR/annotation-glossary.xml"; - my $new_glossary = "$DB_OUTPUT_DIR/annotation-glossary.new"; - my $lastletter = " "; - my $divopen = 0; - - # if there are no annotations used return - return if (! keys(%AnnotationsUsed)); - - # add acronyms that are referenced from acronym text -rerun: - foreach my $annotation (keys(%AnnotationsUsed)) { - if(defined($AnnotationDefinition{$annotation})) { - if($AnnotationDefinition{$annotation} =~ m/([\w ]+)<\/acronym>/) { - if (!exists($AnnotationsUsed{$1})) { - $AnnotationsUsed{$1} = 1; - goto rerun; - } - } - } - } - - open (OUTPUT, ">$new_glossary") - || die "Can't create $new_glossary"; - - print (OUTPUT < - Annotation Glossary -EOF - - foreach my $annotation (sort({lc $a cmp lc $b} keys(%AnnotationsUsed))) { - if(defined($AnnotationDefinition{$annotation})) { - my $def = $AnnotationDefinition{$annotation}; - my $curletter = uc(substr($annotation,0,1)); - - if ($curletter ne $lastletter) { - $lastletter = $curletter; - - if ($divopen == 1) { - print (OUTPUT "\n"); - } - print (OUTPUT "$curletter\n"); - $divopen = 1; - } - print (OUTPUT < - $annotation - - $def - - -EOF - } - } - - if ($divopen == 1) { - print (OUTPUT "\n"); - } - print (OUTPUT "\n"); - close (OUTPUT); - - &UpdateFileIfChanged ($old_glossary, $new_glossary, 0); -} - -############################################################################# -# Function : ReadKnownSymbols -# Description : This collects the names of non-private symbols from the -# $MODULE-sections.txt file. -# Arguments : $file - the $MODULE-sections.txt file which contains all of -# the functions/macros/structs etc. being documented, organised -# into sections and subsections. -############################################################################# - -sub ReadKnownSymbols { - my ($file) = @_; - - my $subsection = ""; - - @TRACE@("Reading: $file\n"); - open (INPUT, $file) - || die "Can't open $file: $!"; - - while () { - if (m/^#/) { - next; - - } elsif (m/^
/) { - $subsection = ""; - - } elsif (m/^/i) { - $subsection = $1; - - } elsif (m/^/) { - next; - - } elsif (m/^(.*)<\/TITLE>/) { - next; - - } elsif (m/^<FILE>(.*)<\/FILE>/) { - $KnownSymbols{"$TMPL_DIR/$1:Long_Description"} = 1; - $KnownSymbols{"$TMPL_DIR/$1:Short_Description"} = 1; - next; - - } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) { - next; - - } elsif (m/^<\/SECTION>/) { - next; - - } elsif (m/^(\S+)/) { - my $symbol = $1; - - if ($subsection ne "Standard" && $subsection ne "Private") { - $KnownSymbols{$symbol} = 1; - } - else { - $KnownSymbols{$symbol} = 0; - } - } - } - close (INPUT); -} - - -############################################################################# -# Function : OutputDeclaration -# Description : Returns the synopsis and detailed description DocBook -# describing one function/macro etc. -# Arguments : $symbol - the name of the function/macro begin described. -# $declaration - the declaration of the function/macro. -############################################################################# - -sub OutputDeclaration { - my ($symbol, $declaration) = @_; - - my $type = $DeclarationTypes {$symbol}; - if ($type eq 'MACRO') { - return &OutputMacro ($symbol, $declaration); - } elsif ($type eq 'TYPEDEF') { - return &OutputTypedef ($symbol, $declaration); - } elsif ($type eq 'STRUCT') { - return &OutputStruct ($symbol, $declaration); - } elsif ($type eq 'ENUM') { - return &OutputEnum ($symbol, $declaration); - } elsif ($type eq 'UNION') { - return &OutputUnion ($symbol, $declaration); - } elsif ($type eq 'VARIABLE') { - return &OutputVariable ($symbol, $declaration); - } elsif ($type eq 'FUNCTION') { - return &OutputFunction ($symbol, $declaration, $type); - } elsif ($type eq 'USER_FUNCTION') { - return &OutputFunction ($symbol, $declaration, $type); - } else { - die "Unknown symbol type"; - } -} - - -############################################################################# -# Function : OutputSymbolTraits -# Description : Returns the Since and StabilityLevel paragraphs for a symbol. -# Arguments : $symbol - the name of the function/macro begin described. -############################################################################# - -sub OutputSymbolTraits { - my ($symbol) = @_; - my $desc = ""; - - if (exists $Since{$symbol}) { - my $link_id = "api-index-".$Since{$symbol}; - $desc .= "<para role=\"since\">Since: <link linkend=\"$link_id\">$Since{$symbol}</link></para>"; - } - if (exists $StabilityLevel{$symbol}) { - my $stability = $StabilityLevel{$symbol}; - $AnnotationsUsed{$stability} = 1; - $desc .= "<para role=\"stability\">Stability Level: <acronym>$stability</acronym></para>"; - } - return $desc; -} - -############################################################################# -# Function : Output{Symbol,Section}ExtraLinks -# Description : Returns extralinks for the symbol (if enabled). -# Arguments : $symbol - the name of the function/macro begin described. -############################################################################# - -sub uri_escape { - my $text = $_[0]; - return undef unless defined $text; - - # Build a char to hex map - my %escapes = (); - for (0..255) { - $escapes{chr($_)} = sprintf("%%%02X", $_); - } - - # Default unsafe characters. RFC 2732 ^(uric - reserved) - $text =~ s/([^A-Za-z0-9\-_.!~*'()])/$escapes{$1}/g; - - return $text; -} - -sub OutputSymbolExtraLinks { - my ($symbol) = @_; - my $desc = ""; - - if (0) { # NEW FEATURE: needs configurability - my $sstr = &uri_escape($symbol); - my $mstr = &uri_escape($MODULE); - $desc .= <<EOF; -<ulink role="extralinks" url="http://www.google.com/codesearch?q=$sstr">code search</ulink> -<ulink role="extralinks" url="http://library.gnome.org/edit?module=$mstr&symbol=$sstr">edit documentation</ulink> -EOF - } - return $desc; -} - -sub OutputSectionExtraLinks { - my ($symbol,$docsymbol) = @_; - my $desc = ""; - - if (0) { # NEW FEATURE: needs configurability - my $sstr = &uri_escape($symbol); - my $mstr = &uri_escape($MODULE); - my $dsstr = &uri_escape($docsymbol); - $desc .= <<EOF; -<ulink role="extralinks" url="http://www.google.com/codesearch?q=$sstr">code search</ulink> -<ulink role="extralinks" url="http://library.gnome.org/edit?module=$mstr&symbol=$dsstr">edit documentation</ulink> -EOF - } - return $desc; -} - - -############################################################################# -# Function : OutputMacro -# Description : Returns the synopsis and detailed description of a macro. -# Arguments : $symbol - the macro. -# $declaration - the declaration of the macro. -############################################################################# - -sub OutputMacro { - my ($symbol, $declaration) = @_; - my $id = &CreateValidSGMLID ($symbol); - my $condition = &MakeConditionDescription ($symbol); - my $synop = "<row><entry role=\"define_keyword\">#define</entry><entry role=\"function_name\"><link linkend=\"$id\">$symbol</link>"; - my $desc; - - my @fields = ParseMacroDeclaration($declaration, \&CreateValidSGML); - my $title = $symbol . (@fields ? "()" : ""); - - $desc = "<refsect2 id=\"$id\" role=\"macro\"$condition>\n<title>$title\n"; - $desc .= MakeIndexterms($symbol, $id); - $desc .= "\n"; - $desc .= OutputSymbolExtraLinks($symbol); - - if (@fields) { - $synop .= "()"; - } - $synop .= "\n"; - - # Don't output the macro definition if is is a conditional macro or it - # looks like a function, i.e. starts with "g_" or "_?gnome_", or it is - # longer than 2 lines, otherwise we get lots of complicated macros like - # g_assert. - if (!defined ($DeclarationConditional{$symbol}) && ($symbol !~ m/^g_/) - && ($symbol !~ m/^_?gnome_/) && (($declaration =~ tr/\n//) < 2)) { - my $decl_out = &CreateValidSGML ($declaration); - $desc .= "$decl_out\n"; - } else { - $desc .= "" . &MakeReturnField("#define") . "$symbol"; - if ($declaration =~ m/^\s*#\s*define\s+\w+(\([^\)]*\))/) { - my $args = $1; - my $pad = ' ' x ($RETURN_TYPE_FIELD_WIDTH - length ("#define ")); - # Align each line so that if should all line up OK. - $args =~ s/\n/\n$pad/gm; - $desc .= &CreateValidSGML ($args); - } - $desc .= "\n"; - } - - $desc .= &MakeDeprecationNote($symbol); - - my $parameters = &OutputParamDescriptions ("MACRO", $symbol, @fields); - - if (defined ($SymbolDocs{$symbol})) { - my $symbol_docs = &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - $desc .= $symbol_docs; - } - - $desc .= $parameters; - $desc .= OutputSymbolTraits ($symbol); - $desc .= "\n"; - return ($synop, $desc); -} - - -############################################################################# -# Function : OutputTypedef -# Description : Returns the synopsis and detailed description of a typedef. -# Arguments : $symbol - the typedef. -# $declaration - the declaration of the typedef, -# e.g. 'typedef unsigned int guint;' -############################################################################# - -sub OutputTypedef { - my ($symbol, $declaration) = @_; - my $id = &CreateValidSGMLID ($symbol); - my $condition = &MakeConditionDescription ($symbol); - my $desc = "\n$symbol\n"; - my $synop = "typedef$symbol\n"; - - $desc .= MakeIndexterms($symbol, $id); - $desc .= "\n"; - $desc .= OutputSymbolExtraLinks($symbol); - - if (!defined ($DeclarationConditional{$symbol})) { - my $decl_out = &CreateValidSGML ($declaration); - $desc .= "$decl_out\n"; - } - - $desc .= &MakeDeprecationNote($symbol); - - if (defined ($SymbolDocs{$symbol})) { - $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - } - $desc .= OutputSymbolTraits ($symbol); - $desc .= "\n"; - return ($synop, $desc); -} - - -############################################################################# -# Function : OutputStruct -# Description : Returns the synopsis and detailed description of a struct. -# We check if it is a object struct, and if so we only output -# parts of it that are noted as public fields. -# We also use a different IDs for object structs, since the -# original ID is used for the entire RefEntry. -# Arguments : $symbol - the struct. -# $declaration - the declaration of the struct. -############################################################################# - -sub OutputStruct { - my ($symbol, $declaration) = @_; - - my $is_gtype = 0; - my $default_to_public = 1; - if (&CheckIsObject ($symbol)) { - @TRACE@("Found struct gtype: $symbol\n"); - $is_gtype = 1; - $default_to_public = $ObjectRoots{$symbol} eq 'GBoxed'; - } - - my $id; - my $condition; - if ($is_gtype) { - $id = &CreateValidSGMLID ($symbol . "_struct"); - $condition = &MakeConditionDescription ($symbol . "_struct"); - } else { - $id = &CreateValidSGMLID ($symbol); - $condition = &MakeConditionDescription ($symbol); - } - - # Determine if it is a simple struct or it also has a typedef. - my $has_typedef = 0; - if ($StructHasTypedef{$symbol} || $declaration =~ m/^\s*typedef\s+/) { - $has_typedef = 1; - } - - my $type_output; - my $desc; - if ($has_typedef) { - # For structs with typedefs we just output the struct name. - $type_output = ""; - $desc = "\n$symbol\n"; - } else { - $type_output = "struct"; - $desc = "\nstruct $symbol\n"; - } - my $synop = "${type_output}$symbol\n"; - - $desc .= MakeIndexterms($symbol, $id); - $desc .= "\n"; - $desc .= OutputSymbolExtraLinks($symbol); - - # Form a pretty-printed, private-data-removed form of the declaration - - my $decl_out = ""; - if ($declaration =~ m/^\s*$/) { - @TRACE@("Found opaque struct: $symbol\n"); - $decl_out = "typedef struct _$symbol $symbol;"; - } elsif ($declaration =~ m/^\s*struct\s+\w+\s*;\s*$/) { - @TRACE@("Found opaque struct: $symbol\n"); - $decl_out = "struct $symbol;"; - } else { - my $public = $default_to_public; - my $new_declaration = ""; - my $decl_line; - my $decl = $declaration; - - if ($decl =~ m/^\s*(typedef\s+)?struct\s*\w*\s*(?:\/\*.*\*\/)?\s*{(.*)}\s*\w*\s*;\s*$/s) { - my $struct_contents = $2; - - foreach $decl_line (split (/\n/, $struct_contents)) { - @TRACE@("Struct line: $decl_line\n"); - if ($decl_line =~ m%/\*\s*<\s*public\s*>\s*\*/%) { - $public = 1; - } elsif ($decl_line =~ m%/\*\s*<\s*(private|protected)\s*>\s*\*/%) { - $public = 0; - } elsif ($public) { - $new_declaration .= $decl_line . "\n"; - } - } - - if ($new_declaration) { - # Strip any blank lines off the ends. - $new_declaration =~ s/^\s*\n//; - $new_declaration =~ s/\n\s*$/\n/; - - if ($has_typedef) { - $decl_out = "typedef struct {\n" . $new_declaration - . "} $symbol;\n"; - } else { - $decl_out = "struct $symbol {\n" . $new_declaration - . "};\n"; - } - } - } else { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Couldn't parse struct:\n$declaration"); - } - - # If we couldn't parse the struct or it was all private, output an - # empty struct declaration. - if ($decl_out eq "") { - if ($has_typedef) { - $decl_out = "typedef struct _$symbol $symbol;"; - } else { - $decl_out = "struct $symbol;"; - } - } - } - - $decl_out = &CreateValidSGML ($decl_out); - $desc .= "$decl_out\n"; - - $desc .= &MakeDeprecationNote($symbol); - - if (defined ($SymbolDocs{$symbol})) { - $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - } - - # Create a table of fields and descriptions - - # FIXME: Inserting  's into the produced type declarations here would - # improve the output in most situations ... except for function - # members of structs! - my @fields = ParseStructDeclaration($declaration, !$default_to_public, - 0, \&MakeXRef, - sub { - "$_[0]"; - }); - my $params = $SymbolParams{$symbol}; - - # If no parameters are filled in, we don't generate the description - # table, for backwards compatibility. - - my $found = 0; - if (defined $params) { - for (my $i = 1; $i <= $#$params; $i += $PARAM_FIELD_COUNT) { - if ($params->[$i] =~ /\S/) { - $found = 1; - last; - } - } - } - - if ($found) { - my %field_descrs = @$params; - my $missing_parameters = ""; - my $unused_parameters = ""; - my $id = &CreateValidSGMLID ("$symbol".".members"); - - $desc .= <\nMembers - - - - - - -EOF - - while (@fields) { - my $field_name = shift @fields; - my $text = shift @fields; - my $field_descr = $field_descrs{$field_name}; - my $param_annotations = ""; - - $desc .= "$text\n"; - if (defined $field_descr) { - ($field_descr,$param_annotations) = &ExpandAnnotation($symbol, $field_descr); - $field_descr = &ConvertMarkDown($symbol, $field_descr); - # trim - $field_descr =~ s/^(\s|\n)+//msg; - $field_descr =~ s/(\s|\n)+$//msg; - $desc .= "$field_descr\n$param_annotations\n"; - delete $field_descrs{$field_name}; - } else { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Field description for $symbol"."::"."$field_name is missing in source code comment block."); - if ($missing_parameters ne "") { - $missing_parameters .= ", ".$field_name; - } else { - $missing_parameters = $field_name; - } - $desc .= "\n"; - } - $desc .= "\n"; - } - $desc .= "\n\n"; - foreach my $field_name (keys %field_descrs) { - # Documenting those standard fields is not required anymore, but - # we don't want to warn if they are documented anyway. - if ($field_name =~ /(g_iface|parent_instance|parent_class)/) { - next; - } - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Field description for $symbol"."::"."$field_name is not used from source code comment block."); - if ($unused_parameters ne "") { - $unused_parameters .= ", ".$field_name; - } else { - $unused_parameters = $field_name; - } - } - - # remember missing/unused parameters (needed in tmpl-free build) - if (($missing_parameters ne "") and (! exists ($AllIncompleteSymbols{$symbol}))) { - $AllIncompleteSymbols{$symbol}=$missing_parameters; - } - if (($unused_parameters ne "") and (! exists ($AllUnusedSymbols{$symbol}))) { - $AllUnusedSymbols{$symbol}=$unused_parameters; - } - } - else { - if (scalar(@fields) > 0) { - if (! exists ($AllIncompleteSymbols{$symbol})) { - $AllIncompleteSymbols{$symbol}=""; - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Field descriptions for struct $symbol are missing in source code comment block."); - @TRACE@("Remaining structs fields: ".@fields.":".join(',',@fields)."\n"); - } - } - } - - $desc .= OutputSymbolTraits ($symbol); - $desc .= "\n"; - return ($synop, $desc); -} - - -############################################################################# -# Function : OutputUnion -# Description : Returns the synopsis and detailed description of a union. -# Arguments : $symbol - the union. -# $declaration - the declaration of the union. -############################################################################# - -sub OutputUnion { - my ($symbol, $declaration) = @_; - - my $is_gtype = 0; - if (&CheckIsObject ($symbol)) { - @TRACE@("Found union gtype: $symbol\n"); - $is_gtype = 1; - } - - my $id; - my $condition; - if ($is_gtype) { - $id = &CreateValidSGMLID ($symbol . "_union"); - $condition = &MakeConditionDescription ($symbol . "_union"); - } else { - $id = &CreateValidSGMLID ($symbol); - $condition = &MakeConditionDescription ($symbol); - } - - # Determine if it is a simple struct or it also has a typedef. - my $has_typedef = 0; - if ($StructHasTypedef{$symbol} || $declaration =~ m/^\s*typedef\s+/) { - $has_typedef = 1; - } - - my $type_output; - my $desc; - if ($has_typedef) { - # For unions with typedefs we just output the union name. - $type_output = ""; - $desc = "\n$symbol\n"; - } else { - $type_output = "union"; - $desc = "\nunion $symbol\n"; - } - my $synop = "${type_output}$symbol\n"; - - $desc .= MakeIndexterms($symbol, $id); - $desc .= "\n"; - $desc .= OutputSymbolExtraLinks($symbol); - $desc .= &MakeDeprecationNote($symbol); - - if (defined ($SymbolDocs{$symbol})) { - $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - } - - # Create a table of fields and descriptions - - # FIXME: Inserting  's into the produced type declarations here would - # improve the output in most situations ... except for function - # members of structs! - my @fields = ParseStructDeclaration($declaration, 0, - 0, \&MakeXRef, - sub { - "$_[0]"; - }); - my $params = $SymbolParams{$symbol}; - - # If no parameters are filled in, we don't generate the description - # table, for backwards compatibility - - my $found = 0; - if (defined $params) { - for (my $i = 1; $i <= $#$params; $i += $PARAM_FIELD_COUNT) { - if ($params->[$i] =~ /\S/) { - $found = 1; - last; - } - } - } - - if ($found) { - my %field_descrs = @$params; - my $missing_parameters = ""; - my $unused_parameters = ""; - my $id = &CreateValidSGMLID ("$symbol".".members"); - - $desc .= <\nMembers - - - - - - -EOF - - while (@fields) { - my $field_name = shift @fields; - my $text = shift @fields; - my $field_descr = $field_descrs{$field_name}; - my $param_annotations = ""; - - $desc .= "$text\n"; - if (defined $field_descr) { - ($field_descr,$param_annotations) = &ExpandAnnotation($symbol, $field_descr); - $field_descr = &ConvertMarkDown($symbol, $field_descr); - - # trim - $field_descr =~ s/^(\s|\n)+//msg; - $field_descr =~ s/(\s|\n)+$//msg; - $desc .= "$field_descr\n$param_annotations\n"; - delete $field_descrs{$field_name}; - } else { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Field description for $symbol"."::"."$field_name is missing in source code comment block."); - if ($missing_parameters ne "") { - $missing_parameters .= ", ".$field_name; - } else { - $missing_parameters = $field_name; - } - $desc .= "\n"; - } - $desc .= "\n"; - } - $desc .= "\n"; - foreach my $field_name (keys %field_descrs) { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Field description for $symbol"."::"."$field_name is not used from source code comment block."); - if ($unused_parameters ne "") { - $unused_parameters .= ", ".$field_name; - } else { - $unused_parameters = $field_name; - } - } - - # remember missing/unused parameters (needed in tmpl-free build) - if (($missing_parameters ne "") and (! exists ($AllIncompleteSymbols{$symbol}))) { - $AllIncompleteSymbols{$symbol}=$missing_parameters; - } - if (($unused_parameters ne "") and (! exists ($AllUnusedSymbols{$symbol}))) { - $AllUnusedSymbols{$symbol}=$unused_parameters; - } - } - else { - if (scalar(@fields) > 0) { - if (! exists ($AllIncompleteSymbols{$symbol})) { - $AllIncompleteSymbols{$symbol}=""; - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Field descriptions for union $symbol are missing in source code comment block."); - @TRACE@("Remaining union fields: ".@fields.":".join(',',@fields)."\n"); - } - } - } - - $desc .= OutputSymbolTraits ($symbol); - $desc .= "\n"; - return ($synop, $desc); -} - - -############################################################################# -# Function : OutputEnum -# Description : Returns the synopsis and detailed description of a enum. -# Arguments : $symbol - the enum. -# $declaration - the declaration of the enum. -############################################################################# - -sub OutputEnum { - my ($symbol, $declaration) = @_; - - my $is_gtype = 0; - if (&CheckIsObject ($symbol)) { - @TRACE@("Found enum gtype: $symbol\n"); - $is_gtype = 1; - } - - my $id; - my $condition; - if ($is_gtype) { - $id = &CreateValidSGMLID ($symbol . "_enum"); - $condition = &MakeConditionDescription ($symbol . "_enum"); - } else { - $id = &CreateValidSGMLID ($symbol); - $condition = &MakeConditionDescription ($symbol); - } - - my $synop = "enum$symbol\n"; - my $desc = "\nenum $symbol\n"; - - $desc .= MakeIndexterms($symbol, $id); - $desc .= "\n"; - $desc .= OutputSymbolExtraLinks($symbol); - $desc .= &MakeDeprecationNote($symbol); - - if (defined ($SymbolDocs{$symbol})) { - $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - } - - # Create a table of fields and descriptions - - my @fields = ParseEnumDeclaration($declaration); - my $params = $SymbolParams{$symbol}; - - # If nothing at all is documented log a single summary warning at the end. - # Otherwise, warn about each undocumented item. - - my $found = 0; - if (defined $params) { - for (my $i = 1; $i <= $#$params; $i += $PARAM_FIELD_COUNT) { - if ($params->[$i] =~ /\S/) { - $found = 1; - last; - } - } - } - - my %field_descrs = (defined $params ? @$params : ()); - my $missing_parameters = ""; - my $unused_parameters = ""; - - $id = &CreateValidSGMLID ("$symbol".".members"); - $desc .= <\nMembers - - - - - - -EOF - - for my $field_name (@fields) { - my $field_descr = $field_descrs{$field_name}; - my $param_annotations = ""; - - $id = &CreateValidSGMLID ($field_name); - $condition = &MakeConditionDescription ($field_name); - $desc .= "$field_name\n"; - if (defined $field_descr) { - ($field_descr,$param_annotations) = &ExpandAnnotation($symbol, $field_descr); - $field_descr = &ConvertMarkDown($symbol, $field_descr); - $desc .= "$field_descr\n$param_annotations\n"; - delete $field_descrs{$field_name}; - } else { - if ($found) { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Value description for $symbol"."::"."$field_name is missing in source code comment block."); - if ($missing_parameters ne "") { - $missing_parameters .= ", ".$field_name; - } else { - $missing_parameters = $field_name; - } - } - $desc .= "\n"; - } - $desc .= "\n"; - } - $desc .= "\n"; - foreach my $field_name (keys %field_descrs) { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Value description for $symbol"."::"."$field_name is not used from source code comment block."); - if ($unused_parameters ne "") { - $unused_parameters .= ", ".$field_name; - } else { - $unused_parameters = $field_name; - } - } - - # remember missing/unused parameters (needed in tmpl-free build) - if (($missing_parameters ne "") and (! exists ($AllIncompleteSymbols{$symbol}))) { - $AllIncompleteSymbols{$symbol}=$missing_parameters; - } - if (($unused_parameters ne "") and (! exists ($AllUnusedSymbols{$symbol}))) { - $AllUnusedSymbols{$symbol}=$unused_parameters; - } - - if (!$found) { - if (scalar(@fields) > 0) { - if (! exists ($AllIncompleteSymbols{$symbol})) { - $AllIncompleteSymbols{$symbol}=""; - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Value descriptions for $symbol are missing in source code comment block."); - } - } - } - - $desc .= OutputSymbolTraits ($symbol); - $desc .= "\n"; - return ($synop, $desc); -} - - -############################################################################# -# Function : OutputVariable -# Description : Returns the synopsis and detailed description of a variable. -# Arguments : $symbol - the extern'ed variable. -# $declaration - the declaration of the variable. -############################################################################# - -sub OutputVariable { - my ($symbol, $declaration) = @_; - my $id = &CreateValidSGMLID ($symbol); - my $condition = &MakeConditionDescription ($symbol); - - @TRACE@("ouputing variable: '$symbol' '$declaration'"); - - my $type_output; - if ($declaration =~ m/^\s*extern\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*;/) { - my $mod1 = defined ($1) ? $1 : ""; - my $ptr = defined ($3) ? $3 : ""; - my $space = defined ($4) ? $4 : ""; - my $mod2 = defined ($5) ? $5 : ""; - $type_output = "extern $mod1$ptr$space$mod2"; - } elsif ($declaration =~ m/^\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*=/) { - my $mod1 = defined ($1) ? $1 : ""; - my $ptr = defined ($3) ? $3 : ""; - my $space = defined ($4) ? $4 : ""; - my $mod2 = defined ($5) ? $5 : ""; - $type_output = "$mod1$ptr$space$mod2"; - } else { - $type_output = "extern"; - } - my $synop = "${type_output}$symbol\n"; - - my $desc = "\n$symbol\n"; - - $desc .= MakeIndexterms($symbol, $id); - $desc .= "\n"; - $desc .= OutputSymbolExtraLinks($symbol); - - my $decl_out = &CreateValidSGML ($declaration); - $desc .= "$decl_out\n"; - - $desc .= &MakeDeprecationNote($symbol); - - if (defined ($SymbolDocs{$symbol})) { - $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - } - if (defined ($SymbolAnnotations{$symbol})) { - my $param_desc = $SymbolAnnotations{$symbol}; - my $param_annotations = ""; - ($param_desc,$param_annotations) = &ExpandAnnotation($symbol, $param_desc); - if ($param_annotations ne "") { - $desc .= "\n$param_annotations"; - } - } - - $desc .= OutputSymbolTraits ($symbol); - $desc .= "\n"; - return ($synop, $desc); -} - - -############################################################################# -# Function : OutputFunction -# Description : Returns the synopsis and detailed description of a function. -# Arguments : $symbol - the function. -# $declaration - the declaration of the function. -############################################################################# - -sub OutputFunction { - my ($symbol, $declaration, $symbol_type) = @_; - my $id = &CreateValidSGMLID ($symbol); - my $condition = &MakeConditionDescription ($symbol); - - # Take out the return type $1 $2 $3 - $declaration =~ s/\s*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|enum\s+)*)(\w+)(\s*\**\s*(?:const|G_CONST_RETURN)?\s*\**\s*(?:restrict)?\s*)<\/RETURNS>\n//; - my $type_modifier = defined($1) ? $1 : ""; - my $type = $2; - my $pointer = $3; - # Trim trailing spaces as we are going to pad to $RETURN_TYPE_FIELD_WIDTH below anyway - $pointer =~ s/\s+$//; - my $xref = &MakeXRef ($type, &tagify($type, "returnvalue")); - my $start = ""; - #if ($symbol_type eq 'USER_FUNCTION') { - # $start = "typedef "; - #} - - # We output const rather than G_CONST_RETURN. - $type_modifier =~ s/G_CONST_RETURN/const/g; - $pointer =~ s/G_CONST_RETURN/const/g; - $pointer =~ s/^\s+/ /g; - - my $ret_type_output; - $ret_type_output = "$start$type_modifier$xref$pointer\n"; - - my $indent_len; - $indent_len = length ($symbol) + 2; - my $char1 = my $char2 = my $char3 = ""; - if ($symbol_type eq 'USER_FUNCTION') { - $indent_len += 3; - $char1 = "("; - $char2 = "*"; - $char3 = ")"; - } - - my ($symbol_output, $symbol_desc_output); - $symbol_output = "$char1$char2$symbol$char3"; - if ($indent_len < $MAX_SYMBOL_FIELD_WIDTH) { - $symbol_desc_output = "$char1$char2$symbol$char3 "; - } else { - $indent_len = $MAX_SYMBOL_FIELD_WIDTH - 8; - $symbol_desc_output = "$char1$char2$symbol$char3\n" - . (' ' x ($indent_len - 1)); - } - - my $synop = "${ret_type_output}${symbol_output} ()\n"; - - my $desc = "\n${symbol} ()\n"; - - $desc .= MakeIndexterms($symbol, $id); - $desc .= "\n"; - $desc .= OutputSymbolExtraLinks($symbol); - - $desc .= "${ret_type_output}$symbol_desc_output("; - - my @fields = ParseFunctionDeclaration($declaration, \&MakeXRef, - sub { - &tagify($_[0],"parameter"); - }); - - for (my $i = 1; $i <= $#fields; $i += 2) { - my $field_name = $fields[$i]; - - if ($i == 1) { - $desc .= "$field_name"; - } else { - $desc .= ",\n" - . (' ' x $indent_len) - . "$field_name"; - } - - } - - $desc .= ");\n"; - - $desc .= &MakeDeprecationNote($symbol); - - if (defined ($SymbolDocs{$symbol})) { - $desc .= &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - } - if (defined ($SymbolAnnotations{$symbol})) { - my $param_desc = $SymbolAnnotations{$symbol}; - my $param_annotations = ""; - ($param_desc,$param_annotations) = &ExpandAnnotation($symbol, $param_desc); - if ($param_annotations ne "") { - $desc .= "\n$param_annotations"; - } - } - - $desc .= &OutputParamDescriptions ("FUNCTION", $symbol, @fields); - $desc .= OutputSymbolTraits ($symbol); - $desc .= "\n"; - return ($synop, $desc); -} - - -############################################################################# -# Function : OutputParamDescriptions -# Description : Returns the DocBook output describing the parameters of a -# function, macro or signal handler. -# Arguments : $symbol_type - 'FUNCTION', 'MACRO' or 'SIGNAL'. Signal -# handlers have an implicit user_data parameter last. -# $symbol - the name of the function/macro being described. -# @fields - parsed fields from the declaration, used to determine -# undocumented/unused entries -############################################################################# - -sub OutputParamDescriptions { - my ($symbol_type, $symbol, @fields) = @_; - my $output = ""; - my $params = $SymbolParams{$symbol}; - my $num_params = 0; - my %field_descrs = (); - - if (@fields) { - %field_descrs = @fields; - delete $field_descrs{"void"}; - delete $field_descrs{"Returns"}; - } - - if (defined $params) { - my $returns = ""; - my $params_desc = ""; - my $missing_parameters = ""; - my $unused_parameters = ""; - my $j; - - for ($j = 0; $j <= $#$params; $j += $PARAM_FIELD_COUNT) { - my $param_name = $$params[$j]; - my $param_desc = $$params[$j + 1]; - my $param_annotations = ""; - - ($param_desc,$param_annotations) = &ExpandAnnotation($symbol, $param_desc); - $param_desc = &ConvertMarkDown($symbol, $param_desc); - # trim - $param_desc =~ s/^(\s|\n)+//msg; - $param_desc =~ s/(\s|\n)+$//msg; - if ($param_name eq "Returns") { - $returns = $param_desc; - if ($param_annotations ne "") { - $returns .= "\n$param_annotations"; - } - } elsif ($param_name eq "void") { - # FIXME: &LogWarning()? - @TRACE@("!!!! void in params for $symbol?\n"); - } else { - if (@fields) { - if (!defined $field_descrs{$param_name}) { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Parameter description for $symbol"."::"."$param_name is not used from source code comment block."); - if ($unused_parameters ne "") { - $unused_parameters .= ", ".$param_name; - } else { - $unused_parameters = $param_name; - } - } else { - delete $field_descrs{$param_name}; - } - } - if($param_desc ne "") { - $params_desc .= "$param_name\n$param_desc\n$param_annotations\n"; - $num_params++; - } - } - } - foreach my $param_name (keys %field_descrs) { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Parameter description for $symbol"."::"."$param_name is missing in source code comment block."); - if ($missing_parameters ne "") { - $missing_parameters .= ", ".$param_name; - } else { - $missing_parameters = $param_name; - } - } - - # Signals have an implicit user_data parameter which we describe. - if ($symbol_type eq "SIGNAL") { - $params_desc .= "user_data\nuser data set when the signal handler was connected.\n\n"; - } - - # Start a table if we need one. - if ($params_desc ne "") { - my $id = &CreateValidSGMLID ("$symbol".".parameters"); - - $output .= <\nParameters - - - - - - -EOF - $output .= $params_desc; - $output .= "\n"; - } - - # Output the returns info last - if ($returns ne "") { - my $id = &CreateValidSGMLID ("$symbol".".returns"); - - $output .= <\nReturns -EOF - $output .= $returns; - $output .= "\n"; - } - - # remember missing/unused parameters (needed in tmpl-free build) - if (($missing_parameters ne "") and (! exists ($AllIncompleteSymbols{$symbol}))) { - $AllIncompleteSymbols{$symbol}=$missing_parameters; - } - if (($unused_parameters ne "") and (! exists ($AllUnusedSymbols{$symbol}))) { - $AllUnusedSymbols{$symbol}=$unused_parameters; - } - } - if (($num_params == 0) && @fields && (scalar(keys(%field_descrs)) > 0)) { - if (! exists ($AllIncompleteSymbols{$symbol})) { - $AllIncompleteSymbols{$symbol}=""; - } - } - - return $output; -} - - -############################################################################# -# Function : ParseStabilityLevel -# Description : Parses a stability level and outputs a warning if it isn't -# valid. -# Arguments : $stability - the stability text. -# $file, $line - context for error message -# $message - description of where the level is from, to use in -# any error message. -# Returns : The parsed stability level string. -############################################################################# - -sub ParseStabilityLevel { - my ($stability, $file, $line, $message) = @_; - - $stability =~ s/^\s*//; - $stability =~ s/\s*$//; - if ($stability =~ m/^stable$/i) { - $stability = "Stable"; - } elsif ($stability =~ m/^unstable$/i) { - $stability = "Unstable"; - } elsif ($stability =~ m/^private$/i) { - $stability = "Private"; - } else { - &LogWarning ($file, $line, "$message is $stability.". - "It should be one of these: Stable, Unstable, or Private."); - } - return $stability; -} - - -############################################################################# -# Function : OutputDBFile -# Description : Outputs the final DocBook file for one section. -# Arguments : $file - the name of the file. -# $title - the title from the $MODULE-sections.txt file, which -# will be overridden by the title in the template file. -# $section_id - the id to use for the toplevel tag. -# $includes - comma-separates list of include files added at top of -# synopsis, with '<' '>' around them (if not already enclosed in ""). -# $functions_synop - reference to the DocBook for the Functions Synopsis part. -# $other_synop - reference to the DocBook for the Types and Values Synopsis part. -# $functions_details - reference to the DocBook for the Functions Details part. -# $other_details - reference to the DocBook for the Types and Values Details part. -# $signal_synop - reference to the DocBook for the Signal Synopsis part -# $signal_desc - reference to the DocBook for the Signal Description part -# $args_synop - reference to the DocBook for the Arg Synopsis part -# $args_desc - reference to the DocBook for the Arg Description part -# $hierarchy - reference to the DocBook for the Object Hierarchy part -# $interfaces - reference to the DocBook for the Interfaces part -# $implementations - reference to the DocBook for the Known Implementations part -# $prerequisites - reference to the DocBook for the Prerequisites part -# $derived - reference to the DocBook for the Derived Interfaces part -# $file_objects - reference to an array of objects in this file -############################################################################# - -sub OutputDBFile { - my ($file, $title, $section_id, $includes, $functions_synop, $other_synop, $functions_details, $other_details, $signals_synop, $signals_desc, $args_synop, $args_desc, $hierarchy, $interfaces, $implementations, $prerequisites, $derived, $file_objects) = @_; - - @TRACE@("Output docbook for file $file with title '$title'\n"); - - # The edited title overrides the one from the sections file. - my $new_title = $SymbolDocs{"$TMPL_DIR/$file:Title"}; - if (defined ($new_title) && $new_title !~ m/^\s*$/) { - $title = $new_title; - @TRACE@("Found title: $title\n"); - } - my $short_desc = $SymbolDocs{"$TMPL_DIR/$file:Short_Description"}; - if (!defined ($short_desc) || $short_desc =~ m/^\s*$/) { - $short_desc = ""; - } else { - # Don't use ConvertMarkDown here for now since we don't want blocks - $short_desc = &ExpandAbbreviations("$title:Short_description", - $short_desc); - @TRACE@("Found short_desc: $short_desc"); - } - my $long_desc = $SymbolDocs{"$TMPL_DIR/$file:Long_Description"}; - if (!defined ($long_desc) || $long_desc =~ m/^\s*$/) { - $long_desc = ""; - } else { - $long_desc = &ConvertMarkDown("$title:Long_description", - $long_desc); - @TRACE@("Found long_desc: $long_desc"); - } - my $see_also = $SymbolDocs{"$TMPL_DIR/$file:See_Also"}; - if (!defined ($see_also) || $see_also =~ m%^\s*()?\s*()?\s*$%) { - $see_also = ""; - } else { - $see_also = &ConvertMarkDown("$title:See_Also", $see_also); - @TRACE@("Found see_also: $see_also"); - } - if ($see_also) { - $see_also = "\nSee Also\n$see_also\n\n"; - } - my $stability = $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"}; - if (!defined ($stability) || $stability =~ m/^\s*$/) { - $stability = ""; - } else { - $stability = &ParseStabilityLevel($stability, $file, $., "Section stability level"); - @TRACE@("Found stability: $stability"); - } - if ($stability) { - $AnnotationsUsed{$stability} = 1; - $stability = "\nStability Level\n$stability, unless otherwise indicated\n\n"; - } elsif ($DEFAULT_STABILITY) { - $AnnotationsUsed{$DEFAULT_STABILITY} = 1; - $stability = "\nStability Level\n$DEFAULT_STABILITY, unless otherwise indicated\n\n"; - } - - my $image = $SymbolDocs{"$TMPL_DIR/$file:Image"}; - if (!defined ($image) || $image =~ m/^\s*$/) { - $image = ""; - } else { - $image =~ s/^\s*//; - $image =~ s/\s*$//; - - my $format; - - if ($image =~ /jpe?g$/i) { - $format = "format='JPEG'"; - } elsif ($image =~ /png$/i) { - $format = "format='PNG'"; - } elsif ($image =~ /svg$/i) { - $format = "format='SVG'"; - } else { - $format = ""; - } - - $image = " \n" - } - - my ($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) = - gmtime (time); - my $month = (qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec))[$mon]; - $year += 1900; - - my $include_output = ""; - if ($includes) { - $include_output .= "Includes"; - my $include; - foreach $include (split (/,/, $includes)) { - if ($include =~ m/^\".+\"$/) { - $include_output .= "#include ${include}\n"; - } - else { - $include =~ s/^\s+|\s+$//gs; - $include_output .= "#include <${include}>\n"; - } - } - $include_output .= "\n"; - } - - my $extralinks = OutputSectionExtraLinks($title,"Section:$file"); - - my $old_db_file = "$DB_OUTPUT_DIR/$file.xml"; - my $new_db_file = "$DB_OUTPUT_DIR/$file.xml.new"; - - open (OUTPUT, ">$new_db_file") - || die "Can't create $new_db_file: $!"; - - my $object_anchors = ""; - foreach my $object (@$file_objects) { - next if ($object eq $section_id); - my $id = CreateValidSGMLID($object); - @TRACE@("Adding anchor for $object\n"); - $object_anchors .= ""; - } - - # Make sure we produce valid docbook - $$functions_details ||= ""; - - # We used to output this, but is messes up our UpdateFileIfChanged code - # since it changes every day (and it is only used in the man pages): - # "" - - print OUTPUT < - -$title -3 -\U$MODULE\E Library$image - - -$title -$short_desc - -$stability -$$functions_synop$$args_synop$$signals_synop$object_anchors$$other_synop$$hierarchy$$prerequisites$$derived$$interfaces$$implementations -$include_output - -Description -$extralinks$long_desc - - -Functions -$$functions_details - - -Types and Values -$$other_details - -$$args_desc$$signals_desc$see_also - -EOF - close (OUTPUT); - - return &UpdateFileIfChanged ($old_db_file, $new_db_file, 0); -} - - -############################################################################# -# Function : OutputExtraFile -# Description : Copies an "extra" DocBook file into the output directory, -# expanding abbreviations -# Arguments : $file - the source file. -############################################################################# -sub OutputExtraFile { - my ($file) = @_; - - my $basename; - - ($basename = $file) =~ s!^.*/!!; - - my $old_db_file = "$DB_OUTPUT_DIR/$basename"; - my $new_db_file = "$DB_OUTPUT_DIR/$basename.new"; - - my $contents; - - open(EXTRA_FILE, "<$file") || die "Can't open $file"; - - { - local $/; - $contents = ; - } - - open (OUTPUT, ">$new_db_file") - || die "Can't create $new_db_file: $!"; - - print OUTPUT &ExpandAbbreviations ("$basename file", $contents); - close (OUTPUT); - - return &UpdateFileIfChanged ($old_db_file, $new_db_file, 0); -} -############################################################################# -# Function : OutputBook -# Description : Outputs the entities that need to be included into the -# main docbook file for the module. -# Arguments : $book_top - the declarations of the entities, which are added -# at the top of the main docbook file. -# $book_bottom - the references to the entities, which are -# added in the main docbook file at the desired position. -############################################################################# - -sub OutputBook { - my ($book_top, $book_bottom) = @_; - - my $old_file = "$DB_OUTPUT_DIR/$MODULE-doc.top"; - my $new_file = "$DB_OUTPUT_DIR/$MODULE-doc.top.new"; - - open (OUTPUT, ">$new_file") - || die "Can't create $new_file: $!"; - print OUTPUT $book_top; - close (OUTPUT); - - &UpdateFileIfChanged ($old_file, $new_file, 0); - - - $old_file = "$DB_OUTPUT_DIR/$MODULE-doc.bottom"; - $new_file = "$DB_OUTPUT_DIR/$MODULE-doc.bottom.new"; - - open (OUTPUT, ">$new_file") - || die "Can't create $new_file: $!"; - print OUTPUT $book_bottom; - close (OUTPUT); - - &UpdateFileIfChanged ($old_file, $new_file, 0); - - - # If the main docbook file hasn't been created yet, we create it here. - # The user can tweak it later. - if ($MAIN_SGML_FILE && ! -e $MAIN_SGML_FILE) { - open (OUTPUT, ">$MAIN_SGML_FILE") - || die "Can't create $MAIN_SGML_FILE: $!"; - - print OUTPUT < - - &package_name; Reference Manual - - for &package_string;. - The latest version of this documentation can be found on-line at - http://[SERVER]/&package_name;/. - - - - - [Insert title here] - $book_bottom - -EOF - if (-e $OBJECT_TREE_FILE) { - print OUTPUT < - Object Hierarchy - - -EOF - } else { - print OUTPUT < - Object Hierarchy - - - --> -EOF - } - print OUTPUT < - API Index - - - - Index of deprecated API - - -EOF - if (keys(%AnnotationsUsed)) { - print OUTPUT < -EOF - } else { - print OUTPUT < - --> -EOF - } - print OUTPUT < -EOF - - close (OUTPUT); - } -} - - -############################################################################# -# Function : CreateValidSGML -# Description : This turns any chars which are used in SGML into entities, -# e.g. '<' into '<' -# Arguments : $text - the text to turn into proper SGML. -############################################################################# - -sub CreateValidSGML { - my ($text) = @_; - $text =~ s/&/&/g; # Do this first, or the others get messed up. - $text =~ s//>/g; - # browers render single tabs inconsistently - $text =~ s/([^\s])\t([^\s])/$1 $2/g; - return $text; -} - -############################################################################# -# Function : ConvertSGMLChars -# Description : This is used for text in source code comment blocks, to turn -# chars which are used in SGML into entities, e.g. '<' into -# '<'. Depending on $INLINE_MARKUP_MODE, this is done -# unconditionally or only if the character doesn't seem to be -# part of an SGML construct (tag or entity reference). -# Arguments : $text - the text to turn into proper SGML. -############################################################################# - -sub ConvertSGMLChars { - my ($symbol, $text) = @_; - - if ($INLINE_MARKUP_MODE) { - # For the XML/SGML mode only convert to entities outside CDATA sections. - return &ModifyXMLElements ($text, $symbol, - "]*>", - \&ConvertSGMLCharsEndTag, - \&ConvertSGMLCharsCallback); - } else { - # For the simple non-sgml mode, convert to entities everywhere. - - # First, convert freestanding & to & - $text =~ s/&(?![a-zA-Z#]+;)/&/g; - $text =~ s/" at beginning of string for blockquote markdown - $text =~ s/(?<=[^\w\n"'\/-])>/>/g; - - return $text; - } -} - - -sub ConvertSGMLCharsEndTag { - if ($_[0] eq ""; - } else { - return ""; - } -} - -sub ConvertSGMLCharsCallback { - my ($text, $symbol, $tag) = @_; - - if ($tag =~ m/^ specially here. - return &ModifyXMLElements ($text, $symbol, - "" at beginning of string for blockquote markdown - $text =~ s/(?<=[^\w\n"'\/-])>/>/g; - - # Handle "#include " - $text =~ s/#include(\s+)<([^>]+)>/#include$1<$2>/g; - } - - return $text; -} - -sub ConvertSGMLCharsCallback2 { - my ($text, $symbol, $tag) = @_; - - # If we're not in CDATA convert to entities. - # We could handle differently, though I'm not sure it helps. - if ($tag eq "") { - # replace only if its not a tag - $text =~ s/&(?![a-zA-Z#]+;)/&/g; # Do this first, or the others get messed up. - $text =~ s/<(?![a-zA-Z\/!])/</g; - $text =~ s/(?/>/g; - - # Handle "#include " - $text =~ s/#include(\s+)<([^>]+)>/#include$1<$2>/g; - } - - return $text; -} - -############################################################################# -# Function : ExpandAnnotation -# Description : This turns annotations into acronym tags. -# Arguments : $symbol - the symbol being documented, for error messages. -# $text - the text to expand. -############################################################################# -sub ExpandAnnotation { - my ($symbol, $param_desc) = @_; - my $param_annotations = ""; - - # look for annotations at the start of the comment part - # function level annotations don't end with a colon ':' - if ($param_desc =~ m%^\s*\((.*?)\)(:|$)%) { - my @annotations; - my $annotation; - $param_desc = $'; - - @annotations = split(/\)\s*\(/,$1); - @TRACE@("annotations for $symbol: '$1'\n"); - foreach $annotation (@annotations) { - # need to search for the longest key-match in %AnnotationDefinition - my $match_length=0; - my $match_annotation=""; - my $annotationdef; - foreach $annotationdef (keys %AnnotationDefinition) { - if ($annotation =~ m/^$annotationdef/) { - if (length($annotationdef)>$match_length) { - $match_length=length($annotationdef); - $match_annotation=$annotationdef; - } - } - } - my $annotation_extra = ""; - if ($match_annotation ne "") { - if ($annotation =~ m%$match_annotation\s+(.*)%) { - $annotation_extra = " $1"; - } - $AnnotationsUsed{$match_annotation} = 1; - $param_annotations .= "[$match_annotation$annotation_extra]"; - } - else { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "unknown annotation \"$annotation\" in documentation for $symbol."); - $param_annotations .= "[$annotation]"; - } - } - chomp($param_desc); - $param_desc =~ m/^(.*?)\.*\s*$/s; - $param_desc = "$1. "; - } - if ($param_annotations ne "") { - $param_annotations = "$param_annotations"; - } - return ($param_desc, $param_annotations); -} - -############################################################################# -# Function : ExpandAbbreviations -# Description : This turns the abbreviations function(), macro(), @param, -# %constant, and #symbol into appropriate DocBook markup. -# CDATA sections and parts are skipped. -# Arguments : $symbol - the symbol being documented, for error messages. -# $text - the text to expand. -############################################################################# - -sub ExpandAbbreviations { - my ($symbol, $text) = @_; - - # Note: This is a fallback and normally done in the markdown parser - - # Convert "|[" and "]|" into the start and end of program listing examples. - # Support \[ modifiers - $text =~ s%\|\[%%g; - - # keep CDATA unmodified, preserve ulink tags (ideally we preseve all tags - # as such) - return &ModifyXMLElements ($text, $symbol, - "]*>|]*>|"; - } elsif ($start_tag eq ""; - } elsif ($start_tag =~ m/<(\w+)/) { - return ""; - } -} - -# Called inside or outside each CDATA or section. -sub ExpandAbbreviationsCallback { - my ($text, $symbol, $tag) = @_; - - if ($tag =~ m/^ sections, so we expand - # any gtk-doc abbreviations. - - # Convert '@param()' - # FIXME: we could make those also links ($symbol.$2), but that would be less - # useful as the link target is a few lines up or down - $text =~ s/(\A|[^\\])\@(\w+((\.|->)\w+)*)\s*\(\)/$1$2()<\/parameter>/g; - - # Convert 'function()' or 'macro()'. - # if there is abc_*_def() we don't want to make a link to _def() - # FIXME: also handle abc(def(....)) : but that would need to be done recursively :/ - $text =~ s/([^\*.\w])(\w+)\s*\(\)/$1.&MakeXRef($2, &tagify($2 . "()", "function"));/eg; - # handle #Object.func() - $text =~ s/(\A|[^\\])#([\w\-:\.]+[\w]+)\s*\(\)/$1.&MakeXRef($2, &tagify($2 . "()", "function"));/eg; - - # Convert '@param', but not '\@param'. - $text =~ s/(\A|[^\\])\@(\w+((\.|->)\w+)*)/$1$2<\/parameter>/g; - $text =~ s/\\\@/\@/g; - - # Convert '%constant', but not '\%constant'. - # Also allow negative numbers, e.g. %-1. - $text =~ s/(\A|[^\\])\%(-?\w+)/$1.&MakeXRef($2, &tagify($2, "literal"));/eg; - $text =~ s/\\\%/\%/g; - - # Convert '#symbol', but not '\#symbol'. - $text =~ s/(\A|[^\\])#([\w\-:\.]+[\w]+)/$1.&MakeHashXRef($2, "type");/eg; - $text =~ s/\\#/#/g; - } - - return $text; -} - -# This is called inside a -sub ExpandAbbreviationsCallback2 { - my ($text, $symbol, $tag) = @_; - - if ($tag eq "") { - # We are inside a but outside any CDATA sections, - # so we expand any gtk-doc abbreviations. - # FIXME: why is this different from &ExpandAbbreviationsCallback(), - # why not just call it - $text =~ s/#(\w+)/&MakeHashXRef($1, "");/eg; - } elsif ($tag eq ". -# Arguments : $text - the text. -# $symbol - the symbol currently being documented (only used for -# error messages). -# $start_tag_regexp - the regular expression to match start tags. -# e.g. "]*>" to match -# CDATA sections or programlisting elements. -# $end_tag_func - function which is passed the matched start tag -# and should return the appropriate end tag string regexp. -# $callback - callback called with each part of the text. It is -# called with a piece of text, the symbol being -# documented, and the matched start tag or "" if the text -# is outside the XML elements being matched. -############################################################################# -sub ModifyXMLElements { - my ($text, $symbol, $start_tag_regexp, $end_tag_func, $callback) = @_; - my ($before_tag, $start_tag, $end_tag_regexp, $end_tag); - my $result = ""; - - while ($text =~ m/$start_tag_regexp/s) { - $before_tag = $`; # Prematch for last successful match string - $start_tag = $&; # Last successful match - $text = $'; # Postmatch for last successful match string - - $result .= &$callback ($before_tag, $symbol, ""); - $result .= $start_tag; - - # get the matching end-tag for current tag - $end_tag_regexp = &$end_tag_func ($start_tag); - - if ($text =~ m/$end_tag_regexp/s) { - $before_tag = $`; - $end_tag = $&; - $text = $'; - - $result .= &$callback ($before_tag, $symbol, $start_tag); - $result .= $end_tag; - } else { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Can't find tag end: $end_tag_regexp in docs for: $symbol."); - # Just assume it is all inside the tag. - $result .= &$callback ($text, $symbol, $start_tag); - $text = ""; - } - } - - # Handle any remaining text outside the tags. - $result .= &$callback ($text, $symbol, ""); - - return $result; -} - -sub noop { - return $_[0]; -} - -# Adds a tag around some text. -# e.g tagify("Text", "literal") => "Text". -sub tagify { - my ($text, $elem) = @_; - return "<" . $elem . ">" . $text . ""; -} - -############################################################################# -# Function : MakeDocHeader -# Description : Builds a docbook header for the given tag -# Arguments : $tag - doctype tag -############################################################################# - -sub MakeDocHeader { - my ($tag) = @_; - my $header = $doctype_header; - $header =~ s/##; - } - - return $header; -} - - -############################################################################# -# Function : MakeXRef -# Description : This returns a cross-reference link to the given symbol. -# Though it doesn't try to do this for a few standard C types -# that it knows won't be in the documentation. -# Arguments : $symbol - the symbol to try to create a XRef to. -# $text - text text to put inside the XRef, defaults to $symbol -############################################################################# - -sub MakeXRef { - my ($symbol, $text) = ($_[0], $_[1]); - - $symbol =~ s/^\s+//; - $symbol =~ s/\s+$//; - - if (!defined($text)) { - $text = $symbol; - - # Get rid of special suffixes ('-struct','-enum'). - $text =~ s/-struct$//; - $text =~ s/-enum$//; - } - - if ($symbol =~ m/ /) { - return "$text"; - } - - @TRACE@("Getting type link for $symbol -> $text\n"); - - my $symbol_id = &CreateValidSGMLID ($symbol); - return "$text"; -} - - -############################################################################# -# Function : MakeIndexterms -# Description : This returns a indexterm elements for the given symbol -# Arguments : $symbol - the symbol to create indexterms for -############################################################################# - -sub MakeIndexterms { - my ($symbol, $id) = @_; - my $terms = ""; - my $sortas = ""; - - # make the index useful, by ommiting the namespace when sorting - if ($NAME_SPACE ne "") { - if ($symbol =~ m/^$NAME_SPACE\_?(.*)/i) { - $sortas=" sortas=\"$1\""; - } - } - - if (exists $Deprecated{$symbol}) { - $terms .= "$symbol"; - $IndexEntriesDeprecated{$symbol}=$id; - $IndexEntriesFull{$symbol}=$id; - } - if (exists $Since{$symbol}) { - my $since = $Since{$symbol}; - $since =~ s/^\s+//; - $since =~ s/\s+$//; - if ($since ne "") { - $terms .= "$symbol"; - } - $IndexEntriesSince{$symbol}=$id; - $IndexEntriesFull{$symbol}=$id; - } - if ($terms eq "") { - $terms .= "$symbol"; - $IndexEntriesFull{$symbol}=$id; - } - - return $terms; - } - -############################################################################# -# Function : MakeDeprecationNote -# Description : This returns a deprecation warning for the given symbol. -# Arguments : $symbol - the symbol to try to create a warning for. -############################################################################# - -sub MakeDeprecationNote { - my ($symbol) = $_[0]; - my $desc = ""; - if (exists $Deprecated{$symbol}) { - my $note; - - $desc .= "$symbol "; - - $note = $Deprecated{$symbol}; - - if ($note =~ /^\s*([0-9\.]+)\s*:?/) { - $desc .= "has been deprecated since version $1 and should not be used in newly-written code."; - } else { - $desc .= "is deprecated and should not be used in newly-written code."; - } - $note =~ s/^\s*([0-9\.]+)\s*:?\s*//; - $note =~ s/^\s+//; - $note =~ s/\s+$//; - if ($note ne "") { - $note = &ConvertMarkDown($symbol, $note); - $desc .= " " . $note; - } - $desc .= "\n"; - } - return $desc; -} - -############################################################################# -# Function : MakeConditionDescription -# Description : This returns a sumary of conditions for the given symbol. -# Arguments : $symbol - the symbol to try to create the sumary. -############################################################################# - -sub MakeConditionDescription { - my ($symbol) = $_[0]; - my $desc = ""; - - if (exists $Deprecated{$symbol}) { - if ($desc ne "") { - $desc .= "|"; - } - - if ($Deprecated{$symbol} =~ /^\s*(.*?)\s*$/) { - $desc .= "deprecated:$1"; - } else { - $desc .= "deprecated"; - } - } - - if (exists $Since{$symbol}) { - if ($desc ne "") { - $desc .= "|"; - } - - if ($Since{$symbol} =~ /^\s*(.*?)\s*$/) { - $desc .= "since:$1"; - } else { - $desc .= "since"; - } - } - - if (exists $StabilityLevel{$symbol}) { - if ($desc ne "") { - $desc .= "|"; - } - $desc .= "stability:".$StabilityLevel{$symbol}; - } - - if ($desc ne "") { - my $cond = $desc; - $cond =~ s/\"/"/g; - $desc=" condition=\"".$cond."\""; - @TRACE@("condition for '$symbol' = '$desc'\n"); - } - return $desc; -} - -############################################################################# -# Function : GetHierarchy -# Description : Returns the DocBook output describing the ancestors and -# immediate children of a GObject subclass. It uses the -# global @Objects and @ObjectLevels arrays to walk the tree. -# -# Arguments : $object - the GtkObject subclass. -# @hierarchy - previous hierarchy -############################################################################# - -sub GetHierarchy { - my ($object,$hierarchy_ref) = @_; - my @hierarchy = @{$hierarchy_ref}; - - # Find object in the objects array. - my $found = 0; - my @children = (); - my $i; - my $level; - my $j; - for ($i = 0; $i < @Objects; $i++) { - if ($found) { - if ($ObjectLevels[$i] <= $level) { - last; - } - elsif ($ObjectLevels[$i] == $level + 1) { - push (@children, $Objects[$i]); - } - } - elsif ($Objects[$i] eq $object) { - $found = 1; - $j = $i; - $level = $ObjectLevels[$i]; - } - } - if (!$found) { - return @hierarchy; - } - - # Walk up the hierarchy, pushing ancestors onto the ancestors array. - my @ancestors = (); - push (@ancestors, $object); - @TRACE@("Level: $level\n"); - while ($level > 1) { - $j--; - if ($ObjectLevels[$j] < $level) { - push (@ancestors, $Objects[$j]); - $level = $ObjectLevels[$j]; - @TRACE@("Level: $level\n"); - } - } - - # Output the ancestors, indented and with links. - my $last_index = 0; - $level = 1; - for ($i = $#ancestors; $i >= 0; $i--) { - my $entry_text; - my $alt_text; - my $ancestor = $ancestors[$i]; - my $ancestor_id = &CreateValidSGMLID ($ancestor); - my $indent = ' ' x ($level * 4); - # Don't add a link to the current object, i.e. when i == 0. - if ($i > 0) { - $entry_text = $indent . "$ancestor"; - $alt_text = $indent . $ancestor; - } else { - $entry_text = $indent . $ancestor; - $alt_text = $indent . "$ancestor"; - } - @TRACE@("Checking for '$entry_text' or '$alt_text'"); - # Check if we already have this object - my $index = -1; - for ($j = 0; $j <= $#hierarchy; $j++) { - if (($hierarchy[$j] eq $entry_text) or ($hierarchy[$j] eq $alt_text)) { - $index = $j; - last; - } - } - if ($index == -1) { - # We have a new entry, find insert position in alphabetical order - my $found = 0; - for ($j = $last_index; $j <= $#hierarchy; $j++) { - if ($hierarchy[$j] !~ m/^${indent}/) { - $last_index = $j; - $found = 1; - last; - } elsif ($hierarchy[$j] =~ m/^${indent}[^ ]/) { - my $stripped_text = $hierarchy[$j]; - if ($entry_text !~ m/%%; - $stripped_text =~ s%%%; - } - if ($entry_text lt $stripped_text) { - $last_index = $j; - $found = 1; - last; - } - } - } - # Append to bottom - if (!$found) { - $last_index = 1 + $#hierarchy; - } - splice @hierarchy, $last_index, 0, ($entry_text); - $last_index++; - } else { - # Already have this one, make sure we use the not linked version - if ($entry_text !~ m/$children[$i]"; - splice @hierarchy, $last_index, 0, ($indented_text); - $last_index++; - } - - return @hierarchy; -} - -############################################################################# -# Function : GetInterfaces -# Description : Returns the DocBook output describing the interfaces -# implemented by a class. It uses the global %Interfaces hash. -# Arguments : $object - the GtkObject subclass. -############################################################################# - -sub GetInterfaces { - my ($object) = @_; - my $text = ""; - my $i; - - # Find object in the objects array. - if (exists($Interfaces{$object})) { - my @ifaces = split(' ', $Interfaces{$object}); - $text = < -$object implements -EOF - for ($i = 0; $i <= $#ifaces; $i++) { - my $id = &CreateValidSGMLID ($ifaces[$i]); - $text .= " $ifaces[$i]"; - if ($i < $#ifaces - 1) { - $text .= ', '; - } - elsif ($i < $#ifaces) { - $text .= ' and '; - } - else { - $text .= '.'; - } - } - $text .= < -EOF - } - - return $text; -} - -############################################################################# -# Function : GetImplementations -# Description : Returns the DocBook output describing the implementations -# of an interface. It uses the global %Interfaces hash. -# Arguments : $object - the GtkObject subclass. -############################################################################# - -sub GetImplementations { - my ($object) = @_; - my @impls = (); - my $text = ""; - my $i; - foreach my $key (keys %Interfaces) { - if ($Interfaces{$key} =~ /\b$object\b/) { - push (@impls, $key); - } - } - if ($#impls >= 0) { - @impls = sort @impls; - $text = < -$object is implemented by -EOF - for ($i = 0; $i <= $#impls; $i++) { - my $id = &CreateValidSGMLID ($impls[$i]); - $text .= " $impls[$i]"; - if ($i < $#impls - 1) { - $text .= ', '; - } - elsif ($i < $#impls) { - $text .= ' and '; - } - else { - $text .= '.'; - } - } - $text .= < -EOF - } - return $text; -} - - -############################################################################# -# Function : GetPrerequisites -# Description : Returns the DocBook output describing the prerequisites -# of an interface. It uses the global %Prerequisites hash. -# Arguments : $iface - the interface. -############################################################################# - -sub GetPrerequisites { - my ($iface) = @_; - my $text = ""; - my $i; - - if (exists($Prerequisites{$iface})) { - $text = < -$iface requires -EOF - my @prereqs = split(' ', $Prerequisites{$iface}); - for ($i = 0; $i <= $#prereqs; $i++) { - my $id = &CreateValidSGMLID ($prereqs[$i]); - $text .= " $prereqs[$i]"; - if ($i < $#prereqs - 1) { - $text .= ', '; - } - elsif ($i < $#prereqs) { - $text .= ' and '; - } - else { - $text .= '.'; - } - } - $text .= < -EOF - } - return $text; -} - -############################################################################# -# Function : GetDerived -# Description : Returns the DocBook output describing the derived interfaces -# of an interface. It uses the global %Prerequisites hash. -# Arguments : $iface - the interface. -############################################################################# - -sub GetDerived { - my ($iface) = @_; - my $text = ""; - my $i; - - my @derived = (); - foreach my $key (keys %Prerequisites) { - if ($Prerequisites{$key} =~ /\b$iface\b/) { - push (@derived, $key); - } - } - if ($#derived >= 0) { - @derived = sort @derived; - $text = < -$iface is required by -EOF - for ($i = 0; $i <= $#derived; $i++) { - my $id = &CreateValidSGMLID ($derived[$i]); - $text .= " $derived[$i]"; - if ($i < $#derived - 1) { - $text .= ', '; - } - elsif ($i < $#derived) { - $text .= ' and '; - } - else { - $text .= '.'; - } - } - $text .= < -EOF - } - return $text; -} - - -############################################################################# -# Function : GetSignals -# Description : Returns the synopsis and detailed description DocBook output -# for the signal handlers of a given GtkObject subclass. -# Arguments : $object - the GtkObject subclass, e.g. 'GtkButton'. -############################################################################# - -sub GetSignals { - my ($object) = @_; - my $synop = ""; - my $desc = ""; - - my $i; - for ($i = 0; $i <= $#SignalObjects; $i++) { - if ($SignalObjects[$i] eq $object) { - @TRACE@("Found signal: $SignalNames[$i]\n"); - my $name = $SignalNames[$i]; - my $symbol = "${object}::${name}"; - my $id = &CreateValidSGMLID ("$object-$name"); - - $desc .= "The <literal>“$name”</literal> signal\n"; - $desc .= MakeIndexterms($symbol, $id); - $desc .= "\n"; - $desc .= OutputSymbolExtraLinks($symbol); - - $desc .= ""; - - $SignalReturns[$i] =~ m/\s*(const\s+)?(\w+)\s*(\**)/; - my $type_modifier = defined($1) ? $1 : ""; - my $type = $2; - my $pointer = $3; - my $xref = &MakeXRef ($type, &tagify($type, "returnvalue")); - - my $ret_type_output = "$type_modifier$xref$pointer"; - my $callback_name = "user_function"; - $desc .= "${ret_type_output}\n${callback_name} ("; - - my $indentation = ' ' x (length($callback_name) + 2); - my $pad = $indentation; - - my $sourceparams = $SourceSymbolParams{$symbol}; - my @params = split ("\n", $SignalPrototypes[$i]); - my $j; - my $l; - my $type_len = length("gpointer"); - my $name_len = length("user_data"); - # do two passes, the first one is to calculate padding - for ($l = 0; $l < 2; $l++) { - for ($j = 0; $j <= $#params; $j++) { - my $param_name; - # allow alphanumerics, '_', '[' & ']' in param names - if ($params[$j] =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)\s*$/) { - $type = $1; - $pointer = $2; - if (defined($sourceparams)) { - $param_name = $$sourceparams[$PARAM_FIELD_COUNT * $j]; - } - else { - $param_name = $3; - } - if (!defined($param_name)) { - $param_name = "arg$j"; - } - if ($l == 0) { - if (length($type) + length($pointer) > $type_len) { - $type_len = length($type) + length($pointer); - } - if (length($param_name) > $name_len) { - $name_len = length($param_name); - } - } - else { - $xref = &MakeXRef ($type, &tagify($type, "type")); - $pad = ' ' x ($type_len - length($type) - length($pointer)); - $desc .= "$xref$pad $pointer${param_name},\n"; - $desc .= $indentation; - } - } else { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Can't parse arg: $params[$j]\nArgs:$SignalPrototypes[$i]"); - } - } - } - $xref = &MakeXRef ("gpointer", &tagify("gpointer", "type")); - $pad = ' ' x ($type_len - length("gpointer")); - $desc .= "$xref$pad user_data)"; - $desc .= "\n"; - - my $flags = $SignalFlags[$i]; - my $flags_string = ""; - - if (defined ($flags)) { - if ($flags =~ m/f/) { - $flags_string = "Run First"; - } - elsif ($flags =~ m/l/) { - $flags_string = "Run Last"; - } - elsif ($flags =~ m/c/) { - $flags_string = "Cleanup"; - $flags_string = "Cleanup"; - } - if ($flags =~ m/r/) { - if ($flags_string) { $flags_string .= " / "; } - $flags_string = "No Recursion"; - } - if ($flags =~ m/d/) { - if ($flags_string) { $flags_string .= " / "; } - $flags_string = "Has Details"; - } - if ($flags =~ m/a/) { - if ($flags_string) { $flags_string .= " / "; } - $flags_string = "Action"; - } - if ($flags =~ m/h/) { - if ($flags_string) { $flags_string .= " / "; } - $flags_string = "No Hooks"; - } - } - - $synop .= "${ret_type_output}${name}${flags_string}\n"; - - my $parameters = &OutputParamDescriptions ("SIGNAL", $symbol); - - $AllSymbols{$symbol} = 1; - if (defined ($SymbolDocs{$symbol})) { - my $symbol_docs = &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - - $desc .= $symbol_docs; - - if (!IsEmptyDoc($SymbolDocs{$symbol})) { - $AllDocumentedSymbols{$symbol} = 1; - } - } - if (defined ($SymbolAnnotations{$symbol})) { - my $param_desc = $SymbolAnnotations{$symbol}; - my $param_annotations = ""; - ($param_desc,$param_annotations) = &ExpandAnnotation($symbol, $param_desc); - if ($param_annotations ne "") { - $desc .= "\n$param_annotations"; - } - } - $desc .= &MakeDeprecationNote($symbol); - - $desc .= $parameters; - if ($flags_string) { - $desc .= "Flags: $flags_string\n"; - } - $desc .= OutputSymbolTraits ($symbol); - $desc .= ""; - } - } - return ($synop, $desc); -} - - -############################################################################# -# Function : GetArgs -# Description : Returns the synopsis and detailed description DocBook output -# for the Args of a given GtkObject subclass. -# Arguments : $object - the GtkObject subclass, e.g. 'GtkButton'. -############################################################################# - -sub GetArgs { - my ($object) = @_; - my $synop = ""; - my $desc = ""; - my $child_synop = ""; - my $child_desc = ""; - my $style_synop = ""; - my $style_desc = ""; - - my $i; - for ($i = 0; $i <= $#ArgObjects; $i++) { - if ($ArgObjects[$i] eq $object) { - @TRACE@("Found arg: $ArgNames[$i]\n"); - my $name = $ArgNames[$i]; - my $flags = $ArgFlags[$i]; - my $flags_string = ""; - my $kind = ""; - my $id_sep = ""; - - if ($flags =~ m/c/) { - $kind = "child property"; - $id_sep = "c-"; - } - elsif ($flags =~ m/s/) { - $kind = "style property"; - $id_sep = "s-"; - } - else { - $kind = "property"; - } - - # Remember only one colon so we don't clash with signals. - my $symbol = "${object}:${name}"; - # use two dashes and ev. an extra separator here for the same reason. - my $id = &CreateValidSGMLID ("$object--$id_sep$name"); - - my $type = $ArgTypes[$i]; - my $type_output; - my $range = $ArgRanges[$i]; - my $range_output = CreateValidSGML ($range); - my $default = $ArgDefaults[$i]; - my $default_output = CreateValidSGML ($default); - - if ($type eq "GtkString") { - $type = "char *"; - } - if ($type eq "GtkSignal") { - $type = "GtkSignalFunc, gpointer"; - $type_output = &MakeXRef ("GtkSignalFunc") . ", " - . &MakeXRef ("gpointer"); - } elsif ($type =~ m/^(\w+)\*$/) { - $type_output = &MakeXRef ($1, &tagify($1, "type")) . " *"; - } else { - $type_output = &MakeXRef ($type, &tagify($type, "type")); - } - - if ($flags =~ m/r/) { - $flags_string = "Read"; - } - if ($flags =~ m/w/) { - if ($flags_string) { $flags_string .= " / "; } - $flags_string .= "Write"; - } - if ($flags =~ m/x/) { - if ($flags_string) { $flags_string .= " / "; } - $flags_string .= "Construct"; - } - if ($flags =~ m/X/) { - if ($flags_string) { $flags_string .= " / "; } - $flags_string .= "Construct Only"; - } - - $AllSymbols{$symbol} = 1; - my $blurb = ""; - if (defined($SymbolDocs{$symbol}) && - !IsEmptyDoc($SymbolDocs{$symbol})) { - $blurb = &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - @TRACE@(".. [$SymbolDocs{$symbol}][$blurb]\n"); - $AllDocumentedSymbols{$symbol} = 1; - } - else { - if ($ArgBlurbs[$i] ne "") { - $blurb = "" . &CreateValidSGML ($ArgBlurbs[$i]) . ""; - $AllDocumentedSymbols{$symbol} = 1; - } else { - # FIXME: print a warning? - @TRACE@(".. no description\n"); - } - } - - my $pad1 = " " x (24 - length ($name)); - - my $arg_synop = "$type_output$name$flags_string\n"; - my $arg_desc = "The <literal>“$name”</literal> $kind\n"; - $arg_desc .= MakeIndexterms($symbol, $id); - $arg_desc .= "\n"; - $arg_desc .= OutputSymbolExtraLinks($symbol); - - $arg_desc .= " “$name”$pad1 $type_output\n"; - $arg_desc .= $blurb; - if (defined ($SymbolAnnotations{$symbol})) { - my $param_desc = $SymbolAnnotations{$symbol}; - my $param_annotations = ""; - ($param_desc,$param_annotations) = &ExpandAnnotation($symbol, $param_desc); - if ($param_annotations ne "") { - $arg_desc .= "\n$param_annotations"; - } - } - $arg_desc .= &MakeDeprecationNote($symbol); - - if ($flags_string) { - $arg_desc .= "Flags: $flags_string\n"; - } - if ($range ne "") { - $arg_desc .= "Allowed values: $range_output\n"; - } - if ($default ne "") { - $arg_desc .= "Default value: $default_output\n"; - } - $arg_desc .= OutputSymbolTraits ($symbol); - $arg_desc .= "\n"; - - if ($flags =~ m/c/) { - $child_synop .= $arg_synop; - $child_desc .= $arg_desc; - } - elsif ($flags =~ m/s/) { - $style_synop .= $arg_synop; - $style_desc .= $arg_desc; - } - else { - $synop .= $arg_synop; - $desc .= $arg_desc; - } - } - } - return ($synop, $child_synop, $style_synop, $desc, $child_desc, $style_desc); -} - - -############################################################################# -# Function : ReadSourceDocumentation -# Description : This reads in the documentation embedded in comment blocks -# in the source code (for Gnome). -# -# Parameter descriptions override any in the template files. -# Function descriptions are placed before any description from -# the template files. -# -# It recursively descends the source directory looking for .c -# files and scans them looking for specially-formatted comment -# blocks. -# -# Arguments : $source_dir - the directory to scan. -#############m############################################################### - -sub ReadSourceDocumentation { - my ($source_dir) = @_; - my ($file, $dir, @suffix_list, $suffix); - - # prepend entries from @SOURCE_DIR - for my $dir (@SOURCE_DIRS) { - # Check if the filename is in the ignore list. - if ($source_dir =~ m%^\Q$dir\E/(.*)$% and $IGNORE_FILES =~ m/(\s|^)\Q$1\E(\s|$)/) { - @TRACE@("Skipping source directory: $source_dir"); - return; - } else { - @TRACE@("No match for: ".($1 || $source_dir)); - } - } - - @TRACE@("Scanning source directory: $source_dir"); - - # This array holds any subdirectories found. - my (@subdirs) = (); - - @suffix_list = split (/,/, $SOURCE_SUFFIXES); - - opendir (SRCDIR, $source_dir) - || die "Can't open source directory $source_dir: $!"; - - foreach $file (readdir (SRCDIR)) { - if ($file =~ /^\./) { - next; - } elsif (-d "$source_dir/$file") { - push (@subdirs, $file); - } elsif (@suffix_list) { - foreach $suffix (@suffix_list) { - if ($file =~ m/\.\Q${suffix}\E$/) { - &ScanSourceFile ("$source_dir/$file"); - } - } - } elsif ($file =~ m/\.[ch]$/) { - &ScanSourceFile ("$source_dir/$file"); - } - } - closedir (SRCDIR); - - # Now recursively scan the subdirectories. - foreach $dir (@subdirs) { - &ReadSourceDocumentation ("$source_dir/$dir"); - } -} - - -############################################################################# -# Function : ScanSourceFile -# Description : Scans one source file looking for specially-formatted comment -# blocks. Later &MergeSourceDocumentation is used to merge any -# documentation found with the documentation already read in -# from the template files. -# -# Arguments : $file - the file to scan. -############################################################################# - -sub ScanSourceFile { - my ($file) = @_; - my $basename; - - # prepend entries from @SOURCE_DIR - for my $dir (@SOURCE_DIRS) { - # Check if the filename is in the ignore list. - if ($file =~ m%^\Q$dir\E/(.*)$% and $IGNORE_FILES =~ m/(\s|^)\Q$1\E(\s|$)/) { - @TRACE@("Skipping source file: $file"); - return; - } - } - - if ($file =~ m/^.*[\/\\]([^\/\\]*)$/) { - $basename = $1; - } else { - &LogWarning ($file, 1, "Can't find basename for this filename."); - $basename = $file; - } - - # Check if the basename is in the list of files to ignore. - if ($IGNORE_FILES =~ m/(\s|^)\Q${basename}\E(\s|$)/) { - @TRACE@("Skipping source file: $file"); - return; - } - - @TRACE@("Scanning source file: $file"); - - open (SRCFILE, $file) - || die "Can't open $file: $!"; - my $in_comment_block = 0; - my $symbol; - my $in_part = ""; - my ($description, $return_desc); - my ($since_desc, $stability_desc, $deprecated_desc); - my $current_param; - my @params; - while () { - # Look for the start of a comment block. - if (!$in_comment_block) { - if (m%^\s*/\*.*\*/%) { - #one-line comment - not gtkdoc - } elsif (m%^\s*/\*\*\s%) { - @TRACE@("Found comment block start\n"); - - $in_comment_block = 1; - - # Reset all the symbol data. - $symbol = ""; - $in_part = ""; - $description = ""; - $return_desc = ""; - $since_desc = ""; - $deprecated_desc = ""; - $stability_desc = ""; - $current_param = -1; - @params = (); - } - next; - } - - # We're in a comment block. Check if we've found the end of it. - if (m%^\s*\*+/%) { - if (!$symbol) { - # maybe its not even meant to be a gtk-doc comment? - &LogWarning ($file, $., "Symbol name not found at the start of the comment block."); - } else { - # Add the return value description onto the end of the params. - if ($return_desc) { - # TODO(ensonic): check for duplicated Return docs - # &LogWarning ($file, $., "Multiple Returns for $symbol."); - push (@params, "Returns"); - push (@params, $return_desc); - } - # Convert special characters - $description = &ConvertSGMLChars ($symbol, $description); - my $k; - for ($k = 1; $k <= $#params; $k += $PARAM_FIELD_COUNT) { - $params[$k] = &ConvertSGMLChars ($symbol, $params[$k]); - } - - # Handle Section docs - if ($symbol =~ m/SECTION:\s*(.*)/) { - my $real_symbol=$1; - my $key; - - if (scalar %KnownSymbols) { - if ((! defined($KnownSymbols{"$TMPL_DIR/$real_symbol:Long_Description"})) || $KnownSymbols{"$TMPL_DIR/$real_symbol:Long_Description"} != 1) { - &LogWarning ($file, $., "Section $real_symbol is not defined in the $MODULE-sections.txt file."); - } - } - - @TRACE@("SECTION DOCS found in source for : '$real_symbol'\n"); - for ($k = 0; $k <= $#params; $k += $PARAM_FIELD_COUNT) { - @TRACE@(" '".$params[$k]."'\n"); - $params[$k] = "\L$params[$k]"; - undef $key; - if ($params[$k] eq "short_description") { - $key = "$TMPL_DIR/$real_symbol:Short_Description"; - } elsif ($params[$k] eq "see_also") { - $key = "$TMPL_DIR/$real_symbol:See_Also"; - } elsif ($params[$k] eq "title") { - $key = "$TMPL_DIR/$real_symbol:Title"; - } elsif ($params[$k] eq "stability") { - $key = "$TMPL_DIR/$real_symbol:Stability_Level"; - } elsif ($params[$k] eq "section_id") { - $key = "$TMPL_DIR/$real_symbol:Section_Id"; - } elsif ($params[$k] eq "include") { - $key = "$TMPL_DIR/$real_symbol:Include"; - } elsif ($params[$k] eq "image") { - $key = "$TMPL_DIR/$real_symbol:Image"; - } - if (defined($key)) { - $SourceSymbolDocs{$key}=$params[$k+1]; - $SourceSymbolSourceFile{$key} = $file; - $SourceSymbolSourceLine{$key} = $.; - } - } - $SourceSymbolDocs{"$TMPL_DIR/$real_symbol:Long_Description"}=$description; - $SourceSymbolSourceFile{"$TMPL_DIR/$real_symbol:Long_Description"} = $file; - $SourceSymbolSourceLine{"$TMPL_DIR/$real_symbol:Long_Description"} = $.; - #$SourceSymbolTypes{$symbol} = "SECTION"; - } else { - @TRACE@("SYMBOL DOCS found in source for : '$symbol' ",length($description), "\n"); - $SourceSymbolDocs{$symbol} = $description; - $SourceSymbolParams{$symbol} = [ @params ]; - # FIXME $SourceSymbolTypes{$symbol} = "STRUCT,SIGNAL,ARG,FUNCTION,MACRO"; - #if (defined $DeclarationTypes{$symbol}) { - # $SourceSymbolTypes{$symbol} = $DeclarationTypes{$symbol} - #} - $SourceSymbolSourceFile{$symbol} = $file; - $SourceSymbolSourceLine{$symbol} = $.; - } - - if ($since_desc) { - ($since_desc, my @extra_lines) = split ("\n", $since_desc); - $since_desc =~ s/^\s+//; - $since_desc =~ s/\s+$//; - @TRACE@("Since($symbol) : [$since_desc]\n"); - $Since{$symbol} = &ConvertSGMLChars ($symbol, $since_desc); - if(scalar @extra_lines) { - &LogWarning ($file, $., "multi-line since docs found"); - } - } - - if ($stability_desc) { - $stability_desc = &ParseStabilityLevel($stability_desc, $file, $., "Stability level for $symbol"); - $StabilityLevel{$symbol} = &ConvertSGMLChars ($symbol, $stability_desc); - } - - if ($deprecated_desc) { - if (!exists $Deprecated{$symbol}) { - # don't warn for signals and properties - #if ($symbol !~ m/::?(.*)/) { - if (defined $DeclarationTypes{$symbol}) { - &LogWarning ($file, $., - "$symbol is deprecated in the inline comments, but no deprecation guards were found around the declaration.". - " (See the --deprecated-guards option for gtkdoc-scan.)"); - } - } - $Deprecated{$symbol} = &ConvertSGMLChars ($symbol, $deprecated_desc); - } - } - - $in_comment_block = 0; - next; - } - - # Get rid of ' * ' at start of every line in the comment block. - s%^\s*\*\s?%%; - # But make sure we don't get rid of the newline at the end. - if (!$_) { - $_ = "\n"; - } - @TRACE@("scanning :$_"); - - # If we haven't found the symbol name yet, look for it. - if (!$symbol) { - if (m%^\s*(SECTION:\s*\S+)%) { - $symbol = $1; - @TRACE@("SECTION DOCS found in source for : '$symbol'\n"); - } elsif (m%^\s*([\w:-]*\w)\s*:?\s*(\([-A-Za-z0-9._() ]+?\)\s*)*$%) { - $symbol = $1; - my $annotation = $2; - @TRACE@("SYMBOL DOCS found in source for : '$symbol'\n"); - if (defined($annotation)) { - chomp($annotation); - if ($annotation ne "") { - $SymbolAnnotations{$symbol} = $annotation; - @TRACE@("remaining text for $symbol: '$annotation'\n"); - } - } - } - next; - } - - if ($in_part eq "description") { - # Get rid of 'Description:' - s%^\s*Description:%%; - } - - if (m%^\s*(returns|return\s+value):%i) { - # we're in param section and have not seen the blank line - if($in_part ne "") { - $return_desc = $'; - $in_part = "return"; - next; - } - } elsif (m%^\s*since:%i) { - # we're in param section and have not seen the blank line - if($in_part ne "param") { - $since_desc = $'; - $in_part = "since"; - next; - } - } elsif (m%^\s*deprecated:%i) { - # we're in param section and have not seen the blank line - if($in_part ne "param") { - $deprecated_desc = $'; - $in_part = "deprecated"; - next; - } - } elsif (m%^\s*stability:%i) { - $stability_desc = $'; - $in_part = "stability"; - next; - } - - if ($in_part eq "description") { - $description .= $_; - next; - } elsif ($in_part eq "return") { - $return_desc .= $_; - next; - } elsif ($in_part eq "since") { - $since_desc .= $_; - next; - } elsif ($in_part eq "stability") { - $stability_desc .= $_; - next; - } elsif ($in_part eq "deprecated") { - $deprecated_desc .= $_; - next; - } - - # We must be in the parameters. Check for the empty line below them. - if (m%^\s*$%) { - $in_part = "description"; - next; - } - - # Look for a parameter name. - if (m%^\s*@(\S+)\s*:\s*%) { - my $param_name = $1; - my $param_desc = $'; - - @TRACE@("Found parameter: $param_name\n"); - # Allow varargs variations - if ($param_name =~ m/^\.\.\.$/) { - $param_name = "..."; - } - @TRACE@("Found param for symbol $symbol : '$param_name'= '$_'"); - - push (@params, $param_name); - push (@params, $param_desc); - $current_param += $PARAM_FIELD_COUNT; - $in_part = "param"; - next; - } elsif ($in_part eq "") { - @TRACE@("continuation for $symbol annotation '$_'"); - my $annotation = $_; - $annotation =~ s/^\s+|\s+$//g ; - $SymbolAnnotations{$symbol} .= $annotation; - next; - } - - # We must be in the middle of a parameter description, so add it on - # to the last element in @params. - if ($current_param == -1) { - &LogWarning ($file, $., "Parsing comment block file : parameter expected, but got '$_'"); - } else { - $params[$#params] .= $_; - } - } - close (SRCFILE); -} - -############################################################################# -# Function : OutputMissingDocumentation -# Description : Outputs report of documentation coverage to a file -# -# Arguments : none -############################################################################# - -sub OutputMissingDocumentation { - my $old_undocumented_file = "$ROOT_DIR/$MODULE-undocumented.txt"; - my $new_undocumented_file = "$ROOT_DIR/$MODULE-undocumented.new"; - - my $n_documented = 0; - my $n_incomplete = 0; - my $total = 0; - my $symbol; - my $percent; - my $msg; - my $buffer = ""; - my $buffer_deprecated = ""; - my $buffer_descriptions = ""; - - open(UNDOCUMENTED, ">$new_undocumented_file") - || die "Can't create $new_undocumented_file"; - - foreach $symbol (sort (keys (%AllSymbols))) { - # FIXME: should we print LogWarnings for undocumented stuff? - # DEBUG - #my $ssfile = &GetSymbolSourceFile($symbol); - #my $ssline = &GetSymbolSourceLine($symbol); - #my $location = "defined at " . (defined($ssfile)?$ssfile:"?") . ":" . (defined($ssline)?$ssline:"0") . "\n"; - # DEBUG - if ($symbol !~ /:(Title|Long_Description|Short_Description|See_Also|Stability_Level|Include|Section_Id|Image)/) { - $total++; - if (exists ($AllDocumentedSymbols{$symbol})) { - $n_documented++; - if (exists ($AllIncompleteSymbols{$symbol})) { - $n_incomplete++; - $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n"; - #$buffer .= "\t0: ".$location; - } - } elsif (exists $Deprecated{$symbol}) { - if (exists ($AllIncompleteSymbols{$symbol})) { - $n_incomplete++; - $buffer_deprecated .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n"; - #$buffer .= "\t1a: ".$location; - } else { - $buffer_deprecated .= $symbol . "\n"; - #$buffer .= "\t1b: ".$location; - } - } else { - if (exists ($AllIncompleteSymbols{$symbol})) { - $n_incomplete++; - $buffer .= $symbol . " (" . $AllIncompleteSymbols{$symbol} . ")\n"; - #$buffer .= "\t2a: ".$location; - } else { - $buffer .= $symbol . "\n"; - #$buffer .= "\t2b: ".$location; - } - } - } elsif ($symbol =~ /:(Long_Description|Short_Description)/) { - $total++; - if (((exists ($SymbolDocs{$symbol})) && (length ($SymbolDocs{$symbol}) > 0)) - || ((exists ($AllDocumentedSymbols{$symbol})) && (length ($AllDocumentedSymbols{$symbol}) > 0))) { - $n_documented++; - } else { - # cut off the leading namespace ($TMPL_DIR) - $symbol =~ m/^.*\/(.*)$/; - $buffer_descriptions .= $1 . "\n"; - } - } - } - - if ($total == 0) { - $percent = 100; - } else { - $percent = ($n_documented / $total) * 100.0; - } - - printf UNDOCUMENTED "%.0f%% symbol docs coverage.\n", $percent; - print UNDOCUMENTED "$n_documented symbols documented.\n"; - print UNDOCUMENTED "$n_incomplete symbols incomplete.\n"; - print UNDOCUMENTED ($total - $n_documented) . " not documented.\n"; - - if ($buffer_deprecated ne "") { - $buffer .= "\n" . $buffer_deprecated; - } - if ($buffer_descriptions ne "") { - $buffer .= "\n" . $buffer_descriptions; - } - if ($buffer ne "") { - print UNDOCUMENTED "\n\n$buffer"; - } - close (UNDOCUMENTED); - - return &UpdateFileIfChanged ($old_undocumented_file, $new_undocumented_file, 0); - - printf "%.0f%% symbol docs coverage", $percent; - print "($n_documented symbols documented, $n_incomplete symbols incomplete, " . ($total - $n_documented) . " not documented)\n"; - print "See $MODULE-undocumented.txt for a list of missing docs.\nThe doc coverage percentage doesn't include intro sections.\n"; -} - - -############################################################################# -# Function : OutputUndeclaredSymbols -# Description : Outputs symbols that are listed in the section file, but not -# declaration is found in the sources -# -# Arguments : none -############################################################################# - -sub OutputUndeclaredSymbols { - my $old_undeclared_file = "$ROOT_DIR/$MODULE-undeclared.txt"; - my $new_undeclared_file = "$ROOT_DIR/$MODULE-undeclared.new"; - - open(UNDECLARED, ">$new_undeclared_file") - || die "Can't create $new_undeclared_file"; - - if (%UndeclaredSymbols) { - print UNDECLARED (join("\n", sort keys %UndeclaredSymbols)); - print UNDECLARED "\n"; - print "See $MODULE-undeclared.txt for the list of undeclared symbols.\n" - } - close(UNDECLARED); - - return &UpdateFileIfChanged ($old_undeclared_file, $new_undeclared_file, 0); -} - -############################################################################# -# Function : OutputUnusedSymbols -# Description : Outputs symbols that are documented in comments, but not -# declared in the sources -# -# Arguments : none -############################################################################# - -sub OutputUnusedSymbols { - my $num_unused = 0; - my $old_unused_file = "$ROOT_DIR/$MODULE-unused.txt"; - my $new_unused_file = "$ROOT_DIR/$MODULE-unused.new"; - - open (UNUSED, ">$new_unused_file") - || die "Can't open $new_unused_file"; - my ($symbol); - foreach $symbol (sort keys (%Declarations)) { - if (!defined ($DeclarationOutput{$symbol})) { - print (UNUSED "$symbol\n"); - $num_unused++; - } - } - foreach $symbol (sort (keys (%AllUnusedSymbols))) { - print (UNUSED "$symbol(" . $AllUnusedSymbols{$symbol} . ")\n"); - $num_unused++; - } - close (UNUSED); - if ($num_unused != 0) { - &LogWarning ($old_unused_file, 1, "$num_unused unused declarations.". - "They should be added to $MODULE-sections.txt in the appropriate place."); - } - - return &UpdateFileIfChanged ($old_unused_file, $new_unused_file, 0); -} - - -############################################################################# -# Function : OutputAllSymbols -# Description : Outputs list of all symbols to a file -# -# Arguments : none -############################################################################# - -sub OutputAllSymbols { - my $n_documented = 0; - my $total = 0; - my $symbol; - my $percent; - my $msg; - - open (SYMBOLS, ">$ROOT_DIR/$MODULE-symbols.txt") - || die "Can't create $ROOT_DIR/$MODULE-symbols.txt: $!"; - - foreach $symbol (sort (keys (%AllSymbols))) { - print SYMBOLS $symbol . "\n"; - } - - close (SYMBOLS); -} - -############################################################################# -# Function : OutputSymbolsWithoutSince -# Description : Outputs list of all symbols without a since tag to a file -# -# Arguments : none -############################################################################# - -sub OutputSymbolsWithoutSince { - my $n_documented = 0; - my $total = 0; - my $symbol; - my $percent; - my $msg; - - open (SYMBOLS, ">$ROOT_DIR/$MODULE-nosince.txt") - || die "Can't create $ROOT_DIR/$MODULE-nosince.txt: $!"; - - foreach $symbol (sort (keys (%SourceSymbolDocs))) { - if (!defined $Since{$symbol}) { - print SYMBOLS $symbol . "\n"; - } - } - - close (SYMBOLS); -} - - -############################################################################# -# Function : MergeSourceDocumentation -# Description : This merges documentation read from a source file into the -# documentation read in from a template file. -# -# Parameter descriptions override any in the template files. -# Function descriptions are placed before any description from -# the template files. -# -# Arguments : none -############################################################################# - -sub MergeSourceDocumentation { - my $symbol; - my @Symbols; - - if (scalar %SymbolDocs) { - @Symbols=keys (%SymbolDocs); - @TRACE@("num existing entries: ".(scalar @Symbols)."\n"); - } - else { - # filter scanned declarations, with what we suppress from -sections.txt - my %tmp = (); - foreach $symbol (keys (%Declarations)) { - if (defined($KnownSymbols{$symbol}) && $KnownSymbols{$symbol} == 1) { - $tmp{$symbol}=1; - } - } - # , add the rest from -sections.txt - foreach $symbol (keys (%KnownSymbols)) { - if ($KnownSymbols{$symbol} == 1) { - $tmp{$symbol}=1; - } - } - # and add whats found in the source - foreach $symbol (keys (%SourceSymbolDocs)) { - $tmp{$symbol}=1; - } - @Symbols = keys (%tmp); - @TRACE@("num source entries: ".(scalar @Symbols)."\n"); - } - foreach $symbol (@Symbols) { - $AllSymbols{$symbol} = 1; - - my $have_tmpl_docs = 0; - - ## see if the symbol is documented in template - my $tmpl_doc = defined ($SymbolDocs{$symbol}) ? $SymbolDocs{$symbol} : ""; - my $check_tmpl_doc =$tmpl_doc; - # remove all xml-tags and whitespaces - $check_tmpl_doc =~ s/<.*?>//g; - $check_tmpl_doc =~ s/\s//g; - # anything left ? - if ($check_tmpl_doc ne "") { - $have_tmpl_docs = 1; - } else { - # if the docs have just an empty para, don't merge that. - $check_tmpl_doc = $tmpl_doc; - $check_tmpl_doc =~ s/(\s|\n)//msg; - if ($check_tmpl_doc eq "") { - $tmpl_doc = ""; - } - } - - if (exists ($SourceSymbolDocs{$symbol})) { - my $type = $DeclarationTypes {$symbol}; - - @TRACE@("merging [$symbol] from source\n"); - - my $item = "Parameter"; - if (defined ($type)) { - if ($type eq 'STRUCT') { - $item = "Field"; - } elsif ($type eq 'ENUM') { - $item = "Value"; - } elsif ($type eq 'UNION') { - $item = "Field"; - } - } else { - $type="SIGNAL"; - } - - my $src_doc = $SourceSymbolDocs{$symbol}; - # remove leading and training whitespaces - $src_doc =~ s/^\s+//; - $src_doc =~ s/\s+$//; - - # Don't output warnings for overridden titles as titles are - # automatically generated in the -sections.txt file, and thus they - # are often overridden. - if ($have_tmpl_docs && $symbol !~ m/:Title$/) { - # check if content is different - if ($tmpl_doc ne $src_doc) { - #print "[$tmpl_doc] [$src_doc]\n"; - &LogWarning ($SourceSymbolSourceFile{$symbol}, $SourceSymbolSourceLine{$symbol}, - "Documentation in template ".$SymbolSourceFile{$symbol}.":".$SymbolSourceLine{$symbol}." for $symbol being overridden by inline comments."); - } - } - - if ($src_doc ne "") { - $AllDocumentedSymbols{$symbol} = 1; - } - - # Do not add to nothing, it breaks missing docs checks. - my $src_doc_para = ""; - if ($src_doc ne "") { - $src_doc_para = $src_doc; - } - - if ($symbol =~ m/$TMPL_DIR\/.+:Long_Description/) { - $SymbolDocs{$symbol} = "$src_doc_para$tmpl_doc"; - } elsif ($symbol =~ m/$TMPL_DIR\/.+:.+/) { - # For the title/summary/see also section docs we don't want to - # add any tags. - $SymbolDocs{$symbol} = "$src_doc" - } else { - $SymbolDocs{$symbol} = "$src_doc_para$tmpl_doc"; - } - - # merge parameters - if ($symbol =~ m/.*::.*/) { - # For signals we prefer the param names from the source docs, - # since the ones from the templates are likely to contain the - # artificial argn names which are generated by gtkdoc-scangobj. - $SymbolParams{$symbol} = $SourceSymbolParams{$symbol}; - # FIXME: we need to check for empty docs here as well! - } else { - # The templates contain the definitive parameter names and order, - # so we will not change that. We only override the actual text. - my $tmpl_params = $SymbolParams{$symbol}; - if (!defined ($tmpl_params)) { - @TRACE@("No merge needed for $symbol\n"); - $SymbolParams{$symbol} = $SourceSymbolParams{$symbol}; - # FIXME: we still like to get the number of params and merge - # 1) we would noticed that params have been removed/renamed - # 2) we would catch undocumented params - # params are not (yet) exported in -decl.txt so that we - # could easily grab them :/ - } else { - my $params = $SourceSymbolParams{$symbol}; - my $j; - @TRACE@("Merge needed for $symbol, tmpl_params: ",$#$tmpl_params,", source_params: ",$#$params," \n"); - for ($j = 0; $j <= $#$tmpl_params; $j += $PARAM_FIELD_COUNT) { - my $tmpl_param_name = $$tmpl_params[$j]; - - # Try to find the param in the source comment documentation. - my $found = 0; - my $k; - @TRACE@(" try merge param $tmpl_param_name\n"); - for ($k = 0; $k <= $#$params; $k += $PARAM_FIELD_COUNT) { - my $param_name = $$params[$k]; - my $param_desc = $$params[$k + 1]; - - @TRACE@(" test param $param_name\n"); - # We accept changes in case, since the Gnome source - # docs contain a lot of these. - if ("\L$param_name" eq "\L$tmpl_param_name") { - $found = 1; - - # Override the description. - $$tmpl_params[$j + 1] = $param_desc; - - # Set the name to "" to mark it as used. - $$params[$k] = ""; - last; - } - } - - # If it looks like the parameters are there, but not - # in the right place, try to explain a bit better. - if ((!$found) && ($src_doc =~ m/\@$tmpl_param_name:/)) { - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "Parameters for $symbol must start on the line immediately after the function or macro name."); - } - } - - # Now we output a warning if parameters have been described which - # do not exist. - for ($j = 0; $j <= $#$params; $j += $PARAM_FIELD_COUNT) { - my $param_name = $$params[$j]; - if ($param_name) { - # the template builder cannot detect if a macro returns - # a result or not - if(($type eq "MACRO") && ($param_name eq "Returns")) { - # FIXME: do we need to add it then to tmpl_params[] ? - my $num=$#$tmpl_params; - @TRACE@(" adding Returns: to macro docs for $symbol.\n"); - $$tmpl_params[$num+1]="Returns"; - $$tmpl_params[$num+2]=$$params[$j+1]; - next; - } - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "$item described in source code comment block but does not exist. $type: $symbol $item: $param_name."); - } - } - } - } - } else { - if ($have_tmpl_docs) { - $AllDocumentedSymbols{$symbol} = 1; - @TRACE@("merging [$symbol] from template\n"); - } - else { - @TRACE@("[$symbol] undocumented\n"); - } - } - - # if this symbol is documented, check if docs are complete - $check_tmpl_doc = defined ($SymbolDocs{$symbol}) ? $SymbolDocs{$symbol} : ""; - # remove all xml-tags and whitespaces - $check_tmpl_doc =~ s/<.*?>//g; - $check_tmpl_doc =~ s/\s//g; - if ($check_tmpl_doc ne "") { - my $tmpl_params = $SymbolParams{$symbol}; - if (defined ($tmpl_params)) { - my $type = $DeclarationTypes {$symbol}; - - my $item = "Parameter"; - if (defined ($type)) { - if ($type eq 'STRUCT') { - $item = "Field"; - } elsif ($type eq 'ENUM') { - $item = "Value"; - } elsif ($type eq 'UNION') { - $item = "Field"; - } - } else { - $type="SIGNAL"; - } - - @TRACE@("Check param docs for $symbol, tmpl_params: ",$#$tmpl_params," entries, type=$type\n"); - - if ($#$tmpl_params > 0) { - my $j; - for ($j = 0; $j <= $#$tmpl_params; $j += $PARAM_FIELD_COUNT) { - # Output a warning if the parameter is empty and - # remember for stats. - my $tmpl_param_name = $$tmpl_params[$j]; - my $tmpl_param_desc = $$tmpl_params[$j + 1]; - if ($tmpl_param_name ne "void" && $tmpl_param_desc !~ m/\S/) { - if (exists ($AllIncompleteSymbols{$symbol})) { - $AllIncompleteSymbols{$symbol}.=", ".$tmpl_param_name; - } else { - $AllIncompleteSymbols{$symbol}=$tmpl_param_name; - } - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "$item description for $symbol"."::"."$tmpl_param_name is missing in source code comment block."); - } - } - } - else { - if ($#$tmpl_params == 0) { - $AllIncompleteSymbols{$symbol}=""; - &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol), - "$item descriptions for $symbol are missing in source code comment block."); - } - # $#$tmpl_params==-1 means we don't know about parameters - # this unfortunately does not tell if there should be some - } - } - } - } - @TRACE@("num doc entries: ".(scalar %SymbolDocs)."\n"); -} - -############################################################################# -# Function : IsEmptyDoc -# Description : Check if a doc-string is empty. Its also regarded as empty if -# it only consist of whitespace or e.g. FIXME. -# Arguments : the doc-string -############################################################################# -sub IsEmptyDoc { - my ($doc) = @_; - - if ($doc =~ /^\s*$/) { - return 1; - } - - if ($doc =~ /^\s*\s*(FIXME)?\s*<\/para>\s*$/) { - return 1; - } - - return 0; -} - -############################################################################# -# Function : ConvertMarkDown -# Description : Converts mark down syntax to the respective docbook. -# http://de.wikipedia.org/wiki/Markdown -# Inspired by the design of ParseDown -# http://parsedown.org/ -# Copyright (c) 2013 Emanuil Rusev, erusev.com -# Arguments : the symbol name, the doc-string -############################################################################# - -sub ConvertMarkDown { - my ($symbol, $text) = @_; - - $text = &MarkDownParse ($text, $symbol); - - return $text -} - -# SUPPORTED MARKDOWN -# ================== -# -# Atx-style Headers -# ----------------- -# -# # Header 1 -# -# ## Header 2 ## -# -# Setext-style Headers -# -------------------- -# -# Header 1 -# ======== -# -# Header 2 -# -------- -# -# Ordered (unnested) Lists -# ------------------------ -# -# 1. item 1 -# -# 1. item 2 with loooong -# description -# -# 3. item 3 -# -# Note: we require a blank line above the list items -# - -# TODO(ensonic): it would be nice to add id parameters to the refsect2 elements - -sub MarkDownParseBlocks { - my ($linesref, $symbol, $context) = @_; - my $line; - my @md_blocks = (); - my $md_block = { type => "" }; - - OUTER: foreach $line (@$linesref) { - my $first_char = substr ($line, 0, 1); - my $deindented_line; - - @TRACE@("in '".$md_block->{"type"}."' state, parsing '$line'"); - - if ($md_block->{"type"} eq "markup") { - if (!$md_block->{"closed"}) { - if (index ($line, $md_block->{"start"}) != -1) { - $md_block->{"depth"}++; - } - if (index ($line, $md_block->{"end"}) != -1) { - if ($md_block->{"depth"} > 0) { - $md_block->{"depth"}--; - } else { - @TRACE@("closing tag '$line'"); - $md_block->{"closed"} = 1; - # TODO(ensonic): reparse inner text with MarkDownParseLines? - } - } - $md_block->{"text"} .= "\n" . $line; - @TRACE@("add to markup"); - next OUTER; - } - } - - $deindented_line = $line; - $deindented_line =~ s/^\s+//; - - if ($md_block->{"type"} eq "heading") { - # a heading is ended by any level less than or equal - if ($md_block->{"level"} == 1) { - if ($line =~ /^={4,}[ \t]*$/) { - my $text = pop @{$md_block->{"lines"}}; - $md_block->{"interrupted"} = 0; - push @md_blocks, $md_block; - - $md_block = { type => "heading", - text => $text, - lines => [], - level => 1 }; - next OUTER; - } elsif ($line =~ /^[#][ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$/) { - $md_block->{"interrupted"} = 0; - push @md_blocks, $md_block; - - $md_block = { type => "heading", - text => $1, - id => $2, - lines => [], - level => 1 }; - next OUTER; - } else { - # push lines into the block until the end is reached - push @{$md_block->{"lines"}}, $line; - next OUTER; - } - } else { - if ($line =~ /^[=]{4,}[ \t]*$/) { - my $text = pop @{$md_block->{"lines"}}; - $md_block->{"interrupted"} = 0; - push @md_blocks, $md_block; - - $md_block = { type => "heading", - text => $text, - lines => [], - level => 1 }; - next OUTER; - } elsif ($line =~ /^[-]{4,}[ \t]*$/) { - my $text = pop @{$md_block->{"lines"}}; - $md_block->{"interrupted"} = 0; - push @md_blocks, $md_block; - - $md_block = { type => "heading", - text => $text, - lines => [], - level => 2 }; - next OUTER; - } elsif ($line =~ /^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$/) { - $md_block->{"interrupted"} = 0; - push @md_blocks, $md_block; - - $md_block = { type => "heading", - text => $2, - id => $3, - lines => [], - level => length($1) }; - next OUTER; - } else { - # push lines into the block until the end is reached - push @{$md_block->{"lines"}}, $line; - next OUTER; - } - } - } elsif ($md_block->{"type"} eq "code") { - if ($line =~ /^[ \t]*\]\|(.*)/) { - push @md_blocks, $md_block; - $md_block = { type => "paragraph", - text => "$1", - lines => [] }; - } else { - push @{$md_block->{"lines"}}, $line; - } - next OUTER; - } - - if ($deindented_line eq "") { - $md_block->{"interrupted"} = 1; - next; - } - - if ($md_block->{"type"} eq "quote") { - if (!$md_block->{"interrupted"}) { - $line =~ s/^[ ]*>[ ]?//; - push @{$md_block->{"lines"}}, $line; - next OUTER; - } - } elsif ($md_block->{"type"} eq "li") { - my $marker = $md_block->{"marker"}; - if ($line =~ /^([ ]{0,3})($marker)[ ](.*)/) { - my $indentation = $1; - if ($md_block->{"indentation"} ne $indentation) { - push @{$md_block->{"lines"}}, $line; - } else { - my $lines = $3; - my $ordered = $md_block->{"ordered"}; - $lines =~ s/^[ ]{0,4}//; - $md_block->{"last"} = 0; - push @md_blocks, $md_block; - $md_block = { type => "li", - ordered => $ordered, - indentation => $indentation, - marker => $marker, - first => 0, - last => 1, - lines => [ $lines ] }; - } - next OUTER; - } - - if ($md_block->{"interrupted"}) { - if ($first_char eq " ") { - push @{$md_block->{"lines"}}, ""; - $line =~ s/^[ ]{0,4}//; - push @{$md_block->{"lines"}}, $line; - $md_block->{"interrupted"} = 0; - next OUTER; - } - } else { - $line =~ s/^[ ]{0,4}//; - push @{$md_block->{"lines"}}, $line; - next OUTER; - } - } - - # indentation sensitive types - @TRACE@("parsing '$line'"); - - if ($line =~ /^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$/) { - # atx heading (#) - push @md_blocks, $md_block; - - $md_block = { type => "heading", - text => $2, - id => $3, - lines => [], - level => length($1) }; - - next OUTER; - } elsif ($line =~ /^={4,}[ \t]*$/) { - # setext heading (====) - - if ($md_block->{"type"} eq "paragraph" && $md_block->{"interrupted"}) { - push @md_blocks, $md_block; - $md_block->{"type"} = "heading"; - $md_block->{"lines"} = []; - $md_block->{"level"} = 1; - } - - next OUTER; - } elsif ($line =~ /^-{4,}[ \t]*$/) { - # setext heading (-----) - - if ($md_block->{"type"} eq "paragraph" && $md_block->{"interrupted"}) { - push @md_blocks, $md_block; - $md_block->{"type"} = "heading"; - $md_block->{"lines"} = []; - $md_block->{"level"} = 2; - } - - next OUTER; - } elsif ($line =~ /^[ \t]*\|\[[ ]*(?:)?/) { - # code - $md_block->{"interrupted"} = 1; - push @md_blocks, $md_block; - $md_block = { type => "code", - language => $1, - lines => [] }; - next OUTER; - } - - # indentation insensitive types - if ($line =~ /^[ ]* "markup", - text => $deindented_line, - start => "<", - end => ">", - closed => 0, - depth => 0 }; - - } elsif ($line =~ /^[ ]*<\??(\w+)[^>]*([\/\?])?[ \t]*>/) { - # markup, including - my $tag = $1; - my $is_self_closing = defined($2); - - # skip link markdown - # TODO(ensonic): consider adding more uri schemes (ftp, ...) - if ($tag =~ /^https?/) { - @TRACE@("skipping link '$tag'"); - } else { - # for TEXT_LEVEL_ELEMENTS, we want to keep them as-is in the paragraph - # instead of creation a markdown block. - my $scanning_for_end_of_text_level_tag = ( - $md_block->{"type"} eq "paragraph" && - defined($md_block->{"start"}) && - !$md_block->{"closed"}); - @TRACE@("markup found '$tag', scanning $scanning_for_end_of_text_level_tag ?"); - if (!$MD_TEXT_LEVEL_ELEMENTS{$tag} && !$scanning_for_end_of_text_level_tag) { - push @md_blocks, $md_block; - - if ($is_self_closing) { - @TRACE@("self-closing docbook '$tag'"); - $md_block = { type => "self-closing tag", - text => $deindented_line }; - $is_self_closing = 0; - next OUTER; - } - - @TRACE@("new markup '$tag'"); - $md_block = { type => "markup", - text => $deindented_line, - start => "<" . $tag . ">", - end => "", - closed => 0, - depth => 0 }; - if ($deindented_line =~ /<\/$tag>/) { - $md_block->{"closed"} = 1; - } - next OUTER; - } else { - if ($MD_TEXT_LEVEL_ELEMENTS{$tag}) { - @TRACE@("text level docbook '$tag' in '".$md_block->{"type"}."' state"); - # TODO(ensonic): handle nesting - if (!$scanning_for_end_of_text_level_tag) { - if ($deindented_line !~ /<\/$tag>/) { - @TRACE@("new text level markup '$tag'"); - $md_block->{"start"} = "<" . $tag . ">"; - $md_block->{"end"} = ""; - $md_block->{"closed"} = 0; - @TRACE@("scanning for end of '$tag'"); - } - } else { - if ($deindented_line =~ /$md_block->{"end"}/) { - $md_block->{"closed"} = 1; - @TRACE@("found end of '$tag'"); - } - } - } - } - } - } elsif ($line =~ /^([ ]*)[*+-][ ](.*)/) { - # li - push @md_blocks, $md_block; - my $lines = $2; - my $indentation = $1; - $lines =~ s/^[ ]{0,4}//; - $md_block = { type => "li", - ordered => 0, - indentation => $indentation, - marker => "[*+-]", - first => 1, - last => 1, - lines => [ $lines ] }; - next OUTER; - } elsif ($line =~ /^[ ]*>[ ]?(.*)/) { - push @md_blocks, $md_block; - $md_block = { type => "quote", - lines => [ $1 ] }; - next OUTER; - } - - # list item - if ($line =~ /^([ ]{0,4})\d+[.][ ]+(.*)/) { - push @md_blocks, $md_block; - my $lines = $2; - my $indentation = $1; - $lines =~ s/^[ ]{0,4}//; - - $md_block = { type => "li", - ordered => 1, - indentation => $indentation, - marker => "\\d+[.]", - first => 1, - last => 1, - lines => [ $lines ] }; - - next; - } - - # paragraph - if ($md_block->{"type"} eq "paragraph") { - if ($md_block->{"interrupted"}) { - push @md_blocks, $md_block; - $md_block = { type => "paragraph", - interrupted => 0, - text => $line }; - @TRACE@("new paragraph due to interrupted"); - } else { - $md_block->{"text"} .= "\n" . $line; - @TRACE@("add to paragraph"); - } - } else { - push @md_blocks, $md_block; - $md_block = { type => "paragraph", - text => $line }; - @TRACE@("new paragraph due to different block type"); - } - } - - push @md_blocks, $md_block; - - shift @md_blocks; - - return @md_blocks; -} - -sub MarkDownParseSpanElementsInner { - my ($text, $markersref) = @_; - my $markup = ""; - my %markers = map { $_ => 1 } @$markersref; - - while ($text ne "") { - my $closest_marker = ""; - my $closest_marker_index = 0; - my $closest_marker_position = -1; - my $text_marker = ""; - my $i = 0; - my $offset = 0; - my @markers_rest; - my $marker; - my $use; - - while ( ($marker, $use) = each %markers ) { - my $marker_position; - - if (!$use) { - next; - } - - $marker_position = index ($text, $marker); - - if ($marker_position < 0) { - $markers{$marker} = 0; - next; - } - - if ($closest_marker eq "" || $marker_position < $closest_marker_position) { - $closest_marker = $marker; - $closest_marker_index = $i; - $closest_marker_position = $marker_position; - } - } - - if ($closest_marker_position >= 0) { - $text_marker = substr ($text, $closest_marker_position); - } - - if ($text_marker eq "") { - $markup .= $text; - $text = ""; - next; # last - } - - $markup .= substr ($text, 0, $closest_marker_position); - $text = substr ($text, $closest_marker_position); - @markers_rest = map { $markers{$_} ? ($_ eq $closest_marker ? () : $_) : () } keys %markers; - - if ($closest_marker eq "![" || $closest_marker eq "[") { - my %element; - - if (index ($text, "]") && $text =~ /\[((?:[^][]|(?R))*)\]/) { - my $remaining_text; - - %element = ( "!" => (substr ($text, 0, 1) eq "!"), - "a" => $1 ); - - $offset = length ($&); - if ($element{"!"}) { - $offset++; - } - - $remaining_text = substr ($text, $offset); - if ($remaining_text =~ /^\([ ]*([^)'"]*?)(?:[ ]+['"](.+?)['"])?[ ]*\)/) { - $element{"»"} = $1; - if (defined ($2)) { - $element{"#"} = $2; - } - $offset += length ($&); - } elsif ($remaining_text =~ /^\s*\[([^\]<]*?)\]/) { - $element{"ref"} = $1; - $offset += length ($&); - } else { - undef %element; - } - } - - if (%element) { - if ($element{"»"}) { - $element{"»"} =~ s/&/&/g; - $element{"»"} =~ s/"; - - if (defined ($element{"a"})) { - $markup .= "" . $element{"a"} . ""; - } - - $markup .= ""; - } elsif ($element{"ref"}) { - $element{"a"} = &MarkDownParseSpanElementsInner ($element{"a"}, \@markers_rest); - $markup .= ""; - } else { - $element{"a"} = &MarkDownParseSpanElementsInner ($element{"a"}, \@markers_rest); - $markup .= ""; - } - } else { - $markup .= $closest_marker; - if ($closest_marker eq "![") { - $offset = 2; - } else { - $offset = 1; - } - } - } elsif ($closest_marker eq "<") { - if ($text =~ /^<(https?:[\/]{2}[^\s]+?)>/i) { - my $element_url = $1; - $element_url =~ s/&/&/g; - $element_url =~ s/" . $element_url . ""; - $offset = length ($&); - } elsif ($text =~ /^<([A-Za-z0-9._-]+?@[A-Za-z0-9._-]+?)>/) { - $markup .= "" . $1 . ""; - $offset = length ($&); - } elsif ($text =~ /^<[^>]+?>/) { - $markup .= $&; - $offset = length ($&); - } else { - $markup .= "<"; - $offset = 1; - } - } elsif ($closest_marker eq "\\") { - my $special_char = substr ($text, 1, 1); - if ($MD_ESCAPABLE_CHARS{$special_char} || - $MD_GTK_ESCAPABLE_CHARS{$special_char}) { - $markup .= $special_char; - $offset = 2; - } else { - $markup .= "\\"; - $offset = 1; - } - } elsif ($closest_marker eq "`") { - if ($text =~ /^(`+)([^`]+?)\1(?!`)/) { - my $element_text = $2; - $markup .= "" . $element_text . ""; - $offset = length ($&); - } else { - $markup .= "`"; - $offset = 1; - } - } elsif ($closest_marker eq "@") { - # Convert '@param()' - # FIXME: we could make those also links ($symbol.$2), but that would be less - # useful as the link target is a few lines up or down - if ($text =~ /^(\A|[^\\])\@(\w+((\.|->)\w+)*)\s*\(\)/) { - $markup .= $1 . "" . $2 . "()\n"; - $offset = length ($&); - } elsif ($text =~ /^(\A|[^\\])\@(\w+((\.|->)\w+)*)/) { - # Convert '@param', but not '\@param'. - $markup .= $1 . "" . $2 . "\n"; - $offset = length ($&); - } elsif ($text =~ /^\\\@/) { - $markup .= "\@"; - $offset = length ($&); - } else { - $markup .= "@"; - $offset = 1; - } - } elsif ($closest_marker eq "#") { - if ($text =~ /^(\A|[^\\])#([\w\-:\.]+[\w]+)\s*\(\)/) { - # handle #Object.func() - $markup .= $1 . &MakeXRef ($2, &tagify ($2 . "()", "function")); - $offset = length ($&); - } elsif ($text =~ /^(\A|[^\\])#([\w\-:\.]+[\w]+)/) { - # Convert '#symbol', but not '\#symbol'. - $markup .= $1 . &MakeHashXRef ($2, "type"); - $offset = length ($&); - } elsif ($text =~ /^\\#/) { - $markup .= "#"; - $offset = length ($&); - } else { - $markup .= "#"; - $offset = 1; - } - } elsif ($closest_marker eq "%") { - if ($text =~ /^(\A|[^\\])\%(-?\w+)/) { - # Convert '%constant', but not '\%constant'. - # Also allow negative numbers, e.g. %-1. - $markup .= $1 . &MakeXRef ($2, &tagify ($2, "literal")); - $offset = length ($&); - } elsif ($text =~ /^\\%/) { - $markup .= "\%"; - $offset = length ($&); - } else { - $markup .= "%"; - $offset = 1; - } - } - - if ($offset > 0) { - $text = substr ($text, $offset); - } - } - - return $markup; -} - -sub MarkDownParseSpanElements { - my ($text) = @_; - my @markers = ( "\\", "<", "![", "[", "`", "%", "#", "@" ); - - $text = &MarkDownParseSpanElementsInner ($text, \@markers); - - # Convert 'function()' or 'macro()'. - # if there is abc_*_def() we don't want to make a link to _def() - # FIXME: also handle abc(def(....)) : but that would need to be done recursively :/ - $text =~ s/([^\*.\w])(\w+)\s*\(\)/$1.&MakeXRef($2, &tagify($2 . "()", "function"));/eg; - - return $text; -} - -sub ReplaceEntities { - my ($text, $symbol) = @_; - my $warn = ""; - my @entities = ( [ "<", "<" ], - [ ">", ">" ], - [ "*", "*" ], - [ "#", "#" ], - [ "%", "%"], - [ ":", ":" ], - [ """, "\"" ], - [ "'", "'" ], - [ " ", " " ], - [ "&", "&" ] ); # Do this last, or the others get messed up. - my $i; - - # Expand entities in even inside CDATA since - # we changed the definition of |[ to add CDATA - for ($i = 0; $i <= $#entities; $i++) { - $text =~ s/$entities[$i][0]/$entities[$i][1]/g; - } - - return $text; -} - -sub MarkDownOutputDocBook { - my ($blocksref, $symbol, $context) = @_; - my $output = ""; - my $block; - my @blocks = @$blocksref; - - foreach $block (@blocks) { - my $text; - my $title; - - #$output .= "\n\n"; - - if ($block->{"type"} eq "paragraph") { - $text = &MarkDownParseSpanElements ($block->{"text"}); - if ($context eq "li" && $output eq "") { - if ($block->{"interrupted"}) { - $output .= "\n$text\n"; - } else { - $output .= "$text"; - if ($#blocks > 0) { - $output .= "\n"; - } - } - } else { - $output .= "$text\n"; - } - - } elsif ($block->{"type"} eq "heading") { - my $tag; - - $title = &MarkDownParseSpanElements ($block->{"text"}); - - if ($block->{"level"} == 1) { - $tag = "refsect2"; - } else { - $tag = "refsect3"; - } - - $text = &MarkDownParseLines ($block->{"lines"}, $symbol, "heading"); - if (defined ($block->{"id"})) { - $output .= "<$tag id=\"" . $block->{"id"} . "\">"; - } else { - $output .= "<$tag>"; - } - - $output .= "$title$text\n"; - } elsif ($block->{"type"} eq "li") { - my $tag = "itemizedlist"; - - if ($block->{"first"}) { - if ($block->{"ordered"}) { - $tag = "orderedlist"; - } - $output .= "<$tag>\n"; - } - - if ($block->{"interrupted"}) { - push @{$block->{"lines"}}, ""; - } - - $text = &MarkDownParseLines ($block->{"lines"}, $symbol, "li"); - $output .= "".$text."\n"; - if ($block->{"last"}) { - if ($block->{"ordered"}) { - $tag = "orderedlist"; - } - $output .= "\n"; - } - } elsif ($block->{"type"} eq "quote") { - $text = &MarkDownParseLines ($block->{"lines"}, $symbol, "quote"); - $output .= "
\n$text
\n"; - } elsif ($block->{"type"} eq "code") { - my $tag = "programlisting"; - - if ($block->{"language"}) { - if ($block->{"language"} eq "plain") { - $output .= "{"language"} . "\">{"lines"}}) { - $output .= &ReplaceEntities ($_, $symbol) . "\n"; - } - $output .= "]]>\n"; - } elsif ($block->{"type"} eq "markup") { - $text = &ExpandAbbreviations($symbol, $block->{"text"}); - $output .= $text."\n"; - } else { - $output .= $block->{"text"}."\n"; - } - #$output .= "\n\n"; - } - - return $output; -} - -sub MarkDownParseLines { - my ($linesref, $symbol, $context) = @_; - my $output; - my @lines = @$linesref; - my @blocks; - - @blocks = &MarkDownParseBlocks (\@lines, $symbol, $context); - $output = &MarkDownOutputDocBook (\@blocks, $symbol, $context); - - return $output; -} - -sub MarkDownParse { - my ($text, $symbol) = @_; - my @lines; - - # take out some variability in line endings - $text =~ s%\r\n%\n%g; - $text =~ s%\r%\n%g; - - # split lines - @lines = split("\n", $text); - $text = MarkDownParseLines(\@lines, $symbol, ""); - - return $text; -} - -############################################################################# -# LIBRARY FUNCTIONS - These functions are used in both gtkdoc-mkdb and -# gtkdoc-mktmpl and should eventually be moved to a -# separate library. -############################################################################# - -############################################################################# -# Function : ReadDeclarationsFile -# Description : This reads in a file containing the function/macro/enum etc. -# declarations. -# -# Note that in some cases there are several declarations with -# the same name, e.g. for conditional macros. In this case we -# set a flag in the %DeclarationConditional hash so the -# declaration is not shown in the docs. -# -# If a macro and a function have the same name, e.g. for -# gtk_object_ref, the function declaration takes precedence. -# -# Some opaque structs are just declared with 'typedef struct -# _name name;' in which case the declaration may be empty. -# The structure may have been found later in the header, so -# that overrides the empty declaration. -# -# Arguments : $file - the declarations file to read -# $override - if declarations in this file should override -# any current declaration. -############################################################################# - -sub ReadDeclarationsFile { - my ($file, $override) = @_; - - if ($override == 0) { - %Declarations = (); - %DeclarationTypes = (); - %DeclarationConditional = (); - %DeclarationOutput = (); - } - - open (INPUT, $file) - || die "Can't open $file: $!"; - my $declaration_type = ""; - my $declaration_name; - my $declaration; - my $is_deprecated = 0; - while () { - if (!$declaration_type) { - if (m/^<([^>]+)>/) { - $declaration_type = $1; - $declaration_name = ""; - @TRACE@("Found declaration: $declaration_type\n"); - $declaration = ""; - } - } else { - if (m%^(.*)%) { - $declaration_name = $1; - } elsif (m%^%) { - $is_deprecated = 1; - } elsif (m%^%) { - @TRACE@("Found end of declaration: $declaration_name\n"); - # Check that the declaration has a name - if ($declaration_name eq "") { - &LogWarning ($file, $., "$declaration_type has no name.\n"); - } - - # If the declaration is an empty typedef struct _XXX XXX - # set the flag to indicate the struct has a typedef. - if (($declaration_type eq 'STRUCT' || $declaration_type eq 'UNION') - && $declaration =~ m/^\s*$/) { - @TRACE@("Struct has typedef: $declaration_name\n"); - $StructHasTypedef{$declaration_name} = 1; - } - - # Check if the symbol is already defined. - if (defined ($Declarations{$declaration_name}) - && $override == 0) { - # Function declarations take precedence. - if ($DeclarationTypes{$declaration_name} eq 'FUNCTION') { - # Ignore it. - } elsif ($declaration_type eq 'FUNCTION') { - if ($is_deprecated) { - $Deprecated{$declaration_name} = ""; - } - $Declarations{$declaration_name} = $declaration; - $DeclarationTypes{$declaration_name} = $declaration_type; - } elsif ($DeclarationTypes{$declaration_name} - eq $declaration_type) { - # If the existing declaration is empty, or is just a - # forward declaration of a struct, override it. - if ($declaration_type eq 'STRUCT' || $declaration_type eq 'UNION') { - if ($Declarations{$declaration_name} =~ m/^\s*((struct|union)\s+\w+\s*;)?\s*$/) { - if ($is_deprecated) { - $Deprecated{$declaration_name} = ""; - } - $Declarations{$declaration_name} = $declaration; - } elsif ($declaration =~ m/^\s*((struct|union)\s+\w+\s*;)?\s*$/) { - # Ignore an empty or forward declaration. - } else { - &LogWarning ($file, $., "Structure $declaration_name has multiple definitions."); - } - } else { - # set flag in %DeclarationConditional hash for - # multiply defined macros/typedefs. - $DeclarationConditional{$declaration_name} = 1; - } - } else { - &LogWarning ($file, $., "$declaration_name has multiple definitions."); - } - } else { - if ($is_deprecated) { - $Deprecated{$declaration_name} = ""; - } - $Declarations{$declaration_name} = $declaration; - $DeclarationTypes{$declaration_name} = $declaration_type; - } - - $declaration_type = ""; - $is_deprecated = 0; - } else { - $declaration .= $_; - } - } - } - close (INPUT); -} - - -############################################################################# -# Function : ReadSignalsFile -# Description : This reads in an existing file which contains information on -# all GTK signals. It creates the arrays @SignalNames and -# @SignalPrototypes containing info on the signals. The first -# line of the SignalPrototype is the return type of the signal -# handler. The remaining lines are the parameters passed to it. -# The last parameter, "gpointer user_data" is always the same -# so is not included. -# Arguments : $file - the file containing the signal handler prototype -# information. -############################################################################# - -sub ReadSignalsFile { - my ($file) = @_; - - my $in_signal = 0; - my $signal_object; - my $signal_name; - my $signal_returns; - my $signal_flags; - my $signal_prototype; - - # Reset the signal info. - @SignalObjects = (); - @SignalNames = (); - @SignalReturns = (); - @SignalFlags = (); - @SignalPrototypes = (); - - if (! -f $file) { - return; - } - if (!open (INPUT, $file)) { - warn "Can't open $file - skipping signals\n"; - return; - } - while () { - if (!$in_signal) { - if (m/^/) { - $in_signal = 1; - $signal_object = ""; - $signal_name = ""; - $signal_returns = ""; - $signal_prototype = ""; - } - } else { - if (m/^(.*)<\/NAME>/) { - $signal_name = $1; - if ($signal_name =~ m/^(.*)::(.*)$/) { - $signal_object = $1; - ($signal_name = $2) =~ s/_/-/g; - @TRACE@("Found signal: $signal_name\n"); - } else { - &LogWarning ($file, $., "Invalid signal name: $signal_name."); - } - } elsif (m/^(.*)<\/RETURNS>/) { - $signal_returns = $1; - } elsif (m/^(.*)<\/FLAGS>/) { - $signal_flags = $1; - } elsif (m%^%) { - @TRACE@("Found end of signal: ${signal_object}::${signal_name}\nReturns: ${signal_returns}\n${signal_prototype}"); - push (@SignalObjects, $signal_object); - push (@SignalNames, $signal_name); - push (@SignalReturns, $signal_returns); - push (@SignalFlags, $signal_flags); - push (@SignalPrototypes, $signal_prototype); - $in_signal = 0; - } else { - $signal_prototype .= $_; - } - } - } - close (INPUT); -} - - -############################################################################# -# Function : ReadTemplateFile -# Description : This reads in the manually-edited documentation file -# corresponding to the file currently being created, so we can -# insert the documentation at the appropriate places. -# It outputs %SymbolTypes, %SymbolDocs and %SymbolParams, which -# is a hash of arrays. -# NOTE: This function is duplicated in gtkdoc-mktmpl (but -# slightly different). -# Arguments : $docsfile - the template file to read in. -# $skip_unused_params - 1 if the unused parameters should be -# skipped. -############################################################################# - -sub ReadTemplateFile { - my ($docsfile, $skip_unused_params) = @_; - - my $template = "$docsfile.sgml"; - if (! -f $template) { - @TRACE@("File doesn't exist: $template\n"); - return 0; - } - - # start with empty hashes, we merge the source comment for each file - # afterwards - %SymbolDocs = (); - %SymbolTypes = (); - %SymbolParams = (); - - my $current_type = ""; # Type of symbol being read. - my $current_symbol = ""; # Name of symbol being read. - my $symbol_doc = ""; # Description of symbol being read. - my @params; # Parameter names and descriptions of current - # function/macro/function typedef. - my $current_param = -1; # Index of parameter currently being read. - # Note that the param array contains pairs - # of param name & description. - my $in_unused_params = 0; # True if we are reading in the unused params. - my $in_deprecated = 0; - my $in_since = 0; - my $in_stability = 0; - - open (DOCS, "$template") - || die "Can't open $template: $!"; - - @TRACE@("reading template $template"); - - while () { - if (m/^/) { - my $type = $1; - my $symbol = $2; - if ($symbol eq "Title" - || $symbol eq "Short_Description" - || $symbol eq "Long_Description" - || $symbol eq "See_Also" - || $symbol eq "Stability_Level" - || $symbol eq "Include" - || $symbol eq "Image") { - - $symbol = $docsfile . ":" . $symbol; - } - - @TRACE@("Found symbol: $symbol\n"); - # Remember file and line for the symbol - $SymbolSourceFile{$symbol} = $template; - $SymbolSourceLine{$symbol} = $.; - - # Store previous symbol, but remove any trailing blank lines. - if ($current_symbol ne "") { - $symbol_doc =~ s/\s+$//; - $SymbolTypes{$current_symbol} = $current_type; - $SymbolDocs{$current_symbol} = $symbol_doc; - - # Check that the stability level is valid. - if ($StabilityLevel{$current_symbol}) { - $StabilityLevel{$current_symbol} = &ParseStabilityLevel($StabilityLevel{$current_symbol}, $template, $., "Stability level for $current_symbol"); - } - - if ($current_param >= 0) { - $SymbolParams{$current_symbol} = [ @params ]; - } else { - # Delete any existing params in case we are overriding a - # previously read template. - delete $SymbolParams{$current_symbol}; - } - } - $current_type = $type; - $current_symbol = $symbol; - $current_param = -1; - $in_unused_params = 0; - $in_deprecated = 0; - $in_since = 0; - $in_stability = 0; - $symbol_doc = ""; - @params = (); - - } elsif (m/^/) { - @TRACE@("Found unused parameters\n"); - $in_unused_params = 1; - next; - - } elsif ($in_unused_params && $skip_unused_params) { - # When outputting the DocBook we skip unused parameters. - @TRACE@("Skipping unused param: $_"); - next; - - } else { - # Check if param found. Need to handle "..." and "format...". - if (s/^\@([\w\.]+):\040?//) { - my $param_name = $1; - my $param_desc = $_; - # Allow variations of 'Returns' - if ($param_name =~ m/^[Rr]eturns?$/) { - $param_name = "Returns"; - } - # Allow varargs variations - if ($param_name =~ m/^.*\.\.\.$/) { - $param_name = "..."; - } - - # strip trailing whitespaces and blank lines - s/\s+\n$/\n/m; - s/\n+$/\n/sm; - @TRACE@("Found param for symbol $current_symbol : '$param_name'= '$_'"); - - if ($param_name eq "Deprecated") { - $in_deprecated = 1; - $Deprecated{$current_symbol} = $_; - } elsif ($param_name eq "Since") { - $in_since = 1; - chomp; - $Since{$current_symbol} = $_; - } elsif ($param_name eq "Stability") { - $in_stability = 1; - $StabilityLevel{$current_symbol} = $_; - } else { - push (@params, $param_name); - push (@params, $param_desc); - $current_param += $PARAM_FIELD_COUNT; - } - } else { - # strip trailing whitespaces and blank lines - s/\s+\n$/\n/m; - s/\n+$/\n/sm; - - if (!m/^\s+$/) { - if ($in_deprecated) { - $Deprecated{$current_symbol} .= $_; - } elsif ($in_since) { - &LogWarning ($template, $., "multi-line since docs found"); - #$Since{$current_symbol} .= $_; - } elsif ($in_stability) { - $StabilityLevel{$current_symbol} .= $_; - } elsif ($current_param >= 0) { - $params[$current_param] .= $_; - } else { - $symbol_doc .= $_; - } - } - } - } - } - - # Remember to finish the current symbol doccs. - if ($current_symbol ne "") { - - $symbol_doc =~ s/\s+$//; - $SymbolTypes{$current_symbol} = $current_type; - $SymbolDocs{$current_symbol} = $symbol_doc; - - # Check that the stability level is valid. - if ($StabilityLevel{$current_symbol}) { - $StabilityLevel{$current_symbol} = &ParseStabilityLevel($StabilityLevel{$current_symbol}, $template, $., "Stability level for $current_symbol"); - } - - if ($current_param >= 0) { - $SymbolParams{$current_symbol} = [ @params ]; - } else { - # Delete any existing params in case we are overriding a - # previously read template. - delete $SymbolParams{$current_symbol}; - } - } - - close (DOCS); - return 1; -} - - -############################################################################# -# Function : ReadObjectHierarchy -# Description : This reads in the $MODULE-hierarchy.txt file containing all -# the GtkObject subclasses described in this module (and their -# ancestors). -# It places them in the @Objects array, and places their level -# in the object hierarchy in the @ObjectLevels array, at the -# same index. GtkObject, the root object, has a level of 1. -# -# This also generates tree_index.sgml as it goes along. -# -# Arguments : none -############################################################################# - -sub ReadObjectHierarchy { - @Objects = (); - @ObjectLevels = (); - - if (! -f $OBJECT_TREE_FILE) { - return; - } - if (!open (INPUT, $OBJECT_TREE_FILE)) { - warn "Can't open $OBJECT_TREE_FILE - skipping object tree\n"; - return; - } - - # Only emit objects if they are supposed to be documented, or if - # they have documented children. To implement this, we maintain a - # stack of pending objects which will be emitted if a documented - # child turns up. - my @pending_objects = (); - my @pending_levels = (); - my $root; - my @tree = (); - while () { - if (m/\S+/) { - my $object = $&; - my $level = (length($`)) / 2 + 1; - my $xref = ""; - - if ($level == 1) { - $root = $object; - } - - while (($#pending_levels >= 0) && ($pending_levels[$#pending_levels] >= $level)) { - my $pobject = pop(@pending_objects); - my $plevel = pop(@pending_levels); - } - - push (@pending_objects, $object); - push (@pending_levels, $level); - - if (exists($KnownSymbols{$object})) { - while ($#pending_levels >= 0) { - $object = shift @pending_objects; - $level = shift @pending_levels; - $xref = &MakeXRef ($object); - - push (@tree, ' ' x ($level * 4) . "$xref"); - push (@Objects, $object); - push (@ObjectLevels, $level); - $ObjectRoots{$object} = $root; - } - } - #else { - # LogWarning ($OBJECT_TREE_FILE, $., "unknown type $object"); - #} - } - } - close (INPUT); - - # FIXME: use xml - # my $old_tree_index = "$DB_OUTPUT_DIR/tree_index.$xml"; - my $old_tree_index = "$DB_OUTPUT_DIR/tree_index.sgml"; - my $new_tree_index = "$DB_OUTPUT_DIR/tree_index.new"; - - open (OUTPUT, ">$new_tree_index") - || die "Can't create $new_tree_index: $!"; - - print (OUTPUT &MakeDocHeader ("screen")."\n\n".&AddTreeLineArt(\@tree)."\n\n"); - close (OUTPUT); - - &UpdateFileIfChanged ($old_tree_index, $new_tree_index, 0); - - &OutputObjectList; -} - -############################################################################# -# Function : ReadInterfaces -# Description : This reads in the $MODULE.interfaces file. -# -# Arguments : none -############################################################################# - -sub ReadInterfaces { - %Interfaces = (); - - if (! -f $INTERFACES_FILE) { - return; - } - if (!open (INPUT, $INTERFACES_FILE)) { - warn "Can't open $INTERFACES_FILE - skipping interfaces\n"; - return; - } - - while () { - chomp; - my ($object, @ifaces) = split; - if (exists($KnownSymbols{$object}) && $KnownSymbols{$object} == 1) { - my @knownIfaces = (); - - # filter out private interfaces, but leave foreign interfaces - foreach my $iface (@ifaces) { - if (!exists($KnownSymbols{$iface}) || $KnownSymbols{$iface} == 1) { - push (@knownIfaces, $iface); - } - } - - $Interfaces{$object} = join(' ', @knownIfaces); - @TRACE@("Interfaces for $object: $Interfaces{$object}\n"); - } else { - @TRACE@("skipping interfaces for unknown symbol: $object\n"); - } - } - close (INPUT); -} - -############################################################################# -# Function : ReadPrerequisites -# Description : This reads in the $MODULE.prerequisites file. -# -# Arguments : none -############################################################################# - -sub ReadPrerequisites { - %Prerequisites = (); - - if (! -f $PREREQUISITES_FILE) { - return; - } - if (!open (INPUT, $PREREQUISITES_FILE)) { - warn "Can't open $PREREQUISITES_FILE - skipping prerequisites\n"; - return; - } - - while () { - chomp; - my ($iface, @prereqs) = split; - if (exists($KnownSymbols{$iface}) && $KnownSymbols{$iface} == 1) { - my @knownPrereqs = (); - - # filter out private prerequisites, but leave foreign prerequisites - foreach my $prereq (@prereqs) { - if (!exists($KnownSymbols{$prereq}) || $KnownSymbols{$prereq} == 1) { - push (@knownPrereqs, $prereq); - } - } - - $Prerequisites{$iface} = join(' ', @knownPrereqs); - } - } - close (INPUT); -} - -############################################################################# -# Function : ReadArgsFile -# Description : This reads in an existing file which contains information on -# all GTK args. It creates the arrays @ArgObjects, @ArgNames, -# @ArgTypes, @ArgFlags, @ArgNicks and @ArgBlurbs containing info -# on the args. -# Arguments : $file - the file containing the arg information. -############################################################################# - -sub ReadArgsFile { - my ($file) = @_; - - my $in_arg = 0; - my $arg_object; - my $arg_name; - my $arg_type; - my $arg_flags; - my $arg_nick; - my $arg_blurb; - my $arg_default; - my $arg_range; - - # Reset the args info. - @ArgObjects = (); - @ArgNames = (); - @ArgTypes = (); - @ArgFlags = (); - @ArgNicks = (); - @ArgBlurbs = (); - @ArgDefaults = (); - @ArgRanges = (); - - if (! -f $file) { - return; - } - if (!open (INPUT, $file)) { - warn "Can't open $file - skipping args\n"; - return; - } - while () { - if (!$in_arg) { - if (m/^/) { - $in_arg = 1; - $arg_object = ""; - $arg_name = ""; - $arg_type = ""; - $arg_flags = ""; - $arg_nick = ""; - $arg_blurb = ""; - $arg_default = ""; - $arg_range = ""; - } - } else { - if (m/^(.*)<\/NAME>/) { - $arg_name = $1; - if ($arg_name =~ m/^(.*)::(.*)$/) { - $arg_object = $1; - ($arg_name = $2) =~ s/_/-/g; - @TRACE@("Found arg: $arg_name\n"); - } else { - &LogWarning ($file, $., "Invalid argument name: $arg_name"); - } - } elsif (m/^(.*)<\/TYPE>/) { - $arg_type = $1; - } elsif (m/^(.*)<\/RANGE>/) { - $arg_range = $1; - } elsif (m/^(.*)<\/FLAGS>/) { - $arg_flags = $1; - } elsif (m/^(.*)<\/NICK>/) { - $arg_nick = $1; - } elsif (m/^(.*)<\/BLURB>/) { - $arg_blurb = $1; - if ($arg_blurb eq "(null)") { - $arg_blurb = ""; - &LogWarning ($file, $., "Property ${arg_object}:${arg_name} has no documentation."); - } - } elsif (m/^(.*)<\/DEFAULT>/) { - $arg_default = $1; - } elsif (m%^%) { - @TRACE@("Found end of arg: ${arg_object}::${arg_name}\n${arg_type} : ${arg_flags}\n"); - push (@ArgObjects, $arg_object); - push (@ArgNames, $arg_name); - push (@ArgTypes, $arg_type); - push (@ArgRanges, $arg_range); - push (@ArgFlags, $arg_flags); - push (@ArgNicks, $arg_nick); - push (@ArgBlurbs, $arg_blurb); - push (@ArgDefaults, $arg_default); - $in_arg = 0; - } - } - } - close (INPUT); -} - -############################################################################# -# Function : AddTreeLineArt -# Description : Add unicode lineart to a pre-indented string array and returns -# it as as multiline string. -# Arguments : @tree - array of indented strings. -############################################################################# - -sub AddTreeLineArt { - my @tree = @{$_[0]}; - my $i; - my $j; - my $indent; - - # iterate bottom up over the tree - for ($i = $#tree; $i >= 0; $i--) { - # count leading spaces - $tree[$i] =~ /^([^ 4) { - if (substr($tree[$i],$indent-4,1) eq " ") { - substr($tree[$i],$indent-4,4) = "--- "; - } else { - substr($tree[$i],$indent-4,4) = "+-- "; - } - # go lines up while space and insert | - for ($j = $i - 1; ($j >= 0 && substr($tree[$j],$indent-4,1) eq ' '); $j--) { - substr($tree[$j],$indent-4,1) = '|'; - } - } - } - - my $res = join("\n", @tree); - # unicode chars for: ╰── - $res =~ s%---%╰──%g; - # unicde chars for: ├── - $res =~ s%\+--%├──%g; - # unicode char for: │ - $res =~ s%\|%│%g; - - return $res; -} - - -############################################################################# -# Function : CheckIsObject -# Description : Returns 1 if the given name is a GObject or a subclass. -# It uses the global @Objects array. -# Note that the @Objects array only contains classes in the -# current module and their ancestors - not all GObject classes. -# Arguments : $name - the name to check. -############################################################################# - -sub CheckIsObject { - my ($name) = @_; - my $root = $ObjectRoots{$name}; - # Let GBoxed pass as an object here to get -struct appended to the id - # and prevent conflicts with sections. - return (defined($root) and $root ne 'GEnum' and $root ne 'GFlags'); -} - - -############################################################################# -# Function : MakeReturnField -# Description : Pads a string to $RETURN_TYPE_FIELD_WIDTH. -# Arguments : $str - the string to pad. -############################################################################# - -sub MakeReturnField { - my ($str) = @_; - - return $str . (' ' x ($RETURN_TYPE_FIELD_WIDTH - length ($str))); -} - -############################################################################# -# Function : GetSymbolSourceFile -# Description : Get the filename where the symbol docs where taken from. -# Arguments : $symbol - the symbol name -############################################################################# - -sub GetSymbolSourceFile { - my ($symbol) = @_; - - if (defined($SourceSymbolSourceFile{$symbol})) { - return $SourceSymbolSourceFile{$symbol}; - } elsif (defined($SymbolSourceFile{$symbol})) { - return $SymbolSourceFile{$symbol}; - } else { - return ""; - } -} - -############################################################################# -# Function : GetSymbolSourceLine -# Description : Get the file line where the symbol docs where taken from. -# Arguments : $symbol - the symbol name -############################################################################# - -sub GetSymbolSourceLine { - my ($symbol) = @_; - - if (defined($SourceSymbolSourceLine{$symbol})) { - return $SourceSymbolSourceLine{$symbol}; - } elsif (defined($SymbolSourceLine{$symbol})) { - return $SymbolSourceLine{$symbol}; - } else { - return 0; - } -} - +from __future__ import print_function + +import argparse +import sys +sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, mkdb + +if __name__ == '__main__': + parser = argparse.ArgumentParser() + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--module', required=True, + help='Name of the doc module being parsed') + parser.add_argument('--source-dir', action='append', dest='source_dir', default=[]) + parser.add_argument('--source-suffixes', dest='source_suffixes', default='') + parser.add_argument('--ignore-files', dest='ignore_files', default='') + parser.add_argument('--output-dir', dest='output_dir', default='') + parser.add_argument('--tmpl-dir', dest='tmpl_dir', help="DEPRECATED") + parser.add_argument('--main-sgml-file', dest='main_sgml_file', default='') + parser.add_argument('--expand-content-files', dest='expand_content_files', default='') + group = parser.add_mutually_exclusive_group() + group.add_argument('--sgml-mode', action='store_true', default=False, dest='sgml_mode') + group.add_argument('--xml-mode', action='store_true', default=False, dest='xml_mode') + parser.add_argument('--default-stability', dest='default_stability', + choices=['', 'Stable', 'Private', 'Unstable'], default='') + parser.add_argument('--default-includes', dest='default_includes', default='') + parser.add_argument('--output-format', default='xml') # MUST be 'xml', deprecate? + parser.add_argument('--name-space', dest='name_space', default='') + parser.add_argument('--outputallsymbols', default=False, action='store_true') + parser.add_argument('--outputsymbolswithoutsince', default=False, action='store_true') + + options = parser.parse_args() + + if options.output_format != "xml": + sys.exit('Invalid format "%s" passed to --output.format' % options.output_format) + + common.setup_logging() + + mkdb.Run(options) diff --git a/gtkdoc-mkhtml.in b/gtkdoc-mkhtml.in index 12aa9f2..0d0a15d 100644 --- a/gtkdoc-mkhtml.in +++ b/gtkdoc-mkhtml.in @@ -1,109 +1,51 @@ -#!/bin/sh +#!@PYTHON@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Owen Taylor +# 2001-2005 Damon Chaplin +# 2009-2017 Stefan Sauer +# 2017 Jussi Pakkanen +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -usage() { -cat <&2 - exit 1 -fi - -module="$1" -shift -document="$1" -shift - -quiet="1" -if test $verbose = "1"; then - quiet="0" -fi - -if test $uninstalled = yes; then - # this does not work from buiddir!=srcdir - gtkdocdir=`dirname $0` - # traditional Bourne shells may not support -e here, use -f - if test ! -f $gtkdocdir/gtk-doc.xsl; then - # try to src dir (set from makefiles) too - if test -f $ABS_TOP_SRCDIR/gtk-doc.xsl; then - gtkdocdir=$ABS_TOP_SRCDIR - fi - fi - styledir=$gtkdocdir/style - #echo "uninstalled, gtkdocdir=$gtkdocdir, cwd=$PWD" -else - # the first two are needed to resolve datadir - prefix=@prefix@ - datarootdir=@datarootdir@ - gtkdocdir=@datadir@/gtk-doc/data - styledir=$gtkdocdir -fi - -# we could do "$path_option $PWD " -# to avoid needing rewriting entities that are copied from the header -# into docs under xml -if test "X$searchpath" = "X"; then - path_arg= -else - path_arg="--path $searchpath" -fi - -# profiling -profile_args="" -if test "$GTKDOC_PROFILE" != ""; then - profile_args="--profile" -fi - -#echo @XSLTPROC@ $path_arg --nonet --xinclude \ -# --stringparam gtkdoc.bookname $module \ -# --stringparam gtkdoc.version "@VERSION@" \ -# "$@" $gtkdocdir/gtk-doc.xsl "$document" -@XSLTPROC@ 2>profile.txt $profile_args $path_arg --nonet --xinclude \ - --stringparam gtkdoc.bookname $module \ - --stringparam gtkdoc.version "@VERSION@" \ - --stringparam chunk.quietly $quiet \ - --stringparam chunker.output.quiet $quiet \ - "$@" $gtkdocdir/gtk-doc.xsl "$document" || exit $? - -# profiling -if test "$GTKDOC_PROFILE" != ""; then - cat profile.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o profile.png -else - rm profile.txt -fi - -# copy navigation images and stylesheets to html directory ... -cp -f $styledir/*.png $styledir/*.css ./ - - -echo "timestamp" > ../html.stamp - +import argparse +import sys +sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, mkhtml + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-mkhtml version %s - generate documentation in html format' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--verbose', default=False, action='store_true', + help='Print extra output while processing') + parser.add_argument('--path', default=[], action='append', + help='Extra source directories') + parser.add_argument('args', nargs='*', + help='MODULE DRIVER_FILE') + # TODO: only for testing, replace with env-var + parser.add_argument('--uninstalled', action='store_true', default=False, + help='???') + + options = parser.parse_args() + if len(options.args) < 2: + sys.exit('Too few arguments') + + common.setup_logging() + + sys.exit(mkhtml.run(options)) diff --git a/gtkdoc-mkman.in b/gtkdoc-mkman.in index b6e91a5..c5445cd 100644 --- a/gtkdoc-mkman.in +++ b/gtkdoc-mkman.in @@ -1,95 +1,49 @@ -#!/bin/sh +#!@PYTHON@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Owen Taylor +# 2001-2005 Damon Chaplin +# 2009-2017 Stefan Sauer +# 2017 Jussi Pakkanen +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -usage() { -cat <&2 - exit 1 -fi - -module=$1 -shift -document=$1 -shift - -quiet="1" -if test $verbose = "1"; then - quiet="0" -fi +import argparse +import sys +sys.path.append('@PYTHON_PACKAGE_DIR@') -if test $uninstalled = yes; then - # this does not work from buiddir!=srcdir - gtkdocdir=`dirname $0` - #echo "uninstalled, gtkdocdir=$gtkdocdir" -else - # the first two are needed to resolve datadir - prefix=@prefix@ - datarootdir=@datarootdir@ - gtkdocdir=@datadir@/gtk-doc/data -fi +from gtkdoc import common, config, mkman -if head -n 1 $document | grep " /dev/null; then - is_xml=true - path_option='--path' -else - is_xml=false - path_option='--directory' -fi +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-mkman version %s - generate documentation in man format' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--verbose', default=False, action='store_true', + help='Print extra output while processing') + parser.add_argument('--path', default=[], action='append', + help='Extra source directories') + parser.add_argument('args', nargs=2, + help='MODULE DRIVER_FILE') + # TODO: only for testing, replace with env-var + parser.add_argument('--uninstalled', action='store_true', default=False, + help='???') -# we could do "$path_option $PWD " -# to avoid needing rewriting entities that are copied from the header -# into docs under xml -if test "X$searchpath" = "X"; then - path_arg= -else - path_arg="$path_option $searchpath" -fi + options = parser.parse_args() -# would it make sens to create man pages only for certain refentries -# e.g. for tools -if $is_xml; then - # see http://bugzilla.gnome.org/show_bug.cgi?id=467488 - @XSLTPROC@ $path_arg --nonet --xinclude \ - --stringparam gtkdoc.bookname $module \ - --stringparam gtkdoc.version "@VERSION@" \ - --stringparam chunk.quietly $quiet \ - --stringparam chunker.output.quiet $quiet \ - http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl \ - $document || exit $? -else - for i in `cd sgml;ls *.sgml`; do - j=`echo $i | sed 's/.sgml/.man/'` - echo ": converting " $i $j - docbook-to-man sgml/$i > man/$j 2> man/$j.log - done -fi + common.setup_logging() + sys.exit(mkman.run(options)) diff --git a/gtkdoc-mkpdf.in b/gtkdoc-mkpdf.in old mode 100644 new mode 100755 index 908fda4..e8c0c03 --- a/gtkdoc-mkpdf.in +++ b/gtkdoc-mkpdf.in @@ -1,133 +1,48 @@ -#!/bin/sh +#!@PYTHON@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2009-2017 Stefan Sauer +# 2017 Jussi Pakkanen +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -usage() { -cat <&2 - exit 1 -fi - -module="$1" -shift -document="$1" -shift - -quiet="1" -if test $verbose = "1"; then - quiet="0" -fi - -if test $uninstalled = yes; then - # this does not work from buiddir!=srcdir - # we could try this - # MAKE_SCRDIR=$(abs_srcdir) MAKE_BUILDDIR=$(abs_builddir) gtkdoc-mkpdf ... - gtkdocdir=`dirname $0` - #echo "uninstalled, gtkdocdir=$gtkdocdir" -else - # the first two are needed to resolve datadir - prefix=@prefix@ - datarootdir=@datarootdir@ - gtkdocdir=@datadir@/gtk-doc/data -fi +import argparse +import sys +sys.path.append('@PYTHON_PACKAGE_DIR@') -if head -n 1 $document | grep " /dev/null; then - is_xml=true - path_option='--path' -else - is_xml=false - path_option='--directory' -fi +from gtkdoc import common, config, mkpdf -# we could do "$path_option $PWD " -# to avoid needing rewriting entities that are copied from the header -# into docs under xml -if test "X$searchpath" = "X"; then - path_arg= -else - path_arg="$path_option $searchpath" -fi +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-mkpdf version %s - generate documentation in pdf format' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--verbose', default=False, action='store_true', + help='Print extra output while processing.') + parser.add_argument('--path', default=[], action='append', + help='Extra source directories.') + parser.add_argument('--imgdir', default=[], action='append', + help='Extra image directories.') + parser.add_argument('--uninstalled', action='store_true', default=False, + help='???') + parser.add_argument('args', nargs=2, + help='MODULE DRIVER_FILE') -if $is_xml; then - if test -n "@DBLATEX@"; then - # extra options to consider - # -I FIG_PATH - # -V is useful for debugging - # -T db2latex : different style - # -d : keep transient files (for debugging) - # -P abc.def=$quiet : once the stylesheets have a quiet mode - # xsltproc is already called with --xinclude - # does not work: --xslt-opts "$path_arg --nonet $@" - dblatex_options="-o $module.pdf $imgdirs $document" - #echo "calling: @DBLATEX@ $dblatex_options" - if test $verbose = "0"; then - @DBLATEX@ 2>&1 --help | grep >/dev/null "\-\-quiet" - if test "$?" = "0"; then - dblatex_options="--quiet $dblatex_options"; - fi; - @DBLATEX@ 2>&1 >/dev/null $dblatex_options | grep -v 'programlisting or screen' - else - { @DBLATEX@ 2>&1 >&3 $dblatex_options | grep -v 'programlisting or screen' >&2; } 3>&1 - fi - else - if test -n "@FOP@"; then - @XSLTPROC@ $path_arg --nonet --xinclude \ - --stringparam gtkdoc.bookname $module \ - --stringparam gtkdoc.version "@VERSION@" \ - --stringparam chunk.quietly $quiet \ - --stringparam chunker.output.quiet $quiet \ - "$@" -o $module.fo $gtkdocdir/gtk-doc-fo.xsl "$document" || cleanexit $? - # fop dies too easily :( - # @FOP@ $module.fo $module.pdf - else - echo "dblatex or fop must be installed to use gtkdoc-mkpdf." >&2 - cleanexit 1 - fi - fi -else - # not very good output - # also for xxx-docs.sgml it will produce xxx-docs.pdf - docbook2pdf -e no-valid "$document" -fi + options = parser.parse_args() -echo "timestamp" > pdf.stamp -cleanexit 0 + common.setup_logging() + sys.exit(mkpdf.run(options)) diff --git a/gtkdoc-mktmpl.in b/gtkdoc-mktmpl.in deleted file mode 100755 index c64dfd3..0000000 --- a/gtkdoc-mktmpl.in +++ /dev/null @@ -1,1274 +0,0 @@ -#!@PERL@ -w -# -*- cperl -*- -# -# gtk-doc - GTK DocBook documentation generator. -# Copyright (C) 1998 Damon Chaplin -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -# - -############################################################################# -# Script : gtkdoc-mktmpl -# Description : This creates or updates the template files which contain the -# manually-edited documentation. (A 'template' is a simple text -# form which is filled in with the description of a function, -# macro, enum, or struct. For functions and macros it also -# contains fields for describing the parameters.) -# -# This script reads in the existing templates, found in -# tmpl/*.sgml, moves these files to tmpl/*.sgml.bak, and then -# recreates the .sgml files according to the structure given in -# the file $MODULE-sections.txt. -# -# Any new templates added, or new function parameters, are -# marked with 'FIXME' so you can do a grep to see which parts -# need updating. -# -# Any templates which are no longer used (i.e. they are remove -# from $MODULE-sections.txt) are placed in the file -# tmpl/$MODULE-unused.sgml. If they are included again later -# they are automatically copied back into position. -# If you are certain that these templates will never be used -# again you can delete them from tmpl/$MODULE-unused.sgml. -# -# Any parameters to functions which are no longer used are -# separated from the rest of the parameters with the line -# ''. It may be that the parameter -# name has just been changed, in which case you can copy the -# description to the parameter with the new name. You can delete -# the unused parameter descriptions when no longer needed. -############################################################################# - -use strict; -use Getopt::Long; - -push @INC, '@PACKAGE_DATA_DIR@'; -require "gtkdoc-common.pl"; - -# Options - -# name of documentation module -my $MODULE; -my $TMPL_DIR; -my $FLAG_CHANGES; -my $PRINT_VERSION; -my $PRINT_HELP; -my $ONLY_SECTION_TMPL; - -my %optctl = ('module' => \$MODULE, - 'flag-changes' => \$FLAG_CHANGES, - 'output-dir' => \$TMPL_DIR, - 'only-section-tmpl' => \$ONLY_SECTION_TMPL, - 'version' => \$PRINT_VERSION, - 'help' => \$PRINT_HELP); -GetOptions(\%optctl, "module=s", "flag-changes!", "output-dir:s", "only-section-tmpl!", "version", "help"); - -if ($PRINT_VERSION) { - print "@VERSION@\n"; - exit 0; -} - -if (!$MODULE) { - $PRINT_HELP = 1; -} - -if ($PRINT_HELP) { - print <$ROOT_DIR/tmpl.stamp") - || die "Can't create $ROOT_DIR/tmpl.stamp"; - print (TIMESTAMP "timestamp"); - close (TIMESTAMP); -} - -############################################################################# -# Function : ReadExistingTemplates -# Description : This reads in all the existing documentation, into the global -# variables %SymbolDocs, %SymbolTypes, and %SymbolParams (a -# hash of arrays). -# Arguments : none -############################################################################# - -sub ReadExistingTemplates { - %SymbolDocs = (); - %SymbolTypes = (); - %SymbolParams = (); - - # Read the unused docs first, so they get overridden by any real docs. - # (though this shouldn't happen often). - my $unused_doc = "$TMPL_DIR/$MODULE-unused.sgml"; - if (-e $unused_doc) { - &ReadTemplateFile ($unused_doc, 0); - } - - while (<$TMPL_DIR/*.sgml>) { -# print "Reading $_\n"; - if ($_ eq $unused_doc) { -# print "skipping $unused_doc\n"; - } else { - &ReadTemplateFile ($_, 0); - } - } -} - - -############################################################################# -# Function : UpdateTemplates -# Description : This collects the output for each section of the docs, and -# outputs each file when the end of the section is found. -# Arguments : $file - the file containing the sections of the docs. -############################################################################# - -sub UpdateTemplates { - my ($file) = @_; -# print "Reading: $file\n"; - - open (INPUT, $file) - || die "Can't open $file"; - - # Create the top output directory if it doesn't exist. - if (! -e $TMPL_DIR) { - mkdir ("$TMPL_DIR", 0777) - || die "Can't create directory: $TMPL_DIR"; - } - - my $filename = ""; - my $title = ""; - my $subsection = ""; - my $output; - my $changed = 0; - while () { - if (m/^#/) { - next; - - } elsif (m/^
/) { - $output = ""; - - } elsif (m/^/i) { - $subsection = $1; - next; - - } elsif (m/^(.*)<\/TITLE>/) { - $title = $1; -# print "Section: $title\n"; - - } elsif (m/^<FILE>(.*)<\/FILE>/) { - $filename = $1; - - } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) { - next; - - } elsif (m/^<\/SECTION>/) { - if ($title eq "") { - $title = $filename; - } -# print "End of section: $title\n"; - - $filename =~ s/\s/_/g; - $filename .= ".sgml"; - - if (&OutputTemplateFile ($filename, $title, \$output)) { - $changed = 1; - } - - $title = ""; - $subsection = ""; - - } elsif (m/^(\S+)/) { - my $symbol = $1; -# print " Symbol: $symbol\n"; - - my $declaration = $Declarations{$1}; - if (defined ($declaration)) { - # We don't want templates for standard macros/functions of - # GObjects or private declarations. - if ($subsection ne "Standard" && $subsection ne "Private") { - $output .= &OutputDeclaration ($DeclarationTypes {$symbol}, - $symbol, $declaration); - - $output .= &OutputSignalTemplates ($symbol); - $output .= &OutputArgTemplates ($symbol); - } - - # Note that the declaration has been output. - $DeclarationOutput{$symbol} = 1; - - if ($declaration eq '##conditional##') { -# print "Conditional $DeclarationTypes{$symbol}\n"; - } - - } else { - &LogWarning ($file, $., "No declaration found for: $1"); - } - } - } - close (INPUT); - - return $changed; -} - - -############################################################################# -# Function : CheckAllDeclarationsOutput -# Description : This steps through all the declarations that were loaded, and -# makes sure that each one has been output, by checking the -# corresponding flag in the %DeclarationOutput hash. It is -# intended to check that any new declarations in new versions -# of the module get added to the $MODULE-sections.txt file. -# Arguments : none -############################################################################# - -sub CheckAllDeclarationsOutput { - my $num_unused = 0; - - my $old_unused_file = "$ROOT_DIR/$MODULE-unused.txt"; - my $new_unused_file = "$ROOT_DIR/$MODULE-unused.new"; - - open (UNUSED, ">$new_unused_file") - || die "Can't open $new_unused_file"; - my ($symbol); - foreach $symbol (sort keys (%Declarations)) { - if (!defined ($DeclarationOutput{$symbol})) { - print (UNUSED "$symbol\n"); - $num_unused++; - } - } - close (UNUSED); - if ($num_unused != 0) { - &LogWarning ($old_unused_file, 1, "$num_unused unused declarations.". - "They should be added to $MODULE-sections.txt in the appropriate place."); - } - - return &UpdateFileIfChanged ($old_unused_file, $new_unused_file, 0); -} - - -############################################################################# -# Function : OutputDeclaration -# Description : This returns the template for one symbol & declaration. -# Note that it uses the global %SymbolDocs and %SymbolParams to -# lookup any existing documentation. -# Arguments : $type - the type of the symbol ('FUNCTION'/'MACRO' etc.) -# $symbol - the symbol name. -# $declaration - the declaration of the symbol. -############################################################################# - -sub OutputDeclaration { - my ($type, $symbol, $declaration) = @_; - my ($output) = ""; - - #print "Outputting $type: $symbol\n"; - - # See if symbol already has a description. - my ($symbol_desc) = $SymbolDocs{$symbol}; - my ($template_exists); - if (defined ($symbol_desc)) { - $template_exists = 1; - $symbol_desc =~ s/\s+$//; - } else { - $template_exists = 0; - $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>"; - } - - $output .= <<EOF; -<!-- ##### $type $symbol ##### --> -$symbol_desc - -EOF - - # For functions, function typedefs and macros, we output the arguments. - # For functions and function typedefs we also output the return value. - if ($type eq "FUNCTION" || $type eq "USER_FUNCTION") { - # Take out the return type - $declaration =~ s/<RETURNS>\s*(.*?)<\/RETURNS>\n//; - my $ret_type_decl = $1; - my $ret_type_modifier; - my $ret_type; - my $ret_type_pointer; - - if ($ret_type_decl =~ m/((const\s+|G_CONST_RETURN\s+|unsigned\s+|signed\s+|long\s+|short\s+|struct\s+|enum\s+)*)(\w+)\s*(\**\s*(const|G_CONST_RETURN)?\s*\**\s*(restrict)?\s*)/) { - $ret_type_modifier = defined($1) ? $1 : ""; - $ret_type = $3; - $ret_type_pointer = $4; - } else { - $ret_type = "void"; - } - - my @fields = ParseFunctionDeclaration($declaration); - - for (my $i = 0; $i <= $#fields; $i += 2) { - my $field_name = $fields[$i]; - $output .= &OutputParam ($symbol, $field_name, $template_exists, 1, ""); - } - - if ($ret_type ne "void" || $ret_type_modifier || $ret_type_pointer) { - $output .= &OutputParam ($symbol, "Returns", $template_exists, 1, ""); - } - - $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, ""); - $output .= &OutputParam ($symbol, "Since", $template_exists, 0, ""); - $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, ""); - $output .= &OutputOldParams ($symbol); - $output .= "\n"; - } - - if ($type eq "MACRO") { - my @fields = ParseMacroDeclaration($declaration); - - for (my $i = 0; $i <= $#fields; $i +=2) { - my $field_name = $fields[$i]; - - $output .= &OutputParam ($symbol, $field_name, $template_exists, - 1, ""); - } - $output .= &OutputParam ($symbol, "Returns", $template_exists, 0, ""); - $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, ""); - $output .= &OutputParam ($symbol, "Since", $template_exists, 0, ""); - $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, ""); - $output .= &OutputOldParams ($symbol); - $output .= "\n"; - } - - if ($type eq "STRUCT") { - my $is_object_struct = CheckIsObject ($symbol); - my @fields = ParseStructDeclaration($declaration, $is_object_struct, 1); - - for (my $i = 0; $i <= $#fields; $i += 2) { - my $field_name = $fields[$i]; - $output .= &OutputParam ($symbol, $field_name, $template_exists, 1, ""); - } - $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, ""); - $output .= &OutputParam ($symbol, "Since", $template_exists, 0, ""); - $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, ""); - } - - if ($type eq "ENUM") { - my @members = ParseEnumDeclaration($declaration); - - for my $member (@members) { - $output .= &OutputParam ($symbol, $member, $template_exists, 1, ""); - } - $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, ""); - $output .= &OutputParam ($symbol, "Since", $template_exists, 0, ""); - $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, ""); - } - - $output .= "\n"; - - # Remove the used docs from the hashes. - if ($template_exists) { - delete $SymbolDocs{$symbol}; - delete $SymbolParams{$symbol}; - } - - return $output; -} - - -############################################################################# -# Function : OutputParam -# Description : This outputs the part of a template for one parameter. -# It first checks if the parameter is already described, and if -# so it uses that description, and clears it so it isn't output -# as an old param. -# Arguments : $symbol - the symbol (function or macro) name. -# $param_to_output - the parameter to add. -# $template_exists - TRUE if the template already existed in -# template files. If it did, then we will flag any changes -# with 'FIXME'. -# $force_output - TRUE if the parameter should be output even -# if it didn't already exist in the template. (The return -# values of macros are added manually if required, and so we -# never add it here - we only copy it if it already exists.) -# $default_description - the default description of the -# parameter to be used if it doesn't already exist. (Signal -# handlers have a few common parameters.) -############################################################################# - -sub OutputParam { - my ($symbol, $param_to_output, $template_exists, - $force_output, $default_description) = @_; - my ($j); - - my ($params) = $SymbolParams{$symbol}; - if (defined ($params)) { - for ($j = 0; $j <= $#$params; $j += 2) { - my $param_name = $$params[$j]; - my $param_desc = $$params[$j + 1]; - - if ($param_name eq $param_to_output) { - $param_desc =~ s/\s+$//; - $$params[$j] = ""; - $$params[$j + 1] = ""; - return "\@$param_name: $param_desc\n"; - } - } - } - - # If the template was already in a file, flag the new parameter. - # If not, the template itself will be flagged, so we don't need to flag - # all the new parameters as well. - if ($force_output) { - if ($default_description ne "") { - $default_description =~ s/\s+$//; - return "\@$param_to_output: $default_description\n"; - } else { - if ($template_exists) { - return "\@$param_to_output: $CHANGES_FLAG\n"; - } else { - return "\@$param_to_output: \n"; - } - } - } - return ""; -} - - -############################################################################# -# Function : OutputOldParams -# Description : This returns all the existing documentation for parameters of -# the given function/macro/signal symbol which are unused, with -# a comment before them. -# Arguments : $symbol - the symbol (function/macro/signal) name. -############################################################################# - -sub OutputOldParams { - my ($symbol) = @_; - my $output = ""; - - my ($params) = $SymbolParams{$symbol}; - if (defined ($params)) { - my $j; - for ($j = 0; $j <= $#$params; $j += 2) { - my $param_name = $$params[$j]; - my $param_desc = $$params[$j + 1]; - - if ($param_name ne "") { - $param_desc =~ s/\s+$//; - - # There's no point keeping it if it has no docs. - if ($param_desc ne "") { - $output .= "\@$param_name: $param_desc\n"; - } - } - } - } - if ($output) { - $output = "<!-- # Unused Parameters # -->\n" . $output; - } - return $output; -} - - -############################################################################# -# Function : OutputTemplateFile -# Description : This outputs one template file. -# Arguments : $file - the basename of the file to output. -# $title - the title from the $MODULE-sections.txt file. This -# will be overridden by any title given in the template file. -# $output - reference to the templates to output. -############################################################################# - -sub OutputTemplateFile { - my ($file, $title, $output) = @_; - - my ($short_desc, $long_desc, $see_also, $stability, $image); - - if (defined ($SymbolDocs{"$TMPL_DIR/$file:Title"})) { - $title = $SymbolDocs{"$TMPL_DIR/$file:Title"}; - delete $SymbolDocs{"$TMPL_DIR/$file:Title"}; - } - if (defined ($SymbolDocs{"$TMPL_DIR/$file:Short_Description"})) { - $short_desc = $SymbolDocs{"$TMPL_DIR/$file:Short_Description"}; - delete $SymbolDocs{"$TMPL_DIR/$file:Short_Description"}; - } else { - $short_desc = ""; - } - if (defined ($SymbolDocs{"$TMPL_DIR/$file:Long_Description"})) { - $long_desc = $SymbolDocs{"$TMPL_DIR/$file:Long_Description"}; - delete $SymbolDocs{"$TMPL_DIR/$file:Long_Description"}; - } else { - $long_desc = "<para>\n\n</para>\n"; - } - if (defined ($SymbolDocs{"$TMPL_DIR/$file:See_Also"})) { - $see_also = $SymbolDocs{"$TMPL_DIR/$file:See_Also"}; - delete $SymbolDocs{"$TMPL_DIR/$file:See_Also"}; - } else { - $see_also = "<para>\n\n</para>\n"; - } - if (defined ($SymbolDocs{"$TMPL_DIR/$file:Stability_Level"})) { - $stability = $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"}; - delete $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"}; - } else { - $stability = ""; - } - if (defined ($SymbolDocs{"$TMPL_DIR/$file:Image"})) { - $image = $SymbolDocs{"$TMPL_DIR/$file:Image"}; - delete $SymbolDocs{"$TMPL_DIR/$file:Image"}; - } else { - $image = ""; - } - - - my $old_tmpl_file = "$TMPL_DIR/$file"; - my $new_tmpl_file = "$TMPL_DIR/$file.new"; - - open (OUTPUT, ">$new_tmpl_file") - || die "Can't create $new_tmpl_file"; - - print (OUTPUT <<EOF); -<!-- ##### SECTION Title ##### --> -$title - -<!-- ##### SECTION Short_Description ##### --> -$short_desc - -<!-- ##### SECTION Long_Description ##### --> -$long_desc - -<!-- ##### SECTION See_Also ##### --> -$see_also - -<!-- ##### SECTION Stability_Level ##### --> -$stability - -<!-- ##### SECTION Image ##### --> -$image - -EOF - - print (OUTPUT $$output) unless $ONLY_SECTION_TMPL; - close (OUTPUT); - - return &UpdateFileIfChanged ($old_tmpl_file, $new_tmpl_file, 1); -} - - -############################################################################# -# Function : OutputSignalTemplates -# Description : Outputs templates for signal handlers. -# Arguments : $title - the title from the $MODULE-sections.txt file. If the -# file is describing a GtkObject subclass, the title should -# be the name of the class, e.g. 'GtkButton'. -############################################################################# - -sub OutputSignalTemplates { - my ($title) = @_; - - my $output = ""; - my ($i, $template_exists); - for ($i = 0; $i <= $#SignalObjects; $i++) { - if ($SignalObjects[$i] eq $title) { -# print "Found signal: $SignalObjects[$i]\n"; - my ($symbol) = "$SignalObjects[$i]::$SignalNames[$i]"; - - # See if symbol already has a description. - my ($symbol_desc) = $SymbolDocs{$symbol}; - if (defined ($symbol_desc)) { - $template_exists = 1; - $symbol_desc =~ s/\s+$//; - delete $SymbolDocs{$symbol}; - } else { - $template_exists = 0; - $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>"; - } - - $output .= <<EOF; -<!-- ##### SIGNAL $symbol ##### --> -$symbol_desc - -EOF - my $sourceparams = $SymbolParams{$symbol}; - my @params = split ("[,\n]", $SignalPrototypes[$i]); - my ($j, $name); - for ($j = 0; $j <= $#params; $j++) { - my $param = $params[$j]; - $param =~ s/^\s+//; - $param =~ s/\s*$//; - if ($param =~ m/^\s*$/) { next; } - if ($param =~ m/^void$/) { next; } - - if ($param =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)?\s*$/) { - if (defined ($sourceparams)) { - $name = $$sourceparams[2 * $j]; - } else { - $name = $3; - } - - if (!defined ($name)) { - $name = "Param" . ($j + 1); - } - - if ($j == 0) { - $output .= &OutputParam ($symbol, $name, - $template_exists, 1, - "the object which received the signal."); - } else { - $output .= &OutputParam ($symbol, $name, - $template_exists, 1, ""); - } - } - } - - if ($SignalReturns[$i] ne "void") { - $output .= &OutputParam ($symbol, "Returns", $template_exists, - 1, ""); - } - $output .= &OutputOldParams ($symbol); - $output .= "\n"; - } - } - return $output; -} - - -############################################################################# -# Function : OutputArgTemplates -# Description : Outputs templates for Args. -# Arguments : $title - the title from the $MODULE-sections.txt file. If the -# file is describing a GtkObject subclass, the title should -# be the name of the class, e.g. 'GtkButton'. -############################################################################# - -sub OutputArgTemplates { - my ($title) = @_; - - my $output = ""; - my $i; - for ($i = 0; $i <= $#ArgObjects; $i++) { - if ($ArgObjects[$i] eq $title) { -# print "Found arg: $ArgObjects[$i]\n"; - # I've only used one colon so we don't clash with signals. - my ($symbol) = "$ArgObjects[$i]:$ArgNames[$i]"; - - # See if symbol already has a description. - my ($symbol_desc) = $SymbolDocs{$symbol}; - if (defined ($symbol_desc)) { - delete $SymbolDocs{$symbol}; - $symbol_desc =~ s/\s+$//; - } else { - $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>"; - } - - $output .= <<EOF; -<!-- ##### ARG $symbol ##### --> -$symbol_desc - -EOF - } - } - return $output; -} - - -############################################################################# -# Function : OutputUnusedTemplates -# Description : This saves any unused documentation into $MODULE-unused.sgml. -# Arguments : none -############################################################################# - -sub OutputUnusedTemplates { - my ($old_unused_file) = "$TMPL_DIR/$MODULE-unused.sgml"; - my ($new_unused_file) = "$TMPL_DIR/$MODULE-unused.new"; - - open (UNUSED, ">$new_unused_file") - || die "Can't open file: $new_unused_file"; - - my $output = ""; - my ($symbol, $symbol_desc); - for $symbol (sort keys %SymbolDocs) { - $symbol_desc = $SymbolDocs{$symbol}; - -# print "Unused: $symbol\n"; - - my $type = $SymbolTypes{$symbol}; - if (!defined ($type)) { - $type = "UNKNOWN"; - &LogWarning ($SymbolSourceFile{$symbol},$SymbolSourceLine{$symbol}, "Unused symbol $symbol has unknown type."); - } - - $output .= <<EOF; -<!-- ##### $type $symbol ##### --> -$symbol_desc - -EOF - - my ($params) = $SymbolParams{$symbol}; - if (defined ($params)) { - my $j; - for ($j = 0; $j <= $#$params; $j += 2) { - my $param_name = $$params[$j]; - my $param_desc = $$params[$j + 1]; - $param_desc =~ s/\s+$//; - $output .= "\@$param_name: $param_desc\n"; - } - } - $output .= "\n"; - } - - print UNUSED $output; - close (UNUSED); - - &UpdateFileIfChanged ($old_unused_file, $new_unused_file, 1); -} - - -############################################################################# -# LIBRARY FUNCTIONS - These functions are used in both gtkdoc-mkdb and -# gtkdoc-mktmpl and should eventually be moved to a -# separate library. -############################################################################# - -############################################################################# -# Function : ReadDeclarationsFile -# Description : This reads in a file containing the function/macro/enum etc. -# declarations. -# -# Note that in some cases there are several declarations with -# the same name, e.g. for conditional macros. In this case we -# set a flag in the %DeclarationConditional hash so the -# declaration is not shown in the docs. -# -# If a macro and a function have the same name, e.g. for -# gtk_object_ref, the function declaration takes precedence. -# -# Some opaque structs are just declared with 'typedef struct -# _name name;' in which case the declaration may be empty. -# The structure may have been found later in the header, so -# that overrides the empty declaration. -# -# Arguments : $file - the declarations file to read -# $override - if declarations in this file should override -# any current declaration. -############################################################################# - -sub ReadDeclarationsFile { - my ($file, $override) = @_; - - if ($override == 0) { - %Declarations = (); - %DeclarationTypes = (); - %DeclarationConditional = (); - %DeclarationOutput = (); - } - - open (INPUT, $file) - || die "Can't open $file"; - my $declaration_type = ""; - my $declaration_name; - my $declaration; - while (<INPUT>) { - if (!$declaration_type) { - if (m/^<([^>]+)>/) { - $declaration_type = $1; - $declaration_name = ""; -# print "Found declaration: $declaration_type\n"; - $declaration = ""; - } - } else { - if (m%^<NAME>(.*)</NAME>%) { - $declaration_name = $1; - } elsif (m%<DEPRECATED/>%) { - # do nothing, just skip the line; we handle this - # in mkdb - } elsif (m%^</$declaration_type>%) { -# print "Found end of declaration: $declaration_name\n"; - # Check that the declaration has a name - if ($declaration_name eq "") { - print "ERROR: $declaration_type has no name $file:$.\n"; - } - - # Check if the symbol is already defined. - if (defined ($Declarations{$declaration_name}) - && $override == 0) { - # Function declarations take precedence. - if ($DeclarationTypes{$declaration_name} eq 'FUNCTION') { - # Ignore it. - } elsif ($declaration_type eq 'FUNCTION') { - $Declarations{$declaration_name} = $declaration; - $DeclarationTypes{$declaration_name} = $declaration_type; - } elsif ($DeclarationTypes{$declaration_name} - eq $declaration_type) { - # If the existing declaration is empty, or is just a - # forward declaration of a struct, override it. - if ($declaration_type eq 'STRUCT') { - if ($Declarations{$declaration_name} =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) { - $Declarations{$declaration_name} = $declaration; - } elsif ($declaration =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) { - # Ignore an empty or forward declaration. - } else { - &LogWarning ($file, $., "Structure $declaration_name has multiple definitions."); - } - - } else { - # set flag in %DeclarationConditional hash for - # multiply defined macros/typedefs. - $DeclarationConditional{$declaration_name} = 1; - } - } else { - &LogWarning ($file, $., "$declaration_name has multiple definitions."); - } - } else { - $Declarations{$declaration_name} = $declaration; - $DeclarationTypes{$declaration_name} = $declaration_type; - } - $declaration_type = ""; - } else { - $declaration .= $_; - } - } - } - close (INPUT); -} - - -############################################################################# -# Function : ReadSignalsFile -# Description : This reads in an existing file which contains information on -# all GObject signals. It creates the arrays @SignalNames and -# @SignalPrototypes containing info on the signals. The first -# line of the SignalPrototype is the return type of the signal -# handler. The remaining lines are the parameters passed to it. -# The last parameter, "gpointer user_data" is always the same -# so is not included. -# Arguments : $file - the file containing the signal handler prototype -# information. -############################################################################# - -sub ReadSignalsFile { - my ($file) = @_; - - my $in_signal = 0; - my $signal_object; - my $signal_name; - my $signal_returns; - my $signal_flags; - my $signal_prototype; - - # Reset the signal info. - @SignalObjects = (); - @SignalNames = (); - @SignalReturns = (); - @SignalFlags = (); - @SignalPrototypes = (); - - if (! -f $file) { - return; - } - if (!open (INPUT, $file)) { - warn "Can't open $file - skipping signals\n"; - return; - } - while (<INPUT>) { - if (!$in_signal) { - if (m/^<SIGNAL>/) { - $in_signal = 1; - $signal_object = ""; - $signal_name = ""; - $signal_returns = ""; - $signal_prototype = ""; - } - } else { - if (m/^<NAME>(.*)<\/NAME>/) { - $signal_name = $1; - if ($signal_name =~ m/^(.*)::(.*)$/) { - $signal_object = $1; - ($signal_name = $2) =~ s/_/-/g; -# print "Found signal: $signal_name\n"; - } else { - print "Invalid signal name: $signal_name\n"; - } - } elsif (m/^<RETURNS>(.*)<\/RETURNS>/) { - $signal_returns = $1; - } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) { - $signal_flags = $1; - } elsif (m%^</SIGNAL>%) { -# print "Found end of signal: ${signal_object}::${signal_name}\nReturns: ${signal_returns}\n${signal_prototype}"; - push (@SignalObjects, $signal_object); - push (@SignalNames, $signal_name); - push (@SignalReturns, $signal_returns); - push (@SignalFlags, $signal_flags); - push (@SignalPrototypes, $signal_prototype); - $in_signal = 0; - } else { - $signal_prototype .= $_; - } - } - } - close (INPUT); -} - - -############################################################################# -# Function : ReadTemplateFile -# Description : This reads in the manually-edited documentation file -# corresponding to the file currently being created, so we can -# insert the documentation at the appropriate places. -# It outputs %SymbolTypes, %SymbolDocs and %SymbolParams, which -# is a hash of arrays. -# NOTE: This function is duplicated in gtkdoc-mkdb (but -# slightly different). -# Arguments : $docsfile - the template file to read in. -# $skip_unused_params - 1 if the unused parameters should be -# skipped. -############################################################################# - -sub ReadTemplateFile { - my ($docsfile, $skip_unused_params) = @_; - -# print "Reading $docsfile\n"; - if (! -f $docsfile) { - print "File doesn't exist: $docsfile\n"; - return 0; - } - - my $CurrentType = ""; # Type of symbol being read. - my $CurrentSymbol = ""; # Name of symbol being read. - my $SymbolDoc = ""; # Description of symbol being read. - my @Params; # Parameter names and descriptions of current - # function/macro/function typedef. - my $CurrentParam = -1; # Index of parameter currently being read. - # Note that the param array contains pairs - # of param name & description. - my $InUnusedParameters = 0; # True if we are reading in the unused params. - - open (DOCS, $docsfile) - || die "Can't open file $docsfile: $!"; - while (<DOCS>) { - if (m/^<!-- ##### ([A-Z_]+) (\S+) ##### -->/) { - my $type = $1; - my $symbol = $2; - if ($symbol eq "Title" - || $symbol eq "Short_Description" - || $symbol eq "Long_Description" - || $symbol eq "See_Also" - || $symbol eq "Stability_Level" - || $symbol eq "Image") { - $symbol = $docsfile . ":" . $symbol; - } - - #print "Found symbol: $symbol\n"; - # Remember file and line for the symbol - $SymbolSourceFile{$symbol} = $docsfile; - $SymbolSourceLine{$symbol} = $.; - - # Canonicalize signal and argument names to have -, not _ - if ($type eq "ARG" || $type eq "SIGNAL") { - $symbol =~ s/_/-/g; - } - - # Store previous symbol, but remove any trailing blank lines. - if ($CurrentSymbol ne "") { - $SymbolDoc =~ s/\s+$//; - $SymbolTypes{$CurrentSymbol} = $CurrentType; - $SymbolDocs{$CurrentSymbol} = $SymbolDoc; - - if ($CurrentParam >= 0) { - $SymbolParams{$CurrentSymbol} = [ @Params ]; - } else { - # Delete any existing params in case we are overriding a - # previously read template. - delete $SymbolParams{$CurrentSymbol}; - } - } - $CurrentType = $type; - $CurrentSymbol = $symbol; - $CurrentParam = -1; - $InUnusedParameters = 0; - $SymbolDoc = ""; - @Params = (); - - } elsif (m/^<!-- # Unused Parameters # -->/) { - $InUnusedParameters = 1; - next; - - } else { - # Workaround for an old bug that left a mess in the templates. - # This happened with macros with args spread over several lines. - if (m/^\@\\$/) { - # Skip the next line. - $_ = <DOCS>; - next; - } - - # Workaround for an old bug that left '@:' at start of lines. - if (m/^\@:$/) { - next; - } - - - # Check if param found. Need to handle "..." and "format...". - if (s/^\@([\w\.]+):\040?//) { - my $param_name = $1; - # Allow variations of 'Returns' - if ($param_name =~ m/^[Rr]eturns?$/) { - $param_name = "Returns"; - } -# print "Found param: $param_name\n"; - push (@Params, $param_name); - push (@Params, $_); - $CurrentParam += 2; - next; - } - - # When outputting the DocBook we skip unused parameters. - if (!$InUnusedParameters || !$skip_unused_params) { - if ($CurrentParam >= 0) { - $Params[$CurrentParam] .= $_; - } else { - $SymbolDoc .= $_; - } - } - } - } - - # Remember to finish the current symbol doccs. - if ($CurrentSymbol ne "") { - - $SymbolDoc =~ s/\s+$//; - $SymbolTypes{$CurrentSymbol} = $CurrentType; - $SymbolDocs{$CurrentSymbol} = $SymbolDoc; - - if ($CurrentParam >= 0) { - $SymbolParams{$CurrentSymbol} = [ @Params ]; - } else { - delete $SymbolParams{$CurrentSymbol}; - } - } - - close (DOCS); - return 1; -} - - -############################################################################# -# Function : ReadObjectHierarchy -# Description : This reads in the $MODULE-hierarchy.txt file containing all -# the GtkObject subclasses described in this module (and their -# ancestors). -# It places them in the @Objects array, and places their level -# in the widget hierarchy in the @ObjectLevels array, at the -# same index. GtkObject, the root object, has a level of 1. -# -# FIXME: the version in gtkdoc-mkdb also generates tree_index.sgml -# as it goes along, this should be split out into a separate -# function. -# -# Arguments : none -############################################################################# - -sub ReadObjectHierarchy { - @Objects = (); - @ObjectLevels = (); - - if (! -f $OBJECT_TREE_FILE) { - return; - } - if (!open (INPUT, $OBJECT_TREE_FILE)) { - warn "Can't open $OBJECT_TREE_FILE - skipping object tree\n"; - return; - } - while (<INPUT>) { - if (m/\S+/) { - my $object = $&; - my $level = (length($`)) / 2 + 1; -# print ("Level: $level Object: $object\n"); - - push (@Objects, $object); - push (@ObjectLevels, $level); - } - } - - close (INPUT); -} - - -############################################################################# -# Function : ReadArgsFile -# Description : This reads in an existing file which contains information on -# all GObject args. It creates the arrays @ArgObjects, @ArgNames, -# @ArgTypes and @ArgFlags containing info on the args. -# Arguments : $file - the file containing the arg information. -############################################################################# - -sub ReadArgsFile { - my ($file) = @_; - - my $in_arg = 0; - my $arg_object; - my $arg_name; - my $arg_type; - my $arg_flags; - - # Reset the signal info. - @ArgObjects = (); - @ArgNames = (); - @ArgTypes = (); - @ArgFlags = (); - - if (! -f $file) { - return; - } - if (!open (INPUT, $file)) { - warn "Can't open $file - skipping args\n"; - return; - } - while (<INPUT>) { - if (!$in_arg) { - if (m/^<ARG>/) { - $in_arg = 1; - $arg_object = ""; - $arg_name = ""; - $arg_type = ""; - $arg_flags = ""; - } - } else { - if (m/^<NAME>(.*)<\/NAME>/) { - $arg_name = $1; - if ($arg_name =~ m/^(.*)::(.*)$/) { - $arg_object = $1; - ($arg_name = $2) =~ s/_/-/g; -# print "Found arg: $arg_name\n"; - } else { - print "Invalid arg name: $arg_name\n"; - } - } elsif (m/^<TYPE>(.*)<\/TYPE>/) { - $arg_type = $1; - } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) { - $arg_flags = $1; - } elsif (m%^</ARG>%) { -# print "Found end of arg: ${arg_object}::${arg_name}\n${arg_type} : ${arg_flags}\n"; - push (@ArgObjects, $arg_object); - push (@ArgNames, $arg_name); - push (@ArgTypes, $arg_type); - push (@ArgFlags, $arg_flags); - $in_arg = 0; - } - } - } - close (INPUT); -} - - -############################################################################# -# Function : CheckIsObject -# Description : Returns 1 if the given name is a GObject or a subclass. -# It uses the global @Objects array. -# Note that the @Objects array only contains classes in the -# current module and their ancestors - not all GObject classes. -# Arguments : $name - the name to check. -############################################################################# - -sub CheckIsObject { - my ($name) = @_; - - my $object; - foreach $object (@Objects) { - if ($object eq $name) { - return 1; - } - } - return 0; -} - diff --git a/gtkdoc-rebase.in b/gtkdoc-rebase.in old mode 100644 new mode 100755 index 375482d..17a71c2 --- a/gtkdoc-rebase.in +++ b/gtkdoc-rebase.in @@ -1,9 +1,10 @@ -#!@PERL@ -w -# -*- cperl -*- +#!@PYTHON@ +# -*- python -*- # # gtk-doc - GTK DocBook documentation generator. # Copyright (C) 1998 Damon Chaplin -# Copyright (C) 2007 David Necas (Yeti) +# 2007 David Necas (Yeti) +# 2007-2016 Stefan Sauer # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -20,351 +21,36 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -############################################################################# -# Script : gtkdoc-rebase -# Description : Rebases URI references in installed HTML documentation. -############################################################################# - -use strict; -use bytes; -use Getopt::Long qw(:config gnu_getopt); -use Cwd qw(realpath); - -# Options - -my $HTML_DIR; -my @OTHER_DIRS; -my $DEST_DIR; -my $PRINT_VERSION; -my $PRINT_HELP; -my $AGGRESSIVE; -my $ONLINE; -my $RELATIVE; -my $VERBOSE; - -# Maps. -# These two point to the last seen URI of given type for a package: -# OnlineMap: package => on-line URI -# LocalMap: package => local URI -# This maps all seen URIs of a package to fix broken links in the process: -# RevMap: URI => package -my (%OnlineMap, %LocalMap, %RevMap); -# Remember what mangling we did. -my %Mapped; - - -run() unless caller; # Run program unless loaded as a module - - -sub run { - my %optctl = ('html-dir' => \$HTML_DIR, - 'other-dir' => \@OTHER_DIRS, - 'dest-dir' => \$DEST_DIR, - 'online' => \$ONLINE, - 'relative' => \$RELATIVE, - 'aggressive' => \$AGGRESSIVE, - 'verbose' => \$VERBOSE, - 'version' => \$PRINT_VERSION, - 'help' => \$PRINT_HELP); - GetOptions(\%optctl, 'html-dir=s', 'other-dir=s@', 'dest-dir:s', - 'online', 'relative', 'aggressive', 'verbose', - 'version', 'help'); - - if ($PRINT_VERSION) { - print "@VERSION@\n"; - exit 0; - } - - if ($PRINT_HELP) { - print <<EOF; -gtkdoc-rebase version @VERSION@ - rewrite the base url of html files - ---html-dir=HTML_DIR The directory which contains the installed HTML ---other-dir=OTHER_DIR Directories to recursively scan for indices (index.sgml) - May be used more than once for multiple directories ---online Prefer cross-references to online documents ---relative Prefer relative cross-references ---aggressive Rebase links to all files that are under a directory - matching a package name. ---dest-dir=ROOT_DIR Staging area virtual root, this prefix will be removed - from HTML_DIR fore relative link calculation. ---verbose Be verbose ---version Print the version of this program ---help Print this help -EOF - exit 0; - } - - if (!$HTML_DIR) { - die "No HTML directory (--html-dir) given.\n"; - } - - my $dir; - - # We scan the directory containing GLib and any directories in GNOME2_PATH - # first, but these will be overriden by any later scans. - if (defined ($ENV{"GNOME2_PATH"})) { - foreach $dir (split(/:/, $ENV{"GNOME2_PATH"})) { - $dir = $dir . "/share/gtk-doc/html"; - if ($dir && -d $dir) { - print "Prepending GNOME2_PATH directory: $dir\n" if $VERBOSE; - unshift @OTHER_DIRS, $dir; - } - } - } - - $dir = `pkg-config --variable=prefix glib-2.0`; - $dir =~ s/^\s*(\S*)\s*$/$1/; - $dir = $dir . "/share/gtk-doc/html"; - print "Prepending GLib directory $dir\n" if $VERBOSE; - unshift @OTHER_DIRS, $dir; - - # Check all other dirs, but skip already scanned dirs ord subdirs of those - if ($DEST_DIR) { - $DEST_DIR =~ s#/?$#/#; - } - $HTML_DIR =~ s#/?$#/#; - - foreach $dir (@OTHER_DIRS) { - &ScanDirectory($dir, $HTML_DIR); - } - - if ($RELATIVE) { - &RelativizeLocalMap($HTML_DIR); - } - - &RebaseReferences($HTML_DIR); - &PrintWhatWeHaveDone(); -} - - -sub ScanDirectory { - my ($dir, $self) = @_; - # This array holds any subdirectories found. - my (@subdirs) = (); - - print "Scanning documentation directory $dir\n" if $VERBOSE; - - if ("$dir/" eq $self) { - print "Excluding self\n" if $VERBOSE; - return; - } - if (not opendir(HTMLDIR, $dir)) { - print "Cannot open $dir: $!\n"; - return; - } - - my $file; - my $onlinedir; - my $have_index = 0; - foreach $file (readdir(HTMLDIR)) { - if ($file eq '.' or $file eq '..') { - next; - } - elsif (-d "$dir/$file") { - push @subdirs, $file; - next; - } - if ($file =~ m/\.devhelp2$/) { - print "Reading index from $file\n" if $VERBOSE; - my $o = &ReadDevhelp($dir, $file); - # Prefer this location over possibly stale index.sgml - if ($o) { - $onlinedir = $o; - } - $have_index = 1; - } - if (!$onlinedir and ($file eq "index.sgml")) { - print "Reading index from index.sgml\n" if $VERBOSE; - $onlinedir = &ReadIndex($dir, $file); - $have_index = 1; - } - elsif ($file eq "index.sgml.gz") { - # debian/ubuntu started to compress this as index.sgml.gz :/ - print <<EOF; -Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138 . For now run: -gunzip $dir/$file -EOF - } - elsif ($file =~ m/\.devhelp2.gz$/) { - # debian/ubuntu started to compress this as *devhelp2.gz :/ - print <<EOF; -Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/1466210 . For now run: -gunzip $dir/$file -EOF - } - # we could consider supporting: use IO::Zlib; - } - closedir (HTMLDIR); - if ($have_index) { - &AddMap($dir, $onlinedir); - } - - # Now recursively scan the subdirectories. - my $d; - foreach my $subdir (@subdirs) { - &ScanDirectory("$dir/$subdir", $self); - } -} - - -sub ReadDevhelp { - my ($dir, $file) = @_; - my $onlinedir; - - open(INDEXFILE, "$dir/$file") || die "Can't open $dir/$file: $!"; - while (<INDEXFILE>) { - # online must come before chapter/functions - last if m/<(chapters|functions)/; - if (m/ online="([^"]*)"/) { - $onlinedir = $1; - # Remove trailing non-directory component. - $onlinedir =~ s#(.*/).*#$1#; - } - } - close (INDEXFILE); - return $onlinedir; -} - - -sub ReadIndex { - my ($dir, $file) = @_; - my $onlinedir; - - open(INDEXFILE, "$dir/$file") || die "Can't open $dir/$file: $!"; - while (<INDEXFILE>) { - # ONLINE must come before any ANCHORs - last if m/^<ANCHOR/; - if (m/^<ONLINE\s+href\s*=\s*"([^"]+)"\s*>/) { - $onlinedir = $1; - # Remove trailing non-directory component. - $onlinedir =~ s#(.*/).*#$1#; - } - } - close (INDEXFILE); - return $onlinedir; -} - - -sub AddMap { - my ($dir, $onlinedir) = @_; - my $package; - - $dir =~ s#/?$#/#; - ($package = $dir) =~ s#.*/([^/]+)/#$1#; - if ($DEST_DIR and substr($dir, 0, length $DEST_DIR) eq $DEST_DIR) { - $dir = substr($dir, -1 + length $DEST_DIR); - } - if ($onlinedir) { - print "On-line location of $package: $onlinedir\n" if $VERBOSE; - $OnlineMap{ $package } = $onlinedir; - $RevMap{ $onlinedir } = $package; - } else { - print "No On-line location for $package found\n" if $VERBOSE; - } - print "Local location of $package: $dir\n" if $VERBOSE; - $LocalMap{ $package } = $dir; - $RevMap{ $dir } = $package; -} - - -sub RelativizeLocalMap { - my ($self) = @_; - my $prefix; - my $dir; - - $self = realpath $self; - $self =~ s#/?$#/#; - ($prefix = $self) =~ s#[^/]+/$##; - foreach my $package (keys %LocalMap) { - $dir = $LocalMap{ $package }; - if (substr($dir, 0, length $prefix) eq $prefix) { - $dir = "../" . substr($dir, length $prefix); - $LocalMap{ $package } = $dir; - print "Relativizing local location of $package to $dir\n" if $VERBOSE; - } - } -} - - -sub RebaseReferences { - my ($dir) = @_; - - opendir(HTMLDIR, $dir) || die "Can't open HTML directory $dir: $!"; - foreach my $file (readdir(HTMLDIR)) { - if ($file =~ m/\.html?$/) { - &RebaseFile("$dir$file"); - } - } - closedir (HTMLDIR); -} - - -sub RebaseFile { - my ($file) = @_; - print "Fixing file: $file\n" if $VERBOSE; - - open(HTMLFILE, $file) || die "Can't open $file: $!"; - local $/; - undef $/; - my $text = <HTMLFILE>; - close(HTMLFILE); - - $text =~ s#(<a(?:\s+\w+=(?:"[^"]*"|'[^']*'))*\s+href=")([^"]*)(")#$1 . &RebaseLink($2) .$3#gse; - - open(NEWFILE, ">$file.new") || die "Can't open $file: $!"; - print NEWFILE $text; - close(NEWFILE); - - unlink($file) || die "Can't delete $file: $!"; - rename("$file.new", $file) || die "Can't rename $file.new: $!"; -} - - -sub RebaseLink { - my ($href) = @_; - my ($dir, $origdir, $file, $package); - - if ($href =~ m#^(.*/)([^/]*)$#) { - $dir = $origdir = $1; - $file = $2; - if ($RevMap{ $dir }) { - $package = $RevMap{ $dir }; - } - elsif ($dir =~ m#^\.\./([^/]+)/#) { - $package = $1 - } - elsif ($AGGRESSIVE) { - $dir =~ m#([^/]+)/$#; - $package = $1; - } - - if ($package) { - if ($ONLINE && $OnlineMap{ $package }) { - $dir = $OnlineMap{ $package }; - } - elsif ($LocalMap{ $package }) { - $dir = $LocalMap{ $package }; - } - $href = $dir . $file; - } - if ($dir ne $origdir) { - if ($Mapped{ $origdir }) { - $Mapped{ $origdir }->[1]++; - } - else { - $Mapped{ $origdir } = [ $dir, 1 ]; - } - } - } - return $href; -} - - -sub PrintWhatWeHaveDone { - my ($origdir, $info); - foreach $origdir (sort keys %Mapped) { - $info = $Mapped{$origdir}; - print "$origdir -> ", $info->[0], " (", $info->[1], ")\n"; - } -} +import argparse +import sys +sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, rebase + + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-rebase version %s - rewrite links in html docs' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--html-dir', required=True, + help='The directory which contains the installed HTML') + parser.add_argument('--other-dir', default=[], action='append', + help='Directories to recursively scan for indices (*.devhelp2).' + 'May be used more than once for multiple directories.') + parser.add_argument('--dest-dir', default='', + help='Staging area virtual root, this prefix will be removed' + 'from HTML_DIR for relative link calculation.') + parser.add_argument('--aggressive', action='store_true', default=False, + help='Rebase links to all files that are under a directory matching a package name.') + parser.add_argument('--verbose', action='store_true', default=False, + help='Print extra output while processing') + parser.add_argument('--online', action='store_true', default=False, + help='Prefer cross-references to online documents') + parser.add_argument('--relative', action='store_true', default=False, + help='Prefer relative cross-references') + + options = parser.parse_args() + + common.setup_logging() + + sys.exit(rebase.run(options)) diff --git a/gtkdoc-scan.in b/gtkdoc-scan.in index 048e5c9..954c811 100755 --- a/gtkdoc-scan.in +++ b/gtkdoc-scan.in @@ -1,8 +1,9 @@ -#!@PERL@ -w -# -*- cperl -*- +#!@PYTHON@ +# -*- python -*- # # gtk-doc - GTK DocBook documentation generator. # Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -19,978 +20,40 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -############################################################################# -# Script : gtkdoc-scan -# Description : Extracts declarations of functions, macros, enums, structs -# and unions from header files. -# -# It is called with a module name, an optional source directory, -# an optional output directory, and the header files to scan. -# -# It outputs all declarations found to a file named -# '$MODULE-decl.txt', and the list of decarations to another -# file '$MODULE-decl-list.txt'. -# -# This second list file is typically copied to -# '$MODULE-sections.txt' and organized into sections ready to -# output the SGML pages. -############################################################################# - -use strict; -use Getopt::Long; -use Cwd qw(realpath); - -push @INC, '@PACKAGE_DATA_DIR@'; -require "gtkdoc-common.pl"; - -# Options - -# name of documentation module -my $MODULE; -my $OUTPUT_DIR; -my @SOURCE_DIRS; -my $IGNORE_HEADERS = ""; -my $REBUILD_TYPES; -my $REBUILD_SECTIONS; -my $PRINT_VERSION; -my $PRINT_HELP; -# regexp matching cpp symbols which surround deprecated stuff -# e.g. 'GTK_ENABLE_BROKEN|GTK_DISABLE_DEPRECATED' -# these are detected if they are used as #if FOO, #ifndef FOO, or #ifdef FOO -my $DEPRECATED_GUARDS; -# regexp matching decorators that should be ignored -my $IGNORE_DECORATORS; - -my @get_types = (); - -# do not read files twice; checking it here permits to give both srcdir and -# builddir as --source-dir without fear of duplicities -my %seen_headers; - - -run() unless caller; # Run program unless loaded as a module - - -sub run { - my %optctl = (module => \$MODULE, - 'source-dir' => \@SOURCE_DIRS, - 'ignore-headers' => \$IGNORE_HEADERS, - 'output-dir' => \$OUTPUT_DIR, - 'rebuild-types' => \$REBUILD_TYPES, - 'rebuild-sections' => \$REBUILD_SECTIONS, - 'version' => \$PRINT_VERSION, - 'help' => \$PRINT_HELP, - 'deprecated-guards' => \$DEPRECATED_GUARDS, - 'ignore-decorators' => \$IGNORE_DECORATORS); - GetOptions(\%optctl, "module=s", "source-dir:s", "ignore-headers:s", - "output-dir:s", "rebuild-types", "rebuild-sections", "version", - "help", "deprecated-guards:s", "ignore-decorators:s"); - - if ($PRINT_VERSION) { - print "@VERSION@\n"; - exit 0; - } - - if (!$MODULE) { - $PRINT_HELP = 1; - } - - if ($PRINT_HELP) { - print <<EOF; -gtkdoc-scan version @VERSION@ - scan header files for public symbols - ---module=MODULE_NAME Name of the doc module being parsed ---source-dir=DIRNAME Directories containing the source files to scan ---ignore-headers=FILES A space-separated list of header files/dirs not to - scan ---output-dir=DIRNAME The directory where the results are stored ---deprecated-guards=GUARDS A |-separated list of symbols used as deprecation - guards ---ignore-decorators=DECS A |-separated list of addition decorators in - declarations that should be ignored ---rebuild-sections Rebuild (overwrite) the MODULE-sections.txt file ---rebuild-types Automatically recreate the MODULE.types file using - all the *_get_type() functions found ---version Print the version of this program ---help Print this help -EOF - exit 0; - } - - $DEPRECATED_GUARDS = $DEPRECATED_GUARDS ? $DEPRECATED_GUARDS : "does_not_match_any_cpp_symbols_at_all_nope"; - - $IGNORE_DECORATORS = $IGNORE_DECORATORS || "(?=no)match"; - - $OUTPUT_DIR = $OUTPUT_DIR ? $OUTPUT_DIR : "."; - - if (!-d ${OUTPUT_DIR}) { - mkdir($OUTPUT_DIR, 0755) || die "Cannot create $OUTPUT_DIR: $!"; - } - - my $old_decl_list = "${OUTPUT_DIR}/$MODULE-decl-list.txt"; - my $new_decl_list = "${OUTPUT_DIR}/$MODULE-decl-list.new"; - my $old_decl = "${OUTPUT_DIR}/$MODULE-decl.txt"; - my $new_decl = "${OUTPUT_DIR}/$MODULE-decl.new"; - my $old_types = "${OUTPUT_DIR}/$MODULE.types"; - my $new_types = "${OUTPUT_DIR}/$MODULE.types.new"; - my $sections_file = "${OUTPUT_DIR}/$MODULE-sections.txt"; - - # If this is the very first run then we create the .types file automatically. - if (! -e $sections_file && ! -e $old_types) { - $REBUILD_TYPES = 1; - } - - open (DECLLIST, ">$new_decl_list") - || die "Can't open $new_decl_list"; - open (DECL, ">$new_decl") - || die "Can't open $new_decl"; - if ($REBUILD_TYPES) { - open (TYPES, ">$new_types") - || die "Can't open $new_types"; - } - - my %section_list = (); - my $file; - - # The header files to scan are passed in as command-line args. - for $file (@ARGV) { - &ScanHeader ($file, \%section_list); - } - - for my $dir (@SOURCE_DIRS) { - &ScanHeaders ($dir, \%section_list); - } - - ## FIXME: sort by key and output - #print DECLLIST $section_list; - my $section; - foreach $section (sort(keys %section_list)) { - print DECLLIST "$section_list{$section}"; - } - - close (DECLLIST); - close (DECL); - - if ($REBUILD_TYPES) { - my $func; - - foreach $func (sort(@get_types)) { - print TYPES "$func\n"; - } - close (TYPES); - &UpdateFileIfChanged ($old_types, $new_types, 1); - - # remove the file if empty - if (scalar (@get_types) == 0) { - unlink ("$new_types"); - } - } - - &UpdateFileIfChanged ($old_decl_list, $new_decl_list, 1); - &UpdateFileIfChanged ($old_decl, $new_decl, 1); - - # If there is no MODULE-sections.txt file yet or we are asked to rebuild it, - # we copy the MODULE-decl-list.txt file into its place. The user can tweak it - # later if they want. - if ($REBUILD_SECTIONS || ! -e $sections_file) { - `cp $old_decl_list $sections_file`; - } - - # If there is no MODULE-overrides.txt file we create an empty one - # because EXTRA_DIST in gtk-doc.make requires it. - my $overrides_file = "${OUTPUT_DIR}/$MODULE-overrides.txt"; - if (! -e $overrides_file) { - `touch $overrides_file`; - } -} - - -############################################################################# -# Function : ScanHeaders -# Description : This scans a directory tree looking for header files. -# -# Arguments : $source_dir - the directory to scan. -# $section_list - a reference to the hashmap of sections. -############################################################################# - -sub ScanHeaders { - my ($source_dir, $section_list) = @_; - @TRACE@("Scanning source directory: $source_dir"); - - # This array holds any subdirectories found. - my (@subdirs) = (); - - opendir (SRCDIR, $source_dir) - || die "Can't open source directory $source_dir: $!"; - my $file; - foreach $file (readdir (SRCDIR)) { - if ($file eq '.' || $file eq '..' || $file =~ /^\./) { - next; - } elsif (-d "$source_dir/$file") { - push (@subdirs, $file); - } elsif ($file =~ m/\.h$/) { - &ScanHeader ("$source_dir/$file", $section_list); - } - } - closedir (SRCDIR); - - # Now recursively scan the subdirectories. - my $dir; - foreach $dir (@subdirs) { - next if ($IGNORE_HEADERS =~ m/(\s|^)\Q${dir}\E(\s|$)/); - &ScanHeaders ("$source_dir/$dir", $section_list); - } -} - - -############################################################################# -# Function : ScanHeader -# Description : This scans a header file, looking for declarations of -# functions, macros, typedefs, structs and unions, which it -# outputs to the DECL file. -# Arguments : $input_file - the header file to scan. -# $section_list - a reference to the hashmap of sections. -# Returns : it adds declarations to the appropriate list. -############################################################################# - -sub ScanHeader { - my ($input_file, $section_list) = @_; - - my $list = ""; # Holds the resulting list of declarations. - my $title = ""; # Holds the title of the section - my ($in_comment) = 0; # True if we are in a comment. - my ($in_declaration) = ""; # The type of declaration we are in, e.g. - # 'function' or 'macro'. - my ($skip_block) = 0; # True if we should skip a block. - my ($symbol); # The current symbol being declared. - my ($decl); # Holds the declaration of the current symbol. - my ($ret_type); # For functions and function typedefs this - # holds the function's return type. - my ($pre_previous_line) = ""; # The pre-previous line read in - some Gnome - # functions have the return type on one - # line, the function name on the next, - # and the rest of the declaration after. - my ($previous_line) = ""; # The previous line read in - some Gnome - # functions have the return type on one line - # and the rest of the declaration after. - my ($first_macro) = 1; # Used to try to skip the standard #ifdef XXX - # #define XXX at the start of headers. - my ($level); # Used to handle structs/unions which contain - # nested structs or unions. - my @objects = (); # Holds declarations that look like GtkObject - # subclasses, which we remove from the list. - my ($internal) = 0; # Set to 1 for internal symbols, we need to - # fully parse, but don't add them to docs - my %forward_decls = (); # hashtable of forward declarations, we skip - # them if we find the real declaration - # later. - my %doc_comments = (); # hastable of doc-comment we found. We can - # use that to put element to the right - # sction in the generated section-file - - my $file_basename; - - my $deprecated_conditional_nest = 0; - my $ignore_conditional_nest = 0; - - my $deprecated = ""; - my $doc_comment = ""; - - # Don't scan headers twice - my $canonical_input_file = realpath $input_file; - if (exists $seen_headers{$canonical_input_file}) { - @TRACE@("File already scanned: $input_file"); - return; - } - $seen_headers{$canonical_input_file} = 1; - - if ($input_file =~ m/^.*[\/\\](.*)\.h+$/) { - $file_basename = $1; - } else { - LogWarning(__FILE__,__LINE__,"Can't find basename of file $input_file"); - $file_basename = $input_file; - } - - # Check if the basename is in the list of headers to ignore. - if ($IGNORE_HEADERS =~ m/(\s|^)\Q${file_basename}\E\.h(\s|$)/) { - @TRACE@("File ignored: $input_file"); - return; - } - # Check if the full name is in the list of headers to ignore. - if ($IGNORE_HEADERS =~ m/(\s|^)\Q${input_file}\E(\s|$)/) { - @TRACE@("File ignored: $input_file"); - return; - } - - if (! -f $input_file) { - LogWarning(__FILE__,__LINE__,"File doesn't exist: $input_file"); - return; - } - - @TRACE@("Scanning $input_file"); - - open(INPUT, $input_file) - || die "Can't open $input_file: $!"; - while(<INPUT>) { - # If this is a private header, skip it. - if (m%^\s*/\*\s*<\s*private_header\s*>\s*\*/%) { - close(INPUT); - return; - } - - # Skip to the end of the current comment. - if ($in_comment) { - @TRACE@("Comment: $_"); - $doc_comment .= $_; - if (m%\*/%) { - if ($doc_comment =~ m/\* ([a-zA-Z][a-zA-Z0-9_]+):/) { - $doc_comments{lc($1)} = 1; - } - $in_comment = 0; - $doc_comment = ""; - } - next; - } - - # Keep a count of #if, #ifdef, #ifndef nesting, - # and if we enter a deprecation-symbol-bracketed - # zone, take note. - if (m/^\s*#\s*if(?:n?def\b|\s+!?\s*defined\s*\()\s*(\w+)/) { - my $define_name = $1; - if ($deprecated_conditional_nest < 1 and $define_name =~ /$DEPRECATED_GUARDS/) { - $deprecated_conditional_nest = 1; - } elsif ($deprecated_conditional_nest >= 1) { - $deprecated_conditional_nest += 1; - } - if ($ignore_conditional_nest == 0 and $define_name =~ /__GTK_DOC_IGNORE__/) { - $ignore_conditional_nest = 1; - } elsif ($ignore_conditional_nest > 0) { - $ignore_conditional_nest += 1; - } - } elsif (m/^\s*#\sif/) { - if ($deprecated_conditional_nest >= 1) { - $deprecated_conditional_nest += 1; - } - if ($ignore_conditional_nest > 0) { - $ignore_conditional_nest += 1; - } - } elsif (m/^\s*#endif/) { - if ($deprecated_conditional_nest >= 1) { - $deprecated_conditional_nest -= 1; - } - if ($ignore_conditional_nest > 0) { - $ignore_conditional_nest -= 1; - } - } - - # If we find a line containing _DEPRECATED, we hope that this is - # attribute based deprecation and also treat this as a deprecation - # guard, unless it's a macro definition. - if ($deprecated_conditional_nest == 0 and m/_DEPRECATED/) { - unless (m/^\s*#\s*(if*|define)/ or $in_declaration eq "enum") { - @TRACE@("Found deprecation annotation (decl: '$in_declaration'): $_"); - $deprecated_conditional_nest += 0.1; - } - } - - # set global that is used later when we do AddSymbolToList - if ($deprecated_conditional_nest > 0) { - $deprecated = "<DEPRECATED/>\n"; - } else { - $deprecated = ""; - } - - if($ignore_conditional_nest) { - next; - } - - if (!$in_declaration) { - # Skip top-level comments. - if (s%^\s*/\*%%) { - if (m%\*/%) { - @TRACE@("Found one-line comment: $_"); - } else { - $in_comment = 1; - $doc_comment = $_; - @TRACE@("Found start of comment: $_"); - } - next; - } - - @TRACE@("0: $_"); - - # MACROS - - if (m/^\s*#\s*define\s+(\w+)/) { - $symbol = $1; - $decl = $_; - # We assume all macros which start with '_' are private, but - # we accept '_' itself which is the standard gettext macro. - # We also try to skip the first macro if it looks like the - # standard #ifndef HEADER_FILE #define HEADER_FILE etc. - # And we only want TRUE & FALSE defined in GLib (libdefs.h in - # libgnome also defines them if they are not already defined). - if (($symbol !~ m/^_/ - && ($previous_line !~ m/#ifndef\s+$symbol/ - || $first_macro == 0) - && (($symbol ne 'TRUE' && $symbol ne 'FALSE') - || $MODULE eq 'glib')) - || $symbol eq "_") { - $in_declaration = "macro"; - @TRACE@("Macro: $symbol"); - } else { - @TRACE@("skipping Macro: $symbol"); - $in_declaration = "macro"; - $internal = 1; - } - $first_macro = 0; - - - # TYPEDEF'D FUNCTIONS (i.e. user functions) - - # $1 $3 $4 $5 - } elsif (m/^\s*typedef\s+((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) { - my $p3 = defined($3) ? $3 : ""; - $ret_type = "$1$p3 $4"; - $symbol = $5; - $decl = $'; - $in_declaration = "user_function"; - @TRACE@("user function (1): $symbol, Returns: $ret_type"); - - # $1 $3 $4 $5 - } elsif (($previous_line =~ m/^\s*typedef\s*/) && m/^\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) { - my $p3 = defined($3) ? $3 : ""; - $ret_type = "$1$p3 $4"; - $symbol = $5; - $decl = $'; - $in_declaration = "user_function"; - @TRACE@("user function (2): $symbol, Returns: $ret_type"); - - # $1 $2 - } elsif (($previous_line =~ m/^\s*typedef\s*/) && m/^\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/) { - $ret_type = $1; - $symbol = $2; - $decl = $'; - # $1 $3 - if ($previous_line =~ m/^\s*typedef\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*/) { - my $p3 = defined($3) ? $3 : ""; - $ret_type = "$1$p3 ".$ret_type; - $in_declaration = "user_function"; - @TRACE@("user function (3): $symbol, Returns: $ret_type"); - - } - # FUNCTION POINTER VARIABLES - # $1 $3 $4 $5 - } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(/o) { - my $p3 = defined($3) ? $3 : ""; - $ret_type = "$1$p3 $4"; - $symbol = $5; - $decl = $'; - $in_declaration = "user_function"; - @TRACE@("function pointer variable: $symbol, Returns: $ret_type"); - - # ENUMS - - } elsif (s/^\s*enum\s+_?(\w+)\s+\{/enum $1 {/) { - # We assume that 'enum _<enum_name> {' is really the - # declaration of enum <enum_name>. - $symbol = $1; - @TRACE@("plain enum: $symbol"); - $decl = $_; - $in_declaration = "enum"; - - } elsif (m/^\s*typedef\s+enum\s+_?(\w+)\s+\1\s*;/) { - # We skip 'typedef enum <enum_name> _<enum_name>;' as the enum will - # be declared elsewhere. - @TRACE@("skipping enum typedef: $1"); - - } elsif (m/^\s*typedef\s+enum/) { - $symbol = ""; - @TRACE@("typedef enum: -"); - $decl = $_; - $in_declaration = "enum"; - - - # STRUCTS AND UNIONS - - } elsif (m/^\s*typedef\s+(struct|union)\s+_(\w+)\s+\2\s*;/) { - # We've found a 'typedef struct _<name> <name>;' - # This could be an opaque data structure, so we output an - # empty declaration. If the structure is actually found that - # will override this. - my $structsym = uc $1; - @TRACE@("$structsym typedef: $2"); - $forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$deprecated</$structsym>\n" - - } elsif (m/^\s*(?:struct|union)\s+_(\w+)\s*;/) { - # Skip private structs/unions. - @TRACE@("private struct/union"); - - } elsif (m/^\s*(struct|union)\s+(\w+)\s*;/) { - # Do a similar thing for normal structs as for typedefs above. - # But we output the declaration as well in this case, so we - # can differentiate it from a typedef. - my $structsym = uc $1; - @TRACE@("$structsym: $2"); - $forward_decls{$2} = "<$structsym>\n<NAME>$2</NAME>\n$_$deprecated</$structsym>\n"; - - } elsif (m/^\s*typedef\s+(struct|union)\s*\w*\s*{/) { - $symbol = ""; - $decl = $_; - $level = 0; - $in_declaration = $1; - @TRACE@("typedef struct/union $1"); - - # OTHER TYPEDEFS - - } elsif (m/^\s*typedef\s+(?:struct|union)\s+\w+[\s\*]+(\w+)\s*;/) { - @TRACE@("Found struct/union(*) typedef $1: $_"); - if (&AddSymbolToList (\$list, $1)) { - print DECL "<TYPEDEF>\n<NAME>$1</NAME>\n$deprecated$_</TYPEDEF>\n"; - } - - } elsif (m/^\s*(G_GNUC_EXTENSION\s+)?typedef\s+(.+[\s\*])(\w+)(\s*\[[^\]]+\])*\s*;/) { - if ($2 !~ m/^struct\s/ && $2 !~ m/^union\s/) { - @TRACE@("Found typedef: $_"); - if (&AddSymbolToList (\$list, $3)) { - print DECL "<TYPEDEF>\n<NAME>$3</NAME>\n$deprecated$_</TYPEDEF>\n"; - } - } - } elsif (m/^\s*typedef\s+/) { - @TRACE@("Skipping typedef: $_"); - - - # VARIABLES (extern'ed variables) - - } elsif (m/^\s*(extern|[A-Za-z_]+VAR|${IGNORE_DECORATORS})\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*;/o) { - $symbol = $6; - s/^\s*([A-Za-z_]+VAR)\b/extern/; - $decl = $_; - @TRACE@("Possible extern var $symbol: $decl"); - if (&AddSymbolToList (\$list, $symbol)) { - print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$deprecated$decl</VARIABLE>\n"; - } - - - # VARIABLES - - } elsif (m/^\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*\=/) { - $symbol = $5; - $decl = $_; - @TRACE@("Possible global var $symbol: $decl"); - if (&AddSymbolToList (\$list, $symbol)) { - print DECL "<VARIABLE>\n<NAME>$symbol</NAME>\n$deprecated$decl</VARIABLE>\n"; - } - - # G_DECLARE_* - - } elsif (m/.*G_DECLARE_(FINAL_TYPE|DERIVABLE_TYPE|INTERFACE)\s*\(/) { - $in_declaration = "g-declare"; - $symbol = "G_DECLARE_$1"; - $decl = $'; - - # FUNCTIONS - - # We assume that functions which start with '_' are private, so - # we skip them. - # $1 $2 $3 - } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s+|\*)+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*(_[A-Za-z]\w*)\s*\(/o) { - $ret_type = $1; - if (defined ($2)) { $ret_type .= " $2"; } - $symbol = $3; - $decl = $'; - @TRACE@("internal Function: $symbol, Returns: [$1][$2]"); - $in_declaration = "function"; - $internal = 1; - if (m/^\s*G_INLINE_FUNC/) { - @TRACE@("skip block after inline function"); - # now we we need to skip a whole { } block - $skip_block = 1; - } - - # $1 $2 $3 - } elsif (m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s+|\*)+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*([A-Za-z]\w*)\s*\(/o) { - $ret_type = $1; - if (defined ($2)) { $ret_type .= " $2"; } - $symbol = $3; - $decl = $'; - @TRACE@("Function (1): $symbol, Returns: [$1][$2]"); - $in_declaration = "function"; - if (m/^\s*G_INLINE_FUNC/) { - @TRACE@("skip block after inline function"); - # now we we need to skip a whole { } block - $skip_block = 1; - } - - # Try to catch function declarations which have the return type on - # the previous line. But we don't want to catch complete functions - # which have been declared G_INLINE_FUNC, e.g. g_bit_nth_lsf in - # glib, or 'static inline' functions. - } elsif (m/^\s*([A-Za-z]\w*)\s*\(/) { - $symbol = $1; - $decl = $'; - - if ($previous_line !~ m/^\s*G_INLINE_FUNC/) { - if ($previous_line !~ m/^\s*static\s+/) { - # $1 $2 - if ($previous_line =~ m/^\s*(?:\b(?:extern|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$/o) { - $ret_type = $1; - if (defined ($2)) { $ret_type .= " $2"; } - @TRACE@("Function (2): $symbol, Returns: $ret_type"); - $in_declaration = "function"; - } - } else { - @TRACE@("skip block after inline function"); - # now we we need to skip a whole { } block - $skip_block = 1; - # $1 $2 - if ($previous_line =~ m/^\s*(?:\b(?:extern|static|inline|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$/o) { - $ret_type = $1; - if (defined ($2)) { $ret_type .= " $2"; } - @TRACE@("Function (3): $symbol, Returns: $ret_type"); - $in_declaration = "function"; - } - } - } - else { - if ($previous_line !~ m/^\s*static\s+/) { - @TRACE@("skip block after inline function"); - # now we we need to skip a whole { } block - $skip_block = 1; - # $1 $2 - if ($previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$/o) { - $ret_type = $1; - if (defined ($2)) { $ret_type .= " $2"; } - @TRACE@("Function (4): $symbol, Returns: $ret_type"); - $in_declaration = "function"; - } - } - } - - # Try to catch function declarations with the return type and name - # on the previous line(s), and the start of the parameters on this. - } elsif (m/^\s*\(/) { - $decl = $'; - if ($previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|enum\s+)*\w+)(\s+\*+|\*+|\s)\s*([A-Za-z]\w*)\s*$/o) { - $ret_type = "$1 $2"; - $symbol = $3; - @TRACE@("Function (5): $symbol, Returns: $ret_type"); - $in_declaration = "function"; - - } elsif ($previous_line =~ m/^\s*\w+\s*$/ - && $pre_previous_line =~ m/^\s*(?:\b(?:extern|G_INLINE_FUNC|${IGNORE_DECORATORS})\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|struct\s+|union\s+|enum\s+)*\w+(?:\**\s+\**(?:const|G_CONST_RETURN))?(?:\s+|\s*\*+))\s*$/o) { - $ret_type = $1; - $ret_type =~ s/\s*\n//; - $in_declaration = "function"; - - $symbol = $previous_line; - $symbol =~ s/^\s+//; - $symbol =~ s/\s*\n//; - @TRACE@("Function (6): $symbol, Returns: $ret_type"); - } - - #} elsif (m/^extern\s+/) { - #print "DEBUG: Skipping extern: $_"; - - - # STRUCTS - - } elsif (m/^\s*struct\s+_?(\w+)\s*\*/) { - # Skip 'struct _<struct_name> *', since it could be a - # return type on its own line. - - } elsif (m/^\s*struct\s+_?(\w+)/) { - # We assume that 'struct _<struct_name>' is really the - # declaration of struct <struct_name>. - $symbol = $1; - $decl = $_; - # we will find the correct level as below we do $level += tr/{//; - $level = 0; - $in_declaration = "struct"; - @TRACE@("Struct(_): $symbol"); - - - # UNIONS - - } elsif (m/^\s*union\s+_(\w+)\s*\*/) { - # Skip 'union _<union_name> *' (see above) - } elsif (m/^\s*union\s+_(\w+)/) { - $symbol = $1; - $decl = $_; - $level = 0; - $in_declaration = "union"; - @TRACE@("Union(_): $symbol"); - } - - } else { - @TRACE@("1: [$skip_block] $_"); - # If we were already in the middle of a declaration, we simply add - # the current line onto the end of it. - if ($skip_block == 0) { - $decl .= $_; - } else { - # Remove all nested pairs of curly braces. - while ($_ =~ s/{[^{]*}//g) { } - # Then hope at most one remains in the line... - if (m%(.*?){%) { - if ($skip_block == 1) { - $decl .= $1; - } - $skip_block += 1; - } elsif (m%}%) { - $skip_block -= 1; - if ($skip_block == 1) { - # this is a hack to detect the end of declaration - $decl .= ";"; - $skip_block = 0; - @TRACE@("2: ---"); - } - } else { - if ($skip_block == 1) { - $decl .= $_; - } - } - } - } - - #if ($in_declaration ne '') { - # print "$in_declaration = $decl\n"; - #} - - if ($in_declaration eq "g-declare") { - if ($decl =~ s/\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*\).*$//) { - my $ModuleObjName = $1; - my $module_obj_name = $2; - if ($REBUILD_TYPES) { - push (@get_types, "${module_obj_name}_get_type"); - } - $forward_decls{$ModuleObjName} = "<STRUCT>\n<NAME>$ModuleObjName</NAME>\n$deprecated</STRUCT>\n"; - if ($symbol =~ /^G_DECLARE_DERIVABLE/) { - $forward_decls{"${ModuleObjName}Class"} = "<STRUCT>\n<NAME>${ModuleObjName}Class</NAME>\n$deprecated</STRUCT>\n"; - } - if ($symbol =~ /^G_DECLARE_INTERFACE/) { - $forward_decls{"${ModuleObjName}Interface"} = "<STRUCT>\n<NAME>${ModuleObjName}Interface</NAME>\n$deprecated</STRUCT>\n"; - } - $in_declaration = ""; - } - } - - # Note that sometimes functions end in ') G_GNUC_PRINTF (2, 3);' or - # ') __attribute__ (...);'. - if ($in_declaration eq 'function') { - if ($decl =~ s/\)\s*(G_GNUC_.*|.*DEPRECATED.*|${IGNORE_DECORATORS}\s*|__attribute__\s*\(.*\)\s*)*;.*$//s) { - if ($internal == 0) { - $decl =~ s%/\*.*?\*/%%gs; # remove comments. - #$decl =~ s/^\s+//; # remove leading whitespace. - #$decl =~ s/\s+$//; # remove trailing whitespace. - $decl =~ s/\s*\n\s*/ /gs; # consolidate whitespace at start - # and end of lines. - $ret_type =~ s%/\*.*?\*/%%g; # remove comments in ret type. - if (&AddSymbolToList (\$list, $symbol)) { - print DECL "<FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl\n</FUNCTION>\n"; - if ($REBUILD_TYPES) { - # check if this looks like a get_type function and if so remember - if (($symbol =~ m/_get_type$/) && ($ret_type =~ m/GType/) && ($decl =~ m/^(void|)$/)) { - @TRACE@("Adding get-type: [$ret_type] [$symbol] [$decl]\tfrom $input_file"); - push (@get_types, $symbol); - } - } - } - } else { - $internal = 0; - } - $deprecated_conditional_nest = int($deprecated_conditional_nest); - $in_declaration = ""; - $skip_block = 0; - } - } - - if ($in_declaration eq 'user_function') { - if ($decl =~ s/\).*$//) { - if (&AddSymbolToList (\$list, $symbol)) { - print DECL "<USER_FUNCTION>\n<NAME>$symbol</NAME>\n$deprecated<RETURNS>$ret_type</RETURNS>\n$decl</USER_FUNCTION>\n"; - } - $deprecated_conditional_nest = int($deprecated_conditional_nest); - $in_declaration = ""; - } - } - - if ($in_declaration eq 'macro') { - if ($decl !~ m/\\\s*$/) { - if ($internal == 0) { - if (&AddSymbolToList (\$list, $symbol)) { - print DECL "<MACRO>\n<NAME>$symbol</NAME>\n$deprecated$decl</MACRO>\n"; - } - } else { - $internal = 0; - } - $deprecated_conditional_nest = int($deprecated_conditional_nest); - $in_declaration = ""; - } - } - - if ($in_declaration eq 'enum') { - if ($decl =~ m/\}\s*(\w+)?;\s*$/) { - if ($symbol eq "") { - $symbol = $1; - } - if (&AddSymbolToList (\$list, $symbol)) { - print DECL "<ENUM>\n<NAME>$symbol</NAME>\n$deprecated$decl</ENUM>\n"; - } - $deprecated_conditional_nest = int($deprecated_conditional_nest); - $in_declaration = ""; - } - } - - # We try to handle nested stucts/unions, but unmatched brackets in - # comments will cause problems. - if ($in_declaration eq 'struct' or $in_declaration eq 'union') { - if (($level <= 1) && ($decl =~ m/\n\}\s*(\w*);\s*$/)) { - if ($symbol eq "") { - $symbol = $1; - } - - if ($symbol =~ m/^(\S+)(Class|Iface|Interface)\b/) { - my $objectname = $1; - @TRACE@("Found object: $1"); - $title = "<TITLE>$objectname\n"; - push (@objects, $objectname); - } - @TRACE@("Store struct: $symbol"); - if (&AddSymbolToList (\$list, $symbol)) { - my $structsym = uc $in_declaration; - print DECL "<$structsym>\n$symbol\n$deprecated$decl\n"; - if (defined($forward_decls{$symbol})) { - undef($forward_decls{$symbol}); - } - } - $deprecated_conditional_nest = int($deprecated_conditional_nest); - $in_declaration = ""; - } else { - # We use tr to count the brackets in the line, and adjust - # $level accordingly. - $level += tr/{//; - $level -= tr/}//; - @TRACE@("struct/union level : $level"); - } - } - - $pre_previous_line = $previous_line; - $previous_line = $_; - } - close(INPUT); - - # print remaining forward declarations - foreach $symbol (sort(keys %forward_decls)) { - if (defined($forward_decls{$symbol})) { - &AddSymbolToList (\$list, $symbol); - print DECL $forward_decls{$symbol}; - } - } - - # add title - $list = "$title$list"; - - @TRACE@("Scanning $input_file done\n"); - - # Try to separate the standard macros and functions, placing them at the - # end of the current section, in a subsection named 'Standard'. - # do this in a loop to catch object, enums and flags - my ($class,$lclass,$prefix,$lprefix); - my ($standard_decl) = ""; - do { - if ($list =~ m/^(\S+)_IS_(\S*)_CLASS\n/m) { - $prefix = $1; - $lprefix = lc($prefix); - $class = $2; - $lclass = lc($class); - @TRACE@("Found gobject type '${prefix}_$class' from is_class macro\n"); - } elsif ($list =~ m/^(\S+)_IS_(\S*)\n/m) { - $prefix = $1; - $lprefix = lc($prefix); - $class = $2; - $lclass = lc($class); - @TRACE@("Found gobject type '${prefix}_$class' from is_ macro\n"); - } elsif ($list =~ m/^(\S+?)_(\S*)_get_type\n/m) { - $lprefix = $1; - $prefix = uc($lprefix); - $lclass = $2; - $class = uc($lclass); - @TRACE@("Found gobject type '${prefix}_$class' from get_type function\n"); - } else { - $class = $lclass = ""; - } - - if ($class ne "") { - my ($cclass) = $lclass; - $cclass =~ s/_//g; - my ($type) = $lprefix.$cclass; - - if ($list =~ s/^${type}Private\n//im) { $standard_decl .= $&; } - - # We only leave XxYy* in the normal section if they have docs - if (! defined($doc_comments{$type})) { - @TRACE@(" Hide instance docs for $type"); - if ($list =~ s/^${type}\n//im) { $standard_decl .= $&; } - } - if (! defined($doc_comments{$type."class"})) { - @TRACE@(" Hide class docs for $type"); - if ($list =~ s/^${type}Class\n//im) { $standard_decl .= $&; } - } - if (! defined($doc_comments{$type."interface"})) { - @TRACE@(" Hide iface docs for $type"); - if ($list =~ s/^$type}Interface\n//im) { $standard_decl .= $&; } - } - if (! defined($doc_comments{$type."iface"})) { - @TRACE@(" Hide iface docs for $type"); - if ($list =~ s/${type}Iface\n//im) { $standard_decl .= $&; } - } - - while ($list =~ s/^\S+_IS_$class\n//m) { $standard_decl .= $&; } - while ($list =~ s/^\S+_TYPE_$class\n//m) { $standard_decl .= $&; } - while ($list =~ s/^\S+_${lclass}_get_type\n//m) { $standard_decl .= $&; } - while ($list =~ s/^\S+_${class}_CLASS\n//m) { $standard_decl .= $&; } - while ($list =~ s/^\S+_IS_${class}_CLASS\n//m) { $standard_decl .= $&; } - while ($list =~ s/^\S+_${class}_GET_CLASS\n//m) { $standard_decl .= $&; } - while ($list =~ s/^\S+_${class}_GET_IFACE\n//m) { $standard_decl .= $&; } - while ($list =~ s/^\S+_${class}_GET_INTERFACE\n//m) { $standard_decl .= $&; } - - # We do this one last, otherwise it tends to be caught by the IS_$class macro - while ($list =~ s/^\S+_$class\n//m) { $standard_decl .= $&; } - - @TRACE@("Decl '".join(",",split("\n",$list))."'\n"); - @TRACE@("Std '".join(",",split("\n",$standard_decl))."'\n"); - } - } while ($class ne ""); - if ($standard_decl ne "") { - # sort the symbols - $standard_decl=join("\n",sort(split("\n",$standard_decl)))."\n"; - $list .= "\n$standard_decl"; - } - if ($list ne "") { - $$section_list{$file_basename} .= "
\n$file_basename\n$list
\n\n"; - } -} - - -############################################################################# -# Function : AddSymbolToList -# Description : This adds the symbol to the list of declarations, but only if -# it is not already in the list. -# Arguments : $list - reference to the list of symbols, one on each line. -# $symbol - the symbol to add to the list. -############################################################################# - -sub AddSymbolToList { - my ($list, $symbol) = @_; - - if ($$list =~ m/\b\Q$symbol\E\b/) { - #print "Symbol $symbol already in list. skipping\n"; - # we return 0 to skip outputting another entry to -decl.txt - # this is to avoid redeclarations (e.g. in conditional - # sections). - return 0; - } - $$list .= "$symbol\n"; - return 1; -} +from __future__ import print_function + +import argparse +import sys +sys.path.append('@PYTHON_PACKAGE_DIR@') + +from gtkdoc import common, config, scan + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description='gtkdoc-scan version %s - scan header files for public symbols' % config.version) + parser.add_argument('--version', action='version', version=config.version) + parser.add_argument('--module', required=True, + help='Name of the doc module being processed.') + parser.add_argument('--source-dir', action='append', default=[], + help='Directories containing the source files to scan') + parser.add_argument('--ignore-headers', default='', + help='A space-separated list of header files/dirs not to scan') + parser.add_argument('--output-dir', default='.', + help='The directory where the results are stored') + parser.add_argument('--deprecated-guards', default='does_not_match_any_cpp_symbols_at_all_nope', + help='A |-separated list of symbols used as deprecation guards') + parser.add_argument('--ignore-decorators', default='(?=no)match', + help='A |-separated list of additional decorators in' + 'declarations that should be ignored') + parser.add_argument('--rebuild-sections', action='store_true', default=False, + help='Rebuild (overwrite) the MODULE-sections.txt file') + parser.add_argument('--rebuild-types', action='store_true', default=False, + help='Automatically recreate the MODULE.types file using' + 'all the *_get_type() functions found') + parser.add_argument('headers', nargs='*') + + options = parser.parse_args() + + common.setup_logging() + + scan.Run(options) diff --git a/gtkdoc-scangobj.in b/gtkdoc-scangobj.in index fb66b76..4cbe130 100644 --- a/gtkdoc-scangobj.in +++ b/gtkdoc-scangobj.in @@ -1,8 +1,9 @@ -#!@PERL@ -w -# -*- cperl -*- +#!@PYTHON@ +# -*- python -*- # # gtk-doc - GTK DocBook documentation generator. # Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -19,1333 +20,52 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. # -# -# This gets information about object hierarchies and signals -# by compiling a small C program. CFLAGS and LDFLAGS must be -# set appropriately before running this script. -# - -use strict; -use Getopt::Long; - -push @INC, '@PACKAGE_DATA_DIR@'; -require "gtkdoc-common.pl"; - -# Options - -# name of documentation module -my $MODULE; -my $TYPES_FILE; -my $NO_GTK_INIT; -my $OUTPUT_DIR; -my $VERBOSE; -my $PRINT_VERSION; -my $PRINT_HELP; -my $TYPE_INIT_FUNC="#if !GLIB_CHECK_VERSION(2,35,0)\n g_type_init();\n #endif\n g_type_class_ref(G_TYPE_OBJECT)"; -my $QUERY_CHILD_PROPERTIES; - -my $CC; -my $LD; -my $CFLAGS; -my $LDFLAGS; -my $RUN; - -# --nogtkinit is deprecated, as it is the default now anyway. -my %optctl = (module => \$MODULE, - types => \$TYPES_FILE, - nogtkinit => \$NO_GTK_INIT, - 'type-init-func' => \$TYPE_INIT_FUNC, - 'query-child-properties' => \$QUERY_CHILD_PROPERTIES, - 'output-dir' => \$OUTPUT_DIR, - 'cc' => \$CC, - 'ld' => \$LD, - 'cflags' => \$CFLAGS, - 'ldflags' => \$LDFLAGS, - 'run' => \$RUN, - 'verbose' => \$VERBOSE, - 'version' => \$PRINT_VERSION, - 'help' => \$PRINT_HELP); - -GetOptions(\%optctl, "module=s", "types:s", "output-dir:s", "nogtkinit", "type-init-func:s", "query-child-properties:s", "cc:s", "ld:s", "run:s", "cflags:s", "ldflags:s", "verbose", "version", "help"); - -if ($NO_GTK_INIT) { - # Do nothing. This just avoids a warning. - # the option is not used anymore -} - -if ($PRINT_VERSION) { - print "@VERSION@\n"; - exit 0; -} - -if (!$MODULE) { - $PRINT_HELP = 1; -} - -if ($PRINT_HELP) { - print <$MODULE-scan.c") || die "Cannot open $MODULE-scan.c: $!\n"; - -my $old_signals_filename = "$OUTPUT_DIR/$MODULE.signals"; -my $new_signals_filename = "$OUTPUT_DIR/$MODULE.signals.new"; -my $old_hierarchy_filename = "$OUTPUT_DIR/$MODULE.hierarchy"; -my $new_hierarchy_filename = "$OUTPUT_DIR/$MODULE.hierarchy.new"; -my $old_interfaces_filename = "$OUTPUT_DIR/$MODULE.interfaces"; -my $new_interfaces_filename = "$OUTPUT_DIR/$MODULE.interfaces.new"; -my $old_prerequisites_filename = "$OUTPUT_DIR/$MODULE.prerequisites"; -my $new_prerequisites_filename = "$OUTPUT_DIR/$MODULE.prerequisites.new"; -my $old_args_filename = "$OUTPUT_DIR/$MODULE.args"; -my $new_args_filename = "$OUTPUT_DIR/$MODULE.args.new"; - -# generate a C program to scan the types - -my $includes = ""; -my $forward_decls = ""; -my $get_types = ""; -my $ntypes = 1; - -for () { - if (/^#include/) { - $includes .= $_; - } elsif (/^gnome_keyring_item_info_get_type$/) { - # HACK: This isn't really a GObject type so skip it. - next; - } elsif (/^%/) { - next; - } elsif (/^\s*$/) { - next; - } else { - chomp; - $get_types .= " object_types[i++] = $_ ();\n"; - $forward_decls .= "extern GType $_ (void);\n"; - $ntypes++; - } -} - -print OUTPUT < -#include -#include -#include -#include - -EOT - -if ($includes) { - print OUTPUT $includes; -} else { - print OUTPUT $forward_decls; -} - -if ($QUERY_CHILD_PROPERTIES) { - print OUTPUT < -#endif -static GType object_types[$ntypes]; - -static GType * -get_object_types (void) -{ - gpointer g_object_class; - gint i = 0; - -${get_types} - object_types[i] = G_TYPE_INVALID; - - /* reference the GObjectClass to initialize the param spec pool - * potentially needed by interfaces. See http://bugs.gnome.org/571820 */ - g_object_class = g_type_class_ref (G_TYPE_OBJECT); - - /* Need to make sure all the types are loaded in and initialize - * their signals and properties. - */ - for (i=0; object_types[i]; i++) { - if (G_TYPE_IS_CLASSED (object_types[i])) - g_type_class_ref (object_types[i]); - if (G_TYPE_IS_INTERFACE (object_types[i])) - g_type_default_interface_ref (object_types[i]); - } - - g_type_class_unref (g_object_class); - - return object_types; -} - -/* - * This uses GObject type functions to output signal prototypes and the object - * hierarchy. - */ - -/* The output files */ -const gchar *signals_filename = "$new_signals_filename"; -const gchar *hierarchy_filename = "$new_hierarchy_filename"; -const gchar *interfaces_filename = "$new_interfaces_filename"; -const gchar *prerequisites_filename = "$new_prerequisites_filename"; -const gchar *args_filename = "$new_args_filename"; - -static void output_signals (void); -static void output_object_signals (FILE *fp, - GType object_type); -static void output_object_signal (FILE *fp, - const gchar *object_class_name, - guint signal_id); -static const gchar * get_type_name (GType type, - gboolean * is_pointer); -static void output_object_hierarchy (void); -static void output_hierarchy (FILE *fp, - GType type, - guint level); - -static void output_object_interfaces (void); -static void output_interfaces (FILE *fp, - GType type); - -static void output_interface_prerequisites (void); -static void output_prerequisites (FILE *fp, - GType type); - -static void output_args (void); -static void output_object_args (FILE *fp, GType object_type); - -int -main (int argc, char *argv[]) -{ - $TYPE_INIT_FUNC; - - get_object_types (); - - output_signals (); - output_object_hierarchy (); - output_object_interfaces (); - output_interface_prerequisites (); - output_args (); - - return 0; -} - -static void -output_signals (void) -{ - FILE *fp; - gint i; - - fp = fopen (signals_filename, "w"); - if (fp == NULL) { - g_warning ("Couldn't open output file: %s : %s", signals_filename, g_strerror(errno)); - return; - } - - for (i = 0; object_types[i]; i++) - output_object_signals (fp, object_types[i]); - - fclose (fp); -} - -static gint -compare_signals (const void *a, const void *b) -{ - const guint *signal_a = a; - const guint *signal_b = b; - - return strcmp (g_signal_name (*signal_a), g_signal_name (*signal_b)); -} - -/* This outputs all the signals of one object. */ -static void -output_object_signals (FILE *fp, GType object_type) -{ - const gchar *object_class_name; - guint *signals, n_signals; - guint sig; - - if (G_TYPE_IS_INSTANTIATABLE (object_type) || - G_TYPE_IS_INTERFACE (object_type)) { - - object_class_name = g_type_name (object_type); - - signals = g_signal_list_ids (object_type, &n_signals); - qsort (signals, n_signals, sizeof (guint), compare_signals); - - for (sig = 0; sig < n_signals; sig++) { - output_object_signal (fp, object_class_name, signals[sig]); - } - g_free (signals); - } -} - -/* This outputs one signal. */ -static void -output_object_signal (FILE *fp, - const gchar *object_name, - guint signal_id) -{ - GSignalQuery query_info; - const gchar *type_name, *ret_type, *object_arg, *arg_name; - gchar *pos, *object_arg_lower; - gboolean is_pointer; - gchar buffer[1024]; - guint i, param; - gint param_num, widget_num, event_num, callback_num; - gint *arg_num; - gchar signal_name[128]; - gchar flags[16]; - - /* g_print ("Object: %s Signal: %u\\n", object_name, signal_id);*/ - - param_num = 1; - widget_num = event_num = callback_num = 0; - - g_signal_query (signal_id, &query_info); - - /* Output the signal object type and the argument name. We assume the - * type is a pointer - I think that is OK. We remove "Gtk" or "Gnome" and - * convert to lower case for the argument name. */ - pos = buffer; - sprintf (pos, "%s ", object_name); - pos += strlen (pos); - - /* Try to come up with a sensible variable name for the first arg - * It chops off 2 know prefixes :/ and makes the name lowercase - * It should replace lowercase -> uppercase with '_' - * GFileMonitor -> file_monitor - * GIOExtensionPoint -> extension_point - * GtkTreeView -> tree_view - * if 2nd char is upper case too - * search for first lower case and go back one char - * else - * search for next upper case - */ - if (!strncmp (object_name, "Gtk", 3)) - object_arg = object_name + 3; - else if (!strncmp (object_name, "Gnome", 5)) - object_arg = object_name + 5; - else - object_arg = object_name; - - object_arg_lower = g_ascii_strdown (object_arg, -1); - sprintf (pos, "*%s\\n", object_arg_lower); - pos += strlen (pos); - if (!strncmp (object_arg_lower, "widget", 6)) - widget_num = 2; - g_free(object_arg_lower); - - /* Convert signal name to use underscores rather than dashes '-'. */ - strncpy (signal_name, query_info.signal_name, 127); - signal_name[127] = '\\0'; - for (i = 0; signal_name[i]; i++) { - if (signal_name[i] == '-') - signal_name[i] = '_'; - } - - /* Output the signal parameters. */ - for (param = 0; param < query_info.n_params; param++) { - type_name = get_type_name (query_info.param_types[param] & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer); - - /* Most arguments to the callback are called "arg1", "arg2", etc. - GtkWidgets are called "widget", "widget2", ... - GtkCallbacks are called "callback", "callback2", ... */ - if (!strcmp (type_name, "GtkWidget")) { - arg_name = "widget"; - arg_num = &widget_num; - } - else if (!strcmp (type_name, "GtkCallback") - || !strcmp (type_name, "GtkCCallback")) { - arg_name = "callback"; - arg_num = &callback_num; - } - else { - arg_name = "arg"; - arg_num = ¶m_num; - } - sprintf (pos, "%s ", type_name); - pos += strlen (pos); - - if (!arg_num || *arg_num == 0) - sprintf (pos, "%s%s\\n", is_pointer ? "*" : " ", arg_name); - else - sprintf (pos, "%s%s%i\\n", is_pointer ? "*" : " ", arg_name, - *arg_num); - pos += strlen (pos); - - if (arg_num) { - if (*arg_num == 0) - *arg_num = 2; - else - *arg_num += 1; - } - } - - pos = flags; - /* We use one-character flags for simplicity. */ - if (query_info.signal_flags & G_SIGNAL_RUN_FIRST) - *pos++ = 'f'; - if (query_info.signal_flags & G_SIGNAL_RUN_LAST) - *pos++ = 'l'; - if (query_info.signal_flags & G_SIGNAL_RUN_CLEANUP) - *pos++ = 'c'; - if (query_info.signal_flags & G_SIGNAL_NO_RECURSE) - *pos++ = 'r'; - if (query_info.signal_flags & G_SIGNAL_DETAILED) - *pos++ = 'd'; - if (query_info.signal_flags & G_SIGNAL_ACTION) - *pos++ = 'a'; - if (query_info.signal_flags & G_SIGNAL_NO_HOOKS) - *pos++ = 'h'; - *pos = 0; - - /* Output the return type and function name. */ - ret_type = get_type_name (query_info.return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer); - - fprintf (fp, - "\\n%s::%s\\n%s%s\\n%s\\n%s\\n\\n", - object_name, query_info.signal_name, ret_type, is_pointer ? "*" : "", flags, buffer); -} - - -/* Returns the type name to use for a signal argument or return value, given - the GtkType from the signal info. It also sets is_pointer to TRUE if the - argument needs a '*' since it is a pointer. */ -static const gchar * -get_type_name (GType type, gboolean * is_pointer) -{ - const gchar *type_name; - - *is_pointer = FALSE; - type_name = g_type_name (type); - - switch (type) { - case G_TYPE_NONE: - case G_TYPE_CHAR: - case G_TYPE_UCHAR: - case G_TYPE_BOOLEAN: - case G_TYPE_INT: - case G_TYPE_UINT: - case G_TYPE_LONG: - case G_TYPE_ULONG: - case G_TYPE_FLOAT: - case G_TYPE_DOUBLE: - case G_TYPE_POINTER: - /* These all have normal C type names so they are OK. */ - return type_name; - - case G_TYPE_STRING: - /* A GtkString is really a gchar*. */ - *is_pointer = TRUE; - return "gchar"; - - case G_TYPE_ENUM: - case G_TYPE_FLAGS: - /* We use a gint for both of these. Hopefully a subtype with a decent - name will be registered and used instead, as GTK+ does itself. */ - return "gint"; - - case G_TYPE_BOXED: - /* The boxed type shouldn't be used itself, only subtypes. Though we - return 'gpointer' just in case. */ - return "gpointer"; - - case G_TYPE_PARAM: - /* A GParam is really a GParamSpec*. */ - *is_pointer = TRUE; - return "GParamSpec"; - -#if GLIB_CHECK_VERSION (2, 25, 9) - case G_TYPE_VARIANT: - *is_pointer = TRUE; - return "GVariant"; -#endif - -default: - break; - } - - /* For all GObject subclasses we can use the class name with a "*", - e.g. 'GtkWidget *'. */ - if (g_type_is_a (type, G_TYPE_OBJECT)) - *is_pointer = TRUE; - - /* Also catch non GObject root types */ - if (G_TYPE_IS_CLASSED (type)) - *is_pointer = TRUE; - - /* All boxed subtypes will be pointers as well. */ - /* Exception: GStrv */ - if (g_type_is_a (type, G_TYPE_BOXED) && - !g_type_is_a (type, G_TYPE_STRV)) - *is_pointer = TRUE; - - /* All pointer subtypes will be pointers as well. */ - if (g_type_is_a (type, G_TYPE_POINTER)) - *is_pointer = TRUE; - - /* But enums are not */ - if (g_type_is_a (type, G_TYPE_ENUM) || - g_type_is_a (type, G_TYPE_FLAGS)) - *is_pointer = FALSE; - - return type_name; -} - - -/* This outputs the hierarchy of all objects which have been initialized, - i.e. by calling their XXX_get_type() initialization function. */ -static void -output_object_hierarchy (void) -{ - FILE *fp; - gint i,j; - GType root, type; - GType root_types[$ntypes] = { G_TYPE_INVALID, }; - - fp = fopen (hierarchy_filename, "w"); - if (fp == NULL) { - g_warning ("Couldn't open output file: %s : %s", hierarchy_filename, g_strerror(errno)); - return; - } - output_hierarchy (fp, G_TYPE_OBJECT, 0); - output_hierarchy (fp, G_TYPE_INTERFACE, 0); - - for (i=0; object_types[i]; i++) { - root = object_types[i]; - while ((type = g_type_parent (root))) { - root = type; - } - if ((root != G_TYPE_OBJECT) && (root != G_TYPE_INTERFACE)) { - for (j=0; root_types[j]; j++) { - if (root == root_types[j]) { - root = G_TYPE_INVALID; break; - } - } - if(root) { - root_types[j] = root; - output_hierarchy (fp, root, 0); - } - } - } - - fclose (fp); -} - -/* This is called recursively to output the hierarchy of a object. */ -static void -output_hierarchy (FILE *fp, - GType type, - guint level) -{ - guint i; - GType *children; - guint n_children; - - if (!type) - return; - - for (i = 0; i < level; i++) - fprintf (fp, " "); - fprintf (fp, "%s\\n", g_type_name (type)); - - children = g_type_children (type, &n_children); - - for (i=0; i < n_children; i++) - output_hierarchy (fp, children[i], level + 1); - - g_free (children); -} - -static void output_object_interfaces (void) -{ - guint i; - FILE *fp; - - fp = fopen (interfaces_filename, "w"); - if (fp == NULL) { - g_warning ("Couldn't open output file: %s : %s", interfaces_filename, g_strerror(errno)); - return; - } - output_interfaces (fp, G_TYPE_OBJECT); - - for (i = 0; object_types[i]; i++) { - if (!g_type_parent (object_types[i]) && - (object_types[i] != G_TYPE_OBJECT) && - G_TYPE_IS_INSTANTIATABLE (object_types[i])) { - output_interfaces (fp, object_types[i]); - } - } - fclose (fp); -} - -static void -output_interfaces (FILE *fp, - GType type) -{ - guint i; - GType *children, *interfaces; - guint n_children, n_interfaces; - - if (!type) - return; - - interfaces = g_type_interfaces (type, &n_interfaces); - - if (n_interfaces > 0) { - fprintf (fp, "%s", g_type_name (type)); - for (i=0; i < n_interfaces; i++) - fprintf (fp, " %s", g_type_name (interfaces[i])); - fprintf (fp, "\\n"); - } - g_free (interfaces); - - children = g_type_children (type, &n_children); - - for (i=0; i < n_children; i++) - output_interfaces (fp, children[i]); - - g_free (children); -} - -static void output_interface_prerequisites (void) -{ - FILE *fp; - - fp = fopen (prerequisites_filename, "w"); - if (fp == NULL) { - g_warning ("Couldn't open output file: %s : %s", prerequisites_filename, g_strerror(errno)); - return; - } - output_prerequisites (fp, G_TYPE_INTERFACE); - fclose (fp); -} - -static void -output_prerequisites (FILE *fp, - GType type) -{ -#if GLIB_CHECK_VERSION(2,1,0) - guint i; - GType *children, *prerequisites; - guint n_children, n_prerequisites; - - if (!type) - return; - - prerequisites = g_type_interface_prerequisites (type, &n_prerequisites); - - if (n_prerequisites > 0) { - fprintf (fp, "%s", g_type_name (type)); - for (i=0; i < n_prerequisites; i++) - fprintf (fp, " %s", g_type_name (prerequisites[i])); - fprintf (fp, "\\n"); - } - g_free (prerequisites); - - children = g_type_children (type, &n_children); - - for (i=0; i < n_children; i++) - output_prerequisites (fp, children[i]); - - g_free (children); -#endif -} - -static void -output_args (void) -{ - FILE *fp; - gint i; - - fp = fopen (args_filename, "w"); - if (fp == NULL) { - g_warning ("Couldn't open output file: %s : %s", args_filename, g_strerror(errno)); - return; - } - - for (i = 0; object_types[i]; i++) { - output_object_args (fp, object_types[i]); - } - - fclose (fp); -} - -static gint -compare_param_specs (const void *a, const void *b) -{ - GParamSpec *spec_a = *(GParamSpec **)a; - GParamSpec *spec_b = *(GParamSpec **)b; - - return strcmp (g_param_spec_get_name (spec_a), g_param_spec_get_name (spec_b)); -} - -/* Its common to have unsigned properties restricted - * to the signed range. Therefore we make this look - * a bit nicer by spelling out the max constants. - */ - -/* Don't use "==" with floats, it might trigger a gcc warning. */ -#define GTKDOC_COMPARE_FLOAT(x, y) (x <= y && x >= y) - -static gchar* -describe_double_constant (gdouble value) -{ - gchar *desc; - - if (GTKDOC_COMPARE_FLOAT (value, G_MAXDOUBLE)) - desc = g_strdup ("G_MAXDOUBLE"); - else if (GTKDOC_COMPARE_FLOAT (value, G_MINDOUBLE)) - desc = g_strdup ("G_MINDOUBLE"); - else if (GTKDOC_COMPARE_FLOAT (value, -G_MAXDOUBLE)) - desc = g_strdup ("-G_MAXDOUBLE"); - else if (GTKDOC_COMPARE_FLOAT (value, G_MAXFLOAT)) - desc = g_strdup ("G_MAXFLOAT"); - else if (GTKDOC_COMPARE_FLOAT (value, G_MINFLOAT)) - desc = g_strdup ("G_MINFLOAT"); - else if (GTKDOC_COMPARE_FLOAT (value, -G_MAXFLOAT)) - desc = g_strdup ("-G_MAXFLOAT"); - else{ - /* make sure floats are output with a decimal dot irrespective of - * current locale. Use formatd since we want human-readable numbers - * and do not need the exact same bit representation when deserialising */ - desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE); - g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g", value); - } - - return desc; -} - -static gchar* -describe_signed_constant (gsize size, gint64 value) -{ - gchar *desc = NULL; - - switch (size) { - case 2: - if (sizeof (int) == 2) { - if (value == G_MAXINT) - desc = g_strdup ("G_MAXINT"); - else if (value == G_MININT) - desc = g_strdup ("G_MININT"); - } - break; - case 4: - if (sizeof (int) == 4) { - if (value == G_MAXINT) - desc = g_strdup ("G_MAXINT"); - else if (value == G_MININT) - desc = g_strdup ("G_MININT"); - } - if (value == G_MAXLONG) - desc = g_strdup ("G_MAXLONG"); - else if (value == G_MINLONG) - desc = g_strdup ("G_MINLONG"); - break; - case 8: - if (value == G_MAXINT64) - desc = g_strdup ("G_MAXINT64"); - else if (value == G_MININT64) - desc = g_strdup ("G_MININT64"); - break; - default: - break; - } - if (!desc) - desc = g_strdup_printf ("%" G_GINT64_FORMAT, value); - - return desc; -} - -static gchar* -describe_unsigned_constant (gsize size, guint64 value) -{ - gchar *desc = NULL; - - switch (size) { - case 2: - if (sizeof (int) == 2) { - if (value == (guint64)G_MAXINT) - desc = g_strdup ("G_MAXINT"); - else if (value == G_MAXUINT) - desc = g_strdup ("G_MAXUINT"); - } - break; - case 4: - if (sizeof (int) == 4) { - if (value == (guint64)G_MAXINT) - desc = g_strdup ("G_MAXINT"); - else if (value == G_MAXUINT) - desc = g_strdup ("G_MAXUINT"); - } - if (value == (guint64)G_MAXLONG) - desc = g_strdup ("G_MAXLONG"); - else if (value == G_MAXULONG) - desc = g_strdup ("G_MAXULONG"); - break; - case 8: - if (value == G_MAXINT64) - desc = g_strdup ("G_MAXINT64"); - else if (value == G_MAXUINT64) - desc = g_strdup ("G_MAXUINT64"); - break; - default: - break; - } - if (!desc) - desc = g_strdup_printf ("%" G_GUINT64_FORMAT, value); - - return desc; -} - -static gchar* -describe_type (GParamSpec *spec) -{ - gchar *desc; - gchar *lower; - gchar *upper; - - if (G_IS_PARAM_SPEC_CHAR (spec)) { - GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec); - - lower = describe_signed_constant (sizeof(gchar), pspec->minimum); - upper = describe_signed_constant (sizeof(gchar), pspec->maximum); - if (pspec->minimum == G_MININT8 && pspec->maximum == G_MAXINT8) - desc = g_strdup (""); - else if (pspec->minimum == G_MININT8) - desc = g_strdup_printf ("<= %s", upper); - else if (pspec->maximum == G_MAXINT8) - desc = g_strdup_printf (">= %s", lower); - else - desc = g_strdup_printf ("[%s,%s]", lower, upper); - g_free (lower); - g_free (upper); - } - else if (G_IS_PARAM_SPEC_UCHAR (spec)) { - GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec); - - lower = describe_unsigned_constant (sizeof(guchar), pspec->minimum); - upper = describe_unsigned_constant (sizeof(guchar), pspec->maximum); - if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT8) - desc = g_strdup (""); - else if (pspec->minimum == 0) - desc = g_strdup_printf ("<= %s", upper); - else if (pspec->maximum == G_MAXUINT8) - desc = g_strdup_printf (">= %s", lower); - else - desc = g_strdup_printf ("[%s,%s]", lower, upper); - g_free (lower); - g_free (upper); - } - else if (G_IS_PARAM_SPEC_INT (spec)) { - GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec); - - lower = describe_signed_constant (sizeof(gint), pspec->minimum); - upper = describe_signed_constant (sizeof(gint), pspec->maximum); - if (pspec->minimum == G_MININT && pspec->maximum == G_MAXINT) - desc = g_strdup (""); - else if (pspec->minimum == G_MININT) - desc = g_strdup_printf ("<= %s", upper); - else if (pspec->maximum == G_MAXINT) - desc = g_strdup_printf (">= %s", lower); - else - desc = g_strdup_printf ("[%s,%s]", lower, upper); - g_free (lower); - g_free (upper); - } - else if (G_IS_PARAM_SPEC_UINT (spec)) { - GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec); - - lower = describe_unsigned_constant (sizeof(guint), pspec->minimum); - upper = describe_unsigned_constant (sizeof(guint), pspec->maximum); - if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT) - desc = g_strdup (""); - else if (pspec->minimum == 0) - desc = g_strdup_printf ("<= %s", upper); - else if (pspec->maximum == G_MAXUINT) - desc = g_strdup_printf (">= %s", lower); - else - desc = g_strdup_printf ("[%s,%s]", lower, upper); - g_free (lower); - g_free (upper); - } - else if (G_IS_PARAM_SPEC_LONG (spec)) { - GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec); - - lower = describe_signed_constant (sizeof(glong), pspec->minimum); - upper = describe_signed_constant (sizeof(glong), pspec->maximum); - if (pspec->minimum == G_MINLONG && pspec->maximum == G_MAXLONG) - desc = g_strdup (""); - else if (pspec->minimum == G_MINLONG) - desc = g_strdup_printf ("<= %s", upper); - else if (pspec->maximum == G_MAXLONG) - desc = g_strdup_printf (">= %s", lower); - else - desc = g_strdup_printf ("[%s,%s]", lower, upper); - g_free (lower); - g_free (upper); - } - else if (G_IS_PARAM_SPEC_ULONG (spec)) { - GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec); - - lower = describe_unsigned_constant (sizeof(gulong), pspec->minimum); - upper = describe_unsigned_constant (sizeof(gulong), pspec->maximum); - if (pspec->minimum == 0 && pspec->maximum == G_MAXULONG) - desc = g_strdup (""); - else if (pspec->minimum == 0) - desc = g_strdup_printf ("<= %s", upper); - else if (pspec->maximum == G_MAXULONG) - desc = g_strdup_printf (">= %s", lower); - else - desc = g_strdup_printf ("[%s,%s]", lower, upper); - g_free (lower); - g_free (upper); - } - else if (G_IS_PARAM_SPEC_INT64 (spec)) { - GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec); - - lower = describe_signed_constant (sizeof(gint64), pspec->minimum); - upper = describe_signed_constant (sizeof(gint64), pspec->maximum); - if (pspec->minimum == G_MININT64 && pspec->maximum == G_MAXINT64) - desc = g_strdup (""); - else if (pspec->minimum == G_MININT64) - desc = g_strdup_printf ("<= %s", upper); - else if (pspec->maximum == G_MAXINT64) - desc = g_strdup_printf (">= %s", lower); - else - desc = g_strdup_printf ("[%s,%s]", lower, upper); - g_free (lower); - g_free (upper); - } - else if (G_IS_PARAM_SPEC_UINT64 (spec)) { - GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec); - - lower = describe_unsigned_constant (sizeof(guint64), pspec->minimum); - upper = describe_unsigned_constant (sizeof(guint64), pspec->maximum); - if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT64) - desc = g_strdup (""); - else if (pspec->minimum == 0) - desc = g_strdup_printf ("<= %s", upper); - else if (pspec->maximum == G_MAXUINT64) - desc = g_strdup_printf (">= %s", lower); - else - desc = g_strdup_printf ("[%s,%s]", lower, upper); - g_free (lower); - g_free (upper); - } - else if (G_IS_PARAM_SPEC_FLOAT (spec)) { - GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec); - - lower = describe_double_constant (pspec->minimum); - upper = describe_double_constant (pspec->maximum); - if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXFLOAT)) { - if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT)) - desc = g_strdup (""); - else - desc = g_strdup_printf ("<= %s", upper); - } - else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT)) - desc = g_strdup_printf (">= %s", lower); - else - desc = g_strdup_printf ("[%s,%s]", lower, upper); - g_free (lower); - g_free (upper); - } - else if (G_IS_PARAM_SPEC_DOUBLE (spec)) { - GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec); - - lower = describe_double_constant (pspec->minimum); - upper = describe_double_constant (pspec->maximum); - if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXDOUBLE)) { - if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE)) - desc = g_strdup (""); - else - desc = g_strdup_printf ("<= %s", upper); - } - else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE)) - desc = g_strdup_printf (">= %s", lower); - else - desc = g_strdup_printf ("[%s,%s]", lower, upper); - g_free (lower); - g_free (upper); - } -#if GLIB_CHECK_VERSION (2, 12, 0) - else if (G_IS_PARAM_SPEC_GTYPE (spec)) { - GParamSpecGType *pspec = G_PARAM_SPEC_GTYPE (spec); - gboolean is_pointer; - - desc = g_strdup (get_type_name (pspec->is_a_type, &is_pointer)); - } -#endif -#if GLIB_CHECK_VERSION (2, 25, 9) - else if (G_IS_PARAM_SPEC_VARIANT (spec)) { - GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec); - gchar *variant_type; - - variant_type = g_variant_type_dup_string (pspec->type); - desc = g_strdup_printf ("GVariant<%s>", variant_type); - g_free (variant_type); - } -#endif - else { - desc = g_strdup (""); - } - - return desc; -} - -static gchar* -describe_default (GParamSpec *spec) -{ - gchar *desc; - - if (G_IS_PARAM_SPEC_CHAR (spec)) { - GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec); - - desc = g_strdup_printf ("%d", pspec->default_value); - } - else if (G_IS_PARAM_SPEC_UCHAR (spec)) { - GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec); - - desc = g_strdup_printf ("%u", pspec->default_value); - } - else if (G_IS_PARAM_SPEC_BOOLEAN (spec)) { - GParamSpecBoolean *pspec = G_PARAM_SPEC_BOOLEAN (spec); - - desc = g_strdup_printf ("%s", pspec->default_value ? "TRUE" : "FALSE"); - } - else if (G_IS_PARAM_SPEC_INT (spec)) { - GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec); - - desc = g_strdup_printf ("%d", pspec->default_value); - } - else if (G_IS_PARAM_SPEC_UINT (spec)) { - GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec); - - desc = g_strdup_printf ("%u", pspec->default_value); - } - else if (G_IS_PARAM_SPEC_LONG (spec)) { - GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec); - - desc = g_strdup_printf ("%ld", pspec->default_value); - } - else if (G_IS_PARAM_SPEC_LONG (spec)) { - GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec); - - desc = g_strdup_printf ("%lu", pspec->default_value); - } - else if (G_IS_PARAM_SPEC_INT64 (spec)) { - GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec); - - desc = g_strdup_printf ("%" G_GINT64_FORMAT, pspec->default_value); - } - else if (G_IS_PARAM_SPEC_UINT64 (spec)) - { - GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec); - - desc = g_strdup_printf ("%" G_GUINT64_FORMAT, pspec->default_value); - } - else if (G_IS_PARAM_SPEC_UNICHAR (spec)) { - GParamSpecUnichar *pspec = G_PARAM_SPEC_UNICHAR (spec); - - if (g_unichar_isprint (pspec->default_value)) - desc = g_strdup_printf ("'%c'", pspec->default_value); - else - desc = g_strdup_printf ("%u", pspec->default_value); - } - else if (G_IS_PARAM_SPEC_ENUM (spec)) { - GParamSpecEnum *pspec = G_PARAM_SPEC_ENUM (spec); - - GEnumValue *value = g_enum_get_value (pspec->enum_class, pspec->default_value); - if (value) - desc = g_strdup_printf ("%s", value->value_name); - else - desc = g_strdup_printf ("%d", pspec->default_value); - } - else if (G_IS_PARAM_SPEC_FLAGS (spec)) { - GParamSpecFlags *pspec = G_PARAM_SPEC_FLAGS (spec); - guint default_value; - GString *acc; - - default_value = pspec->default_value; - acc = g_string_new (""); - - while (default_value) { - GFlagsValue *value = g_flags_get_first_value (pspec->flags_class, default_value); - - if (!value) - break; - - if (acc->len > 0) - g_string_append (acc, " | "); - g_string_append (acc, value->value_name); - - default_value &= ~value->value; - } - - if (default_value == 0) - desc = g_string_free (acc, FALSE); - else { - desc = g_strdup_printf ("%d", pspec->default_value); - g_string_free (acc, TRUE); - } - } - else if (G_IS_PARAM_SPEC_FLOAT (spec)) { - GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec); - - /* make sure floats are output with a decimal dot irrespective of - * current locale. Use formatd since we want human-readable numbers - * and do not need the exact same bit representation when deserialising */ - desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE); - g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g", - pspec->default_value); - } - else if (G_IS_PARAM_SPEC_DOUBLE (spec)) { - GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec); - - /* make sure floats are output with a decimal dot irrespective of - * current locale. Use formatd since we want human-readable numbers - * and do not need the exact same bit representation when deserialising */ - desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE); - g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g", - pspec->default_value); - } - else if (G_IS_PARAM_SPEC_STRING (spec)) { - GParamSpecString *pspec = G_PARAM_SPEC_STRING (spec); - - if (pspec->default_value) { - gchar *esc = g_strescape (pspec->default_value, NULL); - desc = g_strdup_printf ("\\"%s\\"", esc); - g_free (esc); - } - else - desc = g_strdup_printf ("NULL"); - } -#if GLIB_CHECK_VERSION (2, 25, 9) - else if (G_IS_PARAM_SPEC_VARIANT (spec)) { - GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec); - - if (pspec->default_value) - desc = g_variant_print (pspec->default_value, TRUE); - else - desc = g_strdup ("NULL"); - } -#endif - else { - desc = g_strdup (""); - } - - return desc; -} - - -static void -output_object_args (FILE *fp, GType object_type) -{ - gpointer class; - const gchar *object_class_name; - guint arg; - gchar flags[16], *pos; - GParamSpec **properties; - guint n_properties; - gboolean child_prop; - gboolean style_prop; - gboolean is_pointer; - const gchar *type_name; - gchar *type_desc; - gchar *default_value; - - if (G_TYPE_IS_OBJECT (object_type)) { - class = g_type_class_peek (object_type); - if (!class) - return; - - properties = g_object_class_list_properties (class, &n_properties); - } -#if GLIB_MAJOR_VERSION > 2 || (GLIB_MAJOR_VERSION == 2 && GLIB_MINOR_VERSION >= 3) - else if (G_TYPE_IS_INTERFACE (object_type)) { - class = g_type_default_interface_ref (object_type); - - if (!class) - return; - - properties = g_object_interface_list_properties (class, &n_properties); - } -#endif - else - return; - - object_class_name = g_type_name (object_type); - - child_prop = FALSE; - style_prop = FALSE; - - while (TRUE) { - qsort (properties, n_properties, sizeof (GParamSpec *), compare_param_specs); - for (arg = 0; arg < n_properties; arg++) { - GParamSpec *spec = properties[arg]; - const gchar *nick, *blurb, *dot; - - if (spec->owner_type != object_type) - continue; - - pos = flags; - /* We use one-character flags for simplicity. */ - if (child_prop && !style_prop) - *pos++ = 'c'; - if (style_prop) - *pos++ = 's'; - if (spec->flags & G_PARAM_READABLE) - *pos++ = 'r'; - if (spec->flags & G_PARAM_WRITABLE) - *pos++ = 'w'; - if (spec->flags & G_PARAM_CONSTRUCT) - *pos++ = 'x'; - if (spec->flags & G_PARAM_CONSTRUCT_ONLY) - *pos++ = 'X'; - *pos = 0; - - nick = g_param_spec_get_nick (spec); - blurb = g_param_spec_get_blurb (spec); - - dot = ""; - if (blurb) { - int str_len = strlen (blurb); - if (str_len > 0 && blurb[str_len - 1] != '.') - dot = "."; - } - - type_desc = describe_type (spec); - default_value = describe_default (spec); - type_name = get_type_name (spec->value_type, &is_pointer); - fprintf (fp, "\\n%s::%s\\n%s%s\\n%s\\n%s\\n%s\\n%s%s\\n%s\\n\\n\\n", - object_class_name, g_param_spec_get_name (spec), type_name, is_pointer ? "*" : "", type_desc, flags, nick ? nick : "(null)", blurb ? blurb : "(null)", dot, default_value); - g_free (type_desc); - g_free (default_value); - } - - g_free (properties); - -#ifdef GTK_IS_CONTAINER_CLASS - if (!child_prop && GTK_IS_CONTAINER_CLASS (class)) { - properties = gtk_container_class_list_child_properties (class, &n_properties); - child_prop = TRUE; - continue; - } -#endif - -#ifdef GTK_IS_CELL_AREA_CLASS - if (!child_prop && GTK_IS_CELL_AREA_CLASS (class)) { - properties = gtk_cell_area_class_list_cell_properties (class, &n_properties); - child_prop = TRUE; - continue; - } -#endif - -#ifdef GTK_IS_WIDGET_CLASS -#if GTK_CHECK_VERSION(2,1,0) - if (!style_prop && GTK_IS_WIDGET_CLASS (class)) { - properties = gtk_widget_class_list_style_properties (GTK_WIDGET_CLASS (class), &n_properties); - style_prop = TRUE; - continue; - } -#endif -#endif - -EOT - -if ($QUERY_CHILD_PROPERTIES) { - print OUTPUT < 0) + (undeclared != 0) + (unused != 0) + (missing_includes != 0) + rate = 100.0 * (checks - failed) / checks + print("%.1f%%: Checks %d, Failures: %d" % (rate, checks, failed)) + return failed + + +def run(options=None): + """Runs the tests. + + Returns: + int: a system exit code. + """ + + # Get parameters from test env, if not there try to grab them from the makefile + # We like Makefile.am more but builddir does not necessarily contain one. + makefilename = 'Makefile.am' + if not os.path.exists(makefilename): + makefilename = 'Makefile' + makefile = read_file(makefilename) + + # For historic reasons tests are launched in srcdir + workdir = os.environ.get('BUILDDIR', None) + if not workdir: + workdir = '.' + + try: + doc_module = get_variable(os.environ, makefile, 'DOC_MODULE') + doc_main_file = get_variable(os.environ, makefile, 'DOC_MAIN_SGML_FILE') + except FileFormatError as e: + print('Cannot find %s in %s' % (str(e), makefilename)) + return 1 + + doc_main_file = doc_main_file.replace('$(DOC_MODULE)', doc_module) + + return run_tests(workdir, doc_module, doc_main_file) diff --git a/gtkdoc/common.py b/gtkdoc/common.py new file mode 100644 index 0000000..470722e --- /dev/null +++ b/gtkdoc/common.py @@ -0,0 +1,577 @@ +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2001 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +# Support both Python 2 and 3 +from __future__ import print_function + +from collections import OrderedDict +import logging +import os +import re +import subprocess +import sys + +from . import config + + +def setup_logging(): + """Check GTKDOC_TRACE environment variable. + + Set python log level to the value of the environment variable (DEBUG, INFO, + WARNING, ERROR and CRITICAL) or INFO if the environment variable is empty. + """ + log_level = os.environ.get('GTKDOC_TRACE') + if log_level == '': + log_level = 'INFO' + if log_level: + logging.basicConfig(stream=sys.stdout, + level=logging.getLevelName(log_level.upper()), + format='%(asctime)s:%(filename)s:%(funcName)s:%(lineno)d:%(levelname)s:%(message)s') + # When redirecting the output on python2 we get UnicodeEncodeError: + if not sys.stdout.encoding: + import codecs + sys.stdout = codecs.getwriter('utf8')(sys.stdout) + + +def UpdateFileIfChanged(old_file, new_file, make_backup): + """Compares the old version of the file with the new version and if the + file has changed it moves the new version into the old versions place. This + is used so we only change files if needed, so we can do proper dependency + tracking. + + Args: + old_file (str): The pathname of the old file. + new_file (str): The pathname of the new version of the file. + make_backup (bool): True if a backup of the old file should be kept. + It will have the .bak suffix added to the file name. + + Returns: + bool: It returns False if the file hasn't changed, and True if it has. + """ + + logging.debug("Comparing %s with %s...", old_file, new_file) + + if os.path.exists(old_file): + old_contents = open(old_file, 'rb').read() + new_contents = open(new_file, 'rb').read() + if old_contents == new_contents: + os.unlink(new_file) + logging.debug("-> content is the same.") + return False + + if make_backup: + backupname = old_file + '.bak' + if os.path.exists(backupname): + os.unlink(backupname) + os.rename(old_file, backupname) + else: + os.unlink(old_file) + logging.debug("-> content differs.") + else: + logging.debug("-> %s created.", old_file) + + os.rename(new_file, old_file) + return True + + +def GetModuleDocDir(module_name): + """Get the docdir for the given module via pkg-config + + Args: + module_name (string): The module, e.g. 'glib-2.0' + + Returns: + str: the doc directory + """ + path = subprocess.check_output([config.pkg_config, '--variable=prefix', module_name], universal_newlines=True) + return os.path.join(path.strip(), 'share/gtk-doc/html') + + +def LogWarning(filename, line, message): + """Log a warning in gcc style format + + Args: + file (str): The file the error comes from + line (int): line number in the file + message (str): the error message to print + """ + filename = filename or "unknown" + + # TODO: write to stderr + print ("%s:%d: warning: %s" % (filename, line, message)) + + +def CreateValidSGMLID(xml_id): + """Creates a valid SGML 'id' from the given string. + + According to http://www.w3.org/TR/html4/types.html#type-id "ID and NAME + tokens must begin with a letter ([A-Za-z]) and may be followed by any number + of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), + and periods (".")." + + When creating SGML IDS, we append ":CAPS" to all all-caps identifiers to + prevent name clashes (SGML ids are case-insensitive). (It basically never is + the case that mixed-case identifiers would collide.) + + Args: + id (str): The text to be converted into a valid SGML id. + + Returns: + str: The converted id. + """ + + # Special case, '_' would end up as '' so we use 'gettext-macro' instead. + if xml_id == '_': + return "gettext-macro" + + xml_id = re.sub(r'[,;]', '', xml_id) + xml_id = re.sub(r'[_ ]', '-', xml_id) + xml_id = re.sub(r'^-+', '', xml_id) + xml_id = xml_id.replace('::', '-') + xml_id = xml_id.replace(':', '--') + + # Append ":CAPS" to all all-caps identifiers + # FIXME: there are some inconsistencies here, we have index files containing e.g. TRUE--CAPS + if xml_id.isupper() and not xml_id.endswith('-CAPS'): + xml_id += ':CAPS' + + return xml_id + + +# Parsing helpers (move to mkdb ?) + +class ParseError(Exception): + pass + + +def PreprocessStructOrEnum(declaration): + """Trim a type declaration for display. + + Removes private sections and comments from the declaration. + + Args: + declaration (str): the type declaration (struct or enum) + + Returns: + str: the trimmed declaration + """ + # Remove private symbols + # Assume end of declaration if line begins with '}' + declaration = re.sub(r'\n?[ \t]*/\*\s*<\s*(private|protected)\s*>\s*\*/.*?(?:/\*\s*<\s*public\s*>\s*\*/|(?=^\}))', + '', declaration, flags=re.MULTILINE | re.DOTALL) + + # Remove all other comments + declaration = re.sub(r'\n\s*/\*.*?\*/\s*\n', r'\n', declaration, flags=re.MULTILINE | re.DOTALL) + declaration = re.sub(r'/\*([^*]+|\*(?!/))*\*/', r' ', declaration) + declaration = re.sub(r'\n\s*//.*?\n', r'\n', declaration, flags=re.MULTILINE | re.DOTALL) + declaration = re.sub(r'//.*', '', declaration) + + return declaration + + +# TODO: output_function_params is always passed as 0 +# TODO: we always pass both functions +def ParseStructDeclaration(declaration, is_object, output_function_params, typefunc=None, namefunc=None): + """ Parse a struct declaration. + + Takes a structure declaration and breaks it into individual type declarations. + + Args: + declaration (str): the declaration to parse + is_object (bool): true if this is an object structure + output_function_params (bool): true if full type is wanted for function pointer members + typefunc (func): function to apply to type + namefunc (func): function to apply to name + + Returns: + dict: map of (symbol, decl) pairs describing the public declaration + """ + + # For forward struct declarations just return an empty array. + if re.search(r'(?:struct|union)\s+\S+\s*;', declaration, flags=re.MULTILINE | re.DOTALL): + return {} + + # Remove all private parts of the declaration + # For objects, assume private + if is_object: + declaration = re.sub(r'''((?:struct|union)\s+\w*\s*\{) + .*? + (?:/\*\s*<\s*public\s*>\s*\*/|(?=\}))''', + r'\1', declaration, flags=re.MULTILINE | re.DOTALL | re.VERBOSE) + + # Remove g_iface, parent_instance and parent_class if they are first member + declaration = re.sub(r'(\{)\s*(\w)+\s+(g_iface|parent_instance|parent_class)\s*;', r'\1', declaration) + + declaration = PreprocessStructOrEnum(declaration) + + if declaration.strip() == '': + return {} + + # Prime match after "struct/union {" declaration + match = re.search(r'(?:struct|union)\s+\w*\s*\{', declaration, flags=re.MULTILINE | re.DOTALL) + if not match: + raise ParseError('Declaration "%s" does not begin with "struct/union [NAME] {"' % declaration) + + logging.debug('public fields in struct/union: %s', declaration) + + result = OrderedDict() + + # Treat lines in sequence, allowing singly nested anonymous structs and unions. + for m in re.finditer(r'\s*([^{;]+(\{[^\}]*\}[^{;]+)?);', declaration[match.end():], flags=re.MULTILINE | re.DOTALL): + line = m.group(1) + + logging.debug('checking "%s"', line) + + if re.search(r'^\s*\}\s*\w*\s*$', line): + break + + # FIXME: Just ignore nested structs and unions for now + if '{' in line: + continue + + # ignore preprocessor directives + line = re.sub(r'^#.*?\n\s*', '', line, flags=re.MULTILINE | re.DOTALL) + + if re.search(r'^\s*\}\s*\w*\s*$', line): + break + + func_match = re.search(r'''^ + (const\s+|G_CONST_RETURN\s+|unsigned\s+|signed\s+|long\s+|short\s+)*(struct\s+|enum\s+)? # mod1 + (\w+)\s* # type + (\**(?:\s*restrict)?)\s* # ptr1 + (const\s+)? # mod2 + (\**\s*) # ptr2 + (const\s+)? # mod3 + \(\s*\*\s*(\w+)\s*\)\s* # name + \(([^)]*)\)\s* # func_params + $''', line, flags=re.VERBOSE) + vars_match = re.search(r'''^ + ((?:const\s+|volatile\s+|unsigned\s+|signed\s+|short\s+|long\s+)?)(struct\s+|enum\s+)? # mod1 + (\w+)\s* # type + (\** \s* const\s+)? # mod2 + (.*) # variables + $''', line, flags=re.VERBOSE) + + # Try to match structure members which are functions + if func_match: + mod1 = func_match.group(1) or '' + if func_match.group(2): + mod1 += func_match.group(2) + func_type = func_match.group(3) + ptr1 = func_match.group(4) + mod2 = func_match.group(5) or '' + ptr2 = func_match.group(6) + mod3 = func_match.group(7) or '' + name = func_match.group(8) + func_params = func_match.group(9) + ptype = func_type + if typefunc: + ptype = typefunc(func_type, '%s' % func_type) + pname = name + if namefunc: + pname = namefunc(name) + + if output_function_params: + result[name] = '%s%s%s%s%s%s (*%s) (%s)' % ( + mod1, ptype, ptr1, mod2, ptr2, mod3, pname, func_params) + else: + result[name] = '%s ()' % pname + + # Try to match normal struct fields of comma-separated variables/ + elif vars_match: + mod1 = vars_match.group(1) or '' + if vars_match.group(2): + mod1 += vars_match.group(2) + vtype = vars_match.group(3) + ptype = vtype + if typefunc: + ptype = typefunc(vtype, '%s' % vtype) + mod2 = vars_match.group(4) or '' + if mod2: + mod2 = ' ' + mod2 + var_list = vars_match.group(5) + + logging.debug('"%s" "%s" "%s" "%s"', mod1, vtype, mod2, var_list) + + mod1 = mod1.replace(' ', ' ') + mod2 = mod2.replace(' ', ' ') + + for n in var_list.split(','): + # Each variable can have any number of '*' before the identifier, + # and be followed by any number of pairs of brackets or a bit field specifier. + # e.g. *foo, ***bar, *baz[12][23], foo : 25. + m = re.search( + r'^\s* (\**(?:\s*restrict\b)?) \s* (\w+) \s* (?: ((?:\[[^\]]*\]\s*)+) | (:\s*\d+)?) \s* $', + n, flags=re.VERBOSE) + if m: + ptrs = m.group(1) + name = m.group(2) + array = m.group(3) or '' + bits = m.group(4) + if bits: + bits = ' ' + bits + else: + bits = '' + if ptrs and not ptrs.endswith('*'): + ptrs += ' ' + + array = array.replace(' ', ' ') + bits = bits.replace(' ', ' ') + + pname = name + if namefunc: + pname = namefunc(name) + + result[name] = '%s%s%s %s%s%s%s;' % (mod1, ptype, mod2, ptrs, pname, array, bits) + + logging.debug('Matched line: %s%s%s %s%s%s%s', mod1, ptype, mod2, ptrs, pname, array, bits) + else: + logging.warning('Cannot parse struct field: "%s"', n) + + else: + logging.warning('Cannot parse structure field: "%s"', line) + + return result + + +def ParseEnumDeclaration(declaration): + """Parse an enum declaration. + + This function takes a enumeration declaration and breaks it into individual + enum member declarations. + + Args: + declaration (str): the declaration to parse + + Returns: + str: list of strings describing the public declaration + """ + + # For forward struct declarations just return an empty array. + if re.search(r'enum\s+\S+\s*;', declaration, flags=re.MULTILINE | re.DOTALL): + return () + + declaration = PreprocessStructOrEnum(declaration) + + if declaration.strip() == '': + return () + + result = [] + + # Remove parenthesized expressions (in macros like GTK_BLAH = BLAH(1,3)) + # to avoid getting confused by commas they might contain. This doesn't + # handle nested parentheses correctly. + declaration = re.sub(r'\([^)\n]+\)', '', declaration) + + # Remove apostrophed characters (e.g. '}' or ',') values to avoid getting + # confused with end of enumeration. + # See https://bugzilla.gnome.org/show_bug.cgi?id=741305 + declaration = re.sub(r'\'.\'', '', declaration) + + # Remove comma from comma - possible whitespace - closing brace sequence + # since it is legal in GNU C and C99 to have a trailing comma but doesn't + # result in an actual enum member + declaration = re.sub(r',(\s*})', r'\1', declaration) + + # Prime match after "typedef enum {" declaration + match = re.search(r'(typedef\s+)?enum\s*(\S+\s*)?\{', declaration, flags=re.MULTILINE | re.DOTALL) + if not match: + raise ParseError('Enum declaration "%s" does not begin with "typedef enum {" or "enum [NAME] {"' % declaration) + + logging.debug("public fields in enum: %s'", declaration) + + # Treat lines in sequence. + for m in re.finditer(r'\s*([^,\}]+)([,\}])', declaration[match.end():], flags=re.MULTILINE | re.DOTALL): + line = m.group(1) + terminator = m.group(2) + + # ignore preprocessor directives + line = re.sub(r'^#.*?\n\s*', '', line, flags=re.MULTILINE | re.DOTALL) + + m1 = re.search(r'^(\w+)\s*(=.*)?$', line, flags=re.MULTILINE | re.DOTALL) + # Special case for GIOCondition, where the values are specified by + # macros which expand to include the equal sign like '=1'. + m2 = re.search(r'^(\w+)\s*GLIB_SYSDEF_POLL', line, flags=re.MULTILINE | re.DOTALL) + if m1: + result.append(m1.group(1)) + elif m2: + result.append(m2.group(1)) + elif line.strip().startswith('#'): + # Special case include of , just ignore it + # Special case for #ifdef/#else/#endif, just ignore it + break + else: + logging.warning('Cannot parse enumeration member: %s', line) + + if terminator == '}': + break + + return result + + +def ParseFunctionDeclaration(declaration, typefunc, namefunc): + """Parse a function declaration. + + This function takes a function declaration and breaks it into individual + parameter declarations. + + Args: + declaration (str): the declaration to parse + typefunc (func): function to apply to type + namefunc (func): function to apply to name + + Returns: + dict: map of (symbol, decl) pairs describing the prototype + """ + + result = OrderedDict() + + param_num = 0 + while declaration: + logging.debug('decl=[%s]', declaration) + + # skip whitespace and commas + declaration, n = re.subn(r'^[\s,]+', '', declaration) + if n: + continue + + declaration, n = re.subn(r'^void\s*[,\n]', '', declaration) + if n: + if param_num != 0: + logging.warning('void used as parameter %d in function %s', param_num, declaration) + result['void'] = namefunc('void') + param_num += 1 + continue + + declaration, n = re.subn(r'^\s*[_a-zA-Z0-9]*\.\.\.\s*[,\n]', '', declaration) + if n: + result['...'] = namefunc('...') + param_num += 1 + continue + + # allow alphanumerics, '_', '[' & ']' in param names, try to match a standard parameter + # $1 $2 $3 $4 $5 + regex = r'^\s*((?:(?:G_CONST_RETURN|G_GNUC_[A-Z_]+\s+|unsigned long|unsigned short|signed long|signed short|unsigned|signed|long|short|volatile|const)\s+)*)((?:struct\b|enum\b)?\s*\w+)\s*((?:(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*\*?\s*(?:const\b|restrict\b|G_GNUC_[A-Z_]+\b)?\s*)*)(\w+)?\s*((?:\[\S*\])*)\s*(?:G_GNUC_[A-Z_]+)?\s*[,\n]' + m = re.match(regex, declaration) + if m: + declaration = re.sub(regex, '', declaration) + + pre = m.group(1) or '' + type = m.group(2) + ptr = m.group(3) or '' + name = m.group(4) or '' + array = m.group(5) or '' + + pre = re.sub(r'\s+', ' ', pre) + type = re.sub(r'\s+', ' ', type) + ptr = re.sub(r'\s+', ' ', ptr) + ptr = re.sub(r'\s+$', '', ptr) + if ptr and not ptr.endswith('*'): + ptr += ' ' + + logging.debug('"%s" "%s" "%s" "%s" "%s"', pre, type, ptr, name, array) + + m = re.search(r'^((un)?signed .*)\s?', pre) + if name == '' and m: + name = type + type = m.group(1) + pre = '' + + if name == '': + name = 'Param' + str(param_num + 1) + + logging.debug('"%s" "%s" "%s" "%s" "%s"', pre, type, ptr, name, array) + + xref = typefunc(type, '%s' % type) + result[name] = namefunc('%s%s %s%s%s' % (pre, xref, ptr, name, array)) + param_num += 1 + continue + + # Try to match parameters which are functions + # $1 $2 $3 $4 $5 $6 $7 $8 + regex = r'^(const\s+|G_CONST_RETURN\s+|G_GNUC_[A-Z_]+\s+|signed\s+|unsigned\s+)*(struct\s+)?(\w+)\s*(\**)\s*(?:restrict\b)?\s*(const\s+)?\(\s*(\*[\s\*]*)\s*(\w+)\s*\)\s*\(([^)]*)\)\s*[,\n]' + m = re.match(regex, declaration) + if m: + declaration = re.sub(regex, '', declaration) + + mod1 = m.group(1) or '' + if m.group(2): + mod1 += m.group(2) + type = m.group(3) + ptr1 = m.group(4) + mod2 = m.group(5) or '' + func_ptr = m.group(6) + name = m.group(7) + func_params = m.group(8) or '' + + if ptr1 and not ptr1.endswith('*'): + ptr1 += ' ' + func_ptr = re.sub(r'\s+', ' ', func_ptr) + + logging.debug('"%s" "%s" "%s" "%s" "%s"', mod1, type, mod2, func_ptr, name) + + xref = typefunc(type, '%s' % type) + result[name] = namefunc('%s%s%s%s (%s%s) (%s)' % (mod1, xref, ptr1, mod2, func_ptr, name, func_params)) + param_num += 1 + continue + + logging.warning('Cannnot parse args for function in "%s"', declaration) + break + + return result + + +def ParseMacroDeclaration(declaration, namefunc): + """Parse a macro declaration. + + This function takes a macro declaration and breaks it into individual + parameter declarations. + + Args: + declaration (str): the declaration to parse + namefunc (func): function to apply to name + + Returns: + dict: map of (symbol, decl) pairs describing the macro + """ + + result = OrderedDict() + + logging.debug('decl=[%s]', declaration) + + m = re.search(r'^\s*#\s*define\s+\w+\(([^\)]*)\)', declaration) + if m: + params = m.group(1) + params = re.sub(r'\n', '', params) + + logging.debug('params=[%s]', params) + + for param in params.split(','): + param = param.strip() + + # Allow varargs variations + if param.endswith('...'): + param = '...' + + if param != '': + result[param] = namefunc(param) + + return result diff --git a/gtkdoc/config.py b/gtkdoc/config.py new file mode 100644 index 0000000..bce3899 --- /dev/null +++ b/gtkdoc/config.py @@ -0,0 +1,16 @@ +version = "1.26" + +# tools +dblatex = '/usr/bin/dblatex' +fop = '' +highlight = '/usr/bin/source-highlight' +highlight_options = '-t4 -s$SRC_LANG -cstyle.css --no-doc -i' +pkg_config = '/usr/bin/pkg-config' +xsltproc = '/usr/bin/xsltproc' + +# configured directories +prefix = '/usr' +datarootdir = "${prefix}/share".replace('${prefix}', prefix) +datadir = "${datarootdir}".replace('${datarootdir}', datarootdir) + +exeext = '' diff --git a/gtkdoc/config.py.in b/gtkdoc/config.py.in new file mode 100644 index 0000000..472c7df --- /dev/null +++ b/gtkdoc/config.py.in @@ -0,0 +1,16 @@ +version = "@VERSION@" + +# tools +dblatex = '@DBLATEX@' +fop = '@FOP@' +highlight = '@HIGHLIGHT@' +highlight_options = '@HIGHLIGHT_OPTIONS@' +pkg_config = '@PKG_CONFIG@' +xsltproc = '@XSLTPROC@' + +# configured directories +prefix = '@prefix@' +datarootdir = "@datarootdir@".replace('${prefix}', prefix) +datadir = "@datadir@".replace('${datarootdir}', datarootdir) + +exeext = '@EXEEXT@' diff --git a/gtkdoc/fixxref.py b/gtkdoc/fixxref.py new file mode 100755 index 0000000..a7029cb --- /dev/null +++ b/gtkdoc/fixxref.py @@ -0,0 +1,447 @@ +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +''"Fix cross-references in the HTML documentation.''" + +# Support both Python 2 and 3 +from __future__ import print_function + +import logging +import os +import re +import shlex +import subprocess +import sys +import tempfile + +from . import common, config + +# This contains all the entities and their relative URLs. +Links = {} + +# failing link targets we don't warn about even once +NoLinks = { + 'char', + 'double', + 'float', + 'int', + 'long', + 'main', + 'signed', + 'unsigned', + 'va-list', + 'void', + 'GBoxed', + 'GEnum', + 'GFlags', + 'GInterface' +} + +# Cache of dirs we already scanned for index files +DirCache = {} + + +def Run(options): + # logging.basicConfig(level=logging.INFO) + + path_prefix = '' + m = re.search(r'(.*?)/share/gtk-doc/html', options.html_dir) + if m: + path_prefix = m.group(1) + logging.info('Path prefix: %s', path_prefix) + prefix_match = r'^' + re.escape(path_prefix) + r'/' + + # We scan the directory containing GLib and any directories in GNOME2_PATH + # first, but these will be overriden by any later scans. + dir = common.GetModuleDocDir('glib-2.0') + if os.path.exists(dir): + # Some predefined link targets to get links into type hierarchies as these + # have no targets. These are always absolute for now. + Links['GBoxed'] = dir + '/gobject/gobject-Boxed-Types.html' + Links['GEnum'] = dir + '/gobject/gobject-Enumeration-and-Flag-Types.html' + Links['GFlags'] = dir + '/gobject/gobject-Enumeration-and-Flag-Types.html' + Links['GInterface'] = dir + '/gobject/GTypeModule.html' + + if dir != options.html_dir: + logging.info('Scanning GLib directory: %s', dir) + ScanIndices(dir, (re.search(prefix_match, dir) is None)) + + path = os.environ.get('GNOME2_PATH') + if path: + for dir in path.split(':'): + dir += '/share/gtk-doc/html' + if os.path.exists(dir) and dir != options.html_dir: + logging.info('Scanning GNOME2_PATH directory: %s', dir) + ScanIndices(dir, (re.search(prefix_match, dir) is None)) + + logging.info('Scanning HTML_DIR directory: %s', options.html_dir) + ScanIndices(options.html_dir, 0) + logging.info('Scanning MODULE_DIR directory: %s', options.module_dir) + ScanIndices(options.module_dir, 0) + + # check all extra dirs, but skip already scanned dirs or subdirs of those + for dir in options.extra_dir: + dir = dir.rstrip('/') + logging.info('Scanning EXTRA_DIR directory: %s', dir) + + # If the --extra-dir option is not relative and is not sharing the same + # prefix as the target directory of the docs, we need to use absolute + # directories for the links + if not dir.startswith('..') and re.search(prefix_match, dir) is None: + ScanIndices(dir, 1) + else: + ScanIndices(dir, 0) + + ReadSections(options) + FixCrossReferences(options) + + +def ScanIndices(scan_dir, use_absolute_links): + if not scan_dir or scan_dir in DirCache: + return + DirCache[scan_dir] = 1 + + logging.info('Scanning index directory: %s, absolute: %d', scan_dir, use_absolute_links) + + # TODO(ensonic): this code is the same as in rebase.py + if not os.path.isdir(scan_dir): + logging.info('Cannot open dir "%s"', scan_dir) + return + + subdirs = [] + for entry in sorted(os.listdir(scan_dir)): + full_entry = os.path.join(scan_dir, entry) + if os.path.isdir(full_entry): + subdirs.append(full_entry) + continue + + if entry.endswith('.devhelp2'): + # if devhelp-file is good don't read index.sgml + ReadDevhelp(full_entry, use_absolute_links) + elif entry == "index.sgml.gz" and not os.path.exists(os.path.join(scan_dir, 'index.sgml')): + # debian/ubuntu started to compress this as index.sgml.gz :/ + print(''' Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138 . For now run: +gunzip %s +''' % full_entry) + elif entry.endswith('.devhelp2.gz') and not os.path.exists(full_entry[:-3]): + # debian/ubuntu started to compress this as *devhelp2.gz :/ + print('''Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/1466210 . For now run: +gunzip %d +''' % full_entry) + # we could consider supporting: gzip module + + # Now recursively scan the subdirectories. + for subdir in subdirs: + ScanIndices(subdir, use_absolute_links) + + +def ReadDevhelp(file, use_absolute_links): + # Determine the absolute directory, to be added to links in $file + # if we need to use an absolute link. + # $file will be something like /prefix/gnome/share/gtk-doc/html/gtk/$file + # We want the part up to 'html/.*' since the links in $file include + # the rest. + dir = "../" + if use_absolute_links: + # For uninstalled index files we'd need to map the path to where it + # will be installed to + if not file.startswith('./'): + m = re.search(r'(.*\/)(.*?)\/.*?\.devhelp2', file) + dir = m.group(1) + m.group(2) + '/' + else: + m = re.search(r'(.*\/)(.*?)\/.*?\.devhelp2', file) + if m: + dir += m.group(2) + '/' + else: + dir = '' + + logging.info('Scanning index file=%s, absolute=%d, dir=%s', file, use_absolute_links, dir) + + for line in open(file): + m = re.search(r' link="([^#]*)#([^"]*)"', line) + if m: + link = m.group(1) + '#' + m.group(2) + logging.debug('Found id: %s href: %s', m.group(2), link) + Links[m.group(2)] = dir + link + + +def ReadSections(options): + for line in open(options.module + '-sections.txt'): + m1 = re.search(r'^', line) + if line.startswith('#') or line.strip() == '': + continue + elif line.startswith('
'): + subsection = '' + elif m1: + subsection = m1.group(1) + elif line.startswith('') or line.startswith('
'): + continue + elif re.search(r'^(.*)<\/TITLE>', line): + continue + elif re.search(r'^<FILE>(.*)<\/FILE>', line): + continue + elif re.search(r'^<INCLUDE>(.*)<\/INCLUDE>', line): + continue + else: + symbol = line.strip() + if subsection == "Standard" or subsection == "Private": + NoLinks.add(common.CreateValidSGMLID(symbol)) + + +def FixCrossReferences(options): + scan_dir = options.module_dir + # TODO(ensonic): use glob.glob()? + for entry in sorted(os.listdir(scan_dir)): + full_entry = os.path.join(scan_dir, entry) + if os.path.isdir(full_entry): + continue + elif entry.endswith('.html') or entry.endswith('.htm'): + FixHTMLFile(options, full_entry) + + +def FixHTMLFile(options, file): + logging.info('Fixing file: %s', file) + + content = open(file).read() + if sys.version_info < (3,): + content = content.decode('utf-8') + + if config.highlight: + # FIXME: ideally we'd pass a clue about the example language to the highligher + # unfortunately the "language" attribute is not appearing in the html output + # we could patch the customization to have <code class="xxx"> inside of <pre> + if config.highlight.endswith('vim'): + def repl_func(m): + return HighlightSourceVim(options, m.group(1), m.group(2)) + content = re.sub( + r'<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>', + repl_func, content, flags=re.DOTALL) + else: + def repl_func(m): + return HighlightSource(options, m.group(1), m.group(2)) + content = re.sub( + r'<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>', + repl_func, content, flags=re.DOTALL) + + content = re.sub(r'\<GTKDOCLINK\s+HREF=\"(.*?)\"\>(.*?)\</GTKDOCLINK\>', + r'\<GTKDOCLINK\ HREF=\"\1\"\>\2\</GTKDOCLINK\>', content, flags=re.DOTALL) + + # From the highlighter we get all the functions marked up. Now we can turn them into GTKDOCLINK items + def repl_func(m): + return MakeGtkDocLink(m.group(1), m.group(2), m.group(3)) + content = re.sub(r'(<span class=\"function\">)(.*?)(</span>)', repl_func, content, flags=re.DOTALL) + # We can also try the first item in stuff marked up as 'normal' + content = re.sub( + r'(<span class=\"normal\">\s*)(.+?)((\s+.+?)?\s*</span>)', repl_func, content, flags=re.DOTALL) + + lines = content.rstrip().split('\n') + + def repl_func_with_ix(i): + def repl_func(m): + return MakeXRef(options, file, i + 1, m.group(1), m.group(2)) + return repl_func + + for i in range(len(lines)): + lines[i] = re.sub(r'<GTKDOCLINK\s+HREF="([^"]*)"\s*>(.*?)</GTKDOCLINK\s*>', repl_func_with_ix(i), lines[i]) + if 'GTKDOCLINK' in lines[i]: + logging.info('make xref failed for line %d: "%s"', i, lines[i]) + + new_file = file + '.new' + content = '\n'.join(lines) + if sys.version_info < (3,): + content = content.encode('utf-8') + open(new_file, 'w').write(content) + + os.unlink(file) + os.rename(new_file, file) + + +def MakeXRef(options, file, line, id, text): + href = Links.get(id) + + # This is a workaround for some inconsistency we have with CreateValidSGMLID + if not href and ':' in id: + href = Links.get(id.replace(':', '--')) + # poor mans plural support + if not href and id.endswith('s'): + tid = id[:-1] + href = Links.get(tid) + if not href: + href = Links.get(tid + '-struct') + if not href: + href = Links.get(id + '-struct') + + if href: + # if it is a link to same module, remove path to make it work uninstalled + m = re.search(r'^\.\./' + options.module + '/(.*)$', href) + if m: + href = m.group(1) + logging.info('Fixing link to uninstalled doc: %s, %s, %s', id, href, text) + else: + logging.info('Fixing link: %s, %s, %s', id, href, text) + return "<a href=\"%s\">%s</a>" % (href, text) + else: + logging.info('no link for: %s, %s', id, text) + + # don't warn multiple times and also skip blacklisted (ctypes) + if id in NoLinks: + return text + # if it's a function, don't warn if it does not contain a "_" + # (transformed to "-") + # - gnome coding style would use '_' + # - will avoid wrong warnings for ansi c functions + if re.search(r' class=\"function\"', text) and '-' not in id: + return text + # if it's a 'return value', don't warn (implicitly created link) + if re.search(r' class=\"returnvalue\"', text): + return text + # if it's a 'type', don't warn if it starts with lowercase + # - gnome coding style would use CamelCase + if re.search(r' class=\"type\"', text) and id[0].islower(): + return text + # don't warn for self links + if text == id: + return text + + common.LogWarning(file, line, 'no link for: "%s" -> (%s).' % (id, text)) + NoLinks.add(id) + return text + + +def MakeGtkDocLink(pre, symbol, post): + id = common.CreateValidSGMLID(symbol) + + # these are implicitely created links in highlighed sources + # we don't want warnings for those if the links cannot be resolved. + NoLinks.add(id) + + return pre + '<GTKDOCLINK HREF="' + id + '">' + symbol + '</GTKDOCLINK>' + post + + +def HighlightSource(options, type, source): + # write source to a temp file + # FIXME: use .c for now to hint the language to the highlighter + with tempfile.NamedTemporaryFile(mode='w+', suffix='.c') as f: + temp_source_file = HighlightSourcePreProcess(f, source) + highlight_options = config.highlight_options.replace('$SRC_LANG', options.src_lang) + + logging.info('running %s %s %s', config.highlight, highlight_options, temp_source_file) + + # format source + highlighted_source = subprocess.check_output( + [config.highlight] + shlex.split(highlight_options) + [temp_source_file]).decode('utf-8') + logging.debug('result: [%s]', highlighted_source) + if config.highlight.endswith('/source-highlight'): + highlighted_source = re.sub(r'^<\!-- .*? -->', '', highlighted_source, flags=re.MULTILINE | re.DOTALL) + highlighted_source = re.sub( + r'<pre><tt>(.*?)</tt></pre>', r'\1', highlighted_source, flags=re.MULTILINE | re.DOTALL) + elif config.highlight.endswith('/highlight'): + # need to rewrite the stylesheet classes + highlighted_source = highlighted_source.replace('<span class="gtkdoc com">', '<span class="comment">') + highlighted_source = highlighted_source.replace('<span class="gtkdoc dir">', '<span class="preproc">') + highlighted_source = highlighted_source.replace('<span class="gtkdoc kwd">', '<span class="function">') + highlighted_source = highlighted_source.replace('<span class="gtkdoc kwa">', '<span class="keyword">') + highlighted_source = highlighted_source.replace('<span class="gtkdoc line">', '<span class="linenum">') + highlighted_source = highlighted_source.replace('<span class="gtkdoc num">', '<span class="number">') + highlighted_source = highlighted_source.replace('<span class="gtkdoc str">', '<span class="string">') + highlighted_source = highlighted_source.replace('<span class="gtkdoc sym">', '<span class="symbol">') + # maybe also do + # highlighted_source = re.sub(r'</span>(.+)<span', '</span><span class="normal">\1</span><span') + + return HighlightSourcePostprocess(type, highlighted_source) + + +def HighlightSourceVim(options, type, source): + # write source to a temp file + with tempfile.NamedTemporaryFile(mode='w+', suffix='.h') as f: + temp_source_file = HighlightSourcePreProcess(f, source) + + # format source + # TODO(ensonic): use p.communicate() + script = "echo 'let html_number_lines=0|let html_use_css=1|let html_use_xhtml=1|e %s|syn on|set syntax=%s|run! syntax/2html.vim|w! %s.html|qa!' | " % ( + temp_source_file, options.src_lang, temp_source_file) + script += "%s -n -e -u NONE -T xterm >/dev/null" % config.highlight + subprocess.check_call([script], shell=True) + + highlighted_source = open(temp_source_file + ".html").read() + highlighted_source = re.sub(r'.*<pre\b[^>]*>\n', '', highlighted_source, flags=re.MULTILINE) + highlighted_source = re.sub(r'</pre>.*', '', highlighted_source, flags=re.MULTILINE) + + # need to rewrite the stylesheet classes + highlighted_source = highlighted_source.replace('<span class="Comment">', '<span class="comment">') + highlighted_source = highlighted_source.replace('<span class="PreProc">', '<span class="preproc">') + highlighted_source = highlighted_source.replace('<span class="Statement">', '<span class="keyword">') + highlighted_source = highlighted_source.replace('<span class="Identifier">', '<span class="function">') + highlighted_source = highlighted_source.replace('<span class="Constant">', '<span class="number">') + highlighted_source = highlighted_source.replace('<span class="Special">', '<span class="symbol">') + highlighted_source = highlighted_source.replace('<span class="Type">', '<span class="type">') + + # remove temp files + os.unlink(temp_source_file + '.html') + + return HighlightSourcePostprocess(type, highlighted_source) + + +def HighlightSourcePreProcess(f, source): + # chop of leading and trailing empty lines, leave leading space in first real line + source = source.strip(' ') + source = source.strip('\n') + source = source.rstrip() + + # cut common indent + m = re.search(r'^(\s+)', source) + if m: + source = re.sub(r'^' + m.group(1), '', source, flags=re.MULTILINE) + # avoid double entity replacement + source = source.replace('<', '<') + source = source.replace('>', '>') + source = source.replace('&', '&') + if sys.version_info < (3,): + source = source.encode('utf-8') + f.write(source) + f.flush() + return f.name + + +def HighlightSourcePostprocess(type, highlighted_source): + # chop of leading and trailing empty lines + highlighted_source = highlighted_source.strip() + + # turn common urls in comments into links + highlighted_source = re.sub(r'<span class="url">(.*?)</span>', + r'<span class="url"><a href="\1">\1</a></span>', + highlighted_source, flags=re.DOTALL) + + # we do own line-numbering + line_count = highlighted_source.count('\n') + source_lines = '\n'.join([str(i) for i in range(1, line_count + 2)]) + + return """<div class="%s"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>%s</pre></td> + <td class="listing_code"><pre class="programlisting">%s</pre></td> + </tr> + </tbody> + </table> +</div> +""" % (type, source_lines, highlighted_source) diff --git a/gtkdoc/md_to_db.py b/gtkdoc/md_to_db.py new file mode 100644 index 0000000..2576f05 --- /dev/null +++ b/gtkdoc/md_to_db.py @@ -0,0 +1,744 @@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +""" +Markdown to Docbook converter +""" + +import logging +import re + +# external functions +ExpandAbbreviations = MakeXRef = MakeHashXRef = tagify = None + +# Elements to consider non-block items in MarkDown parsing +MD_TEXT_LEVEL_ELEMENTS = { + 'emphasis', 'envar', 'filename', 'firstterm', 'footnote', 'function', 'literal', + 'manvolnum', 'option', 'replaceable', 'structfield', 'structname', 'title', + 'varname' +} +MD_ESCAPABLE_CHARS = r'\`*_{}[]()>#+-.!' +MD_GTK_ESCAPABLE_CHARS = r'@%' + + +def Init(): + # TODO(enonic): find a better way to do this + global ExpandAbbreviations, MakeXRef, MakeHashXRef, tagify + from .mkdb import ExpandAbbreviations, MakeXRef, MakeHashXRef, tagify + + +def MarkDownParseBlocks(lines, symbol, context): + md_blocks = [] + md_block = {"type": ''} + + logging.debug("parsing %s lines", len(lines)) + for line in lines: + logging.info("type='%s', int='%s', parsing '%s'", md_block["type"], md_block.get('interrupted'), line) + first_char = None + if line: + first_char = line[0] + + if md_block["type"] == "markup": + if 'closed' not in md_block: + if md_block["start"] in line: + md_block["depth"] += 1 + + if md_block["end"] in line: + if md_block["depth"] > 0: + md_block["depth"] -= 1 + else: + logging.info("closing tag '%s'", line) + md_block["closed"] = 1 + # TODO(ensonic): reparse inner text with MarkDownParseLines? + + md_block["text"] += "\n" + line + logging.info("add to markup: '%s'", line) + continue + + deindented_line = line.lstrip() + + if md_block["type"] == "heading": + # a heading is ended by any level less than or equal + if md_block["level"] == 1: + heading_match = re.search(r'^[#][ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$', line) + if re.search(r'^={4,}[ \t]*$', line): + text = md_block["lines"].pop() + md_block.pop("interrupted", None) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': text, + 'lines': [], + 'level': 1, + } + continue + elif heading_match: + md_block.pop("interrupted", None) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': heading_match.group(1), + 'lines': [], + 'level': 1, + } + if heading_match.group(2): + md_block['id'] = heading_match.group(2) + continue + else: + # push lines into the block until the end is reached + md_block["lines"].append(line) + continue + + else: + heading_match = re.search(r'^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$', line) + if re.search(r'^[=]{4,}[ \t]*$', line): + text = md_block["lines"].pop() + md_block.pop("interrupted", None) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': text, + 'lines': [], + 'level': 1, + } + continue + elif re.search(r'^[-]{4,}[ \t]*$', line): + text = md_block["lines"].pop() + md_block.pop("interrupted", None) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': text, + 'lines': [], + 'level': 2, + } + continue + elif heading_match: + md_block.pop("interrupted", None) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': heading_match.group(2), + 'lines': [], + 'level': len(heading_match.group(1)) + } + if heading_match.group(3): + md_block['id'] = heading_match.group(3) + continue + else: + # push lines into the block until the end is reached + md_block["lines"].append(line) + continue + elif md_block["type"] == "code": + end_of_code_match = re.search(r'^[ \t]*\]\|(.*)', line) + if end_of_code_match: + md_blocks.append(md_block) + md_block = {'type': "paragraph", + 'text': end_of_code_match.group(1), + 'lines': [], + } + else: + md_block["lines"].append(line) + continue + + if deindented_line == '': + logging.info('setting "interrupted" due to empty line') + md_block["interrupted"] = 1 + continue + + if md_block["type"] == "quote": + if 'interrupted' not in md_block: + line = re.sub(r'^[ ]*>[ ]?', '', line) + md_block["lines"].append(line) + continue + + elif md_block["type"] == "li": + marker = md_block["marker"] + marker_match = re.search(r'^([ ]{0,3})(%s)[ ](.*)' % marker, line) + if marker_match: + indentation = marker_match.group(1) + if md_block["indentation"] != indentation: + md_block["lines"].append(line) + else: + ordered = md_block["ordered"] + md_block.pop('last', None) + md_blocks.append(md_block) + md_block = {'type': "li", + 'ordered': ordered, + 'indentation': indentation, + 'marker': marker, + 'last': 1, + 'lines': [re.sub(r'^[ ]{0,4}', '', marker_match.group(3))], + } + continue + + if 'interrupted' in md_block: + if first_char == " ": + md_block["lines"].append('') + line = re.sub(r'^[ ]{0,4}', '', line) + md_block["lines"].append(line) + md_block.pop("interrupted", None) + continue + else: + line = re.sub(r'^[ ]{0,4}', '', line) + md_block["lines"].append(line) + continue + + # indentation sensitive types + heading_match = re.search(r'^([#]{1,2})[ \t]+(.+?)[ \t]*[#]*[ \t]*(?:{#([^}]+)})?[ \t]*$', line) + code_match = re.search(r'^[ \t]*\|\[[ ]*(?:<!-- language="([^"]+?)" -->)?', line) + if heading_match: + # atx heading (#) + md_blocks.append(md_block) + md_block = {'type': "heading", + 'text': heading_match.group(2), + 'lines': [], + 'level': len(heading_match.group(1)), + } + if heading_match.group(3): + md_block['id'] = heading_match.group(3) + continue + elif re.search(r'^={4,}[ \t]*$', line): + # setext heading (====) + + if md_block["type"] == "paragraph" and "interrupted" in md_block: + md_blocks.append(md_block.copy()) + md_block["type"] = "heading" + md_block["lines"] = [] + md_block["level"] = 1 + continue + elif re.search(r'^-{4,}[ \t]*$', line): + # setext heading (-----) + + if md_block["type"] == "paragraph" and "interrupted" in md_block: + md_blocks.append(md_block.copy()) + md_block["type"] = "heading" + md_block["lines"] = [] + md_block["level"] = 2 + + continue + elif code_match: + # code + md_block["interrupted"] = 1 + md_blocks.append(md_block) + md_block = {'type': "code", + 'lines': [], + } + if code_match.group(1): + md_block['language'] = code_match.group(1) + continue + + # indentation insensitive types + markup_match = re.search(r'^[ ]*<\??(\w+)[^>]*([\/\?])?[ \t]*>', line) + li_match = re.search(r'^([ ]*)[*+-][ ](.*)', line) + quote_match = re.search(r'^[ ]*>[ ]?(.*)', line) + if re.search(r'^[ ]*<!DOCTYPE/', line): + md_blocks.append(md_block) + md_block = {'type': "markup", + 'text': deindented_line, + 'start': '<', + 'end': '>', + 'depth': 0, + } + + elif markup_match: + # markup, including <?xml version="1.0"?> + tag = markup_match.group(1) + is_self_closing = markup_match.group(2) is not None + + # skip link markdown + # TODO(ensonic): consider adding more uri schemes (ftp, ...) + if re.search(r'https?', tag): + logging.info("skipping link '%s'", tag) + else: + # for TEXT_LEVEL_ELEMENTS, we want to keep them as-is in the paragraph + # instead of creation a markdown block. + scanning_for_end_of_text_level_tag = ( + md_block["type"] == "paragraph" and + 'start' in md_block and + 'closed' not in md_block) + logging.info("markup found '%s', scanning %s ?", tag, scanning_for_end_of_text_level_tag) + if tag not in MD_TEXT_LEVEL_ELEMENTS and not scanning_for_end_of_text_level_tag: + md_blocks.append(md_block) + + if is_self_closing: + logging.info("self-closing docbook '%s'", tag) + md_block = {'type': "self-closing tag", + 'text': deindented_line, + } + is_self_closing = 0 + continue + + logging.info("new markup '%s'", tag) + md_block = {'type': "markup", + 'text': deindented_line, + 'start': '<' + tag + '>', + 'end': '</' + tag + '>', + 'depth': 0, + } + if re.search(r'<\/%s>' % tag, deindented_line): + md_block["closed"] = 1 + + continue + else: + if tag in MD_TEXT_LEVEL_ELEMENTS: + logging.info("text level docbook '%s' in '%s' state", tag, md_block["type"]) + # TODO(ensonic): handle nesting + if not scanning_for_end_of_text_level_tag: + if not re.search(r'<\/%s>' % tag, deindented_line): + logging.info("new text level markup '%s'", tag) + md_block["start"] = '<' + tag + '>' + md_block["end"] = '</' + tag + '>' + md_block.pop("closed", None) + logging.info("scanning for end of '%s'", tag) + + else: + if md_block["end"] in deindented_line: + md_block["closed"] = 1 + logging.info("found end of '%s'", tag) + elif li_match: + # li + md_blocks.append(md_block) + indentation = li_match.group(1) + md_block = {'type': "li", + 'ordered': 0, + 'indentation': indentation, + 'marker': "[*+-]", + 'first': 1, + 'last': 1, + 'lines': [re.sub(r'^[ ]{0,4}', '', li_match.group(2))], + } + continue + elif quote_match: + md_blocks.append(md_block) + md_block = {'type': "quote", + 'lines': [quote_match.group(1)], + } + continue + + # list item + list_item_match = re.search(r'^([ ]{0,4})\d+[.][ ]+(.*)', line) + if list_item_match: + md_blocks.append(md_block) + indentation = list_item_match.group(1) + md_block = {'type': "li", + 'ordered': 1, + 'indentation': indentation, + 'marker': "\\d+[.]", + 'first': 1, + 'last': 1, + 'lines': [re.sub(r'^[ ]{0,4}', '', list_item_match.group(2))], + } + continue + + # paragraph + if md_block["type"] == "paragraph": + if "interrupted" in md_block: + md_blocks.append(md_block) + md_block = {'type': "paragraph", + 'text': line, + } + logging.info("new paragraph due to interrupted") + else: + md_block["text"] += "\n" + line + logging.info("add to paragraph: '%s'", line) + + else: + md_blocks.append(md_block) + md_block = {'type': "paragraph", + 'text': line, + } + logging.info("new paragraph due to different block type") + + md_blocks.append(md_block) + md_blocks.pop(0) + + return md_blocks + + +def MarkDownParseSpanElementsInner(text, markersref): + markup = '' + markers = {i: 1 for i in markersref} + + while text != '': + closest_marker = '' + closest_marker_position = -1 + text_marker = '' + offset = 0 + markers_rest = [] + + for marker, use in markers.items(): + if not use: + continue + + marker_position = text.find(marker) + + if marker_position < 0: + markers[marker] = 0 + continue + + if closest_marker == '' or marker_position < closest_marker_position: + closest_marker = marker + closest_marker_position = marker_position + + if closest_marker_position >= 0: + text_marker = text[closest_marker_position:] + + if text_marker == '': + markup += text + text = '' + continue + + markup += text[:closest_marker_position] + text = text[closest_marker_position:] + markers_rest = {k: v for k, v in markers.items() if v and k != closest_marker} + + if closest_marker == '![' or closest_marker == '[': + element = None + + # FIXME: '(?R)' is a recursive subpattern + # match a [...] block with no ][ inside or this thing again + # m = re.search(r'\[((?:[^][]|(?R))*)\]', text) + m = re.search(r'\[((?:[^][])*)\]', text) + if ']' in text and m: + element = {'!': text[0] == '!', + 'a': m.group(1), + } + + offset = len(m.group(0)) + if element['!']: + offset += 1 + logging.debug("Recursive md-expr match: off=%d, text='%s', match='%s'", offset, text, m.group(1)) + + remaining_text = text[offset:] + m2 = re.search(r'''^\([ ]*([^)'"]*?)(?:[ ]+['"](.+?)['"])?[ ]*\)''', remaining_text) + m3 = re.search(r'^\s*\[([^\]<]*?)\]', remaining_text) + if m2: + element['»'] = m2.group(1) + if m2.group(2): + element['#'] = m2.group(2) + offset += len(m2.group(0)) + elif m3: + element['ref'] = m3.group(1) + offset += len(m3.group(0)) + else: + element = None + + if element: + if '»' in element: + element['»'] = element['»'].replace('&', '&').replace('<', '<') + + if element['!']: + markup += '<inlinemediaobject><imageobject><imagedata fileref="' + \ + element['»'] + '"></imagedata></imageobject>' + + if 'a' in element: + markup += "<textobject><phrase>" + element['a'] + "</phrase></textobject>" + + markup += "</inlinemediaobject>" + elif 'ref' in element: + element['a'] = MarkDownParseSpanElementsInner(element['a'], markers_rest) + markup += '<link linkend="' + element['ref'] + '"' + + if '#' in element: + # title attribute not supported + pass + + markup += '>' + element['a'] + "</link>" + else: + element['a'] = MarkDownParseSpanElementsInner(element['a'], markers_rest) + markup += '<ulink url="' + element['»'] + '"' + + if '#' in element: + # title attribute not supported + pass + + markup += '>' + element['a'] + "</ulink>" + + else: + markup += closest_marker + if closest_marker == '![': + offset = 2 + else: + offset = 1 + + elif closest_marker == '<': + m4 = re.search(r'^<(https?:[\/]{2}[^\s]+?)>', text, flags=re.I) + m5 = re.search(r'^<([A-Za-z0-9._-]+?@[A-Za-z0-9._-]+?)>', text) + m6 = re.search(r'^<[^>]+?>', text) + if m4: + element_url = m4.group(1).replace('&', '&').replace('<', '<') + + markup += '<ulink url="' + element_url + '">' + element_url + '</ulink>' + offset = len(m4.group(0)) + elif m5: + markup += "<ulink url=\"mailto:" + m5.group(1) + "\">" + m5.group(1) + "</ulink>" + offset = len(m5.group(0)) + elif m6: + markup += m6.group(0) + offset = len(m6.group(0)) + else: + markup += "<" + offset = 1 + + elif closest_marker == "\\": + special_char = '' + if len(text) > 1: + special_char = text[1] + if special_char in MD_ESCAPABLE_CHARS or special_char in MD_GTK_ESCAPABLE_CHARS: + markup += special_char + offset = 2 + else: + markup += "\\" + offset = 1 + + elif closest_marker == "`": + m7 = re.search(r'^(`+)([^`]+?)\1(?!`)', text) + if m7: + element_text = m7.group(2) + markup += "<literal>" + element_text + "</literal>" + offset = len(m7.group(0)) + else: + markup += "`" + offset = 1 + + elif closest_marker == "@": + # Convert '@param()' + # FIXME: we could make those also links ($symbol.$2), but that would be less + # useful as the link target is a few lines up or down + m7 = re.search(r'^(\A|[^\\])\@(\w+((\.|->)\w+)*)\s*\(\)', text) + m8 = re.search(r'^(\A|[^\\])\@(\w+((\.|->)\w+)*)', text) + m9 = re.search(r'^\\\@', text) + if m7: + markup += m7.group(1) + "<parameter>" + m7.group(2) + "()</parameter>\n" + offset = len(m7.group(0)) + elif m8: + # Convert '@param', but not '\@param'. + markup += m8.group(1) + "<parameter>" + m8.group(2) + "</parameter>\n" + offset = len(m8.group(0)) + elif m9: + markup += r"\@" + offset = len(m9.group(0)) + else: + markup += "@" + offset = 1 + + elif closest_marker == '#': + m10 = re.search(r'^(\A|[^\\])#([\w\-:\.]+[\w]+)\s*\(\)', text) + m11 = re.search(r'^(\A|[^\\])#([\w\-:\.]+[\w]+)', text) + m12 = re.search(r'^\\#', text) + if m10: + # handle #Object.func() + markup += m10.group(1) + MakeXRef(m10.group(2), tagify(m10.group(2) + "()", "function")) + offset = len(m10.group(0)) + elif m11: + # Convert '#symbol', but not '\#symbol'. + markup += m11.group(1) + MakeHashXRef(m11.group(2), "type") + offset = len(m11.group(0)) + elif m12: + markup += '#' + offset = len(m12.group(0)) + else: + markup += '#' + offset = 1 + + elif closest_marker == "%": + m12 = re.search(r'^(\A|[^\\])\%(-?\w+)', text) + m13 = re.search(r'^\\%', text) + if m12: + # Convert '%constant', but not '\%constant'. + # Also allow negative numbers, e.g. %-1. + markup += m12.group(1) + MakeXRef(m12.group(2), tagify(m12.group(2), "literal")) + offset = len(m12.group(0)) + elif m13: + markup += r"\%" + offset = len(m13.group(0)) + else: + markup += "%" + offset = 1 + + if offset > 0: + text = text[offset:] + + return markup + + +def MarkDownParseSpanElements(text): + markers = ["\\", '<', '![', '[', "`", '%', '#', '@'] + + text = MarkDownParseSpanElementsInner(text, markers) + + # Convert 'function()' or 'macro()'. + # if there is abc_*_def() we don't want to make a link to _def() + # FIXME: also handle abc(def(....)) : but that would need to be done recursively :/ + def f(m): + return m.group(1) + MakeXRef(m.group(2), tagify(m.group(2) + "()", "function")) + text = re.sub(r'([^\*.\w])(\w+)\s*\(\)', f, text) + return text + + +def ReplaceEntities(text): + entities = [["<", '<'], + [">", '>'], + ["*", '*'], + ["#", '#'], + ["%", '%'], + [":", ':'], + [""", '"'], + ["'", "'"], + [" ", ' '], + ["&", '&'], # Do this last, or the others get messed up. + ] + + # Expand entities in <programlisting> even inside CDATA since + # we changed the definition of |[ to add CDATA + for i in entities: + text = re.sub(i[0], i[1], text) + return text + + +def MarkDownOutputDocBook(blocksref, symbol, context): + output = '' + blocks = blocksref + + for block in blocks: + #$output += "\n<!-- beg type='" . $block->{"type"} . "'-->\n" + + if block["type"] == "paragraph": + text = MarkDownParseSpanElements(block["text"]) + if context == "li" and output == '': + if 'interrupted' in block: + output += "\n<para>%s</para>\n" % text + else: + output += "<para>%s</para>" % text + if len(blocks) > 1: + output += "\n" + else: + output += "<para>%s</para>\n" % text + + elif block["type"] == "heading": + + title = MarkDownParseSpanElements(block["text"]) + + if block["level"] == 1: + tag = "refsect2" + else: + tag = "refsect3" + + text = MarkDownParseLines(block["lines"], symbol, "heading") + if 'id' in block: + output += "<%s id=\"%s\">" % (tag, block["id"]) + else: + output += "<%s>" % tag + + output += "<title>%s%s\n" % (title, text, tag) + elif block["type"] == "li": + tag = "itemizedlist" + + if "first" in block: + if block["ordered"]: + tag = "orderedlist" + output += "<%s>\n" % tag + + if "interrupted" in block: + block["lines"].append('') + + text = MarkDownParseLines(block["lines"], symbol, "li") + output += "" + text + "\n" + if 'last' in block: + if block["ordered"]: + tag = "orderedlist" + output += "\n" % tag + + elif block["type"] == "quote": + text = MarkDownParseLines(block["lines"], symbol, "quote") + output += "
\n%s
\n" % text + elif block["type"] == "code": + tag = "programlisting" + + if "language" in block: + if block["language"] == "plain": + output += "\n" % tag + elif block["type"] == "markup": + text = ExpandAbbreviations(symbol, block["text"]) + output += text + "\n" + else: + output += block["text"] + "\n" + + #$output += "\n\n" + return output + + +def MarkDownParseLines(lines, symbol, context): + logging.info('md parse: ctx=%s, [%s]', context, '\n'.join(lines)) + blocks = MarkDownParseBlocks(lines, symbol, context) + output = MarkDownOutputDocBook(blocks, symbol, context) + return output + + +def MarkDownParse(text, symbol): + """Converts mark down syntax to the respective docbook. + + http://de.wikipedia.org/wiki/Markdown + Inspired by the design of ParseDown + http://parsedown.org/ + Copyright (c) 2013 Emanuil Rusev, erusev.com + + SUPPORTED MARKDOWN + ================== + + Atx-style Headers + ----------------- + + # Header 1 + + ## Header 2 ## + + Setext-style Headers + -------------------- + + Header 1 + ======== + + Header 2 + -------- + + Ordered (unnested) Lists + ------------------------ + + 1. item 1 + + 1. item 2 with loooong + description + + 3. item 3 + + Note: we require a blank line above the list items + """ + # TODO(ensonic): it would be nice to add id parameters to the refsect2 elements + + return MarkDownParseLines(text.splitlines(), symbol, '') diff --git a/gtkdoc/mkdb.py b/gtkdoc/mkdb.py new file mode 100644 index 0000000..e103138 --- /dev/null +++ b/gtkdoc/mkdb.py @@ -0,0 +1,4728 @@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +""" +Creates the DocBook files from the source comments. +""" + +from __future__ import print_function +from six import iteritems, iterkeys + +from collections import OrderedDict +import logging +import os +import re +import string +import sys + +from . import common, md_to_db + +# Options +MODULE = None +DB_OUTPUT_DIR = None +INLINE_MARKUP_MODE = None +DEFAULT_STABILITY = None +NAME_SPACE = '' +ROOT_DIR = '.' + +# These global arrays store information on signals. Each signal has an entry +# in each of these arrays at the same index, like a multi-dimensional array. +SignalObjects = [] # The GtkObject which emits the signal. +SignalNames = [] # The signal name. +SignalReturns = [] # The return type. +SignalFlags = [] # Flags for the signal +SignalPrototypes = [] # The rest of the prototype of the signal handler. + +# These global arrays store information on Args. Each Arg has an entry +# in each of these arrays at the same index, like a multi-dimensional array. +ArgObjects = [] # The GtkObject which has the Arg. +ArgNames = [] # The Arg name. +ArgTypes = [] # The Arg type - gint, GtkArrowType etc. +ArgFlags = [] # How the Arg can be used - readable/writable etc. +ArgNicks = [] # The nickname of the Arg. +ArgBlurbs = [] # Docstring of the Arg. +ArgDefaults = [] # Default value of the Arg. +ArgRanges = [] # The range of the Arg type + +# These global hashes store declaration info keyed on a symbol name. +Declarations = {} +DeclarationTypes = {} +DeclarationConditional = {} +DeclarationOutput = {} +Deprecated = {} +Since = {} +StabilityLevel = {} +StructHasTypedef = {} + +# These global hashes store the existing documentation. +SymbolDocs = {} +SymbolParams = {} +SymbolAnnotations = {} + +# These global hashes store documentation scanned from the source files. +SourceSymbolDocs = {} +SourceSymbolParams = {} +SourceSymbolSourceFile = {} +SourceSymbolSourceLine = {} + +# all documentation goes in here, so we can do coverage analysis +AllSymbols = {} +AllIncompleteSymbols = {} +AllUnusedSymbols = {} +AllDocumentedSymbols = {} + +# Undeclared yet documented symbols +UndeclaredSymbols = {} + +# These global arrays store GObject, subclasses and the hierarchy (also of +# non-object derived types). +Objects = [] +ObjectLevels = [] +ObjectRoots = {} + +Interfaces = {} +Prerequisites = {} + +# holds the symbols which are mentioned in -sections.txt and in which +# section they are defined +KnownSymbols = {} +SymbolSection = {} +SymbolSectionId = {} + +# collects index entries +IndexEntriesFull = {} +IndexEntriesSince = {} +IndexEntriesDeprecated = {} + +# Standard C preprocessor directives, which we ignore for '#' abbreviations. +PreProcessorDirectives = { + 'assert', 'define', 'elif', 'else', 'endif', 'error', 'if', 'ifdef', 'ifndef', + 'include', 'line', 'pragma', 'unassert', 'undef', 'warning' +} + +# remember used annotation (to write minimal glossary) +AnnotationsUsed = {} + +# the regexp that parses the annotation is in ScanSourceFile() +AnnotationDefinition = { + # the GObjectIntrospection annotations are defined at: + # https://live.gnome.org/GObjectIntrospection/Annotations + 'allow-none': "NULL is OK, both for passing and for returning.", + 'nullable': "NULL may be passed as the value in, out, in-out; or as a return value.", + 'not nullable': "NULL must not be passed as the value in, out, in-out; or as a return value.", + 'optional': "NULL may be passed instead of a pointer to a location.", + 'array': "Parameter points to an array of items.", + 'attribute': "Deprecated free-form custom annotation, replaced by (attributes) annotation.", + 'attributes': "Free-form key-value pairs.", + 'closure': "This parameter is a 'user_data', for callbacks; many bindings can pass NULL here.", + 'constructor': "This symbol is a constructor, not a static method.", + 'destroy': "This parameter is a 'destroy_data', for callbacks.", + 'default': "Default parameter value (for in case the shadows-to function has less parameters).", + 'element-type': "Generics and defining elements of containers and arrays.", + 'error-domains': "Typed errors. Similar to throws in Java.", + 'foreign': "This is a foreign struct.", + 'get-value-func': "The specified function is used to convert a struct from a GValue, must be a GTypeInstance.", + 'in': "Parameter for input. Default is transfer none.", + 'inout': "Parameter for input and for returning results. Default is transfer full.", + 'in-out': "Parameter for input and for returning results. Default is transfer full.", + 'method': "This is a method", + 'not-error': "A GError parameter is not to be handled like a normal GError.", + 'out': "Parameter for returning results. Default is transfer full.", + 'out caller-allocates': "Out parameter, where caller must allocate storage.", + 'out callee-allocates': "Out parameter, where caller must allocate storage.", + 'ref-func': "The specified function is used to ref a struct, must be a GTypeInstance.", + 'rename-to': "Rename the original symbol's name to SYMBOL.", + 'scope call': "The callback is valid only during the call to the method.", + 'scope async': "The callback is valid until first called.", + 'scope notified': "The callback is valid until the GDestroyNotify argument is called.", + 'set-value-func': "The specified function is used to convert from a struct to a GValue, must be a GTypeInstance.", + 'skip': "Exposed in C code, not necessarily available in other languages.", + 'transfer container': "Free data container after the code is done.", + 'transfer floating': "Alias for transfer none, used for objects with floating refs.", + 'transfer full': "Free data after the code is done.", + 'transfer none': "Don't free data after the code is done.", + 'type': "Override the parsed C type with given type.", + 'unref-func': "The specified function is used to unref a struct, must be a GTypeInstance.", + 'virtual': "This is the invoker for a virtual method.", + 'value': "The specified value overrides the evaluated value of the constant.", + # Stability Level definition + # https://bugzilla.gnome.org/show_bug.cgi?id=170860 + 'Stable': '''The intention of a Stable interface is to enable arbitrary third parties to +develop applications to these interfaces, release them, and have confidence that +they will run on all minor releases of the product (after the one in which the +interface was introduced, and within the same major release). Even at a major +release, incompatible changes are expected to be rare, and to have strong +justifications. +''', + 'Unstable': '''Unstable interfaces are experimental or transitional. They are typically used to +give outside developers early access to new or rapidly changing technology, or +to provide an interim solution to a problem where a more general solution is +anticipated. No claims are made about either source or binary compatibility from +one minor release to the next. + +The Unstable interface level is a warning that these interfaces are subject to +change without warning and should not be used in unbundled products. + +Given such caveats, customer impact need not be a factor when considering +incompatible changes to an Unstable interface in a major or minor release. +Nonetheless, when such changes are introduced, the changes should still be +mentioned in the release notes for the affected release. +''', + 'Private': '''An interface that can be used within the GNOME stack itself, but that is not +documented for end-users. Such functions should only be used in specified and +documented ways. +''', +} + +# Function and other declaration output settings. +RETURN_TYPE_FIELD_WIDTH = 20 +MAX_SYMBOL_FIELD_WIDTH = 40 + +# XML header +doctype_header = None + +# refentry template +REFENTRY = string.Template('''${header} + + +${title} +3 +${MODULE} Library${image} + + +${title} +${short_desc} + +${stability} +${functions_synop}${args_synop}${signals_synop}${object_anchors}${other_synop}${hierarchy}${prerequisites}${derived}${interfaces}${implementations} +${include_output} + +Description +${extralinks}${long_desc} + + +Functions +${functions_details} + + +Types and Values +${other_details} + +${args_desc}${signals_desc}${see_also} + +''') + + +def Run(options): + global MODULE, INLINE_MARKUP_MODE, DEFAULT_STABILITY, NAME_SPACE, \ + DB_OUTPUT_DIR, doctype_header + + # We should pass the options variable around instead of this global variable horror + # but too much of the code expects these to be around. Fix this once the transition is done. + MODULE = options.module + INLINE_MARKUP_MODE = options.xml_mode or options.sgml_mode + DEFAULT_STABILITY = options.default_stability + NAME_SPACE = options.name_space + + main_sgml_file = options.main_sgml_file + if not main_sgml_file: + # backwards compatibility + if os.path.exists(MODULE + "-docs.sgml"): + main_sgml_file = MODULE + "-docs.sgml" + else: + main_sgml_file = MODULE + "-docs.xml" + + # extract docbook header or define default + doctype_header = GetDocbookHeader(main_sgml_file) + + # This is where we put all the DocBook output. + DB_OUTPUT_DIR = DB_OUTPUT_DIR if DB_OUTPUT_DIR else os.path.join(ROOT_DIR, "xml") + if not os.path.isdir(DB_OUTPUT_DIR): + os.mkdir(DB_OUTPUT_DIR) + + ReadKnownSymbols(os.path.join(ROOT_DIR, MODULE + "-sections.txt")) + ReadSignalsFile(os.path.join(ROOT_DIR, MODULE + ".signals")) + ReadArgsFile(os.path.join(ROOT_DIR, MODULE + ".args")) + ReadObjectHierarchy(os.path.join(ROOT_DIR, MODULE + ".hierarchy")) + ReadInterfaces(os.path.join(ROOT_DIR, MODULE + ".interfaces")) + ReadPrerequisites(os.path.join(ROOT_DIR, MODULE + ".prerequisites")) + + ReadDeclarationsFile(os.path.join(ROOT_DIR, MODULE + "-decl.txt"), 0) + if os.path.isfile(os.path.join(ROOT_DIR, MODULE + "-overrides.txt")): + ReadDeclarationsFile(os.path.join(ROOT_DIR, MODULE + "-overrides.txt"), 1) + + # Scan sources + if options.source_suffixes: + suffix_list = ['.' + ext for ext in options.source_suffixes.split(',')] + else: + suffix_list = ['.c', '.h'] + + source_dirs = options.source_dir + ignore_files = options.ignore_files + logging.info(" ignore files: " + ignore_files) + for sdir in source_dirs: + ReadSourceDocumentation(sdir, suffix_list, source_dirs, ignore_files) + + changed, book_top, book_bottom = OutputDB(os.path.join(ROOT_DIR, MODULE + "-sections.txt"), options) + OutputBook(main_sgml_file, book_top, book_bottom) + + logging.info("All files created: %d", changed) + + # If any of the DocBook files have changed, update the timestamp file (so + # it can be used for Makefile dependencies). + if changed or not os.path.exists(os.path.join(ROOT_DIR, "sgml.stamp")): + + # try to detect the common prefix + # GtkWidget, GTK_WIDGET, gtk_widget -> gtk + if NAME_SPACE == '': + NAME_SPACE = DetermineNamespace() + + logging.info('namespace prefix ="%s"', NAME_SPACE) + + OutputIndex("api-index-full", IndexEntriesFull) + OutputIndex("api-index-deprecated", IndexEntriesDeprecated) + OutputSinceIndexes() + OutputAnnotationGlossary() + + open(os.path.join(ROOT_DIR, 'sgml.stamp'), 'w').write('timestamp') + + +def OutputObjectList(): + """This outputs the alphabetical list of objects, in a columned table.""" + # FIXME: Currently this also outputs ancestor objects which may not actually + # be in this module. + cols = 3 + + # FIXME: use .xml + old_object_index = os.path.join(DB_OUTPUT_DIR, "object_index.sgml") + new_object_index = os.path.join(DB_OUTPUT_DIR, "object_index.new") + + OUTPUT = open(new_object_index, 'w') + + OUTPUT.write('''%s + + + + + + +''' % (MakeDocHeader("informaltable"), cols)) + + count = 0 + object = None + for object in sorted(Objects): + xref = MakeXRef(object) + if count % cols == 0: + OUTPUT.write("\n") + OUTPUT.write("%s\n" % xref) + if count % cols == cols - 1: + OUTPUT.write("\n") + count += 1 + + if count == 0: + # emit an empty row, since empty tables are invalid + OUTPUT.write(" \n") + + else: + if count % cols > 0: + OUTPUT.write("\n") + + OUTPUT.write('''\n''') + OUTPUT.close() + + common.UpdateFileIfChanged(old_object_index, new_object_index, 0) + + +def TrimTextBlock(desc): + """Trims extra whitespace. + + Empty lines inside a block are preserved. + Args: + desc (str): the text block to trim. May contain newlines. + """ + + # strip trailing spaces on every line + return re.sub(r'\s+$', '\n', desc.lstrip(), flags=re.MULTILINE) + + +def OutputDB(file, options): + """Generate docbook files. + + This collects the output for each section of the docs, and outputs each file + when the end of the section is found. + + Args: + file (str): the $MODULE-sections.txt file which contains all of the + functions/macros/structs etc. being documented, organised + into sections and subsections. + options: commandline options + """ + + logging.info("Reading: %s", file) + INPUT = open(file) + filename = '' + book_top = '' + book_bottom = '' + includes = options.default_includes or '' + section_includes = '' + in_section = 0 + title = '' + section_id = '' + subsection = '' + num_symbols = 0 + changed = 0 + functions_synop = '' + other_synop = '' + functions_details = '' + other_details = '' + signals_synop = '' + signals_desc = '' + args_synop = '' + child_args_synop = '' + style_args_synop = '' + args_desc = '' + child_args_desc = '' + style_args_desc = '' + hierarchy_str = '' + hierarchy = [] + interfaces = '' + implementations = '' + prerequisites = '' + derived = '' + file_objects = [] + file_def_line = {} + symbol_def_line = {} + + MergeSourceDocumentation() + + line_number = 0 + for line in INPUT: + line_number += 1 + + if line.startswith('#'): + continue + + logging.info("section file data: %d: %s", line_number, line) + + m1 = re.search(r'^', line, re.I) + m2 = re.search(r'^(.*)<\/TITLE', line) + m3 = re.search(r'^<FILE>(.*)<\/FILE>', line) + m4 = re.search(r'^<INCLUDE>(.*)<\/INCLUDE>', line) + m5 = re.search(r'^(\S+)', line) + + if line.startswith('<SECTION>'): + num_symbols = 0 + in_section = False + file_objects = [] + symbol_def_line = {} + + elif m1: + other_synop += "\n" + functions_synop += "\n" + subsection = m1.group(1) + + elif line.startswith('<SUBSECTION>'): + continue + elif m2: + title = m2.group(1) + logging.info("Section: %s", title) + + # We don't want warnings if object & class structs aren't used. + DeclarationOutput[title] = 1 + DeclarationOutput["%sClass" % title] = 1 + DeclarationOutput["%sIface" % title] = 1 + DeclarationOutput["%sInterface" % title] = 1 + + elif m3: + filename = m3.group(1) + if not filename in file_def_line: + file_def_line[filename] = line_number + else: + common.LogWarning(file, line_number, "Double <FILE>%s</FILE> entry. Previous occurrence on line %s." % + (filename, file_def_line[filename])) + if title == '': + key = filename + ":Title" + if key in SourceSymbolDocs: + title = SourceSymbolDocs[key].rstrip() + + elif m4: + if in_section: + section_includes = m4.group(1) + else: + if options.default_includes: + common.LogWarning(file, line_number, "Default <INCLUDE> being overridden by command line option.") + else: + includes = m4.group(1) + + elif re.search(r'^<\/SECTION>', line): + logging.info("End of section: %s", title) + if num_symbols > 0: + # collect documents + book_bottom += " <xi:include href=\"xml/%s.xml\"/>\n" % filename + + key = filename + ":Include" + if key in SourceSymbolDocs: + if section_includes: + common.LogWarning(file, line_number, "Section <INCLUDE> being overridden by inline comments.") + section_includes = SourceSymbolDocs[key] + + if section_includes == '': + section_includes = includes + + signals_synop = re.sub(r'^\n*', '', signals_synop) + signals_synop = re.sub(r'\n+$', '\n', signals_synop) + + if signals_synop != '': + signals_synop = '''<refsect1 id="%s.signals" role="signal_proto"> +<title role="signal_proto.title">Signals + + + + + + +%s + + + + +''' % (section_id, signals_synop) + signals_desc = TrimTextBlock(signals_desc) + signals_desc = ''' +Signal Details +%s + +''' % (section_id, signals_desc) + + args_synop = re.sub(r'^\n*', '', args_synop) + args_synop = re.sub(r'\n+$', '\n', args_synop) + if args_synop != '': + args_synop = ''' +Properties + + + + + + +%s + + + + +''' % (section_id, args_synop) + args_desc = TrimTextBlock(args_desc) + args_desc = ''' +Property Details +%s + +''' % (section_id, args_desc) + + child_args_synop = re.sub(r'^\n*', '', child_args_synop) + child_args_synop = re.sub(r'\n+$', '\n', child_args_synop) + if child_args_synop != '': + args_synop += ''' +Child Properties + + + + + + +%s + + + + +''' % (section_id, child_args_synop) + child_args_desc = TrimTextBlock(child_args_desc) + args_desc += ''' +Child Property Details +%s + +''' % (section_id, child_args_desc) + + style_args_synop = re.sub(r'^\n*', '', style_args_synop) + style_args_synop = re.sub(r'\n+$', '\n', style_args_synop) + if style_args_synop != '': + args_synop += ''' +Style Properties + + + + + + +%s + + + + +''' % (section_id, style_args_synop) + style_args_desc = TrimTextBlock(style_args_desc) + args_desc += ''' +Style Property Details +%s + +''' % (section_id, style_args_desc) + + hierarchy_str = AddTreeLineArt(hierarchy) + if hierarchy_str != '': + hierarchy_str = ''' +Object Hierarchy +%s + + +''' % (section_id, hierarchy_str) + + interfaces = TrimTextBlock(interfaces) + if interfaces != '': + interfaces = ''' +Implemented Interfaces +%s + +''' % (section_id, interfaces) + + implementations = TrimTextBlock(implementations) + if implementations != '': + implementations = ''' +Known Implementations +%s + +''' % (section_id, implementations) + + prerequisites = TrimTextBlock(prerequisites) + if prerequisites != '': + prerequisites = ''' +Prerequisites +%s + +''' % (section_id, prerequisites) + + derived = TrimTextBlock(derived) + if derived != '': + derived = ''' +Known Derived Interfaces +%s + +''' % (section_id, derived) + + functions_synop = re.sub(r'^\n*', '', functions_synop) + functions_synop = re.sub(r'\n+$', '\n', functions_synop) + if functions_synop != '': + functions_synop = ''' +Functions + + + + + +%s + + + + +''' % (section_id, functions_synop) + + other_synop = re.sub(r'^\n*', '', other_synop) + other_synop = re.sub(r'\n+$', '\n', other_synop) + if other_synop != '': + other_synop = ''' +Types and Values + + + + + +%s + + + + +''' % (section_id, other_synop) + + file_changed = OutputDBFile(filename, title, section_id, + section_includes, + functions_synop, other_synop, + functions_details, other_details, + signals_synop, signals_desc, + args_synop, args_desc, + hierarchy_str, interfaces, + implementations, + prerequisites, derived, + file_objects) + if file_changed: + changed = True + + title = '' + section_id = '' + subsection = '' + in_section = 0 + section_includes = '' + functions_synop = '' + other_synop = '' + functions_details = '' + other_details = '' + signals_synop = '' + signals_desc = '' + args_synop = '' + child_args_synop = '' + style_args_synop = '' + args_desc = '' + child_args_desc = '' + style_args_desc = '' + hierarchy_str = '' + hierarchy = [] + interfaces = '' + implementations = '' + prerequisites = '' + derived = '' + + elif m5: + symbol = m5.group(1) + logging.info(' Symbol: "%s" in subsection: "%s"', symbol, subsection) + + # check for duplicate entries + if symbol not in symbol_def_line: + declaration = Declarations.get(symbol) + # FIXME: with this we'll output empty declaration + if declaration is not None: + if CheckIsObject(symbol): + file_objects.append(symbol) + + # We don't want standard macros/functions of GObjects, + # or private declarations. + if subsection != "Standard" and subsection != "Private": + synop, desc = OutputDeclaration(symbol, declaration) + type = DeclarationTypes[symbol] + + if type == 'FUNCTION' or type == 'USER_FUNCTION': + functions_synop += synop + functions_details += desc + elif type == 'MACRO' and re.search(symbol + r'\(', declaration): + functions_synop += synop + functions_details += desc + else: + other_synop += synop + other_details += desc + + sig_synop, sig_desc = GetSignals(symbol) + arg_synop, child_arg_synop, style_arg_synop, arg_desc, child_arg_desc, style_arg_desc = GetArgs( + symbol) + ifaces = GetInterfaces(symbol) + impls = GetImplementations(symbol) + prereqs = GetPrerequisites(symbol) + der = GetDerived(symbol) + hierarchy = GetHierarchy(symbol, hierarchy) + + signals_synop += sig_synop + signals_desc += sig_desc + args_synop += arg_synop + child_args_synop += child_arg_synop + style_args_synop += style_arg_synop + args_desc += arg_desc + child_args_desc += child_arg_desc + style_args_desc += style_arg_desc + interfaces += ifaces + implementations += impls + prerequisites += prereqs + derived += der + + # Note that the declaration has been output. + DeclarationOutput[symbol] = True + elif subsection != "Standard" and subsection != "Private": + UndeclaredSymbols[symbol] = True + common.LogWarning(file, line_number, "No declaration found for %s." % symbol) + + num_symbols += 1 + symbol_def_line[symbol] = line_number + + if section_id == '': + if title == '' and filename == '': + common.LogWarning(file, line_number, "Section has no title and no file.") + + # FIXME: one of those would be enough + # filename should be an internal detail for gtk-doc + if title == '': + title = filename + elif filename == '': + filename = title + + filename = filename.replace(' ', '_') + + section_id = SourceSymbolDocs.get(filename + ":Section_Id") + if section_id and section_id.strip() != '': + # Remove trailing blanks and use as is + section_id = section_id.rstrip() + elif CheckIsObject(title): + # GObjects use their class name as the ID. + section_id = common.CreateValidSGMLID(title) + else: + section_id = common.CreateValidSGMLID(MODULE + '-' + title) + + SymbolSection[symbol] = title + SymbolSectionId[symbol] = section_id + + else: + common.LogWarning(file, line_number, "Double symbol entry for %s. " + "Previous occurrence on line %d." % (symbol, symbol_def_line[symbol])) + INPUT.close() + + OutputMissingDocumentation() + OutputUndeclaredSymbols() + OutputUnusedSymbols() + + if options.outputallsymbols: + OutputAllSymbols() + + if options.outputsymbolswithoutsince: + OutputSymbolsWithoutSince() + + for filename in options.expand_content_files.split(): + file_changed = OutputExtraFile(filename) + if file_changed: + changed = True + + return (changed, book_top, book_bottom) + + +def DetermineNamespace(): + """Find common set of characters.""" + name_space = '' + pos = 0 + ratio = 0.0 + while True: + prefix = {} + letter = '' + for symbol in iterkeys(IndexEntriesFull): + if name_space == '' or name_space.lower() in symbol.lower(): + if len(symbol) > pos: + letter = symbol[pos:pos + 1] + # stop prefix scanning + if letter == "_": + # stop on "_" + break + # Should we also stop on a uppercase char, if last was lowercase + # GtkWidget, if we have the 'W' and had the 't' before + # or should we count upper and lowercase, and stop one 2nd uppercase, if we already had a lowercase + # GtkWidget, the 'W' would be the 2nd uppercase and with 't','k' we had lowercase chars before + # need to recound each time as this is per symbol + ul = letter.upper() + if ul in prefix: + prefix[ul] += 1 + else: + prefix[ul] = 1 + + if letter != '' and letter != "_": + maxletter = '' + maxsymbols = 0 + for letter in iterkeys(prefix): + logging.debug("ns prefix: %s: %s", letter, prefix[letter]) + if prefix[letter] > maxsymbols: + maxletter = letter + maxsymbols = prefix[letter] + + ratio = float(len(IndexEntriesFull)) / prefix[maxletter] + logging.debug('most symbols start with %s, that is %f', maxletter, (100 * ratio)) + if ratio > 0.9: + # do another round + name_space += maxletter + + pos += 1 + + else: + ratio = 0.0 + + if ratio < 0.9: + break + return name_space + + +def OutputIndex(basename, apiindex): + """Writes an index that can be included into the main-document into an tag. + + Args: + basename (str): name of the index file without extension + apiindex (dict): the index data + """ + old_index = os.path.join(DB_OUTPUT_DIR, basename + '.xml') + new_index = os.path.join(DB_OUTPUT_DIR, basename + '.new') + lastletter = " " + divopen = 0 + symbol = None + short_symbol = None + + OUTPUT = open(new_index, 'w') + + OUTPUT.write(MakeDocHeader("indexdiv") + "\n\n" % basename) + + logging.info("generate %s index (%d entries) with namespace %s", basename, len(apiindex), NAME_SPACE) + + # do a case insensitive sort while chopping off the prefix + mapped_keys = [ + { + 'original': x, + 'short': re.sub(r'^' + NAME_SPACE + r'\_?(.*)', r'\1', x.upper(), flags=re.I), + } for x in iterkeys(apiindex)] + sorted_keys = sorted(mapped_keys, key=lambda d: (d['short'], d['original'])) + + for key in sorted_keys: + symbol = key['original'] + short = key['short'] + if short != '': + short_symbol = short + else: + short_symbol = symbol + + # generate a short symbol description + symbol_desc = '' + symbol_section = '' + symbol_section_id = '' + symbol_type = '' + if symbol in DeclarationTypes: + symbol_type = DeclarationTypes[symbol].lower() + + if symbol_type == '': + logging.info("trying symbol %s", symbol) + m1 = re.search(r'(.*)::(.*)', symbol) + m2 = re.search(r'(.*):(.*)', symbol) + if m1: + oname = m1.group(1) + osym = m1.group(2) + logging.info(" trying object signal %s:%s in %d signals", oname, osym, len(SignalNames)) + for name in SignalNames: + logging.info(" " + name) + if name == osym: + symbol_type = "object signal" + if oname in SymbolSection: + symbol_section = SymbolSection[oname] + symbol_section_id = SymbolSectionId[oname] + break + elif m2: + oname = m2.group(1) + osym = m2.group(2) + logging.info(" trying object property %s::%s in %d properties", oname, osym, len(ArgNames)) + for name in ArgNames: + logging.info(" " + name) + if name == osym: + symbol_type = "object property" + if oname in SymbolSection: + symbol_section = SymbolSection[oname] + symbol_section_id = SymbolSectionId[oname] + break + else: + if symbol in SymbolSection: + symbol_section = SymbolSection[symbol] + symbol_section_id = SymbolSectionId[symbol] + + if symbol_type != '': + symbol_desc = ", " + symbol_type + if symbol_section != '': + symbol_desc += " in %s" % (symbol_section_id, symbol_section) + # symbol_desc +=" in " + ExpandAbbreviations(symbol, "#symbol_section") + + curletter = short_symbol[0].upper() + ixid = apiindex[symbol] + + logging.info(" add symbol %s with %s to index in section '%s' (derived from %s)", + symbol, ixid, curletter, short_symbol) + + if curletter != lastletter: + lastletter = curletter + + if divopen: + OUTPUT.write("\n") + + OUTPUT.write("%s\n" % curletter) + divopen = True + + OUTPUT.write('%s%s\n' % + (ixid, ixid, symbol, symbol_desc)) + + if divopen: + OUTPUT.write("\n") + + OUTPUT.write("\n") + OUTPUT.close() + + common.UpdateFileIfChanged(old_index, new_index, 0) + + +def OutputSinceIndexes(): + """Generate the 'since' api index files.""" + for version in set(Since.values()): + logging.info("Since : [%s]", version) + index = {x: IndexEntriesSince[x] for x in iterkeys(IndexEntriesSince) if Since[x] == version} + OutputIndex("api-index-" + version, index) + + +def OutputAnnotationGlossary(): + """Writes a glossary of the used annotation terms. + + The glossary file can be included into the main document. + """ + # if there are no annotations used return + if not AnnotationsUsed: + return + + old_glossary = os.path.join(DB_OUTPUT_DIR, "annotation-glossary.xml") + new_glossary = os.path.join(DB_OUTPUT_DIR, "annotation-glossary.new") + lastletter = " " + divopen = False + + # add acronyms that are referenced from acronym text + rerun = True + while rerun: + rerun = False + for annotation in AnnotationsUsed: + if annotation not in AnnotationDefinition: + continue + m = re.search(r'([\w ]+)<\/acronym>', AnnotationDefinition[annotation]) + if m and m.group(1) not in AnnotationsUsed: + AnnotationsUsed[m.group(1)] = 1 + rerun = True + break + + OUTPUT = open(new_glossary, 'w') + + OUTPUT.write('''%s + + Annotation Glossary +''' % MakeDocHeader("glossary")) + + for annotation in sorted(iterkeys(AnnotationsUsed), key=str.lower): + if annotation in AnnotationDefinition: + definition = AnnotationDefinition[annotation] + curletter = annotation[0].upper() + + if curletter != lastletter: + lastletter = curletter + + if divopen: + OUTPUT.write("\n") + + OUTPUT.write("%s\n" % curletter) + divopen = True + + OUTPUT.write(''' + %s + + %s + + +''' % (annotation, annotation, definition)) + + if divopen: + OUTPUT.write("\n") + + OUTPUT.write("\n") + OUTPUT.close() + + common.UpdateFileIfChanged(old_glossary, new_glossary, 0) + + +def ReadKnownSymbols(file): + """Collect the names of non-private symbols from the $MODULE-sections.txt file. + + Args: + file: the $MODULE-sections.txt file + """ + + subsection = '' + + logging.info("Reading: %s", file) + INPUT = open(file) + for line in INPUT: + if line.startswith('#'): + continue + + if line.startswith('
'): + subsection = '' + continue + + m = re.search(r'^', line, flags=re.I) + if m: + subsection = m.group(1) + continue + + if line.startswith(''): + continue + + if re.search(r'^(.*)<\/TITLE>', line): + continue + + m = re.search(r'^<FILE>(.*)<\/FILE>', line) + if m: + KnownSymbols[m.group(1) + ":Long_Description"] = 1 + KnownSymbols[m.group(1) + ":Short_Description"] = 1 + continue + + m = re.search(r'^<INCLUDE>(.*)<\/INCLUDE>', line) + if m: + continue + + m = re.search(r'^<\/SECTION>', line) + if m: + continue + + m = re.search(r'^(\S+)', line) + if m: + symbol = m.group(1) + if subsection != "Standard" and subsection != "Private": + KnownSymbols[symbol] = 1 + else: + KnownSymbols[symbol] = 0 + INPUT.close() + + +def OutputDeclaration(symbol, declaration): + """Returns the formatted documentation block for a symbol. + + Args: + symbol (str): the name of the function/macro/... + declaration (str): the declaration of the function/macro. + + Returns: + str: the formatted documentation + """ + + dtype = DeclarationTypes[symbol] + if dtype == 'MACRO': + return OutputMacro(symbol, declaration) + elif dtype == 'TYPEDEF': + return OutputTypedef(symbol, declaration) + elif dtype == 'STRUCT': + return OutputStruct(symbol, declaration) + elif dtype == 'ENUM': + return OutputEnum(symbol, declaration) + elif dtype == 'UNION': + return OutputUnion(symbol, declaration) + elif dtype == 'VARIABLE': + return OutputVariable(symbol, declaration) + elif dtype == 'FUNCTION': + return OutputFunction(symbol, declaration, dtype) + elif dtype == 'USER_FUNCTION': + return OutputFunction(symbol, declaration, dtype) + else: + sys.exit("Unknown symbol type " + dtype) + + +def OutputSymbolTraits(symbol): + """Returns the Since and StabilityLevel paragraphs for a symbol. + + Args: + symbol (str): the name to describe + + Returns: + str: paragraph or empty string + """ + + desc = '' + + if symbol in Since: + link_id = "api-index-" + Since[symbol] + desc += "<para role=\"since\">Since: <link linkend=\"%s\">%s</link></para>" % (link_id, Since[symbol]) + + if symbol in StabilityLevel: + stability = StabilityLevel[symbol] + AnnotationsUsed[stability] = True + desc += "<para role=\"stability\">Stability Level: <acronym>%s</acronym></para>" % stability + return desc + + +def uri_escape(text): + if text is None: + return None + + # Build a char to hex map + escapes = {chr(i): ("%%%02X" % i) for i in range(256)} + + # Default unsafe characters. RFC 2732 ^(uric - reserved) + def do_escape(char): + return escapes[char] + return re.sub(r"([^A-Za-z0-9\-_.!~*'()]", do_escape, text) + + +def OutputSymbolExtraLinks(symbol): + """Returns extralinks for the symbol (if enabled). + + Args: + symbol (str): the name to describe + + Returns: + str: paragraph or empty string + """ + desc = '' + + if False: # NEW FEATURE: needs configurability + sstr = uri_escape(symbol) + mstr = uri_escape(MODULE) + desc += '''<ulink role="extralinks" url="http://www.google.com/codesearch?q=%s">code search</ulink> +<ulink role="extralinks" url="http://library.gnome.org/edit?module=%s&symbol=%s">edit documentation</ulink> +''' % (sstr, mstr, sstr) + + return desc + + +def OutputSectionExtraLinks(symbol, docsymbol): + desc = '' + + if False: # NEW FEATURE: needs configurability + sstr = uri_escape(symbol) + mstr = uri_escape(MODULE) + dsstr = uri_escape(docsymbol) + desc += '''<ulink role="extralinks" url="http://www.google.com/codesearch?q=%s">code search</ulink> +<ulink role="extralinks" url="http://library.gnome.org/edit?module=%s&symbol=%s">edit documentation</ulink> +''' % (sstr, mstr, dsstr) + return desc + + +def OutputMacro(symbol, declaration): + """Returns the synopsis and detailed description of a macro. + + Args: + symbol (str): the macro name. + declaration (str): the declaration of the macro. + + Returns: + str: the formated docs + """ + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + synop = "<row><entry role=\"define_keyword\">#define</entry><entry role=\"function_name\"><link linkend=\"%s\">%s</link>" % ( + sid, symbol) + + fields = common.ParseMacroDeclaration(declaration, CreateValidSGML) + title = symbol + if len(fields) > 0: + title += '()' + + desc = '<refsect2 id="%s" role="macro"%s>\n<title>%s\n' % (sid, condition, title) + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + if len(fields) > 0: + synop += "()" + + synop += "\n" + + # Don't output the macro definition if is is a conditional macro or it + # looks like a function, i.e. starts with "g_" or "_?gnome_", or it is + # longer than 2 lines, otherwise we get lots of complicated macros like + # g_assert. + if symbol not in DeclarationConditional and not symbol.startswith('g_') \ + and not re.search(r'^_?gnome_', symbol) and declaration.count('\n') < 2: + decl_out = CreateValidSGML(declaration) + desc += "%s\n" % decl_out + else: + desc += "" + "#define".ljust(RETURN_TYPE_FIELD_WIDTH) + symbol + m = re.search(r'^\s*#\s*define\s+\w+(\([^\)]*\))', declaration) + if m: + args = m.group(1) + pad = ' ' * (RETURN_TYPE_FIELD_WIDTH - len("#define ")) + # Align each line so that if should all line up OK. + args = args.replace('\n', '\n' + pad) + desc += CreateValidSGML(args) + + desc += "\n" + + desc += MakeDeprecationNote(symbol) + + parameters = OutputParamDescriptions("MACRO", symbol, fields) + + if symbol in SymbolDocs: + symbol_docs = ConvertMarkDown(symbol, SymbolDocs[symbol]) + desc += symbol_docs + + desc += parameters + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputTypedef(symbol, declaration): + """Returns the synopsis and detailed description of a typedef. + + Args: + symbol (str): the typedef. + declaration (str): the declaration of the typedef, + e.g. 'typedef unsigned int guint;' + + Returns: + str: the formated docs + """ + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + desc = "\n%s\n" % (sid, condition, symbol) + synop = "typedef%s\n" % ( + sid, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + if symbol in DeclarationConditional: + decl_out = CreateValidSGML(declaration) + desc += "%s\n" % decl_out + + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputStruct(symbol, declaration): + """Returns the synopsis and detailed description of a struct. + + We check if it is a object struct, and if so we only output parts of it that + are noted as public fields. We also use a different IDs for object structs, + since the original ID is used for the entire RefEntry. + + Args: + symbol (str): the struct. + declaration (str): the declaration of the struct. + + Returns: + str: the formated docs + """ + is_gtype = False + default_to_public = True + if CheckIsObject(symbol): + logging.info("Found struct gtype: %s", symbol) + is_gtype = True + default_to_public = ObjectRoots[symbol] == 'GBoxed' + + sid = None + condition = None + if is_gtype: + sid = common.CreateValidSGMLID(symbol + "_struct") + condition = MakeConditionDescription(symbol + "_struct") + else: + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + + # Determine if it is a simple struct or it also has a typedef. + has_typedef = False + if symbol in StructHasTypedef or re.search(r'^\s*typedef\s+', declaration): + has_typedef = True + + type_output = None + desc = None + if has_typedef: + # For structs with typedefs we just output the struct name. + type_output = '' + desc = "\n%s\n" % (sid, condition, symbol) + else: + type_output = "struct" + desc = "\nstruct %s\n" % (sid, condition, symbol) + + synop = "%s%s\n" % ( + type_output, sid, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + # Form a pretty-printed, private-data-removed form of the declaration + + decl_out = '' + if re.search(r'^\s*$', declaration): + logging.info("Found opaque struct: %s", symbol) + decl_out = "typedef struct _%s %s;" % (symbol, symbol) + elif re.search(r'^\s*struct\s+\w+\s*;\s*$', declaration): + logging.info("Found opaque struct: %s", symbol) + decl_out = "struct %s;" % symbol + else: + m = re.search( + r'^\s*(typedef\s+)?struct\s*\w*\s*(?:\/\*.*\*\/)?\s*{(.*)}\s*\w*\s*;\s*$', declaration, flags=re.S) + if m: + struct_contents = m.group(2) + + public = default_to_public + new_declaration = '' + + for decl_line in struct_contents.splitlines(): + logging.info("Struct line: %s", decl_line) + m2 = re.search(r'/\*\s*<\s*public\s*>\s*\*/', decl_line) + m3 = re.search(r'/\*\s*<\s*(private|protected)\s*>\s*\*/', decl_line) + if m2: + public = True + elif m3: + public = False + elif public: + new_declaration += decl_line + "\n" + + if new_declaration: + # Strip any blank lines off the ends. + new_declaration = re.sub(r'^\s*\n', '', new_declaration) + new_declaration = re.sub(r'\n\s*$', r'\n', new_declaration) + + if has_typedef: + decl_out = "typedef struct {\n%s} %s;\n" % (new_declaration, symbol) + else: + decl_out = "struct %s {\n%s};\n" % (symbol, new_declaration) + + else: + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Couldn't parse struct:\n%s" % declaration) + + # If we couldn't parse the struct or it was all private, output an + # empty struct declaration. + if decl_out == '': + if has_typedef: + decl_out = "typedef struct _%s %s;" % (symbol, symbol) + else: + decl_out = "struct %s;" % symbol + + decl_out = CreateValidSGML(decl_out) + desc += "%s\n" % decl_out + + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + # Create a table of fields and descriptions + + # FIXME: Inserting  's into the produced type declarations here would + # improve the output in most situations ... except for function + # members of structs! + def pfunc(*args): + return '%s' % (common.CreateValidSGMLID(sid + '.' + args[0]), args[0]) + fields = common.ParseStructDeclaration(declaration, not default_to_public, 0, MakeXRef, pfunc) + params = SymbolParams.get(symbol) + + # If no parameters are filled in, we don't generate the description + # table, for backwards compatibility. + found = False + if params: + found = next((True for p in params.values() if p.strip() != ''), False) + + if found: + field_descrs = params + missing_parameters = '' + unused_parameters = '' + sid = common.CreateValidSGMLID(symbol + ".members") + + desc += '''\nMembers + + + + + + +''' % sid + + for field_name, text in iteritems(fields): + param_annotations = '' + + desc += "%s\n" % text + if field_name in field_descrs: + (field_descr, param_annotations) = ExpandAnnotation(symbol, field_descrs[field_name]) + field_descr = ConvertMarkDown(symbol, field_descr) + # trim + field_descr = re.sub(r'^(\s|\n)+', '', field_descr, flags=re.M | re.S) + field_descr = re.sub(r'(\s|\n)+$', '', field_descr, flags=re.M | re.S) + desc += "%s\n%s\n" % ( + field_descr, param_annotations) + del field_descrs[field_name] + else: + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Field description for %s::%s is missing in source code comment block." % (symbol, field_name)) + if missing_parameters != '': + missing_parameters += ", " + field_name + else: + missing_parameters = field_name + + desc += "\n" + + desc += "\n" + + desc += "\n\n" + for field_name in field_descrs: + # Documenting those standard fields is not required anymore, but + # we don't want to warn if they are documented anyway. + m = re.search(r'(g_iface|parent_instance|parent_class)', field_name) + if m: + continue + + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Field description for %s::%s is not used from source code comment block." % (symbol, field_name)) + if unused_parameters != '': + unused_parameters += ", " + field_name + else: + unused_parameters = field_name + + # remember missing/unused parameters (needed in tmpl-free build) + if missing_parameters != '' and (symbol not in AllIncompleteSymbols): + AllIncompleteSymbols[symbol] = missing_parameters + + if unused_parameters != '' and (symbol not in AllUnusedSymbols): + AllUnusedSymbols[symbol] = unused_parameters + else: + if fields: + if symbol not in AllIncompleteSymbols: + AllIncompleteSymbols[symbol] = "" + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Field descriptions for struct %s are missing in source code comment block." % symbol) + logging.info("Remaining structs fields: " + ':'.join(fields) + "\n") + + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputUnion(symbol, declaration): + """Returns the synopsis and detailed description of a union. + + Args: + symbol (str): the union. + declaration (str): the declaration of the union. + + Returns: + str: the formated docs + """ + is_gtype = False + if CheckIsObject(symbol): + logging.info("Found union gtype: %s", symbol) + is_gtype = True + + sid = None + condition = None + if is_gtype: + sid = common.CreateValidSGMLID(symbol + "_union") + condition = MakeConditionDescription(symbol + "_union") + else: + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + + # Determine if it is a simple struct or it also has a typedef. + has_typedef = False + if symbol in StructHasTypedef or re.search(r'^\s*typedef\s+', declaration): + has_typedef = True + + type_output = None + desc = None + if has_typedef: + # For unions with typedefs we just output the union name. + type_output = '' + desc = "\n%s\n" % (sid, condition, symbol) + else: + type_output = "union" + desc = "\nunion %s\n" % (sid, condition, symbol) + + synop = "%s%s\n" % ( + type_output, sid, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + # Create a table of fields and descriptions + + # FIXME: Inserting  's into the produced type declarations here would + # improve the output in most situations ... except for function + # members of structs! + def pfunc(*args): + return '%s' % (common.CreateValidSGMLID(sid + '.' + args[0]), args[0]) + fields = common.ParseStructDeclaration(declaration, 0, 0, MakeXRef, pfunc) + params = SymbolParams.get(symbol) + + # If no parameters are filled in, we don't generate the description + # table, for backwards compatibility + found = False + if params: + found = next((True for p in params.values() if p.strip() != ''), False) + + logging.debug('Union %s has %d entries, found=%d, has_typedef=%d', symbol, len(fields), found, has_typedef) + + if found: + field_descrs = params + missing_parameters = '' + unused_parameters = '' + sid = common.CreateValidSGMLID('%s.members' % symbol) + + desc += '''\nMembers + + + + + + +''' % sid + + for field_name, text in iteritems(fields): + param_annotations = '' + + desc += "%s\n" % text + if field_name in field_descrs: + (field_descr, param_annotations) = ExpandAnnotation(symbol, field_descrs[field_name]) + field_descr = ConvertMarkDown(symbol, field_descr) + + # trim + field_descr = re.sub(r'^(\s|\n)+', '', field_descr, flags=re.M | re.S) + field_descr = re.sub(r'(\s|\n)+$', '', field_descr, flags=re.M | re.S) + desc += "%s\n%s\n" % ( + field_descr, param_annotations) + del field_descrs[field_name] + else: + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Field description for %s::%s is missing in source code comment block." % (symbol, field_name)) + if missing_parameters != '': + missing_parameters += ", " + field_name + else: + missing_parameters = field_name + + desc += "\n" + + desc += "\n" + + desc += "\n" + for field_name in field_descrs: + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Field description for %s::%s is not used from source code comment block." % (symbol, field_name)) + if unused_parameters != '': + unused_parameters += ", " + field_name + else: + unused_parameters = field_name + + # remember missing/unused parameters (needed in tmpl-free build) + if missing_parameters != '' and (symbol not in AllIncompleteSymbols): + AllIncompleteSymbols[symbol] = missing_parameters + + if unused_parameters != '' and (symbol not in AllUnusedSymbols): + AllUnusedSymbols[symbol] = unused_parameters + else: + if len(fields) > 0: + if symbol not in AllIncompleteSymbols: + AllIncompleteSymbols[symbol] = "" + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Field descriptions for union %s are missing in source code comment block." % symbol) + logging.info("Remaining union fields: " + ':'.join(fields) + "\n") + + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputEnum(symbol, declaration): + """Returns the synopsis and detailed description of a enum. + + Args: + symbol (str): the enum. + declaration (str): the declaration of the enum. + + Returns: + str: the formated docs + """ + is_gtype = False + if CheckIsObject(symbol): + logging.info("Found enum gtype: %s", symbol) + is_gtype = True + + sid = None + condition = None + if is_gtype: + sid = common.CreateValidSGMLID(symbol + "_enum") + condition = MakeConditionDescription(symbol + "_enum") + else: + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + + synop = "enum%s\n" % ( + sid, symbol) + desc = "\nenum %s\n" % (sid, condition, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + # Create a table of fields and descriptions + + fields = common.ParseEnumDeclaration(declaration) + params = SymbolParams.get(symbol) + + # If nothing at all is documented log a single summary warning at the end. + # Otherwise, warn about each undocumented item. + + found = False + if params: + found = next((True for p in params.values() if p.strip() != ''), False) + field_descrs = params + else: + field_descrs = {} + + missing_parameters = '' + unused_parameters = '' + + sid = common.CreateValidSGMLID("%s.members" % symbol) + desc += '''\nMembers + + + + + + +''' % sid + + for field_name in fields: + field_descr = field_descrs.get(field_name) + param_annotations = '' + + sid = common.CreateValidSGMLID(field_name) + condition = MakeConditionDescription(field_name) + desc += "%s\n" % ( + sid, field_name) + if field_descr: + field_descr, param_annotations = ExpandAnnotation(symbol, field_descr) + field_descr = ConvertMarkDown(symbol, field_descr) + desc += "%s\n%s\n" % ( + field_descr, param_annotations) + del field_descrs[field_name] + else: + if found: + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Value description for %s::%s is missing in source code comment block." % (symbol, field_name)) + if missing_parameters != '': + missing_parameters += ", " + field_name + else: + missing_parameters = field_name + desc += "\n" + desc += "\n" + + desc += "\n" + for field_name in field_descrs: + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Value description for %s::%s is not used from source code comment block." % (symbol, field_name)) + if unused_parameters != '': + unused_parameters += ", " + field_name + else: + unused_parameters = field_name + + # remember missing/unused parameters (needed in tmpl-free build) + if missing_parameters != '' and (symbol not in AllIncompleteSymbols): + AllIncompleteSymbols[symbol] = missing_parameters + + if unused_parameters != '' and (symbol not in AllUnusedSymbols): + AllUnusedSymbols[symbol] = unused_parameters + + if not found: + if len(fields) > 0: + if symbol not in AllIncompleteSymbols: + AllIncompleteSymbols[symbol] = "" + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Value descriptions for %s are missing in source code comment block." % symbol) + + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputVariable(symbol, declaration): + """Returns the synopsis and detailed description of a variable. + + Args: + symbol (str): the extern'ed variable. + declaration (str): the declaration of the variable. + + Returns: + str: the formated docs + """ + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + + logging.info("ouputing variable: '%s' '%s'", symbol, declaration) + + type_output = None + m1 = re.search( + r'^\s*extern\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*;', declaration) + m2 = re.search( + r'\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)(\s*)(const\s+)*([A-Za-z]\w*)\s*=', declaration) + if m1: + mod1 = m1.group(1) or '' + ptr = m1.group(3) or '' + space = m1.group(4) or '' + mod2 = m1.group(5) or '' + type_output = "extern %s%s%s%s" % (mod1, ptr, space, mod2) + elif m2: + mod1 = m2.group(1) or '' + ptr = m2.group(3) or '' + space = m2.group(4) or '' + mod2 = m2.group(5) or '' + type_output = '%s%s%s%s' % (mod1, ptr, space, mod2) + else: + type_output = "extern" + + synop = "%s%s\n" % ( + type_output, sid, symbol) + + desc = "\n%s\n" % (sid, condition, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + decl_out = CreateValidSGML(declaration) + desc += "%s\n" % decl_out + + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + if symbol in SymbolAnnotations: + param_desc = SymbolAnnotations[symbol] + param_annotations = '' + (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc) + if param_annotations != '': + desc += "\n%s" % param_annotations + + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputFunction(symbol, declaration, symbol_type): + """Returns the synopsis and detailed description of a function. + + Args: + symbol (str): the function. + declaration (str): the declaration of the function. + + Returns: + str: the formated docs + """ + sid = common.CreateValidSGMLID(symbol) + condition = MakeConditionDescription(symbol) + + # Take out the return type + # $1 $2 $3 + regex = r'\s*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|enum\s+)*)(\w+)(\s*\**\s*(?:const|G_CONST_RETURN)?\s*\**\s*(?:restrict)?\s*)<\/RETURNS>\n' + m = re.search(regex, declaration) + declaration = re.sub(regex, '', declaration) + type_modifier = m.group(1) or '' + type = m.group(2) + pointer = m.group(3) + pointer = pointer.rstrip() + xref = MakeXRef(type, tagify(type, "returnvalue")) + start = '' + # if (symbol_type == 'USER_FUNCTION') + # start = "typedef " + # + + # We output const rather than G_CONST_RETURN. + type_modifier = re.sub(r'G_CONST_RETURN', 'const', type_modifier) + pointer = re.sub(r'G_CONST_RETURN', 'const', pointer) + pointer = re.sub(r'^\s+', ' ', pointer) + + ret_type_output = "%s%s%s%s\n" % (start, type_modifier, xref, pointer) + + indent_len = len(symbol) + 2 + char1 = char2 = char3 = '' + if symbol_type == 'USER_FUNCTION': + indent_len += 3 + char1 = "(" + char2 = "*" + char3 = ")" + + symbol_output = "%s%s%s%s" % (char1, sid, char2, symbol, char3) + if indent_len < MAX_SYMBOL_FIELD_WIDTH: + symbol_desc_output = "%s%s%s%s " % (char1, char2, symbol, char3) + else: + indent_len = MAX_SYMBOL_FIELD_WIDTH - 8 + symbol_desc_output = ('%s%s%s%s\n' % (char1, char2, symbol, char3)) + (' ' * (indent_len - 1)) + + synop = "%s%s ()\n" % ( + ret_type_output, symbol_output) + + desc = "\n%s ()\n" % (sid, condition, symbol) + + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + desc += "%s%s(" % (ret_type_output, symbol_desc_output) + + def tagfun(*args): + return tagify(args[0], "parameter") + + fields = common.ParseFunctionDeclaration(declaration, MakeXRef, tagfun) + + first = True + for field_name in fields.values(): + if first: + desc += field_name + first = False + else: + desc += ",\n" + (' ' * indent_len) + field_name + + desc += ");\n" + + desc += MakeDeprecationNote(symbol) + + if symbol in SymbolDocs: + desc += ConvertMarkDown(symbol, SymbolDocs[symbol]) + + if symbol in SymbolAnnotations: + param_desc = SymbolAnnotations[symbol] + (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc) + if param_annotations != '': + desc += "\n%s" % param_annotations + + desc += OutputParamDescriptions("FUNCTION", symbol, iterkeys(fields)) + desc += OutputSymbolTraits(symbol) + desc += "\n" + return (synop, desc) + + +def OutputParamDescriptions(symbol_type, symbol, fields): + """Returns the DocBook output describing the parameters of a symbol. + + This can be used for functions, macros or signal handlers. + + Args: + symbol_type (str): 'FUNCTION', 'MACRO' or 'SIGNAL'. Signal + handlers have an implicit user_data parameter last. + symbol (str): the name of the symbol being described. + fields (list): parsed fields from the declaration, used to determine + undocumented/unused entries + + Returns: + str: the formated parameter docs + """ + output = '' + num_params = 0 + field_descrs = None + + if fields: + field_descrs = [f for f in fields if f not in ['void', 'Returns']] + else: + field_descrs = [] + + params = SymbolParams.get(symbol) + logging.info("param_desc(%s, %s) = %s", symbol_type, symbol, str(params)) + # This might be an empty dict, but for SIGNALS we append the user_data docs. + # TODO(ensonic): maybe create that docstring in GetSignals() + if params is not None: + returns = '' + params_desc = '' + missing_parameters = '' + unused_parameters = '' + + for param_name, param_desc in iteritems(params): + (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc) + param_desc = ConvertMarkDown(symbol, param_desc) + # trim + param_desc = re.sub(r'^(\s|\n)+', '', param_desc, flags=re.M | re.S) + param_desc = re.sub(r'(\s|\n)+$', '', param_desc, flags=re.M | re.S) + if param_name == "Returns": + returns = param_desc + if param_annotations != '': + returns += "\n%s" % param_annotations + + elif param_name == "void": + # FIXME: &common.LogWarning()? + logging.info("!!!! void in params for %s?\n", symbol) + else: + if fields: + if param_name not in field_descrs: + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Parameter description for %s::%s is not used from source code comment block." % (symbol, param_name)) + if unused_parameters != '': + unused_parameters += ", " + param_name + else: + unused_parameters = param_name + else: + field_descrs.remove(param_name) + + if param_desc != '': + params_desc += "%s\n%s\n%s\n" % ( + param_name, param_desc, param_annotations) + num_params += 1 + + for param_name in field_descrs: + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Parameter description for %s::%s is missing in source code comment block." % (symbol, param_name)) + if missing_parameters != '': + missing_parameters += ", " + param_name + else: + missing_parameters = param_name + + # Signals have an implicit user_data parameter which we describe. + if symbol_type == "SIGNAL": + params_desc += "user_data\nuser data set when the signal handler was connected.\n\n" + + # Start a table if we need one. + if params_desc != '': + sid = common.CreateValidSGMLID("%s.parameters" % symbol) + + output += '''\nParameters + + + + + + +''' % sid + output += params_desc + output += "\n" + + # Output the returns info last + if returns != '': + sid = common.CreateValidSGMLID("%s.returns" % symbol) + + output += '''\nReturns +''' % sid + output += returns + output += "\n" + + # remember missing/unused parameters (needed in tmpl-free build) + if missing_parameters != '' and (symbol not in AllIncompleteSymbols): + AllIncompleteSymbols[symbol] = missing_parameters + + if unused_parameters != '' and (symbol not in AllUnusedSymbols): + AllUnusedSymbols[symbol] = unused_parameters + + if num_params == 0 and fields and field_descrs: + if symbol not in AllIncompleteSymbols: + AllIncompleteSymbols[symbol] = "" + return output + + +def ParseStabilityLevel(stability, file, line, message): + """Parses a stability level and outputs a warning if it isn't valid. + Args: + stability (str): the stability text. + file, line: context for error message + message: description of where the level is from, to use in any error message. + Returns: + str: the parsed stability level string. + """ + sl = stability.strip().lower() + if sl == 'stable': + stability = "Stable" + elif sl == 'unstable': + stability = "Unstable" + elif sl == 'private': + stability = "Private" + else: + common.LogWarning(file, line, "%s is %s." % (message, stability) + + "It should be one of these: Stable, Unstable, or Private.") + return stability + + +def OutputDBFile(file, title, section_id, includes, functions_synop, other_synop, functions_details, other_details, signals_synop, signals_desc, args_synop, args_desc, hierarchy, interfaces, implementations, prerequisites, derived, file_objects): + """Outputs the final DocBook file for one section. + + Args: + file (str): the name of the file. + title (str): the title from the $MODULE-sections.txt file + section_id (str): the id to use for the toplevel tag. + includes (str): comma-separates list of include files added at top of + synopsis, with '<' '>' around them (if not already enclosed in ''). + functions_synop (str): the DocBook for the Functions Synopsis part. + other_synop (str): the DocBook for the Types and Values Synopsis part. + functions_details (str): the DocBook for the Functions Details part. + other_details (str): the DocBook for the Types and Values Details part. + signal_synop (str): the DocBook for the Signal Synopsis part + signal_desc (str): the DocBook for the Signal Description part + args_synop (str): the DocBook for the Arg Synopsis part + args_desc (str): the DocBook for the Arg Description part + hierarchy (str): the DocBook for the Object Hierarchy part + interfaces (str): the DocBook for the Interfaces part + implementations (str): the DocBook for the Known Implementations part + prerequisites (str): the DocBook for the Prerequisites part + derived (str): the DocBook for the Derived Interfaces part + file_objects (list): objects in this file + + Returns: + bool: True if the docs where updated + """ + + logging.info("Output docbook for file %s with title '%s'", file, title) + + # The edited title overrides the one from the sections file. + new_title = SymbolDocs.get(file + ":Title") + if new_title and not new_title.strip() == '': + title = new_title + logging.info("Found title: %s", title) + + short_desc = SymbolDocs.get(file + ":Short_Description") + if not short_desc or short_desc.strip() == '': + short_desc = '' + else: + # Don't use ConvertMarkDown here for now since we don't want blocks + short_desc = ExpandAbbreviations(title + ":Short_description", short_desc) + logging.info("Found short_desc: %s", short_desc) + + long_desc = SymbolDocs.get(file + ":Long_Description") + if not long_desc or long_desc.strip() == '': + long_desc = '' + else: + long_desc = ConvertMarkDown(title + ":Long_description", long_desc) + logging.info("Found long_desc: %s", long_desc) + + see_also = SymbolDocs.get(file + ":See_Also") + if not see_also or re.search(r'^\s*()?\s*()?\s*$', see_also): + see_also = '' + else: + see_also = ConvertMarkDown(title + ":See_Also", see_also) + logging.info("Found see_also: %s", see_also) + + if see_also: + see_also = "\nSee Also\n%s\n\n" % (section_id, see_also) + + stability = SymbolDocs.get(file + ":Stability_Level") + if not stability or re.search(r'^\s*$', stability): + stability = '' + else: + line_number = GetSymbolSourceLine(file + ":Stability_Level") + stability = ParseStabilityLevel(stability, file, line_number, "Section stability level") + logging.info("Found stability: %s", stability) + + if stability: + AnnotationsUsed[stability] = 1 + stability = "\nStability Level\n%s, unless otherwise indicated\n\n" % ( + section_id, stability) + elif DEFAULT_STABILITY: + AnnotationsUsed[DEFAULT_STABILITY] = 1 + stability = "\nStability Level\n%s, unless otherwise indicated\n\n" % ( + section_id, DEFAULT_STABILITY) + + image = SymbolDocs.get(file + ":Image") + if not image or re.search(r'^\s*$', image): + image = '' + else: + image = image.strip() + + format = None + + il = image.lower() + if re.search(r'jpe?g$', il): + format = "format='JPEG'" + elif il.endswith('png'): + format = "format='PNG'" + elif il.endswith('svg'): + format = "format='SVG'" + else: + format = '' + + image = " \n" % (image, format) + + include_output = '' + if includes: + include_output += "Includes" % section_id + for include in includes.split(','): + if re.search(r'^\".+\"$', include): + include_output += "#include %s\n" % include + else: + include = re.sub(r'^\s+|\s+$', '', include, flags=re.S) + include_output += "#include <%s>\n" % include + + include_output += "\n" + + extralinks = OutputSectionExtraLinks(title, "Section:%s" % file) + + old_db_file = os.path.join(DB_OUTPUT_DIR, file + '.xml') + new_db_file = os.path.join(DB_OUTPUT_DIR, file + '.xml.new') + + OUTPUT = open(new_db_file, 'w') + + object_anchors = '' + for fobject in file_objects: + if fobject == section_id: + continue + sid = common.CreateValidSGMLID(fobject) + logging.info("Adding anchor for %s\n", fobject) + object_anchors += "" % sid + + # Make sure we produce valid docbook + if not functions_details: + functions_details = "" + + # We used to output this, but is messes up our common.UpdateFileIfChanged code + # since it changes every day (and it is only used in the man pages): + # "" + + OUTPUT.write(REFENTRY.substitute({ + 'args_desc': args_desc, + 'args_synop': args_synop, + 'derived': derived, + 'extralinks': extralinks, + 'functions_details': functions_details, + 'functions_synop': functions_synop, + 'header': MakeDocHeader('refentry'), + 'hierarchy': hierarchy, + 'image': image, + 'include_output': include_output, + 'interfaces': interfaces, + 'implementations': implementations, + 'long_desc': long_desc, + 'object_anchors': object_anchors, + 'other_details': other_details, + 'other_synop': other_synop, + 'prerequisites': prerequisites, + 'section_id': section_id, + 'see_also': see_also, + 'signals_desc': signals_desc, + 'signals_synop': signals_synop, + 'short_desc': short_desc, + 'stability': stability, + 'title': title, + 'MODULE': MODULE.upper(), + })) + OUTPUT.close() + + return common.UpdateFileIfChanged(old_db_file, new_db_file, 0) + + +def OutputProgramDBFile(program, section_id): + """Outputs the final DocBook file for one program. + + Args: + file (str): the name of the file. + section_id (str): the id to use for the toplevel tag. + + Returns: + bool: True if the docs where updated + """ + logging.info("Output program docbook for %s", program) + + short_desc = SourceSymbolDocs.get(program + ":Short_Description") + if not short_desc or short_desc.strip() == '': + short_desc = '' + else: + # Don't use ConvertMarkDown here for now since we don't want blocks + short_desc = ExpandAbbreviations(program, short_desc) + logging.info("Found short_desc: %s", short_desc) + + synopsis = SourceSymbolDocs.get(program + ":Synopsis") + if synopsis and synopsis.strip() != '': + items = synopsis.split(' ') + for i in range(0, len(items)): + parameter = items[i] + choice = "plain" + rep = '' + + # first parameter is the command name + if i == 0: + synopsis = "%s\n" % parameter + continue + + # square brackets indicate optional parameters, curly brackets + # indicate required parameters ("plain" parameters are also + # mandatory, but do not get extra decoration) + m1 = re.search(r'^\[(.+?)\]$', parameter) + m2 = re.search(r'^\{(.+?)\}$', parameter) + if m1: + choice = "opt" + parameter = m1.group(1) + elif m2: + choice = "req" + parameter = m2.group(1) + + # parameters ending in "..." are repeatable + if parameter.endswith('...'): + rep = ' rep=\"repeat\"' + parameter = parameter[:-3] + + # italic parameters are replaceable parameters + parameter = re.sub(r'\*(.+?)\*', r'\1', parameter) + + synopsis += "" % (choice, rep) + synopsis += parameter + synopsis += "\n" + + logging.info("Found synopsis: %s", synopsis) + else: + synopsis = "%s" % program + + long_desc = SourceSymbolDocs.get(program + ":Long_Description") + if not long_desc or long_desc.strip() == '': + long_desc = '' + else: + long_desc = ConvertMarkDown("%s:Long_description" % program, long_desc) + logging.info("Found long_desc: %s", long_desc) + + options = '' + o = program + ":Options" + if o in SourceSymbolDocs: + opts = SourceSymbolDocs[o].split('\t') + + logging.info('options: %d, %s', len(opts), str(opts)) + + options = "\nOptions\n\n" + for k in range(0, len(opts), 2): + opt_desc = opts[k + 1] + + opt_desc = re.sub(r'\*(.+?)\*', r'\1', opt_desc) + + options += "\n" + opt_names = opts[k].split(',') + for i in range(len(opt_names)): + prefix = ', ' if i > 0 else '' + # italic parameters are replaceable parameters + opt_name = re.sub(r'\*(.+?)\*', r'\1', opt_names[i]) + + options += "%s\n" % (prefix, opt_name) + + options += "\n" + options += "%s\n" % opt_desc + options += "\n" + + options += "\n" + + exit_status = SourceSymbolDocs.get(program + ":Returns") + if exit_status and exit_status != '': + exit_status = ConvertMarkDown("%s:Returns" % program, exit_status) + exit_status = "\nExit Status\n%s\n\n" % ( + section_id, exit_status) + else: + exit_status = '' + + see_also = SourceSymbolDocs.get(program + ":See_Also") + if not see_also or re.search(r'^\s*()?\s*()?\s*$', see_also): + see_also = '' + else: + see_also = ConvertMarkDown("%s:See_Also" % program, see_also) + logging.info("Found see_also: %s", see_also) + + if see_also: + see_also = "\nSee Also\n%s\n\n" % (section_id, see_also) + + old_db_file = os.path.join(DB_OUTPUT_DIR, program + ".xml") + new_db_file = os.path.join(DB_OUTPUT_DIR, program + ".xml.new") + + OUTPUT = open(new_db_file, 'w') + + OUTPUT.write('''%s + + +%s +1 +User Commands + + +%s +%s + + +%s + + +Description +%s + +%s%s%s + +''' % (MakeDocHeader("refentry"), section_id, section_id, program, program, short_desc, synopsis, section_id, long_desc, options, exit_status, see_also)) + OUTPUT.close() + + return common.UpdateFileIfChanged(old_db_file, new_db_file, 0) + + +def OutputExtraFile(file): + """Copies an "extra" DocBook file into the output directory, expanding abbreviations. + + Args: + file (str): the source file. + + Returns: + bool: True if the docs where updated + """ + + basename = os.path.basename(file) + + old_db_file = os.path.join(DB_OUTPUT_DIR, basename) + new_db_file = os.path.join(DB_OUTPUT_DIR, basename + ".new") + + contents = open(file).read() + + OUTPUT = open(new_db_file, 'w') + OUTPUT.write(ExpandAbbreviations(basename + " file", contents)) + OUTPUT.close() + + return common.UpdateFileIfChanged(old_db_file, new_db_file, 0) + + +def GetDocbookHeader(main_file): + if os.path.exists(main_file): + INPUT = open(main_file) + header = '' + for line in INPUT: + if re.search(r'^\s*<(book|chapter|article)', line): + # check that the top-level tagSYSTEM or the doctype decl contain the xinclude namespace decl + if not re.search(r'http:\/\/www.w3.org\/200[13]\/XInclude', line) and \ + not re.search(r'http:\/\/www.w3.org\/200[13]\/XInclude', header, flags=re.MULTILINE): + header = '' + break + + # if there are SYSTEM ENTITIES here, we should prepend "../" to the path + # FIXME: not sure if we can do this now, as people already work-around the problem + # r'#', r''; + line = re.sub( + r'', r'', line) + header += line + INPUT.close() + header = header.strip() + else: + header = ''' + + + %gtkdocentities; +]>''' + return header + + +def OutputBook(main_file, book_top, book_bottom): + """Outputs the entities that need to be included into the main docbook file for the module. + + Args: + book_top (str): the declarations of the entities, which are added + at the top of the main docbook file. + book_bottom (str): the entities, which are added in the main docbook + file at the desired position. + """ + + old_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.top") + new_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.top.new") + + OUTPUT = open(new_file, 'w') + OUTPUT.write(book_top) + OUTPUT.close() + + common.UpdateFileIfChanged(old_file, new_file, 0) + + old_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.bottom") + new_file = os.path.join(DB_OUTPUT_DIR, MODULE + "-doc.bottom.new") + + OUTPUT = open(new_file, 'w') + OUTPUT.write(book_bottom) + OUTPUT.close() + + common.UpdateFileIfChanged(old_file, new_file, 0) + + # If the main docbook file hasn't been created yet, we create it here. + # The user can tweak it later. + if main_file and not os.path.exists(main_file): + OUTPUT = open(main_file, 'w') + + logging.info("no master doc, create default one at: " + main_file) + + OUTPUT.write('''%s + + + &package_name; Reference Manual + + for &package_string;. + The latest version of this documentation can be found on-line at + http://[SERVER]/&package_name;/. + + + + + [Insert title here] + %s + +''' % (MakeDocHeader("book"), book_bottom)) + if os.path.exists('xml/tree_index.sgml'): + OUTPUT.write(''' + Object Hierarchy + + +''') + else: + OUTPUT.write(''' +''') + + OUTPUT.write(''' + API Index + + + + Index of deprecated API + + +''') + for version in set(Since.values()): + dash_version = version.replace('.', '-') + OUTPUT.write(''' + Index of new API in %s + + +''' % (dash_version, version, version, version)) + + if AnnotationsUsed: + OUTPUT.write(''' +''') + else: + OUTPUT.write(''' +''') + + OUTPUT.write(''' +''') + + OUTPUT.close() + + +def CreateValidSGML(text): + """Turn any chars which are used in XML into entities. + + e.g. '<' into '<' + + Args: + text (str): the text to turn into proper XML. + + Returns: + str: escaped input + """ + + text = text.replace('&', '&') # Do this first, or the others get messed up. + text = text.replace('<', '<') + text = text.replace('>', '>') + # browsers render single tabs inconsistently + text = re.sub(r'([^\s])\t([^\s])', r'\1 \2', text) + return text + + +def ConvertSGMLChars(symbol, text): + """Escape XML chars. + + This is used for text in source code comment blocks, to turn + chars which are used in XML into entities, e.g. '<' into + <'. Depending on INLINE_MARKUP_MODE, this is done + unconditionally or only if the character doesn't seem to be + part of an XML construct (tag or entity reference). + Args: + text (str): the text to turn into proper XML. + + Returns: + str: escaped input + """ + + if INLINE_MARKUP_MODE: + # For the XML/SGML mode only convert to entities outside CDATA sections. + return ModifyXMLElements(text, symbol, + "]*>", + ConvertSGMLCharsEndTag, + ConvertSGMLCharsCallback) + # For the simple non-sgml mode, convert to entities everywhere. + + text = re.sub(r'&(?![a-zA-Z#]+;)', r'&', text) # Do this first, or the others get messed up. + text = re.sub(r'<', r'<', text) + # Allow '>' at beginning of string for blockquote markdown + text = re.sub(r'''(?<=[^\w\n"'\/-])>''', r'>', text) + + return text + + +def ConvertSGMLCharsEndTag(start_tag): + if start_tag == '" + return "" + + +def ConvertSGMLCharsCallback(text, symbol, tag): + if re.search(r'^ specially here. + return ModifyXMLElements(text, symbol, + "' at beginning of string for blockquote markdown + text = re.sub(r'''(?<=[^\w\n"'\/-])>''', r'>', text) + + # Handle "#include " + text = re.sub(r'#include(\s+)<([^>]+)>', r'#include\1<\2>', text) + + return text + + +def ConvertSGMLCharsCallback2(text, symbol, tag): + # If we're not in CDATA convert to entities. + # We could handle differently, though I'm not sure it helps. + if tag == '': + # replace only if its not a tag + text = re.sub(r'&(?![a-zA-Z#]+;)', r'&', text) # Do this first, or the others get messed up. + text = re.sub(r'<(?![a-zA-Z\/!])', r'<', text) + text = re.sub(r'''(?''', r'>', text) + # Handle "#include " + text = re.sub(r'/#include(\s+)<([^>]+)>', r'#include\1<\2>', text) + + return text + + +def ExpandAnnotation(symbol, param_desc): + """This turns annotations into acronym tags. + Args: + symbol (str): the symbol being documented, for error messages. + param_desc (str): the text to expand. + + Returns: + str: the remaining param_desc + str: the formatted annotations + """ + param_annotations = '' + + # look for annotations at the start of the comment part + # function level annotations don't end with a colon ':' + m = re.search(r'^\s*\((.*?)\)(:|$)', param_desc) + if m: + param_desc = param_desc[m.end():] + + annotations = re.split(r'\)\s*\(', m.group(1)) + logging.info("annotations for %s: '%s'\n", symbol, m.group(1)) + for annotation in annotations: + # need to search for the longest key-match in %AnnotationDefinition + match_length = 0 + match_annotation = '' + + for annotationdef in AnnotationDefinition: + if annotation.startswith(annotationdef): + if len(annotationdef) > match_length: + match_length = len(annotationdef) + match_annotation = annotationdef + + annotation_extra = '' + if match_annotation != '': + m = re.search(match_annotation + r'\s+(.*)', annotation) + if m: + annotation_extra = " " + m.group(1) + + AnnotationsUsed[match_annotation] = 1 + param_annotations += "[%s%s]" % (match_annotation, annotation_extra) + else: + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "unknown annotation \"%s\" in documentation for %s." % (annotation, symbol)) + param_annotations += "[%s]" % annotation + + param_desc = param_desc.strip() + m = re.search(r'^(.*?)\.*\s*$', param_desc, flags=re.S) + param_desc = m.group(1) + '. ' + + if param_annotations != '': + param_annotations = "%s" % param_annotations + + return (param_desc, param_annotations) + + +def ExpandAbbreviations(symbol, text): + """Expand the shortcut notation for symbol references. + + This turns the abbreviations function(), macro(), @param, %constant, and #symbol + into appropriate DocBook markup. CDATA sections and parts + are skipped. + + Args: + symbol (str): the symbol being documented, for error messages. + text (str): the text to expand. + + Returns: + str: the expanded text + """ + # Note: This is a fallback and normally done in the markdown parser + + logging.debug('expand abbreviations for "%s", text: [%s]', symbol, text) + m = re.search(r'\|\[[^\n]*\n(.*)\]\|', text, flags=re.M | re.S) + if m: + logging.debug('replaced entities in code block') + text = text[:m.start(1)] + md_to_db.ReplaceEntities(m.group(1)) + text[m.end(1):] + + # Convert "|[" and "]|" into the start and end of program listing examples. + # Support \[ modifiers + text = re.sub(r'\|\[', r'', text) + + # keep CDATA unmodified, preserve ulink tags (ideally we preseve all tags + # as such) + return ModifyXMLElements(text, symbol, + "]*>|]*>|" + if start_tag == "' + m = re.search(r'<(\w+)', start_tag) + if m: + return "" % m.group(1) + + logging.warning('no end tag for "%s"', start_tag) + return '' + + +def ExpandAbbreviationsCallback(text, symbol, tag): + # Called inside or outside each CDATA or section. + if tag.startswith(r'^ sections, so we expand + # any gtk-doc abbreviations. + + # Convert '@param()' + # FIXME: we could make those also links ($symbol.$2), but that would be less + # useful as the link target is a few lines up or down + text = re.sub(r'(\A|[^\\])\@(\w+((\.|->)\w+)*)\s*\(\)', r'\1\2()', text) + + # Convert 'function()' or 'macro()'. + # if there is abc_*_def() we don't want to make a link to _def() + # FIXME: also handle abc(def(....)) : but that would need to be done recursively :/ + def f1(m): + return m.group(1) + MakeXRef(m.group(2), tagify(m.group(2) + "()", "function")) + text = re.sub(r'([^\*.\w])(\w+)\s*\(\)', f1, text) + # handle #Object.func() + text = re.sub(r'(\A|[^\\])#([\w\-:\.]+[\w]+)\s*\(\)', f1, text) + + # Convert '@param', but not '\@param'. + text = re.sub(r'(\A|[^\\])\@(\w+((\.|->)\w+)*)', r'\1\2', text) + text = re.sub(r'/\\\@', r'\@', text) + + # Convert '%constant', but not '\%constant'. + # Also allow negative numbers, e.g. %-1. + def f2(m): + return m.group(1) + MakeXRef(m.group(2), tagify(m.group(2), "literal")) + text = re.sub(r'(\A|[^\\])\%(-?\w+)', f2, text) + text = re.sub(r'\\\%', r'\%', text) + + # Convert '#symbol', but not '\#symbol'. + def f3(m): + return m.group(1) + MakeHashXRef(m.group(2), "type") + text = re.sub(r'(\A|[^\\])#([\w\-:\.]+[\w]+)', f3, text) + text = re.sub(r'\\#', '#', text) + + return text + + +def ExpandAbbreviationsCallback2(text, symbol, tag): + # This is called inside a + if tag == '': + # We are inside a but outside any CDATA sections, + # so we expand any gtk-doc abbreviations. + # FIXME: why is this different from &ExpandAbbreviationsCallback(), + # why not just call it + text = re.sub(r'#(\w+)', lambda m: '%s;' % MakeHashXRef(m.group(1), ''), text) + elif tag == ". + + Args: + text (str): the text. + symbol (str): the symbol currently being documented (only used for + error messages). + start_tag_regexp (str): the regular expression to match start tags. + e.g. "]*>" to + match CDATA sections or programlisting elements. + end_tag_func (func): function which is passed the matched start tag + and should return the appropriate end tag string + regexp. + callback - callback called with each part of the text. It is + called with a piece of text, the symbol being + documented, and the matched start tag or '' if the text + is outside the XML elements being matched. + + Returns: + str: modified text + """ + before_tag = start_tag = end_tag_regexp = end_tag = None + result = '' + + logging.debug('modify xml for symbol: %s, regex: %s, text: [%s]', symbol, start_tag_regexp, text) + + m = re.search(start_tag_regexp, text, flags=re.S) + while m: + before_tag = text[:m.start()] # Prematch for last successful match string + start_tag = m.group(0) # Last successful match + text = text[m.end():] # Postmatch for last successful match string + # get the matching end-tag for current tag + end_tag_regexp = end_tag_func(start_tag) + + logging.debug('symbol: %s matched start: %s, end_tag: %s, text: [%s]', symbol, start_tag, end_tag_regexp, text) + + logging.debug('converting before tag: [%s]', before_tag) + result += callback(before_tag, symbol, '') + result += start_tag + + m2 = re.search(end_tag_regexp, text, flags=re.S) + if m2: + before_tag = text[:m2.start()] + end_tag = m2.group(0) + text = text[m2.end():] + + logging.debug('symbol: %s matched end %s: text: [%s]', symbol, end_tag, text) + + result += callback(before_tag, symbol, start_tag) + result += end_tag + else: + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Can't find tag end: %s in docs for: %s." % (end_tag_regexp, symbol)) + # Just assume it is all inside the tag. + result += callback(text, symbol, start_tag) + text = '' + m = re.search(start_tag_regexp, text, flags=re.S) + + # Handle any remaining text outside the tags. + logging.debug('converting after tag: [%s]', text) + result += callback(text, symbol, '') + logging.debug('results for symbol: %s, text: [%s]', symbol, result) + + return result + + +def tagify(text, elem): + # Adds a tag around some text. + # e.g tagify("Text", "literal") => "Text". + return '<' + elem + '>' + text + '' + + +def MakeDocHeader(tag): + """Builds a docbook header for the given tag. + + Args: + tag (str): doctype tag + + Returns: + str: the docbook header + """ + header = re.sub(r'', r'', header) + return header + + +def MakeXRef(symbol, text=None): + """This returns a cross-reference link to the given symbol. + + Though it doesn't try to do this for a few standard C types that it knows + won't be in the documentation. + + Args: + symbol (str): the symbol to try to create a XRef to. + text (str): text to put inside the XRef, defaults to symbol + + Returns: + str: a docbook link + """ + symbol = symbol.strip() + if not text: + text = symbol + + # Get rid of special suffixes ('-struct','-enum'). + text = re.sub(r'-struct$', '', text) + text = re.sub(r'-enum$', '', text) + + if ' ' in symbol: + return text + + logging.info("Getting type link for %s -> %s", symbol, text) + + symbol_id = common.CreateValidSGMLID(symbol) + return "%s" % (symbol_id, text) + + +def MakeIndexterms(symbol, sid): + """This returns a indexterm elements for the given symbol + + Args: + symbol (str): the symbol to create indexterms for + + Returns: + str: doxbook index terms + """ + terms = '' + sortas = '' + + # make the index useful, by ommiting the namespace when sorting + if NAME_SPACE != '': + m = re.search(r'^%s\_?(.*)' % NAME_SPACE, symbol, flags=re.I) + if m: + sortas = ' sortas="%s"' % m.group(1) + + if symbol in Deprecated: + terms += "%s" % ( + sid, sortas, symbol) + IndexEntriesDeprecated[symbol] = sid + IndexEntriesFull[symbol] = sid + if symbol in Since: + since = Since[symbol].strip() + if since != '': + terms += "%s" % ( + sid, since, sortas, symbol) + IndexEntriesSince[symbol] = sid + IndexEntriesFull[symbol] = sid + if terms == '': + terms += "%s" % (sid, sortas, symbol) + IndexEntriesFull[symbol] = sid + return terms + + +def MakeDeprecationNote(symbol): + """This returns a deprecation warning for the given symbol. + + Args: + symbol (str): the symbol to try to create a warning for. + + Returns: + str: formatted warning or empty string if symbol is not deprecated + """ + desc = '' + if symbol in Deprecated: + desc += "%s " % symbol + note = Deprecated[symbol] + + m = re.search(r'^\s*([0-9\.]+)\s*:?', note) + if m: + desc += "has been deprecated since version %s and should not be used in newly-written code." % m.group( + 1) + else: + desc += "is deprecated and should not be used in newly-written code." + + note = re.sub(r'^\s*([0-9\.]+)\s*:?\s*', '', note) + note = note.strip() + + if note != '': + note = ConvertMarkDown(symbol, note) + desc += " " + note + + desc += "\n" + + return desc + + +def MakeConditionDescription(symbol): + """This returns a sumary of conditions for the given symbol. + + Args: + symbol (str): the symbol to create the sumary for. + + Returns: + str: formatted text or empty string if no special conditions apply. + """ + desc = '' + if symbol in Deprecated: + if desc != '': + desc += "|" + m = re.search(r'^\s*(.*?)\s*$', Deprecated[symbol]) + if m: + desc += "deprecated:%s" % m.group(1) + else: + desc += "deprecated" + + if symbol in Since: + if desc != '': + desc += "|" + m = re.search(r'^\s*(.*?)\s*$', Since[symbol]) + if m: + desc += "since:%s" % m.group(1) + else: + desc += "since" + + if symbol in StabilityLevel: + if desc != '': + desc += "|" + + desc += "stability:" + StabilityLevel[symbol] + + if desc != '': + cond = re.sub(r'"', r'"', desc) + desc = ' condition=\"%s\"' % cond + logging.info("condition for '%s' = '%s'", symbol, desc) + + return desc + + +def GetHierarchy(gobject, hierarchy): + """Generate the object inheritance graph. + + Returns the DocBook output describing the ancestors and + immediate children of a GObject subclass. It uses the + global Objects and ObjectLevels arrays to walk the tree. + + Args: + object (str): the GtkObject subclass. + hierarchy (list) - previous hierarchy + + Returns: + list: lines of docbook describing the hierarchy + """ + # Find object in the objects array. + found = False + children = [] + level = 0 + j = 0 + for i in range(len(Objects)): + if found: + if ObjectLevels[i] <= level: + break + + elif ObjectLevels[i] == level + 1: + children.append(Objects[i]) + + elif Objects[i] == gobject: + found = True + j = i + level = ObjectLevels[i] + + if not found: + return hierarchy + + logging.info("=== Hierachy for: %s (%d existing entries) ===", gobject, len(hierarchy)) + + # Walk up the hierarchy, pushing ancestors onto the ancestors array. + ancestors = [gobject] + logging.info("Level: %s", level) + while level > 1: + j -= 1 + if ObjectLevels[j] < level: + ancestors.append(Objects[j]) + level = ObjectLevels[j] + logging.info("Level: %s", level) + + # Output the ancestors, indented and with links. + logging.info('%d ancestors', len(ancestors)) + last_index = 0 + level = 1 + for i in range(len(ancestors) - 1, -1, -1): + ancestor = ancestors[i] + ancestor_id = common.CreateValidSGMLID(ancestor) + indent = ' ' * (level * 4) + # Don't add a link to the current object, i.e. when i == 0. + if i > 0: + entry_text = indent + "%s" % (ancestor_id, ancestor) + alt_text = indent + ancestor + else: + entry_text = indent + ancestor + alt_text = indent + "%s" % (ancestor_id, ancestor) + + logging.info("Checking for '%s' or '%s'", entry_text, alt_text) + # Check if we already have this object + index = -1 + for j in range(len(hierarchy)): + if hierarchy[j] == entry_text or (hierarchy[j] == alt_text): + index = j + break + if index == -1: + # We have a new entry, find insert position in alphabetical order + found = False + for j in range(last_index, len(hierarchy)): + if not re.search(r'^' + indent, hierarchy[j]): + last_index = j + found = True + break + elif re.search(r'^%s[^ ]' % indent, hierarchy[j]): + stripped_text = hierarchy[j] + if r'', '', stripped_text) + stripped_text = re.sub(r'', '', stripped_text) + + if entry_text < stripped_text: + last_index = j + found = True + break + + # Append to bottom + if not found: + last_index = len(hierarchy) + + logging.debug('insert at %d: %s', last_index, entry_text) + hierarchy.insert(last_index, entry_text) + last_index += 1 + else: + # Already have this one, make sure we use the not linked version + if r'%s" % (sid, children[i]) + logging.debug('insert at %d: %s', last_index, indented_text) + hierarchy.insert(last_index, indented_text) + last_index += 1 + return hierarchy + + +def GetInterfaces(gobject): + """Generate interface implementation graph. + + Returns the DocBook output describing the interfaces + implemented by a class. It uses the global Interfaces hash. + + Args: + object (str): the GObject subclass. + + Returns: + str: implemented interfaces + """ + text = '' + # Find object in the objects array. + if gobject in Interfaces: + ifaces = Interfaces[gobject].split() + text = ''' +%s implements +''' % gobject + count = len(ifaces) + for i in range(count): + sid = common.CreateValidSGMLID(ifaces[i]) + text += " %s" % (sid, ifaces[i]) + if i < count - 2: + text += ', ' + elif i < count - 1: + text += ' and ' + else: + text += '.' + text += '\n' + return text + + +def GetImplementations(gobject): + """Generate interface usage graph. + + Returns the DocBook output describing the implementations + of an interface. It uses the global Interfaces hash. + + Args: + object (str): the GObject subclass. + + Returns: + str: interface implementations + """ + text = '' + impls = [] + for key in Interfaces: + if re.search(r'\b%s\b' % gobject, Interfaces[key]): + impls.append(key) + + count = len(impls) + if count > 0: + impls.sort() + text = ''' +%s is implemented by +''' % gobject + for i in range(count): + sid = common.CreateValidSGMLID(impls[i]) + text += " %s" % (sid, impls[i]) + if i < count - 2: + text += ', ' + elif i < count - 1: + text += ' and ' + else: + text += '.' + text += '\n' + return text + + +def GetPrerequisites(iface): + """Generates interface requirements. + + Returns the DocBook output describing the prerequisites + of an interface. It uses the global Prerequisites hash. + Args: + iface (str): the interface. + + Returns: + str: required interfaces + """ + + text = '' + if iface in Prerequisites: + text = ''' +%s requires +''' % iface + prereqs = Prerequisites[iface].split() + count = len(prereqs) + for i in range(count): + sid = common.CreateValidSGMLID(prereqs[i]) + text += " %s" % (sid, prereqs[i]) + if i < count - 2: + text += ', ' + elif i < count - 1: + text += ' and ' + else: + text += '.' + text += '\n' + return text + + +def GetDerived(iface): + """ + Returns the DocBook output describing the derived interfaces + of an interface. It uses the global %Prerequisites hash. + + Args: + iface (str): the interface. + + Returns: + str: derived interfaces + """ + text = '' + derived = [] + for key in Prerequisites: + if re.search(r'\b%s\b' % iface, Prerequisites[key]): + derived.append(key) + + count = len(derived) + if count > 0: + derived.sort() + text = ''' +%s is required by +''' % iface + for i in range(count): + sid = common.CreateValidSGMLID(derived[i]) + text += " %s" % (sid, derived[i]) + if i < count - 2: + text += ', ' + elif i < count - 1: + text += ' and ' + else: + text += '.' + text += '\n' + return text + + +def GetSignals(gobject): + """Generate signal docs. + + Returns the synopsis and detailed description DocBook output + for the signal handlers of a given GObject subclass. + + Args: + object (str): the GObject subclass, e.g. 'GtkButton'. + + Returns: + str: signal docs + """ + synop = '' + desc = '' + + for i in range(len(SignalObjects)): + if SignalObjects[i] == gobject: + logging.info("Found signal: %s", SignalNames[i]) + name = SignalNames[i] + symbol = '%s::%s' % (gobject, name) + sid = common.CreateValidSGMLID('%s-%s' % (gobject, name)) + + desc += "The <literal>“%s”</literal> signal\n" % ( + sid, name) + desc += MakeIndexterms(symbol, sid) + desc += "\n" + desc += OutputSymbolExtraLinks(symbol) + + desc += "" + + m = re.search(r'\s*(const\s+)?(\w+)\s*(\**)', SignalReturns[i]) + type_modifier = m.group(1) or '' + gtype = m.group(2) + pointer = m.group(3) + xref = MakeXRef(gtype, tagify(gtype, "returnvalue")) + + ret_type_output = '%s%s%s' % (type_modifier, xref, pointer) + callback_name = "user_function" + desc += '%s\n%s (' % (ret_type_output, callback_name) + + indentation = ' ' * (len(callback_name) + 2) + + sourceparams = SourceSymbolParams.get(symbol) + sourceparam_names = None + if sourceparams: + sourceparam_names = list(sourceparams) # keys as list + params = SignalPrototypes[i].splitlines() + type_len = len("gpointer") + name_len = len("user_data") + # do two passes, the first one is to calculate padding + for l in range(2): + for j in range(len(params)): + param_name = None + # allow alphanumerics, '_', '[' & ']' in param names + m = re.search(r'^\s*(\w+)\s*(\**)\s*([\w\[\]]+)\s*$', params[j]) + if m: + gtype = m.group(1) + pointer = m.group(2) + if sourceparam_names: + if j < len(sourceparam_names): + param_name = sourceparam_names[j] + logging.info('from sourceparams: "%s" (%d: %s)', param_name, j, params[j]) + # we're mssing the docs for this param, don't warn here though + else: + param_name = m.group(3) + logging.info('from params: "%s" (%d: %s)', param_name, j, params[j]) + + if not param_name: + param_name = "arg%d" % j + + if l == 0: + if len(gtype) + len(pointer) > type_len: + type_len = len(gtype) + len(pointer) + if len(param_name) > name_len: + name_len = len(param_name) + else: + logging.info("signal arg[%d]: '%s'", j, param_name) + xref = MakeXRef(gtype, tagify(gtype, "type")) + pad = ' ' * (type_len - len(gtype) - len(pointer)) + desc += '%s%s %s%s,\n' % (xref, pad, pointer, param_name) + desc += indentation + + else: + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "Can't parse arg: %s\nArgs:%s" % (params[j], SignalPrototypes[i])) + + xref = MakeXRef("gpointer", tagify("gpointer", "type")) + pad = ' ' * (type_len - len("gpointer")) + desc += '%s%s user_data)' % (xref, pad) + desc += "\n" + + flags = SignalFlags[i] + flags_string = '' + if flags: + if 'f' in flags: + flags_string = "Run First" + + elif 'l' in flags: + flags_string = "Run Last" + + elif 'c' in flags: + flags_string = "Cleanup" + flags_string = "Cleanup" + + if 'r' in flags: + if flags_string: + flags_string += " / " + flags_string = "No Recursion" + + if 'd' in flags: + if flags_string: + flags_string += " / " + flags_string = "Has Details" + + if 'a' in flags: + if flags_string: + flags_string += " / " + flags_string = "Action" + + if 'h' in flags: + if flags_string: + flags_string += " / " + flags_string = "No Hooks" + + synop += "%s%s%s\n" % ( + ret_type_output, sid, name, flags_string) + + parameters = OutputParamDescriptions("SIGNAL", symbol, None) + logging.info("formatted signal params: '%s' -> '%s'", symbol, parameters) + + AllSymbols[symbol] = 1 + if symbol in SymbolDocs: + symbol_docs = ConvertMarkDown(symbol, SymbolDocs[symbol]) + + desc += symbol_docs + + if not IsEmptyDoc(SymbolDocs[symbol]): + AllDocumentedSymbols[symbol] = 1 + + if symbol in SymbolAnnotations: + param_desc = SymbolAnnotations[symbol] + (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc) + if param_annotations != '': + desc += "\n%s" % param_annotations + + desc += MakeDeprecationNote(symbol) + + desc += parameters + if flags_string: + desc += "Flags: %s\n" % flags_string + + desc += OutputSymbolTraits(symbol) + desc += "" + + return (synop, desc) + + +def GetArgs(gobject): + """Generate property docs. + + Returns the synopsis and detailed description DocBook output + for the Args of a given GtkObject subclass. + + Args: + object (str): the GObject subclass, e.g. 'GtkButton'. + + Returns: + str: property docs + """ + synop = '' + desc = '' + child_synop = '' + child_desc = '' + style_synop = '' + style_desc = '' + + for i in range(len(ArgObjects)): + if ArgObjects[i] == gobject: + logging.info("Found arg: %s", ArgNames[i]) + name = ArgNames[i] + flags = ArgFlags[i] + flags_string = '' + kind = '' + id_sep = '' + + if 'c' in flags: + kind = "child property" + id_sep = "c-" + elif 's' in flags: + kind = "style property" + id_sep = "s-" + else: + kind = "property" + + # Remember only one colon so we don't clash with signals. + symbol = '%s:%s' % (gobject, name) + # use two dashes and ev. an extra separator here for the same reason. + sid = common.CreateValidSGMLID('%s--%s%s' % (gobject, id_sep, name)) + + atype = ArgTypes[i] + type_output = None + arange = ArgRanges[i] + range_output = CreateValidSGML(arange) + default = ArgDefaults[i] + default_output = CreateValidSGML(default) + + if atype == "GtkString": + atype = "char *" + + if atype == "GtkSignal": + atype = "GtkSignalFunc, gpointer" + type_output = MakeXRef("GtkSignalFunc") + ", " + MakeXRef("gpointer") + elif re.search(r'^(\w+)\*$', atype): + m = re.search(r'^(\w+)\*$', atype) + type_output = MakeXRef(m.group(1), tagify(m.group(1), "type")) + " *" + else: + type_output = MakeXRef(atype, tagify(atype, "type")) + + if 'r' in flags: + flags_string = "Read" + + if 'w' in flags: + if flags_string: + flags_string += " / " + flags_string += "Write" + + if 'x' in flags: + if flags_string: + flags_string += " / " + flags_string += "Construct" + + if 'X' in flags: + if flags_string: + flags_string += " / " + flags_string += "Construct Only" + + AllSymbols[symbol] = 1 + blurb = '' + if symbol in SymbolDocs and not IsEmptyDoc(SymbolDocs[symbol]): + blurb = ConvertMarkDown(symbol, SymbolDocs[symbol]) + logging.info(".. [%s][%s]", SymbolDocs[symbol], blurb) + AllDocumentedSymbols[symbol] = 1 + + else: + if ArgBlurbs[i] != '': + blurb = "" + CreateValidSGML(ArgBlurbs[i]) + "" + AllDocumentedSymbols[symbol] = 1 + else: + # FIXME: print a warning? + logging.info(".. no description") + + pad1 = '' + if len(name) < 24: + pad1 = " " * (24 - len(name)) + + arg_synop = "%s%s%s\n" % ( + type_output, sid, name, flags_string) + arg_desc = "The <literal>“%s”</literal> %s\n" % ( + sid, name, kind) + arg_desc += MakeIndexterms(symbol, sid) + arg_desc += "\n" + arg_desc += OutputSymbolExtraLinks(symbol) + + arg_desc += " “%s”%s %s\n" % (name, pad1, type_output) + arg_desc += blurb + if symbol in SymbolAnnotations: + param_desc = SymbolAnnotations[symbol] + (param_desc, param_annotations) = ExpandAnnotation(symbol, param_desc) + if param_annotations != '': + arg_desc += "\n%s" % param_annotations + + arg_desc += MakeDeprecationNote(symbol) + + if flags_string: + arg_desc += "Flags: %s\n" % flags_string + + if arange != '': + arg_desc += "Allowed values: %s\n" % range_output + + if default != '': + arg_desc += "Default value: %s\n" % default_output + + arg_desc += OutputSymbolTraits(symbol) + arg_desc += "\n" + + if 'c' in flags: + child_synop += arg_synop + child_desc += arg_desc + + elif 's' in flags: + style_synop += arg_synop + style_desc += arg_desc + + else: + synop += arg_synop + desc += arg_desc + + return (synop, child_synop, style_synop, desc, child_desc, style_desc) + + +def IgnorePath(path, source_dirs, ignore_files): + for sdir in source_dirs: + # Cut off base directory + m1 = re.search(r'^%s/(.*)$' % re.escape(sdir), path) + if m1: + # Check if the filename is in the ignore list. + m2 = re.search(r'(\s|^)%s(\s|$)' % re.escape(m1.group(1)), ignore_files) + if m2: + logging.info("Skipping path: %s", path) + return True + else: + logging.info("No match for: %s", m1.group(1)) + else: + logging.info("No match for: %s", path) + return False + + +def ReadSourceDocumentation(source_dir, suffix_list, source_dirs, ignore_files): + """Read the documentation embedded in comment blocks in the source code. + + It recursively descends the source directory looking for source files and + scans them looking for specially-formatted comment blocks. + + Args: + source_dir (str): the directory to scan. + suffix_list (list): extensions to check + """ + if IgnorePath(source_dir, source_dirs, ignore_files): + return + + logging.info("Scanning source directory: %s", source_dir) + + # This array holds any subdirectories found. + subdirs = [] + + for ifile in sorted(os.listdir(source_dir)): + logging.debug("... : %s", ifile) + if ifile.startswith('.'): + continue + fname = os.path.join(source_dir, ifile) + if os.path.isdir(fname): + subdirs.append(fname) + else: + for suffix in suffix_list: + if ifile.endswith(suffix): + if not IgnorePath(fname, source_dirs, ignore_files): + ScanSourceFile(fname, ignore_files) + break + + # Now recursively scan the subdirectories. + for sdir in subdirs: + ReadSourceDocumentation(sdir, suffix_list, source_dirs, ignore_files) + + +def ScanSourceFile(ifile, ignore_files): + """Scans one source file looking for specially-formatted comment blocks. + + Later MergeSourceDocumentation() is copying over the doc blobs that are not + suppressed/ignored. + + Args: + file (str): the file to scan. + """ + m = re.search(r'^.*[\/\\]([^\/\\]*)$', ifile) + if m: + basename = m.group(1) + else: + common.LogWarning(ifile, 1, "Can't find basename for this filename.") + basename = ifile + + # Check if the basename is in the list of files to ignore. + if re.search(r'(\s|^)%s(\s|$)' % re.escape(basename), ignore_files): + logging.info("Skipping source file: %s", ifile) + return + + logging.info("Scanning source file: %s", ifile) + + SRCFILE = open(ifile) + in_comment_block = False + symbol = None + in_part = '' + description = '' + return_desc = '' + since_desc = stability_desc = deprecated_desc = '' + params = OrderedDict() + param_name = None + line_number = 0 + for line in SRCFILE: + line_number += 1 + # Look for the start of a comment block. + if not in_comment_block: + if re.search(r'^\s*/\*.*\*/', line): + # one-line comment - not gtkdoc + pass + elif re.search(r'^\s*/\*\*\s', line): + logging.info("Found comment block start") + + in_comment_block = True + + # Reset all the symbol data. + symbol = '' + in_part = '' + description = '' + return_desc = '' + since_desc = '' + deprecated_desc = '' + stability_desc = '' + params = OrderedDict() + param_name = None + + continue + + # We're in a comment block. Check if we've found the end of it. + if re.search(r'^\s*\*+/', line): + if not symbol: + # maybe its not even meant to be a gtk-doc comment? + common.LogWarning(ifile, line_number, "Symbol name not found at the start of the comment block.") + else: + # Add the return value description onto the end of the params. + if return_desc: + # TODO(ensonic): check for duplicated Return docs + # common.LogWarning(file, line_number, "Multiple Returns for %s." % symbol) + params['Returns'] = return_desc + + # Convert special characters + description = ConvertSGMLChars(symbol, description) + for (param_name, param_desc) in iteritems(params): + params[param_name] = ConvertSGMLChars(symbol, param_desc) + + # Handle Section docs + m = re.search(r'SECTION:\s*(.*)', symbol) + m2 = re.search(r'PROGRAM:\s*(.*)', symbol) + if m: + real_symbol = m.group(1) + long_descr = real_symbol + ":Long_Description" + + if long_descr not in KnownSymbols or KnownSymbols[long_descr] != 1: + common.LogWarning( + ifile, line_number, "Section %s is not defined in the %s-sections.txt file." % (real_symbol, MODULE)) + + logging.info("SECTION DOCS found in source for : '%s'", real_symbol) + for param_name, param_desc in iteritems(params): + logging.info(" '" + param_name + "'") + param_name = param_name.lower() + key = None + if param_name == "short_description": + key = real_symbol + ":Short_Description" + elif param_name == "see_also": + key = real_symbol + ":See_Also" + elif param_name == "title": + key = real_symbol + ":Title" + elif param_name == "stability": + key = real_symbol + ":Stability_Level" + elif param_name == "section_id": + key = real_symbol + ":Section_Id" + elif param_name == "include": + key = real_symbol + ":Include" + elif param_name == "image": + key = real_symbol + ":Image" + + if key: + SourceSymbolDocs[key] = param_desc + SourceSymbolSourceFile[key] = ifile + SourceSymbolSourceLine[key] = line_number + + SourceSymbolDocs[long_descr] = description + SourceSymbolSourceFile[long_descr] = ifile + SourceSymbolSourceLine[long_descr] = line_number + elif m2: + real_symbol = m2.group(1) + key = None + section_id = None + + logging.info("PROGRAM DOCS found in source for '%s'", real_symbol) + for param_name, param_desc in iteritems(params): + logging.info("PROGRAM key %s: '%s'", real_symbol, param_name) + param_name = param_name.lower() + key = None + if param_name == "short_description": + key = real_symbol + ":Short_Description" + elif param_name == "see_also": + key = real_symbol + ":See_Also" + elif param_name == "section_id": + key = real_symbol + ":Section_Id" + elif param_name == "synopsis": + key = real_symbol + ":Synopsis" + elif param_name == "returns": + key = real_symbol + ":Returns" + elif re.search(r'^(-.*)', param_name): + logging.info("PROGRAM opts: '%s': '%s'", param_name, param_desc) + key = real_symbol + ":Options" + opts = [] + opts_str = SourceSymbolDocs.get(key) + if opts_str: + opts = opts_str.split('\t') + opts.append(param_name) + opts.append(param_desc) + + logging.info("Setting options for symbol: %s: '%s'", real_symbol, '\t'.join(opts)) + SourceSymbolDocs[key] = '\t'.join(opts) + continue + + if key: + logging.info("PROGRAM value %s: '%s'", real_symbol, param_desc.rstrip()) + SourceSymbolDocs[key] = param_desc.rstrip() + SourceSymbolSourceFile[key] = ifile + SourceSymbolSourceLine[key] = line_number + + long_descr = real_symbol + ":Long_Description" + SourceSymbolDocs[long_descr] = description + SourceSymbolSourceFile[long_descr] = ifile + SourceSymbolSourceLine[long_descr] = line_number + + section_id = SourceSymbolDocs.get(real_symbol + ":Section_Id") + if section_id and section_id.strip() != '': + # Remove trailing blanks and use as is + section_id = section_id.rstrip() + else: + section_id = common.CreateValidSGMLID('%s-%s' % (MODULE, real_symbol)) + OutputProgramDBFile(real_symbol, section_id) + + else: + logging.info("SYMBOL DOCS found in source for : '%s'", symbol) + SourceSymbolDocs[symbol] = description + SourceSymbolParams[symbol] = params + SourceSymbolSourceFile[symbol] = ifile + SourceSymbolSourceLine[symbol] = line_number + + if since_desc: + arr = since_desc.splitlines() + since_desc = arr[0].strip() + extra_lines = arr[1:] + logging.info("Since(%s) : [%s]", symbol, since_desc) + Since[symbol] = ConvertSGMLChars(symbol, since_desc) + if len(extra_lines) > 1: + common.LogWarning(ifile, line_number, "multi-line since docs found") + + if stability_desc: + stability_desc = ParseStabilityLevel( + stability_desc, ifile, line_number, "Stability level for %s" % symbol) + StabilityLevel[symbol] = ConvertSGMLChars(symbol, stability_desc) + + if deprecated_desc: + if symbol not in Deprecated: + # don't warn for signals and properties + # if ($symbol !~ m/::?(.*)/) + if symbol in DeclarationTypes: + common.LogWarning(ifile, line_number, + "%s is deprecated in the inline comments, but no deprecation guards were found around the declaration. (See the --deprecated-guards option for gtkdoc-scan.)" % symbol) + + Deprecated[symbol] = ConvertSGMLChars(symbol, deprecated_desc) + + in_comment_block = False + continue + + # Get rid of ' * ' at start of every line in the comment block. + line = re.sub(r'^\s*\*\s?', '', line) + # But make sure we don't get rid of the newline at the end. + if not line.endswith('\n'): + line = line + "\n" + + logging.info("scanning :%s", line.strip()) + + # If we haven't found the symbol name yet, look for it. + if not symbol: + m1 = re.search(r'^\s*(SECTION:\s*\S+)', line) + m2 = re.search(r'^\s*(PROGRAM:\s*\S+)', line) + m3 = re.search(r'^\s*([\w:-]*\w)\s*:?\s*(\(.+?\)\s*)*$', line) + if m1: + symbol = m1.group(1) + logging.info("SECTION DOCS found in source for : '%s'", symbol) + elif m2: + symbol = m2.group(1) + logging.info("PROGRAM DOCS found in source for : '%s'", symbol) + elif m3: + symbol = m3.group(1) + annotation = m3.group(2) + logging.info("SYMBOL DOCS found in source for : '%s'", symbol) + if annotation: + annotation = annotation.strip() + if annotation != '': + SymbolAnnotations[symbol] = annotation + logging.info("remaining text for %s: '%s'", symbol, annotation) + + continue + + if in_part == "description": + # Get rid of 'Description:' + line = re.sub(r'^\s*Description:', '', line) + + m1 = re.search(r'^\s*(returns|return\s+value):', line, flags=re.I) + m2 = re.search(r'^\s*since:', line, flags=re.I) + m3 = re.search(r'^\s*deprecated:', line, flags=re.I) + m4 = re.search(r'^\s*stability:', line, flags=re.I) + + if m1: + # we're in param section and have not seen the blank line + if in_part != '': + return_desc = line[m1.end():] + in_part = "return" + continue + + if m2: + # we're in param section and have not seen the blank line + if in_part != "param": + since_desc = line[m2.end():] + in_part = "since" + continue + + elif m3: + # we're in param section and have not seen the blank line + if in_part != "param": + deprecated_desc = line[m3.end():] + in_part = "deprecated" + continue + + elif m4: + stability_desc = line[m4.end():] + in_part = "stability" + continue + + if in_part == "description": + description += line + continue + elif in_part == "return": + return_desc += line + continue + elif in_part == "since": + since_desc += line + continue + elif in_part == "stability": + stability_desc += line + continue + elif in_part == "deprecated": + deprecated_desc += line + continue + + # We must be in the parameters. Check for the empty line below them. + if re.search(r'^\s*$', line): + in_part = "description" + continue + + # Look for a parameter name. + m = re.search(r'^\s*@(.+?)\s*:\s*', line) + if m: + param_name = m.group(1) + param_desc = line[m.end():] + + logging.info("Found parameter: %s", param_name) + # Allow varargs variations + if re.search(r'^\.\.\.$', param_name): + param_name = "..." + + logging.info("Found param for symbol %s : '%s'= '%s'", symbol, param_name, line) + + params[param_name] = param_desc + in_part = "param" + continue + elif in_part == '': + logging.info("continuation for %s annotation '%s'", symbol, line) + annotation = re.sub(r'^\s+|\s+$', '', line) + if symbol in SymbolAnnotations: + SymbolAnnotations[symbol] += annotation + else: + SymbolAnnotations[symbol] = annotation + continue + + # We must be in the middle of a parameter description, so add it on + # to the last element in @params. + if not param_name: + common.LogWarning(file, line_number, "Parsing comment block file : parameter expected, but got '%s'" % line) + else: + params[param_name] += line + + SRCFILE.close() + + +def OutputMissingDocumentation(): + """Outputs report of documentation coverage to a file. + + Returns: + bool: True if the report was updated + """ + old_undocumented_file = os.path.join(ROOT_DIR, MODULE + "-undocumented.txt") + new_undocumented_file = os.path.join(ROOT_DIR, MODULE + "-undocumented.new") + + n_documented = 0 + n_incomplete = 0 + total = 0 + symbol = None + percent = None + buffer = '' + buffer_deprecated = '' + buffer_descriptions = '' + + UNDOCUMENTED = open(new_undocumented_file, 'w') + + for symbol in sorted(iterkeys(AllSymbols)): + # FIXME: should we print common.LogWarnings for undocumented stuff? + # DEBUG + # location = "defined at " + GetSymbolSourceFile(symbol) + ":" + GetSymbolSourceLine(symbol) + "\n" + # DEBUG + m = re.search( + r':(Title|Long_Description|Short_Description|See_Also|Stability_Level|Include|Section_Id|Image)', symbol) + m2 = re.search(r':(Long_Description|Short_Description)', symbol) + if not m: + total += 1 + if symbol in AllDocumentedSymbols: + n_documented += 1 + if symbol in AllIncompleteSymbols: + n_incomplete += 1 + buffer += symbol + " (" + AllIncompleteSymbols[symbol] + ")\n" + #$buffer += "\t0: ".$location + + elif symbol in Deprecated: + if symbol in AllIncompleteSymbols: + n_incomplete += 1 + buffer_deprecated += symbol + " (" + AllIncompleteSymbols[symbol] + ")\n" + #$buffer += "\t1a: ".$location + else: + buffer_deprecated += symbol + "\n" + #$buffer += "\t1b: ".$location + + else: + if symbol in AllIncompleteSymbols: + n_incomplete += 1 + buffer += symbol + " (" + AllIncompleteSymbols[symbol] + ")\n" + #$buffer += "\t2a: ".$location + else: + buffer += symbol + "\n" + #$buffer += "\t2b: ".$location + + elif m2: + total += 1 + if (symbol in SymbolDocs and len(SymbolDocs[symbol]) > 0)\ + or (symbol in AllDocumentedSymbols and AllDocumentedSymbols[symbol] > 0): + n_documented += 1 + else: + buffer_descriptions += symbol + "\n" + + if total == 0: + percent = 100 + else: + percent = (n_documented / total) * 100.0 + + UNDOCUMENTED.write("%.0f%% symbol docs coverage.\n" % percent) + UNDOCUMENTED.write("%s symbols documented.\n" % n_documented) + UNDOCUMENTED.write("%s symbols incomplete.\n" % n_incomplete) + UNDOCUMENTED.write("%d not documented.\n" % (total - n_documented)) + + if buffer_deprecated != '': + buffer += "\n" + buffer_deprecated + + if buffer_descriptions != '': + buffer += "\n" + buffer_descriptions + + if buffer != '': + UNDOCUMENTED.write("\n\n" + buffer) + + UNDOCUMENTED.close() + + return common.UpdateFileIfChanged(old_undocumented_file, new_undocumented_file, 0) + + +def OutputUndeclaredSymbols(): + """Reports undeclared symbols. + + Outputs symbols that are listed in the section file, but have no declaration + in the sources. + + Returns: + bool: True if the report was updated + """ + old_undeclared_file = os.path.join(ROOT_DIR, MODULE + "-undeclared.txt") + new_undeclared_file = os.path.join(ROOT_DIR, MODULE + "-undeclared.new") + + UNDECLARED = open(new_undeclared_file, 'w') + + if UndeclaredSymbols: + UNDECLARED.write("\n".join(sorted(iterkeys(UndeclaredSymbols)))) + UNDECLARED.write("\n") + print("See %s-undeclared.txt for the list of undeclared symbols." % MODULE) + + UNDECLARED.close() + + return common.UpdateFileIfChanged(old_undeclared_file, new_undeclared_file, 0) + + +def OutputUnusedSymbols(): + """Reports unused documentation. + + Outputs symbols that are documented in comments, but not declared in the + sources. + + Returns: + bool: True if the report was updated + """ + num_unused = 0 + old_unused_file = os.path.join(ROOT_DIR, MODULE + "-unused.txt") + new_unused_file = os.path.join(ROOT_DIR, MODULE + "-unused.new") + + UNUSED = open(new_unused_file, 'w') + + for symbol in sorted(iterkeys(Declarations)): + if not symbol in DeclarationOutput: + UNUSED.write("%s\n" % symbol) + num_unused += 1 + + for symbol in sorted(iterkeys(AllUnusedSymbols)): + UNUSED.write(symbol + "(" + AllUnusedSymbols[symbol] + ")\n") + num_unused += 1 + + UNUSED.close() + if num_unused != 0: + common.LogWarning( + old_unused_file, 1, "%d unused declarations. They should be added to %s-sections.txt in the appropriate place." % (num_unused, MODULE)) + + return common.UpdateFileIfChanged(old_unused_file, new_unused_file, 0) + + +def OutputAllSymbols(): + """Outputs list of all symbols to a file.""" + SYMBOLS = open(os.path.join(ROOT_DIR, MODULE + "-symbols.txt"), 'w') + + for symbol in sorted(iterkeys(AllSymbols)): + SYMBOLS.write(symbol + "\n") + SYMBOLS.close() + + +def OutputSymbolsWithoutSince(): + """Outputs list of all symbols without a since tag to a file.""" + SYMBOLS = open(os.path.join(ROOT_DIR, MODULE + "-nosince.txt"), 'w') + + for symbol in sorted(iterkeys(SourceSymbolDocs)): + if symbol in Since: + SYMBOLS.write(symbol + "\n") + SYMBOLS.close() + + +def CheckParamsDocumented(symbol, params): + stype = DeclarationTypes.get(symbol) + + item = "Parameter" + if stype: + if stype == 'STRUCT': + item = "Field" + elif stype == 'ENUM': + item = "Value" + elif stype == 'UNION': + item = "Field" + else: + stype = "SIGNAL" + logging.info("Check param docs for %s, params: %s entries, type=%s", symbol, len(params), stype) + + if len(params) > 0: + logging.info("params: %s", str(params)) + for (param_name, param_desc) in iteritems(params): + # Output a warning if the parameter is empty and remember for stats. + if param_name != "void" and not re.search(r'\S', param_desc): + if symbol in AllIncompleteSymbols: + AllIncompleteSymbols[symbol] += ", " + param_name + else: + AllIncompleteSymbols[symbol] = param_name + + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "%s description for %s::%s is missing in source code comment block." % (item, symbol, param_name)) + + elif len(params) == 0: + AllIncompleteSymbols[symbol] = "" + common.LogWarning(GetSymbolSourceFile(symbol), GetSymbolSourceLine(symbol), + "%s descriptions for %s are missing in source code comment block." % (item, symbol)) + + +def MergeSourceDocumentation(): + """Merges documentation read from a source file. + + Parameter descriptions override any in the template files. + Function descriptions are placed before any description from + the template files. + """ + + # add whats found in the source + symbols = set(iterkeys(SourceSymbolDocs)) + + # and add known symbols from -sections.txt + for symbol in iterkeys(KnownSymbols): + if KnownSymbols[symbol] == 1: + symbols.add(symbol) + + logging.info("num source entries: %d", len(symbols)) + + for symbol in symbols: + AllSymbols[symbol] = 1 + + if symbol in SourceSymbolDocs: + logging.info("merging [%s] from source", symbol) + + # remove leading and training whitespaces + src_docs = SourceSymbolDocs[symbol].strip() + if src_docs != '': + AllDocumentedSymbols[symbol] = 1 + + SymbolDocs[symbol] = src_docs + + # merge parameters + if symbol in SourceSymbolParams: + param_docs = SourceSymbolParams[symbol] + SymbolParams[symbol] = param_docs + # if this symbol is documented, check if docs are complete + # remove all xml-tags and whitespaces + check_docs = re.sub(r'\s', '', re.sub(r'<.*?>', '', src_docs)) + if check_docs != '' and param_docs: + CheckParamsDocumented(symbol, param_docs) + else: + logging.info("[%s] undocumented", symbol) + + logging.info("num doc entries: %d", len(SymbolDocs)) + + +def IsEmptyDoc(doc): + """Check if a doc-string is empty. + + It is also regarded as empty if it only consist of whitespace or e.g. FIXME. + + Args: + doc (str): the doc-string + + Returns: + bool: True if empty + """ + if re.search(r'^\s*$', doc): + return True + if re.search(r'^\s*\s*(FIXME)?\s*<\/para>\s*$', doc): + return True + return False + + +def ConvertMarkDown(symbol, text): + md_to_db.Init() + return md_to_db.MarkDownParse(text, symbol) + + +def ReadDeclarationsFile(ifile, override): + """Reads in a file containing the function/macro/enum etc. declarations. + + Note that in some cases there are several declarations with + the same name, e.g. for conditional macros. In this case we + set a flag in the DeclarationConditional hash so the + declaration is not shown in the docs. + + If a macro and a function have the same name, e.g. for + g_object_ref, the function declaration takes precedence. + + Some opaque structs are just declared with 'typedef struct + _name name;' in which case the declaration may be empty. + The structure may have been found later in the header, so + that overrides the empty declaration. + + Args: + file (str): the declarations file to read + override (bool): if declarations in this file should override + any current declaration. + """ + if override == 0: + Declarations.clear() + DeclarationTypes.clear() + DeclarationConditional.clear() + DeclarationOutput.clear() + + INPUT = open(ifile) + declaration_type = '' + declaration_name = None + declaration = None + is_deprecated = 0 + line_number = 0 + for line in INPUT: + line_number += 1 + if not declaration_type: + m1 = re.search(r'^<([^>]+)>', line) + if m1: + declaration_type = m1.group(1) + declaration_name = '' + logging.info("Found declaration: %s", declaration_type) + declaration = '' + else: + m2 = re.search(r'^(.*)', line) + m3 = re.search(r'^', line) + m4 = re.search(r'^' % declaration_type, line) + if m2: + declaration_name = m2.group(1) + elif m3: + is_deprecated = True + elif m4: + logging.info("Found end of declaration: %s, %s", declaration_type, declaration_name) + # Check that the declaration has a name + if declaration_name == '': + common.LogWarning(ifile, line_number, declaration_type + " has no name.\n") + + # If the declaration is an empty typedef struct _XXX XXX + # set the flag to indicate the struct has a typedef. + if (declaration_type == 'STRUCT' or declaration_type == 'UNION') \ + and re.search(r'^\s*$', declaration): + logging.info("Struct has typedef: %s", declaration_name) + StructHasTypedef[declaration_name] = 1 + + # Check if the symbol is already defined. + if declaration_name in Declarations and override == 0: + # Function declarations take precedence. + if DeclarationTypes[declaration_name] == 'FUNCTION': + # Ignore it. + pass + elif declaration_type == 'FUNCTION': + if is_deprecated: + Deprecated[declaration_name] = '' + + Declarations[declaration_name] = declaration + DeclarationTypes[declaration_name] = declaration_type + elif DeclarationTypes[declaration_name] == declaration_type: + # If the existing declaration is empty, or is just a + # forward declaration of a struct, override it. + if declaration_type == 'STRUCT' or declaration_type == 'UNION': + if re.search(r'^\s*((struct|union)\s+\w+\s*;)?\s*$', Declarations[declaration_name]): + if is_deprecated: + Deprecated[declaration_name] = '' + Declarations[declaration_name] = declaration + elif re.search(r'^\s*((struct|union)\s+\w+\s*;)?\s*$', declaration): + # Ignore an empty or forward declaration. + pass + else: + common.LogWarning( + ifile, line_number, "Structure %s has multiple definitions." % declaration_name) + + else: + # set flag in %DeclarationConditional hash for + # multiply defined macros/typedefs. + DeclarationConditional[declaration_name] = 1 + + else: + common.LogWarning(ifile, line_number, declaration_name + " has multiple definitions.") + + else: + if is_deprecated: + Deprecated[declaration_name] = '' + + Declarations[declaration_name] = declaration + DeclarationTypes[declaration_name] = declaration_type + logging.debug("added declaration: %s, %s, [%s]", declaration_type, declaration_name, declaration) + + declaration_type = '' + is_deprecated = False + else: + declaration += line + INPUT.close() + + +def ReadSignalsFile(ifile): + """Reads information about object signals. + + It creates the arrays @SignalNames and @SignalPrototypes containing details + about the signals. The first line of the SignalPrototype is the return type + of the signal handler. The remaining lines are the parameters passed to it. + The last parameter, "gpointer user_data" is always the same so is not included. + + Args: + ifile (str): the file containing the signal handler prototype information. + """ + in_signal = 0 + signal_object = None + signal_name = None + signal_returns = None + signal_flags = None + signal_prototype = None + + # Reset the signal info. + SignalObjects[:] = [] + SignalNames[:] = [] + SignalReturns[:] = [] + SignalFlags[:] = [] + SignalPrototypes[:] = [] + + if not os.path.isfile(ifile): + return + + INPUT = open(ifile) + line_number = 0 + for line in INPUT: + line_number += 1 + if not in_signal: + if re.search(r'^', line): + in_signal = 1 + signal_object = '' + signal_name = '' + signal_returns = '' + signal_prototype = '' + + else: + m = re.search(r'^(.*)<\/NAME>', line) + m2 = re.search(r'^(.*)<\/RETURNS>', line) + m3 = re.search(r'^(.*)<\/FLAGS>', line) + if m: + signal_name = m.group(1) + m1_2 = re.search(r'^(.*)::(.*)$', signal_name) + if m1_2: + signal_object = m1_2.group(1) + signal_name = m1_2.group(2).replace('_', '-') + logging.info("Found signal: %s", signal_name) + else: + common.LogWarning(ifile, line_number, "Invalid signal name: %s." % signal_name) + + elif m2: + signal_returns = m2.group(1) + elif m3: + signal_flags = m3.group(1) + elif re.search(r'^', line): + logging.info("Found end of signal: %s::%s\nReturns: %s\n%s", + signal_object, signal_name, signal_returns, signal_prototype) + SignalObjects.append(signal_object) + SignalNames.append(signal_name) + SignalReturns.append(signal_returns) + SignalFlags.append(signal_flags) + SignalPrototypes.append(signal_prototype) + in_signal = False + else: + signal_prototype += line + INPUT.close() + + +def ReadObjectHierarchy(ifile): + """Reads the $MODULE-hierarchy.txt file. + + This contains all the GObject subclasses described in this module (and their + ancestors). + It places them in the Objects array, and places their level + in the object hierarchy in the ObjectLevels array, at the + same index. GObject, the root object, has a level of 1. + + This also generates tree_index.sgml as it goes along. + + Args: + ifile (str): the input filename. + """ + + Objects[:] = [] + ObjectLevels[:] = [] + + if not os.path.isfile(ifile): + logging.debug('no *-hierarchy.tx') + return + + INPUT = open(ifile) + + # Only emit objects if they are supposed to be documented, or if + # they have documented children. To implement this, we maintain a + # stack of pending objects which will be emitted if a documented + # child turns up. + pending_objects = [] + pending_levels = [] + root = None + tree = [] + for line in INPUT: + m1 = re.search(r'\S+', line) + if not m1: + continue + + gobject = m1.group(0) + level = len(line[:m1.start()]) // 2 + 1 + + if level == 1: + root = gobject + + while pending_levels and pending_levels[-1] >= level: + pending_objects.pop() + pending_levels.pop() + + pending_objects.append(gobject) + pending_levels.append(level) + + if gobject in KnownSymbols: + while len(pending_levels) > 0: + gobject = pending_objects.pop(0) + level = pending_levels.pop(0) + xref = MakeXRef(gobject) + + tree.append(' ' * (level * 4) + xref) + Objects.append(gobject) + ObjectLevels.append(level) + ObjectRoots[gobject] = root + # else + # common.LogWarning(ifile, line_number, "unknown type %s" % object) + # + + INPUT.close() + + # FIXME: use xml + # my $old_tree_index = "$DB_OUTPUT_DIR/tree_index.$xml" + old_tree_index = os.path.join(DB_OUTPUT_DIR, "tree_index.sgml") + new_tree_index = os.path.join(DB_OUTPUT_DIR, "tree_index.new") + + logging.debug('got %d entries for hierarchy', len(tree)) + + OUTPUT = open(new_tree_index, 'w') + OUTPUT.write(MakeDocHeader("screen") + "\n\n" + AddTreeLineArt(tree) + "\n\n") + OUTPUT.close() + + common.UpdateFileIfChanged(old_tree_index, new_tree_index, 0) + + OutputObjectList() + + +def ReadInterfaces(ifile): + """Reads the $MODULE.interfaces file. + + Args: + ifile (str): the input filename. + """ + + Interfaces.clear() + + if not os.path.isfile(ifile): + return + + INPUT = open(ifile) + + for line in INPUT: + line = line.strip() + ifaces = line.split() + gobject = ifaces.pop(0) + if gobject in KnownSymbols and KnownSymbols[gobject] == 1: + knownIfaces = [] + + # filter out private interfaces, but leave foreign interfaces + for iface in ifaces: + if iface not in KnownSymbols or KnownSymbols[iface] == 1: + knownIfaces.append(iface) + + Interfaces[gobject] = ' '.join(knownIfaces) + logging.info("Interfaces for %s: %s", gobject, Interfaces[gobject]) + else: + logging.info("skipping interfaces for unknown symbol: %s", gobject) + + INPUT.close() + + +def ReadPrerequisites(ifile): + """This reads in the $MODULE.prerequisites file. + + Args: + ifile (str): the input filename. + """ + Prerequisites.clear() + + if not os.path.isfile(ifile): + return + + INPUT = open(ifile) + + for line in INPUT: + line = line.strip() + prereqs = line.split() + iface = prereqs.pop(0) + if iface in KnownSymbols and KnownSymbols[iface] == 1: + knownPrereqs = [] + + # filter out private prerequisites, but leave foreign prerequisites + for prereq in prereqs: + if prereq not in KnownSymbols or KnownSymbols[prereq] == 1: + knownPrereqs.append(prereq) + + Prerequisites[iface] = ' '.join(knownPrereqs) + + INPUT.close() + + +def ReadArgsFile(ifile): + """Reads information about object properties + + It creates the arrays ArgObjects, ArgNames, ArgTypes, ArgFlags, ArgNicks and + ArgBlurbs containing info on the args. + + Args: + ifile (str): the input filename. + """ + in_arg = False + arg_object = None + arg_name = None + arg_type = None + arg_flags = None + arg_nick = None + arg_blurb = None + arg_default = None + arg_range = None + + # Reset the args info. + ArgObjects[:] = [] + ArgNames[:] = [] + ArgTypes[:] = [] + ArgFlags[:] = [] + ArgNicks[:] = [] + ArgBlurbs[:] = [] + ArgDefaults[:] = [] + ArgRanges[:] = [] + + if not os.path.isfile(ifile): + return + + INPUT = open(ifile) + line_number = 0 + for line in INPUT: + line_number += 1 + if not in_arg: + if line.startswith(''): + in_arg = True + arg_object = '' + arg_name = '' + arg_type = '' + arg_flags = '' + arg_nick = '' + arg_blurb = '' + arg_default = '' + arg_range = '' + + else: + m1 = re.search(r'^(.*)', line) + m2 = re.search(r'^(.*)', line) + m3 = re.search(r'^(.*)', line) + m4 = re.search(r'^(.*)', line) + m5 = re.search(r'^(.*)', line) + m6 = re.search(r'^(.*)', line) + m7 = re.search(r'^(.*)', line) + if m1: + arg_name = m1.group(1) + m1_1 = re.search(r'^(.*)::(.*)$', arg_name) + if m1_1: + arg_object = m1_1.group(1) + arg_name = m1_1.group(2).replace('_', '-') + logging.info("Found arg: %s", arg_name) + else: + common.LogWarning(ifile, line_number, "Invalid argument name: " + arg_name) + + elif m2: + arg_type = m2.group(1) + elif m3: + arg_range = m3.group(1) + elif m4: + arg_flags = m4.group(1) + elif m5: + arg_nick = m5.group(1) + elif m6: + arg_blurb = m6.group(1) + if arg_blurb == "(null)": + arg_blurb = '' + common.LogWarning( + ifile, line_number, "Property %s:%s has no documentation." % (arg_object, arg_name)) + + elif m7: + arg_default = m7.group(1) + elif re.search(r'^', line): + logging.info("Found end of arg: %s::%s\n%s : %s", arg_object, arg_name, arg_type, arg_flags) + ArgObjects.append(arg_object) + ArgNames.append(arg_name) + ArgTypes.append(arg_type) + ArgRanges.append(arg_range) + ArgFlags.append(arg_flags) + ArgNicks.append(arg_nick) + ArgBlurbs.append(arg_blurb) + ArgDefaults.append(arg_default) + in_arg = False + + INPUT.close() + + +def AddTreeLineArt(tree): + """Generate a line art tree. + + Add unicode lineart to a pre-indented string array and returns + it as as multiline string. + + Args: + tree (list): of indented strings. + + Returns: + str: multiline string with tree line art + """ + # iterate bottom up over the tree + for i in range(len(tree) - 1, -1, -1): + # count leading spaces + m = re.search(r'^([^ 4: + if tree[i][indent - 4] == " ": + tree[i] = tree[i][:indent - 4] + "--- " + tree[i][indent:] + else: + tree[i] = tree[i][:indent - 4] + "+-- " + tree[i][indent:] + + # go lines up while space and insert | + j = i - 1 + while j >= 0 and tree[j][indent - 4] == ' ': + tree[j] = tree[j][:indent - 4] + '|' + tree[j][indent - 3:] + j -= 1 + + res = "\n".join(tree) + # unicode chars for: ╰── + res = re.sub(r'---', '╰──', res) + # unicde chars for: ├── + res = re.sub(r'\+--', '├──', res) + # unicode char for: │ + res = re.sub(r'\|', '│', res) + + return res + + +def CheckIsObject(name): + """Check if symbols is an object. + + It uses the global Objects array. Note that the Objects array only contains + classes in the current module and their ancestors - not all GObject classes. + + Args: + name (str): the object name to check. + + Returns: + bool: True if the given name is a GObject or a subclass. + """ + root = ObjectRoots.get(name) + # Let GBoxed pass as an object here to get -struct appended to the id + # and prevent conflicts with sections. + return root and root != 'GEnum' and root != 'GFlags' + + +def GetSymbolSourceFile(symbol): + """Get the filename where the symbol docs where taken from.""" + return SourceSymbolSourceFile.get(symbol, '') + + +def GetSymbolSourceLine(symbol): + """Get the file line where the symbol docs where taken from.""" + return SourceSymbolSourceLine.get(symbol, 0) diff --git a/gtkdoc/mkhtml.py b/gtkdoc/mkhtml.py new file mode 100644 index 0000000..80ddadf --- /dev/null +++ b/gtkdoc/mkhtml.py @@ -0,0 +1,94 @@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Owen Taylor +# 2001-2005 Damon Chaplin +# 2009-2017 Stefan Sauer +# 2017 Jussi Pakkanen +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import os +import sys +import subprocess +import shutil +from glob import glob + +from . import config + + +def run_xsltproc(options, args): + command = [config.xsltproc] + # we could do "$path_option $PWD " to avoid needing rewriting entities that + # are copied from the header into docs under xml + if os.environ.get("GTKDOC_PROFILE", '') == '': + for path in options.path: + command += ['--path', path] + return subprocess.call(command + args) + else: + command += ['--profile'] + for path in options.path: + command += ['--path', path] + return subprocess.call(command + args, stderr=open('profile.txt', 'w')) + + +def run(options): + module = options.args[0] + document = options.args[1] + if options.verbose: + quiet = '0' + else: + quiet = '1' + remaining_args = options.args[2:] + + if options.uninstalled: + # this does not work from buiddir!=srcdir + gtkdocdir = os.path.split(sys.argv[0])[0] + if not os.path.exists(gtkdocdir + '/gtk-doc.xsl'): + # try to src dir (set from makefiles) too + if os.path.exists(os.environ.get("ABS_TOP_SRCDIR", '') + '/gtk-doc.xsl'): + gtkdocdir = os.environ['ABS_TOP_SRCDIR'] + styledir = gtkdocdir + '/style' + else: + gtkdocdir = os.path.join(config.datadir, 'gtk-doc/data') + styledir = gtkdocdir + + res = run_xsltproc(options, [ + '--nonet', + '--xinclude', + '--stringparam', + 'gtkdoc.bookname', + module, + '--stringparam', + 'gtkdoc.version', + config.version, + '--stringparam', + 'chunk.quietly', + quiet, + '--stringparam', + 'chunker.output.quiet', + quiet] + remaining_args + [gtkdocdir + '/gtk-doc.xsl', document]) + + # profiling + if os.environ.get("GTKDOC_PROFILE", '') != '': + subprocess.check_call('cat profile.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o profile.png', shell=True) + + # copy navigation images and stylesheets to html directory ... + for f in glob(styledir + '/*.png') + glob(styledir + '/*.css'): + shutil.copy(f, '.') + + open('../html.stamp', 'w').write('timestamp') + return res diff --git a/gtkdoc/mkman.py b/gtkdoc/mkman.py new file mode 100644 index 0000000..515b37f --- /dev/null +++ b/gtkdoc/mkman.py @@ -0,0 +1,62 @@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Owen Taylor +# 2001-2005 Damon Chaplin +# 2009-2017 Stefan Sauer +# 2017 Jussi Pakkanen +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import subprocess + +from . import config + + +def run(options): + module = options.args[0] + document = options.args[1] + if options.verbose: + quiet = '0' + else: + quiet = '1' + + # we could do "--path $PWD " to avoid needing rewriting entities that + # are copied from the header into docs under xml + path_arg = [] + for path in options.path: + path_arg += ['--path', path] + + # would it make sense to create man pages only for certain refentries + # e.g. for tools + # see http://bugzilla.gnome.org/show_bug.cgi?id=467488 + return subprocess.call([config.xsltproc] + path_arg + [ + '--nonet', + '--xinclude', + '--stringparam', + 'gtkdoc.bookname', + module, + '--stringparam', + 'gtkdoc.version', + config.version, + '--stringparam', + 'chunk.quietly ', + quiet, + '--stringparam', + 'chunker.output.quiet', + quiet, + 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl', + document]) diff --git a/gtkdoc/mkpdf.py b/gtkdoc/mkpdf.py new file mode 100755 index 0000000..5fd9ecb --- /dev/null +++ b/gtkdoc/mkpdf.py @@ -0,0 +1,122 @@ +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2009-2017 Stefan Sauer +# 2017 Jussi Pakkanen +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +# Support both Python 2 and 3 +from __future__ import print_function + +import os +import sys +import subprocess + +from . import config + + +def run_xsltproc(options, args): + command = [config.xsltproc] + # we could do "--path $PWD " to avoid needing rewriting entities that are + # copied from the header into docs under xml + for path in options.path: + command += ['--path', path] + pc = subprocess.Popen(command + args, stderr=subprocess.PIPE) + (o, stde) = pc.communicate() + open('profile.txt', 'wb').write(stde) + return pc.returncode + + +def run(options): + module = options.args[0] + document = options.args[1] + + if options.uninstalled: + # this does not work from buiddir!=srcdir + # we could try this + # MAKE_SCRDIR=$(abs_srcdir) MAKE_BUILDDIR=$(abs_builddir) gtkdoc-mkpdf ... + gtkdocdir = os.path.split(sys.argv[0])[0] + else: + gtkdocdir = os.path.join(config.datadir, 'gtk-doc/data') + + if config.dblatex != '': + # extra options to consider + # -I FIG_PATH + # -V is useful for debugging + # -T db2latex : different style + # -d : keep transient files (for debugging) + # -P abc.def=$quiet : once the stylesheets have a quiet mode + # xsltproc is already called with --xinclude + # does not work: --xslt-opts "--path $searchpath --nonet $@" + dblatex_options = ['-o', module + '.pdf'] + for i in options.imgdir: + dblatex_options += ['-I', i] + dblatex_options.append(document) + if not options.verbose: + pc = subprocess.Popen([config.dblatex, '--help'], stdout=subprocess.PIPE, stderr=subprocess.PIPE) + (stdo, stde) = pc.communicate() + if b'--quiet' in stdo or b'--quiet' in stde: + dblatex_options = ['--quiet'] + dblatex_options + dbcmd = [config.dblatex] + dblatex_options + pc = subprocess.Popen(dbcmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT) + (stde, _) = pc.communicate() + for line in stde.decode('utf-8').split('\n'): + if not line.strip(): + continue + if 'programlisting or screen' in line: + continue + # This happens when dblatex has no support for some special chars + if 'Missing character' in line: + continue + print(line) + res = pc.returncode + elif config.fop != '': + if options.verbose: + quiet = '0' + else: + quiet = '1' + res = run_xsltproc(options, ['--nonet', + '--xinclude', + '--stringparam', + 'gtkdoc.bookname', + module, + '--stringparam', + 'gtkdoc.version', + config.version, + '--stringparam', + 'chunk.quietly', + quiet, + '--stringparam', + 'chunker.output.quiet', + quiet, + module, + document, + '-o', + module + '.fo', + gtkdocdir + '/gtk-doc-fo.xsl', + document]) + # TODO: fop dies too easily :( + # res = subprocess.call([config.fop, module + '.fo', module + '.pdf')) + fname = module + '.fo' + if os.path.exists(fname): + os.unlink(fname) + else: + print("dblatex or fop must be installed to use gtkdoc-mkpdf.") + res = 1 + + open('pdf.stamp', 'w').write('timestamp') + return res diff --git a/gtkdoc/rebase.py b/gtkdoc/rebase.py new file mode 100755 index 0000000..d6affe3 --- /dev/null +++ b/gtkdoc/rebase.py @@ -0,0 +1,254 @@ +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007 David Necas (Yeti) +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +""" +The rebase tool rewrites URI references in installed HTML documentation. +""" + +from __future__ import print_function +from six import iteritems, iterkeys + +import logging +import os +import re + +from . import common + +# Maps. +# These two point to the last seen URI of given type for a package: +# OnlineMap: package => on-line URI +# LocalMap: package => local URI +# This maps all seen URIs of a package to fix broken links in the process: +# RevMap: URI => package +OnlineMap = {} +LocalMap = {} +RevMap = {} +# Remember what mangling we did. +Mapped = {} + + +def log(options, *msg): + if options.verbose: + print(*msg) + + +def run(options): + other_dirs = [] + + # We scan the directory containing GLib and any directories in GNOME2_PATH + # first, but these will be overriden by any later scans. + if "GNOME2_PATH" in os.environ: + for dir in os.environ["GNOME2_PATH"].split(':'): + dir = os.path.join(dir, "/share/gtk-doc/html") + if os.path.isdir(dir): + log(options, "Prepending GNOME2_PATH directory:", dir) + other_dirs = [dir] + other_dirs + + dir = common.GetModuleDocDir('glib-2.0') + log(options, "Prepending GLib directory", dir) + other_dirs = [dir] + other_dirs + + # Check all other dirs, but skip already scanned dirs ord subdirs of those + + for dir in other_dirs: + ScanDirectory(dir, options) + + if options.relative: + RelativizeLocalMap(options.html_dir, options) + + RebaseReferences(options.html_dir, options) + PrintWhatWeHaveDone() + + +def ScanDirectory(scan_dir, options): + log(options, "Scanning documentation directory %s", scan_dir) + + if scan_dir == options.html_dir: + log(options, "Excluding self") + return + + if not os.path.isdir(scan_dir): + logging.info('Cannot open dir "%s"', scan_dir) + return + + subdirs = [] + onlinedir = None + have_index = False + for entry in sorted(os.listdir(scan_dir)): + full_entry = os.path.join(scan_dir, entry) + if os.path.isdir(full_entry): + subdirs.append(full_entry) + continue + + if entry.endswith('.devhelp2'): + log(options, "Reading index from " + entry) + o = ReadDevhelp(scan_dir, entry) + # Prefer this location over possibly stale index.sgml + if o is not None: + onlinedir = o + have_index = True + + if onlinedir and entry == "index.sgml": + log(options, "Reading index from index.sgml") + onlinedir = ReadIndex(dir, entry) + have_index = True + elif entry == "index.sgml.gz" and not os.path.exists(os.path.join(scan_dir, 'index.sgml')): + # debian/ubuntu started to compress this as index.sgml.gz :/ + print(''' Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138 . For now run: +gunzip %s/%s +''' % (scan_dir, entry)) + elif entry.endswith('.devhelp2.gz') and not os.path.exists(full_entry[:-3]): + # debian/ubuntu started to compress this as *devhelp2.gz :/ + print('''Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/1466210 . For now run: +gunzip %d/%s +''' % (scan_dir, entry)) + # we could consider supporting: gzip module + + if have_index: + AddMap(scan_dir, onlinedir, options) + + # Now recursively scan the subdirectories. + for subdir in subdirs: + ScanDirectory(subdir, options) + + +def ReadDevhelp(dir, file): + onlinedir = None + + for line in open(os.path.join(dir, file)): + # online must come before chapter/functions + if '''', line) + if match: + # Remove trailing non-directory component. + onlinedir = re.sub(r'''(.*/).*''', r'\1', match.groups(1)) + return onlinedir + + +def AddMap(dir, onlinedir, options): + package = None + + package = os.path.split(dir)[1] + if options.dest_dir != '' and dir.startswith(options.dest_dir): + dir = dir[len(options.dest_dir) - 1:] + + if onlinedir: + log(options, "On-line location of %s." % onlinedir) + OnlineMap[package] = onlinedir + RevMap[onlinedir] = package + else: + log(options, "No On-line location for %s found" % package) + + log(options, "Local location of $package: " + dir) + LocalMap[package] = dir + RevMap[dir] = package + + +def RelativizeLocalMap(dirname, options): + prefix = None + dir = None + + dirname = os.path.realpath(dirname) + prefix = os.path.split(dirname) + for package, dir in LocalMap.items(): + if dir.startswith(prefix): + dir = os.path.join("..", dir[len(prefix):]) + LocalMap[package] = dir + log(options, "Relativizing local location of $package to " + dir) + + +def RebaseReferences(dirname, options): + for ifile in sorted(os.listdir(dirname)): + if ifile.endswith('.html'): + RebaseFile(os.path.join(dirname, ifile), options) + + +def RebaseFile(filename, options): + log(options, "Fixing file: " + filename) + regex = re.compile(r'''(", info[0], "(%s)" % info[1]) diff --git a/gtkdoc/scan.py b/gtkdoc/scan.py new file mode 100644 index 0000000..0843519 --- /dev/null +++ b/gtkdoc/scan.py @@ -0,0 +1,892 @@ +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +""" +Extracts declarations of functions, macros, enums, structs and unions from +header files. + +It is called with a module name, an optional source directory, an optional +output directory, and the header files to scan. + +It outputs all declarations found to a file named '$MODULE-decl.txt', and the +list of decarations to another file '$MODULE-decl-list.txt'. + +This second list file is typically copied to '$MODULE-sections.txt' and +organized into sections ready to output the XML pages. +""" + +from __future__ import print_function +from six import iteritems, iterkeys + +import logging +import os +import re +import shutil + +from . import common + +# do not read files twice; checking it here permits to give both srcdir and +# builddir as --source-dir without fear of duplicities +seen_headers = {} + + +def Run(options): + # logging.basicConfig(level=logging.INFO) + + if not os.path.isdir(options.output_dir): + os.mkdir(options.output_dir) + + base_filename = os.path.join(options.output_dir, options.module) + old_decl_list = base_filename + '-decl-list.txt' + new_decl_list = base_filename + '-decl-list.new' + old_decl = base_filename + '-decl.txt' + new_decl = base_filename + '-decl.new' + old_types = base_filename + '.types' + new_types = base_filename + '.types.new' + sections_file = base_filename + '-sections.txt' + + # If this is the very first run then we create the .types file automatically. + if not os.path.exists(sections_file) and not os.path.exists(old_types): + options.rebuild_types = True + + section_list = {} + decl_list = [] + get_types = [] + + for file in options.headers: + ScanHeader(file, section_list, decl_list, get_types, options) + + for dir in options.source_dir: + ScanHeaders(dir, section_list, decl_list, get_types, options) + + with open(new_decl_list, 'w') as f: + for section in sorted(iterkeys(section_list)): + f.write(section_list[section]) + + with open(new_decl, 'w') as f: + for decl in decl_list: + f.write(decl) + + if options.rebuild_types: + with open(new_types, 'w') as f: + for func in sorted(get_types): + f.write(func + '\n') + + # remove the file if empty + if len(get_types) == 0: + os.unlink(new_types) + if os.path.exists(old_types): + os.rename(old_types, old_types + '.bak') + else: + common.UpdateFileIfChanged(old_types, new_types, True) + + common.UpdateFileIfChanged(old_decl_list, new_decl_list, True) + common.UpdateFileIfChanged(old_decl, new_decl, True) + + # If there is no MODULE-sections.txt file yet or we are asked to rebuild it, + # we copy the MODULE-decl-list.txt file into its place. The user can tweak it + # later if they want. + if options.rebuild_sections or not os.path.exists(sections_file): + new_sections_file = base_filename + '-sections.new' + shutil.copyfile(old_decl_list, new_sections_file) + common.UpdateFileIfChanged(sections_file, new_sections_file, False) + + # If there is no MODULE-overrides.txt file we create an empty one + # because EXTRA_DIST in gtk-doc.make requires it. + overrides_file = base_filename + '-overrides.txt' + if not os.path.exists(overrides_file): + open(overrides_file, 'w').close() + + +# +# Function : ScanHeaders +# Description : This scans a directory tree looking for header files. +# +# Arguments : $source_dir - the directory to scan. +# $section_list - a reference to the hashmap of sections. +# + +def ScanHeaders(source_dir, section_list, decl_list, get_types, options): + logging.info('Scanning source directory: %s', source_dir) + + # This array holds any subdirectories found. + subdirs = [] + + for file in sorted(os.listdir(source_dir)): + if file.startswith('.'): + continue + fullname = os.path.join(source_dir, file) + if os.path.isdir(fullname): + subdirs.append(file) + elif file.endswith('.h'): + ScanHeader(fullname, section_list, decl_list, get_types, options) + + # Now recursively scan the subdirectories. + for dir in subdirs: + matchstr = r'(\s|^)' + re.escape(dir) + r'(\s|$)' + if re.search(matchstr, options.ignore_headers): + continue + ScanHeaders(os.path.join(source_dir, dir), section_list, decl_list, + get_types, options) + + +# +# Function : ScanHeader +# Description : This scans a header file, looking for declarations of +# functions, macros, typedefs, structs and unions, which it +# outputs to the decl_list. +# Arguments : $input_file - the header file to scan. +# $section_list - a map of sections. +# $decl_list - a list of declarations +# Returns : it adds declarations to the appropriate list. +# + +def ScanHeader(input_file, section_list, decl_list, get_types, options): + global seen_headers + slist = [] # Holds the resulting list of declarations. + title = '' # Holds the title of the section + in_comment = 0 # True if we are in a comment. + in_declaration = '' # The type of declaration we are in, e.g. + # 'function' or 'macro'. + skip_block = 0 # True if we should skip a block. + symbol = None # The current symbol being declared. + decl = '' # Holds the declaration of the current symbol. + ret_type = None # For functions and function typedefs this + # holds the function's return type. + pre_previous_line = '' # The pre-previous line read in - some Gnome + # functions have the return type on one + # line, the function name on the next, + # and the rest of the declaration after. + previous_line = '' # The previous line read in - some Gnome + # functions have the return type on one line + # and the rest of the declaration after. + first_macro = 1 # Used to try to skip the standard #ifdef XXX + # define XXX at the start of headers. + level = None # Used to handle structs/unions which contain + # nested structs or unions. + internal = 0 # Set to 1 for internal symbols, we need to + # fully parse, but don't add them to docs + forward_decls = {} # Dict of forward declarations, we skip + # them if we find the real declaration + # later. + doc_comments = {} # Dict of doc-comments we found. + # The key is lowercase symbol name, val=1. + + file_basename = None + + deprecated_conditional_nest = 0 + ignore_conditional_nest = 0 + + deprecated = '' + doc_comment = '' + + # Don't scan headers twice + canonical_input_file = os.path.realpath(input_file) + if canonical_input_file in seen_headers: + logging.info('File already scanned: %s', input_file) + return + + seen_headers[canonical_input_file] = 1 + + file_basename = os.path.split(input_file)[1][:-2] # filename ends in .h + + # Check if the basename is in the list of headers to ignore. + matchstr = r'(\s|^)' + re.escape(file_basename) + r'\.h(\s|$)' + if re.search(matchstr, options.ignore_headers): + logging.info('File ignored: %s', input_file) + return + + # Check if the full name is in the list of headers to ignore. + matchstr = r'(\s|^)' + re.escape(input_file) + r'(\s|$)' + if re.search(matchstr, options.ignore_headers): + logging.info('File ignored: %s', input_file) + return + + if not os.path.exists(input_file): + logging.warning('File does not exist: %s', input_file) + return + + logging.info('Scanning %s', input_file) + + for line in open(input_file): + # If this is a private header, skip it. + if re.search(r'%^\s*/\*\s*<\s*private_header\s*>\s*\*/', line): + return + + # Skip to the end of the current comment. + if in_comment: + logging.info('Comment: %s', line.strip()) + doc_comment += line + if re.search(r'\*/', line): + m = re.search(r'\* ([a-zA-Z][a-zA-Z0-9_]+):', doc_comment) + if m: + doc_comments[m.group(1).lower()] = 1 + in_comment = 0 + doc_comment = '' + continue + + # Keep a count of #if, #ifdef, #ifndef nesting, + # and if we enter a deprecation-symbol-bracketed + # zone, take note. + m = re.search(r'^\s*#\s*if(?:n?def\b|\s+!?\s*defined\s*\()\s*(\w+)', line) + if m: + define_name = m.group(1) + if deprecated_conditional_nest < 1 and re.search(options.deprecated_guards, define_name): + deprecated_conditional_nest = 1 + elif deprecated_conditional_nest >= 1: + deprecated_conditional_nest += 1 + if ignore_conditional_nest == 0 and '__GTK_DOC_IGNORE__' in define_name: + ignore_conditional_nest = 1 + elif ignore_conditional_nest > 0: + ignore_conditional_nest = 1 + + elif re.search(r'^\s*#\sif', line): + if deprecated_conditional_nest >= 1: + deprecated_conditional_nest += 1 + + if ignore_conditional_nest > 0: + ignore_conditional_nest += 1 + elif re.search(r'^\s*#endif', line): + if deprecated_conditional_nest >= 1: + deprecated_conditional_nest -= 1 + + if ignore_conditional_nest > 0: + ignore_conditional_nest -= 1 + + # If we find a line containing _DEPRECATED, we hope that this is + # attribute based deprecation and also treat this as a deprecation + # guard, unless it's a macro definition. + if deprecated_conditional_nest == 0 and '_DEPRECATED' in line: + m = re.search(r'^\s*#\s*(if*|define)', line) + if not (m or in_declaration == 'enum'): + logging.info('Found deprecation annotation (decl: "%s"): "%s"', + in_declaration, line.strip()) + deprecated_conditional_nest += 0.1 + + # set flag that is used later when we do AddSymbolToList + if deprecated_conditional_nest > 0: + deprecated = '\n' + else: + deprecated = '' + + if ignore_conditional_nest: + continue + + if not in_declaration: + # Skip top-level comments. + m = re.search(r'^\s*/\*', line) + if m: + re.sub(r'^\s*/\*', '', line) + if re.search(r'\*/', line): + logging.info('Found one-line comment: %s', line.strip()) + else: + in_comment = 1 + doc_comment = line + logging.info('Found start of comment: %s', line.strip()) + continue + + logging.info('no decl: %s', line.strip()) + + # avoid generating regex with |'' (matching no string) + ignore_decorators = '' + if options.ignore_decorators: + ignore_decorators = '|' + options.ignore_decorators + + m = re.search(r'^\s*#\s*define\s+(\w+)', line) + # $1 $3 $4 $5 + m2 = re.search( + r'^\s*typedef\s+((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(', line) + # $1 $3 $4 $5 + m3 = re.search(r'^\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(', line) + # $1 $2 + m4 = re.search(r'^\s*(\**)\s*\(\*\s*(\w+)\)\s*\(', line) + # $1 $3 + m5 = re.search(r'^\s*typedef\s*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*', previous_line) + # $1 $3 $4 $5 + m6 = re.search( + r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((const\s+|G_CONST_RETURN\s+)?\w+)(\s+const)?\s*(\**)\s*\(\*\s*(\w+)\)\s*\(' % ignore_decorators, line) + m7 = re.search(r'^\s*enum\s+_?(\w+)\s+\{', line) + m8 = re.search(r'^\s*typedef\s+enum', line) + m9 = re.search(r'^\s*typedef\s+(struct|union)\s+_(\w+)\s+\2\s*;', line) + m10 = re.search(r'^\s*(struct|union)\s+(\w+)\s*;', line) + m11 = re.search(r'^\s*typedef\s+(struct|union)\s*\w*\s*{', line) + m12 = re.search(r'^\s*typedef\s+(?:struct|union)\s+\w+[\s\*]+(\w+)\s*;', line) + m13 = re.search(r'^\s*(G_GNUC_EXTENSION\s+)?typedef\s+(.+[\s\*])(\w+)(\s*\[[^\]]+\])*\s*;', line) + m14 = re.search( + r'^\s*(extern|[A-Za-z_]+VAR%s)\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*;' % ignore_decorators, line) + m15 = re.search( + r'^\s*((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*\=', line) + m16 = re.search(r'.*G_DECLARE_(FINAL_TYPE|DERIVABLE_TYPE|INTERFACE)\s*\(', line) + # $1 $2 $3 + m17 = re.search( + r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)([\s*]+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*(_[A-Za-z]\w*)\s*\(' % ignore_decorators, line) + # $1 $2 $3 + m18 = re.search( + r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)([\s*]+(?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*([A-Za-z]\w*)\s*\(' % ignore_decorators, line) + m19 = re.search(r'^\s*([A-Za-z]\w*)\s*\(', line) + m20 = re.search(r'^\s*\(', line) + m21 = re.search(r'^\s*struct\s+_?(\w+)', line) + m22 = re.search(r'^\s*union\s+_(\w+)', line) + + # MACROS + + if m: + symbol = m.group(1) + decl = line + # We assume all macros which start with '_' are private. + # We also try to skip the first macro if it looks like the + # standard #ifndef HEADER_FILE #define HEADER_FILE etc. + # And we only want TRUE & FALSE defined in GLib. + if not symbol.startswith('_') \ + and (not re.search(r'#ifndef\s+' + symbol, previous_line) + or first_macro == 0) \ + and ((symbol != 'TRUE' and symbol != 'FALSE') + or options.module == 'glib'): + in_declaration = 'macro' + logging.info('Macro: "%s"', symbol) + else: + logging.info('skipping Macro: "%s"', symbol) + in_declaration = 'macro' + internal = 1 + first_macro = 0 + + # TYPEDEF'D FUNCTIONS (i.e. user functions) + elif m2: + p3 = m2.group(3) or '' + ret_type = "%s%s %s" % (m2.group(1), p3, m2.group(4)) + symbol = m2.group(5) + decl = line[m2.end():] + in_declaration = 'user_function' + logging.info('user function (1): "%s", Returns: "%s"', symbol, ret_type) + + elif re.search(r'^\s*typedef\s*', previous_line) and m3: + p3 = m3.group(3) or '' + ret_type = '%s%s %s' % (m3.group(1), p3, m3.group(4)) + symbol = m3.group(5) + decl = line[m3.end():] + in_declaration = 'user_function' + logging.info('user function (2): "%s", Returns: "%s"', symbol, ret_type) + + elif re.search(r'^\s*typedef\s*', previous_line) and m4: + ret_type = m4.group(1) + symbol = m4.group(2) + decl = line[m4.end():] + if m5: + p3 = m5.group(3) or '' + ret_type = "%s%s %s" % (m5.group(1), p3, ret_type) + in_declaration = 'user_function' + logging.info('user function (3): "%s", Returns: "%s"', symbol, ret_type) + + # FUNCTION POINTER VARIABLES + elif m6: + p3 = m6.group(3) or '' + ret_type = '%s%s %s' % (m6.group(1), p3, m6.group(4)) + symbol = m6.group(5) + decl = line[m6.end():] + in_declaration = 'user_function' + logging.info('function pointer variable: "%s", Returns: "%s"', symbol, ret_type) + + # ENUMS + + elif m7: + re.sub(r'^\s*enum\s+_?(\w+)\s+\{', r'enum \1 {', line) + # We assume that 'enum _ {' is really the + # declaration of enum . + symbol = m7.group(1) + decl = line + in_declaration = 'enum' + logging.info('plain enum: "%s"', symbol) + + elif re.search(r'^\s*typedef\s+enum\s+_?(\w+)\s+\1\s*;', line): + # We skip 'typedef enum _;' as the enum will + # be declared elsewhere. + logging.info('skipping enum typedef: "%s"', line) + elif m8: + symbol = '' + decl = line + in_declaration = 'enum' + logging.info('typedef enum: -') + + # STRUCTS AND UNIONS + + elif m9: + # We've found a 'typedef struct _ ;' + # This could be an opaque data structure, so we output an + # empty declaration. If the structure is actually found that + # will override this. + structsym = m9.group(1).upper() + logging.info('%s typedef: "%s"', structsym, m9.group(2)) + forward_decls[m9.group(2)] = '<%s>\n%s\n%s\n' % ( + structsym, m9.group(2), deprecated, structsym) + + elif re.search(r'^\s*(?:struct|union)\s+_(\w+)\s*;', line): + # Skip private structs/unions. + logging.info('private struct/union') + + elif m10: + # Do a similar thing for normal structs as for typedefs above. + # But we output the declaration as well in this case, so we + # can differentiate it from a typedef. + structsym = m10.group(1).upper() + logging.info('%s:%s', structsym, m10.group(2)) + forward_decls[m10.group(2)] = '<%s>\n%s\n%s%s\n' % ( + structsym, m10.group(2), line, deprecated, structsym) + + elif m11: + symbol = '' + decl = line + level = 0 + in_declaration = m11.group(1) + logging.info('typedef struct/union "%s"', in_declaration) + + # OTHER TYPEDEFS + + elif m12: + logging.info('Found struct/union(*) typedef "%s": "%s"', m12.group(1), line) + if AddSymbolToList(slist, m12.group(1)): + decl_list.append('\n%s\n%s%s\n' % (m12.group(1), deprecated, line)) + + elif m13: + if m13.group(2).split()[0] not in ('struct', 'union'): + logging.info('Found typedef: "%s"', line) + if AddSymbolToList(slist, m13.group(3)): + decl_list.append( + '\n%s\n%s%s\n' % (m13.group(3), deprecated, line)) + elif re.search(r'^\s*typedef\s+', line): + logging.info('Skipping typedef: "%s"', line) + + # VARIABLES (extern'ed variables) + + elif m14: + symbol = m14.group(6) + line = re.sub(r'^\s*([A-Za-z_]+VAR)\b', r'extern', line) + decl = line + logging.info('Possible extern var "%s": "%s"', symbol, decl) + if AddSymbolToList(slist, symbol): + decl_list.append('\n%s\n%s%s\n' % (symbol, deprecated, decl)) + + # VARIABLES + + elif m15: + symbol = m15.group(5) + decl = line + logging.info('Possible global var" %s": "%s"', symbol, decl) + if AddSymbolToList(slist, symbol): + decl_list.append('\n%s\n%s%s\n' % (symbol, deprecated, decl)) + + # G_DECLARE_* + + elif m16: + in_declaration = 'g-declare' + symbol = 'G_DECLARE_' + m16.group(1) + decl = line[m16.end():] + + # FUNCTIONS + + # We assume that functions which start with '_' are private, so + # we skip them. + elif m17: + ret_type = m17.group(1) + if m17.group(2): + ret_type += ' ' + m17.group(2) + symbol = m17.group(3) + decl = line[m17.end():] + logging.info('internal Function: "%s", Returns: "%s""%s"', symbol, m17.group(1), m17.group(2)) + in_declaration = 'function' + internal = 1 + if line.strip().startswith('G_INLINE_FUNC'): + logging.info('skip block after inline function') + # now we we need to skip a whole { } block + skip_block = 1 + + elif m18: + ret_type = m18.group(1) + if m18.group(2): + ret_type += ' ' + m18.group(2) + symbol = m18.group(3) + decl = line[m18.end():] + logging.info('Function (1): "%s", Returns: "%s""%s"', symbol, m18.group(1), m18.group(2)) + in_declaration = 'function' + if line.strip().startswith('G_INLINE_FUNC'): + logging.info('skip block after inline function') + # now we we need to skip a whole { } block + skip_block = 1 + + # Try to catch function declarations which have the return type on + # the previous line. But we don't want to catch complete functions + # which have been declared G_INLINE_FUNC, e.g. g_bit_nth_lsf in + # glib, or 'static inline' functions. + elif m19: + symbol = m19.group(1) + decl = line[m19.end():] + + previous_line_words = previous_line.strip().split() + + if not previous_line.strip().startswith('G_INLINE_FUNC'): + if not previous_line_words or previous_line_words[0] != 'static': + # $1 $2 + pm = re.search(r'^\s*(?:\b(?:extern%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$' % + ignore_decorators, previous_line) + if pm: + ret_type = pm.group(1) + if pm.group(2): + ret_type += ' ' + pm.group(2) + logging.info('Function (2): "%s", Returns: "%s"', symbol, ret_type) + in_declaration = 'function' + else: + logging.info('skip block after inline function') + # now we we need to skip a whole { } block + skip_block = 1 + # $1 $2 + pm = re.search(r'^\s*(?:\b(?:extern|static|inline%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$' % + ignore_decorators, previous_line) + if pm: + ret_type = pm.group(1) + if pm.group(2): + ret_type += ' ' + pm.group(2) + logging.info('Function (3): "%s", Returns: "%s"', symbol, ret_type) + in_declaration = 'function' + else: + if not previous_line_words or previous_line_words[0] != 'static': + logging.info('skip block after inline function') + # now we we need to skip a whole { } block + skip_block = 1 + # $1 $2 + pm = re.search(r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|long\s+|short\s+|struct\s+|union\s+|enum\s+)*\w+)((?:\s*(?:\*+|\bconst\b|\bG_CONST_RETURN\b))*)\s*$' % + ignore_decorators, previous_line) + if pm: + ret_type = pm.group(1) + if pm.group(2): + ret_type += ' ' + pm.group(2) + logging.info('Function (4): "%s", Returns: "%s"', symbol, ret_type) + in_declaration = 'function' + + # Try to catch function declarations with the return type and name + # on the previous line(s), and the start of the parameters on this. + elif m20: + decl = line[m20.end():] + pm = re.search( + r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|enum\s+)*\w+)(\s+\*+|\*+|\s)\s*([A-Za-z]\w*)\s*$' % ignore_decorators, previous_line) + ppm = re.search(r'^\s*(?:\b(?:extern|G_INLINE_FUNC%s)\s*)*((?:const\s+|G_CONST_RETURN\s+|signed\s+|unsigned\s+|struct\s+|union\s+|enum\s+)*\w+(?:\**\s+\**(?:const|G_CONST_RETURN))?(?:\s+|\s*\*+))\s*$' % + ignore_decorators, pre_previous_line) + if pm: + ret_type = pm.group(1) + ' ' + pm.group(2) + symbol = pm.group(3) + in_declaration = 'function' + logging.info('Function (5): "%s", Returns: "%s"', symbol, ret_type) + + elif re.search(r'^\s*\w+\s*$', previous_line) and ppm: + ret_type = ppm.group(1) + ret_type = re.sub(r'\s*\n', '', ret_type, flags=re.MULTILINE) + in_declaration = 'function' + + symbol = previous_line + symbol = re.sub(r'^\s+', '', symbol) + symbol = re.sub(r'\s*\n', '', symbol, flags=re.MULTILINE) + logging.info('Function (6): "%s", Returns: "%s"', symbol, ret_type) + + #} elsif (m/^extern\s+/) { + # print "DEBUG: Skipping extern: $_" + + # STRUCTS + elif re.search(r'^\s*struct\s+_?(\w+)\s*\*', line): + # Skip 'struct _ *', since it could be a + # return type on its own line. + pass + elif m21: + # We assume that 'struct _' is really the + # declaration of struct . + symbol = m21.group(1) + decl = line + # we will find the correct level as below we do $level += tr/{// + level = 0 + in_declaration = 'struct' + logging.info('Struct(_): "%s"', symbol) + + # UNIONS + elif re.search(r'^\s*union\s+_(\w+)\s*\*', line): + # Skip 'union _ *' (see above) + pass + elif m22: + symbol = m22.group(1) + decl = line + level = 0 + in_declaration = 'union' + logging.info('Union(_): "%s"', symbol) + else: + logging.info('in decl: skip=%s %s', skip_block, line.strip()) + # If we were already in the middle of a declaration, we simply add + # the current line onto the end of it. + if skip_block == 0: + decl += line + else: + # Remove all nested pairs of curly braces. + brace_remover = r'{[^{]*}' + bm = re.search(brace_remover, line) + while bm: + line = re.sub(brace_remover, '', line) + bm = re.search(brace_remover, line) + # Then hope at most one remains in the line... + bm = re.search(r'(.*?){', line) + if bm: + if skip_block == 1: + decl += bm.group(1) + skip_block += 1 + elif '}' in line: + skip_block -= 1 + if skip_block == 1: + # this is a hack to detect the end of declaration + decl += ';' + skip_block = 0 + logging.info('2: ---') + + else: + if skip_block == 1: + decl += line + + if in_declaration == "g-declare": + dm = re.search(r'\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*\).*$', decl) + # FIXME the original code does s// stuff here and we don't. Is it necessary? + if dm: + ModuleObjName = dm.group(1) + module_obj_name = dm.group(2) + if options.rebuild_types: + get_types.append(module_obj_name + '_get_type') + forward_decls[ModuleObjName] = '\n%s\n%s\n' % (ModuleObjName, deprecated) + if symbol.startswith('G_DECLARE_DERIVABLE'): + forward_decls[ModuleObjName + 'Class'] = '\n%sClass\n%s\n' % ( + ModuleObjName, deprecated) + if symbol.startswith('G_DECLARE_INTERFACE'): + forward_decls[ModuleObjName + 'Interface'] = '\n%sInterface\n%s\n' % ( + ModuleObjName, deprecated) + in_declaration = '' + + # Note that sometimes functions end in ') G_GNUC_PRINTF (2, 3);' or + # ') __attribute__ (...);'. + if in_declaration == 'function': + regex = r'\)\s*(G_GNUC_.*|.*DEPRECATED.*%s\s*|__attribute__\s*\(.*\)\s*)*;.*$' % ignore_decorators + pm = re.search(regex, decl, flags=re.MULTILINE) + if pm: + logging.info('scrubbing:[%s]', decl.strip()) + decl = re.sub(regex, '', decl, flags=re.MULTILINE) + logging.info('scrubbed:[%s]', decl.strip()) + if internal == 0: + decl = re.sub(r'/\*.*?\*/', '', decl, flags=re.MULTILINE) # remove comments. + decl = re.sub(r'\s*\n\s*(?!$)', ' ', decl, flags=re.MULTILINE) + # consolidate whitespace at start/end of lines. + decl = decl.strip() + ret_type = re.sub(r'/\*.*?\*/', '', ret_type) # remove comments in ret type. + if AddSymbolToList(slist, symbol): + decl_list.append('\n%s\n%s%s\n%s\n\n' % + (symbol, deprecated, ret_type, decl)) + if options.rebuild_types: + # check if this looks like a get_type function and if so remember + if symbol.endswith('_get_type') and 'GType' in ret_type and re.search(r'^(void|)$', decl): + logging.info( + "Adding get-type: [%s] [%s] [%s]\tfrom %s", ret_type, symbol, decl, input_file) + get_types.append(symbol) + else: + internal = 0 + deprecated_conditional_nest = int(deprecated_conditional_nest) + in_declaration = '' + skip_block = 0 + + if in_declaration == 'user_function': + if re.search(r'\).*$', decl): + decl = re.sub(r'\).*$', '', decl) + if AddSymbolToList(slist, symbol): + decl_list.append('\n%s\n%s%s\n%s\n' % + (symbol, deprecated, ret_type, decl)) + deprecated_conditional_nest = int(deprecated_conditional_nest) + in_declaration = '' + + if in_declaration == 'macro': + if not re.search(r'\\\s*$', decl): + if internal == 0: + if AddSymbolToList(slist, symbol): + decl_list.append('\n%s\n%s%s\n' % (symbol, deprecated, decl)) + else: + internal = 0 + deprecated_conditional_nest = int(deprecated_conditional_nest) + in_declaration = '' + + if in_declaration == 'enum': + em = re.search(r'\}\s*(\w+)?;\s*$', decl) + if em: + if symbol == '': + symbol = em.group(1) + if AddSymbolToList(slist, symbol): + decl_list.append('\n%s\n%s%s\n' % (symbol, deprecated, decl)) + deprecated_conditional_nest = int(deprecated_conditional_nest) + in_declaration = '' + + # We try to handle nested stucts/unions, but unmatched brackets in + # comments will cause problems. + if in_declaration == 'struct' or in_declaration == 'union': + sm = re.search(r'\n\}\s*(\w*);\s*$', decl) + if level <= 1 and sm: + if symbol == '': + symbol = sm.group(1) + + bm = re.search(r'^(\S+)(Class|Iface|Interface)\b', symbol) + if bm: + objectname = bm.group(1) + logging.info('Found object: "%s"', objectname) + title = '%s' % objectname + + logging.info('Store struct: "%s"', symbol) + if AddSymbolToList(slist, symbol): + structsym = in_declaration.upper() + decl_list.append('<%s>\n%s\n%s%s\n' % + (structsym, symbol, deprecated, decl, structsym)) + if symbol in forward_decls: + del forward_decls[symbol] + deprecated_conditional_nest = int(deprecated_conditional_nest) + in_declaration = '' + else: + # We use tr to count the brackets in the line, and adjust + # $level accordingly. + level += line.count('{') + level -= line.count('}') + logging.info('struct/union level : %d', level) + + pre_previous_line = previous_line + previous_line = line + + # print remaining forward declarations + for symbol in sorted(iterkeys(forward_decls)): + if forward_decls[symbol]: + AddSymbolToList(slist, symbol) + decl_list.append(forward_decls[symbol]) + + # add title + slist = [title] + slist + + logging.info("Scanning %s done", input_file) + + # Try to separate the standard macros and functions, placing them at the + # end of the current section, in a subsection named 'Standard'. + # do this in a loop to catch object, enums and flags + klass = lclass = prefix = lprefix = None + standard_decl = [] + liststr = '\n'.join(s for s in slist if s) + '\n' + while True: + m = re.search(r'^(\S+)_IS_(\S*)_CLASS\n', liststr, flags=re.MULTILINE) + m2 = re.search(r'^(\S+)_IS_(\S*)\n', liststr, flags=re.MULTILINE) + m3 = re.search(r'^(\S+?)_(\S*)_get_type\n', liststr, flags=re.MULTILINE) + if m: + prefix = m.group(1) + lprefix = prefix.lower() + klass = m.group(2) + lclass = klass.lower() + logging.info("Found gobject type '%s_%s' from is_class macro", prefix, klass) + elif m2: + prefix = m2.group(1) + lprefix = prefix.lower() + klass = m2.group(2) + lclass = klass.lower() + logging.info("Found gobject type '%s_%s' from is_ macro", prefix, klass) + elif m3: + lprefix = m3.group(1) + prefix = lprefix.upper() + lclass = m3.group(2) + klass = lclass.upper() + logging.info("Found gobject type '%s_%s' from get_type function", prefix, klass) + else: + break + + cclass = lclass + cclass = cclass.replace('_', '') + mtype = lprefix + cclass + + liststr, standard_decl = replace_once(liststr, standard_decl, r'^%sPrivate\n' % mtype) + + # We only leave XxYy* in the normal section if they have docs + if mtype not in doc_comments: + logging.info(" Hide instance docs for %s", mtype) + liststr, standard_decl = replace_once(liststr, standard_decl, r'^%s\n' % mtype) + + if mtype + 'class' not in doc_comments: + logging.info(" Hide class docs for %s", mtype) + liststr, standard_decl = replace_once(liststr, standard_decl, r'^%sClass\n' % mtype) + + if mtype + 'interface' not in doc_comments: + logging.info(" Hide iface docs for %s", mtype) + liststr, standard_decl = replace_once(liststr, standard_decl, r'%sInterface\n' % mtype) + + if mtype + 'iface' not in doc_comments: + logging.info(" Hide iface docs for " + mtype) + liststr, standard_decl = replace_once(liststr, standard_decl, r'%sIface\n' % mtype) + + liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_IS_%s\n' % klass) + liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_TYPE_%s\n' % klass) + liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_get_type\n' % lclass) + liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_CLASS\n' % klass) + liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_IS_%s_CLASS\n' % klass) + liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_GET_CLASS\n' % klass) + liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_GET_IFACE\n' % klass) + liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s_GET_INTERFACE\n' % klass) + # We do this one last, otherwise it tends to be caught by the IS_$class macro + liststr, standard_decl = replace_all(liststr, standard_decl, r'^\S+_%s\n' % klass) + + logging.info('Decl:%s---', liststr) + logging.info('Std :%s---', ''.join(sorted(standard_decl))) + if len(standard_decl): + # sort the symbols + liststr += '\n' + ''.join(sorted(standard_decl)) + + if liststr != '': + if file_basename not in section_list: + section_list[file_basename] = '' + section_list[file_basename] += "
\n%s\n%s
\n\n" % (file_basename, liststr) + + +def replace_once(liststr, standard_decl, regex): + mre = re.search(regex, liststr, flags=re.IGNORECASE | re.MULTILINE) + if mre: + standard_decl.append(mre.group(0)) + liststr = re.sub(regex, '', liststr, flags=re.IGNORECASE | re.MULTILINE) + return liststr, standard_decl + + +def replace_all(liststr, standard_decl, regex): + mre = re.search(regex, liststr, flags=re.MULTILINE) + while mre: + standard_decl.append(mre.group(0)) + liststr = re.sub(regex, '', liststr, flags=re.MULTILINE) + mre = re.search(regex, liststr, flags=re.MULTILINE) + return liststr, standard_decl + + +def AddSymbolToList(slist, symbol): + """ Adds symbol to list of declaration if not already present. + + Args: + slist: The list of symbols. + symbol: The symbol to add to the list. + """ + if symbol in slist: + # logging.info('Symbol %s already in list. skipping', symbol) + # we return False to skip outputting another entry to -decl.txt + # this is to avoid redeclarations (e.g. in conditional sections). + return False + slist.append(symbol) + return True diff --git a/gtkdoc/scangobj.py b/gtkdoc/scangobj.py new file mode 100644 index 0000000..e6db6cd --- /dev/null +++ b/gtkdoc/scangobj.py @@ -0,0 +1,1295 @@ +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 1998 Damon Chaplin +# 2007-2016 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +""" +The scangobj tool gets information about object hierarchies and signals by +compiling and running a small C program. CFLAGS and LDFLAGS must be set +appropriately before running this script. +""" + +import logging +import os +import string +import subprocess + +from . import common, config + + +COMMON_INCLUDES = """ +#include +#include +#include +#include +#include +""" + +QUERY_CHILD_PROPS_PROTOTYPE = "extern GParamSpec** %s (gpointer class, guint *n_properties);" + +QUERY_CHILD_PROPS_CODE = """ + if (!child_prop) { + properties = %s (class, &n_properties); + if (properties) { + child_prop = TRUE; + continue; + } + } +""" + +MAIN_CODE = """ + +#ifdef GTK_IS_WIDGET_CLASS +#include +#endif +static GType object_types[$ntypes]; + +static GType * +get_object_types (void) +{ + gpointer g_object_class; + gint i = 0; + +${get_types} + object_types[i] = G_TYPE_INVALID; + + /* reference the GObjectClass to initialize the param spec pool + * potentially needed by interfaces. See http://bugs.gnome.org/571820 */ + g_object_class = g_type_class_ref (G_TYPE_OBJECT); + + /* Need to make sure all the types are loaded in and initialize + * their signals and properties. + */ + for (i=0; object_types[i]; i++) { + if (G_TYPE_IS_CLASSED (object_types[i])) + g_type_class_ref (object_types[i]); + if (G_TYPE_IS_INTERFACE (object_types[i])) + g_type_default_interface_ref (object_types[i]); + } + + g_type_class_unref (g_object_class); + + return object_types; +} + +/* + * This uses GObject type functions to output signal prototypes and the object + * hierarchy. + */ + +/* The output files */ +const gchar *signals_filename = "$new_signals_filename"; +const gchar *hierarchy_filename = "$new_hierarchy_filename"; +const gchar *interfaces_filename = "$new_interfaces_filename"; +const gchar *prerequisites_filename = "$new_prerequisites_filename"; +const gchar *args_filename = "$new_args_filename"; + +static void output_signals (void); +static void output_object_signals (FILE *fp, + GType object_type); +static void output_object_signal (FILE *fp, + const gchar *object_class_name, + guint signal_id); +static const gchar * get_type_name (GType type, + gboolean * is_pointer); +static void output_object_hierarchy (void); +static void output_hierarchy (FILE *fp, + GType type, + guint level); + +static void output_object_interfaces (void); +static void output_interfaces (FILE *fp, + GType type); + +static void output_interface_prerequisites (void); +static void output_prerequisites (FILE *fp, + GType type); + +static void output_args (void); +static void output_object_args (FILE *fp, GType object_type); + +int +main (int argc, char *argv[]) +{ + ${type_init_func}; + + get_object_types (); + + output_signals (); + output_object_hierarchy (); + output_object_interfaces (); + output_interface_prerequisites (); + output_args (); + + return 0; +} + +static void +output_signals (void) +{ + FILE *fp; + gint i; + + fp = fopen (signals_filename, "w"); + if (fp == NULL) { + g_warning ("Couldn't open output file: %s : %s", signals_filename, g_strerror(errno)); + return; + } + + for (i = 0; object_types[i]; i++) + output_object_signals (fp, object_types[i]); + + fclose (fp); +} + +static gint +compare_signals (const void *a, const void *b) +{ + const guint *signal_a = a; + const guint *signal_b = b; + + return strcmp (g_signal_name (*signal_a), g_signal_name (*signal_b)); +} + +/* This outputs all the signals of one object. */ +static void +output_object_signals (FILE *fp, GType object_type) +{ + const gchar *object_class_name; + guint *signals, n_signals; + guint sig; + + if (G_TYPE_IS_INSTANTIATABLE (object_type) || + G_TYPE_IS_INTERFACE (object_type)) { + + object_class_name = g_type_name (object_type); + + signals = g_signal_list_ids (object_type, &n_signals); + qsort (signals, n_signals, sizeof (guint), compare_signals); + + for (sig = 0; sig < n_signals; sig++) { + output_object_signal (fp, object_class_name, signals[sig]); + } + g_free (signals); + } +} + +/* This outputs one signal. */ +static void +output_object_signal (FILE *fp, + const gchar *object_name, + guint signal_id) +{ + GSignalQuery query_info; + const gchar *type_name, *ret_type, *object_arg, *arg_name; + gchar *pos, *object_arg_lower; + gboolean is_pointer; + gchar buffer[1024]; + guint i, param; + gint param_num, widget_num, event_num, callback_num; + gint *arg_num; + gchar signal_name[128]; + gchar flags[16]; + + /* g_print ("Object: %s Signal: %u\\n", object_name, signal_id);*/ + + param_num = 1; + widget_num = event_num = callback_num = 0; + + g_signal_query (signal_id, &query_info); + + /* Output the signal object type and the argument name. We assume the + * type is a pointer - I think that is OK. We remove "Gtk" or "Gnome" and + * convert to lower case for the argument name. */ + pos = buffer; + sprintf (pos, "%s ", object_name); + pos += strlen (pos); + + /* Try to come up with a sensible variable name for the first arg + * It chops off 2 know prefixes :/ and makes the name lowercase + * It should replace lowercase -> uppercase with '_' + * GFileMonitor -> file_monitor + * GIOExtensionPoint -> extension_point + * GtkTreeView -> tree_view + * if 2nd char is upper case too + * search for first lower case and go back one char + * else + * search for next upper case + */ + if (!strncmp (object_name, "Gtk", 3)) + object_arg = object_name + 3; + else if (!strncmp (object_name, "Gnome", 5)) + object_arg = object_name + 5; + else + object_arg = object_name; + + object_arg_lower = g_ascii_strdown (object_arg, -1); + sprintf (pos, "*%s\\n", object_arg_lower); + pos += strlen (pos); + if (!strncmp (object_arg_lower, "widget", 6)) + widget_num = 2; + g_free(object_arg_lower); + + /* Convert signal name to use underscores rather than dashes '-'. */ + strncpy (signal_name, query_info.signal_name, 127); + signal_name[127] = '\\0'; + for (i = 0; signal_name[i]; i++) { + if (signal_name[i] == '-') + signal_name[i] = '_'; + } + + /* Output the signal parameters. */ + for (param = 0; param < query_info.n_params; param++) { + type_name = get_type_name (query_info.param_types[param] & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer); + + /* Most arguments to the callback are called "arg1", "arg2", etc. + GtkWidgets are called "widget", "widget2", ... + GtkCallbacks are called "callback", "callback2", ... */ + if (!strcmp (type_name, "GtkWidget")) { + arg_name = "widget"; + arg_num = &widget_num; + } + else if (!strcmp (type_name, "GtkCallback") + || !strcmp (type_name, "GtkCCallback")) { + arg_name = "callback"; + arg_num = &callback_num; + } + else { + arg_name = "arg"; + arg_num = ¶m_num; + } + sprintf (pos, "%s ", type_name); + pos += strlen (pos); + + if (!arg_num || *arg_num == 0) + sprintf (pos, "%s%s\\n", is_pointer ? "*" : " ", arg_name); + else + sprintf (pos, "%s%s%i\\n", is_pointer ? "*" : " ", arg_name, + *arg_num); + pos += strlen (pos); + + if (arg_num) { + if (*arg_num == 0) + *arg_num = 2; + else + *arg_num += 1; + } + } + + pos = flags; + /* We use one-character flags for simplicity. */ + if (query_info.signal_flags & G_SIGNAL_RUN_FIRST) + *pos++ = 'f'; + if (query_info.signal_flags & G_SIGNAL_RUN_LAST) + *pos++ = 'l'; + if (query_info.signal_flags & G_SIGNAL_RUN_CLEANUP) + *pos++ = 'c'; + if (query_info.signal_flags & G_SIGNAL_NO_RECURSE) + *pos++ = 'r'; + if (query_info.signal_flags & G_SIGNAL_DETAILED) + *pos++ = 'd'; + if (query_info.signal_flags & G_SIGNAL_ACTION) + *pos++ = 'a'; + if (query_info.signal_flags & G_SIGNAL_NO_HOOKS) + *pos++ = 'h'; + *pos = 0; + + /* Output the return type and function name. */ + ret_type = get_type_name (query_info.return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE, &is_pointer); + + fprintf (fp, + "\\n%s::%s\\n%s%s\\n%s\\n%s\\n\\n", + object_name, query_info.signal_name, ret_type, is_pointer ? "*" : "", flags, buffer); +} + + +/* Returns the type name to use for a signal argument or return value, given + the GtkType from the signal info. It also sets is_pointer to TRUE if the + argument needs a '*' since it is a pointer. */ +static const gchar * +get_type_name (GType type, gboolean * is_pointer) +{ + const gchar *type_name; + + *is_pointer = FALSE; + type_name = g_type_name (type); + + switch (type) { + case G_TYPE_NONE: + case G_TYPE_CHAR: + case G_TYPE_UCHAR: + case G_TYPE_BOOLEAN: + case G_TYPE_INT: + case G_TYPE_UINT: + case G_TYPE_LONG: + case G_TYPE_ULONG: + case G_TYPE_FLOAT: + case G_TYPE_DOUBLE: + case G_TYPE_POINTER: + /* These all have normal C type names so they are OK. */ + return type_name; + + case G_TYPE_STRING: + /* A GtkString is really a gchar*. */ + *is_pointer = TRUE; + return "gchar"; + + case G_TYPE_ENUM: + case G_TYPE_FLAGS: + /* We use a gint for both of these. Hopefully a subtype with a decent + name will be registered and used instead, as GTK+ does itself. */ + return "gint"; + + case G_TYPE_BOXED: + /* The boxed type shouldn't be used itself, only subtypes. Though we + return 'gpointer' just in case. */ + return "gpointer"; + + case G_TYPE_PARAM: + /* A GParam is really a GParamSpec*. */ + *is_pointer = TRUE; + return "GParamSpec"; + +#if GLIB_CHECK_VERSION (2, 25, 9) + case G_TYPE_VARIANT: + *is_pointer = TRUE; + return "GVariant"; +#endif + +default: + break; + } + + /* For all GObject subclasses we can use the class name with a "*", + e.g. 'GtkWidget *'. */ + if (g_type_is_a (type, G_TYPE_OBJECT)) + *is_pointer = TRUE; + + /* Also catch non GObject root types */ + if (G_TYPE_IS_CLASSED (type)) + *is_pointer = TRUE; + + /* All boxed subtypes will be pointers as well. */ + /* Exception: GStrv */ + if (g_type_is_a (type, G_TYPE_BOXED) && + !g_type_is_a (type, G_TYPE_STRV)) + *is_pointer = TRUE; + + /* All pointer subtypes will be pointers as well. */ + if (g_type_is_a (type, G_TYPE_POINTER)) + *is_pointer = TRUE; + + /* But enums are not */ + if (g_type_is_a (type, G_TYPE_ENUM) || + g_type_is_a (type, G_TYPE_FLAGS)) + *is_pointer = FALSE; + + return type_name; +} + + +/* This outputs the hierarchy of all objects which have been initialized, + i.e. by calling their XXX_get_type() initialization function. */ +static void +output_object_hierarchy (void) +{ + FILE *fp; + gint i,j; + GType root, type; + GType root_types[$ntypes] = { G_TYPE_INVALID, }; + + fp = fopen (hierarchy_filename, "w"); + if (fp == NULL) { + g_warning ("Couldn't open output file: %s : %s", hierarchy_filename, g_strerror(errno)); + return; + } + output_hierarchy (fp, G_TYPE_OBJECT, 0); + output_hierarchy (fp, G_TYPE_INTERFACE, 0); + + for (i=0; object_types[i]; i++) { + root = object_types[i]; + while ((type = g_type_parent (root))) { + root = type; + } + if ((root != G_TYPE_OBJECT) && (root != G_TYPE_INTERFACE)) { + for (j=0; root_types[j]; j++) { + if (root == root_types[j]) { + root = G_TYPE_INVALID; break; + } + } + if(root) { + root_types[j] = root; + output_hierarchy (fp, root, 0); + } + } + } + + fclose (fp); +} + +/* This is called recursively to output the hierarchy of a object. */ +static void +output_hierarchy (FILE *fp, + GType type, + guint level) +{ + guint i; + GType *children; + guint n_children; + + if (!type) + return; + + for (i = 0; i < level; i++) + fprintf (fp, " "); + fprintf (fp, "%s\\n", g_type_name (type)); + + children = g_type_children (type, &n_children); + + for (i=0; i < n_children; i++) + output_hierarchy (fp, children[i], level + 1); + + g_free (children); +} + +static void output_object_interfaces (void) +{ + guint i; + FILE *fp; + + fp = fopen (interfaces_filename, "w"); + if (fp == NULL) { + g_warning ("Couldn't open output file: %s : %s", interfaces_filename, g_strerror(errno)); + return; + } + output_interfaces (fp, G_TYPE_OBJECT); + + for (i = 0; object_types[i]; i++) { + if (!g_type_parent (object_types[i]) && + (object_types[i] != G_TYPE_OBJECT) && + G_TYPE_IS_INSTANTIATABLE (object_types[i])) { + output_interfaces (fp, object_types[i]); + } + } + fclose (fp); +} + +static void +output_interfaces (FILE *fp, + GType type) +{ + guint i; + GType *children, *interfaces; + guint n_children, n_interfaces; + + if (!type) + return; + + interfaces = g_type_interfaces (type, &n_interfaces); + + if (n_interfaces > 0) { + fprintf (fp, "%s", g_type_name (type)); + for (i=0; i < n_interfaces; i++) + fprintf (fp, " %s", g_type_name (interfaces[i])); + fprintf (fp, "\\n"); + } + g_free (interfaces); + + children = g_type_children (type, &n_children); + + for (i=0; i < n_children; i++) + output_interfaces (fp, children[i]); + + g_free (children); +} + +static void output_interface_prerequisites (void) +{ + FILE *fp; + + fp = fopen (prerequisites_filename, "w"); + if (fp == NULL) { + g_warning ("Couldn't open output file: %s : %s", prerequisites_filename, g_strerror(errno)); + return; + } + output_prerequisites (fp, G_TYPE_INTERFACE); + fclose (fp); +} + +static void +output_prerequisites (FILE *fp, + GType type) +{ +#if GLIB_CHECK_VERSION(2,1,0) + guint i; + GType *children, *prerequisites; + guint n_children, n_prerequisites; + + if (!type) + return; + + prerequisites = g_type_interface_prerequisites (type, &n_prerequisites); + + if (n_prerequisites > 0) { + fprintf (fp, "%s", g_type_name (type)); + for (i=0; i < n_prerequisites; i++) + fprintf (fp, " %s", g_type_name (prerequisites[i])); + fprintf (fp, "\\n"); + } + g_free (prerequisites); + + children = g_type_children (type, &n_children); + + for (i=0; i < n_children; i++) + output_prerequisites (fp, children[i]); + + g_free (children); +#endif +} + +static void +output_args (void) +{ + FILE *fp; + gint i; + + fp = fopen (args_filename, "w"); + if (fp == NULL) { + g_warning ("Couldn't open output file: %s : %s", args_filename, g_strerror(errno)); + return; + } + + for (i = 0; object_types[i]; i++) { + output_object_args (fp, object_types[i]); + } + + fclose (fp); +} + +static gint +compare_param_specs (const void *a, const void *b) +{ + GParamSpec *spec_a = *(GParamSpec **)a; + GParamSpec *spec_b = *(GParamSpec **)b; + + return strcmp (g_param_spec_get_name (spec_a), g_param_spec_get_name (spec_b)); +} + +/* Its common to have unsigned properties restricted + * to the signed range. Therefore we make this look + * a bit nicer by spelling out the max constants. + */ + +/* Don't use "==" with floats, it might trigger a gcc warning. */ +#define GTKDOC_COMPARE_FLOAT(x, y) (x <= y && x >= y) + +static gchar* +describe_double_constant (gdouble value) +{ + gchar *desc; + + if (GTKDOC_COMPARE_FLOAT (value, G_MAXDOUBLE)) + desc = g_strdup ("G_MAXDOUBLE"); + else if (GTKDOC_COMPARE_FLOAT (value, G_MINDOUBLE)) + desc = g_strdup ("G_MINDOUBLE"); + else if (GTKDOC_COMPARE_FLOAT (value, -G_MAXDOUBLE)) + desc = g_strdup ("-G_MAXDOUBLE"); + else if (GTKDOC_COMPARE_FLOAT (value, G_MAXFLOAT)) + desc = g_strdup ("G_MAXFLOAT"); + else if (GTKDOC_COMPARE_FLOAT (value, G_MINFLOAT)) + desc = g_strdup ("G_MINFLOAT"); + else if (GTKDOC_COMPARE_FLOAT (value, -G_MAXFLOAT)) + desc = g_strdup ("-G_MAXFLOAT"); + else{ + /* make sure floats are output with a decimal dot irrespective of + * current locale. Use formatd since we want human-readable numbers + * and do not need the exact same bit representation when deserialising */ + desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE); + g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g", value); + } + + return desc; +} + +static gchar* +describe_signed_constant (gsize size, gint64 value) +{ + gchar *desc = NULL; + + switch (size) { + case 2: + if (sizeof (int) == 2) { + if (value == G_MAXINT) + desc = g_strdup ("G_MAXINT"); + else if (value == G_MININT) + desc = g_strdup ("G_MININT"); + } + break; + case 4: + if (sizeof (int) == 4) { + if (value == G_MAXINT) + desc = g_strdup ("G_MAXINT"); + else if (value == G_MININT) + desc = g_strdup ("G_MININT"); + } + if (value == G_MAXLONG) + desc = g_strdup ("G_MAXLONG"); + else if (value == G_MINLONG) + desc = g_strdup ("G_MINLONG"); + break; + case 8: + if (value == G_MAXINT64) + desc = g_strdup ("G_MAXINT64"); + else if (value == G_MININT64) + desc = g_strdup ("G_MININT64"); + break; + default: + break; + } + if (!desc) + desc = g_strdup_printf ("%" G_GINT64_FORMAT, value); + + return desc; +} + +static gchar* +describe_unsigned_constant (gsize size, guint64 value) +{ + gchar *desc = NULL; + + switch (size) { + case 2: + if (sizeof (int) == 2) { + if (value == (guint64)G_MAXINT) + desc = g_strdup ("G_MAXINT"); + else if (value == G_MAXUINT) + desc = g_strdup ("G_MAXUINT"); + } + break; + case 4: + if (sizeof (int) == 4) { + if (value == (guint64)G_MAXINT) + desc = g_strdup ("G_MAXINT"); + else if (value == G_MAXUINT) + desc = g_strdup ("G_MAXUINT"); + } + if (value == (guint64)G_MAXLONG) + desc = g_strdup ("G_MAXLONG"); + else if (value == G_MAXULONG) + desc = g_strdup ("G_MAXULONG"); + break; + case 8: + if (value == G_MAXINT64) + desc = g_strdup ("G_MAXINT64"); + else if (value == G_MAXUINT64) + desc = g_strdup ("G_MAXUINT64"); + break; + default: + break; + } + if (!desc) + desc = g_strdup_printf ("%" G_GUINT64_FORMAT, value); + + return desc; +} + +static gchar* +describe_type (GParamSpec *spec) +{ + gchar *desc; + gchar *lower; + gchar *upper; + + if (G_IS_PARAM_SPEC_CHAR (spec)) { + GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec); + + lower = describe_signed_constant (sizeof(gchar), pspec->minimum); + upper = describe_signed_constant (sizeof(gchar), pspec->maximum); + if (pspec->minimum == G_MININT8 && pspec->maximum == G_MAXINT8) + desc = g_strdup (""); + else if (pspec->minimum == G_MININT8) + desc = g_strdup_printf ("<= %s", upper); + else if (pspec->maximum == G_MAXINT8) + desc = g_strdup_printf (">= %s", lower); + else + desc = g_strdup_printf ("[%s,%s]", lower, upper); + g_free (lower); + g_free (upper); + } + else if (G_IS_PARAM_SPEC_UCHAR (spec)) { + GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec); + + lower = describe_unsigned_constant (sizeof(guchar), pspec->minimum); + upper = describe_unsigned_constant (sizeof(guchar), pspec->maximum); + if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT8) + desc = g_strdup (""); + else if (pspec->minimum == 0) + desc = g_strdup_printf ("<= %s", upper); + else if (pspec->maximum == G_MAXUINT8) + desc = g_strdup_printf (">= %s", lower); + else + desc = g_strdup_printf ("[%s,%s]", lower, upper); + g_free (lower); + g_free (upper); + } + else if (G_IS_PARAM_SPEC_INT (spec)) { + GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec); + + lower = describe_signed_constant (sizeof(gint), pspec->minimum); + upper = describe_signed_constant (sizeof(gint), pspec->maximum); + if (pspec->minimum == G_MININT && pspec->maximum == G_MAXINT) + desc = g_strdup (""); + else if (pspec->minimum == G_MININT) + desc = g_strdup_printf ("<= %s", upper); + else if (pspec->maximum == G_MAXINT) + desc = g_strdup_printf (">= %s", lower); + else + desc = g_strdup_printf ("[%s,%s]", lower, upper); + g_free (lower); + g_free (upper); + } + else if (G_IS_PARAM_SPEC_UINT (spec)) { + GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec); + + lower = describe_unsigned_constant (sizeof(guint), pspec->minimum); + upper = describe_unsigned_constant (sizeof(guint), pspec->maximum); + if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT) + desc = g_strdup (""); + else if (pspec->minimum == 0) + desc = g_strdup_printf ("<= %s", upper); + else if (pspec->maximum == G_MAXUINT) + desc = g_strdup_printf (">= %s", lower); + else + desc = g_strdup_printf ("[%s,%s]", lower, upper); + g_free (lower); + g_free (upper); + } + else if (G_IS_PARAM_SPEC_LONG (spec)) { + GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec); + + lower = describe_signed_constant (sizeof(glong), pspec->minimum); + upper = describe_signed_constant (sizeof(glong), pspec->maximum); + if (pspec->minimum == G_MINLONG && pspec->maximum == G_MAXLONG) + desc = g_strdup (""); + else if (pspec->minimum == G_MINLONG) + desc = g_strdup_printf ("<= %s", upper); + else if (pspec->maximum == G_MAXLONG) + desc = g_strdup_printf (">= %s", lower); + else + desc = g_strdup_printf ("[%s,%s]", lower, upper); + g_free (lower); + g_free (upper); + } + else if (G_IS_PARAM_SPEC_ULONG (spec)) { + GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec); + + lower = describe_unsigned_constant (sizeof(gulong), pspec->minimum); + upper = describe_unsigned_constant (sizeof(gulong), pspec->maximum); + if (pspec->minimum == 0 && pspec->maximum == G_MAXULONG) + desc = g_strdup (""); + else if (pspec->minimum == 0) + desc = g_strdup_printf ("<= %s", upper); + else if (pspec->maximum == G_MAXULONG) + desc = g_strdup_printf (">= %s", lower); + else + desc = g_strdup_printf ("[%s,%s]", lower, upper); + g_free (lower); + g_free (upper); + } + else if (G_IS_PARAM_SPEC_INT64 (spec)) { + GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec); + + lower = describe_signed_constant (sizeof(gint64), pspec->minimum); + upper = describe_signed_constant (sizeof(gint64), pspec->maximum); + if (pspec->minimum == G_MININT64 && pspec->maximum == G_MAXINT64) + desc = g_strdup (""); + else if (pspec->minimum == G_MININT64) + desc = g_strdup_printf ("<= %s", upper); + else if (pspec->maximum == G_MAXINT64) + desc = g_strdup_printf (">= %s", lower); + else + desc = g_strdup_printf ("[%s,%s]", lower, upper); + g_free (lower); + g_free (upper); + } + else if (G_IS_PARAM_SPEC_UINT64 (spec)) { + GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec); + + lower = describe_unsigned_constant (sizeof(guint64), pspec->minimum); + upper = describe_unsigned_constant (sizeof(guint64), pspec->maximum); + if (pspec->minimum == 0 && pspec->maximum == G_MAXUINT64) + desc = g_strdup (""); + else if (pspec->minimum == 0) + desc = g_strdup_printf ("<= %s", upper); + else if (pspec->maximum == G_MAXUINT64) + desc = g_strdup_printf (">= %s", lower); + else + desc = g_strdup_printf ("[%s,%s]", lower, upper); + g_free (lower); + g_free (upper); + } + else if (G_IS_PARAM_SPEC_FLOAT (spec)) { + GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec); + + lower = describe_double_constant (pspec->minimum); + upper = describe_double_constant (pspec->maximum); + if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXFLOAT)) { + if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT)) + desc = g_strdup (""); + else + desc = g_strdup_printf ("<= %s", upper); + } + else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXFLOAT)) + desc = g_strdup_printf (">= %s", lower); + else + desc = g_strdup_printf ("[%s,%s]", lower, upper); + g_free (lower); + g_free (upper); + } + else if (G_IS_PARAM_SPEC_DOUBLE (spec)) { + GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec); + + lower = describe_double_constant (pspec->minimum); + upper = describe_double_constant (pspec->maximum); + if (GTKDOC_COMPARE_FLOAT (pspec->minimum, -G_MAXDOUBLE)) { + if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE)) + desc = g_strdup (""); + else + desc = g_strdup_printf ("<= %s", upper); + } + else if (GTKDOC_COMPARE_FLOAT (pspec->maximum, G_MAXDOUBLE)) + desc = g_strdup_printf (">= %s", lower); + else + desc = g_strdup_printf ("[%s,%s]", lower, upper); + g_free (lower); + g_free (upper); + } +#if GLIB_CHECK_VERSION (2, 12, 0) + else if (G_IS_PARAM_SPEC_GTYPE (spec)) { + GParamSpecGType *pspec = G_PARAM_SPEC_GTYPE (spec); + gboolean is_pointer; + + desc = g_strdup (get_type_name (pspec->is_a_type, &is_pointer)); + } +#endif +#if GLIB_CHECK_VERSION (2, 25, 9) + else if (G_IS_PARAM_SPEC_VARIANT (spec)) { + GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec); + gchar *variant_type; + + variant_type = g_variant_type_dup_string (pspec->type); + desc = g_strdup_printf ("GVariant<%s>", variant_type); + g_free (variant_type); + } +#endif + else { + desc = g_strdup (""); + } + + return desc; +} + +static gchar* +describe_default (GParamSpec *spec) +{ + gchar *desc; + + if (G_IS_PARAM_SPEC_CHAR (spec)) { + GParamSpecChar *pspec = G_PARAM_SPEC_CHAR (spec); + + desc = g_strdup_printf ("%d", pspec->default_value); + } + else if (G_IS_PARAM_SPEC_UCHAR (spec)) { + GParamSpecUChar *pspec = G_PARAM_SPEC_UCHAR (spec); + + desc = g_strdup_printf ("%u", pspec->default_value); + } + else if (G_IS_PARAM_SPEC_BOOLEAN (spec)) { + GParamSpecBoolean *pspec = G_PARAM_SPEC_BOOLEAN (spec); + + desc = g_strdup_printf ("%s", pspec->default_value ? "TRUE" : "FALSE"); + } + else if (G_IS_PARAM_SPEC_INT (spec)) { + GParamSpecInt *pspec = G_PARAM_SPEC_INT (spec); + + desc = g_strdup_printf ("%d", pspec->default_value); + } + else if (G_IS_PARAM_SPEC_UINT (spec)) { + GParamSpecUInt *pspec = G_PARAM_SPEC_UINT (spec); + + desc = g_strdup_printf ("%u", pspec->default_value); + } + else if (G_IS_PARAM_SPEC_LONG (spec)) { + GParamSpecLong *pspec = G_PARAM_SPEC_LONG (spec); + + desc = g_strdup_printf ("%ld", pspec->default_value); + } + else if (G_IS_PARAM_SPEC_LONG (spec)) { + GParamSpecULong *pspec = G_PARAM_SPEC_ULONG (spec); + + desc = g_strdup_printf ("%lu", pspec->default_value); + } + else if (G_IS_PARAM_SPEC_INT64 (spec)) { + GParamSpecInt64 *pspec = G_PARAM_SPEC_INT64 (spec); + + desc = g_strdup_printf ("%" G_GINT64_FORMAT, pspec->default_value); + } + else if (G_IS_PARAM_SPEC_UINT64 (spec)) + { + GParamSpecUInt64 *pspec = G_PARAM_SPEC_UINT64 (spec); + + desc = g_strdup_printf ("%" G_GUINT64_FORMAT, pspec->default_value); + } + else if (G_IS_PARAM_SPEC_UNICHAR (spec)) { + GParamSpecUnichar *pspec = G_PARAM_SPEC_UNICHAR (spec); + + if (g_unichar_isprint (pspec->default_value)) + desc = g_strdup_printf ("'%c'", pspec->default_value); + else + desc = g_strdup_printf ("%u", pspec->default_value); + } + else if (G_IS_PARAM_SPEC_ENUM (spec)) { + GParamSpecEnum *pspec = G_PARAM_SPEC_ENUM (spec); + + GEnumValue *value = g_enum_get_value (pspec->enum_class, pspec->default_value); + if (value) + desc = g_strdup_printf ("%s", value->value_name); + else + desc = g_strdup_printf ("%d", pspec->default_value); + } + else if (G_IS_PARAM_SPEC_FLAGS (spec)) { + GParamSpecFlags *pspec = G_PARAM_SPEC_FLAGS (spec); + guint default_value; + GString *acc; + + default_value = pspec->default_value; + acc = g_string_new (""); + + while (default_value) { + GFlagsValue *value = g_flags_get_first_value (pspec->flags_class, default_value); + + if (!value) + break; + + if (acc->len > 0) + g_string_append (acc, " | "); + g_string_append (acc, value->value_name); + + default_value &= ~value->value; + } + + if (default_value == 0) + desc = g_string_free (acc, FALSE); + else { + desc = g_strdup_printf ("%d", pspec->default_value); + g_string_free (acc, TRUE); + } + } + else if (G_IS_PARAM_SPEC_FLOAT (spec)) { + GParamSpecFloat *pspec = G_PARAM_SPEC_FLOAT (spec); + + /* make sure floats are output with a decimal dot irrespective of + * current locale. Use formatd since we want human-readable numbers + * and do not need the exact same bit representation when deserialising */ + desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE); + g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g", + pspec->default_value); + } + else if (G_IS_PARAM_SPEC_DOUBLE (spec)) { + GParamSpecDouble *pspec = G_PARAM_SPEC_DOUBLE (spec); + + /* make sure floats are output with a decimal dot irrespective of + * current locale. Use formatd since we want human-readable numbers + * and do not need the exact same bit representation when deserialising */ + desc = g_malloc0 (G_ASCII_DTOSTR_BUF_SIZE); + g_ascii_formatd (desc, G_ASCII_DTOSTR_BUF_SIZE, "%g", + pspec->default_value); + } + else if (G_IS_PARAM_SPEC_STRING (spec)) { + GParamSpecString *pspec = G_PARAM_SPEC_STRING (spec); + + if (pspec->default_value) { + gchar *esc = g_strescape (pspec->default_value, NULL); + desc = g_strdup_printf ("\\"%s\\"", esc); + g_free (esc); + } + else + desc = g_strdup_printf ("NULL"); + } +#if GLIB_CHECK_VERSION (2, 25, 9) + else if (G_IS_PARAM_SPEC_VARIANT (spec)) { + GParamSpecVariant *pspec = G_PARAM_SPEC_VARIANT (spec); + + if (pspec->default_value) + desc = g_variant_print (pspec->default_value, TRUE); + else + desc = g_strdup ("NULL"); + } +#endif + else { + desc = g_strdup (""); + } + + return desc; +} + + +static void +output_object_args (FILE *fp, GType object_type) +{ + gpointer class; + const gchar *object_class_name; + guint arg; + gchar flags[16], *pos; + GParamSpec **properties; + guint n_properties; + gboolean child_prop; + gboolean style_prop; + gboolean is_pointer; + const gchar *type_name; + gchar *type_desc; + gchar *default_value; + + if (G_TYPE_IS_OBJECT (object_type)) { + class = g_type_class_peek (object_type); + if (!class) + return; + + properties = g_object_class_list_properties (class, &n_properties); + } +#if GLIB_MAJOR_VERSION > 2 || (GLIB_MAJOR_VERSION == 2 && GLIB_MINOR_VERSION >= 3) + else if (G_TYPE_IS_INTERFACE (object_type)) { + class = g_type_default_interface_ref (object_type); + + if (!class) + return; + + properties = g_object_interface_list_properties (class, &n_properties); + } +#endif + else + return; + + object_class_name = g_type_name (object_type); + + child_prop = FALSE; + style_prop = FALSE; + + while (TRUE) { + qsort (properties, n_properties, sizeof (GParamSpec *), compare_param_specs); + for (arg = 0; arg < n_properties; arg++) { + GParamSpec *spec = properties[arg]; + const gchar *nick, *blurb, *dot; + + if (spec->owner_type != object_type) + continue; + + pos = flags; + /* We use one-character flags for simplicity. */ + if (child_prop && !style_prop) + *pos++ = 'c'; + if (style_prop) + *pos++ = 's'; + if (spec->flags & G_PARAM_READABLE) + *pos++ = 'r'; + if (spec->flags & G_PARAM_WRITABLE) + *pos++ = 'w'; + if (spec->flags & G_PARAM_CONSTRUCT) + *pos++ = 'x'; + if (spec->flags & G_PARAM_CONSTRUCT_ONLY) + *pos++ = 'X'; + *pos = 0; + + nick = g_param_spec_get_nick (spec); + blurb = g_param_spec_get_blurb (spec); + + dot = ""; + if (blurb) { + int str_len = strlen (blurb); + if (str_len > 0 && blurb[str_len - 1] != '.') + dot = "."; + } + + type_desc = describe_type (spec); + default_value = describe_default (spec); + type_name = get_type_name (spec->value_type, &is_pointer); + fprintf (fp, "\\n" + "%s::%s\\n" + "%s%s\\n" + "%s\\n" + "%s\\n" + "%s\\n" + "%s%s\\n" + "%s\\n" + "\\n\\n", + object_class_name, g_param_spec_get_name (spec), type_name, + is_pointer ? "*" : "", type_desc, flags, nick ? nick : "(null)", + blurb ? blurb : "(null)", dot, default_value); + g_free (type_desc); + g_free (default_value); + } + + g_free (properties); + +#ifdef GTK_IS_CONTAINER_CLASS + if (!child_prop && GTK_IS_CONTAINER_CLASS (class)) { + properties = gtk_container_class_list_child_properties (class, &n_properties); + child_prop = TRUE; + continue; + } +#endif + +#ifdef GTK_IS_CELL_AREA_CLASS + if (!child_prop && GTK_IS_CELL_AREA_CLASS (class)) { + properties = gtk_cell_area_class_list_cell_properties (class, &n_properties); + child_prop = TRUE; + continue; + } +#endif + +#ifdef GTK_IS_WIDGET_CLASS +#if GTK_CHECK_VERSION(2,1,0) && !GTK_CHECK_VERSION(3,89,2) + if (!style_prop && GTK_IS_WIDGET_CLASS (class)) { + properties = gtk_widget_class_list_style_properties (GTK_WIDGET_CLASS (class), &n_properties); + style_prop = TRUE; + continue; + } +#endif +#endif + +""" + +MAIN_CODE_END = """ + break; + } +} +""" + + +def run(options): + + c_file = options.module + '-scan.c' + output = open(c_file, 'w') + + base_filename = os.path.join(options.output_dir, options.module) + old_signals_filename = base_filename + '.signals' + new_signals_filename = base_filename + '.signals.new' + old_hierarchy_filename = base_filename + '.hierarchy' + new_hierarchy_filename = base_filename + '.hierarchy.new' + old_interfaces_filename = base_filename + '.interfaces' + new_interfaces_filename = base_filename + '.interfaces.new' + old_prerequisites_filename = base_filename + '.prerequisites' + new_prerequisites_filename = base_filename + '.prerequisites.new' + old_args_filename = base_filename + '.args' + new_args_filename = base_filename + '.args.new' + + # generate a C program to scan the types + + includes = "" + forward_decls = "" + get_types = "" + ntypes = 1 + + for line in open(options.types): + if line.startswith('#include'): + includes += line + elif line.startswith('%') or line.strip() == '': + continue + else: + line = line.strip() + get_types += ' object_types[i++] = ' + line + ' ();\n' + forward_decls += 'extern GType ' + line + ' (void);\n' + ntypes += 1 + + output.write(COMMON_INCLUDES) + + if includes: + output.write(includes) + else: + output.write(forward_decls) + + if options.query_child_properties: + output.write(QUERY_CHILD_PROPS_PROTOTYPE % options.query_child_properties) + + # substitute local vars in the template + type_init_func = options.type_init_func + output.write(string.Template(MAIN_CODE).substitute(locals())) + + if options.query_child_properties: + output.write(QUERY_CHILD_PROPS_CODE % options.query_child_properties) + + output.write(MAIN_CODE_END) + + output.close() + + # Compile and run our file + if 'libtool' in options.cc: + o_file = options.module + '-scan.lo' + else: + o_file = options.module + '-scan.o' + + x_file = options.module + '-scan' + config.exeext + + stdout = "" + if not options.verbose: + stdout = ">/dev/null" + + logging.debug('Intermediate scanner files: %s, %s, %s', c_file, o_file, x_file) + + # Compiling scanner + command = '%s %s %s -c -o %s %s' % (options.cc, stdout, options.cflags, o_file, c_file) + res = subprocess.check_call(command, shell=True) + if res > 0: + logging.warning('Compilation of scanner failed: %d', res) + return res + + # Linking scanner + command = '%s %s %s %s -o %s' % (options.ld, stdout, o_file, options.ldflags, x_file) + res = subprocess.check_call(command, shell=True) + if res > 0: + logging.warning('Linking of scanner failed: %d', res) + return res + + # Running scanner + command = '%s ./%s' % (options.run, x_file) + res = subprocess.check_call(command, shell=True) + if res > 0: + logging.warning('Running scanner failed: %d', res) + return res + + logging.debug('Scan complete') + if 'GTK_DOC_KEEP_INTERMEDIATE' not in os.environ: + os.unlink(c_file) + os.unlink(o_file) + os.unlink(x_file) + if 'libtool' in options.cc: + o_file = options.module + '-scan.o' + if os.path.exists(o_file): + os.unlink(o_file) + else: + logging.debug('Keeping generated sources for analysis: %s, %s, %s', + c_file, o_file, x_file) + + common.UpdateFileIfChanged(old_signals_filename, new_signals_filename, False) + common.UpdateFileIfChanged(old_hierarchy_filename, new_hierarchy_filename, False) + common.UpdateFileIfChanged(old_interfaces_filename, new_interfaces_filename, False) + common.UpdateFileIfChanged(old_prerequisites_filename, new_prerequisites_filename, False) + common.UpdateFileIfChanged(old_args_filename, new_args_filename, False) + + return 0 diff --git a/gtkdocize.in b/gtkdocize.in index 50a041d..a688fc3 100644 --- a/gtkdocize.in +++ b/gtkdocize.in @@ -115,16 +115,10 @@ while test $# -gt 0; do done case "$flavour" in - legacy-flat*) + legacy-flat|no-tmpl-flat) makefile=gtk-doc.flat.make ;; - legacy*) - ;; - no-tmpl-flat*) - makefile=gtk-doc.notmpl-flat.make - ;; - no-tmpl*) - makefile=gtk-doc.notmpl.make + legacy|no-tmpl) ;; *) echo "$progname: invalid value for --flavour" 1>&2 diff --git a/help/Makefile.in b/help/Makefile.in index fb35e03..a177b84 100644 --- a/help/Makefile.in +++ b/help/Makefile.in @@ -237,12 +237,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ diff --git a/help/manual/C/index.docbook b/help/manual/C/index.docbook index ed88747..e27fabf 100644 --- a/help/manual/C/index.docbook +++ b/help/manual/C/index.docbook @@ -80,6 +80,12 @@ + + 1.26 + 11 Aug 2017 + ss + port all tools from perl/bash to python + 1.25 21 March 2016 @@ -205,7 +211,7 @@ - GTK-Doc consists of a number of perl scripts, each performing a different step + GTK-Doc consists of a number of python scripts, each performing a different step in the process. @@ -255,27 +261,6 @@ - - - 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.) - - - - 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). - - - - Generating the XML and HTML/PDF. @@ -293,7 +278,7 @@ document called <package>.pdf. - Files in xml/ and + Files in xml/ and html/ directories are always overwritten. One should never edit them directly. @@ -323,7 +308,7 @@ Requirements - Perl v5 - the main scripts are in Perl. + python 2/3 - the main scripts are written in python. xsltproc - the xslt processor from libxslt @@ -333,9 +318,6 @@ docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl - - Python - optional - for gtkdoc-depscan - One of source-highlight, highlight or vim - optional - used for syntax highlighting of examples @@ -468,7 +450,7 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) Furthermore it is recommended that you have the following line inside - you configure.ac script. + your configure.ac script. This allows gtkdocize to automatically copy the macro definition for GTK_DOC_CHECK to your project. @@ -491,12 +473,12 @@ AC_CONFIG_MACRO_DIR(m4) Integration with automake - First copy the Makefile.am from the + 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. + 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. @@ -705,7 +687,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html The scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + hint GTK-Doc to skip over them. GTK-Doc comment block Limitations Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not + #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations. @@ -856,7 +838,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + XML tags inside doc-comments by putting (or ) in the variable MKDB_OPTIONS inside Makefile.am. @@ -957,7 +939,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + name given here should match the <FILE> tag in the <package>-sections.txt file. @@ -1187,7 +1169,7 @@ foo_get_bar(Foo *foo) Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list - of the supported tags can be found on + of the supported tags can be found on the wiki. @@ -1405,6 +1387,111 @@ typedef enum { + + + Inline program documentation + + You can document programs and their commandline interface using inline + documentation. + + + + Tags + + PROGRAM + + + + Defines the start of a program documentation. + + + + + + @short_description: + + + Defines a short description of the program. (Optional) + + + + + + @synopsis: + + + Defines the arguments, or list of arguments that the program can take. + (Optional) + + + + + + @see_also: + + + See Also manual page section. (Optional) + + + + + + @arg: + + + Argument(s) passed to the program and their description. (Optional) + + + + + + Description: + + + A longer description of the program. + + + + + + Returns: + + + Specificy what value(s) the program returns. (Optional) + + + + + + + + Example of program documentation. + Program documentation block + + + + + + Useful DocBook tags @@ -1667,17 +1754,17 @@ gtk_arrow_get_type In addition a few option elements are created in commented form. You can review these and enable them as you like. - + Optional part in the master document - --> + --> ]]> - + Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will @@ -1712,7 +1799,7 @@ gtk_arrow_get_type Blank lines are ignored and lines starting with a '#' are treated as comment lines. - + While the tags make the file look like xml, it is not. Please do not @@ -1855,15 +1942,15 @@ meep_app_get_type GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizing the documentation - + 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. - + GTK-Doc 1.9 @@ -1871,7 +1958,7 @@ meep_app_get_type When using xml instead of sgml, one can actually name the master document <package>-docs.xml. - + This version supports in Makefile.am. When this is enabled, the @@ -1879,21 +1966,21 @@ meep_app_get_type can be removed from the vcs. This only works nicely for projects that have a very regular structure (e.g. each .{c,h} pair will create new section). If one organize a project close to that updating a manually - maintained section file can be as simple as running + maintained section file can be as simple as running meld <package>-decl-list.txt <package>-sections.txt. - + 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 you source control system and haven't yet switched, just + checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. - + GTK-Doc 1.10 @@ -1946,7 +2033,7 @@ endif 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 any example that shows how the entity file is included + number. Below is an example that shows how the entity file is included and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. diff --git a/help/manual/Makefile.am b/help/manual/Makefile.am index 1c8fcfa..b56fa4d 100644 --- a/help/manual/Makefile.am +++ b/help/manual/Makefile.am @@ -8,7 +8,7 @@ HELP_FILES = \ index.docbook \ fdl-appendix.xml -HELP_LINGUAS = bn_IN de el en_GB es fr gl gu pt_BR sl sv ta te zh_CN +HELP_LINGUAS = bn_IN cs de el en_GB es fr gl gu pt_BR sl sv ta te zh_CN CLEANFILES = $(_HELP_LC_FILES) $(_HELP_LC_STAMPS) $(_HELP_MOFILES) diff --git a/help/manual/Makefile.in b/help/manual/Makefile.in index 67fc6df..96ec312 100644 --- a/help/manual/Makefile.in +++ b/help/manual/Makefile.in @@ -177,12 +177,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ @@ -264,7 +264,7 @@ HELP_FILES = \ index.docbook \ fdl-appendix.xml -HELP_LINGUAS = bn_IN de el en_GB es fr gl gu pt_BR sl sv ta te zh_CN +HELP_LINGUAS = bn_IN cs de el en_GB es fr gl gu pt_BR sl sv ta te zh_CN CLEANFILES = $(_HELP_LC_FILES) $(_HELP_LC_STAMPS) $(_HELP_MOFILES) GITIGNOREFILES = ??_??/$(HELP_ID).xml ??/$(HELP_ID).xml all: all-am diff --git a/help/manual/bn_IN/index.docbook b/help/manual/bn_IN/index.docbook index 8955886..417a859 100644 --- a/help/manual/bn_IN/index.docbook +++ b/help/manual/bn_IN/index.docbook @@ -81,10 +81,16 @@ - 1.24.1 - 30 May 2015 + 1.25.1 + 21 March 2016 + ss + development version + + + 1.25 + 21 March 2016 ss - development version + bug fixes, test cleanups 1.24 @@ -243,27 +249,6 @@ - - - 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.) - - - - 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). - - - - Generating the XML and HTML/PDF. @@ -281,7 +266,7 @@ document called <package>.pdf. - Files in xml/ and + Files in xml/ and html/ directories are always overwritten. One should never edit them directly. @@ -446,7 +431,7 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) Furthermore it is recommended that you have the following line inside - you configure.ac script. + your configure.ac script. This allows gtkdocize to automatically copy the macro definition for GTK_DOC_CHECK to your project. @@ -469,12 +454,12 @@ AC_CONFIG_MACRO_DIR(m4) automake সহযোগে একত্রিত করার প্রণালী - First copy the Makefile.am from the + 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. + 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. @@ -683,7 +668,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html The scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + hint GTK-Doc to skip over them. GTK-Doc comment block Limitations Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not + #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations. @@ -828,7 +813,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + XML tags inside doc-comments by putting (or ) in the variable MKDB_OPTIONS inside Makefile.am. @@ -929,7 +914,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + name given here should match the <FILE> tag in the <package>-sections.txt file. @@ -1151,7 +1136,7 @@ foo_get_bar(Foo *foo) Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list - of the supported tags can be found on + of the supported tags can be found on the wiki. @@ -1367,6 +1352,111 @@ typedef enum { + + + Inline program documentation + + You can document programs and their commandline interface using inline + documentation. + + + + Tags + + PROGRAM + + + + Defines the start of a program documentation. + + + + + + @short_description: + + + Defines a short description of the program. (Optional) + + + + + + @synopsis: + + + Defines the arguments, or list of arguments that the program can take. + (Optional) + + + + + + @see_also: + + + See Also manual page section. (Optional) + + + + + + @arg: + + + Argument(s) passed to the program and their description. (Optional) + + + + + + Description: + + + A longer description of the program. + + + + + + প্রাপ্ত মান: + + + Specificy what value(s) the program returns. (Optional) + + + + + + + + Example of program documentation. + Program documentation block + + + + + + সুবিধাজনক DocBook ট্যাগ @@ -1626,17 +1716,17 @@ gtk_arrow_get_type In addition a few option elements are created in commented form. You can review these and enable them as you like. - + Optional part in the master document - --> + --> ]]> - + Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will @@ -1671,7 +1761,7 @@ gtk_arrow_get_type Blank lines are ignored and lines starting with a '#' are treated as comment lines. - + While the tags make the file look like xml, it is not. Please do not @@ -1814,15 +1904,15 @@ meep_app_get_type GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizing the documentation - + 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. - + GTK-Doc 1.9 @@ -1830,7 +1920,7 @@ meep_app_get_type When using xml instead of sgml, one can actually name the master document <package>-docs.xml. - + This version supports in Makefile.am. When this is enabled, the @@ -1838,21 +1928,21 @@ meep_app_get_type can be removed from the vcs. This only works nicely for projects that have a very regular structure (e.g. each .{c,h} pair will create new section). If one organize a project close to that updating a manually - maintained section file can be as simple as running + maintained section file can be as simple as running meld <package>-decl-list.txt <package>-sections.txt. - + 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 you source control system and haven't yet switched, just + checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. - + GTK-Doc 1.10 @@ -1905,7 +1995,7 @@ endif 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 any example that shows how the entity file is included + number. Below is an example that shows how the entity file is included and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. diff --git a/help/manual/cs/cs.po b/help/manual/cs/cs.po new file mode 100644 index 0000000..0f1bedd --- /dev/null +++ b/help/manual/cs/cs.po @@ -0,0 +1,5427 @@ +# Czech translation of gtk-doc. +# Copyright (C) 2009 gtk-doc's COPYRIGHT HOLDER +# This file is distributed under the same license as the gtk-doc package. +# Marek Černocký , 2009, 2015, 2016. +# +msgid "" +msgstr "" +"Project-Id-Version: gtk-doc master\n" +"POT-Creation-Date: 2016-09-06 04:43+0000\n" +"PO-Revision-Date: 2016-09-18 10:27+0200\n" +"Last-Translator: Marek Černocký \n" +"Language-Team: čeÅ¡tina \n" +"Language: cs\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;\n" +"X-Generator: Gtranslator 2.91.7\n" + +#. Put one translator per line, in the form NAME , YEAR1, YEAR2 +msgctxt "_" +msgid "translator-credits" +msgstr "Marek Černocký " + +#. (itstool) path: bookinfo/title +#: C/index.docbook:12 +msgid "GTK-Doc Manual" +msgstr "Příručka ke GTK-Doc" + +#. (itstool) path: bookinfo/edition +#: C/index.docbook:13 +msgid "1.24.1" +msgstr "1.24.1" + +#. (itstool) path: abstract/para +#: C/index.docbook:14 +msgid "User manual for developers with instructions of GTK-Doc usage." +msgstr "Uživatelská příručka pro vývojáře s instrukcemi k používání GTK-Doc." + +#. (itstool) path: authorgroup/author +#: C/index.docbook:16 +msgid "" +"Chris Lyttle " +"
chris@wilddev.net
" +msgstr "" +"Chris Lyttle " +"
chris@wilddev.net
" + +#. (itstool) path: authorgroup/author +#: C/index.docbook:25 +msgid "" +"Dan Mueth
" +"d-mueth@uchicago.edu
" +msgstr "" +"Dan Mueth " +"
d-mueth@uchicago.edu
" + +#. (itstool) path: authorgroup/author +#: C/index.docbook:34 +msgid "" +"Stefan Sauer (Kost) " +"
ensonic@users.sf.net
" +msgstr "" +"Stefan Sauer (Kost) " +"
ensonic@users.sf.net
" + +#. (itstool) path: publisher/publishername +#: C/index.docbook:45 +msgid "GTK-Doc project" +msgstr "Projekt GTK-Doc" + +#. (itstool) path: bookinfo/publisher +#: C/index.docbook:44 +msgid "" +"<_:publishername-1/>
gtk-doc-list@gnome.org
" +msgstr "" +"<_:publishername-1/>
gtk-doc-list@gnome.org
" + +#. (itstool) path: bookinfo/copyright +#: C/index.docbook:48 +msgid "2000, 2005 Dan Mueth and Chris Lyttle" +msgstr "2000, 2005 Dan Mueth and Chris Lyttle" + +#. (itstool) path: bookinfo/copyright +#: C/index.docbook:52 +msgid "2007-2015 Stefan Sauer (Kost)" +msgstr "2007-2015 Stefan Sauer (Kost)" + +#. (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, " +"Version 1.1 or any later version published by the Free Software Foundation " +"with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A " +"copy of the license is included." +msgstr "" +"Je povoleno kopírovat, šířit a/nebo upravovat tento dokument za podmínek " +"GNU Free Documentation License ve verzi 1.1 nebo v " +"jakékoli další verzi vydané nadací Free Software Foundation, s neměnnými " +"oddíly, bez textů předních desek a bez textů zadních desek. Kopie licence je " +"součástí." + +#. (itstool) path: legalnotice/para +#: C/index.docbook:73 +msgid "" +"Many of the names used by companies to distinguish their products and " +"services are claimed as trademarks. Where those names appear in any GNOME " +"documentation, and those trademarks are made aware to the members of the " +"GNOME Documentation Project, the names have been printed in caps or initial " +"caps." +msgstr "" +"Mnoho názvů použitých firmami k zviditelnění produktů nebo služeb jsou " +"ochranné známky. Na místech, kde jsou tyto názvy v dokumentaci použity a " +"členové Dokumentačního projektu GNOME jsou si vědomi skutečnosti, že se " +"jedná o ochrannou známku, je takovýto název psán velkými písmeny celý nebo s " +"velkým písmenem na začátku." + +#. (itstool) path: revhistory/revision +#: C/index.docbook:83 +msgid "" +"1.25.1 21 March 2016 ss development version" +msgstr "" +"1.25.1 21. březen 2016 " +"ss development version" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:89 +msgid "" +"1.25 21 March 2016 ss bug fixes, test cleanups" +msgstr "" +"1.25 21. březen 2016 ss opravy chyb, pročištění testů" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:95 +msgid "" +"1.24 29 May 2015 ss bug fix" +msgstr "" +"1.24 29. května 2015 ss oprava chyby" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:101 +msgid "" +"1.23 17 May 2015 ss bug fix" +msgstr "" +"1.23 17. květen 2015 ss oprava chyby" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:107 +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í" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:113 +msgid "" +"1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" +msgstr "" +"1.21 17. červenec 2014 " +"ss oprava chyb, odstranění " +"zastaralých věcí" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:119 +msgid "" +"1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" +msgstr "" +"1.20 16. únor 2014 ss opravy chyb, podpora značkovacího jazyka, " +"vylepšení stylů" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:125 +msgid "" +"1.19 05 Jun 2013 ss bug fixes" +msgstr "" +"1.19 05. červen 2013 ss opravy chyb" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:131 +msgid "" +"1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" +msgstr "" +"1.18 14. září 2011 ss opravy chyb, zrychlení, podpora značkovacího " +"jazyka" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:137 +msgid "" +"1.17 26 Feb 2011 sk urgent bug fix update" +msgstr "" +"1.17 26. únor 2011 sk aktualizace kvůli neodkladné opravě chyby" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:143 +msgid "" +"1.16 14 Jan 2011 sk bugfixes, layout improvements" +msgstr "" +"1.16 14. leden 2011 sk opravy chyb, vylepšení vzhledu" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:149 +msgid "" +"1.15 21 May 2010 sk bug and regression fixes" +msgstr "" +"1.15 21. květen 2010 sk opravy chyb a regresí" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:155 +msgid "" +"1.14 28 March 2010 sk bugfixes and performance improvements" +msgstr "" +"1.14 28. březen 2010 sk opravy chyb a vylepšení výkonu" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:161 +msgid "" +"1.13 18 December 2009 " +"sk broken tarball update" +msgstr "" +"1.13 18. prosinec 2009 " +"sk aktualizace poškozeného " +"balíčku" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:167 +msgid "" +"1.12 18 December 2009 " +"sk new tool features and " +"bugfixes" +msgstr "" +"1.12 18. prosinec 2009 " +"sk nové funkce nástroje a opravy " +"chyb" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:173 +msgid "" +"1.11 16 November 2008 " +"mal GNOME doc-utils migration" +msgstr "" +"1.11 16. listopad 2008 " +"mal přechod na doc-utils z " +"GNOME" + +#. (itstool) path: chapter/title +#: C/index.docbook:186 +msgid "Introduction" +msgstr "Úvod" + +#. (itstool) path: chapter/para +#: C/index.docbook:188 +msgid "" +"This chapter introduces GTK-Doc and gives an overview of what it is and how " +"it is used." +msgstr "" +"Tato kapitola je úvodem do GTK-Doc a podává přehled o tom, co to je a jak to " +"použít." + +#. (itstool) path: sect1/title +#: C/index.docbook:194 +msgid "What is GTK-Doc?" +msgstr "Co je to GTK-Doc?" + +#. (itstool) path: sect1/para +#: C/index.docbook:196 +msgid "" +"GTK-Doc is used to document C code. It is typically used to document the " +"public API of libraries, such as the GTK+ and GNOME libraries. But it can " +"also be used to document application code." +msgstr "" +"GTK-Doc se používá k dokumentaci kódu jazyka C. Typické použití je pro " +"dokumentaci veřejného API knihoven, jako jsou knihovny GTK+ a GNOME. Lze jej " +"ale použít i k dokumentaci aplikačního kódu." + +#. (itstool) path: sect1/title +#: C/index.docbook:204 +msgid "How Does GTK-Doc Work?" +msgstr "Jak GTK-Doc pracuje?" + +#. (itstool) path: sect1/para +#: C/index.docbook:206 +msgid "" +"GTK-Doc works by using documentation of functions placed inside the source " +"files in specially-formatted comment blocks, or documentation added to the " +"template files which GTK-Doc uses (though note that GTK-Doc will only " +"document functions that are declared in header files; it won't produce " +"output for static functions)." +msgstr "" +"GTK-Doc pracuje na základě dokumentace funkcí umístěné přímo v souborech se " +"zdrojovým kódem ve speciálně formátovaných komentářových blocích, nebo " +"dokumentace přidané do souborů šablon, které GTK-Doc používá (ačkoliv je " +"nutno poznamenat, že GTK-Doc dokumentuje pouze funkce, které jsou " +"deklarované v hlavičkových souborech; pro statické funkce žádný výstup " +"nevytváří)." + +#. (itstool) path: sect1/para +#: C/index.docbook:213 +msgid "" +"GTK-Doc consists of a number of perl scripts, each performing a different " +"step in the process." +msgstr "" +"GTK-Doc sestává z řady perlových skriptů, z nichž každý provádí jinou část " +"procesu." + +#. (itstool) path: sect1/para +#: C/index.docbook:218 +msgid "There are 5 main steps in the process:" +msgstr "Celý proces se skládá z pěti hlavních kroků:" + +#. (itstool) path: listitem/para +#: C/index.docbook:225 +msgid "" +"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)." +msgstr "" +"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)." + +#. (itstool) path: listitem/para +#: C/index.docbook:235 +msgid "" +"Gathering information about the code. " +"gtkdoc-scan scans the header files of the code " +"looking for declarations of functions, macros, enums, structs, and unions. " +"It creates the file <module>-decl-list.txt " +"containing a list of the declarations, placing them into sections according " +"to which header file they are in. On the first run this file is copied to " +"<module>-sections.txt. The author can rearrange " +"the sections, and the order of the declarations within them, to produce the " +"final desired order. The second file it generates is <" +"module>-decl.txt. This file contains the full declarations " +"found by the scanner. If for some reason one would like some symbols to show " +"up in the docs, where the full declaration cannot be found by the scanner or " +"the declaration should appear differently, one can place entities similar to " +"the ones in <module>-decl.txt into <" +"module>-overrides.txt." +msgstr "" +"Shromáždění informací o kódu. gtkdoc-scan projde hlavičkové soubory kódu a vyhledá při tom deklarace " +"funkcí, maker, výčtů, struktur a sjednocení. Tím se vytvoří soubor " +"<module>-decl-list.txt obsahující seznam " +"deklarací, které jsou rozdělené do oddílů podle hlavičkového souboru, ze " +"kterého pochází. Při prvním spuštění se tento soubor zkopíruje do " +"<module>-sections.txt. Autor může změnit " +"uspořádání oddílů a jejich pořadí v rámci deklarací tak, jak to požaduje ve " +"výsledku. Druhý soubor, který se vytvoří, je <module>-decl." +"txt. Tento soubor obsahuje úplné deklarace nalezené při " +"procházení. Pokud byste z nějakého důvodu chtěli v dokumentaci zahrnout " +"symbol, který při procházení nebyl nalezen, nebo jeho deklarace vypadá " +"jinak, můžete jej umístit podobně jako v <module>-decl.txt do <module>-overrides.txt." + +#. (itstool) path: listitem/para +#: C/index.docbook:252 +msgid "" +"gtkdoc-scangobj can also be used to dynamically " +"query a library about any GObject subclasses it exports. It saves " +"information about each object's position in the class hierarchy and about " +"any GObject properties and signals it provides." +msgstr "" +"Dá se také použít gtkdoc-scanobj k dynamickým " +"dotazům do knihoven na podtřídy objektu GObject, které exportují. Tím se " +"uloží informace o pozici každého objektu v hierarchii tříd a o argumentech a " +"signálech objektu GObject, které poskytují." + +#. (itstool) path: listitem/para +#: C/index.docbook:258 +msgid "" +"gtkdoc-scanobj should not be used anymore. It was " +"needed in the past when GObject was still GtkObject inside gtk+." +msgstr "" +"gtkdoc-scanobj by se ale již používat nemělo. " +"Bylo zapotřebí v minulosti, kdy byl GObject ještě GtkObject v rámci gtk+." + +#. (itstool) path: listitem/para +#: C/index.docbook:265 +msgid "" +"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 "" +"Generování souborů „šablon“. gtkdoc-" +"mktmpl vytvoří v podsložce tmpl/" +" řadu souborů, za použití informací shromážděných v prvním kroku. " +"(Poznamenejme, že může být spouštěn opakovaně. Tím se zajistí, že se žádná " +"dokumentace neztratí.)" + +#. (itstool) path: note/para +#: C/index.docbook:274 +msgid "" +"Since GTK-Doc 1.9 the templates can be avoided. We encourage people to keep " +"documentation in the code. 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 "" +"Od verze gtk-doc 1.9 můžete šablony vynechat. Doporučujeme lidem, aby " +"udržovali dokumentaci v kódu. gtkdocize nyní " +"podporuje přepínač , který způsobí, že " +"makefile úplně přeskočí použití tmpl. Pokud jste nikdy ručně neměnili " +"soubory v tmpl, tak tuto složku prosím odstraňte." + +#. (itstool) path: listitem/para +#: C/index.docbook:286 +msgid "" +"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." +msgstr "" +"Generování XML a HTML/PDF. gtkdoc-mkdb přemění soubory šablon na soubory XML v podsložce xml/. Pokud zdrojový kód obsahuje dokumentaci " +"funkcí za použití speciálních komentářových bloků, tak zde se sloučí. V " +"případě, že není použitý žádný soubor šablon, načte se dokumentace pouze ze " +"zdrojového kódu a introspektivních dat." + +#. (itstool) path: listitem/para +#: C/index.docbook:295 +msgid "" +"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 převádí soubory XML na soubory HTML " +"v podsložce html/. Obdobně " +"gtkdoc-mkpdf převádí soubory XML na dokument PDF " +"nazvaný <balíček>.pdf." + +#. (itstool) path: listitem/para +#: C/index.docbook:301 +msgid "" +"Files in xml/ and html/ directories are always overwritten. One " +"should never edit them directly." +msgstr "" +"Soubory ve složkách xml/ a " +"html/ jsou vždy přepsány. Nikdy by " +"neměly být upravovány přímo." + +#. (itstool) path: listitem/para +#: C/index.docbook:309 +msgid "" +"Fixing up cross-references between documents. After " +"installing the HTML files, gtkdoc-fixxref can be " +"run to fix up any cross-references between separate documents. For example, " +"the GTK+ documentation contains many cross-references to types documented in " +"the GLib manual. When creating the source tarball for distribution, " +"gtkdoc-rebase turns all external links into web-" +"links. When installing distributed (pregenerated) docs the same application " +"will try to turn links back to local links (where those docs are installed)." +msgstr "" +"Opravy křížových odkazů mezi dokumenty. Po " +"nainstalování souborů HTML můžete spustit gtkdoc-fixxref, aby se opravily křížové odkazy mezi samostanými dokumenty. " +"Například dokumentace GTK+ obsahuje křížové odkazy na typy zdokumentované v " +"příručce GLib. Když vytváříte zdrojový balíček pro distribuci, " +"gtkdoc-rebase předělá všechny externí odkazy na " +"webové odkazy. Když se distribuovaná (předgenerovaná) dokumentace instaluje, " +"pokusí se tatáž aplikace předělat odkazy zpátky na místní odkazy (na " +"dokumenty, které jsou nainstalované)." + +#. (itstool) path: sect1/title +#: C/index.docbook:327 +msgid "Getting GTK-Doc" +msgstr "Jak získat GTK-Doc?" + +#. (itstool) path: sect2/title +#: C/index.docbook:330 +msgid "Requirements" +msgstr "Požadavky" + +#. (itstool) path: sect2/para +#: C/index.docbook:331 +msgid "Perl v5 - the main scripts are in Perl." +msgstr "Perl v5 – hlavní skripty jsou v jazyce Perl." + +#. (itstool) path: sect2/para +#: C/index.docbook:334 +msgid "" +"xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" +msgstr "" +"xsltproc – procesor xslt z knihovny libxslt xmlsoft.org/XSLT/" + +#. (itstool) path: sect2/para +#: C/index.docbook:338 +msgid "" +"docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" +msgstr "" +"docbook-xsl – stylopisy XSL pro docbook sourceforge.net/projects/docbook/files/docbook-xsl" + +#. (itstool) path: sect2/para +#: C/index.docbook:342 +msgid "Python - optional - for gtkdoc-depscan" +msgstr "Python – pro gtkdoc-depscan (volitelné)" + +#. (itstool) path: sect2/para +#: C/index.docbook:345 +msgid "" +"One of source-highlight, highlight " +"or vim - optional - used for syntax highlighting of " +"examples" +msgstr "" +"Něco z source-highlight, highlight " +"nebo vim – (volitelné) používá se pro zvýraznění " +"syntaxe u příkladů" + +#. (itstool) path: sect1/title +#: C/index.docbook:353 +msgid "About GTK-Doc" +msgstr "O aplikaci GTK-Doc" + +#. (itstool) path: sect1/para +#: C/index.docbook:355 C/index.docbook:369 +msgid "(FIXME)" +msgstr "(DOPLNIT)" + +#. (itstool) path: sect1/para +#: C/index.docbook:359 +msgid "" +"(History, authors, web pages, mailing list, license, future plans, " +"comparison with other similar systems.)" +msgstr "" +"(Historie, autoři, webové stránky, poštovní konference, licence, plány do " +"budoucna, srovnání s ostatními podobnými systémy.)" + +#. (itstool) path: sect1/title +#: C/index.docbook:367 +msgid "About this Manual" +msgstr "O této příručce" + +#. (itstool) path: sect1/para +#: C/index.docbook:373 +msgid "(who it is meant for, where you can get it, license)" +msgstr "(k čemu je určená, kde ji můžete získat, licence)" + +#. (itstool) path: chapter/title +#: C/index.docbook:382 +msgid "Setting up your project" +msgstr "Nastavení vašeho projektu" + +#. (itstool) path: chapter/para +#: C/index.docbook:384 +msgid "" +"The next sections describe what steps to perform to integrate GTK-Doc into " +"your project. Theses sections assume we work on a project called 'meep'. " +"This project contains a library called 'libmeep' and an end-user app called " +"'meeper'. We also assume you will be using autoconf and automake. In " +"addition section plain makefiles or other " +"build systems will describe the basics needed to work in a different " +"build setup." +msgstr "" +"Následující oddíl popisuje kroky, které musíte provést, abyste integrovali " +"GTK-Doc do svého projektu. Tento oddíl předpokládá, že pracujeme na projektu " +"nazvaném „meep“. Tento projekt obsahuje knihovnu nazvanou „libmeep“ a " +"aplikaci pro koncového uživatele nazvanou „meeper“. Rovněž předpokládá, že " +"používáte autoconf a automake. V oddílu prosté soubory Makefile nebo jiné sestavovací systémy budou " +"popsány základní požadavky pro fungování s jinými postupy sestavování." + +#. (itstool) path: sect1/title +#: C/index.docbook:395 +msgid "Setting up a skeleton documentation" +msgstr "Nastavení kostry dokumentace" + +#. (itstool) path: sect1/para +#: C/index.docbook:397 +msgid "" +"Under your top-level project directory create folders called docs/reference " +"(this way you can also have docs/help for end-user documentation). It is " +"recommended to create another subdirectory with the name of the doc-package. " +"For packages with just one library this step is not necessary." +msgstr "" +"Pod nejvyšší složkou projektu vytvořte složky nazvané docs/reference (takto " +"můžete mít i docs/help s dokumentací pro koncového uživatele). Je doporučeno " +"vytvořit další podsložku s názvem balíčku s dokumentací. Pro balíčky s " +"jedinou knihovnou není tento krok nutný." + +#. (itstool) path: example/title +#: C/index.docbook:406 +msgid "Example directory structure" +msgstr "Příklad struktury složek" + +#. (itstool) path: example/programlisting +#: C/index.docbook:407 +#, no-wrap +msgid "" +"\n" +"meep/\n" +" docs/\n" +" reference/\n" +" libmeep/\n" +" meeper/\n" +" src/\n" +" libmeep/\n" +" meeper/\n" +msgstr "" +"\n" +"meep/\n" +" docs/\n" +" reference/\n" +" libmeep/\n" +" meeper/\n" +" src/\n" +" libmeep/\n" +" meeper/\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:404 +msgid "This can then look as shown below: <_:example-1/>" +msgstr "Ve výsledku to může vypadat nějak takto: <_:example-1/>" + +#. (itstool) path: sect1/title +#. (itstool) path: example/title +#: C/index.docbook:422 C/index.docbook:429 +msgid "Integration with autoconf" +msgstr "Integrace s autoconf" + +#. (itstool) path: sect1/para +#: C/index.docbook:424 +msgid "" +"Very easy! Just add one line to your configure.ac " +"script." +msgstr "" +"Velmi snadné! Stačí jen přidat jeden řádek do vašeho skriptu " +"configure.ac." + +#. (itstool) path: example/programlisting +#: C/index.docbook:430 +#, no-wrap +msgid "" +"\n" +"# check for gtk-doc\n" +"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" +msgstr "" +"\n" +"# check for gtk-doc\n" +"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" + +#. (itstool) path: example/title +#: C/index.docbook:442 +msgid "Keep gtk-doc optional" +msgstr "Ponechání gtk-doc jako volitelného" + +#. (itstool) path: example/programlisting +#: C/index.docbook:443 +#, no-wrap +msgid "" +"\n" +"# check for gtk-doc\n" +"m4_ifdef([GTK_DOC_CHECK], [\n" +"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" +"],[\n" +"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n" +"])\n" +msgstr "" +"\n" +"# check for gtk-doc\n" +"m4_ifdef([GTK_DOC_CHECK], [\n" +"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" +"],[\n" +"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n" +"])\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:437 +msgid "" +"This will require all developers to have gtk-doc installed. If it is okay " +"for your project to have optional api-doc build setup, you can solve this as " +"below. Keep it as is, as gtkdocize is looking for GTK_DOC_CHECK at the start of a line. <_:example-1/>" +msgstr "" +"Vyžaduje to, aby všichni vývojáři měli gtk-doc nainstalované. Jestli u " +"vašeho projektu stačí mít sestavení dokumentaci k API jen volitelné, můžete " +"to vyřešit podle vzoru níže. Použijte to přesně tak, jak je uvedeno, protože " +"gtkdocize hledá GTK_DOC_CHECK na začátku řádku. <_:" +"example-1/>" + +#. (itstool) path: sect1/para +#: C/index.docbook:454 +msgid "" +"The first argument is used to check for the gtkdocversion at configure time. " +"The 2nd, optional argument is used by gtkdocize. " +"The GTK_DOC_CHECK macro also adds several configure " +"switches:" +msgstr "" +"První argument se používá ke kontrole gtkdocversion v průběhu konfigurace. " +"Druhý, volitelný argument používá nástroj gtkdocize. Makro GTK_DOC_CHECK také přidává několik " +"přepínačů pro configure:" + +#. (itstool) path: listitem/para +#: C/index.docbook:460 +msgid "--with-html-dir=PATH : path to installed docs" +msgstr "--with-html-dir=CESTA: cesta, kam se má dokumentace nainstalovat" + +#. (itstool) path: listitem/para +#: C/index.docbook:461 +msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" +msgstr "" +"--enable-gtk-doc: použít k sestavení dokumentace gtk-doc [výchozí je ne]" + +#. (itstool) path: listitem/para +#: C/index.docbook:462 +msgid "" +"--enable-gtk-doc-html : build documentation in html format [default=yes]" +msgstr "" +"--enable-gtk-doc-html: sestavit dokumentaci ve formátu HTML [výchozí je ano]" + +#. (itstool) path: listitem/para +#: C/index.docbook:463 +msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" +msgstr "" +"--enable-gtk-doc-pdf: sestavit dokumentaci ve formátu PDF [výchozí je ne]" + +#. (itstool) path: important/para +#: C/index.docbook:467 +msgid "" +"GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " +"Otherwise pregenerated documentation is installed (which makes sense for " +"users but not for developers)." +msgstr "" +"GTK-Doc je standardně vypnuté! Nezapomeňte zadat přepínač „“ 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)." + +#. (itstool) path: sect1/para +#: C/index.docbook:475 +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." +msgstr "" +"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." + +#. (itstool) path: example/title +#: C/index.docbook:483 +msgid "Preparation for gtkdocize" +msgstr "Příprava pro gtkdocize" + +#. (itstool) path: example/programlisting +#: C/index.docbook:484 +#, no-wrap +msgid "" +"\n" +"AC_CONFIG_MACRO_DIR(m4)\n" +msgstr "" +"\n" +"AC_CONFIG_MACRO_DIR(m4)\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:489 +msgid "" +"After all changes to configure.ac are made, update the " +"configure file. This can be done by re-running " +"autoreconf -i or autogen.sh." +msgstr "" +"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." + +#. (itstool) path: sect1/title +#: C/index.docbook:497 +msgid "Integration with automake" +msgstr "Integrace s automake" + +#. (itstool) path: sect1/para +#: C/index.docbook:499 +msgid "" +"First copy the 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 "" +"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." + +#. (itstool) path: sect1/para +#: C/index.docbook:510 +msgid "" +"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." +msgstr "" +"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čů." + +#. (itstool) path: sect1/title +#: C/index.docbook:524 +msgid "Integration with autogen" +msgstr "Integrace s autogen" + +#. (itstool) path: sect1/para +#: C/index.docbook:526 +msgid "" +"Most projects will have an 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." +msgstr "" +"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." + +#. (itstool) path: example/title +#: C/index.docbook:535 +msgid "Running gtkdocize from autogen.sh" +msgstr "Spuštění gtkdocize z autogen.sh" + +#. (itstool) path: example/programlisting +#: C/index.docbook:536 +#, no-wrap +msgid "" +"\n" +"gtkdocize || exit 1\n" +msgstr "" +"\n" +"gtkdocize || exit 1\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:542 +msgid "" +"When running 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." +msgstr "" +"Když spustíte gtkdocize, tak nakopíruje do kořenové " +"složky vašeho projektu (nebo složky určené přepínačem " #. (itstool) path: sect2/para -#: C/index.docbook:332 +#: C/index.docbook:317 msgid "" "docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" #. (itstool) path: sect2/para -#: C/index.docbook:336 +#: C/index.docbook:321 msgid "Python - optional - for gtkdoc-depscan" msgstr "Python - optional - für gtkdoc-depscan" #. (itstool) path: sect2/para -#: C/index.docbook:339 +#: C/index.docbook:324 msgid "" "One of source-highlight, highlight " "or vim - optional - used for syntax highlighting of " "examples" msgstr "" +"source-highlight, highlight oder " +"vim - optional - für Syntax-Hervorhebung von Beispielen" #. (itstool) path: sect1/title -#: C/index.docbook:347 +#: C/index.docbook:332 msgid "About GTK-Doc" msgstr "Info zu GTK-Doc" #. (itstool) path: sect1/para -#: C/index.docbook:349 C/index.docbook:363 +#: C/index.docbook:334 C/index.docbook:348 msgid "(FIXME)" msgstr "(FIXME)" #. (itstool) path: sect1/para -#: C/index.docbook:353 -#, fuzzy -#| msgid "" -#| "(History, authors, web pages, license, future plans, comparison with " -#| "other similar systems.)" +#: C/index.docbook:338 msgid "" "(History, authors, web pages, mailing list, license, future plans, " "comparison with other similar systems.)" msgstr "" -"(Geschichte, Autoren, Webseiten, Lizenz, Zukunftspläne, Vergleich mit " -"ähnlichen Systemen)" +"(Geschichte, Autoren, Webseiten, Mailingliste, Lizenz, Zukunftspläne, " +"Vergleich mit ähnlichen Systemen)" #. (itstool) path: sect1/title -#: C/index.docbook:361 +#: C/index.docbook:346 msgid "About this Manual" msgstr "Über dieses Handbuch" #. (itstool) path: sect1/para -#: C/index.docbook:367 +#: C/index.docbook:352 msgid "(who it is meant for, where you can get it, license)" msgstr "(wofür es bestimmt ist, wo Sie es erhalten können, Lizenz)" #. (itstool) path: chapter/title -#: C/index.docbook:376 +#: C/index.docbook:361 msgid "Setting up your project" msgstr "Einrichten Ihres Projekts" #. (itstool) path: chapter/para -#: C/index.docbook:378 +#: C/index.docbook:363 msgid "" "The next sections describe what steps to perform to integrate GTK-Doc into " "your project. Theses sections assume we work on a project called 'meep'. " @@ -639,12 +589,12 @@ msgstr "" "Erstellungsumgebung." #. (itstool) path: sect1/title -#: C/index.docbook:389 +#: C/index.docbook:374 msgid "Setting up a skeleton documentation" msgstr "Einrichten des Grundgerüsts der Dokumentation" #. (itstool) path: sect1/para -#: C/index.docbook:391 +#: C/index.docbook:376 msgid "" "Under your top-level project directory create folders called docs/reference " "(this way you can also have docs/help for end-user documentation). It is " @@ -659,12 +609,12 @@ msgstr "" "notwendig." #. (itstool) path: example/title -#: C/index.docbook:400 +#: C/index.docbook:385 msgid "Example directory structure" msgstr "Beispiel für die Ordnerstruktur" #. (itstool) path: example/programlisting -#: C/index.docbook:401 +#: C/index.docbook:386 #, no-wrap msgid "" "\n" @@ -688,18 +638,18 @@ msgstr "" " meeper/\n" #. (itstool) path: sect1/para -#: C/index.docbook:398 +#: C/index.docbook:383 msgid "This can then look as shown below: <_:example-1/>" msgstr "Dies kann dann wie nachstehend angezeigt aussehen: <_:example-1/>" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:416 C/index.docbook:423 +#: C/index.docbook:401 C/index.docbook:408 msgid "Integration with autoconf" msgstr "Integration in autoconf" #. (itstool) path: sect1/para -#: C/index.docbook:418 +#: C/index.docbook:403 msgid "" "Very easy! Just add one line to your configure.ac " "script." @@ -708,7 +658,7 @@ msgstr "" "filename>-Skript hinzu." #. (itstool) path: example/programlisting -#: C/index.docbook:424 +#: C/index.docbook:409 #, no-wrap msgid "" "\n" @@ -720,12 +670,12 @@ msgstr "" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" #. (itstool) path: example/title -#: C/index.docbook:436 +#: C/index.docbook:421 msgid "Keep gtk-doc optional" msgstr "Halten Sie gtk-doc optional" #. (itstool) path: example/programlisting -#: C/index.docbook:437 +#: C/index.docbook:422 #, no-wrap msgid "" "\n" @@ -745,7 +695,7 @@ msgstr "" "])\n" #. (itstool) path: sect1/para -#: C/index.docbook:431 +#: C/index.docbook:416 msgid "" "This will require all developers to have gtk-doc installed. If it is okay " "for your project to have optional api-doc build setup, you can solve this as " @@ -759,7 +709,7 @@ msgstr "" "Zeile sucht. <_:example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:448 +#: C/index.docbook:433 msgid "" "The first argument is used to check for the gtkdocversion at configure time. " "The 2nd, optional argument is used by gtkdocize. " @@ -773,19 +723,19 @@ msgstr "" "hinzu:" #. (itstool) path: listitem/para -#: C/index.docbook:454 +#: C/index.docbook:439 msgid "--with-html-dir=PATH : path to installed docs" msgstr "--with-html-dir=PATH : Pfad zur installierten Dokumentation" #. (itstool) path: listitem/para -#: C/index.docbook:455 +#: C/index.docbook:440 msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "" "--enable-gtk-doc : gtk-doc zur Erstellung der Dokumentation verwenden " "[Vorgabe=no]" #. (itstool) path: listitem/para -#: C/index.docbook:456 +#: C/index.docbook:441 msgid "" "--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" @@ -793,14 +743,14 @@ msgstr "" "[Vorgabe=yes]" #. (itstool) path: listitem/para -#: C/index.docbook:457 +#: C/index.docbook:442 msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" msgstr "" "--enable-gtk-doc-pdf : Erstellung der Dokumentation im PDF-Format " "[Vorgabe=no]" #. (itstool) path: important/para -#: C/index.docbook:461 +#: C/index.docbook:446 msgid "" "GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " @@ -814,7 +764,7 @@ msgstr "" "aber nicht für Entwickler." #. (itstool) path: sect1/para -#: C/index.docbook:469 +#: C/index.docbook:454 msgid "" "Furthermore it is recommended that you have the following line inside you " "configure.ac script. This allows " @@ -827,12 +777,12 @@ msgstr "" "GTK_DOC_CHECK in Ihr Projekt." #. (itstool) path: example/title -#: C/index.docbook:477 +#: C/index.docbook:462 msgid "Preparation for gtkdocize" msgstr "Vorbereitung für gtkdocize" #. (itstool) path: example/programlisting -#: C/index.docbook:478 +#: C/index.docbook:463 #, no-wrap msgid "" "\n" @@ -842,26 +792,24 @@ msgstr "" "AC_CONFIG_MACRO_DIR(m4)\n" #. (itstool) path: sect1/para -#: C/index.docbook:483 +#: C/index.docbook:468 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 "" +"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." #. (itstool) path: sect1/title -#: C/index.docbook:491 +#: C/index.docbook:476 msgid "Integration with automake" msgstr "Integration in automake" #. (itstool) path: sect1/para -#: C/index.docbook:493 -#, fuzzy -#| msgid "" -#| "First copy the 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." +#: C/index.docbook:478 msgid "" "First copy the Makefile.am from the examples sub directory of the Makefile.am aus dem " -"Beispiel-Unterordner der gtkdoc-sources in den API-Dokumentationsordner " -"Ihres Projekts ( ./docs/reference/<" -"package>). Falls Sie mehrere Dokumentationspakete haben, " -"müssen Sie dies für jedes davon wiederholen." +"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." #. (itstool) path: sect1/para -#: C/index.docbook:504 +#: C/index.docbook:489 msgid "" "The next step is to edit the settings inside the Makefile.am. All the settings have a comment above that describes their " @@ -897,12 +848,12 @@ msgstr "" "unterstützten Parameter." #. (itstool) path: sect1/title -#: C/index.docbook:518 +#: C/index.docbook:503 msgid "Integration with autogen" msgstr "Integration in autogen" #. (itstool) path: sect1/para -#: C/index.docbook:520 +#: C/index.docbook:505 msgid "" "Most projects will have an autogen.sh script to setup " "the build infrastructure after a checkout from version control system (such " @@ -918,12 +869,12 @@ msgstr "" "oder autoconf ausgeführt werden." #. (itstool) path: example/title -#: C/index.docbook:529 +#: C/index.docbook:514 msgid "Running gtkdocize from autogen.sh" msgstr "Ausführen von gtkdocize durch autogen.sh" #. (itstool) path: example/programlisting -#: C/index.docbook:530 +#: C/index.docbook:515 #, no-wrap msgid "" "\n" @@ -933,7 +884,7 @@ msgstr "" "gtkdocize || exit 1\n" #. (itstool) path: sect1/para -#: C/index.docbook:536 +#: C/index.docbook:521 msgid "" "When running gtkdocize it copies gtk-" "doc.make to your project root (or any directory specified by the " @@ -949,7 +900,7 @@ msgstr "" "Parameter an gtkdocize zu übergeben." #. (itstool) path: sect1/para -#: C/index.docbook:545 +#: C/index.docbook:530 msgid "" "Historically GTK-Doc was generating template files where developers entered " "the docs. This turned out to be not so good (e.g. the need for having " @@ -984,12 +935,12 @@ msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:562 C/index.docbook:579 +#: C/index.docbook:547 C/index.docbook:564 msgid "Running the doc build" msgstr "Erstellung der Dokumentation" #. (itstool) path: sect1/para -#: C/index.docbook:564 +#: C/index.docbook:549 msgid "" "After the previous steps it's time to run the build. First we need to rerun " "autogen.sh. If this script runs configure for you, then " @@ -1004,7 +955,7 @@ msgstr "" "Option." #. (itstool) path: sect1/para -#: C/index.docbook:571 +#: C/index.docbook:556 msgid "" "The first make run generates several additional files in the doc-" "directories. The important ones are: <package>.types<package>-sections.txt." #. (itstool) path: example/programlisting -#: C/index.docbook:580 +#: C/index.docbook:565 #, no-wrap msgid "" "\n" @@ -1029,7 +980,7 @@ msgstr "" "make\n" #. (itstool) path: sect1/para -#: C/index.docbook:586 +#: C/index.docbook:571 msgid "" "Now you can point your browser to docs/reference/<package>/" "index.html. Yes, it's a bit disappointing still. But hang-on, " @@ -1041,19 +992,12 @@ msgstr "" "Seiten mit Leben füllen können." #. (itstool) path: sect1/title -#: C/index.docbook:594 +#: C/index.docbook:579 msgid "Integration with version control systems" msgstr "Integration in Versionsverwaltungssysteme" #. (itstool) path: sect1/para -#: C/index.docbook:596 -#, fuzzy -#| msgid "" -#| "As a rule of the thumb, it's those files you edit, that should go under " -#| "version control. For typical projects it's these files: <" -#| "package>.types, <package>-docs.xml (in the past .sgml), <package>-sections.txt, Makefile.am" +#: C/index.docbook:581 msgid "" "As a rule of thumb, it's the files you edit which should go under version " "control. For typical projects it's these files: <package>." @@ -1064,24 +1008,27 @@ msgstr "" "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>-" +"package>-docs.xml (früher .sgml), <package>-" "sections.txt, Makefile.am." #. (itstool) path: sect1/para -#: C/index.docbook:604 +#: C/index.docbook:589 msgid "" "Files in the xml/ and html/ " "directories should not go under version control. Neither should any of the " ".stamp files." msgstr "" +"Dateien in den Ordnern xml/ und html/ sollten nicht unter Versionsverwaltung gestellt werden, ebenso " +"keine der .stamp-Dateien." #. (itstool) path: sect1/title -#: C/index.docbook:612 +#: C/index.docbook:597 msgid "Integration with plain makefiles or other build systems" msgstr "Integration in Klartext-Makefiles oder andere Erstellungssysteme" #. (itstool) path: sect1/para -#: C/index.docbook:614 +#: C/index.docbook:599 msgid "" "In the case one does not want to use automake and therefore gtk-" "doc.mak one will need to call the gtkdoc tools in the right order " @@ -1092,12 +1039,12 @@ msgstr "" "(oder andere Werkzeuge) in der richtigen Reihenfolge aufrufen." #. (itstool) path: example/title -#: C/index.docbook:621 +#: C/index.docbook:606 msgid "Documentation build steps" msgstr "Schritte zur Erstellung der Dokumentation" #. (itstool) path: example/programlisting -#: C/index.docbook:622 +#: C/index.docbook:607 #, no-wrap msgid "" "\n" @@ -1123,7 +1070,7 @@ msgstr "" "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" #. (itstool) path: sect1/para -#: C/index.docbook:636 +#: C/index.docbook:621 msgid "" "One will need to look at the Makefile.am and " "gtk-doc.mak to pick the extra options needed." @@ -1132,28 +1079,31 @@ msgstr "" "filename> anschauen, um die zusätzlich notwendigen Optionen herauszusuchen." #. (itstool) path: sect1/title -#: C/index.docbook:643 -#, fuzzy -#| msgid "Integration with plain makefiles or other build systems" +#: C/index.docbook:628 msgid "Integration with CMake build systems" -msgstr "Integration in Klartext-Makefiles oder andere Erstellungssysteme" +msgstr "Integration in CMake-Erstellungssysteme" #. (itstool) path: sect1/para -#: C/index.docbook:645 +#: C/index.docbook:630 msgid "" "GTK-Doc now provides a 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 "" +"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." #. (itstool) path: example/title -#: C/index.docbook:655 +#: C/index.docbook:640 msgid "Example of using GTK-Doc from CMake" -msgstr "" +msgstr "Beispiel zur Verwendung von GTK-Doc mit CMake" #. (itstool) path: example/programlisting -#: C/index.docbook:656 +#: C/index.docbook:641 #, no-wrap msgid "" "\n" @@ -1175,19 +1125,39 @@ msgid "" "install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html\n" " DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" msgstr "" +"\n" +"find_package(GtkDoc 1.25 REQUIRED)\n" +"\n" +"# Create the doc-libmeep target.\n" +"gtk_doc_add_module(\n" +" libmeep ${CMAKE_SOURCE_DIR}/libmeep\n" +" XML meep-docs.xml\n" +" LIBRARIES libmeep\n" +")\n" +"\n" +"# Build doc-libmeep as part of the default target. Without this, you would\n" +"# have to explicitly run something like `make doc-libmeep` to build the docs.\n" +"add_custom_target(documentation ALL DEPENDS doc-libmeep)\n" +"\n" +"# Install the docs. (This assumes you're using the GNUInstallDirs CMake module\n" +"# to set the CMAKE_INSTALL_DOCDIR variable correctly).\n" +"install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html\n" +" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" #. (itstool) path: sect1/para -#: C/index.docbook:653 +#: C/index.docbook:638 msgid "The following example shows how to use this command. <_:example-1/>" msgstr "" +"Das folgende Beispiel zeigt, wie dieser Befehl eingesetzt wird. <_:example-1/" +">" #. (itstool) path: chapter/title -#: C/index.docbook:681 +#: C/index.docbook:666 msgid "Documenting the code" msgstr "Dokumentieren des Codes" #. (itstool) path: chapter/para -#: C/index.docbook:683 +#: C/index.docbook:668 msgid "" "GTK-Doc uses source code comment with a special syntax for code " "documentation. Further it retrieves information about your project structure " @@ -1200,12 +1170,12 @@ msgstr "" "Informationen über die Syntax der Kommentare." #. (itstool) path: note/title -#: C/index.docbook:691 +#: C/index.docbook:676 msgid "Documentation placement" msgstr "Platzierung der Dokumentation" #. (itstool) path: note/para -#: C/index.docbook:692 +#: C/index.docbook:677 msgid "" "In the past most documentation had to be filled into files residing inside " "the tmpl directory. This has the disadvantages that the " @@ -1218,7 +1188,7 @@ msgstr "" "Konflikte mit Versionsverwaltungssystemen verursachen kann." #. (itstool) path: note/para -#: C/index.docbook:698 +#: C/index.docbook:683 msgid "" "The avoid the aforementioned problems we suggest putting the documentation " "inside the sources. This manual will only describe this way of documenting " @@ -1229,12 +1199,12 @@ msgstr "" "ausschließlich dieser Weg des Dokumentierens des Quellcodes beschrieben." #. (itstool) path: example/title -#: C/index.docbook:709 C/index.docbook:735 +#: C/index.docbook:694 C/index.docbook:720 msgid "GTK-Doc comment block" msgstr "GTK-Doc-Kommentarblock" #. (itstool) path: example/programlisting -#: C/index.docbook:710 +#: C/index.docbook:695 #, no-wrap msgid "" "\n" @@ -1248,7 +1218,7 @@ msgstr "" "#endif\n" #. (itstool) path: chapter/para -#: C/index.docbook:705 +#: C/index.docbook:690 msgid "" "The scanner can handle the majority of C headers fine. In the case of " "receiving warnings from the scanner that look like a special case, one can " @@ -1259,24 +1229,27 @@ msgstr "" "anweisen diese zu überspringen. <_:example-1/>" #. (itstool) path: note/title -#: C/index.docbook:719 +#: C/index.docbook:704 msgid "Limitations" msgstr "Einschränkungen" #. (itstool) path: note/para -#: C/index.docbook:720 +#: C/index.docbook:705 msgid "" "Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but " "not #if !defined(__GTK_DOC_IGNORE__) or other combinations." msgstr "" +"Beachten Sie, dass GTK-Doc zwar #ifndef(__GTK_DOC_IGNORE__) " +"unterstützt, aber nicht #if !defined(__GTK_DOC_IGNORE__) oder " +"andere Kombinationen." #. (itstool) path: sect1/title -#: C/index.docbook:730 +#: C/index.docbook:715 msgid "Documentation comments" msgstr "Kommentare zur Dokumentation" #. (itstool) path: example/programlisting -#: C/index.docbook:736 +#: C/index.docbook:721 #, no-wrap msgid "" "\n" @@ -1292,7 +1265,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:732 +#: C/index.docbook:717 msgid "" "A multiline comment that starts with an additional '*' marks a documentation " "block that will be processed by the GTK-Doc tools. <_:example-1/>" @@ -1302,7 +1275,7 @@ msgstr "" "example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:745 +#: C/index.docbook:730 msgid "" "The 'identifier' is one line with the name of the item the comment is " "related to. The syntax differs a little depending on the item. (TODO add " @@ -1313,7 +1286,7 @@ msgstr "" "variieren." #. (itstool) path: sect1/para -#: C/index.docbook:751 +#: C/index.docbook:736 msgid "" "The 'documentation' block is also different for each symbol type. Symbol " "types that get parameters such as functions or macros have the parameter " @@ -1334,7 +1307,7 @@ msgstr "" "dahinter. Dies ist in vorformatiertem Text nützlich (Code-Auflistungen)." #. (itstool) path: listitem/para -#: C/index.docbook:768 +#: C/index.docbook:753 msgid "" "What it is: The name for a class or function can sometimes be misleading for " "people coming from a different background." @@ -1343,7 +1316,7 @@ msgstr "" "führend sein für Personen, die einen anderen Hintergrund haben." #. (itstool) path: listitem/para -#: C/index.docbook:774 +#: C/index.docbook:759 msgid "" "What it does: Tell about common uses. Put it in relation with the other API." msgstr "" @@ -1351,20 +1324,20 @@ msgstr "" "Verhältnis mit der anderen API." #. (itstool) path: tip/para -#: C/index.docbook:764 +#: C/index.docbook:749 msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" msgstr "" "Beim Dokumentieren von Code beschreiben Sie zwei Aspekte: <_:itemizedlist-1/>" #. (itstool) path: listitem/para -#: C/index.docbook:789 +#: C/index.docbook:774 msgid "Use function() to refer to functions or macros which take arguments." msgstr "" "Verwenden Sie function(), um einen Bezug zu Funktionen oder Makros " "herzustellen, die Argumente akzeptieren." #. (itstool) path: listitem/para -#: C/index.docbook:794 +#: C/index.docbook:779 msgid "" "Use @param to refer to parameters. Also use this when referring to " "parameters of other functions, related to the one being described." @@ -1374,14 +1347,14 @@ msgstr "" "bezogen auf jene, die Sie gerade beschreiben." #. (itstool) path: listitem/para -#: C/index.docbook:800 +#: C/index.docbook:785 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "" "Benutzen Sie %constant, um einen Bezug auf eine Konstante herzustellen, z.B. " "%G_TRAVERSE_LEAFS." #. (itstool) path: listitem/para -#: C/index.docbook:805 +#: C/index.docbook:790 msgid "" "Use #symbol to refer to other types of symbol, e.g. structs and enums and " "macros which don't take arguments." @@ -1390,29 +1363,27 @@ msgstr "" "»structs« und »enums« und Makros, die keine Argumente benötigen." #. (itstool) path: listitem/para -#: C/index.docbook:811 +#: C/index.docbook:796 msgid "Use #Object::signal to refer to a GObject signal." msgstr "Verwenden Sie #Object::signal, um auf ein GObject-Signal zu verweisen" #. (itstool) path: listitem/para -#: C/index.docbook:816 +#: C/index.docbook:801 msgid "Use #Object:property to refer to a GObject property." msgstr "" "Verwenden Sie #Object:property, um auf eine GObject-Eigenschaft zu verweisen." #. (itstool) path: listitem/para -#: C/index.docbook:821 -#, fuzzy -#| msgid "Use #Struct.field to refer to a field inside a structure." +#: C/index.docbook:806 msgid "" "Use #Struct.field to refer to a field inside a structure and #GObjectClass." "foo_bar() to refer to a vmethod." msgstr "" "Verwenden Sie #Struct.field, um auf ein Feld innerhalb einer Struktur zu " -"verweisen." +"verweisen und #GObjectClass.foo_bar() für eine vmethod." #. (itstool) path: sect1/para -#: C/index.docbook:783 +#: C/index.docbook:768 msgid "" "One advantage of hyper-text over plain-text is the ability to have links in " "the document. Writing the correct markup for a link can be tedious though. " @@ -1426,7 +1397,7 @@ msgstr "" "itemizedlist-1/>" #. (itstool) path: tip/para -#: C/index.docbook:830 +#: C/index.docbook:815 msgid "" "If you need to use the special characters '<', '>', '()', '@', '%', or " "'#' in your documentation without GTK-Doc changing them you can use the XML " @@ -1441,7 +1412,7 @@ msgstr "" "einem Backslash »\\« maskieren." #. (itstool) path: sect1/para -#: C/index.docbook:839 +#: C/index.docbook:824 msgid "" "DocBook can do more than just links. One can also have lists, examples, " "headings, and images. As of version 1.20, the preferred way is to use a " @@ -1450,24 +1421,27 @@ msgid "" "versions any documentation that includes Markdown will be rendered as is. " "For example, list items will appear as lines starting with a dash." msgstr "" +"DocBook kann mehr als nur Verweise zu erzeugen. Sie können Listen, " +"Beispiele, Überschriften und Bilder einfügen. In Version 1.20 ist der " +"bevorzugte Weg, ein Subset grundlegender Textformatierungssyntax namens " +"Markdown " +"zu verwenden. In älteren Versionen von GTK-Doc wird jede Dokumentation, die " +"Markdown enthält, unverändert gerendert. Zum Beispiel erscheinen " +"Listenobjekte als Zeilen, die mit einem Gedankenstrich beginnen." #. (itstool) path: sect1/para -#: C/index.docbook:850 +#: C/index.docbook:835 msgid "" "While markdown is now preferred one can mix both. One limitation here is " "that one can use docbook xml within markdown, but markdown within docbook " "xml is not supported." msgstr "" +"Wenngleich Markdown bevorzugt wird, können Sie beide Formate mischen. Eine " +"Einschränkung ist jedoch, dass Sie DocBook XML innerhalb von Markdown " +"verwenden können, während Markdown in DocBook XML nicht unterstützt wird." #. (itstool) path: sect1/para -#: C/index.docbook:856 -#, fuzzy -#| msgid "" -#| "DocBook can do more than just links. One can also have lists, tables and " -#| "examples. To enable the usage of docbook SGML/XML tags inside doc-" -#| "comments you need to have or in the variable MKDB_OPTIONS inside " -#| "Makefile.am." +#: C/index.docbook:841 msgid "" "In older GTK-Doc releases, if you need support for additional formatting, " "you would need to enable the usage of docbook XML tags inside doc-comments " @@ -1475,21 +1449,18 @@ msgid "" "the variable MKDB_OPTIONS inside Makefile.am." msgstr "" -"DocBook kann mehr als nur verknüpfen. Sie können auch Listen, Tabellen und " -"Beispiele einbauen. Um die Nutzung der DocBook-SGML/XML-Tags innerhalb der " +"Um die Nutzung der DocBook-XML-Markierungen innerhalb der " "Dokumentationskommentare zu aktivieren, übergeben Sie der Variable " "MKDB_OPTIONS in der Datei Makefile.am " -"die Option oder ." +"die Option (oder )." #. (itstool) path: example/title -#: C/index.docbook:865 -#, fuzzy -#| msgid "GTK-Doc comment block using markdown" +#: C/index.docbook:850 msgid "GTK-Doc comment block using Markdown" msgstr "GTK-Doc-Kommentarblock in Markdown-Syntax" #. (itstool) path: example/programlisting -#: C/index.docbook:866 +#: C/index.docbook:851 #, no-wrap msgid "" "\n" @@ -1565,15 +1536,18 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:905 +#: C/index.docbook:890 msgid "" "More examples of what markdown tags are supported can be found in the GTK+ Documentation Markdown Syntax Reference." msgstr "" +"Weitere Beispiele zu den unterstützten Markdown-Formatierungen finden Sie in " +"der GTK+ Documentation Markdown Syntax Reference." #. (itstool) path: tip/para -#: C/index.docbook:911 +#: C/index.docbook:896 msgid "" "As already mentioned earlier GTK-Doc is for documenting public API. Thus one " "cannot write documentation for static symbols. Nevertheless it is good to " @@ -1594,12 +1568,12 @@ msgstr "" "Abschnittsdatei einzubauen." #. (itstool) path: sect1/title -#: C/index.docbook:925 +#: C/index.docbook:910 msgid "Documenting sections" msgstr "Dokumentieren von Abschnitten" #. (itstool) path: sect1/para -#: C/index.docbook:927 +#: C/index.docbook:912 msgid "" "Each section of the documentation contains information about one class or " "module. To introduce the component one can write a section block. The short " @@ -1612,12 +1586,12 @@ msgstr "" "Inhaltsverzeichnis verwendet. Alle @-Felder sind optional." #. (itstool) path: example/title -#: C/index.docbook:935 +#: C/index.docbook:920 msgid "Section comment block" msgstr "Abschnitts-Kommentarblock" #. (itstool) path: example/programlisting -#: C/index.docbook:936 +#: C/index.docbook:921 #, no-wrap msgid "" "\n" @@ -1649,12 +1623,12 @@ msgstr "" " */\n" #. (itstool) path: varlistentry/term -#: C/index.docbook:955 +#: C/index.docbook:940 msgid "SECTION:<name>" msgstr "SECTION:<name>" #. (itstool) path: listitem/para -#: C/index.docbook:957 +#: C/index.docbook:942 msgid "" "The name links the section documentation to the respective part in the " "<package>-sections.txt file. The name give here " @@ -1667,12 +1641,12 @@ msgstr "" "<package>-sections.txt entsprechen." #. (itstool) path: varlistentry/term -#: C/index.docbook:966 +#: C/index.docbook:951 msgid "@short_description" msgstr "@short_description" #. (itstool) path: listitem/para -#: C/index.docbook:968 +#: C/index.docbook:953 msgid "" "A one line description of the section, that later will appear after the " "links in the TOC and at the top of the section page." @@ -1681,12 +1655,12 @@ msgstr "" "im Inhaltsverzeichnis und oben in der Abschnittsseite erscheint." #. (itstool) path: varlistentry/term -#: C/index.docbook:975 +#: C/index.docbook:960 msgid "@title" msgstr "@title" #. (itstool) path: listitem/para -#: C/index.docbook:977 +#: C/index.docbook:962 msgid "" "The section title defaults to <name> from the SECTION declaration. It " "can be overridden with the @title field." @@ -1695,12 +1669,12 @@ msgstr "" "kann im Feld @title überschrieben werden." #. (itstool) path: varlistentry/term -#: C/index.docbook:984 +#: C/index.docbook:969 msgid "@section_id" msgstr "@section_id" #. (itstool) path: listitem/para -#: C/index.docbook:986 +#: C/index.docbook:971 msgid "" "Overrides the use of title as a section identifier. For GObjects the <" "title> is used as a section_id and for other sections it is <" @@ -1711,22 +1685,22 @@ msgstr "" "<MODUL>-<Titel>." #. (itstool) path: varlistentry/term -#: C/index.docbook:994 +#: C/index.docbook:979 msgid "@see_also" msgstr "@see_also" #. (itstool) path: listitem/para -#: C/index.docbook:996 +#: C/index.docbook:981 msgid "A list of symbols that are related to this section." msgstr "Eine Liste von Symbolen, welche sich auf diesen Abschnitt beziehen." #. (itstool) path: varlistentry/term -#: C/index.docbook:1002 +#: C/index.docbook:987 msgid "@stability" msgstr "@stability" #. (itstool) path: listitem/para -#: C/index.docbook:1009 +#: C/index.docbook:994 msgid "" "Stable - The intention of a Stable interface is to enable arbitrary third " "parties to develop applications to these interfaces, release them, and have " @@ -1744,7 +1718,7 @@ msgstr "" "von stark berechtigten." #. (itstool) path: listitem/para -#: C/index.docbook:1021 +#: C/index.docbook:1006 msgid "" "Unstable - Unstable interfaces are experimental or transitional. They are " "typically used to give outside developers early access to new or rapidly " @@ -1760,7 +1734,7 @@ msgstr "" "Binärkompatibilität von einer minor-Freigabe zur nächsten gegeben." #. (itstool) path: listitem/para -#: C/index.docbook:1033 +#: C/index.docbook:1018 msgid "" "Private - An interface that can be used within the GNOME stack itself, but " "that is not documented for end-users. Such functions should only be used in " @@ -1771,7 +1745,7 @@ msgstr "" "nur auf spezifizierte und dokumentierte Weisen verwendet werden." #. (itstool) path: listitem/para -#: C/index.docbook:1042 +#: C/index.docbook:1027 msgid "" "Internal - An interface that is internal to a module and does not require " "end-user documentation. Functions that are undocumented are assumed to be " @@ -1782,7 +1756,7 @@ msgstr "" "intern angesehen." #. (itstool) path: listitem/para -#: C/index.docbook:1004 +#: C/index.docbook:989 msgid "" "An informal description of the stability level this API has. We recommend " "the use of one of these terms: <_:itemizedlist-1/>" @@ -1791,12 +1765,12 @@ msgstr "" "dafür einen der folgenden Begriffe: <_:itemizedlist-1/>" #. (itstool) path: varlistentry/term -#: C/index.docbook:1054 +#: C/index.docbook:1039 msgid "@include" msgstr "@include" #. (itstool) path: listitem/para -#: C/index.docbook:1056 +#: C/index.docbook:1041 msgid "" "The #include files to show in the section synopsis (a " "comma separated list), overriding the global value from the --default-stability argument to " "gtkdoc-mkdb with one of the values below." msgstr "" +"Die Standard-Stabilitätsstufe für alle Dokumentationselemente setzen Sie " +"durch Übergabe des Arguments an " +"gtkdoc-mkdb in einem der nachfolgend " +"beschriebenen Werte." #. (itstool) path: variablelist/title -#: C/index.docbook:1134 -#, fuzzy -#| msgid "@stability" +#: C/index.docbook:1119 msgid "Stability Tags" -msgstr "@stability" +msgstr "Stabilitäts-Markierungen" #. (itstool) path: varlistentry/term -#: C/index.docbook:1135 +#: C/index.docbook:1120 msgid "Stability: Stable" -msgstr "" +msgstr "Stability: Stable" #. (itstool) path: listitem/para -#: C/index.docbook:1137 +#: C/index.docbook:1122 msgid "" "Mark the element as stable. This is for public APIs which are guaranteed to " "remain stable for all future minor releases of the project." msgstr "" +"Markiert das Element als stabil. Dies bezieht sich auf öffentliche APIs, für " +"die für alle zukünftigen Minor-Veröffentlichungen des Projekts Stabilität " +"gewährleistet ist." #. (itstool) path: varlistentry/term -#: C/index.docbook:1144 +#: C/index.docbook:1129 msgid "Stability: Unstable" -msgstr "" +msgstr "Stability: Unstable" #. (itstool) path: listitem/para -#: C/index.docbook:1146 +#: C/index.docbook:1131 msgid "" "Mark the element as unstable. This is for public APIs which are released as " "a preview before being stabilised." msgstr "" +"Markiert das Element als instabil. Dies bezieht sich auf öffentliche APIs, " +"die als Vorschau vor der endgültigen Stabilisierung gedacht sind." #. (itstool) path: varlistentry/term -#: C/index.docbook:1152 +#: C/index.docbook:1137 msgid "Stability: Private" -msgstr "" +msgstr "Stability: Private" #. (itstool) path: listitem/para -#: C/index.docbook:1154 +#: C/index.docbook:1139 msgid "" "Mark the element as private. This is for interfaces which can be used by " "tightly coupled modules, but not by arbitrary third parties." msgstr "" +"Markiert das Element als privat. Dies bezieht sich auf Schnittstellen, die " +"von eng damit verknüpften Modulen genutzt werden kann, aber nicht von " +"beliebigen Drittanbietern." #. (itstool) path: example/programlisting -#: C/index.docbook:1164 +#: C/index.docbook:1149 #, no-wrap msgid "" "\n" @@ -2008,12 +1988,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1184 C/index.docbook:1194 +#: C/index.docbook:1169 C/index.docbook:1179 msgid "Annotations" msgstr "Anmerkungen" #. (itstool) path: sect2/para -#: C/index.docbook:1186 +#: C/index.docbook:1171 msgid "" "Documentation blocks can contain annotation-tags. These tags will be " "rendered with tooltips describing their meaning. The tags are used by " @@ -2021,9 +2001,15 @@ msgid "" "supported tags can be found on the wiki." msgstr "" +"Dokumentationsblöcke können Anmerkungs-Markierungen enthalten. Diese " +"Markierungen werden als Tooltips (Minihilfen) dargestellt, die die jeweilige " +"Bedeutung anzeigen. Sie werden von gobject-introspection genutzt, um " +"Sprachbindungen zu erzeugen. Eine detaillierte Liste der unterstützten " +"Markierungen finden Sie im Wiki." #. (itstool) path: example/programlisting -#: C/index.docbook:1195 +#: C/index.docbook:1180 #, no-wrap msgid "" "\n" @@ -2064,12 +2050,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1216 C/index.docbook:1245 +#: C/index.docbook:1201 C/index.docbook:1230 msgid "Function comment block" msgstr "Kommentarblock einer Funktion" #. (itstool) path: listitem/para -#: C/index.docbook:1222 +#: C/index.docbook:1207 msgid "" "Document whether returned objects, lists, strings, etc, should be freed/" "unrefed/released." @@ -2078,14 +2064,14 @@ msgstr "" "dereferenziert/freigegeben werden." #. (itstool) path: listitem/para -#: C/index.docbook:1228 +#: C/index.docbook:1213 msgid "Document whether parameters can be NULL, and what happens if they are." msgstr "" "Dokumentiert, ob Parameter NULL sein können, und was in diesem Fall " "geschieht." #. (itstool) path: listitem/para -#: C/index.docbook:1233 +#: C/index.docbook:1218 msgid "" "Mention interesting pre-conditions and post-conditions where appropriate." msgstr "" @@ -2093,12 +2079,12 @@ msgstr "" "es nützlich erscheint." #. (itstool) path: sect2/para -#: C/index.docbook:1218 C/index.docbook:1304 +#: C/index.docbook:1203 C/index.docbook:1289 msgid "Please remember to: <_:itemizedlist-1/>" msgstr "Bitte denken Sie an: <_:itemizedlist-1/>" #. (itstool) path: sect2/para -#: C/index.docbook:1240 +#: C/index.docbook:1225 msgid "" "Gtk-doc assumes all symbols (macros, functions) starting with '_' are " "private. They are treated like static functions." @@ -2107,7 +2093,7 @@ msgstr "" "beginnen, privat sind. Sie werden wie statische Funktionen behandelt." #. (itstool) path: example/programlisting -#: C/index.docbook:1246 +#: C/index.docbook:1231 #, no-wrap msgid "" "\n" @@ -2149,40 +2135,43 @@ msgstr "" " */\n" #. (itstool) path: variablelist/title -#: C/index.docbook:1267 +#: C/index.docbook:1252 msgid "Function tags" -msgstr "Funktions-Tags" +msgstr "Funktions-Markierungen" #. (itstool) path: varlistentry/term -#: C/index.docbook:1268 +#: C/index.docbook:1253 C/index.docbook:1460 msgid "Returns:" msgstr "Returns:" #. (itstool) path: listitem/para -#: C/index.docbook:1270 +#: C/index.docbook:1255 msgid "Paragraph describing the returned result." msgstr "Abschnitt, der das zurückgegebene Ergebnis beschreibt." #. (itstool) path: varlistentry/term -#: C/index.docbook:1275 +#: C/index.docbook:1260 msgid "@...:" msgstr "@...:" #. (itstool) path: listitem/para -#: C/index.docbook:1277 +#: C/index.docbook:1262 msgid "" "In case the function has variadic arguments, you should use this tag " "(@Varargs: does also work for historic reasons)." msgstr "" +"Wenn die Funktion variadische Argumente enthält, sollten Sie diese " +"Markierung verwenden (@Varargs: funktioniert aus historischen Gründen " +"ebenfalls)." #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1287 C/index.docbook:1289 +#: C/index.docbook:1272 C/index.docbook:1274 msgid "Property comment block" msgstr "Property-Kommentarblock" #. (itstool) path: example/programlisting -#: C/index.docbook:1290 +#: C/index.docbook:1275 #, no-wrap msgid "" "\n" @@ -2203,12 +2192,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1302 C/index.docbook:1321 +#: C/index.docbook:1287 C/index.docbook:1306 msgid "Signal comment block" msgstr "Signal-Kommentarblock" #. (itstool) path: listitem/para -#: C/index.docbook:1308 +#: C/index.docbook:1293 msgid "" "Document when the signal is emitted and whether it is emitted before or " "after other signals." @@ -2217,12 +2206,12 @@ msgstr "" "anderen Signalen ausgegeben wird." #. (itstool) path: listitem/para -#: C/index.docbook:1314 +#: C/index.docbook:1299 msgid "Document what an application might do in the signal handler." msgstr "Dokumentiert, was eine Anwendung in dem Signal-Handler tun könnte." #. (itstool) path: example/programlisting -#: C/index.docbook:1322 +#: C/index.docbook:1307 #, no-wrap msgid "" "\n" @@ -2253,12 +2242,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1339 C/index.docbook:1340 +#: C/index.docbook:1324 C/index.docbook:1325 msgid "Struct comment block" msgstr "Struct-Kommentarblock" #. (itstool) path: example/programlisting -#: C/index.docbook:1341 +#: C/index.docbook:1326 #, no-wrap msgid "" "\n" @@ -2288,7 +2277,7 @@ msgstr "" "} FooWidget;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1356 +#: C/index.docbook:1341 msgid "" "Use /*< private >*/ before the private struct fields you " "want to hide. Use /*< public >*/ for the reverse " @@ -2299,15 +2288,18 @@ msgstr "" "verwenden Sie /*< public >*/." #. (itstool) path: sect2/para -#: C/index.docbook:1362 +#: C/index.docbook:1347 msgid "" "If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" " "it will be considered private automatically and doesn't need to be mentioned " "in the comment block." msgstr "" +"Wenn das erste Feld »g_iface«, »parent_instance« oder »parent_class« ist, " +"wird es automatisch als privat angesehen und muss nicht im Kommentarblock " +"erwähnt werden." #. (itstool) path: sect2/para -#: C/index.docbook:1368 +#: C/index.docbook:1353 msgid "" "Struct comment blocks can also be used for GObjects and GObjectClasses. It " "is usually a good idea to add a comment block for a class, if it has " @@ -2317,15 +2309,23 @@ msgid "" "here is that this creates two index entries of the same name (the structure " "and the section)." msgstr "" +"Struct-Kommentarblöcke können auch für GObjects und GObjectClasses verwendet " +"werden. Es ist ratsam, einen Kommentarblock für eine Klasse hinzuzufügen, " +"wenn diese vmethods enthält (dies ist die Art der Dokumentation dafür). Für " +"GObject selbst können Sie die jeweiligen Abschnittsdokumentationen " +"verwenden, wobei ein separater Block für das Instanz-Struct sinnvoll ist, " +"sofern die Instanz öffentliche Felder enthält. Ein Nachteil ist hier, dass " +"dadurch zwei gleichnamige Indexeinträge erstellt werden (die Struktur und " +"der Abschnitt)." #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1380 C/index.docbook:1381 +#: C/index.docbook:1365 C/index.docbook:1366 msgid "Enum comment block" msgstr "Enum-Kommentarblock" #. (itstool) path: example/programlisting -#: C/index.docbook:1382 +#: C/index.docbook:1367 #, no-wrap msgid "" "\n" @@ -2359,7 +2359,7 @@ msgstr "" "} Something;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1399 +#: C/index.docbook:1384 msgid "" "Use /*< private >*/ before the private enum values you " "want to hide. Use /*< public >*/ for the reverse " @@ -2370,20 +2370,167 @@ msgstr "" "verwenden Sie /*< public >*/." #. (itstool) path: sect1/title -#: C/index.docbook:1409 +#: C/index.docbook:1395 +msgid "Inline program documentation" +msgstr "Eingebettete Programmdokumentation" + +#. (itstool) path: sect1/para +#: C/index.docbook:1396 +msgid "" +"You can document programs and their commandline interface using inline " +"documentation." +msgstr "" +"Dokumentieren Sie ein Programm und dessen Befehlszeilen-Schnittstelle mit " +"eingebetteter Dokumentation." + +#. (itstool) path: variablelist/title +#: C/index.docbook:1402 +msgid "Tags" +msgstr "Schlagwörter" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1404 +msgid "PROGRAM" +msgstr "PROGRAM" + +#. (itstool) path: listitem/para +#: C/index.docbook:1407 +msgid "Defines the start of a program documentation." +msgstr "Definiert den Start einer Programmdokumentation" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1414 +msgid "@short_description:" +msgstr "@short_description:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1416 +msgid "Defines a short description of the program. (Optional)" +msgstr "Definiert eine Kurzbeschreibung des Programms (optional)." + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1423 +msgid "@synopsis:" +msgstr "@synopsis:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1425 +msgid "" +"Defines the arguments, or list of arguments that the program can take. " +"(Optional)" +msgstr "" +"Definiert die Argumente oder eine Liste von Argumenten, die das Programm " +"akzeptiert (optional)." + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1433 +msgid "@see_also:" +msgstr "@see_also:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1435 +msgid "See Also manual page section. (Optional)" +msgstr "" +"Der Abschnitt »SEE ALSO« in den man-Pages (Unix-Handbuchseiten, optional)." + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1442 +msgid "@arg:" +msgstr "@arg:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1444 +msgid "Argument(s) passed to the program and their description. (Optional)" +msgstr "" +"Argument(e), die dem Programm übergeben wurden, und die zugehörige " +"Beschreibung (optional)." + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1451 +msgid "Description:" +msgstr "Description:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1453 +msgid "A longer description of the program." +msgstr "Eine ausführlichere Beschreibung des Programms." + +#. (itstool) path: listitem/para +#: C/index.docbook:1462 +msgid "Specificy what value(s) the program returns. (Optional)" +msgstr "Geben Sie an, welche Wert(e) das Programm zurück gibt (optional)." + +#. (itstool) path: sect2/title +#: C/index.docbook:1471 +msgid "Example of program documentation." +msgstr "Beispiel einer Programmdokumentation." + +#. (itstool) path: example/title +#: C/index.docbook:1472 +msgid "Program documentation block" +msgstr "Programm-Dokumentationsblock" + +# Würde ich nicht übersetzen. Ein Entwickler schreibt stets in Englisch, +# die Übersetzung ist unsere Sache. +#. (itstool) path: example/programlisting +#: C/index.docbook:1473 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * PROGRAM:test-program\n" +" * @short_description: A test program\n" +" * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*\n" +" * @see_also: test(1)\n" +" * @--arg1 *arg*: set arg1 to *arg*\n" +" * @--arg2 *arg*: set arg2 to *arg*\n" +" * @-v, --version: Print the version number\n" +" * @-h, --help: Print the help message\n" +" *\n" +" * Long description of program.\n" +" *\n" +" * Returns: Zero on success, non-zero on failure\n" +" */\n" +"int main(int argc, char *argv[])\n" +"{\n" +"\treturn 0;\n" +"}\n" +msgstr "" +"\n" +"/**\n" +" * PROGRAM:test-program\n" +" * @short_description: A test program\n" +" * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*\n" +" * @see_also: test(1)\n" +" * @--arg1 *arg*: set arg1 to *arg*\n" +" * @--arg2 *arg*: set arg2 to *arg*\n" +" * @-v, --version: Print the version number\n" +" * @-h, --help: Print the help message\n" +" *\n" +" * Long description of program.\n" +" *\n" +" * Returns: Zero on success, non-zero on failure\n" +" */\n" +"int main(int argc, char *argv[])\n" +"{\n" +"\treturn 0;\n" +"}\n" + +#. (itstool) path: sect1/title +#: C/index.docbook:1499 msgid "Useful DocBook tags" -msgstr "Nützliche DocBook-Tags" +msgstr "Nützliche DocBook-Markierungen" #. (itstool) path: sect1/para -#: C/index.docbook:1411 +#: C/index.docbook:1501 msgid "" "Here are some DocBook tags which are most useful when documenting the code." msgstr "" -"Nachfolgend finden Sie einige DocBook-Tags, die beim Dokumentieren von Code " -"nützlich sein können." +"Nachfolgend finden Sie einige DocBook-Markierungen, die beim Dokumentieren " +"von Code nützlich sein können." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1420 +#: C/index.docbook:1510 #, no-wrap msgid "" "\n" @@ -2393,7 +2540,7 @@ msgstr "" "<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1416 +#: C/index.docbook:1506 msgid "" "To link to another section in the GTK docs: <_:informalexample-1/> The " "linkend is the SGML/XML id on the top item of the page you want to link to. " @@ -2409,7 +2556,7 @@ msgstr "" "konform in »-« umgewandelt. " #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1433 +#: C/index.docbook:1523 #, no-wrap msgid "" "\n" @@ -2419,7 +2566,7 @@ msgstr "" "<function>...</function>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1430 +#: C/index.docbook:1520 msgid "" "To refer to an external function, e.g. a standard C function: <_:" "informalexample-1/>" @@ -2428,7 +2575,7 @@ msgstr "" "<_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1442 +#: C/index.docbook:1532 #, no-wrap msgid "" "\n" @@ -2448,7 +2595,7 @@ msgstr "" "</example>\n" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1453 +#: C/index.docbook:1543 #, no-wrap msgid "" "\n" @@ -2466,7 +2613,7 @@ msgstr "" "</informalexample>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1439 +#: C/index.docbook:1529 msgid "" "To include example code: <_:informalexample-1/> or possibly this, for very " "short code fragments which don't need a title: <_:informalexample-2/> For " @@ -2477,7 +2624,7 @@ msgstr "" "Außerdem unterstützt GTK-Doc auch eine Abkürzung: |[ ... ]|" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1472 +#: C/index.docbook:1562 #, no-wrap msgid "" "\n" @@ -2509,12 +2656,12 @@ msgstr "" "</itemizedlist>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1469 +#: C/index.docbook:1559 msgid "To include bulleted lists: <_:informalexample-1/>" msgstr "Für eine Liste mit Aufzählungszeichen: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1492 +#: C/index.docbook:1582 #, no-wrap msgid "" "\n" @@ -2532,14 +2679,14 @@ msgstr "" "</note>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1489 +#: C/index.docbook:1579 msgid "" "To include a note which stands out from the text: <_:informalexample-1/>" msgstr "" "Für eine nicht zum eigentlichen Text gehörende Notiz: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1505 +#: C/index.docbook:1595 #, no-wrap msgid "" "\n" @@ -2549,12 +2696,12 @@ msgstr "" "<type>unsigned char</type>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1502 +#: C/index.docbook:1592 msgid "To refer to a type: <_:informalexample-1/>" msgstr "Für einen Bezug zu einem Typ: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1514 +#: C/index.docbook:1604 #, no-wrap msgid "" "\n" @@ -2564,7 +2711,7 @@ msgstr "" "<structname>XFontStruct</structname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1511 +#: C/index.docbook:1601 msgid "" "To refer to an external structure (not one described in the GTK docs): <_:" "informalexample-1/>" @@ -2573,7 +2720,7 @@ msgstr "" "beschrieben wird): <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1523 +#: C/index.docbook:1613 #, no-wrap msgid "" "\n" @@ -2583,12 +2730,12 @@ msgstr "" "<structfield>len</structfield>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1520 +#: C/index.docbook:1610 msgid "To refer to a field of a structure: <_:informalexample-1/>" msgstr "Für einen Bezug zu einem Feld einer Struktur: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1532 +#: C/index.docbook:1622 #, no-wrap msgid "" "\n" @@ -2598,7 +2745,7 @@ msgstr "" "<classname>GtkWidget</classname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1529 +#: C/index.docbook:1619 msgid "" "To refer to a class name, we could possibly use: <_:informalexample-1/> but " "you'll probably be using #GtkWidget instead (to automatically create a link " @@ -2611,7 +2758,7 @@ msgstr "" "- lesen Sie die Abkürzungen)." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1543 +#: C/index.docbook:1633 #, no-wrap msgid "" "\n" @@ -2621,12 +2768,12 @@ msgstr "" "<emphasis>This is important</emphasis>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1540 +#: C/index.docbook:1630 msgid "To emphasize text: <_:informalexample-1/>" msgstr "Zum Hervorheben von Text: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1552 +#: C/index.docbook:1642 #, no-wrap msgid "" "\n" @@ -2636,12 +2783,12 @@ msgstr "" "<filename>/home/user/documents</filename>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1549 +#: C/index.docbook:1639 msgid "For filenames use: <_:informalexample-1/>" msgstr "Für Dateinamen: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1561 +#: C/index.docbook:1651 #, no-wrap msgid "" "\n" @@ -2651,17 +2798,17 @@ msgstr "" "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1558 +#: C/index.docbook:1648 msgid "To refer to keys use: <_:informalexample-1/>" msgstr "Für einen Bezug zu einem Schlüssel: <_:informalexample-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1571 +#: C/index.docbook:1661 msgid "Filling the extra files" msgstr "Füllen der zusätzlichen Dateien" #. (itstool) path: chapter/para -#: C/index.docbook:1573 +#: C/index.docbook:1663 msgid "" "There are a couple of extra files, that need to be maintained along with the " "inline source code comments: <package>.types, " @@ -2674,12 +2821,12 @@ msgstr "" "<package>-sections.txt." #. (itstool) path: sect1/title -#: C/index.docbook:1582 +#: C/index.docbook:1672 msgid "Editing the types file" msgstr "Bearbeiten der Typendatei" #. (itstool) path: sect1/para -#: C/index.docbook:1584 +#: C/index.docbook:1674 msgid "" "If your library or application includes GObjects, you want their signals, " "arguments/parameters and position in the hierarchy to be shown in the " @@ -2694,12 +2841,12 @@ msgstr "" "der Datei <package>.types aufzulisten." #. (itstool) path: example/title -#: C/index.docbook:1593 +#: C/index.docbook:1683 msgid "Example types file snippet" msgstr "Beispiel-Schnipsel einer Typen-Datei" #. (itstool) path: example/programlisting -#: C/index.docbook:1594 +#: C/index.docbook:1684 #, no-wrap msgid "" "\n" @@ -2719,8 +2866,7 @@ msgstr "" "gtk_arrow_get_type\n" #. (itstool) path: sect1/para -#: C/index.docbook:1605 -#, fuzzy +#: C/index.docbook:1695 msgid "" "Since GTK-Doc 1.8 gtkdoc-scan can generate this " "list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in " @@ -2730,15 +2876,16 @@ msgstr "" "Seit GTK-Doc 1.8 kann gtkdoc-scan diese Liste für " "Sie erstellen. Fügen Sie einfach »--rebuild-types« zu SCAN_OPTIONS in " "Makefile.am hinzu. Wenn Sie so vorgehen sollten Sie " -"nicht ??" +"weder Typen-Datei mit veröffentlichen noch diese unter Versionsverwaltung " +"stellen." #. (itstool) path: sect1/title -#: C/index.docbook:1614 +#: C/index.docbook:1704 msgid "Editing the master document" msgstr "Bearbeiten des Master-Dokuments" #. (itstool) path: sect1/para -#: C/index.docbook:1616 +#: C/index.docbook:1706 msgid "" "GTK-Doc produces documentation in DocBook SGML/XML. When processing the " "inline source comments, the GTK-Doc tools generate one documentation page " @@ -2751,15 +2898,7 @@ msgstr "" "Hauptdokument schließt diese ein und setzt sie in die passende Reihenfolge." #. (itstool) path: sect1/para -#: C/index.docbook:1623 -#, fuzzy -#| msgid "" -#| "While GTK-Doc creates a template master document for you, later run will " -#| "not touch it again. This means that one can freely structure the " -#| "documentation. That includes grouping pages and adding extra pages. GTK-" -#| "Doc has now a test suite, where also the master-document is recreated " -#| "from scratch. Its a good idea to look at this from time to time to see if " -#| "there are some new goodies introduced there." +#: C/index.docbook:1713 msgid "" "While GTK-Doc creates a template master document for you, later runs will " "not touch it again. This means that one can freely structure the " @@ -2768,16 +2907,16 @@ msgid "" "scratch. Its a good idea to look at this from time to time to see if there " "are some new goodies introduced there." msgstr "" -"Während GTK-Doc ein Vorlagen-Hauptdokument für Sie erstellt wird eine " -"spätere Ausführung es nicht mehr verändern. Dies bedeutet, dass man das " -"Dokument beliebig strukturieren kann. Dies schließt Gruppieren von Seiten " +"Während GTK-Doc ein Vorlagen-Hauptdokument für Sie erstellt, wird eine " +"spätere Ausführung es nicht mehr verändern. Das bedeutet, dass Sie das " +"Dokument beliebig strukturieren können. Dies schließt Gruppieren von Seiten " "und Hinzufügen von zusätzlichen Seiten ein. GTK-Doc hat eine neue Test-" -"Garnitur, wo auch das Hauptdokument von Neuem erstellt wird. Es ist ratsam " -"sich diese von Zeit zu Zeit anzusehen und zu schauen, ob dort einige " +"Suite, wo auch das Hauptdokument von Grund auf neu erstellt wird. Es ist " +"ratsam, sich diese von Zeit zu Zeit anzusehen und zu schauen, ob dort einige " "Neuigkeiten eingeführt werden." #. (itstool) path: tip/para -#: C/index.docbook:1633 +#: C/index.docbook:1723 msgid "" "Do not create tutorials as extra documents. Just write extra chapters. The " "benefit of directly embedding the tutorial for your library into the API " @@ -2793,7 +2932,7 @@ msgstr "" "die gleichen Aktualisierungen erfährt wie die Bibliothek selbst." #. (itstool) path: sect1/para -#: C/index.docbook:1642 +#: C/index.docbook:1732 msgid "" "So what are the things to change inside the master document? For a start is " "only a little. There are some placeholders (text in square brackets) there " @@ -2804,12 +2943,12 @@ msgstr "" "beachten sollten." #. (itstool) path: example/title -#: C/index.docbook:1649 +#: C/index.docbook:1739 msgid "Master document header" msgstr "Kopfzeile des Master-Dokuments" #. (itstool) path: example/programlisting -#: C/index.docbook:1650 +#: C/index.docbook:1740 #, no-wrap msgid "" "\n" @@ -2839,48 +2978,52 @@ msgstr "" " <title>[Insert title here]</title>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1666 +#: C/index.docbook:1756 msgid "" "In addition a few option elements are created in commented form. You can " "review these and enable them as you like." msgstr "" +"Zusätzlich werden einige Optionselemente in Kommentarform erstellt. Sie " +"können sich diese anschauen und aktivieren, wenn Sie wollen." #. (itstool) path: example/title -#: C/index.docbook:1672 -#, fuzzy -#| msgid "Editing the master document" +#: C/index.docbook:1762 msgid "Optional part in the master document" -msgstr "Bearbeiten des Master-Dokuments" +msgstr "Optionaler Teil im Master-Dokument" #. (itstool) path: example/programlisting -#: C/index.docbook:1673 +#: C/index.docbook:1763 #, no-wrap msgid "" "\n" " <!-- enable this when you use gobject introspection annotations\n" " <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n" -" --> \n" +" -->\n" msgstr "" "\n" -" <!-- enable this when you use gobject introspection annotations\n" +" <!-- aktivieren Sie dieses, wenn sie gobject introspection-Anmerkungen verwenden\n" " <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n" " --> \n" #. (itstool) path: sect1/para -#: C/index.docbook:1681 +#: C/index.docbook:1771 msgid "" "Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind " "you of newly generated xml files that are not yet included into the doc." msgstr "" +"Schlussendlich müssen Sie einen neuen Abschnitt explizit einfügen, sobald " +"Sie einen öffnen. Das Werkzeug gtkdoc-check erinnert Sie an neu erzeugte XML-Dateien, die " +"in der Dokumentation noch nicht erfasst sind." #. (itstool) path: example/title -#: C/index.docbook:1689 C/index.docbook:1724 +#: C/index.docbook:1779 C/index.docbook:1814 msgid "Including generated sections" -msgstr "" +msgstr "Einbeziehen erzeugter Abschnitte" #. (itstool) path: example/programlisting -#: C/index.docbook:1690 +#: C/index.docbook:1780 #, no-wrap msgid "" "\n" @@ -2896,12 +3039,12 @@ msgstr "" " ...\n" #. (itstool) path: sect1/title -#: C/index.docbook:1702 +#: C/index.docbook:1792 msgid "Editing the section file" msgstr "Bearbeiten der Abschnittsdatei" #. (itstool) path: sect1/para -#: C/index.docbook:1704 +#: C/index.docbook:1794 msgid "" "The section file is used to organise the documentation output by GTK-Doc. " "Here one specifies which symbol belongs to which module or class and control " @@ -2912,29 +3055,26 @@ msgstr "" "welcher Klasse gehört und regelt die Sichtbarkeit (öffentlich oder privat)." #. (itstool) path: sect1/para -#: C/index.docbook:1710 -#, fuzzy -#| msgid "" -#| "The section file is a plain text file with XML-like syntax (using tags). " -#| "Blank lines are ignored and lines starting with a '#' are treated as " -#| "comment lines." +#: C/index.docbook:1800 msgid "" "The section file is a plain text file with tags delimiting sections. Blank " "lines are ignored and lines starting with a '#' are treated as comment lines." msgstr "" -"Die Abschnittsdatei ist eine reine Textdatei mit XML-ähnlicher Syntax (mit " -"Tags). Leere Zeilen werden ignoriert und Zeilen, die mit »#« beginnen, " -"werden als Kommentarzeilen behandelt." +"Die Abschnittsdatei ist eine reine Textdatei mit Markierungen, welche die " +"Abschnitte voneinander trennen. Leere Zeilen werden ignoriert und Zeilen, " +"die mit »#« beginnen, werden als Kommentarzeilen behandelt." #. (itstool) path: note/para -#: C/index.docbook:1717 +#: C/index.docbook:1807 msgid "" "While the tags make the file look like xml, it is not. Please do not close " "tags like <SUBSECTION>." msgstr "" +"Zwar lassen die Markierungen die Datei wie XML erscheinen, doch der Schein " +"trügt. Bitte schließen Sie keine Markierungen wie <SUBSECTION>." #. (itstool) path: example/programlisting -#: C/index.docbook:1725 +#: C/index.docbook:1815 #, no-wrap msgid "" "\n" @@ -2966,18 +3106,7 @@ msgstr "" "</SECTION>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1742 -#, fuzzy -#| msgid "" -#| "The <FILE> ... </FILE> tag is used to specify the file name, " -#| "without any suffix. For example, using '<FILE>gnome-config</" -#| "FILE>' will result in the section declarations being output in the " -#| "template file tmpl/gnome-config.sgml, which will be " -#| "converted into the DocBook SGML/XML file sgml/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)." +#: C/index.docbook:1832 msgid "" "The <FILE> ... </FILE> tag is used to specify the file name, " "without any suffix. For example, using '<FILE>gnome-config</" @@ -2989,18 +3118,18 @@ msgid "" "title, or for GObjects it is based on the GObjects class name converted to " "lower case)." msgstr "" -"Das Tag <FILE> ... </FILE> wird verwendet, um den Dateinamen " -"ohne Suffix anzugeben. Zum Beispiel wird »<FILE>gnome-config</" -"FILE>« dazu führen, dass der Deklarationsabschnitt in die Vorlage-Datei " -"tmpl/gnome-config.sgml ausgegeben wird, welche in die " -"DocBook SGML/XML-Datei sgml/gnome-config.sgml oder die " -"DocBook XML-Datei xml/gnome-config.xml umgewandelt " -"wird. (Der Name der HTML-Datei basiert auf dem Modulnamen und dem " -"Abschnittstitel. Für GObject basiert er auf dem GObjekt-Klassennamen in " +"Die Markierung <FILE> ... </FILE> wird verwendet, um den " +"Dateinamen ohne Suffix anzugeben. Zum Beispiel wird »<FILE>gnome-" +"config</FILE>« dazu führen, dass der Deklarationsabschnitt in die " +"Vorlage-Datei tmpl/gnome-config.sgml ausgegeben wird, " +"welche in die DocBook-XML-Datei sgml/gnome-config.sgml " +"oder die DocBook-XML-Datei xml/gnome-config.xml " +"umgewandelt wird. (Der Name der HTML-Datei basiert auf dem Modulnamen und " +"dem Abschnittstitel. Für GObject basiert er auf dem GObject-Klassennamen in " "Kleinbuchstaben)." #. (itstool) path: sect1/para -#: C/index.docbook:1754 +#: C/index.docbook:1844 msgid "" "The <TITLE> ... </TITLE> tag is used to specify the title of the " "section. It is only useful before the templates (if used) are initially " @@ -3013,8 +3142,7 @@ msgstr "" "das SECTION-Kommentar in den Quellen einsetzt, ist dies überflüssig." #. (itstool) path: sect1/para -#: C/index.docbook:1761 -#, fuzzy +#: C/index.docbook:1851 msgid "" "You can group items in the section by using the <SUBSECTION> tag. " "Currently it outputs a blank line between subsections in the synopsis " @@ -3029,17 +3157,24 @@ msgid "" "Whether you would place GObject and GObjectClass like structs in public or " "Standard section depends if they have public entries (variables, vmethods)." msgstr "" -"Sie können Objekte im Abschnitt mittels des Tag <SUBSECTION> " +"Sie können Objekte im Abschnitt mittels der Markierung <SUBSECTION> " "gruppieren. Derzeit gibt es eine Leerzeile zwischen Unterabschnitten im " "Inhaltsangabe-Abschnitt aus. Sie können auch <SUBSECTION Standard> für " "Standard GObject-Deklarationen verwenden (z.B. Funktionen wie " "g_object_get_type und Makros wie G_OBJECT(), G_IS_OBJECT() etc.). Derzeit " -"werden diese nicht in die Dokumentation aufgenommen. Die können auch <" +"werden diese nicht in die Dokumentation aufgenommen. Sie können auch <" "SUBSECTION Private> für private Deklarationen verwenden, welche nicht " -"ausgegeben werden …" +"ausgegeben werden. Dies ist eine praktische Möglichkeit, Warnmeldungen " +"bezüglich ungenutzter Deklarationen zu vermeiden. Wenn Ihre Bibliothek " +"private Typen enthält, die nicht in der Objekthierarchie und der Liste der " +"implementierten oder benötigten Schnittstellen erscheinen sollen, fügen Sie " +"diese zu einem »Private«-Unterabschnitt hinzu. Ob Sie GObject oder " +"GObjectClass wie Structs im öffentlichen oder im Standardabschnitt " +"einsetzen, hängt davon ab, ob öffentliche Einträge vorhanden sind " +"(Variablen, vmethods)." #. (itstool) path: sect1/para -#: C/index.docbook:1780 +#: C/index.docbook:1870 msgid "" "You can also use <INCLUDE> ... </INCLUDE> to specify the " "#include files which are shown in the synopsis sections. It contains a comma-" @@ -3055,12 +3190,12 @@ msgstr "" "Abschnitts festlegen, wirkt es nur in diesem Abschnitt." #. (itstool) path: chapter/title -#: C/index.docbook:1794 +#: C/index.docbook:1884 msgid "Controlling the result" msgstr "Überprüfung des Ergebnisses" #. (itstool) path: chapter/para -#: C/index.docbook:1796 +#: C/index.docbook:1886 msgid "" "A GTK-Doc run generates report files inside the documentation directory. The " "generated files are named: <package>-undocumented.txt<package>-undocumented.txt file starts with " "the documentation coverage summary. Below are two sections divided by blank " @@ -3092,7 +3227,7 @@ msgstr "" "Dokumentation haben, aber z.B. ein neuer Parameter hinzugefügt worden ist." #. (itstool) path: chapter/para -#: C/index.docbook:1814 +#: C/index.docbook:1904 msgid "" "The <package>-undeclared.txt file lists symbols " "given in the <package>-sections.txt but not found " @@ -3104,7 +3239,7 @@ msgstr "" "geschrieben wurden." #. (itstool) path: chapter/para -#: C/index.docbook:1821 +#: C/index.docbook:1911 msgid "" "The <package>-unused.txt file lists symbol names, " "where the GTK-Doc scanner has found documentation, but does not know where " @@ -3118,7 +3253,7 @@ msgstr "" "wurde." #. (itstool) path: tip/para -#: C/index.docbook:1829 +#: C/index.docbook:1919 msgid "" "Enable or add the line in Makefile." "am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during " @@ -3130,7 +3265,7 @@ msgstr "" "ausgeführt." #. (itstool) path: chapter/para -#: C/index.docbook:1836 +#: C/index.docbook:1926 msgid "" "One can also look at the files produced by the source code scanner: " "<package>-decl-list.txt and <" @@ -3147,18 +3282,7 @@ msgstr "" "kann man prüfen, ob diese Datei es enthält." #. (itstool) path: chapter/para -#: C/index.docbook:1845 -#, fuzzy -#| msgid "" -#| "If the project is GObject based, one can also look into the files " -#| "produced by the object scanner: <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, by running it as GTK_DOC_KEEP_INTERMEDIATE=1 make." +#: C/index.docbook:1935 msgid "" "If the project is GObject based, one can also look into the files produced " "by the object scanner: <package>.args.txt, " @@ -3174,43 +3298,41 @@ msgstr "" "filename>, <package>.hierarchy.txt, <" "package>.interfaces.txt, <package>." "prerequisites.txt und <package>.signals.txt. Falls es in irgendeiner Datei fehlende Symbole gibt, kann man " -"gtkdoc anweisen die zwischenläufige Scanner-Datei zur weiteren Analyse zu " -"behalten, indem man GTK_DOC_KEEP_INTERMEDIATE=1 make " -"ausführt." +"filename>. Falls in irgendeiner Datei Symbole fehlen, können Sie Gtk-Doc " +"anweisen, die zwischenläufige Scanner-Datei zur weiteren Analyse zu " +"behalten, indem Sie GTK_DOC_KEEP_INTERMEDIATE=1 make " +"ausführen." #. (itstool) path: chapter/title -#: C/index.docbook:1860 +#: C/index.docbook:1950 msgid "Modernizing the documentation" msgstr "Die Dokumentation modernisieren" #. (itstool) path: chapter/para -#: C/index.docbook:1862 +#: C/index.docbook:1952 msgid "" "GTK-Doc has been around for quite some time. In this section we list new " "features together with the version since when it is available." msgstr "" +"GTK-Doc ist schon seit längerer Zeit verfügbar. In diesem Abschnitt zeigen " +"wir neue Features und die Version, mit der sie eingeführt wurden." #. (itstool) path: sect1/title -#: C/index.docbook:1868 +#: C/index.docbook:1958 msgid "GTK-Doc 1.9" msgstr "GTK-Doc 1.9" #. (itstool) path: sect1/para -#: C/index.docbook:1870 -#, fuzzy -#| msgid "" -#| "Is the new page xi:included from <package>-docs.{xml,sgml}" -#| "." +#: C/index.docbook:1960 msgid "" "When using xml instead of sgml, one can actually name the master document " "<package>-docs.xml." msgstr "" -"Ist die neue Seite xi:eingebunden von <package>-docs.{xml," -"sgml}?" +"Wenn Sie XML anstatt SGML verwenden, können Sie das Hauptdokument " +"<package>-docs.xml nennen." #. (itstool) path: sect1/para -#: C/index.docbook:1875 +#: C/index.docbook:1965 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3221,9 +3343,18 @@ msgid "" "simple as running meld <package>-decl-list.txt <package>-" "sections.txt." msgstr "" +"Diese Version unterstützt " +"in Makefile.am. Wenn dies aktiviert ist, wird die Datei " +"<package>-sections.txt automatisch erzeugt und " +"kann aus der Versionsverwaltung entfernt werden. Dies funktioniert nur " +"sauber in Projekten, die eine strikt »reguläre« Struktur haben (zum Beispiel " +"erzeugt jedes .{c,h}-Paar einen neuen Abschnitt). In einem solch sauber " +"organisierten Projekt kann dann mit dem Befehl meld <package>-" +"decl-list.txt <package>-sections.txt eine manuell verwaltete " +"Abschnittsdatei sehr einfach aktualisiert werden." #. (itstool) path: sect1/para -#: C/index.docbook:1886 +#: C/index.docbook:1976 msgid "" "Version 1.8 already introduced the syntax for documenting sections in the " "sources instead of the separate files under configure.ac and you are done." msgstr "" +"In Version 1.8 wurde bereits die Syntax für Dokumentationsabschnitte in den " +"Quelltexten anstelle von separaten Dateien unter tmpl eingeführt. Diese Version fügt Optionen zur Umstellung " +"des gesamten Dokumentationsmoduls auf das neue Verhalten hinzu, so dass kein " +"zusätzlicher tmpl-Erstellungsschritt mehr nötig ist. Dazu dient die Option " +" in configure.ac. " +"Wenn Sie keinen Ordner namens tmpl " +"unter Versionsverwaltung haben und noch nicht umgestellt haben, fügen Sie " +"einfach die Option zu configure.ac hinzu, und die Sache " +"ist erledigt." #. (itstool) path: sect1/title -#: C/index.docbook:1898 +#: C/index.docbook:1988 msgid "GTK-Doc 1.10" msgstr "GTK-Doc 1.10" #. (itstool) path: sect1/para -#: C/index.docbook:1900 +#: C/index.docbook:1990 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3250,19 +3391,26 @@ msgid "" "IGNORE_HFILES in Makefile.am for " "code that is build conditionally." msgstr "" +"Diese Version unterstützt in " +"Makefile.am. Wenn dies aktiviert ist, wird die Datei " +"<package>.types automatisch erzeugt und kann aus " +"der Versionsverwaltung entfernt werden. Dieses Feature erfordert die " +"Einrichtung von IGNORE_HFILES in Makefile.am für Code, der nur unter bestimmten Bedingungen erstellt werden " +"soll." #. (itstool) path: sect1/title -#: C/index.docbook:1911 +#: C/index.docbook:2001 msgid "GTK-Doc 1.16" msgstr "GTK-Doc 1.16" #. (itstool) path: example/title -#: C/index.docbook:1917 +#: C/index.docbook:2007 msgid "Enable gtkdoc-check" msgstr "gtkdoc-check einschalten" #. (itstool) path: example/programlisting -#: C/index.docbook:1918 +#: C/index.docbook:2008 #, no-wrap msgid "" "\n" @@ -3282,39 +3430,49 @@ msgstr "" "endif\n" #. (itstool) path: sect1/para -#: C/index.docbook:1913 +#: C/index.docbook:2003 msgid "" "This version includes a new tool called gtkdoc-check. This tool can run a " "set of sanity checks on your documentation. It is enabled by adding these " "lines to the end of Makefile.am. <_:example-1/>" msgstr "" +"Diese Version führt ein neues Werkzeug namens gtkdoc-check ein. Damit können " +"Sie eine Reihe von Plausibilitätsprüfungen auf Ihre Dokumentation anwenden. " +"Um es zu aktivieren, fügen Sie folgende Zeilen am Ende von " +"Makefile.am hinzu. <_:example-1/>" #. (itstool) path: sect1/title -#: C/index.docbook:1931 +#: C/index.docbook:2021 msgid "GTK-Doc 1.20" msgstr "GTK-Doc 1.20" #. (itstool) path: sect1/para -#: C/index.docbook:1933 +#: C/index.docbook:2023 msgid "" "Version 1.18 brought some initial markdown support. Using markdown in doc " "comments is less intrusive than writing docbook xml. This version improves a " "lot on this and add a lot more styles. The section that explains the comment syntax has all the details." msgstr "" +"In Version 1.18 wurde erstmals Unterstützung für Markdown eingeführt. Die " +"Verwendung von Markdown in Dokumentationskommentaren ist weniger aufwändig " +"als das Schreiben von DocBook XML. Diese Version bringt diesbezüglich " +"wesentliche Verbesserungen und fügt zahlreiche weitere Stile hinzu. Alle " +"Details hierzu finden Sie im Abschnitt zur Kommentarsyntax." #. (itstool) path: sect1/title -#: C/index.docbook:1943 +#: C/index.docbook:2033 msgid "GTK-Doc 1.25" msgstr "GTK-Doc 1.25" #. (itstool) path: example/title -#: C/index.docbook:1953 +#: C/index.docbook:2043 msgid "Use pre-generated entities" -msgstr "" +msgstr "Vorerzeugte Entitäten verwenden" #. (itstool) path: example/programlisting -#: C/index.docbook:1954 +#: C/index.docbook:2044 #, no-wrap msgid "" "\n" @@ -3356,7 +3514,7 @@ msgstr "" " </bookinfo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1945 +#: C/index.docbook:2035 msgid "" "The makefiles shipped with this version generate an entity file at " "xml/gtkdocentities.ent, containing entities for e.g. " @@ -3366,14 +3524,22 @@ msgid "" "also be used in all generated files, GTK-Doc will use the same xml header in " "generated xml files. <_:example-1/>" msgstr "" +"Die in dieser Version enthaltenen Make-Steuerdateien erzeugen die " +"Entitätsdatei 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. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1979 +#: C/index.docbook:2069 msgid "Documenting other interfaces" msgstr "Dokumentieren anderer Schnittstellen" #. (itstool) path: chapter/para -#: C/index.docbook:1981 +#: C/index.docbook:2071 msgid "" "So far we have been using GTK-Doc to document the API of code. The next " "sections contain suggestions how the tools can be used to document other " @@ -3384,12 +3550,12 @@ msgstr "" "Werkzeuge zum Dokumentieren anderer Schnittstellen eingesetzt werden können." #. (itstool) path: sect1/title -#: C/index.docbook:1988 +#: C/index.docbook:2078 msgid "Command line options and man pages" msgstr "Befehlszeilenoptionen und Handbuchseiten" #. (itstool) path: sect1/para -#: C/index.docbook:1990 +#: C/index.docbook:2080 msgid "" "As one can generate man pages for a docbook refentry as well, it sounds like " "a good idea to use it for that purpose. This way the interface is part of " @@ -3401,13 +3567,12 @@ msgstr "" "kostenfrei die man-Hilfeseite." #. (itstool) path: sect2/title -#: C/index.docbook:1997 +#: C/index.docbook:2087 msgid "Document the tool" msgstr "Dokumentieren des Werkzeuges" #. (itstool) path: sect2/para -#: C/index.docbook:1999 -#, fuzzy +#: C/index.docbook:2089 msgid "" "Create one refentry file per tool. Following our example we would call it meep/" @@ -3417,22 +3582,22 @@ msgid "" msgstr "" "Erstellen Sie eine Referenzeintragsdatei pro Werkzeug. In unserem Beispiel nennen wir sie meep/" -"docs/reference/meeper/meep.xml. Für die zu verwendenden XML-Tags " -"können Sie die generierte Datei im XML-Verzeichnis oder Beispiele (z.B. in " -"glib) ansehen." +"docs/reference/meeper/meep.xml. Für die zu verwendenden XML-" +"Markierungen können Sie die generierte Datei im XML-Unterordner oder " +"Beispiele (z.B. in glib) ansehen." #. (itstool) path: sect2/title -#: C/index.docbook:2009 +#: C/index.docbook:2099 msgid "Adding the extra configure check" msgstr "Hinzufügen der zusätzlichen Configure-Überprüfungen" #. (itstool) path: example/title -#: C/index.docbook:2012 C/index.docbook:2030 +#: C/index.docbook:2102 C/index.docbook:2120 msgid "Extra configure checks" msgstr "Zusätzliche Configure-Überprüfungen" #. (itstool) path: example/programlisting -#: C/index.docbook:2013 +#: C/index.docbook:2103 #, no-wrap msgid "" "\n" @@ -3454,12 +3619,12 @@ msgstr "" "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" #. (itstool) path: sect2/title -#: C/index.docbook:2027 +#: C/index.docbook:2117 msgid "Adding the extra makefile rules" msgstr "Hinzufügen der zusätzlichen Makefile-Regeln" #. (itstool) path: example/programlisting -#: C/index.docbook:2031 +#: C/index.docbook:2121 #, no-wrap msgid "" "\n" @@ -3495,12 +3660,12 @@ msgstr "" "EXTRA_DIST += meep.xml\n" #. (itstool) path: sect1/title -#: C/index.docbook:2053 +#: C/index.docbook:2143 msgid "DBus interfaces" msgstr "DBus-Schnittstellen" #. (itstool) path: sect1/para -#: C/index.docbook:2055 +#: C/index.docbook:2145 msgid "" "(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" @@ -3509,27 +3674,27 @@ msgstr "" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" #. (itstool) path: chapter/title -#: C/index.docbook:2064 +#: C/index.docbook:2154 msgid "Frequently asked questions" msgstr "Häufig gestellte Fragen" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2068 +#: C/index.docbook:2158 msgid "Question" msgstr "Frage" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2069 +#: C/index.docbook:2159 msgid "Answer" msgstr "Antwort" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2071 +#: C/index.docbook:2161 msgid "No class hierarchy." msgstr "Keine Klassenhierarchie." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2072 +#: C/index.docbook:2162 msgid "" "The objects xxx_get_type() function has not been " "entered into the <package>.types file." @@ -3538,12 +3703,12 @@ msgstr "" "die Datei <package>.types eingegeben." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2078 +#: C/index.docbook:2168 msgid "Still no class hierarchy." msgstr "Noch immer keine Klassenhierarchie." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2079 +#: C/index.docbook:2169 msgid "" "Missing or wrong naming in <package>-sections.txt " "file (see Erklärung)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2085 +#: C/index.docbook:2175 msgid "Damn, I have still no class hierarchy." msgstr "Verdammt, ich habe immer noch keine Klassenhierarchie." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2086 +#: C/index.docbook:2176 msgid "" "Is the object name (name of the instance struct, e.g. GtkWidget) part of the normal section (don't put this into Standard or Private " @@ -3569,12 +3734,12 @@ msgstr "" "Teil des normalen Abschnitts (nicht in den Standard- oder Unterabschnitte)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2093 +#: C/index.docbook:2183 msgid "No symbol index." msgstr "Kein Symbolindex." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2094 +#: C/index.docbook:2184 msgid "" "Does the <package>-docs.{xml,sgml} contain a " "index that xi:includes the generated index?" @@ -3583,12 +3748,12 @@ msgstr "" "der den erstellten Index xi:enthält?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2100 +#: C/index.docbook:2190 msgid "Symbols are not linked to their doc-section." msgstr "Symbole werden nicht mit deren Dokumentationsbschnitt verknüpft." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2101 +#: C/index.docbook:2191 msgid "" "Is the doc-comment using the correct markup (added #,% or ())? Check if the " "gtkdoc-fixxref warns about unresolvable xrefs." @@ -3597,12 +3762,12 @@ msgstr "" "»()«)? Prüfen Sie, ob gtkdoc-fixxref wegen nicht auflösbarer xrefs warnt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2107 +#: C/index.docbook:2197 msgid "A new class does not appear in the docs." msgstr "Eine neue Klasse erscheint nicht in der Dokumentation." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2108 +#: C/index.docbook:2198 msgid "" "Is the new page xi:included from <package>-docs.{xml,sgml}." @@ -3611,12 +3776,12 @@ msgstr "" "sgml}?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2114 +#: C/index.docbook:2204 msgid "A new symbol does not appear in the docs." msgstr "Ein neues Symbol erscheint nicht in der Dokumentation." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2115 +#: C/index.docbook:2205 msgid "" "Is the doc-comment properly formatted. Check for spelling mistakes in the " "begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable " @@ -3630,12 +3795,12 @@ msgstr "" "Abschnitt gelistet ist." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2123 +#: C/index.docbook:2213 msgid "A type is missing from the class hierarchy." msgstr "Ein Typ fehlt in der Klassenhierarchie." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2124 +#: C/index.docbook:2214 msgid "" "If the type is listed in <package>.hierarchy but " "not in xml/tree_index.sgml then double check that the " @@ -3651,12 +3816,12 @@ msgstr "" "sie nicht angezeigt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2133 +#: C/index.docbook:2223 msgid "I get foldoc links for all gobject annotations." msgstr "Ich erhalte foldoc-Verweise für alle gobjekt-Anmerkungen." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2134 +#: C/index.docbook:2224 msgid "" "Check that xml/annotation-glossary.xml is xi:included " "from <package>-docs.{xml,sgml}." @@ -3665,14 +3830,14 @@ msgstr "" "<package>-docs.{xml,sgml} xi:eingebunden ist." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2142 +#: C/index.docbook:2232 msgid "Parameter described in source code comment block but does not exist" msgstr "" "Parameter wird im Kommentarblock des Quellcodes beschrieben, aber existiert " "nicht" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2143 +#: C/index.docbook:2233 msgid "" "Check if the prototype in the header has different parameter names as in the " "source." @@ -3681,13 +3846,12 @@ msgstr "" "Header unterschiedlich sind" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2148 -#, fuzzy +#: C/index.docbook:2238 msgid "multiple \"IDs\" for constraint linkend: XYZ" -msgstr "mehrfache »ID« für ?" +msgstr "Mehrfache »IDs« für »constraint linkend: XYZ«" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2149 +#: C/index.docbook:2239 msgid "" "Symbol XYZ appears twice in <package>-sections.txt file." @@ -3696,19 +3860,21 @@ msgstr "" "sections.txt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2152 +#: C/index.docbook:2242 msgid "" "Element typename in namespace '' encountered in para, but no template " "matches." msgstr "" +"Element-Typname im Namensraum '' in einem Abschnitt, der keiner Vorlage " +"entspricht." #. (itstool) path: chapter/title -#: C/index.docbook:2159 +#: C/index.docbook:2249 msgid "Tools related to gtk-doc" msgstr "Werkzeuge mit Bezug zu gtk-doc" #. (itstool) path: chapter/para -#: C/index.docbook:2161 +#: C/index.docbook:2251 msgid "" "GtkDocPlugin - a Trac " "GTK-Doc integration plugin, that adds API docs to a trac site and " @@ -3719,7 +3885,7 @@ msgstr "" "Seite hinzufügt und die trac-Suche einbindet." #. (itstool) path: chapter/para -#: C/index.docbook:2166 +#: C/index.docbook:2256 msgid "" "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " "tags in the API to determine the minimum required version." @@ -4569,12 +4735,6 @@ msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:527 C/fdl-appendix.xml:527 -#, fuzzy -#| msgid "" -#| "You may extract a single document from such a collection, and dispbibute " -#| "it individually under this License, provided you insert a copy of this " -#| "License into the extracted document, and follow this License in all other " -#| "respects regarding verbatim copying of that document." msgid "" "You may extract a single document from such a collection, and distribute it " "individually under this License, provided you insert a copy of this License " @@ -5741,6 +5901,37 @@ msgstr "" "wie der <_:ulink-1/>, zu veröffentlichen, um ihren Gebrauch in freier " "Software zu erlauben." +#~ 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 "" +#~ "Erstellen der »Vorlage«-Dateien. gtkdoc-" +#~ "mktmpl erstellt einige Dateien im Unterordner tmpl/ mit Hilfe der Informationen aus dem " +#~ "ersten Schritt. (Bedenken Sie, dass dies wiederholt ausgeführt werden " +#~ "kann. Es wird versucht sicherzustellen, dass keine Dokumentation jemals " +#~ "verloren geht.)" + +#~ msgid "" +#~ "Since GTK-Doc 1.9 the templates can be avoided. We encourage people to " +#~ "keep documentation in the code. 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 "" +#~ "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. Falls Sie niemals Dateien im " +#~ "Vorlagenordner manuell bearbeitet oder aus älteren GTK-Doc-Versionen " +#~ "importiert haben, sollten Sie den Ordner löschen, z.B. in der " +#~ "Versionsverwaltung." + #~ msgid "1.18.1" #~ msgstr "1.18.1" diff --git a/help/manual/de/fdl-appendix.xml b/help/manual/de/fdl-appendix.xml index 6a58e47..4cf9ad9 100644 --- a/help/manual/de/fdl-appendix.xml +++ b/help/manual/de/fdl-appendix.xml @@ -192,13 +192,7 @@ 6. SAMMLUNGEN VON DOKUMENTEN Sie dürfen eine Sammlung erstellen, die aus dem Dokument und anderen, unter dieser Lizenz veröffentlichten Dokumenten besteht, und die individuellen Kopien der Lizenz in den einzelnen Dokumenten durch eine einzige Kopie ersetzen, die sich in der Sammlung befindet, vorausgesetzt, Sie folgen den Regeln dieser Lizenz für wortwörtliches Kopieren jedes dieser Dokumente in jeglicher Hinsicht. - - 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. - + Sie dürfen ein einzelnes Dokument aus einer solchen Sammlung heraustrennen, und es individuell unter dieser Lizenz verteilen, vorausgesetzt, Sie fügen eine Kopie dieser Lizenz in das herausgetrennte Dokument ein und folgen der Lizenz in jeglicher Hinsicht bezüglich dem wortwörtlichen Kopieren des Dokuments. diff --git a/help/manual/de/index.docbook b/help/manual/de/index.docbook index 05ad127..59ca772 100644 --- a/help/manual/de/index.docbook +++ b/help/manual/de/index.docbook @@ -34,7 +34,8 @@ - 1.24.1 30. Mai 2015 ss Entwicklerversion + 1.25.1 21. März 2016 ss Entwicklerversion + 1.25 21. März 2015 ss Fehlerbehebungen, Test-Cleanups 1.24 29. Mai 2015 sk Fehlerbehebungen 1.23 17. Mai 2015 sk Fehlerbehebungen 1.22 7. Mai 2015 sk Fehlerbehebungen, veraltete Funktionen verworfen @@ -62,6 +63,8 @@ 2009-2013 + 2016 + Mario Blättermann @@ -77,6 +80,10 @@ 2015 + 2016 + + 2017 + Christian Kirbach @@ -116,33 +123,9 @@ - Erstellen der »Vorlage«-Dateien. gtkdoc-mktmpl erstellt einige Dateien im Unterordner tmpl/ mit Hilfe der Informationen aus dem ersten Schritt. (Bedenken Sie, dass dies wiederholt ausgeführt werden kann. Es wird versucht sicherzustellen, dass keine Dokumentation jemals verloren geht.) - - 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. 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. - - - - - - 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. - - - 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. - - - Files in xml/ and - html/ directories are always - overwritten. One should never edit them directly. - + Erstellen des SGML/XML und HTML/PDF. gtkdoc-mkdb wandelt die Vorlagen-Dateien in XML-Dateien in den Unterordner xml/ um. Wenn der Quellcode Dokumentation über Funktionen mittels speziellen Kommentarblöcken enthält, so wird diese hier eingepflegt. Wenn keine tmpl-Dateien eingesetzt werden, so wird nur Dokumentation von den Quell- und introspection-Daten gelesen. + gtkdoc-mkhtml konvertiert die XML-Dateien in HTML-Dateien im Unterordner html/. Ebenso konvertiert gtkdoc-mkpdf die XML-Dateien in ein PDF-Dokument namens <package>.pdf. + Dateien in xml/ und html/-Ordnern werden immer überschrieben. Niemand sollte diese direkt bearbeiten. @@ -161,10 +144,7 @@ xsltproc - der xslt-Verarbeiter von libxslt xmlsoft.org/XSLT/ docbook-xsl - die docbook xsl-Stilvorlagen sourceforge.net/projects/docbook/files/docbook-xsl Python - optional - für gtkdoc-depscan - - One of source-highlight, highlight or - vim - optional - used for syntax highlighting of examples - + source-highlight, highlight oder vim - optional - für Syntax-Hervorhebung von Beispielen @@ -173,10 +153,7 @@ (FIXME) - - (History, authors, web pages, mailing list, license, future plans, - comparison with other similar systems.) - + (Geschichte, Autoren, Webseiten, Mailingliste, Lizenz, Zukunftspläne, Vergleich mit ähnlichen Systemen) @@ -252,7 +229,12 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) 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. - 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. + + 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. + Vorbereitung für gtkdocize @@ -261,26 +243,13 @@ AC_CONFIG_MACRO_DIR(m4) - - After all changes to configure.ac are made, update - the configure file. This can be done by re-running - autoreconf -i or autogen.sh. - + 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. Integration in automake - - 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. - + 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. 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. @@ -325,19 +294,8 @@ make Integration in Versionsverwaltungssysteme - - 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. - + 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. @@ -365,20 +323,12 @@ 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 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. @@ -396,9 +346,8 @@ add_custom_target(documentation ALL DEPENDS doc-libmeep) # to set the CMAKE_INSTALL_DOCDIR variable correctly). install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - + + @@ -423,11 +372,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Einschränkungen - - Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not - #if !defined(__GTK_DOC_IGNORE__) or other combinations. - + Beachten Sie, dass GTK-Doc zwar #ifndef(__GTK_DOC_IGNORE__) unterstützt, aber nicht #if !defined(__GTK_DOC_IGNORE__) oder andere Kombinationen. @@ -479,10 +424,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Verwenden Sie #Object:property, um auf eine GObject-Eigenschaft zu verweisen. - - Use #Struct.field to refer to a field inside a structure and - #GObjectClass.foo_bar() to refer to a vmethod. - + Verwenden Sie #Struct.field, um auf ein Feld innerhalb einer Struktur zu verweisen und #GObjectClass.foo_bar() für eine vmethod. @@ -490,33 +432,14 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Falls Sie die Sonderzeichen »<«, »>«, »()«, »@«, »%« oder »#« in Ihrer Dokumentation verwenden wollen, ohne dass GTK-Doc diese ändert, können Sie die XML-Entitäten »&lt;«, »&gt;«, »&lpar;«, »&rpar;«, »&commat;«, »&percnt;« und »&num;« verwenden oder die Zeichen mit einem Backslash »\« maskieren. - - DocBook can do more than just links. One can also have lists, - examples, headings, and images. As of version 1.20, the - preferred way is to use a subset of the basic text formatting - syntax called - Markdown. - 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. - + DocBook kann mehr als nur Verweise zu erzeugen. Sie können Listen, Beispiele, Überschriften und Bilder einfügen. In Version 1.20 ist der bevorzugte Weg, ein Subset grundlegender Textformatierungssyntax namens Markdown zu verwenden. In älteren Versionen von GTK-Doc wird jede Dokumentation, die Markdown enthält, unverändert gerendert. Zum Beispiel erscheinen Listenobjekte als Zeilen, die mit einem Gedankenstrich beginnen. - - 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. - + Wenngleich Markdown bevorzugt wird, können Sie beide Formate mischen. Eine Einschränkung ist jedoch, dass Sie DocBook XML innerhalb von Markdown verwenden können, während Markdown in DocBook XML nicht unterstützt wird. - - 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. - + Um die Nutzung der DocBook-XML-Markierungen innerhalb der Dokumentationskommentare zu aktivieren, übergeben Sie der Variable MKDB_OPTIONS in der Datei Makefile.am die Option (oder ). - GTK-Doc comment block using Markdown + GTK-Doc-Kommentarblock in Markdown-Syntax /** * identifier: @@ -556,10 +479,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - - More examples of what markdown tags are supported can be found in the - GTK+ Documentation Markdown Syntax Reference. - + 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. @@ -594,7 +514,12 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html SECTION:<name> - Der Name verweist auf die Abschnittsdokumentation des entsprechenden Teils der Datei <package>-sections.txt. Der hier angegebene Name sollte der Markierung <FILE> in der Datei <package>-sections.txt entsprechen. + + The name links the section documentation to the respective part in + the <package>-sections.txt file. The + name given here should match the <FILE> tag in the + <package>-sections.txt file. + @@ -682,43 +607,24 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - - 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. - + Sie können Stabilitätsinformationen zu allen Dokumentationselementen hinzufügen, um darauf hinzuweisen, ob API-Stabilität für alle Minor-Veröffentlichungen des Projekts garantiert wird. - - The default stability level for all documentation elements can be set - by passing the argument to - gtkdoc-mkdb with one of the values below. - + Die Standard-Stabilitätsstufe für alle Dokumentationselemente setzen Sie durch Übergabe des Arguments an gtkdoc-mkdb in einem der nachfolgend beschriebenen Werte. - Stability Tags + Stabilitäts-Markierungen Stability: Stable - - Mark the element as stable. This is for public APIs which are - guaranteed to remain stable for all future minor releases of the - project. - + Markiert das Element als stabil. Dies bezieht sich auf öffentliche APIs, für die für alle zukünftigen Minor-Veröffentlichungen des Projekts Stabilität gewährleistet ist. Stability: Unstable - - Mark the element as unstable. This is for public APIs which are - released as a preview before being stabilised. - + Markiert das Element als instabil. Dies bezieht sich auf öffentliche APIs, die als Vorschau vor der endgültigen Stabilisierung gedacht sind. Stability: Private - - Mark the element as private. This is for interfaces which can be - used by tightly coupled modules, but not by arbitrary third - parties. - + Markiert das Element als privat. Dies bezieht sich auf Schnittstellen, die von eng damit verknüpften Modulen genutzt werden kann, aber nicht von beliebigen Drittanbietern. @@ -746,13 +652,7 @@ foo_get_bar(Foo *foo) Anmerkungen - - 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. - + Dokumentationsblöcke können Anmerkungs-Markierungen enthalten. Diese Markierungen werden als Tooltips (Minihilfen) dargestellt, die die jeweilige Bedeutung anzeigen. Sie werden von gobject-introspection genutzt, um Sprachbindungen zu erzeugen. Eine detaillierte Liste der unterstützten Markierungen finden Sie im Wiki. Anmerkungen @@ -814,7 +714,7 @@ foo_get_bar(Foo *foo) - Funktions-Tags + Funktions-Markierungen Returns: Abschnitt, der das zurückgegebene Ergebnis beschreibt. @@ -822,10 +722,7 @@ foo_get_bar(Foo *foo) @...: - - In case the function has variadic arguments, you should use this - tag (@Varargs: does also work for historic reasons). - + Wenn die Funktion variadische Argumente enthält, sollten Sie diese Markierung verwenden (@Varargs: funktioniert aus historischen Gründen ebenfalls). @@ -895,21 +792,9 @@ typedef struct _FooWidget { Verwenden Sie /*< private >*/ vor den privaten »struct«-Feldern, die Sie verbergen wollen. Um das umgekehrte Verhalten zu erzielen, verwenden Sie /*< public >*/. - - 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. - + Wenn das erste Feld »g_iface«, »parent_instance« oder »parent_class« ist, wird es automatisch als privat angesehen und muss nicht im Kommentarblock erwähnt werden. - - Struct comment blocks can also be used for GObjects and GObjectClasses. - It is usually a good idea to add a comment block for a class, if it has - vmethods (as this is how they can be documented). For the GObject - itself one can use the related section docs, having a separate block - for the instance struct would be useful if the instance has public - fields. One disadvantage here is that this creates two index entries - of the same name (the structure and the section). - + Struct-Kommentarblöcke können auch für GObjects und GObjectClasses verwendet werden. Es ist ratsam, einen Kommentarblock für eine Klasse hinzuzufügen, wenn diese vmethods enthält (dies ist die Art der Dokumentation dafür). Für GObject selbst können Sie die jeweiligen Abschnittsdokumentationen verwenden, wobei ein separater Block für das Instanz-Struct sinnvoll ist, sofern die Instanz öffentliche Felder enthält. Ein Nachteil ist hier, dass dadurch zwei gleichnamige Indexeinträge erstellt werden (die Struktur und der Abschnitt). @@ -937,10 +822,97 @@ typedef enum { + + + Eingebettete Programmdokumentation + Dokumentieren Sie ein Programm und dessen Befehlszeilen-Schnittstelle mit eingebetteter Dokumentation. + + + Schlagwörter + + PROGRAM + + + Definiert den Start einer Programmdokumentation + + + + + @short_description: + + Definiert eine Kurzbeschreibung des Programms (optional). + + + + + @synopsis: + + Definiert die Argumente oder eine Liste von Argumenten, die das Programm akzeptiert (optional). + + + + + @see_also: + + Der Abschnitt »SEE ALSO« in den man-Pages (Unix-Handbuchseiten, optional). + + + + + @arg: + + Argument(e), die dem Programm übergeben wurden, und die zugehörige Beschreibung (optional). + + + + + Description: + + Eine ausführlichere Beschreibung des Programms. + + + + + Returns: + + Geben Sie an, welche Wert(e) das Programm zurück gibt (optional). + + + + + + + Beispiel einer Programmdokumentation. + Programm-Dokumentationsblock + +/** + * PROGRAM:test-program + * @short_description: A test program + * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE* + * @see_also: test(1) + * @--arg1 *arg*: set arg1 to *arg* + * @--arg2 *arg*: set arg2 to *arg* + * @-v, --version: Print the version number + * @-h, --help: Print the help message + * + * Long description of program. + * + * Returns: Zero on success, non-zero on failure + */ +int main(int argc, char *argv[]) +{ + return 0; +} + + + + + + - Nützliche DocBook-Tags + Nützliche DocBook-Markierungen - Nachfolgend finden Sie einige DocBook-Tags, die beim Dokumentieren von Code nützlich sein können. + Nachfolgend finden Sie einige DocBook-Markierungen, die beim Dokumentieren von Code nützlich sein können. So erstellen Sie eine Verknüpfung zu einem anderen Abschnitt in den GTK-Docs: @@ -1059,11 +1031,7 @@ gtk_arrow_get_type - - Since GTK-Doc 1.8 gtkdoc-scan can generate this list for you. - Just add "--rebuild-types" to SCAN_OPTIONS in Makefile.am. If you - use this approach you should not dist the types file nor have it under version control. - + Seit GTK-Doc 1.8 kann gtkdoc-scan diese Liste für Sie erstellen. Fügen Sie einfach »--rebuild-types« zu SCAN_OPTIONS in Makefile.am hinzu. Wenn Sie so vorgehen sollten Sie weder Typen-Datei mit veröffentlichen noch diese unter Versionsverwaltung stellen. @@ -1072,14 +1040,7 @@ gtk_arrow_get_type GTK-Doc erstellt die Dokumentation in DocBook-SGML/XML. Beim Verarbeiten der in den Quellcode eingebetteten Kommentare erzeugt GTK-Doc eine Dokumentationsseite pro Klasse oder Modul als separate Datei. Das Hauptdokument schließt diese ein und setzt sie in die passende Reihenfolge. - - 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. - + Während GTK-Doc ein Vorlagen-Hauptdokument für Sie erstellt, wird eine spätere Ausführung es nicht mehr verändern. Das bedeutet, dass Sie das Dokument beliebig strukturieren können. Dies schließt Gruppieren von Seiten und Hinzufügen von zusätzlichen Seiten ein. GTK-Doc hat eine neue Test-Suite, wo auch das Hauptdokument von Grund auf neu erstellt wird. Es ist ratsam, sich diese von Zeit zu Zeit anzusehen und zu schauen, ob dort einige Neuigkeiten eingeführt werden. Erstellen Sie keine Schritt-für-Schritt-Anleitungen als zusätzliche Dokumente. Schreiben Sie lediglich zusätzliche Kapitel. Der Vorteil des direkten Einbettens einer Anleitung für Ihre Bibliothek in die API ist die Möglichkeit der einfachen Verknüpfung der Schritt-für-Schritt-Anleitung zur Symboldokumentation. Außerdem sind die Chancen größer, dass die Anleitung die gleichen Aktualisierungen erfährt wie die Bibliothek selbst. @@ -1105,30 +1066,22 @@ gtk_arrow_get_type + Zusätzlich werden einige Optionselemente in Kommentarform erstellt. Sie können sich diese anschauen und aktivieren, wenn Sie wollen. + - In addition a few option elements are created in commented form. You can - review these and enable them as you like. - - - - Optional part in the master document + Optionaler Teil im Master-Dokument - <!-- enable this when you use gobject introspection annotations + <!-- aktivieren Sie dieses, wenn sie gobject introspection-Anmerkungen verwenden <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> --> - - - 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. - + + Schlussendlich müssen Sie einen neuen Abschnitt explizit einfügen, sobald Sie einen öffnen. Das Werkzeug gtkdoc-check erinnert Sie an neu erzeugte XML-Dateien, die in der Dokumentation noch nicht erfasst sind. - Including generated sections + Einbeziehen erzeugter Abschnitte <chapter> <title>my library</title> @@ -1145,21 +1098,14 @@ gtk_arrow_get_type Die Abschnittsdatei wird verwendet, um die Dokumentations-Ausgaben von GTK-Doc zu organisieren. Man gibt an, welches Symbol zu welchem Modul oder welcher Klasse gehört und regelt die Sichtbarkeit (öffentlich oder privat). - - The section file is a plain text file with tags delimiting sections. - Blank lines are ignored and lines starting with a '#' are treated as - comment lines. - - + Die Abschnittsdatei ist eine reine Textdatei mit Markierungen, welche die Abschnitte voneinander trennen. Leere Zeilen werden ignoriert und Zeilen, die mit »#« beginnen, werden als Kommentarzeilen behandelt. + - - While the tags make the file look like xml, it is not. Please do not - close tags like <SUBSECTION>. - + Zwar lassen die Markierungen die Datei wie XML erscheinen, doch der Schein trügt. Bitte schließen Sie keine Markierungen wie <SUBSECTION>. - Including generated sections + Einbeziehen erzeugter Abschnitte <INCLUDE>libmeep/meep.h</INCLUDE> @@ -1177,38 +1123,11 @@ meep_app_get_type - - 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 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). - + Die Markierung <FILE> ... </FILE> wird verwendet, um den Dateinamen ohne Suffix anzugeben. Zum Beispiel wird »<FILE>gnome-config</FILE>« dazu führen, dass der Deklarationsabschnitt in die Vorlage-Datei tmpl/gnome-config.sgml ausgegeben wird, welche in die DocBook-XML-Datei sgml/gnome-config.sgml oder die DocBook-XML-Datei xml/gnome-config.xml umgewandelt wird. (Der Name der HTML-Datei basiert auf dem Modulnamen und dem Abschnittstitel. Für GObject basiert er auf dem GObject-Klassennamen in Kleinbuchstaben). Das Tag <TITLE> ... </TITLE> wird zur Angabe des Abschnitttitels verwendet. Es ist nur nützlich bevor die Vorlagen (falls verwendet) anfangs erstellt werden, weil der Titel in der Vorlage diesen überschreibt. Wenn man das SECTION-Kommentar in den Quellen einsetzt, ist dies überflüssig. - - 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). - + Sie können Objekte im Abschnitt mittels der Markierung <SUBSECTION> gruppieren. Derzeit gibt es eine Leerzeile zwischen Unterabschnitten im Inhaltsangabe-Abschnitt aus. Sie können auch <SUBSECTION Standard> für Standard GObject-Deklarationen verwenden (z.B. Funktionen wie g_object_get_type und Makros wie G_OBJECT(), G_IS_OBJECT() etc.). Derzeit werden diese nicht in die Dokumentation aufgenommen. Sie können auch <SUBSECTION Private> für private Deklarationen verwenden, welche nicht ausgegeben werden. Dies ist eine praktische Möglichkeit, Warnmeldungen bezüglich ungenutzter Deklarationen zu vermeiden. Wenn Ihre Bibliothek private Typen enthält, die nicht in der Objekthierarchie und der Liste der implementierten oder benötigten Schnittstellen erscheinen sollen, fügen Sie diese zu einem »Private«-Unterabschnitt hinzu. Ob Sie GObject oder GObjectClass wie Structs im öffentlichen oder im Standardabschnitt einsetzen, hängt davon ab, ob öffentliche Einträge vorhanden sind (Variablen, vmethods). Sie können auch <INCLUDE> ... </INCLUDE> verwenden, um die #include-Dateien anzugeben, die in den Abschnitten zur Inhaltsangabe gezeigt werden. Es enthält eine durch Kommata getrennte Liste von #include-Dateien ohne eckige Klammern. Wenn Sie es außerhalb aller Abschnitte festlegen, wirkt es in allen Abschnitten bis zum Dateiende. Wenn Sie es innerhalb eines Abschnitts festlegen, wirkt es nur in diesem Abschnitt. @@ -1233,101 +1152,57 @@ meep_app_get_type Man kann sich auch die Dateien ansehen, die durch den Quellcode-Scanner erzeugt wurden: <package>-decl-list.txt und <package>-decl.txt. Die erste kann mit der Abschnittsdatei verglichen werden, falls diese händisch verwaltet wird. Die zweite listet alle Deklarationen aus den Kopfdateien. Falls ein Symbol fehlt kann man prüfen, ob diese Datei es enthält. - - 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 GTK-Doc to keep the intermediate - scanner file for further analysis, by running it as - GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Wenn das Projekt auf GObject basiert, kann man auch in die Dateien schauen, die der Objekt-Scanner erzeugt hat: <package>.args.txt, <package>.hierarchy.txt, <package>.interfaces.txt, <package>.prerequisites.txt und <package>.signals.txt. Falls in irgendeiner Datei Symbole fehlen, können Sie Gtk-Doc anweisen, die zwischenläufige Scanner-Datei zur weiteren Analyse zu behalten, indem Sie GTK_DOC_KEEP_INTERMEDIATE=1 make ausführen. - + Die Dokumentation modernisieren - - - 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. - - + + GTK-Doc ist schon seit längerer Zeit verfügbar. In diesem Abschnitt zeigen wir neue Features und die Version, mit der sie eingeführt wurden. + GTK-Doc 1.9 - - When using xml instead of sgml, one can actually name the master - document <package>-docs.xml. - - - - 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. - - + Wenn Sie XML anstatt SGML verwenden, können Sie das Hauptdokument <package>-docs.xml nennen. + + Diese Version unterstützt in Makefile.am. Wenn dies aktiviert ist, wird die Datei <package>-sections.txt automatisch erzeugt und kann aus der Versionsverwaltung entfernt werden. Dies funktioniert nur sauber in Projekten, die eine strikt »reguläre« Struktur haben (zum Beispiel erzeugt jedes .{c,h}-Paar einen neuen Abschnitt). In einem solch sauber organisierten Projekt kann dann mit dem Befehl meld <package>-decl-list.txt <package>-sections.txt eine manuell verwaltete Abschnittsdatei sehr einfach aktualisiert werden. + 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 you source control system and haven't yet switched, just + checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. - + GTK-Doc 1.10 - - 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. - + Diese Version unterstützt in Makefile.am. Wenn dies aktiviert ist, wird die Datei <package>.types automatisch erzeugt und kann aus der Versionsverwaltung entfernt werden. Dieses Feature erfordert die Einrichtung von IGNORE_HFILES in Makefile.am für Code, der nur unter bestimmten Bedingungen erstellt werden soll. GTK-Doc 1.16 - - 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. - Enable gtkdoc-check - Diese Version führt ein neues Werkzeug namens gtkdoc-check ein. Damit können Sie eine Reihe von Plausibilitätsprüfungen auf Ihre Dokumentation anwenden. Um es zu aktivieren, fügen Sie folgende Zeilen am Ende von Makefile.am hinzu. gtkdoc-check einschalten + if ENABLE_GTK_DOC TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) TESTS = $(GTKDOC_CHECK) endif -]]> - - + + GTK-Doc 1.20 - - 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. - + In Version 1.18 wurde erstmals Unterstützung für Markdown eingeführt. Die Verwendung von Markdown in Dokumentationskommentaren ist weniger aufwändig als das Schreiben von DocBook XML. Diese Version bringt diesbezüglich wesentliche Verbesserungen und fügt zahlreiche weitere Stile hinzu. Alle Details hierzu finden Sie im Abschnitt zur Kommentarsyntax. @@ -1337,7 +1212,7 @@ endif 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 any example that shows how the entity file is included + number. Below is an example that shows how the entity file is included and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. @@ -1379,13 +1254,7 @@ endif Dokumentieren des Werkzeuges - - Create one refentry file per tool. Following - our example we would call it - meep/docs/reference/meeper/meep.xml. For the xml - tags that should be used and can look at generated file in the xml - subdirectory as well as examples e.g. in glib. - + Erstellen Sie eine Referenzeintragsdatei pro Werkzeug. In unserem Beispiel nennen wir sie meep/docs/reference/meeper/meep.xml. Für die zu verwendenden XML-Markierungen können Sie die generierte Datei im XML-Unterordner oder Beispiele (z.B. in glib) ansehen. @@ -1492,11 +1361,11 @@ EXTRA_DIST += meep.xml - multiple "IDs" for constraint linkend: XYZ + Mehrfache »IDs« für »constraint linkend: XYZ« Das Symbol XYZ erscheint zweifach in der Datei <package>-sections.txt. - Element typename in namespace '' encountered in para, but no template matches. + Element-Typname im Namensraum '' in einem Abschnitt, der keiner Vorlage entspricht. @@ -1703,13 +1572,7 @@ EXTRA_DIST += meep.xml 6. SAMMLUNGEN VON DOKUMENTEN Sie dürfen eine Sammlung erstellen, die aus dem Dokument und anderen, unter dieser Lizenz veröffentlichten Dokumenten besteht, und die individuellen Kopien der Lizenz in den einzelnen Dokumenten durch eine einzige Kopie ersetzen, die sich in der Sammlung befindet, vorausgesetzt, Sie folgen den Regeln dieser Lizenz für wortwörtliches Kopieren jedes dieser Dokumente in jeglicher Hinsicht. - - 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. - + Sie dürfen ein einzelnes Dokument aus einer solchen Sammlung heraustrennen, und es individuell unter dieser Lizenz verteilen, vorausgesetzt, Sie fügen eine Kopie dieser Lizenz in das herausgetrennte Dokument ein und folgen der Lizenz in jeglicher Hinsicht bezüglich dem wortwörtlichen Kopieren des Dokuments. diff --git a/help/manual/el/el.po b/help/manual/el/el.po index 7f8d21b..0bb5d22 100644 --- a/help/manual/el/el.po +++ b/help/manual/el/el.po @@ -8,8 +8,8 @@ msgid "" msgstr "" "Project-Id-Version: gtk-doc-help.master\n" -"POT-Creation-Date: 2015-11-19 07:07+0000\n" -"PO-Revision-Date: 2016-03-14 12:06+0200\n" +"POT-Creation-Date: 2016-03-21 21:32+0000\n" +"PO-Revision-Date: 2016-04-10 22:03+0300\n" "Last-Translator: Tom Tryfonidis \n" "Language-Team: team@lists.gnome.gr\n" "Language: el\n" @@ -17,7 +17,7 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=(n != 1);\n" -"X-Generator: Poedit 1.8.7\n" +"X-Generator: Poedit 1.8.7.1\n" #. Put one translator per line, in the form NAME , YEAR1, YEAR2 msgctxt "_" @@ -129,15 +129,32 @@ msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:83 +#| msgid "" +#| "1.24.1 30 May 2015 " +#| "ss development version" msgid "" -"1.24.1 30 May 2015 ss1.25.1 21 March 2016 ss development version" msgstr "" -"1.24.1 30 Μαΐου 2015 ss έκδοση ανάπτυξης" +"1.25.1 21 Μαρτίου 2016 " +"ss έκδοση ανάπτυξης" #. (itstool) path: revhistory/revision #: C/index.docbook:89 +#| msgid "" +#| "1.24 29 May 2015 ss bug fix" +msgid "" +"1.25 21 March 2016 ss bug fixes, test cleanups" +msgstr "" +"1.25 21 Μαρτίου 2016 ss διορθώσεις σφαλμάτων, εκαθάρριση δοκιμαστικού " +"κώδικα" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:95 msgid "" "1.24 29 May 2015 ss bug fix" @@ -146,7 +163,7 @@ msgstr "" "authorinitials> διόρθωση σφαλμάτων" #. (itstool) path: revhistory/revision -#: C/index.docbook:95 +#: C/index.docbook:101 msgid "" "1.23 17 May 2015 ss bug fix" @@ -155,7 +172,7 @@ msgstr "" "authorinitials> διόρθωση σφαλμάτων" #. (itstool) path: revhistory/revision -#: C/index.docbook:101 +#: C/index.docbook:107 msgid "" "1.22 07 May 2015 ss bug fixes, dropping deprecated features" #. (itstool) path: revhistory/revision -#: C/index.docbook:107 +#: C/index.docbook:113 msgid "" "1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" #. (itstool) path: revhistory/revision -#: C/index.docbook:113 +#: C/index.docbook:119 msgid "" "1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" #. (itstool) path: revhistory/revision -#: C/index.docbook:119 +#: C/index.docbook:125 msgid "" "1.19 05 Jun 2013 ss bug fixes" @@ -197,7 +214,7 @@ msgstr "" "authorinitials> διόρθωση σφαλμάτων" #. (itstool) path: revhistory/revision -#: C/index.docbook:125 +#: C/index.docbook:131 msgid "" "1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" @@ -207,7 +224,7 @@ msgstr "" "markdown" #. (itstool) path: revhistory/revision -#: C/index.docbook:131 +#: C/index.docbook:137 msgid "" "1.17 26 Feb 2011 sk urgent bug fix update" @@ -216,7 +233,7 @@ msgstr "" "authorinitials> επείγουσα διόρθωση σφάλματος" #. (itstool) path: revhistory/revision -#: C/index.docbook:137 +#: C/index.docbook:143 msgid "" "1.16 14 Jan 2011 sk bugfixes, layout improvements" @@ -226,7 +243,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:143 +#: C/index.docbook:149 msgid "" "1.15 21 May 2010 sk bug and regression fixes" @@ -235,7 +252,7 @@ msgstr "" "authorinitials> διορθώσεις σφαλμάτων και αναδρομής" #. (itstool) path: revhistory/revision -#: C/index.docbook:149 +#: C/index.docbook:155 msgid "" "1.14 28 March 2010 sk bugfixes and performance improvements" @@ -245,7 +262,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:155 +#: C/index.docbook:161 msgid "" "1.13 18 December 2009 " "sk broken tarball update" #. (itstool) path: revhistory/revision -#: C/index.docbook:161 +#: C/index.docbook:167 msgid "" "1.12 18 December 2009 " "sk new tool features and " @@ -267,7 +284,7 @@ msgstr "" "και διορθώσεις σφαλμάτων" #. (itstool) path: revhistory/revision -#: C/index.docbook:167 +#: C/index.docbook:173 msgid "" "1.11 16 November 2008 " "mal GNOME doc-utils migration" #. (itstool) path: chapter/title -#: C/index.docbook:180 +#: C/index.docbook:186 msgid "Introduction" msgstr "Εισαγωγή" #. (itstool) path: chapter/para -#: C/index.docbook:182 +#: C/index.docbook:188 msgid "" "This chapter introduces GTK-Doc and gives an overview of what it is and how " "it is used." @@ -292,12 +309,12 @@ msgstr "" "και τον τρόπο χρήσης του." #. (itstool) path: sect1/title -#: C/index.docbook:188 +#: C/index.docbook:194 msgid "What is GTK-Doc?" msgstr "Τι είναι το GTK-Doc;" #. (itstool) path: sect1/para -#: C/index.docbook:190 +#: C/index.docbook:196 msgid "" "GTK-Doc is used to document C code. It is typically used to document the " "public API of libraries, such as the GTK+ and GNOME libraries. But it can " @@ -309,12 +326,12 @@ msgstr "" "εφαρμογών." #. (itstool) path: sect1/title -#: C/index.docbook:198 +#: C/index.docbook:204 msgid "How Does GTK-Doc Work?" msgstr "Πώς λειτουργεί το GTK-Doc;" #. (itstool) path: sect1/para -#: C/index.docbook:200 +#: C/index.docbook:206 msgid "" "GTK-Doc works by using documentation of functions placed inside the source " "files in specially-formatted comment blocks, or documentation added to the " @@ -330,7 +347,7 @@ msgstr "" "συναρτήσεις)." #. (itstool) path: sect1/para -#: C/index.docbook:207 +#: C/index.docbook:213 msgid "" "GTK-Doc consists of a number of perl scripts, each performing a different " "step in the process." @@ -339,12 +356,12 @@ msgstr "" "οποία είναι υπεύθυνο για διαφορετικό στάδιο της όλης διαδικασίας." #. (itstool) path: sect1/para -#: C/index.docbook:212 +#: C/index.docbook:218 msgid "There are 5 main steps in the process:" msgstr "Η διαδικασία περιλαμβάνει 5 κύρια στάδια:" #. (itstool) path: listitem/para -#: C/index.docbook:219 +#: C/index.docbook:225 msgid "" "Writing the documentation. The author fills in the " "source files with the documentation for each function, macro, union etc. (In " @@ -357,7 +374,7 @@ msgstr "" "παράγονταν αυτόματα, αλλά αυτός ο τρόπος δεν συνιστάται πλέον.)" #. (itstool) path: listitem/para -#: C/index.docbook:229 +#: C/index.docbook:235 msgid "" "Gathering information about the code. " "gtkdoc-scan scans the header files of the code " @@ -393,7 +410,7 @@ msgstr "" "<module>-overrides.txt." #. (itstool) path: listitem/para -#: C/index.docbook:246 +#: C/index.docbook:252 msgid "" "gtkdoc-scangobj can also be used to dynamically " "query a library about any GObject subclasses it exports. It saves " @@ -406,7 +423,7 @@ msgstr "" "ιεραρχία κλάσεων καθώς και για τις ιδιότητες και σήματα GObject που περιέχει." #. (itstool) path: listitem/para -#: C/index.docbook:252 +#: C/index.docbook:258 msgid "" "gtkdoc-scanobj should not be used anymore. It was " "needed in the past when GObject was still GtkObject inside gtk+." @@ -416,7 +433,7 @@ msgstr "" "gtk+." #. (itstool) path: listitem/para -#: C/index.docbook:259 +#: C/index.docbook:265 msgid "" "Generating the \"template\" files. gtkdoc-" "mktmpl creates a number of files in the gtkdocize supports now " @@ -449,7 +466,7 @@ msgstr "" "σύστημα ελέγχου εκδόσεων)." #. (itstool) path: listitem/para -#: C/index.docbook:280 +#: C/index.docbook:286 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 " @@ -479,7 +496,7 @@ msgstr "" "σε ένα έγγραφο PDF που ονομάζεται <package>.pdf." #. (itstool) path: listitem/para -#: C/index.docbook:295 +#: C/index.docbook:301 msgid "" "Files in xml/ and html/ directories are always overwritten. One " @@ -490,7 +507,7 @@ msgstr "" "Επομένως, δεν πρέπει να τα επεξεργάζεστε απευθείας." #. (itstool) path: listitem/para -#: C/index.docbook:303 +#: C/index.docbook:309 msgid "" "Fixing up cross-references between documents. After " "installing the HTML files, gtkdoc-fixxref can be " @@ -515,24 +532,24 @@ msgstr "" "εγκατεστημένη η τεκμηρίωση)." #. (itstool) path: sect1/title -#: C/index.docbook:321 +#: C/index.docbook:327 msgid "Getting GTK-Doc" msgstr "Λήψη GTK-Doc" #. (itstool) path: sect2/title -#: C/index.docbook:324 +#: C/index.docbook:330 msgid "Requirements" msgstr "Απαιτήσεις" #. (itstool) path: sect2/para -#: C/index.docbook:325 +#: C/index.docbook:331 msgid "Perl v5 - the main scripts are in Perl." msgstr "" "Perl v5 - οι κύριες δέσμες ενεργειών είναι γραμμένες σε " "Perl." #. (itstool) path: sect2/para -#: C/index.docbook:328 +#: C/index.docbook:334 msgid "" "xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" @@ -542,7 +559,7 @@ msgstr "" "\">xmlsoft.org/XSLT/" #. (itstool) path: sect2/para -#: C/index.docbook:332 +#: C/index.docbook:338 msgid "" "docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" #. (itstool) path: sect2/para -#: C/index.docbook:336 +#: C/index.docbook:342 msgid "Python - optional - for gtkdoc-depscan" msgstr "Python - προαιρετική - για το gtkdoc-depscan" #. (itstool) path: sect2/para -#: C/index.docbook:339 +#: C/index.docbook:345 msgid "" "One of source-highlight, highlight " "or vim - optional - used for syntax highlighting of " @@ -569,17 +586,17 @@ msgstr "" "για την επισήμανση της σύνταξης στα παραδείγματα" #. (itstool) path: sect1/title -#: C/index.docbook:347 +#: C/index.docbook:353 msgid "About GTK-Doc" msgstr "Περί GTK-Doc" #. (itstool) path: sect1/para -#: C/index.docbook:349 C/index.docbook:363 +#: C/index.docbook:355 C/index.docbook:369 msgid "(FIXME)" msgstr "(ΠΡΟΣ ΔΙΟΡΘΩΣΗ)" #. (itstool) path: sect1/para -#: C/index.docbook:353 +#: C/index.docbook:359 msgid "" "(History, authors, web pages, mailing list, license, future plans, " "comparison with other similar systems.)" @@ -588,22 +605,22 @@ msgstr "" "σχέδια, σύγκριση με άλλα παρόμοια συστήματα.)" #. (itstool) path: sect1/title -#: C/index.docbook:361 +#: C/index.docbook:367 msgid "About this Manual" msgstr "Περί του εγχειριδίου" #. (itstool) path: sect1/para -#: C/index.docbook:367 +#: C/index.docbook:373 msgid "(who it is meant for, where you can get it, license)" msgstr "(σε ποιους απευθύνεται, πού θα το βρείτε, άδεια)" #. (itstool) path: chapter/title -#: C/index.docbook:376 +#: C/index.docbook:382 msgid "Setting up your project" msgstr "Δημιουργώντας το δικό σας έργο" #. (itstool) path: chapter/para -#: C/index.docbook:378 +#: C/index.docbook:384 msgid "" "The next sections describe what steps to perform to integrate GTK-Doc into " "your project. Theses sections assume we work on a project called 'meep'. " @@ -623,12 +640,12 @@ msgstr "" "μια διαφορετική δόμηση ρυθμίσεων." #. (itstool) path: sect1/title -#: C/index.docbook:389 +#: C/index.docbook:395 msgid "Setting up a skeleton documentation" msgstr "Δημιουργία του σκελετού τεκμηρίωσης" #. (itstool) path: sect1/para -#: C/index.docbook:391 +#: C/index.docbook:397 msgid "" "Under your top-level project directory create folders called docs/reference " "(this way you can also have docs/help for end-user documentation). It is " @@ -642,12 +659,12 @@ msgstr "" "περιλαμβάνουν μόνο μία βιβλιοθήκη." #. (itstool) path: example/title -#: C/index.docbook:400 +#: C/index.docbook:406 msgid "Example directory structure" msgstr "Παράδειγμα δομής καταλόγου" #. (itstool) path: example/programlisting -#: C/index.docbook:401 +#: C/index.docbook:407 #, no-wrap msgid "" "\n" @@ -671,18 +688,18 @@ msgstr "" " meeper/\n" #. (itstool) path: sect1/para -#: C/index.docbook:398 +#: C/index.docbook:404 msgid "This can then look as shown below: <_:example-1/>" msgstr "Αυτό θα φαίνεται, λοιπόν, όπως εμφανίζεται παρακάτω: <_:example-1/>" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:416 C/index.docbook:423 +#: C/index.docbook:422 C/index.docbook:429 msgid "Integration with autoconf" msgstr "Ενσωμάτωση στο autoconf" #. (itstool) path: sect1/para -#: C/index.docbook:418 +#: C/index.docbook:424 msgid "" "Very easy! Just add one line to your configure.ac " "script." @@ -691,7 +708,7 @@ msgstr "" "configure.ac." #. (itstool) path: example/programlisting -#: C/index.docbook:424 +#: C/index.docbook:430 #, no-wrap msgid "" "\n" @@ -703,12 +720,12 @@ msgstr "" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" #. (itstool) path: example/title -#: C/index.docbook:436 +#: C/index.docbook:442 msgid "Keep gtk-doc optional" msgstr "Προαιρετικά διατηρήστε το gtk-doc" #. (itstool) path: example/programlisting -#: C/index.docbook:437 +#: C/index.docbook:443 #, no-wrap msgid "" "\n" @@ -728,7 +745,7 @@ msgstr "" "])\n" #. (itstool) path: sect1/para -#: C/index.docbook:431 +#: C/index.docbook:437 msgid "" "This will require all developers to have gtk-doc installed. If it is okay " "for your project to have optional api-doc build setup, you can solve this as " @@ -742,7 +759,7 @@ msgstr "" "GTK_DOC_CHECK. <_:example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:448 +#: C/index.docbook:454 msgid "" "The first argument is used to check for the gtkdocversion at configure time. " "The 2nd, optional argument is used by gtkdocize. " @@ -755,30 +772,30 @@ msgstr "" "symbol> επίσης προσθέτει αρκετούς διακόπτες ρύθμισης:" #. (itstool) path: listitem/para -#: C/index.docbook:454 +#: C/index.docbook:460 msgid "--with-html-dir=PATH : path to installed docs" msgstr "--with-html-dir= PATH : διαδρομή προς την εγκατεστημένη τεκμηρίωση" #. (itstool) path: listitem/para -#: C/index.docbook:455 +#: C/index.docbook:461 msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "" "--enable-gtk-doc : χρήση gtk-doc για τη δόμηση τεκμηρίωσης [προεπιλογή=no]" #. (itstool) path: listitem/para -#: C/index.docbook:456 +#: C/index.docbook:462 msgid "" "--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" "--enable-gtk-doc-html : δόμηση τεκμηρίωσης σε μορφή html [προεπιλογή=yes]" #. (itstool) path: listitem/para -#: C/index.docbook:457 +#: C/index.docbook:463 msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" msgstr "--enable-gtk-doc-pdf : δόμηση τεκμηρίωσης σε μορφή pdf [προεπιλογή=no]" #. (itstool) path: important/para -#: C/index.docbook:461 +#: C/index.docbook:467 msgid "" "GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " @@ -792,7 +809,7 @@ msgstr "" "τον προγραμματιστή)." #. (itstool) path: sect1/para -#: C/index.docbook:469 +#: C/index.docbook:475 msgid "" "Furthermore it is recommended that you have the following line inside you " "configure.ac script. This allows " @@ -805,12 +822,12 @@ msgstr "" "GTK_DOC_CHECK στο έργο σας." #. (itstool) path: example/title -#: C/index.docbook:477 +#: C/index.docbook:483 msgid "Preparation for gtkdocize" msgstr "Προετοιμασία για το gtkdocize" #. (itstool) path: example/programlisting -#: C/index.docbook:478 +#: C/index.docbook:484 #, no-wrap msgid "" "\n" @@ -820,7 +837,7 @@ msgstr "" "AC_CONFIG_MACRO_DIR(m4)\n" #. (itstool) path: sect1/para -#: C/index.docbook:483 +#: C/index.docbook:489 msgid "" "After all changes to configure.ac are made, update the " "configure file. This can be done by re-running " @@ -832,12 +849,12 @@ msgstr "" "code>." #. (itstool) path: sect1/title -#: C/index.docbook:491 +#: C/index.docbook:497 msgid "Integration with automake" msgstr "Ενσωμάτωση στο automake" #. (itstool) path: sect1/para -#: C/index.docbook:493 +#: C/index.docbook:499 msgid "" "First copy the Makefile.am from the examples sub directory of the Makefile.am. All the settings have a comment above that describes their " @@ -876,12 +893,12 @@ msgstr "" "παραμέτρους." #. (itstool) path: sect1/title -#: C/index.docbook:518 +#: C/index.docbook:524 msgid "Integration with autogen" msgstr "Ενσωμάτωση στο autogen" #. (itstool) path: sect1/para -#: C/index.docbook:520 +#: C/index.docbook:526 msgid "" "Most projects will have an autogen.sh script to setup " "the build infrastructure after a checkout from version control system (such " @@ -896,12 +913,12 @@ msgstr "" "πρέπει να εκτελείται πριν το autoheader, το automake ή το autoconf." #. (itstool) path: example/title -#: C/index.docbook:529 +#: C/index.docbook:535 msgid "Running gtkdocize from autogen.sh" msgstr "Εκτέλεση του gtkdocize από το autogen.sh" #. (itstool) path: example/programlisting -#: C/index.docbook:530 +#: C/index.docbook:536 #, no-wrap msgid "" "\n" @@ -911,7 +928,7 @@ msgstr "" "gtkdocize || exit 1\n" #. (itstool) path: sect1/para -#: C/index.docbook:536 +#: C/index.docbook:542 msgid "" "When running gtkdocize it copies gtk-" "doc.make to your project root (or any directory specified by the " @@ -926,7 +943,7 @@ msgstr "" "function>." #. (itstool) path: sect1/para -#: C/index.docbook:545 +#: C/index.docbook:551 msgid "" "Historically GTK-Doc was generating template files where developers entered " "the docs. This turned out to be not so good (e.g. the need for having " @@ -959,12 +976,12 @@ msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:562 C/index.docbook:579 +#: C/index.docbook:568 C/index.docbook:585 msgid "Running the doc build" msgstr "Εκτέλεση της δόμησης τεκμηρίωσης" #. (itstool) path: sect1/para -#: C/index.docbook:564 +#: C/index.docbook:570 msgid "" "After the previous steps it's time to run the build. First we need to rerun " "autogen.sh. If this script runs configure for you, then " @@ -978,7 +995,7 @@ msgstr "" "με αυτή την επιλογή." #. (itstool) path: sect1/para -#: C/index.docbook:571 +#: C/index.docbook:577 msgid "" "The first make run generates several additional files in the doc-" "directories. The important ones are: <package>.types<package>-sections.txt." #. (itstool) path: example/programlisting -#: C/index.docbook:580 +#: C/index.docbook:586 #, no-wrap msgid "" "\n" @@ -1003,7 +1020,7 @@ msgstr "" "make\n" #. (itstool) path: sect1/para -#: C/index.docbook:586 +#: C/index.docbook:592 msgid "" "Now you can point your browser to docs/reference/<package>/" "index.html. Yes, it's a bit disappointing still. But hang-on, " @@ -1015,12 +1032,12 @@ msgstr "" "κεφάλαιο θα μάθετε πώς μπορείτε να ζωντανέψετε τις σελίδες σας." #. (itstool) path: sect1/title -#: C/index.docbook:594 +#: C/index.docbook:600 msgid "Integration with version control systems" msgstr "Ενσωμάτωση σε συστήματα ελέγχου εκδόσεων" #. (itstool) path: sect1/para -#: C/index.docbook:596 +#: C/index.docbook:602 msgid "" "As a rule of thumb, it's the files you edit which should go under version " "control. For typical projects it's these files: <package>." @@ -1035,7 +1052,7 @@ msgstr "" "filename>, Makefile.am." #. (itstool) path: sect1/para -#: C/index.docbook:604 +#: C/index.docbook:610 msgid "" "Files in the xml/ and html/ " "directories should not go under version control. Neither should any of the " @@ -1046,12 +1063,12 @@ msgstr "" "xml/ and html/." #. (itstool) path: sect1/title -#: C/index.docbook:612 +#: C/index.docbook:618 msgid "Integration with plain makefiles or other build systems" msgstr "Ενσωμάτωση στα αρχεία makefiles ή άλλα συστήματα δόμησης" #. (itstool) path: sect1/para -#: C/index.docbook:614 +#: C/index.docbook:620 msgid "" "In the case one does not want to use automake and therefore gtk-" "doc.mak one will need to call the gtkdoc tools in the right order " @@ -1062,12 +1079,12 @@ msgstr "" "εργαλεία του gtkdoc στη σωστή σειρά στα makefiles (ή άλλα εργαλεία δόμησης)." #. (itstool) path: example/title -#: C/index.docbook:621 +#: C/index.docbook:627 msgid "Documentation build steps" msgstr "Βήματα δόμησης τεκμηρίωσης" #. (itstool) path: example/programlisting -#: C/index.docbook:622 +#: C/index.docbook:628 #, no-wrap msgid "" "\n" @@ -1093,7 +1110,7 @@ msgstr "" "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" #. (itstool) path: sect1/para -#: C/index.docbook:636 +#: C/index.docbook:642 msgid "" "One will need to look at the Makefile.am and " "gtk-doc.mak to pick the extra options needed." @@ -1103,12 +1120,12 @@ msgstr "" "χρειάζονται." #. (itstool) path: sect1/title -#: C/index.docbook:643 +#: C/index.docbook:649 msgid "Integration with CMake build systems" msgstr "Ενσωμάτωση με συστήματα δόμησης CMake" #. (itstool) path: sect1/para -#: C/index.docbook:645 +#: C/index.docbook:651 msgid "" "GTK-Doc now provides a GtkDocConfig.cmake module (and " "the corresponding GtkDocConfigVersion.cmake module). " @@ -1121,12 +1138,12 @@ msgstr "" "μπορείτε να ορίσετε στο αρχείο CMakeLists.txt." #. (itstool) path: example/title -#: C/index.docbook:655 +#: C/index.docbook:661 msgid "Example of using GTK-Doc from CMake" msgstr "Παράδειγμα χρήσης του GTK-Doc από το CMake" #. (itstool) path: example/programlisting -#: C/index.docbook:656 +#: C/index.docbook:662 #, no-wrap msgid "" "\n" @@ -1168,19 +1185,19 @@ msgstr "" " DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" #. (itstool) path: sect1/para -#: C/index.docbook:653 +#: C/index.docbook:659 msgid "The following example shows how to use this command. <_:example-1/>" msgstr "" "Το ακόλουθο παράδειγμα δείχνει πως να χρησιμοποιήσετε την εντολή. <_:" "example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:681 +#: C/index.docbook:687 msgid "Documenting the code" msgstr "Τεκμηρίωση κώδικα" #. (itstool) path: chapter/para -#: C/index.docbook:683 +#: C/index.docbook:689 msgid "" "GTK-Doc uses source code comment with a special syntax for code " "documentation. Further it retrieves information about your project structure " @@ -1193,12 +1210,12 @@ msgstr "" "λεπτομέρειες για τη σύνταξη αυτών των σχολίων." #. (itstool) path: note/title -#: C/index.docbook:691 +#: C/index.docbook:697 msgid "Documentation placement" msgstr "Τοποθέτηση τεκμηρίωσης" #. (itstool) path: note/para -#: C/index.docbook:692 +#: C/index.docbook:698 msgid "" "In the past most documentation had to be filled into files residing inside " "the tmpl directory. This has the disadvantages that the " @@ -1211,7 +1228,7 @@ msgstr "" "συγκρούσεις με τα συστήματα ελέγχου εκδόσεων." #. (itstool) path: note/para -#: C/index.docbook:698 +#: C/index.docbook:704 msgid "" "The avoid the aforementioned problems we suggest putting the documentation " "inside the sources. This manual will only describe this way of documenting " @@ -1222,12 +1239,12 @@ msgstr "" "περιγράψουμε σε αυτό το εγχειρίδιο." #. (itstool) path: example/title -#: C/index.docbook:709 C/index.docbook:735 +#: C/index.docbook:715 C/index.docbook:741 msgid "GTK-Doc comment block" msgstr "Μπλοκ σχολίου GTK-Doc" #. (itstool) path: example/programlisting -#: C/index.docbook:710 +#: C/index.docbook:716 #, no-wrap msgid "" "\n" @@ -1241,7 +1258,7 @@ msgstr "" "#endif\n" #. (itstool) path: chapter/para -#: C/index.docbook:705 +#: C/index.docbook:711 msgid "" "The scanner can handle the majority of C headers fine. In the case of " "receiving warnings from the scanner that look like a special case, one can " @@ -1253,12 +1270,12 @@ msgstr "" "παραλείψει. <_:example-1/>" #. (itstool) path: note/title -#: C/index.docbook:719 +#: C/index.docbook:725 msgid "Limitations" msgstr "Περιορισμοί" #. (itstool) path: note/para -#: C/index.docbook:720 +#: C/index.docbook:726 msgid "" "Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but " "not #if !defined(__GTK_DOC_IGNORE__) or other combinations." @@ -1268,12 +1285,12 @@ msgstr "" "συνδυασμούς." #. (itstool) path: sect1/title -#: C/index.docbook:730 +#: C/index.docbook:736 msgid "Documentation comments" msgstr "Σχόλια τεκμηρίωσης" #. (itstool) path: example/programlisting -#: C/index.docbook:736 +#: C/index.docbook:742 #, no-wrap msgid "" "\n" @@ -1289,7 +1306,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:732 +#: C/index.docbook:738 msgid "" "A multiline comment that starts with an additional '*' marks a documentation " "block that will be processed by the GTK-Doc tools. <_:example-1/>" @@ -1299,7 +1316,7 @@ msgstr "" "Doc. <_:example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:745 +#: C/index.docbook:751 msgid "" "The 'identifier' is one line with the name of the item the comment is " "related to. The syntax differs a little depending on the item. (TODO add " @@ -1310,7 +1327,7 @@ msgstr "" "στοιχείου. (ΜΕΛΛΟΝΤΙΚΑ: να προστεθεί πίνακας με τα αναγνωριστικά)" #. (itstool) path: sect1/para -#: C/index.docbook:751 +#: C/index.docbook:757 msgid "" "The 'documentation' block is also different for each symbol type. Symbol " "types that get parameters such as functions or macros have the parameter " @@ -1331,7 +1348,7 @@ msgstr "" "κώδικα)." #. (itstool) path: listitem/para -#: C/index.docbook:768 +#: C/index.docbook:774 msgid "" "What it is: The name for a class or function can sometimes be misleading for " "people coming from a different background." @@ -1340,26 +1357,26 @@ msgstr "" "παραπλανητικό για ανθρώπους που δεν έχουν τεχνογνωσία στο θέμα." #. (itstool) path: listitem/para -#: C/index.docbook:774 +#: C/index.docbook:780 msgid "" "What it does: Tell about common uses. Put it in relation with the other API." msgstr "" "Τι κάνει: Αναφέρει τις κοινές χρήσεις και τις βάζει σε σχέση με άλλο API." #. (itstool) path: tip/para -#: C/index.docbook:764 +#: C/index.docbook:770 msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" msgstr "Όταν τεκμηριώνετε κώδικα, περιγράψτε δύο πλευρές: <_:itemizedlist-1/>" #. (itstool) path: listitem/para -#: C/index.docbook:789 +#: C/index.docbook:795 msgid "Use function() to refer to functions or macros which take arguments." msgstr "" "Χρησιμοποιήστε το function() για να αναφερθείτε σε συναρτήσεις ή " "μακροεντολές που δέχονται ορίσματα." #. (itstool) path: listitem/para -#: C/index.docbook:794 +#: C/index.docbook:800 msgid "" "Use @param to refer to parameters. Also use this when referring to " "parameters of other functions, related to the one being described." @@ -1369,14 +1386,14 @@ msgstr "" "συναρτήσεων, σχετικών με την περιγραφόμενη." #. (itstool) path: listitem/para -#: C/index.docbook:800 +#: C/index.docbook:806 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "" "Χρησιμοποιήστε το %constant για να αναφερθείτε σε σταθερές, π.χ. " "%G_TRAVERSE_LEAFS." #. (itstool) path: listitem/para -#: C/index.docbook:805 +#: C/index.docbook:811 msgid "" "Use #symbol to refer to other types of symbol, e.g. structs and enums and " "macros which don't take arguments." @@ -1385,20 +1402,20 @@ msgstr "" "δομές, αριθμήσεις και μακροεντολές που δε δέχονται ορίσματα." #. (itstool) path: listitem/para -#: C/index.docbook:811 +#: C/index.docbook:817 msgid "Use #Object::signal to refer to a GObject signal." msgstr "" "Χρησιμοποιήστε το #Object::signal για να αναφερθείτε σε ένα σήμα GObject." #. (itstool) path: listitem/para -#: C/index.docbook:816 +#: C/index.docbook:822 msgid "Use #Object:property to refer to a GObject property." msgstr "" "Χρησιμοποιήστε το #Object::property για να αναφερθείτε σε μία ιδιότητα " "GObject." #. (itstool) path: listitem/para -#: C/index.docbook:821 +#: C/index.docbook:827 msgid "" "Use #Struct.field to refer to a field inside a structure and #GObjectClass." "foo_bar() to refer to a vmethod." @@ -1407,7 +1424,7 @@ msgstr "" "δομή και #GObjectClass.foo_bar() για να αναφερθείτε σε μια vmethod." #. (itstool) path: sect1/para -#: C/index.docbook:783 +#: C/index.docbook:789 msgid "" "One advantage of hyper-text over plain-text is the ability to have links in " "the document. Writing the correct markup for a link can be tedious though. " @@ -1421,7 +1438,7 @@ msgstr "" "<_:itemizedlist-1/>" #. (itstool) path: tip/para -#: C/index.docbook:830 +#: C/index.docbook:836 msgid "" "If you need to use the special characters '<', '>', '()', '@', '%', or " "'#' in your documentation without GTK-Doc changing them you can use the XML " @@ -1437,7 +1454,7 @@ msgstr "" "διαφυγής." #. (itstool) path: sect1/para -#: C/index.docbook:839 +#: C/index.docbook:845 msgid "" "DocBook can do more than just links. One can also have lists, examples, " "headings, and images. As of version 1.20, the preferred way is to use a " @@ -1456,7 +1473,7 @@ msgstr "" "εμφανίζονται σαν γραμμές που αρχίζουν με μια παύλα." #. (itstool) path: sect1/para -#: C/index.docbook:850 +#: C/index.docbook:856 msgid "" "While markdown is now preferred one can mix both. One limitation here is " "that one can use docbook xml within markdown, but markdown within docbook " @@ -1468,7 +1485,7 @@ msgstr "" "υποστηρίζεται." #. (itstool) path: sect1/para -#: C/index.docbook:856 +#: C/index.docbook:862 msgid "" "In older GTK-Doc releases, if you need support for additional formatting, " "you would need to enable the usage of docbook XML tags inside doc-comments " @@ -1483,12 +1500,12 @@ msgstr "" "μέσα στο Makefile.am." #. (itstool) path: example/title -#: C/index.docbook:865 +#: C/index.docbook:871 msgid "GTK-Doc comment block using Markdown" msgstr "Μπλοκ σχολίου GTK-Doc χρησιμοποιώντας Markdown" #. (itstool) path: example/programlisting -#: C/index.docbook:866 +#: C/index.docbook:872 #, no-wrap msgid "" "\n" @@ -1564,7 +1581,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:905 +#: C/index.docbook:911 msgid "" "More examples of what markdown tags are supported can be found in the ." #. (itstool) path: tip/para -#: C/index.docbook:911 +#: C/index.docbook:917 msgid "" "As already mentioned earlier GTK-Doc is for documenting public API. Thus one " "cannot write documentation for static symbols. Nevertheless it is good to " @@ -1596,12 +1613,12 @@ msgstr "" "να εισαχθεί το όνομα του συμβόλου στην κατάλληλη θέση του αρχείου ενοτήτων." #. (itstool) path: sect1/title -#: C/index.docbook:925 +#: C/index.docbook:931 msgid "Documenting sections" msgstr "Τεκμηρίωση ενοτήτων" #. (itstool) path: sect1/para -#: C/index.docbook:927 +#: C/index.docbook:933 msgid "" "Each section of the documentation contains information about one class or " "module. To introduce the component one can write a section block. The short " @@ -1614,12 +1631,12 @@ msgstr "" "περιεχομένων. Όλα τα πεδία @fields είναι προαιρετικά." #. (itstool) path: example/title -#: C/index.docbook:935 +#: C/index.docbook:941 msgid "Section comment block" msgstr "Μπλοκ σχολίου ενότητας" #. (itstool) path: example/programlisting -#: C/index.docbook:936 +#: C/index.docbook:942 #, no-wrap msgid "" "\n" @@ -1651,12 +1668,12 @@ msgstr "" " */\n" #. (itstool) path: varlistentry/term -#: C/index.docbook:955 +#: C/index.docbook:961 msgid "SECTION:<name>" msgstr "SECTION:<name>" #. (itstool) path: listitem/para -#: C/index.docbook:957 +#: C/index.docbook:963 msgid "" "The name links the section documentation to the respective part in the " "<package>-sections.txt file. The name give here " @@ -1669,12 +1686,12 @@ msgstr "" "<package>-sections.txt." #. (itstool) path: varlistentry/term -#: C/index.docbook:966 +#: C/index.docbook:972 msgid "@short_description" msgstr "@short_description" #. (itstool) path: listitem/para -#: C/index.docbook:968 +#: C/index.docbook:974 msgid "" "A one line description of the section, that later will appear after the " "links in the TOC and at the top of the section page." @@ -1684,12 +1701,12 @@ msgstr "" "της ενότητας." #. (itstool) path: varlistentry/term -#: C/index.docbook:975 +#: C/index.docbook:981 msgid "@title" msgstr "@title" #. (itstool) path: listitem/para -#: C/index.docbook:977 +#: C/index.docbook:983 msgid "" "The section title defaults to <name> from the SECTION declaration. It " "can be overridden with the @title field." @@ -1698,12 +1715,12 @@ msgstr "" "SECTION. Μπορεί να παρακαμφθεί με το πεδίο @title." #. (itstool) path: varlistentry/term -#: C/index.docbook:984 +#: C/index.docbook:990 msgid "@section_id" msgstr "@section_id" #. (itstool) path: listitem/para -#: C/index.docbook:986 +#: C/index.docbook:992 msgid "" "Overrides the use of title as a section identifier. For GObjects the <" "title> is used as a section_id and for other sections it is <" @@ -1714,22 +1731,22 @@ msgstr "" "άλλες ενότητες είναι <MODULE>-<title>." #. (itstool) path: varlistentry/term -#: C/index.docbook:994 +#: C/index.docbook:1000 msgid "@see_also" msgstr "@see_also" #. (itstool) path: listitem/para -#: C/index.docbook:996 +#: C/index.docbook:1002 msgid "A list of symbols that are related to this section." msgstr "Λίστα συμβόλων σχετικών με αυτή την ενότητα." #. (itstool) path: varlistentry/term -#: C/index.docbook:1002 +#: C/index.docbook:1008 msgid "@stability" msgstr "@stability" #. (itstool) path: listitem/para -#: C/index.docbook:1009 +#: C/index.docbook:1015 msgid "" "Stable - The intention of a Stable interface is to enable arbitrary third " "parties to develop applications to these interfaces, release them, and have " @@ -1747,7 +1764,7 @@ msgstr "" "λόγους." #. (itstool) path: listitem/para -#: C/index.docbook:1021 +#: C/index.docbook:1027 msgid "" "Unstable - Unstable interfaces are experimental or transitional. They are " "typically used to give outside developers early access to new or rapidly " @@ -1762,7 +1779,7 @@ msgstr "" "συμβατότητας μεταξύ μιας ελάσσονας έκδοσης και της επόμενης." #. (itstool) path: listitem/para -#: C/index.docbook:1033 +#: C/index.docbook:1039 msgid "" "Private - An interface that can be used within the GNOME stack itself, but " "that is not documented for end-users. Such functions should only be used in " @@ -1774,7 +1791,7 @@ msgstr "" "σαφώς καθορισμένων και τεκμηριωμένων διαδικασιών." #. (itstool) path: listitem/para -#: C/index.docbook:1042 +#: C/index.docbook:1048 msgid "" "Internal - An interface that is internal to a module and does not require " "end-user documentation. Functions that are undocumented are assumed to be " @@ -1785,7 +1802,7 @@ msgstr "" "περιέχουν τεκμηρίωση εκλαμβάνονται ως εσωτερικές." #. (itstool) path: listitem/para -#: C/index.docbook:1004 +#: C/index.docbook:1010 msgid "" "An informal description of the stability level this API has. We recommend " "the use of one of these terms: <_:itemizedlist-1/>" @@ -1794,12 +1811,12 @@ msgstr "" "συνιστούμε τη χρήση ενός από τους ακόλουθους όρους: <_:itemizedlist-1/>" #. (itstool) path: varlistentry/term -#: C/index.docbook:1054 +#: C/index.docbook:1060 msgid "@include" msgstr "@include" #. (itstool) path: listitem/para -#: C/index.docbook:1056 +#: C/index.docbook:1062 msgid "" "The #include files to show in the section synopsis (a " "comma separated list), overriding the global value from the ή στη γραμμή εντολών. Πρόκειται για προαιρετικό στοιχείο." #. (itstool) path: varlistentry/term -#: C/index.docbook:1065 +#: C/index.docbook:1071 msgid "@image" msgstr "@image" #. (itstool) path: listitem/para -#: C/index.docbook:1067 +#: C/index.docbook:1073 msgid "" "The image to display at the top of the reference page for this section. This " "will often be some sort of a diagram to illustrate the visual appearance of " @@ -1830,7 +1847,7 @@ msgstr "" "καταχώρηση είναι προαιρετική." #. (itstool) path: tip/para -#: C/index.docbook:1078 +#: C/index.docbook:1084 msgid "" "To avoid unnecessary recompilation after doc-changes put the section docs " "into the c-source where possible." @@ -1840,12 +1857,12 @@ msgstr "" "αρχείο του πηγαίου κώδικα, όπου αυτό είναι δυνατό." #. (itstool) path: sect1/title -#: C/index.docbook:1087 +#: C/index.docbook:1093 msgid "Documenting symbols" msgstr "Τεκμηρίωση συμβόλων" #. (itstool) path: sect1/para -#: C/index.docbook:1089 +#: C/index.docbook:1095 msgid "" "Each symbol (function, macro, struct, enum, signal and property) is " "documented in a separate block. The block is best placed close to the " @@ -1862,12 +1879,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1097 C/index.docbook:1163 +#: C/index.docbook:1103 C/index.docbook:1169 msgid "General tags" msgstr "Γενικές ετικέτες" #. (itstool) path: sect2/para -#: C/index.docbook:1099 +#: C/index.docbook:1105 msgid "" "You can add versioning information to all documentation elements to tell " "when an API was introduced, or when it was deprecated." @@ -1876,27 +1893,27 @@ msgstr "" "τεκμηρίωσης για να πείτε πότε εισήχθηκε ένα API, ή πότε καταργήθηκε." #. (itstool) path: variablelist/title -#: C/index.docbook:1104 +#: C/index.docbook:1110 msgid "Versioning Tags" msgstr "Εκδόσεις Ετικετών" #. (itstool) path: varlistentry/term -#: C/index.docbook:1105 +#: C/index.docbook:1111 msgid "Since:" msgstr "Από:" #. (itstool) path: listitem/para -#: C/index.docbook:1107 +#: C/index.docbook:1113 msgid "Description since which version of the code the API is available." msgstr "Περιγραφή οπό ποια έκδοση του κώδικα και μετά είναι διαθέσιμο το API." #. (itstool) path: varlistentry/term -#: C/index.docbook:1112 +#: C/index.docbook:1118 msgid "Deprecated:" msgstr "Παρωχημένη:" #. (itstool) path: listitem/para -#: C/index.docbook:1114 +#: C/index.docbook:1120 msgid "" "Paragraph denoting that this function should no be used anymore. The " "description should point the reader to the new API." @@ -1905,7 +1922,7 @@ msgstr "" "συνάρτησης. Η περιγραφή θα πρέπει να παραπέμπει τον αναγνώστη στο νέο API." #. (itstool) path: sect2/para -#: C/index.docbook:1122 +#: C/index.docbook:1128 msgid "" "You can also add stability information to all documentation elements to " "indicate whether API stability is guaranteed for them for all future minor " @@ -1916,7 +1933,7 @@ msgstr "" "για όλες τις μελλοντικές δευτερεύουσες εκδόσεις του έργου." #. (itstool) path: sect2/para -#: C/index.docbook:1128 +#: C/index.docbook:1134 msgid "" "The default stability level for all documentation elements can be set by " "passing the argument to " @@ -1928,17 +1945,17 @@ msgstr "" "τιμές." #. (itstool) path: variablelist/title -#: C/index.docbook:1134 +#: C/index.docbook:1140 msgid "Stability Tags" msgstr "Ετικέτες σταθερότητας" #. (itstool) path: varlistentry/term -#: C/index.docbook:1135 +#: C/index.docbook:1141 msgid "Stability: Stable" msgstr "Σταθερότητα: σταθερό" #. (itstool) path: listitem/para -#: C/index.docbook:1137 +#: C/index.docbook:1143 msgid "" "Mark the element as stable. This is for public APIs which are guaranteed to " "remain stable for all future minor releases of the project." @@ -1948,12 +1965,12 @@ msgstr "" "εκδόσεις του έργου." #. (itstool) path: varlistentry/term -#: C/index.docbook:1144 +#: C/index.docbook:1150 msgid "Stability: Unstable" msgstr "Σταθερότητα: ασταθές" #. (itstool) path: listitem/para -#: C/index.docbook:1146 +#: C/index.docbook:1152 msgid "" "Mark the element as unstable. This is for public APIs which are released as " "a preview before being stabilised." @@ -1962,12 +1979,12 @@ msgstr "" "εκδίδονται ως μια προεπισκόπηση πριν να σταθεροποιηθούν." #. (itstool) path: varlistentry/term -#: C/index.docbook:1152 +#: C/index.docbook:1158 msgid "Stability: Private" msgstr "Σταθερότητα: προσωπική" #. (itstool) path: listitem/para -#: C/index.docbook:1154 +#: C/index.docbook:1160 msgid "" "Mark the element as private. This is for interfaces which can be used by " "tightly coupled modules, but not by arbitrary third parties." @@ -1977,7 +1994,7 @@ msgstr "" "μέρη." #. (itstool) path: example/programlisting -#: C/index.docbook:1164 +#: C/index.docbook:1170 #, no-wrap msgid "" "\n" @@ -2016,12 +2033,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1184 C/index.docbook:1194 +#: C/index.docbook:1190 C/index.docbook:1200 msgid "Annotations" msgstr "Σχόλια" #. (itstool) path: sect2/para -#: C/index.docbook:1186 +#: C/index.docbook:1192 msgid "" "Documentation blocks can contain annotation-tags. These tags will be " "rendered with tooltips describing their meaning. The tags are used by " @@ -2037,7 +2054,7 @@ msgstr "" "Annotations\" type=\"http\">η βίκι." #. (itstool) path: example/programlisting -#: C/index.docbook:1195 +#: C/index.docbook:1201 #, no-wrap msgid "" "\n" @@ -2078,12 +2095,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1216 C/index.docbook:1245 +#: C/index.docbook:1222 C/index.docbook:1251 msgid "Function comment block" msgstr "Ομάδα σχολίων συνάρτησης" #. (itstool) path: listitem/para -#: C/index.docbook:1222 +#: C/index.docbook:1228 msgid "" "Document whether returned objects, lists, strings, etc, should be freed/" "unrefed/released." @@ -2092,26 +2109,26 @@ msgstr "" "λπ, θα πρέπει να ελευθερώνονται, να μην ελευθερώνονται ή να απορρίπτονται." #. (itstool) path: listitem/para -#: C/index.docbook:1228 +#: C/index.docbook:1234 msgid "Document whether parameters can be NULL, and what happens if they are." msgstr "" "Τεκμηριώσετε κατά πόσο οι παράμετροι μπορούν να είναι μηδενικές (NULL) και " "τι συμβαίνει αν είναι." #. (itstool) path: listitem/para -#: C/index.docbook:1233 +#: C/index.docbook:1239 msgid "" "Mention interesting pre-conditions and post-conditions where appropriate." msgstr "" "Αναφέρετε ενδιαφέρουσες προ-καταστάσεις και μετα-καταστάσεις όπου χρειάζεται." #. (itstool) path: sect2/para -#: C/index.docbook:1218 C/index.docbook:1304 +#: C/index.docbook:1224 C/index.docbook:1310 msgid "Please remember to: <_:itemizedlist-1/>" msgstr "Παρακαλούμε να θυμηθείτε να: <_:itemizedlist-1/>" #. (itstool) path: sect2/para -#: C/index.docbook:1240 +#: C/index.docbook:1246 msgid "" "Gtk-doc assumes all symbols (macros, functions) starting with '_' are " "private. They are treated like static functions." @@ -2121,7 +2138,7 @@ msgstr "" "συναρτήσεις." #. (itstool) path: example/programlisting -#: C/index.docbook:1246 +#: C/index.docbook:1252 #, no-wrap msgid "" "\n" @@ -2163,27 +2180,27 @@ msgstr "" " */\n" #. (itstool) path: variablelist/title -#: C/index.docbook:1267 +#: C/index.docbook:1273 msgid "Function tags" msgstr "Ετικέτες συναρτήσεων" #. (itstool) path: varlistentry/term -#: C/index.docbook:1268 +#: C/index.docbook:1274 msgid "Returns:" msgstr "Επιστροφές:" #. (itstool) path: listitem/para -#: C/index.docbook:1270 +#: C/index.docbook:1276 msgid "Paragraph describing the returned result." msgstr "Παράγραφος που περιγράφει το επιστρεφόμενο αποτέλεσμα." #. (itstool) path: varlistentry/term -#: C/index.docbook:1275 +#: C/index.docbook:1281 msgid "@...:" msgstr "@...:" #. (itstool) path: listitem/para -#: C/index.docbook:1277 +#: C/index.docbook:1283 msgid "" "In case the function has variadic arguments, you should use this tag " "(@Varargs: does also work for historic reasons)." @@ -2194,12 +2211,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1287 C/index.docbook:1289 +#: C/index.docbook:1293 C/index.docbook:1295 msgid "Property comment block" msgstr "Ομάδα σχολίων ιδιότητας" #. (itstool) path: example/programlisting -#: C/index.docbook:1290 +#: C/index.docbook:1296 #, no-wrap msgid "" "\n" @@ -2220,12 +2237,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1302 C/index.docbook:1321 +#: C/index.docbook:1308 C/index.docbook:1327 msgid "Signal comment block" msgstr "Ομάδα σχολίων σήματος" #. (itstool) path: listitem/para -#: C/index.docbook:1308 +#: C/index.docbook:1314 msgid "" "Document when the signal is emitted and whether it is emitted before or " "after other signals." @@ -2234,12 +2251,12 @@ msgstr "" "άλλα σήματα." #. (itstool) path: listitem/para -#: C/index.docbook:1314 +#: C/index.docbook:1320 msgid "Document what an application might do in the signal handler." msgstr "Τεκμηριώστε τι μπορεί να κάνει μια εφαρμογή στον διαχειριστή σημάτων." #. (itstool) path: example/programlisting -#: C/index.docbook:1322 +#: C/index.docbook:1328 #, no-wrap msgid "" "\n" @@ -2270,12 +2287,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1339 C/index.docbook:1340 +#: C/index.docbook:1345 C/index.docbook:1346 msgid "Struct comment block" msgstr "Ομάδα σχολίων δομής" #. (itstool) path: example/programlisting -#: C/index.docbook:1341 +#: C/index.docbook:1347 #, no-wrap msgid "" "\n" @@ -2305,7 +2322,7 @@ msgstr "" "} FooWidget;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1356 +#: C/index.docbook:1362 msgid "" "Use /*< private >*/ before the private struct fields you " "want to hide. Use /*< public >*/ for the reverse " @@ -2316,7 +2333,7 @@ msgstr "" "public >*/για την αντίστροφη συμπεριφορά." #. (itstool) path: sect2/para -#: C/index.docbook:1362 +#: C/index.docbook:1368 msgid "" "If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" " "it will be considered private automatically and doesn't need to be mentioned " @@ -2327,7 +2344,7 @@ msgstr "" "των σχολίων." #. (itstool) path: sect2/para -#: C/index.docbook:1368 +#: C/index.docbook:1374 msgid "" "Struct comment blocks can also be used for GObjects and GObjectClasses. It " "is usually a good idea to add a comment block for a class, if it has " @@ -2348,12 +2365,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1380 C/index.docbook:1381 +#: C/index.docbook:1386 C/index.docbook:1387 msgid "Enum comment block" msgstr "Ομάδα σχολίων Enum" #. (itstool) path: example/programlisting -#: C/index.docbook:1382 +#: C/index.docbook:1388 #, no-wrap msgid "" "\n" @@ -2387,7 +2404,7 @@ msgstr "" "} Something;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1399 +#: C/index.docbook:1405 msgid "" "Use /*< private >*/ before the private enum values you " "want to hide. Use /*< public >*/ for the reverse " @@ -2398,12 +2415,12 @@ msgstr "" ">*/ για την αντίστροφη συμπεριφορά." #. (itstool) path: sect1/title -#: C/index.docbook:1409 +#: C/index.docbook:1415 msgid "Useful DocBook tags" msgstr "Χρήσιμες ετικέτες DocBook" #. (itstool) path: sect1/para -#: C/index.docbook:1411 +#: C/index.docbook:1417 msgid "" "Here are some DocBook tags which are most useful when documenting the code." msgstr "" @@ -2411,7 +2428,7 @@ msgstr "" "του κώδικα." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1420 +#: C/index.docbook:1426 #, no-wrap msgid "" "\n" @@ -2421,7 +2438,7 @@ msgstr "" "<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1416 +#: C/index.docbook:1422 msgid "" "To link to another section in the GTK docs: <_:informalexample-1/> The " "linkend is the SGML/XML id on the top item of the page you want to link to. " @@ -2438,7 +2455,7 @@ msgstr "" "υπάρχει συμμόρφωση με το SGML/XML." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1433 +#: C/index.docbook:1439 #, no-wrap msgid "" "\n" @@ -2448,7 +2465,7 @@ msgstr "" "<function>...</function>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1430 +#: C/index.docbook:1436 msgid "" "To refer to an external function, e.g. a standard C function: <_:" "informalexample-1/>" @@ -2457,7 +2474,7 @@ msgstr "" "informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1442 +#: C/index.docbook:1448 #, no-wrap msgid "" "\n" @@ -2477,7 +2494,7 @@ msgstr "" "</example>\n" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1453 +#: C/index.docbook:1459 #, no-wrap msgid "" "\n" @@ -2495,7 +2512,7 @@ msgstr "" "</informalexample>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1439 +#: C/index.docbook:1445 msgid "" "To include example code: <_:informalexample-1/> or possibly this, for very " "short code fragments which don't need a title: <_:informalexample-2/> For " @@ -2506,7 +2523,7 @@ msgstr "" "τελευταία περίπτωση το GTK-Doc υποστηρίζει επίσης μια συντόμευση: |[ ... ]|" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1472 +#: C/index.docbook:1478 #, no-wrap msgid "" "\n" @@ -2538,12 +2555,12 @@ msgstr "" "</itemizedlist>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1469 +#: C/index.docbook:1475 msgid "To include bulleted lists: <_:informalexample-1/>" msgstr "Συμπερίληψη λιστών με κουκκίδες: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1492 +#: C/index.docbook:1498 #, no-wrap msgid "" "\n" @@ -2561,7 +2578,7 @@ msgstr "" "</note>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1489 +#: C/index.docbook:1495 msgid "" "To include a note which stands out from the text: <_:informalexample-1/>" msgstr "" @@ -2569,7 +2586,7 @@ msgstr "" "informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1505 +#: C/index.docbook:1511 #, no-wrap msgid "" "\n" @@ -2579,12 +2596,12 @@ msgstr "" "<type>unsigned char</type>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1502 +#: C/index.docbook:1508 msgid "To refer to a type: <_:informalexample-1/>" msgstr "Για να αναφερθείτε σε έναν τύπο: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1514 +#: C/index.docbook:1520 #, no-wrap msgid "" "\n" @@ -2594,7 +2611,7 @@ msgstr "" "<structname>XFontStruct</structname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1511 +#: C/index.docbook:1517 msgid "" "To refer to an external structure (not one described in the GTK docs): <_:" "informalexample-1/>" @@ -2603,7 +2620,7 @@ msgstr "" "τεκμηρίωση GTK): <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1523 +#: C/index.docbook:1529 #, no-wrap msgid "" "\n" @@ -2613,12 +2630,12 @@ msgstr "" "<structfield>len</structfield>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1520 +#: C/index.docbook:1526 msgid "To refer to a field of a structure: <_:informalexample-1/>" msgstr "Για να αναφερθείτε σε ένα πεδίο μιας δομής: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1532 +#: C/index.docbook:1538 #, no-wrap msgid "" "\n" @@ -2628,7 +2645,7 @@ msgstr "" "<classname>GtkWidget</classname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1529 +#: C/index.docbook:1535 msgid "" "To refer to a class name, we could possibly use: <_:informalexample-1/> but " "you'll probably be using #GtkWidget instead (to automatically create a link " @@ -2641,7 +2658,7 @@ msgstr "" "linkend=\"documenting_syntax\">τις συντομεύσεις)." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1543 +#: C/index.docbook:1549 #, no-wrap msgid "" "\n" @@ -2651,12 +2668,12 @@ msgstr "" "<emphasis>This is important</emphasis>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1540 +#: C/index.docbook:1546 msgid "To emphasize text: <_:informalexample-1/>" msgstr "Χρήση έντονων χαρακτήρων: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1552 +#: C/index.docbook:1558 #, no-wrap msgid "" "\n" @@ -2666,12 +2683,12 @@ msgstr "" "<filename>/home/user/documents</filename>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1549 +#: C/index.docbook:1555 msgid "For filenames use: <_:informalexample-1/>" msgstr "Για ονόματα αρχείων χρησιμοποιήστε: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1561 +#: C/index.docbook:1567 #, no-wrap msgid "" "\n" @@ -2681,17 +2698,17 @@ msgstr "" "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1558 +#: C/index.docbook:1564 msgid "To refer to keys use: <_:informalexample-1/>" msgstr "Για να αναφερθείτε σε κλειδιά χρησιμοποιήστε: <_:informalexample-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1571 +#: C/index.docbook:1577 msgid "Filling the extra files" msgstr "Συμπλήρωση των επιπλέον αρχείων" #. (itstool) path: chapter/para -#: C/index.docbook:1573 +#: C/index.docbook:1579 msgid "" "There are a couple of extra files, that need to be maintained along with the " "inline source code comments: <package>.types, " @@ -2704,12 +2721,12 @@ msgstr "" "sgml), <package>-sections.txt." #. (itstool) path: sect1/title -#: C/index.docbook:1582 +#: C/index.docbook:1588 msgid "Editing the types file" msgstr "Επεξεργασία του αρχείου types" #. (itstool) path: sect1/para -#: C/index.docbook:1584 +#: C/index.docbook:1590 msgid "" "If your library or application includes GObjects, you want their signals, " "arguments/parameters and position in the hierarchy to be shown in the " @@ -2724,12 +2741,12 @@ msgstr "" "<package>.types." #. (itstool) path: example/title -#: C/index.docbook:1593 +#: C/index.docbook:1599 msgid "Example types file snippet" msgstr "Υπόδειγμα αποσπάσματος αρχείου types" #. (itstool) path: example/programlisting -#: C/index.docbook:1594 +#: C/index.docbook:1600 #, no-wrap msgid "" "\n" @@ -2749,7 +2766,7 @@ msgstr "" "gtk_arrow_get_type\n" #. (itstool) path: sect1/para -#: C/index.docbook:1605 +#: C/index.docbook:1611 msgid "" "Since GTK-Doc 1.8 gtkdoc-scan can generate this " "list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in " @@ -2763,12 +2780,12 @@ msgstr "" "types ούτε στη διανομή ούτε στον έλεγχο εκδόσεων." #. (itstool) path: sect1/title -#: C/index.docbook:1614 +#: C/index.docbook:1620 msgid "Editing the master document" msgstr "Επεξεργασία κύριου εγγράφου (master)" #. (itstool) path: sect1/para -#: C/index.docbook:1616 +#: C/index.docbook:1622 msgid "" "GTK-Doc produces documentation in DocBook SGML/XML. When processing the " "inline source comments, the GTK-Doc tools generate one documentation page " @@ -2782,7 +2799,7 @@ msgstr "" "ταξινομεί." #. (itstool) path: sect1/para -#: C/index.docbook:1623 +#: C/index.docbook:1629 msgid "" "While GTK-Doc creates a template master document for you, later runs will " "not touch it again. This means that one can freely structure the " @@ -2800,7 +2817,7 @@ msgstr "" "νέα καλούδια που εισήχθησαν εκεί." #. (itstool) path: tip/para -#: C/index.docbook:1633 +#: C/index.docbook:1639 msgid "" "Do not create tutorials as extra documents. Just write extra chapters. The " "benefit of directly embedding the tutorial for your library into the API " @@ -2815,7 +2832,7 @@ msgstr "" "καθίσταται πιθανότερη η ενημέρωση του εγχειριδίου μαζί με τη βιβλιοθήκη." #. (itstool) path: sect1/para -#: C/index.docbook:1642 +#: C/index.docbook:1648 msgid "" "So what are the things to change inside the master document? For a start is " "only a little. There are some placeholders (text in square brackets) there " @@ -2826,12 +2843,12 @@ msgstr "" "αγκυλών) που πρέπει να διευκρινήσετε." #. (itstool) path: example/title -#: C/index.docbook:1649 +#: C/index.docbook:1655 msgid "Master document header" msgstr "Κεφαλίδα κύριου εγγράφου" #. (itstool) path: example/programlisting -#: C/index.docbook:1650 +#: C/index.docbook:1656 #, no-wrap msgid "" "\n" @@ -2861,7 +2878,7 @@ msgstr "" " <title>[Insert title here]</title>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1666 +#: C/index.docbook:1672 msgid "" "In addition a few option elements are created in commented form. You can " "review these and enable them as you like." @@ -2870,12 +2887,12 @@ msgstr "" "να τα ελέγξετε και να τα ενεργοποιήσετε όπως θέλετε." #. (itstool) path: example/title -#: C/index.docbook:1672 +#: C/index.docbook:1678 msgid "Optional part in the master document" msgstr "Προαιρετικό τμήμα στο κύριο έγγραφο" #. (itstool) path: example/programlisting -#: C/index.docbook:1673 +#: C/index.docbook:1679 #, no-wrap msgid "" "\n" @@ -2889,7 +2906,7 @@ msgstr "" " --> \n" #. (itstool) path: sect1/para -#: C/index.docbook:1681 +#: C/index.docbook:1687 msgid "" "Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind " @@ -2901,12 +2918,12 @@ msgstr "" "έγγραφο." #. (itstool) path: example/title -#: C/index.docbook:1689 C/index.docbook:1724 +#: C/index.docbook:1695 C/index.docbook:1730 msgid "Including generated sections" msgstr "Συμπερίληψη των δημιουργούμενων ενοτήτων" #. (itstool) path: example/programlisting -#: C/index.docbook:1690 +#: C/index.docbook:1696 #, no-wrap msgid "" "\n" @@ -2922,12 +2939,12 @@ msgstr "" " ...\n" #. (itstool) path: sect1/title -#: C/index.docbook:1702 +#: C/index.docbook:1708 msgid "Editing the section file" msgstr "Επεξεργασία αρχείου ενοτήτων" #. (itstool) path: sect1/para -#: C/index.docbook:1704 +#: C/index.docbook:1710 msgid "" "The section file is used to organise the documentation output by GTK-Doc. " "Here one specifies which symbol belongs to which module or class and control " @@ -2938,7 +2955,7 @@ msgstr "" "σύμβολο και αποφασίζεται η ορατότητά του (αν θα είναι δημόσιο ή ιδιωτικό)." #. (itstool) path: sect1/para -#: C/index.docbook:1710 +#: C/index.docbook:1716 msgid "" "The section file is a plain text file with tags delimiting sections. Blank " "lines are ignored and lines starting with a '#' are treated as comment lines." @@ -2948,7 +2965,7 @@ msgstr "" "αντιμετωπίζονται ως γραμμές σχολίων." #. (itstool) path: note/para -#: C/index.docbook:1717 +#: C/index.docbook:1723 msgid "" "While the tags make the file look like xml, it is not. Please do not close " "tags like <SUBSECTION>." @@ -2957,7 +2974,7 @@ msgstr "" "είναι. Παρακαλούμε μην κλείνετε τις ετικέτες όπως <SUBSECTION>." #. (itstool) path: example/programlisting -#: C/index.docbook:1725 +#: C/index.docbook:1731 #, no-wrap msgid "" "\n" @@ -2989,7 +3006,7 @@ msgstr "" "</SECTION>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1742 +#: C/index.docbook:1748 msgid "" "The <FILE> ... </FILE> tag is used to specify the file name, " "without any suffix. For example, using '<FILE>gnome-config</" @@ -3012,7 +3029,7 @@ msgstr "" "κλάσης GObjects που μετατράπηκε σε πεζά γράμματα)." #. (itstool) path: sect1/para -#: C/index.docbook:1754 +#: C/index.docbook:1760 msgid "" "The <TITLE> ... </TITLE> tag is used to specify the title of the " "section. It is only useful before the templates (if used) are initially " @@ -3026,7 +3043,7 @@ msgstr "" "αυτό είναι παρωχημένο." #. (itstool) path: sect1/para -#: C/index.docbook:1761 +#: C/index.docbook:1767 msgid "" "You can group items in the section by using the <SUBSECTION> tag. " "Currently it outputs a blank line between subsections in the synopsis " @@ -3058,7 +3075,7 @@ msgstr "" "(μεταβλητές,vmethods)." #. (itstool) path: sect1/para -#: C/index.docbook:1780 +#: C/index.docbook:1786 msgid "" "You can also use <INCLUDE> ... </INCLUDE> to specify the " "#include files which are shown in the synopsis sections. It contains a comma-" @@ -3075,12 +3092,12 @@ msgstr "" "μόνο τη συγκεκριμένη ενότητα. " #. (itstool) path: chapter/title -#: C/index.docbook:1794 +#: C/index.docbook:1800 msgid "Controlling the result" msgstr "Έλεγχος αποτελέσματος" #. (itstool) path: chapter/para -#: C/index.docbook:1796 +#: C/index.docbook:1802 msgid "" "A GTK-Doc run generates report files inside the documentation directory. The " "generated files are named: <package>-undocumented.txt. Είναι αρχεία απλού κειμένου, εύκολα στην ανάγνωση και επεξεργασία." #. (itstool) path: chapter/para -#: C/index.docbook:1805 +#: C/index.docbook:1811 msgid "" "The <package>-undocumented.txt file starts with " "the documentation coverage summary. Below are two sections divided by blank " @@ -3112,7 +3129,7 @@ msgstr "" "προστέθηκε μια νέα παράμετρος." #. (itstool) path: chapter/para -#: C/index.docbook:1814 +#: C/index.docbook:1820 msgid "" "The <package>-undeclared.txt file lists symbols " "given in the <package>-sections.txt but not found " @@ -3124,7 +3141,7 @@ msgstr "" "έχουν αφαιρεθεί ή αν περιέχουν συντακτικά λάθη." #. (itstool) path: chapter/para -#: C/index.docbook:1821 +#: C/index.docbook:1827 msgid "" "The <package>-unused.txt file lists symbol names, " "where the GTK-Doc scanner has found documentation, but does not know where " @@ -3137,7 +3154,7 @@ msgstr "" "προστεθεί ακόμη στο αρχείο <package>-sections.txt." #. (itstool) path: tip/para -#: C/index.docbook:1829 +#: C/index.docbook:1835 msgid "" "Enable or add the line in Makefile." "am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during " @@ -3149,7 +3166,7 @@ msgstr "" "make check." #. (itstool) path: chapter/para -#: C/index.docbook:1836 +#: C/index.docbook:1842 msgid "" "One can also look at the files produced by the source code scanner: " "<package>-decl-list.txt and <" @@ -3166,7 +3183,7 @@ msgstr "" "περιέχεται σε αυτό το αρχείο." #. (itstool) path: chapter/para -#: C/index.docbook:1845 +#: C/index.docbook:1851 msgid "" "If the project is GObject based, one can also look into the files produced " "by the object scanner: <package>.args.txt, " @@ -3188,12 +3205,12 @@ msgstr "" "GTK_DOC_KEEP_INTERMEDIATE=1 make." #. (itstool) path: chapter/title -#: C/index.docbook:1860 +#: C/index.docbook:1866 msgid "Modernizing the documentation" msgstr "Εκσυγχρονίζοντας την τεκμηρίωση" #. (itstool) path: chapter/para -#: C/index.docbook:1862 +#: C/index.docbook:1868 msgid "" "GTK-Doc has been around for quite some time. In this section we list new " "features together with the version since when it is available." @@ -3203,12 +3220,12 @@ msgstr "" "διαθέσιμες." #. (itstool) path: sect1/title -#: C/index.docbook:1868 +#: C/index.docbook:1874 msgid "GTK-Doc 1.9" msgstr "GTK-Doc 1.9" #. (itstool) path: sect1/para -#: C/index.docbook:1870 +#: C/index.docbook:1876 msgid "" "When using xml instead of sgml, one can actually name the master document " "<package>-docs.xml." @@ -3217,7 +3234,7 @@ msgstr "" "το κύριο έγγραφο <package>-docs.xml." #. (itstool) path: sect1/para -#: C/index.docbook:1875 +#: C/index.docbook:1881 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3239,7 +3256,7 @@ msgstr "" "sections.txt." #. (itstool) path: sect1/para -#: C/index.docbook:1886 +#: C/index.docbook:1892 msgid "" "Version 1.8 already introduced the syntax for documenting sections in the " "sources instead of the separate files under και τελειώσατε." #. (itstool) path: sect1/title -#: C/index.docbook:1898 +#: C/index.docbook:1904 msgid "GTK-Doc 1.10" msgstr "GTK-Doc 1.10" #. (itstool) path: sect1/para -#: C/index.docbook:1900 +#: C/index.docbook:1906 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3283,17 +3300,17 @@ msgstr "" "am για τον κώδικα που δομείται υπό όρους." #. (itstool) path: sect1/title -#: C/index.docbook:1911 +#: C/index.docbook:1917 msgid "GTK-Doc 1.16" msgstr "GTK-Doc 1.16" #. (itstool) path: example/title -#: C/index.docbook:1917 +#: C/index.docbook:1923 msgid "Enable gtkdoc-check" msgstr "Ενεργοποίηση του gtkdoc-check" #. (itstool) path: example/programlisting -#: C/index.docbook:1918 +#: C/index.docbook:1924 #, no-wrap msgid "" "\n" @@ -3313,7 +3330,7 @@ msgstr "" "endif\n" #. (itstool) path: sect1/para -#: C/index.docbook:1913 +#: C/index.docbook:1919 msgid "" "This version includes a new tool called gtkdoc-check. This tool can run a " "set of sanity checks on your documentation. It is enabled by adding these " @@ -3325,12 +3342,12 @@ msgstr "" "Makefile.am. <_:example-1/>" #. (itstool) path: sect1/title -#: C/index.docbook:1931 +#: C/index.docbook:1937 msgid "GTK-Doc 1.20" msgstr "GTK-Doc 1.20" #. (itstool) path: sect1/para -#: C/index.docbook:1933 +#: C/index.docbook:1939 msgid "" "Version 1.18 brought some initial markdown support. Using markdown in doc " "comments is less intrusive than writing docbook xml. This version improves a " @@ -3344,17 +3361,17 @@ msgstr "" "\">σύνταξη σχολίων έχει όλες τις λεπτομέρειες." #. (itstool) path: sect1/title -#: C/index.docbook:1943 +#: C/index.docbook:1949 msgid "GTK-Doc 1.25" msgstr "GTK-Doc 1.25" #. (itstool) path: example/title -#: C/index.docbook:1953 +#: C/index.docbook:1959 msgid "Use pre-generated entities" msgstr "Χρήση προδημιουργημένων οντοτήτων" #. (itstool) path: example/programlisting -#: C/index.docbook:1954 +#: C/index.docbook:1960 #, no-wrap msgid "" "\n" @@ -3396,7 +3413,7 @@ msgstr "" " </bookinfo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1945 +#: C/index.docbook:1951 msgid "" "The makefiles shipped with this version generate an entity file at " "xml/gtkdocentities.ent, containing entities for e.g. " @@ -3417,12 +3434,12 @@ msgstr "" "xml σε όλα τα δημιουργημένα αρχεία xml. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1979 +#: C/index.docbook:1985 msgid "Documenting other interfaces" msgstr "Τεκμηρίωση άλλων διεπαφών" #. (itstool) path: chapter/para -#: C/index.docbook:1981 +#: C/index.docbook:1987 msgid "" "So far we have been using GTK-Doc to document the API of code. The next " "sections contain suggestions how the tools can be used to document other " @@ -3433,12 +3450,12 @@ msgstr "" "μπορούν να χρησιμοποιηθούν για να καταγράφετε και άλλες διεπαφές." #. (itstool) path: sect1/title -#: C/index.docbook:1988 +#: C/index.docbook:1994 msgid "Command line options and man pages" msgstr "Επιλογές γραμμής εντολών και σελίδες τεκμηρίωσης man" #. (itstool) path: sect1/para -#: C/index.docbook:1990 +#: C/index.docbook:1996 msgid "" "As one can generate man pages for a docbook refentry as well, it sounds like " "a good idea to use it for that purpose. This way the interface is part of " @@ -3450,12 +3467,12 @@ msgstr "" "δωρεάν την σελίδα-man." #. (itstool) path: sect2/title -#: C/index.docbook:1997 +#: C/index.docbook:2003 msgid "Document the tool" msgstr "Τεκμηρίωση του εργαλείου" #. (itstool) path: sect2/para -#: C/index.docbook:1999 +#: C/index.docbook:2005 msgid "" "Create one refentry file per tool. Following our example we would call it meep/" @@ -3470,17 +3487,17 @@ msgstr "" "αρχείο στον υποκατάλογο xml καθώς επίσης και τα παραδείγματα π.χ. στο glib." #. (itstool) path: sect2/title -#: C/index.docbook:2009 +#: C/index.docbook:2015 msgid "Adding the extra configure check" msgstr "Προσθήκη του έξτρα ελέγχου διαμόρφωσης" #. (itstool) path: example/title -#: C/index.docbook:2012 C/index.docbook:2030 +#: C/index.docbook:2018 C/index.docbook:2036 msgid "Extra configure checks" msgstr "Επιπλέον έλεγχοι ρυθμίσεων" #. (itstool) path: example/programlisting -#: C/index.docbook:2013 +#: C/index.docbook:2019 #, no-wrap msgid "" "\n" @@ -3502,12 +3519,12 @@ msgstr "" "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" #. (itstool) path: sect2/title -#: C/index.docbook:2027 +#: C/index.docbook:2033 msgid "Adding the extra makefile rules" msgstr "Προσθήκη των επιπλέον κανόνων makefile" #. (itstool) path: example/programlisting -#: C/index.docbook:2031 +#: C/index.docbook:2037 #, no-wrap msgid "" "\n" @@ -3543,12 +3560,12 @@ msgstr "" "EXTRA_DIST += meep.xml\n" #. (itstool) path: sect1/title -#: C/index.docbook:2053 +#: C/index.docbook:2059 msgid "DBus interfaces" msgstr "Διεπαφές DBus" #. (itstool) path: sect1/para -#: C/index.docbook:2055 +#: C/index.docbook:2061 msgid "" "(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" @@ -3557,27 +3574,27 @@ msgstr "" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" #. (itstool) path: chapter/title -#: C/index.docbook:2064 +#: C/index.docbook:2070 msgid "Frequently asked questions" msgstr "Συχνές ερωτήσεις" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2068 +#: C/index.docbook:2074 msgid "Question" msgstr "Ερώτηση" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2069 +#: C/index.docbook:2075 msgid "Answer" msgstr "Απάντηση" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2071 +#: C/index.docbook:2077 msgid "No class hierarchy." msgstr "Δεν υπάρχει ιεραρχία κλάσεων." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2072 +#: C/index.docbook:2078 msgid "" "The objects xxx_get_type() function has not been " "entered into the <package>.types file." @@ -3586,12 +3603,12 @@ msgstr "" "εισαχθεί στο αρχείο <package>.types" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2078 +#: C/index.docbook:2084 msgid "Still no class hierarchy." msgstr "Εξακολουθεί να μην υπάρχει ιεραρχία κλάσεων." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2079 +#: C/index.docbook:2085 msgid "" "Missing or wrong naming in <package>-sections.txt " "file (see αιτιολόγηση)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2085 +#: C/index.docbook:2091 msgid "Damn, I have still no class hierarchy." msgstr "Στο καλό του, πάλι δεν έχω ιεραρχία κλάσεων." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2086 +#: C/index.docbook:2092 msgid "" "Is the object name (name of the instance struct, e.g. GtkWidget) part of the normal section (don't put this into Standard or Private " @@ -3619,12 +3636,12 @@ msgstr "" "Private)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2093 +#: C/index.docbook:2099 msgid "No symbol index." msgstr "Δεν υπάρχει ευρετήριο συμβόλων." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2094 +#: C/index.docbook:2100 msgid "" "Does the <package>-docs.{xml,sgml} contain a " "index that xi:includes the generated index?" @@ -3633,14 +3650,14 @@ msgstr "" "ευρετήριο το οποίο περιλαμβάνει με xi:includes το παραγόμενο ευρετήριο;" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2100 +#: C/index.docbook:2106 msgid "Symbols are not linked to their doc-section." msgstr "" "Δεν υπάρχουν σύνδεσμοι μεταξύ των συμβόλων και των κατάλληλων ενοτήτων της " "τεκμηρίωσης." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2101 +#: C/index.docbook:2107 msgid "" "Is the doc-comment using the correct markup (added #,% or ())? Check if the " "gtkdoc-fixxref warns about unresolvable xrefs." @@ -3649,12 +3666,12 @@ msgstr "" "()); Ελέγξτε αν το gtkdoc-fixxref προειδοποιεί για ανεπίλυτα xrefs." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2107 +#: C/index.docbook:2113 msgid "A new class does not appear in the docs." msgstr "Μια νέα κλάση δεν εμφανίζεται στην τεκμηρίωση." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2108 +#: C/index.docbook:2114 msgid "" "Is the new page xi:included from <package>-docs.{xml,sgml}." @@ -3663,12 +3680,12 @@ msgstr "" "docs.{xml,sgml};" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2114 +#: C/index.docbook:2120 msgid "A new symbol does not appear in the docs." msgstr "Ένα νέο σύμβολο δεν εμφανίζεται στην τεκμηρίωση." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2115 +#: C/index.docbook:2121 msgid "" "Is the doc-comment properly formatted. Check for spelling mistakes in the " "begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable " @@ -3681,12 +3698,12 @@ msgstr "" "<package>-sections.txt σε μια δημόσια υποενότητα." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2123 +#: C/index.docbook:2129 msgid "A type is missing from the class hierarchy." msgstr "Λείπει ένας τύπος από την ιεραρχία κλάσεων." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2124 +#: C/index.docbook:2130 msgid "" "If the type is listed in <package>.hierarchy but " "not in xml/tree_index.sgml then double check that the " @@ -3702,12 +3719,12 @@ msgstr "" "εμφανιστεί." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2133 +#: C/index.docbook:2139 msgid "I get foldoc links for all gobject annotations." msgstr "Λαμβάνω συνδέσμους foldoc για όλες τις σημειώσεις gobject." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2134 +#: C/index.docbook:2140 msgid "" "Check that xml/annotation-glossary.xml is xi:included " "from <package>-docs.{xml,sgml}." @@ -3716,13 +3733,13 @@ msgstr "" "included από το <package>-docs.{xml,sgml}." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2142 +#: C/index.docbook:2148 msgid "Parameter described in source code comment block but does not exist" msgstr "" "Μια παράμετρος περιγράφεται σε σχόλιο του πηγαίου κώδικα, αλλά δεν υπάρχει" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2143 +#: C/index.docbook:2149 msgid "" "Check if the prototype in the header has different parameter names as in the " "source." @@ -3731,12 +3748,12 @@ msgstr "" "παράμετρο από αυτό που αναφέρεται στον κώδικα." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2148 +#: C/index.docbook:2154 msgid "multiple \"IDs\" for constraint linkend: XYZ" msgstr "Πολλαπλά \"Αναγνωριστικά\" για τον προορισμό συνδέσμου: XYZ" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2149 +#: C/index.docbook:2155 msgid "" "Symbol XYZ appears twice in <package>-sections.txt file." @@ -3745,7 +3762,7 @@ msgstr "" "sections.txt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2152 +#: C/index.docbook:2158 msgid "" "Element typename in namespace '' encountered in para, but no template " "matches." @@ -3754,12 +3771,12 @@ msgstr "" "αντιστοιχεί σε κανένα πρότυπο." #. (itstool) path: chapter/title -#: C/index.docbook:2159 +#: C/index.docbook:2165 msgid "Tools related to gtk-doc" msgstr "Εργαλεία σχετικά με το gtk-doc" #. (itstool) path: chapter/para -#: C/index.docbook:2161 +#: C/index.docbook:2167 msgid "" "GtkDocPlugin - a Trac " "GTK-Doc integration plugin, that adds API docs to a trac site and " @@ -3770,7 +3787,7 @@ msgstr "" "ιστοσελίδες trac και ενσωματώνεται με την αναζήτηση trac." #. (itstool) path: chapter/para -#: C/index.docbook:2166 +#: C/index.docbook:2172 msgid "" "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " "tags in the API to determine the minimum required version." diff --git a/help/manual/el/index.docbook b/help/manual/el/index.docbook index 650d233..24da785 100644 --- a/help/manual/el/index.docbook +++ b/help/manual/el/index.docbook @@ -34,7 +34,8 @@ - 1.24.1 30 Μαΐου 2015 ss έκδοση ανάπτυξης + 1.25.1 21 Μαρτίου 2016 ss έκδοση ανάπτυξης + 1.25 21 Μαρτίου 2016 ss διορθώσεις σφαλμάτων, εκαθάρριση δοκιμαστικού κώδικα 1.24 29 Μαΐου 2015 ss διόρθωση σφαλμάτων 1.23 17 Μαΐου 2015 ss διόρθωση σφαλμάτων 1.22 07 Μαΐου 2015 ss διορθώσεις σφαλμάτων, απόρριψη παρωχημένων λειτουργιών @@ -60,7 +61,7 @@ - 2009-2015 + 2009-2016 Ελληνική μεταφραστική ομάδα GNOME @@ -82,7 +83,7 @@ Θάνος Τρυφωνίδης - tomtryf@gmail.com + tomtryf@gnome.org @@ -90,6 +91,8 @@ 2015 + 2016 + Θάνος Τρυφωνίδης @@ -167,13 +170,6 @@ Το gtkdoc-scanobj δεν πρέπει να χρησιμοποιείται πλέον. Χρειαζόταν στο παρελθόν όταν το GObject ήταν ακόμα GtkObject μέσα στη gtk+. - - Δημιουργία "πρότυπων" αρχείων Το gtkdoc-mktmpl παράγει μια σειρά από αρχεία στον υποκατάλογο tmpl/, χρησιμοποιώντας τις πληροφορίες που συλλέχθηκαν κατά το πρώτο στάδιο. (Σημειώστε ότι μπορεί να εκτελεσθεί περισσότερες από μία φορές. Προσπαθεί να διασφαλίσει ότι δεν χάνεται ποτέ και κανενός είδους τεκμηρίωση.) - - Από την έκδοση GTK-Doc 1.9 και μετά, τα πρότυπα αρχεία δεν είναι πλέον απαραίτητα. Σας συνιστούμε να διατηρείτε την τεκμηρίωση στον κώδικα. Το gtkdocize υποστηρίζει πλέον την επιλογή η οποία επιλέγει ένα αρχείο makefile που δεν χρησιμοποιεί καθόλου πρότυπα tmpl. Αν δεν έχετε κάνει ποτέ αλλαγές με το χέρι σε αρχεία προτύπων tmpl, παρακαλώ αφαιρέστε τον κατάλογο (π.χ. από ένα σύστημα ελέγχου εκδόσεων). - - - Δημιουργία του XML και του HTML/PDF. Το gtkdoc-mkdb μετατρέπει τα αρχεία προτύπων σε αρχεία XML στον υποκατάλογο xml/. Αν ο πηγαίος κώδικας περιέχει τεκμηρίωση συναρτήσεων, χρησιμοποιώντας τις ειδικές ομάδες σχολίων, συγχωνεύεται εδώ. Αν δεν υπάρχουν χρησιμοποιούμενα αρχεία tmpl, διαβάζει μόνο έγγραφα από τα δεδομένα πηγών και αυτοελέγχου. Το gtkdoc-mkhtml μετατρέπει τα αρχεία XML σε αρχεία HTML στον υποκατάλογο html/. Ομοίως, το gtkdoc-mkpdf μετατρέπει τα αρχεία XML σε ένα έγγραφο PDF που ονομάζεται <package>.pdf. @@ -281,7 +277,12 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) Το GTK-Doc είναι απενεργοποιημένο από προεπιλογή! Να θυμάστε να χρησιμοποιείτε την επιλογή στην επόμενη εκτέλεση του configure. Διαφορετικά, εγκαθίσταται η προπαραχθείσα τεκμηρίωση (δυνατότητα χρήσιμη για τον χρήστη, αλλά όχι για τον προγραμματιστή). - Επίσης, συνιστάται να προσθέσετε την ακόλουθη γραμμή στη δέσμη ενεργειών configure.ac. Αυτό επιτρέπει στο gtkdocize να αντιγράφει αυτόματα τον ορισμό της μακροεντολής για το GTK_DOC_CHECK στο έργο σας. + + 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. + Προετοιμασία για το gtkdocize @@ -370,20 +371,12 @@ 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 - Ενσωμάτωση με συστήματα δόμησης 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. @@ -401,9 +394,8 @@ add_custom_target(documentation ALL DEPENDS doc-libmeep) # to set the CMAKE_INSTALL_DOCDIR variable correctly). install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - + + @@ -570,7 +562,12 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html SECTION:<name> - Το name συνδέει την τεκμηρίωση της ενότητας με το αντίστοιχο μέρος στο αρχείο <package>-sections.txt. Το όνομα που δίνεται εδώ πρέπει να ταιριάζει με την ετικέτα <FILE> στο αρχείο <package>-sections.txt. + + The name links the section documentation to the respective part in + the <package>-sections.txt file. The + name given here should match the <FILE> tag in the + <package>-sections.txt file. + @@ -873,6 +870,111 @@ typedef enum { + + + Inline program documentation + + You can document programs and their commandline interface using inline + documentation. + + + + Tags + + PROGRAM + + + + Defines the start of a program documentation. + + + + + + @short_description: + + + Defines a short description of the program. (Optional) + + + + + + @synopsis: + + + Defines the arguments, or list of arguments that the program can take. + (Optional) + + + + + + @see_also: + + + See Also manual page section. (Optional) + + + + + + @arg: + + + Argument(s) passed to the program and their description. (Optional) + + + + + + Description: + + + A longer description of the program. + + + + + + Επιστροφές: + + + Specificy what value(s) the program returns. (Optional) + + + + + + + + Example of program documentation. + Program documentation block + + + + + + Χρήσιμες ετικέτες DocBook @@ -1040,17 +1142,17 @@ gtk_arrow_get_type Επιπλέον κάποια στοιχεία επιλογής δημιουργούνται με μορφή σχολίου. Μπορείτε να τα ελέγξετε και να τα ενεργοποιήσετε όπως θέλετε. - + Προαιρετικό τμήμα στο κύριο έγγραφο - - <!-- ενεργοποιήστε το όταν χρησιμοποιείτε σχόλια αυτοελέγχου gobject - <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> - --> - + + --> +]]> - + Τέλος, χρειάζεται να προσθέσετε νέα ενότητα όποτε εισάγετε μία. Το εργαλείο gtkdoc-check θα σας θυμίσει τα νεοδημιουργούμενα αρχεία xml που δεν περιλαμβάνονται ακόμα στο έγγραφο. @@ -1072,7 +1174,7 @@ gtk_arrow_get_type Το αρχείο ενοτήτων χρησιμεύει στην οργάνωση της τεκμηρίωσης που παράγεται από το GTK-Doc. Εδώ διευκρινίζεται σε ποιο άρθρωμα ή κλάση ανήκει κάθε σύμβολο και αποφασίζεται η ορατότητά του (αν θα είναι δημόσιο ή ιδιωτικό). Το αρχείο ενοτήτων είναι ένα αρχείο απλού κειμένου με ετικέτες οριοθετημένων περιοχών. Οι κενές γραμμές αγνοούνται, ενώ οι γραμμές που ξεκινούν με '#' αντιμετωπίζονται ως γραμμές σχολίων. - + Ενώ οι ετικέτες δείχνουν πως είναι ένα αρχείο xml, στην πραγματικότητα δεν είναι. Παρακαλούμε μην κλείνετε τις ετικέτες όπως <SUBSECTION>. @@ -1127,22 +1229,30 @@ meep_app_get_type Αν το έργο βασίζεται στο GObject, μπορείτε επίσης να δείτε τα αρχεία που παράγονται από το σαρωτή αντικειμένων: <package>.args.txt, <package>.hierarchy.txt, <package>.interfaces.txt, <package>.prerequisites.txt και <package>.signals.txt. Αν υπάρχουν σύμβολα που λείπουν από οποιοδήποτε από αυτά, μπορείτε να ζητήσετε από το gtkdoc να κρατήσει το ενδιάμεσο αρχείο σάρωσης για περαιτέρω ανάλυση, εκτελώντας το ως μια εντολή GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Εκσυγχρονίζοντας την τεκμηρίωση - + Το GTK-Doc κυκλοφορεί εδώ και αρκετό καιρό. Σε αυτό το κεφάλαιο θα παραθέσουμε τις νέες λειτουργίες μαζί με την έκδοση στην οποία είναι διαθέσιμες. - + GTK-Doc 1.9 Όταν χρησιμοποιείτε το xml αντί για το sgml, μπορείτε πράγματι να ονομάσετε το κύριο έγγραφο <package>-docs.xml. - + Αυτή η έκδοση υποστηρίζει στο Makefile.am. Αν αυτό ενεργοποιηθεί, το <package>-sections.txt αυτοδημιουργείται και μπορεί να αφαιρεθεί από το vcs. Αυτό λειτουργεί καλά μόνο για έργα που έχουν μια πολύ κανονική δομή (π.χ. το κάθε ζεύγος .{c,h} θα δημιουργεί μια νέα ενότητα). Αν κάποιος οργανώσει ένα έργο κοντά σε αυτό, τότε η ενημέρωση μιας ενότητας αρχείων που συντηρούνται χειρονακτικά μπορεί να είναι τόσο απλή όσο και το να εκτελούμε meld <package>-decl-list.txt <package>-sections.txt. - - Η εκδοση 1.8 εισήγαγε ήδη τη σύνταξη για τις ενότητες τεκμηρίωσης στις πηγές, αντί για τα ξεχωριστά αρχεία, κάτω από το tmpl. Αυτή η έκδοση προσθέτει επιλογές για τη μετατροπή ολόκληρου του αρθρώματος doc ώστε να μη χρησιμοποιεί καθόλου το επιπλέον στάδιο δόμησης tmpl, με τη χρήση του στο configure.ac. Εάν δεν έχετε ένα tmpl σημειωμένο στο σύστημα ελέγχου πηγής και δεν έχετε ακόμα αλλάξει, προσθέστε απλά τη σημαία στο configure.ac και τελειώσατε. + + + 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. + - + GTK-Doc 1.10 @@ -1173,27 +1283,36 @@ endif GTK-Doc 1.25 - Τα αρχεία makefiles που έρχονται με αυτή την έκδοση παράγουν ένα αρχείο οντοτήτων στο xml/gtkdocentities.ent, το οποίο περιλαμβάνει οντότητες π.χ. package_name και package_version. Μπορείτε να το χρησιμοποιήσετε π.χ. στο κύριο αρχείο xml για να αποφύγετε τον στατικό ορισμό του αριθμού έκδοσης. Παρακάτω είναι ένα παράδειγμα που σας δείχνει πως συμπεριλαμβάνεται το αρχείο οντοτήτων και πως οι οντότητες χρησιμοποιούνται. Οι οντότητες μπορούν να χρησιμοποιηθούν και σε όλα τα δημιουργημένα αρχεία, καθώς το GTK-Doc θα χρησιμοποιήσει την ίδια κεφαλίδα xml σε όλα τα δημιουργημένα αρχεία xml. Χρήση προδημιουργημένων οντοτήτων - -<?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 + 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/en_GB/index.docbook b/help/manual/en_GB/index.docbook index b717189..32aa146 100644 --- a/help/manual/en_GB/index.docbook +++ b/help/manual/en_GB/index.docbook @@ -68,10 +68,16 @@ - 1.24.1 - 30 May 2015 + 1.25.1 + 21 March 2016 + ss + development version + + + 1.25 + 21 March 2016 ss - development version + bug fixes, test cleanups 1.24 @@ -219,27 +225,6 @@ - - - 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.) - - - - 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). - - - - Generating the XML and HTML/PDF. @@ -257,7 +242,7 @@ document called <package>.pdf. - Files in xml/ and + Files in xml/ and html/ directories are always overwritten. One should never edit them directly. @@ -406,7 +391,7 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) Furthermore it is recommended that you have the following line inside - you configure.ac script. + your configure.ac script. This allows gtkdocize to automatically copy the macro definition for GTK_DOC_CHECK to your project. @@ -429,12 +414,12 @@ AC_CONFIG_MACRO_DIR(m4) Integration with automake - First copy the Makefile.am from the + 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. + 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. @@ -624,7 +609,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html The scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + hint GTK-Doc to skip over them. GTK-Doc comment block Limitations Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not + #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations. @@ -771,7 +756,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + XML tags inside doc-comments by putting (or ) in the variable MKDB_OPTIONS inside Makefile.am. @@ -872,7 +857,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + name given here should match the <FILE> tag in the <package>-sections.txt file. @@ -1086,7 +1071,7 @@ foo_get_bar(Foo *foo) Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list - of the supported tags can be found on + of the supported tags can be found on the wiki. @@ -1299,6 +1284,111 @@ typedef enum { + + + Inline program documentation + + You can document programs and their commandline interface using inline + documentation. + + + + Tags + + PROGRAM + + + + Defines the start of a program documentation. + + + + + + @short_description: + + + Defines a short description of the program. (Optional) + + + + + + @synopsis: + + + Defines the arguments, or list of arguments that the program can take. + (Optional) + + + + + + @see_also: + + + See Also manual page section. (Optional) + + + + + + @arg: + + + Argument(s) passed to the program and their description. (Optional) + + + + + + Description: + + + A longer description of the program. + + + + + + Returns: + + + Specificy what value(s) the program returns. (Optional) + + + + + + + + Example of program documentation. + Program documentation block + + + + + + Useful DocBook tags @@ -1548,17 +1638,17 @@ gtk_arrow_get_type In addition a few option elements are created in commented form. You can review these and enable them as you like. - + Optional part in the master document - --> + --> ]]> - + Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will @@ -1593,7 +1683,7 @@ gtk_arrow_get_type Blank lines are ignored and lines starting with a '#' are treated as comment lines. - + While the tags make the file look like xml, it is not. Please do not @@ -1722,15 +1812,15 @@ meep_app_get_type GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizing the documentation - + 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. - + GTK-Doc 1.9 @@ -1738,7 +1828,7 @@ meep_app_get_type When using xml instead of sgml, one can actually name the master document <package>-docs.xml. - + This version supports in Makefile.am. When this is enabled, the @@ -1746,21 +1836,21 @@ meep_app_get_type can be removed from the vcs. This only works nicely for projects that have a very regular structure (e.g. each .{c,h} pair will create new section). If one organize a project close to that updating a manually - maintained section file can be as simple as running + maintained section file can be as simple as running meld <package>-decl-list.txt <package>-sections.txt. - + 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 you source control system and haven't yet switched, just + checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. - + GTK-Doc 1.10 @@ -1813,7 +1903,7 @@ endif 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 any example that shows how the entity file is included + number. Below is an example that shows how the entity file is included and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. diff --git a/help/manual/es/es.po b/help/manual/es/es.po index a10ab93..1b90d93 100644 --- a/help/manual/es/es.po +++ b/help/manual/es/es.po @@ -3,15 +3,15 @@ # Jorge Gonzalez , 2009. # Jorge González , 2009, 2010, 2011. # -# Daniel Mustieles , 2011, 2012, 2013, 2014, 2015. , 2015. +# Daniel Mustieles , 2011, 2012, 2013, 2014, 2015. , 2016, 2017. # msgid "" msgstr "" "Project-Id-Version: gtk-doc-help.master\n" -"POT-Creation-Date: 2015-11-19 07:07+0000\n" -"PO-Revision-Date: 2015-11-23 10:31+0100\n" +"POT-Creation-Date: 2017-04-23 16:21+0000\n" +"PO-Revision-Date: 2017-07-25 10:11+0200\n" "Last-Translator: Daniel Mustieles \n" -"Language-Team: Español; Castellano \n" +"Language-Team: es \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" @@ -23,7 +23,7 @@ msgstr "" msgctxt "_" msgid "translator-credits" msgstr "" -"Daniel Mustieles , 2009 - 2015\n" +"Daniel Mustieles , 2009 - 2017\n" "Jorge González , 2009 - 2011\n" "Francisco Javier F. Serrador , 2009, 2010" @@ -126,16 +126,26 @@ msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:83 msgid "" -"1.24.1 30 May 2015 ss1.25.1 21 March 2016 ss development version" msgstr "" -"1.24.1 30 de mayo de 2015 " +"1.25.1 21 de mayo de 2016 " "ss versión de desarrollo" #. (itstool) path: revhistory/revision #: C/index.docbook:89 msgid "" +"1.25 21 March 2016 ss bug fixes, test cleanups" +msgstr "" +"1.25 21 de marzo de 2016 " +"ss correcciones de errores, " +"limpieza" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:95 +msgid "" "1.24 29 May 2015 ss bug fix" msgstr "" @@ -144,7 +154,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:95 +#: C/index.docbook:101 msgid "" "1.23 17 May 2015 ss bug fix" @@ -154,7 +164,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:101 +#: C/index.docbook:107 msgid "" "1.22 07 May 2015 ss bug fixes, dropping deprecated features" #. (itstool) path: revhistory/revision -#: C/index.docbook:107 +#: C/index.docbook:113 msgid "" "1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" #. (itstool) path: revhistory/revision -#: C/index.docbook:113 +#: C/index.docbook:119 msgid "" "1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" #. (itstool) path: revhistory/revision -#: C/index.docbook:119 +#: C/index.docbook:125 msgid "" "1.19 05 Jun 2013 ss bug fixes" @@ -197,7 +207,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:125 +#: C/index.docbook:131 msgid "" "1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" @@ -207,7 +217,7 @@ msgstr "" "mejoras en la velocidad y soporte de marcado" #. (itstool) path: revhistory/revision -#: C/index.docbook:131 +#: C/index.docbook:137 msgid "" "1.17 26 Feb 2011 sk urgent bug fix update" @@ -217,7 +227,7 @@ msgstr "" "corrección de error" #. (itstool) path: revhistory/revision -#: C/index.docbook:137 +#: C/index.docbook:143 msgid "" "1.16 14 Jan 2011 sk bugfixes, layout improvements" @@ -227,7 +237,7 @@ msgstr "" "mejoras en la distribución" #. (itstool) path: revhistory/revision -#: C/index.docbook:143 +#: C/index.docbook:149 msgid "" "1.15 21 May 2010 sk bug and regression fixes" @@ -237,7 +247,7 @@ msgstr "" "regresiones" #. (itstool) path: revhistory/revision -#: C/index.docbook:149 +#: C/index.docbook:155 msgid "" "1.14 28 March 2010 sk bugfixes and performance improvements" @@ -247,7 +257,7 @@ msgstr "" "mejoras en el rendimiento" #. (itstool) path: revhistory/revision -#: C/index.docbook:155 +#: C/index.docbook:161 msgid "" "1.13 18 December 2009 " "sk broken tarball update" #. (itstool) path: revhistory/revision -#: C/index.docbook:161 +#: C/index.docbook:167 msgid "" "1.12 18 December 2009 " "sk new tool features and " @@ -269,7 +279,7 @@ msgstr "" "nuevas características" #. (itstool) path: revhistory/revision -#: C/index.docbook:167 +#: C/index.docbook:173 msgid "" "1.11 16 November 2008 " "mal GNOME doc-utils migration" #. (itstool) path: chapter/title -#: C/index.docbook:180 +#: C/index.docbook:186 msgid "Introduction" msgstr "Introducción" #. (itstool) path: chapter/para -#: C/index.docbook:182 +#: C/index.docbook:188 msgid "" "This chapter introduces GTK-Doc and gives an overview of what it is and how " "it is used." @@ -294,12 +304,12 @@ msgstr "" "es y cómo usarlo." #. (itstool) path: sect1/title -#: C/index.docbook:188 +#: C/index.docbook:194 msgid "What is GTK-Doc?" msgstr "¿Qué es GTK-Doc?" #. (itstool) path: sect1/para -#: C/index.docbook:190 +#: C/index.docbook:196 msgid "" "GTK-Doc is used to document C code. It is typically used to document the " "public API of libraries, such as the GTK+ and GNOME libraries. But it can " @@ -310,12 +320,12 @@ msgstr "" "Pero también se puede usar para documentar código de aplicaciones." #. (itstool) path: sect1/title -#: C/index.docbook:198 +#: C/index.docbook:204 msgid "How Does GTK-Doc Work?" msgstr "¿Cómo funciona GTK-Doc?" #. (itstool) path: sect1/para -#: C/index.docbook:200 +#: C/index.docbook:206 msgid "" "GTK-Doc works by using documentation of functions placed inside the source " "files in specially-formatted comment blocks, or documentation added to the " @@ -330,7 +340,7 @@ msgstr "" "archivos de cabecera; no produce salida para funciones estáticas)." #. (itstool) path: sect1/para -#: C/index.docbook:207 +#: C/index.docbook:213 msgid "" "GTK-Doc consists of a number of perl scripts, each performing a different " "step in the process." @@ -339,12 +349,12 @@ msgstr "" "diferente en el proceso." #. (itstool) path: sect1/para -#: C/index.docbook:212 +#: C/index.docbook:218 msgid "There are 5 main steps in the process:" msgstr "Existen 5 pasos importantes en el proceso:" #. (itstool) path: listitem/para -#: C/index.docbook:219 +#: C/index.docbook:225 msgid "" "Writing the documentation. The author fills in the " "source files with the documentation for each function, macro, union etc. (In " @@ -357,7 +367,7 @@ msgstr "" "lo que ya no se recomienda)." #. (itstool) path: listitem/para -#: C/index.docbook:229 +#: C/index.docbook:235 msgid "" "Gathering information about the code. " "gtkdoc-scan scans the header files of the code " @@ -393,7 +403,7 @@ msgstr "" "txt dentro de <module>-overrides.txt." #. (itstool) path: listitem/para -#: C/index.docbook:246 +#: C/index.docbook:252 msgid "" "gtkdoc-scangobj can also be used to dynamically " "query a library about any GObject subclasses it exports. It saves " @@ -407,7 +417,7 @@ msgstr "" "que proporciona." #. (itstool) path: listitem/para -#: C/index.docbook:252 +#: C/index.docbook:258 msgid "" "gtkdoc-scanobj should not be used anymore. It was " "needed in the past when GObject was still GtkObject inside gtk+." @@ -416,38 +426,7 @@ msgstr "" "necesitó en el pasado, cuando GObject todavía era GtkObject dentro de GTK+." #. (itstool) path: listitem/para -#: C/index.docbook:259 -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 "" -"Generar los archivos «plantilla». gtkdoc-" -"mktmpl crea un número de archivos en la subcarpeta tmpl/, usando la información obtenida en el " -"primer paso. (Tenga en cuenta que esto se puede ejecutar de forma separada. " -"Intentará asegurarse de que la documentación nunca se pierde.)" - -#. (itstool) path: note/para -#: C/index.docbook:268 -msgid "" -"Since GTK-Doc 1.9 the templates can be avoided. We encourage people to keep " -"documentation in the code. 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 "" -"Desde de GTK-Doc 1.9 se pueden evitar las plantillas. Animamos a la gente a " -"que mantenga la documentación en el código. gtkdocize ahora soporta una opción --flavour no-tmpl " -"que elige un archivo makefile que omite completamente el uso de tmpl. Si " -"nunca ha cambiado a mano el archivo tmpl, elimine la carpeta una vez (por " -"ejemplo, desde el sistema de control de versiones)." - -#. (itstool) path: listitem/para -#: C/index.docbook:280 +#: C/index.docbook:265 msgid "" "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 " @@ -478,7 +457,7 @@ msgstr "" "paquete>.pdf." #. (itstool) path: listitem/para -#: C/index.docbook:295 +#: C/index.docbook:280 msgid "" "Files in xml/ and html/ directories are always overwritten. One " @@ -489,7 +468,7 @@ msgstr "" "Nunca se deben editar directamente." #. (itstool) path: listitem/para -#: C/index.docbook:303 +#: C/index.docbook:288 msgid "" "Fixing up cross-references between documents. After " "installing the HTML files, gtkdoc-fixxref can be " @@ -512,22 +491,22 @@ msgstr "" "esa documentación está instalada)." #. (itstool) path: sect1/title -#: C/index.docbook:321 +#: C/index.docbook:306 msgid "Getting GTK-Doc" msgstr "Obtener GTK-Doc" #. (itstool) path: sect2/title -#: C/index.docbook:324 +#: C/index.docbook:309 msgid "Requirements" msgstr "Requerimientos" #. (itstool) path: sect2/para -#: C/index.docbook:325 +#: C/index.docbook:310 msgid "Perl v5 - the main scripts are in Perl." msgstr "Perl v5: los scripts principales están en Perl." #. (itstool) path: sect2/para -#: C/index.docbook:328 +#: C/index.docbook:313 msgid "" "xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" @@ -536,7 +515,7 @@ msgstr "" "\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/" #. (itstool) path: sect2/para -#: C/index.docbook:332 +#: C/index.docbook:317 msgid "" "docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" #. (itstool) path: sect2/para -#: C/index.docbook:336 +#: C/index.docbook:321 msgid "Python - optional - for gtkdoc-depscan" msgstr "Python: opcional, para gtkdoc-depscan" #. (itstool) path: sect2/para -#: C/index.docbook:339 +#: C/index.docbook:324 msgid "" "One of source-highlight, highlight " "or vim - optional - used for syntax highlighting of " @@ -563,17 +542,17 @@ msgstr "" "los ejemplos." #. (itstool) path: sect1/title -#: C/index.docbook:347 +#: C/index.docbook:332 msgid "About GTK-Doc" msgstr "Acerca de GTK-Doc" #. (itstool) path: sect1/para -#: C/index.docbook:349 C/index.docbook:363 +#: C/index.docbook:334 C/index.docbook:348 msgid "(FIXME)" msgstr "(ARRÉGLAME)" #. (itstool) path: sect1/para -#: C/index.docbook:353 +#: C/index.docbook:338 msgid "" "(History, authors, web pages, mailing list, license, future plans, " "comparison with other similar systems.)" @@ -582,22 +561,22 @@ msgstr "" "futuros, comparación con otros sistemas similares.)" #. (itstool) path: sect1/title -#: C/index.docbook:361 +#: C/index.docbook:346 msgid "About this Manual" msgstr "Acerca de este manual" #. (itstool) path: sect1/para -#: C/index.docbook:367 +#: C/index.docbook:352 msgid "(who it is meant for, where you can get it, license)" msgstr "(a quién está dirigido, dónde puede obtenerse, licencia)" #. (itstool) path: chapter/title -#: C/index.docbook:376 +#: C/index.docbook:361 msgid "Setting up your project" msgstr "Configurando su proyecto" #. (itstool) path: chapter/para -#: C/index.docbook:378 +#: C/index.docbook:363 msgid "" "The next sections describe what steps to perform to integrate GTK-Doc into " "your project. Theses sections assume we work on a project called 'meep'. " @@ -617,12 +596,12 @@ msgstr "" "construcción diferente." #. (itstool) path: sect1/title -#: C/index.docbook:389 +#: C/index.docbook:374 msgid "Setting up a skeleton documentation" msgstr "Configurar el esquema de la documentación" #. (itstool) path: sect1/para -#: C/index.docbook:391 +#: C/index.docbook:376 msgid "" "Under your top-level project directory create folders called docs/reference " "(this way you can also have docs/help for end-user documentation). It is " @@ -635,12 +614,12 @@ msgstr "" "Para paquetes con una sola biblioteca este paso no es necesario." #. (itstool) path: example/title -#: C/index.docbook:400 +#: C/index.docbook:385 msgid "Example directory structure" msgstr "Ejemplo de estructura de carpetas" #. (itstool) path: example/programlisting -#: C/index.docbook:401 +#: C/index.docbook:386 #, no-wrap msgid "" "\n" @@ -664,18 +643,18 @@ msgstr "" " meeper/\n" #. (itstool) path: sect1/para -#: C/index.docbook:398 +#: C/index.docbook:383 msgid "This can then look as shown below: <_:example-1/>" msgstr "Esto después aparecerá como se muestra debajo: <_:example-1/>" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:416 C/index.docbook:423 +#: C/index.docbook:401 C/index.docbook:408 msgid "Integration with autoconf" msgstr "Integración con autoconf" #. (itstool) path: sect1/para -#: C/index.docbook:418 +#: C/index.docbook:403 msgid "" "Very easy! Just add one line to your configure.ac " "script." @@ -684,7 +663,7 @@ msgstr "" "filename>." #. (itstool) path: example/programlisting -#: C/index.docbook:424 +#: C/index.docbook:409 #, no-wrap msgid "" "\n" @@ -696,12 +675,12 @@ msgstr "" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" #. (itstool) path: example/title -#: C/index.docbook:436 +#: C/index.docbook:421 msgid "Keep gtk-doc optional" msgstr "Mantener gtk-doc como opcional" #. (itstool) path: example/programlisting -#: C/index.docbook:437 +#: C/index.docbook:422 #, no-wrap msgid "" "\n" @@ -721,7 +700,7 @@ msgstr "" "])\n" #. (itstool) path: sect1/para -#: C/index.docbook:431 +#: C/index.docbook:416 msgid "" "This will require all developers to have gtk-doc installed. If it is okay " "for your project to have optional api-doc build setup, you can solve this as " @@ -735,7 +714,7 @@ msgstr "" "<_:example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:448 +#: C/index.docbook:433 msgid "" "The first argument is used to check for the gtkdocversion at configure time. " "The 2nd, optional argument is used by gtkdocize. " @@ -748,19 +727,19 @@ msgstr "" "symbol> también añade diversas opciones de configuración:" #. (itstool) path: listitem/para -#: C/index.docbook:454 +#: C/index.docbook:439 msgid "--with-html-dir=PATH : path to installed docs" msgstr "--with-html-dir=RUTA: ruta a los documentos instalados" #. (itstool) path: listitem/para -#: C/index.docbook:455 +#: C/index.docbook:440 msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "" "--enable-gtk-doc: usar gtk-doc para construir la documentación " "[predeterminado=no]" #. (itstool) path: listitem/para -#: C/index.docbook:456 +#: C/index.docbook:441 msgid "" "--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" @@ -768,14 +747,14 @@ msgstr "" "[predeterminado=sí]" #. (itstool) path: listitem/para -#: C/index.docbook:457 +#: C/index.docbook:442 msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" msgstr "" "--enable-gtk-doc: usar gtk-doc para construir la documentación " "[predeterminado=no]" #. (itstool) path: important/para -#: C/index.docbook:461 +#: C/index.docbook:446 msgid "" "GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " @@ -789,25 +768,30 @@ msgstr "" "desarrolladores)." #. (itstool) path: sect1/para -#: C/index.docbook:469 +#: C/index.docbook:454 +#| msgid "" +#| "Furthermore it is recommended that you have the following line inside you " +#| "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." msgstr "" "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 del macro para " +"configure.ac. Esto permite que gtkdocize copie automáticamente la definición de la macro para " "GTK_DOC_CHECK a su proyecto." #. (itstool) path: example/title -#: C/index.docbook:477 +#: C/index.docbook:462 msgid "Preparation for gtkdocize" msgstr "Preparación para gtkdocize" #. (itstool) path: example/programlisting -#: C/index.docbook:478 +#: C/index.docbook:463 #, no-wrap msgid "" "\n" @@ -817,7 +801,7 @@ msgstr "" "AC_CONFIG_MACRO_DIR(m4)\n" #. (itstool) path: sect1/para -#: C/index.docbook:483 +#: C/index.docbook:468 msgid "" "After all changes to configure.ac are made, update the " "configure file. This can be done by re-running " @@ -828,12 +812,12 @@ msgstr "" "volviendo a ejecutar autoreconf -i o autogen.sh." #. (itstool) path: sect1/title -#: C/index.docbook:491 +#: C/index.docbook:476 msgid "Integration with automake" msgstr "Integración con automake" #. (itstool) path: sect1/para -#: C/index.docbook:493 +#: C/index.docbook:478 msgid "" "First copy the Makefile.am from the examples sub directory of the Makefile.am. All the settings have a comment above that describes their " @@ -871,12 +855,12 @@ msgstr "" "soportan para listar los parámetros que soportan." #. (itstool) path: sect1/title -#: C/index.docbook:518 +#: C/index.docbook:503 msgid "Integration with autogen" msgstr "Integración con autogen" #. (itstool) path: sect1/para -#: C/index.docbook:520 +#: C/index.docbook:505 msgid "" "Most projects will have an autogen.sh script to setup " "the build infrastructure after a checkout from version control system (such " @@ -892,12 +876,12 @@ msgstr "" "automake o autoconf." #. (itstool) path: example/title -#: C/index.docbook:529 +#: C/index.docbook:514 msgid "Running gtkdocize from autogen.sh" msgstr "Ejecutar gtkdocize desde autogen.sh" #. (itstool) path: example/programlisting -#: C/index.docbook:530 +#: C/index.docbook:515 #, no-wrap msgid "" "\n" @@ -907,7 +891,7 @@ msgstr "" "gtkdocize || exit 1\n" #. (itstool) path: sect1/para -#: C/index.docbook:536 +#: C/index.docbook:521 msgid "" "When running gtkdocize it copies gtk-" "doc.make to your project root (or any directory specified by the " @@ -923,7 +907,7 @@ msgstr "" "gtkdocize." #. (itstool) path: sect1/para -#: C/index.docbook:545 +#: C/index.docbook:530 msgid "" "Historically GTK-Doc was generating template files where developers entered " "the docs. This turned out to be not so good (e.g. the need for having " @@ -957,12 +941,12 @@ msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:562 C/index.docbook:579 +#: C/index.docbook:547 C/index.docbook:564 msgid "Running the doc build" msgstr "Ejecutar la construcción de la documentación" #. (itstool) path: sect1/para -#: C/index.docbook:564 +#: C/index.docbook:549 msgid "" "After the previous steps it's time to run the build. First we need to rerun " "autogen.sh. If this script runs configure for you, then " @@ -976,7 +960,7 @@ msgstr "" "configure con esta opción." #. (itstool) path: sect1/para -#: C/index.docbook:571 +#: C/index.docbook:556 msgid "" "The first make run generates several additional files in the doc-" "directories. The important ones are: <package>.types<paquete>-sections.txt." #. (itstool) path: example/programlisting -#: C/index.docbook:580 +#: C/index.docbook:565 #, no-wrap msgid "" "\n" @@ -1001,7 +985,7 @@ msgstr "" "make\n" #. (itstool) path: sect1/para -#: C/index.docbook:586 +#: C/index.docbook:571 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 +997,12 @@ msgstr "" "información." #. (itstool) path: sect1/title -#: C/index.docbook:594 +#: C/index.docbook:579 msgid "Integration with version control systems" msgstr "Integración con los sistemas de control de versiones" #. (itstool) path: sect1/para -#: C/index.docbook:596 +#: C/index.docbook:581 msgid "" "As a rule of thumb, it's the files you edit which should go under version " "control. For typical projects it's these files: <package>." @@ -1033,7 +1017,7 @@ msgstr "" "txt, Makefile.am." #. (itstool) path: sect1/para -#: C/index.docbook:604 +#: C/index.docbook:589 msgid "" "Files in the xml/ and html/ " "directories should not go under version control. Neither should any of the " @@ -1044,12 +1028,12 @@ msgstr "" "los archivos .stamp." #. (itstool) path: sect1/title -#: C/index.docbook:612 +#: C/index.docbook:597 msgid "Integration with plain makefiles or other build systems" msgstr "Integración con makefiles u otros sistemas de construcción" #. (itstool) path: sect1/para -#: C/index.docbook:614 +#: C/index.docbook:599 msgid "" "In the case one does not want to use automake and therefore gtk-" "doc.mak one will need to call the gtkdoc tools in the right order " @@ -1060,12 +1044,12 @@ msgstr "" "makefiles propios (o en otras herramientas de construcción)." #. (itstool) path: example/title -#: C/index.docbook:621 +#: C/index.docbook:606 msgid "Documentation build steps" msgstr "Pasos de construcción de la documentación" #. (itstool) path: example/programlisting -#: C/index.docbook:622 +#: C/index.docbook:607 #, no-wrap msgid "" "\n" @@ -1091,7 +1075,7 @@ msgstr "" "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" #. (itstool) path: sect1/para -#: C/index.docbook:636 +#: C/index.docbook:621 msgid "" "One will need to look at the Makefile.am and " "gtk-doc.mak to pick the extra options needed." @@ -1100,13 +1084,12 @@ msgstr "" "doc.mak para elegir las opciones adicionales necesarias." #. (itstool) path: sect1/title -#: C/index.docbook:643 -#| msgid "Integration with plain makefiles or other build systems" +#: C/index.docbook:628 msgid "Integration with CMake build systems" msgstr "Integración con sistemas de construcción CMake" #. (itstool) path: sect1/para -#: C/index.docbook:645 +#: C/index.docbook:630 msgid "" "GTK-Doc now provides a GtkDocConfig.cmake module (and " "the corresponding GtkDocConfigVersion.cmake module). " @@ -1120,12 +1103,12 @@ msgstr "" "filename>." #. (itstool) path: example/title -#: C/index.docbook:655 +#: C/index.docbook:640 msgid "Example of using GTK-Doc from CMake" msgstr "Ejeplo de uso de GTK-Doc desde CMake" #. (itstool) path: example/programlisting -#: C/index.docbook:656 +#: C/index.docbook:641 #, no-wrap msgid "" "\n" @@ -1167,17 +1150,17 @@ msgstr "" " DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" #. (itstool) path: sect1/para -#: C/index.docbook:653 +#: C/index.docbook:638 msgid "The following example shows how to use this command. <_:example-1/>" msgstr "El siguiente ejemplo muestra cómo usar este comando. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:681 +#: C/index.docbook:666 msgid "Documenting the code" msgstr "Documentar el código" #. (itstool) path: chapter/para -#: C/index.docbook:683 +#: C/index.docbook:668 msgid "" "GTK-Doc uses source code comment with a special syntax for code " "documentation. Further it retrieves information about your project structure " @@ -1190,12 +1173,12 @@ msgstr "" "acerca de la sintaxis de los comentarios." #. (itstool) path: note/title -#: C/index.docbook:691 +#: C/index.docbook:676 msgid "Documentation placement" msgstr "Ubicación de la documentación" #. (itstool) path: note/para -#: C/index.docbook:692 +#: C/index.docbook:677 msgid "" "In the past most documentation had to be filled into files residing inside " "the tmpl directory. This has the disadvantages that the " @@ -1209,7 +1192,7 @@ msgstr "" "conflictos con los sistemas de control de versiones." #. (itstool) path: note/para -#: C/index.docbook:698 +#: C/index.docbook:683 msgid "" "The avoid the aforementioned problems we suggest putting the documentation " "inside the sources. This manual will only describe this way of documenting " @@ -1220,12 +1203,12 @@ msgstr "" "documentar el código." #. (itstool) path: example/title -#: C/index.docbook:709 C/index.docbook:735 +#: C/index.docbook:694 C/index.docbook:720 msgid "GTK-Doc comment block" msgstr "Bloque de comentario de GTK-Doc" #. (itstool) path: example/programlisting -#: C/index.docbook:710 +#: C/index.docbook:695 #, no-wrap msgid "" "\n" @@ -1239,7 +1222,7 @@ msgstr "" "#endif\n" #. (itstool) path: chapter/para -#: C/index.docbook:705 +#: C/index.docbook:690 msgid "" "The scanner can handle the majority of C headers fine. In the case of " "receiving warnings from the scanner that look like a special case, one can " @@ -1250,12 +1233,12 @@ msgstr "" "GTK-Doc que los omita. <_:example-1/>" #. (itstool) path: note/title -#: C/index.docbook:719 +#: C/index.docbook:704 msgid "Limitations" msgstr "Limitaciones" #. (itstool) path: note/para -#: C/index.docbook:720 +#: C/index.docbook:705 msgid "" "Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but " "not #if !defined(__GTK_DOC_IGNORE__) or other combinations." @@ -1264,12 +1247,12 @@ msgstr "" "pero #if !defined(__GTK_DOC_IGNORE__) u otras combinaciones." #. (itstool) path: sect1/title -#: C/index.docbook:730 +#: C/index.docbook:715 msgid "Documentation comments" msgstr "Comentarios de la documentación" #. (itstool) path: example/programlisting -#: C/index.docbook:736 +#: C/index.docbook:721 #, no-wrap msgid "" "\n" @@ -1285,7 +1268,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:732 +#: C/index.docbook:717 msgid "" "A multiline comment that starts with an additional '*' marks a documentation " "block that will be processed by the GTK-Doc tools. <_:example-1/>" @@ -1294,7 +1277,7 @@ msgstr "" "bloque de documentación que GTK-Doc tools procesarán. <_:example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:745 +#: C/index.docbook:730 msgid "" "The 'identifier' is one line with the name of the item the comment is " "related to. The syntax differs a little depending on the item. (TODO add " @@ -1305,7 +1288,7 @@ msgstr "" "hacer: añadir una tabla mostrando los identificadores)" #. (itstool) path: sect1/para -#: C/index.docbook:751 +#: C/index.docbook:736 msgid "" "The 'documentation' block is also different for each symbol type. Symbol " "types that get parameters such as functions or macros have the parameter " @@ -1325,7 +1308,7 @@ msgstr "" "espacio). Esto es útil para texto preformateado (listados de código)." #. (itstool) path: listitem/para -#: C/index.docbook:768 +#: C/index.docbook:753 msgid "" "What it is: The name for a class or function can sometimes be misleading for " "people coming from a different background." @@ -1334,24 +1317,24 @@ msgstr "" "personas que provengan de otros entornos." #. (itstool) path: listitem/para -#: C/index.docbook:774 +#: C/index.docbook:759 msgid "" "What it does: Tell about common uses. Put it in relation with the other API." msgstr "Qué hace: indique los usos comunes, en relación con las otras API." #. (itstool) path: tip/para -#: C/index.docbook:764 +#: C/index.docbook:749 msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" msgstr "Al documentar código, describa dos aspectos: <_:itemizedlist-1/>" #. (itstool) path: listitem/para -#: C/index.docbook:789 +#: C/index.docbook:774 msgid "Use function() to refer to functions or macros which take arguments." msgstr "" "Use función() para referirse a funciones o macros que toman argumentos." #. (itstool) path: listitem/para -#: C/index.docbook:794 +#: C/index.docbook:779 msgid "" "Use @param to refer to parameters. Also use this when referring to " "parameters of other functions, related to the one being described." @@ -1360,12 +1343,12 @@ msgstr "" "parámetros de otras funciones, relacionados al que se describe." #. (itstool) path: listitem/para -#: C/index.docbook:800 +#: C/index.docbook:785 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "Use %constant para referirse a una constante, ej: %G_TRAVERSE_LEAFS." #. (itstool) path: listitem/para -#: C/index.docbook:805 +#: C/index.docbook:790 msgid "" "Use #symbol to refer to other types of symbol, e.g. structs and enums and " "macros which don't take arguments." @@ -1374,17 +1357,17 @@ msgstr "" "estructuras, enumeraciones y macros que no toman argumentos." #. (itstool) path: listitem/para -#: C/index.docbook:811 +#: C/index.docbook:796 msgid "Use #Object::signal to refer to a GObject signal." msgstr "Use #Object::signal para referirse a una señal de GObject." #. (itstool) path: listitem/para -#: C/index.docbook:816 +#: C/index.docbook:801 msgid "Use #Object:property to refer to a GObject property." msgstr "Use #Object:property para referirse a una propiedad de GObject." #. (itstool) path: listitem/para -#: C/index.docbook:821 +#: C/index.docbook:806 msgid "" "Use #Struct.field to refer to a field inside a structure and #GObjectClass." "foo_bar() to refer to a vmethod." @@ -1393,7 +1376,7 @@ msgstr "" "#GObjectClass.foo_bar() para referirse a un vmethod." #. (itstool) path: sect1/para -#: C/index.docbook:783 +#: C/index.docbook:768 msgid "" "One advantage of hyper-text over plain-text is the ability to have links in " "the document. Writing the correct markup for a link can be tedious though. " @@ -1406,7 +1389,7 @@ msgstr "" "itemizedlist-1/>" #. (itstool) path: tip/para -#: C/index.docbook:830 +#: C/index.docbook:815 msgid "" "If you need to use the special characters '<', '>', '()', '@', '%', or " "'#' in your documentation without GTK-Doc changing them you can use the XML " @@ -1421,7 +1404,7 @@ msgstr "" "doble «\\»." #. (itstool) path: sect1/para -#: C/index.docbook:839 +#: C/index.docbook:824 msgid "" "DocBook can do more than just links. One can also have lists, examples, " "headings, and images. As of version 1.20, the preferred way is to use a " @@ -1439,7 +1422,7 @@ msgstr "" "elementos de una lista aparecerán como líneas que empiezan con un guión." #. (itstool) path: sect1/para -#: C/index.docbook:850 +#: C/index.docbook:835 msgid "" "While markdown is now preferred one can mix both. One limitation here is " "that one can use docbook xml within markdown, but markdown within docbook " @@ -1450,7 +1433,7 @@ msgstr "" "xml no está soportado." #. (itstool) path: sect1/para -#: C/index.docbook:856 +#: C/index.docbook:841 msgid "" "In older GTK-Doc releases, if you need support for additional formatting, " "you would need to enable the usage of docbook XML tags inside doc-comments " @@ -1465,12 +1448,12 @@ msgstr "" "Makefile.am." #. (itstool) path: example/title -#: C/index.docbook:865 +#: C/index.docbook:850 msgid "GTK-Doc comment block using Markdown" msgstr "Bloque de comentario de GTK-Doc usando marcado" #. (itstool) path: example/programlisting -#: C/index.docbook:866 +#: C/index.docbook:851 #, no-wrap msgid "" "\n" @@ -1546,7 +1529,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:905 +#: C/index.docbook:890 msgid "" "More examples of what markdown tags are supported can be found in the ." #. (itstool) path: tip/para -#: C/index.docbook:911 +#: C/index.docbook:896 msgid "" "As already mentioned earlier GTK-Doc is for documenting public API. Thus one " "cannot write documentation for static symbols. Nevertheless it is good to " @@ -1579,12 +1562,12 @@ msgstr "" "secciones." #. (itstool) path: sect1/title -#: C/index.docbook:925 +#: C/index.docbook:910 msgid "Documenting sections" msgstr "Documentar secciones" #. (itstool) path: sect1/para -#: C/index.docbook:927 +#: C/index.docbook:912 msgid "" "Each section of the documentation contains information about one class or " "module. To introduce the component one can write a section block. The short " @@ -1597,12 +1580,12 @@ msgstr "" "los campos @ son opcionales." #. (itstool) path: example/title -#: C/index.docbook:935 +#: C/index.docbook:920 msgid "Section comment block" msgstr "Bloque de comentarios en una sección" #. (itstool) path: example/programlisting -#: C/index.docbook:936 +#: C/index.docbook:921 #, no-wrap msgid "" "\n" @@ -1634,15 +1617,20 @@ msgstr "" " */\n" #. (itstool) path: varlistentry/term -#: C/index.docbook:955 +#: C/index.docbook:940 msgid "SECTION:<name>" msgstr "SECCIÓN <nombre>" #. (itstool) path: listitem/para -#: C/index.docbook:957 +#: C/index.docbook:942 +#| msgid "" +#| "The name links the section documentation to the respective part in the " +#| "<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 "" @@ -1652,12 +1640,12 @@ msgstr "" "archivo <paquete>-sections.txt." #. (itstool) path: varlistentry/term -#: C/index.docbook:966 +#: C/index.docbook:951 msgid "@short_description" msgstr "@short_description" #. (itstool) path: listitem/para -#: C/index.docbook:968 +#: C/index.docbook:953 msgid "" "A one line description of the section, that later will appear after the " "links in the TOC and at the top of the section page." @@ -1666,12 +1654,12 @@ msgstr "" "TOC y en la página de la sección." #. (itstool) path: varlistentry/term -#: C/index.docbook:975 +#: C/index.docbook:960 msgid "@title" msgstr "@title" #. (itstool) path: listitem/para -#: C/index.docbook:977 +#: C/index.docbook:962 msgid "" "The section title defaults to <name> from the SECTION declaration. It " "can be overridden with the @title field." @@ -1680,12 +1668,12 @@ msgstr "" "declaración SECTION. Se puede sobrescribir con el campo @title." #. (itstool) path: varlistentry/term -#: C/index.docbook:984 +#: C/index.docbook:969 msgid "@section_id" msgstr "@section_id" #. (itstool) path: listitem/para -#: C/index.docbook:986 +#: C/index.docbook:971 msgid "" "Overrides the use of title as a section identifier. For GObjects the <" "title> is used as a section_id and for other sections it is <" @@ -1696,22 +1684,22 @@ msgstr "" "para otra sección es <MÓDULO>-<title>." #. (itstool) path: varlistentry/term -#: C/index.docbook:994 +#: C/index.docbook:979 msgid "@see_also" msgstr "@see_also" #. (itstool) path: listitem/para -#: C/index.docbook:996 +#: C/index.docbook:981 msgid "A list of symbols that are related to this section." msgstr "Una lista de símbolos relacionados con esta sección." #. (itstool) path: varlistentry/term -#: C/index.docbook:1002 +#: C/index.docbook:987 msgid "@stability" msgstr "@stability" #. (itstool) path: listitem/para -#: C/index.docbook:1009 +#: C/index.docbook:994 msgid "" "Stable - The intention of a Stable interface is to enable arbitrary third " "parties to develop applications to these interfaces, release them, and have " @@ -1729,7 +1717,7 @@ msgstr "" "de haberlos habrá buenas razones para ello." #. (itstool) path: listitem/para -#: C/index.docbook:1021 +#: C/index.docbook:1006 msgid "" "Unstable - Unstable interfaces are experimental or transitional. They are " "typically used to give outside developers early access to new or rapidly " @@ -1745,7 +1733,7 @@ msgstr "" "publicación menor a la siguiente." #. (itstool) path: listitem/para -#: C/index.docbook:1033 +#: C/index.docbook:1018 msgid "" "Private - An interface that can be used within the GNOME stack itself, but " "that is not documented for end-users. Such functions should only be used in " @@ -1756,7 +1744,7 @@ msgstr "" "deberían usar de formas especificadas y documentadas." #. (itstool) path: listitem/para -#: C/index.docbook:1042 +#: C/index.docbook:1027 msgid "" "Internal - An interface that is internal to a module and does not require " "end-user documentation. Functions that are undocumented are assumed to be " @@ -1767,7 +1755,7 @@ msgstr "" "son internas." #. (itstool) path: listitem/para -#: C/index.docbook:1004 +#: C/index.docbook:989 msgid "" "An informal description of the stability level this API has. We recommend " "the use of one of these terms: <_:itemizedlist-1/>" @@ -1776,12 +1764,12 @@ msgstr "" "recomienda el uso de uno de estos términos: <_:itemizedlist-1/>" #. (itstool) path: varlistentry/term -#: C/index.docbook:1054 +#: C/index.docbook:1039 msgid "@include" msgstr "@include" #. (itstool) path: listitem/para -#: C/index.docbook:1056 +#: C/index.docbook:1041 msgid "" "The #include files to show in the section synopsis (a " "comma separated list), overriding the global value from the --default-stability argument to " @@ -1910,17 +1898,17 @@ msgstr "" "siguientes valores." #. (itstool) path: variablelist/title -#: C/index.docbook:1134 +#: C/index.docbook:1119 msgid "Stability Tags" msgstr "Etiquetas de estabilidad" #. (itstool) path: varlistentry/term -#: C/index.docbook:1135 +#: C/index.docbook:1120 msgid "Stability: Stable" msgstr "Estabilidad: estable" #. (itstool) path: listitem/para -#: C/index.docbook:1137 +#: C/index.docbook:1122 msgid "" "Mark the element as stable. This is for public APIs which are guaranteed to " "remain stable for all future minor releases of the project." @@ -1930,12 +1918,12 @@ msgstr "" "proyecto." #. (itstool) path: varlistentry/term -#: C/index.docbook:1144 +#: C/index.docbook:1129 msgid "Stability: Unstable" msgstr "Estabilidad: inestable" #. (itstool) path: listitem/para -#: C/index.docbook:1146 +#: C/index.docbook:1131 msgid "" "Mark the element as unstable. This is for public APIs which are released as " "a preview before being stabilised." @@ -1944,12 +1932,12 @@ msgstr "" "publican como versión previa antes de estabilizarse." #. (itstool) path: varlistentry/term -#: C/index.docbook:1152 +#: C/index.docbook:1137 msgid "Stability: Private" msgstr "Estabilidad: privado" #. (itstool) path: listitem/para -#: C/index.docbook:1154 +#: C/index.docbook:1139 msgid "" "Mark the element as private. This is for interfaces which can be used by " "tightly coupled modules, but not by arbitrary third parties." @@ -1958,7 +1946,7 @@ msgstr "" "en módulos fuertemente acoplados, pero no en terceras partes aleatorias." #. (itstool) path: example/programlisting -#: C/index.docbook:1164 +#: C/index.docbook:1149 #, no-wrap msgid "" "\n" @@ -1997,12 +1985,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1184 C/index.docbook:1194 +#: C/index.docbook:1169 C/index.docbook:1179 msgid "Annotations" msgstr "Anotaciones" #. (itstool) path: sect2/para -#: C/index.docbook:1186 +#: C/index.docbook:1171 msgid "" "Documentation blocks can contain annotation-tags. These tags will be " "rendered with tooltips describing their meaning. The tags are used by " @@ -2018,7 +2006,7 @@ msgstr "" "type=\"http\">el wiki." #. (itstool) path: example/programlisting -#: C/index.docbook:1195 +#: C/index.docbook:1180 #, no-wrap msgid "" "\n" @@ -2059,12 +2047,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1216 C/index.docbook:1245 +#: C/index.docbook:1201 C/index.docbook:1230 msgid "Function comment block" msgstr "Bloque de comentario de función" #. (itstool) path: listitem/para -#: C/index.docbook:1222 +#: C/index.docbook:1207 msgid "" "Document whether returned objects, lists, strings, etc, should be freed/" "unrefed/released." @@ -2073,26 +2061,26 @@ msgstr "" "debería liberarse/desreferenciarse/etc." #. (itstool) path: listitem/para -#: C/index.docbook:1228 +#: C/index.docbook:1213 msgid "Document whether parameters can be NULL, and what happens if they are." msgstr "" "El documento, dependiendo de si sus parámetros pueden ser nulos, y qué " "sucede si lo son." #. (itstool) path: listitem/para -#: C/index.docbook:1233 +#: C/index.docbook:1218 msgid "" "Mention interesting pre-conditions and post-conditions where appropriate." msgstr "" "Mencionar precondiciones y postcondiciones interesantes donde sea apropiado." #. (itstool) path: sect2/para -#: C/index.docbook:1218 C/index.docbook:1304 +#: C/index.docbook:1203 C/index.docbook:1289 msgid "Please remember to: <_:itemizedlist-1/>" msgstr "Recuerde: <_:itemizedlist-1/>" #. (itstool) path: sect2/para -#: C/index.docbook:1240 +#: C/index.docbook:1225 msgid "" "Gtk-doc assumes all symbols (macros, functions) starting with '_' are " "private. They are treated like static functions." @@ -2101,7 +2089,7 @@ msgstr "" "«_» son privados. Se tratan como funciones estáticas." #. (itstool) path: example/programlisting -#: C/index.docbook:1246 +#: C/index.docbook:1231 #, no-wrap msgid "" "\n" @@ -2143,27 +2131,27 @@ msgstr "" " */\n" #. (itstool) path: variablelist/title -#: C/index.docbook:1267 +#: C/index.docbook:1252 msgid "Function tags" msgstr "Etiquetas de funciones" #. (itstool) path: varlistentry/term -#: C/index.docbook:1268 +#: C/index.docbook:1253 C/index.docbook:1460 msgid "Returns:" msgstr "Devuelve:" #. (itstool) path: listitem/para -#: C/index.docbook:1270 +#: C/index.docbook:1255 msgid "Paragraph describing the returned result." msgstr "Párrafo que describe el resultado devuelto." #. (itstool) path: varlistentry/term -#: C/index.docbook:1275 +#: C/index.docbook:1260 msgid "@...:" msgstr "@...:" #. (itstool) path: listitem/para -#: C/index.docbook:1277 +#: C/index.docbook:1262 msgid "" "In case the function has variadic arguments, you should use this tag " "(@Varargs: does also work for historic reasons)." @@ -2173,12 +2161,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1287 C/index.docbook:1289 +#: C/index.docbook:1272 C/index.docbook:1274 msgid "Property comment block" msgstr "Bloque de comentario de propiedad" #. (itstool) path: example/programlisting -#: C/index.docbook:1290 +#: C/index.docbook:1275 #, no-wrap msgid "" "\n" @@ -2199,12 +2187,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1302 C/index.docbook:1321 +#: C/index.docbook:1287 C/index.docbook:1306 msgid "Signal comment block" msgstr "Bloque de comentario de señal" #. (itstool) path: listitem/para -#: C/index.docbook:1308 +#: C/index.docbook:1293 msgid "" "Document when the signal is emitted and whether it is emitted before or " "after other signals." @@ -2213,12 +2201,12 @@ msgstr "" "otras señales." #. (itstool) path: listitem/para -#: C/index.docbook:1314 +#: C/index.docbook:1299 msgid "Document what an application might do in the signal handler." msgstr "Documentar qué aplicación debe gestionar las señales." #. (itstool) path: example/programlisting -#: C/index.docbook:1322 +#: C/index.docbook:1307 #, no-wrap msgid "" "\n" @@ -2249,12 +2237,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1339 C/index.docbook:1340 +#: C/index.docbook:1324 C/index.docbook:1325 msgid "Struct comment block" msgstr "Bloque de comentario de estructura" #. (itstool) path: example/programlisting -#: C/index.docbook:1341 +#: C/index.docbook:1326 #, no-wrap msgid "" "\n" @@ -2284,7 +2272,7 @@ msgstr "" "} FooWidget;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1356 +#: C/index.docbook:1341 msgid "" "Use /*< private >*/ before the private struct fields you " "want to hide. Use /*< public >*/ for the reverse " @@ -2295,7 +2283,7 @@ msgstr "" "revertir el comportamiento anterior." #. (itstool) path: sect2/para -#: C/index.docbook:1362 +#: C/index.docbook:1347 msgid "" "If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" " "it will be considered private automatically and doesn't need to be mentioned " @@ -2306,7 +2294,7 @@ msgstr "" "bloque de comentario." #. (itstool) path: sect2/para -#: C/index.docbook:1368 +#: C/index.docbook:1353 msgid "" "Struct comment blocks can also be used for GObjects and GObjectClasses. It " "is usually a good idea to add a comment block for a class, if it has " @@ -2326,12 +2314,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1380 C/index.docbook:1381 +#: C/index.docbook:1365 C/index.docbook:1366 msgid "Enum comment block" msgstr "Enumerar bloques de comentarios" #. (itstool) path: example/programlisting -#: C/index.docbook:1382 +#: C/index.docbook:1367 #, no-wrap msgid "" "\n" @@ -2365,7 +2353,7 @@ msgstr "" "} Something;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1399 +#: C/index.docbook:1384 msgid "" "Use /*< private >*/ before the private enum values you " "want to hide. Use /*< public >*/ for the reverse " @@ -2376,19 +2364,161 @@ msgstr "" "comportamiento anterior." #. (itstool) path: sect1/title -#: C/index.docbook:1409 +#: C/index.docbook:1395 +msgid "Inline program documentation" +msgstr "Documentación en línea del programa" + +#. (itstool) path: sect1/para +#: C/index.docbook:1396 +msgid "" +"You can document programs and their commandline interface using inline " +"documentation." +msgstr "" +"Puede documentar programas y su interfaz de línea de comandos usando la " +"documentación en línea." + +#. (itstool) path: variablelist/title +#: C/index.docbook:1402 +msgid "Tags" +msgstr "Etiquetas" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1404 +msgid "PROGRAM" +msgstr "PROGRAM" + +#. (itstool) path: listitem/para +#: C/index.docbook:1407 +msgid "Defines the start of a program documentation." +msgstr "Define el inicio de la documentación de un programa." + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1414 +msgid "@short_description:" +msgstr "@short_description:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1416 +msgid "Defines a short description of the program. (Optional)" +msgstr "Define una descripción corta del programa. (Opcional)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1423 +msgid "@synopsis:" +msgstr "@synopsis:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1425 +msgid "" +"Defines the arguments, or list of arguments that the program can take. " +"(Optional)" +msgstr "" +"Define el argumento o la lista de argumentos que el programa puede usar. " +"(Opcional)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1433 +msgid "@see_also:" +msgstr "@see_also:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1435 +msgid "See Also manual page section. (Optional)" +msgstr "Página del manual Ver también. (Opcional)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1442 +msgid "@arg:" +msgstr "@arg:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1444 +msgid "Argument(s) passed to the program and their description. (Optional)" +msgstr "Argumentos pasados al programa y su descripción. (Opcional)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1451 +msgid "Description:" +msgstr "Description:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1453 +msgid "A longer description of the program." +msgstr "Una descripción más larga del programa." + +#. (itstool) path: listitem/para +#: C/index.docbook:1462 +msgid "Specificy what value(s) the program returns. (Optional)" +msgstr "Especifique qué valores devuelve el programa. (Opcional)" + +#. (itstool) path: sect2/title +#: C/index.docbook:1471 +msgid "Example of program documentation." +msgstr "Ejemplo de documentación de un programa." + +#. (itstool) path: example/title +#: C/index.docbook:1472 +msgid "Program documentation block" +msgstr "Bloque de documentación del programa" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1473 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * PROGRAM:test-program\n" +" * @short_description: A test program\n" +" * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*\n" +" * @see_also: test(1)\n" +" * @--arg1 *arg*: set arg1 to *arg*\n" +" * @--arg2 *arg*: set arg2 to *arg*\n" +" * @-v, --version: Print the version number\n" +" * @-h, --help: Print the help message\n" +" *\n" +" * Long description of program.\n" +" *\n" +" * Returns: Zero on success, non-zero on failure\n" +" */\n" +"int main(int argc, char *argv[])\n" +"{\n" +"\treturn 0;\n" +"}\n" +msgstr "" +"\n" +"/**\n" +" * PROGRAM:test-program\n" +" * @short_description: A test program\n" +" * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*\n" +" * @see_also: test(1)\n" +" * @--arg1 *arg*: set arg1 to *arg*\n" +" * @--arg2 *arg*: set arg2 to *arg*\n" +" * @-v, --version: Print the version number\n" +" * @-h, --help: Print the help message\n" +" *\n" +" * Long description of program.\n" +" *\n" +" * Returns: Zero on success, non-zero on failure\n" +" */\n" +"int main(int argc, char *argv[])\n" +"{\n" +"\treturn 0;\n" +"}\n" + +#. (itstool) path: sect1/title +#: C/index.docbook:1499 msgid "Useful DocBook tags" msgstr "Etiquetas DocBook útiles" #. (itstool) path: sect1/para -#: C/index.docbook:1411 +#: C/index.docbook:1501 msgid "" "Here are some DocBook tags which are most useful when documenting the code." msgstr "" "Aquí están varias etiquetas de DocBook muy útiles al documentar código." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1420 +#: C/index.docbook:1510 #, no-wrap msgid "" "\n" @@ -2398,7 +2528,7 @@ msgstr "" "<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1416 +#: C/index.docbook:1506 msgid "" "To link to another section in the GTK docs: <_:informalexample-1/> The " "linkend is the SGML/XML id on the top item of the page you want to link to. " @@ -2414,7 +2544,7 @@ msgstr "" "ajustarse a SGML/XML." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1433 +#: C/index.docbook:1523 #, no-wrap msgid "" "\n" @@ -2424,7 +2554,7 @@ msgstr "" "<function>...</function>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1430 +#: C/index.docbook:1520 msgid "" "To refer to an external function, e.g. a standard C function: <_:" "informalexample-1/>" @@ -2433,7 +2563,7 @@ msgstr "" "informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1442 +#: C/index.docbook:1532 #, no-wrap msgid "" "\n" @@ -2453,7 +2583,7 @@ msgstr "" "</example>\n" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1453 +#: C/index.docbook:1543 #, no-wrap msgid "" "\n" @@ -2471,7 +2601,7 @@ msgstr "" "</informalexample>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1439 +#: C/index.docbook:1529 msgid "" "To include example code: <_:informalexample-1/> or possibly this, for very " "short code fragments which don't need a title: <_:informalexample-2/> For " @@ -2482,7 +2612,7 @@ msgstr "" "informalexample-2/>. El último GTK-Doc también soporta abreviación: |[ ... ]|" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1472 +#: C/index.docbook:1562 #, no-wrap msgid "" "\n" @@ -2514,12 +2644,12 @@ msgstr "" "</itemizedlist>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1469 +#: C/index.docbook:1559 msgid "To include bulleted lists: <_:informalexample-1/>" msgstr "Para incluir listas de topos: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1492 +#: C/index.docbook:1582 #, no-wrap msgid "" "\n" @@ -2537,13 +2667,13 @@ msgstr "" "</note>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1489 +#: C/index.docbook:1579 msgid "" "To include a note which stands out from the text: <_:informalexample-1/>" msgstr "Para incluir una nota que sobresale del texto: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1505 +#: C/index.docbook:1595 #, no-wrap msgid "" "\n" @@ -2553,12 +2683,12 @@ msgstr "" "<type>unsigned char</type>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1502 +#: C/index.docbook:1592 msgid "To refer to a type: <_:informalexample-1/>" msgstr "Para referirse a un tipo: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1514 +#: C/index.docbook:1604 #, no-wrap msgid "" "\n" @@ -2568,7 +2698,7 @@ msgstr "" "<structname>XFontStruct</structname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1511 +#: C/index.docbook:1601 msgid "" "To refer to an external structure (not one described in the GTK docs): <_:" "informalexample-1/>" @@ -2577,7 +2707,7 @@ msgstr "" "de GTK): <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1523 +#: C/index.docbook:1613 #, no-wrap msgid "" "\n" @@ -2587,12 +2717,12 @@ msgstr "" "<structfield>len</structfield>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1520 +#: C/index.docbook:1610 msgid "To refer to a field of a structure: <_:informalexample-1/>" msgstr "Para referirse a un campo o a una estructura: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1532 +#: C/index.docbook:1622 #, no-wrap msgid "" "\n" @@ -2602,7 +2732,7 @@ msgstr "" "<classname>GtkWidget</classname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1529 +#: C/index.docbook:1619 msgid "" "To refer to a class name, we could possibly use: <_:informalexample-1/> but " "you'll probably be using #GtkWidget instead (to automatically create a link " @@ -2615,7 +2745,7 @@ msgstr "" "\"documenting_syntax\">abreviaciones)." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1543 +#: C/index.docbook:1633 #, no-wrap msgid "" "\n" @@ -2625,12 +2755,12 @@ msgstr "" "<emphasis>This is important</emphasis>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1540 +#: C/index.docbook:1630 msgid "To emphasize text: <_:informalexample-1/>" msgstr "Para enfatizar un texto: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1552 +#: C/index.docbook:1642 #, no-wrap msgid "" "\n" @@ -2640,12 +2770,12 @@ msgstr "" "<filename>/home/user/documents</filename>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1549 +#: C/index.docbook:1639 msgid "For filenames use: <_:informalexample-1/>" msgstr "Para uso de nombres de archivo: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1561 +#: C/index.docbook:1651 #, no-wrap msgid "" "\n" @@ -2655,17 +2785,17 @@ msgstr "" "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1558 +#: C/index.docbook:1648 msgid "To refer to keys use: <_:informalexample-1/>" msgstr "Para referirse a claves: <_:informalexample-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1571 +#: C/index.docbook:1661 msgid "Filling the extra files" msgstr "Rellenar campos adicionales" #. (itstool) path: chapter/para -#: C/index.docbook:1573 +#: C/index.docbook:1663 msgid "" "There are a couple of extra files, that need to be maintained along with the " "inline source code comments: <package>.types, " @@ -2678,12 +2808,12 @@ msgstr "" "pasado) y <paquete>-sections.txt." #. (itstool) path: sect1/title -#: C/index.docbook:1582 +#: C/index.docbook:1672 msgid "Editing the types file" msgstr "Editar los tipos de archivo" #. (itstool) path: sect1/para -#: C/index.docbook:1584 +#: C/index.docbook:1674 msgid "" "If your library or application includes GObjects, you want their signals, " "arguments/parameters and position in the hierarchy to be shown in the " @@ -2698,12 +2828,12 @@ msgstr "" "<paquete>.types." #. (itstool) path: example/title -#: C/index.docbook:1593 +#: C/index.docbook:1683 msgid "Example types file snippet" msgstr "Fragmento de ejemplo de tipos de archivo" #. (itstool) path: example/programlisting -#: C/index.docbook:1594 +#: C/index.docbook:1684 #, no-wrap msgid "" "\n" @@ -2723,7 +2853,7 @@ msgstr "" "gtk_arrow_get_type\n" #. (itstool) path: sect1/para -#: C/index.docbook:1605 +#: C/index.docbook:1695 msgid "" "Since GTK-Doc 1.8 gtkdoc-scan can generate this " "list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in " @@ -2736,12 +2866,12 @@ msgstr "" "los tipos de archivo ni tenerlos bajo el control de versiones." #. (itstool) path: sect1/title -#: C/index.docbook:1614 +#: C/index.docbook:1704 msgid "Editing the master document" msgstr "Editar la sección maestra del documento" #. (itstool) path: sect1/para -#: C/index.docbook:1616 +#: C/index.docbook:1706 msgid "" "GTK-Doc produces documentation in DocBook SGML/XML. When processing the " "inline source comments, the GTK-Doc tools generate one documentation page " @@ -2754,7 +2884,7 @@ msgstr "" "documento maestro las incluye y ordena." #. (itstool) path: sect1/para -#: C/index.docbook:1623 +#: C/index.docbook:1713 msgid "" "While GTK-Doc creates a template master document for you, later runs will " "not touch it again. This means that one can freely structure the " @@ -2771,7 +2901,7 @@ msgstr "" "vez en cuando para ver si se han introducido algunas mejoras." #. (itstool) path: tip/para -#: C/index.docbook:1633 +#: C/index.docbook:1723 msgid "" "Do not create tutorials as extra documents. Just write extra chapters. The " "benefit of directly embedding the tutorial for your library into the API " @@ -2786,7 +2916,7 @@ msgstr "" "el tutorial junto con la biblioteca son mayores." #. (itstool) path: sect1/para -#: C/index.docbook:1642 +#: C/index.docbook:1732 msgid "" "So what are the things to change inside the master document? For a start is " "only a little. There are some placeholders (text in square brackets) there " @@ -2797,12 +2927,12 @@ msgstr "" "que habría que encargarse." #. (itstool) path: example/title -#: C/index.docbook:1649 +#: C/index.docbook:1739 msgid "Master document header" msgstr "Cabecera del documento maestro" #. (itstool) path: example/programlisting -#: C/index.docbook:1650 +#: C/index.docbook:1740 #, no-wrap msgid "" "\n" @@ -2832,7 +2962,7 @@ msgstr "" " <title>[Insert title here]</title>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1666 +#: C/index.docbook:1756 msgid "" "In addition a few option elements are created in commented form. You can " "review these and enable them as you like." @@ -2841,26 +2971,31 @@ msgstr "" "Puede revisarlos y activarlos como quiera." #. (itstool) path: example/title -#: C/index.docbook:1672 +#: C/index.docbook:1762 msgid "Optional part in the master document" msgstr "Parte opcional en el documento maestro" #. (itstool) path: example/programlisting -#: C/index.docbook:1673 +#: C/index.docbook:1763 #, no-wrap +#| msgid "" +#| "\n" +#| " <!-- enable this when you use gobject introspection annotations\n" +#| " <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n" +#| " --> \n" msgid "" "\n" " <!-- enable this when you use gobject introspection annotations\n" " <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n" -" --> \n" +" -->\n" msgstr "" "\n" -" <!-- enable this when you use gobject introspection annotations\n" +" <!-- active esto cuando use anotaciones de introspección de gobject\n" " <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n" " --> \n" #. (itstool) path: sect1/para -#: C/index.docbook:1681 +#: C/index.docbook:1771 msgid "" "Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind " @@ -2872,12 +3007,12 @@ msgstr "" "todavía en la documentación." #. (itstool) path: example/title -#: C/index.docbook:1689 C/index.docbook:1724 +#: C/index.docbook:1779 C/index.docbook:1814 msgid "Including generated sections" msgstr "Incluir secciones generadas" #. (itstool) path: example/programlisting -#: C/index.docbook:1690 +#: C/index.docbook:1780 #, no-wrap msgid "" "\n" @@ -2893,12 +3028,12 @@ msgstr "" " ...\n" #. (itstool) path: sect1/title -#: C/index.docbook:1702 +#: C/index.docbook:1792 msgid "Editing the section file" msgstr "Editar el archivo de sección" #. (itstool) path: sect1/para -#: C/index.docbook:1704 +#: C/index.docbook:1794 msgid "" "The section file is used to organise the documentation output by GTK-Doc. " "Here one specifies which symbol belongs to which module or class and control " @@ -2909,7 +3044,7 @@ msgstr "" "y el control de la visibilidad (pública o privada)." #. (itstool) path: sect1/para -#: C/index.docbook:1710 +#: C/index.docbook:1800 msgid "" "The section file is a plain text file with tags delimiting sections. Blank " "lines are ignored and lines starting with a '#' are treated as comment lines." @@ -2919,7 +3054,7 @@ msgstr "" "comiencen con «#» se tratan como comentarios." #. (itstool) path: note/para -#: C/index.docbook:1717 +#: C/index.docbook:1807 msgid "" "While the tags make the file look like xml, it is not. Please do not close " "tags like <SUBSECTION>." @@ -2928,7 +3063,7 @@ msgstr "" "etiquetas del tipo <SUBSECTION>." #. (itstool) path: example/programlisting -#: C/index.docbook:1725 +#: C/index.docbook:1815 #, no-wrap msgid "" "\n" @@ -2960,7 +3095,7 @@ msgstr "" "</SECTION>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1742 +#: C/index.docbook:1832 msgid "" "The <FILE> ... </FILE> tag is used to specify the file name, " "without any suffix. For example, using '<FILE>gnome-config</" @@ -2983,7 +3118,7 @@ msgstr "" "clase de GObject convertido a minúscula.)" #. (itstool) path: sect1/para -#: C/index.docbook:1754 +#: C/index.docbook:1844 msgid "" "The <TITLE> ... </TITLE> tag is used to specify the title of the " "section. It is only useful before the templates (if used) are initially " @@ -2997,7 +3132,7 @@ msgstr "" "obsoleto." #. (itstool) path: sect1/para -#: C/index.docbook:1761 +#: C/index.docbook:1851 msgid "" "You can group items in the section by using the <SUBSECTION> tag. " "Currently it outputs a blank line between subsections in the synopsis " @@ -3027,7 +3162,7 @@ msgstr "" "públicas (variables, vmethods)." #. (itstool) path: sect1/para -#: C/index.docbook:1780 +#: C/index.docbook:1870 msgid "" "You can also use <INCLUDE> ... </INCLUDE> to specify the " "#include files which are shown in the synopsis sections. It contains a comma-" @@ -3043,12 +3178,12 @@ msgstr "" "a esa sección." #. (itstool) path: chapter/title -#: C/index.docbook:1794 +#: C/index.docbook:1884 msgid "Controlling the result" msgstr "Controlar el resultado" #. (itstool) path: chapter/para -#: C/index.docbook:1796 +#: C/index.docbook:1886 msgid "" "A GTK-Doc run generates report files inside the documentation directory. The " "generated files are named: <package>-undocumented.txt<package>-undocumented.txt file starts with " "the documentation coverage summary. Below are two sections divided by blank " @@ -3079,7 +3214,7 @@ msgstr "" "documentación pero dónde; p.e. se ha añadido un parámetro nuevo." #. (itstool) path: chapter/para -#: C/index.docbook:1814 +#: C/index.docbook:1904 msgid "" "The <package>-undeclared.txt file lists symbols " "given in the <package>-sections.txt but not found " @@ -3091,7 +3226,7 @@ msgstr "" "eliminado o no se han escrito correctamente." #. (itstool) path: chapter/para -#: C/index.docbook:1821 +#: C/index.docbook:1911 msgid "" "The <package>-unused.txt file lists symbol names, " "where the GTK-Doc scanner has found documentation, but does not know where " @@ -3104,7 +3239,7 @@ msgstr "" "todavía al archivo <paquete>-sections.txt." #. (itstool) path: tip/para -#: C/index.docbook:1829 +#: C/index.docbook:1919 msgid "" "Enable or add the line in Makefile." "am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during " @@ -3115,7 +3250,7 @@ msgstr "" "de integridad durante la ejecución de make check." #. (itstool) path: chapter/para -#: C/index.docbook:1836 +#: C/index.docbook:1926 msgid "" "One can also look at the files produced by the source code scanner: " "<package>-decl-list.txt and <" @@ -3132,7 +3267,7 @@ msgstr "" "si este archivo lo contiene." #. (itstool) path: chapter/para -#: C/index.docbook:1845 +#: C/index.docbook:1935 msgid "" "If the project is GObject based, one can also look into the files produced " "by the object scanner: <package>.args.txt, " @@ -3153,12 +3288,12 @@ msgstr "" "ejecutándolo como GTK_DOC_KEEP_INTERMEDIATE=1 make." #. (itstool) path: chapter/title -#: C/index.docbook:1860 +#: C/index.docbook:1950 msgid "Modernizing the documentation" msgstr "Modernizar la documentación" #. (itstool) path: chapter/para -#: C/index.docbook:1862 +#: C/index.docbook:1952 msgid "" "GTK-Doc has been around for quite some time. In this section we list new " "features together with the version since when it is available." @@ -3167,12 +3302,12 @@ msgstr "" "características nuevas junto con la versión desde la que están disponibles." #. (itstool) path: sect1/title -#: C/index.docbook:1868 +#: C/index.docbook:1958 msgid "GTK-Doc 1.9" msgstr "GTK-Doc 1.9" #. (itstool) path: sect1/para -#: C/index.docbook:1870 +#: C/index.docbook:1960 msgid "" "When using xml instead of sgml, one can actually name the master document " "<package>-docs.xml." @@ -3181,7 +3316,7 @@ msgstr "" "maestro <paquete>-docs.xml." #. (itstool) path: sect1/para -#: C/index.docbook:1875 +#: C/index.docbook:1965 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3202,14 +3337,23 @@ msgstr "" "paquete>-decl-list.txt <paquete>-sections.txt." #. (itstool) path: sect1/para -#: C/index.docbook:1886 +#: C/index.docbook:1976 +#| msgid "" +#| "Version 1.8 already introduced the syntax for documenting sections in the " +#| "sources instead of the separate files under 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 " +#| "you source control system and haven't yet switched, just add the flag to " +#| "configure.ac and you are done." 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 you source " +"tmpl checked into your source " "control system and haven't yet switched, just add the flag to " "configure.ac and you are done." msgstr "" @@ -3224,12 +3368,12 @@ msgstr "" "configure.ac y lo tendrá hecho." #. (itstool) path: sect1/title -#: C/index.docbook:1898 +#: C/index.docbook:1988 msgid "GTK-Doc 1.10" msgstr "GTK-Doc 1.10" #. (itstool) path: sect1/para -#: C/index.docbook:1900 +#: C/index.docbook:1990 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3247,17 +3391,17 @@ msgstr "" "condicional." #. (itstool) path: sect1/title -#: C/index.docbook:1911 +#: C/index.docbook:2001 msgid "GTK-Doc 1.16" msgstr "GTK-Doc 1.16" #. (itstool) path: example/title -#: C/index.docbook:1917 +#: C/index.docbook:2007 msgid "Enable gtkdoc-check" msgstr "Activar gtkdoc-check" #. (itstool) path: example/programlisting -#: C/index.docbook:1918 +#: C/index.docbook:2008 #, no-wrap msgid "" "\n" @@ -3277,7 +3421,7 @@ msgstr "" "endif\n" #. (itstool) path: sect1/para -#: C/index.docbook:1913 +#: C/index.docbook:2003 msgid "" "This version includes a new tool called gtkdoc-check. This tool can run a " "set of sanity checks on your documentation. It is enabled by adding these " @@ -3289,12 +3433,12 @@ msgstr "" "archivo Makefile.am. <_:example-1/>" #. (itstool) path: sect1/title -#: C/index.docbook:1931 +#: C/index.docbook:2021 msgid "GTK-Doc 1.20" msgstr "GTK-Doc 1.20" #. (itstool) path: sect1/para -#: C/index.docbook:1933 +#: C/index.docbook:2023 msgid "" "Version 1.18 brought some initial markdown support. Using markdown in doc " "comments is less intrusive than writing docbook xml. This version improves a " @@ -3308,17 +3452,17 @@ msgstr "" "comentarios contiene todos los detalles." #. (itstool) path: sect1/title -#: C/index.docbook:1943 +#: C/index.docbook:2033 msgid "GTK-Doc 1.25" msgstr "GTK-Doc 1.25" #. (itstool) path: example/title -#: C/index.docbook:1953 +#: C/index.docbook:2043 msgid "Use pre-generated entities" msgstr "Usar entidades generadas previamenet" #. (itstool) path: example/programlisting -#: C/index.docbook:1954 +#: C/index.docbook:2044 #, no-wrap msgid "" "\n" @@ -3360,12 +3504,20 @@ msgstr "" " </bookinfo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1945 +#: C/index.docbook:2035 +#| msgid "" +#| "The makefiles shipped with this version generate an entity file at " +#| "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 any example that " +#| "shows how the entity file is included and how the entities are used. The " +#| "entities can also be used in all generated files, GTK-Doc will use the " +#| "same xml header in generated xml files. <_:example-1/>" msgid "" "The makefiles shipped with this version generate an entity file at " "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 any example that shows how " +"to avoid hardcoding the version number. Below is an example that shows how " "the entity file is included and how the entities are used. The entities can " "also be used in all generated files, GTK-Doc will use the same xml header in " "generated xml files. <_:example-1/>" @@ -3380,12 +3532,12 @@ msgstr "" "archivos XML generados. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1979 +#: C/index.docbook:2069 msgid "Documenting other interfaces" msgstr "Documentar otras interfaces" #. (itstool) path: chapter/para -#: C/index.docbook:1981 +#: C/index.docbook:2071 msgid "" "So far we have been using GTK-Doc to document the API of code. The next " "sections contain suggestions how the tools can be used to document other " @@ -3396,12 +3548,12 @@ msgstr "" "herramientas para documentar otras interfaces." #. (itstool) path: sect1/title -#: C/index.docbook:1988 +#: C/index.docbook:2078 msgid "Command line options and man pages" msgstr "Opciones de la línea de comandos y páginas man" #. (itstool) path: sect1/para -#: C/index.docbook:1990 +#: C/index.docbook:2080 msgid "" "As one can generate man pages for a docbook refentry as well, it sounds like " "a good idea to use it for that purpose. This way the interface is part of " @@ -3412,12 +3564,12 @@ msgstr "" "interfaz es parte de la referencia y se obtienen las páginas man sin trabajo." #. (itstool) path: sect2/title -#: C/index.docbook:1997 +#: C/index.docbook:2087 msgid "Document the tool" msgstr "Documentar la herramienta" #. (itstool) path: sect2/para -#: C/index.docbook:1999 +#: C/index.docbook:2089 msgid "" "Create one refentry file per tool. Following our example we would call it meep/" @@ -3432,17 +3584,17 @@ msgstr "" "así como los ejemplos en, por ejemplo, glib." #. (itstool) path: sect2/title -#: C/index.docbook:2009 +#: C/index.docbook:2099 msgid "Adding the extra configure check" msgstr "Añadir la comprobación de configuración adicional" #. (itstool) path: example/title -#: C/index.docbook:2012 C/index.docbook:2030 +#: C/index.docbook:2102 C/index.docbook:2120 msgid "Extra configure checks" msgstr "Comprobaciones de configuración adicionales" #. (itstool) path: example/programlisting -#: C/index.docbook:2013 +#: C/index.docbook:2103 #, no-wrap msgid "" "\n" @@ -3464,12 +3616,12 @@ msgstr "" "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" #. (itstool) path: sect2/title -#: C/index.docbook:2027 +#: C/index.docbook:2117 msgid "Adding the extra makefile rules" msgstr "Añadir reglas de makefile adicionales" #. (itstool) path: example/programlisting -#: C/index.docbook:2031 +#: C/index.docbook:2121 #, no-wrap msgid "" "\n" @@ -3505,12 +3657,12 @@ msgstr "" "EXTRA_DIST += meep.xml\n" #. (itstool) path: sect1/title -#: C/index.docbook:2053 +#: C/index.docbook:2143 msgid "DBus interfaces" msgstr "Interfaces de DBus" #. (itstool) path: sect1/para -#: C/index.docbook:2055 +#: C/index.docbook:2145 msgid "" "(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" @@ -3519,27 +3671,27 @@ msgstr "" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" #. (itstool) path: chapter/title -#: C/index.docbook:2064 +#: C/index.docbook:2154 msgid "Frequently asked questions" msgstr "Preguntas más frecuentes" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2068 +#: C/index.docbook:2158 msgid "Question" msgstr "Pregunta" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2069 +#: C/index.docbook:2159 msgid "Answer" msgstr "Respuesta" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2071 +#: C/index.docbook:2161 msgid "No class hierarchy." msgstr "Sin jerarquía de clases." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2072 +#: C/index.docbook:2162 msgid "" "The objects xxx_get_type() function has not been " "entered into the <package>.types file." @@ -3548,12 +3700,12 @@ msgstr "" "introducido en el archivo <package>.types." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2078 +#: C/index.docbook:2168 msgid "Still no class hierarchy." msgstr "Aún sin jerarquía de clases." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2079 +#: C/index.docbook:2169 msgid "" "Missing or wrong naming in <package>-sections.txt " "file (see explicación)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2085 +#: C/index.docbook:2175 msgid "Damn, I have still no class hierarchy." msgstr "Maldición, aún no hay una jerarquía de clases." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2086 +#: C/index.docbook:2176 msgid "" "Is the object name (name of the instance struct, e.g. GtkWidget) part of the normal section (don't put this into Standard or Private " @@ -3580,12 +3732,12 @@ msgstr "" "Estándar o Privado)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2093 +#: C/index.docbook:2183 msgid "No symbol index." msgstr "Sin índice de símbolos." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2094 +#: C/index.docbook:2184 msgid "" "Does the <package>-docs.{xml,sgml} contain a " "index that xi:includes the generated index?" @@ -3594,12 +3746,12 @@ msgstr "" "«xi:includes» el índice generado?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2100 +#: C/index.docbook:2190 msgid "Symbols are not linked to their doc-section." msgstr "Los símbolos no se enlazan con su sección en el documento." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2101 +#: C/index.docbook:2191 msgid "" "Is the doc-comment using the correct markup (added #,% or ())? Check if the " "gtkdoc-fixxref warns about unresolvable xrefs." @@ -3608,12 +3760,12 @@ msgstr "" "si gtk-doc-fixxref avisa de alguna referencia xref sin resolver." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2107 +#: C/index.docbook:2197 msgid "A new class does not appear in the docs." msgstr "Una clase nueva no aparece en la documentación." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2108 +#: C/index.docbook:2198 msgid "" "Is the new page xi:included from <package>-docs.{xml,sgml}." @@ -3622,12 +3774,12 @@ msgstr "" "sgml}." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2114 +#: C/index.docbook:2204 msgid "A new symbol does not appear in the docs." msgstr "Un símbolo nuevo no aparece en la documentación." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2115 +#: C/index.docbook:2205 msgid "" "Is the doc-comment properly formatted. Check for spelling mistakes in the " "begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable " @@ -3641,12 +3793,12 @@ msgstr "" "txt en una subsección pública." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2123 +#: C/index.docbook:2213 msgid "A type is missing from the class hierarchy." msgstr "Falta un tipo en la clase de jerarquías" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2124 +#: C/index.docbook:2214 msgid "" "If the type is listed in <package>.hierarchy but " "not in xml/tree_index.sgml then double check that the " @@ -3662,14 +3814,14 @@ msgstr "" "privada." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2133 +#: C/index.docbook:2223 msgid "I get foldoc links for all gobject annotations." msgstr "" "Obtengo enlaces de seguimiento de documentos para todas las anotaciones " "gobject." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2134 +#: C/index.docbook:2224 msgid "" "Check that xml/annotation-glossary.xml is xi:included " "from <package>-docs.{xml,sgml}." @@ -3678,14 +3830,14 @@ msgstr "" "included» desde <package>-docs.{xml,sgml}." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2142 +#: C/index.docbook:2232 msgid "Parameter described in source code comment block but does not exist" msgstr "" "Parámetro descrito en el bloque de comentarios del código fuente pero no " "existe" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2143 +#: C/index.docbook:2233 msgid "" "Check if the prototype in the header has different parameter names as in the " "source." @@ -3694,12 +3846,12 @@ msgstr "" "diferentes de la fuente." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2148 +#: C/index.docbook:2238 msgid "multiple \"IDs\" for constraint linkend: XYZ" msgstr "múltiples «ID» para la restricción enlazada: XYZ" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2149 +#: C/index.docbook:2239 msgid "" "Symbol XYZ appears twice in <package>-sections.txt file." @@ -3708,7 +3860,7 @@ msgstr "" "sections.txt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2152 +#: C/index.docbook:2242 msgid "" "Element typename in namespace '' encountered in para, but no template " "matches." @@ -3717,12 +3869,12 @@ msgstr "" "coincide." #. (itstool) path: chapter/title -#: C/index.docbook:2159 +#: C/index.docbook:2249 msgid "Tools related to gtk-doc" msgstr "Herramientas relacionadas con GTK-Doc" #. (itstool) path: chapter/para -#: C/index.docbook:2161 +#: C/index.docbook:2251 msgid "" "GtkDocPlugin - a Trac " "GTK-Doc integration plugin, that adds API docs to a trac site and " @@ -3733,7 +3885,7 @@ msgstr "" "a un sitio «trac» y se integra con la búsqueda de «trac»." #. (itstool) path: chapter/para -#: C/index.docbook:2166 +#: C/index.docbook:2256 msgid "" "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " "tags in the API to determine the minimum required version." @@ -4729,9 +4881,9 @@ msgstr "" #: C/index.docbook:629 C/fdl-appendix.xml:629 msgid "Copyright YEAR YOUR NAME." msgstr "" +"Copyright 2009-2016 Daniel Mustieles\n" "Copyright 2009-2010 Jorge González González\n" -"Copyright 2009-2010 Francisco Javier Fernández Serrador\n" -"Copyright 2009 Daniel Mustieles" +"Copyright 2009-2010 Francisco Javier Fernández Serrador" #. (itstool) path: blockquote/para #: C/index.docbook:632 @@ -5699,6 +5851,35 @@ msgstr "" "libre que usted elija, como la <_:ulink-1/>, para permitir su uso en " "software libre." +#~ 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 "" +#~ "Generar los archivos «plantilla». " +#~ "gtkdoc-mktmpl crea un número de archivos en la " +#~ "subcarpeta tmpl/, usando la " +#~ "información obtenida en el primer paso. (Tenga en cuenta que esto se " +#~ "puede ejecutar de forma separada. Intentará asegurarse de que la " +#~ "documentación nunca se pierde.)" + +#~ msgid "" +#~ "Since GTK-Doc 1.9 the templates can be avoided. We encourage people to " +#~ "keep documentation in the code. 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 "" +#~ "Desde de GTK-Doc 1.9 se pueden evitar las plantillas. Animamos a la gente " +#~ "a que mantenga la documentación en el código. gtkdocize ahora soporta una opción --flavour no-tmpl que elige un archivo makefile que omite completamente el uso de " +#~ "tmpl. Si nunca ha cambiado a mano el archivo tmpl, elimine la carpeta una " +#~ "vez (por ejemplo, desde el sistema de control de versiones)." + #~ msgid "(FIXME : Stability information)" #~ msgstr "(ARREGLAR: estabilidad de la información)" diff --git a/help/manual/es/fdl-appendix.xml b/help/manual/es/fdl-appendix.xml index 42d6733..aab509f 100644 --- a/help/manual/es/fdl-appendix.xml +++ b/help/manual/es/fdl-appendix.xml @@ -222,9 +222,9 @@ Para usar esta licencia en un documento que ha escrito, incluya una copia de la Licencia en el documento y ponga el siguiente copyright y las notas justo después del título de la página.
- Copyright 2009-2010 Jorge González González -Copyright 2009-2010 Francisco Javier Fernández Serrador -Copyright 2009 Daniel Mustieles + Copyright 2009-2016 Daniel Mustieles +Copyright 2009-2010 Jorge González González +Copyright 2009-2010 Francisco Javier Fernández Serrador Se otorga permiso para copiar, distribuir y/o modificar este documento bajo los términos de la Licencia de Documentación Libre de GNU, Versión 1.1 o cualquier otra versión posterior publicada por la Free Software Foundation; con las Secciones invariantes siendo su LISTE SUS TÍTULOS, con Textos de cubierta delantera siendo LISTA, y con los Textos de cubierta trasera siendo LISTA. Una copia de la licencia está incluida en la sección titulada Licencia de documentación libre de GNU.
diff --git a/help/manual/es/index.docbook b/help/manual/es/index.docbook index 3371205..a2fc29e 100644 --- a/help/manual/es/index.docbook +++ b/help/manual/es/index.docbook @@ -34,7 +34,8 @@ - 1.24.1 30 de mayo de 2015 ss versión de desarrollo + 1.25.1 21 de mayo de 2016 ss versión de desarrollo + 1.25 21 de marzo de 2016 ss correcciones de errores, limpieza 1.24 29 de mayo de 2015 ss correcciones de errores 1.23 17 de mayo de 2015 ss correcciones de errores 1.22 7 de mayo de 2015 ss correcciones de errores, eliminadas funcionalidades obsoletas @@ -60,7 +61,7 @@ - 2009 - 2015 + 2009 - 2017 Daniel Mustieles @@ -128,13 +129,6 @@ gtkdoc-scanobj no se debería usar más. Se necesitó en el pasado, cuando GObject todavía era GtkObject dentro de GTK+. - - Generar los archivos «plantilla». gtkdoc-mktmpl crea un número de archivos en la subcarpeta tmpl/, usando la información obtenida en el primer paso. (Tenga en cuenta que esto se puede ejecutar de forma separada. Intentará asegurarse de que la documentación nunca se pierde.) - - Desde de GTK-Doc 1.9 se pueden evitar las plantillas. Animamos a la gente a que mantenga la documentación en el código. gtkdocize ahora soporta una opción --flavour no-tmpl que elige un archivo makefile que omite completamente el uso de tmpl. Si nunca ha cambiado a mano el archivo tmpl, elimine la carpeta una vez (por ejemplo, desde el sistema de control de versiones). - - - Generar el XML y el HTML/PDF.gtkdoc-mkdb convierte los archivos de plantilla en archivos SGML o XML en la subcarpeta xml/. Si el código fuente contiene documentación de funciones, usando los bloques especiales de comentarios, entonces se mezclarán aquí. Si no se usan archivos tmpl sólo obtiene los documentos de los fuentes y los datos obtenidos en introspección. gtkdoc-mkhtml convierte los archivos XML en archivos HTML en la subcarpeta html/. De la misma forma gtkdoc-mkpdf convierte los archivos XML en un documento PDF llamado <paquete>.pdf. @@ -242,7 +236,7 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) 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). - 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 del macro para GTK_DOC_CHECK a su proyecto. + 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. Preparación para gtkdocize @@ -825,6 +819,93 @@ typedef enum { + + + Documentación en línea del programa + Puede documentar programas y su interfaz de línea de comandos usando la documentación en línea. + + + Etiquetas + + PROGRAM + + + Define el inicio de la documentación de un programa. + + + + + @short_description: + + Define una descripción corta del programa. (Opcional) + + + + + @synopsis: + + Define el argumento o la lista de argumentos que el programa puede usar. (Opcional) + + + + + @see_also: + + Página del manual Ver también. (Opcional) + + + + + @arg: + + Argumentos pasados al programa y su descripción. (Opcional) + + + + + Description: + + Una descripción más larga del programa. + + + + + Devuelve: + + Especifique qué valores devuelve el programa. (Opcional) + + + + + + + Ejemplo de documentación de un programa. + Bloque de documentación del programa + +/** + * PROGRAM:test-program + * @short_description: A test program + * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE* + * @see_also: test(1) + * @--arg1 *arg*: set arg1 to *arg* + * @--arg2 *arg*: set arg2 to *arg* + * @-v, --version: Print the version number + * @-h, --help: Print the help message + * + * Long description of program. + * + * Returns: Zero on success, non-zero on failure + */ +int main(int argc, char *argv[]) +{ + return 0; +} + + + + + + Etiquetas DocBook útiles @@ -992,17 +1073,17 @@ gtk_arrow_get_type Se crean además unos pocos elementos de opciones de la manera comentada. Puede revisarlos y activarlos como quiera. - + Parte opcional en el documento maestro - <!-- enable this when you use gobject introspection annotations + <!-- active esto cuando use anotaciones de introspección de gobject <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> --> - + Por último, necesita añadir una sección nueva siempre que quiera introducir una. La herramienta gtkdoc-check le recordará los nuevos archivos xml generados que no estén inclídos todavía en la documentación. @@ -1024,7 +1105,7 @@ gtk_arrow_get_type El archivo de sección se usa para organizar la salida de la documentación por GTK-Doc. Aquí se especifica qué símbolos pertenecen a qué módulo o clase y el control de la visibilidad (pública o privada). El archivo de sección es un archivo de texto plano con etiquetas que delimitan las secciones. Se ignoran las líneas vacías y las líneas que comiencen con «#» se tratan como comentarios. - + Aunque las etiquetas hacen que el archivo parezca XML, no lo es. No incluya etiquetas del tipo <SUBSECTION>. @@ -1079,22 +1160,22 @@ meep_app_get_type Si el proyecto está basado en GObject, también se puede mirar en los archivos producidos por el analizador de objetos: <paquete>.args.txt, <paquete>.hierarchy.txt, <paquete>.interfaces.txt, <paquete>.prerequisites.txt y <paquete>.signals.txt. Si faltan símbolos en cualquiera de ellos, puede hacer que GTK-Doc guarde el análisis de archivos para futuros análisis, pero ejecutándolo como GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizar la documentación - + GTK-Doc ha existido durante mucho tiempo. En esta sección se listan las características nuevas junto con la versión desde la que están disponibles. - + GTK-Doc 1.9 Al usar XML en lugar de SGML, actualmente se puede nombrar el documento maestro <paquete>-docs.xml. - + Esta versión soporta en Makefile.am. Cuando está activada, el archivo <paquete>-sections.txt se genera automáticamente y se puede quitar del control de versiones. Esto sólo funciona en proyectos que tienen una estructura regular (ej. cada pareja .{c,h} creará una sección nueva). Si se organiza un proyecto parecido a esto, actualizar una sección mantenida manualmente puede ser tan sencillo como ejecutar meld <paquete>-decl-list.txt <paquete>-sections.txt. - + La versión 1.18 ya introdujo la sintaxis para documentar secciones en las fuentes en lugar de tener que hacerlo en archivos separados bajo tmpl. Esta versión añade opciones para cambiar todo el módulo «doc» del documento para que no realice el paso de construcción de tmpl adicional, usando en configure.ac. Si no tiene una tmpl marcada en su sistema de control de versiones y todavía no ha cambiado, simplemente añada la opción al archivo configure.ac y lo tendrá hecho. - + GTK-Doc 1.10 @@ -1510,9 +1591,9 @@ EXTRA_DIST += meep.xml Para usar esta licencia en un documento que ha escrito, incluya una copia de la Licencia en el documento y ponga el siguiente copyright y las notas justo después del título de la página.
- Copyright 2009-2010 Jorge González González -Copyright 2009-2010 Francisco Javier Fernández Serrador -Copyright 2009 Daniel Mustieles + Copyright 2009-2016 Daniel Mustieles +Copyright 2009-2010 Jorge González González +Copyright 2009-2010 Francisco Javier Fernández Serrador Se otorga permiso para copiar, distribuir y/o modificar este documento bajo los términos de la Licencia de Documentación Libre de GNU, Versión 1.1 o cualquier otra versión posterior publicada por la Free Software Foundation; con las Secciones Invariantes siendo su LISTE SUS TÍTULOS, con Textos de Cubierta Delantera siendo LISTA, y con los Textos de Cubierta Trasera siendo LISTA. Una copia de la licencia está incluida en la sección titulada GNU Free Documentation License.
diff --git a/help/manual/fr/index.docbook b/help/manual/fr/index.docbook index 31ceb83..eb1d809 100644 --- a/help/manual/fr/index.docbook +++ b/help/manual/fr/index.docbook @@ -46,10 +46,16 @@ - 1.24.1 - 30 May 2015 + 1.25.1 + 21 March 2016 + ss + development version + + + 1.25 + 21 March 2016 ss - development version + bug fixes, test cleanups 1.24 @@ -218,13 +224,6 @@ gtkdoc-scanobj ne devrait plus être utilisé. Il était nécessaire par le passé lorsque GObject était encore GtkObject dans gtk+. - - 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). - - 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). - - - Generating the XML and HTML/PDF. @@ -242,7 +241,7 @@ document called <package>.pdf. - Files in xml/ and + Files in xml/ and html/ directories are always overwritten. One should never edit them directly. @@ -363,7 +362,12 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) 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). - De plus, il est recommandé d'avoir la ligne suivante dans votre script configure.ac. Cela permet à gtkdocize de copier automatiquement les définitions de macro pour GTK_DOC_CHECK à votre projet. + + 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. + Préparation pour gtkdocize @@ -383,12 +387,12 @@ AC_CONFIG_MACRO_DIR(m4) Intégration avec automake - First copy the Makefile.am from the + 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. + 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. @@ -527,7 +531,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html The scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + hint GTK-Doc to skip over them. GTK-Doc comment block Limitations Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not + #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations. @@ -640,7 +644,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + XML tags inside doc-comments by putting (or ) in the variable MKDB_OPTIONS inside Makefile.am. @@ -724,7 +728,12 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html SECTION:<nom> - Le nom relie la section de la documentation à la partie respective dans le fichier <package>-sections.txt. Le nom fourni ici doit correspondre à la balise <FILE> du fichier <package>-sections.txt. + + The name links the section documentation to the respective part in + the <package>-sections.txt file. The + name given here should match the <FILE> tag in the + <package>-sections.txt file. + @@ -913,7 +922,7 @@ foo_get_bar(Foo *foo) Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list - of the supported tags can be found on + of the supported tags can be found on the wiki. @@ -1089,6 +1098,111 @@ typedef enum { + + + Inline program documentation + + You can document programs and their commandline interface using inline + documentation. + + + + Tags + + PROGRAM + + + + Defines the start of a program documentation. + + + + + + @short_description: + + + Defines a short description of the program. (Optional) + + + + + + @synopsis: + + + Defines the arguments, or list of arguments that the program can take. + (Optional) + + + + + + @see_also: + + + See Also manual page section. (Optional) + + + + + + @arg: + + + Argument(s) passed to the program and their description. (Optional) + + + + + + Description: + + + A longer description of the program. + + + + + + « Returns » : + + + Specificy what value(s) the program returns. (Optional) + + + + + + + + Example of program documentation. + Program documentation block + + + + + + Balises DocBook utiles @@ -1272,17 +1386,17 @@ gtk_arrow_get_type In addition a few option elements are created in commented form. You can review these and enable them as you like. - + Optional part in the master document - --> + --> ]]> - + Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will @@ -1313,7 +1427,7 @@ gtk_arrow_get_type Blank lines are ignored and lines starting with a '#' are treated as comment lines. - + While the tags make the file look like xml, it is not. Please do not @@ -1416,15 +1530,15 @@ meep_app_get_type GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizing the documentation - + 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. - + GTK-Doc 1.9 @@ -1432,7 +1546,7 @@ meep_app_get_type When using xml instead of sgml, one can actually name the master document <package>-docs.xml. - + This version supports in Makefile.am. When this is enabled, the @@ -1440,21 +1554,21 @@ meep_app_get_type can be removed from the vcs. This only works nicely for projects that have a very regular structure (e.g. each .{c,h} pair will create new section). If one organize a project close to that updating a manually - maintained section file can be as simple as running + maintained section file can be as simple as running meld <package>-decl-list.txt <package>-sections.txt. - + 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 you source control system and haven't yet switched, just + checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. - + GTK-Doc 1.10 @@ -1507,7 +1621,7 @@ endif 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 any example that shows how the entity file is included + number. Below is an example that shows how the entity file is included and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. diff --git a/help/manual/gl/index.docbook b/help/manual/gl/index.docbook index 546d3a1..0649a00 100644 --- a/help/manual/gl/index.docbook +++ b/help/manual/gl/index.docbook @@ -44,10 +44,16 @@ - 1.24.1 - 30 May 2015 + 1.25.1 + 21 March 2016 + ss + development version + + + 1.25 + 21 March 2016 ss - development version + bug fixes, test cleanups 1.24 @@ -211,27 +217,6 @@ - - - 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.) - - - - 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). - - - - Generating the XML and HTML/PDF. @@ -249,7 +234,7 @@ document called <package>.pdf. - Files in xml/ and + Files in xml/ and html/ directories are always overwritten. One should never edit them directly. @@ -424,7 +409,7 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) Furthermore it is recommended that you have the following line inside - you configure.ac script. + your configure.ac script. This allows gtkdocize to automatically copy the macro definition for GTK_DOC_CHECK to your project. @@ -447,12 +432,12 @@ AC_CONFIG_MACRO_DIR(m4) Integration with automake - First copy the Makefile.am from the + 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. + 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. @@ -661,7 +646,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html The scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + hint GTK-Doc to skip over them. GTK-Doc comment block Limitations Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not + #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations. @@ -812,7 +797,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + XML tags inside doc-comments by putting (or ) in the variable MKDB_OPTIONS inside Makefile.am. @@ -913,7 +898,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + name given here should match the <FILE> tag in the <package>-sections.txt file. @@ -1143,7 +1128,7 @@ foo_get_bar(Foo *foo) Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list - of the supported tags can be found on + of the supported tags can be found on the wiki. @@ -1361,6 +1346,111 @@ typedef enum { + + + Inline program documentation + + You can document programs and their commandline interface using inline + documentation. + + + + Tags + + PROGRAM + + + + Defines the start of a program documentation. + + + + + + @short_description: + + + Defines a short description of the program. (Optional) + + + + + + @synopsis: + + + Defines the arguments, or list of arguments that the program can take. + (Optional) + + + + + + @see_also: + + + See Also manual page section. (Optional) + + + + + + @arg: + + + Argument(s) passed to the program and their description. (Optional) + + + + + + Description: + + + A longer description of the program. + + + + + + Returns: + + + Specificy what value(s) the program returns. (Optional) + + + + + + + + Example of program documentation. + Program documentation block + + + + + + Useful DocBook tags @@ -1623,17 +1713,17 @@ gtk_arrow_get_type In addition a few option elements are created in commented form. You can review these and enable them as you like. - + Optional part in the master document - --> + --> ]]> - + Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will @@ -1668,7 +1758,7 @@ gtk_arrow_get_type Blank lines are ignored and lines starting with a '#' are treated as comment lines. - + While the tags make the file look like xml, it is not. Please do not @@ -1811,15 +1901,15 @@ meep_app_get_type GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizing the documentation - + 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. - + GTK-Doc 1.9 @@ -1827,7 +1917,7 @@ meep_app_get_type When using xml instead of sgml, one can actually name the master document <package>-docs.xml. - + This version supports in Makefile.am. When this is enabled, the @@ -1835,21 +1925,21 @@ meep_app_get_type can be removed from the vcs. This only works nicely for projects that have a very regular structure (e.g. each .{c,h} pair will create new section). If one organize a project close to that updating a manually - maintained section file can be as simple as running + maintained section file can be as simple as running meld <package>-decl-list.txt <package>-sections.txt. - + 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 you source control system and haven't yet switched, just + checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. - + GTK-Doc 1.10 @@ -1902,7 +1992,7 @@ endif 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 any example that shows how the entity file is included + number. Below is an example that shows how the entity file is included and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. diff --git a/help/manual/gu/index.docbook b/help/manual/gu/index.docbook index 68dcf87..47246c2 100644 --- a/help/manual/gu/index.docbook +++ b/help/manual/gu/index.docbook @@ -68,10 +68,16 @@ - 1.24.1 - 30 May 2015 + 1.25.1 + 21 March 2016 + ss + development version + + + 1.25 + 21 March 2016 ss - development version + bug fixes, test cleanups 1.24 @@ -219,27 +225,6 @@ - - - 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.) - - - - 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). - - - - Generating the XML and HTML/PDF. @@ -257,7 +242,7 @@ document called <package>.pdf. - Files in xml/ and + Files in xml/ and html/ directories are always overwritten. One should never edit them directly. @@ -413,7 +398,12 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) GTK-Doc એ મૂળભૂત રીતે નિષ્ક્રિય થયેલ છે! આગળનાં configure ને ચલાવવા માટે ને પસાર કરવાનું યાદ રાખો. નહિં તો પહેલીથી ઉત્પન્ન થયેલ દસ્તાવેજીકરણ સ્થાપિત થયેલ છે (કે જે વપરાશકર્તાઓ માટેનો અર્થ બને છે પરંતુ ડેવલપરો માટે નહિં). - આગળ વધારે તે અગ્રહણીય થયેલ છે કે જે તમારી પાસે તમારી configure.ac સ્ક્રિપ્ટની અંદર નીચેનું વાક્ય છે. આ તમારા પ્રોજેક્ટમાં GTK_DOC_CHECK માટે મેક્રો વ્યાખ્યાને આપમેળે નકલ કરવા માટે પરવાનગી આપે છે. + + 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. + gtkdocize માટે તૈયારી @@ -433,12 +423,12 @@ AC_CONFIG_MACRO_DIR(m4) automake સાથે એકત્રિકરણ - First copy the Makefile.am from the + 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. + 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. @@ -631,7 +621,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html The scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + hint GTK-Doc to skip over them. GTK-Doc comment block Limitations Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not + #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations. @@ -776,7 +766,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + XML tags inside doc-comments by putting (or ) in the variable MKDB_OPTIONS inside Makefile.am. @@ -863,7 +853,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + name given here should match the <FILE> tag in the <package>-sections.txt file. @@ -1082,7 +1072,7 @@ foo_get_bar(Foo *foo) Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list - of the supported tags can be found on + of the supported tags can be found on the wiki. @@ -1295,6 +1285,111 @@ typedef enum { + + + Inline program documentation + + You can document programs and their commandline interface using inline + documentation. + + + + Tags + + PROGRAM + + + + Defines the start of a program documentation. + + + + + + @short_description: + + + Defines a short description of the program. (Optional) + + + + + + @synopsis: + + + Defines the arguments, or list of arguments that the program can take. + (Optional) + + + + + + @see_also: + + + See Also manual page section. (Optional) + + + + + + @arg: + + + Argument(s) passed to the program and their description. (Optional) + + + + + + Description: + + + A longer description of the program. + + + + + + પાછુ આવે છે: + + + Specificy what value(s) the program returns. (Optional) + + + + + + + + Example of program documentation. + Program documentation block + + + + + + ઉપયોગી DocBook ટૅગ @@ -1550,17 +1645,17 @@ gtk_arrow_get_type In addition a few option elements are created in commented form. You can review these and enable them as you like. - + Optional part in the master document - --> + --> ]]> - + Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will @@ -1595,7 +1690,7 @@ gtk_arrow_get_type Blank lines are ignored and lines starting with a '#' are treated as comment lines. - + While the tags make the file look like xml, it is not. Please do not @@ -1724,15 +1819,15 @@ meep_app_get_type GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizing the documentation - + 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. - + GTK-Doc 1.9 @@ -1740,7 +1835,7 @@ meep_app_get_type When using xml instead of sgml, one can actually name the master document <package>-docs.xml. - + This version supports in Makefile.am. When this is enabled, the @@ -1748,21 +1843,21 @@ meep_app_get_type can be removed from the vcs. This only works nicely for projects that have a very regular structure (e.g. each .{c,h} pair will create new section). If one organize a project close to that updating a manually - maintained section file can be as simple as running + maintained section file can be as simple as running meld <package>-decl-list.txt <package>-sections.txt. - + 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 you source control system and haven't yet switched, just + checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. - + GTK-Doc 1.10 @@ -1815,7 +1910,7 @@ endif 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 any example that shows how the entity file is included + number. Below is an example that shows how the entity file is included and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. diff --git a/help/manual/pt_BR/fdl-appendix.xml b/help/manual/pt_BR/fdl-appendix.xml index b1549a5..e59b10b 100644 --- a/help/manual/pt_BR/fdl-appendix.xml +++ b/help/manual/pt_BR/fdl-appendix.xml @@ -74,7 +74,7 @@ A - Usar na Título da página (e nas capas, se existirem) um título distinto em relação ao do Documento, e daqueles de versões anteriores (os quais devem, na existência de algum, ser listados na seção "Histórico" do Documento). Você pode usar o mesmo título de uma versão anterior se o editor original daquela versão conceder-lhe permissão. + Usar na Título da página (e nas capas, se existirem) um título distinto em relação ao do Documento, e daqueles de versões anteriores (os quais devem, na existência de algum, ser listados na seção “Histórico” do Documento). Você pode usar o mesmo título de uma versão anterior se o editor original daquela versão conceder-lhe permissão. @@ -192,13 +192,7 @@ 6. COLEÇÕES DE DOCUMENTOS Você pode fazer uma coleção que consiste do Documento e outros documentos publicados sob esta Licença, e substituir as cópias individuais desta Licença, nos vários documentos, por uma única cópia a ser incluída na coleção, desde que você siga as regras desta Licença para cópias literais de cada documento em todos os outros aspectos. - - 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. - + Você pode extrair um único documento desta coleção, e distribuí-lo individualmente sob esta Licença, desde que você insira uma cópia desta Licença no documento extraído, e siga esta Licença em todos os outros aspectos com relação à cópia literal do documento. @@ -234,6 +228,6 @@ Se você não tiver qualquer Sessões invariantes, escreva sem Seções Invariantes ao invés de afirmar quais são invariantes. Se você não tem Textos de Capa Frontal, escreva sem Textos de Capa Frontal ao invés de Textos de Capa Frontal sendo LISTADOS; O mesmo se aplica a Textos de Contracapa. - Se seu documento contiver exemplos não-triviais de código de programação, recomendamos publicar estes exemplos paralelamente, sob a licença de software livre que você escolher, como por exemplo a Licença Pública Geral GNU (GPL) (GNU General Public License), para permitir seu uso em software livre. + Se seu documento contiver exemplos não-triviais de código de programação, recomendamos publicar estes exemplos paralelamente, sob a licença de software livre que você escolher, como, por exemplo, a Licença Pública Geral GNU (GPL), para permitir seu uso em software livre. diff --git a/help/manual/pt_BR/index.docbook b/help/manual/pt_BR/index.docbook index cc97330..be39f78 100644 --- a/help/manual/pt_BR/index.docbook +++ b/help/manual/pt_BR/index.docbook @@ -19,10 +19,7 @@ Projeto GTK-Doc
gtk-doc-list@gnome.org
 2000, 2005 Dan Mueth e Chris Lyttle - - 2007-2015 - Stefan Sauer (Kost) - + 2007-2015 Stefan Sauer (Kost) @@ -439,7 +374,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Comentários de documentação - Um comentário multilinha que começa com um "*" adicional marca um bloco de documentação que será processado pelas ferramentas do GTK-Doc. Bloco de comentário do GTK-Doc + Um comentário multilinha que começa com um “*” adicional marca um bloco de documentação que será processado pelas ferramentas do GTK-Doc. Bloco de comentário do GTK-Doc /** * identificador: @@ -448,9 +383,9 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - O "identificador" é uma linha com o nome do item ao qual o comentário está relacionado. A sintaxe difere um pouco dependendo do item. + O “identificador” é uma linha com o nome do item ao qual o comentário está relacionado. A sintaxe difere um pouco dependendo do item. - O bloco "documentação" também é diferente para cada tipo de símbolo. Tipos de símbolos que levam parâmetros, como funções e macros, têm a descrição de parâmetro começando com uma linha vazia (apenas com um "*"). Posteriormente, segue com a descrição detalhada. Todas as linhas (fora das listagens do programa e seções CDATA) contendo apenas um " *" (espaço em branco e asterisco) são convertidas para quebras de parágrafos. Se você não quiser uma quebra de parágrafo, altere isso para " * " (espaço, asterisco, espaço e espaço). Isso é útil em textos pré-formatados (listagens de código). + O bloco “documentação” também é diferente para cada tipo de símbolo. Tipos de símbolos que levam parâmetros, como funções e macros, têm a descrição de parâmetro começando com uma linha vazia (apenas com um “*”). Posteriormente, segue com a descrição detalhada. Todas as linhas (fora das listagens do programa e seções CDATA) contendo apenas um “ *” (espaço em branco e asterisco) são convertidas para quebras de parágrafos. Se você não quiser uma quebra de parágrafo, altere isso para “ * “ (espaço, asterisco, espaço e espaço). Isso é útil em textos pré-formatados (listagens de código). Ao documentar um código, descreva dois aspectos: @@ -488,24 +423,14 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - Se você precisar usar os caracteres especiais "<", ">", "()", "@", "%" ou "#" em sua documentação sem GTK-Doc alterando-os, você pode usar as entidades XML "&lt;", "&gt;", "&lpar;", "&rpar;", "&commat;", "&percnt;" e "&num;", respectivamente, ou escapá-los com uma contrabarra "\". + Se você precisar usar os caracteres especiais “<”, “>”, “()”, “@”, “%” ou “#” em sua documentação sem GTK-Doc alterando-os, você pode usar as entidades XML “&lt;”, “&gt;”, “&lpar;”, “&rpar;”, “&commat;”, “&percnt;” e “&num;”, respectivamente, ou escapá-los com uma contrabarra “\”. DocBook pode fazer mais do que apenas links. Ele também pode ter listas, exemplos, títulos e imagens. A partir da versão 1.20, a forma preferível é usar um subconjunto de sintaxe de formatação de texto básica chamada Markdown. Em versões mais antigas do GTK-Doc, qualquer documentação que inclui Markdown será renderizada como está. Por exemplo, itens de lista aparecerão como linhas começando com um traço. - - 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. - + Enquanto markdown é agora preferível, é possível misturar ambos. Uma limitação aqui é que é possível usar docbook xml no markdown, mas não há suporte a markdown no docbook xml. - - 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. - + Em versões mais antigas do GTK-Doc, se você precisasse de suporte para formatação adicional, você precisaria de habilitar o uso de tags de XML de docbook dentro de comentários de documentação colocando (ou ) na variável MKDB_OPTIONS dentro de Makefile.am. Bloco de comentário do GTK-Doc usando Markdown @@ -551,7 +476,7 @@ 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. + 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. @@ -624,7 +549,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html Privado - Uma interface que pode ser usada dentro da própria pilha do GNOME, mas que não está documentada para usuários finais. Tais funções deveriam ser usadas nas formas especificadas e documentadas. - Interna - Uma interface que é interna a um módulo e não requer documentação para o usuário final. Funções que não estão documentadas são presumidas como sendo "Interna". + Interna - Uma interface que é interna a um módulo e não requer documentação para o usuário final. Funções que não estão documentadas são presumidas como sendo “Interna”. @@ -671,43 +596,24 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html - - 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. - + Você também pode adicionar informação sobre estabilidade em todos os elementos de documentação para indicar se a estabilidade de uma API é garantida para eles para futuros lançamentos menores do projeto. - - The default stability level for all documentation elements can be set - by passing the argument to - gtkdoc-mkdb with one of the values below. - + O nível de estabilidade padrão para todos os elementos de documentação pode ser definido passando o argumento para gtkdoc-mkdb com um dos balores abaixo. - Stability Tags + Tags de estabilidade Stability: Stable - - Mark the element as stable. This is for public APIs which are - guaranteed to remain stable for all future minor releases of the - project. - + Marca o elemento como estável. Isto é para APIs públicas cuja estabilidade é garantida para todos os próximos lançamentos menores do projeto. Stability: Unstable - - Mark the element as unstable. This is for public APIs which are - released as a preview before being stabilised. - + Marca o elemento como instável. Isto é para APIs públicas que são publicados como versão de desenvolvimento antes de se tornar estável. Stability: Private - - Mark the element as private. This is for interfaces which can be - used by tightly coupled modules, but not by arbitrary third - parties. - + Marca o elemento como privado. Isto é para interfaces que podem ser usadas por um conjunto pequeno de módulos, mas não por terceiros. @@ -733,35 +639,29 @@ foo_get_bar(Foo *foo) - Annotations + Anotações - - 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. - + Blocos de documentação podem conter tags de anotação. Essas tags serão renderizadas com dicas de ferramentas descrevendo seu significados. As tags são usadas pelo gobject-introspection para garantir associações (bindings) de linguagens. Uma lista detalhada tags aceitas podem ser encontrada no wiki. - Annotations - Anotações + /** - * foo_get_bar: (annotation) - * @foo: (annotation): some foo + * foo_get_bar: (anotação) + * @foo: (anotação): algum foo * - * Retrieves @foo's bar. + * Obtém bar do @foo. * - * Returns: (annotation): @foo's bar + * Returns: (anotação): bar do @foo */ ... /** - * foo_set_bar_using_the_frobnicator: (annotation) (another annotation) - * (and another annotation) - * @foo: (annotation) (another annotation): some foo + * foo_set_bar_using_the_frobnicator: (anotação) (outra anotação) + * (e uma outra anotação) + * @foo: (anotação) (uma outra anotação): algum foo * - * Sets bar on @foo. + * Define bar no @foo. */ -]]> + @@ -779,7 +679,7 @@ foo_get_bar(Foo *foo) - Gtk-doc presume que todos os símbolos (macros, funções) começando com "_" são privadas. Elas são tratadas como funções estáticas. + Gtk-doc presume que todos os símbolos (macros, funções) começando com “_” são privadas. Elas são tratadas como funções estáticas. Bloco de comentário de função @@ -864,28 +764,24 @@ foo_sinais[FOOBARIZAR] = Bloco de comentário de struct Bloco de comentário de struct - /** * FooWidget: - * @bar: some #gboolean + * @bar: algum #gboolean * - * This is the best widget, ever. + * Este é o melhor widget, já mais visto. */ typedef struct _FooWidget { - GtkWidget parent_instance; + GtkWidget parent_intance; gboolean bar; } FooWidget; -]]> + Use /*< private >*/ antes dos campos da struct privada que você deseja esconder. Use /*< public >*/ para o comportamento inverso. - - 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. - + Se o primeiro campo for “g_iface”, “parent_instance” ou “parent_class”, ele será automaticamente considerado como privado e não precisará ser mencionado no bloco de comentário. Blocos de comentário de struct também podem ser usados para GObjects e GObjectClasses. É normalmente uma boa ideia adicionar um bloco de comentário para uma classe, se ela possui vmethods (pois assim é como elas podem ser documentadas). Para o próprio GOBject pode-se usar os documentos de seção relacionados, tendo um bloco separado para a instância do struct seria útil se a instância possui campos públicos. Uma desvantagem aqui é que isso cria duas entradas no índice do mesmo nome (a estrutura e a seção). @@ -915,6 +811,93 @@ typedef enum { + + + Documentação de programa em-linha + Você pode documentar programas e sua interface de linha de comando usando documentação em-linha. + + + Tags + + PROGRAM + + + Define o início da documentação de um programa. + + + + + @short_description: + + Define uma descrição breve do programa. (Opcional) + + + + + @synopsis: + + Define os argumentos, ou lista de argumentos, que o programa pode receber. (Opcional) + + + + + @see_also: + + A seção “Veja Também” (See Also) de páginas de manual. (Opcional) + + + + + @arg: + + Argumento(s) passado(s) para o programa e sua descrição. (Opcional) + + + + + Description: + + Um descrição mais longa do programa. + + + + + Returns: + + Especifique quais valor(es) o programa retorna. (Opcional) + + + + + + + Exemplo de documentação de programa. + Bloco de documentação de programa + +/** + * PROGRAM:programa-teste + * @short_description: Um programa teste + * @synopsis: programa-teste [*OPÇÕES*...] --arg1 *arg* *ARQUIVO* + * @see_also: teste(1) + * @--arg1 *arg*: define arg1 para *arg* + * @--arg2 *arg*: define arg2 para *arg* + * @-v, --version: Exibe o número da versão + * @-h, --help: Exibe a mensagem de ajuda + * + * Descrição longa do programa. + * + * Returns: Zero no caso de sucesso, não-zero no caso de falha + */ +int main(int argc, char *argv[]) +{ + return 0; +} + + + + + + Tags úteis do DocBook @@ -924,7 +907,7 @@ typedef enum { <link linkend="glib-Hash-Tables">Tabela de hashes</link> - O fim do link é o ID do SGML/XML no item superior da páginao a qual você deseja vincular. Para a maioria das páginas isto é atualmente a parte ("gtk", "gdk", "glib") e, então, o título da página ("Hash Tables"). Para os widgets isso é apenas o nome da classe. Espaços e sublinhados são convertidos em '-' para estar em conformidade com SGML/XML. + O fim do link é o ID do SGML/XML no item superior da página a qual você deseja vincular. Para a maioria das páginas isto é atualmente a parte (“gtk”, “gdk”, “glib”) e, então, o título da página (“Hash Tables”). Para os widgets isso é apenas o nome da classe. Espaços e sublinhados são convertidos em '-' para estar em conformidade com SGML/XML. Para se referir a uma função externa, como, por exemplo, uma função padrão do C: @@ -1046,7 +1029,7 @@ gtk_arrow_get_type - Desde o GTK-Doc 1.8, o gtkdoc-scan pode gerar esta lista para você. Basta adicionar "--rebuild-types" a SCAN_OPTIONS no Makefile.am. Se você usar esta abordagem, você não deveria distribuir o arquivo de tipos nem tê-lo sob um controle de versão. + Desde o GTK-Doc 1.8, o gtkdoc-scan pode gerar esta lista para você. Basta adicionar “--rebuild-types” a SCAN_OPTIONS no Makefile.am. Se você usar esta abordagem, você não deveria distribuir o arquivo de tipos nem tê-lo sob um controle de versão. @@ -1055,14 +1038,7 @@ gtk_arrow_get_type O Gtk-Doc produz documentação em DocBook SGML/XML. Ao processar os comentários inseridos nos fontes, as ferramentas do GTK-Doc geram uma página de documentação por classe ou módulo como um arquivo separado. O documento mestre os inclui e os coloca em uma ordem. - - 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. - + Enquanto o Gtk-Doc cria um modelo de documento mestre para você, execuções posteriores não vão tocá-lo novamente. Isso significa que se pode estruturar a documentação livremente. Isso inclui agrupamento de páginas e adição de páginas extras. O Gtk-Doc agora possui uma suíte de teste, na qual também o documento mestre é recriado do zero. É uma boa ideia verificar isso de tempo em tempo para ver se há itens a serem introduzidos lá. Não crie tutoriais como documentos extras. Apenas escreva capítulos extras. O benefício de embutir diretamente o tutorial para sua biblioteca na documentação da API é que é mais fácil vincular o tutorial a um símbolo da documentação. Além disso, as chances são mais altas que o tutorial obtenha atualizações junto com a biblioteca. @@ -1088,36 +1064,28 @@ gtk_arrow_get_type + Além disso, alguns elementos de opção são criados na forma comentada. Você pode revisá-los e habilitá-los como preferir. + - In addition a few option elements are created in commented form. You can - review these and enable them as you like. - - - - Optional part in the master document - - --> -]]> + Parte opcional do documento mestre + + <!-- habilite isso se você usa anotações do gobject introspection + <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> + --> + - - - 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. - + + Finalmente você precisa adicionar nova seção sempre que você a introduzir. A ferramenta gtkdoc-check vai lembrar você de arquivos xml recentemente gerados que ainda não foram incluídos na documentação. - Including generated sections - - my library - + Incluindo seções geradas + + <chapter> + <title>minha biblioteca</title> + <xi:include href="xml/object.xml"/> ... -]]> + @@ -1128,55 +1096,38 @@ gtk_arrow_get_type O arquivo de seção é usado para organizar a saída da documentação pelo GTK-Doc. Aqui pode-se especificar qual símbolo pertence a qual módulo ou classe e controla a visibilidade (pública ou privada). - - 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. - - + O arquivo de seção é uma arquivo texto simples com seções delimitadas por tags. Linhas em branco são ignoradas e linhas começando com um “#” são tratadas como linhas de comentários. + - - While the tags make the file look like xml, it is not. Please do not - close tags like <SUBSECTION>. - + Enquanto as tags fazem o arquivo se parecer xml, ele não é. Por favor, não feche tags como <SUBSECTION>. - Including generated sections - libmeep/meep.h + Incluindo seções geradas + +<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> + - - 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 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). - + A tag <FILE> ... </FILE> é usada para especificar o nome de arquivo, sem qualquer sufixo. Por exemplo, ao usar “<FILE>gnome-config</FILE>” resultará nas declarações da seção serem retornadas no arquivo modelo tmpl/gnome-config.sgml, o qual será convertido no arquivo DocBook XML xml/gnome-config.sgml ou no arquivo DocBook XML xml/gnome-config.xml. (O nome do arquivo HTML é baseado no nome do módulo e no título da seção ou, para GObjects, é baseado no nome da classe GObjects convertidos os caracteres para minúsculos). A tag <TITLE> ... </TITLE> é usada para especificar o título da seção. Ela é usada apenas antes do modelo (se usado) ser criado inicialmente, já que o título definido no arquivo de modelo sobrescreve este. Também, se for usado o comentário SECTION nos fontes, isso está obsoleto. - Você pode agrupar itens na seção usando a tag <SUBSECTION>. Atualmente, ela retorna uma linha em branco entre as subseções na seção de sinópse. Você também pode usar <SUBSECTION Standard> para declarações padrão do GObject (ex.: as funções como g_object_get_type e macros como G_OBJECT(), G_IS_OBJECT() etc.). Atualmente, estas são deixadas fora da documentação. Você também pode usar <SUBSECTION Private> para declarações privadas que não serão retornadas (é uma forma prática de evitar mensagens de aviso sobre declarações não usadas). Se sua biblioteca contém tipos privados que você não deseja que apareçam na hierarquia do objeto e a linha de classes implementadas ou exigidas, adicione-as a uma subseção privada. Se você colocaria o GObject e GObjectClass como structs numa seção padrão ou pública depende se há entradas públicas (variáveis, vmethods). + Você pode agrupar itens na seção usando a tag <SUBSECTION>. Atualmente, ela retorna uma linha em branco entre as subseções na seção de sinopse. Você também pode usar <SUBSECTION Standard> para declarações padrão do GObject (ex.: as funções como g_object_get_type e macros como G_OBJECT(), G_IS_OBJECT() etc.). Atualmente, estas são deixadas fora da documentação. Você também pode usar <SUBSECTION Private> para declarações privadas que não serão retornadas (é uma forma prática de evitar mensagens de aviso sobre declarações não usadas). Se sua biblioteca contém tipos privados que você não deseja que apareçam na hierarquia do objeto e a linha de classes implementadas ou exigidas, adicione-as a uma subseção privada. Se você colocaria o GObject e GObjectClass como structs numa seção padrão ou pública depende se há entradas públicas (variáveis, vmethods). - Você também pode usar <INCLUDE> ... </INCLUDE> para especificar os arquivos #include que são mostrados nas seções de sinópse. Ela contém uma lista separada por vírgula de arquivos #include, sem os sinais de maior que e menor que. Se você define-a fora de quaisquer seções, ela age para todas as seções até o fim do arquivo. Se você define-a em uma seção, ela só vai se aplicar àquela seção. + Você também pode usar <INCLUDE> ... </INCLUDE> para especificar os arquivos #include que são mostrados nas seções de sinopse. Ela contém uma lista separada por vírgula de arquivos #include, sem os sinais de maior que e menor que. Se você define-a fora de quaisquer seções, ela age para todas as seções até o fim do arquivo. Se você define-a em uma seção, ela só vai se aplicar àquela seção. @@ -1201,30 +1152,22 @@ meep_app_get_type Se o projeto é baseado em GObject, pode-se também procurar nos arquivos produzidos pela varredura de objetos: <pacote>.args.txt, <pacote>.hierarchy.txt, <pacote>.interfaces.txt, <pacote>.prerequisites.txt e <pacote>.signals.txt. Se há símbolos faltando em qualquer um deles, pode-se exigir que o GTK-Doc mantenha o arquivo intermediário de varredura para análise posterior, executando GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizando a documentação - + GTK-Doc está por aí já faz um tempo. Nesta seção, nós listamos novas funcionalidades juntamente da versão desde a qual está disponível. - + GTK-Doc 1.9 Ao usar xml em vez de sgml, na verdade, é possível nomear o documento mestre <pacote>-docs.xml. - + Essa versão provê suporte em Makefile.am. Quando esta opção está habilitada, o <package>-sections.txt é auto-gerado e pode ser removido a partir do VCS. Isso só funciona corretamente para projetos que têm uma estrutura muito regular (ex.: cada par .{c,h} vai criar uma nova seção). Se uma pessoa organiza um projeto próximo a isso atualizando um arquivo de seção mantido manualmente pode ser tão simples quanto executando meld <package>-decl-list.txt <package>-sections.txt. - - - 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 you source control system and haven't yet switched, just - add the flag to configure.ac and you are done. - + + A versão 1.8 já introduziu a sintaxe para documentação seções nos fontes em vez dos arquivos separados sob tmpl. Essa versão adiciona opções para alternar todo o módulo de documentação para não usar a etapa de compilação extra do tmpl, usando no configure.ac. Se você não possui um tmpl no seu sistema de controle de versão e ainda não trocou, basta adicionar uma opção ao configure.ac e está resolvido. - + GTK-Doc 1.10 @@ -1255,36 +1198,27 @@ endif 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 any example that shows how the entity file is included - and how the entities are used. The entities can also be used in all - generated files, GTK-Doc will use the same xml header in generated xml - files. - Use pre-generated entities - -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" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ - - + <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> + <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent"> %gtkdocentities; -]> - - - &package_name; Reference Manual - - for &package_string;. - The latest version of this documentation can be found on-line at - http://[SERVER]/&package_name;/. - - -]]> - - +]> +<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> + + @@ -1373,11 +1307,11 @@ EXTRA_DIST += meep.xml Droga. Eu ainda não tenho hierarquia de classes. - Por acaso o nome do objeto (nome da struct da instância, ex. GtkWidget) faz parte da seção normal (não coloque isso em subsções Standard ou Private)? + Por acaso o nome do objeto (nome da struct da instância, ex. GtkWidget) faz parte da seção normal (não coloque isso em subseções Standard ou Private)? Nenhum símbolo de índice. - O <pacote>-docs.{xml,sgml} contém um índice que "xi:inclui" o índice gerado? + O <pacote>-docs.{xml,sgml} contém um índice que “xi:inclui” o índice gerado? Símbolos não estão vinculados ao seus doc-section. @@ -1385,7 +1319,7 @@ EXTRA_DIST += meep.xml Uma nova classe não aparece nos documentos. - A nova página foi "xi:incluída" do <pacote>-docs.{xml,sgml}? + A nova página foi “xi:incluída” do <pacote>-docs.{xml,sgml}? Um novo símbolo não aparece nos documentos. @@ -1393,17 +1327,11 @@ EXTRA_DIST += meep.xml Um tipo está faltando da hierarquia de classe. - - 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 - incidentally marked private it will not be shown. - + Se o tipo está listado no <pacote>.hierarchy, mas não em xml/tree_index.sgml, então certifique-se de que o tipo está colocado corretamente no <pacote>-sections.txt. Se a instância do tipo (ex.: GtkWidget) não está listada ou incidentalmente marcada como privada, ela não será mostrada. Obtenho links de seguimento de documentos para todas as anotações gobject. - Verifique se xml/annotation-glossary.xml está "xi:incluído" de <pacote>-docs.{xml,sgml}. + Verifique se xml/annotation-glossary.xml está “xi:incluído” de <pacote>-docs.{xml,sgml}. @@ -1414,7 +1342,7 @@ EXTRA_DIST += meep.xml - Múltiplos "IDs" para restrições do fim do link XYZ + múltiplos “IDs” para restrições do fim do link XYZ O símbolo XYZ aparece duas vezes no arquivo <pacote>-sections.txt. @@ -1507,7 +1435,7 @@ EXTRA_DIST += meep.xml A - Usar na Página de Título (e nas capas, se existirem) um título distinto em relação ao do Documento, e daqueles de versões anteriores (os quais devem, na existência de algum, ser listados na seção "Histórico" do Documento). Você pode usar o mesmo título de uma versão anterior se o editor original daquela versão conceder-lhe permissão. + Usar na Página de Título (e nas capas, se existirem) um título distinto em relação ao do Documento, e daqueles de versões anteriores (os quais devem, na existência de algum, ser listados na seção “Histórico” do Documento). Você pode usar o mesmo título de uma versão anterior se o editor original daquela versão conceder-lhe permissão. @@ -1625,13 +1553,7 @@ EXTRA_DIST += meep.xml 6. COLEÇÕES DE DOCUMENTOS Você pode fazer uma coleção que consiste do Documento e outros documentos publicados sob esta Licença, e substituir as cópias individuais desta Licença, nos vários documentos, por uma única cópia a ser incluída na coleção, desde que você siga as regras desta Licença para cópias literais de cada documento em todos os outros aspectos. - - 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. - + Você pode extrair um único documento desta coleção, e distribuí-lo individualmente sob esta Licença, desde que você insira uma cópia desta Licença no documento extraído, e siga esta Licença em todos os outros aspectos com relação à cópia literal do documento. diff --git a/help/manual/pt_BR/pt_BR.po b/help/manual/pt_BR/pt_BR.po index 409136e..d46edab 100644 --- a/help/manual/pt_BR/pt_BR.po +++ b/help/manual/pt_BR/pt_BR.po @@ -1,15 +1,15 @@ # Brazilian Portuguese translation for gtk-doc help. -# Copyright (C) 2016 gtk-doc's COPYRIGHT HOLDER +# Copyright (C) 2017 gtk-doc's COPYRIGHT HOLDER # This file is distributed under the same license as the gtk-doc package. # Marcelo Rodrigues , 2010. -# Rafael Fontenelle , 2013, 2014, 2016. +# Rafael Fontenelle , 2013, 2014, 2016, 2017. msgid "" msgstr "" "Project-Id-Version: gtk-doc help\n" "Report-Msgid-Bugs-To: http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-" "doc&keywords=I18N+L10N&component=general\n" -"POT-Creation-Date: 2016-01-21 21:44+0000\n" -"PO-Revision-Date: 2016-03-21 10:13-0200\n" +"POT-Creation-Date: 2017-04-23 16:21+0000\n" +"PO-Revision-Date: 2017-04-25 08:24-0200\n" "Last-Translator: Rafael Fontenelle \n" "Language-Team: Brazilian Portuguese \n" "Language: pt_BR\n" @@ -17,7 +17,7 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=(n > 1);\n" -"X-Generator: Virtaal 0.7.1\n" +"X-Generator: Virtaal 1.0.0-beta1\n" "X-Project-Style: gnome\n" #. Put one translator per line, in the form NAME , YEAR1, YEAR2 @@ -25,7 +25,7 @@ msgctxt "_" msgid "translator-credits" msgstr "" "Marcelo Rodrigues , 2010\n" -"Rafael Fontenelle , 2013, 2014, 2016" +"Rafael Fontenelle , 2013, 2014, 2016, 2017" #. (itstool) path: bookinfo/title #: C/index.docbook:12 @@ -89,7 +89,6 @@ msgstr "2000, 2005 Dan Mueth e Chris Lyttle" #. (itstool) path: bookinfo/copyright #: C/index.docbook:52 -#| msgid "2007-2014 Stefan Sauer (Kost)" msgid "2007-2015 Stefan Sauer (Kost)" msgstr "2007-2015 Stefan Sauer (Kost)" @@ -126,59 +125,53 @@ msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:83 -#| msgid "" -#| "1.21.1 18 Jul 2014 " -#| "ss development version" msgid "" -"1.24.1 30 May 2015 ss1.25.1 21 March 2016 ss development version" msgstr "" -"1.24.1 30 Maio 2015 " -"ss versão de " -"desenvolvimento" +"1.25.1 21 Março 2016 ss versão de desenvolvimento" #. (itstool) path: revhistory/revision #: C/index.docbook:89 -#| msgid "" -#| "1.19 05 Jun 2013 ss bug fixes" +msgid "" +"1.25 21 March 2016 ss bug fixes, test cleanups" +msgstr "" +"1.25 21 Março 2016 ss correção de erros, limpezas de testes" + +#. (itstool) path: revhistory/revision +#: C/index.docbook:95 msgid "" "1.24 29 May 2015 ss bug fix" msgstr "" -"1.24 29 Maio 2015 " -"ss correção de erros" +"1.24 29 Maio 2015 ss correção de erros" #. (itstool) path: revhistory/revision -#: C/index.docbook:95 -#| msgid "" -#| "1.19 05 Jun 2013 ss bug fixes" +#: C/index.docbook:101 msgid "" "1.23 17 May 2015 ss bug fix" msgstr "" -"1.23 17 Maio 2015 " -"ss correção de erros" +"1.23 17 Maio 2015 ss correção de erros" #. (itstool) path: revhistory/revision -#: C/index.docbook:101 -#| msgid "" -#| "1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" +#: C/index.docbook:107 msgid "" "1.22 07 May 2015 ss bug fixes, dropping deprecated features" msgstr "" -"1.22 07 Maio 2015 " -"ss correção de erros, " -"desativadas funcionalidades obsoletas" +"1.22 07 Maio 2015 ss correção de erros, desativadas funcionalidades " +"obsoletas" #. (itstool) path: revhistory/revision -#: C/index.docbook:107 +#: C/index.docbook:113 msgid "" "1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" #. (itstool) path: revhistory/revision -#: C/index.docbook:113 +#: C/index.docbook:119 msgid "" "1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" #. (itstool) path: revhistory/revision -#: C/index.docbook:119 +#: C/index.docbook:125 msgid "" "1.19 05 Jun 2013 ss bug fixes" @@ -209,7 +202,7 @@ msgstr "" "authorinitials> correção de erros" #. (itstool) path: revhistory/revision -#: C/index.docbook:125 +#: C/index.docbook:131 msgid "" "1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" @@ -219,7 +212,7 @@ msgstr "" "markdown" #. (itstool) path: revhistory/revision -#: C/index.docbook:131 +#: C/index.docbook:137 msgid "" "1.17 26 Feb 2011 sk urgent bug fix update" @@ -229,7 +222,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:137 +#: C/index.docbook:143 msgid "" "1.16 14 Jan 2011 sk bugfixes, layout improvements" @@ -238,7 +231,7 @@ msgstr "" "authorinitials> correção de erros, melhorias no layout" #. (itstool) path: revhistory/revision -#: C/index.docbook:143 +#: C/index.docbook:149 msgid "" "1.15 21 May 2010 sk bug and regression fixes" @@ -247,7 +240,7 @@ msgstr "" "authorinitials> correção de erros e regressões" #. (itstool) path: revhistory/revision -#: C/index.docbook:149 +#: C/index.docbook:155 msgid "" "1.14 28 March 2010 sk bugfixes and performance improvements" @@ -257,7 +250,7 @@ msgstr "" "revremark>" #. (itstool) path: revhistory/revision -#: C/index.docbook:155 +#: C/index.docbook:161 msgid "" "1.13 18 December 2009 " "sk broken tarball update atualização de tarball defeituoso" #. (itstool) path: revhistory/revision -#: C/index.docbook:161 +#: C/index.docbook:167 msgid "" "1.12 18 December 2009 " "sk new tool features and " @@ -278,7 +271,7 @@ msgstr "" "erros" #. (itstool) path: revhistory/revision -#: C/index.docbook:167 +#: C/index.docbook:173 msgid "" "1.11 16 November 2008 " "mal GNOME doc-utils migration Migração do GNOME doc-utils" #. (itstool) path: chapter/title -#: C/index.docbook:180 +#: C/index.docbook:186 msgid "Introduction" msgstr "Introdução" #. (itstool) path: chapter/para -#: C/index.docbook:182 +#: C/index.docbook:188 msgid "" "This chapter introduces GTK-Doc and gives an overview of what it is and how " "it is used." @@ -302,12 +295,12 @@ msgstr "" "usado." #. (itstool) path: sect1/title -#: C/index.docbook:188 +#: C/index.docbook:194 msgid "What is GTK-Doc?" msgstr "O que é GTK-Doc?" #. (itstool) path: sect1/para -#: C/index.docbook:190 +#: C/index.docbook:196 msgid "" "GTK-Doc is used to document C code. It is typically used to document the " "public API of libraries, such as the GTK+ and GNOME libraries. But it can " @@ -318,12 +311,12 @@ msgstr "" "GNOME. Mas ele também pode ser usado para documentar código de aplicativos." #. (itstool) path: sect1/title -#: C/index.docbook:198 +#: C/index.docbook:204 msgid "How Does GTK-Doc Work?" msgstr "Como o GTK-Doc funciona?" #. (itstool) path: sect1/para -#: C/index.docbook:200 +#: C/index.docbook:206 msgid "" "GTK-Doc works by using documentation of functions placed inside the source " "files in specially-formatted comment blocks, or documentation added to the " @@ -338,7 +331,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:207 +#: C/index.docbook:213 msgid "" "GTK-Doc consists of a number of perl scripts, each performing a different " "step in the process." @@ -347,12 +340,12 @@ msgstr "" "diferente no processo." #. (itstool) path: sect1/para -#: C/index.docbook:212 +#: C/index.docbook:218 msgid "There are 5 main steps in the process:" msgstr "Há 5 etapas principais no processo:" #. (itstool) path: listitem/para -#: C/index.docbook:219 +#: C/index.docbook:225 msgid "" "Writing the documentation. The author fills in the " "source files with the documentation for each function, macro, union etc. (In " @@ -365,7 +358,7 @@ msgstr "" "que não é mais recomendado)." #. (itstool) path: listitem/para -#: C/index.docbook:229 +#: C/index.docbook:235 msgid "" "Gathering information about the code. " "gtkdoc-scan scans the header files of the code " @@ -400,7 +393,7 @@ msgstr "" "txt no <módulo>-overrides.txt." #. (itstool) path: listitem/para -#: C/index.docbook:246 +#: C/index.docbook:252 msgid "" "gtkdoc-scangobj can also be used to dynamically " "query a library about any GObject subclasses it exports. It saves " @@ -414,7 +407,7 @@ msgstr "" "fornece." #. (itstool) path: listitem/para -#: C/index.docbook:252 +#: C/index.docbook:258 msgid "" "gtkdoc-scanobj should not be used anymore. It was " "needed in the past when GObject was still GtkObject inside gtk+." @@ -423,47 +416,7 @@ msgstr "" "era necessário no passado, quando GObject ainda era GtkObject dentro do gtk+." #. (itstool) path: listitem/para -#: C/index.docbook:259 -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 "" -"Gerando os arquivos \"template\". gtkdoc-" -"mktmpl cria uma quantidade de arquivos no subdiretório " -"tmpl/, usando a informação coletada " -"na primeira etapa. (Note que ele pode ser executado repetidas vezes e vai " -"tentar garantir que nenhuma documentação será perdida, jamais.)" - -#. (itstool) path: note/para -#: C/index.docbook:268 -msgid "" -"Since GTK-Doc 1.9 the templates can be avoided. We encourage people to keep " -"documentation in the code. 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 "" -"Desde o GTK-Doc 1.9, os modelos (\"templates\") podem ser evitados. Nós " -"encorajamos as pessoas a manter a documentação no código. " -"gtkdocize possui suporte a uma opção que escolhe um makefile que ignora totalmente o uso " -"de tmpl. Se você nunca alterou o arquivo em tmpl manualmente, por favor " -"remova o diretório (ex.: do sistema de controle de versão)." - -#. (itstool) path: listitem/para -#: C/index.docbook:280 -#| msgid "" -#| "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." +#: C/index.docbook:265 msgid "" "Generating the XML and HTML/PDF. gtkdoc-" "mkdb turns the template files into XML files in the Gerando o XML e HTML/PDF. gtkdoc-" -"mkdb transforma os arquivos modelos em arquivos XML no " -"subdiretório xml/. Se o código fonte " -"contém documentação nas funções, usando os blocos de comentários especiais, " -"ela é mesclada aqui. Se não há arquivos tmpl sendo usados, ele apenas lê " +"Gerando o XML e HTML/PDF. gtkdoc-mkdb transforma os arquivos modelos em arquivos XML no subdiretório " +"xml/. Se o código fonte contém " +"documentação nas funções, usando os blocos de comentários especiais, ela é " +"mesclada aqui. Se não há arquivos tmpl sendo usados, ele apenas lê " "documentos dos dados de introspecção e dos fontes." #. (itstool) path: listitem/para -#: C/index.docbook:289 -#| msgid "" -#| "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." +#: C/index.docbook:274 msgid "" "gtkdoc-mkhtml turns the XML files into HTML files " "in the html/ subdirectory. Likewise " @@ -494,18 +441,13 @@ msgid "" "document called <package>.pdf." msgstr "" "gtkdoc-mkhtml transforma os arquivos XML em " -"arquivos HTML no subdiretório html/. " -"Da mesma forma, gtkdoc-mkpdf transforma os " -"arquivos XML em um documento PDF chamado " -"<pacote>.pdf." +"arquivos HTML no subdiretório html/. Da mesma forma, gtkdoc-mkpdf " +"transforma os arquivos XML em um documento PDF chamado <" +"pacote>.pdf." #. (itstool) path: listitem/para -#: C/index.docbook:295 -#| msgid "" -#| "Files in sgml/ or xml/ and html/ directories are always overwritten. One should never " -#| "edit them directly." +#: C/index.docbook:280 msgid "" "Files in xml/ and html/ directories are always overwritten. One " @@ -516,7 +458,7 @@ msgstr "" "devem ser editados manualmente." #. (itstool) path: listitem/para -#: C/index.docbook:303 +#: C/index.docbook:288 msgid "" "Fixing up cross-references between documents. After " "installing the HTML files, gtkdoc-fixxref can be " @@ -538,22 +480,22 @@ msgstr "" "volta para links locais (onde aquelas documentações estão instaladas)." #. (itstool) path: sect1/title -#: C/index.docbook:321 +#: C/index.docbook:306 msgid "Getting GTK-Doc" msgstr "Obtendo GTK-Doc" #. (itstool) path: sect2/title -#: C/index.docbook:324 +#: C/index.docbook:309 msgid "Requirements" msgstr "Requisitos" #. (itstool) path: sect2/para -#: C/index.docbook:325 +#: C/index.docbook:310 msgid "Perl v5 - the main scripts are in Perl." msgstr "Perl v5 - os scripts principais são Perl." #. (itstool) path: sect2/para -#: C/index.docbook:328 +#: C/index.docbook:313 msgid "" "xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" @@ -562,7 +504,7 @@ msgstr "" "\"http://xmlsoft.org/XSLT/\" type=\"http\">xmlsoft.org/XSLT/" #. (itstool) path: sect2/para -#: C/index.docbook:332 +#: C/index.docbook:317 msgid "" "docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" #. (itstool) path: sect2/para -#: C/index.docbook:336 +#: C/index.docbook:321 msgid "Python - optional - for gtkdoc-depscan" msgstr "Python - opcional - para gtkdoc-depscan" #. (itstool) path: sect2/para -#: C/index.docbook:339 +#: C/index.docbook:324 msgid "" "One of source-highlight, highlight " "or vim - optional - used for syntax highlighting of " @@ -589,17 +531,17 @@ msgstr "" "sintaxe de exemplos" #. (itstool) path: sect1/title -#: C/index.docbook:347 +#: C/index.docbook:332 msgid "About GTK-Doc" msgstr "Sobre GTK-Doc" #. (itstool) path: sect1/para -#: C/index.docbook:349 C/index.docbook:363 +#: C/index.docbook:334 C/index.docbook:348 msgid "(FIXME)" msgstr "(CORRIJA-ME)" #. (itstool) path: sect1/para -#: C/index.docbook:353 +#: C/index.docbook:338 msgid "" "(History, authors, web pages, mailing list, license, future plans, " "comparison with other similar systems.)" @@ -608,22 +550,22 @@ msgstr "" "futuros, comparação com outros sistemas similares.)" #. (itstool) path: sect1/title -#: C/index.docbook:361 +#: C/index.docbook:346 msgid "About this Manual" msgstr "Sobre este manual" #. (itstool) path: sect1/para -#: C/index.docbook:367 +#: C/index.docbook:352 msgid "(who it is meant for, where you can get it, license)" msgstr "(pra quem ele serve, onde você pode obtê-lo, licença)" #. (itstool) path: chapter/title -#: C/index.docbook:376 +#: C/index.docbook:361 msgid "Setting up your project" msgstr "Preparando seu projeto" #. (itstool) path: chapter/para -#: C/index.docbook:378 +#: C/index.docbook:363 msgid "" "The next sections describe what steps to perform to integrate GTK-Doc into " "your project. Theses sections assume we work on a project called 'meep'. " @@ -635,20 +577,20 @@ msgid "" msgstr "" "As próximas seções descrevem quais as etapas para realizar a integração do " "GTK-Doc em seu projeto. Estas seções consideram que nós trabalhamos em um " -"projeto chamado \"meep\". Este projeto contém uma biblioteca chamada " -"\"libmeep\" e um aplicativo para usuário final chamado \"meeper\". Nós " -"também consideramos que você estará usando autoconf e automake. Além disso, " -"a seção sobre makefiles simples ou outros " -"sistemas de compilação vai descrever as necessidades básicas para " -"trabalhar em uma configuração de compilação diferente." +"projeto chamado “meep”. Este projeto contém uma biblioteca chamada “libmeep” " +"e um aplicativo para usuário final chamado “meeper”. Nós também consideramos " +"que você estará usando autoconf e automake. Além disso, a seção sobre makefiles simples ou outros sistemas de " +"compilação vai descrever as necessidades básicas para trabalhar em " +"uma configuração de compilação diferente." #. (itstool) path: sect1/title -#: C/index.docbook:389 +#: C/index.docbook:374 msgid "Setting up a skeleton documentation" msgstr "Preparando o esqueleto de uma documentação" #. (itstool) path: sect1/para -#: C/index.docbook:391 +#: C/index.docbook:376 msgid "" "Under your top-level project directory create folders called docs/reference " "(this way you can also have docs/help for end-user documentation). It is " @@ -662,12 +604,12 @@ msgstr "" "obrigatória." #. (itstool) path: example/title -#: C/index.docbook:400 +#: C/index.docbook:385 msgid "Example directory structure" msgstr "Exemplo de estrutura de diretórios" #. (itstool) path: example/programlisting -#: C/index.docbook:401 +#: C/index.docbook:386 #, no-wrap msgid "" "\n" @@ -691,18 +633,18 @@ msgstr "" " meeper/\n" #. (itstool) path: sect1/para -#: C/index.docbook:398 +#: C/index.docbook:383 msgid "This can then look as shown below: <_:example-1/>" msgstr "Isto pode, então, parecer como exibido abaixo: <_:example-1/>" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:416 C/index.docbook:423 +#: C/index.docbook:401 C/index.docbook:408 msgid "Integration with autoconf" msgstr "Integração com autoconf" #. (itstool) path: sect1/para -#: C/index.docbook:418 +#: C/index.docbook:403 msgid "" "Very easy! Just add one line to your configure.ac " "script." @@ -711,7 +653,7 @@ msgstr "" "filename>." #. (itstool) path: example/programlisting -#: C/index.docbook:424 +#: C/index.docbook:409 #, no-wrap msgid "" "\n" @@ -723,12 +665,12 @@ msgstr "" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" #. (itstool) path: example/title -#: C/index.docbook:436 +#: C/index.docbook:421 msgid "Keep gtk-doc optional" msgstr "Mantenha o gtk-doc como opcional" #. (itstool) path: example/programlisting -#: C/index.docbook:437 +#: C/index.docbook:422 #, no-wrap msgid "" "\n" @@ -748,7 +690,7 @@ msgstr "" "])\n" #. (itstool) path: sect1/para -#: C/index.docbook:431 +#: C/index.docbook:416 msgid "" "This will require all developers to have gtk-doc installed. If it is okay " "for your project to have optional api-doc build setup, you can solve this as " @@ -762,7 +704,7 @@ msgstr "" "GTK_DOC_CHECK no começo de uma linha. <_:example-1/>" #. (itstool) path: sect1/para -#: C/index.docbook:448 +#: C/index.docbook:433 msgid "" "The first argument is used to check for the gtkdocversion at configure time. " "The 2nd, optional argument is used by gtkdocize. " @@ -775,30 +717,30 @@ msgstr "" "também adiciona várias opções de configuração:" #. (itstool) path: listitem/para -#: C/index.docbook:454 +#: C/index.docbook:439 msgid "--with-html-dir=PATH : path to installed docs" msgstr "--with-html-dir=CAMINHO : caminho para as documentações instaladas" #. (itstool) path: listitem/para -#: C/index.docbook:455 +#: C/index.docbook:440 msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "--enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=no]" #. (itstool) path: listitem/para -#: C/index.docbook:456 +#: C/index.docbook:441 msgid "" "--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" "--enable-gtk-doc-html : compila documentação em formato html [padrão=sim]" #. (itstool) path: listitem/para -#: C/index.docbook:457 +#: C/index.docbook:442 msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" msgstr "" "--enable-gtk-doc-pdf : compila documentação em formato pdf [padrão=não]" #. (itstool) path: important/para -#: C/index.docbook:461 +#: C/index.docbook:446 msgid "" "GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " @@ -811,9 +753,14 @@ msgstr "" "que faz sentido para usuários, mas não para desenvolvedores)." #. (itstool) path: sect1/para -#: C/index.docbook:469 +#: C/index.docbook:454 +#| msgid "" +#| "Furthermore it is recommended that you have the following line inside you " +#| "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." @@ -824,12 +771,12 @@ msgstr "" "macro para GTK_DOC_CHECK para o seu projeto." #. (itstool) path: example/title -#: C/index.docbook:477 +#: C/index.docbook:462 msgid "Preparation for gtkdocize" msgstr "Preparação para gtkdocize" #. (itstool) path: example/programlisting -#: C/index.docbook:478 +#: C/index.docbook:463 #, no-wrap msgid "" "\n" @@ -839,7 +786,7 @@ msgstr "" "AC_CONFIG_MACRO_DIR(m4)\n" #. (itstool) path: sect1/para -#: C/index.docbook:483 +#: C/index.docbook:468 msgid "" "After all changes to configure.ac are made, update the " "configure file. This can be done by re-running " @@ -850,12 +797,12 @@ msgstr "" "executando novamente autoreconf -i ou autogen.sh." #. (itstool) path: sect1/title -#: C/index.docbook:491 +#: C/index.docbook:476 msgid "Integration with automake" msgstr "Integração com automake" #. (itstool) path: sect1/para -#: C/index.docbook:493 +#: C/index.docbook:478 msgid "" "First copy the Makefile.am from the examples sub directory of the Makefile.am. All the settings have a comment above that describes their " @@ -893,12 +840,12 @@ msgstr "" "suporte a pra listar os parâmetros disponíveis." #. (itstool) path: sect1/title -#: C/index.docbook:518 +#: C/index.docbook:503 msgid "Integration with autogen" msgstr "Integração com autogen" #. (itstool) path: sect1/para -#: C/index.docbook:520 +#: C/index.docbook:505 msgid "" "Most projects will have an autogen.sh script to setup " "the build infrastructure after a checkout from version control system (such " @@ -913,12 +860,12 @@ msgstr "" "O gtkdocize deveria ser executado antes de autoheader, automake ou autoconf." #. (itstool) path: example/title -#: C/index.docbook:529 +#: C/index.docbook:514 msgid "Running gtkdocize from autogen.sh" msgstr "Executando gtkdocize no autogen.sh" #. (itstool) path: example/programlisting -#: C/index.docbook:530 +#: C/index.docbook:515 #, no-wrap msgid "" "\n" @@ -928,7 +875,7 @@ msgstr "" "gtkdocize || exit 1\n" #. (itstool) path: sect1/para -#: C/index.docbook:536 +#: C/index.docbook:521 msgid "" "When running gtkdocize it copies gtk-" "doc.make to your project root (or any directory specified by the " @@ -944,7 +891,7 @@ msgstr "" "gtkdocize." #. (itstool) path: sect1/para -#: C/index.docbook:545 +#: C/index.docbook:530 msgid "" "Historically GTK-Doc was generating template files where developers entered " "the docs. This turned out to be not so good (e.g. the need for having " @@ -977,12 +924,12 @@ msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: C/index.docbook:562 C/index.docbook:579 +#: C/index.docbook:547 C/index.docbook:564 msgid "Running the doc build" msgstr "Executando a compilação da documentação" #. (itstool) path: sect1/para -#: C/index.docbook:564 +#: C/index.docbook:549 msgid "" "After the previous steps it's time to run the build. First we need to rerun " "autogen.sh. If this script runs configure for you, then " @@ -996,7 +943,7 @@ msgstr "" "configure com esta opção em seguida." #. (itstool) path: sect1/para -#: C/index.docbook:571 +#: C/index.docbook:556 msgid "" "The first make run generates several additional files in the doc-" "directories. The important ones are: <package>.types<pacote>-sections.txt." #. (itstool) path: example/programlisting -#: C/index.docbook:580 +#: C/index.docbook:565 #, no-wrap msgid "" "\n" @@ -1021,7 +968,7 @@ msgstr "" "make\n" #. (itstool) path: sect1/para -#: C/index.docbook:586 +#: C/index.docbook:571 msgid "" "Now you can point your browser to docs/reference/<package>/" "index.html. Yes, it's a bit disappointing still. But hang-on, " @@ -1033,18 +980,12 @@ msgstr "" "páginas com vida." #. (itstool) path: sect1/title -#: C/index.docbook:594 +#: C/index.docbook:579 msgid "Integration with version control systems" msgstr "Integração com sistemas de controle de versão" #. (itstool) path: sect1/para -#: C/index.docbook:596 -#| msgid "" -#| "As a rule of the thumb, it's those files you edit, that should go under " -#| "version control. For typical projects it's these files: <" -#| "package>.types, <package>-docs.xml (in the past .sgml), <package>-sections.txt, Makefile.am" +#: C/index.docbook:581 msgid "" "As a rule of thumb, it's the files you edit which should go under version " "control. For typical projects it's these files: <package>." @@ -1054,29 +995,28 @@ msgid "" msgstr "" "Como uma regra de ouro, são aqueles arquivos que você edita que deveriam " "entrar no controle de versão. Para projetos normais, esses são os arquivos: " -"<pacote>.types, " -"<pacote>-docs.xml (no passado, .sgml), " -"<pacote>-sections.txt, " -"Makefile.am" +"<pacote>.types, <pacote>-docs." +"xml (no passado, .sgml), <pacote>-sections.txt, Makefile.am." #. (itstool) path: sect1/para -#: C/index.docbook:604 +#: C/index.docbook:589 msgid "" "Files in the xml/ and html/ " "directories should not go under version control. Neither should any of the " ".stamp files." msgstr "" -"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." +"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." #. (itstool) path: sect1/title -#: C/index.docbook:612 +#: C/index.docbook:597 msgid "Integration with plain makefiles or other build systems" msgstr "Integração com makefiles simples ou outros sistemas de compilação" #. (itstool) path: sect1/para -#: C/index.docbook:614 +#: C/index.docbook:599 msgid "" "In the case one does not want to use automake and therefore gtk-" "doc.mak one will need to call the gtkdoc tools in the right order " @@ -1087,24 +1027,13 @@ msgstr "" "correta nos makefiles devidos (ou outras ferramentas de compilação)." #. (itstool) path: example/title -#: C/index.docbook:621 +#: C/index.docbook:606 msgid "Documentation build steps" msgstr "Etapas de compilação da documentação" #. (itstool) path: example/programlisting -#: C/index.docbook:622 +#: C/index.docbook:607 #, no-wrap -#| msgid "" -#| "\n" -#| "DOC_MODULE=meep\n" -#| "// sources have changed\n" -#| "gtkdoc-scan --module=$(DOC_MODULE) --source-dir=...\n" -#| "gtkdoc-scangobj --module=$(DOC_MODULE)\n" -#| "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml\n" -#| "// xml files have changed\n" -#| "mkdir html\n" -#| "cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n" -#| "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" msgid "" "\n" "DOC_MODULE=meep\n" @@ -1122,15 +1051,14 @@ msgstr "" "// fontes foram alterados\n" "gtkdoc-scan --module=$(DOC_MODULE) <source-dir=>\n" "gtkdoc-scangobj --module=$(DOC_MODULE)\n" -"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<" -";source-dir>\n" +"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>\n" "// arquivos xml foram alterados \n" "mkdir html\n" "cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n" "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" #. (itstool) path: sect1/para -#: C/index.docbook:636 +#: C/index.docbook:621 msgid "" "One will need to look at the Makefile.am and " "gtk-doc.mak to pick the extra options needed." @@ -1139,13 +1067,12 @@ msgstr "" "doc.mak para obter as opções extras necessárias." #. (itstool) path: sect1/title -#: C/index.docbook:643 -#| msgid "Integration with plain makefiles or other build systems" +#: C/index.docbook:628 msgid "Integration with CMake build systems" msgstr "Integração com sistemas de compilação CMake" #. (itstool) path: sect1/para -#: C/index.docbook:645 +#: C/index.docbook:630 msgid "" "GTK-Doc now provides a GtkDocConfig.cmake module (and " "the corresponding GtkDocConfigVersion.cmake module). " @@ -1158,12 +1085,12 @@ msgstr "" "em seu arquivo CMakeLists.txt." #. (itstool) path: example/title -#: C/index.docbook:655 +#: C/index.docbook:640 msgid "Example of using GTK-Doc from CMake" msgstr "Exemplo de uso do GTK-Doc no CMake" #. (itstool) path: example/programlisting -#: C/index.docbook:656 +#: C/index.docbook:641 #, no-wrap msgid "" "\n" @@ -1200,24 +1127,23 @@ msgstr "" "# documentos.\n" "add_custom_target(documentation ALL DEPENDS doc-libmeep)\n" "\n" -"# Install the docs. (This assumes you're using the GNUInstallDirs CMake " -"module\n" +"# Install the docs. (This assumes you're using the GNUInstallDirs CMake module\n" "# to set the CMAKE_INSTALL_DOCDIR variable correctly).\n" "install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html\n" " DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" #. (itstool) path: sect1/para -#: C/index.docbook:653 +#: C/index.docbook:638 msgid "The following example shows how to use this command. <_:example-1/>" msgstr "O exemplo a seguir mostra como usar este comando. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:681 +#: C/index.docbook:666 msgid "Documenting the code" msgstr "Documentando o código" #. (itstool) path: chapter/para -#: C/index.docbook:683 +#: C/index.docbook:668 msgid "" "GTK-Doc uses source code comment with a special syntax for code " "documentation. Further it retrieves information about your project structure " @@ -1230,12 +1156,12 @@ msgstr "" "descobrir todas as informações sobre a sintaxe dos comentários." #. (itstool) path: note/title -#: C/index.docbook:691 +#: C/index.docbook:676 msgid "Documentation placement" msgstr "Localização da documentação" #. (itstool) path: note/para -#: C/index.docbook:692 +#: C/index.docbook:677 msgid "" "In the past most documentation had to be filled into files residing inside " "the tmpl directory. This has the disadvantages that the " @@ -1249,7 +1175,7 @@ msgstr "" "versão." #. (itstool) path: note/para -#: C/index.docbook:698 +#: C/index.docbook:683 msgid "" "The avoid the aforementioned problems we suggest putting the documentation " "inside the sources. This manual will only describe this way of documenting " @@ -1260,12 +1186,12 @@ msgstr "" "descrever esta forma de documentar código." #. (itstool) path: example/title -#: C/index.docbook:709 C/index.docbook:735 +#: C/index.docbook:694 C/index.docbook:720 msgid "GTK-Doc comment block" msgstr "Bloco de comentário do GTK-Doc" #. (itstool) path: example/programlisting -#: C/index.docbook:710 +#: C/index.docbook:695 #, no-wrap msgid "" "\n" @@ -1279,7 +1205,7 @@ msgstr "" "#endif\n" #. (itstool) path: chapter/para -#: C/index.docbook:705 +#: C/index.docbook:690 msgid "" "The scanner can handle the majority of C headers fine. In the case of " "receiving warnings from the scanner that look like a special case, one can " @@ -1290,28 +1216,27 @@ msgstr "" "pode-se informar ao GTK-Doc para ignorá-los. <_:example-1/>" #. (itstool) path: note/title -#: C/index.docbook:719 -#| msgid "Dedications" +#: C/index.docbook:704 msgid "Limitations" msgstr "Limitações" #. (itstool) path: note/para -#: C/index.docbook:720 +#: C/index.docbook:705 msgid "" "Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but " "not #if !defined(__GTK_DOC_IGNORE__) or other combinations." msgstr "" -"Note que o GTK-Doc oferece suporte a " -"#ifndef(__GTK_DOC_IGNORE__), mas não a #if " -"!defined(__GTK_DOC_IGNORE__) ou outras combinações." +"Note que o GTK-Doc oferece suporte a #ifndef(__GTK_DOC_IGNORE__), mas não a #if !defined(__GTK_DOC_IGNORE__) ou outras " +"combinações." #. (itstool) path: sect1/title -#: C/index.docbook:730 +#: C/index.docbook:715 msgid "Documentation comments" msgstr "Comentários de documentação" #. (itstool) path: example/programlisting -#: C/index.docbook:736 +#: C/index.docbook:721 #, no-wrap msgid "" "\n" @@ -1327,27 +1252,27 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:732 +#: C/index.docbook:717 msgid "" "A multiline comment that starts with an additional '*' marks a documentation " "block that will be processed by the GTK-Doc tools. <_:example-1/>" msgstr "" -"Um comentário multilinha que começa com um \"*\" adicional marca um bloco de " +"Um comentário multilinha que começa com um “*” adicional marca um bloco de " "documentação que será processado pelas ferramentas do GTK-Doc. <_:example-1/>" # Ocultei o TODO da tradução. Para que server? :/ #. (itstool) path: sect1/para -#: C/index.docbook:745 +#: C/index.docbook:730 msgid "" "The 'identifier' is one line with the name of the item the comment is " "related to. The syntax differs a little depending on the item. (TODO add " "table showing identifiers)" msgstr "" -"O \"identificador\" é uma linha com o nome do item ao qual o comentário está " +"O “identificador” é uma linha com o nome do item ao qual o comentário está " "relacionado. A sintaxe difere um pouco dependendo do item." #. (itstool) path: sect1/para -#: C/index.docbook:751 +#: C/index.docbook:736 msgid "" "The 'documentation' block is also different for each symbol type. Symbol " "types that get parameters such as functions or macros have the parameter " @@ -1357,17 +1282,17 @@ msgid "" "breaks. If you don't want a paragraph break, change that into ' * ' (blank-" "asterisk-blank-blank). This is useful in preformatted text (code listings)." msgstr "" -"O bloco \"documentação\" também é diferente para cada tipo de símbolo. Tipos " +"O bloco “documentação” também é diferente para cada tipo de símbolo. Tipos " "de símbolos que levam parâmetros, como funções e macros, têm a descrição de " -"parâmetro começando com uma linha vazia (apenas com um \"*\"). " -"Posteriormente, segue com a descrição detalhada. Todas as linhas (fora das " -"listagens do programa e seções CDATA) contendo apenas um \" *\" (espaço em " -"branco e asterisco) são convertidas para quebras de parágrafos. Se você não " -"quiser uma quebra de parágrafo, altere isso para \" * \" (espaço, asterisco, " -"espaço e espaço). Isso é útil em textos pré-formatados (listagens de código)." +"parâmetro começando com uma linha vazia (apenas com um “*”). Posteriormente, " +"segue com a descrição detalhada. Todas as linhas (fora das listagens do " +"programa e seções CDATA) contendo apenas um “ *” (espaço em branco e " +"asterisco) são convertidas para quebras de parágrafos. Se você não quiser " +"uma quebra de parágrafo, altere isso para “ * “ (espaço, asterisco, espaço e " +"espaço). Isso é útil em textos pré-formatados (listagens de código)." #. (itstool) path: listitem/para -#: C/index.docbook:768 +#: C/index.docbook:753 msgid "" "What it is: The name for a class or function can sometimes be misleading for " "people coming from a different background." @@ -1376,24 +1301,24 @@ msgstr "" "entendimento equivocado pessoas com experiências diferentes." #. (itstool) path: listitem/para -#: C/index.docbook:774 +#: C/index.docbook:759 msgid "" "What it does: Tell about common uses. Put it in relation with the other API." msgstr "" "O que isso faz: Fale sobre usos comuns. Coloque em relação com a outra API." #. (itstool) path: tip/para -#: C/index.docbook:764 +#: C/index.docbook:749 msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" msgstr "Ao documentar um código, descreva dois aspectos: <_:itemizedlist-1/>" #. (itstool) path: listitem/para -#: C/index.docbook:789 +#: C/index.docbook:774 msgid "Use function() to refer to functions or macros which take arguments." msgstr "Use function() para referir às funções ou macros que levam argumentos." #. (itstool) path: listitem/para -#: C/index.docbook:794 +#: C/index.docbook:779 msgid "" "Use @param to refer to parameters. Also use this when referring to " "parameters of other functions, related to the one being described." @@ -1402,12 +1327,12 @@ msgstr "" "parâmetros de outras funções, relacionadas àquele sendo descrito." #. (itstool) path: listitem/para -#: C/index.docbook:800 +#: C/index.docbook:785 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "Use %constant para se referir a uma constante, ex.: %G_TRAVERSE_LEAFS." #. (itstool) path: listitem/para -#: C/index.docbook:805 +#: C/index.docbook:790 msgid "" "Use #symbol to refer to other types of symbol, e.g. structs and enums and " "macros which don't take arguments." @@ -1416,17 +1341,17 @@ msgstr "" "e macros que não levam argumentos." #. (itstool) path: listitem/para -#: C/index.docbook:811 +#: C/index.docbook:796 msgid "Use #Object::signal to refer to a GObject signal." msgstr "Use #Object::signal para se referir a um sinal de GObject." #. (itstool) path: listitem/para -#: C/index.docbook:816 +#: C/index.docbook:801 msgid "Use #Object:property to refer to a GObject property." msgstr "Use #Object:property para se referir a uma propriedade de GObject." #. (itstool) path: listitem/para -#: C/index.docbook:821 +#: C/index.docbook:806 msgid "" "Use #Struct.field to refer to a field inside a structure and #GObjectClass." "foo_bar() to refer to a vmethod." @@ -1435,7 +1360,7 @@ msgstr "" "#GObjectClass.foo_bar() para se referir a um vmethod." #. (itstool) path: sect1/para -#: C/index.docbook:783 +#: C/index.docbook:768 msgid "" "One advantage of hyper-text over plain-text is the ability to have links in " "the document. Writing the correct markup for a link can be tedious though. " @@ -1448,7 +1373,7 @@ msgstr "" "itemizedlist-1/>" #. (itstool) path: tip/para -#: C/index.docbook:830 +#: C/index.docbook:815 msgid "" "If you need to use the special characters '<', '>', '()', '@', '%', or " "'#' in your documentation without GTK-Doc changing them you can use the XML " @@ -1456,14 +1381,14 @@ msgid "" "commat;\", \"&percnt;\" and \"&num;\" respectively or escape them " "with a backslash '\\'." msgstr "" -"Se você precisar usar os caracteres especiais \"<\", \">\", \"()\", \"@" -"\", \"%\" ou \"#\" em sua documentação sem GTK-Doc alterando-os, você pode " -"usar as entidades XML \"&lt;\", \"&gt;\", \"&lpar;\", \"&" -"rpar;\", \"&commat;\", \"&percnt;\" e \"&num;\", " -"respectivamente, ou escapá-los com uma contrabarra \"\\\"." +"Se você precisar usar os caracteres especiais “<”, “>”, “()”, “@”, “%” " +"ou “#” em sua documentação sem GTK-Doc alterando-os, você pode usar as " +"entidades XML “&lt;”, “&gt;”, “&lpar;”, “&rpar;”, “&" +"commat;”, “&percnt;” e “&num;”, respectivamente, ou escapá-los com " +"uma contrabarra “\\”." #. (itstool) path: sect1/para -#: C/index.docbook:839 +#: C/index.docbook:824 msgid "" "DocBook can do more than just links. One can also have lists, examples, " "headings, and images. As of version 1.20, the preferred way is to use a " @@ -1481,7 +1406,7 @@ msgstr "" "linhas começando com um traço." #. (itstool) path: sect1/para -#: C/index.docbook:850 +#: C/index.docbook:835 msgid "" "While markdown is now preferred one can mix both. One limitation here is " "that one can use docbook xml within markdown, but markdown within docbook " @@ -1492,13 +1417,7 @@ msgstr "" "suporte a markdown no docbook xml." #. (itstool) path: sect1/para -#: C/index.docbook:856 -#| msgid "" -#| "In older GTK-Doc releases, if you need support for additional formatting, " -#| "you would need to enable the usage of docbook SGML/XML tags inside doc-" -#| "comments by putting or (ou ) na variável " -"MKDB_OPTIONS dentro de Makefile.am." +"docbook dentro de comentários de documentação colocando ) na variável MKDB_OPTIONS dentro de Makefile.am." #. (itstool) path: example/title -#: C/index.docbook:865 +#: C/index.docbook:850 msgid "GTK-Doc comment block using Markdown" msgstr "Bloco de comentário do GTK-Doc usando Markdown" #. (itstool) path: example/programlisting -#: C/index.docbook:866 +#: C/index.docbook:851 #, no-wrap msgid "" "\n" @@ -1594,7 +1513,7 @@ msgstr "" " */\n" #. (itstool) path: sect1/para -#: C/index.docbook:905 +#: C/index.docbook:890 msgid "" "More examples of what markdown tags are supported can be found in the Referência de sintaxe de markdown de documentação." #. (itstool) path: tip/para -#: C/index.docbook:911 +#: C/index.docbook:896 msgid "" "As already mentioned earlier GTK-Doc is for documenting public API. Thus one " "cannot write documentation for static symbols. Nevertheless it is good to " @@ -1619,18 +1538,17 @@ msgstr "" "Portanto, não é possível escrever documentação para símbolos estáticos. Não " "obstante, é bom comentar estes símbolos também. Isso ajuda outros a entender " "seu código. Portanto, é recomendado comentá-los usando comentários normais " -"(sem o segundo \"*\" na primeira linha). Se, posteriormente, a função " -"precisar ser publicada, tudo que precisa ser feito é adicionar outro \"*\" " -"no bloco de comentário e inserir o nome do símbolo no lugar correto do " -"arquivo e seções." +"(sem o segundo “*” na primeira linha). Se, posteriormente, a função precisar " +"ser publicada, tudo que precisa ser feito é adicionar outro “*” no bloco de " +"comentário e inserir o nome do símbolo no lugar correto do arquivo e seções." #. (itstool) path: sect1/title -#: C/index.docbook:925 +#: C/index.docbook:910 msgid "Documenting sections" msgstr "Documentando seções" #. (itstool) path: sect1/para -#: C/index.docbook:927 +#: C/index.docbook:912 msgid "" "Each section of the documentation contains information about one class or " "module. To introduce the component one can write a section block. The short " @@ -1643,12 +1561,12 @@ msgstr "" "os @fields são opcionais." #. (itstool) path: example/title -#: C/index.docbook:935 +#: C/index.docbook:920 msgid "Section comment block" msgstr "Bloco de comentário de sessão" #. (itstool) path: example/programlisting -#: C/index.docbook:936 +#: C/index.docbook:921 #, no-wrap msgid "" "\n" @@ -1680,30 +1598,35 @@ msgstr "" " */\n" #. (itstool) path: varlistentry/term -#: C/index.docbook:955 +#: C/index.docbook:940 msgid "SECTION:<name>" msgstr "SECTION:<nome>" #. (itstool) path: listitem/para -#: C/index.docbook:957 +#: C/index.docbook:942 +#| msgid "" +#| "The name links the section documentation to the respective part in the " +#| "<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 "" "O nome vincula a documentação da seção à respectiva parte do arquivo " "<pacote>-sections.txt. O nome informado aqui deve " -"corresponder à tag <FILE> no arquivo <pacote>-sections." -"txt." +"corresponder à tag <FILE> no arquivo " +"<pacote>-sections.txt." #. (itstool) path: varlistentry/term -#: C/index.docbook:966 +#: C/index.docbook:951 msgid "@short_description" msgstr "@short_description" #. (itstool) path: listitem/para -#: C/index.docbook:968 +#: C/index.docbook:953 msgid "" "A one line description of the section, that later will appear after the " "links in the TOC and at the top of the section page." @@ -1712,12 +1635,12 @@ msgstr "" "no TOC (sumário) no topo da página da sessão." #. (itstool) path: varlistentry/term -#: C/index.docbook:975 +#: C/index.docbook:960 msgid "@title" msgstr "@title" #. (itstool) path: listitem/para -#: C/index.docbook:977 +#: C/index.docbook:962 msgid "" "The section title defaults to <name> from the SECTION declaration. It " "can be overridden with the @title field." @@ -1726,12 +1649,12 @@ msgstr "" "pode ser sobrescrito com o campo @title." #. (itstool) path: varlistentry/term -#: C/index.docbook:984 +#: C/index.docbook:969 msgid "@section_id" msgstr "@section_id" #. (itstool) path: listitem/para -#: C/index.docbook:986 +#: C/index.docbook:971 msgid "" "Overrides the use of title as a section identifier. For GObjects the <" "title> is used as a section_id and for other sections it is <" @@ -1742,22 +1665,22 @@ msgstr "" "MÓDULO>-<title>." #. (itstool) path: varlistentry/term -#: C/index.docbook:994 +#: C/index.docbook:979 msgid "@see_also" msgstr "@see_also" #. (itstool) path: listitem/para -#: C/index.docbook:996 +#: C/index.docbook:981 msgid "A list of symbols that are related to this section." msgstr "Uma lista de símbolos que estão relacionados a esta sessão." #. (itstool) path: varlistentry/term -#: C/index.docbook:1002 +#: C/index.docbook:987 msgid "@stability" msgstr "@stability" #. (itstool) path: listitem/para -#: C/index.docbook:1009 +#: C/index.docbook:994 msgid "" "Stable - The intention of a Stable interface is to enable arbitrary third " "parties to develop applications to these interfaces, release them, and have " @@ -1774,7 +1697,7 @@ msgstr "" "alterações incompatíveis sejam raras e que tenham fortes justificativas." #. (itstool) path: listitem/para -#: C/index.docbook:1021 +#: C/index.docbook:1006 msgid "" "Unstable - Unstable interfaces are experimental or transitional. They are " "typically used to give outside developers early access to new or rapidly " @@ -1790,7 +1713,7 @@ msgstr "" "fontes de uma versão menor para a próxima." #. (itstool) path: listitem/para -#: C/index.docbook:1033 +#: C/index.docbook:1018 msgid "" "Private - An interface that can be used within the GNOME stack itself, but " "that is not documented for end-users. Such functions should only be used in " @@ -1801,7 +1724,7 @@ msgstr "" "usadas nas formas especificadas e documentadas." #. (itstool) path: listitem/para -#: C/index.docbook:1042 +#: C/index.docbook:1027 msgid "" "Internal - An interface that is internal to a module and does not require " "end-user documentation. Functions that are undocumented are assumed to be " @@ -1809,10 +1732,10 @@ msgid "" msgstr "" "Interna - Uma interface que é interna a um módulo e não requer documentação " "para o usuário final. Funções que não estão documentadas são presumidas como " -"sendo \"Interna\"." +"sendo “Interna”." #. (itstool) path: listitem/para -#: C/index.docbook:1004 +#: C/index.docbook:989 msgid "" "An informal description of the stability level this API has. We recommend " "the use of one of these terms: <_:itemizedlist-1/>" @@ -1821,12 +1744,12 @@ msgstr "" "recomendamos o uso de um desses termos: <_:itemizedlist-1/>" #. (itstool) path: varlistentry/term -#: C/index.docbook:1054 +#: C/index.docbook:1039 msgid "@include" msgstr "@include" #. (itstool) path: listitem/para -#: C/index.docbook:1056 +#: C/index.docbook:1041 msgid "" "The #include files to show in the section synopsis (a " "comma separated list), overriding the global value from the --default-stability argument to " @@ -1956,18 +1876,17 @@ msgstr "" "gtkdoc-mkdb com um dos balores abaixo." #. (itstool) path: variablelist/title -#: C/index.docbook:1134 -#| msgid "@stability" +#: C/index.docbook:1119 msgid "Stability Tags" msgstr "Tags de estabilidade" #. (itstool) path: varlistentry/term -#: C/index.docbook:1135 +#: C/index.docbook:1120 msgid "Stability: Stable" msgstr "Stability: Stable" #. (itstool) path: listitem/para -#: C/index.docbook:1137 +#: C/index.docbook:1122 msgid "" "Mark the element as stable. This is for public APIs which are guaranteed to " "remain stable for all future minor releases of the project." @@ -1976,12 +1895,12 @@ msgstr "" "garantida para todos os próximos lançamentos menores do projeto." #. (itstool) path: varlistentry/term -#: C/index.docbook:1144 +#: C/index.docbook:1129 msgid "Stability: Unstable" msgstr "Stability: Unstable" #. (itstool) path: listitem/para -#: C/index.docbook:1146 +#: C/index.docbook:1131 msgid "" "Mark the element as unstable. This is for public APIs which are released as " "a preview before being stabilised." @@ -1990,12 +1909,12 @@ msgstr "" "como versão de desenvolvimento antes de se tornar estável." #. (itstool) path: varlistentry/term -#: C/index.docbook:1152 +#: C/index.docbook:1137 msgid "Stability: Private" msgstr "Stability: Private" #. (itstool) path: listitem/para -#: C/index.docbook:1154 +#: C/index.docbook:1139 msgid "" "Mark the element as private. This is for interfaces which can be used by " "tightly coupled modules, but not by arbitrary third parties." @@ -2004,7 +1923,7 @@ msgstr "" "por um conjunto pequeno de módulos, mas não por terceiros." #. (itstool) path: example/programlisting -#: C/index.docbook:1164 +#: C/index.docbook:1149 #, no-wrap msgid "" "\n" @@ -2043,13 +1962,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1184 C/index.docbook:1194 -#| msgid "Installation" +#: C/index.docbook:1169 C/index.docbook:1179 msgid "Annotations" msgstr "Anotações" #. (itstool) path: sect2/para -#: C/index.docbook:1186 +#: C/index.docbook:1171 msgid "" "Documentation blocks can contain annotation-tags. These tags will be " "rendered with tooltips describing their meaning. The tags are used by " @@ -2061,11 +1979,11 @@ msgstr "" "renderizadas com dicas de ferramentas descrevendo seu significados. As tags " "são usadas pelo gobject-introspection para garantir associações (bindings) " "de linguagens. Uma lista detalhada tags aceitas podem ser encontrada no " -"wiki." +"url=\"http://live.gnome.org/GObjectIntrospection/Annotations\" type=\"http" +"\">no wiki." #. (itstool) path: example/programlisting -#: C/index.docbook:1195 +#: C/index.docbook:1180 #, no-wrap msgid "" "\n" @@ -2106,12 +2024,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1216 C/index.docbook:1245 +#: C/index.docbook:1201 C/index.docbook:1230 msgid "Function comment block" msgstr "Bloco de comentário de função" #. (itstool) path: listitem/para -#: C/index.docbook:1222 +#: C/index.docbook:1207 msgid "" "Document whether returned objects, lists, strings, etc, should be freed/" "unrefed/released." @@ -2120,34 +2038,34 @@ msgstr "" "não referenciados/liberada." #. (itstool) path: listitem/para -#: C/index.docbook:1228 +#: C/index.docbook:1213 msgid "Document whether parameters can be NULL, and what happens if they are." msgstr "" "Documente se parâmetros pode ser NULL e o que acontece se eles o forem." #. (itstool) path: listitem/para -#: C/index.docbook:1233 +#: C/index.docbook:1218 msgid "" "Mention interesting pre-conditions and post-conditions where appropriate." msgstr "" "Mencione pré-condições e pós-condições interessantes onde for apropriado." #. (itstool) path: sect2/para -#: C/index.docbook:1218 C/index.docbook:1304 +#: C/index.docbook:1203 C/index.docbook:1289 msgid "Please remember to: <_:itemizedlist-1/>" msgstr "Por favor, lembre-se de: <_:itemizedlist-1/>" #. (itstool) path: sect2/para -#: C/index.docbook:1240 +#: C/index.docbook:1225 msgid "" "Gtk-doc assumes all symbols (macros, functions) starting with '_' are " "private. They are treated like static functions." msgstr "" -"Gtk-doc presume que todos os símbolos (macros, funções) começando com \"_\" " +"Gtk-doc presume que todos os símbolos (macros, funções) começando com “_” " "são privadas. Elas são tratadas como funções estáticas." #. (itstool) path: example/programlisting -#: C/index.docbook:1246 +#: C/index.docbook:1231 #, no-wrap msgid "" "\n" @@ -2177,12 +2095,9 @@ msgstr "" " * @par2: descrição do parâmetro 2\n" " * @...: uma lista de bars terminada em %NULL\n" " *\n" -" * A descrição da função vai aqui. Você pode usar @par1 para se referir a " -"parâmetros\n" -" * de forma que eles ficam em destaque na saída. Você também pode usar %" -"constant\n" -" * para constantes, nome_da_função2() para funções e #GtkWidget para links " -"para\n" +" * A descrição da função vai aqui. Você pode usar @par1 para se referir a parâmetros\n" +" * de forma que eles ficam em destaque na saída. Você também pode usar %constant\n" +" * para constantes, nome_da_função2() para funções e #GtkWidget para links para\n" " * outras declarações (que pode ser documentada em outro lugar).\n" " *\n" " * Returns: um inteiro.\n" @@ -2192,27 +2107,27 @@ msgstr "" " */\n" #. (itstool) path: variablelist/title -#: C/index.docbook:1267 +#: C/index.docbook:1252 msgid "Function tags" msgstr "Tags de função" #. (itstool) path: varlistentry/term -#: C/index.docbook:1268 +#: C/index.docbook:1253 C/index.docbook:1460 msgid "Returns:" msgstr "Returns:" #. (itstool) path: listitem/para -#: C/index.docbook:1270 +#: C/index.docbook:1255 msgid "Paragraph describing the returned result." msgstr "Parágrafo descrevendo o resultado retornado." #. (itstool) path: varlistentry/term -#: C/index.docbook:1275 +#: C/index.docbook:1260 msgid "@...:" msgstr "@...:" #. (itstool) path: listitem/para -#: C/index.docbook:1277 +#: C/index.docbook:1262 msgid "" "In case the function has variadic arguments, you should use this tag " "(@Varargs: does also work for historic reasons)." @@ -2222,12 +2137,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1287 C/index.docbook:1289 +#: C/index.docbook:1272 C/index.docbook:1274 msgid "Property comment block" msgstr "Bloco de comentário de propriedade" #. (itstool) path: example/programlisting -#: C/index.docbook:1290 +#: C/index.docbook:1275 #, no-wrap msgid "" "\n" @@ -2248,12 +2163,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1302 C/index.docbook:1321 +#: C/index.docbook:1287 C/index.docbook:1306 msgid "Signal comment block" msgstr "Bloco de comentário de sinal" #. (itstool) path: listitem/para -#: C/index.docbook:1308 +#: C/index.docbook:1293 msgid "" "Document when the signal is emitted and whether it is emitted before or " "after other signals." @@ -2262,12 +2177,12 @@ msgstr "" "sinais." #. (itstool) path: listitem/para -#: C/index.docbook:1314 +#: C/index.docbook:1299 msgid "Document what an application might do in the signal handler." msgstr "Documente o que um aplicativo pode fazer no manipulador do sinal." #. (itstool) path: example/programlisting -#: C/index.docbook:1322 +#: C/index.docbook:1307 #, no-wrap msgid "" "\n" @@ -2298,28 +2213,13 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1339 C/index.docbook:1340 +#: C/index.docbook:1324 C/index.docbook:1325 msgid "Struct comment block" msgstr "Bloco de comentário de struct" #. (itstool) path: example/programlisting -#: C/index.docbook:1341 +#: C/index.docbook:1326 #, no-wrap -#| msgid "" -#| "\n" -#| "/**\n" -#| " * FooWidget:\n" -#| " * @bar: some #gboolean\n" -#| " *\n" -#| " * This is the best widget, ever.\n" -#| " */\n" -#| "typedef struct _FooWidget {\n" -#| " /*< private >*/\n" -#| " GtkWidget parent;\n" -#| "\n" -#| " /*< public >*/\n" -#| " gboolean bar;\n" -#| "} FooWidget;\n" msgid "" "\n" "/**\n" @@ -2348,7 +2248,7 @@ msgstr "" "} FooWidget;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1356 +#: C/index.docbook:1341 msgid "" "Use /*< private >*/ before the private struct fields you " "want to hide. Use /*< public >*/ for the reverse " @@ -2359,18 +2259,18 @@ msgstr "" "comportamento inverso." #. (itstool) path: sect2/para -#: C/index.docbook:1362 +#: C/index.docbook:1347 msgid "" "If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" " "it will be considered private automatically and doesn't need to be mentioned " "in the comment block." msgstr "" -"Se o primeiro campo for \"g_iface\", \"parent_instance\" ou \"parent_class\", ele " +"Se o primeiro campo for “g_iface”, “parent_instance” ou “parent_class”, ele " "será automaticamente considerado como privado e não precisará ser mencionado " "no bloco de comentário." #. (itstool) path: sect2/para -#: C/index.docbook:1368 +#: C/index.docbook:1353 msgid "" "Struct comment blocks can also be used for GObjects and GObjectClasses. It " "is usually a good idea to add a comment block for a class, if it has " @@ -2390,12 +2290,12 @@ msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title -#: C/index.docbook:1380 C/index.docbook:1381 +#: C/index.docbook:1365 C/index.docbook:1366 msgid "Enum comment block" msgstr "Bloco de comentário de enum" #. (itstool) path: example/programlisting -#: C/index.docbook:1382 +#: C/index.docbook:1367 #, no-wrap msgid "" "\n" @@ -2429,7 +2329,7 @@ msgstr "" "} Alguma coisa;\n" #. (itstool) path: sect2/para -#: C/index.docbook:1399 +#: C/index.docbook:1384 msgid "" "Use /*< private >*/ before the private enum values you " "want to hide. Use /*< public >*/ for the reverse " @@ -2440,12 +2340,154 @@ msgstr "" "comportamento inverso." #. (itstool) path: sect1/title -#: C/index.docbook:1409 +#: C/index.docbook:1395 +msgid "Inline program documentation" +msgstr "Documentação de programa em-linha" + +#. (itstool) path: sect1/para +#: C/index.docbook:1396 +msgid "" +"You can document programs and their commandline interface using inline " +"documentation." +msgstr "" +"Você pode documentar programas e sua interface de linha de comando usando " +"documentação em-linha." + +#. (itstool) path: variablelist/title +#: C/index.docbook:1402 +msgid "Tags" +msgstr "Tags" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1404 +msgid "PROGRAM" +msgstr "PROGRAM" + +#. (itstool) path: listitem/para +#: C/index.docbook:1407 +msgid "Defines the start of a program documentation." +msgstr "Define o início da documentação de um programa." + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1414 +msgid "@short_description:" +msgstr "@short_description:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1416 +msgid "Defines a short description of the program. (Optional)" +msgstr "Define uma descrição breve do programa. (Opcional)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1423 +msgid "@synopsis:" +msgstr "@synopsis:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1425 +msgid "" +"Defines the arguments, or list of arguments that the program can take. " +"(Optional)" +msgstr "" +"Define os argumentos, ou lista de argumentos, que o programa pode receber. " +"(Opcional)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1433 +msgid "@see_also:" +msgstr "@see_also:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1435 +msgid "See Also manual page section. (Optional)" +msgstr "A seção “Veja Também” (See Also) de páginas de manual. (Opcional)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1442 +msgid "@arg:" +msgstr "@arg:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1444 +msgid "Argument(s) passed to the program and their description. (Optional)" +msgstr "Argumento(s) passado(s) para o programa e sua descrição. (Opcional)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1451 +msgid "Description:" +msgstr "Description:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1453 +msgid "A longer description of the program." +msgstr "Um descrição mais longa do programa." + +#. (itstool) path: listitem/para +#: C/index.docbook:1462 +msgid "Specificy what value(s) the program returns. (Optional)" +msgstr "Especifique quais valor(es) o programa retorna. (Opcional)" + +#. (itstool) path: sect2/title +#: C/index.docbook:1471 +msgid "Example of program documentation." +msgstr "Exemplo de documentação de programa." + +#. (itstool) path: example/title +#: C/index.docbook:1472 +msgid "Program documentation block" +msgstr "Bloco de documentação de programa" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1473 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * PROGRAM:test-program\n" +" * @short_description: A test program\n" +" * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*\n" +" * @see_also: test(1)\n" +" * @--arg1 *arg*: set arg1 to *arg*\n" +" * @--arg2 *arg*: set arg2 to *arg*\n" +" * @-v, --version: Print the version number\n" +" * @-h, --help: Print the help message\n" +" *\n" +" * Long description of program.\n" +" *\n" +" * Returns: Zero on success, non-zero on failure\n" +" */\n" +"int main(int argc, char *argv[])\n" +"{\n" +"\treturn 0;\n" +"}\n" +msgstr "" +"\n" +"/**\n" +" * PROGRAM:programa-teste\n" +" * @short_description: Um programa teste\n" +" * @synopsis: programa-teste [*OPÇÕES*...] --arg1 *arg* *ARQUIVO*\n" +" * @see_also: teste(1)\n" +" * @--arg1 *arg*: define arg1 para *arg*\n" +" * @--arg2 *arg*: define arg2 para *arg*\n" +" * @-v, --version: Exibe o número da versão\n" +" * @-h, --help: Exibe a mensagem de ajuda\n" +" *\n" +" * Descrição longa do programa.\n" +" *\n" +" * Returns: Zero no caso de sucesso, não-zero no caso de falha\n" +" */\n" +"int main(int argc, char *argv[])\n" +"{\n" +"\treturn 0;\n" +"}\n" + +#. (itstool) path: sect1/title +#: C/index.docbook:1499 msgid "Useful DocBook tags" msgstr "Tags úteis do DocBook" #. (itstool) path: sect1/para -#: C/index.docbook:1411 +#: C/index.docbook:1501 msgid "" "Here are some DocBook tags which are most useful when documenting the code." msgstr "" @@ -2453,7 +2495,7 @@ msgstr "" "documentado o código." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1420 +#: C/index.docbook:1510 #, no-wrap msgid "" "\n" @@ -2463,7 +2505,7 @@ msgstr "" "<link linkend=\"glib-Hash-Tables\">Tabela de hashes</link>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1416 +#: C/index.docbook:1506 msgid "" "To link to another section in the GTK docs: <_:informalexample-1/> The " "linkend is the SGML/XML id on the top item of the page you want to link to. " @@ -2472,14 +2514,14 @@ msgid "" "name. Spaces and underscores are converted to '-' to conform to SGML/XML." msgstr "" "Para vincular a outra seção nas documentações do GTK: <_:informalexample-1/> " -"O fim do link é o ID do SGML/XML no item superior da páginao a qual você " -"deseja vincular. Para a maioria das páginas isto é atualmente a parte (\"gtk" -"\", \"gdk\", \"glib\") e, então, o título da página (\"Hash Tables\"). Para " -"os widgets isso é apenas o nome da classe. Espaços e sublinhados são " +"O fim do link é o ID do SGML/XML no item superior da página a qual você " +"deseja vincular. Para a maioria das páginas isto é atualmente a parte " +"(“gtk”, “gdk”, “glib”) e, então, o título da página (“Hash Tables”). Para os " +"widgets isso é apenas o nome da classe. Espaços e sublinhados são " "convertidos em '-' para estar em conformidade com SGML/XML." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1433 +#: C/index.docbook:1523 #, no-wrap msgid "" "\n" @@ -2489,7 +2531,7 @@ msgstr "" "<function>...</function>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1430 +#: C/index.docbook:1520 msgid "" "To refer to an external function, e.g. a standard C function: <_:" "informalexample-1/>" @@ -2498,7 +2540,7 @@ msgstr "" "do C: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1442 +#: C/index.docbook:1532 #, no-wrap msgid "" "\n" @@ -2518,7 +2560,7 @@ msgstr "" "</example>\n" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1453 +#: C/index.docbook:1543 #, no-wrap msgid "" "\n" @@ -2536,7 +2578,7 @@ msgstr "" "</informalexample>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1439 +#: C/index.docbook:1529 msgid "" "To include example code: <_:informalexample-1/> or possibly this, for very " "short code fragments which don't need a title: <_:informalexample-2/> For " @@ -2548,7 +2590,7 @@ msgstr "" "abreviação: |[ ... ]|" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1472 +#: C/index.docbook:1562 #, no-wrap msgid "" "\n" @@ -2580,12 +2622,12 @@ msgstr "" "</itemizedlist>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1469 +#: C/index.docbook:1559 msgid "To include bulleted lists: <_:informalexample-1/>" msgstr "Para incluir listas com marcadores: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1492 +#: C/index.docbook:1582 #, no-wrap msgid "" "\n" @@ -2603,13 +2645,13 @@ msgstr "" "</note>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1489 +#: C/index.docbook:1579 msgid "" "To include a note which stands out from the text: <_:informalexample-1/>" msgstr "Para incluir uma nota que fique fora do texto: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1505 +#: C/index.docbook:1595 #, no-wrap msgid "" "\n" @@ -2619,12 +2661,12 @@ msgstr "" "<type>unsigned char</type>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1502 +#: C/index.docbook:1592 msgid "To refer to a type: <_:informalexample-1/>" msgstr "Para se referir a um tipo: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1514 +#: C/index.docbook:1604 #, no-wrap msgid "" "\n" @@ -2634,7 +2676,7 @@ msgstr "" "<structname>XFontStruct</structname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1511 +#: C/index.docbook:1601 msgid "" "To refer to an external structure (not one described in the GTK docs): <_:" "informalexample-1/>" @@ -2643,7 +2685,7 @@ msgstr "" "GTK): <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1523 +#: C/index.docbook:1613 #, no-wrap msgid "" "\n" @@ -2653,12 +2695,12 @@ msgstr "" "<structfield>len</structfield>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1520 +#: C/index.docbook:1610 msgid "To refer to a field of a structure: <_:informalexample-1/>" msgstr "Para se referir a um campo de uma estrutura: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1532 +#: C/index.docbook:1622 #, no-wrap msgid "" "\n" @@ -2668,7 +2710,7 @@ msgstr "" "<classname>GtkWidget</classname>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1529 +#: C/index.docbook:1619 msgid "" "To refer to a class name, we could possibly use: <_:informalexample-1/> but " "you'll probably be using #GtkWidget instead (to automatically create a link " @@ -2681,7 +2723,7 @@ msgstr "" "veja as abreviações)." #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1543 +#: C/index.docbook:1633 #, no-wrap msgid "" "\n" @@ -2691,12 +2733,12 @@ msgstr "" "<emphasis>Isso é importante</emphasis>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1540 +#: C/index.docbook:1630 msgid "To emphasize text: <_:informalexample-1/>" msgstr "Para enfatizar um texto: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1552 +#: C/index.docbook:1642 #, no-wrap msgid "" "\n" @@ -2706,12 +2748,12 @@ msgstr "" "<filename>/home/usuario/documentos</filename>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1549 +#: C/index.docbook:1639 msgid "For filenames use: <_:informalexample-1/>" msgstr "Para nome de arquivos use: <_:informalexample-1/>" #. (itstool) path: informalexample/programlisting -#: C/index.docbook:1561 +#: C/index.docbook:1651 #, no-wrap msgid "" "\n" @@ -2721,17 +2763,17 @@ msgstr "" "<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1558 +#: C/index.docbook:1648 msgid "To refer to keys use: <_:informalexample-1/>" msgstr "Para se referir a chaves use: <_:informalexample-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1571 +#: C/index.docbook:1661 msgid "Filling the extra files" msgstr "Preenchendo os arquivos extras" #. (itstool) path: chapter/para -#: C/index.docbook:1573 +#: C/index.docbook:1663 msgid "" "There are a couple of extra files, that need to be maintained along with the " "inline source code comments: <package>.types, " @@ -2744,12 +2786,12 @@ msgstr "" "<pacote>-sections.txt." #. (itstool) path: sect1/title -#: C/index.docbook:1582 +#: C/index.docbook:1672 msgid "Editing the types file" msgstr "Editando o arquivo de tipos" #. (itstool) path: sect1/para -#: C/index.docbook:1584 +#: C/index.docbook:1674 msgid "" "If your library or application includes GObjects, you want their signals, " "arguments/parameters and position in the hierarchy to be shown in the " @@ -2764,12 +2806,12 @@ msgstr "" "<pacote>.types." #. (itstool) path: example/title -#: C/index.docbook:1593 +#: C/index.docbook:1683 msgid "Example types file snippet" msgstr "Trecho de exemplo de arquivo de tipos" #. (itstool) path: example/programlisting -#: C/index.docbook:1594 +#: C/index.docbook:1684 #, no-wrap msgid "" "\n" @@ -2789,7 +2831,7 @@ msgstr "" "gtk_arrow_get_type\n" #. (itstool) path: sect1/para -#: C/index.docbook:1605 +#: C/index.docbook:1695 msgid "" "Since GTK-Doc 1.8 gtkdoc-scan can generate this " "list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in " @@ -2797,17 +2839,17 @@ msgid "" "dist the types file nor have it under version control." msgstr "" "Desde o GTK-Doc 1.8, o gtkdoc-scan pode gerar " -"esta lista para você. Basta adicionar \"--rebuild-types\" a SCAN_OPTIONS no " +"esta lista para você. Basta adicionar “--rebuild-types” a SCAN_OPTIONS no " "Makefile.am. Se você usar esta abordagem, você não " "deveria distribuir o arquivo de tipos nem tê-lo sob um controle de versão." #. (itstool) path: sect1/title -#: C/index.docbook:1614 +#: C/index.docbook:1704 msgid "Editing the master document" msgstr "Editando o documento mestre" #. (itstool) path: sect1/para -#: C/index.docbook:1616 +#: C/index.docbook:1706 msgid "" "GTK-Doc produces documentation in DocBook SGML/XML. When processing the " "inline source comments, the GTK-Doc tools generate one documentation page " @@ -2820,14 +2862,7 @@ msgstr "" "mestre os inclui e os coloca em uma ordem." #. (itstool) path: sect1/para -#: C/index.docbook:1623 -#| msgid "" -#| "While GTK-Doc creates a template master document for you, later run will " -#| "not touch it again. This means that one can freely structure the " -#| "documentation. That includes grouping pages and adding extra pages. GTK-" -#| "Doc has now a test suite, where also the master-document is recreated " -#| "from scratch. Its a good idea to look at this from time to time to see if " -#| "there are some new goodies introduced there." +#: C/index.docbook:1713 msgid "" "While GTK-Doc creates a template master document for you, later runs will " "not touch it again. This means that one can freely structure the " @@ -2844,7 +2879,7 @@ msgstr "" "em tempo para ver se há itens a serem introduzidos lá." #. (itstool) path: tip/para -#: C/index.docbook:1633 +#: C/index.docbook:1723 msgid "" "Do not create tutorials as extra documents. Just write extra chapters. The " "benefit of directly embedding the tutorial for your library into the API " @@ -2859,7 +2894,7 @@ msgstr "" "atualizações junto com a biblioteca." #. (itstool) path: sect1/para -#: C/index.docbook:1642 +#: C/index.docbook:1732 msgid "" "So what are the things to change inside the master document? For a start is " "only a little. There are some placeholders (text in square brackets) there " @@ -2870,12 +2905,12 @@ msgstr "" "colchetes) que você deve cuidar." #. (itstool) path: example/title -#: C/index.docbook:1649 +#: C/index.docbook:1739 msgid "Master document header" msgstr "Cabeçalho do documento mestre" #. (itstool) path: example/programlisting -#: C/index.docbook:1650 +#: C/index.docbook:1740 #, no-wrap msgid "" "\n" @@ -2905,7 +2940,7 @@ msgstr "" " <title>[Insira o título aqui]</title>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1666 +#: C/index.docbook:1756 msgid "" "In addition a few option elements are created in commented form. You can " "review these and enable them as you like." @@ -2914,45 +2949,43 @@ msgstr "" "pode revisá-los e habilitá-los como preferir." #. (itstool) path: example/title -#: C/index.docbook:1672 -#| msgid "Editing the master document" +#: C/index.docbook:1762 msgid "Optional part in the master document" msgstr "Parte opcional do documento mestre" #. (itstool) path: example/programlisting -#: C/index.docbook:1673 +#: C/index.docbook:1763 #, no-wrap msgid "" "\n" " <!-- enable this when you use gobject introspection annotations\n" " <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n" -" --> \n" +" -->\n" msgstr "" "\n" " <!-- habilite isso se você usa anotações do gobject introspection\n" -" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback " -"/></xi:include>\n" -" --> \n" +" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n" +" -->\n" #. (itstool) path: sect1/para -#: C/index.docbook:1681 +#: C/index.docbook:1771 msgid "" "Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind " "you of newly generated xml files that are not yet included into the doc." msgstr "" "Finalmente você precisa adicionar nova seção sempre que você a introduzir. A " -"ferramenta gtkdoc-check vai " -"lembrar você de arquivos xml recentemente gerados que ainda não foram " +"ferramenta gtkdoc-check " +"vai lembrar você de arquivos xml recentemente gerados que ainda não foram " "incluídos na documentação." #. (itstool) path: example/title -#: C/index.docbook:1689 C/index.docbook:1724 +#: C/index.docbook:1779 C/index.docbook:1814 msgid "Including generated sections" msgstr "Incluindo seções geradas" #. (itstool) path: example/programlisting -#: C/index.docbook:1690 +#: C/index.docbook:1780 #, no-wrap msgid "" "\n" @@ -2968,12 +3001,12 @@ msgstr "" " ...\n" #. (itstool) path: sect1/title -#: C/index.docbook:1702 +#: C/index.docbook:1792 msgid "Editing the section file" msgstr "Editando o arquivo de seção" #. (itstool) path: sect1/para -#: C/index.docbook:1704 +#: C/index.docbook:1794 msgid "" "The section file is used to organise the documentation output by GTK-Doc. " "Here one specifies which symbol belongs to which module or class and control " @@ -2984,21 +3017,17 @@ msgstr "" "e controla a visibilidade (pública ou privada)." #. (itstool) path: sect1/para -#: C/index.docbook:1710 -#| msgid "" -#| "The section file is a plain text file with XML-like syntax (using tags). " -#| "Blank lines are ignored and lines starting with a '#' are treated as " -#| "comment lines." +#: C/index.docbook:1800 msgid "" "The section file is a plain text file with tags delimiting sections. Blank " "lines are ignored and lines starting with a '#' are treated as comment lines." msgstr "" "O arquivo de seção é uma arquivo texto simples com seções delimitadas por " -"tags. Linhas em branco são ignoradas e linhas começando com um \"#\" são " +"tags. Linhas em branco são ignoradas e linhas começando com um “#” são " "tratadas como linhas de comentários." #. (itstool) path: note/para -#: C/index.docbook:1717 +#: C/index.docbook:1807 msgid "" "While the tags make the file look like xml, it is not. Please do not close " "tags like <SUBSECTION>." @@ -3007,7 +3036,7 @@ msgstr "" "feche tags como <SUBSECTION>." #. (itstool) path: example/programlisting -#: C/index.docbook:1725 +#: C/index.docbook:1815 #, no-wrap msgid "" "\n" @@ -3039,17 +3068,7 @@ msgstr "" "</SECTION>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1742 -#| msgid "" -#| "The <FILE> ... </FILE> tag is used to specify the file name, " -#| "without any suffix. For example, using '<FILE>gnome-config</" -#| "FILE>' will result in the section declarations being output in the " -#| "template file tmpl/gnome-config.sgml, which will be " -#| "converted into the DocBook SGML/XML file sgml/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)." +#: C/index.docbook:1832 msgid "" "The <FILE> ... </FILE> tag is used to specify the file name, " "without any suffix. For example, using '<FILE>gnome-config</" @@ -3062,17 +3081,17 @@ msgid "" "lower case)." msgstr "" "A tag <FILE> ... </FILE> é usada para especificar o nome de " -"arquivo, sem qualquer sufixo. Por exemplo, ao usar \"<FILE>gnome-" -"config</FILE>\" resultará nas declarações da seção serem retornadas no " +"arquivo, sem qualquer sufixo. Por exemplo, ao usar “<FILE>gnome-" +"config</FILE>” resultará nas declarações da seção serem retornadas no " "arquivo modelo tmpl/gnome-config.sgml, o qual será " "convertido no arquivo DocBook XML xml/gnome-config.sgml " -"ou no arquivo DocBook XML xml/gnome-config.xml. (O " -"nome do arquivo HTML é baseado no nome do módulo e no título da seção ou, " -"para GObjects, é baseado no nome da classe GObjects convertidos os " -"caracteres para minúsculos)." +"ou no arquivo DocBook XML xml/gnome-config.xml. (O nome " +"do arquivo HTML é baseado no nome do módulo e no título da seção ou, para " +"GObjects, é baseado no nome da classe GObjects convertidos os caracteres " +"para minúsculos)." #. (itstool) path: sect1/para -#: C/index.docbook:1754 +#: C/index.docbook:1844 msgid "" "The <TITLE> ... </TITLE> tag is used to specify the title of the " "section. It is only useful before the templates (if used) are initially " @@ -3086,7 +3105,7 @@ msgstr "" "obsoleto." #. (itstool) path: sect1/para -#: C/index.docbook:1761 +#: C/index.docbook:1851 msgid "" "You can group items in the section by using the <SUBSECTION> tag. " "Currently it outputs a blank line between subsections in the synopsis " @@ -3103,7 +3122,7 @@ msgid "" msgstr "" "Você pode agrupar itens na seção usando a tag <SUBSECTION>. " "Atualmente, ela retorna uma linha em branco entre as subseções na seção de " -"sinópse. Você também pode usar <SUBSECTION Standard> para declarações " +"sinopse. Você também pode usar <SUBSECTION Standard> para declarações " "padrão do GObject (ex.: as funções como g_object_get_type e macros como " "G_OBJECT(), G_IS_OBJECT() etc.). Atualmente, estas são deixadas fora da " "documentação. Você também pode usar <SUBSECTION Private> para " @@ -3115,7 +3134,7 @@ msgstr "" "padrão ou pública depende se há entradas públicas (variáveis, vmethods)." #. (itstool) path: sect1/para -#: C/index.docbook:1780 +#: C/index.docbook:1870 msgid "" "You can also use <INCLUDE> ... </INCLUDE> to specify the " "#include files which are shown in the synopsis sections. It contains a comma-" @@ -3124,19 +3143,19 @@ msgid "" "If you set it within a section, it only applies to that section." msgstr "" "Você também pode usar <INCLUDE> ... </INCLUDE> para especificar " -"os arquivos #include que são mostrados nas seções de sinópse. Ela contém uma " +"os arquivos #include que são mostrados nas seções de sinopse. Ela contém uma " "lista separada por vírgula de arquivos #include, sem os sinais de maior que " "e menor que. Se você define-a fora de quaisquer seções, ela age para todas " "as seções até o fim do arquivo. Se você define-a em uma seção, ela só vai se " "aplicar àquela seção." #. (itstool) path: chapter/title -#: C/index.docbook:1794 +#: C/index.docbook:1884 msgid "Controlling the result" msgstr "Controlando o resultado" #. (itstool) path: chapter/para -#: C/index.docbook:1796 +#: C/index.docbook:1886 msgid "" "A GTK-Doc run generates report files inside the documentation directory. The " "generated files are named: <package>-undocumented.txt<package>-undocumented.txt file starts with " "the documentation coverage summary. Below are two sections divided by blank " @@ -3168,7 +3187,7 @@ msgstr "" "exemplo, um novo parâmetro foi adicionado." #. (itstool) path: chapter/para -#: C/index.docbook:1814 +#: C/index.docbook:1904 msgid "" "The <package>-undeclared.txt file lists symbols " "given in the <package>-sections.txt but not found " @@ -3180,7 +3199,7 @@ msgstr "" "escritos incorretamente." #. (itstool) path: chapter/para -#: C/index.docbook:1821 +#: C/index.docbook:1911 msgid "" "The <package>-unused.txt file lists symbol names, " "where the GTK-Doc scanner has found documentation, but does not know where " @@ -3193,7 +3212,7 @@ msgstr "" "ainda ao arquivo <pacote>-sections.txt." #. (itstool) path: tip/para -#: C/index.docbook:1829 +#: C/index.docbook:1919 msgid "" "Enable or add the line in Makefile." "am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during " @@ -3204,7 +3223,7 @@ msgstr "" "verificações de sanidade durante a execução de make check." #. (itstool) path: chapter/para -#: C/index.docbook:1836 +#: C/index.docbook:1926 msgid "" "One can also look at the files produced by the source code scanner: " "<package>-decl-list.txt and <" @@ -3221,7 +3240,7 @@ msgstr "" "este arquivo o contém." #. (itstool) path: chapter/para -#: C/index.docbook:1845 +#: C/index.docbook:1935 msgid "" "If the project is GObject based, one can also look into the files produced " "by the object scanner: <package>.args.txt, " @@ -3242,12 +3261,12 @@ msgstr "" "executando GTK_DOC_KEEP_INTERMEDIATE=1 make." #. (itstool) path: chapter/title -#: C/index.docbook:1860 +#: C/index.docbook:1950 msgid "Modernizing the documentation" msgstr "Modernizando a documentação" #. (itstool) path: chapter/para -#: C/index.docbook:1862 +#: C/index.docbook:1952 msgid "" "GTK-Doc has been around for quite some time. In this section we list new " "features together with the version since when it is available." @@ -3256,12 +3275,12 @@ msgstr "" "funcionalidades juntamente da versão desde a qual está disponível." #. (itstool) path: sect1/title -#: C/index.docbook:1868 +#: C/index.docbook:1958 msgid "GTK-Doc 1.9" msgstr "GTK-Doc 1.9" #. (itstool) path: sect1/para -#: C/index.docbook:1870 +#: C/index.docbook:1960 msgid "" "When using xml instead of sgml, one can actually name the master document " "<package>-docs.xml." @@ -3270,7 +3289,7 @@ msgstr "" "<pacote>-docs.xml." #. (itstool) path: sect1/para -#: C/index.docbook:1875 +#: C/index.docbook:1965 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3291,39 +3310,42 @@ msgstr "" "meld <package>-decl-list.txt <package>-sections.txt." #. (itstool) path: sect1/para -#: C/index.docbook:1886 +#: C/index.docbook:1976 #| msgid "" #| "Version 1.8 already introduced the syntax for documenting sections in the " #| "sources instead of the separate files under 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." +#| "flavour no-tmpl in configure.ac. If you " +#| "don't have a tmpl checked into " +#| "you source control system and haven't yet switched, just add the flag to " +#| "configure.ac and you are done." 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 you source " +"tmpl checked into your source " "control system and haven't yet switched, just add the flag to " "configure.ac and you are done." msgstr "" "A versão 1.8 já introduziu a sintaxe para documentação seções nos fontes em " -"vez dos arquivos separados sob tmpl. " -"Essa versão adiciona opções para alternar todo o módulo de documentação para " -"não usar a etapa de compilação extra do tmpl, usando no configure.ac. Se você não possui um " +"vez dos arquivos separados sob tmpl" +". Essa versão adiciona opções para alternar todo o módulo de documentação " +"para não usar a etapa de compilação extra do tmpl, usando no configure.ac. Se você não possui um " "tmpl no seu sistema de controle de " "versão e ainda não trocou, basta adicionar uma opção ao " "configure.ac e está resolvido." #. (itstool) path: sect1/title -#: C/index.docbook:1898 +#: C/index.docbook:1988 msgid "GTK-Doc 1.10" msgstr "GTK-Doc 1.10" #. (itstool) path: sect1/para -#: C/index.docbook:1900 +#: C/index.docbook:1990 msgid "" "This version supports in " "Makefile.am. When this is enabled, the <" @@ -3340,17 +3362,17 @@ msgstr "" "código que é compilado condicionalmente." #. (itstool) path: sect1/title -#: C/index.docbook:1911 +#: C/index.docbook:2001 msgid "GTK-Doc 1.16" msgstr "GTK-Doc 1.16" #. (itstool) path: example/title -#: C/index.docbook:1917 +#: C/index.docbook:2007 msgid "Enable gtkdoc-check" msgstr "Habilitar gtkdoc-check" #. (itstool) path: example/programlisting -#: C/index.docbook:1918 +#: C/index.docbook:2008 #, no-wrap msgid "" "\n" @@ -3370,7 +3392,7 @@ msgstr "" "endif\n" #. (itstool) path: sect1/para -#: C/index.docbook:1913 +#: C/index.docbook:2003 msgid "" "This version includes a new tool called gtkdoc-check. This tool can run a " "set of sanity checks on your documentation. It is enabled by adding these " @@ -3382,12 +3404,12 @@ msgstr "" "filename>. <_:example-1/>" #. (itstool) path: sect1/title -#: C/index.docbook:1931 +#: C/index.docbook:2021 msgid "GTK-Doc 1.20" msgstr "GTK-Doc 1.20" #. (itstool) path: sect1/para -#: C/index.docbook:1933 +#: C/index.docbook:2023 msgid "" "Version 1.18 brought some initial markdown support. Using markdown in doc " "comments is less intrusive than writing docbook xml. This version improves a " @@ -3401,18 +3423,17 @@ msgstr "" "comentário tem todos os detalhes." #. (itstool) path: sect1/title -#: C/index.docbook:1943 -#| msgid "GTK-Doc 1.20" +#: C/index.docbook:2033 msgid "GTK-Doc 1.25" msgstr "GTK-Doc 1.25" #. (itstool) path: example/title -#: C/index.docbook:1953 +#: C/index.docbook:2043 msgid "Use pre-generated entities" msgstr "Usando entradas geradas previamente" #. (itstool) path: example/programlisting -#: C/index.docbook:1954 +#: C/index.docbook:2044 #, no-wrap msgid "" "\n" @@ -3439,8 +3460,7 @@ msgstr "" "<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"\n" " \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"\n" "[\n" -" <!ENTITY % local.common.attrib \"xmlns:xi CDATA #FIXED " -"'http://www.w3.org/2003/XInclude'\">\n" +" <!ENTITY % local.common.attrib \"xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'\">\n" " <!ENTITY % gtkdocentities SYSTEM \"xml/gtkdocentities.ent\">\n" " %gtkdocentities;\n" "]>\n" @@ -3450,18 +3470,25 @@ msgstr "" " <releaseinfo>\n" " para &versão-pacote;.\n" " A última versão desta documentação pode ser encontra on-line em\n" -" <ulink role=\"online-location\" url=\"http://[SERVIDOR]/&nome-" -"pacote;/index.html\">http://[SERVIDOR]/&nome-pacote;/</ulink>.\n" +" <ulink role=\"online-location\" url=\"http://[SERVIDOR]/&nome-pacote;/index.html\">http://[SERVIDOR]/&nome-pacote;/</ulink>.\n" " </releaseinfo>\n" " </bookinfo>\n" #. (itstool) path: sect1/para -#: C/index.docbook:1945 +#: C/index.docbook:2035 +#| msgid "" +#| "The makefiles shipped with this version generate an entity file at " +#| "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 any example that " +#| "shows how the entity file is included and how the entities are used. The " +#| "entities can also be used in all generated files, GTK-Doc will use the " +#| "same xml header in generated xml files. <_:example-1/>" msgid "" "The makefiles shipped with this version generate an entity file at " "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 any example that shows how " +"to avoid hardcoding the version number. Below is an example that shows how " "the entity file is included and how the entities are used. The entities can " "also be used in all generated files, GTK-Doc will use the same xml header in " "generated xml files. <_:example-1/>" @@ -3476,12 +3503,12 @@ msgstr "" "xml nos arquivos xml gerados. <_:example-1/>" #. (itstool) path: chapter/title -#: C/index.docbook:1979 +#: C/index.docbook:2069 msgid "Documenting other interfaces" msgstr "Documentando outras interfaces" #. (itstool) path: chapter/para -#: C/index.docbook:1981 +#: C/index.docbook:2071 msgid "" "So far we have been using GTK-Doc to document the API of code. The next " "sections contain suggestions how the tools can be used to document other " @@ -3492,13 +3519,13 @@ msgstr "" "para documentar outras interfaces, também." #. (itstool) path: sect1/title -#: C/index.docbook:1988 +#: C/index.docbook:2078 msgid "Command line options and man pages" msgstr "Opções de linha de comando e de páginas man" # RefEntry é uma página de referência do DocBook (http://www.docbook.org/tdg/en/html/refentry.html) #. (itstool) path: sect1/para -#: C/index.docbook:1990 +#: C/index.docbook:2080 msgid "" "As one can generate man pages for a docbook refentry as well, it sounds like " "a good idea to use it for that purpose. This way the interface is part of " @@ -3509,12 +3536,12 @@ msgstr "" "parte da referência e é possível obter a página man de graça." #. (itstool) path: sect2/title -#: C/index.docbook:1997 +#: C/index.docbook:2087 msgid "Document the tool" msgstr "Documentar a ferramenta" #. (itstool) path: sect2/para -#: C/index.docbook:1999 +#: C/index.docbook:2089 msgid "" "Create one refentry file per tool. Following our example we would call it meep/" @@ -3529,17 +3556,17 @@ msgstr "" "assim como exemplos, por exemplo, em glib." #. (itstool) path: sect2/title -#: C/index.docbook:2009 +#: C/index.docbook:2099 msgid "Adding the extra configure check" msgstr "Adicionando a verificação extra ao configure" #. (itstool) path: example/title -#: C/index.docbook:2012 C/index.docbook:2030 +#: C/index.docbook:2102 C/index.docbook:2120 msgid "Extra configure checks" msgstr "Verificações extra no configure" #. (itstool) path: example/programlisting -#: C/index.docbook:2013 +#: C/index.docbook:2103 #, no-wrap msgid "" "\n" @@ -3561,12 +3588,12 @@ msgstr "" "AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" #. (itstool) path: sect2/title -#: C/index.docbook:2027 +#: C/index.docbook:2117 msgid "Adding the extra makefile rules" msgstr "Adicionando as regras extras ao makefile" #. (itstool) path: example/programlisting -#: C/index.docbook:2031 +#: C/index.docbook:2121 #, no-wrap msgid "" "\n" @@ -3602,12 +3629,12 @@ msgstr "" "EXTRA_DIST += meep.xml\n" #. (itstool) path: sect1/title -#: C/index.docbook:2053 +#: C/index.docbook:2143 msgid "DBus interfaces" msgstr "Interfaces DBus" #. (itstool) path: sect1/para -#: C/index.docbook:2055 +#: C/index.docbook:2145 msgid "" "(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" "cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" @@ -3616,27 +3643,27 @@ msgstr "" "http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" #. (itstool) path: chapter/title -#: C/index.docbook:2064 +#: C/index.docbook:2154 msgid "Frequently asked questions" msgstr "Perguntas frequentes" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2068 +#: C/index.docbook:2158 msgid "Question" msgstr "Questão" #. (itstool) path: segmentedlist/segtitle -#: C/index.docbook:2069 +#: C/index.docbook:2159 msgid "Answer" msgstr "Resposta" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2071 +#: C/index.docbook:2161 msgid "No class hierarchy." msgstr "Sem hierarquia de classe." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2072 +#: C/index.docbook:2162 msgid "" "The objects xxx_get_type() function has not been " "entered into the <package>.types file." @@ -3645,12 +3672,12 @@ msgstr "" "arquivo <pacote>.types." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2078 +#: C/index.docbook:2168 msgid "Still no class hierarchy." msgstr "Ainda sem hierarquia." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2079 +#: C/index.docbook:2169 msgid "" "Missing or wrong naming in <package>-sections.txt " "file (see explicação)." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2085 +#: C/index.docbook:2175 msgid "Damn, I have still no class hierarchy." msgstr "Droga. Eu ainda não tenho hierarquia de classes." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2086 +#: C/index.docbook:2176 msgid "" "Is the object name (name of the instance struct, e.g. GtkWidget) part of the normal section (don't put this into Standard or Private " @@ -3677,26 +3704,26 @@ msgstr "" "subseções Standard ou Private)?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2093 +#: C/index.docbook:2183 msgid "No symbol index." msgstr "Nenhum símbolo de índice." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2094 +#: C/index.docbook:2184 msgid "" "Does the <package>-docs.{xml,sgml} contain a " "index that xi:includes the generated index?" msgstr "" "O <pacote>-docs.{xml,sgml} contém um índice que " -"\"xi:inclui\" o índice gerado?" +"“xi:inclui” o índice gerado?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2100 +#: C/index.docbook:2190 msgid "Symbols are not linked to their doc-section." msgstr "Símbolos não estão vinculados ao seus doc-section." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2101 +#: C/index.docbook:2191 msgid "" "Is the doc-comment using the correct markup (added #,% or ())? Check if the " "gtkdoc-fixxref warns about unresolvable xrefs." @@ -3705,26 +3732,26 @@ msgstr "" "Verifique se o gtkdoc-fixxref avisa sobre xrefs não resolvidos." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2107 +#: C/index.docbook:2197 msgid "A new class does not appear in the docs." msgstr "Uma nova classe não aparece nos documentos." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2108 +#: C/index.docbook:2198 msgid "" "Is the new page xi:included from <package>-docs.{xml,sgml}." msgstr "" -"A nova página foi \"xi:incluída\" do <pacote>-docs.{xml,sgml}" -"?" +"A nova página foi “xi:incluída” do <pacote>-docs.{xml,sgml}?" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2114 +#: C/index.docbook:2204 msgid "A new symbol does not appear in the docs." msgstr "Um novo símbolo não aparece nos documentos." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2115 +#: C/index.docbook:2205 msgid "" "Is the doc-comment properly formatted. Check for spelling mistakes in the " "begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable " @@ -3737,18 +3764,12 @@ msgstr "" "<pacote>-sections.txt em uma subseção pública." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2123 +#: C/index.docbook:2213 msgid "A type is missing from the class hierarchy." msgstr "Um tipo está faltando da hierarquia de classe." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2124 -#| msgid "" -#| "If the type is listed in <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." +#: C/index.docbook:2214 msgid "" "If the type is listed in <package>.hierarchy but " "not in xml/tree_index.sgml then double check that the " @@ -3758,33 +3779,32 @@ msgid "" msgstr "" "Se o tipo está listado no <pacote>.hierarchy, mas " "não em xml/tree_index.sgml, então certifique-se de que " -"o tipo está colocado corretamente no " -"<pacote>-sections.txt. Se a instância do tipo " -"(ex.: GtkWidget) não está listada ou incidentalmente marcada " -"como privada, ela não será mostrada." +"o tipo está colocado corretamente no <pacote>-sections.txt. Se a instância do tipo (ex.: GtkWidget) não está " +"listada ou incidentalmente marcada como privada, ela não será mostrada." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2133 +#: C/index.docbook:2223 msgid "I get foldoc links for all gobject annotations." msgstr "" "Obtenho links de seguimento de documentos para todas as anotações gobject." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2134 +#: C/index.docbook:2224 msgid "" "Check that xml/annotation-glossary.xml is xi:included " "from <package>-docs.{xml,sgml}." msgstr "" -"Verifique se xml/annotation-glossary.xml está \"xi:" -"incluído\" de <pacote>-docs.{xml,sgml}." +"Verifique se xml/annotation-glossary.xml está “xi:" +"incluído” de <pacote>-docs.{xml,sgml}." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2142 +#: C/index.docbook:2232 msgid "Parameter described in source code comment block but does not exist" msgstr "Parâmetro descrito no bloco de comentário do código fonte não existe" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2143 +#: C/index.docbook:2233 msgid "" "Check if the prototype in the header has different parameter names as in the " "source." @@ -3793,12 +3813,12 @@ msgstr "" "fonte." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2148 +#: C/index.docbook:2238 msgid "multiple \"IDs\" for constraint linkend: XYZ" -msgstr "Múltiplos \"IDs\" para restrições do fim do link XYZ" +msgstr "múltiplos “IDs” para restrições do fim do link XYZ" #. (itstool) path: seglistitem/seg -#: C/index.docbook:2149 +#: C/index.docbook:2239 msgid "" "Symbol XYZ appears twice in <package>-sections.txt file." @@ -3807,7 +3827,7 @@ msgstr "" "sections.txt." #. (itstool) path: seglistitem/seg -#: C/index.docbook:2152 +#: C/index.docbook:2242 msgid "" "Element typename in namespace '' encountered in para, but no template " "matches." @@ -3816,12 +3836,12 @@ msgstr "" "correspondeu." #. (itstool) path: chapter/title -#: C/index.docbook:2159 +#: C/index.docbook:2249 msgid "Tools related to gtk-doc" msgstr "Ferramentas relacionadas ao gtk-doc" #. (itstool) path: chapter/para -#: C/index.docbook:2161 +#: C/index.docbook:2251 msgid "" "GtkDocPlugin - a Trac " "GTK-Doc integration plugin, that adds API docs to a trac site and " @@ -3832,7 +3852,7 @@ msgstr "" "a um site trac e integra com a pesquisa do trac." #. (itstool) path: chapter/para -#: C/index.docbook:2166 +#: C/index.docbook:2256 msgid "" "Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " "tags in the API to determine the minimum required version." @@ -4258,7 +4278,7 @@ msgstr "" "Usar na Página de Título (e nas " "capas, se existirem) um título distinto em relação ao do Documento, e daqueles de versões anteriores (os quais " -"devem, na existência de algum, ser listados na seção \"Histórico\" do " +"devem, na existência de algum, ser listados na seção “Histórico” do " "Documento). Você pode usar o mesmo título de uma versão anterior se o editor " "original daquela versão conceder-lhe permissão." @@ -4656,11 +4676,6 @@ msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:527 C/fdl-appendix.xml:527 -#| msgid "" -#| "You may extract a single document from such a collection, and dispbibute " -#| "it individually under this License, provided you insert a copy of this " -#| "License into the extracted document, and follow this License in all other " -#| "respects regarding verbatim copying of that document." msgid "" "You may extract a single document from such a collection, and distribute it " "individually under this License, provided you insert a copy of this License " @@ -5292,7 +5307,7 @@ msgid "" msgstr "" "Usar na <_:link-1/> (e nas capas, se existirem) um título distinto em " "relação ao do <_:link-2/>, e daqueles de versões anteriores (os quais devem, " -"na existência de algum, ser listados na seção \"Histórico\" do Documento). " +"na existência de algum, ser listados na seção “Histórico” do Documento). " "Você pode usar o mesmo título de uma versão anterior se o editor original " "daquela versão conceder-lhe permissão." @@ -5794,8 +5809,37 @@ msgid "" msgstr "" "Se seu documento contiver exemplos não-triviais de código de programação, " "recomendamos publicar estes exemplos paralelamente, sob a licença de " -"software livre que você escolher, como por exemplo a <_:ulink-1/> (GNU " -"General Public License), para permitir seu uso em software livre." +"software livre que você escolher, como, por exemplo, a <_:ulink-1/>, para " +"permitir seu uso em software livre." + +#~ msgid "" +#~ "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 "" +#~ "Gerando os arquivos \"template\". " +#~ "gtkdoc-mktmpl cria uma quantidade de arquivos " +#~ "no subdiretório tmpl/, usando a " +#~ "informação coletada na primeira etapa. (Note que ele pode ser executado " +#~ "repetidas vezes e vai tentar garantir que nenhuma documentação será " +#~ "perdida, jamais.)" + +#~ msgid "" +#~ "Since GTK-Doc 1.9 the templates can be avoided. We encourage people to " +#~ "keep documentation in the code. 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 "" +#~ "Desde o GTK-Doc 1.9, os modelos (\"templates\") podem ser evitados. Nós " +#~ "encorajamos as pessoas a manter a documentação no código. " +#~ "gtkdocize possui suporte a uma opção que escolhe um makefile que ignora totalmente o " +#~ "uso de tmpl. Se você nunca alterou o arquivo em tmpl manualmente, por " +#~ "favor remova o diretório (ex.: do sistema de controle de versão)." #~ msgid "1.20" #~ msgstr "1.20" diff --git a/help/manual/sl/index.docbook b/help/manual/sl/index.docbook index 5d999ec..6b32cdc 100644 --- a/help/manual/sl/index.docbook +++ b/help/manual/sl/index.docbook @@ -81,10 +81,16 @@ - 1.24.1 - 30 May 2015 + 1.25.1 + 21 March 2016 + ss + development version + + + 1.25 + 21 March 2016 ss - development version + bug fixes, test cleanups 1.24 @@ -255,27 +261,6 @@ - - - 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.) - - - - 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). - - - - Generating the XML and HTML/PDF. @@ -293,7 +278,7 @@ document called <package>.pdf. - Files in xml/ and + Files in xml/ and html/ directories are always overwritten. One should never edit them directly. @@ -468,7 +453,7 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) Furthermore it is recommended that you have the following line inside - you configure.ac script. + your configure.ac script. This allows gtkdocize to automatically copy the macro definition for GTK_DOC_CHECK to your project. @@ -491,12 +476,12 @@ AC_CONFIG_MACRO_DIR(m4) Integration with automake - First copy the Makefile.am from the + 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. + 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. @@ -705,7 +690,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html The scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + hint GTK-Doc to skip over them. GTK-Doc comment block Limitations Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not + #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations. @@ -856,7 +841,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + XML tags inside doc-comments by putting (or ) in the variable MKDB_OPTIONS inside Makefile.am. @@ -957,7 +942,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + name given here should match the <FILE> tag in the <package>-sections.txt file. @@ -1187,7 +1172,7 @@ foo_get_bar(Foo *foo) Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list - of the supported tags can be found on + of the supported tags can be found on the wiki. @@ -1405,6 +1390,111 @@ typedef enum { + + + Inline program documentation + + You can document programs and their commandline interface using inline + documentation. + + + + Tags + + PROGRAM + + + + Defines the start of a program documentation. + + + + + + @short_description: + + + Defines a short description of the program. (Optional) + + + + + + @synopsis: + + + Defines the arguments, or list of arguments that the program can take. + (Optional) + + + + + + @see_also: + + + See Also manual page section. (Optional) + + + + + + @arg: + + + Argument(s) passed to the program and their description. (Optional) + + + + + + Description: + + + A longer description of the program. + + + + + + Returns: + + + Specificy what value(s) the program returns. (Optional) + + + + + + + + Example of program documentation. + Program documentation block + + + + + + Useful DocBook tags @@ -1667,17 +1757,17 @@ gtk_arrow_get_type In addition a few option elements are created in commented form. You can review these and enable them as you like. - + Optional part in the master document - --> + --> ]]> - + Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will @@ -1712,7 +1802,7 @@ gtk_arrow_get_type Blank lines are ignored and lines starting with a '#' are treated as comment lines. - + While the tags make the file look like xml, it is not. Please do not @@ -1855,15 +1945,15 @@ meep_app_get_type GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizing the documentation - + 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. - + GTK-Doc 1.9 @@ -1871,7 +1961,7 @@ meep_app_get_type When using xml instead of sgml, one can actually name the master document <package>-docs.xml. - + This version supports in Makefile.am. When this is enabled, the @@ -1879,21 +1969,21 @@ meep_app_get_type can be removed from the vcs. This only works nicely for projects that have a very regular structure (e.g. each .{c,h} pair will create new section). If one organize a project close to that updating a manually - maintained section file can be as simple as running + maintained section file can be as simple as running meld <package>-decl-list.txt <package>-sections.txt. - + 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 you source control system and haven't yet switched, just + checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. - + GTK-Doc 1.10 @@ -1946,7 +2036,7 @@ endif 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 any example that shows how the entity file is included + number. Below is an example that shows how the entity file is included and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. diff --git a/help/manual/sv/fdl-appendix.xml b/help/manual/sv/fdl-appendix.xml index d75087d..4c0f73b 100644 --- a/help/manual/sv/fdl-appendix.xml +++ b/help/manual/sv/fdl-appendix.xml @@ -14,237 +14,88 @@ 2000Free Software Foundation, Inc. - -
Free Software Foundation, Inc. 51 Franklin Street, +
Free Software Foundation, Inc. 51 Franklin Street, Suite 330, Boston, MA - 02110-1301 USA
- Everyone is permitted to copy and distribute verbatim copies of this - license document, but changing it is not allowed. - + 02110-1301 USA
. Alla är tillåtna kopiera och distribuera ordagranna kopior av detta licensdokument, men att ändra det är ej tillåtet. GNU Free Documentation License 0. BAKGRUND - - 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 effective freedom to copy and - redistribute it, with or without modifying it, either - commercially or noncommercially. Secondarily, this License - preserves for the author and publisher a way to get credit for - their work, while not being considered responsible for - modifications made by others. - + Syftet med denna licens är att göra en handbok, bok, eller annat praktiskt och användbart dokument fritt som i frihet: att försäkra var och en den faktiska friheten att kopiera och sprida det vidare, med eller utan förändringar, antingen kommersiellt eller ideellt. Sekundärt bevarar denna licens ett sätt för författaren och förläggaren att få ära för deras arbete utan att de anses vara ansvariga för förändringar gjorda av andra. - - This License is a kind of copyleft, which means - that derivative works of the document must themselves be free in - the same sense. It complements the GNU General Public License, - which is a copyleft license designed for free software. - + Denna Licens är en sorts copyleft, vilket betyder att derivativa verk av detta dokument själva måste vara fria på samma sätt. Den kompletterar GNU General Public License, som är en copyleft-licens utformad för fri programvara. Vi har utformat denna licens för att den skall användas för handböcker till fri programvara, eftersom fri programvara behöver fri dokumentation: ett fritt program bör ha en handbok som erbjuder samma friheter som programmet gör. Men denna licens är inte begränsad till programvaruhandböcker; den kan användas för vilket textverk som helst oavsett ämne eller huruvida det är en utgiven, tryckt bok. Vi rekommenderar denna licens huvudsakligen för alla verk vars syfte är instruktion eller referens. - TILLÄMPNINGSOMRÅDE OCH DEFINITIONER - - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be - distributed under the terms of this License. The - Document, below, refers to any such manual or - work. Any member of the public is a licensee, and is addressed - as you. - + 1. TILLÄMPNINGSOMRÅDE OCH DEFINITIONER + Denna licens [det engelska originalet] gäller för varje handbok eller annat verk, oavsett uttrycksform, som innehåller ett meddelande där upphovsrättsinnehavaren stadgat att verket kan spridas enligt villkoren i GNU Free Documentation License. Ett sådant meddelande ger en internationell frihet utan krav på ersättning och utan tidsbegränsning att använda verket under villkoren i denna licens [det engelska originalet]. Dokument nedan syftar på godtycklig handbok eller verk. Var och en är licenstagare och benämns som du. - - A Modified Version of the Document means any work - containing the Document or a portion of it, either copied - verbatim, or with modifications and/or translated into another - language. - + En förändrad version av dokumentet avser varje verk som innehåller dokumentet eller en del av det, antingen ordagranna kopior, eller med ändringar och/eller översatt till ett annat språk. - - A Secondary Section is a named appendix or a - front-matter section of the Document that deals exclusively - with the relationship of the publishers or authors of the - Document to the Document's overall subject (or to related - matters) and contains nothing that could fall directly within - that overall subject. (For example, if the Document is in part a - textbook of mathematics, a Secondary Section may not explain any - mathematics.) The relationship could be a matter of historical - connection with the subject or with related matters, or of - legal, commercial, philosophical, ethical or political position - regarding them. - + Ett sekundärt avsnitt är en märkt bilaga eller förord till dokumentet som exklusivt behandlar förhållandet mellan dokumentets förläggare eller författare och dokumentets huvudsakliga ämne (eller till relaterade ämnen) och som inte innehåller något som direkt faller under det huvudsakliga ämnet. (Således, om dokumentet delvis är en lärobok i matematik så får ett sekundärt avsnitt inte förklara någon matematik.) Förhållandet kan vara en historisk koppling till ämnet eller något relaterat, eller en juridisk, kommersiell, filosofisk, etisk eller politisk ställning till det. - - The Invariant Sections are certain Secondary Sections whose titles - are designated, as being those of Invariant Sections, in the - notice that says that the Document is released under this - License. - + De oföränderliga avsnitten är sekundära avsnitt vars titlar är angivna som oföränderliga avsnitt i meddelandet som stadgar att Dokument är utgivet under denna licens [det engelska originalet]. - - 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 that the Document is released under this - License. - + Omslagstexterna är speciella korta ordföljder som är listade som framsidestexter eller baksidestexter i meddelandet som stadgar att Dokument är utgivet under denna licens [det engelska originalet]. - - A Transparent copy of the Document means a machine-readable - copy, represented in a format whose specification is available - to the general public, whose contents can be viewed and edited - directly and straightforwardly with generic text editors or (for - images composed of pixels) generic paint programs or (for - drawings) some widely available drawing editor, and that is - suitable for input to text formatters or for automatic - translation to a variety of formats suitable for input to text - formatters. A copy made in an otherwise Transparent file format - whose markup has been designed to thwart or discourage - subsequent modification by readers is not Transparent. A copy - that is not Transparent is called - Opaque. - + En transparent kopia av Dokument är en maskinläsbar kopia, representerad i ett format vars specifikation finns tillgänglig för allmänheten, som lämpar sig för att revidera dokumentet på ett enkelt sätt med generella textredigeringsprogram eller (för pixelbaserade bilder) generella grafikprogram eller (för ritningar) något väl tillgängligt ritprogram, och som är passande som indata till textformaterare eller för automatisk konvertering till en mängd format som passar som indata till textformaterare. En kopia i ett för övrigt transparent filformat vars markeringar, eller avsaknad av markeringar, har ordnats för att hindra eller motverka att vidare förändring vidtas av läsare är inte transparent. En kopia som inte är transparent kallas opak. - Exempel på passande format för transparenta kopior innefattar ren ASCII utan markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript eller PDF utformat för mänsklig förändring. Exempel på transparenta bildformat innefattar PNG, XCF och JPG. Opaka format innefattar leverantörsspecifika format som bara kan läsas och editeras med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/eller verktyg för behandling inte finns allmänt tillgängliga, och den maskingenererade HTML, PostScript eller PDF som produceras av vissa ordbehandlare enbart avsett som utdata. + Exempel på passande format för transparenta kopior innefattar ren ASCII utan markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript eller PDF utformat för mänsklig förändring. Opaka format innefattar Postscript, PDF, leverantörsspecifika format som bara kan läsas och editeras med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/eller verktyg för behandling inte finns allmänt tillgängliga, och den maskingenererade HTML som produceras av vissa ordbehandlare enbart avsett som utdata. - - The Title Page means, for a printed book, the - title page itself, plus such following pages as are needed to - hold, legibly, the material this License requires to appear in - the title page. For works in formats which do not have any title - page as such, Title Page means the text near the - most prominent appearance of the work's title, preceding the - beginning of the body of the text. - + Titelsidan innebär, för en tryckt bok, titelsidan själv, och sådana därpå följande sidor som krävs för att göra det material som enligt denna licens skall synas på titelsidan läsbart. För verk i sådana format som inte har någon egentlig titelsida, avses med Titelsidan den text som är närmast den mest framstående förekomsten av verkets titel, föregående den huvudsakliga textmassan. 2. ORDAGRANN KOPIERING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that - you add no other conditions whatsoever to those of this - License. You may not use technical measures to obstruct or - control the reading or further copying of the copies you make or - distribute. However, you may accept compensation in exchange for - copies. If you distribute a large enough number of copies you - must also follow the conditions in section 3. - + Du äger kopiera och sprida Dokument på valfritt medium, antingen kommersiellt eller ideellt, förutsatt att denna licens [det engelska originalet], upphovsrättsklausul, och meddelandet som stadgar att GNU Free Documentation License gäller för dokumentet finns med på alla kopior, och att du inte lägger till några som helst andra villkor än de som ingår i denna licens. Du äger inte vidta tekniska åtgärder för att begränsa eller kontrollera läsande eller vidare kopiering av de kopior du skapar eller sprider. Dock äger du ta emot kompensation i utbyte mot kopior. Om du sprider tillräckligt många kopior måste du också följa villkoren i paragraf 3. Du äger också låna ut kopior, under samma villkor som ovan, och du äger visa kopior offentligt. 3. OMFATTANDE KOPIERING - - If you publish printed copies of the Document numbering more than 100, - and the Document's license notice requires Cover Texts, you must enclose - the copies in covers that carry, clearly and legibly, all these - Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also - clearly and legibly identify you as the publisher of these - copies. The front cover must present the full title with all - words of the title equally prominent and visible. You may add - other material on the covers in addition. Copying with changes - limited to the covers, as long as they preserve the title of the - Document and satisfy these - conditions, can be treated as verbatim copying in other - respects. - + Om du publicerar tryckta kopior (eller kopior i medier som normalt har tryckta omslag) av Dokument, i en upplaga överstigande 100 exemplar, och dokumentets licensmeddelande kräver Omslagstexterna, så måste du förse kopiorna med omslag som, klart och tydligt, visar alla omslagstexter: framsidestexter på framsidan och baksidestexter på baksidan. Båda omslagen måste klart och tydligt identifiera dig som utgivare av dessa kopior. Framsidan måste presentera dokumentets hela titel, med alla ord i titeln lika framträdande och synliga. Du äger lägga till ytterligare stoff på omslagen. Kopiering med förändringar gjorda bara på omslaget, så länge som de bevarar titeln för Dokument och i övrigt uppfyller dessa krav kan anses vara ordagrann kopiering i andra avseenden. Om de obligatoriska texterna för något omslag är för omfattande för att rymmas i läsbart skick skall du placera de första (så många som får plats) på det egentliga omslaget, och fortsätta med resten på de direkt intilliggande sidorna. - - If you publish or distribute Opaque copies of the Document numbering more than 100, - you must either include a machine-readable Transparent copy along with - each Opaque copy, or state in or with each Opaque copy a - publicly-accessible computer-network location containing a - complete Transparent copy of the Document, free of added - material, which the general network-using public has access to - download anonymously at no charge using public-standard network - protocols. If you use the latter option, you must take - reasonably prudent steps, when you begin distribution of Opaque - copies in quantity, to ensure that this Transparent copy will - remain thus accessible at the stated location until at least one - year after the last time you distribute an Opaque copy (directly - or through your agents or retailers) of that edition to the - public. - + Om du publicerar opaka kopior av Dokument i upplagor om mer än 100, måste du antingen bifoga en maskinläsbar transparent kopia med varje opak kopia, eller ange i eller med varje opak kopia en nätverksadress som är tillgänglig för den allmänna nätverksanvändande massan där man, med öppet standardiserade protokoll, anonymt och utan kostnad kan ladda ner en komplett transparent kopia av dokumentet, utan extra material. Om du väljer det senare alternativet, måste du vidta skäliga åtgärder, när du börjar sprida opaka kopior i kvantitet, för att denna transparenta kopia skall förbli tillgänglig på angivna platsen till åtminstone ett år efter den sista gången du spred en opak kopia (direkt eller via ombud eller återförsäljare) av den utgåvan till allmänheten. - - It is requested, but not required, that you contact the authors - of the Document well before - redistributing any large number of copies, to give them a chance - to provide you with an updated version of the Document. - + Det är önskvärt, men inte ett krav, att du kontaktar författarna till Dokument i god tid innan du sprider något större antal kopior, för att ge dem en chans att förse dig med en uppdaterad version av dokumentet. 4. FÖRÄNDRINGAR - - You may copy and distribute a Modified Version of the Document under the conditions of - sections 2 and 3 above, provided that you release - the Modified Version under precisely this License, with the - Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version - to whoever possesses a copy of it. In addition, you must do - these things in the Modified Version: - + Du äger kopiera och sprida en förändrad version av Dokument under de villkor som beskrivs i paragraf 2 och 3 av GNU Free Documentation License, förutsatt att du släpper den förändrade versionen under exakt denna licens, och att den förändrade versionen antar dokumentets roll, och således medger spridning och förändring av den förändrade versionen till envar som erhåller en kopia av den. Utöver detta måste du göra följande med den ändrade versionen: A - - Use in the Title - Page (and on the covers, if any) a title distinct - from that of the Document, and from those of - previous versions (which should, if there were any, be - listed in the History section of the Document). You may - use the same title as a previous version if the original - publisher of that version gives permission. - + På Titelsidan (och omslagen om det finns några) använda en titel skild från den som [original]Dokument har, och skild från tidigare versioners titel (som skall, om det finns några, finnas listade i historikavsnittet i dokumentet). Du äger använda samma titel som det föregående dokumentet om den ursprungliga utgivaren ger sitt tillstånd. B - - List on the Title - Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the - Modified Version, - together with at least five of the principal authors of - the Document (all of - its principal authors, if it has less than five). - + Lista på Titelsidan, som författare, en eller flera personer eller juridiska personer som ansvarat för förändringarna i förändrad version, tillsammans med minst fem av de huvudsakliga författarna av Dokument (alla dess huvudsakliga författare, om det har mindre än fem). C - - State on the Title - Page the name of the publisher of the Modified Version, as the - publisher. - + Ange namnet på utgivaren av Titelsidan, som utgivare, på förändrad version. D - - Preserve all the copyright notices of the Document. - + Bibehålla alla upphovsrättsklausuler för Dokument. @@ -258,24 +109,14 @@ F - - Include, immediately after the copyright notices, a - license notice giving the public permission to use the - Modified Version under - the terms of this License, in the form shown in the - Addendum below. - + Direkt efter upphovsrättsklausulerna innefatta ett meddelande som ger allmänheten tillstånd att använda förändrad version under villkoren i denna licens [det engelska originalet] i den form som visas i Tillägg nedan. G - - Preserve in that license notice the full lists of Invariant Sections and - required Cover - Texts given in the Document's license notice. - + I meddelandet om licensen bevara den fullständiga listan över oföränderliga avsnitten och obligatoriska Omslagstexterna som finns i dokumentets meddelande om licensen. @@ -289,257 +130,91 @@ I - - Preserve the section entitled History, and - its title, and add to it an item stating at least the - title, year, new authors, and publisher of the Modified Version as given on - the Title Page. If - there is no section entitled History in the - Document, create one - stating the title, year, authors, and publisher of the - Document as given on its Title Page, then add an item - describing the Modified Version as stated in the previous - sentence. - + Bevara avsnittet med titeln historik (History), bevara dess titel och lägg i avsnittet till en post med åtminstone titeln, året, nya författare och utgivaren av förändrad version så som angivet på Titelsidan. Om det inte finns något avsnitt med titeln historik (History) i Dokument så skapa en med titeln, året, författare och utgivaren av dokumentet så som det står på [original]dokumentets titelsida. Lägg sedan till en post som beskriver den förändrade versionen så som beskrivits ovan. J - - Preserve the network location, if any, given in the Document for public access - to a Transparent - copy of the Document, and likewise the network locations - given in the Document for previous versions it was based - on. These may be placed in the History - section. You may omit a network location for a work that - was published at least four years before the Document - itself, or if the original publisher of the version it - refers to gives permission. - + Bevara den nätverksadress, om det finns någon, angiven i Dokument till den allmänt tillgängliga transparenta kopian av dokumentet, och likaså nätverksadresserna till de föregående versioner som dokumentet baseras på. Dessa får placeras i avsnittet historik (History). Du äger utelämna en nätverksadress för ett verk som är publicerat mer än fyra år före dokumentet självt, eller om den ursprunglige utgivaren vars verk nätverksadressen hänvisar till ger sitt tillstånd. K - - In any section entitled Acknowledgements or - Dedications, preserve the section's title, - and preserve in the section all the substance and tone of - each of the contributor acknowledgements and/or - dedications given therein. - + För alla avsnitt med titlarna tillkännagivanden (Acknowledgements) eller dedikationer (Dedications), bevara titeln på avsnittet, och bevara allt innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda av varje bidragsgivare. L - - Preserve all the Invariant - Sections of the Document, unaltered in their - text and in their titles. Section numbers or the - equivalent are not considered part of the section titles. - + Bevara alla oföränderliga avsnitten i Dokument oförändrade till text och titel. Avsnittsnummer eller motsvarande anses inte tillhöra avsnittets titel. M - - Delete any section entitled - Endorsements. Such a section may not be - included in the Modified - Version. - + Radera varje avsnitt med titeln endossering (Endorsements). Ett sådant avsnitt får inte inkluderas i en förändrad version. N - - Do not retitle any existing section as - Endorsements or to conflict in title with - any Invariant - Section. - + Inte byta titel på något existerande avsnitt så att det blir endossering (Endorsements) eller så att titeln kan förväxlas med något oföränderligt avsnitt. - - If the Modified Version - includes new front-matter sections or appendices that qualify as - Secondary Sections and - contain no material copied from the Document, you may at your - option designate some or all of these sections as invariant. To - do this, add their titles to the list of Invariant Sections in the - Modified Version's license notice. These titles must be - distinct from any other section titles. - + Om förändrad version innehåller nya framsidestexter eller bilagor som är att anses som sekundära avsnitt och inte innehåller något material kopierat från dokumentet, så äger du, om du vill, benämna några eller samtliga av dessa som oföränderliga. För att göra detta, lägg deras titlar till listan över oföränderliga avsnitten i den förändrade versionens licensmeddelande. Dessa titlar måste vara skilda från alla andra avsnitts titlar. - - You may add a section entitled Endorsements, - provided it contains nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - + Du äger lägga till ett avsnitt med titeln endossering (Endorsements), förutsatt att det inte innehåller något annat än endosseringar för din förändrad version från olika aktörer -- till exempel, meddelanden om utförd korrekturläsning eller att texten har godkänts av en organisation som en officiell definition av en standard. - - You may add a passage of up to five words as a Front-Cover Text, and a passage - of up to 25 words as a Back-Cover Text, to the end of - the list of Cover Texts - in the Modified Version. - Only one passage of Front-Cover Text and one of Back-Cover Text - may be added by (or through arrangements made by) any one - entity. If the Document - already includes a cover text for the same cover, previously - added by you or by arrangement made by the same entity you are - acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - + Du äger lägga till ett textavsnitt på upp till fem ord som framsidestext, och ett textavsnitt på upp till 25 ord som baksidestext i listan över Omslagstexterna i förändrad version. Bara ett textavsnitt med framsidestexter och ett med baksidestexter får läggas till av (eller genom försorg av) en enda juridisk person. Om Dokument redan innehåller en omslagstext för något av omslagen, tidigare tillagd av dig eller genom försorg av samma juridiska person som du företräder, äger du inte lägga till en till, men du äger ändra den gamla med tillstånd från den tidigare utgivaren som lade till den förra. - - The author(s) and publisher(s) of the Document do not by this License - give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version . - + Författaren (författarna) och utgivaren (utgivarna) av Dokument ger inte via denna licens sitt tillstånd att använda sina namn för publicitet eller för att lägga till eller antyda endossering av någon förändrad version. 5. KOMBINERA DOKUMENT - - You may combine the Document - with other documents released under this License, under the - terms defined in section 4 - above for modified versions, provided that you include in the - combination all of the Invariant - Sections of all of the original documents, unmodified, - and list them all as Invariant Sections of your combined work in - its license notice. - + Du äger kombinera Dokument med andra dokument som är utgivna under denna licens, under de villkor som definieras i paragraf 4 av GNU Free Documentation License för förändrade versioner, förutsatt att du, i det kombinerade dokumentet, innefattar alla oföränderliga avsnitten från originaldokumenten, omodifierade, och listar dem som oföränderliga avsnitt i ditt kombinerade verk i dess licensklausul, och att du bevarar alla deras garantiavsägelseklausuler. - - The combined work need only contain one copy of this License, - and multiple identical Invariant - Sections may be replaced with a single copy. If there are - multiple Invariant Sections with the same name but different - contents, make the title of each such section unique by adding - at the end of it, in parentheses, the name of the original - author or publisher of that section if known, or else a unique - number. Make the same adjustment to the section titles in the - list of Invariant Sections in the license notice of the combined - work. - + Det kombinerade verket behöver bara innehålla en enstaka kopia av denna licens [engelska originalversionen], och flera identiska oföränderliga avsnitten kan ersättas med en kopia. Om det finns flera oföränderliga stycken med samma namn men olika innehåll, se till att titeln på varje sådant avsnitt är unik genom att i slutet på den, inom parentes, lägga till namnet på den ursprunglige författaren eller utgivaren av det avsnittet om dessa är kända, annars ett unikt nummer. Gör samma justeringar av titlarna i listan över oföränderliga avsnitt i licensklausulen i det kombinerade verket. - - In the combination, you must combine any sections entitled - History in the various original documents, - forming one section entitled History; likewise - combine any sections entitled Acknowledgements, - and any sections entitled Dedications. You must - delete all sections entitled Endorsements. - + I det kombinerade verket måste du kombinera alla avsnitt med titlarna historik (History) i de ursprungliga dokumenten, till ett avsnitt med titeln historik (History); på samma sätt skall alla avsnitt med titlarna tillkännagivanden (Acknowledgements), alla avsnitt med titlarna dedikationer (Dedications) kombineras. Du måste ta bort alla avsnitt med titlarna endossering (Endorsements). 6. SAMLINGAR AV DOKUMENT - - You may make a collection consisting of the Document and other documents - released under this License, and replace the individual copies - of this License in the various documents with a single copy that - is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - + Du äger skapa en samling bestående av Dokument och andra dokument som är släppta under GNU Free Documentation License, och ersätta individuella kopior i dokumenten av denna licens med en enda kopia [av den engelska originalversionen] som inkluderas i samlingen, förutsatt att du följer villkoren för ordagrann kopiering i denna licens för varje inkluderat dokument i alla andra avseenden. - - 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. - + Du äger lyfta ut ett dokument från en sådan samling, och sprida det enskilt under GNU Free Documentation License, förutsatt att du lägger till en kopia av denna licens [den engelska originalversionen] i det utlyfta dokumentet, och följer villkoren för ordagrann kopiering i denna licens för det utlyfta dokumentet i alla andra avseenden. 7. SAMMANSLAGNING MED OBEROENDE VERK - - A compilation of the Document or its derivatives with - other separate and independent documents or works, in or on a - volume of a storage or distribution medium, does not as a whole - count as a Modified Version - of the Document, provided no compilation copyright is claimed - for the compilation. Such a compilation is called an - aggregate, and this License does not apply to the - other self-contained works thus compiled with the Document , on - account of their being thus compiled, if they are not themselves - derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one - quarter of the entire aggregate, the Document's Cover Texts may - be placed on covers that surround only the Document within the - aggregate. Otherwise they must appear on covers around the whole - aggregate. - + En samling av Dokument eller av dess derivat med andra separata och oberoende dokument eller verk, på eller i en lagringsvolym eller ett spridningsmedium, kallas för en sammanslagning om den sammanslagna upphovsrätten inte används för att begränsa samlingens användares rättigheter som de enskilda dokumenten medger. När dokumentet ingår i en sådan sammanslagning, gäller inte denna licens de andra verken i samlingen som inte själva är deriverat av dokumentet. Om kravet på omslagstexter enligt paragraf 3 är tillämpligt på dessa kopior av dokumentet, så kan dokumentets omslagstexter, om dokumentet utgör mindre än en fjärdedel av hela samlingen, placeras på det omslag som omger dokumentet inuti samlingen, eller den elektroniska motsvarigheten till omslag om dokumentet är i elektronisk form. Annars måste de synas på det omslag som omger hela samlingen. 8. ÖVERSÄTTNING - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with - translations requires special permission from their copyright - holders, but you may include translations of some or all - Invariant Sections in addition to the original versions of these - Invariant Sections. You may include a translation of this - License provided that you also include the original English - version of this License. In case of a disagreement between the - translation and the original English version of this License, - the original English version will prevail. - + Översättning anses vara en sorts förändring, så du äger sprida översättningar av Dokument enligt de villkor som sätts i paragraf 4. oföränderliga avsnitten som ersätts med översättningar kräver tillstånd från deras upphovsrättsinnehavare, men du äger inkludera översättningar av alla eller vissa av dessa oföränderliga avsnitt tillsammans med originalversionerna av dessa oföränderliga avsnitt. Du äger inkludera en översättning av denna licens, och alla licensklausuler i dokumentet, och alla garantiavsägelser, förutsatt att du också innefattar den engelska originalversionen av denna licens och originalversionerna av dessa klausuler. Skulle det finnas skillnader mellan översättningen och originalversionen av denna licens eller någon klausul så gäller originalversionen. 9. UPPHÖRANDE - - You may not copy, modify, sublicense, or distribute the Document except as expressly - provided for under this License. Any other attempt to copy, - modify, sublicense or distribute the Document is void, and will - automatically terminate your rights under this License. However, - parties who have received copies, or rights, from you under this - License will not have their licenses terminated so long as such - parties remain in full compliance. - + Du äger inte kopiera, förändra, omlicensiera eller sprida Dokument annat än enligt villkoren i GNU Free Documentation License. Alla övriga försök att kopiera, modifiera, omlicensiera, eller sprida dokumentet är ogiltiga och kommer automatiskt medföra att du förlorar dina rättigheter enligt denna licens. Tredje man som har mottagit kopior eller rättigheter från dig enligt dessa licensvillkor kommer dock inte att förlora sina rättigheter så länge de följer licensvillkoren. 10. FRAMTIDA VERSIONER AV DENNA LICENS - - The Free Software - Foundation may publish new, revised versions of the GNU - Free Documentation License from time to time. Such new versions - will be similar in spirit to the present version, but may differ - in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. - + Free Software Foundation kan publicera nya, reviderade versioner av GNU Free Documentation License då och då. Sådana nya versioner kommer att vara likadana i andemening som den nuvarande versionen, men kan skilja i detalj för att behandla nya problem eller angelägenheter. Se http://www.gnu.org/copyleft/. - - Each version of the License is given a distinguishing version - number. If the Document - specifies that a particular numbered version of this License - or any later version applies to it, you have the - option of following the terms and conditions either of that - specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by - the Free Software Foundation. - + Varje version av licensen ges ett unikt versionsnummer. Om Dokument stadgar att en specifik numrerad version av denna licens eller valfri senare version gäller för det, så äger du rätten att följa villkoren enligt antingen den angivna versionen eller vilken senare version som helst som publicerats (inte som utkast) av Free Software Foundation. Om dokumentet inte anger en version av denna licens, äger du välja vilken version som helst som publicerats (inte som utkast) av Free Software Foundation. @@ -547,34 +222,12 @@ För att använda GNU Free Documentation License för ett dokument du har skrivit, inkludera en kopia av licensen [det engelska originalet] i dokumentet och placera följande copyrightklausul omedelbart efter titelsidan:
- Copyright (c) ÅRTAL DITT NAMN. - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation - License, Version 1.1 or any later version published by the - Free Software Foundation; with the Invariant Sections being LIST - THEIR TITLES, with the Front-Cover Texts being LIST, - and with the Back-Cover - Texts being LIST. A copy of the license is included in - the section entitled GNU Free Documentation - License. - + Copyright © YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the oföränderliga avsnitten being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled GNU Free Documentation License.
- - If you have no Invariant - Sections, write with no Invariant Sections - instead of saying which ones are invariant. If you have no - Front-Cover Texts, write - no Front-Cover Texts instead of - Front-Cover Texts being LIST; likewise for Back-Cover Texts. - + Om du inte har några oföränderliga avsnitten, skriv with no Invariant Sections istället för att ange vilka som är oföränderliga. Om du inte har några Front-Cover Texts, skriv no Front-Cover Texts istället för Front-Cover Texts being LIST; såväl som för Back-Cover Texts. - - If your document contains nontrivial examples of program code, - we recommend releasing these examples in parallel under your - choice of free software license, such as the GNU General Public - License, to permit their use in free software. - + Om ditt dokument innehåller icke-triviala exempel med programkod, så rekommenderar vi att du släpper dessa exempel parallellt under en, av dig vald, fri programvarulicens, som till exempel GNU General Public License, för att möjliggöra deras användning i fri programvara. diff --git a/help/manual/sv/index.docbook b/help/manual/sv/index.docbook index 82b54bf..daff145 100644 --- a/help/manual/sv/index.docbook +++ b/help/manual/sv/index.docbook @@ -13,46 +13,13 @@ 1.24.1 Användarhandbok för utvecklare med användningsinstruktioner för GTK-Doc. - - Chris - Lyttle - -
- chris@wilddev.net -
- - - - Dan - Mueth - -
- d-mueth@uchicago.edu -
- - - - Stefan - Sauer (Kost) - -
- ensonic@users.sf.net -
- - + Chris Lyttle
chris@wilddev.net
+ Dan Mueth
d-mueth@uchicago.edu
+ Stefan Sauer (Kost)
ensonic@users.sf.net
- - GTK-Doc project -
gtk-doc-list@gnome.org
- - - 2000, 2005 - Dan Mueth and Chris Lyttle - - - 2007-2015 - Stefan Sauer (Kost) - + GTK-Doc-projektet
gtk-doc-list@gnome.org
 + 2000, 2005 Dan Mueth and Chris Lyttle + 2007-2015 Stefan Sauer (Kost) @@ -166,139 +98,43 @@ Introduktion - - This chapter introduces GTK-Doc and gives an overview of what it is and - how it is used. - + Detta kapitel introducerar GTK-Doc och ger en överblick över vad det är och hur det används. Vad är GTK-Doc? - - GTK-Doc is used to document C code. It is typically used to document the public - API of libraries, such as the GTK+ and GNOME libraries. But it can also be - used to document application code. - + GTK-Doc används för att dokumentera C-kod. Det används vanligen för att dokumentera det publika API:t för bibliotek, så som GTK+- och GNOME-biblioteken. Men det kan också användas för att dokumentera programkod. Hur fungerar GTK-Doc? - - GTK-Doc works by using documentation of functions placed inside the source files in - specially-formatted comment blocks, or documentation added to the template files - which GTK-Doc uses (though note that GTK-Doc will only document functions that - are declared in header files; it won't produce output for static functions). - + GTK-Doc fungerar så att det använder dokumentation för funktioner placerad inuti källkodsfilerna i speciellt formaterade kommentarsblock, eller dokumentation som lagts till i mallfilerna som GTK-Doc använder (notera dock att GTK-Doc endast kommer att dokumentera funktioner som deklarerats i huvudfiler; det kommer inte att producera utdata för statiska funktioner). - - GTK-Doc consists of a number of perl scripts, each performing a different step - in the process. - + GTK-Doc består av ett antal perl-skript som vart och ett utför olika steg i processen. - - There are 5 main steps in the process: - + Det finns 5 huvudsteg i processen: - - 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). - - - - - - Gathering information about the code. - - gtkdoc-scan scans the header files of the - code looking for declarations of functions, macros, enums, structs, and unions. - It creates the file <module>-decl-list.txt containing a list of the - declarations, placing them into sections according to which header file they - are in. On the first run this file is copied to <module>-sections.txt. - The author can rearrange the sections, and the order of the - declarations within them, to produce the final desired order. - The second file it generates is <module>-decl.txt. - This file contains the full declarations found by the scanner. If for - some reason one would like some symbols to show up in the docs, where - the full declaration cannot be found by the scanner or the declaration - should appear differently, one can place entities similar to the ones in - <module>-decl.txt into <module>-overrides.txt. - - - gtkdoc-scangobj can also be used to dynamically query a library about - any GObject subclasses it exports. It saves information about each - object's position in the class hierarchy and about any GObject properties - and signals it provides. - - - gtkdoc-scanobj should not be used anymore. - It was needed in the past when GObject was still GtkObject inside gtk+. - + 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). - - 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.) - - - - 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). - - + Samla ihop information om koden. gtkdoc-scan söker genom huvudfilerna för koden och letar efter deklarationer av funktioner, makron, uppräkningar, strukturer och unioner. Det skapar sedan filen <module>-decl-list.txt som innehåller en lista över deklarationerna, och placerar dem i avsnitt efter vilken huvudfil de finns i. Vid första körningen kommer denna fil att kopieras till <module>-sections.txt. Författaren kan, genom att omarrangera avsnitten och ändra ordningen för deklarationerna inom dem, framställa den önskade, slutgiltiga ordningen. Den andra filen det genererar är <module>-decl.txt. Denna fil innehåller de fullständiga deklarationerna som hittats av detektorn. Om man av något skäl vill att vissa symboler ska visas i dokumentation då den fullständiga deklarationen inte kan hittas av detektorn, eller om deklarationen ska visas annorlunda, kan man placera rader liknande de som finns i <module>-decl.txt i <module>-overrides.txt. + gtkdoc-scangobj kan också användas för att dynamiskt fråga ett bibliotek om vilka GObject-underklasser det exporterar. Det sparar information om varje objekts position i klasshierarkin och om vilka GObject-egenskaper och signaler det tillhandahåller. + gtkdoc-scanobj bör inte användas längre. Det behövdes tidigare när GObject fortfarande var GtkObject inuti gtk+. - - 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. - - - 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. - - - Files in xml/ and - html/ directories are always - overwritten. One should never edit them directly. - + Generera XML och HTML/PDF. gtkdoc-mkdb förvandlar mallfilerna till XML-filer i underkatalogen xml/. Om källkoden innehåller dokumentation över funktioner i speciella kommentarsblock, så kommer denna att sammanfogas här. Om det inte finns några tmpl-filer som används så kommer det endast att läsa dokumentation från källkoden och introspektionsdata. + gtkdoc-mkhtml förvandlar XML-filer till HTML-filer i underkatalogen html/. På samma sätt förvandlar gtkdoc-mkpdf XML-filerna till ett PDF-dokument kallat <package>.pdf. + Filer i xml/- och html/-katalogerna skrivs alltid över. Man bör aldrig redigera dem direkt. - - Fixing up cross-references between documents. - - After installing the HTML files, gtkdoc-fixxref can be run to fix up any - cross-references between separate documents. For example, the GTK+ - documentation contains many cross-references to types documented in the GLib manual. - - When creating the source tarball for distribution, gtkdoc-rebase - turns all external links into web-links. When installing distributed (pregenerated) docs - the same application will try to turn links back to local links - (where those docs are installed). - + Fixa korsreferenser mellan dokument. Efter att ha installerat HTML-filerna kan gtkdoc-fixxref köras för att fixa korsreferenser mellan separata dokument. Till exempel GTK+-dokumentationen innehåller många korsreferenser till typer som dokumenterats i GLib-manualen. När tar-arkivet med källkod skapas för distribution, förvandlar gtkdoc-rebase alla externa länkar till webblänkar. När (förgenererad) distribuerad dokumentation installeras kommer samma program att försöka att förvandla länkarna tillbaka till lokala länkar (i de fall där dokumentationen finns installerad). @@ -309,83 +145,46 @@ Krav - - Perl v5 - the main scripts are in Perl. - - - xsltproc - the xslt processor from libxslt - xmlsoft.org/XSLT/ - - - docbook-xsl - the docbook xsl stylesheets - sourceforge.net/projects/docbook/files/docbook-xsl - - - Python - optional - for gtkdoc-depscan - - - One of source-highlight, highlight or - vim - optional - used for syntax highlighting of examples - + Perl v5 - huvudskripten är skrivna i Perl. + xsltproc - xslt-processorn från libxslt xmlsoft.org/XSLT/ + docbook-xsl - docbook xsl-stilmallar sourceforge.net/projects/docbook/files/docbook-xsl + Python - valfritt - för gtkdoc-depscan + Endera av source-highlight, highlight eller vim - valfritt - används för syntaxfärgning av exempel Om GTK-Doc - - (FIXME) - + (FIXME) - - (History, authors, web pages, mailing list, license, future plans, - comparison with other similar systems.) - + (Historia, författare, webbsidor, sändlistor, licens, framtida planer, jämförelse med andra liknande system.) Om denna handbok - - (FIXME) - + (FIXME) - - (who it is meant for, where you can get it, license) - + (vem är den avsett för, var kan du få tag i den, licens) - Setting up your project - - - 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. - + Att ställa in ditt projekt + + 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. - Setting up a skeleton documentation + Att ställa in en skelettstruktur för dokumentation - - 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. - + 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. - - This can then look as shown below: - Example directory structure - Detta kan se ut enligt nedan: Exempel på katalogstruktur + meep/ docs/ reference/ @@ -394,1628 +193,1082 @@ meep/ src/ libmeep/ meeper/ -]]> - - + + - Integration with autoconf + Integrering med autoconf - - Very easy! Just add one line to your configure.ac script. - + Väldigt enkelt! Bara lägg till en rad till ditt configure.ac-skript. - Integration with autoconf - Integrering med autoconf + # check for gtk-doc GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) -]]> + - - 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 - 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 + # check for gtk-doc m4_ifdef([GTK_DOC_CHECK], [ GTK_DOC_CHECK([1.14],[--flavour no-tmpl]) ],[ AM_CONDITIONAL([ENABLE_GTK_DOC], false) ]) -]]> - - + + - - 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: - + 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=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] + --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] - - 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). - + 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). - - 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. - + 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. Förberedelse för gtkdocize - AC_CONFIG_MACRO_DIR(m4) -]]> + - - After all changes to configure.ac are made, update - the configure file. This can be done by re-running - autoreconf -i or autogen.sh. - + 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. - Integration med automake + Integrering med automake - - 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. - + 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. - - 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. - + 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. - Integration with autogen + Integrering med autogen - - 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. - + 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. - Running gtkdocize from autogen.sh - Köra gtkdocize från autogen.sh + gtkdocize || exit 1 -]]> + - - 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. - + 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. - - 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). - + 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). - Running the doc build + Att köra dokumentationsbygget + 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. - 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 - Att köra dokumentationsbygget + ./autogen.sh --enable-gtk-doc make -]]> + - - 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. - + 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. - Integration with version control systems + Integrering med versionshanteringssystem - - 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. - + 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. - Integration with plain makefiles or other build systems + Integrering med vanliga makefiler eller andra byggsystem - - 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 in own makefiles (or other build tools). - + 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). - Documentation build steps - Byggsteg för dokumentation + DOC_MODULE=meep -// sources have changed -gtkdoc-scan --module=$(DOC_MODULE) +// källkod har ändrats +gtkdoc-scan --module=$(DOC_MODULE) <källkodskatalog> gtkdoc-scangobj --module=$(DOC_MODULE) -gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir= -// xml files have changed +gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<källkodskatalog> +// xml-filer har ändrats mkdir html -cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml +cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html -]]> + - - One will need to look at the Makefile.am and - gtk-doc.mak to pick the extra options needed. - + Man kommer att behöva titta i Makefile.am och gtk-doc.mak för att plocka ut de extra flaggor som behövs. - 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 - 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) -# Create the doc-libmeep target. +# Skapa målet doc-libmeep. gtk_doc_add_module( libmeep ${CMAKE_SOURCE_DIR}/libmeep XML meep-docs.xml LIBRARIES libmeep ) -# Build doc-libmeep as part of the default target. Without this, you would -# have to explicitly run something like `make doc-libmeep` to build the docs. +# Bygg doc-libmeep som standardmålet. Utan detta måste du uttryckligen +# köra något i stil med `make doc-libmeep` för att bygga dokumentationen. add_custom_target(documentation ALL DEPENDS doc-libmeep) -# Install the docs. (This assumes you're using the GNUInstallDirs CMake module -# to set the CMAKE_INSTALL_DOCDIR variable correctly). +# Installera dokumentationen. (Detta förutsätter att du använder CMake-modulen +# GNUInstallDirs för att ställa in variabeln CMAKE_INSTALL_DOCDIR korrekt). install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) -]]> - - + + - Documenting the code + Att dokumentera koden - - GTK-Doc uses source code comment with a special syntax for code documentation. - Further it retrieves information about your project structure from other - sources. During the next section you will find all information about the - syntax of the comments. - + 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. - 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. - + 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. - - 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. - GTK-Doc comment block - 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 + #ifndef __GTK_DOC_IGNORE__ /* unparseable code here */ #endif -]]> - - + + - Limitations - - Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not - #if !defined(__GTK_DOC_IGNORE__) or other combinations. - + Begränsningar + Notera att GTK-Doc har stöd för #ifndef(__GTK_DOC_IGNORE__) men inte #if !defined(__GTK_DOC_IGNORE__) eller andra kombinationer. - Documentation comments + Dokumentationskommentarer - - A multiline comment that starts with an additional '*' marks a - documentation block that will be processed by the GTK-Doc tools. - GTK-Doc comment block - En flerradskommentar som börjar med en extra ”*” markerar ett dokumentationsblock som kommer att hanteras av GTK-Doc-verktygen. GTK-Doc-kommentarsblock + /** - * identifier: - * documentation ... + * identifierare: + * dokumentation … */ -]]> - - + + - - The 'identifier' is one line with the name of the item the comment is - related to. The syntax differs a little depending on the item. - (TODO add table showing identifiers) - + 'Identifierare' är en rad med namnet på det objekt som kommentaren är relaterad till. Syntaxen skiljer sig lite beroende på objekt. (TODO lägg till tabell som visar identifierare) - - 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). - + Blocket 'dokumentation' skiljer sig också för varje symboltyp. Symboltyper som får parametrar så som funktioner eller makron har en parameterbeskrivning först, åtföljd av en blankrad (bara en ”*”). Efteråt följer den detaljerade beskrivningen. Alla rader (utanför programlistningar och CDATA-avsnitt) som endast innehåller ” *” (blanksteg-asterisk) konverteras till styckeavgränsare. Om du inte vill ha en styckeavgränsare, ändra till ” * ” (blanksteg-asterisk-blanksteg-blanksteg). Detta är användbart i förformaterad text (kodlistningar). - - When documenting code, describe two aspects: - + När du dokumenterar kod, beskriv två aspekter: - - What it is: The name for a class or function can sometimes - be misleading for people coming from a different background. - + Vad är detta: Namnet på en klass eller en funktion kan ibland vara vilseledande för personer med annan bakgrund. - - What it does: Tell about common uses. Put it in relation - with the other API. - + Vad gör det: Berättar om vanliga användningsfall. Sätter det i relation med det andra API:t. - - + - - One advantage of hyper-text over plain-text is the ability to have links - in the document. Writing the correct markup for a link can be tedious - though. GTK-Doc comes to help by providing several useful abbreviations. - + En fördel med hypertext framför vanlig text är möjligheten att ha länkar i dokumentet. Att skriva korrekta taggar för en länk kan dock vara tröttsamt. GTK-Doc hjälper då till med att tillhandahålla flera användbara förkortningar. - - Use function() to refer to functions or macros which take arguments. - + Använd funktion() för att referera till funktioner eller makron som tar argument. - - Use @param to refer to parameters. Also use this when referring to - parameters of other functions, related to the one being described. - + Använd @param för att referera till parametrar. Använd också detta när du refererar till parametrar för andra funktioner, relaterade till den som beskrivs. - - Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS. - + Använd %konstant för att referera till en konstant, t.ex. %G_TRAVERSE_LEAFS. - - Use #symbol to refer to other types of symbol, e.g. structs and - enums and macros which don't take arguments. - + Använd #symbol för att referera till andra typer av symboler, t.ex. strukturer eller uppräkningar och makron som inte tar argument. - - Use #Object::signal to refer to a GObject signal. - + Använd #Objekt::signal för att referera till en GObject-signal. - - Use #Object:property to refer to a GObject property. - + Använd #Objekt:egenskap för att referera till en GObject-egenskap. - - Use #Struct.field to refer to a field inside a structure and - #GObjectClass.foo_bar() to refer to a vmethod. - + Använd #Struktur.fält för att referera till ett fält inuti en struktur och #GObjectKlass.foo_bar() för att referera till en virtuell metod. - - + - - If you need to use the special characters '<', '>', '()', '@', - '%', or '#' in your documentation without GTK-Doc changing them you - can use the XML entities "&lt;", "&gt;", "&lpar;", - "&rpar;", "&commat;", "&percnt;" and "&num;" - respectively or escape them with a backslash '\'. - + Om du behöver använda specialtecken ”<”, ”>”, ”()”, ”@”, ”%” eller ”#” i din dokumentation utan att GTK-Doc ändrar dem kan du använda XML-entiteterna ”&lt;”, ”&gt;”, ”&lpar;”, ”&rpar;”, ”&commat;”, ”&percnt;” respektive ”&num;” eller använda kontrollsekvensen ”\”. - - DocBook can do more than just links. One can also have lists, - examples, headings, and images. As of version 1.20, the - preferred way is to use a subset of the basic text formatting - syntax called - Markdown. - 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. - + DocBook kan mer än bara länkar. Du kan också ha listor, exempel, rubriker och bilder. Från och med version 1.20, är det föredragna sättet att använda en delmängd av den grundläggande textformateringssyntaxen som kallas Markdown. Äldre GTK-Doc-versioner kommer dokumentation som inkluderar markdown att renderas som den är. Till exempel kommer listobjekt att visas som att de börjar med ett bindestreck. - - 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. - + Då markdown numera föredras kan du blanda båda. En begränsning här är att du kan använda docbook-xml inuti markdown, men markdown inuti docbook-xml stöds inte. - - 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. - + I äldre GTK-Doc-versioner var du tvungen, om du ville ha stöd för ytterligare formatering, att aktivera användningen av docbook-XML-taggar inuti dok-kommentarer genom att lägga till (eller ) i variabeln MKDB_OPTIONS inuti Makefile.am. - GTK-Doc comment block using Markdown - GTK-Doc-kommentarsblock som använder Markdown + /** - * identifier: + * Identifierare: * - * documentation paragraph ... + * stycke med dokumentation … * - * # Sub Heading # + * # Underrubrik # * - * ## Second Sub Heading + * ## Underunderrubrik * - * # Sub Heading With a Link Anchor # {#heading-two} + * # Underrubrik med länkankare # {#andra-rubriken} * - * more documentation: + * mer dokumentation: * - * - list item 1 + * - listobjekt 1 * - * Paragraph inside a list item. + * Stycke inuti listobjekt. * - * - list item 2 + * - listobjekt 2 * - * 1. numbered list item + * 1. numrerat listobjekt * - * 2. another numbered list item + * 2. ytterligare ett numrerat listobjekt * - * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/) + * Ett annat stycke. [En länk till GNOME:s webbplats](http://www.gnome.org/) * - * ![an inline image](plot-result.png) + * ![en bild](resultatgraf.png) * - * [A link to the heading anchor above][heading-two] + * [En länk till rubrikankaret ovan][andra-rubriken] * - * A C-language example: - * |[ - * GtkWidget *label = gtk_label_new ("Gorgeous!"); + * Ett C-exempel: + * |[<!-- language="C" --> + * GtkWidget *label = gtk_label_new ("Vackert!"); * ]| */ -]]> + - - More examples of what markdown tags are supported can be found in the - GTK+ Documentation Markdown Syntax Reference. - + Fler exempel på vilka markdown-taggar som stöds hittas i Referensen för GTK+-dokumentationens markdown-syntax. - - As already mentioned earlier GTK-Doc is for documenting public API. Thus - one cannot write documentation for static symbols. Nevertheless it is good - to comment those symbols too. This helps other to understand you code. - Therefore we recommend to comment these using normal comments (without the - 2nd '*' in the first line). - If later the function needs to be made public, all one needs to do is to - add another '*' in the comment block and insert the symbol name at the - right place inside the sections file. - + 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. - Documenting sections + Dokumentationsavsnitt - - Each section of the documentation contains information about one class - or module. To introduce the component one can write a section block. - The short description is also used inside the table of contents. - All the @fields are optional. - + Varje avsnitt av dokumentation innehåller information om en klass eller en modul. För att introducera komponenten kan man skriva ett avsnittsblock. Den korta beskrivningen används också i innehållsförteckningen. Alla @fälten är valfria. - Section comment block - Kommentarsblock för avsnitt + /** * SECTION:meepapp - * @short_description: the application class - * @title: Meep application + * @short_description: programklassen + * @title: Meep-programmet * @section_id: * @see_also: #MeepSettings * @stability: Stable * @include: meep/app.h * @image: application.png * - * The application class handles ... + * Programklassen hanterar … */ -]]> + - SECTION:<name> + SECTION:<namn> - - 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. - + Namnet länkar till avsnittsdokumentationen för respektive del i filen <paket>-sections.txt. Namnet som anges här bör matcha taggen <FILE> i filen <paket>-sections.txt. @short_description - - 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. - + En enradsbeskrivning av avsnittet som senare kommer att visas efter länkar i innehållsförteckningen och lägst upp på avsnittssidan. @title - - The section title defaults to <name> from the SECTION - declaration. It can be overridden with the @title field. - + Avsnittstiteln är som standard <namn> från SECTION-deklarationen. Den kan åsidosättas med fältet @title. @section_id - - Overrides the use of title as a section identifier. For GObjects - the <title> is used as a section_id and for other sections - it is <MODULE>-<title>. - + Åsidosätter användningen av titeln som avsnittsidentifierare. För GObjects används <title> som ett section_id och för andra avsnitt är det <MODULE>-<title>. @see_also - - A list of symbols that are related to this section. - + En lista över symboler som är relaterade till detta avsnitt. @stability - - An informal description of the stability level this API has. - We recommend the use of one of these terms: - + En informell beskrivning över stabiliteten för detta API. Vi rekommenderar att använda en av dessa termer: - - Stable - - The intention of a Stable interface is to enable arbitrary - third parties to develop applications to these interfaces, - release them, and have confidence that they will run on all - minor releases of the product (after the one in which the - interface was introduced, and within the same major release). - Even at a major release, incompatible changes are expected - to be rare, and to have strong justifications. - + Stable - Avsikten med ett stabilt gränssnitt är att möjliggöra för tredje parter att utveckla program mot dessa gränssnitt, släppa dem och vara säkra på att de kommer att köra på alla programfixversioner av produkten (efter den i vilken gränssnittet introducerats, och inom samma huvudversion). Även vid en ny huvudversion förväntas inkompatibla ändringar vara få och vara väl motiverade. - - Unstable - - Unstable interfaces are experimental or transitional. - They are typically used to give outside developers early - access to new or rapidly changing technology, or to provide - an interim solution to a problem where a more general - solution is anticipated. - No claims are made about either source or binary - compatibility from one minor release to the next. - + Unstable - Instabila gränssnitt är experimentella eller i en övergångsfas. De används typiskt för att ge utomstående utvecklare tidig tillgång till ny eller snabbt föränderlig teknologi, eller för att tillhandahålla provisoriska lösningar för ett problem där en mer generell lösning förutses. Inga påståenden görs om endera källkods- eller binärkompatibilitet från en programfixversion till nästa. - - Private - - An interface that can be used within the GNOME stack - itself, but that is not documented for end-users. Such - functions should only be used in specified and documented - ways. - + Private - Ett gränssnitt som kan användas inom GNOME-stacken i sig, men som inte dokumenterats för slutanvändare. Sådana funktioner bör endast användas på angivna och dokumenterade sätt. - - Internal - - An interface that is internal to a module and does not - require end-user documentation. Functions that are - undocumented are assumed to be Internal. - + Internal - ett gränssnitt som är internt för en modul och inte behöver slutanvändardokumentation. Funktioner som är odokumenterade förutsätts vara interna. - - + @include - - The #include files to show in the section - synopsis (a comma separated list), overriding the global - value from the section - file or command line. This item is optional. - + #include-filerna som ska visas i avsnittssammanfattningen (en kommaavgränsad lista), vilket åsidosätter det globala värdet från avsnittsfilen eller kommandoraden. Detta objekt är valfritt. @image - - The image to display at the top of the reference page for this - section. This will often be some sort of a diagram to illustrate - the visual appearance of a class or a diagram of its relationship - to other classes. This item is optional. - + Bilden som ska visas längst upp på referenssidan för detta avsnitt. Detta kommer ofta att vara någon form av diagram för att illustrera det visuella utseendet för en klass eller ett diagram över dess relationer med andra klasser. Detta objekt är valfritt. - - To avoid unnecessary recompilation after doc-changes put the section - docs into the c-source where possible. - + För att undvika onödig omkompilering efter dokumentationsändringar, placera avsnittsdokumentationen i c-källkoden där möjligt. - Documenting symbols + Dokumentationssymboler - - Each symbol (function, macro, struct, enum, signal and property) is - documented in a separate block. The block is best placed close to the - definition of the symbols so that it is easy to keep them in sync. - Thus functions are usually documented in the c-source and macros, - structs and enums in the header file. - + Varje symbol (funktion, makro, struktur, uppräkning, signal och egenskap) är dokumenterad i ett separat block. Blocket placeras bäst intill definitionen av symbolerna så att det är enkelt att hålla dem synkroniserade. Därför dokumenteras funktioner vanligtvis i c-källkoden och makron, strukturer och uppräkningar i huvudfilen. - General tags + Generella taggar - - You can add versioning information to all documentation elements to tell - when an API was introduced, or when it was deprecated. - + Du kan lägga till versioneringsinformation i alla dokumentationselement för att berätta när ett API introducerats eller blev föråldrat. - Versioning Tags + Versioneringstaggar Since: - - Description since which version of the code the API is available. - + Beskrivning över från och med vilken version av koden som API:t är tillgängligt. Deprecated: - - Paragraph denoting that this function should no be used anymore. - The description should point the reader to the new API. - + Stycke som betecknar att denna funktion inte bör användas längre. Beskrivningen bör peka läsaren vidare till det nya API:t. - - 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. - + Du kan också lägga till stabilitetsinformation för alla dokumentationselement för att indikera huruvida API-stabilitet är garanterad för dem för alla framtida programfix-versioner av projektet. - - The default stability level for all documentation elements can be set - by passing the argument to - gtkdoc-mkdb with one of the values below. - + Standardvärdet för stabilitetsnivån för alla dokumentations element kan ställas in genom att ange argumentet till gtkdoc-mkdb med endera av värdena nedan. - Stability Tags + Stabilitetstaggar Stability: Stable - - Mark the element as stable. This is for public APIs which are - guaranteed to remain stable for all future minor releases of the - project. - + Markera elementet som stabilt. Detta är för publika API:er som är garanterade att hållas stabila i alla framtida programfix-versioner av projektet. Stability: Unstable - - Mark the element as unstable. This is for public APIs which are - released as a preview before being stabilised. - + Markera elementet som instabilt. Detta är för publika API:er som är släppta på förhand innan de blivit stabiliserade. Stability: Private - - Mark the element as private. This is for interfaces which can be - used by tightly coupled modules, but not by arbitrary third - parties. - + Markera element som privat. Detta är avsett för gränssnitt som kan användas av tätt sammankopplade moduler, men inte av godtyckliga tredje parter. - General tags - Generella taggar + /** * foo_get_bar: - * @foo: some foo + * @foo: någon foo * - * Retrieves @foo's bar. + * Hämtar bar från @foo. * - * Returns: @foo's bar + * Returns: bar från @foo * * Since: 2.6 - * Deprecated: 2.12: Use foo_baz_get_bar() instead. + * Deprecated: 2.12: Använd foo_baz_get_bar() istället. */ Bar * foo_get_bar(Foo *foo) { -... -]]> +… + - Annotations + Noteringar - - 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. - + Dokumentationsblock kan innehålla noteringstaggar. Dessa taggar kommer att renderas som verktygstips som beskriver deras syfte. Taggarna används av gobject-introspection för att generera språkbindningar. En detaljerad lista över vilka taggar som stöds hittas på wikisidan. - Annotations - Noteringar + /** - * foo_get_bar: (annotation) - * @foo: (annotation): some foo + * foo_get_bar: (notering) + * @foo: (notering): någon foo * - * Retrieves @foo's bar. + * Hämtar bar från @foo. * - * Returns: (annotation): @foo's bar + * Returns: (notering): bar från @foo */ ... /** - * foo_set_bar_using_the_frobnicator: (annotation) (another annotation) - * (and another annotation) - * @foo: (annotation) (another annotation): some foo + * foo_set_bar_using_the_frobnicator: (notering) (an annan notering) + * (ytterligare en annan notering) + * @foo: (notering) (en annan notering): någon foo * - * Sets bar on @foo. + * Ställer in bar i @foo. */ -]]> + - Function comment block + Kommentarsblock för funktioner - - Please remember to: - + Kom ihåg att: - - Document whether returned objects, lists, strings, etc, should be - freed/unrefed/released. - + Dokumentera huruvida returnerade objekt, listor, strängar, etc. bör frigöras/avrefereras/släppas. - - Document whether parameters can be NULL, and what happens if they are. - + Dokumentera huruvida parametrar tillåts vara NULL och vad som händer om de är NULL. - - Mention interesting pre-conditions and post-conditions where appropriate. - + Nämn intressanta förvillkor och eftervillkor där lämpligt. - - + - - Gtk-doc assumes all symbols (macros, functions) starting with '_' are - private. They are treated like static functions. - + Gtk-doc förutsätter att alla symboler (makron, funktioner) som börjar med ”_” är privata. De behandlas på samma sätt som statiska funktioner. - Function comment block - Kommentarsblock för funktioner + /** - * function_name: - * @par1: description of parameter 1. These can extend over more than - * one line. - * @par2: description of parameter 2 - * @...: a %NULL-terminated list of bars + * funktionsnamn: + * @par1: beskrivning av parameter 1. Dessa kan sträcka sig + * över mer än en rad. + * @par2: beskrivning av parameter 2 + * @...: en %NULL-terminerad lista av flera bar * - * The function description goes here. You can use @par1 to refer to parameters - * so that they are highlighted in the output. You can also use %constant - * for constants, function_name2() for functions and #GtkWidget for links to - * other declarations (which may be documented elsewhere). + * Funktionsbeskrivningen ska vara här. Du kan använda @par1 för att + * referera till parametrar så att de färgmarkeras i utdata. Du kan också + * använda %konstant för konstanter, funktionsnamn2() för funktioner och + * #GtkWidget för länkar till andra deklarationer (vilka kan vara dokumenterade + * på annat håll). * - * Returns: an integer. + * Returns: ett heltal. * * Since: 2.2 - * Deprecated: 2.18: Use other_function() instead. + * Deprecated: 2.18: Använd annan_funktion() istället. */ -]]> + - Function tags + Funktions-taggar Returns: - - Paragraph describing the returned result. - + Stycke som beskriver det returnerade resultatet. @...: - - In case the function has variadic arguments, you should use this - tag (@Varargs: does also work for historic reasons). - + Om funktionen har variadiska argument bör du använda denna tagg (@Varargs: fungerar också på grund av historiska skäl). - Property comment block + Kommentarsblock för egenskaper - Property comment block - Kommentarsblock för egenskaper + /** - * SomeWidget:some-property: + * EnKomponent:en-egenskap: * - * Here you can document a property. + * Här kan du dokumentera en egenskap. */ -g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...); -]]> +g_object_class_install_property (object_class, PROP_EN_EGENSKAP, …); + - Signal comment block + Kommentarsblock för signaler - - Please remember to: - + Kom ihåg att: - - Document when the signal is emitted and whether it is emitted before - or after other signals. - + Dokumentera när en signal sänds ut och huruvida den sänds ut före eller efter andra signaler. - - Document what an application might do in the signal handler. - + Dokumentera vad ett program kan göra i signalhanteraren. - - + - Signal comment block - Kommentarsblock för signaler + /** - * FooWidget::foobarized: - * @widget: the widget that received the signal - * @foo: some foo - * @bar: some bar + * FooWidget::foobariserad: + * @widget: komponenten som erhåller signalen + * @foo: någon foo + * @bar: någon bar * - * The ::foobarized signal is emitted each time someone tries to foobarize @widget. + * Signalen ::foobarized sänds ut varje gång någon försöker att foobarisera @widget. */ foo_signals[FOOBARIZE] = - g_signal_new ("foobarize", + g_signal_new ("foobarisera", ... -]]> + - Struct comment block - Struct comment block - Kommentarsblock för strukturer + Kommentarsblock för strukturer + /** * FooWidget: - * @bar: some #gboolean + * @bar: någon #gboolean * - * This is the best widget, ever. + * Detta är den bästa komponenten någonsin. */ typedef struct _FooWidget { GtkWidget parent_instance; gboolean bar; } FooWidget; -]]> + - - Use /*< private >*/ before the private struct fields - you want to hide. Use /*< public >*/ for the reverse - behaviour. - + Använd/*< private >*/ före privata strukturfält som du vill gömma. Använd /*< public >*/ för det omvända beteendet. - - 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. - + Om det första fältet är ”g_iface”, ”parent_instance” eller ”parent_class” kommer det att anses vara privat automatiskt och behöver inte nämnas i kommentarsblocket. - - Struct comment blocks can also be used for GObjects and GObjectClasses. - It is usually a good idea to add a comment block for a class, if it has - vmethods (as this is how they can be documented). For the GObject - itself one can use the related section docs, having a separate block - for the instance struct would be useful if the instance has public - fields. One disadvantage here is that this creates two index entries - of the same name (the structure and the section). - + Kommentarsblock för strukturer kan också användas för GObject och GObjectClass. Det är vanligtvis en bra idé att lägga till ett kommentarsblock för en klass om den har virtuella metoder (då detta är sättet på vilket de kan dokumenteras). För GObject i sig kan man använda den relaterade avsnittsdokumentationen, och ha ett separat block för varje instansstruktur vore användbart om instansen har publika fält. En nackdel här är att det skapar två indexposter med samma namn (strukturen och avsnittet). - Enum comment block - Enum comment block - Kommentarsblock för uppräkningar + Kommentarsblock för uppräkningar + /** * Something: - * @SOMETHING_FOO: something foo - * @SOMETHING_BAR: something bar + * @SOMETHING_FOO: någonting foo + * @SOMETHING_BAR: någonting bar * - * Enum values used for the thing, to specify the thing. + * Uppräkningsvärden som används för saken, för att specificera saken. */ typedef enum { SOMETHING_FOO, SOMETHING_BAR, - /*< private >*/ + /*< private >*/ SOMETHING_COUNT } Something; -]]> + - - Use /*< private >*/ before the private enum values - you want to hide. Use /*< public >*/ for the reverse - behaviour. - + Använd /*< private >*/ före privata uppräkningsvärden som du vill gömma. Använd /*< public >*/ för det omvända beteendet. - - Useful DocBook tags - - Here are some DocBook tags which are most useful when documenting the - code. - + + Infogad programdokumentation + Du kan dokumentera program och deras kommandoradsgränssnitt med infogad dokumentation. - - To link to another section in the GTK docs: - - - Hash Tables -]]> - - The linkend is the SGML/XML id on the top item of the page you want to link to. - For most pages this is currently the part ("gtk", "gdk", "glib") and then - the page title ("Hash Tables"). For widgets it is just the class name. - Spaces and underscores are converted to '-' to conform to SGML/XML. - + + Taggar - - To refer to an external function, e.g. a standard C function: - - ... -]]> - - + PROGRAM - - To include example code: - - - Using a GHashTable. - - ... - - -]]> - - or possibly this, for very short code fragments which don't need a title: - - - - ... - - -]]> - - For the latter GTK-Doc also supports an abbreviation: - - + + Definierar början av programdokumentationen. + + - - To include bulleted lists: - - - - - ... - - - - - ... - - - -]]> - - + + @short_description: + + Definierar en kort beskrivning av programmet. (Valfritt) + + - - To include a note which stands out from the text: - - - - Make sure you free the data after use. - - -]]> - - + + @synopsis: + + Definierar argumenten, eller en lista av argument som programmet kan ta. (Valfritt) + + - - To refer to a type: - - unsigned char -]]> - - + + @see_also: + + Se vidare i manualavsnitt. (Valfritt) + + - - To refer to an external structure (not one described in the GTK docs): - - XFontStruct -]]> - - + + @arg: + + Argument som skickas vidare till programmet och deras beskrivningar. (Valfritt) + + - - To refer to a field of a structure: - - len -]]> - - + + Beskrivning: + + En längre beskrivning av programmet. + + - - To refer to a class name, we could possibly use: - - GtkWidget -]]> - - but you'll probably be using #GtkWidget instead (to automatically create - a link to the GtkWidget page - see the abbreviations). - + + Returns: + + Ange vilka värden programmet returnerar. (Valfritt) + + - - To emphasize text: - - This is important -]]> - - + - - For filenames use: - - /home/user/documents -]]> - - + + Exempel på programdokumentation. + Dokumentationsblock för program + +/** + * PROGRAM:test-program + * @short_description: Ett testprogram + * @synopsis: test-program [*FLAGGOR*...] --arg1 *arg* *FIL* + * @see_also: test(1) + * @--arg1 *arg*: ställ in arg1 på *arg* + * @--arg2 *arg*: ställ in arg2 på *arg* + * @-v, --version: Skriv ut versionsinformation + * @-h, --help: Skriv ut hjälpmeddelandet + * + * En längre beskrivning av programmet. + * + * Returns: Noll vid framgång, icke-noll vid fel + */ +int main(int argc, char *argv[]) +{ + return 0; +} + + - - To refer to keys use: - - ControlL -]]> - - + + + + + Användbara DocBook-taggar + + Här är några DocBook-taggar som är användbara när man dokumenterar koden. + + För att länka till ett annat avsnitt i GTK-dokumentationen: + +<link linkend="glib-Hash-Tables">Hashtabeller</link> + + Länkslutet är XGML/XML-id:t för toppnivåobjektet på sidan du vill länka till. För de flesta sidorna är detta för närvarande delen (”gtk”, ”gdk”, ”glib”) och sedan sidans titel (”Hashtabeller”). För komponenter är detta helt enkelt klassnamnet. Blanksteg och understreck konverteras till ”-” för att överensstämma med SGML/XML. + + För att referera till en extern funktion, t.ex. en standardfunktion i C: + +<function>…</function> + + + + För att inkludera exempelkod: + +<example> + <title>Att använda en hashtabell.</title> + <programlisting> + … + </programlisting> +</example> + + eller möjligen följande, för väldigt korta kodfragment som inte behöver en titel: + +<informalexample> + <programlisting> + … + </programlisting> +</informalexample> + + För det senare fallet har GTK-Doc också stöd för förkortningen: |[ … ]| + + För att inkludera punktlistor: + +<itemizedlist> + <listitem> + <para> + … + </para> + </listitem> + <listitem> + <para> + … + </para> + </listitem> +</itemizedlist> + + + + För att inkludera en not som skiljer sig från texten: + +<note> + <para> + Säkerställ att du frigjort data efter användning. + </para> +</note> + + + + För att refera till en typ: + +<type>unsigned char</type> + + + + För att referera till en extern struktur (som inte beskrivs i GTK-dokumentationen): + +<structname>XFontStruct</structname> + + + + För att referera till ett fält för en struktur: + +<structfield>len</structfield> + + + + För att referera till ett klassnamn kan vi möjligen använda: + +<classname>GtkWidget</classname> + + men du kommer troligt att använda #GtkWidget istället (för att automatiskt skapa en länk till GtkWidget-sidan - se förkortningarna). + + För att betona text: + +<emphasis>Detta är viktigt</emphasis> + + + + För filnamn använd: + +<filename>/home/användare/dokument</filename> + + + + För att referera till tangenter använd: + +<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo> + + - Filling the extra files + Fylla i de extra filerna - - There are a couple of extra files, that need to be maintained along with - the inline source code comments: - <package>.types, - <package>-docs.xml (in the past .sgml), - <package>-sections.txt. - + Det finns ett antal extra filer som behöver underhållas tillsammans med de infogade källkodskommentarerna: <paket>.types, <paket>-docs.xml (tidigare .sgml), <paket>-sections.txt. - Editing the types file + Redigera typfilen - - 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. - + 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. - Example types file snippet - + Exempel på typfilsnutt + +#include <gtk/gtk.h> gtk_accel_label_get_type gtk_adjustment_get_type gtk_alignment_get_type gtk_arrow_get_type -]]> + - - Since GTK-Doc 1.8 gtkdoc-scan can generate this list for you. - Just add "--rebuild-types" to SCAN_OPTIONS in Makefile.am. If you - use this approach you should not dist the types file nor have it under version control. - + Sedan GTK-Doc 1.8 kan gtkdoc-scan generera denna lista åt dig. Lägg bara till ”--rebuild-types” i SCAN_OPTIONS i Makefile.am. Om du använder detta tillvägagångssätt bör du inte distribuera typfilen eller versionshantera den. - Editing the master document + Redigera huvuddokumentet - - GTK-Doc produces documentation in DocBook SGML/XML. When processing the - inline source comments, the GTK-Doc tools generate one documentation - page per class or module as a separate file. The master document - includes them and place them in an order. - + GTK-Doc producerar dokumentation i DocBook SGML/XML. När infogade källkodskommentarer behandlas genererar GTK-Doc en dokumentationssida per klass eller modul som en separat fil. Huvuddokumentet inkluderar dem och placerar dem i en ordning. - - 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. - + Även om GTK-Doc skapar en mall för huvuddokumentet åt dig kommer senare körningar inte att röra det igen. Detta innebär att man är fri att strukturera om dokumentationen. Detta inkluderar att gruppera sidor och lägga till extra sidor. GTK-Doc har numera en testsvit där också huvuddokumentet återskapas från grunden. Det är en bra idé att titta på detta då och då för att se om några nya godsaker införts där. - - Do not create tutorials as extra documents. Just write extra chapters. - The benefit of directly embedding the tutorial for your library into - the API documentation is that it is easy to link for the tutorial to - symbol documentation. Apart chances are higher that the tutorial gets - updates along with the library. - + Skapa inte handledningar som extra dokument. Skriv bara extra kapitel. Fördelen med att bädda in handledningen direkt i ditt biblioteks gränssnittsdokumentation är att det är enkelt att länka från handledningen till symboldokumentationen. Inbäddad är det större chans att handledningen blir uppdaterad tillsammans med biblioteket. - - So what are the things to change inside the master document? For a start - is only a little. There are some placeholders (text in square brackets) - there which you should take care of. - + Så vilka saker ska ändras i huvuddokumentet? I början är det väldigt lite. Det finns en del platshållare (text i hakparenteser) som du bör ta hand om. - Master document header - - MODULENAME Reference Manual - - for MODULENAME [VERSION] - The latest version of this documentation can be found on-line at - http://[SERVER]/MODULENAME/. - - - - - [Insert title here] -]]> + Huvuddokumentets huvud + +<bookinfo> + <title>MODULNAMN handbok</title> + <releaseinfo> + för MODULNAMN [VERSION] + Den senaste versionen av detta dokument kan hittas på nätet på + <ulink role="online-location" url="http://[SERVER]/MODULNAMN/index.html">http://[SERVER]/MODULNAMN/</ulink>. + </releaseinfo> +</bookinfo> + +<chapter> + <title>[Infoga titel här]</title> + + Dessutom finns det ett antal valfria element som skapas i kommenterad form. Du kan granska dessa och aktivera dem enligt dina egna önskemål. + - In addition a few option elements are created in commented form. You can - review these and enable them as you like. - - - - Optional part in the master document - - --> -]]> + Valfri del i huvuddokumentet + + <!-- aktivera detta om du vill använda gobject introspection-noteringar + <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> + --> + - - - 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. - + + Slutligen behöver du lägga till ett nytt avsnitt när du infogar det. Verktyget gtkdoc-check kommer att påminna dig om nyligen genererade xml-filer som ännu inte infogats i dokumentationen. - Including generated sections - - my library - + Inkludera genererade avsnitt + + <chapter> + <title>mitt bibliotek</title> + <xi:include href="xml/object.xml"/> ... -]]> + - Editing the section file + Redigera avsnittsfilen - - The section file is used to organise the documentation output by - GTK-Doc. Here one specifies which symbol belongs to which module or - class and control the visibility (public or private). - + Avsnittsfilen används för att organisera dokumentationsutdata från GTK-Doc. Här kan man ange vilken symbol som hör till vilken modul eller klass och styra synligheten (publik eller privat). + + Avsnittsfilen är en vanlig textfil med taggar som avgränsar avsnitt. Blankrader ignoreras och rader som börjar med ett ”#” behandlas som kommentarsrader. - - 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. - - - - While the tags make the file look like xml, it is not. Please do not - close tags like <SUBSECTION>. - + Även om taggarna får filen att se ut som xml, är det inte det. Avsluta inte taggar så som <SUBSECTION>. - Including generated sections - libmeep/meep.h + Inkludera genererade avsnitt + +<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> + - - 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 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). - + Taggen <FILE> … </FILE> används för att ange filnamnet, utan något suffix. Om man t.ex. använder ”<FILE>gnome-config</FILE>” blir resultatet att avsnittsdeklarationerna matas ut i mallfilen tmpl/gnome-config.sgml, som kommer att konverteras till DocBook XML-filen xml/gnome-config.sgml eller DocBook XML-filen xml/gnome-config.xml. (Namnet på HTML-filen baseras på modulnamnet och avsnittstiteln, för GObject baseras det på klassnamnet för GObjectet konverterat till gemener). - - The <TITLE> ... </TITLE> tag is used to specify the title of - the section. It is only useful before the templates (if used) are - initially created, since the title set in the template file overrides - this. Also if one uses SECTION comment in the sources, this is obsolete. - + Taggen <TITLE> … </TITLE> används för att ange titeln på avsnittet. Det är bara användbart före mallar skapas initialt (om de används), eftersom titeln som ställs in i avsnittsfilen åsidosätter denna. Vidare är detta föråldrat om man använder SECTIONS-kommentarer i källkoden. - - 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). - + Du kan gruppera objekt i avsnittet genom att använda taggen <SUBSECTION>. För närvarande matas en blankrad ut mellan underavsnitt i sammanfattningsavsnittet. Du kan också använda <SUBSECTION Standard> för standard GObject-deklarationer (t.ex. funktioner så som g_object_get_type och makron som G_OBJECT(), G_IS_OBJECT(), etc.). För närvarande utelämnas dessa ur dokumentationen. Du kan också använda <SUBSECTION Private> för privata deklarationer som inte kommer att matas ut (det är ett bekvämt sätt att undvika varningsmeddelanden om oanvända deklarationer). Om ditt bibliotek innehåller privata typer som du inte vill ska dyka upp i objekthierarkin och i listan över implementerade eller krävda gränssnitt, lägg till dem i ett privat avsnitt. Huruvida du vill placera GObject och GObjectClass-liknande strukturer i publika eller standardavsnitt beror på om de har publika poster (variabler, virtuella metoder). - - You can also use <INCLUDE> ... </INCLUDE> to specify the - #include files which are shown in the synopsis sections. - It contains a comma-separate list of #include files, without the angle - brackets. If you set it outside of any sections, it acts for all - sections until the end of the file. If you set it within a section, it - only applies to that section. - + Du kan också använda <INCLUDE> ... </INCLUDE> för att ange #include-filerna som ska visas i sammanfattningsavsnitten. Den innehåller en kommaavgränsad lista av #include-filer, utan vinkelparenteser. Om du ställer in det utanför några avsnitt kommer det att påverka alla avsnitt tills slutet på filen. Om du ställer in det inom ett avsnitt kommer det bara att påverka det avsnittet. - Controlling the result - - - A GTK-Doc run generates report files inside the documentation directory. - The generated files are named: - <package>-undocumented.txt, - <package>-undeclared.txt and - <package>-unused.txt. - All those are plain text files that can be viewed and postprocessed easily. - - - - The <package>-undocumented.txt file starts with - the documentation coverage summary. Below are two sections divided by - blank lines. The first section lists undocumented or incomplete symbols. - The second section does the same for section docs. Incomplete entries are - those, which have documentation, but where e.g. a new parameter has been - added. - - - - The <package>-undeclared.txt file lists symbols - given in the <package>-sections.txt but not - found in the sources. Check if they have been removed or if they are - misspelled. - - - - The <package>-unused.txt file lists symbol - names, where the GTK-Doc scanner has found documentation, but does not - know where to put it. This means that the symbol has not yet been added to - the <package>-sections.txt file. - + Kontrollera resultatet + + En GTK-Doc-körning genererar rapportfiler inuti dokumentationskatalogen. De genererade filerna heter: <paket>-undocumented.txt, <paket>-undeclared.txt och <paket>-unused.txt. Alla är vanliga textfiler och kan visas eller efterbehandlas enkelt. + + Filen <paket>-undocumented.txt inleds med en sammanfattning över hur mycket dokumentation som skrivits. Under det finns två avsnitt avgränsade av blankrader. Det första avsnittet listar odokumenterade eller ofullständiga symboler. Det andra avsnittet gör detsamma för avsnittsdokumentation. Ofullständiga poster är de som har dokumentation, men där en ny parameter har lagts till. + + Filen <paket>-undeclared.txt listar symboler som anges i <paket>-sections.txt men inte hittas i källkoden. Kontrollera om de har tagits bort eller om de är felstavade. + + Filen <paket>-unused.txt listar symbolnamn där GTK-Doc-detektorn har hittat dokumentation men inte vet var den ska placeras. Detta innebär att symbolen ännu inte har lagts till i filen <package>-sections.txt. - - Enable or add the line in Makefile.am. - If at least GTK-Doc 1.9 is installed, this will run sanity checks during - make check run. - + Aktivera eller lägg till raden i Makefile.am. Om åtminstone GTK-Doc 1.9 finns installerat kommer detta att köra rimlighetskontroller under körning av make check. - - 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. - - - - 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 GTK-Doc to keep the intermediate - scanner file for further analysis, by running it as - GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Man kan också titta på filerna som producerats av källkodsdetektorn: <paket>-decl-list.txt och <paket>-decl.txt. Den första kan jämföras med avsnittsfilen om den underhålls manuellt. Den andra listar alla deklarationer från huvudena. Om en symbol saknas bör man kontrollera om denna filen innehåller den. + + Om projektet är GObject-baserat kan man också titta på filerna som producerats av objekt-detektorn: <paket>.args.txt, <paket>.hierarchy.txt, <paket>.interfaces.txt, <paket>.prerequisites.txt och <paket>.signals.txt. Om det saknas symboler i någon av dem kan man be GTK-Doc att bibehålla de temporära detektorfilerna för vidare analys, genom att köra det som GTK_DOC_KEEP_INTERMEDIATE=1 make. - + - Modernizing the documentation - - - 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. - - + Modernisera dokumentationen + + GTK-Doc har funnits ett tag. I detta avsnitt listar vi nya funktioner tillsammans med vilken version de gjordes tillgängliga. + GTK-Doc 1.9 - - When using xml instead of sgml, one can actually name the master - document <package>-docs.xml. - - - - 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. - - - - 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 you source control system and haven't yet switched, just - add the flag to configure.ac and you are done. - + När man använder xml istället för sgml, kan man faktiskt kalla huvuddokumentet <paket>-docs.xml. + + Denna version har stöd för i Makefile.am. När detta är aktiverat kommer <paket>-sections.txt att autogenereras och kan tas bort från versionshanteringssystemet. Detta fungerar bra för projekt som har en väldigt standardiserad struktur (t.ex. kommer varje .{c,h}-par att skapa ett nytt avsnitt). Om man organiserar ett projekt likt detta kommer den manuella uppdateringen av en avsnittsfil att vara så enkelt som att köra meld <paket>-decl-list.txt <paket>-sections.txt. + + Redan version 1.8 introducerade syntaxen för avsnittsdokumentation i källkoden istället för separata filer under tmpl. Denna version lägger till flaggor för att kunna ställa om hela dokumentationsmodulen till att inte använda det extra tmpl-byggsteget alls, genom att använda i configure.ac. Om du inte har tmpl incheckat i ditt versionshanteringssystem just nu och inte har gått över än bara lägg till flaggan i configure.ac så är du klar. - + GTK-Doc 1.10 - - 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. - + Denna version har stöd för i Makefile.am. När det är aktiverat kommer <package>.types att autogenereras och kan tas bort från versionshanteringssystemet. När denna funktion används är det viktigt att också ställa in IGNORE_HFILES i Makefile.am för kod som bara byggs ibland. GTK-Doc 1.16 - - 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. - Enable gtkdoc-check - Denna version har stöd för ett nytt verktyg som heter gtkdoc-check. Detta verktyg kan köra en uppsättning kontroller på din dokumentation. Det aktiveras genom att lägga till dessa raderna i slutet av Makefile.am. Aktivera gtkdoc-check + if ENABLE_GTK_DOC TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) TESTS = $(GTKDOC_CHECK) endif -]]> - - + + GTK-Doc 1.20 - - 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. - + Version 1.18 införde inledande stöd för markdown. Att använda markdown i dokumentationskommentarer är mindre påträngande än att skriva docbook xml. Denna version förbättrar detta väsentligt och lägger till många fler stilar. Avsnittet som beskriver kommentarsyntax finnas alla detaljer. 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 any example that shows how the entity file is included - and how the entities are used. The entities can also be used in all - generated files, GTK-Doc will use the same xml header in generated xml - files. - Use pre-generated entities - -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" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ - - + <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> + <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent"> %gtkdocentities; -]> - - - &package_name; Reference Manual - - for &package_string;. - The latest version of this documentation can be found on-line at - http://[SERVER]/&package_name;/. - - -]]> - - +]> +<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> + + - Documenting other interfaces + Dokumentera andra gränssnitt - - So far we have been using GTK-Doc to document the API of code. The next - sections contain suggestions how the tools can be used to document other - interfaces too. - + Så här långt har vi använt GTK-Doc för att dokumentera API:t för koden. Följande avsnitt innehåller förslag om hur verktyget kan användas för att också dokumentera andra gränssnitt. - Command line options and man pages + Kommandoradsflaggor och mansidor - - As one can generate man pages for a docbook refentry as well, it sounds - like a good idea to use it for that purpose. This way the interface is - part of the reference and one gets the man-page for free. - + Då man också kan generera mansidor för ett docbook-refentry, låter det som en bra idé att använda det för detta ändamål. På detta sättet kommer gränssnittet att vara en del av referensen och man får mansidan gratis. - Document the tool + Dokumentera verktyget - - Create one refentry file per tool. Following - our example we would call it - meep/docs/reference/meeper/meep.xml. For the xml - tags that should be used and can look at generated file in the xml - subdirectory as well as examples e.g. in glib. - + Skapa en refentry-fil per verktyg. Om du följer vårt exempel borde vi kalla det meep/docs/reference/meeper/meep.xml. För xml-taggarna bör detta användas och man kan studera den genererade filen i xml-underkatalogen så väl som exempel i glib. - Adding the extra configure check + Lägga till den extra configure-kontrollen - Extra configure checks - Lägga till extra configure-kontroller + AC_ARG_ENABLE(man, [AC_HELP_STRING([--enable-man], - [regenerate man pages from Docbook [default=no]])],enable_man=yes, + [omgenerera mansidor från Docbook [standardvärde=no]])],enable_man=yes, enable_man=no) AC_PATH_PROG([XSLTPROC], [xsltproc]) AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno) -]]> + - Adding the extra makefile rules + Lägga till de extra makefilsreglerna - Extra configure checks - Lägga till extra configure-kontroller + man_MANS = \ meeper.1 @@ -2023,137 +1276,94 @@ 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 -]]> + - DBus interfaces + DBus-gränssnitt - - (FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, -http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) - + (FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) - Frequently asked questions + Frågor och svar Fråga Svar - No class hierarchy. - - The objects xxx_get_type() function has not been - entered into the <package>.types file. - + Ingen klasshierarki. + Objektens xxx_get_type()-funktion har inte matats in i filen <paket>.types. - Still no class hierarchy. - - Missing or wrong naming in <package>-sections.txt - file (see explanation). - + Fortfarande ingen klasshierarki. + Saknat eller fel namn i filen <paket>-sections.txt (se förklaring). - Damn, I have still no class hierarchy. - - 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 - subsections). - + Förbannat, jag har fortfarande ingen klasshierarki. + Är objektnamnet (namnet på instansstrukturen, t.ex. GtkWidget) del av det normala avsnittet (stoppa inte detta i underavsnitt så som Standard eller Private). - No symbol index. - - Does the <package>-docs.{xml,sgml} contain a - index that xi:includes the generated index? - + Inget symbolindex. + Innehåller <paket>-docs.{xml,sgml} ett index som inkluderar det genererade indexet med xi:include? - Symbols are not linked to their doc-section. - - Is the doc-comment using the correct markup (added #,% or ())? - Check if the gtkdoc-fixxref warns about unresolvable xrefs. - + Symboler är inte länkade till deras dokumentationsavsnitt. + Använder dokumentationskommentaren korrekta taggar (har du lagt till #, % eller ())? Kontrollera om gtkdoc-fixxref varnar om oupplösbara korsreferenser. - A new class does not appear in the docs. - - Is the new page xi:included from - <package>-docs.{xml,sgml}. - + En ny klass dyker inte upp i dokumentationen. + Är den nya sidan inkluderad med xi:include från <package>-docs.{xml,sgml}. - A new symbol does not appear in the docs. - - Is the doc-comment properly formatted. Check for spelling mistakes in - the begin of the comment. Check if the gtkdoc-fixxref warns about - unresolvable xrefs. Check if the symbol is correctly listed in the - <package>-sections.txt in a public subsection. - + En ny symbol dyker inte upp i dokumentationen. + Är dokumentationskommentaren korrekt formaterad. Leta efter stavfel i början av kommentaren. Kontrollera om gtkdoc-fixxref varnar om oupplösbara korsreferenser. Kontrollera om symbolen finns korrekt listad i <paket>-sections.txt i ett publikt avsnitt. - A type is missing from the class hierarchy. - - 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 - incidentally marked private it will not be shown. - + En typ saknas från klasshierarkin. + Om typen finns listad i <paket>.hierarchy men inte i xml/tree_index.sgml, dubbelkolla då att typen finns korrekt placerad i <paket>-sections.txt. Om typinstansen (t.ex. GtkWidget) inte visas eller är markerad privat kommer den inte att visas. - I get foldoc links for all gobject annotations. - - Check that xml/annotation-glossary.xml is - xi:included from <package>-docs.{xml,sgml}. - + Jag får foldoc-länkar för alla gobject-noteringar. + Kontrollera att xml/annotation-glossary.xml är inkluderad med xi:include från <package>-docs.{xml,sgml}. - Parameter described in source code comment block but does not exist - Check if the prototype in the header has different parameter names as in the source. + Parameter beskriven i kommentarsblock i källkoden men existerar inte + Kontrollera om prototypen i huvudet har andra parameternamn än i källkoden. - multiple "IDs" for constraint linkend: XYZ - Symbol XYZ appears twice in <package>-sections.txt file. + multipla ”ID:n” för begränsat länkslut: XYZ + Symbolen XYZ förekommer två gånger i filen <paket>-sections.txt. - Element typename in namespace '' encountered in para, but no template matches. + Elementtypnamn i namnrymd ”” påträffat i para, men ingen mall matchar. - Tools related to gtk-doc - - - GtkDocPlugin - a Trac GTK-Doc - integration plugin, that adds API docs to a trac site and integrates with - the trac search. - - - Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since - tags in the API to determine the minimum required version. - + Verktyg relaterade till gtk-doc + + GtkDocPlugin - en insticksmodul för Trac GTK-Doc-integrering som lägger till API-dokumentation till en trac-webbplats och integrerar med trac-sökningen. + Gtkdoc-depscan - ett verktyg (del av gtk-doc) för att kontrollera använda API mot since-taggar i API:t för att avgöra minsta version som krävs. @@ -2170,17 +1380,11 @@ http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) Version 1.1, mars 2000 - - 2000Free Software Foundation, Inc. - + 2000Free Software Foundation, Inc. - -
Free Software Foundation, Inc. 51 Franklin Street, +
Free Software Foundation, Inc. 51 Franklin Street, Suite 330, Boston, MA - 02110-1301 USA
- Everyone is permitted to copy and distribute verbatim copies of this - license document, but changing it is not allowed. - + 02110-1301 USA
. Alla är tillåtna kopiera och distribuera ordagranna kopior av detta licensdokument, men att ändra det är ej tillåtet. GNU Free Documentation License @@ -2194,7 +1398,7 @@ http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) Vi har utformat denna licens för att den skall användas för handböcker till fri programvara, eftersom fri programvara behöver fri dokumentation: ett fritt program bör ha en handbok som erbjuder samma friheter som programmet gör. Men denna licens är inte begränsad till programvaruhandböcker; den kan användas för vilket textverk som helst oavsett ämne eller huruvida det är en utgiven, tryckt bok. Vi rekommenderar denna licens huvudsakligen för alla verk vars syfte är instruktion eller referens. - TILLÄMPNINGSOMRÅDE OCH DEFINITIONER + 1. TILLÄMPNINGSOMRÅDE OCH DEFINITIONER Denna licens [det engelska originalet] gäller för varje handbok eller annat verk, oavsett uttrycksform, som innehåller ett meddelande där upphovsrättsinnehavaren stadgat att verket kan spridas enligt villkoren i GNU Free Documentation License. Ett sådant meddelande ger en internationell frihet utan krav på ersättning och utan tidsbegränsning att använda verket under villkoren i denna licens [det engelska originalet]. Dokument nedan syftar på godtycklig handbok eller verk. Var och en är licenstagare och benämns som du. En förändrad version av dokumentet avser varje verk som innehåller dokumentet eller en del av det, antingen ordagranna kopior, eller med ändringar och/eller översatt till ett annat språk. @@ -2205,9 +1409,9 @@ http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) Omslagstexterna är speciella korta ordföljder som är listade som framsidestexter eller baksidestexter i meddelandet som stadgar att dokumentet är utgivet under denna licens [det engelska originalet]. - En transparent kopia av dokumentet är en maskinläsbar kopia, representerad i ett format vars specifikation finns tillgänglig för allmänheten, som lämpar sig för att revidera dokumentet på ett enkelt sätt med generella textredigeringsprogram eller (för pixelbaserade bilder) generella grafikprogram eller (för ritningar) något väl tillgängligt ritprogram, och som är passande som indata till textfomaterare eller för automatisk konvertering till en mängd format som passar som indata till textformaterare. En kopia i ett för övrigt transparent filformat vars markeringar, eller avsaknad av markeringar, har ordnats för att hindra eller motverka att vidare förändring vidtas av läsare är inte transparent. Ett bildformat är inte transparent om det används för någon betydande del text. En kopia som inte är transparent kallas opak. + En transparent kopia av dokumentet är en maskinläsbar kopia, representerad i ett format vars specifikation finns tillgänglig för allmänheten, som lämpar sig för att revidera dokumentet på ett enkelt sätt med generella textredigeringsprogram eller (för pixelbaserade bilder) generella grafikprogram eller (för ritningar) något väl tillgängligt ritprogram, och som är passande som indata till textformaterare eller för automatisk konvertering till en mängd format som passar som indata till textformaterare. En kopia i ett för övrigt transparent filformat vars markeringar, eller avsaknad av markeringar, har ordnats för att hindra eller motverka att vidare förändring vidtas av läsare är inte transparent. En kopia som inte är transparent kallas opak. - Exempel på passande format för transparenta kopior innefattar ren ASCII utan markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript eller PDF utformat för mänsklig förändring. Exempel på transparenta bildformat innefattar PNG, XCF och JPG. Opaka format innefattar leverantörsspecifika format som bara kan läsas och editeras med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/eller verktyg för behandling inte finns allmänt tillgängliga, och den maskingenererade HTML, PostScript eller PDF som produceras av vissa ordbehandlare enbart avsett som utdata. + Exempel på passande format för transparenta kopior innefattar ren ASCII utan markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript eller PDF utformat för mänsklig förändring. Opaka format innefattar Postscript, PDF, leverantörsspecifika format som bara kan läsas och editeras med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/eller verktyg för behandling inte finns allmänt tillgängliga, och den maskingenererade HTML som produceras av vissa ordbehandlare enbart avsett som utdata. Titelsidan innebär, för en tryckt bok, titelsidan själv, och sådana därpå följande sidor som krävs för att göra det material som enligt denna licens skall synas på titelsidan läsbart. För verk i sådana format som inte har någon egentlig titelsida, avses med titelsida den text som är närmast den mest framstående förekomsten av verkets titel, föregående den huvudsakliga textmassan. @@ -2225,7 +1429,7 @@ http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) Om de obligatoriska texterna för något omslag är för omfattande för att rymmas i läsbart skick skall du placera de första (så många som får plats) på det egentliga omslaget, och fortsätta med resten på de direkt intilliggande sidorna. - Om du publicerar opaka kopior av dokumentet i upplagor om mer än 100, måste du antingen bifoga en maskinläsbar transparent kopia med varje opak kopia, eller ange i eller med varje opak kopia en nätverksadress som är tillgänglig för den allmänna nätverksanvändande massan där man, med öppet standardiserade protokoll, kan ladda ner en komplett transparent kopia av dokumentet, utan extra material. Om du väljer det senare alternativet, måste du vidta skäliga åtgärder, när du börjar sprida opaka kopior i kvantitet, för att denna transparenta kopia skall förbli tillgänglig på angivna platsen till åtminstone ett år efter den sista gången du spred en opak kopia (direkt eller via ombud eller återförsäljare) av den utgåvan till allmänheten. + Om du publicerar opaka kopior av dokumentet i upplagor om mer än 100, måste du antingen bifoga en maskinläsbar transparent kopia med varje opak kopia, eller ange i eller med varje opak kopia en nätverksadress som är tillgänglig för den allmänna nätverksanvändande massan där man, med öppet standardiserade protokoll, anonymt och utan kostnad kan ladda ner en komplett transparent kopia av dokumentet, utan extra material. Om du väljer det senare alternativet, måste du vidta skäliga åtgärder, när du börjar sprida opaka kopior i kvantitet, för att denna transparenta kopia skall förbli tillgänglig på angivna platsen till åtminstone ett år efter den sista gången du spred en opak kopia (direkt eller via ombud eller återförsäljare) av den utgåvan till allmänheten. Det är önskvärt, men inte ett krav, att du kontaktar författarna till dokumentet i god tid innan du sprider något större antal kopior, för att ge dem en chans att förse dig med en uppdaterad version av dokumentet. @@ -2294,18 +1498,7 @@ http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) I - - Preserve the section entitled History, and - its title, and add to it an item stating at least the - title, year, new authors, and publisher of the Modified Version as given on - the Title Page. If - there is no section entitled History in the - Document, create one - stating the title, year, authors, and publisher of the - Document as given on its Title Page, then add an item - describing the Modified Version as stated in the previous - sentence. - + Bevara avsnittet med titeln historik (History), bevara dess titel och lägg i avsnittet till en post med åtminstone titeln, året, nya författare och utgivaren av den förändrade versionen så som angivet på titelsidan. Om det inte finns något avsnitt med titeln historik (History) i dokumentet så skapa en med titeln, året, författare och utgivaren av dokumentet så som det står på [original]dokumentets titelsida. Lägg sedan till en post som beskriver den förändrade versionen så som beskrivits ovan. @@ -2319,7 +1512,7 @@ http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) K - För alla avsnitt med titlarna tillkännagivanden (Acknowledgements) eller dedikationer (Dedications), bevara titeln på avsnittet, och bevara allt innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda av varje bidragare. + För alla avsnitt med titlarna tillkännagivanden (Acknowledgements) eller dedikationer (Dedications), bevara titeln på avsnittet, och bevara allt innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda av varje bidragsgivare. @@ -2349,7 +1542,7 @@ http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) Du äger lägga till ett avsnitt med titeln endossering (Endorsements), förutsatt att det inte innehåller något annat än endosseringar för din förändrade version från olika aktörer -- till exempel, meddelanden om utförd korrekturläsning eller att texten har godkänts av en organisation som en officiell definition av en standard. - Du äger lägga till ett textavsnitt på upp till fem ord som framsidestext, och ett textavsnitt på upp till 25 ord som baksidestext i listan över omslagstexter i den förändrade versionen. Bara ett textavsnitt med framsidestexter och ett med baksidestexter får läggas till av (eller genom försorg av) en enda juridisk person. Om dokumentet redan innehåller en omlagstext för något av omslagen, tidigare tillagd av dig eller genom försorg av samma juridiska person som du företräder, äger du inte lägga till en till, men du äger ändra den gamla med tillstånd från den tidigare utgivaren som lade till den förra. + Du äger lägga till ett textavsnitt på upp till fem ord som framsidestext, och ett textavsnitt på upp till 25 ord som baksidestext i listan över omslagstexter i den förändrade versionen. Bara ett textavsnitt med framsidestexter och ett med baksidestexter får läggas till av (eller genom försorg av) en enda juridisk person. Om dokumentet redan innehåller en omslagstext för något av omslagen, tidigare tillagd av dig eller genom försorg av samma juridiska person som du företräder, äger du inte lägga till en till, men du äger ändra den gamla med tillstånd från den tidigare utgivaren som lade till den förra. Författaren (författarna) och utgivaren (utgivarna) av dokumentet ger inte via denna licens sitt tillstånd att använda sina namn för publicitet eller för att lägga till eller antyda endossering av någon förändrad version. @@ -2367,18 +1560,12 @@ http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) 6. SAMLINGAR AV DOKUMENT Du äger skapa en samling bestående av dokumentet och andra dokument som är släppta under GNU Free Documentation License, och ersätta individuella kopior i dokumenten av denna licens med en enda kopia [av den engelska originalversionen] som inkluderas i samlingen, förutsatt att du följer villkoren för ordagrann kopiering i denna licens för varje inkluderat dokument i alla andra avseenden. - - 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. - + Du äger lyfta ut ett dokument från en sådan samling, och sprida det enskilt under GNU Free Documentation License, förutsatt att du lägger till en kopia av denna licens [den engelska originalversionen] i det utlyfta dokumentet, och följer villkoren för ordagrann kopiering i denna licens för det utlyfta dokumentet i alla andra avseenden. 7. SAMMANSLAGNING MED OBEROENDE VERK - En samling av dokumentet eller av dess derivat med andra separata och oberoende dokument eller verk, på eller i en lagringsvolym eller ett spridningsmedium, kallas för en sammanslagning om den sammanslagna upphovsrätten inte används för att begränsa samlingens användares rättigheter som de enskilda dokumenten medger. När dokumentet ingår i en sådan sammanslagning, gäller inte denna licens de andra verken i samlingen som inte själva är deriverat av dokumentet. Om kravet på omslagstexter enligt paragraf 3 är tillämpligt på dessa kopior av dokumentet, så kan dokumentets omslagstexter, om dokumentet utgör mindre än hälften av hela samlingen, placeras på det omslag som omger dokumentet inuti samlingen, eller den elektroniska motsvarigheten till omslag om dokumentet är i elektronisk form. Annars måste de synas på det omslag som omger hela samlingen. + En samling av dokumentet eller av dess derivat med andra separata och oberoende dokument eller verk, på eller i en lagringsvolym eller ett spridningsmedium, kallas för en sammanslagning om den sammanslagna upphovsrätten inte används för att begränsa samlingens användares rättigheter som de enskilda dokumenten medger. När dokumentet ingår i en sådan sammanslagning, gäller inte denna licens de andra verken i samlingen som inte själva är deriverat av dokumentet. Om kravet på omslagstexter enligt paragraf 3 är tillämpligt på dessa kopior av dokumentet, så kan dokumentets omslagstexter, om dokumentet utgör mindre än en fjärdedel av hela samlingen, placeras på det omslag som omger dokumentet inuti samlingen, eller den elektroniska motsvarigheten till omslag om dokumentet är i elektronisk form. Annars måste de synas på det omslag som omger hela samlingen. @@ -2403,11 +1590,11 @@ http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) För att använda GNU Free Documentation License för ett dokument du har skrivit, inkludera en kopia av licensen [det engelska originalet] i dokumentet och placera följande copyrightklausul omedelbart efter titelsidan:
- Copyright (c) ÅRTAL DITT NAMN. + Copyright © YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled GNU Free Documentation License.
- Om du inte har några oföränderliga avsnitt, skriv utan oföränderliga avsnitt istället för att ange vilka som är oföränderliga. Om du inte har några framsidestexter, skriv utan framsidestexter istället för framsidestexter som LISTAS; såväl som för baksidestexter. + Om du inte har några oföränderliga avsnitt, skriv with no Invariant Sections istället för att ange vilka som är oföränderliga. Om du inte har några framsidestexter, skriv no Front-Cover Texts istället för Front-Cover Texts being LIST; såväl som för baksidestexter. Om ditt dokument innehåller icke-triviala exempel med programkod, så rekommenderar vi att du släpper dessa exempel parallellt under en, av dig vald, fri programvarulicens, som till exempel GNU General Public License, för att möjliggöra deras användning i fri programvara. diff --git a/help/manual/sv/sv.po b/help/manual/sv/sv.po index 82c0f34..ca8bfa6 100644 --- a/help/manual/sv/sv.po +++ b/help/manual/sv/sv.po @@ -1,1156 +1,5894 @@ # Swedish translation of gtk-doc. -# Copyright (C) 2009 Free Software Foundation, Inc. +# Copyright © 2009-2017 Free Software Foundation, Inc. # This file is distributed under the same license as the gtk-doc package. # Daniel Nylander , 2009. +# Sebastian Rasmussen , 2016. +# Anders Jonsson , 2017. # msgid "" msgstr "" "Project-Id-Version: gtk-doc master\n" -"POT-Creation-Date: 2009-07-07 22:07+0000\n" -"PO-Revision-Date: 2009-07-09 12:31+0100\n" -"Last-Translator: Daniel Nylander \n" +"POT-Creation-Date: 2017-04-23 16:21+0000\n" +"PO-Revision-Date: 2017-04-28 23:38+0200\n" +"Last-Translator: Anders Jonsson \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 1.8.11\n" -#: C/gtk-doc-manual.xml:12(title) +#. Put one translator per line, in the form NAME , YEAR1, YEAR2 +msgctxt "_" +msgid "translator-credits" +msgstr "" +"Sebastian Rasmussen , 2016\n" +"Daniel Nylander , 2009\n" +"Marcus Rejås och Alexander Nordström , 2004\n" +"\n" +"Skicka kommentarer om översättningen\n" +"till svenska till " + +#. (itstool) path: bookinfo/title +#: C/index.docbook:12 msgid "GTK-Doc Manual" msgstr "Handbok för GTK-Doc" -#: C/gtk-doc-manual.xml:13(edition) -msgid "1.12" -msgstr "1.12" +#. (itstool) path: bookinfo/edition +#: C/index.docbook:13 +msgid "1.24.1" +msgstr "1.24.1" -#: C/gtk-doc-manual.xml:14(para) +#. (itstool) path: abstract/para +#: C/index.docbook:14 msgid "User manual for developers with instructions of GTK-Doc usage." -msgstr "Användarhandbok för utvecklare med användningsinstruktioner för GTK-Doc." - -#: C/gtk-doc-manual.xml:17(firstname) -msgid "Chris" -msgstr "Chris" - -#: C/gtk-doc-manual.xml:18(surname) -msgid "Lyttle" -msgstr "Lyttle" - -#: C/gtk-doc-manual.xml:21(email) -msgid "chris@wilddev.net" -msgstr "chris@wilddev.net" - -#: C/gtk-doc-manual.xml:26(firstname) -msgid "Dan" -msgstr "Dan" - -#: C/gtk-doc-manual.xml:27(surname) -msgid "Mueth" -msgstr "Mueth" - -#: C/gtk-doc-manual.xml:30(email) -msgid "d-mueth@uchicago.edu" -msgstr "d-mueth@uchicago.edu" +msgstr "" +"Användarhandbok för utvecklare med användningsinstruktioner för GTK-Doc." -#: C/gtk-doc-manual.xml:35(firstname) -msgid "Stefan" -msgstr "Stefan" +#. (itstool) path: authorgroup/author +#: C/index.docbook:16 +msgid "" +"Chris Lyttle " +"
chris@wilddev.net
" +msgstr "" +"Chris Lyttle " +"
chris@wilddev.net
" -#: C/gtk-doc-manual.xml:36(surname) -msgid "Kost" -msgstr "Kost" +#. (itstool) path: authorgroup/author +#: C/index.docbook:25 +msgid "" +"Dan Mueth
" +"d-mueth@uchicago.edu
" +msgstr "" +"Dan Mueth
" +"d-mueth@uchicago.edu
" -#: C/gtk-doc-manual.xml:39(email) -msgid "ensonic@users.sf.net" -msgstr "ensonic@users.sf.net" +#. (itstool) path: authorgroup/author +#: C/index.docbook:34 +msgid "" +"Stefan Sauer (Kost) " +"
ensonic@users.sf.net
" +msgstr "" +"Stefan Sauer (Kost) " +"
ensonic@users.sf.net
" -#: C/gtk-doc-manual.xml:45(publishername) +#. (itstool) path: publisher/publishername +#: C/index.docbook:45 msgid "GTK-Doc project" msgstr "GTK-Doc-projektet" -#: C/gtk-doc-manual.xml:46(email) -msgid "gtk-doc-list@gnome.org" -msgstr "gtk-doc-list@gnome.org" - -#: C/gtk-doc-manual.xml:49(year) -msgid "2000, 2005, 2007-2009" -msgstr "2000, 2005, 2007-2009" - -#: C/gtk-doc-manual.xml:50(holder) -msgid "Dan Mueth and Chris Lyttle and Stefan Kost" -msgstr "Dan Mueth, Chris Lyttle och Stefan Kost" - -#: C/gtk-doc-manual.xml:61(para) -msgid "Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included." -msgstr "Tillstånd att kopiera, distribuera och/eller modifiera detta dokument ges under villkoren i GNU Free Documentation License, version 1.1 eller senare, utgivet av Free Software Foundation utan standardavsnitt och omslagstexter. En kopia av licensen finns inkluderad." - -#: C/gtk-doc-manual.xml:69(para) -msgid "Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps." -msgstr "Flera namn på produkter och tjänster är registrerade varumärken. I de fall dessa namn förekommer i GNOME-dokumentation - och medlemmarna i GNOME-dokumentationsprojektet är medvetna om dessa varumärken - är de skrivna med versaler eller med inledande versal." - -#: C/gtk-doc-manual.xml:80(revnumber) -msgid "1.11" -msgstr "1.11" +#. (itstool) path: bookinfo/publisher +#: C/index.docbook:44 +msgid "" +"<_:publishername-1/>
gtk-doc-list@gnome.org
" +msgstr "" +"<_:publishername-1/>
gtk-doc-list@gnome.org
" -#: C/gtk-doc-manual.xml:81(date) -msgid "22 March 2008" -msgstr "22 mars 2008" +#. (itstool) path: bookinfo/copyright +#: C/index.docbook:48 +msgid "2000, 2005 Dan Mueth and Chris Lyttle" +msgstr "2000, 2005 Dan Mueth and Chris Lyttle" -#: C/gtk-doc-manual.xml:82(authorinitials) -msgid "mal" -msgstr "mal" +#. (itstool) path: bookinfo/copyright +#: C/index.docbook:52 +msgid "2007-2015 Stefan Sauer (Kost)" +msgstr "2007-2015 Stefan Sauer (Kost)" -#: C/gtk-doc-manual.xml:83(revremark) -msgid "GNOME doc-utils migration" +#. (itstool) path: legalnotice/para +#: C/index.docbook:65 +msgid "" +"Permission is granted to copy, distribute and/or modify this document under " +"the terms of the GNU Free Documentation License, " +"Version 1.1 or any later version published by the Free Software Foundation " +"with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A " +"copy of the license is included." +msgstr "" +"Tillstånd att kopiera, distribuera och/eller modifiera detta dokument ges " +"under villkoren i GNU Free Documentation License, " +"version 1.1 eller senare, utgivet av Free Software Foundation utan " +"standardavsnitt och omslagstexter. En kopia av licensen finns inkluderad." + +#. (itstool) path: legalnotice/para +#: C/index.docbook:73 +msgid "" +"Many of the names used by companies to distinguish their products and " +"services are claimed as trademarks. Where those names appear in any GNOME " +"documentation, and those trademarks are made aware to the members of the " +"GNOME Documentation Project, the names have been printed in caps or initial " +"caps." +msgstr "" +"Flera namn på produkter och tjänster är registrerade varumärken. I de fall " +"dessa namn förekommer i GNOME-dokumentation - och medlemmarna i GNOME-" +"dokumentationsprojektet är medvetna om dessa varumärken - är de skrivna med " +"versaler eller med inledande versal." + +#. (itstool) path: revhistory/revision +#: C/index.docbook:83 +msgid "" +"1.25.1 21 March 2016 ss development version" msgstr "" +"1.25.1 21 Mars 2016 ss utvecklingsversion" -#: C/gtk-doc-manual.xml:92(title) -msgid "Introduction" -msgstr "Introduktion" +#. (itstool) path: revhistory/revision +#: C/index.docbook:89 +msgid "" +"1.25 21 March 2016 ss bug fixes, test cleanups" +msgstr "" +"1.25 21 Mars 2016 ss programfixar, uppstädning av tester" -#: C/gtk-doc-manual.xml:94(para) -msgid "This chapter introduces GTK-Doc and gives an overview of what it is and how it is used." +#. (itstool) path: revhistory/revision +#: C/index.docbook:95 +msgid "" +"1.24 29 May 2015 ss bug fix" msgstr "" +"1.24 29 Maj 2015 ss programfix" -#: C/gtk-doc-manual.xml:100(title) -msgid "What is GTK-Doc?" -msgstr "Vad är GTK-Doc?" +#. (itstool) path: revhistory/revision +#: C/index.docbook:101 +msgid "" +"1.23 17 May 2015 ss bug fix" +msgstr "" +"1.23 17 Maj 2015 ss programfix" -#: C/gtk-doc-manual.xml:102(para) -msgid "GTK-Doc is used to document C code. It is typically used to document the public API of libraries, such as the GTK+ and GNOME libraries. But it can also be used to document application code." +#. (itstool) path: revhistory/revision +#: C/index.docbook:107 +msgid "" +"1.22 07 May 2015 ss bug fixes, dropping deprecated features" msgstr "" +"1.22 07 Maj 2015 ss programfixar, borttagning av föråldrade " +"funktioner" -#: C/gtk-doc-manual.xml:110(title) -msgid "How Does GTK-Doc Work?" -msgstr "Hur fungerar GTK-Doc?" +#. (itstool) path: revhistory/revision +#: C/index.docbook:113 +msgid "" +"1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" +msgstr "" +"1.21 17 Jul 2014 ss programfixar, borttagning av föråldrade " +"funktioner" -#: C/gtk-doc-manual.xml:112(para) -msgid "GTK-Doc works by using documentation of functions placed inside the source files in specially-formatted comment blocks, or documentation added to the template files which GTK-Doc uses (though note that GTK-Doc will only document functions that are declared in header files; it won't produce output for static functions)." +#. (itstool) path: revhistory/revision +#: C/index.docbook:119 +msgid "" +"1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" msgstr "" +"1.20 16 Feb 2014 ss programfixar, stöd för markdown, " +"stilförbättringar" -#: C/gtk-doc-manual.xml:119(para) -msgid "GTK-Doc consists of a number of perl scripts, each performing a different step in the process." +#. (itstool) path: revhistory/revision +#: C/index.docbook:125 +msgid "" +"1.19 05 Jun 2013 ss bug fixes" msgstr "" +"1.19 05 Jun 2013 ss programfixar" -#: C/gtk-doc-manual.xml:124(para) -msgid "There are 5 main steps in the process:" +#. (itstool) path: revhistory/revision +#: C/index.docbook:131 +msgid "" +"1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" msgstr "" +"1.18 14 Sep 2011 ss programfixar, uppsnabbningar, stöd för markdown" -#: C/gtk-doc-manual.xml:131(para) -msgid "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)." +#. (itstool) path: revhistory/revision +#: C/index.docbook:137 +msgid "" +"1.17 26 Feb 2011 sk urgent bug fix update" msgstr "" +"1.17 26 Feb 2011 sk brådskande programfixuppdatering" -#: C/gtk-doc-manual.xml:141(para) -msgid "Gathering information about the code.gtkdoc-scan scans the header files of the code looking for declarations of functions, macros, enums, structs, and unions. It creates the file <module>-decl-list.txt containg a list of the declarations, placing them into sections according to which header file they are in. On the first run this file is copied to <module>-sections.txt The author can rearrange the sections, and the order of the declarations within them, to produce the final desired order. The second file it generates is <module>-decl.txt. This file contains the full declarations found by the scanner. If for some reason one would like some sybols to show up in the docs, where the full declaration cannot be found by th scanner or the declaration should appear differently, one can place enties similar to the ones in <module>-decl.txt into <module>-overrides.txt. gtkdoc-scanobj can also be used to dynamically query a library about any GtkObject subclasses it exports. It saves information about each object's position in the class hierarchy and about any GTK Args and Signals it provides." +#. (itstool) path: revhistory/revision +#: C/index.docbook:143 +msgid "" +"1.16 14 Jan 2011 sk bugfixes, layout improvements" msgstr "" +"1.16 14 Jan 2011 sk programfixar, layoutförbättringar" -#: C/gtk-doc-manual.xml:166(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.)" +#. (itstool) path: revhistory/revision +#: C/index.docbook:149 +msgid "" +"1.15 21 May 2010 sk bug and regression fixes" msgstr "" +"1.15 21 Maj 2010 sk program- och regressionsfixar" -#: C/gtk-doc-manual.xml:175(para) -msgid "Since gtk-doc 1.9 the templates can be avoided. We encourage people to keep documentation in the code. gtkdocize supports now a --flavour no-tmpl option that chooses a makefile that skips tmpl usage totally. If you have never changed file in tmpl by hand, please remove the dir once." +#. (itstool) path: revhistory/revision +#: C/index.docbook:155 +msgid "" +"1.14 28 March 2010 sk bugfixes and performance improvements" msgstr "" +"1.14 28 Mars 2010 sk programfixar och prestandaförbättringar" -#: C/gtk-doc-manual.xml:185(para) -msgid "Generating the SGML/XML and HTML.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 takes docs from sources and introspection data. gtkdoc-mkhtml turns the SGML files into HTML files in the html/ subdirectory. Files in sgml/ or xml/ and html/ directories are always overwritten. One should never edit them directly." +#. (itstool) path: revhistory/revision +#: C/index.docbook:161 +msgid "" +"1.13 18 December 2009 " +"sk broken tarball update" msgstr "" +"1.13 18 December 2009 " +"sk uppdatering på grund av " +"trasigt tar-arkiv" -#: C/gtk-doc-manual.xml:205(para) -msgid "Fixing up cross-references between documents. After installing the HTML files, gtkdoc-fixxref can be run to fix up any cross-references between separate documents. For example, the GTK+ documentation contains many cross-references to types documented in the GLib manual. When creating the source tarball for distribution, gtkdoc-rebase turns all external links into web-links. When installing distributed (pregenerated) docs the same application will try to turn links back to local links (where those docs are installed)." +#. (itstool) path: revhistory/revision +#: C/index.docbook:167 +msgid "" +"1.12 18 December 2009 " +"sk new tool features and " +"bugfixes" msgstr "" +"1.12 18 December 2009 " +"sk nya verktygsfunktioner och " +"programfixar" -#: C/gtk-doc-manual.xml:223(title) -msgid "Getting GTK-Doc" -msgstr "Hämta GTK-Doc" +#. (itstool) path: revhistory/revision +#: C/index.docbook:173 +msgid "" +"1.11 16 November 2008 " +"mal GNOME doc-utils migration" +msgstr "" +"1.11 16 November 2008 " +"mal GNOME doc-utils migration" -#: C/gtk-doc-manual.xml:226(title) -msgid "Requirements" -msgstr "Krav" +#. (itstool) path: chapter/title +#: C/index.docbook:186 +msgid "Introduction" +msgstr "Introduktion" -#: C/gtk-doc-manual.xml:227(para) -msgid "Perl v5 - the main scripts are in Perl." +#. (itstool) path: chapter/para +#: C/index.docbook:188 +msgid "" +"This chapter introduces GTK-Doc and gives an overview of what it is and how " +"it is used." msgstr "" +"Detta kapitel introducerar GTK-Doc och ger en överblick över vad det är och " +"hur det används." -#: C/gtk-doc-manual.xml:230(para) -msgid "DocBook DTD v3.0 - This is the DocBook SGML DTD. http://www.ora.com/davenport" -msgstr "" +#. (itstool) path: sect1/title +#: C/index.docbook:194 +msgid "What is GTK-Doc?" +msgstr "Vad är GTK-Doc?" -#: C/gtk-doc-manual.xml:234(para) -msgid "Jade v1.1 - This is a DSSSL processor for converting SGML to various formats. http://www.jclark.com/jade" +#. (itstool) path: sect1/para +#: C/index.docbook:196 +msgid "" +"GTK-Doc is used to document C code. It is typically used to document the " +"public API of libraries, such as the GTK+ and GNOME libraries. But it can " +"also be used to document application code." msgstr "" +"GTK-Doc används för att dokumentera C-kod. Det används vanligen för att " +"dokumentera det publika API:t för bibliotek, så som GTK+- och GNOME-" +"biblioteken. Men det kan också användas för att dokumentera programkod." -#: C/gtk-doc-manual.xml:238(para) -msgid "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 "" +#. (itstool) path: sect1/title +#: C/index.docbook:204 +msgid "How Does GTK-Doc Work?" +msgstr "Hur fungerar GTK-Doc?" -#: C/gtk-doc-manual.xml:247(para) -msgid "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." +# sebras: how do I translate header files? +#. (itstool) path: sect1/para +#: C/index.docbook:206 +msgid "" +"GTK-Doc works by using documentation of functions placed inside the source " +"files in specially-formatted comment blocks, or documentation added to the " +"template files which GTK-Doc uses (though note that GTK-Doc will only " +"document functions that are declared in header files; it won't produce " +"output for static functions)." +msgstr "" +"GTK-Doc fungerar så att det använder dokumentation för funktioner placerad " +"inuti källkodsfilerna i speciellt formaterade kommentarsblock, eller " +"dokumentation som lagts till i mallfilerna som GTK-Doc använder (notera dock " +"att GTK-Doc endast kommer att dokumentera funktioner som deklarerats i " +"huvudfiler; det kommer inte att producera utdata för statiska funktioner)." + +#. (itstool) path: sect1/para +#: C/index.docbook:213 +msgid "" +"GTK-Doc consists of a number of perl scripts, each performing a different " +"step in the process." msgstr "" +"GTK-Doc består av ett antal perl-skript som vart och ett utför olika steg i " +"processen." -#: C/gtk-doc-manual.xml:258(title) -msgid "Installation" -msgstr "Installation" +#. (itstool) path: sect1/para +#: C/index.docbook:218 +msgid "There are 5 main steps in the process:" +msgstr "Det finns 5 huvudsteg i processen:" -#: C/gtk-doc-manual.xml:259(para) -msgid "There is no standard place where the DocBook Modular Stylesheets are installed." +#. (itstool) path: listitem/para +#: C/index.docbook:225 +msgid "" +"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)." +msgstr "" +"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)." + +# sebras: more header files... +#. (itstool) path: listitem/para +#: C/index.docbook:235 +msgid "" +"Gathering information about the code. " +"gtkdoc-scan scans the header files of the code " +"looking for declarations of functions, macros, enums, structs, and unions. " +"It creates the file <module>-decl-list.txt " +"containing a list of the declarations, placing them into sections according " +"to which header file they are in. On the first run this file is copied to " +"<module>-sections.txt. The author can rearrange " +"the sections, and the order of the declarations within them, to produce the " +"final desired order. The second file it generates is <" +"module>-decl.txt. This file contains the full declarations " +"found by the scanner. If for some reason one would like some symbols to show " +"up in the docs, where the full declaration cannot be found by the scanner or " +"the declaration should appear differently, one can place entities similar to " +"the ones in <module>-decl.txt into <" +"module>-overrides.txt." +msgstr "" +"Samla ihop information om koden. gtkdoc-" +"scan söker genom huvudfilerna för koden och letar efter " +"deklarationer av funktioner, makron, uppräkningar, strukturer och unioner. " +"Det skapar sedan filen <module>-decl-list.txt som " +"innehåller en lista över deklarationerna, och placerar dem i avsnitt efter " +"vilken huvudfil de finns i. Vid första körningen kommer denna fil att " +"kopieras till <module>-sections.txt. Författaren " +"kan, genom att omarrangera avsnitten och ändra ordningen för deklarationerna " +"inom dem, framställa den önskade, slutgiltiga ordningen. Den andra filen det " +"genererar är <module>-decl.txt. Denna fil " +"innehåller de fullständiga deklarationerna som hittats av detektorn. Om man " +"av något skäl vill att vissa symboler ska visas i dokumentation då den " +"fullständiga deklarationen inte kan hittas av detektorn, eller om " +"deklarationen ska visas annorlunda, kan man placera rader liknande de som " +"finns i <module>-decl.txt i <" +"module>-overrides.txt." + +#. (itstool) path: listitem/para +#: C/index.docbook:252 +msgid "" +"gtkdoc-scangobj can also be used to dynamically " +"query a library about any GObject subclasses it exports. It saves " +"information about each object's position in the class hierarchy and about " +"any GObject properties and signals it provides." +msgstr "" +"gtkdoc-scangobj kan också användas för att " +"dynamiskt fråga ett bibliotek om vilka GObject-underklasser det exporterar. " +"Det sparar information om varje objekts position i klasshierarkin och om " +"vilka GObject-egenskaper och signaler det tillhandahåller." + +#. (itstool) path: listitem/para +#: C/index.docbook:258 +msgid "" +"gtkdoc-scanobj should not be used anymore. It was " +"needed in the past when GObject was still GtkObject inside gtk+." msgstr "" +"gtkdoc-scanobj bör inte användas längre. Det " +"behövdes tidigare när GObject fortfarande var GtkObject inuti gtk+." -#: C/gtk-doc-manual.xml:262(para) -msgid "gtk-doc's configure script searches these 3 directories automatically:" +#. (itstool) path: listitem/para +#: C/index.docbook:265 +msgid "" +"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." +msgstr "" +"Generera XML och HTML/PDF. gtkdoc-mkdb förvandlar mallfilerna till XML-filer i underkatalogen " +"xml/. Om källkoden innehåller " +"dokumentation över funktioner i speciella kommentarsblock, så kommer denna " +"att sammanfogas här. Om det inte finns några tmpl-filer som används så " +"kommer det endast att läsa dokumentation från källkoden och " +"introspektionsdata." + +#. (itstool) path: listitem/para +#: C/index.docbook:274 +msgid "" +"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 förvandlar XML-filer till HTML-" +"filer i underkatalogen html/. På " +"samma sätt förvandlar gtkdoc-mkpdf XML-filerna " +"till ett PDF-dokument kallat <package>.pdf." + +#. (itstool) path: listitem/para +#: C/index.docbook:280 +msgid "" +"Files in xml/ and html/ directories are always overwritten. One " +"should never edit them directly." msgstr "" +"Filer i xml/- och html/-katalogerna skrivs alltid över. Man bör " +"aldrig redigera dem direkt." -#: C/gtk-doc-manual.xml:265(para) -msgid " /usr/lib/sgml/stylesheets/nwalsh-modular (used by RedHat)" -msgstr "" +#. (itstool) path: listitem/para +#: C/index.docbook:288 +msgid "" +"Fixing up cross-references between documents. After " +"installing the HTML files, gtkdoc-fixxref can be " +"run to fix up any cross-references between separate documents. For example, " +"the GTK+ documentation contains many cross-references to types documented in " +"the GLib manual. When creating the source tarball for distribution, " +"gtkdoc-rebase turns all external links into web-" +"links. When installing distributed (pregenerated) docs the same application " +"will try to turn links back to local links (where those docs are installed)." +msgstr "" +"Fixa korsreferenser mellan dokument. Efter att ha " +"installerat HTML-filerna kan gtkdoc-fixxref köras " +"för att fixa korsreferenser mellan separata dokument. Till exempel GTK+-" +"dokumentationen innehåller många korsreferenser till typer som dokumenterats " +"i GLib-manualen. När tar-arkivet med källkod skapas för distribution, " +"förvandlar gtkdoc-rebase alla externa länkar till " +"webblänkar. När (förgenererad) distribuerad dokumentation installeras kommer " +"samma program att försöka att förvandla länkarna tillbaka till lokala länkar " +"(i de fall där dokumentationen finns installerad)." + +#. (itstool) path: sect1/title +#: C/index.docbook:306 +msgid "Getting GTK-Doc" +msgstr "Hämta GTK-Doc" -#: C/gtk-doc-manual.xml:268(para) -msgid " /usr/lib/dsssl/stylesheets/docbook (used by Debian)" -msgstr "" +#. (itstool) path: sect2/title +#: C/index.docbook:309 +msgid "Requirements" +msgstr "Krav" + +#. (itstool) path: sect2/para +#: C/index.docbook:310 +msgid "Perl v5 - the main scripts are in Perl." +msgstr "Perl v5 - huvudskripten är skrivna i Perl." -#: C/gtk-doc-manual.xml:271(para) -msgid " /usr/share/sgml/docbkdsl (used by SuSE)" +#. (itstool) path: sect2/para +#: C/index.docbook:313 +msgid "" +"xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" msgstr "" +"xsltproc - xslt-processorn från libxslt xmlsoft.org/XSLT/" -#: C/gtk-doc-manual.xml:274(para) -msgid "If you have the stylesheets installed somewhere else, you need to configure gtk-doc using the option: --with-dsssl-dir=<PATH_TO_TOPLEVEL_STYLESHEETS_DIR> " +#. (itstool) path: sect2/para +#: C/index.docbook:317 +msgid "" +"docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" +msgstr "" +"docbook-xsl - docbook xsl-stilmallar sourceforge.net/projects/docbook/files/docbook-xsl" + +#. (itstool) path: sect2/para +#: C/index.docbook:321 +msgid "Python - optional - for gtkdoc-depscan" +msgstr "Python - valfritt - för gtkdoc-depscan" + +# sebras: remind me how was highlighting translated..? +#. (itstool) path: sect2/para +#: C/index.docbook:324 +msgid "" +"One of source-highlight, highlight " +"or vim - optional - used for syntax highlighting of " +"examples" msgstr "" +"Endera av source-highlight, highlight eller vim - valfritt - används för " +"syntaxfärgning av exempel" -#: C/gtk-doc-manual.xml:297(title) +#. (itstool) path: sect1/title +#: C/index.docbook:332 msgid "About GTK-Doc" msgstr "Om GTK-Doc" -#: C/gtk-doc-manual.xml:299(para) -#: C/gtk-doc-manual.xml:313(para) +#. (itstool) path: sect1/para +#: C/index.docbook:334 C/index.docbook:348 msgid "(FIXME)" -msgstr "" +msgstr "(FIXME)" -#: C/gtk-doc-manual.xml:303(para) -msgid "(History, authors, web pages, license, future plans, comparison with other similar systems.)" +#. (itstool) path: sect1/para +#: C/index.docbook:338 +msgid "" +"(History, authors, web pages, mailing list, license, future plans, " +"comparison with other similar systems.)" msgstr "" +"(Historia, författare, webbsidor, sändlistor, licens, framtida planer, " +"jämförelse med andra liknande system.)" -#: C/gtk-doc-manual.xml:311(title) +#. (itstool) path: sect1/title +#: C/index.docbook:346 msgid "About this Manual" msgstr "Om denna handbok" -#: C/gtk-doc-manual.xml:317(para) +#. (itstool) path: sect1/para +#: C/index.docbook:352 msgid "(who it is meant for, where you can get it, license)" -msgstr "" +msgstr "(vem är den avsett för, var kan du få tag i den, licens)" -#: C/gtk-doc-manual.xml:326(title) +#. (itstool) path: chapter/title +#: C/index.docbook:361 msgid "Setting up your project" -msgstr "" - -#: C/gtk-doc-manual.xml:328(para) -msgid "The next sections describe what steps to perform to integrate GTK-Doc into your project. Theses section assume we work on a project called 'meep'. This project contains a library called 'libmeep' and an end-user app called 'meeper'." -msgstr "" +msgstr "Att ställa in ditt projekt" -#: C/gtk-doc-manual.xml:336(title) +#. (itstool) path: chapter/para +#: C/index.docbook:363 +msgid "" +"The next sections describe what steps to perform to integrate GTK-Doc into " +"your project. Theses sections assume we work on a project called 'meep'. " +"This project contains a library called 'libmeep' and an end-user app called " +"'meeper'. We also assume you will be using autoconf and automake. In " +"addition section plain makefiles or other " +"build systems will describe the basics needed to work in a different " +"build setup." +msgstr "" +"De följande avsnitten beskriver vilka steg du måste utföra för att integrera " +"GTK-Doc i ditt projekt. Dessa avsnitt förutsätter att vi arbetar på ett " +"projekt kallat ”meep”. Detta projekt innehåller ett bibliotek kallat " +"”libmeep” och ett slutanvändarprogram kallat ”meeper”. Vi förutsätter också " +"att du kommer att använda autoconf och automake. Dessutom kommer avsnittet " +"vanliga makefiler eller andra byggsystem att beskriva de grundläggande sakerna som behöver fungera i ett annat " +"byggsystem." + +#. (itstool) path: sect1/title +#: C/index.docbook:374 msgid "Setting up a skeleton documentation" -msgstr "" - -#: C/gtk-doc-manual.xml:338(para) -msgid "Under your top-level project directory create folders called docs/reference (this way you can also have docs/help for end-user documentation). It is recommended to create another subdirectory with the name of the doc-package. For packages with just one library this step is not necessary." -msgstr "" +msgstr "Att ställa in en skelettstruktur för dokumentation" -#: C/gtk-doc-manual.xml:347(title) +#. (itstool) path: sect1/para +#: C/index.docbook:376 +msgid "" +"Under your top-level project directory create folders called docs/reference " +"(this way you can also have docs/help for end-user documentation). It is " +"recommended to create another subdirectory with the name of the doc-package. " +"For packages with just one library this step is not necessary." +msgstr "" +"Under toppnivåkatalogen för ditt projekt, skapa mappar kallade docs/" +"reference (på detta sättet kan du också ha docs/help för " +"slutanvändardokumentation). Det rekommenderas att skapa en annan " +"underkatalog med namnet på dokumentations-paketet. För paket med bara ett " +"bibliotek är detta steg inte nödvändigt." + +#. (itstool) path: example/title +#: C/index.docbook:385 msgid "Example directory structure" -msgstr "" - -#: C/gtk-doc-manual.xml:345(para) -msgid "This can then look as show below: " -msgstr "" +msgstr "Exempel på katalogstruktur" -#: C/gtk-doc-manual.xml:365(title) -#: C/gtk-doc-manual.xml:372(title) +#. (itstool) path: example/programlisting +#: C/index.docbook:386 +#, no-wrap +msgid "" +"\n" +"meep/\n" +" docs/\n" +" reference/\n" +" libmeep/\n" +" meeper/\n" +" src/\n" +" libmeep/\n" +" meeper/\n" +msgstr "" +"\n" +"meep/\n" +" docs/\n" +" reference/\n" +" libmeep/\n" +" meeper/\n" +" src/\n" +" libmeep/\n" +" meeper/\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:383 +msgid "This can then look as shown below: <_:example-1/>" +msgstr "Detta kan se ut enligt nedan: <_:example-1/>" + +#. (itstool) path: sect1/title +#. (itstool) path: example/title +#: C/index.docbook:401 C/index.docbook:408 msgid "Integration with autoconf" -msgstr "" - -#: C/gtk-doc-manual.xml:367(para) -msgid "Very easy! Just add one line to your configure.ac script." -msgstr "" +msgstr "Integrering med autoconf" -#: C/gtk-doc-manual.xml:382(para) -msgid "Besides checking for the required Gtk-Doc version, this adds two configure switches:" +#. (itstool) path: sect1/para +#: C/index.docbook:403 +msgid "" +"Very easy! Just add one line to your configure.ac " +"script." msgstr "" +"Väldigt enkelt! Bara lägg till en rad till ditt configure.ac-skript." -#: C/gtk-doc-manual.xml:387(para) +#. (itstool) path: example/programlisting +#: C/index.docbook:409 +#, no-wrap +msgid "" +"\n" +"# check for gtk-doc\n" +"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" +msgstr "" +"\n" +"# check for gtk-doc\n" +"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" + +#. (itstool) path: example/title +#: C/index.docbook:421 +msgid "Keep gtk-doc optional" +msgstr "Låt gtk-doc vara valfritt" + +#. (itstool) path: example/programlisting +#: C/index.docbook:422 +#, no-wrap +msgid "" +"\n" +"# check for gtk-doc\n" +"m4_ifdef([GTK_DOC_CHECK], [\n" +"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" +"],[\n" +"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n" +"])\n" +msgstr "" +"\n" +"# check for gtk-doc\n" +"m4_ifdef([GTK_DOC_CHECK], [\n" +"GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" +"],[\n" +"AM_CONDITIONAL([ENABLE_GTK_DOC], false)\n" +"])\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:416 +msgid "" +"This will require all developers to have gtk-doc installed. If it is okay " +"for your project to have optional api-doc build setup, you can solve this as " +"below. Keep it as is, as gtkdocize is looking for GTK_DOC_CHECK at the start of a line. <_:example-1/>" +msgstr "" +"Detta kommer att kräva att alla utvecklare har gtk-doc installerat. Om det " +"är okej för ditt projekt att ha ett valfritt api-dokumentation bygge, kan du " +"lösa det enligt nedan. Behåll det som det är eftersom gtkdocize letar efter " +"GTK_DOC_CHECK i början på en rad. <_:example-1/>" + +# sebras: or ? +#. (itstool) path: sect1/para +#: C/index.docbook:433 +msgid "" +"The first argument is used to check for the gtkdocversion at configure time. " +"The 2nd, optional argument is used by gtkdocize. " +"The GTK_DOC_CHECK macro also adds several configure " +"switches:" +msgstr "" +"Det första argumentet används för att leta efter gtkdoc-versionen under " +"konfigurationen. Det andra, valfria, argumentet används av " +"gtkdocize. Makrot GTK_DOC_CHECK " +"lägger också till flera configure-flaggor:" + +#. (itstool) path: listitem/para +#: C/index.docbook:439 msgid "--with-html-dir=PATH : path to installed docs" -msgstr "" +msgstr "--with-html-dir=SÖKVÄG : sökväg till installerad dokumentation" -#: C/gtk-doc-manual.xml:388(para) -msgid "--enable-gtk-doc : use gtk-doc to build documentation" +#. (itstool) path: listitem/para +#: C/index.docbook:440 +msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "" +"--enable-gtk-doc : använd gtk-doc för att bygga dokumentation " +"[standardvärde=no]" -#: C/gtk-doc-manual.xml:392(para) -msgid "Gtk-Doc is disabled by default! Remember to pass the option to the next configure run. Otherwise pregenerated documentation is installed (which makes sense for users but not for developers)." +#. (itstool) path: listitem/para +#: C/index.docbook:441 +msgid "" +"--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" +"--enable-gtk-doc-html : bygg dokumentation i html-format [standardvärde=yes]" -#: C/gtk-doc-manual.xml:400(para) -msgid "Furthermore it is recommended that you have the following line inside you configure.ac script. This allows gtkdocize to automatically copy the macro definition for GTK_DOC_CHECK to your project." +#. (itstool) path: listitem/para +#: C/index.docbook:442 +msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" msgstr "" +"--enable-gtk-doc-pdf : bygg dokumentation i pdf-format [standardvärde=no]" -#: C/gtk-doc-manual.xml:408(title) +#. (itstool) path: important/para +#: C/index.docbook:446 +msgid "" +"GTK-Doc is disabled by default! Remember to pass the option to the next configure run. " +"Otherwise pregenerated documentation is installed (which makes sense for " +"users but not for developers)." +msgstr "" +"GTK-Doc är inaktiverat som standard! Kom ihåg att skicka flaggan 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)." + +#. (itstool) path: sect1/para +#: C/index.docbook:454 +msgid "" +"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." +msgstr "" +"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." + +#. (itstool) path: example/title +#: C/index.docbook:462 msgid "Preparation for gtkdocize" msgstr "Förberedelse för gtkdocize" -#: C/gtk-doc-manual.xml:419(title) -msgid "Integration with automake" -msgstr "Integration med automake" - -#: C/gtk-doc-manual.xml:421(para) -msgid "First copy the 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." -msgstr "" - -#: C/gtk-doc-manual.xml:428(para) -msgid "The next step is to edit the setting 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." +#. (itstool) path: example/programlisting +#: C/index.docbook:463 +#, no-wrap +msgid "" +"\n" +"AC_CONFIG_MACRO_DIR(m4)\n" msgstr "" +"\n" +"AC_CONFIG_MACRO_DIR(m4)\n" -#. FIXME: explain options ? -#: C/gtk-doc-manual.xml:439(para) -msgid "You may also want to enable gtk-doc for the distcheckmake target. Just add then one-liner show in the next example to you top-level Makefile.am:" +#. (itstool) path: sect1/para +#: C/index.docbook:468 +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 "" +"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." -#: C/gtk-doc-manual.xml:446(title) -msgid "Enable gtk-doc during make distcheck" -msgstr "" +#. (itstool) path: sect1/title +#: C/index.docbook:476 +msgid "Integration with automake" +msgstr "Integrering med automake" -#: C/gtk-doc-manual.xml:458(title) +#. (itstool) path: sect1/para +#: C/index.docbook:478 +msgid "" +"First copy the 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 "" +"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." + +#. (itstool) path: sect1/para +#: C/index.docbook:489 +msgid "" +"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." +msgstr "" +"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." + +#. (itstool) path: sect1/title +#: C/index.docbook:503 msgid "Integration with autogen" -msgstr "" +msgstr "Integrering med autogen" -#: C/gtk-doc-manual.xml:460(para) -msgid "Most projects will have an autogen.sh script to setup the build infrastructure after a checkout from version control system (such as cvs). 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." -msgstr "" - -#: C/gtk-doc-manual.xml:469(title) +#. (itstool) path: sect1/para +#: C/index.docbook:505 +msgid "" +"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." +msgstr "" +"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." + +#. (itstool) path: example/title +#: C/index.docbook:514 msgid "Running gtkdocize from autogen.sh" -msgstr "" +msgstr "Köra gtkdocize från autogen.sh" -#: C/gtk-doc-manual.xml:478(para) -msgid "When running gtkdocize it copies gtk-doc.make to you project root (or any directory specified by the --docdir option). If also check you configure script for the GTK_DOC_CHECK invocation." -msgstr "" - -#: C/gtk-doc-manual.xml:485(para) -msgid "Historically gtk-doc was gerating template files where developers entered the docs. this turned out to be not so good. Since a few version gtk-doc could also get all the information from source comments. Since gtk-doc 1.9 the templates can be avoided. We encourage people to keep documentation in the code. gtkdocize supports now a --flavour=no-tmpl option that chooses a makefile that skips tmpl usage totally. If you have never changed file in tmpl by hand, please remove the dir once." +#. (itstool) path: example/programlisting +#: C/index.docbook:515 +#, no-wrap +msgid "" +"\n" +"gtkdocize || exit 1\n" msgstr "" +"\n" +"gtkdocize || exit 1\n" -#: C/gtk-doc-manual.xml:497(title) -#: C/gtk-doc-manual.xml:514(title) +#. (itstool) path: sect1/para +#: C/index.docbook:521 +msgid "" +"When running 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." +msgstr "" +"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." + +# 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:530 +msgid "" +"Historically GTK-Doc was generating template files where developers entered " +"the docs. This turned out to be not so good (e.g. the need for having " +"generated files under version control). Since GTK-Doc 1.9 the tools can get " +"all the information from source comments and thus the templates can be " +"avoided. We encourage people to keep documentation in the code. " +"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)." +msgstr "" +"Historiskt genererade GTK-Doc mallfiler i vilka utvecklare skrev in " +"dokumentationen. Detta visade sig inte vara så bra (t.ex. på grund av " +"behovet att ha genererade filer under versionskontroll). Sedan GTK-Doc 1.9 " +"kan verktygen hämta all information från källkodskommentarer och mallar kan " +"därför undvikas. Vi rekommenderar att hålla dokumentationen i koden. " +"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)." + +#. (itstool) path: sect1/title +#. (itstool) path: example/title +#: C/index.docbook:547 C/index.docbook:564 msgid "Running the doc build" -msgstr "" - -#: C/gtk-doc-manual.xml:499(para) -msgid "After the previous steps it's time to run the build. First we need to rerun autogen.sh. If this script runs configure for you, then give it the option. Otherwise manually run configure with this option afterwards." -msgstr "" +msgstr "Att köra dokumentationsbygget" -#: C/gtk-doc-manual.xml:506(para) -msgid "The first make run generates several additional files in the doc-dirs. The important ones are: <package>.types, <package>-docs.sgml, <package>-sections.txt." +#. (itstool) path: sect1/para +#: C/index.docbook:549 +msgid "" +"After the previous steps it's time to run the build. First we need to rerun " +"autogen.sh. If this script runs configure for you, then " +"give it the option. Otherwise manually run " +"configure with this option afterwards." +msgstr "" +"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." + +#. (itstool) path: sect1/para +#: C/index.docbook:556 +msgid "" +"The first make run generates several additional files in the doc-" +"directories. The important ones are: <package>.types, <package>-docs.xml (in the past ." +"sgml), <package>-sections.txt." +msgstr "" +"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." + +#. (itstool) path: example/programlisting +#: C/index.docbook:565 +#, no-wrap +msgid "" +"\n" +"./autogen.sh --enable-gtk-doc\n" +"make\n" msgstr "" +"\n" +"./autogen.sh --enable-gtk-doc\n" +"make\n" -#: C/gtk-doc-manual.xml:523(para) -msgid "Now you can point your browser to 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." +#. (itstool) path: sect1/para +#: C/index.docbook:571 +msgid "" +"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." msgstr "" +"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." -#: C/gtk-doc-manual.xml:531(title) +#. (itstool) path: sect1/title +#: C/index.docbook:579 msgid "Integration with version control systems" -msgstr "" +msgstr "Integrering med versionshanteringssystem" -#: C/gtk-doc-manual.xml:533(para) -msgid "As a rule of the thumb, it's those files you edit, that should go under version control. For typical projects it's these files: <package>.types<package>-docs.sgml<package>-sections.txtMakefile.am" +#. (itstool) path: sect1/para +#: C/index.docbook:581 +msgid "" +"As a rule of thumb, it's the files you edit which should go under version " +"control. For typical projects it's these files: <package>." +"types, <package>-docs.xml (in the " +"past .sgml), <package>-sections.txt, " +"Makefile.am." +msgstr "" +"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." + +#. (itstool) path: sect1/para +#: C/index.docbook:589 +msgid "" +"Files in the xml/ and html/ " +"directories should not go under version control. Neither should any of the " +".stamp files." msgstr "" +"Filer i katalogerna xml/ och html/ " +"bör inte versionshanteras. Detsamma gäller .stamp-" +"filerna." -#: C/gtk-doc-manual.xml:546(title) -msgid "Documenting the code" -msgstr "" +#. (itstool) path: sect1/title +#: C/index.docbook:597 +msgid "Integration with plain makefiles or other build systems" +msgstr "Integrering med vanliga makefiler eller andra byggsystem" -#: C/gtk-doc-manual.xml:548(para) -msgid "GTK-Doc uses source code comment with a special syntax for code documentation. Further it retrieves information about your project structure from other sources. During the next section you find all information about the syntax of the comments." +#. (itstool) path: sect1/para +#: C/index.docbook:599 +msgid "" +"In the case one does not want to use automake and therefore gtk-" +"doc.mak one will need to call the gtkdoc tools in the right order " +"in own makefiles (or other build tools)." +msgstr "" +"I det fall man inte vill använda automake och därför inte heller " +"gtk-doc.mak kommer man att behöva anropa gtkdoc-" +"verktygen i rätt ordning i sina egna makefiler (eller andra byggverktyg)." + +#. (itstool) path: example/title +#: C/index.docbook:606 +msgid "Documentation build steps" +msgstr "Byggsteg för dokumentation" + +#. (itstool) path: example/programlisting +#: C/index.docbook:607 +#, no-wrap +msgid "" +"\n" +"DOC_MODULE=meep\n" +"// sources have changed\n" +"gtkdoc-scan --module=$(DOC_MODULE) <source-dir>\n" +"gtkdoc-scangobj --module=$(DOC_MODULE)\n" +"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>\n" +"// xml files have changed\n" +"mkdir html\n" +"cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n" +"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" +msgstr "" +"\n" +"DOC_MODULE=meep\n" +"// källkod har ändrats\n" +"gtkdoc-scan --module=$(DOC_MODULE) <källkodskatalog>\n" +"gtkdoc-scangobj --module=$(DOC_MODULE)\n" +"gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<källkodskatalog>\n" +"// xml-filer har ändrats\n" +"mkdir html\n" +"cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml\n" +"gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:621 +msgid "" +"One will need to look at the Makefile.am and " +"gtk-doc.mak to pick the extra options needed." msgstr "" +"Man kommer att behöva titta i Makefile.am och " +"gtk-doc.mak för att plocka ut de extra flaggor som " +"behövs." -#: C/gtk-doc-manual.xml:556(title) -msgid "Documentation placement" -msgstr "" +#. (itstool) path: sect1/title +#: C/index.docbook:628 +msgid "Integration with CMake build systems" +msgstr "Integrering med CMake-byggsystem" -#: C/gtk-doc-manual.xml:557(para) -msgid "In the past most documentation had to be filled into files residing inside the 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." -msgstr "" +#. (itstool) path: sect1/para +#: C/index.docbook:630 +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 "" +"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." + +#. (itstool) path: example/title +#: C/index.docbook:640 +msgid "Example of using GTK-Doc from CMake" +msgstr "Exempel på användning av GTK-Doc från CMake" + +#. (itstool) path: example/programlisting +#: C/index.docbook:641 +#, no-wrap +msgid "" +"\n" +"find_package(GtkDoc 1.25 REQUIRED)\n" +"\n" +"# Create the doc-libmeep target.\n" +"gtk_doc_add_module(\n" +" libmeep ${CMAKE_SOURCE_DIR}/libmeep\n" +" XML meep-docs.xml\n" +" LIBRARIES libmeep\n" +")\n" +"\n" +"# Build doc-libmeep as part of the default target. Without this, you would\n" +"# have to explicitly run something like `make doc-libmeep` to build the docs.\n" +"add_custom_target(documentation ALL DEPENDS doc-libmeep)\n" +"\n" +"# Install the docs. (This assumes you're using the GNUInstallDirs CMake module\n" +"# to set the CMAKE_INSTALL_DOCDIR variable correctly).\n" +"install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html\n" +" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" +msgstr "" +"\n" +"find_package(GtkDoc 1.25 REQUIRED)\n" +"\n" +"# Skapa målet doc-libmeep.\n" +"gtk_doc_add_module(\n" +" libmeep ${CMAKE_SOURCE_DIR}/libmeep\n" +" XML meep-docs.xml\n" +" LIBRARIES libmeep\n" +")\n" +"\n" +"# Bygg doc-libmeep som standardmålet. Utan detta måste du uttryckligen\n" +"# köra något i stil med `make doc-libmeep` för att bygga dokumentationen.\n" +"add_custom_target(documentation ALL DEPENDS doc-libmeep)\n" +"\n" +"# Installera dokumentationen. (Detta förutsätter att du använder CMake-modulen\n" +"# GNUInstallDirs för att ställa in variabeln CMAKE_INSTALL_DOCDIR korrekt).\n" +"install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html\n" +" DESTINATION ${CMAKE_INSTALL_DOCDIR})\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:638 +msgid "The following example shows how to use this command. <_:example-1/>" +msgstr "" +"Det följande exemplet visar hur du använder detta kommando. <_:example-1/>" + +#. (itstool) path: chapter/title +#: C/index.docbook:666 +msgid "Documenting the code" +msgstr "Att dokumentera koden" + +#. (itstool) path: chapter/para +#: C/index.docbook:668 +msgid "" +"GTK-Doc uses source code comment with a special syntax for code " +"documentation. Further it retrieves information about your project structure " +"from other sources. During the next section you will find all information " +"about the syntax of the comments." +msgstr "" +"GTK-Doc använder källkodskommentarer med en speciell syntax för " +"koddokumentation. Vidare så hämtar det information om din projektstruktur " +"från olika källor. Under nästa avsnitt kommer du att hitta information om " +"syntaxen i kommentarerna." + +#. (itstool) path: note/title +#: C/index.docbook:676 +msgid "Documentation placement" +msgstr "Dokumentationsplacering" -#: C/gtk-doc-manual.xml:563(para) -msgid "The avoid the aforementioned problems we suggest putting the documentation inside the sources. This manual will only describe this way of documenting code." +#. (itstool) path: note/para +#: C/index.docbook:677 +msgid "" +"In the past most documentation had to be filled into files residing inside " +"the 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." +msgstr "" +"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." + +#. (itstool) path: note/para +#: C/index.docbook:683 +msgid "" +"The avoid the aforementioned problems we suggest putting the documentation " +"inside the sources. This manual will only describe this way of documenting " +"code." +msgstr "" +"För att undvika de nämnda problemen föreslår vi att placera dokumentationen " +"i källkoden. Denna manual kommer endast att beskriva detta sättet att " +"dokumentera kod." + +#. (itstool) path: example/title +#: C/index.docbook:694 C/index.docbook:720 +msgid "GTK-Doc comment block" +msgstr "GTK-Doc-kommentarsblock" + +#. (itstool) path: example/programlisting +#: C/index.docbook:695 +#, no-wrap +msgid "" +"\n" +"#ifndef __GTK_DOC_IGNORE__\n" +"/* unparseable code here */\n" +"#endif\n" +msgstr "" +"\n" +"#ifndef __GTK_DOC_IGNORE__\n" +"/* unparseable code here */\n" +"#endif\n" + +#. (itstool) path: chapter/para +#: C/index.docbook:690 +msgid "" +"The scanner can handle the majority of C headers fine. In the case of " +"receiving warnings from the scanner that look like a special case, one can " +"hint GTK-Doc to skip over them. <_:example-1/>" +msgstr "" +"Detektorn kan hantera majoriteten av C-huvuden bra. I det fall när du får " +"varningar från detektorn som ser ut som ett specialfall, kan du tipsa GTK-" +"Doc att hoppa över dem. <_:example-1/>" + +#. (itstool) path: note/title +#: C/index.docbook:704 +msgid "Limitations" +msgstr "Begränsningar" + +# sebras: no 's in the original +#. (itstool) path: note/para +#: C/index.docbook:705 +msgid "" +"Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but " +"not #if !defined(__GTK_DOC_IGNORE__) or other combinations." msgstr "" +"Notera att GTK-Doc har stöd för #ifndef(__GTK_DOC_IGNORE__) men " +"inte #if !defined(__GTK_DOC_IGNORE__) eller andra kombinationer." -#: C/gtk-doc-manual.xml:573(title) +#. (itstool) path: sect1/title +#: C/index.docbook:715 msgid "Documentation comments" -msgstr "" +msgstr "Dokumentationskommentarer" -#: C/gtk-doc-manual.xml:578(title) -msgid "Gtk-Doc comment block" +#. (itstool) path: example/programlisting +#: C/index.docbook:721 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * identifier:\n" +" * documentation ...\n" +" */\n" +msgstr "" +"\n" +"/**\n" +" * identifierare:\n" +" * dokumentation …\n" +" */\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:717 +msgid "" +"A multiline comment that starts with an additional '*' marks a documentation " +"block that will be processed by the GTK-Doc tools. <_:example-1/>" msgstr "" +"En flerradskommentar som börjar med en extra ”*” markerar ett " +"dokumentationsblock som kommer att hanteras av GTK-Doc-verktygen. <_:" +"example-1/>" -#: C/gtk-doc-manual.xml:575(para) -msgid "A multiline comment that starts with an additional '*' marks a documentation block that will be processed by the Gtk-Doc tools. " +#. (itstool) path: sect1/para +#: C/index.docbook:730 +msgid "" +"The 'identifier' is one line with the name of the item the comment is " +"related to. The syntax differs a little depending on the item. (TODO add " +"table showing identifiers)" msgstr "" +"'Identifierare' är en rad med namnet på det objekt som kommentaren är " +"relaterad till. Syntaxen skiljer sig lite beroende på objekt. (TODO lägg " +"till tabell som visar identifierare)" -#: C/gtk-doc-manual.xml:590(para) -msgid "The 'identifier' is one line with the name of the item the comment is related to. The syntax differs a little depending on the item. (TODO add table showing identifiers)" +#. (itstool) path: sect1/para +#: C/index.docbook:736 +msgid "" +"The 'documentation' block is also different for each symbol type. Symbol " +"types that get parameters such as functions or macros have the parameter " +"description first followed by a blank line (just a '*'). Afterwards follows " +"the detailed description. All lines (outside program listings and CDATA " +"sections) just containing a ' *' (blank-asterisk) are converted to paragraph " +"breaks. If you don't want a paragraph break, change that into ' * ' (blank-" +"asterisk-blank-blank). This is useful in preformatted text (code listings)." +msgstr "" +"Blocket 'dokumentation' skiljer sig också för varje symboltyp. Symboltyper " +"som får parametrar så som funktioner eller makron har en " +"parameterbeskrivning först, åtföljd av en blankrad (bara en ”*”). Efteråt " +"följer den detaljerade beskrivningen. Alla rader (utanför programlistningar " +"och CDATA-avsnitt) som endast innehåller ” *” (blanksteg-asterisk) " +"konverteras till styckeavgränsare. Om du inte vill ha en styckeavgränsare, " +"ändra till ” * ” (blanksteg-asterisk-blanksteg-blanksteg). Detta är " +"användbart i förformaterad text (kodlistningar)." + +#. (itstool) path: listitem/para +#: C/index.docbook:753 +msgid "" +"What it is: The name for a class or function can sometimes be misleading for " +"people coming from a different background." msgstr "" +"Vad är detta: Namnet på en klass eller en funktion kan ibland vara " +"vilseledande för personer med annan bakgrund." -#: C/gtk-doc-manual.xml:596(para) -msgid "The 'documentation' block is also different for each symbol type. Symbol types that get parameters such as functions or macros have the parameter description first followed by a blank line (just a '*'). Afterwards follows the detailed description. All lines (outside program- listings and CDATA sections) just containing a ' *' (blank-asterisk) are converted to paragraph breaks. If you don't want a paragraph break, change that into ' * ' (blank-asterisk-blank-blank)." +#. (itstool) path: listitem/para +#: C/index.docbook:759 +msgid "" +"What it does: Tell about common uses. Put it in relation with the other API." msgstr "" +"Vad gör det: Berättar om vanliga användningsfall. Sätter det i relation med " +"det andra API:t." + +#. (itstool) path: tip/para +#: C/index.docbook:749 +msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" +msgstr "När du dokumenterar kod, beskriv två aspekter: <_:itemizedlist-1/>" -#: C/gtk-doc-manual.xml:613(para) +#. (itstool) path: listitem/para +#: C/index.docbook:774 msgid "Use function() to refer to functions or macros which take arguments." msgstr "" +"Använd funktion() för att referera till funktioner eller makron som tar " +"argument." -#: C/gtk-doc-manual.xml:618(para) -msgid "Use @param to refer to parameters. Also use this when referring to parameters of other functions, related to the one being described." +#. (itstool) path: listitem/para +#: C/index.docbook:779 +msgid "" +"Use @param to refer to parameters. Also use this when referring to " +"parameters of other functions, related to the one being described." msgstr "" +"Använd @param för att referera till parametrar. Använd också detta när du " +"refererar till parametrar för andra funktioner, relaterade till den som " +"beskrivs." -#: C/gtk-doc-manual.xml:624(para) +#. (itstool) path: listitem/para +#: C/index.docbook:785 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "" +"Använd %konstant för att referera till en konstant, t.ex. %G_TRAVERSE_LEAFS." -#: C/gtk-doc-manual.xml:629(para) -msgid "Use #symbol to refer to other types of symbol, e.g. structs and enums and macros which don't take arguments." +#. (itstool) path: listitem/para +#: C/index.docbook:790 +msgid "" +"Use #symbol to refer to other types of symbol, e.g. structs and enums and " +"macros which don't take arguments." msgstr "" +"Använd #symbol för att referera till andra typer av symboler, t.ex. " +"strukturer eller uppräkningar och makron som inte tar argument." -#: C/gtk-doc-manual.xml:635(para) -msgid "Use #Object::signal to refer to a GObject signal" -msgstr "" +#. (itstool) path: listitem/para +#: C/index.docbook:796 +msgid "Use #Object::signal to refer to a GObject signal." +msgstr "Använd #Objekt::signal för att referera till en GObject-signal." -#: C/gtk-doc-manual.xml:640(para) -msgid "Use #Object:property to refer to a GObject property" -msgstr "" +#. (itstool) path: listitem/para +#: C/index.docbook:801 +msgid "Use #Object:property to refer to a GObject property." +msgstr "Använd #Objekt:egenskap för att referera till en GObject-egenskap." -#: C/gtk-doc-manual.xml:645(para) -msgid "Use #Struct.field to refer to a field inside a structure." +#. (itstool) path: listitem/para +#: C/index.docbook:806 +msgid "" +"Use #Struct.field to refer to a field inside a structure and #GObjectClass." +"foo_bar() to refer to a vmethod." msgstr "" +"Använd #Struktur.fält för att referera till ett fält inuti en struktur och " +"#GObjectKlass.foo_bar() för att referera till en virtuell metod." -#: C/gtk-doc-manual.xml:607(para) -msgid "One advantage of hyper-text over plain-text is the ability to have links in the document. Writing the correct markup for a link can be tedious though. Gtk-Doc comes to help by providing several useful abbreviations. " +#. (itstool) path: sect1/para +#: C/index.docbook:768 +msgid "" +"One advantage of hyper-text over plain-text is the ability to have links in " +"the document. Writing the correct markup for a link can be tedious though. " +"GTK-Doc comes to help by providing several useful abbreviations. <_:" +"itemizedlist-1/>" +msgstr "" +"En fördel med hypertext framför vanlig text är möjligheten att ha länkar i " +"dokumentet. Att skriva korrekta taggar för en länk kan dock vara tröttsamt. " +"GTK-Doc hjälper då till med att tillhandahålla flera användbara " +"förkortningar. <_:itemizedlist-1/>" + +#. (itstool) path: tip/para +#: C/index.docbook:815 +msgid "" +"If you need to use the special characters '<', '>', '()', '@', '%', or " +"'#' in your documentation without GTK-Doc changing them you can use the XML " +"entities \"&lt;\", \"&gt;\", \"&lpar;\", \"&rpar;\", \"&" +"commat;\", \"&percnt;\" and \"&num;\" respectively or escape them " +"with a backslash '\\'." +msgstr "" +"Om du behöver använda specialtecken ”<”, ”>”, ”()”, ”@”, ”%” eller ”#” " +"i din dokumentation utan att GTK-Doc ändrar dem kan du använda XML-" +"entiteterna ”&lt;”, ”&gt;”, ”&lpar;”, ”&rpar;”, ”&" +"commat;”, ”&percnt;” respektive ”&num;” eller använda " +"kontrollsekvensen ”\\”." + +#. (itstool) path: sect1/para +#: C/index.docbook:824 +msgid "" +"DocBook can do more than just links. One can also have lists, examples, " +"headings, and images. As of version 1.20, the preferred way is to use a " +"subset of the basic text formatting syntax called Markdown. On older GTK-Doc " +"versions any documentation that includes Markdown will be rendered as is. " +"For example, list items will appear as lines starting with a dash." +msgstr "" +"DocBook kan mer än bara länkar. Du kan också ha listor, exempel, rubriker " +"och bilder. Från och med version 1.20, är det föredragna sättet att använda " +"en delmängd av den grundläggande textformateringssyntaxen som kallas Markdown. Äldre " +"GTK-Doc-versioner kommer dokumentation som inkluderar markdown att renderas " +"som den är. Till exempel kommer listobjekt att visas som att de börjar med " +"ett bindestreck." + +#. (itstool) path: sect1/para +#: C/index.docbook:835 +msgid "" +"While markdown is now preferred one can mix both. One limitation here is " +"that one can use docbook xml within markdown, but markdown within docbook " +"xml is not supported." msgstr "" +"Då markdown numera föredras kan du blanda båda. En begränsning här är att du " +"kan använda docbook-xml inuti markdown, men markdown inuti docbook-xml stöds " +"inte." -#: C/gtk-doc-manual.xml:653(para) -msgid "If you need to use the special characters '()', '@', '%', or '#' in your documentation without gtk-doc changing them you can use the XML entities \"&lpar;\", \"&rpar;\", \"&commat;\", \"&percnt;\" and \"&num;\" respectively or escape them with a backslash '\\'." +#. (itstool) path: sect1/para +#: C/index.docbook:841 +msgid "" +"In older GTK-Doc releases, if you need support for additional formatting, " +"you would need to enable the usage of docbook XML tags inside doc-comments " +"by putting (or ) in " +"the variable MKDB_OPTIONS inside Makefile.am." +msgstr "" +"I äldre GTK-Doc-versioner var du tvungen, om du ville ha stöd för " +"ytterligare formatering, att aktivera användningen av docbook-XML-taggar " +"inuti dok-kommentarer genom att lägga till " +"(eller ) i variabeln MKDB_OPTIONS inuti Makefile.am." + +# sebras: markdown or Markdown? +#. (itstool) path: example/title +#: C/index.docbook:850 +msgid "GTK-Doc comment block using Markdown" +msgstr "GTK-Doc-kommentarsblock som använder Markdown" + +#. (itstool) path: example/programlisting +#: C/index.docbook:851 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * identifier:\n" +" *\n" +" * documentation paragraph ...\n" +" *\n" +" * # Sub Heading #\n" +" *\n" +" * ## Second Sub Heading\n" +" *\n" +" * # Sub Heading With a Link Anchor # {#heading-two}\n" +" *\n" +" * more documentation:\n" +" *\n" +" * - list item 1\n" +" *\n" +" * Paragraph inside a list item.\n" +" *\n" +" * - list item 2\n" +" *\n" +" * 1. numbered list item\n" +" *\n" +" * 2. another numbered list item\n" +" *\n" +" * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)\n" +" *\n" +" * ![an inline image](plot-result.png)\n" +" *\n" +" * [A link to the heading anchor above][heading-two]\n" +" *\n" +" * A C-language example:\n" +" * |[<!-- language=\"C\" -->\n" +" * GtkWidget *label = gtk_label_new (\"Gorgeous!\");\n" +" * ]|\n" +" */\n" +msgstr "" +"\n" +"/**\n" +" * Identifierare:\n" +" *\n" +" * stycke med dokumentation …\n" +" *\n" +" * # Underrubrik #\n" +" *\n" +" * ## Underunderrubrik\n" +" *\n" +" * # Underrubrik med länkankare # {#andra-rubriken}\n" +" *\n" +" * mer dokumentation:\n" +" *\n" +" * - listobjekt 1\n" +" *\n" +" * Stycke inuti listobjekt.\n" +" *\n" +" * - listobjekt 2\n" +" *\n" +" * 1. numrerat listobjekt\n" +" *\n" +" * 2. ytterligare ett numrerat listobjekt\n" +" *\n" +" * Ett annat stycke. [En länk till GNOME:s webbplats](http://www.gnome.org/)\n" +" *\n" +" * ![en bild](resultatgraf.png)\n" +" *\n" +" * [En länk till rubrikankaret ovan][andra-rubriken]\n" +" *\n" +" * Ett C-exempel:\n" +" * |[<!-- language=\"C\" -->\n" +" * GtkWidget *label = gtk_label_new (\"Vackert!\");\n" +" * ]|\n" +" */\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:890 +msgid "" +"More examples of what markdown tags are supported can be found in the GTK+ Documentation Markdown Syntax Reference." msgstr "" +"Fler exempel på vilka markdown-taggar som stöds hittas i Referensen för GTK+-dokumentationens markdown-syntax." -#: C/gtk-doc-manual.xml:662(para) -msgid "DocBook can do more that just links. One can also have lists, tables and examples. To enable the usage of SGML/XML tags inside doc-comments you need to have in the variable MKDB_OPTIONS inside Makefile.am." -msgstr "" +#. (itstool) path: tip/para +#: C/index.docbook:896 +msgid "" +"As already mentioned earlier GTK-Doc is for documenting public API. Thus one " +"cannot write documentation for static symbols. Nevertheless it is good to " +"comment those symbols too. This helps other to understand you code. " +"Therefore we recommend to comment these using normal comments (without the " +"2nd '*' in the first line). If later the function needs to be made public, " +"all one needs to do is to add another '*' in the comment block and insert " +"the symbol name at the right place inside the sections file." +msgstr "" +"Som redan nämnts är GTK-Doc avsett för att dokumentera publika API:er. Du " +"kan därför inte skriva dokumentation för statiska symboler. Likväl är det " +"bra att kommentera dessa symboler. Det hjälper andra att förstå din kod. " +"Därför rekommenderar vi att du kommenterar dessa med normala kommenterar " +"(utan den andra ”*” på den första raden). Om funktionen vid ett senare " +"tillfälle måste göras publik är allt du behöver göra att lägga till " +"ytterligare en ”*” i kommentarsblocket och infoga symbolnamnet på rätt " +"ställe i avsnittsfilen." + +#. (itstool) path: sect1/title +#: C/index.docbook:910 +msgid "Documenting sections" +msgstr "Dokumentationsavsnitt" -#: C/gtk-doc-manual.xml:670(para) -msgid "As already mentioned earlier Gtk-Doc is for documenting public API. Thus one cannot write documentation for static symbols. Nevertheless it is good to comment those symbols too. This helps other to understand you code. Therefore we recommend to comment these using normal comments (without the 2nd '*' in the first line). If later the function needs to be made public, all one needs to do is to add another '*' in the comment block and insert the symbol name at the right place inside the sections file." -msgstr "" +#. (itstool) path: sect1/para +#: C/index.docbook:912 +msgid "" +"Each section of the documentation contains information about one class or " +"module. To introduce the component one can write a section block. The short " +"description is also used inside the table of contents. All the @fields are " +"optional." +msgstr "" +"Varje avsnitt av dokumentation innehåller information om en klass eller en " +"modul. För att introducera komponenten kan man skriva ett avsnittsblock. Den " +"korta beskrivningen används också i innehållsförteckningen. Alla @fälten är " +"valfria." + +#. (itstool) path: example/title +#: C/index.docbook:920 +msgid "Section comment block" +msgstr "Kommentarsblock för avsnitt" -#: C/gtk-doc-manual.xml:684(title) -msgid "Documenting sections" -msgstr "" +#. (itstool) path: example/programlisting +#: C/index.docbook:921 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * SECTION:meepapp\n" +" * @short_description: the application class\n" +" * @title: Meep application\n" +" * @section_id:\n" +" * @see_also: #MeepSettings\n" +" * @stability: Stable\n" +" * @include: meep/app.h\n" +" * @image: application.png\n" +" *\n" +" * The application class handles ...\n" +" */\n" +msgstr "" +"\n" +"/**\n" +" * SECTION:meepapp\n" +" * @short_description: programklassen\n" +" * @title: Meep-programmet\n" +" * @section_id:\n" +" * @see_also: #MeepSettings\n" +" * @stability: Stable\n" +" * @include: meep/app.h\n" +" * @image: application.png\n" +" *\n" +" * Programklassen hanterar …\n" +" */\n" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:940 +msgid "SECTION:<name>" +msgstr "SECTION:<namn>" + +#. (itstool) path: listitem/para +#: C/index.docbook:942 +msgid "" +"The name links the section documentation to the respective part in the " +"<package>-sections.txt file. The name given here " +"should match the <FILE> tag in the <package>-sections." +"txt file." +msgstr "" +"Namnet länkar till avsnittsdokumentationen för respektive del i filen " +"<paket>-sections.txt. Namnet som anges här bör " +"matcha taggen <FILE> i filen <paket>-sections.txt." + +#. (itstool) path: varlistentry/term +#: C/index.docbook:951 +msgid "@short_description" +msgstr "@short_description" -#: C/gtk-doc-manual.xml:686(para) -msgid "Each section of the documentation contains information about one class or module. To introduce the component one can write a section block. The short description is also used inside the table of contents." +#. (itstool) path: listitem/para +#: C/index.docbook:953 +msgid "" +"A one line description of the section, that later will appear after the " +"links in the TOC and at the top of the section page." msgstr "" +"En enradsbeskrivning av avsnittet som senare kommer att visas efter länkar i " +"innehållsförteckningen och lägst upp på avsnittssidan." -#: C/gtk-doc-manual.xml:693(title) -msgid "Section comment block" +#. (itstool) path: varlistentry/term +#: C/index.docbook:960 +msgid "@title" +msgstr "@title" + +#. (itstool) path: listitem/para +#: C/index.docbook:962 +msgid "" +"The section title defaults to <name> from the SECTION declaration. It " +"can be overridden with the @title field." msgstr "" +"Avsnittstiteln är som standard <namn> från SECTION-deklarationen. Den " +"kan åsidosättas med fältet @title." -#: C/gtk-doc-manual.xml:712(term) -msgid "@short_description" -msgstr "@short_description" +#. (itstool) path: varlistentry/term +#: C/index.docbook:969 +msgid "@section_id" +msgstr "@section_id" -#: C/gtk-doc-manual.xml:714(para) -msgid "A one line description of the section, that later will appear after the links in the TOC and at the top of the section page." +#. (itstool) path: listitem/para +#: C/index.docbook:971 +msgid "" +"Overrides the use of title as a section identifier. For GObjects the <" +"title> is used as a section_id and for other sections it is <" +"MODULE>-<title>." msgstr "" +"Åsidosätter användningen av titeln som avsnittsidentifierare. För GObjects " +"används <title> som ett section_id och för andra avsnitt är det <" +"MODULE>-<title>." -#: C/gtk-doc-manual.xml:721(term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:979 msgid "@see_also" msgstr "@see_also" -#: C/gtk-doc-manual.xml:723(para) -msgid "A list of symbols that are related to this section.." -msgstr "" +#. (itstool) path: listitem/para +#: C/index.docbook:981 +msgid "A list of symbols that are related to this section." +msgstr "En lista över symboler som är relaterade till detta avsnitt." -#: C/gtk-doc-manual.xml:729(term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:987 msgid "@stability" msgstr "@stability" -#: C/gtk-doc-manual.xml:736(para) -msgid "Stable - The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release). Even at a major release, incompatible changes are expected to be rare, and to have strong justifications." -msgstr "" - -#: C/gtk-doc-manual.xml:748(para) -msgid "Unstable - Unstable interfaces are experimental or transitional. They are typically used to give outside developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated. No claims are made about either source or binary compatibility from one minor release to the next." -msgstr "" - -#: C/gtk-doc-manual.xml:760(para) -msgid "Private - An interface that can be used within the GNOME stack itself, but that is not documented for end-users. Such functions should only be used in specified and documented ways." +#. (itstool) path: listitem/para +#: C/index.docbook:994 +msgid "" +"Stable - The intention of a Stable interface is to enable arbitrary third " +"parties to develop applications to these interfaces, release them, and have " +"confidence that they will run on all minor releases of the product (after " +"the one in which the interface was introduced, and within the same major " +"release). Even at a major release, incompatible changes are expected to be " +"rare, and to have strong justifications." +msgstr "" +"Stable - Avsikten med ett stabilt gränssnitt är att möjliggöra för tredje " +"parter att utveckla program mot dessa gränssnitt, släppa dem och vara säkra " +"på att de kommer att köra på alla programfixversioner av produkten (efter " +"den i vilken gränssnittet introducerats, och inom samma huvudversion). Även " +"vid en ny huvudversion förväntas inkompatibla ändringar vara få och vara väl " +"motiverade." + +#. (itstool) path: listitem/para +#: C/index.docbook:1006 +msgid "" +"Unstable - Unstable interfaces are experimental or transitional. They are " +"typically used to give outside developers early access to new or rapidly " +"changing technology, or to provide an interim solution to a problem where a " +"more general solution is anticipated. No claims are made about either source " +"or binary compatibility from one minor release to the next." +msgstr "" +"Unstable - Instabila gränssnitt är experimentella eller i en övergångsfas. " +"De används typiskt för att ge utomstående utvecklare tidig tillgång till ny " +"eller snabbt föränderlig teknologi, eller för att tillhandahålla " +"provisoriska lösningar för ett problem där en mer generell lösning förutses. " +"Inga påståenden görs om endera källkods- eller binärkompatibilitet från en " +"programfixversion till nästa." + +#. (itstool) path: listitem/para +#: C/index.docbook:1018 +msgid "" +"Private - An interface that can be used within the GNOME stack itself, but " +"that is not documented for end-users. Such functions should only be used in " +"specified and documented ways." msgstr "" +"Private - Ett gränssnitt som kan användas inom GNOME-stacken i sig, men som " +"inte dokumenterats för slutanvändare. Sådana funktioner bör endast användas " +"på angivna och dokumenterade sätt." -#: C/gtk-doc-manual.xml:769(para) -msgid "Internal - An interface that is internal to a module and does not require end-user documentation. Functions that are undocumented are assumed to be Internal." +#. (itstool) path: listitem/para +#: C/index.docbook:1027 +msgid "" +"Internal - An interface that is internal to a module and does not require " +"end-user documentation. Functions that are undocumented are assumed to be " +"Internal." msgstr "" +"Internal - ett gränssnitt som är internt för en modul och inte behöver " +"slutanvändardokumentation. Funktioner som är odokumenterade förutsätts vara " +"interna." -#: C/gtk-doc-manual.xml:731(para) -msgid "A informal description of the stability level this API has. We recommend the use of one of these terms: " +#. (itstool) path: listitem/para +#: C/index.docbook:989 +msgid "" +"An informal description of the stability level this API has. We recommend " +"the use of one of these terms: <_:itemizedlist-1/>" msgstr "" +"En informell beskrivning över stabiliteten för detta API. Vi rekommenderar " +"att använda en av dessa termer: <_:itemizedlist-1/>" -#: C/gtk-doc-manual.xml:781(term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:1039 msgid "@include" msgstr "@include" -#: C/gtk-doc-manual.xml:783(para) -msgid "The #include files to show in the section synopsis (a comma separated list), overriding the global value from the section file or command line. This item is optional." -msgstr "" - -#: C/gtk-doc-manual.xml:793(para) -msgid "FIXME having @title here, would put this title into a newly generated section file, but later would be obsolete (right?)" -msgstr "" - -#: C/gtk-doc-manual.xml:800(para) -msgid "To avoid unnecessary recompilation after doc-changes put the section docs into the c-source where possible." +#. (itstool) path: listitem/para +#: C/index.docbook:1041 +msgid "" +"The #include files to show in the section synopsis (a " +"comma separated list), overriding the global value from the section file or command line. This item is " +"optional." +msgstr "" +"#include-filerna som ska visas i avsnittssammanfattningen " +"(en kommaavgränsad lista), vilket åsidosätter det globala värdet från avsnittsfilen eller kommandoraden. " +"Detta objekt är valfritt." + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1050 +msgid "@image" +msgstr "@image" + +#. (itstool) path: listitem/para +#: C/index.docbook:1052 +msgid "" +"The image to display at the top of the reference page for this section. This " +"will often be some sort of a diagram to illustrate the visual appearance of " +"a class or a diagram of its relationship to other classes. This item is " +"optional." +msgstr "" +"Bilden som ska visas längst upp på referenssidan för detta avsnitt. Detta " +"kommer ofta att vara någon form av diagram för att illustrera det visuella " +"utseendet för en klass eller ett diagram över dess relationer med andra " +"klasser. Detta objekt är valfritt." + +#. (itstool) path: tip/para +#: C/index.docbook:1063 +msgid "" +"To avoid unnecessary recompilation after doc-changes put the section docs " +"into the c-source where possible." msgstr "" +"För att undvika onödig omkompilering efter dokumentationsändringar, placera " +"avsnittsdokumentationen i c-källkoden där möjligt." -#: C/gtk-doc-manual.xml:809(title) +#. (itstool) path: sect1/title +#: C/index.docbook:1072 msgid "Documenting symbols" -msgstr "" +msgstr "Dokumentationssymboler" -#: C/gtk-doc-manual.xml:811(para) -msgid "Each symbol (function, macro, struct, enum, signal and property) is documented in a separate block. The block is best placed close to the definition of the symbols so that it is easy to keep them in sync. Thus function are usually documented in the c-source and macros, struct and enum in the header file." +#. (itstool) path: sect1/para +#: C/index.docbook:1074 +msgid "" +"Each symbol (function, macro, struct, enum, signal and property) is " +"documented in a separate block. The block is best placed close to the " +"definition of the symbols so that it is easy to keep them in sync. Thus " +"functions are usually documented in the c-source and macros, structs and " +"enums in the header file." +msgstr "" +"Varje symbol (funktion, makro, struktur, uppräkning, signal och egenskap) är " +"dokumenterad i ett separat block. Blocket placeras bäst intill definitionen " +"av symbolerna så att det är enkelt att hålla dem synkroniserade. Därför " +"dokumenteras funktioner vanligtvis i c-källkoden och makron, strukturer och " +"uppräkningar i huvudfilen." + +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1082 C/index.docbook:1148 +msgid "General tags" +msgstr "Generella taggar" + +#. (itstool) path: sect2/para +#: C/index.docbook:1084 +msgid "" +"You can add versioning information to all documentation elements to tell " +"when an API was introduced, or when it was deprecated." msgstr "" +"Du kan lägga till versioneringsinformation i alla dokumentationselement för " +"att berätta när ett API introducerats eller blev föråldrat." -#: C/gtk-doc-manual.xml:820(title) -msgid "Function comment block" -msgstr "" +#. (itstool) path: variablelist/title +#: C/index.docbook:1089 +msgid "Versioning Tags" +msgstr "Versioneringstaggar" -#: C/gtk-doc-manual.xml:843(term) -msgid "Returns:" -msgstr "" +#. (itstool) path: varlistentry/term +#: C/index.docbook:1090 +msgid "Since:" +msgstr "Since:" -#: C/gtk-doc-manual.xml:845(para) -msgid "Paragraph describing the returned result." +#. (itstool) path: listitem/para +#: C/index.docbook:1092 +msgid "Description since which version of the code the API is available." msgstr "" +"Beskrivning över från och med vilken version av koden som API:t är " +"tillgängligt." -#: C/gtk-doc-manual.xml:851(term) +#. (itstool) path: varlistentry/term +#: C/index.docbook:1097 msgid "Deprecated:" -msgstr "" +msgstr "Deprecated:" -#: C/gtk-doc-manual.xml:853(para) -msgid "Paragraph denoting that this function should no be used anymore. The description should point the reader to the new API." +#. (itstool) path: listitem/para +#: C/index.docbook:1099 +msgid "" +"Paragraph denoting that this function should no be used anymore. The " +"description should point the reader to the new API." msgstr "" +"Stycke som betecknar att denna funktion inte bör användas längre. " +"Beskrivningen bör peka läsaren vidare till det nya API:t." -#: C/gtk-doc-manual.xml:860(term) -msgid "Since:" +#. (itstool) path: sect2/para +#: C/index.docbook:1107 +msgid "" +"You can also add stability information to all documentation elements to " +"indicate whether API stability is guaranteed for them for all future minor " +"releases of the project." msgstr "" +"Du kan också lägga till stabilitetsinformation för alla " +"dokumentationselement för att indikera huruvida API-stabilitet är garanterad " +"för dem för alla framtida programfix-versioner av projektet." -#: C/gtk-doc-manual.xml:862(para) -msgid "Description since which version of the code the API is available." +#. (itstool) path: sect2/para +#: C/index.docbook:1113 +msgid "" +"The default stability level for all documentation elements can be set by " +"passing the argument to " +"gtkdoc-mkdb with one of the values below." +msgstr "" +"Standardvärdet för stabilitetsnivån för alla dokumentations element kan " +"ställas in genom att ange argumentet " +"till gtkdoc-mkdb med endera av värdena nedan." + +#. (itstool) path: variablelist/title +#: C/index.docbook:1119 +msgid "Stability Tags" +msgstr "Stabilitetstaggar" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1120 +msgid "Stability: Stable" +msgstr "Stability: Stable" + +#. (itstool) path: listitem/para +#: C/index.docbook:1122 +msgid "" +"Mark the element as stable. This is for public APIs which are guaranteed to " +"remain stable for all future minor releases of the project." msgstr "" +"Markera elementet som stabilt. Detta är för publika API:er som är " +"garanterade att hållas stabila i alla framtida programfix-versioner av " +"projektet." -#: C/gtk-doc-manual.xml:869(para) -msgid "Gtk-doc assumes all symbols (macros, functions) starting with '_' are private. They are treated like static functions." -msgstr "" +#. (itstool) path: varlistentry/term +#: C/index.docbook:1129 +msgid "Stability: Unstable" +msgstr "Stability: Unstable" -#: C/gtk-doc-manual.xml:874(para) -msgid "(FIXME) (stability) (glib-enums, ...)" +#. (itstool) path: listitem/para +#: C/index.docbook:1131 +msgid "" +"Mark the element as unstable. This is for public APIs which are released as " +"a preview before being stabilised." msgstr "" +"Markera elementet som instabilt. Detta är för publika API:er som är släppta " +"på förhand innan de blivit stabiliserade." -#: C/gtk-doc-manual.xml:880(title) -msgid "Property comment block" -msgstr "" +#. (itstool) path: varlistentry/term +#: C/index.docbook:1137 +msgid "Stability: Private" +msgstr "Stability: Private" -#: C/gtk-doc-manual.xml:892(title) -msgid "Signal comment block" +#. (itstool) path: listitem/para +#: C/index.docbook:1139 +msgid "" +"Mark the element as private. This is for interfaces which can be used by " +"tightly coupled modules, but not by arbitrary third parties." msgstr "" +"Markera element som privat. Detta är avsett för gränssnitt som kan användas " +"av tätt sammankopplade moduler, men inte av godtyckliga tredje parter." -#: C/gtk-doc-manual.xml:909(title) -msgid "Struct comment block" -msgstr "" +#. (itstool) path: example/programlisting +#: C/index.docbook:1149 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * foo_get_bar:\n" +" * @foo: some foo\n" +" *\n" +" * Retrieves @foo's bar.\n" +" *\n" +" * Returns: @foo's bar\n" +" *\n" +" * Since: 2.6\n" +" * Deprecated: 2.12: Use foo_baz_get_bar() instead.\n" +" */\n" +"Bar *\n" +"foo_get_bar(Foo *foo)\n" +"{\n" +"...\n" +msgstr "" +"\n" +"/**\n" +" * foo_get_bar:\n" +" * @foo: någon foo\n" +" *\n" +" * Hämtar bar från @foo.\n" +" *\n" +" * Returns: bar från @foo\n" +" *\n" +" * Since: 2.6\n" +" * Deprecated: 2.12: Använd foo_baz_get_bar() istället.\n" +" */\n" +"Bar *\n" +"foo_get_bar(Foo *foo)\n" +"{\n" +"…\n" + +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1169 C/index.docbook:1179 +msgid "Annotations" +msgstr "Noteringar" + +# sebras: was it called verkygstips? verktygshjälp? I forget... +#. (itstool) path: sect2/para +#: C/index.docbook:1171 +msgid "" +"Documentation blocks can contain annotation-tags. These tags will be " +"rendered with tooltips describing their meaning. The tags are used by " +"gobject-introspection to generate language bindings. A detailed list of the " +"supported tags can be found on the wiki." +msgstr "" +"Dokumentationsblock kan innehålla noteringstaggar. Dessa taggar kommer att " +"renderas som verktygstips som beskriver deras syfte. Taggarna används av " +"gobject-introspection för att generera språkbindningar. En detaljerad lista " +"över vilka taggar som stöds hittas på wikisidan." + +#. (itstool) path: example/programlisting +#: C/index.docbook:1180 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * foo_get_bar: (annotation)\n" +" * @foo: (annotation): some foo\n" +" *\n" +" * Retrieves @foo's bar.\n" +" *\n" +" * Returns: (annotation): @foo's bar\n" +" */\n" +"...\n" +"/**\n" +" * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)\n" +" * (and another annotation)\n" +" * @foo: (annotation) (another annotation): some foo\n" +" *\n" +" * Sets bar on @foo.\n" +" */\n" +msgstr "" +"\n" +"/**\n" +" * foo_get_bar: (notering)\n" +" * @foo: (notering): någon foo\n" +" *\n" +" * Hämtar bar från @foo.\n" +" *\n" +" * Returns: (notering): bar från @foo\n" +" */\n" +"...\n" +"/**\n" +" * foo_set_bar_using_the_frobnicator: (notering) (an annan notering)\n" +" * (ytterligare en annan notering)\n" +" * @foo: (notering) (en annan notering): någon foo\n" +" *\n" +" * Ställer in bar i @foo.\n" +" */\n" + +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1201 C/index.docbook:1230 +msgid "Function comment block" +msgstr "Kommentarsblock för funktioner" -#: C/gtk-doc-manual.xml:928(title) -msgid "Useful DocBook tags" +#. (itstool) path: listitem/para +#: C/index.docbook:1207 +msgid "" +"Document whether returned objects, lists, strings, etc, should be freed/" +"unrefed/released." msgstr "" +"Dokumentera huruvida returnerade objekt, listor, strängar, etc. bör frigöras/" +"avrefereras/släppas." -#: C/gtk-doc-manual.xml:930(para) -msgid "Here are some DocBook tags which are most useful when documenting the code." +#. (itstool) path: listitem/para +#: C/index.docbook:1213 +msgid "Document whether parameters can be NULL, and what happens if they are." msgstr "" +"Dokumentera huruvida parametrar tillåts vara NULL och vad som händer om de " +"är NULL." -#: C/gtk-doc-manual.xml:935(para) -msgid "To link to another section in the GTK docs: The linkend is the SGML id on the top item of the page you want to link to. For most pages this is currently the part (\"gtk\", \"gdk\", glib\") and then the page title (\"Hash Tables\"). For widgets it is just the class name. Spaces and underscores are converted to '-' to conform to SGML." -msgstr "" +#. (itstool) path: listitem/para +#: C/index.docbook:1218 +msgid "" +"Mention interesting pre-conditions and post-conditions where appropriate." +msgstr "Nämn intressanta förvillkor och eftervillkor där lämpligt." -#: C/gtk-doc-manual.xml:951(para) -msgid "To refer to an external function, e.g. a standard C function: " -msgstr "" +#. (itstool) path: sect2/para +#: C/index.docbook:1203 C/index.docbook:1289 +msgid "Please remember to: <_:itemizedlist-1/>" +msgstr "Kom ihåg att: <_:itemizedlist-1/>" -#: C/gtk-doc-manual.xml:962(para) +# sebras: Gtk-doc? GTK-Doc? gtk-doc? macros and functions? +#. (itstool) path: sect2/para +#: C/index.docbook:1225 msgid "" -"To include example code: or possibly this, for very short code fragments which don't need a title: For the latter gtk-doc also supports an abbreviation: " +"Gtk-doc assumes all symbols (macros, functions) starting with '_' are " +"private. They are treated like static functions." msgstr "" +"Gtk-doc förutsätter att alla symboler (makron, funktioner) som börjar med " +"”_” är privata. De behandlas på samma sätt som statiska funktioner." -#: C/gtk-doc-manual.xml:996(para) -msgid "To include bulleted lists: " -msgstr "" +# sebras: how to translate highlight? +#. (itstool) path: example/programlisting +#: C/index.docbook:1231 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * function_name:\n" +" * @par1: description of parameter 1. These can extend over more than\n" +" * one line.\n" +" * @par2: description of parameter 2\n" +" * @...: a %NULL-terminated list of bars\n" +" *\n" +" * The function description goes here. You can use @par1 to refer to parameters\n" +" * so that they are highlighted in the output. You can also use %constant\n" +" * for constants, function_name2() for functions and #GtkWidget for links to\n" +" * other declarations (which may be documented elsewhere).\n" +" *\n" +" * Returns: an integer.\n" +" *\n" +" * Since: 2.2\n" +" * Deprecated: 2.18: Use other_function() instead.\n" +" */\n" +msgstr "" +"\n" +"/**\n" +" * funktionsnamn:\n" +" * @par1: beskrivning av parameter 1. Dessa kan sträcka sig\n" +" * över mer än en rad.\n" +" * @par2: beskrivning av parameter 2\n" +" * @...: en %NULL-terminerad lista av flera bar\n" +" *\n" +" * Funktionsbeskrivningen ska vara här. Du kan använda @par1 för att\n" +" * referera till parametrar så att de färgmarkeras i utdata. Du kan också\n" +" * använda %konstant för konstanter, funktionsnamn2() för funktioner och\n" +" * #GtkWidget för länkar till andra deklarationer (vilka kan vara dokumenterade\n" +" * på annat håll).\n" +" *\n" +" * Returns: ett heltal.\n" +" *\n" +" * Since: 2.2\n" +" * Deprecated: 2.18: Använd annan_funktion() istället.\n" +" */\n" + +#. (itstool) path: variablelist/title +#: C/index.docbook:1252 +msgid "Function tags" +msgstr "Funktions-taggar" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1253 C/index.docbook:1460 +msgid "Returns:" +msgstr "Returns:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1255 +msgid "Paragraph describing the returned result." +msgstr "Stycke som beskriver det returnerade resultatet." -#: C/gtk-doc-manual.xml:1018(para) -msgid "To include a note which stands out from the text: " +#. (itstool) path: varlistentry/term +#: C/index.docbook:1260 +msgid "@...:" +msgstr "@...:" + +# sebras: variadic? +#. (itstool) path: listitem/para +#: C/index.docbook:1262 +msgid "" +"In case the function has variadic arguments, you should use this tag " +"(@Varargs: does also work for historic reasons)." msgstr "" +"Om funktionen har variadiska argument bör du använda denna tagg (@Varargs: " +"fungerar också på grund av historiska skäl)." -#: C/gtk-doc-manual.xml:1033(para) -msgid "To refer to a type: " +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1272 C/index.docbook:1274 +msgid "Property comment block" +msgstr "Kommentarsblock för egenskaper" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1275 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * SomeWidget:some-property:\n" +" *\n" +" * Here you can document a property.\n" +" */\n" +"g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);\n" +msgstr "" +"\n" +"/**\n" +" * EnKomponent:en-egenskap:\n" +" *\n" +" * Här kan du dokumentera en egenskap.\n" +" */\n" +"g_object_class_install_property (object_class, PROP_EN_EGENSKAP, …);\n" + +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1287 C/index.docbook:1306 +msgid "Signal comment block" +msgstr "Kommentarsblock för signaler" + +#. (itstool) path: listitem/para +#: C/index.docbook:1293 +msgid "" +"Document when the signal is emitted and whether it is emitted before or " +"after other signals." msgstr "" +"Dokumentera när en signal sänds ut och huruvida den sänds ut före eller " +"efter andra signaler." + +#. (itstool) path: listitem/para +#: C/index.docbook:1299 +msgid "Document what an application might do in the signal handler." +msgstr "Dokumentera vad ett program kan göra i signalhanteraren." + +#. (itstool) path: example/programlisting +#: C/index.docbook:1307 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * FooWidget::foobarized:\n" +" * @widget: the widget that received the signal\n" +" * @foo: some foo\n" +" * @bar: some bar\n" +" *\n" +" * The ::foobarized signal is emitted each time someone tries to foobarize @widget.\n" +" */\n" +"foo_signals[FOOBARIZE] =\n" +" g_signal_new (\"foobarize\",\n" +" ...\n" +msgstr "" +"\n" +"/**\n" +" * FooWidget::foobariserad:\n" +" * @widget: komponenten som erhåller signalen\n" +" * @foo: någon foo\n" +" * @bar: någon bar\n" +" *\n" +" * Signalen ::foobarized sänds ut varje gång någon försöker att foobarisera @widget.\n" +" */\n" +"foo_signals[FOOBARIZE] =\n" +" g_signal_new (\"foobarisera\",\n" +" ...\n" + +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1324 C/index.docbook:1325 +msgid "Struct comment block" +msgstr "Kommentarsblock för strukturer" -#: C/gtk-doc-manual.xml:1044(para) -msgid "To refer to an external structure (not one described in the GTK docs): " +#. (itstool) path: example/programlisting +#: C/index.docbook:1326 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * FooWidget:\n" +" * @bar: some #gboolean\n" +" *\n" +" * This is the best widget, ever.\n" +" */\n" +"typedef struct _FooWidget {\n" +" GtkWidget parent_instance;\n" +"\n" +" gboolean bar;\n" +"} FooWidget;\n" +msgstr "" +"\n" +"/**\n" +" * FooWidget:\n" +" * @bar: någon #gboolean\n" +" *\n" +" * Detta är den bästa komponenten någonsin.\n" +" */\n" +"typedef struct _FooWidget {\n" +" GtkWidget parent_instance;\n" +"\n" +" gboolean bar;\n" +"} FooWidget;\n" + +#. (itstool) path: sect2/para +#: C/index.docbook:1341 +msgid "" +"Use /*< private >*/ before the private struct fields you " +"want to hide. Use /*< public >*/ for the reverse " +"behaviour." msgstr "" +"Använd/*< private >*/ före privata strukturfält som du " +"vill gömma. Använd /*< public >*/ för det omvända " +"beteendet." -#: C/gtk-doc-manual.xml:1055(para) -msgid "To refer to a field of a structure: " +#. (itstool) path: sect2/para +#: C/index.docbook:1347 +msgid "" +"If the first field is \"g_iface\", \"parent_instance\" or \"parent_class\" " +"it will be considered private automatically and doesn't need to be mentioned " +"in the comment block." msgstr "" +"Om det första fältet är ”g_iface”, ”parent_instance” eller ”parent_class” " +"kommer det att anses vara privat automatiskt och behöver inte nämnas i " +"kommentarsblocket." -#: C/gtk-doc-manual.xml:1066(para) -msgid "To refer to a class name, we could possibly use: but you'll probably be using #GtkWidget instead (to automatically create a link to the GtkWidget page - see the abbreviations)." +#. (itstool) path: sect2/para +#: C/index.docbook:1353 +msgid "" +"Struct comment blocks can also be used for GObjects and GObjectClasses. It " +"is usually a good idea to add a comment block for a class, if it has " +"vmethods (as this is how they can be documented). For the GObject itself one " +"can use the related section docs, having a separate block for the instance " +"struct would be useful if the instance has public fields. One disadvantage " +"here is that this creates two index entries of the same name (the structure " +"and the section)." +msgstr "" +"Kommentarsblock för strukturer kan också användas för GObject och " +"GObjectClass. Det är vanligtvis en bra idé att lägga till ett " +"kommentarsblock för en klass om den har virtuella metoder (då detta är " +"sättet på vilket de kan dokumenteras). För GObject i sig kan man använda den " +"relaterade avsnittsdokumentationen, och ha ett separat block för varje " +"instansstruktur vore användbart om instansen har publika fält. En nackdel " +"här är att det skapar två indexposter med samma namn (strukturen och " +"avsnittet)." + +#. (itstool) path: sect2/title +#. (itstool) path: example/title +#: C/index.docbook:1365 C/index.docbook:1366 +msgid "Enum comment block" +msgstr "Kommentarsblock för uppräkningar" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1367 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * Something:\n" +" * @SOMETHING_FOO: something foo\n" +" * @SOMETHING_BAR: something bar\n" +" *\n" +" * Enum values used for the thing, to specify the thing.\n" +" */\n" +"typedef enum {\n" +" SOMETHING_FOO,\n" +" SOMETHING_BAR,\n" +" /*< private >*/\n" +" SOMETHING_COUNT\n" +"} Something;\n" +msgstr "" +"\n" +"/**\n" +" * Something:\n" +" * @SOMETHING_FOO: någonting foo\n" +" * @SOMETHING_BAR: någonting bar\n" +" *\n" +" * Uppräkningsvärden som används för saken, för att specificera saken.\n" +" */\n" +"typedef enum {\n" +" SOMETHING_FOO,\n" +" SOMETHING_BAR,\n" +" /*< private >*/\n" +" SOMETHING_COUNT\n" +"} Something;\n" + +#. (itstool) path: sect2/para +#: C/index.docbook:1384 +msgid "" +"Use /*< private >*/ before the private enum values you " +"want to hide. Use /*< public >*/ for the reverse " +"behaviour." +msgstr "" +"Använd /*< private >*/ före privata uppräkningsvärden som " +"du vill gömma. Använd /*< public >*/ för det omvända " +"beteendet." + +#. (itstool) path: sect1/title +#: C/index.docbook:1395 +msgid "Inline program documentation" +msgstr "Infogad programdokumentation" + +# sebras: how to translate inline? +#. (itstool) path: sect1/para +#: C/index.docbook:1396 +msgid "" +"You can document programs and their commandline interface using inline " +"documentation." +msgstr "" +"Du kan dokumentera program och deras kommandoradsgränssnitt med infogad " +"dokumentation." + +#. (itstool) path: variablelist/title +#: C/index.docbook:1402 +msgid "Tags" +msgstr "Taggar" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1404 +msgid "PROGRAM" +msgstr "PROGRAM" + +#. (itstool) path: listitem/para +#: C/index.docbook:1407 +msgid "Defines the start of a program documentation." +msgstr "Definierar början av programdokumentationen." + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1414 +msgid "@short_description:" +msgstr "@short_description:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1416 +msgid "Defines a short description of the program. (Optional)" +msgstr "Definierar en kort beskrivning av programmet. (Valfritt)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1423 +msgid "@synopsis:" +msgstr "@synopsis:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1425 +msgid "" +"Defines the arguments, or list of arguments that the program can take. " +"(Optional)" +msgstr "" +"Definierar argumenten, eller en lista av argument som programmet kan ta. " +"(Valfritt)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1433 +msgid "@see_also:" +msgstr "@see_also:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1435 +msgid "See Also manual page section. (Optional)" +msgstr "Se vidare i manualavsnitt. (Valfritt)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1442 +msgid "@arg:" +msgstr "@arg:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1444 +msgid "Argument(s) passed to the program and their description. (Optional)" +msgstr "" +"Argument som skickas vidare till programmet och deras beskrivningar. " +"(Valfritt)" + +#. (itstool) path: varlistentry/term +#: C/index.docbook:1451 +msgid "Description:" +msgstr "Beskrivning:" + +#. (itstool) path: listitem/para +#: C/index.docbook:1453 +msgid "A longer description of the program." +msgstr "En längre beskrivning av programmet." + +#. (itstool) path: listitem/para +#: C/index.docbook:1462 +msgid "Specificy what value(s) the program returns. (Optional)" +msgstr "Ange vilka värden programmet returnerar. (Valfritt)" + +#. (itstool) path: sect2/title +#: C/index.docbook:1471 +msgid "Example of program documentation." +msgstr "Exempel på programdokumentation." + +#. (itstool) path: example/title +#: C/index.docbook:1472 +msgid "Program documentation block" +msgstr "Dokumentationsblock för program" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1473 +#, no-wrap +msgid "" +"\n" +"/**\n" +" * PROGRAM:test-program\n" +" * @short_description: A test program\n" +" * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*\n" +" * @see_also: test(1)\n" +" * @--arg1 *arg*: set arg1 to *arg*\n" +" * @--arg2 *arg*: set arg2 to *arg*\n" +" * @-v, --version: Print the version number\n" +" * @-h, --help: Print the help message\n" +" *\n" +" * Long description of program.\n" +" *\n" +" * Returns: Zero on success, non-zero on failure\n" +" */\n" +"int main(int argc, char *argv[])\n" +"{\n" +"\treturn 0;\n" +"}\n" +msgstr "" +"\n" +"/**\n" +" * PROGRAM:test-program\n" +" * @short_description: Ett testprogram\n" +" * @synopsis: test-program [*FLAGGOR*...] --arg1 *arg* *FIL*\n" +" * @see_also: test(1)\n" +" * @--arg1 *arg*: ställ in arg1 på *arg*\n" +" * @--arg2 *arg*: ställ in arg2 på *arg*\n" +" * @-v, --version: Skriv ut versionsinformation\n" +" * @-h, --help: Skriv ut hjälpmeddelandet\n" +" *\n" +" * En längre beskrivning av programmet.\n" +" *\n" +" * Returns: Noll vid framgång, icke-noll vid fel\n" +" */\n" +"int main(int argc, char *argv[])\n" +"{\n" +"\treturn 0;\n" +"}\n" + +#. (itstool) path: sect1/title +#: C/index.docbook:1499 +msgid "Useful DocBook tags" +msgstr "Användbara DocBook-taggar" + +#. (itstool) path: sect1/para +#: C/index.docbook:1501 +msgid "" +"Here are some DocBook tags which are most useful when documenting the code." msgstr "" +"Här är några DocBook-taggar som är användbara när man dokumenterar koden." -#: C/gtk-doc-manual.xml:1079(para) -msgid "To emphasize text: " +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1510 +#, no-wrap +msgid "" +"\n" +"<link linkend=\"glib-Hash-Tables\">Hash Tables</link>\n" msgstr "" +"\n" +"<link linkend=\"glib-Hash-Tables\">Hashtabeller</link>\n" -#: C/gtk-doc-manual.xml:1090(para) -msgid "For filenames use: " +#. (itstool) path: sect1/para +#: C/index.docbook:1506 +msgid "" +"To link to another section in the GTK docs: <_:informalexample-1/> The " +"linkend is the SGML/XML id on the top item of the page you want to link to. " +"For most pages this is currently the part (\"gtk\", \"gdk\", \"glib\") and " +"then the page title (\"Hash Tables\"). For widgets it is just the class " +"name. Spaces and underscores are converted to '-' to conform to SGML/XML." +msgstr "" +"För att länka till ett annat avsnitt i GTK-dokumentationen: <_:" +"informalexample-1/> Länkslutet är XGML/XML-id:t för toppnivåobjektet på " +"sidan du vill länka till. För de flesta sidorna är detta för närvarande " +"delen (”gtk”, ”gdk”, ”glib”) och sedan sidans titel (”Hashtabeller”). För " +"komponenter är detta helt enkelt klassnamnet. Blanksteg och understreck " +"konverteras till ”-” för att överensstämma med SGML/XML." + +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1523 +#, no-wrap +msgid "" +"\n" +"<function>...</function>\n" msgstr "" +"\n" +"<function>…</function>\n" -#: C/gtk-doc-manual.xml:1105(title) -msgid "Filling the extra files" +#. (itstool) path: sect1/para +#: C/index.docbook:1520 +msgid "" +"To refer to an external function, e.g. a standard C function: <_:" +"informalexample-1/>" msgstr "" +"För att referera till en extern funktion, t.ex. en standardfunktion i C: <_:" +"informalexample-1/>" -#: C/gtk-doc-manual.xml:1107(para) -msgid "There are a couple of extra files, that need to be maintained along with the inline source code comments: <package>.types, <package>-docs.sgml, <package>-sections.txt." +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1532 +#, no-wrap +msgid "" +"\n" +"<example>\n" +" <title>Using a GHashTable.</title>\n" +" <programlisting>\n" +" ...\n" +" </programlisting>\n" +"</example>\n" +msgstr "" +"\n" +"<example>\n" +" <title>Att använda en hashtabell.</title>\n" +" <programlisting>\n" +" …\n" +" </programlisting>\n" +"</example>\n" + +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1543 +#, no-wrap +msgid "" +"\n" +"<informalexample>\n" +" <programlisting>\n" +" ...\n" +" </programlisting>\n" +"</informalexample>\n" +msgstr "" +"\n" +"<informalexample>\n" +" <programlisting>\n" +" …\n" +" </programlisting>\n" +"</informalexample>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1529 +msgid "" +"To include example code: <_:informalexample-1/> or possibly this, for very " +"short code fragments which don't need a title: <_:informalexample-2/> For " +"the latter GTK-Doc also supports an abbreviation: |[ ... ]|" +msgstr "" +"För att inkludera exempelkod: <_:informalexample-1/> eller möjligen " +"följande, för väldigt korta kodfragment som inte behöver en titel: <_:" +"informalexample-2/> För det senare fallet har GTK-Doc också stöd för " +"förkortningen: |[ … ]|" + +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1562 +#, no-wrap +msgid "" +"\n" +"<itemizedlist>\n" +" <listitem>\n" +" <para>\n" +" ...\n" +" </para>\n" +" </listitem>\n" +" <listitem>\n" +" <para>\n" +" ...\n" +" </para>\n" +" </listitem>\n" +"</itemizedlist>\n" +msgstr "" +"\n" +"<itemizedlist>\n" +" <listitem>\n" +" <para>\n" +" …\n" +" </para>\n" +" </listitem>\n" +" <listitem>\n" +" <para>\n" +" …\n" +" </para>\n" +" </listitem>\n" +"</itemizedlist>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1559 +msgid "To include bulleted lists: <_:informalexample-1/>" +msgstr "För att inkludera punktlistor: <_:informalexample-1/>" + +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1582 +#, no-wrap +msgid "" +"\n" +"<note>\n" +" <para>\n" +" Make sure you free the data after use.\n" +" </para>\n" +"</note>\n" +msgstr "" +"\n" +"<note>\n" +" <para>\n" +" Säkerställ att du frigjort data efter användning.\n" +" </para>\n" +"</note>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1579 +msgid "" +"To include a note which stands out from the text: <_:informalexample-1/>" msgstr "" +"För att inkludera en not som skiljer sig från texten: <_:informalexample-1/>" -#: C/gtk-doc-manual.xml:1116(title) -msgid "Editing the types file" +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1595 +#, no-wrap +msgid "" +"\n" +"<type>unsigned char</type>\n" msgstr "" +"\n" +"<type>unsigned char</type>\n" -#: C/gtk-doc-manual.xml:1118(para) -msgid "If your library or application includes GtkObjects/GObjects, you want their signals, arguments/parameters and position in the hierarchy to be shown in the documentation. All you need to do, is to list the xxx_get_type functions together with their include inside the <package>.types file." +#. (itstool) path: sect1/para +#: C/index.docbook:1592 +msgid "To refer to a type: <_:informalexample-1/>" +msgstr "För att refera till en typ: <_:informalexample-1/>" + +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1604 +#, no-wrap +msgid "" +"\n" +"<structname>XFontStruct</structname>\n" msgstr "" +"\n" +"<structname>XFontStruct</structname>\n" -#: C/gtk-doc-manual.xml:1127(title) -msgid "Example types file snippet" +#. (itstool) path: sect1/para +#: C/index.docbook:1601 +msgid "" +"To refer to an external structure (not one described in the GTK docs): <_:" +"informalexample-1/>" msgstr "" +"För att referera till en extern struktur (som inte beskrivs i GTK-" +"dokumentationen): <_:informalexample-1/>" -#: C/gtk-doc-manual.xml:1141(para) -msgid "Since gtk-doc 1.8 gtkdoc-scan can generate this list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in Makefile.am. If you use this approach you should not dist the types file nor have it under version control." +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1613 +#, no-wrap +msgid "" +"\n" +"<structfield>len</structfield>\n" msgstr "" +"\n" +"<structfield>len</structfield>\n" -#: C/gtk-doc-manual.xml:1150(title) -msgid "Editing the master document" +#. (itstool) path: sect1/para +#: C/index.docbook:1610 +msgid "To refer to a field of a structure: <_:informalexample-1/>" +msgstr "För att referera till ett fält för en struktur: <_:informalexample-1/>" + +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1622 +#, no-wrap +msgid "" +"\n" +"<classname>GtkWidget</classname>\n" msgstr "" +"\n" +"<classname>GtkWidget</classname>\n" -#: C/gtk-doc-manual.xml:1152(para) -msgid "Gtk-Doc produces documentation in DocBook SGML/XML. When processing the inline source comments, the Gtk-Doc tools generate one documentation page per class or module as a separate file. The master document includes them and place them in a order." +#. (itstool) path: sect1/para +#: C/index.docbook:1619 +msgid "" +"To refer to a class name, we could possibly use: <_:informalexample-1/> but " +"you'll probably be using #GtkWidget instead (to automatically create a link " +"to the GtkWidget page - see the " +"abbreviations)." +msgstr "" +"För att referera till ett klassnamn kan vi möjligen använda: <_:" +"informalexample-1/> men du kommer troligt att använda #GtkWidget istället " +"(för att automatiskt skapa en länk till GtkWidget-sidan - se förkortningarna)." + +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1633 +#, no-wrap +msgid "" +"\n" +"<emphasis>This is important</emphasis>\n" msgstr "" +"\n" +"<emphasis>Detta är viktigt</emphasis>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1630 +msgid "To emphasize text: <_:informalexample-1/>" +msgstr "För att betona text: <_:informalexample-1/>" -#: C/gtk-doc-manual.xml:1159(para) -msgid "While Gtk-Doc creates a template master document for you, later run will not touch it again. This means that one can freely structure the documentation. That includes grouping pages and adding extra pages. Gtk-doc has now a test suite, where also the master-document is recreated from scratch. Its a good idea to look at this from time to time to see if there are some new goodies introduced there." +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1642 +#, no-wrap +msgid "" +"\n" +"<filename>/home/user/documents</filename>\n" msgstr "" +"\n" +"<filename>/home/användare/dokument</filename>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1639 +msgid "For filenames use: <_:informalexample-1/>" +msgstr "För filnamn använd: <_:informalexample-1/>" -#: C/gtk-doc-manual.xml:1169(para) -msgid "Do not create tutorials as extra documents. Just write extra chapters. The benefit of directly embedding the tutorial for your library into the API documentation is that it is easy to link for the tutorial to symbol documentation. Apart chances are higher that the tutorial gets updates along with the library." +#. (itstool) path: informalexample/programlisting +#: C/index.docbook:1651 +#, no-wrap +msgid "" +"\n" +"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" msgstr "" +"\n" +"<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1648 +msgid "To refer to keys use: <_:informalexample-1/>" +msgstr "För att referera till tangenter använd: <_:informalexample-1/>" -#: C/gtk-doc-manual.xml:1178(para) -msgid "So what are the things to change inside the master document? For a start is only a little. There are some placeholders (text in square brackets) there which you should take care of." +#. (itstool) path: chapter/title +#: C/index.docbook:1661 +msgid "Filling the extra files" +msgstr "Fylla i de extra filerna" + +#. (itstool) path: chapter/para +#: C/index.docbook:1663 +msgid "" +"There are a couple of extra files, that need to be maintained along with the " +"inline source code comments: <package>.types, " +"<package>-docs.xml (in the past .sgml), " +"<package>-sections.txt." +msgstr "" +"Det finns ett antal extra filer som behöver underhållas tillsammans med de " +"infogade källkodskommentarerna: <paket>.types, " +"<paket>-docs.xml (tidigare .sgml), <" +"paket>-sections.txt." + +#. (itstool) path: sect1/title +#: C/index.docbook:1672 +msgid "Editing the types file" +msgstr "Redigera typfilen" + +#. (itstool) path: sect1/para +#: C/index.docbook:1674 +msgid "" +"If your library or application includes GObjects, you want their signals, " +"arguments/parameters and position in the hierarchy to be shown in the " +"documentation. All you need to do, is to list the xxx_get_type functions together with their include inside the <" +"package>.types file." +msgstr "" +"Om ditt bibliotek eller program inkluderar GObject så kommer du att vilja " +"att deras signaler, argument/parametrar och position i hierarkin visas i " +"dokumentationen. Allt du behöver göra är att lista xxx_get_type-funktionerna tillsammans med deras huvudfil i filen <" +"package>.types." + +#. (itstool) path: example/title +#: C/index.docbook:1683 +msgid "Example types file snippet" +msgstr "Exempel på typfilsnutt" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1684 +#, no-wrap +msgid "" +"\n" +"#include <gtk/gtk.h>\n" +"\n" +"gtk_accel_label_get_type\n" +"gtk_adjustment_get_type\n" +"gtk_alignment_get_type\n" +"gtk_arrow_get_type\n" +msgstr "" +"\n" +"#include <gtk/gtk.h>\n" +"\n" +"gtk_accel_label_get_type\n" +"gtk_adjustment_get_type\n" +"gtk_alignment_get_type\n" +"gtk_arrow_get_type\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1695 +msgid "" +"Since GTK-Doc 1.8 gtkdoc-scan can generate this " +"list for you. Just add \"--rebuild-types\" to SCAN_OPTIONS in " +"Makefile.am. If you use this approach you should not " +"dist the types file nor have it under version control." +msgstr "" +"Sedan GTK-Doc 1.8 kan gtkdoc-scan generera denna " +"lista åt dig. Lägg bara till ”--rebuild-types” i SCAN_OPTIONS i " +"Makefile.am. Om du använder detta tillvägagångssätt bör " +"du inte distribuera typfilen eller versionshantera den." + +#. (itstool) path: sect1/title +#: C/index.docbook:1704 +msgid "Editing the master document" +msgstr "Redigera huvuddokumentet" + +#. (itstool) path: sect1/para +#: C/index.docbook:1706 +msgid "" +"GTK-Doc produces documentation in DocBook SGML/XML. When processing the " +"inline source comments, the GTK-Doc tools generate one documentation page " +"per class or module as a separate file. The master document includes them " +"and place them in an order." +msgstr "" +"GTK-Doc producerar dokumentation i DocBook SGML/XML. När infogade " +"källkodskommentarer behandlas genererar GTK-Doc en dokumentationssida per " +"klass eller modul som en separat fil. Huvuddokumentet inkluderar dem och " +"placerar dem i en ordning." + +# sebras: Its -> it's +#. (itstool) path: sect1/para +#: C/index.docbook:1713 +msgid "" +"While GTK-Doc creates a template master document for you, later runs will " +"not touch it again. This means that one can freely structure the " +"documentation. That includes grouping pages and adding extra pages. GTK-Doc " +"has now a test suite, where also the master-document is recreated from " +"scratch. Its a good idea to look at this from time to time to see if there " +"are some new goodies introduced there." +msgstr "" +"Även om GTK-Doc skapar en mall för huvuddokumentet åt dig kommer senare " +"körningar inte att röra det igen. Detta innebär att man är fri att " +"strukturera om dokumentationen. Detta inkluderar att gruppera sidor och " +"lägga till extra sidor. GTK-Doc har numera en testsvit där också " +"huvuddokumentet återskapas från grunden. Det är en bra idé att titta på " +"detta då och då för att se om några nya godsaker införts där." + +# sebras: for -> from Apart -> together/embedded... +#. (itstool) path: tip/para +#: C/index.docbook:1723 +msgid "" +"Do not create tutorials as extra documents. Just write extra chapters. The " +"benefit of directly embedding the tutorial for your library into the API " +"documentation is that it is easy to link for the tutorial to symbol " +"documentation. Apart chances are higher that the tutorial gets updates along " +"with the library." +msgstr "" +"Skapa inte handledningar som extra dokument. Skriv bara extra kapitel. " +"Fördelen med att bädda in handledningen direkt i ditt biblioteks " +"gränssnittsdokumentation är att det är enkelt att länka från handledningen " +"till symboldokumentationen. Inbäddad är det större chans att handledningen " +"blir uppdaterad tillsammans med biblioteket." + +#. (itstool) path: sect1/para +#: C/index.docbook:1732 +msgid "" +"So what are the things to change inside the master document? For a start is " +"only a little. There are some placeholders (text in square brackets) there " +"which you should take care of." msgstr "" +"Så vilka saker ska ändras i huvuddokumentet? I början är det väldigt lite. " +"Det finns en del platshållare (text i hakparenteser) som du bör ta hand om." -#: C/gtk-doc-manual.xml:1185(title) +#. (itstool) path: example/title +#: C/index.docbook:1739 msgid "Master document header" +msgstr "Huvuddokumentets huvud" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1740 +#, no-wrap +msgid "" +"\n" +"<bookinfo>\n" +" <title>MODULENAME Reference Manual</title>\n" +" <releaseinfo>\n" +" for MODULENAME [VERSION]\n" +" The latest version of this documentation can be found on-line at\n" +" <ulink role=\"online-location\" url=\"http://[SERVER]/MODULENAME/index.html\">http://[SERVER]/MODULENAME/</ulink>.\n" +" </releaseinfo>\n" +"</bookinfo>\n" +"\n" +"<chapter>\n" +" <title>[Insert title here]</title>\n" +msgstr "" +"\n" +"<bookinfo>\n" +" <title>MODULNAMN handbok</title>\n" +" <releaseinfo>\n" +" för MODULNAMN [VERSION]\n" +" Den senaste versionen av detta dokument kan hittas på nätet på\n" +" <ulink role=\"online-location\" url=\"http://[SERVER]/MODULNAMN/index.html\">http://[SERVER]/MODULNAMN/</ulink>.\n" +" </releaseinfo>\n" +"</bookinfo>\n" +"\n" +"<chapter>\n" +" <title>[Infoga titel här]</title>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1756 +msgid "" +"In addition a few option elements are created in commented form. You can " +"review these and enable them as you like." msgstr "" +"Dessutom finns det ett antal valfria element som skapas i kommenterad form. " +"Du kan granska dessa och aktivera dem enligt dina egna önskemål." + +#. (itstool) path: example/title +#: C/index.docbook:1762 +msgid "Optional part in the master document" +msgstr "Valfri del i huvuddokumentet" -#: C/gtk-doc-manual.xml:1207(title) +#. (itstool) path: example/programlisting +#: C/index.docbook:1763 +#, no-wrap +msgid "" +"\n" +" <!-- enable this when you use gobject introspection annotations\n" +" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n" +" -->\n" +msgstr "" +"\n" +" <!-- aktivera detta om du vill använda gobject introspection-noteringar\n" +" <xi:include href=\"xml/annotation-glossary.xml\"><xi:fallback /></xi:include>\n" +" -->\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1771 +msgid "" +"Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will remind " +"you of newly generated xml files that are not yet included into the doc." +msgstr "" +"Slutligen behöver du lägga till ett nytt avsnitt när du infogar det. " +"Verktyget gtkdoc-check " +"kommer att påminna dig om nyligen genererade xml-filer som ännu inte " +"infogats i dokumentationen." + +#. (itstool) path: example/title +#: C/index.docbook:1779 C/index.docbook:1814 +msgid "Including generated sections" +msgstr "Inkludera genererade avsnitt" + +#. (itstool) path: example/programlisting +#: C/index.docbook:1780 +#, no-wrap +msgid "" +"\n" +" <chapter>\n" +" <title>my library</title>\n" +" <xi:include href=\"xml/object.xml\"/>\n" +" ...\n" +msgstr "" +"\n" +" <chapter>\n" +" <title>mitt bibliotek</title>\n" +" <xi:include href=\"xml/object.xml\"/>\n" +" ...\n" + +#. (itstool) path: sect1/title +#: C/index.docbook:1792 msgid "Editing the section file" -msgstr "" +msgstr "Redigera avsnittsfilen" -#: C/gtk-doc-manual.xml:1209(para) -msgid "The section file is used to organise the documentation output by Gtk-Doc. Here one specifies which symbol belongs to which module or class and control the visibility (public or private)." +#. (itstool) path: sect1/para +#: C/index.docbook:1794 +msgid "" +"The section file is used to organise the documentation output by GTK-Doc. " +"Here one specifies which symbol belongs to which module or class and control " +"the visibility (public or private)." msgstr "" +"Avsnittsfilen används för att organisera dokumentationsutdata från GTK-Doc. " +"Här kan man ange vilken symbol som hör till vilken modul eller klass och " +"styra synligheten (publik eller privat)." -#: C/gtk-doc-manual.xml:1215(para) -msgid "The section file is a plain test file with xml like syntax (using tags). Blank lines are ignored and lines starting with a '#' are treated as comment lines." +#. (itstool) path: sect1/para +#: C/index.docbook:1800 +msgid "" +"The section file is a plain text file with tags delimiting sections. Blank " +"lines are ignored and lines starting with a '#' are treated as comment lines." msgstr "" +"Avsnittsfilen är en vanlig textfil med taggar som avgränsar avsnitt. " +"Blankrader ignoreras och rader som börjar med ett ”#” behandlas som " +"kommentarsrader." -#: C/gtk-doc-manual.xml:1221(para) -msgid "The <FILE> ... </FILE> tag is used to specify the file name, without any suffix. For example, using '<FILE>gnome-config</FILE>' will result in the section declarations being output in the template file tmpl/gnome-config.sgml, which will be converted into the DocBook SGML 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)." +#. (itstool) path: note/para +#: C/index.docbook:1807 +msgid "" +"While the tags make the file look like xml, it is not. Please do not close " +"tags like <SUBSECTION>." msgstr "" +"Även om taggarna får filen att se ut som xml, är det inte det. Avsluta inte " +"taggar så som <SUBSECTION>." -#: C/gtk-doc-manual.xml:1233(para) -msgid "The <TITLE> ... </TITLE> tag is used to specify the title of the section. It is only useful before the templates are initially created, since the title set in the template file overrides this." -msgstr "" +#. (itstool) path: example/programlisting +#: C/index.docbook:1815 +#, no-wrap +msgid "" +"\n" +"<INCLUDE>libmeep/meep.h</INCLUDE>\n" +"\n" +"<SECTION>\n" +"<FILE>meepapp</FILE>\n" +"<TITLE>MeepApp</TITLE>\n" +"MeepApp\n" +"<SUBSECTION Standard>\n" +"MEEP_APP\n" +"...\n" +"MeepAppClass\n" +"meep_app_get_type\n" +"</SECTION>\n" +msgstr "" +"\n" +"<INCLUDE>libmeep/meep.h</INCLUDE>\n" +"\n" +"<SECTION>\n" +"<FILE>meepapp</FILE>\n" +"<TITLE>MeepApp</TITLE>\n" +"MeepApp\n" +"<SUBSECTION Standard>\n" +"MEEP_APP\n" +"...\n" +"MeepAppClass\n" +"meep_app_get_type\n" +"</SECTION>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:1832 +msgid "" +"The <FILE> ... </FILE> tag is used to specify the file name, " +"without any suffix. For example, using '<FILE>gnome-config</" +"FILE>' will result in the section declarations being output in the " +"template file tmpl/gnome-config.sgml, which will be " +"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 "" +"Taggen <FILE> … </FILE> används för att ange filnamnet, utan " +"något suffix. Om man t.ex. använder ”<FILE>gnome-config</FILE>” " +"blir resultatet att avsnittsdeklarationerna matas ut i mallfilen " +"tmpl/gnome-config.sgml, som kommer att konverteras till " +"DocBook XML-filen xml/gnome-config.sgml eller DocBook " +"XML-filen xml/gnome-config.xml. (Namnet på HTML-filen " +"baseras på modulnamnet och avsnittstiteln, för GObject baseras det på " +"klassnamnet för GObjectet konverterat till gemener)." + +#. (itstool) path: sect1/para +#: C/index.docbook:1844 +msgid "" +"The <TITLE> ... </TITLE> tag is used to specify the title of the " +"section. It is only useful before the templates (if used) are initially " +"created, since the title set in the template file overrides this. Also if " +"one uses SECTION comment in the sources, this is obsolete." +msgstr "" +"Taggen <TITLE> … </TITLE> används för att ange titeln på " +"avsnittet. Det är bara användbart före mallar skapas initialt (om de " +"används), eftersom titeln som ställs in i avsnittsfilen åsidosätter denna. " +"Vidare är detta föråldrat om man använder SECTIONS-kommentarer i källkoden." + +#. (itstool) path: sect1/para +#: C/index.docbook:1851 +msgid "" +"You can group items in the section by using the <SUBSECTION> tag. " +"Currently it outputs a blank line between subsections in the synopsis " +"section. You can also use <SUBSECTION Standard> for standard GObject " +"declarations (e.g. the functions like g_object_get_type and macros like " +"G_OBJECT(), G_IS_OBJECT() etc.). Currently these are left out of the " +"documentation. You can also use <SUBSECTION Private> for private " +"declarations which will not be output (it is a handy way to avoid warning " +"messages about unused declarations). If your library contains private types " +"which you don't want to appear in the object hierarchy and the list of " +"implemented or required interfaces, add them to a Private subsection. " +"Whether you would place GObject and GObjectClass like structs in public or " +"Standard section depends if they have public entries (variables, vmethods)." +msgstr "" +"Du kan gruppera objekt i avsnittet genom att använda taggen <" +"SUBSECTION>. För närvarande matas en blankrad ut mellan underavsnitt i " +"sammanfattningsavsnittet. Du kan också använda <SUBSECTION Standard> " +"för standard GObject-deklarationer (t.ex. funktioner så som " +"g_object_get_type och makron som G_OBJECT(), G_IS_OBJECT(), etc.). För " +"närvarande utelämnas dessa ur dokumentationen. Du kan också använda <" +"SUBSECTION Private> för privata deklarationer som inte kommer att matas " +"ut (det är ett bekvämt sätt att undvika varningsmeddelanden om oanvända " +"deklarationer). Om ditt bibliotek innehåller privata typer som du inte vill " +"ska dyka upp i objekthierarkin och i listan över implementerade eller krävda " +"gränssnitt, lägg till dem i ett privat avsnitt. Huruvida du vill placera " +"GObject och GObjectClass-liknande strukturer i publika eller standardavsnitt " +"beror på om de har publika poster (variabler, virtuella metoder)." + +#. (itstool) path: sect1/para +#: C/index.docbook:1870 +msgid "" +"You can also use <INCLUDE> ... </INCLUDE> to specify the " +"#include files which are shown in the synopsis sections. It contains a comma-" +"separate list of #include files, without the angle brackets. If you set it " +"outside of any sections, it acts for all sections until the end of the file. " +"If you set it within a section, it only applies to that section." +msgstr "" +"Du kan också använda <INCLUDE> ... </INCLUDE> för att ange " +"#include-filerna som ska visas i sammanfattningsavsnitten. Den innehåller en " +"kommaavgränsad lista av #include-filer, utan vinkelparenteser. Om du ställer " +"in det utanför några avsnitt kommer det att påverka alla avsnitt tills " +"slutet på filen. Om du ställer in det inom ett avsnitt kommer det bara att " +"påverka det avsnittet." + +#. (itstool) path: chapter/title +#: C/index.docbook:1884 +msgid "Controlling the result" +msgstr "Kontrollera resultatet" -#: C/gtk-doc-manual.xml:1239(para) -msgid "You can group items in the section by using the <SUBSECTION> tag. Currently it outputs a blank line between subsections in the synopsis section. You can also use <SUBSECTION Standard> for standard GObject declarations (e.g. the functions like g_object_get_type and macros like G_OBJECT(), G_IS_OBJECT() etc.). Currently these are left out of the documentation. You can also use <SUBSECTION Private> for private declarations which will not be output (It is a handy way to avoid warning messages about unused declarations.). If your library contains private types which you don't want to appear in the object hierarchy and the list of implemented or required interfaces, add them to a Private subsection." +#. (itstool) path: chapter/para +#: C/index.docbook:1886 +msgid "" +"A GTK-Doc run generates report files inside the documentation directory. The " +"generated files are named: <package>-undocumented.txt, <package>-undeclared.txt and " +"<package>-unused.txt. All those are plain text " +"files that can be viewed and postprocessed easily." +msgstr "" +"En GTK-Doc-körning genererar rapportfiler inuti dokumentationskatalogen. De " +"genererade filerna heter: <paket>-undocumented.txt, <paket>-undeclared.txt och " +"<paket>-unused.txt. Alla är vanliga textfiler och " +"kan visas eller efterbehandlas enkelt." + +#. (itstool) path: chapter/para +#: C/index.docbook:1895 +msgid "" +"The <package>-undocumented.txt file starts with " +"the documentation coverage summary. Below are two sections divided by blank " +"lines. The first section lists undocumented or incomplete symbols. The " +"second section does the same for section docs. Incomplete entries are those, " +"which have documentation, but where e.g. a new parameter has been added." +msgstr "" +"Filen <paket>-undocumented.txt inleds med en " +"sammanfattning över hur mycket dokumentation som skrivits. Under det finns " +"två avsnitt avgränsade av blankrader. Det första avsnittet listar " +"odokumenterade eller ofullständiga symboler. Det andra avsnittet gör " +"detsamma för avsnittsdokumentation. Ofullständiga poster är de som har " +"dokumentation, men där en ny parameter har lagts till." + +#. (itstool) path: chapter/para +#: C/index.docbook:1904 +msgid "" +"The <package>-undeclared.txt file lists symbols " +"given in the <package>-sections.txt but not found " +"in the sources. Check if they have been removed or if they are misspelled." msgstr "" +"Filen <paket>-undeclared.txt listar symboler som " +"anges i <paket>-sections.txt men inte hittas i " +"källkoden. Kontrollera om de har tagits bort eller om de är felstavade." -#: C/gtk-doc-manual.xml:1255(para) -msgid "You can also use <INCLUDE> ... </INCLUDE> to specify the #include files which are shown in the synopsis sections. It contains a comma-separate list of #include files, without the angle brackets. If you set it outside of any sections, it acts for all sections until the end of the file. If you set it within a section, it only applies to that section." +#. (itstool) path: chapter/para +#: C/index.docbook:1911 +msgid "" +"The <package>-unused.txt file lists symbol names, " +"where the GTK-Doc scanner has found documentation, but does not know where " +"to put it. This means that the symbol has not yet been added to the " +"<package>-sections.txt file." +msgstr "" +"Filen <paket>-unused.txt listar symbolnamn där " +"GTK-Doc-detektorn har hittat dokumentation men inte vet var den ska " +"placeras. Detta innebär att symbolen ännu inte har lagts till i filen " +"<package>-sections.txt." + +# sebras: ? +#. (itstool) path: tip/para +#: C/index.docbook:1919 +msgid "" +"Enable or add the line in Makefile." +"am. If at least GTK-Doc 1.9 is installed, this will run sanity checks during " +"make check run." msgstr "" +"Aktivera eller lägg till raden i " +"Makefile.am. Om åtminstone GTK-Doc 1.9 finns installerat kommer detta att " +"köra rimlighetskontroller under körning av make check." -#: C/gtk-doc-manual.xml:1269(title) -msgid "Controlling the result" +#. (itstool) path: chapter/para +#: C/index.docbook:1926 +msgid "" +"One can also look at the files produced by the source code scanner: " +"<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." +msgstr "" +"Man kan också titta på filerna som producerats av källkodsdetektorn: " +"<paket>-decl-list.txt och <paket>-" +"decl.txt. Den första kan jämföras med avsnittsfilen om den " +"underhålls manuellt. Den andra listar alla deklarationer från huvudena. Om " +"en symbol saknas bör man kontrollera om denna filen innehåller den." + +#. (itstool) path: chapter/para +#: C/index.docbook:1935 +msgid "" +"If the project is GObject based, one can also look into the files produced " +"by the object scanner: <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 GTK-Doc " +"to keep the intermediate scanner file for further analysis, by running it as " +"GTK_DOC_KEEP_INTERMEDIATE=1 make." +msgstr "" +"Om projektet är GObject-baserat kan man också titta på filerna som " +"producerats av objekt-detektorn: <paket>.args.txt, <paket>.hierarchy.txt, <" +"paket>.interfaces.txt, <paket>.prerequisites." +"txt och <paket>.signals.txt. Om det " +"saknas symboler i någon av dem kan man be GTK-Doc att bibehålla de temporära " +"detektorfilerna för vidare analys, genom att köra det som " +"GTK_DOC_KEEP_INTERMEDIATE=1 make." + +#. (itstool) path: chapter/title +#: C/index.docbook:1950 +msgid "Modernizing the documentation" +msgstr "Modernisera dokumentationen" + +#. (itstool) path: chapter/para +#: C/index.docbook:1952 +msgid "" +"GTK-Doc has been around for quite some time. In this section we list new " +"features together with the version since when it is available." msgstr "" +"GTK-Doc har funnits ett tag. I detta avsnitt listar vi nya funktioner " +"tillsammans med vilken version de gjordes tillgängliga." -#: C/gtk-doc-manual.xml:1271(para) -msgid "A Gtk-Doc run generates report files inside the documentation directory. The generated files are named: <package>-undocumented.txt, <package>-undeclared.txt and <package>-unused.txt. All those are plain text files that can be viewed and postprocessed easily." -msgstr "" +#. (itstool) path: sect1/title +#: C/index.docbook:1958 +msgid "GTK-Doc 1.9" +msgstr "GTK-Doc 1.9" -#: C/gtk-doc-manual.xml:1280(para) -msgid "The <package>-undocumented.txt file starts with the documentation coverage summary. Below are two sections divided by blank lines. The first section lists undocumented or incomplete symbols. The second section does the same for section docs. Incomplete entries are those, which have documentation, but where e.g. a new parameter has been added." +#. (itstool) path: sect1/para +#: C/index.docbook:1960 +msgid "" +"When using xml instead of sgml, one can actually name the master document " +"<package>-docs.xml." msgstr "" +"När man använder xml istället för sgml, kan man faktiskt kalla " +"huvuddokumentet <paket>-docs.xml." -#: C/gtk-doc-manual.xml:1289(para) -msgid "The <package>-undeclared.txt file lists symbols given in the <package>-section.txt but not found in the sources. Check if they have been removed or if they are misspelled." +#. (itstool) path: sect1/para +#: C/index.docbook:1965 +msgid "" +"This version supports 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 "" +"Denna version har stöd för " +"i Makefile.am. När detta är aktiverat kommer " +"<paket>-sections.txt att autogenereras och kan " +"tas bort från versionshanteringssystemet. Detta fungerar bra för projekt som " +"har en väldigt standardiserad struktur (t.ex. kommer varje .{c,h}-par att " +"skapa ett nytt avsnitt). Om man organiserar ett projekt likt detta kommer " +"den manuella uppdateringen av en avsnittsfil att vara så enkelt som att köra " +"meld <paket>-decl-list.txt <paket>-sections.txt." + +#. (itstool) path: sect1/para +#: C/index.docbook:1976 +msgid "" +"Version 1.8 already introduced the syntax for documenting sections in the " +"sources instead of the separate files under 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 "" +"Redan version 1.8 introducerade syntaxen för avsnittsdokumentation i " +"källkoden istället för separata filer under tmpl. Denna version lägger till flaggor för att kunna ställa " +"om hela dokumentationsmodulen till att inte använda det extra tmpl-" +"byggsteget alls, genom att använda i " +"configure.ac. Om du inte har tmpl incheckat i ditt versionshanteringssystem just nu och " +"inte har gått över än bara lägg till flaggan i configure.ac så är du klar." + +#. (itstool) path: sect1/title +#: C/index.docbook:1988 +msgid "GTK-Doc 1.10" +msgstr "GTK-Doc 1.10" + +#. (itstool) path: sect1/para +#: C/index.docbook:1990 +msgid "" +"This version supports 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 "" +"Denna version har stöd för i " +"Makefile.am. När det är aktiverat kommer <" +"package>.types att autogenereras och kan tas bort från " +"versionshanteringssystemet. När denna funktion används är det viktigt att " +"också ställa in IGNORE_HFILES i Makefile.am för kod som bara byggs ibland." + +#. (itstool) path: sect1/title +#: C/index.docbook:2001 +msgid "GTK-Doc 1.16" +msgstr "GTK-Doc 1.16" + +#. (itstool) path: example/title +#: C/index.docbook:2007 +msgid "Enable gtkdoc-check" +msgstr "Aktivera gtkdoc-check" + +#. (itstool) path: example/programlisting +#: C/index.docbook:2008 +#, no-wrap +msgid "" +"\n" +"if ENABLE_GTK_DOC\n" +"TESTS_ENVIRONMENT = \\\n" +" DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \\\n" +" SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)\n" +"TESTS = $(GTKDOC_CHECK)\n" +"endif\n" +msgstr "" +"\n" +"if ENABLE_GTK_DOC\n" +"TESTS_ENVIRONMENT = \\\n" +" DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \\\n" +" SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)\n" +"TESTS = $(GTKDOC_CHECK)\n" +"endif\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:2003 +msgid "" +"This version includes a new tool called gtkdoc-check. This tool can run a " +"set of sanity checks on your documentation. It is enabled by adding these " +"lines to the end of Makefile.am. <_:example-1/>" +msgstr "" +"Denna version har stöd för ett nytt verktyg som heter gtkdoc-check. Detta " +"verktyg kan köra en uppsättning kontroller på din dokumentation. Det " +"aktiveras genom att lägga till dessa raderna i slutet av Makefile." +"am. <_:example-1/>" + +#. (itstool) path: sect1/title +#: C/index.docbook:2021 +msgid "GTK-Doc 1.20" +msgstr "GTK-Doc 1.20" + +#. (itstool) path: sect1/para +#: C/index.docbook:2023 +msgid "" +"Version 1.18 brought some initial markdown support. Using markdown in doc " +"comments is less intrusive than writing docbook xml. This version improves a " +"lot on this and add a lot more styles. The section that explains the comment syntax has all the details." +msgstr "" +"Version 1.18 införde inledande stöd för markdown. Att använda markdown i " +"dokumentationskommentarer är mindre påträngande än att skriva docbook xml. " +"Denna version förbättrar detta väsentligt och lägger till många fler stilar. " +"Avsnittet som beskriver kommentarsyntax finnas alla detaljer." + +#. (itstool) path: sect1/title +#: C/index.docbook:2033 +msgid "GTK-Doc 1.25" +msgstr "GTK-Doc 1.25" + +#. (itstool) path: example/title +#: C/index.docbook:2043 +msgid "Use pre-generated entities" +msgstr "Att använda förgenererade entiteter" + +#. (itstool) path: example/programlisting +#: C/index.docbook:2044 +#, no-wrap +msgid "" +"\n" +"<?xml version=\"1.0\"?>\n" +"<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"\n" +" \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"\n" +"[\n" +" <!ENTITY % local.common.attrib \"xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'\">\n" +" <!ENTITY % gtkdocentities SYSTEM \"xml/gtkdocentities.ent\">\n" +" %gtkdocentities;\n" +"]>\n" +"<book id=\"index\" xmlns:xi=\"http://www.w3.org/2003/XInclude\">\n" +" <bookinfo>\n" +" <title>&package_name; Reference Manual</title>\n" +" <releaseinfo>\n" +" for &package_string;.\n" +" The latest version of this documentation can be found on-line at\n" +" <ulink role=\"online-location\" url=\"http://[SERVER]/&package_name;/index.html\">http://[SERVER]/&package_name;/</ulink>.\n" +" </releaseinfo>\n" +" </bookinfo>\n" +msgstr "" +"\n" +"<?xml version=\"1.0\"?>\n" +"<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.3//EN\"\n" +" \"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd\"\n" +"[\n" +" <!ENTITY % local.common.attrib \"xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'\">\n" +" <!ENTITY % gtkdocentities SYSTEM \"xml/gtkdocentities.ent\">\n" +" %gtkdocentities;\n" +"]>\n" +"<book id=\"index\" xmlns:xi=\"http://www.w3.org/2003/XInclude\">\n" +" <bookinfo>\n" +" <title>&package_name; handbok</title>\n" +" <releaseinfo>\n" +" för &package_string;.\n" +" Den senaste versionen av detta dokument kan hittas på nätet på\n" +" <ulink role=\"online-location\" url=\"http://[SERVER]/&package_name;/index.html\">http://[SERVER]/&package_name;/</ulink>.\n" +" </releaseinfo>\n" +" </bookinfo>\n" + +#. (itstool) path: sect1/para +#: C/index.docbook:2035 +msgid "" +"The makefiles shipped with this version generate an entity file at " +"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 "" +"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. <_:example-1/>" + +#. (itstool) path: chapter/title +#: C/index.docbook:2069 +msgid "Documenting other interfaces" +msgstr "Dokumentera andra gränssnitt" + +#. (itstool) path: chapter/para +#: C/index.docbook:2071 +msgid "" +"So far we have been using GTK-Doc to document the API of code. The next " +"sections contain suggestions how the tools can be used to document other " +"interfaces too." msgstr "" +"Så här långt har vi använt GTK-Doc för att dokumentera API:t för koden. " +"Följande avsnitt innehåller förslag om hur verktyget kan användas för att " +"också dokumentera andra gränssnitt." -#: C/gtk-doc-manual.xml:1296(para) -msgid "The <package>-unused.txt file lists symbol names, where the Gtk-Doc scanner has found documentation, but does not know where to put it. This means that the symbol has not yet been added to the <package>-section.txt file." -msgstr "" +#. (itstool) path: sect1/title +#: C/index.docbook:2078 +msgid "Command line options and man pages" +msgstr "Kommandoradsflaggor och mansidor" -#: C/gtk-doc-manual.xml:1304(para) -msgid "Enable or add the line in Makefile.am. If at least gtk-doc 1.9 is installed, this will run sanity checks during make check run." +#. (itstool) path: sect1/para +#: C/index.docbook:2080 +msgid "" +"As one can generate man pages for a docbook refentry as well, it sounds like " +"a good idea to use it for that purpose. This way the interface is part of " +"the reference and one gets the man-page for free." +msgstr "" +"Då man också kan generera mansidor för ett docbook-refentry, låter det som " +"en bra idé att använda det för detta ändamål. På detta sättet kommer " +"gränssnittet att vara en del av referensen och man får mansidan gratis." + +#. (itstool) path: sect2/title +#: C/index.docbook:2087 +msgid "Document the tool" +msgstr "Dokumentera verktyget" + +# sebras: strange English +#. (itstool) path: sect2/para +#: C/index.docbook:2089 +msgid "" +"Create one refentry file per tool. Following our example we would call it meep/" +"docs/reference/meeper/meep.xml. For the xml tags that should be " +"used and can look at generated file in the xml subdirectory as well as " +"examples e.g. in glib." +msgstr "" +"Skapa en refentry-fil per verktyg. Om du följer vårt exempel borde vi kalla det meep/" +"docs/reference/meeper/meep.xml. För xml-taggarna bör detta " +"användas och man kan studera den genererade filen i xml-underkatalogen så " +"väl som exempel i glib." + +#. (itstool) path: sect2/title +#: C/index.docbook:2099 +msgid "Adding the extra configure check" +msgstr "Lägga till den extra configure-kontrollen" + +#. (itstool) path: example/title +#: C/index.docbook:2102 C/index.docbook:2120 +msgid "Extra configure checks" +msgstr "Lägga till extra configure-kontroller" + +#. (itstool) path: example/programlisting +#: C/index.docbook:2103 +#, no-wrap +msgid "" +"\n" +"AC_ARG_ENABLE(man,\n" +" [AC_HELP_STRING([--enable-man],\n" +" [regenerate man pages from Docbook [default=no]])],enable_man=yes,\n" +" enable_man=no)\n" +"\n" +"AC_PATH_PROG([XSLTPROC], [xsltproc])\n" +"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" +msgstr "" +"\n" +"AC_ARG_ENABLE(man,\n" +" [AC_HELP_STRING([--enable-man],\n" +" [omgenerera mansidor från Docbook [standardvärde=no]])],enable_man=yes,\n" +" enable_man=no)\n" +"\n" +"AC_PATH_PROG([XSLTPROC], [xsltproc])\n" +"AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)\n" + +#. (itstool) path: sect2/title +#: C/index.docbook:2117 +msgid "Adding the extra makefile rules" +msgstr "Lägga till de extra makefilsreglerna" + +#. (itstool) path: example/programlisting +#: C/index.docbook:2121 +#, no-wrap +msgid "" +"\n" +"man_MANS = \\\n" +" meeper.1\n" +"\n" +"if ENABLE_GTK_DOC\n" +"if ENABLE_MAN\n" +"\n" +"%.1 : %.xml\n" +" @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<\n" +"\n" +"endif\n" +"endif\n" +"\n" +"BUILT_EXTRA_DIST = $(man_MANS)\n" +"EXTRA_DIST += meep.xml\n" +msgstr "" +"\n" +"man_MANS = \\\n" +" meeper.1\n" +"\n" +"if ENABLE_GTK_DOC\n" +"if ENABLE_MAN\n" +"\n" +"%.1 : %.xml\n" +" @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<\n" +"\n" +"endif\n" +"endif\n" +"\n" +"BUILT_EXTRA_DIST = $(man_MANS)\n" +"EXTRA_DIST += meep.xml\n" + +#. (itstool) path: sect1/title +#: C/index.docbook:2143 +msgid "DBus interfaces" +msgstr "DBus-gränssnitt" + +#. (itstool) path: sect1/para +#: C/index.docbook:2145 +msgid "" +"(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" +"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" msgstr "" +"(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://" +"cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)" -#: C/gtk-doc-manual.xml:1314(title) -msgid "Frequently asked question" +#. (itstool) path: chapter/title +#: C/index.docbook:2154 +msgid "Frequently asked questions" msgstr "Frågor och svar" -#: C/gtk-doc-manual.xml:1318(segtitle) +#. (itstool) path: segmentedlist/segtitle +#: C/index.docbook:2158 msgid "Question" msgstr "Fråga" -#: C/gtk-doc-manual.xml:1319(segtitle) +#. (itstool) path: segmentedlist/segtitle +#: C/index.docbook:2159 msgid "Answer" msgstr "Svar" -#: C/gtk-doc-manual.xml:1321(seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2161 msgid "No class hierarchy." -msgstr "" +msgstr "Ingen klasshierarki." -#: C/gtk-doc-manual.xml:1322(filename) -msgid ".types" -msgstr "" - -#: C/gtk-doc-manual.xml:1322(seg) -msgid "The objects _get_type() function has not been entered into the file." +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2162 +msgid "" +"The objects xxx_get_type() function has not been " +"entered into the <package>.types file." msgstr "" +"Objektens xxx_get_type()-funktion har inte matats in i " +"filen <paket>.types." -#: C/gtk-doc-manual.xml:1325(seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2168 msgid "Still no class hierarchy." -msgstr "" - -#: C/gtk-doc-manual.xml:1326(ulink) -msgid "explanation" -msgstr "förklaring" +msgstr "Fortfarande ingen klasshierarki." -#: C/gtk-doc-manual.xml:1326(seg) -msgid "Wrong naming in section file (see )" +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2169 +msgid "" +"Missing or wrong naming in <package>-sections.txt " +"file (see explanation)." msgstr "" +"Saknat eller fel namn i filen <paket>-sections.txt (se förklaring)." -#: C/gtk-doc-manual.xml:1329(seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2175 msgid "Damn, I have still no class hierarchy." -msgstr "" +msgstr "Förbannat, jag har fortfarande ingen klasshierarki." -#: C/gtk-doc-manual.xml:1330(seg) -msgid "Is the object name (name of the instance struct) part of the normal section (don't put this into Standard or Private)." +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2176 +msgid "" +"Is the object name (name of the instance struct, e.g. GtkWidget) part of the normal section (don't put this into Standard or Private " +"subsections)." msgstr "" +"Är objektnamnet (namnet på instansstrukturen, t.ex. GtkWidget) " +"del av det normala avsnittet (stoppa inte detta i underavsnitt så som " +"Standard eller Private)." -#: C/gtk-doc-manual.xml:1333(seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2183 msgid "No symbol index." -msgstr "" +msgstr "Inget symbolindex." -#: C/gtk-doc-manual.xml:1334(seg) -msgid "FIXME (<index> tag in main sgml file)" +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2184 +msgid "" +"Does the <package>-docs.{xml,sgml} contain a " +"index that xi:includes the generated index?" msgstr "" +"Innehåller <paket>-docs.{xml,sgml} ett index som " +"inkluderar det genererade indexet med xi:include?" -#: C/gtk-doc-manual.xml:1337(seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2190 msgid "Symbols are not linked to their doc-section." -msgstr "" +msgstr "Symboler är inte länkade till deras dokumentationsavsnitt." -#: C/gtk-doc-manual.xml:1338(seg) -msgid "FIXME (added #,% or () ?)" +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2191 +msgid "" +"Is the doc-comment using the correct markup (added #,% or ())? Check if the " +"gtkdoc-fixxref warns about unresolvable xrefs." msgstr "" +"Använder dokumentationskommentaren korrekta taggar (har du lagt till #, % " +"eller ())? Kontrollera om gtkdoc-fixxref varnar om oupplösbara " +"korsreferenser." -#: C/gtk-doc-manual.xml:1341(seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2197 msgid "A new class does not appear in the docs." -msgstr "" +msgstr "En ny klass dyker inte upp i dokumentationen." -#: C/gtk-doc-manual.xml:1342(seg) -msgid "FIXME (section file, types file, main-sgml file)" +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2198 +msgid "" +"Is the new page xi:included from <package>-docs.{xml,sgml}." msgstr "" +"Är den nya sidan inkluderad med xi:include från <package>-" +"docs.{xml,sgml}." -#: C/gtk-doc-manual.xml:1345(seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2204 msgid "A new symbol does not appear in the docs." -msgstr "" +msgstr "En ny symbol dyker inte upp i dokumentationen." -#: C/gtk-doc-manual.xml:1346(seg) -msgid "FIXME (section file, proper doc comment)" +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2205 +msgid "" +"Is the doc-comment properly formatted. Check for spelling mistakes in the " +"begin of the comment. Check if the gtkdoc-fixxref warns about unresolvable " +"xrefs. Check if the symbol is correctly listed in the <" +"package>-sections.txt in a public subsection." +msgstr "" +"Är dokumentationskommentaren korrekt formaterad. Leta efter stavfel i början " +"av kommentaren. Kontrollera om gtkdoc-fixxref varnar om oupplösbara " +"korsreferenser. Kontrollera om symbolen finns korrekt listad i <" +"paket>-sections.txt i ett publikt avsnitt." + +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2213 +msgid "A type is missing from the class hierarchy." +msgstr "En typ saknas från klasshierarkin." + +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2214 +msgid "" +"If the type is listed in <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 incidentally marked private it will not be shown." +msgstr "" +"Om typen finns listad i <paket>.hierarchy men " +"inte i xml/tree_index.sgml, dubbelkolla då att typen " +"finns korrekt placerad i <paket>-sections.txt. Om " +"typinstansen (t.ex. GtkWidget) inte visas eller är markerad " +"privat kommer den inte att visas." + +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2223 +msgid "I get foldoc links for all gobject annotations." +msgstr "Jag får foldoc-länkar för alla gobject-noteringar." + +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2224 +msgid "" +"Check that xml/annotation-glossary.xml is xi:included " +"from <package>-docs.{xml,sgml}." msgstr "" +"Kontrollera att xml/annotation-glossary.xml är " +"inkluderad med xi:include från <package>-docs.{xml,sgml}." -#: C/gtk-doc-manual.xml:1351(seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2232 msgid "Parameter described in source code comment block but does not exist" -msgstr "" +msgstr "Parameter beskriven i kommentarsblock i källkoden men existerar inte" -#: C/gtk-doc-manual.xml:1352(seg) -msgid "Check if the prototype in the header has different parameter names as in the source." +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2233 +msgid "" +"Check if the prototype in the header has different parameter names as in the " +"source." msgstr "" +"Kontrollera om prototypen i huvudet har andra parameternamn än i källkoden." -#: C/gtk-doc-manual.xml:1356(seg) +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2238 msgid "multiple \"IDs\" for constraint linkend: XYZ" +msgstr "multipla ”ID:n” för begränsat länkslut: XYZ" + +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2239 +msgid "" +"Symbol XYZ appears twice in <package>-sections.txt file." msgstr "" +"Symbolen XYZ förekommer två gånger i filen <paket>-sections." +"txt." + +#. (itstool) path: seglistitem/seg +#: C/index.docbook:2242 +msgid "" +"Element typename in namespace '' encountered in para, but no template " +"matches." +msgstr "Elementtypnamn i namnrymd ”” påträffat i para, men ingen mall matchar." + +#. (itstool) path: chapter/title +#: C/index.docbook:2249 +msgid "Tools related to gtk-doc" +msgstr "Verktyg relaterade till gtk-doc" -#: C/gtk-doc-manual.xml:1357(seg) -msgid "Symbol XYZ appears twice in -section.txt file." +#. (itstool) path: chapter/para +#: C/index.docbook:2251 +msgid "" +"GtkDocPlugin - a Trac " +"GTK-Doc integration plugin, that adds API docs to a trac site and " +"integrates with the trac search." msgstr "" +"GtkDocPlugin - en insticksmodul för Trac GTK-Doc-integrering som lägger till API-" +"dokumentation till en trac-webbplats och integrerar med trac-sökningen." -#: C/gtk-doc-manual.xml:1360(seg) -msgid "Element typename in namespace '' encountered in para, but no template matches." +#. (itstool) path: chapter/para +#: C/index.docbook:2256 +msgid "" +"Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since " +"tags in the API to determine the minimum required version." msgstr "" +"Gtkdoc-depscan - ett verktyg (del av gtk-doc) för att kontrollera använda " +"API mot since-taggar i API:t för att avgöra minsta version som krävs." -#: C/gtk-doc-manual.xml:12(releaseinfo) +#. (itstool) path: appendixinfo/releaseinfo +#: C/index.docbook:12 C/fdl-appendix.xml:12 msgid "Version 1.1, March 2000" msgstr "Version 1.1, mars 2000" -#: C/gtk-doc-manual.xml:16(year) -msgid "2000" -msgstr "2000" +#. (itstool) path: appendixinfo/copyright +#: C/index.docbook:15 +msgid "2000Free Software Foundation, Inc." +msgstr "2000Free Software Foundation, Inc." -#: C/gtk-doc-manual.xml:16(holder) -msgid "Free Software Foundation, Inc." -msgstr "Free Software Foundation, Inc." +#. (itstool) path: para/address +#: C/index.docbook:20 +#, no-wrap +msgid "" +"Free Software Foundation, Inc. 51 Franklin Street, \n" +" Suite 330, Boston, MA \n" +" 02110-1301 USA" +msgstr "" +"Free Software Foundation, Inc. 51 Franklin Street, \n" +" Suite 330, Boston, MA \n" +" 02110-1301 USA" -#: C/gtk-doc-manual.xml:19(para) -msgid "
Free Software Foundation, Inc. 51 Franklin Street, Suite 330, Boston, MA02110-1301USA
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed." -msgstr "
Free Software Foundation, Inc. 51 Franklin Street, Suite 330, Boston, MA02110-1301USA
. Var och en äger kopiera och sprida ordagranna kopior av detta licensavtal [originalet och denna översättning], men att ändra det är inte tillåtet." +#. (itstool) path: legalnotice/para +#: C/index.docbook:19 C/fdl-appendix.xml:19 +msgid "" +"<_:address-1/> Everyone is permitted to copy and distribute verbatim copies " +"of this license document, but changing it is not allowed." +msgstr "" +"<_:address-1/>. Alla är tillåtna kopiera och distribuera ordagranna kopior " +"av detta licensdokument, men att ändra det är ej tillåtet." -#: C/gtk-doc-manual.xml:28(title) +#. (itstool) path: appendix/title +#. (itstool) path: para/quote +#: C/index.docbook:28 C/fdl-appendix.xml:28 C/fdl-appendix.xml:642 msgid "GNU Free Documentation License" msgstr "GNU Free Documentation License" -#: C/gtk-doc-manual.xml:31(title) +#. (itstool) path: sect1/title +#: C/index.docbook:31 C/fdl-appendix.xml:31 msgid "0. PREAMBLE" msgstr "0. BAKGRUND" -#: C/gtk-doc-manual.xml:32(para) -msgid "The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others." -msgstr "Syftet med denna licens är att göra en handbok, bok, eller annat praktiskt och användbart dokument fritt som i frihet: att försäkra var och en den faktiska friheten att kopiera och sprida det vidare, med eller utan förändringar, antingen kommersiellt eller ideellt. Sekundärt bevarar denna licens ett sätt för författaren och förläggaren att få ära för deras arbete utan att de anses vara ansvariga för förändringar gjorda av andra." - -#: C/gtk-doc-manual.xml:43(para) -msgid "This License is a kind of copyleft, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software." -msgstr "Denna Licens är en sorts copyleft, vilket betyder att derivativa verk av detta dokument själva måste vara fria på samma sätt. Den kompletterar GNU General Public License, som är en copyleft-licens utformad för fri programvara." - -#: C/gtk-doc-manual.xml:50(para) -msgid "We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference." -msgstr "Vi har utformat denna licens för att den skall användas för handböcker till fri programvara, eftersom fri programvara behöver fri dokumentation: ett fritt program bör ha en handbok som erbjuder samma friheter som programmet gör. Men denna licens är inte begränsad till programvaruhandböcker; den kan användas för vilket textverk som helst oavsett ämne eller huruvida det är en utgiven, tryckt bok. Vi rekommenderar denna licens huvudsakligen för alla verk vars syfte är instruktion eller referens." - -#: C/gtk-doc-manual.xml:62(title) +#. (itstool) path: sect1/para +#: C/index.docbook:32 +msgid "" +"The purpose of this License is to make a manual, textbook, or other written " +"document free in the sense of freedom: to assure everyone the " +"effective freedom to copy and redistribute it, with or without modifying it, " +"either commercially or noncommercially. Secondarily, this License preserves " +"for the author and publisher a way to get credit for their work, while not " +"being considered responsible for modifications made by others." +msgstr "" +"Syftet med denna licens är att göra en handbok, bok, eller annat praktiskt " +"och användbart dokument fritt som i frihet: att försäkra var " +"och en den faktiska friheten att kopiera och sprida det vidare, med eller " +"utan förändringar, antingen kommersiellt eller ideellt. Sekundärt bevarar " +"denna licens ett sätt för författaren och förläggaren att få ära för deras " +"arbete utan att de anses vara ansvariga för förändringar gjorda av andra." + +#. (itstool) path: sect1/para +#: C/index.docbook:43 +msgid "" +"This License is a kind of copyleft, which means that " +"derivative works of the document must themselves be free in the same sense. " +"It complements the GNU General Public License, which is a copyleft license " +"designed for free software." +msgstr "" +"Denna Licens är en sorts copyleft, vilket betyder att " +"derivativa verk av detta dokument själva måste vara fria på samma sätt. Den " +"kompletterar GNU General Public License, som är en copyleft-licens utformad " +"för fri programvara." + +#. (itstool) path: sect1/para +#: C/index.docbook:50 C/fdl-appendix.xml:50 +msgid "" +"We have designed this License in order to use it for manuals for free " +"software, because free software needs free documentation: a free program " +"should come with manuals providing the same freedoms that the software does. " +"But this License is not limited to software manuals; it can be used for any " +"textual work, regardless of subject matter or whether it is published as a " +"printed book. We recommend this License principally for works whose purpose " +"is instruction or reference." +msgstr "" +"Vi har utformat denna licens för att den skall användas för handböcker till " +"fri programvara, eftersom fri programvara behöver fri dokumentation: ett " +"fritt program bör ha en handbok som erbjuder samma friheter som programmet " +"gör. Men denna licens är inte begränsad till programvaruhandböcker; den kan " +"användas för vilket textverk som helst oavsett ämne eller huruvida det är en " +"utgiven, tryckt bok. Vi rekommenderar denna licens huvudsakligen för alla " +"verk vars syfte är instruktion eller referens." + +#. (itstool) path: sect1/title +#: C/index.docbook:62 C/fdl-appendix.xml:62 msgid "1. APPLICABILITY AND DEFINITIONS" -msgstr "TILLÄMPNINGSOMRÅDE OCH DEFINITIONER" - -#: C/gtk-doc-manual.xml:63(para) -msgid "This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The Document, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as you." -msgstr "Denna licens [det engelska originalet] gäller för varje handbok eller annat verk, oavsett uttrycksform, som innehåller ett meddelande där upphovsrättsinnehavaren stadgat att verket kan spridas enligt villkoren i GNU Free Documentation License. Ett sådant meddelande ger en internationell frihet utan krav på ersättning och utan tidsbegränsning att använda verket under villkoren i denna licens [det engelska originalet]. Dokument nedan syftar på godtycklig handbok eller verk. Var och en är licenstagare och benämns som du." - -#: C/gtk-doc-manual.xml:72(para) -msgid "A Modified Version of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language." -msgstr "En förändrad version av dokumentet avser varje verk som innehåller dokumentet eller en del av det, antingen ordagranna kopior, eller med ändringar och/eller översatt till ett annat språk." +msgstr "1. TILLÄMPNINGSOMRÅDE OCH DEFINITIONER" -#: C/gtk-doc-manual.xml:79(para) -msgid "A Secondary Section is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them." -msgstr "Ett sekundärt avsnitt är en märkt bilaga eller förord till dokumentet som exklusivt behandlar förhållandet mellan dokumentets förläggare eller författare och dokumentets huvudsakliga ämne (eller till relaterade ämnen) och som inte innehåller något som direkt faller under det huvudsakliga ämnet. (Således, om dokumentet delvis är en lärobok i matematik så får ett sekundärt avsnitt inte förklara någon matematik.) Förhållandet kan vara en historisk koppling till ämnet eller något relaterat, eller en juridisk, kommersiell, filosofisk, etisk eller politisk ställning till det." - -#: C/gtk-doc-manual.xml:94(para) -msgid "The Invariant Sections are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License." -msgstr "De oföränderliga avsnitten är sekundära avsnitt vars titlar är angivna som oföränderliga avsnitt i meddelandet som stadgar att dokumentet är utgivet under denna licens [det engelska originalet]." - -#: C/gtk-doc-manual.xml:103(para) -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 that the Document is released under this License." -msgstr "Omslagstexterna är speciella korta ordföljder som är listade som framsidestexter eller baksidestexter i meddelandet som stadgar att dokumentet är utgivet under denna licens [det engelska originalet]." - -#: C/gtk-doc-manual.xml:111(para) -msgid "A Transparent copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not Transparent is called Opaque." -msgstr "En transparent kopia av dokumentet är en maskinläsbar kopia, representerad i ett format vars specifikation finns tillgänglig för allmänheten, som lämpar sig för att revidera dokumentet på ett enkelt sätt med generella textredigeringsprogram eller (för pixelbaserade bilder) generella grafikprogram eller (för ritningar) något väl tillgängligt ritprogram, och som är passande som indata till textfomaterare eller för automatisk konvertering till en mängd format som passar som indata till textformaterare. En kopia i ett för övrigt transparent filformat vars markeringar, eller avsaknad av markeringar, har ordnats för att hindra eller motverka att vidare förändring vidtas av läsare är inte transparent. Ett bildformat är inte transparent om det används för någon betydande del text. En kopia som inte är transparent kallas opak." - -#: C/gtk-doc-manual.xml:128(para) -msgid "Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only." -msgstr "Exempel på passande format för transparenta kopior innefattar ren ASCII utan markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript eller PDF utformat för mänsklig förändring. Exempel på transparenta bildformat innefattar PNG, XCF och JPG. Opaka format innefattar leverantörsspecifika format som bara kan läsas och editeras med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/eller verktyg för behandling inte finns allmänt tillgängliga, och den maskingenererade HTML, PostScript eller PDF som produceras av vissa ordbehandlare enbart avsett som utdata." - -#: C/gtk-doc-manual.xml:141(para) -msgid "The Title Page means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, Title Page means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text." -msgstr "Titelsidan innebär, för en tryckt bok, titelsidan själv, och sådana därpå följande sidor som krävs för att göra det material som enligt denna licens skall synas på titelsidan läsbart. För verk i sådana format som inte har någon egentlig titelsida, avses med titelsida den text som är närmast den mest framstående förekomsten av verkets titel, föregående den huvudsakliga textmassan." +#. (itstool) path: sect1/para +#: C/index.docbook:63 +msgid "" +"This License applies to any manual or other work that contains a notice " +"placed by the copyright holder saying it can be distributed under the terms " +"of this License. The Document, below, refers to any such " +"manual or work. Any member of the public is a licensee, and is addressed as " +"you." +msgstr "" +"Denna licens [det engelska originalet] gäller för varje handbok eller annat " +"verk, oavsett uttrycksform, som innehåller ett meddelande där " +"upphovsrättsinnehavaren stadgat att verket kan spridas enligt villkoren i " +"GNU Free Documentation License. Ett sådant meddelande ger en internationell " +"frihet utan krav på ersättning och utan tidsbegränsning att använda verket " +"under villkoren i denna licens [det engelska originalet]. Dokument nedan syftar på godtycklig handbok eller verk. Var och en är " +"licenstagare och benämns som du." + +#. (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 " +"modifications and/or translated into another language." +msgstr "" +"En förändrad version av dokumentet avser varje verk som " +"innehåller dokumentet eller en del av det, antingen ordagranna kopior, eller " +"med ändringar och/eller översatt till ett annat språk." -#: C/gtk-doc-manual.xml:153(title) +#. (itstool) path: sect1/para +#: C/index.docbook:79 +msgid "" +"A Secondary Section is a named appendix or a front-matter " +"section of the Document that deals " +"exclusively with the relationship of the publishers or authors of the " +"Document to the Document's overall subject (or to related matters) and " +"contains nothing that could fall directly within that overall subject. (For " +"example, if the Document is in part a textbook of mathematics, a Secondary " +"Section may not explain any mathematics.) The relationship could be a matter " +"of historical connection with the subject or with related matters, or of " +"legal, commercial, philosophical, ethical or political position regarding " +"them." +msgstr "" +"Ett sekundärt avsnitt är en märkt bilaga eller förord till " +"dokumentet som exklusivt behandlar " +"förhållandet mellan dokumentets förläggare eller författare och dokumentets " +"huvudsakliga ämne (eller till relaterade ämnen) och som inte innehåller " +"något som direkt faller under det huvudsakliga ämnet. (Således, om " +"dokumentet delvis är en lärobok i matematik så får ett sekundärt avsnitt " +"inte förklara någon matematik.) Förhållandet kan vara en historisk koppling " +"till ämnet eller något relaterat, eller en juridisk, kommersiell, " +"filosofisk, etisk eller politisk ställning till det." + +#. (itstool) path: sect1/para +#: C/index.docbook:94 +msgid "" +"The Invariant Sections are certain Secondary Sections whose titles are designated, as being " +"those of Invariant Sections, in the notice that says that the Document is released under this License." +msgstr "" +"De oföränderliga avsnitten är sekundära avsnitt vars titlar är angivna som oföränderliga avsnitt " +"i meddelandet som stadgar att dokumentet är utgivet under denna licens [det engelska originalet]." + +#. (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 " +"that the Document is released under " +"this License." +msgstr "" +"Omslagstexterna är speciella korta ordföljder som är listade " +"som framsidestexter eller baksidestexter i meddelandet som stadgar att dokumentet är utgivet under denna licens " +"[det engelska originalet]." + +#. (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 " +"specification is available to the general public, whose contents can be " +"viewed and edited directly and straightforwardly with generic text editors " +"or (for images composed of pixels) generic paint programs or (for drawings) " +"some widely available drawing editor, and that is suitable for input to text " +"formatters or for automatic translation to a variety of formats suitable for " +"input to text formatters. A copy made in an otherwise Transparent file " +"format whose markup has been designed to thwart or discourage subsequent " +"modification by readers is not Transparent. A copy that is not " +"Transparent is called Opaque." +msgstr "" +"En transparent kopia av dokumentet är en maskinläsbar kopia, representerad i ett format " +"vars specifikation finns tillgänglig för allmänheten, som lämpar sig för att " +"revidera dokumentet på ett enkelt sätt med generella textredigeringsprogram " +"eller (för pixelbaserade bilder) generella grafikprogram eller (för " +"ritningar) något väl tillgängligt ritprogram, och som är passande som indata " +"till textformaterare eller för automatisk konvertering till en mängd format " +"som passar som indata till textformaterare. En kopia i ett för övrigt " +"transparent filformat vars markeringar, eller avsaknad av markeringar, har " +"ordnats för att hindra eller motverka att vidare förändring vidtas av läsare " +"är inte transparent. En kopia som inte är transparent kallas " +"opak." + +#. (itstool) path: sect1/para +#: C/index.docbook:128 C/fdl-appendix.xml:128 +msgid "" +"Examples of suitable formats for Transparent copies include plain ASCII " +"without markup, Texinfo input format, LaTeX input format, SGML or XML using " +"a publicly available DTD, and standard-conforming simple HTML designed for " +"human modification. Opaque formats include PostScript, PDF, proprietary " +"formats that can be read and edited only by proprietary word processors, " +"SGML or XML for which the DTD and/or processing tools are not generally " +"available, and the machine-generated HTML produced by some word processors " +"for output purposes only." +msgstr "" +"Exempel på passande format för transparenta kopior innefattar ren ASCII utan " +"markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som " +"använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript " +"eller PDF utformat för mänsklig förändring. Opaka format innefattar " +"Postscript, PDF, leverantörsspecifika format som bara kan läsas och editeras " +"med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/" +"eller verktyg för behandling inte finns allmänt tillgängliga, och den " +"maskingenererade HTML som produceras av vissa ordbehandlare enbart avsett " +"som utdata." + +#. (itstool) path: sect1/para +#: C/index.docbook:141 +msgid "" +"The Title Page means, for a printed book, the title page " +"itself, plus such following pages as are needed to hold, legibly, the " +"material this License requires to appear in the title page. For works in " +"formats which do not have any title page as such, Title Page " +"means the text near the most prominent appearance of the work's title, " +"preceding the beginning of the body of the text." +msgstr "" +"Titelsidan innebär, för en tryckt bok, titelsidan själv, och " +"sådana därpå följande sidor som krävs för att göra det material som enligt " +"denna licens skall synas på titelsidan läsbart. För verk i sådana format som " +"inte har någon egentlig titelsida, avses med titelsida den " +"text som är närmast den mest framstående förekomsten av verkets titel, " +"föregående den huvudsakliga textmassan." + +#. (itstool) path: sect1/title +#: C/index.docbook:153 C/fdl-appendix.xml:153 msgid "2. VERBATIM COPYING" msgstr "2. ORDAGRANN KOPIERING" -#: C/gtk-doc-manual.xml:154(para) -msgid "You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3." -msgstr "Du äger kopiera och sprida dokumentet på valfritt medium, antingen kommersiellt eller ideellt, förutsatt att denna licens [det engelska originalet], upphovsrättsklausul, och meddelandet som stadgar att GNU Free Documentation License gäller för dokumentet finns med på alla kopior, och att du inte lägger till några som helst andra villkor än de som ingår i denna licens. Du äger inte vidta tekniska åtgärder för att begränsa eller kontrollera läsande eller vidare kopiering av de kopior du skapar eller sprider. Dock äger du ta emot kompensation i utbyte mot kopior. Om du sprider tillräckligt många kopior måste du också följa villkoren i paragraf 3." - -#: C/gtk-doc-manual.xml:169(para) -msgid "You may also lend copies, under the same conditions stated above, and you may publicly display copies." -msgstr "Du äger också låna ut kopior, under samma villkor som ovan, och du äger visa kopior offentligt." +#. (itstool) path: sect1/para +#: C/index.docbook:154 +msgid "" +"You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that " +"this License, the copyright notices, and the license notice saying this " +"License applies to the Document are reproduced in all copies, and that you " +"add no other conditions whatsoever to those of this License. You may not use " +"technical measures to obstruct or control the reading or further copying of " +"the copies you make or distribute. However, you may accept compensation in " +"exchange for copies. If you distribute a large enough number of copies you " +"must also follow the conditions in section 3." +msgstr "" +"Du äger kopiera och sprida dokumentet " +"på valfritt medium, antingen kommersiellt eller ideellt, förutsatt att denna " +"licens [det engelska originalet], upphovsrättsklausul, och meddelandet som " +"stadgar att GNU Free Documentation License gäller för dokumentet finns med " +"på alla kopior, och att du inte lägger till några som helst andra villkor än " +"de som ingår i denna licens. Du äger inte vidta tekniska åtgärder för att " +"begränsa eller kontrollera läsande eller vidare kopiering av de kopior du " +"skapar eller sprider. Dock äger du ta emot kompensation i utbyte mot kopior. " +"Om du sprider tillräckligt många kopior måste du också följa villkoren i " +"paragraf 3." + +#. (itstool) path: sect1/para +#: C/index.docbook:169 C/fdl-appendix.xml:169 +msgid "" +"You may also lend copies, under the same conditions stated above, and you " +"may publicly display copies." +msgstr "" +"Du äger också låna ut kopior, under samma villkor som ovan, och du äger visa " +"kopior offentligt." -#: C/gtk-doc-manual.xml:176(title) +#. (itstool) path: sect1/title +#: C/index.docbook:176 C/fdl-appendix.xml:176 msgid "3. COPYING IN QUANTITY" msgstr "3. OMFATTANDE KOPIERING" -#: C/gtk-doc-manual.xml:177(para) -msgid "If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects." -msgstr "Om du publicerar tryckta kopior (eller kopior i medier som normalt har tryckta omslag) av dokumentet, i en upplaga överstigande 100 exemplar, och dokumentets licensmeddelande kräver omslagstexter, så måste du förse kopiorna med omslag som, klart och tydligt, visar alla omslagstexter: framsidestexter på framsidan och baksidestexter på baksidan. Båda omslagen måste klart och tydligt identifiera dig som utgivare av dessa kopior. Framsidan måste presentera dokumentets hela titel, med alla ord i titeln lika framträdande och synliga. Du äger lägga till ytterligare stoff på omslagen. Kopiering med förändringar gjorda bara på omslaget, så länge som de bevarar dokumentets titel och i övrigt uppfyller dessa krav kan anses vara ordagrann kopiering i andra avseenden." - -#: C/gtk-doc-manual.xml:195(para) -msgid "If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages." -msgstr "Om de obligatoriska texterna för något omslag är för omfattande för att rymmas i läsbart skick skall du placera de första (så många som får plats) på det egentliga omslaget, och fortsätta med resten på de direkt intilliggande sidorna." - -#: C/gtk-doc-manual.xml:202(para) -msgid "If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public." -msgstr "Om du publicerar opaka kopior av dokumentet i upplagor om mer än 100, måste du antingen bifoga en maskinläsbar transparent kopia med varje opak kopia, eller ange i eller med varje opak kopia en nätverksadress som är tillgänglig för den allmänna nätverksanvändande massan där man, med öppet standardiserade protokoll, kan ladda ner en komplett transparent kopia av dokumentet, utan extra material. Om du väljer det senare alternativet, måste du vidta skäliga åtgärder, när du börjar sprida opaka kopior i kvantitet, för att denna transparenta kopia skall förbli tillgänglig på angivna platsen till åtminstone ett år efter den sista gången du spred en opak kopia (direkt eller via ombud eller återförsäljare) av den utgåvan till allmänheten." - -#: C/gtk-doc-manual.xml:222(para) -msgid "It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document." -msgstr "Det är önskvärt, men inte ett krav, att du kontaktar författarna till dokumentet i god tid innan du sprider något större antal kopior, för att ge dem en chans att förse dig med en uppdaterad version av dokumentet." +#. (itstool) path: sect1/para +#: C/index.docbook:177 +msgid "" +"If you publish printed copies of the Document numbering more than 100, and the Document's license " +"notice requires Cover Texts, you " +"must enclose the copies in covers that carry, clearly and legibly, all these " +"Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on " +"the back cover. Both covers must also clearly and legibly identify you as " +"the publisher of these copies. The front cover must present the full title " +"with all words of the title equally prominent and visible. You may add other " +"material on the covers in addition. Copying with changes limited to the " +"covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as " +"verbatim copying in other respects." +msgstr "" +"Om du publicerar tryckta kopior (eller kopior i medier som normalt har " +"tryckta omslag) av dokumentet, i en " +"upplaga överstigande 100 exemplar, och dokumentets licensmeddelande kräver " +"omslagstexter, så måste du förse " +"kopiorna med omslag som, klart och tydligt, visar alla omslagstexter: " +"framsidestexter på framsidan och baksidestexter på baksidan. Båda omslagen " +"måste klart och tydligt identifiera dig som utgivare av dessa kopior. " +"Framsidan måste presentera dokumentets hela titel, med alla ord i titeln " +"lika framträdande och synliga. Du äger lägga till ytterligare stoff på " +"omslagen. Kopiering med förändringar gjorda bara på omslaget, så länge som " +"de bevarar dokumentets titel och i " +"övrigt uppfyller dessa krav kan anses vara ordagrann kopiering i andra " +"avseenden." + +#. (itstool) path: sect1/para +#: C/index.docbook:195 C/fdl-appendix.xml:195 +msgid "" +"If the required texts for either cover are too voluminous to fit legibly, " +"you should put the first ones listed (as many as fit reasonably) on the " +"actual cover, and continue the rest onto adjacent pages." +msgstr "" +"Om de obligatoriska texterna för något omslag är för omfattande för att " +"rymmas i läsbart skick skall du placera de första (så många som får plats) " +"på det egentliga omslaget, och fortsätta med resten på de direkt " +"intilliggande sidorna." -#: C/gtk-doc-manual.xml:231(title) +#. (itstool) path: sect1/para +#: C/index.docbook:202 +msgid "" +"If you publish or distribute Opaque " +"copies of the Document numbering more " +"than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state " +"in or with each Opaque copy a publicly-accessible computer-network location " +"containing a complete Transparent copy of the Document, free of added " +"material, which the general network-using public has access to download " +"anonymously at no charge using public-standard network protocols. If you use " +"the latter option, you must take reasonably prudent steps, when you begin " +"distribution of Opaque copies in quantity, to ensure that this Transparent " +"copy will remain thus accessible at the stated location until at least one " +"year after the last time you distribute an Opaque copy (directly or through " +"your agents or retailers) of that edition to the public." +msgstr "" +"Om du publicerar opaka kopior av " +"dokumentet i upplagor om mer än 100, " +"måste du antingen bifoga en maskinläsbar transparent kopia med varje opak kopia, eller ange i eller med " +"varje opak kopia en nätverksadress som är tillgänglig för den allmänna " +"nätverksanvändande massan där man, med öppet standardiserade protokoll, " +"anonymt och utan kostnad kan ladda ner en komplett transparent kopia av " +"dokumentet, utan extra material. Om du väljer det senare alternativet, måste " +"du vidta skäliga åtgärder, när du börjar sprida opaka kopior i kvantitet, " +"för att denna transparenta kopia skall förbli tillgänglig på angivna platsen " +"till åtminstone ett år efter den sista gången du spred en opak kopia (direkt " +"eller via ombud eller återförsäljare) av den utgåvan till allmänheten." + +#. (itstool) path: sect1/para +#: C/index.docbook:222 +msgid "" +"It is requested, but not required, that you contact the authors of the Document well before redistributing any " +"large number of copies, to give them a chance to provide you with an updated " +"version of the Document." +msgstr "" +"Det är önskvärt, men inte ett krav, att du kontaktar författarna till dokumentet i god tid innan du sprider något " +"större antal kopior, för att ge dem en chans att förse dig med en uppdaterad " +"version av dokumentet." + +#. (itstool) path: sect1/title +#: C/index.docbook:231 C/fdl-appendix.xml:231 msgid "4. MODIFICATIONS" msgstr "4. FÖRÄNDRINGAR" -#: C/gtk-doc-manual.xml:232(para) -msgid "You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:" -msgstr "Du äger kopiera och sprida en förändrad version av dokumentet under de villkor som beskrivs i paragraf 2 och 3 av GNU Free Documentation License, förutsatt att du släpper den förändrade versionen under exakt denna licens, och att den förändrade versionen antar dokumentets roll, och således medger spridning och förändring av den förändrade versionen till envar som erhåller en kopia av den. Utöver detta måste du göra följande med den ändrade versionen:" - -#: C/gtk-doc-manual.xml:248(title) +#. (itstool) path: sect1/para +#: C/index.docbook:232 +msgid "" +"You may copy and distribute a Modified " +"Version of the Document under " +"the conditions of sections 2 and 3 above, provided that you release the " +"Modified Version under precisely this License, with the Modified Version " +"filling the role of the Document, thus licensing distribution and " +"modification of the Modified Version to whoever possesses a copy of it. In " +"addition, you must do these things in the Modified Version:" +msgstr "" +"Du äger kopiera och sprida en förändrad " +"version av dokumentet under de " +"villkor som beskrivs i paragraf 2 och " +"3 av GNU Free Documentation License, " +"förutsatt att du släpper den förändrade versionen under exakt denna licens, " +"och att den förändrade versionen antar dokumentets roll, och således medger " +"spridning och förändring av den förändrade versionen till envar som erhåller " +"en kopia av den. Utöver detta måste du göra följande med den ändrade " +"versionen:" + +#. (itstool) path: formalpara/title +#: C/index.docbook:248 C/fdl-appendix.xml:248 msgid "A" msgstr "A" -#: C/gtk-doc-manual.xml:249(para) -msgid "Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission." -msgstr "På titelsidan (och omslagen om det finns några) använda en titel skild från den som [original]dokumentet har, och skild från tidigare versioners titel (som skall, om det finns några, finnas listade i historikavsnittet i dokumentet). Du äger använda samma titel som det föregående dokumentet om den ursprungliga utgivaren ger sitt tillstånd." - -#: C/gtk-doc-manual.xml:264(title) +#. (itstool) path: formalpara/para +#: C/index.docbook:249 +msgid "" +"Use in the Title Page (and on the " +"covers, if any) a title distinct from that of the Document, and from those of previous versions (which " +"should, if there were any, be listed in the History section of the " +"Document). You may use the same title as a previous version if the original " +"publisher of that version gives permission." +msgstr "" +"På titelsidan (och omslagen om det " +"finns några) använda en titel skild från den som [original]dokumentet har, och skild från tidigare versioners " +"titel (som skall, om det finns några, finnas listade i historikavsnittet i " +"dokumentet). Du äger använda samma titel som det föregående dokumentet om " +"den ursprungliga utgivaren ger sitt tillstånd." + +#. (itstool) path: formalpara/title +#: C/index.docbook:264 C/fdl-appendix.xml:264 msgid "B" msgstr "B" -#: C/gtk-doc-manual.xml:265(para) -msgid "List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five)." -msgstr "Lista på titelsidan, som författare, en eller flera personer eller juridiska personer som ansvarat för förändringarna i den förändrade versionen, tillsammans med minst fem av de huvudsakliga författarna av dokumentet (alla dess huvudsakliga författare, om det har mindre än fem)." - -#: C/gtk-doc-manual.xml:279(title) +#. (itstool) path: formalpara/para +#: C/index.docbook:265 +msgid "" +"List on the Title Page, as authors, " +"one or more persons or entities responsible for authorship of the " +"modifications in the Modified Version, " +"together with at least five of the principal authors of the Document (all of its principal authors, if it has " +"less than five)." +msgstr "" +"Lista på titelsidan, som författare, " +"en eller flera personer eller juridiska personer som ansvarat för " +"förändringarna i den förändrade versionen, tillsammans med minst fem av de huvudsakliga författarna av dokumentet (alla dess huvudsakliga " +"författare, om det har mindre än fem)." + +#. (itstool) path: formalpara/title +#: C/index.docbook:279 C/fdl-appendix.xml:279 msgid "C" msgstr "C" -#: C/gtk-doc-manual.xml:280(para) -msgid "State on the Title Page the name of the publisher of the Modified Version, as the publisher." -msgstr "Ange namnet på utgivaren av den förändrade versionen, som utgivare, på titelsidan." +#. (itstool) path: formalpara/para +#: C/index.docbook:280 +msgid "" +"State on the Title Page the name of " +"the publisher of the Modified Version, " +"as the publisher." +msgstr "" +"Ange namnet på utgivaren av den förändrade " +"versionen, som utgivare, på titelsidan." -#: C/gtk-doc-manual.xml:291(title) +#. (itstool) path: formalpara/title +#: C/index.docbook:291 C/fdl-appendix.xml:291 msgid "D" msgstr "D" -#: C/gtk-doc-manual.xml:292(para) -msgid "Preserve all the copyright notices of the Document." -msgstr "Bibehålla dokumentets alla upphovsrättsklausuler." +#. (itstool) path: formalpara/para +#: C/index.docbook:292 +msgid "" +"Preserve all the copyright notices of the Document." +msgstr "" +"Bibehålla dokumentets alla " +"upphovsrättsklausuler." -#: C/gtk-doc-manual.xml:301(title) +#. (itstool) path: formalpara/title +#: C/index.docbook:301 C/fdl-appendix.xml:301 msgid "E" msgstr "E" -#: C/gtk-doc-manual.xml:302(para) -msgid "Add an appropriate copyright notice for your modifications adjacent to the other copyright notices." -msgstr "Lägga till en upphovsrättsklausul för dina förändringar angränsande till de andra upphovsrättsklausulerna." +#. (itstool) path: formalpara/para +#: C/index.docbook:302 C/fdl-appendix.xml:302 +msgid "" +"Add an appropriate copyright notice for your modifications adjacent to the " +"other copyright notices." +msgstr "" +"Lägga till en upphovsrättsklausul för dina förändringar angränsande till de " +"andra upphovsrättsklausulerna." -#: C/gtk-doc-manual.xml:311(title) +#. (itstool) path: formalpara/title +#: C/index.docbook:311 C/fdl-appendix.xml:311 msgid "F" msgstr "F" -#: C/gtk-doc-manual.xml:312(para) -msgid "Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below." -msgstr "Direkt efter upphovsrättsklausulerna innefatta ett meddelande som ger allmänheten tillstånd att använda den förändrade versionen under villkoren i denna licens [det engelska originalet] i den form som visas i Tillägg nedan." - -#: C/gtk-doc-manual.xml:324(title) +#. (itstool) path: formalpara/para +#: C/index.docbook:312 +msgid "" +"Include, immediately after the copyright notices, a license notice giving " +"the public permission to use the Modified " +"Version under the terms of this License, in the form shown in the " +"Addendum below." +msgstr "" +"Direkt efter upphovsrättsklausulerna innefatta ett meddelande som ger " +"allmänheten tillstånd att använda den förändrade versionen under villkoren i denna licens [det engelska " +"originalet] i den form som visas i Tillägg nedan." + +#. (itstool) path: formalpara/title +#: C/index.docbook:324 C/fdl-appendix.xml:324 msgid "G" msgstr "G" -#: C/gtk-doc-manual.xml:325(para) -msgid "Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice." -msgstr "I meddelandet om licensen bevara den fullständiga listan över oföränderliga avsnitt och obligatoriska omslagstexter som finns i dokumentets meddelande om licensen." - -#: C/gtk-doc-manual.xml:337(title) +#. (itstool) path: formalpara/para +#: C/index.docbook:325 +msgid "" +"Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice." +msgstr "" +"I meddelandet om licensen bevara den fullständiga listan över oföränderliga avsnitt och obligatoriska omslagstexter som finns i dokumentets meddelande om licensen." + +#. (itstool) path: formalpara/title +#: C/index.docbook:337 C/fdl-appendix.xml:337 msgid "H" msgstr "H" -#: C/gtk-doc-manual.xml:338(para) +#. (itstool) path: formalpara/para +#: C/index.docbook:338 C/fdl-appendix.xml:338 msgid "Include an unaltered copy of this License." -msgstr "Inkludera en oförändrad kopia av denna licens [Det är den engelska originalversionen som avses]." +msgstr "" +"Inkludera en oförändrad kopia av denna licens [Det är den engelska " +"originalversionen som avses]." -#: C/gtk-doc-manual.xml:346(title) +#. (itstool) path: formalpara/title +#: C/index.docbook:346 C/fdl-appendix.xml:346 msgid "I" msgstr "I" -#: C/gtk-doc-manual.xml:347(para) -msgid "Preserve the section entitled History, and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled History in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence." -msgstr "Bevara avsnittet med titeln historik (History), bevara dess titel och lägg i avsnittet till en post med åtminstone titeln, året, nya författare och utgivaren av den förändrade versionen så som angivet på titelsidan. Om det inte finns något avsnitt med titeln historik (History) i dokumentet så skapa en med titeln, året, författare och utgivaren av dokumentet så som det står på [original]dokumentets titelsida. Lägg sedan till en post som beskriver den förändrade versionen så som beskrivits ovan." - -#: C/gtk-doc-manual.xml:365(title) +#. (itstool) path: formalpara/para +#: C/index.docbook:347 +msgid "" +"Preserve the section entitled History, and its title, and add " +"to it an item stating at least the title, year, new authors, and publisher " +"of the Modified Version as given on " +"the Title Page. If there is no " +"section entitled History in the Document, create one stating the title, year, authors, and " +"publisher of the Document as given on its Title Page, then add an item " +"describing the Modified Version as stated in the previous sentence." +msgstr "" +"Bevara avsnittet med titeln historik (History), bevara dess " +"titel och lägg i avsnittet till en post med åtminstone titeln, året, nya " +"författare och utgivaren av den förändrade " +"versionen så som angivet på titelsidan. Om det inte finns något avsnitt med titeln " +"historik (History) i dokumentet så skapa en med titeln, året, författare och utgivaren " +"av dokumentet så som det står på [original]dokumentets titelsida. Lägg sedan " +"till en post som beskriver den förändrade versionen så som beskrivits ovan." + +#. (itstool) path: formalpara/title +#: C/index.docbook:365 C/fdl-appendix.xml:365 msgid "J" msgstr "J" -#: C/gtk-doc-manual.xml:366(para) -msgid "Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the History section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission." -msgstr "Bevara den nätverksadress, om det finns någon, angiven i dokumentet till den allmänt tillgängliga transparenta kopian av dokumentet, och likaså nätverksadresserna till de föregående versioner som dokumentet baseras på. Dessa får placeras i avsnittet historik (History). Du äger utelämna en nätverksadress för ett verk som är publicerat mer än fyra år före dokumentet självt, eller om den ursprunglige utgivaren vars verk nätverksadressen hänvisar till ger sitt tillstånd." - -#: C/gtk-doc-manual.xml:383(title) +#. (itstool) path: formalpara/para +#: C/index.docbook:366 +msgid "" +"Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the " +"network locations given in the Document for previous versions it was based " +"on. These may be placed in the History section. You may omit " +"a network location for a work that was published at least four years before " +"the Document itself, or if the original publisher of the version it refers " +"to gives permission." +msgstr "" +"Bevara den nätverksadress, om det finns någon, angiven i dokumentet till den allmänt tillgängliga transparenta kopian av dokumentet, och likaså " +"nätverksadresserna till de föregående versioner som dokumentet baseras på. " +"Dessa får placeras i avsnittet historik (History). Du äger " +"utelämna en nätverksadress för ett verk som är publicerat mer än fyra år " +"före dokumentet självt, eller om den ursprunglige utgivaren vars verk " +"nätverksadressen hänvisar till ger sitt tillstånd." + +#. (itstool) path: formalpara/title +#: C/index.docbook:383 C/fdl-appendix.xml:383 msgid "K" msgstr "K" -#: C/gtk-doc-manual.xml:384(para) -msgid "In any section entitled Acknowledgements or Dedications, preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein." -msgstr "För alla avsnitt med titlarna tillkännagivanden (Acknowledgements) eller dedikationer (Dedications), bevara titeln på avsnittet, och bevara allt innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda av varje bidragare." - -#: C/gtk-doc-manual.xml:396(title) +#. (itstool) path: formalpara/para +#: C/index.docbook:384 +msgid "" +"In any section entitled Acknowledgements or " +"Dedications, preserve the section's title, and preserve in " +"the section all the substance and tone of each of the contributor " +"acknowledgements and/or dedications given therein." +msgstr "" +"För alla avsnitt med titlarna tillkännagivanden " +"(Acknowledgements) eller dedikationer (Dedications), bevara " +"titeln på avsnittet, och bevara allt innehåll och prägel på alla " +"tillkännagivanden och/eller dedikationer gjorda av varje bidragsgivare." + +#. (itstool) path: formalpara/title +#: C/index.docbook:396 C/fdl-appendix.xml:396 msgid "L" msgstr "L" -#: C/gtk-doc-manual.xml:397(para) -msgid "Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles." -msgstr "Bevara alla oföränderliga avsnitt i dokumentet oförändrade till text och titel. Avsnittsnummer eller motsvarande anses inte tillhöra avsnittets titel." +#. (itstool) path: formalpara/para +#: C/index.docbook:397 +msgid "" +"Preserve all the Invariant Sections " +"of the Document, unaltered in their " +"text and in their titles. Section numbers or the equivalent are not " +"considered part of the section titles." +msgstr "" +"Bevara alla oföränderliga avsnitt i " +"dokumentet oförändrade till text och " +"titel. Avsnittsnummer eller motsvarande anses inte tillhöra avsnittets titel." -#: C/gtk-doc-manual.xml:409(title) +#. (itstool) path: formalpara/title +#: C/index.docbook:409 C/fdl-appendix.xml:409 msgid "M" msgstr "M" -#: C/gtk-doc-manual.xml:410(para) -msgid "Delete any section entitled Endorsements. Such a section may not be included in the Modified Version." -msgstr "Radera varje avsnitt med titeln endossering (Endorsements). Ett sådant avsnitt får inte inkluderas i en förändrad version." +#. (itstool) path: formalpara/para +#: C/index.docbook:410 +msgid "" +"Delete any section entitled Endorsements. Such a section may " +"not be included in the Modified Version." +msgstr "" +"Radera varje avsnitt med titeln endossering (Endorsements). " +"Ett sådant avsnitt får inte inkluderas i en förändrad version." -#: C/gtk-doc-manual.xml:421(title) +#. (itstool) path: formalpara/title +#: C/index.docbook:421 C/fdl-appendix.xml:421 msgid "N" msgstr "N" -#: C/gtk-doc-manual.xml:422(para) -msgid "Do not retitle any existing section as Endorsements or to conflict in title with any Invariant Section." -msgstr "Inte byta titel på något existerande avsnitt så att det blir endossering (Endorsements) eller så att titeln kan förväxlas med något oföränderligt avsnitt." - -#: C/gtk-doc-manual.xml:432(para) -msgid "If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles." -msgstr "Om den förändrade versionen innehåller nya framsidestexter eller bilagor som är att anses som sekundära avsnitt och inte innehåller något material kopierat från dokumentet, så äger du, om du vill, benämna några eller samtliga av dessa som oföränderliga. För att göra detta, lägg deras titlar till listan över oföränderliga avsnitt i den förändrade versionens licensmeddelande. Dessa titlar måste vara skilda från alla andra avsnitts titlar." - -#: C/gtk-doc-manual.xml:444(para) -msgid "You may add a section entitled Endorsements, provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard." -msgstr "Du äger lägga till ett avsnitt med titeln endossering (Endorsements), förutsatt att det inte innehåller något annat än endosseringar för din förändrade version från olika aktörer -- till exempel, meddelanden om utförd korrekturläsning eller att texten har godkänts av en organisation som en officiell definition av en standard." - -#: C/gtk-doc-manual.xml:453(para) -msgid "You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one." -msgstr "Du äger lägga till ett textavsnitt på upp till fem ord som framsidestext, och ett textavsnitt på upp till 25 ord som baksidestext i listan över omslagstexter i den förändrade versionen. Bara ett textavsnitt med framsidestexter och ett med baksidestexter får läggas till av (eller genom försorg av) en enda juridisk person. Om dokumentet redan innehåller en omlagstext för något av omslagen, tidigare tillagd av dig eller genom försorg av samma juridiska person som du företräder, äger du inte lägga till en till, men du äger ändra den gamla med tillstånd från den tidigare utgivaren som lade till den förra." - -#: C/gtk-doc-manual.xml:470(para) -msgid "The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version ." -msgstr "Författaren (författarna) och utgivaren (utgivarna) av dokumentet ger inte via denna licens sitt tillstånd att använda sina namn för publicitet eller för att lägga till eller antyda endossering av någon förändrad version." +#. (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 " +"Section." +msgstr "" +"Inte byta titel på något existerande avsnitt så att det blir " +"endossering (Endorsements) eller så att titeln kan förväxlas " +"med något oföränderligt avsnitt." -#: C/gtk-doc-manual.xml:480(title) +#. (itstool) path: sect1/para +#: C/index.docbook:432 +msgid "" +"If the Modified Version includes new " +"front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from " +"the Document, you may at your option designate some or all of these sections " +"as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's " +"license notice. These titles must be distinct from any other section titles." +msgstr "" +"Om den förändrade versionen innehåller " +"nya framsidestexter eller bilagor som är att anses som sekundära avsnitt och inte innehåller något material " +"kopierat från dokumentet, så äger du, om du vill, benämna några eller " +"samtliga av dessa som oföränderliga. För att göra detta, lägg deras titlar " +"till listan över oföränderliga avsnitt i den förändrade versionens licensmeddelande. Dessa titlar måste vara " +"skilda från alla andra avsnitts titlar." + +#. (itstool) path: sect1/para +#: C/index.docbook:444 +msgid "" +"You may add a section entitled Endorsements, provided it " +"contains nothing but endorsements of your Modified Version by various parties--for example, statements of " +"peer review or that the text has been approved by an organization as the " +"authoritative definition of a standard." +msgstr "" +"Du äger lägga till ett avsnitt med titeln endossering " +"(Endorsements), förutsatt att det inte innehåller något annat än " +"endosseringar för din förändrade version från olika aktörer -- till exempel, meddelanden om utförd " +"korrekturläsning eller att texten har godkänts av en organisation som en " +"officiell definition av en standard." + +#. (itstool) path: sect1/para +#: C/index.docbook:453 +msgid "" +"You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list " +"of Cover Texts in the Modified Version. Only one passage of Front-Cover " +"Text and one of Back-Cover Text may be added by (or through arrangements " +"made by) any one entity. If the Document already includes a cover text for the same cover, previously added by " +"you or by arrangement made by the same entity you are acting on behalf of, " +"you may not add another; but you may replace the old one, on explicit " +"permission from the previous publisher that added the old one." +msgstr "" +"Du äger lägga till ett textavsnitt på upp till fem ord som framsidestext, och ett textavsnitt på upp till 25 " +"ord som baksidestext i listan över " +"omslagstexter i den förändrade versionen. Bara ett textavsnitt med " +"framsidestexter och ett med baksidestexter får läggas till av (eller genom " +"försorg av) en enda juridisk person. Om dokumentet redan innehåller en omslagstext för något av omslagen, " +"tidigare tillagd av dig eller genom försorg av samma juridiska person som du " +"företräder, äger du inte lägga till en till, men du äger ändra den gamla med " +"tillstånd från den tidigare utgivaren som lade till den förra." + +#. (itstool) path: sect1/para +#: C/index.docbook:470 +msgid "" +"The author(s) and publisher(s) of the Document do not by this License give permission to use their names " +"for publicity for or to assert or imply endorsement of any Modified Version ." +msgstr "" +"Författaren (författarna) och utgivaren (utgivarna) av dokumentet ger inte via denna licens sitt tillstånd att " +"använda sina namn för publicitet eller för att lägga till eller antyda " +"endossering av någon förändrad version." + +#. (itstool) path: sect1/title +#: C/index.docbook:480 C/fdl-appendix.xml:480 msgid "5. COMBINING DOCUMENTS" msgstr "5. KOMBINERA DOKUMENT" -#: C/gtk-doc-manual.xml:481(para) -msgid "You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice." -msgstr "Du äger kombinera dokumentet med andra dokument som är utgivna under denna licens, under de villkor som definieras i paragraf 4 av GNU Free Documentation License för förändrade versioner, förutsatt att du, i det kombinerade dokumentet, innefattar alla oföränderliga avsnitt från originaldokumenten, omodifierade, och listar dem som oföränderliga avsnitt i ditt kombinerade verk i dess licensklausul, och att du bevarar alla deras garantiavsägelseklausuler." - -#: C/gtk-doc-manual.xml:492(para) -msgid "The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work." -msgstr "Det kombinerade verket behöver bara innehålla en enstaka kopia av denna licens [engelska originalversionen], och flera identiska oföränderliga stycken kan ersättas med en kopia. Om det finns flera oföränderliga stycken med samma namn men olika innehåll, se till att titeln på varje sådant avsnitt är unik genom att i slutet på den, inom parentes, lägga till namnet på den ursprunglige författaren eller utgivaren av det avsnittet om dessa är kända, annars ett unikt nummer. Gör samma justeringar av titlarna i listan över oföränderliga avsnitt i licensklausulen i det kombinerade verket." - -#: C/gtk-doc-manual.xml:505(para) -msgid "In the combination, you must combine any sections entitled History in the various original documents, forming one section entitled History; likewise combine any sections entitled Acknowledgements, and any sections entitled Dedications. You must delete all sections entitled Endorsements." -msgstr "I det kombinerade verket måste du kombinera alla avsnitt med titlarna historik (History) i de ursprungliga dokumenten, till ett avsnitt med titeln historik (History); på samma sätt skall alla avsnitt med titlarna tillkännagivanden (Acknowledgements), alla avsnitt med titlarna dedikationer (Dedications) kombineras. Du måste ta bort alla avsnitt med titlarna endossering (Endorsements)." - -#: C/gtk-doc-manual.xml:516(title) +#. (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 " +"section 4 above for modified versions, " +"provided that you include in the combination all of the Invariant Sections of all of the original documents, " +"unmodified, and list them all as Invariant Sections of your combined work in " +"its license notice." +msgstr "" +"Du äger kombinera dokumentet med andra " +"dokument som är utgivna under denna licens, under de villkor som definieras " +"i paragraf 4 av GNU Free Documentation " +"License för förändrade versioner, förutsatt att du, i det kombinerade " +"dokumentet, innefattar alla oföränderliga " +"avsnitt från originaldokumenten, omodifierade, och listar dem som " +"oföränderliga avsnitt i ditt kombinerade verk i dess licensklausul, och att " +"du bevarar alla deras garantiavsägelseklausuler." + +#. (itstool) path: sect1/para +#: C/index.docbook:492 +msgid "" +"The combined work need only contain one copy of this License, and multiple " +"identical Invariant Sections may be " +"replaced with a single copy. If there are multiple Invariant Sections with " +"the same name but different contents, make the title of each such section " +"unique by adding at the end of it, in parentheses, the name of the original " +"author or publisher of that section if known, or else a unique number. Make " +"the same adjustment to the section titles in the list of Invariant Sections " +"in the license notice of the combined work." +msgstr "" +"Det kombinerade verket behöver bara innehålla en enstaka kopia av denna " +"licens [engelska originalversionen], och flera identiska oföränderliga stycken kan ersättas med en kopia. Om det " +"finns flera oföränderliga stycken med samma namn men olika innehåll, se till " +"att titeln på varje sådant avsnitt är unik genom att i slutet på den, inom " +"parentes, lägga till namnet på den ursprunglige författaren eller utgivaren " +"av det avsnittet om dessa är kända, annars ett unikt nummer. Gör samma " +"justeringar av titlarna i listan över oföränderliga avsnitt i " +"licensklausulen i det kombinerade verket." + +#. (itstool) path: sect1/para +#: C/index.docbook:505 +msgid "" +"In the combination, you must combine any sections entitled History in the various original documents, forming one section entitled " +"History; likewise combine any sections entitled " +"Acknowledgements, and any sections entitled " +"Dedications. You must delete all sections entitled " +"Endorsements." +msgstr "" +"I det kombinerade verket måste du kombinera alla avsnitt med titlarna " +"historik (History) i de ursprungliga dokumenten, till ett " +"avsnitt med titeln historik (History); på samma sätt skall " +"alla avsnitt med titlarna tillkännagivanden " +"(Acknowledgements), alla avsnitt med titlarna dedikationer " +"(Dedications) kombineras. Du måste ta bort alla avsnitt med titlarna " +"endossering (Endorsements)." + +#. (itstool) path: sect1/title +#: C/index.docbook:516 C/fdl-appendix.xml:516 msgid "6. COLLECTIONS OF DOCUMENTS" msgstr "6. SAMLINGAR AV DOKUMENT" -#: C/gtk-doc-manual.xml:517(para) -msgid "You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects." -msgstr "Du äger skapa en samling bestående av dokumentet och andra dokument som är släppta under GNU Free Documentation License, och ersätta individuella kopior i dokumenten av denna licens med en enda kopia [av den engelska originalversionen] som inkluderas i samlingen, förutsatt att du följer villkoren för ordagrann kopiering i denna licens för varje inkluderat dokument i alla andra avseenden." - -#: C/gtk-doc-manual.xml:527(para) -msgid "You may extract a single document from such a collection, and dispbibute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document." -msgstr "Du äger lyfta ut ett dokument från en sådan samling, och sprida det enskilt under GNU Free Documentation License, förutsatt att du lägger till en kopia av denna licens [den engelska originalversionen] i det utlyfta dokumentet, och följer villkoren för ordagrann kopiering i denna licens för det utlyfta dokumentet i alla andra avseenden." - -#: C/gtk-doc-manual.xml:537(title) +#. (itstool) path: sect1/para +#: C/index.docbook:517 +msgid "" +"You may make a collection consisting of the Document and other documents released under this License, and " +"replace the individual copies of this License in the various documents with " +"a single copy that is included in the collection, provided that you follow " +"the rules of this License for verbatim copying of each of the documents in " +"all other respects." +msgstr "" +"Du äger skapa en samling bestående av dokumentet och andra dokument som är släppta under GNU Free " +"Documentation License, och ersätta individuella kopior i dokumenten av denna " +"licens med en enda kopia [av den engelska originalversionen] som inkluderas " +"i samlingen, förutsatt att du följer villkoren för ordagrann kopiering i " +"denna licens för varje inkluderat dokument i alla andra avseenden." + +#. (itstool) path: sect1/para +#: C/index.docbook:527 C/fdl-appendix.xml:527 +msgid "" +"You may extract a single document from such a collection, and distribute it " +"individually under this License, provided you insert a copy of this License " +"into the extracted document, and follow this License in all other respects " +"regarding verbatim copying of that document." +msgstr "" +"Du äger lyfta ut ett dokument från en sådan samling, och sprida det enskilt " +"under GNU Free Documentation License, förutsatt att du lägger till en kopia " +"av denna licens [den engelska originalversionen] i det utlyfta dokumentet, " +"och följer villkoren för ordagrann kopiering i denna licens för det utlyfta " +"dokumentet i alla andra avseenden." + +#. (itstool) path: sect1/title +#: C/index.docbook:537 C/fdl-appendix.xml:537 msgid "7. AGGREGATION WITH INDEPENDENT WORKS" msgstr "7. SAMMANSLAGNING MED OBEROENDE VERK" -#: C/gtk-doc-manual.xml:538(para) -msgid "A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an aggregate, and this License does not apply to the other self-contained works thus compiled with the Document , on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate." -msgstr "En samling av dokumentet eller av dess derivat med andra separata och oberoende dokument eller verk, på eller i en lagringsvolym eller ett spridningsmedium, kallas för en sammanslagning om den sammanslagna upphovsrätten inte används för att begränsa samlingens användares rättigheter som de enskilda dokumenten medger. När dokumentet ingår i en sådan sammanslagning, gäller inte denna licens de andra verken i samlingen som inte själva är deriverat av dokumentet. Om kravet på omslagstexter enligt paragraf 3 är tillämpligt på dessa kopior av dokumentet, så kan dokumentets omslagstexter, om dokumentet utgör mindre än hälften av hela samlingen, placeras på det omslag som omger dokumentet inuti samlingen, eller den elektroniska motsvarigheten till omslag om dokumentet är i elektronisk form. Annars måste de synas på det omslag som omger hela samlingen." - -#: C/gtk-doc-manual.xml:561(title) +#. (itstool) path: sect1/para +#: C/index.docbook:538 +msgid "" +"A compilation of the Document or its " +"derivatives with other separate and independent documents or works, in or on " +"a volume of a storage or distribution medium, does not as a whole count as a " +"Modified Version of the Document, " +"provided no compilation copyright is claimed for the compilation. Such a " +"compilation is called an aggregate, and this License does not " +"apply to the other self-contained works thus compiled with the Document , on " +"account of their being thus compiled, if they are not themselves derivative " +"works of the Document. If the Cover Text requirement of section 3 is " +"applicable to these copies of the Document, then if the Document is less " +"than one quarter of the entire aggregate, the Document's Cover Texts may be " +"placed on covers that surround only the Document within the aggregate. " +"Otherwise they must appear on covers around the whole aggregate." +msgstr "" +"En samling av dokumentet eller av dess " +"derivat med andra separata och oberoende dokument eller verk, på eller i en " +"lagringsvolym eller ett spridningsmedium, kallas för en " +"sammanslagning om den sammanslagna upphovsrätten inte används " +"för att begränsa samlingens användares rättigheter som de enskilda " +"dokumenten medger. När dokumentet ingår i en sådan sammanslagning, gäller " +"inte denna licens de andra verken i samlingen som inte själva är deriverat " +"av dokumentet. Om kravet på omslagstexter enligt paragraf 3 är tillämpligt " +"på dessa kopior av dokumentet, så kan dokumentets omslagstexter, om " +"dokumentet utgör mindre än en fjärdedel av hela samlingen, placeras på det " +"omslag som omger dokumentet inuti samlingen, eller den elektroniska " +"motsvarigheten till omslag om dokumentet är i elektronisk form. Annars måste " +"de synas på det omslag som omger hela samlingen." + +#. (itstool) path: sect1/title +#: C/index.docbook:561 C/fdl-appendix.xml:561 msgid "8. TRANSLATION" msgstr "8. ÖVERSÄTTNING" -#: C/gtk-doc-manual.xml:562(para) -msgid "Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail." -msgstr "Översättning anses vara en sorts förändring, så du äger sprida översättningar av dokumentet enligt de villkor som sätts i paragraf 4. Oföränderliga avsnitt som ersätts med översättningar kräver tillstånd från deras upphovsrättsinnehavare, men du äger inkludera översättningar av alla eller vissa av dessa oföränderliga avsnitt tillsammans med originalversionerna av dessa oföränderliga avsnitt. Du äger inkludera en översättning av denna licens, och alla licensklausuler i dokumentet, och alla garantiavsägelser, förutsatt att du också innefattar den engelska originalversionen av denna licens och originalversionerna av dessa klausuler. Skulle det finnas skillnader mellan översättningen och originalversionen av denna licens eller någon klausul så gäller originalversionen." - -#: C/gtk-doc-manual.xml:580(title) +#. (itstool) path: sect1/para +#: C/index.docbook:562 +msgid "" +"Translation is considered a kind of modification, so you may distribute " +"translations of the Document under the " +"terms of section 4. Replacing Invariant Sections with translations " +"requires special permission from their copyright holders, but you may " +"include translations of some or all Invariant Sections in addition to the " +"original versions of these Invariant Sections. You may include a translation " +"of this License provided that you also include the original English version " +"of this License. In case of a disagreement between the translation and the " +"original English version of this License, the original English version will " +"prevail." +msgstr "" +"Översättning anses vara en sorts förändring, så du äger sprida " +"översättningar av dokumentet enligt de " +"villkor som sätts i paragraf 4. Oföränderliga avsnitt som ersätts med " +"översättningar kräver tillstånd från deras upphovsrättsinnehavare, men du " +"äger inkludera översättningar av alla eller vissa av dessa oföränderliga " +"avsnitt tillsammans med originalversionerna av dessa oföränderliga avsnitt. " +"Du äger inkludera en översättning av denna licens, och alla licensklausuler " +"i dokumentet, och alla garantiavsägelser, förutsatt att du också innefattar " +"den engelska originalversionen av denna licens och originalversionerna av " +"dessa klausuler. Skulle det finnas skillnader mellan översättningen och " +"originalversionen av denna licens eller någon klausul så gäller " +"originalversionen." + +#. (itstool) path: sect1/title +#: C/index.docbook:580 C/fdl-appendix.xml:580 msgid "9. TERMINATION" msgstr "9. UPPHÖRANDE" -#: C/gtk-doc-manual.xml:581(para) -msgid "You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance." -msgstr "Du äger inte kopiera, förändra, omlicensiera eller sprida dokumentet annat än enligt villkoren i GNU Free Documentation License. Alla övriga försök att kopiera, modifiera, omlicensiera, eller sprida dokumentet är ogiltiga och kommer automatiskt medföra att du förlorar dina rättigheter enligt denna licens. Tredje man som har mottagit kopior eller rättigheter från dig enligt dessa licensvillkor kommer dock inte att förlora sina rättigheter så länge de följer licensvillkoren." - -#: C/gtk-doc-manual.xml:594(title) +#. (itstool) path: sect1/para +#: C/index.docbook:581 +msgid "" +"You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this " +"License. Any other attempt to copy, modify, sublicense or distribute the " +"Document is void, and will automatically terminate your rights under this " +"License. However, parties who have received copies, or rights, from you " +"under this License will not have their licenses terminated so long as such " +"parties remain in full compliance." +msgstr "" +"Du äger inte kopiera, förändra, omlicensiera eller sprida dokumentet annat än enligt villkoren i GNU Free " +"Documentation License. Alla övriga försök att kopiera, modifiera, " +"omlicensiera, eller sprida dokumentet är ogiltiga och kommer automatiskt " +"medföra att du förlorar dina rättigheter enligt denna licens. Tredje man som " +"har mottagit kopior eller rättigheter från dig enligt dessa licensvillkor " +"kommer dock inte att förlora sina rättigheter så länge de följer " +"licensvillkoren." + +#. (itstool) path: sect1/title +#: C/index.docbook:594 C/fdl-appendix.xml:594 msgid "10. FUTURE REVISIONS OF THIS LICENSE" msgstr "10. FRAMTIDA VERSIONER AV DENNA LICENS" -#: C/gtk-doc-manual.xml:595(para) -msgid "The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/." -msgstr "Free Software Foundation kan publicera nya, reviderade versioner av GNU Free Documentation License då och då. Sådana nya versioner kommer att vara likadana i andemening som den nuvarande versionen, men kan skilja i detalj för att behandla nya problem eller angelägenheter. Se http://www.gnu.org/copyleft/." - -#: C/gtk-doc-manual.xml:606(para) -msgid "Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License or any later version applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation." -msgstr "Varje version av licensen ges ett unikt versionsnummer. Om dokumentet stadgar att en specifik numrerad version av denna licens eller valfri senare version gäller för det, så äger du rätten att följa villkoren enligt antingen den angivna versionen eller vilken senare version som helst som publicerats (inte som utkast) av Free Software Foundation. Om dokumentet inte anger en version av denna licens, äger du välja vilken version som helst som publicerats (inte som utkast) av Free Software Foundation." - -#: C/gtk-doc-manual.xml:621(title) +#. (itstool) path: sect1/para +#: C/index.docbook:595 +msgid "" +"The Free " +"Software Foundation may publish new, revised versions of the GNU " +"Free Documentation License from time to time. Such new versions will be " +"similar in spirit to the present version, but may differ in detail to " +"address new problems or concerns. See http://www.gnu.org/copyleft/." +msgstr "" +"Free Software " +"Foundation kan publicera nya, reviderade versioner av GNU Free " +"Documentation License då och då. Sådana nya versioner kommer att vara " +"likadana i andemening som den nuvarande versionen, men kan skilja i detalj " +"för att behandla nya problem eller angelägenheter. Se http://www.gnu.org/copyleft/." + +#. (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 " +"numbered version of this License or any later version applies " +"to it, you have the option of following the terms and conditions either of " +"that specified version or of any later version that has been published (not " +"as a draft) by the Free Software Foundation. If the Document does not " +"specify a version number of this License, you may choose any version ever " +"published (not as a draft) by the Free Software Foundation." +msgstr "" +"Varje version av licensen ges ett unikt versionsnummer. Om dokumentet stadgar att en specifik numrerad version " +"av denna licens eller valfri senare version gäller för det, " +"så äger du rätten att följa villkoren enligt antingen den angivna versionen " +"eller vilken senare version som helst som publicerats (inte som utkast) av " +"Free Software Foundation. Om dokumentet inte anger en version av denna " +"licens, äger du välja vilken version som helst som publicerats (inte som " +"utkast) av Free Software Foundation." + +#. (itstool) path: sect1/title +#: C/index.docbook:621 C/fdl-appendix.xml:621 msgid "Addendum" msgstr "TILLÄGG" -#: C/gtk-doc-manual.xml:622(para) -msgid "To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:" -msgstr "För att använda GNU Free Documentation License för ett dokument du har skrivit, inkludera en kopia av licensen [det engelska originalet] i dokumentet och placera följande copyrightklausul omedelbart efter titelsidan:" +#. (itstool) path: sect1/para +#: C/index.docbook:622 C/fdl-appendix.xml:622 +msgid "" +"To use this License in a document you have written, include a copy of the " +"License in the document and put the following copyright and license notices " +"just after the title page:" +msgstr "" +"För att använda GNU Free Documentation License för ett dokument du har " +"skrivit, inkludera en kopia av licensen [det engelska originalet] i " +"dokumentet och placera följande copyrightklausul omedelbart efter titelsidan:" -#: C/gtk-doc-manual.xml:629(para) +#. (itstool) path: blockquote/para +#: C/index.docbook:629 C/fdl-appendix.xml:629 msgid "Copyright YEAR YOUR NAME." -msgstr "Copyright (c) ÅRTAL DITT NAMN." +msgstr "Copyright © YEAR YOUR NAME." -#: C/gtk-doc-manual.xml:632(para) -msgid "Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled GNU Free Documentation License." -msgstr "Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled GNU Free Documentation License." +#. (itstool) path: blockquote/para +#: C/index.docbook:632 +msgid "" +"Permission is granted to copy, distribute and/or modify this document under " +"the terms of the GNU Free Documentation License, Version 1.1 or any later " +"version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with " +"the Front-Cover Texts being LIST, " +"and with the Back-Cover Texts being " +"LIST. A copy of the license is included in the section entitled GNU " +"Free Documentation License." +msgstr "" +"Permission is granted to copy, distribute and/or modify this document under " +"the terms of the GNU Free Documentation License, Version 1.1 or any later " +"version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with " +"the Front-Cover Texts being LIST, " +"and with the Back-Cover Texts being " +"LIST. A copy of the license is included in the section entitled GNU " +"Free Documentation License." + +#. (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 " +"are invariant. If you have no Front-Cover " +"Texts, write no Front-Cover Texts instead of " +"Front-Cover Texts being LIST; likewise for Back-Cover Texts." +msgstr "" +"Om du inte har några oföränderliga avsnitt, skriv with no Invariant Sections istället för att ange " +"vilka som är oföränderliga. Om du inte har några framsidestexter, skriv no Front-Cover Texts " +"istället för Front-Cover Texts being LIST; såväl som för " +"baksidestexter." + +#. (itstool) path: sect1/para +#: C/index.docbook:657 +msgid "" +"If your document contains nontrivial examples of program code, we recommend " +"releasing these examples in parallel under your choice of free software " +"license, such as the GNU General Public License, to permit their use in free " +"software." +msgstr "" +"Om ditt dokument innehåller icke-triviala exempel med programkod, så " +"rekommenderar vi att du släpper dessa exempel parallellt under en, av dig " +"vald, fri programvarulicens, som till exempel GNU General Public License, " +"för att möjliggöra deras användning i fri programvara." + +#. (itstool) path: copyright/year +#: C/fdl-appendix.xml:16 +msgid "2000" +msgstr "2000" -#: C/gtk-doc-manual.xml:647(para) -msgid "If you have no Invariant Sections, write with no Invariant Sections instead of saying which ones are invariant. If you have no Front-Cover Texts, write no Front-Cover Texts instead of Front-Cover Texts being LIST; likewise for Back-Cover Texts." -msgstr "Om du inte har några oföränderliga avsnitt, skriv utan oföränderliga avsnitt istället för att ange vilka som är oföränderliga. Om du inte har några framsidestexter, skriv utan framsidestexter istället för framsidestexter som LISTAS; såväl som för baksidestexter." +#. (itstool) path: copyright/holder +#: C/fdl-appendix.xml:16 +msgid "Free Software Foundation, Inc." +msgstr "Free Software Foundation, Inc." -#: C/gtk-doc-manual.xml:657(para) -msgid "If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software." -msgstr "Om ditt dokument innehåller icke-triviala exempel med programkod, så rekommenderar vi att du släpper dessa exempel parallellt under en, av dig vald, fri programvarulicens, som till exempel GNU General Public License, för att möjliggöra deras användning i fri programvara." +#. (itstool) path: address/street +#: C/fdl-appendix.xml:20 +msgid "51 Franklin Street, Suite 330" +msgstr "51 Franklin Street, Suite 330" + +#. (itstool) path: address/city +#: C/fdl-appendix.xml:21 +msgid "Boston" +msgstr "Boston" + +#. (itstool) path: address/state +#: C/fdl-appendix.xml:21 +msgid "MA" +msgstr "MA" + +#. (itstool) path: address/postcode +#: C/fdl-appendix.xml:22 +msgid "02110-1301" +msgstr "02110-1301" + +#. (itstool) path: address/country +#: C/fdl-appendix.xml:22 +msgid "USA" +msgstr "USA" + +#. (itstool) path: para/address +#: C/fdl-appendix.xml:20 +msgid "" +"Free Software Foundation, Inc. <_:street-1/>, <_:city-2/>, <_:state-3/> <_:" +"postcode-4/> <_:country-5/>" +msgstr "" +"Free Software Foundation, Inc. <_:street-1/>, <_:city-2/>, <_:state-3/> <_:" +"postcode-4/> <_:country-5/>" -#. Put one translator per line, in the form of NAME , YEAR1, YEAR2. -#: C/gtk-doc-manual.xml:0(None) -msgid "translator-credits" +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:34 +msgid "free" +msgstr "fritt" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:32 +msgid "" +"The purpose of this License is to make a manual, textbook, or other written " +"document <_:quote-1/> in the sense of freedom: to assure everyone the " +"effective freedom to copy and redistribute it, with or without modifying it, " +"either commercially or noncommercially. Secondarily, this License preserves " +"for the author and publisher a way to get credit for their work, while not " +"being considered responsible for modifications made by others." +msgstr "" +"Syftet med denna licens är att göra en handbok, bok, eller annat praktiskt " +"och användbart dokument <_:quote-1/> som i frihet: att försäkra var och en " +"den faktiska friheten att kopiera och sprida det vidare, med eller utan " +"förändringar, antingen kommersiellt eller ideellt. Sekundärt bevarar denna " +"licens ett sätt för författaren och förläggaren att få ära för deras arbete " +"utan att de anses vara ansvariga för förändringar gjorda av andra." + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:44 +msgid "copyleft" +msgstr "copyleft" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:43 +msgid "" +"This License is a kind of <_:quote-1/>, which means that derivative works of " +"the document must themselves be free in the same sense. It complements the " +"GNU General Public License, which is a copyleft license designed for free " +"software." +msgstr "" +"Denna Licens är en sorts <_:quote-1/>, vilket betyder att derivativa verk av " +"detta dokument själva måste vara fria på samma sätt. Den kompletterar GNU " +"General Public License, som är en copyleft-licens utformad för fri " +"programvara." + +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:67 C/fdl-appendix.xml:82 C/fdl-appendix.xml:99 +#: C/fdl-appendix.xml:107 C/fdl-appendix.xml:113 C/fdl-appendix.xml:156 +#: C/fdl-appendix.xml:179 C/fdl-appendix.xml:190 C/fdl-appendix.xml:205 +#: C/fdl-appendix.xml:224 C/fdl-appendix.xml:235 C/fdl-appendix.xml:253 +#: C/fdl-appendix.xml:271 C/fdl-appendix.xml:294 C/fdl-appendix.xml:354 +#: C/fdl-appendix.xml:368 C/fdl-appendix.xml:400 C/fdl-appendix.xml:462 +#: C/fdl-appendix.xml:472 C/fdl-appendix.xml:482 C/fdl-appendix.xml:519 +#: C/fdl-appendix.xml:540 C/fdl-appendix.xml:565 C/fdl-appendix.xml:583 +#: C/fdl-appendix.xml:608 +msgid "Document" +msgstr "Dokument" + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:69 +msgid "you" +msgstr "du" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:63 +msgid "" +"This License applies to any manual or other work that contains a notice " +"placed by the copyright holder saying it can be distributed under the terms " +"of this License. The <_:quote-1/>, below, refers to any such manual or work. " +"Any member of the public is a licensee, and is addressed as <_:quote-2/>." +msgstr "" +"Denna licens [det engelska originalet] gäller för varje handbok eller annat " +"verk, oavsett uttrycksform, som innehåller ett meddelande där " +"upphovsrättsinnehavaren stadgat att verket kan spridas enligt villkoren i " +"GNU Free Documentation License. Ett sådant meddelande ger en internationell " +"frihet utan krav på ersättning och utan tidsbegränsning att använda verket " +"under villkoren i denna licens [det engelska originalet]. <_:quote-1/> nedan " +"syftar på godtycklig handbok eller verk. Var och en är licenstagare och " +"benämns som <_:quote-2/>." + +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:73 C/fdl-appendix.xml:234 C/fdl-appendix.xml:269 +#: C/fdl-appendix.xml:283 C/fdl-appendix.xml:315 C/fdl-appendix.xml:351 +#: C/fdl-appendix.xml:413 C/fdl-appendix.xml:433 C/fdl-appendix.xml:447 +#: C/fdl-appendix.xml:459 C/fdl-appendix.xml:475 C/fdl-appendix.xml:543 +msgid "Modified Version" +msgstr "förändrad version" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:72 +msgid "" +"A <_:quote-1/> of the Document means any work containing the Document or a " +"portion of it, either copied verbatim, or with modifications and/or " +"translated into another language." msgstr "" -"Daniel Nylander , 2009\n" -"Marcus Rejås och Alexander Nordström , 2004" +"En <_:quote-1/> av dokumentet avser varje verk som innehåller dokumentet " +"eller en del av det, antingen ordagranna kopior, eller med ändringar och/" +"eller översatt till ett annat språk." +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:80 +msgid "Secondary Section" +msgstr "sekundärt avsnitt" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:79 +msgid "" +"A <_:quote-1/> is a named appendix or a front-matter section of the <_:" +"link-2/> that deals exclusively with the relationship of the publishers or " +"authors of the Document to the Document's overall subject (or to related " +"matters) and contains nothing that could fall directly within that overall " +"subject. (For example, if the Document is in part a textbook of mathematics, " +"a Secondary Section may not explain any mathematics.) The relationship could " +"be a matter of historical connection with the subject or with related " +"matters, or of legal, commercial, philosophical, ethical or political " +"position regarding them." +msgstr "" +"Ett <_:quote-1/> är en märkt bilaga eller förord till dokumentet som exklusivt behandlar förhållandet mellan " +"dokumentets förläggare eller författare och dokumentets huvudsakliga ämne " +"(eller till relaterade ämnen) och som inte innehåller något som direkt " +"faller under det huvudsakliga ämnet. (Således, om dokumentet delvis är en " +"lärobok i matematik så får ett sekundärt avsnitt inte förklara någon " +"matematik.) Förhållandet kan vara en historisk koppling till ämnet eller " +"något relaterat, eller en juridisk, kommersiell, filosofisk, etisk eller " +"politisk ställning till det." + +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:95 C/fdl-appendix.xml:327 C/fdl-appendix.xml:398 +#: C/fdl-appendix.xml:439 C/fdl-appendix.xml:486 C/fdl-appendix.xml:494 +#: C/fdl-appendix.xml:567 C/fdl-appendix.xml:637 C/fdl-appendix.xml:648 +msgid "Invariant Sections" +msgstr "oföränderliga avsnitten" + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:96 C/fdl-appendix.xml:435 +msgid "Secondary Sections" +msgstr "sekundära avsnitt" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:94 +msgid "" +"The <_:quote-1/> are certain <_:link-2/> whose titles are designated, as " +"being those of Invariant Sections, in the notice that says that the <_:" +"link-3/> is released under this License." +msgstr "" +"De <_:quote-1/> är <_:link-2/> vars titlar är angivna som oföränderliga " +"avsnitt i meddelandet som stadgar att <_:link-3/> är utgivet under denna " +"licens [det engelska originalet]." + +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:104 C/fdl-appendix.xml:181 C/fdl-appendix.xml:328 +#: C/fdl-appendix.xml:458 +msgid "Cover Texts" +msgstr "Omslagstexterna" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:103 +msgid "" +"The <_:quote-1/> are certain short passages of text that are listed, as " +"Front-Cover Texts or Back-Cover Texts, in the notice that says that the <_:" +"link-2/> is released under this License." +msgstr "" +"<_:quote-1/> är speciella korta ordföljder som är listade som " +"framsidestexter eller baksidestexter i meddelandet som stadgar att <_:link-2/" +"> är utgivet under denna licens [det engelska originalet]." + +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:112 C/fdl-appendix.xml:124 C/fdl-appendix.xml:207 +#: C/fdl-appendix.xml:369 +msgid "Transparent" +msgstr "transparent" + +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:125 C/fdl-appendix.xml:204 +msgid "Opaque" +msgstr "opak" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:111 +msgid "" +"A <_:quote-1/> copy of the <_:link-2/> means a machine-readable copy, " +"represented in a format whose specification is available to the general " +"public, whose contents can be viewed and edited directly and " +"straightforwardly with generic text editors or (for images composed of " +"pixels) generic paint programs or (for drawings) some widely available " +"drawing editor, and that is suitable for input to text formatters or for " +"automatic translation to a variety of formats suitable for input to text " +"formatters. A copy made in an otherwise Transparent file format whose markup " +"has been designed to thwart or discourage subsequent modification by readers " +"is not Transparent. A copy that is not <_:quote-3/> is called <_:quote-4/>." +msgstr "" +"En <_:quote-1/> kopia av <_:link-2/> är en maskinläsbar kopia, representerad " +"i ett format vars specifikation finns tillgänglig för allmänheten, som " +"lämpar sig för att revidera dokumentet på ett enkelt sätt med generella " +"textredigeringsprogram eller (för pixelbaserade bilder) generella " +"grafikprogram eller (för ritningar) något väl tillgängligt ritprogram, och " +"som är passande som indata till textformaterare eller för automatisk " +"konvertering till en mängd format som passar som indata till " +"textformaterare. En kopia i ett för övrigt transparent filformat vars " +"markeringar, eller avsaknad av markeringar, har ordnats för att hindra eller " +"motverka att vidare förändring vidtas av läsare är inte transparent. En " +"kopia som inte är <_:quote-3/> kallas <_:quote-4/>." + +#. (itstool) path: para/quote +#. (itstool) path: para/link +#: C/fdl-appendix.xml:142 C/fdl-appendix.xml:146 C/fdl-appendix.xml:250 +#: C/fdl-appendix.xml:266 C/fdl-appendix.xml:281 C/fdl-appendix.xml:352 +msgid "Title Page" +msgstr "Titelsidan" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:141 +msgid "" +"The <_:quote-1/> means, for a printed book, the title page itself, plus such " +"following pages as are needed to hold, legibly, the material this License " +"requires to appear in the title page. For works in formats which do not have " +"any title page as such, <_:quote-2/> means the text near the most prominent " +"appearance of the work's title, preceding the beginning of the body of the " +"text." +msgstr "" +"<_:quote-1/> innebär, för en tryckt bok, titelsidan själv, och sådana därpå " +"följande sidor som krävs för att göra det material som enligt denna licens " +"skall synas på titelsidan läsbart. För verk i sådana format som inte har " +"någon egentlig titelsida, avses med <_:quote-2/> den text som är närmast den " +"mest framstående förekomsten av verkets titel, föregående den huvudsakliga " +"textmassan." + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:166 C/fdl-appendix.xml:551 +msgid "section 3" +msgstr "paragraf 3" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:154 +msgid "" +"You may copy and distribute the <_:link-1/> in any medium, either " +"commercially or noncommercially, provided that this License, the copyright " +"notices, and the license notice saying this License applies to the Document " +"are reproduced in all copies, and that you add no other conditions " +"whatsoever to those of this License. You may not use technical measures to " +"obstruct or control the reading or further copying of the copies you make or " +"distribute. However, you may accept compensation in exchange for copies. If " +"you distribute a large enough number of copies you must also follow the " +"conditions in <_:link-2/>." +msgstr "" +"Du äger kopiera och sprida <_:link-1/> på valfritt medium, antingen " +"kommersiellt eller ideellt, förutsatt att denna licens [det engelska " +"originalet], upphovsrättsklausul, och meddelandet som stadgar att GNU Free " +"Documentation License gäller för dokumentet finns med på alla kopior, och " +"att du inte lägger till några som helst andra villkor än de som ingår i " +"denna licens. Du äger inte vidta tekniska åtgärder för att begränsa eller " +"kontrollera läsande eller vidare kopiering av de kopior du skapar eller " +"sprider. Dock äger du ta emot kompensation i utbyte mot kopior. Om du " +"sprider tillräckligt många kopior måste du också följa villkoren i <_:link-2/" +">." + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:177 +msgid "" +"If you publish printed copies of the <_:link-1/> numbering more than 100, " +"and the Document's license notice requires <_:link-2/>, you must enclose the " +"copies in covers that carry, clearly and legibly, all these Cover Texts: " +"Front-Cover Texts on the front cover, and Back-Cover Texts on the back " +"cover. Both covers must also clearly and legibly identify you as the " +"publisher of these copies. The front cover must present the full title with " +"all words of the title equally prominent and visible. You may add other " +"material on the covers in addition. Copying with changes limited to the " +"covers, as long as they preserve the title of the <_:link-3/> and satisfy " +"these conditions, can be treated as verbatim copying in other respects." +msgstr "" +"Om du publicerar tryckta kopior (eller kopior i medier som normalt har " +"tryckta omslag) av <_:link-1/>, i en upplaga överstigande 100 exemplar, och " +"dokumentets licensmeddelande kräver <_:link-2/>, så måste du förse kopiorna " +"med omslag som, klart och tydligt, visar alla omslagstexter: framsidestexter " +"på framsidan och baksidestexter på baksidan. Båda omslagen måste klart och " +"tydligt identifiera dig som utgivare av dessa kopior. Framsidan måste " +"presentera dokumentets hela titel, med alla ord i titeln lika framträdande " +"och synliga. Du äger lägga till ytterligare stoff på omslagen. Kopiering med " +"förändringar gjorda bara på omslaget, så länge som de bevarar titeln för <_:" +"link-3/> och i övrigt uppfyller dessa krav kan anses vara ordagrann " +"kopiering i andra avseenden." + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:202 +msgid "" +"If you publish or distribute <_:link-1/> copies of the <_:link-2/> numbering " +"more than 100, you must either include a machine-readable <_:link-3/> copy " +"along with each Opaque copy, or state in or with each Opaque copy a publicly-" +"accessible computer-network location containing a complete Transparent copy " +"of the Document, free of added material, which the general network-using " +"public has access to download anonymously at no charge using public-standard " +"network protocols. If you use the latter option, you must take reasonably " +"prudent steps, when you begin distribution of Opaque copies in quantity, to " +"ensure that this Transparent copy will remain thus accessible at the stated " +"location until at least one year after the last time you distribute an " +"Opaque copy (directly or through your agents or retailers) of that edition " +"to the public." +msgstr "" +"Om du publicerar <_:link-1/>a kopior av <_:link-2/> i upplagor om mer än " +"100, måste du antingen bifoga en maskinläsbar <_:link-3/> kopia med varje " +"opak kopia, eller ange i eller med varje opak kopia en nätverksadress som är " +"tillgänglig för den allmänna nätverksanvändande massan där man, med öppet " +"standardiserade protokoll, anonymt och utan kostnad kan ladda ner en " +"komplett transparent kopia av dokumentet, utan extra material. Om du väljer " +"det senare alternativet, måste du vidta skäliga åtgärder, när du börjar " +"sprida opaka kopior i kvantitet, för att denna transparenta kopia skall " +"förbli tillgänglig på angivna platsen till åtminstone ett år efter den sista " +"gången du spred en opak kopia (direkt eller via ombud eller återförsäljare) " +"av den utgåvan till allmänheten." + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:222 +msgid "" +"It is requested, but not required, that you contact the authors of the <_:" +"link-1/> well before redistributing any large number of copies, to give them " +"a chance to provide you with an updated version of the Document." +msgstr "" +"Det är önskvärt, men inte ett krav, att du kontaktar författarna till <_:" +"link-1/> i god tid innan du sprider något större antal kopior, för att ge " +"dem en chans att förse dig med en uppdaterad version av dokumentet." + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:236 +msgid "2" +msgstr "2" + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:237 +msgid "3" +msgstr "3" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:232 +msgid "" +"You may copy and distribute a <_:link-1/> of the <_:link-2/> under the " +"conditions of sections <_:link-3/> and <_:link-4/> above, provided that you " +"release the Modified Version under precisely this License, with the Modified " +"Version filling the role of the Document, thus licensing distribution and " +"modification of the Modified Version to whoever possesses a copy of it. In " +"addition, you must do these things in the Modified Version:" +msgstr "" +"Du äger kopiera och sprida en <_:link-1/> av <_:link-2/> under de villkor " +"som beskrivs i paragraf <_:link-3/> och <_:link-4/> av GNU Free " +"Documentation License, förutsatt att du släpper den förändrade versionen " +"under exakt denna licens, och att den förändrade versionen antar dokumentets " +"roll, och således medger spridning och förändring av den förändrade " +"versionen till envar som erhåller en kopia av den. Utöver detta måste du " +"göra följande med den ändrade versionen:" + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:249 +msgid "" +"Use in the <_:link-1/> (and on the covers, if any) a title distinct from " +"that of the <_:link-2/>, and from those of previous versions (which should, " +"if there were any, be listed in the History section of the Document). You " +"may use the same title as a previous version if the original publisher of " +"that version gives permission." +msgstr "" +"På <_:link-1/> (och omslagen om det finns några) använda en titel skild från " +"den som [original]<_:link-2/> har, och skild från tidigare versioners titel " +"(som skall, om det finns några, finnas listade i historikavsnittet i " +"dokumentet). Du äger använda samma titel som det föregående dokumentet om " +"den ursprungliga utgivaren ger sitt tillstånd." + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:265 +msgid "" +"List on the <_:link-1/>, as authors, one or more persons or entities " +"responsible for authorship of the modifications in the <_:link-2/>, together " +"with at least five of the principal authors of the <_:link-3/> (all of its " +"principal authors, if it has less than five)." +msgstr "" +"Lista på <_:link-1/>, som författare, en eller flera personer eller " +"juridiska personer som ansvarat för förändringarna i <_:link-2/>, " +"tillsammans med minst fem av de huvudsakliga författarna av <_:link-3/> " +"(alla dess huvudsakliga författare, om det har mindre än fem)." + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:280 +msgid "" +"State on the <_:link-1/> the name of the publisher of the <_:link-2/>, as " +"the publisher." +msgstr "Ange namnet på utgivaren av <_:link-1/>, som utgivare, på <_:link-2/>." + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:292 +msgid "Preserve all the copyright notices of the <_:link-1/>." +msgstr "Bibehålla alla upphovsrättsklausuler för <_:link-1/>." + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:312 +msgid "" +"Include, immediately after the copyright notices, a license notice giving " +"the public permission to use the <_:link-1/> under the terms of this " +"License, in the form shown in the Addendum below." +msgstr "" +"Direkt efter upphovsrättsklausulerna innefatta ett meddelande som ger " +"allmänheten tillstånd att använda <_:link-1/> under villkoren i denna licens " +"[det engelska originalet] i den form som visas i Tillägg nedan." + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:330 +msgid "Document's" +msgstr "dokumentets" + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:325 +msgid "" +"Preserve in that license notice the full lists of <_:link-1/> and required " +"<_:link-2/> given in the <_:link-3/> license notice." +msgstr "" +"I meddelandet om licensen bevara den fullständiga listan över <_:link-1/> " +"och obligatoriska <_:link-2/> som finns i <_:link-3/> meddelande om licensen." + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:348 C/fdl-appendix.xml:353 C/fdl-appendix.xml:372 +#: C/fdl-appendix.xml:507 C/fdl-appendix.xml:508 +msgid "History" +msgstr "historik" + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:347 +msgid "" +"Preserve the section entitled <_:quote-1/>, and its title, and add to it an " +"item stating at least the title, year, new authors, and publisher of the <_:" +"link-2/> as given on the <_:link-3/>. If there is no section entitled <_:" +"quote-4/> in the <_:link-5/>, create one stating the title, year, authors, " +"and publisher of the Document as given on its Title Page, then add an item " +"describing the Modified Version as stated in the previous sentence." +msgstr "" +"Bevara avsnittet med titeln <_:quote-1/> (History), bevara dess titel och " +"lägg i avsnittet till en post med åtminstone titeln, året, nya författare " +"och utgivaren av <_:link-2/> så som angivet på <_:link-3/>. Om det inte " +"finns något avsnitt med titeln <_:quote-4/> (History) i <_:link-5/> så skapa " +"en med titeln, året, författare och utgivaren av dokumentet så som det står " +"på [original]dokumentets titelsida. Lägg sedan till en post som beskriver " +"den förändrade versionen så som beskrivits ovan." + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:366 +msgid "" +"Preserve the network location, if any, given in the <_:link-1/> for public " +"access to a <_:link-2/> copy of the Document, and likewise the network " +"locations given in the Document for previous versions it was based on. These " +"may be placed in the <_:quote-3/> section. You may omit a network location " +"for a work that was published at least four years before the Document " +"itself, or if the original publisher of the version it refers to gives " +"permission." +msgstr "" +"Bevara den nätverksadress, om det finns någon, angiven i <_:link-1/> till " +"den allmänt tillgängliga <_:link-2/>a kopian av dokumentet, och likaså " +"nätverksadresserna till de föregående versioner som dokumentet baseras på. " +"Dessa får placeras i avsnittet <_:quote-3/> (History). Du äger utelämna en " +"nätverksadress för ett verk som är publicerat mer än fyra år före dokumentet " +"självt, eller om den ursprunglige utgivaren vars verk nätverksadressen " +"hänvisar till ger sitt tillstånd." + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:385 C/fdl-appendix.xml:509 +msgid "Acknowledgements" +msgstr "tillkännagivanden" + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:386 C/fdl-appendix.xml:510 +msgid "Dedications" +msgstr "dedikationer" + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:384 +msgid "" +"In any section entitled <_:quote-1/> or <_:quote-2/>, preserve the section's " +"title, and preserve in the section all the substance and tone of each of the " +"contributor acknowledgements and/or dedications given therein." +msgstr "" +"För alla avsnitt med titlarna <_:quote-1/> (Acknowledgements) eller <_:" +"quote-2/> (Dedications), bevara titeln på avsnittet, och bevara allt " +"innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda " +"av varje bidragsgivare." + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:397 +msgid "" +"Preserve all the <_:link-1/> of the <_:link-2/>, unaltered in their text and " +"in their titles. Section numbers or the equivalent are not considered part " +"of the section titles." +msgstr "" +"Bevara alla <_:link-1/> i <_:link-2/> oförändrade till text och titel. " +"Avsnittsnummer eller motsvarande anses inte tillhöra avsnittets titel." + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:412 C/fdl-appendix.xml:424 C/fdl-appendix.xml:445 +msgid "Endorsements" +msgstr "endossering" + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:410 +msgid "" +"Delete any section entitled <_:quote-1/>. Such a section may not be included " +"in the <_:link-2/>." +msgstr "" +"Radera varje avsnitt med titeln <_:quote-1/> (Endorsements). Ett sådant " +"avsnitt får inte inkluderas i en <_:link-2/>." + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:425 +msgid "Invariant Section" +msgstr "oföränderligt avsnitt" + +#. (itstool) path: formalpara/para +#: C/fdl-appendix.xml:422 +msgid "" +"Do not retitle any existing section as <_:quote-1/> or to conflict in title " +"with any <_:link-2/>." +msgstr "" +"Inte byta titel på något existerande avsnitt så att det blir <_:quote-1/> " +"(Endorsements) eller så att titeln kan förväxlas med något <_:link-2/>." + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:432 +msgid "" +"If the <_:link-1/> includes new front-matter sections or appendices that " +"qualify as <_:link-2/> and contain no material copied from the Document, you " +"may at your option designate some or all of these sections as invariant. To " +"do this, add their titles to the list of <_:link-3/> in the Modified " +"Version's license notice. These titles must be distinct from any other " +"section titles." +msgstr "" +"Om <_:link-1/> innehåller nya framsidestexter eller bilagor som är att anses " +"som <_:link-2/> och inte innehåller något material kopierat från dokumentet, " +"så äger du, om du vill, benämna några eller samtliga av dessa som " +"oföränderliga. För att göra detta, lägg deras titlar till listan över <_:" +"link-3/> i den förändrade versionens licensmeddelande. Dessa titlar måste " +"vara skilda från alla andra avsnitts titlar." + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:444 +msgid "" +"You may add a section entitled <_:quote-1/>, provided it contains nothing " +"but endorsements of your <_:link-2/> by various parties--for example, " +"statements of peer review or that the text has been approved by an " +"organization as the authoritative definition of a standard." +msgstr "" +"Du äger lägga till ett avsnitt med titeln <_:quote-1/> (Endorsements), " +"förutsatt att det inte innehåller något annat än endosseringar för din <_:" +"link-2/> från olika aktörer -- till exempel, meddelanden om utförd " +"korrekturläsning eller att texten har godkänts av en organisation som en " +"officiell definition av en standard." + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:455 +msgid "Front-Cover Text" +msgstr "framsidestext" + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:457 +msgid "Back-Cover Text" +msgstr "baksidestext" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:453 +msgid "" +"You may add a passage of up to five words as a <_:link-1/>, and a passage of " +"up to 25 words as a <_:link-2/>, to the end of the list of <_:link-3/> in " +"the <_:link-4/>. Only one passage of Front-Cover Text and one of Back-Cover " +"Text may be added by (or through arrangements made by) any one entity. If " +"the <_:link-5/> already includes a cover text for the same cover, previously " +"added by you or by arrangement made by the same entity you are acting on " +"behalf of, you may not add another; but you may replace the old one, on " +"explicit permission from the previous publisher that added the old one." +msgstr "" +"Du äger lägga till ett textavsnitt på upp till fem ord som <_:link-1/>, och " +"ett textavsnitt på upp till 25 ord som <_:link-2/> i listan över <_:link-3/> " +"i <_:link-4/>. Bara ett textavsnitt med framsidestexter och ett med " +"baksidestexter får läggas till av (eller genom försorg av) en enda juridisk " +"person. Om <_:link-5/> redan innehåller en omslagstext för något av " +"omslagen, tidigare tillagd av dig eller genom försorg av samma juridiska " +"person som du företräder, äger du inte lägga till en till, men du äger ändra " +"den gamla med tillstånd från den tidigare utgivaren som lade till den förra." + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:470 +msgid "" +"The author(s) and publisher(s) of the <_:link-1/> do not by this License " +"give permission to use their names for publicity for or to assert or imply " +"endorsement of any <_:link-2/>." +msgstr "" +"Författaren (författarna) och utgivaren (utgivarna) av <_:link-1/> ger inte " +"via denna licens sitt tillstånd att använda sina namn för publicitet eller " +"för att lägga till eller antyda endossering av någon <_:link-2/>." + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:484 C/fdl-appendix.xml:566 +msgid "section 4" +msgstr "paragraf 4" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:481 +msgid "" +"You may combine the <_:link-1/> with other documents released under this " +"License, under the terms defined in <_:link-2/> above for modified versions, " +"provided that you include in the combination all of the <_:link-3/> of all " +"of the original documents, unmodified, and list them all as Invariant " +"Sections of your combined work in its license notice." +msgstr "" +"Du äger kombinera <_:link-1/> med andra dokument som är utgivna under denna " +"licens, under de villkor som definieras i <_:link-2/> av GNU Free " +"Documentation License för förändrade versioner, förutsatt att du, i det " +"kombinerade dokumentet, innefattar alla <_:link-3/> från originaldokumenten, " +"omodifierade, och listar dem som oföränderliga avsnitt i ditt kombinerade " +"verk i dess licensklausul, och att du bevarar alla deras " +"garantiavsägelseklausuler." + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:492 +msgid "" +"The combined work need only contain one copy of this License, and multiple " +"identical <_:link-1/> may be replaced with a single copy. If there are " +"multiple Invariant Sections with the same name but different contents, make " +"the title of each such section unique by adding at the end of it, in " +"parentheses, the name of the original author or publisher of that section if " +"known, or else a unique number. Make the same adjustment to the section " +"titles in the list of Invariant Sections in the license notice of the " +"combined work." +msgstr "" +"Det kombinerade verket behöver bara innehålla en enstaka kopia av denna " +"licens [engelska originalversionen], och flera identiska <_:link-1/> kan " +"ersättas med en kopia. Om det finns flera oföränderliga stycken med samma " +"namn men olika innehåll, se till att titeln på varje sådant avsnitt är unik " +"genom att i slutet på den, inom parentes, lägga till namnet på den " +"ursprunglige författaren eller utgivaren av det avsnittet om dessa är kända, " +"annars ett unikt nummer. Gör samma justeringar av titlarna i listan över " +"oföränderliga avsnitt i licensklausulen i det kombinerade verket." + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:511 +msgid "Endorsements." +msgstr "endossering" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:505 +msgid "" +"In the combination, you must combine any sections entitled <_:quote-1/> in " +"the various original documents, forming one section entitled <_:quote-2/>; " +"likewise combine any sections entitled <_:quote-3/>, and any sections " +"entitled <_:quote-4/>. You must delete all sections entitled <_:quote-5/>" +msgstr "" +"I det kombinerade verket måste du kombinera alla avsnitt med titlarna <_:" +"quote-1/> (History) i de ursprungliga dokumenten, till ett avsnitt med " +"titeln <_:quote-2/> (History); på samma sätt skall alla avsnitt med titlarna " +"<_:quote-3/> (Acknowledgements), alla avsnitt med titlarna <_:quote-4/> " +"(Dedications) kombineras. Du måste ta bort alla avsnitt med titlarna <_:" +"quote-5/> (Endorsements)." + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:517 +msgid "" +"You may make a collection consisting of the <_:link-1/> and other documents " +"released under this License, and replace the individual copies of this " +"License in the various documents with a single copy that is included in the " +"collection, provided that you follow the rules of this License for verbatim " +"copying of each of the documents in all other respects." +msgstr "" +"Du äger skapa en samling bestående av <_:link-1/> och andra dokument som är " +"släppta under GNU Free Documentation License, och ersätta individuella " +"kopior i dokumenten av denna licens med en enda kopia [av den engelska " +"originalversionen] som inkluderas i samlingen, förutsatt att du följer " +"villkoren för ordagrann kopiering i denna licens för varje inkluderat " +"dokument i alla andra avseenden." + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:546 +msgid "aggregate" +msgstr "sammanslagning" + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:550 +msgid "Cover Text" +msgstr "Omslagstext" + +# sebras +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:538 +msgid "" +"A compilation of the <_:link-1/> or its derivatives with other separate and " +"independent documents or works, in or on a volume of a storage or " +"distribution medium, does not as a whole count as a <_:link-2/> of the " +"Document, provided no compilation copyright is claimed for the compilation. " +"Such a compilation is called an <_:quote-3/>, and this License does not " +"apply to the other self-contained works thus compiled with the Document , on " +"account of their being thus compiled, if they are not themselves derivative " +"works of the Document. If the <_:link-4/> requirement of <_:link-5/> is " +"applicable to these copies of the Document, then if the Document is less " +"than one quarter of the entire aggregate, the Document's Cover Texts may be " +"placed on covers that surround only the Document within the aggregate. " +"Otherwise they must appear on covers around the whole aggregate." +msgstr "" +"En samling av <_:link-1/> eller av dess derivat med andra separata och " +"oberoende dokument eller verk, på eller i en lagringsvolym eller ett " +"spridningsmedium, kallas för en sammanslagning om den " +"sammanslagna upphovsrätten inte används för att begränsa samlingens " +"användares rättigheter som de enskilda dokumenten medger. När dokumentet " +"ingår i en sådan sammanslagning, gäller inte denna licens de andra verken i " +"samlingen som inte själva är deriverat av dokumentet. Om kravet på omslagstexter enligt paragraf 3 är tillämpligt på dessa kopior av dokumentet, " +"så kan dokumentets omslagstexter, om dokumentet utgör mindre än en fjärdedel " +"av hela samlingen, placeras på det omslag som omger dokumentet inuti " +"samlingen, eller den elektroniska motsvarigheten till omslag om dokumentet " +"är i elektronisk form. Annars måste de synas på det omslag som omger hela " +"samlingen." + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:562 +msgid "" +"Translation is considered a kind of modification, so you may distribute " +"translations of the <_:link-1/> under the terms of <_:link-2/>. Replacing <_:" +"link-3/> with translations requires special permission from their copyright " +"holders, but you may include translations of some or all Invariant Sections " +"in addition to the original versions of these Invariant Sections. You may " +"include a translation of this License provided that you also include the " +"original English version of this License. In case of a disagreement between " +"the translation and the original English version of this License, the " +"original English version will prevail." +msgstr "" +"Översättning anses vara en sorts förändring, så du äger sprida " +"översättningar av <_:link-1/> enligt de villkor som sätts i <_:link-2/>. <_:" +"link-3/> som ersätts med översättningar kräver tillstånd från deras " +"upphovsrättsinnehavare, men du äger inkludera översättningar av alla eller " +"vissa av dessa oföränderliga avsnitt tillsammans med originalversionerna av " +"dessa oföränderliga avsnitt. Du äger inkludera en översättning av denna " +"licens, och alla licensklausuler i dokumentet, och alla garantiavsägelser, " +"förutsatt att du också innefattar den engelska originalversionen av denna " +"licens och originalversionerna av dessa klausuler. Skulle det finnas " +"skillnader mellan översättningen och originalversionen av denna licens eller " +"någon klausul så gäller originalversionen." + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:581 +msgid "" +"You may not copy, modify, sublicense, or distribute the <_:link-1/> except " +"as expressly provided for under this License. Any other attempt to copy, " +"modify, sublicense or distribute the Document is void, and will " +"automatically terminate your rights under this License. However, parties who " +"have received copies, or rights, from you under this License will not have " +"their licenses terminated so long as such parties remain in full compliance." +msgstr "" +"Du äger inte kopiera, förändra, omlicensiera eller sprida <_:link-1/> annat " +"än enligt villkoren i GNU Free Documentation License. Alla övriga försök att " +"kopiera, modifiera, omlicensiera, eller sprida dokumentet är ogiltiga och " +"kommer automatiskt medföra att du förlorar dina rättigheter enligt denna " +"licens. Tredje man som har mottagit kopior eller rättigheter från dig enligt " +"dessa licensvillkor kommer dock inte att förlora sina rättigheter så länge " +"de följer licensvillkoren." + +#. (itstool) path: para/ulink +#: C/fdl-appendix.xml:597 +msgid "Free Software Foundation" +msgstr "Free Software Foundation" + +#. (itstool) path: para/ulink +#: C/fdl-appendix.xml:603 +msgid "http://www.gnu.org/copyleft/" +msgstr "http://www.gnu.org/copyleft/" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:595 +msgid "" +"The <_:ulink-1/> may publish new, revised versions of the GNU Free " +"Documentation License from time to time. Such new versions will be similar " +"in spirit to the present version, but may differ in detail to address new " +"problems or concerns. See <_:ulink-2/>." +msgstr "" +"<_:ulink-1/> kan publicera nya, reviderade versioner av GNU Free " +"Documentation License då och då. Sådana nya versioner kommer att vara " +"likadana i andemening som den nuvarande versionen, men kan skilja i detalj " +"för att behandla nya problem eller angelägenheter. Se <_:ulink-2/>." + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:610 +msgid "or any later version" +msgstr "eller valfri senare version" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:606 +msgid "" +"Each version of the License is given a distinguishing version number. If the " +"<_:link-1/> specifies that a particular numbered version of this License <_:" +"quote-2/> applies to it, you have the option of following the terms and " +"conditions either of that specified version or of any later version that has " +"been published (not as a draft) by the Free Software Foundation. If the " +"Document does not specify a version number of this License, you may choose " +"any version ever published (not as a draft) by the Free Software Foundation." +msgstr "" +"Varje version av licensen ges ett unikt versionsnummer. Om <_:link-1/> " +"stadgar att en specifik numrerad version av denna licens <_:quote-2/> gäller " +"för det, så äger du rätten att följa villkoren enligt antingen den angivna " +"versionen eller vilken senare version som helst som publicerats (inte som " +"utkast) av Free Software Foundation. Om dokumentet inte anger en version av " +"denna licens, äger du välja vilken version som helst som publicerats (inte " +"som utkast) av Free Software Foundation." + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:639 C/fdl-appendix.xml:651 +msgid "Front-Cover Texts" +msgstr "Front-Cover Texts" + +#. (itstool) path: para/link +#: C/fdl-appendix.xml:640 C/fdl-appendix.xml:654 +msgid "Back-Cover Texts" +msgstr "Back-Cover Texts" + +# <_:link-1/> blir "oföränderliga avsnitten" +#. (itstool) path: blockquote/para +#: C/fdl-appendix.xml:632 +msgid "" +"Permission is granted to copy, distribute and/or modify this document under " +"the terms of the GNU Free Documentation License, Version 1.1 or any later " +"version published by the Free Software Foundation; with the <_:link-1/> " +"being LIST THEIR TITLES, with the <_:link-2/> being LIST, and with the <_:" +"link-3/> being LIST. A copy of the license is included in the section " +"entitled <_:quote-4/>." +msgstr "" +"Permission is granted to copy, distribute and/or modify this document under " +"the terms of the GNU Free Documentation License, Version 1.1 or any later " +"version published by the Free Software Foundation; with the <_:link-1/> " +"being LIST THEIR TITLES, with the <_:link-2/> being LIST, and with the <_:" +"link-3/> being LIST. A copy of the license is included in the section " +"entitled <_:quote-4/>." + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:649 +msgid "with no Invariant Sections" +msgstr "with no Invariant Sections" + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:652 +msgid "no Front-Cover Texts" +msgstr "no Front-Cover Texts" + +#. (itstool) path: para/quote +#: C/fdl-appendix.xml:653 +msgid "Front-Cover Texts being LIST" +msgstr "Front-Cover Texts being LIST" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:647 +msgid "" +"If you have no <_:link-1/>, write <_:quote-2/> instead of saying which ones " +"are invariant. If you have no <_:link-3/>, write <_:quote-4/> instead of <_:" +"quote-5/>; likewise for <_:link-6/>." +msgstr "" +"Om du inte har några <_:link-1/>, skriv <_:quote-2/> istället för att ange " +"vilka som är oföränderliga. Om du inte har några <_:link-3/>, skriv <_:" +"quote-4/> istället för <_:quote-5/>; såväl som för <_:link-6/>." + +#. (itstool) path: para/ulink +#: C/fdl-appendix.xml:661 +msgid "GNU General Public License" +msgstr "GNU General Public License" + +#. (itstool) path: sect1/para +#: C/fdl-appendix.xml:657 +msgid "" +"If your document contains nontrivial examples of program code, we recommend " +"releasing these examples in parallel under your choice of free software " +"license, such as the <_:ulink-1/>, to permit their use in free software." +msgstr "" +"Om ditt dokument innehåller icke-triviala exempel med programkod, så " +"rekommenderar vi att du släpper dessa exempel parallellt under en, av dig " +"vald, fri programvarulicens, som till exempel <_:ulink-1/>, för att " +"möjliggöra deras användning i fri programvara." + +#~ msgid "" +#~ "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 "" +#~ "Generera ”mall”-filerna. gtkdoc-mktmpl skapar ett antal filer i underkatalogen tmpl/, från information som samlats ihop i det " +#~ "första steget. (Notera att detta kan köras upprepade gånger. Det kommer " +#~ "att försöka att säkerställa att ingen dokumentation någonsin går " +#~ "förlorad.)" + +#~ msgid "" +#~ "Since GTK-Doc 1.9 the templates can be avoided. We encourage people to " +#~ "keep documentation in the code. 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 "" +#~ "Sedan GTK-Doc 1.9 kan mallar undvikas. Vi rekommenderar att hålla " +#~ "dokumentationen i koden. gtkdocize har nu stöd " +#~ "för flaggan som väljer en makefil som " +#~ "helt hoppar över tmpl-användning. Om du inte ändrat i någon fil i tmpl " +#~ "för hand, ta bort katalogen (t.ex. från versionshanteringssystemet)." + +#~ msgid "1.12" +#~ msgstr "1.12" + +#~ msgid "Chris" +#~ msgstr "Chris" + +#~ msgid "Lyttle" +#~ msgstr "Lyttle" + +#~ msgid "chris@wilddev.net" +#~ msgstr "chris@wilddev.net" + +#~ msgid "Dan" +#~ msgstr "Dan" + +#~ msgid "Mueth" +#~ msgstr "Mueth" + +#~ msgid "d-mueth@uchicago.edu" +#~ msgstr "d-mueth@uchicago.edu" + +#~ msgid "Stefan" +#~ msgstr "Stefan" + +#~ msgid "Kost" +#~ msgstr "Kost" + +#~ msgid "ensonic@users.sf.net" +#~ msgstr "ensonic@users.sf.net" + +#~ msgid "gtk-doc-list@gnome.org" +#~ msgstr "gtk-doc-list@gnome.org" + +#~ msgid "2000, 2005, 2007-2009" +#~ msgstr "2000, 2005, 2007-2009" + +#~ msgid "Dan Mueth and Chris Lyttle and Stefan Kost" +#~ msgstr "Dan Mueth, Chris Lyttle och Stefan Kost" + +#~ msgid "1.11" +#~ msgstr "1.11" + +#~ msgid "22 March 2008" +#~ msgstr "22 mars 2008" + +#~ msgid "mal" +#~ msgstr "mal" + +#~ msgid "explanation" +#~ msgstr "förklaring" diff --git a/help/manual/ta/index.docbook b/help/manual/ta/index.docbook index f208377..2ecdb95 100644 --- a/help/manual/ta/index.docbook +++ b/help/manual/ta/index.docbook @@ -68,10 +68,16 @@ - 1.24.1 - 30 May 2015 + 1.25.1 + 21 March 2016 + ss + development version + + + 1.25 + 21 March 2016 ss - development version + bug fixes, test cleanups 1.24 @@ -219,27 +225,6 @@ - - - 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.) - - - - 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). - - - - Generating the XML and HTML/PDF. @@ -257,7 +242,7 @@ document called <package>.pdf. - Files in xml/ and + Files in xml/ and html/ directories are always overwritten. One should never edit them directly. @@ -397,7 +382,12 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) ஜிடிகே டாக் GTK-Doc முன்னிருப்பாக செயலிழந்து இருக்கும்! ஆகவே அடுத்த configure இயக்கத்துக்கு இந்த தேர்வை செய்க: . இல்லையானால் முன் உருவாக்கிய ஆவணங்கள் நிறூவப்படும்.( இது பயனர்களுக்கு புரியும், நல்லது. ஆனால் உருவாக்குவோருக்கு அல்ல). - மேலும் பின் வரும் வரியை உங்கள் configure.ac குறுநிரலில் அமைத்துக்கொள்க. இது gtkdocize நிரலை தானியங்கியாக GTK_DOC_CHECK இன் மேக்ரோ அறிதியீட்டை உங்கள் திட்டத்துக்கு பிரதி எடுக்கிறது. + + 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. + gtkdocize க்கு முன்னேற்பாடு @@ -417,12 +407,12 @@ AC_CONFIG_MACRO_DIR(m4) ஆட்டோமேக் உடன் ஒருங்கிணைப்பு - First copy the Makefile.am from the + 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. + 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. @@ -606,7 +596,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html The scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + hint GTK-Doc to skip over them. GTK-Doc comment block Limitations Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not + #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations. @@ -747,7 +737,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + XML tags inside doc-comments by putting (or ) in the variable MKDB_OPTIONS inside Makefile.am. @@ -831,7 +821,12 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html SECTION:<பெயர்> - பகுதி ஆவணத்தை பெயர் <package>-sections.txtகோப்புக்கு இணைக்கிறது. கொடுக்கப்பட்ட பெயர் <package>-sections.txt கோப்பில் <FILE> குறிப்புடன் பொருந்த வேண்டும். + + The name links the section documentation to the respective part in + the <package>-sections.txt file. The + name given here should match the <FILE> tag in the + <package>-sections.txt file. + @@ -1053,7 +1048,7 @@ foo_get_bar(Foo *foo) Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list - of the supported tags can be found on + of the supported tags can be found on the wiki. @@ -1271,6 +1266,111 @@ typedef enum { + + + Inline program documentation + + You can document programs and their commandline interface using inline + documentation. + + + + Tags + + PROGRAM + + + + Defines the start of a program documentation. + + + + + + @short_description: + + + Defines a short description of the program. (Optional) + + + + + + @synopsis: + + + Defines the arguments, or list of arguments that the program can take. + (Optional) + + + + + + @see_also: + + + See Also manual page section. (Optional) + + + + + + @arg: + + + Argument(s) passed to the program and their description. (Optional) + + + + + + Description: + + + A longer description of the program. + + + + + + திருப்பிகிடைப்பவை: + + + Specificy what value(s) the program returns. (Optional) + + + + + + + + Example of program documentation. + Program documentation block + + + + + + Useful DocBook tags @@ -1529,17 +1629,17 @@ gtk_arrow_get_type In addition a few option elements are created in commented form. You can review these and enable them as you like. - + Optional part in the master document - --> + --> ]]> - + Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will @@ -1570,7 +1670,7 @@ gtk_arrow_get_type Blank lines are ignored and lines starting with a '#' are treated as comment lines. - + While the tags make the file look like xml, it is not. Please do not @@ -1697,15 +1797,15 @@ meep_app_get_type GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizing the documentation - + 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. - + GTK-Doc 1.9 @@ -1713,7 +1813,7 @@ meep_app_get_type When using xml instead of sgml, one can actually name the master document <package>-docs.xml. - + This version supports in Makefile.am. When this is enabled, the @@ -1721,21 +1821,21 @@ meep_app_get_type can be removed from the vcs. This only works nicely for projects that have a very regular structure (e.g. each .{c,h} pair will create new section). If one organize a project close to that updating a manually - maintained section file can be as simple as running + maintained section file can be as simple as running meld <package>-decl-list.txt <package>-sections.txt. - + 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 you source control system and haven't yet switched, just + checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. - + GTK-Doc 1.10 @@ -1788,7 +1888,7 @@ endif 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 any example that shows how the entity file is included + number. Below is an example that shows how the entity file is included and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. diff --git a/help/manual/te/index.docbook b/help/manual/te/index.docbook index 5ccd31c..b2397eb 100644 --- a/help/manual/te/index.docbook +++ b/help/manual/te/index.docbook @@ -68,10 +68,16 @@ - 1.24.1 - 30 May 2015 + 1.25.1 + 21 March 2016 + ss + development version + + + 1.25 + 21 March 2016 ss - development version + bug fixes, test cleanups 1.24 @@ -219,27 +225,6 @@ - - - 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.) - - - - 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). - - - - Generating the XML and HTML/PDF. @@ -257,7 +242,7 @@ document called <package>.pdf. - Files in xml/ and + Files in xml/ and html/ directories are always overwritten. One should never edit them directly. @@ -395,7 +380,12 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) GTK-Doc అప్రమేయంగా అచేతనము చేయబడింది! ఐచ్చికము ను తరువాతి configureకు నడుపుట మర్చిపోవద్దు. లేకపోతే ముందుగా జనియింపచేసిన పత్రికీకరణ సంస్థాపించబడుతుంది (ఇది వినియోగదారులకు వుపయోగకరం అయితే అభివృద్దికారులకు కాదు). - మీ configure.ac స్క్రిప్టునందు ఈ క్రింది వరుసను కలిగివుండుట చాలామంచిది. ఇది మీ ప్రోజెక్టునందు GTK_DOC_CHECK కొరకు స్వయంచాలకంగా మాక్రో నిర్వచనాన్ని నకలు తీయుటకు gtkdocizeను అనుమతిస్తుంది. + + 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. + gtkdocize కొరకు సన్నాహం @@ -415,12 +405,12 @@ AC_CONFIG_MACRO_DIR(m4) automake తో విలీనం - First copy the Makefile.am from the + 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. + 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. @@ -604,7 +594,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html The scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + hint GTK-Doc to skip over them. GTK-Doc comment block Limitations Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not + #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations. @@ -745,7 +735,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + XML tags inside doc-comments by putting (or ) in the variable MKDB_OPTIONS inside Makefile.am. @@ -829,7 +819,12 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html SECTION:<name> - నామము అనునది విభాగపు పత్రికీకరణను <package>-sections.txt ఫైలునందలి సంభందిత భాగమునకు లింకుచేయును. ఇక్కడ యిచ్చిన నామము <package>-sections.txt ఫైలునందలి <FILE> టాగ్‌తో సరిపోలవలెను. + + The name links the section documentation to the respective part in + the <package>-sections.txt file. The + name given here should match the <FILE> tag in the + <package>-sections.txt file. + @@ -1033,7 +1028,7 @@ foo_get_bar(Foo *foo) Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list - of the supported tags can be found on + of the supported tags can be found on the wiki. @@ -1243,6 +1238,111 @@ typedef enum { + + + Inline program documentation + + You can document programs and their commandline interface using inline + documentation. + + + + Tags + + PROGRAM + + + + Defines the start of a program documentation. + + + + + + @short_description: + + + Defines a short description of the program. (Optional) + + + + + + @synopsis: + + + Defines the arguments, or list of arguments that the program can take. + (Optional) + + + + + + @see_also: + + + See Also manual page section. (Optional) + + + + + + @arg: + + + Argument(s) passed to the program and their description. (Optional) + + + + + + Description: + + + A longer description of the program. + + + + + + తిరిగివచ్చినవి: + + + Specificy what value(s) the program returns. (Optional) + + + + + + + + Example of program documentation. + Program documentation block + + + + + + ఉపయోగకర DocBook టాగ్స్ @@ -1502,17 +1602,17 @@ gtk_arrow_get_type In addition a few option elements are created in commented form. You can review these and enable them as you like. - + Optional part in the master document - --> + --> ]]> - + Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will @@ -1547,7 +1647,7 @@ gtk_arrow_get_type Blank lines are ignored and lines starting with a '#' are treated as comment lines. - + While the tags make the file look like xml, it is not. Please do not @@ -1690,15 +1790,15 @@ meep_app_get_type GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizing the documentation - + 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. - + GTK-Doc 1.9 @@ -1706,7 +1806,7 @@ meep_app_get_type When using xml instead of sgml, one can actually name the master document <package>-docs.xml. - + This version supports in Makefile.am. When this is enabled, the @@ -1714,21 +1814,21 @@ meep_app_get_type can be removed from the vcs. This only works nicely for projects that have a very regular structure (e.g. each .{c,h} pair will create new section). If one organize a project close to that updating a manually - maintained section file can be as simple as running + maintained section file can be as simple as running meld <package>-decl-list.txt <package>-sections.txt. - + 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 you source control system and haven't yet switched, just + checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. - + GTK-Doc 1.10 @@ -1781,7 +1881,7 @@ endif 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 any example that shows how the entity file is included + number. Below is an example that shows how the entity file is included and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. diff --git a/help/manual/zh_CN/index.docbook b/help/manual/zh_CN/index.docbook index 5025288..13d0a88 100644 --- a/help/manual/zh_CN/index.docbook +++ b/help/manual/zh_CN/index.docbook @@ -46,10 +46,16 @@ - 1.24.1 - 30 May 2015 + 1.25.1 + 21 March 2016 + ss + development version + + + 1.25 + 21 March 2016 ss - development version + bug fixes, test cleanups 1.24 @@ -212,27 +218,6 @@ - - - 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.) - - - - 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). - - - - Generating the XML and HTML/PDF. @@ -250,7 +235,7 @@ document called <package>.pdf. - Files in xml/ and + Files in xml/ and html/ directories are always overwritten. One should never edit them directly. @@ -409,7 +394,12 @@ AM_CONDITIONAL([ENABLE_GTK_DOC], false) GTK-Doc在默认情况下是关闭的！请记得给文本configure运作时传递选项。否则，将会安装预先生成的文档（对用户有意义但对开发人员没用处）。 - 而且建议你在configure.ac脚本里拥有这样一行。它允许gtkdocize将GTK_DOC_CHECK的宏定义复制到您的项目中去。 + + 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. + 准备gtkdocize @@ -429,12 +419,12 @@ AC_CONFIG_MACRO_DIR(m4) 与automake集成 - First copy the Makefile.am from the + 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. + 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. @@ -631,7 +621,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html The scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can - hint GTK-Doc to skip over them. + hint GTK-Doc to skip over them. GTK-Doc comment block Limitations Note, that GTK-Doc's supports - #ifndef(__GTK_DOC_IGNORE__) but not + #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations. @@ -761,7 +751,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html 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 + XML tags inside doc-comments by putting (or ) in the variable MKDB_OPTIONS inside Makefile.am. @@ -845,7 +835,12 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html SECTION:<name> - 名字链接这节文档到文件<package>-sections.txt中对应的部分。这里的名字应匹配<package>-sections.txt文件中的<FILE>标识。 + + The name links the section documentation to the respective part in + the <package>-sections.txt file. The + name given here should match the <FILE> tag in the + <package>-sections.txt file. + @@ -1039,7 +1034,7 @@ foo_get_bar(Foo *foo) Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list - of the supported tags can be found on + of the supported tags can be found on the wiki. @@ -1215,6 +1210,111 @@ typedef enum { + + + Inline program documentation + + You can document programs and their commandline interface using inline + documentation. + + + + Tags + + PROGRAM + + + + Defines the start of a program documentation. + + + + + + @short_description: + + + Defines a short description of the program. (Optional) + + + + + + @synopsis: + + + Defines the arguments, or list of arguments that the program can take. + (Optional) + + + + + + @see_also: + + + See Also manual page section. (Optional) + + + + + + @arg: + + + Argument(s) passed to the program and their description. (Optional) + + + + + + Description: + + + A longer description of the program. + + + + + + 返回值： + + + Specificy what value(s) the program returns. (Optional) + + + + + + + + Example of program documentation. + Program documentation block + + + + + + 有用的DocBook标记 @@ -1406,17 +1506,17 @@ gtk_arrow_get_type In addition a few option elements are created in commented form. You can review these and enable them as you like. - + Optional part in the master document - --> + --> ]]> - + Finally you need to add new section whenever you introduce one. The gtkdoc-check tool will @@ -1447,7 +1547,7 @@ gtk_arrow_get_type Blank lines are ignored and lines starting with a '#' are treated as comment lines. - + While the tags make the file look like xml, it is not. Please do not @@ -1585,15 +1685,15 @@ meep_app_get_type GTK_DOC_KEEP_INTERMEDIATE=1 make. - + Modernizing the documentation - + 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. - + GTK-Doc 1.9 @@ -1601,7 +1701,7 @@ meep_app_get_type When using xml instead of sgml, one can actually name the master document <package>-docs.xml. - + This version supports in Makefile.am. When this is enabled, the @@ -1609,21 +1709,21 @@ meep_app_get_type can be removed from the vcs. This only works nicely for projects that have a very regular structure (e.g. each .{c,h} pair will create new section). If one organize a project close to that updating a manually - maintained section file can be as simple as running + maintained section file can be as simple as running meld <package>-decl-list.txt <package>-sections.txt. - + 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 you source control system and haven't yet switched, just + checked into your source control system and haven't yet switched, just add the flag to configure.ac and you are done. - + GTK-Doc 1.10 @@ -1676,7 +1776,7 @@ endif 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 any example that shows how the entity file is included + number. Below is an example that shows how the entity file is included and how the entities are used. The entities can also be used in all generated files, GTK-Doc will use the same xml header in generated xml files. diff --git a/tests/Makefile.am b/tests/Makefile.am index 7e23744..b376e58 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -1,26 +1,25 @@ ## Process this file with automake to produce Makefile.in -SUBDIRS = gobject bugs annotations fail empty . +SUBDIRS = gobject bugs annotations fail empty program . if BUILD_TESTS TESTS = \ - gtkdoc-common.t gtkdoc-fixxref.t gtkdoc-mkdb.t gtkdoc-rebase.t gtkdoc-scan.t \ - tools.sh gobject.sh bugs.sh annotations.sh fail.sh empty.sh sanity.sh + check.py common.py mk_to_db.py \ + tools.sh gobject.sh bugs.sh annotations.sh fail.sh empty.sh sanity.sh \ + program.sh TESTS_ENVIRONMENT = \ BUILDDIR=$(abs_builddir) \ SRCDIR=$(abs_srcdir) \ ABS_TOP_BUILDDIR=$(abs_top_builddir) \ ABS_TOP_SRCDIR=$(abs_top_srcdir) \ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ - PERL5LIB=$(abs_top_builddir):$(PERL5LIB) + PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ + GLIB_PREFIX="$(glib_prefix)" endif -EXTRA_DIST = gtkdoctest.sh tools.sh sanity.sh \ - gobject.sh bugs.sh annotations.sh fail.sh empty.sh \ - gtkdoc-common.t gtkdoc-fixxref.t gtkdoc-mkdb.t gtkdoc-rebase.t gtkdoc-scan.t - +EXTRA_DIST = gtkdoctest.sh $(TESTS) # run any given test by running make .check %.check: % diff --git a/tests/Makefile.in b/tests/Makefile.in index 0d659cc..e5f0494 100644 --- a/tests/Makefile.in +++ b/tests/Makefile.in @@ -441,12 +441,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ @@ -523,10 +523,11 @@ target_alias = @target_alias@ top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ -SUBDIRS = gobject bugs annotations fail empty . +SUBDIRS = gobject bugs annotations fail empty program . @BUILD_TESTS_TRUE@TESTS = \ -@BUILD_TESTS_TRUE@ gtkdoc-common.t gtkdoc-fixxref.t gtkdoc-mkdb.t gtkdoc-rebase.t gtkdoc-scan.t \ -@BUILD_TESTS_TRUE@ tools.sh gobject.sh bugs.sh annotations.sh fail.sh empty.sh sanity.sh +@BUILD_TESTS_TRUE@ check.py common.py mk_to_db.py \ +@BUILD_TESTS_TRUE@ tools.sh gobject.sh bugs.sh annotations.sh fail.sh empty.sh sanity.sh \ +@BUILD_TESTS_TRUE@ program.sh @BUILD_TESTS_TRUE@TESTS_ENVIRONMENT = \ @BUILD_TESTS_TRUE@ BUILDDIR=$(abs_builddir) \ @@ -534,12 +535,10 @@ SUBDIRS = gobject bugs annotations fail empty . @BUILD_TESTS_TRUE@ ABS_TOP_BUILDDIR=$(abs_top_builddir) \ @BUILD_TESTS_TRUE@ ABS_TOP_SRCDIR=$(abs_top_srcdir) \ @BUILD_TESTS_TRUE@ PATH=$(abs_top_builddir):$(srcdir):$(PATH) \ -@BUILD_TESTS_TRUE@ PERL5LIB=$(abs_top_builddir):$(PERL5LIB) - -EXTRA_DIST = gtkdoctest.sh tools.sh sanity.sh \ - gobject.sh bugs.sh annotations.sh fail.sh empty.sh \ - gtkdoc-common.t gtkdoc-fixxref.t gtkdoc-mkdb.t gtkdoc-rebase.t gtkdoc-scan.t +@BUILD_TESTS_TRUE@ PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ +@BUILD_TESTS_TRUE@ GLIB_PREFIX="$(glib_prefix)" +EXTRA_DIST = gtkdoctest.sh $(TESTS) all: all-recursive .SUFFIXES: @@ -823,37 +822,23 @@ recheck: all am__force_recheck=am--force-recheck \ TEST_LOGS="$$log_list"; \ exit $$? -gtkdoc-common.t.log: gtkdoc-common.t - @p='gtkdoc-common.t'; \ - b='gtkdoc-common.t'; \ +check.py.log: check.py + @p='check.py'; \ + b='check.py'; \ $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \ --log-file $$b.log --trs-file $$b.trs \ $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ "$$tst" $(AM_TESTS_FD_REDIRECT) -gtkdoc-fixxref.t.log: gtkdoc-fixxref.t - @p='gtkdoc-fixxref.t'; \ - b='gtkdoc-fixxref.t'; \ +common.py.log: common.py + @p='common.py'; \ + b='common.py'; \ $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \ --log-file $$b.log --trs-file $$b.trs \ $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ "$$tst" $(AM_TESTS_FD_REDIRECT) -gtkdoc-mkdb.t.log: gtkdoc-mkdb.t - @p='gtkdoc-mkdb.t'; \ - b='gtkdoc-mkdb.t'; \ - $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \ - --log-file $$b.log --trs-file $$b.trs \ - $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ - "$$tst" $(AM_TESTS_FD_REDIRECT) -gtkdoc-rebase.t.log: gtkdoc-rebase.t - @p='gtkdoc-rebase.t'; \ - b='gtkdoc-rebase.t'; \ - $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \ - --log-file $$b.log --trs-file $$b.trs \ - $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ - "$$tst" $(AM_TESTS_FD_REDIRECT) -gtkdoc-scan.t.log: gtkdoc-scan.t - @p='gtkdoc-scan.t'; \ - b='gtkdoc-scan.t'; \ +mk_to_db.py.log: mk_to_db.py + @p='mk_to_db.py'; \ + b='mk_to_db.py'; \ $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \ --log-file $$b.log --trs-file $$b.trs \ $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ @@ -907,6 +892,13 @@ sanity.sh.log: sanity.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) +program.sh.log: program.sh + @p='program.sh'; \ + b='program.sh'; \ + $(am__check_pre) $(LOG_DRIVER) --test-name "$$f" \ + --log-file $$b.log --trs-file $$b.trs \ + $(am__common_driver_flags) $(AM_LOG_DRIVER_FLAGS) $(LOG_DRIVER_FLAGS) -- $(LOG_COMPILE) \ + "$$tst" $(AM_TESTS_FD_REDIRECT) .test.log: @p='$<'; \ $(am__set_b); \ diff --git a/tests/annotations/Makefile.in b/tests/annotations/Makefile.in index d143517..716de73 100644 --- a/tests/annotations/Makefile.in +++ b/tests/annotations/Makefile.in @@ -237,12 +237,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ diff --git a/tests/annotations/docs/Makefile.am b/tests/annotations/docs/Makefile.am index 416b678..7f8a752 100644 --- a/tests/annotations/docs/Makefile.am +++ b/tests/annotations/docs/Makefile.am @@ -24,10 +24,6 @@ SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ # Extra options to supply to gtkdoc-mkdb. MKDB_OPTIONS=--xml-mode -# Extra options to supply to gtkdoc-mktmpl -# e.g. MKTMPL_OPTIONS=--only-section-tmpl -MKTMPL_OPTIONS= - # Extra options to supply to gtkdoc-mkhtml MKHTML_OPTIONS= @@ -61,7 +57,7 @@ GTKDOC_CFLAGS = -I$(top_srcdir)/tests/annotations/src $(TEST_DEPS_CFLAGS) GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/annotations/src/libtester.la # include generic part -include $(top_srcdir)/tests/gtk-doc.notmpl.make +include $(top_srcdir)/tests/gtk-doc.make # Other files to distribute # e.g. EXTRA_DIST += version.xml.in diff --git a/tests/annotations/docs/Makefile.in b/tests/annotations/docs/Makefile.in index db8410a..ac7e01c 100644 --- a/tests/annotations/docs/Makefile.in +++ b/tests/annotations/docs/Makefile.in @@ -83,8 +83,8 @@ PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ -DIST_COMMON = $(top_srcdir)/tests/gtk-doc.notmpl.make \ - $(srcdir)/Makefile.in $(srcdir)/Makefile.am +DIST_COMMON = $(top_srcdir)/tests/gtk-doc.make $(srcdir)/Makefile.in \ + $(srcdir)/Makefile.am subdir = tests/annotations/docs ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \ @@ -184,12 +184,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ @@ -292,10 +292,6 @@ SCAN_OPTIONS = --deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ # Extra options to supply to gtkdoc-mkdb. MKDB_OPTIONS = --xml-mode -# Extra options to supply to gtkdoc-mktmpl -# e.g. MKTMPL_OPTIONS=--only-section-tmpl -MKTMPL_OPTIONS = - # Extra options to supply to gtkdoc-mkhtml MKHTML_OPTIONS = @@ -373,9 +369,8 @@ REPORT_FILES = \ CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \ $(DOC_MODULE).pdf ts gtkdoc-scan.log gtkdoc-scangobj.log \ - gtkdoc-mktmpl.log gtkdoc-mkdb.log gtkdoc-mkhtml.log \ - gtkdoc-mkpdf.log gtkdoc-fixxref.log \ - $(DOC_MODULE)-overrides.txt + gtkdoc-mkdb.log gtkdoc-mkhtml.log gtkdoc-mkpdf.log \ + gtkdoc-fixxref.log $(DOC_MODULE)-overrides.txt GITIGNOREFILES = \ html.ref xml.ref @@ -387,7 +382,7 @@ GITIGNOREFILES = \ all: all-am .SUFFIXES: -$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.notmpl.make $(am__configure_deps) +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.make $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ @@ -408,7 +403,7 @@ Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ esac; -$(top_srcdir)/tests/gtk-doc.notmpl.make: +$(top_srcdir)/tests/gtk-doc.make: $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh @@ -597,14 +592,14 @@ ts: setup-build.stamp: ts -@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - echo ' DOC Preparing build'; \ - files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ - if test "x$$files" != "x" ; then \ - for file in $$files ; do \ - test -f $(abs_srcdir)/$$file && \ - cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ - done; \ - fi; \ + echo ' DOC Preparing build'; \ + files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ + if test "x$$files" != "x" ; then \ + for file in $$files ; do \ + test -f $(abs_srcdir)/$$file && \ + cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ + done; \ + fi; \ fi @touch setup-build.stamp @@ -615,26 +610,26 @@ scan-build.stamp: ts setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files" @_source_dir='' ; \ for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log @if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ - echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ - scanobj_options=""; \ - if test "x$(V)" = "x1"; then \ - scanobj_options="--verbose"; \ - fi; \ - echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ - CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ - gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ + echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ + scanobj_options=""; \ + if test "x$(V)" = "x1"; then \ + scanobj_options="--verbose"; \ + fi; \ + echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ + gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ else \ - for i in $(SCANOBJ_FILES) ; do \ - test -f $$i || touch $$i ; \ - done \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ fi @touch scan-build.stamp @@ -651,7 +646,7 @@ sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HF _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log @touch sgml-build.stamp @@ -681,7 +676,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) mkhtml_options="$$mkhtml_options --verbose"; \ fi; \ echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \ - cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log -@test "x$(HTML_IMAGES)" = "x" || \ for file in $(HTML_IMAGES) ; do \ @@ -695,7 +690,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references" @echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log @touch html-build.stamp @@ -719,7 +714,7 @@ pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) done; \ fi; \ echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log @touch pdf-build.stamp diff --git a/tests/annotations/docs/tester-sections.txt b/tests/annotations/docs/tester-sections.txt index d3efd64..d7c1c38 100644 --- a/tests/annotations/docs/tester-sections.txt +++ b/tests/annotations/docs/tester-sections.txt @@ -19,6 +19,8 @@ annotation_skip annotation_skip_return annotation_scope annotation_rename_to +annotation_attributes_single +annotation_attributes_single_eq stability_unstable annotation_multiline_on_function annotation_multiline_on_function2 diff --git a/tests/annotations/src/Makefile.in b/tests/annotations/src/Makefile.in index 5ab1899..94ba12b 100644 --- a/tests/annotations/src/Makefile.in +++ b/tests/annotations/src/Makefile.in @@ -229,12 +229,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ diff --git a/tests/annotations/src/tester.c b/tests/annotations/src/tester.c index 4e05dc5..eeb1159 100644 --- a/tests/annotations/src/tester.c +++ b/tests/annotations/src/tester.c @@ -257,6 +257,26 @@ annotation_rename_to (void) { } +/** + * annotation_attributes_single: (attributes key value) + * + * Documentation for this function. + */ +void +annotation_attributes_single (void) +{ +} + +/** + * annotation_attributes_single_eq: (attributes key=value) + * + * Documentation for this function. + */ +void +annotation_attributes_single_eq (void) +{ +} + /** * stability_unstable: * diff --git a/tests/annotations/src/tester.h b/tests/annotations/src/tester.h index 3627e59..e3b0f78 100644 --- a/tests/annotations/src/tester.h +++ b/tests/annotations/src/tester.h @@ -38,6 +38,9 @@ void annotation_scope (GCallback *callback, gpointer user_data); void annotation_rename_to (void); +void annotation_attributes_single (void); +void annotation_attributes_single_eq (void); + void stability_unstable(void); void annotation_multiline_on_function (void); diff --git a/tests/bugs/Makefile.in b/tests/bugs/Makefile.in index 440e93b..c13617d 100644 --- a/tests/bugs/Makefile.in +++ b/tests/bugs/Makefile.in @@ -237,12 +237,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ diff --git a/tests/bugs/docs/Makefile.am b/tests/bugs/docs/Makefile.am index 852e1e9..97c4702 100644 --- a/tests/bugs/docs/Makefile.am +++ b/tests/bugs/docs/Makefile.am @@ -25,10 +25,6 @@ SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ # Extra options to supply to gtkdoc-mkdb. MKDB_OPTIONS=--xml-mode -# Extra options to supply to gtkdoc-mktmpl -# e.g. MKTMPL_OPTIONS=--only-section-tmpl -MKTMPL_OPTIONS= - # Extra options to supply to gtkdoc-mkhtml MKHTML_OPTIONS= @@ -62,7 +58,7 @@ GTKDOC_CFLAGS = -I$(top_srcdir)/tests/bugs/src $(TEST_DEPS_CFLAGS) GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/bugs/src/libtester.la # include generic part -include $(top_srcdir)/tests/gtk-doc.notmpl.make +include $(top_srcdir)/tests/gtk-doc.make # Other files to distribute # e.g. EXTRA_DIST += version.xml.in diff --git a/tests/bugs/docs/Makefile.in b/tests/bugs/docs/Makefile.in index 3b2520e..30bb872 100644 --- a/tests/bugs/docs/Makefile.in +++ b/tests/bugs/docs/Makefile.in @@ -83,8 +83,8 @@ PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ -DIST_COMMON = $(top_srcdir)/tests/gtk-doc.notmpl.make \ - $(srcdir)/Makefile.in $(srcdir)/Makefile.am +DIST_COMMON = $(top_srcdir)/tests/gtk-doc.make $(srcdir)/Makefile.in \ + $(srcdir)/Makefile.am subdir = tests/bugs/docs ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \ @@ -184,12 +184,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ @@ -293,10 +293,6 @@ SCAN_OPTIONS = --deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ # Extra options to supply to gtkdoc-mkdb. MKDB_OPTIONS = --xml-mode -# Extra options to supply to gtkdoc-mktmpl -# e.g. MKTMPL_OPTIONS=--only-section-tmpl -MKTMPL_OPTIONS = - # Extra options to supply to gtkdoc-mkhtml MKHTML_OPTIONS = @@ -374,9 +370,9 @@ REPORT_FILES = \ CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \ $(DOC_MODULE).pdf ts gtkdoc-scan.log gtkdoc-scangobj.log \ - gtkdoc-mktmpl.log gtkdoc-mkdb.log gtkdoc-mkhtml.log \ - gtkdoc-mkpdf.log gtkdoc-fixxref.log \ - $(DOC_MODULE)-overrides.txt $(DOC_MODULE).types + gtkdoc-mkdb.log gtkdoc-mkhtml.log gtkdoc-mkpdf.log \ + gtkdoc-fixxref.log $(DOC_MODULE)-overrides.txt \ + $(DOC_MODULE).types GITIGNOREFILES = \ html.ref xml.ref @@ -388,7 +384,7 @@ GITIGNOREFILES = \ all: all-am .SUFFIXES: -$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.notmpl.make $(am__configure_deps) +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.make $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ @@ -409,7 +405,7 @@ Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ esac; -$(top_srcdir)/tests/gtk-doc.notmpl.make: +$(top_srcdir)/tests/gtk-doc.make: $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh @@ -598,14 +594,14 @@ ts: setup-build.stamp: ts -@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - echo ' DOC Preparing build'; \ - files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ - if test "x$$files" != "x" ; then \ - for file in $$files ; do \ - test -f $(abs_srcdir)/$$file && \ - cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ - done; \ - fi; \ + echo ' DOC Preparing build'; \ + files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ + if test "x$$files" != "x" ; then \ + for file in $$files ; do \ + test -f $(abs_srcdir)/$$file && \ + cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ + done; \ + fi; \ fi @touch setup-build.stamp @@ -616,26 +612,26 @@ scan-build.stamp: ts setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files" @_source_dir='' ; \ for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log @if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ - echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ - scanobj_options=""; \ - if test "x$(V)" = "x1"; then \ - scanobj_options="--verbose"; \ - fi; \ - echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ - CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ - gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ + echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ + scanobj_options=""; \ + if test "x$(V)" = "x1"; then \ + scanobj_options="--verbose"; \ + fi; \ + echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ + gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ else \ - for i in $(SCANOBJ_FILES) ; do \ - test -f $$i || touch $$i ; \ - done \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ fi @touch scan-build.stamp @@ -652,7 +648,7 @@ sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HF _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log @touch sgml-build.stamp @@ -682,7 +678,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) mkhtml_options="$$mkhtml_options --verbose"; \ fi; \ echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \ - cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log -@test "x$(HTML_IMAGES)" = "x" || \ for file in $(HTML_IMAGES) ; do \ @@ -696,7 +692,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references" @echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log @touch html-build.stamp @@ -720,7 +716,7 @@ pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) done; \ fi; \ echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log @touch pdf-build.stamp diff --git a/tests/bugs/docs/tester-sections.txt b/tests/bugs/docs/tester-sections.txt index ca23ab0..fe1013c 100644 --- a/tests/bugs/docs/tester-sections.txt +++ b/tests/bugs/docs/tester-sections.txt @@ -70,6 +70,7 @@ bug_749142 deprecation_notice bug_741941 bug_732689 +bug_783420 gst_play_marshal_BUFFER__BOXED diff --git a/tests/bugs/src/Makefile.in b/tests/bugs/src/Makefile.in index 4ebd0d4..964f12b 100644 --- a/tests/bugs/src/Makefile.in +++ b/tests/bugs/src/Makefile.in @@ -229,12 +229,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ diff --git a/tests/bugs/src/tester.c b/tests/bugs/src/tester.c index 94235bd..cc87ff5 100644 --- a/tests/bugs/src/tester.c +++ b/tests/bugs/src/tester.c @@ -115,14 +115,6 @@ G_CONST_RETURN gchar* G_CONST_RETURN * bug_471014 (void) { } -/** - * Bug446648: - * @BUG_446648_FOO: foo - * - * http://bugzilla.gnome.org/show_bug.cgi?id=446648 - **/ - - /** * bug_552602: * @@ -469,3 +461,35 @@ void bug_749142 (void) { } + +/** + * bug_783420: + * @in: input + * @out: output + * + * http://bugzilla.gnome.org/show_bug.cgi?id=783420 + * + * |[ + * #include + * + * int res; + * bug_783420(42, &res); + * ]| + * + * + * Subsection + * + * Lorem ipsum ... + * |[ + * #include + * + * int res; + * bug_783420(42, &res); + * ]| + * + * + */ +void +bug_783420 (int in, int *out) +{ +} \ No newline at end of file diff --git a/tests/bugs/src/tester.h b/tests/bugs/src/tester.h index 00e5826..4958374 100644 --- a/tests/bugs/src/tester.h +++ b/tests/bugs/src/tester.h @@ -115,7 +115,7 @@ const char* const * bug_552602 (void); /** * Bug446648: - * @BUG_446648_FOO: field + * @BUG_446648_FOO: foo * * http://bugzilla.gnome.org/show_bug.cgi?id=446648 */ @@ -506,6 +506,7 @@ void bug_741941(void *object, void *par) G_GNUC_NONNULL(1) G_GNUC_NONNULL(2); void bug_732689 (const gchar *spec); void bug_749142 (void); +void bug_783420 (int in, int *out); /** * BUG_731417_DEPRECATED: @@ -544,4 +545,12 @@ typedef enum */ #define MACRO_FUNCTION(x) (x << 1) +/** + * _: + * @str: a string + * + * https://bugzilla.gnome.org/show_bug.cgi?id=753052 + */ +#define _(str) str + #endif // GTKDOC_TESTER_H diff --git a/tests/check.py b/tests/check.py new file mode 100755 index 0000000..e6f12b5 --- /dev/null +++ b/tests/check.py @@ -0,0 +1,52 @@ +#!/usr/bin/env python +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2017 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import unittest + +from gtkdoc import check + + +class TestCheck(unittest.TestCase): + + def test_grep_finds_token_in_one_line(self): + result = check.grep(r'^(foo)', ['foo'], 'foo') + self.assertEqual('foo', result) + + def test_grep_does_not_find_token(self): + with self.assertRaises(check.FileFormatError) as ctx: + check.grep(r'^(foo)', ['bar'], 'foo') + self.assertEqual(str(ctx.exception), 'foo') + + def test_get_variable_prefers_env(self): + result = check.get_variable({'foo': 'bar'}, ['foo=baz'], 'foo') + self.assertEqual('bar', result) + + def test_get_variable_finds_in_file(self): + result = check.get_variable({}, ['foo=bar'], 'foo') + self.assertEqual('bar', result) + + def test_get_variable_finds_in_file_with_whitespce(self): + result = check.get_variable({}, ['foo = bar'], 'foo') + self.assertEqual('bar', result) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/common.py b/tests/common.py new file mode 100755 index 0000000..3f78220 --- /dev/null +++ b/tests/common.py @@ -0,0 +1,70 @@ +#!/usr/bin/env python +#!/usr/bin/env python +# -*- python -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2017 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import mock +import unittest + +from gtkdoc import common + + +class TestUpdateFileIfChanged(unittest.TestCase): + + @mock.patch('os.path.exists') + @mock.patch('os.rename') + def test_NoOldFile(self, os_rename, os_path_exists): + os_path_exists.return_value = False + res = common.UpdateFileIfChanged('/old', '/new', False) + os_rename.assert_called_with('/new', '/old') + self.assertTrue(res) + + @mock.patch('os.path.exists') + @mock.patch('__builtin__.open', mock.mock_open(read_data='bar')) + @mock.patch('os.unlink') + def test_FilesAreTheSame(self, os_unlink, os_path_exists): + os_path_exists.return_value = True + res = common.UpdateFileIfChanged('/old', '/new', False) + os_unlink.assert_called_with('/new') + self.assertFalse(res) + + +class TestGetModuleDocDir(unittest.TestCase): + + @mock.patch('subprocess.check_output') + def test_ReturnsPath(self, subprocess_check_output): + subprocess_check_output.return_value = '/usr' + self.assertEquals(common.GetModuleDocDir('glib-2.0'), '/usr/share/gtk-doc/html') + + +class TestCreateValidSGMLID(unittest.TestCase): + + def test_AlreadyValid(self): + self.assertEquals(common.CreateValidSGMLID('x'), 'x') + + def test_SpecialCharsBecomeDash(self): + self.assertEquals(common.CreateValidSGMLID('x_ y'), 'x--y') + + def test_SpecialCharsGetRemoved(self): + self.assertEquals(common.CreateValidSGMLID('x,;y'), 'xy') + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/empty/Makefile.in b/tests/empty/Makefile.in index 6051ad2..7eb0204 100644 --- a/tests/empty/Makefile.in +++ b/tests/empty/Makefile.in @@ -237,12 +237,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ diff --git a/tests/empty/docs/Makefile.am b/tests/empty/docs/Makefile.am index 7c183af..4733cb3 100644 --- a/tests/empty/docs/Makefile.am +++ b/tests/empty/docs/Makefile.am @@ -30,10 +30,6 @@ SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ # Extra options to supply to gtkdoc-mkdb. MKDB_OPTIONS=--xml-mode -# Extra options to supply to gtkdoc-mktmpl -# e.g. MKTMPL_OPTIONS=--only-section-tmpl -MKTMPL_OPTIONS= - # Extra options to supply to gtkdoc-mkhtml MKHTML_OPTIONS= @@ -67,7 +63,7 @@ GTKDOC_CFLAGS = -I$(top_srcdir)/tests/empty/src $(TEST_DEPS_CFLAGS) GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/empty/src/libtester.la # include generic part -include $(top_srcdir)/tests/gtk-doc.notmpl.make +include $(top_srcdir)/tests/gtk-doc.make # Other files to distribute # e.g. EXTRA_DIST += version.xml.in diff --git a/tests/empty/docs/Makefile.in b/tests/empty/docs/Makefile.in index c39c9a4..8cb0c66 100644 --- a/tests/empty/docs/Makefile.in +++ b/tests/empty/docs/Makefile.in @@ -83,8 +83,8 @@ PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ -DIST_COMMON = $(top_srcdir)/tests/gtk-doc.notmpl.make \ - $(srcdir)/Makefile.in $(srcdir)/Makefile.am +DIST_COMMON = $(top_srcdir)/tests/gtk-doc.make $(srcdir)/Makefile.in \ + $(srcdir)/Makefile.am subdir = tests/empty/docs ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \ @@ -184,12 +184,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ @@ -298,10 +298,6 @@ SCAN_OPTIONS = --deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ # Extra options to supply to gtkdoc-mkdb. MKDB_OPTIONS = --xml-mode -# Extra options to supply to gtkdoc-mktmpl -# e.g. MKTMPL_OPTIONS=--only-section-tmpl -MKTMPL_OPTIONS = - # Extra options to supply to gtkdoc-mkhtml MKHTML_OPTIONS = @@ -379,10 +375,9 @@ REPORT_FILES = \ CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \ $(DOC_MODULE).pdf ts gtkdoc-scan.log gtkdoc-scangobj.log \ - gtkdoc-mktmpl.log gtkdoc-mkdb.log gtkdoc-mkhtml.log \ - gtkdoc-mkpdf.log gtkdoc-fixxref.log \ - $(DOC_MODULE)-overrides.txt $(DOC_MODULE).types \ - tester-docs.xml tester-sections.txt + gtkdoc-mkdb.log gtkdoc-mkhtml.log gtkdoc-mkpdf.log \ + gtkdoc-fixxref.log $(DOC_MODULE)-overrides.txt \ + $(DOC_MODULE).types tester-docs.xml tester-sections.txt GITIGNOREFILES = \ html.ref xml.ref @@ -394,7 +389,7 @@ GITIGNOREFILES = \ all: all-am .SUFFIXES: -$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.notmpl.make $(am__configure_deps) +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.make $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ @@ -415,7 +410,7 @@ Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ esac; -$(top_srcdir)/tests/gtk-doc.notmpl.make: +$(top_srcdir)/tests/gtk-doc.make: $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh @@ -604,14 +599,14 @@ ts: setup-build.stamp: ts -@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - echo ' DOC Preparing build'; \ - files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ - if test "x$$files" != "x" ; then \ - for file in $$files ; do \ - test -f $(abs_srcdir)/$$file && \ - cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ - done; \ - fi; \ + echo ' DOC Preparing build'; \ + files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ + if test "x$$files" != "x" ; then \ + for file in $$files ; do \ + test -f $(abs_srcdir)/$$file && \ + cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ + done; \ + fi; \ fi @touch setup-build.stamp @@ -622,26 +617,26 @@ scan-build.stamp: ts setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files" @_source_dir='' ; \ for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log @if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ - echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ - scanobj_options=""; \ - if test "x$(V)" = "x1"; then \ - scanobj_options="--verbose"; \ - fi; \ - echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ - CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ - gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ + echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ + scanobj_options=""; \ + if test "x$(V)" = "x1"; then \ + scanobj_options="--verbose"; \ + fi; \ + echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ + gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ else \ - for i in $(SCANOBJ_FILES) ; do \ - test -f $$i || touch $$i ; \ - done \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ fi @touch scan-build.stamp @@ -658,7 +653,7 @@ sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HF _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log @touch sgml-build.stamp @@ -688,7 +683,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) mkhtml_options="$$mkhtml_options --verbose"; \ fi; \ echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \ - cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log -@test "x$(HTML_IMAGES)" = "x" || \ for file in $(HTML_IMAGES) ; do \ @@ -702,7 +697,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references" @echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log @touch html-build.stamp @@ -726,7 +721,7 @@ pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) done; \ fi; \ echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log @touch pdf-build.stamp diff --git a/tests/empty/docs/tester-docs.xml b/tests/empty/docs/tester-docs.xml index b9f72de..6531a77 100644 --- a/tests/empty/docs/tester-docs.xml +++ b/tests/empty/docs/tester-docs.xml @@ -33,6 +33,10 @@ Index of deprecated API + + Index of new API in 0.1 + + diff --git a/tests/empty/docs/tester-sections.txt b/tests/empty/docs/tester-sections.txt index 1291fb4..ef56f8f 100644 --- a/tests/empty/docs/tester-sections.txt +++ b/tests/empty/docs/tester-sections.txt @@ -1,6 +1,7 @@
tester GtkDocTestIf +FOO test GtkDocTestIfInterface GtkDocTestIf diff --git a/tests/empty/src/Makefile.in b/tests/empty/src/Makefile.in index 06c03ad..43d9086 100644 --- a/tests/empty/src/Makefile.in +++ b/tests/empty/src/Makefile.in @@ -229,12 +229,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ diff --git a/tests/empty/src/tester.h b/tests/empty/src/tester.h index 23ab4ea..a9f5515 100644 --- a/tests/empty/src/tester.h +++ b/tests/empty/src/tester.h @@ -4,6 +4,14 @@ #include #include +/** + * FOO: + * + * The FOO. + * + * Since: 0.1 + */ +#define FOO "bar" void test (gint a); diff --git a/tests/fail/Makefile.in b/tests/fail/Makefile.in index b3aec84..25ca541 100644 --- a/tests/fail/Makefile.in +++ b/tests/fail/Makefile.in @@ -237,12 +237,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ diff --git a/tests/fail/docs/Makefile.am b/tests/fail/docs/Makefile.am index 5a4f164..8210a80 100644 --- a/tests/fail/docs/Makefile.am +++ b/tests/fail/docs/Makefile.am @@ -23,9 +23,6 @@ SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ # Extra options to supply to gtkdoc-mkdb. MKDB_OPTIONS= -# Extra options to supply to gtkdoc-mktmpl -# e.g. MKTMPL_OPTIONS=--only-section-tmpl -MKTMPL_OPTIONS= # Extra options to supply to gtkdoc-mkhtml MKHTML_OPTIONS= @@ -60,7 +57,7 @@ GTKDOC_CFLAGS = -I$(top_srcdir)/tests/fail/src $(TEST_DEPS_CFLAGS) GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/fail/src/libtester.la # include generic part -include $(top_srcdir)/tests/gtk-doc.notmpl.make +include $(top_srcdir)/tests/gtk-doc.make # Other files to distribute # e.g. EXTRA_DIST += version.xml.in diff --git a/tests/fail/docs/Makefile.in b/tests/fail/docs/Makefile.in index 93e9977..4079a83 100644 --- a/tests/fail/docs/Makefile.in +++ b/tests/fail/docs/Makefile.in @@ -83,8 +83,8 @@ PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ -DIST_COMMON = $(top_srcdir)/tests/gtk-doc.notmpl.make \ - $(srcdir)/Makefile.in $(srcdir)/Makefile.am +DIST_COMMON = $(top_srcdir)/tests/gtk-doc.make $(srcdir)/Makefile.in \ + $(srcdir)/Makefile.am subdir = tests/fail/docs ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \ @@ -184,12 +184,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ @@ -291,9 +291,6 @@ SCAN_OPTIONS = --deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ # Extra options to supply to gtkdoc-mkdb. MKDB_OPTIONS = -# Extra options to supply to gtkdoc-mktmpl -# e.g. MKTMPL_OPTIONS=--only-section-tmpl -MKTMPL_OPTIONS = # Extra options to supply to gtkdoc-mkhtml MKHTML_OPTIONS = @@ -372,9 +369,8 @@ REPORT_FILES = \ CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \ $(DOC_MODULE).pdf ts gtkdoc-scan.log gtkdoc-scangobj.log \ - gtkdoc-mktmpl.log gtkdoc-mkdb.log gtkdoc-mkhtml.log \ - gtkdoc-mkpdf.log gtkdoc-fixxref.log \ - $(DOC_MODULE)-overrides.txt + gtkdoc-mkdb.log gtkdoc-mkhtml.log gtkdoc-mkpdf.log \ + gtkdoc-fixxref.log $(DOC_MODULE)-overrides.txt GITIGNOREFILES = \ html.ref xml.ref @@ -386,7 +382,7 @@ GITIGNOREFILES = \ all: all-am .SUFFIXES: -$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.notmpl.make $(am__configure_deps) +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.make $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ @@ -407,7 +403,7 @@ Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ esac; -$(top_srcdir)/tests/gtk-doc.notmpl.make: +$(top_srcdir)/tests/gtk-doc.make: $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh @@ -596,14 +592,14 @@ ts: setup-build.stamp: ts -@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - echo ' DOC Preparing build'; \ - files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ - if test "x$$files" != "x" ; then \ - for file in $$files ; do \ - test -f $(abs_srcdir)/$$file && \ - cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ - done; \ - fi; \ + echo ' DOC Preparing build'; \ + files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ + if test "x$$files" != "x" ; then \ + for file in $$files ; do \ + test -f $(abs_srcdir)/$$file && \ + cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ + done; \ + fi; \ fi @touch setup-build.stamp @@ -614,26 +610,26 @@ scan-build.stamp: ts setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files" @_source_dir='' ; \ for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log @if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ - echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ - scanobj_options=""; \ - if test "x$(V)" = "x1"; then \ - scanobj_options="--verbose"; \ - fi; \ - echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ - CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ - gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ + echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ + scanobj_options=""; \ + if test "x$(V)" = "x1"; then \ + scanobj_options="--verbose"; \ + fi; \ + echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ + gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ else \ - for i in $(SCANOBJ_FILES) ; do \ - test -f $$i || touch $$i ; \ - done \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ fi @touch scan-build.stamp @@ -650,7 +646,7 @@ sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HF _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log @touch sgml-build.stamp @@ -680,7 +676,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) mkhtml_options="$$mkhtml_options --verbose"; \ fi; \ echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \ - cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log -@test "x$(HTML_IMAGES)" = "x" || \ for file in $(HTML_IMAGES) ; do \ @@ -694,7 +690,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references" @echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log @touch html-build.stamp @@ -718,7 +714,7 @@ pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) done; \ fi; \ echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log @touch pdf-build.stamp diff --git a/tests/fail/src/Makefile.in b/tests/fail/src/Makefile.in index ebcfc9f..8394d82 100644 --- a/tests/fail/src/Makefile.in +++ b/tests/fail/src/Makefile.in @@ -229,12 +229,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ diff --git a/tests/gobject/Makefile.in b/tests/gobject/Makefile.in index f665696..cafef4b 100644 --- a/tests/gobject/Makefile.in +++ b/tests/gobject/Makefile.in @@ -237,12 +237,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ diff --git a/tests/gobject/docs/Makefile.am b/tests/gobject/docs/Makefile.am index bbd4610..3eb5b7e 100644 --- a/tests/gobject/docs/Makefile.am +++ b/tests/gobject/docs/Makefile.am @@ -24,10 +24,6 @@ SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ # Extra options to supply to gtkdoc-mkdb. MKDB_OPTIONS=--xml-mode -# Extra options to supply to gtkdoc-mktmpl -# e.g. MKTMPL_OPTIONS=--only-section-tmpl -MKTMPL_OPTIONS= - # Extra options to supply to gtkdoc-mkhtml MKHTML_OPTIONS= @@ -62,7 +58,7 @@ GTKDOC_CFLAGS = -I$(top_srcdir)/tests/gobject/src $(TEST_DEPS_CFLAGS) GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/gobject/src/libtester.la # include generic part -include $(top_srcdir)/tests/gtk-doc.notmpl.make +include $(top_srcdir)/tests/gtk-doc.make # Other files to distribute # e.g. EXTRA_DIST += version.xml.in diff --git a/tests/gobject/docs/Makefile.in b/tests/gobject/docs/Makefile.in index 50705bd..0887ff8 100644 --- a/tests/gobject/docs/Makefile.in +++ b/tests/gobject/docs/Makefile.in @@ -83,8 +83,8 @@ PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ -DIST_COMMON = $(top_srcdir)/tests/gtk-doc.notmpl.make \ - $(srcdir)/Makefile.in $(srcdir)/Makefile.am +DIST_COMMON = $(top_srcdir)/tests/gtk-doc.make $(srcdir)/Makefile.in \ + $(srcdir)/Makefile.am subdir = tests/gobject/docs ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/gtkdoc_jh_check_xml_catalog.m4 \ @@ -184,12 +184,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ @@ -292,10 +292,6 @@ SCAN_OPTIONS = --deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \ # Extra options to supply to gtkdoc-mkdb. MKDB_OPTIONS = --xml-mode -# Extra options to supply to gtkdoc-mktmpl -# e.g. MKTMPL_OPTIONS=--only-section-tmpl -MKTMPL_OPTIONS = - # Extra options to supply to gtkdoc-mkhtml MKHTML_OPTIONS = @@ -375,9 +371,9 @@ REPORT_FILES = \ CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \ $(DOC_MODULE).pdf ts gtkdoc-scan.log gtkdoc-scangobj.log \ - gtkdoc-mktmpl.log gtkdoc-mkdb.log gtkdoc-mkhtml.log \ - gtkdoc-mkpdf.log gtkdoc-fixxref.log \ - $(DOC_MODULE)-overrides.txt $(DOC_MODULE).types + gtkdoc-mkdb.log gtkdoc-mkhtml.log gtkdoc-mkpdf.log \ + gtkdoc-fixxref.log $(DOC_MODULE)-overrides.txt \ + $(DOC_MODULE).types GITIGNOREFILES = \ html.ref xml.ref @@ -389,7 +385,7 @@ GITIGNOREFILES = \ all: all-am .SUFFIXES: -$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.notmpl.make $(am__configure_deps) +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/tests/gtk-doc.make $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ @@ -410,7 +406,7 @@ Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ esac; -$(top_srcdir)/tests/gtk-doc.notmpl.make: +$(top_srcdir)/tests/gtk-doc.make: $(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh @@ -599,14 +595,14 @@ ts: setup-build.stamp: ts -@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - echo ' DOC Preparing build'; \ - files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ - if test "x$$files" != "x" ; then \ - for file in $$files ; do \ - test -f $(abs_srcdir)/$$file && \ - cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ - done; \ - fi; \ + echo ' DOC Preparing build'; \ + files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ + if test "x$$files" != "x" ; then \ + for file in $$files ; do \ + test -f $(abs_srcdir)/$$file && \ + cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ + done; \ + fi; \ fi @touch setup-build.stamp @@ -617,26 +613,26 @@ scan-build.stamp: ts setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files" @_source_dir='' ; \ for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log @if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ - echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ - scanobj_options=""; \ - if test "x$(V)" = "x1"; then \ - scanobj_options="--verbose"; \ - fi; \ - echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ - CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ - gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ + echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ + scanobj_options=""; \ + if test "x$(V)" = "x1"; then \ + scanobj_options="--verbose"; \ + fi; \ + echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ + gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ else \ - for i in $(SCANOBJ_FILES) ; do \ - test -f $$i || touch $$i ; \ - done \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ fi @touch scan-build.stamp @@ -653,7 +649,7 @@ sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HF _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log @touch sgml-build.stamp @@ -683,7 +679,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) mkhtml_options="$$mkhtml_options --verbose"; \ fi; \ echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \ - cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log -@test "x$(HTML_IMAGES)" = "x" || \ for file in $(HTML_IMAGES) ; do \ @@ -697,7 +693,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references" @echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log @touch html-build.stamp @@ -721,7 +717,7 @@ pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) done; \ fi; \ echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log @touch pdf-build.stamp diff --git a/tests/gobject/src/Makefile.am b/tests/gobject/src/Makefile.am index eaa6a40..0fc2ac9 100644 --- a/tests/gobject/src/Makefile.am +++ b/tests/gobject/src/Makefile.am @@ -15,5 +15,4 @@ AM_CPPFLAGS = $(TEST_DEPS_CFLAGS) endif - -include $(top_srcdir)/git.mk diff --git a/tests/gobject/src/Makefile.in b/tests/gobject/src/Makefile.in index b41c9e3..dc700fe 100644 --- a/tests/gobject/src/Makefile.in +++ b/tests/gobject/src/Makefile.in @@ -231,12 +231,12 @@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ -PERL = @PERL@ PKG_CONFIG = @PKG_CONFIG@ PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ PYTHON = @PYTHON@ PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PACKAGE_DIR = @PYTHON_PACKAGE_DIR@ PYTHON_PLATFORM = @PYTHON_PLATFORM@ PYTHON_PREFIX = @PYTHON_PREFIX@ PYTHON_VERSION = @PYTHON_VERSION@ diff --git a/tests/gobject/src/gobject.c b/tests/gobject/src/gobject.c index b4f19f2..2a455c1 100644 --- a/tests/gobject/src/gobject.c +++ b/tests/gobject/src/gobject.c @@ -32,6 +32,9 @@ * A new instance can be created using the gtkdoc_object_new() function. The * whole lifecycle usualy looks like shown in this example: * |[ + * #include + * #include + * * GObject *myobj; * * myobj = gtkdoc_object_new(); diff --git a/tests/gtk-doc.notmpl.make b/tests/gtk-doc.make similarity index 81% rename from tests/gtk-doc.notmpl.make rename to tests/gtk-doc.make index 2c5e33b..808fda4 100644 --- a/tests/gtk-doc.notmpl.make +++ b/tests/gtk-doc.make @@ -55,7 +55,6 @@ CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) \ ts \ gtkdoc-scan.log \ gtkdoc-scangobj.log \ - gtkdoc-mktmpl.log \ gtkdoc-mkdb.log \ gtkdoc-mkhtml.log \ gtkdoc-mkpdf.log \ @@ -81,14 +80,14 @@ ts: setup-build.stamp: ts -@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - echo ' DOC Preparing build'; \ - files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ - if test "x$$files" != "x" ; then \ - for file in $$files ; do \ - test -f $(abs_srcdir)/$$file && \ - cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ - done; \ - fi; \ + echo ' DOC Preparing build'; \ + files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ + if test "x$$files" != "x" ; then \ + for file in $$files ; do \ + test -f $(abs_srcdir)/$$file && \ + cp -pf $(abs_srcdir)/$$file $(abs_builddir)/ || true; \ + done; \ + fi; \ fi @touch setup-build.stamp @@ -99,26 +98,26 @@ scan-build.stamp: ts setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) echo " DOC `$(DATE_FMT_CMD)$$tsd`: Scanning header files" @_source_dir='' ; \ for i in $(DOC_SOURCE_DIR) ; do \ - _source_dir="$${_source_dir} --source-dir=$$i" ; \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES)" >gtkdoc-scan.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) 2>&1 | tee -a gtkdoc-scan.log @if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ - echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ - scanobj_options=""; \ - if test "x$(V)" = "x1"; then \ - scanobj_options="--verbose"; \ - fi; \ - echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ - CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ - gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ + echo " DOC `$(DATE_FMT_CMD)$$tsd`: Introspecting gobjects"; \ + scanobj_options=""; \ + if test "x$(V)" = "x1"; then \ + scanobj_options="--verbose"; \ + fi; \ + echo "gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options" >gtkdoc-scangobj.log; \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ + gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) $$scanobj_options 2>&1 | tee -a gtkdoc-scangobj.log; \ else \ - for i in $(SCANOBJ_FILES) ; do \ - test -f $$i || touch $$i ; \ - done \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ fi @touch scan-build.stamp @@ -135,7 +134,7 @@ sgml-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(HF _source_dir="$${_source_dir} --source-dir=$$i" ; \ done ; \ echo "gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS)" >gtkdoc-mkdb.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) 2>&1 | tee -a gtkdoc-mkdb.log @touch sgml-build.stamp @@ -165,7 +164,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) mkhtml_options="$$mkhtml_options --verbose"; \ fi; \ echo "gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)" >gtkdoc-mkhtml.log; \ - cd html && PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + cd html && PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkhtml --uninstalled --path="$(abs_srcdir)" $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) 2>&1 | tee -a ../gtkdoc-mkhtml.log -@test "x$(HTML_IMAGES)" = "x" || \ for file in $(HTML_IMAGES) ; do \ @@ -179,7 +178,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) @ts1=`cat ts`;ts2=`date $(TS_FMT)`;tsd=`echo $$ts2-$$ts1 | bc`; \ echo " DOC `$(DATE_FMT_CMD)$$tsd`: Fixing cross-references" @echo "gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)" >gtkdoc-fixxref.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) \ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) 2>&1 | tee -a gtkdoc-fixxref.log @touch html-build.stamp @@ -203,7 +202,7 @@ pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) done; \ fi; \ echo "gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS)" >gtkdoc-mkpdf.log; \ - PATH=$(abs_top_builddir):$(PATH) PERL5LIB=$(abs_top_builddir):$(PERL5LIB) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ + PATH=$(abs_top_builddir):$(PATH) PYTHONPATH=$(abs_top_builddir):$(abs_top_srcdir):$(PYTHONPATH) ABS_TOP_SRCDIR=$(abs_top_srcdir) \ gtkdoc-mkpdf --uninstalled --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) 2>&1 | tee -a gtkdoc-mkpdf.log @touch pdf-build.stamp diff --git a/tests/gtkdoc-common.t b/tests/gtkdoc-common.t deleted file mode 100755 index 35a706e..0000000 --- a/tests/gtkdoc-common.t +++ /dev/null @@ -1,36 +0,0 @@ -#!/usr/bin/env perl -# -*- cperl -*- -# -# gtk-doc - GTK DocBook documentation generator. -# Copyright (C) 2015 Stefan Sauer -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -# - -use diagnostics; -use warnings; -use strict; -use Test::More; - -require_ok ("gtkdoc-common.pl"); - -subtest 'CreateValidSGMLID' => sub { - is(CreateValidSGMLID('x'), 'x', 'already valid id is keept'); - is(CreateValidSGMLID('x_ y'), 'x--y', '\'_\' and \' \' are converted to \'-\''); - is(CreateValidSGMLID('x,;y'), 'xy', '\',\' and \';\' are dropped'); -}; - -done_testing(); - diff --git a/tests/gtkdoc-fixxref.t b/tests/gtkdoc-fixxref.t deleted file mode 100755 index 87dd44d..0000000 --- a/tests/gtkdoc-fixxref.t +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env perl -# -*- cperl -*- -# -# gtk-doc - GTK DocBook documentation generator. -# Copyright (C) 2015 Stefan Sauer -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -# - -use diagnostics; -use warnings; -use strict; -use Test::More; - -require_ok ("gtkdoc-fixxref"); - -done_testing(); - diff --git a/tests/gtkdoc-mkdb.t b/tests/gtkdoc-mkdb.t deleted file mode 100755 index 0a135af..0000000 --- a/tests/gtkdoc-mkdb.t +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env perl -# -*- cperl -*- -# -# gtk-doc - GTK DocBook documentation generator. -# Copyright (C) 2015 Stefan Sauer -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -# - -use diagnostics; -use warnings; -use strict; -use Test::More; - -require_ok ("gtkdoc-mkdb"); - -done_testing(); - diff --git a/tests/gtkdoc-rebase.t b/tests/gtkdoc-rebase.t deleted file mode 100755 index 6d5c7d5..0000000 --- a/tests/gtkdoc-rebase.t +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env perl -# -*- cperl -*- -# -# gtk-doc - GTK DocBook documentation generator. -# Copyright (C) 2015 Stefan Sauer -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -# - -use diagnostics; -use warnings; -use strict; -use Test::More; - -require_ok ("gtkdoc-rebase"); - -done_testing(); - diff --git a/tests/gtkdoc-scan.t b/tests/gtkdoc-scan.t deleted file mode 100755 index a04d971..0000000 --- a/tests/gtkdoc-scan.t +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env perl -# -*- cperl -*- -# -# gtk-doc - GTK DocBook documentation generator. -# Copyright (C) 2015 Stefan Sauer -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -# - -use diagnostics; -use warnings; -use strict; -use Test::More; - -require_ok ("gtkdoc-scan"); - -done_testing(); - diff --git a/tests/mk_to_db.py b/tests/mk_to_db.py new file mode 100755 index 0000000..646ad39 --- /dev/null +++ b/tests/mk_to_db.py @@ -0,0 +1,261 @@ +#!/usr/bin/env python +# -*- python; coding: utf-8 -*- +# +# gtk-doc - GTK DocBook documentation generator. +# Copyright (C) 2015 Christoph Reiter +# 2017 Stefan Sauer +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# + +import unittest + +from gtkdoc import md_to_db + + +class TestConverter(unittest.TestCase): + + def setUp(self): + md_to_db.Init() + + def test_main(self): + input_ = """\ +SUPPORTED MARKDOWN +================== + +Atx-style Headers +----------------- + +# Header 1 + +## Header 2 ## + +Setext-style Headers +-------------------- + +Header 1 +======== + +Header 2 +-------- + +Ordered (unnested) Lists +------------------------ + +1. item 1 + +1. item 2 with loooong *foo* + description + +3. item 3 + +Note: we require a blank line above the list items +""" + + expexted = """\ +SUPPORTED MARKDOWN +Atx-style Headers +Header 1Header 2 +Setext-style Headers + +Header 1Header 2 +Ordered (unnested) Lists + + +item 1 + + +item 2 with loooong *foo* +description + + +item 3 + + +Note: we require a blank line above the list items + +""" + + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(expexted, output) + + def test_docbook(self): + input_ = """\ + + foo + +""" + + # docbook should stay the same + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(input_, output) + + def test_header(self): + input_ = """ +widget lifecycle, states and style. + +# Height-for-width Geometry Management # {#geometry-management} + +GTK+ uses a height-for-width (and wid +""" + + expected = """\ +widget lifecycle, states and style. +Height-for-width Geometry ManagementGTK+ uses a height-for-width (and wid + +""" + + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(expected, output) + + def test_lists(self): + input_ = """\ +bla bla +bla: + +- The channel was just created, and has not been written to or read from yet. + bla + +- The channel is write-only. + +foo +""" + expected = """\ +bla bla +bla: + + +The channel was just created, and has not been written to or read from yet. +bla + + +The channel is write-only. + + +foo +""" + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(expected, output) + + def test_paragraphs(self): + input_ = """\ +foo, +bar. + +foo, +bar. + +foo, +bar. +""" + expected = """\ +foo, +bar. +foo, +bar. +foo, +bar. +""" + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(expected, output) + + def test_reference(self): + input_ = """\ +The #GData struct is an opaque data structure to represent a +[Keyed Data List][glib-Keyed-Data-Lists]. It should only be +accessed via the following functions.""" + + expected = """\ +The GData struct is an opaque data structure to represent a +Keyed Data List. It should only be +accessed via the following functions. +""" + + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(expected, output) + + def test_reference2(self): + input_ = "a [foo][bar] b [quux][baz]" + expected = 'a foo b quux\n' + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(expected, output) + + def test_reference_empty(self): + input_ = "[][]" + # expected = '\n' + expected = '\n' + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(expected, output) + + def test_inline_code(self): + input_ = "a `abc`" + expected = 'a abc\n' + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(expected, output) + + def test_inline_code2(self): + input_ = "a `[][]`" + expected = 'a [][]\n' + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(expected, output) + + def test_code(self): + input_ = """\ +|[ + GdkEvent *event; + GdkEventType type; + + type = event->type; +]| +""" + + expected = '''\ +type; +]]> + +''' + output = md_to_db.MarkDownParse(input_, "") + self.assertEqual(expected, output) + + def test_plain(self): + input_ = u"""\ +|[ +frame +├── border +├──