File 4014-Write-documentation.patch of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 4014-Write-documentation.patch of Package erlang

From a01d64ecd95916c8a6f652cf5a7c642f6ddd6c20 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 29 Jun 2023 19:29:48 +0200
Subject: [PATCH 4/8] Write documentation

---
 system/doc/reference_manual/data_types.xml | 148 ++++++++++++++++++++-
 1 file changed, 145 insertions(+), 3 deletions(-)

diff --git a/system/doc/reference_manual/data_types.xml b/system/doc/reference_manual/data_types.xml
index 6cbf864a79..67adc6f7d1 100644
--- a/system/doc/reference_manual/data_types.xml
+++ b/system/doc/reference_manual/data_types.xml
@@ -370,6 +370,133 @@ a
 is equivalent to
 <pre>
 "string42"</pre>
+ 
+ Strings can also be written as triple-quoted strings,
+ which can be indented over multiple lines to follow
+ the indentation of the surrounding code.
+ They are also verbatim, that is; they don't allow
+ escape sequences, and thereby don't need double quote characters
+ to be escaped.
+ 
+ <change>
+ 
+ Triple-quoted strings were added in Erlang/OTP 27.
+ Before that 3 consecutive double quote characters
+ had a different meaning.
+ There were absolutely no good reason to write
+ such a character sequence before triple-quoted strings existed,
+ but there are some gotcha:s; see the
+ <seeguide marker="#triple-quoted-strings-warning">
+ Warning
+ </seeguide>
+ at the end of this description of
+ triple-quoted strings.
+ 
+ </change>
+ 
+ Example, with verbatim double quote characters:
+ 
+ <pre>
+"""
+ Line "1"
+ Line "2"
+ """</pre>
+ 
+ That is equivalent to the normal single quoted string
+ (which also allows newlines):
+ 
+ <pre>
+"Line \"1\"
+Line \"2\""</pre>
+ 
+ The opening and the closing line has got the delimiters;
+ the <c>"""</c> characters. The lines between them
+ are the content lines. The newline on the opening line
+ is not regarded as string content, nor is the newline
+ on the last content line.
+ 
+ 
+ The indentation is defined by the white space character
+ sequence preceding the delimiter on the closing line.
+ That character sequence is stripped from all content lines.
+ There can only be white space before the delimiter
+ on the closing line, or else it is regarded as a content line.
+ 
+ 
+ The opening line is not allowed to have any characters
+ other than white space after the delimiter,
+ and all content lines must start with the defined
+ indentation character sequence,
+ otherwise the string has a syntax error.
+ 
+ 
+ Here is a larger example:
+ 
+ <pre>
+X = """
+ First line starting with two spaces
+ Not escaped: "\t \r \xFF" and """
+ 
+ """</pre>
+ 
+ That corresponds to the normal string:
+ 
+ <pre>
+X = " First line starting with two spaces
+Not escaped: \"\\t \\r \\xFF\" and \"\"\"
+"</pre>
+ 
+ It is possible to write consecutive double quote characters
+ on the beginning of a content line by using more
+ double quote characters as delimiters.
+ This is a string that contains exactly 4 double quote characters,
+ using a delimiter with 5 double quote characters:
+ 
+ <pre>
+"""""
+""""
+"""""</pre>
+ 
+ These strings are all the empty string:
+ 
+ <pre>""</pre>
+ <pre>
+"""
+"""</pre>
+ <pre>
+"""
+ 
+ """</pre>
+
+ <marker id="triple-quoted-strings-warning"/>
+ <warning>
+ 
+ Before Erlang/OTP 27, when triple-quoted strings were added,
+ the character sequence <c>"""</c> was interpreted as <c>"" "</c>
+ which means concatenate the empty string to the string that follows.
+ All sequences of an odd number of double quote characters had
+ this meaning.
+ 
+ 
+ Any even number of double quote characters was interpreted as
+ a sequence of empty strings, that were concatenated
+ (to the empty string).
+ 
+ 
+ There was no reason to write such character sequences.
+ But should that have happended; the meaning probably changed
+ with the introduction of triple-quoted strings.
+ 
+ 
+ The compiler preprocessor was patched in Erlang/OTP 26.1
+ to warn about 3 or more sequential double quote characters.
+ If the compiler should emit such a warning, please change
+ all such double quote character sequences to have a whitespace
+ after every second character, making the code more readable,
+ and mean the same thing in all releases.
+ 
+ </warning>
+
 </section>
 
 <section>
@@ -414,8 +541,8 @@ true</pre>
 
 <section>
 <title>Escape Sequences</title>
- Within strings and quoted atoms, the following escape sequences
- are recognized:
+ Within strings (<c>"</c>-delimited) and quoted atoms,
+ the following escape sequences are recognized:
 <table>
 <row>
 <cell align="left" valign="middle">Sequence</cell>
@@ -520,11 +647,26 @@ true</pre>
 <tcaption>Recognized Escape Sequences</tcaption>
 </table>
 
-
 <change>As of Erlang/OTP 26, the value of <c>$\^?</c> has been
 changed to be 127 (Delete), instead of 31. Previous releases
 would allow any character following <c>$\^</c>; as of Erlang/OTP
 26, only the documented characters are allowed.</change>
+
+ 
+ Within triple-quoted strings, escape sequences are not recognized.
+ The only text that cannot be written in a triple-quoted string
+ is three consecutive double quote characters at the beginning
+ of a line (preceded only by whitespace). This limitation can
+ be worked around by using more double quote characters
+ for the string delimiters than in the string.
+ Any number three or above is allowed.
+ 
+
+ <change>
+ 
+ Triple quoted strings were introduced in Erlang/OTP 27.
+ 
+ </change>
 </section>
 
 <section>
-- 
2.35.3

Places

File 4014-Write-documentation.patch of Package erlang

Places