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
  44 HOW IMAGES ARE HANDLED
  45 ----------------------
  46 * the format of images used is:
  47   - PNG for html
  48   - EPS for ps
  49   - PDF for pdf
  50
  51 * images may need to be converted from their source format to the end format
  52
  53 * a file called image.entities is generated that provides two entities:
  54   &image; and &IMAGE;
  55   &image; is the file extension (png, ps, pdf)
  56 * all generated images will be put in images/
  57
  58 HOW THE BUILD WORKS FOR EACH FORMAT
  59 -----------------------------------
  60 * HTML:
  61   - xmlto html gstreamer-whatever.xml should produce the html docs.
  62   - We do this in the html subdir of the doc builddir.
  63   - images are copied to (builddir)/html/images
  64   - PNGS should be set to all of the png's referenced for html, both
  65     already there and auto-generated
  66
  67 * PS :
  68   - images are converted to .ps files in EPS format.  Generated images are
  69     put in images/
  70   - xmlto ps gstreamer-whatever.xml generates the ps file
  71
  72 * PDF :
  73   There are two ways:
  74   - ps2pdf is the easiest
  75   - we specify ps, PS as the image type, but using xmlto the build will fail
  76     because it uses ps2pdf internally and it fails to generate the images
  77     By hand-generating .pdf images before xmlto we can make the build succeed.
  78     (This is why image-pdf has file ext pdf but type EPS; this tricks xmlto in
  79      doing the right thing)
  80     xmlto pdf gstreamer-whatever.xml generates pdf (but seems to fail on the
  81     FAQ, so for now we use ps2pdf)
  82
  83 HOW THE BUILD SYSTEM IS SET UP
  84 ------------------------------
  85 * make all should build html, ps, and pdf
  86 * html is built in a subdir, with the png/ps images copied there
  87 * ps and pdf are built in the current dir, in one file
  88
  89
  90 DOCBOOK NOTES
  91 =============
  92
  93 * spell checking with aspell
  94   * aspell -b -c --mode=sgml --lang=en <file>.xml
  95     unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags
  96
  97
  98 GTK-DOC NOTES
  99 =============
 100
 101 * files under CVS control:
 102   - Makefile.am
 103   - gstreamer-sections.txt
 104     describes which symbols later appear on one api-doc page
 105     configure which symbols are shown/invisible/private
 106   - gstreamer.types
 107     the types file lists all get_type() functions that register the GObject types
 108   - gstreamer-docs.sgml
 109     defines the overall structure of the api documentation
 110   - tmpl/
 111     - only add the file to CVS if you have at least filled the short description
 112       (filename corresponds to the <FILE> tag in the sections file)
 113     - document as much as possible in the source (*.c files)
 114
 115 * what to do when adding a new piece of API:
 116   - add both an entity and use the entity in gstreamer-docs.sgml
 117   - add a new <SECTION> to gstreamer-sections.txt in the correct alphabetical
 118     position related to the other sections (so that it is easier to locate)
 119   - add all documented symbols to gstreamer-sections.txt in the proper section
 120     (default),<SUBSECTION Standard>,<SUBSECTION Private>
 121   - document at least the Short_Description in tmpl/.sgml
 122   - document symbols where they are definied, so that when one changes the
 123     definition, the chaces are good that docs are updated.
 124     - document functions, signals in the .c files
 125     - document structs, typedefs, enums in the .h files
 126
 127 * checklist:
 128   - make sure *-sections.txt has a <TITLE> set for each <FILE>
 129   - add only *one* <TITLE> to each file, when you have multiple classes in one
 130     source-file, create one <FILE> section for each class
 131   - the <TITLE> *must* be named like the type of the GType, when it gets
 132     registered (otherwise gtkdoc introspection fails)
 133   - for clarity name the <FILE> like the <TITLE>, but all lowercase
 134
 135 * what to do when trying to improve the docs
 136   - compare the output of
 137     grep "_get_type" gstreamer-sections.txt | sort
 138     with the types in XXX.types to detect entries that
 139     are maybe missing
 140   - gtk docs does not warns about empty member docs!, run
 141     find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \;
 142     in the project root to find them
 143   - gtk docs does not warns about empty Returns: docs!, run
 144     find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@Returns: *$" {} \;
 145     in the project root to find them
 146
 147 * what happens during a gtk-doc build ?
 148   - Scan step:
 149     - based on a $(MODULE).types file:
 150       - gtkdoc-scangobj creates a gtkdoc-scan binary
 151         - using CC, LD, CFLAGS, LDFLAGS env var
 152         - using --type-init-func and --module parameters
 153         - gtkdoc-scan creates
 154           - $MODULE.signals.new
 155           - $MODULE.hierarchy.new
 156           - $MODULE.interfaces.new
 157           - $MODULE.prerequisites.new
 158           - $MODULE.args.new
 159         - generated source and objects get deleted
 160         - gtkdoc-scangobj merges changes into the original files
 161     - gtkdoc-scan
 162       - extracts decls of functions, macros, enums, structs, unions from headers
 163       - generates
 164         - $MODULE-decl.txt
 165         - $MODULE-decl-list.txt
 166       - $MODULE-decl-list.txt then should get copied to $MODULE-sections.txt
 167     - scan-build.stamp gets created
 168
 169   - Template generation step:
 170     - gtkdoc-mktmpl --module=$MODULE
 171       - reads in tmpl/*.sgml
 172       - moves them to tmpl/*.sgml.bak
 173       - recreates tmpl/*.sgml according to $MODULE-sections.txt
 174       - moves unused stuff to $MODULE-unused.txt
 175     - tmpl-build.stamp gets generated
 176
 177 * Possible errors and how to fix them
 178   - Warning: multiple "IDs" for constraint linkend: gst-tag-register.
 179     - check if gst_tag_register is listed more than once in -sections.txt
 180
 181 WEBSITE DOCUMENTATION
 182 =====================
 183
 184 Updating the online documentation is pretty simple.
 185 Make sure that you
 186 a) have a working freedesktop.org account
 187 b) $HOME/.ssh/config set up so that it has the right User for the Host
 188    (for example, I have:
 189 Host freedesktop.org
 190   User thomasvs
 191 c) verify this works by doing ssh freedesktop.org and being logged in without
 192    a password prompt
 193 d) have verified your changes build documentation locally.
 194
 195 Then, after updating any of the docs, run "make upload" from that directory.
 196 Or, run "make upload" from this (docs) directory.
 197
 198 RANDOM THINGS I'VE LEARNED
 199 ==========================
 200
 201 * for clean builddir != srcdir separation, I wanted to use xmlto --searchpath
 202   so the source xml could find the built entity file.
 203   But xmlto --searchpath is (right now) for TeX input, not xml input.
 204   xsltproc has a --path option (that xmlto doesn't use yet), but it
 205   resolves single files to $(specified_path)/$(srcdir)/$(file)
 206   For now, we need to hack around it by copying xml to the build dir.
 207
 208