The first draft of an updated "Ethereal User's Guide" redesigned and updated to the current released Ethereal version 0.10.5.

As generation of output files is a bit tricky, please have a look at the Readme.txt file for instructions.

Please send comments and improvements.

svn path=/trunk/; revision=11433

docbook/GFDPL_appendix.xml

@@ -0,0 +1,443 @@
+<!-- Ethereal GFDPL Appendix -->
+<appendix id="AppGFDL">
+  <title>This Documents License (GFDL)</title>
+  <section>
+  <title>The GNU Free Document Public Licence</title>
+  <section>
+    <title>Copyright</title>
+    <para>Version 1.1, March 2000 </para>
+    <para>
+      Copyright (C) 2000  Free Software Foundation, Inc.
+      59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+      Everyone is permitted to copy and distribute verbatim copies
+      of this license document, but changing it is not allowed.
+    </para>
+  </section>
+  <section>
+    <title>Preamble</title>
+    <para>
+      The purpose of this License is to make a manual, textbook, or other 
+      written document "free" in the sense of freedom: to assure everyone 
+      the effective freedom to copy and redistribute it, with or without 
+      modifying it, either commercially or noncommercially. Secondarily, 
+      this License preserves for the author and publisher a way to get 
+      credit for their work, while not being considered responsible for 
+      modifications made by others. 
+    </para>
+    <para>
+      This License is a kind of "copyleft", which means that derivative 
+      works of the document must themselves be free in the same sense. It 
+      complements the GNU General Public License, which is a copyleft 
+      license designed for free software. 
+    </para>
+    <para>
+      We have designed this License in order to use it for manuals for free 
+      software, because free software needs free documentation: a free 
+      program should come with manuals providing the same freedoms that the 
+      software does. But this License is not limited to software manuals; it 
+      can be used for any textual work, regardless of subject matter or 
+      whether it is published as a printed book. We recommend this License 
+      principally for works whose purpose is instruction or reference. 
+    </para>
+  </section>
+  <section>
+    <title>Applicability and Definitions</title>
+    <para>
+      This License applies to any manual or other work that contains a notice 
+      placed by the copyright holder saying it can be distributed under the 
+      terms of this License.  The "Document", below, refers to any such 
+      manual or work. Any member of the public is a licensee, and is 
+      addressed as "you". 
+    </para>
+    <para>
+      A "Modified Version" of the Document means any work containing the 
+      Document or a portion of it, either copied verbatim, or with 
+      modifications and/or translated into another language. 
+    </para>
+    <para>
+      A "Secondary Section" is a named appendix or a front-matter section of 
+      the Document that deals exclusively with the relationship of the 
+      publishers or authors of the Document to the Document's overall subject 
+      (or to related matters) and contains nothing that could fall directly 
+      within that overall subject. (For example, if the Document is in part a 
+      textbook of mathematics, a Secondary Section may not explain any 
+      mathematics.) The relationship could be a matter of historical 
+      connection with the subject or with related matters, or of legal, 
+      commercial, philosophical, ethical or political position regarding them.
+    </para>
+    <para>
+      The "Invariant Sections" are certain Secondary Sections whose titles 
+      are designated, as being those of Invariant Sections, in the notice 
+      that says that the Document is released under this License. 
+    </para>
+    <para>
+      The "Cover Texts" are certain short passages of text that are listed, 
+      as Front-Cover Texts or Back-Cover Texts, in the notice that says 
+      that the Document is released under this License. 
+    </para>
+    <para>
+      A "Transparent" copy of the Document means a machine-readable copy, 
+      represented in a format whose specification is available to the 
+      general public, whose contents can be viewed and edited directly 
+      and straightforwardly with generic text editors or (for images 
+      composed of pixels) generic paint programs or (for drawings) some 
+      widely available drawing editor, and that is suitable for input to 
+      text formatters or for automatic translation to a variety of 
+      formats suitable for input to text formatters. A copy made in an 
+      otherwise Transparent file format whose markup has been designed 
+      to thwart or discourage subsequent modification by readers is not 
+      Transparent. A copy that is not "Transparent" is called "Opaque". 
+    </para>
+    <para>
+      Examples of suitable formats for Transparent copies include plain 
+      ASCII without markup, Texinfo input format, LaTeX input format, 
+      SGML or XML using a publicly available DTD, and standard-conforming 
+      simple HTML designed for human modification. Opaque formats include 
+      PostScript, PDF, proprietary formats that can be read and edited 
+      only by proprietary word processors, SGML or XML for which the 
+      DTD and/or processing tools are not generally available, and the
+      machine-generated HTML produced by some word processors for output 
+      purposes only. 
+    </para>
+    <para>
+      The "Title Page" means, for a printed book, the title page itself, plus 
+      such following pages as are needed to hold, legibly, the material this 
+      License requires to appear in the title page. For works in formats 
+      which do not have any title page as such, "Title Page" means the text 
+      near the most prominent appearance of the work's title,
+      preceding the beginning of the body of the text. 
+    </para>
+  </section>
+  <section>
+    <title>Verbatim Copying</title>
+    <para>
+      You may copy and distribute the Document in any medium, either 
+      commercially or noncommercially, provided that this License, the 
+      copyright notices, and the license notice saying this License 
+      applies to the Document are reproduced in all copies, and that you 
+      add no other conditions whatsoever to those of this License. You may
+      not use technical measures to obstruct or control the reading or 
+      further copying of the copies you make or distribute. However, you 
+      may accept compensation in exchange for copies. If you distribute a 
+      large enough number of copies you must also follow the conditions 
+      in section 3. 
+    </para>
+    <para>
+      You may also lend copies, under the same conditions stated above, and 
+      you may publicly display copies. 
+    </para>
+  </section>
+  <section>
+    <title>Copying in Quantity</title>
+    <para>
+      If you publish printed copies of the Document numbering more than 100, 
+      and the Document's license notice requires Cover Texts, you must 
+      enclose the copies in covers that carry, clearly and legibly, all 
+      these Cover Texts: Front-Cover Texts on the front cover, and 
+      Back-Cover Texts on the back cover. Both covers must also
+      clearly and legibly identify you as the publisher of these copies. The 
+      front cover must present the full title with all words of the title 
+      equally prominent and visible. You may add other material on the 
+      covers in addition. Copying with changes limited to the covers, 
+      as long as they preserve the title of the Document and satisfy these
+      conditions, can be treated as verbatim copying in other respects. 
+    </para>
+    <para>
+      If the required texts for either cover are too voluminous to fit 
+      legibly, you should put the first ones listed (as many as fit 
+      reasonably) on the actual cover, and continue
+      the rest onto adjacent pages. 
+    </para>
+    <para>
+      If you publish or distribute Opaque copies of the Document numbering 
+      more than 100, you must either include a machine-readable Transparent 
+      copy along with each Opaque copy, or state in or with each Opaque 
+      copy a publicly-accessible computer-network location containing a 
+      complete Transparent copy of the Document, free of added material, 
+      which the general network-using public has access to download 
+      anonymously at no charge using public-standard network protocols. If 
+      you use the latter option, you must take reasonably prudent steps, 
+      when you begin distribution of Opaque copies in quantity, to ensure 
+      that this Transparent copy will remain thus accessible at the stated 
+      location until at least one year after the last time you distribute an 
+      Opaque copy (directly or through your agents or retailers) of that 
+      edition to the public. 
+    </para>
+    <para>
+      It is requested, but not required, that you contact the authors of the 
+      Document well before redistributing any large number of copies, to 
+      give them a chance to provide you with an updated version of the 
+      Document. 
+    </para>
+  </section>
+  <section>
+    <title>Modifications</title>
+    <para>
+      You may copy and distribute a Modified Version of the Document under 
+      the conditions of sections 2 and 3 above, provided that you release 
+      the Modified Version under precisely this License, with the Modified 
+      Version filling the role of the Document, thus licensing distribution 
+      and modification of the Modified Version to whoever possesses a copy of 
+      it. In addition, you must do these things in the Modified Version: 
+      <itemizedlist>
+	<listitem>
+	  <para>
+	    Use in the Title Page (and on the covers, if any) a title 
+	    distinct from that of the Document, and from those of previous 
+	    versions (which should, if there were any, be listed in the 
+	    History section of the Document). You may use the same title as 
+	    a previous version if the original publisher of that version gives
+	    permission.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    List on the Title Page, as authors, one or more persons or 
+	    entities responsible for authorship of the modifications in the 
+	    Modified Version, together with at least five of the principal 
+	    authors of the Document (all of its principal authors, 
+	    if it has less than five). 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    State on the Title page the name of the publisher of the 
+	    Modified Version, as the publisher. 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    Preserve all the copyright notices of the Document. 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    Add an appropriate copyright notice for your modifications 
+	    adjacent to the other copyright notices. 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    Include, immediately after the copyright notices, a license 
+	    notice giving the public permission to use the Modified Version 
+	    under the terms of this License, in the form shown in the 
+	    Addendum below. 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    Preserve in that license notice the full lists of Invariant 
+	    Sections and required Cover Texts given in the Document's 
+	    license notice. 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>Include an unaltered copy of this License. </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    Preserve the section entitled "History", and its title, and add 
+	    to it an item stating at least the title, year, new authors, 
+	    and publisher of the Modified Version as given on the Title 
+	    Page. If there is no section entitled "History" in the 
+	    Document, create one stating the title, year, authors, 
+	    and publisher of the Document as given on its Title Page, 
+	    then add an item describing the Modified Version as stated 
+	    in the previous sentence. 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    Preserve the network location, if any, given in the Document 
+	    for public access to a Transparent copy of the Document, and 
+	    likewise the network locations given in the Document for 
+	    previous versions it was based on. These may be placed in 
+	    the "History" section. You may omit a network location for a 
+	    work that was published at least four years before the 
+	    Document itself, or if the original publisher of the version 
+	    it refers to gives permission. 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    In any section entitled "Acknowledgements" or "Dedications", 
+	    preserve the section's title, and preserve in the section all 
+	    the substance and tone of each of the contributor 
+	    acknowledgements and/or dedications given therein. 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    Preserve all the Invariant Sections of the Document, unaltered 
+	    in their text and in their titles. Section numbers or the 
+	    equivalent are not considered part of the section titles. 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    Delete any section entitled "Endorsements". Such a section 
+	    may not be included in the Modified Version. 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    Do not retitle any existing section as "Endorsements" or to 
+	    conflict in title with any Invariant Section. 
+	  </para>
+	</listitem>
+      </itemizedlist>
+    </para>
+    <para>
+      If the Modified Version includes new front-matter sections or 
+      appendices that qualify as Secondary Sections and contain no 
+      material copied from the Document, you may at your option designate 
+      some or all of these sections as invariant. To do this, add their 
+      titles to the list of Invariant Sections in the Modified Version's 
+      license notice. These titles must be distinct from any other section 
+      titles. 
+    </para>
+    <para>
+      You may add a section entitled "Endorsements", provided it contains 
+      nothing but endorsements of your Modified Version by various 
+      parties--for example, statements of peer review or that the text has 
+      been approved by an organization as the authoritative definition of a 
+      standard. 
+    </para>
+    <para>
+      You may add a passage of up to five words as a Front-Cover Text, 
+      and a passage of up to 25 words as a Back-Cover Text, to the end 
+      of the list of Cover Texts in the Modified Version. Only one passage 
+      of Front-Cover Text and one of Back-Cover Text may be added by (or 
+      through arrangements made by) any one entity. If the Document 
+      already includes a cover text for the same cover, previously added 
+      by you or by arrangement made by the same entity you are acting on 
+      behalf of, you may not add another; but you may replace the old one, 
+      on explicit permission from the previous publisher that added the 
+      old one. 
+    </para>
+    <para>
+      The author(s) and publisher(s) of the Document do not by this 
+      License give permission to use their names for publicity for or to 
+      assert or imply endorsement of any Modified Version. 
+    </para>
+  </section>
+  <section>
+    <title>Combining Documents</title>
+    <para>
+      You may combine the Document with other documents released under 
+      this License, under the terms defined in section 4 above for 
+      modified versions, provided that you include in the combination all 
+      of the Invariant Sections of all of the original documents, 
+      unmodified, and list them all as Invariant Sections of your combined 
+      work in its license notice. 
+    </para>
+    <para>
+      The combined work need only contain one copy of this License, and 
+      multiple identical Invariant Sections may be replaced with a single 
+      copy. If there are multiple Invariant Sections with the same name 
+      but different contents, make the title of each such section unique 
+      by adding at the end of it, in parentheses, the name of the
+      original author or publisher of that section if known, or else a 
+      unique number. Make the same adjustment to the section titles in 
+      the list of Invariant Sections in the license notice of the combined 
+      work. 
+    </para>
+    <para>
+      In the combination, you must combine any sections entitled "History" 
+      in the various original documents, forming one section entitled 
+      "History"; likewise combine any sections entitled "Acknowledgements", 
+      and any sections entitled "Dedications". You must delete all 
+      sections entitled "Endorsements." 
+    </para>
+  </section>
+  <section>
+    <title>Collections of Documents</title>
+    <para>
+      You may make a collection consisting of the Document and other 
+      documents released under this License, and replace the individual 
+      copies of this License in the various documents with a single copy 
+      that is included in the collection, provided that you follow the 
+      rules of this License for verbatim copying of each of the
+      documents in all other respects. 
+    </para>
+    <para>
+      You may extract a single document from such a collection, and 
+      distribute it individually under this License, provided you insert a 
+      copy of this License into the extracted document, and follow this 
+      License in all other respects regarding verbatim copying of 
+      that document. 
+    </para>
+  </section>
+  <section>
+    <title>Aggregation with Independent Works</title>
+    <para>
+      A compilation of the Document or its derivatives with other separate 
+      and independent documents or works, in or on a volume of a storage 
+      or distribution medium, does not as a whole count as a Modified 
+      Version of the Document, provided no compilation copyright is 
+      claimed for the compilation. Such a compilation is called an
+      "aggregate", and this License does not apply to the other 
+      self-contained works thus compiled with the Document, on account 
+      of their being thus compiled, if they are not themselves derivative 
+      works of the Document. 
+    </para>
+    <para>
+      If the Cover Text requirement of section 3 is applicable to these 
+      copies of the Document, then if the Document is less than one quarter 
+      of the entire aggregate, the Document's Cover Texts may be placed 
+      on covers that surround only the Document within the aggregate. 
+      Otherwise they must appear on covers around the whole
+      aggregate. 
+    </para>
+  </section>
+  <section>
+    <title>Translation</title>
+    <para>
+      Translation is considered a kind of modification, so you may 
+      distribute translations of the Document under the terms of 
+      section 4. Replacing Invariant Sections with translations requires 
+      special permission from their copyright holders, but you may include 
+      translations of some or all Invariant Sections in addition to the 
+      original versions of these Invariant Sections. You may include a 
+      translation of this License provided that you also include the 
+      original English version of this License. In case
+      of a disagreement between the translation and the original 
+      English version of this License, the original English version will 
+      prevail. 
+    </para>
+  </section>
+  <section>
+    <title>Termination</title>
+    <para>
+      You may not copy, modify, sublicense, or distribute the Document 
+      except as expressly provided for under this License. Any other 
+      attempt to copy, modify, sublicense or distribute the Document is 
+      void, and will automatically terminate your rights under this 
+      License. However, parties who have received copies, or rights,
+      from you under this License will not have their licenses terminated 
+      so long as such parties remain in full compliance. 
+    </para>
+  </section>
+  <section>
+    <title>Future Revisions of this License</title>
+    <para>
+      The Free Software Foundation may publish new, revised versions of the 
+      GNU Free Documentation License from time to time. Such new versions 
+      will be similar in spirit to the present version, but may differ in 
+      detail to address new problems or concerns. See 
+      http://www.gnu.org/copyleft/. 
+    </para>
+    <para>
+      Each version of the License is given a distinguishing version 
+      number. If the Document specifies that a particular numbered 
+      version of this License "or any later version" applies to it, you 
+      have the option of following the terms and conditions either of 
+      that specified version or of any later version that has been 
+      published (not as a draft) by the Free Software Foundation. If 
+      the Document does not specify a version number of this License, 
+      you may choose any version ever published (not as a draft) by the 
+      Free Software Foundation.
+    </para>
+  </section>
+  </section>
+</appendix>

docbook/Makefile

@@ -0,0 +1,99 @@
+#
+# Make the "Ethereal User's Guide" in several formats.
+# See the Readme.txt file for instructions.
+#
+
+# if you need to change this, don't forget to change it in catalog.xml too
+DOCBOOKXSL="/usr/share/docbook-xsl"
+
+# formatting objects processor
+# (comment this out, if you don't want pdf or don't have fop installed)
+FOP="fop-0.20.5/fop.bat"
+#FOP="fop-0.20.5/fop.sh"
+
+# html help compiler (Win32 only)
+# (comment this out, if you don't want chm or don't have hhc installed)
+HHC="/cygdrive/c/Program Files/HTML Help Workshop/hhc.exe"
+
+############### YOU SHOULDN'T HAVE TO EDIT ANYTHING BELOW THIS LINE! ################
+
+# the XSL processor
+XSLTPROC="xsltproc"
+
+# the XML validator (from the xsltproc package)
+XMLLINT="xmllint"
+
+# as eug_chm will stop with an error, make sure it's the last in this dependency list
+all: eug_validate eug_pdf_a4 eug_html eug_html_chunked eug_chm 
+
+clean:
+	rm -f *.html
+	rm -f htmlhelp.*
+	rm -f *.hhc
+	rm -f *.fo
+	rm -f *.pdf
+	rm -f *.chm
+
+images:
+	cp $(DOCBOOKXSL)/images/note.png ./graphics
+	cp $(DOCBOOKXSL)/images/tip.png ./graphics
+	cp $(DOCBOOKXSL)/images/warning.png ./graphics
+
+# validate the content
+eug_validate:
+	@ echo --- VALIDATING XML ---
+	$(XMLLINT) --valid --noout user-guide.xml
+
+# create html single page file
+eug_html:
+	@ echo --- HTML SINGLE PAGE ---
+	mkdir -p eug_html
+	mkdir -p eug_html/graphics
+	mkdir -p eug_html/graphics/toolbar
+	cp ./graphics/*.* eug_html/graphics
+	cp ./graphics/toolbar/*.* eug_html/graphics/toolbar
+	$(XSLTPROC) --nonet $(DOCBOOKXSL)/html/docbook.xsl user-guide.xml > eug_html/user-guide.html
+	
+# create html chunked page files
+eug_html_chunked: images
+	@ echo --- HTML CHUNKED ---
+	mkdir -p eug_html_chunked
+	mkdir -p eug_html_chunked/graphics
+	mkdir -p eug_html_chunked/graphics/toolbar
+	cp ./graphics/*.* eug_html_chunked/graphics
+	cp ./graphics/toolbar/*.* eug_html_chunked/graphics/toolbar
+	$(XSLTPROC) --stringparam base.dir eug_html_chunked/ --stringparam  use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam  section.label.includes.component.label 1 --nonet $(DOCBOOKXSL)/html/chunk.xsl user-guide.xml
+
+# create pdf file (through XSL-FO), portrait pages on US letter paper (the default)
+# you will get lot's of errors, but that's ok
+eug_pdf_us: images
+ifdef FOP
+	@ echo --- PDF US PAPER ---
+	$(XSLTPROC) --nonet custom_layer_pdf.xsl $(DOCBOOKXSL)/fo/docbook.xsl user-guide.xml > user-guide.fo
+	$(FOP) user-guide.fo user-guide.pdf
+endif
+
+# create pdf file (through XSL-FO), portrait pages on A4 paper
+# you will get lot's of errors, but that's ok
+eug_pdf_a4: images
+ifdef FOP
+	@ echo --- PDF A4 PAPER ---
+	$(XSLTPROC) --stringparam paper.type A4 --nonet custom_layer_pdf.xsl user-guide.xml > user-guide.fo
+	$(FOP) user-guide.fo user-guide.pdf
+endif
+
+# create MS html help file (through html chunked pages)
+eug_chm: images
+ifdef HHC
+	@ echo --- MICROSOFT HTML HELP ---
+	mkdir -p eug_chm
+	mkdir -p eug_chm/graphics
+	mkdir -p eug_chm/graphics/toolbar
+	cp ./graphics/*.* eug_chm/graphics
+	cp ./graphics/toolbar/*.* eug_chm/graphics/toolbar
+	$(XSLTPROC) --stringparam base.dir eug_chm/ --stringparam  use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam  section.label.includes.component.label 1 --nonet $(DOCBOOKXSL)/htmlhelp/htmlhelp.xsl user-guide.xml
+	-$(HHC) htmlhelp.hhp
+	mv htmlhelp.chm user-guide.chm
+	rm -r htmlhelp.hhp
+	rm -r toc.hhc
+endif

docbook/README.txt

@@ -0,0 +1,135 @@
+This directory contains the source files needed to build the:
+
+Ethereal User's guide (almost ready to release, has to be reviewed) 
+
+and the:
+
+Ethereal Developer's Guide  (long time unchanged still a very early state).
+
+To build the User's Guide, just do 'make', but see requirements below.
+The Developer's Guide is currently not generated, as it has no content.
+
+
+The guides are written in Docbook/XML (formerly Docbook/SGML). This format is 
+now used by many other documentation projects, e.g. "the linux documentation 
+project" uses it too.
+
+To get HTML, PDF or other output formats, conversions are done using XSL 
+stylesheets, which provides a flexible way for these conversions.
+
+The current Makefile is running under Win32 in the cygwin environment, so it uses 
+GNU make and such. It should be pretty easy to use it in UNIX environments too.
+Using Microsoft make (nmake) is not supported.
+
+By default the Makefile generates HTML in single page and multiple (chunked) formats.
+Optional output formats are PDF and CHM.
+
+
+Requirements:
+-------------
+
+Settings in Makefile and catalog.xml
+------------------------------------
+You have to edit the settings in these files, to point to the DTD/XSL files, fop (and possibly hhc).
+
+DocBook XML DTD
+---------------
+DocBook "official" XML DTD V4.2 from:
+http://www.oasis-open.org/docbook/xml/
+(or using cygwin package docbook-xml42)
+
+DocBook XSL
+-----------
+The "official" XSL stylesheets from Norman Walsh:
+http://docbook.sourceforge.net/
+(or using cygwin package docbook-xsl)
+
+xsltproc
+--------
+The XSL processor xsltproc. 
+(it seems to be packages libxml2 and libxslt, ... please give comments)
+
+FOP processor (for PDF generation only)
+---------------------------------------
+FOP processor from the apache project:
+http://xml.apache.org/fop/
+FOP is a JAVA program, so you need to have a JAVA environment installed.
+I have put the fop-0.20.5 dir right into the sources dir. If you have it somewhere else,
+you'll have to change the setting in the Makefile.
+
+Be sure to also have installed JAI and/or jimi to be able to use/convert the png graphics files.
+The fop release note webpage tells how to do it: 
+download jimi from:
+http://java.sun.com/products/jimi/
+then extract the archive, then copy JimiProClasses.zip to FOP's lib dir and rename it to jimi-1.0.jar.
+
+As I got OutOfMemoryException when running fop, I had to insert -Xmx256m into the last line of the fop.bat file from:
+java -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
+to:
+java -Xmx256m -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
+
+HTML help compiler (for chm file generation only)
+-------------------------------------------------
+hhc compiler from Microsoft:
+http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp 
+
+
+Makefile:
+---------
+There are several ways and tools to do these conversion, following is a short 
+description of the way the makefile targets are doing things and which output 
+files required for a release in that format.
+
+all
+Will generate all output formats (see below).
+
+make eug_html
+The HTML file is generated using xsltproc and the XSL stylesheets from 
+Norman Walsh. This is a conversion into a single HTML page.
+output: eug_html
+
+make eug_htmlchunk
+The HTML files are generated using xsltproc and the XSL stylesheets from 
+Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
+output: eug_html_chunked
+
+make eug_pdf_us
+make eug_pdf_a4
+The PDF is generated using an intermediate format named XSL-FO (XSL 
+formatting objects). xsltproc converts the XML to a FO file, and then fop 
+(apache's formatting object processor) is used to generate the PDF document, 
+in US letter or A4 paper format.
+TIPP: You will get lot's of INFO/WARNING/ERROR messages when generating pdf, 
+but conversation works just fine.
+output: user-guide.pdf
+
+make eug_chm
+On Win32 platforms, the "famous" HTML help format can be generated by using a 
+special HTML chunked conversion and then use the htmlhelp compiler from 
+Microsoft.
+output: htmlhelp.chm
+
+The makefile is written to be run with gmake on unix/linux platforms. Win32 
+platforms have to use the cygwin environment (Microsoft nmake is not 
+supported).
+
+
+Docbook web references:
+-----------------------
+Some web references to further documentation about Docbook/XML and Docbook XSL conversions:
+
+DocBook: The Definitive Guide
+by Norman Walsh and Leonard Muellner
+http://www.docbook.org/tdg/en/html/docbook.html
+
+DocBook XSL: The Complete Guide
+by Bob Stayton
+http://www.sagehill.net/docbookxsl/index.html
+
+Documention with DocBook on Win32
+by Jim Crafton
+http://www.codeproject.com/winhelp/docbook_howto.asp
+
+FO Parameter Reference
+by Norman Walsh
+http://docbook.sourceforge.net/release/xsl/current/doc/fo/

docbook/catalog.xml

@@ -0,0 +1,56 @@
+<?xml version="1.0"?>
+<!-- Ethereal User's Guide and Developer's Guide catalog
+
+
+Intall this copy into the root directory of the book. Please note that if you shift any files in the directory structure you MUST adjust this catalog.
+
+
+-->
+<!DOCTYPE catalog
+   PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
+   "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
+
+<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
+
+  <!-- DTD and stylesheet files installed under /usr/share/xml -->
+  <group  xml:base="file:///usr/share/xml/" >
+
+    <!-- Resolve DTD URL system ID to local file -->
+    <rewriteSystem
+        systemIdStartString="http://www.oasis-open.org/docbook/xml/4.2/"
+        rewritePrefix="/usr/share/docbook-xml42/" />
+    <!-- Resolve stylesheet URL to local file -->
+    <!-- if you need to change this, don't forget to change it in the Makefile too -->
+    <rewriteURI
+        uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
+        rewritePrefix="/usr/share/docbook-xsl/" />
+
+    <!-- Resolve DTD PUBLIC identifiers -->
+    <nextCatalog  catalog="docbook42/catalog.xml" />
+
+    <!-- To resolve simple DTD SYSTEM identifiers. -->
+    <!-- Note: this does not work with Java resolver -->
+    <!--   classes in Saxon or Xalan -->
+    <system
+         systemId="docbook.dtd"
+         uri="docbook42/docbookx.dtd" />
+
+    <!-- To resolve short stylesheet references -->
+	<!--
+    <system
+        systemId="EtherealMain1"
+        uri="./graphics/ethereal-main.jpg" />
+    <system
+        systemId="EtherealThreePane1"
+        uri="./graphics/ethereal-main.jpg" />
+    <uri 
+        name="chunk.xsl"
+        uri="docbook-xsl-1.62.1/html/chunk.xsl" />
+    <uri
+        name="fo-docbook.xsl"
+        uri="docbook-xsl-1.62.1/fo/docbook.xsl" />
+	-->
+
+  </group>
+
+</catalog>

docbook/custom_layer_pdf.xsl

@@ -0,0 +1,36 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version="1.0">
+
+<!-- import the main stylesheet -->
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
+
+<!-- create pdf bookmarks -->
+<xsl:param name="fop.extensions" select="1"/>
+
+<!-- use graphics for admons (note, tip, ...) -->
+<xsl:param name="admon.graphics" select="1"/>
+<xsl:param name="admon.graphics.path">graphics/</xsl:param>
+
+<!-- use numbering for sections (not only for chapters) -->
+<xsl:param name="section.autolabel" select="1"/>
+<xsl:param name="section.label.includes.component.label" select="1"/>
+
+<!-- include page numbers in cross references -->
+<!-- <xsl:param name="insert.xref.page.number" select="1"/> -->
+
+<!-- don't show URL's, but only the text of it -->
+<xsl:param name="ulink.show" select="0"/>
+
+<!-- put a page break after each section -->
+<xsl:attribute-set name="section.level1.properties">
+  <xsl:attribute name="break-after">page</xsl:attribute>
+</xsl:attribute-set>
+
+<!-- set link style to blue and underlined -->
+<xsl:attribute-set name="xref.properties">
+  <xsl:attribute name="color">blue</xsl:attribute>
+  <xsl:attribute name="text-decoration">underline</xsl:attribute>
+</xsl:attribute-set>
+
+</xsl:stylesheet>

docbook/developer-guide.xml

@@ -0,0 +1,76 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+<!--
+BIOGRAPHICAL SECTION
+-Use this section to encode all biographical information
+-->
+
+<!-- Authors Names -->
+  <!ENTITY AuthorFullName "Richard Sharpe">
+  <!ENTITY AuthorFirstName "Richard">
+  <!ENTITY AuthorOtherName "">
+  <!ENTITY AuthorSurname "Sharpe">
+
+<!--Authors Affiliation -->
+  <!ENTITY AuthorShortAffiliation "">
+  <!ENTITY AuthorJobTitle "Director">
+  <!ENTITY AuthorOrgName "NS Computer Software and Services P/L">
+  <!ENTITY AuthorOrgDiv "">
+
+<!--
+DOCUMENT SECTION
+-Use this section to encode all document information
+-->
+
+  <!ENTITY DocumentTitle "<application>Ethereal</application> Developer's Guide">
+  <!ENTITY DocumentSubTitle "">
+  <!ENTITY DocumentTitleAbbreviation "EDG">
+
+  <!ENTITY DocumentCopyrightHolder "NS Computer Software and Services P/L">
+  <!ENTITY DocumentCopyrightYear "2000">
+
+  <!ENTITY DocumentEdition "First edition">
+  <!ENTITY DocumentPubDate "2000">
+
+  <!ENTITY DocumentLegalNotice "<para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled &quot;GNU Free Documentation License&quot;</para>">
+
+<!--
+Ethereal Info
+-->
+  <!ENTITY EtherealCurrentVersion "0.8.10">
+  <!ENTITY EtherealNextMinorVersion "0.8.11">
+
+<!--
+FILE SECTION
+-Use this section to specify the files that make up the book. Use FPI (public identifiers)
+-->
+
+
+<!-- These are the actual files that make up the document -->
+  <!ENTITY BookMetaInformation SYSTEM "dg-src/EDG_meta_info.xml">
+  <!ENTITY Chapter1 SYSTEM "dg-src/EDG_chapter_one.xml">
+  <!ENTITY Chapter2 SYSTEM "dg-src/EDG_chapter_two.xml">
+  <!ENTITY Chapter3 SYSTEM "dg-src/EDG_chapter_three.xml">
+  <!ENTITY Chapter4 SYSTEM "dg-src/EDG_chapter_four.xml">
+  <!ENTITY Chapter5 SYSTEM "dg-src/EDG_chapter_five.xml">
+
+<!-- These refer to graphics files and figures contained in the document -->
+  <!-- 1st Chapter -->
+]>
+
+<book>
+<title>&DocumentTitle;</title>
+<subtitle>&DocumentSubTitle;</subtitle>
+&BookMetaInformation;
+&Chapter1;
+&Chapter2;
+&Chapter3;
+&Chapter4;
+&Chapter5;
+<!--
+
+&Glossary;
+&Index;  -->
+</book>

docbook/dfilter2xml.pl

@@ -0,0 +1,153 @@
+#!/usr/bin/perl
+#
+# Reads the display filter keyword dump produced by 'ethereal -G' and
+# formats it for a pod document. The pod document is then used to
+# make a manpage
+#
+# STDIN is the ethereal glossary
+# arg1 is the pod template file. The =insert_dfilter_table token
+#	will be replaced by the pod-formatted glossary
+# STDOUT is the output
+#
+# $Id: dfilter2sgml,v 1.5 2002/09/10 15:49:57 sharpe Exp $
+
+%ftenum_names = (
+	'FT_NONE',		'No value',
+	'FT_PROTOCOL',		'Protocol',
+	'FT_BOOLEAN',		'Boolean',
+	'FT_UINT8',		'Unsigned 8-bit integer',
+	'FT_UINT16',		'Unsigned 16-bit integer',
+	'FT_UINT24',		'Unsigned 24-bit integer',
+	'FT_UINT32',		'Unsigned 32-bit integer',
+	'FT_UINT64',		'Unsigned 64-bit integer',
+	'FT_INT8',		'Signed 8-bit integer',
+	'FT_INT16',		'Signed 16-bit integer',
+	'FT_INT24',		'Signed 24-bit integer',
+	'FT_INT32',		'Signed 32-bit integer',
+	'FT_INT64',		'Signed 64-bit integer',
+	'FT_DOUBLE',		'Double-precision floating point',
+	'FT_ABSOLUTE_TIME',	'Date/Time stamp',
+	'FT_RELATIVE_TIME',	'Time duration',
+	'FT_STRING',		'String',
+	'FT_STRINGZ',		'String',
+	'FT_UINT_STRING',	'String',
+	'FT_ETHER',		'6-byte Hardware (MAC) Address',
+	'FT_BYTES',		'Byte array',
+	'FT_IPv4',		'IPv4 address',
+	'FT_IPv6',		'IPv6 address',
+	'FT_IPXNET',		'IPX network or server name',
+);
+
+# Read all the data into memory
+while (<STDIN>) {
+	next unless (/^([PF])/);
+
+	$record_type = $1;
+	chomp($_);
+	$_ =~ s/\&/\&amp\;/g;
+	$_ =~ s/\>/\&gt;/g;
+	$_ =~ s/\</\&lt\;/g;
+
+	# Store protocol information
+	if ($record_type eq 'P') {
+		($junk, $name, $abbrev) = split(/\t+/, $_);
+		$proto_abbrev{$name} = $abbrev;
+	}
+	# Store header field information
+	else {
+		($junk, $name, $abbrev, $type, $parent, $blurb) =
+			split(/\t+/, $_);
+		push(@{$field_abbrev{$parent}}, $abbrev);
+		$field_info{$abbrev} = [ $name, $type, $blurb ];
+	}
+}
+
+# if there was no input on stdin, bail out
+if ($record_type ne 'P' and $record_type ne 'F') {
+	exit;
+}
+
+$template = shift(@ARGV);
+
+open(TEMPLATE, $template) || die "Can't open $template for reading: $!\n";
+
+while (<TEMPLATE>) {
+	if (/=insert_dfilter_table/) {
+		&create_dfilter_table;
+	}
+	else {
+		print;
+	}
+}
+
+close(TEMPLATE) || die "Can't close $template: $!\n";
+
+sub create_dfilter_table {
+
+        print "<appendix id=\"AppFiltFields\"><title>Ethereal Display Filter Fields</title>\n";
+	$pn_counter = 1;
+
+	# Print each protocol
+	for $proto_name (sort keys %proto_abbrev) {
+
+		$ns_proto_name = $proto_name;
+		$ns_proto_name =~ s/\s//g;
+		$ns_proto_name =~ s/\)//g;
+		$ns_proto_name =~ s/\(//g;
+		$ns_proto_name =~ s/_//g;
+		$ns_proto_name =~ s/\+/plus/g;
+		$ns_proto_name =~ s/\//slash/g;
+		$ns_proto_name =~ s/,/comma/g;
+		$ns_proto_name =~ s/:/colon/g;
+		$ns_proto_name =~ s/'/apos/g;
+		
+		# The maximum token name length is apparently 44 characters. 
+		# That's what NAMELEN is defined as in docbook 4.1, at least.
+
+		if (length ($ns_proto_name) > 41) {  # "SID" and "TID" are prepended below
+			$ns_proto_name = sprintf ("%s%04d", substr($ns_proto_name, 0,
+				37), $pn_counter);
+			$pn_counter++;
+		}
+			
+		print "<section id=\"SID$ns_proto_name\"><title>$proto_name ($proto_abbrev{$proto_name})</title>\n\n";
+
+		print "<table id=\"TID$ns_proto_name\"><title>$proto_name ($proto_abbrev{$proto_name})</title>\n";
+		print "<tgroup cols=\"4\">\n";
+#		print "<colspec colnum=\"1\" colwidth=\"80pt\">\n";
+#		print "<colspec colnum=\"2\" colwidth=\"80pt\"\n>";
+		print "<thead>\n  <row>\n    ";
+ 		print "<entry>Field</>\n    <entry>Field Name</>\n    <entry>Type</>\n    <entry>Description</>\n\n";
+
+		print "  </row>\n</thead>\n<tbody>\n";
+
+		# If this proto has children fields, print those
+		if ($field_abbrev{$proto_abbrev{$proto_name}}) {
+
+			for $field_abbrev (sort @{$field_abbrev{$proto_abbrev{$proto_name}}}) {
+
+			    print "  <row>\n";
+			    print "    <entry>$field_abbrev</entry>\n";
+			    print "    <entry>", $field_info{$field_abbrev}[0], "</entry>\n";
+			    print "    <entry>", $ftenum_names{$field_info{$field_abbrev}[1]}, "</entry>\n";
+ 				print "    <entry>", $field_info{$field_abbrev}[2], "</>\n";
+			    print "  </row>\n\n";
+
+			}
+
+		}
+		else {
+
+		    print "  <row>\n    <entry></entry>\n    <entry></entry>\n    <entry></entry><entry></entry>\n";
+		    print "  </row>\n";
+
+		}
+
+		print "</tbody></tgroup></table>\n";
+		print "</section>\n\n";
+
+	}
+
+	print "</appendix>\n";
+
+}

docbook/dg-src/EDG_chapter_five.xml

@@ -0,0 +1,12 @@
+<!-- EDG Chapter Five -->
+<chapter id="Chap05">
+<title>Functions available to dissector writers</title>
+<section>
+<title>Groups 1</title>
+<para>
+<application>Ethereal</application> is perhaps one of blah blah...
+</para>
+</section>
+
+</chapter>
+<!-- End of EDG Chapter 5 -->

docbook/dg-src/EDG_chapter_four.xml

@@ -0,0 +1,33 @@
+<!-- EDG Chapter Four -->
+<chapter id="Chap04">
+<title>Writing a new dissector by example</title>
+<section>
+<title>Introduction</title>
+<para>
+<application>Ethereal</application> is perhaps one of blah blah...
+</para>
+</section>
+
+<section>
+<title>Producing the code</title>
+<para>Another para</para>
+</section>
+
+<section>
+<title>The files you have to create and modify</title>
+<para>A para</para>
+</section>
+
+<section>
+<title>Running autoconf.sh</title>
+<para>A para</para>
+</section>
+
+<section>
+<title>Contributing your new dissector</title>
+<para>A para</para>
+</section>
+
+</chapter>
+<!-- End of EDG Chapter 4 -->
+

docbook/dg-src/EDG_chapter_one.xml

@@ -0,0 +1,39 @@
+<!-- EDG Chapter One -->
+<chapter id="Chap01">
+<title>Introduction</title>
+  <!-- Introduction -->
+<section>
+<title>What is <application>Ethereal?</application></title>
+<para>
+<application>Ethereal</application> is perhaps one of blah blah...
+</para>
+</section>
+
+<section>
+<title>A rose by any other name</title>
+<para>One more</para>
+</section>
+
+<section>
+<title>A brief history of Ethereal</title>
+<para>One para</para>
+</section>
+
+<section>
+<title>Platforms Ethereal runs on</title>
+<para>One para</para>
+
+</section>
+
+<section>
+<title>Where to get Ethereal</title>
+<para>Another para</para>
+</section>
+
+<section>
+<title>Where to get the latest copy of this document</title>
+<para>Another para</para>
+</section>
+
+</chapter>
+<!-- End of EDG Chapter 1 -->

docbook/dg-src/EDG_chapter_three.xml

@@ -0,0 +1,34 @@
+<!-- EDG Chapter Three -->
+<chapter id="Chap03">
+<title>How Ethereal works</title>
+<section>
+<title>Introduction</title>
+<para>
+<application>Ethereal</application> is perhaps one of blah blah...
+</para>
+</section>
+
+<section>
+<title>Capturing packets</title>
+<!-- Including Windows versions -->
+<para>Another para</para>
+</section>
+
+<section>
+<title>Passes across the data</title>
+<para>Another para</para>
+</section>
+
+<section>
+<title>Calling the dissection routines</title>
+<para>Another para</para>
+
+</section>
+
+<section>
+<title>Parameters passed</title>
+<para>Another para</para>
+</section>
+
+</chapter>
+<!-- End of EDG Chapter 3 -->

docbook/dg-src/EDG_chapter_two.xml

@@ -0,0 +1,33 @@
+<!-- EDG Chapter Two -->
+<chapter id="Chap02">
+<title>What is packet sniffing</title>
+<section>
+<title>Introduction</title>
+<para>
+<application>Ethereal</application> is perhaps one of blah blah...
+</para>
+</section>
+
+<section>
+<title>tcpdump, libpcap and other tools</title>
+<para>A para here</para>
+</section>
+
+<section>
+<title>The structure of packets</title>
+<para>Another para</para>
+</section>
+
+<section>
+<title>How a packet's payload is handled</title>
+<para>Another para</para>
+
+</section>
+
+<section>
+<title>An introduction to wiretap</title>
+<para>Another para</para>
+</section>
+
+</chapter>
+<!-- End of EDG Chapter 2 -->

docbook/dg-src/EDG_meta_info.xml

@@ -0,0 +1,19 @@
+<bookinfo>
+  <title>&DocumentTitle;</title>
+  <subtitle>&DocumentSubTitle;</subtitle>
+  <authorgroup>
+    <author><firstname>&AuthorFirstName;</firstname><surname>&AuthorSurname;</surname>
+      <affiliation><orgname>&AuthorOrgName;</orgname></affiliation>
+    </author>
+  </authorgroup>
+  <edition>&DocumentEdition;</edition>
+  <pubdate>&DocumentPubDate;</pubdate>
+  <copyright><year>&DocumentCopyrightYear;</year>
+    <holder>&DocumentCopyrightHolder;</holder>
+  </copyright>
+
+<legalnotice>
+  &DocumentLegalNotice;
+</legalnotice>
+
+</bookinfo>

docbook/ethereal-doc.txt

@@ -0,0 +1,93 @@
+ETHEREAL USER'S GUIDE OUTLINE
+
+Chapter 1.0 Introduction
+  - What is Ethereal
+  - A rose by any other name
+  - A brief history of Ethereal
+  - Platforms Ethereal runs on
+  - Where to get Ethereal
+
+Chapter 2.0 Building and Installing Ethereal
+  - Obtaining the source and binary distributions
+  - Before you build Ethereal
+  - Building the source
+  - Installing the binaries
+  - Installing from RPMs
+
+Chapter 3.0 Using Ethereal
+  - Starting Ethereal
+  - Capturing packets
+  - Filtering during capturing
+  - Viewing packets
+  - Viewing packets while you capture
+  - Saving captures
+  - Reading captures from other tools
+  - Filtering packets while viewing
+
+Chapter 4.0 Troubleshooting with Ethereal
+
+  - An approach to troubleshooting with Ethereal
+  - Examples of troubleshooting
+
+Chapter 5.0 Miscellaneous topics
+
+  - Capturing with tcpdump for viewing with Ethereal
+  - Using editpcap
+  - Other tools
+
+Glossary
+
+Index
+
+ETHEREAL DEVELOPERS GUIDE OUTLINE
+
+1.0 Introduction
+ 
+  - What is Ethereal
+  - A rose by any other name
+  - A brief history of Ethereal
+  - Platforms Ethereal runs on
+  - Where to get Ethereal
+ 
+2.0 What is packet sniffing
+
+  - The use of libpcap and other capture tools
+  - The structure of packets
+  - How a packet's payload is handled
+  - An introduction to wiretap
+
+3.0 An outline of what Ethereal does
+
+  - Capturing packets
+  - Passes across the data
+  - Calling the dissection routines
+  - Parameters passed
+
+4.0 Writing a new dissector by example
+
+  - The basics of writing a dissector
+  - Producing the code
+  - The files you have to produce and modify
+  - Running autoconf.sh
+  - The final product
+  - Contributing your new dissector
+
+5.0 Functions avalailable to dissector writers
+
+  - All the relevant functions
+
+6.0 A list of all the existing dissectors
+
+  - A list of all the dissectors
+
+Glossary
+
+Index
+
+Regards
+-------
+Richard Sharpe, sharpe@ns.aus.com
+Samba (Team member, www.samba.org), Ethereal (Team member, www.zing.org)
+ 
+
+