Bug#1064394: release-notes: English language output for the commands into script session

[Franco]

Package: release-notes
Severity: wishlist
X-Debbugs-Cc: marte...@gmail.com

Dear Debian Documentation Project staff,

I want to suggest to add a sentence like the following to the §4.4.1 "Recording the session" paragraph. ¹ Below the "script" command:

--- BEGIN of the statement ---
" If you are comfortable with English language it's strongly recommended that you run the following command as soon as you start the 'script' session:

# LC_ALL=C.UTF-8; LANGUAGE=; export LC_ALL LANGUAGE

This will allow you to get command output messages in English into the script session. By doing so, it will help you for searching the web, during discussions or to submit a bug report."
--- END of the statement ---

This change it has been discussed on debian-user mailing-list here. ²
The syntax of the command was designed to be portable to all shells, csh included.

¹ https://www.debian.org/releases/testing/release-notes/upgrading.en.html#recording-the-session
² https://lists.debian.org/debian-user/2024/02/msg00562.html

[Justin B Rye]

Franco wrote:
> Dear Debian Documentation Project staff,
>
> I want to suggest to add a sentence like the following to the §4.4.1
> "Recording the session" paragraph. ¹ Below the "script" command:
>
> --- BEGIN of the statement ---

I like this idea; but it might work better if we turn things around
and start with the possible problem before offering the solution.

> " If you are comfortable with English language it's strongly
> recommended that you run the following command as soon as you start
> the 'script' session:
> # LC_ALL=C.UTF-8; LANGUAGE=; export LC_ALL LANGUAGE
>
> This will allow you to get command output messages in English into
> the script session. By doing so, it will help you for searching the
> web, during discussions or to submit a bug report."
> --- END of the statement ---

A rephrased version:

If you use a non-English locale during the upgrade, any progress
or error messages are likely to be translated, so in the event of
problems it may be difficult to get assistance from the Internet,
or to submit a bug report. If you are comfortable using English
then it is strongly recommended that you run the following command
at the start of your 'script' session:

# LC_ALL=C.UTF-8; LANGUAGE=; export LC_ALL LANGUAGE

This will give you command output in English.

(Or do we also need to warn users to say "yes" and not "si"?)

> This change it has been discussed on debian-user mailing-list here. ²
> The syntax of the command was designed to be portable to all shells,
> csh included.

I'm sorry, but if you're doing vital root-privileged sysadmin tasks
under csh, things have already gone badly wrong; the instructions in
the Release Notes all assume a Bourne-family shell. For instance, the
immediately preceding line invoking screen with a 2>~/foo redirection*
won't work on csh (tested with bookworm's tcsh).

So I'm not sure there's any point using anything longer than:

# export LC_ALL=C.UTF-8 LANGUAGE=

(But doing it separately from starting "script" does make sense, if
only to give us room for an explanation.)

> ¹ https://www.debian.org/releases/testing/release-notes/upgrading.en.html#recording-the-session
> ² https://lists.debian.org/debian-user/2024/02/msg00562.html

I don't think the Release Notes ever mention the fact that we assume
a Bourne shell, but if you boot into an initrd rescue shell expecting
it to be csh then your day hasn't finished getting worse.

[--just as I was about to hit SEND:--]

> Could I suggest that the syntax of "script" command in the "4.4.1.
> Recording the session" section it should be:
>
> # script -T ~/upgrade-trixie-step.time -a ~/upgrade-trixie-step.script

Ah, yes, avoiding the tricky redirection syntax (worthwhile even if
we don't care about csh). But if we're assuming this is already a
root session, "~/foo" will put that log in /root/; maybe we should
say that instead of using tilde-expansion?
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package

[RL]

Franco <marte...@gmail.com> writes:

> " If you are comfortable with English language it's strongly
> recommended that you run the following command as soon as you start
> the 'script' session:
>
> # LC_ALL=C.UTF-8; LANGUAGE=; export LC_ALL LANGUAGE
>
> This will allow you to get command output messages in English into
> the script session. By doing so, it will help you for searching the
> web, during discussions or to submit a bug report."

Are we *sure* this is a good idea - i have some doubts?

-- "strongly recommended" by who? where did anyone previously make this
recommendation and why do they feel so strongly that it is needed in
2024 when it has not been suggested before?

-- does anyone test the upgrade with this locale setting? telling people
to use something less tested seems like a bad idea.eg, i have
LANG=en_GB.UTF-8 would i still want to change locales?

-- why are we suggesting non-english message are somehow less clear? if
so, we should remove translations not hide them?

-- why are we making the output harder to read for the user - that will
make it harder for them to fix their own issue. isnt this is the
opposite of what we want?

-- isnt it better to say that if you get an error in non-english to
search the web for the english vesion? it's not like you cant look-up
the english version of the error message

-- are we suggesting errors are likely? that isnt my experience with debian
upgrades


(maybe it makes more sense to do this if the upgrade fails and you can't
debug)

[Justin B Rye]

RL wrote:
> Franco <marte...@gmail.com> writes:
>
>> " If you are comfortable with English language it's strongly
>> recommended that you run the following command as soon as you start
>> the 'script' session:
>>
>> # LC_ALL=C.UTF-8; LANGUAGE=; export LC_ALL LANGUAGE
>>
>> This will allow you to get command output messages in English into
>> the script session. By doing so, it will help you for searching the
>> web, during discussions or to submit a bug report."
>
> Are we *sure* this is a good idea - i have some doubts?
>
> -- "strongly recommended" by who? where did anyone previously make this
> recommendation and why do they feel so strongly that it is needed in
> 2024 when it has not been suggested before?

"Strongly" does seem a bit overconfident, but I've frequently seen it
recommended for bug reporting. The fact that nobody's mentioned it in
the specific context of the Release Notes may just mean that nobody's
considered it - compare the way we've just been taking it for granted
the user is running a sensible shell.

> -- does anyone test the upgrade with this locale setting?

What, C.UTF-8? Far more than test it under zh_TW.BIG-5 or whatever
other locale the user might be using. If it fails on POSIX+unicode
we've got real problems.

> telling people to use something less tested seems like a bad
> idea.eg, i have LANG=en_GB.UTF-8 would i still want to change
> locales?

This is one of the reasons I suggested starting with the problem, and
saying "If you use a non-English locale..." (thus implying that it
shouldn't matter for you).

> -- why are we suggesting non-english message are somehow less clear? if
> so, we should remove translations not hide them?

Error messages in Korean or Norwegian or whatever are less likely to
be intelligible to the average Debian developer reading a bug report,
or to the average user reading the appeal for help on the debian-user
mailing list.

> -- why are we making the output harder to read for the user - that will
> make it harder for them to fix their own issue. isnt this is the
> opposite of what we want?

Hence the "If you are comfortable using English..." caveat - I was
hoping to avoid turning it into an explicit list of pros and cons for
them to weigh up, but it's possible it does need some more.

> -- isnt it better to say that if you get an error in non-english to
> search the web for the english vesion? it's not like you cant look-up
> the english version of the error message

No, "better" would be if it was *less* bad! The idea is, if they're
comfortable using English, and they can pick the relevant error out
from its side-effects and the routine status messages (this is often
the tricky bit), we want them to be able to quote what it says, not
just give their best guess.

> -- are we suggesting errors are likely? that isnt my experience with debian
> upgrades

Me too, but if nothing ever goes wrong, it hardly matters what the
Release Notes say...

> (maybe it makes more sense to do this if the upgrade fails and you can't
> debug)

Having a readable screen session makes things *much* easier to debug
on the rare occasions when something does go wrong.

[Hendrik Boom]

On Wed, Feb 21, 2024 at 09:27:45PM +0000, Justin B Rye wrote:
...

>
> Error messages in Korean or Norwegian or whatever are less likely to
> be intelligible to the average Debian developer reading a bug report,
> or to the average user reading the appeal for help on the debian-user
> mailing list.

Or worse! You might not even get to see the messages!

I once had to debug a program whose messages got truncated
in Korean. I did not know any Korean. It turned out that the two-byte
code used for Korean contains a character one of whose bytes is
binary-zero. The program, written in C, was doing the natural thing
and treating it as end of string. I had to replace use of the
C string-manipulation functions with locale-senxitive ones.

-- hendrik

[Justin B Rye]

I've just noticed that we're discussing this on debian-doc without
always Ccing the bug - see
https://lists.debian.org/debian-doc/2024/02/threads.html

Franco Martelli wrote:
>> immediately preceding line invoking screen with a 2>~/foo redirection*
>> won't work on csh (tested with bookworm's tcsh).
>

> Yes, the redirection of only stderr is not allowed in csh but with the new
> "script" command syntax this will be solved:

>
> # script -T ~/upgrade-trixie-step.time -a ~/upgrade-trixie-step.script

(We're imagining italic "variable" markup on "-step")

>> So I'm not sure there's any point using anything longer than:
>>
>> # export LC_ALL=C.UTF-8 LANGUAGE=
>

> Yes, but what's wrong if we have a syntax portable to all shells? If
> available.

What's wrong is that people might use csh! Nobody's been checking the
Release Notes for csh-compatibility, so recipes assume you can say
things like "cd $(mktemp -d)". Who are these people using csh, and
how do we stop them?

(In fact that use of $() is the only other incompatibility I can see
at the moment, but who's going to remember to check each new incoming
recipe next year?)

>> (But doing it separately from starting "script" does make sense, if
>> only to give us room for an explanation.)
>

> Sorry I missed the sense, what explanation?

If we said "LC_ALL=C.UTF-8 LANGUAGE= script -T ..." it would have all
sorts of disadvantages, including the fact that we'd have to explain
all of it together. Much easier to explain about script, then suggest
a "script -T..." commandline, *then* deal with locales separately.

>> I don't think the Release Notes ever mention the fact that we assume
>> a Bourne shell, but if you boot into an initrd rescue shell expecting
>> it to be csh then your day hasn't finished getting worse.
>

> Again, only if available, why don't we use a portable syntax to all shells?

"Portable" in the sense of "POSIX-ish" (including things like ksh or
zsh) makes sense. But the thing we should be recommending to anyone
doing a dist-upgrade under csh or fish or intercal is "please stop".

>> Ah, yes, avoiding the tricky redirection syntax (worthwhile even if
>> we don't care about csh). But if we're assuming this is already a
>> root session, "~/foo" will put that log in /root/; maybe we should
>> say that instead of using tilde-expansion?
>

> I'm for tilde-expansion I find it more elegant and more widespread use for
> referring to the home directory.

The question is, will users realise that they're putting the files in
*root's* home directory, and will they even know where that is?

If we really can't suggest using /var/tmp for this, that seems a pity;
that location *shouldn't* be wiped on reboot, and it's usable whether
you're running "sudo; screen" or "sudo screen" or "screen; sudo".