latency: Dot not override already stored events

[platform/upstream/gstreamer.git] / docs / README

diff --git a/docs/README b/docs/README
index 1f9670c..a7b46fe 100644 (file)
--- a/docs/README
+++ b/docs/README
@@ -6,12 +6,16 @@ IMPORTANT
 Please make sure you've read and understood everything in this file
 before you try changing documentation.
 
 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)
 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
 =============
 
 DOCBOOK NOTES
 =============


@@ -26,7 +30,7 @@ OVERVIEW
 * The source for the documentation is:
   - one or more .xml files, with the main one being gstreamer-(whatever).xml
   - image files
 * 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
     - in .png (and maybe others)
 * We want to generate docs in HTML, PS and PDF
 * We want to use xml to to generate these


@@ -86,11 +90,9 @@ HOW THE BUILD SYSTEM IS SET UP
 * 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
 
 * 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
 
   * aspell -b -c --mode=sgml --lang=en <file>.xml
     unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags
 


@@ -98,7 +100,7 @@ DOCBOOK NOTES
 GTK-DOC NOTES
 =============
 
 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
   - Makefile.am
   - gstreamer-sections.txt
     describes which symbols later appear on one api-doc page


@@ -119,7 +121,7 @@ GTK-DOC NOTES
   - 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
   - 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
     definition, the chaces are good that docs are updated.
     - document functions, signals in the .c files
     - document structs, typedefs, enums in the .h files


@@ -178,6 +180,30 @@ GTK-DOC NOTES
   - Warning: multiple "IDs" for constraint linkend: gst-tag-register.
     - check if gst_tag_register is listed more than once in -sections.txt
 
   - 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
 =====================
 
 WEBSITE DOCUMENTATION
 =====================
 


@@ -202,11 +228,50 @@ in the various plugin packages.
 
 - in a submodule, docs go in docs/plugins
 - template can be copied from gst-plugins-base
 
 - 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:
 - to add an element to be documented:

-  - add an include href in the Elements chapter for the element
+  - 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
   - add a section for it in -sections.txt with

+      <SECTION>

       <FILE>element-(element)</FILE>
       <TITLE>(element)</TITLE>
       <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
   - add a gtk-doc section to the source code like:
 /**
  * SECTION:element-multifdsink


@@ -222,19 +287,60 @@ in the various plugin packages.
       - 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
       - 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
+    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 ?)
     (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
   - to rebuild the docs, do:
     make clean

-    make inspect-update
+    make update

     make
     make

-
-- 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
+  - 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
 ==========================
 
 RANDOM THINGS I'VE LEARNED
 ==========================


@@ -247,3 +353,16 @@ RANDOM THINGS I'VE LEARNED
   For now, we need to hack around it by copying xml to the build dir.
 
 
   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