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

commit f3dbe0b113d59bc508fe589478809769783f1650
Author: Solderpunk 
Date:   Tue Oct 29 19:22:56 2019 +0000

    FAQ overhaul.

diff --git a/docs/faq.txt b/docs/faq.txt

--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -1,153 +1,203 @@
-What is project Gemini?
------------------------
-
-Project Gemini is my effort to design a new application-level internet
-protocol for the distribution of arbitrary files, with some special
-consideration for serving a lightweight hypertext format which
-facilitates linking between files.
-
-Gemini is not an exercise in absolute, brutal minimalism, and will not
-result in a "featherweight" protocol.  This doesn't mean featherweight
-protocols are bad, I think they're interesting and fun, it's just not
-what this project is about.  Informally, Gemini is about designing a
-protocol which maximises "power to weight ratio" without crossing the
-line from "lightweight" to "mediumweight" (I don't know what this
-means, but I trust that I'll know it when I see it).  Even less
-formally, and in the grand internet tradition of meaningless car
-analogies, Gemini is a protocol answer to the question "What is the
-closest thing you can build to a HUMVEE which still weighs less than a
-Volkswagen Beetle and can be maintained by a backyard mechanic?".
-
-Gemini looks to gopher (mostly great, but with some undeniable pain
-points) and to the web (mostly bad, but with some good ideas and
-valuable capabilities) for examples of potential problems associated
-with protocols which are close to the lower and upper extremes of
-complexity/capability, and strives to walk a middle path between them.
-It is inspired by both, but is not backward-, upward- or
-sideways-compatible with either.  Gemini is not intended to replace
-either gopher or the web, but to co-exist peacefully alongside them.
-In the same way that many people serve the same content via gopher and
-the web, people will be able to "bihost" or "trihost" content on
-whichever protocols they think offer the best match to their technical,
-philosophical and aesthetic requirements and those of their intended
-audience.
-
-Design criteria
----------------
-
-Simplicity:
-
-* It should be possible for somebody who had no part in designing the
-  protocol to accurately hold the entire protocol spec in their head
-  after reading a well-written description of it once or twice.
-* A basic but usable (not ultra-spartan) client should fit comfortably
-  within 50 or so lines of code in a modern high-level language.
-  Certainly not more than 100.
-* A client comfortable for daily use which implements every single
-  protocol feature should be a feasible weekend programming project
-  for a single developer.
-
-Privacy:
-
-* The privacy disaster of the modern web must be avoided at all costs.
-  Nothing which could conceivably be used as an equivalent of cookies,
-  Referer or User-Agent headers will be included.  The cautionary
-  tales of browser fingerprinting and Etag-based "supercookies" should
-  be kept in mind: it's not enough to avoid designing in features
-  which obviously facilitate tracking.  The protocol design should
-  assume active, malicious efforts to sneak tracking in, and minimise
-  the potential for this as much as possible - even if this means
-  missing out on nice features with legitimate uses.
-* It's not the 90s anymore, and sadly it never will be again.  In some
-  countries it's perfectly legal for ISPs to log anything that they
-  receive from or send to their customers, analyse those logs, and
-  sell the results to marketers.  In other countries, so-called "deep
-  packet inspection" is used to terminate connections when certain
-  forbidden words or phrases are recognised.  The protocol must not
-  stick its head in the sand with regard to this.
-
-Functionality:
-
-* The "first class" application of Gemini is human consumption of
-  predominantly written material - to facilitate something like
-  gopherspace, or like reasonably-used webspace (something which is
-  comfortably usable in lynx etc.)  Where possible, the protocol
-  should be designed to minimise the overhead associated with this
-  application.
-* But, just like HTTP can be, and is, used for much, much more than
-  serving HTML, Gemini should be able to be used for as many other
-  purposes as possible without compromising the simplicity and
-  privacy criteria above.  Simplicity and privacy always come first,
-  and text for humans always comes first, but if it's possible to do
-  something else simply and privately, Gemini should support it,
-  even if it's obviously not the best tool for the job.  This means
-  taking into account possible applications built around non-text
-  files and non-human clients.  A robust, general purpose tool for
-  sending arbitrary information across networks is darn handy, and
-  there is no reason that such a thing needs to be particularly
-  complex.
-
-Do you really expect anybody to use this?
------------------------------------------
-
-I am under no delusions that Gemini will be "the next web" or anything
-like that.  I certainly don't expect Gemini to become widely known or
-widely used any time soon.  That's okay.  The vibrant and wonderful
-gopher community is undeniable evidence that a very small group of
-enthusiasts united around an interesting protocol is more than enough
-to facilitate...well, a vibrant and wonderful community.  If Gemini
-ends up supporting 25% as many regularly updated personal sites as
-there are regularly updated personal gopherholes, then I will be very
-happy and consider the project a success.
-
-I plan to encourage early adoption by building (or encouraging other
-people to build) tools like:
-
-* A Gemini-to-gopher proxy so that Gemini clients will immediately be
-  able to be used to read all existing gopher content alongside the
-  very small amount of new Gemini content that will exist in early
-  days.
-* A Gemini server which knows how to parse the gophermap or equivalent
-  formats of some of the most popular gopher servers, so that people
-  can immediately start bihosting their content on gopher and Gemini
-  with very little effort by just pointing the Gemini server at
-  exactly the same /var/gopher or whatever directory they already
-  have.
-
-What's with the name?
----------------------
-
-Why "Gemini"?  It's a reference to the pre-shuttle era of US manned
-spaceflight, which consisted of three projects.  The first was Project
-Mercury, which was a fairly minimalist "proof of concept" and part
-of the race to put a human in space soonest.  Mercury was a one-man
-capsule with no ability to adjust to its own orbit after launch and
-only one flight lasted longer than a day.  The last was Project
-Apollo, which was large, heavy, complicated and expensive but could,
-of course, fly three men to the moon and back.  Less well known to the
-modern public, Project Gemini was the "middle child": a two person
-capsule which could rendezvous and dock with other craft in orbit,
-could be depressurised and repressurised in orbit to facilitate
-spacewalks, and whose longest flight was almost two weeks - longer
-than any Apollo mission!  In terms of size, weight and cost Gemini was
-much closer to Mercury than to Apollo, but in terms of capabilities it
-was the other way around - there were even plans (which never
-eventuated) to do circumlunar Gemini flights!
-
-I hope the analogy is obvious: Mercury = gopher and Apollo = the web.
-
-I very deliberately didn't choose a name which had *anything* to do
-with gopher, or other rodents, or even other animals.  Some people in
-the phlogosphere seem to think that the discussions of new protocols
-represent a threat to gopher, and/or that those taking part in the
-discussions want to replace gopher with something new, or worse want
-to build these new ideas into gopher clients and servers as
-unofficial, compatibility-breaking upgrades.  This is partially our
-own fault for not talking more carefully in the earliest days of this
-discussion.  But none of those things are true for me, and I really
-think they are a minority opinion, if indeed not an outright strawman.
-To minimise the risk of further confusion, I chose a totally
-non-gophery name and will only ever refer to Gemini as
-"gopher-inspired" (and to be clear, it's definitely web-inspired,
-too!), not "based on gopher" or "an upgrade to gopher" or anything
-else like that.
+# Project Gemini FAQ
+
+## 1. Overview
+
+### 1.1 What is Gemini?
+
+Gemini is a new application-level internet protocol for the
+distribution of arbitrary files, with some special consideration for
+serving a lightweight hypertext format which facilitates linking
+between files.
+
+Gemini is intended to be simple, but not necessarily as simple as
+possible.  Instead, the design strives to maximise its "power to
+weight ratio", while keeping its weight within "acceptable" limits.
+Gemini is also intended to be very privacy conscious.
+
+You may think of Gemini as "the web, stripped right back to its
+essence" or as "Gopher, souped up and modernised a little", depending
+upon your perspective.
+
+### 1.2 Whose fault is Gemini?
+
+Project Gemini was started by Solderpunk , who
+remains Benevolent Dictator For Now.  However, the protocol has been
+designed in collaboration with a loose and informal community of
+interested parties via emails, phlog and Fediverse posts.  Many people
+have shaped significant parts of the protocol, so Gemini should not be
+thought of as the work of one person.
+
+### 1.3 Where can I learn more?
+
+The official home of Project Gemini is the gemini.circumlunar.space
+server.  It serves the latest version of this FAQ document, as well
+the protocol specification and recommended best practices via Gemini,
+Gopher and HTTPS, on IPv4 and IPv6.
+
+Official discussion regarding Gemini hapens on a mailing list.  You
+can subscribe to the list and view archives at
+gemini://lists.orbitalfox.eu/listinfo/gemini.  Anybody who is running
+a Gemini server or implementing a Gemini client or server software is
+strongly encouraged to subscribe to the list.
+
+### 1.4 Do you really think you can replace the web?
+
+Not for a minute!  Nor does anybody involved with Gemini want to
+destroy Gopherspace.  Gemini is not intended to replace either Gopher
+or the web, but to co-exist peacefully alongside them as one more
+option which people can freely choose to use if it suits them.  In
+the same way that many people currently serve the same content via
+gopher and the web, people will be able to "bihost" or "trihost"
+content on whichever combination of protocols they think offer the
+best match to their technical, philosophical and aesthetic
+requirements and those of their intended audience.
+
+### 1.5 What's with the name?
+
+It's a reference to the pre-shuttle era of US manned spaceflight,
+which consisted of three projects.  The first was Project Mercury,
+which was a fairly minimalist "proof of concept" and part of the race
+to put a human in space soonest (which the Soviet Union won with their
+Vostok project).  Mercury was a one-man capsule with no ability to
+adjust to its own orbit after launch and only one Mercury flight
+lasted longer than a single day.  The last was Project Apollo, which
+was large, heavy, complicated and expensive but could, of course,
+fly three men to the moon and back.
+
+Less well known to the modern public, Project Gemini was the "middle
+child": a two person capsule which could rendezvous and dock with
+other craft in orbit, could be depressurised and repressurised in
+orbit to facilitate spacewalks, and whose longest flight was almost
+two weeks - longer than any Apollo mission!  In terms of size, weight
+and cost Gemini was much closer to Mercury than to Apollo, but in
+terms of capabilities it was the other way around - there were even
+plans (which never eventuated) to do circumlunar Gemini flights!
+
+Hopefully the analogy is obvious: Gopher is akin to Mercury, and the
+web is akin to Apollo.  Gemini hopes to sit between the two, doing
+more with less.
+
+Gemini very deliberately didn't receive a name which had *anything*
+to do with gophers, or other rodents, or even other animals.  During
+the earliest phlog-based discussions which eventually grew into
+Project Gemini, a lack of careful writing meant it was sometimes
+unclear whether people were talking about replacing Gopher outright,
+or adding unofficial, compatibility-breaking upgrades into existing
+Gopher clients and servers.  When idle discussion turned into an
+actual project, it seemed wise to send a clearer message.
+
+# 2. Protocol design
+
+## 2.1 What are the design criteria for Gemini?
+
+The following criteria were informally put in place at the beginning
+of the project.  It's debatable how closely some of these goals have
+been met, but in general Gemini is still quite close to this target.
+
+The following are the core design criteria of the Gemini protocol:
+
+### 2.1.1 Simplicity
+
+In particular, Gemini strives for simplicity of client implementation.
+Modern web browsers are so complicated that they can only be developed
+by very large and expensive projects.  This naturally leads to a very
+small number of near-monopoly browsers, which stiffles innovation and
+diversity and allows the developers of these browsers to dictate the
+direction in which the web evolves.
+
+Gemini aims to be simple, but not *too* simple.  Gopher is simpler at
+a protocol level, but as a consequence the client is eternally
+uncertain: what character encoding is this text in?  Is this text the
+intended content or an error message from the server?  What kind of
+file is this binary data?  Because of this, a robust Gopher client is
+made *less* simple by needing to infer or guess missing information.
+
+Early Gemini discussion included three clear goals with regard to
+simplicity:
+
+1. It should be possible for somebody who had no part in designing the
+   protocol to accurately hold the entire protocol spec in their head
+   after reading a well-written description of it once or twice.
+2. A basic but usable (not ultra-spartan) client should fit comfortably
+   within 50 or so lines of code in a modern high-level language.
+   Certainly not more than 100.
+3. A client comfortable for daily use which implements every single
+   protocol feature should be a feasible weekend programming project
+   for a single developer.
+
+It's debatable to what extent these goals have been met.  Experiments
+suggest that a very basic interactive client takes more like a minimum
+of 100 lines of code, and a comfortable fit and moderate feature
+completeness need more like 200 lines.  But Gemini still seems to be
+in the ballpark of these goals.
+
+### 2.1.2 Privacy
+
+Gemini is designed with an acute awareness that the modern web is a
+privacy disaster, and that the internet is not a safe place for
+plaintext.  Things like browser fingerprinting and Etag-based
+"supercookies" are an important cautionary tale: user tracking can and
+will be snuck in via the backdoor using protocol features which were
+not designed to facilitate it.  Thus, protocol designers must not only
+avoid designing in tracking features (which is easy), but also assume
+active malicious intent and avoid designing anything which could be
+subverted to provide effective tracking.  This concern manifests as a
+deliberate non-extensibility in many parts of the Gemini protocol.
+
+### 2.1.3 Generality
+
+The "first class" application of Gemini is human consumption of
+predominantly written material - to facilitate something like
+gopherspace, or like "reasonable webspace" (e.g. something which is
+comfortably usable in Lynx or Dillo).  But, just like HTTP can be,
+and is, used for much, much more than serving HTML, Gemini should be
+able to be used for as many other purposes as possible without
+compromising the simplicity and privacy criteria above.  This means
+taking into account possible applications built around non-text
+files and non-human clients.
+
+## 2.2 Which shortcomings of Gopher does Gemini overcome?
+
+Gemini allows for:
+
+* Unambiguous use of arbitrary non-ASCII character sets.
+* Identifying binary content using MIME types instead of a small set
+  of badly outdated item types.
+* Clearly distinguishing successful transactions from failed ones.
+* Linking to non-gopher resources via URLs, without ugly hacks.
+* Redirects to prevent broken links when content moves or is
+  rearranged.
+* Domain-based virtual hosting.
+
+Gemini does away with Gopher's strict directory / text dichotomy and
+lets you insert links in prose.
+
+Gemini mandates the use of TLS encryption.
+
+## 2.3 Which shortcomings of the web does Gemini overcome?
+
+Gemini contains no equivalent of User-Agent or Referer headers, and
+the request format is not extensible so that these cannot be
+shoehorned in later.
+
+The "native content type" of Gemini (analogous to HTML for HTTP(S) or
+plain text for Gopher) never requires additional network transactions
+(there are no in-line images, external stylesheets, fonts or scripts,
+no iframes, etc.).  This allows for quick browsing even on slow
+connections and for full awareness of and control over which hosts
+connections are made to.
+
+The native content type of Gemini is strictly a document, with no
+facility for scripting.
+
+## 2.4 How can you say Gemini is simple if it uses TLS?
+
+Some people are upset that the TLS requirement means they need to use
+a TLS library to write Gemini code, whereas e.g. Gopher allows them
+full control by writing everthing from scratch themselves.
+
+Of course, even a "from scratch" Gopher client actually depends
+crucially on thousands of lines of complicated code written by other
+people in order to provide a functioning IP stack, DNS resolver and
+filesystem.  Using a TLS library to provide a trustworthy
+implementation of cryptography is little different.

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