On Thu, Sep 07, 2017 at 04:50:00PM -0400, J William Piggott wrote:
> My thoughts were:
>
> It was Rudi's idea, so I assumed he wanted to implement it.
>
> It doesn't look to me like this can be done with sed alone. It seems
> like it would take too long to finish for this cycle?
Probably yes. It is not anything urgent so it could be done later (or
never -- the current usage() output seems good too). The idea is not
bad, but it's pretty invasive... I have no strong opinion about it.
> I didn't think all of the details had been hammered out yet, like:
>
> * ul currently uses the same argument notation for usage and docs.
> coreutils usages and docs both use their notation style.
> So won't this switch mean changing all of the docs as well?
Good point.
> * Your final example was:
>
> > after change:
> > -e, --exclude MAJOR exclude specified devices (see below)
> > -I, --include MAJOR show only specified devices (see below)
> > -o, --output COLUMNS output columns (see below)
> > -x, --sort COLUMN sort output by column
> >
> > The MAJOR command separated list of the device major numbers. The
> > ramdisk devices are excluded by default.
> >
> > Available COLUMNS:
> > NAME device name
> > KNAME internal kernel device name
> > ...
>
> Coreutils starts the details sections with the magic argument. See
> 'split --help' and 'date --help'. I think that is better because they
> align and you don't have to look for them.
>
> IMO, coreutils usage is too verbose and busy; it should be a quick
Well, I'd like to keep our usage() stuff compact and short.
> reference for users that already understand the command and should be as
> terse as possible. Otherwise they probably need to read the manual.
>
> Perhaps the magic argument name should not be too abstract(MAJOR) and
> its details should be a simple example list? Something like:
>
> -e, --exclude DEV exclude specified devices (see below)
> -I, --include DEV show only specified devices (see below)
> -o, --output COLUMNS output columns (see below)
> -x, --sort COLUMN sort output by column
>
> DEV: 1,2,3 ... major_dev_number
>
> COLUMNS: NAME,KNAME, ...
>
> The linkage between the magic argument and its details section should be
> strong enough to not require any more explanation.
"(see below)" seems good enough
> I think mixed case for section headers is fine:
> Usage:
> Options:
> SIZE:
> ...
Yes.
Karel
--
Karel Zak <kzak@xxxxxxxxxx>
http://karelzak.blogspot.com
--
To unsubscribe from this list: send the line "unsubscribe util-linux" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
