Re: Suggestion about how to improve sha512sum documentation

[Pádraig Brady]

On 15/06/2023 22:37, David Loyall wrote:
> Hello.
>
> Today the correct canonical link to the HTML form of the documentation
> for sha512sum is this:
> https://www.gnu.org/software/coreutils/manual/html_node/md5sum-invocation.html

> Note "md5sum" in the URL and in the document.
>
> Here is the explanation:
> https://www.gnu.org/software/coreutils/manual/html_node/sha2-utilities.html
>
> I think the situation should change somehow.  Off the top of my head:
> what if you just flip it around so that the md5sum documentation
> points at the sha2 utilities, instead of the other way around?
>
> Here is why I considered this important enough to mention: at least
> one major organization is currently giving bad advice about the sha2
> family of utilities..  See
> https://www.apache.org/info/verification.html#CheckingHashes and note
> the absence of advice about using the `--check` argument.  The
> `--check` argument is important.
>
> Background: I started writing to a smaller organization suggesting
> they add `--check` to their documentation and during the process I
> discovered a) the larger organization also got it wrong and b) I can't
> provide a direct link to clear documentation from the canonical
> source.
>
> A generation or two of folks have been taught to avoid anything that
> says md5 on it...
>
> Thank you for your time and of course for this collection of utilities
> of immeasurable importance.

Well there are redirects setup for all utils to redirect to the appropriate
part of the manual. These are the URLs presented in the man pages BTW.
So in this case the best url to use is:

https://www.gnu.org/software/coreutils/sha512sum


But I do agree that the docs for these checksum utils have become
a bit awkward as these utilities have evolved.
Currently the option descriptions are dispersed over the following nodes:

* b2sum
* cksum
* md5sum

It would be better I think to now organize the options over two nodes as 
follows,
and then adjust to redirects for the standalone checksum utils to 
cksum-common-options:

* cksum invocation
  * general options
    Options supported only by cksum
    --algorithm
    --base64
    --debug
    --length
    --raw
    --untagged
  * common options
    Options supported by cksum and standalone checksum utilities
    --binary
    --check
    --ignore-missing
    --quiet
    --status
    --tag
    --text
    --warn
    --strict
    --zero

cheers,
Pádraig