Merge pull request #140 from brianteeman/master

Stage 1 - copying markdown docs from gh-pages branch

manual/appendices/analysis.md

@@ -0,0 +1,37 @@
+## Coding Standards Analysis
+
+For new contributions we are going to be enforcing coding standards to ensure that the coding style in the source code is consistent. Ensuring that your code meets these standards will make the process of code contribution smoother.
+
+## Configuring Code Analysis Tools
+
+In order to improve the consistency and readability of the source code, the Joomla project runs a coding style analysis tool, CodeSniffer, everytime changes are pushed to a Joomla project's repository. 
+
+### Running CodeSniffer
+
+The Joomla Coding Standards sniffer rules are written to be used with a tool called PHP CodeSniffer. Please see the [PHP CodeSniffer Pear
+Page](http://pear.php.net/package/PHP_CodeSniffer) for information on
+installing PHP CodeSniffer on your system.
+
+You can run the CodeSniffer by going to the CMS, Framework, or Issue Tracker's root directory and executing 
+
+```
+phpcs --report=checkstyle --report-file=build/logs/checkstyle.xml --standard=/path/to/<your root>/build/phpcs/Joomla /path/to/<your root>
+```
+
+Alternatively, if you have Ant installed on your system, you may run the CodeSniffer by going to the `<root directory>` of the Joomla project's code you want to test and executing
+
+```
+ant phpcs
+```
+
+#### Known Issues
+
+-   There is currently an issue with running the Code Sniffer on the
+    Simplepie library. Pointing the sniffs at the libraries/joomla
+    directory or below will avoid the issue.
+
+## Other Tools
+
+Here are some other tools available to developers who are planning to submit source code to the project.
+
+### PhpStorm Code Style Scheme

manual/appendices/examples.md

@@ -0,0 +1 @@
+## Code Examples

manual/basic-guidelines.md

@@ -0,0 +1,31 @@
+## Basic Guidelines
+
+This chapter outlines the basic guidelines covering files contributed to the Joomla project. The most important rule to remember when coding for the Joomla project, **if in doubt, please ask**. 
+
+### File Format
+
+All files contributed to Joomla must be: 
+
+* Stored as ASCII text
+* Use UTF-8 character encoding
+* Be Unix formatted following these rules. 
+	1. Lines must end only with a line feed (LF). 
+	2. Line feeds are represented as ordinal 10, octal 012 and hex 0A. 
+	3. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.
+
+### Spelling
+
+The spelling of words and terms used in code comments and in the naming of class, functions, variables and constant should generally be in accordance with British English rules (en\_GB). 
+Some exceptions are permitted, for example where common programming names are used that align with the PHP API or other established conventions such as for `color` where is it common practice to maintain US English spelling.
+
+### Indenting
+
+Tabs are used for indenting code (not spaces as required by the PEAR standard). Source code editors or Integrated Development Environments (IDE’s) such as Eclipse must have the tab-stops for indenting measuring four (4) spaces in length.
+
+### Line Length
+
+There is no maximum limit for line lengths in files, however, a notional value of about 150 characters is recommended to achieve a good level of readability without horizontal scrolling. Longer lines are permitted if the nature of the code for individual lines requires it and line breaks would have an adverse affect on the final output (such as for mixed PHP/HTML layout files).
+
+## Best Practices
+
+TODO Any words of wisdom about PHP best practice, maybe even references for design patterns? Can/should we link out to the JRD, Doc wiki and Developer site for additional resources?

manual/css.md

@@ -0,0 +1,220 @@
+## CSS
+These guidelines have been assembled following an examination of emerging practices, ideas and existing styleguides, namely:
+
+1. [OOCSS Code Standards](https://github.com/stubbornella/oocss-code-standards)
+2. [Oneweb Style Guide](https://github.com/nternetinspired/OneWeb/blob/master/STYLEGUIDE.md)
+3. [Idiomatic CSS](https://github.com/necolas/idiomatic-css)
+
+
+## Commenting
+
+### Major sections
+Major code sections should be named in caps and within a full comment block, eg:
+```css
+/* ==========================================================================
+   PRIMARY NAVIGATION
+   ========================================================================== */
+```
+
+### Sub sections
+Subsections should be normally cased and within an open comment block.
+```css
+/* Mobile navigation
+   ========================================================================== */
+```
+
+### Verbose comments
+```css
+/**
+ * Short description using Doxygen-style comment format
+ *
+ * The first sentence of the long description starts here and continues on this
+ * line for a while finally concluding here at the end of this paragraph.
+ *
+ * The long description is ideal for more detailed explanations and
+ * documentation. It can include example HTML, URLs, or any other information
+ * that is deemed necessary or useful.
+ *
+ * @tag This is a tag named 'tag'
+ *
+ * TODO: This is a todo statement that describes an atomic task to be completed
+ *   at a later date. It wraps after 80 characters and following lines are
+ *   indented by 2 spaces.
+ */
+ ```
+
+### Basic comments
+```css
+/* Basic comment */
+```
+
+### Uncompiled LESS/Scss comments
+```css
+// These are stripped on compile.
+```
+
+## Class naming
+Use dashes to create compound class names:
+
+```css
+/* Good - use dashes */
+.compound-class-name {…}
+
+/* Bad - uses underscores */
+.compound_class_name {…}
+
+/* Bad - uses camelCase */
+.compoundClassName {…}
+
+/* Bad - does not use seperators */
+.compoundclassname {…}
+```
+
+### Indentation
+Rules should be indented one tab (equal to 4 spaces):
+
+```css
+/* Good */
+.example {
+	color: #000;
+	visibility: hidden;
+}
+
+/* Bad - all on one line */
+.example {color: #000; visibility: hidden;}
+```
+
+LESS/Scss should also be nested , with child selectors and rules indented again. Nested rules should also be spaced by one line:
+
+```css
+/* Good */
+.example {
+
+  > li {
+    float: none;
+
+	+ li {
+		margin-top: 2px;
+		margin-left: 0;
+	}
+
+  }
+
+}
+/* Bad - nested rules not indented */
+.example {
+
+	> li {
+	float: none;
+
+	+ li {
+	margin-top: 2px;
+	margin-left: 0;
+	}
+
+	}
+
+}
+/* Bad - nested rules not spaced */
+.example {
+  > li {
+    float: none;
+	+ li {
+		margin-top: 2px;
+		margin-left: 0;
+	}
+  }
+}
+```
+
+### Alignment
+The opening brace must be on the same line as the last selector and preceded by a space. The closing brace must be on its own line after the last property and be indented to the same level as the opening brace.
+
+```css
+/* Good */
+.example {
+    color: #fff;
+}
+
+/* Bad - closing brace is in the wrong place */
+.example {
+    color: #fff;
+    }
+
+/* Bad - opening brace missing space */
+.example{
+    color: #fff;
+}
+```
+
+### Property Format
+Each property must be on its own line and indented one level. There should be no space before the colon and one space after. All properties must end with a semicolon.
+
+```css
+/* Good */
+.example {
+    background: black;
+    color: #fff;
+}
+
+/* Bad - missing spaces after colons */
+.example {
+    background:black;
+    color:#fff;
+}
+
+/* Bad - missing last semicolon */
+.example {
+    background: black;
+    color: #fff
+}
+```
+
+### HEX values
+HEX values must be declared in lowercase and shorthand:
+```css
+/* Good */
+.example {
+    color: #eee;
+}
+
+/* Bad */
+.example {
+    color: #EEEEEE;
+}
+```
+
+### Attribute selectors
+Always use double quotes around attribute selectors.
+
+```css
+/* Good */
+input[type="button"] {
+    ...
+}
+
+/* Bad - missing quotes */
+input[type=button] {
+    ...
+}
+
+/* Bad - using single quote */
+input[type='button'] {
+    ...
+}
+```
+
+### Zero value units
+Zero values should not carry units.
+
+```css
+/* Good */
+.example {
+   padding: 0;
+}
+
+/* Bad - uses units */
+.example {
+   padding: 0px;
+}
+```