: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 [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: 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: