|
1 |
| -# Referencing Bug Tracker Tickets |
| 1 | +## Referencing Bug Tracker Tickets |
2 | 2 |
|
3 | 3 | * Pull requests for changes that were requested or recommended via the [jQuery Bug Tracker](http://bugs.jquery.com) should include a link back to the relevant ticket.
|
4 | 4 |
|
5 |
| -# Style Guidelines |
| 5 | +## Building |
6 | 6 |
|
7 |
| -## Prose Style & Grammar |
| 7 | +### Requirements |
| 8 | +* <a href="http://www.xmlsoft.org/">libxml2</a> |
| 9 | +* <a href="http://xmlsoft.org/XSLT/">libxslt</a> |
8 | 10 |
|
9 |
| -###Sentence Structure |
| 11 | +The `xmllint` and `xsltproc` utilities need to be in your path. If you are on Windows, you can get libxml2 and libxslt from <a href="http://sourceforge.net/projects/gnuwin32/files/">GnuWin32</a>. |
| 12 | + |
| 13 | +### Build |
| 14 | + |
| 15 | +1. `npm install` |
| 16 | +2. `grunt` |
| 17 | + |
| 18 | +## Style Guidelines |
| 19 | + |
| 20 | +### Prose Style & Grammar |
| 21 | + |
| 22 | +#### Sentence Structure |
10 | 23 |
|
11 | 24 | * Write in clear, easy-to-understand statements.
|
12 | 25 | * Keep sentences short and to the point.
|
13 | 26 |
|
14 |
| -###Spelling |
| 27 | +#### Spelling |
15 | 28 | * The documentation standardizes on American English spelling. For example:
|
16 | 29 | * **Yes**: color, while, among, customize
|
17 | 30 | * **No**: colour, whilst, amongst, customise
|
18 | 31 |
|
19 |
| -### Pronoun Usage |
| 32 | +#### Pronoun Usage |
20 | 33 | * Use second-person pronoun ("you") when necessary, but try to avoid it.
|
21 | 34 | * Favor the definite article ("the") over second-person possesive ("your").
|
22 | 35 | * **Yes**: Insert the paragraph after the unordered list.
|
|
25 | 38 | * **Yes**: The `.insertAfter()` method here adds an unordered list beneath the paragraph.
|
26 | 39 | * **No**: And now we have our paragraph beneath the unordered list.
|
27 | 40 |
|
28 |
| -### "Voice" |
| 41 | +#### "Voice" |
29 | 42 | * Prefer active voice over passive.
|
30 | 43 | * **Active**: Calling `.click()` binds a click handler to the elements in the collection
|
31 | 44 | * **Passive**: Click handlers are bound to elements in the collection when `.click()` is called
|
32 | 45 |
|
33 |
| -## Code Style |
| 46 | +### Code Style |
34 | 47 | Code in the API documentation should follow the [jQuery Core Style Guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines) with the following addition and exception:
|
35 | 48 |
|
36 | 49 | * **Document ready syntax**: Use `$( document ).ready(function() {` instead of `$(function() {` as it's harder for new users to distinguish the difference between the latter and an IIFE.
|
37 | 50 | * **Indentation**: Core guidelines say to use tabs. In API documentation, *use 2 spaces instead*. This helps keep the line width manageable and avoid horizontal scrollbars.
|
38 | 51 |
|
39 |
| -### Code within prose content (paragraphs and the like): |
| 52 | +#### Code within prose content (paragraphs and the like): |
40 | 53 | * Methods: use a dot, followed by the method name, followed by parentheses: e.g. The `.focus()` method is a shortcut for `.bind('focus', handler)` in the first and second variations, and `.trigger('focus')` in the third.
|
41 | 54 | * Properties: use a dot, followed by the property name: e.g. `.length`.
|
42 | 55 | * Functions: use the function name, followed by parentheses: `myFunction()`.
|
43 | 56 |
|
44 |
| -### Examples |
| 57 | +#### Examples |
45 | 58 | * Examples should indicate what the expected result will be before presenting the code. This makes code clearer and skimming easier, especially for newer coders who may not understand what is supposed to be happening from reading the code itself.
|
46 | 59 | * **Yes**: Find all p elements that are children of a div element and apply a border to them.
|
47 | 60 | * **No**: Find all p elements that are children of a div element.
|
48 | 61 | * Make your example easy to follow with good comments so that the explanation isn't necessary.
|
49 | 62 |
|
50 |
| -## Rhetorical Context |
| 63 | +### Rhetorical Context |
51 | 64 | * Subject
|
52 | 65 | * The entirety of jQuery's public API
|
53 | 66 | * Audience
|
|
0 commit comments