Re: ocamldoc generation and packed files

[Thomas Gazagnaire <thomas.gazagnaire@xxxxxxxxx>]

No ocamlbuild integration yet but would be definitely useful to add. I
can have a look at integrating it to mirage build next week if it's
useful.

--
Thomas

2011/8/13 Anil Madhavapeddy <anil@xxxxxxxxxx>:
> Thanks Thomas, that looks very useful and definitely better than the script 
> in tree at the moment.
>
> One question: ocp-pack also requires that the list of files be passed in 
> dependency order, or else the resulting pack file will not compile.  Have you 
> tried to integrate it as an ocamlbuild rule, so that it can automatically 
> sort the input modules before generates the packed file / functor?
>
> Anil
>
> On 12 Aug 2011, at 20:01, Thomas Gazagnaire wrote:
>
>> It will be anounced quite shortly on the ocaml mailing list, so I can
>> give you the link to ocp-pack :
>>
>> http://www.ocamlpro.com/code/2011-08-10-ocaml-pack-functors.html
>> http://www.ocamlpro.com/files/ocp-pack-1.0.0.tar.gz
>>
>> It should help you to pack modules easily and have a working doc.
>>
>> --
>> Thomas
>>
>> 2011/7/28 Anil Madhavapeddy <anil@xxxxxxxxxx>:
>>> That tool will be very useful! I've committed the 'make doc' target. The 
>>> output is still pretty dirty as we don't use the documentation tags 
>>> properly, but I'll go through adding .mli files and adding proper 
>>> documentation on the more stable interfaces.
>>>
>>> It would be quite nice to eventually have a single documentation output for 
>>> all the backends, with an addition section saying 'only present in Xen' or 
>>> 'only present in Node'. I think that should be possible by parsing the 
>>> ocamldoc dump outputs, but something for the future!
>>>
>>> Anil
>>>
>>> On 27 Jul 2011, at 16:56, Thomas Gazagnaire wrote:
>>>
>>>> We have as well a program which pack together ML files (and is able to 
>>>> functorize packs as well...) it is not released yet, but I guess we can 
>>>> open-source it shortly.
>>>>
>>>> But I think overriding the default rule for ocamldoc+pack in ocamlbuild is 
>>>> sufficient for now on so you should push your patch :-)
>>>>
>>>> Thomas
>>>>
>>>> On Jul 27, 2011, at 5:36 PM, Anil Madhavapeddy wrote:
>>>>
>>>>> I'd really like to generate ocamldoc (HTML/PDF) of all the various 
>>>>> libraries so that it's easier to learn Mirage (and support editor 
>>>>> auto-completion, etc).
>>>>>
>>>>> The big problem is that ocamldoc doesn't support packed modules, and we 
>>>>> use packing quite extensively (in Net, Http, Block, etc).
>>>>>
>>>>> So I've hacked up an ocamlbuild target that concats together the *source* 
>>>>> ML files from an .mlpack and uses that to generate the ocamldoc for the 
>>>>> standard library, with one set of HTML files generated per backend (Xen, 
>>>>> Net-Direct, Net-Socket, and so on).
>>>>>
>>>>> The issue is that these rules are a little grim: everywhere where we have 
>>>>> a .mlpack file at the moment, we need to override that rule to generate a 
>>>>> concatenated ML file that is used for ocamldoc (but not for actual 
>>>>> compilation, since line numbers get lost since those aren't preserved 
>>>>> when converting from ML files into a single big one).
>>>>>
>>>>> Does anyone have a better solution for ocamldoc and packed files? All of 
>>>>> the grimness here is hidden away in the ocamlbuild rules, so I'm inclined 
>>>>> to just commit this patch, and perhaps see about adding -pack support 
>>>>> into ocamldoc at a later stage (there's an open bug in Mantis somewhere).
>>>>>
>>>>> Dave, do you use pack in XAPI, and/or ocamldoc?  I wonder if everyone 
>>>>> else (like Core) also have their own swanky 'cat ML files into one' 
>>>>> script too...
>>>>>
>>>>> -anil
>>>>
>>>
>>>
>>
>
>