[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