repo: gemini-site
action: commit
revision: 
path_from: 
revision_from: a9067a3c16b79a6f3a4658d4d9b82f9c1f39a95a:
path_to: 
revision_to: 

commit a9067a3c16b79a6f3a4658d4d9b82f9c1f39a95a
Author: Solderpunk 
Date:   Sun Nov 14 18:31:43 2021 +0100

    Assorted spelling and grammar fixes.

diff --git a/docs/best-practices.gmi b/docs/best-practices.gmi

--- a/docs/best-practices.gmi
+++ b/docs/best-practices.gmi
@@ -15,7 +15,7 @@ path.

 ## File size

-Gemini servers do not inform clients of the size of files they are serving, which can make it difficult to detect if a connection is closed prematurely due to a server fault.  This risk of this happening increases with file size.
+Gemini servers do not inform clients of the size of files they are serving, which can make it difficult to detect if a connection is closed prematurely due to a server fault.  The risk of this happening increases with file size.

 Gemini also has no support for compression of large files, or support for checksums to enable detection of file corruption, the risk of which also increases with file size.

@@ -43,13 +43,13 @@ As such, please refrain from using redirects frivolously!  Things like URL-short

 Clients may prompt their users for decisions as to whether or not to follow a redirect, or they may follow redirects automatically.  If you write a client which follows redirects automatically, you should keep the following issues in mind.

-Misconfigured or malicious Gemini servers may serve redirects in such a way that a client which follows them blindly gets trapped in an infinite loop of redirects, or otherwise has to complete a very long chain of redirects.  Robust clients will need to be smart enough to detect these conditions and act accordingly.  The simplest implementation is to refuse to follow more than N consecutive redirects.  It is recommended that N be set no higher than 5.  This is inline with the original recommenation for HTTP (see RFC-2068).
+Misconfigured or malicious Gemini servers may serve redirects in such a way that a client which follows them blindly gets trapped in an infinite loop of redirects, or otherwise has to complete a very long chain of redirects.  Robust clients will need to be smart enough to detect these conditions and act accordingly.  The simplest implementation is to refuse to follow more than N consecutive redirects.  It is recommended that N be set no higher than 5.  This is inline with the original recommendation for HTTP (see RFC-2068).

 ### Cross-protocol redirects

 Cross-protocol redirects (i.e. redirects from Gemini to something else, like Gopher) are possible within Gemini, but are very heavily discouraged.  However, misconfigured or malicious servers will always be able to serve such redirects, so well-written clients should be ready to detect them and respond accordingly.

-It is strongly recommended that even clients which generally follow redirects automatically alert the user and ask for explicit confirmation when served a redirect to a non-TLS-secured protocols like HTTP or Gopher, assuming the client implements support for these protocols.  This avoids unintentional plaintext transfers.
+It is strongly recommended that even clients which generally follow redirects automatically alert the user and ask for explicit confirmation when served a redirect to a non-TLS-secured protocol like HTTP or Gopher, assuming the client implements support for these protocols.  This avoids unintentional plaintext transfers.

 ### TLS Cipher suites

diff --git a/docs/gemtext.gmi b/docs/gemtext.gmi

--- a/docs/gemtext.gmi
+++ b/docs/gemtext.gmi
@@ -1,8 +1,8 @@
 # A quick introduction to "gemtext" markup

-The most common way to serve textual content over Gemini is not just plain text like on Gopher, but using a lightweight markup language called "Gemtext" (which is served with the unofficial MIME type text/gemini).  This document is a quick introduction to that markup language.  It has some superficial resemblences to Markdown, which will make it easy to learn if you know MD, but it's quite different in other ways.
+The most common way to serve textual content over Gemini is not just plain text like on Gopher, but using a lightweight markup language called "Gemtext" (which is served with the unofficial MIME type text/gemini).  This document is a quick introduction to that markup language.  It has some superficial resemblances to Markdown, which will make it easy to learn if you know MD, but it's quite different in other ways.

-Once you've read this document, you might like to occasionally refresh your memory by refering to the:
+Once you've read this document, you might like to occasionally refresh your memory by referring to the:

 => cheatsheet.gmi Gemtext cheatsheet

@@ -10,7 +10,7 @@ Once you've read this document, you might like to occasionally refresh your memo

 Text in Gemtext documents is written using "long lines", i.e. you (or your editor) shouldn't be inserting newline characters every 80 characters or so.  Instead, leave it up to the receiving Gemini client to wrap your lines to fit the device's screen size and the user's preference.  This way Gemtext content looks good and is easy to read on desktop monitors, laptop screens, tablets and smartphones.

-Note that while Gemini clients will break up lines of text which are longer than the user's screen, they will not join up lines which are shorter than the user's screen, like would happen in Markdown, HTML or LaTeX.  This means that, e.g. "dot point" lists or poems with deliberately short lines will be displayed correctly without the author having to do any extra work or the client having to be any smarter in order to recognise and handle that kind of content corectly.
+Note that while Gemini clients will break up lines of text which are longer than the user's screen, they will not join up lines which are shorter than the user's screen, like would happen in Markdown, HTML or LaTeX.  This means that, e.g. "dot point" lists or poems with deliberately short lines will be displayed correctly without the author having to do any extra work or the client having to be any smarter in order to recognise and handle that kind of content correctly.

 For most "everyday" writing, this approach means you probably just want to use one line per paragraph.

diff --git a/docs/specification.gmi b/docs/specification.gmi

--- a/docs/specification.gmi
+++ b/docs/specification.gmi
@@ -45,7 +45,7 @@ Gemini requests are a single CRLF-terminated line with the following structure:

 Sending an absolute URL instead of only a path or selector is effectively equivalent to building in a HTTP "Host" header.  It permits virtual hosting of multiple Gemini domains on the same IP address.  It also allows servers to optionally act as proxies.  Including schemes other than "gemini" in requests allows servers to optionally act as protocol-translating gateways to e.g. fetch gopher resources over Gemini.  Proxying is optional and the vast majority of servers are expected to only respond to requests for resources at their own domain(s).

-Clients MUST NOT send anything after the first occurence of  in a request, and servers MUST ignore anything sent after the first occurence of a .
+Clients MUST NOT send anything after the first occurrence of  in a request, and servers MUST ignore anything sent after the first occurrence of a .

 # 3 Gemini responses

@@ -91,7 +91,7 @@ The request was handled successfully and a response body will follow the respons

 Status codes beginning with 3 are REDIRECT status codes, meaning:

-The server is redirecting the client to a new location for the requested resource.  There is no response body.   is a new URL for the requested resource.  The URL may be absolute or relative.  If relative, it should be resolved against the URL used in the original request.  If the URL used in the original request contained a query string, the client MUST NOT apply this string to the redirect URL, instead using the redirect URL "as is".  The redirect should be considered temporary, i.e. clients should continue to request the resource at the original address and should not performance convenience actions like automatically updating bookmarks.  There is no response body.
+The server is redirecting the client to a new location for the requested resource.  There is no response body.   is a new URL for the requested resource.  The URL may be absolute or relative.  If relative, it should be resolved against the URL used in the original request.  If the URL used in the original request contained a query string, the client MUST NOT apply this string to the redirect URL, instead using the redirect URL "as is".  The redirect should be considered temporary, i.e. clients should continue to request the resource at the original address and should not perform convenience actions like automatically updating bookmarks.  There is no response body.

 ### 3.2.4 4x (TEMPORARY FAILURE)

@@ -121,7 +121,7 @@ The Gemini status code system has been carefully designed so that the increased

 ## 3.3 Response bodies

-Response bodies are just raw content, text or binary, ala gopher.  There is no support for compression, chunking or any other kind of content or transfer encoding.  The server closes the connection after the final byte, there is no "end of response" signal like gopher's lonely dot.
+Response bodies are just raw content, text or binary, à la gopher.  There is no support for compression, chunking or any other kind of content or transfer encoding.  The server closes the connection after the final byte, there is no "end of response" signal like gopher's lonely dot.

 Response bodies only accompany responses whose header indicates a SUCCESS status (i.e. a status code whose first digit is 2).  For such responses,  is a MIME media type as defined in RFC 2046.

@@ -208,7 +208,7 @@ Text lines are the most fundamental line type - any line which does not match th

 Text lines should be presented to the user, after being wrapped to the appropriate width for the client's viewport (see below).  Text lines may be presented to the user in a visually pleasing manner for general reading, the precise meaning of which is at the client's discretion.  For example, variable width fonts may be used, spacing may be normalised, with spaces between sentences being made wider than spacing between words, and other such typographical niceties may be applied.  Clients may permit users to customise the appearance of text lines by altering the font, font size, text and background colour, etc.  Authors should not expect to exercise any control over the precise rendering of their text lines, only of their actual textual content.  Content such as ASCII art, computer source code, etc. which may appear incorrectly when treated as such should be enclosed between preformatting toggle lines (see 5.4.3).

-Blank lines are instances of text lines and have no special meaning.  They should be rendered individually as vertical blank space each time they occur.  In this way  they are analogous to 
 tags in HTML.  Consecutive blank lines should NOT be collapsed into a fewer blank lines.  Note also that consecutive non-blank text lines do not form any kind of coherent unit or block such as a "paragraph": all text lines are independent entities.
+Blank lines are instances of text lines and have no special meaning.  They should be rendered individually as vertical blank space each time they occur.  In this way  they are analogous to 
 tags in HTML.  Consecutive blank lines should NOT be collapsed into fewer blank lines.  Note also that consecutive non-blank text lines do not form any kind of coherent unit or block such as a "paragraph": all text lines are independent entities.

 Text lines which are longer than can fit on a client's display device SHOULD be "wrapped" to fit, i.e. long lines should be split (ideally at whitespace or at hyphens) into multiple consecutive lines of a device-appropriate width.  This wrapping is applied to each line of text independently.  Multiple consecutive lines which are shorter than the client's display device MUST NOT be combined into fewer, longer lines.

@@ -276,7 +276,7 @@ Lines beginning with "* " are unordered list items.  This line type exists purel

 ### 5.5.3 Quote lines

-Lines beginning with ">" are quote lines.  This line type exists so that advanced clients may use distinct styling to convey to readers the important semantic information that certain text is being quoted from an external source.  For example, when wrapping long lines to the the viewport, each resultant line may have a ">" symbol placed at the front.
+Lines beginning with ">" are quote lines.  This line type exists so that advanced clients may use distinct styling to convey to readers the important semantic information that certain text is being quoted from an external source.  For example, when wrapping long lines to the viewport, each resultant line may have a ">" symbol placed at the front.

 # Appendix 1. Full two digit status codes

@@ -350,4 +350,4 @@ The supplied client certificate is not authorised for accessing the particular r

 ## 62 CERTIFICATE NOT VALID

-The supplied client certificate was not accepted because it is not valid.  This indicates a problem with the certificate in and of itself, with no consideration of the particular requested resource.  The most likely cause is that the certificate's validity start date is in the future or its expiry date has passed, but this code may also indicate an invalid signature, or a violation of a X509 standard requirements.  The  should provide more information about the exact error.
+The supplied client certificate was not accepted because it is not valid.  This indicates a problem with the certificate in and of itself, with no consideration of the particular requested resource.  The most likely cause is that the certificate's validity start date is in the future or its expiry date has passed, but this code may also indicate an invalid signature, or a violation of X509 standard requirements.  The  should provide more information about the exact error.
diff --git a/docs/tls-tutorial.gmi b/docs/tls-tutorial.gmi

--- a/docs/tls-tutorial.gmi
+++ b/docs/tls-tutorial.gmi
@@ -4,12 +4,12 @@ This document is under construction!

 ## Introduction

-Gemini makes it mandatory to protect connections using TLS.  Not only that, but it supports the use of client certificates and alternative certificate validation schemes, which are unfamiliar to a lot of people.  For many would-be Gemini developers, this is the hardest part of the whole thing.  This document aims to provide a gentle introduction to the relevant concepts.  It's not super detailed or precise: the goal is to allow people to understand and reason about how this stuff works at level of abstraction above all the cryptographic details.
+Gemini makes it mandatory to protect connections using TLS.  Not only that, but it supports the use of client certificates and alternative certificate validation schemes, which are unfamiliar to a lot of people.  For many would-be Gemini developers, this is the hardest part of the whole thing.  This document aims to provide a gentle introduction to the relevant concepts.  It's not super detailed or precise: the goal is to allow people to understand and reason about how this stuff works at a level of abstraction above all the cryptographic details.

 This isn't a completely "from scratch" explanation.  This document assumes that you are familiar with some basic concepts from asymmetric (or "public key") cryptography; not the mathematics of how and why it all works, but the conceptual big picture.  Basically, you should feel comfortable with the ideas of:

 * Key pairs, i.e. matched public and private keys, which have the property that what is encrypted with one can only be decrypted with the other
-* Digital signatures, i.e. that people can use their private key to "sign" some digital content in way which others can validate using their public key, that said signatures cannot be forged, and they protect the signed content against modification
+* Digital signatures, i.e. that people can use their private key to "sign" some digital content in a way which others can validate using their public key, that said signatures cannot be forged, and they protect the signed content against modification

 ## Certificate basics

@@ -29,7 +29,7 @@ There can be, and in practice often is, more to a certificate than this, but the

 ### How are TLS certificates typically used?

-Suppose you are the legimiate operator of the server named `example.com`.  The "normal" way to use TLS is for you to contact a trusted third party, called a "Certificate Authority" (CA), and say "Hello CA, my DN is bla, bla, bla, and in particular my CN is example.com.  This blob of bytes right here is my very own public key".  The CA "does something" to convince itself that you are, indeed, the legitimate operator of example.com, and then they use their private key to sign a certificate, which features your DN (as the subject), their own DN (as the issuer), plus an expiry date.  You then setup your webserver, mailserver, whatever to hand out that certificate when clients make TLS certificates to it.
+Suppose you are the legitimate operator of the server named `example.com`.  The "normal" way to use TLS is for you to contact a trusted third party, called a "Certificate Authority" (CA), and say "Hello CA, my DN is bla, bla, bla, and in particular my CN is example.com.  This blob of bytes right here is my very own public key".  The CA "does something" to convince itself that you are, indeed, the legitimate operator of example.com, and then they use their private key to sign a certificate, which features your DN (as the subject), their own DN (as the issuer), plus an expiry date.  You then setup your webserver, mailserver, whatever to hand out that certificate when clients make TLS certificates to it.

 On the client side of things, web browsers and/or operating systems usually come with a big pile of public keys for recognised CAs pre-installed.  When somebody connects to your webserver and gets your certificate, they can use your CA's DN to find that CA's public key in their pile, and then they can validate the signature in your certificate.  If the signature is valid, this tells them that, indeed, that particular fine and upstanding CA has done something to convince itself that the public key in that certificate does indeed belong to example.com.  Since the client trusts the CA, they accept that this public key is genuine and (assuming the expiry date has not passed) everything is good: the client and server use the authenticated public key to bootstrap a secure channel, via a complicated process which actually has very little more to do with the certificate.

@@ -45,11 +45,11 @@ Thus, if you get away from the technical details of what's *in* a TLS cert and w

 Well, yes and no.

-Some people aren't really happy with the security provided by the CA system.  Unless you pile a lot of extra stuff on top of the simple validation procedure outlined above, *any* CA whose public key is pre-installed with your browser or your operating system can sign a certificate for *any* hostname, and your system will happily accept it.  That can be a list of literally hundreds of CAs, owned by companies or governments from all over the world, which you may actually have wildly varying levels of trust in (realistically, you won't have heard of or previously interacted with the majority of them).  If your system will accept a certificate from any of them, the whole system is only as strong as the weakest CA: the CA who does the least careful checking of claims to own a public key, or the CA with the worst internet security who gets their private key stolen, or the CA with the most easily bribed employees, or the CA whose government has the most legal power to compel them to sign a phony certificate under threat of prison or worse.  The weakest CA might be quite weak indeed, and if it is discovered that a certain CA has "gone rogue" it can be a lot of work and take a lot of time to remove its public key from each and every device which had it installed.
+Some people aren't really happy with the security provided by the CA system.  Unless you pile a lot of extra stuff on top of the simple validation procedure outlined above, *any* CA whose public key is pre-installed with your browser or your operating system can sign a certificate for *any* hostname, and your system will happily accept it.  That can be a list of literally hundreds of CAs, owned by companies or governments from all over the world, which you may actually have wildly varying levels of trust in (realistically, you won't have heard of or previously interacted with the majority of them).  If your system will accept a certificate from any of them, the whole system is only as strong as the weakest CA: the CA who does the least careful checking of claims to own a public key, or the CA with the worst internet security who gets their private key stolen, or the CA with the most easily bribed employees, or the CA whose government has the most legal power to compel them to sign a phoney certificate under threat of prison or worse.  The weakest CA might be quite weak indeed, and if it is discovered that a certain CA has "gone rogue" it can be a lot of work and take a lot of time to remove its public key from each and every device which had it installed.

 Some people are less concerned about the security provided by the CA system, and are instead unhappy for political or philosophical reasons that the whole system is based primarily on a relatively small number of private, for-profit corporations running expensive, centralised infrastructure, who charge end users money (sometimes a lot of money) for certificates.

-### What are self-issued and self-signed certificate?
+### What are self-issued and self-signed certificates?

 A certificate is "self-issued" if the subject and the issuer are the same entity, and "self-signed" if it is signed using the private key corresponding to the public key it contains.  A certificate can be self-issued without being self-signed, and vice-versa, but the most common case (and the one most people are thinking of when they talk about "self-signed certificates") is for a certificate to have both of these properties.

@@ -62,7 +62,7 @@ This is not a small problem, but it's important to understand that the differenc

 self-signed certificates are a perfectly valid thing to use.

-You might be wondering: what is the value of using a self-signed certificate instead of just using a public key by itself?  The answer is, in fact, very, little, and there are lots of secure protocols which use bare public keys without certificates.  But TLS is built completely around the concept of CA-signed certificates and doesn't provide a way to use public keys in isolation.  You can think of self-signed certificates as a hack to work around this: they let us use the pre-existing TLS technology stack but opt out of the CA system.
+You might be wondering: what is the value of using a self-signed certificate instead of just using a public key by itself?  The answer is, in fact, very little, and there are lots of secure protocols which use bare public keys without certificates.  But TLS is built completely around the concept of CA-signed certificates and doesn't provide a way to use public keys in isolation.  You can think of self-signed certificates as a hack to work around this: they let us use the pre-existing TLS technology stack but opt out of the CA system.

 ## Client certificates

-----END OF PAGE-----