Add a simple example of inclusion

0.7.9.3 is needed, but it's pushed on pip so it shouldn't
be too complicated.

Need the C extension as well, README updated to reflect
that.

This allowed noticing and fixing two errors in the
link_to_multiplexer snippet, as clang complained,
check the differences between the previous version
and the new one :)

README

@@ -24,6 +24,9 @@ for *stable* automatic formatting.
 * Follow [hotdoc's installation guide](https://people.collabora.com/~meh/hotdoc_hotdoc/html/installing.html),
   preferably in a virtualenv.
 
+* We *experimentally* use the hotdoc C extension to include functions by
+  name, follow the steps outlined [here](https://github.com/hotdoc/hotdoc_c_extension)
+
 * Optionally install the `hotdoc_search_extension`:
 
 ```

examples/bus_example.c

@@ -0,0 +1,82 @@
+#include <gst/gst.h>
+
+static GMainLoop *loop;
+
+static gboolean
+my_bus_callback (GstBus     *bus,
+         GstMessage *message,
+         gpointer    data)
+{
+  g_print ("Got %s message\n", GST_MESSAGE_TYPE_NAME (message));
+
+  switch (GST_MESSAGE_TYPE (message)) {
+    case GST_MESSAGE_ERROR: {
+      GError *err;
+      gchar *debug;
+
+      gst_message_parse_error (message, &err, &debug);
+      g_print ("Error: %s\n", err->message);
+      g_error_free (err);
+      g_free (debug);
+
+      g_main_loop_quit (loop);
+      break;
+    }
+    case GST_MESSAGE_EOS:
+      /* end-of-stream */
+      g_main_loop_quit (loop);
+      break;
+    default:
+      /* unhandled message */
+      break;
+  }
+
+  /* we want to be notified again the next time there is a message
+   * on the bus, so returning TRUE (FALSE means we want to stop watching
+   * for messages on the bus and our callback should not be called again)
+   */
+  return TRUE;
+}
+
+gint
+main (gint   argc,
+      gchar *argv[])
+{
+  GstElement *pipeline;
+  GstBus *bus;
+  guint bus_watch_id;
+
+  /* init */
+  gst_init (&argc, &argv);
+
+  /* create pipeline, add handler */
+  pipeline = gst_pipeline_new ("my_pipeline");
+
+  /* adds a watch for new message on our pipeline's message bus to
+   * the default GLib main context, which is the main context that our
+   * GLib main loop is attached to below
+   */
+  bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
+  bus_watch_id = gst_bus_add_watch (bus, my_bus_callback, NULL);
+  gst_object_unref (bus);
+
+  /* [...] */
+
+  /* create a mainloop that runs/iterates the default GLib main context
+   * (context NULL), in other words: makes the context check if anything
+   * it watches for has happened. When a message has been posted on the
+   * bus, the default main context will automatically call our
+   * my_bus_callback() function to notify us of that message.
+   * The main loop will be run until someone calls g_main_loop_quit()
+   */
+  loop = g_main_loop_new (NULL, FALSE);
+  g_main_loop_run (loop);
+
+  /* clean up */
+  gst_element_set_state (pipeline, GST_STATE_NULL);
+  gst_object_unref (pipeline);
+  g_source_remove (bus_watch_id);
+  g_main_loop_unref (loop);
+
+  return 0;
+}

examples/snippets.c

@@ -0,0 +1,38 @@
+#include <gst/gst.h>
+  
+static void
+link_to_multiplexer (GstPad     *tolink_pad,
+                     GstElement *mux)
+{
+  GstPad *pad;
+  gchar *srcname, *sinkname;
+
+  srcname = gst_pad_get_name (tolink_pad);
+  pad = gst_element_get_compatible_pad (mux, tolink_pad, NULL);
+  gst_pad_link (tolink_pad, pad);
+  sinkname = gst_pad_get_name (pad);
+  gst_object_unref (GST_OBJECT (pad));
+
+  g_print ("A new pad %s was created and linked to %s\n", sinkname, srcname);
+  g_free (sinkname);
+  g_free (srcname);
+}
+
+static void
+some_function (GstElement *tee)
+{
+  GstPad * pad;
+  gchar *name;
+
+  pad = gst_element_get_request_pad (tee, "src%d");
+  name = gst_pad_get_name (pad);
+  g_print ("A new pad %s was created\n", name);
+  g_free (name);
+
+  /* here, you would link the pad */
+
+  /* [..] */
+
+  /* and, after doing that, free our reference */
+  gst_object_unref (GST_OBJECT (pad));
+}

hotdoc.json

@@ -5,5 +5,6 @@
     "output": "built_doc", 
     "project_name": "gstdotcom", 
     "sitemap": "sitemap.txt",
-    "extra_assets": ["attachments", "images"]
+    "extra_assets": ["attachments", "images"],
+    "pkg_config_packages": ["gstreamer-1.0"]
 }

manual-bus.md

@@ -39,94 +39,8 @@ There are two different ways to use a bus:
   - Check for messages on the bus yourself. This can be done using
     `gst_bus_peek ()` and/or `gst_bus_poll ()`.
 
-<!-- end list -->
 
-``` 
+{{ examples/bus_example.c }}
-#include <gst/gst.h>
-
-static GMainLoop *loop;
-
-static gboolean
-my_bus_callback (GstBus     *bus,
-         GstMessage *message,
-         gpointer    data)
-{
-  g_print ("Got %s message\n", GST_MESSAGE_TYPE_NAME (message));
-
-  switch (GST_MESSAGE_TYPE (message)) {
-    case GST_MESSAGE_ERROR: {
-      GError *err;
-      gchar *debug;
-
-      gst_message_parse_error (message, &err, &debug);
-      g_print ("Error: %s\n", err->message);
-      g_error_free (err);
-      g_free (debug);
-
-      g_main_loop_quit (loop);
-      break;
-    }
-    case GST_MESSAGE_EOS:
-      /* end-of-stream */
-      g_main_loop_quit (loop);
-      break;
-    default:
-      /* unhandled message */
-      break;
-  }
-
-  /* we want to be notified again the next time there is a message
-   * on the bus, so returning TRUE (FALSE means we want to stop watching
-   * for messages on the bus and our callback should not be called again)
-   */
-  return TRUE;
-}
-
-gint
-main (gint   argc,
-      gchar *argv[])
-{
-  GstElement *pipeline;
-  GstBus *bus;
-  guint bus_watch_id;
-
-  /* init */
-  gst_init (&argc, &argv);
-
-  /* create pipeline, add handler */
-  pipeline = gst_pipeline_new ("my_pipeline");
-
-  /* adds a watch for new message on our pipeline's message bus to
-   * the default GLib main context, which is the main context that our
-   * GLib main loop is attached to below
-   */
-  bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
-  bus_watch_id = gst_bus_add_watch (bus, my_bus_callback, NULL);
-  gst_object_unref (bus);
-
-[..]
-
-  /* create a mainloop that runs/iterates the default GLib main context
-   * (context NULL), in other words: makes the context check if anything
-   * it watches for has happened. When a message has been posted on the
-   * bus, the default main context will automatically call our
-   * my_bus_callback() function to notify us of that message.
-   * The main loop will be run until someone calls g_main_loop_quit()
-   */
-  loop = g_main_loop_new (NULL, FALSE);
-  g_main_loop_run (loop);
-
-  /* clean up */
-  gst_element_set_state (pipeline, GST_STATE_NULL);
-  gst_object_unref (pipeline);
-  g_source_remove (bus_watch_id);
-  g_main_loop_unref (loop);
-
-  return 0;
-}
-    
-    
-```
 
 It is important to know that the handler will be called in the thread
 context of the mainloop. This means that the interaction between the

manual-pads.md

@@ -123,26 +123,7 @@ the stream, it can simply request a new output pad from the tee element.
 The following piece of code shows how you can request a new output pad
 from a “tee” element:
 
-``` 
+{{ examples/snippets.c#some_function }}
-static void
-some_function (GstElement *tee)
-{
-  GstPad * pad;
-  gchar *name;
-
-  pad = gst_element_get_request_pad (tee, "src%d");
-  name = gst_pad_get_name (pad);
-  g_print ("A new pad %s was created\n", name);
-  g_free (name);
-
-  /* here, you would link the pad */
-[..]
-
-  /* and, after doing that, free our reference */
-  gst_object_unref (GST_OBJECT (pad));
-}
-      
-```
 
 The `gst_element_get_request_pad ()` method can be used to get a pad
 from the element based on the name of the pad template. It is also
@@ -153,26 +134,7 @@ element and you need to request a pad that is compatible. The method
 pad, as shown in the next example. It will request a compatible pad from
 an Ogg multiplexer from any input.
 
-``` 
+{{ examples/snippets.c#link_to_multiplexer }}
-static void
-link_to_multiplexer (GstPad     *tolink_pad,
-             GstElement *mux)
-{
-  GstPad *pad;
-  gchar *srcname, *sinkname;
-
-  srcname = gst_pad_get_name (tolink_pad);
-  pad = gst_element_get_compatible_pad (mux, tolink_pad);
-  gst_pad_link (tolinkpad, pad);
-  sinkname = gst_pad_get_name (pad);
-  gst_object_unref (GST_OBJECT (pad));
-
-  g_print ("A new pad %s was created and linked to %s\n", sinkname, srcname);
-  g_free (sinkname);
-  g_free (srcname);
-}
-      
-```
 
 # Capabilities of a pad