[bug#70228] [PATCH] doc: Update gnome-desktop-configuration.

[bug#70228] [PATCH] doc: Update gnome-desktop-configuration.

[Liliana Marie Prikler]

* doc/guix.texi (gnome-desktop-configuration): Fill in missing fields.
[gnome]: Talk about the deprecation.
---
Hi Guix,

this patch updates the gnome-desktop-configuration documentation,
that really ought to have been updated sooner.  It does not quite match
the auto-generated documentation, because I took some stylistic choices
and went further in some places.

There is IIRC already a bug report talking about this, but I cannot at
the top of my head recall its number.

Cheers

 doc/guix.texi | 36 ++++++++++++++++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index acfe60b47a..e856e95fb5 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -24818,10 +24818,42 @@ Desktop Services
 
 @deftp {Data Type} gnome-desktop-configuration
 Configuration record for the GNOME desktop environment.
+Available @code{gnome-desktop-configuration} fields are:
 
 @table @asis
-@item @code{gnome} (default: @code{gnome})
-The GNOME package to use.
+@item @code{core-services} (type: list-of-packages)
+A list of packages that the GNOME Shell and applications may rely on.
+
+@item @code{shell} (type: list-of-packages)
+A list of packages that constitute the GNOME Shell, without
+applications.
+
+@item @code{utilities} (type: list-of-packages)
+A list of packages that serve as applications to use on top of the GNOME Shell.
+
+@item @code{gnome} (type: maybe-package)
+This field used to be the only configuration point and specified
+a GNOME meta-package to install system-wide.  Since the meta-package
+itself provides neither sources nor the actual packages and is only
+used to propagate them, this field is deprecated.
+
+@item @code{extra-packages} (type: list-of-packages)
+A list of GNOME-adjacent packages to also include.  This field is
+intended for users to add their own packages to their GNOME experience.
+Note, that it already includes some packages that are considered
+essential by some (most?) GNOME users.
+
+@item @code{udev-ignorelist} (default: @code{()}) (type: list-of-strings)
+A list of regular expressions denoting udev rules or hardware file names
+provided by any package that should not be installed.  By default, every
+udev rule and hardware file specified by any package referenced in the
+other fields are installed.
+
+@item @code{polkit-ignorelist} (default: @code{()}) (type: list-of-strings)
+A list of regular expressions denoting polkit rules provided by any
+package that should not be installed.  By default, every polkit rule
+added by any package referenced in the other fields are installed.
+
 @end table
 @end deftp
 

base-commit: bfc614397b5f146056bda4b5a8e3a67bd1ca7b23
-- 
2.41.0

[bug#70228] [PATCH] doc: Update gnome-desktop-configuration.

[Maxim Cournoyer]

Hi Liliana,

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

> * doc/guix.texi (gnome-desktop-configuration): Fill in missing fields.
> [gnome]: Talk about the deprecation.
> ---
> Hi Guix,
>
> this patch updates the gnome-desktop-configuration documentation,
> that really ought to have been updated sooner.  It does not quite match
> the auto-generated documentation, because I took some stylistic choices
> and went further in some places.

The long term plan (TM) is to have the auto-generated documentation
truly auto-generated at build time.  You should think of any extra edits
manually made as possibly lost in the future, so it'd be best to either

1. edit the real source (docstrings)
2. fix the doc-generating macros if there's a problem worthy of
addressing

Otherwise, LGTM.

-- 
Thanks,
Maxim

[bug#70228] [PATCH] doc: Update gnome-desktop-configuration.

[Liliana Marie Prikler]

Am Samstag, dem 06.04.2024 um 11:50 -0400 schrieb Maxim Cournoyer:
> Hi Liliana,
> 
> Liliana Marie Prikler <liliana.prikler@gmail.com> writes:
> 
> > * doc/guix.texi (gnome-desktop-configuration): Fill in missing
> > fields.
> > [gnome]: Talk about the deprecation.
> > ---
> > Hi Guix,
> > 
> > this patch updates the gnome-desktop-configuration documentation,
> > that really ought to have been updated sooner.  It does not quite
> > match the auto-generated documentation, because I took some
> > stylistic choices and went further in some places.
> 
> The long term plan (TM) is to have the auto-generated documentation
> truly auto-generated at build time.  You should think of any extra
> edits manually made as possibly lost in the future, so it'd be best
> to either
> 
> 1. edit the real source (docstrings)
> 2. fix the doc-generating macros if there's a problem worthy of
> addressing
> 
> Otherwise, LGTM.
My edits concern a field that I'd like to see gone in that long-term
future, so it's fine.  Maybe I'm missing a record-level documentation
field, though, because I'm also adding a line there.

Cheers