<page xmlns="http://projectmallard.org/1.0/"
      type="guide" style="task 2column"
      id="gedit-plugins-snippets">
  <info>
    <link type="guide" xref="gedit-plugin-guide#gedit-default-plugins"/>
    <desc>Use snippets to quickly insert often-used pieces of text.</desc>
  </info>

  <title>Snippets</title>

  <p><app>Snippets</app> provide a convenient way of inserting repetitive
  portions of code into your files. For example, an HTML snippet for the
  <code><![CDATA[<img>]]></code> tag would insert the opening and closing
  portions of the tag, as well as fixed places where you can enter image
  attributes. This can make writing code easier and faster.</p>

  <section id="enable-snippets">
    <title>Enable Snippets Plugin</title>

    <p>To enable the <gui>Snippets</gui> plugin:</p>

    <steps>
      <item>
        <p>Select <guiseq><gui style="menu">gedit</gui>
        <gui style="menuitem">Preferences</gui>
        <gui style="tab">Plugins</gui></guiseq>.</p>
      </item>
      <item>
        <p>Select <gui style="menuitem">Snippets</gui> to enable the
        plugin.</p>
      </item>
    </steps>
  </section>

  <section id="browse-snippets">
    <title>Browse Snippets</title>

    <p>To browse available snippets:</p>
    <steps>
      <item>
        <p>Select <guiseq><gui style="menu">Tools</gui>
        <gui style="menuitem">Manage Snippets</gui></guiseq>.</p>
        <note style="important">
          <p>Make sure the syntax is set appropriately. The status bar at the
          bottom of the <app>gedit</app> window will show the current language
          setting. This language setting is what allows gedit to insert the
          proper snippets. <app>Gedit</app> will normally detect the language or
          syntax of the file that you're using, but sometimes you may need to
          set it.</p>
          <figure>
            <desc>In this example, the language is set to HTML.</desc>
            <media type="image" mime="image/png"
            src="figures/gedit-html-snippet.png"></media>
        </figure>
        </note>
      </item>
      <item>
        <p>Browse the snippets that are available for your language or
        syntax.</p>
      </item>
    </steps>
  </section>

  <section id="using-snippets">
    <title>Using Snippets</title>

    <p>To insert a snippet into your current document:</p>

    <steps>
      <item>
        <p>Type the desired snippet name anywhere in your current document.</p>
      </item>
      <item>
        <p>Press <key>Tab</key> to insert the snippet associated with the input
        term.</p>
      </item>
    </steps>
  </section>

    <section id="example-insert-snippet">
    <title>Snippet Example Usage</title>

    <p>For example, if you have set the syntax to <em>HTML</em>, type
    <code>head </code>, and press the <key>Tab</key> key. The text would have
    auto completed into a snippet as:</p>

    <code>
      <![CDATA[<head>
      <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
      <title>Page Title</title>
      </head>]]>
    </code>

  </section>

  <section id="adding-snippets">
    <title>Adding Snippets</title>

    <p>You can add new Snippets that work either globally (that is, they are
    language agnostic) or only in a particular syntax.</p>

    <steps>
      <item>
        <p>Select <guiseq style="menu"><gui style="menuitem">Tools</gui>
        <gui style="menuitem">Manage Snippets</gui></guiseq>.</p>
      </item>
      <item>
        <p>From the <gui>Manage Snippets</gui> sidebar select the desired syntax
        and click on the "+" button to list existing snippets for the selected
        syntax.</p>
        <note style="tip">
          <p>To add a snippet that works globally (that is, when no particular
          syntax or language has been set for the document), select
          <gui>Global</gui> from the <gui>Manage Snippets</gui> sidebar.</p>
        </note>
      </item>
      <item>
        <p>To add a new snippet, click on the "plus" icon in the
        <gui>Manage Snippets</gui> sidebar.</p>
      </item>
      <item>
        <p>Input a name for the new snippet. The name of the snippet can be
        different from the snippet you want to add.</p>
      </item>
      <item>
        <p>Under the <gui style="group">Activation</gui> section, you must
        input a term for the <gui style="input">Tab trigger:</gui> textarea.
        You will be using this term to insert your snippet.</p>
        <note style="tip">
          <p>If you wish to insert a snippet with a keyboard shortcut, then
          click your mouse pointer on <gui style="input">Shortcut key:</gui>
          textarea and press the desired combination of keys. Once you have
          pressed and released the keys, the keyboard shortcut will be set.</p>
        </note>
      </item>
      <item>
        <p>Under the textarea for <gui style="input">Edit:</gui>, input the
        desired text for the snippet. You may use <code>${n}</code> to indicate
        variables, where <em>n</em> is replaced with a number that
        represents the numerical order of variables included.</p>
      </item>
    </steps>

  </section>

  <section id="example-add-snippet">
    <title>New Snippet Example</title>

    <p>Consider you have created a snippet with the term <var>greetings</var>
    in <gui style="input">Tab trigger:</gui>. The
    <gui style="input">Edit:</gui> textarea contains:</p>

    <code>
      <![CDATA[<greetings>Hello ${1:wonderful}${2:amazing} world!
      </greetings>]]>
    </code>

    <p>You can insert this snippet by typing <var>greetings</var> in the
    document and pressing the <key>Tab</key> key. The following text snippet
    will be inserted:</p>

    <code>
      <![CDATA[<greetings>Hello wonderfulamazing world!</greetings>]]>
    </code>

    <p>The words "wonderful" and "amazing" can be retained or deleted depending
    on your choice of usage. To do so, press <key>Tab</key> to choose between
    "wonderful" and "amazing" and press <key>Del</key> to delete the least
    preferred option.</p>
  </section>

  <!--TODO: <section id="modifying-snippets">
    <title>Modifying Existing Snippets</title>

  </section>-->
</page>
