[PATCH] Use recommended long options syntax in man page

[PATCH] Use recommended long options syntax in man page

[Philipp Stephani]

* doc/man/emacs.1.in: Specify equals sign for long options, as
recommended in the manual.
---
 doc/man/emacs.1.in | 50 +++++++++++++++++++++++++-------------------------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/doc/man/emacs.1.in b/doc/man/emacs.1.in
index 7654c9610d..5116953041 100644
--- a/doc/man/emacs.1.in
+++ b/doc/man/emacs.1.in
@@ -61,7 +61,7 @@ The following options are of general interest:
 Edit
 .IR file .
 .TP
-.BI \-\-file " file\fR,\fP " \-\-find-file " file\fR,\fP " \-\-visit " file"
+.BI \-\-file= "file\fR,\fP " \-\-find-file= "file\fR,\fP " \-\-visit= "file"
 The same as specifying
 .I file
 directly as an argument.
@@ -79,7 +79,7 @@ Go to the specified
 and
 .IR column .
 .TP
-.BI \-\-chdir " directory"
+.BI \-\-chdir= "directory"
 Change to
 .IR directory .
 .TP
@@ -112,12 +112,12 @@ Lisp debugger during the processing of the user init file
 .BR ~/.emacs .
 This is useful for debugging problems in the init file.
 .TP
-.BI \-u " user\fR,\fP " \-\-user " user"
+.BI \-u " user\fR,\fP " \-\-user= "user"
 Load
 .IR user 's
 init file.
 .TP
-.BI \-t " file\fR,\fP " \-\-terminal " file"
+.BI \-t " file\fR,\fP " \-\-terminal= "file"
 Use specified
 .I file
 as the terminal instead of using stdin/stdout.
@@ -144,15 +144,15 @@ The following options are Lisp-oriented
 (these options are processed in the order encountered):
 .RS
 .TP 8
-.BI \-f " function\fR,\fP " \-\-funcall " function"
+.BI \-f " function\fR,\fP " \-\-funcall= "function"
 Execute the lisp function
 .IR function .
 .TP
-.BI \-l " file\fR,\fP " \-\-load " file"
+.BI \-l " file\fR,\fP " \-\-load= "file"
 Load the lisp code in the file
 .IR file .
 .TP
-.BI \-\-eval " expr\fR,\fP " \-\-execute " expr"
+.BI \-\-eval= "expr\fR,\fP " \-\-execute= "expr"
 Evaluate the Lisp expression
 .IR expr .
 .RE
@@ -168,12 +168,12 @@ The editor will send messages to stderr.
 You must use \-l and \-f options to specify files to execute
 and functions to call.
 .TP
-.BI \-\-script " file"
+.BI \-\-script= "file"
 Run
 .I file
 as an Emacs Lisp script.
 .TP
-.BI \-\-insert " file"
+.BI \-\-insert= "file"
 Insert contents of
 .I file
 into the current buffer.
@@ -183,7 +183,7 @@ Exit
 .I Emacs
 while in batch mode.
 .TP
-.BI \-L " dir\fR,\fP " \-\-directory " dir"
+.BI \-L " dir\fR,\fP " \-\-directory= "dir"
 Add
 .I dir
 to the list of directories
@@ -206,13 +206,13 @@ process so that you can continue using your original window.
 can be started with the following X switches:
 .RS
 .TP 8
-.BI \-\-name " name"
+.BI \-\-name= "name"
 Specify the name which should be assigned to the initial
 .I Emacs
 window.
 This controls looking up X resources as well as the window title.
 .TP
-.BI \-T " name\fR,\fP " \-\-title " name"
+.BI \-T " name\fR,\fP " \-\-title= "name"
 Specify the title for the initial X window.
 .TP
 .BR \-r ", " \-rv ", " \-\-reverse\-video
@@ -220,7 +220,7 @@ Display the
 .I Emacs
 window in reverse video.
 .TP
-.BI \-fn " font\fR,\fP " \-\-font " font"
+.BI \-fn " font\fR,\fP " \-\-font= "font"
 Set the
 .I Emacs
 window's font to that specified by
@@ -247,7 +247,7 @@ for more information.
 When you specify a font, be sure to put a space between the
 switch and the font name.
 .TP
-.BI \-\-xrm " resources"
+.BI \-\-xrm= "resources"
 Set additional X resources.
 .TP
 .BI "\-\-color\fR,\fP \-\-color=" mode
@@ -256,20 +256,20 @@ Override color mode for character terminals;
 defaults to "auto", and can also be "never", "auto", "always",
 or a mode name like "ansi8".
 .TP
-.BI \-bw " pixels\fR,\fP " \-\-border\-width " pixels"
+.BI \-bw " pixels\fR,\fP " \-\-border\-width= "pixels"
 Set the
 .I Emacs
 window's border width to the number of pixels specified by
 .IR pixels .
 Defaults to one pixel on each side of the window.
 .TP
-.BI \-ib " pixels\fR,\fP " \-\-internal\-border " pixels"
+.BI \-ib " pixels\fR,\fP " \-\-internal\-border= "pixels"
 Set the window's internal border width to the number of pixels specified
 by
 .IR pixels .
 Defaults to one pixel of padding on each side of the window.
 .TP
-.BI \-g " geometry\fR,\fP " \-\-geometry " geometry"
+.BI \-g " geometry\fR,\fP " \-\-geometry= "geometry"
 Set the
 .I Emacs
 window's width, height, and position as specified.
@@ -282,7 +282,7 @@ See the Emacs manual, section "Options for Window Size and Position",
 for information on how window sizes interact
 with selecting or deselecting the tool bar and menu bar.
 .TP
-.BI \-lsp " pixels\fR,\fP " \-\-line\-spacing " pixels"
+.BI \-lsp " pixels\fR,\fP " \-\-line\-spacing= "pixels"
 Additional space to put between lines.
 .TP
 .BR \-vb ", " \-\-vertical\-scroll\-bars
@@ -300,26 +300,26 @@ Make the first frame as wide as the screen.
 .BR \-mm ", " \-\-maximized
 Maximize the first frame, like "\-fw \-fh".
 .TP
-.BI \-fg " color\fR,\fP " \-\-foreground\-color " color"
+.BI \-fg " color\fR,\fP " \-\-foreground\-color= "color"
 On color displays, set the color of the text.
 
 Use the command
 .I M\-x list\-colors\-display
 for a list of valid color names.
 .TP
-.BI \-bg " color\fR,\fP " \-\-background\-color " color"
+.BI \-bg " color\fR,\fP " \-\-background\-color= "color"
 On color displays, set the color of the window's background.
 .TP
-.BI \-bd " color\fR,\fP " \-\-border\-color " color"
+.BI \-bd " color\fR,\fP " \-\-border\-color= "color"
 On color displays, set the color of the window's border.
 .TP
-.BI \-cr " color\fR,\fP " \-\-cursor\-color " color"
+.BI \-cr " color\fR,\fP " \-\-cursor\-color= "color"
 On color displays, set the color of the window's text cursor.
 .TP
-.BI \-ms " color\fR,\fP " \-\-mouse\-color " color"
+.BI \-ms " color\fR,\fP " \-\-mouse\-color= "color"
 On color displays, set the color of the window's mouse cursor.
 .TP
-.BI \-d " displayname\fR,\fP " \-\-display " displayname"
+.BI \-d " displayname\fR,\fP " \-\-display= "displayname"
 Create the
 .I Emacs
 window on the display specified by
@@ -337,7 +337,7 @@ in iconified state.
 .BR \-nbc ", " \-\-no\-blinking\-cursor
 Disable blinking cursor.
 .TP
-.BI \-\-parent-id " xid"
+.BI \-\-parent-id= "xid"
 Set parent window.
 .TP
 .BR \-nw ", " \-\-no\-window\-system
-- 
2.15.1

Re: [PATCH] Use recommended long options syntax in man page

[Paul Eggert]

Philipp Stephani wrote:
> * doc/man/emacs.1.in: Specify equals sign for long options, as
> recommended in the manual.

Why are they recommended? They are so often omitted that at this point any such 
recommendation is somewhat pointless.

Re: [PATCH] Use recommended long options syntax in man page

[Eli Zaretskii]

> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Mon,  8 Jan 2018 00:12:38 +0100
> Cc: Philipp Stephani <phst@google.com>
> 
> * doc/man/emacs.1.in: Specify equals sign for long options, as
> recommended in the manual.

Fine with me, but I think this should mention bug#24949, as it
provides the background for this change.

Thanks.

Re: [PATCH] Use recommended long options syntax in man page

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Why are they recommended? They are so often omitted that at this point

What is omitted, where?

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
Skype: No way! See https://stallman.org/skype.html.

Re: [PATCH] Use recommended long options syntax in man page

[Paul Eggert]

Richard Stallman wrote:
>    > Why are they recommended? They are so often omitted that at this point
> 
> What is omitted, where?

The equals sign between "--longoption" and its operand. That is, I see a shell 
command like this:

emacs -Q --batch --eval '(message "%s" (cos 0))'

far more often than I see one like this:

emacs -Q --batch --eval='(message "%s" (cos 0))'

Although the latter form also works, I don't see any reason to recommend it to 
the former; quite the contrary, as the former is easier to type.

Re: [PATCH] Use recommended long options syntax in man page

[Eli Zaretskii]

> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Mon, 8 Jan 2018 23:30:59 -0800
> Cc: phst@google.com, p.stephani2@gmail.com, emacs-devel@gnu.org
> 
> emacs -Q --batch --eval '(message "%s" (cos 0))'
> 
> far more often than I see one like this:
> 
> emacs -Q --batch --eval='(message "%s" (cos 0))'
> 
> Although the latter form also works, I don't see any reason to recommend it to 
> the former; quite the contrary, as the former is easier to type.

The latter works in more use cases than the former, see bug#24949.  So
recommending it will trip fewer newbies.

Re: [PATCH] Use recommended long options syntax in man page

[Paul Eggert]

On 01/09/2018 09:24 AM, Eli Zaretskii wrote:
> The latter works in more use cases than the former, see bug#24949.  So
> recommending it will trip fewer newbies.

That is true only for options with an optional argument, as Bug#24949#30 
mentions. Most options are not that way, and we needn't recommend the 
spurious "=" for them. On the contrary, it's better to use "=" only in 
examples of options with an optional argument, as a way to help remind 
users that these options are unusual.

Re: [PATCH] Use recommended long options syntax in man page

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

The equal sign makes it clearer that what follows is an argument
for the preceding option.  That is the advantage of it.

This makes no difference when you or I read a script, but it can help
people who are not experienced and not confident.

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
Skype: No way! See https://stallman.org/skype.html.

Re: [PATCH] Use recommended long options syntax in man page

[Eli Zaretskii]

> Cc: rms@gnu.org, phst@google.com, p.stephani2@gmail.com, emacs-devel@gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 9 Jan 2018 14:21:49 -0800
> 
> On 01/09/2018 09:24 AM, Eli Zaretskii wrote:
> > The latter works in more use cases than the former, see bug#24949.  So
> > recommending it will trip fewer newbies.
> 
> That is true only for options with an optional argument, as Bug#24949#30 
> mentions. Most options are not that way, and we needn't recommend the 
> spurious "=" for them.

Newbies or people who only rarely use these options would not know
which arguments are optional, so recommending to always use a '='
makes their muscle memory more future-proof.

Re: [PATCH] Use recommended long options syntax in man page

[Richard Copley]

On 10 January 2018 at 03:36, Eli Zaretskii <eliz@gnu.org> wrote:
>> Cc: rms@gnu.org, phst@google.com, p.stephani2@gmail.com, emacs-devel@gnu.org
>> From: Paul Eggert <eggert@cs.ucla.edu>
>> Date: Tue, 9 Jan 2018 14:21:49 -0800
>>
>> That is true only for options with an optional argument, as Bug#24949#30
>> mentions. Most options are not that way, and we needn't recommend the
>> spurious "=" for them.
>
> Newbies or people who only rarely use these options would not know
> which arguments are optional, so recommending to always use a '='
> makes their muscle memory more future-proof.

Both arguments have merit. Manuals aren't just for newbies. Maybe
there's room to introduce the syntax with the = first, then elaborate
explaining the actual syntax in full. Or maybe that level of detail is
best left for the TexInfo manual.

Re: [PATCH] Use recommended long options syntax in man page

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Both arguments have merit. Manuals aren't just for newbies. Maybe
  > there's room to introduce the syntax with the = first, then elaborate
  > explaining the actual syntax in full. Or maybe that level of detail is
  > best left for the TexInfo manual.

Please use = for long option arguments in the man page.

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
Skype: No way! See https://stallman.org/skype.html.

Re: [PATCH] Use recommended long options syntax in man page

[Philipp Stephani]

[-- Attachment #1: Type: text/plain, Size: 902 bytes --]

Richard Stallman <rms@gnu.org> schrieb am Do., 11. Jan. 2018 um 20:51 Uhr:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > Both arguments have merit. Manuals aren't just for newbies. Maybe
>   > there's room to introduce the syntax with the = first, then elaborate
>   > explaining the actual syntax in full. Or maybe that level of detail is
>   > best left for the TexInfo manual.
>
> Please use = for long option arguments in the man page.
>
>
I've pushed the patch that switches to = to emacs-26 (commit 779b2ac484).
We can argue about what should be recommended, but at the very least the
documentation should be consistent, and we either recommend or require =
everywhere else in the Info manual and other man pages.

[-- Attachment #2: Type: text/html, Size: 1262 bytes --]