[RFC] Cosmetic changes to define-configuration usage

[Bruno Victal <mirai@makinata.eu>]

Forwarded from: <https://logs.guix.gnu.org/guix/2023-03-22.log#165538> & [1]

--8<---------------cut here---------------start------------->8---
<mirai>apteryx: IMO the spacing between the fields should have been kept
<mirai>it makes things easier to read
<mirai>it's a nightmare if the records grow very large
<apteryx>mirai: I was on the fence about it, but keeping the fields together in the same record appears to be the more conventional style in the code base
<apteryx>(together as in without blank lines in-between)
<mirai>apteryx: I'm planning to gradually shift the define-configurations to have a space between fields
<apteryx>mirai: it should be discussed first to guix-devel :-)
--8<---------------cut here---------------end--------------->8---


I'd like to propose for field specifications in define-configuration to be separated with a
blank line between them. Reason for this is that it makes it much easier on the eyes
to read, rather than being presented with a dense hunk of text to sift through.

I tend to always insert these blank lines when making changes in these parts to aid reading,
even if they weren't originally present and were not planned to be committed. I'd be happy if
I could simply keep the line separations and avoid the tedious insert-erase ritual.

I think I'm not alone in this opinion, consider the following snippets:


With a line separating each field:   (gnu/services/mcron.scm)
--8<---------------cut here---------------start------------->8---
(define-configuration/no-serialization mcron-configuration
  (mcron
   (file-like mcron)
   "The mcron package to use.")

  (jobs
   (list-of-gexps '())
   "This is a list of gexps (@pxref{G-Expressions}), where each gexp
corresponds to an mcron job specification (@pxref{Syntax, mcron job
specifications,, mcron, GNU@tie{}mcron}).")

  (log?
   (boolean #t)
   "Log messages to standard output.")

  (log-file
   (string "/var/log/mcron.log")
   "Log file location.")

  (log-format
   (string "~1@*~a ~a: ~a~%")
   "@code{(ice-9 format)} format string for log messages.  The default value
produces messages like @samp{@var{pid} @var{name}: @var{message}}
(@pxref{Invoking mcron, Invoking,, mcron, GNU@tie{}mcron}).
Each message is also prefixed by a timestamp by GNU Shepherd.")

  (date-format
   maybe-string
   "@code{(srfi srfi-19)} format string for date."))
--8<---------------cut here---------------end--------------->8---


Lines collapsed:   (gnu/services/linux.scm)
--8<---------------cut here---------------start------------->8---
(define-configuration fstrim-configuration
  (package
    (file-like util-linux)
    "The package providing the @command{fstrim} command."
    empty-serializer)
  (schedule
   (mcron-time "0 0 * * 0")
   "Schedule for launching @command{fstrim}.  This can be a procedure, a list
or a string.  For additional information, see @ref{Guile Syntax,,
Job specification, mcron, the mcron manual}.  By default this is set to run
weekly on Sunday at 00:00."
   empty-serializer)
  ;; The following are fstrim-related options.
  (listed-in
   (maybe-list-of-strings '("/etc/fstab" "/proc/self/mountinfo"))
   ;; Note: documentation sourced from the fstrim manpage.
   "List of files in fstab or kernel mountinfo format.  All missing or
empty files are silently ignored.  The evaluation of the list @emph{stops}
after the first non-empty file.  File systems with @code{X-fstrim.notrim} mount
option in fstab are skipped.")
  (verbose?
   (boolean #t)
   "Verbose execution.")
  (quiet-unsupported?
   (boolean #t)
   "Suppress error messages if trim operation (ioctl) is unsupported.")
  (extra-arguments
   maybe-list-of-strings
   "Extra options to append to @command{fstrim} (run @samp{man fstrim} for
more information)."
   (lambda (_ value)
     (if (maybe-value-set? value)
         value '())))
--8<---------------cut here---------------end--------------->8---


IMO, the top snippet looks much less overwhelming than the bottom one.


## “Implementation” plan

This cosmetic change can be done gradually or with a commit that performs the restyling in bulk.


[1]: <https://issues.guix.gnu.org/61964>


Cheers,
Bruno