Imágenes en la documentación
Introducción
A la hora de elaborar documentación es muy normal la inclusión de imágenes en ella. Las imágenes suelen ayudar a comprender la utilización de una herramienta o nos muestran un esquema que aclara la utilización de una librería.
A la hora de incluir esas imágenes en la documentación hay que tener en cuenta:
- Que estén completas. Si son capturas de pantalla deberemos asegurarnos que estas son de la versión de la aplicación adecuada y que las cadenas que aparecen en ella están correctamente traducidas al menos a inglés.
- Dónde dejarlas, qué estructura de carpetas debemos usar para almacenarlas en gvsig.org.
- Cómo nombrarlas, criterio de nombrado de las imágenes que debemos utilizar.
- Calidad de estas, resolución y profundidad de color que debemos utilizar.
Estructura de carpetas
A la hora de incluir imágenes en la documentación tenderemos a estructurar las carpetas de una de las dos siguientes formas:
Agrupando las imágenes en una sola carpeta. Si estamos documentando una funcionalidad concreta, crearemos una carpeta para albergar la documentación de esa funcionalidad, y dentro de ella crearemos una carpeta images en la que dejaremos todas las imágenes que precise nuestra documentación (en algunos casos en la documentación de desarrollo data, ya que es común subir junto con las imágenes los archivos fuentes de los modelos que se documenta)
Agrupando las imágenes en una carpeta por documento que creemos.
Normalmente las imágenes que se capturan se dejan en una carpeta llamada como el documento que tiene la descripción de la funcionalidad añadiendo el sufijo "img". Dentro de esta carpeta imágenes, se crea una carpeta por cada idioma del que se dispongan imágenes, añadiendo el sufijo indicado para el idioma de que se trate según lo especificado en la iso639.
Ejemplo: (D) introduccion a gvSIG (F) introduccion a gvSIG (D) introduccion a gvSIG.img (D) es (F) img1-24-es.png (F) img1-es.png (D) en (F) img1-24-en.png (F) img1-en.png Nota: (D) Directorio/Carpeta (F) Archivo
Sea uno u otro el caso tendremos que tener en cuenta las siguientes consideraciones:
- La carpeta donde se dejan caer las imágenes no será de tipo carpeta (i18n).
- Si las imágenes han de ser dependientes del idioma, se creará una carpeta en, es en la que se dejaran caer las imágenes correspondientes al idioma.
- La carpeta de imágenes se excluirá de la navegación (ver Cómo excluir un documento de la navegación ).
Nombrado
El nombre que se le de a la imagen debe ser descriptivo.
Ejemplo: No vale Boton1, debe ser botonAñadirNuevaCapa
A la imagen que no tienen la paleta de colores optimizada se la identifica con un sufijo "-24". La imagen con la paleta optimizada no llevará sufijo.
Ejemplo: botonAñadirNuevaCapa-24.png
También se le añade un sufijo que haga referencia al idioma de la interface de usuario cuando se capturó la imagen, usando la nomenclatura de la iso639.
Ejemplo: Un imagen que haya sido capturada con la interface de usuario en castellano debe ir acompañada del sufijo "es" botonAñadirNuevaCapa-es.png
Calidad
Tip
Es recomendable que lea el apartado "Inclusion de imágenes o diagramas" del documento Normas y recomendaciones
Normalmente cuando estemos capturando imágenes para la aplicación almacenaremos dos o tres archivos:
- Una captura de pantalla de buena calidad con una paleta de colores de 24 bits o verdadero color en formato PNG. Esta imagen será la imagen principal, de gran tamaño y servirá de respaldo en cualquier momento.
- En el caso de que sea necesario, se adjuntara el archivo ODG de OpenOffice Draw con la composición gráfica realizada con la imagen original de calidad. El documento del Draw debe tener una página de tamaño A4 sobre la que se monta la composición. Para realizar la exportación a PNG se deben seleccionar los elementos de la composición y exportarla. De esta forma se generará un imagen del tamaño necesario para contener el montaje.
- Una imagen a partir de la imagen principal o de la imagen del montaje, pero de menor calidad y por lo tanto de menor peso también en formato PNG. En este caso se debe utilizar una paleta de colores lo más baja posible, siempre y cuando no se produzcan pérdidas significativas en la resolución. Estas imágenes son las que se insertarán en la documentación.
El utilizar archivos PNG cuya paleta de colores está optimizada se debe a que la exportación de la documentación a formatos PDF es capaz de optimizar mucho mejor el almacenamiento de imágenes en paleta de colores que en color de 24 bits.
El programa que utilizamos para la captura de imágenes es Gimp Con él, una vez capturada la imágen se optimiza la paleta de colores, adecuándola al número de colores necesario para que la imágen no pierda calidad. El criterio es visual. Como regla puede decirse que un botón por ejemplo "Cancelar" se ve bien con una paleta de 8 o 16 colores y una imágen de 3D con mucho colorido no suele necesitar más de 64.
El menú de optimización de la paleta de colores está en Imagen -> Modo -> Indexado.
![images/en/gimp-menu-image-mode.png](images/en/gimp-menu-image-mode.png)
Menú optimizar paleta de colores
En la ventana podemos seleccionar el número de colores que queremos y el modo de optimización.
![images/en/gimp-dialog-indexed-color-conversion.png](images/en/gimp-dialog-indexed-color-conversion.png)
Ventana optimización de la paleta de colores.
Como ya se ha comentado, es recomendable dejar accesibles los 2 archivos (el de la imágen optimizada y el que no tiene la paleta optimizada). La razón es que si luego se quiere realizar algún tratamiento a la imágen, por ejemplo resaltar un área, recortarla o escalarla, ... la imágen con la paleta optimizada no tiene la misma calidad que la imágen que no tiene la paleta optimizada.
Como nota final, tener en cuenta que la imagen debe guardarse sin compresión.
Subir y enlazar una imagen en un documento
Para subir una imagen, se deberá acceder al directorio previo al del documento y acceder a la carpeta "images" (si no está creada se deberá crear con el menú "agregar un nuevo ítem"-->"carpeta"). Dentro de la carpeta "images" deberá haber una carpeta por cada idioma al que esté traducido el documento (es: español, en: inglés, it: italiano, de:alemán...), y dentro de cada carpeta de cada idioma deberá haber el mismo número de imágenes. Si la carpeta no está creada se creará como se ha comentado anteriormente. Después se entrará en la carpeta del idioma correspondiente, y se seleccionará la pestaña "agregar un nuevo ítem"-->"imagen".
![images/es/pestanya_agregar_imagen_8.png](images/es/pestanya_agregar_imagen_8.png)
Pestaña Agregar imagen
En la siguiente ventana se pondrá el título y con el comando "Examinar" se buscará la imagen a subir al servidor. Finalmente se ejecutará el comando "Guardar".
Para enlazar una imagen desde la traducción del documento, si por ejemplo el idioma desde el cual se está traduciendo es el español, se dispondrá del siguiente texto:
.. figure:: images/es/pestanya_agregar_imagen_1.png :align: center
donde "es" es el nombre de la carpeta correspondiente al español. Se deberá sustituir el nombre de dicha carpeta por el de la carpeta donde están las imágenes del nuevo idioma, así como el nombre de la imagen que se ha subido previamente al servidor en el nuevo idioma. Por ejemplo, en la traducción a inglés podría ser:
.. figure::images/en/add_image_tab_1.png :align: center