Allow to include sections of other parts of the xml documentation.

Avoid duplicating xml documentation by allowing to include other parts of
the xml documentation using XInclude.
Example:
   <xi:include xpointer="xpointer(/docs/function[@name='CHANNEL']/synopsis)" />
(Insert this line to include the synopsis of the CHANNEL function xml
documentation).

It is also possible to include documentation from other files in the
'documentation/' directory using the href="" attribute inside a xinclude
element.

(closes issue #15107)
Reported by: lmadsen

(issue #14444)
Reported by: ewieling



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@194982 65c4cc65-6c06-0410-ace0-fbb531ad65f3

3 files changed, 34 insertions, 16 deletions

diff --git a/Makefile b/Makefile
index 0e2acb73d..9bed308a8 100644
--- a/Makefile
+++ b/Makefile
@@ -497,7 +497,7 @@ doc/core-en_US.xml: $(foreach dir,$(MOD_SUBDIRS),$(shell $(GREP) -l "language=\"
 	@echo -n "Building Documentation For: "
 	@echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" > $@
 	@echo "<!DOCTYPE docs SYSTEM \"appdocsxml.dtd\">" >> $@
-	@echo "<docs>" >> $@
+	@echo "<docs xmlns:xi=\"http://www.w3.org/2001/XInclude\">" >> $@
 	@for x in $(MOD_SUBDIRS); do \
 		echo -n "$$x " ; \
 		for i in $$x/*.c; do \
diff --git a/doc/appdocsxml.dtd b/doc/appdocsxml.dtd
index ba0ef2726..c06f720e1 100644
--- a/doc/appdocsxml.dtd
+++ b/doc/appdocsxml.dtd
@@ -1,4 +1,15 @@
-  <!ELEMENT docs (application|function|agi)* >
+  <!ELEMENT docs (application|function|agi)*>
+  <!ATTLIST docs xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude">
+
+  <!ELEMENT xi:include (xi:fallback?) >
+  <!ATTLIST xi:include 
+  xmlns:xi	CDATA       #FIXED    "http://www.w3.org/2001/XInclude"
+  href		CDATA       #IMPLIED
+  parse		(xml|text)  "xml"
+  xpointer	CDATA       #IMPLIED
+  encoding	CDATA       #IMPLIED 
+  accept	CDATA       #IMPLIED
+  accept-language CDATA  #IMPLIED >
 
   <!ELEMENT application (synopsis?,syntax?,description?,see-also?)>
   <!ATTLIST application name CDATA #REQUIRED>
@@ -12,19 +23,19 @@
   <!ATTLIST agi name CDATA #REQUIRED>
   <!ATTLIST agi language CDATA #REQUIRED>
 
-  <!ELEMENT see-also (ref*)>
+  <!ELEMENT see-also (ref|xi:include)*>
 
-  <!ELEMENT ref (#PCDATA)*>
+  <!ELEMENT ref (#PCDATA)>
   <!ATTLIST ref type (application|function|astcli|link|manpage|filename|agi) #REQUIRED>
 
   <!ELEMENT synopsis (#PCDATA)>
 
-  <!ELEMENT syntax (parameter*)>
+  <!ELEMENT syntax (parameter|xi:include)*>
   <!ATTLIST syntax argsep CDATA ",">
 
-  <!ELEMENT description (para|note|warning|variablelist|enumlist)*>
+  <!ELEMENT description (para|note|warning|variablelist|enumlist|xi:include)*>
 
-  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter)*>
+  <!ELEMENT parameter (optionlist|enumlist|argument|para|note|warning|parameter|xi:include)*>
   <!ATTLIST parameter name CDATA "">
   <!ATTLIST parameter required (yes|no|true|false) "false">
   <!ATTLIST parameter multiple (yes|no|true|false) "false">
@@ -34,24 +45,24 @@
   <!ATTLIST parameter argsep CDATA ",">
 
   <!ELEMENT optionlist (option+)>
-  <!ELEMENT option (argument|para|note|warning|variablelist|enumlist)*>
+  <!ELEMENT option (argument|para|note|warning|variablelist|enumlist|xi:include)*>
   <!ATTLIST option name CDATA #REQUIRED>
   <!ATTLIST option argsep CDATA ",">
   <!ATTLIST option implies CDATA "">
   <!ATTLIST option hasparams CDATA "">
 
   <!ELEMENT enumlist (enum+)>
-  <!ELEMENT enum (para|note|warning|parameter|enumlist)*>
+  <!ELEMENT enum (para|note|warning|parameter|enumlist|xi:include)*>
   <!ATTLIST enum name CDATA "">
 
-  <!ELEMENT argument (para|note|warning|variablelist|argument)*>
+  <!ELEMENT argument (para|note|warning|variablelist|argument|xi:include)*>
   <!ATTLIST argument name CDATA #REQUIRED>
   <!ATTLIST argument multiple (yes|no|true|false) "false">
   <!ATTLIST argument required (yes|no|true|false) "false">
   <!ATTLIST argument hasparams (yes|no|true|false|optional) "false">
   <!ATTLIST argument argsep CDATA ",">
 
-  <!ELEMENT para (#PCDATA|astcli|literal|emphasis|filename|directory|replaceable|variable)*>
+  <!ELEMENT para (#PCDATA|astcli|literal|emphasis|filename|directory|replaceable|variable|xi:include)*>
   <!ELEMENT literal (#PCDATA)>
   <!ELEMENT emphasis (#PCDATA)>
   <!ELEMENT filename (#PCDATA)>
@@ -59,11 +70,11 @@
   <!ELEMENT directory (#PCDATA)>
   <!ELEMENT astcli (#PCDATA)>
  
-  <!ELEMENT note (para+)>
-  <!ELEMENT warning (para+)>
+  <!ELEMENT note (para+|xi:include*)>
+  <!ELEMENT warning (para+|xi:include*)>
 
-  <!ELEMENT variablelist (variable+)>
-  <!ELEMENT variable (#PCDATA|value|para)*>
+  <!ELEMENT variablelist (variable+|xi:include*)>
+  <!ELEMENT variable (#PCDATA|value|para|xi:include)*>
   <!ATTLIST variable name CDATA "">
 
   <!ELEMENT value (#PCDATA)>
diff --git a/main/xml.c b/main/xml.c
index 9a0c66d90..fe00bfbf6 100644
--- a/main/xml.c
+++ b/main/xml.c
@@ -29,6 +29,7 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #if defined(HAVE_LIBXML2)
 #include <libxml/parser.h>
 #include <libxml/tree.h>
+#include <libxml/xinclude.h>
 /* libxml2 ast_xml implementation. */
 
 
@@ -55,11 +56,17 @@ struct ast_xml_doc *ast_xml_open(char *filename)
 	}
 
 	doc = xmlReadFile(filename, NULL, XML_PARSE_RECOVER);
+	if (doc) {
+		/* process xinclude elements. */
+		if (xmlXIncludeProcess(doc) <= 0) {
+			xmlFreeDoc(doc);
+			return NULL;
+		}
+	}
 
 	return (struct ast_xml_doc *) doc;
 }
 
-
 void ast_xml_close(struct ast_xml_doc *doc)
 {
 	if (!doc) {