From bbbadbcb7881c11ec3f4f4790d7331cac9d16b65 Mon Sep 17 00:00:00 2001
From: Fabian Homborg <FHomborg@gmail.com>
Date: Mon, 10 Aug 2015 23:49:22 +0200
Subject: [PATCH] Document printf

---
 doc_src/printf.txt | 70 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 doc_src/printf.txt

diff --git a/doc_src/printf.txt b/doc_src/printf.txt
new file mode 100644
index 000000000..6c3ed558d
--- /dev/null
+++ b/doc_src/printf.txt
@@ -0,0 +1,70 @@
+\section printf printf - display text according to a format string
+
+\subsection printf-synopsis Synopsis
+\fish{synopsis}
+printf format [argument...]
+\endfish
+
+\subsection printf-description Description
+A front end to the printf function that lets it be used from the shell.
+
+This tool reads a format string, and then outputs the arguments according to that format.
+
+Unlike `echo`, however, it does not append a newline unless explicitly directed to.
+
+Valid format specifiers are:
+
+- `%%d`: Argument will be used as decimal integer (signed or unsigned)
+
+- `%%i`: Argument will be used as a signed integer
+
+- `%%o`: An octal unsigned integer
+
+- `%%u`: An unsigned decimal integer
+
+- `%%x` or `%%X`: An unsigned hexadecimal integer
+
+- `%%f`, `%%g` or `%%G`: A floating-point number
+
+- `%%e` or `%%E`: A floating-point number in scientific (XXXeYY) notation
+
+- `%%s`: A string
+
+- `%%b`: As a string, interpreting backslash escapes, except that octal escapes are of the form \0 or \0ooo.
+
+`%%` signifies a literal "%".
+
+Note that conversion may fail, e.g. "102.234" will not losslessly convert to an integer, causing printf to print an error.
+
+printf also knows a number of backslash escapes:
+- `\"` double quote
+- `\\` backslash
+- `\a` alert (bell)
+- `\b` backspace
+- `\c` produce no further output
+- `\e` escape
+- `\f` form feed
+- `\n` new line
+- `\r` carriage return
+- `\t` horizontal tab
+- `\v` vertical tab
+- `\ooo` octal number (ooo is 1 to 3 digits)
+- `\xhh` hexadecimal number (hhh is 1 to 2 digits)
+- `\uhhhh` 16-bit Unicode character (hhhh is 4 digits)
+- `\Uhhhhhhhh` 32-bit Unicode character (hhhhhhhh is 8 digits)
+
+The `format' argument is re-used as many times as necessary to convert all of the given arguments.
+
+This file has been imported from source code of printf command in GNU Coreutils version 6.9. If you would like to use a newer version of printf, for example the one shipped with your OS, try `command printf`.
+
+\subsection printf-example Example
+
+\fish
+printf '%s\t%s\n' flounder fish
+\endfish
+Will print "flounder	fish" (separated with a tab character), followed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character.
+
+\fish
+printf '%s:%d' "Number of bananas in my pocket" 42
+\endfish
+Will print "Number of bananas in my pocket: 42", _without_ a newline.