install po4a

Introduction

AsciiDoc is not supported by any translation tool: WebLate, Transifex, OmegaT, WorldTrans, etc. Translating documentation directly as AsciiDoc is hard to maintain.

[po4a](https://po4a.org/) to the rescue!

po4a can convert AsciiDoc to gettext (.po files) and back. [PR#325](https://github.com/uyuni-project/uyuni-docs/pull/325) added the [make_pot.sh](https://github.com/uyuni-project/uyuni-docs/blob/master/make_pot.sh) and [use_po.sh](https://github.com/uyuni-project/uyuni-docs/blob/master/use_po.sh) scripts and a few Antora tricks to generate translations, [PR#581](https://github.com/uyuni-project/uyuni-docs/pull/581) moved to the high-level po4a tool, which is what we use today.

Installing po4a

po4a >= 0.62 (we are using 0.66) is required for the AsciiDoc to gettext and back to work, otherwise the PDF will not be correctly rendered.

• OpenSUSE Leap 15.2: https://download.opensuse.org/repositories/devel:/languages:/perl/openSUSE_Leap_15.2/noarch/

• openSUSE Leap 15.3: https://download.opensuse.org/repositories/devel:/languages:/perl/openSUSE_Leap_15.3/noarch/

• openSUSE Leap 15.4: https://download.opensuse.org/repositories/devel:/languages:/perl/15.4/noarch/

• SLE 12 SP4: https://download.opensuse.org/repositories/devel:/languages:/perl/SLE_12_SP4/noarch/

• SLE 15: https://download.opensuse.org/repositories/devel:/languages:/perl/SLE_15/noarch/

• Ubuntu: https://launchpad.net/~pgquiles/+archive/ubuntu/uyuni

Before installing ensure you have the required perl dependencies:

cpan install Locale::gettext
cpan install Text::WrapI18N
cpan install Term::ReadKey
cpan install Unicode::GCString

In the case of openSUSE/SLES, if po4a from the operating system, or some other repository, is installed, make sure you allow vendor change for the right package to be picked up: zypper up --allow-vendor-change po4a

Troubleshooting

If your PDF is missing content, make sure po4a >= 0.62 is installed.

If you try to make antora-uyuni and it fails with an error like any of these (or all of these), then either po4a is not installed, or it’s too old of a version. Make sure po4a is installed:

/home/user/uyuni-docs//use_po.sh: line 75: po4a: command not found

or

sed -E  -e 's/\*\*\*\*\*\ xref\:(.*)\.adoc\[(.*)\]/include\:\:modules\/quickstart-public-cloud\/pages\/\1\.adoc\[leveloffset\=\+4\]/' -e 's/\*\*\*\*\ xref\:(.*)\.adoc\[(.*)\]/include\:\:modules\/quickstart-public-cloud\/pages\/\1\.adoc\[leveloffset\=\+3\]/' -e 's/\*\*\*\ xref\:(.*)\.adoc\[(.*)\]/include\:\:modules\/quickstart-public-cloud\/pages\/\1\.adoc\[leveloffset\=\+2\]/' -e 's/\*\*\ xref\:(.*)\.adoc\[(.*)\]/include\:\:modules\/quickstart-public-cloud\/pages\/\1\.adoc\[leveloffset\=\+1\]/' -e 's/\*\ xref\:(.*)\.adoc\[(.*)\]/include\:\:modules\/quickstart-public-cloud\/pages\/\1\.adoc\[leveloffset\=\+0\]/' -e 's/\*\*\*\*\ (.*)/==== \1/' -e 's/\*\*\*\ (.*)/=== \1/' -e 's/\*\*\ (.*)/== \1/' -e 's/\*\ (.*)/= \1/' modules/quickstart-public-cloud/nav-quickstart-public-cloud-guide.adoc > translations/es/modules/quickstart-public-cloud/nav-quickstart-public-cloud-guide.pdf.es.adoc
bash: translations/es/modules/quickstart-public-cloud/nav-quickstart-public-cloud-guide.pdf.es.adoc: No such file or directory
make: *** [Makefile.es:135: modules/quickstart-public-cloud/nav-quickstart-public-cloud-guide.pdf.es.adoc] Error 1

Now that the toolchain is installed proceed with building docs! Building Documentation