
The TODO list for the gtk-doc project is at Bugzilla,
the bugtracking system of the GNOME project.

Visit
 http://bugzilla.gnome.org/buglist.cgi?product=gtk-doc&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED
to see what is allready requested, or where you can help. :-)

To put an other request on the TODO list, visit
 http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc

Also have a look at
 http://live.gnome.org/DocumentationProject/GtkDocFuture
and join discussion about future features.


Developers can also add items here :)

= Tracing =
* there is a bunch of #print statements for tracing
  => add a sub Trace() to gtkdoc-common.pl
  => use @TRACE@ "..." and depending on configure flag
     turn that into
       [print __FILE__ . ":" . __LINE__ . ":" . ] or [#]
     should be a function and the function should support loglevels and an
       envar to enable/disable conditionally;

= More abbreviations =
* expand urls

= Testing =
cd test/gobject
diff -u --exclude="Makefile*" docs docs-tmpl | diffstat

= Issues =
* gtkdoc-fixxref makefile targets use $HTML_DIR
  * HTML_DIR: The directory where gtk-doc generated documentation is installed
    it comes from gtk-doc.m4 (--with-html-dir) but has no default
  * automake exports $htmldir which is by default:
    ${prefix}/share/doc/${PACKAGE_TARNAME}
  * the Makefile uses $(DESTDIR)$(TARGET_DIR)
    where TARGET_DIR = $(HTML_DIR)/$(DOC_MODULE)
    http://www.gnu.org/software/libtool/manual/automake/DESTDIR.html
    
* $MODULE-unused.txt is produced in gtkdoc-mktmpl only
  * we won't find unused doc blobs in notmpl build
  * we should add mktmpl::CheckAllDeclarationsOutput() to mkdb (call it after
    OutputSGML), but only call it if there is no tmpl dir or
    remove writing the unused.txt in mktmpl.txt

= Output =
* http://sagehill.net/docbookxsl/index.html
* multipage-html
  * would be good to be able to have page titles as a concatenation of document
    name and page name (gtk+:GtkWIdget)
* formats
  http://bugzilla.gnome.org/show_bug.cgi?id=531572
  http://bugzilla.gnome.org/show_bug.cgi?id=466535
  we need more configure options in gtk-doc.m4:
  --(enable|disable)-gtk-doc-(html|pdf|man|html-single|rtf)
  - html : enabled by default
  - html-single : is single page html
* validation
    xmllint --noout --xinclude --postvalid tester-docs.xml
    xmllint --noout --postvalid tester-docs.fo --dtdvalid file://$HOME/download/fo.dtd
    - fo.dtd : http://www.renderx.com/Tests/validator/fo.zip
* single page
  xsltproc  --nonet --xinclude -o gtk-docs.html /home/ensonic/projects/gtk-doc/gtk-doc-single.xsl  gtk-docs.sgml
* pdf
  * xmlto via passivetex
    xmlto --skip-validation pdf tester-docs.xml
  * fop
    ~/download/fop-0.95beta/fop -xsl /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl -xml tester-docs.xml -pdf tester-docs.pdf 
    ~/download/fop-0.94/fop  -xsl /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl -xml tester-docs.xml -pdf tester-docs.pdf
  * xsltproc + fop
    xsltproc  --nonet --xinclude -o tester-docs.fo ../../../gtk-doc-fo.xsl tester-docs.xml
    ~/download/fop-0.94/fop -fo tester-docs.fo -pdf tester-docs.pdf
  * xsltproc + passivetex
    pdflatex "&pdfxmltex" tester-docs.fo
    xmltex tester-docs.fo

  * bugs/problems/howto
    * xmlto via passivetex
      http://bugs.gentoo.org/show_bug.cgi?id=224937
      http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=310148
      - info
        http://www.tug.org/texlive/devsrc/Master/texmf-dist/doc/xmltex/passivetex/
    * fop
      - download fop
        http://mirror.eunet.fi/apache/xmlgraphics/fop/binaries/
        http://xmlgraphics.apache.org/fop/0.94/running.html
        export FOP_OPTS="-Dhttp.proxyHost=eswebproxy00.europe.nokia.com -Dhttp.proxyPort=8080"
      - download offo
        http://sourceforge.net/project/showfiles.php?group_id=116740&package_id=129569&release_id=267101
        and copy fop-hyph.jar to fop-0.9*/lib/
* rtf
 ~/download/fop-0.94/fop -fo tester-docs.fo -rtf tester-docs.rtf
 * unrtf
   unrtf -t ps tester-docs.rtf >tester-docs.ps
   unrtf -t latex tester-docs.rtf >tester-docs.tex
   - bad output

= Indexes =
* http://www.w3.org/TR/2003/WD-xinclude-20031110/#syntax
<xi:include href="index-symbols.html">
  <xi:fallback><index /></xi:fallback>
</xi:include>
* index terms
  http://sourceforge.net/tracker/index.php?func=detail&aid=1986587&group_id=21935&atid=373747

* we could add smart navigation for index/glossary pages
  (like the subsections on the doc-pages)
  
= Cleanup =
* can we deprecate title in the sectionfile and request people to have this in
  the SECTION comment?

= Warnings =
* add some -Wxxx parameters to help qa work
  - 'deprecated' deprecating 'features'
  - 'dummy-docs' check if symbol docs are very short and repeat mainly words
    from the symbol.

= GIR =
== scanning ==
* ideas
  * use gir files
    1) replace gtkdoc-scan/gtkdoc-scangobject by gtkdoc-gir and output the classical files
    2) patch gtkdoc-mkdb to read stuff from gir instead of classical files
  * if gir-files would have the comments too:
    * we could even drop scanning the sources
    * IDEs could use the gir-files to show doc-tooltips for symbols  
* perl and xml
  * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
== handling the annotations ==
* figure out how to install default glossary
== binding docs ==
* simmillar workflow to gettext
* add gtkdoc-mk??? to generate binding doc templates
  * have c-comments there as comments
  * when updating templates, mark sections that have changed as fuzzy
* add options to gtkdoc-mkdb to build docbook from those templates
* questions
  * could we use the tmpl file mechanism?
  * directory structure?
    * we need to list the languages like ALL_LINGUAS for translations
    * we need to create subdirs for binding docs, ideally we use one for 'C' as well
* devhelp
  * devhelp files need a language attribute in the book-tag
    language={C,C++,JavaScript,Perl,Python,...}
  * devhelp could show a selector for the language
  * need to get existing python/~mm docs to use it, gtk-doc could output
    language=C for own docs 
== installation ==
* need to install each book with a prefix
* would be good to have a language attribute in book tag to allow filter by language
* look at /usr/share/gtk-doc/html/pygobject/index.html

