[DRE-maint] Bug#945056: jekyll: terrible failure mode when run by novice

[G. Branden Robinson]

Package: jekyll
Version: 3.8.3+dfsg-4
Severity: normal

Dear Maintainer,

*** Reporter, please consider answering these questions, where appropriate ***

   * What led up to the situation?

I'm trying to debug why some Markdown didn't convert to HTML properly on
a jekyll-generated website.  So that I don't have to shoot in the dark
while troubleshooting it, I wanted to install a local copy of Jekyll so
I could test and evaluate my fixes/workarounds.

   * What exactly did you do (or not do) that was effective (or
     ineffective)?

With no Ruby experience, I ran "apt install jekyll".

I then ran "man jekyll".  The page is terse to a fault and the synopsis
is nonstandard.  It is scarcely better than the output of "help2man".
It does not document the syntax "jekyll new $SITENAME", which I had to
find via Web search.  (I found a better source later; see below.)

   * What was the outcome of this action?

[wide terminal required]

$ jekyll
Traceback (most recent call last):
        10: from /usr/bin/jekyll:9:in `<main>'
         9: from /usr/lib/ruby/vendor_ruby/jekyll/plugin_manager.rb:50:in `require_from_bundler'
         8: from /usr/share/rubygems-integration/all/gems/bundler-1.17.3/lib/bundler.rb:107:in `setup'
         7: from /usr/share/rubygems-integration/all/gems/bundler-1.17.3/lib/bundler/runtime.rb:20:in `setup'
         6: from /usr/share/rubygems-integration/all/gems/bundler-1.17.3/lib/bundler/runtime.rb:108:in `block in definition_method'
         5: from /usr/share/rubygems-integration/all/gems/bundler-1.17.3/lib/bundler/definition.rb:226:in `requested_specs'
         4: from /usr/share/rubygems-integration/all/gems/bundler-1.17.3/lib/bundler/definition.rb:237:in `specs_for'
         3: from /usr/share/rubygems-integration/all/gems/bundler-1.17.3/lib/bundler/definition.rb:170:in `specs'
         2: from /usr/share/rubygems-integration/all/gems/bundler-1.17.3/lib/bundler/spec_set.rb:85:in `materialize'
         1: from /usr/share/rubygems-integration/all/gems/bundler-1.17.3/lib/bundler/spec_set.rb:85:in `map!'
/usr/share/rubygems-integration/all/gems/bundler-1.17.3/lib/bundler/spec_set.rb:91:in `block in materialize': Could not find ffi-1.9.25 in any of the sources (Bundler::GemNotFound)

   * What outcome did you expect instead?

A diagnostic message that:

1. Is not an interpreter traceback.  "jekyll" is a command-line utility
and its communication should be targeted to users, not programmers.

2. Does not suggest a package dependency problem, in turn implying that
Debian screwed up its stable release.

3. Does not pair the grave accent with the apostrophe.  This doesn't
look good in any font that people actually use.  See
https://www.gnu.org/prep/standards/html_node/Quote-Characters.html .
This ugly typography simply adds insult to injury.

The interpreter takes all that time to spin up and doesn't actually
appear to spend any of it sanity-checking the command-line arguments,
the environment, or the file system for signs that it is being run by a
newcomer.

The good news is that "jekyll --help" actually documents (briefly) the
subcommands.

The bad news is that "jekyll --help" takes over 7 seconds to run on a
six-core i5-8500 at 3GHz:

$ time jekyll --help && uptime
jekyll 3.8.3 -- Jekyll is a blog-aware, static site generator in Ruby
[...]
real    0m7.476s
user    0m0.304s
sys     0m0.021s
 15:25:17 up  1:08,  4 users,  load average: 0.50, 0.49, 0.46

"jekyll --help" produces 1255 characters of output.  Rounding to 7
seconds, that gives 179.2 characters per second.

Fortunately, that is faster then Thompson & Ritchie's 110 baud ASR 33
Teletypes.

But not by much.

The Ruby ecosystem is making a poor first impression on me.

-- System Information:
Debian Release: 10.2
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.19.0-6-amd64 (SMP w/6 CPU cores)
Locale: LANG=C, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=en_AU:en (charmap=UTF-8)
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Versions of packages jekyll depends on:
ii  bundler                     1.17.3-3
ii  ruby                        1:2.5.1
ii  ruby-addressable            2.5.2-1
ii  ruby-classifier-reborn      2.2.0-1
ii  ruby-colorator              1.1.0-1
ii  ruby-em-websocket           0.5.1-2
ii  ruby-i18n                   1.5.3-1
ii  ruby-jekyll-coffeescript    1.0.1-2
ii  ruby-jekyll-feed            0.3.1-1
ii  ruby-jekyll-gist            1.5.0-1
ii  ruby-jekyll-paginate        1.1.0-1
ii  ruby-jekyll-sass-converter  1.5.2-1
ii  ruby-jekyll-watch           2.0.0-1
ii  ruby-kramdown               1.17.0-1
ii  ruby-launchy-shim           2.3.0.1
ii  ruby-liquid                 4.0.1-1
ii  ruby-mercenary              0.3.6-1
ii  ruby-mime-types             3.2.2-1
ii  ruby-pathutil               0.16.1-1
ii  ruby-pygments.rb            1.2.0-4
ii  ruby-rdiscount              2.1.8-1+b5
ii  ruby-redcarpet              3.4.0-4+b1
ii  ruby-rouge                  3.3.0-1
ii  ruby-safe-yaml              1.0.4-2
ii  ruby-toml                   0.2.0-3
ii  xdg-utils                   1.1.3-1

Versions of packages jekyll recommends:
pn  ruby-mysql      <none>
ii  ruby-sequel     5.15.0-1
pn  ruby-sequel-pg  <none>

jekyll suggests no packages.

-- no debconf information
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://alioth-lists.debian.net/pipermail/pkg-ruby-extras-maintainers/attachments/20191119/3657740a/attachment.sig>