mirror of https://github.com/google/styleguide
Ted Osborne
parent
54cca78d64
commit
505ba68c74
|
|
@ -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/
|
||||
|
|
@ -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><-</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><-</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 <- table(df[df$days.from.opt < 0, "campaign.id"])
|
||||
total <- sum(x[, 1])
|
||||
total <- sum(x[1, ])</pre>
|
||||
<p>
|
||||
BAD:
|
||||
</p>
|
||||
<pre><span style="color:red">tab.prior <- table(df[df$days.from.opt<0, "campaign.id"]) # Needs spaces around '<'
|
||||
tab.prior <- table(df[df$days.from.opt < 0,"campaign.id"]) # Needs a space after the comma
|
||||
tab.prior<- table(df[df$days.from.opt < 0, "campaign.id"]) # Needs a space before <-
|
||||
tab.prior<-table(df[df$days.from.opt < 0, "campaign.id"]) # Needs spaces around <-
|
||||
total <- sum(x[,1]) # Needs a space after the comma
|
||||
total <- 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><-</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 <- c(0, 0.06)
|
||||
}</pre>
|
||||
<p>
|
||||
xor (but not both)
|
||||
</p>
|
||||
<pre>
|
||||
if (is.null(ylim))
|
||||
ylim <- 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 <- c(0, 0.06)</span></code>
|
||||
<br/><code><span style="color:red"> if (is.null(ylim))
|
||||
{ylim <- 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><-</code>, not <code>=</code>, for assignment.
|
||||
</p>
|
||||
<p>
|
||||
GOOD:
|
||||
<br/><code> x <- 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 <- function(query, property, num.days,
|
||||
show.plot = TRUE)
|
||||
</pre>
|
||||
BAD:
|
||||
<pre><span style="color:red">PredictCTR <- 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 <- 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 <- length(x)
|
||||
# Error handling
|
||||
if (n <= 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 <- 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>
|
||||
|
|
@ -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>
|
||||
<div ng-controller="hello.mainpage.HomeCtrl"/>
|
||||
<span ng-class="homeCtrl.myColor">I'm in a color!</span>
|
||||
<span>{{homeCtrl.add(5, 6)}}</span>
|
||||
</div>
|
||||
</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>
|
||||
<div ng-controller="hello.mainpage.HomeCtrl as homeCtrl"/>
|
||||
<span ng-class="homeCtrl.myColor">I'm in a color!</span>
|
||||
<span>{{homeCtrl.add(5, 6)}}</span>
|
||||
</div>
|
||||
</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><ng-include src="template"></ng-include></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>
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -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>
|
||||
|
|
@ -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.
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1 @@
|
|||
// A test header for cpplint_unittest.py.
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1 @@
|
|||
// A test header for cpplint_unittest.py.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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/`.
|
||||
|
||||
...
|
||||
```
|
||||
|
|
@ -0,0 +1 @@
|
|||
1.0
|
||||
|
|
@ -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).
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
||||
`Backticks` 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.
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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
|
||||
|
|
@ -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>
|
||||
|
|
@ -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"><!-- Not recommended: omits the protocol -->
|
||||
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
|
||||
|
||||
<!-- Not recommended: uses the HTTP protocol -->
|
||||
<script src="http://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
|
||||
</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’t use tabs or mix tabs and spaces for indentation.</p>
|
||||
|
||||
<pre><code class="language-html prettyprint"><ul>
|
||||
<li>Fantastic
|
||||
<li>Great
|
||||
</ul>
|
||||
</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"><!-- Not recommended -->
|
||||
<A HREF="/">Home</A>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
<img src="google.png" alt="Google">
|
||||
</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"><!-- Not recommended -->
|
||||
<p>What?_
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
<p>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><meta
|
||||
charset="utf-8"></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’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 #}
|
||||
<center>Test</center>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- TODO: remove optional tags -->
|
||||
<ul>
|
||||
<li>Apples</li>
|
||||
<li>Oranges</li>
|
||||
</ul>
|
||||
</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><!DOCTYPE html></code>.</p>
|
||||
|
||||
<p>(It’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><br></code>, not
|
||||
<code><br /></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"><!-- Not recommended -->
|
||||
<title>Test</title>
|
||||
<article>This is only a test.
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
<!DOCTYPE html>
|
||||
<meta charset="utf-8">
|
||||
<title>Test</title>
|
||||
<article>This is only a test.</article>
|
||||
</code></pre>
|
||||
|
||||
<h4 id="Semantics">3.1.3 Semantics</h4>
|
||||
|
||||
<p>Use HTML according to its purpose.</p>
|
||||
|
||||
<p>Use elements (sometimes incorrectly called “tags”) 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"><!-- Not recommended -->
|
||||
<div onclick="goToRecommendations();">All recommendations</div>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
<a href="recommendations/">All recommendations</a>
|
||||
</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"><!-- Not recommended -->
|
||||
<img src="spreadsheet.png">
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
|
||||
</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"><!-- Not recommended -->
|
||||
<!DOCTYPE html>
|
||||
<title>HTML sucks</title>
|
||||
<link rel="stylesheet" href="base.css" media="screen">
|
||||
<link rel="stylesheet" href="grid.css" media="screen">
|
||||
<link rel="stylesheet" href="print.css" media="print">
|
||||
<h1 style="font-size: 1em;">HTML sucks</h1>
|
||||
<p>I’ve read about this on a few sites but now I’m sure:
|
||||
<u>HTML is stupid!!1</u>
|
||||
<center>I can’t believe there’s no way to control the styling of
|
||||
my website without doing everything all over again!</center>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
<!DOCTYPE html>
|
||||
<title>My first CSS-only redesign</title>
|
||||
<link rel="stylesheet" href="default.css">
|
||||
<h1>My first CSS-only redesign</h1>
|
||||
<p>I’ve read about this on a few sites but today I’m actually
|
||||
doing it: separating concerns and avoiding anything in the HTML of
|
||||
my website that is presentational.
|
||||
<p>It’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>&mdash;</code>, <code>&rdquo;</code>, or
|
||||
<code>&#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><</code>
|
||||
and <code>&</code>) as well as control or “invisible” characters (like no-break spaces).</p>
|
||||
|
||||
<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
|
||||
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
The currency symbol for the Euro is “€”.
|
||||
</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’s significantly different from what web developers are typically taught.
|
||||
For consistency and simplicity reasons it’s best served omitting all optional
|
||||
tags, not just a selection.)</p>
|
||||
|
||||
<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Spending money, spending bytes</title>
|
||||
</head>
|
||||
<body>
|
||||
<p>Sic.</p>
|
||||
</body>
|
||||
</html>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
<!DOCTYPE html>
|
||||
<title>Saving money, saving bytes</title>
|
||||
<p>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"><!-- Not recommended -->
|
||||
<link rel="stylesheet" href="https://www.google.com/css/maia.css"
|
||||
type="text/css">
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
<link rel="stylesheet" href="https://www.google.com/css/maia.css">
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
|
||||
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"
|
||||
type="text/javascript"></script>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||||
</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’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"><blockquote>
|
||||
<p><em>Space</em>, the final frontier.</p>
|
||||
</blockquote>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><ul>
|
||||
<li>Moe
|
||||
<li>Larry
|
||||
<li>Curly
|
||||
</ul>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th scope="col">Income
|
||||
<th scope="col">Taxes
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>$ 5.00
|
||||
<td>$ 4.50
|
||||
</table>
|
||||
</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"><md-progress-circular md-mode="indeterminate" class="md-accent"
|
||||
ng-show="ctrl.loading" md-diameter="35">
|
||||
</md-progress-circular>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><md-progress-circular
|
||||
md-mode="indeterminate"
|
||||
class="md-accent"
|
||||
ng-show="ctrl.loading"
|
||||
md-diameter="35">
|
||||
</md-progress-circular>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><md-progress-circular md-mode="indeterminate"
|
||||
class="md-accent"
|
||||
ng-show="ctrl.loading"
|
||||
md-diameter="35">
|
||||
</md-progress-circular>
|
||||
</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"><!-- Not recommended -->
|
||||
<a class='maia-button maia-button-secondary'>Sign in</a>
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html prettyprint"><!-- Recommended -->
|
||||
<a class="maia-button maia-button-secondary">Sign in</a>
|
||||
</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 “helpers.”</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 “0” 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 “0”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 “demo” and “image” */
|
||||
.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 “hacks”—try a different approach
|
||||
first.</p>
|
||||
|
||||
<p>It’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—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’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—<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’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’re saying rather than on how you’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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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);
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 189 B |
|
|
@ -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;
|
||||
}
|
||||
|
|
@ -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');
|
||||
}
|
||||
|
|
@ -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>
|
||||
|
|
@ -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;
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
Binary file not shown.
|
After Width: | Height: | Size: 189 B |
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -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>
|
||||
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 |
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -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>
|
||||
File diff suppressed because it is too large
Load Diff
2568
pyguide.md
2568
pyguide.md
File diff suppressed because it is too large
Load Diff
|
|
@ -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;
|
||||
}
|
||||
|
||||
|
|
@ -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="'▶'" />
|
||||
<xsl:variable name="hide_button_text" select="'▽'" />
|
||||
<!-- 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 && str.indexOf(suffix, l) == l;
|
||||
}
|
||||
|
||||
function RefreshVisibilityFromHashParam() {
|
||||
var hashRegexp = new RegExp('#([^&#]*)$');
|
||||
var hashMatch = hashRegexp.exec(window.location.href);
|
||||
var anchor = hashMatch && GetElementsByName(hashMatch[1])[0];
|
||||
var node = anchor;
|
||||
var suffix = '<xsl:value-of select="$body_suffix"/>';
|
||||
while (node) {
|
||||
var id = node.id;
|
||||
var matched = id && 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("[\\?&](showall)=([^&#]*)");
|
||||
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("[\\?&](showone)=([^&#]*)");
|
||||
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="" ()#'""/>
|
||||
<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, '
')"/>
|
||||
<xsl:variable name="rest" select="substring-after($text, '
')"/>
|
||||
<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 < $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, '
')">
|
||||
<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, '
')">
|
||||
<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, '
')">
|
||||
<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, '
')"/>
|
||||
<xsl:variable name="rest" select="substring-after($text, '
')"/>
|
||||
<xsl:choose>
|
||||
<xsl:when test="substring($line, $b) = '' and not($rest = '')">
|
||||
<xsl:if test="not($is_first_line = '1')">
|
||||
<xsl:text>
</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>
</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, '
')"/>
|
||||
<xsl:variable name="rest" select="substring-after($text, '
')"/>
|
||||
<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) <= $trim_count)">
|
||||
</xsl:when>
|
||||
<xsl:when test="($strip = '1') and
|
||||
(string-length($rest) <= $trim_count)">
|
||||
<xsl:value-of select="$stripped_line"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:value-of select="$stripped_line"/>
|
||||
<xsl:text>
</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>
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -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-<Plug>.) 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>&l:</code> instead of
|
||||
<code>:set</code> and <code>&</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 <leader>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 don’t 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>
|
||||
|
|
@ -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). 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. 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. 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. 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. 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. 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> <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. 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. Try to get wide review of your format, from outside your organization as well, if possible. [<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. 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. 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. [<i>Rationale:</i> 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. [<i>Rationale: </i>Consistency.]<br></li></ol><br><h2>2. Schemas</h2><ol><li>Document formats SHOULD be expressed using a schema language. [<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>. Embedded <a title="Schematron" href="http://www.schematron.com/" id="ymh-">Schematron</a> rules MAY be added to the schema for additional fine control. [<i>Rationale:</i>
|
||||
|
||||
RELAX NG is the most flexible schema language, with very few arbitrary
|
||||
restrictions on designs. 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. Schematron handles arbitrary cross-element and
|
||||
cross-attribute constraints nicely.]<br><br></li><li>Schemas SHOULD use the <a title=""Salami Slice" style" href="http://www.xfront.com/GlobalVersusLocal.html#SecondDesign" id="r:fj">"Salami Slice" style</a> (one rule per element). Schemas MAY use the <a title=""Russian Doll" style" href="http://www.xfront.com/GlobalVersusLocal.html#FirstDesign" id="h14y">"Russian Doll" style</a> (schema resembles document) if they are short and simple. The <a title=""Venetian Blind" 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. [<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.
|
||||
|
||||
A default namespace SHOULD be used. [<i>Rationale:</i> Namespace-free
|
||||
documents are obsolete; every set of names should be in some
|
||||
namespace. 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. [<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. 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. There may be additional URI-path parts
|
||||
before the <i>year.</i> [<i>Rationale:</i> Existing convention. 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. [<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). Single-letter prefixes MUST NOT be used. Prefixes SHOULD contain only lower-case ASCII letters. [<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. 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.
|
||||
[<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. If a name can only remain within this limit by becoming obscure, the limit SHOULD be ignored. [<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. Acronyms MUST be treated as words for camel-casing purposes: informationUri, not informationURI. [<i>Rationale:</i> 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. Mixed content MUST NOT be used. [<i>Rationale:</i> Many XML data models don't handle mixed content properly, and its use makes the element order-dependent. 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. [<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. [<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). Instead, use child elements to
|
||||
encapsulate closely related attributes. [<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. [<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. [<i>Rationale:</i> 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. 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. If required in particular cases, <span style="font-family: Courier New;">xsd:integer</span> (unlimited-precision integer) values MAY also be used. [<i>Rationale:</i> There are far too many numeric types in XML Schema: these provide a reasonable subset.] <br><br></li><li>
|
||||
|
||||
Boolean values SHOULD NOT be used (use enumerations instead). 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>. 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. [<i>Rationale:</i> Boolean arguments are not extensible. 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. UTC times SHOULD be used rather than local times.
|
||||
|
||||
[<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. Syntax in values means XML tools are largely useless. Syntaxes such as dates, URIs, and
|
||||
XPath expressions are exceptions. [<i>Rationale:</i>
|
||||
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. XML parsers don't strip whitespace in elements, but do convert newlines to spaces in attributes. However, application frameworks may do more aggressive whitespace stripping. 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. 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. [<i>Rationale:</i>
|
||||
|
||||
Simplicity and design consistency. 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).
|
||||
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. 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. [<i>Rationale:</i> XML does not allow arbitrary binary bytes.]<br><br></li><li>
|
||||
|
||||
The line breaks required by Base64 MAY be omitted. [<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. [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. Existing standardized processing instructions MAY be used. [<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> </p>
|
||||
|
||||
<p>
|
||||
</p><p> </p><h2>11. Representation of XML document instances<br></h2><p><b>Note:</b> 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). <i>In no case</i> should XML parsers rely on these guidelines being followed. Use standard XML parsers, not hand-rolled hacks.<br></p><p><br></p><ol><li>The character encoding used SHOULD be UTF-8. Exceptions should require extremely compelling circumstances. [<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. [<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. [<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. [<i>Rationale:</i> Human readability.]<br><br></li><li>Redundant whitespace in a tag SHOULD NOT be
|
||||
used. 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. [<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. [<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. Elements that contain character content SHOULD NOT be
|
||||
wrapped. Long start-tags MAY be broken using newlines (possibly with extra indentation) after any attribute value except the last. [<i>Rationale:</i> General compatibility with our style. 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. <span style="font-family: Courier New;">&apos;</span> and <span style="font-family: Courier New;">&quot;</span> may be freely used to escape each type of quote. [<i>Rationale:</i> No XML parsers report the distinction.]<br><br>
|
||||
|
||||
</li><li>Comments MUST NOT be used to carry real data. Comments MAY be used to contain TODOs in hand-written XML. Comments SHOULD NOT be used at all in publicly transmitted documents. [<i>Rationale: </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. If pretty-printing is required, pretty-print
|
||||
comments like elements, but with line wrapping. Comments SHOULD NOT
|
||||
appear in elements that contain character content. [<i>Rationale: </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;"><!--</span> and preceding <span style="font-family: Courier New;">--></span>. [<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;</span> and <span style="font-family: Courier New;">&lt;</span>. Specifications MUST NOT require or forbid the use of CDATA sections. [<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;</span>, <span style="font-family: Courier New;">&lt;</span>, <span style="font-family: Courier New;">&gt;</span>, <span style="font-family: Courier New;">&quot;</span>, and <span style="font-family: Courier New;">&apos;</span> MUST NOT be used. Character references MAY be used, but actual characters are preferred, unless the character encoding is not UTF-8. As usual, textual formats are exempt from this rule.<br></li></ol>
|
||||
|
||||
<br><p> </p><p>
|
||||
</p>
|
||||
<p>
|
||||
</p><br><br><h2>
|
||||
12. Elements vs. Attributes
|
||||
</h2>
|
||||
<p>
|
||||
<b>Note:</b> There are no hard and fast rules for deciding when to use attributes and when to use elements. 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. 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. Beware of using ease of processing as a criterion. 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. (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. 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. 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. 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. 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. 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, 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. 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. 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>. Design for extensibility. You <i>are</i> gonna need it. [<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. 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. 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>
|
||||
"Elements or attributes?
|
||||
</p>
|
||||
<p>
|
||||
Which will serve me best?"
|
||||
</p>
|
||||
<p>
|
||||
Those who know roar like lions;
|
||||
</p>
|
||||
<p>
|
||||
Wise hackers smile like tigers.
|
||||
</p>
|
||||
<p>
|
||||
--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>
|
||||
Loading…
Reference in New Issue