Debian Bug report logs - #477402
manpages-dev: Formatting problem in utime(2)

version graph

Package: manpages-dev; Maintainer for manpages-dev is Martin Schulze <joey@debian.org>; Source for manpages-dev is src:manpages.

Reported by: Reuben Thomas <rrt@sc3d.org>

Date: Tue, 22 Apr 2008 23:06:31 UTC

Severity: minor

Tags: upstream

Found in version manpages/2.79-2

Fixed in version manpages/2.80-1

Done: Joey Schulze <joey@infodrom.org>

Bug is archived. No further changes may be made.

Forwarded to Michael Kerrisk <mtk.manpages@googlemail.com>

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Reuben Thomas <rrt@sc3d.org>:
New Bug report received and forwarded. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: Reuben Thomas <rrt@sc3d.org>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: manpages-dev: Formatting problem in utime(2)
Date: Wed, 23 Apr 2008 00:04:30 +0100
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




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk.manpages@googlemail.com>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #10 received at submit@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk" <mtk.manpages@googlemail.com>
To: "Reuben Thomas" <rrt@sc3d.org>, 477402@bugs.debian.org
Cc: "Debian Bug Tracking System" <submit@bugs.debian.org>
Subject: Re: Bug#477402: manpages-dev: Formatting problem in utime(2)
Date: Wed, 23 Apr 2008 16:43:44 +0200
Hi Reuben,

On Wed, Apr 23, 2008 at 1:04 AM, Reuben Thomas <rrt@sc3d.org> 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




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk.manpages@googlemail.com>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Reuben Thomas <rrt@sc3d.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #20 received at submit@bugs.debian.org (full text, mbox):

From: Reuben Thomas <rrt@sc3d.org>
To: Michael Kerrisk <mtk.manpages@googlemail.com>
Cc: 477402@bugs.debian.org, Debian Bug Tracking System <submit@bugs.debian.org>
Subject: Re: Bug#477402: manpages-dev: Formatting problem in utime(2)
Date: Wed, 23 Apr 2008 15:49:40 +0100 (BST)
On Wed, 23 Apr 2008, Michael Kerrisk wrote:

> Hi Reuben,
>
> On Wed, Apr 23, 2008 at 1:04 AM, Reuben Thomas <rrt@sc3d.org> 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)




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Reuben Thomas <rrt@sc3d.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk.manpages@googlemail.com>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #30 received at submit@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk" <mtk.manpages@googlemail.com>
To: "Reuben Thomas" <rrt@sc3d.org>
Cc: 477402@bugs.debian.org, "Debian Bug Tracking System" <submit@bugs.debian.org>
Subject: Re: Bug#477402: manpages-dev: Formatting problem in utime(2)
Date: Wed, 23 Apr 2008 16:58:53 +0200
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




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk.manpages@googlemail.com>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Reuben Thomas <rrt@sc3d.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #40 received at submit@bugs.debian.org (full text, mbox):

From: Reuben Thomas <rrt@sc3d.org>
To: Michael Kerrisk <mtk.manpages@googlemail.com>
Cc: 477402@bugs.debian.org, Debian Bug Tracking System <submit@bugs.debian.org>
Subject: Re: Bug#477402: manpages-dev: Formatting problem in utime(2)
Date: Wed, 23 Apr 2008 16:18:27 +0100 (BST)
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)




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Reuben Thomas <rrt@sc3d.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk.manpages@googlemail.com>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #50 received at submit@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk" <mtk.manpages@googlemail.com>
To: "Reuben Thomas" <rrt@sc3d.org>
Cc: 477402@bugs.debian.org, "Debian Bug Tracking System" <submit@bugs.debian.org>
Subject: Re: Bug#477402: manpages-dev: Formatting problem in utime(2)
Date: Wed, 23 Apr 2008 20:05:27 +0200
On Wed, Apr 23, 2008 at 5:18 PM, Reuben Thomas <rrt@sc3d.org> 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




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk.manpages@googlemail.com>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Reuben Thomas <rrt@sc3d.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #60 received at submit@bugs.debian.org (full text, mbox):

From: Reuben Thomas <rrt@sc3d.org>
To: Michael Kerrisk <mtk.manpages@googlemail.com>
Cc: 477402@bugs.debian.org, Debian Bug Tracking System <submit@bugs.debian.org>
Subject: Re: Bug#477402: manpages-dev: Formatting problem in utime(2)
Date: Fri, 25 Apr 2008 11:38:48 +0100 (BST)
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




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Reuben Thomas <rrt@sc3d.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk.manpages@googlemail.com>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #70 received at submit@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk" <mtk.manpages@googlemail.com>
To: "Reuben Thomas" <rrt@sc3d.org>
Cc: 477402@bugs.debian.org, "Debian Bug Tracking System" <submit@bugs.debian.org>
Subject: Re: Bug#477402: manpages-dev: Formatting problem in utime(2)
Date: Fri, 25 Apr 2008 12:56:53 +0200
On Fri, Apr 25, 2008 at 12:38 PM, Reuben Thomas <rrt@sc3d.org> 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




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk.manpages@googlemail.com>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Reuben Thomas <rrt@sc3d.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #80 received at submit@bugs.debian.org (full text, mbox):

From: Reuben Thomas <rrt@sc3d.org>
To: Michael Kerrisk <mtk.manpages@googlemail.com>
Cc: 477402@bugs.debian.org, Debian Bug Tracking System <submit@bugs.debian.org>
Subject: Re: Bug#477402: manpages-dev: Formatting problem in utime(2)
Date: Fri, 25 Apr 2008 12:23:22 +0100 (BST)
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




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Reuben Thomas <rrt@sc3d.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk.manpages@googlemail.com>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #90 received at submit@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk" <mtk.manpages@googlemail.com>
To: "Reuben Thomas" <rrt@sc3d.org>
Cc: 477402@bugs.debian.org, "Debian Bug Tracking System" <submit@bugs.debian.org>
Subject: Re: Bug#477402: manpages-dev: Formatting problem in utime(2)
Date: Fri, 25 Apr 2008 13:46:01 +0200
On Fri, Apr 25, 2008 at 1:23 PM, Reuben Thomas <rrt@sc3d.org> 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




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk.manpages@googlemail.com>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Reuben Thomas <rrt@sc3d.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #100 received at submit@bugs.debian.org (full text, mbox):

From: Reuben Thomas <rrt@sc3d.org>
To: Michael Kerrisk <mtk.manpages@googlemail.com>
Cc: 477402@bugs.debian.org, Debian Bug Tracking System <submit@bugs.debian.org>
Subject: Re: Bug#477402: manpages-dev: Formatting problem in utime(2)
Date: Fri, 25 Apr 2008 12:51:41 +0100 (BST)
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)




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#477402; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Reuben Thomas <rrt@sc3d.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Tags added: upstream Request was from Martin Schulze <joey@infodrom.org> to control@bugs.debian.org. (Fri, 25 Apr 2008 14:18:12 GMT) Full text and rfc822 format available.

Noted your statement that Bug has been forwarded to Michael Kerrisk <mtk.manpages@googlemail.com>. Request was from Martin Schulze <joey@infodrom.org> to control@bugs.debian.org. (Fri, 25 Apr 2008 14:18:14 GMT) Full text and rfc822 format available.

Reply sent to Joey Schulze <joey@infodrom.org>:
You have taken responsibility. Full text and rfc822 format available.

Notification sent to Reuben Thomas <rrt@sc3d.org>:
Bug acknowledged by developer. Full text and rfc822 format available.

Message #114 received at 477402-close@bugs.debian.org (full text, mbox):

From: Joey Schulze <joey@infodrom.org>
To: 477402-close@bugs.debian.org
Subject: Bug#477402: fixed in manpages 2.80-1
Date: Sat, 07 Jun 2008 21:02:37 +0000
Source: manpages
Source-Version: 2.80-1

We believe that the bug you reported is fixed in the latest version of
manpages, which is due to be installed in the Debian FTP archive:

manpages-dev_2.80-1_all.deb
  to pool/main/m/manpages/manpages-dev_2.80-1_all.deb
manpages_2.80-1.diff.gz
  to pool/main/m/manpages/manpages_2.80-1.diff.gz
manpages_2.80-1.dsc
  to pool/main/m/manpages/manpages_2.80-1.dsc
manpages_2.80-1_all.deb
  to pool/main/m/manpages/manpages_2.80-1_all.deb
manpages_2.80.orig.tar.gz
  to pool/main/m/manpages/manpages_2.80.orig.tar.gz



A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 477402@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Joey Schulze <joey@infodrom.org> (supplier of updated manpages package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Format: 1.8
Date: Sat, 07 Jun 2008 22:42:06 +0200
Source: manpages
Binary: manpages manpages-dev
Architecture: source all
Version: 2.80-1
Distribution: unstable
Urgency: low
Maintainer: Martin Schulze <joey@debian.org>
Changed-By: Joey Schulze <joey@infodrom.org>
Description: 
 manpages   - Manual pages about using a GNU/Linux system
 manpages-dev - Manual pages about using GNU/Linux for development
Closes: 421482 467552 476484 476672 477402 479284
Changes: 
 manpages (2.80-1) unstable; urgency=low
 .
   * New upstream version
     . Add getgrouplist(3) to SEE ALSO of getgrent(2) (closes: Bug#479284)
     . Document EEXISTS for rmdir(2) (closes: Bug#467552)
     . Update to sync_file_range(2) (closes: Bug#421482)
     . Remove unnecessary subheading in utime(2) (closes: Bug#477402)
     . Fix declaration of valuep in getsubopt(3) (closes: Bug#476672)
     . Clarify semantics when called from a multithreaded program in
       raise(3) (closes: Bug#476484)
Checksums-Sha1: 
 c7ceec36090e7472f22d2bc9c34933cb75d38252 964 manpages_2.80-1.dsc
 4c87677b117244b0bf346d29fb386f445343d179 1317640 manpages_2.80.orig.tar.gz
 42bf361cca01cf7f5d929cbae0004502c4006e92 51304 manpages_2.80-1.diff.gz
 fe0c0cd9be2a77a9bedbeab29e1d5d08f2a31399 553902 manpages_2.80-1_all.deb
 d6cff52f9c47456598134c7cd584dd6978ebc7d4 1393904 manpages-dev_2.80-1_all.deb
Checksums-Sha256: 
 7cc2effe80c537c7d016c0a75250aa546761a9d1076a2cb4c3baa123602c858b 964 manpages_2.80-1.dsc
 887d9faa3e8bfb79336264c36fe8b65eb852e7b13043cbd66c17ba9ecac8ab55 1317640 manpages_2.80.orig.tar.gz
 e889887d4feee01e56997084849c22101fc791deca24d709586dd94df883b062 51304 manpages_2.80-1.diff.gz
 ef575a3deda4823f50c76edee8da050ada837f74adaf4030eaeb41476f836fd8 553902 manpages_2.80-1_all.deb
 ae04cb913484f94f842d6fb7d9024099b9f9203c4b84bf3f99abf24eb56bba2b 1393904 manpages-dev_2.80-1_all.deb
Files: 
 aa1d101adbc82d6c70070c66ef7a2901 964 doc important manpages_2.80-1.dsc
 1ffb19f639fc105c41fe24ec2308293f 1317640 doc important manpages_2.80.orig.tar.gz
 14718d9a35ecfa70089856e675fbb118 51304 doc important manpages_2.80-1.diff.gz
 fb663a344da9a61ea881d88ef16287a4 553902 doc important manpages_2.80-1_all.deb
 5f8a8ec191f8001a794f587739e8a96e 1393904 doc optional manpages-dev_2.80-1_all.deb

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)

iD8DBQFISvNSW5ql+IAeqTIRAvXKAJ99mlb0ddU6OXn/H+Uy0nuBdPSiPACgskqv
M5aSonBZ6WRvLmJli1hC59k=
=hF0v
-----END PGP SIGNATURE-----





Bug archived. Request was from Debbugs Internal Request <owner@bugs.debian.org> to internal_control@bugs.debian.org. (Thu, 17 Jul 2008 07:25:58 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Mon Apr 21 07:05:31 2014; Machine Name: beach.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.