man-pages-2.61 is released

man-pages-2.61 is released

[Michael Kerrisk]

Gidday,

I recently released man-pages-2.61.

This release is now available for download at:

    http://www.kernel.org/pub/linux/docs/manpages
    or ftp://ftp.kernel.org/pub/linux/docs/manpages

and soon at:

    ftp://ftp.win.tue.nl/pub/linux-local/manpages

A few of the changes that may of interest to readers of this list are
supplied below.

Cheers,

Michael
(man-pages maintenance is supported by Google, as a Google engineer 20%
project.)

==================== Changes in man-pages-2.61 ====================

Changes to individual pages
---------------------------

intro.2
    mtk
       Rewrite to reflect the fact that the _syscallN
       macros are no longer available.

select.2
    mtk
        Noted that 'timeout' can also be changed if select() is
        interrupted by a signal.

swapon.2
    Ivana Varekova  / mtk
        Update text for EPERM error describing the maximum number of
        swap files.  (From downstream Fedora patch.)

write.2
    mtk
        Added details about seekable files and file offset.
        Noted that write() may write less than 'count' bytes, and
        gave some examples of why this might occur.
        Noted what happens if write() is interrupted by a signal.

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7

Want to help with man page maintenance?  Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages/
read the HOWTOHELP file and grep the source files for 'FIXME'.

Re: man-pages-2.61 is released

[Jan Engelhardt]

On Jul 7 2007 18:26, Michael Kerrisk wrote:
>
>I recently released man-pages-2.61.

utimensat() was introduced in Linux 2.6.22-rc1.
I am kindly hinting that it does not yet have a manpage yet :)


	Jan
-- 

Re: man-pages-2.61 is released

[Michael Kerrisk]

> On Jul 7 2007 18:26, Michael Kerrisk wrote:
> >
> >I recently released man-pages-2.61.
> 
> utimensat() was introduced in Linux 2.6.22-rc1.

Yes, I am aware.

> I am kindly hinting that it does not yet have a manpage yet :)

Such a hint is a good idea.  But strangely, you send it to me,
rather than the author of the system call.  Why is that?

Rhetorically,

Michael
-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  
Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages , 
read the HOWTOHELP file and grep the source 
files for 'FIXME'.

Re: utimensat (man-pages-2.61 is released)

[Jan Engelhardt]

On Jul 8 2007 09:30, Michael Kerrisk wrote:
>> On Jul 7 2007 18:26, Michael Kerrisk wrote:
>> >
>> >I recently released man-pages-2.61.
>> 
>> utimensat() was introduced in Linux 2.6.22-rc1.
>
>Yes, I am aware.
>
>> I am kindly hinting that it does not yet have a manpage yet :)
>
>Such a hint is a good idea.  But strangely, you send it to me,
>rather than the author of the system call.  Why is that?

Related manpages (futimesat(2)) does not list an author.
So I were to guess who wrote it: you, or Ulrich, or a contributor.


	Jan
-- 

Re: utimensat (man-pages-2.61 is released)

[Michael Kerrisk]

> On Jul 8 2007 09:30, Michael Kerrisk wrote:
> >> On Jul 7 2007 18:26, Michael Kerrisk wrote:
> >> >
> >> >I recently released man-pages-2.61.
> >> 
> >> utimensat() was introduced in Linux 2.6.22-rc1.
> >
> >Yes, I am aware.
> >
> >> I am kindly hinting that it does not yet have a manpage yet :)
> >
> >Such a hint is a good idea.  But strangely, you send it to me,
> >rather than the author of the system call.  Why is that?
> 
> Related manpages (futimesat(2)) does not list an author.
> So I were to guess who wrote it: you, or Ulrich, or a contributor.

An author of which -- the man page itself, or the system call?
Looking at the source of almost any page in man-pages certainly
shows the author of the page.  In the case of the futimesat(2)
man page: yes, I was the author.

So yes, I sometimes write pages for system calls that were 
written by others.  But this suffers serious limitations:

* Many people are changing the kernel-userland API; leaving me
  to write the documentation does not scale well.  (To begin
  with there is the problem: how can I even tell what has
  changed in a new release?  But here I must thank Andrew,
  who helps a bit by forwarding me things he notices.)

* I am fallible: I sometimes make mistakes of understanding
  when interpreting other people's code.

* Even when I do not make mistakes, when I write a man page by
  reading someone else's code, all I am doing is interpreting.
  The implementation may not match the (code) author's
  intention (aka a bug).  I may just be accurately documented
  buggy behaviour, or accurately describing design mistakes.
  (Yes, sometimes I'm smart enough to recognize the bugs and
  call them, but that is far from guaranteed.)

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  
Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages , 
read the HOWTOHELP file and grep the source 
files for 'FIXME'.