Tutorial

[benjub]

I'm not sure where to report this: in https://erratique.ch/software/cmdliner/doc/tutorial.html, the fourth line of code begins with let cmd = which should be let revolt_cmd =.

Also, from a learner perspective, the beginning of the tutorial is not very clear because there are three diffrent things sharing the same name, "revolt": the function defined on the first line, the argument of Cmd.info, and (implicitly) the name of the executable file. This may not be a problem for people who are comfortable with the compilation process, but it confused me (and may confuse others). For instance, if I keep "revolt" in the first line, change the second usage of "revolt" to (Cmd.info "revolt1"), put things in a file named revolt2.ml, and run

$ ocamlfind ocamlopt -linkpkg -package cmdliner revolt2.ml

then I get:

$ ./a.out
Revolt!
$ ./a.out azer
revolt1: too many arguments, don't know what to do with 'azer'
Usage: revolt1 [OPTION]… 
Try 'revolt1 --help' for more information.
$ revolt1 --help
bash: revolt1 : commande introuvable
$ ./a.out --help  [displays the man page, with "revolt1" as command name]

In particular, the sentence This defines a command line tool named "revolt" is a bit misleading (to achieve this, you apparently need to use ocamlopt -o XXX where XXX matches exactly the argument of Cmd.info). Again, this is probably obvious to anyone slightly acquainted to this kind of tools, but since the tutorial is targeted at beginners, maybe some of this can be added to the tutorial to avoid some confusion.

[dbuenzli]

I'm not sure where to report this: in https://erratique.ch/software/cmdliner/doc/tutorial.html, the fourth line of code begins with let cmd = which should be let revolt_cmd =.

Thanks yes, there's a PR here #137

In particular, the sentence This defines a command line tool named "revolt" is a bit misleading

Indeed I should likely have full instructions including a compiler invocation.

Again, this is probably obvious to anyone slightly acquainted to this kind of tools, but since the tutorial is targeted at beginners,

The tutorial is not really targeted at OCaml newcomers, there's other, better, material for that. It's targeted at newcomers to the library.

But I see the confusion, I'll try to see if I can do something about that.

[dbuenzli]

I tried to improve things a bit. I mentioned the file name in which snippets should belong to and added full compilation instructions before invoking the tool.

I also mentioned in passing that the name you use in Cmdliner is used for error reporting and doc gen.

Not sure if I that will do, but again I don't really want to explain ocaml's compilation model here. It's not really the place for that.

[benjub]

Thanks, I think this is clearer.
I still feel uneasy about the fact that many things share the same name: here, revolt is: an ocaml function (let revolt () = ...), the Cmd.info string, the name of the .ml file, and the name of the output (-o revolt) of ocamlopt. This makes it hard to know which identifier identities are necessary and which are accidental. It's a bit as if the first example you gave to illustrate the commutativity of integer addition was: 3 + 3 = 3 + 3.

[dbuenzli]

I still feel uneasy about the fact that many things share the same name: here, revolt is: an ocaml function (let revolt () = ...), the Cmd.info string, the name of the .ml file, and the name of the output (-o revolt) of ocamlopt

I don't. Sample code should reflect good practice and in practice, unless you have a good reason not to, it wouldn't be good to define different names for these things. Unless you want to make it harder for users to orient themselves in your code.