bug#34955: Manual: Service extensions not clear

bug#34955: Manual: Service extensions not clear

[pelzflorian (Florian Pelz)]

The Guix manual (section Defining services) says about service
extensions:

[The example guix-service-type definition] defines three things:

  1. […]

  2. A list of “service extensions”, where each extension designates the
     target service type and a procedure that, given the parameters of
     the service, returns a list of objects to extend the service of
     that type.

     Every service type has at least one service extension.  The only
     exception is the “boot service type”, which is the ultimate
     service.

This is confusing to me because previously it was explained that
services extend services but now it says types extend types which does
not fit the previous explanation.

Later it says:

   There can be only one instance of an extensible service type such as
UDEV-SERVICE-TYPE.  If there were more, the ‘service-extension’
specifications would be ambiguous.

I believe before the example for the definition of service types,
service extensions should be explained.

E.g.

A service type definition specifies which services can be extended by
an instance of the service type.  For each service extension, exactly
one service of the target service type of the extension must appear
in the services field of the operating-system declaration.

Regards,
Florian