File inclusion with Ocamldoc

File inclusion with Ocamldoc

[Dario Teixeira]

Hi,

I want to create a customised APIDOC starter page that includes
links to child pages containing various tutorials for the API.
Now, Ocamldoc already has a -intro option that allows an external
file to be used as an APIDOC starter page.  But I see no way
to create a link to an external file from within this starter
page, and to tell Ocamldoc to also process and include the
external file.  Does someone know of a straightforward solution
for this problem?

Thanks!
Dario Teixeira

Re: [Caml-list] File inclusion with Ocamldoc

[Maxence Guesdon]

Dario Teixeira <darioteixeira@yahoo.com> a ?it :

> Hi,

Hello,

> I want to create a customised APIDOC starter page that includes
> links to child pages containing various tutorials for the API.
> Now, Ocamldoc already has a -intro option that allows an external
> file to be used as an APIDOC starter page.  But I see no way
> to create a link to an external file from within this starter
> page, and to tell Ocamldoc to also process and include the
> external file.  Does someone know of a straightforward solution
> for this problem?

You can use .txt files to do this. Simply type ocamldoc comment  
(without (** *)) in a file.txt file and pass it to ocamldoc like any  
.ml or .mli file. This will be considered as a File module and you can  
refer to it by {!File} from any ocamldoc comment.

Example:
cat > file.txt
This is the {!File} file.

ocamldoc -html file.txt


Hope this helps,

Maxence Guesdon

> Thanks!
> Dario Teixeira
>
>
>
>
>
> _______________________________________________
> Caml-list mailing list. Subscription management:
> http://yquem.inria.fr/cgi-bin/mailman/listinfo/caml-list
> Archives: http://caml.inria.fr
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
>



----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.

Re: [Caml-list] File inclusion with Ocamldoc

[Dario Teixeira]

Hi,

> You can use .txt files to do this. Simply type ocamldoc
> comment  (without (** *)) in a file.txt file and pass it to
> ocamldoc like any  .ml or .mli file. This will be considered
> as a File module and you can refer to it by {!File} from any
> ocamldoc comment.

Excellent!  Thanks for the tip.  Incidentally, the 3.10 version
of Ocamlbuild does not support the generation of documentation
from implementation files.  Will 3.11 fix this?

Cheers,
Dario

Re: [Caml-list] File inclusion with Ocamldoc

[Romain Bardou]

>> You can use .txt files to do this. Simply type ocamldoc
>> comment  (without (** *)) in a file.txt file and pass it to
>> ocamldoc like any  .ml or .mli file. This will be considered
>> as a File module and you can refer to it by {!File} from any
>> ocamldoc comment.
> 
> Excellent!  Thanks for the tip.  Incidentally, the 3.10 version
> of Ocamlbuild does not support the generation of documentation
> from implementation files.  Will 3.11 fix this?

It works for me with the 3.10.1. I just tried to write a file test.ml, 
and a file truc.odocl with "Test" in it, and then ran ocamlbuild :
	ocamlbuild truc.docdic/index.html
And it worked. Or maybe I didn't understand what you want?

-- 
Romain Bardou

Re: [Caml-list] File inclusion with Ocamldoc

[Dario Teixeira]

Hi,

> It works for me with the 3.10.1. I just tried to write a
> file test.ml, and a file truc.odocl with "Test" in it, and then
> ran ocamlbuild :
> 	ocamlbuild truc.docdic/index.html
> And it worked. Or maybe I didn't understand what you want?

You're right.  I took the Ocamlbuild manual at face value, since
it states it cannot handle implementation files.  Nevertheless,
I'm still running into some problems with Ocamlbuild+Ocamldoc.
First, while Ocamldoc will by default merge the comments from .ml
and .mli files (with precedence given to the .mli file, unless
-inv-merge-ml-mli is given), when I use Ocamlbuild to generate
the documentation I notice the following pattern: if only the .ml
file is present then it's used for generating the documentation;
If, however, both .ml and .mli are present, then only the .mli
is taken into account (no merging is done).  Second, how does one
tell Ocamlbuild to include .txt files in the documentation?

Thanks again for your attention,
Dario Teixeira

Re: [Caml-list] File inclusion with Ocamldoc

[Nicolas Pouillard]

Excerpts from Dario Teixeira's message of Wed Oct 15 16:43:32 +0200 2008:
> Hi,
> 
> > It works for me with the 3.10.1. I just tried to write a
> > file test.ml, and a file truc.odocl with "Test" in it, and then
> > ran ocamlbuild :
> >     ocamlbuild truc.docdic/index.html
> > And it worked. Or maybe I didn't understand what you want?
> 
> You're right.  I took the Ocamlbuild manual at face value, since
> it states it cannot handle implementation files.  Nevertheless,
> I'm still running into some problems with Ocamlbuild+Ocamldoc.
> First, while Ocamldoc will by default merge the comments from .ml
> and .mli files (with precedence given to the .mli file, unless
> -inv-merge-ml-mli is given), when I use Ocamlbuild to generate
> the documentation I notice the following pattern: if only the .ml
> file is present then it's used for generating the documentation;
> If, however, both .ml and .mli are present, then only the .mli
> is taken into account (no merging is done).  Second, how does one
> tell Ocamlbuild to include .txt files in the documentation?

The manual states that implementation files are not handled because if you
have a .ml and .mli then ocamlbuild will choose the .mli.

-- 
Nicolas Pouillard aka Ertai

Re: [Caml-list] File inclusion with Ocamldoc

[Dario Teixeira]

Hi,

> The manual states that implementation files are not handled
> because if you have a .ml and .mli then ocamlbuild will choose
> the .mli.

Thanks for the info.  You may want to clarify that on the manual,
because presently the language implies that implementation files
are ignored altogether.

Also, I'm having trouble getting Ocamlbuild/Ocamldoc working
on a project that also uses mlpack.  Basically, I have a "lambdoc" directory containing a number of modules whose
documentation I want to generate.  I also have lambdoc.mlpack
listing all those modules, and a lambdoc.mllib containing only
"Lambdoc".

In these circumstances, what should be the contents of the
lambdoc.odocl file?  I tried listing lambdoc's modules, both
fully qualified (eg, "Lambdoc.Document_ast") and not, but
Ocamlbuild always chokes.  Also, what is the rule of .odoc
files and how do they differ from .odocl?

Thanks for your time,
Dario Teixeira