:lang: en
:toc:

= LÉAME para autores de documentos

== Agregar archivos

Para agregar un archivo a los documentos, se deben actualizar
Submakefile, docs.xml e index.tmpl.

The relevant pdf.adoc must be updated to include the new document in the
pdf documentation. e.g. if a new document belongs in the Master
Documentation then an entry is required in src/Master_Documentation.adoc

docs.xml se usa para crear los botones "anterior" y "siguiente" en la
parte superior de cada documento html individual.
En general, los documentos debe coincidir con el orden de index.tmpl

== Notas sobre la documentación de LinuxCNC

El archivo makefile principal de LinuxCNC puede construir opcionalmente
la documentación y otros archivos en este árbol de directorios.
Utilice --enable-build-documentation cuando invoque src/configure, y
ejecute make desde ../src

== Notas sobre los dibujos

-N.T. Muchos de los inconvenientes que aqui se comentan estan superados
en las versiones actuales de los correspondientes programas.
N.T.- Muchos de los documentos incluyen dibujos. La mayoría de ellos
fueron creados originalmente con EasyCad, una aplicación de Windows no
gratuita, y luego exportados a archivos .eps e incluido en los
documentos. Los archivos originales 'fuente' (formato EasyCad .FC7) no
se podían usar en un sistema gratuito. Para solucionar este problema,
todos los archivos fuente se han convertido a archivos .dxf y se han
agregado a git.
Los archivos .dxf pueden editarse con diferentes paquetes CAD y servir
como archivos 'fuente' para futuros cambios en los dibujos. Se pueden
convertir de .dxf a postscript (no .eps) usando Qcad, que está
disponible como paquete ubuntu (y creo que también está disponible para
debian).

Desafortunadamente, EasyCad (y AutoCad) admiten varias entidades
que Qcad no importa correctamente, incluyendo algunos que fueron
utilizados en los dibujos de LinuxCNC; círculos rellenos, puntas de
flecha rellenas, líneas de ancho no nulos y líneas discontinuas. Qcad
representa círculos rellenos como huecos, hace que todas las líneas
tengan el mismo ancho, y se hace lineas de puntos como sólidas, a menos
que le diga que haga lo contrario. Todos estas cosas hacen que los
dibujos sean menos atractivos, pero son aceptables. Sin embargo, Qcad no
importa puntas de flecha rellenas en absoluto, lo que daña seriamente
los dibujos. Así que se usó EasyCad para convertir las puntas de flecha
a huecas antes de exportarlas. Las puntas de flecha huecas no se ven tan
bonitas como las sólidas, pero al menos son visibles.

Una vez exportadas, las puntas de flecha pierden su relación con la
línea correspondiente y deben moverse y/o girarse manualmente si la
línea se ha movido. Creo que incluso si fueran importados de nuevo a
EasyCad, la conexión línea/flecha permanecería rota. Nuevas líneas con
las puntas de flecha se pueden crear en Qcad con la herramienta de
dimensión 'líder'.

Debido a que los archivos EPS originales con líneas llenas y círculos,
líneas anchas, y las líneas punteadas se ven mucho mejor, permanecerán
en git y probablemente deberían usarse para los documentos. Sin embargo,
si se vuelven inexactos debido a cambios en el software, tendremos que
editar los archivos DXF, generar postscript, y usar imágenes menos
bonitas pero correctas.

Dado que Qcad en sí es una aplicación GUI, la conversión dxf a postscript
implica hacer clicks en ventanas, y no se puede automatizar y formar
parte de makefile. Además, no todos tendrán Qcad instalado en su sistema.
Por lo tanto, almacenaremos los archivos DXF y los archivos postscript
resultante en git, y el proceso normal de creación de documentación usará
archivos postscript solamente. La edicion de archivos dxf necesitará
la conversion manual a PostScript. El procedimiento de conversión es como
sigue:

- Comenzar QCAD
- Archivo -> Abrir-> Elegir archivo dxf (el dibujo aparece en la ventana)
- Editar -> Current Drawing Preferences -> Paper +
  Establecer:
  * el tamaño del papel a "carta",
  * la orientación a "paisaje" o "retrato", dependiendo de la relación
    de aspecto del dibujo.
- Archivo -> Vista Previa Impresion +
  Haga clic en el botón "Ajustar a la página" en la barra de herramientas
  (último botón a la derecha - en menos en la versión 2.0.4.0 de QCAD)
- Archivo -> Imprimir
  * Seleccionar "Imprimir en archivo"
  * Establecer la ruta para que apunte al mismo directorio que el
    archivo .dxf fuente
  * Establecer el nombre como el mismo que el archivo de origen,
    pero .ps en lugar de .dxf
  * haga clic en Aceptar

Los fabricantes de Qcad también tienen un convertidor de formato GPL
llamado vec2web, que puede hacer la conversión dxf a postscript desde la
línea de comando. Esto no está disponible como un paquete precompilado,
pero está disponible en http://www.ribbonsoft.com/vec2web.html

vec2web depende de los paquetes de desarrollo qt3 para la compilación,
por lo que no debería ser una dependencia para construir los documentos
de LinuxCNC. Pero si configure puede detectarlo, sería bueno automatizar
la conversión de dxf a ps para aquellos sistemas donde está instalado
vec2web.

Para construir vec2web, ejecutar apt-get install qt3-dev-tools
El archivo tar de vec2web contiene un script de compilación, pero antes
de ejecutarlo debe configurar $QTDIR para que apunte a la instalación de
QT3; en mi caso fue:

```
export QTDIR=/usr/share/qt3
```

A continuación, ejecutar el script de compilación:

```
./build_vec2web.sh
```

No hay un paso de instalación, el ejecutable se descarga en el directorio
de compilación.
Tampoco hay una página man, pero al ejecutarla sin argumentos imprime
las siguiente instrucciones de uso:

```
Uso: vec2web <archivo de entrada> <archivo de salida> [opciones]
Donde las opciones son:
        -x # 	tamaño x máximo para el mapa de bits de salida en píxeles
        -y # 	tamaño máximo y para el mapa de bits de salida en píxeles
        -b 	negro/blanco en lugar de usar colores
        -o [l|p]orientación para salida PS (horizontal o vertical)
        -s ..	tamaño de página para salida PS (A4, A5)

p.ej. vec2web drawing.dxf drawing.png
        convierte drawing.dxf en un gráfico .png
```

Mis intentos iniciales de usar vec2web dieron como resultado la
conversion de las partes gráficas del dibujo, pero todo el texto se
perdió. No sé si vale la pena pasar mucho más tiempo con vec2web, sin
embargo, es GPL e incluye una biblioteca para leer archivos DXF que
podría ser una cosa que vale la pena a la comunidad LinuxCNC.

=== Dibujos de QCad

 - Guardar como .dxf en el mismo directorio que la imagen
 - Establecer grosor de línea a 0.50 mm
 - Exportar imagen con resolución 480 x 480 Auto .png

== Dealing with translations

Translation of our documentation is in transition at the moment.

We have some old-style translations that are separate asciidoc .adoc
files checked into git. These started out as copies of the english
master docs at some point, and diverged from there over time.  This
turned out not to be an ideal situation.

We are experimenting with a new system using
https://po4a.alioth.debian.org/[po4a]. With po4a, the English text
is the master document, and each paragraph is translated using
gettext, just like the strings in our software.

Some documentation of po4a is available in the
https://po4a.alioth.debian.org/man/man7/po4a.7.php[po4a(7)] manpage.

We are using po4a version 0.62, available in Debian Bullseye.

=== To transition a translated file to po4a

If there is a pre-existing translation of the file to your language,
create a .po translation database seeded by the old translation.

If the english file is called "file.adoc" then the old pre-existing
translated file is probably called "file_fr.adoc" (for the french
translation, as an example), and the translation database should be
called "file.fr.po". Creating PO file from adoc can be done by running
this command:

```
(f=getting-linuxcnc; l=cn; po4a-gettextize \
  > --format asciidoc \
  > -m ${f}.adoc -M utf8 \
  > -l ${f}_${l}.adoc -L utf8 \
  > -p ${f}.${l}.po)
```

Similarly, for translated manual pages:

```
(f=elbpcom.1; l=es; po4a-gettextize \
  > --format asciidoc \
  > -m man/man1/${f} -M utf8 \
  > -l man/${l}/man1/${f} -L utf8 \
  -p ${f}.${l}.po)
```

To append the extracted translations to the combined PO file, do
something like this:

```
msgcat --use-first po/documentation.es.po \
  > elbpcom.1.es.po \
  > po/documentation.es.po
```

=== To create a new po4a translation of an untranslated file

If there is no pre-existing translation of the file to your language,
create an empty .po file to start with.  If the english file is called
"file.adoc" then the translation database should be called "file.se.po"
(for the swedish translation, as an example).  It is created by running
this command:

```
po4a-gettextize --format text \
  > -m file.adoc -M utf8 \
  > -p file.se.po
```

=== Improving the translation of a po4a-managed file

Translations are done paragraph by paragraph.

You can use a GUI tool like Poedit or Gtranslator or others, or you can
(carefully!) edit the .po file by hand.

The next time the translated document gets rebuilt, the updated
translations will be used.

=== When the master document (english) changes

When the master document (english) file has changed, use the
po4a-updatepo to update the .po files:

```
po4a-updatepo -f text \
  > -m file.adoc \
  > -p file.fr.po
```

=== Cómo agregar un nuevo idioma de traducción

Determine the ISO 639-1 code for your new language (for example:
English -> "en", Vietnamese -> "vi", etc).  This becomes the "NEWLANG"
variable in the examples below.  There is a list of codes here:
<https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>

Agregue los archivos de origen asciidoc que contendrán su nueva
traducción. Por lo general, eso significa copiar los archivos de idioma
de uno de los idiomas existentes, probablemente inglés ya que suele ser
el más actualizado.

Copy the docs/po/documentation.pot to docs/po/documentation.$LANG.po.
where $LANG is a two letter language code according to ISO 639-1, or
three letter code according to ISO 639-2 if no two letter code exist.
Add the new language code to the proper place in docs/po4a.conf.

Agregue los archivos nuevos al lugar correcto en `docs/src/Submakefile`,
para asegurar que se construirán.

Edite debian/control.in para agregar el nuevo paquete
linuxcnc-doc-$NEWLANG.
Agregue el nuevo paquete de documentos a la lista "or" de la línea
"Recommends" del paquete linuxcnc principal.
N.T. Actualmente, control.in esta dividido en control.top.in y
control.bottom.in, siendo este ultimo el que contiene los parrafos
Package:

Agregue el nuevo idioma a la lista en la variable DOCS_PACKAGES en
debian/configure.

Si hay un paquete texlive-lang-$NEWLANGUAGE para su nuevo idioma,
agréguelo a todas las líneas EXTRA_BUILD apropiadas en debian/configure.
N.T La variable que contiene los texlive-lang-$NEWLANGUAGE es
DOC_DEPENDS.

Agregue el archivo 'linuxcnc-doc-$NEWLANG.files.in' al nuevo paquete,
probablemente copiando y editando "debian/linuxcnc-doc-en.files.in".

¡Pruebe a construir los paquetes y verifiquelos!

// vim: set syntax=asciidoc:
