new repository

1 files changed, 75 insertions, 0 deletions

diff --git a/devdocs/elisp/output-functions.html b/devdocs/elisp/output-functions.html
new file mode 100644
index 00000000..cf3d03f6
--- /dev/null
+++ b/devdocs/elisp/output-functions.html
@@ -0,0 +1,75 @@
+ <h3 class="section">Output Functions</h3> <p>This section describes the Lisp functions for printing Lisp objects—converting objects into their printed representation. </p>     <p>Some of the Emacs printing functions add quoting characters to the output when necessary so that it can be read properly. The quoting characters used are ‘<samp>"</samp>’ and ‘<samp>\</samp>’; they distinguish strings from symbols, and prevent punctuation characters in strings and symbols from being taken as delimiters when reading. See <a href="printed-representation">Printed Representation</a>, for full details. You specify quoting or no quoting by the choice of printing function. </p> <p>If the text is to be read back into Lisp, then you should print with quoting characters to avoid ambiguity. Likewise, if the purpose is to describe a Lisp object clearly for a Lisp programmer. However, if the purpose of the output is to look nice for humans, then it is usually better to print without quoting. </p> <p>Lisp objects can refer to themselves. Printing a self-referential object in the normal way would require an infinite amount of text, and the attempt could cause infinite recursion. Emacs detects such recursion and prints ‘<samp>#<var>level</var></samp>’ instead of recursively printing an object already being printed. For example, here ‘<samp>#0</samp>’ indicates a recursive reference to the object at level 0 of the current print operation: </p> <div class="example"> <pre class="example">(setq foo (list nil))
+     ⇒ (nil)
+(setcar foo foo)
+     ⇒ (#0)
+</pre>
+</div> <p>In the functions below, <var>stream</var> stands for an output stream. (See the previous section for a description of output streams. Also See <a href="output-streams#external_002ddebugging_002doutput">external-debugging-output</a>, a useful stream value for debugging.) If <var>stream</var> is <code>nil</code> or omitted, it defaults to the value of <code>standard-output</code>. </p> <dl> <dt id="print">Function: <strong>print</strong> <em>object &amp;optional stream</em>
+</dt> <dd>
+ <p>The <code>print</code> function is a convenient way of printing. It outputs the printed representation of <var>object</var> to <var>stream</var>, printing in addition one newline before <var>object</var> and another after it. Quoting characters are used. <code>print</code> returns <var>object</var>. For example: </p> <div class="example"> <pre class="example">(progn (print 'The\ cat\ in)
+       (print "the hat")
+       (print " came back"))
+     -|
+     -| The\ cat\ in
+     -|
+     -| "the hat"
+     -|
+     -| " came back"
+     ⇒ " came back"
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="prin1">Function: <strong>prin1</strong> <em>object &amp;optional stream</em>
+</dt> <dd>
+<p>This function outputs the printed representation of <var>object</var> to <var>stream</var>. It does not print newlines to separate output as <code>print</code> does, but it does use quoting characters just like <code>print</code>. It returns <var>object</var>. </p> <div class="example"> <pre class="example">(progn (prin1 'The\ cat\ in)
+       (prin1 "the hat")
+       (prin1 " came back"))
+     -| The\ cat\ in"the hat"" came back"
+     ⇒ " came back"
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="princ">Function: <strong>princ</strong> <em>object &amp;optional stream</em>
+</dt> <dd>
+<p>This function outputs the printed representation of <var>object</var> to <var>stream</var>. It returns <var>object</var>. </p> <p>This function is intended to produce output that is readable by people, not by <code>read</code>, so it doesn’t insert quoting characters and doesn’t put double-quotes around the contents of strings. It does not add any spacing between calls. </p> <div class="example"> <pre class="example">(progn
+  (princ 'The\ cat)
+  (princ " in the \"hat\""))
+     -| The cat in the "hat"
+     ⇒ " in the \"hat\""
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="terpri">Function: <strong>terpri</strong> <em>&amp;optional stream ensure</em>
+</dt> <dd>
+ <p>This function outputs a newline to <var>stream</var>. The name stands for “terminate print”. If <var>ensure</var> is non-<code>nil</code> no newline is printed if <var>stream</var> is already at the beginning of a line. Note in this case <var>stream</var> can not be a function and an error is signaled if it is. This function returns <code>t</code> if a newline is printed. </p>
+</dd>
+</dl> <dl> <dt id="write-char">Function: <strong>write-char</strong> <em>character &amp;optional stream</em>
+</dt> <dd><p>This function outputs <var>character</var> to <var>stream</var>. It returns <var>character</var>. </p></dd>
+</dl> <dl> <dt id="prin1-to-string">Function: <strong>prin1-to-string</strong> <em>object &amp;optional noescape</em>
+</dt> <dd>
+ <p>This function returns a string containing the text that <code>prin1</code> would have printed for the same argument. </p> <div class="example"> <pre class="example">(prin1-to-string 'foo)
+     ⇒ "foo"
+</pre>
+<pre class="example">(prin1-to-string (mark-marker))
+     ⇒ "#&lt;marker at 2773 in strings.texi&gt;"
+</pre>
+</div> <p>If <var>noescape</var> is non-<code>nil</code>, that inhibits use of quoting characters in the output. (This argument is supported in Emacs versions 19 and later.) </p> <div class="example"> <pre class="example">(prin1-to-string "foo")
+     ⇒ "\"foo\""
+</pre>
+<pre class="example">(prin1-to-string "foo" t)
+     ⇒ "foo"
+</pre>
+</div> <p>See <code>format</code>, in <a href="formatting-strings">Formatting Strings</a>, for other ways to obtain the printed representation of a Lisp object as a string. </p>
+</dd>
+</dl> <dl> <dt id="with-output-to-string">Macro: <strong>with-output-to-string</strong> <em>body…</em>
+</dt> <dd>
+<p>This macro executes the <var>body</var> forms with <code>standard-output</code> set up to feed output into a string. Then it returns that string. </p> <p>For example, if the current buffer name is ‘<samp>foo</samp>’, </p> <div class="example"> <pre class="example">(with-output-to-string
+  (princ "The buffer is ")
+  (princ (buffer-name)))
+</pre>
+</div> <p>returns <code>"The buffer is foo"</code>. </p>
+</dd>
+</dl>  <dl> <dt id="pp">Function: <strong>pp</strong> <em>object &amp;optional stream</em>
+</dt> <dd><p>This function outputs <var>object</var> to <var>stream</var>, just like <code>prin1</code>, but does it in a prettier way. That is, it’ll indent and fill the object to make it more readable for humans. </p></dd>
+</dl> <p>If you need to use binary I/O in batch mode, e.g., use the functions described in this section to write out arbitrary binary data or avoid conversion of newlines on non-POSIX hosts, see <a href="input-functions">set-binary-mode</a>. </p><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Output-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Output-Functions.html</a>
+  </p>
+</div>