Hi Branden, On 2023-08-01 22:01, G. Branden Robinson wrote: > Hi Alex, > > At 2023-08-01T01:03:38+0200, Alejandro Colomar wrote: >>> My goal is that it not be obvious to the causal reader of a man page >>> whether man(7) or mdoc(7) was used to compose it. >> >> Function prototypes are the biggest difference, IMO. I prefer how >> man(7) pages show function prototypes (the type and the variable are >> formatted differently). Though I'll give to mdoc(7) that parentheses >> and commas in roman are nice. > > You will scandalize some people by suggesting that bold isn't the best > choice for all literals. ;-) I enjoy scandalizing people. ;-) > >> .3 pages are easily distinguished in the first screenful of text >> without looking at the source, in the SYNOPSIS. > > I think it might be tricky to achieve parity here without either: > > 1. imposing eyeball-bleeding complexity on man(7) authors; or > 2. implementing the most radical of my man(7) reform proposals: > an extensible semantic tagging mechanism. > > https://lists.gnu.org/archive/html/groff/2022-12/msg00075.html > > I'll see how we weather the `MR` storm before sailing into that one. Huh, I didn't know this meaning of weather (I didn't even know it could be a verb!). Interesting. And yes, MR will take a lot of time from us, I expect. Just remember about references to specific sections or even subsections within a page. I have been thinking about these things, and some day I'll share my thoughts, but I can resume them in "everything we suggested doesn't scale well". I'd fight that battle before going for macros specific to functions. Oh, and if you manage to have full-paragraph or even full-document knowledge before even starting to print a line, these macros might be even more juicy to add (just imagine not having to hand-craft the alignment of continuation lines of function declarations and yet having a nice alignment for a page). :) > > In any event I'd need to devote some serious time to considering the > shape of the problem of function declarations. Possibly their hopeless > variability is what led mdoc(7)'s designer(s) to implement its > challenging "called"/"parsable" system of argument interpretation. > > And think--C language declaration syntax has gotten _more_ complex since > mdoc fossilized around the time ANSI C froze. Type qualifiers are far > more often used now, and attributes were, if not inconceivable, then on > a distant horizon. And consider my proposal for a GCC extension to use array notation in a backwards manner with buf[.size]. It won't be nice. > > But maybe that won't matter: with only three font styles available > (though we probably _could_ employ bold-italics if we _had_ to), there > is a limit to how many different sorts of things we can represent. We'll see. Cheers, Alex > > Regards, > Branden -- <http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
