From 537cfcbf792e29adea5864416367c19e9060e79f Mon Sep 17 00:00:00 2001
From: Jermolene <jeremy@jermolene.com>
Date: Sat, 15 Oct 2016 18:06:17 +0100
Subject: [PATCH] Addendum to #2610
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Ensure we don’t try to read tiddlers from `.meta` files
* Improve docs
---
 boot/boot.js                                  |  8 ++--
 .../nodejs/tiddlywiki.files_Files.tid         | 45 ++++++++++++++++++-
 2 files changed, 48 insertions(+), 5 deletions(-)

diff --git a/boot/boot.js b/boot/boot.js
index 5ffbd2770..db49afb35 100644
--- a/boot/boot.js
+++ b/boot/boot.js
@@ -1592,10 +1592,12 @@ $tw.loadTiddlersFromSpecification = function(filepath) {
 			// Process directory specifier
 			var dirPath = path.resolve(filepath,dirSpec.path),
 				files = fs.readdirSync(dirPath),
-				fileRegExp = new RegExp(dirSpec.filesRegExp || "^.*$");
+				fileRegExp = new RegExp(dirSpec.filesRegExp || "^.*$"),
+				metaRegExp = /^.*\.meta$/;
 			for(var t=0; t<files.length; t++) {
-				if(files[t] !== "tiddlywiki.files" && fileRegExp.test(files[t])) {
-					processFile(dirPath + path.sep + files[t],dirSpec.isTiddlerFile,dirSpec.fields);
+				var filename = files[t];
+				if(filename !== "tiddlywiki.files" && !metaRegExp.test(filename) && fileRegExp.test(filename)) {
+					processFile(dirPath + path.sep + filename,dirSpec.isTiddlerFile,dirSpec.fields);
 				}
 			}
 		}
diff --git a/editions/tw5.com/tiddlers/nodejs/tiddlywiki.files_Files.tid b/editions/tw5.com/tiddlers/nodejs/tiddlywiki.files_Files.tid
index b466dd0d7..3df16e7c6 100644
--- a/editions/tw5.com/tiddlers/nodejs/tiddlywiki.files_Files.tid
+++ b/editions/tw5.com/tiddlers/nodejs/tiddlywiki.files_Files.tid
@@ -1,5 +1,5 @@
 created: 20161015114118243
-modified: 20161015151555834
+modified: 20161015170604353
 tags: TiddlyWikiFolders
 title: tiddlywiki.files Files
 type: text/vnd.tiddlywiki
@@ -47,6 +47,47 @@ Directory specifications in the `directories` array may take the following forms
 * a ''string'' literal, specifying the absolute or relative path to the directory containing the tiddler files (relative paths are interpreted relative to the path of the `tiddlywiki.files` file). The directory is recursively searched for tiddler files
 * <<.from-version "5.1.14">> an ''object'' with the following properties:
 ** ''path'' - (required) the absolute or relative path to the directory containing the tiddler files (relative paths are interpreted relative to the path of the `tiddlywiki.files` file). Note that the directory is not recursively searched; sub-directories are ignored
-** ''filesRegExp'' - (optional) a [[regular expression]] that matches the filenames of the files that should be processed within the directory
+** ''filesRegExp'' - (optional) a [[regular expression|https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Regular_Expressions]] that matches the filenames of the files that should be processed within the directory
 ** ''isTiddlerFile'' - (required) if `true`, the file will be treated as a [[tiddler file|TiddlerFiles]] and deserialised to extract the tiddlers. Otherwise, the raw content of the file is assigned to the `text` field without any parsing
 ** ''fields'' - (required) an object containing values that override or customise the fields provided in the tiddler file (see above)
+
+Fields can be overridden for particular files by creating a file with the same name plus the suffix `.meta` -- see TiddlerFiles.
+
+! Examples
+
+These example `tiddlywiki.files` must be placed in their own sub-directory of the [[wiki folder|TiddlyWikiFolders]].
+
+There are also several examples of `tiddlywiki.files` files in the main [[TiddlyWiki 5 GitHub repository|https://github.com/Jermolene/TiddlyWiki5]]. 
+
+!! Importing a folder of PDFs
+
+This example retrieves all the files with the extension `.pdf` from a folder specified by a relative path. Each tiddler is given the following fields:
+
+* ''title'' - set to the filename of the PDF file
+* ''created'' - set to the creation date/time of the PDF file
+* ''modified'' - set to the modification date/time of the PDF file
+* ''type'' - set to `application/pdf`
+* ''tags'' - set to `$:/tags/AttachedFile`
+* ''_canonical_uri'' - set to the string "pdfs/" concatenated with the filename
+
+```
+{
+    "directories": [
+        {
+            "path": "../../../input/pdfs",
+            "filesRegExp": "^.*\\.pdf$",
+            "isTiddlerFile": false,
+            "fields": {
+                "title": {"source": "filename"},
+                "created": {"source": "created"},
+                "modified": {"source": "modified"},
+                "type": "application/pdf",
+                "tags": ["$:/tags/AttachedFile"],
+                "_canonical_uri": {"source": "filename", "prefix": "pdfs/"}
+            }
+        }
+    ]
+}
+```
+
+The approach of re-using the filename of the PDF as the 
\ No newline at end of file