Add prefixes to identifiers with `--file-scope`.multifile

This change only affects the case where `--file-scope` is used
and more than one file is specified on the command line.

In this case, identifiers will be prefixed with a string
derived from the file path, to disambiguate them. For example,
an identifier `foo` in `contents/file1.txt` will become
`contents__file1.txt__foo`.  Links will be adjusted accordingly:
if `file2.txt` links to `file1.txt#foo`, then the link will
be changed to point to `#file1.txt__foo`.  Similarly, a link
to `file1.txt` will point to `#file1.txt`.  A Div with an
identifier derived from the file path will be added around
each file's content, so that links to files will still work.

Closes #6384.

[API change]: Text.Pandoc.Shared exports `textToIdentifier`.

1 files changed, 11 insertions, 0 deletions

diff --git a/MANUAL.txt b/MANUAL.txt
index 4ba409c76..e80c920f2 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -564,6 +564,17 @@ header when requesting a document from a URL:
     footnotes and links will not work across files. Reading binary
     files (docx, odt, epub) implies `--file-scope`.
 
+    If two or more files are processed using `--file-scope`,
+    prefixes based on the filenames will be added to identifiers
+    in order to disambiguate them, and internal links will
+    be adjusted accordingly.  For example, a header with
+    identifier `foo` in `subdir/file1.txt` will have its
+    identifier changed to `subdir__file1.txt__foo`.
+
+    In addition, a Div with an identifier based on the filename
+    will be added around the file's content, so that internal
+    links to the filename will point to this Div's identifier.
+
 `-F` *PROGRAM*, `--filter=`*PROGRAM*
 
 :   Specify an executable to be used as a filter transforming the