### ----------------------------------------------------
### -- Arithmetic::PaperAndPencil
### -- Licenses: Artistic-2.0
### -- Authors: Jean Forget
### -- File: doc/Description-fr.md
### ----------------------------------------------------
### -- Chunk 3 of 5
agne du
harponnage du  diviseur, invariablement sur un  chiffre. Le harponnage
du diviseur n'a aucun intérêt et je ne l'ai pas repris dans la méthode
`division`.

Le harponnage est visible également dans ces
[deux](https://www.youtube.com/watch?v=bn-IZD-jgl8)
[tutoriels](https://www.youtube.com/watch?v=pbwoawMMEhU),
où  il est  utilisé  pour  tous les  dividendes  partiels  et non  pas
seulement pour le premier. À  mon avis, le harponnage n'est réellement
utile que  sur la première ligne  où le premier dividende  partiel est
noyé dans le dividende complet, tandis que sur les lignes suivantes on
voit très bien où se termine  le dividende partiel. En outre, dans les
divisions où  la multiplication et  la soustraction sont  séparées, le
tracé  du harpon  serait  en conflit  avec  le tracé  du  trait de  la
soustraction.

Mes expériences pour utiliser un caractère Unicode de combinaison pour
créer un surlignement n'ont pas réussi. J'ai donc biaisé en soulignant
les caractères  espaces sur la  ligne juste au-dessus. Cela  ne permet
pas  de  montrer  le  crochet   (ou  _les_  crochets  pour  un  double
harponnage), mais tant pis.

### Division et calcul du PGCD

En 1978, le  professeur de math nous  a appris à poser  la division en
écrivant le  quotient _au-dessus_ du  diviseur et non  pas au-dessous.
Ci-dessous, vous  voyez à  gauche la  disposition traditionnelle  et à
droite la nouvelle disposition.

```
                                   3141592
                                   ---
 355000000|113           355000000|113
 0160     |---           0160     |
  0470    |3141592        0470    |
   0180   |                0180   |
    0670  |                 0670  |
     1050 |                  1050 |
      0330|                   0330|
       104|                    104|
```

Pourquoi cette nouvelle disposition ? Parce que
le professeur de  math nous a également  appris l'algorithme d'Euclide
pour  le  calcul du  PGCD  de  deux nombres.  Le  calcul  se fait  par
divisions successives.  Le dividende  de la  deuxième division  est le
diviseur de la première division. Sous ce nombre, on devrait trouver à
la  fois   le  quotient  de   la  première  division  et   les  restes
intermédiaires de la deuxième division.  Ce n'est pas possible d'avoir
ces nombres  à la même  place sur le  papier, l'un d'eux  doit bouger.
C'est pour cela que le quotient est écrit au-dessus du diviseur. Voici
ce que  cela donne si  l'on veut calculer le  PGCD de 350000000  et de
113 :

```
          3141592 1   14 1
          ---     --- -- -
355000000|113    |104|7 |6
0160     |  7    | 34|1
 0470    |          6|
  0180   |
   0670  |
    1050 |
     0330|
      104|
```

L'algorithme d'Euclide effectue les opérations suivantes :

1. 355000000 ÷ 113 = 3141592, reste 104

2. 113 ÷ 104 = 1, reste 7

3. 104 ÷ 7 = 14, reste 6

4. 7 ÷ 6 = 1, reste 1

### Division standard et dissociation de la multiplication et de la soustraction

Il y  a eu un  bug dans la division  standard, si vous  choisissiez de
séparer la  multiplication et  la division lors  du calcul  des restes
intermédiaires. Le bug est corrigé, mais il mérite d'être rappelé, car
il a eu comme résultats  une restriction dans l'API. Prenons l'exemple
de la division `724 ÷ 16`.

```
--
724|16
   |--
   |..
```

Le chiffre des dizaines  est calcué avec `72 ÷ 16`.  Pour ce faire, la
première proposition est `7 ÷ 1 = 7`. La division devient :

```
--
724|16
   |--
   |7.
```

Le produit intermédiaire  est `7 × 16  = 112`, que l'on  écrit sous la
partie « harponnée » `72`, en alignant sur la droite. Cela donne :

```
 --
 724|16
112 |--
    |7.
```

Le chiffre proposé  est trop fort, donc  on le remplace par  `6` et on
efface le produit intermédiaire. En fait, seuls les caractères sous le
dividende `724` sont effacés (les chiffres `12` et l'espace qui suit).
Cela donne :

```
 --
 724|16
1   |--
    |6.
```

Le calcul du produit intermédiaire est alors :

```
 --
 724|16
196 |--
    |6.
```

En poursuivant la division, le même problème se produit avec le calcul
du chiffre des unités. La division finale est :

```
 --
 724|16
164 |--
 -- |45
  84|
 180|
  --|
   4|
```

En  fait,  non, le  problème  ne  se  produit  pas pour  les  chiffres
suivants, seulement pour le premier.  Dans un but de simplification du
code, lorsque j'ai besoin d'effacer  un produit intermédiaire (dans le
cas  de   multiplication  et   soustraction  séparées)  ou   un  reste
intermédiaire   (dans  le   cas  de   multiplicaton  et   soustraction
combinées), l'effacement se produit sur  la totalité de la ligne. Dans
l'exemple ci-dessous,  l'effacement se  produit sur les  cinq colonnes
correspondant au dividende  `72426`, même si à chaque  fois le produit
intermédiaire ne fait que 2 ou 3 chiffres.

```
 --
 72426|16
164   |--
 --   |4526
  84  |
  80  |
  --  |
   42 |
   32 |
   -- |
   102|
    96|
   ---|
    06|
```

Pour les  divisions individuelles, le  bug a été corrigé,  en effaçant
« un chiffre de  plus ». Pour la conversion de base  et pour le calcul
du PGCD, il  est impossible de le corriger. Prenons  le calcul du PGCD
de 2912 et 724. La première division est :

```
     4
     ---
2912|724
2896|
----|
  16|
```

La division suivante est initialisée avec :

```
     4   ..
     --- --
2912|724|16
2896|   |
----|   |
  16|
```

Comme on l'a vu ci-dessus, la  première proposition de chiffre est `7`
et le produit intermédiaire est `112`. Comment écrivez-vous ce produit
dans  la deuxième  division?  Le chiffre  des  centaines déborde  dans
l'espace réservé à  la première division, ce qui  transforme `2896` en
`2891` :

```
     4   7.
     --- --
2912|724|16
2891|12 |
----|   |
  16|
```

Lorsque nous passons à la  proposition suivante `6`, nous pouvons soit
effacer deux chiffres (et l'espace sous le chiffre 4), soit en effacer
trois  (et l'espace).  Dans les  deux  cas, cela  donnera un  résultat
incorrect :

```
     4   45 4           4   45 4
     --- -- -           --- -- -
2912|724|16|4      2912|724|16|4
2891|64 |16|       289 |64 |16|
----|-- |--|       ----|-- |--|
  16| 84| 0|         16| 84| 0|
    | 80|              | 80|
      --|                --|
       4|                 4|
```

La  solution  consiste  donc  à  éviter de  nous  retrouver  dans  une
situation inextricable. Donc, dans le cas  de la conversion de base et
dans  le cas  du  calcul du  PGCD,  lorsque l'on  choisit  le type  de
division  `"std"`,  alors  il   est  interdit  d'attribuer  la  valeur
`"separate"` au paramètre `mult-and-sub`.

### Division « bateau » (`boat`)

Comme vous avez  pu le constater sur les exemples  présentés au début,
la division à la mode de 1822 a la forme générale d'un losange ou d'un
hexagone, en  fonction des  longueurs respectives  du dividende  et du
diviseur.

<pre>
   0<u>4</u>                   <u>13</u>
  <strike>108</strike><u>5</u>                 <strike>142</strike><u>1</u>
 <strike>14021</strike><u>7</u>               <strike>04015</strike><u>7</u>
<strike>2469620</strike><u>2</u>             <strike>0816648</strike><u>0</u>
<u><strike>24696000</strike></u>{0954        <u><strike>34048000</strike></u>{1315
--------           --------
<strike>25882222</strike>             <strike>25882222</strike>
 <strike>258888</strike>               <strike>258888</strike>
  <strike>2588</strike>                 <strike>2588</strike>
   <strike>25</strike>                   <strike>25</strike>
</pre>

Comme  le   terme  « hexagone »   pouvait  prêter  à   confusion  avec
« hexadécimal », j'ai nommé initialement ce type de division d'après le
losange, soit _rhombic_, du terme _rhombus_ utilisé en anglais pour le
losange.

Ultérieurement, j'ai relu les pages 330  et 331 de _NWNS_ et j'ai noté
une remarque  que j'avais négligée  lors de mes  précédentes lectures.
Les Italiens comparaient la forme de cette division à un bateau ou une
galère avec la voile levée.  Donc leur expression était _divisione per
batello_ ou  _divisione per  galea_. J'ai choisi  l'équivalent anglais
`"boat"` au lieu de `"rhombic"`.

Comment ai-je  fait pour  deviner le  mécanisme ? Lorsque  l'on trouve
comment  aborder  le problème,  c'est  très  simple. Pour  aborder  le
problème, j'ai  simplement repris  l'une de ces  divisions et  je l'ai
refaite avec le mécanisme que je connaissais. Exemple concret :

```
      13            -----
     1421           34048000|25882
    040157          081660  |-----
   08166480          040140 |1315
   34048000{1315      142580|
   --------            13170|
   25882222
    258888
     2588
      25
```

J'ai  cherché  si  je  trouvais  des points  communs  entre  les  deux
divisions. Et  effectivement, il y  en a,  quand on observe  bien. Par
exemple, le deuxième dividende partiel 081660 :

<pre>
      13            -----
     1421           34048000|25882
    040157          <strong>081660</strong>  |-----
   <strong>08166</strong>480          040140 |1315
   34048<strong>0</strong>00{1315      142580|
   --------            13170|
   25882222
    258888
     2588
      25
</pre>

ou bien le troisième dividende partiel 040140 :

<pre>
      13            -----
     1421           34048000|25882
    <strong>0401</strong>57          081660  |-----
   08166<strong>4</strong>80          <strong>040140</strong> |1315
   340480<strong>0</strong>0{1315      142580|
   --------            13170|
   25882222
    258888
     2588
      25
</pre>

J'en  ai déduit  que  la division  en cours,  après  avoir abaissé  le
premier chiffre, puis  le deuxième, aurait ressemblé à  ceci, avec une
grosse interrogation en-dessous du trait :

<pre>
                    -----
                    34048000|25882
                    081660  |-----
   08166                    |1...
   <strike>34048</strike>000{1...            |
   --------                 |
   ????????
    ??????
     ????
      ??

                    -----
                    34048000|25882
    0401            081660  |-----
   <strike>08166</strike>0            040140 |13..
   <strike>340480</strike>00{13..            |
   --------                 |
   ????????
    ??????
     ????
      ??
</pre>

Comme  le  premier dividende  partiel  34048  est  barré et  comme  le
deuxième  dividende  partiel 081660  se  lit  en deux  mouvements,  un
premier mouvement  horizontal puis un mouvement  oblique, j'ai supposé
qu'il en  allait de même  pour le diviseur,  écrit deux fois  dont une
première occurrence  barrée et  une seconde  occurrence que  l'on peut
lire en deux mouvements, un horizontal et un oblique.

<pre>
                    -----
                    34048000|25882
                    081660  |-----
   08166                    |1...
   <strike>34048</strike>000{1...            |
   --------                 |
   <strike>25882</strike>2
    2588

                    -----
                    34048000|25882
    0401            081660  |-----
   <strike>08166</strike>0            040140 |13..
   <strike>340480</strike>00{13..            |
   --------                 |
   <strike>258822</strike>2
    <strike>2588</strike>8
     258
</pre>

Néanmoins, il y avait des écueils à éviter. Tout d'abord, il aurait pu
y avoir des erreurs de calcul. En fait je n'en ai pas trouvé. Ensuite,
il  aurait pu  y  avoir  des erreurs  mineures,  qui témoignent  d'une
mauvaise  application  du  mécanisme  sans  pour  autant  produire  un
résultat incorrect.  C'est le cas  avec l'autre division  présentée en
exemple.  La  voici  en  regard  avec  sa  version  en  potence,  avec
séparation  de la  multiplication  et de  la  soustraction, pour  bien
montrer le léger problème de mécanisme.

```
   04            -----
  1085           24696000|25882
 140217          00000   |-----
24696202         -----   |0954
24696000{0954    246960  |
--------         232938  |
25882222         ------  |
 258888           140220 |
  2588            129410 |
   25             ------ |
                   108100|
                   103528|
                   ------|
                    04572|
```

Dans cette division, l'élève a mal aligné le dividende et le diviseur,
ce qui a  engendré un premier chiffre  à zéro pour le  quotient et une
soustraction inutile et (légèrement) chronophage.

C'est  bel  et bien  une  erreur,  car à  une  autre  page, l'élève  a
correctement décalé la première occurrence  du diviseur par rapport au
dividende, pour  avoir un  premier chiffre différent  de zéro  dans le
quotient. On  voit que  le « 8 »  de « 87 » est  inscrit en  regard du
« 4 » de « 14076 » et non pas en regard du « 1 ».

![Exemple de division avec décalage entre le diviseur et le dividende](boat-with-shift.webp)

<pre>
  <strike>1</strike>6
 <strike>535</strike>9
<strike>14076</strike>{161
-----
 <strike>8777</strike>
  <strike>88</strike>
</pre>

Remarque : dans  cette division, l'élève  a continué en  calculant les
centimes.  Les   chiffres  correspondant  aux   restes  intermédiaires
figurent  dans  l'opération (mais  pas  dans  ma transcription).  Mais
l'opération ne  contient pas  les chiffres  de la  quatrième et  de la
cinquième occurrences du diviseur.

Un autre écueil à éviter est de  choisir une division avec trop peu de
chiffres différents. Voici un exemple  de division qui ne m'aurait pas
permis de retrouver le mécanisme.

![Exemple de division avec beaucoup de zéros, avec à droite la division en mode "potence"](boat-and-gallows.webp)

Comme vous  pouvez le remarquer,  à la droite  de la division  en mode
« bateau », on retrouve la même  division en mode « potence », avec un
commentaire écrit par un camarade de classe de l'élève de 1822 (désolé
pour les fautes d'orthographe).

<pre>
   09                   38400000{19100
  <strike>009</strike>0                  002000  {-----
 <strike>02000</strike>0                  020000 {2010
<strike>0020000</strike>0                  009000
<strike>38400000</strike>{2010              09000
--------
<strike>19100000</strike>
 <strike>191000</strike>
  <strike>1911</strike>
   <strike>19</strike>
</pre>

> Voila comme on la fait en dessus et sans bârer les chiffres

Comme vous pouvez le constater,  parmi les restes intermédiaires, il y
a  peu de  chiffres  différents de  zéro, ce  qui  rend difficiles les
comparaisons entre le « bateau » et la « potence ».

Racine carrée
-------------

L'algorithme d'extraction des racines  carrées est présenté dans _HAL_
pages 234 à 237. Il y a une première description pour un abaque (table
à calcul  ou boulier) et  une seconde, appelée  « disposition pratique
des calculs ». Voici ce que cela donne.

```
6554900|2
255    |---
       | c(c+40)<255

6554900|25
255    |---
 3049  | 5(5+40)<255
       | c(c+500)<3049

6554900|256
255    |---
 3049  | 5(5+40)<255
   1300| 6(6+500)<3049
       | c(c+5120)<1300
```

Contrairement au titre qui lui a été attribué, cette disposition n'est
pas aussi pratique que  cela. Comment calculer simplement l'expression
`c(c+40)`  pour  `c=6`  puis   pour  `c=5` ?  Idem  pour  l'expression
`c(c+500)` pour `c=6`.  Alors qu'avec la disposition  que j'ai apprise
en 1976,

```
6554900|2
255    |---
       |46
       | 6

6554900|2
255    |---
       |45
       | 5

6554900|25
255    |---
 3049  |45
       | 5
       |---
       |506
       |  6
```

les  opérations  `6×46`,  `5×45`  et `6×506`  sont  des  calculs  très
semblables aux  calculs des  restes intermédiaires dans  une division.
Donc une partie  de la mécanique d'extraction nous  était déjà connue.
De plus,  au lieu  de doubler  25 puis  de le  multiplier par  10 pour
obtenir  500, puis  de doubler  256 et  de le  multiplier par  10 pour
obtenir 5120, il nous suffisait de faire la somme `45+5` puis la somme
`506+6` et dans les deux cas, de leur coller le chiffre à essayer.

C'est pourquoi  je me contente de  la disposition que j'ai  apprise en
1976 et je laisse tomber la disposition présentée dans _HAL_ page 237.

À propos,  _HAL_ assure  que l'extraction des  racines carrées  par la
méthode de la potence a été enseignée en France jusque dans les années
1960. Or c'est en 1976 que j'ai appris cette technique.

Implémentation
==============

Coordonnées
-----------

Les coordonnées  sont le numéro de  ligne et le numéro  de colonne. Le
sens de  variation est le sens  habituel. Le numéro de  ligne croît du
haut vers le  bas et le numéro  de colonne croît de la  gauche vers la
droite.  Comme il  est difficile  de  déterminer _a  priori_ la  place
occupée   par   certaines    opérations   (multiplication  « bateau »,
notamment), on pourra avoir des  coordonnées négatives s'il y a besoin
d'insérer une nouvelle  ligne au-dessus de l'opération  ou insérer une
nouvelle colonne à gauche.

Cela  nous conduit  à  la distinction  entre  coordonnées logiques  et
coordonnées physiques.  Le générateur de HTML  utilise des coordonnées
l-c  positives  ou  nulles, appelées  « coordonnées  physiques ».  Les
coordonnées déterminées par  les différents constructeurs d'opérations
sont  les « coordonnées  logiques ». Le  générateur de  HTML détermine
quelles  sont la  valeur minimale  des  lignes logiques  et celle  des
colonnes logiques pour déterminer la façon de calculer les coordonnées
physiques à partir des coordonnées logiques.

Une autre source  d'écart entre coordonnées physiques  et logiques est
les traits verticaux.  Les traits verticaux sont  matérialisés par des
caractères  « pipe », qui  sont  des caractères  à  part entière,  par
opposition  aux  traits  horizontaux  qui  sont  matérialisés  par  un
attribut « souligné »  pour les  caractères juste au-dessus  du trait.
Cela veut  dire qu'il  faut réserver  une coordonnée  colonne physique
pour les traits verticaux. Cela conduit donc à un écart supplémentaire
pour les coordonnées colonnes.

Exemple (sachant  que je n'ai pas  réussi à générer des  soulignés, le
`31` devrait  être sur  la même  ligne que  le `160`,  les coordonnées
lignes ne sont donc pas significatives)

```
+--------------- logique = -8, physique =  0
|       +------- logique =  0, physique =  8
|       |+------ logique =  0, physique =  9
|       ||+----- logique =  1, physique = 10
|       ||| +--- logique =  3, physique = 12

355000000|133
0160     |---
 057     |31
```

Pour une chaîne de caractères,  les coordonnées sont celles du dernier
caractère (en général le chiffre  des unités s'il s'agit d'un nombre).
Par  exemple, ci-dessus,  les coordonnées  logiques du  dividende sont
`l=0, c=0`  et les coordonnées  du diviseur  sont `l=0, c=3`.  Pour un
trait  vertical,  la coordonnée  colonne  est  la  même que  celle  du
caractère  immédiatement à  sa gauche.  Pour un  trait horizontal,  la
coordonnée  ligne est  la coordonnée  des caractères  qui apparaîtront
soulignés.

Feuille de papier
-----------------

La  classe  principale, `Arithmetic::PaperAndPencil`,  représente  une
feuille de papier (ou deux dans  le cas d'une division préparée). Pour
l'instant, le seul  attribut de cette classe est  une liste d'actions,
`Arithmetic::PaperAndPencil::Action`.

Actions
-------

Une action consiste, la plupart du temps, à :

1. lire un ou deux chiffres déjà marqués,

2. éventuellement, les barrer,

3. effectuer un calcul avec ces deux chiffres,

4. prononcer ce calcul à haute voix,

5. écrire le résultat sur la feuille de papier.

Parfois, une  action consiste simplement  à tirer un trait,  sans rien
dire. Ou bien, recopier toute une  série de chiffres contigus (cas des
multiplications avec  raccourcis ou des divisions  préparées). Ou bien
encore, à effacer une série de chiffres contigus.

Les attributs  de la classe  `Arithmetic::PaperAndPencil::Action` sont
donc :

* `level` niveau de l'action, voir ci-dessous.

* `label` code de la formule consacrée accompagnant certains calculs ou certaines actions,

* `val1`, `val2`, `val3` valeurs à insérer dans le message

* `r1l` et `r1c` coordonnées logiques du premier chiffre lu,

* `r1val` valeur du premier chiffre lu,

* `r1str` indicateur signalant si le premier chiffre lu a été biffé,

* `r2l`, `r2c`, `r2val`, `r2str` l'équivalent pour le deuxième chiffre lu,

* `w1l`, `w1c`, `w1val` l'équivalent pour le premier chiffre écrit,

* `w2l`, `w2c`, `w2val` l'équivalent pour le deuxième chiffre écrit,

Exemple, pour l'action suivante :

```
        c → 0 123456 7     0 123456 7

l → 0         6 2 8          6 2 8
             --------       --------
    1        | / / /|       |1/ / /|
    2        |/ / / |2      |/2/ / |2
    3        | / / /|    →  | / / /|
    4        |/ / / |3      |/ / / |3
    5        | / / /|       | / / /|
    6        |/ / / |4      |/ / / |4
             --------       --------
    7
```

L'action correspondante est constituée de :

* `level = 5` (voir ci-dessous)

* `label = MUL01` code pour le message "#1# fois #2#, #3#"

* `val1 = 6`, `val2 = 2`, `val3 = 12` pour un message final "6 fois 2, 12"

* `r1l = 0`, `r1c = 1`, `r1val = 6`, `r1str = False`

* `r2l = 2`, `r2c = 7`, `r1val = 2`, `r1str = False`

* `w1l = 1`, `w1c = 1`, `w1val = 1`

* `w2l = 2`, `w2c = 2`, `w2val = 2`

Deuxième exemple, avec une chaîne au lieu de chiffres isolés :

```
        c → 0123456      0123456 7

l → 1          628          628
    2          333   →      333
              ----         ----
    3         1884         1884
    4            .        1884.
```

L'action correspondante est constituée de :

* `level = 3` (voir ci-dessous)

* `label = WR05` code pour "Je recopie la ligne #1#"

* `val1 = 1884` pour le message final "Je recopie la ligne 1884"

* `w1l = 4`, `w1c = 4`, `w1val = 1884`, la colonne correspond au dernier caractère de la chaîne.

* autres attributs : peu importe

Lorsque l'on  trace une ligne,  le code  du message commence  par `DR`
(comme  l'anglais _draw_).  En général,  cela ne  correspond pas  à un
véritable message,  car on  n'a pas l'habitude  de commenter  le tracé
d'une ligne. Les  coordonnées des extrémités sont  données dans `w1l`,
`w1c`, `w2l` et `w2c`. Exemple :

```
        c → 0 123456 7     0 123456 