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

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

[Ekaitz Zarraga]

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

Hi,

I decided to go for the action instead of discussion.

I attach an early WIP patch where I add a small section about
other setups for Guix development. I moved the Vim section from the
bottom because it felt alone and dangling.

I'd also like to add something about commit style, and that kind
of things, but I'll leave it for later.

Are maintainers open to add some section like this to the manual?

Please, comments and ideas are welcome.

If anyone wants to add other setups, please do.

Best,
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: 4350 bytes --]

From 40e5d840cf497a4313f33ce5fad7ecbea081f6ba Mon Sep 17 00:00:00 2001
Message-ID: <40e5d840cf497a4313f33ce5fad7ecbea081f6ba.1695651517.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 | 78 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 71 insertions(+), 7 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index ce4b9db366..0c98a81787 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,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.
+
+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 greath, 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 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 +1267,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

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

[Simon Tournier]

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!

> Are maintainers open to add some section like this to the manual?

I am not maintainer and I have nothing against. :-)

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


> --- 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.

> +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

> +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

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

> +
> +@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

> +@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?


Cheers,
simon

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

[Ekaitz Zarraga]

[-- 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

Re: RFC: add more setups to Guix docs

[Ludovic Courtès]

Hi,

Ekaitz Zarraga <ekaitz@elenq.tech> skribis:

> 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

Not a maintainer either but I like it!

>  
> +@node Alternative Setups
> +

I think you’re missing an @section here.

> +@node Vim and NeoVim
> +@subsection Vim and Neovim

Which spelling is the right one?  :-)

Maybe send it to guix-patches@gnu.org so it passes on everyone’s radar,
but otherwise LGTM!

Ludo’.