--- /dev/null
+OK, I've grown so tired of having to coax the docs to build every time I
+get round to it that I've decided to note down some of the things that
+are important to know.
+
+Here goes.
+
+A) Our documentation should all be Docbook/XML. No SGML.
+B) The source for the documentation is:
+ - one or more .xml files, with the main one being gstreamer-(whatever).xml
+ - image files
+ - in .fig
+ - in .png (and maybe others)
+
+C) We want to generate docs in HTML, PS and PDF
+D) We want to use xmlto to generate these
+
+THINGS TO DO IN THE SOURCE XML
+------------------------------
+
+
+HOW TO HANDLE IMAGES
+--------------------
+* the format of images used is:
+ - PNG for html
+ - EPS for ps
+ - PDF for pdf
+
+* images may need to be converted from their source format to the end format
+
+* a file called image.entities is generated that provides two entities:
+ ℑ and ℑ
+ ℑ is the file extension (png, ps, pdf)
+* all generated images will be put in images/
+
+HOW THE BUILD WORKS
+-------------------
+
+1) HTML
+-------
+xmlto html gstreamer-whatever.xml should produce the html docs.
+We do this in the html subdir of the doc builddir.
+images are copied to (builddir)/html/images
+PNGS should be set to all of the png's referenced for html, both
+already there and auto-generated
+
+2) PS
+-----
+images are converted to .ps files in EPS format. Generated images are
+put in images/
+xmlto ps gstreamer-whatever.xml generates the ps file
+
+3) PDF
+------
+There are two ways:
+a) ps2pdf is the easiest
+b) we specify ps, PS as the image type, but using xmlto the build will fail
+ because it uses ps2pdf internally and it fails to generate the images
+ By hand-generating .pdf images before xmlto we can make the build succeed.
+ (This is why image-pdf has file ext pdf but type EPS; this tricks xmlto in
+ doing the right thing)
+ xmlto pdf gstreamer-whatever.xml generates pdf (but seems to fail on the
+ FAQ, so for now we use ps2pdf)
+
+HOW WE SET UP OUR BUILD FOR THE DOCS
+------------------------------------
+make all should build html, ps, and pdf
+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
+
+
+
+
+THINGS I'VE LEARNED
+-------------------
+a) for clean builddir != srcdir separation, I wanted to use xmlto --searchpath
+ so the source xml could find the built entity file.
+ But xmlto --searchpath is (right now) for TeX input, not xml input.
+ xsltproc has a --path option (that xmlto doesn't use yet), but it
+ resolves single files to $(specified_path)/$(srcdir)/$(file)
+ For now, we need to hack around it by copying xml to the build dir.