docs: add concept map

Add a graphviz dot file. Add rules to render it to svg and include in docs.
Nodes are clickable. It is an attempt to show how things fit together.

diff --git a/docs/gst/Makefile.am b/docs/gst/Makefile.am
index 4fa8f31..d92ea2a 100644 (file)
--- a/docs/gst/Makefile.am
+++ b/docs/gst/Makefile.am
@@ -33,7 +33,7 @@ include $(top_srcdir)/common/upload-doc.mak
 #$(basefiles): gstreamer-@GST_MAJORMINOR@%: gstreamer%
 #      cp $< $@
 
-#CLEANFILES = $(basefiles)
+#CLEANFILES += $(basefiles)
 
 # The top-level SGML file. Change it if you want.
 DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
@@ -75,14 +75,17 @@ IGNORE_HFILES= \
        grammar.tab.pre.h \
        types.h
 
+gst-universe.svg: gst-universe.dot
+       -dot -Tsvg $< | sed 's/\(font-size:[0-9]*\.[0-9]*\);/\1px;/g' >$@
+
 # Images to copy into HTML directory.
 HTML_IMAGES =
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
-content_files = building.xml running.xml
+content_files = building.xml running.xml gst-universe.svg
 
 # Other files to distribute.
-extra_files =
+extra_files = gst-universe.dot
 
 # CFLAGS and LDFLAGS for compiling scan program. Only needed if your app/lib
 # contains GtkObjects/GObjects and you want to document signals and properties.
@@ -100,3 +103,7 @@ GTKDOC_EXTRA_ENVIRONMENT= \
 DOC_OVERRIDES = $(DOC_MODULE)-overrides.txt
 
 include $(top_srcdir)/common/gtk-doc.mak
+
+# gtk-doc.mak defines CLEANFILES
+CLEANFILES += gst-universe.svg
+

diff --git a/docs/gst/gst-universe.dot b/docs/gst/gst-universe.dot
new file mode 100644 (file)
index 0000000..46f6b5c
--- /dev/null
+++ b/docs/gst/gst-universe.dot
@@ -0,0 +1,74 @@
+/* dot -Tpng gst-universe.dot -ogst-universe.png
+ *
+ * other layouts:
+ * circo -Tpng gst-universe.dot -ogst-universe.circo.png
+ * neato -Tpng gst-universe.dot -ogst-universe.neato.png
+ *
+ * todo:
+ * - add urls to api docs
+ * - use color
+ */
+digraph pipeline {
+  node [style="filled", shape="box", fillcolor="#eeeeee", fontsize="9px", fontname="Bitstream Vera Sans", target="_top"];
+  edge [labelfontsize="7px", fontsize="7px", labelfontname="Bitstream Vera Sans", fontname="Bitstream Vera Sans"];
+  labelloc=t;
+  nodesep=0.25;
+
+  /*
+  fontname="Bitstream Vera Sans";
+  fontsize="10px";
+  label="GStreamer Universe";
+  */
+  
+  /* objects */
+  application [color=black, fillcolor="#ffdddd"];
+  bin [href="GstBin.html", color=black, fillcolor="#ccccff"];
+  bus [href="GstBus.html"];
+  buffer [href="gstreamer-GstBuffer.html", color=black, fillcolor="#ddffdd"];
+  caps [href="gstreamer-GstCaps.html"];
+  clock [href="GstClock.html"];
+  element [href="GstElement.html", color=black, fillcolor="#ccccff"];
+  element_factory [href="GstElementFactory.html", label="element factory"];
+  event [href="gstreamer-GstEvent.html", color=black, fillcolor="#ddffdd"];
+  message [href="gstreamer-GstMessage.html", color=black, fillcolor="#ddffdd"];
+  pad [href="GstPad.html", color=black, fillcolor="#ccccff"];
+  pad_template [href="GstPadTemplate.html", label="pad template"];
+  pipeline [href="GstPipeline.html", color=black, fillcolor="#ccccff"];
+  plugin [href="GstPlugin.html"];
+  plugin_feature [href="GstPluginFeature.html", label="plugin feature"];
+  query [href="gstreamer-GstQuery.html", color=black, fillcolor="#ddffdd"];
+  registry [href="GstRegistry.html"];
+  structure [href="gstreamer-GstStructure.html"];
+  
+  /* relations */
+  bin -> element [label="is-a"];
+  pipeline -> bin [label="is-a"];
+  pipeline -> bus [label="has 1"];
+  pipeline -> clock [label="has 1"];
+  element -> pad_template [label="has n"];
+  element -> pad [label="has n"];
+  element -> clock [label="may provide"];
+  pad -> caps [label="has n"];
+  pad_template -> caps [label="has n"];
+  buffer -> caps [label="has n"];
+  caps -> structure [label="has n"];
+  bin -> element [label="has n"];
+    
+  pad -> pad_template [label="is created from"];
+  element -> element_factory [label="is created from"];
+    
+  element -> query [label="answers"];
+  element -> event [label="send & receive"];
+  element -> buffer [label="send & receive"];
+  element -> message [label="send"];
+  bus -> message [label="receive"];
+    
+  registry -> plugin [label="has n"];
+  plugin -> plugin_feature [label="has n"];
+  element_factory -> plugin_feature [label="is-a"];
+    
+  application -> pipeline [label="has"];
+  application -> bus [label="listen on"];
+  application -> query [label="send"];
+  application -> event [label="send"];
+}

diff --git a/docs/gst/gstreamer-docs.sgml b/docs/gst/gstreamer-docs.sgml
index e39d47f..a1c915e 100644 (file)
--- a/docs/gst/gstreamer-docs.sgml
+++ b/docs/gst/gstreamer-docs.sgml
@@ -32,6 +32,15 @@ GStreamer is cross-platform and works on most UNIX-like platforms as well as
 Windows.  It is released under the GNU Library General Public License
 (GNU LGPL).
     </para>
+    
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="gst-universe.svg" format="SVG"/>
+      </imageobject>
+      <caption>
+        <para>Relation between gstreamer core objects.</para>
+      </caption>
+    </mediaobject>
 
     <xi:include href="building.xml" />
     <xi:include href="running.xml" />