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

Note: This archive is from the project's previous web site, ethereal.com. This list is no longer active.

From: Ulf Lamping <[email protected]>
Date: Thu, 29 Jul 2004 20:55:36 +0200
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
>