Re: Coreutils needs a man page

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

[re-adding the list, so that others may chime in]

[please don't top-post on technical lists, and consider changing your
line-wrap options to 72 characters so your text doesn't look so ugly]

According to jesse wilson on 5/30/2009 5:00 AM:
>>>>> deleting it. Since "--" is a
>>>>> common option of the coreutils,
>> More than that, it is a common option required by POSIX of almost all apps
>> (although not all apps follow POSIX, and there are a few exceptions for
>> things like echo).

> Even though it is a posix standard, as you yourself said the -- option
> is not used by all
> programs. POSIX is just there to provide the most basic sanity, there
> is really no force
> behind the POSIX standards, at least with respect to writers of
> individual programs.
> Should POSIX itself have a manpage? Perhaps. I do not suggest that
> coreutils should be
> "The One" to provide the manpage that describes this option, only "a
> one". Indeed, there
> are other manpages that describe this option, see: man getopts.
> However, getopts is
> an unrelated utility, so it would be daft (in my opinion) to refer
> users to that manpage. If
> there were a POSIX manpage, it would still be a bad idea to refer
> users to that manpage.
> Why? Because POSIX is a standard, it describes the way things "should"
> be done. Users
> reading the manpages of the various coreutils are looking for how
> things actually are
> done. The two can be very close, but there is no guarantee they will
> be the same. I know
> the developers of the coreutils work very hard to follow POSIX
> standards, but users
> reading manpages don't necessarily even know what POSIX is. They might not 
> care
> whether you follow the POSIX standard or the BAD'NIX standard. They're not 
> that
> concerned whether you use -- to delimit the options or -EndOfOptions,
> they just want to
> know how to delimit the options. But the fact is that  -- is an option
> of ls and all the other
> coreutils, which is not listed in hardly any of their manpages (rm
> being the only
> exception I am aware of). Info coreutils takes care of this by
> describing the common
> options first, before going into the individual coreutils programs'
> options. It appears
> that the manpages only contain the same information as the sections
> for the individual
> programs in the coreutils info manual, which do not describe the -- option. 
> The
> manpages also do not refer people to info coreutils 'common options'
> but rather to e.g.
> info coreutils 'ls invocation'. Clearly the manpages need to either
> describe the common
> options themselves, or reference a document that does describe the
> common options.

They do.  'man ls' tells you to read 'info ls', and when you do that, the
very first link on the 'info ls' page takes you to Common Options, which
details the behavior of -- among others.  You can also get there directly
with:
info coreutils 'Common Options'

> The manpages should also not assume that 'info' is available to the
> user: if the user is
> reading a manpage, he's got man installed/available, but not
> necessarily info.

But in the GNU world, info is the primary documentation, and man is
secondary.  If you don't have the info pages installed, you aren't
following the GNU recommendations, so it is your installation at fault.

> So, my
> suggestion is, coreutils should have a manpage, and individual
> coreutils manpages
> should reference it. Why not put that option in each and every manpage
> for the individual
> coreutils? I don't know. Some would argue that that is the better
> option for sure.
> However, it seems to me that having one manpage describing the 'common' 
> behavior
> of coreutils programs is useful. That 'common' behavior is designed to
> be common, and
> that 'common' behavior (in theory) could change. If it changes than
> you only have to
> update one manpage. Also, the coreutils manpage would have alot of info that 
> is
> obviously out of the scope of the individual coreutils' manpages. It
> would also be easy
> to create an initial coreutils manpage: you can pretty much just copy the
> 'common options' section of the coreutils info page.
> 

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkohKvsACgkQ84KuGfSFAYBFKgCfdYBFcaOaDuX+3vHz332hML8o
rcAAn0y4BCIgozBDcU4HgfLEG11O0yiu
=JCsh
-----END PGP SIGNATURE-----