Docs: Document our diagnostic output options.

Add docs/diagnostic-options.adoc, which is a snippet that documents our
various --log-* options. Include it in the dumpcap, rawshark, and tshark
man pages.

Make the ws_log_print_usage output more consistent.

18 files changed, 56 insertions, 2 deletions

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 4c948bdf1b..d417d9a8c7 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -88,12 +88,15 @@ endif()
 set(BUNDLE_RESOURCE_SHARE_MAN1_FILES ${MAN1_INSTALL_FILES} PARENT_SCOPE)
 set(BUNDLE_RESOURCE_SHARE_MAN4_FILES ${MAN4_INSTALL_FILES} PARENT_SCOPE)
 
+set(MAN_INCLUDES diagnostic-options.adoc)
+
 if(ASCIIDOCTOR_FOUND)
 	ASCIIDOCTOR2ROFFMAN(1 ${MAN1_SOURCE_FILES})
 	ASCIIDOCTOR2ROFFMAN(4 ${MAN4_SOURCE_FILES})
 	ASCIIDOCTOR2HTMLMAN(${MAN1_SOURCE_FILES} ${MAN4_SOURCE_FILES})
 
 	add_custom_target(manpages DEPENDS
+		${MAN_INCLUDES}
 		${MAN1_INSTALL_FILES}
 		${MAN4_INSTALL_FILES}
 	)
@@ -104,6 +107,7 @@ add_custom_target(
 	docs ALL
 	DEPENDS
 		${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT
+		${MAN_INCLUDES}
 		${MAN1_INSTALL_FILES}
 		${MAN4_INSTALL_FILES}
 		${HTML_INSTALL_FILES}
diff --git a/doc/capinfos.adoc b/doc/capinfos.adoc
index 6477d5f418..16ed2e300a 100644
--- a/doc/capinfos.adoc
+++ b/doc/capinfos.adoc
@@ -401,6 +401,8 @@ Displays the average data rate, in bytes/sec
 Displays the average packet size, in bytes
 --
 
+include::diagnostic-options.adoc[]
+
 == EXAMPLES
 
 To see a description of the options use:
diff --git a/doc/captype.adoc b/doc/captype.adoc
index 7b5e4ee492..4fd5eebde3 100644
--- a/doc/captype.adoc
+++ b/doc/captype.adoc
@@ -46,6 +46,8 @@ Print the version number and options and exit.
 Print the full version information and exit.
 --
 
+include::diagnostic-options.adoc[]
+
 == SEE ALSO
 
 xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:mergecap.html[mergecap](1), xref:editcap.html[editcap](1), xref:tshark.html[tshark](1),
diff --git a/doc/dftest.adoc b/doc/dftest.adoc
index be12646dab..a148cbcdfe 100644
--- a/doc/dftest.adoc
+++ b/doc/dftest.adoc
@@ -29,6 +29,8 @@ filter::
 The display filter expression. If needed it has to be quoted.
 --
 
+include::diagnostic-options.adoc[]
+
 == EXAMPLES
 
 Show how the IP protocol is filtered:
diff --git a/doc/diagnostic-options.adoc b/doc/diagnostic-options.adoc
new file mode 100644
index 0000000000..bfca44b304
--- /dev/null
+++ b/doc/diagnostic-options.adoc
@@ -0,0 +1,21 @@
+== DIAGNOSTIC OPTIONS
+
+--log-level <level>:: Set the active log level.
+Supported levels in lowest to highest order are "noisy", "debug", "info", "message", "warning", "critical", and "error".
+Messages at each level and higher will be printed, for example "warning" prints "warning", "critical", and "error" messages and "noisy" prints all messages.
+Levels are case insensitive.
+
+--log-fatal <level>:: Abort the program if any messages are logged at the specified level or higher.
+For example, "warning" aborts on any "warning", "critical", or "error" messages.
+
+// XXX List avaliable domains if no list is provided?
+--log-domains <list>:: Only print messages for the specified log domains, e.g. "GUI,Epan,sshdump".
+List of domains must be comma-separated.
+
+--log-debug <list>:: Force the specified domains to log at the "debug" level.
+List of domains must be comma-separated.
+
+--log-noisy <list>:: Force the specified domains to log at the "debug" level.
+List of domains must be comma-separated.
+
+--log-file <path>:: Write log messages and stderr output to the specified file.
diff --git a/doc/dumpcap.adoc b/doc/dumpcap.adoc
index 39ce6976b2..3defdeb463 100644
--- a/doc/dumpcap.adoc
+++ b/doc/dumpcap.adoc
@@ -509,6 +509,8 @@ set, no time stamp types are listed.
 Change the interface's timestamp method.
 --
 
+include::diagnostic-options.adoc[]
+
 == CAPTURE FILTER SYNTAX
 
 See the manual page of xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or, if that doesn't exist, xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8),
diff --git a/doc/editcap.adoc b/doc/editcap.adoc
index 3a6a8df693..b644e44669 100644
--- a/doc/editcap.adoc
+++ b/doc/editcap.adoc
@@ -460,6 +460,8 @@ file. Does not discard comments added by *--capture-comment* in the same
 command line.
 --
 
+include::diagnostic-options.adoc[]
+
 == EXAMPLES
 
 To see more detailed description of the options use:
diff --git a/doc/mergecap.adoc b/doc/mergecap.adoc
index 01e39f2e2e..044e598dee 100644
--- a/doc/mergecap.adoc
+++ b/doc/mergecap.adoc
@@ -150,6 +150,8 @@ Sets the output filename. If the name is '*-*', stdout will be used.
 This setting is mandatory.
 --
 
+include::diagnostic-options.adoc[]
+
 == EXAMPLES
 
 To merge two capture files together into a third capture file, in which
diff --git a/doc/randpkt.adoc b/doc/randpkt.adoc
index aa9faa8222..280c0b2357 100644
--- a/doc/randpkt.adoc
+++ b/doc/randpkt.adoc
@@ -92,6 +92,8 @@ Defines the type of packet to generate:
         usb-linux       Universal Serial Bus with Linux specific header
 --
 
+include::diagnostic-options.adoc[]
+
 == EXAMPLES
 
 To see a description of the randpkt options use:
diff --git a/doc/rawshark.adoc b/doc/rawshark.adoc
index ccc17a6e0a..e4d0644923 100644
--- a/doc/rawshark.adoc
+++ b/doc/rawshark.adoc
@@ -307,6 +307,8 @@ The default format is relative.
 Print the version and exit.
 --
 
+include::diagnostic-options.adoc[]
+
 == READ FILTER SYNTAX
 
 For a complete table of protocol and protocol fields that are filterable
diff --git a/doc/reordercap.adoc b/doc/reordercap.adoc
index 57b0781575..623b26e995 100644
--- a/doc/reordercap.adoc
+++ b/doc/reordercap.adoc
@@ -54,6 +54,8 @@ file if it finds that the input file is already in order.
 Print the version and exit.
 --
 
+include::diagnostic-options.adoc[]
+
 == SEE ALSO
 
 xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:editcap.html[editcap](1), xref:mergecap.html[mergecap](1),
diff --git a/doc/text2pcap.adoc b/doc/text2pcap.adoc
index f8189fb8b3..97c380649f 100644
--- a/doc/text2pcap.adoc
+++ b/doc/text2pcap.adoc
@@ -315,6 +315,8 @@ Example: __-6 fe80::202:b3ff:fe1e:8329,2001:0db8:85a3::8a2e:0370:7334__ to
 use fe80::202:b3ff:fe1e:8329 and 2001:0db8:85a3::8a2e:0370:7334 for all IP packets.
 --
 
+include::diagnostic-options.adoc[]
+
 == SEE ALSO
 
 od(1), xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:mergecap.html[mergecap](1),
diff --git a/doc/tshark.adoc b/doc/tshark.adoc
index 29680f3361..e598c344a8 100644
--- a/doc/tshark.adoc
+++ b/doc/tshark.adoc
@@ -2392,6 +2392,8 @@ Enable dissection of heuristic protocol.
 Disable dissection of heuristic protocol.
 --
 
+include::diagnostic-options.adoc[]
+
 == CAPTURE FILTER SYNTAX
 
 See the manual page of xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or, if that doesn't exist, xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8),
diff --git a/doc/wireshark.adoc b/doc/wireshark.adoc
index 55153420ee..4b8cc6e952 100644
--- a/doc/wireshark.adoc
+++ b/doc/wireshark.adoc
@@ -1089,6 +1089,8 @@ Show IEEE 802.11 network and station statistics.
 Show WSP packet counters.
 --
 
+include::diagnostic-options.adoc[]
+
 == INTERFACE
 
 === MENU ITEMS
diff --git a/dumpcap.c b/dumpcap.c
index 3492283180..add3a89790 100644
--- a/dumpcap.c
+++ b/dumpcap.c
@@ -437,6 +437,7 @@ print_usage(FILE *output)
     fprintf(output, "\n");
 
     ws_log_print_usage(output);
+    fprintf(output, "\n");
 
     fprintf(output, "Miscellaneous:\n");
     fprintf(output, "  -N <packet_limit>        maximum number of packets buffered within dumpcap\n");
diff --git a/rawshark.c b/rawshark.c
index 8ae7addc90..50e328e907 100644
--- a/rawshark.c
+++ b/rawshark.c
@@ -189,8 +189,10 @@ print_usage(FILE *output)
     fprintf(output, "  -S                       format string for fields\n");
     fprintf(output, "                           (%%D - name, %%S - stringval, %%N numval)\n");
     fprintf(output, "  -t ad|a|r|d|dd|e         output format of time stamps (def: r: rel. to first)\n");
+    fprintf(output, "\n");
 
     ws_log_print_usage(output);
+    fprintf(output, "\n");
 
     fprintf(output, "\n");
     fprintf(output, "Miscellaneous:\n");
diff --git a/tfshark.c b/tfshark.c
index 4c245d9dc7..b8803e098a 100644
--- a/tfshark.c
+++ b/tfshark.c
@@ -201,10 +201,11 @@ print_usage(FILE *output)
   fprintf(output, "  -Q                       only log true errors to stderr (quieter than -q)\n");
   fprintf(output, "  -X <key>:<value>         eXtension options, see the man page for details\n");
   fprintf(output, "  -z <statistics>          various statistics, see the man page for details\n");
+  fprintf(output, "\n");
 
   ws_log_print_usage(output);
-
   fprintf(output, "\n");
+
   fprintf(output, "Miscellaneous:\n");
   fprintf(output, "  -h                       display this help and exit\n");
   fprintf(output, "  -v                       display version info and exit\n");
diff --git a/tshark.c b/tshark.c
index 92bcd4ecf3..c8f5191d38 100644
--- a/tshark.c
+++ b/tshark.c
@@ -472,10 +472,11 @@ print_usage(FILE *output)
   fprintf(output, "                           values\n");
   fprintf(output, "  --elastic-mapping-filter <protocols> If -G elastic-mapping is specified, put only the\n");
   fprintf(output, "                           specified protocols within the mapping file\n");
+  fprintf(output, "\n");
 
   ws_log_print_usage(output);
-
   fprintf(output, "\n");
+
   fprintf(output, "Miscellaneous:\n");
   fprintf(output, "  -h, --help               display this help and exit\n");
   fprintf(output, "  -v, --version            display version info and exit\n");