From owner-freebsd-doc@FreeBSD.ORG  Mon Jun 17 18:39:14 2013
Return-Path: <owner-freebsd-doc@FreeBSD.ORG>
Delivered-To: doc@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org
 [IPv6:2001:1900:2254:206a::19:1])
 by hub.freebsd.org (Postfix) with ESMTP id 1A4DF79A
 for <doc@freebsd.org>; Mon, 17 Jun 2013 18:39:14 +0000 (UTC)
 (envelope-from wblock@wonkity.com)
Received: from wonkity.com (wonkity.com [67.158.26.137])
 by mx1.freebsd.org (Postfix) with ESMTP id D61DB1868
 for <doc@freebsd.org>; Mon, 17 Jun 2013 18:39:13 +0000 (UTC)
Received: from wonkity.com (localhost [127.0.0.1])
 by wonkity.com (8.14.7/8.14.7) with ESMTP id r5HIdDUv080396
 for <doc@freebsd.org>; Mon, 17 Jun 2013 12:39:13 -0600 (MDT)
 (envelope-from wblock@wonkity.com)
Received: from localhost (wblock@localhost)
 by wonkity.com (8.14.7/8.14.7/Submit) with ESMTP id r5HIdDhY080393
 for <doc@freebsd.org>; Mon, 17 Jun 2013 12:39:13 -0600 (MDT)
 (envelope-from wblock@wonkity.com)
Date: Mon, 17 Jun 2013 12:39:13 -0600 (MDT)
From: Warren Block <wblock@wonkity.com>
To: doc@freebsd.org
Subject: RFC: acronym tags
Message-ID: <alpine.BSF.2.00.1306171233490.80376@wonkity.com>
User-Agent: Alpine 2.00 (BSF 1167 2008-08-23)
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII
X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3
 (wonkity.com [127.0.0.1]); Mon, 17 Jun 2013 12:39:13 -0600 (MDT)
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Documentation project <freebsd-doc.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/options/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc>
List-Post: <mailto:freebsd-doc@freebsd.org>
List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Mon, 17 Jun 2013 18:39:14 -0000

The FDP writing guide says:

   The first three uses of an acronym should be enclosed in acronym tags,
   with a role attribute with the full term defined. This allows a link
   to the glossary to be created, and for mouseovers to be rendered with
   the fully expanded term.

I believe this is obsolete.  The current usage is to tag every 
occurrence of an acronym, but not enter the definition in the role 
attribute.  AFAIK, we've never used these to generate the glossary or 
mouseover links.

My suggestion is to make the current usage the preferred style:
1. Tag each occurrence of an acronym.
2. Do not enter the role= attribute.  These could result in differing 
definitions for the same acronym.