# Introducción al FDP-es

### J. Vicente Carrasco Vayá

`<carvay@FreeBSD.org>`

Este documento ha sido escrito para que sirva de guía somera a quienes quieren colaborar con FreeBSD traduciendo documentación o alguna sección de la web de FreeBSD al castellano. FreeBSD es un proyecto que crece diariamente gracias al trabajo voluntario de miles de personas de todo el mundo. La traducción de documentación y de la web supone una enorme ayuda para quienes se acercan a FreeBSD y no saben inglés (o alguna de las lenguas a las que ya esá traducido todo o parte de dicho material). Casi cualquier persona puede ayudar en alguna tarea. Si quiere colaborar reciba nuestra más calurosa bienvenida y siga leyendo.

Este documento no pretende ser exhaustivo. Casi toda la información necesaria para trabajar en el FDP está en el libro fdp-primer (que esperamos poder tener traducido algún dia) y en cuya sección de estilo está basada gran parte de este texto. Si quiere ampliar los conocimientos que aquí se esbozan (y si va a trabajar con la documentación de FreeBSD seguramente querrá hacerlo) le rogamos que lo lea cuidadosamente. Recuerde que cualquier duda que pudiera salirle al paso mientras trabaja en la documentación de FreeBSD puede enviarla a la lista de correo sobre la documentación de FreeBSD en castellano

Si tiene alguna sugerencia, crítica o duda relacionada con este artículo no dude en escribir al autor.

[ Split HTML / Single HTML ]

## 1. El FDP-es

El FreeBSD Spanish Documentation Project (en adelante FDP-es) tiene las siguientes funciones:

- Mantener al día la documentación existente en castellano e ir traduciendo más siempre que los recursos lo permitan.

- Traducir y mantener la web http://www.freebsd.org/es/.

- Desarrollar documentos propios como éste.

## 2. Tareas pendientes

Glosario: Confección y Mantenimiento de un Glosario de términos frecuentes en la Documentación para ayuda y referencia del traductor.

Páginas man: El Proyecto de Documentación de FreeBSD también se encarga de desarrollar, mantener y corregir las páginas `man` del sistema pero debido a la escasez de voluntarios es una tarea que (siendo muy optimistas) preferimos pensar que podremos acometer a medio o largo plazo.

“Scripts” `accent2xml` y `xml2accent`. Existen dos “scripts” que traducen los caracteres que no existen en inglés a código sgml; por ejemplo `&aacute;` a “`á`”, &iquest; a “`¿`”, etcétera. Sería muy útil disponer de sus homólogos xml para facilitar el trabajo de aquellas personas que traducen secciones de la web y (cosa poco sorprendente) no conozcan de memoria todos los secretos de xml.

## 3. Cómo formar parte del FPD-es

Casi cualquier persona puede formar parte del FDP-es. Igual que sucede en el FDP no hay cuota mensual que haya que pagar ni una cantidad mensual o anual de material que haya que traducir de forma obligatoria. Basta con suscribirse a la lista de correo sobre la documentación de FreeBSD en castellano. Puede aportar sus conocimientos de inglés para ayudar con las dudas de quienes están traduciendo o quizás pueda dedicar un poco de su tiempo a traducir.

### 3.1. Asignación de trabajos

Al depender del esfuerzo voluntario es lógico que cada cual pueda elegir qué parte de la web o de la documentación desea traducir. Dentro de poco esperamos disponer de una página web pública en la que poder consultar qué textos están asignados y desde cuando. De momento el procedimiento es el siguiente:

- la persona interesada en traducir elige un texto que desea traducir y dos alternativas por si su primera elección ya está asignada

- el coordinador de traducciones le asigna el texto

- el texto traducido es revisado e incluído en el repositorio del FDP-es primero y en el del FDP después.

### 3.2. Si puede dedicar un poco de tiempo

Puede traducir una sección de la web, un capítulo del handbook o un artículo y entregarlo en formato ASCII (texto plano). Tenga en cuenta que alguien tendrá que darle formato (DocBook o xml en el caso de la web). Será de grandísima ayuda si entrega su trabajo con los acentos, eñes y demás signos característicos de nuestro idioma corregidos al formato adecuado. Consulte la tabla que encontrará en http://www.theorem.ca/~mvcorks/code/charsets/latin1.html o utilice el “script” perl `accent2sgml.pl` ubicado en `doc/share/examples/vim/`. La parte más difícil del trabajo es sin duda alguna la traducción pero si pudiera avanzar trabajo adaptando en lo posible la sintaxis del texto a sgml o xml (o maquetándolo usted, pruébelo: no es difícil) aligerará notablemente la carga de trabajo de unos cuantos (y mortales) voluntarios y voluntarias. Tenga en cuenta que no sobra precisamente el personal para estas tareas y enfrentarse a convertir un texto ASCII de 5.000 líneas a DocBook puede hacer flaquear al voluntario más comprometido.

### 3.3. Con un poco más de tiempo

La forma ideal de entrega de trabajos al FDP-es es enviarlos listos para incluir en el árbol cvs de FreeBSD. Si tiene un especial interés en un texto en concreto puede encargarse de su mantenimiento (es lo que llamamos “apadrinar” ese texto). En poco tiempo se convertirá en su mejor conocedor y no le resultará difícil ir añadiendo los cambios a medida que se vayan produciendo en el original. De este modo al menos una fracción de la documentación tendrá más posibilidades de estar al dia;-)

### 3.4. Colaboración esporádica

En la lista de correo sobre la documentación de FreeBSD en castellano hay personas que colaboran resolviendo dudas que surgen a los traductores. Si por el motivo que fuera no quiere o no puede traducir textos no debería subestimar la importancia de la ayuda que puede prestarse de este modo. Gracias a estas personas los traductores encuentran más argumentos a favor o en contra de traducir ciertos términos, con lo que la documentación resulta más útil; y nuestro trabajo consiste en hacer algo útil.

### 3.5. ¿Todo el mundo puede traducir?

En principio sí, pero no necesariamente. Le recomendamos que si quiere traducir documentación se familiarice con otros textos ya traducidos y comience por colaborar con las dudas de los traductores en la lista de correo sobre la documentación de FreeBSD en castellano.

La documentación de FreeBSD goza de una merecida fama de calidad, lo que hace que el trabajo de un proyecto de traducción como el nuestro implique una gran responsabilidad. Es imposible mantener una fidelidad absoluta al original, pero dentro de lo posible lo intentamos. Al tratarse de textos técnicos hay que tener muy presente al traducirlos que sin duda alguna van a ser utilizados como guía. Se suele exigir a los recién llegados a FreeBSD que lean la documentación relacionada con sus dudas antes de preguntar dudas, así que, al menos en teoría, lo que usted traduzca tendrá ávidos lectores. Tenga esto muy presente al traducir: mejor preguntar una duda de más en la lista de correo sobre la documentación de FreeBSD en castellano que incluir información errónea en un texto.

Se estará preguntando ¿cuál es el perfil necesario para traducir? La verdad es que no hay un acuerdo sobre esto. Es obvio que necesita comprender el inglés técnico (americano) en el que está escrita la documentación de FreeBSD, [1] y por supuesto sólidos conocimientos de castellano. Dicho de otro modo, no es imprescindible hablar inglés, basta con comprenderlo lo mejor posible, pero es imprescindible la expresión escrita en castellano. La calidad de una traducción es algo totalmente subjetivo, pero suele haber acuerdo entre los miembros de la lista entre lo que es asumible [2] y lo que no lo es. El trabajo de arreglar una mala traducción puede ser igual de largo que traducir desde cero un texto y es varios órdenes de magnitud más penoso. Encontrar un buen traductor de textos técnicos es tanto o más difícil que encontrar un buen programador, como sabe cualquiera que haya abierto más de una docena de libros técnicos traducidos a nuestro idioma [3] Cuando envíe un texto traducido para su revisión es posible que, aunque ponga mucho cuidado para evitarlo, aparezcan errores en el código SGML o en el propio texto. El trabajo de revisión consiste precisamente en eso así que no se preocupe, dentro de la ayuda esporádica que algunas personas ofrecen al FDP-es está la de revisar textos de otros. Un voluntario depurará el texto en caso de que haga falta y lo dejará listo para subir al cvs [4].

## 4. Guía de estilo

Esta sección están basada en la sección “writing style” del libro “fdp-primer” que puede consultarse en (http://www.es.FreeBSD.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style.html).

Es necesario intentar mantener la consistencia entre la multitud de autores que trabajan en la Documentación de FreeBSD, razón por la cual se han creado unas líneas generales. A esta búsqueda de la consistencia se opone también la variedad de orígenes de los traductores de la Documentación, por lo que se listan aquí unas cuantas normas que pueden ser de ayuda. Dado que la Documentación que va a traducir ya ha pasado por más de una mano experta puede usarla como plantilla para su traducción.

Idioma

- El idioma oficial del FDP-es es el castellano (o español de España), es_ES; la decisión de tener lengua oficial no es una idea exclusiva nuestra puesto que en el el Proyecto de Documentación de FreeBSD el idioma oficial es el inglés de los Estados Unidos de América (en_US). Se intenta evitar el uso de palabras “agresivas” con otros castellanoparlantes como `ordenador` (computador, computadora, sistema, máquina o incluso host) pero al iniciar los trabajos necesitaban una norma y lógicamente usaron la que la que más cerca tenían.

- Evite frases redundantes

  Intente evitar usar frases redundantes. Por ejemplo “el comando”, “el fichero” y “man comando” probablemente son redundantes.

  He aquí dos ejemplos en el caso de los comandos. El segundo ejemplo mostrado es el recomendable.

- Utilice el comando `cvsup` para actualizar sus fuentes

- Utilice `cvsup` para actualizar sus fuentes

Veamos dos ejemplos para nombres de ficheros. Recomendamos el uso del segundo ejemplo.

... en el fichero llamado `/etc/rc.local`...

... en `/etc/rc.local`...

Veamos un ejemplo sobre páginas man. Recomendamos el uso del segundo caso, que usa `<citerefentry>`.

Para más información consulte `man csh`.

Consulte csh(1)

Dos espacios al final de cada frase

  Deje siempre dos espacios al final de cada frase. El texto será más legible y se facilita el uso de herramientas como Emacs.

  Puede pensarse que una mayúscula tras un punto indica nueva frase pero no siempre es así, sobre todo si se trata del nombre de algunas personas. “Jordan K. Hubbard” es un buen ejemplo de ello. Tiene una `H` mayúscula tras un punto y un espacio y es evidente que no es una nueva frase.

## 5. Guía de sintaxis

Por favor, siga éstas sencillas reglas para facilitar el trabajo de toda la gente que mantiene el código fuente de la documentación.

### 5.1. Minúsculas

Las etiquetas van siempre en minúsculas: `<para>`, no `<PARA>`.

El texto SGML normalmente se escribe en mayúsculas: `<!ENTITY...>` y `<!DOCTYPE...>`, no `<!entity...>` o `<!doctype...>`.

### 5.2. Sangrado

Cada fichero comienza con un sangrado nulo, es decir, en la columna 0, sin tener en cuenta el nivel de sangrado del fichero que pueda contenerlo.

La apertura de etiquetas incrementa el nivel de sangrado en 2 espacios. Reemplace los bloques de 8 espacios al inicio de una línea con una tabulación. No use espacios antes de una tabulación y no añada espacios al final de una línea. El contenido que esté entre elementos debe sangrarse en dos espacios si el contenido ocupa más de una línea.

Por ejemplo, el código fuente de esta sección es algo parecido a esto:

    +--- Ésta es la columna 0
    V

      <sect1>
        <title>...</title>

        <sect2>
          <title>Sangrado</title>

          <para>Cada fichero comienza con un sangrado nulo, es decir,
        en la columna 0, <emphasis>sin tener en cuenta</emphasis>
        el nivel de sangrado del fichero que pueda contenerlo.</para>

          ...
        </sect2>
      </sect1>
    </chapter>

Si usa Emacs o XEmacs para editar ficheros que forman parte de la Documentación se cargará automáticamente el `sgml-mode` y las variables locales que Emacs encontrará al principio de cada fichero podrán utilizarse.

Si usa Vim puede serle muy útil incluir lo siguiente en la configuración de su editor:

    augroup sgmledit
      autocmd FileType sgml set formatoptions=cq2l " Opciones especiales de formato
      autocmd FileType sgml set textwidth=70       " Corta las lìneas a 70 espacios
      autocmd FileType sgml set shiftwidth=2       " Sangra automáticamente
      autocmd FileType sgml set softtabstop=2      " Tabulación = 2 espacios
      autocmd FileType sgml set tabstop=8          " Reemplaza 8 espacios con Tab
      autocmd FileType sgml set autoindent         " Sangrado automático
    augroup END

### 5.3. Etiquetas

#### 5.3.1. Espacios en las etiquetas

Las etiquetas que comienzan en el mismo nivel de sangrado que la etiqueta anterior deben separarse con una línea en blanco, y las que no están al mismo nivel de sangrado que la anterior no:

    <article>
      <articleinfo>
        <title>NIS</title>

        <pubdate>Octubre 1999</pubdate>

        <abstract>
          <para>...
        ...
        ...</para>
        </abstract>
      </articleinfo>

      <sect1>
        <title>...</title>

        <para>...</para>
      </sect1>

      <sect1>
        <title>...</title>

        <para>...</para>
      </sect1>
    </article>

## 6. Trato al lector o lectora

Cuando hay que dirigirse al lector o lectora siempre usamos el usted, habitual en muchos países en cualquier ámbito y respetuoso en cualquiera de los demás. Como puede verse en el título existe también el problema del género de quien lee el texto; casi siempre hay una manera de evitar usarlo (buscando bien) pero puede alternarse el uso del género. Evitamos el uso de la forma lector/a, programador/a, etcétera, que a costa de una pretendida corrección política convierte a los textos en algo bastante más difícil de leer.

## 7. Léxico

Es muy importante intentar evitar argot, giros, dichos o bromas exclusivos de un sólo país, región, ciudad o grupo social. La Documentación será leída por gentes muy diversas en cualquier lugar del mundo y puede ser muy frustrante que lo que uno quiere hacer esté documentado pero no lo podamos entender “por no haber viajado suficiente”.

## 8. Ayuda

### 8.1. Lista doc@es.FreeBSD.org

La lista de correo sobre la documentación de FreeBSD en castellano es el lugar ideal para enviar:

dudas de traducción

ideas, sugerencias, críticas sobre la documentación (en castellano o relacionadas con la Documentación en inglés)

errores en la generación de documentación

### 8.2. Diccionarios en Internet

Existen muchos diccionarios en Internet y en bastantes de ellos podemos consultar términos gratuitamente. Las palabras más técnicas y muchas exclusivas de FreeBSD no aparecerán en ninguno de estos diccionarios y en pocos de los editados en papel, por lo que tendrá que recurrir a otros documentos ya traducidos o a la lista de correo sobre la documentación de FreeBSD en castellano.

## 9. Envío de traducciones

1. Por correo electrónico al coordinador, o bien

2. si lo considera conveniente, enviarlo a la lista de correo sobre la documentación de FreeBSD en castellano para su revisión.

3. send-pr(1)

## 10. Voluntarios del FDP-es

Estos son los colaboradores habituales del FDP-es. Si cree que su nombre debe (o no debe) aparecer en esta lista puede escribir al autor.

(en orden alfabético por apellido):

- José Ramón Baz `<jr_baz@hartu.net>`

- José Vicente Carrasco Vayá `<carvay@es.FreeBSD.org>`

- Luis López `<cronopiolopez@terra.es>`

- Jesus R. Camou `<jcamou@FreeBSD.org>`

- Jesus Rodriguez `<jesusr@FreeBSD.org>`

- Juan F. Rodriguez `<jrh@it.uc3m.es>`

- Enrique Matías Sánchez `<cronopios@gmail.com>`

## 11. Agradecimientos

A la lista de correo sobre la documentación de FreeBSD en castellano por su infinita paciencia durante las revisiones de este documento (y desde mucho antes) y a Jesus Rodriguez `<jesusr@FreeBSD.org>` por lo mismo y además por animarme. Que tiene delito.

### Notas

[1] | También puede traducir desde alguno de los idiomas en los que hay documentación de FreeBSD. Puede echar un vistazo a los textos traducidos a distintas lenguas en http://www.es.FreeBSD.org/doc/.
[2] | es decir, lo que podemos subir al cvs para que cualquiera pueda verlo repartido por los sitios web de FreeBSD del mundo entero
[3] | Si es su caso, ya sabe a ciencia cierta que tener una o más carreras, técnicas o no, no evita que alguien sea capaz de perpetrar “traducciones” abominables y además cobrar por ello. Nosotros no pagamos, pero somos mucho más estrictos.
[4] | es posible que el revisor le devuelva el texto si las modificaciones que hay que hacer son muchas y usted mismo puede hacerlas)

Puede descargar éste y muchos otros documentos desde ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

Si tiene dudas sobre FreeBSD consulte la documentación antes de escribir a la lista <questions@FreeBSD.org>.
Envíe sus preguntas sobre la documentación a <doc@FreeBSD.org>.