Re: [Emc-developers] RFC: doc translations

[Steffen Möller]

On 10.11.21 00:29, andy pugh wrote:

On Tue, 9 Nov 2021 at 23:19, Steffen Möller  wrote:


Maybe Andy could outline how his system
differs from what po4a would come up with.

The thing I was trying to address is that the HAL components that are
derived from .comp files are self-documenting.

You know better than me if adapting what po4a is doing the .comp files
has any advantages. I like what you have done.

So this source file:
https://github.com/LinuxCNC/linuxcnc/blob/master/src/hal/components/abs.comp

Creates this manpage:
http://linuxcnc.org/docs/2.8/html/man/man9/abs.9.html


Looks good. Since you have this dense integration of documentation and
source - with it is possible to add a link to the generated
documentation that points to the file on github from which it was
generated - but is everyone as exited about that prospect as I am? This
way a larger audience would be introduced to the source code and the
last ambiguities about what the function is doing would go away.

Sidenote - this "provenance" (have every piece of data explain how it
was generated) may be of interest to add to all parts of the documentation.

Best,
Steffen





___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers

Re: [Emc-developers] RFC: doc translations

[andy pugh]

On Tue, 9 Nov 2021 at 23:19, Steffen Möller  wrote:

> Maybe Andy could outline how his system
> differs from what po4a would come up with.

The thing I was trying to address is that the HAL components that are
derived from .comp files are self-documenting.

So this source file:
https://github.com/LinuxCNC/linuxcnc/blob/master/src/hal/components/abs.comp

Creates this manpage:
http://linuxcnc.org/docs/2.8/html/man/man9/abs.9.html

-- 
atp
"A motorcycle is a bicycle with a pandemonium attachment and is
designed for the especial use of mechanical geniuses, daredevils and
lunatics."
— George Fitch, Atlanta Constitution Newspaper, 1912


___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers

Re: [Emc-developers] RFC: doc translations

[Steffen Möller]

Hello,

I have looked at https://techbase.kde.org/Localization but failed to
take too much from their site. Maybe Andy could outline how his system
differs from what po4a would come up with.

The difficulty I see is that the synchronisation between the original
and its translations is not supported. And it may be preferable to have
one translation system for everything.

Also, I am with J.M. that the roles of developers and translators should
possibly be kept apart a bit more. This way, it is easy to tell that a
translator with a quick introduction to git will not unintentionally
change something functional.


Best,
Steffen

On 09.11.21 22:37, J.M. Garcia wrote:

Hi, Andy.
In my opinion, this solution has an drawback: the developer must take the
role of translator. And for several languages. I think it is potentially
dangerous, prone to errors and overload development work.
It's just my opinion.

El mar, 9 nov 2021 a las 20:54, andy pugh () escribió:


On Tue, 9 Nov 2021 at 19:21, J.M. Garcia  wrote:


worked last year I found many problems that were difficult to solve.
Example: the documentation of modules generated with halcompile.

I did manage to come up with a partial solution to this, which might
be practical in conjunction with gettext. Or might be totally
superseded by gettext.


https://github.com/LinuxCNC/linuxcnc/blob/andypugh/multilingual_comp/src/hal/components/abs.comp

Is an example of how a .comp file with multilingual documentation could
look.

(note that the language tags are _deliberately_ inconsistently
formatted for testing.)

It might be a better plan to hack halcompile to automatically
gettext-ify the docs, though.

--
atp
"A motorcycle is a bicycle with a pandemonium attachment and is
designed for the especial use of mechanical geniuses, daredevils and
lunatics."
— George Fitch, Atlanta Constitution Newspaper, 1912


___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers


___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers



___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers

Re: [Emc-developers] RFC: doc translations

[J.M. Garcia]

Hi, Andy.
In my opinion, this solution has an drawback: the developer must take the
role of translator. And for several languages. I think it is potentially
dangerous, prone to errors and overload development work.
It's just my opinion.

El mar, 9 nov 2021 a las 20:54, andy pugh () escribió:

> On Tue, 9 Nov 2021 at 19:21, J.M. Garcia  wrote:
>
> > worked last year I found many problems that were difficult to solve.
> > Example: the documentation of modules generated with halcompile.
>
> I did manage to come up with a partial solution to this, which might
> be practical in conjunction with gettext. Or might be totally
> superseded by gettext.
>
>
> https://github.com/LinuxCNC/linuxcnc/blob/andypugh/multilingual_comp/src/hal/components/abs.comp
>
> Is an example of how a .comp file with multilingual documentation could
> look.
>
> (note that the language tags are _deliberately_ inconsistently
> formatted for testing.)
>
> It might be a better plan to hack halcompile to automatically
> gettext-ify the docs, though.
>
> --
> atp
> "A motorcycle is a bicycle with a pandemonium attachment and is
> designed for the especial use of mechanical geniuses, daredevils and
> lunatics."
> — George Fitch, Atlanta Constitution Newspaper, 1912
>
>
> ___
> Emc-developers mailing list
> Emc-developers@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/emc-developers
>

___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers

Re: [Emc-developers] RFC: doc translations

[andy pugh]

On Tue, 9 Nov 2021 at 19:21, J.M. Garcia  wrote:

> worked last year I found many problems that were difficult to solve.
> Example: the documentation of modules generated with halcompile.

I did manage to come up with a partial solution to this, which might
be practical in conjunction with gettext. Or might be totally
superseded by gettext.

https://github.com/LinuxCNC/linuxcnc/blob/andypugh/multilingual_comp/src/hal/components/abs.comp

Is an example of how a .comp file with multilingual documentation could look.

(note that the language tags are _deliberately_ inconsistently
formatted for testing.)

It might be a better plan to hack halcompile to automatically
gettext-ify the docs, though.

-- 
atp
"A motorcycle is a bicycle with a pandemonium attachment and is
designed for the especial use of mechanical geniuses, daredevils and
lunatics."
— George Fitch, Atlanta Constitution Newspaper, 1912


___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers

Re: [Emc-developers] RFC: doc translations

[J.M. Garcia]

Greetings to the entire LinuxCNC community.

Translations ... the worst nightmare.
During the translation of documentation from English to Spanish in which I
worked last year I found many problems that were difficult to solve.
Example: the documentation of modules generated with halcompile.

But I don't think that's the root problem. My thought is that there are no
clear guidelines for both programmers and translators. Documentation
translation is not a trivial job. The number of factors to consider is
large; from the use of correct English by the editor of the original
documentation to a minimum knowledge of the subject by the translator.

GNU, KDE, or GNOME may have a lot of the work done:
- https://translationproject.org
- live.gnome.org/TranslationProject
- live.gnome.org/TranslationProject
I suggest analyzing how they are doing before making decisions.

Thanks!

El lun, 8 nov 2021 a las 20:41, Sebastian Kuzminsky ()
escribió:

> Hello LinuxCNC people, there's a possible change brewing that I'd like
> to ask for your feedback on.
>
> The translations of our documentation into non-English languages has
> been handled in an unusual and cumbersome way, and a new developer has
> suggested a plan to modernize and streamline things.
>
>
> How things are now:
>
> * All our documentation is maintained in Asciidoc format in the git
> repo, and built into HTML and PDF by the build system.
>
> * The "main" documentation is maintained in English.
>
> * To create a new translation, a translator copies the asciidoc source
> of the English documentation to a new language-specific asciidoc source
> file.  For example: `README.adoc` -> `README_fr.adoc`.  They edit the
> new file and translate the words.
>
> That's it!  Simple, but it has a couple of problems...
>
>
> Problems with the current system:
>
> * If the English-speaking developers change the main documentation file
> there is no automatic process to notify the translators, and the
> translated docs slowly drift out of date with the main English docs,
> without us really knowing.
>
> * The translations of the docs are handled differently than the
> translations of the software.  The translations of the strings in the
> software is done using a widely used system called "gettext", which has
> a suite of tools to identify translatable strings in programs and
> maintain a database of what those strings should look like in different
> languages.  You can learn more about gettext here:
> 
>
>
> The new proposal is basically to use gettext for everything, both the
> software and the documentation.  This would be done using a system
> called po4a: 
>
> Moving the docs translations to po4a would let us use the standard
> gettext tools, including online tools like Weblate, to maintain the
> translations.  gettext keeps track of what "main" english strings have
> changed, and flags the translations of those strings as "out of date",
> so that translators know they need attention.  Out-of-date translations
> automatically fall back to using the up-to-date english strings.
>
> I'm not very experienced with translations, so I'm asking for comments
> from the folks who currently do the work of translating LinuxCNC (both
> docs & software) into non-English languages...
>
> Do you have any concerns, input, or comments on this proposal?
>
> Would you be willing to verify and update the translations into your
> languages?
>
> What can we software people do to help make this task easier?
>
>
> Thanks!
>
>
> --
> Sebastian Kuzminsky
>
>
> ___
> Emc-developers mailing list
> Emc-developers@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/emc-developers
>

___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers

Re: [Emc-developers] Processing of linuxcnc_2.9.0~pre0+git20211108.cf14c89a9-1_amd64.changes

[Sam Sokolik]

Amazing work!

On Tue, Nov 9, 2021, 9:35 AM Chris Radek  wrote:

> On Mon, Nov 08, 2021 at 06:31:20PM -0700, Sebastian Kuzminsky wrote:
> >
> > This will make it much easier for people to try out LinuxCNC, and will
> > greatly increase our visibility in the CNC software world.
> >
> > This is an exciting time for LinuxCNC, and we could not have done it
> > without Steffen and Petter.  Thank you!  <3
>
> Wow, thank you for doing this work.  It's a goal the project has had
> for 20 years and I very much appreciate everyone who helped make it
> possible.
>
> Cheers,
> Chris
>
>
>
> ___
> Emc-developers mailing list
> Emc-developers@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/emc-developers
>

___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers

Re: [Emc-developers] Processing of linuxcnc_2.9.0~pre0+git20211108.cf14c89a9-1_amd64.changes

[Chris Radek]

On Mon, Nov 08, 2021 at 06:31:20PM -0700, Sebastian Kuzminsky wrote:
> 
> This will make it much easier for people to try out LinuxCNC, and will 
> greatly increase our visibility in the CNC software world.
> 
> This is an exciting time for LinuxCNC, and we could not have done it 
> without Steffen and Petter.  Thank you!  <3

Wow, thank you for doing this work.  It's a goal the project has had
for 20 years and I very much appreciate everyone who helped make it
possible.

Cheers,
Chris



___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers

Re: [Emc-developers] RFC: doc translations

[Steffen Möller]

Hello,

On 08.11.21 20:40, Sebastian Kuzminsky wrote:

Hello LinuxCNC people, there's a possible change brewing that I'd like
to ask for your feedback on.

The translations of our documentation into non-English languages has
been handled in an unusual and cumbersome way, and a new developer has
suggested a plan to modernize and streamline things.


I thought I should chime in, to help keeping the momentum - and the
other DD, Petter, was the one who came up with this, not me :)

I see two basic challenges:

a) localize the documentation to lower entry barriers for decision makers
b) localize the runtime GUIs to lower the barriers for users (which also
will affect a) ).

From what I see on YouTube, the individuals behind a) and b) are
typically the same person. But this hopefully changes with automation
soon found everywhere.

The .po files are known to help with the runtime localisation for ages.
Every language has a file with pairs of lines - English first, localized
underneath. These lists are extracted and mainted automatically with the
source code. This po4a I did not know about before. They now extends
that principle with documentation. So, when the English manual has
paragraphs reordered, the other languages are equally reordered. No
exact idea yet how this works with single sentences introduced or words
changed but am confident these folks found something reasonable.

There is a c). Show to the world that LinuxCNC keeps rejuvenating itself.



How things are now:

* All our documentation is maintained in Asciidoc format in the git
repo, and built into HTML and PDF by the build system.

* The "main" documentation is maintained in English.

* To create a new translation, a translator copies the asciidoc source
of the English documentation to a new language-specific asciidoc
source file.  For example: `README.adoc` -> `README_fr.adoc`.  They
edit the new file and translate the words.

That's it!  Simple, but it has a couple of problems...


Problems with the current system:

* If the English-speaking developers change the main documentation
file there is no automatic process to notify the translators, and the
translated docs slowly drift out of date with the main English docs,
without us really knowing.


Right. This will not be automagically solved, people still need to
translate, but it will manageable since you see what paragraphs have
been changed and also see the corresponding outdated chunk of
translation next to it.



* The translations of the docs are handled differently than the
translations of the software.  The translations of the strings in the
software is done using a widely used system called "gettext", which
has a suite of tools to identify translatable strings in programs and
maintain a database of what those strings should look like in
different languages.  You can learn more about gettext here:



Gettext and .po files are a long established technology. There are also
many auxiliary tools to help with the translation. That should be mostly
painless. The danger is that someone light-heartedly translates units
without thinking straight, like "inch" to "mm". I have no doubt that
this will be caught quickly, though.



The new proposal is basically to use gettext for everything, both the
software and the documentation.  This would be done using a system
called po4a: 

Moving the docs translations to po4a would let us use the standard
gettext tools, including online tools like Weblate, to maintain the
translations.  gettext keeps track of what "main" english strings have
changed, and flags the translations of those strings as "out of date",
so that translators know they need attention. Out-of-date translations
automatically fall back to using the up-to-date english strings.

I'm not very experienced with translations, so I'm asking for comments
from the folks who currently do the work of translating LinuxCNC (both
docs & software) into non-English languages...


Debian has translations of its package descriptions. And even though all
my professional life is in English, when I read through
https://blends.debian.org/med/tasks/bio (please have a look) you will
find that there is an extra edge to those descriptions that are
translated. I find that amazing and this experience helped me to keep my
arrogance in check.



Do you have any concerns, input, or comments on this proposal?

I think it is one the most important developmental steps for LinuxCNC to
take. The translations should preferably not be performed by the
developers but by the users.


Would you be willing to verify and update the translations into your
languages?


Wrong addressees. Let me try rephrase that: "Would you be willing to
help organizing translations into your languages and to help your local
user base to contribute and forward their problems?" Problems likely are
differences in the order words in sentences that would affect the C code
and 

Re: [Emc-developers] Processing of linuxcnc_2.9.0~pre0+git20211108.cf14c89a9-1_amd64.changes

[Steffen Möller]

On 09.11.21 02:46, Rod Webster wrote:

Awesome work guys. I for one am super excited.
Thanks so much. Please pass on thanks to all concerned.

So the big question is, are those packages available in Debian testing
(12)?
If not, how long do they take to ripple through?


Thank you. On https://ftp-master.debian.org/new.html you see that we are
9 hours in and have 6 packages that arrived later than LinuxCNC. There
is quite a steady influx of packages, which is amazing. 367 packages are
currently waiting in the queue. The packages at the top of the waiting
list are waiting since 8 months and my hunch is that if there is not an
FTPmaster with a lathe at home waiting to be retrofitted then we need to
crawl to that top of the list, too. This is just because it is a 41MB
tarball and the FTPmasters typically check every file for some copyright
violation or authors that have not been declared in d/copyright and and
and, which takes considerable time. FTPmastesr coming home from a
working day, it is then more likely that smaller package is
cherry-picked - which are also important since these are typically some
build-dependency for something larger.

mesaflash is now waiting for about a month and is in the upper third of
the waiting list. My gut feeling says that this should be in within the
next two weeks.

Best,
Steffen




On Tue, 9 Nov 2021 at 11:32, Sebastian Kuzminsky  wrote:


On 11/8/21 6:16 PM, Debian FTP Masters wrote:

linuxcnc_2.9.0~pre0+git20211108.cf14c89a9-1_amd64.changes uploaded

successfully to localhost

along with the files:
linuxcnc_2.9.0~pre0+git20211108.cf14c89a9-1.dsc
linuxcnc_2.9.0~pre0+git20211108.cf14c89a9.orig.tar.xz
linuxcnc_2.9.0~pre0+git20211108.cf14c89a9-1.debian.tar.xz
linuxcnc-doc-cn_2.9.0~pre0+git20211108.cf14c89a9-1_all.deb
linuxcnc-doc-en_2.9.0~pre0+git20211108.cf14c89a9-1_all.deb
linuxcnc-doc-es_2.9.0~pre0+git20211108.cf14c89a9-1_all.deb
linuxcnc-doc-fr_2.9.0~pre0+git20211108.cf14c89a9-1_all.deb
linuxcnc-uspace-dbgsym_2.9.0~pre0+git20211108.cf14c89a9-1_amd64.deb
linuxcnc-uspace-dev_2.9.0~pre0+git20211108.cf14c89a9-1_amd64.deb
linuxcnc-uspace_2.9.0~pre0+git20211108.cf14c89a9-1_amd64.deb
linuxcnc_2.9.0~pre0+git20211108.cf14c89a9-1_amd64.buildinfo

Greetings,

   Your Debian queue daemon (running on host usper.debian.org)

Wooo h!

Huge thanks to Steffen Möller and Petter Reinholdtsen of the Debian
project for all their work getting LinuxCNC into an acceptable state for
inclusion into Debian, and for uploading our packages to the NEW queue.

There's surely more work to do, but if all goes well I expected starting
with the next release of Debian 12 "Bookworm", users will be able to
install LinuxCNC (and all dependencies, including the RT-Preempt
realtime kernel) directly from the debian.org package archives.  Shortly
thereafter the derivative distributions like Ubuntu and Mint will pick
up LinuxCNC.

This will make it much easier for people to try out LinuxCNC, and will
greatly increase our visibility in the CNC software world.

This is an exciting time for LinuxCNC, and we could not have done it
without Steffen and Petter.  Thank you!  <3


--
Sebastian Kuzminsky


___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers


___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers



___
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers