rearchitect modules and filenames and drop asciidoctor folder under docs

8 files changed, 272 insertions, 0 deletions

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)
+....