Page MenuHomeFreeBSD
Differential D25116

seq(1): complete EXAMPLES section
ClosedPublic
Actions

Authored by fernape on Jun 3 2020, 11:21 AM.
Tags
None
Referenced Files
Unknown Object (File)
Fri, Nov 15, 8:00 AM
Unknown Object (File)
Thu, Nov 14, 12:29 PM
Unknown Object (File)
Thu, Nov 14, 10:43 AM
Unknown Object (File)
Thu, Nov 14, 2:08 AM
Unknown Object (File)
Nov 11 2024, 11:11 AM
Unknown Object (File)
Nov 11 2024, 9:57 AM
Unknown Object (File)
Nov 10 2024, 9:51 AM
Unknown Object (File)
Nov 10 2024, 12:11 AM
View All 23 Files
Subscribers
0mp
bcr
imp
juan.molina_club.fr
Contributor Reviews (src)

Details

Reviewers
0mp
Group Reviewers
manpages
Summary

This change is three fold but I'm willing to split this in parts if necessary.

  • Add a small description before the EXAMPLES that are already in the man page. It is always better to explicitely state what we are trying to show instead of having the user guess what the example is doing. Even for simple cases.
  • Add two more examples to show usage of -s, -t and -f
  • mandoc -Tlint reports irrelevant use of .Tn so remove them since according to mdoc(7) it is there only for compatibility and should not be used in new manuals.

I did not run any atf(7) tests but having a look at the script in test/ I
can't see anything related to the manual page.

Test Plan

mandoc -Tlint ./seq.1 doesn't report any issues
man page renders normally

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
No Lint Coverage
Unit
No Test Coverage
Build Status
Buildable 31459
Build 29073: arc lint + arc unit

Event Timeline

fernape created this revision.Jun 3 2020, 11:21 AM
Herald added a reviewer: manpages. · View Herald TranscriptJun 3 2020, 11:21 AM
Herald added subscribers: Contributor Reviews (src), imp. · View Herald Transcript
Harbormaster completed remote builds in B31458: Diff 72608.Jun 3 2020, 11:21 AM
fernape requested review of this revision.Jun 3 2020, 11:21 AM
fernape edited the summary of this revision. (Show Details)Jun 3 2020, 11:25 AM
bcr added a subscriber: bcr.Jun 3 2020, 11:30 AM

Mention the including last number and end each description with a colon (:).

seq/seq.1
136

I'd add "(including)" after the 3 to indicate that the last number provided is also part of the resulting output. You might also want to end the sentence with a colon (:).

144

Same here for the 1: (including)

153

If you want, you can make all these descriptions end in a colon (:) for consistency.

fernape updated this revision to Diff 72614.Jun 3 2020, 2:17 PM

Addressing bcr@ comments:

  • Add colon (:) at the end of every description
  • Add (including) to signify this is a closed range at both ends
Harbormaster completed remote builds in B31459: Diff 72614.Jun 3 2020, 2:17 PM
fernape marked 3 inline comments as done.Jun 3 2020, 2:19 PM
bcr accepted this revision as: manpages.Jun 3 2020, 4:41 PM

Excellent, good to go now. Thank you!

fernape added a comment.Jun 3 2020, 4:44 PM
In D25116#553363, @bcr wrote:

Excellent, good to go now. Thank you!

Great! Thanks for the time spent to review this. Just note that I'm not neither a docs nor a src committer :-)

juan.molina_club.fr added a subscriber: juan.molina_club.fr.Jun 3 2020, 6:13 PM
juan.molina_club.fr added inline comments.
seq/seq.1
152

The increment is 0.05

fernape updated this revision to Diff 72642.Jun 3 2020, 8:25 PM

Fix incorrect increment in example description (spotted by Juan Molina)

Harbormaster completed remote builds in B31474: Diff 72642.Jun 3 2020, 8:25 PM
fernape marked an inline comment as done.Jun 3 2020, 8:25 PM
fernape added inline comments.
seq/seq.1
152

Nice catch!

fernape marked an inline comment as done.Jun 4 2020, 8:28 AM

Do we need to update .Dd?

bcr added a comment.Jun 4 2020, 8:38 AM

Yeah, it can be done by a follow-up commit.

fernape added a comment.Jun 18 2020, 4:19 PM
In D25116#553569, @bcr wrote:

Yeah, it can be done by a follow-up commit.

In D25116#553569, @bcr wrote:

Yeah, it can be done by a follow-up commit.

Is this ready to go? Seems a bit confusing the "Needs-review" and the "accepted earlier" badge.

bcr accepted this revision as: manpages.Jun 18 2020, 5:58 PM

Approved!

0mp requested changes to this revision.Jun 18 2020, 7:17 PM
0mp added a subscriber: 0mp.
0mp added inline comments.
seq/seq.1
136

Shouldn't it be inclusive instead of including?

Also, a sequence and a default increment.

The same for other examples as well I think.

161

a custom separator and a custom terminator

170

How about

with an increment of 0.2 and print the results with two digits after the decimal point (using a printf(3)-like format)

This revision now requires changes to proceed.Jun 18 2020, 7:17 PM
fernape updated this revision to Diff 73338.Jun 19 2020, 3:59 PM

Addressing comments by 0mp@:

  • Use of the particle 'a' when necessary
  • Use of 'include' instead of 'including' (I see this is how it is used here)
  • Rephrasing to make example descriptions clearer
fernape marked 3 inline comments as done.Jun 19 2020, 4:05 PM
fernape added inline comments.
seq/seq.1
136

I used included as it is used in the Wikipedia article of ISO 31-11

170

I rephrased the text that is much clearer now.

However for the the printf(3)-like, I observe the expression printf(3) style is used before in the man page. Shouldn't we keep it like that for consistency? Also, how can I use .Xr printf 3 and have the -like joined to the previous word? I could only find an example in dialog.3, but it was in the form \fBprintf(3)\fP-like format): which looses the cross-reference.

0mp accepted this revision.Jun 19 2020, 4:34 PM

Very nice, OK from me.

seq/seq.1
136

Nice!

170

Works for me! Thanks a lot!

This revision is now accepted and ready to land.Jun 19 2020, 4:34 PM
fernape closed this revision.Jun 20 2020, 11:31 AM
fernape marked 2 inline comments as done.

Done in r362435

Thanks for reviewing!

Revision Contents
Changeset List

PathSize
seq/
40 lines

Diff 72614

View Options

seq/seq.1

Loading...