bug#12973: @: overused in manual

bug#12973: @: overused in manual

[Paul Eggert]

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

Tags: patch
Severity: minor

The Emacs manual uses "@:" in many places where it needn't.
Sometimes the @: has no effect, e.g., "Jay K.@: Adams".
Other times, it's being used in places where punctuation
would be better, e.g., "(e.g.@: spaces)".  I'm attaching a
proposed patch.

[-- Attachment #2: at-colon.txt.gz --]
[-- Type: application/x-gzip, Size: 55550 bytes --]

bug#12973: @: overused in manual

[Eli Zaretskii]

> Date: Fri, 23 Nov 2012 11:25:21 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> 
> The Emacs manual uses "@:" in many places where it needn't.
> Sometimes the @: has no effect, e.g., "Jay K.@: Adams".

Why do you say it has no effect in this case?

bug#12973: @: overused in manual

[Paul Eggert]

On 11/23/2012 11:46 AM, Eli Zaretskii wrote:
> Why do you say it has no effect in this case?

It has no effect in TeX because TeX already does
the right thing with initials.  TeX assumes that
"." ends a sentence unless it's preceded by a capital
letter.  "Jay K. Adams" has a capital letter before
the period so no @: is needed after the period.

bug#12973: @: overused in manual

[Eli Zaretskii]

> Date: Fri, 23 Nov 2012 12:50:34 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: 12973@debbugs.gnu.org
> 
> On 11/23/2012 11:46 AM, Eli Zaretskii wrote:
> > Why do you say it has no effect in this case?
> 
> It has no effect in TeX because TeX already does
> the right thing with initials.  TeX assumes that
> "." ends a sentence unless it's preceded by a capital
> letter.  "Jay K. Adams" has a capital letter before
> the period so no @: is needed after the period.

This ought to be in the Texinfo manual, then.  I suggest to report
this to Texinfo maintainers, because the latest manual doesn't mention
that.

bug#12973: @: overused in manual

[Stephen Berman]

On Fri, 23 Nov 2012 12:50:34 -0800 Paul Eggert <eggert@cs.ucla.edu> wrote:

> On 11/23/2012 11:46 AM, Eli Zaretskii wrote:
>> Why do you say it has no effect in this case?
>
> It has no effect in TeX because TeX already does
> the right thing with initials.  TeX assumes that
> "." ends a sentence unless it's preceded by a capital
> letter.  "Jay K. Adams" has a capital letter before
> the period so no @: is needed after the period.

What does TeX do with sentences like these:

"Mary would never do that, nor would I.  Would you?"
"We met the mysterious Madame X.  She's younger than I thought."
"Walk ten paces to point A.  Turn left, then walk 7 paces to point B."

Steve Berman

bug#12973: @: overused in manual

[Paul Eggert]

On 11/23/2012 03:51 PM, Stephen Berman wrote:
> What does TeX do with sentences like these:
> 
> "Mary would never do that, nor would I.  Would you?"
> "We met the mysterious Madame X.  She's younger than I thought."
> "Walk ten paces to point A.  Turn left, then walk 7 paces to point B."

It assumes that "I.", "X.", "A.", and "B." do not end sentences.
To fix this in Texinfo, use "I@." instead of "I.", and similarly
for the others.

This is documented in the Texinfo manual, though apparently the
documentation isn't clear enough.

bug#12973: @: overused in manual

[Stephen Berman]

On Fri, 23 Nov 2012 15:56:08 -0800 Paul Eggert <eggert@cs.ucla.edu> wrote:

> On 11/23/2012 03:51 PM, Stephen Berman wrote:
>> What does TeX do with sentences like these:
>> 
>> "Mary would never do that, nor would I.  Would you?"
>> "We met the mysterious Madame X.  She's younger than I thought."
>> "Walk ten paces to point A.  Turn left, then walk 7 paces to point B."
>
> It assumes that "I.", "X.", "A.", and "B." do not end sentences.
> To fix this in Texinfo, use "I@." instead of "I.", and similarly
> for the others.
>
> This is documented in the Texinfo manual, though apparently the
> documentation isn't clear enough.

I hadn't actually looked before, but I just did, and it's quite clear in
(texinfo)Ending a Sentence.

Steve Berman

bug#12973: @: overused in manual

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Cc: Eli Zaretskii <eliz@gnu.org>,  12973@debbugs.gnu.org
> Date: Sat, 24 Nov 2012 01:11:53 +0100
> 
> On Fri, 23 Nov 2012 15:56:08 -0800 Paul Eggert <eggert@cs.ucla.edu> wrote:
> 
> > On 11/23/2012 03:51 PM, Stephen Berman wrote:
> >> What does TeX do with sentences like these:
> >> 
> >> "Mary would never do that, nor would I.  Would you?"
> >> "We met the mysterious Madame X.  She's younger than I thought."
> >> "Walk ten paces to point A.  Turn left, then walk 7 paces to point B."
> >
> > It assumes that "I.", "X.", "A.", and "B." do not end sentences.
> > To fix this in Texinfo, use "I@." instead of "I.", and similarly
> > for the others.
> >
> > This is documented in the Texinfo manual, though apparently the
> > documentation isn't clear enough.
> 
> I hadn't actually looked before, but I just did, and it's quite clear in
> (texinfo)Ending a Sentence.

But if one looks up @:, which is in another section, they will not see
that "X." doesn't need a @:.  And that is a problem, because "Not
Ending a Sentence" should have pointed to "Ending a Sentence" or told
explicitly that @: is not required in those cases.

bug#12973: @: overused in manual

[Richard Stallman]

    But if one looks up @:, which is in another section, they will not see
    that "X." doesn't need a @:.  And that is a problem, because "Not
    Ending a Sentence" should have pointed to "Ending a Sentence" or told
    explicitly that @: is not required in those cases.

I explicitly decided NOT to say this.  I don't remember for certain
why I made that decision, but it was not an omission.  Maybe it
was to simplify the rules for Texinfo; maybe it is for some
other formatter's sake.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#12973: @: overused in manual

[Eli Zaretskii]

> Date: Sat, 24 Nov 2012 13:37:14 -0500
> From: Richard Stallman <rms@gnu.org>
> CC: stephen.berman@gmx.net, eggert@cs.ucla.edu, 12973@debbugs.gnu.org
> 
>     But if one looks up @:, which is in another section, they will not see
>     that "X." doesn't need a @:.  And that is a problem, because "Not
>     Ending a Sentence" should have pointed to "Ending a Sentence" or told
>     explicitly that @: is not required in those cases.
> 
> I explicitly decided NOT to say this.  I don't remember for certain
> why I made that decision, but it was not an omission.

That suggests we shouldn't make those parts of the proposed changes,
where initials are involved.

bug#12973: @: overused in manual

[Richard Stallman]

    It has no effect in TeX because TeX already does
    the right thing with initials.  TeX assumes that
    "." ends a sentence unless it's preceded by a capital
    letter.  "Jay K. Adams" has a capital letter before
    the period so no @: is needed after the period.

Maybe other Texinfo formatters do not treat the capital letter as
special.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#12973: @: overused in manual

[Paul Eggert]

On 11/23/2012 05:43 PM, Richard Stallman wrote:
> Maybe other Texinfo formatters do not treat the capital letter as
> special.

As far as I know, they're all consistent in this matter,
i.e., all formatters treat the "Q." in "John Q. Smith"
as not ending a sentence, and none of them insert extra
space after the "Q.".

In hindsight, perhaps Texinfo should also have been consistent
about the way that it formats "Write it in C.  The compile it."
That is, perhaps it should have formatted that "C.<space><space>"
as end of sentence, regardless of what TeX would do with the same
input.  But I suppose it's too late to change that now.

bug#12973: @: overused in manual

[Glenn Morris]

Paul Eggert wrote:

> Other times, it's being used in places where punctuation
> would be better, e.g., "(e.g.@: spaces)".

Stylistically, I prefer the current form in at least some cases.

Anyway, I think a patch of this kind if applied to trunk is likely to
lead to repeated merge conflicts coming from emacs-24. So maybe wait
till there is no active branch.

bug#12973: @: overused in manual

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Date: Fri, 23 Nov 2012 21:03:33 -0500
> Cc: 12973@debbugs.gnu.org
> 
> Paul Eggert wrote:
> 
> > Other times, it's being used in places where punctuation
> > would be better, e.g., "(e.g.@: spaces)".
> 
> Stylistically, I prefer the current form in at least some cases.

Me too (which isn't surprising, since I wrote some of them ;-).

bug#12973: @: overused in manual

[Paul Eggert]

> maybe wait till there is no active branch.

Yes, it sounds good to wait.

>> Stylistically, I prefer the current form in at least some cases.
> Me too (which isn't surprising, since I wrote some of them ;-).

I got the suggestion of putting a comma after "i.e." and after "e.g."
from RMS, many years ago.  RMS's style agrees with that of the
Chicago Manual of Style, the Columbia Guide to Standard American
English, the Lynch Guide to Grammar, and the Blue Book on Grammar
and Punctuation, among others.

American style guides seem to prefer the commas almost universally.
British guides are not that way (Fowler 3rd, in particular, says to omit
comma after i.e.; it says nothing about e.g.).  The Emacs manual
is written in American English, though, not in British English.

bug#12973: @: overused in manual

[Eli Zaretskii]

> Date: Fri, 23 Nov 2012 22:45:40 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: Glenn Morris <rgm@gnu.org>, 12973@debbugs.gnu.org
> 
> American style guides seem to prefer the commas almost universally.
> British guides are not that way (Fowler 3rd, in particular, says to omit
> comma after i.e.; it says nothing about e.g.).  The Emacs manual
> is written in American English, though, not in British English.

It is pointless to argue about personal style preferences.

In any case, in my experience, this kind of changes is quickly made
futile by future changes to the manuals that re-introduce comma-less
e.g. and i.e. back into the text.  So if we want to adhere to the
style that prefers the comma, we should IMO install some change that
enforces these rules, to be run at "make info" time and flag any
deviations.

bug#12973: @: overused in manual

[Stefan Monnier]

> In any case, in my experience, this kind of changes is quickly made
> futile by future changes to the manuals that re-introduce comma-less
> e.g. and i.e. back into the text.  So if we want to adhere to the
> style that prefers the comma, we should IMO install some change that
> enforces these rules, to be run at "make info" time and flag any
> deviations.

And I think we had better just ignore those differences and move on.
Enforcing such rules is a waste of time.


        Stefan

bug#12973: @: overused in manual

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Paul Eggert <eggert@cs.ucla.edu>,  12973@debbugs.gnu.org
> Date: Sat, 24 Nov 2012 10:17:02 -0500
> 
> > In any case, in my experience, this kind of changes is quickly made
> > futile by future changes to the manuals that re-introduce comma-less
> > e.g. and i.e. back into the text.  So if we want to adhere to the
> > style that prefers the comma, we should IMO install some change that
> > enforces these rules, to be run at "make info" time and flag any
> > deviations.
> 
> And I think we had better just ignore those differences and move on.

Ignore them and install the changes proposed by Paul, or ignore them
and don't install?

bug#12973: @: overused in manual

[Stefan Monnier]

> Ignore them and install the changes proposed by Paul, or ignore them
> and don't install?

Whichever gets us to "move on" more quickly.


        Stefan

bug#12973: @: overused in manual

[Richard Stallman]

Consistent style and proper usage do not alone make a manual good, but
the lack of them makes any manual worse.  We should correct these
style issues for each Emacs release.

It would be good to invite some people who are good at this
to do the work and install the fixes directly.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#12973: @: overused in manual

[Paul Eggert]

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

On 11/24/2012 10:37 AM, Richard Stallman wrote:
> We should correct these style issues for each Emacs release.

Our release strategy makes it difficult to fix these style
changes now: if we made changes like these, either to
the trunk or to the emacs-24 branch, that'd make it harder
to merge other emacs-24 changes into the trunk later.  For
this reason it's been suggested that I hold off on changes
like these, I guess until after the next Emacs release.

While we're on the topic, the Emacs manual has similar problems with
"@.".  Sometimes it uses "@." when it's not necessary, or even
incorrect (the attached patch at-dot1.txt fixes instances of this
that I found).  More often, the manual incorrectly omits "@."
(see attached patch at-dot.txt.gz).

I'm attaching a combined patch at-combined.txt.gz to make it
easier for me to remember about installing these patches later.
I'm not installing these patches now, though, for the reasons
discussed above.

[-- Attachment #2: at-dot1.txt --]
[-- Type: text/plain, Size: 4599 bytes --]

=== modified file 'doc/misc/org.texi'
--- doc/misc/org.texi	2012-11-24 23:57:21 +0000
+++ doc/misc/org.texi	2012-11-25 00:24:17 +0000
@@ -838,7 +838,7 @@
 @cindex FAQ
 There is a website for Org which provides links to the newest
 version of Org, as well as additional information, frequently asked
-questions (FAQ), links to tutorials, etc@.  This page is located at
+questions (FAQ), links to tutorials, etc.  This page is located at
 @uref{http://orgmode.org}.
 
 @cindex print edition
@@ -2445,7 +2445,7 @@
 However, this syntax is deprecated, it should not be used for new documents.
 Use @code{@@>$} instead.} row in the table, respectively.  You may also
 specify the row relative to one of the hlines: @code{@@I} refers to the first
-hline, @code{@@II} to the second, etc@.  @code{@@-I} refers to the first such
+hline, @code{@@II} to the second, etc.  @code{@@-I} refers to the first such
 line above the current line, @code{@@+I} to the first such line below the
 current line.  You can also write @code{@@III+2} which is the second data line
 after the third hline in the table.
@@ -15168,7 +15168,7 @@
 Things become cleaner still if you skip all the even levels and use only odd
 levels 1, 3, 5..., effectively adding two stars to go from one outline level
 to the next@footnote{When you need to specify a level for a property search
-or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc@.}.  In this
+or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc.}.  In this
 way we get the outline view shown at the beginning of this section.  In order
 to make the structure editing and export commands handle this convention
 correctly, configure the variable @code{org-odd-levels-only}, or set this on
@@ -15259,7 +15259,7 @@
 constants in the variable @code{org-table-formula-constants}, install
 the @file{constants} package which defines a large number of constants
 and units, and lets you use unit prefixes like @samp{M} for
-@samp{Mega}, etc@.  You will need version 2.0 of this package, available
+@samp{Mega}, etc.  You will need version 2.0 of this package, available
 at @url{http://www.astro.uva.nl/~dominik/Tools}.  Org checks for
 the function @code{constants-get}, which has to be autoloaded in your
 setup.  See the installation instructions in the file
@@ -15832,7 +15832,7 @@
 table inserted between the two marker lines.
 
 Now let's assume you want to make the table header by hand, because you
-want to control how columns are aligned, etc@.  In this case we make sure
+want to control how columns are aligned, etc.  In this case we make sure
 that the table translator skips the first 2 lines of the source
 table, and tell the command to work as a @i{splice}, i.e., to not produce
 header and footer commands of the target table:

=== modified file 'doc/misc/sc.texi'
--- doc/misc/sc.texi	2012-11-24 23:57:21 +0000
+++ doc/misc/sc.texi	2012-11-25 00:24:17 +0000
@@ -202,7 +202,7 @@
 cited text and want to re-fill it, you must use an add-on package such
 as @cite{filladapt} or @cite{gin-mode}.  These packages can recognize
 Supercited text and will fill them appropriately.  Emacs's built-in
-filling routines, e.g@. @code{fill-paragraph}, do not recognize cited
+filling routines, e.g., @code{fill-paragraph}, do not recognize cited
 text and will not re-fill them properly because it cannot guess the
 @code{fill-prefix} being used.
 @xref{Post-yank Formatting Commands}, for details.@refill
@@ -1132,8 +1132,8 @@
 
 @example
 @group
-(@var{infokey} ((@var{regexp} @. @var{attribution})
-         (@var{regexp} @. @var{attribution})
+(@var{infokey} ((@var{regexp} . @var{attribution})
+         (@var{regexp} . @var{attribution})
          (@dots{})))
 @end group
 @end example
@@ -1284,7 +1284,7 @@
 association list, where each element is a cons cell of the form:
 
 @example
-(@var{regexp} @. @var{position})
+(@var{regexp} . @var{position})
 @end example
 
 @noindent
@@ -1295,7 +1295,7 @@
 @code{sc-name-filter-alist} would have an entry such as:
 
 @example
-("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0)
+("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" . 0)
 @end example
 
 @noindent
@@ -1486,8 +1486,8 @@
 respectively).  These frames can contain alists of the form:
 
 @example
-((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
- (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{})
+((@var{infokey} (@var{regexp} . @var{frame}) (@var{regexp} . @var{frame}) @dots{})
+ (@var{infokey} (@var{regexp} . @var{frame}) (@var{regexp} . @var{frame}) @dots{})
  (@dots{}))
 @end example
 


[-- Attachment #3: at-dot.txt.gz --]
[-- Type: application/x-gzip, Size: 38763 bytes --]

[-- Attachment #4: at-combined.txt.gz --]
[-- Type: application/x-gzip, Size: 93159 bytes --]

bug#12973: [TRUNCATED MESSAGE 2692 191817] bug#12973: @: overused in manual

[Richard Stallman]

    > We should correct these style issues for each Emacs release.

    Our release strategy makes it difficult to fix these style
    changes now: if we made changes like these, either to
    the trunk or to the emacs-24 branch, that'd make it harder
    to merge other emacs-24 changes into the trunk later.

I don't think we are talking about the same thing.

You seem to be criticizing a specific plan for installing the changes
into the Bzr repository.  I'm not talking about mechanics like that.
I'm saying that someone should edit the manual for style and usage for
each release.  Precisely when in the release style is a detail that I
leave to others, but I would normally do it before making a separate
branch for a given release.  If it is done after that, the changes 
should be installed in both the trunk and the branch.

    While we're on the topic, the Emacs manual has similar problems with
    "@.".  Sometimes it uses "@." when it's not necessary, 

An unnecessary use of @. is not an error.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call

bug#12973: @: overused in manual

[Glenn Morris]

Richard Stallman wrote:

> I'm saying that someone should edit the manual for style and usage for
> each release.

People do.

bug#12973: @: overused in manual

[Glenn Morris]

Paul Eggert wrote:

> Our release strategy makes it difficult to fix these style changes
> now: if we made changes like these, either to the trunk or to the
> emacs-24 branch, that'd make it harder to merge other emacs-24 changes
> into the trunk later.

There's zero problem wrt merging if the changes go to emacs-24 now.
If they go trunk, they will probably create repeated merge annoyances
(like any pervasive formatting change would).

bug#12973: @: overused in manual

[Glenn Morris]

Glenn Morris wrote:

> There's zero problem wrt merging if the changes go to emacs-24 now.

In fact I suggest you just do that so that we can stop discussing this.

bug#12973: @: overused in manual

[Paul Eggert]

On 11/25/12 17:31, Glenn Morris wrote:
> In fact I suggest you just do that so that we can stop discussing this.

Done, as emacs-24 bzr 110998, and I'm
marking this bug as done.