On Sun, Jul 19, 2026 at 05:30:42PM +0200, Patrice Dumas wrote:
> Hello,
>
> The second discussion on translated manuals recommendations, this time
> on output manual name.
>
> In the following LL corresponds to a full language specification, with
> @documentlanguage, @documentscript and @documentlanguagevariants.
>
> In many cases, the manual file name is a project name that is not
> translatable. Having a manual file name or parts of it that could be
> translated also happens, for example if there are several manuals for
> a project and one manual has 'tutorial' in its file name, that
> part could be translated.
>
> For the translated manual output file location, my proposal is to have
> the language specification in the manual name. That way there is no
> need for specific installation location nor manual name mapping.
>
> I propose
> main_manual_name-LL or main_manual_name_LL
> if the manual name is not translatable. If the manual name is
> translatable, it could be possible to translate the manual name, using:
> translated_manual_name
> or
> translated_manual_name-LL
> but it seems somewhat more complex to me for tools like gendoc.sh that
> could process automatically translated manuals.
>
> Other options could have been main_manual_name.LL, but . is usually used
> for extensions, and LL/main_manual_name but it requires some changes in
> the converters and Info readers, which I would like to avoid.
help2man seems to use help2man-LL, e.g. help2man-es for Spanish. help2man
is one project with several translated manuals, for some reason.
I think this should be left to the writers of the manual. texi2any
certainly should not add a suffix to the output file name (I'm not sure
if you were proposing this) as this would conflict with existing uses.
We could suggest/recommend using such a suffix in the source file name,
e.g. help2man-es.texi.
> All the output manuals could be installed in the same directory in the
> the default case.
This appears to contradict your recommendation in the other thread to
use a separate dir file for manuals in a particular language, in a separate
directory.
> The split manuals names would naturally be constructed similarly.
>
> For htmlxref, it could be possible to have some automatic
> generalisation when there is no existing entry, ie, when there is a
> language in the output file name like mymanual-LL, possibly with a check
> of matching @documentl* in the tree and there is
>
> mymanual node ${GS}/something/mymanual/mymanual
>
> occurences of mymanual in the path would become mymanual-LL. Also we
> could extend htmlxref with list of languages with translations for a
> manual.
>
I can't follow your explanation here. What do you mean by "occurences of
mymanual in the path"?
The mymanual htmlxref entry is for links to the mymanual manual, but you
are talking about the output file name being mymanual-LL, which is unlikely
to contain cross-references to itself.
>
> Remarks, thoughts?
>
> --
> Pat
>
