From c3c7ddbda681cc8f44832b0549bb623d3eace748 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Wed, 18 Nov 2020 15:53:10 -0700 Subject: rearchitect modules and filenames and drop asciidoctor folder under docs --- docs/modules/install/nav.adoc | 6 ++ docs/modules/install/pages/gem.adoc | 67 +++++++++++++++++ docs/modules/install/pages/index.adoc | 17 +++++ docs/modules/install/pages/linux.adoc | 84 ++++++++++++++++++++++ docs/modules/install/pages/macos.adoc | 23 ++++++ .../modules/install/pages/supported-platforms.adoc | 45 ++++++++++++ docs/modules/install/pages/windows.adoc | 18 +++++ docs/modules/install/partials/success.adoc | 12 ++++ 8 files changed, 272 insertions(+) create mode 100644 docs/modules/install/nav.adoc create mode 100644 docs/modules/install/pages/gem.adoc create mode 100644 docs/modules/install/pages/index.adoc create mode 100644 docs/modules/install/pages/linux.adoc create mode 100644 docs/modules/install/pages/macos.adoc create mode 100644 docs/modules/install/pages/supported-platforms.adoc create mode 100644 docs/modules/install/pages/windows.adoc create mode 100644 docs/modules/install/partials/success.adoc (limited to 'docs/modules/install') diff --git a/docs/modules/install/nav.adoc b/docs/modules/install/nav.adoc new file mode 100644 index 00000000..afd431e0 --- /dev/null +++ b/docs/modules/install/nav.adoc @@ -0,0 +1,6 @@ +* xref:index.adoc[] +** xref:supported-platforms.adoc[] +** xref:gem.adoc[] +** xref:linux.adoc[] +** xref:macos.adoc[] +** xref:windows.adoc[] diff --git a/docs/modules/install/pages/gem.adoc b/docs/modules/install/pages/gem.adoc new file mode 100644 index 00000000..af8b116f --- /dev/null +++ b/docs/modules/install/pages/gem.adoc @@ -0,0 +1,67 @@ += Install Using Ruby Tools + +[#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 +==== diff --git a/docs/modules/install/pages/index.adoc b/docs/modules/install/pages/index.adoc new file mode 100644 index 00000000..bdc1c57d --- /dev/null +++ b/docs/modules/install/pages/index.adoc @@ -0,0 +1,17 @@ += Install Asciidoctor + +To simplify installation, Asciidoctor is packaged and distributed as a RubyGem (aka gem) to {url-rubygem}/asciidoctor[RubyGems.org^]. +It's also distributed as a package for popular Linux distributions and macOS. +In addition to running on Ruby, Asciidoctor can be executed on a JVM using {url-asciidoctorj}[AsciidoctorJ^] or in any JavaScript environment (including the browser) using xref:asciidoctor.js::index.adoc[Asciidoctor.js]. + +== Installation methods + +Asciidoctor can be installed using: + +* package managers for popular Linux distributions, +* Homebrew for macOS, +* the `gem install` command (recommended for Windows users or if you'll be installing additional gems), +* the Asciidoctor Docker image, or +* Bundler. + +The benefit of using your operating system's package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine. diff --git a/docs/modules/install/pages/linux.adoc b/docs/modules/install/pages/linux.adoc new file mode 100644 index 00000000..a2b605f6 --- /dev/null +++ b/docs/modules/install/pages/linux.adoc @@ -0,0 +1,84 @@ += Install Using a Linux Package Manager +:url-alpine: https://pkgs.alpinelinux.org/packages?name=asciidoctor +:url-arch: https://www.archlinux.org/packages/?name=asciidoctor +:url-debian: https://packages.debian.org/sid/asciidoctor +:url-fedora: https://apps.fedoraproject.org/packages/rubygem-asciidoctor +:url-suse: https://software.opensuse.org/package/rubygem-asciidoctor +:url-ubuntu: https://packages.ubuntu.com/search?keywords=asciidoctor + +The benefit of using your operating system's package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine. + +== Linux packages + +The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor. +Consult the package repository for your distribution to find out which version is packaged per distribution release. + +* {url-alpine}[Alpine Linux (asciidoctor)] +* {url-arch}[Arch Linux (asciidoctor)] +* {url-debian}[Debian (asciidoctor)] +* {url-fedora}[Fedora (asciidoctor)] +* {url-suse}[OpenSUSE (rubygem-asciidoctor)] +* {url-ubuntu}[Ubuntu (asciidoctor)] + +If you want to use a version of Asciidoctor that is newer than what is available via your package manager, see xref:gem.adoc[]. + +== APT + +On Debian and Debian-based distributions such as Ubuntu, use APT to install Asciidoctor. +To install the package, open a terminal and type: + + $ sudo apt-get install -y asciidoctor + +include::partial$success.adoc[] + +== DNF + +On RPM-based Linux distributions, such as Fedora, CentOS, and RHEL, use the DNF package manager to install Asciidoctor. +To install the package, open a terminal and type: + + $ sudo dnf install -y asciidoctor + +include::partial$success.adoc[] + +== apk (Alpine Linux) + +To install the gem on Alpine Linux, open a terminal and type: + + $ sudo apk add asciidoctor + +include::partial$success.adoc[] + +== pacman (Arch Linux) + +To install the gem on Arch-based distributions, open a terminal and type: + + $ sudo pacman -S asciidoctor + +include::partial$success.adoc[] + +[#upgrade] +== Upgrading on Linux + +Some Linux distributions may not have the latest stable version of Asciidoctor packaged immediately after a release of a new gem. +If you need to upgrade to the latest version immediately, use xref:gem.adoc[gem install] instead of the package manager. + +TIP: Your Linux system may be configured to automatically update packages, in which case the latest Asciidoctor package will be installed as soon as it becomes available. +No further action is required by you. + +=== APT + +On Debian and Debian-based distributions, update the Asciidoctor package using: + + $ sudo apt-get upgrade -y asciidoctor + +=== DNF + +On Fedora and other RPM-based distributions, you can update the package using: + + $ sudo dnf update -y asciidoctor + +=== apk (Alpine Linux) + +On Alpine Linux, update the Asciidoctor package using: + + $ sudo apk add -u asciidoctor diff --git a/docs/modules/install/pages/macos.adoc b/docs/modules/install/pages/macos.adoc new file mode 100644 index 00000000..25a71919 --- /dev/null +++ b/docs/modules/install/pages/macos.adoc @@ -0,0 +1,23 @@ += Install on macOS +:url-homebrew: https://brew.sh/ + +== Install with Homebrew + +You can use Homebrew, the macOS package manager, to install Asciidoctor. +If you don't have Homebrew on your computer, complete the installation instructions at {url-homebrew}[brew.sh^] first. + +Once Homebrew is installed, you're ready to install the `asciidoctor` gem. +Open a terminal and type: + + $ brew install asciidoctor + +Homebrew installs the `asciidoctor` gem into an exclusive prefix that's independent of system gems. + +include::partial$success.adoc[] + +== Upgrade with Homebrew + +To upgrade the gem, open a terminal and type: + + $ brew update + $ brew upgrade asciidoctor diff --git a/docs/modules/install/pages/supported-platforms.adoc b/docs/modules/install/pages/supported-platforms.adoc new file mode 100644 index 00000000..789a01d4 --- /dev/null +++ b/docs/modules/install/pages/supported-platforms.adoc @@ -0,0 +1,45 @@ += Supported Platforms + +Asciidoctor operates on Linux, macOS and Windows and requires one of the supported Ruby implementations listed in the next section. + +== Ruby runtimes + +Asciidoctor requires one of the following implementations of {url-ruby}[Ruby^]. + +[%autowidth] +|=== +|Supported Runtime |Supported Versions + +|Ruby +|≥ 2.3 + +|JRuby +|≥ 9.1 + +|TruffleRuby +|≥ 20.2 +|=== + +== Operating systems + +[%autowidth] +|=== +|Supported OS |Supported Versions + +|Ubuntu +|18.04 LTS + +|Fedora +|≥ 31 + +|macOS +|High Sierra + +Mojave + +Catalina + +|Microsoft +|Windows 10 + +Windows Server 2019 +|=== + +Note that while the community tests Asciidoctor on a variety of Linux distributions, it's only officially tested on Ubuntu and Fedora. diff --git a/docs/modules/install/pages/windows.adoc b/docs/modules/install/pages/windows.adoc new file mode 100644 index 00000000..ae25d23e --- /dev/null +++ b/docs/modules/install/pages/windows.adoc @@ -0,0 +1,18 @@ += Install on Windows + +To install Asciidoctor on Windows, you can use Chocolatey or Rubyinstaller. + +== Chocolatey + +When you already use https://chocolatey.org[chocolatey^] on your machine, you can use: + +[source] +---- +choco install ruby +---- + +Then follow the xref:gem.adoc[gem installation instructions]. + +== Rubyinstaller + +Or you use the https://rubyinstaller.org/downloads/[Rubyinstaller^], download the package for your Windows Version and after the installation, then follow the xref:gem.adoc[gem installation instructions]. diff --git a/docs/modules/install/partials/success.adoc b/docs/modules/install/partials/success.adoc new file mode 100644 index 00000000..8ad68700 --- /dev/null +++ b/docs/modules/install/partials/success.adoc @@ -0,0 +1,12 @@ +If the gem installed successfully, its xref:cli:index.adoc[command line interface (CLI)] will be available on your PATH. +To confirm that Asciidoctor is available, execute: + + $ asciidoctor --version + +You should see information about the Asciidoctor version and your Ruby environment printed in the terminal. + +[.output,subs=attributes+] +.... +Asciidoctor {release-version} [https://asciidoctor.org] +Runtime Environment ({ruby-description}) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8) +.... -- cgit v1.2.3 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/nav.adoc | 4 +- docs/modules/install/pages/gem.adoc | 67 -------------------- docs/modules/install/pages/index.adoc | 4 +- docs/modules/install/pages/linux-packaging.adoc | 84 +++++++++++++++++++++++++ docs/modules/install/pages/linux.adoc | 84 ------------------------- docs/modules/install/pages/ruby-packaging.adoc | 67 ++++++++++++++++++++ docs/modules/install/pages/windows.adoc | 4 +- 7 files changed, 158 insertions(+), 156 deletions(-) delete mode 100644 docs/modules/install/pages/gem.adoc create mode 100644 docs/modules/install/pages/linux-packaging.adoc delete mode 100644 docs/modules/install/pages/linux.adoc create mode 100644 docs/modules/install/pages/ruby-packaging.adoc (limited to 'docs/modules/install') diff --git a/docs/modules/install/nav.adoc b/docs/modules/install/nav.adoc index afd431e0..6908b431 100644 --- a/docs/modules/install/nav.adoc +++ b/docs/modules/install/nav.adoc @@ -1,6 +1,6 @@ * xref:index.adoc[] ** xref:supported-platforms.adoc[] -** xref:gem.adoc[] -** xref:linux.adoc[] +** xref:ruby-packaging.adoc[] +** xref:linux-packaging.adoc[] ** xref:macos.adoc[] ** xref:windows.adoc[] diff --git a/docs/modules/install/pages/gem.adoc b/docs/modules/install/pages/gem.adoc deleted file mode 100644 index af8b116f..00000000 --- a/docs/modules/install/pages/gem.adoc +++ /dev/null @@ -1,67 +0,0 @@ -= Install Using Ruby Tools - -[#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 -==== diff --git a/docs/modules/install/pages/index.adoc b/docs/modules/install/pages/index.adoc index bdc1c57d..67ecc0b0 100644 --- a/docs/modules/install/pages/index.adoc +++ b/docs/modules/install/pages/index.adoc @@ -1,4 +1,4 @@ -= Install Asciidoctor += Install and Update To simplify installation, Asciidoctor is packaged and distributed as a RubyGem (aka gem) to {url-rubygem}/asciidoctor[RubyGems.org^]. It's also distributed as a package for popular Linux distributions and macOS. @@ -15,3 +15,5 @@ Asciidoctor can be installed using: * Bundler. The benefit of using your operating system's package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine. + +You should use the same method to update Asciidoctor as you use to install it. diff --git a/docs/modules/install/pages/linux-packaging.adoc b/docs/modules/install/pages/linux-packaging.adoc new file mode 100644 index 00000000..5df8c1f0 --- /dev/null +++ b/docs/modules/install/pages/linux-packaging.adoc @@ -0,0 +1,84 @@ += Install Using Linux Packaging +:url-alpine: https://pkgs.alpinelinux.org/packages?name=asciidoctor +:url-arch: https://www.archlinux.org/packages/?name=asciidoctor +:url-debian: https://packages.debian.org/sid/asciidoctor +:url-fedora: https://apps.fedoraproject.org/packages/rubygem-asciidoctor +:url-suse: https://software.opensuse.org/package/rubygem-asciidoctor +:url-ubuntu: https://packages.ubuntu.com/search?keywords=asciidoctor + +The benefit of using your operating system's package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine. + +== Package versions + +The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor. +Consult the package repository for your distribution to find out which version is packaged per distribution release. + +* {url-alpine}[Alpine Linux (asciidoctor)] +* {url-arch}[Arch Linux (asciidoctor)] +* {url-debian}[Debian (asciidoctor)] +* {url-fedora}[Fedora (asciidoctor)] +* {url-suse}[OpenSUSE (rubygem-asciidoctor)] +* {url-ubuntu}[Ubuntu (asciidoctor)] + +If you want to use a version of Asciidoctor that is newer than what is available via your package manager, see xref:ruby-packaging.adoc[]. + +== APT + +On Debian and Debian-based distributions such as Ubuntu, use APT to install Asciidoctor. +To install the package, open a terminal and type: + + $ sudo apt-get install -y asciidoctor + +include::partial$success.adoc[] + +== DNF + +On RPM-based Linux distributions, such as Fedora, CentOS, and RHEL, use the DNF package manager to install Asciidoctor. +To install the package, open a terminal and type: + + $ sudo dnf install -y asciidoctor + +include::partial$success.adoc[] + +== apk (Alpine Linux) + +To install the gem on Alpine Linux, open a terminal and type: + + $ sudo apk add asciidoctor + +include::partial$success.adoc[] + +== pacman (Arch Linux) + +To install the gem on Arch-based distributions, open a terminal and type: + + $ sudo pacman -S asciidoctor + +include::partial$success.adoc[] + +[#upgrade] +== Upgrading on Linux + +Some Linux distributions may not have the latest stable version of Asciidoctor packaged immediately after a release of a new gem. +If you need to upgrade to the latest version immediately, use xref:ruby-packaging.adoc[gem install] instead of the package manager. + +TIP: Your Linux system may be configured to automatically update packages, in which case the latest Asciidoctor package will be installed as soon as it becomes available. +No further action is required by you. + +=== APT + +On Debian and Debian-based distributions, update the Asciidoctor package using: + + $ sudo apt-get upgrade -y asciidoctor + +=== DNF + +On Fedora and other RPM-based distributions, you can update the package using: + + $ sudo dnf update -y asciidoctor + +=== apk (Alpine Linux) + +On Alpine Linux, update the Asciidoctor package using: + + $ sudo apk add -u asciidoctor diff --git a/docs/modules/install/pages/linux.adoc b/docs/modules/install/pages/linux.adoc deleted file mode 100644 index a2b605f6..00000000 --- a/docs/modules/install/pages/linux.adoc +++ /dev/null @@ -1,84 +0,0 @@ -= Install Using a Linux Package Manager -:url-alpine: https://pkgs.alpinelinux.org/packages?name=asciidoctor -:url-arch: https://www.archlinux.org/packages/?name=asciidoctor -:url-debian: https://packages.debian.org/sid/asciidoctor -:url-fedora: https://apps.fedoraproject.org/packages/rubygem-asciidoctor -:url-suse: https://software.opensuse.org/package/rubygem-asciidoctor -:url-ubuntu: https://packages.ubuntu.com/search?keywords=asciidoctor - -The benefit of using your operating system's package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine. - -== Linux packages - -The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor. -Consult the package repository for your distribution to find out which version is packaged per distribution release. - -* {url-alpine}[Alpine Linux (asciidoctor)] -* {url-arch}[Arch Linux (asciidoctor)] -* {url-debian}[Debian (asciidoctor)] -* {url-fedora}[Fedora (asciidoctor)] -* {url-suse}[OpenSUSE (rubygem-asciidoctor)] -* {url-ubuntu}[Ubuntu (asciidoctor)] - -If you want to use a version of Asciidoctor that is newer than what is available via your package manager, see xref:gem.adoc[]. - -== APT - -On Debian and Debian-based distributions such as Ubuntu, use APT to install Asciidoctor. -To install the package, open a terminal and type: - - $ sudo apt-get install -y asciidoctor - -include::partial$success.adoc[] - -== DNF - -On RPM-based Linux distributions, such as Fedora, CentOS, and RHEL, use the DNF package manager to install Asciidoctor. -To install the package, open a terminal and type: - - $ sudo dnf install -y asciidoctor - -include::partial$success.adoc[] - -== apk (Alpine Linux) - -To install the gem on Alpine Linux, open a terminal and type: - - $ sudo apk add asciidoctor - -include::partial$success.adoc[] - -== pacman (Arch Linux) - -To install the gem on Arch-based distributions, open a terminal and type: - - $ sudo pacman -S asciidoctor - -include::partial$success.adoc[] - -[#upgrade] -== Upgrading on Linux - -Some Linux distributions may not have the latest stable version of Asciidoctor packaged immediately after a release of a new gem. -If you need to upgrade to the latest version immediately, use xref:gem.adoc[gem install] instead of the package manager. - -TIP: Your Linux system may be configured to automatically update packages, in which case the latest Asciidoctor package will be installed as soon as it becomes available. -No further action is required by you. - -=== APT - -On Debian and Debian-based distributions, update the Asciidoctor package using: - - $ sudo apt-get upgrade -y asciidoctor - -=== DNF - -On Fedora and other RPM-based distributions, you can update the package using: - - $ sudo dnf update -y asciidoctor - -=== apk (Alpine Linux) - -On Alpine Linux, update the Asciidoctor package using: - - $ sudo apk add -u asciidoctor 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 +==== diff --git a/docs/modules/install/pages/windows.adoc b/docs/modules/install/pages/windows.adoc index ae25d23e..2248b0b1 100644 --- a/docs/modules/install/pages/windows.adoc +++ b/docs/modules/install/pages/windows.adoc @@ -11,8 +11,8 @@ When you already use https://chocolatey.org[chocolatey^] on your machine, you ca choco install ruby ---- -Then follow the xref:gem.adoc[gem installation instructions]. +Then follow the xref:ruby-packaging.adoc[gem installation instructions]. == Rubyinstaller -Or you use the https://rubyinstaller.org/downloads/[Rubyinstaller^], download the package for your Windows Version and after the installation, then follow the xref:gem.adoc[gem installation instructions]. +Or you use the https://rubyinstaller.org/downloads/[Rubyinstaller^], download the package for your Windows Version and after the installation, then follow the xref:ruby-packaging.adoc[gem installation instructions]. -- 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/linux-packaging.adoc | 5 +++++ docs/modules/install/pages/ruby-packaging.adoc | 3 ++- 2 files changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/modules/install') diff --git a/docs/modules/install/pages/linux-packaging.adoc b/docs/modules/install/pages/linux-packaging.adoc index 5df8c1f0..940fecf3 100644 --- a/docs/modules/install/pages/linux-packaging.adoc +++ b/docs/modules/install/pages/linux-packaging.adoc @@ -40,6 +40,7 @@ To install the package, open a terminal and type: include::partial$success.adoc[] +[#apk] == apk (Alpine Linux) To install the gem on Alpine Linux, open a terminal and type: @@ -48,6 +49,7 @@ To install the gem on Alpine Linux, open a terminal and type: include::partial$success.adoc[] +[#pacman] == pacman (Arch Linux) To install the gem on Arch-based distributions, open a terminal and type: @@ -65,18 +67,21 @@ If you need to upgrade to the latest version immediately, use xref:ruby-packagin TIP: Your Linux system may be configured to automatically update packages, in which case the latest Asciidoctor package will be installed as soon as it becomes available. No further action is required by you. +[#upgrade-apt] === APT On Debian and Debian-based distributions, update the Asciidoctor package using: $ sudo apt-get upgrade -y asciidoctor +[#upgrade-dnf] === DNF On Fedora and other RPM-based distributions, you can update the package using: $ sudo dnf update -y asciidoctor +[#upgrade-apk] === apk (Alpine Linux) On Alpine Linux, update the Asciidoctor package using: 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 +- docs/modules/install/pages/windows.adoc | 5 +---- 2 files changed, 2 insertions(+), 5 deletions(-) (limited to 'docs/modules/install') 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' diff --git a/docs/modules/install/pages/windows.adoc b/docs/modules/install/pages/windows.adoc index 2248b0b1..99d29b1e 100644 --- a/docs/modules/install/pages/windows.adoc +++ b/docs/modules/install/pages/windows.adoc @@ -6,10 +6,7 @@ To install Asciidoctor on Windows, you can use Chocolatey or Rubyinstaller. When you already use https://chocolatey.org[chocolatey^] on your machine, you can use: -[source] ----- -choco install ruby ----- + C:\> choco install ruby Then follow the xref:ruby-packaging.adoc[gem installation instructions]. -- cgit v1.2.3 From 062ddfe40c7b90205b74d1313969cd3287be99fe Mon Sep 17 00:00:00 2001 From: Sarah White Date: Thu, 3 Dec 2020 17:30:34 -0700 Subject: content clarifications, syntax fixes, and added xrefs --- docs/modules/install/pages/index.adoc | 2 +- docs/modules/install/pages/linux-packaging.adoc | 12 ++++++------ docs/modules/install/pages/supported-platforms.adoc | 2 +- docs/modules/install/partials/success.adoc | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/modules/install') diff --git a/docs/modules/install/pages/index.adoc b/docs/modules/install/pages/index.adoc index 67ecc0b0..1cfcaa2c 100644 --- a/docs/modules/install/pages/index.adoc +++ b/docs/modules/install/pages/index.adoc @@ -1,6 +1,6 @@ = Install and Update -To simplify installation, Asciidoctor is packaged and distributed as a RubyGem (aka gem) to {url-rubygem}/asciidoctor[RubyGems.org^]. +To simplify installation, Asciidoctor is packaged and distributed as a {url-rubygem}/asciidoctor[RubyGem to the package repository at RubyGems.org^]. It's also distributed as a package for popular Linux distributions and macOS. In addition to running on Ruby, Asciidoctor can be executed on a JVM using {url-asciidoctorj}[AsciidoctorJ^] or in any JavaScript environment (including the browser) using xref:asciidoctor.js::index.adoc[Asciidoctor.js]. diff --git a/docs/modules/install/pages/linux-packaging.adoc b/docs/modules/install/pages/linux-packaging.adoc index 940fecf3..1033a622 100644 --- a/docs/modules/install/pages/linux-packaging.adoc +++ b/docs/modules/install/pages/linux-packaging.adoc @@ -13,12 +13,12 @@ The benefit of using your operating system's package manager to install the gem The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor. Consult the package repository for your distribution to find out which version is packaged per distribution release. -* {url-alpine}[Alpine Linux (asciidoctor)] -* {url-arch}[Arch Linux (asciidoctor)] -* {url-debian}[Debian (asciidoctor)] -* {url-fedora}[Fedora (asciidoctor)] -* {url-suse}[OpenSUSE (rubygem-asciidoctor)] -* {url-ubuntu}[Ubuntu (asciidoctor)] +* {url-alpine}[Alpine Linux (asciidoctor)^] +* {url-arch}[Arch Linux (asciidoctor)^] +* {url-debian}[Debian (asciidoctor)^] +* {url-fedora}[Fedora (asciidoctor)^] +* {url-suse}[OpenSUSE (rubygem-asciidoctor)^] +* {url-ubuntu}[Ubuntu (asciidoctor)^] If you want to use a version of Asciidoctor that is newer than what is available via your package manager, see xref:ruby-packaging.adoc[]. diff --git a/docs/modules/install/pages/supported-platforms.adoc b/docs/modules/install/pages/supported-platforms.adoc index 789a01d4..3d14e255 100644 --- a/docs/modules/install/pages/supported-platforms.adoc +++ b/docs/modules/install/pages/supported-platforms.adoc @@ -42,4 +42,4 @@ Catalina Windows Server 2019 |=== -Note that while the community tests Asciidoctor on a variety of Linux distributions, it's only officially tested on Ubuntu and Fedora. +While the community tests Asciidoctor on a variety of Linux distributions, it's only officially tested on Ubuntu and Fedora. diff --git a/docs/modules/install/partials/success.adoc b/docs/modules/install/partials/success.adoc index 8ad68700..df70c570 100644 --- a/docs/modules/install/partials/success.adoc +++ b/docs/modules/install/partials/success.adoc @@ -1,4 +1,4 @@ -If the gem installed successfully, its xref:cli:index.adoc[command line interface (CLI)] will be available on your PATH. +If the gem installed successfully, Asciidoctor's xref:cli:index.adoc[command line interface (CLI)] will be available on your PATH. To confirm that Asciidoctor is available, execute: $ asciidoctor --version -- cgit v1.2.3