[Lazarus] Beyond Compare 4 built with Lazarus 1.2

[Jürgen Hestermann]

Am 2013-12-28 14:01, schrieb Michael Van Canneyt:
 > As it happens, I am preparing the documentation for 2.6.4, and I checked: the bug is fixed.
 > So the bug should be fixed on the website one of the next days.
 > Now, I realize that the strings issue is rather messy, Delphi
 > engineers really messed it up.
 > Following your message, I looked up Delphi's docus:
 > http://docwiki.embarcadero.com/Libraries/XE5/en/System.SysUtils.FindFirst
 > No mention of encoding either.
 > I am looking for a way to make sure that when the unicode version is made,
 > the documentation will make clear what 'string' means if it appears somewhere in a declaration.
 > You can help by making suggestions. Anything that does not require me going over all functions that require string arguments is good :)

I always stumble over encodings and the documentation is of no help.
Another example I found recently:

I wanted to display error messages and
found that SysErrorMessage should give me what I want.
It is said to be "cross platform", so I thought the encoding
is the same (UTF8) as for all other "cross platform"
functions (otherwise why is it called "cross platform"?).
But only by accident I found out that the encoding cannot be UTF8
because it did not display all characters correctly (which only
becomes apparent when german umlauts appear so it could go wrong for a long
time until it this bug is discovered because errors should not happen very often
and even if they appear not all contain umlauts).
So I took a look into the documentation to find out about the encoding:

http://lazarus-ccr.sourceforge.net/docs/rtl/sysutils/syserrormessage.html

There it says:

---------------------
function SysErrorMessage(
   ErrorCode: Integer
):;
SysErrorMessage returns a string that describes the operating system error code ErrorCode.
---------------------

Yet another documentation bug?
What kind of string is given back?
But even if it would say "string" it would  be of no use for me.
Which encoding?
How should a user find out what he has to do in his program
to display a correct string in a ShowMessage() or whatever?
This is a real mess.
Actually I found out by trial and error that

       ShowMessage(Trim(SysToUTF8(SysErrorMessage(GetLastError))));

is required to get a correct string (Trim is needed because trailing spaces and tabs may appear).

I would expect that for all these functions where stings are involved at least a link
to the encoding is added that tells the user that he will get back an
AnsiString with System-ANSI-encoding (or whatever he will get back on other OS's).
How else should a user find out about this?