Installation appears to succeed but asciidoctor-pdf is not available

[janicemhdc]

After installing a local version of Ruby on my Mac (I originally got an error because of the system version of Ruby), I installed asciidoctor-pdf following the instructions in the README:

$ gem install asciidoctor-pdf --pre
Successfully installed asciidoctor-pdf-1.5.0.beta.2
Parsing documentation for asciidoctor-pdf-1.5.0.beta.2
Done installing documentation for asciidoctor-pdf after 1 seconds
1 gem installed

However, when I try to use it or check that it's working, it doesn't actually appear to be installed:

$ asciidoctor-pdf --version
-bash: asciidoctor-pdf: command not found

[mojavelinux]

This is a classic Ruby installation problem. You are installing into one location, but your PATH is pointing to another.

I strongly recommend studying the advice on this page: https://asciidoctor.org/docs/install-asciidoctor-macos/#rvm-procedure-recommended

I assure you that if you use RVM, all your Ruby woes will go away. RVM sets up a proper, clean Ruby environment in user space (your home directory) with all the necessary paths and environment variables set up correctly. (Just don't forget to run rvm use 2.6 so RVM is activated).

[mojavelinux]

After I get RVM set up, here's what it reports:

$ echo $GEM_PATH
/home/dallen/.rvm/gems/ruby-2.6.3@runtime:/home/dallen/.rvm/gems/ruby-2.6.3@global

$ echo $PATH
/home/dallen/.rvm/gems/ruby-2.6.3@runtime/bin:/home/dallen/.rvm/gems/ruby-2.6.3@global/bin:/home/dallen/.rvm/rubies/ruby-2.6.3/bin:/home/dallen/.rvm/bin:...

Notice how it's looking in the Ruby installation that RVM set up. That's where it's probably going wrong on your system.

[janicemhdc]

I feel like we're playing musical chairs with comments. that said...

Your mac instructions on the main asciidoctor.org page tell folks to install asciidoctor using Homebrew so that's exactly what I did. If I'd been told to use RVM and sent to those instructions I would have followed them.

[janicemhdc]

BTW, I did add my local ruby install to my PATH and if it didn't see it wouldn't it still be giving the permission errors from the Apple-owned default Ruby?

[mojavelinux]

The page clearly says "recommended" next to the RVM section. It also starts out by saying "The safest and most reliable choice is RVM." I stand by that statement.

[mojavelinux]

You should never install gems into the system Ruby (unless you are installing gems that are to be used by other system applications). It's best just to assume that the system doesn't provide Ruby. I've worked that way for almost a decade and it has never failed me.

[janicemhdc]

I'm talking about the main asciidoctor.org page which includes installation instructions for Mac that specify only Homebrew and do not link to or mention that page. I never saw that specific installation page because it did not occur to me to look for alternate instructions once I was presented with instructions on the main asciidoctor.org page.

and below that:

[mojavelinux]

Yes, but it mentions nothing about gem install in that section. If you use gem install, then you need to use RVM (to be guaranteed success).

[mojavelinux]

Besides, those instructions are for the asciidoctor gem, not the asciidoctor-pdf gem. And since you currently need to use gem install to get the asciidoctor-pdf gem, then you need RVM.

[mojavelinux]

We're also well aware that the home page of asciidoctor.org is historically biased towards the core gem and needs to be updated. That's what we're in the process of doing right now.

[janicemhdc]

You keep sending me to other instructions for the asciidoctor gem to tell me about asciidoctor-pdf so it's not fair for you to complain when I reference them. The upshot is that the current instructions for asciidoctor are inconsistent and the current instructions for asciidoctor-pdf are incomplete. I was trying to be helpful by providing an update to the PDF instructions earlier (granted, I was premature) but I will just delete my PR and move on.

[mojavelinux]

I'm not saying that at all. Please don't delete. I'm happy to update an incorporate. I understand you are trying to help.

[mojavelinux]

I'm just trying to get you on the right path. And the right path is RVM.

[mojavelinux]

We've already established that the installation instructions need updating. That point has been taken.

What I would like to do is use the space in the README to incorporate the troubleshooting instructions. However, instead of it being biased for macOS, it should be focused on RVM as the solution (because it's the same problem on Linux). Unfortunately, the only page we have that talks specifically about RVM is the macOS page I linked to, so we'll have to use that for now until there is a better choice available.

In brief, the sidebar would say:

• If you get a permissions error, you probably aren't using RVM
• You should be using RVM
• Here's a page that explains how to install it

Again, I can work what you wrote into that framework and see that it gets merged.

[janicemhdc]

Okay, thanks. Sorry, I didn't mean to threaten to take all my marbles and go home. I'm just a bit frustrated - it's been a long day.

[mojavelinux]

I didn't handle this well and I am sorry for that. My frustration is with the docs. I wish they were better. I very much appreciate that you are trying to e help make them better. So let's reset from there.

I want to take some time with your contribution and see how best to incorporate it so we can make the installation experience smoother. I'll post a draft here for you to review and we'll take it from there. Thanks again!

[mojavelinux]

A fix for this was (hopefully) merged as part of #1236.