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]
