Merge branch 'LinuxCNC:master' into master

.github/workflows/ci.yml

@@ -24,10 +24,11 @@ jobs:
     - name: Build RIP & test
       run: |
         ./scripts/travis-install-build-deps.sh
+        sudo apt-get install -y eatmydata
         cd src
-        ./autogen.sh
-        ./configure --with-realtime=uspace --disable-check-runtime-deps
-        make -O -j$((1+$(nproc))) default pycheck V=1
+        eatmydata ./autogen.sh
+        eatmydata ./configure --with-realtime=uspace --disable-check-runtime-deps
+        eatmydata make -O -j$((1+$(nproc))) default pycheck V=1
         # Note that the package build covers html docs
         ../scripts/rip-environment runtests -p
     
@@ -46,10 +47,11 @@ jobs:
     - name: Build HTML docmentation
       run: |
         ./scripts/travis-install-build-deps.sh
+        sudo apt-get install -y eatmydata
         cd src
-        ./autogen.sh
-        ./configure --with-realtime=uspace --disable-check-runtime-deps --enable-build-documentation=html
-        make -O -j$((1+$(nproc))) docs
+        eatmydata ./autogen.sh
+        eatmydata ./configure --with-realtime=uspace --disable-check-runtime-deps --enable-build-documentation=html
+        eatmydata make -O -j$((1+$(nproc))) docs
         # Note that the package build covers html docs
 
   package:
@@ -68,9 +70,10 @@ jobs:
         set -x
         git fetch --recurse-submodules=no https://github.com/linuxcnc/linuxcnc refs/tags/*:refs/tags/*
         ./scripts/travis-install-build-deps.sh
+        sudo apt-get install -y eatmydata
         codename=$(grep VERSION_CODENAME /etc/os-release | cut -d = -f 2)
         dch --maintmaint --distribution $codename "GitHub test package."
         fakeroot ./debian/rules binary
         sudo apt-get install ../*.deb
-        ./scripts/runtests -p tests/
-        lintian --info --display-info --pedantic --display-experimental ../*.deb
+        eatmydata ./scripts/runtests -p tests/
+        eatmydata lintian --info --display-info --pedantic --display-experimental ../*.deb

debian/copyright

@@ -484,7 +484,7 @@ License: LGPL-2
  with this program. If not, see <https://www.gnu.org/licenses/>
  .
  On Debian systems, the complete text of the GNU Lesser General Public
- License version 2.1 can be found in ‘/usr/share/common-licenses/LGPL-2’.
+ License version 2.1 can be found in '/usr/share/common-licenses/LGPL-2'.
 
 License: LGPL-2.1+
  This program is free software; you can redistribute it and/or modify
@@ -501,7 +501,7 @@ License: LGPL-2.1+
  with this program. If not, see <https://www.gnu.org/licenses/>
  .
  On Debian systems, the complete text of the GNU Lesser General Public
- License version 2.1 can be found in ‘/usr/share/common-licenses/LGPL-2.1’.
+ License version 2.1 can be found in '/usr/share/common-licenses/LGPL-2.1'.
 
 License: MIT
  Permission is hereby granted, free of charge, to any person obtaining a copy

docs/README.adoc

@@ -122,6 +122,87 @@ Drawings from QCAD
  - Export the  image as 480 x 480 Resolution 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
+[po4a](https://po4a.alioth.debian.org/).  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 po4a(7) manpage, and
+online here:
+
+    https://po4a.alioth.debian.org/man/man7/po4a.7.php
+
+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
+
+
 How to add a new translation language
 -------------------------------------
 
@@ -134,8 +215,10 @@ Add the asciidoc source files containing your new translation.  Usually
 that means copying the language files from one of the existing languages,
 probably English since that's usually the most up-to-date.
 
-Add the new files to the proper place in docs/src/Submakefile, to ensure
-they get built.
+Copy the docs/po/Documentation.pot todocs/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.
 
 Edit debian/control.in to add the new linuxcnc-doc-$NEWLANG package.
 Add the new doc package to the or-list of the "Recommends" line of the