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

[Giorgos Keramidas]

On Sat, 13 Dec 2008 01:46:06 +0900 (JST), Hiroki Sato <hrs at FreeBSD.org> wrote:
> Giorgos Keramidas <keramida at freebsd.org> wrote
>   in <871vwdahna.fsf at kobe.laptop>:
> ke> On Fri, 12 Dec 2008 09:58:28 +0100, Gabor PALI <pgj at FreeBSD.org> wrote:
> ke> > Maybe you can have different versions in the .ent file, like you did
> ke> > in case of mailing lists (defer the design decisions :)):
> ke> >
> ke> > <!ENTITY acronym.wlan.wep '<acronym role="Wired Equivalent Privacy">WEP</acronym>'>
> ke> > <!ENTITY acronym.wlan.wep.name '<acronym>WEP</acronym>'>
> ke>
> ke> Heh, cool!  I'll try to update the patch to include entities like this.
>
>  Hmm, this is not directly related to your idea, but I did not noticed
>  that role attrib is used for adding the description so far.  I think
>  this is incorrect from viewpoint of DocBook because it is for
>  classification of the element, not real content.  In DocBook
>  vocabulary, <acronym> cannot have such a expanded text,
>  unfortunately.
>
>  As a workaround, how about using the following phrase:
>
>  <acronym>WEP<remark role="acronym">Wired Equivalent Privacy</remark></acronym>
>
>  I use <remark> with role attrib here (probably this is the only
>  option which looks reasonable).  The necessary changes to the
>  stylesheet and an SGML example of vm-design/article.sgml are attached
>  (indentation is incomplete, though).  We need to rewrite the existing
>  <acronym> elements, too.
>
>  For entity definition, I like the following:
>
>  <!ENTITY acronym.FOO '<acronym xreflabel="FOO">FOO<remark role="acronym">DESC OF FOO</remark></acronym>'>
>
>  Generating link to glossary, suppressing rendering of <remark>, or so
>  on can be controlled by stylesheet, so multiple definitions are not
>  needed at the <!ENTITY> level, IMHO.

Very nice, thank you! :-)

I like the idea of moving content from role="xxx" attributes to real
content too.

What would our next steps be for this?

Perhaps something like this?

  * Commit this to doc/share/sgml/freebsd.dsl

  * Add share/sgml/acronyms.ent with some of the common entities

  * Update the existing role="" attributes to use the entities for those
    acronyms that need a tooltip, but a plain <acronym>FOO</acronym> for
    all the rest.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 194 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20081216/2921048c/attachment.sig>