Date: Fri, 12 Dec 2008 08:51:07 +0100 From: "Rene Ladan" <r.c.ladan@gmail.com> To: "Giorgos Keramidas" <keramida@freebsd.org> Cc: doc@freebsd.org Subject: Re: [PATCH] Adding <acronym> elements to wlan Handbook section Message-ID: <e890cae60812112351h226d57fja3c481c56d7f4a7b@mail.gmail.com> In-Reply-To: <87k5a63z2d.fsf@kobe.laptop> References: <871vwfn418.fsf@kobe.laptop> <2a7894eb0812101310v2123a452q26b0e07630e7f209@mail.gmail.com> <878wqnafso.fsf@kobe.laptop> <2a7894eb0812101322o77b12fc9k8208f83d62481ad3@mail.gmail.com> <87k5a63z2d.fsf@kobe.laptop>
next in thread | previous in thread | raw e-mail | index | archive | help
2008/12/12 Giorgos Keramidas <keramida@freebsd.org>: > On Wed, 10 Dec 2008 13:22:57 -0800, "Murray Stokely" <murray@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)
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?e890cae60812112351h226d57fja3c481c56d7f4a7b>