Re: function prototypes, man(7), and mdoc(7) (was: boldface, italics, spaces and ellipses in synopses of commands, and *nix history)

[Alejandro Colomar]

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

OpenPGP_signature
Description: OpenPGP digital signature