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 == Makefiles ==
  29 sgml-build.stamp -> db-build.stamp
  30 sgml.stamp -> db.stamp
  31
  32 = More abbreviations =
  33 * expand urls (needds more work, see gtkdoc-mkdb : ExpandAbbreviations)
  34
  35 = Testing =
  36 cd test/gobject
  37 diff -u --exclude="Makefile*" docs docs-tmpl | diffstat
  38
  39 = Issues =
  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
  48
  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
  54
  55 = Output =
  56 * http://sagehill.net/docbookxsl/index.html
  57 * multipage-html
  58   * would be good to be able to have page titles as a concatenation of document
  59     name and page name (gtk+:GtkWIdget)
  60 * formats
  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
  68 * validation
  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
  72 * single page
  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
  77 * pdf
  78   * xmlto via passivetex
  79     xmlto --skip-validation pdf tester-docs.xml
  80   * fop
  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
  83   * xsltproc + fop
  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
  88     xmltex tester-docs.fo
  89   * jade
  90     docbook2pdf -e no-valid tester-docs.sgml
  91
  92   * bugs/problems/howto
  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
  96       - info
  97         http://www.tug.org/texlive/devsrc/Master/texmf-dist/doc/xmltex/passivetex/
  98     * fop
  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"
 104       - download offo
 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/
 107 * rtf
 108  ~/download/fop-0.94/fop -fo tester-docs.fo -rtf tester-docs.rtf
 109  * unrtf
 110    unrtf -t ps tester-docs.rtf >tester-docs.ps
 111    unrtf -t latex tester-docs.rtf >tester-docs.tex
 112    - bad output
 113 * man
 114   we shouldn't convert the whole document to man. We should convert e.g. tool
 115   sections to man pages.
 116
 117 = Indexes =
 118 * http://www.w3.org/TR/2003/WD-xinclude-20031110/#syntax
 119 <xi:include href="index-symbols.html">
 120   <xi:fallback><index /></xi:fallback>
 121 </xi:include>
 122 * index terms
 123   http://sourceforge.net/tracker/index.php?func=detail&aid=1986587&group_id=21935&atid=373747
 124
 125 * we could add smart navigation for index/glossary pages
 126   (like the subsections on the doc-pages)
 127
 128 = Cleanup =
 129 * can we deprecate title in the sectionfile and request people to have this in
 130   the SECTION comment?
 131
 132 = Warnings =
 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
 136     from the symbol.
 137
 138 = Markup =
 139 * protected scope
 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
 144
 145 = GIR =
 146 == scanning ==
 147 * ideas
 148   * use gir files
 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
 155 * perl and xml
 156   * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
 157 == binding docs ==
 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
 163 * questions
 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
 168 * devhelp
 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
 174 == installation ==
 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
 178
 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
 185
 186
 187 = docbook xml =
 188 Its tedious to write large amounts of docbook.
 189
 190 == more macros ==
 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
 205
 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
 211
 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.
 216
 217 == extract other bits and pieces ==
 218 === library api ==
 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 ===
 225
 226 === Wiki imports ===
 227
 228
 229
 230 = styling =
 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
 234
 235 tools:
 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
 240
 241   highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.xml -l -X -f -j2
 242
 243 some tips about styling code listings in html
 244 http://www.tjkdesign.com/articles/how_to_style_a_code_listing.asp
 245
 246 === process docbook ===
 247 if we highlight to docbook, we just get emphasis (bold)
 248 === process html ===
 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.
 252 problems:
 253 * in html we don't know the language anymore
 254   * add another div
 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 |[
 265
 266
 267
 268 = syntax =
 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.
 274
 275
 276 = documentation best practises #518427 =
 277 * we'd like offer a more complete skelleton
 278   * structure
 279   * docbook markup (part/chapter structure)
 280 * 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.
 285
 286   * examples
 287     * gobject in devhelp
 288       * concepts / api / tools / tutorial / related tools
 289     * gtk in devhelp
 290       * overview / api / migation / tools
 291     * qt reference docs in qt assistant
 292       * classes / overview / tutorial&examples
 293   * recommendation
 294     * front-page
 295       * table with details (http://www.docbook.org/tdg/en/html/bookinfo.html)
 296         (problem: what enclosing tag)
 297         Logo, Module Version
 298         Copyright and Legalnotice
 299         Links
 300         * homepage, mailing lists, irc channel
 301         * repository, source releases, bugtracker
 302       * TOC
 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
 311
 312 proposed structure in docbook xml:
 313 <book>
 314   <bookinfo>
 315   </bookinfo>
 316   <preface><title>Introduction</title>
 317     ...
 318   </preface>
 319   <part label="I"><title>xxx Overview</title>
 320     <xi:include href="building.xml" />
 321     ...
 322   </part>
 323   <reference label="II"><title>xxx Core Reference</title>
 324     <xi:include href="xml/gtkmain.xml" />
 325     ...
 326   </part>
 327   <reference label="III"><title>xxx Object Reference</title>
 328     <chapter><title>Object Hierarchy</title>
 329       <xi:include href="xml/tree_index.sgml" />
 330     </chapter>
 331     <chapter>...
 332   </part>
 333   <index>...</index>
 334 </book>
 335
 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
 341
 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)?
 350 == codesearch ==
 351 - google (code) link : http://www.google.com/codesearch?q=g_object_unref
 352 == live editing ==
 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).
 359 problems:
 360 - signal that this has been edited already?
 361 - support for xi:included examples
 362 - updating the checkout could be slow
 363
 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
 368 git bisect start
 369 git bisect good
 370 git bisect bad RELEASE-0_10_0
 371 git bisect run script.sh
 372
 373 script:
 374 #!/bin/sh
 375 make ctags
 376 grep "gst_caps_is_always_compatible" tags
 377
 378
 379 = performance =
 380 - timestamp each step
 381   make check >make.log
 382 - try CFLAGS=-O0 for compiling the scanner, no need to optimize it
 383   CFLAGS="-O0" make check >make.log
 384   safes max 0.5 sec.
 385 - xslt
 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
 394         glib/gobject
 395         real        user        sys
 396         2m15.221s   1m58.740s   0m1.456s
 397         >
 398         1m55.480s   1m44.296s   0m2.125s
 399       - removing the gentext calls for nav-bar alt tags does not help
 400
 401
 402   - try plain docbook xslt to see if maybe we have bad xslt templates in the
 403     customisation layer (gtk-doc.xsl)
 404
 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
 407     real        user       sys
 408     0m4.846s    0m4.434s   0m0.147s
 409     0m4.842s    0m4.386s   0m0.145s
 410
 411
 412     time xmllint --nonet --xinclude ../tester-docs.xml >./tester-docs-all.xml
 413     real        user       sys
 414     0m0.596s    0m0.546s   0m0.023s
 415
 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
 417     real        user       sys
 418     0m4.167s    0m3.834s   0m0.106s
 419     0m4.248s    0m3.851s   0m0.114s
 420
 421
 422     time xmllint --nonet --c14n --xinclude ../tester-docs.xml >./tester-docs-all2.xml
 423
 424     real        user       sys
 425     0m0.700s    0m0.636s   0m0.034s
 426
 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
 428
 429     real        user       sys
 430     0m3.344s    0m3.026s   0m0.109s
 431     0m3.372s    0m3.037s   0m0.115s
 432
 433
 434     l ../tester-docs.xml ./tester-docs-all*.xml
 435
 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
 439       - strip comments
 440       - process xsl:import and xsl:include
 441