[asterisk-commits] eliel: branch group/appdocsxml r148242 - in /team/group/appdocsxml: include/a...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Fri Oct 10 07:33:56 CDT 2008


Author: eliel
Date: Fri Oct 10 07:33:56 2008
New Revision: 148242

URL: http://svn.digium.com/view/asterisk?view=rev&rev=148242
Log:
Add a new tag <see-also> of the form:
<see-also>
     <ref type="application">Appname</ref>
     <ref type="function">Funcname</ref>
     <ref type="link">URL</ref>
</see-also>

Modified:
    team/group/appdocsxml/include/asterisk/pbx.h
    team/group/appdocsxml/main/pbx.c

Modified: team/group/appdocsxml/include/asterisk/pbx.h
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/include/asterisk/pbx.h?view=diff&rev=148242&r1=148241&r2=148242
==============================================================================
--- team/group/appdocsxml/include/asterisk/pbx.h (original)
+++ team/group/appdocsxml/include/asterisk/pbx.h Fri Oct 10 07:33:56 2008
@@ -85,6 +85,7 @@
 	char *desc;		/*!< Help text that explains it all */
 	char *syntax;		/*!< Syntax description */
 	char *arguments;	/*!< Arguments description */
+	char *seealso;		/*!< See also */
 	enum doc_src docsrc;		/*!< Where the documentation come from */
 	int (*read)(struct ast_channel *, const char *, char *, char *, size_t);	/*!< Read function, if read is supported */
 	int (*write)(struct ast_channel *, const char *, char *, const char *);		/*!< Write function, if write is supported */

Modified: team/group/appdocsxml/main/pbx.c
URL: http://svn.digium.com/view/asterisk/team/group/appdocsxml/main/pbx.c?view=diff&rev=148242&r1=148241&r2=148242
==============================================================================
--- team/group/appdocsxml/main/pbx.c (original)
+++ team/group/appdocsxml/main/pbx.c Fri Oct 10 07:33:56 2008
@@ -154,8 +154,10 @@
 					<value name="FAILED" />
 				</variable>
 			</variablelist>
-			<para>See Also: Playback (application) -- Play sound file(s) to the channel, that cannot be interrupted</para>
 		</description>
+		<see-also>
+			<ref type="application">Playback</ref>
+		</see-also>
 	</application>
 	<application name="Busy" language="en_US">
 		<synopsis>
@@ -308,9 +310,11 @@
 			<replaceable>channel</replaceable> (as opposed to the current one) and stores it as a variable
 			(<replaceable>newvar</replaceable>) in the current channel (the channel that is calling this
 			application). Variables created by this application have the same inheritance properties as those
-			created with the <literal>Set</literal> application. See the documentation for <literal>Set</literal>
-			for more information.</para>
+			created with the <literal>Set</literal> application.</para>
 		</description>
+		<see-also>
+			<ref type="application">Set</ref>
+		</see-also>
 	</application>
 	<application name="Hangup" language="en_US">
 		<synopsis>
@@ -365,10 +369,11 @@
 		</syntax>
 		<description>
 			<para>This application does nothing. However, it is useful for debugging purposes.</para>
-			<para>This method can be used to see the evaluations of variables or functions without having any effect.
-			Alternatively, see the <literal>Verbose()</literal> application for finer grain control of output at
-			custom verbose levels.</para>
+			<para>This method can be used to see the evaluations of variables or functions without having any effect.</para>
 		</description>
+		<see-also>
+			<ref type="application">Verbose</ref>
+		</see-also>
 	</application>
 	<application name="Proceeding" language="en_US">
 		<synopsis>
@@ -456,8 +461,7 @@
 		</syntax>
 		<description>
 			<para>This application will play the sounds that correspond to the digits of
-			the given number. This will use the language that is currently set for the channel.
-			See the LANGUAGE() function for more information on setting the language for the channel.</para>
+			the given number. This will use the language that is currently set for the channel.</para>
 		</description>
 	</application>
 	<application name="SayNumber" language="en_US">
@@ -585,8 +589,11 @@
 		<description>
 			<para>This application waits for the user to enter a new extension for a specified number
 			of <replaceable>seconds</replaceable>.</para>
-			<para>See Also: Playback(application), Background(application).</para>
 		</description>
+		<see-also>
+			<ref type="application">Playback</ref>
+			<ref type="application">Background</ref>
+		</see-also>
 	</application>
 	<function name="EXCEPTION" language="en_US">
 		<synopsis>
@@ -758,6 +765,7 @@
 	char *description;			/*!< Description (help text) for 'show application &lt;name&gt;' */
 	char *syntax;				/*!< Syntax text for 'core show applications' */
 	char *arguments;			/*!< Arguments description */
+	char *seealso;				/*!< See also */
 	enum doc_src docsrc;			/*!< Where the documentation come from. */
 	AST_RWLIST_ENTRY(ast_app) list;		/*!< Next app in list */
 	struct ast_module *module;		/*!< Module this app belongs to */
@@ -2952,12 +2960,12 @@
 {
 	struct ast_custom_function *acf;
 	/* Maximum number of characters added by terminal coloring is 22 */
-	char infotitle[64 + AST_MAX_APP + 22], syntitle[40], destitle[40], argtitle[40];
-	char info[64 + AST_MAX_APP], *synopsis = NULL, *description = NULL;
+	char infotitle[64 + AST_MAX_APP + 22], syntitle[40], destitle[40], argtitle[40], seealsotitle[40];
+	char info[64 + AST_MAX_APP], *synopsis = NULL, *description = NULL, *seealso = NULL;
 	char stxtitle[40], *syntax = NULL, *arguments = NULL;
 	int syntax_size;
 #ifndef XML_DOCUMENTATION
-	int description_size, synopsis_size, arguments_size;
+	int description_size, synopsis_size, arguments_size, seealso_size;
 #endif
 	char *ret = NULL;
 	int which = 0;
@@ -3011,6 +3019,12 @@
 	else
 		arguments_size = strlen("Not available") + 23;
 	arguments = alloca(arguments_size);
+
+	if (acf->seealso)
+		seealso_size = strlen(acf->seealso) + 23;
+	else
+		seealso_size = strlen("Not available") + 23;
+	seealso = alloca(seealso_size);	
 #endif
 	if (acf->syntax)
 		syntax_size = strlen(acf->syntax) + 23;
@@ -3024,6 +3038,7 @@
 	term_color(argtitle, "[Arguments]\n", COLOR_MAGENTA, 0, 40);
 	term_color(syntitle, "[Synopsis]\n", COLOR_MAGENTA, 0, 40);
 	term_color(destitle, "[Description]\n", COLOR_MAGENTA, 0, 40);
+	term_color(seealsotitle, "[See Also]\n", COLOR_MAGENTA, 0, 40);
 	term_color(syntax,
 		   acf->syntax ? acf->syntax : "Not available",
 		   COLOR_CYAN, 0, syntax_size);
@@ -3031,6 +3046,7 @@
 	arguments = xmldoc_colorization(acf->arguments ? acf->arguments : "Not available", COLOR_CYAN, COLOR_BLACK);
 	synopsis = xmldoc_colorization(acf->synopsis ? acf->synopsis : "Not available", COLOR_CYAN, COLOR_BLACK);
 	description = xmldoc_colorization(acf->desc ? acf->desc : "Not available", COLOR_CYAN, COLOR_BLACK);
+	seealso = xmldoc_colorization(acf->seealso ? acf->seealso : "Not available", COLOR_CYAN, COLOR_BLACK);
 #else
 	term_color(arguments,
 		  acf->arguments ? acf->arguments : "Not available",
@@ -3041,14 +3057,18 @@
 	term_color(description,
 		  acf->desc ? acf->desc : "Not available",
 		  COLOR_CYAN, 0, description_size);
+	term_color(seealso,
+		  acf->seealso ? acf->seealso : "Not available",
+		  COLOR_CYAN, 0, seealso_size);
 #endif
 
-	ast_cli(a->fd,"%s%s%s\n\n%s%s\n\n%s%s\n\n%s%s\n", infotitle, stxtitle, syntax, argtitle, arguments, 
-		syntitle, synopsis, destitle, description);
+	ast_cli(a->fd,"%s%s%s\n\n%s%s\n\n%s%s\n\n%s%s\n\n%s%s\n", infotitle, stxtitle, syntax, argtitle, arguments, 
+		syntitle, synopsis, destitle, description, seealsotitle, seealso);
 #ifdef XML_DOCUMENTATION
 	ast_free(arguments);
 	ast_free(synopsis);
 	ast_free(description);
+	ast_free(seealso);
 #endif
 
 	return CLI_SUCCESS;
@@ -3113,6 +3133,7 @@
 	{ "\"", "\"", COLOR_CYAN, COLOR_BLACK, "<directory>", "</directory>" },
 	{ "${", "}", COLOR_GREEN, COLOR_BLACK, "<variable>", "</variable>" },
 	{ "", "", COLOR_BLUE, COLOR_BLACK, "<enum>", "</enum>" },
+	{ "\'", "\'", COLOR_GRAY, COLOR_BLACK, "<astcli>", "</astcli>" },
 
 	/* Special tags */
 	{ "", "", COLOR_YELLOW, COLOR_BLACK, "<note>", "</note>" },
@@ -4083,6 +4104,84 @@
 }
 
 /*! \internal
+ *  \brief Parse the <see-also> node.
+ *  \param type 'application' or 'function'.
+ *  \param name Application or functions name.
+ *  \retval NULL on error.
+ *  \retval Content of the see-also node.
+ */
+static char *xmldoc_parse_seealso(const char *type, const char *name)
+{
+	struct ast_str *outputstr;
+	char *output, *content;
+	ast_xml_node *node;
+	ast_xml_attr *typename;
+
+	if (ast_strlen_zero(type) || ast_strlen_zero(name)) {
+		return NULL;
+	}
+
+	/* get the application/function root node. */
+	node = xmldoc_get_node(documentation_tree, type, name, documentation_language);	
+	if (!node || !node->AST_XML_CHILD) {
+		return NULL;
+	}
+
+	/* Find the <see-also> node. */
+	node = node->AST_XML_CHILD;
+	while (node) {
+		if (!strcasecmp((char *)node->AST_XML_NAME, "see-also")) {
+			break;
+		}
+		node = node->AST_XML_NEXT;
+	}
+
+	if (!node || !node->AST_XML_CHILD) {
+		/* we couldnt find a <see-also> node. */
+		return NULL;
+	}
+
+	/* prepare the output string. */
+	outputstr = ast_str_create(1);
+	if (!outputstr) {
+		return NULL;
+	}
+
+	/* get into the <see-also> node. */
+	node = node->AST_XML_CHILD;
+	while (node) {	
+		if (strcasecmp((char *)node->AST_XML_NAME, "ref")) {
+			node = node->AST_XML_NEXT;
+			continue;
+		}
+
+		/* parse the <ref> node. 'type' attribute is required. */
+		typename = ast_xml_get_attribute(node, "type");
+		if (typename) {
+			content = ast_xml_get_text(node);
+			if (content) {
+				if (!strcasecmp(typename, "application") || !strcasecmp(typename, "function")) {
+					ast_str_append(&outputstr, 0, "%s: Type <astcli>core show %s %s</astcli> for more info.\n", 
+						content, typename, content);
+				} else if (!strcasecmp(typename, "astcli")) {
+					ast_str_append(&outputstr, 0, "%s: Type <astcli>help %s</astcli> for more info.\n", content, content);
+				} else if (!strcasecmp(typename, "link")) {
+					ast_str_append(&outputstr, 0, "%s\n", content);
+				}			
+				ast_xml_free_text(content);
+			}
+			ast_xml_free_attr(typename);
+		}
+		node = node->AST_XML_NEXT;
+	}
+
+	output = ast_strdup(outputstr->str);
+	ast_free(outputstr);
+
+	return output;
+}
+
+/*! \internal
  *  \brief Parse a <enum> node.
  *  \brief fixnode An ast_xml_node pointer to the <enum> node. 
  *  \bried buffer The output buffer.
@@ -4469,6 +4568,7 @@
 		acf->desc = xmldoc_get_field("function", acf->name, "description", 0);
 		acf->syntax = xmldoc_get_syntax("function", acf->name);
 		acf->arguments = xmldoc_build_arguments("function", acf->name);
+		acf->seealso = xmldoc_parse_seealso("functions", acf->name);
 		acf->docsrc = AST_XML_DOC;
 	}
 #endif
@@ -6184,6 +6284,7 @@
 		tmp->description = xmldoc_get_field("application", app, "description", 0);
 		tmp->syntax = xmldoc_get_syntax("application", app);
 		tmp->arguments = xmldoc_build_arguments("application", app);
+		tmp->seealso = xmldoc_parse_seealso("application", app);
 		tmp->docsrc = AST_XML_DOC;
 	} else {
 #endif
@@ -6358,10 +6459,12 @@
 			if (!strcasecmp(aa->name, a->argv[app])) {
 				/* Maximum number of characters added by terminal coloring is 22 */
 				char infotitle[64 + AST_MAX_APP + 22], syntitle[40], destitle[40], stxtitle[40], argtitle[40];
+				char seealsotitle[40];
 				char info[64 + AST_MAX_APP], *synopsis = NULL, *description = NULL, *syntax = NULL, *arguments = NULL;
+				char *seealso;
 				int syntax_size;
 #ifndef XML_DOCUMENTATION
-				int synopsis_size, description_size, arguments_size; 
+				int synopsis_size, description_size, arguments_size, seealso_size; 
 #endif
 
 				no_registered_app = 0;
@@ -6389,6 +6492,12 @@
 				else
 					arguments_size = strlen("Not available") + 23;
 				arguments = alloca(arguments_size);
+			
+				if (aa->seealso)
+					seealso_size = strlen(aa->seealso) + 23;
+				else
+					seealso_size = strlen("Not available") + 23;
+				seealso = alloca(seealso_size);
 #endif
 
 #ifdef XML_DOCUMENTATION
@@ -6402,10 +6511,12 @@
 					term_color(argtitle, "[Arguments]\n", COLOR_MAGENTA, 0, 40);
 					term_color(syntitle, "[Synopsis]\n", COLOR_MAGENTA, 0, 40);
 					term_color(destitle, "[Description]\n", COLOR_MAGENTA, 0, 40);
+					term_color(seealsotitle, "[See Also]\n", COLOR_MAGENTA, 0, 40);
 #ifdef XML_DOCUMENTATION
 					description = xmldoc_colorization(aa->description ? aa->description : "Not available", COLOR_CYAN, COLOR_BLACK);
 					arguments = xmldoc_colorization(aa->arguments ? aa->arguments : "Not available", COLOR_CYAN, COLOR_BLACK);
 					synopsis = xmldoc_colorization(aa->synopsis ? aa->synopsis : "Not available", COLOR_CYAN, COLOR_BLACK);
+					seealso = xmldoc_colorization(aa->seealso ? aa->seealso : "Not available", COLOR_CYAN, COLOR_BLACK);
 #else
 					term_color(synopsis,
 									aa->synopsis ? aa->synopsis : "Not available",
@@ -6417,17 +6528,21 @@
 					term_color(arguments,
 									aa->arguments ? aa->arguments : "Not available",
 									COLOR_CYAN, 0, arguments_size);
+					term_color(seealso,
+									aa->seealso ? aa->seealso : "Not available",
+									COLOR_CYAN, 0, seealso_size);
 #endif
 					term_color(syntax,
 									aa->syntax ? aa->syntax : "Not available",
 									COLOR_CYAN, 0, syntax_size);
 
-					ast_cli(a->fd,"%s%s%s\n\n%s%s\n\n%s%s\n\n%s%s\n", infotitle, stxtitle, syntax, argtitle, 
-						arguments, syntitle, synopsis, destitle, description);
+					ast_cli(a->fd,"%s%s%s\n\n%s%s\n\n%s%s\n\n%s%s\n\n%s%s\n", infotitle, stxtitle, syntax, argtitle, 
+						arguments, syntitle, synopsis, destitle, description, seealsotitle, seealso);
 #ifdef XML_DOCUMENTATION
 					ast_free(description);
 					ast_free(arguments);
 					ast_free(synopsis);
+					ast_free(seealso);
 #endif
 				} else {
 					/* ... one of our applications, show info ...*/
@@ -6435,12 +6550,14 @@
 						"[Syntax]\n  %s\n\n"
 						"[Arguments]\n%s\n\n"
 						"[Synopsis]\n  %s\n\n"
-						"[Description]\n%s\n",
+						"[Description]\n%s\n"
+						"[See Also]\n%s\n",
 						aa->name,
 						aa->syntax ? aa->syntax : "Not available",
 						aa->arguments ? aa->arguments : "Not available",
 						aa->synopsis ? aa->synopsis : "Not available",
-						aa->description ? aa->description : "Not available");
+						aa->description ? aa->description : "Not available",
+						aa->seealso ? aa->seealso : "Not available");
 				}
 			}
 		}




More information about the asterisk-commits mailing list