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.

Date Index Thread Index Other Months All Mailing Lists
Date Prev Date Next Thread Prev Thread Next
From: Ulf Lamping <ulf.lamping@xxxxxx>
Date: Fri, 30 Jul 2004 19:11:13 +0200
Guy Harris wrote:


Ulf Lamping said:

BTW: is BeOS unix based or a completely different thing?


Different.  It is (was?) somewhat *influenced* by Unix, but it's not a
Unix-compatible OS.


Do we need to have a section others with only BeOS in it?


>     The FAQ gives the official pronounciation as "e-the-real".
I've added this, please review.


My in-house editor (who's done technical publications editing for Novell
and is now an editor at Network Appliance) would probably say it should be

   You are welcome to call it what you like, as long as you find it
useful.  The FAQ gives the official pronounciation as "e-the-real".

as that was her response to another case of a comma separating independent
clauses in a sentence - split the sentence into two sentences.


changed.
BTW: you often put two spaces at the start of a sentence, is there a reason for it? 


>     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 :-)


...although it fails to give credit to a number of developers who've
contributed a lot to the project, including you. :-)


Thanks :-)


>     "dependant libraries" should be "dependent libraries".
changed


There's one other occurrence of "dependant", in the paragraph at the end
of page 69.


oops, changed


> P. 13:


In the second paragraph, "ethereal" should be "Ethereal" in the first
sentence.
I've found some other appearances in this section, but didn't looked at the other sections. 


> P. 15:


libpcap-0.5 should probably be changed to libpcap-0.8.3, as that's the
current version.


changed
Is the cd libpcap_0_8_3 in the next line correct then?


>     "deb's" should be "debs".
Hmm, that looks strange, I keep it as it is.


A Google for

   debs apt-get

found 15,100 pages, a Google for

   deb's apt-get

found 2,220.

I'm not sure wheether there's an official standard - the first Google also
found "DEBs", although "DEB" isn't an acronym (it's short for "Deborah",
as in "Deborah and Ian") so it probably shouldn't be all-caps.  The main
Debian page just has a link to "Debian Packages".
What about "Installing using a .rpm file ..." and "Installing using a .deb file..."? 


> 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 :-(


How is the PDF generated?  Is there a DocBook-to-PDF translator used, or
is there some intermediate step?

There is an intermediate step, please have a look at docbook/Readme.txt


> P. 43:
>
>     "obsoleted be" should be "obsoleted by".
changed


There's another one in the description of "Endpoint List".


changed


> P. 49:
>
>     "it's data" should be "its data".
changed


Some others:

P. 2 - "Unlike it's name suggests, Ethereal can capture traffic from some
other network media than Ethernet too." should probably be "Although its
name might suggest that it captures only on Ethernet, Ethereal can capture
traffic from some other network media as well."

changed


P. 49: "the IP dissector will overwrite this by it's own" should be
"...its own".

changed


P. 138: "Each protocol has it's own dissector" should be "Each protocol
has its own dissector".

changed

Obviously, that was teached in the english lesson I've missed at school :-(


> P. 56:
>
>     The link-layer header type description should probably be
> something such as


...


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).


Part of the problem is that the mechanism in libpcap that this uses was
originally added for one purpose, but is useful for other purposes as
well, and was used for that.

The original purpose was to handle support 802.11 headers; I think it was
added so that applications that don't understand 802.11 headers wouldn't
have to be changed if support for them was added to BPF (the underlying
feature that libpcap uses for that is a BSD BPF feature, currently
supported in FreeBSD 5.2 and later and NetBSD 2.0-beta).  Ethereal should
probably check whether a device offers both Ethernet and 802.11 headers
and, if so, default to 802.11 headers (although capture filters
*currently* can't handle packets with 4 MAC addresses in 802.11 headers; I
hope to find time to fix that before the next libpcap release).

However, it also turned out to be useful for people trying to capture
DOCSIS traffic from the Cisco cable modem hardware in question, which uses
an Ethernet as a bit pipe, encapsulating DOCSIS frames inside low-level
Ethernet framing, so that the packets don't have an Ethernet header.  This
lets you capture that traffic but have it marked as a DOCSIS capture, so
that you don't have to set the Ethereal "treat all traffic as DOCSIS"
dissector preference in order to read the capture file correctly.  That's
in the current main-branch libpcap, but not yet in any release.

It then also turned out to be useful for passive capturing on synchronous
serial lines.  If you're capturing serial line traffic to or from your
machine, the OS knows the encapsulation being used, so that libpcap can
find out from the OS whether it's PPP, Cisco HDLC, etc..  However, if
you're doing a passive capture, you'd have to tell it - there are settings
in Sniffer, for example, for that - so that was also done using that
libpcap feature.


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?


We could do that.


I've done that, please review.


>     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


I'd either remove the "The value should be at least the MTU for the
interface you're capturing on", as the whole point of a short snapshot
length is *not* to capture all of the packet data, or say "If you want to
capture all of the data in each packet, the value should be...", but if
you want to capture all of the data in each packet, you should just
disable that field.

Sounds reasonable, I've removed that sentence


I'd make the second and third rules be

   If you don't need all of the data in a packet - for example, if you
only need the link-layer, IP, and TCP headers - you might want to
choose a smal snapshot length, as less CPU time is required for
copying packets, less buffer space is required for packets, and thus
perhaps fewer packets will be dropped if traffic is very heavy.

   If you don't capture all of the data in a packet, you might find that
the packet data you want is in the part that's dropped, or that
reassembly isn't possible as the data required for reassembly is
missing.


I've replaced the two paragraphs


> P. 57:
>     "after the given number of ... were captured" should probably be
"... have been captured", and "expired" should probably be "have
expired" or "have elapsed".
changed


The ones in section 4.2.2 "Capture File(s) frame" should also be changed.


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).


   http://www.lockstockandbarrel.org/Poems/Kipling/gunga_din.html


I've replaced it by a more general sentence, please review.


It looks good, although "to some extend" should be "to some extent".


changed


> P. 67:
I've put the sentence about dnd into a note and also added that it's not
available on all desktop environments. please review.



>     The note on the open dialog should probably be


  ...


As on win32 the GTK libs are installed by Ethereal, I've changed to a
slightly different text, please review


It looks good, although "might be looking different" should be "might look
different".

changed


> P. 70:
>
>     The note on the save dialog should probably be changed along the
lines of the changes to the open dialog.
changed


Again, "be looking different" should be "look different".


yes, sometimes grep is your friend :-)


> P. 82:
>
>     "output of the packet bytes" should probably be "output of the
packet bytes, just as in the "Packet Bytes" pane".
changed


"just like in the "Packet List" pane" should probably also be "just as
in...".


changed


> 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.


My concern was that somebody looking for, for example, an HTTP GET request
might think that even strings in the expression would have to be entered
in lower-case.

changed
Now I understand where the problems is. If you have to input comparison strings, that sentence is just not true. 


P. 97:

"*not*" should probably be italicized, rather than put in asterisks.


changed, I've boldify it


>     "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


But the "Uncompressed entity body" tab doesn't come from reassembly - if
reassembly is done in that case, the tab with the reassembled data would
be "Desegmented TCP".  The "Uncompressed entity body" tab would come from
uncompression, which could happen even if no reassembly was done.
We might need to have a section about uncompression as well then. Could you give me some input, when it's the case and how its working. 


P. 114:

In the warning, "ethereal" should be "Ethereal".


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.


The NBNS problem is probably very often the cause of Ethereal "hangs" on
Windows.

Also, that warning says "your DNS server" - the problem is that it's not
just your DNS server, it's whatever DNS servers are needed to resolve a
name, so you might have a problem even if your DNS server is working
perfectly.
I've changed "DNS server" to "name server". I would think this section needs a redesign and more information about name resolution at all. It should tell which services are used by Ethereal and such. But this should be done in the next release. 


> P. 115:
>
>     "informations" should be "information".
changed


Some other places where that needs to be fixed:

P. 11: "the informations mentioned".

changed


P. 49: "Ethereal will place informations".

changed


P. 59: "these informations only for the loaded files".

changed


>     "seperately" should be "separately".
changed


One more place where that should be fixed - P. 114, "en-/disabled
seperately".

changed (at some other places too, as grep is my friend :-)