README 15.6 KB
Newer Older
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
1
GStreamer documentation notes
Thomas Vander Stichele's avatar
readme  
Thomas Vander Stichele committed
2

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
IMPORTANT
=========

Please make sure you've read and understood everything in this file
before you try changing documentation.

OVERVIEW
========

GStreamer has two sets of documentation that we maintain:
* API references, using gtk-doc (gstreamer, gstreamer-libs)
* "books", using DocBook/XML (faq, manual, pwg)

DOCBOOK NOTES
=============

OK, I've grown so tired of having to coax the docs to build every time I
get round to it that I've decided to note down some of the things that
are important to know.

OVERVIEW
--------
* Our documentation should all be Docbook/XML.  No SGML.
* The source for the documentation is:
  - one or more .xml files, with the main one being gstreamer-(whatever).xml
  - image files
    - in .fig
    - in .png (and maybe others)
* We want to generate docs in HTML, PS and PDF
32
* We want to use xml to to generate these
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
33 34 35 36 37 38 39 40 41 42

CONVENTIONS
-----------
We stick to some simple conventions for writing docbook documentation.
* id names:
  - all id's start with chapter-, part-, section-, or misc-
  - verify this is the case by looking at the generated file names in html/
  - sections should also include the chapter name;
    for example in a chapter called chapter-example, a section would be
    called section-example-hello-world
43 44 45
* there are currently comments of the form <!-- synchronize with PWG -->
  in the docbook file. Please check the relevant section of the other manual
  when updating.
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91

HOW IMAGES ARE HANDLED
----------------------
* the format of images used is:
  - PNG for html
  - EPS for ps
  - PDF for pdf

* images may need to be converted from their source format to the end format

* a file called image.entities is generated that provides two entities:
  &image; and &IMAGE;
  &image; is the file extension (png, ps, pdf)
* all generated images will be put in images/

HOW THE BUILD WORKS FOR EACH FORMAT
-----------------------------------
* HTML:
  - xmlto html gstreamer-whatever.xml should produce the html docs.
  - We do this in the html subdir of the doc builddir.
  - images are copied to (builddir)/html/images
  - PNGS should be set to all of the png's referenced for html, both
    already there and auto-generated

* PS :
  - images are converted to .ps files in EPS format.  Generated images are
    put in images/
  - xmlto ps gstreamer-whatever.xml generates the ps file

* PDF :
  There are two ways:
  - ps2pdf is the easiest
  - we specify ps, PS as the image type, but using xmlto the build will fail
    because it uses ps2pdf internally and it fails to generate the images
    By hand-generating .pdf images before xmlto we can make the build succeed.
    (This is why image-pdf has file ext pdf but type EPS; this tricks xmlto in
     doing the right thing)
    xmlto pdf gstreamer-whatever.xml generates pdf (but seems to fail on the
    FAQ, so for now we use ps2pdf)

HOW THE BUILD SYSTEM IS SET UP
------------------------------
* make all should build html, ps, and pdf
* html is built in a subdir, with the png/ps images copied there
* ps and pdf are built in the current dir, in one file

92 93 94
SPELL CHECKING
--------------
* with aspell
95 96 97 98
  * aspell -b -c --mode=sgml --lang=en <file>.xml
    unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags


Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
99 100 101 102
GTK-DOC NOTES
=============

* files under CVS control:
Thomas Vander Stichele's avatar
readme  
Thomas Vander Stichele committed
103
  - Makefile.am
104 105 106 107 108 109 110
  - gstreamer-sections.txt
    describes which symbols later appear on one api-doc page
    configure which symbols are shown/invisible/private
  - gstreamer.types
    the types file lists all get_type() functions that register the GObject types
  - gstreamer-docs.sgml
    defines the overall structure of the api documentation
Thomas Vander Stichele's avatar
readme  
Thomas Vander Stichele committed
111
  - tmpl/
112 113 114
    - only add the file to CVS if you have at least filled the short description
      (filename corresponds to the <FILE> tag in the sections file)
    - document as much as possible in the source (*.c files)
Thomas Vander Stichele's avatar
readme  
Thomas Vander Stichele committed
115

116 117
* what to do when adding a new piece of API:
  - add both an entity and use the entity in gstreamer-docs.sgml
118 119
  - add a new <SECTION> to gstreamer-sections.txt in the correct alphabetical
    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 122
    (default),<SUBSECTION Standard>,<SUBSECTION Private>
  - document at least the Short_Description in tmpl/.sgml
Piotr Fusik's avatar
Piotr Fusik committed
123
  - document symbols where they are defined, so that when one changes the
124 125 126
    definition, the chaces are good that docs are updated.
    - document functions, signals in the .c files
    - document structs, typedefs, enums in the .h files
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
127

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
128
* checklist:
129 130 131 132 133 134
  - make sure *-sections.txt has a <TITLE> set for each <FILE>
  - add only *one* <TITLE> to each file, when you have multiple classes in one
    source-file, create one <FILE> section for each class
  - the <TITLE> *must* be named like the type of the GType, when it gets
    registered (otherwise gtkdoc introspection fails)
  - for clarity name the <FILE> like the <TITLE>, but all lowercase
135 136 137 138 139 140

* what to do when trying to improve the docs
  - compare the output of
    grep "_get_type" gstreamer-sections.txt | sort
    with the types in XXX.types to detect entries that
    are maybe missing
141
  - gtk docs does not warns about empty member docs!, run
142 143 144 145
    find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \;
    in the project root to find them
  - gtk docs does not warns about empty Returns: docs!, run
    find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@Returns: *$" {} \;
146
    in the project root to find them
Thomas Vander Stichele's avatar
readme  
Thomas Vander Stichele committed
147

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
148
* what happens during a gtk-doc build ?
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
  - Scan step:
    - based on a $(MODULE).types file:
      - gtkdoc-scangobj creates a gtkdoc-scan binary
        - using CC, LD, CFLAGS, LDFLAGS env var
        - using --type-init-func and --module parameters
        - gtkdoc-scan creates
          - $MODULE.signals.new
          - $MODULE.hierarchy.new
          - $MODULE.interfaces.new
          - $MODULE.prerequisites.new
          - $MODULE.args.new
        - generated source and objects get deleted
        - gtkdoc-scangobj merges changes into the original files
    - gtkdoc-scan
      - extracts decls of functions, macros, enums, structs, unions from headers
      - generates
        - $MODULE-decl.txt
        - $MODULE-decl-list.txt
      - $MODULE-decl-list.txt then should get copied to $MODULE-sections.txt
    - scan-build.stamp gets created
  
  - Template generation step:
    - gtkdoc-mktmpl --module=$MODULE
      - reads in tmpl/*.sgml
      - moves them to tmpl/*.sgml.bak
      - recreates tmpl/*.sgml according to $MODULE-sections.txt
      - moves unused stuff to $MODULE-unused.txt
    - tmpl-build.stamp gets generated
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
177

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
178 179 180
* Possible errors and how to fix them
  - Warning: multiple "IDs" for constraint linkend: gst-tag-register.
    - check if gst_tag_register is listed more than once in -sections.txt
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
181

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
182 183 184 185 186 187 188 189 190 191 192 193
STYLE GUIDE FOR GTK-DOC
=======================
- this is in addition to gtk-doc's style-guide.txt

- when documenting signals, use "the #Gst..." for the object receiving the
  signal; no trailing dot, and no "that received the signal"
- function/macro descriptions are descriptive, not imperative
  ie, it uses the third person verb
- synopsis and description should have most-used/application functions at the
  top
- functions that can return FALSE/NULL or fail should describe their failure
  conditions like this:
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
194 195
  * Returns NULL if no element with the given name is found in the bin, if
  * the frobble was stuck in the froob, or the frizzle was frazzed.
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
196 197 198
- a line with function attributes should be added before Returns:
  - can contain:
    "MT safe." - the function is verified to be multithreadingsafe
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
199 200 201 202
    "Caller owns returned reference" for refcounted classes
    "Caller owns returned value" for other types (iterators, ..)
  - we do this because, in contrast with GLib/GTK, we are more explicit
    about threadsafety and related issues
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
203 204
- link to signals from the description like this:
  * The <link linkend="GstBin-element-added">element-added</link> signal
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
205 206 207 208
- the bottom of the description should say when the doc was last reviewed
  (version and date)
   * Last reviewed on 2005-10-28 (0.9.4)

209 210
WEBSITE DOCUMENTATION
=====================
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
211 212 213 214 215 216 217 218 219 220 221 222 223 224

Updating the online documentation is pretty simple.
Make sure that you
a) have a working freedesktop.org account
b) $HOME/.ssh/config set up so that it has the right User for the Host
   (for example, I have:
Host freedesktop.org
  User thomasvs
c) verify this works by doing ssh freedesktop.org and being logged in without
   a password prompt
d) have verified your changes build documentation locally.

Then, after updating any of the docs, run "make upload" from that directory.
Or, run "make upload" from this (docs) directory.
Thomas Vander Stichele's avatar
readme  
Thomas Vander Stichele committed
225

226 227 228 229 230 231 232
DOCUMENTING ELEMENTS
====================
As of september 2005 we have some system to document plugins and elements
in the various plugin packages.

- in a submodule, docs go in docs/plugins
- template can be copied from gst-plugins-base
233 234 235 236 237 238 239 240 241 242 243 244
- to add plugins documentation:
  - create docs/plugins
  - create Makefile.am and friends, add to configure.ac
  - create docs/version.entities.in, add to configure.ac
  - in docs/plugins:
    - create $(module)-plugins.types with #include <gst/gst.h>
    - run make
    - edit the -docs.sgml
    - add to cvs:
      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
      cvs add inspect
      cvs add inspect/*.xml
245 246 247 248 249 250 251 252
    - Additional types can be added to the documentation by placing them in
      the .types file like this:
        type:GstPlayBaseBin
      This is useful for documenting plugin-private types that implement
      signals or properties. The GType is looked up by name after all the
      element classes have been printed - so this is only useful for types
      that are created as a consequence of loading plugins and registering
      the element(s).
253

254 255 256 257 258 259
- to add a plugin to be documented:
  - make sure inspect/ has generated a inspect/plugin-xxx.xml file for it.
    - if it has not, make sure you have pygst installed and run 'make update'.
      and add it to CVS.
  - add an xi:include in -docs.sgml in the Plugins chapter for that plugin

260
- to add an element to be documented:
261 262
  - add an xi:include in the Elements chapter for the element
    in the main -docs.sgml
263
  - add a section for it in -sections.txt with
264
      <SECTION>
265 266
      <FILE>element-(element)</FILE>
      <TITLE>(element)</TITLE>
267 268 269 270 271 272 273 274 275 276
      GstXxx
      <SUBSECTION Standard>
      GstXxxClass
      GST_XXX
      GST_XXX_CLASS
      GST_IS_XXX
      GST_IS_XXX_CLASS
      GST_TYPE_XXX
      gst_xxx_get_type
      </SECTION>
277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
  - add a gtk-doc section to the source code like:
/**
 * SECTION:element-multifdsink

  and fill it with documentation about the element, preferably inside
  a <refsect2> docbook container.
  - add an example:
    - either a few pipelines, inside <programlisting>
    - or a piece of code:
      - create an example program (element)-example.c in the plugin dir
      - add the full path (starting with $(top_srcdir)) for this example
        to the EXAMPLE_CFILES variable in Makefile.am
      - add an xinclude of a file named "element-(element)-example.xml"
        to the docbook documentation piece in the element source code
  - add the header to EXTRA_HFILES in Makefile.am to be able to document
292 293 294
    signals and args; in that case, the object struct needs to be in
    -sections.txt outside of the Standard Subsection (which is annoying,
    but ...)
295 296 297
    (FIXME: are we sure we can both do the xinclude from the tmpl/ sgml,
     as well as an override from the source itself ? maybe we should just
     make sure the xinclude is in the source itself instead ?)
298 299
  - if the plugin has no public header, don't add the c-file, add entries to the
    -overrides.txt file (see playbin docs in plugins-base).
300 301
  - to rebuild the docs, do:
    make clean
302
    make update
303
    make
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
304 305 306
  - examples will only show up using gtk-doc 1.4 or later - it relies on
    merging stuff from .sgml with inline docs.  We might want to change
    this to only get stuff from the source.
Thijs Vermeir's avatar
Thijs Vermeir committed
307
  - you need to commit resulting files to git:
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
308 309
    - changes to *.signals and *.args
    - new files for your plugin created in inspect/
Thijs Vermeir's avatar
Thijs Vermeir committed
310
  - if you get this warning:
311 312 313 314 315
    " Documentation in template xxx for ./tmpl/element-yyy:Short_Description
      being overridden by inline comments"
    per-default the description from the GST_ELEMENT_DETAILS is put to the
    Short_Description. This warning mean you have a different one in the section
    docs as "@short_description:".
316

317 318 319 320
- the plugin-doc-list on the gstreamer homepage is updated along with other
  web site updates.

- maintainer tricks:
321 322 323 324 325 326 327 328
  - in gst-plugins-foo/docs/plugins/, run
        make check-inspected-versions
    to show plugins whose inspect information is not up-to-date (which is
    usually either because they have been moved to a different module or
    because they are not built on the maintainer's machine for some reason).
    Whether it really makes sense to update the version number is debatable
    (after all, the inspected information may be outdated and things may have
    changed, in which case it would be bad to change the version number)
329 330 331 332 333 334 335 336 337 338
  - find files that have docs
    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
    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
    - add those .h files to EXTRA_HFILES in Makefile.am
  - update gst-plugins-xxx-docs.sgml
    cd docs/plugins
    ls -1 xml/plugin-*.xml | sort | sed -e "s/\(.*\)/    \<xi:include href=\"\1\" \/\>/"
    ls -1 xml/element-*.xml | grep -v -- "-details.xml" | sort | sed -e "s/\(.*\)/    \<xi:include href=\"\1\" \/\>/"
    - maybe we can generate these lists after "make update" and just xi:include
      them in gst-plugins-xxx-docs.sgml. They should be committed to the vcs.
339

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
340
- possible errors:
341 342 343 344
  - "multiple constraints for linkend ID":
    check if each section in -sections.txt actually starts and ends with
    <SECTION> and </SECTION>
  - if a plugin does not show up:
345
    - check inspect/plugin-xxx.xml and tmpl/elements-
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
346

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
347 348
RANDOM THINGS I'VE LEARNED
==========================
Thomas Vander Stichele's avatar
readme  
Thomas Vander Stichele committed
349

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
350 351 352 353 354 355
* for clean builddir != srcdir separation, I wanted to use xmlto --searchpath
  so the source xml could find the built entity file.
  But xmlto --searchpath is (right now) for TeX input, not xml input.
  xsltproc has a --path option (that xmlto doesn't use yet), but it
  resolves single files to $(specified_path)/$(srcdir)/$(file)
  For now, we need to hack around it by copying xml to the build dir.
356

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
357

358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398
(old) DOCUMENTATION BUILDING NOTES
----------------------------------

To build the GStreamer documentation you need the following installed (based on
Red Hat packages).  These packages comes from rawhide and are the ones that
will be in Red Hat 7.3/8.0

Docbook stuff:
sgml-common 
xml-common 
openjade (needs to be rebuilt from SRPM for Red Hat 7.2)
tetex-dvips
jadetex
docbook-dtds      
docbook-style-dsssl 
docbook-style-xsl
docbook-utils

XML stuff:
libxml2
libxml2-python
libxml2-devel
libxslt
libxslt-devel
libxslt-python



Gtkdoc:
gtk-doc

Other stuff:
transfig
pdftops

DEVHELP INTEGRATION
-------------------
Check http://www.imendio.com/projects/devhelp/
It's a really nice development app allowing you to look up API stuff
from various gtk-doc'd libraries.  GStreamer is one of these ;)

399
gtk-doc generates both html API docs and the matching .devhelp(2) books.
400 401 402 403 404 405

IMAGES
------
It's important to keep the original source format for images, to be able
to change and regenerate later on.  Original files go in
docs/images