all: simplify cmd/resolver documentation

It is hard to keep the documentation in sync between manual page,
the Go documentation, and command line usage.
A changes in manual page need to be copied into two different places.

To simplify this, we make the Go doc comment as summary and the command
line usage is set from output of `go tool doc ./cmd/resolver`.

2 files changed, 111 insertions, 288 deletions

diff --git a/cmd/resolver/doc.go b/cmd/resolver/doc.go
new file mode 100644
index 0000000..8c86091
--- /dev/null
+++ b/cmd/resolver/doc.go
@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2022 M. Shulhan <ms@kilabit.info>
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/*
+Command resolver is command line interface (CLI) for DNS and rescached server.
+
+# SYNOPSIS
+
+	resolver [-insecure] [-ns=<dns-URL>] [-server=<rescached-URL>] <command> [args...]
+
+# DESCRIPTION
+
+resolver is a tool to resolve hostname to IP address or to query services
+on hostname by type (MX, SOA, TXT, etc.) using standard DNS protocol with UDP,
+DNS over TLS (DoT), or DNS over HTTPS (DoH).
+
+It is also provide CLI to the rescached server to manage environment, block.d,
+hosts.d, and zone.d; as in the web user interface.
+
+# OPTIONS
+
+The following options affect the command operation.
+
+	-insecure
+
+Ignore invalid server certificate when querying DoT, DoH, or rescached
+server.
+This option only affect the `query` command.
+
+	-ns=<dns-URL>
+
+This option define the parent DNS server where the resolver send the query.
+This option only affect the `query` command.
+
+The nameserver is defined in the following format,
+
+	("udp"/"tcp"/"https") "://" (domain / ip-address) [":" port]
+
+Examples,
+
+  - udp://194.233.68.184:53 for querying with UDP,
+  - tcp://194.233.68.184:53 for querying with TCP,
+  - https://194.233.68.184:853 for querying with DNS over TLS (DoT), and
+  - https://kilabit.info/dns-query for querying with DNS over HTTPS (DoH).
+
+Default to one of "nameserver" in `/etc/resolv.conf`.
+
+	-server=<rescached-URL>
+
+Set the rescached HTTP server where commands, except query, will be send.
+The rescached-URL use HTTP scheme:
+
+	("http" / "https") "://" (domain / ip-address) [":" port]
+
+Default to https://127.0.0.1:5380 if its empty.
+
+# COMMANDS
+
+Query the DNS server,
+
+	query <domain / ip-address> [type] [class]
+
+Managing block.d files,
+
+	block.d disable <name>
+	block.d enable <name>
+	block.d update <name>
+
+Managing caches,
+
+	caches
+	caches search <string>
+	caches remove <string>
+
+Managing environment,
+
+	env
+	env update <path-to-file / "-">
+
+Managing hosts.d files,
+
+	hosts.d create <name>
+	hosts.d get <name>
+
+Managing record in hosts.d file,
+
+	hosts.d rr add <name> <domain> <value>
+	hosts.d rr delete <name> <domain>
+
+Managing zone.d files,
+
+	zone.d
+	zone.d create <name>
+	zone.d delete <name>
+
+Managing record in zone.d,
+
+	zone.d rr get <zone>
+	zone.d rr add <zone> <"@" | subdomain> <ttl> <type> <class> <value> ...
+	zone.d rr delete <zone> <"@" | subdomain> <type> <class> <value>
+
+For more information see the manual page for resolver(1) or its HTML page at
+http://127.0.0.1:5380/doc/resolver.html.
+*/
+package main
diff --git a/cmd/resolver/main.go b/cmd/resolver/main.go
index 556cff1..3b27c90 100644
--- a/cmd/resolver/main.go
+++ b/cmd/resolver/main.go
@@ -1,8 +1,6 @@
 // SPDX-FileCopyrightText: 2018 M. Shulhan <ms@kilabit.info>
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-// Command resolver is client for DNS server to resolve query and client for
-// rescached HTTP server.
 package main
 
 import (
@@ -34,6 +32,10 @@ const (
 	subCmdUpdate  = "update"
 )
 
+var (
+	Usage string // Overwritten by build.
+)
+
 func main() {
 	var (
 		rsol = new(resolver)
@@ -54,12 +56,12 @@ func main() {
 	args = flag.Args()
 
 	if optHelp {
-		help()
+		fmt.Println(Usage)
 		os.Exit(1)
 	}
 
 	if len(args) == 0 {
-		help()
+		fmt.Println(Usage)
 		os.Exit(1)
 	}
 
@@ -95,287 +97,3 @@ func main() {
 		os.Exit(2)
 	}
 }
-
-func help() {
-	fmt.Println(`
-= resolver
-
-resolver is command line interface for DNS and rescached server
-
-==  Usage
-
-	resolver [-insecure] [-ns nameserver] [-server] <command> [args...]
-
-==  Options
-
-The following options affect the commands operation.
-
--insecure
-
-	Ignore invalid server certificate when querying DoT, DoH, or rescached
-	server.
-
--ns nameserver
-
-	Parent name server address using scheme based.
-	For example,
-
-	* udp://35.240.172.103:53 for querying with UDP,
-	* tcp://35.240.172.103:53 for querying with TCP,
-	* https://35.240.172:103:853 for querying with DNS over TLS (DoT), and
-	* https://kilabit.info/dns-query for querying with DNS over HTTPS
-	  (DoH).
-
--server <rescached-URL>
-
-	Set the location of rescached HTTP server where commands will send.
-	The rescached-URL use HTTP scheme:
-
-		("http" / "https") "://" (domain / ip-address) [":" port]
-
-	Default to "https://127.0.0.1:5380" if its empty.
-
-==  Commands
-
-===  QUERY
-
-query <domain / ip-address> [type] [class]
-
-	Query the domain or IP address with optional type and/or class.
-
-	Unless the option "-ns" is given, the query command will use the
-	nameserver defined in the system resolv.conf file.
-
-	Valid type are either A, NS, CNAME, SOA, MB, MG, MR, NULL,
-	WKS, PTR, HINFO, MINFO, MX, TXT, AAAA, or SRV.
-	Default value is A.
-
-	Valid class are either IN, CS, HS.
-	Default value is IN.
-
-
-===  MANAGING BLOCK.D
-
-block.d disable <name>
-
-	Disable specific hosts on block.d.
-
-block.d enable <name>
-
-	Enable specific hosts on block.d.
-
-block.d update <name>
-
-	Fetch the latest hosts file from remote block.d URL defined by
-	its name.
-	On success, the hosts file will be updated and the server will be
-	restarted.
-
-
-===  MANAGING CACHES
-
-caches
-
-	Fetch and print all caches from rescached server.
-
-caches search <string>
-
-	Search the domain name in rescached caches.
-	This command can also be used to inspect each DNS message on the
-	caches.
-
-caches remove <string>
-
-	Remove the domain name from rescached caches.
-	If the parameter is "all", it will remove all caches.
-
-
-===  MANAGING ENVIRONMENT
-
-env
-
-	Fetch the current server environment and print it as JSON format to
-	stdout.
-
-env update <path-to-file / "-">
-
-	Update the server environment from JSON formatted file.
-	If the argument is "-", the new environment is read from stdin.
-	If the environment is valid, the server will be restarted.
-
-
-===  MANAGING HOSTS.D
-
-hosts.d create <name>
-
-	Create new hosts file inside the hosts.d directory with specific file
-	name.
-
-hosts.d delete <name>
-
-	Delete hosts file inside the hosts.d directory by file name.
-
-hosts.d get <name>
-
-	Get the content of hosts file inside the hosts.d directory by file
-	name.
-
-
-===  MANAGING RECORD IN HOSTS.D
-
-hosts.d rr add <name> <domain> <value>
-
-	Insert a new record and save it to the hosts file identified by
-	"name".
-	If the domain name already exists, the new record will be appended
-	instead of replaced.
-
-hosts.d rr delete <name> <domain>
-
-	Delete record from hosts file "name" by domain name.
-
-
-===  MANAGING ZONE.D
-
-zone.d create <name>
-
-	Create new zone file inside the zone.d directory.
-
-zone.d delete <name>
-
-	Delete zone file inside the zone.d directory.
-
-
-===  MANAGING RECORD IN ZONE.D
-
-zone.d rr add <zone> <domain> <ttl> <type> <class> <value> ...
-
-	Add new record into the zone file.
-	If domain ttl is set to 0, it will default to 604800 (7 days).
-	List of valid type are A, NS, CNAME, PTR, MX, TXT, and AAAA.
-	The value parameter can be more than one, for example, the MX record
-	we pass two parameters:
-
-		<pref> <exchange>
-
-	See the example below for more information.
-
-==  Examples
-
-===  QUERY
-
-Query the IPv4 address for kilabit.info,
-
-	$ resolver query kilabit.info
-
-Query the mail exchange (MX) for domain kilabit.info,
-
-	$ resolver query kilabit.info MX
-
-Query the IPv4 address for kilabit.info using 127.0.0.1 at port 53 as
-name server,
-
-	$ resolver -ns=udp://127.0.0.1:53 query kilabit.info
-
-Query the IPv4 address of domain name "kilabit.info" using DNS over TLS at
-name server 194.233.68.184,
-
-	$ resolver -insecure -ns=https://194.233.68.184 query kilabit.info
-
-Query the IPv4 records of domain name "kilabit.info" using DNS over HTTPS on
-name server kilabit.info,
-
-	$ resolver -insecure -ns=https://kilabit.info/dns-query query kilabit.info
-
-
-===  MANAGING CACHES
-
-Inspect the rescached's caches on server at http://127.0.0.1:5380,
-
-	$ resolver -server=http://127.0.0.1:5380 caches
-
-Search caches that contains "bit" on the domain name,
-
-	$ resolver caches search bit
-
-Remove caches that contains domain name "kilabit.info",
-
-	$ resolver caches remove kilabit.info
-
-Remove all caches in the server,
-
-	$ resolver caches remove all
-
-
-===  MANAGING ENVIRONMENT
-
-Fetch and print current server environment,
-
-	$ resolver env
-
-Update the server environment from JSON file in /tmp/env.json,
-
-	$ resolver env update /tmp/env.json
-
-Update the server environment by reading JSON from standard input,
-
-	$ cat /tmp/env.json | resolver env update -
-
-
-===  MANAGING HOSTS.D
-
-Create new hosts file named "myhosts" inside the hosts.d directory,
-
-	$ resolver hosts.d create myhosts
-	OK
-
-Delete hosts file named "myhosts" inside the hosts.d directory,
-
-	$ resolver hosts.d delete myhosts
-	OK
-
-Get the content of hosts file named "myhosts" inside the hosts.d directory,
-
-	$ resolver hosts.d get myhosts
-	[
-	  {
-	    "Value": "127.0.0.1",
-	    "Name": "localhost",
-	    "Type": 1,
-	    "Class": 1,
-	    "TTL": 604800
-	  },
-	  {
-	    "Value": "::1",
-	    "Name": "localhost",
-	    "Type": 28,
-	    "Class": 1,
-	    "TTL": 604800
-	  }
-	]
-
-
-===  MANAGING RECORD IN HOSTS.D
-
-Add new record "127.0.0.1 my.hosts" to hosts file named "hosts",
-
-	$ resolver hosts.d rr add hosts my.hosts 127.0.0.1
-	{
-	  "Value": "127.0.0.1",
-	  "Name": "my.hosts",
-	  "Type": 1,
-	  "Class": 1,
-	  "TTL": 604800
-	}
-
-Delete record "my.hosts" from hosts file "hosts",
-
-	$ resolver hosts.d rr delete hosts my.hosts
-	{
-	  "Value": "127.0.0.1",
-	  "Name": "my.hosts",
-	  "Type": 1,
-	  "Class": 1,
-	  "TTL": 604800
-	}`)
-}