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
- - document symbols where they are definied, so that when one changes the
+ - 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
about threadsafety and related issues
- link to signals from the description like this:
* The <link linkend="GstBin-element-added">element-added</link> signal
-- 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)
WEBSITE DOCUMENTATION
=====================
- 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 include href in the Elements chapter for the element
- in the main .sgml
+ - 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
(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 inspect-update
+ 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.
-
-- to add a plugin to be documented:
- - make sure inspect/ has generated a .xml file for it
- - add it to CVS
- - add an include in -docs.sgml in the Plugins list for that plugin
+ - 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>
+ - "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
==========================
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
projects / platform / upstream / gstreamer.git / blobdiff