Better way to include content as-is with AsciiDoc include directive

2.6k views Asked by At

Context

I am making a script that dynamically inserts include directives in code blocks on an AsciiDoc file and then generates a PDF out of that. A generated AsciiDoc file could look like this:

= Title

[source,java]
---
include::foo.java[]
---

I want the user to be free to include whatever char-based file he or she wants, even other AsciiDoc files.

Problems

My goal is to show the contents as are of these included files. I run into problems when the included file:

  • is recognized as AsciiDoc beacuse of its extension, an thus any include directives it has are interpreted. I don't want nested includes, just to show the include directive in the code block. Example of undesired behaviour:

Unwanted nested includes

  • contains the code block delimiter ----, as seen on the image above when I end up with two code blocks instead of the intended single one. In this case, it does not matter if the file is recognized as an AsciiDoc file, the problem persists.

My workaround

My workaround

The script I am writing uses AsciidoctorJ and I am leveraging that I can control how the content of each file is included by using an include processor. Using the include processor I wrap each line of each file with the pass:[] macro. Additionally, I activate macro substitution on the desired code block. A demonstration of this idea is shown in the image above.

Is there a better way to show the exact contents of a file? This works, but it seems like a hack. I would much rather prefer not having to change the read lines as I am currently doing.


EDIT for futher information

I would like to:

  • not have to escape the block delimiter. I am not exclusively referring to ----, but whatever the delimiter happens to be. For example, the answer by cirrus still has the problem when a line of the included file has .....
  • not have to escape the include directives in files recognized as AsciiDoc.

In a general note, I don't want to escape (or modify in any way) any lines.

Problem I found with my workaround:

  • If the last char of a line is a backslash (\), it escapes the closing bracket of the pass:[] macro.
1

There are 1 answers

1
cirrus On

You can try using a literal block. Based on your above example:

a.adoc:

= Title

....
include::c.adoc[]
....

If you use include:: in c.adoc, asciidoctor will still try to find and include the file. As such you will need to replace include:: with \include::

c.adoc:

\include::foo.txt[]
----
----

Which should output the following pdf: pdfoutput