Re: RFC: add more setups to Guix docs (was: The e(macs)lephant in the room and the Guix Bang)

[Ekaitz Zarraga <ekaitz@elenq.tech>]

[-- Attachment #1: Type: text/plain, Size: 5056 bytes --]

Hi Simon

------- Original Message -------
On Monday, September 25th, 2023 at 20:58, Simon Tournier <zimon.toutoune@gmail.com> wrote:

> Hi Ekaitz,
> 
> On Mon, 25 Sep 2023 at 14:25, Ekaitz Zarraga ekaitz@elenq.tech wrote:
> 
> > I decided to go for the action instead of discussion.
> 
> 
> Nice initiative!

Thank you.

> > Are maintainers open to add some section like this to the manual?
> 
> 
> I am not maintainer and I have nothing against. :-)

Great! Thanks for sharing your opinion.

> Well, I do not know if you plan to iterate. Here minor comments while
> reading it, in case.

Sure, I sent it looking for this. Thanks for the feedback. I really appreciate
it.

> 
> > --- a/doc/contributing.texi
> > +++ b/doc/contributing.texi
> > @@ -23,6 +23,7 @@ Contributing
> > * Building from Git:: The latest and greatest.
> > * Running Guix Before It Is Installed:: Hacker tricks.
> > * The Perfect Setup:: The right tools.
> > +* Alternative Setups:: Other posible tools that do the job.
> > * Packaging Guidelines:: Growing the distribution.
> > * Coding Style:: Hygiene of the contributor.
> > * Submitting Patches:: Share your work.
> > @@ -448,6 +449,76 @@ The Perfect Setup
> > Emacs Manual} and @ref{Minor Mode,,, debbugs-ug, The Debbugs User
> > Guide}.
> > 
> > +@node Alternative Setups
> > +
> > +Other setups may let you work on Guix with a similar development
> > +experience, but using an editor that is not as powerful as Emacs, but
> > +they might work better with the tools you currently use or help you
> > +make the transition to Emacs.
> 
> 
> Alternative wording:
> 
> Alternative setups than Emacs may let you work on Guix with a
> similar development experience and they might work better with the
> tools you currently use or help you make the transition to Emacs.
> 

Great, added!

> > +The options listed below only provide the alternatives to the Emacs
> > +based setup, which is the most widely used in the Guix community. If
> > +you want to really understand how is the perfect setup for Guix
> > +development supposed to work, we encourage you to read the section
> > +before this regardless the editor you choose to use.
> > +
> > +@menu
> > +* Guile Studio:: First step in your transition to Emacs.
> > +* Vim and NeoVim:: When you are evil to the root.
> > +@end menu
> > +
> > +@node Guile Studio
> > +@subsection Guile Studio
> > +
> > +Guile Studio is a pre-configured Emacs with mostly everything you need
> > +to start hacking in guile. If you are not familiar with Emacs it makes
> 
> -^
> Guile
> 
> typo: s/guile/Guile
> 

Added

> > +the transition easier for you.
> > +
> > +@example
> > +guix install guile-studio
> > +@end example
> > +
> > +Guile Studio comes with Geiser preinstalled and prepared for action.
> > +
> > +@node Vim and NeoVim
> > +@subsection Vim and Neovim
> > +
> > +Vim (and NeoVim) are also packaged in Guix, just in case you decided
> > +to go for the evil path.
> > +
> > +@example
> > +guix install vim
> > +@end example
> > +
> > +If you want to enjoy a similar development experience to that in the perfect
> > +setup, you should install several plugins to configure the editor. Vim (and
> > +NeoVim) have the equivalent to Paredit,
> > +@uref{https://www.vim.org/scripts/script.php?script_id=3998,
> > +@code{paredit.vim}}, that will help you with the structural editing of scheme
> 
> -^
> Scheme
> typo: s/scheme/Scheme
> 

Done

> > +files (the support for very large files is not greath, though).
> 
> -^
> typo
> typo: s/greath/great
> 

Done

> > +
> > +@example
> > +guix install vim-paredit
> > +@end example
> > +
> > +We also recommend that you run @code{:set autoindent} so that your code is
> > +automatically indented as you type.
> > +
> > +For the interaction with Git,
> > +@uref{https://www.vim.org/scripts/script.php?script_id=2975
> > +@code{fugitive.vim}} is the most commonly used plugin:
> > +
> > +@example
> > +guix install vim-fugitive
> > +@end example
> > +
> > +In NeoVim you can even even make a similar setup to Geiser using
> 
> -^ -^
> double
> typo: double even

Done

> 
> > +@url{https://conjure.fun/, Conjure} that lets you connect to a running
> > +Guile process and inject your code there live (sadly it's not packaged in
> > +Guix yet).

> NeoVim packager, is it complicated to have in Guix? If yes, is it easy
> to install without Guix?

I'd like to add it to Guix. Both Vim8 and NeoVim support packages (see `:help
package`) but I'm not really versed on this because I use Plug for this (it's
pretty easy to use, it's just an interface to git-clone/git-pull) but there
are many plugin systems in Vim.

I don't know very well how Vim works in Guix currently... I'm not sure if
the Vim package in Guix uses the package system.

I'll take a look and I'll try to add it to Guix too.

> Cheers,
> simon

I attach the new version.

Thank you Simon.

Cheers,
Ekaitz

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-WIP-doc-contributing-Add-alternative-setups-section.patch --]
[-- Type: text/x-patch; name=0001-WIP-doc-contributing-Add-alternative-setups-section.patch, Size: 4304 bytes --]

From 0c2be98f05bb288699a8e39dcef6428eb5a9dc3f Mon Sep 17 00:00:00 2001
Message-ID: <0c2be98f05bb288699a8e39dcef6428eb5a9dc3f.1695679042.git.ekaitz@elenq.tech>
From: Ekaitz Zarraga <ekaitz@elenq.tech>
Date: Mon, 25 Sep 2023 16:16:28 +0200
Subject: [PATCH] WIP: doc: contributing: Add alternative setups section

Start with Guile Studio and Vim/NeoVim.

* doc/contributing.texi (Alternative Setups): Add section explaining
  other setups that are similar to the one in The Perfect Setup
---
 doc/contributing.texi | 76 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 69 insertions(+), 7 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index ce4b9db366..5f936c4f64 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -23,6 +23,7 @@ Contributing
 * Building from Git::           The latest and greatest.
 * Running Guix Before It Is Installed::  Hacker tricks.
 * The Perfect Setup::           The right tools.
+* Alternative Setups::          Other posible tools that do the job.
 * Packaging Guidelines::        Growing the distribution.
 * Coding Style::                Hygiene of the contributor.
 * Submitting Patches::          Share your work.
@@ -448,6 +449,74 @@ The Perfect Setup
 Emacs Manual} and @ref{Minor Mode,,, debbugs-ug, The Debbugs User
 Guide}.
 
+@node Alternative Setups
+
+Alternative setups than Emacs may let you work on Guix with a
+similar development experience and they might work better with the
+tools you currently use or help you make the transition to Emacs.
+
+The options listed below only provide the alternatives to the Emacs
+based setup, which is the most widely used in the Guix community. If
+you want to really understand how is the perfect setup for Guix
+development supposed to work, we encourage you to read the section
+before this regardless the editor you choose to use.
+
+@menu
+* Guile Studio::                First step in your transition to Emacs.
+* Vim and NeoVim::              When you are evil to the root.
+@end menu
+
+@node Guile Studio
+@subsection Guile Studio
+
+Guile Studio is a pre-configured Emacs with mostly everything you need
+to start hacking in Guile. If you are not familiar with Emacs it makes
+the transition easier for you.
+
+@example
+guix install guile-studio
+@end example
+
+Guile Studio comes with Geiser preinstalled and prepared for action.
+
+@node Vim and NeoVim
+@subsection Vim and Neovim
+
+
+Vim (and NeoVim) are also packaged in Guix, just in case you decided
+to go for the evil path.
+
+@example
+guix install vim
+@end example
+
+If you want to enjoy a similar development experience to that in the perfect
+setup, you should install several plugins to configure the editor. Vim (and
+NeoVim) have the equivalent to Paredit,
+@uref{https://www.vim.org/scripts/script.php?script_id=3998,
+@code{paredit.vim}}, that will help you with the structural editing of Scheme
+files (the support for very large files is not great, though).
+
+@example
+guix install vim-paredit
+@end example
+
+We also recommend that you run @code{:set autoindent} so that your code is
+automatically indented as you type.
+
+For the interaction with Git,
+@uref{https://www.vim.org/scripts/script.php?script_id=2975
+@code{fugitive.vim}} is the most commonly used plugin:
+
+@example
+guix install vim-fugitive
+@end example
+
+In NeoVim you can even make a similar setup to Geiser using
+@url{https://conjure.fun/, Conjure} that lets you connect to a running Guile
+process and inject your code there live (sadly it's not packaged in Guix yet).
+
+
 @node Packaging Guidelines
 @section Packaging Guidelines
 
@@ -1196,13 +1265,6 @@ Formatting Code
 @noindent
 @xref{Invoking guix style}, for more information.
 
-@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.

base-commit: a965ff448dc9d92d18a51068388faf21e394d483
-- 
2.41.0