Page MenuHomeFreeBSD

md5(1): Add EXAMPLES section
ClosedPublic

Authored by fernape on Jun 15 2020, 10:23 AM.

Details

Reviewers
bcr
0mp
Group Reviewers
manpages
Commits
rS362365: md5(1): Add EXAMPLES section
Summary

Add EXAMLES covering -c, -s and -r

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

Diff Detail

Repository
rS FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

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/

Modifying according to suggestions made by bcr@

  • Start with the simplest example and grow from that
  • s/compare to and/compare with/
fernape added inline comments.
sbin/md5/md5.1
109 ↗(On Diff #73130)

Yep, seems pretty logical :-)

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 marked an inline comment as done.

Merging two sentences suggested by bcr@

Using .Pa for paths after comment from yuripv@

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

This revision is now accepted and ready to land.Jun 18 2020, 12:55 PM
0mp requested changes to this revision.Jun 18 2020, 1:01 PM
0mp added a subscriber: 0mp.
0mp added inline comments.
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.

This revision now requires changes to proceed.Jun 18 2020, 1:01 PM

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 added inline comments.
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.

This revision is now accepted and ready to land.Jun 18 2020, 6:45 PM
This revision was automatically updated to reflect the committed changes.
fernape marked 3 inline comments as done.