Comment contribuer ?

Vous pouvez contribuer à la présente FAQ de multiples façons, notamment en :

• corrigeant les imperfections et éventuelles erreurs, certaines pages attendant des corrections ;

• mettant à jour des informations parfois datées ;

• ajoutant ou précisant des réponses aux questions ;

• créant de nouvelles pages pour partager votre expérience avec LaTeX.

1.  Principe de fonctionnement de la FAQ

Le processus de création du site Web de la présente FAQ est analogue à celui de LaTeX : des fichiers sources sont compilés pour fournir d’autres fichiers plus « exploitables ».

1.1.  Fichiers sources

Les fichiers sources de cette FAQ sont (pour l’instant) uniquement au format Markdown. Markdown est un langage de balisage léger, à la syntaxe facile à lire et à écrire (comme le sont les courriers électroniques écrits en mode texte).

Mais c’est plus précisément une version enrichie de Markdown, MyST-Parser, qui est utilisée ici. Celle-ci fournit de très nombreuses fonctionnalités dont nous décrivons la syntaxe sur une page dédiée.

1.2.  Compilation

La compilation est effectuée par le logiciel générateur de documentation Sphinx et, pour l’instant, seulement pour fabriquer les pages HTML du présent site Web. Cette compilation est lancée automatiquement et de façon transparente pour le contributeur dès lors que les modifications qu’il a apportées aux fichiers sources sont intégrées au dépôt (plus de détails ci-dessous).

2.  Dépôt GitLab

L’ensemble des fichiers de la FAQ est géré par le logiciel Git (de façon transparente pour ceux qui ne souhaitent pas apprendre à l’utiliser) et est stocké dans un dépôt GitLab : https://gitlab.gutenberg-asso.fr/gutenberg/faq-gut/.

Pour pouvoir contribuer à la présente FAQ, il vous faut au préalable suivre une procédure classique d’inscription :

1. inscription sur l’instance GitLab de l’association GUTenberg ;

2. (une fois votre inscription validée par un membre du bureau de l’association) connexion sur cette instance GitLab ;

3. demande d’accès au projet de la FAQ.

3.  Contribution au contenu de la FAQ

3.1.  Édition via l’éditeur de texte de GitLab

Si vous ne connaissez pas et ne souhaitez pas apprendre à utiliser Git, vous pouvez néanmoins très facilement contribuer à la présente FAQ en en modifiant les fichiers sources dans un éditeur de texte en ligne (qui est une version Web et light de l’éditeur Visual Studio Code).

Le moyen le plus simple pour ce faire est de cliquer sur le lien « Modifier (Ctrl+ conseillé) », présent dans le volet droit de chacune des pages de la FAQ.

Attention

Il est souvent préférable d’ouvrir ce lien dans un nouvel onglet (d’où l’indication « Ctrl+ conseillé ») de façon à garder « sous la main » la page du site dont on souhaite modifier le contenu.

Éditeur de texte Web intégré à GitLab

Note

Le thème par défaut pour l’éditeur Web est sombre (« GitLab Dark »). Vous pouvez en changer de la façon suivante :

1. En haut du volet latéral gauche, sélectionnez → File → Preferences → Theme → Color Theme.

2. Dans la liste déroulante, prévisualisez les thèmes avec les touches fléchées (les thèmes clairs se trouvant en haut de liste).

3. Sélectionnez un thème.

Une fois l’onglet ouvert, vous pourrez contribuer à la FAQ en modifiant :

• donc la page d’où vous venez ;

• mais aussi d’autres pages que vous pourrez ouvrir en naviguant dans l’arborescence de fichiers accessible dans le volet gauche.

Lorsque vos modifications seront prêtes, il vous faudra les décrire dans un message (dit « de commit ») avant qu’elles soient intégrées à la FAQ. Pour ce faire, cliquez sur le bouton mis en évidence dans l’image suivante (ou saisissez le raccourci clavier Ctrl+Shift+G) afin d’ouvrir la zone de l’éditeur dédiée à la gestion de versions du dépôt :

Zone de l’éditeur dédiée à la gestion de versions du dépôt

Saisissez ensuite votre message dans la boîte de saisie « Commit message » et enfin cliquez sur le bouton Commit to ‘main’ pour envoyer vos modifications sur le dépôt.

La plupart du temps, celles-ci apparaîtront sur le site de la FAQ en moins d’une minute.

3.2.  Édition en clonant le dépôt

Si vous êtes déjà utilisateur de Git, vous pouvez contribuer à la présente FAQ en en modifiant les fichiers sources dans votre environnement de travail habituel. Pour ce faire, il vous suffit de cloner le dépôt, ce qui peut se faire de deux manières :

1. la plus simple à moyen terme consiste à cloner avec SSH en utilisant l’URL ssh://git@gitlab.gutenberg-asso.fr:31022/gutenberg/faq-gut.git.

   Avertissement

   Cette méthode est moins simple immédiatement car elle nécessite d’utiliser une clé SSH pour envoyer vos modifications de la FAQ. La procédure pour ce faire dépasse le cadre de cette page et nous renvoyons vers la documentation (en anglais) de GitLab à ce sujet. Vous pouvez toutefois si nécessaire nous demander de l’aide en écrivant à la liste dédiée à la FAQ.

2. la plus simple immédiatement consiste à cloner avec HTTPS en utilisant l’URL https://gitlab.gutenberg-asso.fr/gutenberg/faq-gut.git. Mais il faut par la suite fournir vos nom d’utilisateur et mot de passe GitLab chaque fois que vous envoyez vos modifications de la FAQ. Sauf si vous pouvez configurer le credential.helper de git sur votre système. Par exemple sur macOS la commande suivante :

   git config --global credential.helper 'osxkeychain'
   

   a pour conséquence que le nom d’utilisateur et le mot de passe utilisés pour GitLab ne sont demandés qu’une unique fois, à l’occasion de votre tout premier git push contribuant des modifications à la FAQ.

Ensuite, procédez de façon habituelle en éditant les fichiers sources, en effectuant des commits puis des git push.

Note

Si vous envisagez de contribuer en clonant le dépôt, vous pourrez être intéressé par la possibilité de compiler la FAQ localement sur votre machine et ainsi pouvoir contrôler vos modifications avant de les publier sur le site.

3.3.  Par où commencer ?

Si vous ne savez pas par quelle page commencer, vous pouvez en consulter .

4.  Association GUTenberg

Enfin, une autre façon de contribuer à cette FAQ est d’adhérer à l’association GUTenberg, qui l’héberge et la maintient.