Publication multicanal à source unique avec Markdown

Publié le 1 juin 2023 par Andrew Owen (5 minutes)

Cette semaine, j’ai terminé la version bêta finale de l’interpréteur BASIC classique sur lequel j’ai travaillé pour le projet d’ordinateur rétro Chloe 280SE FPGA. Comme beaucoup d’ordinateurs personnels des années 1970 au début des années 1990, lorsque vous l’allumez, vous entrez directement dans l’éditeur BASIC. Mais contrairement à la plupart des ordinateurs personnels de la même époque, il dispose d’une capacité de stockage illimitée. Cela signifie qu’il peut inclure une aide intégrée, une fonction que Microsoft n’a pas ajoutée à QuickBASIC avant 1987.

Bien qu’il s’agisse d’un projet rétro, il n’y a aucune raison de limiter le développement à ce qui était disponible à l’époque. Mais le microprocesseur est encore incroyablement limité par rapport aux normes modernes. Un format de document léger est donc crucial pour un système d’aide réactif, et le choix logique est donc Markdown. C’est également un bon choix car toute la documentation actuelle est dans un wiki GitHub au format Markdown, ce qui signifie que le contenu peut être réutilisé.

Il y a quelques limitations techniques à prendre en considération. La Chloé a un écran de 80×24 caractères avec une police à largeur fixe. Et le wiki est actuellement composé de neuf fichiers, chacun équivalant à un chapitre du guide de l’utilisateur. Ces fichiers sont trop volumineux pour être chargés en une seule fois avec un espace d’adressage de 64 kilo-octets. De plus, avec un affichage basé sur le texte et sans souris, les utilisateurs devront taper les noms des liens du wiki. La solution logique consiste donc à diviser le contenu en composants. Chaque document est décomposé en sections et en rubriques individuelles. Contrairement à un véritable système de création de composants, les niveaux de rubriques sont fixes. Mais la décomposition des chapitres en composants facilite la réutilisation du contenu. Par exemple, les descriptions des fonctions et des instructions BASIC peuvent être utilisées dans un document de référence rapide distinct. Et si la syntaxe change, lorsque les documents sont republiés, les changements sont répercutés partout.

Nous disposons donc désormais d’une source unique entre le wiki GitHub et l’aide intégrée. Mais qu’en est-il d’un manuel imprimé: Comment passer d’une énorme collection de fichiers Markdown à un PDF ou à d’autres formats tels que EPUB, HTML ou Word: La réponse est Pandoc, un convertisseur de documents open-source créé par John MacFarlane, professeur de philosophie à Berkeley. Il peut importer des documents à partir d’un large éventail de sources et prend en charge de nombreux formats de sortie. Cependant, pour le format PDF, il s’appuie sur LaTeX pour le formatage, vous devrez donc également l’installer.

Comme toujours, je recommande l’installation en utilisant Homebrew sur macOS et Scoop sur Windows. Pandoc est inclus dans les dépôts de la plupart des variétés de Linux. Sur macOS, il y a un élément supplémentaire à prendre en compte: l’installation complète de LaTeX utilise quatre gigaoctets de stockage. Donc, à moins que vous n’ayez besoin de toutes les fonctionnalités, vous devriez utiliser BasicTeX à la place.

brew install pandoc
brew install librsvg python homebrew/cask/basictex

L’étape suivante consiste à créer un conteneur pour votre contenu, sous la forme d’un ensemble de paramètres pour Pandoc. Celui-ci contient votre table des matières et toutes les directives LaTeX supplémentaires pour définir des éléments tels que les images de couverture et la taille des pages. Pour plus de commodité, je l’ai placé dans un fichier makefile afin de pouvoir l’appeler à partir de la ligne de commande en utilisant make. J’ai également créé deux fichiers texte contenant des directives LaTeX. Ceux-ci peuvent être stockés à la racine du dépôt, et ils n’apparaîtront pas dans le wiki GitHub (vous pouvez obtenir le lien de clonage git pour le dépôt lorsque vous affichez le wiki dans votre navigateur). Il y a plusieurs façons de configurer LaTeX, mais la plus simple est d’ajouter un en-tête YAML à un fichier que vous enregistrez avec une extension .txt.

---
 titlepage: true
 title: "Programming SE Basic IV"
 author: "Rob Hagemans"
 date: \today
 subtitle: "Cordelia 4.2.0"
 subject: "Classic BASIC Programming"
 keywords: "BASIC"
 toc: true
 numbersections: true
 geometry: margin=2cm
 urlcolor: blue
 header-includes: |
    \lfoot{SE Basic IV}
    \rfoot{Cordelia 4.2.0}    
---

Cet exemple fournit une page de titre et inclut quelques métadonnées et informations de formatage pour le PDF.

J’ai également créé un fichier texte pour produire un saut de page entre les chapitres. Il ne contient qu’une seule ligne.

\newpage

Et voici un exemple partiel de fichier makefile.

prg:
	pandoc --toc --output "Programming SE Basic IV.pdf" -s \
	cover.txt \
	newpage.txt BASIC.MD \
					FUNCTION.MD \
						ABS.MD ACOS.MD ASC.MD ASIN.MD ATAN.MD CHRS.MD COS.MD \
						DEEK.MD EXP.MD FIX.MD FN.MD INKEYS.MD INP.MD INT.MD \
						LEFTS.MD LEN.MD LOG.MD MIDS.MD PEEK.MD RIGHTS.MD \
						RND.MD SGN.MD SIN.MD SQR.MD STRS.MD STRINGS.MD TAN.MD \
						USR.MD VAL.MD VALS.MD \
					STATEMEN.MD \
						BLOAD.MD BSAVE.MD CALL.MD CHDIR.MD CIRCLE.MD CLEAR.MD \
						CLOSE.MD CLS.MD COLOR.MD CONT.MD COPY.MD DATA.MD \
						DEF_FN.MD DELETE.MD DIM.MD DOKE.MD DRAW.MD EDIT.MD \
						ELSE.MD END.MD ERROR.MD FILES.MD FOR.MD GOSUB.MD \
						GOTO.MD IF.MD INPUT.MD KEY.MD KILL.MD LET.MD LINE.MD \
						LIST.MD LOAD.MD LOCATE.MD MERGE.MD MKDIR.MD NAME.MD \
						NEW.MD NEXT.MD OLD.MD ON.MD ON_ERROR.MD OPEN.MD OUT.MD \
						PALETTE.MD PLAY.MD PLOT.MD POKE.MD PRINT.MD \
						RANDOMIZ.MD READ.MD REM.MD RENUM.MD RMDIR.MD RUN.MD \
						SAVE.MD SCREEN.MD SOUND.MD STOP.MD TRACE.MD WAIT.MD \
						WEND.MD WHILE.MD \
	newpage.txt LICENSE.MD

Les barres obliques inverses concatènent tout le texte en une seule ligne de commande, mais vous voulez pouvoir lire votre table des matières. L’insertion de newpage.txt avant chaque chapitre fait commencer celui-ci sur une nouvelle page. Les niveaux de titres sont tirés des fichiers Markdown, de sorte que vous ne pouvez insérer du contenu qu’au niveau de titre approprié. Par conséquent, le contenu réutilisable doit avoir un niveau de titre minimum de trois (`###`) ou quatre (`####`).

Ensuite, vous entrez dans make et, à condition que vos noms de fichiers ne contiennent pas de caractères shell et que votre markdown soit valide, vous obtiendrez un PDF à partir de votre wiki avec une page de couverture et une table des matières. Ce n’est pas très sophistiqué, mais cela devrait suffire pour des projets open source simples.