[PATCH] Adding <acronym> elements to wlan Handbook section

[Giorgos Keramidas]

On Wed, 10 Dec 2008 13:22:57 -0800, "Murray Stokely" <murray at stokely.org> wrote:
> In that case this looks great to me.  I agree with Manolis that adding
> the role="definition" for the first instance of each acronym is
> helpful.  I really thought we were already doing this in parts of the
> Handbook, but I may be misremembering.

I started adding a role="" at the first instance of each WLAN-specific
acronym and I noticed that I was typing the same expansions again and
again all over the place.  This is a bit error prone, so it seemed more
natural to add a ``set of "standard" acronym expansions''.

Does something like this look useful for other sorts of acronyms too?

%%%
# HG changeset patch
# User keramida
# Date 1229048467 -7200
# Node ID c8a6e126654fba80e290d6c93568d551a0c10473
# Parent  669337240ff11759179bde192d61b69a6be769ea
Add support for a set of 'standard' acronym expansions.

I got a bit sick of typing role="the same text" all the time, and
this gives us an easy point to redefine an acronym expansion
without having to crawl the entire doc/ tree, so here it is.

diff -r 669337240ff1 -r c8a6e126654f share/sgml/acronyms.ent
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/share/sgml/acronyms.ent	Fri Dec 12 04:21:07 2008 +0200
@@ -0,0 +1,21 @@
+<!--
+
+  This file contains entities for common acronyms used in the FreeBSD
+  documentation.
+
+  Please keep this file sorted.
+
+  $FreeBSD$
+
+-->
+
+<!ENTITY acronym.dhcp		"Dynamic Host Configuration Protocol">
+<!ENTITY acronym.ieee		"Institute of Electrical and Electronics Engineers">
+<!ENTITY acronym.mac		"Media Access Control">
+<!ENTITY acronym.tls		"Transport Layer Security">
+
+<!-- Entities for Wi-Fi acronyms and other common terms -->
+<!ENTITY acronym.wlan.ap	"Access Point">
+<!ENTITY acronym.wlan.bss	"Basic Service Set">
+<!ENTITY acronym.wlan.ibss	"Independent Basic Service Set">
+<!ENTITY acronym.wlan.wep	"Wired Equivalent Privacy">
diff -r 669337240ff1 -r c8a6e126654f share/sgml/articles.ent
--- a/share/sgml/articles.ent	Wed Dec 10 22:51:06 2008 +0200
+++ b/share/sgml/articles.ent	Fri Dec 12 04:21:07 2008 +0200
@@ -8,6 +8,8 @@
 %man;
 <!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
 %freebsd;
+<!ENTITY % acronyms PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Acronyms Entity Set//EN">
+%acronyms;
 <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
 %authors;
 <!ENTITY % teams PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//EN">
diff -r 669337240ff1 -r c8a6e126654f share/sgml/books.ent
--- a/share/sgml/books.ent	Wed Dec 10 22:51:06 2008 +0200
+++ b/share/sgml/books.ent	Fri Dec 12 04:21:07 2008 +0200
@@ -10,6 +10,8 @@
 %bookinfo;
 <!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
 %freebsd;
+<!ENTITY % acronyms PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Acronyms Entity Set//EN">
+%acronyms;
 <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
 %authors;
 <!ENTITY % teams PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//EN">
diff -r 669337240ff1 -r c8a6e126654f share/sgml/catalog
--- a/share/sgml/catalog	Wed Dec 10 22:51:06 2008 +0200
+++ b/share/sgml/catalog	Fri Dec 12 04:21:07 2008 +0200
@@ -23,6 +23,9 @@
 PUBLIC "-//FreeBSD//DOCUMENT DocBook Language Neutral Stylesheet//EN"
 	"freebsd.dsl"
 
+PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Acronyms Entity Set//EN"
+	"acronyms.ent"
+
 PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN" 
        "articles.ent"
 
%%%

I have only added a few acronym expansions now, but this already makes
it possible to write things like:

    <para>Using <acronym role="&acronym.wlan.wep;">WEP</acronym>
      encryption is not really safe anymore, but a lot of people use it
      anyway.</para>

We can probably go a step further and define:

    <!ENTITY acronym.wlan.wep '<acronym role="Wired Equivalent Privacy">WEP</acronym>'>

but I wanted to ask the rest of doc@ first what they think about a list
of acronym expansions that is shared like this?

If yes, which form of entity would you prefer to have?  One that expands
to the "Name of the Acronym" or one that expands to the full <acronym>
element?

Giorgos