Commit 4d214ecc authored by Yves's avatar Yves

Merge branch 'master' into 'master'

DOC: découpage de la documentation en plusieurs pages et ajout règles de convivialité

See merge request !51
parents f8a3b916 f5924763
# CesiumWebsite
- français : [LISEZ-MOI.md](LISEZ-MOI.md)
- english : [READ-ME.md](READ-ME.md)
## Documentation en français
* [Restrictions à votre liberté d'expression](doc/fr/restrictions-liberte-d-expression.md)
* [Comment tester installer le site sur son ordinateur ?](doc/fr/installation.md)
* [Comment traduire le site](doc/fr/comment-traduire-le-site.md)
* [Comment mettre à jour les liens de téléchargement au changement de version](doc/fr/comment-mettre-a-jour-les-liens-de-telechargement.md)
* [Licences](docs/fr/licences.md)
## Documentation in English
* [How to install Cesium website on your computer](doc/en/install.md)
* [How to translate the website](doc/en/how-to-translate-the-website.md)
* [Licences](doc/en/licences.md)
How to translate the website
===
## How to translate the main contents
For pages such as:
- Home
- Features
- Download
..and header and footer menus,
the changes take place in *.po files.
You will find those files in folders such as `i18n/fr_FR/LC_MESSAGES/` .
Such files can be edited with softwares such as [PoEdit](https://poedit.net/).
## How to translate the tutorial
To translate the tutorial, you will find .html files in folders such as `i18n/fr_FR/contents/tuto/`, where `fr_FR` is the language code for the French (fr) variant that is spoken in France (FR).
Cesium website
How to install Cesium website on your computer
===
## Install notes
## How to install the web server le serveur web
### .htaccess
To run Cesium website on your computer, you will need install a web server, and PHP ; the later converts the source code contained in *.php files into HTML the browser can understand.
Linux users will need two packages:
- apache2
- php
For instance, Debian-like (Ubuntu, Linux Mint, etc.) users will have to run:
```
sudo apt install apache2 php
```
Windows users can use [WAMP Serveur](https://www.wampserver.com/).
## .htaccess
Create a .htaccess in cesium_website directory, with the following text :
......@@ -49,7 +63,7 @@ with :
</Directory>
```
### config.php
## config.php
In ̀`config.php`, edit $rootURL var according to your setup.
......
Licences
===
Ce logiciel est pour sa majeure partie sous licence GNU GPL 3.0.
Aux exceptions suivantes :
- Le script Funding.class.php est basé sur la [barre de financement intégrable](https://git.duniter.org/paidge/barre-de-financement-int-grable), elle-même sous licence GNUL GPL 3.
- [Composer](https://getcomposer.org/) est sous licence MIT.
- [GeoIP2](https://maxmind.github.io/GeoIP2-php/) est la création de by MaxMind est distribué sous licence Apache
- Les [bases de données GeoLite2](https://dev.maxmind.com/geoip/geoip2/geolite2/) sont la création de MaxMind et sont sous licence Creative Commons Attribution-ShareAlike 4.0 International.
- Le script [LazyImg](https://github.com/colas31/lazyImg), dont la licence est inconnue.
- [Font-Awesome](https://fontawesome.com/license/free) est sous licence libre ([voir détail](https://fontawesome.com/license/free))
- Les photos, qui sont la propriété de leurs auteurs
- Le logo Cesium est la création de DiG
Comment mettre à jour les liens de téléchargement au changement de version
===
Lors d'une mise à jour de Cesium, il suffit de mettre à jour [le fichier cesiumVersions.php](cesiumVersions.php) pour que les liens de téléchargement soient automatiquement mis à jour.
Si ceux-ci étaient amenés à changer d'emplacement, veuillez mettre à jour [le fichier cesiumDownloads.php](cesiumDownloads.php)
Cesium website
Comment traduire le site
===
## Comment contribuer
## Comment traduire le contenu principal
### Comment mettre à jour les liens de téléchargement
Pour les pages :
- Accueil
- Fonctionnalités
- Téléchargement
...et les menu de l'entête et du pied de page :
Lors d'une mise à jour de Cesium, il suffit de mettre à jour [le fichier cesiumVersions.php](cesiumVersions.php) pour que les liens de téléchargement soient automatiquement mis à jour.
les modifications sont à faire dans les fichiers .po que vous trouverez dans les dossiers type `i18n/es_ES/LC_MESSAGES/` (ici : l'espagnol)
Si ceux-ci étaient amenés à changer d'emplacement, veuillez mettre à jour [le fichier cesiumDownloads.php](cesiumDownloads.php)
Ces fichiers sont éditables avec des logiciels type [PoEdit](https://poedit.net/).
### Comment traduire le tutoriel
## Comment traduire le tutoriel
Pour le tutoriel, vous trouverez les fichiers .html dans les dossiers type `i18n/es_ES/contents/tuto/` (où `es_ES` est la langue qui vous intéresse).
......@@ -18,6 +24,7 @@ Pour le tutoriel, vous trouverez les fichiers .html dans les dossiers type `i18n
Il vous faudra aussi modifier le fichier `menu.html`
Dans le menu, les URLs doivent avoir la forme suivante :
```html
<ul>
<li>
......@@ -32,121 +39,31 @@ Dans le menu, les URLs doivent avoir la forme suivante :
</ul>
</li>
</ul>
````
```
Ici, slash ou pas slash, ça compte :
* **un slash** de fin pour un **dossier** (va chercher le index.html à la racine du dossier)
* **pas de slash** de fin pour un **fichier** (va chercher le .html correspondant)
#### Comment formatter les URLs dans les fichiers
### Comment formatter les URLs dans les fichiers
Chaque URLs est relative au fichier dans lequel on l'écrit.
#### Comment rendre notre code clair pour les autres
### Comment rendre notre code clair pour les autres
Efforçons-nous d'aérer au maximum votre code HTML, afin qu'il soit facilement lisible par tous et donc rapidement modifiable.
Aussi : utiliser 4 espaces consécutifs en guise d'indentation est une déviance ainsi qu'une perversion.
#### Comment faire en sorte que le contenu soit lisible pour le visiteur
### Comment faire en sorte que le contenu soit lisible pour le visiteur
J'ai remarqué que pour les instructions dans un tuto, souvent une liste ordonnée &lt;ol&gt;&lt;/ol&gt; rend mieux
qu'une liste non-ordonnée &lt;ul&gt;&lt;/ul&gt;
### Comment modifier les images
## Comment modifier les images
C'est dans `i18n/es_ES/contents/tuto/` (où `es_ES` est la langue qui vous intéresse).
Pour des questions de SEO, les noms des fichiers sont traduits, via les fichiers .po
### Comment traduire le reste
Pour les pages :
- Accueil
- Fonctionnalités
- Téléchargement
- ...et les menu de l'entête et du pied de page
les modifications sont à faire dans les fichiers .po que vous trouverez dans les dossiers type `i18n/es_ES/LC_MESSAGES/` (ici : l'espagnol)
Ces fichiers sont éditables avec des logiciels type PoEdit.
## Instructions d'installation
### .htaccess
Votre fichier .htaccess doit contenir les infos suivantes :
```txt
<IfModule mod_rewrite.c>
RewriteEngine On
# Adaptez la ligne suivante à votre configuration (avec un slash à la fin)
RewriteBase /cesium-website-project/cesium_website/
RewriteOptions InheritDown
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule .*\.php - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^([^/]+)/(.*)$ index.php?lang=$1&page=/$2 [L]
</IfModule>
```
Modifiez l'instruction RewriteBase du .htaccess pour qu'elle s'accorde à votre propre configuration
(tapez l'endroit où CesiumWebsite est installé, typiquement /)
Si lorsque vous essayez d'accéder au site, vous avez une erreur "404 Not Found", c'est que votre fichier `.htaccess` n'est pas pris en considération par Apache.
Il vous faudra alors éditer votre fichier `/etc/apache2/apache2.conf` (anciennement `/etc/apache2/httpd.conf`) pour y remplacer :
```txt
<Directory /var/www/>
Options Indexes FollowSymLinks
AllowOverride None
Require all granted
</Directory>
```
par :
```txt
<Directory /var/www/>
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
```
Activez le mod_rewrite d'Apache :
```
sudo a2enmod rewrite
```
Redémarrez Apache :
```
systemctl restart apache2
```
### config.php
Modifiez la variable $rootURL de la même façon.
## Licences
Ce logiciel est pour sa majeure partie sous licence GNU GPL 3.0.
Aux exceptions suivantes :
- Le script Funding.class.php est basé sur la [barre de financement intégrable](https://git.duniter.org/paidge/barre-de-financement-int-grable), elle-même sous licence GNUL GPL 3.
- [Composer](https://getcomposer.org/) est sous licence MIT.
- [GeoIP2](https://maxmind.github.io/GeoIP2-php/) est la création de by MaxMind est distribué sous licence Apache
- Les [bases de données GeoLite2](https://dev.maxmind.com/geoip/geoip2/geolite2/) sont la création de MaxMind et sont sous licence Creative Commons Attribution-ShareAlike 4.0 International.
- Le script [LazyImg](https://github.com/colas31/lazyImg), dont la licence est inconnue.
- [Font-Awesome](https://fontawesome.com/license/free) est sous licence libre ([voir détail](https://fontawesome.com/license/free))
- Les photos, qui sont la propriété de leurs auteurs
- Le logo Cesium est la création de DiG
Installer le site sur son ordinateur
===
## Installer le serveur web
Pour faire tourner ce site sur votre ordinateur, vous aurez besoin d'installer un serveur web ainsi que PHP, qui transforme le code source contenu dans les fichiers *.php en HTML que le navigateur du visiteur peu comprendre.
Sous Linux, il vous faudra installer les paquets :
- apache2
- php
Par exemple, sous une Debian-like (Ubuntu, Linux Mint, etc.) :
```
sudo apt install apache2 php
```
Les utilisateurs de Windows peuvent utiliser [WAMP Serveur](https://www.wampserver.com/).
## .htaccess
Le fichier `.htaccess` est celui qui gère la réécriture d'URL, qui permet d'afficher au visiteur une structure compréhensible par un être humain dans sa barre d'adresse.
Votre fichier .htaccess doit contenir les infos suivantes :
```txt
<IfModule mod_rewrite.c>
RewriteEngine On
# Adaptez la ligne suivante à votre configuration (avec un slash à la fin)
RewriteBase /cesium-website-project/cesium_website/
RewriteOptions InheritDown
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule .*\.php - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^([^/]+)/(.*)$ index.php?lang=$1&page=/$2 [L]
</IfModule>
```
Modifiez l'instruction RewriteBase du .htaccess pour qu'elle s'accorde à votre propre configuration
(tapez l'endroit où CesiumWebsite est installé, typiquement /)
Si lorsque vous essayez d'accéder au site, vous avez une erreur "404 Not Found", c'est que votre fichier `.htaccess` n'est pas pris en considération par Apache.
Il vous faudra alors éditer votre fichier `/etc/apache2/apache2.conf` (anciennement `/etc/apache2/httpd.conf`) pour y remplacer :
```txt
<Directory /var/www/>
Options Indexes FollowSymLinks
AllowOverride None
Require all granted
</Directory>
```
par :
```txt
<Directory /var/www/>
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
```
Activez le mod_rewrite d'Apache :
```
sudo a2enmod rewrite
```
Redémarrez Apache :
```
systemctl restart apache2
```
## config.php
Modifiez la variable $rootURL de la même façon.
Licences
===
Ce logiciel est pour sa majeure partie sous licence GNU GPL 3.0.
Aux exceptions suivantes :
- Le script Funding.class.php est basé sur la [barre de financement intégrable](https://git.duniter.org/paidge/barre-de-financement-int-grable), elle-même sous licence GNUL GPL 3.
- [Composer](https://getcomposer.org/) est sous licence MIT.
- [GeoIP2](https://maxmind.github.io/GeoIP2-php/) est la création de by MaxMind est distribué sous licence Apache
- Les [bases de données GeoLite2](https://dev.maxmind.com/geoip/geoip2/geolite2/) sont la création de MaxMind et sont sous licence Creative Commons Attribution-ShareAlike 4.0 International.
- Le script [LazyImg](https://github.com/colas31/lazyImg), dont la licence est inconnue.
- [Font-Awesome](https://fontawesome.com/license/free) est sous licence libre ([voir détail](https://fontawesome.com/license/free))
- Les photos, qui sont la propriété de leurs auteurs
- Le logo Cesium est la création de DiG
Restrictions à votre liberté d'expression
===
Nous essayons de créer une communauté conviviale autour du projet de ce site.
Pour cette raison, si vous choisissez de communiquer sur [le canal #cesium-website](https://chat.axiom-team.fr/channel/cesium-website), les restrictions suivantes vous seront imposées.
Si vous n'adhérez pas à ces restrictions, vous pouvez choisir de communiquer dans un espace avec des restrictions différentes. Des outils comme [Aether](https://getaether.net/), [ScuttleButt](https://scuttlebutt.nz/), [Cabal](https://cabal.chat/) ou encore Matrix/[Riot/Element](https://riot.im/app/) vous permettent de créer des communauté sans grandes compétences techniques.
## Restriction n°1 : n'utilisez pas le champ lexical du dégoût
Le champ lexical du dégoût cherche à stimuler chez le lecteur des réactions émotionnelles de rejet.
Ce genre de pratiques va à l'encontre d'une évaluation objective des faits.
| interdit | autorisé |
| --- | --- |
| "la doc est dégueu" | "la documentation n'est pas organisée d'une façon très navigable" |
| "les dépendances sont moches" | "les dépendances pourraient casser facilement" |
| "le code est sale" | "le code est peu encapsulé" |
| "les noms des variables sont pourris" | "le code serait plus lisible pour moi si les noms des variables étaient plus explicites" |
| 🤢 ou 🤮  | s'abstenir de commentaire désobligeant |
## Restriction n°2 : n'utilisez pas le champ lexical du bien et du mal
Le bien et le mal sont des notions très relatives à chacun.
| interdit | autorisé |
| --- | --- |
| "C'est mal documenté" | "La documentation ne me permet pas de faire fonctionner le logiciel." |
| "L'outil a été mal utilisé" | "L'outil a été utilisé d'une façon qui m'est inhabituelle" |
| "C'est pire qu'avant !" | "Je préférais la version précédente parce que..." |
| "Ça ne respecte pas les bonnes pratiques" | "il n'a pas été mis en place de [séparation des préoccupations](https://fr.wikipedia.org/wiki/S%C3%A9paration_des_pr%C3%A9occupations)" |
| "C'est bien." | "J'aime." |
| "C'est mieux." | "Merci" |
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment