From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.1.3 (2006-06-01) on yquem.inria.fr X-Spam-Level: X-Spam-Status: No, score=0.1 required=5.0 tests=AWL autolearn=disabled version=3.1.3 Received: from mail1-relais-roc.national.inria.fr (mail1-relais-roc.national.inria.fr [192.134.164.82]) by yquem.inria.fr (Postfix) with ESMTP id 79C44BBAF for ; Tue, 2 Sep 2008 15:06:51 +0200 (CEST) X-IronPort-AV: E=Sophos;i="4.32,316,1217800800"; d="scan'208";a="16720956" Received: from alcazar.inria.fr ([128.93.24.50]) by mail1-relais-roc.national.inria.fr with ESMTP; 02 Sep 2008 15:06:51 +0200 Date: Tue, 2 Sep 2008 15:12:45 +0200 From: Maxence Guesdon To: David Teller Cc: Caml Subject: Re: [Caml-list] Two questions on OCamlDoc Message-ID: <20080902151245.2b3402b6@alcazar.inria.fr> In-Reply-To: <1220356028.6406.33.camel@Blefuscu> References: <1220356028.6406.33.camel@Blefuscu> Organization: INRIA X-Mailer: Claws Mail 3.5.0 (GTK+ 2.12.11; i486-pc-linux-gnu) Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-15 Content-Transfer-Encoding: quoted-printable X-Spam: no; 0.00; maxence:01 guesdon:01 maxence:01 guesdon:01 ocamldoc:01 univ-orleans:01 toying:01 ocamldoc:01 inlining:01 lib:01 lib:01 rework:01 clashes:01 overriding:01 mli:01 On Tue, 02 Sep 2008 13:47:08 +0200 David Teller wrote: > Hi everyone, Hello, > I'm currently toying with OCamlDoc, with very little success. I'm > attempting to do two things: > * getting OCamlDoc to understand that some modules (which I can modify) > contain the documentation for some other modules (which I can't) replace > some modules with others > * inlining the documentation for modules in modules which import those. >=20 > I need a little help. >=20 > Let me detail this. >=20 > *** Documentation replacement *** > My project uses modules M_lib1, M_lib2... which come from a variety of > libraries. For each of these modules, I have created a module > M_lib1_with_doc, M_lib2_with_doc, which imports the corresponding > library module but tailors the documentation to my project. However, for > technical reasons of mechanical generation, assuming that M_lib1 refers > to M_lib2, M_lib1_with_doc still refers to M_lib2 instead of referring > to M_lib2_with_doc. Consequently, when generating the documentation of > M_lib1_with_doc, ocamldoc doesn't link the generated pages to the > documentation of M_lib2_with_doc but rather attempts to link it to > M_lib2 (and fails, as expected). >=20 > Now, I could rework the mechanical generation of my modules and in time, > I will. However, for the moment, I'm looking for a purely OCamlDoc-based > solution. I'd like to be able to ask OCamlDoc to please consider every > reference to M_lib2 as actually meaning a reference to M_lib2_with_doc. >=20 > I have tried to override method [text#html_of_Ref], without much > success. Is there a simple solution for this? A simple way (but not always possible, due to name clashes) would be to use some script to perform string substitution in generated html files; in your example, replacing all "M_lib2" by "M_lib2_with_doc". you could indeed try to do this by overriding the method html_of_Ref. What problem do you encounter ? Another way would be to use some "cat" commands to create new "..._with_doc.ml" files, compile them and use your "..._with_doc.mli" as documented interface. > *** Inlining modules *** > I have a few modules whose sole role is to include one or two existing > modules. By default, when meeting [include], OCamlDoc, ocamldoc only > generates a link from the container module to the inlined module. In > this case, I'd rather want the whole documentation of each of these > modules to be inlined.=20 > > Is that possible? May be. You could try to override the method html_of_module_element so that, when you encounter a Element_included_module, you search the real module by its name and print its elements instead of just "include ...". Does this help ? Regards, Maxence --=20 Maxence Guesdon http://yquem.inria.fr/~guesdon/ Service Exp=E9rimentation et D=E9veloppements https://devel.inria.fr/rocq/ INRIA Paris-Rocquencourt http://www.inria.fr/rocquencourt/