[pacman-dev] Translation of man pages

Message ID CAHi0vA-NPY3o05iotq+_1-+8n1erxJjX5W0M__OLaKK3488ZZg@mail.gmail.com
State New
Headers show
Series [pacman-dev] Translation of man pages | expand

Commit Message

Mario Blättermann May 21, 2021, 4:51 p.m. UTC
Hello,

the translation help page [1] says:

---
There are currently no efforts underway to include translated manual
pages in the pacman codebase. However, this is not to say translations
are unwelcome. If someone has experience with i18n man pages and how
to best include them with our source, please contact the pacman-dev
mailing list at pacman-dev@archlinux.org.
---

OK, then let me introduce my approach. Although the man page
translations are already maintained in the manpages-l10n project [2]
for some years, I think it is it better to use Pacman's upstream tree
instead. The external maintenance has some disadvantages: We download
distribution packages, create the templates, translate them and
release the translated man pages some months later. Besides this
delay, we don't know how many users know about the existence of the
translated versions. Having the translations in the upstream project
(translated using Transifex) would be better, and the localized
versions would be released with Pacman itself and always in sync with
the English ones.

See the attached patch and config file. The patch manpage-markup.diff
fixes the Asciidoc markup to get Po4a [3] properly working. After
applying the patch, put po4a.cfg in doc/po/. I've imported German,
Brazilian Portuguese and French translations from manpages-l10n, but
even compressed they
are too big for the list. The .po files will follow in separate
mails.To test the creation of the translated
Asciidoc files, just run 'po4a po4a.cfg'. This command creates a
translation template and a subdirectory for each language and saves
the resulting files there.
Once you have the Asciidoc files, they can be processed further like
those in doc/.

Unfortunately, I don't have neither Autotools nor Meson knowledge,
maybe someone else can help with integration into the build systems?

[1] https://archlinux.org/pacman/translation-help.html#_translating_manpages
[2] https://salsa.debian.org/manpages-l10n-team/manpages-l10n
[3] https://po4a.org/index.php.en

Best Regards,
Mario

Comments

Mario Blättermann May 21, 2021, 4:54 p.m. UTC | #1
Hello,

Am Fr., 21. Mai 2021 um 18:51 Uhr schrieb Mario Blättermann
<mario.blaettermann@gmail.com>:
> […]
> I've imported German,
> Brazilian Portuguese and French translations from manpages-l10n, but
> even compressed they
> are too big for the list.

See the attached de.po. Unpack it in doc/po/ to test the creation of
the translated Asciidoc files.

Best Regards,
Mario
Allan McRae May 28, 2021, 2:34 a.m. UTC | #2
On 22/5/21 2:51 am, Mario Blättermann wrote:
> Hello,
> 
> the translation help page [1] says:
> 
> ---
> There are currently no efforts underway to include translated manual
> pages in the pacman codebase. However, this is not to say translations
> are unwelcome. If someone has experience with i18n man pages and how
> to best include them with our source, please contact the pacman-dev
> mailing list at pacman-dev@archlinux.org.
> ---
> 

Thanks - on first glance this looks good. I am focusing on things that
will appear in pacamn-6.0.1 at the moment, but have this flagged for
full review afterwards.

Allan
Allan McRae June 3, 2021, 4:08 a.m. UTC | #3
On 22/5/21 2:51 am, Mario Blättermann wrote:
> Hello,
> 
> the translation help page [1] says:
> 
> ---
> There are currently no efforts underway to include translated manual
> pages in the pacman codebase. However, this is not to say translations
> are unwelcome. If someone has experience with i18n man pages and how
> to best include them with our source, please contact the pacman-dev
> mailing list at pacman-dev@archlinux.org.
> ---
> 
> OK, then let me introduce my approach. 

<snip>

Thanks - this approach looks good to me.  We had someone on IRC suggest
the same approach independently of this patch too!

Just checking before I pull all this together:

1) are you happy is I use your name and email in the commit log.

2) are the translated manpages published under any license?  Just making
sure that importing them does not create issues...

3) are there languages other than German, Brazilian Portuguese and
French already available?
Mario Blättermann June 3, 2021, 7:17 a.m. UTC | #4
Hello Allan,

Am Do., 3. Juni 2021 um 06:09 Uhr schrieb Allan McRae <allan@archlinux.org>:
>
> On 22/5/21 2:51 am, Mario Blättermann wrote:
> > Hello,
> >
> > the translation help page [1] says:
> >
> > ---
> > There are currently no efforts underway to include translated manual
> > pages in the pacman codebase. However, this is not to say translations
> > are unwelcome. If someone has experience with i18n man pages and how
> > to best include them with our source, please contact the pacman-dev
> > mailing list at pacman-dev@archlinux.org.
> > ---
> >
> > OK, then let me introduce my approach.
>
> <snip>
>
> Thanks - this approach looks good to me.  We had someone on IRC suggest
> the same approach independently of this patch too!
>
> Just checking before I pull all this together:
>
> 1) are you happy is I use your name and email in the commit log.
>
Yes, of course.

> 2) are the translated manpages published under any license?  Just making
> sure that importing them does not create issues...
>
The manpages-l10n project publishes the translated man pages under
GPLv3+. However, some downstream packagers decided to mention all the
upstream licenses in their packages (see [1]), but as far as I can
evaluate, our translations are - regarding the license - rather
independent from the English originals. So using GPLv3+ in general
should be a good choice. And the Pacman man pages are GPLed anyway.

> 3) are there languages other than German, Brazilian Portuguese and
> French already available?

No, at least there's nothing known to me. Some years ago I started
with the German translations from scratch, later the Brazilian
Portuguese translations by Rafael were added, and then I found a few
unmaintained and outdated French translations, residing in the AUR for
a long time [2]. These I've imported and added to manpages-l10n.

Note, to avoid file conflicts, it is important to have a deadline for
the inclusion of translated man pages in Pacman itself. As soon as
they are available from the official package, I need to roll out a
bugfix release of manpages-l10n without the Pacman .po files.

BTW, due to the latest changes in libalpm, we don't have static
asciidoc sources anymore. I don't know how we could generate
translation templates within the Doxygen workflow, maybe it is
impossible at all. AFAIK, the only output format usable with Po4a is
»man page« [3]. Just an idea: To get a translation template for the
libalpm man pages, we let Doxygen generate some temporary *roff files
and use po4a to create an extra template on the fly which we provide
on Transifex. I anyway think it makes sense to split the translations
into an end user part (sections 1, 5, 8) and a developer part (section
3). But there's no need to host the template in the Git repo -- the
Pacman tarball would only ship .po files (if any) and create the
translated versions downstream. But let's focus on the Asciidoc based
man pages first and get them properly working; the Libalpm stuff can
be done later.

[1] https://src.fedoraproject.org/rpms/man-pages-l10n/raw/rawhide/f/man-pages-l10n.spec
[2] https://aur.archlinux.org/packages/man-pages-pacman-fr/
[3] https://www.doxygen.nl/manual/output.html

Best Regards,
Mario

Patch

diff --git a/doc/makepkg.conf.5.asciidoc b/doc/makepkg.conf.5.asciidoc
index 76c27f6a..a5ff4c99 100644
--- a/doc/makepkg.conf.5.asciidoc
+++ b/doc/makepkg.conf.5.asciidoc
@@ -39,11 +39,11 @@  Options
 	well, and any protocol can have a download agent.  Any spaces in option
 	arguments are required to be escaped to avoid being split.  Several
 	examples are provided in the default makepkg.conf.
-	+
-	If present, `%u` will be replaced with the download URL. Otherwise, the
-	download URL will be placed on the end of the command. If present, `%o` will
-	be replaced with the local file name, plus a ``.part'' extension, which allows
-	makepkg to handle resuming file downloads.
++
+If present, `%u` will be replaced with the download URL. Otherwise, the
+download URL will be placed on the end of the command. If present, `%o` will
+be replaced with the local file name, plus a ``.part'' extension, which allows
+makepkg to handle resuming file downloads.
 
 **VCSCLIENTS=(**\'protocol::package' ...**)**::
 	Sets the packages required to fetch version controlled source files. When
@@ -282,9 +282,9 @@  Options
 	Specify a command prefix for running pacman as root. If unset, makepkg will
 	check for the presence of sudo(8) and su(1) in turn, and try the first one
 	it finds.
-	+
-	If present, `%c` will be replaced with the shell-quoted form of the command
-	to run. Otherwise, the command to run is appended to the auth command.
++
+If present, `%c` will be replaced with the shell-quoted form of the command
+to run. Otherwise, the command to run is appended to the auth command.
 
 
 
diff --git a/doc/pacman.conf.5.asciidoc b/doc/pacman.conf.5.asciidoc
index fd765f3d..fbf6ba78 100644
--- a/doc/pacman.conf.5.asciidoc
+++ b/doc/pacman.conf.5.asciidoc
@@ -127,10 +127,10 @@  Options
 	instances of `%o` will be replaced with the local filename, plus a
 	``.part'' extension, which allows programs like wget to do file resumes
 	properly.
-	+
-	This option is useful for users who experience problems with built-in
-	HTTP/FTP support, or need the more advanced proxy support that comes with
-	utilities like wget.
++
+This option is useful for users who experience problems with built-in
+HTTP/FTP support, or need the more advanced proxy support that comes with
+utilities like wget.
 
 *NoUpgrade =* file ...::
 	All files listed with a `NoUpgrade` directive will never be touched during
diff --git a/doc/repo-add.8.asciidoc b/doc/repo-add.8.asciidoc
index 8de4485b..1b637c2e 100644
--- a/doc/repo-add.8.asciidoc
+++ b/doc/repo-add.8.asciidoc
@@ -1,5 +1,5 @@ 
 repo-add(8)
-==========
+===========
 
 Name
 ----