DOCS-527 edit, reformat, add dbshell and environment variables

Author: Ed Costello

source/reference/mongo.txt

@@ -1,20 +1,29 @@
 .. _mongo:
 
+.. meta::
+   :description: The mongo shell man page
+   :keywords: man page, mongo, javascript, shell
+   
 .. default-domain:: mongodb
 
 ================
-:program:`mongo`
+mongo
 ================
 
 Synopsis
 --------
 
+.. describe:: mongo [--shell] [--nodb] [--norc] [--quiet] [--port <port>] [--host <host>] [--eval <JavaScript>] [-u <username>] [--username <username>] [-p <password>] [--password <password>] [--help] [-h] [--version] [--verbose] [--ipv6] [database] [file.js]
+
+Description
+-----------
+
 :program:`mongo` is an interactive JavaScript shell interface to
-MongoDB. :program:`mongo` provides a powerful administrative interface
-for systems administrators as well as an way to test queries and
+MongoDB. :program:`mongo` provides a powerful interface
+for systems administrators as well as a way to test queries and
 operations directly with the database. To increase the flexibility of
 :program:`mongo`, the shell provides a fully functional JavaScript
-environment. This manual page, addresses the basic invocation of the
+environment. This document addresses the basic invocation of the
 :program:`mongo` shell and an overview of its usage.
 
 .. STUB -- This manual contains more extensive documentation of :program:`mongo` in the ":doc:`/mongo`" document.
@@ -26,84 +35,84 @@ Options
 
 .. program:: mongo
 
-.. option:: --shell
+.. cmdoption:: --shell
 
    If you invoke the :program:`mongo` and specify a :term:`JavaScript`
    file as an argument, or ":option:`mongo --eval`" the
-   :option:`--shell` provides the user with a shell prompt after the
+   :option:`--shell` option provides the user with a shell prompt after the
    file finishes executing.
 
-.. option:: --nodb
+.. cmdoption:: --nodb
 
    Use this option to prevent the shell from connecting to any
    database instance.
 
-.. option:: --norc
+.. cmdoption:: --norc
 
    By default :program:`mongo` runs the ``~/.mongorc.js`` file when it
    starts. Use this option to prevent the shell from sourcing this
    file on start up.
 
-.. option:: --quiet
+.. cmdoption:: --quiet
 
    Silences output from the shell during the connection process.
 
-.. option:: --port <PORT>
+.. cmdoption:: --port <PORT>
 
    Specify the port where the :program:`mongod` or :program:`mongos`
    instance is listening. Unless specified :program:`mongo` connects
    to :program:`mongod` instances on port 27017, which is the default
    :program:`mongod` port.
 
-.. option:: --host <HOSTNAME>
+.. cmdoption:: --host <HOSTNAME>
 
    Specific the host where the :program:`mongod` or :program:`mongos` is running to
    connect to as ``<HOSTNAME>``. By default :program:`mongo` will attempt
    to connect to MongoDB process running on the localhost.
 
-.. option:: --eval <JAVASCRIPT>
+.. cmdoption:: --eval <JAVASCRIPT>
 
    Evaluates a JavaScript specified as an argument to this
    option. :program:`mongo` does not load its own environment when evaluating
-   code: as a result many convinces of the shell environment are not
+   code: as a result many options of the shell environment are not
    available.
 
-.. option:: --username <USERNAME>, -u <USERNAME>
+.. cmdoption:: --username <USERNAME>, -u <USERNAME>
 
    Specify a username to authenticate to the MongoDB instance, if your
    database requires authentication. Use in conjunction with the
    :option:`mongo --password` option to supply a password.
 
-.. option:: --password <password>, -p <password>
+.. cmdoption:: --password <password>, -p <password>
 
    Specify a password to authenticate to the MongoDB instance, if your
    database requires authentication. Use in conjunction with the
    :option:`mongo --username` option to supply a username. If you
    specify a :option:`--username <mongo --username>` without the
-   :option:`--password` option, :program:`mongo` will prompt for a
+   :option:`mongo --password` option, :program:`mongo` will prompt for a
    password interactively.
 
-.. option:: --help,  -h
+.. cmdoption:: --help,  -h
 
    Returns a basic help and usage text.
 
-.. option:: --version
+.. cmdoption:: --version
 
    Returns the version of the shell.
 
-.. option:: --verbose
+.. cmdoption:: --verbose
 
    Increases the verbosity of the output of the shell during the
    connection process.
 
-.. option:: --ipv6
+.. cmdoption:: --ipv6
 
    Enables IPv6 support that allows :program:`mongo` to connect
    to the MongoDB instance using an IPv6 network. All MongoDB programs
    and processes, including :program:`mongo`, disable IPv6
    support by default.
 
-.. option:: <db address>
+.. cmdoption:: <db address>
 
    Specify the "database address" of the database to connect to. For
    example: ::
@@ -122,15 +131,13 @@ Options
 
 .. _mongo-shell-file:
 
-.. option:: <file.js>
+.. cmdoption:: <file.js>
 
    Optionally, specify a JavaScript file as the final argument to the
    shell. The shell will run the file and then exit. Use the
-   :option:`mongo --shell` to return to a shell after the file
+   :option:`mongo --shell` option to return to a shell after the file
    finishes running.
 
-   This should be the last address
-
 Usage
 -----
 
@@ -156,7 +163,7 @@ values for your situation and substitute or omit the :option:`--port`
 as needed.
 
 To execute a JavaScript file without evaluating the ``~/.mongorc.js``
-file before starting a sell session, use the following form:
+file before starting a shell session, use the following form:
 
 .. code-block:: sh
 
@@ -172,3 +179,66 @@ the :option:`--eval <mongo --eval>` option, use the following form:
 Note the use of single quotes (e.g. ``'``) to enclose the JavaScript,
 as well as the additional JavaScript required to generate this
 output.
+
+Files
+-----
+
+:file:`~/.dbshell` 
+	
+	:program:`mongo` maintains a history of commands in the `.dbshell`
+	file.  
+	
+	.. note:
+	
+		Authentication commands (such as :dbcommand:`authenticate`, 
+		:method:`db.addUser()`) will not be saved in the history file.
+		
+	.. warning:
+	
+		Versions of Windows :command:`mongo.exe` earlier than 2.2.0 
+		will save the `.dbshell` file in the :command:`mongo.exe` 
+		working directory.
+		
+:file:`~/.mongorc.js`
+
+	:program:`mongo` will read `.mongorc.js` from the home directory
+	of the user invoking :program:`mongo`.  
+	Specify the :option:`mongo --norc` option to disable 
+	reading `.mongorc.js`.
+	
+:file:`/tmp/mongo_edit{<time_t>}.js`
+
+	 Created by :program:`mongo` when editing a file.  If the file
+	 exists :program:`mongo` will append an integer from 1 to 10 to
+	 the time value to attempt to create a unique file.
+	 
+:file:`%TEMP%\mongo_edit{<time_t>}.js`
+
+	 Created by :command:`mongo.exe` on Windows when editing a file.  
+	 If the file
+	 exists :program:`mongo` will append an integer from 1 to 10 to
+	 the time value to attempt to create a unique file.
+
+Environment
+-----------
+
+.. envvar:: EDITOR
+
+	Specify the path to an editor to use with the `edit` shell command.
+	A JavaScript variable `EDITOR` will override the value of 
+	:envvar:`EDITOR`.
+
+.. envvar:: HOME
+
+	Specify the path to the home directory where `.mongorc.js` will be
+	read from and `.dbshell` will be written to.
+
+.. envvar:: HOMEDRIVE
+
+	Specify the Windows path to the home directory where `.mongorc.js` will be
+	read from and `.dbshell` will be written to.
+
+.. envvar:: HOMEPATH
+
+	Specify the Windows path to the home directory where `.mongorc.js` will be
+	read from and `.dbshell` will be written to.