//== Application Messages

// Only includes the CLI. asciidoctorj and the asciidoctor API are not included.
// When there are enough documented, maybe add another table for them. Although these users are programmers-wouldn't they just run it in the debugger?

////
Testing was carried out with
Asciidoctor 1.5.5 [https://asciidoctor.org]
Runtime Environment (ruby 2.3.1p112 (2016-04-26) [i386-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
////

All warning, error, and failure messages emitted by the Asciidoctor CLI (i.e., `asciidoctor`) are listed in the table below.
These messages are written to the console via stderr (i.e., standard error).
Most messages also apply to the API, though keep in mind they're written directly to stderr.

//.Legend
//--
.Placeholders
//[horizontal]
<docname>;; represents the basename of the source file being processed (e.g., `sample.adoc`).
<file>;; represents a path to the input file or other referenced file.
<uri>;; represents a URI being referenced.
<x> or <y>;; placeholders for other contextual information in the message.

.Categories
//[horizontal]
ERROR;; Errors do not stop conversion, but the output document will almost certainly be wrong.
FAILURE;; Failures are fatal; no output document will be produced.
WARNING;; Warnings do not stop conversion, but they indicate possible problems, and the output may not be what you were expecting.
//--

.List of Application Messages
[options="header,breakable",cols="<20,<60,<50,<30"]
|===
|Category |Message |Cause |See also

|ERROR
|input file <file> missing or cannot be read
|Check that the file exists and that the filename is not misspelled.
|<<using-the-command-line-interface>>

|ERROR
|include file has illegal reference to ancestor of jail, auto-recovering
|The safe mode is restricting access to an include file outside of the base directory.
|<<running-asciidoctor-securely>>

|ERROR
|input file and output file cannot be the same: <file>
|Choose a different output directory or filename.
|

|ERROR
|partintro block can only be used when doctype is book and it\'s a child of a part section. Excluding block content.
|Invalid book document structure.
|<<book-parts-and-chapters>>

|ERROR
|unmatched macro: endif::<x>[]
|`endif::[]` with no unclosed preceding `ifdef::<x>[]`.
|<<ifdef-directive>>

|ERROR
|<docname> dropping cell because it exceeds specified number of columns
// The extra cells are dropped, but this message is not produced ???
|
|<<tables>>

|ERROR
|<docname> illegal block content outside of partintro block
|Invalid book document structure.
|<<book-parts-and-chapters>>

|ERROR
|<docname> invalid part, must have at least one section (e.g., chapter, appendix, etc.)
|Invalid book document structure.
|<<book-parts-and-chapters>>

|ERROR
|<docname> malformed manpage title
|Invalid man page document structure.
|<<man-pages>>

|ERROR
|<docname> malformed name section body
|Invalid man page document structure.
|<<man-pages>>

|ERROR
|<docname> maximum include depth of 64 exceeded
|Does your file include itself, directly or indirectly?
|

// This is not explicit the docs

|ERROR
|<docname> mismatched macro: endif::<x>[], expected endif::<y>[]
|ifdef/endif blocks must be strictly nested.
|<<ifdef-directive>>

|ERROR
|<docname> name section expected
|Invalid man page document structure.
|<<man-pages>>

|ERROR
|<docname> name section title must be at level 1
|Invalid man page document structure.
|<<man-pages>>

|ERROR
|<docname> only book doctypes can contain level 0 sections
|Illegal use of a level-0 section when doctype is not book.
|<<sections>>

|ERROR
|<docname> table missing leading separator, recovering automatically
|Check for missing cell separator characters at the start of the line.
|<<tables>>

|FAILED
|missing converter for backend '<x>'. Processing aborted. (RuntimeError)
|You used -b with an invalid or missing backend.
|

//|FAILED
//|Failed to load AsciiDoc document - undefined method `convert' for nil:NilClass
//|
//|<<cli-options>>

|FAILED
|'tilt' could not be loaded
|You must have the tilt gem installed (`gem install tilt`) to use custom backend templates
|

|WARNING
|abstract block cannot be used in a document without a title when doctype is book. Excluding block content.
|Invalid book document structure.
|<<user-abstract>>

|WARNING
|cannot retrieve contents of <x> at URI: <uri> (allow-uri-read attribute not enabled)
|Reading from a URI is only allowed in certain safe modes and the allow-uri-read attribute must be passed to the application.
|<<include-uri>>

|WARNING
|could not retrieve contents of <x> at URI: <uri>
|Web address not found.
|

|WARNING
|could not retrieve image data from URI: <uri>
|Web address not found. Only occurs with `allow-uri-read` and `data-uri`. Check the URI.
|<<include-images-by-full-url>>

|WARNING
|dropping line containing reference to missing attribute: <x>
|An attribute cannot be resolved and the `attribute-missing` attribute is set to `drop-line`.
|<<catch-a-missing-or-undefined-attribute>>

|WARNING
|file does not exist or cannot be read: <file>
|You specified a stylesheet (`-a stylesheet=<file>`) but <file> does not exist or is not readable.
|

|WARNING
|gem 'thread_safe' is not installed. This gem is recommended when registering custom converters.
|You have registered a custom converter, and you have not installed the thread_safe gem.
|

|WARNING
|gem 'thread_safe' is not installed. This gem is recommended when using custom backend templates.
|You are using custom templates (`-T <template_dir>`), but you have not installed the thread_safe gem.
|

|WARNING
|image to embed not found or not readable: <file>
|You used `:data-uri:` but the file could not be found.
|<<managing-images>>

|WARNING
|include file not readable: <file>
|You do not have permission to access the file.
|<<include-nonasciidoc>>

|WARNING
|input path <file> is a <x>, not a file
|The path is not a file (perhaps it is a socket or a block device).
|<<include-nonasciidoc>>

|WARNING
|optional gem 'asciimath' is not installed. Functionality disabled.
|asciimath is one of the libraries used for equations.
|<<stem>>

|WARNING
|optional gem 'coderay' is not installed. Functionality disabled.
|CodeRay is used for source code highlighting.
|<<coderay>>

|WARNING
|skipping reference to missing attribute: <x>
|An attribute cannot be resolved and the `attribute-missing` attribute is set to `skip`.
|<<catch-a-missing-or-undefined-attribute>>

|WARNING
|tables must have at least one body row
|
|<<tables>>

|WARNING
|tag '<x>' not found in include file: <file>
|You tried to include by tagged region, but the included document does not have that tag.
|<<include-partial>>

|WARNING
|<docname>: id assigned to <type> already in use: <id>
|<id> is a duplicate ID, meaning it has already been assigned to a node of <type> (e.g., section, block, anchor).
If you don't see the problem in <docname>, check that the duplicate ID isn't coming from a file which is being included.
|

|WARNING
|<docname> callout list item index: expected <x> got <y>
|Callouts are expected to be in numerical order, just like any ordered list.
|<<callouts>>

|WARNING
|<docname> include <x> not readable: <y>
|If <y> is a file, do you have read permissions for it?
If it is a URI and `-a allow-uri-read` is set, does it exist?
|
|WARNING
|<docname> include file not found: <file>
|Probably a typo or missing file. If not, make sure you understand the search process.
|<<include-directive>>, <<include-resolution>>

|WARNING
|<docname> invalid empty <x> detected in style attribute
|The first positional attribute in the block attributes could not be parsed.
|<<options>>

|WARNING
|<docname> invalid style for <x> block: <y>
|You have added a custom style to a block, but you haven't registered a custom block extension to handle it.
|

|WARNING
|<docname> invalid style for paragraph: <x>
|You have a line `[xxx]` before a paragraph, but `xxx` isn't one of the built-in styles.
|<<style>>

|WARNING
|<docname> list item index: expected <x>, got <y>
|You gave explicit numbers on an ordered list, but they were not sequential. Asciidoctor renumbers them for you, and gives this warning.
|<<ordered-lists>>

|WARNING
|<docname> multiple ids detected in style attribute
|Multiple IDs cannot be specified in the block style (e.g., `[#cat#dog]`).
// But [#wibble,id="wobble"] does not generate an error
|<<id>>

|WARNING
|<docname> no callouts refer to list item <x>
|The callout is missing or not recognized.
In source listings, is the callout the last thing on the line?
|<<callouts>>

|WARNING
|<docname> section title out of sequence
|Invalid document structure. Check section levels.
|<<sections>>

|===

////
API only

|ERROR
|IOError, %(target directory does not exist: #{to_dir})
|API, the mkdirs option is not set, and the target directory does not already exist.
|
////
