<?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
    <ulink url="https://wiki.gnome.org/Projects/GtkSourceView">GtkSourceView</ulink>-based
    text editors and IDEs. Tepl is the acronym for “Text editor product line”.
  </para>

  <para>
    See the <ulink url="https://wiki.gnome.org/Projects/Tepl">Tepl web page</ulink>.
  </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 (see the book
    <ulink url="https://www.amazon.com/Feature-Oriented-Software-Product-Lines-Implementation/dp/3642375200/">Feature-Oriented
    Software Product Lines: Concepts and Implementation</ulink>).
    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>
    Maybe some of the Tepl features will be moved to GtkSourceView when it's
    considered more stable. So Tepl can also be seen as an incubator for some
    GtkSourceView features.
  </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>Iterative API design and stability guarantees</title>

    <para>
      Tepl uses the same
      <ulink url="https://developer.gnome.org/programming-guidelines/stable/versioning.html.en">versioning scheme</ulink>
      as GNOME. API/ABI stability is guaranteed. For example Tepl 17.2 is
      backward-compatible with Tepl 17.0 (those versions don't necessarily exist,
      it's just an example). But the peculiarity of Tepl is that new major
      versions are released more often, at most every 6 months if needed.
      Different major versions can be installed in parallel, like GTK&nbsp;2
      and GTK&nbsp;3.
    </para>

    <para>
      New major versions are released more often because 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>
      So applications depending on an old (stable) vesion of Tepl will still
      compile and run fine, and the Tepl developers can develop the library with
      more freedom.
    </para>

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

    <para>
      We think that it is the best development model for a library like Tepl. We
      have thought about other solutions: (a) providing an unstable API, forcing
      all applications to be ported to the new APIs when a new version of Tepl
      is released, and (b) have a much longer development cycle (5 years for
      instance) to develop Tepl and port several applications to it – including
      gedit. We prefer to follow an agile methodology, which implies to have
      frequent releases, and to follow the GNOME release schedule with a new
      stable version every six months. So we don't like the solution (b). As for
      the solution (a), it should be self-evident that it would cause problems
      for downstream distributors. There is another solution: (c) bundling,
      applications statically link the Tepl library with the app binary. But we
      know that some downstream distributors don't like bundling. If you think
      of other solutions, comments are more than welcome. We prefer to release a
      new stable version every six months, and we prefer to implement and design
      the APIs iteratively.
    </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>
    <para>
      To compile a program that uses Tepl&nbsp;&package_api_version;, you can for
      example use the following command:
    </para>
    <para>
      <code>$ gcc hello.c `pkg-config --cflags --libs tepl-&package_api_version;` -o hello</code>
    </para>
  </refsect1>
</part>
