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]
