By using our website you agree that we use cookies. More information

| Convenir

Blog

Un nouveau manuel écrit en AsciiDoc

Partie 1

Page de couverture du manuel de Merlin Project

Nous optimisons constamment Merlin Project pour le rendre plus facile à utiliser. Nous avons déjà commencé il y a quelque temps avec le dialogue de départ et le nettoyage de l'inspecteur.

Avec la version 8, l'aide dynamique est maintenant arrivée : Il suffit de cliquer sur le symbole ? pour obtenir un texte d'aide explicatif pour chaque objet que vous pointez avec la souris (ou avec votre doigt sur l'iPad). Vous pouvez même créer vos propres textes d'aide pour vos propres champs.

Mais malheureusement, notre manuel est un peu en retard. Mais ne vous inquiétez pas, il existe une documentation abondante et à jour, telle que :

Mais un manuel complet n'existe pas pour l'instant. Et c'est exactement ce que je voudrais changer maintenant.

Le projet

J'ai récemment commencé à réécrire le manuel et à créer cette référence. Bien sûr, j'ai mis en place un projet pour cela, mais malheureusement, il doit partager le temps disponible avec tous mes autres projets.

L'objectif

Outre l'objectif évident de créer une documentation à jour des fonctions de Merlin Project dans les (link: support/faq/usage/language text: langues les plus importantes, je me suis fixé quelques autres sous-objectifs ou sous-objectifs :

  • Le manuel doit être disponible en HTML, PDF et eBook.
  • L'impression à la demande doit être possible en tant qu'option.
  • Le manuel devrait s'appliquer à tous nos produits, donc :
  • Il sera proposé gratuitement sur notre site web, sur la librairie iTunes et sur d'autres sites.

Cependant, la date cible est totalement ouverte à toute planification, car j'ai une charge de travail différente d'une semaine à l'autre. Une date fixe comme objectif serait donc totalement irréaliste.

Les outils

Chez ProjectWizards, nous écrivons tous les textes au format ascii et les enregistrons dans notre git au plus tard en fin de journée.

Contrairement à la mode actuelle, nous n'écrivons pas en Markdown ou l'un de ses dérivés ou suppléments. Nous nous sommes déjà intéressés à AsciiDoc il y a très longtemps et depuis quelques années à Asciidoctor, la nouvelle implémentation de Dan Allen (via Twitter). Les raisons de cette décision sont principalement :

  • Variables,
  • la liaison d'autres fichiers,
  • textes et formatages conditionnels,
  • des tableaux, des diagrammes et de nombreux autres contenus,
  • sortie de texte dans de nombreux formats différents,
  • des tables des matières automatiques, ainsi que des glossaires, des index et des bibliographies
  • et bien plus encore ...

Et avant que j'oublie, bien sûr, BBEdit est toujours défini comme éditeur #1 pour moi.

AsciiDoc vs Asciidoctor

En bref, vous donnez la source AsciiDoc à Asciidoctor et obtenez un résultat que vous pouvez publier. Donc :

  • AsciiDoc est la langue
  • Asciidoctor est le processeur

Comme Markdown, AsciiDoc a été conçu comme un langage pour être discret et concis, et pour rendre l'écriture plus facile, voire plus agréable. Mais AsciiDoc lui-même n'est pas un format de publication. Il s'agit plutôt d'un raccourci. C'est là qu'intervient un processeur AsciiDoc.

Un processeur AsciiDoc, tel qu'Asciidoctor, lit le texte source AsciiDoc et le convertit en formats publiables tels que HTML 5, eBook ou PDF. Bien entendu, l'ensemble du processus est complété par des outils de conception tels que les feuilles de style en cascade (CSS).

Travailler à voix haute (WOL)

Conformément à l'esprit de Working out Loud, j'essaierai de rendre compte régulièrement de ce travail. Je mettrai moins l'accent sur le nombre de mots ou de phrases que j'ai pu écrire pendant la semaine. Je suis beaucoup plus intéressé par la présentation des aides et des nouvelles perspectives d'Asciidoc et d'Asciidoctor.

Avec cette approche, je rends bien sûr hommage au travail inlassable de Dan Allen et je le soutiens. Au moins autant, c'est un vote pour Asciidoc dans la gestion de projet.

Vendredi prochain, nous commencerons à ce point.


Continuation - Un nouveau manuel en AsciiDoc, partie 2

Publié par Frank Blome le 08.10.2021 dans Interne
Mots-clés: asciidoc asciidoctor projet-manuel wol

Merlin Project sur Mac et iPad

Vos idées, notre magie – Réalisez vos projets en toute simplicité!
Essayez maintenant gratuitement pendant 30 jours.