Hi Branden! On 4/21/23 07:00, G. Branden Robinson wrote: > Hi Alex, > > At 2023-04-21T00:29:12+0200, Alejandro Colomar wrote: >> On 4/20/23 20:33, G. Branden Robinson wrote: >>> [Note for non-mdoc(7) speakers: `Sx` is its macro for (sub)section >>> heading cross references. man(7) doesn't have an equivalent, though >>> if there is demand, I'm happy to implement one. :D] >> >> I've been delaying my global switch to non-shouting sexion headings, >> due to not having a clear idea of how to refer to them. > > Fair. > >> Having a macro that does that for me, and ensures that the appropriate >> formatting is applied might be a good solution. > > Well, I have three ideas. > > 1. Mark them up the way the groff man pages do, in typographer's > quotes. > > See \[lq]Match offsets\[rq] in > .MR regex 3 . Not bad, but if we can have some macro that hides these details, and even lets users tune their favourite formatting, that may be nicer. As a bonus, it adds hyperlinking abilities. :-) > > 2. I could implement the `Q` quotation macro for man(7) that I've been > making noise about for a while.[1] Of course, you'd be waiting for > the next release _after_ groff 1.23.0 for it... > > See > .Q "Match offsets" > in > .MR regex 3 . I'm not yet convinced by a general need for .Q. Since the single use I've needed so far for it is in section references, I guess a .SR macro is more appropriate. > > 3. I could implement a macro explicitly tuned to the problem of > (sub)section cross references. I didn't see anybody come up with a > good way to shoehorn this functionality into `MR`, so I suggest the > following. Agree; extending .MR for that seems not easy. [... fixed in reply; below ...] > > On devices supporting hyperlinks, "Match offsets" would be a hyperlink > with a to-be-determined anchor reference. "regex(3)" would be a > hyperlink as with the `MR` macro today. "Bugs" would be a hyperlink > with a to-be-determined anchor reference within the current document. > (OSC 8 support for this may require some thought, or maybe we'd just > handle them like external page references.) > > I trust the tradeoffs involved with each of the above solutions are > readily apparent. > >> It would also please the info(1) people, so that the few references we >> have to those would be linked. > > What's the URL format for hyperlinks into Info documents? You ask me about how info(1) works? :D info(1) is to me as unknown as ed(1). At least I can quit them both with q. There's not much more I know of either. > How is the > existing .UR/.UE inadequate? I meant more that man(7) would have capabilities similar to info documents. It would only be that the current implementation of man(1) is not powerful enough to do what info(1) does, but I guess it would be conceivable to implement an info-like system that got man(7) source. Similar to what this lsp(1) proposed to the list recently could do. > > Regards, > Branden > > [1] https://mail.gnu.org/archive/html/groff/2022-12/msg00078.html On 4/21/23 10:06, G. Branden Robinson wrote: > [self-follow-up; updated subject] > > At 2023-04-21T00:07:21-0500, G. Branden Robinson wrote: >> 3. I could implement a macro explicitly tuned to the problem of >> (sub)section cross references. I didn't see anybody come up with a >> good way to shoehorn this functionality into `MR`, so I suggest the >> following. >> >> .SR section-or-subsection-title [page-topic page-section [trailing-punct] > > On second thought, I think it would be better to have matched brackets > here. And more seriously, to permute the argument order to feel more > parallel to `MR` (as well as `ME` and `UE`). > > .SR section-or-subsection-title [trailing-punct [page-topic page-section]] I like this one most, by far. However, I wonder what happens when there are conflicting names for subsections. This doesn't happen often, but certainly happens. Should we disambiguate by specifying the section and subsection in separate arguments? .SR section-or-subsection-title [trailing-punct [page-topic page-section] [section-title]] I guess that will be hard to implement, but should be doable, since it's unambiguous. It also answers what to do when the chapter is not specified: it would be interpreted as a section instead, so author's fault. Some draft examples: See .SR Description See “Description” See .SR Description . See “Description”. See .SR Compilation . Description See “Compilation” (“Description”). See .SR Description . regex 3 See “Description” (regex(3)). See .SR Compilation . regex 3 Description See “Compilation” (regex(3) “Description”). Further arguments ignored. The complex thing would be that the meaning of the 3rd arg depends on having a 4th one, but it's not so bad. Does it make sense to you? Cheers, Alex > > Updating the example: > > See > .SR "Match offsets" . regex 3 > . > Also see > .SR Bugs > below. > > In this design, if argument 3 is present, argument 4 is mandatory. This > would need to be a pretty hard requirement. Maybe the default section, > if unspecified, would be "UNKNOWN". This is rude but doesn't penalize > the user any more than the document author does. (There is also > precedent in mdoc(7)'s setup macros.) We don't want to `ab`ort page > rendering for these errors because that will adversely affect innocent > users who are simply trying to read documentation. > > The foregoing would render as > > See “Match offsets” (regex(3)). Also see “Bugs” below. > > Regards, > Branden -- <http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
