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 :)
20 == get rid of the -section.txt file ==
21 * section-title can be in SECTION comment already
22 * when scanning a header file, everything will be put to one section
23 * like we do for autogenerated section.txt file (gtkdoc-scan)
24 * we need comment markup to override the section
25 e.g.: " * InSection: xxxx"
26 this needs gtkdoc-mkdb::ScanSourceFile to understand a new tag, which
27 otherwise would appear as verbatim in the sources
28 * if one has "@InSection: xxxx" in a section comment we could patch the
29 main.xml file and insert then xi:include line (would possibly rely on a
30 special comment-pair there, we might also need to rewrite these
31 auto-generated xi:includes everytime as the placements could have been
32 changed, or we have a xi:inlcude for each chapter, that we regenerate).
33 * we need a way to specify subsections (Standart, Private)
34 this could be done in the SECTION comment
35 e.g.: "@HideSymbols: <list-of-symbols-to-hide>
36 * we could allow to have a SUBSECTION:xxx comment block too
37 but then we list all the symbols here to override the auto-section placement
38 * if we want to avoid the "InSection in symbol docs we could also have
39 e.g.: "@ExtraSymbols: <list-of-symbols-to-include>
40 * documented symbols that are in a file without section comment and do not
41 appear in "@ExtraSymbols", "@HideSymbols" would go to unused.txt
42 * shall we deprecated the unused sub-sections?
43 * can we have both at the same time (for migration)
44 * yes, read section-file first and add/override from inline comments
47 = More abbreviations =
48 * expand urls (needds more work, see gtkdoc-mkdb : ExpandAbbreviations)
53 diff -u --exclude="Makefile*" docs docs-tmpl | diffstat
57 gtk-doc is using a makefile with several targets to get from sources to docs. It
58 uses makefile variables for configuration.
59 It might be easier to have a gtk-doc tool that can run the other gtk-doc tools
60 in the right order (ev. by importing them as modules). This could handle a few
61 things nicer that the makefiles don't do well. This would also make it easy to
62 run it manually or integrate into other build systems.
65 * gtkdoc-fixxref makefile targets use $HTML_DIR
66 * HTML_DIR: The directory where gtk-doc generated documentation is installed
67 it comes from gtk-doc.m4 (--with-html-dir) but has no default
68 * automake exports $htmldir which is by default:
69 ${prefix}/share/doc/${PACKAGE_TARNAME}
70 * the Makefile uses $(DESTDIR)$(TARGET_DIR)
71 where TARGET_DIR = $(HTML_DIR)/$(DOC_MODULE)
72 http://www.gnu.org/software/libtool/manual/automake/DESTDIR.html
73 * gtkdoc does not know about module versions
74 * this is causing troubles when multiple library versions are installed
75 (gtk+-{2,3}, gstreamer-{0.8,0.10,1.0}
76 * right now gtk-doc is xreffing against any <module>/index.sgml found
77 * just using the one with a higher number won't work
81 We'd like to extend gtk-doc to understand conventions/features of gobject libs.
82 Ideally libs register their extension hooks, so that other libs that use these
83 libs can benefit from the extensions too.
85 == custom get_types collector ==
86 - the default method takes the types from a type file
87 - gstreamer plugin docs take a list of types from the gst plugin registry
89 == custom properties ==
90 - gtk has style and child properties
92 == extra gobject property flags ==
93 - gstreamer has 'controllable' properties
96 * http://sagehill.net/docbookxsl/index.html
98 * would be good to be able to have page titles as a concatenation of document
99 name and page name (gtk+:GtkWIdget)
101 http://bugzilla.gnome.org/show_bug.cgi?id=531572 : html-single
102 http://bugzilla.gnome.org/show_bug.cgi?id=466535 : pdf
103 http://bugzilla.gnome.org/show_bug.cgi?id=467488 : man
104 we need more configure options in gtk-doc.m4:
105 --(enable|disable)-gtk-doc-(html|pdf|man|html-single|rtf)
106 - html : enabled by default
107 - html-single : is single page html
109 xmllint --noout --xinclude --postvalid tester-docs.xml
110 xmllint --noout --postvalid tester-docs.fo --dtdvalid file://$HOME/download/fo.dtd
111 - fo.dtd : http://www.renderx.com/Tests/validator/fo.zip
113 xsltproc --nonet --xinclude -o gtk-docs.html /home/ensonic/projects/gtk-doc/gtk-doc-single.xsl gtk-docs.sgml
114 * need to check if we can pass the style-sheet class as a parameter (--stringparam gtkdoc.stylesheet=(chunk|docbook))
115 * we might also need to reflow some things, as gtk-doc.xsl also runs the devhelp/devhelp2 generation
116 - but then the urls in the devhelp file, refer to the chunked html anyway
118 ~/download/fop-0.94/fop -fo tester-docs.fo -rtf tester-docs.rtf
120 unrtf -t ps tester-docs.rtf >tester-docs.ps
121 unrtf -t latex tester-docs.rtf >tester-docs.tex
126 Bugzilla has some requests for extra warnings. We should support a common
127 commandline option(s) in all tools to enable/disable the warnings. The makefiles
128 should pass the flags from an env-var (GTKDOC_OPTIONS). The env-var should be
129 used after the regular flags, so that the env-var can override hardcoded
130 settings (in Makefile.am).
132 Lets take this warning for the example:
133 "Symbol name not found at the start of the comment block."
135 Version 1: (template "warn-xxx!, warn-yyy!")
136 --warn-missing-symbol-at-comment-start
137 --no-warn-missing-symbol-at-comment-start
139 Version 2: (template "warn:s@")
140 -Wmissing-symbol-at-comment-start
141 -Wno-missing-symbol-at-comment-start
142 -warn missing-symbol-at-comment-start
143 -warn no-missing-symbol-at-comment-start
146 - 'deprecated' deprecating 'features'
147 - 'dummy-docs' check if symbol docs are very short and repeat mainly words
149 - possible xrefs (e.g. adding a # or () would make it a successful xref)
154 * we can have /* < protected > */ in classes
155 * we can have <SUBSECTION Protected> in -section.txt
156 * ideally we have Scope: {Public, Protected, Private} supported in doc comments
157 * there is a bg for gir, https://bugzilla.gnome.org/show_bug.cgi?id=594125
163 1) replace gtkdoc-scan/gtkdoc-scangobject by gtkdoc-gir and output the classical files or
164 patch gtkdoc-scan/gtkdoc-scangobject to output gir files
165 2) patch gtkdoc-mkdb to read stuff from gir instead of classical files
166 * if gir-files would have the comments too (they are getting this now):
167 * we could even drop scanning the sources
168 * IDEs could use the gir-files to show doc-tooltips for symbols
169 * we might need yet another makefile flavour to use gir files
171 * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
174 * simmillar workflow to gettext
175 * add gtkdoc-mk??? to generate binding doc templates
176 * have c-comments there as comments
177 * when updating templates, mark sections that have changed as fuzzy
178 * add options to gtkdoc-mkdb to build docbook from those templates
180 * could we use the tmpl file mechanism?
181 * directory structure?
182 * we need to list the languages like ALL_LINGUAS for translations
183 * we need to create subdirs for binding docs, ideally we use one for 'C' as well
185 * devhelp files need a language attribute in the book-tag
186 language={C,C++,JavaScript,Perl,Python,...}
187 * devhelp could show a selector for the language
188 * need to get existing python/~mm docs to use it, gtk-doc could output
189 language=C for own docs
192 * need to install each book with a prefix
193 * would be good to have a language attribute in book tag to allow filter by language
194 * look at /usr/share/gtk-doc/html/pygobject/index.html
198 Its tedious to write large amounts of docbook.
201 We need parametric, user definable macros.
202 |[ ... ]| - programlistings
203 |macro(arg1,arg2,...)[ ... ]| - call macro
204 - pass args as parameters (on the commandline)
205 - pass some gtk-doc vars in environment
206 (gtk-doc version, module, srcdir, buildir)
207 - content of [] on stdin or as a file
208 - get output on stdout or file
209 - and replace the macro with it
210 The changes could be made in gtkdoc-mkdb::ExpandAbbreviations()
211 === example macros ===
212 |highlight(c)[...]| - highlight source code for a specific language (c)
213 - what will this output? preformatted html to be xincluded?
214 - we could have macros for each format, the docbook xml macro would leave
215 enough traces in the html so that a html macro can continue
216 |dot(svg)[...]| - format dot graph and include result as mediaobject (in svg format)
217 |ditta(svg)[...]| - parse ascii art and include result as mediaobject (in svg format)
218 - we need to generate a filename for the image or use anoter parameter
220 === where to define macros ===
221 * system wide and with the package, <prefix>/share/gtk-doc/macros, $(srcdir)
222 * prefix for custom macros?
223 * we could require stdin for input and stdout for output, the wrapper for the
224 actual tool can ensure the convention
226 == asciidoc as a frontend ==
227 Can we offer integration with asciidoc (http://www.methods.co.nz/asciidoc/)?
228 This way the master document could be written much easier. It would be cool if
229 we could use the asciidoc markup in source-comments also.
231 == extract other bits and pieces ==
233 gtkdoc-scan could be obsoleted and gtkdoc-mkdb would build docbook fragemnts for
234 api docs and their indexes
235 === DBUs Interfaces ===
236 http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html
237 http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus
238 === GConf schemas ===
245 == source code examples==
246 http://bugzilla.gnome.org/show_bug.cgi?id=536928
247 We could also run a postprocessing script in gtkdoc-mkhtml/gtkdoc-fixxref
250 source-highlight (/usr/bin/source-highlight)
251 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.html -n -t4 -sc
252 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.html -n -t4 -sc -cstyle.css --no-doc
253 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.xml -n -t4 -sc -f docbook
255 highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.xml -l -X -f -j2
257 some tips about styling code listings in html
258 http://www.tjkdesign.com/articles/how_to_style_a_code_listing.asp
260 === process docbook ===
261 if we highlight to docbook, we just get emphasis (bold)
263 if we highlight to html we get colors, we need to check what tags we should process though:
264 <pre class="programlisting"> is used for all code boxes.
265 <div class="informalexample"><pre class="programlisting"> is used for examples.
267 * in html we don't know the language anymore
269 * with source-highlight, constants and types are not markedup.
270 for types we might need to build an own lang file dynamically and include
271 /usr/share/source-highlight/c.lang
272 === |[ ... ]| does not allow setting the language ===
273 * check for vi/emacs/jedit modelines
274 jedit: http://www.jedit.org/users-guide/buffer-local.html
275 vim: http://vim.wikia.com/wiki/Modeline_magic
276 emacs: http://www.delorie.com/gnu/docs/emacs/emacs_486.html
277 * allow <!-- language="C" --> comments after |[
278 * we need to catch those when processing the docbook and expanding the |[
279 * require new macro syntax
281 == show inherited api ==
282 could we write small html files for each object for methods, signals and properties and then use iframes to combine those at runtime like in javadoc?
283 could we do that using javascript and some other magic?
287 == wildcards in symbol names ==
288 Somtimes one defines a set of function and macros with very simillar purpose, e.g.
289 READ_INT8, READ_INT16, READ_INT32. It would be great to allow documenting a symbol
290 READ_INT* instead of 3 docs which are copy'n'pasted anyway. In the output we will have
291 all matching declarations in one source listing. Multiple wildcards are okay.
294 = documentation best practises #518427 =
295 * we'd like offer a more complete skelleton
297 * docbook markup (part/chapter structure)
299 Sugested structure for api-docs.
300 Idea is to have more content that api reference. It would be good to have a
301 gnome-platform document in devhelp, so that we could xref that instead of
302 explaining 100 times how to use pkg-config.
306 * concepts / api / tools / tutorial / related tools
308 * overview / api / migation / tools
309 * qt reference docs in qt assistant
310 * classes / overview / tutorial&examples
313 * table with details (http://www.docbook.org/tdg/en/html/bookinfo.html)
314 (problem: what enclosing tag)
316 Copyright and Legalnotice
318 * homepage, mailing lists, irc channel
319 * repository, source releases, bugtracker
321 * introduction - what is is about
322 * concepts - explain basic ideas and terminology
323 * development - how to build and run, env-vars, different platforms
324 * api - classic api docs
325 * tutorial & examples - integrated to keep it up-to-date and cross referenced
326 * migration - how to for api changes, deprecations
327 * (releated) tools - tools part of the package or recommended for development
328 * indexes - api-index, depretations, new api since xxx
330 proposed structure in docbook xml:
334 <preface><title>Introduction</title>
337 <part label="I"><title>xxx Overview</title>
338 <xi:include href="building.xml" />
341 <reference label="II"><title>xxx Core Reference</title>
342 <xi:include href="xml/gtkmain.xml" />
345 <reference label="III"><title>xxx Object Reference</title>
346 <chapter><title>Object Hierarchy</title>
347 <xi:include href="xml/tree_index.sgml" />
354 some things to check:
355 * gtk,glib: can we make a <part> for the glosary and index's (according to docbook, yes)
356 should we use <appendix>? its like a chapter.
357 * gobject: uses a <preface> for introductions
358 * gobject: uses <reference> as a parent for the xi:includeed <refentry> docs
361 = extra link for symbols =
362 need options for configure:
363 --enable-gtk-doc-codesearch-links
364 --enable-gtk-doc-liveedit-links
365 == viewvc,cgit,... ==
366 - link to some online service for the code
367 - problem: most don't have local anchors for the symbols
368 - where to set the uri (in the document, like for online url)?
369 - what about a template URL containing a %s for the "path/file" or a special macro
370 http://svn.gnome.org/viewvc/gtk-doc/trunk/tests/gobject/src/gobject.c?view=markup
371 http://buzztard.svn.sourceforge.net/viewvc/buzztard/trunk/buzztard/src/lib/core/core.c?view=markup
372 - unfortunately we can't link to symbols (only lines)
373 - linking to files is difficult as in gtkdoc we have modules
376 - google (code) link : http://www.google.com/codesearch?q=g_object_unref
378 The idea is to have an 'edit' link in an online version of the docs (build from
379 head development version) per doc-entry (symbols and section).
380 The link goes to a cgi and that gets following parameters: docmodule,symbol.
381 E.g. http://library.gnome.org/devel/references/edit?docmodule=glib&symbol=g_new
382 The cgi would need a hashmap to get from docmodule to the way to check it out
383 (ideally it has a recent checkout and only updates it).
385 - signal that this has been edited already?
386 - support for xi:included examples
387 - updating the checkout could be slow
390 = fix missing since docs =
391 cd gstreamer/gstreamer/docs/gst
392 gtkdoc-mkdb --module=gstreamer --source-dir=../../gst --outputsymbolswithoutsince
393 cd gstreamer/gstreamer/src
396 git bisect bad RELEASE-0_10_0
397 git bisect run script.sh
402 grep "gst_caps_is_always_compatible" tags
406 - timestamp each step
408 - try CFLAGS=-O0 for compiling the scanner, no need to optimize it
409 CFLAGS="-O0" make check >make.log
412 http://docbook2x.sourceforge.net/latest/doc/performance.html
413 - play with xsltproc --profile --verbose --timing
414 cd tests/gobject/docs/html
415 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
416 - l10n.language is slow
417 bug: https://sourceforge.net/tracker/index.php?func=detail&aid=2918673&group_id=21935&atid=373750
418 see: http://www.mail-archive.com/docbook-apps@lists.oasis-open.org/msg05412.html
419 - overide l10n.language
422 2m15.221s 1m58.740s 0m1.456s
424 1m55.480s 1m44.296s 0m2.125s
425 - override many template related to gentext
427 0m43.327s 0m38.594s 0m4.724s
430 0m33.282s 0m29.266s 0m4.012s
431 - removing the gentext calls for nav-bar alt tags does not help
434 - try plain docbook xslt to see if maybe we have bad xslt templates in the
435 customisation layer (gtk-doc.xsl)
437 - we could do the xinlcude processing once and use it for both html and pdf
438 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
440 0m4.846s 0m4.434s 0m0.147s
441 0m4.842s 0m4.386s 0m0.145s
444 time xmllint --nonet --xinclude ../tester-docs.xml >./tester-docs-all.xml
446 0m0.596s 0m0.546s 0m0.023s
448 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
450 0m4.167s 0m3.834s 0m0.106s
451 0m4.248s 0m3.851s 0m0.114s
454 time xmllint --nonet --c14n --xinclude ../tester-docs.xml >./tester-docs-all2.xml
457 0m0.700s 0m0.636s 0m0.034s
459 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
462 0m3.344s 0m3.026s 0m0.109s
463 0m3.372s 0m3.037s 0m0.115s
466 l ../tester-docs.xml ./tester-docs-all*.xml
468 - we could also try to compact the installed xslt
469 xmllint --nonet --c14n --xinclude gtk-doc.xsl | sed -ne '/<!--/ { :c; /-->/! { N; b c; }; /-->/s/<!--.*-->//g }; /^ *$/!p;' | sed '/^$/d' >gtk-doc.pre.xsl
470 - unfortunately there is no way to ask xsltproc to pre-transform an xslt, that could
472 - process xsl:import and xsl:include
474 http://sourceforge.net/projects/xsltc/
475 http://www.xmlhack.com/read.php?item=618
476 - extra xsltproc options:
477 --novalid: saves ~ 0.12 sec
480 - not really an issue, but we can improve by compiling the regexps
481 http://stackoverflow.com/questions/550258/does-the-o-modifier-for-perl-regular-expressions-still-provide-any-benefit
482 - we use $&, $', and $` in several places (comple match, pre-match and post-match).
483 Those are slow and once they are used a single time perl prepares them for every match operation.
484 Since perl 5.10 one can use the /p flag for matches where this is needed and then use
485 ${^PREMATCH} , ${^MATCH} and ${^POSTMATCH}
487 - http://blog.timbunce.org/2008/07/15/nytprof-v2-a-major-advance-in-perl-profilers/
488 perl -d:NYTProf gtkdoc-mkdb ...
490 firefox nytprof/index.html