From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail1-relais-roc.national.inria.fr (mail1-relais-roc.national.inria.fr [192.134.164.82]) by walapai.inria.fr (8.13.6/8.13.6) with ESMTP id pA4BP7Uv026644 for ; Fri, 4 Nov 2011 12:25:07 +0100 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AvYBAOzKs07RVdU2kGdsb2JhbABEhHqiPIE1gRgIIgEBAQEJCQ0HFAQhgXIBAQEDARICDx0BOAEDAQsBBQULDwImAgIiEgEFARwGNYdgCJd5CosNgyiFMoktAgUKgSaGZYEWBJQcjTo9gUmCJw X-IronPort-AV: E=Sophos;i="4.69,455,1315173600"; d="scan'208";a="128376817" Received: from mail-yw0-f54.google.com ([209.85.213.54]) by mail1-smtp-roc.national.inria.fr with ESMTP/TLS/RC4-SHA; 04 Nov 2011 12:25:01 +0100 Received: by ywt32 with SMTP id 32so3475882ywt.27 for ; Fri, 04 Nov 2011 04:25:00 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=mime-version:sender:in-reply-to:references:date :x-google-sender-auth:message-id:subject:from:to:cc:content-type; bh=DyCTxcBd6GHrVU/h6OuJWXCOjxGbm+Yis2PBOdhYMDo=; b=td7y3aWwxq9sNo8T2zL9yRkAX0gTcHRnRCuuUcs8fjGX1Vj9qyMY+qhoV13WRQyewx l+W3+CreoK5affubcZxhX2KV9kX3kUokABoskSxNNC9gC8rhqFILGYO7uye7eOJR0sjF tyo8x6OwmaU8hFXm7v2EIS2BGjuR7AY4z/E5o= MIME-Version: 1.0 Received: by 10.150.144.4 with SMTP id r4mr14049956ybd.98.1320405900681; Fri, 04 Nov 2011 04:25:00 -0700 (PDT) Sender: daniel.c.buenzli@gmail.com Received: by 10.147.128.14 with HTTP; Fri, 4 Nov 2011 04:25:00 -0700 (PDT) In-Reply-To: <4D9C7FE8-98E1-4D36-90CE-BDEDA6607338@ocamlpro.com> References: <7EB42100-0E5F-4FBB-8CB8-A318926F0E0E@x9c.fr> <3AFFA70C-BD82-4A7B-94E6-7FAB5BC93148@x9c.fr> <4EB2F67D.6070202@inria.fr> <20111104092409.GA22221@ccellier.rd.securactive.lan> <4D9C7FE8-98E1-4D36-90CE-BDEDA6607338@ocamlpro.com> Date: Fri, 4 Nov 2011 12:25:00 +0100 X-Google-Sender-Auth: 4-z_1SeSGnC-TYo8PndlfY3n-z8 Message-ID: From: =?UTF-8?Q?Daniel_B=C3=BCnzli?= To: Thomas Gazagnaire Cc: caml-list@inria.fr Content-Type: text/plain; charset=UTF-8 Subject: Re: [Caml-list] [ANN] Argot: 1.0 release Hello, A few comments on the design. Overall much better than ocaml's current stylesheet and completely web 2.0 correct. But. One problem of web 2.0 correct interfaces is that they are a little bit patronizing, and don't show enough data. The information density is too low. Do you really half of my screen to communicate me the name of the module I'm currently looking at ? Overall I find the spacing to be too loose. I want to see more information on a screenful. Much more can be shown, while retaining the ability to rapidly skim from one definition to the other and without cramping the design. Another thing is the fixed-width layout. The width of the page is too wide. First the lines are too long which causes a readability issue: it makes it hard to read from one line to the other --- depends on the font but beyond approx. 80 chars per line it becomes hard for continuous reading. Second I personally never work on 27-inch displays. With the current design I cannot put my browser window next to emacs and read the doc without a horizontal scroll bar. The design grid should be fluid, within reasonable limits (cf. css's min-width, max-width and if you want to go wild, media queries to use different style sheets for different devices widths, a few techniques and pointers here [1]). Finally do something with css' *:target selector it's useful when you link to anchors that are at the bottom of a page or on a page that is too small to scroll. E.g. : http://erratique.ch/software/cmdliner/doc/Cmdliner.Arg.html#VALpair > The goal is to be able to browse it locally (it's a bit awkward to have to run a webserver to read documentation). Yes. > The searching tools are quite limited currently, To me the search tools are not so useful. Usually I know in which module I want to lookup a function. To get there quickly I use my OS file search --- thanks to ocamldoc generating one file per module --- and then the incremental search of my browser. Of course this is quite different of indexing e.g. the symbols directly but it works well in practice. But having been recently forced out of emacs into a proprietary IDE to be *able* to work on a project written in a programmingLanguageWithAbsurdlyLongNamingConventions, one thing I actually became very fond of is type aware autocompletion and the ability to browse from a symbol in my code directly to the page where its documented. The former may be complex to implement without compiler support but I'm sure the latter is not. My elisp skills are however too limited for me to implement that myself but I'd love to have that in ocaml's emacs mode. Regarding search by type, I wonder if people actually use this for useful reasons or if it's just out of curiosity or for the cool hack factor -- and sure it's cool. I mean there's not enough semantics in types to tell you what a function will do, and since we curry it is not always clear in which order we will argument. Best, Daniel [1] http://www.alistapart.com/articles/responsive-web-design/