Page MenuHomeFreeBSD

Tidy up ports.7 manual
ClosedPublic

Authored by 0mp on May 8 2018, 11:32 AM.

Details

Summary

Changes:

  • Use .Dq Li for inline commands.
  • Reference pkg(8) is not installed by default. pkg(7) is. Reference pkg(7) first and then pkg(8) in additional documentation.
  • Fix some style problems.
  • Reword some sentences.
  • Reference additional documentation.
Test Plan
  • igor ok
  • mandoc -Tlint ok

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

0mp created this revision.May 8 2018, 11:32 AM
0mp updated this revision to Diff 45535.Jul 19 2018, 12:31 PM

Update the patch after recent changes to ports.7.

0mp edited the summary of this revision. (Show Details)Jul 19 2018, 12:36 PM
0mp edited the test plan for this revision. (Show Details)
0mp added reviewers: krion, mat.
mat accepted this revision.Jul 20 2018, 11:34 AM
mat added 1 blocking reviewer(s): manpages.

No idea what this is/does.

bjk added a subscriber: bjk.Jul 24 2018, 12:46 AM

Can you remind me why the .Dq Li is supposed to be better for inline commands?

0mp added a comment.Jul 31 2018, 1:27 AM
In D15350#348437, @bjk wrote:

Can you remind me why the .Dq Li is supposed to be better for inline commands?

As fair as I know we tend to use Dq Li instead of Nm make Cm build-like for inline commands. This is the style we follow in make.conf.5, src.conf.5, mqueufs.5. The Nm-based formatting is used in rc.conf.5 and find.1 on the other hand.

AFAICT, Dq Li is a more popular way to format commands.

The argument which is in favor of Dq Li is that we tend to make commands in Examples sections literal. We very rarely add Nm-like formatting to examples. Hence for the sake of consistency I'm proposing this change from Nm ... to Dq Li. ๐Ÿ˜„

What do you think about it, @bjk?

0mp added a reviewer: bcr.Aug 15 2018, 1:55 PM
eadler accepted this revision.Aug 16 2018, 5:15 AM
This revision is now accepted and ready to land.Aug 16 2018, 5:15 AM
krion accepted this revision.Aug 16 2018, 6:53 AM
This revision was automatically updated to reflect the committed changes.
bjk added a comment.Aug 16 2018, 2:55 PM
In D15350#350715, @0mp wrote:
In D15350#348437, @bjk wrote:

Can you remind me why the .Dq Li is supposed to be better for inline commands?

As fair as I know we tend to use Dq Li instead of Nm make Cm build-like for inline commands. This is the style we follow in make.conf.5, src.conf.5, mqueufs.5. The Nm-based formatting is used in rc.conf.5 and find.1 on the other hand.
AFAICT, Dq Li is a more popular way to format commands.
The argument which is in favor of Dq Li is that we tend to make commands in Examples sections literal. We very rarely add Nm-like formatting to examples. Hence for the sake of consistency I'm proposing this change from Nm ... to Dq Li. ๐Ÿ˜„
What do you think about it, @bjk?

I see this is basically overcome by events, but thank you for the explanation/research -- your proposal seems reasonable to me.

0mp added a comment.Aug 16 2018, 3:26 PM
In D15350#356103, @bjk wrote:
In D15350#350715, @0mp wrote:
In D15350#348437, @bjk wrote:

Can you remind me why the .Dq Li is supposed to be better for inline commands?

As fair as I know we tend to use Dq Li instead of Nm make Cm build-like for inline commands. This is the style we follow in make.conf.5, src.conf.5, mqueufs.5. The Nm-based formatting is used in rc.conf.5 and find.1 on the other hand.
AFAICT, Dq Li is a more popular way to format commands.
The argument which is in favor of Dq Li is that we tend to make commands in Examples sections literal. We very rarely add Nm-like formatting to examples. Hence for the sake of consistency I'm proposing this change from Nm ... to Dq Li. ๐Ÿ˜„
What do you think about it, @bjk?

I see this is basically overcome by events, but thank you for the explanation/research -- your proposal seems reasonable to me.

Thanks, @bjk. :)