Existen diversas herramientas para la creación de páginas para el comando man. En este caso me centraré en pod2man, una aplicación muy fácil de usar y que viene en casi todas las distros. pod2man es una utilidad que viene junto al perl, por ello es muy difícil que no se encuentre en una distro; es una de las razones por la que la he escogido.

Al grano. Para crear la página de manual de un programa (el de los dados, por variar). Lo primero será editar un archivo de texto plano, para ello utilizamos vim o emacs (¿has utilizado nano?), que deberá tener la siguiente estructura:

=head1 NOMBRE

juego - programa para lanzar dados

=head1 SYNOPSIS

juego un_numero

=head1 DESCRIPCION

Este es un programa que sirve para lanzar dados. ¿qué? ¿cómo? ¿no te gusta? ¿te parece inútil? A mi también y no me ando quejando ¿acaso crees que es fácil hacer ejemplos de práctica? Mejor dedicate a aprender gran-son hijo de *******. Es en serio: si estudias este tutorial te volverás un poco más inteligente, tu mente se abrirá, cada vez aprenderás más, llegará a tu escritorio una carta donde se te pide trabajar en una sofisticada empresa de software (solo porque entiendes el programa de los dados), luego harás conferencias en todos lados (y para toda clase de personas: programadores, linuxeros, adictos al juego de dados, etc.), luego te harás muy rico, tendrás sexo con las mujeres más lindas del mundo, comprarás Playboy, conquistarás el mundo... y cuando todo eso pase, te acordarás de mi, sí, ese pobre que hizo un tutorial de más de 30 páginas, con el único fin de aportar su granito de arena, y al que un dia miraste con asco, pensando que era un negligente, mediocre e ignorante, y.... eso es todo. (todo esto es para llenar más espacio en esta parte manual, pero podría facilmente suceder)

=head1 AUTOR

Cristian Castiblanco E<lt>castidiablo@gmail.comE<gt>.

=cut

Llamaremos a este archivo juego.pod. Luego utilizaremos el comando pod2man para crear la página de documentación, así:

$ pod2man --lax juego.pod > juego.1

La opción lax se utiliza para que se acepten nombres diferentes a los habituales para las secciones, pues en este caso están traducidos al español. La página leída puede ser observada con el comando:

$ man -l juego.1

El único paquete necesario para la utilización de pod2man es perl. Si el programa que se quiere documentar está escrito en perl, el código pod puede estar dentro del propio programa y puede servir tanto para documentar el código fuente, como para crear la documentación adicional para man. Por otro lado, he leído en una bitácora (en barrapunto) la existencia de un programa llamado asciidoc, y según los comentarios es excelente, pero en verdad no lo he utilizado, si deseas más información acerca de éste programa no queda más que utilizar el Google.

Antes que nada debemos tener claro ¿Qué es un IDE? IDE son las siglas en inglés de Integrated Development Environment algo así como Ambiente Integrado de Desarrollo, y es un conjunto de herramientas útiles al programador colocadas en un todo para no tener que estar usando las herramientas por separado y de diferentes autores. Los componentes más comunes de un IDE son: un editor de texto, un compilador, un intérprete, un depurador y después vendrán los plugins que cada IDE tenga como característica especial.

Algunos IDE pueden tener soporte para varios lenguajes de programación y otros están especializados para un solo lenguaje. El IDE del que hablaremos es Anjuta IDE; este es un proyecto libre que busca ofrecer un IDE para C y C++, aunque también se soportan otros lenguajes como Perl. Anjuta está escrito para GTK+ y GNOME.

Muchas de las distribuciones más populares de GNU/Linux ya traen entre sus paquetes a Anjunta, y será fácil de instalar usando sus respectivas herramientas (apt-get, urmpi, emerge , e tc.) Sin embargo desde el sitio web del proyecto podemos descargar el tarball para instalarlo nosotros mismos.

Lo primero que debemos hacer una vez que lo hayamos descargado es extraer el contenido del tarball:

$ tar -xvzf anjuta-1.2.4.tar.gz

Después de esta instrucción desde la línea de comandos, entraremos al directorio en donde se encuentra todo el contenido del tarball

$ cd ./anjuta-1.2.4a

Algo que siempre recomiendo en la instalación de cualquier cosa es el leer el README.TXT, esto siempre es importante en todo lo que hagamos. Bien, continuando con la instalación debemos de tipear las siguientes instrucciones desde la línea de comandos:

$ ./configure
$ make
$ make install

Ahora sí entiendes como funciona eso de make ¿verdad? Con esto habremos terminado de construir Anjuta IDE sin importar si está o no empaquetado para nuestra distribución.

El primer contacto con Anjuta

La primera vez que iniciemos Anjuta veremos un IDE sencillo, bien ordenado y que si no supiéramos nada de software alternativo, bien podría pasar por un IDE de esos comerciales. Al dar click en nuevo nos aparecerá un diálogo que nos preguntará el tipo de archivo a crear, un .c, .cpp, .pl, etc. Algo que m e llamó la atención de esta parte es que podemos activar una casilla con la cual nuestro nuevo programa ya aparecerá comentado con la leyenda de la GPL, así desde antes de escribir el código ya nuestro programa es libre.

Anjuta tiene todo lo que podemos esperar de un herramienta que nos ayudará a programar, como es un asistente que nos guiará paso a paso en la creación de nuestros proyectos; o si ya tenemos un proyecto hecho y queremos importarlo, bueno, pues Anjunta cuenta con esta opción; y claro, ya hablando de las características del editor pues tendremos el ya muy característico resaltado de sintaxis, identado y el autocompletado de instrucciones y variables.

En pequeño ejemplo

Anjuta es tan sencillo que realmente no hay mucho que decir, pues todo no lo pone a nuestro alcance, así que probaremos nuestro ya famoso programa de lanzar dados. Como ya tenemos los archivos, lo único que tenemos que hacer es ir al menú Archivo y dar click en Abrir; escogemos nuestros dos programas en C++ de ejemplo juego.cpp y tirador .cpp; luego vamos al menú Build y le damos en "Compile".

Ahora ejecutemos el programa... recuerda que es necesario enviar/pasarle un argumento a nuestro programa. Anjuta nos dá la posibilidad de simplemente Ejecutar el programa o Ejecutarlo con parámetros. Para esto vamos al menú Build y le damos en “Set program params”, click en ejecutar y...

Esto es lo básico del Anjuta, pero el programa está lleno de opciones y herramientas... una muy buena es el permitenos trabajar con CVS.