some hacking notes

Original commit message from CVS:
some hacking notes
This commit is contained in:
Thomas Vander Stichele 2003-10-08 14:56:26 +00:00
parent 1983a8b4e4
commit 2d3862344c

80
docs/HACKING Normal file
View file

@ -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.