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
- sections should also include the chapter name;
for example in a chapter called chapter-example, a section would be
called section-example-hello-world
-* 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.
HOW IMAGES ARE HANDLED
----------------------
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
=====================
- 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 CVS:
+ - 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.
For now, we need to hack around it by copying xml to the build dir.
-(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/
+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 ;)
projects / platform / upstream / gstreamer.git / blobdiff