Translate the tutorial manual to wodoc (.mld)

tutos/8.0/manual/custom-conf.wiki → tutos/8.0/manual/custom-conf.mld

@@ -1,16 +1,18 @@
-=Custom configuration options=
-<<concepts |Custom configuration options>>
+{0 Custom configuration options}
+{%wodoc:aside class="concepts"%}{b Concepts}
+
+Custom configuration options{%wodoc:end%}
 
 It is not convenient to have to edit the code to change some
 configurations, like the location where are saved the favorite
 images in the Graffiti tutorial
-(see: [[wiki:pictures|Saving favorite pictures]]).
+(see: {{:pictures.html}Saving favorite pictures}).
 Fortunately Ocsigen provides a mechanism to extend its
 configuration file.
 
-==Basic interface==
+{1 Basic interface}
 
-<<code language="ocaml"|
+{@ocaml[
 let static_dir =
   match Eliom_config.get_config () with
     | [Simplexmlparser.Element
@@ -22,27 +24,27 @@ let static_dir =
     | _ ->
       raise (Ocsigen_extensions.Error_in_config_file
                ("Unexpected content inside config"))
->>
+]}
 
 This will add a mandatory child to the eliom tag in the
 configuration file:
-{{{
+{v
 <eliom module="path/to/your/module.cma">
   <staticdir>/tmp/static</staticdir>
 </eliom>
-}}}
+v}
 
 
-==New interface==
+{1 New interface}
 
 From Eliom 4.0 it is much easier to define configuration file extension.
-Have a look at module <<a_api project="eliom" subproject="server"|module Eliom_config>>.
+Have a look at module {!Eliom_config}.
 For instance, here is how you can add an element "<ldap>"
 in the configuration file to store a list of LDAP servers your application
 interacts with.
 
 
-<<code language="ocaml"|
+{@ocaml[
 
 (** An LDAP server is characterized by an host and a port. *)
 type ldap_configuration = {
@@ -86,4 +88,4 @@ let ldap_configuration = Ocsigen_extensions.Configuration.(
 
 let _ = Eliom_config.parse_config [ldap_configuration]
 
->>
+]}

tutos/8.0/manual/hash-password.wiki → tutos/8.0/manual/hash-password.mld

@@ -1,13 +1,13 @@
-=Protecting your passwords=
+{0 Protecting your passwords}
 
 For protecting the user passwords or other sensitive data,
 we can use
-[[http://ocaml-safepass.forge.ocamlcore.org/|ocaml-safepass]].
+{{:http://ocaml-safepass.forge.ocamlcore.org/}ocaml-safepass}.
 
 We can now write the encrypted password in our database
-(using <<a_api project="ocsigenserver"| type Ocsipersist.table >>
+(using {!Ocsipersist.table}
 in this example) as follow:
-<<code language="ocaml"|
+{@ocaml[
 let table =
   Ocsipersist.Polymorphic.open_table "users"
 
@@ -20,8 +20,8 @@ let add_user username password =
       | Not_found ->
         Ocsipersist.Polymorphic.add table username
           (Bcrypt.hash password, email)
-        ~>>= fun () ->
+        >>= fun () ->
         Lwt.return true
       | e -> Lwt.fail e
     )
->>
+]}

tutos/8.0/manual/how-do-i-create-a-cryptographically-safe-identifier.mld

@@ -0,0 +1,3 @@
+{0 How do I create a cryptographically safe identifier?}
+
+{!Ocsigen_lib.make_cryptographic_safe_string}

tutos/8.0/manual/how-does-a-page-s-source-code-look.mld

@@ -0,0 +1,81 @@
+{0 How does a client-server app source code look like?}
+
+{2 Eliom client-server applications}
+
+Eliom client-server applications are running in your browser for a {{:../eliom/clientserver-applications.html}certain lifetime} and consist of one or several pages/URLs.
+An application has its associated js file, which must have the same name ({{:../manual/how-to-compile-my-ocsigen-pages}generated automatically by the default makefile} and added automatically by Eliom in the page).
+
+For example, we define an application called {e example}:
+{@ocaml[
+module Example =
+  Eliom_registration.App
+    (struct
+      let application_name = "example"
+     end)
+]}
+
+{2 Eliom Services}
+
+Pages are generated by {e services}. Here is how to define a service:
+
+{@ocaml[
+let main =
+  Eliom_service.create
+    ~path:(Eliom_service.Path [])
+    ~meth:(Eliom_service.Get unit)
+    ()
+]}
+
+The path is a list of string corresponding to the url. Here, the list is empty because it's the main page.
+
+If, for example, the list is ["hello";"world"], the page will be accessed using the address:
+{[http://website.com/hello/world/]}
+
+More information about parameters: {{:how-to-use-get-parameters-or-parameters-in-the-url.html}How to use GET parameters (parameters in the URL)?}
+
+Now that our service has been declared, we associate to it an OCaml function that will generate the page. We call this {e service registration}. If the service belongs to the application, we use the registrations functions from module [Example] defined above.
+
+{@ocaml[
+let _ =
+  Example.register
+    ~service:main
+    (fun () () ->
+      Lwt.return ...)
+]}
+
+The third parameter is the function that will be called to generate the page.
+This function takes two parameters, corresponding respectively to GET and POST parameters. Here both are [()] because the service does not take any parameter. The function returns an element of type html (using Lwt).
+
+
+{2 Page Content}
+
+The content of Eliom application pages is made using functions.
+The {b html function} takes two parameters:
+head and body, which are also functions that takes parameters coresponding to their content.
+
+{@ocaml[
+(html
+           (head (title (txt "Page Title")) [])
+           (body [p [txt "Hello World!"]])))
+]}
+
+Most of the elements functions take a list of other elements as a parameter.
+
+{%wodoc:img src="http://public.db0.fr/dev/ocsigen/html.png" alt="ast"%}
+
+Validity of HTML is checked at compile time, which means that a program
+that may generate a page that does not respect the recommendations of the
+W3C will be rejected at compile time.
+
+{2 Download full code}
+
+{e Warning: This third party code may be outdated. Please notify the author is something is broken, or do a pull request on github.}
+
+- {{:https://github.com/db0company/Ocsigen-Quick-Howto/blob/master/page/example.eliom}Read the full code}
+- {{:https://github.com/db0company/Ocsigen-Quick-Howto}Download and try this example}
+
+
+{2 Links}
+
+- {{:../eliom/server-services.html}About services}
+- {{:../tyxml/.html}About html generation}

tutos/8.0/manual/how-to-add-a-div.mld

@@ -0,0 +1,25 @@
+{0 How to add a div?}
+
+{@ocaml[
+div ~a:[a_class ["firstclass"; "secondclass"]] [txt "Hello!"]
+]}
+
+{b Required parameter}: list containing other elements
+(Details of available elements in type
+{!Html_types.flow5}).
+
+{b Optional parameter} for attributes "a" ({{:how-to-set-and-id-classes-or-other-attributes-to-html-elements.html}How to set and id, classes or other attributes to HTML elements?}).
+
+{2 Download full code}
+
+{e Warning: This third party code may be outdated. Please notify the author is something is broken, or do a pull request on github.}
+
+- {{:https://github.com/db0company/Ocsigen-Quick-Howto/blob/master/elements/example.eliom}Read the full code}
+- {{:https://github.com/db0company/Ocsigen-Quick-Howto}Download and try this example}
+
+{2 Links}
+
+- Modules {!Eliom_content.Html.D} and
+  {!Eliom_content.Html.F}
+  (HTML5 Elements)
+- signature {!Html_sigs.T} (Element attributes)

tutos/8.0/manual/how-to-add-a-favicon.mld

@@ -0,0 +1,16 @@
+{0 How to add a Favicon?}
+
+A favicon is a file of type "ico" which contain a picture of size 16x16px. It is the picture that you can ususally see next to the title of the page on a browser.
+
+{%wodoc:img src="http://public.db0.fr/dev/ocsigen/favicon.png" alt="favicon for Ocsigen.org"%}
+
+By default, all browsers look for a file [favicon.ico]
+at the root of the website:
+{[ http://website.com/favicon.ico]}
+
+Just put the file at the root of the static directory set in the configuration file.
+
+{2 Links}
+
+- {{:../ocsigenserver/staticmod.html}Configuring Ocsigen Server for serving static files}
+- {{:http://www.favicon.cc/}An example of a favicon generator}

tutos/8.0/manual/how-to-add-a-javascript-script.mld

@@ -0,0 +1,30 @@
+{0 How to add a JavaScript script?}
+
+If you have client-side programs on your website, you can use Eliom's client-server features, that will compile client-side parts to JS using {b Ocsigen Js_of_ocaml}, and automatically include the script in the page. But in some cases you may also want to include external JS scripts yourself.
+
+{2 Include the script on the html header}
+
+Javascript scripts are included in the header using the {b js_script} function (defined in {!Eliom_content.Html.D}).
+
+{@ocaml[
+open Eliom_content.Html.D (* for make_uri an js_script *)
+
+js_script
+     ~uri:(make_uri (Eliom_service.static_dir ())
+              ["hello.js"])
+     ()
+]}
+This function has 2 parameters: the file path and unit.
+
+The file path is generated using the {b make_uri} function (from {!Eliom_content.Html.D} module). This function creates the relative URL string using the static directory (which is a service) configured in the configuration file and the given list.
+
+Insert this piece of code on the list given in parameter to the {b head} function.
+
+Or you can use:
+{!Eliom_tools.F.head}
+
+{2 Call an external function}
+
+Have a look at
+{{:../js_of_ocaml/bindings.html}this page of Js_of_ocaml's manual}
+to understand how to call JS function from your OCaml program.