Re: Cross references to specific sections in other manual pages

[Ingo Schwarze <schwarze@usta.de>]

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