docs: minor polish

- "an HTTP*" (not "a")
- remove a few contractions
- remove a spurious "a"
- reduce use of "I" in texts

Closes #11040
This commit is contained in:
Daniel Stenberg 2023-04-27 11:31:36 +02:00
parent bb0b245cc1
commit 4578ada4a0
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
11 changed files with 24 additions and 25 deletions

View File

@ -64,7 +64,7 @@ resolution screens:
newspapers have used columns for decades or centuries.
2. Narrower columns allow developers to easier show multiple pieces of code
next to each other in different windows. I often have two or three source
next to each other in different windows. It allows two or three source
code windows next to each other on the same screen - as well as multiple
terminal and debugging windows.

View File

@ -25,7 +25,7 @@ Curl_easy *data connectdata *conn cf-ssl cf-socket
While connection filters all do different things, they look the same from the "outside". The code in `data` and `conn` does not really know **which** filters are installed. `conn` just writes into the first filter, whatever that is.
Same is true for filters. Each filter has a pointer to the `next` filter. When SSL has encrypted the data, it does not write to a socket, it writes to the next filter. If that is indeed a socket, or a file, or a HTTP/2 connection is of no concern to the SSL filter.
Same is true for filters. Each filter has a pointer to the `next` filter. When SSL has encrypted the data, it does not write to a socket, it writes to the next filter. If that is indeed a socket, or a file, or an HTTP/2 connection is of no concern to the SSL filter.
And this allows the stacking, as in:
@ -91,13 +91,13 @@ struct Curl_cfilter {
BIT(connected); /* != 0 iff this filter is connected */
};
```
The filter type `cft` is a singleton, one static struct for each type of filter. The `ctx` is where a filter will hold its specific data. That varies by filter type. A http-proxy filter will keep the ongoing state of the CONNECT here, but free it after its has been established. The SSL filter will keep the `SSL*` (if OpenSSL is used) here until the connection is closed. So, this varies.
The filter type `cft` is a singleton, one static struct for each type of filter. The `ctx` is where a filter will hold its specific data. That varies by filter type. An http-proxy filter will keep the ongoing state of the CONNECT here, but free it after its has been established. The SSL filter will keep the `SSL*` (if OpenSSL is used) here until the connection is closed. So, this varies.
`conn` is a reference to the connection this filter belongs to, so nothing extra besides the pointer itself.
Several things, that before were kept in `struct connectdata`, will now go into the `filter->ctx` *when needed*. So, the memory footprint for connections that do *not* use a http proxy, or socks, or https will be lower.
Several things, that before were kept in `struct connectdata`, will now go into the `filter->ctx` *when needed*. So, the memory footprint for connections that do *not* use an http proxy, or socks, or https will be lower.
As to transfer efficiency, writing and reading through a filter comes at near zero cost *if the filter does not transform the data*. A http proxy or socks filter, once it is connected, will just pass the calls through. Those filters implementations will look like this:
As to transfer efficiency, writing and reading through a filter comes at near zero cost *if the filter does not transform the data*. An http proxy or socks filter, once it is connected, will just pass the calls through. Those filters implementations will look like this:
```
ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data,

View File

@ -205,9 +205,9 @@ A short guide to how to write git commit messages in the curl project.
followed by an -- empty line -- ]
[Bug: URL to the source of the report or more related discussion; use Fixes
for GitHub issues instead when that is appropriate]
[Approved-by: John Doe - credit someone who approved the PR; if you're
[Approved-by: John Doe - credit someone who approved the PR; if you are
committing this for someone else using --author=... you don't need this
as you're implicitly approving it by committing]
as you are implicitly approving it by committing]
[Authored-by: John Doe - credit the original author of the code; only use
this if you can't use "git commit --author=..."]
{Signed-off-by: John Doe - we don't use this, but don't bother removing it]

View File

@ -275,7 +275,7 @@ The `happy-eyeballs-timeout-ms` value is the **hard** timeout, meaning after tha
So, without you specifying anything, the hard timeout is 200ms and the soft is 100ms:
* Ideally, the whole QUIC handshake happens and curl has a HTTP/3 connection in less than 100ms.
* Ideally, the whole QUIC handshake happens and curl has an HTTP/3 connection in less than 100ms.
* When QUIC is not supported (or UDP does not work for this network path), no reply is seen and the HTTP/2 TLS+TCP connection starts 100ms later.
* In the worst case, UDP replies start before 100ms, but drag on. This will start the TLS+TCP connection after 200ms.
* When the QUIC handshake fails, the TLS+TCP connection is attempted right away. For example, when the QUIC server presents the wrong certificate.
@ -300,8 +300,8 @@ ones. You can easily create huge local files like `truncate -s=8G 8GB` - they
are huge but do not occupy that much space on disk since they are just big
holes.
In my Debian setup I just installed **apache2**. It runs on port 80 and has a
document root in `/var/www/html`. I can get the 8GB file from it with `curl
In a Debian setup you can install **apache2**. It runs on port 80 and has a
document root in `/var/www/html`. Download the 8GB file from apache with `curl
localhost/8GB -o dev/null`
In this description we setup and run an HTTP/3 reverse-proxy in front of the

View File

@ -423,7 +423,7 @@ OpenSSL, follow the OpenSSL build instructions and then install `libssl.a` and
OpenSSL like this:
```bash
LIBS="-lssl -lcrypto -lc++" # For OpenSSL/BoringSSL. In general, you'll need to the SSL/TLS layer's transtive dependencies if you're linking statically.
LIBS="-lssl -lcrypto -lc++" # For OpenSSL/BoringSSL. In general, you will need to the SSL/TLS layer's transtive dependencies if you are linking statically.
./configure --host aarch64-linux-android --with-pic --disable-shared --with-openssl="$TOOLCHAIN/sysroot/usr"
```

View File

@ -786,18 +786,16 @@ by default.
Default protocol version used by curl is LDAP version 3. Version 2 will be
used as a fallback mechanism in case version 3 fails to connect.
LDAP is a complex thing and writing an LDAP query is not an easy task. I do
advise you to dig up the syntax description for that elsewhere. One such place
might be: [RFC 2255, The LDAP URL Format](https://curl.se/rfc/rfc2255.txt)
LDAP is a complex thing and writing an LDAP query is not an easy
task. Familiarize yourself with the exact syntax description elsewhere. One
such place might be: [RFC 2255, The LDAP URL
Format](https://curl.se/rfc/rfc2255.txt)
To show you an example, this is how I can get all people from my local LDAP
server that has a certain sub-domain in their email address:
To show you an example, this is how to get all people from an LDAP server that
has a certain sub-domain in their email address:
curl -B "ldap://ldap.frontec.se/o=frontec??sub?mail=*sth.frontec.se"
If I want the same info in HTML format, I can get it by not using the `-B`
(enforce ASCII) flag.
You also can use authentication when accessing LDAP catalog:
curl -u user:passwd "ldap://ldap.frontec.se/o=frontec??sub?mail=*"

View File

@ -11,8 +11,9 @@
Curl is a command line tool for doing all sorts of URL manipulations and
transfers, but this particular document will focus on how to use it when
doing HTTP requests for fun and profit. I will assume that you know how to
invoke `curl --help` or `curl --manual` to get basic information about it.
doing HTTP requests for fun and profit. This documents assumes that you know
how to invoke `curl --help` or `curl --manual` to get basic information about
it.
Curl is not written to do everything for you. It makes the requests, it gets
the data, it sends data and it retrieves the information. You probably need

View File

@ -12,7 +12,7 @@ Category: http proxy
Example: --proxy-http2 -x proxy $URL
Multi: boolean
---
Tells curl to try negotiate HTTP version 2 with a HTTPS proxy. The proxy might
Tells curl to try negotiate HTTP version 2 with an HTTPS proxy. The proxy might
still only offer HTTP/1 and then curl will stick to using that version.
This has no effect for any other kinds of proxies.

View File

@ -34,7 +34,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC, char *filename);
.SH DESCRIPTION
Pass in a pointer to a \fIfilename\fP to instruct libcurl to use that file as
the Alt-Svc cache to read existing cache contents from and possibly also write
it back to a after a transfer, unless \fBCURLALTSVC_READONLYFILE\fP is set in
it back to after a transfer, unless \fBCURLALTSVC_READONLYFILE\fP is set in
\fICURLOPT_ALTSVC_CTRL(3)\fP.
Specify a blank file name ("") to make libcurl not load from a file at all.

View File

@ -99,7 +99,7 @@ method special. This method cannot be combined with other auth types.
A sha256 checksum of the request payload is used as input to the signature
calculation. For POST requests, this is a checksum of the provided
\fICURLOPT_POSTFIELDS(3)\fP. Otherwise, it's the checksum of an empty buffer.
For requests like PUT, you can provide your own checksum in a HTTP header named
For requests like PUT, you can provide your own checksum in an HTTP header named
\fBx-provider2-content-sha256\fP.
.PP
For \fBaws:s3\fP, a \fBx-amz-content-sha256\fP header is added to every request

View File

@ -124,7 +124,7 @@ Since 7.21.7 the proxy string supports the socks protocols as "schemes".
Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return
error.
curl built to use NSS cannot connect to a HTTPS server over a unix domain
curl built to use NSS cannot connect to an HTTPS server over a unix domain
socket.
.SH RETURN VALUE
Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or