brl/gnome-shell
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Use Markdown

Browse Source 
Markdown produces nicer output where supported, so use that instead
of plain ASCII formatting.
This commit is contained in:
Florian Müllner 2018-05-23 17:55:43 +02:00
parent f56e4e177e
commit 02bbf409ea
7 changed files with 97 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
HACKING → HACKING.md
View File

@ -1,19 +1,16 @@
Coding guide # Coding guide
============
Our goal is to have all JavaScript code in GNOME follow a consistent style. In Our goal is to have all JavaScript code in GNOME follow a consistent style. In
a dynamic language like JavaScript, it is essential to be rigorous about style a dynamic language like JavaScript, it is essential to be rigorous about style
(and unit tests), or you rapidly end up with a spaghetti-code mess. (and unit tests), or you rapidly end up with a spaghetti-code mess.
A quick note ## A quick note
------------
Life isn't fun if you can't break the rules. If a rule seems unnecessarily Life isn't fun if you can't break the rules. If a rule seems unnecessarily
restrictive while you're coding, ignore it, and let the patch reviewer decide restrictive while you're coding, ignore it, and let the patch reviewer decide
what to do. what to do.
Indentation and whitespace ## Indentation and whitespace
--------------------------
Use four-space indents. Braces are on the same line as their associated Use four-space indents. Braces are on the same line as their associated
statements. You should only omit braces if *both* sides of the statement are statements. You should only omit braces if *both* sides of the statement are
@ -22,7 +19,7 @@ on one line.
* One space after the `function` keyword. No space between the function name * One space after the `function` keyword. No space between the function name
* in a declaration or a call. One space before the parens in the `if` * in a declaration or a call. One space before the parens in the `if`
* statements, or `while`, or `for` loops. * statements, or `while`, or `for` loops.
```javascript
function foo(a, b) { function foo(a, b) {
let bar; let bar;
@ -39,22 +36,20 @@ on one line.
print(20); print(20);
} }
} }
```
Semicolons ## Semicolons
----------
JavaScript allows omitting semicolons at the end of lines, but don't. Always JavaScript allows omitting semicolons at the end of lines, but don't. Always
end statements with a semicolon. end statements with a semicolon.
js2-mode ## js2-mode
--------
If using Emacs, do not use js2-mode. It is outdated and hasn't worked for a If using Emacs, do not use js2-mode. It is outdated and hasn't worked for a
while. emacs now has a built-in JavaScript mode, js-mode, based on while. emacs now has a built-in JavaScript mode, js-mode, based on
espresso-mode. It is the de facto emacs mode for JavaScript. espresso-mode. It is the de facto emacs mode for JavaScript.
File naming and creation ## File naming and creation
------------------------
For JavaScript files, use lowerCamelCase-style names, with a `.js` extension. For JavaScript files, use lowerCamelCase-style names, with a `.js` extension.
@ -67,14 +62,13 @@ library name followed by a dash, e.g. `shell-app-system.c`. Create a
`-private.h` header when you want to share code internally in the `-private.h` header when you want to share code internally in the
library. These headers are not installed, distributed or introspected. library. These headers are not installed, distributed or introspected.
Imports ## Imports
-------
Use UpperCamelCase when importing modules to distinguish them from ordinary Use UpperCamelCase when importing modules to distinguish them from ordinary
variables, e.g. variables, e.g.
```javascript
const GLib = imports.gi.GLib; const GLib = imports.gi.GLib;
```
Imports should be categorized into one of two places. The top-most import block Imports should be categorized into one of two places. The top-most import block
should contain only "environment imports". These are either modules from should contain only "environment imports". These are either modules from
gobject-introspection or modules added by gjs itself. gobject-introspection or modules added by gjs itself.
@ -85,7 +79,7 @@ e.g. `imports.ui.popupMenu`.
Each import block should be sorted alphabetically. Don't import modules you Each import block should be sorted alphabetically. Don't import modules you
don't use. don't use.
```javascript
const GLib = imports.gi.GLib; const GLib = imports.gi.GLib;
const Gio = imports.gi.Gio; const Gio = imports.gi.Gio;
const Lang = imports.lang; const Lang = imports.lang;
@ -95,23 +89,22 @@ don't use.
const Params = imports.misc.params; const Params = imports.misc.params;
const Tweener = imports.ui.tweener; const Tweener = imports.ui.tweener;
const Util = imports.misc.util; const Util = imports.misc.util;
```
The alphabetical ordering should be done independently of the location of the The alphabetical ordering should be done independently of the location of the
location. Never reference `imports` in actual code. location. Never reference `imports` in actual code.
Constants ## Constants
---------
We use CONSTANTS_CASE to define constants. All constants should be directly We use CONSTANTS_CASE to define constants. All constants should be directly
under the imports: under the imports:
```javascript
const MY_DBUS_INTERFACE = 'org.my.Interface'; const MY_DBUS_INTERFACE = 'org.my.Interface';
```
Variable declaration ## Variable declaration
--------------------
Always use either `const` or `let` when defining a variable. Always use either `const` or `let` when defining a variable.
```javascript
// Iterating over an array // Iterating over an array
for (let i = 0; i < arr.length; ++i) { for (let i = 0; i < arr.length; ++i) {
let item = arr[i]; let item = arr[i];
@ -121,17 +114,17 @@ Always use either `const` or `let` when defining a variable.
for (let prop in someobj) { for (let prop in someobj) {
... ...
} }
```
If you use "var" then the variable is added to function scope, not block scope. If you use "var" then the variable is added to function scope, not block scope.
See [What's new in JavaScript 1.7](https://developer.mozilla.org/en/JavaScript/New_in_JavaScript/1.7#Block_scope_with_let_%28Merge_into_let_Statement%29) See [What's new in JavaScript 1.7](https://developer.mozilla.org/en/JavaScript/New_in_JavaScript/1.7#Block_scope_with_let_%28Merge_into_let_Statement%29)
Classes ## Classes
-------
There are many approaches to classes in JavaScript. We use our own class framework There are many approaches to classes in JavaScript. We use our own class framework
(sigh), which is built in gjs. The advantage is that it supports inheriting from (sigh), which is built in gjs. The advantage is that it supports inheriting from
GObjects, although this feature isn't used very often in the Shell itself. GObjects, although this feature isn't used very often in the Shell itself.
```javascript
var IconLabelMenuItem = new Lang.Class({ var IconLabelMenuItem = new Lang.Class({
Name: 'IconLabelMenuItem', Name: 'IconLabelMenuItem',
Extends: PopupMenu.PopupMenuBaseItem, Extends: PopupMenu.PopupMenuBaseItem,
@ -146,6 +139,7 @@ GObjects, although this feature isn't used very often in the Shell itself.
log("menu opened!"); log("menu opened!");
} }
}); });
```
* 'Name' is required. 'Extends' is optional. If you leave it out, you will * 'Name' is required. 'Extends' is optional. If you leave it out, you will
automatically inherit from Object. automatically inherit from Object.
@ -162,13 +156,12 @@ GObjects, although this feature isn't used very often in the Shell itself.
still a giant function call, even though it may resemble a more still a giant function call, even though it may resemble a more
conventional syntax. conventional syntax.
GObject Introspection ## GObject Introspection
---------------------
GObject Introspection is a powerful feature that allows us to have native GObject Introspection is a powerful feature that allows us to have native
bindings for almost any library built around GObject. If a library requires bindings for almost any library built around GObject. If a library requires
you to inherit from a type to use it, you can do so: you to inherit from a type to use it, you can do so:
```javascript
var MyClutterActor = new Lang.Class({ var MyClutterActor = new Lang.Class({
Name: 'MyClutterActor', Name: 'MyClutterActor',
Extends: Clutter.Actor, Extends: Clutter.Actor,
@ -188,9 +181,9 @@ you to inherit from a type to use it, you can do so:
alloc.x2, alloc.y2); alloc.x2, alloc.y2);
} }
}); });
```
Translatable strings, `environment.js` ## Translatable strings, `environment.js`
--------------------------------------
We use gettext to translate the GNOME Shell into all the languages that GNOME We use gettext to translate the GNOME Shell into all the languages that GNOME
supports. The `gettext` function is aliased globally as `_`, you do not need to supports. The `gettext` function is aliased globally as `_`, you do not need to
@ -204,8 +197,7 @@ and "double quotes" for strings that the user may see. This allows us to
quickly find untranslated or mistranslated strings by grepping through the quickly find untranslated or mistranslated strings by grepping through the
sources for double quotes without a gettext call around them. sources for double quotes without a gettext call around them.
`actor` and `_delegate` ## `actor` and `_delegate`
-----------------------
gjs allows us to set so-called "expando properties" on introspected objects, gjs allows us to set so-called "expando properties" on introspected objects,
allowing us to treat them like any other. Because the Shell was built before allowing us to treat them like any other. Because the Shell was built before
@ -214,7 +206,7 @@ that has a property called `actor`. We call this wrapper class the "delegate".
We sometimes use expando properties to set a property called `_delegate` on We sometimes use expando properties to set a property called `_delegate` on
the actor itself: the actor itself:
```javascript
var MyClass = new Lang.Class({ var MyClass = new Lang.Class({
Name: 'MyClass', Name: 'MyClass',
@ -229,6 +221,7 @@ the actor itself:
actor.set_label("You clicked the button!"); actor.set_label("You clicked the button!");
} }
}); });
```
The 'delegate' property is important for anything which trying to get the The 'delegate' property is important for anything which trying to get the
delegate object from an associated actor. For instance, the drag and drop delegate object from an associated actor. For instance, the drag and drop
@ -236,16 +229,14 @@ system calls the `handleDragOver` function on the delegate of a "drop target"
when the user drags an item over it. If you do not set the `_delegate` when the user drags an item over it. If you do not set the `_delegate`
property, your actor will not be able to be dropped onto. property, your actor will not be able to be dropped onto.
Functional style ## Functional style
----------------
JavaScript Array objects offer a lot of common functional programming JavaScript Array objects offer a lot of common functional programming
capabilities such as forEach, map, filter and so on. You can use these when capabilities such as forEach, map, filter and so on. You can use these when
they make sense, but please don't have a spaghetti mess of function programming they make sense, but please don't have a spaghetti mess of function programming
messed in a procedural style. Use your best judgment. messed in a procedural style. Use your best judgment.
Closures ## Closures
--------
`this` will not be captured in a closure, it is relative to how the closure is `this` will not be captured in a closure, it is relative to how the closure is
invoked, not to the value of this where the closure is created, because "this" invoked, not to the value of this where the closure is created, because "this"
@ -254,15 +245,16 @@ variable that can be captured in closures.
All closures should be wrapped with Function.prototype.bind or use arrow All closures should be wrapped with Function.prototype.bind or use arrow
notation. notation.
```javascript
const Lang = imports.lang; const Lang = imports.lang;
let closure1 = () => { this._fnorbate(); }; let closure1 = () => { this._fnorbate(); };
let closure2 = this._fnorbate.bind(this); let closure2 = this._fnorbate.bind(this);
```
A more realistic example would be connecting to a signal on a method of a A more realistic example would be connecting to a signal on a method of a
prototype: prototype:
```javascript
const Lang = imports.lang; const Lang = imports.lang;
const FnorbLib = imports.fborbLib; const FnorbLib = imports.fborbLib;
@ -276,19 +268,21 @@ prototype:
this._updateFnorb(); this._updateFnorb();
} }
}); });
```
Object literal syntax ## Object literal syntax
---------------------
In JavaScript, these are equivalent: In JavaScript, these are equivalent:
```javascript
foo = { 'bar': 42 }; foo = { 'bar': 42 };
foo = { bar: 42 }; foo = { bar: 42 };
```
and so are these: and so are these:
```javascript
var b = foo['bar']; var b = foo['bar'];
var b = foo.bar; var b = foo.bar;
```
If your usage of an object is like an object, then you're defining "member If your usage of an object is like an object, then you're defining "member
variables." For member variables, use the no-quotes no-brackets syntax: `{ bar: variables." For member variables, use the no-quotes no-brackets syntax: `{ bar:
@ -298,14 +292,13 @@ If your usage of an object is like a hash table (and thus conceptually the keys
can have special chars in them), don't use quotes, but use brackets: `{ bar: 42 can have special chars in them), don't use quotes, but use brackets: `{ bar: 42
}`, `foo['bar']`. }`, `foo['bar']`.
Getters, setters, and Tweener ## Getters, setters, and Tweener
-----------------------------
Getters and setters should be used when you are dealing with an API that is Getters and setters should be used when you are dealing with an API that is
designed around setting properties, like Tweener. If you want to animate an designed around setting properties, like Tweener. If you want to animate an
arbitrary property, create a getter and setter, and use Tweener to animate the arbitrary property, create a getter and setter, and use Tweener to animate the
property. property.
```javascript
var ANIMATION_TIME = 2000; var ANIMATION_TIME = 2000;
var MyClass = new Lang.Class({ var MyClass = new Lang.Class({
@ -331,3 +324,4 @@ property.
{ position: 100, { position: 100,
time: ANIMATION_TIME, time: ANIMATION_TIME,
transition: 'easeOutQuad' }); transition: 'easeOutQuad' });
```

16
README → README.md
View File

@ -1,3 +1,4 @@
# GNOME Shell
GNOME Shell provides core user interface functions for the GNOME 3 desktop, GNOME Shell provides core user interface functions for the GNOME 3 desktop,
like switching to windows and launching applications. GNOME Shell takes like switching to windows and launching applications. GNOME Shell takes
advantage of the capabilities of modern graphics hardware and introduces advantage of the capabilities of modern graphics hardware and introduces
@ -6,15 +7,14 @@ easy to use experience.
For more information about GNOME Shell, including instructions on how For more information about GNOME Shell, including instructions on how
to build GNOME Shell from source and how to get involved with the project, to build GNOME Shell from source and how to get involved with the project,
see: see the [project wiki][wiki]
https://wiki.gnome.org/Projects/GnomeShell Bugs should be reported to the GNOME [bug tracking system][bug-tracker].
Bugs should be reported at http://bugzilla.gnome.org against the 'gnome-shell' ## License
product.
License
=======
GNOME Shell is distributed under the terms of the GNU General Public License, GNOME Shell is distributed under the terms of the GNU General Public License,
version 2 or later. See the COPYING file for details. version 2 or later. See the [COPYING][license] file for details.
[project-wiki]: https://wiki.gnome.org/Projects/GnomeShell
[bug-tracker]: https://gitlab.gnome.org/GNOME/gnome-shell/issues
[license]: COPYING

8
browser-plugin/README → browser-plugin/README.md
View File

@ -4,14 +4,14 @@ the extensions repository to provide good integration, letting the website
know which extensions are enabled and disabled, and allowing the website to know which extensions are enabled and disabled, and allowing the website to
enable, disable and install them. enable, disable and install them.
Bugs should be reported at http://bugzilla.gnome.org against the 'gnome-shell' Bugs should be reported to the GNOME [bug tracking system][bug-tracker].
product.
License ## License
=======
The GNOME Shell Browser Plugin, like GNOME Shell itself is distributed under The GNOME Shell Browser Plugin, like GNOME Shell itself is distributed under
the GNU General Public License, version 2 or later. The plugin also contains the GNU General Public License, version 2 or later. The plugin also contains
header files from the "NPAPI SDK" project, tri-licensed under MPL 1.1, GPL 2.0 header files from the "NPAPI SDK" project, tri-licensed under MPL 1.1, GPL 2.0
and LGPL 2.1. These headers are third-party sources and can be retrieved from: and LGPL 2.1. These headers are third-party sources and can be retrieved from:
http://code.google.com/p/npapi-sdk/ http://code.google.com/p/npapi-sdk/
[bug-tracker]: https://gitlab.gnome.org/GNOME/gnome-shell/issues

31
data/theme/README
View File

@ -1,31 +0,0 @@
Summary
-------
* Do not edit the CSS directly, edit the source SCSS files and the CSS files will be generated
automatically when building with meson + ninja and left inside the build directory to be
incorporated into the gresource XML (you'll need to have sassc installed).
How to tweak the theme
----------------------
Adwaita is a complex theme, so to keep it maintainable it's written and processed in SASS, the
generated CSS is then transformed into a gresource file during gtk build and used at runtime in a
non-legible or editable form.
It is very likely your change will happen in the _common.scss file. That's where all the widget
selectors are defined. Here's a rundown of the "supporting" stylesheets, that are unlikely to be the
right place for a drive by stylesheet fix:
_colors.scss - global color definitions. We keep the number of defined colors to a necessary minimum,
most colors are derived from a handful of basics. It is an exact copy of the gtk+
counterpart. Light theme is used for the classic theme and dark is for GNOME3 shell
default.
_drawing.scss - drawing helper mixings/functions to allow easier definition of widget drawing under
specific context. This is why Adwaita isn't 15000 LOC.
_common.scss - actual definitions of style for each widget. This is where you are likely to add/remove
your changes.
You can read about SASS at http://sass-lang.com/documentation/. Once you make your changes to the
_common.scss file, you can run ninja to generate the final CSS files.

32
data/theme/README.md Normal file
View File

@ -0,0 +1,32 @@
## Summary
Do not edit the CSS directly, edit the source SCSS files and the CSS files
will be generated automatically when building with meson + ninja and left
inside the build directory to be incorporated into the gresource XML (you'll
need to have sassc installed).
## How to tweak the theme
Adwaita is a complex theme, so to keep it maintainable it's written and
processed in SASS, the generated CSS is then transformed into a gresource
file during gtk build and used at runtime in a non-legible or editable form.
It is very likely your change will happen in the [_common.scss][common] file.
That's where all the widget selectors are defined. Here's a rundown of
the "supporting" stylesheets, that are unlikely to be the right place
for a drive by stylesheet fix:
| File | Description |
| ------------------------ | ----------------- |
| [_colors.scss][colors] | global color definitions. We keep the number of defined colors to a necessary minimum, most colors are derived from a handful of basics. It is an exact copy of the gtk+ counterpart. Light theme is used for the classic theme and dark is for GNOME3 shell default. |
| [_drawing.scss][drawing] | drawing helper mixings/functions to allow easier definition of widget drawing under specific context. This is why Adwaita isn't 15000 LOC. |
| [_common.scss][common] | actual definitions of style for each widget. This is where you are likely to add/remove your changes. |
You can read about SASS on its [web page][sass-web]. Once you make your
changes to the [_common.scss][common] file, you can run ninja to generate the
final CSS files.
[common]: data/theme/gnome-shell-sass/_common.scss
[colors]: data/theme/gnome-shell-sass/_colors.scss
[drawing]: data/theme/gnome-shell-sass/_drawing.scss
[sass-web]: http://sass-lang.com/documentation/

7
data/theme/gnome-shell-sass/README
View File

@ -1,7 +0,0 @@
GNOME Shell Sass is a project intended to allow the sharing of the theme sources in sass between gnome-shell and other projects like gnome-shell-extensions.
License
=======
GNOME Shell Sass is distributed under the terms of the GNU General Public License,
version 2 or later. See the COPYING file for details.

10
data/theme/gnome-shell-sass/README.md Normal file
View File

@ -0,0 +1,10 @@
# GNOME Shell Sass
GNOME Shell Sass is a project intended to allow the sharing of the
theme sources in sass between gnome-shell and other projects like
gnome-shell-extensions.
## License
GNOME Shell Sass is distributed under the terms of the GNU General Public
License, version 2 or later. See the [COPYING][license] file for details.
[license]: COPYING