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

[Gabor PALI]

Rene Ladan wrote:
> 2008/12/12 Giorgos Keramidas <keramida at 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