[svn-commits] eliel: branch group/appdocsxml r148242 - in /team/group/appdocsxml: include/a...
SVN commits to the Digium repositories
svn-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 <name>' */
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 svn-commits
mailing list