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