Skip to content

Commit ce94079

Browse files
fabi1cazenavefabi1cazenave
authored
writing guidelines (#252)
* writing guidelines * typo * addressing review comments * raw link bedween <> * [] links * fixes * typo
1 parent ad0bc61 commit ce94079

File tree

1 file changed

+120
-29
lines changed

1 file changed

+120
-29
lines changed

‎www/CONTRIBUTING.md

+120-29
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,120 @@
1-
# Contributing to the Ergo‑L website
2-
3-
## Setup
4-
5-
### For Windows
6-
7-
* Open a terminal, for example Windows PowerShell
8-
* Install [Hugo](https://gohugo.io/installation/windows/) :
9-
```powershell
10-
winget install Hugo.Hugo.Extended
11-
```
12-
* Optional if you run Hugo in a Linux terminal such as WSL or Git Bash ; install [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4) (Hugo can’t run in preinstalled Windows PowerShell) :
13-
```powershell
14-
winget install --id Microsoft.Powershell --source winget
15-
```
16-
Note : PowerShell is not [the same application](https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3) as _Windows_ PowerShell even if the name is almost the same and they are both maintained by Microsoft
17-
* Install [Pandoc](https://pandoc.org/installing.html#windows) :
18-
```powershell
19-
winget install --source winget --exact --id JohnMacFarlane.Pandoc
20-
```
21-
* Launch the newly installed PowerShell (or restart it if you already had it) and go to the `www` folder :
22-
```powershell
23-
cd www
24-
```
25-
* Run the development server :
26-
```powershell
27-
hugo server
28-
```
29-
* And go to http://localhost:1313/ to see the effect of your changes in livereload
1+
Contribuer au site Web Ergo‑L
2+
================================================================================
3+
4+
5+
Prérequis : Hugo + Pandoc
6+
--------------------------------------------------------------------------------
7+
8+
### Windows
9+
10+
Installer [Hugo] et [Pandoc] depuis un émulateur de terminal, par exemple
11+
Windows PowerShell :
12+
13+
```powershell
14+
winget install Hugo.Hugo.Extended
15+
winget install --source winget --exact --id JohnMacFarlane.Pandoc
16+
```
17+
18+
Attention : Hugo ne fonctionne pas depuis le terminal Windows PowerShell qui est
19+
préinstallé.
20+
21+
Hugo requiert un terminal WSL, Git Bash ou [PowerShell] tout court, [qui n’est
22+
pas la même application que Windows PowerShell][WindowsPS], bien que le nom soit
23+
quasiment le même et que les deux applications soient maintenues par Microsoft.
24+
PowerShell peut s’installer depuis Windows PowerShell :
25+
26+
```powershell
27+
winget install --id Microsoft.Powershell --source winget
28+
```
29+
30+
[Hugo]: https://gohugo.io/installation/windows/
31+
[Pandoc]: https://pandoc.org/installing.html#windows
32+
[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
33+
[WindowsPS]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell
34+
35+
36+
Serveur de développement
37+
--------------------------------------------------------------------------------
38+
39+
On lance le serveur de développement via un émulateur de terminal depuis ce
40+
répertoire `www` :
41+
42+
```bash
43+
cd www
44+
hugo serve
45+
```
46+
47+
Le site est alors visible sur <http://localhost:1313/>.
48+
49+
Le site est mis à jour à chaque modification de fichier
50+
(<i lang="en">live-reload</i>).
51+
52+
53+
54+
Rédaction
55+
--------------------------------------------------------------------------------
56+
57+
### Markdown
58+
59+
Les pages sont écrites en [Pandoc Markdown] plutôt qu’en HTML chaque fois que
60+
c’est possible.
61+
62+
Les lignes sont limitées à 80 caractères.
63+
64+
Les titres de niveau 1 et 2 sont marqués par un soulignement de 80 signes `=` et
65+
`-` respectivement (en-tête Setext). Les titres de niveau supérieur sont
66+
indiqués par des `#` (en-tête ATX), mais on évitera d’utiliser les niveaux
67+
supérieurs à 3.
68+
69+
Pour les liens, on privilégie les URL dans une référence de bas de page plutôt
70+
que dans le corps du texte, afin de faciliter la lecture.
71+
72+
### Orthographe
73+
74+
On suit l’orthographe de la [réforme de 1990]. Il existe des dictionnaires
75+
dédiés, et des outils comme Wiktionnaire indiquent les variantes.
76+
77+
Par souci d’inclusivité, on privilégie les formules [épicènes]. Les formes
78+
condensées avec le point médian sont tolérées mais gagnent à être évitées.
79+
L’[accord de proximité] est encouragé.
80+
81+
### Typographie
82+
83+
On utilise l’insécable fine avant toutes les ponctuations hautes (`?!:;`) et
84+
à l’intérieur des guillemets (`« »`).
85+
86+
Les incises sont délimitées par des tirets cadratins (—), sans insécables.
87+
88+
### Nombres
89+
90+
Les nombres utilisent l’insécable fine comme séparateur de milliers et d’unité.
91+
Le séparateur décimal est la virgule.
92+
93+
### Termes anglophones
94+
95+
On évite les mots anglais dans le texte, et quand on y a recours on veillera à
96+
les inclure dans une balise `<i lang="en">` pour l’accessibilité (lecteurs
97+
d’écran).
98+
99+
Les termes techniques courants en anglais sont tolérés — notamment tous ceux qui
100+
sont définis dans le glossaire.
101+
102+
### Désignation des touches
103+
104+
Les touches physiques sont incluses dans des balises `<kbd>`, les caractères
105+
produits dans des balises `<code>`. On parle donc de la touche <kbd>F</kbd> pour
106+
désigner celle qui produit un `N` en Ergo‑L.
107+
108+
Comme on n’a pas encore de règle pour désigner les touches spéciales, l’usage
109+
actuel mélange les termes anglais et français : <kbd>Shift</kbd>,
110+
<kbd>Entrée</kbd>, <kbd>Backspace</kbd>, <kbd>Esc</kbd>, etc. Une possibilité
111+
serait de s’appuyer sur des normes existantes telles que [w3c] ou [USB HID].
112+
113+
114+
[épicènes]: https://fr.wiktionary.org/wiki/épicène
115+
[accord de proximité]: https://fr.wikipedia.org/wiki/Règle_de_proximité
116+
[réforme de 1990]: https://fr.wikipedia.org/wiki/Rectifications_orthographiques_du_français_en_1990
117+
118+
[Pandoc Markdown]: https://pandoc.org/MANUAL.html#pandocs-markdown
119+
[USB HID]: https://www.usb.org/sites/default/files/hut1_5.pdf
120+
[w3c]: https://w3c.github.io/uievents-code/#key-alphanumeric-writing-system

0 commit comments

Comments
 (0)