documentation: remove links to element/plugin docs that don't exist

If an element or plugin is not documented, we'd just link to a page that
doesn't exist. There is an explanatory note at the top of the page that
explains that this means the element or plugin in question is not
documented, but people seem to regularly miss that note or still find
it confusing to run into 404s.

This commit adds a little perl helper script that removes the hyperlinks
to pages that don't exist. This also makes it much easier to see which
elements are actually documented or not.

3 files changed, 73 insertions, 1 deletions

diff --git a/bin/fix-undocumented-plugins-links b/bin/fix-undocumented-plugins-links
new file mode 100755
index 00000000..93bd4891
--- /dev/null
+++ b/bin/fix-undocumented-plugins-links
@@ -0,0 +1,67 @@
+#!/usr/bin/perl -w
+#
+# Copyright (C) 2009 Tim-Philipp Müller <tim centricular net>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Library General Public
+# License as published by the Free Software Foundation; either
+# version 2 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Library General Public License for more details.
+#
+# You should have received a copy of the GNU Library General Public
+# License along with this library; if not, write to the
+# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+#
+# -----------------------------------------------------------------------------
+#
+# Removes links to documentation pages that don't exist (in case where the
+# element or plugin in question is not documented). Outputs fixed plugins.html
+# page to stdout.
+#
+# -----------------------------------------------------------------------------
+
+use strict;
+
+my $PROG_NAME = 'fix-undocumented-plugins-links';
+my $WWW_ROOT = "";
+my $PLUGINS_HTML = "";
+
+if (scalar @ARGV != 2) {
+  print STDERR "Usage: $PROG_NAME PLUGINS.HTML WWW-ROOT-DIRECTORY\n";
+  exit 1;
+}
+
+$PLUGINS_HTML = $ARGV[0];
+$WWW_ROOT = $ARGV[1];
+
+if ( ! -f $PLUGINS_HTML ) { die "$PLUGINS_HTML is not a file!"; }
+if ( ! -d $WWW_ROOT ) { die "$WWW_ROOT is not a directory!"; }
+
+open (INPUT, $PLUGINS_HTML) ||
+   die "Could not open plugins.html input file $PLUGINS_HTML: $!";
+
+# Plugin link:
+#   <a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-bad-plugins/html/gst-plugins-bad-plugins-videomark.html">videomark</a>
+#
+# Element link:
+#   <a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/gst-plugins-base-plugins-plugin-videotestsrc.html">videotestsrc</a>
+#
+# There is likely more html markup on either side (table markers etc.)
+while (<INPUT>) {
+  if (m%(data/doc/gstreamer/[^>]+).>%) {
+    # print "check file: $1\n";
+    if ( ! -e "$WWW_ROOT/$1" ) {
+      # print "$1 does not exist.\n";
+      s/<a.href=[^>]*>([^<]*)<\/a>/$1/i;
+    }
+  }
+  print "$_";
+}
+
+close (INPUT);
+
diff --git a/src/htdocs/documentation/Makefile.am b/src/htdocs/documentation/Makefile.am
index 9c2741c2..dc5a65dc 100644
--- a/src/htdocs/documentation/Makefile.am
+++ b/src/htdocs/documentation/Makefile.am
@@ -2,6 +2,9 @@ built_pages = index.html licensing.html rtp.html plugins.html splitup.html gstre
 
 CHECKOUT_DIR = $(top_builddir)/cache/plugin-inspect-checkouts
 
+# the top_builddir here is not quite right, but should work for now
+FIX_UNDOCUMENTED_PLUGIN_LINKS = $(top_builddir)/bin/fix-undocumented-plugins-links
+
 checkoutdir:
 	echo "Check plugin documentation checkout directory $(CHECKOUT_DIR)"; \
 	mkdir -p $(CHECKOUT_DIR) || { \
@@ -48,5 +51,7 @@ plugins.xml-update:
 
 plugins.html: plugins.xsl plugins.xml-update
 	xsltproc -o plugins.html $(srcdir)/plugins.xsl plugins.xml
+	$(FIX_UNDOCUMENTED_PLUGIN_LINKS) plugins.html $(top_builddir) > plugins-fixed.html
+	mv plugins-fixed.html plugins.html
 
 include $(top_srcdir)/html.make
diff --git a/src/htdocs/documentation/plugins.xsl b/src/htdocs/documentation/plugins.xsl
index 3a642ac0..f3067961 100644
--- a/src/htdocs/documentation/plugins.xsl
+++ b/src/htdocs/documentation/plugins.xsl
@@ -18,7 +18,7 @@
     <xsl:call-template name="page">
       <xsl:with-param name="content">
         <h1>Overview of available plug-ins</h1>
-        <i>Note: if a link to an element is broken, this means the
+        <i>Note: if a link to an element or plugin is missing, this means the
            element is not documented yet.  We appreciate contributions
            to the documentation !</i>
         <xsl:element name="table">