docs/README

   1 GStreamer documentation notes
   2
   3 IMPORTANT
   4 =========
   5
   6 Please make sure you've read and understood everything in this file
   7 before you try changing documentation.
   8
   9 OVERVIEW
  10 ========
  11
  12 GStreamer has two sets of documentation that we maintain:
  13 * API references, using gtk-doc (gstreamer, gstreamer-libs)
  14 * "books", using DocBook/XML (faq, manual, pwg)
  15
  16 DOCBOOK NOTES
  17 =============
  18
  19 OK, I've grown so tired of having to coax the docs to build every time I
  20 get round to it that I've decided to note down some of the things that
  21 are important to know.
  22
  23 OVERVIEW
  24 --------
  25 * Our documentation should all be Docbook/XML.  No SGML.
  26 * The source for the documentation is:
  27   - one or more .xml files, with the main one being gstreamer-(whatever).xml
  28   - image files
  29     - in .fig
  30     - in .png (and maybe others)
  31 * We want to generate docs in HTML, PS and PDF
  32 * We want to use xml to to generate these
  33
  34 CONVENTIONS
  35 -----------
  36 We stick to some simple conventions for writing docbook documentation.
  37 * id names:
  38   - all id's start with chapter-, part-, section-, or misc-
  39   - verify this is the case by looking at the generated file names in html/
  40   - sections should also include the chapter name;
  41     for example in a chapter called chapter-example, a section would be
  42     called section-example-hello-world
  43 * there are currently comments of the form <!-- synchronize with PWG -->
  44   in the docbook file. Please check the relevant section of the other manual
  45   when updating.
  46
  47 HOW IMAGES ARE HANDLED
  48 ----------------------
  49 * the format of images used is:
  50   - PNG for html
  51   - EPS for ps
  52   - PDF for pdf
  53
  54 * images may need to be converted from their source format to the end format
  55
  56 * a file called image.entities is generated that provides two entities:
  57   &image; and &IMAGE;
  58   &image; is the file extension (png, ps, pdf)
  59 * all generated images will be put in images/
  60
  61 HOW THE BUILD WORKS FOR EACH FORMAT
  62 -----------------------------------
  63 * HTML:
  64   - xmlto html gstreamer-whatever.xml should produce the html docs.
  65   - We do this in the html subdir of the doc builddir.
  66   - images are copied to (builddir)/html/images
  67   - PNGS should be set to all of the png's referenced for html, both
  68     already there and auto-generated
  69
  70 * PS :
  71   - images are converted to .ps files in EPS format.  Generated images are
  72     put in images/
  73   - xmlto ps gstreamer-whatever.xml generates the ps file
  74
  75 * PDF :
  76   There are two ways:
  77   - ps2pdf is the easiest
  78   - we specify ps, PS as the image type, but using xmlto the build will fail
  79     because it uses ps2pdf internally and it fails to generate the images
  80     By hand-generating .pdf images before xmlto we can make the build succeed.
  81     (This is why image-pdf has file ext pdf but type EPS; this tricks xmlto in
  82      doing the right thing)
  83     xmlto pdf gstreamer-whatever.xml generates pdf (but seems to fail on the
  84     FAQ, so for now we use ps2pdf)
  85
  86 HOW THE BUILD SYSTEM IS SET UP
  87 ------------------------------
  88 * make all should build html, ps, and pdf
  89 * html is built in a subdir, with the png/ps images copied there
  90 * ps and pdf are built in the current dir, in one file
  91
  92 SPELL CHECKING
  93 --------------
  94 * with aspell
  95   * aspell -b -c --mode=sgml --lang=en <file>.xml
  96     unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags
  97
  98
  99 GTK-DOC NOTES
 100 =============
 101
 102 * files under CVS control:
 103   - Makefile.am
 104   - gstreamer-sections.txt
 105     describes which symbols later appear on one api-doc page
 106     configure which symbols are shown/invisible/private
 107   - gstreamer.types
 108     the types file lists all get_type() functions that register the GObject types
 109   - gstreamer-docs.sgml
 110     defines the overall structure of the api documentation
 111   - tmpl/
 112     - only add the file to CVS if you have at least filled the short description
 113       (filename corresponds to the <FILE> tag in the sections file)
 114     - document as much as possible in the source (*.c files)
 115
 116 * what to do when adding a new piece of API:
 117   - add both an entity and use the entity in gstreamer-docs.sgml
 118   - add a new <SECTION> to gstreamer-sections.txt in the correct alphabetical
 119     position related to the other sections (so that it is easier to locate)
 120   - add all documented symbols to gstreamer-sections.txt in the proper section
 121     (default),<SUBSECTION Standard>,<SUBSECTION Private>
 122   - document at least the Short_Description in tmpl/.sgml
 123   - document symbols where they are defined, so that when one changes the
 124     definition, the chaces are good that docs are updated.
 125     - document functions, signals in the .c files
 126     - document structs, typedefs, enums in the .h files
 127
 128 * checklist:
 129   - make sure *-sections.txt has a <TITLE> set for each <FILE>
 130   - add only *one* <TITLE> to each file, when you have multiple classes in one
 131     source-file, create one <FILE> section for each class
 132   - the <TITLE> *must* be named like the type of the GType, when it gets
 133     registered (otherwise gtkdoc introspection fails)
 134   - for clarity name the <FILE> like the <TITLE>, but all lowercase
 135
 136 * what to do when trying to improve the docs
 137   - compare the output of
 138     grep "_get_type" gstreamer-sections.txt | sort
 139     with the types in XXX.types to detect entries that
 140     are maybe missing
 141   - gtk docs does not warns about empty member docs!, run
 142     find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \;
 143     in the project root to find them
 144   - gtk docs does not warns about empty Returns: docs!, run
 145     find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@Returns: *$" {} \;
 146     in the project root to find them
 147
 148 * what happens during a gtk-doc build ?
 149   - Scan step:
 150     - based on a $(MODULE).types file:
 151       - gtkdoc-scangobj creates a gtkdoc-scan binary
 152         - using CC, LD, CFLAGS, LDFLAGS env var
 153         - using --type-init-func and --module parameters
 154         - gtkdoc-scan creates
 155           - $MODULE.signals.new
 156           - $MODULE.hierarchy.new
 157           - $MODULE.interfaces.new
 158           - $MODULE.prerequisites.new
 159           - $MODULE.args.new
 160         - generated source and objects get deleted
 161         - gtkdoc-scangobj merges changes into the original files
 162     - gtkdoc-scan
 163       - extracts decls of functions, macros, enums, structs, unions from headers
 164       - generates
 165         - $MODULE-decl.txt
 166         - $MODULE-decl-list.txt
 167       - $MODULE-decl-list.txt then should get copied to $MODULE-sections.txt
 168     - scan-build.stamp gets created
 169
 170   - Template generation step:
 171     - gtkdoc-mktmpl --module=$MODULE
 172       - reads in tmpl/*.sgml
 173       - moves them to tmpl/*.sgml.bak
 174       - recreates tmpl/*.sgml according to $MODULE-sections.txt
 175       - moves unused stuff to $MODULE-unused.txt
 176     - tmpl-build.stamp gets generated
 177
 178 * Possible errors and how to fix them
 179   - Warning: multiple "IDs" for constraint linkend: gst-tag-register.
 180     - check if gst_tag_register is listed more than once in -sections.txt
 181
 182 STYLE GUIDE FOR GTK-DOC
 183 =======================
 184 - this is in addition to gtk-doc's style-guide.txt
 185
 186 - when documenting signals, use "the #Gst..." for the object receiving the
 187   signal; no trailing dot, and no "that received the signal"
 188 - function/macro descriptions are descriptive, not imperative
 189   ie, it uses the third person verb
 190 - synopsis and description should have most-used/application functions at the
 191   top
 192 - functions that can return FALSE/NULL or fail should describe their failure
 193   conditions like this:
 194   * Returns NULL if no element with the given name is found in the bin, if
 195   * the frobble was stuck in the froob, or the frizzle was frazzed.
 196 - a line with function attributes should be added before Returns:
 197   - can contain:
 198     "MT safe." - the function is verified to be multithreadingsafe
 199     "Caller owns returned reference" for refcounted classes
 200     "Caller owns returned value" for other types (iterators, ..)
 201   - we do this because, in contrast with GLib/GTK, we are more explicit
 202     about threadsafety and related issues
 203 - link to signals from the description like this:
 204   * The <link linkend="GstBin-element-added">element-added</link> signal
 205 - the bottom of the description should say when the doc was last reviewed
 206   (version and date)
 207    * Last reviewed on 2005-10-28 (0.9.4)
 208
 209 WEBSITE DOCUMENTATION
 210 =====================
 211
 212 Updating the online documentation is pretty simple.
 213 Make sure that you
 214 a) have a working freedesktop.org account
 215 b) $HOME/.ssh/config set up so that it has the right User for the Host
 216    (for example, I have:
 217 Host freedesktop.org
 218   User thomasvs
 219 c) verify this works by doing ssh freedesktop.org and being logged in without
 220    a password prompt
 221 d) have verified your changes build documentation locally.
 222
 223 Then, after updating any of the docs, run "make upload" from that directory.
 224 Or, run "make upload" from this (docs) directory.
 225
 226 DOCUMENTING ELEMENTS
 227 ====================
 228 As of september 2005 we have some system to document plugins and elements
 229 in the various plugin packages.
 230
 231 - in a submodule, docs go in docs/plugins
 232 - template can be copied from gst-plugins-base
 233 - to add plugins documentation:
 234   - create docs/plugins
 235   - create Makefile.am and friends, add to configure.ac
 236   - create docs/version.entities.in, add to configure.ac
 237   - in docs/plugins:
 238     - create $(module)-plugins.types with #include <gst/gst.h>
 239     - run make
 240     - edit the -docs.sgml
 241     - add to cvs:
 242       cvs add *-plugins-docs.sgml *-plugins.args *-plugins.hierarchy *-plugins.interfaces *-plugins.prerequisites *-plugins.signals *-plugins.types inspect-build.stamp inspect.stamp scanobj-build.stamp
 243       cvs add inspect
 244       cvs add inspect/*.xml
 245     - Additional types can be added to the documentation by placing them in
 246       the .types file like this:
 247         type:GstPlayBaseBin
 248       This is useful for documenting plugin-private types that implement
 249       signals or properties. The GType is looked up by name after all the
 250       element classes have been printed - so this is only useful for types
 251       that are created as a consequence of loading plugins and registering
 252       the element(s).
 253
 254 - to add a plugin to be documented:
 255   - make sure inspect/ has generated a inspect/plugin-xxx.xml file for it.
 256     - if it has not, make sure you have pygst installed and run 'make update'.
 257       and add it to CVS.
 258   - add an xi:include in -docs.sgml in the Plugins chapter for that plugin
 259
 260 - to add an element to be documented:
 261   - add an xi:include in the Elements chapter for the element
 262     in the main -docs.sgml
 263   - add a section for it in -sections.txt with
 264       <SECTION>
 265       <FILE>element-(element)</FILE>
 266       <TITLE>(element)</TITLE>
 267       GstXxx
 268       <SUBSECTION Standard>
 269       GstXxxClass
 270       GST_XXX
 271       GST_XXX_CLASS
 272       GST_IS_XXX
 273       GST_IS_XXX_CLASS
 274       GST_TYPE_XXX
 275       gst_xxx_get_type
 276       </SECTION>
 277   - add a gtk-doc section to the source code like:
 278 /**
 279  * SECTION:element-multifdsink
 280
 281   and fill it with documentation about the element, preferably inside
 282   a <refsect2> docbook container.
 283   - add an example:
 284     - either a few pipelines, inside <programlisting>
 285     - or a piece of code:
 286       - create an example program (element)-example.c in the plugin dir
 287       - add the full path (starting with $(top_srcdir)) for this example
 288         to the EXAMPLE_CFILES variable in Makefile.am
 289       - add an xinclude of a file named "element-(element)-example.xml"
 290         to the docbook documentation piece in the element source code
 291   - add the header to EXTRA_HFILES in Makefile.am to be able to document
 292     signals and args; in that case, the object struct needs to be in
 293     -sections.txt outside of the Standard Subsection (which is annoying,
 294     but ...)
 295     (FIXME: are we sure we can both do the xinclude from the tmpl/ sgml,
 296      as well as an override from the source itself ? maybe we should just
 297      make sure the xinclude is in the source itself instead ?)
 298   - if the plugin has no public header, don't add the c-file, add entries to the
 299     -overrides.txt file (see playbin docs in plugins-base).
 300   - to rebuild the docs, do:
 301     make clean
 302     make update
 303     make
 304   - examples will only show up using gtk-doc 1.4 or later - it relies on
 305     merging stuff from .sgml with inline docs.  We might want to change
 306     this to only get stuff from the source.
 307   - you need to commit resulting files to git:
 308     - changes to *.signals and *.args
 309     - new files for your plugin created in inspect/
 310   - if you get this warning:
 311     " Documentation in template xxx for ./tmpl/element-yyy:Short_Description
 312       being overridden by inline comments"
 313     per-default the description from the GST_ELEMENT_DETAILS is put to the
 314     Short_Description. This warning mean you have a different one in the section
 315     docs as "@short_description:".
 316
 317 - the plugin-doc-list on the gstreamer homepage is updated along with other
 318   web site updates.
 319
 320 - maintainer tricks:
 321   - in gst-plugins-foo/docs/plugins/, run
 322         make check-inspected-versions
 323     to show plugins whose inspect information is not up-to-date (which is
 324     usually either because they have been moved to a different module or
 325     because they are not built on the maintainer's machine for some reason).
 326     Whether it really makes sense to update the version number is debatable
 327     (after all, the inspected information may be outdated and things may have
 328     changed, in which case it would be bad to change the version number)
 329   - find files that have docs
 330     for file in `find . -name "*.c" -exec grep -l " * SECTION:element-" {} \; | sort`; do if [ -e ${file/.c/.h} ]; then echo ${file/.c/.h}; else echo "no header for $file"; fi; done
 331     for file in `find . -name "*.cc" -exec grep -l " * SECTION:element-" {} \; | sort`; do if [ -e ${file/.cc/.h} ]; then echo ${file/.cc/.h}; else echo "no header for $file"; fi; done
 332     - add those .h files to EXTRA_HFILES in Makefile.am
 333   - update gst-plugins-xxx-docs.sgml
 334     cd docs/plugins
 335     ls -1 xml/plugin-*.xml | sort | sed -e "s/\(.*\)/    \<xi:include href=\"\1\" \/\>/"
 336     ls -1 xml/element-*.xml | grep -v -- "-details.xml" | sort | sed -e "s/\(.*\)/    \<xi:include href=\"\1\" \/\>/"
 337     - maybe we can generate these lists after "make update" and just xi:include
 338       them in gst-plugins-xxx-docs.sgml. They should be committed to the vcs.
 339
 340 - possible errors:
 341   - "multiple constraints for linkend ID":
 342     check if each section in -sections.txt actually starts and ends with
 343     <SECTION> and </SECTION>
 344   - if a plugin does not show up:
 345     - check inspect/plugin-xxx.xml and tmpl/elements-
 346
 347 RANDOM THINGS I'VE LEARNED
 348 ==========================
 349
 350 * for clean builddir != srcdir separation, I wanted to use xmlto --searchpath
 351   so the source xml could find the built entity file.
 352   But xmlto --searchpath is (right now) for TeX input, not xml input.
 353   xsltproc has a --path option (that xmlto doesn't use yet), but it
 354   resolves single files to $(specified_path)/$(srcdir)/$(file)
 355   For now, we need to hack around it by copying xml to the build dir.
 356
 357
 358 (old) DOCUMENTATION BUILDING NOTES
 359 ----------------------------------
 360
 361 To build the GStreamer documentation you need the following installed (based on
 362 Red Hat packages).  These packages comes from rawhide and are the ones that
 363 will be in Red Hat 7.3/8.0
 364
 365 Docbook stuff:
 366 sgml-common
 367 xml-common
 368 openjade (needs to be rebuilt from SRPM for Red Hat 7.2)
 369 tetex-dvips
 370 jadetex
 371 docbook-dtds
 372 docbook-style-dsssl
 373 docbook-style-xsl
 374 docbook-utils
 375
 376 XML stuff:
 377 libxml2
 378 libxml2-python
 379 libxml2-devel
 380 libxslt
 381 libxslt-devel
 382 libxslt-python
 383
 384
 385
 386 Gtkdoc:
 387 gtk-doc
 388
 389 Other stuff:
 390 transfig
 391 pdftops
 392
 393 DEVHELP INTEGRATION
 394 -------------------
 395 Check http://www.imendio.com/projects/devhelp/
 396 It's a really nice development app allowing you to look up API stuff
 397 from various gtk-doc'd libraries.  GStreamer is one of these ;)
 398
 399 gtk-doc generates both html API docs and the matching .devhelp(2) books.
 400
 401 IMAGES
 402 ------
 403 It's important to keep the original source format for images, to be able
 404 to change and regenerate later on.  Original files go in
 405 docs/images