Porque hay que escribir el MAN

Contents

Porque hay que escribir el MAN
1. Porque escribir
2. Como escribir
Enlaces

Porque escribir

escribir el man de una aplicación es de las partes mas importantes en el desarrollo de Software para algunos es incluso mas importante que escribir código. Es uno de los compromisos esenciales que se adquiere al trabajar en un proyecto SoftwareLibre, pues es una forma de garantizar que el resto de la comunidad este en capacidad de comprender el propósito del Software, que librerías lo conforman, los formatos de archivo con los que trabaja, etc.

Lo ideal seria que siempre se escriba Documentación, así se desarrolle software que no se piensa utilizar, pues unos meses después, el objetivo y la composición de un software no documentado se puede olvidar, dejando así un software que no es claro lo que hace y que nadie sabe como esta echo. Cosa que termina consumiendo mas tiempo pues hay que hacer una revisión del software para volver a medio comprender porque se hizo y como se hizo.

Como escribir

para empezar es necesario saber que un man esta dividido en secciones que explican partes diferentes del Software.

usualmente un man esta compuesto por seciones como las siguientes:

NAME           Name section, the name of the function or command.
SYNOPSIS       Usage.
DESCRIPTION    General description
OPTIONS        Should include options and parameters.
RETURN VALUES  Sections two and three function calls.
ENVIRONMENT    Describe environment variables.
FILES          Files associated with the subject.
EXAMPLES       Examples and suggestions.
DIAGNOSTICS    Normally used for section 4 device interface
               diagnostics.
ERRORS         Sections two and three error and signal handling.
SEE ALSO       Cross references and citations.
STANDARDS      Conformance to standards if applicable.
BUGS           Gotchas and caveats.
SECURITY CONSIDERATIONS
               Security issues to be aware of.
other          Customized headers may be added at the authors
               discretion.

escribir un man es vastante sencillo, lo unico que hay que tener en cuenta en que para hacerlo se usa un conjunto de palabras clave que hacen parte de un lenguaje de marcas, las principales marcas son:

.TH -> Indica el titulo/cabecera de la pagina del manual
.SH -> cabecera de una sección
.PP -> Nuevo párrafo
."  -> una linea de comentario
.TP -> Indenta en texto que esta hasta dos lineas después de esta macro
.nf/.fi -> para la inclusión de testo pre formateado, este texto va entre estas dos macros

A continuacion un pequeño ejemplo de una pagina de Manual

.TH cdspeed 1  "September 10, 2003" "version 0.3" "USER COMMANDS"
.SH NAME
cdspeed \- decrease the speed of you cdrom to get faster access time
.SH SYNOPSIS
.B cdspeed
[\-h] [\-d device] \-s speed
.SH DESCRIPTION
Modern cdrom drives are too fast. It can take several seconds
on a 60x speed cdrom drive to spin it up and read data from
the drive.  The result is that these drives are just a lot slower
than a 8x or 24x drive.  This is especially true if you are only
occasionally (e.g every 5 seconds) reading a small file. This
utility limits the speed and makes the drive more responsive
when accessing small files.
.PP
cdspeed makes the drive also less noisy and is very useful if
you want to listen to music on your computer.
.SH OPTIONS
.TP
\-h
display a short help text
.TP
\-d
use the given device instead of /dev/cdrom
.TP
\-s
set the speed. The argument is a integer. Zero means restore maximum
speed.
.SH EXAMPLES
.TP
Set the maximum speed to 8 speed cdrom:
.B cdspeed
\-s 8
.PP
.TP
Restore maximum speed:
.B cdspeed
\-s 0
.PP
.SH EXIT STATUS
cdspeed returns a zero exist status if it succeeds to change to set the
maximum speed of the cdrom drive. Non zero is returned in case of failure.
.SH AUTHOR
Guido Socher (guido (at) linuxfocus.org)
.SH SEE ALSO
eject(1)

Enlaces

Para ver mas información sobre la forma de escribir un man ver Como hacer una pagina de manul en Linux