resolve some nit regarding line terminators

Ken Kundert · Ken Kundert · commit 9c386e71791a · 2024-08-10T12:41:20.000-07:00
diff --git a/doc/file_format.rst b/doc/file_format.rst
@@ -73,8 +73,10 @@ The *NestedText* format follows a small number of simple rules. Here they are.
     item*.  After comments and blank lines have been removed, adjacent string 
     items with the same indentation level are combined in order into 
     a multiline string.  The string value is the multiline string with the 
-    tags removed. Any leading white space that follows the tag is retained, as 
-    is any trailing white space and all newlines except the last.
+    tags removed.  Any leading white space that follows the tag is retained, as 
+    is any trailing white space. The last newline is removed and all other 
+    newlines are converted to the default line terminator for the current 
+    operating system.
 
     String values may contain any printing UTF-8 character.
 
@@ -105,9 +107,10 @@ The *NestedText* format follows a small number of simple rules. Here they are.
     immediately by an ASCII space (``:&#9251;``) or a line break, the line is a *key 
     item*.  After comments and blank lines have been removed, adjacent key items 
     with the same indentation level are combined in order into a multiline key.  
-    The key itself is the multiline string with the tags removed. Any leading 
-    white space that follows the tag is retained, as is any trailing white space 
-    and all newlines except the last.
+    The key itself is the multiline string with the tags removed.  Any leading 
+    white space that follows the tag is retained, as is any trailing white 
+    space. The last newline is removed and all other newlines are converted to 
+    the default line terminator for the current operating system.
 
     Key values may contain any printing UTF-8 character.
 
diff --git a/doc/techniques.rst b/doc/techniques.rst
@@ -547,6 +547,9 @@ This example uses the pretty-print function from the previous example.
         Lorem ipsum dolor sit amet, consectetur adipiscing elit.
         Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
+An alternative to using a backslash to escape the newline is to simply join 
+lines that end with a space.  This might be more natural for non-programmers and 
+can work well for prose.
 
 .. _voluptuous: https://github.com/alecthomas/voluptuous
 .. _pydantic: https://pydantic-docs.helpmanual.io
diff --git a/nestedtext/nestedtext.py b/nestedtext/nestedtext.py
@@ -52,8 +52,8 @@
 
 
 # Utility functions {{{1
-# convert_returns {{{2
-def convert_returns(text):
+# convert_line_terminators {{{2
+def convert_line_terminators(text):
     return text.replace("\r\n", "\n").replace("\r", "\n")
 
 
@@ -1320,7 +1320,7 @@ def loads(
     '''
 
     # code {{{3
-    lines = convert_returns(content).split("\n")
+    lines = convert_line_terminators(content).split("\n")
     loader = NestedTextLoader(
         lines, top, source, on_dup, keymap, normalize_key, dialect
     )
@@ -1407,7 +1407,7 @@ def load(
     # code {{{3
     # Do not invoke the read method as that would read in the entire contents of
     # the file, possibly consuming a lot of memory. Instead pass the file
-    # pointer into _read_all(), it will iterate through the lines, discarding
+    # pointer into loader, it will iterate through the lines, discarding
     # them once they are no longer needed, which reduces the memory usage.
 
     if isinstance(f, collections.abc.Iterator):
@@ -1527,7 +1527,7 @@ def render_key(self, key, keys):
             raise NestedTextError(
                 key, template="keys must be strings.", culprit=keys
             ) from None
-        return convert_returns(key)
+        return convert_line_terminators(key)
 
     # render_dict_item {{{3
     def render_dict_item(self, key, value, keys, values):
@@ -1546,7 +1546,7 @@ def render_dict_item(self, key, value, keys, values):
                 return key + self.render_value(value, keys, values)
             if is_str(value):
                 # force use of multiline value with multiline keys
-                value = convert_returns(value)
+                value = convert_line_terminators(value)
             else:
                 value = self.render_value(value, keys, values)
             return key + "\n" + add_leader(value, self.indent*" " + "> ")
@@ -1674,7 +1674,7 @@ def render_value(self, obj, keys, values):
                 content = "\n".join(content)
 
         elif self.is_a_str(obj):
-            text = convert_returns(obj)
+            text = convert_line_terminators(obj)
             if "\n" in text or level == 0:
                 content = add_leader(text, "> ")
                 need_indented_block = True
