Wireshark · Ethereal-dev: Re: [Ethereal-dev] No further comments on the "User's guide" preview?!?

[Ulf Lamping <ulf.lamping@xxxxxx>]

Guy Harris wrote:

>
> P. xiv:
>
>     Should "backtrace" have the normal weight rather than being boldface?
It has normal weight now.
>
>     In the acknowledgments at the bottom, "derived" should be "is 
derived".
changed

>
> P. xvii:
>
>     Should the e-mail address be followed by a "change [AT] to @, 
unless you can find all the e-mail sellers of cable TV descramblers, 
penis enlargement pills, etc. and get them to stop, so we don't have to 
put [AT] in there"?
I would think the people using Ethereal will know what we mean.

>
> P. 1:
>
>     "Network packet sniffer" should probably be "network packet 
analyzer" - I don't know whether the newly-created Network General will 
be as litigious as I think Network Associates were about stopping other 
people from using their trademark word "Sniffer(TM)", but we might want 
to avoid using it in any case.
I replaced (hopefully any) appearances of sniffer by analyzer.

>
>     "network aministrators" should be "network administrators".
Obviously :-)
>
> P. 2:
>
>     In 1.1.6, GPL stands for "General Public License" (or "GNU 
General Public License", although that'd presumably be GGPL), and "fees" 
shouldn't have an apostrophe in it.
Changed both.
>
> P. 3:
>
>     The first item about Ethereal not being an IDS should read
>
>         Ethereal 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, Ethereal might 
help you figure out what is really going on.
Changed
>
>     "DNS name resolution" should just be "name resolution" - if 
you're not using GNU ADNS, the OS's native name resolution software 
might also be sending packets over the network for NIS or NBNS name 
resolution.
changed
>
> P. 4:
>
>     "GLIB" should be "GLib".
changed
>
>     "Apple MAC OS X" should be "Apple Mac OS X".
changed.
BTW: is BeOS unix based or a completely different thing?
>
>     Also, if the BSDs (including OS X) count as "Unix", one could 
argue that the Linux distributions in 1.2.2 count as well; none of them 
have been certified as passing any of the UNIX conformance suites, and 
they have only slightly more AT&T-derived code in them than Linux 
distributions do at this point.
Do we want to put them under a new section BSD?
>
> P. 5:
>
>     "Windows ME" should be "Windows Me", and "NT" should be "NT 4.0" 
(just in case somebody's still running NT 3.x).
changed both
>
> P. 7:
>
>     The FAQ gives the official pronounciation as "e-the-real".
I've added this, please review.

>
> P. 8:
>
>     "Guy Harris, of NetApp" should be "Guy Harris of Network 
Appliance", and "TCPview" should probably just be "tcpview".
changed both
>
>     Or, at this point, we might want to leave out everybody but 
Gerald, as even if we only mention the *major* contributors, that 
history would get a bit long.
I think it's ok to describe the beginning of the project the way it is. 
I find it interesting to read :-)
>
> P. 9:
>
>     "GPL" is, as per the above, the GNU General Public License.
changed
>
>     The first bulleted list item needs a period at the end.
changed
>
> P. 10:
>
>     The mailing list names should probably be given as 
"Ethereal-announce", "Ethereal-users", and "Ethereal-dev".
I changed it to something like "ethereal-announce", as that seems to be 
the "official" name.
>
>     "dependant libraries" should be "dependent libraries".
changed
>
> P. 13:
>
>     "Linux Distributions" should be "Linux distributions", and "eg" 
should be "e.g.".
changed both
>
> P. 15:
>
>     If we use GTK 1.2[.x] in the example, we should probably use 
1.2.10, as that was the last 1.2[.x] release.
changed
BTW: this chapter needs to be reworked, like adding GTK 2.x explanations
>
> P. 20:
>
>     The Ethereal RPM name should probably be updated to the name of 
the current RPM for 0.10.5.
updated to ethereal-0.10.5-0.2.2.i386.rpm which seems to be the latest 
official RedHat
>
>     "deb's" should be "debs".
Hmm, that looks strange, I keep it as it is.
>
> P. 21:
>
>     The sentence about an antiquated "sed" should probably be
>
>         ... This is likely to be caused by an antiquated sed (such as 
the one shipped with Solaris). ...
changed
>
> P. 23:
>
>     The URL for WinPcap should be
>
>         http://winpcap.polito.it/install/Default.htm
changed
>
>     and the list of OSes should be "9x/Me/NT/2000/XP/2003 Server".
the currently released WinPCap version 3.0 does *not* support 2003 Server!
>
> P. 25:
>
>     "How the Ethereal user interface work" should be "How the 
Ethereal user interface works".
changed
>
> P. 29:
>
>     Should the Control key's name in languages other than English and 
German be given (if in other languages it's given a different name)?
I don't know any other than the English and German, do you :-)
>
> P. 30:
>
>     Is the blank line at the top of the "Description" field for each 
menu item supposed to be there?
I'm unsure why it's there. That seems to be a bug in the pdf conversion, 
the HTML version doesn't show that behaviour :-(
>
> P. 31:
>
>     "ascii" should be "ASCII", and "postscript" should be "PostScript".
changed both
>
> P. 41:
>
>     "ethereal" should be "Ethereal".
changed both appearances
>
> P. 43:
>
>     "obsoleted be" should be "obsoleted by".
changed
>
> P. 44:
>
>     "webbrowser" should be "Web browser".
changed
>
>     "like the plugins, ..." should be "such as the plugins, ...".
changed
>
> PP. 29-44:
>
>     Some menu item descriptions say "This menu item does XXX", and 
others say just "Do XXX"; they should probably be consistent - I'd vote 
for "Do XXX".
I would agree, but didn't changed anything.

>
>     The same should probably be done for toolbar buttons.
yes
>
> P. 48:
>
>     "enter key" should probably be "Enter key" - or "Enter or Return 
key"; the keyboard on which I'm typing this has "Return" (or, rather, 
"return") on the main keyboard and "Enter" (or, rather, "enter") on the 
numeric keypad.
changed it to "Enter/Return key"
>
> P. 49:
>
>     "it's data" should be "its data".
changed
>
> P. 50:
>
>     In the section on "Links", "If clicked" should be "If 
double-clicked".
changed
>
> P. 52: "it's" should be "its" in the section on the statusbar with a 
loaded capture file.
changed
>
> P. 56:
>
>     The link-layer header type description should probably be 
something such as
>
>         If you are capturing on an 802.11 device on some versions of 
BSD, this might offer a choice of "Ethernet" or "802.11".  "Ethernet" 
will cause the captured packets to have fake Ethernet headers; "802.11" 
will cause them to have IEEE 802.11 headers.  Unless the capture needs 
to be read by an application that doesn't support 802.11 headers, you 
should select "802.11".
>
>         If you are capturing on an Endace DAG card connected to a 
synchronous serial line, this might offer a choice of "PPP over serial" 
or "Cisco HDLC"; if the protocol on the serial line is PPP, select "PPP 
over serial", and if the protocol on the serial line is Cisco HDLC, 
select "Cisco HDLC".
>
>     If you are capturing on an Endace DAG card connected to an ATM 
network, this might offer a choide of "RFC 1483 IP-over-ATM" or "Sun raw 
ATM".  If the only traffic being captured is RFC 1483 LLC-encapsulated 
IP, or if the capture needs to be read by an application that doesn't 
support SunATM headers, select "RFC 1483 IP-over-ATM", otherwise select 
"Sun raw ATM".
>
>         If you are capturing on an Ethernet device, this might offer 
a choice of "Ethernet" or "DOCSIS".  If you are capturing traffic from a 
Cisco Cable Modem Termination System that is putting DOCSIS traffic onto 
the Ethernet to be captured, select "DOCSIS", otherwise select "Ethernet".

I think this is too long and won't be a good description what it's for 
(I still just don't understand it completely). If we want to have it 
that detailed (which might be really a good idea), we might want to put 
this into a new section and put a link to it?

>
>     The space after the "(" in the section on promiscuous mode should 
be removed, and "going by your interface" should probably be "on your 
LAN segment".
changed both
>
>     "promiscous" should be "promiscuous" in the note.
changed
>
>     Another note should perhaps tell people that even in promiscuous 
mode they *still* won't necessarily see all packets on their LAN 
segment, and refer them to
>
>         http://www.ethereal.com/faq#promiscsniff
>
I've added a note

>     The section on the snapshot length should perhaps discuss why you 
would want a smaller snapshot length (less CPU time spent copying 
packets, less buffer space required, so perhaps fewer packets dropped if 
traffic is heavy) and why you would not want a smaller snapshot length 
(you don't get all the packet data, and the stuff you want might be in 
the part that's dropped, or reassembly might not be done).
I've added similar, please review
>
>     The section on the capture file name field should perhaps note 
that the capture will be stored in a temporary file if that field is 
left blank - in some sense, that's the default; "There is no default for 
this value" might make people think they're *required* to specify a file 
name.
I've added similar, please review
>
>     "button right to this field" should be "button to the right of 
this field".
changed
>
> P. 57:
>
>     "ringbuffer" should be "ring buffer".
changed
>
>     "after the given number of ... were captured" should probably be 
"... have been captured", and "expired" should probably be "have 
expired" or "have elapsed".
changed
>
> P. 59:
>
>     "If the establishing phase is saved in one file and the things 
you would like to see is in another, so you might not see some of the 
valuable context related information." should probably be "If the 
establishing phase is saved in one file and the things you would like to 
see is in another, you might not see some of the valuable context 
related information.", without the "so".
removed
>
>     "'Single file named' mode" should be "'Single named file' mode".
changed
>
>     "ringbuffer" should be "ring buffer".
changed
>
> P. 61:
>
>     Would the reference in the first sentence to Kipling's poem be 
considered offensive by Indian readers (or mysterious to those not 
familiar with his poem)?

Well, "or mysterious to those not familiar with his poem" might be true 
for a lot of people (like me). I've replaced it by a more general 
sentence, please review.
>
> P. 63:
>
>     Would the comma in the percentages confuse people in the 
English-speaking world (or other locales where "." rather than "," is 
used to separate the integral and fractional part of a number)?
I don't think so. I would think people using Ethereal will know how to 
interpret this.
>
> P. 67:
>
>     The note about drag and drop should probably say "In some desktop 
environments, you can also use drag-and-drop" - it works in Windows and 
KDE 3.x, at least, but it doesn't work in OS X (OS X's X11 currently 
doesn't support the Xdnd protocol so you can't drag-and-drop between X11 
and Aqua applications; I've filed an RFE on that), and I haven't tried 
it in GNOME or any of the other UNIX+X desktop environments.
I've put the sentence about dnd into a note and also added that it's not 
available on all desktop environments. please review.
>
>     "disabled by preferences" should perhaps be "disabled in the 
preferences".
changed
>
>     "it's native file format libpcap" should probably be "its native 
file format (libpcap format, also used by tcpdump/WinDump and other 
libpcap/WinPcap-based programs)", fixing a typo and explaining a little 
better what "libpcap format" is.
changed
>
>     The note on the open dialog should probably be
>
>         Ethereal uses the open dialog box from the version of the 
GTK+ toolkit that it's using.  This dialog was completely redesigned in 
GTK+ version 2.4.  As not all operating systems that supply GTK+ with 
the operating system have updated the version of GTK+ they're using, and 
as you might not have built Ethereal with GTK+ 2.4, your dialog box 
might look different.  However, as the functionality remains almost the 
same, much of this description will work with your version of Ethereal.
As on win32 the GTK libs are installed by Ethereal, I've changed to a 
slightly different text, please review
>
>     The "+ Add" button, if you've selected a directory in the 
right-hand pane, allows you to add it to the list (I'm not sure what 
that list is called - "favorites", or something else)?
please review
>
>     The "- Remove" button, if you've selected a directory in the 
list, allows you to remove it from the list.  (The items above the line, 
"Home", "Desktop", and "Filesystem", cannot be removed.)
please review
>
>     Those changes are persistent.  (At least on UN*X, they appear to 
be stored in ~/.gtk-bookmarks, so perhaps they're called "bookmarks".)
please review
>
> P. 70:
>
>     The note on the save dialog should probably be changed along the 
lines of the changes to the open dialog.
changed
>
> P. 74:
>
>     "Postscript" and "postscript" should be "PostScript".
changed
>
> P. 79:
>
>     See previous item.
changed
>
> P. 80:
>
>     It should probably note that, on Windows, you'll get a second, 
Windows-style, print dialog if you're not printing to a file.
maybe at the next release, as we should also provide a screenshot.
>
> P. 81:
>
>     "(including)" should probably be "(inclusive)".
changed
>
> P. 82:
>
>     "output of the packet bytes" should probably be "output of the 
packet bytes, just as in the "Packet Bytes" pane".
changed
>
>     The section on "each packet on a new page" should probably be 
"put each packet on a separate page (when saving to a text file, this 
will put a form feed character between the packets)".
changed to something similar
>
> P. 84:
>
>     The plus sign isn't necessarily a plus sign - I think it's a 
rotating triangle by default in GTK+ 2.x (once again, imitating Aqua).
I think it's depending on the theme you use, which can vary a lot of things.
>
> P. 85:
>
>     The "Item" column probably shouldn't be right-justified - it 
leaves a lot of space between "Follow" and "TCP".
it's not justified by me at all
>
>     The description of "Go to Corresponding Packet" should probably 
say "If the selected field has a packet number in it, go to it.  The 
corresponding packet will often be a response to this packet if it's a 
request, or the request for which this packet is a reply if it's a 
reply, or something such as that."
please review
>
> P. 91:
>
>     "All filter expressions are entered in lowercase" should be "all 
protocol and field names are entered in lowercase" (assuming nobody's 
added any mixed-case field names).
That only complicates the text without adding additional information IMHO.
>
> P. 92:
>
>     "it's content" should be "its content".
changed
>
> P. 96:
>
>     The extra spaces after "(" and before ")" should be removed.
changed
>
>     "ie a Value to match" should be "i.e., a Value to match".
replaced with e.g.
>
>     "like the equality relation" should be "such as the equality 
relation".
changed
>
> P. 102:
>
>     The note should be "As these protocols now work like links (just 
as in your Web browser), it's easier to simply double-click on the field 
to jump to the corresponding packet."  (It should perhaps also note that 
they don't work *exactly* like links in a Web browser, as you have to 
double-click.)
please review
>
> P. 103:
>
>     The warning should be just one sentence, with a comma separating 
the two clauses.
changed
>
> P. 110:
>
>     "stream based" should be "stream-based".
changed
>
>     "hexdump" should be "hex dump" - and "Uncompressed entity body" 
probably isn't the name it'll have unless the entity was sent over the 
wire compressed, and even then the reassembled data will be in a tab 
labeled "Desegmented TCP".
changed hex dump
It was from a real life example I've seen, and they are only examples
>
> P. 111:
>
>     The second note should be one sentence, with a comma separating 
the two clauses.
changed
>
>     In section 7.4.2, another problem might be addresses for which 
there's no DNS entry on machines that don't support NetBIOS-over-TCP, if 
you're running Ethereal on Windows - NBNS address resolution is done by 
sending an NBNS packet to the IP address in question, and if that 
machine doesn't support NetBIOS-over-TCP, it won't respond.  Using ADNS 
would help there - because it means no NBNS name resolution will be 
done, so some IP addresses might not get resolved.
I don't know how to write this down, and if it's that important.
>
>     In 7.4.3, "it's" should be "its".
changed
>
>     In 7.4.4, "freezed" should be "frozen".
changed
>
> P. 115:
>
>     "informations" should be "information".
changed
>
> P. 116:
>
>     "this protocols name" should be "this protocol's name".
changed
>
>     "absolute amount" should be "absolute number".
changed four times
>
> P. 117:
>
>     "IP have 99,17%" should be "IP has 99,17%" (or 99.17%, in 
English-speaking locales).
changed to has, the dot should be corresponding to the screenshot
>
> P. 118:
>
>     "it's IP address" should be "its IP address".
changed
>
>     "seperately" should be "separately".
changed
>
>     FDDI and Token Ring are identical to Ethernet here (the endpoint 
is the MAC address).
changed
>
>     The items for TCP and UDP should be one sentence, with a comma 
separating the two clauses.
changed
>
> P. 119, P. 120:
>
>     "each of it's pages" should be "each of its pages".
changed
>