some hacking notes

Original commit message from CVS:
some hacking notes

diff --git a/docs/HACKING b/docs/HACKING
new file mode 100644 (file)
index 0000000..656e528
--- /dev/null
+++ b/docs/HACKING
@@ -0,0 +1,80 @@
+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.