From 46647208b1fb2f3ae3926843c99737662152780e Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Thu, 19 Nov 2020 01:12:37 -0700 Subject: update title of install parent page and rename some install pages --- docs/modules/install/pages/ruby-packaging.adoc | 67 ++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/modules/install/pages/ruby-packaging.adoc (limited to 'docs/modules/install/pages/ruby-packaging.adoc') diff --git a/docs/modules/install/pages/ruby-packaging.adoc b/docs/modules/install/pages/ruby-packaging.adoc new file mode 100644 index 00000000..ea9e0994 --- /dev/null +++ b/docs/modules/install/pages/ruby-packaging.adoc @@ -0,0 +1,67 @@ += Install Using Ruby Packaging + +[#gem-install] +== gem install + +Before installing Asciidoctor using `gem install`, you should set up {url-rvm}[RVM^] to install Ruby in your home directory (i.e., user space). +Then, you can safely use the `gem` command to install or update the Asciidoctor gem, or any other gem for that matter. +When using RVM, gems are installed in a location isolated from the system. + +Once you've installed Ruby using RVM, and you have activated it using `rvm use {ruby-short}`, open a terminal and type: + + $ gem install asciidoctor + +include::partial$success.adoc[] + +[#pre-release] +=== Install a pre-release version + +To install a pre-release version of Asciidoctor (e.g., a release candidate), open a terminal and type: + + $ gem install asciidoctor --pre + +== Bundler + +. Create a Gemfile in the root folder of your project (or the current directory) +. Add the `asciidoctor` gem to your Gemfile as follows: ++ +[source,subs=attributes+] +---- +source 'https://rubygems.org' +gem 'asciidoctor' +# or specify the version explicitly +# gem 'asciidoctor', '{release-version}' +---- + +. Save the Gemfile +. Open a terminal and install the gem using: + + $ bundle + +To upgrade the gem, specify the new version in the Gemfile and run `bundle` again. +Using `bundle update` (without specifying a gem) is *not* recommended as it will also update other gems, which may not be the desired result. + +== Upgrade using gem update + +[CAUTION] +==== +You're advised against using the `gem update` command to update a gem managed by the package manager. +Doing so puts the system into an inconsistent state as the package manager can no longer track the files (which get installed under [.path]_/usr/local_). +Simply put, system gems should only be managed by the package manager. + +If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, you should use {url-rvm}[RVM^] to install Ruby in your home directory (i.e., user space). +Then, you can safely use the `gem` command to install or update the Asciidoctor gem. +When using RVM, gems are installed in a location isolated from the system. +==== + +You can upgrade Asciidoctor using the gem `update` command: + + $ gem update asciidoctor + +[TIP] +==== +If you accidentally use `gem install` instead of `gem update`, then you'll end up with both versions installed. +To remove the older version, use the following `gem` command: + + $ gem cleanup asciidoctor +==== -- cgit v1.2.3 From ddf574ba80c64d0c77dcd1f533aca874710907b4 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Thu, 26 Nov 2020 01:34:22 -0700 Subject: add additional explicit IDs to content --- docs/modules/install/pages/ruby-packaging.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/modules/install/pages/ruby-packaging.adoc') diff --git a/docs/modules/install/pages/ruby-packaging.adoc b/docs/modules/install/pages/ruby-packaging.adoc index ea9e0994..a07cfe16 100644 --- a/docs/modules/install/pages/ruby-packaging.adoc +++ b/docs/modules/install/pages/ruby-packaging.adoc @@ -41,13 +41,14 @@ gem 'asciidoctor' To upgrade the gem, specify the new version in the Gemfile and run `bundle` again. Using `bundle update` (without specifying a gem) is *not* recommended as it will also update other gems, which may not be the desired result. +[#gem-update] == Upgrade using gem update [CAUTION] ==== You're advised against using the `gem update` command to update a gem managed by the package manager. Doing so puts the system into an inconsistent state as the package manager can no longer track the files (which get installed under [.path]_/usr/local_). -Simply put, system gems should only be managed by the package manager. +Simply put, system gems should only be updated by the package manager. If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, you should use {url-rvm}[RVM^] to install Ruby in your home directory (i.e., user space). Then, you can safely use the `gem` command to install or update the Asciidoctor gem. -- cgit v1.2.3 From b5af8e2d8d66d24d9ac03d2bbfac66c74872ac78 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Mon, 30 Nov 2020 18:21:31 -0700 Subject: switch fenced code blocks to AsciiDoc source blocks and always set language --- docs/modules/install/pages/ruby-packaging.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/modules/install/pages/ruby-packaging.adoc') diff --git a/docs/modules/install/pages/ruby-packaging.adoc b/docs/modules/install/pages/ruby-packaging.adoc index a07cfe16..8dbf98c8 100644 --- a/docs/modules/install/pages/ruby-packaging.adoc +++ b/docs/modules/install/pages/ruby-packaging.adoc @@ -25,7 +25,7 @@ To install a pre-release version of Asciidoctor (e.g., a release candidate), ope . Create a Gemfile in the root folder of your project (or the current directory) . Add the `asciidoctor` gem to your Gemfile as follows: + -[source,subs=attributes+] +[source,ruby,subs=attributes+] ---- source 'https://rubygems.org' gem 'asciidoctor' -- cgit v1.2.3