[CC += linux-man@] [Context: https://lwn.net/ml/libc-alpha/875300cf-92ca-c115-c42d-19dda5de5a4a@xxxxxxxxxx/] On Fri, May 22, 2020 at 3:07 PM Carlos O'Donell via Libc-alpha <libc-alpha@xxxxxxxxxxxxxx> wrote: > > On 5/21/20 8:22 PM, Martin Sebor wrote: > > On 5/21/20 4:11 PM, Carlos O'Donell wrote: > >> On 5/21/20 1:46 PM, Martin Sebor wrote: [...] > > It would be a considerable > > effort to bring the manual up to par with the Linux man pages. I see > > little point in investing it into duplicating what already exists > > elsewhere and what according to documentation.html many of you are > > already contributing to. My suggestion instead is to declare > > the Linux man pages the reference and treat the manual as a user > > guide. So, as an aside, I think the Linux man-pages are rather better than the glibc manual in many areas, but there some areas where where the reverse is true. And lately I see patches to the glibc manual from Florian, and sometimes I realize: "oh that's not covered in Linux man-pages". So, notwithstanding what the glibc developers may thing of the idea, from my perspective the notion of declaring man-pages as the [authoritative] reference would not be without problems. > I appreciate your suggestion. > > I agree it would be a waste of time to duplicate what already exists. > > The glibc manual should be a guide and it should contain complete and > authoritative information about the APIs it implements. This does > not include version-by-version changes, bugs, raw syscalls, etc. > > I think having the linux man pages as a non-authoritative reference > is very good, and I contribute to the linux man pages. > > I think having WG14 work on ISO C is also good, so I contribute where > I can to SC22 in Canada for that reason. > > That makes 4 documents covering the same APIs! > > * ISO C (the standard) > * POSIX (the extended standard) > * glibc manual (the authoritative manual for glibc's implementation) > * Linux man pages (detailed syscall and API reference documentation) > > FWIW they all serve different purposes. > > The linux man pages are *great* they even document version to version > differences and if you're interested in targeting specific versions of > glibc you can use them accurately to write code that does exactly > what you would expect. That's awesome! Our manual does not have that as > a goal. > > >> This is not a duplication of effort IMO. The manual and the linux man > >> pages solve different needs. The manual is task-oriented, covering > >> sections of the standard APIs and how they could and should be used > >> together, And yes, in places this is where the glbc manual does really excel. > >> while the the linux man pages are API references only > >> (in isolation to the larger set of APIs). Broadly true, although in places, Linux man-pages tries also to draw bigger pictures (e.g., various overview pages in Section 7). [...] > > A report of the warning above is what prompted my question. I had > > checked the C and in some cases also POSIX standard as well as > > the Glibc manual when adding the attribute. C doesn't have this > > extension, Glibc doesn't document it, and I missed it in POSIX (or > > more likely didn't think to look there in this case). What I was > > looking for with the question is an acknowledgment of what I had > > suspected, namely that the Linux pages can be trusted to accurately > > document this and other Glibc extensions. > > The linux man pages can *absolutely* be trusted to document every > change glibc makes, but that doesn't make them authoritative, it makes > them detailed. As a developer I love the detail in `man mbstowcs`. I commented on this already. I wish the above were true, but Linux man-pages does not manage to track all of the changes. [...] > > But from a simple usability point of view, it's unhelpful to tell > > people to consider the union of the Glibc manual and all external > > documentation (or some subset of it). Not just because it's > > impractical to read everything, but also because not everything > > is correct or up to date. How are they/we supposed to resolve conflicts? > > We resolve conflicts by writing things in the manual to cover such cases, > and we do so tactically to resolve problems as they arise. > > Over the years the project has had a significant lack of engagement with > writing good documentation, Yes, the manual seems to have started very well, but then the wheels came off for many years. (Surprisingly, during that time I would occasionally get a piece of very helpful input for man-pages from Ulrich Drepper!) > and I can understand that. It's hard to > write clear and unambiguous English sentences to describe an interface > and how it dovetails into the rest of the APIs. Yes, best to leave that task to the Germans. (Sorry; I could not resist the hat tip to Florian.) > Such writing is not as > much fun as writing code. Yes, I never really understood that one. It's only by explaining (my) code very clearly at least to myself, but probably to others, that I can feel like it is/I have written good code. Writing good human language expression is just as much an interesting challenge as writing good programming language expression. > We really need to engage with technical writers > and involve a broader set of industry skills in our projects. I want to add a note of caution here. It's great to have technical writers (and like good developers companies should be paying them), but they can't do the job on their own. A lot of developer input is still required. Thanks, Michael
