<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
 <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
 <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
 %gtkdocentities;
]>

<part id="intro">
  <title>Introduction</title>

  <para>
    Tepl is a library that eases the development of GtkSourceView-based text
    editors and IDEs. Tepl is the acronym for “Text editor product line”.
  </para>

  <para>
    Tepl was previously named Gtef (GTK text editor framework). The project has
    been renamed in June 2017 to have a more beautiful name. The end of Tepl is
    pronounced like in “apple”.
  </para>

  <para>
    The Tepl library follows a product line approach, inspired by
    <emphasis>Feature-Oriented Software Product Lines: Concepts and
    Implementation</emphasis> (2013 - Apel, Batory, Kästner and Saake).
  </para>

  <para>
    Instead of creating one general-purpose text editor or IDE with a plugin
    system, the idea is to create several <emphasis>specialized</emphasis> text
    editors. For example specialized for one programming language, or one
    development platform, or a small group of related languages. By being
    specialized, an application is potentially better at what it does. It
    follows more closely the UNIX philosophy to “do only one thing but do it
    well”. And it better follows the GNOME philosophy: writing applications that
    Just Works; when a user opens the text editor for the first time, it should
    work out-of-the-box, without the need to find, install and configure
    plugins. Of course it still makes sense to develop one general-purpose text
    editor for the languages not yet covered by specialized text editors.
  </para>

  <para>
    Most of the features of the library are available as a toolkit, but the
    interesting part of Tepl is that it contains also a framework (for now
    without a plugin system). The goal of the framework is to provide
    higher-level APIs, to be able to create a new text editor easily. An
    application wanting to use Tepl is not forced to use the framework in its
    entirety, it is possible to use just the toolkit parts. The library is
    implemented this way to achieve maximum re-usability: the framework is less
    re-usable because it makes some assumptions about the general architecture
    of the application, but since the features are also available with a
    lower-level API –&nbsp;as a toolkit&nbsp;– all text editors and IDEs based
    on GtkSourceView (or even other types of applications) should be able to
    benefit from the features implemented in Tepl.
  </para>

  <para>
    Initially, Tepl was created as an incubator for new GtkSourceView features,
    but in practice the features remained in Tepl, because Tepl is considered
    less stable for its APIs, and it's convenient to iterate on the APIs with
    more freedom. Another reason is that renaming the namespace of all symbols
    is difficult to do in C.
  </para>

  <refsect1>
    <title>Boundary between GtkSourceView and Tepl</title>

    <para>
      For the framework part of Tepl (not the toolkit parts), there is a
      somewhat clear boundary between GtkSourceView and Tepl: the top-level
      object in GtkSourceView is the <link linkend="GtkSourceView">GtkSourceView</link>
      widget (representing only one view, or one file), while the GtkSourceView
      widget is at the bottom of the containment hierarchy in the Tepl
      framework (it is a “somewhat” clear boundary because there is also
      <link linkend="TeplBuffer">TeplBuffer</link>, a subclass of
      <link linkend="GtkSourceBuffer">GtkSourceBuffer</link>).
    </para>

    <para>
      The top-level object in Tepl is <link linkend="TeplApplication">TeplApplication</link>,
      representing the whole application which can contain several windows, with
      each window containing one or several GtkSourceView widgets (typically
      with a Tabbed Document Interface).
    </para>

    <para>
      So the GtkSourceView library is not aware that there can be several files
      opened in the application, while the Tepl framework has a complete view of
      the application with regards to the opened files/tabs. It permits to
      implement higher-level APIs.
    </para>
  </refsect1>

  <refsect1>
    <title>API stability</title>
    <para>
      The API is now constantly unstable. The library soname is adapted for each
      release.
    </para>

    <para>
      Tepl contains more experimental APIs than GtkSourceView, sometimes even
      unfinished features. API design is hard, it needs an iterative process.
      Instead of being stuck for years with a non-optimal API, the Tepl
      developers want to be able to break the API at any time, to iteratively
      improve it. Sometimes we see possible improvements several years later.
    </para>

    <para>
      The API breaks are documented in
      <link linkend="api-breaks">this section</link>.
    </para>
  </refsect1>

  <refsect1>
    <title>GTK and GtkSourceView dependencies</title>
    <para>
      Tepl&nbsp;&package_api_version; depends on GTK&nbsp;3 and
      GtkSourceView&nbsp;4.
    </para>
  </refsect1>

  <refsect1>
    <title>pkg-config name</title>
    <para>
      For Tepl&nbsp;&package_api_version;, the pkg-config name is:
      <code>tepl-&package_api_version;</code>
    </para>
  </refsect1>
</part>
