DOCBOOK-APPS: Re: <citerefentry>

[Nik Clayton <nik at freebsd dot org>]

Dima,

I'm copying this to the docbook-apps mailing list for comment.  

[ For docbook-apps:  The FreeBSD project has some code in its DSSSL 
  customisation layer to optionally turn <citerefentry>'s in to links 
  to the manual pages.  This behaviour is controlled by a
  %refentry-xref-link% variable, and a function,
  $create-refentry-xref-link$ which actually builds the appropriate URL.

  The code chunks that do this are in

     http://www.freebsd.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dsl.diff?r1=1.25&r2=1.26&f=h

  (language neutral), and

     http://www.freebsd.org/cgi/cvsweb.cgi/doc/en_US.ISO_8859-1/share/sgml/freebsd.dsl.diff?r1=1.5&r2=1.6&f=h

  (which probably needs to be in a per-language customisation layer).
  This code, or something very much like it, is in the stylesheets in
  CVS, which means it will be in a future version of the DSSSL
  stylesheets ]

On Sat, Apr 28, 2001 at 12:24:27AM -0700, Dima Dorfman wrote:
> Some time ago you changed the <citerefentry> element to add a link to
> the man page it was referencing.  This is very good, except when a man
> page entity is used inside another tag which causes a link to be
> created.  For example:
> 
> 	<question id="su-wheel-group">
>           <para>&man.su.1; says <errorname>you are not in the correct group
>             to su root</errorname> when I try to su to
>             <username>root</username>.</para>
>         </question>
> 
> This causes nested links, which, for obvious reasons, aren't allowed
> in HTML.  It ends up linking to just the man page.  To see this bug
> "in action", just look at the ``system administration'' part of the
> FAQ.  The second to last question (about rpc.statd) exhibits this
> behavior.

Yes.

Ordinarily, I'd just set a flag whenever we open a link, and test the
flag each time to make sure we're not creating nested links.

You can't do that in DSSSL, since variable values can't change when
they're set.

> The ideal fix would be for <citerefentry> to check if it's inside a
> link and not create a link if it is.  I can't find a way to do that.
> It would require examining the generated (output) HTML code, but all
> the DSSSL functions (e.g., has-ancestor-member?, etc.) examine input
> SGML code.  A temporary, and somewhat-inadequate-but-good-enough
> solution would be to have <citerefentry> check if it's inside a
> <question> tag.  AFAIK, this is the only case where it's a problem
> right now.

Not true.  Consider

   <sect2>
     <title>Using &man.su.8;</title>

     ...

or similar.  When that title is used to create a link in a TOC you
should have the same problem.

> A short patch to freebsd.dsl to do that is attached.
> 
> Thanks,
> 
> 					Dima Dorfman
> 					dima@unixfreak.org
> 
> Index: freebsd.dsl
> ===================================================================
> RCS file: /st/src/FreeBSD/doc/share/sgml/freebsd.dsl,v
> retrieving revision 1.28
> diff -u -r1.28 freebsd.dsl
> --- freebsd.dsl	2001/04/09 20:35:47	1.28
> +++ freebsd.dsl	2001/04/28 07:17:28
> @@ -116,7 +116,8 @@
>                   (href		($create-refentry-xref-link$   
>                                                   (data refentrytitle)
>                                                   (data manvolnum))))
> -            (if %refentry-xref-link%
> +            (if (and %refentry-xref-link% (not (has-ancestor-member?
> +						(current-node) '("QUESTION"))))
>  	      (make element gi: "A"
>                      attributes: (list (list "HREF" href))
>                  (if %refentry-xref-italic%

This'll break links within the title of the question.  We only want to
not link if we're already inside a link -- typically, a TOC.

Norm's stylesheets use modes to do different processing of certain
elements.  For example, look in .../html/db31.dsl in the stylesheets, at
the block of code that starts

    (mode qandatoc
      
You'll see that some of the elements are redefined when creating the TOC
for FAQ sections.  If you do "grep with-mode *.dsl" you'll see the other
modes available.

What I think we need to do is something like this in the citerefentry
code

    (if (and %refentry-xref-link%
             (not current-mode qandatoc)
	     (not current-mode ...)
	     (not current-mode ...)))

and enumerate all the modes in which the link shouldn't be created.
However, the problem with this is that I just made up the name
"current-mode".  I have no idea whether or not this is possible in
DSSSL.

Looking at this deeper, citerefentry is not the only thing that could
cause this problem.  Any URL in a title or question (or the title of a
table or figure, if TOCs for those elements are created) is going to
cause problems.

The best fix would probably be to write a create-link function, 

    (define (create-link target attrlist)
      (if (lots of tests to determine whether or not the link should
           actually be created)
        (make element gi: "A"
	      attributes: attrlist
          (target))
        ; Else, just include the target, without creating a link
	(target)))

and then adjust the stylesheets to use the create-link function
everywhere they currently do "(make element gi: "A" ... )".

The tricky bit is the "lots of tests to determine whether or not the
link should actually be created" code.  That's left as an exercise for
the reader. . .

N
-- 
FreeBSD: The Power to Serve             http://www.freebsd.org/
FreeBSD Documentation Project           http://www.freebsd.org/docproj/

          --- 15B8 3FFC DDB4 34B0 AA5F  94B7 93A8 0764 2C37 E375 ---

PGP signature