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

Previous Next

Full log

View this message in rfc822 format

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: Xinglu Chen <public <at> yoctocell.xyz>
Cc: 48934 <at> debbugs.gnu.org
Subject: [bug#48934] [PATCH 0/2] Some improvements to (gnu services configuration)
Date: Mon, 02 Aug 2021 14:10:01 -0400

Hello Xinglu!

Xinglu Chen <public <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.