Page MenuHomeFreeBSD

hexdump(1): Add EXAMPLES section
ClosedPublic

Authored by fernape on Jun 23 2020, 9:25 AM.

Details

Reviewers
gbe
Group Reviewers
manpages
Commits
rS362783: hexdump(1): Add EXAMPLES section
Summary
  • Add examples showing the use of -f, -C, -s, -n
  • Rework the two already present examples that were *format* examples
  • Remove .Tn suggested by mandoc(1)
  • Remove reference to gdb(1) since it is not present in current
Test Plan
  • mandoc -Tlint clean
  • igor clean (except for an spurious "repeted [e e]" in "FreeBSD"
  • aspell happy
  • man ./hexdump.1 renders the page properly

The new additions respect the 80 columns limit on source although it exceeds
that when visualizing the man page. Due to how hexdump(1) shows the information
it is difficult to get a meaningful example and complying with that limit
during visualization. Anyway, I'm open to rework this if necessary.

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

gbe requested changes to this revision.Jun 29 2020, 6:18 AM
gbe added a subscriber: gbe.

Thanks for the patch!

Everything looks good except the manpage date, which should be bumped. :)

This revision now requires changes to proceed.Jun 29 2020, 6:18 AM

Bumping .Dd as suggested by gbe

In D25406#563478, @gbe wrote:

Thanks for the patch!

Everything looks good except the manpage date, which should be bumped. :)

Hi Gordon,

Thanks for reviewing this!
I usually bump .Dd when I commit the review (although I know it is a risk because I could forget it). As a general rule, should the manpage date and the commit date be equal?

In D25406#563478, @gbe wrote:

Thanks for the patch!

Everything looks good except the manpage date, which should be bumped. :)

Hi Gordon,

Thanks for reviewing this!
I usually bump .Dd when I commit the review (although I know it is a risk because I could forget it). As a general rule, should the manpage date and the commit date be equal?

Hi Fernando,

not necessarily, I personally set the .Dd to the date I wrote the update, otherwise the workflow would be a little different,
because you theoretically commit something that wasn't approved. After an approval I just download the raw diff an apply it to my
local svn checkout.

@bcr what do you think?

This revision is now accepted and ready to land.Jun 29 2020, 7:37 AM
In D25406#563478, @gbe wrote:

Thanks for the patch!

Everything looks good except the manpage date, which should be bumped. :)

Hi Gordon,

Thanks for reviewing this!
I usually bump .Dd when I commit the review (although I know it is a risk because I could forget it). As a general rule, should the manpage date and the commit date be equal?

The manual page date should match the commit date.

In D25406#563515, @0mp wrote:
In D25406#563478, @gbe wrote:

Thanks for the patch!

Everything looks good except the manpage date, which should be bumped. :)

Hi Gordon,

Thanks for reviewing this!
I usually bump .Dd when I commit the review (although I know it is a risk because I could forget it). As a general rule, should the manpage date and the commit date be equal?

The manual page date should match the commit date.

If everything is OK, I can commit this (later) today. The commit date will match .Dd

In D25406#563515, @0mp wrote:
In D25406#563478, @gbe wrote:

Thanks for the patch!

Everything looks good except the manpage date, which should be bumped. :)

Hi Gordon,

Thanks for reviewing this!
I usually bump .Dd when I commit the review (although I know it is a risk because I could forget it). As a general rule, should the manpage date and the commit date be equal?

The manual page date should match the commit date.

If everything is OK, I can commit this (later) today. The commit date will match .Dd

From my perspective everything is okay. I tried the examples on the command line and they worked, I also checked mandoc -Tlint output and so on. :)

In D25406#563515, @0mp wrote:
In D25406#563478, @gbe wrote:

Thanks for the patch!

Everything looks good except the manpage date, which should be bumped. :)

Hi Gordon,

Thanks for reviewing this!
I usually bump .Dd when I commit the review (although I know it is a risk because I could forget it). As a general rule, should the manpage date and the commit date be equal?

The manual page date should match the commit date.

@0mp I usually tend to not hand edit my "commit ready" tree.

In D25406#563533, @gbe wrote:
In D25406#563515, @0mp wrote:
In D25406#563478, @gbe wrote:

Thanks for the patch!

Everything looks good except the manpage date, which should be bumped. :)

Hi Gordon,

Thanks for reviewing this!
I usually bump .Dd when I commit the review (although I know it is a risk because I could forget it). As a general rule, should the manpage date and the commit date be equal?

The manual page date should match the commit date.

@0mp I usually tend to not hand edit my "commit ready" tree.

Don't we have a commit-hook that checks for .Dd? Would it be difficult to implement?

This revision was automatically updated to reflect the committed changes.
@fernape wrote:

Don't we have a commit-hook that checks for .Dd? Would it be difficult to implement?

How would commit hook differentiate when .Dd bump is needed (that is, because of functional or otherwise significant changes) and when it's not (for typos and small markup fixes and such)?

In D25406#563533, @gbe wrote:
In D25406#563515, @0mp wrote:
In D25406#563478, @gbe wrote:

Thanks for the patch!

Everything looks good except the manpage date, which should be bumped. :)

Hi Gordon,

Thanks for reviewing this!
I usually bump .Dd when I commit the review (although I know it is a risk because I could forget it). As a general rule, should the manpage date and the commit date be equal?

The manual page date should match the commit date.

@0mp I usually tend to not hand edit my "commit ready" tree.

Don't we have a commit-hook that checks for .Dd? Would it be difficult to implement?

It's hard to know when we reach the threshold of a meaningful change.

Do you do the date in the current timezone, or the date in UTC?

when commits are approved that already have a date in them, it's understood that it can change w/o new approval to a more appropriate date...

However having said that, it doesn't matter that much: a day or even 10 days in the past when committed is fine. It doesn't have to match the commit date, just be (a) newer than the last date and (b) be close enough to today. I've often committed things from a branch that have commit dates a few days in the past due to other issues with the string of patches taking a day or three to iron out (and then forgetting). The consequences of a date that's off a few days generally don't matter, so it's best not to sweat it too much if there's an oops or you want to commit 'as tested' code.... igor warns about it :)

Since it doesn't matter that much, and it's hard to implement, nobody has tried.

Anyway, all imho...