README.adoc in asciidoctor-1.5.4 vs README.adoc in asciidoctor-1.5.5

- old
+ new

@@ -1,30 +1,30 @@ = Asciidoctor Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]> -v1.5.4, 2016-01-05 +v1.5.5, 2016-10-05 // settings: :page-layout: base :idprefix: :idseparator: - :source-language: ruby :language: {source-language} -ifdef::env-github[:badges:] +ifdef::env-github[:status:] // URIs: :uri-org: https://github.com/asciidoctor :uri-repo: {uri-org}/asciidoctor :uri-asciidoctorj: {uri-org}/asciidoctorj :uri-asciidoctorjs: {uri-org}/asciidoctor.js :uri-project: http://asciidoctor.org -ifdef::awestruct-version[:uri-project: link:] +ifdef::env-site[:uri-project: link:] :uri-docs: {uri-project}/docs :uri-news: {uri-project}/news :uri-manpage: {uri-project}/man/asciidoctor :uri-issues: {uri-repo}/issues :uri-contributors: {uri-repo}/graphs/contributors :uri-rel-file-base: link: :uri-rel-tree-base: link: -ifdef::awestruct-version[] +ifdef::env-site[] :uri-rel-file-base: {uri-repo}/blob/master/ :uri-rel-tree-base: {uri-repo}/tree/master/ endif::[] :uri-changelog: {uri-rel-file-base}CHANGELOG.adoc :uri-contribute: {uri-rel-file-base}CONTRIBUTING.adoc @@ -52,10 +52,17 @@ {uri-project}/[Asciidoctor] is a _fast_ text processor and publishing toolchain for converting {uri-what-is-asciidoc}[AsciiDoc] content to HTML5, DocBook 5 (or 4.5) and other formats. Asciidoctor is written in Ruby, packaged as a RubyGem and published to {uri-rubygem}[RubyGems.org]. The gem is also included in several Linux distributions, including Fedora, Debian and Ubuntu. Asciidoctor is open source, {uri-repo}[hosted on GitHub] and released under {uri-license}[the MIT license]. +ifndef::env-site[] +.Translations of this document are available in the following languages: +* {uri-rel-file-base}README-zh_CN.adoc[汉语] +* {uri-rel-file-base}README-fr.adoc[Français] +* {uri-rel-file-base}README-jp.adoc[日本語] +endif::[] + .Key documentation [.compact] * {uri-docs}/what-is-asciidoc[What is Asciidoc?] * {uri-docs}/asciidoc-writers-guide[AsciiDoc Writer's Guide] * {uri-docs}/asciidoc-syntax-quick-reference[AsciiDoc Syntax Reference] @@ -70,14 +77,14 @@ Asciidoctor also runs in JavaScript. We use http://opalrb.org[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. **** -ifdef::badges[] +ifdef::status[] .*Project health* -image:https://img.shields.io/travis/asciidoctor/asciidoctor/master.svg[Build Status (Travis CI), link=https://travis-ci.org/asciidoctor/asciidoctor] -image:https://ci.appveyor.com/api/projects/status/ifplu67oxvgn6ceq/branch/master?svg=true&amp;passingText=green%20bar&amp;failingText=%23fail&amp;pendingText=building%2E%2E%2E[Build Status (AppVeyor), link=https://ci.appveyor.com/project/asciidoctor/asciidoctor] +image:https://img.shields.io/travis/asciidoctor/asciidoctor/master.svg[Build Status (Travis CI), link=https://travis-ci.org/asciidoctor/asciidoctor] +image:https://ci.appveyor.com/api/projects/status/ifplu67oxvgn6ceq/branch/master?svg=true&amp;passingText=green%20bar&amp;failingText=%23fail&amp;pendingText=building%2E%2E%2E[Build Status (AppVeyor), link=https://ci.appveyor.com/project/asciidoctor/asciidoctor] //image:https://img.shields.io/coveralls/asciidoctor/asciidoctor/master.svg[Coverage Status, link=https://coveralls.io/r/asciidoctor/asciidoctor] image:https://codeclimate.com/github/asciidoctor/asciidoctor/badges/gpa.svg[Code Climate, link="https://codeclimate.com/github/asciidoctor/asciidoctor"] image:https://inch-ci.org/github/asciidoctor/asciidoctor.svg?branch=master[Inline docs, link="https://inch-ci.org/github/asciidoctor/asciidoctor"] endif::[] @@ -99,20 +106,32 @@ 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. == Requirements -Asciidoctor works on Linux, OSX (Mac) and Windows and requires one of the following implementations of {uri-ruby}[Ruby]: +Asciidoctor works on Linux, OS X (Mac) and Windows and requires one of the following implementations of {uri-ruby}[Ruby]: -* MRI (Ruby 1.8.7, 1.9.3, 2.0, 2.1 & 2.2) -* JRuby 1.7 (Ruby 1.8 and 1.9 modes) & 9000 +* MRI (Ruby 1.8.7, 1.9.3, 2.0, 2.1, 2.2 & 2.3) +* 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 <<{idprefix}contributing,Contributing>> to learn how to get involved. +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: + + chcp 65001 + +Once you make this change, all your Unicode headaches will be behind you. +If you're using an IDE like Eclipse, make sure you set the encoding to UTF-8 there as well. +Asciidoctor works best when you use UTF-8 everywhere. +==== + == Installation Asciidoctor can be installed using (a) the `gem install` command, (b) Bundler or (c) package managers for popular Linux distributions. 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. @@ -150,11 +169,11 @@ [source] ---- source 'https://rubygems.org' gem 'asciidoctor' # or specify the version explicitly -# gem 'asciidoctor', '1.5.3' +# gem 'asciidoctor', '1.5.5' ---- . Save the Gemfile . Open a terminal and install the gem using: @@ -163,34 +182,64 @@ 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 -==== Yum (Fedora 21 or greater) +==== DNF (Fedora 21 or greater) -To install the gem on Fedora 21 or greater using yum, open a terminal and type: +To install the gem on Fedora 21 or greater using dnf, open a terminal and type: - $ sudo yum install -y asciidoctor + $ sudo dnf install -y asciidoctor To upgrade the gem, use: - $ sudo yum update -y asciidoctor + $ sudo dnf update -y asciidoctor -TIP: Your Fedora system may be configured to automatically update packages, in which case no action is required by you to update the gem. +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 Sid, Ubuntu Saucy or greater) +==== apt-get (Debian, Ubuntu, Mint) -To install the gem on Debian or Ubuntu, open a terminal and type: +To install the gem on Debian, Ubuntu or Mint, open a terminal and type: $ sudo apt-get install -y asciidoctor To upgrade the gem, use: $ sudo apt-get upgrade -y asciidoctor -TIP: Your Debian or Ubuntu system may be configured to automatically update packages, in which case no action is required by you to update the gem. +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] +* http://packages.ubuntu.com/search?keywords=asciidoctor&searchon=names&exact=1&suite=all&section=all[asciidoctor package by Ubuntu release] +* https://community.linuxmint.com/software/view/asciidoctor[asciidoctor package by Mint 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 http://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 + +TIP: Your system may be configured to automatically update apk packages, in which case no action is required by you to update the gem. + === Other installation options * {uri-install-docker}[Installing Asciidoctor using Docker] * {uri-install-osx-doc}[Installing Asciidoctor on Mac OS X] // at the moment, the following entry is just a reiteration of the information in this README @@ -205,11 +254,11 @@ You should see information about the Asciidoctor version and your Ruby environment printed in the terminal. [.output] .... -Asciidoctor 1.5.3 [http://asciidoctor.org] +Asciidoctor 1.5.5 [http://asciidoctor.org] Runtime Environment (ruby 2.2.2p95 [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]). @@ -282,11 +331,11 @@ Keep in mind that if you don't like the output Asciidoctor produces, _you can change it!_ Asciidoctor supports custom converters that can handle converting from the parsed document to the generated output. One easy way to customize the output piecemeal is by using the template converter. -The template converter allows you uses supply a {uri-tilt}[Tilt]-supported template file to handle converting any node in the document. +The template converter allows you to supply a {uri-tilt}[Tilt]-supported template file to handle converting any node in the document. 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 @@ -314,17 +363,19 @@ 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. -But we can't do that without your feedback! -We encourage you to ask questions and discuss any aspects of the project on the discussion list, Twitter or IRC. +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. -Mailing list:: {uri-discuss} -Twitter (Chat):: #asciidoctor hashtag -Gitter (Chat):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor] -IRC (Chat):: {uri-irc}[#asciidoctor] on FreeNode IRC +Discussion list (Nabble):: {uri-discuss} +Twitter:: #asciidoctor hashtag or @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] @@ -350,10 +401,63 @@ *AsciiDoc* was started by Stuart Rackham and has received contributions from many other individuals in the AsciiDoc community. == Changelog +== 1.5.5 (2016-10-05) - @mojavelinux + +Enhancements:: + * Add preference to limit the maximum size of an attribute value (#1861) + * Honor SOURCE_DATE_EPOCH environment variable to accomodate reproducible builds (@JojoBoulix) (#1721) + * Add reversed attribute to ordered list if reversed option is enabled (#1830) + * Add support for additional docinfo locations (e.g., :header) + * Configure default stylesheet to break monospace word if exceeds length of line; add roles to prevent breaks (#1814) + * Introduce translation file for built-in labels (@ciampix) + * Provide translations for built-in labels (@JmyL - kr, @ciampix - it, @ivannov - bg, @maxandersen - da, @radcortez - pt, @eddumelendez - es, @leathersole - jp, @aslakknutsen - no, @shahryareiv - fa, @AlexanderZobkov - ru, @dongwq - zh, @rmpestano - pt_BR, @ncomet - fr, @lgvz - fi, @patoi - hu, @BojanStipic - sr, @fwilhe - de, @rahmanusta - tr, @abelsromero - ca, @aboullaite - ar, @roelvs - nl) + * Translate README to Chinese (@diguage) + * Translate README to Japanese (@Mizuho32) + +Improvements:: + * Style nested emphasized phrases properly when using default stylesheet (#1691) + * Honor explicit table width even when autowidth option is set (#1843) + * Only explicit noheader option on table should disable implicit table header (#1849) + * Support docbook orient="land" attribute on tables (#1815) + * Add alias named list to retrieve parent List of ListItem + * Update push_include method to support chaining (#1836) + * Enable font smoothing on Firefox on OSX (#1837) + * Support combined use of sectanchors and sectlinks in HTML5 output (#1806) + * fix API docs for find_by + * Upgrade to Font Awesome 4.6.3 (@allenan, @mogztter) (#1723) + * README: add install instructions for Alpine Linux + * README: Switch yum commands to dnf in README + * README: Mention Mint as a Debian distro that packages Asciidoctor + * README: Add caution advising against using gem update to update a system-managed gem (@oddhack) + * README: sync French version with English version (@flashcode) + * Add missing endline after title element when converting open block to HTML + * Move list_marker_keyword method from AbstractNode to AbstractBlock + * Rename definition list to description list internally + +Compliance:: + * Support 6-digit decimal char refs, 5-digit hexidecimal char refs (#1824) + * Compatibility fixes for Opal + * Check for number using Integer instead of Fixnum class for compatibility with Ruby 2.4 + +Bug fixes:: + * Use method_defined? instead of respond_to? to check if method is already defined when patching (#1838) + * Fix invalid conditional in HTML5 converter when handling of SVG + * Processor#parse_content helper no longer shares attribute list between blocks (#1651) + * Fix infinite loop if unordered list marker is immediately followed by a dot (#1679) + * Don't break SVG source when cleaning if svg start tag name is immediately followed by endline (#1676) + * Prevent template converter from crashing if .rb file found in template directory (#1827) + * Fix crash when generating section ID when both idprefix & idseparator are blank (#1821) + * Use stronger CSS rule for general text color in Pygments stylesheet (#1802) + * Don't duplicate forward slash for path relative to root (#1822) + +Infrastructure:: + * Build gem properly in the absense of a git workspace, make compatible with JRuby (#1779) + * Run tests in CI using latest versions of Ruby, including Ruby 2.3 (@ferdinandrosario) + == 1.5.4 (2016-01-03) - @mojavelinux Enhancements:: * translate README into French (@anthonny, @mogztter, @gscheibel, @mgreau) (#1630) * allow linkstyle in manpage output to be configured (#1610) @@ -427,11 +531,11 @@ * insert toc at default location in embeddable HTML (#1443) * replace _ and - in generated alt text for inline images * restore attributes to header attributes after parse (#1255) * allow docdate and doctime to be overridden (#1495) * add CSS class `.center` for center block alignment (#1456) - * recognize U+2022 as alternative marker for unordered lists (@mogztter) (#1177) + * recognize U+2022 (bullet) as alternative marker for unordered lists (@mogztter) (#1177) * allow videos to work for local files by prepending asset-uri-scheme (Chris) (#1320) * always assign playlist param when loop option is enabled for YouTube video * parse isolated version in revision line (@bk2204) (#790) * autoload Tilt when template converter is instantiated (#1313) * don't overwrite existing id entry in references table (#1256) @@ -452,10 +556,11 @@ * add helper to calculate basename without file extension * document `-I` and `-r` options in the manual page (@bk2204) * fix `+--help+` output text for `-I` (@bk2204) * don't require open-uri-cached if already loaded * do not attempt to scan pattern of non-existent directory in template converter + * prevent CodeRay from bolding every 10th line number Compliance:: * use `<sup>` for footnote reference in text instead of `<span>` (#1523) * fix alignment of wrapped text in footnote (#1524) * include full stop after footnote number in embeddable HTML @@ -493,50 +598,7 @@ * migrate opal_ext from core to Asciidoctor.js (#1517) * add Ruby 2.2 to CI build; only specify minor Ruby versions * enable containerized builds on Travis CI * add config to run CI build on AppVeyor * exclude benchmark folder from gem (#1522) - -== 1.5.2 (2014-11-27) - @mojavelinux - -Enhancements:: - - * add docinfo extension (@mogztter) (#1162) - * allow docinfo to be in separate directory from content, specified by `docinfodir` attribute (@mogztter) (#511) - * enable TeX equation auto-numbering if `eqnums` attribute is set (@jxxcarlson) (#1110) - -Improvements:: - - * recognize `+--+` as valid line comment for callout numbers; make line comment configurable (#1068) - * upgrade highlight.js to version 8.4 (#1216) - * upgrade Font Awesome to version 4.2.0 (@clojens) (#1201) - * define JAVASCRIPT_PLATFORM constant to simplify conditional logic in the JavaScript environment (#897) - * provide access to destination directory, outfile and outdir via Document object (#1203) - * print encoding information in version report produced by `asciidoctor -v` (#1210) - * add intrinsic attribute named `cpp` with value `pass:[C++]` (#1208) - * preserve URI targets passed to `stylesheet` and related attributes (#1192) - * allow numeric characters in block attribute name (#1103) - * support custom YouTube playlists (#1105) - * make start number for unique id generation configurable (#1148) - * normalize and force UTF-8 encoding of docinfo content (#831) - * allow subs and default_subs to be specified in Block constructor (#749) - * enhance error message when reading binary input files (@mogztter) (#1158) - * add `append` method as alias to `<<` method on AbstractBlock (#1085) - * assign value of `preface-title` as title of preface node (#1090) - * fix spacing around checkbox in checklist (#1138) - * automatically load Slim's include plugin when using slim templates (@jirutka) (#1151) - * mixin Slim helpers into execution scope of slim templates (@jirutka) (#1143) - * improve DocBook output for manpage doctype (@bk2204) (#1134, #1142) - -Compliance:: - - * substitute attribute entry value in attributes defined outside of header (#1130) - * allow empty cell to appear at end of table row (#1106) - * only produce one row for table in CSV or DSV format with a single cell (#1180) - -Bug fixes:: - - * add explicit to_s call to generate delimiter settings for MathJax config (#1198) - * fix includes that reference absolute Windows paths (#1144) - * apply DSL to extension block in a way compatible with Opal Refer to the {uri-changelog}[CHANGELOG] for a complete list of changes in older releases.