Hi Bernhard, Added the bug report to CC.
Bernhard Gabler <[email protected]> writes: > Also, thank you for trying to explain the meaning and intention of the > '--' option, which I already fully unterstand in its functionality and > the rationale behind. I fully support its existence and would never > argue against it by any means. > My concerns are only about its documentation that I find lacking in > all places: man page, built-in help, and info page/online help (which > seem to be based on the same contents). The man pages are generated from the --help output of each program. The info pages and online manual are separate and usually have more detailed explanations/descriptions. >> I don't think it belongs in common options since it isn't really an >> option. > > I personally will not argue its correct classification. > Fact is that the info page on coreutils common options already describes > three such: > --help, > --version, and > --. > Moreover, it explicitly discusses the single-dash parameter '-' as > being a parameter but not an option. But it does not raise that point > with regard to the double-dash. > > See: > [1] info '(coreutils) Common options' > or > [2] > https://www.gnu.org/software/coreutils/manual/html_node/Common-options.html > > All this transmits the notion that at least the documentation authors > classify the double-dash as an option. Good point, I forgot about that. > Now my concern is exclusively about the documentation: > The online docs (and info page) on printf says: > > The only options are a lone ‘--help’ or ‘--version’. *Note Common > options::. Options must precede operands. > > But it entirely ignores the double-dash, not mentioning it as option > nor parameter nor any other way. Which seems wrong to me. Yes, I think I agree with you on that. If we list those as the lone options, the "Common options" link seems to disagree with it by listing '--'. What do you think of the text for 'yes' [1]? The use of '--' is important for that program too, but it is documented: The only options are a lone --help or --version. To output an argument that begins with ‘-’, precede it with --, e.g., ‘yes -- --help’. See Common options. >> Perhaps there is somewhere we can place it in the manual, so that it >> doesn't rely on the user knowing about this POSIX rule and/or how >> getopt(3) from libc works. >> >> I'll think about it... > > > A low-effort approach might be to add it to the listed --help and > --version options. I will not get into philosophical discussions on > classification. But I strongly suggest to add a mention of the > double-dash in all three places that I listed in my initial posting. I think adding this improves the man pages: $ ./src/printf --help [...] --help display this help and exit --version output version information and exit -- treat all subsequent arguments as non-options But I am not sure if I like it in the '--help' output. Lets see what others on the list think. > Thank you and the entire coretools team for your great efforts on this > fundamental software package! And thank you for the well written bug report. :) Collin [1] https://www.gnu.org/software/coreutils/manual/html_node/yes-invocation.html
