From c46fca3eddfa93e3edfb0fb7bc23a7bb29a3ad0b Mon Sep 17 00:00:00 2001 From: matthewwall Date: Fri, 23 Sep 2016 11:34:15 -0400 Subject: [PATCH] start of command/option disambiguation --- docs/utilities.htm | 104 +++++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 47 deletions(-) diff --git a/docs/utilities.htm b/docs/utilities.htm index 1532b876..0c7c24ca 100644 --- a/docs/utilities.htm +++ b/docs/utilities.htm @@ -157,7 +157,7 @@ Options: --debug Show diagnostic information while running. -

Command line options

+

Commands and options

--config

@@ -379,7 +379,7 @@ If you are using a MySQL database it is assumed that you have the appropriate permissions for the requested operation. -

Command line options

+

Commands and options

--create-archive

If the database does not already exist, this command will create it @@ -483,7 +483,7 @@ should thoroughly check the generated output for personal/private information before posting the information publicly. -

Command line options

+

Commands options

--info

@@ -618,22 +618,28 @@ wee_debug report successfully generated

--output

-

By default, wee_debug sends its output to the system "standard output" (stdout) unless the --output option is used.

-

Command --output with no parameter sends output to the default file /var/tmp/weewx.debug. Example:

+

By default, wee_debug sends its output to + the system "standard output" (stdout) + unless the --output option is used.

+

The option --output with no parameter + sends output to the default file + /var/tmp/weewx.debug. Example:

wee_debug --info --output
-

Command --output with a specified file will send it to that file. Example:

+

The option --output with a specified file + will send it to that file. Example:

wee_debug --info --output /home/weewx/another.debug

--verbosity

-

The depth of information included in the wee_debug output can be changed using the - --verbosity option. The --verbosity option can be set to - 0, 1 or 2 with each higher level successively displaying more information. The default level is 1. The +

The amount of information included in the + wee_debug output can be changed using the + --verbosity option. The + --verbosity option can be set to + 0, 1 or 2 with each higher level successively displaying more + information. The default level is 1. The information displayed for each level is:

@@ -795,7 +801,7 @@ Options: --dry-run Print what would happen but do not do it. --verbosity=N How much status to display, 0-3 -

Command line options

+

Commands and options

--install

Use this command to install an extension. You must specify the @@ -949,9 +955,9 @@ archive. Daily summaries are updated as each archive record is imported so there should be no need to separately drop and rebuild the daily summaries using the wee_database utility. -

Command line options

+

Commands and options

-

The wee_import command line options are described in more detail below:

+

The wee_import commands and options are described in more detail below:

--config

@@ -965,11 +971,11 @@ the daily summaries using the wee_database utility.

--import-config

wee_import uses a secondary configuration file to store various import parameters. - The --import-config command line option is mandatory for all imports. + The --import-config option is mandatory for all imports. Example import configuration files for each type of import supported by wee_import are provided in the util/import folder. These example files are best used by making a copy of the applicable example file in a working directory and then modifying the duplicate file to - suit your needs. The --import-config command line option is used as + suit your needs. The --import-config option is used as follows:

wee_import --import-config=/folder/import.conf
@@ -977,7 +983,7 @@ the daily summaries using the wee_database utility.

--dry-run

-

The inclusion of the --dry-run command line option will cause the import +

The inclusion of the --dry-run option will cause the import to proceed but no actual data will be saved to the database. This is a useful option to use when first importing data.

@@ -987,18 +993,18 @@ the daily summaries using the wee_database utility.

--date

The date-time range of records to be imported can be specified by use of the --date - command line option. The --date command line option can specify a single + option. The --date option can specify a single date, as single date-time, a date range or a date-time range. The date format used is YYYY/MM/DD and the date-time format YYYY/MM/DD HH:MM. A range is specified by separating two date or date-time formats by a hyphen, e.g., '2015/12/1-2015/12/30'. Note that the date-time or date-time range string must be enclosed in single or double quotation marks. The effect of the - different --date command line option values is shown in the following + different --date option values is shown in the following table:

- + @@ -1031,7 +1037,7 @@ the daily summaries using the wee_database utility.
command line optionoption Records imported for a CSV or Cumulus import Records imported for a Weather Underground import

- Note
If the --date command line option is omitted the default + Note
If the --date option is omitted the default is to import all available records when importing from a CSV or Cumulus source or to import today's records only when importing from Weather Underground.

@@ -1043,14 +1049,14 @@ the daily summaries using the wee_database utility. href="usersguide.htm#monitoring">Monitoring weewx and Where to find things to find it). wee_import log output can be disabled by using --log=-. - The --log command line option is used as follows:

+ The --log option is used as follows: 

wee_import --import-config=/folder/import.conf --log=-

--verbose

-

Inclusion of the --verbose command line option will cause additional +

Inclusion of the --verbose option will cause additional information to be printed during wee_import execution.

wee_import --import-config=/folder/import.conf --verbose
@@ -1060,9 +1066,8 @@ the daily summaries using the wee_database utility.

wee_import requires a second configuration file, the import configuration file, in addition to the standard weewx configuration file. The import configuration file specifies the import type - and various options associated with each type of import. The import configuration file is specified at the - wee_import command line using the mandatory --import-config command line option. How you construct the import configuration + and various options associated with each type of import. The import configuration file is specified using the mandatory --import-config option. How you construct the import configuration file is up to you; however, the recommended method is to copy one of the example import configuration files located in the util/import folder, modify the configuration options in the newly copied file to suit the import to be performed and then use this file as the import configuration file.

@@ -1661,7 +1666,7 @@ the daily summaries using the wee_database utility.
  • When first importing data it is prudent to do a dry run import before any data are actually imported. A dry run import will perform all steps of the import without actually writing imported data to the weewx database. In addition, consideration should be given to any additional - command line options such as --date. + options such as --date.

    To perform a dry run enter the following command:

    @@ -1688,7 +1693,7 @@ Finished dry run import. 70685 records were processed and 70685 unique records w

    Note
    As the weewx database is not altered when the --dry-run command line option is used, wee_import + class="code">--dry-run option is used, wee_import log output is suspended during a dry run import. In effect, the use of --dry-run is equivalent to --dry-run --log=-. During a dry run import the only wee_import output is that displayed on @@ -1884,14 +1889,14 @@ Aug 22 14:38:28 jessie2 weewx[863]: manager: unable to add record 2010-09-04 04:

  • When first importing data it is prudent to do a dry run import before any data are actually imported. A dry run import will perform all steps of the import without actually writing imported data to the weewx database. In addition, consideration should be given to any additional - command line options to be used such as --date. + options to be used such as --date.

    To perform a dry run enter the following command:

    wee_import --import-config=/var/tmp/wu.conf --date="2016/01/20 22:30-2016/01/23 06:00" --dry-run

    - Note
    If the --date command line option is omitted or a date + Note
    If the --date option is omitted or a date (not date-time) range is used during a Weather Underground import, then the current days history data will be imported. This includes records timestamped from 00:00 (inclusive) at the start of the day up to but NOT including the 00:00 @@ -1936,7 +1941,7 @@ Finished dry run import. 607 records were processed and 607 unique records would

    Note
    As the weewx database is not altered when the --dry-run command line option is used, wee_import + class="code">--dry-run option is used, wee_import log output is suspended during a dry run import. In effect, the use of --dry-run is equivalent to --dry-run --log=-. During a dry run import the only wee_import output is that displayed on @@ -1997,8 +2002,8 @@ Confirm successful import in the weewx log file. records for the same import performed at different times. If importing the current day this could be because an additional record may have been added between wee_import runs. For periods before today, this behaviour appears to be a vagary of Weather Underground. The only - solution appears to be to repeat the import with the same --date command - line option setting and observe whether the missing records are imported. Repeating the import will + solution appears to be to repeat the import with the same --date + option setting and observe whether the missing records are imported. Repeating the import will not adversely affect any existing data as records with timestamps that are already in the weewx archive will be ignored. It may; however, generated many UNIQUE constraint failed: archive.dateTime messages in the When first importing data it is prudent to do a dry run import before any data are actually imported. A dry run import will perform all steps of the import without actually writing imported data to the weewx database. In addition, consideration should be given to any additional - command line options to be used such as --date. + options to be used such as --date.

    To perform a dry run enter the following command:

    wee_import --import-config=/var/tmp/cumulus.conf --dry-run
@@ -2227,8 +2232,8 @@ Are you sure you want to proceed (y/n)?
 
                 
    If there is more than one Cumulus monthly log file then wee_import will
                     provide summary information on a per period basis during the import. In addition, if the --date command line option is used then source data that falls outside
-                    the date or date range specified with the --date command line option is
+                            class="code">--date option is used then source data that falls outside
+                    the date or date range specified with the --date option is
                     ignored. In such cases the preamble may look similar to:
    
 
     
    Starting wee_import...
@@ -2256,7 +2261,7 @@ Are you sure you want to proceed (y/n)?
 
    
 
                 
    Again if there is more than one Cumulus monthly log file and if the --date
-                    command line option is used then the progress information may instead look similar to:
    
+                    option is used then the progress information may instead look similar to:
    
 
         
    Period 4 ...
 Records processed: 2521; Unique records: 2521; Last timestamp: 2016-03-01 09:40:00 AEST (1456789200)
@@ -2477,7 +2482,7 @@ Options:
   -q, --query           For each record, query the user before making a
                         change.
    
 
-        
    Command line options
    
+        
    Commands and options
    
 
         
    The wunderfixer options are described in more detail below:
    
 
@@ -2568,13 +2573,17 @@ Options:
 
         
    --query
    
 
-        
    The --query option will cause  wunderfixer to seek user confirmation before each missing record is uploaded to 
-            Weather Underground. When queried you may respond with y to publish the record, 
-                    n to skip the record without publishing, a to 
-            publish the record and automatically publish all further records or q to skip the 
-            record and quit wunderfixer. The --query command 
-            line option should not be used as part of a cron job.
+        
    The --query option will cause
+            wunderfixer to seek user confirmation
+            before each missing record is uploaded to Weather Underground.
+            When queried you may respond with y to
+            publish the record, n to skip the record
+            without publishing, a to publish the
+            record and automatically publish all further records or
+            q to skip the record and quit
+            wunderfixer. The
+            --query option should not be used as
+            part of a cron job.
         
    
 
         
@@ -2585,8 +2594,7 @@ Options:
             you have missing Weather Underground data. Running wunderfixer directly
             is also a useful exercise in the lead up to setting wunderfixer to run as a  cron job as it allows you to verify correct operation 
-            of wunderfixer through the on screen reporting. To run wunderfixer from the command line:
+            of wunderfixer through the on screen reporting.
         
    
 
         
    
@@ -2597,6 +2605,8 @@ Options:
                     class="code">weewx.conf. Data for another station or date could be published by using the --station, --password and --date options.
         
    
 
+        
    To run wunderfixer directly:
    
+
         
      
             
    1. Before publishing missing data for the first time it may be
                 prudent to run wunderfixer with the