Clarify the read_env documentation for pandoc.read

[CodeSandwich]

Explain the problem.

The documentation for read_env parameter of pandoc.read says:

If the value is not given or nil, then the global environment is used. Passing a list of filenames causes the reader to be run in a sandbox. The given files are read from the file system and provided to the sandbox via an ersatz file system. The table can also contain mappings from filenames to contents, which will be used to populate the ersatz file system.

I can't fully understand this piece, IMO it's missing some details:

1. What's the "ersatz file system"? I haven't found any usage of this term on the English part of the internet. I looked it up and "ersatz" means "substitute" in German, which makes a lot of sense. The documentation is in English, so maybe it makes sense to translate this term to English to avoid confusion? It probably also touches other comments across the codebase, which probably would benefit from this translation.
2. It could include an example of mixing table entries (filenames to read from the system) and mapping entries (filenames to make up from the content). It's not obvious how to do that properly because IMO it's not very common to use a table-mapping hybrid as an argument in Lua.
3. The "global environment is used" means "the whole file system of the computer is directly accessible", right? It has nothing to do with environment variables or Pandoc configuration? It would be great to clarify.
4. If I pass a list of filenames, how will they be accessible in the rader? Will they be under the same paths as in the real file system? What file access permissions will be granted? Can files be mapped to different paths? Will the working directory be altered?
5. If I create a virtual file from its content, what permissions will be granted to it?
6. Can I use the real file system, but add on top of it some virtual files?

Pandoc version?
3.7.0.1

[jgm]

re 1: "erzatz" is a perfectly good English word (borrowed from German):
https://www.merriam-webster.com/dictionary/ersatz

re 2: good idea

re 3: this could be clarified

re 4: yes, same paths, unless you explicitly specify a path/content pair

re 5: the only thing you can do is read the files

re 6: no, because sandboxing means that no I/O can be performed by the reader.

[CodeSandwich]

re 1: "erzatz" is a perfectly good English word (borrowed from German):

You're right, it's a correct English word. Nevertheless it's quite confusing, it's an exotic word that doesn't seem commonly used in this context. WDYT about "virtual filesystem" or "sandbox filesystem"? IMO common terms like these would make this feature easier to discover and understand. It took me a good while to crack what "ersatz filesystem" means, I was expecting a 3rd party tool or a new technique I've never seen before.

[jgm]

"virtual file system" would be okay with me.

[tarleb]

FWIW, I really like the term "ersatz file system". I think its very precise and fitting. But I'm German, so maybe that doesn't count.

[jgm]

"virtual" is Latin, "ersatz" is German. Which one seems more obscure will depend on your point of reference, I guess!

[CodeSandwich]

"Virtual file system" is a great term, it's widely used in the English-speaking software developer community. Just search for this term in Google, you'll get thousands of results about technologies similar to what read_env does, including Wikipedia. Searching for "ersatz file system" yields absolutely no relevant results, only the "file system" part is picked up. "Ersatz file system" is objectively obscure in this use case regardless of the point of reference.

[jgm]

Followed the wikipedia link: unfortunately, the definition given there of virtual file system doesn't correspond to what we have here. This isn't an abstract layer for accessing a file system; it's a "fake file system" that doesn't involve accessing the real file system at all.