.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DH_VIM-ADDON 1"
.TH DH_VIM-ADDON 1 "2020-09-03" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dh_vim\-addon \- debhelper addon to help package Vim/Neovim addons
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBdh_vim\-addon\fR [\fIdebhelper options\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdh_vim\-addon\fR is a debhelper program that is responsible for installing
addons for Vim/Neovim and generating the help tags file for any documentation.
The addons are installed into directories following Vim's native \*(L"package\*(R"
hierarchy.
.PP
There are two types of addons which are supported.
.IP "automatic" 4
.IX Item "automatic"
Automatic addons are immediately enabled for users when installed.  The addons
should provide a standard mechansim to let the user disable the addon.  This is
typically done by short-circuiting loading of the addon when the user adds
\&\f(CW\*(C`let g:loaded_<addon> = 1\*(C'\fR in their vimrc.
.IP "optional" 4
.IX Item "optional"
Optional addons are only enabled for users if the explicitly opt-in to the
addon.  The user can do so by adding \f(CW\*(C`packadd! <addon>\*(C'\fR to their vimrc.
.SH "FILES"
.IX Header "FILES"
.IP "debian/\fIpackage\fR.vim\-addon" 4
.IX Item "debian/package.vim-addon"
.PD 0
.IP "debian/\fIpackage\fR.neovim\-addon" 4
.IX Item "debian/package.neovim-addon"
.PD
List of installed directories to be setup as an automatic addon in \fIpackage\fR.
The format is a set of lines, where each line lists the base directory of an
addon, relative to the package build directory and, optionally, the addon name.
.RS 4
.Sp
.Vb 1
\&    B<path/to/addon/basedir>  I<optional\-addon\-name>
.Ve
.RE
.RS 4
.Sp
There should typically only be a single addon, and therefore line, per
package.  If an addon name is not supplied, the last component of the base
directory will be used as the addon name.
.Sp
If the \f(CW\*(C`basedir\*(C'\fR does not match the addon's name (e.g., because it matches the
Debian package's name), then it is recommended to supply the addon name.  This
ensures that common conventions, like \f(CW\*(C`packadd addon\-name\*(C'\fR and \f(CW\*(C`let
g:loaded_addon = 1\*(C'\fR work as the user expects.
.Sp
The \f(CW\*(C`${vim\-addon:Depends}\*(C'\fR substvar will be set with any required dependencies.
.RE
.IP "debian/\fIpackage\fR.vim\-opt\-addon" 4
.IX Item "debian/package.vim-opt-addon"
.PD 0
.IP "debian/\fIpackage\fR.neovim\-opt\-addon" 4
.IX Item "debian/package.neovim-opt-addon"
.PD
This file follows the same format as \fIvim-addon\fR, however the directories will
be installed as optional addons in \fIpackage\fR.
.Sp
The \f(CW\*(C`${vim\-addon:Depends}\*(C'\fR substvar will be set with any required dependencies.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Single addon, dh-style"
.IX Subsection "Single addon, dh-style"
Here is an example of a simple \fBdh\fR\|(1) style package with a single addon,
compatible with Vim and Neovim.  The \fIdebian/rules\fR is:
.Sp
.Vb 3
\&    #!/usr/bin/make \-f
\&    %:
\&        dh $@ \-\-with vim_addon
.Ve
.PP
The Vim addon is installed under \fI/usr/share/vim\-simple\fR, but the addon name
is \fIsimple\fR (i.e., \f(CW\*(C`let g:loaded_simple = 1\*(C'\fR is the expected way for a user
to disable loading of the addon).  The \fIvim-addon\fR file is:
.Sp
.Vb 1
\&    usr/share/vim\-simple simple
.Ve
.PP
\&\fIdebian/vim\-simple.neovim\-addon\fR is a symlink to
\&\fIdebian/vim\-simple.vim\-addon\fR.
.SS "Multiple addons, debhelper"
.IX Subsection "Multiple addons, debhelper"
Here is an example of a debhelper style package, providing multiple addons,
some of which aren't compatible with Neovim.  The \fIdebian/rules\fR contains:
.Sp
.Vb 6
\&    #!/usr/bin/make \-f
\&    ...
\&        # Install the files to the package build directory
\&        dh_install
\&        # Setup the (neo)vim addons
\&        dh_vim\-addon
.Ve
.PP
The addons are installed under \fI/usr/share/vim\-multi\-addons\fR.  Unlike the
single addon example, these addons are all installed into a directory matching
the addon name, so only the base directory is needed in the \fIvim-addon\fR file:
.Sp
.Vb 2
\&    usr/share/vim\-multi\-addons/addon1
\&    usr/share/vim\-multi\-addons/addon2
.Ve
.PP
while the \fIneovim-addon\fR is:
.Sp
.Vb 2
\&    usr/share/vim\-multi\-addon/addon1
\&    usr/share/vim\-multi\-addon/addon3
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnvim\fR\|(1), \fBvim\fR\|(1)
.SH "AUTHOR"
.IX Header "AUTHOR"
James McCoy <jamessan@debian.org>