The R13B03 release.OTP_R13B03

1 files changed, 156 insertions, 0 deletions

diff --git a/lib/webtool/doc/src/webtool.xml b/lib/webtool/doc/src/webtool.xml
new file mode 100644
index 0000000000..55bac8bd34
--- /dev/null
+++ b/lib/webtool/doc/src/webtool.xml
@@ -0,0 +1,156 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2001</year>
+      <year>2007</year>
+      <holder>Ericsson AB, All Rights Reserved</holder>
+    </copyright>
+    <legalnotice>
+  The contents of this file are subject to the Erlang Public License,
+  Version 1.1, (the "License"); you may not use this file except in
+  compliance with the License. You should have received a copy of the
+  Erlang Public License along with this software. If not, it can be
+  retrieved online at http://www.erlang.org/.
+
+  Software distributed under the License is distributed on an "AS IS"
+  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+  the License for the specific language governing rights and limitations
+  under the License.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+
+    <title>webtool</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+  </header>
+  <module>webtool</module>
+  <modulesummary>WebTool is a tool used to simplify the implementation of web based tools with Erlang/OTP.</modulesummary>
+  <description>
+    <p>WebTool makes it easy to use web based tools with Erlang/OTP. WebTool
+      configures and starts the webserver httpd.</p>
+  </description>
+  <funcs>
+    <func>
+      <name>start()-> {ok,Pid}| {stop,Reason}</name>
+      <fsummary>Start WebTool.</fsummary>
+      <desc>
+        <p>Start WebTool with default data, i.e. port 8888, ip-number
+          127.0.0.1, and server-name <c>localhost</c>. If port 8888 is
+          in use, port 8889 is tried instead. If 8889 is also in use,
+          8890 is tried and so on. Max number of ports tried is 256.
+          </p>
+        <p>The <c>mime.types</c> file and WebTool's own HTML files
+          are assumed to be in the directory
+          <c><![CDATA[webtool-<vsn>/priv/root/conf]]></c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>start(Path,Data)->{ok,Pid}|{stop,Reason}</name>
+      <fsummary>Start WebTool with default configuration.</fsummary>
+      <type>
+        <v>Path = string() | standard_path</v>
+        <v>Data = [Port,Address,Name] | PortNumber | standard_data</v>
+        <v>Port = {port,PortNumber}</v>
+        <v>Address = {bind_address,IpNumber}</v>
+        <v>Name = {server_name,ServerName}</v>
+        <v>PortNumber = integer()</v>
+        <v>IpNumber = tuple(), e.g. {127,0,0,1}</v>
+        <v>ServerName = string()</v>
+        <v>Pid = pid()</v>
+      </type>
+      <desc>
+        <p>Use this function to start WebTool if the default port, 
+          ip-number,servername or path can not be used.</p>
+        <p><c>Path</c> is the directory where the <c>mime.types</c>
+          file and WebTool's own HTML files are located. By default
+          this is <c><![CDATA[webtool-<vsn>/priv]]></c>, and in most cases there
+          is no need to change this. If <c>Path</c> is set to
+          <c>standard_path</c> the default will be used.</p>
+        <p>If <c>Data</c> is set to <c>PortNumber</c>, the default data
+          will be used for ip-number (<c>127.0.0.1</c>) and server
+          name (<c>localhost</c>).</p>
+      </desc>
+    </func>
+    <func>
+      <name>stop()->void</name>
+      <fsummary>Stop WebTool.</fsummary>
+      <desc>
+        <p>Stop WebTool and the tools started by WebTool.</p>
+      </desc>
+    </func>
+    <func>
+      <name>debug_app(Module)->void</name>
+      <fsummary>Debug a WebTool application.</fsummary>
+      <type>
+        <v>Module = atom()</v>
+      </type>
+      <desc>
+        <p>Debug a WebTool application by tracing all functions in the
+          given module which are called from WebTool.</p>
+      </desc>
+    </func>
+    <func>
+      <name>stop_debug()->void</name>
+      <fsummary>Stop debugging an application and format the trace log.</fsummary>
+      <desc>
+        <p>Stop the tracing started by <c>debug_app/1</c>, and format
+          the trace log.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>CALLBACK FUNCTIONS</title>
+    <p>The following callback function must be implemented by each web
+      based tool that will be used via WebTool. When started, WebTool
+      searches the Erlang code path for *.tool files to locate all web
+      based tools and their callback functions. See the <seealso marker="webtool_chapter">WebTool User's Guide</seealso> for more
+      information about the *.tool files.</p>
+  </section>
+  <funcs>
+    <func>
+      <name>Module:Func(Data)-> {Name,WebData}|error</name>
+      <fsummary>Returns configuration data needed by WebTool to configure and start a tool.</fsummary>
+      <type>
+        <v>Data = term()</v>
+        <v>Name = atom()</v>
+        <v>WebData = [WebOptions]</v>
+        <v>WebOptions = LinkData | Alias | Start</v>
+        <v>LinkData = {web_data,{ToolName,Url}}</v>
+        <v>Alias = {alias,{VirtualPath,RealPath}} |  {alias,{erl_alias,Path,[Modules]}</v>
+        <v>Start = {start,StartData}</v>
+        <v>ToolName = Url = VirtualPath = RealPath = Path = string()</v>
+        <v>Modules = atom()</v>
+        <v>StartData = AppData | ChildSpec | Func</v>
+        <v>AppData = {app,AppName}</v>
+        <v>ChildSpec = {child,child_spec()}</v>
+        <d>See the Reference Manual for the module supervisor in the STDLIB application for details about child_spec().</d>
+        <v>Func = {func,{StartMod,StartFunc,StartArg}, {StopMod,StopFunc,StopArg}}</v>
+        <v>AppName = StartMod = StartFunc = StopMod = StopFunc =atom()</v>
+        <v>StartArg = StopArg =  [term()]</v>
+      </type>
+      <desc>
+        <p>This is the configuration function (<c>config_func</c>)
+          which must be stated in the <c>*.tool</c> file.</p>
+        <p>The function is called by WebTool at startup to retrieve the
+          data needed to start and configure the tool. <c>LinkData</c> is
+          used by WebTool to create the link to the tool. <c>Alias</c> is
+          used to create the aliases needed by the webserver. <c>Start</c>
+          is used to start and stop the tool.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>See Also</title>
+    <p><seealso marker="start_webtool">start_webtool(1)</seealso>, 
+      <seealso marker="webtool_chapter">WebTool User's Guide</seealso></p>
+  </section>
+</erlref>
+