source: postlfs/editors/vim.xml@ 289fd16

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!-- only for initial releases of a new version
  <!ENTITY vim-download-http "http://ftp.vim.org/vim/unix/vim-&vim-version;.tar.bz2">-->
  <!ENTITY vim-download-http "https://github.com/vim/vim/archive/v&vim-version;/vim-&vim-version;.tar.gz">
  <!ENTITY vim-download-ftp  " ">
  <!ENTITY vim-md5sum        "79dfe62be5d347b1325cbd5ce2a1f9b3">
  <!ENTITY vim-size          "17 MB">
  <!ENTITY vim-buildsize     "125 MB (add 67 MB for tests)">
  <!ENTITY vim-time          "0.3 SBU (with parallelism=4; add 3.0 SBU for tests)">
]>

<sect1 id="vim" xreflabel="Vim-&vim-version;">
  <?dbhtml filename="vim.html"?>


  <title>Vim-&vim-version;</title>

  <indexterm zone="vim">
    <primary sortas="a-Vim">Vim</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Vim</title>

    <para>
      The <application>Vim</application> package, which is an
      abbreviation for VI IMproved, contains a <command>vi</command>
      clone with extra features as compared to the original
      <command>vi</command>.
    </para>

    <para>
      The default LFS instructions install <application>vim</application>
      as a part of the base system. If you would prefer to link
      <application>vim</application> against <application>X</application>,
      you should recompile <application>vim</application> to enable GUI mode.
      There is no need for special instructions since
      <application>X</application> support is automatically detected.
    </para>

    <note>
      <para>
        The version of vim changes daily.  To get the latest
        version, go to <ulink url="https://github.com/vim/vim/releases">
        https://github.com/vim/vim/releases</ulink>.
      </para>
    </note>

    &lfs120_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&vim-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&vim-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &vim-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &vim-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &vim-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &vim-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Vim Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="x-window-system"/> and
      <xref linkend="gtk3"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="gpm"/>,
      <xref linkend="lua"/>,
      <xref linkend="ruby"/>, and
      <xref linkend="rsync"/>
    </para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Vim</title>

    <note>
      <para>
        If you recompile <application>Vim</application> to link against
        <application>X</application> and your <application>X</application>
        libraries are not on the root partition, you will no longer have an
        editor for use in emergencies. You may choose to install an additional
        editor, not link <application>Vim</application> against
        <application>X</application>, or move the current <command>vim</command>
        executable to the <filename class="directory">/bin</filename> directory
        under a different name such as <filename>vi</filename>.
      </para>
    </note>
<!--
    <para>
      First, if you are building the Lua interpreter for VIM, adapt it to an
      API change in lua-5.4.0:
    </para>

<screen><userinput remap="pre">sed -i '461 s/static int/int/' src/if_lua.c</userinput></screen>
-->
    <para>
      Install <application>Vim</application> by running the following
      commands:
    </para>

    <note>
      <para>
        If you intend to run the tests and have not installed Xorg in /usr,
        append LDFLAGS='-L$XORG_PREFIX/lib' to the configure line below.
      </para>
    </note>

<screen><userinput>echo '#define SYS_VIMRC_FILE  "/etc/vimrc"' &gt;&gt;  src/feature.h &amp;&amp;
echo '#define SYS_GVIMRC_FILE "/etc/gvimrc"' &gt;&gt; src/feature.h &amp;&amp;

./configure --prefix=/usr        \
            --with-features=huge \
            --enable-gui=gtk3    \
            --with-tlib=ncursesw &amp;&amp;
make</userinput></screen>

    <note>
      <para>
        If the global configuration file <filename>/etc/vimrc</filename>
        references the <envar>VIMRUNTIME</envar> environment variable, some
        tests may complain about being unable to find the corresponding
        directory and wait for user input. If this is the case, this file
        should be saved and removed before running the tests.  Or if
        <xref linkend='bubblewrap'/> is installed, it's also possible to
        create a lightweight container environment where this file is hidden
        and run the tests in the container.
      </para>
    </note>

    <para>
      To test the results, issue: <command>make -j1 test</command>, or
      <command>bwrap --dev-bind / / --dev-bind /dev/null /etc/vimrc make -j1
      test</command> if running the tests with <xref linkend='bubblewrap'/>
      and <filename>/etc/vimrc</filename> hidden.
      Even if one of the tests fails to produce the file
      <filename>test.out</filename> in <filename
      class="directory">src/testdir</filename>, the remaining tests will
      still be executed. If all goes well, the log will report
      <literal>ALL DONE</literal>. Some tests labelled as
      <quote>flaky</quote> may fail occasionally and can be ignored.
      The tests are known to fail if the output is redirected to a file,
      and also if they are run in a 'screen' session.
    </para>

    <note>
      <para>
        Some color tests expect to be executed under the
        <command>xterm</command> terminal emulator.
      </para>
    </note>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install</userinput></screen>

    <para>
      By default, Vim's documentation is installed in <filename
      class="directory">/usr/share/vim</filename>. The following symlink allows
      the documentation to be accessed via <filename
      class="directory">/usr/share/doc/vim-&vim-version;</filename>, making it
      consistent with the location of documentation for other packages:
    </para>

<!-- When updating, be sure to change the vim-majmin entity for the
     proper 'vimxx' unpacked directory -->

<screen role="root"><userinput>ln -snfv ../vim/vim&vim-majmin;/doc /usr/share/doc/vim-&vim-version;</userinput></screen>

    <para>
      <emphasis role='bold'>If</emphasis> you wish to update the runtime
      files, issue the following command (requires <xref linkend="rsync"/>)
      to download it:
    </para>

<screen role='nodump'><userinput>rsync -avzcP --exclude="/dos/" --exclude="/spell/" \
    ftp.nluug.nl::Vim/runtime/ ./runtime/</userinput></screen>

    <para>
      And then install the updated runtime files and regenerate the
      <filename>tags</filename> file, as the
      <systemitem class="username">root</systemitem> user issue:
    </para>

    <!-- already executed by "make install" if not updating the runtime
         files -->
<screen role="nodump"><userinput>make -C src installruntime &amp;&amp;
vim -c ":helptags /usr/share/doc/vim-&vim-version;" -c ":q"</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <parameter>--with-features=huge</parameter>: This switch enables all
      the additional features available in <application>Vim</application>,
      including support for multibyte characters.
    </para>

    <para>
      <parameter>--with-tlib=ncursesw</parameter>: This switch forces Vim to
      link against the <filename class="libraryfile">libncursesw</filename>
      library.
    </para>

    <para>
      <option>--enable-gui=no</option>: This will prevent compilation of the
      GUI. <application>Vim</application> will still link against
      <application>X</application>, so that some features such as the
      client-server model or the x11-selection (clipboard) are still available.
    </para>

    <para>
      <option>--without-x</option>: If you prefer not to link
      <application>Vim</application> against <application>X</application>, use
      this switch.
    </para>

    <para>
      <option>--enable-luainterp</option>,
      <option>--enable-perlinterp</option>,
      <option>--enable-python3interp=dynamic</option>,
      <option>--enable-tclinterp --with-tclsh=tclsh</option>,
      <option>--enable-rubyinterp</option>:
      These options include the Lua, Perl, Python3, Tcl, or Ruby interpreters
      that allow using other application code in <application>vim</application>
      scripts. All the <option>--enable-*</option> options can accept
      <option>=dynamic</option> to dynamically load the interpreter when
      needed. This is required for <application>Python 3</application> to
      prevent segmentation faults. For <application>tcl</application>,
      it is necessary to indicate the name of the <command>tclsh</command>
      executable, since <command>configure</command> only searches versioned
      names with old versions.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Vim</title>

    <sect3 id='vim-config'>
      <title>Config Files</title>

      <para>
        <filename>/etc/vimrc</filename> and
        <filename>~/.vimrc</filename>
      </para>

      <indexterm zone="vim vim-config">
        <primary sortas="e-etc-vimrc">/etc/vimrc</primary>
      </indexterm>

      <indexterm zone="vim vim-config">
        <primary sortas="e-AA.vimrc">~/.vimrc</primary>
      </indexterm>

    </sect3>
<!-- there are now desktop files shipped with the package
    <sect3 id='vim-desktop'>
      <title>Desktop File</title>

      <para>
        If desired, create a menu entry for graphical vim,
        <filename>gvim.desktop</filename>, as the <systemitem
        class="username">root</systemitem> user
      </para>

<screen role="root"><userinput>cat &gt; /usr/share/applications/gvim.desktop &lt;&lt; "EOF"
<literal>[Desktop Entry]
Name=GVim Text Editor
Comment=Edit text files
Comment[pt_BR]=Edite arquivos de texto
TryExec=gvim
Exec=gvim -f %F
Terminal=false
Type=Application
Icon=gvim.png
Categories=Utility;TextEditor;
StartupNotify=true
MimeType=text/plain;</literal>
EOF</userinput></screen>

    </sect3>
-->
    <sect3 id='vim-init'>
      <title>Configuration Information</title>

      <para>
        <application>Vim</application> has an integrated spell checker
        which you can enable by issuing the following in a vim window:
      </para>

<screen><literal>:setlocal spell spelllang=ru</literal></screen>

      <para>
        This setting will enable spell checking for the Russian
        language for the current session.
      </para>

      <para>
        By default, <application>Vim</application> only installs spell
        files for the English language. If a spell file is not available for
        a language, then <application>Vim</application> will call the
        <filename>$VIMRUNTIME/plugin/spellfile.vim</filename> plugin and will
        try to obtain the *.spl and optionally *.sug from the vim ftp server,
        by using the <filename>$VIMRUNTIME/plugin/netrwPlugin.vim</filename>
        plugin.
      </para>

<!-- When updating, be sure to change the line below for the proper 'vimxx'
     unpacked directory -->
      <para>
        Alternatively you can manually download the *.spl and *.sug files
        from: <ulink url="ftp://ftp.vim.org/pub/vim/runtime/spell/"/> and save
        them to <filename class="directory"> ~/.vim/spell </filename> or in
        <filename
          class="directory">/usr/share/vim/vim&vim-majmin;/spell/</filename>.
      </para>

      <para>
        To find out what's new in <application>Vim-&vim-version;</application>
        issue the following command:
      </para>

<screen><literal>:help version-&vim-version;</literal></screen>

      <para>
        For additional information on setting up
        <application>Vim</application> configuration files, see <xref
        linkend="postlfs-config-vimrc"/> and <ulink
        url="https://vim.fandom.com/wiki/Example_vimrc"/>.
      </para>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <para>
      A list of the reinstalled files, along with their short
      descriptions can be found in the
      <ulink url="&lfs-root;/chapter08/vim.html#contents-vim">LFS Vim
      Installation Instructions</ulink>.
    </para>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directory</segtitle>

      <seglistitem>
        <seg>gview, gvim, gvimdiff, gvimtutor, rgview, and rgvim</seg>
        <seg>None</seg>
        <seg>/usr/share/vim</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="gview">
        <term><command>gview</command></term>
        <listitem>
          <para>
            starts <command>gvim</command> in read-only mode
          </para>
          <indexterm zone="vim gview">
            <primary sortas="b-gview">gview</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gvim">
        <term><command>gvim</command></term>
        <listitem>
          <para>
            is the editor that runs under <application>X</application>
            and includes a GUI
          </para>
          <indexterm zone="vim gvim">
            <primary sortas="b-gvim">gvim</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gvimdiff">
        <term><command>gvimdiff</command></term>
        <listitem>
          <para>
            edits two or three versions of a file with
            <command>gvim</command> and shows the differences
          </para>
          <indexterm zone="vim gvimdiff">
            <primary sortas="b-gvimdiff">gvimdiff</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gvimtutor">
        <term><command>gvimtutor</command></term>
        <listitem>
          <para>
            teaches the basic keys and commands of
            <command>gvim</command>
          </para>
          <indexterm zone="vim gvimtutor">
            <primary sortas="b-gvimtutor">gvimtutor</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rgview">
        <term><command>rgview</command></term>
        <listitem>
          <para>
            is a restricted version of <command>gview</command>
          </para>
          <indexterm zone="vim rgview">
            <primary sortas="b-rgview">rgview</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rgvim">
        <term><command>rgvim</command></term>
        <listitem>
          <para>
            is a restricted version of <command>gvim</command>
          </para>
          <indexterm zone="vim gvim">
            <primary sortas="b-gvim">gvim</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>