From c100402c751734d8633122b85f4a15c3ccf0678e Mon Sep 17 00:00:00 2001
From: Jonathan Pryor <jpryor@novell.com>
Date: Wed, 12 Aug 2009 20:42:42 +0000
Subject: [PATCH] 	* mdoc/Makefile: Add
 ../monodoc/Resources/mdoc-html-format.xsl as a 	  resource. 	*
 monodoc/Resources/mdoc-html-format: Added; XSLT file to match 	 
 "//format[@type='text/html']//*", to support "pass-through" 	  semantics. 
 This allows you to use actual HTML within your 	  documentation and
 have it visible to HTML-supporting output formats. 	  WARNING: Use as a
 "last resort" -- this is primarily intended for 	  importing existing
 HTML w/o needing lots of extra logic to convert 	  into mdoc format XML
 first (with a corresponding loss of fidelity). 	  However, it means
 that if (when) we get non-HTML output format 	  support, the <format
 type="text/html" /> blocks WILL be skipped for 	  that non-HTML output
 format.

	  For example, the forever-on-the-back-burner ROFF output support --
	  to remove the use of lynx, as no one ever has it installed --
	  wouldn't be able to support HTML format, so it would skip these
	  <format type="text/html"/> blocks.

	  Consider <format /> the moral equivalent of Perl POD's
	  '=begin formatname' block; see perlpod(1).
	* monodoc/Resources/mdoc-html-utils.xsl: <xsl:import/>
	  mdoc-html-format.xsl.  It *must* be imported (NOT included) so that
	  it will have a lower priority than other <template/>s, thus allowing
	  the HTML formatter to <xsl:apply-templates/> which then use the
	  "normal" rules.  This allows:
		<format type="text/html">
			<p><see cref="T:System.String" /></p>
		</format>
	  to work as expected.
	* monodoc/Makefile: Add mdoc-html-format.xsl as a resource.

svn path=/trunk/mcs/; revision=139795
---
 mcs/tools/mdoc/ChangeLog                      |  4 +++
 mcs/tools/mdoc/Makefile                       |  1 +
 mcs/tools/monodoc/ChangeLog                   | 31 +++++++++++++++++++
 mcs/tools/monodoc/Makefile                    |  2 ++
 .../monodoc/Resources/mdoc-html-format.xsl    | 24 ++++++++++++++
 .../monodoc/Resources/mdoc-html-utils.xsl     |  1 +
 6 files changed, 63 insertions(+)
 create mode 100644 mcs/tools/monodoc/Resources/mdoc-html-format.xsl

diff --git a/mcs/tools/mdoc/ChangeLog b/mcs/tools/mdoc/ChangeLog
index 332cacc2ccf..a106182185b 100644
--- a/mcs/tools/mdoc/ChangeLog
+++ b/mcs/tools/mdoc/ChangeLog
@@ -1,3 +1,7 @@
+2009-08-10  Jonathan Pryor <jpryor@novell.com>
+
+	* Makefile: Add ../monodoc/Resources/mdoc-html-format.xsl as a resource.
+
 2009-08-06  Jonathan Pryor <jpryor@novell.com>
 
 	* mdoc.exe.sources: Add ../../build/common/Consts.cs to the build.
diff --git a/mcs/tools/mdoc/Makefile b/mcs/tools/mdoc/Makefile
index 9ec57e1514a..576afc644d0 100644
--- a/mcs/tools/mdoc/Makefile
+++ b/mcs/tools/mdoc/Makefile
@@ -3,6 +3,7 @@ SUBDIRS =
 include ../../build/rules.make
 
 LOCAL_MCS_FLAGS = \
+	/resource:../monodoc/Resources/mdoc-html-format.xsl,mdoc-html-format.xsl    \
 	/resource:../monodoc/Resources/mdoc-html-utils.xsl,mdoc-html-utils.xsl      \
 	/resource:../monodoc/Resources/mdoc-sections-css.xsl,mdoc-sections-css.xsl  \
 	/resource:../monodoc/Resources/mono-ecma-css.xsl,mono-ecma-css.xsl          \
diff --git a/mcs/tools/monodoc/ChangeLog b/mcs/tools/monodoc/ChangeLog
index 2ee427ade03..763863b5e28 100644
--- a/mcs/tools/monodoc/ChangeLog
+++ b/mcs/tools/monodoc/ChangeLog
@@ -1,3 +1,34 @@
+2009-09-10  Jonathan Pryor  <jpryor@novell.com>
+
+	* Resources/mdoc-html-format: Added; XSLT file to match
+	  "//format[@type='text/html']//*", to support "pass-through"
+	  semantics.  This allows you to use actual HTML within your
+	  documentation and have it visible to HTML-supporting output formats.
+	  WARNING: Use as a "last resort" -- this is primarily intended for
+	  importing existing HTML w/o needing lots of extra logic to convert
+	  into mdoc format XML first (with a corresponding loss of fidelity).
+	  However, it means that if (when) we get non-HTML output format
+	  support, the <format type="text/html" /> blocks WILL be skipped for
+	  that non-HTML output format.
+
+	  For example, the forever-on-the-back-burner ROFF output support --
+	  to remove the use of lynx, as no one ever has it installed --
+	  wouldn't be able to support HTML format, so it would skip these
+	  <format type="text/html"/> blocks.
+
+	  Consider <format /> the moral equivalent of Perl POD's 
+	  '=begin formatname' block; see perlpod(1).
+	* Resources/mdoc-html-utils.xsl: <xsl:import/> mdoc-html-format.xsl.
+	  It *must* be imported (NOT included) so that it will have a lower
+	  priority than other <template/>s, thus allowing the HTML formatter
+	  to <xsl:apply-templates/> which then use the "normal" rules.  This
+	  allows:
+		<format type="text/html">
+			<p><see cref="T:System.String" /></p>
+		</format>
+	  to work as expected.
+	* Makefile: Add mdoc-html-format.xsl as a resource.
+
 2009-04-16  Jonathan Pryor  <jpryor@novell.com>
 
 	* Monodoc/man-provider.cs: NEVER return a non-null string from
diff --git a/mcs/tools/monodoc/Makefile b/mcs/tools/monodoc/Makefile
index cffa79d1060..56a09ea44b9 100644
--- a/mcs/tools/monodoc/Makefile
+++ b/mcs/tools/monodoc/Makefile
@@ -14,6 +14,7 @@ RESOURCE_FILES = \
 	Resources/home.html               \
 	Resources/Lminus.gif              \
 	Resources/Lplus.gif               \
+	Resources/mdoc-html-format.xsl    \
 	Resources/mdoc-html-utils.xsl     \
 	Resources/mdoc-sections-css.xsl   \
 	Resources/mdoc-sections.xsl       \
@@ -50,6 +51,7 @@ LIB_MCS_FLAGS = \
 	/resource:Resources/home.html,home.html                           \
 	/resource:Resources/Lminus.gif,Lminus.gif                         \
 	/resource:Resources/Lplus.gif,Lplus.gif                           \
+	/resource:Resources/mdoc-html-format.xsl,mdoc-html-format.xsl     \
 	/resource:Resources/mdoc-html-utils.xsl,mdoc-html-utils.xsl       \
 	/resource:Resources/mdoc-sections-css.xsl,mdoc-sections-css.xsl   \
 	/resource:Resources/mdoc-sections.xsl,mdoc-sections.xsl           \
diff --git a/mcs/tools/monodoc/Resources/mdoc-html-format.xsl b/mcs/tools/monodoc/Resources/mdoc-html-format.xsl
new file mode 100644
index 00000000000..10acd9c3b6a
--- /dev/null
+++ b/mcs/tools/monodoc/Resources/mdoc-html-format.xsl
@@ -0,0 +1,24 @@
+<?xml version="1.0"?>
+
+<!--
+	mdoc-html-format.xsl: HTML pass-through formatting support
+
+	Author: Jonathan Pryor (jpryor@novell.com)
+
+-->
+
+<xsl:stylesheet
+	version="1.0"
+	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+	>
+
+	<!-- pass-through any other elements unchanged - they may be HTML -->
+	<xsl:template match="//format[@type='text/html']//*">
+		<xsl:copy>
+			<xsl:copy-of select="@*" />
+			<xsl:apply-templates select="*|node()" />
+		</xsl:copy>
+	</xsl:template>
+
+</xsl:stylesheet>
+
diff --git a/mcs/tools/monodoc/Resources/mdoc-html-utils.xsl b/mcs/tools/monodoc/Resources/mdoc-html-utils.xsl
index 72d2c9554e2..7bb26d9cfab 100644
--- a/mcs/tools/monodoc/Resources/mdoc-html-utils.xsl
+++ b/mcs/tools/monodoc/Resources/mdoc-html-utils.xsl
@@ -24,6 +24,7 @@
 	version="1.0"
 	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 	>
+	<xsl:import href="mdoc-html-format.xsl" />
 	
 	<!-- TEMPLATE PARAMETERS -->
 	<xsl:param name="language" select="'C#'"/>
-- 
2.25.1