Remind wiretap developers where else they need to register their file types.

Chances are they want to include the file extension in wiretap's list of
file extensions (for the File->Open dialog) as well as the various files
needed for integration with the various desktop environments that
Wireshark supports.

(I should have put this advice there years ago when creating the
freedesktop.org mime-package file.)

Add a comment to the mime-package file explaining its purpose, giving
a link to the specification, and talking about MIME types and the registration
thereof.

Change-Id: I60540bf88062b7a90653888534405f6aef4f657c
Reviewed-on: https://code.wireshark.org/review/15011
Reviewed-by: Jeff Morriss <jeff.morriss.ws@gmail.com>

wireshark-mime-package.xml

@@ -1,5 +1,32 @@
 <?xml version="1.0" encoding="UTF-8"?>
 
+<!--
+    This file allows freedesktop.org-compliant desktops (such as GNOME and
+    KDE) to know which files should be opened by what program (and what icon
+    to show for the file in a file browser).
+
+    Both magic and file name glob patterns are supported; glob patterns are
+    preferred since they don't require require opening and reading part of
+    the file to determine its type.
+
+    The specification for this file can be found here:
+    https://standards.freedesktop.org/shared-mime-info-spec/latest/
+
+
+    Note that ideally the MIME types listed here should be IANA-registered:
+
+    https://www.iana.org/assignments/media-types/media-types.xhtml
+
+    If your file type is not registered then using one of the
+    (not-really-a-good-idea and deprecated) x- media types is the only option
+    if you want files to be associated with Wireshark in
+    freedesktop.org-compliant file browsers.
+
+
+    NOTE: if you do add a MIME type here, don't forget to add it to the list
+    of MIME types handled by Wireshark in wireshark.desktop.
+-->
+
 <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
   <mime-type type="application/vnd.tcpdump.pcap">
     <comment>Packet Capture (PCAP)</comment>

wiretap/file_access.c

@@ -307,6 +307,17 @@ wtap_get_all_file_extensions_list(void)
  * type to interpret it as, if the file name has no extension, the
  * extension isn't sufficient to determine the appropriate file type,
  * or the extension is wrong.
+ *
+ * NOTE: when adding file formats to this list you may also want to add them
+ * to the following files so that the various desktop environments will
+ * know that Wireshark can open the file:
+ *	1) wireshark-mime-package.xml (for freedesktop.org environments)
+ *	2) packaging/macosx/Info.plist.in (for OS X)
+ *	3) packaging/nsis/AdditionalTasksPage.ini and packaging/nsis/common.nsh
+ *	   (for Windows)
+ *
+ * If your file format has an expected extension (e.g., ".pcap") then you
+ * should probably also add it to file_type_extensions_base[] (in this file).
  */
 static struct open_info open_info_base[] = {
 	{ "Wireshark/tcpdump/... - pcap",           OPEN_INFO_MAGIC,     libpcap_open,             "pcap",     NULL, NULL },