[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