💾 Archived View for geminiprotocol.net › docs › fr › faq.gmi captured on 2023-11-14 at 07:52:07. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-09-08)
-=-=-=-=-=-=-
Dernière mise à jour: 2021-02-21
Gemini est un nouveau protocol internet [application-level] pour le partage de fichiers de tout type, avec une considération particulière pour la distribution d'un format hypertext léger qui [facilitates linking between files]. On peut voir Gemini comme étant "le web, réduit à son essentiel" ou comme "Gopher, modernisé avec parcimonie" selon votre point de vue (cependant, le dernier est probablement plus juste). Gemini intéressera les personnes qui :
Gemini est pensé pour être simple mais pas à tout prix. À la place, son design cherche à maximiser son "ratio puissance:poids", tout en maintenant son poids dans des limites acceptables. Gemini est aussi pensé pour protéger votre vie privée en ligne, pour être difficile à étendre (pour rester *simple* et préserver la vie privée de l'utilisateur), autour du paradigme requete-réponse, et est construit avec des technologies matures et standardisées comme les URIs, des types MIME et du protocole TLS.
Le Projet Gemini a commencé en juin 2019. Alors que le protocol lui-même est quasi finalisé, les logiciels, ressources et la communauté sont encore jeune (mais en plein expansion).
Le Projet Gemini a été lancé par Solderpunk <solderpunk _at_ posteo _dot_ net>, qui reste le "dictateur bienveillant" du projet. Cependant, le protocole a été conçu en collaboration avec une communauté large et hétéroclite de nombreuses personnes via emails, posts dans la "phlogosphere" de Gopher et toots dans le Fediverse. Beaucoup de personnes ont joué un rôle significatif dans la mise en forme du protocole, donc malgré son unique leader, Gemini ne doit pas être pensé comme le travail d'une seule personne.
En février 2021, le contributeur de longue date Sean Conner a reçu des droits de prise de décisions pour aider a finaliser les spécifications de Gemini à un moment où Solderpunk ne pouvait pas y consacrer le temps et l'énergie nécessaire.
C'est difficile à dire exactement. En comptant tous les noms d'hôte de serveurs Gemini on va surestimer la taille du Geminispace puisque certains sites offre à chacun de leurs utilisateurs un sous-domaine. De l'autre côté, si on ne compte que les adresses IP unique on sous-estimer sa taille, car plusieurs domaines peuvent être servi depuis la même adresse IP.Néanmoins, début 2021 on pouvait compter à peu près 200 000 URLs Gemini connues, répartis dans plus ou moins 750 "capsules" (le terme utilisé par la communauté pour désigné un "site"), 500 domaines et 600 adresses IP. Cet espace croît cependant rapidement. Vous pouvez trouver les dernières statistiques en suivant le lien ci-dessous.
Statistiques du Geminispace produites par le crawler "Lupa" de Stéphane Bortzmeyer
The current (informal) specification of the protocol is largely frozen, modulo small changes to remove ambiguity and address edge cases. Suggestions for new features will not be considered, as the protocol is considered feature complete. Going forward, the main focus of the project now is on growing the community around the protocol, as well as working on translating the existing specification into a more precise and formal version which might be considered for submission to internet standards bodies such as IETF and IANA.
Pas une minute! Pas plus qu'on ne veut détruire le Gopherspace. Gemini n'est pas là pour remplacer Gopher ou le web, mais pour co-exister paisiblement à leurs côtés comme une option de plus que les gens peuvent choisir librement si ça leur convient. De la même manière que certaines personnes distribue leur contenu via Gopher et le Web, on pourra "bihéberger" ou même "trihéberger" son contenu avec la combinaison de protocol adéquate selon les besoins techniques, philosophiques et esthétiques et selon le public visé.
C'est une référence à [the pre-shuttle era of US manned spaceflight], qui consistait en trois projets. Le premier était le Projet Mercury qui était plus une "preuve de faisabilité" minimaliste et une partie de la course pour envoyer le premier homme dans l'espace (que l'URSS a gagné avec le projet Vostok). Mercury était une capsule pour une personne sans possibilité d'ajuster son orbite après le lancement et un seul vol Mercury a duré plus d'une journée. Le dernier était le Projet Apollo, grand, lourd, compliquer et cher, mais qui a put envoyer trois homme sur la lune aller-retour.
Moins connu aujourd'hui, le Projet Gemini était "l'enfant du milieu": une navette pour deux qui pouvait rencontré et [s'amarrer aux autres objets en orbite], se dépressuriser et repressuriser en orbite pour facilité les sorties et dont le plus long vol a durée presque deux semaines - plus longtemps que n'importe quelle mission Apollo! En terme de taille et coût, Gemini était beaucoup plus proche de Mercury que de Apollo, mais en terme de capacité, c'était l'inverse - il y avait même des plans (qui n'ont jamais vu le jour) pour faire des vols circumlunaires!
L'analogie est on l'espère claire: Gopher est comme Mercury et le web comme Apollo. Gemini se veut au milieu, faire plus avec moins.
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.
Gemini a délibérément un nom qui n'a rien à voir avec les gauphres (gopher en anglais) ou tout autre rongeur et animal. Pendant les premières discussions sur des phlogs qui ont finis par devenir le projet Gemini, un manque de rigueur dans l'écriture a a fait qu'il n'était pas toujours clair si on parlait de purement et simplement remplacer Gopher, ou de faire des ajouts non-officiels et rétro-incompatible aux clients et serveurs Gopher. Quand la discussion s'est transformée en projet, il était sage d'envoyer un message clair.
L'espace officiel dédié au Projet Gemini est le site gemini.circumlunar.space . Il distribue la dernière version de cette FAQ, ainsi que les spécifications du protocol, les recommendations de bonnes pratiques et autres documentations officiels via Gemini, Gopher et HTTPS, en IPv4 et IPv6.
Les discussions officiels à propos de Gemini se déroulent dans la mailing list:
S'abonner à la mailing list et voir les archives via le web
Il est vivement conseillé à toute personne qui a un serveur Gemini ou qui implémente un client ou un serveur Gemini de s'abonner à la mailing list.
Les discussions informelless sur Gemini ont lieux sur le channel #gemini du serveur IRC tilde.chat:
Voir l'historique IRC via Gemini
Les critères suivants ont été définis de manière informelle au début du projet. On peut discuter à quel point on a réussi à respecter ces critères mais Gemini est généralement proche de sa cible.
En particulier, la simplicité d'implémenter un client. Les navigateurs web modernes sont si compliqués qu'ils ne peuvent être développés que via de grands et coûteux projets. Ce qui amène naturellement à l'apparition d'un petit nombre de navigateurs qui ont un quasi monopole, ce qui entrave l'innovation et la diversité, cela permet également aux développeurs de ces navigateurs de dicter les évolutions qu'ils veulent pour le web.
Gemini se veut simple mais pas *trop* simple. Gopher est un protocole plus simple mais une des conséquences et que les clients sont à jamais dans l'incertitude: quel est l'encodage de ce text? Est-ce que le texte est le contenu prévu ou est-ce un message d'erreur du serveur? Quel type de fichier est-ce? À cause de ça, créer un client Gopher robuste est *moins* facile parce qu'il faut deviner les informations manquantes.
Les premières discussions ont permis de définir trois objectifs concernant la simplicité:
It's debatable to what extent these goals have been met.
L'expérience montre qu'il faut au moins 100 lignes de code pour un client basique et 200 pour un client confortable qui intègre une bonne partie des fonctionnalités. Néanmoins Gemini semble être quand même proche de ces objectifs.
Gemini est conçu avec la connaissance que le web moderne est un désastre pour la vie privée, et qu'internet n'est pas un espace sûr pour le texte en clair. Des choses comme la prise d'empreintes du navigateur (browser fingerprinting) et les "supercookies" sont des récits édifiant: le traçage des utilisateurs est introduit par une porte dérobée en utilisant des des fonctions du protocole qui ne sont pourtant pas pensées pour. Cela signifie que les concepteurs du protocole doivent non seulement éviter d'ajouter des fonctionnalités de traçage explicite (ce qui est facile), mais aussi penser aux intentions malveillantes de certains acteurs et ne pas ajouter de fonctionnalités qui pourraient être subvertis pour du traçage. Cette inquiétude explique pourquoi la majeure partie du protocole Gemini est voulu non extensible.
La principale utilisation de Gemini est la consommation par des humains de documents essentiellement écrits - pour faciliter l'accès au gopherspace, ou un "webspace raisonnable" (e.g. quelque chose d'utilisable avec Lynx ou Dillo). De même que HTTP peut et est utilisé utilisé pour beaucoup , beaucoup plus que pour distribuer du HTML, Gemini devrait pouvoir être utilisé pour autant d'autres utilisations que possible sans compromettre la simplicité ou la sécurité. Ce qui veut dire prendre en compte les applications qui ne tournent pas autour de documents textuels et [non-human clients].
Gemini permet:
Le texte dans les documents Gemini retourne à la ligne pour s'adapter à l'appareil, plutôt que de retourner à ligne tous les ~80 caractères. Cela implique que le texte s'affichera correctement sur téléphone, tablettes, pc portable et pc fixes.
Gemini does away with Gopher's strict directory / text dichotomy and lets you insert links in prose.
Gemini mandates the use of TLS encryption.
Modern usage habits in the phlogosphere would seem to suggest that many people think it is. An increasing number of users are serving content which is almost entirely text as item type 1, so that they can insert a relatively small number of "in line" links to other gopher content, providing some semblance of HTML's hyperlinking - a perfectly reasonable and inoffensive thing to want to do. Without taking this approach, the best Gopher content authors can do is to paste a list of URLs at the bottom of their document, for their readers to manually copy and paste into their client. This is not exactly a pleasant user experience. But forcing hyperlinks into Gopher this way isn't just an abuse of the semantics of the Gopher protocol, it's also a surprisingly inefficient way to serve text, because every single line has to have an item type of i and a phony selector, hostname and port transmitted along with it to make a valid Gopher menu. Any and all claims to simplicity and beauty which Gopher might have are destroyed by this. Gemini takes the simple approach of letting people insert as many or as few links as they like into their text content, with extremely low overhead, but retains the one-link-per-line limitation of Gopher which results in clean, list-like organisation of content. It's hard to see this as anything other than an improvement.
Of course, if you really like the Gopher way, nothing in Gemini stops you from duplicating it. You can serve item type 0 content with a MIME type of text/plain, and you can write text/gemini documents where every single line is a link line, replicating the look and feel of a RFC1436-fearing Gopher menu without that pesky non-standard i item type.
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. In fact, Gemini requests contain nothing other than the URL of the resource being requested. This goes a very long way to preventing user tracking.
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, allowing for easy browsing even on old computers with limited processor speed or memory.
Many people are confused as to why it's worth creating a new protocol to address perceived problems with optional, non-essential features of the web. Just because websites *can* track users and run CPU-hogging Javsacript and pull in useless multi-megabyte header images or even larger autoplaying videos, doesn't mean they *have* to. Why not just build non-evil websites using the existing technology?
Of course, this is possible. "The Gemini experience" is roughly equivalent to HTTP where the only request header is "Host" and the only response header is "Content-type" and HTML where the only tags are <p>, <pre>, <a>, <h1> through <h3>, <ul> and <li> and <blockquote> - and the https://gemini.circumlunar.space website offers pretty much this experience. We know it can be done.
The problem is that deciding upon a strictly limited subset of HTTP and HTML, slapping a label on it and calling it a day would do almost nothing to create a clearly demarcated space where people can go to consume *only* that kind of content in *only* that kind of way. It's impossible to know in advance whether what's on the other side of a https:// URL will be within the subset or outside it. It's very tedious to verify that a website claiming to use only the subset actually does, as many of the features we want to avoid are invisible (but not harmless!) to the user. It's difficult or even impossible to deactivate support for all the unwanted features in mainstream browsers, so if somebody breaks the rules you'll pay the consequences. Writing a dumbed down web browser which gracefully ignores all the unwanted features is much harder than writing a Gemini client from scratch. Even if you did it, you'd have a very difficult time discovering the minuscule fraction of websites it could render.
Alternative, simple-by-design protocols like Gopher and Gemini create alternative, simple-by-design spaces with obvious boundaries and hard restrictions. You know for sure when you enter Geminispace, and you can know for sure and in advance when following a certain link will cause you leave it. While you're there, you know for sure and in advance that everybody else there is playing by the same rules. You can relax and get on with your browsing, and follow links to sites you've never heard of before, which just popped up yesterday, and be confident that they won't try to track you or serve you garbage because they *can't*. You can do all this with a client you wrote yourself, so you *know* you can trust it. It's a very different, much more liberating and much more empowering experience than trying to carve out a tiny, invisible sub-sub-sub-sub-space of the web.
Naturally!
Gemini has no support for caching, compression, or resumption of interrupted downloads. As such, it's not very well suited to distributing large files, for values of "large" which depend upon the speed and reliability of your network connection.
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 everything 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.
Gemini also turns TLS client certificates - very rarely seen on the web - into a first-class citizen with in-band signalling of their requirement. This allows restricting access to Gemini resources to certain parties, or voluntarily establishing "sessions" with server-side applications, without having to pass around cookies, passwords, authentication tokens or anything else you may be used to. It's much closer to SSH's notion of "authorized keys" and is, in fact, a much simpler approach to user authentication.
TLS is certainly not without its shortcomings, but:
The text/gemini markup borrows heavily from Markdown, which might prompt some people to wonder "Why not just use Markdown as the default media type for Gemini? Sure, it's complicated to implement, but like TLS there are plenty of libraries available in all the major languages". Reasons not to go down this route include:
Of course, it is possible to serve Markdown over Gemini. The inclusion of a text/markdown Media type in the response header will allow more advanced clients to support it.
Because text/gemini is an entirely new format defined from scratch for Gemini, client authors will typically need to write their own code to parse and render the format from scratch, without being able to rely on a pre-existing, well-tested library implementation. Therefore, it is important that the format is extremely simple to handle correctly. The line-based format where text lines and link lines are separate concepts achieves this. There is no need for clients to scan each line character-by-character, testing for the presence of some special link syntax. Even the simplest special link syntax introduces the possibility of malformed syntax which clients would need to be robust against, and has edge cases whose handling would either need to be explicitly addressed in the protocol specification (leading to a longer, more tedious specification which was less fun to read and harder to hold in your head), or left undefined (leading to inconsistent behaviour across different clients). Even though in-line links may be a more natural fit for some kinds of content, they're just not worth the increased complexity and fragility they would inevitably introduce to the protocol.
It's true that you need to shift your thinking a bit to get used to the one link per line writing style, but it gets easier over time. There are benefits to the style as well. It encourages including only the most important or relevant links, organising links into related lists, and giving each link a maximally descriptive label without having to worry about whether or not that label fits naturally into the flow of your main text.
Some people have expressed a desire for something similar to CSS in Gemini. While it's true that something much simpler and lighter than CSS could easily be designed, Gemini instead takes the position that visual styling of Gemini content should be under the sole and direct control of the reader, not the writer. Not everybody has the same taste in colours and fonts, and no single way of styling a page will be optimal for all readers, all devices and all lighting conditions. There is much more at stake here than the age old divide in preferene for dark text on a light background or vice versa. People with reading disabilities like dyslexia may benefit tremendously from using specially designed fonts, for example. A simple "one size fits all" styling system where content looks the same everywhere is guaranteed to perform poorly for a lot of people. A more complicated styling system which can specify different looks for different devices and contexts burdens every individual author with the task of making sure their capsule is usable everywhere. Experience from the web suggests that accessibility issues will often be an afterthought at best. It's much simpler, and in fact much more liberating for content authors, to let content just be content, and leave styling to the client. Some Gemini clients might look dull and boring, but there's no reason this has to be the case. If there is demand for clients with high quality font rendering and beautiful typography, such clients will eventually be developed - and when they are, users who value those things can enjoy that reading experience everywhere in Geminispace, even when reading content written by authors who don't care about styling at all.
Non-extensibility of the protocol was a major design principle for Gemini. Things like cookies, Etags and other tracking tools were not present in the original design of HTTP, but could be seamlessly added later because the HTTP response format is open-ended and allows the easy inclusion of new headers. To minimise the risk of Gemini slowly mutating into something more web-like, it was decided to include one and exactly one piece of information in the response header for successful requests. Including two pieces of information with a specified delimiter would provide a very obvious path for later adding a third piece - just use the same delimiter again. There is basically no stable position between one piece of information and arbitrarily many pieces of information, so Gemini sticks hard to the former option, even if it means having to sacrifice some nice and seemingly harmless functionality. Given this restriction, including only an equivalent of Content-type seemed clearly more useful than including only an equivalent of Content-length. The same is true for other harmless and useful HTTP headers, like Last-Modified.
Gopher also has no equivalent of the Content-length header, and this has not proven to be a practical obstacle in Gopherspace.
Even without this header, it is possible (unlike in Gopher) for clients to distinguish between a Gemini transaction which has completed successfully and one which has dropped out mid-transfer due to a network fault or malicious attack via the presence or absence of a TLS Shutdown message.
It is true that the inability for clients to tell users how much more of a large file still has to be downloaded and to estimate how long this may take means Gemini cannot provide a very user-friendly experience for large file downloads. However, this would be the case even if Content-length were specified, as such an experience would also require other complications to be added to the protocol e.g. the ability to resume interrupted downloads. Gemini documents can of course straightforwardly link to resources hosted via HTTPS, BitTorrent, IPFS, DAT, etc. and this may be the best option for very large files.
This would only be useful if there were plans to smoothly upgrade to a "Gemini 2.0" in the future - and there aren't! Gemini is a "less is more" reaction against web browsers and servers becoming too complicated and too powerful. It makes no sense to plan to add more functionality to Gemini later. Instead the plan is to "get it right the first time", as much as possible, then freeze the protocol specification forever after, without upgrades, enhancements or extensions.
This may seem radical or unwise, but we're cautiously optimistic. The Gopher specification has not been changed in about 30 years, and only a very small number of quite minor unofficial changes to that spec are in common use in today's Gopherspace, which is actually growing in popularity. Gemini combines mature, ubiquitous internet primitives like URIs, MIME media types and TLS in a very straightforward way, and seeks to foster a culture of working within - and even embracing - carefully chosen limitations, rather than removing each constraint as it is encountered to make anything possible. There are plenty of things that Gemini is useful for and good at right now, and there is no reason to think it won't be useful for and good at those same things decades from now.
Gopher is so simple that computers from the 80s or 90s can easily implement the protocol, and for some people this is one of the great virtues of Gopher. The TLS requirement of Gemini limits it to more modern machines.
Old machines are awesome, and keeping them running, online and useful for as long as possible is an awesome thing to do. But it also makes no sense for the vast majority of internet users to sacrifice any and all privacy protection to facilitate this. Remember, though, that Gemini does not aim to replace Gopher, so the retro-compatible internet is not directly endangered by it. In fact, people serving content via Gopher right now are strongly encouraged to start also serving that same content via Gemini simultaneously. Retrocomputing fans can continue to access the content via Gopher, while modern computer users who wish to can switch to Gemini and reap some benefits.
The lowest commitment way to explore Geminispace is to use a web proxy or "portal", such as one of the following:
This will allow you to use your regular web browser to explore Geminispace. If you like what you see, you might want to consider installing a dedicated Gemini client, which will typically offer a better and more complete browsing experience. You can find a list of clients (and other software) at the link below. There are even clients available for mobile platforms like Android and iOS!
If you have an ssh client installed, you can try some terminal clients out without installing them by running:
ssh kiosk@gemini.circumlunar.space
This Gemini kiosk was inspired by the Gopher kiosk at bitreich.org!
For now, Geminispace is still small enough that it's feasible to use directories as a way to discover what is out there. Some of these are listed below:
The medusae.space Gemini directory has a list of capsules divided into thematic categories
The geminispace.info search engine's list of known Gemini hosts
A historic list of the first 50 Gemini servers
Si vou cherchez quelque chose en particulier, Gemini a un moteur de recherche :
Le moteur de recherche geminispace.info
There are two public aggregators which attempt to make it easier to find recently-updated material in Geminispace:
CAPCOM, which aggregates Atom feeds of Gemini content
Spacewalk, which uses change-detection to find new content
One option is to set up your own Gemini server on a VPS or a computer in your home (small SBCs like the RaspberryPi are perfectly capable of acting as Gemini servers). There is a wide range of server software available to choose from:
Alternatively, you can find somewhere else to host your content for you. Gemini hosting is also available from the following providers:
SourceHut (including support for custom domains!)
A number of "pubnix" or "tilde" communities (multi-user unix systems where users interact with one another by sshing in and using local email, chat and BBS applications) also offer Gemini hosting (typically alongside web and/or Gopher hosting). You may be able to get an account of one of the communities listed below. Please note that most of these communities are older than Gemini itself, and may be focussed on other services, or may be specific to a particular theme or interest. Research your choices carefully and join somewhere you think you might fit in well overall, rather than just treating these amazing little worlds as free space to dump your stuff.
Tanelorn City, a writer-focussed server
Breadpunk.club, a baking-themed server
If you belong to a pubnix community which doesn't offer Gemini hosting, it can't hurt to ask the admin(s) if they are interested in adding this service!
If you do not feel comfortable with the technologies needed to make use of pubnix hosting (ssh or sftp, terminal text editors, unix file permissions, etc) you can get free accounts at the services below which will allow you to maintain a capsule via a web application:
Gemlog Blue, featuring an ultralight interface with no cookies or Javascript
Flounder, where your content will be available via Gemini and the web simultaneously
Please consider joining the mailing list (see question 1.3) so that you can announce your new server to the community, and keep up to date with e.g. updates to your server software or to the Gemini protocol itself.
Vous pouvez ajouter l'URL de votre serveur au moteur de recherche geminispace.info, pour qu'il soit ramassé et indexé, via :
Soumettre un URL à geminispace.info
Gemini already has a surprising number of client and server implementations in existence - which isn't to say more aren't welcome, but the real shortage right now is not of software but of content. The more interesting and exciting stuff people find in Geminispace, the more likely they are to want to add content of their own. So, the greatest contribution you can make to the project is to be a part of this process. See question 3.3 above for details on how to get your content into Geminispace.
If you have the necessary technical skills, you can make a major contribution to the growth of Geminispace by providing a hosting service which people can use to publish content. This can be as simple as setting up sftp-only user accounts on a VPS. Offering hosting doesn't necessarily need to be a big committment. You can use the cheapest VPS services on offer to very comfortably host a dozen or so users. A large number of hosts each serving the content of a relatively small number of users is a much more robust and sustainable ecosystem than a small number of servers each hosting hundreds or thousands of users!
If you really want to write some software, a powerful tool for expanding Geminispace could be a single piece of software which simultaneously provides a Gemini server and a way for multiple users to easily manage the content provided by said server, e.g. via an interactive web interface or by sending emails full of content; Something like the Gemlog Blue and Flounder services (see question 3.3 again), but packaged up and documented in such a way that it's easy for people to deploy and customise their own multiuser sites, much like e.g. a Mastodon instance.
You can also help the project by contributing corrections and additions to or translations of the official site and documentation (see questions 4.2 and 4.3 below).
All the documentation hosted at gemini.circumlunar.space, including the FAQ you're reading now, lives in a single git repository, which has read-only access open to the public. You can clone the repo as follows:
git clone git://gemini.circumlunar.space/gemini-site
Then, make your suggested changes to the relevant files (the structure of the URLs mirrors the structure of the repository exactly, so e.g. gemini://gemini.circumlunar.space/docs/faq.gmi lives at docs/faq.gmi in the repo). Commit your changes with meaningful commit messages (make sure to set your name and email address so people can see who did your work!), with one commit per conceptual change. You then have two options to send your work upstream.
If you have git's send-email command configured (see below for a link to a tutorial), you can email patches containing your commits to <solderpunk _at_ posteo _dot_ net> with a single command. Otherwise, you can simply run:
git format-patch origin
to create a set of patch files, which you can manually attach to an email using your ordinary mail client of choice.
A friendly tutorial on configuring git send-email
Thank you! Volunteering to translate documentation is a wonderful way to help the project.
To do so, first clone the git repository as described in question 4.2 above. Change into the `doc` directory of the repository, and create a new subdirectory with your language's two letter ISO 639-1 code, e.g. Finnish translations should live in `doc/fi/`, Japanese translations in `doc/jp/`, etc. You can find a complete list of codes at Wikipedia, linked below. If you are translating into a region-specific variant of a language, you can use RFC4646-style codes instead, e.g. pt-PT or pt-BR for the Portuguese as spoken in Portugal or Brazil, respectively.
List of language codes at Wikipedia
For each English file which lives in `doc` which you want to translate, create a corresponding file in your language's subdirectory. It's okay to change the file name as part of the translation, e.g. the German translation of `doc/specification.gmi` might be called `doc/spezifikation.gmi`. You can translate as many or as few of the files in `doc` as you have time and energy for. Don't be shy about submitting partial translations! Once somebody else who speaks your language sees your effort, they might provide some or all of the remaining work. Having some content translated is better than none.
Once you're done, copy across the `doc/index.gmi` file and modify it to match your translated filenames and document titles, and remove links for any of the original documents which you haven't translated yet.
Finally, update `doc/translations.gmi` to include a link to your new subdirectory.
Commit your translations to the repository and send Solderpunk the patch as described in question 4.2 above.