Added documentation for the new -args(0) option. by bschommer · Pull Request #890 · ocaml/ocaml

bschommer · 2016-11-04T09:22:55Z

Additionally typos in the documenation of Args.read_arg(0) and Args.write_arg(0) are fixed.
As requeseted in #843.

Additionally typos in the documenation of Args.read_arg(0) and Args.write_arg(0) are fixed.

dra27

Large number of comments, but predominantly it's just missing hyphens!

dra27 · 2016-11-04T09:54:05Z

manual/manual/cmds/comp.etex

 interactively.

+\item["-args" \var{filename}]
+ Read additional newline separated command line arguments from \var{filename}.


newline-separated (hyphenated). Is this sensitive to Unix/Windows line-endings?

dra27 · 2016-11-04T09:55:20Z

manual/manual/cmds/comp.etex

+ Read additional newline separated command line arguments from \var{filename}.
+
+\item["-args0" \var{filename}]
+ Read additional NUL separated command line arguments from \var{filename}.


NUL-separated (as above). Similarly, is there any Unix/Windows line-ending conversion to worry about here (e.g. would the input file foo\r\n\0bar\r\n be read as foo\n\0bar\n\0 on Windows?)

dra27 · 2016-11-04T09:56:10Z

manual/manual/cmds/depend.etex

+
+\item["-args0" \var{filename}]
+ Read additional NUL separated command line arguments from \var{filename}.
+


Same points as in comp.etex

dra27 · 2016-11-04T09:56:37Z

manual/manual/cmds/native.etex

+
+\item["-args0" \var{filename}]
+ Read additional NUL separated command line arguments from \var{filename}.
+


Same points as in comp.etex

dra27 · 2016-11-04T09:56:43Z

manual/manual/cmds/profil.etex

+
+\item["-args0" \var{filename}]
+ Read additional NUL separated command line arguments from \var{filename}.
+


Same points as in comp.etex

dra27 · 2016-11-04T09:57:53Z

stdlib/arg.mli

@@ -186,12 +186,12 @@ val read_arg: string -> string array

 val read_arg0: string -> string array
 (** Identical to {!Arg.read_arg} but assumes NUL terminated command line


I know it's not part of this diff, but this should really be NUL-terminated (however, the manual and the docs are very inconsistent about null/NULL/NUL!)

dra27 · 2016-11-04T09:58:52Z

stdlib/arg.mli

+    arguments. *)

 val write_arg: string -> string array -> unit
 (** [Arg.write_arg file args] writes the arguments [args] newline terminated


And another hyphen for newline-terminated 😄

dra27 · 2016-11-04T09:59:53Z

stdlib/arg.mli

 (** [Arg.write_arg file args] writes the arguments [args] newline terminated
    into the file [file]. If the any of the arguments in [args] contains a
-    newline use the function {!Args.write_arg0} instead *)
+    newline use the function {!Arg.write_arg0} instead. *)


newline, use (add comma). Could possibly drop the words the function?

dra27 · 2016-11-04T10:01:41Z

stdlib/arg.mli


 val write_arg0: string -> string array -> unit
-(** Identical to {!Arg.write_arg} but uses NUL as terminator instead *)
+(** Identical to {!Arg.write_arg} but uses NUL as terminator instead. *)


as → for the (i.e. "uses NUL as the terminator"). There's a slight inconsistency that the .mli file uses "terminator" where the manual uses "separator".

xavierleroy · 2016-11-04T10:21:18Z

Concerning NUL: I'm afraid few programmers know their ASCII table well enough to know that NUL stands for the character with code 0. For everyone else, it looks like a typo for NULL and is associated with null pointers.

The man page for GNU find reads:

       -print0
              True; print the full file name on the standard output,  followed
              by  a  null  character  (instead  of  the newline character that
              -print uses).  This allows file names that contain  newlines  or
              other  types  of white space to be correctly interpreted by pro‐
              grams that process the find output.  This option corresponds  to
              the -0 option of xargs.

Notice the use of "null character" instead of NUL. Likewise in the man page for xargs, option -0.

So, please don't use NUL, it's jargon. Better use "null character", perhaps with a mention that this is the character with code 0.

gasche · 2016-11-04T10:56:11Z

Despite the non-invasiveness of this patch, it won't be on time for the 4.04 release, so I think we will try to update the manual after the release. I'll create a tag for PRs for which that is relevant.

dra27 · 2016-11-04T11:05:43Z

This feature isn't in 4.04 anyway, I think?

bschommer · 2016-11-04T11:54:09Z

I changed NUL to null character and now everywhere separated/separator is used. Also line feed is replaced by newline, since the implementation ignores the \r before \n.

gasche · 2016-11-04T12:34:09Z

This feature isn't in 4.04 anyway, I think?

Oh indeed, I had forgotten about that. Thanks.

damiendoligez · 2016-11-04T14:47:34Z

now everywhere separated/separator is used

This is incorrect. The arguments are terminated by newlines or null characters, with the last terminator being optional when its argument is not empty:

empty file -> no arguments
one newline -> one empty argument
two newlines -> two empty arguments
etc.

If you insist on specifying a separator, then it becomes impossible to put an empty list of arguments in the file (and in that case we'll need to change the code).

Maybe we should even go so far as to signal an error when the last argument doesn't have its terminator.

bschommer · 2016-11-04T18:48:18Z

Terminated is now used instead of seperated.

Maybe we should even go so far as to signal an error when the last argument doesn't have its terminator.

I don't think that is a good idea to enforce this since one tends to forget this easily.

xavierleroy · 2016-11-04T19:11:37Z

"Be liberal in what you accept, and conservative in what you send" (Postel's law).

gasche · 2016-11-04T19:58:50Z

It is my understanding that the comments have been taken into account, so I'm going ahead and merging the PR -- thanks! If anyone has more comments, feel free to make them here, we can always update or make a second PR.

Added documentation for the new -args(0) option.

Display the exercise difficulty next to the title of the exercise.

Added documentation for the new -args(0) option.

0c53d67

Additionally typos in the documenation of Args.read_arg(0) and Args.write_arg(0) are fixed.

dra27 reviewed Nov 4, 2016

View reviewed changes

gasche added the manual-update label Nov 4, 2016

gasche mentioned this pull request Nov 4, 2016

Spacetime manual page #884

Merged

Use separated/separator and null character.

17efc32

gasche removed the manual-update label Nov 4, 2016

Terminated instead of seperated.

67f4c2b

gasche merged commit d27c578 into ocaml:trunk Nov 4, 2016

camlspotter pushed a commit to camlspotter/ocaml that referenced this pull request Oct 17, 2017

Merge pull request ocaml#890 from bschommer/args-manual

a57e57f

Added documentation for the new -args(0) option.

vicuna mentioned this pull request Mar 14, 2019

Support for passing more parameters from external files #5937

Closed

stedolan pushed a commit to stedolan/ocaml that referenced this pull request Oct 25, 2022

Rework allocation modes to clarify semantics (ocaml#890)

b1106ab

EmileTrotignon pushed a commit to EmileTrotignon/ocaml that referenced this pull request Jan 12, 2024

Display exercise difficulty (ocaml#890) (ocaml#955)

ee21ec3

Display the exercise difficulty next to the title of the exercise.


		\item["-args0" \var{filename}]
		Read additional NUL separated command line arguments from \var{filename}.

		@@ -186,12 +186,12 @@ val read_arg: string -> string array

		val read_arg0: string -> string array
		(** Identical to {!Arg.read_arg} but assumes NUL terminated command line

Conversation

bschommer commented Nov 4, 2016

Uh oh!

dra27 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xavierleroy commented Nov 4, 2016

Uh oh!

gasche commented Nov 4, 2016

Uh oh!

dra27 commented Nov 4, 2016

Uh oh!

bschommer commented Nov 4, 2016

Uh oh!

gasche commented Nov 4, 2016

Uh oh!

damiendoligez commented Nov 4, 2016

Uh oh!

bschommer commented Nov 4, 2016

Uh oh!

xavierleroy commented Nov 4, 2016

Uh oh!

gasche commented Nov 4, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants