Re: [libreoffice-l10n] Change in the documentation of the Format function (LO BASIC)
Hi Sophie, Thanks for relaying my question, Alain's explanation clarifies the matter. I didn't consider that parameter names can be used as keywords in Basic. This would also mean that in contrast to parameter names of Calc functions, parameter names for Basic functions should not be translated. Cheers, Mihail On Wed, May 12, 2021 at 7:04 PM sophi wrote: > Hi Mihail, > > Alain asked me to post this answer he was not able to send via Nabble: > > Hi Mihail, > > The rationale behind this change is detailed in > https://bugs.documentfoundation.org/show_bug.cgi?id=141474 which I > invite you to read thoroughly > > VBA Format help doc - > > https://docs.microsoft.com/en-us/office/vba/language/reference/user-interface-help/format-function-visual-basic-for-applications > > Your recommendations for an increased expressiveness of parameter names > are highly valid. However libO Basic keyword names support - aka VBA > named arguments - combined with LibO Basic compatibility with VBA > prevents from changing parameter names to the extent you suggest. > > In the case of 'Format function', this leads to insert 'expression' and > 'format' as "compulsory" parameter names as well as introducing multiple > occurrences of literals in the help page. > > In order to better describe what 'Numeric expression' stands for, it is > possible to provide extra Basic scripts that'll illustrate this > terminology. > Besides, description improvements for parameters are more than welcome! > > Alain > > PS: One may expect more Basic functions page updates intended to reflect > 'exact' keyword names. > > > Cheers > Sophie > Le 07/05/2021 à 08:07, Mihail Balabanov a écrit : > > Hello, > > > > I noticed that in documentation of the Format function, the name of the > > first parameter had been changed from "Number" to "expression". (Starts > > around > > > https://translations.documentfoundation.org/translate/libo_help-master/textsbasicshared/bg/?checksum=b7bf473e14ccdc22 > , > > tens of strings are affected). > > > > Why this change? The Format function does not convert an *expression* to > a > > string, it actually does convert a *number*; Format (1 + 2 + 3) returns > > "6", not "1 + 2 + 3". It does not care about how the number is produced > > before being passed to it. The next segments mention things like "if > > *expression* contains a digit in this position" and "where *expression* > > appears in the *format* code" which do not make sense; the thing that > > contains a digit at position X to be formatted is the *number* produced > by > > the expression and being formatted by the function; the expression itself > > cannot appear anywhere in the format code. > > > > If we mean this naming to convey the idea that any argument to any > function > > call may be the result of an expression nested in the call, we should > > change all arguments of all functions to read "numeric_expression", > > "start_date_expression", "format_code_expression", etc. It appears to me > > that a better solution would be to have a general explanation about > nesting > > expressions on an introductory page about programming in Basic. > > > > If the reader is unfamiliar with basic programming concepts, either name > > may confuse them: "number" may be misunderstood to mean only literal > > numbers (1, 7.68, .78E5) and "expression" may be misunderstood to mean > that > > the function actually formats expressions. If the reader is familiar with > > nesting expressions in function calls, they would expect the parameter > name > > to denote the role of the respective value in the calculation, not the > way > > it may be produced before passing it to the function. > > > > As a quick fix, maybe changing the parameter to something like > > "numericvalue" (following the latest convention of "all lowercase, no > > spaces/underscores" for the parameter names) would be slightly better > than > > both "number" and "expression"? > > > > Best regards, > > Mihail > > > > > -- > Sophie Gautier so...@libreoffice.org > GSM: +33683901545 > IRC: sophi > Foundation coordinator > The Document Foundation > > -- > To unsubscribe e-mail to: l10n+unsubscr...@global.libreoffice.org > Problems? > https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ > Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette > List archive: https://listarchives.libreoffice.org/global/l10n/ > Privacy Policy: https://www.documentfoundation.org/privacy > -- To unsubscribe e-mail to: l10n+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/l10n/ Privacy Policy: https://www.documentfoundation.org/privacy
Re: [libreoffice-l10n] Change in the documentation of the Format function (LO BASIC)
Hi Mihail, Alain asked me to post this answer he was not able to send via Nabble: Hi Mihail, The rationale behind this change is detailed in https://bugs.documentfoundation.org/show_bug.cgi?id=141474 which I invite you to read thoroughly VBA Format help doc - https://docs.microsoft.com/en-us/office/vba/language/reference/user-interface-help/format-function-visual-basic-for-applications Your recommendations for an increased expressiveness of parameter names are highly valid. However libO Basic keyword names support - aka VBA named arguments - combined with LibO Basic compatibility with VBA prevents from changing parameter names to the extent you suggest. In the case of 'Format function', this leads to insert 'expression' and 'format' as "compulsory" parameter names as well as introducing multiple occurrences of literals in the help page. In order to better describe what 'Numeric expression' stands for, it is possible to provide extra Basic scripts that'll illustrate this terminology. Besides, description improvements for parameters are more than welcome! Alain PS: One may expect more Basic functions page updates intended to reflect 'exact' keyword names. Cheers Sophie Le 07/05/2021 à 08:07, Mihail Balabanov a écrit : > Hello, > > I noticed that in documentation of the Format function, the name of the > first parameter had been changed from "Number" to "expression". (Starts > around > https://translations.documentfoundation.org/translate/libo_help-master/textsbasicshared/bg/?checksum=b7bf473e14ccdc22, > tens of strings are affected). > > Why this change? The Format function does not convert an *expression* to a > string, it actually does convert a *number*; Format (1 + 2 + 3) returns > "6", not "1 + 2 + 3". It does not care about how the number is produced > before being passed to it. The next segments mention things like "if > *expression* contains a digit in this position" and "where *expression* > appears in the *format* code" which do not make sense; the thing that > contains a digit at position X to be formatted is the *number* produced by > the expression and being formatted by the function; the expression itself > cannot appear anywhere in the format code. > > If we mean this naming to convey the idea that any argument to any function > call may be the result of an expression nested in the call, we should > change all arguments of all functions to read "numeric_expression", > "start_date_expression", "format_code_expression", etc. It appears to me > that a better solution would be to have a general explanation about nesting > expressions on an introductory page about programming in Basic. > > If the reader is unfamiliar with basic programming concepts, either name > may confuse them: "number" may be misunderstood to mean only literal > numbers (1, 7.68, .78E5) and "expression" may be misunderstood to mean that > the function actually formats expressions. If the reader is familiar with > nesting expressions in function calls, they would expect the parameter name > to denote the role of the respective value in the calculation, not the way > it may be produced before passing it to the function. > > As a quick fix, maybe changing the parameter to something like > "numericvalue" (following the latest convention of "all lowercase, no > spaces/underscores" for the parameter names) would be slightly better than > both "number" and "expression"? > > Best regards, > Mihail > -- Sophie Gautier so...@libreoffice.org GSM: +33683901545 IRC: sophi Foundation coordinator The Document Foundation -- To unsubscribe e-mail to: l10n+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/l10n/ Privacy Policy: https://www.documentfoundation.org/privacy
Fwd: [libreoffice-l10n] Change in the documentation of the Format function (LO BASIC)
Hi all, Could you give some inputs on these changes to Mihail. Please keep the l10n list in copy as most of the translators are not subscribed to this list. Thanks a lot! Cheers Sophie Message transféré Sujet : [libreoffice-l10n] Change in the documentation of the Format function (LO BASIC) Date : Fri, 7 May 2021 09:07:33 +0300 De : Mihail Balabanov Pour : LibreOffice-l10n Hello, I noticed that in documentation of the Format function, the name of the first parameter had been changed from "Number" to "expression". (Starts around https://translations.documentfoundation.org/translate/libo_help-master/textsbasicshared/bg/?checksum=b7bf473e14ccdc22, tens of strings are affected). Why this change? The Format function does not convert an *expression* to a string, it actually does convert a *number*; Format (1 + 2 + 3) returns "6", not "1 + 2 + 3". It does not care about how the number is produced before being passed to it. The next segments mention things like "if *expression* contains a digit in this position" and "where *expression* appears in the *format* code" which do not make sense; the thing that contains a digit at position X to be formatted is the *number* produced by the expression and being formatted by the function; the expression itself cannot appear anywhere in the format code. If we mean this naming to convey the idea that any argument to any function call may be the result of an expression nested in the call, we should change all arguments of all functions to read "numeric_expression", "start_date_expression", "format_code_expression", etc. It appears to me that a better solution would be to have a general explanation about nesting expressions on an introductory page about programming in Basic. If the reader is unfamiliar with basic programming concepts, either name may confuse them: "number" may be misunderstood to mean only literal numbers (1, 7.68, .78E5) and "expression" may be misunderstood to mean that the function actually formats expressions. If the reader is familiar with nesting expressions in function calls, they would expect the parameter name to denote the role of the respective value in the calculation, not the way it may be produced before passing it to the function. As a quick fix, maybe changing the parameter to something like "numericvalue" (following the latest convention of "all lowercase, no spaces/underscores" for the parameter names) would be slightly better than both "number" and "expression"? Best regards, Mihail -- To unsubscribe e-mail to: l10n+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/l10n/ Privacy Policy: https://www.documentfoundation.org/privacy -- To unsubscribe e-mail to: l10n+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/l10n/ Privacy Policy: https://www.documentfoundation.org/privacy
[libreoffice-l10n] Change in the documentation of the Format function (LO BASIC)
Hello, I noticed that in documentation of the Format function, the name of the first parameter had been changed from "Number" to "expression". (Starts around https://translations.documentfoundation.org/translate/libo_help-master/textsbasicshared/bg/?checksum=b7bf473e14ccdc22, tens of strings are affected). Why this change? The Format function does not convert an *expression* to a string, it actually does convert a *number*; Format (1 + 2 + 3) returns "6", not "1 + 2 + 3". It does not care about how the number is produced before being passed to it. The next segments mention things like "if *expression* contains a digit in this position" and "where *expression* appears in the *format* code" which do not make sense; the thing that contains a digit at position X to be formatted is the *number* produced by the expression and being formatted by the function; the expression itself cannot appear anywhere in the format code. If we mean this naming to convey the idea that any argument to any function call may be the result of an expression nested in the call, we should change all arguments of all functions to read "numeric_expression", "start_date_expression", "format_code_expression", etc. It appears to me that a better solution would be to have a general explanation about nesting expressions on an introductory page about programming in Basic. If the reader is unfamiliar with basic programming concepts, either name may confuse them: "number" may be misunderstood to mean only literal numbers (1, 7.68, .78E5) and "expression" may be misunderstood to mean that the function actually formats expressions. If the reader is familiar with nesting expressions in function calls, they would expect the parameter name to denote the role of the respective value in the calculation, not the way it may be produced before passing it to the function. As a quick fix, maybe changing the parameter to something like "numericvalue" (following the latest convention of "all lowercase, no spaces/underscores" for the parameter names) would be slightly better than both "number" and "expression"? Best regards, Mihail -- To unsubscribe e-mail to: l10n+unsubscr...@global.libreoffice.org Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette List archive: https://listarchives.libreoffice.org/global/l10n/ Privacy Policy: https://www.documentfoundation.org/privacy