gstreamer/docs
Thomas Vander Stichele 6b42c874d2 fix docs build
Original commit message from CVS:
fix docs build
2004-06-26 13:11:31 +00:00
..
code-reviews Re-arranged the build a bit to try to make it more sane. Added some debug. 2001-01-01 08:37:41 +00:00
design current set of design docs, in .txt format 2001-01-20 20:08:59 +00:00
faq gst-python 2004-06-18 17:38:13 +00:00
gst fix docs build 2004-06-26 13:11:31 +00:00
libs fix distcheck 2004-05-20 12:40:31 +00:00
manual Win32 README as a docbook file 2004-06-12 10:55:43 +00:00
plugins oops.. 2002-01-10 04:14:12 +00:00
pwg I'm too lazy to comment this 2004-05-17 16:25:48 +00:00
random bitrates 2004-06-24 14:35:21 +00:00
slides initial checkin 2000-01-30 10:44:33 +00:00
xsl patch from jrb 2002-12-18 09:19:44 +00:00
.gitignore merge in tagging 2003-11-24 02:09:23 +00:00
htmlinstall.mak uninstall fixes 2003-12-14 22:27:25 +00:00
image-eps fix docs build for good 2003-10-08 14:34:09 +00:00
image-pdf fix docs build for good 2003-10-08 14:34:09 +00:00
image-png fix docs build for good 2003-10-08 14:34:09 +00:00
Makefile.am fix non-validating docbook make sure validation gets checked before building 2004-01-29 17:25:18 +00:00
manuals.mak fix po download fix buglet in docs makefile 2004-04-20 16:10:48 +00:00
README backed out the change of gst.h added some comment about building docs to README 2004-05-14 15:17:30 +00:00
upload.mak third time I try commiting this today, let's hope I watch the result this time 2004-01-30 17:01:46 +00:00
version.entities.in this was wrong 2003-10-20 19:40:48 +00:00

GStreamer documentation notes

IMPORTANT
=========

Please make sure you've read and understood everything in this file
before you try changing documentation.

OVERVIEW
========

GStreamer has two sets of documentation that we maintain:
* API references, using gtk-doc (gstreamer, gstreamer-libs)
* "books", using DocBook/XML (faq, manual, pwg)

DOCBOOK NOTES
=============

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.

OVERVIEW
--------
* Our documentation should all be Docbook/XML.  No SGML.
* 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)
* We want to generate docs in HTML, PS and PDF
* We want to use xml to to generate these

CONVENTIONS
-----------
We stick to some simple conventions for writing docbook documentation.
* id names:
  - all id's start with chapter-, part-, section-, or misc-
  - verify this is the case by looking at the generated file names in html/
  - sections should also include the chapter name;
    for example in a chapter called chapter-example, a section would be
    called section-example-hello-world

HOW IMAGES ARE HANDLED
----------------------
* 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 FOR EACH FORMAT
-----------------------------------
* 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

* 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

* PDF :
  There are two ways:
  - ps2pdf is the easiest
  - 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 THE BUILD SYSTEM IS SET UP
------------------------------
* 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


GTK-DOC NOTES
=============

* files under CVS control:
  - Makefile.am
  - gstreamer-sections.txt
    describes which symbols later appear on one api-doc page
    configure which symbols are shown/invisible/private
  - gstreamer.types
    the types file lists all get_type() functions that register the GObject types
  - gstreamer-docs.sgml
    defines the overall structure of the api documentation
  - tmpl/
    - only add the file to CVS if you have at least filled the short description
      (filename corresponds to the <FILE> tag in the sections file)
    - document as much as possible in the source (*.c files)

* what to do when adding a new piece of API:
  - add both an entity and use the entity in gstreamer-docs.sgml
  - add a new section to gstreamer-sections.txt
  - add all documented symbols to gstreamer-sections.txt in the proper section

  - signals: document them properly in tmpl/.sgml
* checklist:
  - make sure -sections.txt has a <TITLE> set for each <FILE>

* what happens during a gtk-doc build ?
  - headers are scanned based on $(MODULE).types
    $(MODULE)-scan is created
    gtkdoc-scan is called with a sourcedir and a module name,
    where the module name is  $(MODULE)
    $(MODULE)-sections.txt is created if it doesn't exist yet (it should),
    as well as $(MODULE)-decl.txt and $(MODULE)-decl-list.txt
    
    and .args, .hierarchy and .signals files are created
    gtkdoc-scan is called 

  (FIXME: why is there gstreamer.types.in and gst-plugins.types.in ?)

* Possible errors and how to fix them
  - Warning: multiple "IDs" for constraint linkend: gst-tag-register.
    - check if gst_tag_register is listed more than once in -sections.txt

WEBSITE DOCUMENTATION
=====================

Updating the online documentation is pretty simple.
Make sure that you
a) have a working freedesktop.org account
b) $HOME/.ssh/config set up so that it has the right User for the Host
   (for example, I have:
Host freedesktop.org
  User thomasvs
c) verify this works by doing ssh freedesktop.org and being logged in without
   a password prompt
d) have verified your changes build documentation locally.

Then, after updating any of the docs, run "make upload" from that directory.
Or, run "make upload" from this (docs) directory.

RANDOM THINGS I'VE LEARNED
==========================

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