[bug#60582] [PATCH] Properly format list of packages & sync lightdm documentation.

[bug#60582] [PATCH] Properly format list of packages & sync lightdm documentation.

[Bruno Victal]

The first patch allows generate-documentation to properly format a list of packages.
Previously these had to be cleaned up by hand which was error-prone.

Sample snippets:

Before:

--8<---------------cut here---------------start------------->8---
@item @code{assets} (default: @code{(#<package adwaita-icon-theme@@42.0 gnu/packages/gnome.scm:2870 7f018c9fd630> #<package gnome-themes-extra@@3.28 gnu/packages/gnome.scm:12233 7f018ca2f0b0> #<package hicolor-icon-theme@@0.17 gnu/packages/gnome.scm:3042 7f018c9fd2c0>)}) (type: list-of-file-likes)
--8<---------------cut here---------------end--------------->8---

After:

--8<---------------cut here---------------start------------->8---
@item @code{assets} (default: @code{(adwaita-icon-theme gnome-themes-extra hicolor-icon-theme)}) (type: list-of-file-likes)
--8<---------------cut here---------------end--------------->8---


The second patch syncs the documentation with the source code and fixes some mistakes.



Bruno Victal (2):
  services: configuration: Format a list of packages by their names.
  services: lightdm: Sync documentation with source.

 doc/guix.texi                  | 4 ++--
 gnu/services/configuration.scm | 3 +++
 gnu/services/lightdm.scm       | 2 +-
 3 files changed, 6 insertions(+), 3 deletions(-)


base-commit: 80902fc210d8dc28e14d63d68f398aef796b5838
-- 
2.38.1

[bug#60582] [PATCH 1/2] services: configuration: Format a list of packages by their names.

[Bruno Victal]

* gnu/services/configuration.scm
(generate-documentation): Format a list of packages by their names.
---
 gnu/services/configuration.scm | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm
index 6b0291dc00..16e2380709 100644
--- a/gnu/services/configuration.scm
+++ b/gnu/services/configuration.scm
@@ -370,6 +370,9 @@ (define (show-default val)
                      (cond
                       ((package? val)
                        (symbol->string (package->symbol val)))
+                      ((and ((list-of package?) val) (not (null? val)))
+                       (format #f "(~{~a~^ ~})"
+                        (map package->symbol val)))
                       (else (str val))))
 
                    `(entry (% (heading
-- 
2.38.1

[bug#60582] [PATCH 2/2] services: lightdm: Sync documentation with source.

[Bruno Victal]

* gnu/services/lightdm.scm
(lightdm-gtk-greeter-configuration): Fix cursor-theme-size description.
* doc/guix.texi (lightdm-service-type): Sync with source.
---
 doc/guix.texi            | 4 ++--
 gnu/services/lightdm.scm | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 32e34b7d52..bb0d276b32 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -21733,7 +21733,7 @@ disable security:
 @end lisp
 
 Or to set a PasswordFile for the classic (unsecure) VncAuth
-mecanism:
+mechanism:
 
 @lisp
 (vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
@@ -21770,7 +21770,7 @@ Available @code{lightdm-gtk-greeter-configuration} fields are:
 The lightdm-gtk-greeter package to use.
 
 @item @code{assets} @
-(default: @code{(adwaita-icon-theme gnome-themes-extrahicolor-icon-theme)}) @
+(default: @code{(adwaita-icon-theme gnome-themes-extra hicolor-icon-theme)}) @
 (type: list-of-file-likes)
 The list of packages complementing the greeter, such as package
 providing icon themes.
diff --git a/gnu/services/lightdm.scm b/gnu/services/lightdm.scm
index 7e3864fec2..0b9094cda1 100644
--- a/gnu/services/lightdm.scm
+++ b/gnu/services/lightdm.scm
@@ -151,7 +151,7 @@ (define-configuration lightdm-gtk-greeter-configuration
    "The name of the cursor theme to use.")
   (cursor-theme-size
    (number 16)
-   "The size to use for the the cursor theme.")
+   "The size to use for the cursor theme.")
   (allow-debugging?
    maybe-boolean
    "Set to #t to enable debug log level.")
-- 
2.38.1

[bug#60582] [PATCH v2 1/2] services: configuration: Format a list of packages by their names.

[Bruno Victal]

* gnu/services/configuration.scm
(generate-documentation): Format a list of packages by their names.
---
 gnu/services/configuration.scm | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm
index 6b0291dc00..482b49aae4 100644
--- a/gnu/services/configuration.scm
+++ b/gnu/services/configuration.scm
@@ -35,6 +35,7 @@ (define-module (gnu services configuration)
   #:autoload   (texinfo serialize) (stexi->texi)
   #:use-module (ice-9 curried-definitions)
   #:use-module (ice-9 match)
+  #:use-module (ice-9 format)
   #:use-module (srfi srfi-1)
   #:use-module (srfi srfi-34)
   #:use-module (srfi srfi-35)
@@ -370,6 +371,9 @@ (define (show-default val)
                      (cond
                       ((package? val)
                        (symbol->string (package->symbol val)))
+                      ((and ((list-of package?) val) (not (null? val)))
+                       (format #f "(~{~a~^ ~})"
+                        (map package->symbol val)))
                       (else (str val))))
 
                    `(entry (% (heading

base-commit: a768b0433e0b79c5a32910ce5515086b92725e84
-- 
2.38.1

[bug#60582] [PATCH v2 2/2] services: lightdm: Sync documentation with source.

[Bruno Victal]

Table entry @item nodes cannot span multiple lines.

* gnu/services/lightdm.scm
(lightdm-gtk-greeter-configuration): Fix cursor-theme-size description.
* doc/guix.texi (lightdm-service-type): Sync with source.
---
 doc/guix.texi            | 12 ++++--------
 gnu/services/lightdm.scm |  2 +-
 2 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 293c3016aa..8fc4ec5640 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -21798,7 +21798,7 @@ disable security:
 @end lisp
 
 Or to set a PasswordFile for the classic (unsecure) VncAuth
-mecanism:
+mechanism:
 
 @lisp
 (vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
@@ -21834,9 +21834,7 @@ Available @code{lightdm-gtk-greeter-configuration} fields are:
 @item @code{lightdm-gtk-greeter} (default: @code{lightdm-gtk-greeter}) (type: file-like)
 The lightdm-gtk-greeter package to use.
 
-@item @code{assets} @
-(default: @code{(adwaita-icon-theme gnome-themes-extrahicolor-icon-theme)}) @
-(type: list-of-file-likes)
+@item @code{assets} (default: @code{(adwaita-icon-theme gnome-themes-extra hicolor-icon-theme)}) (type: list-of-file-likes)
 The list of packages complementing the greeter, such as package
 providing icon themes.
 
@@ -21862,8 +21860,7 @@ The background image to use.
 Enable accessibility support through the Assistive Technology Service
 Provider Interface (AT-SPI).
 
-@item @code{a11y-states} @
-(default: @code{(contrast font keyboard reader)}) (type: list-of-a11y-states)
+@item @code{a11y-states} (default: @code{(contrast font keyboard reader)}) (type: list-of-a11y-states)
 The accessibility features to enable, given as list of symbols.
 
 @item @code{reader} (type: maybe-file-like)
@@ -21897,8 +21894,7 @@ The type of the seat, either the @code{local} or @code{xremote} symbol.
 @item @code{autologin-user} (type: maybe-string)
 The username to automatically log in with by default.
 
-@item @code{greeter-session} @
-(default: @code{lightdm-gtk-greeter}) (type: greeter-session)
+@item @code{greeter-session} (default: @code{lightdm-gtk-greeter}) (type: greeter-session)
 The greeter session to use, specified as a symbol.  Currently, only
 @code{lightdm-gtk-greeter} is supported.
 
diff --git a/gnu/services/lightdm.scm b/gnu/services/lightdm.scm
index 7e3864fec2..0b9094cda1 100644
--- a/gnu/services/lightdm.scm
+++ b/gnu/services/lightdm.scm
@@ -151,7 +151,7 @@ (define-configuration lightdm-gtk-greeter-configuration
    "The name of the cursor theme to use.")
   (cursor-theme-size
    (number 16)
-   "The size to use for the the cursor theme.")
+   "The size to use for the cursor theme.")
   (allow-debugging?
    maybe-boolean
    "Set to #t to enable debug log level.")
-- 
2.38.1

[bug#60582] [PATCH] Properly format list of packages & sync lightdm documentation.

[Maxim Cournoyer]

Hi,

Bruno Victal <mirai@makinata.eu> writes:

> * gnu/services/configuration.scm
> (generate-documentation): Format a list of packages by their names.
> ---
>  gnu/services/configuration.scm | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm
> index 6b0291dc00..16e2380709 100644
> --- a/gnu/services/configuration.scm
> +++ b/gnu/services/configuration.scm
> @@ -370,6 +370,9 @@ (define (show-default val)
>                       (cond
>                        ((package? val)
>                         (symbol->string (package->symbol val)))
> +                      ((and ((list-of package?) val) (not (null? val)))
> +                       (format #f "(~{~a~^ ~})"
> +                        (map package->symbol val)))

The 'and' and (not (null? val)) don't seem to be necessary as in the
empty list of packages, it'd produce the same as the else clause below:

--8<---------------cut here---------------start------------->8---
scheme@(gnu services configuration)> (format #f "(~{~a~^ ~})" '())
$1 = "()"
scheme@(gnu services configuration)> (str '())
$2 = "()"
--8<---------------cut here---------------end--------------->8---

>                        (else (str val))))
>  
>                     `(entry (% (heading

-- 
Thanks,
Maxim

[bug#60582] [PATCH] Properly format list of packages & sync lightdm documentation.

[Bruno Victal]

On 2023-01-13 20:29, Maxim Cournoyer wrote:
> Hi,
> 
> Bruno Victal <mirai@makinata.eu> writes:
> 
>> * gnu/services/configuration.scm
>> (generate-documentation): Format a list of packages by their names.
>> ---
>>  gnu/services/configuration.scm | 3 +++
>>  1 file changed, 3 insertions(+)
>>
>> diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm
>> index 6b0291dc00..16e2380709 100644
>> --- a/gnu/services/configuration.scm
>> +++ b/gnu/services/configuration.scm
>> @@ -370,6 +370,9 @@ (define (show-default val)
>>                       (cond
>>                        ((package? val)
>>                         (symbol->string (package->symbol val)))
>> +                      ((and ((list-of package?) val) (not (null? val)))
>> +                       (format #f "(~{~a~^ ~})"
>> +                        (map package->symbol val)))
> 
> The 'and' and (not (null? val)) don't seem to be necessary as in the
> empty list of packages, it'd produce the same as the else clause below:
> 
> --8<---------------cut here---------------start------------->8---
> scheme@(gnu services configuration)> (format #f "(~{~a~^ ~})" '())
> $1 = "()"
> scheme@(gnu services configuration)> (str '())
> $2 = "()"
> --8<---------------cut here---------------end--------------->8---
> 
>>                        (else (str val))))
>>  
>>                     `(entry (% (heading
> 

It is necessary for non file-like fields whose default value is '().
Otherwise configuration->documentation will show blank spaces when it should show an empty list.


Cheers,
Bruno

[bug#60582] [PATCH v3 1/2] services: configuration: Format a list of packages by their names.

[Bruno Victal]

* gnu/services/configuration.scm
(generate-documentation): Format a list of packages by their names.
---

Simplified condition.

I can't reproduce the issue that was supposed to be resolved by that conditional.
I'm guessing I used to have a different format string back then.

 gnu/services/configuration.scm | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm
index 6b0291dc00..4017cd0fa8 100644
--- a/gnu/services/configuration.scm
+++ b/gnu/services/configuration.scm
@@ -35,6 +35,7 @@ (define-module (gnu services configuration)
   #:autoload   (texinfo serialize) (stexi->texi)
   #:use-module (ice-9 curried-definitions)
   #:use-module (ice-9 match)
+  #:use-module (ice-9 format)
   #:use-module (srfi srfi-1)
   #:use-module (srfi srfi-34)
   #:use-module (srfi srfi-35)
@@ -370,6 +371,8 @@ (define (generate-documentation documentation documentation-name)
                      (cond
                       ((package? val)
                        (symbol->string (package->symbol val)))
+                      (((list-of package?) val)
+                       (format #f "(~{~a~^ ~})" (map package->symbol val)))
                       (else (str val))))
 
                    `(entry (% (heading

base-commit: 0f85081ed1d99be57d3544e0307e7fa9ca043be9
-- 
2.38.1

[bug#60582] [PATCH v3 2/2] services: lightdm: Sync documentation with source.

[Bruno Victal]

Table entry @item nodes cannot span multiple lines.

* gnu/services/lightdm.scm
(lightdm-gtk-greeter-configuration): Fix cursor-theme-size description.
* doc/guix.texi (lightdm-service-type): Sync with source.
---
 doc/guix.texi            | 12 ++++--------
 gnu/services/lightdm.scm |  2 +-
 2 files changed, 5 insertions(+), 9 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 751d0957d8..9c369bd881 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -21818,7 +21818,7 @@ X Window
 @end lisp
 
 Or to set a PasswordFile for the classic (unsecure) VncAuth
-mecanism:
+mechanism:
 
 @lisp
 (vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
@@ -21854,9 +21854,7 @@ X Window
 @item @code{lightdm-gtk-greeter} (default: @code{lightdm-gtk-greeter}) (type: file-like)
 The lightdm-gtk-greeter package to use.
 
-@item @code{assets} @
-(default: @code{(adwaita-icon-theme gnome-themes-extrahicolor-icon-theme)}) @
-(type: list-of-file-likes)
+@item @code{assets} (default: @code{(adwaita-icon-theme gnome-themes-extra hicolor-icon-theme)}) (type: list-of-file-likes)
 The list of packages complementing the greeter, such as package
 providing icon themes.
 
@@ -21882,8 +21880,7 @@ X Window
 Enable accessibility support through the Assistive Technology Service
 Provider Interface (AT-SPI).
 
-@item @code{a11y-states} @
-(default: @code{(contrast font keyboard reader)}) (type: list-of-a11y-states)
+@item @code{a11y-states} (default: @code{(contrast font keyboard reader)}) (type: list-of-a11y-states)
 The accessibility features to enable, given as list of symbols.
 
 @item @code{reader} (type: maybe-file-like)
@@ -21917,8 +21914,7 @@ X Window
 @item @code{autologin-user} (type: maybe-string)
 The username to automatically log in with by default.
 
-@item @code{greeter-session} @
-(default: @code{lightdm-gtk-greeter}) (type: greeter-session)
+@item @code{greeter-session} (default: @code{lightdm-gtk-greeter}) (type: greeter-session)
 The greeter session to use, specified as a symbol.  Currently, only
 @code{lightdm-gtk-greeter} is supported.
 
diff --git a/gnu/services/lightdm.scm b/gnu/services/lightdm.scm
index 7e3864fec2..0b9094cda1 100644
--- a/gnu/services/lightdm.scm
+++ b/gnu/services/lightdm.scm
@@ -151,7 +151,7 @@ (define-configuration lightdm-gtk-greeter-configuration
    "The name of the cursor theme to use.")
   (cursor-theme-size
    (number 16)
-   "The size to use for the the cursor theme.")
+   "The size to use for the cursor theme.")
   (allow-debugging?
    maybe-boolean
    "Set to #t to enable debug log level.")
-- 
2.38.1

[bug#60582] [PATCH] Properly format list of packages & sync lightdm documentation.

[Maxim Cournoyer]

Hello,

Bruno Victal <mirai@makinata.eu> writes:

> Table entry @item nodes cannot span multiple lines.

So it needed some manual fix-up?  Good to know; working toward
automating the expansion of the auto-generated parts in the manual,
we'll have to figure that.  Future work!

LGTM.

-- 
Thanks,
Maxim

bug#60582: [PATCH] Properly format list of packages & sync lightdm documentation.

[Maxim Cournoyer]

Hello!

I merged this series as 8a2c2eaa90.

Thank you!

-- 
Maxim

[bug#60582] [PATCH] Properly format list of packages & sync lightdm documentation.

[Bruno Victal]

On 2023-02-09 03:39, Maxim Cournoyer wrote:
> Bruno Victal <mirai@makinata.eu> writes:
> 
>> Table entry @item nodes cannot span multiple lines.
> 
> So it needed some manual fix-up?  Good to know; working toward
> automating the expansion of the auto-generated parts in the manual,
> we'll have to figure that.  Future work!

The automatic expansion works correctly, this was an error from manually fixing up the previous entries when
`generate-documentation' couldn't handle lists of package objects.


Cheers,
Bruno

[bug#60582] [PATCH] Properly format list of packages & sync lightdm documentation.

[Maxim Cournoyer]

hi,

Bruno Victal <mirai@makinata.eu> writes:

> On 2023-02-09 03:39, Maxim Cournoyer wrote:
>> Bruno Victal <mirai@makinata.eu> writes:
>> 
>>> Table entry @item nodes cannot span multiple lines.
>> 
>> So it needed some manual fix-up?  Good to know; working toward
>> automating the expansion of the auto-generated parts in the manual,
>> we'll have to figure that.  Future work!
>
> The automatic expansion works correctly, this was an error from
> manually fixing up the previous entries when
> `generate-documentation' couldn't handle lists of package objects.

I see, thanks for the explanation!

-- 
Thanks,
Maxim