diff options
| author | EricFromCanada | 2017-03-12 21:01:00 -0400 | 
|---|---|---|
| committer | EricFromCanada | 2017-03-12 21:01:00 -0400 | 
| commit | c0468a3266ca173cb1e04a764bcc205a88957bba (patch) | |
| tree | 7be9f053892fcb731a8856c05e0447fedcf8ddac /docs/Prose-Style-Guidelines.md | |
| parent | ad7c2e5416b032a49f8c889f9f7634ac8c3ffedc (diff) | |
| download | brew-c0468a3266ca173cb1e04a764bcc205a88957bba.tar.bz2 | |
docs: add markers to ordered lists and sublists
While GitHub allows a single space to denote a sublist, Jekyll is not
so lenient. It also seems unable to handle ordered sublists.
Diffstat (limited to 'docs/Prose-Style-Guidelines.md')
| -rw-r--r-- | docs/Prose-Style-Guidelines.md | 22 | 
1 files changed, 11 insertions, 11 deletions
| diff --git a/docs/Prose-Style-Guidelines.md b/docs/Prose-Style-Guidelines.md index 7da21d355..029115699 100644 --- a/docs/Prose-Style-Guidelines.md +++ b/docs/Prose-Style-Guidelines.md @@ -28,7 +28,7 @@ We prefer:  * British/Commonwealth English over American English, in general  * "e.g." and "i.e.": Go ahead and use "e.g." or "i.e." instead of spelling them out. Don't worry about putting a comma after them. - * "e.g." means "for example"; "i.e." means "that is" +  * "e.g." means "for example"; "i.e." means "that is"  * Offset nontrivial subordinate clauses with commas  ### Personal pronouns @@ -45,36 +45,36 @@ We prefer:  * Capitalize all list items if you want, even if they're not complete sentences; just be consistent within each list, and preferably, throughout the whole page  * Use a subordinate list item instead of dropping a multi-sentence paragraph-long item into a list of sentence fragments  * Prefer Markdown over other markup formats unless their specific features are needed - * GitHub Flavored Markdown. GitHub's implementation is the standard, period. +  * GitHub Flavored Markdown. GitHub's implementation is the standard, period.  ### Typographical conventions  * Literal text in commands and code is styled in `fixed width font`  * Placeholders inside code snippets are marked up with `<...>` brackets - * e.g. `git remote add <my-user-name> https://github.com/<my-user-name>/homebrew-core.git` +  * e.g. `git remote add <my-user-name> https://github.com/<my-user-name>/homebrew-core.git`  * Names of commands like `git` and `brew` are styled in `fixed width font`  * No "$" with environment variables mentioned outside code snippets - * e.g. "Set `BLAH` to 5", not "Set `$BLAH` to 5" +  * e.g. "Set `BLAH` to 5", not "Set `$BLAH` to 5"  * One space after periods, not two  * Capitalized proper nouns  * We do not defer to extensive nonstandard capitalization, typesetting, or other styling of brand names, aside from the normal capitalization of proper nouns and simple internal capitalization  * No "TM", ™, <sup>SM</sup>, ©, ®, or other explicit indicators of rights ownership or trademarks; we take these as understood when the brand name is mentioned  * Tap names like `homebrew/core` are styled in `fixed width font`. Repository names may be styled in either fixed width font like "`Homebrew/homebrew-core`", as links like "[Homebrew/homebrew-core](https://github.com/homebrew/homebrew-core)", or regular text like "Homebrew/homebrew-core", based on which looks best for a given use. - * But be consistent within a single document - * Capitalize repository names to match the user and repository names on GitHub. Keep tap names in lower case. +  * But be consistent within a single document +  * Capitalize repository names to match the user and repository names on GitHub. Keep tap names in lower case.  * Commas - * No Oxford commas - * Prefer a "loose" comma style: "when in doubt, leave it out" unless needed for clarity +  * No Oxford commas +  * Prefer a "loose" comma style: "when in doubt, leave it out" unless needed for clarity  ### Terminology, words, and word styling  * "pull request", not "Pull Request"  * "check out" is the verb; "checkout" is the noun  * Spell out certain technical words - * "repository", not "repo" - * When abbreviating, introduce the abbreviation with the first usage in any document +  * "repository", not "repo" +  * When abbreviating, introduce the abbreviation with the first usage in any document  * Some abbreviations (near-universally understood among our user base) are fine, though. - * "Mac" is fine; "Macintosh" isn't necessary +  * "Mac" is fine; "Macintosh" isn't necessary  * "macOS" for all versions, "OS X" or "Mac OS X" when describing specific older versions  * "RuboCop", not "Rubocop"  * A pull request is made "on" a repository; that repository is "at" a URL | 
