Subject: Documenting filesystem kernel options outside of options(4)
To: None <>
From: Michael-John Turner <>
List: tech-kern
Date: 03/09/2006 21:08:58
Hi all,

After a discussion with hubertf@ on port-sparc64 this afternoon, I was
wondering if there was a good place to document filesystem-specific kernel
options. The case in point is documenting that the relevant options for
SMBFS are:
file-system SMBFS
pseudo-device nsmb
I agree that such things should be documented in options.4, as they are,
but it's not the most obvious to go from mount_smbfs.8 to options.4 (nor
is it documented in mount_smbfs(8) that certain kernel options are required
in order to be able to use it).

Two options:
1 - Include the required/optional kernel options (and only the kernel
    options) in the respective mount*.8 manual pages.
2 - Create a section 4 manual page for each filesystem type (ffs.4,
	 cd9660.4, smbfs.4, etc), explaining in more detail what its for,
    certain key data structures, required and optional kernel options, 
    etc (much like raid.4). The various mount*.8 could then refer to 
    the *.4 for the particular filesystem.

My preference would be for (1), probably because I'm lazy, but Hubert had a
valid point in stating that kernel options shouldn't be documented in
manual pages for userland commands. There is (some limited) prior art
though - for example wsmoused.8, ipf.8, compat*.8 and others mention kernel

Any thoughts on this? Is it worthwhile creating such filesystem manual
pages or documenting the kernel options in each mount* manpage (or both)?
Should I rather spend my time on something more useful? :)

Michael-John Turner |    | Open Source in WC ZA -