Date: Fri, 12 Dec 2008 09:58:28 +0100 From: Gabor PALI <pgj@FreeBSD.org> To: Rene Ladan <r.c.ladan@gmail.com> Cc: doc@freebsd.org, Giorgos Keramidas <keramida@freebsd.org> Subject: Re: [PATCH] Adding <acronym> elements to wlan Handbook section Message-ID: <494227B4.3070504@FreeBSD.org> In-Reply-To: <e890cae60812112351h226d57fja3c481c56d7f4a7b@mail.gmail.com> References: <871vwfn418.fsf@kobe.laptop> <2a7894eb0812101310v2123a452q26b0e07630e7f209@mail.gmail.com> <878wqnafso.fsf@kobe.laptop> <2a7894eb0812101322o77b12fc9k8208f83d62481ad3@mail.gmail.com> <87k5a63z2d.fsf@kobe.laptop> <e890cae60812112351h226d57fja3c481c56d7f4a7b@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Rene Ladan wrote: > 2008/12/12 Giorgos Keramidas <keramida@freebsd.org>: >> 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 you can have different versions in the .ent file, like you did in case of mailing lists (defer the design decisions :)): <!ENTITY acronym.wlan.wep '<acronym role="Wired Equivalent Privacy">WEP</acronym>'> <!ENTITY acronym.wlan.wep.name '<acronym>WEP</acronym>'> > Maybe the acronyms can link to the glossary of the Handbook as well? Hm, sounds interesting. I think it is a good idea. Add another entity, for example: <!ENTITY acronym.wlan.wep.glossary '<ulink url="&url.books.handbook;/freebsd-glossary.html#WEP-GLOSSARY"><acronym role="Wired Equivalent Privacy">WEP</acronym></ulink>'> So the documentation writer has the freedom of choice how to mark up acronyms. It could be useful when one does not want to link all instances of an acronym, only the first in the section, for example. Thanks for saving us from lot of typing, Giorgos! :) Cheers, :g
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?494227B4.3070504>