Merge branch 'formatting' into 'master'

Add brief money formatting note

See merge request documentation/docs/dev!989

docs/framework/formatting.md

+# Formatting utilities
+
+CiviCRM provides a utility class to help with formatting in a locale-aware way.
+
+## Money
+
+Money formatting is done by the [brickmoney](https://github.com/brick/money) library.
+Generally the format is derived from a combination of the currency and
+locale. The `Civi::format` helper class is supported for use in extensions
+to do this formatting. Some examples are:
+
+|Code|Output|
+|---|-------------|
+|`Civi::format()->money('10', 'USD', 'it_IT')` |10,00 USD|
+|`Civi::format()->money('10', 'USD', 'fr_CA')`| 10,00 $ US |
+|`Civi::format()->money('10', 'USD', 'en_CA')`| US$10.00|
+|`Civi::format()->money('10', 'CAD', 'en_CA')`| $10.00 (note no currency identifier)|
+
+If no locale is provided then the fallback will use the setting
+`format_locale` from 5.47 onwards, if set and if not then the site
+language. Note that if the site is in (for example) New Zealand and is
+using 'English (United States)' as the language it is probably important
+to set the `format_locale` to 'English (New Zealand)' or it will
+think that NZD transactions need the currency to be output to
+disambiguate the currency.
+
+![Money settings](../img/money_settings.png)
+
+Note that if `format_locale` is set then the brick money is
+'in charge' of determining format and other currency localisation settings
+(thousandSeparator, decimalSeparator) are ignored. There is also a
+setting `moneyFormat` ('Monetary Amount Display') which is only respected by the legacy `CRM_Utils_Money::format`
+method, which is being phased out.
+

mkdocs.yml

@@ -326,6 +326,7 @@ nav:
     - XML Schema definition: framework/database/schema-definition.md
     - Schema Design: framework/database/schema-design.md
     - Transaction Reference: framework/database/transactions.md
+  - Formatting: framework/formatting.md
   - File System: framework/filesystem.md
   - OAuth Reference: framework/oauth.md
   - Pipe Reference: framework/pipe.md