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 .Pp .D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox .Pp 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<<< .Pp .D1 Ar >>>mainbox<<< Cm sub Ar >>>subbox<<< Cm sup Ar >>>supbox<<< .Pp >>>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 folding. 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. Yours, Ingo