Hi,
while scouring our tree for USE_GROFF, i stumbled over a few cases
of non-English pages and looked around a bit in that respect.
To put it politely, the current situation is only partly coherent.
1. Many ports install non-English manual pages.
A few don't, even though upstream provides something.
2. Many ports install unformatted manual pages,
a few install preformatted with groff (or jnroff).
I already fixed one or two where formatting broke the encoding,
but i suspect that some remain.
3. Many ports install UTF-8 encoded,
quite a few install other encodings.
In most cases, the encoding is not specified anywhere.
4. Most install to man/language/manN, which is good.
Some install to man/language_REGION/manN, a few even for
languages where /language/ also exists.
Some install to man/language.ENCODING/manN, both for UTF-8
and for other encodings.
Very few install to man/language@variant/manN.
I don't say this is a very high priority project, also because there
are only about 500 non-English manuals in the ports tree at this
time, but i think it is relatively cheap to improve quality and
consistency a bit by following these rules of thumb (take these as
Requests For Comments, not as Fiats):
1. If upstream provides non-English manual pages, install them if
that is possible without jumping through hoops, and unless there
are specific reasons not too. "They are outdated" is not a
good reason to not install them, as long as upstream still
includes them in the official distribution.
2. Never install any encoding except UTF-8.
If upstream provides UTF-8, great.
Otherwise, set BUILD_DEPENDS = converters/libiconv
and use iconv(1) in the post-build target.
(I already discussed this item with a few porters and they agreed.)
3. If mandoc(1) copes, which you can check in exactly the same
way as with English manuals, simply install the UTF-8 source
code to man/language/manN/*.N and do not USE_GROFF.
4. If mandoc(1) does not cope - which should be very rare by now,
we have less than 130 ports left in the whole tree that still
USE_GROFF, even for English manuals - the proper order of
operations is iconv(1) -t UTF-8, then preconv(1), then nroff(1),
never some other way round.
5. If possible, install to man/language/manN, without any "_", ".",
or "@": KISS. There are rare exceptions, most notably zh_CN
vs. zh_HK vs. zh_TW.
Never include the encoding in the path name, and make sure
the /language/ part never contains "." (a dot).
6. This is all about special needs. If your port has special needs
and you understand them and care, by all means do whatever makes
sense, don't squeeze it into a scheme that doesn't fit.
If the above is followed, people can do the following with no
changes to any part of the default configuration:
$ doas pkg_add mc
$ export LC_CTYPE=en_US.UTF-8
$ alias ruman="man -m /usr/local/man/ru"
$ ruman mc
Any opinions?
If you think the above makes sense, i'm likely to do some of that
myself while continuing work on USE_GROFF, but i don't promise
to check all 500 pages, of course.
Item 1 above might need an explanation, so here you go:
I don't say that translating documentation is always a good idea.
Quite to the contrary, i think that it is not unusual to do more
harm than good. But the reasons why that is so are purely practical
reasons (mostly excessive workload and translations being poor in
the first place and getting outdated over time); in principle,
having information available in more than one language could make
the world a better place, and tooling should not discourage people
trying to prove that for some projects, it is also feasible in
practice.
Do not try to judge the quality of the translated pages, or whether
they are up to date. Just install them anyway. Most port maintainers
won't even know the languages in question, and even if they do,
they should not waste their time assessing the quality for each
update. Even if they would try, there is no way to define a
reasonable quality threshold. For a user having very serious
problems reading English at all, even a badly outdated translation
can help getting started. For a user who more or less understands
English, even tiny translation errors can make a translated manual
seriously harmful. Even if a quality standard could be defined,
removing and re-adding the translations for every second update,
following the inevitably oscillating quality, wouldn't make sense.
If people use translated manuals, they are hopefully aware that
they are less exact than the original and more likely to not be up
to date, and deplorably often enough quite badly so. That's just
common sense. We always provide rope because that is useful to
some, and if others abuse it to hang themselves (or their friends
or enemies), that is unfortunate, but not an argument against ropes.
Finally, even if a translation is known to be outdated, updating
it is often less work than starting over from scratch, so it is
useful for people to know what exists. Kicking away outdated pages
doesn't encourage users to update them and send their work upstream.
But OpenBSD wants to encourage users to participate in the free
software life cycle. It is a developer-oriented system.
Oh, and we are talking about ports here. Many ports manuals are
low quality anyway, even the English ones. That is upstream's
responsibility, not porter's. We don't kick away English manual
pages either, no matter how much upstream may have neglected
keeping them up to date.
Yours,
Ingo
P.S.
Do not start sending stuff for /usr/share/man/*/manN/.
We *know* that we don't have the resources to maintain that.
