Page MenuHomeFreeBSD

Create a manual page for beinstall.8
ClosedPublic

Authored by 0mp on Aug 16 2018, 10:26 AM.

Details

Summary

It's mostly a summary of the comments already present in the actual script.

I am not sure about a few things though:

  • Should this manpage be installed?
  • I am not sure how to describe those kernel and world flags.
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.Aug 16 2018, 10:26 AM
will added a comment.Aug 16 2018, 12:01 PM

Hi Mateusz,

So, the main reason beinstall currently doesn't have a man page is because it's not really appropriate to install. It _requires_ the source tree, because it requires either etcupdate or mergemaster, which in turn require the source tree.

Furthermore, I anticipate beinstall will evolve as an extension to pkg once base packages are up and running, and after that point it will only be of interest to those who don't want to use pkg to manage their base system.

If we were going to support those use-cases, the only other way I could see beinstall being useful would be as an integrated part of freebsd-update, since it has its own mechanism for handling configuration file updates.

I don't have strong feelings against installing the tool or man page, but I don't see the point.

bcr added a comment.Aug 16 2018, 12:49 PM

OK from manpages.

0mp added a comment.Aug 16 2018, 1:04 PM

Alright, those are fair reasons, @will.

I guess that the main reason of creating a manual page for beinstall.sh is having it show up search browsers and manpage browsers like http://man.freebsd.org/. Having a manpage for a command makes it more discoverable.

If you find this argument strong enough to install this manpage then we might consider committing these changes. Otherwise we should probably abandon this revision.

brd accepted this revision.Aug 16 2018, 1:16 PM
This revision is now accepted and ready to land.Aug 16 2018, 1:16 PM
will accepted this revision.Aug 16 2018, 1:22 PM
In D16742#356017, @0mp wrote:

Alright, those are fair reasons, @will.
I guess that the main reason of creating a manual page for beinstall.sh is having it show up search browsers and manpage browsers like http://man.freebsd.org/. Having a manpage for a command makes it more discoverable.
If you find this argument strong enough to install this manpage then we might consider committing these changes. Otherwise we should probably abandon this revision.

Ok. To answer your earlier question, I would suggest a reference to build(7) for those looking for help on flags for installing world/kernel. Presuming you add that, this looks good to me.

0mp updated this revision to Diff 46777.Aug 16 2018, 2:29 PM
  • Reference build(7).
  • Sort environmental variables alphabetically.
  • Fix some minor style issues.

I'll look into how to get this manpage to install.

I wonder if we could just move this manual page to share/man/man8/ and install it together with other section 8 manuals.

This revision now requires review to proceed.Aug 16 2018, 2:29 PM
brd added a comment.Aug 16 2018, 2:33 PM
In D16742#356074, @0mp wrote:
  • Reference build(7).
  • Sort environmental variables alphabetically.
  • Fix some minor style issues.

I'll look into how to get this manpage to install.
I wonder if we could just move this manual page to share/man/man8/ and install it together with other section 8 manuals.

Yeah, that is probably the best way.

0mp updated this revision to Diff 46780.Aug 16 2018, 3:23 PM

Changes:

  • Move beinstall to share/man/man8 and modify the local makefile to install the manpage.
  • Improve the description based on the message from https://reviews.freebsd.org/rS302977.
  • Reference development(7).
  • Extend HISTORY & AUTHORS sections.
will accepted this revision.Aug 18 2018, 9:27 PM

This looks good to me.

This revision is now accepted and ready to land.Aug 18 2018, 9:27 PM
0mp requested review of this revision.Aug 19 2018, 10:52 PM
0mp added reviewers: mat, krion.
0mp added subscribers: krion, mat.

Thanks a lot for reviewing.

@mat, @krion, may I ask for your approval to commit this?

krion accepted this revision.Aug 20 2018, 9:20 AM
This revision is now accepted and ready to land.Aug 20 2018, 9:20 AM
This revision was automatically updated to reflect the committed changes.