[PATCH] doc: Update gnome-desktop-configuration.

  • Open
  • quality assurance status badge
Details
2 participants
  • Liliana Marie Prikler
  • Maxim Cournoyer
Owner
unassigned
Submitted by
Liliana Marie Prikler
Severity
normal
L
L
Liliana Marie Prikler wrote on 6 Apr 07:21 +0200
(address . guix-patches@gnu.org)
72ce110b29c2a54f369b3f95131811058fd2592b.1712380995.git.liliana.prikler@gmail.com
* 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(-)

Toggle diff (53 lines)
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
M
M
Maxim Cournoyer wrote on 6 Apr 17:50 +0200
(name . Liliana Marie Prikler)(address . liliana.prikler@gmail.com)
871q7itrqs.fsf@gmail.com
Hi Liliana,

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

Toggle quote (10 lines)
> * 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
L
L
Liliana Marie Prikler wrote on 7 Apr 08:23 +0200
(name . Maxim Cournoyer)(address . maxim.cournoyer@gmail.com)
9860b8ef787feca5deebf0f3281563b90eddd8ce.camel@gmail.com
Am Samstag, dem 06.04.2024 um 11:50 -0400 schrieb Maxim Cournoyer:
Toggle quote (25 lines)
> 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
?
Your comment

Commenting via the web interface is currently disabled.

To comment on this conversation send an email to 70228@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 70228
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch