Debian Codegraph @

docs/reference/intro.xml

raw
1 <?xml version="1.0"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
4 [
5 <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
6 <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
7 %gtkdocentities;
8 ]>
9
10 <part id="intro">
11 <title>Introduction</title>
12
13 <para>
14 libgedit-tepl is a library that eases the development of text editors and
15 IDEs based on GTK. Tepl is the acronym for “Text editor product line”.
16 </para>
17
18 <para>
19 The libgedit-tepl library follows a product line approach, inspired by
20 <emphasis>Feature-Oriented Software Product Lines: Concepts and
21 Implementation</emphasis> (2013 - Apel, Batory, Kästner and Saake).
22 </para>
23
24 <para>
25 Instead of creating one general-purpose text editor or IDE with a plugin
26 system, the idea is to create several <emphasis>specialized</emphasis> text
27 editors. For example specialized for one programming language, or one
28 development platform, or a small group of related languages. By being
29 specialized, an application is potentially better at what it does. It
30 follows more closely the UNIX philosophy to “do only one thing but do it
31 well”. And it better follows the GNOME philosophy: writing applications that
32 Just Works; when a user opens the text editor for the first time, it should
33 work out-of-the-box, without the need to find, install and configure
34 plugins. Of course it still makes sense to develop one general-purpose text
35 editor for the languages not yet covered by specialized text editors.
36 </para>
37
38 <para>
39 Most of the features of the library are available as a toolkit, but the
40 interesting part of libgedit-tepl is that it contains also a framework (for
41 now without a plugin system). The goal of the framework is to provide
42 higher-level APIs, to be able to create a new text editor easily. An
43 application wanting to use libgedit-tepl is not forced to use the framework
44 in its entirety, it is possible to use just the toolkit parts. The library
45 is implemented this way to achieve maximum re-usability: the framework is
46 less re-usable because it makes some assumptions about the general
47 architecture of the application, but since the features are also available
48 with a lower-level API –&nbsp;as a toolkit&nbsp;– all text editors and IDEs
49 based on GTK and libgedit-gtksourceview (or even other types of
50 applications) should be able to benefit from the features implemented in
51 libgedit-tepl.
52 </para>
53
54 <para>
55 Initially, libgedit-tepl was created as an incubator for new GtkSourceView
56 features, but in practice the features remained in libgedit-tepl, because
57 libgedit-tepl is considered less stable for its APIs, and it's convenient to
58 iterate on the APIs with more freedom. Another reason is that renaming the
59 namespace of all symbols is difficult to do in C.
60 </para>
61
62 <refsect1>
63 <title>Boundary between libgedit-gtksourceview and libgedit-tepl</title>
64
65 <para>
66 For the framework part of libgedit-tepl (not the toolkit parts), there is
67 a somewhat clear boundary between libgedit-gtksourceview and
68 libgedit-tepl: the top-level object in libgedit-gtksourceview is the
69 <link linkend="GtkSourceView">GtkSourceView</link> widget (representing
70 only one view, or one file), while the GtkSourceView widget is at the
71 bottom of the containment hierarchy in the libgedit-tepl framework (it is
72 a “somewhat” clear boundary because there is also
73 <link linkend="TeplBuffer">TeplBuffer</link>, a subclass of
74 <link linkend="GtkSourceBuffer">GtkSourceBuffer</link>).
75 </para>
76
77 <para>
78 The top-level object in libgedit-tepl is
79 <link linkend="TeplApplication">TeplApplication</link>, representing the
80 whole application which can contain several windows, with each window
81 containing one or several GtkSourceView widgets (typically with a Tabbed
82 Document Interface).
83 </para>
84
85 <para>
86 So the libgedit-gtksourceview library is not aware that there can be
87 several files opened in the application, while the libgedit-tepl framework
88 has a complete view of the application with regards to the opened
89 files/tabs. It permits to implement higher-level APIs.
90 </para>
91 </refsect1>
92
93 <refsect1>
94 <title>API stability</title>
95 <para>
96 The API is now constantly <emphasis>unstable</emphasis>. The library
97 soname is adapted (if needed) for each release.
98 </para>
99
100 <para>
101 libgedit-tepl contains experimental APIs, sometimes even unfinished
102 features. API design is hard, it needs an iterative process. Instead of
103 being stuck for years with a non-optimal API, the libgedit-tepl developers
104 want to be able to break the API at any time, to iteratively improve it.
105 Sometimes we see possible improvements several years later.
106 </para>
107
108 <para>
109 The API breaks are documented in
110 <link linkend="api-breaks">this section</link>.
111 </para>
112 </refsect1>
113
114 <refsect1>
115 <title>GTK dependency</title>
116 <para>
117 libgedit-tepl&nbsp;&package_api_version; depends on GTK&nbsp;3.
118 </para>
119 </refsect1>
120
121 <refsect1>
122 <title>pkg-config name</title>
123 <para>
124 For libgedit-tepl&nbsp;&package_api_version;, the pkg-config name is:
125 <code>libgedit-tepl-&package_api_version;</code>
126 </para>
127 </refsect1>
128 </part>