Re: [Xen-API] [PATCH] [ocamldoc] HTML pass-thru in ocamldoc

[Rob Hoes <Rob.Hoes@xxxxxxxxxx>]

Yep, anything you like... it is just copied straight into the web page. It is 
especially useful for things like tables and images, for which OCamlDoc does 
not have built-in support. Of course using this restricts your docs to our 
custom-generated HTML, while "general" OCamlDoc can be used to generate LaTeX, 
man pages etc.

Cheers,
Rob

On 6 Dec 2009, at 22:12, Dave Scott wrote:

> Cool :)
> 
> Can the HTML include javascript?
> 
> Cheers,
> Dave
> 
>> -----Original Message-----
>> From: xen-api-bounces@xxxxxxxxxxxxxxxxxxx [mailto:xen-api-
>> bounces@xxxxxxxxxxxxxxxxxxx] On Behalf Of Rob Hoes
>> Sent: 05 December 2009 18:10
>> To: xen-api
>> Subject: [Xen-API] [PATCH] [ocamldoc] HTML pass-thru in ocamldoc
>> 
>> # HG changeset patch
>> # User Rob Hoes <rob.hoes@xxxxxxxxxx>
>> [ocamldoc] HTML pass-thru in ocamldoc
>> 
>> To include any HTML content in OCamlDoc special comments, place the
>> HTML content inside {html ...}. Example:
>> 
>> (** This picture fully describes the module: {html <img
>> src="mymodule.png" alt="MyModule" />} *)
>> 
>> Signed-off-by: Rob Hoes <rob.hoes@xxxxxxxxxx>
>> 
>> diff -r 9f5b9c98d6ca ocaml/doc/odoc_json.ml
>> --- a/ocaml/doc/odoc_json.ml Fri Dec 04 13:37:13 2009 +0000
>> +++ b/ocaml/doc/odoc_json.ml Sat Dec 05 18:09:33 2009 +0000
>> @@ -186,27 +186,29 @@
>> type html =
>> | Node of string * (string * string) list * html list (** Node ("",_,_)
>> will be discarded *)  | Leaf of string
>> +| Raw_html of string
>> 
>> let node tag ?(atts=[]) subs = Node (tag, atts, subs)
>> 
>> let escape_entities s =
>> -  let len = String.length s in
>> -  let buf = Buffer.create len in
>> -  for i = 0 to len - 1 do
>> -    match s.[i] with
>> -      '<' -> Buffer.add_string buf "&lt;"
>> -    | '>' -> Buffer.add_string buf "&gt;"
>> -    | '&' -> Buffer.add_string buf "&amp;"
>> -    | c -> Buffer.add_char buf c
>> -  done;
>> -  Buffer.contents buf
>> +    let len = String.length s in
>> +    let buf = Buffer.create len in
>> +    for i = 0 to len - 1 do
>> +            match s.[i] with
>> +            | '<' -> Buffer.add_string buf "&lt;"
>> +            | '>' -> Buffer.add_string buf "&gt;"
>> +            | '&' -> Buffer.add_string buf "&amp;"
>> +            | c -> Buffer.add_char buf c
>> +    done;
>> +    Buffer.contents buf
>> 
>> let string_of_bool b = if b then "true" else "false"
>> 
>> let rec print_one_t = function
>> -| Leaf s -> (escape_entities s)
>> -| Node ("",_,_) -> ""
>> -| Node (tag,atts,subs) ->
>> +| Leaf s -> escape_entities s
>> +| Raw_html s -> s
>> +| Node ("", _, _) -> ""
>> +| Node (tag, atts, subs) ->
>>      "<" ^ tag ^
>>      (match atts with
>>       | [] -> ""
>> @@ -219,6 +221,9 @@
>> 
>> and print_t_list l =
>>      String.concat "" (List.map print_one_t l)
>> +
>> +let html_to_json l =
>> +    String (print_t_list l)
>> 
>> (* the actual generator class *)
>> 
>> @@ -237,11 +242,13 @@
>> 
>>      method t_of_text = List.map self#t_of_text_element
>> 
>> +    method t_of_raw s = Leaf (remove_asterisks s)
>> +
>>      method t_of_text_element = function
>> -    | Odoc_info.Raw s -> Leaf (remove_asterisks s)
>> -    | Odoc_info.Code s -> node "tt" [Leaf (remove_asterisks s)]
>> -    | Odoc_info.CodePre s -> node "span" ~atts:["class", "codepre"]
>> [Leaf (remove_asterisks s)]
>> -    | Odoc_info.Verbatim s -> node "span" ~atts:["class", "verbatim"]
>> [Leaf (remove_asterisks s)]
>> +    | Odoc_info.Raw s -> self#t_of_raw s
>> +    | Odoc_info.Code s -> node "span" ~atts:["class", "code"]
>> [self#t_of_raw s]
>> +    | Odoc_info.CodePre s -> node "span" ~atts:["class", "codepre"]
>> [self#t_of_raw s]
>> +    | Odoc_info.Verbatim s -> node "span" ~atts:["class", "verbatim"]
>> +[self#t_of_raw s]
>>      | Odoc_info.Bold t -> node "b" (self#t_of_text t)
>>      | Odoc_info.Italic t -> node "i" (self#t_of_text t)
>>      | Odoc_info.Emphasize t -> node "em" (self#t_of_text t) @@ -
>> 255,14 +262,18 @@
>>      | Odoc_info.Title (n, l_opt, t) ->
>>              (*      (match l_opt with None -> [] | Some t -> ["name",t])
>> *)
>>              node ("h" ^ string_of_int n) (self#t_of_text t)
>> -    | Odoc_info.Latex s -> node "span" ~atts:["class", "latex"] [Leaf
>> (remove_asterisks s)]
>> +    | Odoc_info.Latex s -> node "span" ~atts:["class", "latex"]
>> +[self#t_of_raw s]
>>      | Odoc_info.Link (s, t) -> node "a" ~atts: ["href", s]
>> (self#t_of_text t)
>>      | Odoc_info.Ref (name, ref_opt) -> self#t_of_Ref name ref_opt
>>      | Odoc_info.Superscript t -> node "sup" (self#t_of_text t)
>>      | Odoc_info.Subscript t -> node "sub" (self#t_of_text t)
>>      | Odoc_info.Module_list l -> Leaf "" (* self#json_of_Module_list
>> l *)
>>      | Odoc_info.Index_list -> Leaf "" (* node "index_list" [] *)
>> -    | Odoc_info.Custom (s,t) -> Leaf "" (* node "custom" ~atts:
>> ["name", s] (self#t_of_text t) *)
>> +    | Odoc_info.Custom (s,t) ->
>> +            if s = "{html" then
>> +                    Raw_html (String.concat "" (List.map (fun
>> (Odoc_info.Raw s) -> remove_asterisks s) t))
>> +            else
>> +                    node "div" ~atts:["class", s] (self#t_of_text t)
>> 
>>      method t_of_Ref name ref_opt =
>>              let code = node "span" ~atts:["class", "code"] [Leaf name]
>> in @@ -375,7 +386,7 @@
>>              Object (name :: info :: kind @ [])
>> 
>>      method json_of_comment t =
>> -            String (print_t_list (self#t_of_text t))
>> +            html_to_json (self#t_of_text t)
>> 
>>      method json_of_type t =
>>              let name = "name", String t.Type.ty_name in @@ -416,7
>> +427,7 @@
>>              | None -> []
>>              | Some t ->
>>                      completed_descr_cnt <- completed_descr_cnt + 1;
>> -                    ["description", String (print_t_list (self#t_of_text
>> t))]
>> +                    ["description", html_to_json (self#t_of_text t)]
>>              in
>>              descr_cnt <- descr_cnt + 1;
>>              Object (["name", String c.Type.vc_name] @ desc @ ["type",
>> Array (List.map self#json_of_type_expr c.Type.vc_args)]) @@ -426,7
>> +437,7 @@
>>              | None -> []
>>              | Some t ->
>>                      completed_descr_cnt <- completed_descr_cnt + 1;
>> -                    ["description", String (print_t_list (self#t_of_text
>> t))]
>> +                    ["description", html_to_json (self#t_of_text t)]
>>              in
>>              descr_cnt <- descr_cnt + 1;
>>              Object (["name", String f.Type.rf_name; "mutable",
>> json_of_bool f.Type.rf_mutable] @ @@ -443,7 +454,7 @@
>>              | None -> []
>>              | Some t ->
>>                      completed_descr_cnt <- completed_descr_cnt + 1;
>> -                    ["description", String (print_t_list (self#t_of_text
>> t))]
>> +                    ["description", html_to_json (self#t_of_text t)]
>>              in
>>              let authors = match List.map (fun s -> String s)
>> i.i_authors with
>>              | [] -> []
>> @@ -461,7 +472,7 @@
>>              in
>>              let dep = match i.i_deprecated with
>>              | None -> []
>> -            | Some t -> ["deprecated", String (print_t_list
>> (self#t_of_text t))]
>> +            | Some t -> ["deprecated", html_to_json (self#t_of_text t)]
>>              in
>>              let params = [] in
>>              let raised = match List.map self#json_of_raised_exception
>> i.i_raised_exceptions with @@ -470,18 +481,18 @@
>>              in
>>              let return_v = match i.i_return_value with
>>              | None -> []
>> -            | Some t -> ["return", String (print_t_list (self#t_of_text
>> t))]
>> +            | Some t -> ["return", html_to_json (self#t_of_text t)]
>>              in
>> -            let customs = List.map (fun (tag, t) -> tag, String
>> (print_t_list (self#t_of_text t))) i.i_custom in
>> +            let customs = List.map (fun (tag, t) -> tag, html_to_json
>> +(self#t_of_text t)) i.i_custom in
>>              Object (desc @ authors @ version @ see @ since @ dep @
>> params @ raised @ return_v @ customs)
>> 
>>      method json_of_see = function
>> -    | (See_url s, t) -> Object ["url", String s; "text", String
>> (print_t_list (self#t_of_text t))]
>> -    | (See_file s, t) -> Object ["file", String s; "text", String
>> (print_t_list (self#t_of_text t))]
>> -    | (See_doc s, t) -> Object ["doc", String s; "text", String
>> (print_t_list (self#t_of_text t))]
>> +    | (See_url s, t) -> Object ["url", String s; "text", html_to_json
>> (self#t_of_text t)]
>> +    | (See_file s, t) -> Object ["file", String s; "text",
>> html_to_json (self#t_of_text t)]
>> +    | (See_doc s, t) -> Object ["doc", String s; "text", html_to_json
>> +(self#t_of_text t)]
>> 
>>      method json_of_raised_exception (s, t) =
>> -            Object ["raised_exception", String s; "text", String
>> (print_t_list (self#t_of_text t))]
>> +            Object ["raised_exception", String s; "text", html_to_json
>> +(self#t_of_text t)]
>> 
>>      method json_of_module m =
>>              let name = "name", String m.Module.m_name in diff -r
>> 9f5b9c98d6ca ocaml/doc/style.css
>> --- a/ocaml/doc/style.css    Fri Dec 04 13:37:13 2009 +0000
>> +++ b/ocaml/doc/style.css    Sat Dec 05 18:09:33 2009 +0000
>> @@ -263,8 +263,9 @@
>> }
>> 
>> .arrow {
>> -    font-size: 2em;
>> +    font-size: 150%;
>>      color: #cc6600;
>> +    padding: 0 3px;
>> }
>> 
>> .optional {
>> diff -r 9f5b9c98d6ca ocaml/xapi/xapi_vlan.mli
>> --- a/ocaml/xapi/xapi_vlan.mli       Fri Dec 04 13:37:13 2009 +0000
>> +++ b/ocaml/xapi/xapi_vlan.mli       Sat Dec 05 18:09:33 2009 +0000
>> @@ -16,7 +16,7 @@
>>  *)
>> 
>> (**
>> -Xapi also supports 802.1Q VLANs, which are used to separate network
>> traffic by inserting a _tag_ in each packet, thereby creating multiple
>> virtual networks. A tag is simply a number.
>> +Xapi also supports 802.1Q VLANs, which are used to separate network
>> traffic by inserting a {i tag} in each packet, thereby creating
>> multiple virtual networks. A tag is simply a number.
>> {ul
>> {- A VLAN has a {i VLAN} object in the datamodel, which is associated
>> with a {i slave} PIF and a {i master} PIF.}
>> {- The VLAN slave, or untagged PIF, is used as the base of the VLAN.
>> It can be any existing PIF (including bond masters).}


_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/mailman/listinfo/xen-api