Wireshark · Ethereal-dev: [Ethereal-dev] [RFD] Convert man pages to docbook

[Brad Hards <bhards@xxxxxxxxxxxxxx>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Currently the man pages are in POD "source", and are converted.

I'd like to convert them to DocBook for two reasons:
1. I think it is a technically superior format, and is more widely used.
2. It'd make it easier to keep the manual page, and the places that have 
equivalent data, the same. 

I'm working on some documentation, and I'd like to provide the man pages as 
reference annexes. The current stuff in the manual is way out of date. The 
manual is in Docbook, and it'd be much easier to just convert the man pages 
to Docbook, and then use them as a single source. As an intial example of the 
quality that we can expect, see the attached docbook source, and generated 
man page. Note that the content isn't meant to reflect final content - this 
is just an indication of formatting quality.

Of course, changing to Docbook implies that whoever does the updates needs to 
understand docbook. And while docbook is quite widely used, what matters is 
the specifics of this project.

Assuming that I can convert the current documentation over to docbook, how do 
the developers feel about needing docbook experience and toolchain instead of 
POD?

Brad
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)

iD8DBQE/Atg2W6pHgIdAuOMRAoGhAKCG2uDvryaulaXiKOhK1TKpAtxyuQCdHM0c
smNQiRMbhTLPiAiZqCcft9k=
=Hh02
-----END PGP SIGNATURE-----

Attachment: editcap.1
Description: Troff document

<refmeta>
  <refentrytitle>editcap</refentrytitle>
  <manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
  <refname>editcap</refname>
  <refpurpose>Edit and reformat network capture files</refpurpose>
</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>
  <command>editcap</command>
	<arg>-r</arg>
	<arg>-h</arg>
	<arg>-v</arg>
	<arg>-T <replaceable>encap type</replaceable></arg>
	<arg>-F <replaceable>capture type</replaceable></arg>
        <arg>-s <replaceable>snaplen</replaceable></arg>
        <arg>-t <replaceable>time adjustment</replaceable></arg>
	<arg choice=req><replaceable>infile</replaceable></arg> 
	<arg choice=req><replaceable>outfile</replaceable></arg> 
	<arg>record#<arg>-</arg><arg>record#</arg> ... </arg>

</cmdsynopsis>

</refsynopsisdiv>


<refsect1><title>Description</title>
<para>
Included with Ethereal is a small utility called 
<command>editcap</command>, which is a command-line utility for 
working with capture files.  Its main function is to remove 
packets from capture file, but it can also be used to convert 
capture files from one format to another, as well as print 
information about capture files.
</para>
<para>
<command>editcap</command> has the following format:
Where each option has the following meaning:
      <variablelist>
	<varlistentry><term><command>-r</command></term>
	  <listitem>
	    <para>
	      Causes the packets whose packet numbers are specified on
the command line to be written to the output capture file, and no
other packets to be written to the output capture file.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry><term><command>-h</command></term>
	  <listitem><para>Prints the version and options and exits.</para></listitem>
	</varlistentry>
	<varlistentry><term><command>-v</command></term>
	  <listitem>
	    <para>
	      This option specifies verbose operation.  The default is 
	      silent operation.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry><term><command>-s {snaplen}</command></term>
	  <listitem>
	    <para>
	    Sets the snapshot length to use when writing the data
            </para>
	  </listitem>
	</varlistentry>
	<varlistentry><term><command>-t {time adjustment}</command></term>
	  <listitem>
	    <para>
	    Sets the time adjustment to use on selected frames.
            </para>
	  </listitem>
	</varlistentry>
	<varlistentry><term><command>-T {encap type}</command></term>
	  <listitem>
	    <para>
	      This option specifies the frame encapsulation type to use. 
	      It can take one of the following values:
	      <itemizedlist>
		<listitem><para>ether - Ethernet</para></listitem>
		<listitem><para>tr - Token Ring</para></listitem>
		<listitem><para>slip - SLIP</para></listitem>
		<listitem><para>ppp - PPP</para></listitem>
		<listitem><para>fddi - FDDI</para></listitem>
		<listitem>
		  <para>
		    fddi-swapped - FDDI with bit-swapped MAC addresses
		  </para>
		</listitem>
		<listitem><para>rawip - Raw IP</para></listitem>
		<listitem><para>arcnet - ARCNET</para></listitem>
		<listitem><para>atm-rfc1483 - RFC 1483 ATM</para></listitem>
		<listitem>
		  <para>linux-atm-clip - Linux ATM CLIP</para>
		</listitem>
		<listitem><para>lapb - LAPB</para></listitem>
		<listitem><para>atm-pdus - ATM PDUs</para></listitem>
		<listitem><para>atm-pdus-untruncated - ATM PDUs - untruncated
</para></listitem>
		<listitem><para>null - NULL</para></listitem>
		<listitem>
		  <para>ascend - Lucent/Ascend access equipment</para>
		</listitem>
		<listitem><para>isdn - IDSN</para></listitem>
		<listitem><para>ip-over-fc - RFC 2625 IP-over-Fibre Channel</para></listitem>
		<listitem><para>ppp-with-direction - PPP with Directional Info</para></listitem>
		<listitem><para>ieee-802-11 - IEEE 802.11 Wireless LAN</para></listitem>
		<listitem><para>ieee-802-11-radio - IEEE 802.11 Wireless LAN with radio information</para></listitem>
		<listitem><para>linux-sll - Linux cooked-mode capture</para></listitem>
		<listitem><para>frelay - Frame Relay</para></listitem>
		<listitem><para>frelay-with-direction - Frame Relay with Directional Info</para></listitem>
		<listitem><para>chdlc - Cisco HDLC</para></listitem>
		<listitem><para>ios - Cisco IOS internal</para></listitem>
		<listitem><para>ltalk - Localtalk</para></listitem>
		<listitem><para>prism - IEEE 802.11 plus Prism II monitor mode header
</para></listitem>
		<listitem><para>pflog - OpenBSD PF Firewall logs</para></listitem>
		<listitem><para>hhdlc - HiPath HDLC</para></listitem>
		<listitem><para>docsis - Data Over Cable Service Interface Specification</para></listitem>
		<listitem><para>cosine - CoSine L2 debug log</para></listitem>
		<listitem><para>wlan - IEEE 802.11 plus AVS WLAN monitor header</para></listitem>
		<listitem><para>whdlc - Wellfleet HDLC</para></listitem>
		<listitem><para>sdlc - SDLC</para></listitem>
		<listitem><para>tzsp - Tazmen sniffer protocol</para></listitem>
	      </itemizedlist>
	      It is mainly for converting foreign captures to something 
	      that Ethereal can deal with.  The default frame 
	      encapsulation type is the same as the input encapsulation. 
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry><term><command>-F {capture type}</command></term>
	  <listitem>
	    <para>
	      This option specifies the capture file format to write 
	      the output file in.  You can choose from the following values:
	      <itemizedlist>
		<listitem>
		  <para>libpcap - libpcap (tcpdump, Ethereal, etc.)</para>
		</listitem>
		<listitem>
		  <para>modlibpcap - modified libpcap (tcpdump)</para>
		</listitem>
		<listitem>
		  <para>
		    rh6_1libpcap - Red Hat Linux 6.1 libpcap (tcpdump)
		  </para>
		</listitem>
		<listitem>
		  <para>
                     suse6_3libpcap - SuSE Linux 6.3 libpcap (tcpdump)
		  </para>
		</listitem>
		<listitem>
		  <para>
                     nokialibpcap - Nokia libpcap (tcpdump)
		  </para>
		</listitem>
		<listitem>
		  <para>
                     lanalyzer - Novell LANalyzer
		  </para>
		</listitem>
		<listitem>
		  <para>
		    ngsniffer - Network Associates Sniffer (DOS-based)
		  </para>
		</listitem>
		<listitem><para>snoop - Sun snoop</para></listitem>
		<listitem>
		  <para>
		    netmon1 - Microsoft Network Monitor 1.x
		  </para>
		</listitem>
		<listitem>
		  <para>
		    netmon2 - Microsoft Network Monitor 2.x
		  </para>
		</listitem>
		<listitem>
		  <para>
		    ngwsniffer_1_1 - Network Associates Sniffer 
		    (Windows-based) 1.1
		  </para>
		</listitem>
		<listitem>
		  <para>
		    ngwsniffer_2_0 - Network Associates Sniffer 
		    (Windows-based) 2.x
		  </para>
		</listitem>
		<listitem>
		  <para>
                     visual - Visual Networks traffic capture
		  </para>
		</listitem>
	      </itemizedlist>
	      The default is libpcap format.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry><term><command>infile</command></term>
	  <listitem>
	    <para>
	      This parameter specifies the input file to use. It must be 
	      present.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry><term><command>outfile</command></term>
	  <listitem>
	    <para>
	      This parameter specifies the output file to use. It must 
	      be present.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><command>[record#[-][record# ...]]</command></term>
	  <listitem>
	    <para>
	      This optional parameter specifies the records to include 
	      or exclude (depending on the <command>-r</command> option). 
	      You can specify individual records or a range of records.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </para>
</refsect1>