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