Hi Branden, On 5/23/21 4:26 PM, G. Branden Robinson wrote: > You didn't ask me, Your feedback is, as always has been, very valuable and appreciated :-) If I sometimes don't answer to some of your mails, it's because I don't have enough background to understand it, and prefer to wait for an answer of Michael ;) > 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. Hmm, interesting. > > 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. Agree. > 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.) Interesting idea too. Ideally, for functions, that would be as easy as listing all of the pages in man3 (right now that would be mixing functions and types; for something more precise, see my function man_lsfunc() in <scripts/bash_aliases>). I think it's very unlucky that historically there hasn't been a section for the types, so that we could do the same with the types, and now we're (ab)using section 3 (BTW, do you have any opinion on this? I'm not sure how we should proceed with that in the long term). Specifically, I think that we're breaking the ability of listing all of the pages to know which functions there are. I thought of adding a new subsection (maybe 3t) for types. And there's also another thing: there's no way of listing constants (you either read the standards documents (or the manual pages) entirely (and you will miss implementation-specific details), or read the source code (and become crazy in the process)). > > 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. Yes. Maybe a simpler option to having an entirely new subsection would be to always have a suffix -struct (or _struct) (or [-_]union) for types (others (typedefs) already have _t). > > 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. I used struct-foo because man has the ability to allow either 'man struct-foo' or 'man struct foo', and the latter looks very intuitive from a C-syntax perspective (I learnt this from the git manual pages, where you can do 'man git log' or 'man git-log'). 'man man' doesn't specify this behavior, so I'll read the source code and try to confirm how it works. Regards, Alex -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
