You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by mw...@apache.org on 2013/11/13 19:15:46 UTC
[1/2] docs commit: removed a few useless embedded Xrefs
Updated Branches:
refs/heads/master ad3f66a99 -> 5b907bc24
removed a few useless embedded Xrefs
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/5b907bc2
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/5b907bc2
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/5b907bc2
Branch: refs/heads/master
Commit: 5b907bc2451679ddceefbea6e174ca8247c1c053
Parents: dfda650
Author: Mike Sierra <ms...@adobe.com>
Authored: Mon Nov 11 17:08:28 2013 -0500
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Wed Nov 13 10:15:44 2013 -0800
----------------------------------------------------------------------
docs/en/edge/guide/cli/index.md | 6 ------
docs/en/edge/guide/overview/index.md | 15 ---------------
2 files changed, 21 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5b907bc2/docs/en/edge/guide/cli/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/cli/index.md b/docs/en/edge/guide/cli/index.md
index 1ff1367..ad88ff4 100644
--- a/docs/en/edge/guide/cli/index.md
+++ b/docs/en/edge/guide/cli/index.md
@@ -153,9 +153,6 @@ application whose home page is the project's `www/index.html` file.
Edit this application however you want, but any initialization should
be specified as part of the `deviceready` event handler, referenced by
default from `www/js/index.js`.
-<!-- XREF
-(See the Application Development Guide for details.)
-XREF -->
Run the following command to iteratively build the project:
@@ -230,9 +227,6 @@ example when designing a hybrid app that mixes a Cordova WebView with
native components. (See Embedding WebViews and Plugin Development
Guide for details.) More commonly, you would add a plugin to enable
one of Cordova's basic device-level features
-<!-- XREF
-discussed in the Application Development Guide and
-XREF -->
detailed in the API Reference. A list of these plugins, including
additional plugins provided by the community, can be found at
[plugins.cordova.io](http://plugins.cordova.io/). You can use
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/5b907bc2/docs/en/edge/guide/overview/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/overview/index.md b/docs/en/edge/guide/overview/index.md
index 9cb9287..02f0702 100644
--- a/docs/en/edge/guide/overview/index.md
+++ b/docs/en/edge/guide/overview/index.md
@@ -57,10 +57,6 @@ The app executes as a _WebView_ within the native application wrapper,
which you distribute to app stores. For the web app to interact with
various device features the way native apps do, it must also reference
a `cordova.js` file, which provides API bindings.
-<!-- XREF
-(See the API Reference for an overview, and the Application
-Development Guide for examples of how to use them.)
-XREF -->
The Cordova-enabled WebView may provide the application with its
entire user interface. It can also be a component within a larger,
@@ -90,9 +86,6 @@ the CLI for progressively greater shares of the development cycle:
* For supporting platforms, the CLI can compile executible
applications and run them in an SDK-based device emulator.
- <!-- XREF
- (See Application Development Guide for details.)
- XREF -->
For comprehensive testing, you can also generate application files
and install them directly on a device.
@@ -102,16 +95,8 @@ options.
(See the Platform Guides for details about each platform's SDK tool set.)
An SDK environment is more appropriate if you want implement a hybrid
app that mixes web-based and native application components.
-<!-- XREF
-(See Hybrid Application Guide for more information.)
-XREF -->
You may use the command-line utility to initially generate the app, or
iteratively thereafter to feed updated code to SDK tools. You may
also build the app's configuration file yourself.
(See The config.xml File for details.)
-<!-- XREF
-To build projects on some platforms, you may need to apply digital signatures.
-See Distributing Applications for information on how to upload your app to various store portals.
-XREF -->
-
[2/2] docs commit: tightened up & sample recursive grep commands
Posted by mw...@apache.org.
tightened up & sample recursive grep commands
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/dfda6503
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/dfda6503
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/dfda6503
Branch: refs/heads/master
Commit: dfda65038bc0410b77083cfb6e1bd9a208f1ce14
Parents: ad3f66a
Author: Mike Sierra <ms...@adobe.com>
Authored: Mon Nov 11 17:05:32 2013 -0500
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Wed Nov 13 10:15:44 2013 -0800
----------------------------------------------------------------------
STYLESHEET.md | 186 ++++++++++++++++++++++++++++++++---------------------
1 file changed, 113 insertions(+), 73 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/dfda6503/STYLESHEET.md
----------------------------------------------------------------------
diff --git a/STYLESHEET.md b/STYLESHEET.md
index 123a89d..e795bcb 100644
--- a/STYLESHEET.md
+++ b/STYLESHEET.md
@@ -21,7 +21,9 @@ license: Licensed to the Apache Software Foundation (ASF) under one
Developers contributing to Cordova are already familiar with coding
best practices. What you'll find here are best practices when writing
-tech doc addressed to Cordova developers.
+tech doc addressed to Cordova developers. A consistent set of
+standards helps tie together doc, and makes it seem like it's written
+with one voice.
There are two basic kinds of tech doc: reference content and
expository "guide" content. Reference doc tends to be self-contained,
@@ -35,22 +37,32 @@ workflows. It may not be obvious, but if you first ask yourself what
purpose the doc you're editing serves, it improves its quality
immensely.
+These guidelines are not necessarily set in stone. If you think of
+alternatives or exceptions, please note them here. Some of the issues
+identified below are listed along with recursive `grep` commands to
+help identify them in Markdown.
+
## Structure and Flow
+* __Provide Context__: Each page of expository doc should start with a
+ short paragraph summarizing the subject matter, and serving as
+ necessary connective tissue to other doc. Link to other related &
+ prerequisite topics, especially for likely workflow scenarios.
+ E.g., Plugman doc is most appropriate for platform-specific
+ shell-tool workflow, not for the CLI even though it underlies it
+ invisibly.
+
* __Valid Heading Structure__: One title only (an A-head) at the top
of the page. No jumps to C-heads. Do not follow a heading with a
subheading with no intervening introductory text.
+ grep -hr '^#' * # Lists all headings; use '#' prefixes rather than underlines
+
* __Flatten Content__: Use B-heads to divide each page's content. Please
- avoid C-heads; readers tend to lose context once content gets that
- nested.
+ avoid C-heads. Readers tend to lose context once content gets that
+ nested. Think: "blog post."
-* __Provide Context__: Each page of expository doc should start with a
- short paragraph summarizing the subject matter, and serving as
- necessary connective tissue. Link to other related & prerequisite
- topics, especially for likely workflow scenarios. E.g., Plugman doc
- is most appropriate for platform-specific shell-tool workflow, not
- for the CLI even though it underlies it invisibly.
+ grep -hr '^###' * # Identifies C-heads
* __Consistent Headings__: Try to match verb tense in headings. That
is, if one is task-based and reads "Adding a Platform," the other
@@ -58,11 +70,12 @@ immensely.
* __Heading Content__: In reference doc, preserve case in titles and
headings. In guide doc: Initial Cap Words in Headings, Except for
- Short Prepositions or Conjunctions. Also Init-Cap Around Hyphens,
- when each segment is a word rather than a prefix, e.g.:. No
- punctuation at the end of a heading; avoid punctuation within
+ Short Prepositions or Conjunctions. Also Init-Cap Around Hyphens. No
+ punctuation at the end of a heading, and avoid punctuation within
headings. Do not prefix headings with numbers.
+ grep -hr '^#' * | sed 's/^#*//g' | grep '[^A-Za-z0-9 ]'
+
* __Heading Fonts__: In reference doc, do not apply font formatting to
standalone member names such as compass.getCurrentHeading. Minimize
font changes within headings. If necessary, only apply italic.
@@ -71,10 +84,9 @@ immensely.
content only, otherwise use bullet lists. Precede lists with text
that introduces them, preferably ending with a colon (:). Do not
allow single-item lists. Use bullet lists only to indicate a clear
- set of choices that you first introduce, not as a substitute for
- regular paragraphs. Avoid nested lists, for the same reason you
- avoid C-heads. Do not nest top-level lists for additional
- indentation.
+ set of choices that you first introduce, not as a substitute for a
+ series of regular paragraphs. Avoid nested lists, for the same
+ reason you avoid C-heads. Do not indent top-level lists.
* __Punctuating and Formatting Lists__: Append periods to bullet and
number list items that consist of full sentences. No periods when
@@ -85,9 +97,9 @@ immensely.
scannable items.
* __Procedure Lists__: Don't break out separate procedure items for
- (1) do this, followed by (2) this describes what just happened.
- Prefer (1) Do this. It does so-and-so, which you might see in some
- result. (2) Do that...
+ (1) do this, followed by (2) this describes what just happened, then
+ (3) do that. Prefer (1) Do this. It does so-and-so, which you might
+ see in some result. (2) Do that...
* __Topic/Comment Lists__: For bullet lists that provide short topics
followed by comments, bold the topic, then merge the comment on the
@@ -95,47 +107,61 @@ immensely.
punctuation. This list item provides an example. Bolded Topic Text
Follows Same Init-Cap Rule as Headings.
-* __Notes__: Bold & all-cap __NOTE__:, with colon outside, always at
- the start of a paragraph, never mid-paragraph. <!--RE :__--> Do not
- incorporate this font change into a sentence as in "__Note__
- that..." but OK to start a sentence: "Note that..." when the
- information is less consequential. Do not apply bullet/number list
- formatting. <!--RE- __NOTE-->
+* __Notes__: Bold and all-cap __NOTE__:, with colon outside, always at
+ the start of a paragraph, never mid-paragraph. Do not incorporate
+ this font change into a sentence as in "__Note__ that..." but OK to
+ start a sentence: "Note that..." when the information is less
+ consequential. Do not apply bullet/number list formatting.
+ grep -hr ':__' *
+ grep -hr ' __NOTE' *
+ grep -hr 'Note:' *
* __Warnings/Tips__: As an alternative to __NOTE__:, use __WARNING__:
for serious matters, or __TIP__: to pass along useful tricks or
context.
+ grep -hri 'Tip:' *
+ grep -hri 'Warning:' *
+
* __Minimize Notes__: Avoid too many notes and warnings, as it implies
a haphazard development environment with too many variable factors
that divert the reader's attention. Try to clarify variations on a
- procedure within the text.
-
-<!--
-* __Platform-Specific Notes__ __ios__: ???
--->
+ procedure within the text. Try to focus attention on information
+ specific to Cordova, not on background knowledge.
## Language and Tone
-* __Not So Imperitive__: As a rule of thumb, avoid the word "must" and
+* __Not So Imperative__: As a rule of thumb, avoid the word "must" and
unnecessarily imperative statements in general. E.g., instead of
"Commands must be run from a cmd or powershell prompt," try "You can
run commands either from a cmd or powershell prompt."
+ grep -hri '\<must\>' *
+ grep -r '\<requires*\>' *
+
* __Avoid the Willies__: Use present tense. "This happens," not "this
will happen." Future tense comes off as a tenuous prediction. Rule
of thumb: avoid the word "will."
+ grep -hri '\<will\>' *
+
* __Avoid Passive Voice__: Past-tense passive voice is to be avoided.
E.g., "the pause event fires when..." rather than "the pause event
is fired when..." Rule of thumb: banish verbs ending in "ed".
Passive voice is more appropriate for reference doc, you should
still avoid it when there's a better active-voice alternative.
+ grep -hr '\<is [a-z]*ed\>' *
+ grep -hr '\<be [a-z]*ed\>' *
+ grep -hr '\<was [a-z]*ed\>' *
+
* __Not Kidding, Use Present Tense__: Minimize verbs ending with
"ing": "This is necessary to provide...", not "This is necessary for
providing..." <!-- are\s-+[a-z]+ing\b -->
+ grep -hr '\<for [a-z]*ing\>' *
+ grep -hr '\<by [a-z]*ing\>' *
+
* __Use Action Verbs__: Avoid weak verbs like "is" or "has." The
sentence in the item above could stand improvement.
@@ -150,8 +176,11 @@ immensely.
"the device's home screen" rather than clumsier: "the home screen of
the device"
+ grep -hr '\<of the\>' *
+
* __The Brothers Karmazov__: 'The FOO file', not 'the file FOO', no
- matter how long FOO's path is.
+ matter how long FOO's path is. Rule of thumb: would you say it when
+ speaking out loud?
* __Serial comma__: This, that, and the other.
@@ -159,23 +188,29 @@ immensely.
* Do not start a sentence with a lowercase member name. E.g., "Does
not support `filter`" rather than "`filter` is not supported"
- <!--RE \. `-->
+
+ grep -hr '\. `' *
* Do not refer to "I," the author of the documentation, as in "What I
am going to show you now." Likewise avoid "we" and "let's," so
- instead of "We see that..." try "Note that..." Readers want to focus
- on the thing they're working on, not on you. <!--RE \bI\b-->
+ instead of "We see that..." try "You see that" or "Note that..."
+ Readers want to focus on whatever they're working on, not on you.
+
+ grep -hr '\<I\>' *
* OK to refer to "you," the developer, but only sparingly, e.g., to
- avoid passive voice. Also do not use "your" as a routine substitute
- for "the" or "a" when referring to a noun.
+ avoid the passive voice. Also do not use "your" as a routine
+ substitute for "the" or "a" when referring to a noun.
+
+ grep -hri '\<your*\>' *
* Avoid em dash clauses--they unnecessarily break up the text--and
parenthical statements (which can also be distracting). If you do
include either, remove spaces around the dashes (punctuate fragments
outside of paren's). (Punctuate full sentences inside of parens.)
-* This Guide or section, not this document, page, or anything else
+* Refer to this Guide or section, not this document, page, or anything
+ else.
## In-line Font Formatting
@@ -189,12 +224,12 @@ immensely.
* Use _italics_ for emphasis, simple mathematical expressions, and
variable items (e.g., _x_/_y_ coordinates).
-* Do _not_ use ALL CAPS for emphasis. (Exception: in commented code)
+* Do _not_ use ALL CAPS for emphasis. (Exception: in code comments)
* Do _not_ use "quote characters" to deliniate in-line text unless
required as part of a value. E.g., not OK to refer to the
"text-align" property. OK to set the CSS `text-align` property to
- `left`, and the `content` property to `"This is some text."`
+ `left`, and the `content` property to `"This is some quoted text."`
(Exception: within code comments)
* Do not combine in-line formatting such as _`monospace italic`_.
@@ -205,27 +240,31 @@ immensely.
## Usage
* "User" may refer to the end user, not to an application's
- "developer." Refer to plural "users" as "they" to avoid singular
- he/she pronoun problems. Also avoid "his" and "her".
- <!--RE\bs?he\b--> <!--RE\b(his|her)\b-->
+ "developer" who is presumably reading the doc. Refer to plural
+ "users" as "they" to avoid singular he/she pronoun problems. Also
+ avoid "his" and "her". <!--RE\bs?he\b--> <!--RE\b(his|her)\b-->
+
+ grep -hri '\<s*he\>' *
+ grep -hri '\<his\>' *
+ grep -hri '\<her\>' *
* WebView, not Webview. (OK to use lowercase webview in code)
* "In-line" rather than "inline" in ordinary text, e.g., outside of
technical terms.
-* "Plugman" in generic references, "plugman" when referring to actual
- utility.
+* "Plugman" in generic references, `plugman` when referring to the
+ actual utility as invoked on the command line.
* metadata.
* Xcode.
-* "splash screen" unless specifically referring to API.
+* "splash screen" unless specifically referring to the name of the API.
-* 'Directory', not 'folder'; may be exceptions in some GUI contexts
+* 'Directory', not 'folder'; may be exceptions in some GUI contexts.
-* Prefer "can't" over "cannot"; sounds more relaxed. <!--RE cannot-->
+* Prefer "can't" over "cannot"; sounds more relaxed.
* Subdirectory, not sub-directory
@@ -233,7 +272,7 @@ immensely.
* 'Set up' as verb, 'setup' as noun.
-* 'Handheld' not 'hand held'
+* 'handheld' not 'hand held' or 'hand-held'
* Filename, not file name
@@ -250,10 +289,11 @@ immensely.
* Prefer "emulator" over "simulator"; clarify when interfaces refer to
them differently.
-* Use "app" for mobile apps, and "application" for desktop. E.g., you
- may use the Xcode application to help you write an iOS Cordova app.
- Consider "app" a valid word rather than a contraction, so use "apps"
- rather than "app's" as plural.
+* Use "app" for mobile apps, and "application" for presumably more
+ complex desktop affairs. E.g., you may use the Xcode application to
+ help you write an iOS Cordova app. Consider "app" a valid word
+ rather than a contraction, so use "apps" rather than "app's" as
+ plural.
* Likewise, "repo" is OK to substitute for "repository"
@@ -263,20 +303,23 @@ immensely.
* Remove superfluous "navigate to" wherever possible, unless you need
to `cd` to a particular directory to launch a command. Instead of
- "Navigate to the D directory and edit the F file," prefer: "Edit the
- _D/F_ file."
+ "Navigate to the `D` directory and edit the `F` file," prefer: "Edit
+ the `D/F` file." And don't tell people which text editor to use.
+ That's fascist.
* An XML/HTML 'element' rather than 'tag'
-* It's a "method" when called on an object. Refer to "function" only
- when unspecified, e.g. a "callback function" may also be implemented
- as an object method.
+* Without getting into any pointless arguments about object-oriented
+ programming, it's a "method" when called on an object. Refer to
+ "function" only when unspecified, e.g. you can implement a "callback
+ function" as an object method, but not necessarily.
* Use parentheses when referring to `method()` and `function()` names.
(Exception: when assigning a reference to the object rather than
calling it as a method.)
-* Spell out "and" and "or"; do not substitute with "&" or "/" in text
+* Spell out "and" and "or"; do not substitute with "&" or "/" within
+ text.
* "and/or" is unnecessary; "or" usually makes that implicit.
@@ -284,11 +327,12 @@ immensely.
in this example (but OK to refer to try/catch blocks).
* Avoid trailing (s) to denote optional plural. It's usually implicit.
- E.g., "return information about captured image files", not "file(s)"
+ E.g., "return information about any captured image files", not
+ "file(s)"
* Avoid the word "multiple" wherever possible. It's one of those
- unnecessary words up there with "myriad" or "plethora." What's wrong
- with "several"?
+ unnecessary words up there with "myriad" or "plethora." What ever
+ happened to "several"?
## Punctuation
@@ -322,14 +366,14 @@ immensely.
clauses where one is a sentence fragment. E.g., "This is a clause,
along with this." vs. "This can serve as a sentence; this can too."
-* If a sentence with semicolons runs on tool long, it's time to break
+* If a sentence with semicolons runs on too long, it's time to break
it out into separate sentences. Rewrite this... "This can serve as
a sentence; this can too, along with related information." ...as...
"This can serve as a sentence. This can too, along with related
information."
-* This is can serve as a sentence and this can also serve as a
- sentence but you need to use commas to separate this big mess.
+* This can serve as a sentence and this can also serve as a sentence
+ but you need to use commas to separate this big mess.
## Content-specific
@@ -343,26 +387,22 @@ immensely.
webview, e.g., custom plugins, or an embedded webview component. (2)
An app with an InAppBrowser, that is a web-based app that itself
opens a web page. Don't apply to a garden-variety "cross-platform"
- app that is Cordova's bread & butter.
+ app that is Cordova's bread and butter.
## Links
* Use titles in link text, never 'click here'. Consider using the
- link's domain name as a substitute. <!--RE here]-->
+ link's domain name as a substitute.
* Domain names are OK as a link's display text, but not full
scheme-qualified URLs. No bare URLs in text outside of code.
- <!--RE \[http -->
-## Miscellaneous
+ grep -hr '\[http' *
-* In body text, no ( extra space inside parens ). OK to increase
- readability of code.
+## Miscellaneous
* OK to use shorthand notation for version ranges, e.g. "5.0+" rather
than "(OS 5.0 and higher)"
* Use space characters rather than tabs in code blocks.
-
-