|Anonymous | Login | Signup for a new account||2014-08-23 13:26 CEST|
|Main | My View | View Issues | Change Log | Roadmap|
|View Issue Details|
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0006135||OCaml||OCaml documentation||public||2013-08-22 11:23||2014-08-21 11:16|
|Target Version||after-4.02.0||Fixed in Version|
|Summary||0006135: Please document -ppx option|
|Description||Looking at the 4.01beta reference manual I cannot find -ppx!|
Apart from including -ppx it would be nice to have some basic information about ppx commands (howto read/write the syntax tree, the type of the syntax tree), as well as a pointer to more extensive documentation.
|Tags||No tags attached.|
My personal hunch is that before we know what will be done with extension_points branch (eg. integrating it in time for a 4.02 release), there are relatively few legitimate uses of -ppx, and adding extension_points in the mix would probably require an extensive reformulation of the documentation if it exists. (There already is some documentation for extension_points specifically in http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/branches/extension_points/experimental/frisch/extension_points.txt?view=markup [^] ).
In particular, I think that using -ppx to overload the meaning of program fragments that already have a syntactic meaning in the existing OCaml language (as done in wmeyer's OMonad for experimentation purposes : http://danmey.org/omonad.html [^] ) is a bad practice that we should not encourage. The question is what other use cases remain without extension_points. There are definitely some ( it is used by an experimental version of Bisect http://bisect.x9c.fr/index.html [^] for example), but not as much as there could be in 4.02.
Of course more documentation is better than less, so if you or anyone feels motivated to write something (I guess the best thing to do for now is to look at the existing uses of -ppx to understand how to implement filters with it), I would be happy to have a look, provide feedback, and get something integrated in the manual if it's good.
Hmm. I spend a whole day making sure that every command line option is documented, both in the manual and in the man pages, for ocamlc, ocamlopt, and ocaml...
As for giving a detailed documentation of the AST types, I think like Gabriel that it's probably too early.
Hendrik Tews (reporter)
OK, I didn't know that the extensions have not been merged yet.
Then I would suggest to briefly document -ppx with the calling convention and the data type, eg
-ppx <command> Run <command> as external filter on the
abstract syntax tree after parsing. The filter
is expected to read/write a marshaled ast
of type XXX on stdin/stdout. This option will
only get useful when extension points have been
implemented in one of the following releases.
|Gabriel, what are we going to do about this? It's marked as target 4.02.0+dev.|
> It's marked as target 4.02.0+dev.
That doesn't mean it must be done for 4.02.0, we can still postpone it. I talked to Alain in private, and he says we can (and should) document it after the release.
edited on: 2014-08-21 08:37
I don't know -ppx well enough to write the documentation (should I reassign the issue?). If Alain can do it, that's very good; otherwise we may try to nicely ask Peter "whitequark" Zotov for help, as he's played with -ppx a lot in the last few months.
|Alain is busy right now, so I'll release 4.02 without this documentation. It's still urgent but it can be written after the release.|
|2013-08-22 11:23||Hendrik Tews||New Issue|
|2013-08-22 11:36||gasche||Note Added: 0010226|
|2013-08-22 21:47||doligez||Note Added: 0010227|
|2013-08-22 21:47||doligez||Status||new => acknowledged|
|2013-08-22 21:47||doligez||Target Version||=> later|
|2013-08-23 11:43||Hendrik Tews||Note Added: 0010235|
|2013-09-12 15:59||doligez||Target Version||later => 4.02.0+dev|
|2014-08-18 20:20||doligez||Priority||normal => urgent|
|2014-08-20 09:48||shinwell||Note Added: 0012027|
|2014-08-20 09:48||shinwell||Assigned To||=> gasche|
|2014-08-20 09:48||shinwell||Status||acknowledged => assigned|
|2014-08-20 19:09||doligez||Note Added: 0012030|
|2014-08-21 08:37||gasche||Note Added: 0012036|
|2014-08-21 08:37||gasche||Note Edited: 0012036||View Revisions|
|2014-08-21 11:16||doligez||Note Added: 0012038|
|2014-08-21 11:16||doligez||Target Version||4.02.0+dev => after-4.02.0|
|Copyright © 2000 - 2011 MantisBT Group|