get-zone documentation and help fixes (#766)

commands/getZones.go

@@ -39,8 +39,8 @@ ARGUMENTS:
 
 FORMATS:
    --format=js        dnsconfig.js format (not perfect, just a decent first draft)
-   --format=djs       js with disco commas
-   --format=zone      BIND Zonefile format
+   --format=djs       js with disco commas (leading commas)
+   --format=zone      BIND zonefile format
    --format=tsv       TAB separated value (useful for AWK)
    --format=nameonly  Just print the zone names
 
@@ -55,10 +55,10 @@ The --ttl flag only applies to zone/js/djs formats.
 
 EXAMPLES:
    dnscontrol get-zones myr53 ROUTE53 example.com
-   dnscontrol get-zones gmain GANDI_V5 example.comn other.com
+   dnscontrol get-zones gmain GANDI_V5 example.com other.com
    dnscontrol get-zones cfmain CLOUDFLAREAPI all
-   dnscontrol get-zones -format=tsv bind BIND example.com
-   dnscontrol get-zones -format=djs -out=draft.js glcoud GCLOUD example.com`,
+   dnscontrol get-zones --format=tsv bind BIND example.com
+   dnscontrol get-zones --format=djs --out=draft.js glcoud GCLOUD example.com`,
 	}
 }())
 

docs/get-zones.md

@@ -17,10 +17,11 @@ bootstrapping a new system.
 
 If you are moving a DNS zone from a provider to DNSControl, this
 command will do most of the work for you by downloading the records
-and writing them out in `dnsconfig.js`-format. It is intended to be
+and writing them out in `dnsconfig.js` format. It is intended to be
 "a decent first draft", only requiring minimal editing.
 
-Use `--format=djs` or `--format=js` (djs is recommended).
+Use `--format=djs` or `--format=js` (djs is recommended; djs format is a
+comma-leading formatting style for lists, sometimes also called Haskell style).
 
 Minor editing is required. Not all record formats are supported.
 SOA records are commented out, since most providers do not support it.
@@ -32,7 +33,7 @@ API. Remove the comments only to override the DNS service provider.
 
 ## Use case 2: Generating BIND ZONE files
 
-The `--format=zone` generates BIND-style Zonefiles. Pseudo records not
+The `--format=zone` generates BIND-style zonefiles. Pseudo records not
 supported by BIND are generated as comments.
 
 This format is useful when moving zonedata between providers, since
@@ -69,8 +70,8 @@ ARGUMENTS:
 
 FORMATS:
    --format=js        dnsconfig.js format (not perfect, just a decent first draft)
-   --format=djs       js with disco commas
-   --format=zone      BIND Zonefile format
+   --format=djs       js with disco commas (leading commas)
+   --format=zone      BIND zonefile format
    --format=tsv       TAB separated value (useful for AWK)
    --format=nameonly  Just print the zone names
 
@@ -88,13 +89,13 @@ The --ttl flag only applies to zone/js/djs formats.
    dnscontrol get-zones myr53 ROUTE53 example.com
    dnscontrol get-zones gmain GANDI_V5 example.comn other.com
    dnscontrol get-zones cfmain CLOUDFLAREAPI all
-   dnscontrol get-zones -format=tsv bind BIND example.com
-   dnscontrol get-zones -format=djs -out=draft.js glcoud GCLOUD example.com`,
+   dnscontrol get-zones --format=tsv bind BIND example.com
+   dnscontrol get-zones --format=djs --out=draft.js glcoud GCLOUD example.com`,
 
 Read a zonefile, generate a JS file, then use the JS file to see how
 different it is from the zonefile:
 
-   dnscontrol get-zone --format=djs -out=foo.djs bind BIND example.org 
+   dnscontrol get-zone --format=djs -out=foo.djs bind BIND example.org
    dnscontrol preview --config foo.js
 
 # Developer Notes

docs/migrating.md

@@ -44,9 +44,9 @@ However, where's the fun in that?
 
 The `dnscontrol get-zones` subcommand
 [documented here]({{site.github.url}}/get-zones)
-can automate 90% of the conversion for you. It
-reads BIND-style zonefiles, or will use a providers API to gather the DNS records.  It will then output the records in a variety of formats, including
-the as a `D()` statement
+can automate 90% of the conversion for you. It reads BIND-style zonefiles,
+or will use a providers API to gather the DNS records.  It will then output
+the records in a variety of formats, including as a `D()` statement
 that is usually fairly complete. You may need to touch it up a bit,
 especially if you use pseudo record types in one provider that are
 not supported by another.
@@ -56,13 +56,13 @@ Example 1: Read a BIND zonefile
 Most DNS Service Providers have an 'export to zonefile' feature.
 
 ```
-dnscontrol get-zones -format=js bind BIND example.com
-dnscontrol get-zones -format=js -out=draft.js bind BIND example.com
+dnscontrol get-zones --format=js bind BIND example.com
+dnscontrol get-zones --format=js --out=draft.js bind BIND example.com
 ```
 
 This will read the file `zones/example.com.zone`. The system is a bit
-inflexible and that must be the filename. You can copy the file to
-that name, or use a symlink.
+inflexible and that must be the filename. You can copy the zone file to
+that name or use a symlink.
 
 Add the contents of `draft.js` to `dnsconfig.js` and edit it as needed.
 
@@ -75,8 +75,8 @@ Suppose your `creds.json` file has the name `global_aws`
 for the provider `ROUTE53`.  Your command would look like this:
 
 ```
-dnscontrol get-zones -format=js global_aws ROUTE53 example.com
-dnscontrol get-zones -format=js -out=draft.js global_aws ROUTE53 example.com
+dnscontrol get-zones --format=js global_aws ROUTE53 example.com
+dnscontrol get-zones --format=js --out=draft.js global_aws ROUTE53 example.com
 ```
 
 Add the contents of `draft.js` to `dnsconfig.js` and edit it as needed.
@@ -108,7 +108,7 @@ to convert a zone. Lines that start with `#` are comments.
 
     # Note this command uses ">>" to append to dnsconfig.js.  Do
     # not use ">" as that will erase the existing file.
-    dnscontrol get-zones -format=js -out=draft.js bind BIND foo.com
+    dnscontrol get-zones --format=js --out=draft.js bind BIND foo.com
     cat >>dnsconfig.js draft.js   # Append to dnsconfig.js
     #
     dnscontrol preview