Le Guide du Hacker Noweb (The noweb Hacker’s Guide)

Ramsey (1994) décrit noweb du point de vue d'un utilisateur, montrant sa simplicité et des exemples d'utilisation.

Les outils de noweb sont implémentés en tant que tubes.

Chaque tube commence par le fichier source noweb.

Les étapes successives du tube mettent en œuvre des transformations simples de la source, jusqu'à ce que le résultat souhaité émerge de la fin du tube.

Les figures 1 et 2 montrent les tubes pour notangle et noweave.

Les tubes permettent d'étendre Noweb, ce qui permet de créer de nouvelles fonctionnalités de programmation sans avoir à écrire leurs propres outils.

Ce document explique comment modifier ou étendre noweb en insérant ou en supprimant des étapes de tube.

Les lecteurs doivent se familiariser avec les pages man de noweb, qui décrivent la structure des fichiers sources de noweb.

Le balisage, qui est la première étape de chaque tube, convertit la source de noweb en une représentation facilement manipulable par des outils Unix communs comme sed et awk, simplifiant la construction des étapes ultérieures du tube.

Les étapes intermédiaires ajoutent des informations à la représentation.

La dernière étape de notangle convertit en code ; Les dernières étapes de noweave convertissent en TeX, LaTeX ou HTML.

Les étapes intermédiaires sont appelées filtres, par analogie avec les filtres Unix.

Les étapes finales sont appelées back ends, par analogie avec les compilateurs - elles ne transforment pas la représentation intermédiaire de noweb ; elles émettent autre chose.

Dans le tube, chaque ligne commence par un signe arobase et l'un des mots-clés du tableau 1.

Les mots-clés structurels représentent directement la syntaxe source Noweb. Ils doivent apparaître dans un ordre qui reflète la structure de la source.

Les mots-clés de marquage peuvent être insérés n'importe où (dans des limites raisonnables) et, à quelques exceptions près, ils ne sont pas générés par le balisage.

Les mots-clés wrapper marquent le début et la fin du fichier, et contiennent des informations sur le formatage à faire en début et en fin de bloc. Ils sont utilisés par noweave mais pas par notangle et ils sont insérés directement par le script shell noweave, et non par le balisage.

Les mots-clés structurels représentent les morceaux de la source Noweb.

Chaque morceau est entouré d'une paire @begin . . . @end et le type de morceau est soit docs soit code. Les @begin et @end sont numérotés ; dans un fichier unique, les numéros doivent être croissants mais n'ont pas besoin d'être consécutifs. Les filtres peuvent changer les numéros de bloc à volonté.

Selon son genre, un morceau peut contenir de la documentation ou du code.

La documentation peut contenir du texte et des retours à la ligne, représentés par @text et @nl.

Elle peut aussi contenir du code cité, encadré par @quote . . . @endquote. Chaque @quote doit être terminée par @endquote dans le même bloc. Le code cité correspond à la construction [[. . . ]] du source de noweb.

Le code, qu'il apparaisse dans le code comme code cité ou dans un bloc de code, peut contenir du texte et des retours à la ligne, ainsi que des définitions et des utilisations de fragments de code, marqués avec @defn et @use.

Le premier mot-clé structurel d'un bloc de code doit être @defn.

@defn peut être précédé ou suivi par des mots clé étiquettes, mais le mot clé structurel suivant doit être @nl ; ensemble, @defn et @nl représentent la ligne <<chunk name>>= qui commence le morceau (y compris le retour chariot final).

Il découle de ce qui vient d'être dit que :

• Le code cité peut ne pas apparaître dans le code, ni dans @defn ni @use. Il est recommandé que noweave traite spécialement les back ends [[. . .]] quand il apparaît dans defn ou use, pour que le texte qu'il contient soit traité comme s'il s'agissait d'un code cité.
• Le texte dans les morceaux peut être distribué en autant de mots-clés @text que désiré. Un nombre quelconque de mots-clés @text vides sont autorisés. En particulier, il n’est pas réaliste d’espérer qu’une seule ligne sera représentée dans un seul @text (voir la discussion de finduses à la page 14).
• markup va parfois émettre @use dans @@quote… @endquote, par exemple à partir d’une source comme [[<<chunk name>>]].
• deux morceaux ne peuvent pas avoir le même numéro.
• comme les filtres suivants peuvent changer les numéros de bloc, aucun filtre ne doit placer des références aux numéros de bloc dans le tube.

Les mots-clés structurels portent tout le code et la documentation qui apparaît dans un fichier source Noweb.

Les mots-clés de marquage contiennent des informations sur ce code ou cette documentation.

Le mot clé @file porte le nom du fichier source d'où viennent les lignes suivantes.

Le mot clé @line donne le numéro de ligne de la prochaine ligne @text suivante dans le fichier en cours (comme déterminé par le mot clé @file le plus récent).

La seule garantie de l'endroit où ils apparaissent est que le balisage introduit chaque nouveau fichier source par un @file qui apparaît entre les morceaux.

La plupart des filtres ignorent @file et @line mais nt les respecte, de sorte que notangle peut correctement numéroter les ligne si un filtre noweb déplace des lignes.

Pour prendre en charge l'indexation automatique ou l'impression de jolis caractères, il est possible d'indiquer le langage de programmation dans lequel un bloc est écrit. Le mot clé @language peut apparaître au plus une fois entre chaque paire @begin code et @end code. Voici les valeurs standard de @language et leurs significations :

Si le mot-clé @language est activé, il peut être utile de créer un registre automatique sur le World-Wide Web.

Il est impossible de placer une information @language directement dans un fichier source noweb.

Les commandes index et cross-reference utilisent des étiquettes, des identifiants et des balises.

Une étiquette est une chaîne unique désignant un élément en programmation lettrée.
Ils servent d'étiquettes ou de « points d'ancrage » pour les étapes finales qui peuvent mettre en œuvre leur propre référence croisée.
Par exemple, l'étape finale LATEX utilise des labels comme arguments pour \label et \ref ; l'étape finale HTML utilise des labels pour nommer des ancres et s'y référer.
Les étiquettes ne contiennent jamais d'espace, ce qui simplifie l'analyse.

Les filtres standards font des références croisées au niveau fragment de code : chaque étiquette se réfère à un fragment de code particulier et toutes les références à ce fragment utilisent la même étiquette.

Un identifiant fait référence à un identifiant de langage source.
Dans Noweb, le concept d'identifiant est général.
Un identifiant est une chaîne arbitraire qui peut même contenir des espaces.
Les identifiants sont utilisés comme clés dans l'index ; les références à la même chaîne sont supposées désigner le même identifiant.

Les balises (Tags) sont des chaînes identifiant les composants de référence croisée dans le document final.
Par exemple, Classic WEB utilise des numéros de section consécutifs pour désigner des segments.
Par défaut, Noweb utilise des références de sous-page, par exemple, 24b pour le deuxième segment apparaissant à la page 24.
Le backend HTML n'utilise aucune balise ; au lieu de cela, il implémente des références croisées en utilisant le mécanisme du lien direct.

La dernière étape de la référence croisée consiste à générer des balises et à associer une balise à chaque étiquette.
Tous les back-ends existants reposent sur un formateur de document pour faire ce travail, mais cette stratégie pourrait être modifiée.
Le calcul des balises dans un filtre Noweb peut être beaucoup plus facile que dans un formateur.
Par exemple, un filtre qui calcule des numéros de sous-pages en cherchant dans des fichiers .aux serait assez facile à écrire, et éliminerait beaucoup de code LATEX.

J'ai divisé les mots-clés d'index en plusieurs groupes. Il semble y avoir pléthore de mots-clés, mais la plupart sont des représentations simples de parties d'un document produit par noweave.

Les lecteurs voudront peut-être avoir un échantillon de la sortie de noweave à portée de main lors de l'étude de ceci et de la section suivante.

La fonction la plus fondamentale des mots-clés de références croisées est d'associer des étiquettes et des pointeurs (références croisées) avec des éléments du document, ce qui est fait avec les mots-clés @xref ref et @xref label. Les autres mots-clés @xref expriment des informations de références croisées de segments qui sont émises directement par un ou plusieurs back-ends.

La référence croisée entre blocs introduit l'idée d'une ancre, qui est une étiquette qui fait référence à un « point intéressant » que nous identifions au début d'un fragment de code.

L'ancre est l'endroit où nous nous attendons à aller lorsque nous voulons connaître un fragment de code ; sa valeur exacte et son interprétation dépendent du back-end utilisé. Le backend LATEX standard utilise le numéro de sous-page du fragment comme point d'ancrage, mais le backend HTML standard utilise un certain @text du bloc de documentation précédant le bloc de code.

Les mots-clés du wrapper, @header et @trailer, sont spéciaux en ce sens qu'ils ne sont pas générés par le balisage ou par l'un des filtres standard ; à la place, ils sont insérés par le script shell noweave au tout début et à la fin du fichier.

Les back ends standard TEX, LATEX et HTML les utilisent pour fournir un balisage de préambule et de postambule, c'est-à-dire un texte standard qui doit généralement entourer un document.

Ils ne sont pas obligatoires (parfois, vous ne voulez pas ce type de message), mais lorsqu'ils apparaissent, ils doivent être les toutes premières et dernières lignes du fichier, et les noms des formateurs doivent correspondre.

Le mot clé d'erreur @fatal indique qu'une erreur fatale s'est produite.

L'étape de tube à l'origine d'une telle erreur donne son nom et un message, et affiche également un message d'erreur standard.

Les filtres qui reçoivent @fatal doivent le copier dans leur sortie et se terminer avec le statut d'erreur.

Le back-end recevant @fatal doit se terminer avec le statut d'erreur. (Ils ne devraient rien écrire sur l'erreur standard puisque cela aura été fait.)

L'utilisation de @fatal permet aux scripts shell de détecter que quelque chose a mal tourné même si le seul statut de sortie auquel ils ont accès est le statut de sortie de la dernière étape d'un tube.

Le mot-clé @literal est utilisé pour pirater la sortie directement dans les back-end, comme totex et tohtml. Ces back ends se contentent de copier le texte dans leur sortie.

Tangle appliqué au back-end ignore @literal.

Le mot-clé @literal est utilisé par les Maîtres pirates trop paresseux pour écrire de nouveaux back ends. Son utilisation est obsolète.

Tous les filtres standard, sauf indication contraire, lisent le format de mot clé noweb sur l'entrée standard et l'écrivent sur la sortie standard.

Certains filtres peuvent également utiliser des fichiers auxiliaires.

Strictement parlant, markup est un frontal, pas un filtre, mais j'en discute avec des filtres car il génère la sortie qui est traitée par tous les filtres.

La sortie de markup représente une séquence de fichiers.

Chaque fichier est représenté par une ligne “@file filename”, suivie d'une séquence de blocs.

markup numérote les blocs consécutivement à partir de 0.

Il reconnaît et annule également la séquence d'échappement pour les doubles crochets, par ex. convertir %%“@<<”%% to %%“<<”%%.

Les seuls mots-clés d'étiquetage trouvés dans sa sortie sont @index defn ou @index nl ; malgré ce qui est écrit à ce sujet, @index use n'apparaît jamais.

J'ai écrit une demi-douzaine de filtres dépendants du langage qui utilisent des heuristiques simples (« analyse fuzzy » si vous préférez) pour essayer d'identifier des définitions intéressantes d'identifiants.

En utilisant le code fourni par Preston Briggs, ce filtre fait deux passes sur son entrée.

La première passe lit toutes les lignes @index defn et @index localdefn et construit un module de reconnaissance Aho-Corasick pour les identificateurs qui y sont nommés.

La seconde passe copie l'entrée, en recherchant ces identifiants dans chaque ligne @text qui est du code.

Lorsqu'il trouve un identifiant, finduses coupe la ligne @text, insérant @index use immédiatement avant la partie @text qui contient l'identifiant que l'on vient de trouver.

Le comportement décrit dupliquerait les éléments @text chaque fois qu'un identificateur serait un préfixe d'un autre.

L'option de ligne de commande -noquote empêche les finduses de rechercher des uses dans du code entre guillemets.

Si finduses reçoit des arguments, il prend ces arguments pour des noms de fichiers, et il lit des listes d'identifiants (un par ligne) à partir des fichiers ainsi nommés, plutôt que sur son entrée.

Cette technique permet à finduses de ne faire qu'un seul passage sur son entrée ; noweave utilise cela pour implémenter l'option -indexfrom.

finduses ne doit pas être exécuté avant les filtres qui, comme les filtres autodefs, s'attendent à ce qu'une ligne soit représentée dans un seul @text.

Les filtres (ou back ends) qui doivent être lancés plus tard, comme les prettyprinters, doivent être préparés pour traiter les lignes fragmentées et en intercalant des tags @index et @xref.

noidx calcule toutes les informations d'index et de références croisées représentées par les mots-clés @index et @xref

L'option de ligne de commande -delay retarde le contenu d'en-tête jusqu'à la fin du premier bloc et amène le contenu final avant le dernier tronçon.

En particulier, il provoque l'émission de la liste des morceaux et de l'index des identifiants avant le dernier bloc.

L'option -docanchor n définit l'ancre d'un fragment de code comme suit :

1. Si un bloc de documentation précède le bloc de code et comporte n lignes ou plus, n lignes à la fin de ce bloc de documentation.
2. Si un bloc de documentation précède le bloc de code et comporte moins de n lignes, au début de ce bloc de documentation.
3. Si aucun bloc de documentation ne précède le bloc de code, au début du bloc de code, comme si -docanchor n'avait pas été utilisé.

Le back-end nt implémente notangle. Il extrait le programme défini par un bloc de code unique (en développant toutes les utilisations pour former leurs définitions) et écrit ce programme sur la sortie standard. Ses options en ligne de commande sont :

Voir la page man de notangle pour plus de détails sur le fonctionnement de nt.

mnt (Multiple NoTangle) est un back-end qui peut extraire plusieurs fragments de code d'un même document en un seul passage.

Il rend le shell Noweb plus efficace.

En plus des options -t et -L reconnues par nt, il reconnaît -all comme une instruction pour extraire et écrire dans les fichiers tous les fragments de code conformes aux règles définies dans la page de manuel noweb.

Il accepte également les arguments, ainsi que les options ; chaque argument est considéré comme le nom d'un fragment de code qui devrait être émis dans le fichier du même nom.

Contrairement à nt, mnt a la fonction de cpif intégrée.

Il écrit dans un fichier temporaire, puis n'écrase un fichier existant que si le fichier temporaire est différent.

Ce back-end émet du code HTML.

Il utilise le formateur html avec @header et @trailer pour émettre un langage HTML approprié.

Pour les autres formateurs (comme none), il n'émet aucun en-tête ni trailer. Ses options de ligne de commande sont :

markup: Convert to tube representation
    autodefs.c: Find definitions in C code
        finduses -noquote: Find uses of defined identifiers
            noidx: Add index and cross-reference information
                totex: Convert to LATEX

Totex implémente les back-ends plain TEX et LATEX, avec @header tex et @header latex pour les distinguer.

Lorsque vous utilisez un en-tête LATEX, totex place le texte optionnel après l’en-tête à l’intérieur d’une commande \noweboptions.

Sur la ligne de commande, l'option -delay fait que totex retarde filename markup jusqu’après le premier bloc de documentation ; ce comportement transforme le premier bloc de documentation en un bloc « limbo », qui peut utilement contenir des commandes comme \documentclass.

L’option -noindex supprime la sortie relative à l’index des identificateurs ; Elle est utilisée pour implémenter noweave -x.

unmarkup tente d’être l’inverse de balisage : un document déjà dans le tube est reconverti en forme source noweb.

Ce back-end est utile pour essayer de convertir les autres programmes lettrés en forme source noweb.

Il peut également être utilisé pour capturer et éditer la sortie d’un module de reconnaissance automatique de définition.

Les commandes standard sont toutes écrites en scripts de shell de Bourne (Kernighan et Pike, 1984).

Elles assemblent des tubes d’Unix à l’aide du balisage et des filtres et dos fins décrits ci-dessus.

Elles sont documentées dans les pages de manuel. Je montre deux exemples de tubes dans les Figures 1 et 2. Le code source est disponible dans le répertoire shell pour ceux qui veulent explorer plus loin.

awk ’BEGIN { line = 0; capture = 0
             format = sprintf("’"$format"’",’"$width"’)
           }

function comment(s) {
    ’"$subst"’
    return sprintf(format,s)
}

function grab(s) {
    if (capture==0) print
    else holding[line] = holding[line] s
}

/^@end doc/ { capture = 0; holding[++line] = "" ; next }
/^@begin doc/ { capture = 1; next }

/^@text /     { grab(substr($0,7)); next}
/^@quote$/    { grab("[[") ; next}
/^@endquote$/ { grab("]]") ; next}

/^@nl$/ { if (capture !=0 ) {
            holding[++line] = ""
        } else if (defn_pending != 0) {
          print "@nl"
          for (i=0; i<=line && holding[i] ~ /^ *$/; i++) i=i
          for (; i<=line; i++)
            printf "@text %s\n@nl\n", comment(holding[i])
          line = 0; holding[0] = ""
          defn_pending = 0
        } else print
        next
     }

/^@defn / { holding[line] = holding[line] "<"substr($0,7)">="
            print ; defn_pending = 1 ; next }
{ print }’

$subst, $format et $width sont des variables du shell utilisées pour adapter le script pour différentes langages.

L’exécution de $subst élimine les marqueurs de fin de commentaire- (le cas échéant) de la documentation et le sprintf initial qui crée le format variable awk donne le format utilisé pour imprimer une ligne de la documentation comme un commentaire.

Je ne donne pas d'exemple de la représentation de tube ; nous allons juste jouer avec les filtres existants. En particulier,

$ noweave -v options inputs >/dev/null

imprime (sur le terminal standard d'erreur) le tube utilisé par noweave pour implémenter un ensemble d’options.

Dans cette section, je donne des exemples de quelques filtres non standard, que j’ai lancés ensemble pour un but ou une autre.

Cette commande sed d'une ligne fait que noweb traite deux noms de fragments comme identiques s'ils ne diffèrent que par leur représentation des espaces :

$ sed -e ’/^@use /s/[ \t][ \t]*/ /g’ -e ’/^@defn /s/[ \t][ \t]*/ /g’

Ce petit filtre, un script shell Bourne écrit en awk (Aho, Kernighan et Weinberger 1988), crée la définition d'un bloc vide (<<>>=) qui est une suite de la définition de bloc précédente.

$ awk ’BEGIN { lastdefn = "@defn " }
/^@defn $/ { print lastdefn; next }
/^@defn /  { lastdefn = $0 }
{ print }’ "$@"

Pour partager des programmes avec des collègues qui ne font pas de programmation lettrée, j'utilise un filtre, illustré à la figure 3, qui place chaque ligne de documentation dans un commentaire et le déplace vers le bloc de code suivant. Avec ce filtre, notangle transforme un programme lettré en un programme commenté traditionnel, sans perte d'information et avec une légère pénalité en termes de lisibilité.

• (en) http://
• (fr) http://

Basé sur « Article » par Auteur.