asciidoctor 1.5.7.1 → 1.5.8

data/README-fr.adoc

@@ -1,7 +1,6 @@
 = 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: -
@@ -18,7 +17,7 @@ ifdef::env-github[]
 :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
@@ -60,17 +59,19 @@ endif::[]
 // images:
 :image-uri-screenshot: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/screenshot.png
 
-{uri-project}/[Asciidoctor] est un processeur de texte _rapide_ et une chaîne de publication pour convertir du contenu {uri-what-is-asciidoc}[AsciiDoc] en HTML5, DocBook 5 (ou 4.5) et d'autres formats.
-Asciidoctor est écrit en Ruby, packagé sous forme de RubyGem et publié sur {uri-rubygem}[RubyGems.org].
-La gemme est aussi incluse dans plusieurs distributions Linux, dont Fedora, Debian, Ubuntu et Alpine.
-Asciidoctor est open source, {uri-repo}[hébergé sur GitHub] et distribué sous {uri-license}[licence MIT].
+{uri-project}/[Asciidoctor] est un processeur de texte et une chaîne de publication _rapide_ et {uri-license}[open source] permettant de convertir du contenu {uri-what-is-asciidoc}[AsciiDoc] en HTML5, DocBook, PDF et d'autres formats.
+Asciidoctor est écrit en Ruby et fonctionne sur les principaux systèmes d'exploitation.
+Pour simplifier l'installation, Asciidoctor est publié au format gem sur {uri-rubygem}[RubyGems.org], et il est également disponible en tant que paquet système sur les principales distributions Linux ainsi que sur macOS.
+Asciidoctor fonctionne aussi sur la JVM avec {uri-asciidoctorj}[AsciidoctorJ] et dans n'importe quel environnement JavaScript avec {uri-asciidoctorjs}[Asciidoctor.js].
+Le projet Asciidoctor est {uri-repo}[hébergé sur GitHub].
 
 ifndef::env-site[]
-Ce document est traduit dans les langues suivantes :
-
-* {uri-rel-file-base}README.adoc[Anglais]
-* {uri-rel-file-base}README-zh_CN.adoc[Chinois]
-* {uri-rel-file-base}README-jp.adoc[Japonais]
+Ce document est traduit dans les langues suivantes : +
+{uri-rel-file-base}README.adoc[Anglais]
+|
+{uri-rel-file-base}README-zh_CN.adoc[Chinois]
+|
+{uri-rel-file-base}README-jp.adoc[Japonais]
 endif::[]
 
 .Documentation clé
@@ -80,17 +81,6 @@ endif::[]
 * {uri-docs}/asciidoc-syntax-quick-reference[Syntaxe de Référence AsciiDoc]
 * {uri-docs}/user-manual[Manuel Utilisateur Asciidoctor]
 
-.Asciidoctor est disponible partout où Ruby est disponible
-****
-Vous pouvez exécuter Asciidoctor dans la JVM en utilisant JRuby.
-Pour invoquer l'API Asciidoctor directement depuis Java ou d'autres langages de la JVM, utilisez {uri-asciidoctorj}[AsciidoctorJ].
-Des plugins basés sur AsciidoctorJ permettent d'intégrer le processeur Asciidoctor avec Apache Maven, Gradle ou Javadoc.
-
-Asciidoctor s'exécute également au sein de JavaScript.
-Nous utilisons http://opalrb.org[Opal] pour transcrire le code source Ruby en JavaScript afin de produire {uri-asciidoctorjs}[Asciidoctor.js], une version pleinement fonctionnelle d'Asciidoctor qui s'intègre dans tout environnement JavaScript, comme un navigateur web ou Node.js.
-Asciidoctor.js est utilisé pour faire fonctionner les extensions AsciiDoc Preview pour Chrome, Atom, Brackets et autres outils web.
-****
-
 ifdef::status[]
 .*Santé du projet*
 image:https://img.shields.io/travis/asciidoctor/asciidoctor/master.svg[Build Status (Travis CI), link=https://travis-ci.org/asciidoctor/asciidoctor]
@@ -100,6 +90,20 @@ image:https://ci.appveyor.com/api/projects/status/ifplu67oxvgn6ceq/branch/master
 image:https://inch-ci.org/github/asciidoctor/asciidoctor.svg?branch=master[Inline docs, link="https://inch-ci.org/github/asciidoctor/asciidoctor"]
 endif::[]
 
+== Sponsors
+
+Nous souhaitons exprimer toute notre reconnaissance à nos généreux sponsors, sans qui Asciidoctor ne pourrait pas exister.
+Merci à vous pour votre engagement dans l'amélioration de la documentation technique !
+
+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"]
+
+Asciidoctor est financé majoritairement par nos *Change Makers*, https://developer.okta.com/signup?utm_source=asciidoctor&utm_medium=text-link&utm_campaign=sponsor[Okta] et https://opendevise.com[OpenDevise], ainsi que par nos *Strategy Sponsors*, https://www.khronos.org/[Khronos Group] et Linda Roberts.
+Un apport financier supplémentaire est assuré par https://asciidoctor.org/supporters[la communauté].
+
+Vous pouvez aider ce projet en devant un sponsor sur https://opencollective.com/asciidoctor[OpenCollective].
+
 == En un mot
 
 Asciidoctor lit du contenu écrit en texte brut, comme présenté dans la partie gauche de l'image ci-dessous, et le convertit en HTML5, comme présenté dans la partie droite.
@@ -109,28 +113,35 @@ image::{image-uri-screenshot}[Prévisualisation d'une source AsciiDoc et le rend
 
 == Le traitement d'AsciiDoc
 
-Asciidoctor lit et analyse la syntaxe du texte écrit en AsciiDoc afin de créer une représentation, sous forme d'arbre, à partir de laquelle des templates sont appliqués pour produire de l'HTML5, du DocBook 5 (ou 4.5).
+Asciidoctor lit et analyse la syntaxe du texte écrit en AsciiDoc afin de créer une représentation, sous forme d'arbre, à partir de laquelle des templates sont appliqués pour produire de l'HTML5, du DocBook 5 et des pages de man(uel).
 
 Vous avez la possibilité d'écrire votre propre convertisseur ou de fournir des templates supportant {uri-tilt}[Tilt] pour personnaliser le résultat généré ou pour produire des formats alternatifs.
 
-NOTE: Asciidoctor est un remplaçant du processeur AsciiDoc original écrit en Python (`asciidoc.py`).
-La suite de tests Asciidoctor possède {uri-tests}[> 1,900 tests] pour garantir la compatibilité avec la syntaxe AsciiDoc.
+Asciidoctor remplace le processeur AsciiDoc original écrit en Python (`asciidoc.py`).
+La suite de tests Asciidoctor possède {uri-tests}[plus de 2,000 tests] afin de garantir la compatibilité avec la syntaxe AsciiDoc.
 
 En plus de la syntaxe AsciiDoc standard, Asciidoctor reconnaît des balises additionnelles ainsi que des options de formatage, comme les polices d'icônes (par exemple `+icon:fire[]+`) et des éléments d'interface (par exemple `+button:[Enregistrer]+`).
 Asciidoctor offre aussi un thème moderne et « responsive » basé sur {uri-foundation}[Foundation] pour styliser le document HTML5 généré.
 
+== Asciidoctor est disponible partout où Ruby est disponible
+
+Vous pouvez exécuter Asciidoctor dans la JVM en utilisant JRuby.
+Pour invoquer l'API Asciidoctor directement depuis Java ou d'autres langages de la JVM, utilisez {uri-asciidoctorj}[AsciidoctorJ].
+Des plugins basés sur AsciidoctorJ permettent d'intégrer le processeur Asciidoctor avec Apache Maven, Gradle ou Javadoc.
+
+Asciidoctor s'exécute également au sein de JavaScript.
+Nous utilisons https://opalrb.com[Opal] pour transcrire le code source Ruby en JavaScript afin de produire {uri-asciidoctorjs}[Asciidoctor.js], une version pleinement fonctionnelle d’Asciidoctor qui s’intègre dans tout environnement JavaScript, comme un navigateur web ou Node.js.
+Asciidoctor.js est utilisé pour faire fonctionner les extensions AsciiDoc Preview pour Chrome, Atom, Brackets et autres outils web.
+
 == Prérequis
 
 Asciidoctor fonctionne sur Linux, macOS et Windows et requiert une des implémentations suivantes de {uri-ruby}[Ruby] :
 
 * Ruby (MRI/CRuby 1.8.7 - 2.5)
-* JRuby (1.7 dans les modes Ruby 1.8 et 1.9, 9000)
+* JRuby (1.7 en mode Ruby 1.8 et 1.9, 9000)
 * Rubinius 2.2.x
 * Opal (JavaScript)
 
-Votre aide est appréciée pour tester Asciidoctor sur l'une de ces plateformes.
-Référez-vous au paragraphe <<Contributions>> si vous souhaitez vous impliquer dans ce projet.
-
 [CAUTION]
 ====
 Si vous utilisez un environnement Windows dans une autre langue que l'anglais, vous pourriez tomber sur l'erreur `Encoding::UndefinedConversionError` lors du lancement d'Asciidoctor.
@@ -145,15 +156,63 @@ Asciidoctor fonctionne mieux lorsque vous utilisez UTF-8 partout.
 
 == Installation
 
-Asciidoctor peut être installé en utilisant la commande (a) `gem install`, (b) Bundler, (c) les gestionnaires de paquets pour les distributions Linux populaires, ou (d) Homebrew pour macOS.
+Asciidoctor peut être installé en utilisant (a) un gestionnaire de paquets Linux, (b) Homebrew pour macOS, (c) la commande `gem install` (recommandé pour les utilisateurs Windows), (d) l'image officielle Docker, ou (e) Bundler.
+
+L'avantage d'utiliser le gestionnaire de paquets pour installer la gemme est que l'installation englobe celle des librairies Ruby et RubyGems si elles ne sont pas déjà installées.
+
+=== (a) Gestionnaires de paquets Linux
+
+La version installée par votre gestionnaire de paquets peut ne pas correspondre à la dernière version d'Asciidoctor.
+Consulter le dépôt de votre distribution Linux pour connaitre la dernière version disponible d'Asciidoctor en fonction de la version de votre distribution.
+
+* https://pkgs.alpinelinux.org/packages?name=asciidoctor[Alpine 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)]
+
+Si vous souhaitez installer une version plus récente d'Asciidoctor que celle proposée par votre gestionnaire de paquets, suivre <<gem-install,la procédure d'installation gem>>.
+
+==== apk (Alpine Linux)
+
+Pour installer le paquet sur Alpine Linux, ouvrez un terminal et tapez :
+
+ $ sudo apk add asciidoctor
+
+==== APT
+
+Sur Debian et les distributions dérivées de Debian, comme Ubuntu, utilisez APT pour installer Asciidoctor.
+Pour installer le paquet, ouvrez un terminal et tapez :
+
+ $ sudo apt-get install -y asciidoctor
+
+==== DNF
+
+Sur les distributions Linux qui utilisent des RPM, comme Fedora, CentOS, et RHEL, utilisez le gestionnaire de paquets DNF pour installer Asciidoctor.
+Pour installer le paquet, ouvrez un terminal et tapez :
+
+ $ sudo dnf install -y asciidoctor
+
+=== (b) Homebrew (macOS)
+
+Vous pouvez utiliser Homebrew, le gestionnaire de paquets sur macOS, pour installer Asciidoctor.
+Si vous n'avez pas encore installé Homebrew, suivez les instructions sur https://brew.sh/[brew.sh].
+
+Une fois Homebrew installé, vous pouvez installer Asciidoctor.
+Ouvrez un terminal et tapez :
+
+ $ brew install asciidoctor
 
-TIP: L'avantage d'utiliser le gestionnaire de paquets pour installer la gemme est que l'installation englobe celle des librairies Ruby et RubyGems si elles ne sont pas déjà installés.
-L'inconvénient est que le paquet n'est pas forcément mis à jour immédiatement après la mise à disposition de la gemme.
-Si vous avez besoin de la dernière version, vous devez passer par la commande `gem`.
+Homebrew installe la gemme `asciidoctor` dans un répertoire spécifique qui est indépendant des gemmes système. 
 
-=== (a) Installation de la gemme
+[#gem-install]
+=== (c) gem install
 
-Ouvrir un terminal et taper (en excluant le `$`) :
+Avant d'installer Asciidoctor en utilisant `gem install`, il est recommandé d'utiliser https://rvm.io[RVM] pour installer Ruby dans votre « home » (c'est-à-dire, votre espace utilisateur).
+Ensuite, vous pouvez utiliser la commande `gem` pour installer ou mettre à jour la gemme Asciidoctor.
+Quand vous utilisez RVM, les gemmes sont installées dans un répertoire isolé du système.
+
+Ouvrez un terminal et tapez :
 
  $ gem install asciidoctor
 
@@ -161,20 +220,11 @@ Si vous souhaitez installer une version pre-release (c'est-à-dire, une « rele
 
  $ gem install asciidoctor --pre
 
-.Mettre à jour votre installation
-[TIP]
-====
-Si vous avez une précédente version d'Asciidoctor installée, vous pouvez la mettre à jour en utilisant :
+=== (d) Docker
 
- $ gem update asciidoctor
+Lire {uri-install-docker}[Installer Asciidoctor en utilisant Docker].
 
-Si vous installez une nouvelle version de la gemme en utilisant `gem install` au lieu de `gem update`, vous aurez plusieurs versions d'installées.
-Si c'est le cas, utilisez la commande gem suivante pour supprimer la vieille version :
-
- $ gem cleanup asciidoctor
-====
-
-=== (b) Bundler
+=== (e) Bundler
 
 . Créez un fichier Gemfile à la racine de votre projet (ou du répertoire courant)
 . Ajoutez la gemme `asciidoctor` dans votre fichier Gemfile comme ci-dessous :
@@ -195,85 +245,46 @@ gem 'asciidoctor'
 Pour mettre à jour la gemme, spécifiez la nouvelle version dans le fichier Gemfile et exécutez `bundle` à nouveau.
 Utiliser `bundle update` *n*'est *pas* recommandé car les autres gemmes seront également mises à jour, ce qui n'est pas forcément le résultat voulu.
 
-=== (c) Gestionnaires de paquets Linux
-
-==== DNF (Fedora 21 ou supérieure)
-
-Pour installer la gemme sur Fedora 21 ou supérieure en utilisant dnf, ouvrez un terminal et tapez :
+== Mise à jour
 
- $ sudo dnf install -y asciidoctor
-
-Pour mettre à jour la gemme, utilisez :
-
- $ sudo dnf update -y asciidoctor
+Si vous avez installé Asciidoctor en utilisant votre gestionnaire de paquets, votre système d'exploitation est surement configuré pour mettre à jour automatiquement les paquets, si tel est le cas vous n'avez pas besoin de mettre à jour manuellement Asciidoctor.
 
-TIP: Votre système peut être configuré pour mettre à jour automatiquement les paquets rpm, auquel cas aucune action de votre part ne sera nécessaire pour mettre à jour la gemme.
+=== apk (Alpine Linux)
 
-==== apt-get (Debian, Ubuntu, ou Mint)
+Pour mettre à jour Asciidoctor, tapez :
 
-Pour installer la gemme sur Debian, Ubuntu ou Mint, ouvrez un terminal et tapez :
+ $ sudo apk add -u asciidoctor
 
- $ sudo apt-get install -y asciidoctor
+=== APT
 
-Pour mettre à jour la gemme, utilisez :
+Pour mettre à jour Asciidoctor, tapez :
 
  $ sudo apt-get upgrade -y asciidoctor
 
-TIP: Votre système peut être configuré pour mettre à jour automatiquement les paquets deb, auquel cas aucune action de votre part ne sera nécessaire pour mettre à jour la gemme.
-
-La version d'Asciidoctor installé par le gestionnaire de paquets (apt-get) peut ne pas correspondre à la dernière version d'Asciidoctor.
-Consultez le dépôt de paquets de votre distribution pour trouver quelle version est disponible par version de distribution.
-
-* https://packages.debian.org/search?keywords=asciidoctor&searchon=names&exact=1&suite=all&section=all[Paquet asciidoctor par version de Debian]
-* http://packages.ubuntu.com/search?keywords=asciidoctor&searchon=names&exact=1&suite=all&section=all[Paquet asciidoctor par version d'Ubuntu]
-* https://community.linuxmint.com/software/view/asciidoctor[Paquet asciidoctor par version de Mint]
-
-[CAUTION]
-====
-Il est déconseillé d'utiliser la commande `gem update` pour mettre à jour la gemme gérée par le gestionnaire de paquets.
-Le faire mettrait la système dans un état incohérent car le gestionnaire de paquets ne pourrait plus gérer les fichiers (qui sont installés dans /usr/local).
-En résumé, les gemmes du système doivent être gérées seulement par le gestionnaire de paquets.
-
-Si vous souhaitez utiliser une version d'Asciidoctor qui est plus récente que celle installée par votre gestionnaire de paquets, vous devriez utiliser http://rvm.io[RVM] pour installer Ruby dans votre répertoire personnel (dans votre espace utilisateur).
-Vous pouvez alors utiliser la commande `gem` pour installer ou mettre à jour la gemme Asciidoctor.
-En utilisant RVM, les gemmes sont installées dans un emplacement isolé du système.
-====
-
-==== apk (Alpine Linux)
-
-Pour installer la gemme sur Alpine Linux, ouvrez un terminal et tapez :
-
- $ sudo apk add asciidoctor
-
-Pour mettre à jour la gemme, utilisez :
-
- $ sudo apk add -u asciidoctor
-
-TIP: Votre système peut être configuré pour mettre à jour automatiquement les paquets apk, auquel cas aucune action de votre part ne sera nécessaire pour mettre à jour la gemme.
+=== DNF
 
-=== (d) Homebrew (macOS)
+Pour mettre à jour Asciidoctor, tapez :
 
-Vous pouvez utiliser Homebrew pour installer Asciidoctor sur macOS.
-Si vous n'avez pas encore installé Homebrew, suivez les instructions sur https://brew.sh/[brew.sh].
-
-Une fois Homebrew installé, vous pouvez installer la gemme `asciidoctor` avec le paquet http://brewformulas.org/Asciidoctor[asciidoctor].
-Ouvrez un terminal et tapez :
+ $ sudo dnf update -y asciidoctor
 
- $ brew install asciidoctor
+=== Homebrew (macOS)
 
-Pour mettre à jour la gemme, utilisez :
+Pour mettre à jour Asciidoctor, tapez :
 
  $ brew update
  $ brew upgrade asciidoctor
 
-TIP: Homebrew installe la gemme `asciidoctor` dans un répertoire spécifique qui est indépendant des gemmes système.
+=== gem install
 
-=== Autres options d'installation
+Si vous avez précédemment installé Asciidoctor en utilisant la commande `gem`, vous devez manuellement mettre à jour Asciidoctor quand une nouvelle version est publiée.
+Vous pouvez mettre à jour Asciidoctor en tappant :
 
-* {uri-install-docker}[Installation d'Asciidoctor avec Docker]
-* {uri-install-macos-doc}[Installation d'Asciidoctor sur macOS]
-// pour l'instant, l'entrée suivante est juste une répétition de l'information dans ce README
-//* {uri-install-doc}[Installation de l'outillage Asciidoctor]
+ $ gem install asciidoctor
+
+Quand vous installez une nouvelle version en utilisant `gem install`, vous vous retrouvez avec plusieurs versions installées.
+Utilisez la commande ci-dessous pour supprimer les anciennes versions :
+
+ $ gem cleanup asciidoctor
 
 == Utilisation
 
@@ -370,9 +381,8 @@ Pour plus d'informations sur comment utiliser l'API ou personnaliser le contenu
 
 == Contributions
 
-Dans l'esprit du {uri-freesoftware}[logiciel libre], _tout le monde_ est encouragé à aider en vue d'améliorer le projet.
-Si vous découvrez des erreurs ou des oublis dans le code source, la documentation, ou le contenu du site web, s'il vous plaît n'hésitez pas à ouvrir un ticket ou une « pull request » avec un correctif.
 Les contributeurs et contributrices sont toujours les bienvenus !
+Si vous découvrez des erreurs ou des oublis dans le code source, la documentation, ou le contenu du site web, s'il vous plaît n'hésitez pas à ouvrir un ticket ou une « pull request » avec un correctif.
 
 Voici quelques façons de contribuer :
 
@@ -380,8 +390,7 @@ Voici quelques façons de contribuer :
 * en rapportant des anomalies,
 * en suggérant de nouvelles fonctionnalités,
 * en écrivant ou éditant la documentation,
-* en écrivant des spécifications,
-* en écrivant du code -- _Aucun patch n'est trop petit_
+* en écrivant du code avec des tests -- _Aucun patch n'est trop petit_
 ** corriger une coquille,
 ** ajouter des commentaires,
 ** nettoyer des espaces inutiles,
@@ -394,13 +403,13 @@ Le guide du {uri-contribute}[parfait Contributeur] fournit des informations sur
 
 == Être aidé
 
-Le projet Asciidoctor est développé pour vous aider à écrire et publier du contenu.
-Mais nous ne pouvons pas le faire sans avoir vos avis !
-Nous vous encourageons à poser vos questions et discuter de n'importe quels aspects du projet sur la liste de discussion, Twitter ou dans le salon de discussion.
+Asciidoctor est développé dans le but de vous aider à écrire et publier du contenu.
+Mais nous ne pouvons pas le faire sans vos avis !
+Nous vous encourageons à poser vos questions et à discuter de n'importe quels aspects du projet sur la liste de discussion, Twitter ou dans le salon de discussion.
 
-Mailing list:: {uri-discuss}
+Chat (Gitter):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor]
+Forum (Nabble):: {uri-discuss}
 Twitter:: hashtag https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] ou la mention https://twitter.com/asciidoctor[@asciidoctor]
-Gitter (Chat):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor]
 ////
 IRC (Chat):: {uri-irc}[#asciidoctor] sur FreeNode IRC
 ////
@@ -417,9 +426,9 @@ Dépôt des sources (git):: {uri-repo}
 Gestionnaire de tickets:: {uri-issues}
 L'organisation Asciidoctor sur GitHub:: {uri-org}
 
-== Copyright et licence
+== Licence
 
-Copyright (C) 2012-2018 Dan Allen, Ryan Waldron et le projet Asciidoctor.
+Copyright (C) 2012-2018 Dan Allen, Sarah White et les contributeurs individuels d'Asciidoctor.
 Une utilisation libre de ce logiciel est autorisée sous les termes de la licence MIT.
 
 Consultez le fichier {uri-license}[LICENSE] pour plus de détails.

data/README-jp.adoc

@@ -1,7 +1,6 @@
 = 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:
 :page-layout: base
 :idprefix:
@@ -19,7 +18,7 @@ ifdef::env-github[]
 :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

data/README-zh_CN.adoc

@@ -1,7 +1,6 @@
 = 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:
 :page-layout: base
 :idprefix:
@@ -19,7 +18,7 @@ ifdef::env-github[]
 :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

data/README.adoc

@@ -1,7 +1,6 @@
 = 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: -
@@ -18,12 +17,15 @@ ifdef::env-github[]
 :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
@@ -55,20 +57,24 @@ endif::[]
 :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[日本語]
@@ -99,7 +105,7 @@ image:https://www.okta.com/sites/all/themes/Okta/images/blog/Logos/Okta_Logo_Bri
 &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].
@@ -113,10 +119,10 @@ image::{image-uri-screenshot}[Preview of AsciiDoc source and corresponding rende
 
 == 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]+`).
@@ -126,11 +132,12 @@ Asciidoctor also offers a modern, responsive theme based on {uri-foundation}[Fou
 
 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
 
@@ -141,9 +148,6 @@ Asciidoctor works on Linux, macOS and Windows and requires one of the following
 * 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.
@@ -158,15 +162,88 @@ 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.
+
+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) Linux package managers
+
+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
 
-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.
+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:
 
-=== (a) gem install
+ $ 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>>.
 
-Open a terminal and type (excluding the leading `$`):
+[#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
 
@@ -174,20 +251,11 @@ 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:
-
- $ gem cleanup asciidoctor
-====
-
-=== (b) Bundler
+=== (f) Bundler
 
 . Create a Gemfile in the root folder of your project (or the current directory)
 . Add the `asciidoctor` gem to your Gemfile as follows:
@@ -206,86 +274,48 @@ gem 'asciidoctor'
  $ 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.
-
-=== (c) Linux package managers
+Using `bundle update` (without specifying a gem) is *not* recommended as it will also update other gems, which may not be the desired result.
 
-==== DNF (Fedora 21 or greater)
+== Upgrade
 
-To install the gem on Fedora 21 or greater using dnf, open a terminal and type:
+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.
 
- $ sudo dnf install -y asciidoctor
+=== apk (Alpine Linux)
 
 To upgrade the gem, use:
 
- $ sudo dnf update -y 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-get (Debian or Ubuntu)
-
-To install the gem on Debian or Ubuntu, open a terminal and type:
+ $ sudo apk add -u asciidoctor
 
- $ sudo apt-get install -y asciidoctor
+=== APT
 
 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.
-
-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
+=== DNF
 
 To upgrade the gem, use:
 
- $ sudo apk add -u 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.
-
-=== (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:
+ $ sudo dnf update -y asciidoctor
 
- $ brew install asciidoctor
+=== Homebrew (macOS)
 
 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
+
+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:
+
+ $ gem install asciidoctor
 
-=== Other installation options
+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:
 
-* {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 cleanup asciidoctor
 
 == Usage
 
@@ -299,7 +329,7 @@ You should see information about the Asciidoctor version and your Ruby environme
 [.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.
@@ -382,9 +412,8 @@ For more information about how to use the API or to customize the output, refer
 
 == 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:
 
@@ -392,8 +421,7 @@ Here are some ways *you* can contribute:
 * 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
@@ -406,16 +434,13 @@ The {uri-contribute}[Contributing] guide provides information on how to create,
 
 == 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.
@@ -429,19 +454,19 @@ 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