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 * can we deprecate title in the sectionfile and request people to have this in
33 = More abbreviations =
34 * expand urls (needds more work, see gtkdoc-mkdb : ExpandAbbreviations)
39 diff -u --exclude="Makefile*" docs docs-tmpl | diffstat
43 * gtkdoc-fixxref makefile targets use $HTML_DIR
44 * HTML_DIR: The directory where gtk-doc generated documentation is installed
45 it comes from gtk-doc.m4 (--with-html-dir) but has no default
46 * automake exports $htmldir which is by default:
47 ${prefix}/share/doc/${PACKAGE_TARNAME}
48 * the Makefile uses $(DESTDIR)$(TARGET_DIR)
49 where TARGET_DIR = $(HTML_DIR)/$(DOC_MODULE)
50 http://www.gnu.org/software/libtool/manual/automake/DESTDIR.html
52 * $MODULE-unused.txt is produced in gtkdoc-mktmpl only
53 * we won't find unused doc blobs in notmpl build
54 * we should add mktmpl::CheckAllDeclarationsOutput() to mkdb (call it after
55 OutputSGML), but only call it if there is no tmpl dir or
56 remove writing the unused.txt in mktmpl.txt
60 * http://sagehill.net/docbookxsl/index.html
62 * would be good to be able to have page titles as a concatenation of document
63 name and page name (gtk+:GtkWIdget)
65 http://bugzilla.gnome.org/show_bug.cgi?id=531572 : html-single
66 http://bugzilla.gnome.org/show_bug.cgi?id=466535 : pdf
67 http://bugzilla.gnome.org/show_bug.cgi?id=467488 : man
68 we need more configure options in gtk-doc.m4:
69 --(enable|disable)-gtk-doc-(html|pdf|man|html-single|rtf)
70 - html : enabled by default
71 - html-single : is single page html
73 xmllint --noout --xinclude --postvalid tester-docs.xml
74 xmllint --noout --postvalid tester-docs.fo --dtdvalid file://$HOME/download/fo.dtd
75 - fo.dtd : http://www.renderx.com/Tests/validator/fo.zip
77 xsltproc --nonet --xinclude -o gtk-docs.html /home/ensonic/projects/gtk-doc/gtk-doc-single.xsl gtk-docs.sgml
78 * need to check if we can pass the style-sheet class as a parameter (--stringparam gtkdoc.stylesheet=(chunk|docbook))
79 * we might also need to reflow some things, as gtk-doc.xsl also runs the devhelp/devhelp2 generation
80 - but then the urls in the devhelp file, refer to the chunked html anyway
82 ~/download/fop-0.94/fop -fo tester-docs.fo -rtf tester-docs.rtf
84 unrtf -t ps tester-docs.rtf >tester-docs.ps
85 unrtf -t latex tester-docs.rtf >tester-docs.tex
90 Bugzilla has some requests for extra warnings. We should support a common
91 commandline option(s) in all tools to enable/disable the warnings. The makefiles
92 should pass the flags from an env-var (GTKDOC_OPTIONS). The env-var should be
93 used after the regular flags, so that the env-var can override hardcoded
94 settings (in Makefile.am).
96 Lets take this warning for the example:
97 "Symbol name not found at the start of the comment block."
99 Version 1: (template "warn-xxx!, warn-yyy!")
100 --warn-missing-symbol-at-comment-start
101 --no-warn-missing-symbol-at-comment-start
103 Version 2: (template "warn:s@")
104 -Wmissing-symbol-at-comment-start
105 -Wno-missing-symbol-at-comment-start
106 -warn missing-symbol-at-comment-start
107 -warn no-missing-symbol-at-comment-start
110 - 'deprecated' deprecating 'features'
111 - 'dummy-docs' check if symbol docs are very short and repeat mainly words
113 - possible xrefs (e.g. adding a # or () would make it a successful xref)
118 * we can have /* < protected > */ in classes
119 * we can have <SUBSECTION Protected> in -section.txt
120 * ideally we have Scope: {Public, Protected, Private} supported in doc comments
121 * there is a bg for gir, https://bugzilla.gnome.org/show_bug.cgi?id=594125
127 1) replace gtkdoc-scan/gtkdoc-scangobject by gtkdoc-gir and output the classical files or
128 patch gtkdoc-scan/gtkdoc-scangobject to output gir files
129 2) patch gtkdoc-mkdb to read stuff from gir instead of classical files
130 * if gir-files would have the comments too (they are getting this now):
131 * we could even drop scanning the sources
132 * IDEs could use the gir-files to show doc-tooltips for symbols
134 * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
136 * simmillar workflow to gettext
137 * add gtkdoc-mk??? to generate binding doc templates
138 * have c-comments there as comments
139 * when updating templates, mark sections that have changed as fuzzy
140 * add options to gtkdoc-mkdb to build docbook from those templates
142 * could we use the tmpl file mechanism?
143 * directory structure?
144 * we need to list the languages like ALL_LINGUAS for translations
145 * we need to create subdirs for binding docs, ideally we use one for 'C' as well
147 * devhelp files need a language attribute in the book-tag
148 language={C,C++,JavaScript,Perl,Python,...}
149 * devhelp could show a selector for the language
150 * need to get existing python/~mm docs to use it, gtk-doc could output
151 language=C for own docs
153 * need to install each book with a prefix
154 * would be good to have a language attribute in book tag to allow filter by language
155 * look at /usr/share/gtk-doc/html/pygobject/index.html
159 Its tedious to write large amounts of docbook.
162 We need parametric, user definable macros.
163 |[ ... ]| - programlistings
164 |macro(arg1,arg2,...)[ ... ]| - call macro
165 - pass args as parameters (on the commandline)
166 - pass some gtk-doc vars in environment
167 (gtk-doc version, module, srcdir, buildir)
168 - content of [] on stdin or as a file
169 - get output on stdout or file
170 - and replace the macro with it
171 The changes could be made in gtkdoc-mkdb::ExpandAbbreviations()
172 === example macros ===
173 |highlight(c)[...]| - highlight source code for a specific language (c)
174 - what will this output? preformatted html to be xincluded?
175 - we could have macros for each format, the docbook xml macro would leave
176 enough traces in the html so that a html macro can continue
177 |dot(svg)[...]| - format dot graph and include result as mediaobject (in svg format)
178 |ditta(svg)[...]| - parse ascii art and include result as mediaobject (in svg format)
179 - we need to generate a filename for the image or use anoter parameter
181 === where to define macros ===
182 * system wide and with the package, <prefix>/share/gtk-doc/macros, $(srcdir)
183 * prefix for custom macros?
184 * we could require stdin for input and stdout for output, the wrapper for the
185 actual tool can ensure the convention
187 == ascii doc as a frontend ==
188 Can we offer integration with asciidoc (http://www.methods.co.nz/asciidoc/)?
189 This way the master document could be written much easier. It would be cool if
190 we could use the asciidoc markup in source-comments also.
192 == extract other bits and pieces ==
194 gtkdoc-scan could be obsoleted and gtkdoc-mkdb would build docbook fragemnts for
195 api docs and their indexes
196 === DBUs Interfaces ===
197 http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html
198 http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus
199 === GConf schemas ===
206 == source code examples==
207 http://bugzilla.gnome.org/show_bug.cgi?id=536928
208 We could also run a postprocessing script in gtkdoc-mkhtml/gtkdoc-fixxref
211 source-highlight (/usr/bin/source-highlight)
212 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.html -n -t4 -sc
213 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.html -n -t4 -sc -cstyle.css --no-doc
214 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.xml -n -t4 -sc -f docbook
216 highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.xml -l -X -f -j2
218 some tips about styling code listings in html
219 http://www.tjkdesign.com/articles/how_to_style_a_code_listing.asp
221 === process docbook ===
222 if we highlight to docbook, we just get emphasis (bold)
224 if we highlight to html we get colors, we need to check what tags we should process though:
225 <pre class="programlisting"> is used for all code boxes.
226 <div class="informalexample"><pre class="programlisting"> is used for examples.
228 * in html we don't know the language anymore
230 * with source-highlight, constants and types are not markedup.
231 for types we might need to build an own lang file dynamically and include
232 /usr/share/source-highlight/c.lang
233 === |[ ... ]| does not allow setting the language ===
234 * check for vi/emacs/jedit modelines
235 jedit: http://www.jedit.org/users-guide/buffer-local.html
236 vim: http://vim.wikia.com/wiki/Modeline_magic
237 emacs: http://www.delorie.com/gnu/docs/emacs/emacs_486.html
238 * allow <!-- language="C" --> comments after |[
239 * we need to catch those when processing the docbook and expanding the |[
240 * require new macro syntax
244 == wildcards in symbol names ==
245 Somtimes one defines a set of function and macros with very simillar purpose, e.g.
246 READ_INT8, READ_INT16, READ_INT32. It would be great to allow documenting a symbol
247 READ_INT* instead of 3 docs which are copy'n'pasted anyway. In the output we will have
248 all matching declarations in one source listing. Multiple wildcards are okay.
251 = documentation best practises #518427 =
252 * we'd like offer a more complete skelleton
254 * docbook markup (part/chapter structure)
256 Sugested structure for api-docs.
257 Idea is to have more content that api reference. It would be good to have a
258 gnome-platform document in devhelp, so that we could xref that instead of
259 explaining 100 times how to use pkg-config.
263 * concepts / api / tools / tutorial / related tools
265 * overview / api / migation / tools
266 * qt reference docs in qt assistant
267 * classes / overview / tutorial&examples
270 * table with details (http://www.docbook.org/tdg/en/html/bookinfo.html)
271 (problem: what enclosing tag)
273 Copyright and Legalnotice
275 * homepage, mailing lists, irc channel
276 * repository, source releases, bugtracker
278 * introduction - what is is about
279 * concepts - explain basic ideas and terminology
280 * development - how to build and run, env-vars, different platforms
281 * api - classic api docs
282 * tutorial & examples - integrated to keep it up-to-date and cross referenced
283 * migration - how to for api changes, deprecations
284 * (releated) tools - tools part of the package or recommended for development
285 * indexes - api-index, depretations, new api since xxx
287 proposed structure in docbook xml:
291 <preface><title>Introduction</title>
294 <part label="I"><title>xxx Overview</title>
295 <xi:include href="building.xml" />
298 <reference label="II"><title>xxx Core Reference</title>
299 <xi:include href="xml/gtkmain.xml" />
302 <reference label="III"><title>xxx Object Reference</title>
303 <chapter><title>Object Hierarchy</title>
304 <xi:include href="xml/tree_index.sgml" />
311 some things to check:
312 * gtk,glib: can we make a <part> for the glosary and index's (according to docbook, yes)
313 should we use <appendix>? its like a chapter.
314 * gobject: uses a <preface> for introductions
315 * gobject: uses <reference> as a parent for the xi:includeed <refentry> docs
318 = extra link for symbols =
319 need options for configure:
320 --enable-gtk-doc-codesearch-links
321 --enable-gtk-doc-liveedit-links
322 == viewvc,cgit,... ==
323 - link to some online service for the code
324 - problem: most don't have local anchors for the symbols
325 - where to set the uri (in the document, like for online url)?
326 - what about a template URL containing a %s for the "path/file" or a special macro
327 http://svn.gnome.org/viewvc/gtk-doc/trunk/tests/gobject/src/gobject.c?view=markup
328 http://buzztard.svn.sourceforge.net/viewvc/buzztard/trunk/buzztard/src/lib/core/core.c?view=markup
329 - unfortunately we can't link to symbols (only lines)
330 - linking to files is difficult as in gtkdoc we have modules
333 - google (code) link : http://www.google.com/codesearch?q=g_object_unref
335 The idea is to have an 'edit' link in an online version of the docs (build from
336 head development version) per doc-entry (symbols and section).
337 The link goes to a cgi and that gets following parameters: docmodule,symbol.
338 E.g. http://library.gnome.org/devel/references/edit?docmodule=glib&symbol=g_new
339 The cgi would need a hashmap to get from docmodule to the way to check it out
340 (ideally it has a recent checkout and only updates it).
342 - signal that this has been edited already?
343 - support for xi:included examples
344 - updating the checkout could be slow
347 = fix missing since docs =
348 cd gstreamer/gstreamer/docs/gst
349 gtkdoc-mkdb --module=gstreamer --source-dir=../../gst --outputsymbolswithoutsince
350 cd gstreamer/gstreamer/src
353 git bisect bad RELEASE-0_10_0
354 git bisect run script.sh
359 grep "gst_caps_is_always_compatible" tags
363 - timestamp each step
365 - try CFLAGS=-O0 for compiling the scanner, no need to optimize it
366 CFLAGS="-O0" make check >make.log
369 http://docbook2x.sourceforge.net/latest/doc/performance.html
370 - play with xsltproc --profile --verbose --timing
371 cd tests/gobject/docs/html
372 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
373 - l10n.language is slow
374 bug: https://sourceforge.net/tracker/index.php?func=detail&aid=2918673&group_id=21935&atid=373750
375 see: http://www.mail-archive.com/docbook-apps@lists.oasis-open.org/msg05412.html
376 - overide l10n.language
379 2m15.221s 1m58.740s 0m1.456s
381 1m55.480s 1m44.296s 0m2.125s
382 - override many template related to gentext
384 0m43.327s 0m38.594s 0m4.724s
387 0m33.282s 0m29.266s 0m4.012s
388 - removing the gentext calls for nav-bar alt tags does not help
391 - try plain docbook xslt to see if maybe we have bad xslt templates in the
392 customisation layer (gtk-doc.xsl)
394 - we could do the xinlcude processing once and use it for both html and pdf
395 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
397 0m4.846s 0m4.434s 0m0.147s
398 0m4.842s 0m4.386s 0m0.145s
401 time xmllint --nonet --xinclude ../tester-docs.xml >./tester-docs-all.xml
403 0m0.596s 0m0.546s 0m0.023s
405 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
407 0m4.167s 0m3.834s 0m0.106s
408 0m4.248s 0m3.851s 0m0.114s
411 time xmllint --nonet --c14n --xinclude ../tester-docs.xml >./tester-docs-all2.xml
414 0m0.700s 0m0.636s 0m0.034s
416 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
419 0m3.344s 0m3.026s 0m0.109s
420 0m3.372s 0m3.037s 0m0.115s
423 l ../tester-docs.xml ./tester-docs-all*.xml
425 - we could also try to compact the installed xslt
426 xmllint --nonet --c14n --xinclude gtk-doc.xsl | sed -ne '/<!--/ { :c; /-->/! { N; b c; }; /-->/s/<!--.*-->//g }; /^ *$/!p;' | sed '/^$/d' >gtk-doc.pre.xsl
427 - unfortunately there is no way to ask xsltproc to pre-transform an xslt, that could
429 - process xsl:import and xsl:include
431 http://sourceforge.net/projects/xsltc/
432 http://www.xmlhack.com/read.php?item=618
433 - extra xsltproc options:
434 --novalid: saves ~ 0.12 sec
437 - not really an issue, but we can improve by compiling the regexps
438 http://stackoverflow.com/questions/550258/does-the-o-modifier-for-perl-regular-expressions-still-provide-any-benefit
439 - we use $&, $', and $` in several places (comple match, pre-match and post-match).
440 Those are slow and once they are used a single time perl prepares them for every match operation.
441 Since perl 5.10 one can use the /p flag for matches where this is needed and then use
442 ${^PREMATCH} , ${^MATCH} and ${^POSTMATCH}