Why is a duplicate include file an error?

[mbakeranalecta]

Currently and included file is checked against a list of included files and an error is raised it a duplicate include is found.

I suspect this was installed to detect and prevent circular includes, were a file includes itself or a file that includes itself. This is an important check, but there could be legitimate reasons to include the same file twice.

Is there sufficient reason to try an make this check more sophisticated so that it allows simple duplicate includes but prevents circular ones?

[tigregalis]

A legitimate reason could be, for example, documenting the language itself. With asciidoctor I might use

```asciidoc
include::example.adoc[]
```

include::example.adoc[]

Here, I have included the source of another asciidoc file first, and then I have included it as-is to show what it looks like when rendered (but crucially, it was only written once).

It would be more appropriate to generate a tree of includes, and at each include, check along the current path from root-to-branch.

Given the following documents:

• "root"
• "example"
• "example2"
• "example3"

And the following includes, in this order:

• "root":
  • include "example"
  • include "example2"
  • include "example"
  • include "root"
• "example":
  • include "example2"
  • include "example3"
• "example2":
  • include "example"

The tree generated would be:

• "root" ["root"]
  • "example" ["root", "example"]
  • "example2" ["root", "example", "example2"]
    • "example" ["root", "example", "example2", "example"] ("example" has already appeared along the path to this branch, so don't include, and warn)
  • "example3" ["root", "example", "example3"]
  • "example2" ["root", "example2"]
  • "example" ["root", "example2", "example"]
    • "example2" ["root", "example2", "example", "example2"] ("example2" has already appeared along the path to this branch, so don't include, and warn)
  • "example" ["root", "example"]
  • "example2" ["root", "example", "example2"]
    • "example" ["root", "example", "example2", "example"] ("example" has already appeared along the path to this branch, so don't include, and warn)
  • "example3" ["root", "example", "example3"]
  • "root" ["root", "root"] ("root" has already appeared along the path to this branch, so don't include, and warn)

[mbakeranalecta]

Interesting case, for sure.

SAM would not actually allow this at the syntax level, however. The content of a code block is code, pure and simple, so

            <<<(example.sam) 

Would just render 

     <<<(example.sam)

This case would have to be handled using an insert instead

    code-sample:
        >>>(literal example.sam)

The language designer would have to define a `code-sample` block because the literal codeblock would not execute the insert either. The `literal` include type is not currently on the reserved list for insert types, but maybe it should be. Or maybe there should actually be a `codeblock` insert type. 

But in this case, double include would not apply since there is only one include and one insert. 

Still, an interesting case to think about.

Thanks