Documentation: review applications/nsh

Documentation/applications/nsh/builtin.rst

@@ -1,6 +1,6 @@
-***************************
+===========================
 NSH "Built-In" Applications
-***************************
+===========================
 
 **Overview.** In addition to these commands that are a part of NSH,
 external programs can also be executed as NSH commands. These external
@@ -27,7 +27,7 @@ Note that no detailed help information beyond the name of the built-in
 application is provided.
 
 Built-In Applications
-~~~~~~~~~~~~~~~~~~~~~
+=====================
 
 **Overview.** The underlying logic that supports the NSH built-in
 applications is called "Built-In Applications". The builtin application
@@ -185,7 +185,7 @@ be mentioned.
      functionality.
 
 Synchronous Built-In Applications
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=================================
 
 By default, built-in commands started from the NSH command line will run
 asynchronously with NSH. If you want to force NSH to execute commands

Documentation/applications/nsh/config.rst

@@ -488,3 +488,16 @@ Configuration                  Description
 ``CONFIG_NSH_FATSECTSIZE``     This is the sector size use with the FAT FS. Default is 512.
 ============================== =======================================================
 
+
+Common Problems
+===============
+
+Problem::
+
+  The function 'readline' is undefined.
+
+Usual Cause:
+
+* The following is missing from your `defconfig` file::
+
+    CONFIG_SYSTEM_READLINE=y

Documentation/applications/nsh/customizing.rst

@@ -1,6 +1,6 @@
-*************************
+========================*
 Customizing the NuttShell
-*************************
+========================*
 
 **Overview.** The NuttShell (NSH) is a simple shell application that may
 be used with NuttX. It supports a variety of commands and is (very)
@@ -10,7 +10,7 @@ customizing NSH: Adding new commands, changing the initialization
 sequence, etc.
 
 The NSH Library and NSH Initialization
-**************************************
+======================================
 
 **Overview.** NSH is implemented as a library that can be found at
 ``apps/nshlib``. As a library, it can be custom built into any
@@ -23,7 +23,7 @@ as their application ``main()`` function. That initialization performed
 by that example is discussed in the following paragraphs.
 
 NSH Initialization sequence
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 The NSH start-up sequence is very simple. As an example, the code at
 ``apps/system/nsh/nsh_main.c`` illustrates how to start NSH. It simple
@@ -43,7 +43,7 @@ does the following:
      finished the entire NSH initialization sequence.
 
 ``nsh_initialize()``
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 The NSH initialization function, ``nsh_initialize()``, be found in
 ``apps/nshlib/nsh_init.c``. It does only four things:
@@ -118,7 +118,7 @@ The NSH initialization function, ``nsh_initialize()``, be found in
      found in ``apps/nshlib/nsh_romfsimg.h``.
 
 NSH Commands
-************
+============
 
 **Overview.** NSH supports a variety of commands as part of the NSH
 program. All of the NSH commands are listed in the NSH documentation
@@ -133,7 +133,7 @@ commands will be missing from the list of commands presented by
 table `above <#cmddependencies>`__.
 
 Adding New NSH Commands
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 New commands can be added to the NSH very easily. You simply need to add
 two things:

Documentation/applications/nsh/index.rst

@@ -2,9 +2,14 @@
 NuttShell (NSH)
 ===============
 
-The NuttShell is a very complete shell system to be used in NuttX, similar to bash and other similar options. It supports a rich set of included commands, scripting and the ability to run your own applications as "builtin" (part of the same NuttX binary). NSH is implemented as an application where most of the functionality is part of the library called `nshlib`.
+The NuttShell is a very complete shell system to be used in NuttX, similar to
+bash and other similar options. It supports a rich set of included commands,
+scripting and the ability to run your own applications as "builtin" (part of the
+same NuttX binary). NSH is implemented as an application where most of the
+functionality is part of the library called `nshlib`.
 
-As such, NSH is completely optional and can be disabled so that NuttX directly starts a given task instead of the main ``nsh`` application.
+As such, NSH is completely optional and can be disabled so that NuttX directly
+starts a given task instead of the main ``nsh`` application.
 
 .. toctree::
   :maxdepth: 2

Documentation/applications/nsh/installation.rst

@@ -1,6 +1,6 @@
-******************************
+==============================
 Customizing NSH Initialization
-******************************
+==============================
 
 **Ways to Customize NSH Initialization**. There are three ways to
 customize the NSH start-up behavior. Here they are presented in order of
@@ -28,7 +28,7 @@ increasing difficulty:
      deserves its own paragraph
 
 NuttShell Start up Scripts
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 First of all you should look at `NSH Start-Up Script <#startupscript>`__
 paragraph. Most everything you need to know can be found there. That

Documentation/applications/nsh/login.rst

@@ -1,9 +1,9 @@
-***********
+===========
 Shell Login
-***********
+===========
 
 Enabling Shell Logins
-*********************
+=====================
 
 NuttShell sessions can be protected by requiring that the user supply
 username and password credentials at the beginning of the session.
@@ -39,7 +39,7 @@ will be closed. That number is controlled by::
   CONFIG_NSH_LOGIN_FAILCOUNT=3
 
 Verification of Credentials
-***************************
+===========================
 
 There are three ways that NSH can be configured to verify user
 credentials at login time:
@@ -89,7 +89,7 @@ credentials at login time:
        CONFIG_NSH_LOGIN_PASSWD=y
 
 Password Files
-**************
+==============
 
 NuttX can also be configured to support a password file, by default at
 ``/etc/passwd``. This option enables support for a password file::
@@ -150,7 +150,7 @@ Instead, the password file will be consulted to verify the user
 credentials.
 
 Creating a Password File for a ROMFS File System
-************************************************
+================================================
 
 What we want to accomplish is a ROMFS file system, mounted at ``/etc``
 and containing the password file, ``passwd`` like::

Documentation/applications/nsh/nsh.rst

@@ -1,9 +1,9 @@
 .. include:: /substitutions.rst
 .. _nsh:
 
-********
+========
 Overview
-********
+========
 
 **The NSH Library**. The ``apps/nshlib`` sub-directory contains the
 NuttShell (NSH) library. This library can easily to linked to
@@ -12,7 +12,7 @@ produce a NSH application (See as an example
 application for NuttX.
 
 Console/NSH Front End
-*********************
+=====================
 
 **NSH Consoles**. Using settings in the configuration file, NSH may be
 configured to use (1) the serial stdin/out, (2) a USB serial
@@ -83,7 +83,7 @@ Key Binding            Editor Action
 =====================  ================================================
 
 Command Overview
-****************
+================
 
 **Simple, Re-directed, and Background Commands**. The NuttShell
 (NSH) is a simple shell application. NSH supports the following
@@ -159,7 +159,7 @@ significant resources, they are disabled by default.
      also selected.
 
 Conditional Command Execution
-*****************************
+=============================
 
 An ``if-then[-else]-fi`` construct is also supported in order to
 support conditional execution of commands. This works from the
@@ -191,7 +191,7 @@ Examples:
   1 is not equal 0
 
 Looping
-*******
+=======
 
 **Looping Constructs**. ``while-do-done`` and ``until-do-done``
 looping constructs are also supported. These work from the command
@@ -233,7 +233,7 @@ the loop will immediately terminate and execution will continue
 with the next command immediately following the ``done`` token.
 
 Built-In Variables
-******************
+==================
 
 ======  ====================================================
 ``$?`` 	The result of the last simple command execution. |br|
@@ -242,7 +242,7 @@ Built-In Variables
 ======  ====================================================
 
 Current Working Directory
-*************************
+=========================
 
 ``cd`` **and** ``pwd``. All path arguments to commands may be
 either an absolute path or a path relative to the current working
@@ -251,7 +251,7 @@ directory. The current working directory is set using the
 ``pwd`` command or by using the ``echo $PWD`` command.
 
 Environment Variables
-*********************
+=====================
 
 ==========  ================================================
 ``PATH``    The default path in the file systems to look |br|
@@ -260,8 +260,9 @@ Environment Variables
 ``OLDPWD``  The previous working directory
 ==========  ================================================
 
+
 NSH Start-Up Script
-*******************
+===================
 
 **NSH Start-Up Script**. NSH supports options to provide a start
 up script for NSH. In general this capability is enabled with