Troubleshooting

There can be many reasons why you can’t compile a Metanorma AsciiDoc document into the final output, but you can easily fix them when you are familiar with typical errors.

Metanorma tells you what’s wrong in the terminal while it is building the document. The errors are also stored in an Error file .err in the same directory where your original document is stored, so you can debug them later.

How to troubleshoot a document

The best way to troubleshoot a document is to break up the content in several parts to narrow down the location of the error. Regardless of troubleshooting, it is a good practice to divide a document into sections. You can then compile each section separately, or compile several of them in order to locate the error easier. For example, if you assume there could be some error in Foreword section and want to exclude it from being rendered, you can easily comment out the section.

Example for a modular document setup

`Header with Metadata...``

`//include::sections/00-foreword.adoc[]`

`include::sections/01-introduction.adoc[]`
`include::sections/02-scope.adoc[]`
...

Where to start troubleshooting?

If the document did not compile:
If Metanorma did not generate any visual output, you need to work with the errors in the terminal. If execution has aborted before the XML content could be finalised, the XML file is still output to disk, suffixed with .xml.abort rather than .xml, and you can use it to make sense of error messages.
If the document did compile and generated visual output:
Have a look at the compiled output: Are there missing sections? Is the formatting different than what you expected? Sometimes you can catch errors by looking at the rendered document. After that, have a look at the errors on the terminal to pinpoint where things went wrong.

Markup errors

Metanorma can’t compile a document, when required information is missing or there are markup errors.

Header lacks required metadata

Metanorma can’t compile documents when the core metadata of a document are missing or incomplete. Metanorma will not render a document if one or more attributes are missing or contain unknown values:

Type of flavor :mn-document-class:, for example iso, ietf, un, etc.
If the document flavor isn’t specified in the header, it needs to be specified in the build command, or else the compilation will fail.
Document type :doctype:, for example international standard
If the document type isn’t specified in the header, it needs to be specified in the build command, or else the compilation will fail.
Metadata specific to your organization. Check the flavor documentation to make sure you’ve entered the metadata correctly.

A single double quotation mark inside of a stem block

Double quotation marks are used in stem blocks to denote normal text, e.g.: stem:["normal text"] An odd number of double quotation marks inside a stem block will provoke a compilation error.

For example, stem:["normal text""] leads to the following compilation error:

...
        from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-cli-1.4.6/exe/metanorma:20:in `<top (required)>'
        from C:/tools/ruby25/lib/ruby/gems/2.5.0/bin/metanorma:23:in `load'
        from C:/tools/ruby25/lib/ruby/gems/2.5.0/bin/metanorma:23:in `<main>'
parsing: "normal text""
undefined method `[]' for nil:NilClass

An external file is not found

Metanorma can’t compile a document when a reference to an external file cannot be found (i.e., an image or any other type of file). The error message will be explicit on which file. You can solve the roblem by checking the specified location of the file.

Two or more cross-references have the same anchor

If two or more cross-references have the same anchor, the document won’t build and the error message will be clear on the reason.

Example of the same anchor name

[[anchor1]]
== Section 1
...

[[anchor1]]
== Section 2
...

To solve this problem, rename the anchor. Check your document against any references for the anchor that you changed and update them.

Rendering errors

The main cause for rendering errors are markup errors which can lead to unexpected rendering results. Some issues can be:

Title page is missing information

If your title page is missing completely, or only shows parts, check the document attributes in the header. If metadata, like the title, is missing, the document will be rendered faulty.

Document starts to look odd from one point onwards

AsciiDoc requires block delimiters for some block types, such as code samples and tables. The block delimiter consists of a minimum of four characters. If the number or type of block delimiters don’t match, the compiler doesn’t know where a block begins/ends.

Look for the beginning of the issue, go to the markup, and check out the delimiting characters of the blocks.

Examples of faulty blocks

[source,Asciidoc]
=== (1)
image::../assets/image.png[]
===

|== (2)
|Name of Column 1
|Name of Column 2

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|--- (3)

The author wanted to demonstrate how to insert an image using AsciiDoc markup. However, the compiler will insert the image (if it exists) because of the missing =.
The block delimiter is only three characters long, so the compiler will not render the table.
|--- This delimiter is invalid.

Paragraphs look like code blocks

If you ever see a paragraph rendered inside of a source block, you probably have left a white space at its beginning. Paragraphs cannot begin with any white space or they will be erroneously rendered as source blocks.

Missing images

If there are images missing, make sure that:

The syntax is correct. Make sure you set the square brackets at the end, even if you don’t want to use any attributes for the image.

image::path/file.jpg[]

The path and the file extension are correct. If you used the :imagesdir: attribute to set the image path, check if the path is correct.

Practice time

The code for this exercise is available on GitHub.

The corresponding file is named exercise-4-2.adoc

The following document doesn’t compile because there are some errors.

Enter metnanorma exercise-4-2.adoc to trigger the build process.
Have a look at the error messages.
Try to debug the document. If you get stuck, have a look at the hints.
Once you solved the errors, run the compilation command again to see if the document is build.

Hint Error 1

Lines 47 and 66: Both sections have the anchor [[prefatory-clause]] assigned. You can solve this error by renaming one of the anchors.

Hint Error 2

Line 76: The file that should be included cannot be found. Since the scope section already contains text, you can delete the reference.

Hint Error 3

Line 236: The image attribute contains a whitespace after image::, so the path is invalid. Delete the whitespace.

Let’s recap what we’ve covered in this lesson.

Start next lesson »