Este documento contiene las siguientes secciones:

  Pasos para poder compilar el libro
  Cómo colaborar con la traducción
  Obteniendo acceso de escritura al repositorio
  Cambios futuros que se realizarán en el libro
  Herramientas para ayudar en la traducción
  Reglas mínimas para todos los traductores
  Reglas mínimas para traductores con acceso de escritura
  Traducción de la web del libro
  Corrección ortográfica con aspell
  Lista de correo para discutir la traducción


Pasos para poder compilar el libro:
===================================

1. Obtener una copia fresca del libro en español. El libro está
   alojado en el repositorio principal de desarrollo de Subversion,
   en un subdirectorio del directorio asignado para las traducciones
   y las herramientas docbook que transforman el código fuente XML
   en HTML y PDF. Primero hay que obtener el código fuente:

      svn co http://svn.red-bean.com/svnbook/trunk/src svnbook

   Una vez obtenida la copia, nuestro trabajo estará en el directorio
   "svnbook/es", sobre la cual se puede trabajar. El resto de
   las instrucciones asumen que trabaja con un entorno tipo Unix
   (por ejemplo, Cygwin bajo Windows) y tiene GNU Make instalado,
   alguna shell como bash y un intérprete de Python.

2. Obtener las hojas de estilo XSL para Docbook y ponerlas en el
   subdirectorio tools/xsl. Si su distribución de GNU/Linux ya
   tiene instalado un paquete de hojas de estilo, es posible que
   pueda saltarse este paso. Entre en el directorio "svnbook/es"
   y teclee "make".  Si le faltan las hojas de estilo, obtendrá un
   error similar a:

      ERROR: Failed to find a DocBook XSL directory

   El "Docbook Open Repository" en Sourceforge tiene una
   larga colección de hojas de estilo XSL que funcionan con
   Docbook. Descargue e instale el paquete 'docbook-xsl-X.YY.Z'
   de la siguiente página, donde X, YY y Z son números de versión:
  
      http://sourceforge.net/project/showfiles.php?group_id=21935

   Tras descargar la última versión de docbook-xsl, descomprima el
   fichero, y renombre/mueva el directorio descomprimido a tools/xsl,
   algo como esto:

      $ cd svnbook/tools
      $ tar zxvf docbook-xsl-X.YY.Z.tar.gz
      $ mv docbook-xsl-X.YY.Z xsl

   Este proceso es importante porque el proceso de
   compilación del libro espera que las hojas de estilo estén
   alojadas en "svnbook/tools/xsl/" si el script en Python
   "svnbook/tools/bin/find-xsl.py" no es capaz de encontrar las
   hojas de estilo instaladas en su sistema.

3. Usar XSLT para transformar el libro

   XSLT aplica una hoja de estilo .xsl sobre un fichero .xml,
   y produce un nuevo documento.

   * Obtenga libxslt, una librería en C para XSLT, desde
     http://xmlsoft.org/XSLT/.  (Si se encuentra con problemas
     para encontrar un paquete de código fuente compilable, pruebe
     en ftp://archive.progeny.com/GNOME/sources/libxslt/1.0/.)
     Instalación:

        $ tar zxvf libxslt-1.0.22.tar.gz
        $ cd libxslt-1.0.22
        $ ./configure
        $ ./make
        # make install

     (Nota: quizás descubra que necesita
     instalar antes libxml2. Puede encontrarlo en
     ftp://archive.progeny.com/GNOME/sources/libxml2/)

     Si no desea compilar libxslt a mano, puede optar por descargar
     el paquete binario apropiado para su SO. Por ejemplo, en Debian
     puede instalar el paquete libxslt directamente y ahorrarse
     este paso.

4. Ejecutar "make" desde el directorio "es". Obviamente
   necesitaremos tener GNU make instalado. Si todo el software
   necesario está instalado, acabaremos con un libro en un sólo
   html en book/svn-book.html, y otro dividido en trozos en
   book/html-chunk/index.html.

5. Opcionalmente, colaborar con el proyecto traduciendo ficheros
   .xml o revisando el libro generado y enviando cualquier comentario
   a la lista de correo de traducción de Subversion (información
   sobre esto al final de este documento).

Para cualquier duda, contactar con la lista de correo encargada de
coordinar la traducción.


Cómo colaborar con la traducción
================================

En este momento no hay definido coordinador del proyecto de traducción.
No obstante puede enviar un mensaje a la lista de correo disponible
para darse a conocer y ofrecerse voluntario (ver sección "Lista de
correo para discutir la traducción").  Se puede colaborar traduciendo
el libro o revisando las traducciones realizadas. En ambos casos,
cualquier colaboración por mínima que sea será anotada en un listado
de contribuciones.

Antes de colaborar alguna traducción, hay que entender que
esta traducción se realiza bajo la misma licencia que el libro
original, es decir, la Creative Commons Attribution License
(http://svnbook.red-bean.com/svnbook-1.0/ape.html). Se entiende que
cualquier traducción se ofrece al proyecto bajo esta licencia. No
se aceptarán traducciones bajo otras licencias.

El repositorio de la traducción está disponible en modo sólo
lectura.  La sección "Pasos para poder compilar el libro" indica
cómo obtenerlo.  Para traducir conviene contactar con el coordinador
para que este diga qué secciones están siendo traducidas por qué
personas. Para evitar duplicar esfuerzos a cada persona se le
asignaría un capítulo. Si hay más personas que capítulos, varias
traducirán el mismo, requiriendo la comunicación de ambas partes
para no pisarse trabajo. El listado de quién hace qué cosa se lleva
en el fichero TRABAJO. Aquellos que quieran traducir un fichero
sin acceso de escritura al repositorio, deben indicar en la lista
de correo de forma explícita qué fichero están traduciendo. De lo
contrario este fichero podría ser asignado por error a otra persona.

Cuando un traductor comienza con un capítulo, se entiende que el
trabajo puede llevar bastante tiempo hasta ser completado. Pero
si un traductor no "genera" ningún cambio en la traducción en
14 días, el trozo que se le había asignado quedará libre para
otros traductores. Se pretende evitar así el estancamiento de
la traducción. Por esta razón se recomienda la traducción de una
sección <para></para> por día, para evitar saturarse. Mejor cambios
pequeños frecuentes que ningún cambio.

No poder traducir algo en esos 14 es algo que puede pasar, la vida
es así. No cumplir estos plazos no acarrea ningún perjuicio para
el traductor. La política de acceso de escritura al repositorio
de Subversion es permisiva, así que una vez obtenido el acceso de
escritura ya nunca lo cancelan.

El trabajo de revisión normalmente no se hará de forma global hasta
que al menos un capítulo esté completo. No obstante, si leyendo algo
se encuentra alguna falta ortográfica o gramatical, se agradecerán
las sugerencias o parches realizados contra el servidor público
(resultado del comando svn diff). Un capítulo se considerará
revisado cuando al menos una persona que no haya colaborado en
su traducción lo haya leído sin encontrar fallos. Por supuesto,
cuantas más personas realicen esta tarea mejor.

Conviene recordar que hay dos tipos de revisión: el primer tipo
consiste en leer un capítulo traducido y ver si "suena" bien al ser
leído. El segundo tipo consiste en leer frase a frase el original
en inglés, verificando que la traducción ha sido realizada con la
mayor fidelidad. El primer tipo de revisión es el más sencillo,
pero para validar el libro habrá que realizar ambos tipos al menos
una vez por una o dos personas como mínimo.

Al finalizar la traducción completa se volverá a realizar una
revisión global. Tras ésta, se considerará actualizar la traducción
a la versión actual del libro original, pues la traducción se realiza
sobre una versión específica que con seguridad quedará obsoleta.


Obteniendo acceso de escritura al repositorio
=============================================

En la sección anterior se ha mencionado que el repositorio está en
modo lectura (de hecho se puede ver vía navegador web a través de
http://svn.red-bean.com/svnbook/trunk/src/es).  Esto es aceptable
para hacer trabajos de revisión, cuando lo único importante es
tener acceso a la última versión y poder compilar el libro para
leerlo en su forma final.

Para traducir texto, se puede mandar parches diferenciales a la
lista de correo de la traducción, o se puede obtener acceso directo
de escritura al repositorio.

En el primero de los casos, los parches conviene generarlos
capturando la salida del comando "svn diff" ejecutado en el
directorio raíz de la traducción. Ejemplo:

   [~/project/svnbook/es]$ svn diff > cambios.diff

Si el parche diferencial ocupa bastante (más de 10KB), conviene
comprimirlo, preferiblemente con gzip:

   [~/project/svnbook/es]$ gzip cambios.diff

Una vez generado el parche se envía a la lista de correo y se espera
a que alguien con acceso de escritura lo incluya en el repositorio.

El segundo caso (acceso con escritura al repositorio) consiste
en estar de acuerdo con las reglas enumeradas en "Reglas mínimas
para traductores" (se pueden negociar) y crearse una cuenta en el
servidor http://www.tigris.org/.  Esta cuenta es similar a la que
se puede obtener en servicios como http://www.sourceforge.net/ o
http://developer.berlios.de. El nombre o alias que usemos en esta
cuenta será el que figurará en los informes de cambios que genera
el repositorio cuando se envían cambios.

Una vez creada esta cuenta, mandar un mensaje a la
lista de la traducción indicando el nombre de usuario de
tigris.org. Un coordinador de la traducción mandará un email
a los responsables del repositorio indicando la aprobación de
ese nombre de usuario. Simultáneamente, quien solicita acceso de
escritura tendrá que mandar a los administradores del repositorio
(svnadmin@svn.collab.net) un mensaje indicando el nombre de usuario
que tiene en tigris.org y la palabra clave que desea usar para
modificar el repositorio.

Cuando los responsables del repositorio hayan recibido ambos
mensajes, le indicarán si su acceso es aprobado. Con esto,
simplemente cambiar un fichero en la copia local que tenemos de
la documentación, y al hacer "svn commit" introducir el nombre de
usuario de tigris.org y la clave de acceso de escritura.


Cambios futuros que se realizarán en el libro
=============================================

La licencia del original permite modificarlo. Esto se usará para
añadir un capítulo adicional al libro (o quizás un apéndice) en
el que se especifique cómo se ha realizado la traducción, quienes
han colaborado, el estado actual, lista de palabras que no tiene
traducción directa, etc, etc. Aparte de este capítulo, se preservará
el contenido del resto del libro tal y como está en el original.


Herramientas para ayudar en la traducción
=========================================

Glosario de informática Inglés-Español:
http://es.tldp.org/ORCA/glosario.html más información en
http://quark.fe.up.pt/orca/index.es.html?.

Cómo traducción:
http://libertonia.escomposlinux.org/story/2004/6/4/12518/28489

Cómo traducción wiki (¿es el mismo que arriba?):
http://wiki.escomposlinux.org/bin/view/Escomposlinux/ComoTraduccion

Diccionario online de la RAE:
http://buscon.rae.es/diccionario/cabecera.htm

Traductor de Google:
http://www.google.es/language_tools?hl=es

Artículo sobre malas traducciones, que es la razón por la que al
menos deberían hacerse revisiones por varias personas diferentes:
http://www.javiermarias.es/PAGINASARTICULOSSEMANAL/secolapsarontributos.html

Traducciones de expresiones en varios lenguajes:
http://www.proz.com/kudoz?pairs=&level=

Manual de CVS en español:
http://es.tldp.org/htmls/manuales.html
Es buena idea leerse esto en busca de términos y traducciones. Al
fin y al cabo, estaría bien tener una continuidad en la traducción
de los términos.

Por último, sentido común. Si hay alguna duda sobre un trozo
traducido, a veces viene bien cerrar los ojos y recitar las frases
una y otra vez en voz alta. A veces oír las palabras escritas
es el mejor método para saber si están bien traducidas, pues
deben reflejar lo que una persona humana le diría a otra en una
conversación natural. Si algo le suena "raro", márquelo como un
TODO para revisar/discutir en el futuro.


Reglas mínimas para todos los traductores
=========================================

Las siguientes reglas deben ser cumplidas tanto por aquellos que
tienen acceso de escritura al servidor, como aquellos que no lo
tienen y envían parches a la lista de correo:

- Si se desea colaborar con la traducción de un fichero, hay que
  anunciarlo en la lista de correo para que éste se le asigne de
  forma oficial y así asegurar que otra persona no está traduciendo
  por su cuenta lo mismo.
  
- En el caso de colaborar mediante parches enviados a la lista de
  correo, puede acumular los cambios y enviar éstos semanalmente para
  evitar sobre cargarse con el uso del correo electrónico (si bien el
  coordinador aceptará cualquier colaboración por pequeña que sea).

- No usar tabuladores "duros". Usar espacios al salvar ficheros.

- Cuando se tiene duda sobre una traducción, traducir lo mejor
  que se considere y poner una etiqueta <!-- TODO explicación del
  problema --> dentro del propio texto. Así luego se puede hacer
  "grep TODO *" para ver qué falta.

- Por ahora ningún ejemplo de línea de comando o imagen será
  traducido. Dejar las cosas tal cual (ej: lo que viene dentro de
  las etiquetas screen o programlisting), excepto los nombres de
  usuario que serán traducidos según lo que se haya especificado
  en el glosario.

- A veces es necesario añadir una nota de traductor ya sea para
  indicar un uso inusual de una palabra o comando, explicar alguna
  traducción rebuscada, cosas así. El formato es:

    <footnote><para>N.T.: xxx.</para></footnote>.

  Da igual si se empotra todo en una línea o se formatea (si la
  nota es larga), eso queda a gusto del traductor. Hay un ejemplo
  al comienzo de ch00.xml.

- Recuerde que para obtener acceso de escritura no tiene más que
  pedirlo.

Reglas mínimas para traductores con acceso de escritura
=======================================================

Las siguientes reglas están orientadas a aquellos que tienen acceso
de escritura al servidor y trabajan de forma activa sobre algún
fichero en particular:

- Como cambio al repositorio se considera cualquier modificación
  por pequeña que sea a cualquier fichero del proyecto (incluyendo
  meta ficheros como TRABAJO o LEAME). No hay límite de tamaño
  (ya sea por pequeño o por grande) a la hora de enviar un cambio
  al repositorio.
  
- Estar apuntado a la lista de correo de cambios realizados
  en el repositorio: svnbook-dev@red-bean.com.
  Las instrucciones para apuntarse están en
  http://www.red-bean.com/mailman/listinfo/svnbook-dev/.

- Si se añade un fichero de texto al repositorio, indicar que
  los retornos de línea sean "nativos" y que la codificación es
  ISO-8859-1 (siempre y cuando sea esa, claro). Ejemplo:

     svn propset svn:eol-style native ruta_ficheros
     svn propset svn:mime-type "text/plain; charset=ISO-8859-1" ruta_ficheros

  Para más información sobre esto, leer capítulo 7 del libro. No se
  crea una regla auto-props porque añadir ficheros debería ser una
  tarea inusual al tener ya todos los documentos del libro original
  en el repositorio.

- Dado que las notas de traductor son contenido nuevo no existente
  en el libro, siempre que se añada una hay que publicar en la
  lista de correo en qué revisión se ha añadido la nota (no hace
  falta incluir el parche en el email) para recibir comentarios
  sobre la misma y si es necesario, modificarla.

- A la hora de enviar cambios al repositorio, el mensaje de log
  debe estar en inglés y comenzar con "Book Spanish.". Ejemplo:

    Book Spanish. Translated two paragraphs.

  Si se nos olvida, siempre se puede modificar el log de un cambio
  antiguo con el sub comando propset o propedit. Ejemplo:

    svn propedit svn:log -r113 --revprop

A medida que salgan cosas, ser irán poniendo aquí.


Traducción de la web del libro
==============================

La página web del libro está en http://svnbook.red-bean.com/. Se
considera deber de este proyecto traducir esa misma página y añadir
información actualizada sobre la traducción. Esto se puede ver en
http://svnbook.red-bean.com/index.es.html.  El coordinador debe
encargarse de la actualización de esta página.

La propia página web se controla a través del mismo repositorio
que almacena las traducciones del libro. Es decir, alguien que
tiene permiso de escritura al repositorio y colabora fragmentos
traducidos, puede igualmente modificar la web si es necesario. Para
ello, únicamente hay que cambiar la URL usada al comienzo de este
documento mediante la cual se obtenía el código fuente del libro
de Subversion:

  svn co http://svn.red-bean.com/svnbook/trunk/src svnbook

...cambia a...
      
  svn co http://svn.red-bean.com/svnbook/trunk/www/ websvnbook

Dentro de este directorio, sólo se debe modificar el fichero
index.es.html, ya que de los demás se encargan el resto de
traductores. A diferencia de los mensajes de informes de cambio
del libro, aquí se sigue otro formato. En la traducción basta con
prefijar cada mensaje con "Book Spanish. blah blah".

Aquí, en cambio, se usan las reglas de formato heredadas del
desarrollo del código fuente de Subversion.  Consisten en indicar
siempre en todos los mensajes qué ficheros han sido modificados,
y qué cambios afectan a cada uno. Aquí se puede ver un extracto de
los mensajes de cambios del fichero index.es.html:

 ------------------------------------------------------------------------
 r1854 | maxb | 2005-11-24 00:07:29 +0100 (jue, 24 nov 2005) | 5 lines
 
 * www/index.es.html: Add missing vertical bar.
 
 * www/index.it.html, www/index.ru.html, www/index.html.var:
   Add link to Chinese translation.
 
 ------------------------------------------------------------------------
 r1851 | gradha | 2005-11-22 21:10:44 +0100 (mar, 22 nov 2005) | 2 lines
 
 * www/index.es.html: Updated web page to match English revision 1850.
 
 ------------------------------------------------------------------------

Normalmente sólo hay que actualizar index.es.html (a no ser que
por ejemplo alguien descubra un fallo de HTML que afecte a todas
las páginas y desee realizar el cambio inmediatamente en lugar de
comunicándolo a la lista de correo). Para esto el procedimiento
es simple:

1. Se verifica con "svn log index.es.html" la última sincronización
   del fichero index.es.html respecto a la versión "maestra"
   index.en.html.

2. Usando como punto de referencia la última revisión, se procede
   a obtener los cambios de la versión inglesa (sustituir las X
   por el número de revisión):

      svn diff -rXXXX index.en.html

3. Modificar index.es.html y enviar los cambios al servidor,
   usando el formato de texto adecuado en la descripción del mensaje
   de cambios.

Si por alguna razón la traducción de la página queda desactualizada,
dar un tirón de orejas al coordinador. Si no responde, será que lo
han abducido, en cuyo caso hay que discutir en la lista de correo
quién de los restantes traductores puede actualizar la página,
posiblemente procediendo también a cambiar al coordinador del
proyecto.


Corrección ortográfica con aspell
=================================

El comando aspell en sistemas Unix permite realizar una corrección
ortográfica básica, útil para capturar esos pequeños descuidos que
acaban colándose de una forma u otra. Primero hay que instalar
el propio programa corrector y un diccionario en español. En
distribuciones Debian esto se puede hacer con un "apt-get aspell-bin
aspell-es". También es necesario el programa "make" para ejecutar
los scripts.

El mecanismo de verificación ortográfica sólo es útil una vez
se ha traducido un fichero por completo, dado que la herramienta
no es capaz de procesar documentos multilingües. Igualmente, el
diccionario básico no va a tener todos los términos informáticos
o palabras derivadas que son válidas, así que también muestra
"falsos positivos".

Primero hay que añadir el nombre base del fichero que queremos
traducir a la línea BOOK_ASPELL_FILES del fichero Makefile. Ahora
desde el directorio raíz del proyecto tecleamos en la línea de
comando "make aspell_check".  Este comando ejecutará aspell sobre
todos los ficheros de la variable BOOK_ASPELL_FILES. Los que ya
están verificados no tendrán fallos, así que como mucho veremos un
parpadeo de pantalla que indica que aspell comenzó la verificación
y salió sin encontrar ningún fallo.

Pero como acabamos de añadir un fichero nuevo, el proceso se
detendrá en cuanto llegue el turno del fichero que hemos añadido. La
interfaz de aspell es simple: muestra el texto en la pantalla
superior junto con la palabra que no está en su diccionario, y una
leyenda de opciones en la parte inferior de la pantalla. Pulsando
uno de los números sustituiremos la palabra resaltada por esa opción.

Así, lo único que tenemos que hacer es ir corrigiendo lo que esté
mal.  Para aquellas palabras que están bien, o que se han dejado
en inglés, hay que presionar la tecla I, que sirve para "Ignorar
todas". Tras finalizar la verificación completa, o pulsar x para
salir, un "svn diff" debería mostrar los cambios que acabamos de
hacer, y podemos enviar los cambios al repositorio para mantenerlos.

Pero si volvemos a ejecutar "make aspell_check", veremos que aspell
vuelve a pararse en las palabras que anteriormente ignoramos. Para
evitar esto, hay que ejecutar "make aspell_add_words". Este comando
revisa los ficheros y vuelca en fichero.xml.aspell_ignore la lista
de palabras que hemos ignorado. Esta lista de palabras es usada por
"make aspell_check" como diccionario adicional, y así evitamos que
vuelva a preguntar por palabras que queremos ignorar. Por supuesto,
los ficheros aspell_ignore hay que enviarlos al repositorio para
que otros traductores no tengan que volver a realizar este trabajo.

En resumen, se trata de un proceso algo laborioso, pero que merece la
pena porque es una primera línea de defensa contra fallos básicos.
En cualquier caso, esta verificación no es obligatoria para los
traductores. Si no se desea realizar o no se puede por falta de las
herramientas adecuadas, se puede pedir al coordinador que se encargue
de añadir el fichero traducido a la lista de ficheros verificados.


Lista de correo para discutir la traducción
===========================================

Hay una lista de correo habilitada para discutir la traducción
tanto del libro como de los mensajes .po de Subversion. Se puede
ver aquí:

 http://subversion.tigris.org/servlets/SummarizeList?listName=l10n-es

Para apuntarse, enviar un email a
l10n-es-subscribe@subversion.tigris.org y esperar respuesta con
instrucciones. Para desapuntarse, realizar el mismo proceso con la
dirección l10n-es-unsubscribe@subversion.tigris.org.

A diferencia de las listas de usuarios y desarrollo de Subversion,
esta lista de correo incluye la cabecera:

  Reply-To: l10n-es@subversion.tigris.org
  
Así que cualquier cliente de correo decente debería responder a la
lista y evitar mandar mensajes duplicados al autor y a la lista
(práctica habitual en las listas de Subversion). También incluye
la cabecera:

  List-Post: <mailto:l10n-es@subversion.tigris.org>

La cual resulta útil para filtrar el correo en otra carpeta. A
diferencia de las listas de correo que usan la interfaz web Mailman
para ser gestionadas, esta lista de correo se maneja totalmente
a través de email. Para obtener una lista de los comandos que se
pueden realizar y cómo, enviar un email a la siguiente dirección:

  l10n-es-help@subversion.tigris.org