[zsh] Binary install instructions cannot be copied and pasted from the readme

[nirs]

One of the useful features of github markdown is that we can copy in one click a code block and paste it in the shell to run all the commands. This is used by many project to make install much easier.

Unfortunately this does not work with current binary install steps:
https://github.com/lima-vm/socket_vmnet?tab=readme-ov-file#from-binary

Example run:

% VERSION="$(curl -fsSL https://api.github.com/repos/lima-vm/socket_vmnet/releases/latest | jq -r .tag_name)"
FILE="socket_vmnet-${VERSION:1}-$(uname -m).tar.gz"

# Download the binary archive
curl -OSL "https://github.com/lima-vm/socket_vmnet/releases/download/${VERSION}/${FILE}"

# (Optional) Attest the GitHub Artifact Attestation using GitHub's gh command (https://cli.github.com)
gh attestation verify --owner=lima-vm "${FILE}"

# (Optional) Preview the contents of the binary archive
tar tzvf "${FILE}"

# Install /opt/socket_vmnet from the binary archive
sudo tar Cxzvf / "${FILE}" opt/socket_vmnet
quote> 

Looks like unmatched single-quote, maybe the GitHub's?

[jandubois]

Looks like unmatched single-quote, maybe the GitHub's?

Yes, because in interactive zsh # is not a comment; you have to enable it explicitly, e.g. with set -k.

% # This is a comment
zsh: command not found: #
% set -k
% # This is a comment

[nirs]

Should we add set -k to the command?

Tried it an it does not work, but we can do:

echo Install /opt/socket_vmnet from the binary archive
sudo tar Cxzvf / "${FILE}" opt/socket_vmnet

Too ugly 👎

I think we need to remove the comments and create something that works for copy and paste.

Also some lines are not needed in the instructions like:

# (Optional) Preview the contents of the binary archive
tar tzvf "${FILE}"

[jandubois]

We can use either true or the null command : to include comments, hoping it doesn't confuse the casual shell user:

true This is a comment
: This one is too. It is still parsed as a commandline, so "quotes" must match etc.

[nirs]

true is nice hack but looks confusing.

[jandubois]

I don't like the idea of removing the comments; the point of documentation is to explain stuff; making it more convenient to copy & paste is a secondary goal, but should never happen at the expense of clarity.

I think true and : are confusing for some users, so I think echo is the only option to keep the snippets compatible for zsh users that don't have interactive comments enabled.

Maybe we can just add a footnote for zsh¹ users instead? I think this would be my preferred "solution".

Footnotes

1. If you want to copy & paste the install instructions in zsh, make sure you have interactive comments enabled, with set -k or setopt interactivecomments. ↩