Un nuevo manual escrito en AsciiDoc
Parte 4
Esta semana por fin ha vuelto a funcionar. Mi plan con las fases de tiempo bloqueado en el calendario se puso en marcha. El miércoles pude escribir casi continuamente.
En el proceso, me he dado cuenta de algunas pequeñas cosas en AsciiDoc que me gustaría compartir con vosotros.
Secciones localizadas
Desgraciadamente, algunas secciones como el índice, la tabla de imágenes, el glosario, la bibliografía, etc. no están traducidas. El primer paso es definir la lengua:
:lang: es
Por desgracia, esto no es suficiente. Un archivo específico del alcance de la entrega de Asciidoctor (aquí en Github) debe ser incluido:
// Include your own path for the attributes:include::../locale/attributes.adoc[]
Sólo entonces aparecerán todos los nombres de las secciones estándar en el idioma deseado.
Repeticiones del nombre del programa
Claro, en principio, las repeticiones no son buenas. Pero en un manual es inevitable que el nombre del producto se repita a menudo. Así que me inventé rápidamente una variable:
:mp: Merlin Project
Así es como utilizo la variable:
¡Bienvenido a {mp}!
Resultado:
¡Bienvenido a Merlin Project!
Y otra bonificación: He puesto un espacio protegido entre Merlin y Project (en BBEdit es la combinación de teclas ⌥ + espacio). Entonces, el nombre del programa nunca se rompe en la ruptura.
Nombres de los menús y atajos de teclado
En la naturaleza de un manual de software se encuentra la descripción de la interfaz y su funcionamiento. Aquí, por supuesto, uno puede establecer sus propias normas y poner los elementos en cursiva o negrita. Pero hay una gran alternativa en AsciiDoc. Para ello, sin embargo, hay que anunciar primero el uso con un interruptor especial.
:experimental:
Por cierto, aunque el interruptor se llame experimental, la función ya está totalmente establecida. Aquí hay un comentario de Dan Allen al respecto.
Ahora los elementos del menú se escriben con una notación especial:
Un clic en menu:Ayuda[Ayuda Dinámica] inicia el Globo de Ayuda.
Resultado:
Un clic en Ayuda->Ayuda Dinámica inicia el Globo de Ayuda.
Por supuesto, el formato de los elementos del menú puede adaptarse en los estilos.
Funciona de forma similar con los atajos, los atajos de teclado. Esta es la notación:
kbd:[⌘ + N]
Resultado:
⌘ + N.
Es aún más fácil si pones las entidades HTML en variables. Encontré las entidades HTML más importantes para los ordenadores Apple en StackExchange:
:commandkey: ⌘:optionkey: ⌥:controlkey: ⌃:shiftkey: ⇧:enterkey: ⌤:enterkey: ⌤:returnkey: ⏎:deletekey: ⌫:rightkey: →:leftkey: ←:upkey: ↑:downkey: ↓
Ahora su aportación es justa:
Pulse Sie kbd:[{commandkey} + Q] para iniciar el fin de semana.
Resultado:
Pulse ⌘ + Q para iniciar el fin de semana.
En este sentido - hasta la próxima semana ...
