Hi Alex! At 2022-02-07T18:34:15+0100, Alejandro Colomar (man-pages) wrote: > Hi Branden, > > How would you use .MR on non-man[23] (e.g., man1) pages to refer to > the same topic of the manual page? I mean, how would you refer to > groff(1) from within groff.1? > > .MR groff > .MR groff 1 > > ?
It's an open question, and there is an unresolved difference of opinion between me and Ingo Schwarze (mandoc maintainer) about a somewhat broader issue. Here's the background from last August[1]. Reading all 3 messages in the thread is recommended. In summary, I see man(7)'s new `MR` as roughly analogous to mdoc(7)'s `Xr`. However, by accident (apparently), groff's mdoc(7) implementation supports single-argument calls of `Xr`. mandoc(1) complains about this. Ingo says that an mdoc(7) page making a self-reference should use `Nm` for this purpose, and I see no reason to argue. At the same time, man(7) has no counterpart to `Nm` and in my opinion, introducing one for this purpose would not "pay its freight". My ideas about a general semantic tag system for man(7) are starting to take shape, and I'm inclined to share them soon, but I'm more inclined to get a groff-1.23.0-rc2 out. Long story short, if something like what I have in mind for semantic tags takes shape, it will take only two new macros at most, and most man(7) pages in sections 1, 6, or 8 (commands) wanting to follow groff pages' practices will need only one of those. > If you omit the number, you get empty parentheses, which for man[23] > pages looks good (they are functions, and that syntax looks good for > them), Yes, I think this something like what mathematicians call an abuse of notation. That parentheses are both commonly used as a function invocation operator and to set off man page section numbers from titles is a typographical accident. And not one without cost...let me quote the forthcoming groff 1.23.0 NEWS file. [`MR`'s] purpose is to ameliorate several long-standing problems with man page cross references: [...] (2) false-positive identification of strings resembling man page cross references (as can happen with "exit(1)", "while(1)", "sleep(5)", "time(0)" and others) by terminal emulators and other programs; [...] Right now the second argument to `MR` is mandatory (did I forget to put in a style warning?--no, I didn't). If I were to loosen the syntax to permit an empty second argument, I would have the macro _not_ supply any parentheses, and if you wanted abutting punctuation, I would require the man(7) writer to put `\c` at the end of the first argument. So the new `MR` synopsis would be as follows. .MR page-title [page-section [trailing-punct]] Thus if you wanted to talk in a section 2 or 3 page about some C function name that has a man page to which you'd already referred, you would write, for example. The .MR gmtime\c () function converts the calendar time .I timep to broken-down time representation, Omission of a second argument would also necessarily suppress hyperlink generation. Maybe there's even an upside to this; if consistently applied, function call references that _weren't_ man page cross references would become extremely easy to locate with grep. '^()' ought to do it. > but for commands, it looks weird. Oh, definitely. > And if you specify the section, you're a bit repetitive (but that's > better than nothing). Yes. This doesn't seem to worry Ingo much, but I'm a bit more sympathetic to the "writerly" concern of avoiding excess repetition. (That said, I frequently use parallel constructions in man(7) documents rigidly and without shame, to make it clear to the reader that parallel semantics or behavior are to be inferred--and also because man pages are so frequently not read in linear sequence, but full-text searched and the least possible amount of material absorbed to resolve the immediate concern.) > And then there's the option of using .B, or .I, but as we know, > there's no consensus on which of them should be used. Right. I don't see any solutions for this apart from making `MR` more permissive, supporting "semantic tag classes" (my pie-in-the-sky idea above), or bloating the macro name space for a something of limited and specialized function, and the last is my least favorite by a long shot. If someone else has a better imagination, please speak up. At intervals over the past few days I've been drafting an email in my head about my further man(7) reforms; there are three. One is above. The other two involve the lack of a macro for quotation and the lack of a non-deprecated, non-tbl(1) way to eliminate the space between paragraphs in lists. Regards, Branden [1] https://lists.gnu.org/archive/html/groff/2021-08/msg00035.html
signature.asc
Description: PGP signature
