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

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

[forum]

Dear list,

This post announces the 1.0 release of the Argot project, whose goal is to provide
an enhanced HTML generator for ocamldoc, released under the GPL v3.

Home page: http://argot.x9c.fr
Preview page (for search feature): http://argot.x9c.fr/distrib/argot-3.12-libref/index.html
Forge page: https://forge.ocamlcore.org/projects/argot/

Main changes since 1.0-beta:
  - new '-search' command-line switch to generate search information
    (available on HTML pages through the magnifying glass icon)
  - search by exact name
  - search by name using regular expression
  - search by type using isomorphisms (experimental)
  - new '-definitions' command-line switch to load variables from file
  - correct handling of embedded tables
  - more predefined licenses for the '@license' tag
  - some refactoring


Xavier Clerc

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

[David MENTRE]

Hello,

2011/11/2 forum@x9c.fr <forum@x9c.fr>:
> Preview page (for search feature): http://argot.x9c.fr/distrib/argot-3.12-libref/index.html

Would it be possible to have the search page in another tab? I find
the opening of a new window annoying and if I middle click on the
search icon the same page is opened again in the new tab.

Beside that, the search feature is very responsive and quite useful.

Best regards,
david

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

[forum]

Le 3 nov. 2011 à 09:08, David MENTRE a écrit :

> Hello,
> 
> 2011/11/2 forum@x9c.fr <forum@x9c.fr>:
>> Preview page (for search feature): http://argot.x9c.fr/distrib/argot-3.12-libref/index.html
> 
> Would it be possible to have the search page in another tab? I find
> the opening of a new window annoying and if I middle click on the
> search icon the same page is opened again in the new tab.

I really do not know how to do that, having a very basic knowledge of HTML/JavaScript.
I can't even tell if those have a notion of browser tab ; if they have the notion, it will be pretty
straightforward to add the option to Argot. Just need to look for the information.


Regards,

Xavier

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

[Fabrice Le Fessant]

[-- Attachment #1: Type: text/plain, Size: 1127 bytes --]

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.

Regards,
Fabrice

On 11/03/2011 07:14 PM, forum@x9c.fr wrote:
> 
> Le 3 nov. 2011 à 09:08, David MENTRE a écrit :
> 
>> Hello,
>>
>> 2011/11/2 forum@x9c.fr <forum@x9c.fr>:
>>> Preview page (for search feature): http://argot.x9c.fr/distrib/argot-3.12-libref/index.html
>>
>> Would it be possible to have the search page in another tab? I find
>> the opening of a new window annoying and if I middle click on the
>> search icon the same page is opened again in the new tab.
> 
> I really do not know how to do that, having a very basic knowledge of HTML/JavaScript.
> I can't even tell if those have a notion of browser tab ; if they have the notion, it will be pretty
> straightforward to add the option to Argot. Just need to look for the information.
> 
> 
> Regards,
> 
> Xavier
> 

[-- 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

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

[rixed]

-[ 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 ?

Also, apparently one cannot search by type. It would be a nice feature
to have.

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 ?

Thank you very much to make such tools available, though!

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

[Anil Madhavapeddy]

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

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

[Thomas Gazagnaire]

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

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

[Fabrice Le Fessant]

[-- 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

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

[Gerd Stolpmann]

Excellent! I'll definitely use it.

Another idea for a feature: more options how classes and modules are
shown. For example, I once had the problem that I wanted an included
module also to be included in-place in the documentation (rather than by
reference/link). I modified the ocamldoc generator to get this effect,
and the result is here:

http://projects.camlcity.org/projects/dl/pxp-1.2.1/doc/manual/html/ref/Pxp_types.html

The grey box contains actually the included definitions. This is much
easier to understand for the casual reader. The feature is accompanied
by a link rewriter, so the ocamldoc-generated links point to the
including module rather the included module.

A similar problem occurs for inherited class types. Of course, one wants
to enable this on a case-by-case basis.

I blogged about this some years ago:
http://blog.camlcity.org/blog/pxp121.html

The generator (very specific to this case):
https://godirepo.camlcity.org/svn/lib-pxp/tags/pxp-1.2.1/tools/src/odoc/chtml.ml

Gerd

Am Mittwoch, den 02.11.2011, 19:29 +0100 schrieb forum@x9c.fr:
> Dear list,
> 
> This post announces the 1.0 release of the Argot project, whose goal is to provide
> an enhanced HTML generator for ocamldoc, released under the GPL v3.
> 
> Home page: http://argot.x9c.fr
> Preview page (for search feature): http://argot.x9c.fr/distrib/argot-3.12-libref/index.html
> Forge page: https://forge.ocamlcore.org/projects/argot/
> 
> Main changes since 1.0-beta:
>   - new '-search' command-line switch to generate search information
>     (available on HTML pages through the magnifying glass icon)
>   - search by exact name
>   - search by name using regular expression
>   - search by type using isomorphisms (experimental)
>   - new '-definitions' command-line switch to load variables from file
>   - correct handling of embedded tables
>   - more predefined licenses for the '@license' tag
>   - some refactoring
> 
> 
> Xavier Clerc
> 
> 
> 

-- 
------------------------------------------------------------
Gerd Stolpmann, Darmstadt, Germany    gerd@gerd-stolpmann.de
Creator of GODI and camlcity.org.
Contact details:        http://www.camlcity.org/contact.html
Company homepage:       http://www.gerd-stolpmann.de
*** Searching for new projects! Need consulting for system
*** programming in Ocaml? Gerd Stolpmann can help you.
------------------------------------------------------------

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

[Daniel Bünzli]

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/

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

[forum]

Gerd Stolpmann <info@gerd-stolpmann.de> a écrit :

> Excellent! I'll definitely use it.
>
> Another idea for a feature: more options how classes and modules are
> shown. For example, I once had the problem that I wanted an included
> module also to be included in-place in the documentation (rather than by
> reference/link). I modified the ocamldoc generator to get this effect,
> and the result is here:
>
> http://projects.camlcity.org/projects/dl/pxp-1.2.1/doc/manual/html/ref/Pxp_types.html
>
> The grey box contains actually the included definitions. This is much
> easier to understand for the casual reader. The feature is accompanied
> by a link rewriter, so the ocamldoc-generated links point to the
> including module rather the included module.
>
> A similar problem occurs for inherited class types. Of course, one wants
> to enable this on a case-by-case basis.
>
> I blogged about this some years ago:
> http://blog.camlcity.org/blog/pxp121.html
>
> The generator (very specific to this case):
> https://godirepo.camlcity.org/svn/lib-pxp/tags/pxp-1.2.1/tools/src/odoc/chtml.ml


This is an interesting feature; it may be implemented by
using some "folding" in order to have the best of both
worlds (short name by default, and unfolding upon request).


Regards,

Xavier Clerc

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

[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

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

[Daniel Bünzli]

> 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

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

[Edgar Friendly]

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.

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

[Romain Bardou]

> 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

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

[Daniel Bünzli]

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

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

[Thomas Gazagnaire]

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!