Merge pull request dbuenzli#1 from emillon/1.1.1-dune

Merge upstream 1.1.1

.gitignore

@@ -1,10 +1,6 @@
 _build
 _b0
 tmp
-*~
-\.\#*
-\#*#
 *.byte
 *.native
 cmdliner.install
-src/.merlin

.merlin

@@ -1,3 +1,4 @@
+# PKG b0.kit
 S src
 S test
-B _build/**
+B _b0/**

B0.ml

@@ -1,9 +1,65 @@
-open B0
+open B0_kit.V000
+open B00_std
 
-let cmdliner = "cmdliner"
-let doc = "Declarative definition of command line interfaces for OCaml"
+(* OCaml library names *)
 
-let pkg = Pkg.create cmdliner ~doc
-let lib =
-  let srcs = (`Src_dirs [Fpath.v "src"]) in
-  B0_ocaml.Unit.lib ~pkg cmdliner srcs ~doc
+let cmdliner = B0_ocaml.libname "cmdliner"
+
+(* Units *)
+
+let cmdliner_lib =
+  let srcs = Fpath.[`Dir (v "src")] in
+  B0_ocaml.lib cmdliner ~doc:"The cmdliner library" ~srcs ~requires:[]
+
+(* Tests *)
+
+let test ?doc t =
+  let srcs = [`File (Fpath.v (Fmt.str "test/%s.ml" t))] in
+  let requires = [cmdliner] in
+  let meta = B0_meta.(empty |> tag test) in
+  B0_ocaml.exe t ?doc ~srcs ~requires ~meta
+
+let chorus = test "chorus"
+let cp_ex = test "cp_ex"
+let darcs_ex = test "darcs_ex"
+let revolt = test "revolt"
+let rm_ex = test "rm_ex"
+let tail_ex = test "tail_ex"
+let tail_ex = test "test_nest"
+let test_dupe_stdopts = test "test_dupe_stdopts"
+let test_man = test "test_man"
+let test_man_utf8 = test "test_man_utf8"
+let test_opt_req = test "test_opt_req"
+let test_pos = test "test_pos"
+let test_pos_all = test "test_pos_all"
+let test_pos_left = test "test_pos_left"
+let test_pos_req = test "test_pos_req"
+let test_pos_rev = test "test_pos_rev"
+let test_term_dups = test "test_term_dups"
+let test_with_used_args = test "test_with_used_args"
+
+(* Packs *)
+
+let default =
+  let meta =
+    let open B0_meta in
+    empty
+    |> add authors ["The cmdliner programmers"]
+    |> add maintainers ["Daniel Bünzli <daniel.buenzl [email protected]>"]
+    |> add homepage "https://erratique.ch/software/cmdliner"
+    |> add online_doc "https://erratique.ch/software/cmdliner/doc"
+    |> add issues "https://github.com/dbuenzli/cmdliner/issues"
+    |> add repo "git+https://erratique.ch/repos/cmdliner.git"
+    |> add licenses ["ISC"]
+    |> add description_tags ["cli"; "system"; "declarative"; "org:erratique"]
+    |> tag B0_opam.tag
+    |> add B0_opam.Meta.depends
+      [ "ocaml", {|>= "4.08.0"|}; ]
+    |> add B0_opam.Meta.build
+      {|[[ make "all" "PREFIX=%{prefix}%" ]]|}
+    |> add B0_opam.Meta.install
+      {|[[make "install" "LIBDIR=%{_:lib}%" "DOCDIR=%{_:doc}%"]
+         [make "install-doc" "LIBDIR=%{_:lib}%" "DOCDIR=%{_:doc}%"]]|}
+  in
+  B0_pack.v "default" ~doc:"cmdliner package" ~meta ~locked:true @@
+  B0_unit.list ()

BRZO

@@ -0,0 +1 @@
+(srcs-x build.ml test pkg)

CHANGES.md

@@ -1,7 +1,153 @@
+v1.1.1 2022-03-23 La Forclaz (VS)
+---------------------------------
+
+- General documentation fixes, tweaks and improvements.
+- Docgen: suppress trailing whitespace in synopsis rendering.
+- Docgen: fix duplicate rendering of standard options when using `Term.ret` (#135).
+- Docgen: fix duplicate rendering of command name on ``Term.ret (`Help (fmt, None)`` 
+  (#135).
 
+v1.1.0 2022-02-06 La Forclaz (VS)
+---------------------------------
 
-- Fix default value rendering in manpages. These were not properly
-  escaped. Thanks to David Allsopp for the patch.
+- Require OCaml 4.08.
+
+- Support for deprecating commands, arguments and environment variables (#66).
+  See the `?deprecated` argument of `Cmd.info`, `Cmd.Env.info` and `Arg.info`.
+
+- Add `Manpage.s_none` a special section name to use whenever you 
+  want something not to be listed in a command's manpage.
+
+- Add `Arg.conv'` like `Arg.conv` but with a parser signature that returns 
+  untagged string errors.
+
+- Add `Term.{term,cli_parse}_result'` functions.
+
+- Add deprecation alerts on what is already deprecated.
+
+- On unices, use `command -v` rather than `type` to find commands.
+
+- Stop using backticks for left quotes. Use apostrophes everywhere. 
+  Thanks to Ryan Moore for reporting a typo that prompted the change (#128).
+
+- Rework documentation structure. Move out tutorial, examples and
+  reference doc from the `.mli` to multiple `.mld` pages.
+
+- `Arg.doc_alts` and `Arg.doc_alts_enum`, change the default rendering
+  to match the manpage convention which is to render these tokens in
+  bold.  If you want to recover the previous rendering or were using
+  these functions outside man page rendering use an explicit
+  `~quoted:true` (the optional argument is available on earlier
+  versions).
+
+- The deprecated `Term.exit` and `Term.exit_status_of_result` now 
+  require a `unit` result.  This avoids various errors to go undetected. 
+  Thanks to Thomas Leonard for the patch (#124).
+
+- Fix absent and default option values (`?none` string argument of `Arg.some`)
+  rendering in manpages:
+
+  1. They were not escaped, they now are.
+  2. They where not rendered in bold, they now are.
+  3. The documentation language was interpreted, it is no longer the case.
+
+  If you were relying on the third point via `?none` of `Arg.some`, use the new
+  `?absent` optional argument of `Arg.info` instead. Besides a new
+  `Arg.some'` function is added to specify a value for `?none` instead
+  of a string.  Thanks to David Allsopp for the patch (#111).
+
+- Documentation generation use: `…` (U+2026) instead of `...` for 
+  ellipsis. See also UTF-8 manpage support below.
+
+- Documentation generation, improve command synopsis rendering on 
+  commands with few options (i.e. mention them).
+
+- Documentation generation, drop section heading in the output if the section 
+  is empty.
+
+### New `Cmd` module and deprecation of the `Term` evaluation interface
+
+This version of cmdliner deprecates the `Term.eval*` evaluation
+functions and `Term.info` information values in favor of the new
+`Cmdliner.Cmd` module. 
+
+The `Cmd` module generalizes the existing sub command support to allow
+arbitrarily nested sub commands each with its own man page and command
+line syntax represented by a `Term.t` value.
+
+The mapping between the old interface and the new one should be rather
+straightforward. In particular `Term.info` and `Cmd.info` have exactly
+the same semantics and fields and a command value simply pairs a
+command information with a term.
+
+However in this transition the following things are changed or added:
+
+* All default values of `Cmd.info` match those of `Term.info` except
+  for:
+  * The `?exits` argument which defaults to `Cmd.Exit.defaults`
+    rather than the empty list.
+  * The `?man_xrefs` which defaults to the list ``[`Main]`` rather
+    than the empty list (this means that by default sub commands 
+    at any level automatically cross-reference the main command).
+  * The `?sdocs` argument which defaults to `Manpage.s_common_options`
+    rather than `Manpage.s_options`.
+
+* The `Cmd.Exit.some_error` code is added to `Cmd.Exit.defaults`
+  (which in turn is the default for `Cmd.info` see above).  This is an
+  error code clients can use when they don't want to bother about
+  having precise exit codes.  It is high so that low, meaningful,
+  codes can later be added without breaking a tool's compatibility. In
+  particular the convenience evaluation functions `Cmd.eval_result*`
+  use this code when they evaluate to an error.
+
+* If you relied on `?term_err` defaulting to `1` in the various
+  `Term.exit*` function, note that the new `Cmd.eval*` function use
+  `Exit.cli_error` as a default. You may want to explicitely specify
+  `1` instead if you use `Term.ret` with the `` `Error`` case 
+  or `Term.term_result`.
+
+Finally be aware that if you replace, in an existing tool, an encoding
+of sub commands as positional arguments you will effectively break the
+command line compatibility of your tool since options can no longer be
+specified before the sub commands, i.e. your tool synopsis moves from:
+
+```
+tool cmd [OPTION]… SUBCMD [ARG]…
+```
+to 
+```
+tool cmd SUBCMD [OPTION]… [ARG]…
+```
+
+Thanks to Rudi Grinberg for prototyping the feature in #123.
+
+### UTF-8 manpage support 
+
+It is now possible to write UTF-8 encoded text in your doc strings and
+man pages.
+
+The man page renderer used on `--help` defaults to `mandoc` if
+available, then uses `groff` and then defaults to `nroff`. Starting
+with `mandoc` catches macOS whose `groff` as of 11.6 still doesn't
+support UTF-8 input and struggles to render some Unicode characters.
+
+The invocations were also tweaked to remove the `-P-c` option which
+entails that the default pager `less` is now invoked with the `-R` option.
+
+If you install UTF-8 encoded man pages output via `--help=groff`, in
+`man` directories bear in mind that these pages will look garbled on
+stock macOS (at least until 11.6). One way to work around is to
+instruct your users to change the `NROFF` definition in
+`/private/etc/man.conf` from:
+
+    NROFF       /usr/bin/groff -Wall -mtty-char -Tascii -mandoc -c
+
+to:
+
+    NROFF       /usr/bin/mandoc -Tutf8 -c
+
+Thanks to Antonin Décimo for his knowledge and helping with these
+`man`gnificent intricacies (#27).
 
 v1.0.4 2019-06-14 Zagreb
 ------------------------

LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Daniel C. Bünzli
+Copyright (c) 2011 The cmdliner programmers
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

Makefile

@@ -40,8 +40,10 @@ all: $(BUILD-TARGETS)
 install: $(INSTALL-TARGETS)
 
 install-doc:
-	$(INSTALL) -d $(DOCDIR)
+	$(INSTALL) -d $(DOCDIR)/odoc-pages
 	$(INSTALL) CHANGES.md LICENSE.md README.md $(DOCDIR)
+	$(INSTALL) doc/index.mld doc/cli.mld doc/examples.mld doc/tutorial.mld \
+	           doc/tool_man.mld $(DOCDIR)/odoc-pages
 
 clean:
 	ocaml build.ml clean

README.md

@@ -17,8 +17,6 @@ Cmdliner has no dependencies and is distributed under the ISC license.
 [2]: http://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html
 
 Home page: http://erratique.ch/software/cmdliner  
-Contact: Daniel Bünzli `<daniel.buenzl [email protected]>`
-
 
 ## Installation
 

_tags

@@ -1,3 +1,4 @@
 true : bin_annot, safe_string
+<_b0> : -traverse
 <src> : include
 <test> : include

build.ml

@@ -63,7 +63,7 @@ let ml_srcs dir =
 let find_cmd cmds =
   let test, null = match Sys.win32 with
   | true -> "where", " NUL"
-  | false -> "type", "/dev/null"
+  | false -> "command -v", "/dev/null"
   in
   let cmd c = Sys.command (strf "%s %s 1>%s 2>%s" test c null null) = 0 in
   try Some (List.find cmd cmds) with Not_found -> None

cmdliner.opam

@@ -1,14 +1,31 @@
 opam-version: "2.0"
-maintainer: "Daniel Bünzli <daniel.buenzl [email protected]>"
-authors: ["Daniel Bünzli <daniel.buenzl [email protected]>"]
-homepage: "http://erratique.ch/software/cmdliner"
-doc: "http://erratique.ch/software/cmdliner/doc/Cmdliner"
-dev-repo: "git+http://erratique.ch/repos/cmdliner.git"
+name: "cmdliner"
+synopsis: """Declarative definition of command line interfaces for OCaml"""
+maintainer: ["Daniel Bünzli <daniel.buenzl [email protected]>"]
+authors: ["The cmdliner programmers"]
+homepage: "https://erratique.ch/software/cmdliner"
+doc: "https://erratique.ch/software/cmdliner/doc"
+dev-repo: "git+https://erratique.ch/repos/cmdliner.git"
 bug-reports: "https://github.com/dbuenzli/cmdliner/issues"
-tags: [ "cli" "system" "declarative" "org:erratique" ]
-license: "ISC"
-depends:[ "ocaml" {>= "4.03.0"} ]
+license: ["ISC"]
+tags: ["cli" "system" "declarative" "org:erratique"]
+depends: ["ocaml" {>= "4.08.0"}]
 build: [[ make "all" "PREFIX=%{prefix}%" ]]
-install:
-[[make "install" "LIBDIR=%{_:lib}%" "DOCDIR=%{_:doc}%" ]
- [make "install-doc" "LIBDIR=%{_:lib}%" "DOCDIR=%{_:doc}%"  ]]
+install: [[make "install" "LIBDIR=%{_:lib}%" "DOCDIR=%{_:doc}%"]
+         [make "install-doc" "LIBDIR=%{_:lib}%" "DOCDIR=%{_:doc}%"]]
+description: """
+Cmdliner allows the declarative definition of command line interfaces
+for OCaml.
+
+It provides a simple and compositional mechanism to convert command
+line arguments to OCaml values and pass them to your functions. The
+module automatically handles syntax errors, help messages and UNIX man
+page generation. It supports programs with single or multiple commands
+and respects most of the [POSIX][1] and [GNU][2] conventions.
+
+Cmdliner has no dependencies and is distributed under the ISC license.
+
+[1]: http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html
+[2]: http://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html
+
+Home page: http://erratique.ch/software/cmdliner"""