From 5897b1993d9611654d3caa328221851e94cc02f2 Mon Sep 17 00:00:00 2001
From: Stefan Kost <ensonic@users.sf.net>
Date: Tue, 7 Dec 2010 12:56:44 +0200
Subject: [PATCH] docs: some notes about our plugin docs workflow

---
 docs/random/ensonic/plugindocs.txt | 51 ++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 docs/random/ensonic/plugindocs.txt

diff --git a/docs/random/ensonic/plugindocs.txt b/docs/random/ensonic/plugindocs.txt
new file mode 100644
index 0000000000..3317eb70f0
--- /dev/null
+++ b/docs/random/ensonic/plugindocs.txt
@@ -0,0 +1,51 @@
+Plugin Docs
+===========
+
+In contrast to normal gtk-doc workflow modules will include
+common/gtk-doc-plugins.mak. This provides an additional 'make udpate' target.
+
+the "make update" target calls
+1.) common/gstdoc-scangobj --type-init-func="gst_init(NULL,NULL)" --module=$(DOC_MODULE) --source=$(PACKAGE)
+    common/scangobj-merge.py $(DOC_MODULE)
+
+the "tmpl" target is modified to run this extra step after "gtkdoc-mktmpl":
+2.) common/mangle-tmpl.py $(srcdir)/inspect tmpl
+
+and the "sgml" target is modified to run this step before "gtkdoc-mkdb":
+3.) for a in $(srcdir)/inspect/*.xml; do \
+  xsltproc --stringparam module $(MODULE) $(top_srcdir)/common/plugins.xsl $$a > xml/`basename $$a`;
+done
+
+Details
+=======
+
+1a.) gstdoc-scangobj
+-------------------
+- get types from registry instead of .types file
+- outputs inspect/plugin-<pluginname>.xml files
+- outputs signal and args files
+
+1b.) scangobj-merge.py
+---------------------
+- parse, update and write .signals and .args files
+
+2.) mangle-tmpl.py
+------------------
+- read data from inspect/plugin-<pluginname>.xml
+- insert/overwrite "Short Description" and "Long Description" in tmpl/
+- the "Long Description" contains a <xi:inlcude> for xml/element-<name>-details.xml
+
+3.) common/plugins.xsl
+----------------------
+- creates xml/plugin-<name>.xml and xml/element-<name>-details.xml
+
+
+TODO:
+-----
+- scangobj-merge.py -> gstdoc-scangobj
+- need a way to skip the tmpl step
+  - gtkdoc-mkdb needs a way to insert extra content
+  - maybe patch generated xml/*.xml files
+    - could common/plugins.xsl patch the files?
+      <refsect1 id="gstreamer-plugins-capsfilter.description" role="desc">
+