[Perkamon-devel] Beginning of FAQ about perkamon

[Denis Barbier]

Hi,

There has been some interest from non-French speaking people about
  https://alioth.debian.org/projects/perkamon/
recently, but there is no English documentation yet.  I will try to
write docs soon, but here is a beginning of FAQ.
Do not hesitate to add your own questions to make this FAQ even more useful ;-)

  Q: What is the latest version?
   A: man-pages 3.24

  Q: Which languages are supported?
  A: Only French for now, but adding a language is trivial, a single
variable has to be modified in a Makefile. Well, after that, real work
begins, PO files have to be translated :-)

  Q: Which tool is needed to build translations?
  A: po4a 0.38 or above.  Can be downloaded from
<URL:http://alioth.debian.org/frs/?group_id=30267>

  Q: Which tool is needed to perform translations?
  A: Any PO editor is fine.

  Q: Ouch, po4a configuration files (po4a/man*/man*.cfg) look ugly,
why are they so complicated?
  A: There are 2 reasons. a) We want to credit previous French
translators for their hard work, which means that a specific credits
section is added to almost all pages.  b) We do not know what
distributions will need to build derived translations, and thus we
provided a generic solution.  For instance, in the French translation
team in Debian, we use to add a paragraph to ask bugs or comments
being sent to our l10n mailing-list.  With the current framework, it
is very easy to add any paragraph to all manual pages, or to specific
pages only.

  Q: Does it mean that I have to add a credit section in all my files?
  A: No, you do not have to add any specific information, you can
translate PO files without worrying about other files if you do not
want to add translator's notices.

  Q: Can I use external facilities (transifex, pootle, launchpad,...)
to translate PO files?
  A: Sure, each translation team can manage PO files as they want,
perkamon is there only to provide up-to-date POT files; you manage
your translations as you want.

  Q: Why one to three POT files by man section, and not one POT file by page?
  A: When we converted nroff pages to po4a, we found convenient to
have larger files because many msgids are not unique.  On the other
hand, some gettext commands do not work well with very large files.
Sections 2, 3 and 7 have been arbitrarily cut into smaller pieces.

  Q: I am interested to use perkamon to translate man-pages, how can I do?
  A: If there is already a translator, you should first discuss with
him/her to see if you agree on using perkamon, otherwise you will
waste everybody's time.  If you are the coordinator for your language,
you will decide how you cooperate within your team, and when ready,
you tell us on perkamon-devel@ who needs commit rights on gitorious.

  Q: I maintain a translation of man-pages in a Linux distribution,
but our man-pages are patched, how can I provide patched translations?
  A: There are samples in
<URL:http://gitorious.org/perkamon/man-pages-derived/>  for Debian,
Fedora, Mandriva and openSUSE.  These are mostly proofs of concepts,
you should discuss with us on perkamon-devel if you have trouble or if
you think that current machinery could be simplified.

  Q: I am confused by the last 2 questions, why are 2 people working
on the same translation?
  A: They do not translate the same msgids. The first one translates
the msgids extracted from the official man-pages tarballs.  The second
one translates msgids which are specific to her distribution, there is
no overlap.

  Q: I am still confused, who is in charge of what?
  A: Upstream man-pages are managed in
<URL:http://gitorious.org/perkamon/man-pages/>.  I update POT files,
and am also the coordinator of French translations.  Other
coordinators can commit their own PO files, or delegate this task to
others (human beings or online tools).  For distributions,  nothing is
decided; IMO the ideal solution would be that the maintainer of the
man-pages package (or someone familiar with l10n) maintain POT files,
either in <URL:http://gitorious.org/perkamon/man-pages-derived/> or in
their own SCM, and she helps localization teams in working with their
PO files.

Denis