Re: [RFC] devpts man page update

["H. Peter Anvin" <hpa-YMNOUZJC4hwAvxtiuMwx3w@public.gmane.org>]

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