Skip to contentSkip to conversation

man-pages : section 9 for kernel api description.

PATCH In review GeunSik Lim 3 participants 4 messages May 13, 2009 – Jul 25, 2009

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 man-pages : section 9 for kernel api description.

Dear Michael Kerrisk,

Are you maintainer of man-pages(man-pages-3.XX.tar.gz)? I am not sure...

I use fedora 9 distribution as Linux based Desktop OS currently. I have one proposal about "#> man <linux-kernel-api>" command. Can you tell me your opinion about below patch?
Thanks reading.

commit 45e950c98412c002c47254507a199731315c7c2b

Author: GeunSik,Lim <[email protected]>
Date:   Wed May 13 10:49:47 2009 +0900

Append Section 9 info of man command.

We view description of the Linux kernel API with man command.
For example,
Fedoar9#> yum install kernel-doc*
Fedora9#> man kobject_rename or
Fedora9#> man kthread_create

The man software will display "Section 9"
like the "KOBJECT_RENAME(9)" info about linux kernel API.

KOBJECT_RENAME(9) Driver Basics KOBJECT_RENAME(9)

If most developers all over the world understand "9" meaning as linux kernel API, Append "Section 9" info
in the "man-pages-3.21.Announce" file of man-pages-3.XX.tar.gz . ( http://www.kernel.org/pub/linux/docs/manpages/man-pages-3.XX.tar.gz )

man-pages-3.22.Announce +1 -0
index b52a38f..61f0f64 100644
@@ -35,6 +35,7 @@ Here is a breakdown of what this distribution contains:
     Section 6 = games (intro only)
     Section 7 = overviews, conventions, macro packages, etc.
     Section 8 = system administration (intro, plus a few other pages)
+    Section 9 = linux kernel API (e.g., kthread_create, kthread_stop)
 
     This package contains no, or very few, section 1, 6, and 8 man pages
     because these should be distributed with the binaries they are written
man9/intro.9 new file +36 -0
new file mode 100644
index 0000000..5440579
@@ -0,0 +1,36 @@
+.\" Copyright (c) 1993 Michael Haardt ([email protected]),
+.\"     Fri Apr  2 11:32:09 MET DST 1993
+.\"
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, write to the Free
+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
+.\" USA.
+.\"
+.\" Modified Sat Jul 24 17:19:57 1993 by Rik Faith ([email protected])
+.\" Modified Wed May 24 10:39:14 2009 by GeunSik Lim ([email protected])
+.TH INTRO 9 2007-10-23 "Linux" "Linux Programmer's Manual"
+.SH NAME
+intro \- Introduction to Linux kernel API
+.SH DESCRIPTION
+Section 9 of the manual describes all the Linux kernel API like kthread_create
+available on the system.
+.SH NOTES
+.SS Authors and Copyright Conditions
+Look at the header of the manual page source for the author(s) and copyright
+conditions.
+Note that these can be different from page to page!

-----------------------------------------------
To unsubscribe from this list: send the line "unsubscribe linux-***" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/

GeunSik Lim (ELS - OS Group - S/W Lab - SAIT - SAMSUNG) e-Mail :1) [email protected]
2) [email protected] , [email protected]
HomePage: http://intomail.dnip.net/invain/me/
-----------------------------------------------

commit 45e950c98412c002c47254507a199731315c7c2b

Author: GeunSik,Lim <[email protected]>
Date:   Wed May 13 10:49:47 2009 +0900

Append Section 9 info of man command

We view description of the Linux kernel API with man command.
For example,
Fedoar9#> yum install kernel-doc*
Fedora9#> man kobject_rename or
Fedora9#> man kthread_create

The man software will display "Section 9"
like the "KOBJECT_RENAME(9)" info about linux kernel API.

KOBJECT_RENAME(9) Driver Basics KOBJECT_RENAME(9)

If most developers all over the world understand "9" meaning as linux kernel API, Append "Section 9" info
in the "man-pages-3.21.Announce" file of man-pages-3.XX.tar.gz . ( http://www.kernel.org/pub/linux/docs/manpages/man-pages-3.XX.tar.gz )

man-pages-3.22.Announce +1 -0
index b52a38f..61f0f64 100644
@@ -35,6 +35,7 @@ Here is a breakdown of what this distribution contains:
     Section 6 = games (intro only)
     Section 7 = overviews, conventions, macro packages, etc.
     Section 8 = system administration (intro, plus a few other pages)
+    Section 9 = linux kernel API (e.g., kthread_create, kthread_stop)
 
     This package contains no, or very few, section 1, 6, and 8 man pages
     because these should be distributed with the binaries they are written
man9/intro.9 new file +36 -0
new file mode 100644
index 0000000..5440579
@@ -0,0 +1,36 @@
+.\" Copyright (c) 1993 Michael Haardt ([email protected]),
+.\"     Fri Apr  2 11:32:09 MET DST 1993
+.\"
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, write to the Free
+.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
+.\" USA.
+.\"
+.\" Modified Sat Jul 24 17:19:57 1993 by Rik Faith ([email protected])
+.\" Modified Wed May 24 10:39:14 2009 by GeunSik Lim ([email protected])
+.TH INTRO 9 2007-10-23 "Linux" "Linux Programmer's Manual"
+.SH NAME
+intro \- Introduction to Linux kernel API
+.SH DESCRIPTION
+Section 9 of the manual describes all the Linux kernel API like kthread_create
+available on the system.
+.SH NOTES
+.SS Authors and Copyright Conditions
+Look at the header of the manual page source for the author(s) and copyright
+conditions.
+Note that these can be different from page to page!
#1 lore raw
Quoted 6 lines · GeunSik Lim

Dear Michael Kerrisk,

Are you maintainer of man-pages(man-pages-3.XX.tar.gz)? I am not sure...

Yes, he is.

Quoted 10 lines

I use fedora 9 distribution as Linux based Desktop OS currently. I have one proposal about "#> man <linux-kernel-api>" command. Can you tell me your opinion about below patch?
Thanks reading.

commit 45e950c98412c002c47254507a199731315c7c2b

Author: GeunSik,Lim <[email protected]>
Date:   Wed May 13 10:49:47 2009 +0900
Quoted 7 lines

Append Section 9 info of man command.

We view description of the Linux kernel API with man command.
For example,
Fedoar9#> yum install kernel-doc*
Fedora9#> man kobject_rename or
Fedora9#> man kthread_create

Why?
Why do you want kernel api doc be in man pages?
Why not just browsing the kernel source code?

Kernel APIs are not stable at all, this is also a reason why you should not include their doc into man pages.

Signature · 1 line
Live like a child, think like the god.
#2 lore raw

Thank you for your opinion.

2009/5/13 Américo Wang <[email protected]>:

Quoted 28 lines · GeunSik Lim
Quoted 6 lines

Dear Michael Kerrisk,

Are you maintainer of man-pages(man-pages-3.XX.tar.gz)? I am not sure...

Yes, he is.

Quoted 10 lines

I use fedora 9 distribution as Linux based Desktop OS currently. I have one proposal about "#> man <linux-kernel-api>" command. Can you tell me your opinion about below patch?
Thanks reading.

commit 45e950c98412c002c47254507a199731315c7c2b
Author: GeunSik,Lim <[email protected]>
Date:   Wed May 13 10:49:47 2009 +0900

Quoted 7 lines

   Append Section 9 info of man command.

   We view description of the Linux kernel API with man command. For example,
      Fedoar9#> yum install kernel-doc*
      Fedora9#> man kobject_rename  or
      Fedora9#> man kthread_create

Quoted 4 lines

Why?
Why do you want kernel api doc be in man pages?
Why not just browsing the kernel source code?

I want Michael to append patch file in the man-pages source that I sent because
Many linux distributions (ex: Fedora , openSUSE, and so on ) already support kernel api for man currently.
In general, kernel api(ex:kernel-doc-2.6.29.1-30.fc10.noarch.rpm) is located in the
/usr/share/man/man9/ directory when we installed linux distribution like Fedora by default.
So, I think that we need description and section 9 folder(man9) in the man-pages source
to understand meaning of man 9.

Quoted 2 lines

Kernel APIs are not stable at all, this is also a reason why you should not include their doc into man pages.

I agree that Kernel APIs is not stable.
But, I believe that we can utilize "#> man <linux-kernel-api>" command in the own
Linux distribution easy to use about "uname -a" Linux kernel version. This support is a valuable. I think that The problem deserves solving.

Thanks reading.

Quoted 5 lines

--
Live like a child, think like the god.

Signature · 7 lines
Regards,
GeunSik Lim
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/
#3 lore raw

Very late follow up here...

Quoted 48 lines · GeunSik Lim

Thank you for your opinion.

2009/5/13 Américo Wang <[email protected]>:

Quoted 28 lines · GeunSik Lim
Quoted 6 lines

Dear Michael Kerrisk,

Are you maintainer of man-pages(man-pages-3.XX.tar.gz)? I am not sure...

Yes, he is.

Quoted 10 lines

I use fedora 9 distribution as Linux based Desktop OS currently. I have one proposal about "#> man <linux-kernel-api>" command. Can you tell me your opinion about below patch?
Thanks reading.

commit 45e950c98412c002c47254507a199731315c7c2b
Author: GeunSik,Lim <[email protected]>
Date:   Wed May 13 10:49:47 2009 +0900

Quoted 7 lines

   Append Section 9 info of man command.

   We view description of the Linux kernel API with man command. For example,
      Fedoar9#> yum install kernel-doc*
      Fedora9#> man kobject_rename  or
      Fedora9#> man kthread_create

Quoted 4 lines

Why?
Why do you want kernel api doc be in man pages?
Why not just browsing the kernel source code?

I want Michael to append patch file  in the man-pages source that I sent because
Many linux distributions (ex: Fedora , openSUSE, and so on ) already support  kernel api for man currently.
In general, kernel api(ex:kernel-doc-2.6.29.1-30.fc10.noarch.rpm) is located in the
/usr/share/man/man9/ directory when we installed linux distribution like Fedora by default.
So, I think that we need description and section 9 folder(man9) in the man-pages source
to understand  meaning of man 9.

Quoted 7 lines
Quoted 2 lines

Kernel APIs are not stable at all, this is also a reason why you should not include their doc into man pages.

I agree that Kernel APIs is not stable.
But, I believe that we can utilize "#> man <linux-kernel-api>" command in the own
Linux distribution easy to use about "uname -a" Linux kernel version. This support is a valuable. I think that The problem deserves solving.

I agree that there's a problem that needs solving here, but I don't think it's one that can be solved by man-0pages, whose mission is to document the kerenl-userpsace and libc APIs. (This doesn't mean that kernel APIs couldn't be documented in man pages, but it would be a different project.)

Cheers,

Michael

Signature · 4 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Watch my Linux system programming book progress to publication!
http://blog.man7.org/