katdown

Un traducteur md -> html minimal en awk - retour accueil
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