all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* [PATCH] Use recommended long options syntax in man page
@ 2018-01-07 23:12 Philipp Stephani
  2018-01-08  0:43 ` Paul Eggert
  2018-01-08  4:08 ` Eli Zaretskii
  0 siblings, 2 replies; 12+ messages in thread
From: Philipp Stephani @ 2018-01-07 23:12 UTC (permalink / raw)
  To: emacs-devel; +Cc: 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




^ permalink raw reply related	[flat|nested] 12+ messages in thread

* Re: [PATCH] Use recommended long options syntax in man page
  2018-01-07 23:12 [PATCH] Use recommended long options syntax in man page Philipp Stephani
@ 2018-01-08  0:43 ` Paul Eggert
  2018-01-09  2:51   ` Richard Stallman
  2018-01-08  4:08 ` Eli Zaretskii
  1 sibling, 1 reply; 12+ messages in thread
From: Paul Eggert @ 2018-01-08  0:43 UTC (permalink / raw)
  To: Philipp Stephani, emacs-devel; +Cc: Philipp Stephani

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.



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Use recommended long options syntax in man page
  2018-01-07 23:12 [PATCH] Use recommended long options syntax in man page Philipp Stephani
  2018-01-08  0:43 ` Paul Eggert
@ 2018-01-08  4:08 ` Eli Zaretskii
  1 sibling, 0 replies; 12+ messages in thread
From: Eli Zaretskii @ 2018-01-08  4:08 UTC (permalink / raw)
  To: Philipp Stephani; +Cc: phst, emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Use recommended long options syntax in man page
  2018-01-08  0:43 ` Paul Eggert
@ 2018-01-09  2:51   ` Richard Stallman
  2018-01-09  7:30     ` Paul Eggert
  0 siblings, 1 reply; 12+ messages in thread
From: Richard Stallman @ 2018-01-09  2:51 UTC (permalink / raw)
  To: Paul Eggert; +Cc: phst, p.stephani2, emacs-devel

[[[ 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.




^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Use recommended long options syntax in man page
  2018-01-09  2:51   ` Richard Stallman
@ 2018-01-09  7:30     ` Paul Eggert
  2018-01-09 17:24       ` Eli Zaretskii
  2018-01-10  3:03       ` Richard Stallman
  0 siblings, 2 replies; 12+ messages in thread
From: Paul Eggert @ 2018-01-09  7:30 UTC (permalink / raw)
  To: rms; +Cc: phst, p.stephani2, emacs-devel

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.



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Use recommended long options syntax in man page
  2018-01-09  7:30     ` Paul Eggert
@ 2018-01-09 17:24       ` Eli Zaretskii
  2018-01-09 22:21         ` Paul Eggert
  2018-01-10  3:03       ` Richard Stallman
  1 sibling, 1 reply; 12+ messages in thread
From: Eli Zaretskii @ 2018-01-09 17:24 UTC (permalink / raw)
  To: Paul Eggert; +Cc: phst, p.stephani2, rms, emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Use recommended long options syntax in man page
  2018-01-09 17:24       ` Eli Zaretskii
@ 2018-01-09 22:21         ` Paul Eggert
  2018-01-10  3:36           ` Eli Zaretskii
  0 siblings, 1 reply; 12+ messages in thread
From: Paul Eggert @ 2018-01-09 22:21 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: phst, p.stephani2, rms, emacs-devel

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.




^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Use recommended long options syntax in man page
  2018-01-09  7:30     ` Paul Eggert
  2018-01-09 17:24       ` Eli Zaretskii
@ 2018-01-10  3:03       ` Richard Stallman
  1 sibling, 0 replies; 12+ messages in thread
From: Richard Stallman @ 2018-01-10  3:03 UTC (permalink / raw)
  To: Paul Eggert; +Cc: phst, p.stephani2, emacs-devel

[[[ 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.




^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Use recommended long options syntax in man page
  2018-01-09 22:21         ` Paul Eggert
@ 2018-01-10  3:36           ` Eli Zaretskii
  2018-01-10 19:26             ` Richard Copley
  0 siblings, 1 reply; 12+ messages in thread
From: Eli Zaretskii @ 2018-01-10  3:36 UTC (permalink / raw)
  To: Paul Eggert; +Cc: phst, p.stephani2, rms, emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Use recommended long options syntax in man page
  2018-01-10  3:36           ` Eli Zaretskii
@ 2018-01-10 19:26             ` Richard Copley
  2018-01-11 19:51               ` Richard Stallman
  0 siblings, 1 reply; 12+ messages in thread
From: Richard Copley @ 2018-01-10 19:26 UTC (permalink / raw)
  To: Eli Zaretskii
  Cc: Philipp Stephani, p.stephani2, Paul Eggert, Richard Stallman,
	Emacs Development

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.



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Use recommended long options syntax in man page
  2018-01-10 19:26             ` Richard Copley
@ 2018-01-11 19:51               ` Richard Stallman
  2018-01-17 22:33                 ` Philipp Stephani
  0 siblings, 1 reply; 12+ messages in thread
From: Richard Stallman @ 2018-01-11 19:51 UTC (permalink / raw)
  To: Richard Copley; +Cc: phst, eliz, eggert, p.stephani2, emacs-devel

[[[ 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.




^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [PATCH] Use recommended long options syntax in man page
  2018-01-11 19:51               ` Richard Stallman
@ 2018-01-17 22:33                 ` Philipp Stephani
  0 siblings, 0 replies; 12+ messages in thread
From: Philipp Stephani @ 2018-01-17 22:33 UTC (permalink / raw)
  To: rms; +Cc: Richard Copley, phst, eliz, eggert, emacs-devel

[-- 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 --]

^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2018-01-17 22:33 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-01-07 23:12 [PATCH] Use recommended long options syntax in man page Philipp Stephani
2018-01-08  0:43 ` Paul Eggert
2018-01-09  2:51   ` Richard Stallman
2018-01-09  7:30     ` Paul Eggert
2018-01-09 17:24       ` Eli Zaretskii
2018-01-09 22:21         ` Paul Eggert
2018-01-10  3:36           ` Eli Zaretskii
2018-01-10 19:26             ` Richard Copley
2018-01-11 19:51               ` Richard Stallman
2018-01-17 22:33                 ` Philipp Stephani
2018-01-10  3:03       ` Richard Stallman
2018-01-08  4:08 ` Eli Zaretskii

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.