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

Update the patch after recent changes to ports.7.

0mp edited the test plan for this revision. (Show Details)
0mp added reviewers: krion, mat.
mat added 1 blocking reviewer(s): manpages.

No idea what this is/does.

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

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?

This revision is now accepted and ready to land.Aug 16 2018, 5:15 AM
This revision was automatically updated to reflect the committed changes.
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.

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