[bug#48934] [PATCH 0/2] Some improvements to (gnu services configuration)

[Maxim Cournoyer <maxim.cournoyer@gmail.com>]

Hello Xinglu!

Xinglu Chen <public@yoctocell.xyz> writes:

> * gnu/services/configuration (generate-documentation): Make the formatting of
>   the generated docs more consistent with the rest of the docs in the “Services”
>   section of the manual.

I've modified the commit message to be more in line with the GNU change
log style (see 'info (standards) Style of Change Logs'), like so:

  services: configuration: Uniformize the generated documentation.

  Make the formatting of the generated docs more consistent with the rest of the
  docs in the “Services” section of the manual.

  * gnu/services/configuration (generate-documentation): Represent the data type
  documentation of a field using a DEFTP table rather than DEFTYPEVR elements.

> ---
>  gnu/services/configuration.scm | 54 ++++++++++++++++++----------------
>  1 file changed, 28 insertions(+), 26 deletions(-)
>
> diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm
> index f23840ee6d..abcbc70520 100644
> --- a/gnu/services/configuration.scm
> +++ b/gnu/services/configuration.scm
> @@ -239,32 +239,34 @@ does not have a default value" field kind)))
>    (define (generate configuration-name)
>      (match (assq-ref documentation configuration-name)
>        ((fields . sub-documentation)
> -       `((para "Available " (code ,(str configuration-name)) " fields are:")
> -         ,@(map
> -            (lambda (f)
> -              (let ((field-name (configuration-field-name f))
> -                    (field-type (configuration-field-type f))
> -                    (field-docs (cdr (texi-fragment->stexi
> -                                      (configuration-field-documentation f))))
> -                    (default (catch #t
> -                               (configuration-field-default-value-thunk f)
> -                               (lambda _ '%invalid))))
> -                (define (show-default? val)
> -                  (or (string? val) (number? val) (boolean? val)
> -                      (and (symbol? val) (not (eq? val '%invalid)))
> -                      (and (list? val) (and-map show-default? val))))
> -                `(deftypevr (% (category
> -                                (code ,(str configuration-name)) " parameter")
> -                               (data-type ,(str field-type))
> -                               (name ,(str field-name)))
> -                   ,@field-docs
> -                   ,@(if (show-default? default)
> -                         `((para "Defaults to " (samp ,(str default)) "."))
> -                         '())
> -                   ,@(append-map
> -                      generate
> -                      (or (assq-ref sub-documentation field-name) '())))))
> -            fields)))))
> +       `((deftp (% (category "Data Type") (name ,(str configuration-name)))
> +           (para "Available " (code ,(str configuration-name)) " fields are:")
> +           (table (% (formatter (asis)))
> +                  ,@(map
> +                     (lambda (f)
> +                       (let ((field-name (configuration-field-name f))
> +                             (field-type (configuration-field-type f))
> +                             (field-docs (cdr (texi-fragment->stexi
> +                                               (configuration-field-documentation f))))
> +                             (default (catch #t
> +                                        (configuration-field-default-value-thunk f)
> +                                        (lambda _ '%invalid))))
> +                         (define (show-default? val)
> +                           (or (string? val) (number? val) (boolean? val)
> +                               (and (symbol? val) (not (eq? val '%invalid)))
> +                               (and (list? val) (and-map show-default? val))))
> +                         `(entry (% (heading (code ,(str field-name))
> +                                             ,@(if (show-default? default)
> +                                                   `(" (default: " (code ,(str default)) ")")
> +                                                   '())
> +                                             " (type: "
> +                                             ,(str field-type)
> +                                             ")"))
> +                                 (para ,@field-docs)
> +                                 ,@(append-map
> +                                    generate
> +                                    (or (assq-ref sub-documentation field-name) '())))))
> +                     fields)))))))
>    (stexi->texi `(*fragment* . ,(generate documentation-name))))
>  
>  (define (configuration->documentation configuration-symbol)

I've used this opportunity to re-indent the code a bit, so that it'd fit
under 80 characters column width.

Thanks for this neat improvement!

Maxim