From 087ae0e8abaf7c2c84fea0a4c01a6bdaf5dbaf1c Mon Sep 17 00:00:00 2001 From: Fabien Cazenave Date: Thu, 31 Oct 2024 04:23:52 +0100 Subject: [PATCH 1/7] writing guidelines --- www/CONTRIBUTING.md | 139 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 110 insertions(+), 29 deletions(-) diff --git a/www/CONTRIBUTING.md b/www/CONTRIBUTING.md index c11d2b6b..6156ad97 100644 --- a/www/CONTRIBUTING.md +++ b/www/CONTRIBUTING.md @@ -1,29 +1,110 @@ -# Contributing to the Ergo‑L website - -## Setup - -### For Windows - -* Open a terminal, for example Windows PowerShell -* Install [Hugo](https://gohugo.io/installation/windows/) : - ```powershell - winget install Hugo.Hugo.Extended - ``` -* 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) : - ```powershell - winget install --id Microsoft.Powershell --source winget - ``` - 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 -* Install [Pandoc](https://pandoc.org/installing.html#windows) : - ```powershell - winget install --source winget --exact --id JohnMacFarlane.Pandoc - ``` -* Launch the newly installed PowerShell (or restart it if you already had it) and go to the `www` folder : - ```powershell - cd www - ``` -* Run the development server : - ```powershell - hugo server - ``` -* And go to http://localhost:1313/ to see the effect of your changes in livereload \ No newline at end of file +Contribution au site web Ergo‑L +================================================================================ + + +Pré-requis : Hugo + Pandoc +-------------------------------------------------------------------------------- + +### Windows + +Installer [Hugo][] et [Pandoc][] depuis un émulateur de terminal, par exemple +Windows PowerShell : + +```powershell +winget install Hugo.Hugo.Extended +winget install --source winget --exact --id JohnMacFarlane.Pandoc +``` + +Attention : Hugo ne fonctionne pas depuis le terminal Windows PowerShell qui est +pré-installé. + +Hugo requiert un terminal WSL, Git Bash ou [PowerShell][] tout court, [qui n’est +pas la même application que Windows PowerShell][WindowsPS], bien que le nom soit +qussiment le même et que les deux applications sont maintenues par Microsoft. +PowerShell peut s’installer depuis Windows PowerShell : + +```powershell +winget install --id Microsoft.Powershell --source winget +``` + +[Hugo]: https://gohugo.io/installation/windows/ +[Pandoc]: https://pandoc.org/installing.html#windows +[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4 +[WindowsPS]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3 + + +Serveur de développement +-------------------------------------------------------------------------------- + +On lance le serveur de développement via un émulateur de terminal depuis ce +répertoire `www` : + +```bash +cd www +hugo serve +``` + +Le site est alors visible sur http://localhost:1313/ + +Le site est mis à jour à chaque modification de fichier (live-reload). + + + +Rédaction +-------------------------------------------------------------------------------- + +### Markdown + +Les pages sont écrites en Pandoc Markdown chaque fois que c’est possible. + +Les lignes sont limitées à 80 caractères. Des exceptions peuvent être admises +au cas par cas. + +Les titres de niveau 1 et 2 sont marqués par un soulignement de 80 signes `=` et +`-` respectivement. Les titres de niveau supérieur sont indiqués par des `#`, +mais on évitera d’utiliser les niveaux supérieurs à 3. + +Pour les liens, on privilégie les URLs dans une référence de bas de page plutôt +que dans le corps de texte, afin de faciliter la lecture. + +### Orthographe + +On suit l’orthographe de la réforme de 1990. + +Par souci d’inclusivité, on privilégie les formules épicènes. Les formes +condensées avec le point médian sont tolérées mais gagnent à être évitées. +L’accord de proximité est encouragé. + +### Typographie + +On utilise l’insécable fine avant toutes les ponctuations hautes (`?!:;`) et +entre les guillemets (`« »`). + +Les incises sont délimitées par des tirets cadratins. + +### Nombres + +Les nombres utilisent l’insécable fine comme séparateur de milliers et d’unité. +Le séparateur décimal est la virgule. + +### Anglicismes + +On évite les anglicismes dans le texte, et quand on y a recours on veillera à +les inclure dans une balise `` pour l’accessibilité (lecteurs +d’écran). + +Les termes techniques courants en anglais sont tolérés – notamment tous ceux qui +sont définis dans le glossaire. + +### Désignation des touches + +Les touches physiques du clavier sont désignées suivant les normes techniques en +vigueur (ANSI, USB Keyboard API, JavaScript Keyboard API)… qui découlent des +claviers Qwerty. + +On ne traduit pas les touches spéciales. On parle donc de Shift, +Enter, Backspace, etc. + +Les touches physiques sont incluses dans des balises ``, les caractères +produits dans des balises ``. On parle donc de la touche F pour +désigner celle qui produit un `N` en Ergo‑L. From ca69a1d8db7c7246824418eb8e5168bf66c86599 Mon Sep 17 00:00:00 2001 From: Fabien Cazenave Date: Thu, 31 Oct 2024 04:41:26 +0100 Subject: [PATCH 2/7] typo --- www/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/www/CONTRIBUTING.md b/www/CONTRIBUTING.md index 6156ad97..3d8c2235 100644 --- a/www/CONTRIBUTING.md +++ b/www/CONTRIBUTING.md @@ -93,7 +93,7 @@ On évite les anglicismes dans le texte, et quand on y a recours on veillera à les inclure dans une balise `` pour l’accessibilité (lecteurs d’écran). -Les termes techniques courants en anglais sont tolérés – notamment tous ceux qui +Les termes techniques courants en anglais sont tolérés — notamment tous ceux qui sont définis dans le glossaire. ### Désignation des touches @@ -105,6 +105,6 @@ claviers Qwerty. On ne traduit pas les touches spéciales. On parle donc de Shift, Enter, Backspace, etc. -Les touches physiques sont incluses dans des balises ``, les caractères +Les touches physiques sont incluses dans des balises ``, les caractères produits dans des balises ``. On parle donc de la touche F pour désigner celle qui produit un `N` en Ergo‑L. From 01195a89d46f5d01ce63a6eac925b1ee54eb1289 Mon Sep 17 00:00:00 2001 From: Fabien Cazenave Date: Thu, 31 Oct 2024 23:50:24 +0100 Subject: [PATCH 3/7] addressing review comments --- www/CONTRIBUTING.md | 49 ++++++++++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 21 deletions(-) diff --git a/www/CONTRIBUTING.md b/www/CONTRIBUTING.md index 3d8c2235..a6d68f2a 100644 --- a/www/CONTRIBUTING.md +++ b/www/CONTRIBUTING.md @@ -1,8 +1,8 @@ -Contribution au site web Ergo‑L +Contribuer au site Web Ergo‑L ================================================================================ -Pré-requis : Hugo + Pandoc +Prérequis : Hugo + Pandoc -------------------------------------------------------------------------------- ### Windows @@ -16,11 +16,11 @@ winget install --source winget --exact --id JohnMacFarlane.Pandoc ``` Attention : Hugo ne fonctionne pas depuis le terminal Windows PowerShell qui est -pré-installé. +préinstallé. Hugo requiert un terminal WSL, Git Bash ou [PowerShell][] tout court, [qui n’est pas la même application que Windows PowerShell][WindowsPS], bien que le nom soit -qussiment le même et que les deux applications sont maintenues par Microsoft. +quasiment le même et que les deux applications soient maintenues par Microsoft. PowerShell peut s’installer depuis Windows PowerShell : ```powershell @@ -29,8 +29,8 @@ winget install --id Microsoft.Powershell --source winget [Hugo]: https://gohugo.io/installation/windows/ [Pandoc]: https://pandoc.org/installing.html#windows -[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4 -[WindowsPS]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3 +[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows +[WindowsPS]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell Serveur de développement @@ -46,7 +46,7 @@ hugo serve Le site est alors visible sur http://localhost:1313/ -Le site est mis à jour à chaque modification de fichier (live-reload). +Le site est mis à jour à chaque modification de fichier (live-reload). @@ -55,41 +55,43 @@ Rédaction ### Markdown -Les pages sont écrites en Pandoc Markdown chaque fois que c’est possible. +Les pages sont écrites en [Pandoc Markdown][] plutôn qu’en HTML chaque fois que +c’est possible. -Les lignes sont limitées à 80 caractères. Des exceptions peuvent être admises -au cas par cas. +Les lignes sont limitées à 80 caractères. Les titres de niveau 1 et 2 sont marqués par un soulignement de 80 signes `=` et -`-` respectivement. Les titres de niveau supérieur sont indiqués par des `#`, -mais on évitera d’utiliser les niveaux supérieurs à 3. +`-` respectivement (en-tête Setext). Les titres de niveau supérieur sont +indiqués par des `#` (en-tête ATX), mais on évitera d’utiliser les niveaux +supérieurs à 3. -Pour les liens, on privilégie les URLs dans une référence de bas de page plutôt -que dans le corps de texte, afin de faciliter la lecture. +Pour les liens, on privilégie les URL dans une référence de bas de page plutôt +que dans le corps du texte, afin de faciliter la lecture. ### Orthographe -On suit l’orthographe de la réforme de 1990. +On suit l’orthographe de la [réforme de 1990][]. Il existe des dictionnaires +dédiés, et des outils comme Wiktionnaire indiquent les variantes. -Par souci d’inclusivité, on privilégie les formules épicènes. Les formes +Par souci d’inclusivité, on privilégie les formules [épicènes][]. Les formes condensées avec le point médian sont tolérées mais gagnent à être évitées. -L’accord de proximité est encouragé. +L’[accord de proximité][] est encouragé. ### Typographie On utilise l’insécable fine avant toutes les ponctuations hautes (`?!:;`) et -entre les guillemets (`« »`). +à l’intérieur des guillemets (`« »`). -Les incises sont délimitées par des tirets cadratins. +Les incises sont délimitées par des tirets cadratins (—), sans insécables. ### Nombres Les nombres utilisent l’insécable fine comme séparateur de milliers et d’unité. Le séparateur décimal est la virgule. -### Anglicismes +### Termes anglophones -On évite les anglicismes dans le texte, et quand on y a recours on veillera à +On évite les mots anglais dans le texte, et quand on y a recours on veillera à les inclure dans une balise `` pour l’accessibilité (lecteurs d’écran). @@ -108,3 +110,8 @@ On ne traduit pas les touches spéciales. On parle donc de Shift, Les touches physiques sont incluses dans des balises ``, les caractères produits dans des balises ``. On parle donc de la touche F pour désigner celle qui produit un `N` en Ergo‑L. + +[Pandoc Markdown]: https://pandoc.org/MANUAL.html#pandocs-markdown +[réforme de 1990]: https://fr.wikipedia.org/wiki/Rectifications_orthographiques_du_français_en_1990 +[épicènes]: https://fr.wiktionary.org/wiki/épicène +[accord de proximité]: https://fr.wikipedia.org/wiki/Règle_de_proximité From 7556684486b4e47bb8edebad44776685c67a5bf7 Mon Sep 17 00:00:00 2001 From: Fabien Cazenave Date: Thu, 31 Oct 2024 23:57:41 +0100 Subject: [PATCH 4/7] raw link bedween <> --- www/CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/www/CONTRIBUTING.md b/www/CONTRIBUTING.md index a6d68f2a..234a4df2 100644 --- a/www/CONTRIBUTING.md +++ b/www/CONTRIBUTING.md @@ -44,9 +44,10 @@ cd www hugo serve ``` -Le site est alors visible sur http://localhost:1313/ +Le site est alors visible sur . -Le site est mis à jour à chaque modification de fichier (live-reload). +Le site est mis à jour à chaque modification de fichier +(live-reload). From 26e25b2a52b6dec8eee68b1c0544649959bacce8 Mon Sep 17 00:00:00 2001 From: Fabien Cazenave Date: Fri, 1 Nov 2024 06:45:21 +0100 Subject: [PATCH 5/7] [] links --- www/CONTRIBUTING.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/www/CONTRIBUTING.md b/www/CONTRIBUTING.md index 234a4df2..40c1cf25 100644 --- a/www/CONTRIBUTING.md +++ b/www/CONTRIBUTING.md @@ -56,7 +56,7 @@ Rédaction ### Markdown -Les pages sont écrites en [Pandoc Markdown][] plutôn qu’en HTML chaque fois que +Les pages sont écrites en [Pandoc Markdown] plutôn qu’en HTML chaque fois que c’est possible. Les lignes sont limitées à 80 caractères. @@ -71,12 +71,12 @@ que dans le corps du texte, afin de faciliter la lecture. ### Orthographe -On suit l’orthographe de la [réforme de 1990][]. Il existe des dictionnaires +On suit l’orthographe de la [réforme de 1990]. Il existe des dictionnaires dédiés, et des outils comme Wiktionnaire indiquent les variantes. -Par souci d’inclusivité, on privilégie les formules [épicènes][]. Les formes +Par souci d’inclusivité, on privilégie les formules [épicènes]. Les formes condensées avec le point médian sont tolérées mais gagnent à être évitées. -L’[accord de proximité][] est encouragé. +L’[accord de proximité] est encouragé. ### Typographie @@ -102,7 +102,7 @@ sont définis dans le glossaire. ### Désignation des touches Les touches physiques du clavier sont désignées suivant les normes techniques en -vigueur (ANSI, USB Keyboard API, JavaScript Keyboard API)… qui découlent des +vigueur (ANSI, USB Keyboard API, [w3c Keyboard API])… qui découlent des claviers Qwerty. On ne traduit pas les touches spéciales. On parle donc de Shift, @@ -116,3 +116,5 @@ désigner celle qui produit un `N` en Ergo‑L. [réforme de 1990]: https://fr.wikipedia.org/wiki/Rectifications_orthographiques_du_français_en_1990 [épicènes]: https://fr.wiktionary.org/wiki/épicène [accord de proximité]: https://fr.wikipedia.org/wiki/Règle_de_proximité + +[w3c Keyboard API]: https://w3c.github.io/uievents-code/#key-alphanumeric-writing-system From 7ae0fe39947b1b2d77bfae6cc62aa5a4b68bbfc1 Mon Sep 17 00:00:00 2001 From: Fabien Cazenave Date: Mon, 4 Nov 2024 21:12:13 +0100 Subject: [PATCH 6/7] fixes --- www/CONTRIBUTING.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/www/CONTRIBUTING.md b/www/CONTRIBUTING.md index 40c1cf25..d564e631 100644 --- a/www/CONTRIBUTING.md +++ b/www/CONTRIBUTING.md @@ -7,7 +7,7 @@ Prérequis : Hugo + Pandoc ### Windows -Installer [Hugo][] et [Pandoc][] depuis un émulateur de terminal, par exemple +Installer [Hugo] et [Pandoc] depuis un émulateur de terminal, par exemple Windows PowerShell : ```powershell @@ -18,7 +18,7 @@ winget install --source winget --exact --id JohnMacFarlane.Pandoc Attention : Hugo ne fonctionne pas depuis le terminal Windows PowerShell qui est préinstallé. -Hugo requiert un terminal WSL, Git Bash ou [PowerShell][] tout court, [qui n’est +Hugo requiert un terminal WSL, Git Bash ou [PowerShell] tout court, [qui n’est pas la même application que Windows PowerShell][WindowsPS], bien que le nom soit quasiment le même et que les deux applications soient maintenues par Microsoft. PowerShell peut s’installer depuis Windows PowerShell : @@ -101,20 +101,20 @@ sont définis dans le glossaire. ### Désignation des touches -Les touches physiques du clavier sont désignées suivant les normes techniques en -vigueur (ANSI, USB Keyboard API, [w3c Keyboard API])… qui découlent des -claviers Qwerty. - -On ne traduit pas les touches spéciales. On parle donc de Shift, -Enter, Backspace, etc. - Les touches physiques sont incluses dans des balises ``, les caractères produits dans des balises ``. On parle donc de la touche F pour désigner celle qui produit un `N` en Ergo‑L. -[Pandoc Markdown]: https://pandoc.org/MANUAL.html#pandocs-markdown -[réforme de 1990]: https://fr.wikipedia.org/wiki/Rectifications_orthographiques_du_français_en_1990 +Comme on n’a pas encore de règle pour désigner les touches spéciales, l’usage +actuel mélange les termes anglais et français : Shift, +Entrée, Backspace, Esc, etc. Une possibilité +serait de s’appuyer sur des normes existantes telles que [w3c] ou [USB HID]. + + [épicènes]: https://fr.wiktionary.org/wiki/épicène [accord de proximité]: https://fr.wikipedia.org/wiki/Règle_de_proximité +[réforme de 1990]: https://fr.wikipedia.org/wiki/Rectifications_orthographiques_du_français_en_1990 -[w3c Keyboard API]: https://w3c.github.io/uievents-code/#key-alphanumeric-writing-system +[Pandoc Markdown]: https://pandoc.org/MANUAL.html#pandocs-markdown +[USB HID]: https://www.usb.org/sites/default/files/hut1_5.pdf +[w3c]: https://w3c.github.io/uievents-code/#key-alphanumeric-writing-system From 6de8f134ec226c8ca3c3c14f0925d1e24cc73c57 Mon Sep 17 00:00:00 2001 From: Fabien Cazenave Date: Mon, 4 Nov 2024 21:14:01 +0100 Subject: [PATCH 7/7] typo --- www/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/www/CONTRIBUTING.md b/www/CONTRIBUTING.md index d564e631..151f1482 100644 --- a/www/CONTRIBUTING.md +++ b/www/CONTRIBUTING.md @@ -56,7 +56,7 @@ Rédaction ### Markdown -Les pages sont écrites en [Pandoc Markdown] plutôn qu’en HTML chaque fois que +Les pages sont écrites en [Pandoc Markdown] plutôt qu’en HTML chaque fois que c’est possible. Les lignes sont limitées à 80 caractères.