[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[^zsh] users instead? I think this would be my preferred "solution".

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

[kairveeehh]

Is this issue up? also can we not use this which was mentioned the way earlier , further over the readme I think copying is allowed already and it works fine , please correct me if i am missing smt on it

[jandubois]

Is this issue up?

I think so, but there doesn't seem to be consensus about what to do, so it seems stalled.

also can we not use this which was mentioned the way earlier

I have no idea what that means.

further over the readme I think copying is allowed already and it works fine , please correct me if i am missing smt on it

Yes, copying works fine; the issue is that the copied text does not necessarily work when pasted into a zsh session because # is not treated as a comment by default in interactive sessions.

[nirs]

We can change the example like this - it explains the steps, and the steps can be run easily without typing anything.

From binary

Get the latest release version:

export VERSION="$(curl -fsSL https://api.github.com/repos/lima-vm/socket_vmnet/releases/latest | jq -r .tag_name)"
export 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}"

Optionaly, attest the GitHub Artifact Attestation using GitHub's gh command (https://cli.github.com)

gh attestation verify --owner=lima-vm "${FILE}"

Optionaly, 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

[jandubois]

We can change the example like this - it explains the steps, and the steps can be run easily without typing anything.

Works for me. It requires a bunch of clicking and pasting instead of copying it all at once, but I think that is fine.

[kairveeehh]

thanks for the help , will work on this in the suggested manner