doc: Tidy up the console docs a little

Tweak the documentation to look better when viewed. Use 'write' instead
of 'put'.

Series-to: concept
Series-version: 2
Cover-letter:
console: Refactor in preparation for the pager
This series tidies up a few small things the serial and console areas:

- Move detection of serial-console size to the serial module
- Provide a Kconfig to disable serial detection
- Fix some missing driver-model flags in stdio devices
- Move console docs into the main documentation

This series is marked v2 since some of the patches were sent in any
earlier series. With various tweaks that series grew too large to be
sent as a single series.
END

Signed-off-by: Simon Glass <sjg@chromium.org>

doc/usage/console.rst

@@ -6,10 +6,10 @@
 U-Boot console handling
 =======================
 
-HOW THE CONSOLE WORKS?
+Introduction
-----------------------
+------------
 
-At system startup U-Boot initializes a serial console. When U-Boot
+At system-startup U-Boot initializes a serial console. When U-Boot
 relocates itself to RAM, all console drivers are initialized (they
 will register all detected console devices to the system for further
 use).
@@ -17,43 +17,46 @@ use).
 If not defined in the environment, the first input device is assigned
 to the 'stdin' file, the first output one to 'stdout' and 'stderr'.
 
-You can use the command "coninfo" to see all registered console
+You can use the command `coninfo` to see all registered console
 devices and their flags. You can assign a standard file (stdin,
 stdout or stderr) to any device you see in that list simply by
 assigning its name to the corresponding environment variable. For
-example:
+example::
 
-    setenv stdin serial		<- To use the serial input
+    # Use the serial input
-    setenv stdout video		<- To use the video console
+    setenv stdin serial
 
-Do a simple "saveenv" to save the console settings in the environment
+    # Use the video console
+    setenv stdout vidconsole
+
+Do a simple `saveenv` to save the console settings in the environment
 and get them working on the next startup, too.
 
-HOW CAN I USE STANDARD FILE INTO THE SOURCES?
+How to output text to the console
----------------------------------------------
+---------------------------------
 
 You can use the following functions to access the console:
 
-* STDOUT:
+stdout
-    putc	(to put a char to stdout)
+    - putc() - write a char to stdout
-    puts	(to put a string to stdout)
+    - puts() - write a string to stdout
-    printf	(to format and put a string to stdout)
+    - printf() - format and write a string to stdout
 
-* STDIN:
+stdin
-    tstc	(to test for the presence of a char in stdin)
+    - tstc() - test for the presence of a char in stdin
-    getc	(to get a char from stdin)
+    - getchar() - get a char from stdin
 
-* STDERR:
+stderr
-    eputc	(to put a char to stderr)
+    - eputc() - write a char to stderr
-    eputs	(to put a string to stderr)
+    - eputs() - write a string to stderr
-    eprintf	(to format and put a string to stderr)
+    - eprintf() - format and write a string to stderr
 
-* FILE (can be 'stdin', 'stdout', 'stderr'):
+file ('stdin', 'stdout' or 'stderr')
-    fputc	(like putc but redirected to a file)
+    - fputc() - write a char to a file
-    fputs	(like puts but redirected to a file)
+    - fputs() - write a string to a file
-    fprintf	(like printf but redirected to a file)
+    - fprintf() - format and write a string to a file
-    ftstc	(like tstc but redirected to a file)
+    - ftstc() - test for the presence of a char in file
-    fgetc	(like getc but redirected to a file)
+    - fgetc() - get a char from a file
 
-Remember that all FILE-related functions CANNOT be used before
+Remember that FILE-related functions CANNOT be used before U-Boot relocation,
-U-Boot relocation (done in 'board_init_r' in `arch/*/lib/board.c`).
+which is done in `board_init_r()`.