diff --git a/ocrd_models/README.md b/ocrd_models/README.md
index 36ebf381d..bdd687d05 100644
--- a/ocrd_models/README.md
+++ b/ocrd_models/README.md
@@ -15,10 +15,6 @@ def get_FirstTextRegion(self):
   return self.get_TextRegion[0]
 ```
 
- **NOTE** The method name and file name must be identical.
-
- **NOTE** Do not use Python's `%` string interpolation operator, it will break generateDS. Use `"".format(...)` instead.
-
 2. Edit `ocrd_models/ocrd_page_user_methods.py` and append to the `METHOD_SPECS` list:
 
 ```python
@@ -29,6 +25,23 @@ METHOD_SPECS = (
 )
 ```
 
+If the filename (sans the `.py` extension) does not match the method_name, you
+can provide an additional `file_name` attribute to `_add_method`:
+
+```python
+METHOD_SPECS = (
+  # ...
+  _add_method(r'^PageType$', 'exportChildren', 'exportChildren_PageType')
+  # ...
+)
+```
+
+Would add the method `exportChildren` from a file `exportChildren_PageType.py`.
+
+**NOTE** The method name in the file must match the method name passed to
+`_add_method`. This is *not* checked automatically, so double-check manually!
+
+
 3. Regenerate the PAGE API:
 
 ```sh
diff --git a/ocrd_models/ocrd_page_user_methods.py b/ocrd_models/ocrd_page_user_methods.py
index ff39000eb..ac7fc071f 100644
--- a/ocrd_models/ocrd_page_user_methods.py
+++ b/ocrd_models/ocrd_page_user_methods.py
@@ -91,7 +91,7 @@ def _add_method(class_re, method_name, file_name=None):
         file_name = method_name
     with codecs.open(join(dirname(__file__), 'ocrd_page_user_methods', '%s.py' % file_name)) as f:
         for line in f.readlines():
-            source.append('    %s' % line if line else line)
+            source.append('    %s' % line.replace('%', '%%') if line else line)
     return MethodSpec(name=method_name, class_names=class_re, source=''.join(source))
 
 #