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
44 HOW IMAGES ARE HANDLED
45 ----------------------
46 * the format of images used is:
51 * images may need to be converted from their source format to the end format
53 * a file called image.entities is generated that provides two entities:
55 ℑ is the file extension (png, ps, pdf)
56 * all generated images will be put in images/
58 HOW THE BUILD WORKS FOR EACH FORMAT
59 -----------------------------------
61 - xmlto html gstreamer-whatever.xml should produce the html docs.
62 - We do this in the html subdir of the doc builddir.
63 - images are copied to (builddir)/html/images
64 - PNGS should be set to all of the png's referenced for html, both
65 already there and auto-generated
68 - images are converted to .ps files in EPS format. Generated images are
70 - xmlto ps gstreamer-whatever.xml generates the ps file
74 - ps2pdf is the easiest
75 - we specify ps, PS as the image type, but using xmlto the build will fail
76 because it uses ps2pdf internally and it fails to generate the images
77 By hand-generating .pdf images before xmlto we can make the build succeed.
78 (This is why image-pdf has file ext pdf but type EPS; this tricks xmlto in
79 doing the right thing)
80 xmlto pdf gstreamer-whatever.xml generates pdf (but seems to fail on the
81 FAQ, so for now we use ps2pdf)
83 HOW THE BUILD SYSTEM IS SET UP
84 ------------------------------
85 * make all should build html, ps, and pdf
86 * html is built in a subdir, with the png/ps images copied there
87 * ps and pdf are built in the current dir, in one file
93 * spell checking with aspell
94 * aspell -b -c --mode=sgml --lang=en <file>.xml
95 unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags
101 * files under CVS control:
103 - gstreamer-sections.txt
104 describes which symbols later appear on one api-doc page
105 configure which symbols are shown/invisible/private
107 the types file lists all get_type() functions that register the GObject types
108 - gstreamer-docs.sgml
109 defines the overall structure of the api documentation
111 - only add the file to CVS if you have at least filled the short description
112 (filename corresponds to the <FILE> tag in the sections file)
113 - document as much as possible in the source (*.c files)
115 * what to do when adding a new piece of API:
116 - add both an entity and use the entity in gstreamer-docs.sgml
117 - add a new <SECTION> to gstreamer-sections.txt in the correct alphabetical
118 position related to the other sections (so that it is easier to locate)
119 - add all documented symbols to gstreamer-sections.txt in the proper section
120 (default),<SUBSECTION Standard>,<SUBSECTION Private>
121 - document at least the Short_Description in tmpl/.sgml
122 - document symbols where they are definied, so that when one changes the
123 definition, the chaces are good that docs are updated.
124 - document functions, signals in the .c files
125 - document structs, typedefs, enums in the .h files
128 - make sure *-sections.txt has a <TITLE> set for each <FILE>
129 - add only *one* <TITLE> to each file, when you have multiple classes in one
130 source-file, create one <FILE> section for each class
131 - the <TITLE> *must* be named like the type of the GType, when it gets
132 registered (otherwise gtkdoc introspection fails)
133 - for clarity name the <FILE> like the <TITLE>, but all lowercase
135 * what to do when trying to improve the docs
136 - compare the output of
137 grep "_get_type" gstreamer-sections.txt | sort
138 with the types in XXX.types to detect entries that
140 - gtk docs does not warns about empty member docs!, run
141 find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \; | wc -l
142 in the project root to find them
144 * what happens during a gtk-doc build ?
145 - headers are scanned based on $(MODULE).types
146 $(MODULE)-scan is created
147 gtkdoc-scan is called with a sourcedir and a module name,
148 where the module name is $(MODULE)
149 $(MODULE)-sections.txt is created if it doesn't exist yet (it should),
150 as well as $(MODULE)-decl.txt and $(MODULE)-decl-list.txt
151 and .args, .hierarchy and .signals files are created
152 gtkdoc-scan is called
153 - if it not works, try e.g. 'rm docs/gst/*.stamp'
155 * Possible errors and how to fix them
156 - Warning: multiple "IDs" for constraint linkend: gst-tag-register.
157 - check if gst_tag_register is listed more than once in -sections.txt
159 WEBSITE DOCUMENTATION
160 =====================
162 Updating the online documentation is pretty simple.
164 a) have a working freedesktop.org account
165 b) $HOME/.ssh/config set up so that it has the right User for the Host
166 (for example, I have:
169 c) verify this works by doing ssh freedesktop.org and being logged in without
171 d) have verified your changes build documentation locally.
173 Then, after updating any of the docs, run "make upload" from that directory.
174 Or, run "make upload" from this (docs) directory.
176 RANDOM THINGS I'VE LEARNED
177 ==========================
179 * for clean builddir != srcdir separation, I wanted to use xmlto --searchpath
180 so the source xml could find the built entity file.
181 But xmlto --searchpath is (right now) for TeX input, not xml input.
182 xsltproc has a --path option (that xmlto doesn't use yet), but it
183 resolves single files to $(specified_path)/$(srcdir)/$(file)
184 For now, we need to hack around it by copying xml to the build dir.