RFR: 8271186: Add UL option to replace newline char [v4]

[David Holmes]

On Tue, 24 Aug 2021 18:10:51 GMT, Ioi Lam <iklam at openjdk.org> wrote:

>> Yasumasa Suenaga has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains seven additional commits since the last revision:
>> 
>>  - Update UL help message and manpage
>>  - Merge remote-tracking branch 'upstream/master' into JDK-8271186
>>  - Fix test on Windows
>>  - Implement as foldmultilines
>>  - Merge remote-tracking branch 'upstream/master' into JDK-8271186
>>  - add inclusion of os.hpp
>>  - 8271186: Add UL option to replace newline char
>
> src/hotspot/share/logging/logConfiguration.cpp line 577:
> 
>> 575:                                          " Escape newline (\\n) and backslash (\\) characters in the UL output"
>> 576:                                          " if it is set to true."
>> 577:                                          " Note that it works on file output only.");
> 
> How about this message?
> 
> 
> out->print_cr("   foldmultilines=.. - If set to true, a log event that consists of multiple lines"
>                                        " will be folded into a single line by escaping"
>                                        " the newline (\\n) and backslash (\) characters"
>                                        " in the output.")
> 
> I think there's no need to say "it works on file output only" because this is under the heading of "Additional output-options for file outputs".

We are not "escaping" newline characters here. We went through great pains in the CSR request to describe the actual process accurately. We are replacing newlines with the sequence `` and `n`. We also have to replace `` with the sequence `\` so that the conversion can be reversed by a parser. Saying all this in the help output is awkward but necessary. We also need to warn that this may not be safe with character encodings other than UTF-8. So something like:

`If set to true, a log event that consists of multiple lines will be folded into a single line by replacing newline characters with the sequence '' and 'n' in the output. Existing single backslash characters will also be replaced with a sequence of two backslashes so that the conversion can be reversed. This option is safe to use with UTF-8 character encodings, but other encodings may not work.`

> src/java.base/share/man/java.1 line 4427:
> 
>> 4425: \f[I]foldmultilines\f[R] enables to replace newline characters within
>> 4426: a multiline log event with the character sequence '\\' and 'n'.
>> 4427: Note that it works on file output only.
> 
> How about:
> 
>> When foldmultilines is true, a log event that consists of multiple lines will be folded into a single line by escaping the newline (\\n) and backslash (\) characters in the output. This option is available only for file outputs.

This needs to be expanded similar to the help info. But you can elaborate on the character encoding limitation as per the CSR request.

-------------

PR: https://git.openjdk.java.net/jdk/pull/4885