[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


  • To: Dave Scott <Dave.Scott@xxxxxxxxxxxxx>
  • From: Rob Hoes <Rob.Hoes@xxxxxxxxxx>
  • Date: Sun, 6 Dec 2009 22:23:35 +0000
  • Accept-language: en-US
  • Acceptlanguage: en-US
  • Cc: xen-api <xen-api@xxxxxxxxxxxxxxxxxxx>
  • Delivery-date: Sun, 06 Dec 2009 14:23:38 -0800
  • List-id: Discussion of API issues surrounding Xen <xen-api.lists.xensource.com>
  • Thread-index: Acp2wsHNYr++bI5iRwmu47HWemrPQQ==
  • Thread-topic: [Xen-API] [PATCH] [ocamldoc] HTML pass-thru in ocamldoc

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


 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.