From 8fabc4015c6b67e558b62e1ad0d17fa7b02aec7a Mon Sep 17 00:00:00 2001 From: janicemhdc <54671493+janicemhdc@users.noreply.github.com> Date: Thu, 29 Aug 2019 11:33:22 -0400 Subject: Update README.adoc Add information about common Mac issue with Ruby and how to fix it --- README.adoc | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.adoc b/README.adoc index 2cdd1c1f..6a3d55d7 100644 --- a/README.adoc +++ b/README.adoc @@ -150,6 +150,17 @@ Then, install the gem from RubyGems.org using the following command: $ gem install asciidoctor-pdf --pre +If you're on a Mac and get the following error: + +``` +ERROR: While executing gem ... (Gem::FilePermissionError) + You don't have write permissions for the /Library/Ruby/Gems/2.x.x directory. +``` + +Then your currently installed version of Ruby is owned by Apple and part of the system code. While you could override this ownership, a better practice is to install your own local copy using `brew install ruby` or the installation mechanism of your choice. + +Your non-system version of Ruby will likely live at `/usr/local/opt/ruby/bin` - you may need to explictly add that to your path. + If you want to syntax highlight source listings, you'll also want to install Rouge, Pygments, or CodeRay. Choose one (or more) of the following: -- cgit v1.2.3 From 12a1e540a5361550141c2f90e82e6450fdee6f8f Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Fri, 30 Aug 2019 01:33:11 -0600 Subject: move installation troubleshooting to dedicated section; recommend the use of RVM --- README.adoc | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/README.adoc b/README.adoc index 6a3d55d7..511b10e2 100644 --- a/README.adoc +++ b/README.adoc @@ -150,16 +150,38 @@ Then, install the gem from RubyGems.org using the following command: $ gem install asciidoctor-pdf --pre -If you're on a Mac and get the following error: +=== Installation Troubleshooting -``` +If you get a permission error while installing the gem, such as the one below, it's likely you're attempting to install the gem directly into your system. +Installing gems for tech writing directly into your system is not recommended. + +.Permission error when attempting to install as a system gem +.... ERROR: While executing gem ... (Gem::FilePermissionError) You don't have write permissions for the /Library/Ruby/Gems/2.x.x directory. -``` +.... + +A better practice (and one that will ensure your sanity) is to ignore any version of Ruby installed on your system and use https://rvm.io[RVM] to manage the Ruby installation instead. +The benefit of this approach is that a) Ruby is guaranteed to be set up correctly, b) installing gems will in no way interfere with the operation of your system, and c) any bin scripts provided by the installed gems will be available on your PATH. +All files are managed in user space (aka your home or user directory). +If something gets messed up, you can simply remove the `$HOME/.rvm` folder and start over. + +To learn how to install RVM, follow the https://asciidoctor.org/docs/install-asciidoctor-macos/#rvm-procedure-recommended[RVM installation procedure] covered in the Asciidoctor documentation. +Once you have installed RVM and used it to install Ruby, make sure to activate the Ruby managed by RVM using `rvm use default` or a specific Ruby version like `rvm use 2.6`. +(You'll need to do this each time you open a new terminal). + +After installing the gem, you can see where it was installed using the following command: + + $ gem which asciidoctor-pdf + +To see where the bin script is located, use this command: + + $ command -v asciidoctor-pdf -Then your currently installed version of Ruby is owned by Apple and part of the system code. While you could override this ownership, a better practice is to install your own local copy using `brew install ruby` or the installation mechanism of your choice. +Both paths should be underneath the [.path]_.rvm_ directory. +If not, check your RVM setup. -Your non-system version of Ruby will likely live at `/usr/local/opt/ruby/bin` - you may need to explictly add that to your path. +==== Install a Syntax Highlighter (optional) If you want to syntax highlight source listings, you'll also want to install Rouge, Pygments, or CodeRay. Choose one (or more) of the following: -- cgit v1.2.3