"ocaml_beginners"::[] ocamldoc -> custom @tag

Hi,

I'm trying to define a custom -tag as explained in the
documentation:
http://caml.inria.fr/pub/docs/manual-ocaml/manu
al029.html#htoc168
But it does not work as you can see below:

-- 
[blue_prawnazur ~]$ mkdir /tmp/odoc
[blue_prawnazur ~]$ cd /tmp/odoc

[blue_prawnazur odoc]$ cat > foo.ml <<'EOF'

class my_gen =
  object(self)
    inherit Odoc_html.html

    (** Return HTML code for the given text of a foo tag. *)
    method html_of_foo t =
        "( TEST )"

    initializer
      tag_functions <- ("foo",
self#html_of_foo) :: tag_functions
  end

EOF

[blue_prawnazur odoc]$ cat > bar.mli <<'EOF'

val test: unit -> unit
(**
foo
test
*)

EOF

[blue_prawnazur odoc]$ ocamlc -I +ocamldoc -c foo.ml
[blue_prawnazur odoc]$ ocamldoc -g foo.cmo -html bar.mli
Warning: Tag foo not handled by this generator
Warning: Tag foo not handled by this generator

[blue_prawnazur odoc]$ lynx --dump Bar.html

    [6]Up

                               Module [7]Bar

module Bar: sig [8].. end
  
____________________________________________________________
__________

val test : unit -> unit



_____


------------------------ Yahoo! Groups Sponsor
--------------------~--> 
Get to your groups with one click. Know instantly when new
email arrives
http://us.click.yahoo.com/.7bhrC/MGxNAA/yQLSAA/saFolB/TM

------------------------------------------------------------
--------~-> 

Archives up to August 22, 2005 are also downloadable at http://www.connettivo.net/cntprojects/ocaml_beginners/
The archives of the very official ocaml list (the seniors'
one) can be found at http://caml.inria.fr
Attachments are banned and you're asked to be polite, avoid
flames etc. 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http:/
/groups.yahoo.com/group/ocaml_beginners/

<*> To unsubscribe from this group, send an email to:
    ocaml_beginners-unsubscribe@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.c
om/info/terms/
 

On Tue, May 30, 2006 at 02:53:56PM +0200, Florent Monnier
wrote:
> class my_gen =
>   object(self)
>     inherit Odoc_html.html
> 
>     (** Return HTML code for the given text of a foo
tag. *)
>     method html_of_foo t =
>         "( TEST )"
> 
>     initializer
>       tag_functions <- ("foo",
self#html_of_foo) :: tag_functions
>   end

The documentation is actually self-contradictory, but it's
clear at
least that this class definition alone could never work. 
After all, a
mere class definition does not actually create any objects,
so the
initializer could never be called with the code above.

The documentation suggests adding this (note that the type
of the
argument to set_doc_generator has also changed):

let my_gen = new my_gen
let _ = Odoc_args.set_doc_generator (Some (my_gen :>
Odoc_args.doc_generator))

That causes the initializer to be called, but in my testing
here still
doesn't get the foo tag recognised.

Rich.

-- 
Richard Jones, CTO Merjis Ltd.
Merjis - web marketing and technology - http://merjis.com
Team Notepad - intranets and extranets for business - http://team-notepad.com


------------------------ Yahoo! Groups Sponsor
--------------------~--> 
Get to your groups with one click. Know instantly when new
email arrives
http://us.click.yahoo.com/.7bhrC/MGxNAA/yQLSAA/saFolB/TM

------------------------------------------------------------
--------~-> 

Archives up to August 22, 2005 are also downloadable at http://www.connettivo.net/cntprojects/ocaml_beginners/
The archives of the very official ocaml list (the seniors'
one) can be found at http://caml.inria.fr
Attachments are banned and you're asked to be polite, avoid
flames etc. 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http:/
/groups.yahoo.com/group/ocaml_beginners/

<*> To unsubscribe from this group, send an email to:
    ocaml_beginners-unsubscribe@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.c
om/info/terms/
 

Florent Monnier wrote:
> 
> I'm trying to define a custom -tag as explained in the
documentation:
> http://caml.inria.fr/pub/docs/manual-ocaml/manu
al029.html#htoc168
> But it does not work as you can see below:

The manual says you have to write a custom generator:

	To handle custom tags, you need to define a custom
	generator, as explained in section 15.3.2. (15.2.5)

Note that a custom generator can inherit from one of the
existing 
generators and only override what it needs to change, again
according to 
the documentation.  I haven't tried it myself, but it looks
easy enough.

-- 
Michael Wojcik



------------------------ Yahoo! Groups Sponsor
--------------------~--> 
Everything you need is one click away.  Make Yahoo! your
home page now.
http://us.click.yahoo.com/AHchtC/4FxNAA/yQLSAA/saFolB/TM

------------------------------------------------------------
--------~-> 

Archives up to August 22, 2005 are also downloadable at http://www.connettivo.net/cntprojects/ocaml_beginners/
The archives of the very official ocaml list (the seniors'
one) can be found at http://caml.inria.fr
Attachments are banned and you're asked to be polite, avoid
flames etc. 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http:/
/groups.yahoo.com/group/ocaml_beginners/

<*> To unsubscribe from this group, send an email to:
    ocaml_beginners-unsubscribe@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.c
om/info/terms/
 

Le Tue, 30 May 2006 14:53:56 +0200,
Florent Monnier <fmonnierlinux-nantes.fr.eu.org>
a _crit :

> Hi,
> 
> I'm trying to define a custom -tag as explained in the
documentation:
> http://caml.inria.fr/pub/docs/manual-ocaml/manu
al029.html#htoc168
> But it does not work as you can see below:
> 

I found the documentation not clear at all on this subject
(especially
the "(* your code here *)" part ... )

After googling a bit, I found this page [1] which help me a
lot in
writing a custom generator, especially with this file [2].
It's in french, but the file [2] is clear enough.

Hope it can help ...

	Jonathan



[1]
http://www-poleia.lip6.fr/~gonzales/tea
ching/li260-2005fev/ressources.php
[2]
http://www-poleia.lip6.fr
/~gonzales/teaching/li260-2005fev/resources/ocamldoc_projet.
ml


------------------------ Yahoo! Groups Sponsor
--------------------~--> 
Home is just a click away.  Make Yahoo! your home page now.
http://us.click.yahoo.com/DHchtC/3FxNAA/yQLSAA/saFolB/TM

------------------------------------------------------------
--------~-> 

Archives up to August 22, 2005 are also downloadable at http://www.connettivo.net/cntprojects/ocaml_beginners/
The archives of the very official ocaml list (the seniors'
one) can be found at http://caml.inria.fr
Attachments are banned and you're asked to be polite, avoid
flames etc. 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http:/
/groups.yahoo.com/group/ocaml_beginners/

<*> To unsubscribe from this group, send an email to:
    ocaml_beginners-unsubscribe@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.c
om/info/terms/
 

> > I'm trying to define a custom -tag as
explained in the documentation:
> > http://caml.inria.fr/pub/docs/manual-ocaml/manu
al029.html#htoc168
> > But it does not work as you can see below:
>
> I found the documentation not clear at all on this
subject (especially
> the "(* your code here *)" part ... )
>
> After googling a bit, I found this page [1] which help
me a lot in
> writing a custom generator, especially with this file
[2].
> It's in french, but the file [2] is clear enough.
>
> Hope it can help ...

Thanks a lot Jonathan,  indeed it help for the part which
deals with getting 
the content of the tag with the  self#html_of_text  method.

But the problem is clearly the same: We see clearly in this
example that the 
custom methods associated with the custom tags
should return a string (as we 
can see with Buffer.contents which returns a string), and
this returned 
string does not appear in the resulting documentation... :,(

-- 
thanks


------------------------ Yahoo! Groups Sponsor
--------------------~--> 
Everything you need is one click away.  Make Yahoo! your
home page now.
http://us.click.yahoo.com/AHchtC/4FxNAA/yQLSAA/saFolB/TM

------------------------------------------------------------
--------~-> 

Archives up to August 22, 2005 are also downloadable at http://www.connettivo.net/cntprojects/ocaml_beginners/
The archives of the very official ocaml list (the seniors'
one) can be found at http://caml.inria.fr
Attachments are banned and you're asked to be polite, avoid
flames etc. 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http:/
/groups.yahoo.com/group/ocaml_beginners/

<*> To unsubscribe from this group, send an email to:
    ocaml_beginners-unsubscribe@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.c
om/info/terms/
 

> > I'm trying to define a custom -tag as
explained in the documentation:
> > http://caml.inria.fr/pub/docs/manual-ocaml/manu
al029.html#htoc168
> > But it does not work as you can see below:
>
> The manual says you have to write a custom generator:
>
> 	To handle custom tags, you need to define a custom
> 	generator, as explained in section 15.3.2. (15.2.5)
>
> Note that a custom generator can inherit from one of
the existing
> generators and only override what it needs to change,
again according to
> the documentation.  I haven't tried it myself, but it
looks easy enough.

Have you tryed the code I've given in the mail you are
replying ?
It seems not.
Indeed in the doc it looks very easy enough, 
but as you can see below (the same code than in the message
you're replying) 
I've replaced:     (* your code here *)
by the string:     "( TEST )"
(as the method should return a string)
« It looks easy enough », but IT DOES NOT WORK !

-- 
[blue_prawnazur ~]$ mkdir /tmp/odoc
[blue_prawnazur ~]$ cd /tmp/odoc

[blue_prawnazur odoc]$ cat > foo.ml <<'EOF'

class my_gen =
  object(self)
    inherit Odoc_html.html

    (** Return HTML code for the given text of a foo tag. *)
    method html_of_foo t =
        "( TEST )"

    initializer
      tag_functions <- ("foo",
self#html_of_foo) :: tag_functions
  end

EOF

[blue_prawnazur odoc]$ cat > bar.mli <<'EOF'

val test: unit -> unit
(**
foo
test
*)

EOF

[blue_prawnazur odoc]$ ocamlc -I +ocamldoc -c foo.ml
[blue_prawnazur odoc]$ ocamldoc -g foo.cmo -html bar.mli
Warning: Tag foo not handled by this generator
Warning: Tag foo not handled by this generator

[blue_prawnazur odoc]$ lynx --dump Bar.html

    [6]Up

                               Module [7]Bar

module Bar: sig [8].. end
  
____________________________________________________________
__________

val test : unit -> unit



_____


------------------------ Yahoo! Groups Sponsor
--------------------~--> 
Protect your PC from spy ware with award winning anti spy
technology. It's free.
http://us.click.yahoo.com/97bhrC/LGxNAA/yQLSAA/saFolB/TM

------------------------------------------------------------
--------~-> 

Archives up to August 22, 2005 are also downloadable at http://www.connettivo.net/cntprojects/ocaml_beginners/
The archives of the very official ocaml list (the seniors'
one) can be found at http://caml.inria.fr
Attachments are banned and you're asked to be polite, avoid
flames etc. 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http:/
/groups.yahoo.com/group/ocaml_beginners/

<*> To unsubscribe from this group, send an email to:
    ocaml_beginners-unsubscribe@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.c
om/info/terms/
 

Seems your problem is your arguments to ocamldoc.

foo_tag.ml:
class my_gen = object(self)
  inherit Odoc_html.html
  method invoke t = "(TEST)"
  initializer
    tag_functions <- ("foo", self#invoke) ::
tag_functions
end

let generator = new my_gen
let ignore = Odoc_args.set_doc_generator (Some (generator
:>
Odoc_args.doc_generator))

test.mli:
val test : unit -> unit
(**
foo
this is a test tag
*)

compiling:
ocamlc -I +ocamldoc foo_tag.ml

doc generation:
ocamldoc -g foo_tag.cmo test.mli

Note no -html option, as foo_tag.cmo is itself a generator.

I think what is happening is that specifying -html after -g
option,
the custom generator is getting replaced with the html
generator,
which knows nothing of your custom tag, resulting in your
problems.

I've tested this, and the above indeed works.

Jonathan


------------------------ Yahoo! Groups Sponsor
--------------------~--> 
Home is just a click away.  Make Yahoo! your home page now.
http://us.click.yahoo.com/DHchtC/3FxNAA/yQLSAA/saFolB/TM

------------------------------------------------------------
--------~-> 

Archives up to August 22, 2005 are also downloadable at http://www.connettivo.net/cntprojects/ocaml_beginners/
The archives of the very official ocaml list (the seniors'
one) can be found at http://caml.inria.fr
Attachments are banned and you're asked to be polite, avoid
flames etc. 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http:/
/groups.yahoo.com/group/ocaml_beginners/

<*> To unsubscribe from this group, send an email to:
    ocaml_beginners-unsubscribe@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.c
om/info/terms/
 

Jonathan Roewen a écrit :
> Seems your problem is your arguments to ocamldoc.

[...] <code> [...]

> Note no -html option, as foo_tag.cmo is itself a
generator.
>
> I think what is happening is that specifying -html
after -g option,
> the custom generator is getting replaced with the html
generator,
> which knows nothing of your custom tag, resulting in
your problems.
>
> I've tested this, and the above indeed works.
>
> Jonathan

Yes, now it does work !
Thanks a lot 

In the documentation it is writen :
   ocamldoc -g custom.cmo <other-options>
<source-files>
so in 'other-options' I was using the same options than
previously without the 
custom ocamldoc generator.


-- 


------------------------ Yahoo! Groups Sponsor
--------------------~--> 
Protect your PC from spy ware with award winning anti spy
technology. It's free.
http://us.click.yahoo.com/97bhrC/LGxNAA/yQLSAA/saFolB/TM

------------------------------------------------------------
--------~-> 

Archives up to August 22, 2005 are also downloadable at http://www.connettivo.net/cntprojects/ocaml_beginners/
The archives of the very official ocaml list (the seniors'
one) can be found at http://caml.inria.fr
Attachments are banned and you're asked to be polite, avoid
flames etc. 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http:/
/groups.yahoo.com/group/ocaml_beginners/

<*> To unsubscribe from this group, send an email to:
    ocaml_beginners-unsubscribe@yahoogroups.com

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.c
om/info/terms/