Como contribuir con la traduccion de los ManPages-es. (Parte 1)

Para iniciar es importante saber las partes que componen un ManPage.

Ejemplo.

.\" Copyright
.\"
.\" Most of this was copied from the README file.
.\" Do not restrict distribution.
.\" May be distributed under the GNU General Public License
.TH <program> x "<date>" "" "Linux User's Manual"

.SH NAME
<program> \- program for...

..SH SYNOPSIS
.B <program>
.RI [ options ]
.br

.SH DESCRIPTION
This manual page explains the \fB<program>\fP program. The \fB<program>\fP program is for...

.SH OPTIONS
.IP \fB\-OPTION\fP
This option...

.SH NOTES

.SH "SEE ALSO"

La primera Orden en una página del manual (Despues de las lineas de comentarios) debería ser

.TH <titulo> <sección> <fecha> <fuente> <manual> Donde:

título – Es el titulo de la pagina del manual.

sección – Es el numero de Sección donde debería ir la pagina.

fecha – Esta es la fecha de la ultima revisión (la fecha debería cambiarse cada vez  que se modifica la pagina, ya que                     esta es la forma mas genérica de llevar un  control de la versión).

fuente – Indica cual es la fuente de la orden.

Para ficheros Binarios, se utilizan nombre como: GNU,NET-2,Distribución SLS,Distribución MCC.

Para llamadas al sistema, se especifica la versión actual del núcleo: Linux 0.99.11.

Para llamadas a las bibliotecas, se especifica la fuente de la funcion: GNU, BSD, etc.

manual – Indica el titulo del manual (ejemplo. Manual del programador linux).

Nota: Las paginas del manual de BSD con formato mdoc comienzan con la orden Dd,no con la orden TH. Tradicionalmente las secciones del manual se definen como las siguentes:

0 Cabeceras de la biblioteca estándar de C.

Son los archivos de Cabecera de la biblioteca estándar de C.

1 comandos.

Son órdenes que el usuario puede ejecutar desde el interprete de ordenes.

2 Llamadas al sistema.

Son funciones que el núcleo debe ejecutar.

3 Llamadas a bibliotecas.

La mayoria de las funciones de libc, tales como qsort(3) o scanf(3).

4 Ficheros especiales.

Ficheros que se encuentran en /dev.

5 Formatos de ficheros y convenciones.

El formato de /etc/passwd y otros ficheros legibes.

6 Juegos

Pues para esta no creo que tenga mucho que explicar.

7 Paquetes de macros y convencies.

Describe a estructura estandar del sistema de ficheros, protocolos de red, ASCII

y otros codigos de caracteres, esta pagina de man y otras cosas.

8 Órdenes para a administracion de Sistema.

Órdenes como mount(8), muchas de las cuales sólo pueden ser ejecutadas por el superusuario.

9 Rutinas de núcleo.

Esta es una sección de manua obsoleta. Una vez pensó que una buena idea seria documentar

aquí e núceo de  linux, pero,  en realidad de ha documentado muy poco y la documentación que

existe ya está desfasada. Existen mejores fuentes de informacion para los desarrolladores del núcleo.

Secciones del ManPage.

Las secciones se empiezan con .SH seguido del encabezamiento. Si el nombre contiene espacios y aparece en la misma linea que el .SH, entonces se debe poner el encabezamiento dentro de comillas dobles. Los encabezamientos tradicionales o sugeridos son:

NOMBRE, SINOPSIS, DESCRIPCION, VALOR DEVUELTO, ESTADO DE SALIDA, TRATAMIENTO DE ERRORES,

ERRORES, OPCIONES, USO, EJEMPLOS, FICHEROS, ENTORNO, DIAGNOSTICOS, SEGURIDAD, CONFORME A,

NOTAS(u OBSERVACIONES), FALLOS, AUTOR Y VEASE TAMBIEN. Donde se aplique un encabezamiento tradicional, es recomendable usarlo. Este tipo de consistencias puede hacer que la informacion sea más fácil de comprender. Sin embargo, sientete libre de crear tus propios encabezados si hacen mas facil las comprencion de las cosas. El único encabezamiento obligatorio es el  NOMBRE, que debe ser la primera sección y cuya siguiente línea debe ser una descripción, de una línea, del programa:

.SH NOMBRE

supertux   \-  El juego de SuperTux

Es muy importante respetar este formato. Nótese que despues del nombre de la órden hay una barra invertida antes del guión. Esta sintaxis la utiliza el programa makewhatis(8) para crear una base de datos de descripciones breves para las ordenes whatis(1) y apropos(1).

Otras secciones tradicionales poseen los siguientes contenidos:

–   SINOPSIS   –

Brevemente describe la interfaz de la orden o función. Para las ordenes, muestra la sintáxis de

la orden y sus argumentos (Incluyendo las opciones). La negrita se utiliza para el texto literal y

la itálica para indicar los argumentos que son reemplazables, Los corchetes ( [] )  rodean

argumentos  opcionales, las barras veticales ( | ) separan  alternativas y las elipses ( … ) se pueden

repetir. Para las funciones, muestra cualquier declaracion de datos o directivas #include necesarias,

seguida por la declaracion de la función.

–   DESCRIPCION   –  

Explica lo que la orden, función o formato hace y cómo interactúa con ficheros o con la entrada estándar, y lo que produce en la salida estándar o en la salida de error estándar. Omite detalles internos o de implementación a menos que sean críticos para comprender la interfaz. Describe el caso usual. Para informacion sobre opciones, use la seccion OPTIONS. Si existe algún tipo de gramática la entrada o conjunto complejo de subórdenes, considere el describirla en una sección de USO APARTE (y sólo coloque un resumen en la sección DESCRIPCIÓN).

–   VALOR REVUELTO   –

Da un lista de los valores que la rutina de biblioteca devolvera el invocador y las condiciones que hace que se devuelvan esos valores.

–   OPCIONES   –

Describe las opciones aceptadas por el programa y cómo aquellas  cambian su comportamiento.

–   USO   –

Describe la gramática de cualquier sublenguaje que éste implemente.

–   EJEMPLOS   –

Muestra uno o más ejemplos describiendo como se utiliza la función, fichero u orden.

–   FICHEROS   –

Lista los ficheros que el programa o función usa, tales como ficheros de configuración, fichero de inicio y ficheros sobre los que el programa trabaja directamente. Da las rutas complejas de estos ficheros y usa el proceso de instalación para modificar la parte de directorios para concordar con las preferencias de los usuarios. Para muchos programas, el lugar de instalación por defecto es /usr/local por lo que la página de manual debería usar /usr/local como base.

–   ENTORNO   –

Lista  todas las variables de entorno que afectan a su programa o función y cómo aquellas le afectan.

–   DIAGNOSTICO   –

Da una breve descripción de los mensajes de error más comunes y cómo hacerles frente. No necesita explicar mensajes de error del sistema o señales fatales  que puedan  aparecer durante la ejecución de cualquier programa a menos que sean especiales de alguna forma para su programa.

–   SEGURIDAD   –

Trata sobre problemas de seguridad y sus implicaciones. Advierte sobre configuraciones o entornos que se deben evitar, órdenes que pueden tener implicaciones para las seguridad, etc., especialmente si no son obvios. Tratar la seguirdad en una sección aparte no es necesario. Si es fácil de entender, coloque la información sobre seguridad en las otras secciones (tales como DESCRIPCIÓN O USO). No obstante, por favor, incluya la información sobre seguridad en algún lugar.

–   CONFORME A  –

Describe cualquier estándar o convención que ésta implementada.

–   NOTA    –

Proporciona diversas notas.

–   FALLOS    –

Lista limitaciones, defectos o inconveniencias conocidos y otras actividades cuestionables.

–   AUTOR   –

Lista los autores de la documentacion o programas de tal manera que pueda evitarles un correo para informarles de cualquier fallo.

–   VÉASE TAMBIÉN   –

Lista páginas de manual relacionadas en orden alfabético, posiblemente sequidas de otras páginas o documentos relacionados. Convencionalmente, ésta es la última sección.

Detalles extras

Aunque el mundo UNIX tiene muchas convenciones arbitrarias para las páginas de manual, la existencia de cientos de páginas del manual Linux define nuestros estándares de fuentes:

Para funciones, los argumentos siempre se especifican  usando itálicas, incluso en la seccion SINOPSIS,  mientras que el resto de la función se escribe en negrita:

int myfunction(intargc, char **argv);

Los nombres de ficheros van siempre en letra itálica ( p.ej., /usr/include/stdio.h ), excepto en la sección SINOPSIS, donde los ficheros van en negrita (p. ej., #include  <stdio.h>).

Los macros especiales que suelen ir en mayúsculas, van en negrita (p.ej., MAXINT).

Cuando enumeramos una lista de códigos de error, estos van en negrita (esta lista normalmente usa la macro .TP).

Referencia a otras páginas del manual ( o de algún tem dentro de la página actual) van en negrita. Si se incluye el numero de sección del manual, se debe dar en tipo de letra Romana (Normal),  sin espacions (p.ej., man(7)).

Las órdenes para seleccionar el tipo de letra son:

.B  –  Negrita.

.BI  –  Negrita alternándose con itálica (especialmente útil para especificación de funciones).

.BR  –  Negrita alternándose con romana (especialmente útil para referenciar a otras páginas de manual).

.I  –  Itálica.

.IB  –  Itálica alternándose con negrita.

.IR  –  Itálica alternándose con romana.

.RB  –  Romanda alternándose con negrita.

.RI  –  Romana alternándose con itálica.

.SB  –  Pequeña alternándose con negrita.

.SM  –  Pequeña (Útil para Acrónimos).

Tradicionalmente cada Orden puede tener seis argumentos como  máximo, pero la implementación de GNU elimina esta limitación (aunque tal vez usted todavía quiera limitarse a 6 argumentos por el bien de la portabilidad). Los argumentos se delimitan por espacios. Si el argumento contiene espacios, se debe usar comillas dobles. Todos los argumentos se imprimen uno al lado de otro sin espacios entre medio, de esta forma, la orden. .BR se puede usar sin especificar una palabra en negrita seguido por un signo de puntación en romano. Si no se da ninguún argumento, la orden se aplica a la siguiente línea de texto.

De momento es todo lo que se de los ManPages pero me encuentro estudiando un par de ordenes especiales que espero poner muy pronto en un post, asi que solo les puedo adelantar que ya estan parte de los manpages en traduccion en el git de aztli.

github

Tambien esta un archivo README que explica la funcion de un traductor voluntario pero  sin ningun problema pueden incluirse en el manpage que traduzcan como sus traductores.