Date: Thu, 24 May 2001 17:42:53 +0100 From: Nik Clayton <nik@freebsd.org> To: Udo Erdelhoff <ue@nathan.ruhr.de> Cc: freebsd-doc@freebsd.org Subject: Re: Problems with the automatic links Message-ID: <20010524174252.B51943@catkin.nothing-going-on.org> In-Reply-To: <20010524132051.A25181@nathan.ruhr.de>; from ue@nathan.ruhr.de on Thu, May 24, 2001 at 01:20:51PM %2B0200 References: <20010524132051.A25181@nathan.ruhr.de>
next in thread | previous in thread | raw e-mail | index | archive | help
--l76fUT7nc3MelDdI Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Thu, May 24, 2001 at 01:20:51PM +0200, Udo Erdelhoff wrote: > The first problem is a case of "well, don't do that": > Using &man.foo.bar; inside <question> has intresting side effects for the > TOCs: It ends the link to the question, inserts a link to the manapge and > continues with normal text. Check question 20 in the networking chapter > for a drastic example. Courtesy URL: > http://www.freebsd.org/doc/en_US.ISO_8859-1/books/faq/networking.html >=20 > Solution: Like I said earler: Well, don't do that. The neccessary patches > are already in my version of the FAQ and will be committed "soon". Don't commit them. Dima's been working on some changes to the stylesheets that will allow the link-generating code to know whether or not it's in the middle of another link, and act accordingly. I've been slow in reviewing them, Dima, feel free to post them to -doc for wider comment. > The second problem is somewhat tricky: We have several entities for > programs found in the ports collection. Using them results in a link of > this form: >=20 > http://www.freebsd.org/cgi/man.cgi?query=3Dimwheel&sektion=3D1 >=20 > Unfortunately, using this links gives "Sorry, no data found for...". The > same problem applies to the entities for X programs. The solution is a > link of the form >=20 > http://www.freebsd.org/cgi/man.cgi?\ > query=3Dimwheel&sektion=3D1&manpath=3DFreeBSD+Ports >=20 > Unfortunately, I'm not a stylesheet guru and have absolutely no idea how > to change the stylesheets to add "&manpath=3DFreeBSD+Ports" to some entit= ies. > As far as I can see, the current code simply forces every refentry into > a link to man.cgi. So far, I had two possible ideas: >=20 > a) Go back in time and use the old "1x" notation. The names of the entiti= es > would be &man.foo.1x;, resulting in >=20 > <citerefentry><refentrytitle>foo</refentrytitle><manvolnum>1x</manvolnum>= </citerefentry>=20 >=20 > The code in the stylesheets would have to use the second char to add the > right link to HTML version. In the other formats, the stylesheets would > have to remove the second letter. >=20 > b) Use &man.foo.1x; to generate an entity of the form: > <citerefentry><refentrytitle>foo</refentrytitle><manvolnum class=3D"xfree= ">1</manvolnum></citerefentry>=20 >=20 > And use the class parameter in the HTML version to create the correct lin= k. >=20 > I think b) is the better approach but I'd like to hear the opinions of > our resident stylesheet gurus on that matter. Looking at the various content models, <citerefentry> supports a "vendor" attribute, which might be appropriate (actually, so does <refentrytitle> and <manvolnum>). So the user would write; <citerefentry vendor=3D"XFree86"> <refentrytitle>X</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> and we have to come up with a list of recognised vendors. Here's a proof of concept implementation (I've got a load of cruft in my local freebsd.dsl, so these are cut-n-paste, not patches). First, in doc/share/sgml/freebsd.dsl, replace the definition of $create-refentry-xref-link$ and "(element citerefentry ...)" with this ; Empty function to quiet warnings (define ($create-refentry-xref-link$) (literal "")) (element citerefentry (let ((href ($create-refentry-xref-link$)))=20 (if %refentry-xref-link% (make element gi: "A" attributes: (list (list "HREF" href)) (if %refentry-xref-italic% ($italic-seq$) ($charseq$))) (if %refentry-xref-italic% ($italic-seq$) ($charseq$))))) Second, in doc/en_US.ISO_8859-1/share/sgml/freebsd.dsl, replace the definition of $create-refentry-xref-link$ with this: <!-- Specify how to generate the man page link HREF --> (define ($create-refentry-xref-link$ #!optional (n (current-node))) (let* ((r (select-elements (children n) (normalize "refentrytitle= "))) (m (select-elements (children n) (normalize "manvolnum"))) (v (attribute-string (normalize "vendor") n)) (u (string-append "http://www.FreeBSD.org/cgi/man.cgi?quer= y=3D" (data r) "&" "sektion=3D" (data m)))) (case v (("xfree86") (string-append u "&" "manpath=3DXFree86+4.0.2")) (("netbsd") (string-append u "&" "manpath=3DNetBSD+1.5")) (else u)))) That should be straightforward, and extensible. I suppose what we could do is have a map (in doc/share/sgml/freebsd.dsl, so that's available to all the translations without needing to duplicate it) that maps vendor values to "manpath" values. 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 --- --l76fUT7nc3MelDdI Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.5 (FreeBSD) Comment: For info see http://www.gnupg.org iEYEARECAAYFAjsNOgwACgkQk6gHZCw343WO2ACdGt2JhZBsrfPlq6l25WKFQtSE MY8An2xEVxKTGjCK850ziWfxL79h78ZD =5AF1 -----END PGP SIGNATURE----- --l76fUT7nc3MelDdI-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010524174252.B51943>