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 RAA21214; Wed, 10 Oct 2001 17:12:39 +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 RAA21195 for ; Wed, 10 Oct 2001 17:12:38 +0200 (MET DST) Received: from saul.cis.upenn.edu (SAUL.CIS.UPENN.EDU [158.130.12.4]) by concorde.inria.fr (8.11.1/8.10.0) with ESMTP id f9AFCZ104023; Wed, 10 Oct 2001 17:12:36 +0200 (MET DST) Received: from localhost (localhost [127.0.0.1]) by saul.cis.upenn.edu (8.10.1/8.10.1) with SMTP id f9AFCHx13599; Wed, 10 Oct 2001 11:12:17 -0400 (EDT) To: Sven cc: Dave Berry , Maxence Guesdon , Jerome Vouillon , Francois Pottier , caml-list@inria.fr Reply-to: bcpierce@cis.upenn.edu Subject: Re: [Caml-list] Re: [Caml-announce] OCamldoc In-reply-to: Your message of Wed, 10 Oct 2001 15:33:39 +0200. <20011010153339.C3177@dpt-info.u-strasbg.fr> Date: Wed, 10 Oct 2001 11:12:17 EDT Message-ID: <13596.1002726737@saul.cis.upenn.edu> From: "Benjamin C. Pierce" Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk > Personnaly, i would be very strongly against using indentation to define if > the stuff is before or after, after all, not everyone wants to indent things > the same way. Is there *anyone* that wants to write (* Comment for f *) val f : t (* Comment for f *) val g : t' ? These are the only people that should be unhappy with my proposed rule. > The (*< and (*> idea seems good and very intuitive. what is the reproch > against it you have ? I don't want all sorts of funny characters lying around in my comments when I read/write .mli files. It's very easy for this sort of tool to get out of control and turn the source files into full-blown markup language that can be used to produce all sorts of cool and powerful effects in the docs, but that looks ugly when you read it in the text editor. So I'm resisting taking even one step onto the slippery slope. What I'd really like to have is - A rule for distinguishing "documentation comments" from all other comments - A way of marking "OCaml stuff" when it occurs inside comments, e.g. by enclosing it in square brackets, so that the doc tool knows to set it in a different font (and can maybe try to parse it, find identifiers, index, hyperlink, etc.) - That's all! >>From the OCamlDoc manual, I see that the present design of the tool does, in fact, go quite a few steps further than the point where I could have stopped. Instead of putting in all these little markup commands, I would have preferred a single marker meaning "escape to raw hevea [or whatever] and let me do whatever I want at this point." This provides all the power that one could ever need, but discourages people from using it more than occasionally -- a Good Thing. However, I think the current design is actually a pretty reasonable compromise between what I want and what other (more feature-loving :-) people might like. It allows me to produce *reasonable* docs with *simple* (and not very ugly) mechanisms, while allowing others to produce pretties docs at some cost in ugliness of the sources. Please let's try to keep this property! Benjamin ------------------- Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/ To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr