Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

tip that table footnotes do not cross-reference: https://github.com/m… #801

Merged
merged 2 commits into from
Aug 23, 2024
Merged

tip that table footnotes do not cross-reference: https://github.com/m… #801

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
20dc70c
tip that table footnotes do not cross-reference: https://github.com/m…
opoudjis Jul 30, 2024
8400dcf
feat: update troubleshooting page
ronaldtse Aug 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
229 changes: 171 additions & 58 deletions author/topics/troubleshooting.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,47 +27,64 @@ want to exclude it from being rendered, you can easily comment out the section.
.Example for a modular document setup
[source,adoc]
----
Header with metadata...
Header with metadata...

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

\include::sections/01-introduction.adoc[]
\include::sections/02-scope.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 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.
* *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.

// end::tutorial[]
The following sections discuss common errors and how to fix them.

== The document won't build - Compilation errors

Compilation failures can happen due to installation or markup errors.
Hopefully, the compilation message will provide us with a clear insight of the cause of the failure. The first error line usually tells us the cause of the failure.

Before looking at installation or markup errors, make sure you are running the build command in the place where your document is placed.
Hopefully, the compilation message will provide us with a clear insight of the
cause of the failure. The first error line usually tells us the cause of the
failure.

Before looking at installation or markup errors, make sure you are running the
build command in the place where your document is placed.

.Example for a failed build because of the wrong location
[source,shell]
----
user@machine my-standard % metanorma document.adoc <1>
my-standard $ metanorma document.adoc <1>
Error: Specified input file 'document.adoc' does not exist.

user@machine sources % metanorma document.adoc <2>
sources $ metanorma document.adoc <2>
----
<1> When we try to run Metanorma in the place that doesn't contain the actual document, it says that the document doesn't exist.
<2> Go to the folder that contains the document and run the build command again.

=== Installation errors
Metanorma uses Ruby gems - small software packets that contain a certain function - to build Metanorma documents. For example, the `metanorma-iso` gem processes ISO standards.

Metanorma uses Ruby gems to manage the stack of Metanorma software. For example,
the `metanorma-iso` gem processes ISO standards.

To manage dependencies, Metanorma uses the tool https://bundler.io/v1.12/[Bundler].

To successfully compile a document, you need to install all gems Metanorma uses
Expand All @@ -76,51 +93,77 @@ you followed the link:/install/[Installation guide].

To *install* all relevant gems:

. Go to root folder of the directory in which your Metanorma project sits. +
. Go to root folder of the directory in which your Metanorma project sits.
+
TIP: You can move into another directory using the "change directory" command (`cd`).

. Run `bundle install` +
Bundler fetches and installs the missing gems.
. Run `bundle install`. Bundler fetches and installs the missing gems.

To *update* outdated gems run `bundle-update` in your project directory.

// tag::no-compile-markup[]

=== Markup errors
Metanorma can't compile a document, when required information is missing or there are 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.
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:

* 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.
* 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.

* Metadata specific to your organization. Check the link:/flavors/[flavor documentation] to make sure you've entered the metadata correctly.
* 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 link:/flavors/[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:
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.


.Example of a compilation error due to a single double quotation mark inside of a stem block
[example]
====
`\stem:["normal text""]` leads to the following compilation error:

[source]
----
...
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>'
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.

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 problem 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.

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
[source,asciidoc]
Expand All @@ -134,30 +177,42 @@ If two or more cross-references have the same anchor, the document won't build a
...
----

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

// end::no-compile-markup[]

== The document builds, but looks odd

// tag::rendering-errors[]

=== Rendering errors
The main cause for rendering errors are markup errors which can lead to unexpected rendering results.

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.

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.
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]
[source,asciidoc]
----

[source,Asciidoc]
[source,asciidoc]
=== <1>
image::../assets/image.png[]
===
Expand All @@ -172,44 +227,60 @@ image::../assets/image.png[]
|Cell in column 1, row 2
|Cell in column 2, row 2
|--- <3>

----
<1> 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 `=`.
<2> The block delimiter is only three characters long, so the compiler will not render the table.
<3> `|---` 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.

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. +
* 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.
+
[source,adoc]
----
image::path/file.jpg[]
----
* The path and the file extension are correct. If you used the https://docs.asciidoctor.org/asciidoc/latest/macros/images-directory/[`:imagesdir:` attribute] to set the image path, check if the path is correct.

* The path and the file extension are correct. If you used the
https://docs.asciidoctor.org/asciidoc/latest/macros/images-directory/[`:imagesdir:` attribute]
to set the image path, check if the path is correct.

// end::rendering-errors[]

==== Index term is showing up multiple times

If an index term that only should appear once, appears several times, check the parentheses used in the index entries for this term.
If an index term that only should appear once, appears several times, check the
parentheses used in the index entries for this term.

The syntax for index entries looks like this:

[source,adoc]
----
Visible index terms: `\((Level 1 index term))`
Visible index terms: `((Level 1 index term))`

Hidden index terms: `(\((Level 1 index term, Level 2 index term, Level 3 index term)))`
Hidden index terms: `(((Level 1 index term, Level 2 index term, Level 3 index term)))`
----


=== Cross-reference errors

==== Incorrect format of reference anchor
Cross-reference anchors cannot begin with numbers, underscores, hyphens or any other special characters. If they do, they will not be processed in compilation and will certaintly lead to rendering errors in the section titles. Anchors must begin with a letter or an underscore and can not contain any special character other than hyphens and underscores.

Cross-reference anchors cannot begin with numbers, underscores, hyphens or any
other special characters. If they do, they will not be processed in compilation
and will certainly lead to rendering errors in the section titles. Anchors must
begin with a letter or an underscore and can not contain any special character
other than hyphens and underscores.

.Example for incorrect anchor names
[source,asciidoc]
Expand All @@ -223,9 +294,10 @@ Cross-reference anchors cannot begin with numbers, underscores, hyphens or any o
* [[[#anchor3,identifier 3]]], ... // Anchors cannot begin with any special character. Just letters.
----

Also make sure to use the same keyword for references. If the compiler finds a reference without a matching anchor, it will not process the reference.
Also make sure to use the same keyword for references. If the compiler finds a
reference without a matching anchor, it will not process the reference.

[source, Asciidoc]
[source,asciidoc]
----
[[anchor1234]]
<<anchor1432>>
Expand All @@ -234,12 +306,20 @@ Error message: No label has been processed for ID anchor1432
----

==== A reference auto-fetch failure
When a reference link:/author/topics/sections/bibliography/#autofetch[auto-fetching] process fails, compilation failure may happen.

The Metanorma team is constantly searching and solving issues related with the automatic importation of bibliographic entries.
Instead of waiting for a bugfix, you can apply a quick workaround. You can disable the automatic look-up of the individual reference by enclosing its identifier with `nofetch()`.
When a reference
link:/author/topics/sections/bibliography/#autofetch[auto-fetching] process
fails, compilation failure may happen.

The Metanorma team is constantly searching and solving issues related with the
automatic importation of bibliographic entries.

For example, let's supose we have an issue with the reference `ITU-R BT.2267-10`.
Instead of waiting for a bugfix, you can apply a quick workaround. You can
disable the automatic look-up of the individual reference by enclosing its
identifier with `nofetch()`.


For example, let's suppose we have an issue with the reference `ITU-R BT.2267-10`.
Its AsciiDoc markup would correspond to:

[source,asciidoc]
Expand All @@ -258,8 +338,8 @@ and gives us a compilation failure message of:
[relaton-itu] ("ITU-R BT.2267-10") fetching...
C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:440:in `block in symbolize': undefined method `to_sym' for 404:Integer (NoMethodError)
Did you mean? to_s
from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `each'
from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `reduce'
from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `each'
from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `reduce'
...
----

Expand All @@ -274,8 +354,41 @@ To solve issues with automatic lookup, we can set the `nofetch()` attribute:
* [[[bt2267-10,nofetch(ITU-R BT.2267-10)]]], Report ITU-R BT.2267-10 (2019), _Integrated broadcast-broadband systems._
----

==== Footnotes are repeated in tables

In AsciiDoc, tables cells are processed as completely separate documents. That
means that table cells are not aware of one another's contents. As a result, if
a footnote is repeated among different cells through named footnotes, the
AsciiDoc parser will not recognise them.

.Example of repeated footnotes in tables
[example]
====
[source]
----
|===
|A footnote:a[ABC] | B footnote:a[]
|===
----

Renders as:

____
[cols="1,1"]
|===
| A^1^ | B^2^
2+a| ^1^ ABC +
^2^
|===
____
====


=== Errors that are bugs

Metanorma is under continuous development, so it is possible to face an error that you can not fix because it is a bug. If you need help with a persisting error or if you found a bug, please create a new issue on Github in your organization's repository (`metanorma-ORGNAME`), for example `metanorma-iso`.
Metanorma is under continuous development, so it is possible to face an error
that you can not fix because it is a bug. If you need help with a persisting
error or if you found a bug, please create a new issue on Github in your
organization's repository (`metanorma-ORGNAME`), for example `metanorma-iso`.

* https://github.com/metanorma[Metanorma Github]
Loading