Some more doc.

diff --git a/chapter-libpack.xml b/chapter-libpack.xml
index 81457dafa5e78448553eed30c884fa18be73a960..54b33c3e5ad12b0f18ef0fa7c5de50e401dc3fff 100644 (file)
--- a/chapter-libpack.xml
+++ b/chapter-libpack.xml
@@ -1,3 +1,50 @@
+<section>
+    <title>Creating a package for a library</title>
+
+    <para>
+        A package which provides an OCaml library <filename>xxx</filename> should be split as follows:
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    For libraries which are not purely programmed in OCaml (e.g. C bindings), <filename>libxxx-ocaml</filename> should provide the shared library stubs (<filename>dll*.so</filename>), and all other stuff needed to run a bytecode executable that links into this library. It should depend on <filename>ocaml-base-&ocaml-version;</filename> (or <filename>ocaml-base-nox-&ocaml-version;</filename>) as well as any other library needed.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <filename>libxxx-ocaml-dev</filename> should provide the rest of the library package, in fact anything needed to develop programs using the library. If the library uses other libraries or C libraries, this package should depend on them.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        Optionally, two other packages may be created:
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <filename>libxxx-ocaml-bin</filename> may include binaries provided by the library source package if they are numerous. This package should conform with the same regulations as other packages providing ocaml programs. It is only needed to split off this package if there is a significant number of programs included in the library, if not, the programs should go into <filename>libxxx-ocaml-dev</filename>.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <filename>libxxx-ocaml-doc</filename> may include any kind of documentation provided by the library source package or as separate documentation. Again, if there is only little documentation, they should go with the <filename>-dev</filename> package.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        It is recommended that libraries use the <option>-pack</option> option to pack all the modules provided by the library into one module. We are not sure this really works right now for libraries, and we don't think upstream libraries will be moving to this scheme anytime soon (unless we actively lobby for it) so this is just a recommendation for now.
+    </para>
+</section>
+
+<section>
+    <title>Handling dependencies on OCaml</title>
+    <para>
+    </para>
+</section>
+
 <section id="library-path">
     <title>Paths for libraries</title>
 
@@ -59,6 +106,7 @@
     </para>
 </section>
 
+<!--
 <section id="ocamldoc-base-path">
     <title>&ocamldoc; specific generated documentation</title>
 
@@ -106,19 +154,20 @@
         author to have a well commented source.
     </para>
 </section>
+-->
 
 <section id="camlp4-path">
     <title>&camlp4;</title>
     <para>
         Actually, &camlp4; extensions are stored in
         <filename>/usr/lib/ocaml/&ocaml-version;/camlp4/</filename>. In order to do something
-        cleaner, &ocaml-force; propose to put this files in their own directory, even in their
-        own package. It is not mandatory, but it could ease a lot, the user of camlp4, by avoiding
-        name clash.
+        cleaner, &ocaml-force; proposes to put this files in their own directory, even in their
+        own package. It is not mandatory, but it could ease a lot by avoiding
+        name clashes.
     </para>
 
     <para>
-        You just have to consider &camlp4; file just as standard library, except that you
+        You just have to consider a &camlp4; file just as a standard library, except that you
         prefix them with <varname>-syntax</varname>. For example: the syntax
         extension coming with <application>libokey-ocaml-dev</application> should be stored
         in <filename>/usr/lib/ocaml/&ocaml-version;/okey-syntax/</filename>, the package
@@ -141,35 +190,34 @@
     <title>Documentation</title>
     <para>
         The documentation is a joint effort of  &ocaml-force; and usptream. 
-        There is many way to have documentation : 
+        There are many ways to have documentation:
         <itemizedlist>
-            <listitem><para>Header files (<filename>*.mli</filename>)</para></listitem>
-            <listitem><para>Source files (<filename>*.ml</filename>)</para></listitem>
-            <listitem><para>Specific documentation provided by the upstream</para></listitem>
-            <listitem><para>OCamldoc generated documentation</para></listitem>
+            <listitem><para>header files (<filename>*.mli</filename>),</para></listitem>
+            <listitem><para>source files (<filename>*.ml</filename>),</para></listitem>
+            <listitem><para>specific documentation provided by the upstream,</para></listitem>
+            <listitem><para>OCamldoc generated documentation</para>.</listitem>
         </itemizedlist>
     </para>
 
     <para>
-        This documentation should be browse by different mean, from the
-        most simple to the most complex. At least, they could all be browsed with
-        simple text editor. Specific and &ocamldoc; generated documentation should
-        be browse by using different viewer ( like <application>advi</application>,
-        HTML browser...). There is also at least two
+        This documentation should be browsable by different mean, from the
+        most simple to the most complex. At least, they should all be readable with
+        simple text editor. Specific and &ocamldoc; generated documentations should be provided in HTML format.
+        There are also at least two
         specific &ocaml-name; browser : <application>docbrowse</application> shipped
         with <application>cameleon</application> and <application>ocamlbrowser</application>
-        shipped with &ocaml-name; itself. The first one, need specific
+        shipped with &ocaml-name; itself. The first one, needs specific
         &ocamldoc; generated documentation. The second one enables
-        the user to browse directly the prototype of each function shipped in the cmi gives
+        the user to browse directly the prototype of each function shipped in the <filename>cmi</filename> gives
         to the application.
     </para>
 
     <para>
-        You can generate &ocamldoc; specific documentation by using
+        You can generate &ocamldoc;-specific documentation by using
         the <option>-dump</option> of this application. By using this, you dump the
         intermediary representation of the document that will be generated by ocamldoc.
         This can be used to generate HTML documentation and manpages, by reloading this
-        file ( using <option>-load</option> ).
+        file (using <option>-load</option>).
     </para>
 
     <para>

diff --git a/chapter-progpack.xml b/chapter-progpack.xml
index 2a671e2734c1009e29e8d71926e455384de45c7c..44447ab5bf54048ac4b11b7b8dab94db331b47bd 100644 (file)
--- a/chapter-progpack.xml
+++ b/chapter-progpack.xml
@@ -1,6 +1,25 @@
 <section>
-    <title>Packaging OCaml prgrams</title>
+    <title>Creating a package for an OCaml program</title>
     <para>
-        blah
+        Any package providing executables built from OCaml source should conform
+     the following regulations.
+
+     <itemizedlist>
+         <listitem>
+             <para>
+                 The package should use the name of the upstream package, without modification.
+             </para>
+         </listitem>
+         <listitem>
+             <para>
+                 The package's <filename>debian/rules</filename> should build the native code executable if supported on the architecture it is built on, and fall back to building the bytecode version if no working native code compiler is available. The availability of a native compiler can be tested by <code>[ -e /usr/bin/ocamlopt ]</code>. Exceptions to this are the executables who are small or not time critical, which may be built only as bytecode. It is the decision of the individual maintainers to choose this, maybe guided by the practice of the upstream author.
+             </para>
+         </listitem>
+         <listitem>
+             <para>
+                 All bytecode executables should be link dynamically, so as to not bloat the archive. However, there may be special cases, were using statically linked bytecode is necessary, in these cases, it is naturally ok to link statically. That said, often the upstream authors will favor statically linked bytecode executables, because so they don't need to worry about the presence of the dll stub libraries and such. This will never be a valid reason to use statically linked bytecode in a Debian package. If statically linked bytecode is provided, a justification of this use should be provided in the <filename>README.Debian</filename> file.
+             </para>
+         </listitem>
+     </itemizedlist>
     </para>
 </section>