md5(1): Add EXAMPLES section

[fernape]

Summary

Add EXAMLES covering -c, -s and -r

Test Plan

• mandoc -Tlint clean
• igor clean
• aspell happy
• man ./md5.1 renders the page properly

[bcr]

Two suggestions...

sbin/md5/md5.1

109 ↗

(On Diff #73130)

I'd swap this example with the one above. That way, it shows a simple example first without the combination of any other utility (i.e. echo) and then in the next example, the combination of the two.

128 ↗

(On Diff #73130)

s/compare to and/compare with/

[fernape]

Modifying according to suggestions made by bcr@

• Start with the simplest example and grow from that
• s/compare to and/compare with/

[fernape]

sbin/md5/md5.1

109 ↗

(On Diff #73130)

Yep, seems pretty logical :-)

[bcr]

Almost there...

sbin/md5/md5.1

105 ↗

(On Diff #73242)

I'd combine this to one sentence with the next:
Same as above, but note the absence of ...

[fernape]

Merging two sentences suggested by bcr@

Using .Pa for paths after comment from yuripv@

[bcr]

Excellent, now it's ready to land. Thank you!

[0mp]

sbin/md5/md5.1

99 ↗

(On Diff #73261)

1. md5 here should probably be MD5
2. I'd probably use Dq for Hello, but it is just a personal taste.

105 ↗

(On Diff #73261)

I think I'd replace "\n" with "a newline character". It's up to you though.

111 ↗

(On Diff #73261)

checksum or checksums? I am not sure.

118 ↗

(On Diff #73261)

s/digest/a digest/?

Also, I'd probably drop "file".

122 ↗

(On Diff #73261)

s/validate/validate it/

132 ↗

(On Diff #73261)

I'd wrap randomstring with Dq.

Also, how about:

Same as above but comparing the digest against an invalid string
.Pq Dq randomstring ,
which results in a failure.

or something along those lines.

135 ↗

(On Diff #73261)

The digest file is not used so maybe it could be removed from this example?

Also, the example should be on a single line, right? Or at least have a \ at the end of the first line.

[fernape]

Address comments made by 0mp:

• Use capitalization the name of the checksum algorithm.
• Replace "\n" with "the newline character".
• Use "the digest" instead of "digest". It is used in this form in the man page before.
• s/validate/validate it/
• Rephrasing where necessary
• Remove superfluous command with redirection since the example doesn't need it.

[fernape]

sbin/md5/md5.1

105 ↗

(On Diff #73261)

Note that I used "the newline character" instead.

111 ↗

(On Diff #73261)

I'm not sure either.

118 ↗

(On Diff #73261)

"file" dropped. I used "the digest" since it is used before in the man page.

135 ↗

(On Diff #73261)

Yes, removed. I just added noise to the example.

[0mp]

Thanks!