| 1 |
The TODO list for the gtk-doc project is at Bugzilla, |
| 2 |
the bugtracking system of the GNOME project. |
| 3 |
|
| 4 |
Visit |
| 5 |
http://bugzilla.gnome.org/buglist.cgi?product=gtk-doc&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED |
| 6 |
to see what is already requested, or where you can help. :-) |
| 7 |
|
| 8 |
To put an other request on the TODO list, visit |
| 9 |
http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc |
| 10 |
|
| 11 |
Also have a look at |
| 12 |
http://live.gnome.org/DocumentationProject/GtkDocFuture |
| 13 |
and join discussion about future features. |
| 14 |
|
| 15 |
|
| 16 |
Developers can also add items here :) |
| 17 |
|
| 18 |
= Less files to manually edit = |
| 19 |
The goal is that we configure gtk-doc in configure.ac and Makefile.am and |
| 20 |
document the code in the sources. Right no we also have to edit a bunch of extra |
| 21 |
files: |
| 22 |
* $(DOC_MODULE).types |
| 23 |
* $(DOC_MODULE)-docs.xml |
| 24 |
* $(DOC_MODULE)-sections.txt |
| 25 |
|
| 26 |
== .types == |
| 27 |
|
| 28 |
* using SCAN_OPTION="--rebuild-types" can be used to avoid maintaining the types |
| 29 |
file |
| 30 |
* we need to check if this works well for all kind of _types (e.g. boxed) |
| 31 |
https://bugzilla.gnome.org/show_bug.cgi?id=605025 |
| 32 |
|
| 33 |
== -section.txt == |
| 34 |
https://bugzilla.gnome.org/show_bug.cgi?id=646094 |
| 35 |
|
| 36 |
* using SCAN_OPTION="--rebuild-sections" can be used to use the audogenerated |
| 37 |
sections file |
| 38 |
* when scanning a header file, everything of the header and the respective .c |
| 39 |
file will be put to one section |
| 40 |
* symbols can be hidden using __GTK_DOC_IGNORE__ |
| 41 |
|
| 42 |
* we need comment markup to override the section |
| 43 |
e.g.: " * InSection: xxxx" |
| 44 |
this needs gtkdoc-mkdb::ScanSourceFile to understand a new tag, which |
| 45 |
otherwise would appear as verbatim in the sources |
| 46 |
* if one has "@InSection: xxxx" in a section comment we could patch the |
| 47 |
main.xml file and insert then xi:include line (would possibly rely on a |
| 48 |
special comment-pair there, we might also need to rewrite these |
| 49 |
auto-generated xi:includes every time as the placements could have been |
| 50 |
changed, or we have a xi:include for each chapter, that we regenerate). |
| 51 |
* we need a way to specify subsections (Standard, Private) |
| 52 |
this could be done in the SECTION comment |
| 53 |
e.g.: "@HideSymbols: <list-of-symbols-to-hide> |
| 54 |
* we could allow to have a SUBSECTION:xxx comment block too |
| 55 |
but then we list all the symbols here to override the auto-section placement |
| 56 |
* if we want to avoid the "InSection in symbol docs we could also have |
| 57 |
e.g.: "@ExtraSymbols: <list-of-symbols-to-include> |
| 58 |
* documented symbols that are in a file without section comment and do not |
| 59 |
appear in "@ExtraSymbols", "@HideSymbols" would go to unused.txt |
| 60 |
* shall we deprecated the unused sub-sections? |
| 61 |
* can we have both at the same time (for migration) |
| 62 |
* yes, read section-file first and add/override from inline comments |
| 63 |
|
| 64 |
|
| 65 |
= More abbreviations = |
| 66 |
* expand urls (needds more work, see gtkdoc-mkdb : ExpandAbbreviations) |
| 67 |
|
| 68 |
|
| 69 |
= Running = |
| 70 |
gtk-doc is using a makefile with several targets to get from sources to docs. It |
| 71 |
uses makefile variables for configuration. |
| 72 |
It might be easier to have a gtkdoc tool that can run the other gtkdoc tools |
| 73 |
in the right order (ev. by importing them as modules). This could handle a few |
| 74 |
things nicer that the makefiles don't do well. This would also make it easy to |
| 75 |
run it manually or integrate into other build systems. |
| 76 |
|
| 77 |
|
| 78 |
= Intermediate files = |
| 79 |
Can we change the intermediate files into e.g. json or yaml so that we can just |
| 80 |
load it from python? |
| 81 |
|
| 82 |
Can we drop the decl-list.txt file (or rename to make sure this is what a |
| 83 |
generated section.txt would look like) |
| 84 |
|
| 85 |
|
| 86 |
= Issues = |
| 87 |
* gtkdoc-fixxref makefile targets use $HTML_DIR |
| 88 |
* HTML_DIR: The directory where gtk-doc generated documentation is installed |
| 89 |
it comes from gtk-doc.m4 (--with-html-dir) but has no default |
| 90 |
* automake exports $htmldir which is by default: |
| 91 |
${prefix}/share/doc/${PACKAGE_TARNAME} |
| 92 |
* the Makefile uses $(DESTDIR)$(TARGET_DIR) |
| 93 |
where TARGET_DIR = $(HTML_DIR)/$(DOC_MODULE) |
| 94 |
http://www.gnu.org/software/libtool/manual/automake/DESTDIR.html |
| 95 |
* gtkdoc does not know about module versions |
| 96 |
* this is causing troubles when multiple library versions are installed |
| 97 |
(gtk+-{2,3}, gstreamer-{0.8,0.10,1.0} |
| 98 |
* right now gtk-doc is xreffing against any <module>/*.devhelp2 found |
| 99 |
* just using the one with a higher number won't work |
| 100 |
|
| 101 |
|
| 102 |
= Extensibility = |
| 103 |
We'd like to extend gtk-doc to understand conventions/features of gobject libs. |
| 104 |
Ideally libs register their extension hooks, so that other libs that use these |
| 105 |
libs can benefit from the extensions too. |
| 106 |
|
| 107 |
== custom get_types collector == |
| 108 |
- the default method takes the types from a type file |
| 109 |
- gstreamer plugin docs take a list of types from the gst plugin registry |
| 110 |
|
| 111 |
== custom properties == |
| 112 |
- gtk has style and child properties |
| 113 |
|
| 114 |
== extra gobject property flags == |
| 115 |
- gstreamer has 'controllable' properties |
| 116 |
|
| 117 |
= Output = |
| 118 |
* http://sagehill.net/docbookxsl/index.html |
| 119 |
* multipage-html |
| 120 |
* would be good to be able to have page titles as a concatenation of document |
| 121 |
name and page name (gtk+:GtkWIdget) |
| 122 |
* formats |
| 123 |
http://bugzilla.gnome.org/show_bug.cgi?id=466535 : pdf |
| 124 |
http://bugzilla.gnome.org/show_bug.cgi?id=467488 : man |
| 125 |
we need more configure options in gtk-doc.m4: |
| 126 |
--(enable|disable)-gtk-doc-(html|pdf|man) |
| 127 |
- html : enabled by default |
| 128 |
* validation |
| 129 |
xmllint --noout --xinclude --postvalid tester-docs.xml |
| 130 |
xmllint --noout --postvalid tester-docs.fo --dtdvalid file://$HOME/download/fo.dtd |
| 131 |
- fo.dtd : http://www.renderx.com/Tests/validator/fo.zip |
| 132 |
|
| 133 |
= Warnings = |
| 134 |
Bugzilla has some requests for extra warnings. We should support a common |
| 135 |
commandline option(s) in all tools to enable/disable the warnings. The makefiles |
| 136 |
should pass the flags from an env-var (GTKDOC_OPTIONS). The env-var should be |
| 137 |
used after the regular flags, so that the env-var can override hardcoded |
| 138 |
settings (in Makefile.am). |
| 139 |
|
| 140 |
Lets take this warning for the example: |
| 141 |
"Symbol name not found at the start of the comment block." |
| 142 |
|
| 143 |
Version 1: (template "warn-xxx!, warn-yyy!") |
| 144 |
--warn-missing-symbol-at-comment-start |
| 145 |
--no-warn-missing-symbol-at-comment-start |
| 146 |
|
| 147 |
Version 2: (template "warn:s@") |
| 148 |
-Wmissing-symbol-at-comment-start |
| 149 |
-Wno-missing-symbol-at-comment-start |
| 150 |
-warn missing-symbol-at-comment-start |
| 151 |
-warn no-missing-symbol-at-comment-start |
| 152 |
|
| 153 |
more warnings: |
| 154 |
- 'deprecated' deprecating 'features' |
| 155 |
- 'dummy-docs' check if symbol docs are very short and repeat mainly words |
| 156 |
from the symbol. |
| 157 |
- possible xrefs (e.g. adding a # or () would make it a successful xref) |
| 158 |
|
| 159 |
|
| 160 |
= GIR = |
| 161 |
== scanning == |
| 162 |
* ideas |
| 163 |
* use gir files |
| 164 |
1) replace gtkdoc-scan/gtkdoc-scangobject by gtkdoc-gir and output the classical files or |
| 165 |
patch gtkdoc-scan/gtkdoc-scangobject to output gir files |
| 166 |
2) patch gtkdoc-mkdb to read stuff from gir instead of classical files |
| 167 |
* if gir-files would have the comments too (they are getting this now): |
| 168 |
* we could even drop scanning the sources |
| 169 |
* IDEs could use the gir-files to show doc-tooltips for symbols |
| 170 |
* we might need yet another makefile flavour to use gir files |
| 171 |
* perl and xml |
| 172 |
* http://www.xml.com/pub/a/2001/04/18/perlxmlqstart1.html |
| 173 |
|
| 174 |
== binding docs == |
| 175 |
* simmillar workflow to gettext |
| 176 |
* add gtkdoc-mk??? to generate binding doc templates |
| 177 |
* have c-comments there as comments |
| 178 |
* when updating templates, mark sections that have changed as fuzzy |
| 179 |
* add options to gtkdoc-mkdb to build docbook from those templates |
| 180 |
* questions |
| 181 |
* could we use the tmpl file mechanism? |
| 182 |
* directory structure? |
| 183 |
* we need to list the languages like ALL_LINGUAS for translations |
| 184 |
* we need to create subdirs for binding docs, ideally we use one for 'C' as well |
| 185 |
* devhelp |
| 186 |
* devhelp files need a language attribute in the book-tag |
| 187 |
language={C,C++,JavaScript,Perl,Python,...} |
| 188 |
* devhelp could show a selector for the language |
| 189 |
* need to get existing python/~mm docs to use it, gtk-doc could output |
| 190 |
language=C for own docs |
| 191 |
|
| 192 |
=== installation === |
| 193 |
* need to install each book with a prefix |
| 194 |
* would be good to have a language attribute in book tag to allow filter by language |
| 195 |
* look at /usr/share/gtk-doc/html/pygobject/index.html |
| 196 |
|
| 197 |
|
| 198 |
= external processors = |
| 199 |
We need parametric, user definable macros. |
| 200 |
|[ ... ]| - programlistings |
| 201 |
|macro(arg1,arg2,...)[ ... ]| - call macro |
| 202 |
- pass args as parameters (on the commandline) |
| 203 |
- pass some gtk-doc vars in environment |
| 204 |
(gtk-doc version, module, srcdir, buildir) |
| 205 |
- content of [] on stdin or as a file |
| 206 |
- get output on stdout or file |
| 207 |
- and replace the macro with it |
| 208 |
The changes could be made in gtkdoc-mkdb::ExpandAbbreviations() |
| 209 |
== example macros == |
| 210 |
|highlight(c)[...]| - highlight source code for a specific language (c) |
| 211 |
- what will this output? preformatted html to be xincluded? |
| 212 |
- we could have macros for each format, the docbook xml macro would leave |
| 213 |
enough traces in the html so that a html macro can continue |
| 214 |
|dot(svg)[...]| - format dot graph and include result as mediaobject (in svg format) |
| 215 |
|ditta(svg)[...]| - parse ascii art and include result as mediaobject (in svg format) |
| 216 |
- we need to generate a filename for the image or use anoter parameter |
| 217 |
|
| 218 |
== where to define macros == |
| 219 |
* system wide and with the package, <prefix>/share/gtk-doc/macros, $(srcdir) |
| 220 |
* prefix for custom macros? |
| 221 |
* we could require stdin for input and stdout for output, the wrapper for the |
| 222 |
actual tool can ensure the convention |
| 223 |
|
| 224 |
|
| 225 |
= styling = |
| 226 |
=== process html === |
| 227 |
if we highlight to html we get colors, we need to check what tags we should process though: |
| 228 |
<pre class="programlisting"> is used for all code boxes. |
| 229 |
<div class="informalexample"><pre class="programlisting"> is used for examples. |
| 230 |
problems: |
| 231 |
* in html we don't know the language anymore |
| 232 |
* add another div |
| 233 |
* with source-highlight, constants and types are not markedup. |
| 234 |
for types we might need to build an own lang file dynamically and include |
| 235 |
/usr/share/source-highlight/c.lang |
| 236 |
=== |[ ... ]| does not allow setting the language === |
| 237 |
* check for vi/emacs/jedit modelines |
| 238 |
jedit: http://www.jedit.org/users-guide/buffer-local.html |
| 239 |
vim: http://vim.wikia.com/wiki/Modeline_magic |
| 240 |
emacs: http://www.delorie.com/gnu/docs/emacs/emacs_486.html |
| 241 |
* allow <!-- language="C" --> comments after |[ |
| 242 |
* we need to catch those when processing the docbook and expanding the |[ |
| 243 |
* require new macro syntax |
| 244 |
|
| 245 |
== show inherited api == |
| 246 |
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? |
| 247 |
could we do that using javascript and some other magic? |
| 248 |
|
| 249 |
|
| 250 |
= Markup = |
| 251 |
== tags == |
| 252 |
* to document the api-life cycle we have: since, deprecated and stability: |
| 253 |
* other things we might want to specify: |
| 254 |
* multi-threading safety: mt-safe, use-with-lock <lock> |
| 255 |
|
| 256 |
== protected scope == |
| 257 |
* we can have /* < protected > */ in classes |
| 258 |
* we can have <SUBSECTION Protected> in -section.txt |
| 259 |
* ideally we have Scope: {Public, Protected, Private} supported in doc comments |
| 260 |
* there is a bug for gir, https://bugzilla.gnome.org/show_bug.cgi?id=594125 |
| 261 |
|
| 262 |
== wildcards in symbol names == |
| 263 |
Sometimes one defines a set of function and macros with very similar purpose, e.g. |
| 264 |
READ_INT8, READ_INT16, READ_INT32. It would be great to allow documenting a symbol |
| 265 |
READ_INT* instead of 3 docs which are copy'n'pasted anyway. In the output we will have |
| 266 |
all matching declarations in one source listing. Multiple wildcards are okay. |
| 267 |
|
| 268 |
|
| 269 |
= documentation best practises #518427 = |
| 270 |
* we'd like offer a more complete skelleton |
| 271 |
* structure |
| 272 |
* docbook markup (part/chapter structure) |
| 273 |
* structure |
| 274 |
Suggested structure for api-docs. |
| 275 |
Idea is to have more content that api reference. It would be good to have a |
| 276 |
gnome-platform document in devhelp, so that we could xref that instead of |
| 277 |
explaining 100 times how to use pkg-config. |
| 278 |
|
| 279 |
* examples |
| 280 |
* gobject in devhelp |
| 281 |
* concepts / api / tools / tutorial / related tools |
| 282 |
* gtk in devhelp |
| 283 |
* overview / api / migation / tools |
| 284 |
* qt reference docs in qt assistant |
| 285 |
* classes / overview / tutorial&examples |
| 286 |
* recommendation |
| 287 |
* front-page |
| 288 |
* table with details (http://www.docbook.org/tdg/en/html/bookinfo.html) |
| 289 |
(problem: what enclosing tag) |
| 290 |
Logo, Module Version |
| 291 |
Copyright and Legalnotice |
| 292 |
Links |
| 293 |
* homepage, mailing lists, irc channel |
| 294 |
* repository, source releases, bugtracker |
| 295 |
* TOC |
| 296 |
* introduction - what is is about |
| 297 |
* concepts - explain basic ideas and terminology |
| 298 |
* development - how to build and run, env-vars, different platforms |
| 299 |
* api - classic api docs |
| 300 |
* tutorial & examples - integrated to keep it up-to-date and cross referenced |
| 301 |
* migration - how to for api changes, deprecations |
| 302 |
* (related) tools - tools part of the package or recommended for development |
| 303 |
* indexes - api-index, depretations, new api since xxx |
| 304 |
|
| 305 |
proposed structure in docbook xml: |
| 306 |
<book> |
| 307 |
<bookinfo> |
| 308 |
</bookinfo> |
| 309 |
<preface><title>Introduction</title> |
| 310 |
... |
| 311 |
</preface> |
| 312 |
<part label="I"><title>xxx Overview</title> |
| 313 |
<xi:include href="building.xml" /> |
| 314 |
... |
| 315 |
</part> |
| 316 |
<reference label="II"><title>xxx Core Reference</title> |
| 317 |
<xi:include href="xml/gtkmain.xml" /> |
| 318 |
... |
| 319 |
</part> |
| 320 |
<reference label="III"><title>xxx Object Reference</title> |
| 321 |
<chapter><title>Object Hierarchy</title> |
| 322 |
<xi:include href="xml/tree_index.sgml" /> |
| 323 |
</chapter> |
| 324 |
<chapter>... |
| 325 |
</part> |
| 326 |
<index>...</index> |
| 327 |
</book> |
| 328 |
|
| 329 |
some things to check: |
| 330 |
* gtk,glib: can we make a <part> for the glosary and index's (according to docbook, yes) |
| 331 |
should we use <appendix>? its like a chapter. |
| 332 |
* gobject: uses a <preface> for introductions |
| 333 |
* gobject: uses <reference> as a parent for the xi:includeed <refentry> docs |
| 334 |
|
| 335 |
|
| 336 |
= extra link for symbols = |
| 337 |
need options for configure: |
| 338 |
--enable-gtk-doc-codesearch-links |
| 339 |
--enable-gtk-doc-liveedit-links |
| 340 |
== viewvc,cgit,... == |
| 341 |
- link to some online service for the code |
| 342 |
- problem: most don't have local anchors for the symbols |
| 343 |
- where to set the uri (in the document, like for online url)? |
| 344 |
- what about a template URL containing a %s for the "path/file" or a special macro |
| 345 |
http://svn.gnome.org/viewvc/gtk-doc/trunk/tests/gobject/src/gobject.c?view=markup |
| 346 |
http://buzztard.svn.sourceforge.net/viewvc/buzztard/trunk/buzztard/src/lib/core/core.c?view=markup |
| 347 |
- unfortunately we can't link to symbols (only lines) |
| 348 |
- linking to files is difficult as in gtkdoc we have modules |
| 349 |
|
| 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 |
|
| 365 |
= fix missing since docs = |
| 366 |
cd gstreamer/gstreamer/docs/gst |
| 367 |
gtkdoc-mkdb --module=gstreamer --source-dir=../../gst --outputsymbolswithoutsince |
| 368 |
cd gstreamer/gstreamer/src |
| 369 |
git bisect start |
| 370 |
git bisect good |
| 371 |
git bisect bad RELEASE-0_10_0 |
| 372 |
git bisect run script.sh |
| 373 |
|
| 374 |
script: |
| 375 |
#!/bin/sh |
| 376 |
make ctags |
| 377 |
grep "gst_caps_is_always_compatible" tags |
| 378 |
|
| 379 |
|
| 380 |
= performance = |
| 381 |
- timestamp each step |
| 382 |
make check >make.log |
| 383 |
- try CFLAGS=-O0 for compiling the scanner, no need to optimize it |
| 384 |
CFLAGS="-O0" make check >make.log |
| 385 |
safes max 0.5 sec. |
| 386 |
- xslt |
| 387 |
http://docbook2x.sourceforge.net/latest/doc/performance.html |
| 388 |
- play with xsltproc --profile --verbose --timing |
| 389 |
cd tests/gobject/docs/html |
| 390 |
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 |
| 391 |
- l10n.language is slow |
| 392 |
bug: https://sourceforge.net/tracker/index.php?func=detail&aid=2918673&group_id=21935&atid=373750 |
| 393 |
see: http://www.mail-archive.com/[email protected]/msg05412.html |
| 394 |
- override l10n.language |
| 395 |
glib/gobject |
| 396 |
real user sys |
| 397 |
2m15.221s 1m58.740s 0m1.456s |
| 398 |
> |
| 399 |
1m55.480s 1m44.296s 0m2.125s |
| 400 |
- override many template related to gentext |
| 401 |
real user sys |
| 402 |
0m43.327s 0m38.594s 0m4.724s |
| 403 |
> |
| 404 |
real user sys |
| 405 |
0m33.282s 0m29.266s 0m4.012s |
| 406 |
- removing the gentext calls for nav-bar alt tags does not help |
| 407 |
|
| 408 |
- we could do the xinlcude processing once and use it for both html and pdf |
| 409 |
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 |
| 410 |
real user sys |
| 411 |
0m4.846s 0m4.434s 0m0.147s |
| 412 |
0m4.842s 0m4.386s 0m0.145s |
| 413 |
|
| 414 |
|
| 415 |
time xmllint --nonet --xinclude ../tester-docs.xml >./tester-docs-all.xml |
| 416 |
real user sys |
| 417 |
0m0.596s 0m0.546s 0m0.023s |
| 418 |
|
| 419 |
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 |
| 420 |
real user sys |
| 421 |
0m4.167s 0m3.834s 0m0.106s |
| 422 |
0m4.248s 0m3.851s 0m0.114s |
| 423 |
|
| 424 |
|
| 425 |
time xmllint --nonet --c14n --xinclude ../tester-docs.xml >./tester-docs-all2.xml |
| 426 |
|
| 427 |
real user sys |
| 428 |
0m0.700s 0m0.636s 0m0.034s |
| 429 |
|
| 430 |
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 |
| 431 |
|
| 432 |
real user sys |
| 433 |
0m3.344s 0m3.026s 0m0.109s |
| 434 |
0m3.372s 0m3.037s 0m0.115s |
| 435 |
|
| 436 |
|
| 437 |
l ../tester-docs.xml ./tester-docs-all*.xml |
| 438 |
|
| 439 |
- we could also try to compact the installed xslt |
| 440 |
xmllint --nonet --c14n --xinclude gtk-doc.xsl | sed -ne '/<!--/ { :c; /-->/! { N; b c; }; /-->/s/<!--.*-->//g }; /^ *$/!p;' | sed '/^$/d' >gtk-doc.pre.xsl |
| 441 |
- unfortunately there is no way to ask xsltproc to pre-transform an xslt, that could |
| 442 |
- strip comments |
| 443 |
- process xsl:import and xsl:include |
| 444 |
- extra xsltproc options: |
| 445 |
--novalid: saves ~ 0.12 sec |
| 446 |
|
| 447 |
- strip DOCTYPES on xincludes |
| 448 |
- there is a performance bottleneck in libxml, where it parses DTD for each fragment |
| 449 |
- we're using the dtd to |
| 450 |
- validate fragments |
| 451 |
- inject package name/version etc. |
| 452 |
- 1) we could provide a flags to gtkdoc-mkdb to not put any doctype on |
| 453 |
generated file and manually result entities in generated files (and |
| 454 |
expand_content_files) |
| 455 |
- to get a list of entities: |
| 456 |
- we could parse entities from the main doc-file header |
| 457 |
- tricky as with xml/gtkdocentities.ent, they are in a extra file |
| 458 |
- we could pass entities as args for gtkdoc-mkdb |
| 459 |
- if the flag is used, we should warn if entities are in the header |
| 460 |
- 2) if the doctype on the main doc, does not cotnain entities, skip adding |
| 461 |
the doctype to generated output |
| 462 |
- 3) if the doctype on the main doc contains entities, only add the doctype |
| 463 |
if the generated content contains entities ([&%][_a-zA-Z]*;) |
| 464 |
- a quick check on the gnome modules showed: |
| 465 |
- quite a few don't use entities |
| 466 |
- those that use version.xml |
| 467 |
- seem to mostly use it in the main doc |
| 468 |
- but a few use it for man pages |
| 469 |
find . -name "*.xml" -exec grep -Hn "&version;" {} \; | grep -v "\-docs.xml" |
| 470 |
|
| 471 |
find . -name "*.xml" -exec egrep --color -Hn '&[_a-zA-Z]*;' {} \; | egrep -v '&(amp|lt|gt|quot|apos|nbsp);' | egrep --color '&[_a-zA-Z]*;' |
| 472 |
find . -name "*.xml" -exec egrep -o '&[_a-zA-Z]*;' {} \; | sort | uniq -c | sort -n |
| 473 |
|
| 474 |
= python = |
| 475 |
- consider swithcing to this markdown parser |
| 476 |
https://pythonhosted.org/Markdown/index.html |
| 477 |
- switch intermediate files to json/yaml |
| 478 |
- we need to pick something, that we can easily output from plain c (produced by gtkdoc-scangobj) |
| 479 |
- decl-list.txt and .types would need to stay |
| 480 |
- maybe maintain one file per sourcefile (in a subdir) to eventually be able to |
| 481 |
do incremental builds |
| 482 |
- refactor Read{Args,Declarations,Signals}File to output into a single dictionary each: |
| 483 |
Signal{Names,Objects,Returns,...}[key] -> Signals[key].{names,objects,returns,...} |