From mboxrd@z Thu Jan 1 00:00:00 1970 Received: (from majordomo@localhost) by pauillac.inria.fr (8.7.6/8.7.3) id TAA25246; Fri, 11 May 2001 19:55:59 +0200 (MET DST) X-Authentication-Warning: pauillac.inria.fr: majordomo set sender to owner-caml-list@pauillac.inria.fr using -f Received: from concorde.inria.fr (concorde.inria.fr [192.93.2.39]) by pauillac.inria.fr (8.7.6/8.7.3) with ESMTP id TAA25242 for ; Fri, 11 May 2001 19:55:58 +0200 (MET DST) Received: from fledge.watson.org (fledge.watson.org [204.156.12.50]) by concorde.inria.fr (8.11.1/8.10.0) with ESMTP id f4BHqLf16878; Fri, 11 May 2001 19:53:32 +0200 (MET DST) Received: from localhost (patrick@localhost) by fledge.watson.org (8.11.3/8.11.3) with SMTP id f4BHUtF25585; Fri, 11 May 2001 13:30:55 -0400 (EDT) (envelope-from patrick@watson.org) Date: Fri, 11 May 2001 13:30:54 -0400 (EDT) From: Patrick M Doane To: Fabrice Le Fessant cc: caml-list@inria.fr Subject: Re: [Caml-list] CDK binary release In-Reply-To: <15099.54264.965247.51247@cremant.inria.fr> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk On Fri, 11 May 2001, Fabrice Le Fessant wrote: > > Out of curiosity, who wants to be reading Ocaml documentation through man > > pages? I would think HTML and texinfo would both be nicer formats to work > > with. Is there some advantage that I'm missing? > > You mean that, because you don't like man pages, nobody like them ? I like man pages, it just surprised me to see this as an output for documentation. I guess I would say that it doesn't seem consistent with current programming trends. AFAIK, man pages for programming APIs seem to only be produced for C libraries. > HTML is already supported, I have nothing against texinfo. But, do you > know a tool to generate it from all the mli files from the CDK (that > use different formatting conventions) ? Can you send me a patch to the > CDK to use it ? Are you sure it is installed on all computers that > will compile the CDK documentation ? ocamlweb/hevea generate info files nicely. Regarding the other questions, - In the long term, the .mli files in the CDK should use the same formatting conventions. I assume that the current differences exist because the effort is just getting started. Consistency, aside from documentation, is perhaps the weakest area of CDK right now. This is to be expected of course, designing a good library is hard! - If you would find it useful for me to patch CDK to work with ocamlweb/hevea, then let me know. I'll do the work over the weekend. To go a step further, if there's work that can be farmed out for CDK development, I'm sure many of us would want to help out. - I don't know what machines will be used to compile CDK documentation, but there is an easy solution which will guarantee that ocamlweb/hevea are present on those machines: add them to the CDK. This is similar to the current setup with cdk_doc. I'm not trying to advocate ocamlweb/hevea over cdk_doc. It is a tool combination that support info files though. > For LaTeX, we will not force people to use LaTeX to document their > interfaces: most comments are simple text lines including some pieces > of code (in cdk_doc, they simply have to be between brackets). Only > section titles have to be handled differently. cdk_doc is enough for > that. New output formats have to be added, and all interfaces have to > be completely translated to the input format ... We are not writting a > book, but only a reference manual, thus, we don't need SGML or > complicated formatting tool for that ! I think that the discussion thread for LaTeX/SGML is in a larger context than the needs of CDK. I will echo Markus's desire for there to be a documentation standard. This standard should be simple enough to meet the CDK needs, but also meet more complex formatting needs. Also, you are already using SGML to build the CDK documentation by using HTML. It's not a very good DTD to represent the content for style transformations, but it's a start. Defining a DTD for Caml documentation would be a very nice intermediate representation. Patrick ------------------- To unsubscribe, mail caml-list-request@inria.fr. Archives: http://caml.inria.fr