Doc update (#2792)

* Fix spelling in coredns.1 and corefile.7 md files
* Run make -f Makefile.doc

Signed-off-by: Miek Gieben <miek@miek.nl>

8 files changed, 97 insertions, 112 deletions

diff --git a/man/coredns-etcd.7 b/man/coredns-etcd.7
index b589f7baa..4c2078984 100644
--- a/man/coredns-etcd.7
+++ b/man/coredns-etcd.7
@@ -1,11 +1,11 @@
 .\" Generated by Mmark Markdown Processer - mmark.nl
-.TH "COREDNS-ETCD" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
+.TH "COREDNS-ETCD" 7 "April 2019" "CoreDNS" "CoreDNS Plugins"
 
-.SH NAME
+.SH "NAME"
 .PP
 \fIetcd\fP - enables reading zone data from an etcd version 3 instance.
 
-.SH DESCRIPTION
+.SH "DESCRIPTION"
 .PP
 The data in etcd instance has to be encoded as
 a message
@@ -17,7 +17,7 @@ like SkyDNS
 The etcd plugin makes extensive use of the forward plugin to forward and query other servers in the
 network.
 
-.SH SYNTAX
+.SH "SYNTAX"
 .PP
 .RS
 
@@ -48,7 +48,7 @@ etcd [ZONES...] {
     path PATH
     endpoint ENDPOINT...
     credentials USERNAME PASSWORD
-    upstream [ADDRESS...]
+    upstream
     tls CERT KEY CACERT
 }
 
@@ -70,9 +70,7 @@ queries for those zones will be subject to fallthrough.
 .IP \(bu 4
 \fB\fCupstream\fR upstream resolvers to be used resolve external names found in etcd (think CNAMEs)
 pointing to external names. If you want CoreDNS to act as a proxy for clients, you'll need to add
-the \fIforward\fP plugin. If no \fBADDRESS\fP is given, CoreDNS will resolve CNAMEs against itself.
-\fBADDRESS\fP can be an IP address, and IP:port or a string pointing to a file that is structured
-as /etc/resolv.conf.
+the \fIforward\fP plugin.
 .IP \(bu 4
 \fB\fCtls\fR followed by:
 
@@ -91,7 +89,7 @@ is needed.
 .RE
 
 
-.SH SPECIAL BEHAVIOUR
+.SH "SPECIAL BEHAVIOUR"
 .PP
 CoreDNS etcd plugin leverages directory structure to look for related entries. For example an entry \fB\fC/skydns/test/skydns/mx\fR would have entries like \fB\fC/skydns/test/skydns/mx/a\fR, \fB\fC/skydns/test/skydns/mx/b\fR and so on. Similarly a directory \fB\fC/skydns/test/skydns/mx1\fR will have all \fB\fCmx1\fR entries.
 
@@ -102,7 +100,7 @@ With etcd3, support for hierarchical keys are dropped
 .PP
 This causes two lookups from CoreDNS to etcdv3 in certain cases.
 
-.SH MIGRATION TO \fB\fCetcdv3\fR API
+.SH "MIGRATION TO "\fB\fCetcdv3\fR" API"
 .PP
 With CoreDNS release \fB\fC1.2.0\fR, you'll need to migrate existing CoreDNS related data (if any) on your etcd server to etcdv3 API. This is because with \fB\fCetcdv3\fR support, CoreDNS can't see the data stored to an etcd server using \fB\fCetcdv2\fR API.
 
@@ -110,7 +108,7 @@ With CoreDNS release \fB\fC1.2.0\fR, you'll need to migrate existing CoreDNS rel
 Refer this blog by CoreOS team
 \[la]https://coreos.com/blog/migrating-applications-etcd-v3.html\[ra] to migrate to etcdv3 API.
 
-.SH EXAMPLES
+.SH "EXAMPLES"
 .PP
 This is the default SkyDNS setup, with everything specified in full:
 
@@ -175,7 +173,7 @@ Before getting started with these examples, please setup \fB\fCetcdctl\fR (with
 If you prefer, you can use \fB\fCcurl\fR to populate the \fB\fCetcd\fR server, but with \fB\fCcurl\fR the endpoint URL depends on the version of \fB\fCetcd\fR. For instance, \fB\fCetcd v3.2\fR or before uses only [CLIENT-URL]/v3alpha/* while \fB\fCetcd v3.5\fR or later uses [CLIENT-URL]/v3/* . Also, Key and Value must be base64 encoded in the JSON payload. With \fB\fCetcdctl\fR these details are automatically taken care off. You can check this document
 \[la]https://github.com/coreos/etcd/blob/master/Documentation/dev-guide/api_grpc_gateway.md#notes\[ra] for details.
 
-.SS REVERSE ZONES
+.SS "REVERSE ZONES"
 .PP
 Reverse zones are supported. You need to make CoreDNS aware of the fact that you are also
 authoritative for the reverse. For instance if you want to add the reverse for 10.0.0.0/24, you'll
@@ -217,7 +215,7 @@ reverse.skydns.local.
 .fi
 .RE
 
-.SS ZONE NAME AS A RECORD
+.SS "ZONE NAME AS A RECORD"
 .PP
 The zone name itself can be used as A record. This behavior can be achieved by writing special entries to the ETCD path of your zone. If your zone is named \fB\fCskydns.local\fR for example, you can create an \fB\fCA\fR record for this zone as follows:
 
@@ -270,7 +268,7 @@ If you query the zone name now, you will get the following response:
 .fi
 .RE
 
-.SS ZONE NAME AS AAAA RECORD
+.SS "ZONE NAME AS AAAA RECORD"
 .PP
 If you would like to use \fB\fCAAAA\fR records for the zone name too, you can set the following:
 
@@ -298,7 +296,7 @@ If you query the zone name for \fB\fCAAAA\fR now, you will get the following res
 .fi
 .RE
 
-.SS SRV RECORD
+.SS "SRV RECORD"
 .PP
 If you would like to use \fB\fCSRV\fR records, you can set the following:
 
@@ -327,7 +325,7 @@ If you query the zone name for \fB\fCSRV\fR now, you will get the following resp
 .fi
 .RE
 
-.SS TXT RECORD
+.SS "TXT RECORD"
 .PP
 If you would like to use \fB\fCTXT\fR records, you can set the following:
 
diff --git a/man/coredns-federation.7 b/man/coredns-federation.7
index 2f857062c..c6dabd8e3 100644
--- a/man/coredns-federation.7
+++ b/man/coredns-federation.7
@@ -1,11 +1,11 @@
 .\" Generated by Mmark Markdown Processer - mmark.nl
-.TH "COREDNS-FEDERATION" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
+.TH "COREDNS-FEDERATION" 7 "April 2019" "CoreDNS" "CoreDNS Plugins"
 
-.SH NAME
+.SH "NAME"
 .PP
 \fIfederation\fP - enables federated queries to be resolved via the kubernetes plugin.
 
-.SH DESCRIPTION
+.SH "DESCRIPTION"
 .PP
 Enabling this plugin allows
 Federated
@@ -15,7 +15,7 @@ resolved via the kubernetes plugin.
 .PP
 Enabling \fIfederation\fP without also having \fIkubernetes\fP is a noop.
 
-.SH SYNTAX
+.SH "SYNTAX"
 .PP
 .RS
 
@@ -32,11 +32,12 @@ federation [ZONES...] {
 Each \fBNAME\fP and \fBDOMAIN\fP defines federation membership. One entry for each. A duplicate
 \fBNAME\fP will silently overwrite any previous value.
 .IP \(bu 4
-\fB\fCupstream\fR [\fBADDRESS\fP...] resolve the \fB\fCCNAME\fR target produced by this plugin.  CoreDNS
-will resolve External Services against itself.
+\fB\fCupstream\fR resolve the \fB\fCCNAME\fR target produced by this plugin.  CoreDNS
+will resolve External Services against itself and needs the \fIforward\fP plugin to be active to do
+so.
 
 
-.SH EXAMPLES
+.SH "EXAMPLES"
 .PP
 Here we handle all service requests in the \fB\fCprod\fR and \fB\fCstage\fR federations.
 
@@ -51,25 +52,7 @@ Here we handle all service requests in the \fB\fCprod\fR and \fB\fCstage\fR fede
         staging staging.feddomain.com
         upstream
     }
-}
-
-.fi
-.RE
-
-.PP
-Or slightly shorter:
-
-.PP
-.RS
-
-.nf
-cluster.local {
-    kubernetes
-    federation {
-        prod prod.feddomain.com
-        staging staging.feddomain.com
-        upstream
-    }
+    forward . 192.168.1.12
 }
 
 .fi
diff --git a/man/coredns-file.7 b/man/coredns-file.7
index 9da36797a..d4a8e7e6d 100644
--- a/man/coredns-file.7
+++ b/man/coredns-file.7
@@ -1,18 +1,18 @@
 .\" Generated by Mmark Markdown Processer - mmark.nl
-.TH "COREDNS-FILE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
+.TH "COREDNS-FILE" 7 "April 2019" "CoreDNS" "CoreDNS Plugins"
 
-.SH NAME
+.SH "NAME"
 .PP
 \fIfile\fP - enables serving zone data from an RFC 1035-style master file.
 
-.SH DESCRIPTION
+.SH "DESCRIPTION"
 .PP
 The file plugin is used for an "old-style" DNS server. It serves from a preloaded file that exists
 on disk. If the zone file contains signatures (i.e., is signed using DNSSEC), correct DNSSEC answers
 are returned. Only NSEC is supported! If you use this setup \fIyou\fP are responsible for re-signing the
 zonefile.
 
-.SH SYNTAX
+.SH "SYNTAX"
 .PP
 .RS
 
@@ -61,7 +61,7 @@ really useful when CoreDNS is configured as a proxy; for normal authoritative se
 need \fIor\fP want to use this. CoreDNS will resolve CNAMEs against itself.
 
 
-.SH EXAMPLES
+.SH "EXAMPLES"
 .PP
 Load the \fB\fCexample.org\fR zone from \fB\fCexample.org.signed\fR and allow transfers to the internet, but send
 notifies to 10.240.1.1
diff --git a/man/coredns-health.7 b/man/coredns-health.7
index dab43035e..47eee8671 100644
--- a/man/coredns-health.7
+++ b/man/coredns-health.7
@@ -1,16 +1,16 @@
 .\" Generated by Mmark Markdown Processer - mmark.nl
-.TH "COREDNS-HEALTH" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
+.TH "COREDNS-HEALTH" 7 "April 2019" "CoreDNS" "CoreDNS Plugins"
 
-.SH NAME
+.SH "NAME"
 .PP
 \fIhealth\fP - enables a health check endpoint.
 
-.SH DESCRIPTION
+.SH "DESCRIPTION"
 .PP
 Enabled process wide health endpoint. When CoreDNS is up and running this returns a 200 OK http
 status code. The health is exported, by default, on port 8080/health .
 
-.SH SYNTAX
+.SH "SYNTAX"
 .PP
 .RS
 
@@ -44,7 +44,7 @@ shuts down.
 
 
 .PP
-If you have multiple Server Blocks, \fIhealth\fP should only be enabled in one of them (as it is process
+If you have multiple Server Blocks, \fIhealth\fP can only be enabled in one of them (as it is process
 wide). If you really need multiple endpoints, you must run health endpoints on different ports:
 
 .PP
@@ -64,21 +64,24 @@ net {
 .fi
 .RE
 
-.SH METRICS
+.PP
+Doing this is supported but both endponts ":8080" and ":8081" will export the exact same health.
+
+.SH "METRICS"
 .PP
 If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric is exported:
 
 .IP \(bu 4
-\fB\fCcoredns_health_request_duration_seconds{}\fR - duration to process a /health query. As this should
-be a local operation it should be fast. A (large) increases in this duration indicates the
-CoreDNS process is having trouble keeping up with its query load.
+\fB\fCcoredns_health_request_duration_seconds{}\fR - duration to process a HTTP query to the local
+\fB\fC/health\fR endpoint. As this a local operation it should be fast. A (large) increase in this
+duration indicates the CoreDNS process is having trouble keeping up with its query load.
 
 
 .PP
 Note that this metric \fIdoes not\fP have a \fB\fCserver\fR label, because being overloaded is a symptom of
 the running process, \fInot\fP a specific server.
 
-.SH EXAMPLES
+.SH "EXAMPLES"
 .PP
 Run another health endpoint on http://localhost:8091
 \[la]http://localhost:8091\[ra].
@@ -110,7 +113,7 @@ Set a lameduck duration of 1 second:
 .fi
 .RE
 
-.SH BUGS
+.SH "BUGS"
 .PP
 When reloading, the health handler is stopped before the new server instance is started. If that
 new server fails to start, then the initial server instance is still available and DNS queries still
diff --git a/man/coredns-kubernetes.7 b/man/coredns-kubernetes.7
index 5b06c8d64..00a33aa6a 100644
--- a/man/coredns-kubernetes.7
+++ b/man/coredns-kubernetes.7
@@ -1,11 +1,11 @@
 .\" Generated by Mmark Markdown Processer - mmark.nl
-.TH "COREDNS-KUBERNETES" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
+.TH "COREDNS-KUBERNETES" 7 "April 2019" "CoreDNS" "CoreDNS Plugins"
 
-.SH NAME
+.SH "NAME"
 .PP
 \fIkubernetes\fP - enables the reading zone data from a Kubernetes cluster.
 
-.SH DESCRIPTION
+.SH "DESCRIPTION"
 .PP
 This plugin implements the Kubernetes DNS-Based Service Discovery
 Specification
@@ -26,7 +26,7 @@ are implemented via the \fIforward\fP plugin and kubernetes \fIupstream\fP. See
 .PP
 This plugin can only be used once per Server Block.
 
-.SH SYNTAX
+.SH "SYNTAX"
 .PP
 .RS
 
@@ -55,7 +55,7 @@ kubernetes [ZONES...] {
     labels EXPRESSION
     pods POD\-MODE
     endpoint\_pod\_names
-    upstream [ADDRESS...]
+    upstream
     ttl TTL
     noendpoints
     transfer to ADDRESS...
@@ -125,10 +125,9 @@ follows: Use the hostname of the endpoint, or if hostname is not set, use the
 pod name of the pod targeted by the endpoint. If there is no pod targeted by
 the endpoint, use the dashed IP address form.
 .IP \(bu 4
-\fB\fCupstream\fR [\fBADDRESS\fP...] defines the upstream resolvers used for resolving services
-that point to external hosts (aka External Services, aka CNAMEs).  If no \fBADDRESS\fP is given, CoreDNS
-will resolve External Services against itself. \fBADDRESS\fP can be an IP, an IP:port, or a path
-to a file structured like resolv.conf.
+\fB\fCupstream\fR defines the upstream resolvers used for resolving services
+that point to external hosts (aka External Services, aka CNAMEs).  CoreDNS
+will resolve External Services against itself.
 .IP \(bu 4
 \fB\fCttl\fR allows you to set a custom TTL for responses. The default is 5 seconds.  The minimum TTL allowed is
 0 seconds, and the maximum is capped at 3600 seconds. Setting TTL to 0 will prevent records from being cached.
@@ -155,12 +154,12 @@ This allows the querying pod to continue searching for the service in the search
 The search path could, for example, include another Kubernetes cluster.
 
 
-.SH READY
+.SH "READY"
 .PP
 This plugin reports readiness to the ready plugin. This will happen after it has synced to the
 Kubernetes API.
 
-.SH EXAMPLES
+.SH "EXAMPLES"
 .PP
 Handle all queries in the \fB\fCcluster.local\fR zone. Connect to Kubernetes in-cluster. Also handle all
 \fB\fCin-addr.arpa\fR \fB\fCPTR\fR requests for \fB\fC10.0.0.0/17\fR . Verify the existence of pods when answering pod
@@ -209,7 +208,7 @@ kubernetes cluster.local {
 .fi
 .RE
 
-.SH STUBDOMAINS AND UPSTREAMNAMESERVERS
+.SH "STUBDOMAINS AND UPSTREAMNAMESERVERS"
 .PP
 Here we use the \fIforward\fP plugin to implement a stubDomain that forwards \fB\fCexample.local\fR to the nameserver \fB\fC10.100.0.10:53\fR.
 The \fIupstream\fP option in the \fIkubernetes\fP plugin means that ExternalName services (CNAMEs) will be resolved using the respective proxy.
@@ -251,7 +250,7 @@ upstreamNameservers: |
 .fi
 .RE
 
-.SH AUTOPATH
+.SH "AUTOPATH"
 .PP
 The \fIkubernetes\fP plugin can be used in conjunction with the \fIautopath\fP plugin.  Using this
 feature enables server-side domain search path completion in Kubernetes clusters.  Note: \fB\fCpods\fR must
@@ -271,7 +270,7 @@ cluster.local {
 .fi
 .RE
 
-.SH FEDERATION
+.SH "FEDERATION"
 .PP
 The \fIkubernetes\fP plugin can be used in conjunction with the \fIfederation\fP plugin.  Using this
 feature enables serving federated domains from the Kubernetes clusters.
@@ -291,7 +290,7 @@ cluster.local {
 .fi
 .RE
 
-.SH WILDCARDS
+.SH "WILDCARDS"
 .PP
 Some query labels accept a wildcard value to match any value.  If a label is a valid wildcard (*,
 or the word "any"), then that label will match all values.  The labels that accept wildcards are:
diff --git a/man/coredns-route53.7 b/man/coredns-route53.7
index a9c078b7e..20a88b604 100644
--- a/man/coredns-route53.7
+++ b/man/coredns-route53.7
@@ -1,11 +1,11 @@
 .\" Generated by Mmark Markdown Processer - mmark.nl
-.TH "COREDNS-ROUTE53" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
+.TH "COREDNS-ROUTE53" 7 "April 2019" "CoreDNS" "CoreDNS Plugins"
 
-.SH NAME
+.SH "NAME"
 .PP
 \fIroute53\fP - enables serving zone data from AWS route53.
 
-.SH DESCRIPTION
+.SH "DESCRIPTION"
 .PP
 The route53 plugin is useful for serving zones from resource record
 sets in AWS route53. This plugin supports all Amazon Route 53 records
@@ -13,7 +13,7 @@ sets in AWS route53. This plugin supports all Amazon Route 53 records
 \[la]https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ResourceRecordTypes.html\[ra]).
 The route53 plugin can be used when coredns is deployed on AWS or elsewhere.
 
-.SH SYNTAX
+.SH "SYNTAX"
 .PP
 .RS
 
@@ -59,7 +59,7 @@ only queries for those zones will be subject to fallthrough.
 \fBZONES\fP zones it should be authoritative for. If empty, the zones from the configuration block
 
 
-.SH EXAMPLES
+.SH "EXAMPLES"
 .PP
 Enable route53 with implicit AWS credentials and an upstream:
 
@@ -69,8 +69,9 @@ Enable route53 with implicit AWS credentials and an upstream:
 .nf
 \&. {
 	route53 example.org.:Z1Z2Z3Z4DZ5Z6Z7 {
-	  upstream 10.0.0.1
+	  upstream
 	}
+    forward . 10.0.0.1
 }
 
 .fi
diff --git a/man/coredns.1 b/man/coredns.1
index 0a9684d89..2e4824ce1 100644
--- a/man/coredns.1
+++ b/man/coredns.1
@@ -1,36 +1,36 @@
 .\" Generated by Mmark Markdown Processer - mmark.nl
-.TH "COREDNS" "1" "April 2019" "CoreDNS" "CoreDNS"
+.TH "COREDNS" 1 "April 2019" "CoreDNS" "CoreDNS"
 
-.SH NAME
+.SH "COREDNS"
 .PP
 \fIcoredns\fP - plugable DNS nameserver optimized for service discovery and flexibility.
 
-.SH SYNOPSIS
+.SH "SYNOPSIS"
 .PP
-\fIcoredns\fP \fI[OPTION]\fP...
+\fIcoredns\fP \fB[-conf FILE]\fP \fB[-dns.port PORT}\fP \fB[OPTION]\fP...
 
-.SH DESCRIPTION
+.SH "DESCRIPTION"
 .PP
 CoreDNS is a DNS server that chains plugins. Each plugin handles a DNS feature, like rewriting
 queries, kubernetes service discovery or just exporting metrics. There are many other plugins,
 each described on https://coredns.io/plugins
-\[la]https://coredns.io/plugins\[ra] and there respective manual pages. Plugins not
-bundled in CoreDNS are listed on https://coredns.io/explugins
+\[la]https://coredns.io/plugins\[ra] and their respective manual pages. Plugins not
+bundled by default in CoreDNS are listed on https://coredns.io/explugins
 \[la]https://coredns.io/explugins\[ra].
 
 .PP
-When started with no options CoreDNS will looks for a file names \fB\fCCorefile\fR in the current
-directory, if found it will parse its contents and start up accordingly. If no \fB\fCCorefile\fR is found
+When started without options CoreDNS will look for a file named \fB\fCCorefile\fR in the current
+directory, if found, it will parse its contents and start up accordingly. If no \fB\fCCorefile\fR is found
 it will start with the \fIwhoami\fP plugin (coredns-whoami(7)) and start listening on port 53 (unless
 overridden with \fB\fC-dns.port\fR).
 
 .PP
 Available options:
 
-.RS
 .TP
 \fB-conf\fP \fBFILE\fP
-specify Corefile to load.
+specify Corefile to load, if not given CoreDNS will look for a \fB\fCCorefile\fR in the current
+directory.
 .TP
 \fB-cpu\fP \fBCAP\fP
 specify maximum CPU capacity in percent.
@@ -50,17 +50,16 @@ don't print any version and port information on startup.
 \fB-version\fP
 show version and quit.
 
-.RE
 
-.SH AUTHORS
+.SH "AUTHORS"
 .PP
 CoreDNS Authors.
 
-.SH COPYRIGHT
+.SH "COPYRIGHT"
 .PP
 Apache License 2.0
 
-.SH SEE ALSO
+.SH "SEE ALSO"
 .PP
 Corefile(5) coredns-k8s_external(7) coredns-erratic(7) coredns-nsid(7) coredns-hosts(7) coredns-dnssec(7) coredns-health(7) coredns-grpc(7) coredns-ready(7) coredns-file(7) coredns-root(7) coredns-autopath(7) coredns-auto(7) coredns-dnstap(7) coredns-pprof(7) coredns-tls(7) coredns-loadbalance(7) coredns-cache(7) coredns-whoami(7) coredns-bind(7) coredns-loop(7) coredns-import(7) coredns-chaos(7) coredns-template(7) coredns-log(7) coredns-kubernetes(7) coredns-forward(7) coredns-debug(7) coredns-secondary(7) coredns-route53(7) coredns-errors(7) coredns-metrics(7) coredns-reload(7) coredns-rewrite(7) coredns-metadata(7) coredns-federation(7) coredns-etcd(7) coredns-cancel(7) coredns-trace(7).
 
diff --git a/man/corefile.5 b/man/corefile.5
index a6a02c7ce..bb6d183be 100644
--- a/man/corefile.5
+++ b/man/corefile.5
@@ -1,13 +1,13 @@
 .\" Generated by Mmark Markdown Processer - mmark.nl
-.TH "COREFILE" "5" "April 2019" "CoreDNS" "CoreDNS"
+.TH "COREFILE" 5 "April 2019" "CoreDNS" "CoreDNS"
 
-.SH NAME
+.SH "NAME"
 .PP
-\fIcorefile\fP - configuration file for CoreDNS
+\fIcorefile\fP - configuration file for CoreDNS.
 
-.SH DESCRIPTION
+.SH "DESCRIPTION"
 .PP
-A \fIcorefile\fP specifies the (internal) servers CoreDNS should run and what plugins each of these
+A \fIcorefile\fP specifies the internal servers CoreDNS should run and what plugins each of these
 should chain. The syntax is as follows:
 
 .PP
@@ -32,7 +32,7 @@ The optional \fBSCHEME\fP defaults to \fB\fCdns://\fR, but can also be \fB\fCtls
 
 .PP
 The optional \fBPORT\fP controls on which port the server will bind, this default to 53. If you use
-a port number here, you \fIcan't\fP override it with \fB\fC-dns.port\fR (coredns(1)).
+a port number here, you \fIcan't\fP override it with \fB\fC-dns.port\fR (coredns(1)), also see coredns-bind(7).
 
 .PP
 Specifying a \fBZONE\fP \fIand\fP \fBPORT\fP combination multiple times for \fIdifferent\fP servers will lead to
@@ -56,7 +56,7 @@ Environment variables are supported and either the Unix or Windows form may be u
 or \fB\fC{%ENV_VAR_2%}\fR.
 
 .PP
-You can use the \fB\fCimport\fR "plugin" to include parts of other files.
+You can use the \fB\fCimport\fR "plugin" (See coredns-import(7)) to include parts of other files.
 
 .PP
 If CoreDNS can’t find a Corefile to load it loads the following builtin one:
@@ -72,12 +72,13 @@ If CoreDNS can’t find a Corefile to load it loads the following builtin one:
 .fi
 .RE
 
-.SH IMPORT
+.SH "IMPORT"
 .PP
-You can use the \fB\fCimport\fR "plugin" to include parts of other files, see https://coredns.io/plugins/import
-\[la]https://coredns.io/plugins/import\[ra].
+You can use the \fB\fCimport\fR "plugin" to include parts of other files, see
+https://coredns.io/plugins/import
+\[la]https://coredns.io/plugins/import\[ra], and coredns-import(7).
 
-.SH SNIPPETS
+.SH "SNIPPETS"
 .PP
 If you want to reuse a snippet you can define one with and then use it with \fIimport\fP.
 
@@ -97,10 +98,10 @@ If you want to reuse a snippet you can define one with and then use it with \fIi
 .fi
 .RE
 
-.SH EXAMPLES
+.SH "EXAMPLES"
 .PP
-The \fBZONE\fP is root zone \fB\fC.\fR, the \fBPLUGIN\fP is chaos. The chaos plugin takes an argument:
-\fB\fCCoreDNS-001\fR. This text is returned on a CH class query: \fB\fCdig CH txt version.bind @localhost\fR.
+The \fBZONE\fP is root zone \fB\fC.\fR, the \fBPLUGIN\fP is \fIchaos\fP. The \fIchaos\fP plugin takes an (optional) argument:
+\fB\fCCoreDNS-001\fR. This text is returned on a CH class query: \fB\fCdig CH TXT version.bind @localhost\fR.
 
 .PP
 .RS
@@ -187,18 +188,19 @@ This also works on a non octet boundary:
 .fi
 .RE
 
-.SH AUTHORS
+.SH "AUTHORS"
 .PP
 CoreDNS Authors.
 
-.SH COPYRIGHT
+.SH "COPYRIGHT"
 .PP
 Apache License 2.0
 
-.SH SEE ALSO
+.SH "SEE ALSO"
 .PP
 The manual page for CoreDNS: coredns(1) and more documentation on https://coredns.io
 \[la]https://coredns.io\[ra].
 Also see the \fIimport\fP
-\[la]https://coredns.io/plugins/import\[ra]'s documentation.
+\[la]https://coredns.io/plugins/import\[ra]'s documentation and all the manual pages
+for the plugins.