Commit 3f98ba62 authored by Sebastien Bacher's avatar Sebastien Bacher
Browse files

New upstream version 3.34.0

parents 6fa33de9 0d36c5da
The GNOME contributing guidelines require patches to be forwarded to GNOME's
Bugzilla instance hosted at https://bugzilla.gnome.org. Please do not open
GitHub pull requests against this module as they will be ignored. More
information is available at the following wiki page:
How to contribute to gedit
==========================
https://wiki.gnome.org/Sysadmin/GitHub
gedit development relies on voluntary contributions and everyone is invited to
help.
To know how to contribute, read the README and HACKING files.
If you are interested in helping us to improve gedit, please contact the
developers on IRC and/or send a message to the gedit mailing list and offer your
help. See the “Getting in Touch” section on the
[gedit wiki page](https://wiki.gnome.org/Apps/Gedit).
Contributions other than software development
---------------------------------------------
See the [GNOME wiki](https://wiki.gnome.org/).
Doing **bug triaging** on the bug tracker is a very useful task for gedit,
because gedit is used by many people and there are therefore lots of bug reports
or feature requests. The gedit developers often have difficulties to triage all
the bugs and do first line support. Having a curated list of important bugs to
fix would tremendously help the gedit developers.
Software development
--------------------
To get started with gedit software development, see the file
[docs/gedit-development-getting-started.md](docs/gedit-development-getting-started.md).
gedit follows the same guidelines and code conventions as GtkSourceView. See
the [GtkSourceView HACKING file](https://gitlab.gnome.org/GNOME/gtksourceview/blob/master/HACKING).
The gedit and gedit-plugins Git repositories are hosted on the GNOME GitLab
instance:
- [gedit on GitLab](https://gitlab.gnome.org/GNOME/gedit)
- [gedit-plugins on GitLab](https://gitlab.gnome.org/GNOME/gedit-plugins)
Source code repository
======================
gedit source code is maintained using the git version control system
and is available at the following location:
git://git.gnome.org/gedit
Or if you have an account on GNOME servers:
ssh://USERNAME@git.gnome.org/git/gedit
A web interface is available at:
https://git.gnome.org/browse/gedit
Building from git
=================
When building from a git checkout you will need to run the
autogen.sh script which takes care of running automake, autoconf,
etc and then run "configure" for you. You can pass options like
--prefix to autogen.sh and they will be forwarded to the configure
script.
Note that you cannot run gedit from its build directory: you need
to install it with "make install". For this reason it is highly
recommended that you install in a separate prefix instead of
overwriting your system binaries. Note however that when running
gedit from a custom prefix you will need to set many environment
variables accordingly, for instance PATH and XDG_DATA_DIR.
The JHBuild tool can take care of all this for you.
Commit guidelines
=================
Please don't commit directly to the git repository unless
you have been given the green light to commit freely to gedit.
When in doubt assume you haven't ;-).
Please attach patches in bugzilla (http://bugzilla.gnome.org).
If the patch fixes a bug that is not reported yet in bugzilla or is
an enhancement, create a new bugreport.
Please create patches with the git format-patch command.
If you are a translator feel free to mark strings for translation,
fix typos in the code, etc.
Please send patches for build & configure fixes too. I really appreciate
your help, I just want to review these fixes before applying.
If you are a "build sheriff", feel free to commit fixes for build and
configure (please, send me an e-mail with the patch you have applied).
When committing to the gedit git repository make sure to include a
meaningful commit message. Changes without a sufficient commit message
will be reverted. Commit messages should have the following format:
=== begin example commit ===
Short explanation of the commit
Longer explanation explaining exactly what's changed, whether any
external or private interfaces changed, what bugs were fixed (with bug
tracker reference if applicable) and so forth. Be concise but not too brief.
=== end example commit ===
- Always add a brief description of the commit to the _first_ line of
the commit and terminate by two newlines (it will work without the
second newline, but that is not nice for the interfaces).
- First line (the brief description) must only be one sentence and
should start with a capital letter unless it starts with a lowercase
symbol or identifier. Don't use a trailing period either. Don't exceed
72 characters.
- The main description (the body) is normal prose and should use normal
punctuation and capital letters where appropriate. Normally, for patches
sent to a mailing list it's copied from there.
- When committing code on behalf of others use the --author option, e.g.
git commit -a --author "Joe Coder <joe@coder.org>" and --signoff.
Code conventions
================
You may encounter old code that doesn't follow all the following code
conventions, but for new code it is better to follow them, for consistency.
- Avoid trailing whitespace.
- Indent the C code with tabulations with a width of eight characters.
- The files should have a modeline for the indentation style.
- All blocks should be surrounded by curly braces, even one-line blocks. It
spaces out the code, and it is more convenient when some code must be added
or removed without the need to add or remove the curly braces.
- Follow the C89 standard. In particular, no "//"-style comments.
- As a general rule of thumb, follow the same coding style as the surrounding
code.
- Do not be cheap about blank lines, spacing the code vertically help
readability. However never use two consecutive blank lines, there is really
no need.
Programming best practices
==========================
gedit is a pretty big piece of software, developed over the years by different
people and GNOME technologies. Some parts of the code may be a little old. So
when editing the code, we should try to make it better, not worse.
Here are some general advices.
- Simplicity: the simpler code the better. Any trick that seem smart when you
write it is going to bite your ass later when reading the code. Given that
you spend 90% of the time staring at the code and 10% writing it, making
reading the code harder is a net loss.
- Brevity: make an effort to refactor common code into utility functions and
use library function whenever is possible: every time you cut and paste a
line of code you are throwing away all the precious seconds of your life
that you will later spend trying to figure out the differences among the two
copies that will have surely diverged.
- Code for change: code is bound to contain bugs no matter how well it is
written. A good coding style allows to fix these bugs with minimal changes
instead of reformatting a whole section of unrelated code, this is
especially important to make patch review easier and to easily understand
the commit history. Some practical examples are:
- Factor code into self contained functions so that changing a function
does not require to change all the callers.
- Do not align variable declaration, "case" statements etc, since this
will inevitably mean that when a line will change you'll have to
reformat all the surrounding ones.
- Declare variables in the strictest scope as possible.
- Reorder functions so that you do not need prototypes for static
functions so that when you change them you need to change them only in
one place.
- Self documentation and code comments: use code comments parsimoniously. Code
should be written so that it is clear and evident without the need of
comments. Besides, comments usually get outdated when the code is changed
and they become misleading. In particular avoid stating the obvious e.g. "a
= 1; /* assign 1 to a */". Use good function names and variables to make the
code self-documented.
A good function name is one that explain clearly all what its code really
does. There shouldn't be hidden features. If you can not find easily a good
function name, you should probably split the function in smaller pieces. A
function should do only one thing, but do it well.
Please avoid lots of one-letter variables. And a variable should be used for
only one purpose.
Self-documentation is obviously not always possible, so when a comment is
needed, it is needed. In those cases make sure to explain why and not only
how a specific thing is done: you can deduce the "how" from the code, but
not the "why". Public library functions should always be documented and in
particular should include the calling conventions, e.g. if the result should
be freed by the caller.
Do not use fancy frames around comments like a line full of
/*---------------*/ etc.
- Contribute below on the stack. Fix a problem at the right place, instead of
writing hacks to work around a bug or a lack of feature in an underlying
library.
See also
========
https://wiki.gnome.org/Apps/Gedit/DevGettingStarted
https://developer.gnome.org/programming-guidelines/stable/
https://wiki.gnome.org/Projects/GTK%2B/BestPractices
http://ometer.com/hacking.html
http://blogs.gnome.org/swilmet/2012/08/01/about-code-quality-and-maintainability/
Thanks,
The gedit team.
Paolo Borelli
E-mail: pborelli@gnome.org
Userid: pborelli
Jesse van den Kieboom
E-mail: jessevdk@gnome.org
Userid: jessevdk
Ignacio Casal Quinteiro
E-mail: icq@gnome.org
Userid: icq
News in 3.34.0, 2019-09-09
--------------------------
* Translation updates.
News in 3.33.92, 2019-09-03
---------------------------
* Documentation:
- Overhaul README.md and CONTRIBUTING.md (renamed from HACKING).
- Write several documents in Markdown in the docs/ directory:
- gedit development - getting started
- gedit installation by building the source code
- a new roadmap
(Sébastien Wilmet)
* Updates to the Snap and Flatpak packages (Ken VanDine, Martin Blanchard)
* Translation updates.
=============
gedit 3.33.90
=============
......
General Information
===================
gedit - The GNOME text editor
=============================
This is version 3.33.90 of gedit. gedit is a small and lightweight UTF-8 text
editor for the GNOME environment.
This is version 3.34.0 of gedit.
gedit is part of GNOME and uses the latest GTK+ and GNOME libraries.
Complete GNOME integration is featured, with support for Drag and Drop (DnD)
from Nautilus (the GNOME file manager), the use of the GNOME help system,
the Virtual File System GVfs and the GTK+ print framework.
gedit is the official text editor of the GNOME desktop environment.
While aiming at simplicity and ease of use, gedit is a powerful general
purpose text editor.
gedit uses a Multiple Document Interface (MDI), which lets you edit more than
one document at the same time.
Whether you are writing the next bestseller, programming an innovative
application, or simply taking some quick notes, gedit will be a reliable
tool to accomplish your task.
gedit supports most standard editing features, plus several not found in your
average text editor (plugins being the most notable of these).
Its flexible plugin system allows you to tailor the application to your
needs and adapt it to your workflow.
The gedit core is written in the C language. Thanks to GObject introspection,
plugins may also be written in other languages, like Vala and Python.
Although new features are always under development, currently gedit has:
* Complete support for UTF-8 text
* Syntax highlighting
* Support for editing remote files
* Search and replace
* Printing and Print Previewing Support
* File Revert
* A complete preferences interface
* Configurable Plugin system, with optional python support
Some of the plugins, packaged and installed with gedit include, among others:
* Word count
* Spell checker
* File Browser
* Automatic snippet expansion
* Sort
* Insert Date/Time
* External Tools
* Tag list
Other external plugins are also available.
See the [gedit official website](https://wiki.gnome.org/Apps/Gedit) for
more information.
License
-------
gedit is released under the GNU General Public License (GPL) version 2 or
later, see the file 'COPYING' for more information.
later, see the file [COPYING](COPYING) for more information.
Resources
=========
Dependencies
------------
* [Official web site](https://wiki.gnome.org/Apps/Gedit)
* [Latest gedit tarball](https://download.gnome.org/sources/gedit/)
* [Information about gedit mailing lists](https://mail.gnome.org/mailman/listinfo/gedit-list)
gedit uses the GTK GUI toolkit.
For a complete list of dependencies, see the file [meson.build](meson.build) and
search the section “Dependencies”.
Installation
============
------------
gedit requires `GTK+ >= 3.22.0`, `GtkSourceView >= 4.0.2` and
`libpeas >= 1.14.1` libraries. It also has a run-time dependency on an
icon theme for its icons. If gedit fails to display icons, installing
GNOME's default adwaita-icon-theme is a simple way of providing them.
`PyGObject 3.0.x` and `gobject-introspection 1.42.0` are required to enable
python plugins support.
`gspell >= 0.2.5` is required to enable the spell checking plugin.
Simple install procedure:
```
% tar Jxf gedit-3.33.90.tar.xz # unpack the sources
% cd gedit-3.33.90 # change to the toplevel directory
% meson _build # run the `configure' script
% ninja -C _build # build gedit
[ Become root if necessary ]
% ninja -C _build install # install gedit
```
To build gedit from source, see the [docs/build.md](docs/build.md) file.
How to report bugs
==================
Bugs should be reported to the [GNOME bug tracking system](https://wiki.gnome.org/Apps/Gedit/ReportingBugs).
------------------
Please read
[the wiki page on how to report bugs](https://wiki.gnome.org/Apps/Gedit/ReportingBugs),
it contains a list of frequently reported bugs and a link to the bug
tracker.
Contributions
=============
To contribute changes to the project, please fork the project on [the GNOME gitlab instance](https://gitlab.gnome.org/GNOME/gedit) and open a merge request.
If the change fixes an existing bug, add the issue number in the merge request comment.
See the file 'HACKING' for more detailed information.
-------------
gedit development relies on voluntary contributions and everyone is invited
to help.
The gedit team.
See the file [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
......@@ -40,40 +40,58 @@
"modules" : [
{
"name" : "libpeas",
"buildsystem": "meson",
"buildsystem" : "meson",
"cleanup" : [
"/bin/*",
"/lib/peas-demo"
"/bin/*"
],
"config-opts" : [
"-Ddemos=false",
"-Dvapi=true",
"-Dgtk_doc=false"
],
"sources" : [
{
"type" : "git",
"url" : "https://gitlab.gnome.org/GNOME/libpeas.git"
"type" : "archive",
"url" : "https://download.gnome.org/sources/libpeas/1.23/libpeas-1.23.90.1.tar.xz",
"sha256" : "210d2a44a25934f4f4d359cf54faaff03c2cf6c7fd358ae9da89fba2bca0a2f3"
}
]
},
{
"name" : "gtksourceview",
"buildsystem": "meson",
"buildsystem" : "meson",
"config-opts" : [
"-Dvapi=true",
"-Dgtk_doc=false"
],
"sources" : [
{
"type" : "git",
"url" : "https://gitlab.gnome.org/GNOME/gtksourceview.git"
"type" : "archive",
"url" : "https://download.gnome.org/sources/gtksourceview/4.3/gtksourceview-4.3.1.tar.xz",
"sha256" : "b8ef118786f4e5c1ee20b986ac3914c60064a11acdee73645be3adb3543a2a5d"
}
]
},
{
"name" : "gspell",
"config-opts" : [
"--disable-gtk-doc"
],
"sources" : [
{
"type" : "git",
"url" : "https://gitlab.gnome.org/GNOME/gspell.git"
"type" : "archive",
"url" : "https://download.gnome.org/sources/gspell/1.8/gspell-1.8.1.tar.xz",
"sha256" : "819a1d23c7603000e73f5e738bdd284342e0cd345fb0c7650999c31ec741bbe5"
}
]
},
{
"name" : "gedit",
"buildsystem": "meson",
"buildsystem" : "meson",
"config-opts" : [
"-Dvapi=true",
"-Dgtk_doc=false"
],
"sources" : [
{
"type" : "git",
......@@ -83,7 +101,7 @@
},
{
"name" : "gedit-plugins",
"buildsystem": "meson",
"buildsystem" : "meson",
"sources" : [
{
"type" : "git",
......
gedit installation by building the source code
==============================================
Recommendation to install in a separate prefix
----------------------------------------------
Once you have built gedit from source, you cannot run the application from its
build directory: you need to install it with `ninja install`. For this reason it
is highly recommended that you install in a separate prefix instead of
overwriting your system binaries.
Note however that when running gedit from a custom prefix you will need to set
many environment variables accordingly, for instance `PATH` and `XDG_DATA_DIR`.
There exists several tools that GNOME developers use to take care of all of
this. See the _Tools_ section below.
Installation of the dependencies
--------------------------------
You need to have all gedit dependencies installed, with recent enough versions.
If a dependency is missing or is too old, the build configuration fails (you can
try to run the build configuration command for gedit until it succeeds, see the
procedure below).
You can install the dependencies by installing packages provided by your
operating system, for example on Fedora:
```
# dnf builddep gedit
```
But if your version of gedit provided by the OS differs too much from the
version of gedit you want to build from source, you'll need to install the new
dependencies from source too, and it can become a complicated task if you do it
manually.
Also, during gedit development, gedit may depend on a not-yet-released
development version of a GNOME dependency. So certain GNOME dependencies may
need to be installed from Git.
That's why if you have difficulties installing recent enough versions of the
dependencies, it is usually easier to use one of the tools explained in the next
section.
Tools
-----
There are several tools available that take care of the following:
- Install in a separate prefix.
- Build or install dependencies.
- Plus, for some tools: run in a container/sandbox.
GNOME developers usually use one of these tools:
- [JHBuild](https://developer.gnome.org/jhbuild/unstable/)
- Or [BuildStream](https://buildstream.build/)
- Or [Flatpak](https://flatpak.org/)
JHBuild tips:
- Try `ignore_suggests = True` in your jhbuildrc to have fewer dependencies to
build (see the difference with "jhbuild list gedit"). Another solution is to
put some modules in the skip variable in jhbuildrc.
- Build also the dconf module to get preferences saved.
Building the gedit module manually
----------------------------------
If you use one of the above tools, you don't need all the explanations in this
section. But it can be instructive.
gedit uses the [Meson](https://mesonbuild.com/) build system.
Once the dependencies are installed, here are simple procedures to finally build
the gedit module from source.
### Installation onto the system
**Warning**: this procedure doesn't install in a separate prefix, so it may
overwrite your system binaries.
```
$ mkdir build && cd build/
$ meson # Build configuration
$ ninja # Build
[ Become root if necessary ]
$ ninja install # Installation
```
### Installation in a separate prefix
Just change the above `meson` command by:
```
$ meson --prefix YOUR_PREFIX
```
gedit development - getting started
===================================
The following explanations can be improved over time, if you see something
missing, a feedback is welcome.
Programming languages and paradigms
-----------------------------------
gedit is mostly written in C, with some plugins in Python or
[Vala](https://wiki.gnome.org/Projects/Vala/). The build system is in
[Meson](https://mesonbuild.com/).
The code is object-oriented and event-driven. In C, it's thanks to the use of
the GObject library (see next section). If you open some `*.c` or `*.h` files,
you may think “what is this horror?!” but – don't panic – it's just some
C/GObject boilerplate code, and that boilerplate can be generated by a tool. So
once you've learned GObject, you will no longer be afraid ;-)
Libraries used
--------------
As every GNOME application, gedit uses the GLib, GObject and GTK libraries. To
modify the gedit source code, you should be familiar with those libraries. See
the [GTK website](https://www.gtk.org/) and the document
[The GLib/GTK Development Platform – A Getting Started Guide](https://people.gnome.org/~swilmet/glib-gtk-book/).
The main widget used by gedit is GtkTextView, a general-purpose multiline text
editor. To learn that widget API, read the excellent
[GtkTextView tutorial](http://www.bravegnu.org/gtktext/) (a bit old but still
mostly valid). But GtkTextView is not enough for source code edition. gedit
actually uses the
[GtkSourceView](https://wiki.gnome.org/Projects/GtkSourceView) library, which
contains a subclass of GtkTextView with syntax highlighting, a completion
framework, the search and replace, and many other features useful for a text
editor or an IDE.
For its plugin system, gedit uses the
[libpeas](https://wiki.gnome.org/Projects/Libpeas) library.
Plugins may have other dependencies, for example the spell-checking plugin uses
[gspell](https://wiki.gnome.org/Projects/gspell).
gedit architecture
------------------
The [gedit Git repository](https://gitlab.gnome.org/GNOME/gedit) contains the
_gedit core_ plus the default plugins. There is also the
[gedit-plugins Git repository](https://gitlab.gnome.org/GNOME/gedit-plugins)
for additional official plugins. The gedit core source code is in the `gedit/`
directory. The plugins are in … `plugins/`!
gedit core provides:
- A basic text editor.
- The integration of libpeas, with an API for plugins.
There is a class diagram of gedit core in the file
[class-diagram.dia](class-diagram.dia) (but it may be outdated, see the Git log
for that file).
Build/Installation
------------------
See the file [build.md](build.md).
First contribution
------------------
See the [Newcomers](https://wiki.gnome.org/Newcomers/) page to start
contributing to GNOME in general.
To know how to contribute to gedit specifically, read the