- section reorder

- macro fixes
- kill whitespace at EOL
- new sentence, new line

1 files changed, 112 insertions, 92 deletions

diff --git a/usr.sbin/mtrace/mtrace.8 b/usr.sbin/mtrace/mtrace.8
index 975950ac93f..71850c97581 100644
--- a/usr.sbin/mtrace/mtrace.8
+++ b/usr.sbin/mtrace/mtrace.8
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mtrace.8,v 1.10 2003/06/02 23:36:54 millert Exp $
+.\"	$OpenBSD: mtrace.8,v 1.11 2003/06/12 12:59:51 jmc Exp $
 .\"	$NetBSD: mtrace.8,v 1.4 1995/12/10 10:57:11 mycroft Exp $
 .\"
 .\" Copyright (c) 1993, 1998-2001.
@@ -74,6 +74,7 @@
 .Nd print multicast path from a source to a receiver
 .Sh SYNOPSIS
 .Nm mtrace
+.Bk -words
 .Op Fl g Ar gateway
 .Op Fl i Ar if_addr
 .Op Fl l
@@ -91,6 +92,7 @@
 .Ar source
 .Op Ar receiver
 .Op Ar group
+.Ek
 .Sh DESCRIPTION
 Assessing problems in the distribution of IP multicast traffic
 can be difficult.
@@ -98,8 +100,8 @@ can be difficult.
 utilizes a tracing feature implemented in multicast routers
 .Nm ( mrouted
 version 3.3 and later) that is
-accessed via an extension to the IGMP protocol.  A trace query is
-passed hop-by-hop along the reverse path from the
+accessed via an extension to the IGMP protocol.
+A trace query is passed hop-by-hop along the reverse path from the
 .Ar receiver
 to the
 .Ar source ,
@@ -108,15 +110,17 @@ along the path, and then the response is returned to the requestor.
 .Pp
 The only required parameter is the
 .Ar source
-host name or address.  The default
+host name or address.
+The default
 .Ar receiver
 is the host running mtrace, and the default
 .Ar group
 is "MBone Audio" (224.2.0.1), which is sufficient if packet loss
-statistics for a particular multicast group are not needed.  These two
-optional parameters may be specified to test the path to some other
+statistics for a particular multicast group are not needed.
+These two optional parameters may be specified to test the path to some other
 receiver in a particular group, subject to some constraints as
-detailed below.  The two parameters can be distinguished because the
+detailed below.
+The two parameters can be distinguished because the
 .Ar receiver
 is a unicast address and the
 .Ar group
@@ -144,7 +148,7 @@ and the response destination.
 .It Fl l
 Loop indefinitely printing packet rate and loss statistics for the
 multicast path every 10 seconds (see
-.Fl S Ar stat_int Ns ).
+.Fl S Ar stat_int ) .
 .It Fl M
 Always send the response using multicast rather than attempting
 unicast first.
@@ -165,8 +169,8 @@ Set the maximum number of query attempts for any hop to
 .Ar n .
 The default is 3.
 .It Fl p
-Listen passively for multicast responses from traces initiated by
-others.  This works best when run on a multicast router.
+Listen passively for multicast responses from traces initiated by others.
+This works best when run on a multicast router.
 .It Fl r Ar host
 Send the trace response to
 .Ar host
@@ -185,7 +189,8 @@ seconds (default 10 seconds).
 Set the
 .Ar ttl
 (time-to-live, or number of hops) for multicast trace queries and
-responses.  The default is 64, except for local queries to the 
+responses.
+The default is 64, except for local queries to the
 "all routers" multicast group which use ttl 1.
 .It Fl v
 Verbose mode; show hop times on the initial trace and statistics display.
@@ -212,7 +217,8 @@ to the
 A trace query packet is sent to the last
 hop multicast router (the leaf router for the desired
 .Ar receiver
-address).  The last hop router builds a trace response packet, fills in
+address).
+The last hop router builds a trace response packet, fills in
 a report for its hop, and forwards the trace packet using unicast to
 the router it believes is the previous hop for packets originating
 from the specified
@@ -225,10 +231,10 @@ the trace query.
 .Pp
 If some multicast router along the path does not implement the
 multicast traceroute feature or if there is some outage, then no
-response will be returned.  To solve this problem, the trace query
-includes a maximum hop count field to limit the number of hops traced
-before the response is returned.  That allows a partial path to be
-traced.
+response will be returned.
+To solve this problem, the trace query includes a maximum hop count field
+to limit the number of hops traced before the response is returned.
+That allows a partial path to be traced.
 .Pp
 The reports inserted by each router contain not only the address of
 the hop, but also the ttl required to forward and some flags to indicate
@@ -246,29 +252,31 @@ last hop on the path from the
 .Ae source
 to the
 .Ar receiver .
-If the 
+If the
 .Ar receiver
 is on the local subnet (as determined using the subnet
 mask), then the default method is to multicast the trace query to
-all-routers.mcast.net (224.0.0.2) with a ttl of 1.  Otherwise, the
-trace query is multicast to the
+all-routers.mcast.net (224.0.0.2) with a ttl of 1.
+Otherwise, the trace query is multicast to the
 .Ar group
 address since the last hop router will be a member of that group if
-the 
-.Ar receiver 
-is.  Therefore it is necessary to specify a 
-.Ar group 
-that the intended 
-.Ar receiver 
-is joined.  This multicast is sent with a
-default ttl of 64, which may not be sufficient for all cases (changed
-with the
+the
+.Ar receiver
+is.
+Therefore it is necessary to specify a
+.Ar group
+that the intended
+.Ar receiver
+is joined.
+This multicast is sent with a default ttl of 64, which may not be sufficient
+for all cases (changed with the
 .Fl t
 option).
 If the last hop router is known, it may also be addressed directly
 using the
 .Fl g
-option).  Alternatively, if it is desired to trace a group that the
+option).
+Alternatively, if it is desired to trace a group that the
 .Ar receiver
 has not joined, but it is known that the last-hop router is a
 member of another group, the
@@ -276,9 +284,9 @@ member of another group, the
 option may also be used to specify a different multicast address for the
 trace query.
 .Pp
-When tracing from a multihomed host or router, the default 
+When tracing from a multihomed host or router, the default
 .Ar receiver
-address may not be the desired interface for the path from the 
+address may not be the desired interface for the path from the
 .Ar source .
 In that case, the desired interface should be specified explicitly as
 the
@@ -289,34 +297,37 @@ By default,
 first attempts to trace the full reverse path, unless the number of
 hops to trace is explicitly set with the
 .Fl m
-option.  If there is no response within a 3 second timeout interval
+option.
+If there is no response within a 3 second timeout interval
 (changed with the
 .Fl m
 option), a "*" is printed and the probing switches to hop-by-hop mode.
 Trace queries are issued starting with a maximum hop count of one and
 increasing by one until the full path is traced or no response is
-received.  At each hop, multiple probes are sent (default is three,
-changed with
+received.
+At each hop, multiple probes are sent (default is three, changed with
 .Fl q
-option).  The first half of the attempts (default is one) are made with
+option).
+The first half of the attempts (default is one) are made with
 the unicast address of the host running
 .Nm
-as the destination for the response.  Since the unicast route may be
-blocked, the remainder of attempts request that the response be
-multicast to mtrace.mcast.net (224.0.1.32) with the ttl set to 32 more
-than what's needed to pass the thresholds seen so far along the path
-to the 
+as the destination for the response.
+Since the unicast route may be blocked, the remainder of attempts request
+that the response be multicast to mtrace.mcast.net (224.0.1.32) with the
+ttl set to 32 more than what's needed to pass the thresholds seen so far
+along the path to the
 .Ar receiver .
 For the last quarter of the attempts (default is
-one), the ttl is increased by another 32 each time up to a maximum of
-192.  Alternatively, the ttl may be set explicitly with the
+one), the ttl is increased by another 32 each time up to a maximum of 192.
+Alternatively, the ttl may be set explicitly with the
 .Fl t
 option and/or the initial unicast attempts can be forced to use
 multicast instead with the
 .Fl m
-option.  For each attempt, if no response is received within the
-timeout, a "*" is printed.  After the specified number of attempts
-have failed,
+option.
+For each attempt, if no response is received within the timeout,
+a "*" is printed.
+After the specified number of attempts have failed,
 .Nm
 will try to query the next hop router with a DVMRP_ASK_NEIGHBORS2
 request (as used by the
@@ -325,9 +336,9 @@ program) to see what kind of router it is.
 .Sh EXAMPLES
 The output of
 .Nm
-is in two sections.  The first section is a short listing of the hops
-in the order they are queried, that is, in the reverse of the order
-from the
+is in two sections.
+The first section is a short listing of the hops in the order they are
+queried, that is, in the reverse of the order from the
 .Ae source
 to the
 .Ae receiver .
@@ -336,11 +347,11 @@ negatively to indicate that this is the reverse path); the multicast
 routing protocol (DVMRP, MOSPF, PIM, etc.); the threshold required to
 forward data (to the previous hop in the listing as indicated by the
 up-arrow character); and the cumulative delay for the query to reach
-that hop (valid only if the clocks are synchronized).  This first
-section ends with a line showing the round-trip time which measures
+that hop (valid only if the clocks are synchronized).
+This first section ends with a line showing the round-trip time which measures
 the interval from when the query is issued until the response is
-received, both derived from the local system clock.  A sample use and
-output might be:
+received, both derived from the local system clock.
+A sample use and output might be:
 .Pp
 .Bd -literal
 oak.isi.edu 80# mtrace -l caraway.lcs.mit.edu 224.2.0.3
@@ -358,37 +369,39 @@ Round trip time 124 ms
 .Pp
 The second section provides a pictorial view of the path in the
 forward direction with data flow indicated by arrows pointing downward
-and the query path indicated by arrows pointing upward.  For each hop,
-both the entry and exit addresses of the router are shown if
+and the query path indicated by arrows pointing upward.
+For each hop, both the entry and exit addresses of the router are shown if
 different, along with the initial ttl required on the packet in order
 to be forwarded at this hop and the propagation delay across the hop
-assuming that the routers at both ends have synchronized clocks.  The
-right half of this section is composed of several columns of
-statistics in two groups.  Within each group, the columns are the
-number of packets lost, the number of packets sent, the percentage
-lost, and the average packet rate at each hop.  These statistics are
-calculated from differences between traces and from hop to hop as
-explained above.  The first group shows the statistics for all traffic
-flowing out the interface at one hop and in the interface at the next
-hop.  The second group shows the statistics only for traffic forwarded
+assuming that the routers at both ends have synchronized clocks.
+The right half of this section is composed of several columns of
+statistics in two groups.
+Within each group, the columns are the number of packets lost, the number
+of packets sent, the percentage lost, and the average packet rate at each hop.
+These statistics are calculated from differences between traces and from
+hop to hop as explained above.
+The first group shows the statistics for all traffic flowing out the interface
+at one hop and in the interface at the next hop.
+The second group shows the statistics only for traffic forwarded
 from the specified
 .Ar source
 to the specified
 .Ar group .
 .Pp
-These statistics are shown on one or two lines for each hop.  Without
-any options, this second section of the output is printed only once,
-approximately 10 seconds after the initial trace.  One line is shown
-for each hop showing the statistics over that 10-second period.  If
-the
+These statistics are shown on one or two lines for each hop.
+Without any options, this second section of the output is printed only once,
+approximately 10 seconds after the initial trace.
+One line is shown for each hop showing the statistics over that 10-second
+period.
+If the
 .Fl l
 option is given, the second section is repeated every 10 seconds and
-two lines are shown for each hop.  The first line shows the statistics
-for the last 10 seconds, and the second line shows the cumulative
-statistics over the period since the initial trace, which is 101
-seconds in the example below.  The second section of the output is
-omitted if the
-.Fl s.
+two lines are shown for each hop.
+The first line shows the statistics for the last 10 seconds, and the second
+line shows the cumulative statistics over the period since the initial trace,
+which is 101 seconds in the example below.
+The second section of the output is omitted if the
+.Fl s .
 option is set.
 .Pp
 .Bd -literal
@@ -424,43 +437,48 @@ Waiting to accumulate statistics... Results after 101 seconds:
 .Pp
 Because the packet counts may be changing as the trace query is
 propagating, there may be small errors (off by 1 or 2) in these
-statistics.  However, those errors should not accumulate, so the
-cumulative statistics line should increase in accuracy as a new trace
-is run every 10 seconds.  There are two sources of larger errors, both
-of which show up as negative losses:
+statistics.
+However, those errors should not accumulate, so the cumulative statistics
+line should increase in accuracy as a new trace is run every 10 seconds.
+There are two sources of larger errors,
+both of which show up as negative losses:
 .Bl -bullet -offset abcd
 .It
 If the input to a node is from a multi-access network with more than
 one other node attached, then the input count will be (close to) the
 sum of the output counts from all the attached nodes, but the output
 count from the previous hop on the traced path will be only part of
-that.  Hence the output count minus the input count will be negative.
+that.
+Hence the output count minus the input count will be negative.
 .It
 In release 3.3 of the DVMRP multicast forwarding software for SunOS
 and other systems, a multicast packet generated on a router will be
-counted as having come in an interface even though it did not.  This
-creates the negative loss that can be seen in the example above.
+counted as having come in an interface even though it did not.
+This creates the negative loss that can be seen in the example above.
 .El
 .Pp
 Note that these negative losses may mask positive losses.
 .Pp
-In the example, there is also one negative hop time.  This simply
-indicates a lack of synchronization between the system clocks across
-that hop.  This example also illustrates how the percentage loss is
+In the example, there is also one negative hop time.
+This simply indicates a lack of synchronization between the system clocks
+across that hop.
+This example also illustrates how the percentage loss is
 shown as two dashes when the number of packets sent is less than 10
 because the percentage would not be statistically valid.
 .Pp
-A second example shows a trace to a 
+A second example shows a trace to a
 .Ar receiver
 that is not local; the query is sent to the last-hop router with the
 .Fl g
-option.  In this example, the trace of the full reverse path resulted
+option.
+In this example, the trace of the full reverse path resulted
 in no response because there was a node running an old version of
 .Nm mrouted
 that did not implement the multicast traceroute function, so
 .Nm
-switched to hop-by-hop mode.  The "Route pruned" error code
-indicates that traffic for group 224.2.143.24 would not be forwarded.
+switched to hop-by-hop mode.
+The "Route pruned" error code indicates that traffic for group 224.2.143.24
+would not be forwarded.
 .Pp
 .Bd -literal
 oak.isi.edu 108# mtrace -g 140.173.48.2 204.62.246.73 \\
@@ -482,12 +500,13 @@ Round trip time 95 ms
 .Xr traceroute 8
 .Sh AUTHORS
 Implemented by Steve Casner based on an initial prototype written by
-Ajit Thyagarajan.  The multicast traceroute mechanism was designed by
+Ajit Thyagarajan.
+The multicast traceroute mechanism was designed by
 Van Jacobson with help from Steve Casner, Steve Deering, Dino
 Farinacci, and Deb Agrawal; it was implemented in
 .Nm mrouted
-by Ajit Thyagarajan and Bill Fenner.  The option syntax and the output
-format of
+by Ajit Thyagarajan and Bill Fenner.
+The option syntax and the output format of
 .Nm
 are modeled after the unicast
 .Nm traceroute
@@ -500,7 +519,8 @@ unicast packet and
 .Nm mrouted
 has no route for the
 .Ar source
-address.  Therefore, do not use the
+address.
+Therefore, do not use the
 .Fl g
 option unless the target
 .Nm mrouted