HACKING

   1 Testing
   2 =======
   3
   4 jhbuild --no-interact build 2>&1 | tee build.log
   5 grep "gtkdoc-* line" build.log
   6
   7 jhbuild buildone --no-net glib
   8
   9 Since 1.23 we do have a snapshot feature to check the stability of the generated
  10 xml/html. Simply run "make snapshot" under tests. Then make changes and run
  11 "make check". The tests/sanity.sh will check for delta. If you want to inspect
  12 what delta a change created, you can git checkout a revision before the change,
  13 "make snapshot", go back to head and "make check", the sanity.sh test will now
  14 fail and show the delta.
  15
  16 Releasing
  17 =========
  18
  19 http://live.gnome.org/MaintainersCorner/Releasing
  20
  21 - bump release date in:
  22   help/manual/C/index.docbook
  23 - bump version in (1.14.1 -> 1.15)
  24   configure.ac
  25
  26 - update NEWS
  27   ./bugzilla.py general 1.12 gtk-doc >RELNOTES.txt
  28   git log --summary --format=short GTK_DOC_1_11.. >ChangeLog-1.12
  29   grep "Author:" ChangeLog-1.12 | sed 's/Author:\(.*\)\ <.*>/\1/' | sort | uniq >>RELNOTES.txt
  30   and then copy to NEWS
  31
  32 - commit
  33   git add configure.ac NEWS help/manual/C/index.docbook
  34   git commit -m"release: update news and date in manual"
  35   git push
  36
  37 - dist
  38    TAR_OPTIONS="--owner=root --group=root" make distcheck
  39
  40 - tag
  41   git tag -a GTK_DOC_1_12 -m"release: 1.12"
  42   git push origin GTK_DOC_1_12
  43
  44 - release
  45   scp gtk-doc-1.12.tar.xz <user>@master.gnome.org:
  46   scp NEWS <user>@master.gnome.org:gtk-doc-1.12.news
  47   scp ChangeLog-1.12 <user>@master.gnome.org:gtk-doc-1.12.changes
  48   ssh <user>@master.gnome.org
  49   ftpadmin install gtk-doc-1.12.tar.xz
  50   exit
  51
  52 - bump versions in:
  53   configure.ac
  54   help/manual/C/index.docbook
  55   NEWS
  56
  57 - commit
  58   git add configure.ac NEWS help/manual/C/index.docbook
  59   git commit -m"release: bump versions and back to development"
  60   git push
  61
  62 - update web-pages (gtk-web/gtk-doc)
  63   git add gtk-doc/news.php
  64   git commit -m"gtk-doc: new release (1.15)"
  65   git push
  66
  67 - if we want a icon on the newsfeed, we should copy a icon like on
  68   http://ftp.acc.umu.se/pub/GNOME/sources/rhythmbox/rhythmbox.png
  69   e.g. /usr/share/icons/hicolor/48x48/apps/devhelp.png
  70
  71 Optimizing & Meassuring
  72 =======================
  73
  74 cd tests/gobject/docs/html
  75 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "tester" --stringparam gtkdoc.version "1.12" ../../../../gtk-doc.xsl ../tester-docs.xml
  76 ~ 1.1 sec.
  77 time saxon ../tester-docs.xml ../../../../gtk-doc.xsl gtkdoc.bookname="tester" gtkdoc.version="1.12"
  78 ~ 53 sec.
  79 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "tester" --stringparam gtkdoc.version "1.12" /usr/share/yelp-xsl/xslt/docbook/html/db2html.xsl ../tester-docs.xml
  80 ~ 0.7 sec
  81
  82 cd /your/project/docs/html
  83 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "foo" --stringparam gtkdoc.version "1.12" /usr/share/gtk-doc/data/gtk-doc.xsl ../buzztrax-core-docs.xml
  84 real  0m6.633s  user    0m6.464s  sys   0m0.128s
  85 real    0m6.459s  user  0m6.384s  sys   0m0.068s
  86
  87 time xsltproc --nonet --xinclude --stringparam gtkdoc.bookname "buzztrax-core" --stringparam gtkdoc.version "1.12"  /usr/share/yelp-xsl/xslt/docbook/html/db2html.xsl ../buzztrax-core-docs.xml
  88 real    0m3.312s  user  0m3.224s  sys   0m0.076s
  89 real    0m3.549s  user  0m3.464s  sys   0m0.076s
  90
  91
  92 xsltproc --profile data.xsl data.xml 2>report.txt
  93 cat report.txt | gprof2dot.py -e 0.01 -n 0.01 | dot -Tpng -o report.png
  94
  95 one can now use "GTKDOC_PROFILE=1 make" to run this during gtkdoc-mkhtml. It
  96 still needs a change in gprof2dot.py
  97 https://bugzilla.gnome.org/show_bug.cgi?id=612186#c3
  98
  99 Performance tips:
 100 * uses keys when we have slow xpath selects
 101   http://www.xml.com/pub/a/2002/02/06/key-lookups.html
 102
 103 Troubles with parsing regexps
 104 =============================
 105 Test regexps online:
 106 http://www.solmetra.com/scripts/regex/index.php
 107