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

[Rene Ladan]

2008/12/12 Giorgos Keramidas <keramida at freebsd.org>:
> 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?
>
I am in favour of the full expansion, so that you can write

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

This form is shorter and we don't have to write the word "acronym" three times.

Maybe the acronyms can link to the glossary of the Handbook as well?

Regards,
Rene
-- 
http://www.rene-ladan.nl/

GPG fingerprint = E738 5471 D185 7013 0EE0  4FC8 3C1D 6F83 12E1 84F6
(subkeys.pgp.net)