doc: make it more clear that 'utf-8' encoding is expected.

examples/json-to-nestedtext

@@ -19,6 +19,8 @@ from pathlib import Path
 import json
 import nestedtext
 import sys
+sys.stdin.reconfigure(encoding='utf-8')
+sys.stdout.reconfigure(encoding='utf-8')
 
 cmdline = docopt(__doc__)
 input_filename = cmdline['<filename>']
@@ -32,7 +34,7 @@ try:
     # read JSON content; from file or from stdin
     if input_filename:
         input_path = Path(input_filename)
-        json_content = input_path.read_text()
+        json_content = input_path.read_text(encoding='utf-8')
     else:
         json_content = sys.stdin.read()
     data = json.loads(json_content)
@@ -46,7 +48,7 @@ try:
         if output_path.exists():
             if not cmdline['--force']:
                 fatal('file exists, use -f to force over-write.', culprit=output_path)
-        output_path.write_text(nestedtext_content)
+        output_path.write_text(nestedtext_content, encoding='utf-8')
     else:
         sys.stdout.write(nestedtext_content)
 except OSError as e:

examples/nestedtext-to-json

@@ -19,6 +19,8 @@ from pathlib import Path
 import json
 import nestedtext
 import sys
+sys.stdin.reconfigure(encoding='utf-8')
+sys.stdout.reconfigure(encoding='utf-8')
 
 
 def de_dup(key, value, data, state):
@@ -35,7 +37,7 @@ on_dup = de_dup if cmdline['--dedup'] else None
 try:
     if input_filename:
         input_path = Path(input_filename)
-        nestedtext_content = input_path.read_text()
+        nestedtext_content = input_path.read_text(encoding='utf-8')
     else:
         nestedtext_content = sys.stdin.read()
     data = nestedtext.loads(nestedtext_content, input_filename, on_dup=de_dup)
@@ -45,7 +47,7 @@ try:
         if output_path.exists():
             if not cmdline['--force']:
                 fatal('file exists, use -f to force over-write.', culprit=output_path)
-        output_path.write_text(json_content)
+        output_path.write_text(json_content, encoding='utf-8')
     else:
         sys.stdout.write(json_content)
 except OSError as e:

nestedtext.py

@@ -524,7 +524,7 @@ def loads(content, source=None, on_dup=None):
 
             >>> filename = 'examples/duplicate-keys.nt'
             >>> try:
-            ...     with open(filename) as f:
+            ...     with open(filename, encoding='utf-8') as f:
             ...         addresses = nestedtext.loads(f.read(), filename)
             ... except nestedtext.NestedTextError as e:
             ...     print(str(e))
@@ -535,6 +535,10 @@ def loads(content, source=None, on_dup=None):
                   ↑
                6 «»
 
+        Notice in the above example the encoding is explicitly specified as
+        'utf-8'.  *NestedText* files should always be read and written using
+        *utf-8* encoding.
+
         The following examples demonstrate the various ways of handling
         duplicate keys: