TODO

   1
   2 The TODO list for the gtk-doc project is at Bugzilla,
   3 the bugtracking system of the GNOME project.
   4
   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. :-)
   8
   9 To put an other request on the TODO list, visit
  10  http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc
  11
  12 Also have a look at
  13  http://live.gnome.org/DocumentationProject/GtkDocFuture
  14 and join discussion about future features.
  15
  16
  17 Developers can also add items here :)
  18
  19 = Cleanups =
  20 == Tracing ==
  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
  24      turn that into
  25        [print __FILE__ . ":" . __LINE__ . ":" . ] or [#]
  26      should be a function and the function should support loglevels and an
  27        envar to enable/disable conditionally;
  28 == Files ==
  29 * can we deprecate title in the sectionfile and request people to have this in
  30   the SECTION comment?
  31
  32
  33 = More abbreviations =
  34 * expand urls (needds more work, see gtkdoc-mkdb : ExpandAbbreviations)
  35
  36
  37 = Testing =
  38 cd test/gobject
  39 diff -u --exclude="Makefile*" docs docs-tmpl | diffstat
  40
  41
  42 = Issues =
  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
  51
  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
  57
  58
  59 = Output =
  60 * http://sagehill.net/docbookxsl/index.html
  61 * multipage-html
  62   * would be good to be able to have page titles as a concatenation of document
  63     name and page name (gtk+:GtkWIdget)
  64 * formats
  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
  72 * validation
  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
  76 * single page
  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
  81 * rtf
  82  ~/download/fop-0.94/fop -fo tester-docs.fo -rtf tester-docs.rtf
  83  * unrtf
  84    unrtf -t ps tester-docs.rtf >tester-docs.ps
  85    unrtf -t latex tester-docs.rtf >tester-docs.tex
  86    - bad output
  87
  88
  89 = Warnings =
  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).
  95
  96 Lets take this warning for the example:
  97   "Symbol name not found at the start of the comment block."
  98
  99 Version 1: (template "warn-xxx!, warn-yyy!")
 100 --warn-missing-symbol-at-comment-start
 101 --no-warn-missing-symbol-at-comment-start
 102
 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
 108
 109 more warnings:
 110   - 'deprecated' deprecating 'features'
 111   - 'dummy-docs' check if symbol docs are very short and repeat mainly words
 112     from the symbol.
 113   - possible xrefs (e.g. adding a # or () would make it a successful xref)
 114
 115
 116 = Markup =
 117 * protected scope
 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
 122
 123 = GIR =
 124 == scanning ==
 125 * ideas
 126   * use gir files
 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
 133 * perl and xml
 134   * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
 135 == binding docs ==
 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
 141 * questions
 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
 146 * devhelp
 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
 152 == installation ==
 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
 156
 157
 158 = docbook xml =
 159 Its tedious to write large amounts of docbook.
 160
 161 == more macros ==
 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
 180
 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
 186
 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.
 191
 192 == extract other bits and pieces ==
 193 === library api ==
 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 ===
 200
 201 === Wiki imports ===
 202
 203
 204
 205 = styling =
 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
 209
 210 tools:
 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
 215
 216   highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.xml -l -X -f -j2
 217
 218 some tips about styling code listings in html
 219 http://www.tjkdesign.com/articles/how_to_style_a_code_listing.asp
 220
 221 === process docbook ===
 222 if we highlight to docbook, we just get emphasis (bold)
 223 === process html ===
 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.
 227 problems:
 228 * in html we don't know the language anymore
 229   * add another div
 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
 241
 242
 243 = 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.
 249
 250
 251 = documentation best practises #518427 =
 252 * we'd like offer a more complete skelleton
 253   * structure
 254   * docbook markup (part/chapter structure)
 255 * 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.
 260
 261   * examples
 262     * gobject in devhelp
 263       * concepts / api / tools / tutorial / related tools
 264     * gtk in devhelp
 265       * overview / api / migation / tools
 266     * qt reference docs in qt assistant
 267       * classes / overview / tutorial&examples
 268   * recommendation
 269     * front-page
 270       * table with details (http://www.docbook.org/tdg/en/html/bookinfo.html)
 271         (problem: what enclosing tag)
 272         Logo, Module Version
 273         Copyright and Legalnotice
 274         Links
 275         * homepage, mailing lists, irc channel
 276         * repository, source releases, bugtracker
 277       * TOC
 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
 286
 287 proposed structure in docbook xml:
 288 <book>
 289   <bookinfo>
 290   </bookinfo>
 291   <preface><title>Introduction</title>
 292     ...
 293   </preface>
 294   <part label="I"><title>xxx Overview</title>
 295     <xi:include href="building.xml" />
 296     ...
 297   </part>
 298   <reference label="II"><title>xxx Core Reference</title>
 299     <xi:include href="xml/gtkmain.xml" />
 300     ...
 301   </part>
 302   <reference label="III"><title>xxx Object Reference</title>
 303     <chapter><title>Object Hierarchy</title>
 304       <xi:include href="xml/tree_index.sgml" />
 305     </chapter>
 306     <chapter>...
 307   </part>
 308   <index>...</index>
 309 </book>
 310
 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
 316
 317
 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
 331
 332 == codesearch ==
 333 - google (code) link : http://www.google.com/codesearch?q=g_object_unref
 334 == live editing ==
 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).
 341 problems:
 342 - signal that this has been edited already?
 343 - support for xi:included examples
 344 - updating the checkout could be slow
 345
 346
 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
 351 git bisect start
 352 git bisect good
 353 git bisect bad RELEASE-0_10_0
 354 git bisect run script.sh
 355
 356 script:
 357 #!/bin/sh
 358 make ctags
 359 grep "gst_caps_is_always_compatible" tags
 360
 361
 362 = performance =
 363 - timestamp each step
 364   make check >make.log
 365 - try CFLAGS=-O0 for compiling the scanner, no need to optimize it
 366   CFLAGS="-O0" make check >make.log
 367   safes max 0.5 sec.
 368 - xslt
 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
 377         glib/gobject
 378         real        user        sys
 379         2m15.221s   1m58.740s   0m1.456s
 380         >
 381         1m55.480s   1m44.296s   0m2.125s
 382       - override many template related to gentext
 383         real        user        sys
 384         0m43.327s   0m38.594s   0m4.724s
 385         >
 386         real        user        sys
 387         0m33.282s   0m29.266s   0m4.012s
 388       - removing the gentext calls for nav-bar alt tags does not help
 389
 390
 391   - try plain docbook xslt to see if maybe we have bad xslt templates in the
 392     customisation layer (gtk-doc.xsl)
 393
 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
 396     real        user       sys
 397     0m4.846s    0m4.434s   0m0.147s
 398     0m4.842s    0m4.386s   0m0.145s
 399
 400
 401     time xmllint --nonet --xinclude ../tester-docs.xml >./tester-docs-all.xml
 402     real        user       sys
 403     0m0.596s    0m0.546s   0m0.023s
 404
 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
 406     real        user       sys
 407     0m4.167s    0m3.834s   0m0.106s
 408     0m4.248s    0m3.851s   0m0.114s
 409
 410
 411     time xmllint --nonet --c14n --xinclude ../tester-docs.xml >./tester-docs-all2.xml
 412
 413     real        user       sys
 414     0m0.700s    0m0.636s   0m0.034s
 415
 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
 417
 418     real        user       sys
 419     0m3.344s    0m3.026s   0m0.109s
 420     0m3.372s    0m3.037s   0m0.115s
 421
 422
 423     l ../tester-docs.xml ./tester-docs-all*.xml
 424
 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
 428       - strip comments
 429       - process xsl:import and xsl:include
 430   - compile xslt
 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
 435
 436 - perl regexps
 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}
 443