Un nouveau manuel écrit en AsciiDoc
Partie 4
Cette semaine, il a finalement marché à nouveau. Mon plan avec les phases de temps bloqué dans le calendrier a fonctionné. J'ai pu écrire presque sans interruption le mercredi.
Au cours de ce processus, j'ai remarqué quelques petites choses dans AsciiDoc que j'aimerais partager avec vous.
Sections localisées
Malheureusement, certaines sections telles que la table des matières, la table des images, le glossaire, la bibliographie, etc. ne sont pas traduites. La première étape consiste à définir la langue :
:lang: fr
Cependant, ce n'est pas encore suffisant. Un certain fichier de la portée de la livraison de Asciidoctor (ici sur Github) doit être inclus :
// Include your own path for the attributes:include::../locale/attributes.adoc[]
Ce n'est qu'alors que tous les noms de sections standard apparaîtront dans la langue souhaitée.
Répétitions du nom du programme
Bien sûr, en principe, les répétitions ne sont pas bonnes. Mais dans un manuel, il est inévitable que le nom du produit soit souvent répété. J'ai donc très vite inventé une variable :
:mp: Merlin Project
Voici comment j'utilise la variable :
Bienvenue à {mp}!
Résultat :
Bienvenue à Merlin Project!
Et un autre bonus : J'ai mis un espace protégé entre Merlin et Project (dans BBEdit, il s'agit de la combinaison de touches ⌥ ; + espace). Ensuite, le nom du programme n'est jamais déchiré dans la rupture.
Noms des menus et raccourcis clavier
Dans la nature d'un manuel pour logiciel se trouve la description de l'interface et de son fonctionnement. Ici, bien sûr, on peut établir ses propres normes et mettre les éléments en police italique ou gras. Mais il existe une excellente alternative avec AsciiDoc. Mais pour cela, il faut d'abord annoncer l'utilisation avec un interrupteur spécial.
:experimental:
D'ailleurs, même si l'interrupteur est appelé experimental, la fonction est déjà bien établie. Voici un commentaire de Dan Allen à ce sujet.
Les éléments du menu sont maintenant écrits avec une notation spéciale :
Un clic sur menu:Aide[Aide dynamique] lance l'Aide Ballon.
Résultat :
Un clic sur Aide->Aide dynamique lance l'Aide Ballon.
Bien entendu, le formatage des éléments de menu peut être adapté dans les styles.
Cela fonctionne de la même manière avec les raccourcis, les raccourcis clavier. Voici la notation :
kbd:[⌘ + N]
Résultat :
⌘ ; + N.
C'est encore plus facile si vous placez les entités HTML dans des variables. J'ai trouvé les entités HTML les plus importantes pour les ordinateurs Apple sur StackExchange :
:commandkey: ⌘:optionkey: ⌥:controlkey: ⌃:shiftkey: ⇧:enterkey: ⌤:enterkey: ⌤:returnkey: ⏎:deletekey: ⌫:rightkey: →:leftkey: ←:upkey: ↑:downkey: ↓
Maintenant, votre contribution est juste :
Appuyez sur kbd:[{commandkey} + Q] pour commencer le week-end.
Résultat :
Appuyez sur ⌘ ; + Q pour commencer le week-end.
Dans ce sens - jusqu'à la semaine prochaine ...
