mount(8) manpage and filesystem-specific options

mount(8) manpage and filesystem-specific options

[Christoph Hellwig]

Currently the mount(8) manpages which is contained inside util-linux
has a list of mount options for various filesystem.  Now the filesystems
are in the kernel tree and can change options without affecting the
mount binary, and of course do so frequently.  This means these options
are frequently out of date.  All these options also make the manpage
quite large and harder to read.  What do peope think about adding a
(section 4?) manpage for every common filesystem in the man-pages
repository instead which people seems to help updating nowdays when
doing user ABI changes, and linking from the mount manpage to it?
--
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: mount(8) manpage and filesystem-specific options

[Karel Zak]

On Tue, Nov 25, 2008 at 11:15:58PM -0500, Christoph Hellwig wrote:
> Currently the mount(8) manpages which is contained inside util-linux
> has a list of mount options for various filesystem.  Now the filesystems
> are in the kernel tree and can change options without affecting the
> mount binary, and of course do so frequently.  This means these options
> are frequently out of date.  All these options also make the manpage

 Yes, you're right.

> quite large and harder to read.  What do peope think about adding a
> (section 4?) manpage for every common filesystem in the man-pages

 Something like this is on my wish list for long time ;-)

> repository instead which people seems to help updating nowdays when
> doing user ABI changes, and linking from the mount manpage to it?

 Do we have man-power to maintain the same thing on two places?

 The FS specific options are already documented in the kernel
 Documentation/ directory. I have no strong opinion about it, but I
 think the best solution is to maintain this docs on one place only.
 The place should be in the kernel tree otherwise developers will
 ignore the docs... (it's pretty simple to reject kernel patches
 without proper Documentation/ update).

 What about to keep this kernel docs in a parse-able (ascidoc?) format
 and generate the final man pages from this primary source. The final
 man pages could be distributed by util-linux-ng or man-pages.

    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: mount(8) manpage and filesystem-specific options

[Andreas Dilger]

On Nov 26, 2008  11:54 +0100, Karel Zak wrote:
> On Tue, Nov 25, 2008 at 11:15:58PM -0500, Christoph Hellwig wrote:
> > Currently the mount(8) manpages which is contained inside util-linux
> > has a list of mount options for various filesystem.  Now the filesystems
> > are in the kernel tree and can change options without affecting the
> > mount binary, and of course do so frequently.  This means these options
> > are frequently out of date.  All these options also make the manpage
> 
>  Yes, you're right.
> 
> > quite large and harder to read.  What do peope think about adding a
> > (section 4?) manpage for every common filesystem in the man-pages
> 
>  Something like this is on my wish list for long time ;-)

I see on my system that there are already mount.nfs(8) and mount.cifs(8)
man pages, but this is because /sbin/mount.{nfs,cifs} are separate binaries.

I DO think that it makes sense to have separate mount.{fstype} man pages
to clean up the mount(8) man page.  I've also thought that this page is
a huge mess.

<aside>
I never know what man section to put a new man page in, because the
descriptions of the section numers isn't given in the man(1) man page
itself, nor in any document in SEE ALSO.
</aside> 

>  The FS specific options are already documented in the kernel
>  Documentation/ directory. I have no strong opinion about it, but I
>  think the best solution is to maintain this docs on one place only.
>  The place should be in the kernel tree otherwise developers will
>  ignore the docs... (it's pretty simple to reject kernel patches
>  without proper Documentation/ update).

I would be happy do just put the mount.ext{2,3,4}(4) man pages into
linux/Documentation/filesystems/{man?} and have the ext{2,3,4} docs
refer to them for the mount options.

Cheers, Andreas
--
Andreas Dilger
Sr. Staff Engineer, Lustre Group
Sun Microsystems of Canada, Inc.

--
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: mount(8) manpage and filesystem-specific options

[Chuck Lever]

On Nov 26, 2008, at 3:05 PM, Andreas Dilger wrote:
> On Nov 26, 2008  11:54 +0100, Karel Zak wrote:
>> On Tue, Nov 25, 2008 at 11:15:58PM -0500, Christoph Hellwig wrote:
>>> Currently the mount(8) manpages which is contained inside util-linux
>>> has a list of mount options for various filesystem.  Now the  
>>> filesystems
>>> are in the kernel tree and can change options without affecting the
>>> mount binary, and of course do so frequently.  This means these  
>>> options
>>> are frequently out of date.  All these options also make the manpage
>>
>> Yes, you're right.
>>
>>> quite large and harder to read.  What do peope think about adding a
>>> (section 4?) manpage for every common filesystem in the man-pages
>>
>> Something like this is on my wish list for long time ;-)
>
> I see on my system that there are already mount.nfs(8) and  
> mount.cifs(8)
> man pages, but this is because /sbin/mount.{nfs,cifs} are separate  
> binaries.

NFS mount options are documented in nfs(5) of all places.   
mount.nfs(8) documents only the command-line options for /sbin/ 
mount.nfs, but not NFS mount options.  Kind of confusing.

> I DO think that it makes sense to have separate mount.{fstype} man  
> pages
> to clean up the mount(8) man page.  I've also thought that this page  
> is
> a huge mess.

...especially because support for individual file systems can often be  
separately installed on most distributions I commonly use.  XFS has  
been treated this way, for example, until just recently.  nfs(5) and  
mount.nfs(8) come from nfs-utils, not from util-linux.

> <aside>
> I never know what man section to put a new man page in, because the
> descriptions of the section numers isn't given in the man(1) man page
> itself, nor in any document in SEE ALSO.
> </aside>

+1

Just as an example of what could be done, Solaris uses mount_nfs(1M)  
to document NFS mount options (and mount_zfs(1M) and so on), but the  
administrative command interface is always "mount."  The subcommands  
are hidden, and I'm not aware of any visible documentation for them.   
The man pages describing mount options for individual file systems are  
referenced in mount(1M)'s SEE ALSO section.

--
Chuck Lever
chuck[dot]lever[at]oracle[dot]com

Re: mount(8) manpage and filesystem-specific options

[Karel Zak]

On Wed, Nov 26, 2008 at 01:05:26PM -0700, Andreas Dilger wrote:
> I never know what man section to put a new man page in, because the
> descriptions of the section numers isn't given in the man(1) man page
> itself, nor in any document in SEE ALSO.

 Hmm... man-1.6f-4.fc9, "man man" (yes, man(1) man page):

MANUAL SECTIONS
       The standard sections of the manual include:

       1      User Commands

       2      System Calls

       3      C Library Functions

       4      Devices and Special Files

       5      File Formats and Conventions

       6      Games et. Al.

       7      Miscellanea

       8      System Administration tools and Deamons

       Distributions customize the manual section to their specifics,
       which often include additional sections.


-- 
 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: mount(8) manpage and filesystem-specific options

[Michael Kerrisk]

On Tue, Nov 25, 2008 at 11:15 PM, Christoph Hellwig <hch-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> Currently the mount(8) manpages which is contained inside util-linux
> has a list of mount options for various filesystem.  Now the filesystems
> are in the kernel tree and can change options without affecting the
> mount binary, and of course do so frequently.  This means these options
> are frequently out of date.  All these options also make the manpage
> quite large and harder to read.  What do peope think about adding a
> (section 4?) manpage for every common filesystem in the man-pages
> repository instead which people seems to help updating nowdays when
> doing user ABI changes, and linking from the mount manpage to it?

Sounds okay to me.

-- 
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