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 :)
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
25 [print __FILE__ . ":" . __LINE__ . ":" . ] or [#]
26 should be a function and the function should support loglevels and an
27 envar to enable/disable conditionally;
29 sgml-build.stamp -> db-build.stamp
30 sgml.stamp -> db.stamp
32 = More abbreviations =
33 * expand urls (needds more work, see gtkdoc-mkdb : ExpandAbbreviations)
37 diff -u --exclude="Makefile*" docs docs-tmpl | diffstat
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
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
56 * http://sagehill.net/docbookxsl/index.html
58 * would be good to be able to have page titles as a concatenation of document
59 name and page name (gtk+:GtkWIdget)
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
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
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
78 * xmlto via passivetex
79 xmlto --skip-validation pdf tester-docs.xml
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
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
90 docbook2pdf -e no-valid tester-docs.sgml
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
97 http://www.tug.org/texlive/devsrc/Master/texmf-dist/doc/xmltex/passivetex/
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"
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/
108 ~/download/fop-0.94/fop -fo tester-docs.fo -rtf tester-docs.rtf
110 unrtf -t ps tester-docs.rtf >tester-docs.ps
111 unrtf -t latex tester-docs.rtf >tester-docs.tex
114 we shouldn't convert the whole document to man. We should convert e.g. tool
115 sections to man pages.
118 * http://www.w3.org/TR/2003/WD-xinclude-20031110/#syntax
119 <xi:include href="index-symbols.html">
120 <xi:fallback><index /></xi:fallback>
123 http://sourceforge.net/tracker/index.php?func=detail&aid=1986587&group_id=21935&atid=373747
125 * we could add smart navigation for index/glossary pages
126 (like the subsections on the doc-pages)
129 * can we deprecate title in the sectionfile and request people to have this in
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
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
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
156 * http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html
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
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
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
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
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
188 Its tedious to write large amounts of docbook.
191 We need parametric, user definable macros.
192 |[ ... ]| - programlistings
193 |macro(arg1,arg2,...)[ ... ]| - call macro, pass args as parameters, content
194 of [] on stdin or as a file, get output on stdout or file and replace the macro
196 === example macros ===
197 |highlight(c)[...]| - highlight source code
198 |dot(abc.svg)[...]| - format dot graph and include result as mediaobject
200 === where to define macros ===
201 * system wide and with the package, <prefix>/share/gtk-doc/macros, $(srcdir)
202 * prefix for custom macros?
204 == ascii doc as a frontend ==
205 Can we offer integration with asciidoc (http://www.methods.co.nz/asciidoc/)?
206 This way the master document could be written much easier. It would be cool if
207 we could use the asciidoc markup in source-comments also.
209 == extract other bits and pieces ==
211 gtkdoc-scan could be obsoleted and gtkdoc-mkdb would build docbook fragemnts for
212 api docs and their indexes
213 === DBUs Interfaces ===
214 http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html
215 http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus
216 === GConf schemas ===
223 == source code examples==
224 http://bugzilla.gnome.org/show_bug.cgi?id=536928
225 We could also run a postprocessing script in gtkdoc-mkhtml/gtkdoc-fixxref
228 source-highlight (/usr/bin/source-highlight)
229 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.html -n -t4 -sc
230 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.html -n -t4 -sc -cstyle.css --no-doc
231 source-highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.xml -n -t4 -sc -f docbook
233 highlight -itests/gobject/examples/gobject.c -o$HOME/temp/gobject.xml -l -X -f -j2
235 some tips about styling code listings in html
236 http://www.tjkdesign.com/articles/how_to_style_a_code_listing.asp
238 === process docbook ===
239 if we highlight to docbook, we just get emphasis (bold)
241 if we hightlight to html we get colors, we need to check what tags we should process though:
242 <pre class="programlisting"> is used for all code boxes.
243 <div class="informalexample"><pre class="programlisting"> is used for examples.
245 * in html we don't know the language anymore
247 * with source-highlight, constants and types are not markedup.
248 for types we might need to build an own lang file dynamically and include
249 /usr/share/source-highlight/c.lang
250 === |[ ... ]| does not allow setting the language ===
251 * check for vi/emacs/jedit modelines
252 jedit: http://www.jedit.org/users-guide/buffer-local.html
253 vim: http://vim.wikia.com/wiki/Modeline_magic
254 emacs: http://www.delorie.com/gnu/docs/emacs/emacs_486.html
255 * allow <!-- language="C" --> comments after |[
256 * we need to catch those when processing the docbook and expanding the |[
261 == wildcards in symbol names ==
262 Somtimes one defines a set of function and macros with very simillar purpose, e.g.
263 READ_INT8, READ_INT16, READ_INT32. It would be great to allow documenting a symbol
264 READ_INT* instead of 3 docs which are copy'n'pasted anyway. In the output we will have
265 all matching declarations in one source listing. Multiple wildcards are okay.
268 = documentation best practises #518427 =
269 * we'd like offer a more complete skelleton
271 * docbook markup (part/chapter structure)
273 Sugested structure for api-docs.
274 Idea is to have more content that api reference. It would be good to have a
275 gnome-platform document in devhelp, so that we could xref that instead of
276 explaining 100 times how to use pkg-config.
280 * concepts / api / tools / tutorial / related tools
282 * overview / api / migation / tools
283 * qt reference docs in qt assistant
284 * classes / overview / tutorial&examples
287 * table with details (http://www.docbook.org/tdg/en/html/bookinfo.html)
288 (problem: what enclosing tag)
290 Copyright and Legalnotice
292 * homepage, mailing lists, irc channel
293 * repository, source releases, bugtracker
295 * introduction - what is is about
296 * concepts - explain basic ideas and terminology
297 * development - how to build and run, env-vars, different platforms
298 * api - classic api docs
299 * tutorial & examples - integrated to keep it up-to-date and cross referenced
300 * migration - how to for api changes, deprecations
301 * (releated) tools - tools part of the package or recommended for development
302 * indexes - api-index, depretations, new api since xxx
304 proposed structure in docbook xml:
308 <preface><title>Introduction</title>
311 <part label="I"><title>xxx Overview</title>
312 <xi:include href="building.xml" />
315 <reference label="II"><title>xxx Core Reference</title>
316 <xi:include href="xml/gtkmain.xml" />
319 <reference label="III"><title>xxx Object Reference</title>
320 <chapter><title>Object Hierarchy</title>
321 <xi:include href="xml/tree_index.sgml" />
328 some things to check:
329 * gtk,glib: can we make a <part> for the glosary and index's (according to docbook, yes)
330 should we use <appendix>? its like a chapter.
331 * gobject: uses a <preface> for introductions
332 * gobject: uses <reference> as a parent for the xi:includeed <refentry> docs
334 = extra link for symbols =
335 need options for configure:
336 --enable-gtk-doc-codesearch-links
337 --enable-gtk-doc-liveedit-links
338 == viewvc,cgit,... ==
339 - link to some online service for the code
340 - problem: most don't have local anchors for the symbols
341 - where to set the uri (in the document, like for online url)?
343 - google (code) link : http://www.google.com/codesearch?q=g_object_unref
345 The idea is to have an 'edit' link in an online version of the docs (build from
346 head development version) per doc-entry (symbols and section).
347 The link goes to a cgi and that gets following parameters: docmodule,symbol.
348 E.g. http://library.gnome.org/devel/references/edit?docmodule=glib&symbol=g_new
349 The cgi would need a hashmap to get from docmodule to the way to check it out
350 (ideally it has a recent checkout and only updates it).
352 - signal that this has been edited already?
353 - support for xi:included examples
354 - updating the checkout could be slow
356 = fix missing since docs =
357 cd gstreamer/gstreamer/docs/gst
358 gtkdoc-mkdb --module=gstreamer --source-dir=../../gst --outputsymbolswithoutsince
359 cd gstreamer/gstreamer/src
362 git bisect bad RELEASE-0_10_0
363 git bisect run script.sh
368 grep "gst_caps_is_always_compatible" tags