Allow to include sections of other parts of the xml documentation.
authorEliel C. Sardanons <eliels@gmail.com>
Sat, 16 May 2009 20:01:22 +0000 (20:01 +0000)
committerEliel C. Sardanons <eliels@gmail.com>
Sat, 16 May 2009 20:01:22 +0000 (20:01 +0000)
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

Makefile
doc/appdocsxml.dtd
main/xml.c

index 0e2acb7..9bed308 100644 (file)
--- 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 \
index ba0ef27..c06f720 100644 (file)
@@ -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>
   <!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">
   <!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)>
   <!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)>
index 9a0c66d..fe00bfb 100644 (file)
@@ -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) {