[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK-APPS: Re: <citerefentry>
--kbCYTQG2MZjuOjyn Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Dima, I'm copying this to the docbook-apps mailing list for comment. =20 [ For docbook-apps: The FreeBSD project has some code in its DSSSL=20 customisation layer to optionally turn <citerefentry>'s in to links=20 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=3D1.25&r2=3D1.26&f=3Dh (language neutral), and http://www.freebsd.org/cgi/cvsweb.cgi/doc/en_US.ISO_8859-1/share/sgml/= freebsd.dsl.diff?r1=3D1.5&r2=3D1.6&f=3Dh (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: >=20 > <question id=3D"su-wheel-group"> > <para>&man.su.1; says <errorname>you are not in the correct gro= up > to su root</errorname> when I try to su to > <username>root</username>.</para> > </question> >=20 > 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. >=20 > Thanks, >=20 > Dima Dorfman > dima@unixfreak.org >=20 > Index: freebsd.dsl > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > 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$ =20 > (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 =20 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,=20 (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 --=20 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 --- --kbCYTQG2MZjuOjyn Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.4 (FreeBSD) Comment: For info see http://www.gnupg.org iEYEARECAAYFAjrv4wQACgkQk6gHZCw343XymQCcDhGp4aprjnP/EmsEh3zWXrM3 v+0An1/qdgo3u3rfb+7u/Am0VcET3AuH =ihmJ -----END PGP SIGNATURE----- --kbCYTQG2MZjuOjyn--
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC