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=1.3 required=5.0 tests=AWL,SPF_SOFTFAIL autolearn=disabled version=3.1.3 X-Original-To: caml-list@yquem.inria.fr Delivered-To: caml-list@yquem.inria.fr Received: from mail4-relais-sop.national.inria.fr (mail4-relais-sop.national.inria.fr [192.134.164.105]) by yquem.inria.fr (Postfix) with ESMTP id A0DBFBC37 for ; Mon, 14 Sep 2009 15:40:11 +0200 (CEST) X-IronPort-AV: E=Sophos;i="4.44,383,1249250400"; d="scan'208";a="46539793" Received: from espone.inrialpes.fr (HELO [194.199.21.24]) ([194.199.21.24]) by mail4-relais-sop.national.inria.fr with ESMTP/TLS/DHE-RSA-AES256-SHA; 14 Sep 2009 15:40:11 +0200 Message-ID: <4AAE46EB.1010706@inrialpes.fr> Date: Mon, 14 Sep 2009 15:36:43 +0200 From: Bertrand Jeannet User-Agent: Mozilla Thunderbird 1.0.2-6 (X11/20050513) X-Accept-Language: en-us, en MIME-Version: 1.0 To: caml-list@yquem.inria.fr Subject: Re: Ocamldoc and multiple packages References: <20090911220901.C8F36BCB1@yquem.inria.fr> In-Reply-To: <20090911220901.C8F36BCB1@yquem.inria.fr> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Spam: no; 0.00; jeannet:01 jeannet:01 inrialpes:01 ocamldoc:01 ocamldoc:01 ocaml:01 ocaml:01 -for-pack:01 -pack:01 -load:01 arises:01 -pack:01 cheers:01 mli:01 mli:01 > ------------------------------------------------------------------------ > > Subject: > [Caml-list] Ocamldoc and multiple packages > From: > Alexey Rodriguez > Date: > Fri, 11 Sep 2009 17:47:09 +0200 > To: > OCaml List > > To: > OCaml List > > > Dear list, > > I am trying to build ocamldoc documentation for an ocaml project that > contains multiple packages (collections of modules built using > -for-pack and -pack). My current setup generates documentation for > each package but it won't generate hyperlinks to modules in other > packages (module not found errors). I tried using the -load and -dump > commands to allow ocamldoc see the ocamldoc-results of the referred to > package, but I still get problems. I suspect that the problem arises > because ocamldoc does not have a -pack option, so it always sees > modules in a flat way. So if you have package Pack1 with module A, and > module B in Pack2 which refers to Pack1.A.t, ocamldoc cannot solve > this reference because it does not know that module A is inside > another module called Pack1. > > The solutions I see right now seem to involve more effort than I am > willing to spend. So, before I embark on a task that might take too > long I would like to ask for tips on this. How do you perform ocamldoc > generation for projects with multiple packages? Thanks! > > Cheers, > > Alexey > I wrote very recently a small script that packs source modules into a big module, and takes care of ocamldoc convention, which is to interpret in each file the first (** *) comment as the title associated to the module. I am very bad at sh and gawk script, so the result (given below) is not very elegant... It would of course be better (and much more robust) to have a direct support in ocamldoc. Bertrand ----------- #/bin/sh # command line (very primitive...) if test $1 != "-o"; then echo "ocamlpack: usage: ocamlpack -o outputmodule -title module1 module2 ..." exit -1 fi shift out=$1 shift if test $1 != "-title"; then echo "ocamlpack: usage: ocamlpack -o outputmodule -title module1 module2 ..." exit -1 fi shift outtitle=$1 shift # prepare output /bin/rm -f $out.ml $out.mli echo "(** $outtitle *)">$out.ml echo "(** $outtitle *)">$out.mli # iterate on input module, for i in $*; do name=$i # 1.A Look for the first (** *) comment, and output it to out.ml # (see ocamldoc convention) gawk -v name=$name ' BEGIN { start=1 # isolate module name from path/modulename nb = split(name, dirname, "/") name = dirname[nb] if (RLENGTH>0) name = substr(name,RINDEX,length(name)-RINDEX) # Capitalize the module name hd = toupper(substr(name,1,1)) tl = substr(name,2,length(name)-1) } # Look for the first (** *) comment, and output it { if (start==1) { match($0, /\(\*\*([ ]+)([^*]*)([ ]+)\*\)/ ) if (RLENGTH>0){ start=0 title=substr($0,RSTART+4,RLENGTH-7) print "\n(** {1 Module [",hd tl "]:",title "} *)\n" print "module",hd tl,"= struct" } } } END { if (start==1) { print "\n(** {1 Module [",hd tl "]} *)\n" print "module",hd tl,"= struct" } } ' $i.ml >>$out.ml # 1.B Output the rest of name.ml to out.ml gawk -v name=$name ' { if (start==1) { match($0, /\(\*\*([ ]+)([^*]*)([ ]+)\*\)/ ) if (RLENGTH>0) start=0 else print $0 } else print " ",$0 } END { print "end\n" } ' $i.ml >>$out.ml # 2.A Look for the first (** *) comment, and output it to out.mli gawk -v name=$name ' BEGIN { start=1 nb = split(name, dirname, "/") name = dirname[nb] if (RLENGTH>0) name = substr(name,RINDEX,length(name)-RINDEX) hd = toupper(substr(name,1,1)) tl = substr(name,2,length(name)-1) } { if (start==1) { match($0, /\(\*\*([ ]+)([^*]*)([ ]+)\*\)/ ) if (RLENGTH>0){ start=0 title=substr($0,RSTART+4,RLENGTH-7) print "\n(** {1 Module [",hd tl "]:",title "} *)\n" print "module",hd tl,": sig" } } } END { if (start==1) { print "\n(** {1 Module [",hd tl "]} *)\n" print "module",hd tl,": sig" } } ' $i.mli >>$out.mli # 2.B Output the rest of name.mli to out.mli gawk -v name=$name ' { if (start==1) { match($0, /\(\*\*([ ]+)([^*]*)([ ]+)\*\)/ ) if (RLENGTH>0) start=0 else print $0 } else print " ",$0 } END { print "end\n" } ' $i.mli >>$out.mli done