Merge from trunk: 1835, 1836, 1842, 1843, 1854, 1858, 1860, 1861, and 1862.

* doc/Makefile: In Clean do not remove html. In new Distclean,
remove also html.

* doc/Makefile: When cleaning, remove contributed_modules.tex

* src/Makefile.in: Fix arguments to Install program

* doc/guide.tex: Provide only an example of language option
* doc/guide.html: Likewise

* doc/guide.tex: mod_muc can run in several nodes of cluster
* doc/guide.html: Likewise

* doc/api/process-one.css: Add some style to HTML elements

* src/ejabberd_listener.erl: Fix EDoc errors
* src/web/ejabberd_web_admin.erl: Likewise

* src/ejabberd_hooks.erl: Explanation in EDoc of some functions

* doc/guide.tex: Explain that account creation is only supported
by internal and odbc authentication methods
* doc/guide.html: Likewise

* src/Makefile.in: The path to the installed copy of ejabberd
Guide is set in the environment variable
EJABBERD_DOC_PATH (EJAB-837).
* src/web/ejabberd_web_admin.erl: Likewise
* src/ejabberdctl.template: Likewise
* doc/guide.tex: Likewise
* doc/guide.html: Likewise

SVN Revision: 1937

ChangeLog

@@ -1,7 +1,41 @@
+2009-03-03  Badlop  <badlop@process-one.net>
+
+	* doc/Makefile: In Clean do not remove html. In new Distclean,
+	remove also html.
+
+	* doc/Makefile: When cleaning, remove contributed_modules.tex
+
+	* src/Makefile.in: Fix arguments to Install program
+
+	* doc/guide.tex: Provide only an example of language option
+        * doc/guide.html: Likewise
+
+	* doc/guide.tex: mod_muc can run in several nodes of cluster
+        * doc/guide.html: Likewise
+
+	* doc/api/process-one.css: Add some style to HTML elements
+
+        * src/ejabberd_listener.erl: Fix EDoc errors
+        * src/web/ejabberd_web_admin.erl: Likewise
+
+	* src/ejabberd_hooks.erl: Explanation in EDoc of some functions
+
+	* doc/guide.tex: Explain that account creation is only supported
+        by internal and odbc authentication methods
+        * doc/guide.html: Likewise
+
+	* src/Makefile.in: The path to the installed copy of ejabberd
+	Guide is set in the environment variable
+	EJABBERD_DOC_PATH (EJAB-837).
+	* src/web/ejabberd_web_admin.erl: Likewise
+	* src/ejabberdctl.template: Likewise
+	* doc/guide.tex: Likewise
+	* doc/guide.html: Likewise
+
 2009-03-02  Pablo Polvorin <pablo.polvorin@process-one.net>
 
 	* src/ejabberd_auth_anonymous.erl: Correct include declaration (thanks 
-	to badlop). Bug was introduced in r1863.
+	to Badlop). Bug was introduced in r1863.
 
 	* src/ejabberd_s2s_in.erl, src/ejabberd_s2s_out.erl: Serialize stanzas
 	to iolist().

doc/Makefile

@@ -32,7 +32,6 @@ pdf:	guide.pdf features.pdf
 clean:
 	rm -f *.aux
 	rm -f *.haux
-	rm -f *.html
 	rm -f *.htoc
 	rm -f *.idx
 	rm -f *.ilg
@@ -41,6 +40,10 @@ clean:
 	rm -f *.out
 	rm -f *.pdf
 	rm -f *.toc
+	[ ! -f contributed_modules.tex ] || rm contributed_modules.tex
+
+distclean: clean
+	rm -f *.html
 
 guide.html:	guide.tex
 		hevea -fix -pedantic guide.tex

doc/api/process-one.css

@@ -71,10 +71,22 @@ pre, tt, code {
 }
 
 pre {
-  margin-left: 1em;
+  margin:1ex 2ex;
+  border:1px dashed lightgrey;
+  background-color:#f9f9f9;
+  padding:0.5ex;
 }
 
 pre em {
   font-style: normal;
   font-weight: bold;
 }
+
+dt {
+  margin:0ex 2ex;
+  font-weight:bold;
+}
+
+dd {
+  margin:0ex 0ex 1ex 4ex;
+}

doc/guide.html

@@ -476,7 +476,7 @@ variable.
 </P></LI><LI CLASS="li-enumerate">Install OpenSSL in <CODE>C:\sdk\OpenSSL</CODE> and add <CODE>C:\sdk\OpenSSL\lib\VC</CODE> to your path or copy the binaries to your system directory.
 </LI><LI CLASS="li-enumerate">Install ZLib in <CODE>C:\sdk\gnuWin32</CODE>. Copy
 <CODE>C:\sdk\GnuWin32\bin\zlib1.dll</CODE> to your system directory. If you change your path it should already be set after libiconv install.
-</LI><LI CLASS="li-enumerate">Make sure the you can access Erlang binaries from your path. For example: <CODE>set PATH=%PATH%;"C:\sdk\erl5.5.5\bin"</CODE>
+</LI><LI CLASS="li-enumerate">Make sure the you can access Erlang binaries from your path. For example: <CODE>set PATH=%PATH%;"C:\sdk\erl5.6.5\bin"</CODE>
 </LI><LI CLASS="li-enumerate">Depending on how you end up actually installing the library you might need to check and tweak the paths in the file configure.erl.
 </LI><LI CLASS="li-enumerate">While in the directory <CODE>ejabberd\src</CODE> run:
 <PRE CLASS="verbatim">configure.bat
@@ -914,8 +914,8 @@ connected to port 5237 with password &#X2018;<TT>ggsecret</TT>&#X2019;.
 {s2s_default_policy, deny}.
 {{s2s_host,"jabber.example.org"}, allow}.
 {{s2s_host,"example.com"}, allow}.
-</PRE><P>Note, that for jabberd 1.4- or WPJabber-based
+</PRE><P>Note, that for services based in jabberd14 or WPJabber
-services you have to make the transports log and do XDB by themselves:
+you have to make the transports log and do XDB by themselves:
 </P><PRE CLASS="verbatim">  &lt;!--
      You have to add elogger and rlogger entries here when using ejabberd.
      In this case the transport will do the logging.
@@ -937,7 +937,7 @@ services you have to make the transports log and do XDB by themselves:
   &lt;xdb id="xdb"&gt;
     &lt;host/&gt;
     &lt;load&gt;
-      &lt;!-- this is a lib of wpjabber or jabberd --&gt;
+      &lt;!-- this is a lib of wpjabber or jabberd14 --&gt;
       &lt;xdb_file&gt;/usr/lib/jabber/xdb_file.so&lt;/xdb_file&gt;
       &lt;/load&gt;
     &lt;xdb_file xmlns="jabber:config:xdb_file"&gt;
@@ -959,7 +959,7 @@ example authentication scripts</A>.
 <A HREF="#mssql">3.2.2</A> and <A HREF="#odbc">3.2.4</A>.
 </LI><LI CLASS="li-itemize">anonymous &#X2014; See section&#XA0;<A HREF="#saslanonymous">3.1.4</A>.
 </LI><LI CLASS="li-itemize">pam &#X2014; See section&#XA0;<A HREF="#pam">3.1.4</A>.
-</LI></UL><P> <A NAME="internalauth"></A> </P><!--TOC subsubsection Internal-->
+</LI></UL><P>Account creation is only supported by internal and odbc methods.</P><P> <A NAME="internalauth"></A> </P><!--TOC subsubsection Internal-->
 <H4 CLASS="subsubsection"><!--SEC ANCHOR --><A HREF="#internalauth">Internal</A></H4><!--SEC END --><P> <A NAME="internalauth"></A> 
 </P><P><TT>ejabberd</TT> uses its internal Mnesia database as the default authentication method.</P><UL CLASS="itemize"><LI CLASS="li-itemize">
 <TT>auth_method</TT>: The value <TT>internal</TT> will enable the internal
@@ -1193,13 +1193,9 @@ To define a shaper named &#X2018;<TT>normal</TT>&#X2019; with traffic speed limi
 can be seen by Jabber clients. If a Jabber client does not support
 <TT>xml:lang</TT>, the specified language is used. The default value is
 <TT>en</TT>. In order to take effect there must be a translation file
-<TT>&lt;language&gt;.msg</TT> in <TT>ejabberd</TT>&#X2019;s <TT>msgs</TT> directory.</P><P>Examples:
+<TT>&lt;language&gt;.msg</TT> in <TT>ejabberd</TT>&#X2019;s <TT>msgs</TT> directory.</P><P>For example, to set Russian as default language:
-</P><UL CLASS="itemize"><LI CLASS="li-itemize">
+</P><PRE CLASS="verbatim">{language, "ru"}.
-To set Russian as default language:
+</PRE><P>Appendix <A HREF="#i18ni10n">A</A> provides more details about internationalization and localization.</P><P> <A NAME="includeconfigfile"></A> </P><!--TOC subsection Include Additional Configuration Files-->
-<PRE CLASS="verbatim">{language, "ru"}.
-</PRE></LI><LI CLASS="li-itemize">To set Spanish as default language:
-<PRE CLASS="verbatim">{language, "es"}.
-</PRE></LI></UL><P>Appendix <A HREF="#i18ni10n">A</A> provides more details about internationalization and localization.</P><P> <A NAME="includeconfigfile"></A> </P><!--TOC subsection Include Additional Configuration Files-->
 <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc28">3.1.8</A>&#XA0;&#XA0;<A HREF="#includeconfigfile">Include Additional Configuration Files</A></H3><!--SEC END --><P> <A NAME="includeconfigfile"></A> 
 </P><P>The option <TT>include_config_file</TT> in a configuration file instructs <TT>ejabberd</TT> to include other configuration files immediately.</P><P>The basic usage is:
 </P><PRE CLASS="verbatim">{include_config_file, &lt;filename&gt;}.
@@ -3019,6 +3015,8 @@ all the environment variables and command line parameters.</P><P>The environment
 	Path to the ejabberd service log file.
 </DD><DT CLASS="dt-description"><B><TT>EJABBERD_SO_PATH</TT></B></DT><DD CLASS="dd-description">
 	Path to the directory with binary system libraries.
+</DD><DT CLASS="dt-description"><B><TT>EJABBERD_DOC_PATH</TT></B></DT><DD CLASS="dd-description">
+	Path to the directory with ejabberd documentation.
 </DD><DT CLASS="dt-description"><B><TT>HOME</TT></B></DT><DD CLASS="dd-description">
 	Path to the directory that is considered <TT>ejabberd</TT>&#X2019;s home.
 	This path is used to read the file <TT>.erlang.cookie</TT>.
@@ -3140,10 +3138,8 @@ be installed in the system.
 The file is searched by default in
 <TT>"/share/doc/ejabberd/guide.html"</TT>.
 The directory of the documentation can be specified in
-<TT>ejabberd.cfg</TT> with the option <TT>doc_path</TT>.
+the environment variable <TT>EJABBERD_DOC_PATH</TT>.
-For example:
+See section <A HREF="#erlangconfiguration">4.1.2</A>.</P><P> <A NAME="adhoccommands"></A> </P><!--TOC section Ad-hoc Commands-->
-</P><PRE CLASS="verbatim">{doc_path, "/usr/local/share/doc/ejabberd/"}.
-</PRE><P> <A NAME="adhoccommands"></A> </P><!--TOC section Ad-hoc Commands-->
 <H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc65">4.3</A>&#XA0;&#XA0;<A HREF="#adhoccommands">Ad-hoc Commands</A></H2><!--SEC END --><P> <A NAME="adhoccommands"></A> </P><P>If you enable <TT>mod_configure</TT> and <TT>mod_adhoc</TT>,
 you can perform several administrative tasks in <TT>ejabberd</TT>
 with a Jabber client.
@@ -3315,11 +3311,11 @@ Writing, on the other hand, will be slower. And of course if machine with one
 of the replicas is down, other replicas will be used.</P><P>Also <A HREF="http://www.erlang.org/doc/apps/mnesia/Mnesia_chap5.html#5.3">section 5.3 (Table Fragmentation) of Mnesia User&#X2019;s Guide</A> can be helpful.
 </P><P>(alt) Same as in previous item, but for other tables.</P></LI><LI CLASS="li-enumerate">Run &#X2018;<CODE>init:stop().</CODE>&#X2019; or just &#X2018;<CODE>q().</CODE>&#X2019; to exit from
 the Erlang shell. This probably can take some time if Mnesia has not yet
-transfered and processed all data it needed from <TT>first</TT>.</LI><LI CLASS="li-enumerate">Now run <TT>ejabberd</TT> on <TT>second</TT> with almost the same config as
+transfered and processed all data it needed from <TT>first</TT>.</LI><LI CLASS="li-enumerate">Now run <TT>ejabberd</TT> on <TT>second</TT> with a configuration similar as
-on <TT>first</TT> (you probably do not need to duplicate &#X2018;<CODE>acl</CODE>&#X2019;
+on <TT>first</TT>: you probably do not need to duplicate &#X2018;<CODE>acl</CODE>&#X2019;
-and &#X2018;<CODE>access</CODE>&#X2019; options &#X2014; they will be taken from
+and &#X2018;<CODE>access</CODE>&#X2019; options because they will be taken from
-<TT>first</TT>, and <CODE>mod_muc</CODE> and <CODE>mod_irc</CODE> should be
+<TT>first</TT>; and <CODE>mod_irc</CODE> should be
-enabled only on one machine in the cluster).
+enabled only on one machine in the cluster.
 </LI></OL><P>You can repeat these steps for other machines supposed to serve this
 domain.</P><P> <A NAME="servicelb"></A> </P><!--TOC section Service Load-Balancing-->
 <H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc80">6.3</A>&#XA0;&#XA0;<A HREF="#servicelb">Service Load-Balancing</A></H2><!--SEC END --><P> <A NAME="servicelb"></A> 

doc/guide.tex

@@ -1118,6 +1118,8 @@ The following authentication methods are supported by \ejabberd{}:
 \item pam --- See section~\ref{pam}.
 \end{itemize}
 
+Account creation is only supported by internal and odbc methods.
+
 \makesubsubsection{internalauth}{Internal}
 \ind{internal authentication}\ind{Mnesia}
 
@@ -1481,17 +1483,10 @@ can be seen by \Jabber{} clients. If a \Jabber{} client does not support
 \term{en}. In order to take effect there must be a translation file
 \term{<language>.msg} in \ejabberd{}'s \term{msgs} directory.
 
-Examples:
+For example, to set Russian as default language:
-\begin{itemize}
-\item To set Russian as default language:
 \begin{verbatim}
 {language, "ru"}.
 \end{verbatim}
-\item To set Spanish as default language:
-\begin{verbatim}
-{language, "es"}.
-\end{verbatim}
-\end{itemize}
 
 Appendix \ref{i18ni10n} provides more details about internationalization and localization.
 
@@ -3891,6 +3886,8 @@ The environment variables:
 	Path to the ejabberd service log file.
   \titem{EJABBERD\_SO\_PATH}
 	Path to the directory with binary system libraries.
+  \titem{EJABBERD\_DOC\_PATH}
+	Path to the directory with ejabberd documentation.
   \titem{HOME}
 	Path to the directory that is considered \ejabberd{}'s home.
 	This path is used to read the file \term{.erlang.cookie}.
@@ -4027,11 +4024,9 @@ be installed in the system.
 The file is searched by default in
 \term{"/share/doc/ejabberd/guide.html"}.
 The directory of the documentation can be specified in
-\term{ejabberd.cfg} with the option \term{doc\_path}.
+the environment variable \term{EJABBERD\_DOC\_PATH}.
-For example:
+See section \ref{erlangconfiguration}.
-\begin{verbatim}
+
-{doc_path, "/usr/local/share/doc/ejabberd/"}.
-\end{verbatim}
 
 \makesection{adhoccommands}{Ad-hoc Commands}
 
@@ -4320,11 +4315,11 @@ mnesia:change_table_copy_type(schema, node(), disc_copies).
   transfered and processed all data it needed from \term{first}.
 
 
-\item Now run \ejabberd{} on \term{second} with almost the same config as
+\item Now run \ejabberd{} on \term{second} with a configuration similar as
-  on \term{first} (you probably do not need to duplicate `\verb|acl|'
+  on \term{first}: you probably do not need to duplicate `\verb|acl|'
-  and `\verb|access|' options --- they will be taken from
+  and `\verb|access|' options because they will be taken from
-  \term{first}, and \verb|mod_muc| and \verb|mod_irc| should be
+  \term{first}; and \verb|mod_irc| should be
-  enabled only on one machine in the cluster).
+  enabled only on one machine in the cluster.
 \end{enumerate}
 
 You can repeat these steps for other machines supposed to serve this

src/Makefile.in

@@ -172,6 +172,7 @@ install: all
 		-e "s*@LIBDIR@*@libdir@*" \
 		-e "s*@SYSCONFDIR@*@sysconfdir@*" \
 		-e "s*@LOCALSTATEDIR@*@localstatedir@*" \
+		-e "s*@DOCDIR@*@docdir@*" \
 		-e "s*@erl@*@ERL@*" ejabberdctl.template \
 		> ejabberdctl.example
 	[ -f $(ETCDIR)/ejabberdctl.cfg ] \
@@ -180,7 +181,7 @@ install: all
 	install -b -m 644 $(G_USER) inetrc $(ETCDIR)/inetrc
 	#
 	# Administration script
-	[ -d $(SBINDIR) ] || install -d 750 $(SBINDIR)
+	[ -d $(SBINDIR) ] || install -d -m 750 $(SBINDIR)
 	install -m 550 $(G_USER) ejabberdctl.example $(SBINDIR)/ejabberdctl
 	#
 	# Binary Erlang files

src/ejabberd_hooks.erl

@@ -58,6 +58,9 @@
 start_link() ->
     gen_server:start_link({local, ejabberd_hooks}, ejabberd_hooks, [], []).
 
+%% @spec (Hook::atom(), Module::atom(), Function::atom(), Seq::integer()) -> ok
+%% @doc Add a module and function to this hook.
+%% The integer sequence is used to sort the calls: low number is called before high number.
 add(Hook, Module, Function, Seq) ->
     add(Hook, global, Module, Function, Seq).
 
@@ -65,6 +68,9 @@ add(Hook, Host, Module, Function, Seq)
      when is_binary(Host) orelse is_atom(Host) ->
     gen_server:call(ejabberd_hooks, {add, Hook, Host, Module, Function, Seq}).
 
+%% @spec (Hook::atom(), Module::atom(), Function::atom(), Seq::integer()) -> ok
+%% @doc Delete a module and function from this hook.
+%% It is important to indicate exactly the same information than when the call was added.
 delete(Hook, Module, Function, Seq) ->
     delete(Hook, global, Module, Function, Seq).
 
@@ -72,6 +78,9 @@ delete(Hook, Host, Module, Function, Seq)
      when is_binary(Host) orelse is_atom(Host) ->
     gen_server:call(ejabberd_hooks, {delete, Hook, Host, Module, Function, Seq}).
 
+%% @spec (Hook::atom(), Args) -> ok
+%% @doc Run the calls of this hook in order, don't care about function results.
+%% If a call returns stop, no more calls are performed.
 run(Hook, Args) ->
     run(Hook, global, Args).
 
@@ -83,6 +92,12 @@ run(Hook, Host, Args) when is_binary(Host) orelse is_atom(Host) ->
 	    ok
     end.
 
+%% @spec (Hook::atom(), Val, Args) -> Val | stopped | NewVal
+%% @doc Run the calls of this hook in order.
+%% The arguments passed to the function are: [Val | Args].
+%% The result of a call is used as Val for the next call.
+%% If a call returns 'stop', no more calls are performed and 'stopped' is returned.
+%% If a call returns {stopped, NewVal}, no more calls are performed and NewVal is returned.
 run_fold(Hook, Val, Args) ->
     run_fold(Hook, global, Val, Args).
 
@@ -214,6 +229,3 @@ run_fold1([{_Seq, Module, Function} | Ls], Hook, Val, Args) ->
 	NewVal ->
 	    run_fold1(Ls, Hook, NewVal, Args)
     end.
-
-
-

src/ejabberdctl.template

@@ -48,6 +48,9 @@ fi
 if [ "$SPOOLDIR" = "" ] ; then
     SPOOLDIR=@LOCALSTATEDIR@/lib/ejabberd
 fi
+if [ "$EJABBERD_DOC_PATH" = "" ] ; then
+    EJABBERD_DOC_PATH=@DOCDIR@
+fi
 
 # check the proper system user is used
 ID=`id -g`
@@ -99,6 +102,7 @@ export EJABBERD_MSGS_PATH
 export EJABBERD_LOG_PATH
 export EJABBERD_SO_PATH
 export EJABBERD_BIN_PATH
+export EJABBERD_DOC_PATH
 export ERL_CRASH_DUMP
 export ERL_INETRC
 export ERL_MAX_PORTS

src/web/ejabberd_web_admin.erl

@@ -41,9 +41,9 @@
 
 
 process(["doc", LocalFile], _Request) ->
-    DocPath = case ejabberd_config:get_global_option(doc_path) of
+    DocPath = case os:getenv("EJABBERD_DOC_PATH") of
 		  P when is_list(P) -> P;
-		  _ -> "/share/doc/ejabberd/"
+		  false -> "/share/doc/ejabberd/"
 	      end,
     %% Code based in mod_http_fileserver
     FileName = filename:join(DocPath, LocalFile),
@@ -55,8 +55,8 @@ process(["doc", LocalFile], _Request) ->
              FileContents};
         {error, Error} ->
             ?DEBUG("Delivering error: ~p", [Error]),
-	    Help = " " ++ FileName ++ " - Try to specify the path to ejabberd guide.html "
+	    Help = " " ++ FileName ++ " - Try to specify the path to ejabberd documentation "
-		"with the option doc_path. Check the ejabberd Guide for more information",
+		"with the environment variable EJABBERD_DOC_PATH. Check the ejabberd Guide for more information.",
             case Error of
                 eacces -> {403, [], "Forbidden"++Help};
                 enoent -> {404, [], "Not found"++Help};