kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-11-04 05:15:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Eliel C. Sardanons
2009-05-16 20:01:22 +00:00
parent 766972a3cd
commit 2f996a3ab4
3 changed files with 34 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Makefile
View File

@@ -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 \

39
doc/appdocsxml.dtd
View 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>
@@ -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)>

9
main/xml.c
View 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) {