这份文件详细描述了如何在macOS上安装Asciidoctor。提供了几种方法。选择最适合您的步骤。

RVM是最安全和最可靠的选择。然而，如果你已经在使用Homebrew，你可能会发现它比RVM更容易使用。最普通的（开箱即用的）程序是最不推荐的，但如果你在寻找一个快速安装，或者不想安装Xcode，那可能是必要的。

Caution
 这些安装指导是相互排斥的。如果你只部分遵循了一种程序，然后尝试另一种，你可能会遇到问题。在尝试另一种程序之前，请确保你撤销了之前程序中所执行的任何步骤。

RVM程序（推荐）

RVM 是一个Ruby安装和版本管理工具。RVM的工作原理是在你的家目录内安装Ruby，并管理环境变量，让你能够在系统全局的Ruby和使用RVM安装的任何Ruby版本之间切换。

要安装RVM，你首先必须安装[Xcode](苹果开发者网站(https://developer.apple.com/download/)下载。确保通过运行以下命令接受Xcode的许可协议：

$ xcodebuild -license

安装Xcode后，我们建议您执行软件更新（“图标：苹果[] > 软件更新”）。

使用Homebrew（如上所述）或者访问https://git-scm.com/download/mac下载macOS的安装程序来安装git。

安装RVM以及最新版本的Ruby：

$ \curl -#L https://get.rvm.io | bash -s stable --autolibs=3 --ruby

Note
 RVM 将会下载和构建 Ruby 语言，安装 RubyGems 以及数个必需的 gems，并配置你的 PATH 环境变量。

在你用来安装RVM的窗口中，导入你的Shell配置文件（只在该窗口中需要执行）：

$ source $HOME/.bash_profile

移除你的本地Gem配置，如果你有的话（或者把它挪到别的地方）：

$ rm -f $HOME/.gemrc

安装Asciidoctor：

$ gem install asciidoctor

确认Asciidoctor已安装并且您可以执行`asciidoctor`命令：

$ asciidoctor -v

如果你在终端上看到了Asciidoctor版本信息的打印，那么你就可以开始处理文档了！

当使用RVM时，你可以使用这两个命令在系统范围的Ruby和RVM管理的Ruby之间切换。

切换到系统范围的Ruby

$ rvm use system

切换到RVM管理的Ruby环境

$ rvm use default

当你切换到系统范围的Ruby时，asciidoctor 命令将变得不可用（除非你之前已经安装到了系统中）。这让你放心，RVM没有干扰到你的系统。

家酿程序

Homebrew 是“macOS缺失的包管理器。”Homebrew 安装你需要的东西，而这些是苹果公司没有提供的。

Homebrew通过将包安装到它们自己的目录中，并在_.usr/local_.下创建那些文件的符号链接来工作。

要安装和使用Homebrew，您必须首先安装Xcode。Xcode可以在Mac App Store上获得，或者可以从Apple的开发者网站下载。确保通过运行以下命令接受Xcode的许可证：

$ xcodebuild -license

安装Xcode后，我们建议您执行软件更新（“图标：苹果[] > 软件更新”）。

安装 Homebrew：

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

确认Homebrew是否正确设置：

$ brew doctor

安装Asciidoctor：

$ brew install asciidoctor

确认Asciidoctor已安装并且您可以执行`asciidoctor`命令：

$ asciidoctor -v

如果你在终端看到Asciidoctor版本信息，那么你就准备好开始处理文档了！

TIP: 如果您决定卸载 Homebrew，请按照 https://docs.brew.sh/FAQ.html [Homebrew's FAQ] 中的卸载说明操作。

== MacPorts操作流程

[The MacPorts Project]是一个开源社区倡议，旨在为macOS操作系统上的命令行、X11或Aqua基础的开源软件提供一个易于使用的系统，用于编译、安装和升级。

MacPorts通过在_/opt/local_下安装包来工作。它允许打包软件的多个版本（例如，Ruby 1.9和2.2）共存，并使用户能够轻松地在这些版本之间切换。

要安装和使用MacPorts，您首先必须安装[Xcode](https://developer.apple.com/xcode)。Xcode可以在Mac App Store上获取，或者从[苹果开发者网站](https://developer.apple.com/download/)下载。确保通过运行以下命令接受Xcode的许可证：

$ xcodebuild -license

安装Xcode后，我们建议您执行软件更新（“图标：苹果[] > 软件更新”）。

要安装MacPorts，您需要从 https://www.macports.org/install.php 下载适合您的macOS版本的正确的安装包，并运行它。安装MacPorts后，您需要打开一个*新的*终端窗口，并运行其 `selfupdate` 命令以升级自身并填充端口集合：

$ sudo port -v selfupdate

现在你可以通过以下方式安装Asciidoctor：

bash
$ sudo port install asciidoctor

要验证Asciidoctor是否正确安装，你可以执行`asciidoctor`命令：

$ asciidoctor -v

如果你在终端看到Asciidoctor版本信息，那么你就准备好开始处理文档了！

.排查MacPorts问题
[TIP]
如果在安装MacPorts后找不到`port`命令，你需要打开一个新的shell窗口。MacPorts会调整你的shell启动文件中的PATH（和MANPATH）定义（并保存旧的定义）。通过打开一个新的shell窗口，这些启动文件会被执行，新的PATH定义就会生效。

== 香草程序

香草程序使用随macOS附带的Ruby工具。这是最简单的方法，但也是最不确定的方法。除非你决心采取这种方法，否则使用RVM或Homebrew是一个更好的选择。

首先，更新系统上安装的RubyGems版本。（强烈推荐）


$ sudo gem update --system

使用以下两个命令之一安装Asciidoctor。

.系统安装

$ sudo gem install asciidoctor -N

或者

.用户（主目录）安装


$ gem install asciidoctor -N
$ echo 'export PATH=$PATH:$(find $HOME/.gem/ruby/*/bin -type d)' >> $HOME/.bash_profile
$ source $HOME/.bash_profile

确认Asciidoctor已安装并且您可以执行`asciidoctor`命令：

$ asciidoctor -v

如果你在终端上看到了Asciidoctor版本信息的打印，那么你就可以开始处理文档了！