vmadm(8) manpage cleanup and enhancement

[gemelen]

Changes:

• rewrite double "the" occurrances
• add signatures and descriptions for commands kill,reprovision,receive and send that exist in vmadm command and its help output, but are missing in the manpage

Where it was possible or relevant, I've tried to provide a command explanation as it could be found in the issues tracker or in the sources.

[danmcd]

We had historically left kill, receive, send, and reprovision undocumented because we would not necessarily support people who used these in practice, and because these never received the full amount of testing required to be fully documented, but we needed them for Triton internals.

See OS-8518 for an example of why these are undocumented. IF we decide to accept this PR and document things, these features need to be labelled as unstable/unsupported/etc. I'm still not sure if we should accept these as documented or not.

[danmcd]

Also see https://smartos.topicbox.com/groups/smartos-discuss/T8882ca81b8348adf-M19711360b35d81cd2f58cd02/smartos-release-20240905-zemo (i.e. when OS-8518 appeared for the first time).

[gemelen]

Thanks for the additional context.

I understand this point and overall distinction between documented/stable and undocumented/(internal?) interfaces.

My intention to cover them is mainly driven by the discrepancy between vmadm's help output which explicitely points "For more detailed information on the use of this command,type 'man vmadm'" and the absence in the manpage. From the user's point of view it's unclear why it is that way.

Maybe a comment in the vmadm source or help output would be enough to cover that.

On the other hand, I'd suggest that at least send/receive are worth being added, as they are still useful even with a single SmartOS instance and oneshot zone migrations.

[danmcd]

Thanks for the additional context.

I understand this point and overall distinction between documented/stable and undocumented/(internal?) interfaces.

My intention to cover them is mainly driven by the discrepancy between vmadm's help output which explicitely points "For more detailed information on the use of this command,type 'man vmadm'" and the absence in the manpage. From the user's point of view it's unclear why it is that way.

Maybe a comment in the vmadm source or help output would be enough to cover that.

Pardon my delay. The four you make man page changes for should trigger, IMHO:

• Being documented in the man page as "UNSTABLE", maybe even having an "INTERFACE STABILITY" section as well.
• The help output, per what you say, grouping or indicating these as "UNSTABLE".

You pulled a thread that's going to unravel a larger piece of knitting, unfortunately. It's not a bad idea to have these documented, but to avoid "documented" == "supported or at least stable" assumptions, we need to be clear, and I'm not sure if there are already-documented things that need such classification.