You are currently browsing the category archive for the ‘Aplicaciones de apoyo’ category.

Existen no sé cuántas páginas en Internet que te explican por qué el control de versiones git es mejor que Subversion. No quiero decir que git es peor, pero poco de lo que provee realmente necesitas en muchas ocasiones. Así quiero dar razones por qué quedar con Subversion – sobre todo para los proyectos que ya lo están usando.

Trabajar en Corea del Norte

El cambio más importante de git respecto a Subversion es tener múltiples repositorios en lugar de uno. Mientras en Subversion te puedes confundir, sobre qué rama trabaja tu copia de trabajo, con git te puedes confundir sobre la rama y, además, sobre si has publicados tus cambios locales a qué otro repositorio.

Ninguna página sobre git pierde advertir, que estos repositorios locales te permiten trabajar off-line. Esto habría sido una maravilla con la velocidad del internet en el siglo pasado. Hoy no conozco ninguna empresa informática donde los empleados serían capaces trabajar sin red. ¿Qué te sirve hacer un check-in local si no puedes compilar porque el compilador descarga bibliotecas de un disco en red? Por supuesto, otra cosa es si te envían frecuentemente a Corea del Norte u otro lugar, donde el WIFI de alta velocidad no suele ser la regla.

Copiar repositorios enteros en lugar de ramas

Otra publicidad para git suele ser el cheap branching (ramificación barata), es decir, crear ramas nuevas cuesta poco. Crear ramas es rápido en git porque sólo se crean en tu repositorio local. En Subversion debes crear la rama en el repositorio. No obstante, no ralentiza mucho. La mayor parte de la creación pasas tecleando el nombre de la nueva rama – algo que git no te ahorra tampoco.

Ahora depende como quieres trabajar con tu nueva rama. Una es reciclar tu copia de trabajo y hacerla apuntar a la nueva rama. Esto se hace con switch en Subversion y con checkout en git. Como git no accede a la red, es más rápido. No obstante la pregunta es, si realmente quieres trabajar así, porque puedes confundir la rama en que piensas trabajar con la en que realmente trabajas. Los ficheros modificados en tu copia de trabajo se mantienen y serán ahora ficheros modificaciones sobre la nueva rama a que cambiaste. Si la rama anterior era de una versión de hace un año, con un poco de suerte no sólo harás un check-in de las tres líneas que has modificado sino, además, del estado que tuve el fichero hace un año.

Por no provocar tu suerte decides a editar cada rama en un directorio aparte. Así el flujo de trabajo es así: en Subversion, creas la rama en el repositorio y haces un check-out de lo que necesitas. En git haces una copia (clone) del repositorio entero y creas la rama. Es decir, primero copias el repositorio entero y no sólo lo que necesitas. Pero luego crear la rama, esto, sí, es rápido.

Como no querrás esperar a tanto cheap branching para cada rama que creas, git invita a crear muchos repositorios de que cada uno contiene lo mínimo posible. Puedes crear repositorios pequeños también con Subversion, pero no lo necesitas. Puedes tener un mega-proyecto en un repositorio y no hace falta comprarte un nuevo disco duro para tu copia de trabajo, ya que sólo necesitas descargarte le parte que quieres modificar.

Guardarlo todo

Otra auto-publicidad de git es guardar ficheros enteros en lugar de diferencias. La ventaja: es más rápido al hacer un check-out, ya que git sólo necesita buscar el fichero dentro de un commit y copiarlo. Subversion, en cambio, debe reconstruir el fichero a base del primer check-in más todos los cambios de la historia.

La ventaja de Subversion es que descargas un fichero por la red. En git descargas el repositorio entero con todas las versiones enteras de todos los ficheros – y así lo tendrás también guardado en tu disco duro.

El directorio .git

Git usa una carpeta escondida den nombre “.git” en el directorio raiz para guardar sus datos. En muchas páginas puedes leer que Subversion no es así, porque guarda una carpeta escondida “.svn” en cada carpeta. Esto era cierto. No obstante, esto ha cambiado desde la versión 1.7 de Subversion. Ahora sólo hay una carpeta “.svn” en el directorio raiz – igual como en git.

Seguridad para la generación selfie

Git hace publicidad con la seguridad de los datos. Una revisión no tiene un número, sino un hash, es decir un número hexadecimal lo suficientemente largo, para que, con seguridad, no podrás memorizarlo. Esto es para que no se altere la integridad del commit. El hash se calcula a base de los datos que componen un commit. Cambiar un byte cambia el hash. Al mismo tiempo, git te permite unir varios commits en uno, mover el origin de una rama a otro commit y hacer desaparecer commits por completo. Lo importante es que los commits no aparezcan como si hubieras probado algo, sino que la historia del repositorio muestra que hiciste todos los cambios completos y correctos a la primera. Sólo falta el botón “me gusta”.

En Subversion, en cambio, se queda la historia sin alterar. Lo que está dentro, se queda – a menos si lo quieres hackear. Si haces un merge de una rama, entonces no se copia la historia entera de la rama añadida sino se crear un nuevo commit, donde puedes poner todos los comentarios sensatos que el release manager necesita para decidir si tu cambio entra o no. Los comentarios y check-ins caóticos de tu rama de desarrollo no entran, porque se quedan únicamente en la rama de desarrollo.

Es cierto que tu repositorio de Subversion acumula ramas de desarrollo difuntas que ocupan espacio aunque ya no se necesitan. En git, el repositorio central sólo necesita guardar lo que realmente está terminado y funcionando. Pero esto surge porque estás dispuesto a jugar con dos repositorios a la vez. Lo puedes hacer también en Subversion. Exportas la rama de release, copias los ficheros a la copia de trabajo del repositorio bonito y haces un check-in.

Un repositorio para el back-up

Finalmente queda por hacer una copia de seguridad de tu repositorio, porque no quieres perder tus cambios si se rompe tu disco duro. Normalmente sólo se hace una copia de seguridad del repositorio central. En Subversion, todos los commits entran en la próxima copia de seguridad. En git, te debes pensar si haces un push al repositorio central o creas algún repositorio intermedio (probablemente en red), sobre qué el administrador de sistema hace una copia de seguridad. Así puedes elegir entre olvidar el push al repositorio central o intermedio o olvidar la copia de seguridad de tu repositorios locales.

Se puede argumentar que cualquier directorio de git es un back-up del repositorio central. Esto puede ser válido pero también puede que no. Es posible que sólo empujas commits buenos al repositorio central y el repositorio local contiene muchos más commits “de trabajo”. Es posible que estos no quieres tener en el repositorio central. Además hay configuraciones que son locales a un repositorio determinado – por ejemplo los scripts (hooks) que se llaman en caso de un commit. En fin, es probable que todavía prefieres hacer un back-up del repositorio central como se hace con el repositorio de Subversion, porque la existencias de múltiples clones no te tranquiliza lo suficiente.

El pull request

Una ventaja en el ámbito de git es el pull request. Es un flujo de trabajo en que un desarrollador dice que ha terminado algo y pide al jefe de integrarlo en la rama de release. Antes unas cuantas personas más pueden dar su acuerdo o incluso añadir nuevos commits con cambios. Esta funcionalidad no es de git mismo, sino un software adicional que ofrecen servidores para proyectos en git como GitHub.

Los servidores de Subversion no suelen ofrecer esto aunque teóricamente podrían. Pero es cuestionable si hace falta. En muchos proyectos, los desarrolladores pueden comunicarse de otras formas, se puede convenir que nadie hace un check-in en la rama de release menos el autorizado y siempre es posible crear una rama de la rama para proponer modificaciones adicionales. No aparece todo tan bonito en una página web, pero posible, sí, que es.

Y claro, siempre es posible que alguién implemente algo parecido al pull request para Subversion.

Quédate con lo que tienes

Si ya trabajas en git, entonces déjalo. Git no es peor que Subversion. Pero antes de migrar mil proyectos a git, piénsatelo bien. La mayoría de los argumentos a favor de git se mueven en el nivel de alguien que quiere vender su coche normalito para comprarse un SUV. Como no hay razones de verdad a favor de un SUV, busca razones que, al menos para él, aparentan serlo. El SUV gasta más, cuesta más, ocupa más espacio y es tan estrecho por dentro que la rueda de repuesto no cabe. Pero es mejor porque tiene capabilidad de todo-terreno. Aunque esta nunca aprovecharé porque no quiero que me salpique la tierra a mi bonito coche.

Antes de invertir en git, aprende a diferenciar los usuarios de los creyentes en git. Haz un análisis sobre qué esperas de un control de versiones y piensa si el cambio vale la inversión. Si ni siquiera te convence su propia publicidad, entonces es mejor seguir con lo que tienes.

Los repositorios descentralizados son una ventaja cuando los desarrolladores están distribuidos sobre el planeta como suele ser en muchos proyectos de código abierto. No obstante, en las empresas, los desarrolladores suelen trabajar en la misma oficina. Y existe un buen compromiso: el programa git svn permite trabajar con Subversion como si fuera git y, al mismo tiempo, permite trabajar con Subversion como si fuera Subversion. Es decir, es como un coche normal pero con tracción de cuatro ruedas.

Referencias

  • Página principal de Subversion
  • Página principal de git. git svn es parte del paquete git.
  • Página principal de GitHub

Lectura adicional

A veces no sabes si algunos mensajes te deben hacer llorar o sonreír. Algunos avisos en la informática se encuentran en esta categoría. Aquí un ejemplo de un mensaje de error de Rational Application Developper para Websphere que lo dice todo.

Diálogo con mensajes de error
Si todavía queda alguna duda, entonces se puede desplegar los detalles para más información.

Diálogo con detalle de error
Si todavía no queda claro, entonces considera las penurias que a veces tiene tu ordenador con lo que tú le dices a él.

Más entretenimiento

Este artículo trata de como aprovechar una hoja de cálculo para inicializar tablas en la base de datos.

Dentro de una base de datos guardamos tablas que consideramos “de configuración” ya que no se suelen modificar pero, sí, leerse al menos durante la inicialización del programa. Como estas tablas se modifican pocas veces, es habitual no crear una interfaz gráfica para rellenarlas sino se editan sus datos directamente con una herramienta de administración de la base de datos.

Las tablas de configuración pueden contener datos muy parecidos entre si. Por ejemplo, una tabla de configuración podría definir una red de ordenadores de la siguiente manera:

Ejemplo de una tabla de configuración
Id Nombre Dirección IP
1 Ordenador 1 192.168.0.1
2 Ordenador 2 192.168.0.2
3 Ordenador 3 192.168.0.3
n Ordenador n 192.168.0.n

Como vemos, los datos en cada registro son casi iguales. La parte variable he marcado con una n en la última línea.

Editar una tabla así puede ser pesado cuando se tratan de muchas entradas. Por eso buscamos una manera más sofisticada. Una es crear los comandos INSERT con una hoja de cálculo como Microsoft Excel o Open Office Calc.

Hoja de cálculo para crear comandos INSERT
A B C D
1 Id Nombre Dirección IP Comando SQL
2 1 =”Ordenador ” & A1 =”192.168.0.” & A1 =”insert into mi_tabla values(” & A1 & “, ‘” & B1 & “‘, ‘” & C1 &”‘);”
3 =A1+1 Repite fórmula arriba
4 Repite fórmula arriba

Con “Repite fórmula arriba” me refiero a “copiar hacia abajo” la fórmula de la primera fila.

Con las fórmulas en la hoja de cálculo anterior obtenemos el siguiente resultado.

Hoja de cálculo resultante
A B C D
1 Id Nombre Dirección IP Comando SQL
2 1 Ordenador 1 192.168.0.1 insert into mi_tabla values(1, ‘Ordenador 1’, ‘192.168.0.1’);
3 2 Ordenador 2 192.168.0.2 insert into mi_tabla values(2, ‘Ordenador 2’, ‘192.168.0.2’);
4 3 Ordenador 3 192.168.0.3 insert into mi_tabla values(3, ‘Ordenador 3’, ‘192.168.0.3’);

La última columna podemos copiar y pegar en un fichero de texto y ejecutarlo en el administrador de la base de datos. Así añadimos todas las entradas de golpe sin tener que editar todas las entradas a mano.

insert into mi_tabla values(1, 'Ordenador 1', '192.168.0.1');
insert into mi_tabla values(2, 'Ordenador 2', '192.168.0.2');
insert into mi_tabla values(3, 'Ordenador 3', '192.168.0.3');

Conviene guardar la hoja de cálculo junto con el proyecto para poder fácilmente cambiar la configuración como añadir una nueva fila para un nuevo ordenador o una nueva columna para una característica adicional.

Referencias

La primera tarea del sistema de documentación automatizado doxygen es la creación de un manual de referencia del código del programa. Sin embargo, doxygen ofrece también la funcionalidad de añadir un texto libre. Por la capacidad de doxygen de entender etiquetas de HTML, podemos editar un documento HTML con un editor aparte y luego integrarlo en la documentación generada con doxygen. Esto nos trae la ventaja de poder entregar una documentación completa y actualizada con cada ejecución de doxygen.

Creación de documentación libre

Doxygen conoce varias etiquetas para la creación de documentación libre. En primer lugar están las etiquetas \mainpage, \page y \subpage para la creación y la estructuración de páginas independientes. Dentro de cada página podemos estructurar el texto en apartados con las etiquetas provenientes LaTeX: \section, \subsection, \subsubsection y \paragraph. Conviene guardar la documentación libre en un fichero aparte por no tener correspondencia a ninguna entidad de código en concreto. El sufijo previsto para estos ficheros es dox, es decir, podemos crear una carpeta “doc” o “dox” que incluye todos los ficheros fuente que contienen documentación pero ninguna línea de código ejecutable.

Las etiquetas mencionadas arriba deben encontrarse dentro de un comentario de documentación. Lo más conveniente en este caso es abrir el comentario con /** o /*! en la primera línea y cerrarlo con */ en la última. Doxygen no exige iniciar una línea en medio con *. Ver la documentación de doxygen para un ejemplo.

Lo normal sería escribir la documentación libre en un fichero de texto, pero como ya he mencionado, en este artículo queremos averiguar, si podemos utilizar fuentes escritos en HTML. Dentro de lo que cabe tenemos dos estrategias para usarlas:

  1. Crear un documento HTML que doxygen lee y interpreta como un fichero fuente, es decir, un fichero .dox, y
  2. integrar un documento HTML externo

Ambas maneras tienen ventajas y desventajas que detallaremos a continuación.

Procesar HTML como fichero fuente

Podemos crear un fichero HTML y dejarlo procesar por doxygen como si fuera un fichero fuente. Doxygen entiende la mayoría de las etiquetas de HTML. Las que no entiende son en primer lugar etiquetas de contenido dinámico como OBJECT o EMBED. Esto no es de extrañar ya que doxygen no es un navegador de Internet sino una herramienta de documentación. Lo que duele más que tampoco entiende las etiquetas de cabecera. A contrario de lo que diga la documentación, la versión 1.7.1 que yo probé, no reconoce nada de lo que aparece entre <HEAD> y </HEAD> y tampoco la etiqueta BODY. Estas etiquetas aparecen entonces como cualquier texto normal.

Doxygen tampoco reconoce el comentario de HTML <– –>. Por lo tanto no podríamos esconder la apertura del comentario de documentación /** dentro de un comentario para que no nos aparezca si abrimos el fichero HTML en un navegador. En fin, no es posible crear un documento HTML que queda perfecto tanto en un navegador y en el resultado de doxygen a la vez. Todavía necesitamos un poco de trabajo manual:

Creamos un fichero dox que contiene algo como lo siguiente

/** \page mi_pagina_html Mi página en HTML
<h1>Soy un título</h1>
<p>En esta página podemos hablar de asuntos <em>muy</em> importantes.</p>
*/

Entre la primera y la última línea copiamos todo lo que se encuentra entre las etiquetas <BODY> y </BODY> en el documento HTML. (En este caso sólo he puesto dos líneas.)

La ventaja de esta manera es que doxygen crea una salida homogénea con las otras partes de la documentación. Más interesante aún es que doxygen enlaza los nombres de identificadores con la referencia correspondiente. De esta manera podemos, por ejemplo, crear un manual de usuario de una biblioteca en que aparecen automáticamente las enlaces al manual de referencia de los objetos de que estamos hablando.

Incluir un documento HTML

A veces los documentos HTML no son tan simples para que podamos usarlo directamente con doxygen. Puede haber varias razones. Por ejemplo:

  • El documento HTML se quiere usar tal cual como una página de Internet.
  • El documento usa una hoja de estilo u otros enlaces. En este caso y el anterior no podemos quitar la cabecera.
  • El documento usa contenido dinámico con Javascript.
  • El documento usa contenido empotrado como vídeos o animaciones flash.

En todos estos casos no queremos perder las características del propio HTML. Lo que podemos hacer es crear un pequeño fichero dox con el contenido siguiente:

/** \page mi_otra_pagina_html Mi otra página HTML
\htmlinclude "mi_fichero.html"
(Este documento sólo está disponible en la versión HTML de la documentación.)
*/

Con esta fuente, doxygen crea una página en que incluye el documento HTML “mi_fichero.html”, pero sólo para la versión HTML de la documentación. Desgraciadamente no existe una etiqueta en doxygen, con que podemos escribir algo en todos los formatos menos HTML. Así aparece una página prácticamente vacía en los demás formatos. Sólo se ve la frase “(Este documento sólo está disponible en la versión HTML de la documentación.)“. Esta frase aparece también al final del documento HTML, pero visualmente se impone menos. Existen también comandos exclusivos para otros formatos como \latexonly, pero no podrán sustituir el contenido dinámico de una página HTML, desde luego.

Debemos añadir el directorio, donde guardamos los ficheros HTML a incluir, al EXAMPLE_PATH de la configuración de doxygen. Si no es posible que doxygen no encuentra los ficheros que incluimos.

La ventaja de incluir un documento HTML de esta manera es poder usarlo sin modificación y aprovecharse de toda la potencia que una página WEB ofrece. La desventaja es que doxygen no enlaza nombres de identificadores con el manual de referencia y en los formatos no HTML no aparece ningún su contenido. Sin embargo, en muchos casos esto no supone un problema, ya que no se crea una documentación en otro formato que HTML.

Una aplicación de este truco puede ser la inclusión de un manual de usuario u otro texto libre. Se puede escribir en un editor como Microsoft Word y guardarlo como una página HTML. Luego se incluye esta página mediante \htmlinclude en la documentación de doxygen. Así es posible mantener una documentación completa y actualizada en todo momento.

Una cosa que, por cierto, no funciona es usar el comando \link a un fichero interno para crear un enlace a este documento HTML en la documentación. El enlace, sí, estará en la documentación creada por doxygen, pero no el fichero que enlaza. Esto sólo se puede hacer para documentos con una URL de Internet pública.

Conclusión

Hemos visto dos maneras de incluir documentación adicional al manual de referencia que doxygen crea a partir del código. La capacidad de doxygen de interpretar muchas etiquetas HTML permite incluir documentos escritos en HTML en la documentación. Es una buena opción para documentos no interactivos. Para páginas HTML más complejos se ofrece incluir la página tal cual mediante \htmlinclude, que mantiene toda la potencia de una página interactiva, pero a coste de no poder verlo en los demás formatos que doxygen puede crear.

Referencias

Las tablas de sistema de Firebird contienen todas las informaciones sobre las tablas de usuario. Como estos datos son a veces un poco críptico, conviene reunir los datos de interés en vistas propias. Muchos comandos SQL útiles para extraer información de las tablas de sistemas se encuentran en el artículo “Extracting META information from Interbase/Firebird SQL […]

Obtener información de tablas

Con esta vista puedes obtener información sobre las columnas de las tablas y sus tipos. Esta información puede ser útil a la hora de comprobar si un dato a guardar en la base de datos está en un formato correcto – por ejemplo que un campo de texto no excede la longitud máxima.

CREATE VIEW V_TABLES (TABLE_NAME, FIELD_NAME, FIELD_DESCRIPTION, FIELD_DEFAULT_VALUE, FIELD_NOT_NULL_CONSTRAINT, FIELD_LENGTH, FIELD_PRECISION, FIELD_SCALE, FIELD_TYPE, FIELD_SUBTYPE, FIELD_COLLATION, FIELD_CHARSET)AS 
SELECT  r.RDB$RELATION_NAME as table_name, 
        r.RDB$FIELD_POSITION as field_position, 
        r.RDB$FIELD_NAME AS field_name, 
        r.RDB$DESCRIPTION AS field_description, 
        r.RDB$DEFAULT_VALUE AS field_default_value, 
        r.RDB$NULL_FLAG AS field_not_null_constraint, 
        f.RDB$FIELD_LENGTH AS field_length, 
        f.RDB$FIELD_PRECISION AS field_precision, 
        f.RDB$FIELD_SCALE AS field_scale, 
        CASE f.RDB$FIELD_TYPE 
          WHEN 261 THEN 'BLOB' 
          WHEN 14 THEN 'CHAR' 
          WHEN 40 THEN 'CSTRING' 
          WHEN 11 THEN 'D_FLOAT' 
          WHEN 27 THEN 'DOUBLE' 
          WHEN 10 THEN 'FLOAT' 
          WHEN 16 THEN 'INT64' 
          WHEN 8 THEN 'INTEGER' 
          WHEN 9 THEN 'QUAD' 
          WHEN 7 THEN 'SMALLINT' 
          WHEN 12 THEN 'DATE' 
          WHEN 13 THEN 'TIME' 
          WHEN 35 THEN 'TIMESTAMP' 
          WHEN 37 THEN 'VARCHAR' 
          ELSE 'UNKNOWN' 
        END AS field_type, 
        f.RDB$FIELD_SUB_TYPE AS field_subtype, 
        coll.RDB$COLLATION_NAME AS field_collation, 
        cset.RDB$CHARACTER_SET_NAME AS field_charset 
   FROM RDB$RELATION_FIELDS r 
   LEFT JOIN RDB$FIELDS f ON r.RDB$FIELD_SOURCE = f.RDB$FIELD_NAME 
   LEFT JOIN RDB$COLLATIONS coll ON r.RDB$COLLATION_ID = coll.RDB$COLLATION_ID 
    AND f.RDB$CHARACTER_SET_ID = coll.RDB$CHARACTER_SET_ID 
   LEFT JOIN RDB$CHARACTER_SETS cset ON f.RDB$CHARACTER_SET_ID = cset.RDB$CHARACTER_SET_ID 
ORDER BY r.RDB$RELATION_NAME, r.RDB$FIELD_POSITION;

Información sobre claves externas

Con la vista siguiente puedes extraer información sobre claves externas (foreign keys).

CREATE VIEW V_FOREIGN_KEYS (TABLE_NAME, FIELD_NAME, REFERENCED_TABLE_NAME, REFERENCED_FIELD_NAME, ON_UPDATE, ON_DELETE)AS       
  SELECT DISTINCT  
--          rc.RDB$CONSTRAINT_NAME AS constraint_name,  
          rc.RDB$RELATION_NAME AS table_name,  
          d1.RDB$FIELD_NAME AS field_name,  
          d2.RDB$DEPENDED_ON_NAME AS referenced_table_name,  
          d2.RDB$FIELD_NAME AS referenced_field_name,  
          refc.RDB$UPDATE_RULE AS on_update,  
          refc.RDB$DELETE_RULE AS on_delete  
     FROM RDB$RELATION_CONSTRAINTS AS rc  
LEFT JOIN RDB$REF_CONSTRAINTS refc ON rc.RDB$CONSTRAINT_NAME = refc.RDB$CONSTRAINT_NAME  
LEFT JOIN RDB$DEPENDENCIES d1 ON d1.RDB$DEPENDED_ON_NAME = rc.RDB$RELATION_NAME  
LEFT JOIN RDB$DEPENDENCIES d2 ON d1.RDB$DEPENDENT_NAME = d2.RDB$DEPENDENT_NAME  
    WHERE rc.RDB$CONSTRAINT_TYPE = 'FOREIGN KEY'  
      AND d1.RDB$DEPENDED_ON_NAME <> d2.RDB$DEPENDED_ON_NAME  
      AND d1.RDB$FIELD_NAME <> d2.RDB$FIELD_NAME  
;
GRANT DELETE, INSERT, REFERENCES, SELECT, UPDATE
 ON V_FOREIGN_KEYS TO SYSDBA WITH GRANT OPTION;
UPDATE RDB$RELATION_FIELDS set
  RDB$DESCRIPTION = 'Table that uses the foreign key'
  where RDB$FIELD_NAME = 'TABLE_NAME' AND RDB$RELATION_NAME = 'V_FOREIGN_KEYS';
UPDATE RDB$RELATION_FIELDS set
  RDB$DESCRIPTION = 'Field whose values are restricted to the referenced field'
  where RDB$FIELD_NAME = 'FIELD_NAME' AND RDB$RELATION_NAME = 'V_FOREIGN_KEYS';
UPDATE RDB$RELATION_FIELDS set
  RDB$DESCRIPTION = 'The table which is referenced by the foreign key'
  where RDB$FIELD_NAME = 'REFERENCED_TABLE_NAME' AND RDB$RELATION_NAME = 'V_FOREIGN_KEYS';
UPDATE RDB$RELATION_FIELDS set
  RDB$DESCRIPTION = 'The field whose values are the permitted ones for the target field'
  where RDB$FIELD_NAME = 'REFERENCED_FIELD_NAME' AND RDB$RELATION_NAME = 'V_FOREIGN_KEYS';
UPDATE RDB$RELATION_FIELDS set
  RDB$DESCRIPTION = 'What to do when the referenced field value is updated'
  where RDB$FIELD_NAME = 'ON_UPDATE' AND RDB$RELATION_NAME = 'V_FOREIGN_KEYS';
UPDATE RDB$RELATION_FIELDS set
  RDB$DESCRIPTION = 'What to do when the referenced field value is deleted'
  where RDB$FIELD_NAME = 'ON_DELETE' AND RDB$RELATION_NAME = 'V_FOREIGN_KEYS';

Copiar comentarios de columnas de una tabla a una vista

Si creo una vista, entonces me gustaría tener los mismos comentarios en la vista que en las columnas correspondientes de las tablas a partir de las cuales creo la vista. Por supuesto, esto es un problema trivial para aquellos que nunca ponen comentarios en ningún sitio, pero para los demás, el siguiente comando podría ser de utilidad.

UPDATE RDB$RELATION_FIELDS set RDB$DESCRIPTION = 
       (select RDB$DESCRIPTION from RDB$RELATION_FIELDS 
         where RDB$RELATION_NAME = 'SOURCE_TABLE'
           and RDB$FIELD_NAME = 'SOURCE_COLUMN')
  where RDB$FIELD_NAME = 'TARGET_FIELD' 
    AND RDB$RELATION_NAME = 'TARGET_NAME';

El select interior lee de la tabla de la cual queremos obtener los comentarios. Podemos sustituir el paréntesis por un string si queremos asignar un comentario a medida. SOURCE_TABLE y SOURCE_COLUMN se refieren a la tabla de donde quiero copiar los comentarios y TARGET_NAME y TARGET_FIELD a la vista a donde los quiero copiar. Los nombres de las tablas, vistas y columnas deben estar en mayúsculas. De otra forma la comparación = no funcionará.

Por supuesto, antes de usar este comando SQL hay que crear la tabla y la vista a que se refieren. La herramienta de extracción de DDL (Data Definition Language) no guarda referencias a comentarios de otras tablas. Sólo presenta el comentario actualmente asignado. Por eso, conviene guardarse un fichero SQL con los comandos de copia de comentarios junto con la creación de la vista, ya que se puede ejecutar cada vez se cambia la vista.

Referencias

A la hora de crear un documento es importante saber, qué formato usamos para generarlo. Muy a menudo resolvemos esta cuestión sin pensar más: Usamos Microsoft Word para escribir una carta y creamos un documento HTML para publicar algo en Internet. Otras cosas anotamos en un simple fichero de texto o quizá tenemos una razón de usar formatos menos populares como LaTeX – por ejemplo, si trabajamos en el ámbito de las ciencias naturales. Resolvemos esta cuestión sin pensar más, porque otros ya lo han pensado, o porque simplemente no es siempre tan importante.

En este artículo queremos reflexionar sobre las posibilidades de documentación que tenemos y por qué unos formatos son más adecuados (adecuados, no mejores) para unas tareas y otros para otras. Qué formato a escoger a la hora de crear documentos es desde luego importante a la hora de crear un documento de gran tamaño, que será usada por mucha gente o se actualice durante mucho tiempo. Hay formatos tan diversas como las necesidades que tenemos y aquí no pretendemos de dar a conocer a todos. Lo que presentamos es una presentación de conceptos a tener en cuenta a la hora de eligir una tecnología u otra.

Resumen de formatos y características

Antes de proceder veremos una tabla que resume el contenido de este artículo. En la primera columna están listados unos formatos para editar documentos y en la primera fila las carácterísticas que nos interesan.

Propiedades de diferentes formatos de documentación
Gráfico ASCII Gratis Orto­grafía Gramática Multi-Idioma Guiones
Microsoft Office (Sí)
Open Office (Sí)
LaTeX (Sí) (Sí)
HTML (Sí) (Sí) (Sí) (Sí)
DocBook (Sí) (Sí) (Sí) (Sí)
Texto en­riquecido (Sí) (Sí) (Sí) (Sí)
Texto simple (Sí) (Sí)

El significado de las características es el siguiente:

Gráfico
Existe un editor WYSIWYG, acrónimo inglés para What You See Is What You Get (Lo que ves es lo que obtienes). Tener está capacidad trae la ventaja que vemos ya editando como será nuestro documento final. El contrario de esto es deber editar un fichero fuente en un editor de texto y compilarlo en un formato final. Sí entre paréntesis en esto contexto quiere decir que se puede editar documentos con editores gráficos aunque el fundamento es un texto con códigos de control (como HTML).
ASCII
El formato está basado en un fichero ASCII (de texto) que se debe compilar (transformar) de alguna forma. Por ejemplo, un fichero LaTeX es un código fuente que necesita ser procesado por un programa de nombre TeX para convertirse en un documento de aspecto gráfico. El fichero fuente en sí se parece más a un código de programación. Hay varios formatos (OpenDocument y Texto Enriquecido) que tambien están basado en ficheros ASCII. Sin embargo, no están diseñados para modificar documentos con un editor de texto.
Gratis
Indica si es software libre y usa estándares abiertos. La mayoría de los formatos gratis están basados en estándares y programas de código abierto. Sí entre paréntesis en este contexto quiere decir que puede depender del uso. Un documento en formato DocBook, por ejemplo, necesita un compilador para convertirse en un documento legible. Dependiendo del tipo de documento legible que busco (página Web, PDF etc.) puede tocar pagar o lo consigo gratis también.
Ortografía
Tiene corrector de ortografía mientras edito. Los editores gráficos suelen tenerlo. Los formatos que se basan en un fichero de fuente en formato ASCII pueden ser editado con un editor que dispone de un corrector de ortografía o no. En este contexto se puede enteneder el sí entre paréntesis.
Gramática
Comprueba la gramática del texto editado. Es una herramienta muy útil para editar texto bien redactados especialmente en un idioma extranjero.
Multi-Idioma
Ofrece la posibilidad de usarlo con facilidad con mútliples idiomas. Un sí entre paréntesis en este contexto quiere decir que tiene la posibilidad pero hay que hacer algún esfuerzo más allá de descargar un fichero para conseguirlo (como descargar librerías adicionales o pagar por ello, por ejemplo).
Guiones
Tiene separación de palabras con guiones al final de la línea. Esto es algo imprescindible para generar documentos bonitos, sobre todo si tienen el margen derecho justificado. Sí entre paréntesis quiere decir que esta opción existe teóricamente, pero no está implementado con facilidad (como en HTML) o depende del editor que se usa.

Criterios para el formato adecuado

Para elegir bien el formato para nuestro documento debemos primero fijar los criterios según los cuales eligimos. Para expresarnos mejor, definimos familias de formatos a que nos referimos a partir de ahora:

  • Editores gráficos como Microsoft Office o OpenOffice que muestran el estado visualizado con cada tecla apretada.
  • Formatos de texto como HTML, DocBook o LaTeX que se basan en ficheros de texto.
Contenido gráfico

Si mi documento contiene muchas gráficas y debo constantemente actualizar el lay-out manualmente, entonces conviene usar un editor gráfico que mete todo en un fichero. Como formatos de texto no pueden incluir algo que no sea texto directamente, deben incluirlo mediante enlaces. De esta forma se debe mantener muchos ficheros y para ver el resultado final hace falta un proceso intermedio como la compilación en caso de LaTeX o la actualización del navegador en caso de HTML.

Conveniencia

Si no quiero perder tiempo a aprender un nuevo formato para editar documentos, entonces uso uno que ya conozco. En general es más fácil usar editores gráficos ya que son más intuitivos. Los formatos de texto son más fáciles a generar por programas de documentación automática.

Otro punto importante puede ser la corrección de errores lingüisticos. Un corrector de ortografía que sulinea todas las palabras que no conoce puede ser una ayuda para dejar el documento en un mejor estado desde el principio. Microsoft Office ofrece incluso un corrector de gramática. Desgraciadamente Microsoft Office viene con un número de idiomas bastante reducido. Según lo políglota que soy me pueden interesar correctores de muchos idiomas diferentes. Y finalmente puede influir también la ayuda en línea que suministra el programa que uso para entenderlo.

Tiempo de uso

¿Qué es la probabilidad que vaya abrir, imprimir o modificar el mismo documento en diez años? Si escribo una solicitud de empleo será cercano a cero, si escribo un diario cercano a uno. A priori nunca se sabe qué formato se hará obsoleto, es decir, ya no habrá programas que lean y muestran los contenidos del fichero correctamente. En general es menos probable que un formato popular y basado en un estándar abierto se hará obsoleto que uno de una aplicación específica. Para un uso de larga duración son, por lo tanto, recomendables los formatos abiertos y de texto.

Habrá más personas con el mismo problema si un formato popular se hace obsoleto, y será al menos teóricamente posible de escribir un conversor si el formato sea abierto, o sea, que se puede obtener la documentación necesaria para intepretar correctamente los contenidos del fichero. Una empresa con el peso de Microsoft puede aprovechar su formato no abierto para hacer incompatible documentos de diferentes versiones. Como tampoco vende versiones antiguas de su producto Office es posible que una empresa se ve obligada a comprar muchas licencias nuevas sólo para que un grupo de autores puede seguir trabajando en un mismo documento. Y aunque parezca poco probable hoy en día, también una empresa como Microsoft puede quebrar o abandonar el producto Office, por lo cual ya no habrá actualizaciones y mucho menos conversores para otro software popular en el futuro. La documentación sobre un formato abierto, en cambio, siempre sigue existiendo aunque caiga en desuso.

Si soy mando de una gran empresa podrá ser rentable optar por un formato complejo de un editor gráfico como OpenOffice y arriesgar encargar la programación de un conversor si hubiera la necesidad en algún momento.
Para aquellos con menos recursos serán fuertemente recomendados los formatos de texto, aunque sean más difíciles a usar. Un editor de texto es lo más básico y siempre habrá en uno en cualquier ordenador. Al contrario de los formatos binarios, los formatos de texto pueden ser leídos por seres humanos (aunque con dificultades) si ya no dispongo de ninguna herramienta informática que les sepa tratar. Esto puede ser crucial si sólo busco un nombre o número de teléfono en un documento viejo. Y, desde luego, siempre será más fácil convertir un fichero de texto a un formato más moderno que un fichero binario.

Accesibilidad

No siempre lo mejor es lo más adaptado, sobre todo no adaptado a las necesidades de los lectores. Aunque tendré que actualizar mi currículum vitae durante la vida y sería preferible hacerlo en un formato abierto, los departamentos de recursos humanos siempre me lo piden en formato de Microsoft Word. Si el destinatario sólo quiere leer mi documento, entonces puedo crearlo a mi conveniencia y convertir al formato PDF, que practicamente todos los ordenadores pueden leer. Pero si el destinatario también quiere editarlo, entonces será mejor no obligar a descargarse y entender un software complicado aunque sea el más adecuado para el tipo de documentación que me pide.

Un punto importante puede ser la portabilidad del documento entre diferentes plataformas: Hay navegadores de Internet para Microsoft Windows, para Linux, para Unix y para Apple, pero Microsoft Office no existe en versión Linux. Los formatos de texto pueden ser editados HTML y LaTeX con cualquier ordenador.

Otra cosa que hay que tener en cuenta son las versiones de un mismo programa. Es posible que no todo el mundo tiene la última versión y, por lo tanto, no podrá ver todas las funcionalidades que podrías haber incluído. Optar por un estándar simple ayuda a que más personas puedan verlo. Y lo mismo vale teniendo en cuenta que no todo el mundo tiene una conexión de Internet rápida. Es posible que otros jamás podrán ver tu documento súper bonito pero con poco contenido, simplemente porque no consiguen descargarlo.

Integridad física

¿Ya te ha pasado que quisiste deshacer un cambio en una plantilla de formato en Microsoft Word y buscabas un botón heredar propiedad del padre? Una lista de problemas que you tuve con Microsoft Word durante mi proyecto fin de carrera:

  • No se podía guardar un fichero porque no hubo espacio en el disco duro. El fichero tenía un tamaño de unos tres megabyte y el espacio en el disco duro eran 500. Descubrí que una fórmula matemática se había convertido en un objeto desconocido.
  • Tampoco se podía abrir el fichero por falta de memoria. Conseguí seperar el fichero en múltiples (uno para cada artículo) y podría poner los número de página a mano.
  • En las listas con viñetas (como en la que estás leyendo ahora mismo) desaparecieron las viñetas y no hubo forma de convencer a la aplicaciones que los pusiese otra vez.

Es posible (y me ha pasado), que la falta de memoria hace también imposible trabajar con otros procesadores de texto como LaTeX, pero hay dos puntos diferentes muy importantes:

  1. Microsoft Word guarda un documento en un fichero binario. Si sólo añades, quitas o modificas un byte con un hexeditor puede ser que ya no se deja abrir. No hay forma de reparar un fichero .doc a mano.
  2. Si Microsoft Office te guarda algo mal en tu documento por el error que sea, te habrá sobreescrito la vieja versión que aún funcionaba. En los formatos de texto como LaTeX, sólo editas el fichero fuente. Cualquier representación de esta fuenta será guardado en otro fichero. Aunque este fichero generado será degenerado, siempre es posible que vayas con tus ficheros fuente a otro ordenador mejor (o consultas con una persona que sabe mejor) y intentas generarlo otra vez.

En fin, la integridad física de un fichero indica hasta que grado se puede usar aunque contenga un error o fue parcialmente destruido. En general no hay forma de reparar un fichero binario. Por esto ya no se hace. La versión actual de Microsoft Office y OpenOffice guardan ahora sus contenidos en varios ficheros de texto en formato XML que se comprimen en un archivo ZIP. Que la extensión de Microsoft Word no es ZIP sino DOCX facilita relacionar los documentos con la aplicación. Pero puedes probar cambiar la extensión de un fichero DOCX a ZIP, y entonces puedes abrirlo con un archivo ZIP y ver sus contenidos.

Para los más preocupados es recomendable no usar editores gráficos, porque lo que tú editas no es lo que realmente se guarda – sino sólo una traducción (mayoritariamente correcta) de lo que editas. Sólo en los formatos de texto editas tú y tólo tú.

Medio de publicación

No es lo mismo si quiero escribir un libro o imprimir un texto a crear una página Web. La mayoría de los formatos están dedicados a publicar un documento en un medio específico aunque no exclusivamente. Los procesadores de texto sirven sobre todo para imprimir algo en papel, el HTML se inventó para mostrar algo en pantalla. Hoy en día, se pueden usar muchos formatos en muchos ámbitos aunque sigue haber una preferencia para un determinado uso.

La tendencia hoy en día es publicar un mismo documento en formatos diferentes: en papel, en pantalla e incluso por voz. Todo esto a partir de un mismo documento fuente. Con este propósito se definó el estándar de DocBook, que sólo define contenidos y no la representación de un documento.

Procesado automatizado

Muchas veces interesa crear documentación de forma automatica a partir de código de un lenguaje de programación. Esta documentación se puede mezclar por otra editada por seres humanos, por ejemplo un tutorial sobre una biblioteca, donde se quiere entrelazar los nombres de clases, métodos y variables con la referencia creada por el programa de documentación automatizada. En estos casos es casi imperativo el uso de formatos de texto. Por ejemplo, phpDocumentor, un programa de documentación automatizada para el lenguaje de programación PHP pueden incluir textos editados por humanos, si están escritas en el formato DocBook.

Los formatos en detalle

Queremos dar una vista detallada sobre los distintos formatos mencionados en el resumen. Este apartado tiene en consecuencia una sección para cada formato.

Microsoft Office

Microsoft Office es la elección para quienes quieren usar y no pensar. Todo está automatizado y con dos clicks ya tienes impreso tu documento. A un click la ayuda, corrección de ortografía y el único con correción de gramática convierten Microsoft Office en algo fácil de usar. Lo bueno tiene precio, y este es bastante alto. Si uno quiere ahorrárselo, entonces será recomendable usar OpenOffice. Lo malo es que casi todas las empresas prefieren no ahorrar y al final tú también necesitas Microsoft Word sólo para tener tu currículum en formato Word.

Puesto el caso que ya tienes una licencia, Microsoft Office es una buena elección para editar algo a corto plazo. Es decir, algo que vas a terminar a editar en al menos medio año y luego ya no te duele que no se pueda usarlo con la próxima versión. También conviene para compartir documentos con personas que no saben tanto de ordenador y ya tienen suficiente con conocer a un programa. En cambio, los productos de Microsoft no suele haber en versiones para Linux o Unix.

Si piensas editar un documento de gran tamaño y complejidad como un texto con muchas fórmulas matemáticas, entonces no es recomendable usarlo. Lo mismo vale si no quieres gastarte dinero en la licencia (o hacer cosas ilegales para conseguirla). Si te importa que puedas modificar y usar tu documento durante muchos años, es preferible no usar productos propietarios (no abiertos), ya que puedan volverse incompatible sin previo aviso en la próxima versión.

OpenOffice

OpenOffice tiene la misma funcionalidad que Microsoft Office, a que se parece mucho en su uso. Sin embargo, tiene una diferencia importante en el precio: Es gratis. Es un proyecto de código abierto, donde puedes participar con tus propias rutinas; si quieres. Como no hacen dinero vendiéndote la última versión, tampoco hay necesidad de incluir más incompatibilidades entre versiones que necesario.

Es recomendable usar OpenOffice para el uso diario igual como Microsoft Office. Por ser de código abierto es probable que su formato será legible también en el futuro, aunque tampoco hay garantía de que este proyecto de software será abandonado en algún momento. Una desventaja es que casi nadie tiene OpenOffice instalado y, por eso, no se puede usar su formato nativo para compartir documentos. No obstante, OpenOffice tiene un conversor para documentos de Microsoft Office. Sin embargo, no es recomendable editar un mismo documento con los dos Office. Un conversor sirve para visualizar y transformar contenido, pero no para editar un documento con dos aplicaciones distintas, ya que no todas las características se pueden convertir. Un documento de Microsoft Word es similar a uno de OpenOffice, pero no igual.

Para mí, OpenOffice es la elección cuando quiero editar un texto para mí mismo. Puede ser el estándar interna de una empresa que quiere ahorrarse licencias costosos.

Existe una versión de OpenOffice que se llama OxygenOffice. Funciona igual pero aporta muchos ficheros adicionales como clipart, plantillas, diccionarios, imágenes y sonidos.

LaTeX

Lo primero que llama la atención en el procesador de texto LaTeX es su forma peculiar de escribirse. El sistema de base de llama TeX y fue inventado para rellenar una hoja de papel con caracteres. Como es un formato de texto, todo lo que no sea una letra para imprimir debe ser una palabra que comienza con la barra invertida. Hay un comando para añadir un línea de pie \footline, donde se puede añadir el número de la página \pageno y cambiar a una fuente negrita con \bf.

Hubo a quien todo esto pareció demasiado complicado y se aprovechó de un gran capacidad del sistema TeX: las macros. Se pueden definir nuevos comandos (con \) que luego se reemplazan por el contenido. Estas macros también permiten parámetros de forma que se podría definir un tipo de documento libro, que tiene páginas pares e impares diferentes, con tanto espacacio hacia arriba y abajo y admite como parámetro el tamaño de la fuente. Todo esto ya lo hecho alguien y llamó el resultado LaTeX.

LaTeX tiene comandos que están más cercano a lo que quiere el usuario y por eso es relativamente fácil empezar a usarlo – con énfasis a relativamente. Lo que no cambia es la abundancia de barras inversas a que cuesta acostumbrarse. Ahora la pregunta por qué alguien quisiera usar un sistema así.

Pues, el resultado es simplemente más bonito. La diferencia con los editores gráficos ya no es tan grande ahora que hace años, pero LaTeX sigue siendo la elección para quién quiera escribir textos con muchas fórmulas matemáticas. Porque salen más bonitas y LaTeX ofrece muchos símbolos matemáticos.

Otra ventaja es que las fórmulas no son objetos aparte del texto como en los editores gráficos. No hace falta abrir ningún editor especial para editarlas. Son texto como lo demás, y cambiar el tamaño de la fuente de todo el documento es tan fácil como cambiar un parámetro en la definición de la clase del documento. Con Microsoft u Open Office habría que ir una a una y cambiarlo manualmente.

LaTeX es un formato de texto que tiene, por lo tanto, ficheros fuente más pequeños que los documentos de un editor gráfico. Desventajas son que la instalación es relativamente complicada y que hay que compilar los ficheros fuente cada vez que se cambie algo. El resultado de esto es un gran número de ficheros generados que puede agobiar a quién adora tener sus directorios limpios. En cambio, la funcionalidad de macros es muy potente: se pueden crear nuevos estilos y diseños de página más allá de lo inicialmente pensado. También permite escribir ecuaciones con palabras humanas. Por ejemplo, para visualizar la ecuación U = R·I se puede escribir en el fichero fuente \tension = \resistencia·\corriente si se ha definido anteriormente

\newcommand{\tension}{U}
\newcommand{\resistencia}{R}
\newcommand{\corriente}{I}

Si siempre uso la macro \tension en lugar de U, podría cambiar la letra a V en todo el documento sólo cambiando la definicón de la macro \tension.

HTML

HTML (HyperText Markup Language) es la base de cualquier documento que vemos en un navegador de Internet. Podemos visualizar un fichero HTML también cuando no esté en Internet sino en nuestro disco duro. HTML ha sido diseñado para Internet y permite enlaces a otros documentos o contenido en otros ordenadores. No es difícil incluir en tu documento una imagen que reside en un servidor en otro continente.

Mientras los principios de HTML eran dedicados a mostrar documentos de Internet en un navegador, hay una tendencia de separar contenido de la representación de contenido. Idealmente un documento HTML sólo define qué texto contiene un título, que texto contienen los párafos que siguen, que son las contenidos de una tabla, pero no hay ninguna referencia sobre la fuente, los colores, la sangría o las viñetas en las listas que se usan. Todo esto define un invento más reciente que se llama CSS (Cascading Style Sheet – hojas de estilo en español).

Este proceso todavía no ha finalizado, pero la intención es clara: Que HTML será un formato libre de información representativa, por lo cual el mismo documento puede ser convertido en diferentes representaciones para pantalla, papel o incluso sonido con diferentes hojas de estilo. Esto trae también la ventaja que un escritor sin estilo puede dedicarse a escribir sus ideas y dejar el resto a un estilista sin ideas. Contenido y representación todavía no se dejan separar de todo, pero será el futuro.

HTML es un formato muy popular y es difícil encontrar un editor que no sepa algo de HTML. Microsoft Office y OpenOffice importan y exportan HTML, un documento HTML puede ser visualizado en cualquier navegador y HTML es probablemente el mejor formato para hacer algo para la eternidad. Hay muchos editores gráficos para quien no quiera editar un fichero de texto con códigos de comando <>. Aunque HTML es a veces demasiado simple con comparación con lo que ofrecen los procesadores de texto, se puede optar que el futuro lo resuelve.

Como ejemplo ponemos la númeración de los títulos: HTML no lo permite y habría que numerar cada encabezado manualmente. Sin embargo, la versión 2.1 de los Cascading Style Sheets permite añadir un esquema de númeración de títulos. Podemos esperar que habrá aún más utilidades en el futuro.

DocBook

La separación entre contenido y representación se ha llevado a completo con el estándar DocBook. El código de un documento DocBook tiene un aspecto similar a HTML por tener un formato XML, pero ofrece muchos más componentes: todo lo que uno podría necesitar en una tésis de doctorado o manual de usuario.

Como el formato DocBook sólo contiene el contenido del documento, le falta un herramienta que lo represente, es decir, que lo convierta en una página HTML o un documento PDF o lo que sea. Por lo tanto, DocBook no es una buena elección si sólo pienso tener una representación. La idea de DocBook es que puedo generar representaciones muy diversas a partir de una sola fuente, pero necesito crear estas representaciones anteriormente. Como DocBook es un formato de texto, es muy bueno para crear documentación automatizada que luego se quiere exportar como páginas de Internet, en formato PDF y como fichero de audio.

Texto enriquecido

Texto enriquecido (Rich Text Format en inglés) es un formato de texto. Sin embargo es tan confuso que no habrá quién lo editaría con un editor de texto. (Para comprobarlo basta guardar un documento de Microsoft Word como fichero RTF y abrirlo en el bloc de notas.)

Este formato fue pensado para editar algún texto bonito con texto en negrita y cursiva sin guardar el tipo de contenido detrás de la representación. Es decir, el formato sabe la fuente de la letra pero no sabe qué corresponde a un título y qué a un texto normal y corriente. Por lo tanto, no sirve para escribir grandes obras, pero, sí, para crear un texto visualmente agradable que se deja abrir en muchos editores.

Más que un formato para editar y guardar, es un formato para exportar. Por ejemplo, se puede convertir los contenidos de un DocBook en un fichero de texto enriquecido para luego imprimirlo. Como texto enriquecido es un formato de texto, permite cambios fáciles a base de cadenas de texto por un programa de ordenador.

Texto simple

Un texto simple es lo que muestra el bloc de notas en Microsoft Windows: una secuencia de caracteres. Aunque un texto sin más tiene un aspecto aburrido, puede ser lo mejor en determinadas circunstancias.

Un fichero de texto es lo más portable posible. Siempre habrá un programa que podrá leerlo y no es posible conseguir ficheros más pequeños con el mismo contenido. No requiere ningún programa especial para ser leído. Es eterno. Y los más rápido a la hora mostrarlo en pantalla también.

Desde hace años uso un fichero de texto como mi agenda. Desde luego no es tan fantástico que una PDA o un organizador de eventos especializado, pero cabe en un disquete, se puede leer en cualquier ordenador (en el trabajo) y cuando se acabe la vida (de la batería) de la PDA no necesito copiar manualmente todos los datos porque no son compatibles con la PDA nueva. El formato de texto simple es el más adecuado cuando necesito algo simple y rápido.

Conclusión

Hemos visto formatos muy diferentes para crear documentación. Ahora ¿cómo eligir? Para ello eliges los escenarios que más se ajustan a tu caso. En general no hay el mejor formato. Cada uno tiene sus ventajas e inconvenientes y será a veces una cuestión de gusto cual usas. Y, en fin, hay muchos conversores de un tipo de formato a otro.

Necesidad de documentación y su formato idóneo.
Mi problema Mi formato
Odio a la programación y códigos crípticos. Microsoft Office, OpenOffice o Texto Enriquecido.
Quiero íntegridad física y un formato de texto. HTML, LaTeX, DocBook, Texto simple.
Rápido y simple. Texto simple, HTML. Dependiendo del editor asociado: Texto Enriquecido.
No quiero ni pagar ni piratear (y que sea de código abierto). Todo excepto Microsoft Office.
Quiero un formato popular. HTML. Para el sistema operativo Microsoft Windows: Microsoft Office y Texto Enriquecido.
Quiero imprimir en papel. Microsoft Office, OpenOffice, LaTeX
Quiero las fórmulas matemáticas más bonitas. LaTeX. Microsoft Office y OpenOffice tienen editores de fórmulas.
Quiero verlo en pantalla y que sea interactivo. HTML. En menor medida Microsoft Office y OpenOffice.
Quiero exportar mi documento a muchas representaciones diferentes. DocBook, HTML.
Quiero documentar mi programa de ordenador. (Sólo para quienes ponen comentarios en el código.) DocBook, HTML, LaTeX.
El usuario de mi programa debe poder imprimir la página Web que le muestro o convertirla en un PDF. HTML, LaTeX, Texto Enriquecido, texto simple

Referencias

Formatos de Documentación
Herramientas de documentación automatizada
Artículos relacionados en este blog

Una herramienta de control de versiones tiene un cierto potencial de adicción, ya que es difícil de dejar de usarlo cuando una vez se ha conocido sus ventajas. En este artículo queremos hablar qué ficheros conviene guardar en un control de versiones y cuando conviene no usarlo. “No usar un control de versiones” significa guardar los ficheros en el sistema de ficheros de sistema operativo, es decir en los directorios de toda la vida.

Describo en otro artículo lo que es un control de versiones. En este artículo asumo que el lector ya lo sabe.

En el artículo anteriormente mencionado defino las dos razones de usar un control de versiones, que son:

  1. Ayuda a que varios programadores pueden trabajar en paralelo.
  2. Permite mantener varias versiones de un mismo programa a la vez.

Una conclusión de esto es que no se usa un control de versiones si no se da al menos una de estas condiciones, ya que no vale la pena usar una herramienta adicional si no trae beneficio. No se pueden acceder ficheros bajo el control de versiones excepto con la misma herramienta y está puede tener problemas de compatibilidad con versiones nuevas del sistema operativo como cualquier otro programa. Tampoco es fácil añadir espacio cuando el repositorio ya ha llenado el disco duro entero. Una carpeta simple, por lo contrario, es fácilmente manejable en cualquier plataforma.

La consecuencia de no programar en paralelo es bastante obvia: un sólo programador no corre riesgo de no poder trabajar por culpa de otro. Mientras uno trabaja sólo es mucho más fácil guardar todos los ficheros en las carpetas habituales, aunque eso sí: organizando los ficheros para al menos teóricamente será fácil subirlos a un control de versiones. Nunca sabes si algún día habrá otro programador contigo.

O que habrá múltiples versiones. Mantener múltiples versiones es algo habitual en proyectos grandes. Mientras el cliente prueba una versión, los programadores ya desarrollan la próxima. Si es un software que al menos en principio cualquiera pueda descargar y usar, entonces conviene mantener el código bajo un control de versiones, ya que siempre habrá varias versiones en uso. El caso contrario es un software a medida.

Una vez entregado el software a medida al cliente funcionando, nadie se interesará por un estado intermedio durante el desarrollo. Hay una versión final y punto. Entonces se guarda esta última versión en carpetas del sistema operativo y se puede liberar el espacio en el control de versiones. Si el cliente un día quiere un cambio, se puede volver a subirlo – pero entonces a una herramienta de la última generación y no el control de versiones de hace diez años.

Si el cambio está terminado y aceptado por el cliente, entonces se vuelve a guardar la versión final en un directorio del sistema operativo. Si queremos guardar estas dos versiones, entonces podemos usar dos subcarpetas “versión 1” y “versión 2”. Personalmente prefiero usar la fecha, algo como “Versión 2010-06-01”. Así uno no se lía con los números de versiones y queda aún más claro cual es la más reciente.

En fin, guardar proyectos en carpetas simples en lugar de mantenerlos en un control de versiones puede ser una mejor solución para proyectos pequeños y con pocas versiones.

Finalmente quedan todavía dos puntos adicionales a subrayar:

  • Un control de versiones no reemplaza una copia de seguridad. Guardar su trabajo diario en un disco duro alternativo es importante para no perder datos en caso de averías.
  • Aunque el primer fin de un control de versiones es guardar las versiones de sus propios ficheros fuentes, puede convenir guardar bibliotecas externas con las fuentes, ya que una nueva versión de una biblioteca externa no está garantizada de funcionar con una versión antigua del programa. No es un error guardar todas las bibliotecas externas para cada proyecto por separado, aunque serán siempre las mismas bibliotecas. Simplemente piensa qué frustración puede ser sacar un proyecto viejo del armario y que este no compila directamente porque todavía toca buscar todas las bibliotecas por ahí y a saber con qué versión.

Por cierto, nombrar carpetas con fechas es una manera simple de organizar copias de seguridad del trabajo del día.

Referencias

¿Qué es un control de versiones?

Un control de versiones una herramienta para el desarrollo de software que facilita principalmente dos funciones:

  1. Ayuda a que varios programadores pueden trabajar en paralelo.
  2. Permite mantener varias versiones de un mismo programa a la vez. (De ahí “control de versiones”)

Trabajar en paralelo

Si dos programadores realizan cambios en un mismo fichero fuente, entonces sobreescriben los cambios del otro cada vez cuando lo guardan. Incluso si un equipo de trabajo llega a organizarse para que esto no sucede, todavía es probable que todos los “prints”, “ifs”, y demás modificaciones temporales que un programador pueda poner para probar su código molesten a los demás. Si el programa no compila entonces todos los demás están parados hasta que se haya arreglado el error.

Aquí ayuda un control de versiones. Los ficheros “buenos” – es decir una versión que al menos compila – están en un servidor, el “repositorio”. Un programador trabaja sobre una “vista” a estos ficheros (habitualmente una copia local en el ordenador del programador). Si quiere cambiar un fichero, entonces debe “sacarlo del control” (hacer un check-out o desproteger). Mientras tanto los demás programdores siguen viendo la versión original del fichero y no están afectados por las modificaciones de un miembro de equipo.

Cuando el primer programador cree que su versión modificada funciona razonablemente bien, entonces la “sube” (mete, hace un check-in o la protege). Con esto se ha creado una nueva versión, que será la que verá todo el mundo que “actualice su vista”. Un control de versiones no reemplaza a una copia de seguridad, porque no se guardan los cambios en el servidor hasta que el programador lo ordene. Y esto puede durar un mes en ocasiones.

Merge

Un control de versiones sólo permite “subir” un fichero, si es el sucesor de la versión de que fue sacado. Puede suceder que dos programadores sacan sus versiones personales de la misma versión. El primero puede hacer un check-in de sus cambios sin problemas, pero el segundo debe conciliar sus cambios con las modificaciones del otro programador. Un fichero sacado no se actualiza con las versiones que los otros programadores hayan metido, ya que sobreescribirían las modificaciones propias.

La solución es un “merge” (inglés para combinar). Habitualmente se abre una pantalla con las tres versiones afectados: La versión original de donde se partió, la versión a meter y la última versión bajo control. En un caso simple se ha modificado el fichero en puntos diferentes y se pueden simplemente incluir los cambios de la versión más reciente en la versión a meter. Dos cambios en una misma línea de código causan un “conflicto” que el programador debe resolver a su criterio y con la ayuda del otro programador. Muchas veces un control de versiones puede combinar versiones sin conflictos de forma automática. No es posible hacer un merge en ficheros binarios.

Mantener varias versiones

En muchos programas de uso común es habitual mantener varias versiones. Por ejemplo, no todo el mundo está dispuesto a instalar un nuevo sistema operativo cuando Microsoft publique una nueva versión de Windows. Así Microsoft debe mantener varias versiones de Microsoft Windows al mismo tiempo que está desarrollando la próxima generación.

¿Qué significa varias versiones? Cada vez cuando un programador sube sus cambios, se crea una nueva versión que el sistema enumera con un número secuencial. Podemos decidir que alguna de estas versiones, digamos la versión 3124, será destinada a ser una “release” oficial. Entonces se “etiqueta”, por ejemplo como “Windows 8 alpha” y se crea una nueva “rama” (branch en inglés). La rama principal (“trunk” en inglés) es la en que los programadores hagan el desarrollo nuevo. La rama “Windows 8 alpha” existe en paralelo y sirve para corregir los errores que todavía pueda tener. En esta versión interesa más llegar a una versión “estable”, un “release”, que añadir un nuevo desarrollo.

Lógicamente, todos los errores que se encuentran en la versión “Windows 8 alpha” habrá que corregir también en la rama de desarrollo principal. También puede suceder que alguna funcionalidad nueva de la rama de desarrollo entra en la rama de la versión “release”. En general, los programadores tienen que modificar varias versiones y el control de versiones les permite determinar cuales.

Como es imaginable, una rama de una release puede bifurcarse también. Una sigue con las correcciones de la versión (oficial) 8.0, la otra está destinada a incluir mejoras para la release 8.1. En el momento que una versión ya no incluirá nuevas funcionalidades se “congela”. Cuando ya no se trabaja sobre ella ya no está “soportada”.

Pequeña lista comentada de control de versiones

Hasta algunos años, la comunidad de código abierto ha usado con mucho gusto el CVS (Concurrent Versions System). Ahora se usa más el Subversion, que ofrece un cliente integrado en el explorador de Windows que se llama TurtoiseSVN. Es todo gratis y una buena solución para la mayoría de los proyectos.

Cuando gratis no es un requisito puede convenir usar IBM® Rational® ClearCase®, un programa completo que permite un uso por línea de comando y por interfaz gráfico. Microsoft Visual SourceSafe es un extra con las versiones de empresa de Visual Studio, pero que a veces da impresión de ser ni visual ni seguro. La ventaja que tiene es que se integra bien con el Visual Studio.

Quien piensa en grade debe tener en cuenta que eligir una herramienta de control de versiones es una decisión estratégica de la empresa. Una base de datos es lo más difícil de actualizar en un programa y un control de versiones no es otra cosa que una base de datos donde los datos son ficheros. Es bastante probable que una empresa todavía usa el control de versiones de hoy en diez años.

Doxygen es una herramienta de documentación automatizada muy potente. Como muchos programas viene con la configuración para el inglés americano por defecto. Por eso puede haber problemas a la hora de procesar bien comentarios que usan letras con acentos como suele haber en español y muchos otros idiomas.

Una solución al problema es guardar los ficheros con la codificación UTF-8, que es la que viene por defecto también en phpDocumentor. Sin embargo, doxygen permite especificar explícitamente qué codificación a usar.

Si usas el interfaz gráfico Docwizard, entonces puedes pinchar en la pestaña “Expert”, y luego en el menú de los “Topics” seleccionas “Input”. A la derecha hay un campo que se llama INPUT_ENCODING. Cambia el valor (“UTF-8” por defecto) a la codificación de tus ficheros fuente. Para el español suele ser la codificación ISO-8859-1. Obviamente sólo puedes usar una codificación de caracteres para un proyecto.

Si no usas el interfaz gráfico puedes buscar por la cadena de texto INPUT_ENCODING en el fichero de configuración.

Si no estás seguro qué codificación a elegir, entonces puedes visualizar la documentación generada y jugar con la codificación de los caracteres del navegador hasta tu documentación  salga bien. La codificación puedes cambiar (en Mozilla Firefox) con el menú View (Ver) -> Character Encoding. Cuando haces estas pruebas fíjate en los textos que has escrito tú en la documentación; y no en los títulos que añade doxygen. Cuando pones la codificación correcta en el campo INPUT_ENCODING, tanto los textos generados a partir de los comentarios como los que añade doxygen saldrán con los acentos bien. Recuerda volver poner tu navegador a autodetectar la codificación.

Por cierto, también se puede modificar la codificación del fichero de configuración de doxygen. En la pestaña “Expert” seleccionas en el menú “Topics” el punto “Project”. A la derecha hay un campo que se llama DOXYFILE_ENCODING. Cambia el valor (“UTF-8” por defecto) a la codificación desdeada.

Referencias

Qué es

Lo que javadoc es para Java, phpDocumentor es para PHP: Una herramienta para generar documentación a partir del código fuente. (Ver artículo sobre
Documentación automatizada.)

Por ser dos proyectos separados, phpDocumentor no es automáticamente compatible con una nueva versión de PHP. Por ejemplo, yo tuve problemas con phpDocumentor 1.4.3 cuando instalé PHP 5.3 y volví a la versión 1.4.2 que funcionaba aunque con muchas advertencias.

Una alternativa a phpDocumentor es Doxygen que puede también documentar código PHP. Una diferencia es que doxygen es un programa, mientras phpDocumentor es una colección de código en PHP. Es decir, genera la documentación con el mismo PHP que usas para ejecutar tu propio código PHP. Por eso necesitas tener también PHP en tu máquina para poder usar phpDocumentor. Sin embargo, no necesitas instalar un servidor web.

Como instalar

phpDocumentor no es un programa sino un código fuente y, por eso, no tiene instalador. Es un archivo que descomprimes en un directorio. Para usar phpDocumentor debes abrir el fichero phpdoc.bat (en Windows) y especificar la ruta a php.exe en la variable phpCli. Por ejemplo

SET phpCli=C:\Program Files\PHP\php.exe

Como usar

Para un proyecto en concreto conviene crearse un script en que especificas todas las opciones de phpdoc.

El siguiente script es un ejemplo. Lo he utilizado para generar la documentación del mismo phpDocumentor. Antes de usarlo hay que ajustar los directorios de entrada y salida y de la instalación de PHP.

echo Generate automatic documenation for phpDocumentor
echo Version from 12.6.2009

rem Directory list must be without spaces between the coma
set phpdoc_dir="C:\opt\PhpDocumentor"
set source_dir="C:\opt\PhpDocumentor"
set target_dir="C:\doc\phpDocumentor"
set title="phpDocumentor Documentation"
set projects=phpDocumentor
rem set output="HTML:frames:default"
rem set output="HTML:frames:earthli"
rem set output="HTML:frames:l0l33t"
 set output="HTML:frames:phpdoc.de"
rem set output="HTML:frames:phpedit"
rem set output="HTML:frames:phphtmllib"
rem set output="HTML:frames:DOM/default"
rem set output="HTML:frames:DOM/earthli"
rem set output="HTML:frames:DOM/l0l33t"
rem set output="HTML:frames:DOM/phpdoc.de"
rem set output="HTML:frames:DOM/phphtmllib"
rem set output="HTML:frames:DOM/phphtmllib"
rem set output="HTML:Smarty:default"
rem set output="HTML:Smarty:HandS"
rem set output="HTML:Smarty:PHP"
rem set output="CHM:default"
rem set output="PDF:default"

cd %phpdoc_dir%
call phpdoc -d %source_dir% -t %target_dir% -ue on -ti %title% -pp off -po %projects% -o %output% -s off
rem pause
exit

rem These are comments, but they will not be executed because the scripts exists before
rem use phpdoc -h to see this

  -f    --filename                name of file(s) to parse ',' file1,file2.
                                  Can contain complete path and * ? wildcards

  -d    --directory               name of a directory(s) to parse
                                  directory1,directory2

  -ed    --examplesdir            full path of the directory to look for
                                  example files from @example tags

  -tb    --templatebase           base location of all templates for this
                                  parse.

  -t    --target                  path where to save the generated files

  -i    --ignore                  file(s) that will be ignored, multiple
                                  separated by ','.  Wildcards * and ? are ok

  -is    --ignoresymlinks         ignore symlinks to other files or
                                  directories, default is off

  -it    --ignore-tags            tags to ignore for this parse.  @package,
                                  @subpackage, @access and @ignore may not be
                                  ignored.

  -dh    --hidden                 set equal to on (-dh on) to descend into
                                  hidden directories (directories starting with
                                  '.'), default is off

  -q    --quiet                   do not display parsing/conversion messages.
                                  Useful for cron jobs on/off default off

  -ue    --undocumentedelements   Control whether or not warnings will be shown
                                  for undocumented elements. Useful for
                                  identifying classes and methods that haven't
                                  yet been documented on/off default off

  -ti    --title                  title of generated documentation, default is
                                  'Generated Documentation'

  -h    --help                    show this help message

  -c    --useconfig               Use a Config file in the users/ subdirectory
                                  for all command-line options

  -pp    --parseprivate           parse @internal and elements marked private
                                  with @access.  Use on/off, default off

  -po    --packageoutput          output documentation only for selected
                                  packages.  Use a comma-delimited list

  -dn    --defaultpackagename     name to use for the default package.  If not
                                  specified, uses 'default'

  -dc    --defaultcategoryname    name to use for the default category.  If not
                                  specified, uses 'default'

  -o    --output                  output information to use separated by ','.
                                  Format: output:converter:templatedir like
                                  "HTML:frames:phpedit"

  -cp    --converterparams        dynamic parameters for a converter, separate
                                  values with commas

  -ct    --customtags             custom tags, will be recognized and put in
                                  tags[] instead of unknowntags[]

  -s    --sourcecode              generate highlighted sourcecode for every
                                  parsed file (PHP 4.3.0+ only) on/off default
                                  off

  -j    --javadocdesc             JavaDoc-compliant description parsing.  Use
                                  on/off, default off (more flexibility)

  -p    --pear                    Parse a PEAR-style repository (package is
                                  directory, _members are @access private)
                                  on/off default off

  -ric    --readmeinstallchangelogSpecify custom filenames to parse like
                                  README, INSTALL or CHANGELOG files

You can have multiple directories and multiple files, as well as a combination
of both options

En la carpeta HTML nuevamente generado debes abrir el fichero index.html para ver la página principal de la documentación. La más práctico es crearse un enlace fuera del directorio con un nombre significativo como “Documentación de bla bla”.

Puedes usar letras con acentos y otras letras no ASCII si guardas el fichero fuente (con el código) con la codificación UTF-8 (con BOM). En general no es mala idea guardar tu código como UTF-8 en lugar del habitual ISO-8859 si quieres usar otros idiomas que el inglés en los comentarios, porque phpDocumentor (y también doxygen) codifican su salida HTML en UTF-8.

phpDocumentor tiene diferentes convertidores. Cada uno compila la documentación en un formato y tema diferente (HTML, PDF, CHM). La página web de phpDocumentor muestra ejemplos de los diferentes temas visuales que permite la documentación en HTML.

Crear la documentación de phpDocumentor y tutoriales

Como ya he mencionado más arriba, phpDocumentor puede crear su propia documentación. Los ficheros fuente de esta documentación están en una subcarpeta “tutorials”. Sin embargo, debes especificar el directorio raíz de phpDocumentor como directorio de entrada a phpdoc, para que se compilen estos tutoriales. (phpDocumentor no procesa documentación en “tutorials” que no esté vinculado a algún código fuente. No puedes compilar sólo tutoriales.) Como proyecto debes especificar “phpDocumentor”. (Ver ejemplo abajo.)

Esta subcarpeta “tutorials” es también un ejemplo de como escribir documentación que no está directamente vinculada a algún objeto dentro del código. Estos tutoriales están escrito en un formato reducido de DocBook. Los elementos DocBook que se compilan están listado en la sección [ppage] del fichero options.ini que viene con cada convertidor. Por ejemplo, mi tema favorito “HTML:frames:earthli” está configurado por el fichero Converters/HTML/frames/templates/earthli/options.ini. Cada convertidor/tema tiene su fichero de configuración options.ini en una carpeta diferente.

Conclusión

phpDocumentor es una herramienta potente para crear documentación a partir de código fuente PHP. El formato de comentarios de documentación es fácil de aprender por ser muy parecido al formato de javadoc. (Ver lista de características de phpDocumentor.)

Una desventaja es que cuesta hacer phpDocumentor funcionar. Es un problema que desaparece una vez familiarizado con la herramienta, pero que puede causar frustración al principio. También existe una interfaz gráfica para generar la documentación pero que requiere un servidor web propiamente configurado. No está mal pero no quita el problema de tener que leer mucha documentación antes del primer éxito. En comparación el wizard de doxygen es bastante más fácil de usar.

Además, doxygen entiende varios lenguajes de programación, aunque no es capaz de ofrecer diferentes temas. Aún así vale la pena reflexionar sobre qué herramienta usar.

Referencias

  • phpDocumentor – la herramienta descrita en este artículo
  • Doxygen – una alternativa a phpDocumentor
  • javadoc – un sistema de documentación para Java.
  • PHP – el lenguaje de programación que phpDocumentor documenta.
  • DocBook – un formato para escribir textos sin especificar su aparencia y que phpDocumentor usa para la documentación libre (tutoriales).

Escribe tu dirección de correo electrónico para suscribirte a este blog, y recibir notificaciones de nuevos mensajes por correo.

Únete a otros 46 seguidores

Archivos

mayo 2017
L M X J V S D
« Ene    
1234567
891011121314
15161718192021
22232425262728
293031