Re: [Caml-list] [ANN] Argot: 1.0 release

["Daniel Bünzli" <daniel.buenzli@erratique.ch>]

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/