2 The TODO list for the gtk-doc project is at Bugzilla,
3 the bugtracking system of the GNOME project.
6 http://bugzilla.gnome.org/buglist.cgi?product=gtk-doc&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED
7 to see what is allready requested, or where you can help. :-)
9 To put an other request on the TODO list, visit
10 http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc
13 http://live.gnome.org/DocumentationProject/GtkDocFuture
14 and join discussion about future features.
17 Developers can also add items here :)
21 * there is a bunch of #print statements for tracing
22 => add a sub Trace() to gtkdoc-common.pl
23 => use @TRACE@ "..." and depending on configure flag
25 [print __FILE__ . ":" . __LINE__ . ":" . ] or [#]
26 should be a function and the function should support loglevels and an
27 envar to enable/disable conditionally;
29 sgml-build.stamp -> db-build.stamp
30 sgml.stamp -> db.stamp
32 = More abbreviations =
33 * expand urls (needds more work, see gtkdoc-mkdb : ExpandAbbreviations)
37 diff -u --exclude="Makefile*" docs docs-tmpl | diffstat
40 * gtkdoc-fixxref makefile targets use $HTML_DIR
41 * HTML_DIR: The directory where gtk-doc generated documentation is installed
42 it comes from gtk-doc.m4 (--with-html-dir) but has no default
43 * automake exports $htmldir which is by default:
44 ${prefix}/share/doc/${PACKAGE_TARNAME}
45 * the Makefile uses $(DESTDIR)$(TARGET_DIR)
46 where TARGET_DIR = $(HTML_DIR)/$(DOC_MODULE)
47 http://www.gnu.org/software/libtool/manual/automake/DESTDIR.html
49 * $MODULE-unused.txt is produced in gtkdoc-mktmpl only
50 * we won't find unused doc blobs in notmpl build
51 * we should add mktmpl::CheckAllDeclarationsOutput() to mkdb (call it after
52 OutputSGML), but only call it if there is no tmpl dir or
53 remove writing the unused.txt in mktmpl.txt
56 * http://sagehill.net/docbookxsl/index.html
58 * would be good to be able to have page titles as a concatenation of document
59 name and page name (gtk+:GtkWIdget)
61 http://bugzilla.gnome.org/show_bug.cgi?id=531572 : html-single
62 http://bugzilla.gnome.org/show_bug.cgi?id=466535 : pdf
63 http://bugzilla.gnome.org/show_bug.cgi?id=467488 : man
64 we need more configure options in gtk-doc.m4:
65 --(enable|disable)-gtk-doc-(html|pdf|man|html-single|rtf)
66 - html : enabled by default
67 - html-single : is single page html
69 xmllint --noout --xinclude --postvalid tester-docs.xml
70 xmllint --noout --postvalid tester-docs.fo --dtdvalid file://$HOME/download/fo.dtd
71 - fo.dtd : http://www.renderx.com/Tests/validator/fo.zip
73 xsltproc --nonet --xinclude -o gtk-docs.html /home/ensonic/projects/gtk-doc/gtk-doc-single.xsl gtk-docs.sgml
74 * need to check if we can pass the style-sheet class as a parameter (--stringparam gtkdoc.stylesheet=(chunk|docbook))
75 * we might also need to reflow some things, as gtk-doc.xsl also runs the devhelp/devhelp2 generation
76 - but then the urls in the devhelp file, refer to the chunked html anyway
78 * xmlto via passivetex
79 xmlto --skip-validation pdf tester-docs.xml
81 ~/download/fop-0.95beta/fop -xsl /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl -xml tester-docs.xml -pdf tester-docs.pdf
82 ~/download/fop-0.94/fop -xsl /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl -xml tester-docs.xml -pdf tester-docs.pdf
84 xsltproc --nonet --xinclude -o tester-docs.fo ../../../gtk-doc-fo.xsl tester-docs.xml
85 ~/download/fop-0.94/fop -fo tester-docs.fo -pdf tester-docs.pdf
86 * xsltproc + passivetex
87 pdflatex "&pdfxmltex" tester-docs.fo
90 docbook2pdf -e no-valid tester-docs.sgml
93 * xmlto via passivetex
94 http://bugs.gentoo.org/show_bug.cgi?id=224937
95 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=310148
97 http://www.tug.org/texlive/devsrc/Master/texmf-dist/doc/xmltex/passivetex/
99 https://issues.apache.org/bugzilla/show_bug.cgi?id=46386
100 - download fop (don't use 0.95, 0.94 seems to work)
101 http://mirror.eunet.fi/apache/xmlgraphics/fop/binaries/
102 http://xmlgraphics.apache.org/fop/0.94/running.html
103 export FOP_OPTS="-Dhttp.proxyHost=xxx -Dhttp.proxyPort=8080"
105 http://sourceforge.net/project/showfiles.php?group_id=116740&package_id=129569&release_id=267101
106 and copy fop-hyph.jar to fop-0.9*/lib/
108 ~/download/fop-0.94/fop -fo tester-docs.fo -rtf tester-docs.rtf
110 unrtf -t ps tester-docs.rtf >tester-docs.ps
111 unrtf -t latex tester-docs.rtf >tester-docs.tex
114 we shouldn't convert the whole document to man. We should convert e.g. tool
115 sections to man pages.
118 * http://www.w3.org/TR/2003/WD-xinclude-20031110/#syntax
119 <xi:include href="index-symbols.html">
120 <xi:fallback><index /></xi:fallback>
123 http://sourceforge.net/tracker/index.php?func=detail&aid=1986587&group_id=21935&atid=373747
125 * we could add smart navigation for index/glossary pages
126 (like the subsections on the doc-pages)
129 * can we deprecate title in the sectionfile and request people to have this in
133 * add some -Wxxx parameters to help qa work
134 - 'deprecated' deprecating 'features'
135 - 'dummy-docs' check if symbol docs are very short and repeat mainly words
140 * we can have /* < protected > */ in classes
141 * we can have <SUBSECTION Protected> in -section.txt
142 * ideally we have Scope: {Public, Protected, Private} supported in doc comments
143 * there is a bg for gir, https://bugzilla.gnome.org/show_bug.cgi?id=594125
149 1) replace gtkdoc-scan/gtkdoc-scangobject by gtkdoc-gir and output the classical files or
150 patch gtkdoc-scan/gtkdoc-scangobject to output gir files
151 2) patch gtkdoc-mkdb to read stuff from gir instead of classical files
152 * if gir-files would have the comments too (they are getting this now):
153 * we could even drop scanning the sources
154 * IDEs could use the gir-files to show doc-tooltips for symbols
156 * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
158 * simmillar workflow to gettext
159 * add gtkdoc-mk??? to generate binding doc templates
160 * have c-comments there as comments
161 * when updating templates, mark sections that have changed as fuzzy
162 * add options to gtkdoc-mkdb to build docbook from those templates
164 * could we use the tmpl file mechanism?
165 * directory structure?
166 * we need to list the languages like ALL_LINGUAS for translations
167 * we need to create subdirs for binding docs, ideally we use one for 'C' as well
169 * devhelp files need a language attribute in the book-tag
170 language={C,C++,JavaScript,Perl,Python,...}
171 * devhelp could show a selector for the language
172 * need to get existing python/~mm docs to use it, gtk-doc could output
173 language=C for own docs
175 * need to install each book with a prefix
176 * would be good to have a language attribute in book tag to allow filter by language
177 * look at /usr/share/gtk-doc/html/pygobject/index.html
179 = linking to sources =
180 - what about a template URL containing a %s for the "path/file".
181 http://svn.gnome.org/viewvc/gtk-doc/trunk/tests/gobject/src/gobject.c?view=markup
182 http://buzztard.svn.sourceforge.net/viewvc/buzztard/trunk/buzztard/src/lib/core/core.c?view=markup
183 - unfortunately we can't link to symbols
184 - linking to files is difficult as in gtkdoc we have modules
188 Its tedious to write large amounts of docbook.
191 We need parametric, user definable macros.
192 |[ ... ]| - programlistings
193 |macro(arg1,arg2,...)[ ... ]| - call macro
194 - pass args as parameters (on the commandline)
195 - pass some gtk-doc vars in environment
196 (gtk-doc version, module, srcdir, buildir)
197 - content of [] on stdin or as a file
198 - get output on stdout or file
199 - and replace the macro with it
200 The changes could be made in gtkdoc-mkdb::ExpandAbbreviations()
201 === example macros ===
202 |highlight(c)[...]| - highlight source code for a specific language
203 |dot(abc.svg)[...]| - format dot graph and include result as mediaobject
204 |ditta(abc.svg)[...]| - parse ascii art and include result as mediaobject
206 === where to define macros ===
207 * system wide and with the package, <prefix>/share/gtk-doc/macros, $(srcdir)
208 * prefix for custom macros?
209 * we could require stdin for input and stdout for output, the wrapper for the
210 actual tool can ensure the convention
212 == ascii doc as a frontend ==
213 Can we offer integration with asciidoc (http://www.methods.co.nz/asciidoc/)?
214 This way the master document could be written much easier. It would be cool if
215 we could use the asciidoc markup in source-comments also.
217 == extract other bits and pieces ==
219 gtkdoc-scan could be obsoleted and gtkdoc-mkdb would build docbook fragemnts for
220 api docs and their indexes
221 === DBUs Interfaces ===
222 http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html
223 http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus
224 === GConf schemas ===
231 == source code examples==
232 http://bugzilla.gnome.org/show_bug.cgi?id=536928
233 We could also run a postprocessing script in gtkdoc-mkhtml/gtkdoc-fixxref
236 source-highlight (/usr/bin/source-highlight)
237 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.html -n -t4 -sc
238 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.html -n -t4 -sc -cstyle.css --no-doc
239 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.xml -n -t4 -sc -f docbook
241 highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.xml -l -X -f -j2
243 some tips about styling code listings in html
244 http://www.tjkdesign.com/articles/how_to_style_a_code_listing.asp
246 === process docbook ===
247 if we highlight to docbook, we just get emphasis (bold)
249 if we hightlight to html we get colors, we need to check what tags we should process though:
250 <pre class="programlisting"> is used for all code boxes.
251 <div class="informalexample"><pre class="programlisting"> is used for examples.
253 * in html we don't know the language anymore
255 * with source-highlight, constants and types are not markedup.
256 for types we might need to build an own lang file dynamically and include
257 /usr/share/source-highlight/c.lang
258 === |[ ... ]| does not allow setting the language ===
259 * check for vi/emacs/jedit modelines
260 jedit: http://www.jedit.org/users-guide/buffer-local.html
261 vim: http://vim.wikia.com/wiki/Modeline_magic
262 emacs: http://www.delorie.com/gnu/docs/emacs/emacs_486.html
263 * allow <!-- language="C" --> comments after |[
264 * we need to catch those when processing the docbook and expanding the |[
269 == wildcards in symbol names ==
270 Somtimes one defines a set of function and macros with very simillar purpose, e.g.
271 READ_INT8, READ_INT16, READ_INT32. It would be great to allow documenting a symbol
272 READ_INT* instead of 3 docs which are copy'n'pasted anyway. In the output we will have
273 all matching declarations in one source listing. Multiple wildcards are okay.
276 = documentation best practises #518427 =
277 * we'd like offer a more complete skelleton
279 * docbook markup (part/chapter structure)
281 Sugested structure for api-docs.
282 Idea is to have more content that api reference. It would be good to have a
283 gnome-platform document in devhelp, so that we could xref that instead of
284 explaining 100 times how to use pkg-config.
288 * concepts / api / tools / tutorial / related tools
290 * overview / api / migation / tools
291 * qt reference docs in qt assistant
292 * classes / overview / tutorial&examples
295 * table with details (http://www.docbook.org/tdg/en/html/bookinfo.html)
296 (problem: what enclosing tag)
298 Copyright and Legalnotice
300 * homepage, mailing lists, irc channel
301 * repository, source releases, bugtracker
303 * introduction - what is is about
304 * concepts - explain basic ideas and terminology
305 * development - how to build and run, env-vars, different platforms
306 * api - classic api docs
307 * tutorial & examples - integrated to keep it up-to-date and cross referenced
308 * migration - how to for api changes, deprecations
309 * (releated) tools - tools part of the package or recommended for development
310 * indexes - api-index, depretations, new api since xxx
312 proposed structure in docbook xml:
316 <preface><title>Introduction</title>
319 <part label="I"><title>xxx Overview</title>
320 <xi:include href="building.xml" />
323 <reference label="II"><title>xxx Core Reference</title>
324 <xi:include href="xml/gtkmain.xml" />
327 <reference label="III"><title>xxx Object Reference</title>
328 <chapter><title>Object Hierarchy</title>
329 <xi:include href="xml/tree_index.sgml" />
336 some things to check:
337 * gtk,glib: can we make a <part> for the glosary and index's (according to docbook, yes)
338 should we use <appendix>? its like a chapter.
339 * gobject: uses a <preface> for introductions
340 * gobject: uses <reference> as a parent for the xi:includeed <refentry> docs
342 = extra link for symbols =
343 need options for configure:
344 --enable-gtk-doc-codesearch-links
345 --enable-gtk-doc-liveedit-links
346 == viewvc,cgit,... ==
347 - link to some online service for the code
348 - problem: most don't have local anchors for the symbols
349 - where to set the uri (in the document, like for online url)?
351 - google (code) link : http://www.google.com/codesearch?q=g_object_unref
353 The idea is to have an 'edit' link in an online version of the docs (build from
354 head development version) per doc-entry (symbols and section).
355 The link goes to a cgi and that gets following parameters: docmodule,symbol.
356 E.g. http://library.gnome.org/devel/references/edit?docmodule=glib&symbol=g_new
357 The cgi would need a hashmap to get from docmodule to the way to check it out
358 (ideally it has a recent checkout and only updates it).
360 - signal that this has been edited already?
361 - support for xi:included examples
362 - updating the checkout could be slow
364 = fix missing since docs =
365 cd gstreamer/gstreamer/docs/gst
366 gtkdoc-mkdb --module=gstreamer --source-dir=../../gst --outputsymbolswithoutsince
367 cd gstreamer/gstreamer/src
370 git bisect bad RELEASE-0_10_0
371 git bisect run script.sh
376 grep "gst_caps_is_always_compatible" tags
380 - timestamp each step
382 - try CFLAGS=-O0 for compiling the scanner, no need to optimize it
383 CFLAGS="-O0" make check >make.log
386 http://docbook2x.sourceforge.net/latest/doc/performance.html
387 - play with xsltproc --profile --verbose --timing
388 cd tests/gobject/docs/html
389 time /usr/bin/xsltproc 2>xslt.log --profile --verbose --timing --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --xinclude --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ../tester-docs.xml
390 - l10n.language is slow
391 bug: https://sourceforge.net/tracker/index.php?func=detail&aid=2918673&group_id=21935&atid=373750
392 see: http://www.mail-archive.com/docbook-apps@lists.oasis-open.org/msg05412.html
393 - overide l10n.language
396 2m15.221s 1m58.740s 0m1.456s
398 1m55.480s 1m44.296s 0m2.125s
399 - removing the gentext calls for nav-bar alt tags does not help
402 - try plain docbook xslt to see if maybe we have bad xslt templates in the
403 customisation layer (gtk-doc.xsl)
405 - we could do the xinlcude processing once and use it for both html and pdf
406 time /usr/bin/xsltproc 2>../xslt4.log --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --xinclude --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ../tester-docs.xml
408 0m4.846s 0m4.434s 0m0.147s
409 0m4.842s 0m4.386s 0m0.145s
412 time xmllint --nonet --xinclude ../tester-docs.xml >./tester-docs-all.xml
414 0m0.596s 0m0.546s 0m0.023s
416 time /usr/bin/xsltproc 2>../xslt5.log --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ./tester-docs-all.xml
418 0m4.167s 0m3.834s 0m0.106s
419 0m4.248s 0m3.851s 0m0.114s
422 time xmllint --nonet --c14n --xinclude ../tester-docs.xml >./tester-docs-all2.xml
425 0m0.700s 0m0.636s 0m0.034s
427 time /usr/bin/xsltproc 2>../xslt6.log --path /home/ensonic/projects/gnome/gtk-doc/gtk-doc/tests/gobject/docs --nonet --stringparam gtkdoc.bookname tester --stringparam gtkdoc.version 1.14 /home/ensonic/projects/gnome/gtk-doc/gtk-doc/gtk-doc.xsl ./tester-docs-all2.xml
430 0m3.344s 0m3.026s 0m0.109s
431 0m3.372s 0m3.037s 0m0.115s
434 l ../tester-docs.xml ./tester-docs-all*.xml
436 - we could also try to compact the installed xslt
437 xmllint --nonet --c14n --xinclude gtk-doc.xsl | sed -ne '/<!--/ { :c; /-->/! { N; b c; }; /-->/s/<!--.*-->//g }; /^ *$/!p;' | sed '/^$/d' >gtk-doc.pre.xsl
438 - unfortunately there is no way to ask xsltproc to pre-transform an xslt, that could
440 - process xsl:import and xsl:include