Update README.adoc

[janicemhdc]

Add information about common Mac issue with Ruby and how to fix it

[mojavelinux]

I'm definitely open to adding docs about troubleshooting installation, but I feel this information is getting too specific for this README.

How about we make it a sidebar like "Installation Troubleshooting"? In that sidebar, it would say, generically, that if you get a permission error (and you can show this error as an example), then it means you are trying to install the gem into the system. You should instead set up a Ruby installation in user space, either using RVM or (on MacOS) Brew. Then, try the gem install command again.

You can also link to these instructions for further reading: https://asciidoctor.org/docs/install-asciidoctor-macos/

[janicemhdc]

I'm having additional issues with the install so I'm going to hold up on doing anything more with this until those are sorted out (see issue #1238)

I'm okay with a short "go here for troubleshooting" with some additional doc elsewhere, but that page doesn't seem right since it's for asciidoctor not asciidoctor-pdf

Also, as an aside, the asciidoctor.org home page basically tells folks to use homebrew on macs and does not link to that separate macos install page in those instructions (it encourages the use of the RVM for Windows users only). Conversely, that install page encourages Mac folks to use the RVM model instead of Homebrew. When I just opened that page and read it I was confused and a bit perplexed given that I'd just followed the instructions on the main asciidoctor.org page which encouraged using Homebrew. I'd be happy to discuss this further/make an issue in the asciidoctor.org project/suggested a cleanup via a PR in the asciidoctor.org project if you're open to that - just let me know which option makes the most sense.

[mojavelinux]

We are currently in the process of overhauling the Asciidoctor docs. One of the focuses will be installation. I'm well aware that the install instructions have fallen out of date or are just lacking in general. See asciidoctor/asciidoctor.org#399

[mojavelinux]

@janicemhdc I applied the revisions I alluded to in #1238 (refer to the Files changed tab). Let me know if like them and if there's anything you'd like to see added or changed.

[janicemhdc]

That looks fine as an addition to the readme and it's also kind of nice that the code highlighters have a section heading now too so folks can parse out that it's a separate bit of installation better. Thanks.

Maybe eventually it would make sense to have all but the basic installation be linked off on a separate page ( with a clear for troubleshooting and installation of additional components, go here) if cycles for further Asciidoctor PDF open up in the future but this is definitely a big improvement for now.

[mojavelinux]

Thanks for reviewing, @janicemhdc! I completely agree with you that all but the basic installation instructions should have a dedicated page, ideally on asciidoctor.org. So that we don't forget, I've filed an issue (see asciidoctor/asciidoctor.org#884). It will certainly be a key focal point of the new docs site (coming online soon at docs.asciidoctor.org).

it's also kind of nice that the code highlighters have a section heading now too

👍 As I was reading through the instructions, that was crying out to be a separate section.

[mojavelinux]

Thanks again!