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>
index | next in thread | previous in thread | raw e-mail
[-- Attachment #1 --] 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 > > 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: > > http://www.freebsd.org/cgi/man.cgi?query=imwheel&sektion=1 > > 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 > > http://www.freebsd.org/cgi/man.cgi?\ > query=imwheel&sektion=1&manpath=FreeBSD+Ports > > Unfortunately, I'm not a stylesheet guru and have absolutely no idea how > to change the stylesheets to add "&manpath=FreeBSD+Ports" to some entities. > 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: > > a) Go back in time and use the old "1x" notation. The names of the entities > would be &man.foo.1x;, resulting in > > <citerefentry><refentrytitle>foo</refentrytitle><manvolnum>1x</manvolnum></citerefentry> > > 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. > > b) Use &man.foo.1x; to generate an entity of the form: > <citerefentry><refentrytitle>foo</refentrytitle><manvolnum class="xfree">1</manvolnum></citerefentry> > > And use the class parameter in the HTML version to create the correct link. > > 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="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$))) (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?query=" (data r) "&" "sektion=" (data m)))) (case v (("xfree86") (string-append u "&" "manpath=XFree86+4.0.2")) (("netbsd") (string-append u "&" "manpath=NetBSD+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 -- 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 --- [-- Attachment #2 --] -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.5 (FreeBSD) Comment: For info see http://www.gnupg.org iEYEARECAAYFAjsNOgwACgkQk6gHZCw343WO2ACdGt2JhZBsrfPlq6l25WKFQtSE MY8An2xEVxKTGjCK850ziWfxL79h78ZD =5AF1 -----END PGP SIGNATURE-----help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010524174252.B51943>