Merge branch '5.0' into 5.0-add-js-removals-to-44-50-removed-backward-incompatibility.md

Author: richard67

docs/common-errors/index.md

@@ -8,12 +8,12 @@ Some frequently asked questions on Error messages and how to resolve them.
 
 As a developer you somtimes will be stuck in your code. 
 If it happens to you, also have a look on https://joomla.stackexchange.com/ - a huge collection of valuable knowledge. 
-Here we collect some frequently aske questions. 
+Here we collect some frequently asked questions. 
 
 Class [..] not found
 --------------------
 
-You need to understand the namespace concept as described in sction General Concepts (work in progress)
+You need to understand the namespace concept as described in section General Concepts (work in progress)
 Then check:
 - Is the namespace defined in your manifest file? 
 - Has every class in your extension the correct namespace?

docs/user-interface-text/A-Z.md

@@ -0,0 +1,136 @@
+---
+sidebar_position: 2
+---
+
+## 'a' or 'an' before H?
+* Use 'an' before a silent H: an heir, an hour
+* Use 'a' before an aspirated H: a hero, a hotel, a historian
+* With abbreviations, be guided by pronunciation: eg an HTML document
+
+## Abbreviations and acronyms
+* The first time you use an abbreviation or acronym explain it in full on each page then refer to it by initials unless it's well known, eg HTML, CSS etc.
+* If you think your acronym is well known, please provide evidence that 80% of the UK population will understand, and commonly use, the term. Evidence can be from search analytics or testing of a representative sample.
+* Don't use full stops in abbreviations – BBC, not B.B.C.
+* Use all capitals if an abbreviation is pronounced as the individual letters (an initialism): HTML, CSS
+* If it is an acronym (pronounced as a word) spell out with initial capital, eg Nasa, Nato, Unicef, unless it can be considered to have entered the language as an everyday word, such as laser and sim card.
+* Note that pdf is lowercase.
+
+## Accents
+* Use on French, German, Portuguese, Spanish and Irish Gaelic words (but not anglicised French words such as cafe, apart from exposé, lamé, résumé, roué).
+
+## Americanisms
+* Don't use Americanisms. You 'fill in' a form, not 'fill out' a form.
+* Exceptions include where it's part of a specific name, eg '4th Mechanized Brigade'.
+* Use the 'ise' rather than 'ize' suffix, eg organise not organize (this isn't actually an Americanism but is often seen as such).
+
+## Amounts
+See numbers
+
+## Check
+See select.
+
+## Colour codes
+Hex colours are case insensitive so it doesnt matter if we use upper or lowercase. However we should be consistent in our usage. As the color selector fields uses lowercase then the text should also user lowercase for consistency.
+
+## Contractions
+Use contractions sparingly eg can't. Avoid using you'll, you've, should've, could've, would've etc – these are hard to read.
+
+## Dates
+* use upper case for months eg January, February
+* don't use a comma between the month and year, eg 14 June 2012
+* when space is an issue, eg tables, publication titles etc, you can use truncated months, eg Jan, Feb, Mar
+* use 'to' in date ranges – not hyphens, en rules or em dashes. For example: copyright year 2011 to 2012
+* Monday to Friday, 9am to 5pm (put different days on a new line, don't separate with a comma etc)
+* 10 November to 21 December
+* don't use 'quarter' for dates; use the months, for example: 'expenses, Jan to Mar 2013'
+* when referring to 'today' (eg in a news article) make sure you include the date as well eg 'The minister announced today (14 June 2012) that…'
+
+## Email and Email Address
+Email should refer to the item that you send
+Email address should be used if referring to their actual address
+
+Example
+* Enter an email address for the user.
+* Select which mailer for the delivery of site email.
+
+## File Size display:
+* If less than 1 KB, display <1 KB
+* 1 KB to 1,023 KB, display 357 KB
+* 1 MB to 1,047 MB, display 2.5MB (only one decimal place)
+* 1 GB+, display 3.8 GB (only one decimal place)
+
+## Geography and regions
+Use lower case for north, south, east and west, except when they're part of a name or recognised region. So, 'the south-west' (compass direction), but 'the South West' (administrative region).
+Use lower case for: the north, the south of England, the south-west, north-east Scotland, south Wales, the west, western Europe, the far east, south-east Asia.
+Use upper case for: East End, West End (London), Middle East, Central America, South America, Latin America.
+
+## Maths
+* Use a minus sign for negative numbers with no space: –6
+* Ratios have no space either side of the colon: 5:12
+* One space each side of symbols: +, –, ×, ÷ and = (eg 2 + 2 = 4)
+* Use the minus sign for subtraction not the dash.
+* Use the correct symbol for the multiplication sign (×), not the letter x. (&times; or &#215;)
+
+## Measurements
+* Use lower case for all measurements eg px, em, w and h
+* Use the metric system for mass and non-web measurements eg kg, cm and m
+* Use celcius for temperature eg 34c
+* For all other measurements use SI
+
+## Money
+* Use the £ symbol with no space: – £75.
+* Don't use decimals unless pence are included, for example use: £75.50 but not £75.00.
+* Don't use '£0.xx million' for amounts less than £1 million.
+* Write out 'pence' in full eg 'calls will cost 4 pence per minute from a landline'.
+* Currencies are lowercase.
+
+## Multi-factor Authentication
+Always use the hyphenated word. Multi-factor must always be a single hyphenated word and only the complete words should be capitalised.
+
+## Numbers
+(I have changed this based on the NNG findings (http://www.nngroup.com/articles/web-writing-show-numbers-as-numerals/))
+* Write numbers with digits, not letters (23, not twenty-three).
+* Use numerals even when the number is the first word in a sentence or bullet point.
+* Use numerals for big numbers up to one billon. As a compromise, you can often use numerals for the significant digits and write out the magnitude as a word. For example, write 24 billion.
+* "Enter the **number** of hits to increase the counter by."
+* "Limit the **amount** of text to display"
+
+## Seasons
+Try to avoid using them as they are not global. spring, summer, autumn, winter are lowercase.
+
+## Select
+Select a check box item not check a check box item.
+
+## Sentence length
+Don't use long sentences – check any sentences with more than 25 words to see if you can split them to make them clearer.
+
+## Singular and Plural
+In general a string with a constant of ARTICLE_PUBLISHED_1 should have a value of "Article published." and not "1 Article ...
+
+## Times
+* use 'to' in time ranges – not hyphens, en rules or em dashes, eg 10am to 11am (not 10–11am)
+* 5:30pm (not 1730hrs)
+* midnight, not 00:00
+* midday, not 12 noon, noon or 12pm
+
+## Titles
+Titles should:
+* be no longer than 65 characters
+* be unique, clear and descriptive
+* be front-loaded and optimised for search
+* use a colon to break up longer titles
+* not have a full stop at the end
+* not use acronyms unless they are well-known eg HTML
+
+## Tooltips
+Tooltips should:
+* be as short as possible
+* end with a full stop
+* not repeat the title or body text
+* be clear and specific
+
+## Trademarked Name
+This should always be written with a capital letter unless the trademark is for lowercase eg iPhone.
+
+## Two Factor Authentication
+This should not be used. See Multi-factor Authentication.

docs/user-interface-text/action_or_description.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 2
+---
+
+# Action or Description
+## Archive / Unarchive Vs Archived / Unarchived
+Archive is an action so it is used on buttons
+Unarchive is an action so it is used on buttons
+Archived is a description so it is used in filters and selects
+Unarchived is a description so it is used in filters and selects
+
+## Check in, Check out
+Check-in is hyphenated when it’s a noun eg  I was early for check-in
+Check in is two words when it's a verb eg I walked up to the counter to check in
+Checkout is one word when it's a noun eg you wait in the checkout line
+Check out is two words when it's a verb eg you are ready to check out of the hotel
+
+## Feature / Unfeature Vs Featured / Unfeatured
+Feature is an action so it is used on buttons
+Unfeature is an action so it is used on buttons
+Featured is a description so it is used in filters and selects
+Unfeatured is a description so it is used in filters and selects
+
+## Log in, Log out
+Login is one word (not hyphenated) when it's a noun eg go to the login page
+Log in is two words when it's a verb eg you log in with your username
+Logout is one word (not hyphenated) when it's a noun eg select the logout menu
+Log out is two words when it's a verb eg you log out by clicking on the button
+
+## Logged-in
+When counting the number of users we are counting those who are logged-in not logged in.
+
+## Publish / Unpublish Vs Published / Unpublished
+Publish is an action so it is used on buttons
+Unpublish is an action so it is used on buttons
+Published is a description so it is used in filters and selects
+Unpublished is a description so it is used in filters and selects
+
+## Trash Vs Trashed
+Trash is an action so it is used on buttons
+Trashed is a description so it is used in filters and selects

docs/user-interface-text/capitalisation.md

@@ -0,0 +1,18 @@
+---
+sidebar_position: 3
+---
+
+# Capitalisation
+DON'T USE BLOCK CAPITALS FOR LARGE AMOUNTS OF TEXT AS IT'S QUITE HARD TO READ.
+
+Sentence case is preferable but use capitalisation for:
+
+* Menu Items
+* Labels
+* Buttons
+
+Do not capitalise joining words and words of three characters or less such as and, to, for.
+
+## Examples
+* Show Intro Text
+* Position of Article Info

docs/user-interface-text/index.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 999
+---
+
+# User Interface Text Guidelines
+The official language of Joomla is en-GB and this guide is intended to assist anyone writing language strings in en-GB (British English). This guide should not be translated but may help serve as a starting point for Translation Teams to localise and produce their own guide.
+
+## Purpose
+* Establish official style guidelines for writing en-GB strings.
+* Ensure consistency throughout Joomla.
+* Traditional rules of grammar do not always apply to the web. See [Break Grammar Rules on Websites for Clarity](http://www.nngroup.com/articles/break-grammar-rules/).
+* See [NNG on American vs British english for the web](http://www.nngroup.com/articles/american-vs-british-english-for-web/).
+
+## Target audience
+* Primary: Developers writing en-GB strings.
+* Secondary: Translation teams.
+
+## Uses
+* Primary: Basis for all en-GB strings.
+* Secondary: Assist non native en-GB developers writing language strings in en-GB.
+* Tertiary: Provide guidelines for translation teams to localise.
+
+## Notes
+### Avoid over-communication
+Be explicit wherever necessary but don't explain the obvious. On the web scanning is the norm and too much text weakens the effectiveness of the message - it does not enhance it.

docs/user-interface-text/joomla_name_usage.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 4
+---
+
+# Use of the Joomla Name
+"Joomla!" is our name, and as such it deserves everyone's best efforts to protect it.  It defines our brand for both our software and our community.  It signifies our reputation for excellence.  We have specific guidelines for when and how to properly use our trademarks in public-facing content such as marketing materials and Joomla.org web pages.  Those guidelines are excessive within a controlled user-facing environment like the Joomla backend.
+
+## "Joomla!" should always be capitalised ... ALWAYS
+Our project's name is a proper name.  Please always capitalise the "J" of Joomla.
+
+## When to bang your Joomla "!"
+Our registered trademark is "Joomla!" including the exclamation point.  (The exclamation point is sometimes also called a "bang" from both copy editing and comic book usage.)  The proper and complete use of our name is with the exclamation point.  But, there are many circumstances where including punctuation that also signifies the end of a sentence makes a passage of text difficult to read or confusing.  Also, punctuation is not allowed in certain contexts such as aliases and URL's.  To clarify when to use the exclamation point, here are simple rules <b>applicable only to Joomla CMS language strings.</b>
+
+### Rule: No Bang!
+References to Joomla in language strings should not include the exclamation point unless it is at the end of a sentence that is intended to be exclamatory.
+
+#### Rule of thumb
+Whenever you can substitute "your Joomla CMS" in place of "Joomla" and still make sense, then it's descriptive and no bang needed.
+
+### Exception to the Rule:  Trademarks that contain Joomla
+Whenever the Joomla name is part of or nested inside another multi-word Joomla-related trademark or service mark then the exclamation point should be used even though it is mid-sentence.  If the use is a proper name it should have capitalised initials, Joomla should include the exclamation point and it should be followed by a TM indicia.
+Examples:  References to the Joomla! Extensions Directory&trade;, the Joomla! Framework&trade; or Joomla! 3.4 as a product.
+
+---------
+
+## When to Include Trademark Indicia ( <sup>&reg;</sup> or &trade; )
+
+### Rule: Do not use &reg; in language strings
+Part of protecting a trademark, whether registered or not, is giving notice to viewers that we consider the mark to be our property.  Considering the Joomla! trademark itself, since all backend users must login and will see the Joomla signature and registered trademark indicia on the login module, there is no need to include a registered mark indicia (&reg;) anywhere else in the backend.
+
+### Rule:  Always use &trade; following other Joomla-related trademarks
+With other Joomla-related trademarks or service marks, such as a reference to the Joomla! Extensions Directory&trade;, the proper indicia to use is the TM indicia (&trade;) at the end of the entire mark.  Notice the exclamation point is included and the registered indicia (&reg;) normally used with Joomla standing alone, is removed. The &trade; indicia should be used with any reference to a Joomla product or service other than a release of Joomla itself (such as Joomla! 3.4)
+
+These other trademarks are not registered.  Nevertheless, they are protectable trademarks and service marks.  A superscript circle-R should <em>NOT</em> be used with them; instead a superscript TM should be used.  Because these are unregistered trademarks, extra care is needed to use them consistently on order to emphasize and retain their trademark status. The registration and broader recognition of the main Joomla! wordmark is the reason why we have more flexibility with the Joomla name being used without the exclamation point and as a noun in descriptive context than we do with these other Joomla-related product and service marks.
+
+----------
+
+## Summary
+* Refer to Joomla in general without the exclamation point.
+* Refer to a specific product release or series as "Joomla! 3" or "Joomla! 3.4" (with an exclamation point.)
+* Refer to the JED as Joomla! Extensions Directory&trade; (with exclamation point and TM indicia.)
+
+--------------
+
+## HTML Codes
+For consistent display across fonts, use the html codes for copyright and trademark symbols or indicia.  For proper display, wrapping with a superscript `<sup>` tag is necessary for positioning the &reg; indicia.  It is not needed for the &copy; or &trade; indicia.
+
+* &reg; - for a registered trademark indicia use `<sup>&reg;</sup>`
+* &trade; - for a trademark indicia use `&trade;`
+* &copy; - for a copyright indicia use  `&copy;`
+
+Provenance:  This page was written by Marc Antoine Thevenet and Duke Speer on behalf of the Trademark Team.

docs/user-interface-text/punctuation.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 5
+---
+
+# Punctuation
+## Ampersand
+Unless in a title or referring to a title use 'and' rather than an '&', unless it's part of a trademark. Where it is used then it should be `&` and not `&`
+
+## Apostrophes
+Used to indicate a missing letter or letters (can't, we'd) or a possessive (David's book).
+
+## Brackets
+Use (round brackets), not [square brackets]. The only acceptable use for square brackets is to indicate that it is a placeholder eg [name] is replaced with the real name.
+
+## Bullet points (ul) and numbered steps (ol)
+You can use bullet points to make text easier to read. Make sure that:
+
+* you always use an introductory line
+* the bullets make sense running on from the lead-in line
+* you use lower case at the start of the bullet
+* you don't use more than one sentence per bullet point – use commas, dashes or semicolons to expand on an item
+* you don't put 'or', 'and' after the bullets
+* if you add links they appear within the text and not as the whole bullet
+* there is no full stop after the last bullet point
+
+Use numbered steps instead of bullet points to guide a user through a process. You don't need an introductory line and you can use links and downloads (with appropriate markup) in steps. Each step ends in a full stop because each step should be a complete sentence.
+
+## eg, etc and ie
+Don't use full stops after or between these notations.
+User testing has shown that some people are not familiar with abbreviations such as eg, so consider your audience before abbreviating.
+
+## Ellipsis
+An ellipsis a special character that resembles a set of three periods ( ... ) indicating an omission. In html this is represented by &hellip. There should be a single space on either side. Unless it is at the end of a string where there is no space or period after.
+Example
+* Read more ...
+* Create some text ... add some pictures.
+
+## etc
+* See eg, etc and ie
+
+## full stop
+* See period
+
+## Hyphenation
+Hyphenate:
+* 're-' words only if they start with 'e', eg re-evaluate
+* co-ordinate
+* co-operate
+
+Don't hyphenate:
+* email
+* reuse
+* reinvent
+* reorder
+* reopen
+
+If in doubt, don't use a hyphen
+
+## ie
+* See eg, etc and ie
+
+## Italics
+Don't use italics. Use 'single quotation marks' if referring to a document, scheme or initiative.
+
+## Lists
+See bullets and steps
+
+## Period
+All sentences end with a period. All tooltips end with a period. Bullet points (ul) do not end with a period. Each Numbered step (ol) ends with a period.
+
+## Punctuation
+For quotes, single quotes and speech marks use the character code not the keyboard. Order of precedence is HTML Name, HTML Decimal Code, Unicode Hexadecimal.
+
+### Oxford (or serial) comma.
+We don't use the Oxford comma so the final item in a list before the 'and' does not have a comma.
+
+### Quotes and speech marks.
+Use `" "  "` at the beginning and end.
+
+### Single quotes
+Use either `' '` at the beginning and end.
+Use single quotes:
+* in headlines
+* for unusual terms
+* when referring to words or publications, for example: Download the manual 'Understanding ACL' (PDF, 360KB)'
+
+## Slashes
+A slash (/) should not have spaces around it eg show/hide not show / hide
+
+## Spaces
+Use only one space after a full stop, not 2.