Polishing help page

flawrist commented

2020-03-24 13:19:14 -05:00

(Migrated from github.com)

Ideas for changing the help page of xxhsum 0.7.2

--------------------------------- 0.7.2 ------------------------------------

$ xxhsum
Wrong parameters
D:\xxhsum.exe 0.7.2 (64-bits x86_64 + SSE2 little endian), GCC 9.2.0, by Yann Collet
Usage :
      D:\xxhsum.exe [arg] [filenames]
When no filename provided, or - provided : use stdin as input
Arguments :
 -H# : hash selection : 0=32bits, 1=64bits, 2=128bits (default: 1)
 -c  : read xxHash sums from the [filenames] and check them
 -h  : help

--------------------------------- 0.7.3 ------------------------------------

$ xxhsum-x64-mingw-w64.exe                                                           
Wrong parameters                                                                                   
D:\xxhsum-x64-mingw-w64.exe 0.7.3 (64-bit x86_64 + SSE2 little endian), GCC 9.2.0, by Yann Collet  
Usage: D:\xxhsum-x64-mingw-w64.exe [OPTION] [FILES]...                                             
Print or check xxHash checksums.                                                                   
                                                                                                   
When no filename provided or when '-' is provided, uses stdin as input.                            
Arguments:                                                                                         
  -H#                  Select hash algorithm. 0=32bits, 1=64bits, 2=128bits (default: 1)           
  -c                   Read xxHash sums from the [filenames] and check them                        
  -h                   Display long help and exit                              

--------------------------------- PROPOSAL ---------------------------------

$ xxhsum
Not enough input to proceed

XXHsum 0.7.4 by Yann Collet, compiled as x64 SSE2 GCC on 2020-04-01
Calculate hash using extremely fast non-cryptographic algorithm xxHash

Usage: xxhsum [options] [filenames | string]

Options:
 -#  algorithm strength: 0=32bits, 1=64bits, 2=128bits (default: 1)
 -c  read xxHash sums from [file] and check them
 -h  display a long help page about advanced options

Name Version / Author / Compilation data (the left part is for users, the right is for devs)
What app enables users to achieve (3 important words here: calculate, fast, non-cryptographic)
App’s name is displayed w/o adding path (it’s a nightmare to read help being run from \…\…\)
Words consistency (no parameters, then options, then arguments) and line breaks for legibility
-H# is changed into -# for speed, not to mention we choose not another Hash, but its strength

<p> <details> <summary>Ideas for changing the help page of xxhsum 0.7.2</summary> ```console --------------------------------- 0.7.2 ------------------------------------ $ xxhsum Wrong parameters D:\xxhsum.exe 0.7.2 (64-bits x86_64 + SSE2 little endian), GCC 9.2.0, by Yann Collet Usage : D:\xxhsum.exe [arg] [filenames] When no filename provided, or - provided : use stdin as input Arguments : -H# : hash selection : 0=32bits, 1=64bits, 2=128bits (default: 1) -c : read xxHash sums from the [filenames] and check them -h : help --------------------------------- 0.7.3 ------------------------------------ $ xxhsum-x64-mingw-w64.exe Wrong parameters D:\xxhsum-x64-mingw-w64.exe 0.7.3 (64-bit x86_64 + SSE2 little endian), GCC 9.2.0, by Yann Collet Usage: D:\xxhsum-x64-mingw-w64.exe [OPTION] [FILES]... Print or check xxHash checksums. When no filename provided or when '-' is provided, uses stdin as input. Arguments: -H# Select hash algorithm. 0=32bits, 1=64bits, 2=128bits (default: 1) -c Read xxHash sums from the [filenames] and check them -h Display long help and exit --------------------------------- PROPOSAL --------------------------------- $ xxhsum Not enough input to proceed XXHsum 0.7.4 by Yann Collet, compiled as x64 SSE2 GCC on 2020-04-01 Calculate hash using extremely fast non-cryptographic algorithm xxHash Usage: xxhsum [options] [filenames | string] Options: -# algorithm strength: 0=32bits, 1=64bits, 2=128bits (default: 1) -c read xxHash sums from [file] and check them -h display a long help page about advanced options ``` * Name Version / Author / Compilation data (the left part is for users, the right is for devs) * What app enables users to achieve (3 important words here: calculate, fast, non-cryptographic) * App’s name is displayed w/o adding path (it’s a nightmare to read help being run from ```\…\…\```) * Words consistency (no ```parameters```, then ```options```, then ```arguments```) and line breaks for legibility * ```-H#``` is changed into ```-#``` for speed, not to mention we choose not another Hash, but its strength </details> </p>

👍 1

easyaspi314 commented

2020-03-24 13:32:28 -05:00

(Migrated from github.com)

Name Version / Author / Compilation data (the left part is for users, the right is for devs)

I will say I like the format.

What app enables users to achieve (3 important words here: calculate, fast, non-cryptographic)

Calculate? sure.

Fast? Not required, there is no reason to boast, and most of the time with checksum utilities, the bottleneck is disk IO.

Non-cryptographic? That is good.

App’ name is displayed w/o adding path (it’s a nightmare to read help being run from \…\…)

Yeah, I was considering that.

static const char *exename(const char *filename)
{
    const char *ret = filename;
    if (filename != NULL) {
        const char *forwardslash = strrchr(filename, '/');
        const char *backslash = strrchr(filename, '\\');
        if (forwardslash != NULL && forwardslash > ret)
            ret = forwardslash;
        if (backslash != NULL && backslash > ret)
            ret = backslash;
    }
    return ret;
}

Words consistency (no parameters, then options, then arguments) and line breaks for legibility

Yeah could use better organization

-H# is changed into -# for speed, not to mention we choose not another Hash, but its strength

No, XXH32, XXH64, and XXH128 are different hash algorithms. It would be better to mention them by name, though.

> Name Version / Author / Compilation data (the left part is for users, the right is for devs) I will say I like the format. > What app enables users to achieve (3 important words here: calculate, fast, non-cryptographic) Calculate? sure. Fast? Not required, there is no reason to boast, and most of the time with checksum utilities, the bottleneck is disk IO. Non-cryptographic? That is good. > App’ name is displayed w/o adding path (it’s a nightmare to read help being run from \…\…\) Yeah, I was considering that. ```c static const char *exename(const char *filename) { const char *ret = filename; if (filename != NULL) { const char *forwardslash = strrchr(filename, '/'); const char *backslash = strrchr(filename, '\\'); if (forwardslash != NULL && forwardslash > ret) ret = forwardslash; if (backslash != NULL && backslash > ret) ret = backslash; } return ret; } ``` > Words consistency (no parameters, then options, then arguments) and line breaks for legibility Yeah could use better organization > -H# is changed into -# for speed, not to mention we choose not another Hash, but its strength No, XXH32, XXH64, and XXH128 are different hash algorithms. It would be better to mention them by name, though.

Cyan4973 commented

2020-04-07 16:28:39 -05:00

(Migrated from github.com)

These are nice suggestions @sergeevabc ,
I will put together a patch following some of these recommendations.

These are nice suggestions @sergeevabc , I will put together a patch following some of these recommendations.

flawrist commented

2020-06-25 06:41:36 -05:00

(Migrated from github.com)

I am saddened to report that the default output of 0.7.4 is still an irritating eyesore,
because it displays full path to the executable (1,2) for no reason and neglects line breaks (3).

I am saddened to report that the default output of 0.7.4 is still an irritating eyesore, because it displays full path to the executable (1,2) for no reason and neglects line breaks (3). ![](https://i5.imageban.ru/out/2020/06/25/c7b54cd820daeb25285e7a842255cd6e.webp)

easyaspi314 commented

2020-06-25 07:41:49 -05:00

(Migrated from github.com)

because it displays full path to the executable (1,2) for no reason

I guess I can work on that.

neglects line breaks (3).

We would have to get the specific columns of the terminal, which is far from portable. Won't fix, sorry.

> because it displays full path to the executable (1,2) for no reason I guess I can work on that. > neglects line breaks (3). We would have to get the specific columns of the terminal, which is far from portable. Won't fix, sorry.

👍 1

easyaspi314 commented

2020-06-25 12:05:41 -05:00

(Migrated from github.com)

Lexically, we should be able to do something like this:

static const char* stripDirectoryName(const char* pathname)
{
    const char* tmp = strrchr(pathname, '/');
    if (tmp != NULL && tmp[1] != '\0') {
        pathname = &tmp[1];
    }
    tmp = strrchr(pathname, '\\');
    if (tmp != NULL && tmp[1] != '\0') {
        pathname = &tmp[1];
    }
    return pathname;
}

Lexically, we should be able to do something like this: ```c static const char* stripDirectoryName(const char* pathname) { const char* tmp = strrchr(pathname, '/'); if (tmp != NULL && tmp[1] != '\0') { pathname = &tmp[1]; } tmp = strrchr(pathname, '\\'); if (tmp != NULL && tmp[1] != '\0') { pathname = &tmp[1]; } return pathname; } ```

Cyan4973 commented

2020-06-25 13:30:09 -05:00

(Migrated from github.com)

LZ4 has this : lastNameFromPath()
https://github.com/lz4/lz4/blob/v1.9.2/programs/lz4cli.c#L239

should be re-usable.

`LZ4` has this : `lastNameFromPath()` https://github.com/lz4/lz4/blob/v1.9.2/programs/lz4cli.c#L239 should be re-usable.

flawrist commented

2020-06-25 14:38:54 -05:00

(Migrated from github.com)

And speaking of line breaks, do we really need such verbose first line, including URL to the specific git of Clang?! Not to mention that end-users might perceive that as a link to the official website of the app. Originally I proposed much shorter output which contains app’s name, version, author, architecture and even a release date. But if you insist on outputting all that “little endian” stuff, consider moving it to the next line as follows

XXHsum 0.7.4 by Yann Collet [HARD-CODED LINE BREAK]
Compiled …

And speaking of line breaks, do we really need such verbose first line, including URL to the specific git of Clang?! Not to mention that end-users might perceive that as a link to the official website of the app. Originally I proposed much shorter output which contains app’s name, version, author, architecture and even a _release date_. But if you insist on outputting all that “little endian” stuff, consider moving it to the next line as follows ``` XXHsum 0.7.4 by Yann Collet [HARD-CODED LINE BREAK] Compiled … ```

Cyan4973 commented

2020-06-25 15:53:58 -05:00

(Migrated from github.com)

That looks reasonable.

There might be situations where it's less desirable to display 2 lines instead of 1,
but we can probably separate efficiently these scenarios.

I believe that advanced compilation informations have proven fairly useful during this development period.
I also believe they are still valid and important when invoking the internal benchmark module.
Beyond that, and as we are gearing towards stabilization, they could take a second seat.

That looks reasonable. There might be situations where it's less desirable to display 2 lines instead of 1, but we can probably separate efficiently these scenarios. I believe that advanced compilation informations have proven fairly useful during this development period. I also believe they are still valid and important when invoking the internal benchmark module. Beyond that, and as we are gearing towards stabilization, they could take a second seat.

easyaspi314 commented

2020-06-25 16:56:08 -05:00

(Migrated from github.com)

do we really need such verbose first line, including URL to the specific git of Clang?!

That is a MinGW thing, MinGW puts this in __clang_version__ for some reason. Most just do the version number.

> do we really need such verbose first line, including URL to the specific git of Clang?! That is a MinGW thing, MinGW puts this in `__clang_version__` for some reason. Most just do the version number.

flawrist commented

2023-12-27 16:40:38 -06:00

(Migrated from github.com)

xxHash flavors naming convention probably did not keep up with the development, so today we have a mess of two families (1 and 3), two flavors with the same bit length (64), and ambiguous tags, but this mess needs to be dealt with. Sooner is better than later.

Since I am still looking for clarity regarding the help screen, I'll make another suggestion.

$ xxhsum

xxhsum 1.0 by Yann Collet
Calculates and verifies checksums using fast non-cryptographic algorithm xxHash

Usage: xxhsum [options] [filename]
If filename is omitted or '-' is provided instead, uses stdin as input

Options:
  -H#, --hash  Algorithm flavor to use (default: 1)
               Learn about the differences at xxhash.com
               0 = X1H32  (xxHash1 32 bit)
               1 = X1H64  (xxHash1 64 bit)
               2 = X3H128 (xxHash3 128 bit)
               3 = X3H64  (xxHash3 64 bit)
  -c, --check  Verify checksums from [filename]
  -h, --help   Display information about advanced options

If the tag standardization part looks too radical, there is the OpenHashTab way as follows

               0 = XXH32
               1 = XXH64
               2 = XXH3-128
               3 = XXH3-64

xxHash flavors naming convention probably did not keep up with the development, so today we have a mess of two families (1 and 3), two flavors with the same bit length (64), and [ambiguous tags](https://github.com/Cyan4973/xxHash/issues/645), but this mess needs to be dealt with. Sooner is better than later. Since I am still [looking for clarity](https://github.com/Cyan4973/xxHash/issues/388#issuecomment-1870470560) regarding the help screen, I'll make another suggestion. ``` console $ xxhsum xxhsum 1.0 by Yann Collet Calculates and verifies checksums using fast non-cryptographic algorithm xxHash Usage: xxhsum [options] [filename] If filename is omitted or '-' is provided instead, uses stdin as input Options: -H#, --hash Algorithm flavor to use (default: 1) Learn about the differences at xxhash.com 0 = X1H32 (xxHash1 32 bit) 1 = X1H64 (xxHash1 64 bit) 2 = X3H128 (xxHash3 128 bit) 3 = X3H64 (xxHash3 64 bit) -c, --check Verify checksums from [filename] -h, --help Display information about advanced options ``` If the tag standardization part looks too radical, there is the [OpenHashTab](https://github.com/namazso/OpenHashTab) way as follows ``` console 0 = XXH32 1 = XXH64 2 = XXH3-128 3 = XXH3-64 ```

Rows
Columns

Polishing help page #345