X-Git-Url: http://matita.cs.unibo.it/gitweb/?a=blobdiff_plain;f=helm%2Fsoftware%2Fmatita%2Fhelp%2FC%2Fsec_install.xml;h=be9ddaa11364bae4257f0ed3b13ce55ef7c9cba7;hb=f6fbde555da84d68da2dc87de8d731f1c6ea4476;hp=09bc9d7405198bd0c0e046f3df75712436715594;hpb=3c34684e4003335b9a73eb9d75872938c43600af;p=helm.git

diff --git a/helm/software/matita/help/C/sec_install.xml b/helm/software/matita/help/C/sec_install.xml
index 09bc9d740..be9ddaa11 100644
--- a/helm/software/matita/help/C/sec_install.xml
+++ b/helm/software/matita/help/C/sec_install.xml
@@ -1,16 +1,16 @@
 
 <!-- ============= Installation ============================== -->
 
-<sect1 id="sec_install">
+<chapter id="sec_install">
   <title>Installation</title>
 
-  <sect2>
-    <title>Installing &appname; from sources</title>
+  <sect1 id="inst_from_src">
+    <title>Installing from sources</title>
 
     <para>Currently, the only intended way to install &appname; is starting
       from its source code.  </para>
 
-    <sect3>
+    <sect2 id="get_source_code">
       <title>Getting the source code</title>
 
       <para>You can get the &appname; source code in two ways:
@@ -38,9 +38,9 @@
 	</orderedlist>
       </para>
       
-    </sect3>
+    </sect2>
 
-    <sect3 id="build_requirements">
+    <sect2 id="build_requirements">
       <title>Requirements</title>
 
       <para>In order to build &appname; from sources you will need some
@@ -54,8 +54,8 @@
 	    you can have APT install all the required tools and libraries by
 	    adding the following repository to your
 	    <filename>/etc/apt/sources.list</filename>: <programlisting>
-	      deb&nbsp;<ulink type="http"
-		url="http://people.debian.org/~zack">http://people.debian.org/~zack</ulink>&nbsp;unstable&nbsp;helm
+	      deb <ulink type="http"
+		url="http://people.debian.org/~zack">http://people.debian.org/~zack</ulink> unstable helm
 	  </programlisting> and installing the
 	  <application>helm-matita-deps</application> package.</para>
 
@@ -171,10 +171,7 @@
 	  </varlistentry>
 
 	  <varlistentry>
-	    <term>
-	      <application> <ulink type="http"
-		  url="http://www.mysql.com">MySQL</ulink> </application>
-	    </term>
+	    <term> &MYSQL; </term>
 	    <term>
 	      <application> <ulink type="http"
 		  url="http://raevnos.pennmush.org/code/ocaml-mysql/">OCaml
@@ -205,7 +202,7 @@
 	  <varlistentry>
 	    <term>
 	      <application> <ulink type="http"
-		  url="http://www.cduce.org/download.html#side">ulex</ulink>
+		  url="http://www.cduce.org/download.html">ulex</ulink>
 	      </application>
 	    </term>
 	    <listitem>
@@ -216,7 +213,7 @@
 	  <varlistentry>
 	    <term>
 	      <application> <ulink type="http"
-		  url="http://cristal.inria.fr/~xleroy/software.html#camlzip">CamlZip</ulink>
+		  url="http://cristal.inria.fr/~xleroy/software.html">CamlZip</ulink>
 	      </application>
 	    </term>
 	    <listitem>
@@ -227,33 +224,104 @@
 
 	</variablelist> </para>
 
-    </sect3>
+    </sect2>
+
+    <sect2 id="database_setup">
+      <title>Database setup</title>
+
+      <para> To fully exploit &appname; indexing and search capabilities you
+	will need a working &MYSQL; database. Detalied instructions on how to do
+	it can be found in the <ulink type="http"
+	  url="http://dev.mysql.com/doc/">MySQL documentation</ulink>. Here you
+	can find a quick howto. </para>
+
+      <para> In order to create a database you need administrator permissions on
+	your MySQL installation, usually the root account has them. Once you
+	have the permissions, a new database can be created executing
+	<userinput>mysqladmin create matita</userinput>
+	(<emphasis>matita</emphasis> is the default database name, you can
+	change it using the <parameter>db.user</parameter> key of the
+	configuration file). </para>
+
+      <para> Then you need to grant the necessary access permissions to the
+	database user of &appname;, typing <userinput>echo "grant all privileges
+	  on matita.* to helm;" | mysql matita</userinput> should do the trick
+	(<emphasis>helm</emphasis> is the default user name used by &appname; to
+	access the database, you can change it using the
+	<parameter>db.user</parameter> key of the configuration file).
+      </para>
+
+      <note>
+	<para> This way you create a database named <emphasis>matita</emphasis>
+	  on which anyone claiming to be the <emphasis>helm</emphasis> user can
+	  do everything (like adding dummy data or destroying the contained
+	  one). It is strongly suggested to apply more fine grained permissions,
+	  how to do it is out of the scope of this manual.</para>
+      </note>
+      
+    </sect2>
 
-    <sect3 id="build_instructions">
-      <title>Instructions</title>
+    <sect2 id="build_instructions">
+      <title>Compiling and installing</title>
 
       <para> Once you get the source code the installations steps should be
 	quite familiar.</para>
 
       <para> First of all you need to configure the build process executing
 	<userinput>./configure</userinput>. This will check that all needed
-	tools and library are installed. You may need to pass on the command
-	line some of the parameters riported below:
-
-	<variablelist>
-	  <title><application>configure</application> parameters</title>
-
-	  <varlistentry>
-	    <term>&TODO;</term>
-	    <listitem>&TODO;</listitem>
-	  </varlistentry>
-
-	</variablelist>
+	tools and library are installed and prepare the sources for compilation
+	and installation. </para>
+	
+      <para> Quite a few (optional) arguments may be passed to the
+	<application>configure</application> command line to change build time
+	parameters. They are listed in the table below, together with their
+	default values.
+
+	<table frame="all">
+	  <title> <application>configure</application> command line
+	    arguments</title>
+	  <tgroup cols="3" align="left" colsep="1" rowsep="1">
+	    <thead>
+	      <row>
+		<entry align="center">Argument</entry>
+		<entry align="center">Default</entry>
+		<entry align="center">Description</entry>
+	      </row>
+	    </thead>
+	    <tbody>
+	      <row>
+		<entry>
+		  <userinput>--with-runtime-dir=<replaceable>dir</replaceable></userinput>
+		</entry>
+		<entry> <filename>/usr/local/matita/</filename> </entry>
+		<entry> <para> Runtime base directory where all &appname; stuff
+		    (executables, configuration files, standard
+		    library, ...) will be installed </para> </entry>
+	      </row>
+	      <row>
+		<entry>
+		  <userinput>--with-dbhost=<replaceable>host</replaceable></userinput>
+		</entry>
+		<entry> localhost </entry>
+		<entry> <para>Default SQL server hostname. Will be used while
+		    building the standard library during the installation and to
+		    create the default &appname; configuration. May be changed
+		    later in configuration file.</para></entry>
+	      </row>
+	      <row>
+		<entry> <userinput>--enable-debug</userinput></entry>
+		<entry> disabled </entry>
+		<entry> <para> Enable debugging code. Not for the casual user.
+		  </para> </entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+	</table>
 
       </para>
 
-      <para> Then you will manage the build process using <application><ulink
-	    type="http"
+      <para> Then you will manage the build and install process using
+	<application><ulink type="http"
 	    url="http://www.gnu.org/software/make/">make</ulink></application>
 	as usual. Below are reported the targets you have to invoke in sequence
 	to build and install.
@@ -265,27 +333,25 @@
 	    <term><userinput>world</userinput></term>
 	    <listitem>
 	      <para>builds components needed by &appname; and &appname; itself
-		(in bytecode only or in both bytecode and native code depending
+		(in bytecode or native code depending
 		on the availability of the OCaml native code compiler) </para>
 	    </listitem>
 	  </varlistentry>
 
-	  <varlistentry>
-	    <term><userinput>library</userinput></term>
-	    <listitem>
-	      <para>uses the (just built) <application>matitac</application>
-		compiler to build the &appname; standard library. </para>
-	      <para>For this step you will need a working SQL database (for
-		indexing the standard library while you are compiling it). See
-		&TODO; for instructions on how to set it up.</para>
-	    </listitem>
-	  </varlistentry>
-
 	  <varlistentry>
 	    <term><userinput>install</userinput></term>
 	    <listitem>
 	      <para>installs &appname; related tools, standard library and the
-		needed runtime stuff in the proper places on the filesystem
+		needed runtime stuff in the proper places on the filesystem.
+	      </para>
+	      <para>As a part of the installation process the &appname;
+		standard library will be compiled, thus testing that the just
+		built <application>matitac</application> compiler works
+		properly.</para>
+	      <para>For this step you will need a working SQL database (for
+		indexing the standard library while you are compiling it). See
+		<ulink type="http" url="#database_setup">Database setup</ulink>
+		for instructions on how to set it up.
 	      </para>
 	    </listitem>
 	  </varlistentry>
@@ -294,8 +360,8 @@
 
       </para>
       
-    </sect3>
+    </sect2>
 
-  </sect2>
-</sect1>
+  </sect1>
+</chapter>