GNU bug report logs - #61688
[PATCH 0/3] doc: hosts-service-type: Improve documentation.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 61688 in the body.
You can then email your comments to 61688 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Bruno Victal <mirai <at> makinata.eu>
To: guix-patches <at> gnu.org
Cc: Bruno Victal <mirai <at> makinata.eu>
Subject: [PATCH 0/3] doc: hosts-service-type: Improve documentation.
Date: Tue, 21 Feb 2023 21:34:01 +0000

Address some issues posted in help-guix ML.

Bruno Victal (3):
  doc: hosts-service-type: Relocate to Base Services.
  system: Do not export local-host-entries.
  doc: hosts-service-type: Improve documentation.

 doc/guix.texi  | 146 ++++++++++++++++++++++++-------------------------
 gnu/system.scm |   1 -
 2 files changed, 73 insertions(+), 74 deletions(-)


base-commit: b3844dc99bc830533aa908b7115172a883e856fa
-- 
2.39.1

Message #8 received at 61688 <at> debbugs.gnu.org (full text, mbox):

From: Bruno Victal <mirai <at> makinata.eu>
To: 61688 <at> debbugs.gnu.org
Cc: Bruno Victal <mirai <at> makinata.eu>
Subject: [PATCH 1/3] doc: hosts-service-type: Relocate to Base Services.
Date: Tue, 21 Feb 2023 21:37:07 +0000

hosts-service-type is under (gnu services base)

* doc/guix.texi: Merge duplicated copyright lines.
(Service Reference): Move hosts-service-type to ...
(Base Services): ... here.
---
 doc/guix.texi | 145 +++++++++++++++++++++++++-------------------------
 1 file changed, 72 insertions(+), 73 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 05615b9549..4143488b93 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -109,11 +109,10 @@
 Copyright @copyright{} 2022 Simon Streit@*
 Copyright @copyright{} 2022 (@*
 Copyright @copyright{} 2022 John Kehayias@*
-Copyright @copyright{} 2022 Bruno Victal@*
+Copyright @copyright{} 2022⁠–⁠2023 Bruno Victal@*
 Copyright @copyright{} 2022 Ivan Vilata-i-Balaguer@*
 Copyright @copyright{} 2023 Giacomo Leidi@*
 Copyright @copyright{} 2022 Antero Mejr@*
-Copyright @copyright{} 2023 Bruno Victal@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -18021,6 +18020,77 @@ Base Services
 @end lisp
 @end defvar
 
+@defvar hosts-service-type
+Type of the service that populates the entries for (@file{/etc/hosts}).
+This service type can be extended by passing it a list of
+@code{host} records.
+
+@c TRANSLATORS: The domain names below SHOULD NOT be translated.
+@c They're domains reserved for use in documentation. (RFC6761 Section 6.5)
+@c The addresses used are explained in RFC3849 and RFC5737.
+@lisp
+(simple-service 'add-extra-hosts
+                hosts-service-type
+                (list (host "192.0.2.1" "example.com"
+                            '("example.net" "example.org"))
+                      (host "2001:db8::1" "example.com"
+                            '("example.net" "example.org"))))
+@end lisp
+
+@quotation Note
+@cindex @file{/etc/host} default entries
+By default @file{/etc/host} comes with the following entries:
+@example
+127.0.0.1 localhost @var{host-name}
+::1       localhost @var{host-name}
+@end example
+
+For most setups this is what you want though if you find yourself in
+the situation where you want to change the default entries, you can
+do so in @code{operating-system}.@pxref{operating-system Reference,@code{essential-services}}
+
+The following example shows how one would unset @var{host-name}
+from being an alias of @code{localhost}.
+@lisp
+(operating-system
+  ;; @dots{}
+
+  (essential-services
+   (modify-services
+     (operating-system-default-essential-services this-operating-system)
+     (hosts-service-type config => (list
+                                     (host "127.0.0.1" "localhost")
+                                     (host "::1"       "localhost"))))))
+@end lisp
+@end quotation
+
+@deftp {Data Type} host
+Available @code{host} fields are:
+
+@table @asis
+@item @code{address} (type: string)
+IP address.
+
+@item @code{canonical-name} (type: string)
+Hostname.
+
+@item @code{aliases} (default: @code{'()}) (type: list-of-string)
+Additional aliases that map to the same @code{canonical-name}.
+
+@end table
+@end deftp
+
+@defun host address canonical-name [aliases]
+Procedure for creating @code{host} records.
+@end defun
+
+@quotation Note
+The @code{host} data type constructor is @code{%host} though it is
+tiresome to create multiple records with it so in practice the procedure
+@code{host} (which wraps around @code{%host}) is used instead.
+@end quotation
+@end defvar
+
 @deffn {Scheme Procedure} login-service @var{config}
 Return a service to run login according to @var{config}, a
 @code{<login-configuration>} object, which specifies the message of the day,
@@ -40508,77 +40578,6 @@ Service Reference
 pointing to the given file.
 @end defvar
 
-@defvar hosts-service-type
-Type of the service that populates the entries for (@file{/etc/hosts}).
-This service type can be extended by passing it a list of
-@code{host} records.
-
-@c TRANSLATORS: The domain names below SHOULD NOT be translated.
-@c They're domains reserved for use in documentation. (RFC6761 Section 6.5)
-@c The addresses used are explained in RFC3849 and RFC5737.
-@lisp
-(simple-service 'add-extra-hosts
-                hosts-service-type
-                (list (host "192.0.2.1" "example.com"
-                            '("example.net" "example.org"))
-                      (host "2001:db8::1" "example.com"
-                            '("example.net" "example.org"))))
-@end lisp
-
-@quotation Note
-@cindex @file{/etc/host} default entries
-By default @file{/etc/host} comes with the following entries:
-@example
-127.0.0.1 localhost @var{host-name}
-::1       localhost @var{host-name}
-@end example
-
-For most setups this is what you want though if you find yourself in
-the situation where you want to change the default entries, you can
-do so in @code{operating-system}.@pxref{operating-system Reference,@code{essential-services}}
-
-The following example shows how one would unset @var{host-name}
-from being an alias of @code{localhost}.
-@lisp
-(operating-system
-  ;; @dots{}
-
-  (essential-services
-   (modify-services
-     (operating-system-default-essential-services this-operating-system)
-     (hosts-service-type config => (list
-                                     (host "127.0.0.1" "localhost")
-                                     (host "::1"       "localhost"))))))
-@end lisp
-@end quotation
-
-@deftp {Data Type} host
-Available @code{host} fields are:
-
-@table @asis
-@item @code{address} (type: string)
-IP address.
-
-@item @code{canonical-name} (type: string)
-Hostname.
-
-@item @code{aliases} (default: @code{'()}) (type: list-of-string)
-Additional aliases that map to the same @code{canonical-name}.
-
-@end table
-@end deftp
-
-@defun host address canonical-name [aliases]
-Procedure for creating @code{host} records.
-@end defun
-
-@quotation Note
-The @code{host} data type constructor is @code{%host} though it is
-tiresome to create multiple records with it so in practice the procedure
-@code{host} (which wraps around @code{%host}) is used instead.
-@end quotation
-@end defvar
-
 @defvar setuid-program-service-type
 Type for the ``setuid-program service''.  This service collects lists of
 executable file names, passed as gexps, and adds them to the set of
-- 
2.39.1

Message #11 received at 61688 <at> debbugs.gnu.org (full text, mbox):

From: Bruno Victal <mirai <at> makinata.eu>
To: 61688 <at> debbugs.gnu.org
Cc: Bruno Victal <mirai <at> makinata.eu>
Subject: [PATCH 3/3] doc: hosts-service-type: Improve documentation.
Date: Tue, 21 Feb 2023 21:37:09 +0000

* doc/guix.texi (Base Services): Improve hosts-service-type documentation.
---
 doc/guix.texi | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 4143488b93..85768a4b60 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -18022,7 +18022,7 @@ Base Services
 
 @defvar hosts-service-type
 Type of the service that populates the entries for (@file{/etc/hosts}).
-This service type can be extended by passing it a list of
+This service type can be @emph{extended} by passing it a list of
 @code{host} records.
 
 @c TRANSLATORS: The domain names below SHOULD NOT be translated.
@@ -18047,10 +18047,11 @@ Base Services
 
 For most setups this is what you want though if you find yourself in
 the situation where you want to change the default entries, you can
-do so in @code{operating-system}.@pxref{operating-system Reference,@code{essential-services}}
+do so in @code{operating-system} via @code{modify-services}
+(@pxref{Service Reference,@code{modify-services}}).
 
-The following example shows how one would unset @var{host-name}
-from being an alias of @code{localhost}.
+The following example shows how to unset @var{host-name} from being an
+alias of @code{localhost}.
 @lisp
 (operating-system
   ;; @dots{}
@@ -18085,9 +18086,9 @@ Base Services
 @end defun
 
 @quotation Note
-The @code{host} data type constructor is @code{%host} though it is
-tiresome to create multiple records with it so in practice the procedure
-@code{host} (which wraps around @code{%host}) is used instead.
+The constructor for the @code{host} record-type is @code{%host} though
+the procedure @code{host} results in more concise definitions when there are
+multiple @code{host} records.
 @end quotation
 @end defvar
 
-- 
2.39.1

Message #14 received at 61688 <at> debbugs.gnu.org (full text, mbox):

From: Bruno Victal <mirai <at> makinata.eu>
To: 61688 <at> debbugs.gnu.org
Cc: Bruno Victal <mirai <at> makinata.eu>
Subject: [PATCH 2/3] system: Do not export local-host-entries.
Date: Tue, 21 Feb 2023 21:37:08 +0000

Unlike the deprecated 'local-host-aliases', there's no use for
local-host-entries since it's used to set the default value for
hosts-service-type. Given that this service-type is expected to be
extended, one presumes that when they explicitly override the service
default value they do not have much interest in the 'local-host-entries'
procedure.

* gnu/system.scm: Do not export local-host-entries.
---
 gnu/system.scm | 1 -
 1 file changed, 1 deletion(-)

diff --git a/gnu/system.scm b/gnu/system.scm
index df60fda53b..53f3c62bb0 100644
--- a/gnu/system.scm
+++ b/gnu/system.scm
@@ -171,7 +171,6 @@ (define-module (gnu system)
             boot-parameters->menu-entry
 
             local-host-aliases                    ;deprecated
-            local-host-entries
             %root-account
             %setuid-programs
             %sudoers-specification
-- 
2.39.1

Message #19 received at 61688-done <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: Bruno Victal <mirai <at> makinata.eu>
Cc: 61688-done <at> debbugs.gnu.org
Subject: Re: bug#61688: [PATCH 0/3] doc: hosts-service-type: Improve
 documentation.
Date: Thu, 23 Feb 2023 16:19:26 +0100

Hi,

Bruno Victal <mirai <at> makinata.eu> skribis:

> Address some issues posted in help-guix ML.
>
> Bruno Victal (3):
>   doc: hosts-service-type: Relocate to Base Services.
>   system: Do not export local-host-entries.
>   doc: hosts-service-type: Improve documentation.

Applied!  I followed up with a couple of commits in the same spirit, as
discussed on IRC.

Thanks,
Ludo’.

Previous Next

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