<html><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div>Dear all,</div><div><br></div><div>In addition to Amir's email (From: Amir Chaudhry <<a href="mailto:amc79@cam.ac.uk">amc79@cam.ac.uk</a>>, Date: Thu, Jul 4, 2013 at 9:54 AM),<div>here are some details to help you understand where we're heading to.</div>Please feel free to comment on it.<br><br>(The text below uses markdown syntax and ASCII-based schemas, so it's best viewed using a markdown viewer but using a fixed-width font should be fine too.)<br><br>We're trying to make the new ocaml.org website as simple to maintain<br>and build as possible, in the sense that one should not have to<br>understand the whole process in order to intervene on a tiny specific<br>part of the website.<br>An example of how this might work is in the schematic below.<br><br>**We are not heading to a website entirely written in OCaml.**<br>In particular, pages will be written using the Markdown language,<br>which is more human-friendly than HTML. Where needed, it will be<br>possible to use HTML, but parts written in HTML should almost never<br>change (that means that validation of HTML should be easily done with<br>an external tool). The site being mostly static is the main reason<br>why we're not considering writing the whole website using OCaml: it's<br>not worth the effort. Indeed, having to write some OCaml code is not<br>much more human-friendly than having to write some HTML code,<br>especially compared to using Markdown.<br><br>Some Markdown files will be written by humans, and some others partly<br>or entirely generated. Any of them may contain HTML parts. We will<br>use tools to allow the generation of Markdown files from "enriched"<br>Markdown files. This means that we may write special directives in<br>"enriched" Markdown files in order to, for instance, include OCaml<br>code from existing .ml files. We may also want to include the result<br>of the compilation of some OCaml code.<br><br>In an enriched Markdown file, we may write, for instance<br>{{ format-ocaml "ocaml -I blah" foo.ml }}<br>and this would be replaced by the top-level's output when given the <br>contents of the file foo.ml.<br><br>It could also be<br>{{ format-ocamlc "ocamlc -I blah" foo.ml }}<br>and this would be replaced by the output of the ocamlc compiler.<br><br>This approach allows the author of a page to have control of how the<br>code is processed without having to understand the rest of the<br>transformation chain (i.e., what happens once the Markdown file is<br>produced). That has to be true for the entire website: not having to <br>understand all of it seems to be crucial.<br><br><br><br># Schematic<br><br></div><div>```<br><font face="Courier"> Building the <a href="http://ocaml.org">ocaml.org</a> website<br><br></font></div><div><font face="Courier"> -------------------------------- <br> static generation | the <a href="http://ocaml.org">ocaml.org</a> website | dynamic generation <br> ----------------- | --------------------- | ------------------ <br> | || | <br>[Markdown]-----conv-------->[HTML]----------, | || | <br> (data) | | || | <br> {1}------------+-->[HTML/CSS/JS]=core | <br> | | || | <br>[LESS]---------Less-------->[CSS/JS]--------' | || | <br> (style) | || | <br> | || | <br>[OCaml]-----Js_of_ocaml---->[JS]-----------{2}------------+-->[JS]=components+lib | <br> (scripts) | || `---------+---request--------------, <br> | || | | <br> | || | v <br> | dynamic data=[DOM]<--+--{4}----response--[OPAM package list] <br> | || | [OCamlOT] <br>[Markdown+OCaml]---conv---->[Markdown]------, | || | <br> (examples, exercises) | | || | <br> {3}--conv------+-->[HTML/CSS/JS]=exercices | <br> | | || & demo | <br>[TryOCaml]----------------------------------' | || | <br> (execution environment) | || | <br> | other components | <br> | || | <br> -------------------------------- <br></font>```<br>`[`Format of the source code`]`<br><br>`||`: Backbone (link to all components), yet to be precisely defined.<br><br>`{1}`: The core of the <a href="http://ocaml.org">ocaml.org</a> website. It consists of a bunch of<br>Markdown and LESS files that are converted into HTML.<br><br>`{2}`: The dynamic part of the ocaml.org website. Dynamic components<br>should be written in OCaml. For instance, they may include a component<br>that, on the client side, fetches a list of OPAM packages (e.g., most<br>recent ones) and prints it on the page.<br><br>`{3}`: A kind of richer version of `{1}` (so it does also use CSS/JS).<br>Tutorials, and more generally exercises, are Markdown files which<br>include at some point some OCaml code. The OCaml code should be<br>processed in order to be embedded into some Markdown files; this can<br>be easily done using MPP. For instance, we can process the OCaml parts<br>in order to have the output given by the OCaml compiler (ocamlc or<br>ocamlopt) or interactive top-level (ocaml). We may also embed an<br>interactive top-level (e.g., TryOCaml) and make the examples<br>interactive and (locally) editable by the website visitors.<br><br><br>`[A]---conv--->[B]`: Some files written using the A language are<br>converted by some tools (to be defined) into files using the B<br>language. <br>Pandoc may be used to convert Markdown files into HTML.<br>MPP may be used to (pre)process any textual file.<br><br><br><br><br>```<br><font face="Courier"> Building the web pages (don't ignore the "List.iter")<br><br></font></div><div><font face="Courier">let build_the_main_ocamlorg_pages (all_pages) =<br> List.iter ~l:(all_pages) ~f:(fun a.md.mpp) -><br>,-------------------------------------------------------------------------------------------------------,<br>| | <br>| | <br>| | <br>| ,----------, ,----------------, | <br>| | a.md.mpp | | head.html.tpl | | <br>| | | | | | <br>| | | | title | | <br>| | |--, | author | | <br>| | | \ | style | | <br>| | | | | and | | <br>| | | |---X--->| other metadata |----, | <br>| '----------' | | | \ /------------------------\ | <br>| | '----------------' | | a.html | | <br>| | | | | | <br>| | ,----------------, | | generated | | <br>| | | body.html.tpl | | | web page | | <br>| | | | | | (HTML/CSS/JS) | | <br>| | | contents of | | | | | <br>| | | the body | | | | | <br>| `--X--->| |------+----->| | | <br>| '----------------' | | | | <br>| ,----------------, | | | | <br>| | common.html.tpl| | | | |<br>| | | | | | |<br>| | shared by |-----/ | | | <br>| | most pages | | | |<br>| | | \------------------------/ |<br>| '----------------' |<br>| X: extraction |<br>`-------------------------------------------------------------------------------------------------------'<br></font>``` <br><br>Please feel free to edit the ASCII-based schemas.<br><br><br>Best,<br>Philippe Wang<br><br><br><br><br><br><br></div><br></body></html>