1 GStreamer documentation notes
6 Please make sure you've read and understood everything in this file
7 before you try changing documentation.
12 GStreamer has two sets of documentation that we maintain:
13 * API references, using gtk-doc (gstreamer, gstreamer-libs)
14 * "books", using DocBook/XML (faq, manual, pwg)
19 OK, I've grown so tired of having to coax the docs to build every time I
20 get round to it that I've decided to note down some of the things that
21 are important to know.
25 * Our documentation should all be Docbook/XML. No SGML.
26 * The source for the documentation is:
27 - one or more .xml files, with the main one being gstreamer-(whatever).xml
30 - in .png (and maybe others)
31 * We want to generate docs in HTML, PS and PDF
32 * We want to use xml to to generate these
36 We stick to some simple conventions for writing docbook documentation.
38 - all id's start with chapter-, part-, section-, or misc-
39 - verify this is the case by looking at the generated file names in html/
40 - sections should also include the chapter name;
41 for example in a chapter called chapter-example, a section would be
42 called section-example-hello-world
43 * there are currently comments of the form <!-- synchronize with PWG -->
44 in the docbook file. Please check the relevant section of the other manual
47 HOW IMAGES ARE HANDLED
48 ----------------------
49 * the format of images used is:
54 * images may need to be converted from their source format to the end format
56 * a file called image.entities is generated that provides two entities:
58 ℑ is the file extension (png, ps, pdf)
59 * all generated images will be put in images/
61 HOW THE BUILD WORKS FOR EACH FORMAT
62 -----------------------------------
64 - xmlto html gstreamer-whatever.xml should produce the html docs.
65 - We do this in the html subdir of the doc builddir.
66 - images are copied to (builddir)/html/images
67 - PNGS should be set to all of the png's referenced for html, both
68 already there and auto-generated
71 - images are converted to .ps files in EPS format. Generated images are
73 - xmlto ps gstreamer-whatever.xml generates the ps file
77 - ps2pdf is the easiest
78 - we specify ps, PS as the image type, but using xmlto the build will fail
79 because it uses ps2pdf internally and it fails to generate the images
80 By hand-generating .pdf images before xmlto we can make the build succeed.
81 (This is why image-pdf has file ext pdf but type EPS; this tricks xmlto in
82 doing the right thing)
83 xmlto pdf gstreamer-whatever.xml generates pdf (but seems to fail on the
84 FAQ, so for now we use ps2pdf)
86 HOW THE BUILD SYSTEM IS SET UP
87 ------------------------------
88 * make all should build html, ps, and pdf
89 * html is built in a subdir, with the png/ps images copied there
90 * ps and pdf are built in the current dir, in one file
95 * aspell -b -c --mode=sgml --lang=en <file>.xml
96 unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags
102 * files under CVS control:
104 - gstreamer-sections.txt
105 describes which symbols later appear on one api-doc page
106 configure which symbols are shown/invisible/private
108 the types file lists all get_type() functions that register the GObject types
109 - gstreamer-docs.sgml
110 defines the overall structure of the api documentation
112 - only add the file to CVS if you have at least filled the short description
113 (filename corresponds to the <FILE> tag in the sections file)
114 - document as much as possible in the source (*.c files)
116 * what to do when adding a new piece of API:
117 - add both an entity and use the entity in gstreamer-docs.sgml
118 - add a new <SECTION> to gstreamer-sections.txt in the correct alphabetical
119 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 (default),<SUBSECTION Standard>,<SUBSECTION Private>
122 - document at least the Short_Description in tmpl/.sgml
123 - document symbols where they are definied, so that when one changes the
124 definition, the chaces are good that docs are updated.
125 - document functions, signals in the .c files
126 - document structs, typedefs, enums in the .h files
129 - make sure *-sections.txt has a <TITLE> set for each <FILE>
130 - add only *one* <TITLE> to each file, when you have multiple classes in one
131 source-file, create one <FILE> section for each class
132 - the <TITLE> *must* be named like the type of the GType, when it gets
133 registered (otherwise gtkdoc introspection fails)
134 - for clarity name the <FILE> like the <TITLE>, but all lowercase
136 * what to do when trying to improve the docs
137 - compare the output of
138 grep "_get_type" gstreamer-sections.txt | sort
139 with the types in XXX.types to detect entries that
141 - gtk docs does not warns about empty member docs!, run
142 find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \;
143 in the project root to find them
144 - gtk docs does not warns about empty Returns: docs!, run
145 find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@Returns: *$" {} \;
146 in the project root to find them
148 * what happens during a gtk-doc build ?
150 - based on a $(MODULE).types file:
151 - gtkdoc-scangobj creates a gtkdoc-scan binary
152 - using CC, LD, CFLAGS, LDFLAGS env var
153 - using --type-init-func and --module parameters
154 - gtkdoc-scan creates
155 - $MODULE.signals.new
156 - $MODULE.hierarchy.new
157 - $MODULE.interfaces.new
158 - $MODULE.prerequisites.new
160 - generated source and objects get deleted
161 - gtkdoc-scangobj merges changes into the original files
163 - extracts decls of functions, macros, enums, structs, unions from headers
166 - $MODULE-decl-list.txt
167 - $MODULE-decl-list.txt then should get copied to $MODULE-sections.txt
168 - scan-build.stamp gets created
170 - Template generation step:
171 - gtkdoc-mktmpl --module=$MODULE
172 - reads in tmpl/*.sgml
173 - moves them to tmpl/*.sgml.bak
174 - recreates tmpl/*.sgml according to $MODULE-sections.txt
175 - moves unused stuff to $MODULE-unused.txt
176 - tmpl-build.stamp gets generated
178 * Possible errors and how to fix them
179 - Warning: multiple "IDs" for constraint linkend: gst-tag-register.
180 - check if gst_tag_register is listed more than once in -sections.txt
182 STYLE GUIDE FOR GTK-DOC
183 =======================
184 - this is in addition to gtk-doc's style-guide.txt
186 - when documenting signals, use "the #Gst..." for the object receiving the
187 signal; no trailing dot, and no "that received the signal"
188 - function/macro descriptions are descriptive, not imperative
189 ie, it uses the third person verb
190 - synopsis and description should have most-used/application functions at the
192 - functions that can return FALSE/NULL or fail should describe their failure
193 conditions like this:
194 * Returns NULL if no element with the given name is found in the bin, if
195 * the frobble was stuck in the froob, or the frizzle was frazzed.
196 - a line with function attributes should be added before Returns:
198 "MT safe." - the function is verified to be multithreadingsafe
199 "Caller owns returned reference" for refcounted classes
200 "Caller owns returned value" for other types (iterators, ..)
201 - we do this because, in contrast with GLib/GTK, we are more explicit
202 about threadsafety and related issues
203 - link to signals from the description like this:
204 * The <link linkend="GstBin-element-added">element-added</link> signal
205 - the bottom of the description should say when the doc was last reviewed
207 * Last reviewed on 2005-10-28 (0.9.4)
209 WEBSITE DOCUMENTATION
210 =====================
212 Updating the online documentation is pretty simple.
214 a) have a working freedesktop.org account
215 b) $HOME/.ssh/config set up so that it has the right User for the Host
216 (for example, I have:
219 c) verify this works by doing ssh freedesktop.org and being logged in without
221 d) have verified your changes build documentation locally.
223 Then, after updating any of the docs, run "make upload" from that directory.
224 Or, run "make upload" from this (docs) directory.
228 As of september 2005 we have some system to document plugins and elements
229 in the various plugin packages.
231 - in a submodule, docs go in docs/plugins
232 - template can be copied from gst-plugins-base
233 - to add plugins documentation:
234 - create docs/plugins
235 - create Makefile.am and friends, add to configure.ac
236 - create docs/version.entities.in, add to configure.ac
238 - create $(module)-plugins.types with #include <gst/gst.h>
240 - edit the -docs.sgml
242 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
244 cvs add inspect/*.xml
246 - to add an element to be documented:
247 - add an include href in the Elements chapter for the element
249 - add a section for it in -sections.txt with
250 <FILE>element-(element)</FILE>
251 <TITLE>(element)</TITLE>
252 - add a gtk-doc section to the source code like:
254 * SECTION:element-multifdsink
256 and fill it with documentation about the element, preferably inside
257 a <refsect2> docbook container.
259 - either a few pipelines, inside <programlisting>
260 - or a piece of code:
261 - create an example program (element)-example.c in the plugin dir
262 - add the full path (starting with $(top_srcdir)) for this example
263 to the EXAMPLE_CFILES variable in Makefile.am
264 - add an xinclude of a file named "element-(element)-example.xml"
265 to the docbook documentation piece in the element source code
266 - add the header to EXTRA_HFILES in Makefile.am to be able to document
267 signals and args; in that case, the object struct needs to be in
268 -sections.txt outside of the Standard Subsection (which is annoying,
270 (FIXME: are we sure we can both do the xinclude from the tmpl/ sgml,
271 as well as an override from the source itself ? maybe we should just
272 make sure the xinclude is in the source itself instead ?)
273 - to rebuild the docs, do:
277 - examples will only show up using gtk-doc 1.4 or later - it relies on
278 merging stuff from .sgml with inline docs. We might want to change
279 this to only get stuff from the source.
281 - to add a plugin to be documented:
282 - make sure inspect/ has generated a .xml file for it
284 - add an include in -docs.sgml in the Plugins list for that plugin
287 "multiple constraints for linkend ID": check if each section in
288 -sections.txt actually starts and ends with <SECTION> and </SECTION>
290 RANDOM THINGS I'VE LEARNED
291 ==========================
293 * for clean builddir != srcdir separation, I wanted to use xmlto --searchpath
294 so the source xml could find the built entity file.
295 But xmlto --searchpath is (right now) for TeX input, not xml input.
296 xsltproc has a --path option (that xmlto doesn't use yet), but it
297 resolves single files to $(specified_path)/$(srcdir)/$(file)
298 For now, we need to hack around it by copying xml to the build dir.
301 Building GStreamer documentation
304 (old) DOCUMENTATION BUILDING NOTES
305 ----------------------------------
307 To build the GStreamer documentation you need the following installed (based on
308 Red Hat packages). These packages comes from rawhide and are the ones that
309 will be in Red Hat 7.3/8.0
314 openjade (needs to be rebuilt from SRPM for Red Hat 7.2)
341 Check http://www.imendio.com/projects/devhelp/
342 It's a really nice development app allowing you to look up API stuff
343 from various gtk-doc'd libraries. GStreamer is one of these ;)
345 gtk-doc generates both html API docs and the matching .devhelp files