more documentation work

4 files changed, 205 insertions, 38 deletions

diff --git a/doc/gss/getting-started.xml b/doc/gss/getting-started.xml
index 7e73a23..9d2b23e 100644
--- a/doc/gss/getting-started.xml
+++ b/doc/gss/getting-started.xml
@@ -20,12 +20,133 @@ Getting started with GStreamer Streaming Server.
 </refnamediv>
 
 <refsect1>
-<title>Getting Started</title>
+<title>Overview</title>
 
   <para>
-    Start here.
+    GStreamer Streaming Server (or GSS for short) is a custom HTTP
+    server that has specific features that make it useful for serving
+    media files, particularly live streaming video and video on demand.
+    GSS works best as a specialized origin server for only the media
+    portion of a web site.  This is similar to how you might use a
+    separate web server (and different web server software) for static
+    content vs. dynamic content.
   </para>
 
+  <para>
+    In this chapter, there are sections for installing GSS, configuring
+    GSS, and a section each for using GSS for live streams and video on
+    demand streams.
+  </para>
+
+</refsect1>
+
+<refsect1>
+<title>Installation</title>
+
+  <para>
+    The recommended installation method is to use the Ubuntu PPA
+    to install to a server running Ubuntu.  This will install the
+    appropriate files to start/stop the HTTP server when the machine
+    is turned on/off, using Upstart.  When installing from source,
+    the relevant files should be manually copied from the debian/
+    directory in the source code.
+  </para>
+
+<refsect2>
+<title>Installing Packages on Ubuntu</title>
+
+<para>
+  The GSS project maintainer occasionally uploads snapshots to the
+  GStreamer Streaming Server PPA, hosted on Launchpad.  Launchpad
+  automatically builds the package for precise on amd64 and i386,
+  which can be installed on precise or any later Ubuntu system.
+</para>
+
+<para>
+  The GSS PPA, including instructions for installing packages, can be
+  found on Launchpad at
+  <ulink role="online-location" url="https://launchpad.net/~dschleef/+archive/matterhorn-ppa/">https://launchpad.net/~dschleef/+archive/matterhorn-ppa/</ulink>.
+  The package is called "gst-streaming-server".
+</para>
+
+</refsect2>
+
+<refsect2>
+<title>Installing from source on Linux or UNIX-like systems</title>
+
+  <para>
+    The source code for GSS is stored using git at 
+    <ulink role="online-location" url="http://cgit.freedesktop.org/gstreamer/gst-streaming-server/">http://cgit.freedesktop.org/gstreamer/gst-streaming-server/</ulink>.
+    No source code releases in tar form have been done yet.
+  </para>
+
+  <para>
+    Code can be checked out from git using the commands:
+
+    <literallayout>
+      <userinput>git clone git://anongit.freedesktop.org/gstreamer/gst-streaming-server</userinput>
+    </literallayout>
+  </para>
+
+  <!-- this has been borrowed from the glib docs -->
+  <para>
+    On UNIX, GStreamer Streaming Server uses the standard GNU build system,
+    using <application>autoconf</application> for package
+    configuration and resolving portability issues,
+    <application>automake</application> for building makefiles
+    that comply with the GNU Coding Standards, and
+    <application>libtool</application> for building shared
+    libraries on multiple platforms.  The normal sequence for
+    compiling and installing GSS is thus:
+
+    <literallayout>
+      <userinput>./configure</userinput>
+      <userinput>make</userinput>
+      <userinput>make install</userinput>
+    </literallayout>
+    
+    The GSS web server can be tested in development by running the
+    program gss-streaming-server in the tools/ directory.
+  </para>
+
+  <para>
+    The standard options provided by <application>GNU
+    autoconf</application> may be passed to the
+    <command>configure</command> script.  Please see the
+    <application>autoconf</application> documentation or run
+    <command>./configure --help</command> for information about
+    the standard options.
+  </para>
+
+</refsect2>
 </refsect1>
 
+<refsect1>
+<title>Using GSS for Live Streams</title>
+
+  <para>
+  </para>
+
+</refsect2>
+
+<refsect1>
+<title>Using GSS for Video On Demand</title>
+
+  <para>
+    A collection of test files is available for testing video on
+    demand.  It is at FIXME.
+  </para>
+
+  <para>
+    Once the test collection is downloaded, untar the collection into
+    a convenient temporary directory.  Then create a directory named 'vod'
+    in the base directory for the web server.  If you are running in
+    development, this will be the directory in which the gst-streaming-server
+    resides.  If running from Ubuntu packages, this will be
+    /var/lib/gst-streaming-server/.
+  </para>
+
+</refsect1>
+
+
 </refentry>
diff --git a/doc/gss/gst-streaming-server-docs.sgml b/doc/gss/gst-streaming-server-docs.sgml
index e5e82fb..4606504 100644
--- a/doc/gss/gst-streaming-server-docs.sgml
+++ b/doc/gss/gst-streaming-server-docs.sgml
@@ -12,7 +12,7 @@
     <releaseinfo>
       This manual is for gst-streaming-server-&GSS_VERSION;.
       The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="http://gstreamer.net/gst-streaming-server/index.html">http://gstreamer.net/gst-streaming-server/</ulink>.
+      <ulink role="online-location" url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-streaming-server/html/">http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-streaming-server/html/</ulink>.
     </releaseinfo>
   </bookinfo>
 
@@ -21,46 +21,49 @@
     <xi:include href="getting-started.xml"/>
   </chapter>
   <chapter>
-    <title>Installation</title>
-    <xi:include href="installation.xml"/>
-  </chapter>
-  <chapter>
     <title>GSS HTTP Server</title>
     <xi:include href="gss-http-server.xml"/>
   </chapter>
   <chapter>
     <title>GSS Library Reference</title>
-    <xi:include href="xml/gss-adaptive.xml"/>
-    <xi:include href="xml/gss-addr-range.xml"/>
-    <xi:include href="xml/gss-box.xml"/>
-    <xi:include href="xml/gss-config.xml"/>
-    <xi:include href="xml/gss-drm.xml"/>
-    <xi:include href="xml/gss-html.xml"/>
-    <xi:include href="xml/gss-isom.xml"/>
-    <xi:include href="xml/gss-json.xml"/>
-    <xi:include href="xml/gss-log.xml"/>
-    <xi:include href="xml/gss-manager.xml"/>
-    <xi:include href="xml/gss-metrics.xml"/>
-    <xi:include href="xml/gss-module.xml"/>
-    <xi:include href="xml/gss-object.xml"/>
-    <xi:include href="xml/gss-playready.xml"/>
-    <xi:include href="xml/gss-program.xml"/>
-    <xi:include href="xml/gss-pull.xml"/>
-    <xi:include href="xml/gss-push.xml"/>
-    <xi:include href="xml/gss-resource.xml"/>
-    <xi:include href="xml/gss-rtsp.xml"/>
-    <xi:include href="xml/gss-server.xml"/>
-    <xi:include href="xml/gss-session.xml"/>
-    <xi:include href="xml/gss-sglist.xml"/>
-    <xi:include href="xml/gss-soup.xml"/>
-    <xi:include href="xml/gss-stream.xml"/>
-    <xi:include href="xml/gss-transaction.xml"/>
-    <!-- <xi:include href="xml/gss-types.xml"/> -->
-    <xi:include href="xml/gss-user.xml"/>
-    <xi:include href="xml/gss-utils.xml"/>
-    <xi:include href="xml/gss-vod.xml"/>
-    <xi:include href="xml/gss-websocket.xml"/>
-
+    <section>
+      <title>Modules</title>
+      <xi:include href="xml/gss-manager.xml"/>
+      <xi:include href="xml/gss-playready.xml"/>
+      <xi:include href="xml/gss-server.xml"/>
+      <xi:include href="xml/gss-user.xml"/>
+      <xi:include href="xml/gss-vod.xml"/>
+    </section>
+    <section>
+      <title>Classes</title>
+      <xi:include href="xml/gss-adaptive.xml"/>
+      <xi:include href="xml/gss-config.xml"/>
+      <xi:include href="xml/gss-module.xml"/>
+      <xi:include href="xml/gss-object.xml"/>
+      <xi:include href="xml/gss-program.xml"/>
+      <xi:include href="xml/gss-pull.xml"/>
+      <xi:include href="xml/gss-push.xml"/>
+      <xi:include href="xml/gss-resource.xml"/>
+      <xi:include href="xml/gss-stream.xml"/>
+      <xi:include href="xml/gss-websocket.xml"/>
+    </section>
+    <section>
+      <title>Utility</title>
+      <xi:include href="xml/gss-addr-range.xml"/>
+      <xi:include href="xml/gss-box.xml"/>
+      <xi:include href="xml/gss-drm.xml"/>
+      <xi:include href="xml/gss-html.xml"/>
+      <xi:include href="xml/gss-isom.xml"/>
+      <xi:include href="xml/gss-json.xml"/>
+      <xi:include href="xml/gss-log.xml"/>
+      <xi:include href="xml/gss-metrics.xml"/>
+      <xi:include href="xml/gss-rtsp.xml"/>
+      <xi:include href="xml/gss-session.xml"/>
+      <xi:include href="xml/gss-sglist.xml"/>
+      <xi:include href="xml/gss-soup.xml"/>
+      <xi:include href="xml/gss-transaction.xml"/>
+      <xi:include href="xml/gss-utils.xml"/>
+    </section>
   </chapter>
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
diff --git a/doc/gss/gst-streaming-server-sections.txt b/doc/gss/gst-streaming-server-sections.txt
index d6b2b69..39bdf8c 100644
--- a/doc/gss/gst-streaming-server-sections.txt
+++ b/doc/gss/gst-streaming-server-sections.txt
@@ -1,5 +1,6 @@
 <SECTION>
 <FILE>gss-log</FILE>
+<TITLE>GssLog</TITLE>
 GssErrorEnum
 gss_log_send_syslog
 gss_log_set_verbosity
@@ -9,12 +10,14 @@ gss_log_init
 
 <SECTION>
 <FILE>gss</FILE>
+<TITLE>Gss</TITLE>
 gss_init
 gss_deinit
 </SECTION>
 
 <SECTION>
 <FILE>gss-config</FILE>
+<TITLE>GssConfig</TITLE>
 GssConfig
 GssConfigClass
 gss_config_add_server_resources
@@ -42,6 +45,7 @@ gss_config_get_type
 
 <SECTION>
 <FILE>gss-adaptive</FILE>
+<TITLE>GssAdaptive</TITLE>
 GSS_ADAPTIVE_KEY_LENGTH
 GssAdaptive
 GssAdaptiveLevel
@@ -58,6 +62,7 @@ gss_adaptive_stream_get_name
 
 <SECTION>
 <FILE>gss-addr-range</FILE>
+<TITLE>GssAddrRangeList</TITLE>
 GssAddrRangeList
 gss_addr_range_list_check_address
 gss_addr_range_list_free
@@ -67,6 +72,7 @@ gss_addr_range_list_new_from_string
 
 <SECTION>
 <FILE>gss-drm</FILE>
+<TITLE>GssDrm</TITLE>
 GssDrmInfo
 GssDrmType
 gss_drm_get_drm_name
@@ -76,6 +82,7 @@ gss_drm_get_drm_uuid
 
 <SECTION>
 <FILE>gss-html</FILE>
+<TITLE>GssHtml</TITLE>
 GSS_A
 GSS_P
 gss_html_append_image
@@ -102,6 +109,7 @@ gss_html_header_bare
 
 <SECTION>
 <FILE>gss-box</FILE>
+<TITLE>GssBox</TITLE>
 GssBoxAinf
 GssBoxAvcn
 GssBoxCprt
@@ -178,6 +186,7 @@ GssBoxVmhd
 
 <SECTION>
 <FILE>gss-isom</FILE>
+<TITLE>GssIsom</TITLE>
 GssIsomFragment
 GssIsomFtyp
 GssIsomMovie
@@ -226,11 +235,13 @@ gss_isom_track_serialize_dash
 
 <SECTION>
 <FILE>gss-json</FILE>
+<TITLE>GssJson</TITLE>
 gss_json_gobject_to_data
 </SECTION>
 
 <SECTION>
 <FILE>gss-manager</FILE>
+<TITLE>GssManager</TITLE>
 gss_manager_create_pipeline
 gss_manager_new
 gss_manager_set_location
@@ -250,6 +261,7 @@ gss_manager_get_type
 
 <SECTION>
 <FILE>gss-metrics</FILE>
+<TITLE>GssMetrics</TITLE>
 GssMetrics
 gss_metrics_add_client
 gss_metrics_free
@@ -259,6 +271,7 @@ gss_metrics_remove_client
 
 <SECTION>
 <FILE>gss-module</FILE>
+<TITLE>GssModule</TITLE>
 gss_module_set_admin_resource
 <SUBSECTION Standard>
 GssModule
@@ -274,6 +287,7 @@ gss_module_get_type
 
 <SECTION>
 <FILE>gss-object</FILE>
+<TITLE>GssObject</TITLE>
 GSS_OBJECT_NAME
 GSS_OBJECT_SAFE_TITLE
 GSS_OBJECT_SERVER
@@ -300,6 +314,7 @@ gss_object_get_type
 
 <SECTION>
 <FILE>gss-playready</FILE>
+<TITLE>GssPlayready</TITLE>
 gss_playready_add_protection_header
 gss_playready_encrypt_samples
 gss_playready_generate_key
@@ -372,6 +387,7 @@ gss_program_get_type
 
 <SECTION>
 <FILE>gss-pull</FILE>
+<TITLE>GssPull</TITLE>
 gss_pull_new
 <SUBSECTION Standard>
 GssPull
@@ -387,6 +403,7 @@ gss_pull_get_type
 
 <SECTION>
 <FILE>gss-push</FILE>
+<TITLE>GssPush</TITLE>
 gss_push_new
 GssPushMethod
 <SUBSECTION Standard>
@@ -403,6 +420,7 @@ gss_push_get_type
 
 <SECTION>
 <FILE>gss-resource</FILE>
+<TITLE>GssResource</TITLE>
 GssResource
 GssResourceFlags
 gss_resource_file
@@ -417,6 +435,7 @@ gss_resource_unimplemented
 
 <SECTION>
 <FILE>gss-rtsp</FILE>
+<TITLE>GssRtsp</TITLE>
 GssRtspStream
 gss_rtsp_stream_free
 gss_rtsp_stream_new
@@ -467,6 +486,7 @@ gss_server_get_type
 
 <SECTION>
 <FILE>gss-session</FILE>
+<TITLE>GssSession</TITLE>
 GssSession
 GssSessionAuthorizationFunc
 gss_addr_address_check
@@ -491,6 +511,7 @@ gss_session_set_hosts_allow
 
 <SECTION>
 <FILE>gss-sglist</FILE>
+<TITLE>GssSglist</TITLE>
 GssSGChunk
 GssSGList
 gss_sglist_free
@@ -502,6 +523,7 @@ gss_sglist_new
 
 <SECTION>
 <FILE>gss-soup</FILE>
+<TITLE>GssSoup</TITLE>
 gss_soup_get_base_url_http
 gss_soup_get_base_url_https
 gss_soup_get_request_host
@@ -547,6 +569,7 @@ gss_stream_get_type
 
 <SECTION>
 <FILE>gss-transaction</FILE>
+<TITLE>GssTransaction</TITLE>
 GssTransactionCallback
 GssTransactionFunc
 GssTransaction
@@ -564,6 +587,7 @@ gss_transaction_is_secure
 
 <SECTION>
 <FILE>gss-types</FILE>
+<TITLE>GssTypes</TITLE>
 GssConnection
 GssHLSSegment
 GssMetrics
@@ -579,6 +603,7 @@ GssTransaction
 
 <SECTION>
 <FILE>gss-user</FILE>
+<TITLE>GssUser</TITLE>
 gss_user_add_user_info
 gss_user_get_string
 gss_user_get_type
@@ -598,6 +623,7 @@ GSS_TYPE_USER
 
 <SECTION>
 <FILE>gss-utils</FILE>
+<TITLE>GssUtils</TITLE>
 GSS_CLEANUP
 GSS_TEXT_HTML
 GSS_TEXT_PLAIN
@@ -618,6 +644,7 @@ g_object_set_as_string
 
 <SECTION>
 <FILE>gss-vod</FILE>
+<TITLE>GssVod</TITLE>
 gss_vod_get_type
 gss_vod_new
 <SUBSECTION Standard>
diff --git a/gst-streaming-server/gss-adaptive.c b/gst-streaming-server/gss-adaptive.c
index ad2ed1a..483be60 100644
--- a/gst-streaming-server/gss-adaptive.c
+++ b/gst-streaming-server/gss-adaptive.c
@@ -48,6 +48,22 @@
 #include <fcntl.h>
 #include <openssl/aes.h>
 
+/**
+ * SECTION:gss-adaptive
+ * @short_description: Class for describing adaptive bitrate streams
+ * @see_also: #GssVod
+ *
+ * GssAdaptive represents a collection of media files on disk that
+ * are different representations of the same source media.  Primarily,
+ * this means encodings at different bitrates intended for adaptive
+ * bitrate streaming.
+ * 
+ * Normally, GssAdaptive objects are automatically created and
+ * managed by a GssVod object that is attached to a GssServer.
+ * 
+ * Last reviewed on 2014-01-04 (0.10.0.1)
+ */
+
 #define AUDIO_TRACK_ID 1
 #define VIDEO_TRACK_ID 2