The problem is with nested links; quite frankly, they don't work.

This isn't normally an issue because no one in their right mind will
stick a <link> inside another <link>.  However, we have entities which
create links, such as &man.*;, &a.*;, etc.  It's nice to be able to
use these inside links.  To deal with this..

Introduce a create-link procedure which will be used to replace (make
element gi: "A" ...) constructs.  This procedure creates a link as
specified only if the can-link-here procecure (described below)
returns #t.  If the latter returns #f, it will print the link text
without the link.

The (also new) can-link-here procedure returns #t if it determines
that it's okay to make a link in the current context, and #f
otherwise.  Currently, it does its check by figuring out whether the
current context is within a <title> or <question> tag.  This is not
ideal because it doesn't catch all cases, but it's a lot better than
nothing.  As the other cases are discovered, this procedure can be
modified.

share/sgml/freebsd.dsl

@@ -1,4 +1,4 @@
-<!-- $FreeBSD: doc/share/sgml/freebsd.dsl,v 1.29 2001/05/20 17:30:44 ue Exp $ -->
+<!-- $FreeBSD: doc/share/sgml/freebsd.dsl,v 1.30 2001/05/22 03:32:17 dd Exp $ -->
 
 <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
 <!ENTITY % output.html		"IGNORE">
@@ -116,9 +116,8 @@
                  (href		($create-refentry-xref-link$   
                                                  (data refentrytitle)
                                                  (data manvolnum))))
-            (if %refentry-xref-link%
-	      (make element gi: "A"
-                    attributes: (list (list "HREF" href))
+	    (if %refentry-xref-link%
+	      (create-link (list (list "HREF" href))
                 (if %refentry-xref-italic%
                   ($italic-seq$)
                   ($charseq$)))
@@ -447,6 +446,41 @@
                             (process-node-list abbrev))
                           (make sequence
                             (literal "[" (id target) "]"))))))))
+ 
+       <!-- The (create-link) procedure should be used by all FreeBSD
+ 	   stylesheets to create links.  It calls (can-link-here) to
+ 	   determine whether it's okay to make a link in the current
+ 	   position.
+ 
+ 	   This check is necessary because links aren't allowed in,
+ 	   for example, <question> tags since the latter cause links
+ 	   to be created by themselves.  Obviously, nested links lead
+ 	   to all kinds of evil.  This normally wouldn't be a problem
+ 	   since no one in their right mind will put a <ulink> or
+ 	   <link> in a <question>, but it comes up when someone uses,
+ 	   say, a man page entity (e.g., &man.ls.1;); the latter may
+ 	   cause a link to be created, but its use inside a <question>
+ 	   is perfectly legal.
+ 
+ 	   The (can-link-here) routine isn't perfect; in fact, it's a
+ 	   hack and an ugly one at that.  Ideally, it would detect if
+ 	   the currect output would wind up in an <a> tag and return
+ 	   #f if that's the case.  Slightly less ideally it would
+ 	   check the current mode and return #f if, say, we're
+ 	   currently in TOC mode.  Right now, it makes a best guess
+ 	   attempt at guessing which tags might cause links to be
+ 	   generated.  -->
+      (define (can-link-here)
+ 	(cond ((has-ancestor-member? (current-node)
+				     '("TITLE" "QUESTION")) #f)
+ 	      (#t #t)))
+ 
+      (define (create-link attrlist target)
+ 	(if (can-link-here)
+ 	    (make element gi: "A"
+ 		  attributes: attrlist
+ 		  target)
+	    target))
     </style-specification-body>
   </style-specification>