How to tell ocamlbuild to pass options to ocamldoc?

How to tell ocamlbuild to pass options to ocamldoc?

[Andrej Bauer]

Perhaps I am just blind, but I was unable to figure out after poking
around for a while, how to tell ocamlbuild that it should pass the
-keep-code flag to ocamldoc. I suspect I need to put something in _tags,
but what? (I am an ocamlbuild newbie.)

Andrej

Re: [Caml-list] How to tell ocamlbuild to pass options to ocamldoc?

[Paolo Donadeo]

> Perhaps I am just blind, but I was unable to figure out after poking
>  around for a while, how to tell ocamlbuild that it should pass the
>  -keep-code flag to ocamldoc. I suspect I need to put something in _tags,
>  but what? (I am an ocamlbuild newbie.)

I don't know if this is the best way, but I use the myocamlbuild
module to pass arguments to ocamlfind and ocamldoc, it just works.

An example:

=============== myocamlbuild.ml ===============
open Ocamlbuild_plugin;;
open Command;;

let (|>) x f = f x

let packages =
  [
    "cryptokit";
    "extlib";
    "netcgi2";
    "netcgi2-plex";
    "nethttpd";
    "netplex";
    "netstring";
    "oUnit";
    "pxp-engine";
    "pxp-lex-iso88591";
    "str";
    "unix"
  ] |> String.concat ",";;

let ocamlfind cmd = S[A"ocamlfind"; A cmd; A"-package"; A packages];;

flag ["ocaml"; "link"] (A"-linkpkg");;

let ocamldoc =
  S[A"ocamlfind";
    A"ocamldoc";
    A"-package";
    A packages;
    A"-stars";
    A"-colorize-code";
    A"-intro"; A"../documentation/doc_index.txt";
    A"-css-style"; A"../documentation/style.css";
    A"-t"; A"The Ex-nunc System";
  ];;

dispatch begin function
  | After_options ->
      Options.ocamldoc := ocamldoc;
      Options.ocamlc := ocamlfind "ocamlc";
      Options.ocamlopt := ocamlfind "ocamlopt";
  | _ -> ()
end
=========== END OF myocamlbuild.ml ============



-- 
Paolo Donadeo
Studio Associato 4Sigma
Website:  http://www.4sigma.it
Email:    p.donadeo@4sigma.it
~
~
:wq

Re: [Caml-list] How to tell ocamlbuild to pass options to ocamldoc?

[Romain Bardou]

I didn't find any tag for the -keep-code flag. So indeed, I guess you 
need a plugin. I would suggest adding the flag for tags "ocaml" and 
"doc" (other useful tags are: interf, implem, extension:html, 
extension:tex and so on, docfile, docdir).

Something like this:

open Ocamlbuild_plugin;;

dispatch begin function
   | After_rules ->
       flag ["ocaml"; "doc"] "-keep-code"
end

I didn't test it though.

	Romain Bardou

Paolo Donadeo a écrit :
>> Perhaps I am just blind, but I was unable to figure out after poking
>>  around for a while, how to tell ocamlbuild that it should pass the
>>  -keep-code flag to ocamldoc. I suspect I need to put something in _tags,
>>  but what? (I am an ocamlbuild newbie.)
> 
> I don't know if this is the best way, but I use the myocamlbuild
> module to pass arguments to ocamlfind and ocamldoc, it just works.
> 
> An example:
> 
> =============== myocamlbuild.ml ===============
> open Ocamlbuild_plugin;;
> open Command;;
> 
> let (|>) x f = f x
> 
> let packages =
>   [
>     "cryptokit";
>     "extlib";
>     "netcgi2";
>     "netcgi2-plex";
>     "nethttpd";
>     "netplex";
>     "netstring";
>     "oUnit";
>     "pxp-engine";
>     "pxp-lex-iso88591";
>     "str";
>     "unix"
>   ] |> String.concat ",";;
> 
> let ocamlfind cmd = S[A"ocamlfind"; A cmd; A"-package"; A packages];;
> 
> flag ["ocaml"; "link"] (A"-linkpkg");;
> 
> let ocamldoc =
>   S[A"ocamlfind";
>     A"ocamldoc";
>     A"-package";
>     A packages;
>     A"-stars";
>     A"-colorize-code";
>     A"-intro"; A"../documentation/doc_index.txt";
>     A"-css-style"; A"../documentation/style.css";
>     A"-t"; A"The Ex-nunc System";
>   ];;
> 
> dispatch begin function
>   | After_options ->
>       Options.ocamldoc := ocamldoc;
>       Options.ocamlc := ocamlfind "ocamlc";
>       Options.ocamlopt := ocamlfind "ocamlopt";
>   | _ -> ()
> end
> =========== END OF myocamlbuild.ml ============
> 
> 
> 

Re: [Caml-list] How to tell ocamlbuild to pass options to ocamldoc?

[Nicolas Pouillard]

[-- Attachment #1: Type: text/plain, Size: 2436 bytes --]

Excerpts from Romain Bardou's message of Mon Mar 03 09:05:24 +0100 2008:
> I didn't find any tag for the -keep-code flag. So indeed, I guess you 
> need a plugin. I would suggest adding the flag for tags "ocaml" and 
> "doc" (other useful tags are: interf, implem, extension:html, 
> extension:tex and so on, docfile, docdir).
> 
> Something like this:
> 
> open Ocamlbuild_plugin;;
> 
> dispatch begin function
>    | After_rules ->
>        flag ["ocaml"; "doc"] "-keep-code"
> end

Thanks Romain,

You can also be less global by adding a new tag "keep_code":

==============
open Ocamlbuild_plugin;;

dispatch begin function
  | After_rules ->
      flag ["ocaml"; "doc"; "keep_code"] "-keep-code"
end
==============

And then in your _tags

<foo.ml>: keep_code

Cheers,

> Paolo Donadeo a écrit :
> >> Perhaps I am just blind, but I was unable to figure out after poking
> >>  around for a while, how to tell ocamlbuild that it should pass the
> >>  -keep-code flag to ocamldoc. I suspect I need to put something in _tags,
> >>  but what? (I am an ocamlbuild newbie.)
> > 
> > I don't know if this is the best way, but I use the myocamlbuild
> > module to pass arguments to ocamlfind and ocamldoc, it just works.
> > 
> > An example:
> > 
> > =============== myocamlbuild.ml ===============
> > open Ocamlbuild_plugin;;
> > open Command;;
> > 
> > let (|>) x f = f x
> > 
> > let packages =
> >   [
> >     "cryptokit";
> >     "extlib";
> >     "netcgi2";
> >     "netcgi2-plex";
> >     "nethttpd";
> >     "netplex";
> >     "netstring";
> >     "oUnit";
> >     "pxp-engine";
> >     "pxp-lex-iso88591";
> >     "str";
> >     "unix"
> >   ] |> String.concat ",";;
> > 
> > let ocamlfind cmd = S[A"ocamlfind"; A cmd; A"-package"; A packages];;
> > 
> > flag ["ocaml"; "link"] (A"-linkpkg");;
> > 
> > let ocamldoc =
> >   S[A"ocamlfind";
> >     A"ocamldoc";
> >     A"-package";
> >     A packages;
> >     A"-stars";
> >     A"-colorize-code";
> >     A"-intro"; A"../documentation/doc_index.txt";
> >     A"-css-style"; A"../documentation/style.css";
> >     A"-t"; A"The Ex-nunc System";
> >   ];;
> > 
> > dispatch begin function
> >   | After_options ->
> >       Options.ocamldoc := ocamldoc;
> >       Options.ocamlc := ocamlfind "ocamlc";
> >       Options.ocamlopt := ocamlfind "ocamlopt";
> >   | _ -> ()
> > end
> > =========== END OF myocamlbuild.ml ============
> > 
> > 
> > 
> 

-- 
Nicolas Pouillard aka Ertai

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 194 bytes --]

Re: [Caml-list] How to tell ocamlbuild to pass options to ocamldoc?

[Andrej Bauer]

>> open Ocamlbuild_plugin;;
>>
>> dispatch begin function
>>    | After_rules ->
>>        flag ["ocaml"; "doc"] "-keep-code"
>> end

This gives me an error.

> You can also be less global by adding a new tag "keep_code":

In my case I am happy to be "global". I ended up with:

open Ocamlbuild_plugin ;;

dispatch begin function
  | After_options ->
      Options.ocamldoc :=
        S[
          A"ocamldoc";
          A"-keep-code";
          A"-colorize-code"
        ]
  | _ -> ()
end

This feels "too global" though.

Maybe I should explain the background. I am composing a library of small
examples from programming language theory. A typical example consists of
about 300 lines of code (including ocamllex and ocamlyacc). I want it to be:

(1) as easy to compile as possible: I decided to use ocamlbuild but I
also provide a Makefile which runs ocamlbuild and a README.txt
explaining how to compile. The only drawback is that this requires a
fairly new version of ocaml.

(2) I want to publish the code on the web in browsable format. I think I
will do it two ways: as generated by ocamldoc (which is why I wanted
"-keep-code"). and as raw code converted to HTML with caml2html (because
ocamldoc doesn't do .mly and .mll).

Since I am already talking about ocamlbuild, I should point out that I
used it for teaching last semester. The main challenge was coping with
Windows environment which cannot handle symbolic links. (And we used
OcaIDE, too. The "development environment" kind of worked, and was much
much less hassle than xemacs+make).

Thank you again.

Andrej

Re: [Caml-list] How to tell ocamlbuild to pass options to ocamldoc?

[Nicolas Pouillard]

[-- Attachment #1: Type: text/plain, Size: 1902 bytes --]

Excerpts from andrej.bauer's message of Mon Mar 03 22:59:39 +0100 2008:
> >> open Ocamlbuild_plugin;;
> >>
> >> dispatch begin function
> >>    | After_rules ->
> >>        flag ["ocaml"; "doc"] "-keep-code"
> >> end
> 
> This gives me an error.

Yes, in fact it's:

 flag ["ocaml"; "doc"] (A"-keep-code")

> > You can also be less global by adding a new tag "keep_code":
> 
> In my case I am happy to be "global". I ended up with:
> 
> open Ocamlbuild_plugin ;;
> 
> dispatch begin function
>   | After_options ->
>       Options.ocamldoc :=
>         S[
>           A"ocamldoc";
>           A"-keep-code";
>           A"-colorize-code"
>         ]
>   | _ -> ()
> end
> 
> This feels "too global" though.
> 
> Maybe I should explain the background. I am composing a library of small
> examples from programming language theory. A typical example consists of
> about 300 lines of code (including ocamllex and ocamlyacc). I want it to be:
> 
> (1) as easy to compile as possible: I decided to use ocamlbuild but I
> also provide a Makefile which runs ocamlbuild and a README.txt
> explaining how to compile. The only drawback is that this requires a
> fairly new version of ocaml.
> 
> (2) I want to publish the code on the web in browsable format. I think I
> will do it two ways: as generated by ocamldoc (which is why I wanted
> "-keep-code"). and as raw code converted to HTML with caml2html (because
> ocamldoc doesn't do .mly and .mll).
> 
> Since I am already talking about ocamlbuild, I should point out that I
> used it for teaching last semester. The main challenge was coping with
> Windows environment which cannot handle symbolic links. (And we used
> OcaIDE, too. The "development environment" kind of worked, and was much
> much less hassle than xemacs+make).

Yes windows support needs more care. Glad to hear that you've make it worked.

Best regards,

-- 
Nicolas Pouillard aka Ertai

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 194 bytes --]

Re: [Caml-list] How to tell ocamlbuild to pass options to ocamldoc?

[Andrej Bauer]

Nicolas Pouillard wrote:
> Yes, in fact it's:
> 
>  flag ["ocaml"; "doc"] (A"-keep-code")

Thanks. Alas, I've given up on using ocamldoc with -keep-code because an
 essential part of the (educational) code is the lexer and the parser. I
will just use caml2html. Stay tuned for a "PL Zoo".

Best regards,

Andrej