Un traducteur md -> html minimal en awk - retour accueil
git clone git://bebou.netlib.re/katdown
Log | Files | Refs | README |
README (3800B)
1 # katdown
2
3 **KAT**zele mark**DOWN** est un fork
4 d'[awkdown](https://github.com/mgmarlow/awkdown) de Graham Marlow.
5
6 Il a pour but d'être une implémentation d'un ensemble très restreint de syntaxe
7 markdown et d'être POSIX. Les syntaxes et leurs comportement sont librement
8 inspirés de [commonmark](https://spec.commonmark.org/) et de
9 [lowdown](https://kristaps.bsd.lv/lowdown/) pour les extensions à commonmark.
10
11 > This is the Unix philosophy: Write programs that do one thing and do it well.
12 > Write programs to work together. Write programs to handle text streams, because
13 > that is a *universal interface*.
14
15 Doug McIlroy
16
17 ## Dépendances
18
19 Un interpréteur `awk` POSIX.
20
21 Testé avec les versions les plus à jour à l'écriture de ce README dans Debian
22 12 de :
23
24 * gawk
25 * mawk
26 * one-true-awk
27 * gawk --traditionnal
28 * gawk --posix
29 * busybox awk
30
31 Le script de test dépend de `lynx`. Le code est modifiable pour utiliser `w3m`,
32 `elinks` ou autres.
33
34 ## Installation
35
36 Copier `katdown` quelque part dans un dossier de votre `PATH`. Par exemple :
37
38 $ cp katdown /usr/local/bin
39
40 ## Usage
41
42 $ katdown
43 # titre 1
44
45 ## Les tests
46
47 ./launch-tests
48
49 Le script de test vérifie si l'affichage des pages html générées par `katdown`
50 est identique aux sorties de `cmark` et `lowdown` dans `lynx`.
51
52 ## Limites
53
54 `katdown` a de très^trop nombreuses limites, notamment :
55
56 1. Pas de tableau
57 2. Pas d'espace dans les exposants (l'espace est le délimiteur de fin)
58 3. Pas de balise d'emphase (em) dans des balises d'haute importance (strong)
59 quand l'emphase est écrite avec la syntaxe `*`
60 4. Pas de note de bas de page
61 5. Pas d'échappement automatique d'html
62
63 ## Performances
64
65 ### Un *gros* fichier
66
67 On génère un énorme fichier markdown en copiant 10 000 fois le README. On
68 lance katdown interprété par `gawk` dessus. On compare avec les perfs de cmark
69 et lowdown (j'utilise `zsh` et son builtin `time`) :
70
71 $ yes README | head -n10000 | xargs cat > big
72 $ wc -l big; du -h big
73 560000 big
74 14M big
75 $ time < big ./katdown > a
76 ./katdown < big > a 2,77s user 0,02s system 99% cpu 2,791 total
77 $ time < big cmark > a
78 cmark < big > b 0,42s user 0,12s system 99% cpu 0,543 total
79 $ time < big lowdown > a
80 # NE TERMINE PAS
81
82 `katdown` + `gawk` a des performances raisonnables, convertissant plus de 500
83 000 lignes de markdown en moins de trois secondes. `cmark` reste beaucoup plus
84 performant, environ 5 fois plus rapide. `lowdown` a manifestement un souci de
85 perf et ne termine pas.
86
87 A noter, `mawk` semble encore mieux performer en parsant le gros fichier en 1
88 seconde seulement ! Ce qui n'est pas une découverte puisque :
89
90 $ apt show mawk | grep rapide
91 Mawk est plus petit et plus rapide que gawk. Il a quelques limites à la
92
93 Si un jour `katdown` supporte les tableaux je mettrais ici un joli tableau des
94 perfs de chaque interpréteur.
95
96 ### Pleins de petits fichiers
97
98 On copie 10 000 fois le README puis on lance les traducteurs, quatre en
99 parrallèle, sur les 10 000 fichiers :
100
101 $ for i in $(seq 10000);do cp README README-$i; done
102 $ find -type f -name 'README*' | xargs -P4 -n1 cmark > /dev/null
103 find -type f -name 'README*' 0,01s user 0,01s system 0% cpu 2,150 total
104 xargs -P4 -n1 cmark > /dev/null 7,48s user 2,28s system 229% cpu 4,247 total
105 $ find -type f -name 'README*' | xargs -P4 -n1 ./katdown > /dev/null
106 find -type f -name 'README*' 0,01s user 0,01s system 95% cpu 0,020 total
107 xargs -P4 -n1 ../katdown > /dev/null 20,72s user 16,74s system 364% cpu 10,282 total
108
109 `katdown` convertit les 10 000 fichiers en un peu plus de 10 secondes, `cmark`
110 en un peu plus de 4 secondes. Il ne semble donc pas y avoir d'overhead
111 significatif au lancement d'awk. Encore moins en utilisant `mawk` avec un temps
112 de génération de 3,5 secondes, plus rapide que `cmark` !
113