diff mbox series

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

Message ID 72ce110b29c2a54f369b3f95131811058fd2592b.1712380995.git.liliana.prikler@gmail.com
State New
Headers show
Series [bug#70228] doc: Update gnome-desktop-configuration. | expand

Commit Message

Liliana Marie Prikler April 6, 2024, 5:21 a.m. UTC 
* 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(-)


base-commit: bfc614397b5f146056bda4b5a8e3a67bd1ca7b23

Comments

Maxim Cournoyer April 6, 2024, 3:50 p.m. UTC | #1 
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.
Liliana Marie Prikler April 7, 2024, 6:23 a.m. UTC | #2 
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
diff mbox series

Patch

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