* added external documentation in tex format

* true=>public and false=>private for permissions

diff --git a/helm/uwobo/doc/uwobo.tex b/helm/uwobo/doc/uwobo.tex
new file mode 100644 (file)
index 0000000..177d21d
--- /dev/null
+++ b/helm/uwobo/doc/uwobo.tex
@@ -0,0 +1,216 @@
+\documentclass{article}
+
+\usepackage{hyperref}
+
+\title{UWOBO Reference Manual\thanks{People who contributed to former
+versions are Ferruccio Guidi, Riccardo Solmi, Stephen Watt.}}
+\author{Luca Padovani \and Claudio Sacerdoti Coen \and Stefano
+Zacchiroli}
+
+\begin{document}
+
+\maketitle
+
+\noindent UWOBO is a Web Service implementing a XSLT engine. It allows
+XSLT stylesheets to be applied to XML documents. Once the UWOBO deamon
+is up and running, commands must be sent at the URL
+
+\begin{verbatim}
+http://hostname:uwoboport/command
+\end{verbatim}
+
+\section*{Stylesheet Management}
+
+Before stylesheets can be applied to XML documents, they must be
+loaded into UWOBO. This way stylesheets are compiled once and used as
+many times as needed. Once loaded, each stylesheet is identified by a
+unique identifier.
+
+\begin{verbatim}
+add?bind=key,uri[&bind=key,uri[&...]]
+\end{verbatim}
+
+The \texttt{add} command is used to load a new stylesheet, specified
+by a URI, and bind it to a corresponding key. Multiple stylesheets can
+be loaded at once.
+
+\begin{verbatim}
+remove?keys=[key1,key2,...]
+\end{verbatim}
+
+The \texttt{remove} command unloads one or more stylesheets specified
+by provided keys. It removes \emph{all} the loaded stylesheets if no
+key is given.
+
+\begin{verbatim}
+reload?keys=[key1,key2,...]
+\end{verbatim}
+
+The \texttt{reload} command reloads previously loaded stylesheets
+specified by the provided keys.  It reloads all the loaded stylesheets
+if no key is given. This command is particularly useful during
+stylesheet development (assuming the URI of the loaded stylesheets
+does not change), since it does not require the client to specify the
+URL of the stylesheets again.
+
+\begin{verbatim}
+list
+\end{verbatim}
+
+The \texttt{list} command returns the list of the loaded stylesheets
+along with their associated key.
+
+\section*{Profile Management}
+
+XSLT stylesheets may have \emph{parameters} that are typically
+supplied at application time. Although UWOBO supports this kind of
+interaction, it may be impractical from several different points of
+view.  Since parameters are communicated to UWOBO in the URL, the URL
+itself may become very large: the URL readibility decreases because of
+its lengths and also because of the quoting of the parameter values;
+moreover, there is an upper limit to the length of a URL which can be
+easily reached.
+
+Furthermore, it is often the case that among the supplied parameters,
+a large number of these stays the same between applications. 
+
+UWOBO provides a facility to store imperatively the value of
+parameters as its internal state. However, since parameters are
+typically used for storing user-dependent settings and preferences,
+UWOBO provides a notion of \emph{profile}. Profiles can be created as
+part of UWOBO's internal state. Profiles are identified by a key (a
+sequence of alphanumeric characters) and map parameter names to
+parameter values. At application time, UWOBO may be instructed to take
+the values of the parameters to be passed to the stylesheets from a
+particular profile.
+
+\begin{verbatim}
+listprofiles
+\end{verbatim}
+The \texttt{listprofiles} command returns the list of profiles
+currently loaded in UWOBO.
+
+\begin{verbatim}
+createprofile?[id=id][&orig=orig][&origpassword=origpassword]
+  [&readperm={public|private}][&writeperm={public|private}]
+  [&adminperm={public|private}][&password=password]
+\end{verbatim}
+The \texttt{createprofile} command creates a new profile. The
+identifier of the new profile can be provided, otherwise UWOBO will
+pick a randomly chosen fresh identifier. An \emph{original profile}
+can optionally be cloned (a password for the original profile must be
+provided if the original profile has private read
+permission). Permissions for read, write, and administrative access
+can be set to public or to private, the default being public. The
+newly created profile may optionally have a password set (the default
+is no password set).
+
+\begin{verbatim}
+removeprofile?id=id[&password=password]
+\end{verbatim}
+The \texttt{removeprofile} commands erases and removes the profile
+from UWOBO. The password is required if the profile has private
+administrative permission.
+
+\begin{verbatim}
+setparam?id=id[&password=password]&key=key[&value=value]
+\end{verbatim}
+The \texttt{setparam} command sets the parameter \texttt{key} to
+\texttt{value}, if the value is provided; otherwise the parameter is
+unset. The password is required if the profile has private write
+permission.
+
+\begin{verbatim}
+setpassword?id=id[&oldpassword=oldpassword][&password=password]
+\end{verbatim}
+The \texttt{setpassword} command changes or unset the password
+associated with the profile \texttt{id}. The old password must be
+provided if it was set.
+
+\begin{verbatim}
+setpermission?id=id[&password=password]
+  &permission={read|write|admin}&value={public|private}
+\end{verbatim}
+The \texttt{setpermission} commands changes the specified
+permission. Permissions can be set to private (password protected) or
+public.  The password is required if the profile has private
+administrative permission.
+
+\begin{verbatim}
+getparams?id=id[&password=password]
+\end{verbatim}
+The \texttt{getparams} command returns a list of all the parameters
+set in the specified profile. The password is required if the profile
+has private read permission.
+
+\begin{verbatim}
+getparam?id=id[&password=password]&key=key
+\end{verbatim}
+The \texttt{getparam} commands returns the value of the specified
+parameter in the profile \texttt{id}. The password is required if the
+profile has private read permission.
+
+\begin{verbatim}
+getpermission?id=id[&password=password]&for={read|write|admin}
+\end{verbatim}
+The \texttt{getpermission} command returns the value of the permission
+\texttt{key} in the profile \texttt{id}. The password is required if
+the profile has private administrative permission.
+
+\section*{Stylesheet Application}
+
+\begin{verbatim}
+apply?xmluri=uri&keys=key1,key2,...
+  [&errormode={ignore|comment|embed}]
+  [&debugmode={ignore|comment|embed}]
+  [&profile=id][&password=password]
+  [&param.name=value[&param.name=value[&...]]]
+  [&param.key.name=value[&param.key.name=value[&...]]]
+  [&prop.name[=value][&prop.name[=value][&...]]]
+\end{verbatim}
+The \texttt{apply} command applies a chain of stylesheets, specified
+by the keys \texttt{key1}, \texttt{key2}, \dots, to an input document,
+specified by \texttt{uri}.  Error and debugging modes can be set to
+three different values: \texttt{ignore} means that LibXSLT messages
+are ignored; \texttt{comment} means that LibXSLT messages are embedded
+in the result document inside an XML like comment; \texttt{embed}
+means that LibXSLT messages are embedded at the beginning of the
+result document (as childs of the root node) in XML elements in the
+UWOBO namespace.
+
+Parameters can be set for each stylesheet application: global
+parameters (i.e. parameters passed to all stylesheets) are set using
+\texttt{param.name=value} syntax, per-stylesheet parameters are set
+using \texttt{param.key.name=value} where \texttt{key} is the key of a
+loaded stylesheet.  It is possible to specify a profile that is
+searched for additional global and local parameters. The parameters
+stored in the profile have lower precedence with respect to those
+provided in the URL. A password must be provided if the profile has
+private read permission.
+
+Properties of the final chain output can be set as well: valueless
+properties can be set using \texttt{prop.name} syntax, others can be
+set using \texttt{prop.name=value} syntax.  Supported properties are
+listed in the UWOBO help page.
+
+\section*{Miscellaneous Commands}
+
+\begin{verbatim}
+help
+\end{verbatim}
+The \texttt{help} command displays an help message.
+
+\begin{verbatim}
+newsession?port=p
+\end{verbatim}
+The \texttt{newsession} command forks a new daemon on a specified
+port. The newly created deamon inherits the state of the original
+UWOBO it was forked off.
+
+\begin{verbatim}
+kill
+\end{verbatim}
+The \texttt{kill} command kills the daemon. The log file is \emph{not}
+deleted.
+
+\end{document}
\ No newline at end of file

diff --git a/helm/uwobo/uwobo.ml b/helm/uwobo/uwobo.ml
index 73cc23b6547471511eb4a3a90e8067f93d0f2a26..f5a778882123f901c886f0c2f8fc3a01133558e1 100644 (file)
--- a/helm/uwobo/uwobo.ml
+++ b/helm/uwobo/uwobo.ml
@@ -704,7 +704,7 @@ let main () =
                  | "write" -> `Write
                  | "admin" -> `Admin
                  | _ -> assert false
-             and bool_of_string s = "true" = s
+             and bool_of_string s = ("public" = s) || ("true" = s)
              in
              let pid, password, forwhat, value =
                match Pcre.split ~pat:"," (Pcre.replace ~rex:setpermission_cmd_RE line) with

diff --git a/helm/uwobo/uwobo_common.ml b/helm/uwobo/uwobo_common.ml
index 87a640b4306d156753c0df050ba71a511360acfc..4399709ed43f3f758ad1865224caa1db7d40847f 100644 (file)
--- a/helm/uwobo/uwobo_common.ml
+++ b/helm/uwobo/uwobo_common.ml
@@ -52,7 +52,7 @@ let version = "0.2.1" ;;
 
 let usage_string =
   sprintf
-"
+    "
 <html>
   <head>
     <title>UWOBO's help message</title>
@@ -70,7 +70,7 @@ let usage_string =
     </p>
     <p>
       <b><kbd>help</kbd></b><br />
-      display this help message
+      displays this help message
     </p>
     <p>
       <b><kbd>newsession?port=p</kbd></b><br />
@@ -82,7 +82,7 @@ let usage_string =
     </p>
     <p>
       <b><kbd>add?bind=key,uri[&bind=key,uri[&...]]</kbd></b><br />
-      load a new stylesheet, specified by <em>uri</em>, and bind it to key
+      loads a new stylesheet, specified by <em>uri</em>, and bind it to key
           <em>key</em>
     </p>
     <p>
@@ -92,16 +92,16 @@ let usage_string =
     </p>
     <p>
       <b><kbd>reload?keys=[key1,key2,...]</kbd></b><br />
-      reload stylesheets specified by <em>key1, key2, ...</em> or all
-          stylesheets if no key was given
+      reloads the stylesheets specified by <em>key1, key2, ...</em>. Reloads all
+          the stylesheets if no key was given
     </p>
     <p>
       <b><kbd>list</kbd></b><br />
-      return a list of loaded stylesheets
+      returns the list of loaded stylesheets
     </p>
     <p>
       <b><kbd>apply?xmluri=uri&keys=key1,key2,...[&errormode={ignore|comment|embed}][&debugmode={ignore|comment|embed}][&profile=id][&password=password][&param.name=value[&param.name=value[&...]]][&param.key.name=value[&param.key.name=value[&...]]][&prop.name[=value][&prop.name[=value][&...]]]</kbd></b><br />
-      apply a chain of stylesheets, specified by <em>key1, key2, ...</em>, to an
+      applies a chain of stylesheets, specified by <em>key1, key2, ...</em>, to an
       input document, specified by <em>uri</em>.<br />
       Error and debugging modes could be ste to three different values.
       <em>ignore</em> means that LibXSLT messages are ignored; <em>comment</em>
@@ -119,50 +119,50 @@ let usage_string =
       have lower precedence with respect to those provided in the URL. A
       <em>password</em> for the profile must be provided if the read permission
       of the profile is set to false.<br />
-      Properties of the final chain output can be set too: valueless properties
+      Properties of the final chain output can be set as well: valueless properties
       can be set using <em>prop.name</em> syntax, others can be set using
       <em>prop.name=value</em> syntax.<br />
       Current supported properties are: %s.
     </p>
     <p>
       <b><kbd>listprofiles</kbd></b><br />
-      return the list of profiles available
+      returns the list of profiles available
     </p>
     <p>
-      <b><kbd>createprofile?[id=id][&orig=orig][&origpassword=origpassword][&readperm={true|false}][&writeperm={true|false}][&adminperm={true|false}][&password=password]</kbd></b><br />
+      <b><kbd>createprofile?[id=id][&orig=orig][&origpassword=origpassword][&readperm={public|private}][&writeperm={public|private}][&adminperm={public|private}][&password=password]</kbd></b><br />
       creates a new profile. The id of the created profile is <em>id</em> (if provided); otherwise it is a fresh id.
       The parameters are inherited from the profile <em>orig</em>, if provided. <em>origpassword</em> is the password of the
-      profile being copied in case the read permission of that profile is set to false. The defaults for
-      <em>password</em> and <em>readper,writeperm,adminperm</em> are respectively true, true, true and no password.
+      profile being copied in case the read permission of that profile is set to false. The default for
+      <em>password</em> is no password, the defaults for <em>readper,writeperm,adminperm</em> are public, public, public.
     </p>
     <p>
       <b><kbd>removeprofile?id=id[&password=password]</kbd></b><br />
-      completely removes the profile <em>id</em>. The password is required if the profile administrative permission
+      removes the profile <em>id</em>. The password is required if the profile administrative permission
       is set to false.
     </p>
     <p>
       <b><kbd>setparam?id=id[&password=password]&key=key[&value=value]</kbd></b><br />
-      sets the property <em>key</em> to <em>value</em>, if <em>value</em> is provided; otherwise
+      sets the parameter <em>key</em> to <em>value</em>, if <em>value</em> is provided; otherwise
       the parameter is unset. The password is required if the profile writing permission is set to
       false.
     </p>
     <p>
       <b><kbd>setpassword?id=id[&oldpassword=oldpassword][&password=password]</kbd></b><br />
-      changes or unset the password. The old password is required if it was set.
+      changes or unset the password for a profile. The old password is required if it was set.
     </p>
     <p>
-      <b><kbd>setpermission?id=id[&password=password]&permission={read|write|admin}&value={true|false}</kbd></b><br />
+      <b><kbd>setpermission?id=id[&password=password]&permission={read|write|admin}&value={public|private}</kbd></b><br />
       changes the permission <em>permission</em>. The password is required if the administrative permission
       is set to false.
     </p>
     <p>
       <b><kbd>getparams?id=id[&password=password]</kbd></b><br />
-      returns all the params of the profile <em>id</em>. The password is required if the read permission
+      returns all the parameters of the profile <em>id</em>. The password is required if the read permission
       is set to false.
     </p>
     <p>
       <b><kbd>getparam?id=id[&password=password]&key=key</kbd></b><br />
-      returns the value of the param <em>key</em> of the profile <em>id</em>. The password is required if the read permission
+      returns the value of the parameter <em>key</em> of the profile <em>id</em>. The password is required if the read permission
       is set to false.
     </p>
     <p>
@@ -173,8 +173,8 @@ let usage_string =
   </body>
 </html>
 "
-  version version
-  (String.concat ", " supported_properties) (* supported properties *)
+    version version
+    (String.concat ", " supported_properties) (* supported properties *)
 ;;
 
 let pp_error =