* Re: [Caml-list] [ANN] Argot: 1.0 release
2011-11-04 9:24 ` rixed
@ 2011-11-04 9:34 ` Anil Madhavapeddy
2011-11-04 9:47 ` Thomas Gazagnaire
2011-11-04 9:55 ` Fabrice Le Fessant
2 siblings, 0 replies; 17+ messages in thread
From: Anil Madhavapeddy @ 2011-11-04 9:34 UTC (permalink / raw)
To: rixed; +Cc: caml-list
On 4 Nov 2011, at 09:24, rixed@happyleptic.org wrote:
> -[ Thu, Nov 03, 2011 at 09:15:57PM +0100, Fabrice Le Fessant ]----
>> Hi,
>>
>> By the way, Thomas is also working on a plugin for ocamldoc, with
>> incremental search. An example of what it generates (for the stdlib and
>> some of our internal libraries) is available here:
>>
>> http://www.ocamlpro.com/doc/stdlib/index_modules.html
>>
>> It is not yet released, but we plan to do it in the next months, with
>> some other tools.
>
> This looks very promising.
> Will the tool generate mere html files or is it intended for an ocaml
> web framework such as ocsigen ?
It's all pure HTML/CSS. The wonders of the Twitter Bootstrap framework :-)
> Also, apparently one cannot search by type. It would be a nice feature
> to have.
Thomas also prototyped a searchable version for the CUFP Mirage tutorial:
e.g.: http://www.ocamlpro.com/mirage/xen/
but the search view does need some optimisation with a large number of modules, as in the standard library. The new version he's doing in HTML is far slicker and faster.
Citrix have a really useful JSON output to ocamldoc in the XAPI tree that is very handy for anyone else who wants to do something like this:
https://github.com/xen-org/xen-api/blob/master/ocaml/doc/odoc_json.ml
-anil
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [Caml-list] [ANN] Argot: 1.0 release
2011-11-04 9:24 ` rixed
2011-11-04 9:34 ` Anil Madhavapeddy
@ 2011-11-04 9:47 ` Thomas Gazagnaire
2011-11-04 11:25 ` Daniel Bünzli
2011-11-04 9:55 ` Fabrice Le Fessant
2 siblings, 1 reply; 17+ messages in thread
From: Thomas Gazagnaire @ 2011-11-04 9:47 UTC (permalink / raw)
To: rixed; +Cc: caml-list
Hi,
> This looks very promising.
> Will the tool generate mere html files or is it intended for an ocaml
> web framework such as ocsigen ?
Currently, it generates only raw HTML files. The goal is to be able to browse it locally (it's a bit awkward to have to run a webserver to read documentation).
> Also, apparently one cannot search by type. It would be a nice feature
> to have.
The searching tools are quite limited currently, I'm just re-using standard JavaScript libraries for auto-completion. I had a quick look at Argot, and if I understand correctly, it is generating data and javascript code to enhance the search. So, I think it is possible integrate both tools nicely.
> Last thing, unrelated: from the search box one can see you have many
> modules extending the stdlib (the Ocp* modules). Why another stdlib
> extension instead of, say, contributing to batteries ?
That's true, we have developed internally some limited extensions to the standard library; that's because we didn't want to have external dependencies for our tools and because the amount of extensions was very small (so it was quicker to write the extensions than to modify an external library) However, we don't plan to release yet-an-other-standard-library, so I guess than we could later participate and switch to more widely-used standard library extensions.
--
Thomas
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [Caml-list] [ANN] Argot: 1.0 release
2011-11-04 9:47 ` Thomas Gazagnaire
@ 2011-11-04 11:25 ` Daniel Bünzli
2011-11-04 12:45 ` forum
2011-11-04 17:08 ` Romain Bardou
0 siblings, 2 replies; 17+ messages in thread
From: Daniel Bünzli @ 2011-11-04 11:25 UTC (permalink / raw)
To: Thomas Gazagnaire; +Cc: caml-list
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/
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [Caml-list] [ANN] Argot: 1.0 release
2011-11-04 11:25 ` Daniel Bünzli
@ 2011-11-04 12:45 ` forum
2011-11-04 13:03 ` Daniel Bünzli
2011-11-04 17:08 ` Romain Bardou
1 sibling, 1 reply; 17+ messages in thread
From: forum @ 2011-11-04 12:45 UTC (permalink / raw)
To: caml-list; +Cc: forum
Daniel Bünzli <daniel.buenzli@erratique.ch> a écrit :
(...)
>> 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.
Well, regarding search by name, I consider that the only advantages upon
browser search are:
- simultaneous search on several pages;
- regular expression search (although some browser may support it).
(...)
> 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.
To be clear, I implemented search by type in order to understand a bit
more the book of Roberto Di Cosmo about type isomorphisms. Whether it
can be a useful tool remains to be determined. The tool now exists,
let's see if there is a usage for it.
I do agree that there is often not enough semantics in OCaml types, but
please notice that the order of arguments and whether the function is
currified is not relevant. Indeed, doing type search up to isomorphisms
allows to get rid of these details, all of the following queries will
answer with "String.sub":
- "int -> int -> string -> string"
- "string -> (int * int) -> string"
- "string * int *int -> string"
while the actual signature is "string -> int -> int -> string".
Regards,
Xavier Clerc
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [Caml-list] [ANN] Argot: 1.0 release
2011-11-04 12:45 ` forum
@ 2011-11-04 13:03 ` Daniel Bünzli
0 siblings, 0 replies; 17+ messages in thread
From: Daniel Bünzli @ 2011-11-04 13:03 UTC (permalink / raw)
To: forum; +Cc: caml-list
> I do agree that there is often not enough semantics in OCaml types, but
> please notice that the order of arguments and whether the function is
> currified is not relevant. Indeed, doing type search up to isomorphisms
> allows to get rid of these details,
Ha. I slipped the up to isomorphisms part. Quite cool indeed.
Best,
Daniel
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [Caml-list] [ANN] Argot: 1.0 release
2011-11-04 11:25 ` Daniel Bünzli
2011-11-04 12:45 ` forum
@ 2011-11-04 17:08 ` Romain Bardou
2011-11-04 18:05 ` Daniel Bünzli
1 sibling, 1 reply; 17+ messages in thread
From: Romain Bardou @ 2011-11-04 17:08 UTC (permalink / raw)
To: Daniel Bünzli; +Cc: Thomas Gazagnaire, caml-list
> 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]).
I agree that the name of the module is too big :)
On the other hand, I would advise to be cautious about the fixed width
thing. I find it quite annoying when a website only uses 1/3 of my
browser window and the rest is filled with blank space. Sure, if a line
is too long then it's less readable blablabla. But forcing a fixed width
is not a good solution in my opinion. Too often have I increased the
font size, only to find out that either:
- it did not resize the containers as well,
- or the website did not allow font size changes (probably because of
the above).
In both cases, the user is screwed, especially on small monitors with
big resolutions. The user should be able to change the font size and use
as much space as he wants. If you find that lines are too long, just
resize your window.
Sorry for being off-topic ;)
Cheers,
--
Romain
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [Caml-list] [ANN] Argot: 1.0 release
2011-11-04 17:08 ` Romain Bardou
@ 2011-11-04 18:05 ` Daniel Bünzli
2011-11-04 18:12 ` Thomas Gazagnaire
0 siblings, 1 reply; 17+ messages in thread
From: Daniel Bünzli @ 2011-11-04 18:05 UTC (permalink / raw)
To: caml-list
On 4 November 2011 18:08, Romain Bardou <bardou@lri.fr> wrote:
> If you find that lines are too long, just resize your window.
Well that was my point... You cannot do that at the moment with this design.
Daniel
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [Caml-list] [ANN] Argot: 1.0 release
2011-11-04 18:05 ` Daniel Bünzli
@ 2011-11-04 18:12 ` Thomas Gazagnaire
0 siblings, 0 replies; 17+ messages in thread
From: Thomas Gazagnaire @ 2011-11-04 18:12 UTC (permalink / raw)
To: Daniel Bünzli; +Cc: caml-list
On Nov 4, 2011, at 7:05 PM, Daniel Bünzli wrote:
> On 4 November 2011 18:08, Romain Bardou <bardou@lri.fr> wrote:
>
>> If you find that lines are too long, just resize your window.
>
> Well that was my point... You cannot do that at the moment with this design.
Well, I'm just using the twitter's bootstrap CSS library, which seems to impose a minimum window width. I'm will see how I can handle that nicely (using some "responsive web design" tricks I guess).
Thanks everyone for the feedback!
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [Caml-list] [ANN] Argot: 1.0 release
2011-11-04 9:24 ` rixed
2011-11-04 9:34 ` Anil Madhavapeddy
2011-11-04 9:47 ` Thomas Gazagnaire
@ 2011-11-04 9:55 ` Fabrice Le Fessant
2011-11-04 13:26 ` Edgar Friendly
2 siblings, 1 reply; 17+ messages in thread
From: Fabrice Le Fessant @ 2011-11-04 9:55 UTC (permalink / raw)
To: caml-list
[-- Attachment #1: Type: text/plain, Size: 1461 bytes --]
> Also, apparently one cannot search by type. It would be a nice feature
> to have.
Thomas, add it to the features list ! ;-)
> Last thing, unrelated: from the search box one can see you have many
> modules extending the stdlib (the Ocp* modules). Why another stdlib
> extension instead of, say, contributing to batteries ?
First, we don't have so many of them, we only put there what we needed
for our set of tools. Some of them are really close to the compiler, and
we might submit them for inclusion in the official distribution, so we
didn't want to add a dependency to Batteries or Core too early.
The other reason is that we haven't tried Batteries or Core enough yet,
we have constraints, and we must make sure that if we rely on the some
library, the library fit these constraints. For example, I know that
Core has not been tested on Windows, and I don't know for Batteries.
Also, we want to separate between "lang" and "system", i.e. modules that
can be implemented with the core language, and modules that have system
dependencies.
Finally, unlike other companies using OCaml, we want to provide support
on the language itself, which means the compilers, other dev tools, and
also basic libraries. So, at some point, we will have to contribute to
either Core or Batteries, or both, but before that, we need to think
more about our own idea of what a good standard library should be, to
choose the best candidate from our point of view.
Fabrice
[-- Attachment #2: fabrice_le_fessant.vcf --]
[-- Type: text/x-vcard, Size: 380 bytes --]
begin:vcard
fn:Fabrice LE FESSANT
n:LE FESSANT;Fabrice
org:INRIA Saclay -- Ile-de-France;P2P & OCaml
adr;quoted-printable:;;Parc Orsay Universit=C3=A9 ;Orsay CEDEX;;91893;France
email;internet:fabrice.le_fessant@inria.fr
title;quoted-printable:Charg=C3=A9 de Recherche
tel;work:+33 1 74 85 42 14
tel;fax:+33 1 74 85 42 49
url:http://fabrice.lefessant.net/
version:2.1
end:vcard
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [Caml-list] [ANN] Argot: 1.0 release
2011-11-04 9:55 ` Fabrice Le Fessant
@ 2011-11-04 13:26 ` Edgar Friendly
0 siblings, 0 replies; 17+ messages in thread
From: Edgar Friendly @ 2011-11-04 13:26 UTC (permalink / raw)
To: caml-list
On 11/04/2011 05:55 AM, Fabrice Le Fessant wrote:
> The other reason is that we haven't tried Batteries or Core enough
> yet, we have constraints, and we must make sure that if we rely on
> the some library, the library fit these constraints. For example, I
> know that Core has not been tested on Windows, and I don't know for
> Batteries. Also, we want to separate between "lang" and "system",
> i.e. modules that can be implemented with the core language, and
> modules that have system dependencies.
>
Batteries works for me under Windows, although it's not heavily tested.
It's pure ocaml (no C stubs), and the build system is a thin `make`
wrapper on top of ocamlbuild.
> Finally, unlike other companies using OCaml, we want to provide
> support on the language itself, which means the compilers, other dev
> tools, and also basic libraries. So, at some point, we will have to
> contribute to either Core or Batteries, or both, but before that, we
> need to think more about our own idea of what a good standard library
> should be, to choose the best candidate from our point of view.
I agree there's a need for a good conversation about what a good
standard library should be, and am interested in hearing more your point
of view.
E.
^ permalink raw reply [flat|nested] 17+ messages in thread