<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<!--
The FreeBSD Spanish Documentation Project
$FreeBSD$
-->
<article lang="es">
<articleinfo>
<title>Introducción al FDP-es</title>
<author>
<firstname>J. Vicente</firstname>
<surname>Carrasco Vayá</surname>
<affiliation>
<address><email>carvay@FreeBSD.org</email></address>
</affiliation>
</author>
<releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para>Este documento ha sido escrito para que sirva de guía
somera a quienes quieren colaborar con &os; traduciendo
documentación o alguna sección de la web de &os; al
castellano. &os; 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 &os; 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.</para>
<para>Este documento no pretende ser exhaustivo. Casi toda la
información necesaria para trabajar en el FDP está
en el libro <ulink
url="http://www.es.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/">fdp-primer</ulink>
(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 &os; 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 &os; puede enviarla a la &a.es.doc;</para>
<para>Si tiene alguna sugerencia, crítica o duda relacionada con
este artículo no dude en escribir al autor.</para>
</abstract>
</articleinfo>
<sect1>
<title>El FDP-es</title>
<para>El &os; Spanish Documentation Project (en adelante FDP-es) tiene
las siguientes funciones:</para>
<itemizedlist>
<listitem>
<para>Mantener al día la documentación existente en
castellano e ir traduciendo más siempre que los recursos
lo permitan.</para>
</listitem>
<listitem>
<para>Traducir y mantener la web <ulink
url="http://www.es.freebsd.org/es/">http://www.freebsd.org/es/</ulink>.</para>
</listitem>
<listitem>
<para>Desarrollar documentos propios como éste.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Tareas pendientes</title>
<para> Glosario: Confección y Mantenimiento de un Glosario de
términos frecuentes en la Documentación para
ayuda y referencia del traductor.</para>
<para> Páginas man: El Proyecto de Documentación de
&os; también se encarga de desarrollar, mantener y
corregir las páginas <literal>man</literal> 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.</para>
<para><quote>Scripts</quote> <filename>accent2xml</filename> y
<filename>xml2accent</filename>. Existen dos <quote>scripts</quote>
que traducen los caracteres que no existen en inglés a
código sgml; por ejemplo <literal><![CDATA[á]]></literal>
a <quote><literal>á</literal></quote>, <![CDATA[?]]>
a <quote><literal>?</literal></quote>, 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.</para>
</sect1>
<sect1>
<title>Cómo formar parte del FPD-es</title>
<para>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 &a.es.doc;. 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.</para>
<sect2>
<title>Asignación de trabajos</title>
<para>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:</para>
<itemizedlist>
<listitem>
<para>la persona interesada en traducir elige un texto que desea
traducir y dos alternativas por si su primera elección ya
está asignada</para>
</listitem>
<listitem>
<para>el coordinador de traducciones le asigna el texto</para>
</listitem>
<listitem>
<para>el texto traducido es revisado e incluído en el
repositorio del FDP-es primero y en el del FDP
después.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Si puede dedicar un poco de tiempo</title>
<para>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 <ulink
url="http://www.theorem.ca/~mvcorks/code/charsets/latin1.html">http://www.theorem.ca/~mvcorks/code/charsets/latin1.html</ulink>
o utilice el <quote>script</quote> perl <filename>
accent2sgml.pl</filename> ubicado en <filename>
doc/share/examples/vim/</filename>. 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.</para>
</sect2>
<sect2>
<title>Con un poco más de tiempo</title>
<para>La forma ideal de entrega de trabajos al FDP-es es enviarlos
listos para incluir en el árbol cvs de &os;. Si tiene un
especial interés en un texto en concreto puede encargarse
de su mantenimiento (es lo que llamamos <quote>apadrinar</quote>
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
<emphasis>al dia</emphasis>;-)</para>
</sect2>
<sect2>
<title>Colaboración esporádica</title>
<para>En la &a.es.doc; 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.</para>
</sect2>
<sect2>
<title>?Todo el mundo puede traducir?</title>
<para>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 &a.es.doc;.</para>
<para>La documentación de &os; 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 <emphasis>exigir</emphasis> a los
recién llegados a &os; que lean la documentación
relacionada con sus dudas <emphasis>antes</emphasis> 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 &a.es.doc; que incluir información errónea en un
texto.</para>
<para>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 &os;,
<footnote>
<para>También puede traducir desde alguno de los idiomas en
los que hay documentación de &os;. Puede echar un
vistazo a los textos traducidos a distintas lenguas en <ulink
url="http://www.es.FreeBSD.org/doc/">http://www.es.FreeBSD.org/doc/</ulink>.</para>
</footnote>
y por supuesto sólidos conocimientos de castellano. Dicho
de otro modo, no es imprescindible <emphasis>hablar</emphasis>
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
<footnote>
<para> es decir, lo que podemos subir al cvs para que cualquiera
pueda verlo repartido por los sitios web de &os; del mundo
entero</para>
</footnote>
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
<footnote>
<para>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 <quote>traducciones</quote> abominables y
además cobrar por ello. Nosotros no pagamos, pero somos
mucho más estrictos.</para>
</footnote>
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
<footnote>
<para>es posible que el revisor le devuelva el texto si las
modificaciones que hay que hacer son muchas y usted mismo puede
hacerlas)</para>
</footnote>.</para>
</sect2>
</sect1>
<sect1>
<title>Guía de estilo</title>
<para>Esta sección están basada en la sección
<quote>writing style</quote> del libro <quote>fdp-primer</quote> que
puede consultarse en (<ulink
url="http://www.es.FreeBSD.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style.html"></ulink>).</para>
<para>Es necesario intentar mantener la consistencia entre la multitud de
autores que trabajan en la Documentación de &os;, 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.</para>
<itemizedlist>
<title>Idioma</title>
<listitem>
<para>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 &os; el idioma oficial es el inglés de los
Estados Unidos de América (en_US). Se intenta evitar el uso
de palabras <quote>agresivas</quote> con otros castellanoparlantes
como <literal>ordenador</literal> (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.</para>
</listitem>
<listitem>
<para>Evite frases redundantes</para>
<!-- <itemizedlist> -->
<para>Intente evitar usar frases redundantes. Por ejemplo
<quote>el comando</quote>, <quote>el fichero</quote> y
<quote>man comando</quote> probablemente son redundantes.</para>
<para>He aquí dos ejemplos en el caso de los comandos. El
segundo ejemplo mostrado es el recomendable.</para>
</listitem>
<listitem>
<informalexample>
<para>Utilice el comando <command>cvsup</command> para actualizar
sus fuentes</para>
</informalexample>
</listitem>
<listitem>
<informalexample>
<para>Utilice <command>cvsup</command> para actualizar sus
fuentes</para>
</informalexample>
</listitem>
</itemizedlist>
<para>Veamos dos ejemplos para nombres de ficheros. Recomendamos
el uso del segundo ejemplo.</para>
<informalexample>
<para>… en el fichero llamado
<filename>/etc/rc.local</filename>…</para>
</informalexample>
<informalexample>
<para>… en
<filename>/etc/rc.local</filename>…</para>
</informalexample>
<para>Veamos un ejemplo sobre páginas man. Recomendamos el
uso del segundo caso, que usa <sgmltag>citerefentry</sgmltag>.</para>
<informalexample>
<para>Para más información consulte
<command>man csh</command>.</para>
</informalexample>
<informalexample>
<para>Consulte &man.csh.1;</para>
</informalexample>
<variablelist>
<varlistentry>
<term>Dos espacios al final de cada frase</term>
<listitem>
<para>Deje siempre dos espacios al final de cada frase.
El texto será más legible y se facilita el
uso de herramientas como <application>Emacs</application>.</para>
<para>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.
<quote>Jordan K. Hubbard</quote> es un buen ejemplo de ello.
Tiene una <literal>H</literal> mayúscula tras un punto
y un espacio y es evidente que no es una nueva frase.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="sintaxis">
<title>Guía de sintaxis</title>
<para>Por favor, siga éstas sencillas reglas para facilitar el
trabajo de toda la gente que mantiene el código fuente de la
documentación.</para>
<sect2>
<title>Minúsculas</title>
<para>Las etiquetas van siempre en minúsculas:
<literal><para></literal>, <emphasis>no</emphasis>
<literal><PARA></literal>.</para>
<para>El texto SGML normalmente se escribe en mayúsculas:
<literal><!ENTITY…></literal> y
<literal><!DOCTYPE…></literal>,
<emphasis>no</emphasis>
<literal><!entity…></literal> o
<literal><!doctype…></literal>.</para>
</sect2>
<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>
<para>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.</para>
<para>Por ejemplo, el código fuente de esta sección
es algo parecido a esto:</para>
<programlisting><![CDATA[+--- É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>]]></programlisting>
<para>Si usa <application>Emacs</application> o
<application>XEmacs</application> para editar ficheros
que forman parte de la Documentación se cargará
automáticamente el <literal>sgml-mode</literal> y las
variables locales que <application>Emacs</application>
encontrará al principio de cada fichero podrán
utilizarse.</para>
<para>Si usa <application>Vim</application> puede serle muy
útil incluir lo siguiente en la configuración
de su editor:</para>
<programlisting>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</programlisting>
</sect2>
<sect2>
<title>Etiquetas</title>
<sect3>
<title>Espacios en las etiquetas</title>
<para>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 <emphasis>no</emphasis>:</para>
<informalexample>
<programlisting><![CDATA[<article lang='es'>
<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>]]></programlisting>
</informalexample>
</sect3>
</sect2>
</sect1>
<sect1>
<title>Trato al lector o lectora</title>
<para> 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.</para>
</sect1>
<sect1>
<title>Léxico</title>
<para> 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 <quote>por no haber viajado
suficiente</quote>.</para>
</sect1>
<sect1>
<title>Ayuda</title>
<sect2>
<title>Lista doc@es.FreeBSD.org</title>
<para>La &a.es.doc; es el lugar ideal para enviar:</para>
<para>dudas de traducción</para>
<para>ideas, sugerencias, críticas sobre la
documentación (en castellano o relacionadas con
la Documentación en inglés)</para>
<para>errores en la generación de documentación</para>
</sect2>
<sect2>
<title>Diccionarios en Internet</title>
<para>Existen muchos diccionarios en Internet y en bastantes de
ellos podemos consultar términos
<emphasis>gratuitamente</emphasis>. Las palabras más
técnicas y muchas exclusivas de &os; 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 &a.es.doc;.</para>
</sect2>
</sect1>
<sect1>
<title>Envío de traducciones</title>
<orderedlist>
<listitem>
<para>Por correo electrónico al coordinador, o bien</para>
</listitem>
<listitem>
<para>si lo considera conveniente, enviarlo a la &a.es.doc; para
su revisión.</para>
</listitem>
<listitem>
<para>&man.send-pr.1;</para>
</listitem>
</orderedlist>
</sect1>
<sect1 id="voluntarios-fdp-es">
<title>Voluntarios del FDP-es</title>
<para>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.</para>
<para>(en orden alfabético por apellido):</para>
<itemizedlist>
<listitem>
<para>&a.es.baz;</para>
</listitem>
<listitem>
<para>&a.es.carvay;</para>
</listitem>
<listitem>
<para>&a.es.cronopio;</para>
</listitem>
<listitem>
<para>&a.es.jcamou;</para>
</listitem>
<listitem>
<para>&a.jesusr;</para>
</listitem>
<listitem>
<para>&a.es.jrh;</para>
</listitem>
<listitem>
<para>&a.es.quique;</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Agradecimientos</title>
<para>A la &a.es.doc; por su <emphasis>infinita</emphasis>
paciencia durante las revisiones de este documento (y
desde mucho antes) y a &a.jesusr; por lo mismo y
además por animarme. Que tiene delito.</para>
</sect1>
</article>