Page MenuHomeFreeBSD

seq(1): complete EXAMPLES section
ClosedPublic

Authored by fernape on Jun 3 2020, 11:21 AM.
Tags
None
Referenced Files
Unknown Object (File)
Dec 22 2023, 9:49 PM
Unknown Object (File)
Nov 8 2023, 6:30 PM
Unknown Object (File)
Oct 19 2023, 10:20 AM
Unknown Object (File)
Oct 7 2023, 5:21 PM
Unknown Object (File)
Sep 23 2023, 10:48 PM
Unknown Object (File)
Sep 3 2023, 2:01 PM
Unknown Object (File)
Jun 24 2023, 7:02 AM
Unknown Object (File)
May 8 2023, 5:38 AM

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

Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

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.

Addressing bcr@ comments:

  • Add colon (:) at the end of every description
  • Add (including) to signify this is a closed range at both ends

Excellent, good to go now. Thank you!

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 inline comments.
seq/seq.1
152

The increment is 0.05

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

fernape added inline comments.
seq/seq.1
152

Nice catch!

Do we need to update .Dd?

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.

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.

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

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 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.

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 marked 2 inline comments as done.

Done in r362435

Thanks for reviewing!