Start converting the User's Guide to AsciiDoc.

Convert the preface and introduction. Update various makefiles.

Change-Id: Id998cabadb6de458f04b7a43bdba4f98e4edb052
Reviewed-on: https://code.wireshark.org/review/3139
Reviewed-by: Gerald Combs <gerald@wireshark.org>
Tested-by: Gerald Combs <gerald@wireshark.org>

1 files changed, 484 insertions, 0 deletions

diff --git a/docbook/wsug_src/WSUG_chapter_introduction.asciidoc b/docbook/wsug_src/WSUG_chapter_introduction.asciidoc
new file mode 100644
index 0000000000..b915dafd3c
--- /dev/null
+++ b/docbook/wsug_src/WSUG_chapter_introduction.asciidoc
@@ -0,0 +1,484 @@
+++++++++++++++++++++++++++++++++++++++
+<!-- WSUG Chapter Introduction -->
+++++++++++++++++++++++++++++++++++++++
+    
+[[ChapterIntroduction]]
+
+== Introduction
+
+[[ChIntroWhatIs]]
+
+=== What is Wireshark?
+
+Wireshark is a network packet analyzer. A network packet analyzer will try to
+capture network packets and tries to display that packet data as detailed as
+possible. 
+
+You could think of a network packet analyzer as a measuring device used to
+examine what's going on inside a network cable, just like a voltmeter is used by
+an electrician to examine what's going on inside an electric cable (but at a
+higher level, of course). 
+
+In the past, such tools were either very expensive, proprietary, or both.
+However, with the advent of Wireshark, all that has changed. 
+
+Wireshark is perhaps one of the best open source packet analyzers available
+today. 
+
+[[ChIntroPurposes]]
+
+==== Some intended purposes
+
+Here are some examples people use Wireshark for:
+ 
+*  Network administrators use it to _troubleshoot network problems_ 
+
+*  Network security engineers use it to _examine security problems_ 
+
+*  Developers use it to _debug protocol implementations_ 
+
+*  People use it to _learn network protocol_ internals 
+
+Beside these examples Wireshark can be helpful in many other situations too. 
+
+[[ChIntroFeatures]]
+
+==== Features
+
+The following are some of the many features Wireshark provides:
+ 
+* Available for _UNIX_ and _Windows_.
+    
+* _Capture_ live packet data from a network interface. 
+
+* _Open_ files containing packet data captured with tcpdump/WinDump, Wireshark, and a number of other packet capture programs. 
+    
+* _Import_ packets from text files containing hex dumps of packet data. 
+    
+* Display packets with _very detailed protocol information_. 
+    
+* _Save_ packet data captured. 
+
+* _Export_ some or all packets in a number of capture file formats. 
+    
+* _Filter packets_ on many criteria.
+    
+* _Search_ for packets on many criteria.
+    
+* _Colorize_ packet display based on filters.
+    
+* Create various _statistics_.
+    
+*  ...and _a lot more!_
+
+However, to really appreciate its power you have to start using it. 
+
+<<ChIntroFig1>> shows Wireshark having captured some packets and waiting for you
+to examine them.
+
+[[ChIntroFig1]]
+.Wireshark captures packets and lets you examine their contents. 
+image::wsug_graphics/ws-main.png[]
+
+==== Live capture from many different network media
+
+Wireshark can capture traffic from many different network media types - and
+despite its name - including wireless LAN as well. Which media types are
+supported, depends on many things like the operating system you are using. An
+overview of the supported media types can be found at
+wireshark-wiki-site:[]CaptureSetup/NetworkMedia[].
+
+==== Import files from many other capture programs
+
+Wireshark can open packets captured from a large number of other capture
+programs. For a list of input formats see <<ChIOInputFormatsSection>>. 
+
+==== Export files for many other capture programs
+
+Wireshark can save packets captured in a large number of formats of other
+capture programs. For a list of output formats see <<ChIOOutputFormatsSection>>. 
+
+==== Many protocol decoders
+
+There are protocol decoders (or dissectors, as they are known in Wireshark) for
+a great many protocols: see <<AppProtocols>>. 
+
+==== Open Source Software
+
+Wireshark is an open source software project, and is released under the
+gpl-url:[][GNU General Public License] (GPL). You can freely use
+Wireshark on any number of computers you like, without worrying about license
+keys or fees or such. In addition, all source code is freely available under the
+GPL. Because of that, it is very easy for people to add new protocols to
+Wireshark, either as plugins, or built into the source, and they often do! 
+
+[[ChIntroNoFeatures]]
+
+==== What Wireshark is not
+
+Here are some things Wireshark does not provide: 
+
+* Wireshark isn't an intrusion detection system. It will not warn you when
+  someone does strange things on your network that he/she isn't allowed to do.
+  However, if strange things happen, Wireshark might help you figure out what is
+  really going on. 
+
+* Wireshark will not manipulate things on the network, it will only "measure"
+  things from it. Wireshark doesn't send packets on the network or do other
+  active things (except for name resolutions, but even that can be disabled). 
+
+[[ChIntroPlatforms]]
+
+=== System Requirements
+
+The amount of resources Wireshark needs depends on your environment and on the
+size of the capture file you are analyzing. The values below should be fine for
+small to medium-sized capture files no mor than a few hundred MB. Larger capture
+files will require more memory and disk space. 
+
+[NOTE]
+.Busy networks mean large captures
+====
+Working with a busy network can easily produce huge capture files. Capturing on
+a gigabit or even 100 megabit network can produce hundreds of megabytes of
+capture data in a short time. A fast processor, lots of memory and disk
+space is always a good idea.
+====
+
+If Wireshark runs out of memory it will crash. See
+wireshark-wiki-site:[]KnownBugs/OutOfMemory[] for details and workarounds.
+
+Although Wireshark captures packets using a separate process the main interface
+is single-threaded and won't benefit much from multi-core systems.
+
+==== Microsoft Windows
+ 
+* The current version of Wireshark should support any version of Windows that is
+  still within its http://windows.microsoft.com/en-us/windows/lifecycle[extended
+  support lifetime]. At the time of writing this includes Windows 8, 7, Vista,
+  Server 2012, Server 2008 R2, Server 2008, and Server 2003.
+
+* Any modern 32-bit x86 or 64-bit AMD64/x86-64 processor. 
+
+* 200 MB available RAM. Larger capture files require more RAM. 
+
+* 75 MB available disk space. Capture files require additional disk space. 
+
+* 1024&#xd7;768 (1280&#xd7;1024 or higher recommended) resolution with at
+  least 16 bit color. 8 bit color should work but user experience will be
+  degraded.
+
+* A supported network card for capturing
+
+  - Ethernet. Any card supported by Windows should work. See the wiki pages on
+    wireshark-wiki-site:[]CaptureSetup/Ethernet[Ethernet capture] and
+    wireshark-wiki-site:[]CaptureSetup/Offloading[offloading] for issues that
+    may affect your environment. 
+  
+  - 802.11. See the wireshark-wiki-site:[]CaptureSetup/WLAN#Windows[Wireshark
+    wiki page]. Capturing raw 802.11 information may be difficult without
+    special equipment. 
+  
+  - Other media. See wireshark-wiki-site:[]CaptureSetup/NetworkMedia[] 
+
+Older versions of Windows which are outside Microsoft's extended lifecycle
+support window are no longer supported. It is often difficult or impossible to
+support these systems due to circumstances beyond our control, such as third
+party libraries on which we depend or due to necessary features that are only
+present in newer versions of Windows (such as hardened security or memory
+management).
+
+Wireshark 1.10 was the last release branch to officially support Windows XP.
+Wireshark 1.2 was the last branch to support Windows 2000. See the
+wireshark-wiki-site:[]Development/LifeCycle[Wireshark release lifecycle] page
+for more details.
+
+==== UNIX / Linux
+
+Wireshark currently runs on most UNIX platforms. The system requirements should
+be comparable to the Windows values listed above. 
+
+Binary packages are available for most Unices and Linux distributions including
+the following platforms: 
+
+* Apple Mac OS X
+
+* Debian GNU/Linux
+
+* FreeBSD
+
+* Gentoo Linux
+
+* HP-UX
+
+* Mandriva Linux
+
+* NetBSD
+
+* OpenPKG
+
+* Red Hat Enterprise/Fedora Linux
+
+* Sun Solaris/i386
+
+* Sun Solaris/SPARC
+
+* Canonical Ubuntu
+ 
+If a binary package is not available for your platform you can download the
+source and try to build it. Please report your experiences to
+mailto:wireshark-dev-list-email:[][wireshark-dev-list-email:[]]. 
+
+[[ChIntroDownload]]
+
+=== Where to get Wireshark
+
+You can get the latest copy of the program from the Wireshark website at
+wireshark-download-page:[][wireshark-download-page:[]]. The download page should
+automatically highlight the appropriate download for your platform and direct you
+to the nearest mirror.
+
+A new Wireshark version typically becomes available each month or two. 
+
+If you want to be notified about new Wireshark releases you should subscribe to
+the wireshark-announce mailing list. You will find more details in
+<<ChIntroMailingLists>>. 
+
+[[ChIntroHistory]]
+
+
+=== A brief history of Wireshark
+
+In late 1997 Gerald Combs needed a tool for tracking down network problems
+and wanted to learn more about networking so he started writing Ethereal (the
+original name of the Wireshark project) as a way to solve both problems.
+
+Ethereal was initially released after several pauses in development in July
+1998 as version 0.2.0. Within days patches, bug reports, and words of
+encouragement started arriving and Ethereal was on its way to success.
+
+Not long after that Gilbert Ramirez saw its potential and contributed a
+low-level dissector to it.
+
+In October, 1998 Guy Harris was looking for something better than tcpview so he
+started applying patches and contributing dissectors to Ethereal.
+
+In late 1998 Richard Sharpe, who was giving TCP/IP courses, saw its potential
+on such courses and started looking at it to see if it supported the protocols
+he needed. While it didn't at that point new protocols could be easily added.
+So he started contributing dissectors and contributing patches.
+
+The list of people who have contributed to the project has become very long
+since then, and almost all of them started with a protocol that they needed that
+Wireshark or did not already handle. So they copied an existing dissector and
+contributed the code back to the team.
+
+In 2006 the project moved house and re-emerged under a new name: Wireshark.
+
+In 2008, after ten years of development, Wireshark finally arrived at version
+1.0. This release was the first deemed complete, with the minimum features
+implemented. Its release coincided with the first Wireshark Developer and User
+Conference, called Sharkfest. 
+
+[[ChIntroMaintenance]]
+
+
+=== Development and maintenance of Wireshark 
+
+Wireshark was initially developed by Gerald Combs. Ongoing development and
+maintenance of Wireshark is handled by the Wireshark team, a loose group of
+individuals who fix bugs and provide new functionality.
+
+There have also been a large number of people who have contributed protocol
+dissectors to Wireshark, and it is expected that this will continue. You can
+find a list of the people who have contributed code to Wireshark by checking the
+about dialog box of Wireshark, or at the wireshark-authors-url:[][authors] page
+on the Wireshark web site.
+
+Wireshark is an open source software project, and is released under the
+gpl-url:[][GNU General Public License] (GPL) version 2. All source code is
+freely available under the GPL. You are welcome to modify Wireshark to suit your
+own needs, and it would be appreciated if you contribute your improvements back
+to the Wireshark team.
+
+You gain three benefits by contributing your improvements back to the community: 
+
+. Other people who find your contributions useful will appreciate them, and you
+  will know that you have helped people in the same way that the developers of
+  Wireshark have helped people.
+
+. The developers of Wireshark might improve your changes even more, as there's
+  always room for improvement. Or they may implement some advanced things on top
+  of your code, which can be useful for yourself too.
+
+. The maintainers and developers of Wireshark will maintain your code as well,
+  fixing it when API changes or other changes are made, and generally keeping it
+  in tune with what is happening with Wireshark. So if Wireshark is updated
+  (which is done often), you can get a new Wireshark version from the website
+  and your changes will already be included without any effort for you. 
+
+The Wireshark source code and binary kits for some platforms are all available
+on the download page of the Wireshark website:
+wireshark-download-page:[][wireshark-download-page:[]]. 
+
+[[ChIntroHelp]]
+
+=== Reporting problems and getting help
+
+If you have problems or need help with Wireshark there are several places that
+may be of interest to you (well, besides this guide of course). 
+
+[[ChIntroHomepage]]
+
+==== Website
+
+You will find lots of useful information on the Wireshark homepage at
+wireshark-web-site:[][wireshark-web-site:[]]. 
+
+[[ChIntroWiki]]
+
+==== Wiki
+
+The Wireshark Wiki at wireshark-wiki-site:[][wireshark-wiki-site:[]] provides a
+wide range of information related to Wireshark and packet capture in general.
+You will find a lot of information not part of this user's guide. For example,
+there is an explanation how to capture on a switched network, an ongoing effort
+to build a protocol reference and a lot more.
+
+And best of all, if you would like to contribute your knowledge on a specific
+topic (maybe a network protocol you know well) you can edit the wiki pages by
+simply using your web browser. 
+
+[[ChIntroQA]]
+
+==== Q&amp;A Site
+
+The Wireshark Q&amp;A site at wireshark-qa-url:[][wireshark-qa-url:[]] offers a
+resource where questions and answers come together. You have the option to
+search what questions were asked before and what answers were given by people
+who knew about the issue. Answers are graded, so you can pick out the best ones
+easily. If your question hasn't been discussed before you can post one yourself. 
+
+[[ChIntroFAQ]]
+
+==== FAQ
+
+The Frequently Asked Questions lists often asked questions and their corresponding answers.
+
+[NOTE]
+.Read the FAQ
+====
+Before sending any mail to the mailing lists below, be sure to read the FAQ. It
+will often answer any questions you might have. This will save yourself and
+others a lot of time. Keep in mind that a lot of people are subscribed to the
+mailing lists.
+====
+
+You will find the FAQ inside Wireshark by clicking the menu item Help/Contents
+and selecting the FAQ page in the dialog shown.
+
+An online version is available at the Wireshark website:
+link:$$wireshark-faq-url:[]$$[wireshark-faq-url:[]]. You might prefer this
+online version, as it's typically more up to date and the HTML format is easier
+to use. 
+
+[[ChIntroMailingLists]]
+
+==== Mailing Lists
+
+There are several mailing lists of specific Wireshark topics available:
+
+_wireshark-announce_::
+    This mailing list will inform you about new program releases, which usually appear about every 4-8 weeks. 
+
+
+_wireshark-users_:: 
+    This list is for users of Wireshark.  People post questions about building and using Wireshark, others (hopefully) provide answers. 
+
+
+_wireshark-dev_:: 
+    This list is for Wireshark developers. If you want to start developing a protocol dissector, join this list. 
+
+You can subscribe to each of these lists from the Wireshark web site:
+wireshark-mailing-lists-url:[][wireshark-mailing-lists-url:[]]. From
+there, you can choose which mailing list you want to subscribe to by clicking on
+the Subscribe/Unsubscribe/Options button under the title of the relevant list.
+The links to the archives are included on that page as well. 
+
+[TIP]
+.The lists are archived
+====
+You can search in the list archives to see if someone asked the same question
+some time before and maybe already got an answer. That way you don't have to
+wait until someone answers your question. 
+====
+
+==== Reporting Problems
+
+[NOTE]
+====
+Before reporting any problems, please make sure you have installed the latest
+version of Wireshark. 
+====
+
+
+When reporting problems with Wireshark please supply the following information: 
+
+. The version number of Wireshark and the dependent libraries linked with it,
+  such as Qt or GLib. You can obtain this from Wireshark's about box or the
+  command `wireshark -v`.
+
+. Information about the platform you run Wireshark on.
+
+. A detailed description of your problem.
+
+. If you get an error/warning message, copy the text of that message (and also a
+  few lines before and after it, if there are some) so others may find the
+  place where things go wrong. Please don't give something like: "I get a
+  warning while doing x" as this won't give a good idea where to look. 
+
+[NOTE]
+.Don't send large files
+====
+Do not send large files (&gt;500KB) to the mailing lists. Just place a note that
+further data is available on request. Large files will only annoy a lot of
+people on the list who are not interested in your specific problem. If required
+you will be asked for further data by the persons who really can help you. 
+====
+
+[WARNING]
+.Don't send confidential information!
+====
+If you send capture files to the mailing lists be sure they don't contain any
+sensitive or confidential information like passwords or personally identifiable
+information (PII). 
+====
+
+==== Reporting Crashes on UNIX/Linux platforms
+
+When reporting crashes with Wireshark it is helpful if you supply the traceback
+information along with the information mentioned in "Reporting Problems". 
+
+You can obtain this traceback information with the following commands on UNIX or Linux (note the backticks): 
+
+----
+$ gdb `whereis wireshark | cut -f2 -d: | cut -d' ' -f2` core >& backtrace.txt
+backtrace
+^D
+----
+
+If you do not have `gdb` available, you will have to check out your operating system's debugger. 
+
+Mail `backtrace.txt` to
+mailto:wireshark-dev-list-email:[][wireshark-dev-list-email:[]].
+
+==== Reporting Crashes on Windows platforms
+
+The Windows distributions don't contain the symbol files (.pdb) because they are
+very large. You can download them separately at
+wireshark-download-page:[]download/win32/all-versions and
+wireshark-download-page:[]download/win64/all-versions
+
+++++++++++++++++++++++++++++++++++++++
+<!-- End of WSUG Chapter 1 -->
+++++++++++++++++++++++++++++++++++++++
\ No newline at end of file