doc: Document 'android-ndk-build-system'.

[jackhill/guix/guix.git] / doc / contributing.texi

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 1dd3ea8..2792fe2 100644 (file)
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -110,10 +110,13 @@ actually installing them.  So that you can distinguish between your
 To that end, all the command-line tools can be used even if you have not
 run @code{make install}.  To do that, prefix each command with
 @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
-top build tree of Guix), as in:
+top build tree of Guix), as in@footnote{The @option{-E} flag to
+@command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
+such that @command{guix-daemon} and the tools it uses can find the Guile
+modules they need.}:
 
 @example
-$ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
+$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
 $ ./pre-inst-env guix build hello
 @end example
 
@@ -193,6 +196,34 @@ facilities to directly operate on the syntax tree, such as raising an
 s-expression or wrapping it, swallowing or rejecting the following
 s-expression, etc.
 
+@cindex code snippets
+@cindex templates
+@cindex reducing boilerplate
+We also provide templates for common git commit messages and package
+definitions in the @file{etc/snippets} directory.  These templates can
+be used with @url{http://joaotavora.github.io/yasnippet/, YASnippet} to
+expand short trigger strings to interactive text snippets.  You may want
+to add the snippets directory to the @var{yas-snippet-dirs} variable in
+Emacs.
+
+@lisp
+;; @r{Assuming the Guix checkout is in ~/src/guix.}
+(with-eval-after-load 'yasnippet
+  (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
+@end lisp
+
+The commit message snippets depend on @url{https://magit.vc/, Magit} to
+display staged files.  When editing a commit message type @code{add}
+followed by @kbd{TAB} to insert a commit message template for adding a
+package; type @code{update} followed by @kbd{TAB} to insert a template
+for updating a package.
+
+The main snippet for @code{scheme-mode} is triggered by typing
+@code{package...} followed by @kbd{TAB}.  This snippet also inserts the
+trigger string @code{origin...}, which can be expanded further.  The
+@code{origin} snippet in turn may insert other trigger strings ending on
+@code{...}, which also can be expanded further.
+
 
 @node Coding Style
 @section Coding Style
@@ -277,6 +308,13 @@ indent a whole file, omit the second argument:
 ./etc/indent-code.el gnu/services/@var{file}.scm
 @end example
 
+@cindex Vim, Scheme code editing
+If you are editing code with Vim, we recommend that you run @code{:set
+autoindent} so that your code is automatically indented as you type.
+Additionally,
+@uref{https://www.vim.org/scripts/script.php?script_id=3998,
+@code{paredit.vim}} may help you deal with all these parentheses.
+
 We require all top-level procedures to carry a docstring.  This
 requirement can be relaxed for simple private procedures in the
 @code{(guix build @dots{})} name space, though.