Subject: Re: bug#12973: @: overused in manual

From: Paul Eggert <[email-masked]>
Date: Sat, 24 Nov 2012 16:46:34 -0800

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