update of emacsclient.1

update of emacsclient.1

[Emilio Lopes]

enclosed is a patch updating the man page of Emacsclient.  I hope the
changes are appropriate.

I have one question though.  Under "DESCRIPTION" it says:

   You  typically  do not call emacsclient directly.  Instead, you set the
   environment variable EDITOR to emacsclient and let programs like 'vipw'
   or  'bug'  or anything run it for you, which will use an existing Emacs
   to visit the file.

I myself call `emacsclient' often from the shell.  And should these
`vipw' and `bug' programs be really mentioned?  I use Debian GNU/Linux,
the system for which the man page was originally written, but I don't
have this `bug' program.

What people think of changing the above paragraph to

   You can either call emacsclient directly or set the environment
   variable EDITOR to 'emacsclient' and let other programs run it for
   you, thus using an existing Emacs to edit the file.

?

Here is the patch:

2005-08-17  Emilio C. Lopes  <eclig@gmx.net>

	* emacsclient.1 (DESCRIPTION): reflect inclusion in the Emacs
	distribution.
	(OPTIONS): documented `-s', `-V' and `-h' as well as their long
	name counterparts.
	(BUGS): removed since its contents doesn't
	apply anymore.
  
diff -rN -c old-emacs-darcs.eclig/etc/emacsclient.1 new-emacs-darcs.eclig/etc/emacsclient.1
*** old-emacs-darcs.eclig/etc/emacsclient.1	Wed Aug 17 12:27:14 2005
--- new-emacs-darcs.eclig/etc/emacsclient.1	Wed Aug 17 12:18:48 2005
***************
*** 9,21 ****
  .SH "DESCRIPTION"
  This manual page documents briefly the
  .BR emacsclient
! command.
! This manual page was written for the Debian GNU/Linux distribution
! because the original program does not have a manual page.
! Instead, it has documentation in the GNU Info format; see below.
  .PP
  .B emacsclient 
! works in conjunction with the built-in server of Emacs.
  .PP
  You typically do not call 
  .B emacsclient
--- 9,21 ----
  .SH "DESCRIPTION"
  This manual page documents briefly the
  .BR emacsclient
! command.  Full documentation is available in the GNU Info format; see
! below.
! This manual page was originally written for the Debian GNU/Linux
! distribution, but is not specific to that system.
  .PP
  .B emacsclient 
! works in conjunction with the built-in Emacs server.
  .PP
  You typically do not call 
  .B emacsclient
***************
*** 54,79 ****
  do not visit files but instead evaluate the arguments as Emacs
  Lisp expressions.
  .TP
  .B \-a, \-\-alternate-editor=EDITOR
  if the Emacs server is not running, run the specified editor instead.
  This can also be specified via the `ALTERNATE_EDITOR' environment variable.
  .TP
  .B \-d, \-\-display=DISPLAY
  tell the server to display the files on the given display.
  .SH "SEE ALSO"
  The program is documented fully in
  .IR "Using Emacs as a Server"
  available via the Info system.
- .SH BUGS
- If there is no running Emacs server, 
- .B emacsclient 
- cannot launch one. I use a small Perl script instead of raw 
- .B emacsclient
- to do it (it works only with systems which have BSD sockets, which is fine
- for Debian GNU/Linux).
  .SH AUTHOR
  This manual page was written by Stephane Bortzmeyer <bortzmeyer@debian.org>,
! for the Debian GNU/Linux system (but may be used by others).
  .SH COPYING
  This manual page is in the public domain.
  
--- 54,81 ----
  do not visit files but instead evaluate the arguments as Emacs
  Lisp expressions.
  .TP
+ .B \-s, \-\-socket-name=FILENAME
+ Use socket named FILENAME for communication.
+ .TP
  .B \-a, \-\-alternate-editor=EDITOR
  if the Emacs server is not running, run the specified editor instead.
  This can also be specified via the `ALTERNATE_EDITOR' environment variable.
  .TP
  .B \-d, \-\-display=DISPLAY
  tell the server to display the files on the given display.
+ .TP
+ .B \-V, \-\-version
+ print version information and exit
+ .TP
+ .B \-h, \-\-help
+ print this usage information message and exit
  .SH "SEE ALSO"
  The program is documented fully in
  .IR "Using Emacs as a Server"
  available via the Info system.
  .SH AUTHOR
  This manual page was written by Stephane Bortzmeyer <bortzmeyer@debian.org>,
! for the Debian GNU/Linux system.
  .SH COPYING
  This manual page is in the public domain.

Re: update of emacsclient.1

[Lennart Borgman]

Emilio Lopes wrote:

>What people think of changing the above paragraph to
>
>   You can either call emacsclient directly or set the environment
>   variable EDITOR to 'emacsclient' and let other programs run it for
>   you, thus using an existing Emacs to edit the file.
>  
>
I think it is good to change the original text. However I would like to 
suggest to use a more OS neutral text. I do not believe the proposed use 
of EDITOR always work. Maybe you can say something like "Many programs 
look in the environment variable EDITOR ... "?

I think it would also be good to mention the desktop integration. I do 
not know exactly how this look on other OS:es but on my w32 system 
clicking a file of a type associated with Emacs will open this by 
calling gnuclientw (which is soon to be replaced by emacsclientw on w32 
I hope).

RE: update of emacsclient.1

[Drew Adams]

    Under "DESCRIPTION" it says:
       You  typically  do not call emacsclient directly.  Instead,
       you set the environment variable EDITOR to emacsclient and
       let programs like 'vipw' or  'bug'  or anything run it for
       you, which will use an existing Emacs to visit the file.
    I myself call `emacsclient' often from the shell.  And should these
    `vipw' and `bug' programs be really mentioned?  I use Debian GNU/Linux,
    the system for which the man page was originally written, but I don't
    have this `bug' program.
    What people think of changing the above paragraph to

       You can either call emacsclient directly or set the environment
       variable EDITOR to 'emacsclient' and let other programs run it for
       you, thus using an existing Emacs to edit the file.

I agree. On Windows, for instance, 1) users will most often access it via
file associations or shortcuts; 2) users won't have those programs, either.

Re: update of emacsclient.1

[Emilio Lopes]

I wrote:

> enclosed is a patch updating the man page of Emacsclient.  I hope
> the changes are appropriate. [...]

After collecting suggestions from others, I came up with the following
changes.  They already include the patch I sent before.

2005-08-17  Emilio C. Lopes  <eclig@gmx.net>

	* emacsclient.1 (DESCRIPTION): reflect inclusion in the Emacs
	distribution. Made the role of EDITOR clearer.
	(OPTIONS): documented `-s', `-V' and `-h' as well as their long
	name counterparts.
	(BUGS): removed since its contents doesn't
	apply anymore.
  
diff -rN -c old-emacs-darcs.eclig/etc/emacsclient.1 new-emacs-darcs.eclig/etc/emacsclient.1
*** old-emacs-darcs.eclig/etc/emacsclient.1	Wed Aug 17 18:54:07 2005
--- new-emacs-darcs.eclig/etc/emacsclient.1	Wed Aug 17 18:51:17 2005
***************
*** 9,29 ****
  .SH "DESCRIPTION"
  This manual page documents briefly the
  .BR emacsclient
! command.
! This manual page was written for the Debian GNU/Linux distribution
! because the original program does not have a manual page.
! Instead, it has documentation in the GNU Info format; see below.
  .PP
  .B emacsclient 
! works in conjunction with the built-in server of Emacs.
  .PP
! You typically do not call 
  .B emacsclient
! directly.  Instead, you set the environment variable EDITOR
! to 
! .B emacsclient
! and let programs like 'vipw' or 'bug' or anything run
! it for you, which will use an existing Emacs to visit the file.
  
  For
  .B emacsclient 
--- 9,31 ----
  .SH "DESCRIPTION"
  This manual page documents briefly the
  .BR emacsclient
! command.  Full documentation is available in the GNU Info format; see
! below.
! This manual page was originally written for the Debian GNU/Linux
! distribution, but is not specific to that system.
  .PP
  .B emacsclient 
! works in conjunction with the built-in Emacs server.
  .PP
! You can either call
  .B emacsclient
! directly or let other programs run it for you when necessary.  On
! GNU/Linux and Unix systems many programs consult the environment
! variable EDITOR (sometimes also VISUAL) to obtain the command used for
! editing.  Thus, setting this environment variable to 'emacsclient'
! will allow these programs to use an already running Emacs for editing.
! Other operating systems might have their own methods for defining the
! default editor.
  
  For
  .B emacsclient 
***************
*** 54,79 ****
  do not visit files but instead evaluate the arguments as Emacs
  Lisp expressions.
  .TP
  .B \-a, \-\-alternate-editor=EDITOR
  if the Emacs server is not running, run the specified editor instead.
  This can also be specified via the `ALTERNATE_EDITOR' environment variable.
  .TP
  .B \-d, \-\-display=DISPLAY
  tell the server to display the files on the given display.
  .SH "SEE ALSO"
  The program is documented fully in
  .IR "Using Emacs as a Server"
  available via the Info system.
- .SH BUGS
- If there is no running Emacs server, 
- .B emacsclient 
- cannot launch one. I use a small Perl script instead of raw 
- .B emacsclient
- to do it (it works only with systems which have BSD sockets, which is fine
- for Debian GNU/Linux).
  .SH AUTHOR
! This manual page was written by Stephane Bortzmeyer <bortzmeyer@debian.org>,
! for the Debian GNU/Linux system (but may be used by others).
  .SH COPYING
  This manual page is in the public domain.
  
--- 56,83 ----
  do not visit files but instead evaluate the arguments as Emacs
  Lisp expressions.
  .TP
+ .B \-s, \-\-socket-name=FILENAME
+ Use socket named FILENAME for communication.
+ .TP
  .B \-a, \-\-alternate-editor=EDITOR
  if the Emacs server is not running, run the specified editor instead.
  This can also be specified via the `ALTERNATE_EDITOR' environment variable.
  .TP
  .B \-d, \-\-display=DISPLAY
  tell the server to display the files on the given display.
+ .TP
+ .B \-V, \-\-version
+ print version information and exit
+ .TP
+ .B \-h, \-\-help
+ print this usage information message and exit
  .SH "SEE ALSO"
  The program is documented fully in
  .IR "Using Emacs as a Server"
  available via the Info system.
  .SH AUTHOR
! This manual page was written by Stephane Bortzmeyer <bortzmeyer@debian.org>
! for the Debian GNU/Linux system.
  .SH COPYING
  This manual page is in the public domain.

Re: update of emacsclient.1

[Lennart Borgman]

Emilio Lopes wrote:

>
>! You can either call
>  .B emacsclient
>! directly or let other programs run it for you when necessary.  On
>! GNU/Linux and Unix systems many programs consult the environment
>! variable EDITOR (sometimes also VISUAL) to obtain the command used for
>! editing.  Thus, setting this environment variable to 'emacsclient'
>! will allow these programs to use an already running Emacs for editing.
>! Other operating systems might have their own methods for defining the
>! default editor.
>  
>
Thanks, I believe this is much less confusing for those users that use 
"other operating systems". Beside that it tells them that this perhaps 
does not work on their system it tells how it works on GNU/Linux.

Re: update of emacsclient.1

[Richard M. Stallman]

These changes are ok.  I think it would be better to say "on GNU and Unix systems"
because this is not limited to GNU systems where the kernel is Linux.

Re: update of emacsclient.1

[Emilio Lopes]

Richard M Stallman writes:

> These changes are ok.  I think it would be better to say "on GNU and
> Unix systems" because this is not limited to GNU systems where the
> kernel is Linux.

Sure.  Here is a patch including this change:

2005-08-19  Emilio C. Lopes  <eclig@gmx.net>

	* emacsclient.1 (DESCRIPTION): reflect inclusion in the Emacs
	distribution. Made role of EDITOR clearer.
	(OPTIONS): documented `-s', `-V' and `-h' as well as their long
	name counterparts.
	(BUGS): removed since its contents doesn't
	apply anymore.
  
diff -rN -c old-emacs-darcs.eclig/etc/emacsclient.1 new-emacs-darcs.eclig/etc/emacsclient.1
*** old-emacs-darcs.eclig/etc/emacsclient.1	Fri Aug 19 18:26:38 2005
--- new-emacs-darcs.eclig/etc/emacsclient.1	Fri Aug 19 18:23:34 2005
***************
*** 9,29 ****
  .SH "DESCRIPTION"
  This manual page documents briefly the
  .BR emacsclient
! command.
! This manual page was written for the Debian GNU/Linux distribution
! because the original program does not have a manual page.
! Instead, it has documentation in the GNU Info format; see below.
  .PP
  .B emacsclient 
! works in conjunction with the built-in server of Emacs.
  .PP
! You typically do not call 
  .B emacsclient
! directly.  Instead, you set the environment variable EDITOR
! to 
! .B emacsclient
! and let programs like 'vipw' or 'bug' or anything run
! it for you, which will use an existing Emacs to visit the file.
  
  For
  .B emacsclient 
--- 9,31 ----
  .SH "DESCRIPTION"
  This manual page documents briefly the
  .BR emacsclient
! command.  Full documentation is available in the GNU Info format; see
! below.
! This manual page was originally written for the Debian GNU/Linux
! distribution, but is not specific to that system.
  .PP
  .B emacsclient 
! works in conjunction with the built-in Emacs server.
  .PP
! You can either call
  .B emacsclient
! directly or let other programs run it for you when necessary.  On
! GNU and Unix systems many programs consult the environment
! variable EDITOR (sometimes also VISUAL) to obtain the command used for
! editing.  Thus, setting this environment variable to 'emacsclient'
! will allow these programs to use an already running Emacs for editing.
! Other operating systems might have their own methods for defining the
! default editor.
  
  For
  .B emacsclient 
***************
*** 54,79 ****
  do not visit files but instead evaluate the arguments as Emacs
  Lisp expressions.
  .TP
  .B \-a, \-\-alternate-editor=EDITOR
  if the Emacs server is not running, run the specified editor instead.
  This can also be specified via the `ALTERNATE_EDITOR' environment variable.
  .TP
  .B \-d, \-\-display=DISPLAY
  tell the server to display the files on the given display.
  .SH "SEE ALSO"
  The program is documented fully in
  .IR "Using Emacs as a Server"
  available via the Info system.
- .SH BUGS
- If there is no running Emacs server, 
- .B emacsclient 
- cannot launch one. I use a small Perl script instead of raw 
- .B emacsclient
- to do it (it works only with systems which have BSD sockets, which is fine
- for Debian GNU/Linux).
  .SH AUTHOR
! This manual page was written by Stephane Bortzmeyer <bortzmeyer@debian.org>,
! for the Debian GNU/Linux system (but may be used by others).
  .SH COPYING
  This manual page is in the public domain.
  
--- 56,83 ----
  do not visit files but instead evaluate the arguments as Emacs
  Lisp expressions.
  .TP
+ .B \-s, \-\-socket-name=FILENAME
+ Use socket named FILENAME for communication.
+ .TP
  .B \-a, \-\-alternate-editor=EDITOR
  if the Emacs server is not running, run the specified editor instead.
  This can also be specified via the `ALTERNATE_EDITOR' environment variable.
  .TP
  .B \-d, \-\-display=DISPLAY
  tell the server to display the files on the given display.
+ .TP
+ .B \-V, \-\-version
+ print version information and exit
+ .TP
+ .B \-h, \-\-help
+ print this usage information message and exit
  .SH "SEE ALSO"
  The program is documented fully in
  .IR "Using Emacs as a Server"
  available via the Info system.
  .SH AUTHOR
! This manual page was written by Stephane Bortzmeyer <bortzmeyer@debian.org>
! for the Debian GNU/Linux system.
  .SH COPYING
  This manual page is in the public domain.

Re: update of emacsclient.1

[Richard M. Stallman]

Would someone please install your changes?

Re: update of emacsclient.1

[Emilio Lopes]

Richard M Stallman writes:

> Would someone please install your changes?

It seems `someone' forgot this... :-(

Re: update of emacsclient.1

[Thien-Thi Nguyen]

Emilio Lopes <eclig@gmx.net> writes:

> It seems `someone' forgot this... :-(

sometimes `someone' just needs a friendly reminder. :-)

i have installed the patch.

thi

Re: update of emacsclient.1

[Jose E. Marchesi]

    These changes are ok.  I think it would be better to say "on GNU and Unix systems"
    because this is not limited to GNU systems where the kernel is Linux.

I think would be good to avoid the use of the plural of "Unix", and
subst it with POSIX, such as "on GNU and POSIX systems". Afterall,
there is only one Unix(TM), owned by SCO (afaik).

Re: update of emacsclient.1

[Ken Raeburn]

On Aug 19, 2005, at 12:42, Jose E. Marchesi wrote:
> I think would be good to avoid the use of the plural of "Unix", and
> subst it with POSIX, such as "on GNU and POSIX systems". Afterall,
> there is only one Unix(TM), owned by SCO (afaik).

The Open Group holds the trademark on "UNIX", and several vendors are  
licensed to use it.

Re: update of emacsclient.1

[Richard M. Stallman]

    What people think of changing the above paragraph to

       You can either call emacsclient directly or set the environment
       variable EDITOR to 'emacsclient' and let other programs run it for
       you, thus using an existing Emacs to edit the file.


I think that is good.  Would someone please install it?
Thanks.

Re: update of emacsclient.1

[Lennart Borgman]

Richard M. Stallman wrote:

>    What people think of changing the above paragraph to
>
>       You can either call emacsclient directly or set the environment
>       variable EDITOR to 'emacsclient' and let other programs run it for
>       you, thus using an existing Emacs to edit the file.
>
>
>I think that is good.  Would someone please install it?
>Thanks.
>  
>
Could we please use the next version Emilio sent instead? It is more 
independent of the OS used. This will cause less confusion and save 
peoples time I believe. Then we can do more.