From: Junio C Hamano <gitster@pobox.com>
To: "Krzysztof Żelechowski" <giecrilj@stegny.2a.pl>
Cc: Christopher Yeleighton via GitGitGadget <gitgitgadget@gmail.com>,
git@vger.kernel.org, Bagas Sanjaya <bagasdotme@gmail.com>,
Christopher Yeleighton <ne01026@shark.2a.pl>
Subject: Re: [PATCH v2] pretty-options.txt: describe supported encoding
Date: Fri, 27 Aug 2021 10:03:56 -0700 [thread overview]
Message-ID: <xmqq5yvqbz0j.fsf@gitster.g> (raw)
In-Reply-To: <2247912.lYO0ccLKhl@localhost.localdomain> ("Krzysztof Żelechowski"'s message of "Fri, 27 Aug 2021 13:51:34 +0200")
Krzysztof Żelechowski <giecrilj@stegny.2a.pl> writes:
> git log recognises only system encodings supported by iconv(1), but not
> POSIX character maps used by iconv(1p). Document it.
>
> Signed-off-by: <ne01026@shark.2a.pl>
The "Human Readable Name <email@add.re.ss>" on this line must match
the one on the "From: " line that records the author of the patch.
If you are forwarding somebody else's patch (with or without
improvement), we also need your sign off.
> diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-
> options.txt
> index 27ddaf84a19..4f8376d681b 100644
> --- a/Documentation/pretty-options.txt
> +++ b/Documentation/pretty-options.txt
> @@ -36,9 +36,13 @@ people using 80-column terminals.
> The commit objects record the encoding used for the log message
> in their encoding header; this option can be used to tell the
> command to re-code the commit log message in the encoding
> - preferred by the user. For non plumbing commands this
> - defaults to UTF-8. Note that if an object claims to be encoded
> - in `X` and we are outputting in `X`, we will output the object
> + preferred by the user.
> + The encoding must be a system encoding supported by iconv(1),
> + otherwise this option will be ignored.
> + POSIX character maps used by iconv(1p) are not supported.
This paragraph is a bit hard to grok.
I think it is saying that the "-f frommap -t tomap" form in [*1*]
that can use arbitrary character set description file is not
supported, but "-f fromcode -t tocode" form, which also is what
iconv_open() takes [*2*], is supported. Am I reading it correctly?
Is there an easier-to-read way to explain the distinction to our
average reader?
What I am getting at is this. Imagine average users who need to see
their commits recoded to iso-8859-2. They see "git log" has
"--encoding=<encoding>" option, read the above paragraph and wonder
if they are on the supported side or unsupported side of the above
paragraph. I want to make it easy for them to stop wondering.
For that purpose, "iconv(1) vs iconv(1p)" would not help them very
much, especially considering that not all Git users are UNIX users
(they probably do not even know what (1) and (1p) means).
> + For non-plumbing commands this defaults to UTF-8.
I think I can guess why the patch wants to change "non plumbing" to
"non-plumbing" (I do not strongly care either way, so I'd take the
patch without complaint about that particular change). It would
have been nicer to mention this change in the proposed commit log
message, though, but that is minor.
> + Note that if an object claims to be encoded in `X`
> + and we are outputting in `X`, we shall output the object
> verbatim; this means that invalid sequences in the original
> commit may be copied to the output.
I probably wouldn't have noticed this if a new manual page used
"shall" consistently, but since the original deliberately used
"will" and the patch changes it to "shall", I have to ask: why?
I think our end-user facing manual pages tend to avoid the latter.
We do use "shall" in the RFC2119/BCP14 sense on the technical side
of our documentation where we give requirements to the third-party
implementations so that they can interoperate with us, but this is
not such a description.
Thanks.
[References]
*1* https://pubs.opengroup.org/onlinepubs/9699919799/utilities/iconv.html
*2* https://pubs.opengroup.org/onlinepubs/9699919799/functions/iconv_open.html
next prev parent reply other threads:[~2021-08-27 17:05 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-08-26 21:34 [PATCH] pretty-options.txt: describe supported encoding Christopher Yeleighton via GitGitGadget
2021-08-27 10:46 ` Bagas Sanjaya
2021-08-27 11:47 ` Krzysztof Żelechowski
2021-08-27 11:51 ` [PATCH v2] " Krzysztof Żelechowski
2021-08-27 17:03 ` Junio C Hamano [this message]
2021-08-27 18:03 ` Jeff King
2021-08-27 23:20 ` Krzysztof Żelechowski
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqq5yvqbz0j.fsf@gitster.g \
--to=gitster@pobox.com \
--cc=bagasdotme@gmail.com \
--cc=giecrilj@stegny.2a.pl \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=ne01026@shark.2a.pl \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).