unofficial mirror of guix-patches@gnu.org 
 help / color / mirror / Atom feed
* [bug#48934] [PATCH 0/2] Some improvements to (gnu services configuration)
@ 2021-06-09 13:04 Xinglu Chen
  2021-06-09 13:06 ` [bug#48934] [PATCH 1/2] services: configuration: Change formatting of generated Xinglu Chen
  2021-06-09 13:06 ` [bug#48934] [PATCH 2/2] services: configuration: Show default value when it is a Xinglu Chen
  0 siblings, 2 replies; 3+ messages in thread
From: Xinglu Chen @ 2021-06-09 13:04 UTC (permalink / raw)
  To: 48934; +Cc: Maxim Cournoyer

[-- Attachment #1: Type: text/plain, Size: 2803 bytes --]

This series contains some improvements to the (gnu services
configuration) module.

The first patch changes the formatting of the generated documentation
for configuration records.  Previously, the generated documentation
looked a bit different from the ones that were to generated, compare the
docs for ‘getmail-configuration’ (generated) and ‘openssh-configuration’
(not generated).

--8<---------------cut here---------------start------------->8---
   Available ‘getmail-configuration’ fields are:

 -- ‘getmail-configuration’ parameter: symbol name
     A symbol to identify the getmail service.

     Defaults to ‘"unset"’.

 -- ‘getmail-configuration’ parameter: package package
     The getmail package to use.
--8<---------------cut here---------------end--------------->8---

--8<---------------cut here---------------start------------->8---
 -- Data Type: openssh-configuration
     This is the configuration record for OpenSSH’s ‘sshd’.

     ‘openssh’ (default OPENSSH)
          The Openssh package to use.

     ‘pid-file’ (default: ‘"/var/run/sshd.pid"’)
          Name of the file where ‘sshd’ writes its PID.

     ‘port-number’ (default: ‘22’)
          TCP port on which ‘sshd’ listens for incoming connections.
--8<---------------cut here---------------end--------------->8---

The first patch will make the generated documentation look at lot more
similiar to the hand-written ones.

--8<---------------cut here---------------start------------->8---
 -- Data Type: getmail-configuration
     Available ‘getmail-configuration’ fields are:

     ‘name’ (default: ‘"unset"’) (type: symbol)
          A symbol to identify the getmail service.

     ‘package’ (default: ‘getmail’) (type: package)
          The getmail package to use.
--8<---------------cut here---------------end--------------->8---

If you paid close attention you will also notice that the old generated
docs didn’t specify the default value of the ‘package’ field, whereas
the new docs do.  This brings us to the second patch, it looks the
package and shows the value of the ‘name’ field of the package.  This
will only show the correct package name if the ‘name’ field and the
Scheme variable corresponding to the package are the same, in most cases
it is, so I don’t think it would be a huge deal.

Xinglu Chen (2):
  services: configuration: Change formatting of generated documentation.
  services: configuration: Show default value when it is a package.

 gnu/services/configuration.scm | 62 ++++++++++++++++++++--------------
 1 file changed, 36 insertions(+), 26 deletions(-)


base-commit: 86bb77608d375043f837583332a7c852ea2080ec
-- 
2.32.0



[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 861 bytes --]

^ permalink raw reply	[flat|nested] 3+ messages in thread

* [bug#48934] [PATCH 1/2] services: configuration: Change formatting of generated
  2021-06-09 13:04 [bug#48934] [PATCH 0/2] Some improvements to (gnu services configuration) Xinglu Chen
@ 2021-06-09 13:06 ` Xinglu Chen
  2021-06-09 13:06 ` [bug#48934] [PATCH 2/2] services: configuration: Show default value when it is a Xinglu Chen
  1 sibling, 0 replies; 3+ messages in thread
From: Xinglu Chen @ 2021-06-09 13:06 UTC (permalink / raw)
  To: 48934

* 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.
---
 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)
-- 
2.32.0






^ permalink raw reply	[flat|nested] 3+ messages in thread

* [bug#48934] [PATCH 2/2] services: configuration: Show default value when it is a
  2021-06-09 13:04 [bug#48934] [PATCH 0/2] Some improvements to (gnu services configuration) Xinglu Chen
  2021-06-09 13:06 ` [bug#48934] [PATCH 1/2] services: configuration: Change formatting of generated Xinglu Chen
@ 2021-06-09 13:06 ` Xinglu Chen
  1 sibling, 0 replies; 3+ messages in thread
From: Xinglu Chen @ 2021-06-09 13:06 UTC (permalink / raw)
  To: 48934

* gnu/services/configuration.scm (generate-documentation): If the default
  value of a field is a package, show the value of the ‘name’ field of the
  package.  This might not be the correct name in some cases though.
---
 gnu/services/configuration.scm | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm
index abcbc70520..99687d065a 100644
--- a/gnu/services/configuration.scm
+++ b/gnu/services/configuration.scm
@@ -252,12 +252,20 @@ does not have a default value" field kind)))
                                         (configuration-field-default-value-thunk f)
                                         (lambda _ '%invalid))))
                          (define (show-default? val)
-                           (or (string? val) (number? val) (boolean? val)
+                           (or (string? val) (number? val) (boolean? val) (package? val)
                                (and (symbol? val) (not (eq? val '%invalid)))
                                (and (list? val) (and-map show-default? val))))
+
+                         (define (show-default val)
+                           (cond
+                            ((package? val)
+                             ;; Maybe not always correct.
+                             (package-name val))
+                            (else (str val))))
+
                          `(entry (% (heading (code ,(str field-name))
                                              ,@(if (show-default? default)
-                                                   `(" (default: " (code ,(str default)) ")")
+                                                   `(" (default: " (code ,(show-default default)) ")")
                                                    '())
                                              " (type: "
                                              ,(str field-type)
-- 
2.32.0






^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2021-06-09 13:07 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-06-09 13:04 [bug#48934] [PATCH 0/2] Some improvements to (gnu services configuration) Xinglu Chen
2021-06-09 13:06 ` [bug#48934] [PATCH 1/2] services: configuration: Change formatting of generated Xinglu Chen
2021-06-09 13:06 ` [bug#48934] [PATCH 2/2] services: configuration: Show default value when it is a Xinglu Chen

unofficial mirror of guix-patches@gnu.org 

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://yhetil.org/guix-patches/1 guix-patches/git/1.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 guix-patches guix-patches/ https://yhetil.org/guix-patches \
		guix-patches@gnu.org
	public-inbox-index guix-patches

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://news.yhetil.org/yhetil.gnu.guix.patches


AGPL code for this site: git clone http://ou63pmih66umazou.onion/public-inbox.git