Improve docs formatting of command line options.

Author: dimitri

docs/pgloader.rst

@@ -59,102 +59,103 @@ Options
 Inquiry Options
 ^^^^^^^^^^^^^^^
 
-Use these options when you want to know more about how to use `pgloader`, as
-those options will cause `pgloader` not to load any data.
+Use these options when you want to know more about how to use pgloader, as
+those options will cause pgloader not to load any data.
 
- * `-h`, `--help`
+--help
 
  Show command usage summary and exit.
 
- * `-V`, `--version`
+--version
 
  Show pgloader version string and exit.
 
- * `-E`, `--list-encodings`
+--with-encodings
 
  List known encodings in this version of pgloader.
 
- * `-U`, `--upgrade-config`
+--upgrade-config
 
- Parse given files in the command line as `pgloader.conf` files with the
- `INI` syntax that was in use in pgloader versions 2.x, and output the
+ Parse given files in the command line as ``pgloader.conf`` files with
+ the INI syntax that was in use in pgloader versions 2.x, and output the
  new command syntax for pgloader on standard output.
 
 
 General Options
 ^^^^^^^^^^^^^^^
 
-Those options are meant to tweak `pgloader` behavior when loading data.
+Those options are meant to tweak pgloader behavior when loading data.
 
- * `-v`, `--verbose`
+--verbose
 
  Be verbose.
 
- * `-q`, `--quiet`
+--quiet
 
  Be quiet.
 
- * `-d`, `--debug`
+--debug
 
  Show debug level information messages.
 
- * `-D`, `--root-dir`
+--root-dir
 
- Set the root working directory (default to "/tmp/pgloader").
+ Set the root working directory (defaults to ``/tmp/pgloader``).
 
- * `-L`, `--logfile`
+--logfile
 
- Set the pgloader log file (default to "/tmp/pgloader/pgloader.log").
+ Set the pgloader log file (defaults to ``/tmp/pgloader/pgloader.log``).
 
- * `--log-min-messages`
+--log-min-messages
 
  Minimum level of verbosity needed for log message to make it to the
  logfile. One of critical, log, error, warning, notice, info or debug.
 
- * `--client-min-messages`
+--client-min-messages
 
  Minimum level of verbosity needed for log message to make it to the
  console. One of critical, log, error, warning, notice, info or debug.
 
- * `-S`, `--summary`
+--summary
 
  A filename where to copy the summary output. When relative, the filename
- is expanded into `*root-dir*`.
+ is expanded into ``*root-dir*``.
 
  The format of the filename defaults to being *human readable*. It is
+
  possible to have the output in machine friendly formats such as *CSV*,
  *COPY* (PostgreSQL's own COPY format) or *JSON* by specifying a filename
- with the extension resp. `.csv`, `.copy` or `.json`.
+ with the extension resp. ``.csv``, ``.copy`` or ``.json``.
 
- * `-l <file>`, `--load-lisp-file <file>`
+--load-lisp-file <file>
 
  Specify a lisp <file> to compile and load into the pgloader image before
  reading the commands, allowing to define extra transformation function.
- Those functions should be defined in the `pgloader.transforms` package.
- This option can appear more than once in the command line.
+ Those functions should be defined in the ``pgloader.transforms``
+ package. This option can appear more than once in the command line.
 
- * `--dry-run`
+--dry-run
 
- Allow testing a `.load` file without actually trying to load any data.
+ Allow testing a ``.load`` file without actually trying to load any data.
  It's useful to debug it until it's ok, in particular to fix connection
  strings.
 
- * `--on-error-stop`
+--on-error-stop
 
  Alter pgloader behavior: rather than trying to be smart about error
  handling and continue loading good data, separating away the bad one,
  just stop as soon as PostgreSQL refuses anything sent to it. Useful to
  debug data processing, transformation function and specific type
  casting.
 
- * `--self-upgrade <directory>`
+--self-upgrade <directory>
 
  Specify a <directory> where to find pgloader sources so that one of the
  very first things it does is dynamically loading-in (and compiling to
  machine code) another version of itself, usually a newer one like a very
  recent git checkout.
 
- * `--no-ssl-cert-verification`
+--no-ssl-cert-verification
 
  Uses the OpenSSL option to accept a locally issued server-side
  certificate, avoiding the following error message::
@@ -169,53 +170,55 @@ Those options are meant to tweak `pgloader` behavior when loading data.
 Command Line Only Operations
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Those options are meant to be used when using `pgloader` from the command
-line only, rather than using a command file and the rich command clauses and
+Those options are meant to be used when using pgloader from the command line
+only, rather than using a command file and the rich command clauses and
 parser. In simple cases, it can be much easier to use the *SOURCE* and
 *TARGET* directly on the command line, then tweak the loading with those
 options:
 
- * `--with "option"`
+--with <option>
 
  Allows setting options from the command line. You can use that option as
  many times as you want. The option arguments must follow the *WITH*
- clause for the source type of the `SOURCE` specification, as described
+ clause for the source type of the ``SOURCE`` specification, as described
  later in this document.
 
- * `--set "guc_name='value'"`
+--set
 
  Allows setting PostgreSQL configuration from the command line. Note that
  the option parsing is the same as when used from the *SET* command
  clause, in particular you must enclose the guc value with single-quotes.
 
- * `--field "..."`
+ Use ``--set "guc_name='value'"``.
+
+--field
 
  Allows setting a source field definition. Fields are accumulated in the
- order given on the command line. It's possible to either use a `--field`
- option per field in the source file, or to separate field definitions by
- a comma, as you would do in the *HAVING FIELDS* clause.
+ order given on the command line. It's possible to either use a
+ ``--field`` option per field in the source file, or to separate field
+ definitions by a comma, as you would do in the *HAVING FIELDS* clause.
 
- * `--cast "..."`
+--cast <rule>
 
  Allows setting a specific casting rule for loading the data.
 
- * `--type csv|fixed|db3|ixf|sqlite|mysql|mssql`
+--type <csv|fixed|db3|ixf|sqlite|mysql|mssql>
 
  Allows forcing the source type, in case when the *SOURCE* parsing isn't
  satisfying.
 
- * `--encoding <encoding>`
+--encoding <encoding>
 
  Set the encoding of the source file to load data from.
 
- * `--before <filename>`
+--before <filename>
 
  Parse given filename for SQL queries and run them against the target
  database before loading the data from the source. The queries are parsed
  by pgloader itself: they need to be terminated by a semi-colon (;) and
  the file may include `\i` or `\ir` commands to *include* another file.
 
- * `--after <filename>`
+--after <filename>
 
  Parse given filename for SQL queries and run them against the target
  database after having loaded the data from the source. The queries are