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.2 required=5.0 tests=AWL,SPF_NEUTRAL autolearn=disabled version=3.1.3 X-Original-To: caml-list@yquem.inria.fr Delivered-To: caml-list@yquem.inria.fr 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 CA90ABB84 for ; Mon, 9 Feb 2009 18:27:00 +0100 (CET) X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AnoCAG72j0lDWxLCbmdsb2JhbACBbpJLPq5mhEGISoQaBg X-IronPort-AV: E=Sophos;i="4.37,406,1231110000"; d="scan'208";a="23808768" Received: from ip67-91-18-194.z18-91-67.customer.algx.net (HELO server1.bertec.net) ([67.91.18.194]) by mail1-smtp-roc.national.inria.fr with ESMTP; 09 Feb 2009 18:27:00 +0100 Received: from pc54.bertec.net (pc54.bertec.net [192.168.2.54]) by server1.bertec.net (Postfix) with ESMTP id DE7FF10575C for ; Mon, 9 Feb 2009 12:26:58 -0500 (EST) Message-Id: <529134A7-94A7-4E0F-BB1E-93A0ADE0FD49@osu.edu> From: Kuba Ober To: caml-list@yquem.inria.fr In-Reply-To: <3F6E6CB5-4609-49CE-BCFB-AD609B4BDD78@erratique.ch> Content-Type: text/plain; charset=ISO-8859-1; format=flowed; delsp=yes Content-Transfer-Encoding: quoted-printable Mime-Version: 1.0 (Apple Message framework v930.3) Subject: Re: ocamlbuild documentation (was Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3) Date: Mon, 9 Feb 2009 12:26:58 -0500 References: <1233936696.6216.65.camel@Blefuscu> <200902071458.45000.jon@ffconsultancy.com> <498FF839.6090901@lri.fr> <499018C2.9080007@lri.fr> <499026F9.3030708@lri.fr> <997E6911-3D37-4FAA-A958-757AD21A9F4D@erratique.ch> <49902E11.2010101@lri.fr> <0520EBEC-B30C-4D83-9153-A72BC3C986BF@erratique.ch> <499036C6.5070504@lri.fr> <499037FA.1090603@lri.fr> <3F6E6CB5-4609-49CE-BCFB-AD609B4BDD78@erratique.ch> X-Mailer: Apple Mail (2.930.3) X-Spam: no; 0.00; ocaml:01 makefiles:01 texinfo:01 gnuplot:01 pointers:01 ocaml's:01 'higher:01 locality:01 ocaml:01 syntax:01 syntax:01 pervasives:01 plural:01 foo:01 baz:01 > Le 9 f=E9vr. 09 =E0 15:04, Romain Bardou a =E9crit : > >> However, there ARE some examples in the part which talks about =20 >> "flag", where we clearly see an usage (After_rules). > > Which doesn't mean it cannot be used differently. > > Anyway it seems useless arguing further: we just don't have the same =20= > standards. > > The only thing I see is that there are still a lot of mentions to =20 > makefiles on this list and a lot of new projects don't use =20 > ocamlbuild while ocamlbuild is clearly a superior alternative. The =20 > only way I can explain this is by lack of good documentation. I'd argue that make's documentation is no better. The TeXinfo pages =20 distributed with GNU make are useful as a reference, but if you don't =20= use make much it's a big pain. A good manual IMHO should essentially =20 have two parts: first is a narrative introduction of all features, =20 with good examples. Second is a reference section where each command/=20 setting/UI element is documented in detail. I have to use make and similarly documented tools (say gnuplot) about =20= 40% of any given 12 month period. I waste lots of time looking for =20 same information over and over... simply because it's *documented* but =20= in some hard-to-get-to corner of the hypertext tree. Even Octave's =20 manual, though more conventional in style, is still written in such a =20= way that there are no pointers to most common features if all you do =20 is look at the contents table... OCaml's manual is, unfortunately, in the same class. For someone who =20 is not a devoted, full-time user, it's virtually useless. Unless you =20 know the term/keyword you're looking for, there's no way to find it =20 short of going through the whole thing page-by-page. Such manuals are designed to adhere to some 'higher deity' "standards" =20= of organization, which make them useful to robots perhaps, but nut to =20= humans. There's utter lack of locality of reference. The authors also =20= somehow abhor saying things out like they are. Instead of "just saying =20= it", the sprinkle the information all over the place, in places you'd =20= least expect to find it. Suppose I haven't used lists in OCaml much and would like to refresh =20 my memory. There's a sparse "introduction" to them in section 1.2. =20 List.map is "introduced" in 1.3; List.assoc in 1.6. The syntax of list =20= constants (ekhm, sorry, they are called list expressions) is basically =20= assumed. The list type syntax is given in 19.1. The list concatenation =20= operator is given in Module Pervasives documentation, in the "List =20 operations" section. Why the plural? -- beats me. And then there's the =20= List Module which gives the rest of it. There's no single place that =20 actually gives list syntax and explicitly says: dude, a list is =20 written as [ foo; bar; baz ]. Section 6.7 gives expression syntax, =20 which includes list expressions, but the *narrative* of list syntax is =20= given in -- of all places -- section 6.7.2 "operations on data =20 structures", under the heading "Variants". All in all, this is a good =20= WTF of a manual. Lisp's hyperspec is, after some getting used to, a better "manual" =20 than OCaml's "manual" is. Even though a specification is typically =20 unfit for daily consumption, at least it's reasonably self-consistent, =20= so once you figure out how it's structured, you'll find things where =20 you expect to find them. This doesn't address the locality of =20 reference (there's hardly any) and similar maladies, but at least it =20 doesn't suffer from lack of self-consistency. It's a bad manual, but =20 at least everywhere it's bad just the same. OCaml's manual is bad in =20 many different ways, but not always, and not at the same time. This =20 actually make's it even worse... Jon's "OCaml for Scientists" is written more in the way a manual would =20= be written, but Jon didn't intend to write a manual in the first =20 place, so I cannot blame him that the book isn't really useable as a =20 full-blown manual. It does its prescribed job just fine, though. If there's a good manual I had first-hand experience with, it must be =20= the one that came with Borland's Turbo Pascal. It was entirely clear =20 and understandable back when I was in elementary school. This is in =20 spite of my English being pretty elementary too, back then. Not only =20 was all the information I ever needed in the manual, but it included =20 all the nitty-gritty details you needed to interface to Pascal code =20 from assembly, and the other way around. Down to the layout of =20 compiler-generated stuff (vtables, packing, etc). It was also included =20= in the on-line help system, and there the hypertext navigation =20 actually made it more accessible/navigable. Must be one of the very =20 few manuals which were originally written on paper, and then meshed =20 with hypertext while improving usability. I can only give Borland's =20 doc team from back then highest praise. Writing good documentation takes skills which don't necessarily mesh =20 with skills of an accomplished software engineer. It's an added bonus =20= if a software engineer/scientist is a good documentation writer, but =20 that's very, very rare. There are many either excellent or pretty =20 decent open source tools that desperately need a manual written by =20 someone who knows how to do it. The authors are good at making the =20 tools, but their technical writing skills leave a lot to be desired. =20 I'm referencing stuff that I use: OCaml, make, autotools, Octave, =20 gnuplot, Maxima, ... Cheers, Kuba=