asciidoctor.adoc in asciidoctor-1.5.6

- old
+ new

@@ -1,10 +1,10 @@
 = asciidoctor(1)
 Dan Allen; Sarah White; Ryan Waldron
 :doctype: manpage
 :man manual: Asciidoctor Manual
-:man source: Asciidoctor 1.5.5
+:man source: Asciidoctor 1.5.6
 :page-layout: base
 
 == NAME
 
 asciidoctor - converts AsciiDoc source files to HTML, DocBook and other formats
@@ -24,46 +24,46 @@
 === Security Settings
 
 *-B, --base-dir*=_DIR_::
   Base directory containing the document and resources.
   Defaults to the directory containing the source file, or the working directory if the source is read from a stream.
-  Can be used as a way to chroot the execution of the program.
+  When combined with the safe mode setting, can be used to chroot the execution of the program.
 
 *-S, --safe-mode*=_SAFE_MODE_::
   Set safe mode level: _unsafe_, _safe_, _server_ or _secure_.
   Disables potentially dangerous macros in source files, such as `include::[]`.
   If not set, the safe mode level defaults to _unsafe_ when Asciidoctor is invoked using this script.
 
 *--safe*::
   Set safe mode level to _safe_.
-  Enables include macros, but restricts access to ancestor paths of source file.
+  Enables include directives, but prevents access to ancestor paths of source file.
   Provided for compatibility with the asciidoc command.
   If not set, the safe mode level defaults to _unsafe_ when Asciidoctor is invoked using this script.
 
 === Document Settings
 
 *-a, --attribute*=_ATTRIBUTE_::
   Define, override or delete a document attribute.
-  Command-line attributes take precedence over attributes defined in the source file.
+  Command-line attributes take precedence over attributes defined in the source file unless the value ends with _@_.
 +
 _ATTRIBUTE_ is normally formatted as a key-value pair, in the form _NAME=VALUE_.
 Alternate acceptable forms are _NAME_ (where the _VALUE_ defaults to an empty string), _NAME!_ (unassigns the _NAME_ attribute) and _NAME=VALUE@_ (where _VALUE_ does not override value of _NAME_ attribute if it's already defined in the source document).
 Values containing spaces should be enclosed in quotes.
 +
 This option may be specified more than once.
 
 *-b, --backend*=_BACKEND_::
   Backend output file format: _html5_, _docbook5_, _docbook45_ and _manpage_ are supported out of the box.
   You can also use the backend alias names _html_ (aliased to _html5_) or _docbook_ (aliased to _docbook5_).
+  Other values can be passed, but if Asciidoctor cannot resolve the backend to a converter, it will fail.
   Defaults to _html5_.
-  Other options can be passed, but if Asciidoctor cannot find the backend, it will fail during conversion.
 
 *-d, --doctype*=_DOCTYPE_::
   Document type: _article_, _book_, _manpage_ or _inline_.
   Sets the root element when using the _docbook_ backend and the style class on the HTML body element when using the _html_ backend.
   The _book_ document type allows multiple level-0 section titles in a single document.
-  The _manpage_ document type enables parsing of metadata necessary to produce a manpage.
+  The _manpage_ document type enables parsing of metadata necessary to produce a man page.
   The _inline_ document type allows the content of a single paragraph to be formatted and returned without wrapping it in a containing element.
   Defaults to _article_.
 
 === Rendering Control
 
@@ -96,13 +96,13 @@
   Synonym for *--attribute numbered*.
 
 *-o, --out-file*=_OUT_FILE_::
   Write output to file _OUT_FILE_.
   Defaults to the base name of the input file suffixed with _backend_ extension.
-  If the input is read from standard input, then the output file defaults to stdout.
-  If _OUT_FILE_ is _-_ then the standard output is also used.
-  If specified, the file is resolved relative to the working directory.
+  The file is resolved relative to the working directory.
+  If the input is read from standard input or a named pipe (fifo), then the output file defaults to stdout.
+  If _OUT_FILE_ is _-_, then the output file is written to standard output.
 
 *-r, --require*=_LIBRARY_::
   Require the specified library before executing the processor, using the standard Ruby require.
   This option may be specified more than once.
 
@@ -134,21 +134,23 @@
 *-t, --timings*::
   Display timings information (time to read, parse and convert).
 
 === Program Information
 
-*-h, --help*::
-  Show the help message.
+*-h, --help* [_TOPIC_]::
+  Print the help message.
+  Show the command usage if _TOPIC_ is not specified (or not recognized).
+  Dump the Asciidoctor man page (in troff/groff format) if _TOPIC_ is _manpage_.
 
 *-V, --version*::
   Print program version number.
 +
 `-v` can also be used if no other flags or arguments are present.
 
 == ENVIRONMENT
 
-*Asciidoctor* honors the SOURCE_DATE_EPOCH environment variable.
+*Asciidoctor* honors the *SOURCE_DATE_EPOCH* environment variable.
 If this variable is assigned an integer value, that value is used as the epoch of all input documents and as the local date and time.
 See https://reproducible-builds.org/specs/source-date-epoch/ for more information about this environment variable.
 
 == EXIT STATUS
 
@@ -178,7 +180,7 @@
 
 *Discussion list / forum:* http://discuss.asciidoctor.org
 
 == COPYING
 
-Copyright \(C) 2012-2016 Dan Allen, Ryan Waldron and the Asciidoctor Project.
+Copyright \(C) 2012-2017 Dan Allen, Ryan Waldron and the Asciidoctor Project.
 Free use of this software is granted under the terms of the MIT License.