Un nouveau manuel écrit en AsciiDoc

Partie 2

Page de couverture du manuel de Merlin Project

Ceci est la deuxième partie de mon rapport de projet pour le nouveau manuel de Merlin Project. J'essaierai de faire une mise à jour plus ou moins courte du projet chaque vendredi.

Le projet

Avant de nous plonger dans AsciiDoc, voici un aperçu de mon projet.

Le dépôt Git a été mis en place.
Les lignes sont définies et certaines d'entre elles sont listées ici aussi.
Les prérequis sont connus dans la mesure où ils vont jusqu'au bout.
Une première ébauche a été créée et va maintenant être affinée progressivement.
Comme images, je n'utiliserai d'abord que des captures d'écran rapides, puis je les recréerai si nécessaire.
Un jour de semaine pour l'écriture est fixé.

Le dernier point en particulier a été un véritable défi pour moi, car je dois trouver le temps d'écrire. Si je prends juste chaque minute disponible, je ne finirai probablement jamais. J'ai besoin d'un bloc de temps fixe et c'est exactement ce que j'ai créé. A partir de maintenant, le mercredi est mon jour d'écriture manuelle. Voyons combien de temps cela va durer...

Bien sûr, il y a un tableau Kanban. Désolé pour la langue anglaise - nous faisons beaucoup de documentation interne en anglais.

Conseils d'AsciiDoc

Fractionnement des fichiers

Je ne crée pas le manuel en un seul fichier, mais je préfère le diviser chapitre par chapitre. Je stocke également les variables et les attributs de mon manuel dans un fichier séparé afin de pouvoir construire les fichiers individuellement ou les visualiser dans le navigateur et utiliser toutes les variables et tous les attributs. Ce fichier s'appelle généralement Attributs et pour que je puisse toujours le trouver rapidement, on lui donne un "_" et il apparaît donc toujours au début de la liste des fichiers.

ifndef::_attributes[]
include::_attributes.de.adoc[]
endif::[]

Ici, je demande si la variable _attributs est déjà définie.
Si non, le fichier est inclus.

De cette façon, je m'assure que le fichier d'attributs n'est pas chargé plusieurs fois, car chaque fichier commence par ces lignes.

Mon retournement rapide

Pour l'instant, j'écris encore le manuel seul, mais tous les textes et médias vont dans Git. Cela signifie que ma rédaction matinale commence dans le terminal, ou - selon ce que j'ai sous la main - dans BBEdit Unix Worksheet, par un fougueux git pull. J'ouvre ensuite le fichier du projet BBEdit (qui est inclus dans le dépôt, bien sûr) et je vois tous les fichiers inclus dans la liste de gauche.

Je divise l'écran en deux : J'écris à gauche et j'ai Chrome ouvert à droite. Dans la fenêtre du navigateur, je fais simplement glisser l'icône du proxy du fichier édité. Grâce à l'extension Asciidoctor.js, le navigateur est mis à jour à chaque sauvegarde dans BBEdit.