DOCS: Explain nameservers vs ns (#608)

docs/_functions/domain/DnsProvider.md

@@ -19,3 +19,7 @@ but limit it to this many.
 
 See [this page]({{site.github.url}}/nameservers) for a detailed explanation of how DNSControl handles nameservers and NS records.
 
+If a domain (`D()`) does not include any `DnsProvider()` functions,
+the DNS records will not be modified. In fact, if you want to control
+the Registrar for a domain but not the DNS records themselves, simply
+do not include a `DnsProvider()` function for that `D()`.

docs/_functions/domain/NAMESERVER.md

@@ -25,3 +25,61 @@ D("example.com", REGISTRAR, .... ,
 
 {%endhighlight%}
 {% include endExample.html %}
+
+
+# The difference between NS() and NAMESERVER()
+
+Nameservers are one of the least
+understood parts of DNS, so a little extra explanation is required.
+
+* `NS()` lets you add an NS record to a zone, just like A() adds an A
+  record to the zone.
+
+* The `NAMESERVER()` directive adds an NS record to the parent zone.
+
+Since the parent zone could be completely unrelated to the current
+zone, changes made by `NAMESERVER()` have to be done by an API call to
+the registrar, who then figures out what to do. For example, if I
+change the `NAMESERVER()` for stackoverflow.com, DNSControl talks to
+the registrar who does the hard work of talking to the people that
+control `.com`.  If the domain was gmeet.io, the registrar does
+the right thing to talk to the people that control `.io`.
+
+(Maybe it should have been called `PARENTNAMESERVER()` but we didn't
+think of that at the time.)
+
+When you use `NAMESERVER()`, DNSControl takes care of adding the
+appropriate `NS` records to the zone.
+
+Therefore, you don't have to specify `NS()` records except when
+delegating a subdomain, in which case you are acting like a registrar!
+
+Many DNS Providers will handle all of this for you, pick the name of
+the nameservers for you and updating them (upward and in your zone)
+automatically.  For more information, refer to
+[this page]({{site.github.url}}/nameservers).
+
+
+That's why NAMESERVER() is a separate operator.
+
+
+# How to not change the parent NS records?
+
+If dnsconfig.js has zero `NAMESERVER()` commands for a domain, it will
+use the API to remove all the nameservers.
+
+If dnsconfig.js has 1 or more `NAMESERVER()` commands for a domain, it
+will use the API to set those as the nameservers (unless, of course,
+they're already correct).
+
+So how do you tell DNSControl not to make any changes?  Use the
+special Registrar called "NONE". It makes no changes.
+
+It looks like this:
+
+```
+var REG_THIRDPARTY = NewRegistrar('ThirdParty', 'NONE')
+D("mydomain.com", REG_THIRDPARTY,
+  ...
+)
+```

docs/_functions/domain/NS.md

@@ -7,7 +7,10 @@ parameters:
 ---
 
 NS adds a NS record to the domain. The name should be the relative label for the domain.
-Use `@` for the domain apex, though if you are doing this consider using NAMESERVER() instead.
+
+The name may not be `@` (the bare domain), as that is controlled via `NAMESERVER()`.
+The difference between `NS()` and `NAMESERVER()` is explained in the `NAMESERVER()` description.
+
 
 Target should be a string representing the NS target. If it is a single label we will assume it is a relative name on the current domain. If it contains *any* dots, it should be a fully qualified domain name, ending with a `.`.
 

docs/_functions/global/NewDnsProvider.md

@@ -17,8 +17,8 @@ This function will return the name as a string so that you may assign it to a va
 {% include startExample.html %}
 {% highlight js %}
 var REGISTRAR = NewRegistrar("name.com", "NAMEDOTCOM");
-var r53 = NewDnsProvider("R53","ROUTE53");
+var R53 = NewDnsProvider("r53", "ROUTE53");
 
-D("example.com", REGISTRAR, DnsProvider(r53), A("@","1.2.3.4"));
+D("example.com", REGISTRAR, DnsProvider(R53), A("@","1.2.3.4"));
 {%endhighlight%}
-{% include endExample.html %}
+{% include endExample.html %}