Consistency issues (?) leading to difficulties in getting started

[sogaiu]

Describe the error
Information in some documents appears...not quite aligned...and resulted in some wandering around (though with ultimate success).

Affected documents

• README.md
• Setting up Ruby Wiki Page
• Development Environment

Additional context
I'm using Void Linux.

---

There are some points that I think could be improved with respect to consistency of the documentation in the following areas:

• Setup of Ruby + Gems information
• Specifics of some instructions in the Testing Rouge section of the README

---

Regarding setting up Ruby + Gems:

The Development Environment document currently states:

There are a number of excellent resources out there explaining how to do these things. For Ruby, we recommend the official documentation and for Git, GitHub's documentation.

The Setting up Ruby Wiki page currently states:

If you don't already have a ruby setup on your machine, here's a quick guide to get you up and running.

Based on the dates of the documents, I guess one ought to favor the Development Environment document. Following its instructions (roughly, install ruby using a package manager's ruby package + bundle install) initially resulted in failure for me, so I tried the Wiki page's instructions which also failed for me on the first attempt.

For the former method (dev env -> ruby package), nio4r's build failed (via the bundle install step), and it appears that at least for Void Linux, I needed to install the ruby-devel package (I decided to try this after turning up this SO answer). Installing that yielded success.

I don't know if this is purely a Void Linux issue, but if not, may be it's worth a word or two in the Development Environment doc about possibly needing a dev / devel version of a ruby package as that information does not appear to be present at the official documentation for installing Ruby.

For the latter method (wiki page -> ry), it appears I needed libyaml installed, but this was not mentioned on the Wiki page, though I did see the text:

Note: this requires autoconf and standard C build tools to be available.

(Perhaps when the Wiki page was created, libyaml wasn't required. Now though, a link to this might be helpful.)

Not being too familiar with ry, it took me a while to figure out that a failed installation of ruby via ry required me to remove the remains before trying again (after installing libyaml (or may be it was libyaml-devel?)).

Perhaps the Wiki page could be amended or may be removed?

---

Regarding the Testing Rouge section of the README, it currently states:

you can test the core of Rouge simply by running rake (no bundle exec required).

This results in an error here:

$ rake
rake aborted!
Gem::LoadError: You have already activated rake 13.0.6, but your Gemfile requires rake 13.1.0. Prepending `bundle exec` to your command may solve this.
/usr/lib/ruby/3.2.0/bundler/runtime.rb:304:in `check_for_activated_spec!'
/usr/lib/ruby/3.2.0/bundler/runtime.rb:25:in `block in setup'
/usr/lib/ruby/3.2.0/bundler/spec_set.rb:165:in `each'
/usr/lib/ruby/3.2.0/bundler/spec_set.rb:165:in `each'
/usr/lib/ruby/3.2.0/bundler/runtime.rb:24:in `map'
/usr/lib/ruby/3.2.0/bundler/runtime.rb:24:in `setup'
/usr/lib/ruby/3.2.0/bundler.rb:171:in `setup'
/usr/lib/ruby/3.2.0/bundler/setup.rb:10:in `block in <top (required)>'
/usr/lib/ruby/3.2.0/bundler/ui/shell.rb:159:in `with_level'
/usr/lib/ruby/3.2.0/bundler/ui/shell.rb:111:in `silence'
/usr/lib/ruby/3.2.0/bundler/setup.rb:10:in `<top (required)>'
<internal:/usr/lib/ruby/3.2.0/rubygems/core_ext/kernel_require.rb>:85:in `require'
<internal:/usr/lib/ruby/3.2.0/rubygems/core_ext/kernel_require.rb>:85:in `require'
/home/user/src/rouge/Rakefile:3:in `<top (required)>'
/usr/lib/ruby/gems/3.2.0/gems/rake-13.0.6/exe/rake:27:in `<top (required)>'
(See full trace by running task with --trace)

though the instructions from the Development Environment document: bundle exec rake work fine.

I also encountered difficulty with:

To test a lexer visually, run rackup from the top-level working directory

Invoking rackup by itself yields:

$ rackup
bash: rackup: command not found

here, though bundle exec rackup as suggested in the Development Environment document work fine.

Perhaps the Testing Rouge section of the README could be amended or may be removed?

I don't know if the TEST=... tip or the ?debug=1 tip exist elsewhere (they seem valuable and currently are present in the Testing Rouge section)...I didn't find them here at least.