CURLOPT_STREAM_WEIGHT.3: call argument 'weight' too

... and add a little example of what the weight actually means. "Relative
proportion of bandwidth".

diff --git a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3
index c292c02e31dc4f5e49f9054a7f929ade26c211cd..ca918fb32836c3856d575fff163c1f218db3d97b 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3
+++ b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3
@@ -22,19 +22,18 @@
 .\"
 .TH CURLOPT_STREAM_WEIGHT 3 "13 Sep 2015" "libcurl 7.46.0" "curl_easy_setopt options"
 .SH NAME
-CURLOPT_STREAM_WEIGHT \- set numerical stream priority
+CURLOPT_STREAM_WEIGHT \- set numerical stream weight
 .SH SYNOPSIS
 #include <curl/curl.h>
 
-CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_WEIGHT, long prio);
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_WEIGHT, long weight);
 .SH DESCRIPTION
-Set the long \fIprio\fP to a number between 1 and 256.
+Set the long \fIweight\fP to a number between 1 and 256.
 
-When using HTTP/2, this option can be used to set an individual weight for
-this particular stream used by the easy \fIhandle\fP. Setting and using
-weights really only makes sense and is only usable when doing multiple streams
-over the same connections, which thus implies that you use
-\fICURLMOPT_PIPELINING(3)\fP.
+When using HTTP/2, this option sets the individual weight for this particular
+stream used by the easy \fIhandle\fP. Setting and using weights only makes
+sense and is only usable when doing multiple streams over the same
+connections, which thus implies that you use \fICURLMOPT_PIPELINING(3)\fP.
 
 This option can be set during transfer and will then cause the updated weight
 info get sent to the server the next time a HTTP/2 frame is sent to the
@@ -42,6 +41,12 @@ server.
 
 See section 5.3 of RFC 7540 for protocol details:
 https://httpwg.github.io/specs/rfc7540.html#StreamPriority
+
+Streams with the same parent should be allocated resources proportionally
+based on their weight. So if you have two streams going, stream A with weight
+16 and stream B with weight 32, stream B will get two thirds (32/48) of the
+available bandwidth (assuming the server can send off the data equally for
+both streams).
 .SH DEFAULT
 If nothing is set, the HTTP/2 protocol itself will use its own default which
 is 16.