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.

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}

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:

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),

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:

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.

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),

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:

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

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:

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

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),

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),

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),

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

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");

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");

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");

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");