On 2026-05-28T23:24:06+0200, Alejandro Colomar wrote: > Hi Carlos, > > On 2026-05-28T14:39:15-0400, Carlos O'Donell wrote: > > On 5/28/26 9:06 AM, Michael Kerrisk (man7.org) wrote: > > > I don't think the Linux system call and C library manual pages are a > > > good place to promote this obscure GNU feature. It is confusing > > > people, including me. (I came to making this report because several > > > people have reported this "bug" on various pages rendered at > > > man7.org.) > > > > > > Please consider reverting these changes. These markings use > > > little-understood, nonportable syntax. The manual page synopses should > > > be in standard, portable C that is *easy* to understand. > > > > I agree with Michael. > > > > I think these changes should be reverted, but it's a question of > > goals and values for the project, and the purpose of the SYNOPSIS. > > > > My view was always that they were the simplest expression of the > > interface that the widest possible audience could understand, and > > that seems to align with Michael's view. > > That doesn't provide much value, IMHO. My opinion of the SYNOPSIS is > that it's a quick reminder of how a function should be used. > > Let's take a real example: > > long mbind(void *addr, unsigned long len, int mode, > const unsigned long *nodemask, unsigned long maxnode, > unsigned int flags); > > I honestly don't know anything from the prototype above. Apart from the > types, there's no useful information. There are the names which will > later be described in the description, but so far they're not useful. > > long mbind(unsigned long size, unsigned long maxnode; > void addr[size], unsigned long size, int mode, > const unsigned long nodemask[(maxnode + ULONG_WIDTH - 1) > / ULONG_WIDTH], > unsigned long maxnode, unsigned int flags); > > This already introduces me the function quite well. The description > will of course clarify details, but I can already see some things. > > > It certainly isn't for me as a C library author... > > The SYNOPSIS is for everyone. I read the synopses regularly while > programming. In fact, I read it quite more than the descriptions, which > I only read seldom, when interested in some rare details. > > > it's for > > someone just learning or refreshing knowledge, and what makes > > it easiest for a new person or someone less familiar to consume? > > Speaking of myself as a new programmer not so long ago, I would have > appreciated these synopses. > > > It seems like we've drifted toward describing the interface *and* > > the constraints in a compact form (like N3433). Is that in line > > with the goals of the project? > > I think it is. At least with how I see it. > > I also don't see much difference between the interface and its > constraints. They are deeply related (array parameters are part of the > type system, after all). If we wanted to know the names of the > arguments and their order, we could have something much simpler: > > mbind(addr, size, mode, nodemask, maxnode, flags); BTW, FWIW, this resembles quite a lot the documentation from the times of V7 Unix. Here's how functions were documented back then. SYNOPSIS char *ttyname(fildes) isatty(fildes) ttyslot() AFAICS, 4.4BSD is the first BSD that used function prototypes (both in the source code and documentation). You could similarly argue that that was unnecessarily confusing programmers back then (most programmers of the time might not be aware of the innovation of function prototypes, and why one would care about parameter types, especially when being introduced to a function). However, we'll probably agree that that was a good change. I would find a prototype without types to be quite uninformative. Cheers, Alex > > But of course we don't want that. > > > It's not like these are the *real* prototypes in your C library, > > Implementation details are unimportant. > > > since those are much much more complicated and difficult to > > understand. It's also not like they match the GNU C Library > > manual's description via `info libc mmap` that are presented > > to users of the library. > > I don't see why both documentations should agree in the details. Of > course, I'd like the libc manual to be more detailed, but there's no > inherent reason why both should be exact matches, as long as they're > compatible. > > > What is the intent of the SYNOPSIS field and the prototypes > > therein? What are the goals or values of the project around > > that information? > > That information should introduce the API, giving enough details to > understand a decent amount of it. It should also remind quickly of > some details such as whether an argument may be null, or which sizes > correspond to which arrays, so that programmers can quickly check those. > > > There is certainly some syntax that is valuable for compilers > > enforcing constraints and providing warnings, but is that > > valuable for man pages readers? > > For me, as a frequent reader, it is very valuable. YMMV. > > > For manual pages overall I think the forward declarations > > are a net negative change in readability. I would continue > > to express the constraints in plain prose. > > I tend to disagree. For example, let's consider the addition of > 'restrict' (I added it a few years ago, when Michael was still around, > IIRC). > > $ find man -type f | xargs grep -rl '[[*]restrict' | wc -l; > 137 > > Here's the prose in memcpy(3), which I haven't removed yet (because it's > historically more relevant in memcpy(3)): > > CAVEATS > Failure to observe the requirement that the memory areas do not overlap > has been the source of significant bugs. (POSIX and the C standards are > explicit that employing memcpy() with overlapping areas produces undefined > behavior.) Most notably, in glibc 2.13 a performance optimization of mem‐ > cpy() on some platforms (including x86‐64) included changing the order in > which bytes were copied from src to dest. > > If we had to replicate this paragraph in 137 pages, we'd be adding walls > of text unnecessarily. And it would be a problem for maintaining that > text. Now that we use 'restrict', it's just a few keywords in the > SYNOPSIS, and it's all well documented (but you need to know what that > keyword means, of course; there's a trade-off). (Another matter is that > 'restrict' is utterly broken as a keyword for source code; but for > documentation purposes it's relatively fine. The same thing happens > with Clang's _Nullable, which has never really worked in source code.) > > > Have a lovely night! > Alex > > > > > $0.02. > > > > -- > > Cheers, > > Carlos. > > > > -- > --