Following documentation for editing the Gemfile breaks Logstash

So from looking around I eventually stumbled upon FATAL error after updating to 7.16.1 - #12 by maltewhiite and it turns out that is how to make Logstash work again after editing the Gemfile. I do this after editing the Gemfile:

$ cd /usr/share/logstash/
$ bin/ruby vendor/bundle/jruby/2.5.0/bin/bundle lock

That makes Logstash work again. I would still like to understand the discrepancy between the documentation which says edit the Gemfile and then carry on as normal and my experience that editing the Gemfile totally breaks Logstash, so if anyone is able to explain that, that would be good.

I also found that after the Gemfile was modified and Logstash wasn't just totally broken, trying to install a plugin failed (with an error I've already lost, sorry) and that to make plugin installation work it's necessary to precede the install command with a definition of LOGSTASH_PACK_URL e.g.

$ LOGSTASH_PACK_URL=http://localhost:1234 /usr/share/logstash/bin/logstash-plugin install pluginnamehere

(Nothing is listening on localhost:1234 it seems a value just has to be set.) I

Found at Airgapped install of plugin fails trying to access artifacts.elastic.co - #5 by SebastianThorn