From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id ceff4128 for ; Tue, 19 Feb 2019 17:35:45 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1gwDzK-00035p-Ug; Tue, 19 Feb 2019 23:35:44 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1gwDzJ-00069J-Q5; Tue, 19 Feb 2019 23:35:41 +0100 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1gwDzJ-0000mm-Np; Tue, 19 Feb 2019 23:35:41 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 578c0fac; Tue, 19 Feb 2019 23:35:41 +0100 (CET) Date: Tue, 19 Feb 2019 23:35:41 +0100 From: Ingo Schwarze To: discuss@mandoc.bsd.lv Cc: Robert Mustacchi Subject: Re: Cross references to specific sections in other manual pages Message-ID: <20190219223541.GC95454@athene.usta.de> References: X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.8.0 (2017-02-23) Hi Robert, Robert Mustacchi wrote on Sun, Feb 17, 2019 at 04:09:38PM -0800: > While writing manual pages for illumos, I've often I wonder about this "often". I have worked a lot on OpenBSD manual pages, and i did occasionally encouter the same desire, but i'd rather qualify it as "rarely". > wanted to semantically indicate a cross-reference to a specific > section of another manual page. One place this comes up for us > is in library documentation where we have an introductory page > that contains information about errors or required locking. > It also sometimes comes up in our device driver manual pages. > An example of this is a sentence of the form 'For > more information, see the LOCKING section of libproc(3LIB).' > > I don't believe there's a good way to do this today Absolutely correct. > as the .Sx macro always is supposed to be internal to the page and > the .Xr macro doesn't allow one to target a specific section or > sub-section header (.Sh / .Ss). Those reasons are accurate, too. > Would a new macro (or extension to an existing one) that semantically > indicated such a cross-reference to a particular .Sh/.Ss in another page > be of interest to others? You nailed a desideratum that has long been considered. I discussed it in detail and in a larger context during my presentation at EuroBSDCon 2015 in Stockholm, see pages 14 to 18 in https://www.openbsd.org/papers/eurobsdcon2015-mandoc.pdf Your specific detail is mentioned on page 18 in this line: "-- then use that for .Xr to specific .Sh/.Ss" But i strongly suggest you study the whole context and not this individual point in isolation. So far, it wasn't implemented because the focus has been on consolidating, on simplifying the language, and only to a much lesser degree on adding features. Intentionally so: a programmer should only be allowed to add one new thing (adding complexity) after first having made ten things simpler. Otherwise, the software will inevitably sprawl away from perfection instead of converging towards it. > I'm not sure if this is something that should > be elevated into its own macro. I think the simple, obvious syntax For more information, see .Xr libproc 3LIB LOCKING . is probably fine and unlikely to cause problems with backward compatibility, but i'm not absolutely convinced yet. > If folks think it might be useful, I'm > happy to take a look at implementing it. Whoa, watch out what you promise! :-D Implementing it involves: - syntax tree modeling - modification of the mdoc parser - modification of the mdoc validator - checking tree output mode (likely fine as-is) - modification of the mdoc terminal formatter - making sure PostScript and PDF output dont't break - modification of the mdoc HTML formatter - checking that mandoc.css still works (likely fine as-is) - modification of the mdoc markdown formatter - modification of the mdoc man formatter and that is only the mandoc part. Then, the same thing needs to be done for groff as well, because with respect to language definition changes, mandoc and groff are supposed to march in lock-step. Note that input syntax considerations are not even the most tricky part here. What counts is making the *output* as useful as possible across a wide range of output devices (before telling poeple that they can start using it if they want to). Some years ago, preliminary steps were missing to make the output useful, which is another reason why it wasn't worked on earlier. Now, a useful HTML rendering has become possible: For more information, see the LOCKING section in libproc(3LIB). In terminal output, it is far less useful because we still have no way to somehow invoke "man -s 3LIB libproc" when you see libproc(3LIB) in a terminal, and much less to invoke "man -O tag=LOCKING -s 3LIB libproc" where you see "LOCKING section in libproc(3LIB)". But we are a step closer now: at least the syntax man -O tag=LOCKING -s 3LIB libproc to open the target manual page in a terminal *at the desired place* is now implemented and tested (in OpenBSD) and will be contained in the next portable mandoc release - but it is a lot of typing and not easy to shorten (without causing compatibility issues), which severly limits the usefulness of such links in the terminal. PDF would in principle support hyperlinks, but the mandoc PDF formatting engine is *very* far away from becoming able to generate hyperlinks, and trying to teach it hyperlinks at this point might looks like a task for a suicide squad to me. So, read this as a hopeful reply, but don't necessarily regard it as an easy or short-term target... The best way to get it moved ahead is probably proposing a SIMPLE and convenient way to follow .Xr links from a rendered manual page in a terminal window - simple both in the sense of avoiding undue complication of the implementation and in the sense of ease of use. Once we have that, i absolutely see how your feature request is becoming really useful. In the meantime, simply write For more information, see the LOCKING section in .Xr libproc 3LIB . without any markup on "LOCKING"; the all caps already makes it stand out without additional markup. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv