GNU bug report logs - #51538
First Patch Submit Ever: Additions to the Cookbook Documentation

Previous Next

To reply to this bug, email your comments to 51538 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Disseminate Dissent <disseminatedissent <at> protonmail.com>
To: "guix-patches <at> gnu.org" <guix-patches <at> gnu.org>
Subject: First Patch Submit Ever: Additions to the Cookbook Documentation
Date: Sun, 31 Oct 2021 23:56:13 +0000

[Message part 1 (text/plain, inline)]

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

[Message part 2 (text/html, inline)]

[0001-doc-Added-FAQ-section-with-entry-on-using-clear.patch (text/x-patch, attachment)]

Message #8 received at 51538 <at> debbugs.gnu.org (full text, mbox):

From: jgart <jgart <at> dismail.de>
To: 51538 <at> debbugs.gnu.org
Subject: TOC
Date: Mon, 1 Nov 2021 11:10:12 -0400

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

Message #11 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Disseminate Dissent <disseminatedissent <at> protonmail.com>
To: "guix-patches <at> gnu.org" <guix-patches <at> gnu.org>
Subject: Re: First Patch Submit Ever: Additions to the Cookbook Documentation
Date: Thu, 04 Nov 2021 15:17:48 +0000

[Message part 1 (text/plain, inline)]

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

[Message part 2 (text/html, inline)]

[0001-doc-Added-FAQ-section-with-entry-on-using-clear.patch (text/x-patch, attachment)]

Message #14 received at 51538 <at> debbugs.gnu.org (full text, mbox):

From: "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>
To: Disseminate Dissent <disseminatedissent <at> protonmail.com>
Cc: 51538 <at> debbugs.gnu.org
Subject: Re: [bug#51538] First Patch Submit Ever: Additions to the Cookbook
 Documentation
Date: Mon, 8 Nov 2021 10:29:00 +0100

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

Message #17 received at 51538 <at> debbugs.gnu.org (full text, mbox):

From: "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>
To: Disseminate Dissent <disseminatedissent <at> protonmail.com>
Cc: 51538 <at> debbugs.gnu.org
Subject: Re: [bug#51538] First Patch Submit Ever: Additions to the Cookbook
 Documentation
Date: Mon, 8 Nov 2021 10:53:52 +0100

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

Message #20 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Disseminate Dissent <disseminatedissent <at> protonmail.com>
To: "guix-patches <at> gnu.org" <guix-patches <at> gnu.org>
Subject: Re: First Patch Submit Ever: Additions to the Cookbook Documentation
Date: Mon, 08 Nov 2021 13:50:20 +0000

[Message part 1 (text/plain, inline)]

Corrected missing periods and whitespace.

Disseminate,
Peace

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Thursday, November 4th, 2021 at 3:17 PM, Disseminate Dissent <disseminatedissent <at> 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 <at> 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

[Message part 2 (text/html, inline)]

[0001-doc-Add-a-FAQ-section-with-entry-on-using-clear.patch (text/x-patch, attachment)]

Message #23 received at 51538 <at> debbugs.gnu.org (full text, mbox):

From: Disseminate Dissent <disseminatedissent <at> protonmail.com>
To: "51538 <at> debbugs.gnu.org" <51538 <at> debbugs.gnu.org>
Subject: First Patch Submit Ever: Additions to the Cookbook Documentation
Date: Mon, 08 Nov 2021 13:52:20 +0000

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

Message #26 received at 51538 <at> debbugs.gnu.org (full text, mbox):

From: "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>
To: Disseminate Dissent <disseminatedissent <at> protonmail.com>
Cc: 51538 <at> debbugs.gnu.org
Subject: Re: [bug#51538] First Patch Submit Ever: Additions to the Cookbook
 Documentation
Date: Mon, 8 Nov 2021 18:18:50 +0100

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

Message #29 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Julien Lepiller <julien <at> lepiller.eu>
To: guix-patches <at> gnu.org,
 "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>,
 Disseminate Dissent <disseminatedissent <at> protonmail.com>
Cc: 51538 <at> debbugs.gnu.org
Subject: Re: [bug#51538] First Patch Submit Ever: Additions to the Cookbook Documentation
Date: Mon, 08 Nov 2021 14:04:12 -0500

[Message part 1 (text/plain, inline)]

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

[Message part 2 (text/html, inline)]

Message #35 received at 51538 <at> debbugs.gnu.org (full text, mbox):

From: jgart <jgart <at> dismail.de>
To: 51538 <at> debbugs.gnu.org
Cc: Disseminate Dissent <disseminatedissent <at> protonmail.com>
Date: Mon, 8 Nov 2021 19:21:22 -0500

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.

Message #38 received at 51538 <at> debbugs.gnu.org (full text, mbox):

From: "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>
To: Julien Lepiller <julien <at> lepiller.eu>
Cc: Disseminate Dissent <disseminatedissent <at> protonmail.com>,
 51538 <at> debbugs.gnu.org
Subject: Re: [bug#51538] First Patch Submit Ever: Additions to the Cookbook
 Documentation
Date: Thu, 11 Nov 2021 18:04:06 +0100

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.