Bug#477402: manpages-dev: Formatting problem in utime(2)
On Wed, 23 Apr 2008, Michael Kerrisk wrote: We perhaps disagree a little on the balance between that and other factors, but I think we fundamentally agree on what's good to aim for. I think so. I had written rather more on the subject but deleted it as I thought I would be unlikely to convince you! PS I added a subheaduing in mmap.2 and am wondering about whether msgop.2, semop.2, shmop.2, and getopt.3 could do with some restructuring and/or headings to make their structure clearer. The odd thing about msgop(2) is that there is no msgop(2). I suggest fixing that by removing the text msgop from the page, and renaming it to msgsnd.2 or msgrcv.2, and having msgop.2 link to it. Other than that I have no problem with the structure of the page, as one probably needs to understand sending and receiving together. In getopt.3 I would have a heading for the long variants. shmop.2 has the same problem as msgop.2, and looks like it could do with per-function headings. semop.2 actually exists! and I have no problem with its layout. -- http://rrt.sc3d.org/ | Floc: an egregiously good aperitif -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#477402: manpages-dev: Formatting problem in utime(2)
On Fri, Apr 25, 2008 at 12:38 PM, Reuben Thomas [EMAIL PROTECTED] wrote: On Wed, 23 Apr 2008, Michael Kerrisk wrote: We perhaps disagree a little on the balance between that and other factors, but I think we fundamentally agree on what's good to aim for. I think so. I had written rather more on the subject but deleted it as I thought I would be unlikely to convince you! Well, sometimes arguments will sit in my mind for a while, and precipitate action at a (rather) later date. PS I added a subheaduing in mmap.2 and am wondering about whether msgop.2, semop.2, shmop.2, and getopt.3 could do with some restructuring and/or headings to make their structure clearer. The odd thing about msgop(2) is that there is no msgop(2). I suggest fixing that by removing the text msgop from the page, and renaming it to msgsnd.2 or msgrcv.2, and having msgop.2 link to it. I agree that it's odd, but the name msgop (message operations) is historical -- you'll find it on many (most? all?) Unix variants, so it should be kept. Other than that I have no problem with the structure of the page, as one probably needs to understand sending and receiving together. In getopt.3 I would have a heading for the long variants. Yes, that was what I am tempted to do Done now. shmop.2 has the same problem as msgop.2, and looks like it could do with per-function headings. See above. I consider the need for per-function headings here as borderline. The page is not too long, and the material is a bit mixed up (e.g., general comments aboyt fork() and exec() follow the shmdt() description). I've made a note to review the structure of this page later. semop.2 actually exists! and I have no problem with its layout. Thanks for your input Reuben. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#477402: manpages-dev: Formatting problem in utime(2)
On Fri, 25 Apr 2008, Michael Kerrisk wrote: The odd thing about msgop(2) is that there is no msgop(2). I suggest fixing that by removing the text msgop from the page, and renaming it to msgsnd.2 or msgrcv.2, and having msgop.2 link to it. I agree that it's odd, but the name msgop (message operations) is historical -- you'll find it on many (most? all?) Unix variants, so it should be kept. I agree that the name should be kept, I just don't think that it should be in the page, at least not without some note to explain it; otherwise comparison with semop(2) might lead users to the (wrong) conclusion that there was a missing function. Comparison with msgop.2 might lead to a different conclusion, or it might just mystify further. shmop.2 has the same problem as msgop.2, and looks like it could do with per-function headings. See above. See above. -- http://rrt.sc3d.org/ | irrevocable, a. expensive; see also lawyer -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#477402: manpages-dev: Formatting problem in utime(2)
On Fri, Apr 25, 2008 at 1:23 PM, Reuben Thomas [EMAIL PROTECTED] wrote: On Fri, 25 Apr 2008, Michael Kerrisk wrote: The odd thing about msgop(2) is that there is no msgop(2). I suggest fixing that by removing the text msgop from the page, and renaming it to msgsnd.2 or msgrcv.2, and having msgop.2 link to it. I agree that it's odd, but the name msgop (message operations) is historical -- you'll find it on many (most? all?) Unix variants, so it should be kept. I agree that the name should be kept, I just don't think that it should be in the page, at least not without some note to explain it; otherwise comparison with semop(2) might lead users to the (wrong) conclusion that there was a missing function. Comparison with msgop.2 might lead to a different conclusion, or it might just mystify further. Not sure if that was all you wanted, but I removed msgop and shmop from the NAME section of the respective pages, to reduce the kind of ambiguity you are talking about. shmop.2 has the same problem as msgop.2, and looks like it could do with per-function headings. See above. See above. See above ;-). I went away now and checked. It seems that the names shmop and msgop are less widespread nowadays, but they were used on the first two Unix systems I used. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#477402: manpages-dev: Formatting problem in utime(2)
On Fri, 25 Apr 2008, Michael Kerrisk wrote: Not sure if that was all you wanted, but I removed msgop and shmop from the NAME section of the respective pages, to reduce the kind of ambiguity you are talking about. That's exactly what I meant. I went away now and checked. It seems that the names shmop and msgop are less widespread nowadays, but they were used on the first two Unix systems I used. I have no problem with historicisms (for example, I'd be happy with keeping a symlink to or from *op.2 pretty much indefinitely) but equally, as with various no-longer-documented APIs in glibc, I prefer to hide obsolete names from view so that only people or programs that know they're there can get at them. -- http://rrt.sc3d.org/ strike, v. 1. to act, 2. to refuse to act (Turnbull) -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#477402: manpages-dev: Formatting problem in utime(2)
Hi Reuben, On Wed, Apr 23, 2008 at 1:04 AM, Reuben Thomas [EMAIL PROTECTED] wrote: Package: manpages-dev Version: 2.79-2 Severity: minor In the DESCRIPTION section, utimes() has an outdented heading, but utime() does not. By comparison with other similar man pages it seems the most consistent thing would be to remove the heading for utimes(). There are some other pages that are like this, e.g., poll.2, epoll_wait.2. At the moment I have no plans to change this upstream. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#477402: manpages-dev: Formatting problem in utime(2)
On Wed, 23 Apr 2008, Michael Kerrisk wrote: Hi Reuben, On Wed, Apr 23, 2008 at 1:04 AM, Reuben Thomas [EMAIL PROTECTED] wrote: Package: manpages-dev Version: 2.79-2 Severity: minor In the DESCRIPTION section, utimes() has an outdented heading, but utime() does not. By comparison with other similar man pages it seems the most consistent thing would be to remove the heading for utimes(). There are some other pages that are like this, e.g., poll.2, epoll_wait.2. In that case, there are two inconsistencies: that between pages like this and pages not like this, and that within the pages, between the functions that have headings and those that don't. I suggest you pick a preferred style. I'd be happy to have a look for pages that don't currently match your preferred style, and submit patches. Since it's not a major problem, it doesn't matter if not all the pages that need fixing are found in the first pass. I find having headings makes the pages that deal with multiple functions more legible, so I'd be happy to add them for the first function in each case, and to multi-function pages that currently lack any per-function headings. -- http://rrt.sc3d.org/ | sad, a. the efforts of musical debutantes (Bierce) -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#477402: manpages-dev: Formatting problem in utime(2)
Hi Reuben, In the DESCRIPTION section, utimes() has an outdented heading, but utime() does not. By comparison with other similar man pages it seems the most consistent thing would be to remove the heading for utimes(). There are some other pages that are like this, e.g., poll.2, epoll_wait.2. In that case, there are two inconsistencies: that between pages like this and pages not like this, and that within the pages, between the functions that have headings and those that don't. I agree that there is probably some inconsistency between pages. It's a consequence of having many different authors. I suggest you pick a preferred style. My preferred style is something like this: use the outdented headings, but only in pages where it's needed because the description is long, and it might otherwise be harder for the reader to find the discussion of one of the functions (e.g., see dlopen.3), or because some details are specific to just a single function (in which case I am inclined *not* to put a heading for the the funtion that is the first or main subject of the page. I'd be happy to have a look for pages that don't currently match your preferred style, and submit patches. Since it's not a major problem, it doesn't matter if not all the pages that need fixing are found in the first pass. I find having headings makes the pages that deal with multiple functions more legible, so I'd be happy to add them for the first function in each case, and to multi-function pages that currently lack any per-function headings. Consider my point above. If you are willing, you could start looking at a few pages in Section 2, and make some suggestions to me. Please don't try reviewing all pages yet. (i.e., avoid too much effort.) I'm still undecided about whether I want to add more of these headings -- but if you suggest some things that seem wise, then I may do so. Cheers, Michael -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#477402: manpages-dev: Formatting problem in utime(2)
On Wed, 23 Apr 2008, Michael Kerrisk wrote: I agree that there is probably some inconsistency between pages. It's a consequence of having many different authors. This is quite natural; equally, especially under central maintainership, it's nice to fix up. The more consistent that core man pages are, the better the example they provide to the many more man pages that are shipped with individual software packages. One hopes in particular to influence the author of the various automatic conversion programs that now regularly churn out man pages, usually, with some honorable exceptions, of low quality. My preferred style is something like this: use the outdented headings, but only in pages where it's needed because the description is long, and it might otherwise be harder for the reader to find the discussion of one of the functions (e.g., see dlopen.3), or because some details are specific to just a single function (in which case I am inclined *not* to put a heading for the the funtion that is the first or main subject of the page. I find having a heading for some functions and not others to be confusing, but I do take the point that often the first paragraph is applicable to all the functions described by a page, and that therefore one doesn't want to have a header of just the main function's name, as that implies that the information is not relevant to the other functions. It would be less likely to confuse if pages like utime(2) didn't have the function's name as the first word of a paragraph, so instead of utime()... it started The function utime() This would stop it looking like a mis-formatted heading (which as the bug title shows is what I first thought it was). The point about length of page is well made, but I think there are two other considerations: 1. Printed pages can more easily be designed like that. With man pages, it's hard to tell what constitutes short or long, given the vast range of screen sizes, reading software, c. e.g. man on an 80x25 terminal vs web browsing of an HTML-rendered version on a 24 screen (or even a 3 display!). 2. man pages are highly structured, to the point that consistency is as important than aesthetics for readability. In particular, deviations are easily noticeable, and will make many readers (like me!) wonder whether something is wrong. -- http://rrt.sc3d.org/ | compulsion, n. the eloquence of power (Bierce) -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#477402: manpages-dev: Formatting problem in utime(2)
On Wed, Apr 23, 2008 at 5:18 PM, Reuben Thomas [EMAIL PROTECTED] wrote: On Wed, 23 Apr 2008, Michael Kerrisk wrote: I agree that there is probably some inconsistency between pages. It's a consequence of having many different authors. This is quite natural; equally, especially under central maintainership, it's nice to fix up. The more consistent that core man pages are, the better the example they provide to the many more man pages that are shipped with individual software packages. I completely agree with this, and in fact much work has gone into consistency fixes in the last couple of years (see the end of http://www.kernel.org/doc/man-pages/todo.html ). One hopes in particular to influence the author of the various automatic conversion programs that now regularly churn out man pages, usually, with some honorable exceptions, of low quality. My preferred style is something like this: use the outdented headings, but only in pages where it's needed because the description is long, and it might otherwise be harder for the reader to find the discussion of one of the functions (e.g., see dlopen.3), or because some details are specific to just a single function (in which case I am inclined *not* to put a heading for the the funtion that is the first or main subject of the page. I find having a heading for some functions and not others to be confusing, but I do take the point that often the first paragraph is applicable to all the functions described by a page, and that therefore one doesn't want to have a header of just the main function's name, as that implies that the information is not relevant to the other functions. It would be less likely to confuse if pages like utime(2) didn't have the function's name as the first word of a paragraph, so instead of utime()... it started The function utime() This would stop it looking like a mis-formatted heading (which as the bug title shows is what I first thought it was). For what it's worth, I removed the utimes() hading, since it by my stated criteria, it isn't really needed (the page is short). The point about length of page is well made, but I think there are two other considerations: 1. Printed pages can more easily be designed like that. With man pages, it's hard to tell what constitutes short or long, given the vast range of screen sizes, reading software, c. e.g. man on an 80x25 terminal vs web browsing of an HTML-rendered version on a 24 screen (or even a 3 display!). My rough criteria is this: if on a 40 row xterm I can't grok everything in the description after hitting space once, then the page is (more or less) long, and then I'll consider whether it might need some help with structurinng (e.g., add some subheadings). (People on a 3 screen -- well, that's their problem ;-).) 2. man pages are highly structured, to the point that consistency is as important than aesthetics for readability. In particular, deviations are easily noticeable, and will make many readers (like me!) wonder whether something is wrong. Consistency is indeed important, but there is a balance. We perhaps disagree a little on the balance between that and other factors, but I think we fundamentally agree on what's good to aim for. Cheers, Michael PS I added a subheaduing in mmap.2 and am wondering about whether msgop.2, semop.2, shmop.2, and getopt.3 could do with some restructuring and/or headings to make their structure clearer. -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#477402: manpages-dev: Formatting problem in utime(2)
Package: manpages-dev Version: 2.79-2 Severity: minor In the DESCRIPTION section, utimes() has an outdented heading, but utime() does not. By comparison with other similar man pages it seems the most consistent thing would be to remove the heading for utimes(). -- System Information: Debian Release: lenny/sid APT prefers testing APT policy: (700, 'testing'), (601, 'unstable'), (600, 'experimental') Architecture: i386 (i686) Kernel: Linux 2.6.24-1-686 (SMP w/1 CPU core) Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/bash Versions of packages manpages-dev depends on: ii manpages 2.79-2 Manual pages about using a GNU/Lin manpages-dev recommends no packages. -- no debconf information -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
