[gtk-doc] docs: update the docs for 1.20
- From: Stefan Kost <stefkost src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk-doc] docs: update the docs for 1.20
- Date: Sun, 9 Feb 2014 11:02:07 +0000 (UTC)
commit aa412af11f84e60f56701e16c40968d55632f6a3
Author: Stefan Sauer <ensonic users sf net>
Date: Sun Feb 9 12:01:06 2014 +0100
docs: update the docs for 1.20
Add a section 'modernizing' that helps to decide which verison to require for which feature.
Expand the markdown support a little.
help/manual/C/index.docbook | 103 ++++++++++++++++++++++++++++++++++++++++---
1 files changed, 96 insertions(+), 7 deletions(-)
---
diff --git a/help/manual/C/index.docbook b/help/manual/C/index.docbook
index 1b88217..9728982 100644
--- a/help/manual/C/index.docbook
+++ b/help/manual/C/index.docbook
@@ -835,13 +835,13 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
</para>
<tip>
- <para>
+ <para>
If you need to use the special characters '<', '>', '()', '@',
'%', or '#' in your documentation without GTK-Doc changing them you
can use the XML entities "&lt;", "&gt;", "&lpar;",
"&rpar;", "&commat;", "&percnt;" and "&num;"
respectively or escape them with a backslash '\'.
- </para>
+ </para>
</tip>
<para>
@@ -855,9 +855,9 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
<para>
Since GTK-Doc-1.18 the tool supports a subset or the
<ulink url="http://daringfireball.net/projects/markdown/";>markdown language</ulink>.
- One can use it for sub-headings and simple itemized lists. On older
- GTK-Doc versions the content will be rendered as it (the list items will
- appear in one line separated by dashes).
+ The support has improved a lot with version 1.20. On older GTK-Doc
+ versions the content will be rendered as it (the list items will appear
+ in one line separated by dashes).
<example><title>GTK-Doc comment block using markdown</title>
<programlisting>
<![CDATA[
@@ -878,6 +878,11 @@ gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
</programlisting>
</example>
</para>
+
+ <para>
+ More examples of what markdown tags are supproted can be found in the
+ <ulink url="http://git.gnome.org/browse/gtk-doc/tree/tests";>gtk-doc test suite</ulink>.
+ </para>
<tip>
<para>
@@ -1741,11 +1746,95 @@ gtk_arrow_get_type
<filename><package>.interfaces.txt</filename>,
<filename><package>.prerequisites.txt</filename> and
<filename><package>.signals.txt</filename>. If there are missing
- symbols in any of those, one can ask gtkdoc to keep the intermediate scanner
- file for further analysis, by running it as
+ symbols in any of those, one can ask GTK-Doc to keep the intermediate
+ scanner file for further analysis, by running it as
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
</para>
</chapter>
+
+ <chapter id="modernizing">
+ <title>Modernizing the documentation</title>
+
+ <para>
+ GTK-Doc has been around for quite some time. In this section we list new
+ features together with the version since when it is available.
+ </para>
+
+ <sect1 id="modernizing-gtk-doc-1-9">
+ <title>GTK-Doc 1.9</title>
+
+ <para>
+ When using xml instead of sgml, one can actually name the master
+ document <filename><package>-docs.xml</filename>.
+ </para>
+
+ <para>
+ This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
+ in <filename>Makefile.am</filename>. When this is enabled, the
+ <filename><package>-sections.txt</filename> is autogenerated and
+ can be removed from the vcs. This only works nicely for projects that
+ have a very regular structure (e.g. each .{c,h} pair will create new
+ section. If one organize a project close to that updating a manually
+ maintained section file can be as simple as running
+ <code>meld <package>-decl-list.txt <package>-sections.txt</code>.
+ </para>
+
+ <para>
+ Version 1.8 already introduced the syntax for documenting sections in
+ the sources instead of the separate files under <filename class='directory'>tmpl</filename>.
+ This version adds options to switch the whole doc module to not use the
+ extra tmpl build step at all, by using <option>--flavour no-tmpl</option>
+ in <filename>configure.ac</filename>.
+ </para>
+ </sect1>
+
+ <sect1 id="modernizing-gtk-doc-1-10">
+ <title>GTK-Doc 1.10</title>
+
+ <para>
+ This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in
+ <filename>Makefile.am</filename>. When this is enabled, the
+ <filename><package>.types</filename> is autogenerated and can be
+ removed from the vcs. When using this feature it is important to also
+ setup the <varname>IGNORE_HFILES</varname> in
+ <filename>Makefile.am</filename> for code that is build conditionally.
+ </para>
+ </sect1>
+
+ <sect1 id="modernizing-gtk-doc-1-16">
+ <title>GTK-Doc 1.16</title>
+
+ <para>
+ This version includes a new tool called gtkdoc-check. This tool can run
+ a set of sanity checks on your documentation. It is enabled by adding
+ these lines to the end of <filename>Makefile.am</filename>.
+ <example><title>Enable gtkdoc-check</title>
+ <programlisting>
+<![CDATA[
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = \
+ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
+ SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
+TESTS = $(GTKDOC_CHECK)
+endif
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </sect1>
+
+ <sect1 id="modernizing-gtk-doc-1-20">
+ <title>GTK-Doc 1.20</title>
+
+ <para>
+ Version 1.18 brought some initial markdown support. Using markdown in
+ doc comments is less intrusive than writing docbook xml. This version
+ improves a lot on this and add a lot more styles. The section that
+ explains the <link linkend="documenting_syntax">comment syntax</link>
+ has all the details.
+ </para>
+ </sect1>
+ </chapter>
<chapter id="documenting-others">
<title>Documenting other interfaces</title>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
