mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-04 16:39:39 +00:00
81 lines
2.6 KiB
Text
81 lines
2.6 KiB
Text
|
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.
|