Convert README to README.md.
authorGerald Combs <gerald@wireshark.org>
Fri, 11 Aug 2017 19:43:48 +0000 (12:43 -0700)
committerAnders Broman <a.broman58@gmail.com>
Tue, 15 Aug 2017 14:48:29 +0000 (14:48 +0000)
Convert the contents of the top-level README to Markdown and give it a
.md extension. Most of our documentation is plain text or AsciiDoc, but
the top-level README file in a Git repository is special in that many
online browsers will show the README contents along with the directory
listing and those browsers tend to favor Markdown. This is true of
GitHub (which we're currently mirroring to), Gerrit via its Gitiles
plugin (which we're not yet using but likely will), and other places.

Add "foreign" to AM_INIT_AUTOMAKE. There is probably a joke to be
made here about the FSF and border walls.

Change-Id: I87c306d74864e1f0a432225b160a1b4483ee946c
Reviewed-on: https://code.wireshark.org/review/23049
Reviewed-by: Gerald Combs <gerald@wireshark.org>
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot <buildbot-no-reply@wireshark.org>
Reviewed-by: Anders Broman <a.broman58@gmail.com>
CMakeLists.txt
CPackConfig.txt
INSTALL
INSTALL.configure
Makefile.am
README.md [moved from README with 87% similarity]
configure.ac
doc/README.developer
doc/README.dissector
packaging/wix/ComponentGroups.wxi
packaging/wix/Makefile.am

index 1e6e0b4f7fbf83747fa85e8c090008187ce168c9..9efbe0ee952dadf54c3e17330c1195d882cd50da 100644 (file)
@@ -1678,7 +1678,8 @@ if (BUILD_xxx2deb)
 endif()
 
 if(WIN32)
-       set(TEXTIFY_FILES COPYING NEWS README README.windows)
+       set(INSTALL_FILES README.md ${INSTALL_FILES})
+       set(TEXTIFY_FILES COPYING NEWS README.windows)
        foreach(_text_file ${TEXTIFY_FILES})
                set(INSTALL_FILES ${CMAKE_BINARY_DIR}/${_text_file}.txt ${INSTALL_FILES})
        endforeach()
index 934a86a4b2a6de682e23286df541cd069cb8e150..b32d5e0338de34cc5c8e982c9f588d91c72bb6a4 100644 (file)
@@ -50,7 +50,7 @@ add_custom_target(dist
 set(CPACK_PACKAGE_DESCRIPTION "A set of command line and gui tools to capture and decode traffic")
 set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "Packet capturing and decoding")
 set(CPACK_PACKAGE_VENDOR "Wireshark developers")
-set(CPACK_PACKAGE_DESCRIPTION_FILE "${CMAKE_CURRENT_SOURCE_DIR}/README")
+set(CPACK_PACKAGE_DESCRIPTION_FILE "${CMAKE_CURRENT_SOURCE_DIR}/README.md")
 set(CPACK_PACKAGE_VERSION_MAJOR "${PROJECT_MAJOR_VERSION}")
 set(CPACK_PACKAGE_VERSION_MINOR "${PROJECT_MINOR_VERSION}")
 set(CPACK_PACKAGE_VERSION_PATCH "${PROJECT_PATCH_VERSION}${PROJECT_VERSION_EXTENSION}")
diff --git a/INSTALL b/INSTALL
index aef3f54d5322996f690eaa0f293cfab1b628bccf..efbb106e9704e9107c2da960a243686626e1418a 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -52,7 +52,7 @@ README.windows for those instructions.
    install a "development" package; for example, there's
    apparently a "libpcap0" Debian package, but it just includes a
    shared library, a copyright notice, changelog files, and a
-   README file - you also need to install a "libpcap-dev" package
+   README.md file - you also need to install a "libpcap-dev" package
    to get header files, a non-shared library, and the man page.
    Similarly, Red Hat users will need to install a "libpcap-devel"
    .rpm to go along with the "libpcap" .rpm.
index ef77c3a46f07e8ee8224351006a7b91ac125bfd6..8e46e93709f3751060c100ae3ce97764a92e821f 100644 (file)
@@ -15,7 +15,7 @@ reconfiguring, and a file `config.log' containing compiler output
 
    If you need to do unusual things to compile the package, please try
 to figure out how `configure' could check whether to do them, and mail
-diffs or instructions to the address given in the `README' so they can
+diffs or instructions to the address given in the `README.md' so they can
 be considered for the next release.  If at some point `config.cache'
 contains results you don't want to keep, you may remove or edit it.
 
@@ -111,7 +111,7 @@ Optional Features
 `configure', where FEATURE indicates an optional part of the package.
 They may also pay attention to `--with-PACKAGE' options, where PACKAGE
 is something like `gnu-as' or `x' (for the X Window System).  The
-`README' should mention any `--enable-' and `--with-' options that the
+`README.md' should mention any `--enable-' and `--with-' options that the
 package recognizes.
 
    For packages that use the X Window System, `configure' can usually
index 9168f8e8648a55e24ab373ed3d4a751ced278511..76003b8ff5a9371f618f93af94731908734f7df8 100644 (file)
@@ -837,6 +837,7 @@ EXTRA_DIST = \
        README.hpux             \
        README.linux            \
        README.macos            \
+       README.md               \
        README.vmware           \
        README.windows          \
        abi-descriptor.template \
similarity index 87%
rename from README
rename to README.md
index 2919a88a607e88f73a85e87e45c54cd5ec5f8bc7..7c283ffe07d68bac51600c4ecce098aa92fa6296 100644 (file)
--- a/README
+++ b/README.md
@@ -13,13 +13,9 @@ files and write the packets from that capture file, possibly in a
 different capture file format, and with some packets possibly removed
 from the capture.
 
-The official home of Wireshark is
+The official home of Wireshark is https://www.wireshark.org.
 
-    https://www.wireshark.org
-
-The latest distribution can be found in the subdirectory
-
-    https://www.wireshark.org/download
+The latest distribution can be found in the subdirectory https://www.wireshark.org/download
 
 
 Installation
@@ -57,7 +53,7 @@ Both Perl and Python are needed, the former for building the man pages.
 If you decide to modify the yacc grammar or lex scanner, then
 you need "flex" - it cannot be built with vanilla "lex" -
 and either "bison" or the Berkeley "yacc". Your flex
-version must be 2.5.1 or greater. Check this with 'flex -V'.
+version must be 2.5.1 or greater. Check this with `flex -V`.
 
 You must therefore install Perl, Python, GNU "make", "flex", and either "bison"
 or Berkeley "yacc" on systems that lack them.
@@ -65,7 +61,7 @@ or Berkeley "yacc" on systems that lack them.
 Full installation instructions can be found in the INSTALL file and in the
 Developer's Guide at https://www.wireshark.org/docs/wsdg_html_chunked/
 
-See also the appropriate README.<OS> files for OS-specific installation
+See also the appropriate README._OS_ files for OS-specific installation
 instructions.
 
 Usage
@@ -73,7 +69,7 @@ Usage
 
 In order to capture packets from the network, you need to make the
 dumpcap program set-UID to root, or you need to have access to the
-appropriate entry under /dev if your system is so inclined (BSD-derived
+appropriate entry under `/dev` if your system is so inclined (BSD-derived
 systems, and systems such as Solaris and HP-UX that support DLPI,
 typically fall into this category).  Although it might be tempting to
 make the Wireshark and TShark executables setuid root, or to run them as
@@ -100,12 +96,12 @@ automatically, if you have the zlib library available when compiling
 Wireshark. Wireshark needs a modern version of zlib to be able to use
 zlib to read gzipped files; version 1.1.3 is known to work.  Versions
 prior to 1.0.9 are missing some functions that Wireshark needs and won't
-work.  "./configure" should detect if you have the proper zlib version
+work.  `./configure` should detect if you have the proper zlib version
 available and, if you don't, should disable zlib support. You can always
-use "./configure --disable-zlib" to explicitly disable zlib support.
+use `./configure --disable-zlib` to explicitly disable zlib support.
 
 Although Wireshark can read AIX iptrace files, the documentation on
-AIX's iptrace packet-trace command is sparse.  The 'iptrace' command
+AIX's iptrace packet-trace command is sparse.  The `iptrace` command
 starts a daemon which you must kill in order to stop the trace. Through
 experimentation it appears that sending a HUP signal to that iptrace
 daemon causes a graceful shutdown and a complete packet is written
@@ -117,35 +113,35 @@ file if it's small and contains non-sensitive data.
 
 Support for Lucent/Ascend products is limited to the debug trace output
 generated by the MAX and Pipline series of products.  Wireshark can read
-the output of the "wandsession" "wandisplay", "wannext", and "wdd"
+the output of the `wandsession` `wandisplay`, `wannext`, and `wdd`
 commands.
 
 Wireshark can also read dump trace output from the Toshiba "Compact Router"
 line of ISDN routers (TR-600 and TR-650). You can telnet to the router
-and start a dump session with "snoop dump".
+and start a dump session with `snoop dump`.
 
 CoSine L2 debug output can also be read by Wireshark. To get the L2
 debug output, get in the diags mode first and then use
-"create-pkt-log-profile" and "apply-pkt-log-profile" commands under
+`create-pkt-log-profile` and `apply-pkt-lozg-profile` commands under
 layer-2 category. For more detail how to use these commands, you
-should examine the help command by "layer-2 create ?" or "layer-2 apply ?".
+should examine the help command by `layer-2 create ?` or `layer-2 apply ?`.
 
 To use the Lucent/Ascend, Toshiba and CoSine traces with Wireshark, you must
 capture the trace output to a file on disk.  The trace is happening inside
 the router and the router has no way of saving the trace to a file for you.
-An easy way of doing this under Unix is to run "telnet <ascend> | tee <outfile>".
+An easy way of doing this under Unix is to run `telnet <ascend> | tee <outfile>`.
 Or, if your system has the "script" command installed, you can save
 a shell session, including telnet to a file. For example, to a file named
 tracefile.out:
 
-----
+~~~
 $ script tracefile.out
 Script started on <date/time>
 $ telnet router
 ..... do your trace, then exit from the router's telnet session.
 $ exit
 Script done on <date/time>
-----
+~~~
 
 
 Name Resolution
@@ -155,9 +151,9 @@ Wireshark will attempt to use reverse name resolution capabilities
 when decoding IPv4 and IPv6 packets.
 
 If you want to turn off name resolution while using Wireshark, start
-Wireshark with the "-n" option to turn off all name resolution (including
+Wireshark with the `-n` option to turn off all name resolution (including
 resolution of MAC addresses and TCP/UDP/SMTP port numbers to names), or
-with the "-N mt" option to turn off name resolution for all
+with the `-N mt` option to turn off name resolution for all
 network-layer addresses (IPv4, IPv6, IPX).
 
 You can make that the default setting by opening the Preferences dialog
@@ -175,7 +171,7 @@ files and using the information in those files to display OIDs and
 variable binding values in a friendlier fashion.  The configure script
 will automatically determine whether you have the libsmi library on
 your system.  If you have the libsmi library but _do not_ want to have
-Wireshark use it, you can run configure with the "--without-libsmi"
+Wireshark use it, you can run configure with the `--without-libsmi`
 option.
 
 How to Report a Bug
@@ -186,8 +182,8 @@ encounter a bug while using it. Please report bugs at https://bugs.wireshark.org
 Be sure you enter into the bug:
 
 1. The complete build information from the "About Wireshark"
-   item in the Help menu or the output of "wireshark -v" for
-   Wireshark bugs and the output of "tshark -v" for TShark bugs;
+   item in the Help menu or the output of `wireshark -v` for
+   Wireshark bugs and the output of `tshark -v` for TShark bugs;
 
 2. If the bug happened on Linux, the Linux distribution you were
    using, and the version of that distribution;
@@ -209,13 +205,13 @@ trace can be obtained by using your debugger ('gdb' in this example),
 the wireshark binary, and the resulting core file.  Here's an example of
 how to use the gdb command 'backtrace' to do so.
 
-----
+~~~
 $ gdb wireshark core
 (gdb) backtrace
 ..... prints the stack trace
 (gdb) quit
 $
-----
+~~~
 
 The core dump file may be named "wireshark.core" rather than "core" on
 some platforms (e.g., BSD systems).  If you got a core dump with
index f89a8c04df636a3ec72465876ed102e329e73c58..a8a28ba7e528368de4661a9518de462f6ccc0c0a 100644 (file)
@@ -46,7 +46,7 @@ dnl AC_CANONICAL_BUILD
 dnl AC_CANONICAL_HOST
 AC_CANONICAL_TARGET
 
-AM_INIT_AUTOMAKE([1.11 tar-ustar dist-xz no-dist-gzip subdir-objects])
+AM_INIT_AUTOMAKE([1.11 tar-ustar dist-xz no-dist-gzip subdir-objects foreign])
 
 # Enable silent builds by default. Verbose builds can be enabled with "./configure
 # --enable-silent-rules ..." or "make V=1 ..."
index aa375db636ee6d28c34031460cc7b5cdb79519b7..766ef560353da49943eaf18fdc0721337127b96f 100644 (file)
@@ -17,10 +17,10 @@ Before starting to develop a new dissector, a "running" Wireshark build
 environment is required - there's no such thing as a standalone "dissector
 build toolkit".
 
-How to setup such an environment is platform dependent; detailed information
-about these steps can be found in the "Developer's Guide" (available from:
-https://www.wireshark.org) and in the INSTALL and README files of the sources
-root dir.
+How to setup such an environment is platform dependent; detailed
+information about these steps can be found in the "Developer's Guide"
+(available from: https://www.wireshark.org) and in the INSTALL and
+README.md files of the sources root dir.
 
 0.1. General README files.
 
index 514fe70f7f5f63b4058b09595878c985fa85b91c..737848d8f1eecc5a36ecbba0137c865bab5e9928 100644 (file)
@@ -16,10 +16,10 @@ Before starting to develop a new dissector, a "running" Wireshark build
 environment is required - there's no such thing as a standalone "dissector
 build toolkit".
 
-How to setup such an environment is platform dependent; detailed information
-about these steps can be found in the "Developer's Guide" (available from:
-https://www.wireshark.org) and in the INSTALL and README files of the sources
-root dir.
+How to setup such an environment is platform dependent; detailed
+information about these steps can be found in the "Developer's Guide"
+(available from: https://www.wireshark.org) and in the INSTALL and
+README.md files of the sources root dir.
 
 0.1. Dissector related README files.
 
index 3220eb3fee5e599d8c98ee7706a850f60f66f44d..b74b97bfdca2d171283d3b4663993ed51b393aaf 100644 (file)
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <Include>
 
   <!-- Wireshark -->
@@ -38,8 +38,8 @@
         <Component Id="cmpNEWS_txt" Guid="*">
           <File Id="filNEWS_txt" KeyPath="yes" Source="$(var.Staging.Dir)\NEWS.txt" />
         </Component>
-        <Component Id="cmpREADME_txt" Guid="*">
-          <File Id="filREADME_txt" KeyPath="yes" Source="$(var.Staging.Dir)\README.txt" />
+        <Component Id="cmpREADME_md" Guid="*">
+          <File Id="filREADME_md" KeyPath="yes" Source="$(var.Staging.Dir)\README.md" />
         </Component>
         <Component Id="cmpREADME_windows_txt" Guid="*">
           <File Id="filREADME_windows_txt" KeyPath="yes" Source="$(var.Staging.Dir)\README.windows.txt" />
@@ -92,7 +92,7 @@
         <ComponentRef Id="cmpLibwsutil_dll" />
         <ComponentRef Id="cmpCOPYING_txt" />
         <ComponentRef Id="cmpNEWS_txt" />
-        <ComponentRef Id="cmpREADME_txt" />
+        <ComponentRef Id="cmpREADME_md" />
         <ComponentRef Id="cmpREADME_windows_txt" />
         <ComponentRef Id="cmpAUTHORS_SHORT" />
         <ComponentRef Id="cmpManuf" />
index ce663a213cb030c72ddf5e4360471611b9d29166..77f59f3e641a450fd061cffc3118dd4b2a58fe11 100644 (file)
@@ -10,7 +10,7 @@ EXTRA_DIST = \
        InputPaths.wxi          \
        Plugins.wxi             \
        Prerequisites.wxi       \
-       README                  \
+       README.md               \
        StringOverrides.wxl     \
        UserInterface.wxi       \
        Wireshark.wxs           \