[PATCH 0/1] Two changes before we go to rc

[PATCH 0/1] Two changes before we go to rc

[J William Piggott]

With the recent comment regarding the pending rc, I'd like to make
two small string changes before we send them off for translation.

During this cycle all of hwclock usage strings have been changed, but
I still do not like the debug description.

I looked at what the other utils are using; there are only two others
with a debug option and their strings are no better for hwclock, IMO.
So I looked at usage strings for the verbose option. In 27
occurrences there are 15 different descriptions. The most recent one,
written by Karel, I think is good for both debug (except uuidd) and
verbose (it could be made a usage constant to reduce 17 strings to
1). It is: "display more details"

The second change was the subject of a long discussion which ended
without a consensus. My last volley went unanswered:
https://marc.info/?l=util-linux-ng&m=150124890123757&w=2

So this patch also makes the usage constants for help and version use
the same verb; which Karel originally said was an improvement:
https://marc.info/?l=util-linux-ng&m=149794873321562&w=2


CURRENT DEBUG AND VERBOSE USAGE STRINGS.

ldattach.c:    -d, --debug   print verbose messages to stderr
hwclock.c:     -D, --debug   use debug mode
uuidd.c:       -d, --debug   run in debugging mode

setarch.c:     -v, --verbose say what options are being switched on
ipcrm.c:       -v, --verbose explain what is being done
swapon.c:      -v, --verbose verbose mode
swapoff.c:     -v, --verbose verbose mode
chmem.c:       -v, --verbose verbose output
mount.c:       -v, --verbose say what is being done
eject.c:       -v, --verbose enable verbose output
readprofile.c: -v, --verbose print verbose data
fstrim.c:      -v, --verbose print number of discarded bytes
prlimit.c:         --verbose verbose output
losetup.c:     -v, --verbose verbose mode
umount.c:      -v, --verbose say what is being done
fallocate.c:   -v, --verbose verbose mode
blkzone.c:     -v, --verbose display more details
blkdiscard.c:  -v, --verbose print aligned length and offset
rtcwake.c:     -v, --verbose verbose messages
rename.c:      -v, --verbose explain what is being done
mcookie.c:     -v, --verbose explain what is being done
chrt.c:        -v, --verbose display status information
mesg.c:        -v, --verbose explain what is being done
mkfs.bfs.c:    -v, --verbose explain what is being done
fsck.minix.c:  -v, --verbose be verbose
mkfs.c:        -v            be verbose
mkfs.c:        -V, --verbose explain what is being done;
blockdev.c:    -v            verbose mode
fsck.c:        -v, --verbose be more verbose
partx.c:       -v, --verbose verbose mode

J William Piggott (1):
  hwclock: update usage()

 include/c.h         | 2 +-
 sys-utils/hwclock.c | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

[PATCH 1/1] hwclock: update usage()

[J William Piggott]

Improve usage strings for debug and version.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 include/c.h         | 2 +-
 sys-utils/hwclock.c | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/c.h b/include/c.h
index 119a127e3..b0670dcaa 100644
--- a/include/c.h
+++ b/include/c.h
@@ -317,7 +317,7 @@ static inline int xusleep(useconds_t usec)
 #define USAGE_SEPARATOR    "\n"
 
 #define USAGE_OPTSTR_HELP     _("display this help")
-#define USAGE_OPTSTR_VERSION  _("print version")
+#define USAGE_OPTSTR_VERSION  _("display version")
 
 #define USAGE_HELP_OPTIONS(marg_dsc) \
 		"%-" #marg_dsc "s%s\n" \
diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
index 9fb631f6f..bf5459783 100644
--- a/sys-utils/hwclock.c
+++ b/sys-utils/hwclock.c
@@ -1101,7 +1101,7 @@ usage(void)
 	printf(_(
 	       "     --adjfile <file> use an alternate file to %1$s\n"), _PATH_ADJTIME);
 	puts(_("     --test           dry run; use -D to view what would have happened"));
-	puts(_(" -D, --debug          use debug mode"));
+	puts(_(" -D, --debug          display more details"));
 	fputs(USAGE_SEPARATOR, stdout);
 	printf(USAGE_HELP_OPTIONS(22));
 	printf(USAGE_MAN_TAIL("hwclock(8)"));

Re: [PATCH 0/1] Two changes before we go to rc

[Karel Zak]

On Sun, Sep 03, 2017 at 09:14:25PM -0400, J William Piggott wrote:
> 
> With the recent comment regarding the pending rc, I'd like to make
> two small string changes before we send them off for translation.
> 
> During this cycle all of hwclock usage strings have been changed, but
> I still do not like the debug description.
> 
> I looked at what the other utils are using; there are only two others
> with a debug option and their strings are no better for hwclock, IMO.
> So I looked at usage strings for the verbose option. In 27
> occurrences there are 15 different descriptions. The most recent one,
> written by Karel, I think is good for both debug (except uuidd) and
> verbose (it could be made a usage constant to reduce 17 strings to
> 1). It is: "display more details"

OK, merged.

Frankly, I don't like --debug option. It's better to use --verbose for
this purpose for new tools.

>From my point of view debugging is something extremely talkative with
many additional information and should be implemented with some
instrument to control what and how to debug. This is reason why I
prefer *_DEBUG= env. variables. For example LIBMOUNT_DEBUG=<what>.

Anyway, already supported command line options should be supported
"forever" (if possible); hwclock --debug is nice example. It's used by
many many users.

> 
> The second change was the subject of a long discussion which ended
> without a consensus. My last volley went unanswered:
> https://marc.info/?l=util-linux-ng&m=150124890123757&w=2
> 
> So this patch also makes the usage constants for help and version use
> the same verb; which Karel originally said was an improvement:
> https://marc.info/?l=util-linux-ng&m=149794873321562&w=2

I have merged the change. It's fine to have "display" there, and we
should go away from topic :-)


Note that the missing thing for the next release is Rudi's
coreutils-like options arguments:

 https://www.spinics.net/lists/util-linux-ng/msg14396.html

We have 14 days (to 19th) to implement it, the original plan is:

   - Sep 12 -- feature freeze, no invasive changes allowed (aka rc1)
   - Sep 19 -- strings freeze, translations (aka rc2)
   - Sep 26 -- v2.31


but I'm going to sailing in France next week, so rc1 will be later.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 0/1] Two changes before we go to rc

[J William Piggott]

On 09/05/2017 07:00 AM, Karel Zak wrote:
> On Sun, Sep 03, 2017 at 09:14:25PM -0400, J William Piggott wrote:
>>
>> With the recent comment regarding the pending rc, I'd like to make
>> two small string changes before we send them off for translation.
>>
>> During this cycle all of hwclock usage strings have been changed, but
>> I still do not like the debug description.
>>
>> I looked at what the other utils are using; there are only two others
>> with a debug option and their strings are no better for hwclock, IMO.
>> So I looked at usage strings for the verbose option. In 27
>> occurrences there are 15 different descriptions. The most recent one,
>> written by Karel, I think is good for both debug (except uuidd) and
>> verbose (it could be made a usage constant to reduce 17 strings to
>> 1). It is: "display more details"
> 
> OK, merged.
> 
> Frankly, I don't like --debug option. It's better to use --verbose for
> this purpose for new tools.
> 
> From my point of view debugging is something extremely talkative with
> many additional information and should be implemented with some
> instrument to control what and how to debug. This is reason why I
> prefer *_DEBUG= env. variables. For example LIBMOUNT_DEBUG=<what>.

True, one exception may be when it is a debug 'mode'; like uuidd's which
prevents daemonizing. Although that is probably a bad choice too. I
think most use nodetach, nofork, or daemon options for that. hwclock has
a debug mode at level 10, but neither debug levels nor its debug mode
are documented. IMO, they should not be documented.

> 
> Anyway, already supported command line options should be supported
> "forever" (if possible); hwclock --debug is nice example. It's used by
> many many users.

Other unfortunate options for hwclock are epoch and date. So instead of:
hwclock --set --date DATE
hwclock --predict --date DATE
hwclock --setepoch --epoch YEAR

It should have been:
hwclock --set DATE
hwclock --predict DATE
hwclock --setepoch YEAR

As you say, we are stuck with these options. They could be depreciated
and eventually removed, but it's probably not worth the hassle.

When refactoring is complete, and we likely have an entirely new code
base, we could rename the command again and use whatever options we
like. That's probably not worth the hassle either.

 8< ...
 
> 
> Note that the missing thing for the next release is Rudi's
> coreutils-like options arguments:
> 
>  https://www.spinics.net/lists/util-linux-ng/msg14396.html
> 
> We have 14 days (to 19th) to implement it,

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?

 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?

 * 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
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.

I think mixed case for section headers is fine:
Usage:
Options:
SIZE:
...


> the original plan is:
> 
>    - Sep 12 -- feature freeze, no invasive changes allowed (aka rc1)
>    - Sep 19 -- strings freeze, translations (aka rc2)
>    - Sep 26 -- v2.31
> 
> 
> but I'm going to sailing in France next week, so rc1 will be later.

Have a great time! Redhat has generous vacation packages:)

> 
>     Karel
> 

Re: [PATCH 0/1] Two changes before we go to rc

[Karel Zak]

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@redhat.com>
 http://karelzak.blogspot.com