# Galician translation for gtk-doc. # Copyright (C) 2014 gtk-doc's COPYRIGHT HOLDER # This file is distributed under the same license as the gtk-doc package. # Fran Dieguez , 2014. msgid "" msgstr "" "Project-Id-Version: gtk-doc master\n" "POT-Creation-Date: 2014-09-22 21:18+0000\n" "PO-Revision-Date: 2014-09-23 02:11+0200\n" "Last-Translator: Fran Dieguez \n" "Language-Team: gnome-l10n-gl@gnome.org\n" "Language: gl\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=(n != 1);\n" "X-Generator: Virtaal 0.7.1\n" #. Put one translator per line, in the form NAME , YEAR1, YEAR2 msgctxt "_" msgid "translator-credits" msgstr "Fran Diéguez , 2014." #. (itstool) path: bookinfo/title #: C/index.docbook:12 msgid "GTK-Doc Manual" msgstr "Manual de GTK-Doc" #. (itstool) path: bookinfo/edition #: C/index.docbook:13 msgid "1.20" msgstr "1.20" #. (itstool) path: abstract/para #: C/index.docbook:14 msgid "User manual for developers with instructions of GTK-Doc usage." msgstr "" "Manual de usuarios para desenvolvedores con instrucións do uso de 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 "Proxecto 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-2014 Stefan Sauer (Kost)" msgstr "2007-2014 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 "" "Pode copiar, distribuír e modificar este documento baixo os termos da " "Licenza de Documentación Libre GNU, na súa versión " "1.1 ou posterior, publicada pola Free Software Foundation, sen seccións " "invariantes e sen textos de portada ou de contraportada. Inclúese unha cópida da licenza." #. (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 "" #. (itstool) path: revhistory/revision #: C/index.docbook:83 msgid "" "1.21.1 18 Jul 2014 ss development version" msgstr "" "1.21.1 18 de Xullo de 2014 " "ss versión de " "desenvolvemento" #. (itstool) path: revhistory/revision #: C/index.docbook:89 msgid "" "1.21 17 Jul 2014 ss bug fixes, dropping deprecated features" msgstr "" "1.21 17 de Xullo de 2014 " "ss arranxos de erros, retirado " "de características obsoletas" #. (itstool) path: revhistory/revision #: C/index.docbook:95 msgid "" "1.20 16 Feb 2014 ss bug fixes, markdown support, style improvements" msgstr "" "1.20 16 de Febreiro de 2014 " "ss arranxos de erros, " "compatibilidade de markdown, melloras de estilo" #. (itstool) path: revhistory/revision #: C/index.docbook:101 msgid "" "1.19 05 Jun 2013 ss bug fixes" msgstr "" "1.19 05 de Xuño de 2013 " "ss arranxos de erros" #. (itstool) path: revhistory/revision #: C/index.docbook:107 msgid "" "1.18 14 Sep 2011 ss bug fixes, speedups, markdown support" msgstr "" "1.18 14 de Setembro de 2011 " "ss arranxos de erros, melloras " "de velocidade, compatibilidade de markdown" #. (itstool) path: revhistory/revision #: C/index.docbook:113 msgid "" "1.17 26 Feb 2011 sk urgent bug fix update" msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:119 msgid "" "1.16 14 Jan 2011 sk bugfixes, layout improvements" msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:125 msgid "" "1.15 21 May 2010 sk bug and regression fixes" msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:131 msgid "" "1.14 28 March 2010 sk bugfixes and performance improvements" msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:137 msgid "" "1.13 18 December 2009 " "sk broken tarball update" msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:143 msgid "" "1.12 18 December 2009 " "sk new tool features and " "bugfixes" msgstr "" #. (itstool) path: revhistory/revision #: C/index.docbook:149 msgid "" "1.11 16 November 2008 " "mal GNOME doc-utils migration" msgstr "" #. (itstool) path: chapter/title #: C/index.docbook:162 msgid "Introduction" msgstr "" #. (itstool) path: chapter/para #: C/index.docbook:164 msgid "" "This chapter introduces GTK-Doc and gives an overview of what it is and how " "it is used." msgstr "" #. (itstool) path: sect1/title #: C/index.docbook:170 msgid "What is GTK-Doc?" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:172 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 "" #. (itstool) path: sect1/title #: C/index.docbook:180 msgid "How Does GTK-Doc Work?" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:182 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 "" #. (itstool) path: sect1/para #: C/index.docbook:189 msgid "" "GTK-Doc consists of a number of perl scripts, each performing a different " "step in the process." msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:194 msgid "There are 5 main steps in the process:" msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:201 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 "" #. (itstool) path: listitem/para #: C/index.docbook:211 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 "" #. (itstool) path: listitem/para #: C/index.docbook:228 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 "" #. (itstool) path: listitem/para #: C/index.docbook:234 msgid "" "gtkdoc-scanobj should not be used anymore. It was " "needed in the past when GObject was still GtkObject inside gtk+." msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:241 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 "" #. (itstool) path: note/para #: C/index.docbook:250 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 "" #. (itstool) path: listitem/para #: C/index.docbook:262 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." msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:273 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." msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:279 msgid "" "Files in sgml/ or xml/ and html/ directories are always overwritten. One should never edit them " "directly." msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:287 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 "" #. (itstool) path: sect1/title #: C/index.docbook:305 msgid "Getting GTK-Doc" msgstr "" #. (itstool) path: sect2/title #: C/index.docbook:308 msgid "Requirements" msgstr "" #. (itstool) path: sect2/para #: C/index.docbook:309 msgid "Perl v5 - the main scripts are in Perl." msgstr "" #. (itstool) path: sect2/para #: C/index.docbook:312 msgid "" "xsltproc - the xslt processor from libxslt xmlsoft.org/XSLT/" msgstr "" #. (itstool) path: sect2/para #: C/index.docbook:316 msgid "" "docbook-xsl - the docbook xsl stylesheets sourceforge.net/projects/docbook/files/docbook-xsl" msgstr "" #. (itstool) path: sect2/para #: C/index.docbook:320 msgid "Python - optional - for gtkdoc-depscan" msgstr "" #. (itstool) path: sect2/para #: C/index.docbook:323 msgid "" "One of source-highlight, highlight " "or vim - optional - used for syntax highlighting of " "examples" msgstr "" #. (itstool) path: sect1/title #: C/index.docbook:331 msgid "About GTK-Doc" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:333 C/index.docbook:347 msgid "(FIXME)" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:337 msgid "" "(History, authors, web pages, mailing list, license, future plans, " "comparison with other similar systems.)" msgstr "" #. (itstool) path: sect1/title #: C/index.docbook:345 msgid "About this Manual" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:351 msgid "(who it is meant for, where you can get it, license)" msgstr "" #. (itstool) path: chapter/title #: C/index.docbook:360 msgid "Setting up your project" msgstr "" #. (itstool) path: chapter/para #: C/index.docbook:362 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 "" #. (itstool) path: sect1/title #: C/index.docbook:373 msgid "Setting up a skeleton documentation" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:375 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 "" #. (itstool) path: example/title #: C/index.docbook:384 msgid "Example directory structure" msgstr "" #. (itstool) path: example/programlisting #: C/index.docbook:385 #, no-wrap msgid "" "\n" "meep/\n" " docs/\n" " reference/\n" " libmeep/\n" " meeper/\n" " src/\n" " libmeep/\n" " meeper/\n" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:382 msgid "This can then look as shown below: <_:example-1/>" msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title #: C/index.docbook:400 C/index.docbook:407 msgid "Integration with autoconf" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:402 msgid "" "Very easy! Just add one line to your configure.ac " "script." msgstr "" #. (itstool) path: example/programlisting #: C/index.docbook:408 #, no-wrap msgid "" "\n" "# check for gtk-doc\n" "GTK_DOC_CHECK([1.14],[--flavour no-tmpl])\n" msgstr "" #. (itstool) path: example/title #: C/index.docbook:420 msgid "Keep gtk-doc optional" msgstr "" #. (itstool) path: example/programlisting #: C/index.docbook:421 #, 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 "" #. (itstool) path: sect1/para #: C/index.docbook:415 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 "" #. (itstool) path: sect1/para #: C/index.docbook:432 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 "" #. (itstool) path: listitem/para #: C/index.docbook:438 msgid "--with-html-dir=PATH : path to installed docs" msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:439 msgid "--enable-gtk-doc : use gtk-doc to build documentation [default=no]" msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:440 msgid "" "--enable-gtk-doc-html : build documentation in html format [default=yes]" msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:441 msgid "--enable-gtk-doc-pdf : build documentation in pdf format [default=no]" msgstr "" #. (itstool) path: important/para #: C/index.docbook:445 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 "" #. (itstool) path: sect1/para #: C/index.docbook:453 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 "" #. (itstool) path: example/title #: C/index.docbook:461 msgid "Preparation for gtkdocize" msgstr "" #. (itstool) path: example/programlisting #: C/index.docbook:462 #, no-wrap msgid "" "\n" "AC_CONFIG_MACRO_DIR(m4)\n" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:467 msgid "" "After all changes to configure.ac are made, update the " "configure file. This can be done by re-running " "autoreconf -i or autogen.sh." msgstr "" #. (itstool) path: sect1/title #: C/index.docbook:475 msgid "Integration with automake" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:477 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 "" #. (itstool) path: sect1/para #: C/index.docbook:488 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 "" #. (itstool) path: sect1/title #: C/index.docbook:502 msgid "Integration with autogen" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:504 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 "" #. (itstool) path: example/title #: C/index.docbook:513 msgid "Running gtkdocize from autogen.sh" msgstr "" #. (itstool) path: example/programlisting #: C/index.docbook:514 #, no-wrap msgid "" "\n" "gtkdocize || exit 1\n" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:520 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 "" #. (itstool) path: sect1/para #: C/index.docbook:529 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 "" #. (itstool) path: sect1/title #. (itstool) path: example/title #: C/index.docbook:546 C/index.docbook:563 msgid "Running the doc build" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:548 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 "" #. (itstool) path: sect1/para #: C/index.docbook:555 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 "" #. (itstool) path: example/programlisting #: C/index.docbook:564 #, no-wrap msgid "" "\n" "./autogen.sh --enable-gtk-doc\n" "make\n" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:570 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 "" #. (itstool) path: sect1/title #: C/index.docbook:578 msgid "Integration with version control systems" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:580 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" msgstr "" #. (itstool) path: sect1/title #: C/index.docbook:591 msgid "Integration with plain makefiles or other build systems" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:593 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 "" #. (itstool) path: example/title #: C/index.docbook:600 msgid "Documentation build steps" msgstr "" #. (itstool) path: example/programlisting #: C/index.docbook:601 #, 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" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:615 msgid "" "One will need to look at the Makefile.am and " "gtk-doc.mak to pick the extra options needed." msgstr "" #. (itstool) path: chapter/title #: C/index.docbook:624 msgid "Documenting the code" msgstr "" #. (itstool) path: chapter/para #: C/index.docbook:626 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 "" #. (itstool) path: note/title #: C/index.docbook:634 msgid "Documentation placement" msgstr "" #. (itstool) path: note/para #: C/index.docbook:635 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: note/para #: C/index.docbook:641 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 "" #. (itstool) path: example/title #: C/index.docbook:652 C/index.docbook:669 msgid "GTK-Doc comment block" msgstr "" #. (itstool) path: example/programlisting #: C/index.docbook:653 #, no-wrap msgid "" "\n" "#ifndef __GTK_DOC_IGNORE__\n" "/* unparseable code here */\n" "#endif\n" msgstr "" #. (itstool) path: chapter/para #: C/index.docbook:648 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 "" #. (itstool) path: sect1/title #: C/index.docbook:664 msgid "Documentation comments" msgstr "" #. (itstool) path: example/programlisting #: C/index.docbook:670 #, no-wrap msgid "" "\n" "/**\n" " * identifier:\n" " * documentation ...\n" " */\n" msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:666 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 "" #. (itstool) path: sect1/para #: C/index.docbook:679 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 "" #. (itstool) path: sect1/para #: C/index.docbook:685 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 "" #. (itstool) path: listitem/para #: C/index.docbook:702 msgid "" "What it is: The name for a class or function can sometimes be misleading for " "people coming from a different background." msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:708 msgid "" "What it does: Tell about common uses. Put it in relation with the other API." msgstr "" #. (itstool) path: tip/para #: C/index.docbook:698 msgid "When documenting code, describe two aspects: <_:itemizedlist-1/>" msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:723 msgid "Use function() to refer to functions or macros which take arguments." msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:728 msgid "" "Use @param to refer to parameters. Also use this when referring to " "parameters of other functions, related to the one being described." msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:734 msgid "Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS." msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:739 msgid "" "Use #symbol to refer to other types of symbol, e.g. structs and enums and " "macros which don't take arguments." msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:745 msgid "Use #Object::signal to refer to a GObject signal." msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:750 msgid "Use #Object:property to refer to a GObject property." msgstr "" #. (itstool) path: listitem/para #: C/index.docbook:755 msgid "" "Use #Struct.field to refer to a field inside a structure and #GObjectClass." "foo_bar() to refer to a vmethod." msgstr "" #. (itstool) path: sect1/para #: C/index.docbook:717 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 "" #. (itstool) path: tip/para #: C/index.docbook:764 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 "" #. (itstool) path: sect1/para #: C/index.docbook:773 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 "" #. (itstool) path: sect1/para #: C/index.docbook:784 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