From dc2f808962cac80fa555819368f37b747deb1b4c Mon Sep 17 00:00:00 2001 From: Ewan Edwards Date: Wed, 13 Dec 2023 11:43:58 -0800 Subject: [PATCH 1/2] Add a Known Issues section to the README. The section includes a bullet describing the problem where line comments in a table causes "not found" errors for images in that table. --- README.adoc | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README.adoc b/README.adoc index d70fe3c..97e1731 100644 --- a/README.adoc +++ b/README.adoc @@ -536,6 +536,29 @@ Uses the same path resolution rules as the output dir in the Antora playbook. |Boolean |=== +== Known Issues + +- **Using line comments in tables** ++ +When you use a line-based comment in a table, Assembler loses track of images in that table. ++ +For example, when you include this comment in a table cell: ++ +[,adoc] +---- +// A comment +---- ++ +All images in the table produce "not found" errors when Assembler generates the all-in-one AsciiDoc file. ++ +The workaround is to use a comment block: ++ +[,adoc] +---- +[comment] +A comment +---- + == Copyright and License Copyright (C) 2022-present by OpenDevise Inc. and the individual contributors of this project. -- GitLab From 220b35e8c5acab5af68285b40d696329a8081993 Mon Sep 17 00:00:00 2001 From: Ewan Edwards Date: Fri, 22 Dec 2023 20:40:10 -0800 Subject: [PATCH 2/2] Apply feedback and improve formatting. --- README.adoc | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/README.adoc b/README.adoc index 97e1731..b381afe 100644 --- a/README.adoc +++ b/README.adoc @@ -538,27 +538,31 @@ Uses the same path resolution rules as the output dir in the Antora playbook. == Known Issues -- **Using line comments in tables** -+ -When you use a line-based comment in a table, Assembler loses track of images in that table. -+ -For example, when you include this comment in a table cell: -+ +=== Using line comments in tables + +When you use a line-based comment in a table, Asciidoctor can no longer accurately track the location of lines, so Assembler's line-based processing loses track of block images in that table. + +For example, when you include this comment in an AsciiDoc table cell: + [,adoc] ---- // A comment ---- -+ -All images in the table produce "not found" errors when Assembler generates the all-in-one AsciiDoc file. -+ -The workaround is to use a comment block: -+ + +All block images in the table produce "not found" errors when Assembler generates the all-in-one AsciiDoc file. + +The workaround is to use a comment paragraph: + [,adoc] ---- [comment] A comment ---- +This works because, during parsing, it is discovered as a paragraph. +Comment lines are removed immediately, but comment paragraphs are removed later. +This means the paragraph still "exists" when Asciidoctor processes the remainder of the AsciiDoc table, so block images can still be located. + == Copyright and License Copyright (C) 2022-present by OpenDevise Inc. and the individual contributors of this project. -- GitLab