Puliendo Extensiones

Introducción

Existen hoy cerca de un centenar de extensiones I7 disponibles al público en el sitio oficial. En ese tiempo, han trascendido algunas brillantes ideas de desarrollo y son ellas las que se exponen aquí en formato checklist.

El archivero oficial de extensiones lo encuentras en i7extensions@smallwhitehouse.org

Nota: Este artículo es una traducción libre de un artículo similar en la página oficial. Este artículo se publicó por primera vez en SPAC.

Checklist

A - Supongamos que has escrito una nueva extensión, y estás próximo a terminarla...

- ¿Tienes escrito el epígrafe de la extensión?
- Si tu extensión está dirigida a una máquina virtual en particular, ¿lo has indicado apropiadamente así?
- ¿Tu extensión incluye comandos de testeo?
- ¿Tienen las nuevas acciones soporte para cualquier personaje en lugar de solo el jugador?
- ¿Le has dado nombre a todas las reglas nuevas?
- ¿Has hecho las cosas fáciles para que otros autores puedan reemplazar el texto de salida que imprima tu extensión?
- ¿Has escrito documentación?
- ¿Menciona tu documentación cualquier dependencia que necesites?
- Si tu extensión es de las complejas o muy largas, ¿está la documentación dividida en secciones?
- ¿Has incluido al menos un ejemplo que muestre cómo trabaja tu extensión?
- ¿Has testeado dicho ejemplo para asegurarte que corre correctamente?
- ¿Tiene el ejemplo el botón de pegar?
- ¿Tiene el ejemplo al menos un script de testeo?
- Si tu extensión es amplia o maneja varios efectos, ¿has incluido más de un ejemplo?

B - Supongamos que tu extensión cumple con todo y quieres publicarla en el sitio oficial de Inform...

- Si tu extensión es compleja, ¿le has pedido a alguien más que la pruebe y testee?
- ¿Comprendes las implicancias de la licencia Creative Commons?
- ¿Has incluido tu extensión en el email como archivo de texto?
- ¿Has incluido una reseña para poner en el sitio web?

Notas aclaratorias

A - Supongamos que has escrito una nueva extensión, y estás próximo a terminarla...

¿Tienes escrito el epígrafe de la extensión?

Aclarando: El epígrafe es la porción de texto que se muestra (en el IDE de I7) inmediatamente después del título, como en

“Implementa rigurosamente los sabores y olores de las 39 variedades de queso”

Nota: Este texto se muestra también cuando el autor pasa el puntero del mouse por encima del nombre de la extensión en la lista de extensiones instaladas. Esto le facilita la búsqueda de lo que necesite.

Si tu extensión está dirigida a una máquina virtual en particular, ¿lo has indicado apropiadamente así?

Aclarando: La especificación de máquina virtual debe aparecer entre paréntesis después del título de la extensión. Algo como

Version 4 of Advanced Wine Pairings (for Glulx only) by Emily Short begins here.

Nota: Le ahorrarás tiempo y frustración a los autores si dejas en claro qué VM aceptará tu extensión. Fíjate que si tu extensión depende de otra, que solo trabaja con determinada VM, entonces deberías setearla de igual manera.

¿Tu extensión incluye comandos de testeo?

Aclarando: Por ejemplo, una sección marcada como “not for release” puede incluir uno o más comandos de testeo y depuración. Algo como el comando de fábrica SHOWME, que imprima algunos datos relevantes que tu extensión esté manejando internamente. O algo como ACTIONS, que activa un modo en donde la extensión te va diciendo qué está pasando. Como se trata de comandos definidos en una sección “not for release”, ya no estarán disponibles al publicar el juego. Es bueno emplear nombres bien específicos para dichos comandos y que no entren en conflicto con cualquier posible comando que posteriormente el autor invente y utilice en su aventura. Por ejemplo, ni se te ocurra crear un comando de depuración llamado MIRAR. También es una buena idea que documentes (brevemente) todos los comandos de testeo disponible, quizás al final de la documentación general de tu extensión.

Nota: Las extensiones sencillas quizás no necesiten comandos de testeo, pero frecuentemente sucede que el tiempo que gastes en crearlos tiene su recompensa a la hora de depurar casos que inicialmente no se tuvieron en cuenta. Recuerda que Inform está en constante evolución y que la sintaxis y otras convenciones cambian con el tiempo. A veces una extensión podría entrar en conflicto con otra, y el pobre autor se encontrará frente a un problema nuevo en muchas más ocasiones de lo que crees. Hay extensiones para Inform 6 escritas a principios de los 90 que continúan aún siendo utilizadas en ciertos círculos, y que son mantenidas por personas diferentes al autor original. Si tu extensión es útil, podrá tener una larga vida de la mano de los estándares de software. Si la haces fácil de mantener, esto podría facilitarte mucho las cosas para ti o tus sucesores.

¿Tienen las nuevas acciones soporte para cualquier personaje en lugar de solo el jugador?

Aclarando: Las reglas aplicadas al jugador son algo como:

Check manufacturing a cheese: ...

Las reglas aplicadas a un personaje son algo como:

Check someone manufacturing a cheese: ...

Y las reglas aplicadas a ambos....

Check an actor manufacturing a cheese: ...

Si tu extensión agrega nuevas acciones al juego, impleméntalas de manera que los demás personajes también puedan ejecutarlas. Las extensiones de fábrica Locksmith yRideable Vehicles hacen esto, por si quieres pegarles un vistazo.

Nota: Cada una de las acciones que ya trae Inform funciona para todos los personajes, es decir, cualquier persona puede ser el actor. Esto quiere decir que los autores (y las demás extensiones) asumen que cualquiera puede ejecutar cualquier acción, abriendo el panorama a muchas posibilidades y a efectos interesantes (se da el caso del modelo orientado a personaje en vez del viejo modelo basado en puzzles, y ahora con ello la aventura tiende a involucrar a otras personas además del jugador para planear qué hacer y ejecutar el plan usando acciones.) Un autor que escribe su aventura puede decantarse en acciones pensadas solo para el personaje jugador, ya que él conoce bien lo que necesita en el mundo de su juego. Pero una extensión nunca puede saber qué ocurrirá en los trabajos que la utilicen.

¿Le has dado nombre a todas las reglas nuevas?

Aclarando: En tu extensión, las reglas nunca deberían tener este especto:

Instead of smelling a washed-rind cheese:

say "Whew, that's strong."

Sino más bien:

Instead of smelling a washed-rind cheese (this is the washed-rind cheeses stink rule):

say "Whew, that's strong."

This is the washed-rind cheeses stink rule: ...

Inform requiere que los nombres de las reglas terminen con la palabra “rule”. Además, hay convenciones para ponerles nombre: trata de imitar el estilo usado en los incontables ejemplos del panel Index>>Actions. Por ejemplo, una regla que impida la ejecución de una acción normalmente empieza su nombre con “can’t…”, como en "can’t take what you’re inside rule". Los nombres de tus reglas tienen que ser específicos para que no se superpongan con las reglas de otras extensiones que también se usen en la aventura, así que no utilices nombres como "the bad object rule".

Nota: Los autores podrán manipular tus reglas (reemplazarlas o moverlas) solo si estas tienen nombre. Esto le dará más facilidad y usabilidad a tu extensión en un amplio rango de sistemas. Usar reglas con nombre también facilita la depuración, ya que el comando ACTIONS podrá decirte qué regla detiene las acciones, por ejemplo.

¿Has hecho las cosas fáciles para que otros autores puedan reemplazar el texto de salida que imprima tu extensión?

Aclarando: Los textos pueden reemplazarse (razonablemente) si aparecen en una tabla o en variables; o si se usan en reglas aisladas, como:

Table of Cheese Flavors

variety flavor

gruyere "Faintly nutty."

The Gruyere-flavor message is some text that varies. The Gruyere-flavor message is "Faintly nutty."

A gruyere has some text called the flavor. The flavor of a gruyere is usually "Faintly nutty."

Report eating a gruyere (this is the gruyere-flavor rule):

say "It tastes faintly nutty." instead.

Rule for giving flavor of a gruyere:

say "It tastes faintly nutty."

Es más difícil de reemplazar el texto que aparece entremezclado en una maraña de código dentro de una regla. Si hace falta cambiar el texto durante el juego, las mejores opciones pueden ser tablas, variables y reglas (en ese orden). Las tablas serán tu elección si esperas que el autor agregue (en lugar de reemplace) el material que tu ya provees, ya que él puede continuar la tabla en su propio código. De lo contrario, las reglas y rulebooks son las maneras más fáciles de ayudar al usuario a modificar el comportamiento de tu extensión. Por ejemplo, lo siguiente:

Giving flavor is an object-based rulebook. Rule for giving flavor of a gruyere (this is the gruyere-flavor rule): say "Sabe ligeramente a nuez." Rule for giving flavor (this is the unspecified-flavor rule): say "Tiene un sabor suave."

Report eating a cheese sample (called the hunk): consider the giving flavor rules for the hunk.

Podría ser traducido a otro idioma, o cambiado por otro texto, simplemente reemplazando las dos reglas “giving flavor” por otras del mismo nombre, e inclusive el usuario podría agregar nuevas e interesantes reglas para cubrir otros casos y tamaños.

Nota: Es probable que lo que más quieran hacer los usuarios sea cambiar algunos textos de tu extensión, más que cualquier otro aspecto o comportamiento. Quizás quieran usar la misma lógica, pero escribir el juego en otro idioma, o cambiar todas las menciones de “Tu…” en la prosa. Harás tu extensión mucho más útil si es fácilmente modificable en este sentido.

¿Has escrito documentación?

Aclarando: Cada extensión puede incluir fácilmente su documentación, sin tantas vueltas o archivos extras. Simplemente debe incluir una sección especial de texto para beneficio del usuario. Pueden agregarse códigos de ejemplo que usen tu extensión, parecidos a los ejemplos de la ayuda de Inform. Fíjate en la sección sobre Extensiones y documentación de extensiones para darte una idea, y revisa el ejemplo “Modern Conveniences” donde se discute qué tipo de información es útil incluir en la documentación.

Nota: La documentación de la extensión es procesada por Inform e incluida automáticamente en la documentación en línea tan pronto como es instalada y usada. Los usuarios esperan esto, pues normalmente no pueden leer y entender fácilmente el código de la extensión, ni aunque quisieran. En la práctica, nunca usarán demasiado una extensión que no provee documentación. Una extensión no está completa sin ella.

¿Menciona tu documentación cualquier dependencia que necesites?

Aclarando: Algunas extensiones necesitan a su vez incluir a otras extensiones: esto se llama dependencia. Dependencia no es una mala palabra; la filosofía de diseño de las extensiones está basada en la vinculación de pequeñas piezas que contribuyen al todo.

Nota: Si la extensión que necesitas ya viene con Inform (como la "Basic Screen Effects by Emily Short"), puedes estar seguro de que el usuario la tendrá a mano. Pero si no es el caso, entonces deberá descargarla y tú educadamente lo dejarás claro en la documentación.

Si tu extensión es de las complejas o muy largas, ¿está la documentación dividida en secciones?

Aclarando: Esta habilidad fue agregada en la edición 4X60, en el verano (boreal) de 2007 y no es difícil sacarle provecho, con Inform generando automáticamente la tabla de contenidos.

¿Has incluido al menos un ejemplo que muestre cómo trabaja tu extensión?

Aclarando: Puedes incluir ejemplos de demostración para tu extensión, parecidos a los ejemplos del manual en línea. Revisa la sección "Examples and headings in extension documentation" del manual para ver cómo hacerlo.

Nota: Veamos sus ventajas: por un lado, con esto a los autores se les hará más fácil entender y aplicar tu trabajo. Se darán cuenta de un vistazo que tu extensión hace lo que realmente dice que hace. Los ejemplos constituyen la vidriera de tu trabajo.

Otro beneficio es que los ejemplos ayudan a que tu extensión no quede desfasada ante cada actualización de Inform. Cuando se genera una nueva versión de Inform, la bibliotecaria ejecuta un script automático que prueba todos los ejemplos de todas las extensiones disponibles. Si encuentra errores de compilación, puede informarte que tu extensión necesita actualización, o incluso actualizar y subir la versión revisada ella misma (con tu permiso y si el cambio requerido es mínimo). Los ejemplos también te ayudan a probar tu extensión luego de hacerles ‘mejoras’.

¿Has testeado dicho ejemplo para asegurarte que corre correctamente?

Aclarando: Un error común es crear el ejemplo pero no agregar correctamente la línea que incluye tu extensión. Asegúrate de que "Include Productos Lácteos by John Moo." está presente.

¿Tiene el ejemplo el botón de pegar?

Aclarando: El botón de pegar le facilita al usuario la tarea de probar tu extensión.

¿Tiene el ejemplo al menos un script de testeo?

Aclarando: Para dar al usuario una muestra rápida de lo que el ejemplo puede hacer, bien podrías incluir una línea tipo “test me”, como las que se encuentran en los ejemplos del manual, por ejemplo:

Test me with "eat roquefort / smell gruyere / taste gruyere".

Nota: Esto no solo le sirve al usuario, sino que también es una forma automática de testear cualquier comportamiento que se supone pueda darse. Sin estos ‘casos de testeo’ todo lo que podemos hacer para chequear la extensión luego de una nueva versión de Inform es ver si todavía compila. Por ello un ejemplo no está realmente completo sin un script de testeo (test script).

Si tu extensión es amplia o maneja varios efectos, ¿has incluido más de un ejemplo?

Aclarando: Es una buena idea tener un primer ejemplo sencillito (de una estrella), pero sólo para mostrar al usuario cuan fácil es comenzar a usar la extensión. Puedes continuar entonces con algo más sustancial y complicado. Recuerda que lo que a ti te parece familiar, en realidad es más sintaxis nueva que se deben aprender los usuarios que recién empiezan: ofrecer una rápida gratificación usando ejemplos de complejidad creciente los animará luego a profundizar más en las posibilidades. Esa es la razón por la que la extensión "Locksmith by Emily Short" trae cuatro ejemplos.

B - Supongamos que tu extensión cumple con todo y quieres publicarla en el sitio oficial de Inform...

Si tu extensión es compleja, ¿le has pedido a alguien más que la pruebe y testee?

Aclarando: Las extensiones complejas merecen pasar por un beta testeo, tal como cualquier juego. Cualquier buen chico usuario de I7 podrá darte informe respecto a si la documentación es fácil de entender o si la extensión provee un rango de funcionalidades realmente útil.

Por favor no le pidas a los bibliotecarios que beta-testeen tu extensión. Podría parecer un pequeño favor, pero hay tantas extensiones nuevas, muchas veces surgiendo todas juntas, que los bibliotecarios ya tienen bastante tarea que hacer.

¿Comprendes las implicancias de la licencia Creative Commons?

Aclarando: Las extensiones que se publican en el sitio web oficial de I7 lo hacen bajo licencia de Atribución Creative Common (más detalles en la web de inform, sección extensiones). Si no estás de acuerdo con esta licencia – la cual permite que tu trabajo pueda ser modificado, distribuido e incorporado en productos comerciales- entonces no lo subas a la web de Inform.

Esto no tiene que ver con alguna ideología de los escritores de Inform: solo refleja las costumbres ancestrales de la comunidad IF y busca hacer el sitio web de fácil comprensión para los usuarios. No obstante, eres bienvenido a que publiques la noticia de tu extensión; alojada en cualquier otro sitio con la licencia que te plazca (por favor, deja en claro los términos de dicha licencia).

Si ya tienes publicada una extensión en la web de inform pero has cambiado de parecer respecto a la licencia, puedes proveer el link a las versiones subsiguientes con la licencia de tu elección. La licencia de CC no se aplicará a esas versiones. Pero no podrás eliminar la vieja versión del sitio web de inform: no sería justo para los usuarios que ya la hallan usado.

¿Has incluido tu extensión en el email como archivo de texto?

Aclarando: La respuesta debería ser “SI”. Si en su lugar pegas la extensión en el cuerpo del mensaje, haces las cosas más difíciles. No se trata de un gran problema, pero apreciaríamos tu ayuda en ese sentido.

¿Has incluido una reseña para poner en el sitio web?

Aclarando: Cuando envíes una extensión, sería bueno que agregues una breve descripción para que el bibliotecario la ponga en el sitio web. Podría ser el epígrafe, más una o dos líneas explicando las dependencias, los cambios importantes de la nueva versión, etc. Si no proporcionas descripción alguna, el bibliotecario podría inventarse una; que podría ser o no lo que tenias en mente.