Update README

Author: CFiggers

README.md

@@ -47,7 +47,33 @@ directory, with the `.janet` suffix. If the binding includes the `/` character,
 an underscore - this works because no bindings in the core use an underscore. For example, the
 binding `array/new` has examples in the `examples/array_new.janet` file.
 
-If such a file already exists, you can simply append your example code the existing file.
+To cope with some of Janet's symbols having names with characters that
+are not-so-friendly to certain filesystem and/or operating system
+combinations, an escaping scheme is used.
+
+For a given symbol, use the `content/examples.janet` script to
+generate an appropriate filename.  For example, for `array/new`,
+invoking:
+
+```
+$ janet content/examples.janet array/new
+```
+
+should give the output:
+
+```
+array_47new.janet
+```
+
+If such a file already exists, you can simply append your example code
+to the existing file.
+
+When building the site, the new examples will be included in the
+generated documentation. Make sure that your example has correct janet
+syntax, as syntax errors will cause the entire site to not build. If
+the example has valid syntax (has a 0 exit code when loaded with
+`janet -k example/my-fn.janet`), there may be a bug in the mendoza
+janet syntax highlighter in which case please open a bug in mendoza.
 
 When building the site, the new examples will be included in the generated documentation. Make
 sure that your example has correct janet syntax, as syntax errors will cause the entire site