Re: Emacs-diffs Digest, Vol 3, Issue 245

Re: Emacs-diffs Digest, Vol 3, Issue 245

[Eli Zaretskii]

> From: emacs-diffs-request@gnu.org
> Date: Sat, 22 Feb 2003 06:50:47 -0500

Simon, allow me a few technical comments about Texinfo usage in your
changes.

> +   The variable @code{smtpmail-smtp-server} controls the hostname of
> + the server to use.  It is a string with an IP address or hostname.  It
> + defaults to the contents of the @code{SMTPSERVER} environment
> + variable, or, if empty, the contents of

I think the SMTPSERVER variable should also be mentioned in the
section where all environment variables used by Emacs are described,
and also there should be a @vindex reference to it.

> + to use both these mechanisms, e.g. to use STARTTLS to achieve

I think you should put a comma after "e.g."; if not, please put a "@:"
after it, so that TeX does not typeset the second period as one that
ends a sentence.

> + of this variable requires the @samp{starttls} external program to be
> + installed, you can get it from
> + @samp{ftp://ftp.opaopa.org/pub/elisp/starttls-*.tar.gz}.

It's better if a URL is inside a @uref, not @samp, I think.

> +   The variable @code{smtpmail-debug-info} controls whether to print
> + the SMTP protocol exchange in the minibuffer, and retain the entire
> + exchange in a buffer @samp{*trace of SMTP session to
> + mail.example.org*}.

Perhaps this would be better:

   The variable @code{smtpmail-debug-info} controls whether to print
 the SMTP protocol exchange in the minibuffer, and retain the entire
 exchange in a buffer @samp{*trace of SMTP session to @var{server}*},
 where @var{server} is the name of the mail server to which you send
 mail.

> +   The variable @code{smtpmail-debug-verb} controls whether to send the
> + VERB token to the server.  The VERB server instructs the server to be
> + more verbose, and often also to attempt final delivery while your SMTP
> + session is still running.

Since "VERB" is a command, I think it should have the @code markup
(or maybe even @samp).

> +   The variable @code{smtpmail-local-domain} controls the hostname sent
> + in the first EHLO or HELO command sent to the server.

The same with HELO and EHLO here.

> + when sending mail, and the *trace of SMTP session to <somewhere>*
> + buffer

The buffer name should be in @samp, and please use @var{somewhere}
instead of <somewhere>.

> +   The variable @code{smtpmail-queue-dir} specifies the name of the
> + directory to hold queued messages.  It defaults to
> + @samp{~/Mail/queued-mail/}.

Files and directories should have the @file markup, not @samp.

Re: Emacs-diffs Digest, Vol 3, Issue 245

[Kai Großjohann]

"Eli Zaretskii" <eliz@is.elta.co.il> writes:

>> + of this variable requires the @samp{starttls} external program to be
>> + installed, you can get it from
>> + @samp{ftp://ftp.opaopa.org/pub/elisp/starttls-*.tar.gz}.
>
> It's better if a URL is inside a @uref, not @samp, I think.

Note the asterisk: it's probably not a working URL.  Maybe the
wording should be changed to specify the directory in @uref, then say
something about the file name?
-- 
A preposition is not a good thing to end a sentence with.

Re: Emacs-diffs Digest, Vol 3, Issue 245

[Eli Zaretskii]

> From: kai.grossjohann@uni-duisburg.de (Kai =?iso-8859-1?q?Gro=DFjohann?=)
> Date: Sat, 22 Feb 2003 21:37:02 +0100
> 
> >> + of this variable requires the @samp{starttls} external program to be
> >> + installed, you can get it from
> >> + @samp{ftp://ftp.opaopa.org/pub/elisp/starttls-*.tar.gz}.
> >
> > It's better if a URL is inside a @uref, not @samp, I think.
> 
> Note the asterisk: it's probably not a working URL.

This only matters in the HTML output.  In other formats, @uref just
produces some typeface.

> Maybe the
> wording should be changed to specify the directory in @uref, then say
> something about the file name?

That'd be good, I think.

Re: Emacs-diffs Digest, Vol 3, Issue 245

[Simon Josefsson]

"Eli Zaretskii" <eliz@is.elta.co.il> writes:

> Simon, allow me a few technical comments about Texinfo usage in your
> changes.

All good suggestions, thanks, I incorporated them.

Re: Emacs-diffs Digest, Vol 3, Issue 245

[Kevin Rodgers]

Eli Zaretskii wrote:

>>From: emacs-diffs-request@gnu.org
>>Date: Sat, 22 Feb 2003 06:50:47 -0500
...
>>+   The variable @code{smtpmail-debug-info} controls whether to print
>>+ the SMTP protocol exchange in the minibuffer, and retain the entire
>>+ exchange in a buffer @samp{*trace of SMTP session to
>>+ mail.example.org*}.
>>
> 
> Perhaps this would be better:
> 
>    The variable @code{smtpmail-debug-info} controls whether to print
>  the SMTP protocol exchange in the minibuffer, and retain the entire
>  exchange in a buffer @samp{*trace of SMTP session to @var{server}*},

 >  where @var{server} is the name of the mail server to which you send
 >  mail.

Why not

   The variable @code{smtpmail-debug-info} controls whether to print the
SMTP protocol exchange in the minibuffer, and retain the entire exchange
in a buffer @samp{*trace of SMTP session to @code{smtpmail-smtp-server}*}.

-- 
<a href="mailto:&lt;kevin.rodgers&#64;ihs.com&gt;">Kevin Rodgers</a>

Re: Emacs-diffs Digest, Vol 3, Issue 245

[Eli Zaretskii]

> From: Kevin Rodgers <kevin.rodgers@ihs.com>
> Date: Mon, 10 Mar 2003 16:45:03 -0700
> > 
> >    The variable @code{smtpmail-debug-info} controls whether to print
> >  the SMTP protocol exchange in the minibuffer, and retain the entire
> >  exchange in a buffer @samp{*trace of SMTP session to @var{server}*},
> 
>  >  where @var{server} is the name of the mail server to which you send
>  >  mail.
> 
> Why not
> 
>    The variable @code{smtpmail-debug-info} controls whether to print the
> SMTP protocol exchange in the minibuffer, and retain the entire exchange
> in a buffer @samp{*trace of SMTP session to @code{smtpmail-smtp-server}*}.

Beacsue "smtpmail-smtp-server" is not a literal string that will
appear in the buffer's name.

Re: Emacs-diffs Digest, Vol 3, Issue 245

[Kevin Rodgers]

Eli Zaretskii wrote:

>>From: Kevin Rodgers <kevin.rodgers@ihs.com>
>>Date: Mon, 10 Mar 2003 16:45:03 -0700
>>
>>Why not
>>
>>   The variable @code{smtpmail-debug-info} controls whether to print the
>>SMTP protocol exchange in the minibuffer, and retain the entire exchange
>>in a buffer @samp{*trace of SMTP session to @code{smtpmail-smtp-server}*}.
>>
> 
> Beacsue "smtpmail-smtp-server" is not a literal string that will
> appear in the buffer's name.

How then should one indicate that an Emacs Lisp variable is being used as a
syntactic variable?  @{var@code{smtpmail-smtp-server}}

-- 
<a href="mailto:&lt;kevin.rodgers&#64;ihs.com&gt;">Kevin Rodgers</a>

Re: Emacs-diffs Digest, Vol 3, Issue 245

[Eli Zaretskii]

> From: Kevin Rodgers <kevin.rodgers@ihs.com>
> Date: Tue, 11 Mar 2003 12:07:55 -0700
> 
> >>From: Kevin Rodgers <kevin.rodgers@ihs.com>
> >>Date: Mon, 10 Mar 2003 16:45:03 -0700
> >>
> >>Why not
> >>
> >>   The variable @code{smtpmail-debug-info} controls whether to print the
> >>SMTP protocol exchange in the minibuffer, and retain the entire exchange
> >>in a buffer @samp{*trace of SMTP session to @code{smtpmail-smtp-server}*}.
> >>
> > 
> > Because "smtpmail-smtp-server" is not a literal string that will
> > appear in the buffer's name.
> 
> How then should one indicate that an Emacs Lisp variable is being used as a
> syntactic variable?  @{var@code{smtpmail-smtp-server}}

No.  @var and @code are mutually exclusive (each one specifies a
different typeface), so the above will not do what you want.  And
@samp already specifies the same typeface as @code anyway.

If I understand what you want, I would say something like this:

    The variable @code{smtpmail-debug-info} controls whether to print the
  SMTP protocol exchange in the minibuffer, and retain the entire exchange
  in a buffer @samp{*trace of SMTP session to @var{server}*} (where
  @var{server} is the value of the variable @code{smtpmail-smtp-server}).

Re: Emacs-diffs Digest, Vol 3, Issue 245

[Richard Stallman]

    How then should one indicate that an Emacs Lisp variable is being used as a
    syntactic variable?  @{var@code{smtpmail-smtp-server}}

It makes no sense to "use a Lisp variable as a metasyntactic variable".

Re: Emacs-diffs Digest, Vol 3, Issue 245

[Kevin Rodgers]

Richard Stallman wrote:
 > Kevin Rodgers writes:

>     How then should one indicate that an Emacs Lisp variable is being used as a
>     syntactic variable?  @{var@code{smtpmail-smtp-server}}
> 
> It makes no sense to "use a Lisp variable as a metasyntactic variable".


Really?  Even when they are identical?


Eli Zaretskii writes:

 
> > where @var{server} is the value of the variable @code{smtpmail-smtp-server}


-- 
<a href="mailto:&lt;kevin.rodgers&#64;ihs.com&gt;">Kevin Rodgers</a>