Revert "Project import generated by Copybara."

This reverts commit 54cca78d64.
This commit is contained in:
Ted Osborne 2018-01-30 12:36:50 -05:00
parent 54cca78d64
commit 505ba68c74
47 changed files with 44735 additions and 2568 deletions

54
README.md Normal file
View File

@ -0,0 +1,54 @@
Google Style Guides
===================
Every major open-source project has its own style guide: a set of conventions
(sometimes arbitrary) about how to write code for that project. It is much
easier to understand a large codebase when all the code in it is in a
consistent style.
“Style” covers a lot of ground, from “use camelCase for variable names” to
“never use global variables” to “never use exceptions.” This project
([google/styleguide](https://github.com/google/styleguide)) links to the
style guidelines we use for Google code. If you are modifying a project that
originated at Google, you may be pointed to this page to see the style guides
that apply to that project.
This project holds the [C++ Style Guide][cpp], [Objective-C Style Guide][objc],
[Java Style Guide][java], [Python Style Guide][py], [R Style Guide][r],
[Shell Style Guide][sh], [HTML/CSS Style Guide][htmlcss],
[JavaScript Style Guide][js], [AngularJS Style Guide][angular],
[Common Lisp Style Guide][cl], and [Vimscript Style Guide][vim]. This project
also contains [cpplint][cpplint], a tool to assist with style guide compliance,
and [google-c-style.el][emacs], an Emacs settings file for Google style.
If your project requires that you create a new XML document format, the [XML
Document Format Style Guide][xml] may be helpful. In addition to actual style
rules, it also contains advice on designing your own vs. adapting an existing
format, on XML instance document formatting, and on elements vs. attributes.
The style guides in this project are licensed under the CC-By 3.0 License,
which encourages you to share these documents.
See [https://creativecommons.org/licenses/by/3.0/][ccl] for more details.
The following Google style guides live outside of this project:
[Go Code Review Comments][go] and [Effective Dart][dart].
<a rel="license" href="https://creativecommons.org/licenses/by/3.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/3.0/88x31.png" /></a>
[cpp]: https://google.github.io/styleguide/cppguide.html
[objc]: objcguide.md
[java]: https://google.github.io/styleguide/javaguide.html
[py]: https://google.github.io/styleguide/pyguide.html
[r]: https://google.github.io/styleguide/Rguide.xml
[sh]: https://google.github.io/styleguide/shell.xml
[htmlcss]: https://google.github.io/styleguide/htmlcssguide.html
[js]: https://google.github.io/styleguide/jsguide.html
[angular]: https://google.github.io/styleguide/angularjs-google-style.html
[cl]: https://google.github.io/styleguide/lispguide.xml
[vim]: https://google.github.io/styleguide/vimscriptguide.xml
[cpplint]: https://github.com/google/styleguide/tree/gh-pages/cpplint
[emacs]: https://raw.githubusercontent.com/google/styleguide/gh-pages/google-c-style.el
[xml]: https://google.github.io/styleguide/xmlstyle.html
[go]: https://golang.org/wiki/CodeReviewComments
[dart]: https://www.dartlang.org/guides/language/effective-dart
[ccl]: https://creativecommons.org/licenses/by/3.0/

447
Rguide.xml Normal file
View File

@ -0,0 +1,447 @@
<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<link rel="stylesheet" type="text/css" href="styleguide.css"/>
<title>Google's R Style Guide</title>
</head>
<body>
<h1>Google's R Style Guide</h1>
<p>
R is a high-level programming language used primarily for
statistical computing and graphics. The goal of the R
Programming Style Guide is to make our R code easier to read,
share, and verify. The rules below were designed in
collaboration with the entire R user community at Google.
</p>
<h2>Summary: R Style Rules</h2>
<ol>
<li><a href="#filenames">File Names</a>: end in <code>.R</code></li>
<li><a href="#identifiers">Identifiers</a>: <code>variable.name</code>
(or <code>variableName</code>),
<code>FunctionName</code>, <code>kConstantName</code></li>
<li><a href="#linelength">Line Length</a>: maximum 80 characters</li>
<li><a href="#indentation">Indentation</a>: two spaces, no tabs</li>
<li><a href="#spacing">Spacing</a></li>
<li><a href="#curlybraces">Curly Braces</a>: first on same line, last on
own line</li>
<li><a href="#else">else</a>: Surround else with braces </li>
<li><a href="#assignment">Assignment</a>: use <code>&lt;-</code>, not
<code>=</code></li>
<li><a href="#semicolons">Semicolons</a>: don't use them</li>
<li><a href="#generallayout"> General Layout and Ordering</a></li>
<li><a href="#comments"> Commenting Guidelines</a>: all comments begin
with <code>#</code> followed by a space; inline comments need two
spaces before the <code>#</code></li>
<li><a href="#functiondefinition">Function Definitions and Calls</a></li>
<li><a href="#functiondocumentation"> Function Documentation</a></li>
<li><a href="#examplefunction"> Example Function</a></li>
<li><a href="#todo"> TODO Style</a>: <code>TODO(username)</code></li>
</ol>
<h2>Summary: R Language Rules</h2>
<ol>
<li><a href="#attach"> <code>attach</code></a>: avoid using it</li>
<li><a href="#functionlanguage"> Functions</a>:
errors should be raised using <code>stop()</code></li>
<li><a href="#object"> Objects and Methods</a>: avoid S4 objects and
methods when possible; never mix S3 and S4 </li>
</ol>
<h3>Notation and Naming</h3>
<h4 id="filenames">File Names</h4>
<p>
File names should end in <code>.R</code> and, of course, be
meaningful.
<br/> GOOD: <code>predict_ad_revenue.R</code>
<br/> BAD: <code><span style="color:red">foo.R</span></code>
</p>
<h4 id="identifiers">Identifiers</h4>
<p>
Don't use underscores ( <code>_</code> ) or hyphens
( <code>-</code> ) in identifiers.
Identifiers should be named according to the following conventions.
The preferred form for variable names is all lower case
letters and words separated with dots
(<code>variable.name</code>), but <code>variableName</code>
is also accepted;
function names have initial capital letters and no dots
(<code>FunctionName</code>);
constants are named like functions but with an initial
<code>k</code>.
</p>
<ul>
<li><code>variable.name</code> is preferred, <code>variableName</code> is accepted
<br/> GOOD: <code>avg.clicks</code>
<br/> OK: <code>avgClicks</code>
<br/> BAD: <code><span style="color:red">avg_Clicks</span></code>
</li>
<li><code>FunctionName </code>
<br/> GOOD: <code>CalculateAvgClicks</code>
<br/> BAD: <code><span style="color:red">calculate_avg_clicks
</span></code>,
<code><span style="color:red">calculateAvgClicks</span></code>
<br/> Make function names verbs.
<br/><em>Exception: When creating a classed object, the function
name (constructor) and class should match (e.g., lm).</em></li>
<li><code>kConstantName </code></li>
</ul>
<h3>Syntax</h3>
<h4 id="linelength">Line Length</h4>
<p>
The maximum line length is 80 characters.
</p>
<h4 id="indentation">Indentation</h4>
<p>
When indenting your code, use two spaces. Never use tabs or mix
tabs and spaces.
<br/><em>Exception: When a line break occurs inside parentheses,
align the wrapped line with the first character inside the
parenthesis.</em>
</p>
<h4 id="spacing">Spacing</h4>
<p>
Place spaces around all binary operators (<code>=</code>,
<code>+</code>, <code>-</code>, <code>&lt;-</code>, etc.).
<br/><em> Exception: Spaces around <code>=</code>'s are
optional when passing parameters in a function call.</em>
</p>
<p>
Do not place a space before a comma, but always place one after a
comma.
<br/><br/> GOOD:
</p>
<pre>tab.prior &lt;- table(df[df$days.from.opt &lt; 0, "campaign.id"])
total &lt;- sum(x[, 1])
total &lt;- sum(x[1, ])</pre>
<p>
BAD:
</p>
<pre><span style="color:red">tab.prior &lt;- table(df[df$days.from.opt&lt;0, "campaign.id"]) # Needs spaces around '&lt;'
tab.prior &lt;- table(df[df$days.from.opt &lt; 0,"campaign.id"]) # Needs a space after the comma
tab.prior&lt;- table(df[df$days.from.opt &lt; 0, "campaign.id"]) # Needs a space before &lt;-
tab.prior&lt;-table(df[df$days.from.opt &lt; 0, "campaign.id"]) # Needs spaces around &lt;-
total &lt;- sum(x[,1]) # Needs a space after the comma
total &lt;- sum(x[ ,1]) # Needs a space after the comma, not before</span>
</pre>
<p>
Place a space before left parenthesis, except in a function call.
</p>
<p>
GOOD:
<br/><code>if (debug)</code>
</p>
<p>
BAD:
<br/><code><span style="color:red">if(debug)</span></code>
</p>
<p>
Extra spacing (i.e., more than one space in a row) is okay if it
improves alignment of equals signs or arrows (<code>&lt;-</code>).
</p>
<pre>plot(x = x.coord,
y = data.mat[, MakeColName(metric, ptiles[1], "roiOpt")],
ylim = ylim,
xlab = "dates",
ylab = metric,
main = (paste(metric, " for 3 samples ", sep = "")))
</pre>
<p>
Do not place spaces around code in parentheses or square brackets.
<br/><em> Exception: Always place a space after a comma.</em>
</p>
<p>
GOOD:</p><pre>if (debug)
x[1, ]</pre>
<p>
BAD:</p><pre><span style="color:red">if ( debug ) # No spaces around debug
x[1,] # Needs a space after the comma </span></pre>
<h4 id="curlybraces">Curly Braces</h4>
<p>
An opening curly brace should never go on its own line; a closing
curly brace should always go on its own line. You may omit curly
braces when a block consists of a single statement; however, you
must <em>consistently</em> either use or not use curly braces for
single statement blocks.
</p>
<pre>
if (is.null(ylim)) {
ylim &lt;- c(0, 0.06)
}</pre>
<p>
xor (but not both)
</p>
<pre>
if (is.null(ylim))
ylim &lt;- c(0, 0.06)</pre>
<p>
Always begin the body of a block on a new line.
</p>
<p>
BAD:
<br/><code><span style="color:red"> if (is.null(ylim))
ylim &lt;- c(0, 0.06)</span></code>
<br/><code><span style="color:red"> if (is.null(ylim))
{ylim &lt;- c(0, 0.06)} </span></code>
</p>
<h4 id="else">Surround else with braces</h4>
<p>
An <code>else</code> statement should always be surrounded on the
same line by curly braces.</p>
<pre>
if (condition) {
one or more lines
} else {
one or more lines
}
</pre>
<p>
BAD:<br/>
</p>
<pre style="color:red">
if (condition) {
one or more lines
}
else {
one or more lines
}
</pre>
<p>
BAD:<br/>
</p>
<pre style="color:red">
if (condition)
one line
else
one line
</pre>
<h4 id="assignment">Assignment</h4>
<p>
Use <code>&lt;-</code>, not <code>=</code>, for assignment.
</p>
<p>
GOOD:
<br/><code> x &lt;- 5 </code>
</p>
<p>
BAD:
<br/><code><span style="color:red"> x = 5</span></code>
</p>
<h4 id="semicolons">Semicolons</h4>
<p>
Do not terminate your lines with semicolons or use semicolons to
put more than one command on the same line. (Semicolons are not
necessary, and are omitted for consistency with other Google style
guides.)
</p>
<h3> Organization </h3>
<h4 id="generallayout">General Layout and Ordering</h4>
<p>
If everyone uses the same general ordering, we'll be able to
read and understand each other's scripts faster and more easily.
</p>
<ol>
<li>Copyright statement comment </li>
<li>Author comment</li>
<li>File description comment, including purpose of
program, inputs, and outputs</li>
<li><code>source()</code> and <code>library()</code> statements</li>
<li>Function definitions</li>
<li>Executed statements, if applicable (e.g.,
<code> print</code>, <code>plot</code>)</li>
</ol>
<p>
Unit tests should go in a separate file named
<code>originalfilename_test.R</code>.
</p>
<h4 id="comments">Commenting Guidelines</h4>
<p>
Comment your code. Entire commented lines should begin with
<code>#</code> and one space.
</p>
<p>
Short comments can be placed after code preceded by two spaces,
<code>#</code>, and then one space.
</p>
<pre># Create histogram of frequency of campaigns by pct budget spent.
hist(df$pct.spent,
breaks = "scott", # method for choosing number of buckets
main = "Histogram: fraction budget spent by campaignid",
xlab = "Fraction of budget spent",
ylab = "Frequency (count of campaignids)")
</pre>
<h4 id="functiondefinition">Function Definitions and
Calls</h4>
<p>
Function definitions should first list arguments without default
values, followed by those with default values.
</p>
<p>
In both function definitions and function calls, multiple
arguments per line are allowed; line breaks are only allowed
between assignments.
<br/>GOOD:
</p>
<pre>PredictCTR &lt;- function(query, property, num.days,
show.plot = TRUE)
</pre>
BAD:
<pre><span style="color:red">PredictCTR &lt;- function(query, property, num.days, show.plot =
TRUE)
</span></pre>
<p> Ideally, unit tests should serve as sample function calls (for
shared library routines).
</p>
<h4 id="functiondocumentation">Function Documentation</h4>
<p> Functions should contain a comments section immediately below
the function definition line. These comments should consist of a
one-sentence description of the function; a list of the function's
arguments, denoted by <code>Args:</code>, with a description of
each (including the data type); and a description of the return
value, denoted by <code>Returns:</code>. The comments should be
descriptive enough that a caller can use the function without
reading any of the function's code.
</p>
<h4 id="examplefunction">Example Function</h4>
<pre>
CalculateSampleCovariance &lt;- function(x, y, verbose = TRUE) {
# Computes the sample covariance between two vectors.
#
# Args:
# x: One of two vectors whose sample covariance is to be calculated.
# y: The other vector. x and y must have the same length, greater than one,
# with no missing values.
# verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE.
#
# Returns:
# The sample covariance between x and y.
n &lt;- length(x)
# Error handling
if (n &lt;= 1 || n != length(y)) {
stop("Arguments x and y have different lengths: ",
length(x), " and ", length(y), ".")
}
if (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {
stop(" Arguments x and y must not have missing values.")
}
covariance &lt;- var(x, y)
if (verbose)
cat("Covariance = ", round(covariance, 4), ".\n", sep = "")
return(covariance)
}
</pre>
<h4 id="todo">TODO Style</h4>
<p>
Use a consistent style for TODOs throughout your code.
<br/><code>TODO(username): Explicit description of action to
be taken</code>
</p>
<h3> Language </h3>
<h4 id="attach">Attach</h4>
<p> The possibilities for creating errors when using
<code>attach</code> are numerous. Avoid it.</p>
<h4 id="functionlanguage">Functions</h4>
<p> Errors should be raised using <code>stop()</code>.</p>
<h4 id="object">Objects and Methods</h4>
<p> The S language has two object systems, S3 and S4, both of which
are available in R. S3 methods are more interactive and flexible,
whereas S4 methods are more formal and rigorous. (For an illustration
of the two systems, see Thomas Lumley's
"Programmer's Niche: A Simple
Class, in S3 and S4" in R News 4/1, 2004, pgs. 33 - 36:
<a href="https://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf">
https://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf</a>.)
</p>
<p>Use S3 objects and methods unless there is a strong reason to use
S4 objects or methods. A primary justification for an S4 object
would be to use objects directly in C++ code. A primary
justification for an S4 generic/method would be to dispatch on two
arguments.
</p>
<p>Avoid mixing S3 and S4: S4 methods ignore S3 inheritance and
vice-versa.
</p>
<h3>Exceptions</h3>
<p>
The coding conventions described above should be followed, unless
there is good reason to do otherwise. Exceptions include legacy
code and modifying third-party code.
</p>
<h3>Parting Words</h3>
<p>
Use common sense and BE CONSISTENT.
</p>
<p>
If you are editing code, take a few minutes to look at the code around
you and determine its style. If others use spaces around their
<code>if </code>
clauses, you should, too. If their comments have little boxes of stars
around them, make your comments have little boxes of stars around them,
too.
</p>
<p>
The point of having style guidelines is to have a common vocabulary of
coding so people can concentrate on <em>what</em> you are saying,
rather than on <em>how</em> you are saying it. We present global style
rules here so people
know the vocabulary. But local style is also important. If code you add
to a file looks drastically different from the existing code around it,
the discontinuity will throw readers out of their rhythm when they go to
read it. Try to avoid this.
</p>
<p>
OK, enough writing about writing code; the code itself is much more
interesting. Have fun!
</p>
<h3>References</h3>
<p>
<a href="http://www.maths.lth.se/help/R/RCC/">
http://www.maths.lth.se/help/R/RCC/</a> - R Coding Conventions
</p>
<p>
<a href="http://ess.r-project.org/">http://ess.r-project.org/</a> - For
emacs users. This runs R in your emacs and has an emacs mode.
</p>
</body>
</html>

393
angularjs-google-style.html Normal file
View File

@ -0,0 +1,393 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "https://www.w3.org/TR/REC-html40/strict.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<base target="_blank">
<link rel="stylesheet" type="text/css" href="styleguide.css">
<script src="https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js"></script>
<script language="javascript" src="/eng/doc/devguide/include/styleguide.js"></script>
<title>Google's AngularJS Style Guide</title>
<style type="text/css"><!--
th { background-color: #ddd; }
//--></style>
</head>
<body onload="prettyPrint();initStyleGuide();">
<h1 class="external">An AngularJS Style Guide for Closure Users at Google</h1>
<p class="external">This is the external version of a document that was primarily written for Google
engineers. It describes a recommended style for AngularJS apps that use Closure, as used
internally at Google. Members of the broader AngularJS community should feel free to apply
(or not apply) these recommendations, as relevant to their own use cases.</p>
<p class="external">This document describes style for AngularJS apps in google3. This guide
supplements and extends the <a href="https://google.github.io/styleguide/jsguide.html">
Google JavaScript Style Guide</a>.
</p>
<p><b>Style Note</b>: Examples on the AngularJS external webpage, and many external apps, are
written in a style that freely uses closures, favors functional inheritance, and does not often use
<a class="external"
href="https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System">
JavaScript types</a>. Google follows a more rigorous Javascript style to support JSCompiler
optimizations and large code bases - see the javascript-style mailing list.
This is not an Angular-specific issue, and is not discussed further in this style guide.
(But if you want further reading:
<a href="http://martinfowler.com/bliki/Lambda.html">Martin Fowler on closures</a>,
<a href="http://jibbering.com/faq/notes/closures/">much longer description</a>, appendix A of the
<a href="https://books.google.com/books/about/Closure_The_Definitive_Guide.html?id=p7uyWPcVGZsC">
closure book</a> has a good description of inheritance patterns and why it prefers
pseudoclassical,
<a href="https://books.google.com/books/about/JavaScript.html?id=PXa2bby0oQ0C">
Javascript, the Good Parts</a> as a counter.)</p>
<h5>1 Angular Language Rules</h5>
<ul>
<li> <a target="_self" href="#googprovide">Manage dependencies with Closure's goog.require and
goog.provide</a>
<li> <a target="_self" href="#modules"> Modules</a>
<li> <a target="_self" href="#moduledeps"> Modules should reference other modules using the
"name" property</a>
<li> <a target="_self" href="#externs">Use the provided Angular externs file</a>
<li> <a target="_self" href="#compilerflags">JSCompiler Flags</a>
<li> <a target="_self" href="#controllers">Controllers and Scopes</a>
<li> <a target="_self" href="#directives">Directives</a>
<li> <a target="_self" href="#services">Services</a>
</ul>
<h5>2 Angular Style Rules</h5>
<ul>
<li><a target="_self" href="#dollarsign">Reserve $ for Angular properties and services
</a>
<li><a target="_self" href="#customelements">Custom elements.</a>
</ul>
<h5>3 Angular Tips, Tricks, and Best Practices</h5>
<ul>
<li><a target="_self" href="#testing">Testing</a>
<li><a target="_self" href="#appstructure">Consider using the Best Practices for App Structure</a>
<li><a target="_self" href="#scopeinheritance">Be aware of how scope inheritance works</a>
<li><a target="_self" href="#nginject">Use @ngInject for easy dependency injection compilation</a>
</ul>
<h5><a target="_self" href="#bestpractices">4 Best practices links and docs</a></h5>
<h2>1 Angular Language Rules</h2>
<h3 id="googprovide">Manage dependencies with Closure's goog.require and goog.provide</h3>
<p>Choose a namespace for your project, and use goog.provide and goog.require.</p>
<pre class="prettyprint lang-js">
goog.provide('hello.about.AboutCtrl');
goog.provide('hello.versions.Versions');
</pre>
<p><b>Why?</b>
Google BUILD rules integrate nicely with closure provide/require.</p>
<h3 id="modules">Modules</h3>
<p>Your main application module should be in your root client directory. A module should never be
altered other than the one where it is defined.</p>
<p>Modules may either be defined in the same file as their components (this works well for a module
that contains exactly one service) or in a separate file for wiring pieces together.</p>
<p><b>Why?</b>
A module should be consistent for anyone that wants to include it as a reusable component.
If a module can mean different things depending on which files are included, it is not consistent.
</p>
<h3 id="moduledeps">
Modules should reference other modules using the Angular Module's "name" property
</h3>
<p>For example:</p>
<pre class="prettyprint lang-js">
// file submodulea.js:
goog.provide('my.submoduleA');
my.submoduleA = angular.module('my.submoduleA', []);
// ...
// file app.js
goog.require('my.submoduleA');
Yes: my.application.module = angular.module('hello', [my.submoduleA.name]);
<font color="red">
No: my.application.module = angular.module('hello', ['my.submoduleA']);
</font></pre>
<p><b>Why?</b>
Using a property of my.submoduleA prevents Closure presubmit failures complaining that the file is
required but never used. Using the .name property avoids duplicating strings.</p>
<h3 id="externs">Use a common externs file</h3>
<p>This maximally allows the JS compiler to enforce type safety in the presence of externally
provided types from Angular, and means you don't have to worry about Angular vars being obfuscated
in a confusing way. </p>
<p>Note to readers outside Google: the current externs file is located in an internal-to-Google
directory, but an example can be found on github <a href="https://github.com/angular/angular.js/pull/4722">
here</a>.</p>
<h3 id="compilerflags">JSCompiler Flags</h3>
<p><b>Reminder</b>: According to the JS style guide, customer facing code must be compiled.</p>
<p><b>Recommended</b>: Use the JSCompiler (the closure compiler that works with js_binary by
default) and ANGULAR_COMPILER_FLAGS_FULL from //javascript/angular/build_defs/build_defs for
your base flags.
</p>
<p>Note - if you are using @export for methods, you will need to add the compiler flag</p>
<pre>
"--generate_exports",
</pre>
<p>If you are using @export for properties, you will need to add the flags:</p>
<pre>
"--generate_exports",
"--remove_unused_prototype_props_in_externs=false",
"--export_local_property_definitions",
</pre>
<h3 id="controllers">Controllers and Scopes</h3>
<p>Controllers are classes. Methods should be defined on MyCtrl.prototype.</p>
<p>Google Angular applications should use the <b>'controller as'</b> style to export the controller
onto the scope. This is fully implemented in Angular 1.2 and can be mimicked in pre-Angular 1.2
builds.
</p>
<p>Pre Angular 1.2, this looks like:</p>
<pre class="prettyprint lang-js">
/**
* Home controller.
*
* @param {!angular.Scope} $scope
* @constructor
* @ngInject
* @export
*/
hello.mainpage.HomeCtrl = function($scope) {
/** @export */
$scope.homeCtrl = this; // This is a bridge until Angular 1.2 controller-as
/**
* @type {string}
* @export
*/
this.myColor = 'blue';
};
/**
* @param {number} a
* @param {number} b
* @export
*/
hello.mainpage.HomeCtrl.prototype.add = function(a, b) {
return a + b;
};
</pre>
<p>And the template:</p>
<pre>
&lt;div ng-controller="hello.mainpage.HomeCtrl"/&gt;
&lt;span ng-class="homeCtrl.myColor"&gt;I'm in a color!&lt;/span&gt;
&lt;span&gt;{{homeCtrl.add(5, 6)}}&lt;/span&gt;
&lt;/div&gt;
</pre>
<p>After Angular 1.2, this looks like:</p>
<pre class="prettyprint lang-js">
/**
* Home controller.
*
* @constructor
* @ngInject
* @export
*/
hello.mainpage.HomeCtrl = function() {
/**
* @type {string}
* @export
*/
this.myColor = 'blue';
};
/**
* @param {number} a
* @param {number} b
* @export
*/
hello.mainpage.HomeCtrl.prototype.add = function(a, b) {
return a + b;
};
</pre>
<p>If you are compiling with property renaming, expose properties and methods using the @export
annotation. Remember to @export the constructor as well.</p>
<p>And in the template:</p>
<pre>
&lt;div ng-controller="hello.mainpage.HomeCtrl as homeCtrl"/&gt;
&lt;span ng-class="homeCtrl.myColor"&gt;I'm in a color!&lt;/span&gt;
&lt;span&gt;{{homeCtrl.add(5, 6)}}&lt;/span&gt;
&lt;/div&gt;
</pre>
<p><b>Why?</b>
Putting methods and properties directly onto the controller, instead of building up a scope
object, fits better with the Google Closure class style. Additionally, using 'controller as'
makes it obvious which controller you are accessing when multiple controllers apply to an element.
Since there is always a '.' in the bindings, you don't have to worry about prototypal inheritance
masking primitives.</p>
<h3 id="directives">Directives</h3>
<p>All DOM manipulation should be done inside directives. Directives should be kept small and use
composition. Files defining directives should goog.provide a static function which returns the
directive definition object.</p>
<pre class="prettyprint lang-js">
goog.provide('hello.pane.paneDirective');
/**
* Description and usage
* @return {angular.Directive} Directive definition object.
*/
hello.pane.paneDirective = function() {
// ...
};
</pre>
<p><b>Exception</b>: DOM manipulation may occur in services for DOM elements disconnected from the
rest of the view, e.g. dialogs or keyboard shortcuts.</p>
<h3 id="services">Services</h3>
<p>Services registered on the module with <code>module.service</code> are classes.
Use <code>module.service</code> instead of <code>module.provider</code> or
<code>module.factory</code> unless you need to do initialization beyond just creating a
new instance of the class.</p>
<pre class="prettyprint lang-js">
/**
* @param {!angular.$http} $http The Angular http service.
* @constructor
*/
hello.request.Request = function($http) {
/** @type {!angular.$http} */
this.http_ = $http;
};
hello.request.Request.prototype.get = function() {/*...*/};
</pre>
<p>In the module:</p>
<pre class="prettyprint lang-js">
module.service('request', hello.request.Request);
</pre>
<h2>2 Angular Style Rules</h2>
<h3 id="dollarsign">Reserve $ for Angular properties and services</h3>
<p>Do not use $ to prepend your own object properties and service identifiers. Consider this style
of naming reserved by AngularJS and jQuery.</p>
<p>Yes:</p>
<pre class="prettyprint lang-js">
$scope.myModel = { value: 'foo' }
myModule.service('myService', function() { /*...*/ });
var MyCtrl = function($http) {this.http_ = $http;};
</pre>
<p><font color="red">No:</font></p>
<pre class="prettyprint">
$scope.$myModel = { value: 'foo' } // BAD
$scope.myModel = { $value: 'foo' } // BAD
myModule.service('$myService', function() { ... }); // BAD
var MyCtrl = function($http) {this.$http_ = $http;}; // BAD
</pre>
<p><b>Why?</b>
It's useful to distinguish between Angular / jQuery builtins and things you add yourself.
In addition, $ is not an acceptable character for variables names in the JS style guide.
</p>
<h3 id="customelements">Custom elements</h3>
<p>For custom elements (e.g. <code>&lt;ng-include src="template"&gt;&lt;/ng-include&gt;</code>), IE8
requires special support (html5shiv-like hacks) to enable css styling. Be aware of this
restriction in apps targeting old versions of IE.</p>
<h2>3 Angular Tips, Tricks, and Best Practices</h2>
<p>These are not strict style guide rules, but are placed here as reference for folks getting
started with Angular at Google.</p>
<h3 id="testing">Testing</h3>
<p>Angular is designed for test-driven development.</p>
<p>The recommended unit testing setup is Jasmine + Karma (though you could use closure tests
or js_test)</p>
<p>Angular provides easy adapters to load modules and use the injector in Jasmine tests.
<ul>
<li><a href = "https://docs.angularjs.org/api/angular.mock.module">module</a>
<li><a href="https://docs.angularjs.org/api/angular.mock.inject">inject</a>
</ul>
</p>
<h3 id="appstructure">Consider using the Best Practices for App Structure</h3>
<p>
This <a href="https://docs.google.com/document/d/1XXMvReO8-Awi1EZXAXS4PzDzdNvV6pGcuaF4Q9821Es/pub">directory structure doc</a> describes how to structure your application with controllers in
nested subdirectories and all components (e.g. services and directives) in a 'components' dir.
</p>
<h3 id="scopeinheritance">Be aware of how scope inheritance works</h3>
<p>See <a href="https://github.com/angular/angular.js/wiki/Understanding-Scopes#wiki-JSproto">
The Nuances of Scope Prototypal Inheritance</a></p>
<h3 id="nginject">Use @ngInject for easy dependency injection compilation</h3>
<p>This removes the need to add <code>myCtrl['$inject'] = ...</code> to prevent minification from
messing up Angular's dependency injection.</p>
<p>Usage:</p>
<pre class="prettyprint lang-js">
/**
* My controller.
* @param {!angular.$http} $http
* @param {!my.app.myService} myService
* @constructor
* @export
* @ngInject
*/
my.app.MyCtrl = function($http, myService) {
//...
};
</pre>
<h2 id="bestpractices">4 Best practices links and docs</h2>
<ul>
<li><a href="https://github.com/angular/angular.js/wiki/Best-Practices">
Best Practices</a> from Angular on GitHub</li>
<li><a href="https://www.youtube.com/watch?v=ZhfUv0spHCY">
Meetup video</a> (not Google specific)</li>
</ul>
<address>
Last modified Feb 07 2013
</address>
</body>
<html>

6170
cppguide.html Normal file

File diff suppressed because it is too large Load Diff

18
cppguide.xml Normal file
View File

@ -0,0 +1,18 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf8">
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<meta http-equiv="refresh" content="1; url=cppguide.html">
<title>Redirecting</title>
</head>
<!-- The BODY onLoad redirect is the best: it preserves #fragments and
?queries. But it requires javascript. If that fails, the
meta-refresh kicks in; it works more generally, but loses fragments
and queries, takes a second, and pollutes the browser history.
If they both fail, we let the user manually click on the new link.
-->
<body onload="location.replace(location.href.replace('.xml', '.html'))">
Redirecting you to <a href="cppguide.html">cppguide.html</a>.
</body>
</html>

45
cpplint/README Normal file
View File

@ -0,0 +1,45 @@
This is automated checker to make sure a C++ file follows Google's C++ style
guide (https://google.github.io/styleguide/cppguide.html). As it
heavily relies on regular expressions, cpplint.py won't catch all violations of
the style guide and will very occasionally report a false positive. There is a
list of things we currently don't handle very well at the top of cpplint.py,
and we welcome patches to improve it.
The linting tool takes a list of files as input. For full usage instructions,
please see the output of:
./cpplint.py --help
Unit tests are provided in cpplint_unittest.py. This file can safely be ignored
by end users who have downloaded this package and only want to run the lint
tool.
---
cpplint.py and its corresponding unit tests are Copyright (C) 2009 Google Inc.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
* Neither the name of Google Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

6228
cpplint/cpplint.py vendored Executable file

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1 @@
// A test header for cpplint_unittest.py.

5805
cpplint/cpplint_unittest.py Executable file

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1 @@
// A test header for cpplint_unittest.py.

10
docguide/README.md Normal file
View File

@ -0,0 +1,10 @@
# Google documentation guide
* [Markdown styleguide](style.md)
* [Best practices](best_practices.md)
* [README files](READMEs.md)
* [Philosophy](philosophy.md)
## See also
* [How to update this guide](https://goto.google.com/doc-guide), for Googlers.

69
docguide/READMEs.md Normal file
View File

@ -0,0 +1,69 @@
# README.md files
About README.md files.
1. [Overview](#overview)
1. [Guidelines](#guidelines)
1. [Filename](#filename)
1. [Contents](#contents)
1. [Example](#example)
## Overview
`README.md` files are Markdown files that describe a directory.
GitHub and Gitiles renders it when you browse the directory.
For example, the file /README.md is rendered when you view the contents of the
containing directory:
https://github.com/google/styleguide/tree/gh-pages
Also `README.md` at `HEAD` ref is rendered by Gitiles when displaying repository
index:
https://gerrit.googlesource.com/gitiles/
## Guidelines
**`README.md` files are intended to provide orientation for engineers browsing
your code, especially first-time users.** The `README.md` is likely the first
file a reader encounters when they browse a directory that
contains your code. In this way, it acts as a landing page for the directory.
We recommend that top-level directories for your code have an up-to-date
`README.md` file. This is especially important for package directories that
provide interfaces for other teams.
### Filename
Use `README.md`.
Files named `README` are not displayed in the directory view in Gitiles.
### Contents
At minimum, every package-level `README.md` should include or point to the
following information:
1. **What** is in this package/library and what's it used for.
2. **Who** to contact.
3. **Status**: whether this package/library is deprecated, or not for general
release, etc.
4. **More info**: where to go for more detailed documentation, such as:
* An overview.md file for more detailed conceptual information.
* Any API documentation for using this package/library.
## Example
```markdown
# APIs
This is the top-level directory for all externally-visible APIs, plus some
private APIs under `internal/` directories.
See [API Style Guide](docs/apistyle.md) for more information.
*TL;DR*: API definitions and configurations should be defined in `.proto` files,
checked into `apis/`.
...
```

1
docguide/VERSION Normal file
View File

@ -0,0 +1 @@
1.0

115
docguide/best_practices.md Normal file
View File

@ -0,0 +1,115 @@
# Documentation Best Practices
"Say what you mean, simply and directly." - [Brian Kernighan]
(https://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)
Contents:
1. [Minimum viable documentation](#minimum-viable-documentation)
1. [Update docs with code](#update-docs-with-code)
1. [Delete dead documentation](#delete-dead-documentation)
1. [Documentation is the story of your code](#documentation-is-the-story-of-your-code)
## Minimum viable documentation
A small set of fresh and accurate docs are better than a sprawling, loose
assembly of "documentation" in various states of disrepair.
Write short and useful documents. Cut out everything unnecessary, while also
making a habit of continually massaging and improving every doc to suit your
changing needs. **Docs work best when they are alive but frequently trimmed,
like a bonsai tree**.
This guide encourages engineers to take ownership of their docs and keep
them up to date with the same zeal we keep our tests in good order. Strive for
this.
* Identify what you really need: release docs, API docs, testing guidelines.
* Delete cruft frequently and in small batches.
## Update docs with code
**Change your documentation in the same CL as the code change**. This keeps your
docs fresh, and is also a good place to explain to your reviewer what you're
doing.
A good reviewer can at least insist that docstrings, header files, README.md
files, and any other docs get updated alongside the CL.
## Delete dead documentation
Dead docs are bad. They misinform, they slow down, they incite despair in
engineers and laziness in team leads. They set a precedent for leaving behind
messes in a code base. If your home is clean, most guests will be clean without
being asked.
Just like any big cleaning project, **it's easy to be overwhelmed**. If your
docs are in bad shape:
* Take it slow, doc health is a gradual accumulation.
* First delete what you're certain is wrong, ignore what's unclear.
* Get your whole team involved. Devote time to quickly scan every doc and make
a simple decision: Keep or delete?
* Default to delete or leave behind if migrating. Stragglers can always be
recovered.
* Iterate.
## Prefer the good over the perfect
Your documentation should be as good as possible within a reasonable time frame.
The standards for an documentation review are different from the
standards for code reviews. Reviewers can and should ask for improvements, but
in general, the author should always be able to invoke the "Good Over Perfect
Rule". It's preferable to allow authors to quickly submit changes that improve
the document, instead of forcing rounds of review until it's "perfect". Docs are
never perfect, and tend to gradually improve as the team learns what they really
need to write down.
## Documentation is the story of your code
Writing excellent code doesn't end when your code compiles or even if your
test coverage reaches 100%. It's easy to write something a computer understands,
it's much harder to write something both a human and a computer understand. Your
mission as a Code Health-conscious engineer is to **write for humans first,
computers second.** Documentation is an important part of this skill.
There's a spectrum of engineering documentation that ranges from terse comments
to detailed prose:
1. **Inline comments**: The primary purpose of inline comments is to provide
information that the code itself cannot contain, such as why the code is
there.
2. **Method and class comments**:
* **Method API documentation**: The header / Javadoc / docstring
comments that say what methods do and how to use them. This
documentation is **the contract of how your code must behave**. The
intended audience is future programmers who will use and modify your
code.
It is often reasonable to say that any behavior documented here should
have a test verifying it. This documentation details what arguments the
method takes, what it returns, any "gotchas" or restrictions, and what
exceptions it can throw or errors it can return. It does not usually
explain why code behaves a particular way unless that's relevant to a
developer's understanding of how to use the method. "Why" explanations
are for inline comments. Think in practical terms when writing method
documentation: "This is a hammer. You use it to pound nails."
* **Class / Module API documentation**: The header / Javadoc / docstring
comments for a class or a whole file. This documentation gives a brief
overview of what the class / file does and often gives a few short
examples of how you might use the class / file.
Examples are particularly relevant when there's several distinct ways to
use the class (some advanced, some simple). Always list the simplest
use case first.
3. **README.md**: A good README.md orients the new user to the directory and
points to more detailed explanation and user guides:
* What is this directory intended to hold?
* Which files should the developer look at first? Are some files an API?
* Who maintains this directory and where I can learn more?
See the [README.md guidelines](READMEs.md).

71
docguide/philosophy.md Normal file
View File

@ -0,0 +1,71 @@
# Philosophy
埏埴以為器,當其無,有器之用.
*Clay becomes pottery through craft, but it's the emptiness that makes a pot
useful.*
\- [Laozi](http://ctext.org/dictionary.pl?if=en&id=11602)
Contents:
1. [Radical simplicity](#radical-simplicity)
1. [Readable source text](#readable-source-text)
1. [Minimum viable documentation](#minimum-viable-documentation)
1. [Better is better than perfect](#better-is-better-than-perfect)
## Radical simplicity
* **Scalability and interoperability** are more important than a menagerie of
unessential features. Scale comes from simplicity, speed, and ease.
Interoperability comes from unadorned, digestable content.
* **Fewer distractions** make for better writing and more productive reading.
* **New features should never interfere with the simplest use case** and should
remain invisible to users who don't need them.
* **This guide is designed for the average engineer** -- the busy,
just-want-to-go-back-to-coding engineer. Large and complex documentation is
possible but not the primary focus.
* **Minimizing context switching makes people happier.** Engineers should be
able to interact with documentation using the same tools they use to read and
write code.
## Readable source text
* **Plain text not only suffices, it is superior**. Markdown itself is not
essential to this formula, but it is the best and most widely supported
solution right now. HTML is generally not encouraged.
* **Content and presentation should not mingle**. It should always be possible
to ditch the renderer and read the essential information at source. Users
should never have to touch the presentation layer if they don't want to.
* **Portability and future-proofing leave room for the unimagined integrations
to come**, and are best achieved by keeping the source as human-readable as
possible.
* **Static content is better than dynamic**, because content should not depend
on the features of any one server. However, **fresh is better than stale**. We
strive to balance these needs.
## Minimum viable documentation
* **Docs thrive when they're treated like tests**: a necessary chore one learns
to savor because it rewards over time.
See [Best Practices](best_practices.md).
* **Brief and utilitarian is better than long and exhaustive**. The vast
majority of users need only a small fraction of the author's total knowledge,
but they need it quickly and often.
## Better is better than perfect
* **Incremental improvement is better than prolonged debate**. Patience and
tolerance of imperfection allow projects to evolve organically.
* **Don't lick the cookie, pass the plate**. We're drowning in potentially
impactful projects. Choose only those you can really handle and release those
you can't.

420
docguide/style.md Normal file
View File

@ -0,0 +1,420 @@
# Markdown style guide
Much of what makes Markdown great is the ability to write plain text, and get
great formatted output as a result. To keep the slate clean for the next author,
your Markdown should be simple and consistent with the whole corpus wherever
possible.
We seek to balance three goals:
1. *Source text is readable and portable.*
2. *Markdown files are maintainable over time and across teams.*
3. *The syntax is simple and easy to remember.*
Contents:
1. [Document layout](#document-layout)
1. [Character line limit](#character-line-limit)
1. [Trailing whitespace](#trailing-whitespace)
1. [Headings](#headings)
1. [ATX-style headings](#atx-style-headings)
1. [Add spacing to headings](#add-spacing-to-headings)
1. [Lists](#lists)
1. [Use lazy numbering for long lists](#use-lazy-numbering-for-long-lists)
1. [Nested list spacing](#nested-list-spacing)
1. [Code](#code)
1. [Inline](#inline)
1. [Codeblocks](#codeblocks)
1. [Declare the language](#declare-the-language)
1. [Escape newlines](#escape-newlines)
1. [Nest codeblocks within lists](#nest-codeblocks-within-lists)
1. [Links](#links)
1. [Use informative Markdown link titles](#use-informative-markdown-link-titles)
1. [Images](#images)
1. [Prefer lists to tables](#prefer-lists-to-tables)
1. [Strongly prefer Markdown to HTML](#strongly-prefer-markdown-to-html)
## Document layout
In general, most documents benefit from some variation of the following layout:
```markdown
# Document Title
Short introduction.
[TOC]
## Topic
Content.
## See also
* https://link-to-more-info
```
1. `# Document Title`: The first heading should be a level one heading, and
should ideally be the same or nearly the same as the filename. The first
level one heading is used as the page `<title>`.
1. `author`: *Optional*. If you'd like to claim ownership of the document or
if you are very proud of it, add yourself under the title. However,
revision history generally suffices.
1. `Short introduction.` 1-3 sentences providing a high-level overview of the
topic. Imagine yourself as a complete newbie, who landed on your "Extending
Foo" doc and needs to know the most basic assumptions you take for granted.
"What is Foo? Why would I extend it?"
1. `[TOC]`: if you use hosting that supports table of contents, such as Gitiles,
put `[TOC]` after the short introduction. See
[`[TOC]` documentation](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Table-of-contents).
1. `## Topic`: The rest of your headings should start from level 2.
1. `## See also`: Put miscellaneous links at the bottom for the user who wants
to know more or didn't find what she needed.
## Character line limit
Obey projects' character line limit wherever possible. Long URLs and tables are
the usual suspects when breaking the rule. (Headings also can't be wrapped, but
we encourage keeping them short). Otherwise, wrap your text:
```markdown
Lorem ipsum dolor sit amet, nec eius volumus patrioque cu, nec et commodo
hendrerit, id nobis saperet fuisset ius.
* Malorum moderatius vim eu. In vix dico persecuti. Te nam saperet percipitur
interesset. See the [foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md).
```
Often, inserting a newline before a long link preserves readability while
minimizing the overflow:
```markdown
Lorem ipsum dolor sit amet. See the
[foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md)
for details.
```
## Trailing whitespace
Don't use trailing whitespace, use a trailing backslash.
The [CommonMark spec](http://spec.commonmark.org/0.20/#hard-line-breaks) decrees
that two spaces at the end of a line should insert a `<br />` tag. However, many
directories have a trailing whitespace presubmit check in place, and many IDEs
will clean it up anyway.
Best practice is to avoid the need for a `<br />` altogether. Markdown creates
paragraph tags for you simply with newlines: get used to that.
## Headings
### ATX-style headings
```markdown
## Heading 2
```
Headings with `=` or `-` underlines can be annoying to maintain and don't fit
with the rest of the heading syntax. The user has to ask: Does `---` mean H1 or
H2?
```markdown
Heading - do you remember what level? DO NOT DO THIS.
---------
```
### Add spacing to headings
Prefer spacing after `#` and newlines before and after:
```markdown
...text before.
# Heading 1
Text after...
```
Lack of spacing makes it a little harder to read in source:
```markdown
...text before.
#Heading 1
Text after... DO NOT DO THIS.
```
## Lists
### Use lazy numbering for long lists
Markdown is smart enough to let the resulting HTML render your numbered lists
correctly. For longer lists that may change, especially long nested lists, use
"lazy" numbering:
```markdown
1. Foo.
1. Bar.
1. Foofoo.
1. Barbar.
1. Baz.
```
However, if the list is small and you don't anticipate changing it, prefer fully
numbered lists, because it's nicer to read in source:
```markdown
1. Foo.
2. Bar.
3. Baz.
```
### Nested list spacing
When nesting lists, use a 4 space indent for both numbered and bulleted lists:
```markdown
1. 2 spaces after a numbered list.
4 space indent for wrapped text.
2. 2 spaces again.
* 3 spaces after a bullet.
4 space indent for wrapped text.
1. 2 spaces after a numbered list.
8 space indent for the wrapped text of a nested list.
2. Looks nice, don't it?
* 3 spaces after a bullet.
```
The following works, but it's very messy:
```markdown
* One space,
with no indent for wrapped text.
1. Irregular nesting... DO NOT DO THIS.
```
Even when there's no nesting, using the 4 space indent makes layout consistent
for wrapped text:
```markdown
* Foo,
wrapped.
1. 2 spaces
and 4 space indenting.
2. 2 spaces again.
```
However, when lists are small, not nested, and a single line, one space can
suffice for both kinds of lists:
```markdown
* Foo
* Bar
* Baz.
1. Foo.
2. Bar.
```
## Code
### Inline
&#96;Backticks&#96; designate `inline code`, and will render all wrapped content
literally. Use them for short code quotations and field names:
```markdown
You'll want to run `really_cool_script.sh arg`.
Pay attention to the `foo_bar_whammy` field in that table.
```
Use inline code when referring to file types in an abstract sense, rather than a
specific file:
```markdown
Be sure to update your `README.md`!
```
Backticks are the most common approach for "escaping" Markdown metacharacters;
in most situations where escaping would be needed, code font just makes sense
anyway.
### Codeblocks
For code quotations longer than a single line, use a codeblock:
<pre>
```python
def Foo(self, bar):
self.bar = bar
```
</pre>
#### Declare the language
It is best practice to explicitly declare the language, so that neither the
syntax highlighter nor the next editor must guess.
#### Indented codeblocks are sometimes cleaner
Four-space indenting is also interpreted as a codeblock. These can look
cleaner and be easier to read in source, but there is no way to specify the
language. We encourage their use when writing many short snippets:
```markdown
You'll need to run:
bazel run :thing -- --foo
And then:
bazel run :another_thing -- --bar
And again:
bazel run :yet_again -- --baz
```
#### Escape newlines
Because most commandline snippets are intended to be copied and pasted directly
into a terminal, it's best practice to escape any newlines. Use a single
backslash at the end of the line:
<pre>
```shell
bazel run :target -- --flag --foo=longlonglonglonglongvalue \
--bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
```
</pre>
#### Nest codeblocks within lists
If you need a codeblock within a list, make sure to indent it so as to not break
the list:
```markdown
* Bullet.
```c++
int foo;
```
* Next bullet.
```
You can also create a nested code block with 4 spaces. Simply indent 4
additional spaces from the list indentation:
```markdown
* Bullet.
int foo;
* Next bullet.
```
## Links
Long links make source Markdown difficult to read and break the 80 character
wrapping. **Wherever possible, shorten your links**.
### Use informative Markdown link titles
Markdown link syntax allows you to set a link title, just as HTML does. Use it
wisely.
Titling your links as "link" or "here" tells the reader precisely nothing when
quickly scanning your doc and is a waste of space:
```markdown
See the syntax guide for more info: [link](syntax_guide.md).
Or, check out the style guide [here](style_guide.md).
DO NOT DO THIS.
```
Instead, write the sentence naturally, then go back and wrap the most
appropriate phrase with the link:
```markdown
See the [syntax guide](syntax_guide.md) for more info.
Or, check out the [style guide](style_guide.md).
```
## Images
Use images sparingly, and prefer simple screenshots. This guide is designed
around the idea that plain text gets users down to the business of communication
faster with less reader distraction and author procrastination. However, it's
sometimes very helpful to show what you mean.
See [image syntax](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Images).
## Prefer lists to tables
Any tables in your Markdown should be small. Complex, large tables are difficult
to read in source and most importantly, **a pain to modify later**.
```markdown
Fruit | Attribute | Notes
--- | --- | --- | ---
Apple | [Juicy](https://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away.
Banana | [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.
DO NOT DO THIS
```
[Lists](#lists) and subheadings usually suffice to present the same information
in a slightly less compact, though much more edit-friendly way:
```markdown
## Fruits
### Apple
* [Juicy](https://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
* Firm
* Sweet
Apples keep doctors away.
### Banana
* [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
* Soft
* Sweet
Contrary to popular belief, most apes prefer mangoes.
```
However, there are times when a small table is called for:
```markdown
Transport | Favored by | Advantages
--- | --- | ---
Swallow | Coconuts | Otherwise unladen
Bicycle | Miss Gulch | Weatherproof
X-34 landspeeder | Whiny farmboys | Cheap since the X-38 came out
```
## Strongly prefer Markdown to HTML
Please prefer standard Markdown syntax wherever possible and avoid HTML hacks.
If you can't seem to accomplish what you want, reconsider whether you really
need it. Except for [big tables](#prefer-lists-to-tables), Markdown meets almost
all needs already.
Every bit of HTML or Javascript hacking reduces the readability and portability.
This in turn limits the usefulness of integrations with
other tools, which may either present the source as plain text or render it. See
[Philosophy](philosophy.md).
Gitiles does not render HTML.

View File

@ -0,0 +1,167 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<profiles version="1">
<profile kind="CodeFormatterProfile" name="Google C++" version="1">
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_method_declaration" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_for" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_in_empty_block" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.lineSplit" value="80"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_member_access" value="16"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_base_types" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.keep_else_statement_on_same_line" value="false"/>
<setting id="org.eclipse.cdt.core.formatter.indent_switchstatements_compare_to_switch" value="true"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_constructor_initializer_list" value="83"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_brace_in_array_initializer" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_declaration_parameters" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_if" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_parenthesized_expression" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_exception_specification" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_base_types" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.indent_body_declarations_compare_to_access_specifier" value="true"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_exception_specification" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_template_arguments" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_block" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_method_declaration" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.use_tabs_only_for_leading_indentations" value="false"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_labeled_statement" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_case" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.comment.min_distance_between_code_and_line_comment" value="2"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_array_initializer" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_enum_declarations" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_expressions_in_array_initializer" value="16"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_declarator_list" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_bracket" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_for" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_prefix_operator" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.tabulation.size" value="2"/>
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_else_in_if_statement" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_enumerator_list" value="51"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_parenthesized_expression" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_method_declaration" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_switch" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_declarator_list" value="16"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_parenthesized_expression" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.indent_empty_lines" value="false"/>
<setting id="org.eclipse.cdt.core.formatter.indent_switchstatements_compare_to_cases" value="true"/>
<setting id="org.eclipse.cdt.core.formatter.keep_empty_array_initializer_on_one_line" value="false"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_method_declaration" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.put_empty_statement_on_new_line" value="true"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_switch" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_cast" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_braces_in_array_initializer" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_method_declaration" value="end_of_line"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_while" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_question_in_conditional" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_semicolon" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_angle_bracket_in_template_arguments" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_base_clause" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.indent_breaks_compare_to_cases" value="true"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_unary_operator" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.join_wrapped_lines" value="true"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_declarator_list" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_arguments_in_method_invocation" value="18"/>
<setting id="org.eclipse.cdt.core.formatter.comment.never_indent_line_comments_on_first_column" value="true"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_while" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_brackets" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_bracket" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_parameters_in_method_declaration" value="18"/>
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_closing_brace_in_array_initializer" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.number_of_empty_lines_to_preserve" value="1"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_method_invocation" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_brace_in_array_initializer" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_semicolon_in_for" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_conditional" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_block" value="end_of_line"/>
<setting id="org.eclipse.cdt.core.formatter.comment.preserve_white_space_between_code_and_line_comments" value="true"/>
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_type_declaration" value="end_of_line"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_assignment_operator" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_angle_bracket_in_template_arguments" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_expression_list" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_angle_bracket_in_template_parameters" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.continuation_indentation" value="2"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_expression_list" value="0"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_method_declaration" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_template_parameters" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_default" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_binary_operator" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_conditional_expression" value="34"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_method_invocation" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_array_initializer" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_if" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.format_guardian_clause_on_one_line" value="false"/>
<setting id="org.eclipse.cdt.core.formatter.indent_access_specifier_extra_spaces" value="1"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_cast" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.indent_access_specifier_compare_to_type_header" value="false"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_type_declaration" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.continuation_indentation_for_array_initializer" value="2"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_labeled_statement" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_declaration_parameters" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_semicolon_in_for" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_method_invocation" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.indent_body_declarations_compare_to_namespace_header" value="false"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_compact_if" value="0"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_assignment_operator" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_brace_in_block" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_array_initializer" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_at_end_of_file_if_missing" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_assignment" value="16"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_conditional_expression_chain" value="18"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_template_parameters" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_expression_list" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_question_in_conditional" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_exception_specification" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_binary_operator" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_identifier_in_function_declaration" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_base_clause_in_type_declaration" value="16"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_declaration_throws" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_exception_specification" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_invocation_arguments" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.indent_declaration_compare_to_template_header" value="false"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_unary_operator" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_switch" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.indent_statements_compare_to_body" value="true"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_declaration_throws" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_binary_expression" value="16"/>
<setting id="org.eclipse.cdt.core.formatter.indent_statements_compare_to_block" value="true"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_template_arguments" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_catch_in_try_statement" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_throws_clause_in_method_declaration" value="16"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_method_invocation" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_paren_in_cast" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_catch" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_angle_bracket_in_template_parameters" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.tabulation.char" value="space"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_angle_bracket_in_template_parameters" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_colon_in_constructor_initializer_list" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_while" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_invocation_arguments" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_block_in_case" value="end_of_line"/>
<setting id="org.eclipse.cdt.core.formatter.compact_else_if" value="true"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_postfix_operator" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_after_template_declaration" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_base_clause" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_catch" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.keep_then_statement_on_same_line" value="false"/>
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_switch" value="end_of_line"/>
<setting id="org.eclipse.cdt.core.formatter.alignment_for_overloaded_left_shift_chain" value="18"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_if" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_switch" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.keep_imple_if_on_one_line" value="false"/>
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_after_opening_brace_in_array_initializer" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.indentation.size" value="2"/>
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_namespace_declaration" value="end_of_line"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_conditional" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_enum_declarations" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_prefix_operator" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_angle_bracket_in_template_arguments" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_array_initializer" value="end_of_line"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_case" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_catch" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_namespace_declaration" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_postfix_operator" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_bracket" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_while_in_do_statement" value="do not insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_for" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_angle_bracket_in_template_parameters" value="insert"/>
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_angle_bracket_in_template_arguments" value="do not insert"/>
</profile>
</profiles>

View File

@ -0,0 +1,337 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<profiles version="13">
<profile kind="CodeFormatterProfile" name="GoogleStyle" version="13">
<setting id="org.eclipse.jdt.core.formatter.comment.insert_new_line_before_root_tags" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.disabling_tag" value="@formatter:off"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_annotation" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_type_parameters" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_type_declaration" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_type_arguments" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_anonymous_type_declaration" value="end_of_line"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_case" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_brace_in_array_initializer" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.comment.new_lines_at_block_boundaries" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_cascading_method_invocation_with_arguments.count_dependent" value="16|-1|16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_annotation_declaration" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_annotation" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_field" value="0"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_while" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.use_on_off_tags" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.wrap_prefer_two_fragments" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_annotation_type_member_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_else_in_if_statement" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_prefix_operator" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.keep_else_statement_on_same_line" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_ellipsis" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.comment.insert_new_line_for_parameter" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.wrap_comment_inline_tags" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_annotation_type_declaration" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.indent_breaks_compare_to_cases" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_at_in_annotation" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_local_variable_declaration" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_multiple_fields" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_parameter" value="1040"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_expressions_in_array_initializer" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_type.count_dependent" value="1585|-1|1585"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_conditional_expression" value="80"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_for" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_multiple_fields.count_dependent" value="16|-1|16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_binary_operator" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_question_in_wildcard" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_array_initializer" value="end_of_line"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_enum_constant" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_finally_in_try_statement" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_local_variable" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_catch_in_try_statement" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_while" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.blank_lines_after_package" value="1"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_qualified_allocation_expression.count_dependent" value="16|4|80"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_method_declaration.count_dependent" value="16|4|48"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_type_parameters" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.continuation_indentation" value="2"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_enum_declaration.count_dependent" value="16|4|49"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_postfix_operator" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_method_invocation" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_angle_bracket_in_type_arguments" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_superinterfaces" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_new_chunk" value="1"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_binary_operator" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_package" value="0"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_cascading_method_invocation_with_arguments" value="16"/>
<setting id="org.eclipse.jdt.core.compiler.source" value="1.7"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_constructor_declaration.count_dependent" value="16|4|48"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_enum_constant_arguments" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_constructor_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.comment.format_line_comments" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_angle_bracket_in_type_arguments" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_enum_declarations" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.join_wrapped_lines" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_block" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_explicit_constructor_call" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_local_variable_annotation" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_invocation_arguments" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.align_type_members_on_columns" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_member_type" value="0"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_enum_constant" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_enum_constants.count_dependent" value="16|5|48"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_for" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_method_declaration" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_selector_in_method_invocation" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_switch" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_unary_operator" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_case" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.comment.indent_parameter_description" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_method_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_switch" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_enum_declaration" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_angle_bracket_in_type_parameters" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.comment.clear_blank_lines_in_block_comment" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_type_declaration" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.lineSplit" value="100"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_if" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_selector_in_method_invocation.count_dependent" value="16|4|48"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_brackets_in_array_type_reference" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_parenthesized_expression" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_explicitconstructorcall_arguments" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_constructor_declaration" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_first_class_body_declaration" value="0"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_method" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.indentation.size" value="4"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_method_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.enabling_tag" value="@formatter:on"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_enum_constant" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_package" value="1585"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superclass_in_type_declaration" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_assignment" value="16"/>
<setting id="org.eclipse.jdt.core.compiler.problem.assertIdentifier" value="error"/>
<setting id="org.eclipse.jdt.core.formatter.tabulation.char" value="space"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_semicolon_in_try_resources" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_constructor_declaration_parameters" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_prefix_operator" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.indent_statements_compare_to_body" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_method" value="1"/>
<setting id="org.eclipse.jdt.core.formatter.wrap_outer_expressions_when_nested" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_type_annotation" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.format_guardian_clause_on_one_line" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_for" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_field_declaration" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_cast" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_constructor_declaration" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_labeled_statement" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_annotation_type_declaration" value="end_of_line"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_method_body" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_method_declaration" value="0"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_try" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_method_invocation" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_bracket_in_array_allocation_expression" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_enum_constant" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_annotation" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_at_in_annotation_type_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_declaration_throws" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_if" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_switch" value="end_of_line"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_declaration_throws" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_parenthesized_expression_in_return" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_annotation" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_question_in_conditional" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_question_in_wildcard" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_try" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_bracket_in_array_allocation_expression" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.comment.preserve_white_space_between_code_and_line_comments" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_parenthesized_expression_in_throw" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_type_arguments" value="do not insert"/>
<setting id="org.eclipse.jdt.core.compiler.problem.enumIdentifier" value="error"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_generic_type_arguments" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.indent_switchstatements_compare_to_switch" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.comment_new_line_at_start_of_html_paragraph" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_ellipsis" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_block" value="end_of_line"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comment_prefix" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_for_inits" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_method_declaration" value="end_of_line"/>
<setting id="org.eclipse.jdt.core.formatter.compact_else_if" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_parameter_annotation" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.wrap_before_or_operator_multicatch" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_array_initializer" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_for_increments" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_method" value="1585"/>
<setting id="org.eclipse.jdt.core.formatter.format_line_comment_starting_on_first_column" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_bracket_in_array_reference" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_field" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.comment.indent_root_tags" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_enum_constant" value="end_of_line"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_enum_declarations" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_union_type_in_multicatch" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_explicitconstructorcall_arguments" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_switch" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_declaration_parameters" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_superinterfaces" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_allocation_expression" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.tabulation.size" value="2"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_type_reference" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_opening_brace_in_array_initializer" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_brace_in_block" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_reference" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_enum_constant" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_angle_bracket_in_type_arguments" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_constructor_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_constructor_declaration_throws" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_if" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_method_invocation.count_dependent" value="16|5|80"/>
<setting id="org.eclipse.jdt.core.formatter.comment.clear_blank_lines_in_javadoc_comment" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_parameter.count_dependent" value="1040|-1|1040"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_constructor_declaration" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_assignment_operator" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_assignment_operator" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_package.count_dependent" value="1585|-1|1585"/>
<setting id="org.eclipse.jdt.core.formatter.indent_empty_lines" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_synchronized" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_paren_in_cast" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_declaration_parameters" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.force_if_else_statement_brace" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_block_in_case" value="end_of_line"/>
<setting id="org.eclipse.jdt.core.formatter.number_of_empty_lines_to_preserve" value="3"/>
<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_package_annotation" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_method_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_catch" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_constructor_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_method_invocation" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_bracket_in_array_reference" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_qualified_allocation_expression" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_annotation.count_dependent" value="16|-1|16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_and_in_type_parameter" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_type" value="1585"/>
<setting id="org.eclipse.jdt.core.compiler.compliance" value="1.7"/>
<setting id="org.eclipse.jdt.core.formatter.continuation_indentation_for_array_initializer" value="2"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_brackets_in_array_allocation_expression" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_at_in_annotation_type_declaration" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_allocation_expression" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_cast" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_unary_operator" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_new_anonymous_class" value="20"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_angle_bracket_in_parameterized_type_reference" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_local_variable.count_dependent" value="1585|-1|1585"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_anonymous_type_declaration" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.keep_empty_array_initializer_on_one_line" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_enum_declaration" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_field.count_dependent" value="1585|-1|1585"/>
<setting id="org.eclipse.jdt.core.formatter.keep_imple_if_on_one_line" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_constructor_declaration_parameters" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_angle_bracket_in_type_parameters" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_labeled_statement" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_at_end_of_file_if_missing" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_for" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_parameterized_type_reference" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_constructor_declaration.count_dependent" value="16|5|80"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_type_declaration" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_enum_declaration" value="end_of_line"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_binary_expression" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_while" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_type" value="insert"/>
<setting id="org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode" value="enabled"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_try" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.put_empty_statement_on_new_line" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_label" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_parameter" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_angle_bracket_in_type_parameters" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_method_invocation" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.comment.format_javadoc_comments" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_enum_constant" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_while_in_do_statement" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_enum_constant.count_dependent" value="16|-1|16"/>
<setting id="org.eclipse.jdt.core.formatter.comment.line_length" value="100"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_package" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.blank_lines_between_import_groups" value="0"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_enum_constant_arguments" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_semicolon" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_constructor_declaration" value="end_of_line"/>
<setting id="org.eclipse.jdt.core.formatter.number_of_blank_lines_at_beginning_of_method_body" value="0"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_conditional" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_type_header" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_annotation_type_member_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.wrap_before_binary_operator" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.blank_lines_between_type_declarations" value="2"/>
<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_enum_declaration_header" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_synchronized" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_enum_declaration" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.indent_statements_compare_to_block" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.join_lines_in_comments" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_question_in_conditional" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_multiple_field_declarations" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_compact_if" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_for_inits" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.indent_switchstatements_compare_to_cases" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_array_initializer" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_default" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_and_in_type_parameter" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_constructor_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_imports" value="0"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_assert" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_field" value="1585"/>
<setting id="org.eclipse.jdt.core.formatter.comment.format_html" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_method_declaration" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_angle_bracket_in_type_parameters" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_allocation_expression" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_anonymous_type_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_conditional" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_angle_bracket_in_parameterized_type_reference" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_for" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_expressions_in_array_initializer.count_dependent" value="16|5|80"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_postfix_operator" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.comment.format_source_code" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_synchronized" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_allocation_expression" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_constructor_declaration_throws" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_method_declaration" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_brace_in_array_initializer" value="do not insert"/>
<setting id="org.eclipse.jdt.core.compiler.codegen.targetPlatform" value="1.7"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_resources_in_try" value="80"/>
<setting id="org.eclipse.jdt.core.formatter.use_tabs_only_for_leading_indentations" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_annotation" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.comment.format_header" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.comment.format_block_comments" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_enum_constant" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_enum_constants" value="0"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_parenthesized_expression" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_annotation_declaration_header" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_block" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_parenthesized_expression" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_catch" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_multiple_local_declarations" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_type_declaration.count_dependent" value="16|4|48"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_switch" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_for_increments" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_method.count_dependent" value="1585|-1|1585"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_method_invocation" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_assert" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_type_declaration" value="end_of_line"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_array_initializer" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_braces_in_array_initializer" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_binary_expression.count_dependent" value="16|-1|16"/>
<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_member_annotation" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_local_variable" value="1585"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_method_declaration" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_semicolon_in_for" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_explicit_constructor_call.count_dependent" value="16|5|80"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_catch" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_angle_bracket_in_parameterized_type_reference" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_multiple_field_declarations" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_annotation" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_generic_type_arguments.count_dependent" value="16|-1|16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_parameterized_type_reference" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_allocation_expression.count_dependent" value="16|5|80"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_invocation_arguments" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_method_declaration.count_dependent" value="16|5|80"/>
<setting id="org.eclipse.jdt.core.formatter.comment.new_lines_at_javadoc_boundaries" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.blank_lines_after_imports" value="1"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_multiple_local_declarations" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_enum_constant_header" value="true"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_semicolon_in_for" value="insert"/>
<setting id="org.eclipse.jdt.core.formatter.never_indent_line_comments_on_first_column" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_semicolon_in_try_resources" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.alignment_for_for_statement" value="16"/>
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_angle_bracket_in_type_arguments" value="do not insert"/>
<setting id="org.eclipse.jdt.core.formatter.never_indent_block_comments_on_first_column" value="false"/>
<setting id="org.eclipse.jdt.core.formatter.keep_then_statement_on_same_line" value="false"/>
</profile>
</profiles>

151
google-c-style.el Normal file
View File

@ -0,0 +1,151 @@
;;; google-c-style.el --- Google's C/C++ style for c-mode
;; Keywords: c, tools
;; google-c-style.el is Copyright (C) 2008 Google Inc. All Rights Reserved.
;;
;; It is free software; you can redistribute it and/or modify it under the
;; terms of either:
;;
;; a) the GNU General Public License as published by the Free Software
;; Foundation; either version 1, or (at your option) any later version, or
;;
;; b) the "Artistic License".
;;; Commentary:
;; Provides the google C/C++ coding style. You may wish to add
;; `google-set-c-style' to your `c-mode-common-hook' after requiring this
;; file. For example:
;;
;; (add-hook 'c-mode-common-hook 'google-set-c-style)
;;
;; If you want the RETURN key to go to the next line and space over
;; to the right place, add this to your .emacs right after the load-file:
;;
;; (add-hook 'c-mode-common-hook 'google-make-newline-indent)
;;; Code:
;; For some reason 1) c-backward-syntactic-ws is a macro and 2) under Emacs 22
;; bytecode cannot call (unexpanded) macros at run time:
(eval-when-compile (require 'cc-defs))
;; Wrapper function needed for Emacs 21 and XEmacs (Emacs 22 offers the more
;; elegant solution of composing a list of lineup functions or quantities with
;; operators such as "add")
(defun google-c-lineup-expression-plus-4 (langelem)
"Indents to the beginning of the current C expression plus 4 spaces.
This implements title \"Function Declarations and Definitions\"
of the Google C++ Style Guide for the case where the previous
line ends with an open parenthese.
\"Current C expression\", as per the Google Style Guide and as
clarified by subsequent discussions, means the whole expression
regardless of the number of nested parentheses, but excluding
non-expression material such as \"if(\" and \"for(\" control
structures.
Suitable for inclusion in `c-offsets-alist'."
(save-excursion
(back-to-indentation)
;; Go to beginning of *previous* line:
(c-backward-syntactic-ws)
(back-to-indentation)
(cond
;; We are making a reasonable assumption that if there is a control
;; structure to indent past, it has to be at the beginning of the line.
((looking-at "\\(\\(if\\|for\\|while\\)\\s *(\\)")
(goto-char (match-end 1)))
;; For constructor initializer lists, the reference point for line-up is
;; the token after the initial colon.
((looking-at ":\\s *")
(goto-char (match-end 0))))
(vector (+ 4 (current-column)))))
;;;###autoload
(defconst google-c-style
`((c-recognize-knr-p . nil)
(c-enable-xemacs-performance-kludge-p . t) ; speed up indentation in XEmacs
(c-basic-offset . 2)
(indent-tabs-mode . nil)
(c-comment-only-line-offset . 0)
(c-hanging-braces-alist . ((defun-open after)
(defun-close before after)
(class-open after)
(class-close before after)
(inexpr-class-open after)
(inexpr-class-close before)
(namespace-open after)
(inline-open after)
(inline-close before after)
(block-open after)
(block-close . c-snug-do-while)
(extern-lang-open after)
(extern-lang-close after)
(statement-case-open after)
(substatement-open after)))
(c-hanging-colons-alist . ((case-label)
(label after)
(access-label after)
(member-init-intro before)
(inher-intro)))
(c-hanging-semi&comma-criteria
. (c-semi&comma-no-newlines-for-oneline-inliners
c-semi&comma-inside-parenlist
c-semi&comma-no-newlines-before-nonblanks))
(c-indent-comments-syntactically-p . t)
(comment-column . 40)
(c-indent-comment-alist . ((other . (space . 2))))
(c-cleanup-list . (brace-else-brace
brace-elseif-brace
brace-catch-brace
empty-defun-braces
defun-close-semi
list-close-comma
scope-operator))
(c-offsets-alist . ((arglist-intro google-c-lineup-expression-plus-4)
(func-decl-cont . ++)
(member-init-intro . ++)
(inher-intro . ++)
(comment-intro . 0)
(arglist-close . c-lineup-arglist)
(topmost-intro . 0)
(block-open . 0)
(inline-open . 0)
(substatement-open . 0)
(statement-cont
.
(,(when (fboundp 'c-no-indent-after-java-annotations)
'c-no-indent-after-java-annotations)
,(when (fboundp 'c-lineup-assignments)
'c-lineup-assignments)
++))
(label . /)
(case-label . +)
(statement-case-open . +)
(statement-case-intro . +) ; case w/o {
(access-label . /)
(innamespace . 0))))
"Google C/C++ Programming Style.")
;;;###autoload
(defun google-set-c-style ()
"Set the current buffer's c-style to Google C/C++ Programming
Style. Meant to be added to `c-mode-common-hook'."
(interactive)
(make-local-variable 'c-tab-always-indent)
(setq c-tab-always-indent t)
(c-add-style "Google" google-c-style t))
;;;###autoload
(defun google-make-newline-indent ()
"Sets up preferred newline behavior. Not set by default. Meant
to be added to `c-mode-common-hook'."
(interactive)
(define-key c-mode-base-map "\C-m" 'newline-and-indent)
(define-key c-mode-base-map [ret] 'newline-and-indent))
(provide 'google-c-style)
;;; google-c-style.el ends here

18
google-r-style.html Normal file
View File

@ -0,0 +1,18 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf8">
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<meta http-equiv="refresh" content="1; url=Rguide.xml">
<title>Redirecting</title>
</head>
<!-- The BODY onLoad redirect is the best: it preserves #fragments and
?queries. But it requires javascript. If that fails, the
meta-refresh kicks in; it works more generally, but loses fragments
and queries, takes a second, and pollutes the browser history.
If they both fail, we let the user manually click on the new link.
-->
<body onload="location.replace(location.href.replace('google-r-style.html', 'Rguide.xml'))">
Redirecting you to <a href="Rguide.xml">Rguide.xml</a>.
</body>
</html>

877
htmlcssguide.html Normal file
View File

@ -0,0 +1,877 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Google HTML/CSS Style Guide</title>
<link rel="stylesheet" href="javaguide.css">
<script src="include/styleguide.js"></script>
<link rel="shortcut icon" href="https://www.google.com/favicon.ico">
<script src="include/jsguide.js"></script>
</head>
<body onload="initStyleGuide();">
<div id="content">
<h1>Google HTML/CSS Style Guide</h1>
<h2 id="Background">1 Background</h2>
<p>This document defines formatting and style rules for HTML and CSS. It aims at
improving collaboration, code quality, and enabling supporting infrastructure.
It applies to raw, working files that use HTML and CSS, including GSS files.
Tools are free to obfuscate, minify, and compile as long as the general code
quality is maintained.</p>
<h2 id="General">2 General</h2>
<h3 id="General_Style_Rules">2.1 General Style Rules</h3>
<h4 id="Protocol">2.1.1 Protocol</h4>
<p>Use the HTTPS protocol for embedded resources where possible.</p>
<p>Always use the HTTPS protocol (<code>https:</code>) for images and other media
files, style sheets, and scripts, unless the respective files are not available
over HTTPS.</p>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended: omits the protocol --&gt;
&lt;script src="//ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"&gt;&lt;/script&gt;
&lt;!-- Not recommended: uses the HTTP protocol --&gt;
&lt;script src="http://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"&gt;&lt;/script&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
&lt;script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"&gt;&lt;/script&gt;
</code></pre>
<pre><code class="language-css prettyprint badcode">/* Not recommended: omits the protocol */
@import '//fonts.googleapis.com/css?family=Open+Sans';
/* Not recommended: uses the HTTP protocol */
@import 'http://fonts.googleapis.com/css?family=Open+Sans';
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
@import 'https://fonts.googleapis.com/css?family=Open+Sans';
</code></pre>
<h3 id="General_Formatting_Rules">2.2 General Formatting Rules</h3>
<h4 id="Indentation">2.2.1 Indentation</h4>
<p>Indent by 2 spaces at a time.</p>
<p>Don&#8217;t use tabs or mix tabs and spaces for indentation.</p>
<pre><code class="language-html prettyprint">&lt;ul&gt;
&lt;li&gt;Fantastic
&lt;li&gt;Great
&lt;/ul&gt;
</code></pre>
<pre><code class="language-css prettyprint">.example {
color: blue;
}
</code></pre>
<h4 id="Capitalization">2.2.2 Capitalization</h4>
<p>Use only lowercase.</p>
<p>All code has to be lowercase: This applies to HTML element names, attributes,
attribute values (unless <code>text/CDATA</code>), CSS selectors, properties, and property
values (with the exception of strings).</p>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended --&gt;
&lt;A HREF="/"&gt;Home&lt;/A&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
&lt;img src="google.png" alt="Google"&gt;
</code></pre>
<pre><code class="language-css prettyprint badcode">/* Not recommended */
color: #E5E5E5;
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
color: #e5e5e5;
</code></pre>
<h4 id="Trailing_Whitespace">2.2.3 Trailing Whitespace</h4>
<p>Remove trailing white spaces.</p>
<p>Trailing white spaces are unnecessary and can complicate diffs.</p>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended --&gt;
&lt;p&gt;What?_
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
&lt;p&gt;Yes please.
</code></pre>
<h3 id="General_Meta_Rules">2.3 General Meta Rules</h3>
<h4 id="Encoding">2.3.1 Encoding</h4>
<p>Use UTF-8 (no BOM).</p>
<p>Make sure your editor uses UTF-8 as character encoding, without a byte order
mark.</p>
<p>Specify the encoding in HTML templates and documents via <code>&lt;meta
charset="utf-8"&gt;</code>. Do not specify the encoding of style sheets as these assume
UTF-8.</p>
<p>(More on encodings and when and how to specify them can be found in <a href="https://www.w3.org/International/tutorials/tutorial-char-enc/">Handling
character encodings in HTML and CSS</a>.)</p>
<h4 id="Comments">2.3.2 Comments</h4>
<p>Explain code as needed, where possible.</p>
<p>Use comments to explain code: What does it cover, what purpose does it serve,
why is respective solution used or preferred?</p>
<p>(This item is optional as it is not deemed a realistic expectation to always
demand fully documented code. Mileage may vary heavily for HTML and CSS code and
depends on the project&#8217;s complexity.)</p>
<h4 id="Action_Items">2.3.3 Action Items</h4>
<p>Mark todos and action items with <code>TODO</code>.</p>
<p>Highlight todos by using the keyword <code>TODO</code> only, not other common formats like
<code>@@</code>.</p>
<p>Append a contact (username or mailing list) in parentheses as with the format
<code>TODO(contact)</code>.</p>
<p>Append action items after a colon as in <code>TODO: action item</code>.</p>
<pre><code class="language-django prettyprint external">{# TODO(john.doe): revisit centering #}
&lt;center&gt;Test&lt;/center&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- TODO: remove optional tags --&gt;
&lt;ul&gt;
&lt;li&gt;Apples&lt;/li&gt;
&lt;li&gt;Oranges&lt;/li&gt;
&lt;/ul&gt;
</code></pre>
<h2 id="HTML">3 HTML</h2>
<h3 id="HTML_Style_Rules">3.1 HTML Style Rules</h3>
<h4 id="Document_Type">3.1.1 Document Type</h4>
<p>Use HTML5.</p>
<p>HTML5 (HTML syntax) is preferred for all HTML documents: <code>&lt;!DOCTYPE html&gt;</code>.</p>
<p>(It&#8217;s recommended to use HTML, as <code>text/html</code>. Do not use XHTML. XHTML, as
<a href="https://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>, lacks both browser
and infrastructure support and offers less room for optimization than HTML.)</p>
<p>Although fine with HTML, do not close void elements, i.e. write <code>&lt;br&gt;</code>, not
<code>&lt;br /&gt;</code>.</p>
<h4 id="HTML_Validity">3.1.2 HTML Validity</h4>
<p>Use valid HTML where possible.</p>
<p>Use valid HTML code unless that is not possible due to otherwise unattainable
performance goals regarding file size.</p>
<p>
Use tools such as the <a href="https://validator.w3.org/nu/">W3C HTML validator</a>
to test.
</p>
<p>Using valid HTML is a measurable baseline quality attribute that contributes to
learning about technical requirements and constraints, and that ensures proper
HTML usage.</p>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended --&gt;
&lt;title&gt;Test&lt;/title&gt;
&lt;article&gt;This is only a test.
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
&lt;!DOCTYPE html&gt;
&lt;meta charset="utf-8"&gt;
&lt;title&gt;Test&lt;/title&gt;
&lt;article&gt;This is only a test.&lt;/article&gt;
</code></pre>
<h4 id="Semantics">3.1.3 Semantics</h4>
<p>Use HTML according to its purpose.</p>
<p>Use elements (sometimes incorrectly called &#8220;tags&#8221;) for what they have been
created for. For example, use heading elements for headings, <code>p</code> elements for
paragraphs, <code>a</code> elements for anchors, etc.</p>
<p>Using HTML according to its purpose is important for accessibility, reuse, and
code efficiency reasons.</p>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended --&gt;
&lt;div onclick="goToRecommendations();"&gt;All recommendations&lt;/div&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
&lt;a href="recommendations/"&gt;All recommendations&lt;/a&gt;
</code></pre>
<h4 id="Multimedia_Fallback">3.1.4 Multimedia Fallback</h4>
<p>Provide alternative contents for multimedia.</p>
<p>For multimedia, such as images, videos, animated objects via <code>canvas</code>, make sure
to offer alternative access. For images that means use of meaningful alternative
text (<code>alt</code>) and for video and audio transcripts and captions, if available.</p>
<p>Providing alternative contents is important for accessibility reasons: A blind
user has few cues to tell what an image is about without <code>@alt</code>, and other users
may have no way of understanding what video or audio contents are about either.</p>
<p>(For images whose <code>alt</code> attributes would introduce redundancy, and for images
whose purpose is purely decorative which you cannot immediately use CSS for, use
no alternative text, as in <code>alt=""</code>.)</p>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended --&gt;
&lt;img src="spreadsheet.png"&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
&lt;img src="spreadsheet.png" alt="Spreadsheet screenshot."&gt;
</code></pre>
<h4 id="Separation_of_Concerns">3.1.5 Separation of Concerns</h4>
<p>Separate structure from presentation from behavior.</p>
<p>Strictly keep structure (markup), presentation (styling), and behavior
(scripting) apart, and try to keep the interaction between the three to an
absolute minimum.</p>
<p>That is, make sure documents and templates contain only HTML and HTML that is
solely serving structural purposes. Move everything presentational into style
sheets, and everything behavioral into scripts.</p>
<p>In addition, keep the contact area as small as possible by linking as few style
sheets and scripts as possible from documents and templates.</p>
<p>Separating structure from presentation from behavior is important for
maintenance reasons. It is always more expensive to change HTML documents and
templates than it is to update style sheets and scripts.</p>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended --&gt;
&lt;!DOCTYPE html&gt;
&lt;title&gt;HTML sucks&lt;/title&gt;
&lt;link rel="stylesheet" href="base.css" media="screen"&gt;
&lt;link rel="stylesheet" href="grid.css" media="screen"&gt;
&lt;link rel="stylesheet" href="print.css" media="print"&gt;
&lt;h1 style="font-size: 1em;"&gt;HTML sucks&lt;/h1&gt;
&lt;p&gt;I&#8217;ve read about this on a few sites but now I&#8217;m sure:
&lt;u&gt;HTML is stupid!!1&lt;/u&gt;
&lt;center&gt;I can&#8217;t believe there&#8217;s no way to control the styling of
my website without doing everything all over again!&lt;/center&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
&lt;!DOCTYPE html&gt;
&lt;title&gt;My first CSS-only redesign&lt;/title&gt;
&lt;link rel="stylesheet" href="default.css"&gt;
&lt;h1&gt;My first CSS-only redesign&lt;/h1&gt;
&lt;p&gt;I&#8217;ve read about this on a few sites but today I&#8217;m actually
doing it: separating concerns and avoiding anything in the HTML of
my website that is presentational.
&lt;p&gt;It&#8217;s awesome!
</code></pre>
<h4 id="Entity_References">3.1.6 Entity References</h4>
<p>Do not use entity references.</p>
<p>There is no need to use entity references like <code>&amp;mdash;</code>, <code>&amp;rdquo;</code>, or
<code>&amp;#x263a;</code>, assuming the same encoding (UTF-8) is used for files and editors
as well as among teams.</p>
<p>The only exceptions apply to characters with special meaning in HTML (like <code>&lt;</code>
and <code>&amp;</code>) as well as control or &#8220;invisible&#8221; characters (like no-break spaces).</p>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended --&gt;
The currency symbol for the Euro is &amp;ldquo;&amp;eur;&amp;rdquo;.
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
The currency symbol for the Euro is &#8220;&#8364;&#8221;.
</code></pre>
<h4 id="Optional_Tags">3.1.7 Optional Tags</h4>
<p>Omit optional tags (optional).</p>
<p>For file size optimization and scannability purposes, consider omitting optional
tags. The <a href="https://html.spec.whatwg.org/multipage/syntax.html#syntax-tag-omission">HTML5 specification</a>
defines what tags can be omitted.</p>
<p>(This approach may require a grace period to be established as a wider guideline
as it&#8217;s significantly different from what web developers are typically taught.
For consistency and simplicity reasons it&#8217;s best served omitting all optional
tags, not just a selection.)</p>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended --&gt;
&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;Spending money, spending bytes&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;p&gt;Sic.&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
&lt;!DOCTYPE html&gt;
&lt;title&gt;Saving money, saving bytes&lt;/title&gt;
&lt;p&gt;Qed.
</code></pre>
<h4 id="type_Attributes">3.1.8 <code>type</code> Attributes</h4>
<p>Omit <code>type</code> attributes for style sheets and scripts.</p>
<p>Do not use <code>type</code> attributes for style sheets (unless not using CSS) and scripts
(unless not using JavaScript).</p>
<p>Specifying <code>type</code> attributes in these contexts is not necessary as HTML5 implies
<a href="https://html.spec.whatwg.org/multipage/obsolete.html#attr-style-type"><code>text/css</code></a>
and <a href="https://html.spec.whatwg.org/multipage/scripting.html#attr-script-type"><code>text/javascript</code></a>
as defaults. This can be safely done even for older browsers.</p>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended --&gt;
&lt;link rel="stylesheet" href="https://www.google.com/css/maia.css"
type="text/css"&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
&lt;link rel="stylesheet" href="https://www.google.com/css/maia.css"&gt;
</code></pre>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended --&gt;
&lt;script src="https://www.google.com/js/gweb/analytics/autotrack.js"
type="text/javascript"&gt;&lt;/script&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
&lt;script src="https://www.google.com/js/gweb/analytics/autotrack.js"&gt;&lt;/script&gt;
</code></pre>
<h3 id="HTML_Formatting_Rules">3.2 HTML Formatting Rules</h3>
<h4 id="General_Formatting">3.2.1 General Formatting</h4>
<p>Use a new line for every block, list, or table element, and indent every such
child element.</p>
<p>Independent of the styling of an element (as CSS allows elements to assume a
different role per <code>display</code> property), put every block, list, or table element
on a new line.</p>
<p>Also, indent them if they are child elements of a block, list, or table element.</p>
<p>(If you run into issues around whitespace between list items it&#8217;s acceptable to
put all <code>li</code> elements in one line. A linter is encouraged to throw a warning
instead of an error.)</p>
<pre><code class="language-html prettyprint">&lt;blockquote&gt;
&lt;p&gt;&lt;em&gt;Space&lt;/em&gt;, the final frontier.&lt;/p&gt;
&lt;/blockquote&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;ul&gt;
&lt;li&gt;Moe
&lt;li&gt;Larry
&lt;li&gt;Curly
&lt;/ul&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th scope="col"&gt;Income
&lt;th scope="col"&gt;Taxes
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;$ 5.00
&lt;td&gt;$ 4.50
&lt;/table&gt;
</code></pre>
<h4 id="HTML_Line-Wrapping">3.2.2 HTML Line-Wrapping</h4>
<p>Break long lines (optional).</p>
<p>While there is no column limit recommendation for HTML, you may consider
wrapping long lines if it significantly improves readability.</p>
<p>When line-wrapping, each continuation line should be indented at least 4
additional spaces from the original line.</p>
<pre><code class="language-html prettyprint">&lt;md-progress-circular md-mode="indeterminate" class="md-accent"
ng-show="ctrl.loading" md-diameter="35"&gt;
&lt;/md-progress-circular&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;md-progress-circular
md-mode="indeterminate"
class="md-accent"
ng-show="ctrl.loading"
md-diameter="35"&gt;
&lt;/md-progress-circular&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;md-progress-circular md-mode="indeterminate"
class="md-accent"
ng-show="ctrl.loading"
md-diameter="35"&gt;
&lt;/md-progress-circular&gt;
</code></pre>
<h4 id="HTML_Quotation_Marks">3.2.3 HTML Quotation Marks</h4>
<p>When quoting attributes values, use double quotation marks.</p>
<p>Use double (<code>""</code>) rather than single quotation marks (<code>''</code>) around attribute
values.</p>
<pre><code class="language-html prettyprint badcode">&lt;!-- Not recommended --&gt;
&lt;a class='maia-button maia-button-secondary'&gt;Sign in&lt;/a&gt;
</code></pre>
<pre><code class="language-html prettyprint">&lt;!-- Recommended --&gt;
&lt;a class="maia-button maia-button-secondary"&gt;Sign in&lt;/a&gt;
</code></pre>
<h2 id="CSS">4 CSS</h2>
<h3 id="CSS_Style_Rules">4.1 CSS Style Rules</h3>
<h4 id="CSS_Validity">4.1.1 CSS Validity</h4>
<p>Use valid CSS where possible.</p>
<p>Unless dealing with CSS validator bugs or requiring proprietary syntax, use
valid CSS code.</p>
<p>
Use tools such as the <a href="https://jigsaw.w3.org/css-validator/">W3C CSS validator</a>
to test.
</p>
<p>Using valid CSS is a measurable baseline quality attribute that allows to spot
CSS code that may not have any effect and can be removed, and that ensures
proper CSS usage.</p>
<h4 id="ID_and_Class_Naming">4.1.2 ID and Class Naming</h4>
<p>Use meaningful or generic ID and class names.</p>
<p>Instead of presentational or cryptic names, always use ID and class names that
reflect the purpose of the element in question, or that are otherwise generic.</p>
<p>Names that are specific and reflect the purpose of the element should be
preferred as these are most understandable and the least likely to change.</p>
<p>Generic names are simply a fallback for elements that have no particular or no
meaning different from their siblings. They are typically needed as &#8220;helpers.&#8221;</p>
<p>Using functional or generic names reduces the probability of unnecessary
document or template changes.</p>
<pre><code class="language-css prettyprint badcode">/* Not recommended: meaningless */
#yee-1901 {}
/* Not recommended: presentational */
.button-green {}
.clear {}
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended: specific */
#gallery {}
#login {}
.video {}
/* Recommended: generic */
.aux {}
.alt {}
</code></pre>
<h4 id="ID_and_Class_Name_Style">4.1.3 ID and Class Name Style</h4>
<p>Use ID and class names that are as short as possible but as long as necessary.</p>
<p>Try to convey what an ID or class is about while being as brief as possible.</p>
<p>Using ID and class names this way contributes to acceptable levels of
understandability and code efficiency.</p>
<pre><code class="language-css prettyprint badcode">/* Not recommended */
#navigation {}
.atr {}
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
#nav {}
.author {}
</code></pre>
<h4 id="Type_Selectors">4.1.4 Type Selectors</h4>
<p>Avoid qualifying ID and class names with type selectors.</p>
<p>Unless necessary (for example with helper classes), do not use element names in
conjunction with IDs or classes.</p>
<p>Avoiding unnecessary ancestor selectors is useful for <a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance reasons</a>.</p>
<pre><code class="language-css prettyprint badcode">/* Not recommended */
ul#example {}
div.error {}
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
#example {}
.error {}
</code></pre>
<h4 id="Shorthand_Properties">4.1.5 Shorthand Properties</h4>
<p>Use shorthand properties where possible.</p>
<p>CSS offers a variety of <a href="https://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
properties (like <code>font</code>) that should be used whenever possible, even in cases
where only one value is explicitly set.</p>
<p>Using shorthand properties is useful for code efficiency and understandability.</p>
<pre><code class="language-css prettyprint badcode">/* Not recommended */
border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%;
line-height: 1.6;
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;
</code></pre>
<h4 id="0_and_Units">4.1.6 0 and Units</h4>
<p>Omit unit specification after &#8220;0&#8221; values, unless required.</p>
<p>Do not use units after <code>0</code> values unless they are required.</p>
<pre><code class="language-css prettyprint">flex: 0px; /* This flex-basis component requires a unit. */
flex: 1 1 0px; /* Not ambiguous without the unit, but needed in IE11. */
margin: 0;
padding: 0;
</code></pre>
<h4 id="Leading_0s">4.1.7 Leading 0s</h4>
<p>Omit leading &#8220;0&#8221;s in values.</p>
<p>Do not put <code>0</code>s in front of values or lengths between -1 and 1.</p>
<pre><code class="language-css prettyprint">font-size: .8em;
</code></pre>
<h4 id="Hexadecimal_Notation">4.1.8 Hexadecimal Notation</h4>
<p>Use 3 character hexadecimal notation where possible.</p>
<p>For color values that permit it, 3 character hexadecimal notation is shorter and
more succinct.</p>
<pre><code class="language-css prettyprint badcode">/* Not recommended */
color: #eebbcc;
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
color: #ebc;
</code></pre>
<h4 id="Prefixes">4.1.9 Prefixes</h4>
<p>Prefix selectors with an application-specific prefix (optional).</p>
<p>In large projects as well as for code that gets embedded in other projects or on
external sites use prefixes (as namespaces) for ID and class names. Use short,
unique identifiers followed by a dash.</p>
<p>Using namespaces helps preventing naming conflicts and can make maintenance
easier, for example in search and replace operations.</p>
<pre><code class="language-css prettyprint">.adw-help {} /* AdWords */
#maia-note {} /* Maia */
</code></pre>
<h4 id="ID_and_Class_Name_Delimiters">4.1.10 ID and Class Name Delimiters</h4>
<p>Separate words in ID and class names by a hyphen.</p>
<p>Do not concatenate words and abbreviations in selectors by any characters
(including none at all) other than hyphens, in order to improve understanding
and scannability.</p>
<pre><code class="language-css prettyprint badcode">/* Not recommended: does not separate the words &#8220;demo&#8221; and &#8220;image&#8221; */
.demoimage {}
/* Not recommended: uses underscore instead of hyphen */
.error_status {}
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
#video-id {}
.ads-sample {}
</code></pre>
<h4 id="Hacks">4.1.11 Hacks</h4>
<p>Avoid user agent detection as well as CSS &#8220;hacks&#8221;&#8212;try a different approach
first.</p>
<p>It&#8217;s tempting to address styling differences over user agent detection or
special CSS filters, workarounds, and hacks. Both approaches should be
considered last resort in order to achieve and maintain an efficient and
manageable code base. Put another way, giving detection and hacks a free pass
will hurt projects in the long run as projects tend to take the way of least
resistance. That is, allowing and making it easy to use detection and hacks
means using detection and hacks more frequently&#8212;and more frequently is too
frequently.</p>
<h3 id="CSS_Formatting_Rules">4.2 CSS Formatting Rules</h3>
<h4 id="Declaration_Order">4.2.1 Declaration Order</h4>
<p>Alphabetize declarations.</p>
<p>Put declarations in alphabetical order in order to achieve consistent code in a
way that is easy to remember and maintain.</p>
<p>Ignore vendor-specific prefixes for sorting purposes. However, multiple
vendor-specific prefixes for a certain CSS property should be kept sorted (e.g.
-moz prefix comes before -webkit).</p>
<pre><code class="language-css prettyprint">background: fuchsia;
border: 1px solid;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
border-radius: 4px;
color: black;
text-align: center;
text-indent: 2em;
</code></pre>
<h4 id="Block_Content_Indentation">4.2.2 Block Content Indentation</h4>
<p>Indent all block content.</p>
<p>Indent all <a href="https://www.w3.org/TR/CSS21/syndata.html#block">block content</a>,
that is rules within rules as well as declarations, so to reflect hierarchy and
improve understanding.</p>
<pre><code class="language-css prettyprint">@media screen, projection {
html {
background: #fff;
color: #444;
}
}
</code></pre>
<h4 id="Declaration_Stops">4.2.3 Declaration Stops</h4>
<p>Use a semicolon after every declaration.</p>
<p>End every declaration with a semicolon for consistency and extensibility
reasons.</p>
<pre><code class="language-css prettyprint badcode">/* Not recommended */
.test {
display: block;
height: 100px
}
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
.test {
display: block;
height: 100px;
}
</code></pre>
<h4 id="Property_Name_Stops">4.2.4 Property Name Stops</h4>
<p>Use a space after a property name&#8217;s colon.</p>
<p>Always use a single space between property and value (but no space between
property and colon) for consistency reasons.</p>
<pre><code class="language-css prettyprint badcode">/* Not recommended */
h3 {
font-weight:bold;
}
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
h3 {
font-weight: bold;
}
</code></pre>
<h4 id="Declaration_Block_Separation">4.2.5 Declaration Block Separation</h4>
<p>Use a space between the last selector and the declaration block.</p>
<p>Always use a single space between the last selector and the opening brace that
begins the <a href="https://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration block</a>.</p>
<p>The opening brace should be on the same line as the last selector in a given
rule.</p>
<pre><code class="language-css prettyprint badcode">/* Not recommended: missing space */
#video{
margin-top: 1em;
}
/* Not recommended: unnecessary line break */
#video
{
margin-top: 1em;
}
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
#video {
margin-top: 1em;
}
</code></pre>
<h4 id="Selector_and_Declaration_Separation">4.2.6 Selector and Declaration Separation</h4>
<p>Separate selectors and declarations by new lines.</p>
<p>Always start a new line for each selector and declaration.</p>
<pre><code class="language-css prettyprint badcode">/* Not recommended */
a:focus, a:active {
position: relative; top: 1px;
}
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
h1,
h2,
h3 {
font-weight: normal;
line-height: 1.2;
}
</code></pre>
<h4 id="Rule_Separation">4.2.7 Rule Separation</h4>
<p>Separate rules by new lines.</p>
<p>Always put a blank line (two line breaks) between rules.</p>
<pre><code class="language-css prettyprint">html {
background: #fff;
}
body {
margin: auto;
width: 50%;
}
</code></pre>
<h4 id="CSS_Quotation_Marks">4.2.8 CSS Quotation Marks</h4>
<p>Use single (<code>''</code>) rather than double (<code>""</code>) quotation marks for attribute
selectors and property values.</p>
<p>Do not use quotation marks in URI values (<code>url()</code>).</p>
<p>Exception: If you do need to use the <code>@charset</code> rule, use double quotation
marks&#8212;<a href="https://www.w3.org/TR/CSS21/syndata.html#charset">single quotation marks are not permitted</a>.</p>
<pre><code class="language-css prettyprint badcode">/* Not recommended */
@import url("https://www.google.com/css/maia.css");
html {
font-family: "open sans", arial, sans-serif;
}
</code></pre>
<pre><code class="language-css prettyprint">/* Recommended */
@import url(https://www.google.com/css/maia.css);
html {
font-family: 'open sans', arial, sans-serif;
}
</code></pre>
<h3 id="CSS_Meta_Rules">4.3 CSS Meta Rules</h3>
<h4 id="Section_Comments">4.3.1 Section Comments</h4>
<p>Group sections by a section comment (optional).</p>
<p>If possible, group style sheet sections together by using comments. Separate
sections with new lines.</p>
<pre><code class="language-css prettyprint">/* Header */
#adw-header {}
/* Footer */
#adw-footer {}
/* Gallery */
.adw-gallery {}
</code></pre>
<h2 id="Parting_Words">Parting Words</h2>
<p><em>Be consistent.</em></p>
<p>If you&#8217;re editing code, take a few minutes to look at the code around you and
determine its style. If they use spaces around all their arithmetic operators,
you should too. If their comments have little boxes of hash marks around them,
make your comments have little boxes of hash marks around them too.</p>
<p>The point of having style guidelines is to have a common vocabulary of coding so
people can concentrate on what you&#8217;re saying rather than on how you&#8217;re saying
it. We present global style rules here so people know the vocabulary, but local
style is also important. If code you add to a file looks drastically different
from the existing code around it, it throws readers out of their rhythm when
they go to read it. Avoid this.</p>
</div>
</body>
</html>

8
htmlcssguide.xml Normal file
View File

@ -0,0 +1,8 @@
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
<GUIDE title="Google HTML/CSS Style Guide">
<p>
The style guide has moved to
<a href="htmlcssguide.html">htmlcssguide.html</a>
</p>
</GUIDE>

56
include/jsguide.js Normal file
View File

@ -0,0 +1,56 @@
window.initStyleGuide = function(init) {
// Runs the callback on every element matched by the query selector.
function find(querySelector, callback) {
var elements = [].slice.call(document.querySelectorAll(querySelector));
for (var i = 0; i < elements.length; i++) {
callback(elements[i]);
}
}
// Add the tocDiv at the top.
var title = document.getElementsByTagName('h1')[0];
var toc = document.createElement('div');
toc.id = 'tocDiv';
toc.className = 'vertical_toc';
title.parentNode.insertBefore(toc, title.nextSibling);
// If a paragraph starts with (e.g.) "Note:" or "Tip:" then add
// that "callout class" to its element.
find('p', function(paragraph) {
var match = /^([a-z]+):/i.exec(paragraph.textContent);
if (match) {
paragraph.classList.add(match[1].toLowerCase());
}
});
// Fill in text for intra-document links, ensuring that links
// remain up-to-date even if sections are moved or renumbered.
// This triggers on any link with "??" as its text and a URL
// starting with "#", and the filled-in text is exactly the same
// as the text of the referenced section heading.
find('a[href^="#"]', function(link) {
var href = link.getAttribute('href');
var heading = document.getElementById(href.substring(1));
// Fill in link text with heading title
if (heading && link.textContent == '??') {
link.textContent = heading.textContent;
}
});
// Hoedown renders fenced code blocks incompatibly with what
// prettify expects. As a result, prettify doesn't handle them
// properly. Fix it by moving the code directly into the pre.
find('pre > code', function(code) {
var pre = code.parentElement;
pre.className = code.className;
pre.innerHTML = code.innerHTML;
});
// Run the normal init function.
init();
// Call the pretty-printer after we've fixed up the code blocks.
var pretty = document.createElement('script');
pretty.src = 'https://cdn.rawgit.com/google/code-prettify/master/loader/' +
'run_prettify.js';
document.body.appendChild(pretty);
}.bind(null, window.initStyleGuide);

BIN
include/link.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 189 B

261
include/styleguide.css Normal file
View File

@ -0,0 +1,261 @@
/* General CSS */
body {
background-color: #fff;
color: #333;
font-family: sans-serif;
font-size: 10pt;
margin-right: 100px;
margin-left: 100px;
}
h1 {
text-align: center;
font-size: 18pt;
}
h1, h2, h3, h4, h5, h6 {
color: #06c;
margin-top: 2em;
margin-bottom: 1em;
padding: 25px;
font-weight:bold;
}
h2,
h3,
h4,
h5,
h6 {
margin-top:1.5em;
margin-bottom:.75em;
}
h1 {font-size:200%;}
h2 {font-size:167%;}
h3 {font-size:133%;}
h4 {font-size:120%;}
h5 {font-size:110%;}
table {
border: 1px solid #bbb;
border-spacing: 0;
border-collapse: collapse;
margin: 0 0 1.5em;
vertical-align: middle;
width: 100%
}
td, th {
border: 1px solid #ccc;
padding: 2px 12px;
font-size: 10pt;
}
code, samp, var {
background-color:#FAFAFA;
white-space: nowrap
}
pre {
padding:6px 10px;
background-color:#FAFAFA;
border:1px solid #bbb;
overflow:auto;
}
pre.prettyprint {
padding:6px 10px !important;
border:1px solid #bbb !important;
}
code.bad, code.badcode {
color: magenta;
}
pre.bad, pre.badcode {
background-color:#ffe6d8;
border-top:1px inset #a03;
border-left:1px inset #a03;
}
hr {
margin-top: 3.5em;
border-width: 1px;
color: #fff;
}
/* TOC CSS */
table.columns {
border: none;
}
td.two_columns {
-webkit-column-count: 2;
column-count: 2;
}
.toc_category {
font-size: 10pt;
padding-top: 1em;
padding-bottom: 1em;
border-left-width: 2px;
border-right-width: 2px;
border-color: grey;
}
.toc_stylepoint {
font-size: 10pt;
padding-top: 1em;
padding-bottom: 1em;
}
li.toc_entry {
padding-right: 1em;
display: inline;
list-style-type: none;
}
/*
* This space is required to trigger the linewrap on the links
* at href boundaries
*/
li.toc_entry::after {
content: " ";
}
li.toc_entry a {
white-space: nowrap;
}
/* Horizontal TOC */
.toc td, .toc th {
border-width: 1px 5px;
overflow: hidden;
}
/* Vertical TOC */
.toc td.two_columns {
border-width: 0px;
}
/* Special Sections */
address {
text-align: right;
}
.revision {
text-align: right;
}
.headerbox {
margin-left: 50%;
font-size: 75%;
}
.legend {
padding-top: 1em;
margin-left: 50%;
font-size: 10pt;
}
.link_button {
float: left;
display: none;
background-color: #f8f8ff;
border-color: #f0f0ff;
border-style: solid;
border-width: 1px;
font-size: 75%;
margin-top: 0;
margin-left: -50px;
padding: 24px;
border-radius: 3px;
-webkit-border-radius: 3px;
-moz-border-radius: 3px;
}
.ignoreLink {
padding: 0px;
}
.divider{
width:5px;
height:auto;
display:inline-block;
}
/* Style Guide semantic CSS */
.summary {
margin-top: 1em;
margin-bottom: 1em;
}
.stylebody {
margin-top: 1em;
margin-bottom: 1em;
}
.stylepoint_section {
display: block;
margin-bottom: 1em;
font-family: sans-serif;
font-weight: bold;
}
.stylepoint_subsection {
display: block;
margin-bottom: 1em;
}
.stylepoint_subsubsection {
display: block;
margin-bottom: 1em;
}
.definition:before {
content: "Definition: ";
font-weight: bold;
display: block;
margin-bottom: 1em;
}
.pros:before {
content: "Pros: ";
font-weight: bold;
display: block;
margin-bottom: 1em;
}
.cons:before {
content: "Cons: ";
font-weight: bold;
display: block;
margin-bottom: 1em;
}
.decision:before {
content: "Decision: ";
font-weight: bold;
display: block;
margin-bottom: 1em;
}
.exception:before {
content: "Exception: ";
font-weight: bold;
display: block;
margin-bottom: 1em;
}
.note:before {
content: "Note: ";
font-weight: bold;
display: block;
margin-bottom: 1em;
}

289
include/styleguide.js Normal file
View File

@ -0,0 +1,289 @@
TocTypeEnum = {
VERTICAL: 1,
HORIZONTAL: 2
};
function CreateTOC(tocElement) {
// Find the toc element DIV. We'll place our TOC there.
var toc = document.getElementById(tocElement);
var tocTypeClass = toc.className;
var tocType;
switch (tocTypeClass) {
case 'horizontal_toc':
tocType = TocTypeEnum.HORIZONTAL;
break;
case 'vertical_toc':
tocType = TocTypeEnum.VERTICAL;
break;
default:
tocType = TocTypeEnum.VERTICAL;
break;
}
// If toc_levels is defined, set headingLevels to it.
// Otherwise, use default value of "h2,h3"
var headingLevels;
if (typeof toc_levels === 'undefined') {
headingLevels = 'h2,h3';
} else {
}
// Collect all section heading elements in an array
var headings = document.querySelectorAll(headingLevels);
// Add TOC title elements
var tocHeadingDiv = document.createElement('div');
toc.appendChild(tocHeadingDiv);
tocHeadingDiv.className = 'toc_title';
var tocHeading = document.createElement('h3');
toc.appendChild(tocHeading);
tocHeading.className = 'ignoreLink';
tocHeading.id = 'toc';
var tocText = document.createTextNode('Table of Contents');
tocHeading.appendChild(tocText);
// Add table and tbody
var tocTable = document.createElement('table');
if (tocType == TocTypeEnum.VERTICAL) {
tocTable.className = 'columns';
}
toc.appendChild(tocTable);
var tbody_element = document.createElement('tbody');
tbody_element.setAttribute('valign', 'top');
tbody_element.className = 'toc';
tocTable.appendChild(tbody_element);
// Get the highest level heading
var firstHeading = headings[0];
var masterLevel = parseInt(headingLevels.charAt(1));
// Get the lowest heading level
var lowestLevel = parseInt(headingLevels.charAt(headingLevels - 1));
switch (tocType) {
case TocTypeEnum.HORIZONTAL:
CreateHorizontalTOC(headings, masterLevel, lowestLevel, tbody_element);
break;
case TocTypeEnum.VERTICAL:
CreateVerticalTOC(headings, masterLevel, lowestLevel, tbody_element);
break;
default:
}
}
function CreateHorizontalTOC(
headings, masterLevel, lowestLevel, tbody_element) {
// Initialize the header counter
var h = 0;
var ignoreChildren = false;
while (h < headings.length) {
// Get current heading
var heading = headings[h];
// Get the current heading level
var level = parseInt(heading.tagName.charAt(1));
if (isNaN(level) || level < 1 || level > lowestLevel) continue;
// If level is a masterLevel, make it a TOC parent category
if ((level == masterLevel) && (!hasClass(heading, 'ignoreLink'))) {
toc_current_row = AddTOCMaster(tbody_element, heading);
ignoreChildren = false;
}
if ((level == masterLevel) && (hasClass(heading, 'ignoreLink'))) {
ignoreChildren = true;
}
if ((level != masterLevel) && (!ignoreChildren)) {
AddTOCElements(toc_current_row, heading);
}
// Advance the header counter
h++;
}
}
// Adds a master Table of Content heading
function AddTOCMaster(tocTable, heading) {
// Add the table row scaffolding
var toc_tr = document.createElement('tr');
tocTable.appendChild(toc_tr);
toc_tr.setAttribute('valign', 'top');
var toc_tr_td = document.createElement('td');
toc_tr.appendChild(toc_tr_td);
var toc_category = document.createElement('div');
toc_tr_td.appendChild(toc_category);
toc_category.className = 'toc_category';
// Create the link to this header
var link = document.createElement('a');
link.href = '#' + heading.id; // Create the anchor link
link.textContent = heading.textContent; // Link text is same as heading
toc_category.appendChild(link);
// Add the container table cell for its children
var toc_td = document.createElement('td');
toc_tr.appendChild(toc_td);
var toc_td_div = document.createElement('div');
toc_td_div.className = 'toc_stylepoint';
toc_td.appendChild(toc_td_div);
return (toc_td_div);
}
// Adds Table of Contents element to a master heading as children
function AddTOCElements(toc_div, heading) {
if (heading.offsetParent === null) {
// The element is currently hidden, so don't create a TOC entry
} else {
// Create the list item element
var toc_list_element = document.createElement('li');
toc_list_element.className = 'toc_entry';
toc_div.appendChild(toc_list_element);
// Create the link to this header
var link = document.createElement('a');
link.href = '#' + heading.id; // Create the anchor link
link.textContent = heading.textContent; // Link text is same as heading
toc_list_element.appendChild(link);
}
}
function CreateVerticalTOC(headings, masterLevel, lowestLevel, tbody_element) {
// Create the Column scaffolding
var toc_tr = document.createElement('tr');
tbody_element.appendChild(toc_tr);
var toc_tr_td = document.createElement('td');
toc_tr_td.className = 'two_columns';
toc_tr.appendChild(toc_tr_td);
// Initialize the header counter and the current row
var h = 0;
var toc_current_col = null;
var ignoreChildren = false;
while (h < headings.length) {
// Get current heading
var heading = headings[h];
// Get the current heading level
var level = parseInt(heading.tagName.charAt(1));
if (isNaN(level) || level < 1 || level > lowestLevel) continue;
// If level is a masterLevel, make it a TOC parent category
if ((level == masterLevel) && (!hasClass(heading, 'ignoreLink'))) {
if (heading.offsetParent === null) {
// The element is currently hidden, so don't create a TOC entry
} else {
var td_dl = document.createElement('dl');
toc_tr_td.appendChild(td_dl);
var td_dt = document.createElement('dt');
td_dl.appendChild(td_dt);
toc_current_col = td_dl;
// Create the link to this header
var link = document.createElement('a');
link.href = '#' + heading.id; // Create the anchor link
link.textContent = heading.textContent; // Link text is same as heading
td_dt.appendChild(link);
ignoreChildren = false;
}
}
// If level is a masterLevel but it's specified to ignore links, skip it
// and its children.
if ((level == masterLevel) && (hasClass(heading, 'ignoreLink'))) {
ignoreChildren = true;
}
if ((level != masterLevel) && (!ignoreChildren)) {
if (heading.offsetParent === null) {
// The element is currently hidden, so don't create a TOC entry
} else {
var td_dd = document.createElement('dd');
toc_current_col.appendChild(td_dd);
// Create the link to this header
var link = document.createElement('a');
link.href = '#' + heading.id; // Create the anchor link
link.textContent = heading.textContent; // Link text is same as heading
td_dd.appendChild(link);
}
}
// Advance the header counter
h++;
}
}
/*
* Utility function for finding elements with a given
* class.
*/
function hasClass(element, cls) {
return (' ' + element.className + ' ').indexOf(' ' + cls + ' ') > -1;
}
/*
* Linkify all h2 through h4 headers, except for those marked
* "ignoreLink"
*/
// Add the link image to the element.
function LinkifyHeader(header, fileName, sizePixels) {
var link = document.createElement('a');
link.href = '#' + header.id;
link.setAttribute('alt', 'link to ' + header.id);
link.innerHTML =
'<img src="include/' + fileName + '"' +
' width=' + sizePixels +
' height=' + sizePixels +
' style="float:left;position:relative;bottom:5px;">';
header.appendChild(link);
}
// Find all elements of the given tag and linkify if
// they don't have 'ignoreLink' in their class.
function LinkifyHeadersForTag(tagName) {
var headers = document.getElementsByTagName(tagName);
var header;
for (var j = 0; j != headers.length; j++) {
header = headers[j];
if (!hasClass(header, 'ignoreLink') && ('id' in header)) {
if (header.id != '') {
LinkifyHeader(header, 'link.png', 21);
header.style.left = '-46px';
header.style.position = 'relative';
}
}
}
}
// Linkify all h2, h3, and h4s. h1s are titles.
function LinkifyHeaders() {
LinkifyHeadersForTag('h2');
LinkifyHeadersForTag('h3');
LinkifyHeadersForTag('h4');
}
/*
* Initialize the style guide by showing all internal
* elements and then linkifying the headers.
*/
function initStyleGuide() {
LinkifyHeaders();
CreateTOC('tocDiv');
}

View File

@ -0,0 +1,598 @@
<?xml version="1.0" encoding="UTF-8"?>
<code_scheme name="GoogleStyle">
<option name="OTHER_INDENT_OPTIONS">
<value>
<option name="INDENT_SIZE" value="2" />
<option name="CONTINUATION_INDENT_SIZE" value="4" />
<option name="TAB_SIZE" value="2" />
<option name="USE_TAB_CHARACTER" value="false" />
<option name="SMART_TABS" value="false" />
<option name="LABEL_INDENT_SIZE" value="0" />
<option name="LABEL_INDENT_ABSOLUTE" value="false" />
<option name="USE_RELATIVE_INDENTS" value="false" />
</value>
</option>
<option name="INSERT_INNER_CLASS_IMPORTS" value="true" />
<option name="CLASS_COUNT_TO_USE_IMPORT_ON_DEMAND" value="999" />
<option name="NAMES_COUNT_TO_USE_IMPORT_ON_DEMAND" value="999" />
<option name="PACKAGES_TO_USE_IMPORT_ON_DEMAND">
<value />
</option>
<option name="IMPORT_LAYOUT_TABLE">
<value>
<package name="" withSubpackages="true" static="true" />
<emptyLine />
<package name="" withSubpackages="true" static="false" />
</value>
</option>
<option name="RIGHT_MARGIN" value="100" />
<option name="JD_ALIGN_PARAM_COMMENTS" value="false" />
<option name="JD_ALIGN_EXCEPTION_COMMENTS" value="false" />
<option name="JD_P_AT_EMPTY_LINES" value="false" />
<option name="JD_KEEP_EMPTY_PARAMETER" value="false" />
<option name="JD_KEEP_EMPTY_EXCEPTION" value="false" />
<option name="JD_KEEP_EMPTY_RETURN" value="false" />
<option name="KEEP_CONTROL_STATEMENT_IN_ONE_LINE" value="false" />
<option name="KEEP_BLANK_LINES_BEFORE_RBRACE" value="0" />
<option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
<option name="BLANK_LINES_AFTER_CLASS_HEADER" value="0" />
<option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
<option name="ALIGN_MULTILINE_FOR" value="false" />
<option name="CALL_PARAMETERS_WRAP" value="1" />
<option name="METHOD_PARAMETERS_WRAP" value="1" />
<option name="EXTENDS_LIST_WRAP" value="1" />
<option name="THROWS_KEYWORD_WRAP" value="1" />
<option name="METHOD_CALL_CHAIN_WRAP" value="1" />
<option name="BINARY_OPERATION_WRAP" value="1" />
<option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
<option name="TERNARY_OPERATION_WRAP" value="1" />
<option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
<option name="FOR_STATEMENT_WRAP" value="1" />
<option name="ARRAY_INITIALIZER_WRAP" value="1" />
<option name="WRAP_COMMENTS" value="true" />
<option name="IF_BRACE_FORCE" value="3" />
<option name="DOWHILE_BRACE_FORCE" value="3" />
<option name="WHILE_BRACE_FORCE" value="3" />
<option name="FOR_BRACE_FORCE" value="3" />
<option name="SPACE_BEFORE_ARRAY_INITIALIZER_LBRACE" value="true" />
<AndroidXmlCodeStyleSettings>
<option name="USE_CUSTOM_SETTINGS" value="true" />
<option name="LAYOUT_SETTINGS">
<value>
<option name="INSERT_BLANK_LINE_BEFORE_TAG" value="false" />
</value>
</option>
</AndroidXmlCodeStyleSettings>
<JSCodeStyleSettings>
<option name="INDENT_CHAINED_CALLS" value="false" />
</JSCodeStyleSettings>
<Python>
<option name="USE_CONTINUATION_INDENT_FOR_ARGUMENTS" value="true" />
</Python>
<TypeScriptCodeStyleSettings>
<option name="INDENT_CHAINED_CALLS" value="false" />
</TypeScriptCodeStyleSettings>
<XML>
<option name="XML_ALIGN_ATTRIBUTES" value="false" />
<option name="XML_LEGACY_SETTINGS_IMPORTED" value="true" />
</XML>
<codeStyleSettings language="CSS">
<indentOptions>
<option name="INDENT_SIZE" value="2" />
<option name="CONTINUATION_INDENT_SIZE" value="4" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
</codeStyleSettings>
<codeStyleSettings language="ECMA Script Level 4">
<option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
<option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
<option name="ALIGN_MULTILINE_FOR" value="false" />
<option name="CALL_PARAMETERS_WRAP" value="1" />
<option name="METHOD_PARAMETERS_WRAP" value="1" />
<option name="EXTENDS_LIST_WRAP" value="1" />
<option name="BINARY_OPERATION_WRAP" value="1" />
<option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
<option name="TERNARY_OPERATION_WRAP" value="1" />
<option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
<option name="FOR_STATEMENT_WRAP" value="1" />
<option name="ARRAY_INITIALIZER_WRAP" value="1" />
<option name="IF_BRACE_FORCE" value="3" />
<option name="DOWHILE_BRACE_FORCE" value="3" />
<option name="WHILE_BRACE_FORCE" value="3" />
<option name="FOR_BRACE_FORCE" value="3" />
<option name="PARENT_SETTINGS_INSTALLED" value="true" />
</codeStyleSettings>
<codeStyleSettings language="HTML">
<indentOptions>
<option name="INDENT_SIZE" value="2" />
<option name="CONTINUATION_INDENT_SIZE" value="4" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
</codeStyleSettings>
<codeStyleSettings language="JAVA">
<option name="KEEP_CONTROL_STATEMENT_IN_ONE_LINE" value="false" />
<option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
<option name="BLANK_LINES_AFTER_CLASS_HEADER" value="1" />
<option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
<option name="ALIGN_MULTILINE_RESOURCES" value="false" />
<option name="ALIGN_MULTILINE_FOR" value="false" />
<option name="CALL_PARAMETERS_WRAP" value="1" />
<option name="METHOD_PARAMETERS_WRAP" value="1" />
<option name="EXTENDS_LIST_WRAP" value="1" />
<option name="THROWS_KEYWORD_WRAP" value="1" />
<option name="METHOD_CALL_CHAIN_WRAP" value="1" />
<option name="BINARY_OPERATION_WRAP" value="1" />
<option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
<option name="TERNARY_OPERATION_WRAP" value="1" />
<option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
<option name="FOR_STATEMENT_WRAP" value="1" />
<option name="ARRAY_INITIALIZER_WRAP" value="1" />
<option name="WRAP_COMMENTS" value="true" />
<option name="IF_BRACE_FORCE" value="3" />
<option name="DOWHILE_BRACE_FORCE" value="3" />
<option name="WHILE_BRACE_FORCE" value="3" />
<option name="FOR_BRACE_FORCE" value="3" />
<option name="PARENT_SETTINGS_INSTALLED" value="true" />
<indentOptions>
<option name="INDENT_SIZE" value="2" />
<option name="CONTINUATION_INDENT_SIZE" value="4" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
</codeStyleSettings>
<codeStyleSettings language="JSON">
<indentOptions>
<option name="CONTINUATION_INDENT_SIZE" value="4" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
</codeStyleSettings>
<codeStyleSettings language="JavaScript">
<option name="RIGHT_MARGIN" value="80" />
<option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
<option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
<option name="ALIGN_MULTILINE_FOR" value="false" />
<option name="CALL_PARAMETERS_WRAP" value="1" />
<option name="METHOD_PARAMETERS_WRAP" value="1" />
<option name="BINARY_OPERATION_WRAP" value="1" />
<option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
<option name="TERNARY_OPERATION_WRAP" value="1" />
<option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
<option name="FOR_STATEMENT_WRAP" value="1" />
<option name="ARRAY_INITIALIZER_WRAP" value="1" />
<option name="IF_BRACE_FORCE" value="3" />
<option name="DOWHILE_BRACE_FORCE" value="3" />
<option name="WHILE_BRACE_FORCE" value="3" />
<option name="FOR_BRACE_FORCE" value="3" />
<option name="PARENT_SETTINGS_INSTALLED" value="true" />
<indentOptions>
<option name="INDENT_SIZE" value="2" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
</codeStyleSettings>
<codeStyleSettings language="PROTO">
<option name="RIGHT_MARGIN" value="80" />
<indentOptions>
<option name="INDENT_SIZE" value="2" />
<option name="CONTINUATION_INDENT_SIZE" value="2" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
</codeStyleSettings>
<codeStyleSettings language="protobuf">
<option name="RIGHT_MARGIN" value="80" />
<indentOptions>
<option name="INDENT_SIZE" value="2" />
<option name="CONTINUATION_INDENT_SIZE" value="2" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
</codeStyleSettings>
<codeStyleSettings language="Python">
<option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
<option name="RIGHT_MARGIN" value="80" />
<option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
<option name="PARENT_SETTINGS_INSTALLED" value="true" />
<indentOptions>
<option name="INDENT_SIZE" value="2" />
<option name="CONTINUATION_INDENT_SIZE" value="4" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
</codeStyleSettings>
<codeStyleSettings language="SASS">
<indentOptions>
<option name="CONTINUATION_INDENT_SIZE" value="4" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
</codeStyleSettings>
<codeStyleSettings language="SCSS">
<indentOptions>
<option name="CONTINUATION_INDENT_SIZE" value="4" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
</codeStyleSettings>
<codeStyleSettings language="TypeScript">
<indentOptions>
<option name="INDENT_SIZE" value="2" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
</codeStyleSettings>
<codeStyleSettings language="XML">
<indentOptions>
<option name="INDENT_SIZE" value="2" />
<option name="CONTINUATION_INDENT_SIZE" value="2" />
<option name="TAB_SIZE" value="2" />
</indentOptions>
<arrangement>
<rules>
<section>
<rule>
<match>
<AND>
<NAME>xmlns:android</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>^$</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>xmlns:.*</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>^$</XML_NAMESPACE>
</AND>
</match>
<order>BY_NAME</order>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:id</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>style</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>^$</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>^$</XML_NAMESPACE>
</AND>
</match>
<order>BY_NAME</order>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:.*Style</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
<order>BY_NAME</order>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:layout_width</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:layout_height</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:layout_weight</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:layout_margin</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:layout_marginTop</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:layout_marginBottom</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:layout_marginStart</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:layout_marginEnd</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:layout_marginLeft</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:layout_marginRight</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:layout_.*</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
<order>BY_NAME</order>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:padding</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:paddingTop</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:paddingBottom</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:paddingStart</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:paddingEnd</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:paddingLeft</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*:paddingRight</NAME>
<XML_ATTRIBUTE />
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*</NAME>
<XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
</AND>
</match>
<order>BY_NAME</order>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*</NAME>
<XML_NAMESPACE>http://schemas.android.com/apk/res-auto</XML_NAMESPACE>
</AND>
</match>
<order>BY_NAME</order>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*</NAME>
<XML_NAMESPACE>http://schemas.android.com/tools</XML_NAMESPACE>
</AND>
</match>
<order>BY_NAME</order>
</rule>
</section>
<section>
<rule>
<match>
<AND>
<NAME>.*</NAME>
<XML_NAMESPACE>.*</XML_NAMESPACE>
</AND>
</match>
<order>BY_NAME</order>
</rule>
</section>
</rules>
</arrangement>
</codeStyleSettings>
<Objective-C>
<option name="INDENT_NAMESPACE_MEMBERS" value="0" />
<option name="INDENT_C_STRUCT_MEMBERS" value="2" />
<option name="INDENT_CLASS_MEMBERS" value="2" />
<option name="INDENT_VISIBILITY_KEYWORDS" value="1" />
<option name="INDENT_INSIDE_CODE_BLOCK" value="2" />
<option name="KEEP_STRUCTURES_IN_ONE_LINE" value="true" />
<option name="FUNCTION_PARAMETERS_WRAP" value="5" />
<option name="FUNCTION_CALL_ARGUMENTS_WRAP" value="5" />
<option name="TEMPLATE_CALL_ARGUMENTS_WRAP" value="5" />
<option name="TEMPLATE_CALL_ARGUMENTS_ALIGN_MULTILINE" value="true" />
<option name="ALIGN_INIT_LIST_IN_COLUMNS" value="false" />
<option name="SPACE_BEFORE_SUPERCLASS_COLON" value="false" />
</Objective-C>
<Objective-C-extensions>
<option name="GENERATE_INSTANCE_VARIABLES_FOR_PROPERTIES" value="ASK" />
<option name="RELEASE_STYLE" value="IVAR" />
<option name="TYPE_QUALIFIERS_PLACEMENT" value="BEFORE" />
<file>
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Import" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Macro" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Typedef" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Enum" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Constant" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Global" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Struct" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="FunctionPredecl" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Function" />
</file>
<class>
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Property" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Synthesize" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="InitMethod" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="StaticMethod" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="InstanceMethod" />
<option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="DeallocMethod" />
</class>
<extensions>
<pair source="cc" header="h" />
<pair source="c" header="h" />
</extensions>
</Objective-C-extensions>
<codeStyleSettings language="ObjectiveC">
<option name="RIGHT_MARGIN" value="80" />
<option name="KEEP_BLANK_LINES_BEFORE_RBRACE" value="1" />
<option name="BLANK_LINES_BEFORE_IMPORTS" value="0" />
<option name="BLANK_LINES_AFTER_IMPORTS" value="0" />
<option name="BLANK_LINES_AROUND_CLASS" value="0" />
<option name="BLANK_LINES_AROUND_METHOD" value="0" />
<option name="BLANK_LINES_AROUND_METHOD_IN_INTERFACE" value="0" />
<option name="ALIGN_MULTILINE_BINARY_OPERATION" value="false" />
<option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
<option name="FOR_STATEMENT_WRAP" value="1" />
<option name="ASSIGNMENT_WRAP" value="1" />
<indentOptions>
<option name="INDENT_SIZE" value="2" />
<option name="CONTINUATION_INDENT_SIZE" value="4" />
</indentOptions>
</codeStyleSettings>
</code_scheme>

572
javaguide.css Normal file
View File

@ -0,0 +1,572 @@
table {
border-collapse: collapse;
}
td, th {
border: 1px solid #ccc;
padding: 2px 12px;
font-size: 10pt;
}
code, samp, var {
color: #060;
}
pre {
font-size: 10pt;
display: block;
color: #060;
background-color: #e8fff6;
border-color: #f0fff0;
border-style: solid;
border-top-width: 1px;
border-bottom-width: 1px;
border-right-width: 1px;
border-left-width: 5px;
padding-left: 12px;
padding-right: 12px;
padding-top: 4px;
padding-bottom: 4px;
}
pre.badcode {
color: #c00;
background-color: #ffe6d8;
border-color: #fff0f0;
}
hr {
margin-top: 3.5em;
border-width: 1px;
color: #fff;
}
html {
margin-top:2em;
margin-left:10%;
margin-right:10%;
padding:0;
}
.bp-reset-element,
body,
h1,
h2,
h3,
h4,
h5,
h6,
article,
aside,
details,
figcaption,
figure,
footer,
header,
hgroup,
menu,
nav,
section,
summary,
blockquote,
q,
th,
td,
caption,
table,
div,
span,
object,
iframe,
p,
pre,
a,
abbr,
acronym,
address,
code,
del,
dfn,
em,
img,
dl,
dt,
dd,
ol,
ul,
li,
fieldset,
form,
label,
legend,
caption,
tbody,
tfoot,
thead,
tr {
margin:0;
padding:0;
border:0;
font-weight:inherit;
font-style:inherit;
font-size:100%;
font-family:inherit;
vertical-align:baseline;
}
body {
font-family:'Arial', sans-serif;
font-size:81.25%;
color:#222;
background-color:#fff;
line-height:1.67;
overflow: auto;
}
.change {
text-align: right;
margin-bottom:1em;
}
em {
font-style: italic
}
h1,
h2,
h3,
h4,
h5,
h6 {
font-weight:bold;
}
h1 {
margin-bottom:.50em;
text-align: center
}
h2,
h3,
h4,
h5,
h6 {
margin-top:1.5em;
margin-bottom:.75em;
}
h1 {font-size:200%;}
h2 {font-size:167%;}
h3 {font-size:133%;}
h4 {font-size:120%;}
h5 {font-size:110%;}
p {
margin:0 0 1.5em;
}
a[href=''] {
cursor:default;
}
h1 img,
h2 img,
h3 img,
h4 img,
h5 img,
h6 img {
margin:0;
}
a img {
border:none;
}
pre {
margin:1.5em 0;
white-space:pre;
}
pre,
code,
kbd,
tt {
font:1em 'Droid Sans Mono', monospace;
line-height:1.5;
}
dl {
margin:0 0 1.5em 0;
}
dl dt {
font-weight:bold;
}
dd {
margin-left:1.5em;
}
dd.toc3 {
margin-left:3em;
}
hr {
height:0;
border:0;
border-top:1px solid #ccc;
background-color:#ccc;
}
table {
border:1px solid #bbb;
border-spacing:0;
border-collapse:collapse;
margin:0 0 1.5em;
vertical-align:middle;
width:100%;
}
table.unlined,
table.unlined th,
table.unlined tr,
table.unlined td {
border:0;
}
th,
td,
caption {
float:none !important;
text-align:left;
font-weight:normal;
vertical-align:middle;
padding:4px;
}
caption {
padding:0;
}
td {
border:1px solid #bbb;
vertical-align:top;
}
th {
border:0;
border-bottom:1px solid black;
font-weight:bold;
background:rgb(229, 236, 249);
}
table th code {
background-color:inherit;
color:inherit;
}
table tfoot th {
border:1px solid #bbb;
}
tfoot {
font-style:italic;
}
caption {
background:#eee;
}
table[border='0'] {
border:none;
}
table[border='0']>tbody>tr>td,
table[border='0']>tr>td {
border:none;
}
tr.alt td,
td.alt {
background-color:#efefef;
}
table.striped tr:nth-child(even) td,
table tr.even td {
background:#efefef;
}
table.columns {
border:none;
}
table.columns>tbody>tr>td,
table.columns>tr>td {
border:none;
padding:0 3em 0 0;
}
table.columns>tbody>tr>td:last-child,
table.columns>tr>td:last-child {
border:none;
padding:0;
}
ul,
ol {
margin:0 1.5em 1.5em 0;
padding-left:2em;
}
li ul,
li ol {
margin:0;
}
ul {
list-style-type:disc;
}
ol {
list-style-type:decimal;
}
ul {
list-style-type:disc;
}
ul ul {
list-style-type:circle;
}
ul ul ul {
list-style-type:square;
}
ul.disc {
list-style-type:disc;
}
ul.circle {
list-style-type:circle;
}
ul.square {
list-style-type:square;
}
ol {
list-style-type:decimal;
}
ol ol {
list-style-type:lower-alpha;
}
ol ol ol {
list-style-type:lower-roman;
}
ol ul {
list-style-type:circle;
}
ol.decimal {
list-style-type:decimal;
}
ol.upper-alpha {
list-style-type:upper-alpha;
}
ol.lower-alpha {
list-style-type:lower-alpha;
}
ol.upper-roman {
list-style-type:upper-roman;
}
ol.lower-roman {
list-style-type:lower-roman;
}
ol.nolist,
ul.nolist {
padding-left:0;
list-style-image:none;
list-style-type:none;
margin-left:0;
}
.center {
text-align:center;
}
code,
kbd,
pre {
color:#009900;
}
kbd {
font-weight: bold;
}
table.striped code {
background-color:inherit;
}
pre {
padding:6px 10px;
background-color:#FAFAFA;
border:1px solid #bbb;
overflow:auto;
}
pre.prettyprint {
padding:6px 10px !important;
border:1px solid #bbb !important;
}
code.bad, code.badcode {
color: magenta;
}
pre.bad, pre.badcode {
background-color:#ffe6d8;
border-top:1px inset #a03;
border-left:1px inset #a03;
}
.tip {
background-color:#fffbd9;
padding:6px 8px 6px 10px;
border-left:6px solid #ffef70;
}
.note {
background-color:#e5ecf9;
padding:6px 8px 6px 10px;
border-left:6px solid #36c;
}
@media print {
.str {
color:#060;
}
.kwd {
color:#006;
font-weight:bold;
}
.com {
color:#600;
font-style:italic;
}
.typ {
color:#404;
font-weight:bold;
}
.lit {
color:#044;
}
.pun,
.opn,
.clo {
color:#440;
}
.pln {
color:#000;
}
.tag {
color:#006;
font-weight:bold;
}
.atn {
color:#404;
}
.atv {
color:#060;
}
h1 {
font-style:italic;
}
}
ol.linenums {
margin-top:0;
margin-bottom:0;
}
code {
background-color:#FAFAFA;
padding: 0.25em 0.5em;
white-space: nowrap
}
/* TOC CSS */
table.columns {
border: none;
}
td.two_columns {
-webkit-column-count: 2;
column-count: 2;
}
.toc_category {
font-size: 10pt;
padding-top: 1em;
padding-bottom: 1em;
border-left-width: 2px;
border-right-width: 2px;
border-color: grey;
}
.toc_stylepoint {
font-size: 10pt;
padding-top: 1em;
padding-bottom: 1em;
}
li.toc_entry {
padding-right: 1em;
display: inline;
list-style-type: none;
}
/*
* This space is required to trigger the linewrap on the links
* at href boundaries
*/
li.toc_entry::after {
content: " ";
}
li.toc_entry a {
white-space: nowrap;
}
/* Horizontal TOC */
.toc td, .toc th {
border-width: 1px 5px;
overflow: hidden;
}
/* Vertical TOC */
.toc td.two_columns {
border-width: 0px;
}

1187
javaguide.html Normal file

File diff suppressed because it is too large Load Diff

BIN
javaguidelink.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 189 B

3629
javascriptguide.xml Normal file

File diff suppressed because it is too large Load Diff

2816
jsguide.html Normal file

File diff suppressed because it is too large Load Diff

18
jsoncstyleguide.html Normal file
View File

@ -0,0 +1,18 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf8">
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<meta http-equiv="refresh" content="1; url=jsoncstyleguide.xml">
<title>Redirecting</title>
</head>
<!-- The BODY onLoad redirect is the best: it preserves #fragments and
?queries. But it requires javascript. If that fails, the
meta-refresh kicks in; it works more generally, but loses fragments
and queries, takes a second, and pollutes the browser history.
If they both fail, we let the user manually click on the new link.
-->
<body onload="location.replace(location.href.replace('.html', '.xml'))">
Redirecting you to <a href="jsoncstyleguide.xml">jsoncstyleguide.xml</a>.
</body>
</html>

1187
jsoncstyleguide.xml Normal file

File diff suppressed because it is too large Load Diff

Binary file not shown.

After

Width:  |  Height:  |  Size: 312 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 253 KiB

3887
lispguide.xml Normal file

File diff suppressed because it is too large Load Diff

1661
objcguide.md Normal file

File diff suppressed because it is too large Load Diff

8
objcguide.xml Normal file
View File

@ -0,0 +1,8 @@
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
<GUIDE title="Google Objective-C Style Guide">
<p>
The style guide has moved to
<a href="https://github.com/google/styleguide/blob/gh-pages/objcguide.md">objcguide.md</a>
</p>
</GUIDE>

2310
pyguide.html Normal file

File diff suppressed because it is too large Load Diff

2568
pyguide.md

File diff suppressed because it is too large Load Diff

1152
shell.xml Normal file

File diff suppressed because it is too large Load Diff

147
styleguide.css Normal file
View File

@ -0,0 +1,147 @@
body {
background-color: #fff;
color: #333;
font-family: sans-serif;
font-size: 10pt;
margin-right: 100px;
margin-left: 100px;
}
h1, h2, h3, h4, h5, h6, .toc_title {
color: #06c;
margin-top: 2em;
margin-bottom: 1em;
}
h1 {
text-align: center;
font-size: 18pt;
}
h2, .toc_title {
font-weight: bold;
font-size: 12pt;
margin-left: -40px;
}
h3, h4, h5, h6 {
font-size: 10pt;
margin-left: -20px;
}
.toc_category, .toc_stylepoint {
font-size: 10pt;
padding-top: .3em;
padding-bottom: .3em;
}
table {
border-collapse: collapse;
}
td, th {
border: 1px solid #ccc;
padding: 2px 12px;
font-size: 10pt;
}
.toc td, .toc th {
border-width: 1px 5px;
}
code, samp, var {
color: #060;
}
pre {
font-size: 10pt;
display: block;
color: #060;
background-color: #f8fff8;
border-color: #f0fff0;
border-style: solid;
border-top-width: 1px;
border-bottom-width: 1px;
border-right-width: 1px;
border-left-width: 5px;
padding-left: 12px;
padding-right: 12px;
padding-top: 4px;
padding-bottom: 4px;
}
pre.badcode {
color: #c00;
background-color: #fff8f8;
border-color: #fff0f0;
}
.showhide_button {
float: left;
cursor: pointer;
border-width: 1px;
border-style: solid;
border-color: #ddd #aaa #aaa #ddd;
padding: 0 3px 1px;
margin: 0 4px 8px 0;
border-radius: 3px;
-webkit-border-radius: 3px;
-moz-border-radius: 3px;
}
.link_button {
float: left;
display: none;
background-color: #f8f8ff;
border-color: #f0f0ff;
border-style: solid;
border-width: 1px;
font-size: 75%;
margin-top: 0;
margin-left: -50px;
padding: 4px;
border-radius: 3px;
-webkit-border-radius: 3px;
-moz-border-radius: 3px;
}
address {
text-align: right;
}
hr {
margin-top: 3.5em;
border-width: 1px;
color: #fff;
}
.stylepoint_section {
display: block;
margin-bottom: 1em;
color: #5588ff;
font-family: sans-serif;
font-size: 90%;
font-weight: bold;
margin-left: -2%;
}
.stylepoint_subsection {
color: #667799;
font-family: sans-serif;
font-size: 90%;
font-weight: bold;
margin-left: -1%;
}
.stylepoint_subsubsection {
color: #667799;
font-family: sans-serif;
font-size: 80%;
font-weight: bold;
margin-left: 0;
}
.revision {
text-align: right;
}

924
styleguide.xsl Normal file
View File

@ -0,0 +1,924 @@
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:dcq="http://purl.org/dc/qualifiers/1.0/"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:fn="http://www.w3.org/2005/xpath-functions">
<xsl:output method="html"/>
<!-- Set to 1 to show explanations by default. Set to 0 to hide them -->
<xsl:variable name="show_explanation_default" select="0" />
<!-- The characters within the Webdings font that show the triangles -->
<xsl:variable name="show_button_text" select="'&#x25B6;'" />
<xsl:variable name="hide_button_text" select="'&#x25BD;'" />
<!-- The suffix for names -->
<xsl:variable name="button_suffix" select="'__button'"/>
<xsl:variable name="body_suffix" select="'__body'"/>
<!-- For easy reference, the name of the button -->
<xsl:variable name="show_hide_all_button" select="'show_hide_all_button'"/>
<!-- The top-level element -->
<xsl:template match="GUIDE">
<HTML>
<HEAD>
<TITLE><xsl:value-of select="@title"/></TITLE>
<META http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<LINK HREF="https://www.google.com/favicon.ico" type="image/x-icon"
rel="shortcut icon"/>
<LINK HREF="styleguide.css"
type="text/css" rel="stylesheet"/>
<SCRIPT language="javascript" type="text/javascript">
function GetElementsByName(name) {
// Workaround a bug on old versions of opera.
if (document.getElementsByName) {
return document.getElementsByName(name);
} else {
return [document.getElementById(name)];
}
}
/**
* @param {string} namePrefix The prefix of the body name.
* @param {function(boolean): boolean} getVisibility Computes the new
* visibility state, given the current one.
*/
function ChangeVisibility(namePrefix, getVisibility) {
var bodyName = namePrefix + '<xsl:value-of select="$body_suffix"/>';
var buttonName = namePrefix + '<xsl:value-of select="$button_suffix"/>';
var bodyElements = GetElementsByName(bodyName);
var linkElement = GetElementsByName('link-' + buttonName)[0];
if (bodyElements.length != 1) {
throw Error('ShowHideByName() got the wrong number of bodyElements: ' +
bodyElements.length);
} else {
var bodyElement = bodyElements[0];
var buttonElement = GetElementsByName(buttonName)[0];
var isVisible = bodyElement.style.display != "none";
if (getVisibility(isVisible)) {
bodyElement.style.display = "inline";
linkElement.style.display = "block";
buttonElement.innerHTML = '<xsl:value-of select="$hide_button_text"/>';
} else {
bodyElement.style.display = "none";
linkElement.style.display = "none";
buttonElement.innerHTML = '<xsl:value-of select="$show_button_text"/>';
}
}
}
function ShowHideByName(namePrefix) {
ChangeVisibility(namePrefix, function(old) { return !old; });
}
function ShowByName(namePrefix) {
ChangeVisibility(namePrefix, function() { return true; });
}
function ShowHideAll() {
var allButton = GetElementsByName("show_hide_all_button")[0];
if (allButton.innerHTML == '<xsl:value-of select="$hide_button_text"/>') {
allButton.innerHTML = '<xsl:value-of select="$show_button_text"/>';
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '<xsl:value-of select="$show_button_text"/>');
} else {
allButton.innerHTML = '<xsl:value-of select="$hide_button_text"/>';
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '<xsl:value-of select="$hide_button_text"/>');
}
}
// Recursively sets state of all children
// of a particular node.
function SetHiddenState(root, newState, newButton) {
for (var i = 0; i != root.length; i++) {
SetHiddenState(root[i].childNodes, newState, newButton);
if (root[i].className == 'showhide_button') {
root[i].innerHTML = newButton;
}
if (root[i].className == 'stylepoint_body' ||
root[i].className == 'link_button') {
root[i].style.display = newState;
}
}
}
function EndsWith(str, suffix) {
var l = str.length - suffix.length;
return l >= 0 &amp;&amp; str.indexOf(suffix, l) == l;
}
function RefreshVisibilityFromHashParam() {
var hashRegexp = new RegExp('#([^&amp;#]*)$');
var hashMatch = hashRegexp.exec(window.location.href);
var anchor = hashMatch &amp;&amp; GetElementsByName(hashMatch[1])[0];
var node = anchor;
var suffix = '<xsl:value-of select="$body_suffix"/>';
while (node) {
var id = node.id;
var matched = id &amp;&amp; EndsWith(id, suffix);
if (matched) {
var len = id.length - suffix.length;
ShowByName(id.substring(0, len));
if (anchor.scrollIntoView) {
anchor.scrollIntoView();
}
return;
}
node = node.parentNode;
}
}
window.onhashchange = RefreshVisibilityFromHashParam;
window.onload = function() {
// if the URL contains "?showall=y", expand the details of all children
var showHideAllRegex = new RegExp("[\\?&amp;](showall)=([^&amp;#]*)");
var showHideAllValue = showHideAllRegex.exec(window.location.href);
if (showHideAllValue != null) {
if (showHideAllValue[2] == "y") {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
"inline", '<xsl:value-of select="$hide_button_text"/>');
} else {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
"none", '<xsl:value-of select="$show_button_text"/>');
}
}
var showOneRegex = new RegExp("[\\?&amp;](showone)=([^&amp;#]*)");
var showOneValue = showOneRegex.exec(window.location.href);
if (showOneValue) {
ShowHideByName(showOneValue[2]);
}
RefreshVisibilityFromHashParam();
}
</SCRIPT>
</HEAD>
<BODY>
<H1><xsl:value-of select="@title"/></H1>
<xsl:apply-templates/>
</BODY>
</HTML>
</xsl:template>
<xsl:template match="OVERVIEW">
<xsl:variable name="button_text">
<xsl:choose>
<xsl:when test="$show_explanation_default">
<xsl:value-of select="$hide_button_text"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$show_button_text"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<DIV style="margin-left: 50%; font-size: 75%;">
<P>
Each style point has a summary for which additional information is available
by toggling the accompanying arrow button that looks this way:
<SPAN class="showhide_button" style="margin-left: 0; float: none">
<xsl:value-of select="$show_button_text"/></SPAN>.
You may toggle all summaries with the big arrow button:
</P>
<DIV style=" font-size: larger; margin-left: +2em;">
<SPAN class="showhide_button" style="font-size: 180%; float: none">
<xsl:attribute name="onclick"><xsl:value-of select="'javascript:ShowHideAll()'"/></xsl:attribute>
<xsl:attribute name="name"><xsl:value-of select="$show_hide_all_button"/></xsl:attribute>
<xsl:attribute name="id"><xsl:value-of select="$show_hide_all_button"/></xsl:attribute>
<xsl:value-of select="$button_text"/>
</SPAN>
Toggle all summaries
</DIV>
</DIV>
<xsl:call-template name="TOC">
<xsl:with-param name="root" select=".."/>
</xsl:call-template>
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="PARTING_WORDS">
<H2>Parting Words</H2>
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="CATEGORY">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<H2>
<xsl:variable name="category_name">
<xsl:call-template name="anchorname">
<xsl:with-param name="sectionname" select="@title"/>
</xsl:call-template>
</xsl:variable>
<xsl:attribute name="name"><xsl:value-of select="$category_name"/></xsl:attribute>
<xsl:attribute name="id"><xsl:value-of select="$category_name"/></xsl:attribute>
<xsl:value-of select="@title"/>
</H2>
<xsl:apply-templates/>
</DIV>
</xsl:template>
<xsl:template match="STYLEPOINT">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<xsl:variable name="stylepoint_name">
<xsl:call-template name="anchorname">
<xsl:with-param name="sectionname" select="@title"/>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="button_text">
<xsl:choose>
<xsl:when test="$show_explanation_default">
<xsl:value-of select="$hide_button_text"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$show_button_text"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<H3>
<A>
<xsl:attribute name="name"><xsl:value-of select="$stylepoint_name"/></xsl:attribute>
<xsl:attribute name="id"><xsl:value-of select="$stylepoint_name"/></xsl:attribute>
<xsl:value-of select="@title"/>
</A>
</H3>
<xsl:variable name="buttonName">
<xsl:value-of select="$stylepoint_name"/><xsl:value-of select="$button_suffix"/>
</xsl:variable>
<xsl:variable name="onclick_definition">
<xsl:text>javascript:ShowHideByName('</xsl:text>
<xsl:value-of select="$stylepoint_name"/>
<xsl:text>')</xsl:text>
</xsl:variable>
<SPAN class="link_button" id="link-{$buttonName}" name="link-{$buttonName}">
<A>
<xsl:attribute name="href">?showone=<xsl:value-of select="$stylepoint_name"/>#<xsl:value-of select="$stylepoint_name"/></xsl:attribute>
link
</A>
</SPAN>
<SPAN class="showhide_button">
<xsl:attribute name="onclick"><xsl:value-of select="$onclick_definition"/></xsl:attribute>
<xsl:attribute name="name"><xsl:value-of select="$buttonName"/></xsl:attribute>
<xsl:attribute name="id"><xsl:value-of select="$buttonName"/></xsl:attribute>
<xsl:value-of select="$button_text"/>
</SPAN>
<xsl:apply-templates>
<xsl:with-param name="anchor_prefix" select="$stylepoint_name" />
</xsl:apply-templates>
</DIV>
</xsl:template>
<xsl:template match="SUMMARY">
<xsl:param name="anchor_prefix" />
<DIV style="display:inline;">
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<xsl:apply-templates/>
</DIV>
</xsl:template>
<xsl:template match="BODY">
<xsl:param name="anchor_prefix" />
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<DIV class="stylepoint_body">
<xsl:attribute name="name"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute>
<xsl:attribute name="id"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute>
<xsl:attribute name="style">
<xsl:choose>
<xsl:when test="$show_explanation_default">display: inline</xsl:when>
<xsl:otherwise>display: none</xsl:otherwise>
</xsl:choose>
</xsl:attribute>
<xsl:apply-templates/>
</DIV>
</DIV>
</xsl:template>
<xsl:template match="DEFINITION">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_section">Definition: </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="PROS">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_section">Pros: </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="CONS">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_section">Cons: </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="DECISION">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_section">Decision: </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="TODO">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<DIV style="font-size: 150%;">TODO:
<xsl:apply-templates/>
</DIV>
</P>
</xsl:template>
<xsl:template match="SUBSECTION">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_subsection"><xsl:value-of select="@title"/> </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="SUBSUBSECTION">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_subsubsection"><xsl:value-of select="@title"/> </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="CODE_SNIPPET">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<PRE><xsl:call-template name="print_without_leading_chars">
<xsl:with-param name="text" select="."/>
<xsl:with-param name="strip" select="1"/>
<xsl:with-param name="is_firstline" select="1"/>
<xsl:with-param name="trim_count">
<xsl:call-template name="num_leading_spaces">
<xsl:with-param name="text" select="."/>
<xsl:with-param name="max_so_far" select="1000"/>
</xsl:call-template>
</xsl:with-param>
</xsl:call-template></PRE>
</DIV>
</xsl:template>
<xsl:template match="BAD_CODE_SNIPPET">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<PRE class="badcode"><xsl:call-template name="print_without_leading_chars">
<xsl:with-param name="text" select="."/>
<xsl:with-param name="strip" select="1"/>
<xsl:with-param name="is_firstline" select="1"/>
<xsl:with-param name="trim_count">
<xsl:call-template name="num_leading_spaces">
<xsl:with-param name="text" select="."/>
<xsl:with-param name="max_so_far" select="1000"/>
</xsl:call-template>
</xsl:with-param>
</xsl:call-template></PRE>
</DIV>
</xsl:template>
<xsl:template match="PY_CODE_SNIPPET">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<PRE><xsl:call-template name="print_python_code">
<xsl:with-param name="text" select="."/>
</xsl:call-template></PRE>
</DIV>
</xsl:template>
<xsl:template match="BAD_PY_CODE_SNIPPET">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<PRE class="badcode"><xsl:call-template name="print_python_code">
<xsl:with-param name="text" select="."/>
</xsl:call-template></PRE>
</DIV>
</xsl:template>
<xsl:template match="FUNCTION">
<xsl:call-template name="print_function_name">
<xsl:with-param name="text" select="."/>
</xsl:call-template>
</xsl:template>
<xsl:template match="SYNTAX">
<I>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<xsl:apply-templates/>
</I>
</xsl:template>
<!-- This passes through any HTML elements that the
XML doc uses for minor formatting -->
<xsl:template match="a|address|blockquote|br|center|cite|code|dd|div|dl|dt|em|hr|i|img|li|ol|p|pre|span|table|td|th|tr|ul|var|A|ADDRESS|BLOCKQUOTE|BR|CENTER|CITE|CODE|DD|DIV|DL|DT|EM|HR|I|LI|OL|P|PRE|SPAN|TABLE|TD|TH|TR|UL|VAR">
<xsl:element name="{local-name()}">
<xsl:copy-of select="@*"/>
<xsl:apply-templates/>
</xsl:element>
</xsl:template>
<!-- Builds the table of contents -->
<xsl:template name="TOC">
<xsl:param name="root"/>
<DIV class="toc">
<DIV class="toc_title">Table of Contents</DIV>
<TABLE>
<xsl:for-each select="$root/CATEGORY">
<TR valign="top">
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<TD>
<DIV class="toc_category">
<A>
<xsl:attribute name="href">
<xsl:text>#</xsl:text>
<xsl:call-template name="anchorname">
<xsl:with-param name="sectionname" select="@title"/>
</xsl:call-template>
</xsl:attribute>
<xsl:value-of select="@title"/>
</A>
</DIV>
</TD><TD>
<DIV class="toc_stylepoint">
<xsl:for-each select="./STYLEPOINT">
<SPAN style="padding-right: 1em; white-space:nowrap;">
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<A>
<xsl:attribute name="href">
<xsl:text>#</xsl:text>
<xsl:call-template name="anchorname">
<xsl:with-param name="sectionname" select="@title"/>
</xsl:call-template>
</xsl:attribute>
<xsl:value-of select="@title"/>
</A>
</SPAN>
<xsl:text> </xsl:text>
</xsl:for-each>
</DIV>
</TD>
</TR>
</xsl:for-each>
</TABLE>
</DIV>
</xsl:template>
<xsl:template name="TOC_one_stylepoint">
<xsl:param name="stylepoint"/>
</xsl:template>
<!-- Creates a standard anchor given any text.
Substitutes underscore for characters unsuitable for URLs -->
<xsl:template name="anchorname">
<xsl:param name="sectionname"/>
<!-- strange quoting necessary to strip apostrophes -->
<xsl:variable name="bad_characters" select="&quot; ()#'&quot;"/>
<xsl:value-of select="translate($sectionname,$bad_characters,'_____')"/>
</xsl:template>
<!-- Given text, evaluates to the number of leading spaces. -->
<!-- TODO(csilvers): deal well with leading tabs (treat as 8 spaces?) -->
<xsl:template name="num_leading_spaces_one_line">
<xsl:param name="text"/>
<xsl:param name="current_count"/>
<xsl:choose>
<xsl:when test="starts-with($text, ' ')">
<xsl:call-template name="num_leading_spaces_one_line">
<xsl:with-param name="text" select="substring($text, 2)"/>
<xsl:with-param name="current_count" select="$current_count + 1"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$current_count"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Given a block of text, each line terminated by \n, evaluates to
the indentation-level of that text; that is, the largest number
n such that every non-blank line starts with at least n spaces. -->
<xsl:template name="num_leading_spaces">
<xsl:param name="text"/>
<xsl:param name="max_so_far"/>
<!-- TODO(csilvers): deal with case text doesn't end in a newline -->
<xsl:variable name="line" select="substring-before($text, '&#xA;')"/>
<xsl:variable name="rest" select="substring-after($text, '&#xA;')"/>
<xsl:variable name="num_spaces_this_line">
<xsl:choose>
<xsl:when test="$line=''">
<xsl:value-of select="$max_so_far"/>
</xsl:when>
<xsl:otherwise>
<xsl:call-template name="num_leading_spaces_one_line">
<xsl:with-param name="text" select="$line"/>
<xsl:with-param name="current_count" select="0"/>
</xsl:call-template>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:variable name="new_max_so_far">
<xsl:choose>
<xsl:when test="$num_spaces_this_line &lt; $max_so_far">
<xsl:value-of select="$num_spaces_this_line"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$max_so_far"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<!-- now check if we're on the last line, and if not, recurse -->
<xsl:if test="$rest=''">
<xsl:value-of select="$new_max_so_far"/>
</xsl:if>
<xsl:if test="not($rest='')">
<xsl:call-template name="num_leading_spaces">
<xsl:with-param name="text" select="$rest"/>
<xsl:with-param name="max_so_far" select="$new_max_so_far"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
<!-- Given text, determine the starting position of code.
This similar to num_leading_spaces_one_line but treats "Yes:" and "No:"
as spaces. Also, if there is no code on the first line, it searches
subsequent lines until a non-empty line is found.
Used to find the start of code in snippets like:
Yes: if(foo):
No : if(foo):
As well as:
Yes:
if (foo):
-->
<xsl:template name="code_start_index">
<xsl:param name="text"/>
<xsl:param name="current_count"/>
<xsl:choose>
<xsl:when test="starts-with($text, ' ')">
<xsl:call-template name="code_start_index">
<xsl:with-param name="text" select="substring($text, 2)"/>
<xsl:with-param name="current_count" select="$current_count + 1"/>
</xsl:call-template>
</xsl:when>
<xsl:when test="starts-with($text, 'Yes:')">
<xsl:call-template name="code_start_index">
<xsl:with-param name="text" select="substring($text, 5)"/>
<xsl:with-param name="current_count" select="$current_count + 4"/>
</xsl:call-template>
</xsl:when>
<xsl:when test="starts-with($text, 'No:')">
<xsl:call-template name="code_start_index">
<xsl:with-param name="text" select="substring($text, 4)"/>
<xsl:with-param name="current_count" select="$current_count + 3"/>
</xsl:call-template>
</xsl:when>
<!-- This is only reached if the first line is entirely whitespace or
contains nothing but "Yes:" or "No:"-->
<xsl:when test="starts-with($text, '&#xA;')">
<xsl:call-template name="code_start_index">
<xsl:with-param name="text" select="substring($text, 2)"/>
<xsl:with-param name="current_count" select="0"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$current_count"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Helper for ends_with_colon. Determine whether the given line is nothing
but spaces and python-style comments. -->
<xsl:template name="is_blank_or_comment">
<xsl:param name="line"/>
<xsl:choose>
<xsl:when test="$line = ''">
<xsl:value-of select="1"/>
</xsl:when>
<xsl:when test="starts-with($line, '&#xA;')">
<xsl:value-of select="1"/>
</xsl:when>
<xsl:when test="starts-with($line, '#')">
<xsl:value-of select="1"/>
</xsl:when>
<xsl:when test="starts-with($line, ' ')">
<xsl:call-template name="is_blank_or_comment">
<xsl:with-param name="line" select="substring($line, 2)"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="0"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Determine whether the given line ends with a colon. Note that Python
style comments are ignored so the following lines return True:
- def foo():
- def foo(): # Bar
- if(foo):
But some code may confuse this function. For example the following are
also consider to "end_with_colon" even though they don't for Python
- foo(": #")
- foo() # No need for :
-->
<xsl:template name="ends_with_colon">
<xsl:param name="line"/>
<xsl:param name="found_colon"/>
<xsl:choose>
<xsl:when test="$line = ''">
<xsl:value-of select="$found_colon"/>
</xsl:when>
<xsl:when test="starts-with($line, '&#xA;')">
<xsl:value-of select="$found_colon"/>
</xsl:when>
<xsl:when test="starts-with($line, ' ')">
<xsl:call-template name="ends_with_colon">
<xsl:with-param name="line" select="substring($line, 2)"/>
<xsl:with-param name="found_colon" select="$found_colon"/>
</xsl:call-template>
</xsl:when>
<xsl:when test="starts-with($line, ':')">
<xsl:variable name="rest_is_comment">
<xsl:call-template name="is_blank_or_comment">
<xsl:with-param name="line" select="substring($line, 2)"/>
</xsl:call-template>
</xsl:variable>
<xsl:choose>
<xsl:when test="$rest_is_comment = '1'">
<xsl:value-of select="1"/>
</xsl:when>
<xsl:otherwise>
<xsl:call-template name="ends_with_colon">
<xsl:with-param name="line" select="substring($line, 2)"/>
<xsl:with-param name="found_colon" select="0"/>
</xsl:call-template>
</xsl:otherwise>
</xsl:choose>
</xsl:when>
<xsl:otherwise>
<xsl:call-template name="ends_with_colon">
<xsl:with-param name="line" select="substring($line, 2)"/>
<xsl:with-param name="found_colon" select="0"/>
</xsl:call-template>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Prints one line of python code with proper indent and calls itself
recursively for the rest of the text.
This template uses "a", "b", "c" and "d" to refer to four key column
numbers. They are:
- a: the indentation common to all lines in a code snippet. This is
stripped out to allow for cleaner code in the xml.
- b: the indentation of the most out-dented line of code. This is
different from "a" when code is labelled with "Yes:" or "No:"
- c: the indentation of the current python block, in other words, the
indentation of the first line of this block, which is the
indentation of the last line we saw that ended with a colon.
- d: the "total" indentation of the line, ignorng possible "Yes:" or
"No:" text on the line.
For example, for the last line of the following code snippet, the
positions of a, b, c and d are indicated below:
Yes: def Foo():
if bar():
a += 1
baz()
a b c d
The algorithm is:
1) Split the text into first line and the rest. Note that the
substring-before function is supposed to handle the case where the
character is not present in the string but does not so we
automatically ignore the last line of the snippet which is always
empty (the closing snippet tag). This is consistent with the
behavior or print_without_leading_chars.
2) If the current is empty (only whitespace), print newline and call
itself recursively on the rest of the text with the rest of the
parameters unchanged.
3) Otherwise, measure "d"
4) Measure "c" by taking:
- the value of "d" if the previous line ended with a colon or the
current line is outdented compare to the previous line
- the indent of the previous line otherwise
5) Print line[a:c] (Note that we ignore line[0:a])
6) Print line[b:c] in an external span (in order to double the block
indent in external code).
7) Print line[c:<end>] with function names processed to produce both
internal and external names.
8) If there are more lines, recurse.
-->
<xsl:template name="print_python_line_recursively">
<xsl:param name="text"/>
<xsl:param name="a"/>
<xsl:param name="b"/>
<xsl:param name="previous_indent"/>
<xsl:param name="previous_ends_with_colon"/>
<xsl:param name="is_first_line"/>
<xsl:variable name="line" select="substring-before($text, '&#xA;')"/>
<xsl:variable name="rest" select="substring-after($text, '&#xA;')"/>
<xsl:choose>
<xsl:when test="substring($line, $b) = '' and not($rest = '')">
<xsl:if test="not($is_first_line = '1')">
<xsl:text>&#xA;</xsl:text>
</xsl:if>
<xsl:call-template name="print_python_line_recursively">
<xsl:with-param name="text" select="$rest"/>
<xsl:with-param name="a" select="$a"/>
<xsl:with-param name="b" select="$b"/>
<xsl:with-param name="previous_indent" select="$previous_indent"/>
<xsl:with-param name="previous_ends_with_colon"
select="$previous_ends_with_colon"/>
<xsl:with-param name="is_first_line" select="0"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:variable name="indent_after_b">
<xsl:call-template name="num_leading_spaces_one_line">
<xsl:with-param name="text" select="substring($line, $b + 1)"/>
<xsl:with-param name="current_count" select="0"/>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="d" select="$b + $indent_after_b"/>
<xsl:variable name="c">
<xsl:choose>
<xsl:when test="$previous_ends_with_colon = '1' or
$previous_indent > $d">
<xsl:value-of select="$d"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$previous_indent"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:value-of select="substring($line, $a + 1, $c - $a)"/>
<span class="external">
<xsl:value-of select="substring($line, $b + 1, $c - $b)"/>
</span>
<xsl:call-template name="munge_function_names_in_text">
<xsl:with-param name="stripped_line"
select="substring($line, $c + 1)"/>
</xsl:call-template>
<xsl:if test="not(substring($rest, $a) = '')">
<xsl:text>&#xA;</xsl:text>
<xsl:call-template name="print_python_line_recursively">
<xsl:with-param name="text" select="$rest"/>
<xsl:with-param name="a" select="$a"/>
<xsl:with-param name="b" select="$b"/>
<xsl:with-param name="previous_indent" select="$c"/>
<xsl:with-param name="previous_ends_with_colon">
<xsl:call-template name="ends_with_colon">
<xsl:with-param name="line" select="$line"/>
<xsl:with-param name="found_colon" select="0"/>
</xsl:call-template>
</xsl:with-param>
<xsl:with-param name="is_first_line" select="0"/>
</xsl:call-template>
</xsl:if>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Print python code with internal and external styles.
In order to conform with PEP-8 externally, we identify 2-space indents
and an external-only 4-space indent.
Function names that are marked with $$FunctionName/$$ have an external
lower_with_underscore version added. -->
<xsl:template name="print_python_code">
<xsl:param name="text"/>
<xsl:variable name="a">
<xsl:call-template name="num_leading_spaces">
<xsl:with-param name="text" select="."/>
<xsl:with-param name="max_so_far" select="1000"/>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="b">
<xsl:call-template name="code_start_index">
<xsl:with-param name="text" select="$text"/>
<xsl:with-param name="current_count" select="0"/>
</xsl:call-template>
</xsl:variable>
<xsl:call-template name="print_python_line_recursively">
<xsl:with-param name="text" select="$text"/>
<xsl:with-param name="a" select="$a"/>
<xsl:with-param name="b" select="$b"/>
<xsl:with-param name="previous_indent" select="$b"/>
<xsl:with-param name="previous_ends_with_colon" select="0"/>
<xsl:with-param name="is_first_line" select="1"/>
</xsl:call-template>
</xsl:template>
<!-- Given a block of text, each line terminated by \n, and a number n,
emits the text with the first n characters of each line
deleted. If strip==1, then we omit blank lines at the beginning
and end of the text (but not the middle!) -->
<!-- TODO(csilvers): deal well with leading tabs (treat as 8 spaces?) -->
<xsl:template name="print_without_leading_chars">
<xsl:param name="text"/>
<xsl:param name="trim_count"/>
<xsl:param name="strip"/>
<xsl:param name="is_firstline"/>
<!-- TODO(csilvers): deal with case text doesn't end in a newline -->
<xsl:variable name="line" select="substring-before($text, '&#xA;')"/>
<xsl:variable name="rest" select="substring-after($text, '&#xA;')"/>
<xsl:variable name="stripped_line" select="substring($line, $trim_count+1)"/>
<xsl:choose>
<!-- $line (or $rest) is considered empty if we'd trim the entire line -->
<xsl:when test="($strip = '1') and ($is_firstline = '1') and
(string-length($line) &lt;= $trim_count)">
</xsl:when>
<xsl:when test="($strip = '1') and
(string-length($rest) &lt;= $trim_count)">
<xsl:value-of select="$stripped_line"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$stripped_line"/>
<xsl:text>&#xA;</xsl:text>
</xsl:otherwise>
</xsl:choose>
<xsl:if test="not($rest='')">
<xsl:call-template name="print_without_leading_chars">
<xsl:with-param name="text" select="$rest"/>
<xsl:with-param name="trim_count" select="$trim_count"/>
<xsl:with-param name="strip" select="$strip"/>
<xsl:with-param name="is_firstline" select="0"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
<!-- Given a line of code, find function names that are marked with $$ /$$ and
print out the line with the internal and external versions of the
function names.-->
<xsl:template name="munge_function_names_in_text">
<xsl:param name="stripped_line"/>
<xsl:choose>
<xsl:when test="contains($stripped_line, '$$')">
<xsl:value-of select="substring-before($stripped_line, '$$')"/>
<xsl:call-template name="print_function_name">
<xsl:with-param name="text" select="substring-after(substring-before($stripped_line, '/$$'), '$$')"/>
</xsl:call-template>
<xsl:call-template name="munge_function_names_in_text">
<xsl:with-param name="stripped_line" select="substring-after($stripped_line, '/$$')"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$stripped_line"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Given a function name, print out both the internal and external version
of the function name in their respective spans.-->
<xsl:template name="print_function_name">
<xsl:param name="text"/>
<xsl:call-template name="convert_camel_case_to_lowercase_with_under">
<xsl:with-param name="text" select="$text"/>
</xsl:call-template>
</xsl:template>
<!-- Given a single word of text convert it from CamelCase to
lower_with_under.
This means replacing each uppercase character with _ followed by the
lowercase version except for the first character which is replaced
without adding the _.-->
<xsl:template name="convert_camel_case_to_lowercase_with_under">
<xsl:param name="text"/>
<xsl:param name="is_recursive_call"/>
<xsl:variable name="first_char" select="substring($text, 1, 1)"/>
<xsl:variable name="rest" select="substring($text, 2)"/>
<xsl:choose>
<xsl:when test="contains('ABCDEFGHIJKLMNOPQRSTUVWXYZ', $first_char)">
<xsl:if test="$is_recursive_call='1'">
<xsl:text>_</xsl:text>
</xsl:if>
<xsl:value-of select="translate($first_char, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$first_char" />
</xsl:otherwise>
</xsl:choose>
<xsl:if test="not($rest='')">
<xsl:call-template name="convert_camel_case_to_lowercase_with_under">
<xsl:with-param name="text" select="$rest"/>
<xsl:with-param name="is_recursive_call" select="1"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
</xsl:stylesheet>

1534
vimscriptfull.xml Normal file

File diff suppressed because it is too large Load Diff

412
vimscriptguide.xml Normal file
View File

@ -0,0 +1,412 @@
<?xml version = '1.0'?>
<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
<GUIDE title="Google Vimscript Style Guide">
<p class="revision">
Revision 1.1
</p>
<address>
Nate Soares<br/>
Joshua Hoak<br/>
David Barnett<br/>
</address>
<OVERVIEW>
<CATEGORY title="Background">
<p>
This is a casual version of the vimscript style guide, because
vimscript is a casual language. When submitting vim plugin code, you
must adhere to these rules. For clarifications, justifications, and
explanations about the finer points of vimscript, please refer to the
<a href="vimscriptfull.xml">heavy guide</a>.
</p>
</CATEGORY>
</OVERVIEW>
<CATEGORY title="Portability">
<p>
It's hard to get vimscript right. Many commands depend upon the user's
settings. By following these guidelines, you can hope to make your
scripts portable.
</p>
<STYLEPOINT title="Strings">
<SUMMARY>Prefer single quoted strings</SUMMARY>
<BODY>
<p>
Double quoted strings are semantically different in vimscript, and
you probably don't want them (they break regexes).
</p>
<p>
Use double quoted strings when you need an escape sequence (such as
<code>"\n"</code>) or if you know it doesn't matter and you need to
embed single quotes.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Matching Strings">
<SUMMARY>
Use the <code>=~#</code> or <code>=~?</code> operator families over the
<code>=~</code> family.
</SUMMARY>
<BODY>
<p>
The matching behavior depends upon the user's ignorecase and smartcase
settings and on whether you compare them with the <code>=~</code>,
<code>=~#</code>, or <code>=~?</code> family of operators. Use the
<code>=~#</code> and <code>=~?</code> operator families explicitly
when comparing strings unless you explicitly need to honor the user's
case sensitivity settings.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Regular Expressions">
<SUMMARY>Prefix all regexes with <code>\m\C</code>.</SUMMARY>
<BODY>
<p>
In addition to the case sensitivity settings, regex behavior depends
upon the user's nomagic setting. To make regexes act like nomagic and
noignorecase are set, prepend all regexes with <code>\m\C</code>.
</p>
<p>
You are welcome to use other magic levels (<code>\v</code>) and case
sensitivities (<code>\c</code>) so long as they are intentional and
explicit.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Dangerous commands">
<SUMMARY>Avoid commands with unintended side effects.</SUMMARY>
<BODY>
<p>
Avoid using <code>:s[ubstitute]</code> as it moves the cursor and
prints error messages. Prefer functions (such as
<code>search()</code>) better suited to scripts.
</p>
<p>
For many vim commands, functions exist that do the same thing with
fewer side effects. See <code>:help functions()</code> for a list of
built-in functions.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Fragile commands">
<SUMMARY>Avoid commands that rely on user settings.</SUMMARY>
<BODY>
<p>
Always use <code>normal!</code> instead of <code>normal</code>. The
latter depends upon the user's key mappings and could do anything.
</p>
<p>
Avoid <code>:s[ubstitute]</code>, as its behavior depends upon a
number of local settings.
</p>
<p>
The same applies to other commands not listed here.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Catching Exceptions">
<SUMMARY>Match error codes, not error text.</SUMMARY>
<BODY>
<p>Error text may be locale dependant.</p>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="General Guidelines">
<STYLEPOINT title="Messaging">
<SUMMARY>Message the user infrequently.</SUMMARY>
<BODY>
<p>
Loud scripts are annoying. Message the user only when:
<ul>
<li>A long-running process has kicked off.</li>
<li>An error has occurred.</li>
</ul>
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Type checking">
<SUMMARY>Use strict and explicit checks where possible.</SUMMARY>
<BODY>
<p>
Vimscript has unsafe, unintuitive behavior when dealing with some
types. For instance, <code>0 == 'foo'</code> evaluates to true.
</p>
<p>
Use strict comparison operators where possible. When comparing against
a string literal, use the <code>is#</code> operator. Otherwise, prefer
<code>maktaba#value#IsEqual</code> or check <code>type()</code>
explicitly.
</p>
<p>
Check variable types explicitly before using them. Use functions from
<code>maktaba#ensure</code>, or check <code>maktaba#value</code> or
<code>type()</code> and throw your own errors.
</p>
<p>
Use <code>:unlet</code> for variables that may change types,
particularly those assigned inside loops.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Python">
<SUMMARY>Use sparingly.</SUMMARY>
<BODY>
<p>
Use python only when it provides critical functionality, for example
when writing threaded code.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Other Languages">
<SUMMARY>Use vimscript instead.</SUMMARY>
<BODY>
<p>
Avoid using other scripting languages such as ruby and lua. We can
not guarantee that the end user's vim has been compiled with support
for non-vimscript languages.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Boilerplate">
<SUMMARY>
Use <a href="https://github.com/google/maktaba">maktaba</a>.
</SUMMARY>
<BODY>
<p>
maktaba removes boilerplate, including:
<ul>
<li>Plugin creation</li>
<li>Error handling</li>
<li>Dependency checking</li>
</ul>
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Plugin layout">
<SUMMARY>Organize functionality into modular plugins</SUMMARY>
<BODY>
<p>
Group your functionality as a plugin, unified in one directory (or
code repository) which shares your plugin's name (with a "vim-" prefix
or ".vim" suffix if desired). It should be split into plugin/,
autoload/, etc. subdirectories as necessary, and it should declare
metadata in the addon-info.json format (see the
<a href="https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-additional-documentation.txt">VAM documentation</a> for details).
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Functions">
<SUMMARY>
In the autoload/ directory, defined with <code>[!]</code> and
<code>[abort]</code>.
</SUMMARY>
<BODY>
<p>
Autoloading allows functions to be loaded on demand, which makes
startuptime faster and enforces function namespacing.
</p>
<p>
Script-local functions are welcome, but should also live in autoload/
and be called by autoloaded functions.
</p>
<p>
Non-library plugins should expose commands instead of functions.
Command logic should be extracted into functions and autoloaded.
</p>
<p>
<code>[!]</code> allows developers to reload their functions
without complaint.
</p>
<p>
<code>[abort]</code> forces the function to halt when it encounters
an error.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Commands">
<SUMMARY>
In the plugin/commands.vim or under the ftplugin/ directory, defined
without <code>[!]</code>.
</SUMMARY>
<BODY>
<p>
General commands go in <code>plugin/commands.vim</code>.
Filetype-specific commands go in <code>ftplugin/</code>.
</p>
<p>
Excluding <code>[!]</code> prevents your plugin from silently
clobbering existing commands. Command conflicts should be resolved by
the user.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Autocommands">
<SUMMARY>
Place them in plugin/autocmds.vim, within augroups.
</SUMMARY>
<BODY>
<p>
Place all autocommands in augroups.
</p>
<p>
The augroup name should be unique. It should either be, or be prefixed
with, the plugin name.
</p>
<p>
Clear the augroup with <code>autocmd!</code> before defining new
autocommands in the augroup. This makes your plugin re-entrable.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Mappings">
<SUMMARY>
Place them in <code>plugin/mappings.vim</code>, using
<code>maktaba#plugin#MapPrefix</code> to get a prefix.
</SUMMARY>
<BODY>
<p>
All key mappings should be defined in
<code>plugin/mappings.vim</code>.
</p>
<p>
Partial mappings (see :help using-&lt;Plug&gt;.) should be defined in
<code>plugin/plugs.vim</code>.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Settings">
<SUMMARY>Change settings locally</SUMMARY>
<BODY>
<p>
Use <code>:setlocal</code> and <code>&amp;l:</code> instead of
<code>:set</code> and <code>&amp;</code> unless you have explicit
reason to do otherwise.
</p>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="Style">
<p>
Follow google style conventions. When in doubt, treat vimscript style
like python style.
</p>
<STYLEPOINT title="Whitespace">
<SUMMARY>
Similar to python.
<br/>
<br/>
</SUMMARY>
<BODY>
<ul>
<li>Use two spaces for indents</li>
<li>Do not use tabs</li>
<li>Use spaces around operators
<p>This does not apply to arguments to commands.</p>
<CODE_SNIPPET>
let s:variable = "concatenated " . "strings"
command -range=% MyCommand
</CODE_SNIPPET>
</li>
<li>Do not introduce trailing whitespace
<p>You need not go out of your way to remove it.</p>
<p>
Trailing whitespace is allowed in mappings which prep commands
for user input, such as
"<code>noremap &lt;leader&gt;gf :grep -f </code>".
</p>
</li>
<li>Restrict lines to 80 columns wide</li>
<li>Indent continued lines by four spaces</li>
<li>Do not align arguments of commands
<BAD_CODE_SNIPPET>
command -bang MyCommand call myplugin#foo()
command MyCommand2 call myplugin#bar()
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
command -bang MyCommand call myplugin#foo()
command MyCommand2 call myplugin#bar()
</CODE_SNIPPET>
</li>
</ul>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Naming">
<SUMMARY>
<p>
In general, use
<code>plugin-names-like-this</code>,
<code>FunctionNamesLikeThis</code>,
<code>CommandNamesLikeThis</code>,
<code>augroup_names_like_this</code>,
<code>variable_names_like_this</code>.
</p>
<p>Always prefix variables with their scope.</p>
</SUMMARY>
<BODY>
<SUBSECTION title="plugin-names-like-this">
<p>Keep them short and sweet.</p>
</SUBSECTION>
<SUBSECTION title="FunctionNamesLikeThis">
<p>Prefix script-local functions with <code>s:</code></p>
<p>Autoloaded functions may not have a scope prefix.</p>
<p>
Do not create global functions. Use autoloaded functions
instead.
</p>
</SUBSECTION>
<SUBSECTION title="CommandNamesLikeThis">
<p>Prefer succinct command names over common command prefixes.</p>
</SUBSECTION>
<SUBSECTION title="variable_names_like_this">
<p>Augroup names count as variables for naming purposes.</p>
</SUBSECTION>
<SUBSECTION title="Prefix all variables with their scope.">
<ul>
<li>Global variables with <code>g:</code></li>
<li>Script-local variables with <code>s:</code></li>
<li>Function arguments with <code>a:</code></li>
<li>Function-local variables with <code>l:</code></li>
<li>Vim-predefined variables with <code>v:</code></li>
<li>Buffer-local variables with <code>b:</code></li>
</ul>
<p>
<code>g:</code>, <code>s:</code>, and <code>a:</code> must always
be used.
</p>
<p>
<code>b:</code> changes the variable semantics; use it when you
want buffer-local semantics.
</p>
<p>
<code>l:</code> and <code>v:</code> should be used for consistency,
future proofing, and to avoid subtle bugs. They are not strictly
required. Add them in new code but dont go out of your way to add
them elsewhere.
</p>
</SUBSECTION>
</BODY>
</STYLEPOINT>
</CATEGORY>
<p align="right">
Revision 1.1
</p>
<address>
Nate Soares<br/>
Joshua Hoak<br/>
David Barnett<br/>
</address>
</GUIDE>

681
xmlstyle.html Normal file
View File

@ -0,0 +1,681 @@
<style type="text/css">
/* default css */
table {
font-size: 1em;
line-height: inherit;
}
tr {
text-align: left;
}
div, address, ol, ul, li, option, select {
margin-top: 0px;
margin-bottom: 0px;
}
p {
margin: 0px;
}
body {
margin: 6px;
padding: 0px;
font-family: Verdana, sans-serif;
font-size: 10pt;
background-color: #ffffff;
}
img {
-moz-force-broken-image-icon: 1;
}
@media screen {
html.pageview {
background-color: #f3f3f3 !important;
}
body {
min-height: 1100px;
counter-reset: __goog_page__;
}
* html body {
height: 1100px;
}
.pageview body {
border-top: 1px solid #ccc;
border-left: 1px solid #ccc;
border-right: 2px solid #bbb;
border-bottom: 2px solid #bbb;
width: 648px !important;
margin: 15px auto 25px;
padding: 40px 50px;
}
/* IE6 */
* html {
overflow-y: scroll;
}
* html.pageview body {
overflow-x: auto;
}
/* Prevent repaint errors when scrolling in Safari. This "Star-7" css hack
targets Safari 3.1, but not WebKit nightlies and presumably Safari 4.
That's OK because this bug is fixed in WebKit nightlies/Safari 4 :-). */
html*#wys_frame::before {
content: '\A0';
position: fixed;
overflow: hidden;
width: 0;
height: 0;
top: 0;
left: 0;
}
.writely-callout-data {
display: none;
*display: inline-block;
*width: 0;
*height: 0;
*overflow: hidden;
}
.writely-footnote-marker {
background-image: url('images/footnote_doc_icon.gif');
background-color: transparent;
background-repeat: no-repeat;
width: 7px;
overflow: hidden;
height: 16px;
vertical-align: top;
-moz-user-select: none;
}
.editor .writely-footnote-marker {
cursor: move;
}
.writely-footnote-marker-highlight {
background-position: -15px 0;
-moz-user-select: text;
}
.writely-footnote-hide-selection ::-moz-selection, .writely-footnote-hide-selection::-moz-selection {
background: transparent;
}
.writely-footnote-hide-selection ::selection, .writely-footnote-hide-selection::selection {
background: transparent;
}
.writely-footnote-hide-selection {
cursor: move;
}
.editor .writely-comment-yellow {
background-color: #FF9;
background-position: -240px 0;
}
.editor .writely-comment-yellow-hover {
background-color: #FF0;
background-position: -224px 0;
}
.editor .writely-comment-blue {
background-color: #C0D3FF;
background-position: -16px 0;
}
.editor .writely-comment-blue-hover {
background-color: #6292FE;
background-position: 0 0;
}
.editor .writely-comment-orange {
background-color: #FFDEAD;
background-position: -80px 0;
}
.editor .writely-comment-orange-hover {
background-color: #F90;
background-position: -64px 0;
}
.editor .writely-comment-green {
background-color: #99FBB3;
background-position: -48px 0;
}
.editor .writely-comment-green-hover {
background-color: #00F442;
background-position: -32px 0;
}
.editor .writely-comment-cyan {
background-color: #CFF;
background-position: -208px 0;
}
.editor .writely-comment-cyan-hover {
background-color: #0FF;
background-position: -192px 0;
}
.editor .writely-comment-purple {
background-color: #EBCCFF;
background-position: -144px 0;
}
.editor .writely-comment-purple-hover {
background-color: #90F;
background-position: -128px 0;
}
.editor .writely-comment-magenta {
background-color: #FCF;
background-position: -112px 0;
}
.editor .writely-comment-magenta-hover {
background-color: #F0F;
background-position: -96px 0;
}
.editor .writely-comment-red {
background-color: #FFCACA;
background-position: -176px 0;
}
.editor .writely-comment-red-hover {
background-color: #FF7A7A;
background-position: -160px 0;
}
.editor .writely-comment-marker {
background-image: url('images/markericons_horiz.gif');
background-color: transparent;
padding-right: 11px;
background-repeat: no-repeat;
width: 16px;
height: 16px;
-moz-user-select: none;
}
.editor .writely-comment-hidden {
padding: 0;
background: none;
}
.editor .writely-comment-marker-hidden {
background: none;
padding: 0;
width: 0;
}
.editor .writely-comment-none {
opacity: .2;
filter:progid:DXImageTransform.Microsoft.Alpha(opacity=20);
-moz-opacity: .2;
}
.editor .writely-comment-none-hover {
opacity: .2;
filter:progid:DXImageTransform.Microsoft.Alpha(opacity=20);
-moz-opacity: .2;
}
.br_fix br:not(:-moz-last-node):not(:-moz-first-node) {
position:relative;
left: -1ex
}
.br_fix br+br {
position: static !important
}
}
h6 { font-size: 8pt }
h5 { font-size: 8pt }
h4 { font-size: 10pt }
h3 { font-size: 12pt }
h2 { font-size: 14pt }
h1 { font-size: 18pt }
blockquote {padding: 10px; border: 1px #DDD dashed }
a img {border: 0}
.pb {
border-width: 0;
page-break-after: always;
/* We don't want this to be resizeable, so enforce a width and height
using !important */
height: 1px !important;
width: 100% !important;
}
.editor .pb {
border-top: 1px dashed #C0C0C0;
border-bottom: 1px dashed #C0C0C0;
}
div.google_header, div.google_footer {
position: relative;
margin-top: 1em;
margin-bottom: 1em;
}
/* Table of contents */
.editor div.writely-toc {
background-color: #f3f3f3;
border: 1px solid #ccc;
}
.writely-toc > ol {
padding-left: 3em;
font-weight: bold;
}
ol.writely-toc-subheading {
padding-left: 1em;
font-weight: normal;
}
/* IE6 only */
* html writely-toc ol {
list-style-position: inside;
}
.writely-toc-none {
list-style-type: none;
}
.writely-toc-decimal {
list-style-type: decimal;
}
.writely-toc-upper-alpha {
list-style-type: upper-alpha;
}
.writely-toc-lower-alpha {
list-style-type: lower-alpha;
}
.writely-toc-upper-roman {
list-style-type: upper-roman;
}
.writely-toc-lower-roman {
list-style-type: lower-roman;
}
.writely-toc-disc {
list-style-type: disc;
}
/* Ordered lists converted to numbered lists can preserve ordered types, and
vice versa. This is confusing, so disallow it */
ul[type="i"], ul[type="I"], ul[type="1"], ul[type="a"], ul[type="A"] {
list-style-type: disc;
}
ol[type="disc"], ol[type="circle"], ol[type="square"] {
list-style-type: decimal;
}
/* end default css */
/* custom css */
/* end custom css */
/* ui edited css */
body {
font-family: Verdana;
font-size: 10.0pt;
line-height: normal;
background-color: #ffffff;
}
/* end ui edited css */
/* editor CSS */
.editor a:visited {color: #551A8B}
.editor table.zeroBorder {border: 1px dotted gray}
.editor table.zeroBorder td {border: 1px dotted gray}
.editor table.zeroBorder th {border: 1px dotted gray}
.editor div.google_header, .editor div.google_footer {
border: 2px #DDDDDD dashed;
position: static;
width: 100%;
min-height: 2em;
}
.editor .misspell {background-color: yellow}
.editor .writely-comment {
font-size: 9pt;
line-height: 1.4;
padding: 1px;
border: 1px dashed #C0C0C0
}
/* end editor CSS */
</style>
<style>
body {
margin: 0px;
}
#doc-contents {
margin: 6px;
}
#google-view-footer {
clear: both;
border-top: thin solid;
padding-top: 0.3em;
padding-bottom: 0.3em;
}
a.google-small-link:link, a.google-small-link:visited {
color:#112ABB;
font-family:Arial,Sans-serif;
font-size:11px !important;
}
body, p, div, td {
direction: inherit;
}
@media print {
#google-view-footer {
display: none;
}
}
</style>
<script>
function viewOnLoad() {
if (document.location.href.indexOf('spi=1') != -1) {
if (navigator.userAgent.toLowerCase().indexOf('msie') != -1) {
window.print();
} else {
window.setTimeout(window.print, 10);
}
}
if (document.location.href.indexOf('hgd=1') != -1) {
var footer = document.getElementById("google-view-footer");
if (footer) {
footer.style.display = 'none';
}
}
}
</script>
</head>
<body>
<div id="doc-contents">
<div>
<h1 style="text-align: center;">
Google XML Document Format Style Guide</h1><div style="text-align: center;">Version 1.0<br>Copyright Google 2008<br><br></div><h2>Introduction</h2>This document provides a set of guidelines for general use when designing new XML document formats (and to some extent XML documents as well; see Section 11).&nbsp; Document formats usually include both formal parts (DTDs, schemas) and parts expressed in normative English prose.<br><br>These guidelines apply to new designs, and are not intended to force retroactive changes in existing designs.&nbsp; When participating in the creation of public or private document format designs, the guidelines may be helpful but should not control the group consensus.<br><br>This guide is meant for the design of XML that is to be generated and consumed by machines rather than human beings.&nbsp; Its rules are <i>not applicable</i> to formats such as XHTML (which should be formatted as much like HTML as possible) or ODF which are meant to express rich text.&nbsp; A document that includes embedded content in XHTML or some other rich-text format, but also contains purely machine-interpretable portions, SHOULD follow this style guide for the machine-interpretable portions.&nbsp; It also does not affect XML document formats that are created by translations from proto buffers or through some other type of format.<br><br>Brief rationales have been added to most of the guidelines.&nbsp; They are maintained in the same document in hopes that they won't get out of date, but they are not considered normative.<br><br>The terms MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used in this document in the sense of <a title="RFC 2119" href="https://www.ietf.org/rfc/rfc2119.txt" id="iecm">RFC 2119.</a><br>&nbsp;<br><h2>1. To design or not to design, that is the question<br></h2><ol><li>Attempt to reuse existing XML formats whenever possible, especially those which allow extensions.&nbsp; Creating an entirely new format should be done only with care and consideration; read <a title="Tim Bray's warnings" href="https://www.tbray.org/ongoing/When/200x/2006/01/08/No-New-XML-Languages" id="d3cy">Tim Bray's warnings</a> first.&nbsp; Try to get wide review of your format, from outside your organization as well, if possible.&nbsp; [<i>Rationale:</i> New document formats have a cost: they must be reviewed, documented, and learned by users.]<br><br></li><li>If you are reusing or extending an existing format, make <i>sensible</i>
use of the prescribed elements and attributes, especially any that are
required.&nbsp; Don't completely repurpose them, but do try to see how they
might be used in creative ways if the vanilla semantics aren't
suitable.&nbsp; As a last resort when an element or attribute is required by the format but is not appropriate for your use case, use some
fixed string as its value.&nbsp; [<i>Rationale:</i>&nbsp; Markup reuse is good, markup abuse is bad.]<br><br></li><li>When extending formats, use the implicit style of the existing format, even if it contradicts this guide.&nbsp; [<i>Rationale: </i>Consistency.]<br></li></ol><br><h2>2. Schemas</h2><ol><li>Document formats SHOULD be expressed using a schema language.&nbsp; [<i>Rationale: </i>Clarity and machine-checkability.]<br><br></li><li>The schema language SHOULD be <a title="RELAX NG" href="http://www.relaxng.org/" id="p1s7">RELAX NG</a> <a title="compact syntax" href="http://www.relaxng.org/compact-tutorial-20030326.html" id="ulci">compact syntax</a>.&nbsp; Embedded <a title="Schematron" href="http://www.schematron.com/" id="ymh-">Schematron</a> rules MAY be added to the schema for additional fine control.&nbsp; [<i>Rationale:</i>
RELAX NG is the most flexible schema language, with very few arbitrary
restrictions on designs.&nbsp; The compact syntax is quite easy to read and
learn, and can be converted one-to-one to and from the XML syntax when
necessary.&nbsp; Schematron handles arbitrary cross-element and
cross-attribute constraints nicely.]<br><br></li><li>Schemas SHOULD use the <a title="&quot;Salami Slice&quot; style" href="http://www.xfront.com/GlobalVersusLocal.html#SecondDesign" id="r:fj">"Salami Slice" style</a> (one rule per element).&nbsp; Schemas MAY use the <a title="&quot;Russian Doll&quot; style" href="http://www.xfront.com/GlobalVersusLocal.html#FirstDesign" id="h14y">"Russian Doll" style</a> (schema resembles document) if they are short and simple.&nbsp; The <a title="&quot;Venetian Blind&quot; style" href="http://www.xfront.com/GlobalVersusLocal.html#ThirdDesign" id="dr_g">"Venetian Blind" style</a> (one rule per element type) is unsuited to RELAX NG and SHOULD NOT be used.<br><br></li><li>Regular expressions SHOULD be provided to assist in validating complex values.<br><br></li><li>DTDs and/or W3C XML Schemas MAY be provided for compatibility with existing products, tools, or users.&nbsp; [<i>Rationale:</i> We can't change the world all at once.]<br></li></ol></div><div><br><h2>3. Namespaces</h2><ol><li>Element names MUST be in a namespace, except
when extending pre-existing document types that do not use namespaces.&nbsp;
A default namespace SHOULD be used.&nbsp; [<i>Rationale:</i> Namespace-free
documents are obsolete; every set of names should be in some
namespace.&nbsp; Using a default namespace improves readability.]<br><br></li><li>Attribute
names SHOULD NOT be in a namespace unless they are drawn from a foreign
document type or are meant to be used in foreign document types.&nbsp; [<i>Rationale:</i> Attribute names in a namespace must always have a prefix, which is annoying to type and hard to read.]<br><br>
</li><li>Namespace names are HTTP URIs.&nbsp; Namespace names SHOULD take the form <span style="font-family: Courier New;">https://example.com/</span><i style="font-family: Courier New;">whatever</i><span style="font-family: Courier New;">/</span><i><span style="font-family: Courier New;">year</span>, </i>where <i>whatever</i> is a unique value based on the name of the document type, and <i>year</i>
is the year the namespace was created.&nbsp; There may be additional URI-path parts
before the <i>year.</i>&nbsp; [<i>Rationale:</i> Existing convention.&nbsp; Providing the year allows for the possible recycling of code names.]<br><br></li><li>Namespaces MUST NOT be changed unless the semantics of particular elements or attributes has changed in drastically incompatible ways.&nbsp; [<i>Rationale:</i> Changing the namespace requires changing all client code.]<br><br></li><li>Namespace prefixes SHOULD be short (but not so short that they are likely to be conflict with another project).&nbsp; Single-letter prefixes MUST NOT be used. Prefixes SHOULD contain only lower-case ASCII letters.&nbsp; [<i>Rationale:</i> Ease of typing and absence of encoding compatibility problems.]</li></ol><br>
<h2>4. Names and enumerated values</h2><b>Note: </b>"Names" refers to the names of elements, attributes, and enumerated values.<br><br><ol><li>All names MUST use lowerCamelCase. That is, they start with an initial lower-case letter, then each new word within the name starts with an initial capital letter. [<i>Rationale:</i> Adopting a single style provides consistency, which helps when referring to names since the capitalization is known and so does not have to be remembered.&nbsp; It matches Java style, and other languages can be dealt with using automated name conversion.]<br><br></li><li>Names MUST contain only ASCII letters and digits.&nbsp;
[<i>Rationale:</i> Ease of typing and absence of encoding compatibility problems.]<br> <br></li><li>Names SHOULD NOT exceed 25 characters. Longer names SHOULD be
avoided by devising concise and informative names.&nbsp; If a name can only remain within this limit by becoming obscure, the limit SHOULD be ignored.&nbsp; [<i>Rationale: </i>Longer names are awkward to use and require additional bandwidth.]<br><br></li><li>Published standard abbreviations, if sufficiently well-known, MAY be employed in constructing names. Ad hoc abbreviations MUST NOT be used.&nbsp; Acronyms MUST be treated as words for camel-casing purposes: informationUri, not informationURI. [<i>Rationale:</i>&nbsp; An abbreviation that is well known
to one community is often incomprehensible to others who need to use
the same document format (and who do understand the full name); treating an acronym as a word makes it easier to see where the word boundaries are.] <br></li></ol><p><br></p><p>
</p><h2>
5. Elements</h2><ol><li>All elements MUST contain either nothing, character content, or child elements.&nbsp; Mixed content MUST NOT be used.&nbsp; [<i>Rationale:</i> Many XML data models don't handle mixed content properly, and its use makes the element order-dependent.&nbsp; As always, textual formats are not covered by this rule.]<br><br></li><li>XML elements that merely wrap repeating child elements SHOULD NOT be used.&nbsp; [<i>Rationale:</i> They are not used in Atom and add nothing.]</li></ol>
<p><br></p><h2>6. Attributes</h2><ol><li>Document formats MUST NOT depend on the order of attributes in a start-tag.&nbsp; [<i>Rationale:</i> Few XML parsers report the order, and it is not part of the XML Infoset.]<br><br></li><li>Elements SHOULD NOT be overloaded with too many attributes (no more
than 10 as a rule of thumb).&nbsp; Instead, use child elements to
encapsulate closely related attributes.&nbsp; [<i>Rationale:</i> This
approach maintains the built-in extensibility that XML provides with
elements, and is useful for providing forward compatibility as a
specification evolves.]<br><br></li><li>Attributes MUST NOT be used to hold values in which line breaks are significant.&nbsp; [<i>Rationale:</i> Such line breaks are converted to spaces by conformant XML parsers.]<br><br></li><li>Document formats MUST allow either single or double quotation marks around attribute values.&nbsp; [<i>Rationale:</i>&nbsp; XML parsers don't report the difference.]<br></li></ol>
<p><br></p>
<p>
</p><h2>
7. Values</h2><ol><li>Numeric values SHOULD be 32-bit signed integers, 64-bit signed integers, or 64-bit IEEE doubles, all expressed in base 10.&nbsp; These correspond to the XML Schema types <span style="font-family: Courier New;">xsd:int</span>, <span style="font-family: Courier New;">xsd:long</span>, and <span style="font-family: Courier New;">xsd:double</span> respectively.&nbsp; If required in particular cases, <span style="font-family: Courier New;">xsd:integer</span> (unlimited-precision integer) values MAY also be used.&nbsp; [<i>Rationale:</i> There are far too many numeric types in XML Schema: these provide a reasonable subset.]&nbsp; <br><br></li><li>
Boolean values SHOULD NOT be used (use enumerations instead).&nbsp; If they must be used, they MUST be expressed as <span style="font-family: Courier New;">true</span> or <span style="font-family: Courier New;">false</span>, corresponding to a subset of the XML Schema type <span style="font-family: Courier New;">xsd:boolean</span>.&nbsp; The alternative <span style="font-family: Courier New;">xsd:boolean</span> values <span style="font-family: Courier New;">1</span> and <span style="font-family: Courier New;">0</span> MUST NOT be used.&nbsp; [<i>Rationale:</i> Boolean arguments are not extensible.&nbsp; The additional flexibility of allowing numeric values is not abstracted away by any parser.]<br><br></li><li>Dates should be represented using <a title="RFC 3339" href="https://www.ietf.org/rfc/rfc3339.txt" id="sk98">RFC 3339</a> format, a subset of both
ISO 8601 format and XML Schema <span style="font-family: Courier New;">xsd:dateTime</span> format.&nbsp; UTC times SHOULD be used rather than local times.&nbsp;
[<i>Rationale:</i> There are far too many date formats and time zones, although it is recognized that sometimes local time preserves important information.]<br><br></li><li>Embedded syntax in character content and attribute values SHOULD NOT be
used.&nbsp; Syntax in values means XML tools are largely useless.&nbsp; Syntaxes such as&nbsp; dates, URIs, and
XPath expressions are exceptions.&nbsp; [<i>Rationale:</i>&nbsp;
Users should be able to process XML documents using only an XML parser
without requiring additional special-purpose parsers, which are easy to
get wrong.]<br><br></li><li>Be careful with whitespace in values.&nbsp; XML parsers don't strip whitespace in elements, but do convert newlines to spaces in attributes.&nbsp; However, application frameworks may do more aggressive whitespace stripping.&nbsp; Your document format SHOULD give rules for whitespace stripping.<br></li></ol>
<p><br>
</p>
<p>
</p><h2>8. Key-value pairs<br></h2><ol><li>
Simple key-value pairs SHOULD be represented with an empty element whose name represents the key, with the <span style="font-family: Courier New;">value</span> attribute containing the value. Elements that have a <span style="font-family: Courier New;">value</span> attribute MAY also have a <span style="font-family: Courier New;">unit</span> attribute to specify the unit of a measured value.&nbsp; For physical measurements, the <a title="SI system" href="https://en.wikipedia.org/wiki/International_System_of_Units" id="rhxg">SI system</a> SHOULD be used.&nbsp; [<i>Rationale:</i>
Simplicity and design consistency.&nbsp; Keeping the value in an attribute
hides it from the user, since displaying just the value without the key is not useful.]<br><br></li><li>If the number of possible keys is very large or unbounded, key-value pairs MAY be represented by a single generic element with <span style="font-family: Courier New;">key</span>, <span style="font-family: Courier New;">value</span>, and optional <span style="font-family: Courier New;">unit</span> and <span style="font-family: Courier New;">scheme</span>
attributes (which serve to discriminate keys from different domains).&nbsp;
In that case, also provide (not necessarily in the same document) a
list of keys with human-readable explanations.</li></ol><br><h2>9. Binary data</h2><p><b>Note: </b>There are no hard and fast rules about whether binary data should be included as part of an XML document or not.&nbsp; If it's too large, it's probably better to link to it.</p><p><br></p><ol><li>Binary data MUST NOT be included directly as-is in XML documents, but MUST be encoded using Base64 encoding.&nbsp; [<i>Rationale:</i> XML does not allow arbitrary binary bytes.]<br><br></li><li>
The line breaks required by Base64 MAY be omitted.&nbsp; [<i>Rationale:</i> The line breaks are meant to keep plain text lines short, but XML is not really plain text.]<br><br></li><li>An attribute named <span style="font-family: Courier New;">xsi:type</span> with value <span style="font-family: Courier New;">xs:base64Binary</span> MAY be attached to this element to signal that the Base64 format is in use.&nbsp; [Rationale: Opaque blobs should have decoding instructions attached.]<br><br></li></ol>
<h2>10. Processing instructions</h2><ol><li>New processing instructions MUST NOT be created except in order to specify purely local processing conventions, and SHOULD be avoided altogether.&nbsp; Existing standardized processing instructions MAY be used.&nbsp; [<i>Rationale:</i> Processing instructions fit awkwardly into XML data models and can always be replaced by elements; they exist primarily to avoid breaking backward compatibility.]</li></ol><p>&nbsp;</p>
<p>
</p><p>&nbsp;</p><h2>11. Representation of XML document instances<br></h2><p><b>Note:</b>&nbsp; These points are only guidelines, as the format of program-created instances will often be outside the programmer's control (for example, when an XML serialization library is being used).&nbsp; <i>In no case</i> should XML parsers rely on these guidelines being followed.&nbsp; Use standard XML parsers, not hand-rolled hacks.<br></p><p><br></p><ol><li>The character encoding used SHOULD be UTF-8.&nbsp; Exceptions should require extremely compelling circumstances.&nbsp; [<i>Rationale:</i> UTF-8 is universal and in common use.]<br><br></li><li>Namespaces SHOULD be declared in the root element of a document wherever possible.&nbsp; [<i>Rationale: </i>Clarity and consistency.]<br><br></li><li>The mapping of namespace URIs to prefixes SHOULD remain constant throughout the document, and SHOULD also be used in documentation of the design.&nbsp; [<i>Rationale: </i>Clarity and consistency.]<br><br></li><li>Well-known prefixes such as html: (for XHTML), dc: (for Dublin Core metadata), and xs: (for XML Schema) should be used for standard namespaces.&nbsp; [<i>Rationale:</i> Human readability.]<br><br></li><li>Redundant whitespace in a tag SHOULD NOT be
used.&nbsp; Use one space before each attribute in a start-tag; if the start
tag is too long, the space MAY be replaced by a newline.&nbsp; [<i>Rationale:</i> Consistency and conciseness.]<br><br></li><li>Empty elements MAY be expressed as empty tags or a start-tag
immediately followed by an end-tag. No distinction should be made
between these two formats by any application.&nbsp; [<i>Rationale:</i> They are not distinguished by XML parsers.]<br><br></li><li>Documents MAY be pretty-printed using 2-space indentation for child
elements.&nbsp; Elements that contain character content SHOULD NOT be
wrapped.&nbsp; Long start-tags MAY be broken using newlines (possibly with extra indentation) after any attribute value except the last.&nbsp; [<i>Rationale:</i> General compatibility with our style.&nbsp; Wrapping character content affects its value.]<br><br></li><li>Attribute values MAY be surrounded with either quotation marks or apostrophes.
Specifications MUST NOT require or forbid the use of either form.&nbsp; <span style="font-family: Courier New;">&amp;apos;</span> and <span style="font-family: Courier New;">&amp;quot;</span> may be freely used to escape each type of quote.&nbsp; [<i>Rationale:</i> No XML parsers report the distinction.]<br><br>
</li><li>Comments MUST NOT be used to carry real data.&nbsp; Comments MAY be used to contain TODOs in hand-written XML.&nbsp; Comments SHOULD NOT be used at all in publicly transmitted documents. [<i>Rationale:&nbsp; </i>Comments are often discarded by parsers.]<br><br></li><li>If comments are nevertheless used, they SHOULD appear only in the document prolog or in elements that
contain child elements.&nbsp; If pretty-printing is required, pretty-print
comments like elements, but with line wrapping.&nbsp; Comments SHOULD NOT
appear in elements that contain character content.&nbsp; [<i>Rationale:&nbsp; </i>Whitespace in and around comments improves readability, but embedding a
comment in character content can lead to confusion about what
whitespace is or is not in the content.]<br><br></li><li>Comments SHOULD have whitespace following <span style="font-family: Courier New;">&lt;!--</span> and preceding <span style="font-family: Courier New;">--&gt;</span>.&nbsp; [<i>Rationale:</i> Readability.]<br><br></li><li>CDATA sections MAY be used; they are equivalent to the use of <span style="font-family: Courier New;">&amp;amp;</span> and <span style="font-family: Courier New;">&amp;lt;</span>.&nbsp; Specifications MUST NOT require or forbid the use of CDATA sections.&nbsp; [<i>Rationale:</i> Few XML parsers report the distinction, and combinations of CDATA and text are often reported as single objects anyway.]<br><br></li><li>Entity references other than the XML standard entity references <span style="font-family: Courier New;">&amp;amp;</span>, <span style="font-family: Courier New;">&amp;lt;</span>, <span style="font-family: Courier New;">&amp;gt;</span>, <span style="font-family: Courier New;">&amp;quot;</span>, and <span style="font-family: Courier New;">&amp;apos;</span> MUST NOT be used.&nbsp; Character references MAY be used, but actual characters are preferred, unless the character encoding is not UTF-8.&nbsp; As usual, textual formats are exempt from this rule.<br></li></ol>
<br><p>&nbsp;</p><p>
</p>
<p>
</p><br><br><h2>
12. Elements vs. Attributes
</h2>
<p>
<b>Note:</b>&nbsp; There are no hard and fast rules for deciding when to use attributes and when to use elements.&nbsp; Here are some of the considerations that designers should take into account; no rationales are given.
</p>
<h3>
12.1. General points:<br>
</h3>
<ol>
<li>
<p>
Attributes are more restrictive than elements, and all designs have some elements, so an all-element design is simplest -- which is not the same as best.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
In a tree-style data model, elements are typically represented internally as nodes, which use more memory than the strings used to represent attributes.&nbsp; Sometimes the nodes are of different application-specific classes, which in many languages also takes up memory to represent the classes.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
When streaming, elements are processed one at a time (possibly even piece by piece, depending on the XML parser you are using), whereas all the attributes of an element and their values are reported at once, which costs memory, particularly if some attribute values are very long.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Both element content and attribute values need to be escaped appropriately, so escaping should not be a consideration in the design.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
In some programming languages and libraries, processing elements is easier; in others, processing attributes is easier.&nbsp; Beware of using ease of processing as a criterion.&nbsp; In particular, XSLT can handle either with equal facility.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data should usually be shown to the user, consider using an element; if not, consider using an attribute.&nbsp; (This rule is often violated for one reason or another.)
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If you are extending an existing schema, do things by analogy to how things are done in that schema.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Sensible schema languages, meaning RELAX NG and Schematron, treat elements and attributes symmetrically.&nbsp; Older and cruder<a href="https://www.w3.org/TR/2004/REC-xmlschema-0-20041028/" id="h2c3" title="XML Schema"> </a>schema languages such as DTDs and XML Schema, tend to have better support for elements.
</p>
</li>
</ol>
<p>
</p>
<h3>
12.2 Using elements<br>
</h3>
<ol>
<li>
<p>
If something might appear more than once in a data model, use an element rather than introducing attributes with names like <span style="font-family: Courier New;">foo1, foo2, foo3</span> ....
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Use elements to represent a piece of information that can be considered an independent object and when the information is related via a parent/child relationship to another piece of information.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Use elements when data incorporates strict typing or relationship rules.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If order matters between two pieces of data, use elements for them: attributes are inherently unordered.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data has, or might have, its own substructure, use it in an element: getting substructure into an attribute is always messy.&nbsp; Similarly, if the data is a constituent part of some larger piece of data, put it in an element.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
An exception to the previous rule: multiple whitespace-separated tokens can safely be put in an attribute.&nbsp; In principle, the separator can be anything, but schema-language validators are currently only able to handle whitespace, so it's best to stick with that.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data extends across multiple lines, use an element: XML parsers will change newlines in attribute values into spaces.
<br><br></p></li><li>If a piece of data is very large, use an element so that its content can be streamed.<br><br></li>
<li>
<p>
If a piece of data is in a natural language, put it in an element so you can use the <span style="font-family: Courier New;">xml:lang</span> attribute to label the language being used.&nbsp; Some kinds of natural-language text, like Japanese, often make use <a href="https://www.w3.org/TR/2001/REC-ruby-20010531" id="pa2f" title="annotations">annotations</a> that are conventionally represented using child elements; right-to-left languages like Hebrew and Arabic may similarly require child elements to manage <a href="https://www.w3.org/TR/2001/REC-ruby-20010531" id="ehyv" title="bidirectionality">bidirectionality</a> properly.
</p>
<p>
</p>
</li>
</ol>
<h3>
12.3 Using attributes<br>
</h3>
<ol>
<li>
<p>
If the data is a code from an enumeration, code list, or controlled vocabulary, put it in an attribute if possible.&nbsp; For example, language tags, currency codes, medical diagnostic codes, etc. are best handled as attributes.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data is really metadata on some other piece of data (for example, representing a class or role that the main data serves,&nbsp; or specifying a method of processing it), put it in an attribute if possible.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
In particular, if a piece of data is an ID for some other piece of data, or a reference to such an ID, put the identifying piece in an attribute.&nbsp; When it's an ID, use the name <span style="font-family: Courier New;">xml:id</span> for the attribute.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Hypertext references are conventionally put in <span style="font-family: Courier New;">href</span> attributes.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data is applicable to an element and any descendant elements unless it is overridden in some of them, it is conventional to put it in an attribute.&nbsp; Well-known examples are <span style="font-family: Courier New;">xml:lang</span>, <span style="font-family: Courier New;">xml:space</span>, <span style="font-family: Courier New;">xml:base</span>, and namespace declarations.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If terseness is really the <i>most</i> important thing, use attributes, but consider <span style="font-family: Courier New;">gzip</span> compression instead -- it works very well on documents with highly repetitive structures.</p></li>
</ol></div><br><div><div><div><div><div>
<br><h2>13. Parting words
</h2>
<p>
</p><p>
Use common sense and <i>BE CONSISTENT</i>.&nbsp;&nbsp; Design for extensibility.&nbsp; You <i>are</i> gonna need it.&nbsp; [<i>Rationale:</i> Long and painful experience.]<br></p><p><br> </p>
<p>
When designing XML formats, take a few minutes to look at other formats and determine their style.&nbsp; The point of having style guidelines is so that people can concentrate on what you are
saying, rather than on how you are saying it. <br></p><p>
<br>
Break <i>ANY OR ALL</i> of these rules (yes, even the ones that say MUST) rather than create a crude, arbitrary, disgusting mess of a design if that's what following them slavishly would give you.&nbsp; In particular, random mixtures of attributes and child elements are hard to follow and hard to use, though it often makes good sense to use both when the data clearly fall into two different groups such as simple/complex or metadata/data.
</p>
<div><p>
<br>
Newbies always ask:
</p>
<p>
&nbsp;&nbsp;&nbsp; "Elements or attributes?
</p>
<p>
Which will serve me best?"
</p>
<p>
&nbsp;&nbsp;&nbsp; Those who know roar like lions;
</p>
<p>
&nbsp;&nbsp;&nbsp; Wise hackers smile like tigers.
</p>
<p>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; --a <a href="https://en.wikipedia.org/wiki/Waka_%28poetry%29#Forms_of_waka" id="s3k3" title="tanka">tanka</a>, or extended haiku
</p>
</div>
<p>
<br>
</p>
<br>[TODO: if a registry of schemas is set up, add a link to it]<br><br></div><br></div><br></div></div></div><br>
<br clear="all"/>
</div>