[bug#51538] First Patch Submit Ever: Additions to the Cookbook Documentation

[bug#51538] First Patch Submit Ever: Additions to the Cookbook Documentation

[Disseminate Dissent via Guix-patches via]

[-- Attachment #1.1: Type: text/plain, Size: 222 bytes --]

Hey there, taking my first step into a larger world.

Attached is just a patch to the GNU Guix Cookbook that adds a FAQ with it's first entry. The ToC will need to be edited in order to reflect that though.

Peace,
Dissent

[-- Attachment #1.2: Type: text/html, Size: 307 bytes --]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-Added-FAQ-section-with-entry-on-using-clear.patch --]
[-- Type: text/x-patch; name=0001-doc-Added-FAQ-section-with-entry-on-using-clear.patch, Size: 1217 bytes --]

From 9af25ebde3baaa76b28bbde97bc48640476911f5 Mon Sep 17 00:00:00 2001
From: dissent <disseminatedissent@protonmail.com>
Date: Sat, 30 Oct 2021 17:00:02 -0400
Subject: [PATCH] doc: Added FAQ section with entry on using clear.

* doc/guix-cookbook.texi: Added FAQ section.
---
 doc/guix-cookbook.texi | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index dc52f6d38c..bdbf83f900 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -2964,6 +2964,21 @@ will have predefined environment variables and procedures.
 
 Run @command{direnv allow} to setup the environment for the first time.
 
+@c *********************************************************************
+@node FAQ
+@chapter FAQ
+
+This chapter collects some frequently asked questions that might arise for new users.
+
+@menu
+* How do I clear my terminal screen?
+@end menu
+
+@node How do I clear my terminal screen?
+@section How do I clear my terminal screen?
+
+The @command{clear} command is found in the @command{ncurses} package. 
+
 @c *********************************************************************
 @node Acknowledgments
 @chapter Acknowledgments
-- 
2.20.1

[bug#51538] TOC

[jgart via Guix-patches via]

Hi Dissent,

Great to see that you sent the patch that we worked on from the guix packaging meetup.

To add more stuff to your commit I recommend the following workflow:

1. Make additional changes to the cookbook file.

2. guix shell texi2html -- texi2html doc/guix-cookbook.texi

3. Open and check the generated html file with your web browser.

4. git add doc/guix-cookbook.texi

5. git commit --amend --no-edit

6. git format-patch -1

7. email patch again to 51538@debbugs.gnu.org

With the above workflow I recommend adding an entry in the TOC for the FAQ section.

Note that `git format-patch -1` only takes the last commit so if you add more commits you'll need to adjust that command.

`git commit --amend --no-edit` does not open your editor to modify your commit message. If you'd like to then remove `--no-edit`.

Another guix contributor might prefer that section to be called something else or not so let's wait to hear from others.

I don't have commit access so someone else will have to review your changes also and merge them.

all best,

jgart

[bug#51538] First Patch Submit Ever: Additions to the Cookbook Documentation

[Disseminate Dissent via Guix-patches via]

[-- Attachment #1.1: Type: text/plain, Size: 512 bytes --]

Fixed the previous commit by adding the corresponding ToC heading to the new FAQ section.

Disseminate, Peace.

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Sunday, October 31st, 2021 at 11:56 PM, Disseminate Dissent <disseminatedissent@protonmail.com> wrote:

> Hey there, taking my first step into a larger world.
>
> Attached is just a patch to the GNU Guix Cookbook that adds a FAQ with it's first entry. The ToC will need to be edited in order to reflect that though.
>
> Peace,
> Dissent

[-- Attachment #1.2: Type: text/html, Size: 921 bytes --]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-Added-FAQ-section-with-entry-on-using-clear.patch --]
[-- Type: text/x-patch; name=0001-doc-Added-FAQ-section-with-entry-on-using-clear.patch, Size: 1642 bytes --]

From fce239a311724e38987640af02127179d569d88e Mon Sep 17 00:00:00 2001
From: dissent <disseminatedissent@protonmail.com>
Date: Sat, 30 Oct 2021 17:00:02 -0400
Subject: [PATCH] doc: Added FAQ section with entry on using clear.

* doc/guix-cookbook.texi: Added FAQ section.
---
 doc/guix-cookbook.texi | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index dc52f6d38c..14c55926c2 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -70,6 +70,7 @@ Weblate} (@pxref{Translating Guix,,, guix, GNU Guix reference manual}).
 * System Configuration::        Customizing the GNU System
 * Advanced package management:: Power to the users!
 * Environment management::      Control environment
+* FAQ::                         Commonly asked questions
 
 * Acknowledgments::             Thanks!
 * GNU Free Documentation License::  The license of this document.
@@ -2964,6 +2965,21 @@ will have predefined environment variables and procedures.
 
 Run @command{direnv allow} to setup the environment for the first time.
 
+@c *********************************************************************
+@node FAQ
+@chapter FAQ
+
+This chapter collects some frequently asked questions that might arise for new users.
+
+@menu
+* How do I clear my terminal screen?
+@end menu
+
+@node How do I clear my terminal screen?
+@section How do I clear my terminal screen?
+
+The @command{clear} command is found in the @command{ncurses} package. 
+
 @c *********************************************************************
 @node Acknowledgments
 @chapter Acknowledgments
-- 
2.33.1

[bug#51538] First Patch Submit Ever: Additions to the Cookbook Documentation

[pelzflorian (Florian Pelz)]

Hello Disseminate.

On Thu, Nov 04, 2021 at 03:17:48PM +0000, Disseminate Dissent via Guix-patches via wrote:
> Fixed the previous commit by adding the corresponding ToC heading to the new FAQ section.
> 
> Disseminate, Peace.

Thank you for your contribution!  It is good you add what you are
missing.  I’d prefer if someone else commented, though here are my
thoughts.  A FAQ seems like a good idea, however see below.


On Thu, Nov 04, 2021 at 03:17:48PM +0000, Disseminate Dissent via Guix-patches via wrote:
> From fce239a311724e38987640af02127179d569d88e Mon Sep 17 00:00:00 2001
> From: dissent <disseminatedissent@protonmail.com>
> Date: Sat, 30 Oct 2021 17:00:02 -0400
> Subject: [PATCH] doc: Added FAQ section with entry on using clear.

For the commit message, Guix uses the active voice “Add a FAQ section
with …”.


> * doc/guix-cookbook.texi: Added FAQ section.

Here too.


> ---
>  doc/guix-cookbook.texi | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)
> 
> diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
> index dc52f6d38c..14c55926c2 100644
> --- a/doc/guix-cookbook.texi
> +++ b/doc/guix-cookbook.texi
> @@ -70,6 +70,7 @@ Weblate} (@pxref{Translating Guix,,, guix, GNU Guix reference manual}).
>  * System Configuration::        Customizing the GNU System
>  * Advanced package management:: Power to the users!
>  * Environment management::      Control environment
> +* FAQ::                         Commonly asked questions
>  
>  * Acknowledgments::             Thanks!
>  * GNU Free Documentation License::  The license of this document.

Menu comments like “Commonly asked questions” usually end in a period,
although the surrounding menu comments are missing the period as well.
Could you add a period for “Commonly asked questions”?  But see below.


> @@ -2964,6 +2965,21 @@ will have predefined environment variables
and procedures.
>  
>  Run @command{direnv allow} to setup the environment for the first time.
>  
> +@c *********************************************************************
> +@node FAQ
> +@chapter FAQ
> +
> +This chapter collects some frequently asked questions that might arise for new users.
> +
> +@menu
> +* How do I clear my terminal screen?
> +@end menu
> +
> +@node How do I clear my terminal screen?
> +@section How do I clear my terminal screen?
> +
> +The @command{clear} command is found in the @command{ncurses} package. 
> +
>  @c *********************************************************************
>  @node Acknowledgments
>  @chapter Acknowledgments
> -- 
> 2.33.1

I am uncertain if this tip should be in the cookbook, because I think
GNU Bash’s C-l (control+L) keyboard shortcutis easier to use and is
available in a default setup.  (Actually it may be GNU Readline’s
keyboard shortcut and Bash just uses Readline?)

Now indeed users may not know about it.  I do not know how to help
Guix users learn about features of programs that Guix offers but are
not part of Guix.


Nitpick: you have added an unnecessary space character at the end of the line

> +The @command{clear} command is found in the @command{ncurses} package. 

You should configure your editor to display those.

Regards,
Florian

[bug#51538] First Patch Submit Ever: Additions to the Cookbook Documentation

[pelzflorian (Florian Pelz)]

P.S. I tried your patch with the commands described by `info
"(guix)Building from Git"` and I get the following error:

./doc/guix-cookbook.texi:2978: warning: node `FAQ' is up for `How do I clear my terminal screen?' in sectioning but not in menu
./doc/guix-cookbook.texi:2969: node `FAQ' lacks menu item for `How do I clear my terminal screen?' despite being its Up target
make[2]: *** [Makefile:5331: doc/guix-cookbook.info] Error 1
make[1]: *** [Makefile:6268: all-recursive] Error 1
make: *** [Makefile:3916: all] Error 2

I’m not sure what that means, but please test building it before you
submit a patch.

Regards,
Florian

[bug#51538] First Patch Submit Ever: Additions to the Cookbook Documentation

[Disseminate Dissent via Guix-patches via]

[-- Attachment #1.1: Type: text/plain, Size: 761 bytes --]

Corrected missing periods and whitespace.

Disseminate,
Peace

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Thursday, November 4th, 2021 at 3:17 PM, Disseminate Dissent <disseminatedissent@protonmail.com> wrote:

> Fixed the previous commit by adding the corresponding ToC heading to the new FAQ section.
>
> Disseminate, Peace.
>
> ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
> On Sunday, October 31st, 2021 at 11:56 PM, Disseminate Dissent <disseminatedissent@protonmail.com> wrote:
>
>> Hey there, taking my first step into a larger world.
>>
>> Attached is just a patch to the GNU Guix Cookbook that adds a FAQ with it's first entry. The ToC will need to be edited in order to reflect that though.
>>
>> Peace,
>> Dissent

[-- Attachment #1.2: Type: text/html, Size: 1598 bytes --]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-Add-a-FAQ-section-with-entry-on-using-clear.patch --]
[-- Type: text/x-patch; name=0001-doc-Add-a-FAQ-section-with-entry-on-using-clear.patch, Size: 1963 bytes --]

From 66947f766c59a1ecbf7cb1fc91f404653e74d7e5 Mon Sep 17 00:00:00 2001
From: dissent <disseminatedissent@protonmail.com>
Date: Sat, 30 Oct 2021 17:00:02 -0400
Subject: [PATCH] doc: Add a FAQ section with entry on using clear.

* doc/guix-cookbook.texi: Added FAQ section.
---
 doc/guix-cookbook.texi | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index dc52f6d38c..0718a6711d 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -66,10 +66,11 @@ Weblate} (@pxref{Translating Guix,,, guix, GNU Guix reference manual}).
 
 @menu
 * Scheme tutorials::            Meet your new favorite language!
-* Packaging::                   Packaging tutorials
-* System Configuration::        Customizing the GNU System
+* Packaging::                   Packaging tutorials.
+* System Configuration::        Customizing the GNU System.
 * Advanced package management:: Power to the users!
-* Environment management::      Control environment
+* Environment management::      Control environment.
+* FAQ::                         Commonly asked questions.
 
 * Acknowledgments::             Thanks!
 * GNU Free Documentation License::  The license of this document.
@@ -2964,6 +2965,21 @@ will have predefined environment variables and procedures.
 
 Run @command{direnv allow} to setup the environment for the first time.
 
+@c *********************************************************************
+@node FAQ
+@chapter FAQ
+
+This chapter collects some frequently asked questions that might arise for new users.
+
+@menu
+* How do I clear my terminal screen?
+@end menu
+
+@node How do I clear my terminal screen?
+@section How do I clear my terminal screen?
+
+The @command{clear} command is found in the @command{ncurses} package.
+
 @c *********************************************************************
 @node Acknowledgments
 @chapter Acknowledgments
-- 
2.33.1

[bug#51538] First Patch Submit Ever: Additions to the Cookbook Documentation

[pelzflorian (Florian Pelz)]

Disseminate, thank you for your work.

On Mon, Nov 08, 2021 at 01:48:39PM +0000, Disseminate Dissent wrote:
> Thanks for the comments Florian,
> 
> Added periods and removed whitespace.
> 
> In my initial Guix setup I was unable to clear the terminal with
> neither `clear` nor C-l. Installing ncurses solved that issue and is
> listed as a dependency for GNU Readline.

Bash always enables readline as far as I can see.  Perhaps you used a
system that disabled C-l in the ~/.inputrc file, which would also
disable it for a Guix-installed bash?  Some Slackware users complain
about non-working C-l on stackoverflow.  Anyway I will leave this
patch for experienced guix commiters to decide; IMHO the clear command
should not be needed with Guix and the cookbook so far contains only
what can be done with Guix itself.  Even though I like the idea of a
FAQ section and am happy about new Guix contributors such as you.

As for the patch:

On Mon, Nov 08, 2021 at 01:50:20PM +0000, Disseminate Dissent via Guix-patches via wrote:
> Corrected missing periods and whitespace.
>

You have not addressed this latter passive Added instead of Add:

On Mon, Nov 08, 2021 at 10:29:00AM +0100, pelzflorian (Florian Pelz) wrote:
> For the commit message, Guix uses the active voice “Add a FAQ section
> with …”.
> 
> 
> > * doc/guix-cookbook.texi: Added FAQ section.
> 
> Here too.

Then:

On Mon, Nov 08, 2021 at 01:50:20PM +0000, Disseminate Dissent via Guix-patches via wrote:
>  @menu
>  * Scheme tutorials::            Meet your new favorite language!
> -* Packaging::                   Packaging tutorials
> -* System Configuration::        Customizing the GNU System
> +* Packaging::                   Packaging tutorials.
> +* System Configuration::        Customizing the GNU System.
>  * Advanced package management:: Power to the users!
> -* Environment management::      Control environment
> +* Environment management::      Control environment.
> +* FAQ::                         Commonly asked questions.

Your commit should only add the period to your sentence; other
sentences should remain untouched (fixing them belongs in a separate
commit).  I should fix such things myself in other commits; probably I
won’t do it.

Other than that, it is a nicely written patch.

It seems the issue when running the commands from
`info "(guix)Building from Git"` is that the other menu

> +@menu
> +* How do I clear my terminal screen?
> +@end menu

does not contain double colons followed by a sentence like the other
@menu.

Regards,
Florian

[bug#51538] First Patch Submit Ever: Additions to the Cookbook Documentation

[Julien Lepiller]

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

I think this is fine. The cookbook should recommend using Ctrl-L and suggest you can install clear with the ncurses package. We get that question from time to time, so I think it belongs to a FAQ :)

Le 8 novembre 2021 12:18:50 GMT-05:00, "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> a écrit :
>Disseminate, thank you for your work.
>
>On Mon, Nov 08, 2021 at 01:48:39PM +0000, Disseminate Dissent wrote:
>> Thanks for the comments Florian,
>> 
>> Added periods and removed whitespace.
>> 
>> In my initial Guix setup I was unable to clear the terminal with
>> neither `clear` nor C-l. Installing ncurses solved that issue and is
>> listed as a dependency for GNU Readline.
>
>Bash always enables readline as far as I can see.  Perhaps you used a
>system that disabled C-l in the ~/.inputrc file, which would also
>disable it for a Guix-installed bash?  Some Slackware users complain
>about non-working C-l on stackoverflow.  Anyway I will leave this
>patch for experienced guix commiters to decide; IMHO the clear command
>should not be needed with Guix and the cookbook so far contains only
>what can be done with Guix itself.  Even though I like the idea of a
>FAQ section and am happy about new Guix contributors such as you.
>
>As for the patch:
>
>On Mon, Nov 08, 2021 at 01:50:20PM +0000, Disseminate Dissent via Guix-patches via wrote:
>> Corrected missing periods and whitespace.
>>
>
>You have not addressed this latter passive Added instead of Add:
>
>On Mon, Nov 08, 2021 at 10:29:00AM +0100, pelzflorian (Florian Pelz) wrote:
>> For the commit message, Guix uses the active voice “Add a FAQ section
>> with …”.
>> 
>> 
>> > * doc/guix-cookbook.texi: Added FAQ section.
>> 
>> Here too.
>
>Then:
>
>On Mon, Nov 08, 2021 at 01:50:20PM +0000, Disseminate Dissent via Guix-patches via wrote:
>>  @menu
>>  * Scheme tutorials::            Meet your new favorite language!
>> -* Packaging::                   Packaging tutorials
>> -* System Configuration::        Customizing the GNU System
>> +* Packaging::                   Packaging tutorials.
>> +* System Configuration::        Customizing the GNU System.
>>  * Advanced package management:: Power to the users!
>> -* Environment management::      Control environment
>> +* Environment management::      Control environment.
>> +* FAQ::                         Commonly asked questions.
>
>Your commit should only add the period to your sentence; other
>sentences should remain untouched (fixing them belongs in a separate
>commit).  I should fix such things myself in other commits; probably I
>won’t do it.
>
>Other than that, it is a nicely written patch.
>
>It seems the issue when running the commands from
>`info "(guix)Building from Git"` is that the other menu
>
>> +@menu
>> +* How do I clear my terminal screen?
>> +@end menu
>
>does not contain double colons followed by a sentence like the other
>@menu.
>
>Regards,
>Florian
>
>
>
>

[-- Attachment #2: Type: text/html, Size: 4070 bytes --]

[bug#51538] First Patch Submit Ever: Additions to the Cookbook Documentation

[pelzflorian (Florian Pelz)]

On Mon, Nov 08, 2021 at 02:04:12PM -0500, Julien Lepiller wrote:
> Le 8 novembre 2021 12:18:50 GMT-05:00, "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> a écrit :
> >Bash always enables readline as far as I can see.  Perhaps you used a
> >system that disabled C-l in the ~/.inputrc file, which would also
> >disable it for a Guix-installed bash?  Some Slackware users complain
> >about non-working C-l on stackoverflow.  Anyway I will leave this
> >patch for experienced guix commiters to decide; IMHO the clear command
> >should not be needed with Guix and the cookbook so far contains only
> >what can be done with Guix itself.  Even though I like the idea of a
> >FAQ section and am happy about new Guix contributors such as you.
> I think this is fine. The cookbook should recommend using Ctrl-L and
> suggest you can install clear with the ncurses package. We get that
> question from time to time, so I think it belongs to a FAQ :)

One might expect terminal clearing with C-l or clear in an operating
system manual, but is role of Guix to be an operating system?

I’d think not, the manual/cookbook would blow up too much.

A command to search what package provides the program clear is what
belongs in the manual.

Regards,
Florian

[bug#51538] First Patch Submit Ever: Additions to the Cookbook Documentation

[Disseminate Dissent via Guix-patches via]

Thanks for the comments Florian,

Added periods and removed whitespace.

In my initial Guix setup I was unable to clear the terminal with neither `clear` nor C-l. Installing ncurses solved that issue and is listed as a dependency for GNU Readline.

I was able to build the html just fine before I submitted it. Upon rebuilding, the html appears fine but still getting those errors. I then decided to just clone the guix repo again without making any changes to the .texi but attempting to create the html still produced those errors.

It seems this is the issue:
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.32), passed through in regex; marked by <-- HERE in m/^\s+@([^\s\{\}\@]+)({ <-- HERE })?\s*/ at /gnu/store/nxqw880l3r5z0dl6nrlf75mr0z0v70vp-profile/bin/texi2html line 33246.

Not sure how to proceed from here.

The new patch has been submited

Disseminate,
Peace

[bug#51538] (no subject)

[jgart via Guix-patches via]

I just wanted to mention that roptat added a nice entry for texinfo in learnxinyminutes series of sites:

https://github.com/adambard/learnxinyminutes-docs/pull/4263

Hopefully it will get merged soon.

I think this will help with lowering the barrier to entry for learning Texinfo as well as serve as a quick TLDR reference.