README.adoc in asciidoctor-1.5.7.1 vs README.adoc in asciidoctor-1.5.8

- old
+ new

@@ -1,9 +1,8 @@ = Asciidoctor Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]> -v1.5.7.1, 2018-05-10 -v1.5.7, 2018-05-02 +v1.5.8, 2018-10-28 // settings: :idprefix: :idseparator: - :source-language: ruby :language: {source-language} @@ -16,16 +15,19 @@ :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[] // Variables: -:release-version: 1.5.7.1 +:release-version: 1.5.8 // URIs: :uri-org: https://github.com/asciidoctor :uri-repo: {uri-org}/asciidoctor :uri-asciidoctorj: {uri-org}/asciidoctorj :uri-asciidoctorjs: {uri-org}/asciidoctor.js +:uri-gradle-plugin: {uri-org}/asciidoctor-gradle-plugin +:uri-maven-plugin: {uri-org}/asciidoctor-maven-plugin +:uri-asciidoclet: {uri-org}/asciidoclet :uri-project: https://asciidoctor.org ifdef::env-site[:uri-project: link:] :uri-docs: {uri-project}/docs :uri-news: {uri-project}/news :uri-manpage: {uri-project}/man/asciidoctor @@ -53,24 +55,28 @@ :uri-themes-doc: {uri-docs}/produce-custom-themes-using-asciidoctor-stylesheet-factory :uri-gitscm-repo: https://github.com/git/git-scm.com :uri-prototype: {uri-gitscm-repo}/commits/master/lib/asciidoc.rb :uri-freesoftware: https://www.gnu.org/philosophy/free-sw.html :uri-foundation: https://foundation.zurb.com +:uri-opal: https://opalrb.com :uri-tilt: https://github.com/rtomayko/tilt :uri-ruby: https://www.ruby-lang.org // images: :image-uri-screenshot: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/screenshot.png -{uri-project}[Asciidoctor] is a _fast_ text processor and publishing toolchain for converting {uri-what-is-asciidoc}[AsciiDoc] content to HTML5, DocBook, PDF, and other formats. -Asciidoctor is written in Ruby, packaged and distributed as a gem to {uri-rubygem}[RubyGems.org], and packaged for popular Linux distributions, including Fedora, Debian, Ubuntu, and Alpine. -Asciidoctor can be run on the JVM using AsciidoctorJ and in all JavaScript environments using Asciidoctor.js. -Asciidoctor is {uri-license}[open source software] and {uri-repo}[hosted on GitHub]. +{uri-project}[Asciidoctor] is a _fast_, {uri-license}[open source] text processor and publishing toolchain for converting {uri-what-is-asciidoc}[AsciiDoc] content to HTML5, DocBook, PDF, and other formats. +Asciidoctor is written in Ruby and runs on all major operation systems. +To simplify installation, Asciidoctor is packaged and distributed as a gem to {uri-rubygem}[RubyGems.org] and is packaged for popular Linux distributions and macOS. +Asciidoctor can also be run in a JVM using {uri-asciidoctorj}[AsciidoctorJ] or in any JavaScript environment using {uri-asciidoctorjs}[Asciidoctor.js]. +The Asciidoctor project is {uri-repo}[hosted on GitHub]. ifndef::env-site[] This document is also available in the following languages: + {uri-rel-file-base}README-zh_CN.adoc[汉语] | +{uri-rel-file-base}README-de.adoc[Deutsch] +| {uri-rel-file-base}README-fr.adoc[Français] | {uri-rel-file-base}README-jp.adoc[日本語] endif::[] @@ -97,11 +103,11 @@ image:https://www.okta.com/sites/all/themes/Okta/images/blog/Logos/Okta_Logo_BrightBlue_Medium.png[Okta,280,link=https://developer.okta.com/signup?utm_source=asciidoctor&utm_medium=logo&utm_campaign=sponsor,title="Add User Auth to Your Apps in Minutes with Okta"] &nbsp; &nbsp; &nbsp; image:https://secure.gravatar.com/avatar/823717a797dbd78ceff7b26aa397f383.png?size=200[OpenDevise,100,link=https://opendevise.com,title="Let the Creators of Asciidoctor and Antora Help You to Accelerate Your Docs"] -Major funding for Asciidoctor is provided by our *Change Makers*, https://developer.okta.com/signup?utm_source=asciidoctor&utm_medium=text-link&utm_campaign=sponsor[Okta] and https://opendevise.com[OpenDevise], and our *Strategy Sponsors*, Khronos Group and Linda Roberts. +Major funding for Asciidoctor is provided by our *Change Makers*, https://developer.okta.com/signup?utm_source=asciidoctor&utm_medium=text-link&utm_campaign=sponsor[Okta] and https://opendevise.com[OpenDevise], and our *Strategy Sponsors*, https://www.khronos.org/[Khronos Group] and Linda Roberts. Additional funding is provided by our https://asciidoctor.org/supporters[Community Backers]. You can support this project by becoming a sponsor on https://opencollective.com/asciidoctor[OpenCollective]. == The Big Picture @@ -111,41 +117,39 @@ image::{image-uri-screenshot}[Preview of AsciiDoc source and corresponding rendered HTML] == AsciiDoc Processing -Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree to a set of built-in converters to produce HTML5, DocBook 5 (or 4.5) or man(ual) page output. +Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree to a set of built-in converters to produce HTML5, DocBook 5, and man(ual) page output. You have the option of using your own converter or loading {uri-tilt}[Tilt]-supported templates to customize the generated output or produce additional formats. -NOTE: Asciidoctor is a drop-in replacement for the original AsciiDoc Python processor (`asciidoc.py`). +Asciidoctor is a drop-in replacement for the original AsciiDoc Python processor (`asciidoc.py`). The Asciidoctor test suite has {uri-tests}[> 2,000 tests] to ensure compatibility with the AsciiDoc syntax. In addition to the classic AsciiDoc syntax, Asciidoctor recognizes additional markup and formatting options, such as font-based icons (e.g., `+icon:fire[]+`) and UI elements (e.g., `+button:[Save]+`). Asciidoctor also offers a modern, responsive theme based on {uri-foundation}[Foundation] to style the HTML5 output. == Where Ruby goes, Asciidoctor follows You can run Asciidoctor on the JVM using JRuby. To invoke the Asciidoctor API directly from Java and other JVM languages, use {uri-asciidoctorj}[AsciidoctorJ]. -There are plugins available, based on AsciidoctorJ, that integrate the Asciidoctor processor into Apache Maven, Gradle or Javadoc builds. +There are plugins available for {uri-maven-plugin}[Apache Maven], {uri-gradle-plugin}[Gradle], and {uri-asciidoclet}[Javadoc], which allow you to integrate AsciiDoc processing directly into your build using AsciidoctorJ. Asciidoctor also runs in JavaScript. -We use https://opalrb.com[Opal] to transcompile the Ruby source to JavaScript to produce {uri-asciidoctorjs}[Asciidoctor.js], a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js. -Asciidoctor.js is used to power the AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tooling. +{uri-opal}[Opal] is used to transcompile the Ruby source to JavaScript to produce {uri-asciidoctorjs}[Asciidoctor.js]. +Asciidoctor.js is a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js. +It's used to power the AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tooling. == Requirements Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of {uri-ruby}[Ruby]: * Ruby (MRI/CRuby 1.8.7 - 2.5) * JRuby (1.7 in Ruby 1.8 and 1.9 modes, 9000) * Rubinius 2.2.x * Opal (JavaScript) -We welcome your help testing Asciidoctor on these and other platforms. -Refer to the <<Contributing>> section to learn how to get involved. - [CAUTION] ==== If you're using a non-English Windows environment, you may bump into an `Encoding::UndefinedConversionError` when invoking Asciidoctor. To solve this issue, we recommend changing the active code page in your console to UTF-8: @@ -156,41 +160,105 @@ Asciidoctor works best when you use UTF-8 everywhere. ==== == Installation -Asciidoctor can be installed using (a) the `gem install` command, (b) Bundler, (c) package managers for popular Linux distributions, or (d) Homebrew for macOS. +Asciidoctor can be installed using (a) package managers for popular Linux distributions, (b) Homebrew for macOS, (c) the `gem install` command (recommended for Windows users), (d) the Asciidoctor Docker image, or (e) Bundler. -TIP: The benefit of using a Linux 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. -The drawback is that the package may not be available immediately after the release of the gem. -If you need the latest version, you can always fallback to using the `gem` command. +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. -=== (a) gem install +=== (a) Linux package managers -Open a terminal and type (excluding the leading `$`): +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. +* https://pkgs.alpinelinux.org/packages?name=asciidoctor[Alpine Linux (asciidoctor)] +* https://www.archlinux.org/packages/?name=asciidoctor[Arch Linux (asciidoctor)] +* https://packages.debian.org/sid/asciidoctor[Debian (asciidoctor)] +* https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Fedora (asciidoctor)] +* https://software.opensuse.org/package/rubygem-asciidoctor[OpenSUSE (rubygem-asciidoctor)] +* https://packages.ubuntu.com/search?keywords=asciidoctor[Ubuntu (asciidoctor)] + +If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, see the <<gem-install,gem installation instructions>>. + +==== apk (Alpine Linux) + +To install the gem on Alpine Linux, open a terminal and type: + + $ sudo apk add asciidoctor + +==== pacman (Arch Linux) + +To install the gem on Arch-based distributions, open a terminal and type: + + $ sudo pacman -S asciidoctor + +==== 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 + +==== 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 + +=== (b) Homebrew (macOS) + +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 https://brew.sh/[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. + +=== (c) Windows + +To use Asciidoctor with Windows, you have two easy options. + +==== Chocolatey + +When you already use https://chocolatey.org[chocolatey] on your machine, you can use: + +[source] +---- +choco install ruby +---- + +Then follow <<gem-install,gem installation instructions>>. + +==== Rubyinstaller + +Or you use the https://rubyinstaller.org/downloads/[Rubyinstaller], download the package for your Windows Version and after the installation go ahead with <<gem-install,gem installation instructions>>. + +[#gem-install] +=== (d) gem install + +Before installing Asciidoctor using `gem install`, you should use https://rvm.io[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. + +Open a terminal and type: + $ gem install asciidoctor If you want to install a pre-release version (e.g., a release candidate), use: $ gem install asciidoctor --pre -.Upgrading your installation -[TIP] -==== -If you have an earlier version of Asciidoctor installed, you can update it using: +=== (e) Docker - $ gem update asciidoctor +See {uri-install-docker}[Installing Asciidoctor using Docker]. -If you install a new version of the gem using `gem install` instead of gem update, you'll have multiple versions installed. -If that's the case, use the following gem command to remove the old versions: +=== (f) Bundler - $ gem cleanup asciidoctor -==== - -=== (b) 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+] ---- @@ -204,91 +272,53 @@ . 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` is *not* recommended as it will also update other gems, which may not be the desired result. +Using `bundle update` (without specifying a gem) is *not* recommended as it will also update other gems, which may not be the desired result. -=== (c) Linux package managers +== Upgrade -==== DNF (Fedora 21 or greater) +If you installed Asciidoctor using a package manager, your operating system is probably configured to automatically update packages, in which case you don't need to update the gem manually. -To install the gem on Fedora 21 or greater using dnf, open a terminal and type: +=== apk (Alpine Linux) - $ sudo dnf install -y asciidoctor - To upgrade the gem, use: - $ sudo dnf update -y asciidoctor + $ sudo apk add -u asciidoctor -TIP: Your system may be configured to automatically update rpm packages, in which case no action is required by you to update the gem. +=== APT -==== apt-get (Debian or Ubuntu) - -To install the gem on Debian or Ubuntu, open a terminal and type: - - $ sudo apt-get install -y asciidoctor - To upgrade the gem, use: $ sudo apt-get upgrade -y asciidoctor -TIP: Your system may be configured to automatically update deb packages, in which case no action is required by you to update the gem. +=== DNF -The version of Asciidoctor installed by the package manager (apt-get) 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. - -* https://packages.debian.org/search?keywords=asciidoctor&searchon=names&exact=1&suite=all&section=all[asciidoctor package by Debian release] -* https://packages.ubuntu.com/search?keywords=asciidoctor&searchon=names&exact=1&suite=all&section=all[asciidoctor package by Ubuntu release] - -[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 /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 https://rvm.io[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. -==== - -==== apk (Alpine Linux) - -To install the gem on Alpine Linux, open a terminal and type: - - $ sudo apk add asciidoctor - To upgrade the gem, use: - $ sudo apk add -u asciidoctor + $ sudo dnf update -y asciidoctor -TIP: Your system may be configured to automatically update apk packages, in which case no action is required by you to update the gem. +=== Homebrew (macOS) -=== (d) Homebrew (macOS) - -You can use Homebrew to install Asciidoctor on macOS. -If you haven't yet installed Homebrew, follow the instructions at https://brew.sh/[brew.sh]. - -Once Homebrew is installed, you can install the `asciidoctor` gem using the http://brewformulas.org/Asciidoctor[asciidoctor] package. -To do so, open a terminal and type: - - $ brew install asciidoctor - To upgrade the gem, use: $ brew update $ brew upgrade asciidoctor -TIP: Homebrew installs the `asciidoctor` gem into an exclusive prefix that's independent of system gems. +=== gem install -=== Other installation options +If you previously installed Asciidoctor using the `gem` command, you'll need to manually upgrade Asciidoctor when a new version is released. +You can upgrade the gem by typing: -* {uri-install-docker}[Installing Asciidoctor using Docker] -* {uri-install-macos-doc}[Installing Asciidoctor on macOS] -// at the moment, the following entry is just a reiteration of the information in this README -//* {uri-install-doc}[Installing the Asciidoctor toolchain] + $ gem install asciidoctor +When you install a new version of the gem using `gem install`, you end up with multiple versions installed. +Use the following command to remove the old versions: + + $ gem cleanup asciidoctor + == Usage If the Asciidoctor gem installed successfully, the `asciidoctor` command line interface (CLI) will be available on your PATH. To verify it's available, run the following in your terminal: @@ -297,11 +327,11 @@ 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 2.4.1p111 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8) +Runtime Environment (ruby 2.5.1p57 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8) .... Asciidoctor also provides an API. The API is intended for integration with other Ruby software, such as Rails, Sinatra and GitHub, and other languages, such as Java (via {uri-asciidoctorj}[AsciidoctorJ]) and JavaScript (via {uri-asciidoctorjs}[Asciidoctor.js]). @@ -380,22 +410,20 @@ However you go about it, you _can_ have 100% control over the output. For more information about how to use the API or to customize the output, refer to the {uri-user-manual}[user manual]. == Contributing -In the spirit of {uri-freesoftware}[free software], _everyone_ is encouraged to help improve this project. -If you discover errors or omissions in the source code, documentation, or website content, please don't hesitate to submit an issue or open a pull request with a fix. New contributors are always welcome! +If you discover errors or omissions in the source code, documentation, or website content, please don't hesitate to submit an issue or open a pull request with a fix. Here are some ways *you* can contribute: * by using prerelease (alpha, beta or preview) versions * by reporting bugs * by suggesting new features * by writing or editing documentation -* by writing specifications -* by writing code -- _No patch is too small._ +* by writing code with tests -- _No patch is too small._ ** fix typos ** add comments ** clean up inconsistent whitespace ** write tests! * by refactoring code @@ -404,20 +432,17 @@ The {uri-contribute}[Contributing] guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to the Asciidoctor Project. == Getting Help -The Asciidoctor project is developed to help you easily write and publish your content. +Asciidoctor is developed to help you easily write and publish your content. But we can't do it without your feedback! We encourage you to ask questions and discuss any aspects of the project on the discussion list, on Twitter or in the chat room. +Chat (Gitter):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor] Discussion list (Nabble):: {uri-discuss} Twitter:: https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] hashtag or https://twitter.com/asciidoctor[@asciidoctor] mention -Chat (Gitter):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor] -//// -Chat (IRC):: {uri-irc}[#asciidoctor] on FreeNode IRC -//// ifdef::env-github[] Further information and documentation about Asciidoctor can be found on the project's website. {uri-project}[Home] | {uri-news}[News] | {uri-docs}[Docs] @@ -427,22 +452,22 @@ Source repository (git):: {uri-repo} Issue tracker:: {uri-issues} Asciidoctor organization on GitHub:: {uri-org} -== Copyright and Licensing +== License -Copyright (C) 2012-2018 Dan Allen, Ryan Waldron and the Asciidoctor Project. -Free use of this software is granted under the terms of the MIT License. +Copyright (C) 2012-2018 Dan Allen, Sarah White and the individual contributors to Asciidoctor. +Use of this software is granted under the terms of the MIT License. -See the {uri-license}[LICENSE] file for details. +See the {uri-license}[LICENSE] for the full license text. == Authors -*Asciidoctor* is led by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] and has received contributions from {uri-contributors}[many other individuals] in Asciidoctor's awesome community. +*Asciidoctor* is led by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] and has received contributions from {uri-contributors}[many individuals] in Asciidoctor's awesome community. The project was initiated in 2012 by https://github.com/erebor[Ryan Waldron] and based on {uri-prototype}[a prototype] written by https://github.com/nickh[Nick Hengeveld]. -*AsciiDoc* was started by Stuart Rackham and has received contributions from many other individuals in the AsciiDoc community. +*AsciiDoc* was started by Stuart Rackham and has received contributions from many individuals in the AsciiDoc community. ifndef::env-site[] == Changelog ifeval::[{safe-mode-level} < 20]