Cross references to specific sections in other manual pages

Cross references to specific sections in other manual pages

[Robert Mustacchi]

Hi,

While writing manual pages for illumos, I've often 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 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).

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? I'm not sure if this is something that should
be elevated into its own macro. If folks think it might be useful, I'm
happy to take a look at implementing it.

Thanks,
Robert
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Cross references to specific sections in other manual pages

[Ingo Schwarze]

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
  <a href="$WWWSITE/libproc.3LIB#LOCKING">LOCKING</a>
  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

Re: Cross references to specific sections in other manual pages

[Robert Mustacchi]

Hi Ingo,

Thanks for your reply, apologies this wasn't nearly as prompt as yours.

On 2/19/19 14:35 , Ingo Schwarze wrote:
> 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.

Makes sense. I appreciate the tension there.

>> 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.

I thought about something similar as well, but I hadn't convinced myself
that it made sense or that someone wouldn't end up being upset with
however one phrased to see what we put there.

>> 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.

I'll admit, the groff part was the part of the list that I didn't expect.

> 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
>   <a href="$WWWSITE/libproc.3LIB#LOCKING">LOCKING</a>
>   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.

That's interesting. Will the next portable release be announced here?
I'd like to make sure we're able to test that in illumos whenever it
makes sense.

> 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.

I'll make sure to clean up some of the older markup and standardize on
that going forward. The different constraints and complications make
sense. I do agree, that it's not clear if it'll end up being worthwhile
or not. Depending on time, I may poke at it a little bit and see if it's
worth panning out or if it explodes in complexity and thus isn't worthwhile.

Thanks again,
Robert
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Cross references to specific sections in other manual pages

[Ingo Schwarze]

Hi Robert,

Robert Mustacchi wrote on Tue, Feb 26, 2019 at 04:51:53PM -0800:

> Thanks for your reply, apologies this wasn't nearly as prompt as yours.

No problem, this is a long-term project, and i'm not always all
that prompt either.

> Will the next portable release be announced here?

Yes, right after a new version is released, i usually announce that
on <discuss at mandoc dot bsd dot lv>, on https://mandoc.bsd.lv/,
and on https://undeadly.org/.

> I'd like to make sure we're able to test that in illumos whenever it
> makes sense.

Shortly *before* making a relase, i typically send out a beta-release
tarball to a smaller number of developers working on about ten
different operating and packaging systems.  I've taken a note to
include you in that mailing next time.  The other illumos developer
on that "beta" list currently is Yuri Pankov (who also contributed
to FreeBSD recently, i think).

> On 2/19/19 14:35 , Ingo Schwarze wrote:

>> 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.

> I'll make sure to clean up some of the older markup and standardize on
> that going forward.

Nice.  Of course, you should be aware that once we implement the feature
you asked for, which isn't unlikely to happen at *some* point, you might
end up wanting to edit the same places again...

> The different constraints and complications make sense.
> I do agree, that it's not clear if it'll end up being worthwhile
> or not. Depending on time, I may poke at it a little bit and see if it's
> worth panning out or if it explodes in complexity and thus isn't worthwhile.

I don't expect the *implementation* to add significant complexity,
in particular not in mandoc.  I expect relatively small, straightforward
changes at about one or two dozen places in mandoc.  The hardest
part might possibly be the groff HTML output device - then again,
maybe we can just skip that, it's low quality in the first place.

As i said, if something is not fully clear yet in this respect,
it's whether it is worth making the *user interface* (as opposed
to the implementation) larger, and whether and how it is possible
to make such links useful enough in terminal output mode (in
particular with the man/less/xterm software stack) to warrant asking
manual page authors to learn and use the extended syntax where
appropriate.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv