Please make sure you've read and understood everything in this file
before you try changing documentation.
+Some of the docbook-related bits in this README might be out of date now that
+quite a bit of the documentation has moved into the gst-docs repository.
+
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)
+* FAQ / Application Development Manual / Plugin Writer's Guide / Tutorials -
+ these are maintained in markdown format and live in the gst-docs repository.
DOCBOOK NOTES
=============
* The source for the documentation is:
- one or more .xml files, with the main one being gstreamer-(whatever).xml
- image files
- - in .fig
+ - in .svg
- in .png (and maybe others)
* We want to generate docs in HTML, PS and PDF
* We want to use xml to to generate these
* 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
-
-DOCBOOK NOTES
-=============
-
-* spell checking with aspell
+SPELL CHECKING
+--------------
+* with aspell
* aspell -b -c --mode=sgml --lang=en <file>.xml
unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags
GTK-DOC NOTES
=============
-* files under CVS control:
+* files under revision control:
- Makefile.am
- gstreamer-sections.txt
describes which symbols later appear on one api-doc page
- add all documented symbols to gstreamer-sections.txt in the proper section
(default),<SUBSECTION Standard>,<SUBSECTION Private>
- document at least the Short_Description in tmpl/.sgml
- - signals: document them properly in tmpl/.sgml (or better in the c-source)
+ - document symbols where they are defined, so that when one changes the
+ definition, the chaces are good that docs are updated.
+ - document functions, signals in the .c files
+ - document structs, typedefs, enums in the .h files
* checklist:
- make sure *-sections.txt has a <TITLE> set for each <FILE>
grep "_get_type" gstreamer-sections.txt | sort
with the types in XXX.types to detect entries that
are maybe missing
+ - gtk docs does not warns about empty member docs!, run
+ 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: *$" {} \;
+ in the project root to find them
* what happens during a gtk-doc build ?
- - headers are scanned based on $(MODULE).types
- $(MODULE)-scan is created
- gtkdoc-scan is called with a sourcedir and a module name,
- where the module name is $(MODULE)
- $(MODULE)-sections.txt is created if it doesn't exist yet (it should),
- as well as $(MODULE)-decl.txt and $(MODULE)-decl-list.txt
- and .args, .hierarchy and .signals files are created
- gtkdoc-scan is called
- - if it not works, try e.g. 'rm docs/gst/*.stamp'
+ - 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
* 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
+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:
+ * 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.
+- a line with function attributes should be added before Returns:
+ - can contain:
+ "MT safe." - the function is verified to be multithreadingsafe
+ "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
+- link to signals from the description like this:
+ * The <link linkend="GstBin-element-added">element-added</link> signal
+
WEBSITE DOCUMENTATION
=====================
Then, after updating any of the docs, run "make upload" from that directory.
Or, run "make upload" from this (docs) directory.
+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
+- 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
+ - 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).
+
+- 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
+
+- to add an element to be documented:
+ - add an xi:include in the Elements chapter for the element
+ in the main -docs.sgml
+ - add a section for it in -sections.txt with
+ <SECTION>
+ <FILE>element-(element)</FILE>
+ <TITLE>(element)</TITLE>
+ GstXxx
+ <SUBSECTION Standard>
+ GstXxxClass
+ GST_XXX
+ GST_XXX_CLASS
+ GST_IS_XXX
+ GST_IS_XXX_CLASS
+ GST_TYPE_XXX
+ gst_xxx_get_type
+ </SECTION>
+ - 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
+ signals and args; in that case, the object struct needs to be in
+ -sections.txt outside of the Standard Subsection (which is annoying,
+ but ...)
+ (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 ?)
+ - 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).
+ - to rebuild the docs, do:
+ make clean
+ make update
+ make
+ - 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.
+ - you need to commit resulting files to git:
+ - changes to *.signals and *.args
+ - new files for your plugin created in inspect/
+ - if you get this warning:
+ " 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:".
+
+- the plugin-doc-list on the gstreamer homepage is updated along with other
+ web site updates.
+
+- maintainer tricks:
+ - 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)
+ - 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.
+
+- possible errors:
+ - "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:
+ - check inspect/plugin-xxx.xml and tmpl/elements-
+
RANDOM THINGS I'VE LEARNED
==========================
resolves single files to $(specified_path)/$(srcdir)/$(file)
For now, we need to hack around it by copying xml to the build dir.
+
+DEVHELP INTEGRATION
+-------------------
+Check https://wiki.gnome.org/Apps/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 ;)
+
+gtk-doc generates both html API docs and the matching .devhelp(2) books.
+
+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