[RFC] devpts man page update

[RFC] devpts man page update

[Sukadev Bhattiprolu]

Michael,

Following is some text that would need to be added to devpts section of
mount(8) man page (its not a formal patch, just the text to be added).
I am looking for logistics and a general review of the text to be added.

The relevant kernel patches are currently in ttydev/linux-next trees.
I can send the formal man page patch after those patches go into mainline.

Also, is it ok to refer to 'Documentation' directory in the man page  -
there are several semantics outlined in Documentation/filesystem/devpts.txt
(http://www.linux.org.uk/~alan/ttydev/pty-multiple-doc), that may be of
use only to users of containers.

Thanks,

Suka

---
--- devpts.manpage.orig	2008-11-26 10:04:11.000000000 -0800
+++ devpts.manpage	2008-11-26 10:02:15.000000000 -0800
@@ -1,3 +1,4 @@
+
 Mount options for devpts
 	The  devpts  file system is a pseudo file system, traditionally mounted
 	on /dev/pts.  In order to acquire a pseudo terminal,  a  process  opens
@@ -17,3 +18,48 @@
 		default is 0600.  A value of mode=620 and gid=5 makes  "mesg  y"
 		the default on newly created PTYs.
 
+	newinstance
+
+		Create a private instance of devpts filesystem, such that
+		indices of ptys allocated in this new instance of the
+		filesystem are independent of indices created in other
+		instances of devpts.
+
+		If this option is not specified for a mount of devpts, 
+		("legacy mode"), that instance of devpts shares the pty
+		indices with the initial/default mount of devpts. i.e.
+		all mounts of devpts without this 'newinstance' option
+		share the same set of pty indices. Each mount of devpts
+		with newinstance option has a private set of pty indices.
+
+		This option is mainly used to support containers in the
+		linux kernel. It is implemented in linux kernel versions
+		starting with 2.6.XX.  Further, this mount option is valid
+		only if CONFIG_DEVPTS_MULTIPLE_INSTANCES is enabled in the
+		kernel configuration.
+
+		To use this option effectively, '/dev/ptmx' must be a
+		symlink to 'pts/ptmx'. See Documentation/filesystems/
+		devpts.txt for details.
+
+	ptmxmode=value
+ 
+		Set the mode for the new 'ptmx' device node in the devpts
+		filesystem. Default mode is 0000 for compatibility with
+		legacy mode of devpts.
+
+		This option is only implemented in linux kernel versions
+		starting with 2.6.XX. Further this option is valid only if 
+		CONFIG_DEVPTS_MULTIPLE_INSTANCES is enabled in the kernel
+		configuration.
+
+		With support for multiple instances of devpts (see
+		'newinstance' option above), each instance has a private
+		'ptmx' node in the root of the devpts filesystem (typically
+		'/dev/pts/ptmx').
+
+		For compatibility with older versions of the kernel, the
+		default mode ot the new 'ptmx' node is 0000. 'ptmxmode'
+		option specifies a more useful mode for the 'ptmx' node
+		and is highly recommended when the 'newinstance' option
+		is specified.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[Michael Kerrisk]

Suka,

On Wed, Nov 26, 2008 at 1:17 PM, Sukadev Bhattiprolu
<sukadev-23VcF4HTsmIX0ybBhKVfKdBPR1lH4CV8@public.gmane.org> wrote:
> Michael,
>
> Following is some text that would need to be added to devpts section of
> mount(8) man page (its not a formal patch, just the text to be added).
> I am looking for logistics and a general review of the text to be added.

The mount(8) page is not part of the man-pages set.  Take a look here:
http://www.kernel.org/doc/man-pages/man_pages_other.html

> The relevant kernel patches are currently in ttydev/linux-next trees.
> I can send the formal man page patch after those patches go into mainline.

Though mount(8) is not on my set, I wonder if there is any text that
should perhaps be added to pts(4) or pty(7).

http://www.kernel.org/doc/man-pages/online/pages/man4/pts.4.html
http://www.kernel.org/doc/man-pages/online/pages/man7/pty.7.html

Take a look at those and let me know.

> Also, is it ok to refer to 'Documentation' directory in the man page  -
> there are several semantics outlined in Documentation/filesystem/devpts.txt
> (http://www.linux.org.uk/~alan/ttydev/pty-multiple-doc), that may be of
> use only to users of containers.

Certainly as far as I'm concerned doing this is okay in the pages in
man-pages -- you just need to say "the kernel source file
Documentation/..."

Cheers,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[H. Peter Anvin]

Michael Kerrisk wrote:
> 
> The mount(8) page is not part of the man-pages set.  Take a look here:
> http://www.kernel.org/doc/man-pages/man_pages_other.html
> 

Filesystem-specific options should never have been part of mount(8) 
IMNSHO.  Rather, they should be documented in the respective (4) pages 
with pointers from mount(8)...

	-hpa

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[Sukadev Bhattiprolu]

Michael Kerrisk [mtk.manpages-gM/Ye1E23mwN+BqQ9rBEUg@public.gmane.org] wrote:
| Suka,
| 
| On Wed, Nov 26, 2008 at 1:17 PM, Sukadev Bhattiprolu
| <sukadev-23VcF4HTsmIX0ybBhKVfKdBPR1lH4CV8@public.gmane.org> wrote:
| > Michael,
| >
| > Following is some text that would need to be added to devpts section of
| > mount(8) man page (its not a formal patch, just the text to be added).
| > I am looking for logistics and a general review of the text to be added.
| 
| The mount(8) page is not part of the man-pages set.  Take a look here:
| http://www.kernel.org/doc/man-pages/man_pages_other.html

Aah, so maybe different patches for different distros. I will try to
send them out at least to Redhat/Suse/Ubuntu. But cannot help asking
(curiousity/ignorance :-), why are there separate 'trees' for different
man pages even for features included in kernel ?

| 
| > The relevant kernel patches are currently in ttydev/linux-next trees.
| > I can send the formal man page patch after those patches go into mainline.
| 
| Though mount(8) is not on my set, I wonder if there is any text that
| should perhaps be added to pts(4) or pty(7).
| 
| http://www.kernel.org/doc/man-pages/online/pages/man4/pts.4.html
| http://www.kernel.org/doc/man-pages/online/pages/man7/pty.7.html

I think no updates are needed for pty(7).  I was thinking of adding a
pointer in pts(4) to mount(8), but do the sets of man pages also have
separate release-cycles ? If so, should I stage the patches such that
kernel patches go in first, mount(8) updates next and pts(4) updates
last ?

| 
| Take a look at those and let me know.
| 
| > Also, is it ok to refer to 'Documentation' directory in the man page  -
| > there are several semantics outlined in Documentation/filesystem/devpts.txt
| > (http://www.linux.org.uk/~alan/ttydev/pty-multiple-doc), that may be of
| > use only to users of containers.
| 
| Certainly as far as I'm concerned doing this is okay in the pages in
| man-pages -- you just need to say "the kernel source file
| Documentation/..."

Ok.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[Michael Kerrisk]

Suka,

On Mon, Dec 1, 2008 at 1:10 PM, Sukadev Bhattiprolu
<sukadev-23VcF4HTsmIX0ybBhKVfKdBPR1lH4CV8@public.gmane.org> wrote:
> Michael Kerrisk [mtk.manpages-gM/Ye1E23mwN+BqQ9rBEUg@public.gmane.org] wrote:
> | Suka,
> |
> | On Wed, Nov 26, 2008 at 1:17 PM, Sukadev Bhattiprolu
> | <sukadev-23VcF4HTsmIX0ybBhKVfKdBPR1lH4CV8@public.gmane.org> wrote:
> | > Michael,
> | >
> | > Following is some text that would need to be added to devpts section of
> | > mount(8) man page (its not a formal patch, just the text to be added).
> | > I am looking for logistics and a general review of the text to be added.
> |
> | The mount(8) page is not part of the man-pages set.  Take a look here:
> | http://www.kernel.org/doc/man-pages/man_pages_other.html
>
> Aah, so maybe different patches for different distros.

No, no...  The point is that mount(8) is part of a different project:
util-linux(-ng).  Your patches potentially need to go to the
maintainer of *that* project.

> I will try to
> send them out at least to Redhat/Suse/Ubuntu. But cannot help asking
> (curiousity/ignorance :-), why are there separate 'trees' for different
> man pages even for features included in kernel ?

The fact that the util-linux(-ng) maintainer includes some kernel
details in the mount(8) man page is not something that I control.  It
may or may not be a good idea.

> | > The relevant kernel patches are currently in ttydev/linux-next trees.
> | > I can send the formal man page patch after those patches go into mainline.
> |
> | Though mount(8) is not on my set, I wonder if there is any text that
> | should perhaps be added to pts(4) or pty(7).
> |
> | http://www.kernel.org/doc/man-pages/online/pages/man4/pts.4.html
> | http://www.kernel.org/doc/man-pages/online/pages/man7/pty.7.html
>
> I think no updates are needed for pty(7).  I was thinking of adding a
> pointer in pts(4) to mount(8), but do the sets of man pages also have
> separate release-cycles ?

Most certainly.  The point is: all Linux man pages do *not* come from
the same source.  The package I maintain consists mainly of pages in
Sections 2, 3, 4, 5, and 7.

> If so, should I stage the patches such that
> kernel patches go in first, mount(8) updates next and pts(4) updates
> last ?

Well, You'd need to talk with the util-linux-ng people, but I think in
the end the order doesn't matter too much.  It's typically only a few
months later that man-pages will end in a distro release anyway..

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[H. Peter Anvin]

Add Cc: util-linux-ng

Michael Kerrisk wrote:
> 
> The fact that the util-linux(-ng) maintainer includes some kernel
> details in the mount(8) man page is not something that I control.  It
> may or may not be a good idea.
> 

IMNSHO, it's distincly not a good idea.  For one thing, the mount(8) man
page is a mess.  Any options that aren't generic across filesystems
should be moved out of mount(8) into the filesystem man pages in section 4.

The fact that the options are in the mount(8) man page is largely a
historical artifact dating back to the early 1990's when Linux only had
a handful of filesystems.

The way to do that pretty much ends up with:

1. Agree that this is the way to do it.
2. Add the options to section 4.
3. Clean up mount(8).

... in that order.

	-hpa
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[Michael Kerrisk]

On Mon, Dec 1, 2008 at 2:42 PM, H. Peter Anvin <hpa-YMNOUZJC4hwAvxtiuMwx3w@public.gmane.org> wrote:
> Add Cc: util-linux-ng
>
> Michael Kerrisk wrote:
>>
>> The fact that the util-linux(-ng) maintainer includes some kernel
>> details in the mount(8) man page is not something that I control.  It
>> may or may not be a good idea.
>>
>
> IMNSHO, it's distincly not a good idea.  For one thing, the mount(8) man
> page is a mess.  Any options that aren't generic across filesystems
> should be moved out of mount(8) into the filesystem man pages in section 4.
>
> The fact that the options are in the mount(8) man page is largely a
> historical artifact dating back to the early 1990's when Linux only had
> a handful of filesystems.
>
> The way to do that pretty much ends up with:
>
> 1. Agree that this is the way to do it.
> 2. Add the options to section 4.
> 3. Clean up mount(8).
>
> ... in that order.

If there's consensus (including from the mount(8) man page
maintainer), I have no objection to this, and I can see some sense in
it.  The mount options are, after all, kernel interfaces.  Perhaps
this whole situation arose because once upon a time, the maintainer of
the mount(8) page and the maintainer of man-pages were the same
person, Andries, and perhaps he too has an opinion.  (Andries, here's
a pointer to the thread so far:
http://article.gmane.org/gmane.linux.man/557/ )

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[Andries E. Brouwer]

On Mon, Dec 01, 2008 at 03:05:47PM -0500, Michael Kerrisk wrote:
> On Mon, Dec 1, 2008 at 2:42 PM, H. Peter Anvin <hpa-YMNOUZJC4hwAvxtiuMwx3w@public.gmane.org> wrote:
> > Add Cc: util-linux-ng
> >
> > Michael Kerrisk wrote:
> >>
> >> The fact that the util-linux(-ng) maintainer includes some kernel
> >> details in the mount(8) man page is not something that I control.
> >> It may or may not be a good idea.
> >>
> >
> > IMNSHO, it's distincly not a good idea.  For one thing, the mount(8) man
> > page is a mess.  Any options that aren't generic across filesystems
> > should be moved out of mount(8) into the filesystem man pages in section 4.
> >
> > The fact that the options are in the mount(8) man page is largely a
> > historical artifact dating back to the early 1990's when Linux only had
> > a handful of filesystems.
> >
> > The way to do that pretty much ends up with:
> >
> > 1. Agree that this is the way to do it.
> > 2. Add the options to section 4.
> > 3. Clean up mount(8).
> >
> > ... in that order.
> 
> If there's consensus (including from the mount(8) man page
> maintainer), I have no objection to this, and I can see some sense in
> it.  The mount options are, after all, kernel interfaces.  Perhaps
> this whole situation arose because once upon a time, the maintainer of
> the mount(8) page and the maintainer of man-pages were the same
> person, Andries, and perhaps he too has an opinion.  (Andries, here's
> a pointer to the thread so far:
> http://article.gmane.org/gmane.linux.man/557/ )

Hi Michael,

At some point in time I cleaned up the messy and incomplete mount docs
and wrote the nicely structured and complete mount(8). Of course as
time passes completeness can be lost, and the page can become unwieldy
because of excessive length. The page I am looking at has roughly 1500
lines, of which roughly 1000 are about filesystem-specific mount options.
Maybe a bit long, but since this length is caused by a list that is
alphabetically sorted and has entries that tend to be only a few dozen
lines long, I do not mind this length so much.

Perhaps Peter complains about something else when he sees a mess?

The goal of a man page author must be convenience of the user.
The information must be clear, precise, concise, easy to find.

I don't know how modern distributions usually present these man pages.
Myself, I read them in the old-fashioned way on an xterm, where no
hyperlinks are available. In such a setting a single page is clearly
more convenient, but there will come a point where it is simply too long.

These filesystem man pages in section 4 do not exist yet, as far as I can see.
What would the names be? Would splitting things up make it easier for the
user to find her info?

Andries

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[H. Peter Anvin]

Andries E. Brouwer wrote:
> 
> Hi Michael,
> 
> At some point in time I cleaned up the messy and incomplete mount docs
> and wrote the nicely structured and complete mount(8). Of course as
> time passes completeness can be lost, and the page can become unwieldy
> because of excessive length. The page I am looking at has roughly 1500
> lines, of which roughly 1000 are about filesystem-specific mount options.
> Maybe a bit long, but since this length is caused by a list that is
> alphabetically sorted and has entries that tend to be only a few dozen
> lines long, I do not mind this length so much.
> 
> Perhaps Peter complains about something else when he sees a mess?
> 

No, but I really don't think it's appropriate to just tag on and on to a
single man page.  I know that I find it incredibly painful to wade
through the long list of options, most of which don't apply to me.

Lists within lists don't visually scan well.

> The goal of a man page author must be convenience of the user.
> The information must be clear, precise, concise, easy to find.
> 
> I don't know how modern distributions usually present these man pages.
> Myself, I read them in the old-fashioned way on an xterm, where no
> hyperlinks are available. In such a setting a single page is clearly
> more convenient, but there will come a point where it is simply too long.
> 
> These filesystem man pages in section 4 do not exist yet, as far as I can see.
> What would the names be? Would splitting things up make it easier for the
> user to find her info?

Some auxilliary filesystems already have section 4, I believe.  The
other option, of course, is to move that data to mount.<filesystem>(8).

	-hpa
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[Karel Zak]

On Mon, Dec 01, 2008 at 11:42:42AM -0800, H. Peter Anvin wrote:
> Add Cc: util-linux-ng
> 
> Michael Kerrisk wrote:
> > 
> > The fact that the util-linux(-ng) maintainer includes some kernel
> > details in the mount(8) man page is not something that I control.  It
> > may or may not be a good idea.

 Send a patch or bug report, that's the way how you can "control" :-)

> IMNSHO, it's distincly not a good idea.  For one thing, the mount(8) man
> page is a mess.  Any options that aren't generic across filesystems
> should be moved out of mount(8) into the filesystem man pages in section 4.

 We're already talking about it at linux-fsdevel and util-linux-ng
 mailing list:

    http://marc.info/?l=linux-fsdevel&m=122767297002093&w=3

> The fact that the options are in the mount(8) man page is largely a
> historical artifact dating back to the early 1990's when Linux only had
> a handful of filesystems.

 Yes, I haven't time to cleanup util-linux-ng docs (yet). The idea to
 create man page (in section 4) for every filesystem is my wish. So..
 I look forward to see some patches in this area.

> 1. Agree that this is the way to do it.
> 2. Add the options to section 4.
> 3. Clean up mount(8).

  4. found a way how maintain and keep the man pages up to date.

    Karel

-- 
 Karel Zak  <kzak-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[H. Peter Anvin]

Karel Zak wrote:
> 
>> 1. Agree that this is the way to do it.
>> 2. Add the options to section 4.
>> 3. Clean up mount(8).
> 
>   4. found a way how maintain and keep the man pages up to date.
> 

As far as 4. is concerned -- I personally think that keeping man pages
that directly describe kernel interfaces (e.g. section 2, and parts of
4, 5, and 7) in the kernel git tree is the most logical option.

	-hpa
--
To unsubscribe from this list: send the line "unsubscribe util-linux-ng" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[Karel Zak]

On Mon, Dec 01, 2008 at 02:41:51PM -0800, H. Peter Anvin wrote:
> Karel Zak wrote:
> > 
> >> 1. Agree that this is the way to do it.
> >> 2. Add the options to section 4.
> >> 3. Clean up mount(8).
> > 
> >   4. found a way how maintain and keep the man pages up to date.
> > 
> 
> As far as 4. is concerned -- I personally think that keeping man pages
> that directly describe kernel interfaces (e.g. section 2, and parts of
> 4, 5, and 7) in the kernel git tree is the most logical option.

 That's exactly my opinion ... somewhere in Documentation/ and
 maintained *together* with fs-depend code.

    Karel


-- 
 Karel Zak  <kzak-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[H. Peter Anvin]

Karel Zak wrote:
> On Mon, Dec 01, 2008 at 02:41:51PM -0800, H. Peter Anvin wrote:
>> Karel Zak wrote:
>>>> 1. Agree that this is the way to do it.
>>>> 2. Add the options to section 4.
>>>> 3. Clean up mount(8).
>>>   4. found a way how maintain and keep the man pages up to date.
>>>
>> As far as 4. is concerned -- I personally think that keeping man pages
>> that directly describe kernel interfaces (e.g. section 2, and parts of
>> 4, 5, and 7) in the kernel git tree is the most logical option.
> 
>  That's exactly my opinion ... somewhere in Documentation/ and
>  maintained *together* with fs-depend code.
> 

Acked-by: H. Peter Anvin <hpa-YMNOUZJC4hwAvxtiuMwx3w@public.gmane.org> ;)

	-hpa
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] devpts man page update

[H. Peter Anvin]

Karel Zak wrote:
> On Mon, Dec 01, 2008 at 02:41:51PM -0800, H. Peter Anvin wrote:
>> Karel Zak wrote:
>>>> 1. Agree that this is the way to do it.
>>>> 2. Add the options to section 4.
>>>> 3. Clean up mount(8).
>>>   4. found a way how maintain and keep the man pages up to date.
>>>
>> As far as 4. is concerned -- I personally think that keeping man pages
>> that directly describe kernel interfaces (e.g. section 2, and parts of
>> 4, 5, and 7) in the kernel git tree is the most logical option.
> 
>  That's exactly my opinion ... somewhere in Documentation/ and
>  maintained *together* with fs-depend code.
> 

By the way, lest someone gets the wrong idea... I think mtk has done a
fantastic job with the man pages recently, and I certainly don't want to
replace him.  I think he should push into the kernel tree via git like
all the other maintainers (for the relevant portions, obviously --
section 3, for example, doesn't make sense in the kernel tree.)

	-hpa
--
To unsubscribe from this list: send the line "unsubscribe util-linux-ng" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html