Create a manual page for beinstall.8

[0mp]

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

[will]

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]

OK from manpages.

[0mp]

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.

[will]

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]

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

[brd]

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]

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]

This looks good to me.

[0mp]

Thanks a lot for reviewing.

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