From owner-freebsd-doc@FreeBSD.ORG Fri Dec 12 07:51:09 2008 Return-Path: Delivered-To: doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 59DF61065672; Fri, 12 Dec 2008 07:51:09 +0000 (UTC) (envelope-from r.c.ladan@gmail.com) Received: from yw-out-2324.google.com (yw-out-2324.google.com [74.125.46.29]) by mx1.freebsd.org (Postfix) with ESMTP id F0AA18FC08; Fri, 12 Dec 2008 07:51:08 +0000 (UTC) (envelope-from r.c.ladan@gmail.com) Received: by yw-out-2324.google.com with SMTP id 9so609750ywe.13 for ; Thu, 11 Dec 2008 23:51:08 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:message-id:date:from:to :subject:cc:in-reply-to:mime-version:content-type :content-transfer-encoding:content-disposition:references; bh=d5oGzky7BPhNhokvjkiNw3BHexZ5wZRKstN9vPXDgEE=; b=fXQgxvGYpmayzR2HBSwj4wx3MkQyLN5Q2rOqMy+fAO7+pOLRHPPFhS1eAI85ORi2TQ LtQMuqILmjCHkWfQ2ZsjOttlNzYlnglHmc6NyOUGcVjMOAqCfoKHouP+0mBgN2dj2iqh FbItnD961DrCq6qiq2To1V7/1iU/NrpaOllHo= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=message-id:date:from:to:subject:cc:in-reply-to:mime-version :content-type:content-transfer-encoding:content-disposition :references; b=mgx65k/vniKoS0QrtSirkxxAZGzDLo9Cm/FdHk4Tazy49yXrusCUSJ9ihr1UAL5b2F 3YG4fTpoVVAugwE/ovCUhvbGCuvZQm/evxQlYg9ohZKlmYUMzugB4J7x32Mcb73Rz6Zs 32eCkNQxdFMtp+I74qneAFjtPzIC7YOFq/pvQ= Received: by 10.150.145.20 with SMTP id s20mr5222926ybd.30.1229068268192; Thu, 11 Dec 2008 23:51:08 -0800 (PST) Received: by 10.150.225.9 with HTTP; Thu, 11 Dec 2008 23:51:07 -0800 (PST) Message-ID: Date: Fri, 12 Dec 2008 08:51:07 +0100 From: "Rene Ladan" To: "Giorgos Keramidas" In-Reply-To: <87k5a63z2d.fsf@kobe.laptop> MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Content-Disposition: inline References: <871vwfn418.fsf@kobe.laptop> <2a7894eb0812101310v2123a452q26b0e07630e7f209@mail.gmail.com> <878wqnafso.fsf@kobe.laptop> <2a7894eb0812101322o77b12fc9k8208f83d62481ad3@mail.gmail.com> <87k5a63z2d.fsf@kobe.laptop> Cc: doc@freebsd.org Subject: Re: [PATCH] Adding elements to wlan Handbook section X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 12 Dec 2008 07:51:09 -0000 2008/12/12 Giorgos Keramidas : > On Wed, 10 Dec 2008 13:22:57 -0800, "Murray Stokely" 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 @@ > + > + > + > + > + > + > + > + > + > + > + > + > 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; > > %freebsd; > + > +%acronyms; > > %authors; > > 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; > > %freebsd; > + > +%acronyms; > > %authors; > > 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: > > Using WEP > encryption is not really safe anymore, but a lot of people use it > anyway. > > We can probably go a step further and define: > > WEP'> > > 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 > element? > I am in favour of the full expansion, so that you can write Using &acronym.wlan.wep; encryption is not really safe anymore, but a lot of people use it anyway. 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)