4 Mar
2010
4 Mar
'10
7:35 p.m.
Module: sip-router
Branch: andrei/cdefs2doc
Commit: cee03233fd22955617dc6dfc0676a19c68b86b67
URL:
http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=cee0323…
Author: Andrei Pelinescu-Onciul <andrei(a)iptel.org>
Committer: Andrei Pelinescu-Onciul <andrei(a)iptel.org>
Date: Thu Mar 4 19:27:33 2010 +0100
doc: select_list: added intro & notations sections
---
doc/select_list/Makefile | 1 +
doc/select_list/docbook/intro.xml | 61 +++++++++++++++++++++++++++++++++++++
2 files changed, 62 insertions(+), 0 deletions(-)
diff --git a/doc/select_list/Makefile b/doc/select_list/Makefile
index 4962624..a41b226 100644
--- a/doc/select_list/Makefile
+++ b/doc/select_list/Makefile
@@ -184,6 +184,7 @@ $(docbook_output_dir)/select_list.xml: \
@echo " $(MAKE) -C doc/select_list $(MAKECMDGOALS)" >>$@
@echo ' </revremark>' >>$@
@echo ' </revision></revhistory></info>' >>$@
+ @echo ' <xi:include href="intro.xml"/>' >>$@
@$(foreach f,$(flist),\
echo ' <xi:include'\
'href="'$(call get_target,$f).xml'"/>' \
diff --git a/doc/select_list/docbook/intro.xml b/doc/select_list/docbook/intro.xml
new file mode 100644
index 0000000..da9e852
--- /dev/null
+++ b/doc/select_list/docbook/intro.xml
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="Select_Intro">
+ <title>Introduction and Notations</title>
+ <section id="Intro">
+ <title>Introduction</title>
+ <para>Selects are read-only functions that can be used in the script and
+ that always return a string value. In the script a select always starts
+ with a '<emphasis>@</emphasis>'. In an expression context
a
+ select always evaluates to either a string or undef.
+ </para>
+ <para>For more informations see
+ <ulink url=' http://sip-router.org/wiki/cookbooks/selects/devel'>
+ http://sip-router.org/wiki/cookbooks/selects/devel</ulink>nk>.
+ </para>
+ <para>This document lists all the selects implemented by each module.
+ </para>
+ </section>
+ <section id="Notations">
+ <title>Notations</title>
+ <para>The following notations are used:
+ <orderedlist>
+ <listitem>@ - all selects always start with '@'. </listitem>
+ <listitem>"string" - string type.</listitem>
+ <listitem>integer - integer type.</listitem>
+ <listitem>[] - Parameter markers. Can be either [integer] or
+ ["string"].
+ Note that instead of ["string"] one could write .string,
+ e.g.:
+ @foo.bar["string"] is equivalent to @foo.bar.string.
+ </listitem>
+ <listitem>{} - denotes an optional parameter.
+ E.g.: @ruri.params{["string"]} means you could use
+ @ruri.params by itself or you could specify an extra parameter:
+ @ruri.params["trasnport"] or @ruri.params.transport.
+ </listitem>
+ <listitem><string> - means the next member is not fixed and can
+ take any string value (it is a string parameter).
+ It is equivalent with ["string"], e.g.:
+ @msg.header.<string> is the same as
+ @msg.header["string"].
+ It is used only to expose an internal implementation detail
+ (SEL_PARAM_* vs. CONSUME_NEXT_*), but from the script writer point
+ of view it is the same thing.
+ </listitem>
+ <listitem>.* - means the select can be followed by a variable number of
+ string parameters.
+ E.g.: @cfg_get.* means that @cfg_get.core.version is a valid usage.
+ </listitem>
+ <listitem>* (without a '.' in front) - it means the last member
+ might be a class that might expand further (but the
+ "expansion" is not defined in the same module).
+ E.g. @foo.nameaddr* means that nameaddr is most likely
+ a class that expands further
+ (for example into @foo.nameaddr.uri a.s.o).
+ </listitem>
+ </orderedlist>
+ </para>
+ </section>
+</chapter>