some tweaks to the QUEUEING section;

from mikeb and myself

1 files changed, 23 insertions, 31 deletions

diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index 8adf433ddd3..d76129deb47 100644
--- a/share/man/man5/pf.conf.5
+++ b/share/man/man5/pf.conf.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pf.conf.5,v 1.562 2017/05/19 09:06:39 jmc Exp $
+.\"	$OpenBSD: pf.conf.5,v 1.563 2017/05/22 19:15:29 jmc Exp $
 .\"
 .\" Copyright (c) 2002, Daniel Hartmeier
 .\" Copyright (c) 2003 - 2013 Henning Brauer <henning@openbsd.org>
@@ -28,7 +28,7 @@
 .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: May 19 2017 $
+.Dd $Mdocdate: May 22 2017 $
 .Dt PF.CONF 5
 .Os
 .Sh NAME
@@ -1444,25 +1444,22 @@ Packets can be assigned to queues for the purpose of bandwidth
 control.
 At least one declaration is required to configure queues, and later
 any packet filtering rule can reference the defined queues by name.
-During the filtering component of
-.Nm ,
-the last referenced
+When filtering, the last referenced
 .Ar queue
 name is where any passed packets will be queued, while for
 blocked packets it specifies where any resulting ICMP or TCP RST
 packets should be queued.
-If the referenced queue does not exist on the outgoing interface the
-default queue for that interface is used.
+If the referenced queue does not exist on the outgoing interface,
+the default queue for that interface is used.
 Queues attached to an interface build a tree,
 thus each queue can have further child queues.
 Only leaf queues, i.e. queues without children, can be used to assign
 packets to.
 The root queue must specifically reference an interface, all other queues
-pick up the interface(s) they should be created on from their parent queues
-unless explicitly specified.
+pick up the interfaces they should be created on from their parent queues.
 .Pp
 In the following example, a queue named std is created on the interface em0,
-with 3 child queues ssh, mail and http.
+with 3 child queues ssh, mail and http:
 .Bd -literal -offset indent
 queue std on em0 bandwidth 100M
 queue ssh parent std bandwidth 10M
@@ -1476,16 +1473,14 @@ The maximum bandwidth that should be assigned to a given queue can be limited
 using the
 .Cm max
 keyword.
-Similarly, a minimum (reserved) bandwidth can be specified.
-.Bd -literal -offset indent
-queue ssh parent std bandwidth 10M min 5M max 25M
-.Ed
+Similarly, a minimum (reserved) bandwidth can be specified:
+.Pp
+.Dl queue ssh parent std bandwidth 10M min 5M max 25M
 .Pp
 For each of these 3 bandwidth specifications an additional burst bandwidth and
-time can be specified.
-.Bd -literal -offset indent
-queue ssh parent std bandwidth 10M burst 90M for 100ms
-.Ed
+time can be specified:
+.Pp
+.Dl queue ssh parent std bandwidth 10M burst 90M for 100ms
 .Pp
 All
 .Cm bandwidth
@@ -1535,9 +1530,7 @@ sessions get a queue with a minimum bandwidth;
 and
 .Xr sftp 1
 bulk transfers go to a separate queue.
-The queues are then referenced by filtering rules (see
-.Sx PACKET FILTERING ,
-above).
+The queues are then referenced by filtering rules.
 .Bd -literal -offset 4n
 queue rootq on em0 bandwidth 100M max 100M
 queue http parent rootq bandwidth 60M burst 90M for 100ms
@@ -1564,23 +1557,22 @@ In addition to bandwidth management, a fair traffic sharing option
 is provided via a flow queue.
 When packets are classified by the stateful inspection engine, a flow
 identifier is assigned to all packets belonging to this state.
-A flow queue splits the outgoing traffic according to these identifiers
-into individual queues and services them in a way that provides equal
-opportunities for all connections to progress.
+Outgoing traffic is split according to these identifiers
+into individual queues and is serviced in a way that provides
+a fair share of bandwidth for all connections sharing the queue.
 .Pp
-Configuration of a flow queue is similar to a regular one, however flow
-queues don't build a hierarchy and thus only one flow queue may be
-specified per interface.
+Configuration of a flow queue is similar to a regular one,
+except flow queues don't build a hierarchy
+and thus only one flow queue may be specified per interface.
 .Pp
 The core parameter of a flow queue is the number of expected simultaneous
 connections, or
 .Cm flows ,
-bounded by the resolution of the flow identifier (the current
+limited by the resolution of the flow identifier (the current
 implementation is able to classify traffic into 32767 distinct flows).
 Thus a minimal flow queue configuration is:
-.Bd -literal -offset indent
-queue fq on em0 flows 1024
-.Ed
+.Pp
+.Dl queue fq on em0 flows 1024
 .Pp
 Another value affecting the flow queue is a quantum of service.
 The lower the