https://bugzilla.kernel.org/show_bug.cgi?id=57181 --- Comment #4 from Serge van den Boom <serge+bugzilla.kernel.org@xxxxxxxxxx> --- > So here's an example of ptroblem. 'struct timespec' is in 15 pages. Why point > to this one in particular. I can see it's not a bad page to point to. But, if > you are using one of the other APIs, then laning on nanosleep(2) would be > confusing. I am not singling out 'struct timespec'. In my opinion, we would benefit from being able to use *any* structure name as a keyword to man. My list was intended to show the wide variety of non-trivial structures which one might want to look up. You are right that if you are using one of the other functions, that landing up on another one than the one which you are actually using, might sometimes be confusing. And in fact, I would prefer to have a separate page for each structure. However, even if you sometimes end up on a page of another function which uses the same structure, this is better than having no match at all. At the very least, it gives you a starting point for subsequent searches. And often, you *will* end up at the right page. Or even if it is the wrong page, the structure description will be usable. For me, being able to press 'K' in Vim on some structure name to find out what fields it has, is reason enough to want the structure name to lead somewhere. > > [...] > > I don't really buy this reasoning. If I'm using sendmsg(), then I'm probably on that page already before step 1. Ok, this may not be the most realistic example, but the idea holds for any of the structures. Maybe sockaddr_in works better for this example. Also, having structures as man keywords doesn't just help with writing code, but also with reading someone else's code. If you read code in the order in which it occurs, you'll see the structure being filled before it is passed to some syscall or C library function. In fact, the actual call may be in another (user) function altogether. If you want to know more about what exactly those values being assigned to the various fields mean, you just want to lookup the structure name, instead of first having to figure out in what function it might be used. And I sometimes use these standard structures in my own code (why reinvent the wheel?). In one real-life example, I needed to have some structure to store a time period in, and I know that various standard types exist (struct timeval, struct timespec, time_t), but I couldn't recall the details of each type. So to find out which would be the most suitable, I would have had to think of various standard functions which would use these types. (Though I might have ended up grepping in /usr/include instead; I don't recall exactly. Maybe both even.) But even though I'm now trying to think up all sorts of past and hypothetical situations where it would be useful to be able to look up a structure by its name, the reason why I originally took the time to write the bug report (and the follow-ups now, a year later), is because I have in fact (on multiple occasions) felt the need to perform such lookups. And if I have, so will have others. > Now, whether there should be separate pages for a few structures is something to think about more, but I'd need to see a good reason in each case. (sigevent(7) had a good reason, for example.) I personally would like to be able to search for *every* standard structure, and for typedefs too actually. Even if the resulting pages just contain a reference to the pages of functions which actually use the type, this would be of value. But ideally, the specifics of the fields would be explained there as well. I understand that this might be too much work to actually implement, but I do think that the value is real. Maybe I'll even submit a patch myself one day, if this is the situation. Regards, Serge -- You are receiving this mail because: You are watching the assignee of the bug. -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
