enhancement request: @abbr

[Paul Eggert]

It would be nice to add support for a new command @abbr, that would
behave much like @acronym except it would generate <abbr> in HTML
instead of <acronym>, and it wouldn't use a smaller font in TeX.  Here
is some proposed documentation for such a change.  Unfortunately I ran
out of time today after writing the doc....

2004-07-29  Paul Eggert  <address@hidden>

        * doc/texinfo.txi (Useful Highlighting): Add @abbr.
        (abbr): New subsection, describing @abbr.
        (acronym): Discuss @abbr versus @acronym.  What a minefield!
        (Smallcaps): abbreviations -> acronyms
        (Command List): Add @abbr, and simplify @acronym to avoid
        now-confusing terminology.

--- /home/eggert/src/texinfo/texinfo-4.7/doc/texinfo.txi        2004-04-09 
14:30:07 -0700
+++ texinfo.txi 2004-07-29 18:05:31 -0700
@@ -345,6 +345,7 @@ @node Top
 * option::                      Indicating option names.
 * dfn::                         Specifying definitions.
 * cite::                        Referring to books not in the  Info system.
+* abbr::                        Indicating abbreviations.
 * acronym::                     Indicating acronyms.
 * indicateurl::                 Indicating a World Wide Web reference.
 * email::                       Indicating an electronic mail address.
@@ -6665,6 +6666,7 @@ @node Indicating
 * option::                      Indicating option names.
 * dfn::                         Specifying definitions.
 * cite::                        Referring to books not in the  Info system.
+* abbr::                        Indicating abbreviations.
 * acronym::                     Indicating acronyms.
 * indicateurl::                 Indicating a World Wide Web reference.
 * email::                       Indicating an electronic mail address.
@@ -6718,6 +6720,9 @@ @node Useful Highlighting
 @item @@address@hidden@address@hidden
 Indicate the name of a address@hidden
 
address@hidden @@address@hidden@}
+Indicate an address@hidden
+
 @item @@address@hidden@address@hidden
 Indicate an address@hidden
 
@@ -7351,31 +7356,72 @@ @node cite
 @end ignore
 
 
address@hidden abbr
address@hidden @code{@@address@hidden@var{abbreviation}[, @address@hidden
address@hidden abbr
+
address@hidden Abbreviations, tagging
+You can use the @code{@@abbr} command for abbreviations such
+as address@hidden'.  The abbreviation is given as
+the single argument in braces, as in @samp{@@address@hidden@}}.
+As a matter of style, or for particular abbreviations, you may prefer to
+omit periods, as in @samp{@@address@hidden@} Berry}.
+
address@hidden@@abbr} accepts an optional second argument, intended to be used
+for the meaning of the abbreviation.
+
+If the abbreviation ends in a period and is not at the end of a
+sentence, and if there is no second argument, remember to use the
+special @code{@@.} and similar commands (@pxref{Not Ending a
+Sentence}).
+
address@hidden <abbr> tag
+In @TeX{} and in the Info output, the first argument is printed as-is;
+if the second argument is present, it is printed in parentheses after
+the abbreviation.  In HTML, and XML, the @code{<abbr>} tag is
+used; in Docbook, the @code{<abbrev>} tag is used.  For instance:
+
address@hidden
+@@address@hidden J., Computer Journal@@}
address@hidden example
+
address@hidden produces:
+
address@hidden
address@hidden J., Computer address@hidden
address@hidden display
+
+For some abbreviations you may prefer to use the @code{@@acronym}
+command instead.  @xref{acronym}, for more about the usage of
address@hidden@@abbr} and @code{@@acronym}.
+
+
 @node acronym
 @subsection @code{@@address@hidden@var{acronym}[, @address@hidden
 @findex acronym
 
 @cindex NASA, as acronym
address@hidden F.B.I., as acronym
address@hidden Abbreviations, tagging
 @cindex Acronyms, tagging
 Use the @code{@@acronym} command for abbreviations written in all
 capital letters, such as address@hidden'.  The abbreviation is given as
 the single argument in braces, as in @samp{@@address@hidden@}}.  As
-a matter of style, or for particular abbreviations, you may prefer to
-use periods, as in @samp{@@address@hidden@}}.
+a matter of style, or for particular acronyms, you may prefer to
+use periods, as in @samp{@@address@hidden@}}.
+
address@hidden@@acronym} accepts an optional second argument, intended to be
+used for the meaning of the acronym.
 
-If the acronym is at the end of a sentence, remember to use the
+If the acronym is at the end of a sentence, and if there is no second
+argument, remember to use the
 special @code{@@.} and similar commands (@pxref{Ending a Sentence}).
 
 @cindex <acronym> tag
 In @TeX{}, the acronym is printed in slightly smaller font.  In the
-Info output, the argument is printed as-is.  In HTML, Docbook, and
+Info output, the argument is printed as-is.  In either format, if the
+second argument is present, it is printed in parentheses after the
+acronym.  In HTML, Docbook, and
 XML, the @code{<acronym>} tag is used.
-
address@hidden@@acronym} accepts an optional second argument, intended to be
-used for the meaning of the acronym.  If present, it is printed in
-parentheses after the acronym.  For instance (since GNU is a recursive
+For instance (since GNU is a recursive
 acronym, we use @code{@@acronym} recursively):
 
 @example
@@ -7392,6 +7438,34 @@ @node acronym
 capitals.  Don't use @code{@@acronym} for this, since a name is not an
 acronym.  Use @code{@@sc} instead (@pxref{Smallcaps}).
 
address@hidden@@abbr} and @code{@@acronym} are closely related commands: they
+both signal to the reader that a shortened form is being used, and
+possibly give a meaning.  When choosing whether to use these two
+commands, please bear the following in mind:
+
address@hidden @minus
address@hidden
+In standard English usage, acronyms are a subset of abbreviations:
+they include pronounceable words like `NATO', `radar', and `snafu',
+and some sources also include syllable acronyms like `Usenet', hybrids
+like `SIGGRAPH', or even unpronounceable initialisms like `FBI'.
+
address@hidden
+Texinfo currently supports only acronyms that are all capital letters.  
+
address@hidden
+In @TeX{}, an acronym is printed in a slightly smaller font.
+
address@hidden
+Some browsers place a dotted bottom border under abbreviations but not
+acronyms.
+
address@hidden
+It's not essential to use these commands for all abbreviations.  Text
+is perfectly readable without them, and for common abbreviations like
+`etc.@:' they are overkill.
+
address@hidden itemize
 
 @node indicateurl
 @subsection @code{@@address@hidden@address@hidden
@@ -7534,7 +7608,7 @@ @node Smallcaps
 @end display
 
 As shown here, we recommend using @code{@@acronym} for actual
-abbreviations (@pxref{acronym}), and reserving @code{@@sc} for special
+acronyms (@pxref{acronym}), and reserving @code{@@sc} for special
 cases where you want small caps.  The output is not the same
 (@code{@@acronym} prints in a smaller text font, not the small caps
 font), but more importantly it describes the actual text more
@@ -16477,9 +16551,13 @@ @node Command List
 Generate the uppercase and lowercase Scandinavian A-ring letters,
 respectively: @AA{}, @aa{}.  @xref{Inserting Accents}.
 
address@hidden @@address@hidden@address@hidden
-Tag @var{abbrev} as an acronym, that is, an abbreviation written in all
-capital letters, such as `NASA'.  @xref{acronym,, @code{acronym}}.
address@hidden @@address@hidden@}
+Tag @var{abbreviation} as an abbreviation, such as `Comput.'.
address@hidden,, @code{abbr}}.
+
address@hidden @@address@hidden@address@hidden
+Tag @var{acronym} as an acronym, such as `NASA'.
address@hidden,, @code{acronym}}.
 
 @item @@address@hidden@}
 @itemx @@address@hidden@}