From 719adb4fdc61e5187efefdfeb25a41d60d40be7f Mon Sep 17 00:00:00 2001 From: Gerald Combs Date: Fri, 11 Aug 2017 12:43:48 -0700 Subject: [PATCH] Convert README to README.md. 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 Petri-Dish: Gerald Combs Tested-by: Petri Dish Buildbot Reviewed-by: Anders Broman --- CMakeLists.txt | 3 +- CPackConfig.txt | 2 +- INSTALL | 2 +- INSTALL.configure | 4 +-- Makefile.am | 1 + README => README.md | 48 ++++++++++++++----------------- configure.ac | 2 +- doc/README.developer | 8 +++--- doc/README.dissector | 8 +++--- packaging/wix/ComponentGroups.wxi | 8 +++--- packaging/wix/Makefile.am | 2 +- 11 files changed, 43 insertions(+), 45 deletions(-) rename README => README.md (87%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 1e6e0b4f7f..9efbe0ee95 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -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() diff --git a/CPackConfig.txt b/CPackConfig.txt index 934a86a4b2..b32d5e0338 100644 --- a/CPackConfig.txt +++ b/CPackConfig.txt @@ -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 aef3f54d53..efbb106e97 100644 --- 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. diff --git a/INSTALL.configure b/INSTALL.configure index ef77c3a46f..8e46e93709 100644 --- a/INSTALL.configure +++ b/INSTALL.configure @@ -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 diff --git a/Makefile.am b/Makefile.am index 9168f8e864..76003b8ff5 100644 --- a/Makefile.am +++ b/Makefile.am @@ -837,6 +837,7 @@ EXTRA_DIST = \ README.hpux \ README.linux \ README.macos \ + README.md \ README.vmware \ README.windows \ abi-descriptor.template \ diff --git a/README b/README.md similarity index 87% rename from README rename to README.md index 2919a88a60..7c283ffe07 100644 --- 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. 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 | tee ". +An easy way of doing this under Unix is to run `telnet | tee `. 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 $ telnet router ..... do your trace, then exit from the router's telnet session. $ exit Script done on ----- +~~~ 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 diff --git a/configure.ac b/configure.ac index f89a8c04df..a8a28ba7e5 100644 --- a/configure.ac +++ b/configure.ac @@ -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 ..." diff --git a/doc/README.developer b/doc/README.developer index aa375db636..766ef56035 100644 --- a/doc/README.developer +++ b/doc/README.developer @@ -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. diff --git a/doc/README.dissector b/doc/README.dissector index 514fe70f7f..737848d8f1 100644 --- a/doc/README.dissector +++ b/doc/README.dissector @@ -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. diff --git a/packaging/wix/ComponentGroups.wxi b/packaging/wix/ComponentGroups.wxi index 3220eb3fee..b74b97bfdc 100644 --- a/packaging/wix/ComponentGroups.wxi +++ b/packaging/wix/ComponentGroups.wxi @@ -1,4 +1,4 @@ - + @@ -38,8 +38,8 @@ - - + + @@ -92,7 +92,7 @@ - + diff --git a/packaging/wix/Makefile.am b/packaging/wix/Makefile.am index ce663a213c..77f59f3e64 100644 --- a/packaging/wix/Makefile.am +++ b/packaging/wix/Makefile.am @@ -10,7 +10,7 @@ EXTRA_DIST = \ InputPaths.wxi \ Plugins.wxi \ Prerequisites.wxi \ - README \ + README.md \ StringOverrides.wxl \ UserInterface.wxi \ Wireshark.wxs \