[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Groff] Nesting font macros in man pages

From: Ingo Schwarze
Subject: Re: [Groff] Nesting font macros in man pages
Date: Thu, 4 May 2017 23:01:02 +0200
User-agent: Mutt/1.6.2 (2016-07-01)

Hi Colin,

Colin Watson wrote on Thu, May 04, 2017 at 07:07:28PM +0100:

> The main practical reason I've stuck with man(7) in some cases
> (such as in man-db)

Actually, for man-db, the choice of man(7) is somewhat understandable,
since man-db is most relevant in situations where mandoc(1) is not
available or not wanted, and that maybe correlates with a certain
bias against mdoc(7).

> despite generally preferring mdoc(7) is that I think translations
> are important,

In general, i think that translation of documentation is harmful
rather than useful.  Normally, even freshly translated documents
are of lower quality than the original, so readers are usually
better off reading the original than the translation, even if their
command of the english language is weaker.  Over time, translated
documentation almost always gets outdated, at which point it is
definitely very harmful.  I do not think that it is plausible that
tools like po4a will change that.  Even if you had the perfect
translation toolkit, maintaining translations is an awful lot of
work, more than (work for maintaining the original) times (number
of languages to be maintained).  In practically every real-world
project, that kind of manpower definitely isn't available.  In most
projects, even the original manual pages are poorly maintained,
so adding a multiple of that work is out of the question.

While *theoretically*, translation of documentation might be an
interesting idea, the consequence of the above observations is
that i have never encountered any project where translation of
manual pages was even attempted (not even to one single language).

Even FreeBSD never attempted that, even though that's quite a
large project.

> and po4a(1) works rather more gracefully with man(7).
> With mdoc(7), I find that I end up with nonsense like this
> in my .pot file, which I really can't expect a translator to have the
> slightest clue about:
>   #. type: Plain text
>   #: madison-lite.1:21
>   msgid ""
>   "E<.Nm> E<.Op Fl Fl config\\-file Ar file> E<.Op Fl Fl mirror Ar directory> 
> "
>   "E<.Op Fl Fl nocache> E<.Op Fl Fl update> E<.Op Fl S> E<.Op Fl r> E<.Op Fl 
> a "
>   "Ar architecture Ns Op , Ns Ar ...> E<.Op Fl c Ar component Ns Op , Ns Ar "
>   "...> E<.Op Fl s Ar suite Ns Op , Ns Ar ...> E<.Ar package> E<.Op Ar ...>"
>   msgstr ""

That's obviously from a SYNOPSIS.

I don't think it's a good idea to translate anything in a SYNOPSIS.

The point of the SYNOPSIS is documenting the subtleties of the syntax,
and the risk of breaking the syntax in the process of translation
seems too high.

> Locale::Po4a::Man(3pm) does offer some ways to hit this over the head,
> but they don't really work very well in practice,

That doesn't really come as a surprise.  Translation operates on text,
not on formal syntax descriptions.

> I think because it doesn't understand the way that mdoc(7) parses
> its argument list for callable macro names.  An understandable
> omission given the complexity,

I think because of the blocker above - which could probably be solved
by excluding some parts from translation - you have missed the main
problems.  Consider typical manual page text like the following
from the mandoc eqn(7) manual:

  .It Cm sup
  Set the following box as a superscript to the preceding box.
  As a special case, if a
  .Cm sup
  clause immediately follows a
  .Cm sub
  clause as in
  .D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox
  both are set with respect to the same
  .Ar mainbox ,
  that is,
  .Ar supbox
  is set above
  .Ar subbox .

That is *one* paragraph (even one sentence), not three paragraphs,
in spite of the two .Pp macros.  So it has to be translated as one
unit.  How is po4a supposed to figure that out?

Next problem: assume we tell translators:  you must never
translate parts enclosed in <<<...>>> (or some other, conspicious
markers to be agreed upon), and you must never change the order
of instances of these (the latter may cause trouble in some
languages, but let's ignore that for a second).  Then the
above paragraph would ideally translate into something like this:

  <<<.It Cm sup
  >>>Set the following box as a superscript to the preceding box.
  As a special case, if a<<<
  .Cm sup
  >>>clause immediately follows a<<<
  .Cm sub
  >>>clause as in<<<
  .D1 Ar >>>mainbox<<< Cm sub Ar >>>subbox<<< Cm sup Ar >>>supbox<<<
  >>>both are set with respect to the same<<<
  .Ar >>>mainbox ,<<<
  >>>that is,<<<
  .Ar >>>supbox<<<
  >>>is set above<<<
  .Ar >>>subbox .

The <<<...>>> scheme proposed here is similar in spirit to the
B<>/I<> scheme used by po4a, but the latter is inadequate for
mdoc(7) because it is too simplistic, so i had to somehow
generalize it.  The tool would check that the translator indeed
left the <<<...>>> unmangled.  Also note that line breaks are
critically significant in mdoc(7), so po4a must *never* do any

Is something like the above editable for translators?
I'm not sure, but i doubt that much can be simplified.

Besides, should placeholders (.Ar, .Fa, ...) be translated?
If yes, they may also appear unmarked in free text, and the
translation must be consistent, which is likely to fail.  If no,
errors are less likely, but the text might seem harder to end-users.
Or maybe even go a step further an not translate anything on any
macro lines?  That would be safer and simpler, but would occasionally
leave a word that should
.Em really
be translated (like stress emphasis) untranslated.

> but it does end up being a blocker for me.
> This is of course not a deficiency in *roff, but it's a problem in the
> wider ecosystem that IMO a serious push towards mdoc(7) ought to
> address.

If there is a substantial project that wants to do translation,
working through all this would be a serious undertaking.  If some
project *really* wants to do that (and can make it plausible that
they do have the manpower for at least one language), i might
consider helping, even though i expressed serious doubt about the 
usefulness, above.

The point is, unless one seriously tries, doubting the usefulness
is as much conjecture as asserting it.  The outcome of such a
project would supply one real-world data point strengthening either
side of the argument, and the resulting software would make it easier
for others to gather more data points.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]