Re: Plan 9 man added a new macro for man page references

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Wed, Aug 04, 2021 at 02:06:09PM +1000:

> I owe Doug McIlroy an apology for, some months ago on this list,
> significantly understating his diligence as editor of Volume 1 of the
> Version 7 Unix manual (1979).  A meticulously numerical accounting of
> just one aspect of that effort follows in this (lengthy) email.

Interesting.  So v7 actually used I(R) outside and R(R) inside SEE
ALSO, almost consistently.  Which means you do have tradition on
your side.

Regarding the argument that manual page names are work titles,
generally set in italics in typesetting - that seems less important
to me than that the vast majority of them are command and function
names, and also less important than that they don't need additional
markup because the following section digit in parentheses already
conveys the meaning.


> At 2021-08-01T14:06:38+0200, Alejandro Colomar (man-pages) wrote:

>> Interesting.  You could make it search for SH and SS coincidences.

> They don't have to be coincidences; it's possible to extend SH and SS
> themselves to plant "anchor targets" which can be used by MR.  Such an
> extension involves *roff "device escapes" (probably using groff's
> devtags.tmac) and would not be visible to, or require anything of, the
> man page writer at all.

That`s essentially what mandoc(1) already does, and not only for .SH
and .SS content, but also for .TP and .IP heads:

  https://man.openbsd.org/gdb.1

Watch out for dotted underlining in that man(7) page.


> At 2021-08-01T15:49:25+0200, Ingo Schwarze wrote:
 
>> It turns out the concept of remote deep linking in manual pages is
>> rarely needed, for several reasosn.
>> 
>> Well-designed programs tend to be simple, doing one thing well.

> Even granting this arguendo--I'm not sure it holds for programs that
> aren't _designed_ to participate in the Unix pipeline/filter
> model--there are plenty of counterexamples in the field with a long and
> successful history, like ffmpeg and ImageMagick/GraphicsMagick.

Granted, and i have used both of these programs a lot, even though
neither are easy to use and their documention isn't either.

> I know you have an even stronger prescriptivist bent than I do, and so
> your response might be to leave such ill-conceived programs
> undocumented, thus hastening their deaths in the hopes that
> philosophically pure replacements will come along and which will
> incidentally fit neatly into the mdoc(7) schema without requiring deep
> links.

No, my opinion is that, if a program happens to be excessively
complicated, that doesnt lessen the need for good documentation.
It makes the documentation harder to read and the program less
useful, but not useless.  Not having documentation would make it
mostly useless, which is clearly undesirable.

Besides, some manual pages are unavoidably long and complicated
even though being part of the UNIX way, shell manuals being the
canonical, but not the only, example.

Deep linking does have uses, and i use it a lot when answering
questions on mailing lists, pointing to specific paragraphs of
specific online manual pages.

> That might be the OpenBSD way, but it's not how many GNU/Linux
> distributions operate; they're eclectic, and for better or worse
> assimilate software projects that adhere weakly or not at all to that
> principle.  Some of the people who use them are going to want to see
> them documented.  A few of those, perceiving a lack of documentation,
> are going to want to supply it.

All granted.

>> Consequently, well-written manual pages for well-designed programs
>> tend to be short.  When linking to a short document, deep linking
>> matters little.  Besides, deep linking is not necessarily beneficial.
>> The reader being refered to that other page needs to grasp some
>> context regarding what that other page is about, and that is easiest
>> to get from the page title, the Synopsis section, and the first
>> sentence of the Description section - i.e. from the beginning of the
>> page.  Being plunged right into the middle of a document is not always
>> helpful, *especially* when the document is large or complex.

> Some readers, you can trust to recognize when they're missing context
> and to "zoom out" with respect to the scope that the reference takes
> them.

Granted, too.

> [...]
>> I'm not saying deep linking is completely irrelevant or i would not
>> habe been considering and discussing it for the last six years.
>> But i do insist that it must not dominate the discussion of linking
>> as a whole.  It is *much* more important that simple use cases of
>> linking work in a way as simple as possible for authors and readers
>> than that deep linking is available.  In other words, designing deep
>> linking must not spoil the overall design of linking.  There is a
>> very substantial danger of overengineering here.

> I'm willing to postpone implementation of that aspect of MR pending an
> expression of demand; Alejandro is well-placed to assert whether he sees
> a need based on his Linux man-pages experience.  Given the interface
> proposals mooted already, I think the feature can (and, if done at all,
> should) be grafted on without invalidating the "shallow" syntax.

It certainly seems as if it could likely turn out to be possible.
Hard to say whether hidden obstacles might or might not show up later.

>> Note that the concept of trailing punctuation arguments is standard
>> for mdoc(7) macros but feels somewhat alien to the man(7) macros.

> Not if you support groff man(7)'s .MT/.ME and .UR/.UE.  ;-)

Mandoc does support these, but their suffix support on the end macro
is the exception rather than the rule for man(7).  Besides, these are
block macros and the suffix argument is on the block-ending macro,
whereas .MR is an in-line macro and the suffix argument would be at
the end of the main macro itself.

I'm not saying that's out of the question, but merely that it is not
particularly uniform language design.

[...]
> I am not a fan of mdoc's practice of inferring a data type from a macro
> argument by parsing it.

In general, i agree with your reluctance.  For the specific case of
trailing punctuation, it isn't as bad as in general and allows very
simple and natural syntax in practice.  Then again, no real need to
imitate it in man(7), which already has its own tradition of using
font-switching macros for the purpose.

> Without a mechanism for named parameters (which
> mdoc also implements along the lines of Unix option syntax in macros
> like 'Bl', and which some groff macros like PSPIC also employ), position
> in the argument list is the thing the user, or package, can know.  In
> man(7)'s case, I think that's a benefit.  I want to keep the language
> that simple.

No doubt a laudable goal.

>> An alternative would be using the .Tg macro that already exists in
>> the mdoc(7) language for a related purpose, as follows:
>> 
>>   .Tg deep_target
>>   .Xr page sec [punctuation_suffix_args]
>> 
>> The purpose of .Tg is to mark the next token as a link target.
>> Since .Xr can never be a useful link target, letting the deep_target
>> name refer to the *target* page rather than the *source* page when .Tg
>> precedes .Xr feels kind of natural.
>> 
>> This .Tg / .Xr design provides the side benefit of not changing the
>> syntax of .Xr that has been established for three decades, so it has
>> better backward compatibility properties than the three-argument idea.
>> Again, i'm not claiming just yet this is the best idea.

> Yes, I think the above idea has some merit.  For man(7) we can infer
> link targets automatically for SH, SS, and TP.

Exactly, and just what mandoc(1) already does.  The .Tg macro is needed
rarely.  It merely serves the unusual cases where automatic detection
of link targets does not work well.

>>>>> * Added support for another string, perhaps 'MB' ("manref
>>>>> base"?), supplying a base URL which can be set at
>>>>> page-generation time.  Embedding a full URL in man pages sources
>>>>> to an inherently relocatable page hierarchy is a bad idea.

>> That feels like a feature for the formatter, *not* a feature for the
>> markup language.
>> 
>>   https://man.openbsd.org/mandoc.1#man~2
>> 
>> Note that the mdoc(7) documentation is not encumbered by this -O
>> man=... feature of the mandoc(1) formatter at all.

> You're confusing me.  troff _is_ the formatter (well, in conjunction
> with the output device driver/postprocessor, which is what matters
> here).  A link will not be resolvable until the page is formatted, and
> when it is, it will be generated in a context.  That context has to be
> communicated to troff (and then the output driver) somehow.  That
> context _cannot come from the man(7) document source_.  But it _can_
> come from the man(7) macro _package_, _at the time the document is
> processed_.  A roff string seems like the obvious way to implement this.
> It would still be a man(7) feature because it's going to be up to
> man(7)'s MR implementation to inject the contents of this string into
> the device escape that contains the URI.
> 
> As with the PT and BT hooks of groff_man(7), such an MB string is not
> something than a man _page_ should ever touch or worry about.

Ah yes, the usual problem that the roff pipeline discards all the
semantic structure right at the beginning and that the output devices
no longer have access to information contained in the source document,
in this case "this was a manual page cross reference".

My point is -O man= / \*(MB is a job for the output device.  It is
totally different for HTML or terminal or PDF output.  The HTML
output device wants to build URIs and hence likely needs a base URI,
but that's completely useless for the other devices.  So logically,
making it an option to the output device/postprocessor (like grohtml)
would seem adequate.  But that doesn't work with roff pipelines already
having discarded all the required information...  :-(

So maybe some layering violating contortions invading the macro
package files like the ones you mentioned are needed.  Not sure,
it still feels disgusting to me, but if no better idea can be found...

Yours,
  Ingo