From owner-freebsd-doc  Thu May 31 21:57:39 2001
Delivered-To: freebsd-doc@freebsd.org
Received: from bazooka.unixfreak.org (bazooka.unixfreak.org [63.198.170.138])
	by hub.freebsd.org (Postfix) with ESMTP
	id 5A4DD37B42C; Thu, 31 May 2001 21:57:34 -0700 (PDT)
	(envelope-from dima@unixfreak.org)
Received: from hornet.unixfreak.org (hornet [63.198.170.140])
	by bazooka.unixfreak.org (Postfix) with ESMTP
	id 1CA303E30; Thu, 31 May 2001 21:57:34 -0700 (PDT)
To: doc@freebsd.org
Cc: nik@freebsd.org
Subject: Nested hrefs (also known as: <citerefentry>)
Date: Thu, 31 May 2001 21:57:34 -0700
From: Dima Dorfman <dima@unixfreak.org>
Message-Id: <20010601045734.1CA303E30@bazooka.unixfreak.org>
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
List-ID: <freebsd-doc.FreeBSD.ORG>
List-Archive: <http://docs.freebsd.org/mail/> (Web Archive)
List-Help: <mailto:majordomo?subject=help> (List Instructions)
List-Subscribe: <mailto:majordomo?subject=subscribe%20freebsd-doc>
List-Unsubscribe: <mailto:majordomo?subject=unsubscribe%20freebsd-doc>
X-Loop: FreeBSD.org

As you probably know, we have customized <citerefentry> to create an
href to an HTML rendering of the corresponding manual page when the
document is being rendered to HTML.  The problem is when one of these
entities is used inside a tag which will cause a link to be created,
such as (if a table of contents is to be created for this document):

	<sect1 id="using-ls">Using the &man.ls.1; command</sect1>

This will cause an equivilent of the following to be generated when
rendering to HTML:

	<a href="using-ls.html">Using the
		<a href="http://some/url/ls.1">ls(1)</a> command</a>

Obviously, nested hrefs simply don't work.  Also, the canonical
solution of "then don't do that" is unsatisfying.  The (IMO) ideal
solution would be for the customization of <citerefentry> to detect if
its output will appear inside an href, and not generate an href itself
in that case.

This would be much easier if all links were created with a procedure,
e.g. (create-link), instead of using (make element gi: "A").  Once
that's done, all that's needed to fix the problem described above is
to have (create-link) call another function, e.g. (can-link-here), to
determine if it's okay to make an link in the current place.

Comments?  Suggestions?

Regards,

					Dima Dorfman
					dima@unixfreak.org

Index: freebsd.dsl
===================================================================
RCS file: /stl/src/FreeBSD/doc/share/sgml/freebsd.dsl,v
retrieving revision 1.30
diff -u -r1.30 freebsd.dsl
--- freebsd.dsl	2001/05/22 03:32:17	1.30
+++ freebsd.dsl	2001/05/28 05:55:33
@@ -116,12 +116,12 @@
                  (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
                 (if %refentry-xref-italic%
                   ($italic-seq$)
-                  ($charseq$)))
+                  ($charseq$))
+		(list (list "HREF" href)))
               (if %refentry-xref-italic%
                 ($italic-seq$)
                 ($charseq$)))))
@@ -447,6 +447,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 target attrlist)
+ 	(if (can-link-here)
+ 	    (make element gi: "A"
+ 		  attributes: attrlist
+ 		  target)
+	    target))
     </style-specification-body>
   </style-specification>
       

To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message