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

[Hiroki Sato]

Giorgos Keramidas <keramida at freebsd.org> wrote
  in <871vwdahna.fsf at kobe.laptop>:

ke> On Fri, 12 Dec 2008 08:51:07 +0100, "Rene Ladan" <r.c.ladan at gmail.com> wrote:
ke> > I am in favour of the full expansion, so that you can write
ke> >
ke> > <para>Using &acronym.wlan.wep; encryption is not really safe anymore,
ke> >   but a lot of people use it anyway.</para>
ke> >
ke> > This form is shorter and we don't have to write the word "acronym"
ke> > three times.
ke> >
ke> > Maybe the acronyms can link to the glossary of the Handbook as well?
ke>
ke> That's an interesting idea :-)
ke>
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.

--
| Hiroki SATO
-------------- next part --------------
Index: share/sgml/freebsd.dsl
===================================================================
RCS file: /home/ncvs/doc/share/sgml/freebsd.dsl,v
retrieving revision 1.94
diff -d -u -I\$FreeBSD:.*\$ -I\$NetBSD:.*\$ -I\$OpenBSD:.*\$ -I\$DragonFly:.*\$ -I\$Id:.*\$ -I\$Translation:.*\$ -I\$hrs:.*\$ -r1.94 freebsd.dsl
--- share/sgml/freebsd.dsl	24 May 2008 16:16:20 -0000	1.94
+++ share/sgml/freebsd.dsl	12 Dec 2008 16:13:56 -0000
@@ -78,19 +78,25 @@
 ;; Taken from Norm's stylesheets; modified to add support for TITLE so
 ;; that we get a mouse over definition for acronyms in HTML output.

-	(define ($acronym-seq$ #!optional (sosofo (process-children)))
-	  ;; FIXME: html4 only
-	  (let ((title (attribute-string (normalize "role") (current-node))))
-	    (if title
-	  (make element gi: "ACRONYM"
-	        attributes: (list
-			     (list "TITLE" title)
-	                     (list "CLASS" (gi)))
-		sosofo)
-	  (make element gi: "ACRONYM"
-	        attributes: (list
-	                     (list "CLASS" (gi)))
-		sosofo))))
+(define ($acronym-seq$ #!optional (sosofo (process-children)))
+  (let* ((acronym-remark (select-elements
+			  (children (current-node))
+			  (normalize "remark"))))
+    (let* ((title (if (and acronym-remark
+			   (equal? (attribute-string (normalize "role") acronym-remark) "acronym"))
+		      (data acronym-remark)
+		      "")))
+      (make element gi: "ACRONYM"
+	    attributes: (list
+			 (list "CLASS" (gi))
+			 (list "TITLE" title))
+	    sosofo))))
+
+(element (acronym remark)
+  (let* ((role (attribute-string (normalize "role"))))
+    (if (not (equal? role "acronym"))
+	($charseq$)
+	(empty-sosofo))))

         (define (book-titlepage-recto-elements)
           (list (normalize "title")
@@ -305,6 +311,7 @@
 	    (if (not (last-sibling? (current-node)))
 	        (literal ", ")
 	        (empty-sosofo))))
+
       ]]>

       <!-- HTML with images  ............................................ -->
Index: en_US.ISO8859-1/articles/vm-design/article.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/vm-design/article.sgml,v
retrieving revision 1.16
diff -d -u -I\$FreeBSD:.*\$ -I\$NetBSD:.*\$ -I\$OpenBSD:.*\$ -I\$DragonFly:.*\$ -I\$Id:.*\$ -I\$Translation:.*\$ -I\$hrs:.*\$ -r1.16 article.sgml
--- en_US.ISO8859-1/articles/vm-design/article.sgml	24 Sep 2006 13:36:59 -0000	1.16
+++ en_US.ISO8859-1/articles/vm-design/article.sgml	12 Dec 2008 16:25:08 -0000
@@ -34,7 +34,7 @@

     <abstract>
       <para>The title is really just a fancy way of saying that I am going to
-	attempt to describe the whole VM enchilada, hopefully in a way that
+	attempt to describe the whole <acronym xreflabel="VM">VM<remark role="acronym">Virtual Memory</remark></acronym> enchilada, hopefully in a way that
 	everyone can follow.  For the last year I have concentrated on a number
 	of major kernel subsystems within FreeBSD, with the VM and Swap
 	subsystems being the most interesting and NFS being <quote>a necessary
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 195 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20081213/054784b3/attachment.sig>