Hi Alex, At 2021-05-23T16:03:30+0200, Alejandro Colomar (man-pages) wrote: > Hi Michael, > > We have some structures defined in system_data_types(7) for which we > don't have a link page, because it would have shadowed other more > important pages. > > I've been documenting 'struct stat', and it happens the same: I'd > shadow stat(2) with stat(3). > > But I need to refer to stat(3) (or whatever link page we decide to > have) from stat(2). So I need one (referring to system_data_types(7) > isn't very informative). > > How about adding struct-stat(2)? > > However, that means that we should also add struct-xxx(3) / > union-xxx(3) for all of the structs/unions we have documented there > (one might reasonably expect to be able to find struct-aiocb(3) or > union-sigval(3) if there's a struct-stat(3)). > > What do you think about it? You didn't ask me, but I'd recommend reversing the order, to put the most important information first, and that's the structure (or union) tag, not the "struct" or "union" keyword tag itself. I think the common use case is someone who has the tag in mind (or needs to know it exists) and is looking for it. It is less common that someone is going to want to browse every such page. We don't want to discourage such curiosity, but I think such people can be accommodated easily, say in the libc(7) man page. (In fact, I think that page could be made even more useful by giving a synoptical view of the C Standard Library, but that's a digression and, like a good intro(1), no small task.) Putting the tag first will also help in the tab completion case, because the tag name will be less ambiguous than "struct". We can easily imagine someone typing "man struct<TAB>" and getting blitzed with a menu of dozens of items. If I do that for "stat" on my system, I get this: $ man stat stat stat64 states statfs statfs64 statvfs statx Seeing "stat-struct" in that list would leave me with little doubt as to what the page will cover, even with the manual section missing. The use of a dash/minus as a separator "feels" unorthodox to me, but perhaps that is just the pull of blind tradition. I think it's actually a better choice than an underscore because of course "-" is not valid in a C identifier, and "_" is, so ambiguity is avoided. Regards, Branden
Attachment:
signature.asc
Description: PGP signature
