bhyvectl.8: Polish

[ziaee]

Summary

bhyvectl.8: Polish

+ Add how to find open VMs in the example, linking `apropos Pa=/dev/vmm`
+ Move note about additional bhyve options after options for flow
+ Reclaim some space by shortening <filename> to <file>
+ Align options list width, tested at MANWIDTH 59 and 80
+ Remove unnecessary roff quoting and break long lines, tag SPDX

MFC after:      3 days

[ziaee]

alphabetize the options, except leaving --vm= first since it is always
first.

[markj]

usr.sbin/bhyvectl/bhyvectl.8

57

Since --checkpoint is not compiled in by default, it feels wrong to list it so prominently. Perhaps move it to a separate section or after the other options?

74–75

Same with --suspend.

[ziaee]

Revert line organization. I got distracted thinking about how we should
do this, and circling back after I think this note in the example is
important and helpful.

[ziaee]

Ping

[mhorne]

The subject of line-breaks is infinitely bikesheddable, so I will state my opinion here once more and then never again.

Our doc style guide requires one-sentence-per-line. mandoc -Tlint enforces an 80-byte line-width. I find the semantic line breaks silly. If that's your preference, cool, but you may find that these issues of style will slow down the more consequential changes you wish to make.

To highlight this fact, I must continue to withhold my Reviewed-by on this one.

usr.sbin/bhyvectl/bhyvectl.8

104–105

This block adheres to one-sentence-per-line, and is below 80 characters in width. It will not affect rendered output. Changing it amounts to needless churn.

[ziaee]

Xterm and vt both default to 80x25. Vi puts an 8 character gutter. Further, tracking current tightly, graphics drivers are always broken.

This is significantly less fun if I have 3 characters in the gutter every line and can see half as many lines on a screen.
Granted we have no doc committers, and I am very active and want to work on the doc, and my "trespass" is that I want to format it in a way that is friendly to our most basic and stable tools because everything else breaks, I think that is extremely reasonable.

Edit: I do not think it is infinitely bikesheddable. This is compatibility with the defaults in base.

[ziaee]

• Revert making roff lines look decent on FreeBSD.

[danfe]

@ziaee wrote:

Vi puts an 8 character gutter [or "takes exactly 8 characters off the side", per D50410]

How do you mean (takes for what, from which side)? Mine doesn't take anything from 80 chars. Could it be that you misconfigured it?

[ziaee]

vi takes 8 characters on the left side of the screen anytime lines are numbered. Cat and ed also do.

[danfe]

@ziaee wrote:

[vi, cat, and ed take] 8 characters on the left side of the screen anytime lines are numbered.

Neither of these programs have numbered lines enabled by default, that would be preposterous. Any decorations you might have enabled in your text editor shall not be accounted for in this argument or assumption thereof be reflected in the documentation.

[ziaee]

Is the way the changes are wrapped in this file preposterous?

[ziaee]

To follow my mentors instructions and ask why; why are cat -n, ed ,$n and vi set nu unreasonable workflows?

[mhorne]

Approved, please go ahead and commit this.

In D48401#1151034, @ziaee wrote:

To follow my mentors instructions and ask why; why are cat -n, ed ,$n and vi set nu unreasonable workflows?

They are not unreasonable in themselves, but every choice carries its implications.

I think the assumption underlying your question is that the defaults (e.g. vi in an 80x25 vt(4) terminal) should be practically usable for your particular purpose. This is simply not the case.

If you want to use FreeBSD as a network router, you need to configure it.
If you want to use it as a desktop, you need to configure it, differently.
If you want to use it as a home media appliance, you can! And you will need to configure it.

Herein lies the beauty and simplicity of FreeBSD: it's configurability. You will find folks who use the system for all kinds of purposes, and they do it in their way, according to their tastes. We aim for sensible defaults, but the real power lives in how easily the defaults can be changed to meet your needs.

So, if you want to use FreeBSD to work on documentation, and you are choosing to limit yourself to base-system tools and defaults, you may find this to be a slow or impractical approach. My only response to this is: configure your system appropriately!

There is a lot to be learned from doing things "the old-fashioned way" and despite how it may sound I am an advocate for this (you would not find me here if not). I admire your desire to explore the basic and historic tools. But this is for your personal development and learning; do not assume that others should follow your lead when for them it is a dead-end. When your desire to do things one particular way creates more work for others, that is where I have a big problem with it.

I hope this clears up my position a bit.

[ziaee]

It does and I appreciate your patience and am sorry for conflicting with you.